@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.
- package/LICENSE +6 -6
- package/README.md +112 -15
- package/lib/empty-module.d.ts +1 -1
- package/lib/empty-module.js +6 -1
- package/lib/empty-module.js.map +1 -1
- package/lib/index.d.ts +2 -2
- package/lib/index.js +21 -11
- package/lib/index.js.map +1 -1
- package/lib/load-polyfills.js +15 -0
- package/lib/load-polyfills.js.map +1 -1
- package/lib/model-activity.d.ts +57 -2
- package/lib/model-activity.js +100 -6
- package/lib/model-activity.js.map +1 -1
- package/lib/plugin.d.ts +33 -12
- package/lib/plugin.js +127 -26
- package/lib/plugin.js.map +1 -1
- package/lib/strands-errors.d.ts +39 -0
- package/lib/strands-errors.js +130 -0
- package/lib/strands-errors.js.map +1 -0
- package/lib/temporal-activity-tool.d.ts +18 -10
- package/lib/temporal-activity-tool.js +50 -29
- package/lib/temporal-activity-tool.js.map +1 -1
- package/lib/temporal-agent.d.ts +38 -4
- package/lib/temporal-agent.js +68 -16
- package/lib/temporal-agent.js.map +1 -1
- package/lib/temporal-mcp-client.d.ts +113 -17
- package/lib/temporal-mcp-client.js +376 -102
- package/lib/temporal-mcp-client.js.map +1 -1
- package/lib/temporal-mcp-tool.d.ts +3 -1
- package/lib/temporal-mcp-tool.js +26 -16
- package/lib/temporal-mcp-tool.js.map +1 -1
- package/lib/temporal-model.d.ts +32 -0
- package/lib/temporal-model.js +108 -24
- package/lib/temporal-model.js.map +1 -1
- package/lib/workflow.js +17 -7
- package/lib/workflow.js.map +1 -1
- package/package.json +46 -22
- package/src/empty-module.ts +5 -0
- package/src/index.ts +3 -1
- package/src/load-polyfills.ts +20 -1
- package/src/model-activity.ts +153 -8
- package/src/plugin.ts +159 -31
- package/src/strands-errors.ts +147 -0
- package/src/temporal-activity-tool.ts +43 -32
- package/src/temporal-agent.ts +77 -19
- package/src/temporal-mcp-client.ts +407 -91
- package/src/temporal-mcp-tool.ts +9 -9
- package/src/temporal-model.ts +111 -18
- package/lib/failure-converter.d.ts +0 -14
- package/lib/failure-converter.js +0 -61
- package/lib/failure-converter.js.map +0 -1
- 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
|
|
55
|
-
* factory) and the per-call activity
|
|
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
|
-
*
|
|
77
|
-
*
|
|
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
|
|
86
|
-
*
|
|
87
|
-
*
|
|
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,
|
|
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
|
|
134
|
+
* per plugin via `StrandsPlugin({ mcpConnectionIdleTimeout })`.
|
|
98
135
|
*/
|
|
99
136
|
export declare const MCP_CONNECTION_IDLE_MS: number;
|
|
100
|
-
|
|
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
|
|
103
|
-
*
|
|
104
|
-
*
|
|
105
|
-
*
|
|
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,
|
|
203
|
+
export declare function buildCallToolActivity(server: string, factory: () => McpClient, connections: McpConnections): (input: CallToolInput) => Promise<JSONValue>;
|
|
204
|
+
export {};
|