@temporalio/strands-agents 1.23.0 → 2.0.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/LICENSE +6 -6
  2. package/README.md +112 -15
  3. package/lib/empty-module.d.ts +1 -1
  4. package/lib/empty-module.js +6 -1
  5. package/lib/empty-module.js.map +1 -1
  6. package/lib/index.d.ts +2 -2
  7. package/lib/index.js +21 -11
  8. package/lib/index.js.map +1 -1
  9. package/lib/load-polyfills.js +15 -0
  10. package/lib/load-polyfills.js.map +1 -1
  11. package/lib/model-activity.d.ts +57 -2
  12. package/lib/model-activity.js +100 -6
  13. package/lib/model-activity.js.map +1 -1
  14. package/lib/plugin.d.ts +33 -12
  15. package/lib/plugin.js +127 -26
  16. package/lib/plugin.js.map +1 -1
  17. package/lib/strands-errors.d.ts +39 -0
  18. package/lib/strands-errors.js +130 -0
  19. package/lib/strands-errors.js.map +1 -0
  20. package/lib/temporal-activity-tool.d.ts +18 -10
  21. package/lib/temporal-activity-tool.js +50 -29
  22. package/lib/temporal-activity-tool.js.map +1 -1
  23. package/lib/temporal-agent.d.ts +38 -4
  24. package/lib/temporal-agent.js +68 -16
  25. package/lib/temporal-agent.js.map +1 -1
  26. package/lib/temporal-mcp-client.d.ts +113 -17
  27. package/lib/temporal-mcp-client.js +376 -102
  28. package/lib/temporal-mcp-client.js.map +1 -1
  29. package/lib/temporal-mcp-tool.d.ts +3 -1
  30. package/lib/temporal-mcp-tool.js +26 -16
  31. package/lib/temporal-mcp-tool.js.map +1 -1
  32. package/lib/temporal-model.d.ts +32 -0
  33. package/lib/temporal-model.js +108 -24
  34. package/lib/temporal-model.js.map +1 -1
  35. package/lib/workflow.js +17 -7
  36. package/lib/workflow.js.map +1 -1
  37. package/package.json +46 -22
  38. package/src/empty-module.ts +5 -0
  39. package/src/index.ts +3 -1
  40. package/src/load-polyfills.ts +20 -1
  41. package/src/model-activity.ts +153 -8
  42. package/src/plugin.ts +159 -31
  43. package/src/strands-errors.ts +147 -0
  44. package/src/temporal-activity-tool.ts +43 -32
  45. package/src/temporal-agent.ts +77 -19
  46. package/src/temporal-mcp-client.ts +407 -91
  47. package/src/temporal-mcp-tool.ts +9 -9
  48. package/src/temporal-model.ts +111 -18
  49. package/lib/failure-converter.d.ts +0 -14
  50. package/lib/failure-converter.js +0 -61
  51. package/lib/failure-converter.js.map +0 -1
  52. package/src/failure-converter.ts +0 -77
@@ -13,17 +13,17 @@ import type { z } from 'zod';
13
13
  import * as workflow from '@temporalio/workflow';
14
14
  import type { ActivityOptions } from '@temporalio/workflow';
15
15
  import { ActivityFailure, ApplicationFailure } from '@temporalio/common';
16
- import { STRANDS_INTERRUPT_TYPE } from './failure-converter';
16
+ import { type InterruptDetails, STRANDS_INTERRUPT_TYPE } from './strands-errors';
17
17
  import { toJsonSchema } from './json-schema';
18
18
 
19
19
  /**
20
20
  * Options accepted by {@link activityAsTool}.
21
21
  *
22
- * `name` defaults to the activity function's `.name`. `description` defaults
23
- * to an empty string and SHOULD be supplied so the model has signal about
24
- * when to call the tool. `inputSchema` describes the activity's single
25
- * argument; pass either a literal JSON Schema object or a Zod schema, which
26
- * is converted to JSON Schema for you.
22
+ * `name` defaults to the registered activity name. `description` is omitted
23
+ * when not supplied; supply one to help the model decide when to call the
24
+ * tool. `inputSchema` describes the activity's single argument; pass either a
25
+ * literal JSON Schema object or a Zod schema, which is converted to JSON
26
+ * Schema for you.
27
27
  */
