contrib: add @temporalio/strands-agents plugin

[brianstrauch]

Summary

Adds @temporalio/strands-agents, a Temporal plugin that runs Strands Agents inside Temporal Workflows. Model invocations, MCP tool calls, and activityAsTool/activityAsHook calls all dispatch through Temporal Activities for durable execution and Temporal-managed retries.

API

// Workflow side
import { TemporalAgent, TemporalMCPClient, workflow as strandsWorkflow } from '@temporalio/strands-agents';

const agent = new TemporalAgent({
  model: 'bedrock',
  tools: [
    strandsWorkflow.activityAsTool('getWeather', { description: '…', inputSchema: { … } }),
    new TemporalMCPClient({ server: 'filesystem' }),
  ],
});
const result = await agent.invoke(prompt);

// Worker side
new StrandsPlugin({
  models: { bedrock: () => new BedrockModel({ … }) },
  mcpClients: { filesystem: () => new McpClient({ … }) },
});

Mirrors temporalio[strands-agents] from sdk-python (TemporalAgent, TemporalMCPClient, activity_as_tool, activity_as_hook, auto_heartbeater).

Workflow-bundle plumbing

@strands-agents/sdk@1.3.0's index transitively pulls fs, node:*, and MCP transport modules into any workflow that imports Agent/McpClient. StrandsPlugin.configureBundler handles this by:

• Ignoring fs (statically imported from vended-plugins/skills and vended-tools/file-editor, both unreachable from workflow code).
• Replacing node:fs/promises/os/path/process/stream and @modelcontextprotocol/sdk/client/{stdio,sse}.js with an empty stub via NormalModuleReplacementPlugin (dynamic imports inside mcp-config.js's server-only code paths).
• Disabling async chunks / code-splitting so webpack's JSONP chunk loader (which uses self/document) never ships in the bundle.

load-polyfills.ts installs Headers, web-streams-polyfill, @ungap/structured-clone, and a deterministic crypto.randomUUID backed by workflow.uuid4() — @ungap/structured-clone calls crypto.randomUUID() internally and Temporal's sink path uses structuredClone for log payloads, so without the polyfill the first logger.warn from inside an agent crashes the workflow.

TemporalMCPClient.listTools() returns lightweight TemporalMCPTool wrappers (lazy-required to break the cycle) because McpTool isn't re-exported from @strands-agents/sdk's public index. If strands-agents/sdk-typescript#1108 merges, temporal-mcp-tool.ts can be deleted entirely and TemporalMCPClient.listTools() can return real McpTool instances bound to itself — picking up the built-in content mapping for images, embedded resources, and URL-elicitation errors that our wrapper currently elides.

Tests

9 ava integration tests in contrib/strands/src/__tests__/test-strands.ts:

• Model dispatch via invokeModel activity
• activityAsTool end-to-end
• TemporalMCPClient listTools + callTool through per-server activities
• In-workflow tool() (Strands FunctionTool) running inside the sandbox
• activityAsHook on AfterToolCallEvent
• structuredOutputSchema via the strands_structured_output tool
• Activity-tool interrupt round-trip through the failure converter + workflow-signal resume
• streamingTopic events consumed via WorkflowStreamClient.subscribe
• Captured-history replay (validates the deterministic crypto.randomUUID polyfill stays replay-safe)

Test plan

• pnpm build clean
• pnpm test in contrib/strands — 9/9 passing
• Reviewer-side smoke: install in a downstream project and run a real agent against Bedrock

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new contrib package, @temporalio/strands-agents, to run Strands Agents inside Temporal Workflows by routing model/tool/MCP operations through Temporal Activities (durable execution + retries), and includes workflow-bundle plumbing/polyfills to keep workflow code sandbox-safe.

Changes:

• Introduces the @temporalio/strands-agents plugin + workflow-side wrappers (TemporalAgent, TemporalMCPClient, activityAsTool, activityAsHook) and worker-side activities/failure-converter support.
• Extends workflow bundling behavior to avoid pulling non-workflow-safe modules into workflow bundles and to prevent webpack code-splitting in workflow bundles.
• Adds comprehensive AVA integration tests and documentation for the new contrib package.

Reviewed changes

Copilot reviewed 24 out of 25 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pnpm-workspace.yaml	Adds contrib/strands workspace package.
pnpm-lock.yaml	Locks new dependency graph for contrib/strands and transitive deps.
packages/worker/src/workflow/vm-shared.ts	Injects Symbol.dispose / Symbol.asyncDispose into the workflow VM context for downleveled using support.
contrib/strands/tsconfig.json	Adds TS build configuration and project references for the new contrib package.
contrib/strands/src/index.ts	Package entrypoint: loads workflow polyfills and exports plugin + workflow helpers.
contrib/strands/src/plugin.ts	Implements StrandsPlugin (activities, bundler configuration, failure converter wiring).
contrib/strands/src/workflow.ts	Exposes workflow-side helpers to wrap activities as Strands tools/hooks.
contrib/strands/src/temporal-agent.ts	Adds TemporalAgent wrapper over Strands Agent (model calls via activities, tool refresh hooks).
contrib/strands/src/temporal-model.ts	Adds TemporalModel that dispatches model streaming/invocation through activities.
contrib/strands/src/model-activity.ts	Worker-side activity implementation for model invocation + streaming publication.
contrib/strands/src/temporal-activity-tool.ts	Workflow-side Strands Tool that executes an activity and supports interrupt round-trips.
contrib/strands/src/temporal-mcp-client.ts	Workflow handle + worker-side activity builders for MCP list/call with connection caching.
contrib/strands/src/temporal-mcp-tool.ts	Workflow-side MCP tool wrapper mapping MCP results into Strands blocks.
contrib/strands/src/failure-converter.ts	Converts Strands interrupts and terminal model errors into non-retryable ApplicationFailures.
contrib/strands/src/load-polyfills.ts	Installs workflow-only polyfills needed by Strands/MCP usage in the sandbox.
contrib/strands/src/json-schema.ts	Converts Zod schemas to JSON Schema for tool input schemas.
contrib/strands/src/empty-module.ts	Stub module used by bundler replacement to satisfy named imports safely.
contrib/strands/src/heartbeat.ts	Adds activity auto-heartbeating helper for long-running model activities.
contrib/strands/src/tests/workflows/strands.ts	Workflow fixtures used by integration tests.
contrib/strands/src/tests/activities/strands.ts	Test activities used by integration tests (tools/hooks/interrupt).
contrib/strands/src/tests/test-strands.ts	AVA integration test suite for Temporal/Strands end-to-end behavior.
contrib/strands/src/tests/test-json-schema.ts	Unit tests for toJsonSchema.
contrib/strands/README.md	Adds end-user documentation for install, usage, and design details.
contrib/strands/package.json	Declares the new published package, deps, scripts, and engine constraints.
.github/CODEOWNERS	Adds ownership rule for contrib/strands.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.