@temporalio/strands-agents 1.24.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
@@ -1,6 +1,7 @@
1
1
  import { McpClient } from '@strands-agents/sdk';
2
2
  import type { JSONSchema, JSONValue } from '@strands-agents/sdk';
3
3
  import type { ActivityOptions } from '@temporalio/workflow';
4
+ import type { TemporalMCPTool } from './temporal-mcp-tool';
4
5
  /** Tool descriptor returned by the per-server `{server}-listTools` activity. */
5
6
  export interface McpToolInfo {
6
7
  name: string;
@@ -28,11 +29,33 @@ export interface CallToolInput {
28
29
  * one extra `{server}-listTools` activity per tool round.
29
30
  * - `true` — list once at the beginning of the workflow and reuse for all
30
31
  * turns. Cheaper, but the tool list is fixed for the workflow's lifetime.
32
+ *
33
+ * `prefix` and `toolFilters` work as on Strands' `McpClient`: the agent sees
34
+ * `{prefix}_{name}`, and string and `RegExp` filters match the server's tool
35
+ * name. A callback filter receives the workflow-side {@link TemporalMCPTool}
36
+ * and runs in the workflow, so it must be deterministic.
31
37
  */
32
38
  export interface TemporalMCPClientOptions {
33
39
  server: string;
34
40
  activityOptions?: ActivityOptions;
35
41
  cacheTools?: boolean;
42
+ /** Prefix for the agent's tool names, applied as `{prefix}_{name}`. */
43
+ prefix?: string;
44
+ /** Which of the server's tools the agent gets. */
45
+ toolFilters?: McpToolFilters;
46
+ }
47
+ /**
48
+ * Matches a tool, as in Strands' `McpToolMatcher`: a string matches the
49
+ * server's tool name exactly, a `RegExp` matches it from the start, and a
50
+ * callback receives the tool under the name the agent sees.
51
+ */
52
+ export type McpToolMatcher = string | RegExp | ((tool: TemporalMCPTool) => boolean);
53
+ /** Which of a server's tools the agent gets, as in Strands' `McpToolFilters`. */
54
+ export interface McpToolFilters {
55
+ /** When present, only tools that match at least one matcher. */
56
+ allowed?: McpToolMatcher[];
57
+ /** Tools that match at least one matcher are left out, even when also allowed. */
58
+ rejected?: McpToolMatcher[];
36
59
  }
37
60
  /**
38
61
  * Minimal view of Strands' `ToolRegistry` used by {@link
@@ -51,8 +74,9 @@ export interface ToolRegistryView {
51
74
  *
52
75
  * The transport factory and tool discovery live worker-side via
53
76
  * `StrandsPlugin({ mcpClients: { server: () => new McpClient(...) } })`.
54
- * This handle only carries the server name (which selects the registered
55
- * factory) and the per-call activity options.
77
+ * This handle carries the server name (which selects the registered
78
+ * factory), the tool `prefix` and `toolFilters`, and the per-call activity
79
+ * options.
56
80
  *
57
81
  * Extends {@link McpClient} so it can be passed directly in an
58
82
  * {@link AgentConfig.tools | Agent.tools} array (Strands' `flattenTools`
@@ -64,29 +88,42 @@ export interface ToolRegistryView {
64
88
  export declare class TemporalMCPClient extends McpClient {
65
89
  private readonly server;
66
90
  private readonly activityOptions;
91
+ private readonly prefix;
92
+ private readonly toolFilters;
67
93
  /** Whether the agent lists this server's tools once or re-lists each turn. */
68
94
  readonly cacheTools: boolean;
95
+ private readonly held;
96
+ private readonly listed;
69
97
  constructor(options: TemporalMCPClientOptions);
70
98
  connect(): Promise<void>;
71
99
  disconnect(): Promise<void>;
72
100
  listTools(): Promise<never[]>;
73
101
  /**
74
102
  * Re-list this server's tools and reconcile them into the agent's tool
75
- * registry, dropping tools that no longer exist and adding new ones.
76
- * {@link TemporalAgent} calls this on each agent turn when `cacheTools` is
77
- * `false` so a mid-workflow MCP-server restart is reflected in the next call.
103
+ * registry, dropping tools that no longer exist and adding new ones, so a
104
+ * mid-workflow MCP-server restart is reflected in the next call.
105
+ * {@link TemporalAgent} instead re-lists each of its `cacheTools: false`
106
+ * clients in its own hook after each tool round, and checks and applies
107
+ * their listings together, so a name can move between its servers.
108
+ *
109
+ * A listed name that another tool of the agent has, that differs from one
110
+ * only by `-` or `_`, that the listing has twice, or that Strands rejects
111
+ * throws Strands' `ToolValidationError` and leaves the registry as it was.
78
112
  */
79
113
  refreshTools(registry: ToolRegistryView): Promise<void>;
114
+ private listInRound;
115
+ private heldIn;
116
+ private static apply;
80
117
  }
81
118
  export declare function listToolsActivityName(server: string): string;
82
119
  export declare function callToolActivityName(server: string): string;
83
120
  /**
84
121
  * Builds the per-server `{server}-listTools` activity. Enumerates the server's
85
- * tools live over the shared worker-process connection on every call, so the
86
- * agent sees the server's current tools even if it is redeployed mid-workflow.
87
- * Runs whenever a workflow calls {@link TemporalMCPClient.listTools}.
122
+ * tools live over the plugin's connection on every call, so the agent sees the
123
+ * server's current tools even if it is redeployed mid-workflow. Runs whenever a
124
+ * workflow calls {@link TemporalMCPClient.listTools}.
88
125
  */
89
- export declare function buildListToolsActivity(server: string, factory: () => McpClient, idleMs?: number): (input: {
126
+ export declare function buildListToolsActivity(server: string, factory: () => McpClient, connections: McpConnections): (input: {
90
127
  server: string;
91
128
  }) => Promise<McpToolInfo[]>;
92
129
  /**
@@ -94,15 +131,74 @@ export declare function buildListToolsActivity(server: string, factory: () => Mc
94
131
  * disconnected. The window only starts once no {@link callToolActivityName |
95
132
  * callTool} or {@link listToolsActivityName | listTools} activity is using the
96
133
  * connection, so a call that runs longer than this is never cut off. Override
97
- * per worker via `StrandsPlugin({ mcpConnectionIdleTimeout })`.
134
+ * per plugin via `StrandsPlugin({ mcpConnectionIdleTimeout })`.
98
135
  */
99
136
  export declare const MCP_CONNECTION_IDLE_MS: number;
100
- export declare function _evictConnection(server: string): Promise<void>;
137
+ /** A worker-process MCP connection plus the state governing its idle eviction. */
138
+ interface ConnectionRecord {
139
+ /** Resolves to the connected client, or rejects if the handshake failed. */
140
+ client: Promise<McpClient>;
141
+ /** Number of activities currently using this connection. */
142
+ inflight: number;
143
+ /**
144
+ * Set after a failed call, or when the last Worker using the plugin stops
145
+ * while a call still uses the connection. A retired record is no longer
146
+ * handed out to new calls, and is only disconnected once `inflight` drops
147
+ * back to 0, so one call can't close the session under its siblings.
148
+ */
149
+ retired: boolean;
150
+ /** Armed only while `inflight` is 0. */
151
+ idleTimer?: NodeJS.Timeout;
152
+ }
153
+ export declare function describeValue(value: unknown): string;
154
+ /**
155
+ * The worker-process MCP connections of one {@link StrandsPlugin}, keyed by
156
+ * server name. Workers that share a plugin instance share its connections;
157
+ * another plugin instance opens its own through its own factories, even for
158
+ * the same server name. The plugin's `runContext` counts the Workers using
159
+ * them, and the last one to stop closes them. A connection that a call still
160
+ * uses is closed when that call finishes.
161
+ */
162
+ export declare class McpConnections {
163
+ private readonly idleMs;
164
+ private readonly records;
165
+ private workers;
166
+ /**
167
+ * @param idleMs how long an idle connection stays open; defaults to
168
+ * {@link MCP_CONNECTION_IDLE_MS}.
169
+ */
170
+ constructor(idleMs?: number);
171
+ /** Runs one Worker; once no Worker uses these connections, closes them. */
172
+ use(next: () => Promise<void>): Promise<void>;
173
+ /**
174
+ * Stop handing out `server`'s connection, and disconnect it now or when the
175
+ * last call still using it finishes.
176
+ */
177
+ evict(server: string): Promise<void>;
178
+ /**
179
+ * Return the cached connection for `server`, opening one lazily if needed,
180
+ * and mark a call in flight so idle eviction can't disconnect underneath it.
181
+ * Concurrent first-callers dedupe onto a single connect handshake by awaiting
182
+ * the same record. Every caller must {@link release} once its call completes.
183
+ */
184
+ acquire(server: string, factory: () => McpClient): ConnectionRecord;
185
+ /**
186
+ * Flag `record` as suspect after a failed call. It is unpublished at once so
187
+ * new calls open a fresh connection, but not disconnected until the calls
188
+ * still using it have released it (see {@link release}).
189
+ */
190
+ retire(server: string, record: ConnectionRecord): void;
191
+ /**
192
+ * Mark a call done. Once no calls remain in flight, disconnect a retired
193
+ * connection or arm idle eviction for a healthy one.
194
+ */
195
+ release(server: string, record: ConnectionRecord): void;
196
+ }
101
197
  /**
102
- * Builds the per-server `{server}-callTool` activity. Reuses a worker-process
103
- * MCP session opened lazily through the user-supplied factory — successive
104
- * calls share one connection rather than reconnecting per call. Idle
105
- * connections are disconnected after `idleMs` (defaults to
106
- * {@link MCP_CONNECTION_IDLE_MS}).
198
+ * Builds the per-server `{server}-callTool` activity. Reuses the plugin's MCP
199
+ * session, opened lazily through the user-supplied factory — successive calls
200
+ * share one connection rather than reconnecting per call. Idle connections are
201
+ * disconnected after the plugin's idle timeout.
107
202
  */
108
- export declare function buildCallToolActivity(server: string, factory: () => McpClient, idleMs?: number): (input: CallToolInput) => Promise<JSONValue>;
203
+ export declare function buildCallToolActivity(server: string, factory: () => McpClient, connections: McpConnections): (input: CallToolInput) => Promise<JSONValue>;
204
+ export {};