28
28
  export interface ActivityAsToolOptions {
29
29
  name?: string;
@@ -37,14 +37,17 @@ export interface ActivityAsToolOptions {
37
37
  * {@link workflow.executeActivity}.
38
38
  *
39
39
  * When the activity fails with an {@link ApplicationFailure} whose `type`
40
- * matches {@link STRANDS_INTERRUPT_TYPE} — see {@link StrandsFailureConverter} —
41
- * `stream()` re-throws an {@link InterruptError} so the agent loop handles
42
- * the interrupt the same way as a hook- or tool-body interrupt. Other
43
- * failures are converted to an error {@link ToolResultBlock}.
40
+ * matches {@link STRANDS_INTERRUPT_TYPE} — {@link StrandsPlugin} turns an
41
+ * interrupt the activity throws into one —
42
+ * `stream()` raises each interrupt in its details, in order, so the agent loop
43
+ * handles them the same way as hook- or tool-body interrupts: the agent pauses
44
+ * at the first one without a response. Other failures, including a malformed
45
+ * interrupt, are converted to an error {@link ToolResultBlock}.
44
46
  */
45
47
  export class TemporalActivityTool extends Tool {
46
48
  readonly name: string;
47
- readonly description: string;
49
+ // Strands accepts an omitted description at runtime, though Tool and ToolSpec require it in their types.
50
+ declare readonly description: string;
48
51
  readonly toolSpec: ToolSpec;
49
52
  private readonly activityName: string;
50
53
  private readonly activityOptions: ActivityOptions;
@@ -61,12 +64,14 @@ export class TemporalActivityTool extends Tool {
61
64
  super();
62
65
  this.activityName = activityName;
63
66
  this.name = options.name ?? activityName;
64
- this.description = options.description ?? '';
65
67
  this.toolSpec = {
66
68
  name: this.name,
67
- description: this.description,
68
69
  inputSchema: toJsonSchema(options.inputSchema) ?? { type: 'object', properties: {} },
69
- };
70
+ } as ToolSpec;
71
+ if (options.description !== undefined) {
72
+ this.description = options.description;
73
+ this.toolSpec.description = this.description;
74
+ }
70
75
  this.activityOptions = options.activityOptions ?? {};
71
76
  }
72
77
 
@@ -89,29 +94,19 @@ export class TemporalActivityTool extends Tool {
89
94
  err.cause instanceof ApplicationFailure &&
90
95
  err.cause.type === STRANDS_INTERRUPT_TYPE
91
96
  ) {
92
- const details = (err.cause.details ?? []) as Array<{
93
- name: string;
94
- reason?: unknown;
95
- response?: unknown;
96
- }>;
97
- const first = details[0];
98
- // Route through the agent's interrupt() helper: throws InterruptError to
99
- // halt on first call, returns the user's response on resume.
100
- const response = toolContext.interrupt<unknown>({
101
- name: first?.name ?? 'interrupt',
102
- reason: first?.reason as JSONValue,
103
- });
97
+ const details = (err.cause.details ?? []) as InterruptDetails[];
98
+ // Route each interrupt through the agent's interrupt() helper, in order: the first one with
99
+ // no response throws InterruptError and halts; on resume the answered ones return theirs.
100
+ const responses = (details.length > 0 ? details : [{ name: 'interrupt' }]).map((d: Partial<InterruptDetails>) =>
101
+ toolContext.interrupt<unknown>({ name: d.name ?? 'interrupt', reason: d.reason as JSONValue })
102
+ );
104
103
  return new ToolResultBlock({
105
104
  toolUseId,
106
105
  status: 'success',
107
- content: [toResultContent(response)],
106
+ content: [toResultContent(responses.length === 1 ? responses[0] : responses)],
108
107
  });
109
108
  }
110
- return new ToolResultBlock({
111
- toolUseId,
112
- status: 'error',
113
- content: [new TextBlock(String(err instanceof Error ? err.message : err))],
114
- });
109
+ return activityErrorResult(toolUseId, err);
115
110
  }
116
111
  return new ToolResultBlock({
117
112
  toolUseId,
@@ -121,6 +116,22 @@ export class TemporalActivityTool extends Tool {
121
116
  }
122
117
  }
123
118
 
119
+ /**
120
+ * The error result for a tool call whose activity failed. An `ActivityFailure`'s own message is
121
+ * the generic "Activity task failed", so the result carries its cause instead: what the activity
122
+ * threw, or the timeout or cancellation that ended it. The error is attached for hooks.
123
+ */
124
+ export function activityErrorResult(toolUseId: string, err: unknown): ToolResultBlock {
125
+ const cause = err instanceof ActivityFailure && err.cause ? err.cause : err;
126
+ const error = cause instanceof Error ? cause : new Error(String(cause));
127
+ return new ToolResultBlock({
128
+ toolUseId,
129
+ status: 'error',
130
+ content: [new TextBlock(error.message)],
131
+ error,
132
+ });
133
+ }
134
+
124
135
  function toResultContent(value: unknown): TextBlock | JsonBlock {
125
136
  if (typeof value === 'string') return new TextBlock(value);
126
137
  return new JsonBlock({ json: value as JSONValue });
@@ -1,19 +1,19 @@
1
1
  import { Agent, AfterToolsEvent } from '@strands-agents/sdk';
2
- import type { AgentConfig } from '@strands-agents/sdk';
2
+ import type { AgentConfig, AgentResult, AgentStreamEvent, InvokeArgs, InvokeOptions } from '@strands-agents/sdk';
3
3
  import type { ActivityOptions } from '@temporalio/workflow';
4
4
  import type { Duration } from '@temporalio/common/lib/time';
5
5
  import { TemporalModel } from './temporal-model';
6
6
  import { TemporalMCPClient } from './temporal-mcp-client';
7
+ import { workflowErrorFor } from './strands-errors';
7
8
 
8
- const SNAPSHOT_DISABLED =
9
- 'TemporalAgent disables takeSnapshot()/loadSnapshot(). Temporal workflows ' +
10
- 'already persist agent state durably via the event history at a finer ' +
11
- 'granularity than Strands snapshots. Remove the snapshot call and rely on ' +
12
- "Temporal's durable execution instead.";
9
+ // Strands' own message, which its Agent throws at construction for a stateful model.
10
+ const STATEFUL_MANAGER_REFUSED =
11
+ 'contextManager and conversationManager cannot be used with a stateful model. ' +
12
+ 'The model manages conversation state server-side.';
13
13
 
14
14
  const RETRY_STRATEGY_DISABLED =
15
- 'TemporalAgent disables Strands retries; configure retries via retryPolicy ' +
16
- 'in the model activity options on TemporalAgent, and on the activity options ' +
15
+ 'TemporalAgent disables Strands retries; configure retries via activityOptions.retry ' +
16
+ 'on TemporalAgent, and on the activity options ' +
17
17
  'passed to workflow.activityAsTool, workflow.activityAsHook, or TemporalMCPClient. ' +
18
18
  'Remove retryStrategy from TemporalAgent(...) or pass retryStrategy: null.';
19
19
 
@@ -22,7 +22,7 @@ const RETRY_STRATEGY_DISABLED =
22
22
  *
23
23
  * Accepts everything {@link AgentConfig} accepts except `model` (which is a
24
24
  * factory name selecting a worker-side {@link Model}, not an instance) and
25
- * `retryStrategy` (always disabled — Temporal handles retries via
25
+ * `retryStrategy` (only `null` is accepted — Temporal handles retries via
26
26
  * `activityOptions.retry`).
27
27
  *
28
28
  * The {@link ActivityOptions} apply to every model invocation this agent
@@ -31,6 +31,8 @@ const RETRY_STRATEGY_DISABLED =
31
31
  */
32
32
  export interface TemporalAgentOptions extends Omit<AgentConfig, 'model' | 'retryStrategy'> {
33
33
  model?: string;
34
+ /** Disable Strands retries explicitly; Temporal manages retries via `activityOptions.retry`. */
35
+ retryStrategy?: null;
34
36
  activityOptions?: ActivityOptions;
35
37
  streamingTopic?: string;
36
38
  streamingBatchInterval?: Duration;
@@ -49,11 +51,25 @@ export interface TemporalAgentOptions extends Omit<AgentConfig, 'model' | 'retry
49
51
  * Strands' `retryStrategy` is disabled; configure retries via
50
52
  * `activityOptions.retry` here and on the activity options accepted by
51
53
  * {@link activityAsTool}, {@link activityAsHook}, and {@link TemporalMCPClient}.
54
+ *
55
+ * `activityOptions.heartbeatTimeout` defaults to 10 seconds, and the model
56
+ * activities heartbeat at half of it; `heartbeatTimeout: 0` turns them off.
57
+ * Cancelling a model activity aborts the model call only when the activity
58
+ * heartbeats, since the worker learns of the cancellation through its
59
+ * heartbeats, and only when the model passes `cancelSignal` to its client
60
+ * (Strands' `AnthropicModel` does not). A model that ignores it keeps running
61
+ * and its activity can still complete with the model's result. A workflow
62
+ * cancel during a model call cancels the model activity. With `TRY_CANCEL` the
63
+ * run ends as cancelled at once. With `WAIT_CANCELLATION_COMPLETED` it ends as
64
+ * cancelled only if the activity does; if the activity completes, the turn
65
+ * continues with the model's result.
52
66
  */
53
67
  export class TemporalAgent extends Agent {
68
+ private readonly managerGiven: boolean;
69
+
54
70
  constructor(options: TemporalAgentOptions = {}) {
55
- const { model, activityOptions, streamingTopic, streamingBatchInterval, ...rest } = options;
56
- if ((rest as { retryStrategy?: unknown }).retryStrategy !== undefined) {
71
+ const { model, retryStrategy, activityOptions, streamingTopic, streamingBatchInterval, ...rest } = options;
72
+ if (retryStrategy !== undefined && retryStrategy !== null) {
57
73
  throw new Error(RETRY_STRATEGY_DISABLED);
58
74
  }
59
75
  const temporalModel = new TemporalModel({
@@ -67,25 +83,67 @@ export class TemporalAgent extends Agent {
67
83
  model: temporalModel,
68
84
  retryStrategy: null,
69
85
  });
86
+ this.managerGiven = Boolean(rest.conversationManager || rest.contextManager);
70
87
 
71
88
  // Strands lists each MCP client's tools once at agent initialization and
72
89
  // reuses that list for every turn. For clients with `cacheTools: false`,
73
90
  // re-list on each turn so a mid-workflow MCP-server restart is picked up.
74
91
  // `AfterToolsEvent` fires after a tool round completes, before the next
75
92
  // model call reads the tool registry — so the refresh lands on that call.
76
- for (const client of collectMcpClients(rest.tools)) {
77
- if (!client.cacheTools) {
78
- this.addHook(AfterToolsEvent, (event) => client.refreshTools(event.agent.toolRegistry));
79
- }
93
+ // One hook per client, as each lists its server. Strands runs them last to
94
+ // first, so the first client's hook runs last: it checks the round's
95
+ // listings together and applies them, so a name can move from one server
96
+ // to another.
97
+ const mcpClients = collectMcpClients(rest.tools);
98
+ for (const hook of TemporalMCPClient.refreshHooks(mcpClients.filter((client) => !client.cacheTools))) {
99
+ this.addHook(AfterToolsEvent, hook);
80
100
  }
101
+ // A name that Strands adds a client's tool under is that client's until a
102
+ // re-listing of that client drops it.
103
+ TemporalMCPClient.holdAdded(mcpClients, this.toolRegistry);
104
+ }
105
+
106
+ /**
107
+ * Read the worker model's id, context window and stateful flag before Strands initializes the
108
+ * agent, so its traces, proactive compression and stateful handling use them from the first
109
+ * model call.
110
+ *
111
+ * Not `async`: once the config is read, this returns Strands' own `initialize()` promise, so it
112
+ * adds no microtask before Strands' hooks and model call.
113
+ */
114
+ override initialize(): Promise<void> {
115
+ const loading = this.model instanceof TemporalModel ? this.model.loadConfig() : undefined;
116
+ return loading ? loading.then(() => this.initializeWithConfig()) : this.initializeWithConfig();
81
117
  }
82
118
 
83
- override takeSnapshot(): never {
84
- throw new Error(SNAPSHOT_DISABLED);
119
+ private initializeWithConfig(): Promise<void> {
120
+ // Strands' Agent refuses these managers for a stateful model at construction, before
121
+ // TemporalAgent can read the worker model's stateful flag, so refuse them here.
122
+ if (this.model.stateful && this.managerGiven) {
123
+ return Promise.reject(new Error(STATEFUL_MANAGER_REFUSED));
124
+ }
125
+ return super.initialize();
85
126
  }
86
127
 
87
- override loadSnapshot(): never {
88
- throw new Error(SNAPSHOT_DISABLED);
128
+ /**
129
+ * Strands' stream, ending in a Temporal failure where Strands would end in an error that only
130
+ * fails the workflow task: a terminal model error becomes a typed, non-retryable failure, and a
131
+ * model activity that failed or was cancelled ends the turn with that activity's failure. So the
132
+ * run, or the update that runs the turn, fails or is cancelled. `invoke()` uses this too.
133
+ *
134
+ * Its awaits add microtasks to each agent event, and those are part of replay: when two turns run
135
+ * at once in one workflow, they can change the order in which the turns schedule activities. So
136
+ * removing this override, or wrapping the stream in another layer, can break replay of such runs.
137
+ */
138
+ override async *stream(
139
+ args: InvokeArgs,
140
+ options?: InvokeOptions
141
+ ): AsyncGenerator<AgentStreamEvent, AgentResult, undefined> {
142
+ try {
143
+ return yield* super.stream(args, options);
144
+ } catch (err) {
145
+ throw workflowErrorFor(err);
146
+ }
89
147
  }
90
148
  }
91
149