@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,9 +1,11 @@
|
|
|
1
|
-
import { McpClient } from '@strands-agents/sdk';
|
|
1
|
+
import { McpClient, ToolValidationError } from '@strands-agents/sdk';
|
|
2
2
|
import type { JSONSchema, JSONValue } from '@strands-agents/sdk';
|
|
3
3
|
import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
|
|
4
|
+
import { ApplicationFailure } from '@temporalio/common';
|
|
4
5
|
import * as workflow from '@temporalio/workflow';
|
|
5
6
|
import type { ActivityOptions } from '@temporalio/workflow';
|
|
6
7
|
import { activityInfo, Context as ActivityContext } from '@temporalio/activity';
|
|
8
|
+
import type { TemporalMCPTool } from './temporal-mcp-tool';
|
|
7
9
|
|
|
8
10
|
/** Tool descriptor returned by the per-server `{server}-listTools` activity. */
|
|
9
11
|
export interface McpToolInfo {
|
|
@@ -46,11 +48,35 @@ const STUB_TRANSPORT: Transport = {
|
|
|
46
48
|
* one extra `{server}-listTools` activity per tool round.
|
|
47
49
|
* - `true` — list once at the beginning of the workflow and reuse for all
|
|
48
50
|
* turns. Cheaper, but the tool list is fixed for the workflow's lifetime.
|
|
51
|
+
*
|
|
52
|
+
* `prefix` and `toolFilters` work as on Strands' `McpClient`: the agent sees
|
|
53
|
+
* `{prefix}_{name}`, and string and `RegExp` filters match the server's tool
|
|
54
|
+
* name. A callback filter receives the workflow-side {@link TemporalMCPTool}
|
|
55
|
+
* and runs in the workflow, so it must be deterministic.
|
|
49
56
|
*/
|
|
50
57
|
export interface TemporalMCPClientOptions {
|
|
51
58
|
server: string;
|
|
52
59
|
activityOptions?: ActivityOptions;
|
|
53
60
|
cacheTools?: boolean;
|
|
61
|
+
/** Prefix for the agent's tool names, applied as `{prefix}_{name}`. */
|
|
62
|
+
prefix?: string;
|
|
63
|
+
/** Which of the server's tools the agent gets. */
|
|
64
|
+
toolFilters?: McpToolFilters;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Matches a tool, as in Strands' `McpToolMatcher`: a string matches the
|
|
69
|
+
* server's tool name exactly, a `RegExp` matches it from the start, and a
|
|
70
|
+
* callback receives the tool under the name the agent sees.
|
|
71
|
+
*/
|
|
72
|
+
export type McpToolMatcher = string | RegExp | ((tool: TemporalMCPTool) => boolean);
|
|
73
|
+
|
|
74
|
+
/** Which of a server's tools the agent gets, as in Strands' `McpToolFilters`. */
|
|
75
|
+
export interface McpToolFilters {
|
|
76
|
+
/** When present, only tools that match at least one matcher. */
|
|
77
|
+
allowed?: McpToolMatcher[];
|
|
78
|
+
/** Tools that match at least one matcher are left out, even when also allowed. */
|
|
79
|
+
rejected?: McpToolMatcher[];
|
|
54
80
|
}
|
|
55
81
|
|
|
56
82
|
/**
|
|
@@ -69,8 +95,9 @@ export interface ToolRegistryView {
|
|
|
69
95
|
*
|
|
70
96
|
* The transport factory and tool discovery live worker-side via
|
|
71
97
|
* `StrandsPlugin({ mcpClients: { server: () => new McpClient(...) } })`.
|
|
72
|
-
* This handle
|
|
73
|
-
* factory) and the per-call activity
|
|
98
|
+
* This handle carries the server name (which selects the registered
|
|
99
|
+
* factory), the tool `prefix` and `toolFilters`, and the per-call activity
|
|
100
|
+
* options.
|
|
74
101
|
*
|
|
75
102
|
* Extends {@link McpClient} so it can be passed directly in an
|
|
76
103
|
* {@link AgentConfig.tools | Agent.tools} array (Strands' `flattenTools`
|
|
@@ -82,14 +109,24 @@ export interface ToolRegistryView {
|
|
|
82
109
|
export class TemporalMCPClient extends McpClient {
|
|
83
110
|
private readonly server: string;
|
|
84
111
|
private readonly activityOptions: ActivityOptions;
|
|
112
|
+
private readonly prefix: string | undefined;
|
|
113
|
+
private readonly toolFilters: McpToolFilters | undefined;
|
|
85
114
|
/** Whether the agent lists this server's tools once or re-lists each turn. */
|
|
86
115
|
readonly cacheTools: boolean;
|
|
116
|
+
// The names this client's tools hold in each agent's registry: the names of the tools Strands
|
|
117
|
+
// added there, then the names of each refresh. While the server lists a name, the name is this
|
|
118
|
+
// client's, whatever tool workflow code puts under it.
|
|
119
|
+
private readonly held = new WeakMap<ToolRegistryView, Set<string>>();
|
|
120
|
+
// The tools this client listed, to find its names in a registry it has no record for.
|
|
121
|
+
private readonly listed = new WeakSet<object>();
|
|
87
122
|
|
|
88
123
|
constructor(options: TemporalMCPClientOptions) {
|
|
89
124
|
super({ transport: STUB_TRANSPORT });
|
|
90
125
|
this.server = options.server;
|
|
91
126
|
this.activityOptions = options.activityOptions ?? {};
|
|
92
127
|
this.cacheTools = options.cacheTools ?? false;
|
|
128
|
+
this.prefix = options.prefix;
|
|
129
|
+
this.toolFilters = options.toolFilters;
|
|
93
130
|
}
|
|
94
131
|
|
|
95
132
|
override async connect(): Promise<void> {
|
|
@@ -116,30 +153,205 @@ export class TemporalMCPClient extends McpClient {
|
|
|
116
153
|
...this.activityOptions,
|
|
117
154
|
});
|
|
118
155
|
const infos = await activities[listToolsActivityName(this.server)]!({ server: this.server });
|
|
119
|
-
|
|
156
|
+
const tools = infos
|
|
157
|
+
.map((info) => new TemporalMCPTool(this.server, info, this.activityOptions, this.prefix))
|
|
158
|
+
.filter((tool) => included(tool, this.toolFilters));
|
|
159
|
+
for (const tool of tools) this.listed.add(tool);
|
|
160
|
+
return tools as never[];
|
|
120
161
|
}
|
|
121
162
|
|
|
122
163
|
/**
|
|
123
164
|
* Re-list this server's tools and reconcile them into the agent's tool
|
|
124
|
-
* registry, dropping tools that no longer exist and adding new ones
|
|
125
|
-
*
|
|
126
|
-
*
|
|
165
|
+
* registry, dropping tools that no longer exist and adding new ones, so a
|
|
166
|
+
* mid-workflow MCP-server restart is reflected in the next call.
|
|
167
|
+
* {@link TemporalAgent} instead re-lists each of its `cacheTools: false`
|
|
168
|
+
* clients in its own hook after each tool round, and checks and applies
|
|
169
|
+
* their listings together, so a name can move between its servers.
|
|
170
|
+
*
|
|
171
|
+
* A listed name that another tool of the agent has, that differs from one
|
|
172
|
+
* only by `-` or `_`, that the listing has twice, or that Strands rejects
|
|
173
|
+
* throws Strands' `ToolValidationError` and leaves the registry as it was.
|
|
127
174
|
*/
|
|
128
175
|
async refreshTools(registry: ToolRegistryView): Promise<void> {
|
|
176
|
+
const tools = (await this.listTools()) as unknown as TemporalMCPTool[];
|
|
177
|
+
TemporalMCPClient.apply(registry, [{ client: this, tools }]);
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* One `AfterToolsEvent` hook per client in `clients`, the `cacheTools: false` clients of one agent
|
|
182
|
+
* in `tools` order, to register in that order. Strands runs them last to first. Each lists its
|
|
183
|
+
* server as {@link refreshTools} does, so the `listTools` activities keep the order and timing
|
|
184
|
+
* they had with one `refreshTools()` hook per client, unless a re-listing is refused: then every
|
|
185
|
+
* server has listed before the refusal. The last client's hook starts the tool round, and the
|
|
186
|
+
* first client's checks the round's listings together and applies them. So a name can move from
|
|
187
|
+
* one server to another between tool rounds, and a name that two of the new listings share is
|
|
188
|
+
* refused.
|
|
189
|
+
*
|
|
190
|
+
* @internal
|
|
191
|
+
*/
|
|
192
|
+
static refreshHooks(clients: TemporalMCPClient[]): ((event: RefreshEvent) => Promise<void>)[] {
|
|
193
|
+
const round: Listing[] = [];
|
|
194
|
+
return clients.map(
|
|
195
|
+
(client, i) => (event: RefreshEvent) =>
|
|
196
|
+
client.listInRound(event.agent.toolRegistry, round, i === clients.length - 1, i === 0)
|
|
197
|
+
);
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
// List this server into `round`, which `start` empties first, and apply the round at its `end`.
|
|
201
|
+
private async listInRound(registry: ToolRegistryView, round: Listing[], start: boolean, end: boolean): Promise<void> {
|
|
202
|
+
if (start) round.length = 0;
|
|
203
|
+
const tools = (await this.listTools()) as unknown as TemporalMCPTool[];
|
|
204
|
+
round.unshift({ client: this, tools });
|
|
205
|
+
if (end) TemporalMCPClient.apply(registry, round);
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* Make each of `clients` hold the name of each tool it listed that Strands adds to `registry`,
|
|
210
|
+
* the agent's registry, when Strands adds it. Strands adds a listing tool by tool and stops at a
|
|
211
|
+
* refused one, and a listing of an initialization that failed can add its tools after the agent
|
|
212
|
+
* initialized again, so only the tools that are added count, whenever they are.
|
|
213
|
+
*
|
|
214
|
+
* @internal
|
|
215
|
+
*/
|
|
216
|
+
static holdAdded(clients: TemporalMCPClient[], registry: ToolRegistryView & { add(tool: never): void }): void {
|
|
217
|
+
const add = registry.add.bind(registry);
|
|
218
|
+
registry.add = (tool: never) => {
|
|
219
|
+
try {
|
|
220
|
+
add(tool);
|
|
221
|
+
} finally {
|
|
222
|
+
const present = new Set<object>(registry.list());
|
|
223
|
+
for (const added of [tool].flat() as { name: string }[]) {
|
|
224
|
+
const client = clients.find((c) => c.listed.has(added));
|
|
225
|
+
if (client === undefined || !present.has(added)) continue;
|
|
226
|
+
const names = client.held.get(registry) ?? new Set();
|
|
227
|
+
client.held.set(registry, names.add(added.name));
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
};
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
// The names this client's tools hold in `registry`.
|
|
234
|
+
private heldIn(registry: ToolRegistryView): Set<string> {
|
|
235
|
+
return this.held.get(registry) ?? new Set(registry.list().flatMap((t) => (this.listed.has(t) ? [t.name] : [])));
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
// Check `listings` against each other, the agent's other tools and Strands' name rules, then apply
|
|
239
|
+
// them: drop the names each client held and no longer lists, and add or replace the listed tools.
|
|
240
|
+
// A refusal throws Strands' `ToolValidationError` and changes nothing.
|
|
241
|
+
private static apply(registry: ToolRegistryView, listings: Listing[]): void {
|
|
129
242
|
// Imported lazily to avoid a circular module cycle with TemporalMCPTool.
|
|
130
243
|
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
131
244
|
const { TemporalMCPTool } = require('./temporal-mcp-tool') as typeof import('./temporal-mcp-tool');
|
|
132
|
-
const
|
|
133
|
-
const
|
|
245
|
+
const held = new Map(listings.map(({ client }) => [client, client.heldIn(registry)]));
|
|
246
|
+
const freed = new Set([...held.values()].flatMap((names) => [...names]));
|
|
247
|
+
const taken = new Map<string, { name: string }>();
|
|
134
248
|
for (const tool of registry.list()) {
|
|
135
|
-
if (tool
|
|
136
|
-
|
|
249
|
+
if (!freed.has(tool.name)) taken.set(normalized(tool.name), tool);
|
|
250
|
+
}
|
|
251
|
+
const seen = new Map<string, TemporalMCPTool>();
|
|
252
|
+
for (const { client, tools } of listings) {
|
|
253
|
+
const own = new Map<string, TemporalMCPTool>();
|
|
254
|
+
for (const tool of tools) {
|
|
255
|
+
const { name } = tool;
|
|
256
|
+
const rejected = rejection(name);
|
|
257
|
+
if (rejected !== undefined) {
|
|
258
|
+
throw new ToolValidationError(
|
|
259
|
+
`${rejected}. MCP server ${listedAs(tool)} lists '${name}'. Drop it with the toolFilters of the ` +
|
|
260
|
+
`server's TemporalMCPClient.`
|
|
261
|
+
);
|
|
262
|
+
}
|
|
263
|
+
const first = own.get(normalized(name));
|
|
264
|
+
if (first !== undefined) {
|
|
265
|
+
const both = first.name === name ? 'it twice' : 'both names';
|
|
266
|
+
throw duplicateToolName(name, first.name, `MCP server '${client.server}' lists ${both}.`);
|
|
267
|
+
}
|
|
268
|
+
own.set(normalized(name), tool);
|
|
269
|
+
const earlier = seen.get(normalized(name));
|
|
270
|
+
if (earlier !== undefined) throw duplicateToolName(name, earlier.name, clash(earlier, tool));
|
|
271
|
+
const other = taken.get(normalized(name));
|
|
272
|
+
if (other !== undefined) {
|
|
273
|
+
const source =
|
|
274
|
+
other instanceof TemporalMCPTool && !client.listed.has(other)
|
|
275
|
+
? clash(other, tool)
|
|
276
|
+
: `MCP server ${listedAs(tool)} lists it, and another tool of the agent has it. Set a prefix (or a ` +
|
|
277
|
+
`different one) on the server's TemporalMCPClient, or drop '${tool.serverToolName}' with its toolFilters.`;
|
|
278
|
+
throw duplicateToolName(name, other.name, source);
|
|
279
|
+
}
|
|
280
|
+
}
|
|
281
|
+
for (const [key, tool] of own) seen.set(key, tool);
|
|
282
|
+
}
|
|
283
|
+
for (const { client, tools } of listings) {
|
|
284
|
+
const names = new Set(tools.map((t) => t.name));
|
|
285
|
+
for (const name of held.get(client)!) {
|
|
286
|
+
if (!names.has(name)) registry.remove(name);
|
|
137
287
|
}
|
|
138
288
|
}
|
|
139
|
-
|
|
289
|
+
for (const { client, tools } of listings) {
|
|
290
|
+
registry.addOrReplace(tools as never[]);
|
|
291
|
+
client.held.set(registry, new Set(tools.map((t) => t.name)));
|
|
292
|
+
}
|
|
140
293
|
}
|
|
141
294
|
}
|
|
142
295
|
|
|
296
|
+
/** The part of Strands' `AfterToolsEvent` that {@link TemporalMCPClient.refreshHooks} reads. */
|
|
297
|
+
interface RefreshEvent {
|
|
298
|
+
agent: { toolRegistry: ToolRegistryView };
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
// One client's new listing.
|
|
302
|
+
interface Listing {
|
|
303
|
+
client: TemporalMCPClient;
|
|
304
|
+
tools: TemporalMCPTool[];
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
// Strands' McpClient filter rule: whether `filters` let the agent have `tool`.
|
|
308
|
+
function included(tool: TemporalMCPTool, filters: McpToolFilters | undefined): boolean {
|
|
309
|
+
if (!filters) return true;
|
|
310
|
+
if (filters.allowed !== undefined && !filters.allowed.some((m) => matches(tool, m))) return false;
|
|
311
|
+
return !(filters.rejected !== undefined && filters.rejected.some((m) => matches(tool, m)));
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
function matches(tool: TemporalMCPTool, matcher: McpToolMatcher): boolean {
|
|
315
|
+
if (typeof matcher === 'function') return matcher(tool);
|
|
316
|
+
if (typeof matcher === 'string') return matcher === tool.serverToolName;
|
|
317
|
+
// The sticky flag anchors the match at the start of the name, as Strands does.
|
|
318
|
+
const anchored = new RegExp(matcher.source, matcher.flags.includes('y') ? matcher.flags : `${matcher.flags}y`);
|
|
319
|
+
return anchored.test(tool.serverToolName);
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
// Strands' words when its ToolRegistry rejects a tool name, or undefined when it accepts it.
|
|
323
|
+
function rejection(name: string): string | undefined {
|
|
324
|
+
if (name.length < 1 || name.length > 64) return 'Tool name must be between 1 and 64 characters';
|
|
325
|
+
if (!/^[a-zA-Z0-9_-]+$/.test(name)) return 'Tool name must contain only alphanumeric characters, hyphens, and underscores';
|
|
326
|
+
return undefined;
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
// Strands' ToolRegistry refuses a name that differs from a registered one only by '-' or '_'.
|
|
330
|
+
function normalized(name: string): string {
|
|
331
|
+
return name.replaceAll('-', '_');
|
|
332
|
+
}
|
|
333
|
+
|
|
334
|
+
// The server that lists `tool`, with the server's own name for it when a prefix renames it.
|
|
335
|
+
function listedAs(tool: TemporalMCPTool): string {
|
|
336
|
+
return tool.serverToolName === tool.name ? `'${tool.server}'` : `'${tool.server}' (as '${tool.serverToolName}')`;
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
// Where two clashing MCP tools of two clients come from: `held` is the agent's, and `tool` the new one.
|
|
340
|
+
function clash(held: TemporalMCPTool, tool: TemporalMCPTool): string {
|
|
341
|
+
return held.server === tool.server
|
|
342
|
+
? `The agent has two TemporalMCPClient handles for MCP server '${tool.server}'. Give one a different ` +
|
|
343
|
+
`prefix, narrow one's toolFilters, or pass only one.`
|
|
344
|
+
: `MCP servers ${listedAs(held)} and ${listedAs(tool)} both list it. Set a prefix (or a different one) on ` +
|
|
345
|
+
`one server's TemporalMCPClient, or drop the tool from one with its toolFilters.`;
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
// Strands' words when its ToolRegistry refuses a name, then where the two tools come from.
|
|
349
|
+
function duplicateToolName(name: string, other: string, source: string): ToolValidationError {
|
|
350
|
+
const refused =
|
|
351
|
+
other === name ? `Tool with name '${name}' already registered.` : `Tool name '${name}' already exists as '${other}'.`;
|
|
352
|
+
return new ToolValidationError(`${refused} ${source}`);
|
|
353
|
+
}
|
|
354
|
+
|
|
143
355
|
export function listToolsActivityName(server: string): string {
|
|
144
356
|
return `${server}-listTools`;
|
|
145
357
|
}
|
|
@@ -150,20 +362,21 @@ export function callToolActivityName(server: string): string {
|
|
|
150
362
|
|
|
151
363
|
/**
|
|
152
364
|
* Builds the per-server `{server}-listTools` activity. Enumerates the server's
|
|
153
|
-
* tools live over the
|
|
154
|
-
*
|
|
155
|
-
*
|
|
365
|
+
* tools live over the plugin's connection on every call, so the agent sees the
|
|
366
|
+
* server's current tools even if it is redeployed mid-workflow. Runs whenever a
|
|
367
|
+
* workflow calls {@link TemporalMCPClient.listTools}.
|
|
156
368
|
*/
|
|
157
369
|
export function buildListToolsActivity(
|
|
158
370
|
server: string,
|
|
159
371
|
factory: () => McpClient,
|
|
160
|
-
|
|
372
|
+
connections: McpConnections
|
|
161
373
|
): (input: { server: string }) => Promise<McpToolInfo[]> {
|
|
162
374
|
const name = listToolsActivityName(server);
|
|
163
375
|
const fn = async (_input: { server: string }): Promise<McpToolInfo[]> => {
|
|
164
|
-
const record =
|
|
376
|
+
const record = connections.acquire(server, factory);
|
|
165
377
|
try {
|
|
166
378
|
const client = await record.client;
|
|
379
|
+
refuseFactoryPrefix(server, client);
|
|
167
380
|
const tools = await client.listTools();
|
|
168
381
|
return tools.map((t) => ({
|
|
169
382
|
name: t.name,
|
|
@@ -171,26 +384,41 @@ export function buildListToolsActivity(
|
|
|
171
384
|
inputSchema: t.toolSpec.inputSchema,
|
|
172
385
|
}));
|
|
173
386
|
} catch (err) {
|
|
174
|
-
// The session may be broken (e.g. the server was redeployed);
|
|
175
|
-
// the next call reconnects to the current deployment.
|
|
176
|
-
|
|
387
|
+
// The session may be broken (e.g. the server was redeployed); stop handing
|
|
388
|
+
// it out so the next call reconnects to the current deployment. It is
|
|
389
|
+
// closed once the calls still using it have finished.
|
|
390
|
+
connections.retire(server, record);
|
|
177
391
|
throw err;
|
|
178
392
|
} finally {
|
|
179
|
-
//
|
|
180
|
-
//
|
|
181
|
-
|
|
393
|
+
// Closes the connection if it was retired and this was the last in-flight
|
|
394
|
+
// call; otherwise lets idle eviction resume.
|
|
395
|
+
connections.release(server, record);
|
|
182
396
|
}
|
|
183
397
|
};
|
|
184
398
|
Object.defineProperty(fn, 'name', { value: name });
|
|
185
399
|
return fn;
|
|
186
400
|
}
|
|
187
401
|
|
|
402
|
+
// A prefix on the factory's McpClient renames the tools the agent sees, and the callTool activity
|
|
403
|
+
// then asks the server for those names. Refuse it, retryably, so a run waits for a fixed worker.
|
|
404
|
+
function refuseFactoryPrefix(server: string, client: McpClient): void {
|
|
405
|
+
// Strands' McpClient keeps the option in a private field.
|
|
406
|
+
const prefix = (client as unknown as { _prefix?: string })._prefix;
|
|
407
|
+
if (prefix) {
|
|
408
|
+
throw new Error(
|
|
409
|
+
`The McpClient that the StrandsPlugin mcpClients factory returns for MCP server '${server}' sets ` +
|
|
410
|
+
`prefix '${prefix}'. Set it on the workflow-side TemporalMCPClient instead: ` +
|
|
411
|
+
`new TemporalMCPClient({ server: '${server}', prefix: '${prefix}' }).`
|
|
412
|
+
);
|
|
413
|
+
}
|
|
414
|
+
}
|
|
415
|
+
|
|
188
416
|
/**
|
|
189
417
|
* Default for how long an *idle* MCP connection is kept open before it's
|
|
190
418
|
* disconnected. The window only starts once no {@link callToolActivityName |
|
|
191
419
|
* callTool} or {@link listToolsActivityName | listTools} activity is using the
|
|
192
420
|
* connection, so a call that runs longer than this is never cut off. Override
|
|
193
|
-
* per
|
|
421
|
+
* per plugin via `StrandsPlugin({ mcpConnectionIdleTimeout })`.
|
|
194
422
|
*/
|
|
195
423
|
export const MCP_CONNECTION_IDLE_MS = 5 * 60 * 1000;
|
|
196
424
|
|
|
@@ -200,24 +428,26 @@ interface ConnectionRecord {
|
|
|
200
428
|
client: Promise<McpClient>;
|
|
201
429
|
/** Number of activities currently using this connection. */
|
|
202
430
|
inflight: number;
|
|
431
|
+
/**
|
|
432
|
+
* Set after a failed call, or when the last Worker using the plugin stops
|
|
433
|
+
* while a call still uses the connection. A retired record is no longer
|
|
434
|
+
* handed out to new calls, and is only disconnected once `inflight` drops
|
|
435
|
+
* back to 0, so one call can't close the session under its siblings.
|
|
436
|
+
*/
|
|
437
|
+
retired: boolean;
|
|
203
438
|
/** Armed only while `inflight` is 0. */
|
|
204
439
|
idleTimer?: NodeJS.Timeout;
|
|
205
440
|
}
|
|
206
441
|
|
|
207
|
-
|
|
208
|
-
// Node process, so this module state is shared across every activity invocation on the worker.
|
|
209
|
-
const CONNECTIONS: Map<string, ConnectionRecord> = new Map();
|
|
210
|
-
|
|
211
|
-
export async function _evictConnection(server: string): Promise<void> {
|
|
212
|
-
const record = CONNECTIONS.get(server);
|
|
213
|
-
if (record === undefined) return;
|
|
214
|
-
// Delete before awaiting: a call arriving during `disconnect` must open a
|
|
215
|
-
// fresh connection rather than join the one being torn down.
|
|
216
|
-
CONNECTIONS.delete(server);
|
|
442
|
+
function clearIdleTimer(record: ConnectionRecord): void {
|
|
217
443
|
if (record.idleTimer !== undefined) {
|
|
218
444
|
clearTimeout(record.idleTimer);
|
|
219
445
|
record.idleTimer = undefined;
|
|
220
446
|
}
|
|
447
|
+
}
|
|
448
|
+
|
|
449
|
+
/** Disconnect a record that is no longer handed out. Best-effort. */
|
|
450
|
+
async function closeRecord(record: ConnectionRecord): Promise<void> {
|
|
221
451
|
try {
|
|
222
452
|
const client = await record.client;
|
|
223
453
|
await client.disconnect();
|
|
@@ -226,76 +456,161 @@ export async function _evictConnection(server: string): Promise<void> {
|
|
|
226
456
|
}
|
|
227
457
|
}
|
|
228
458
|
|
|
459
|
+
// Names a value for an error message: `undefined`, `null`, `number`, or an object's class, such as `Client`.
|
|
460
|
+
export function describeValue(value: unknown): string {
|
|
461
|
+
if (value === null) return 'null';
|
|
462
|
+
if (typeof value !== 'object' && typeof value !== 'function') return typeof value;
|
|
463
|
+
return (value as { constructor?: { name?: string } }).constructor?.name || typeof value;
|
|
464
|
+
}
|
|
465
|
+
|
|
229
466
|
/**
|
|
230
|
-
*
|
|
231
|
-
*
|
|
232
|
-
*
|
|
233
|
-
* the same
|
|
234
|
-
*
|
|
467
|
+
* The worker-process MCP connections of one {@link StrandsPlugin}, keyed by
|
|
468
|
+
* server name. Workers that share a plugin instance share its connections;
|
|
469
|
+
* another plugin instance opens its own through its own factories, even for
|
|
470
|
+
* the same server name. The plugin's `runContext` counts the Workers using
|
|
471
|
+
* them, and the last one to stop closes them. A connection that a call still
|
|
472
|
+
* uses is closed when that call finishes.
|
|
235
473
|
*/
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
}
|
|
252
|
-
|
|
253
|
-
|
|
474
|
+
export class McpConnections {
|
|
475
|
+
private readonly records: Map<string, ConnectionRecord> = new Map();
|
|
476
|
+
private workers = 0;
|
|
477
|
+
|
|
478
|
+
/**
|
|
479
|
+
* @param idleMs how long an idle connection stays open; defaults to
|
|
480
|
+
* {@link MCP_CONNECTION_IDLE_MS}.
|
|
481
|
+
*/
|
|
482
|
+
constructor(private readonly idleMs: number = MCP_CONNECTION_IDLE_MS) {}
|
|
483
|
+
|
|
484
|
+
/** Runs one Worker; once no Worker uses these connections, closes them. */
|
|
485
|
+
async use(next: () => Promise<void>): Promise<void> {
|
|
486
|
+
this.workers += 1;
|
|
487
|
+
try {
|
|
488
|
+
await next();
|
|
489
|
+
} finally {
|
|
490
|
+
this.workers -= 1;
|
|
491
|
+
if (this.workers === 0) {
|
|
492
|
+
await Promise.all([...this.records.keys()].map((server) => this.evict(server)));
|
|
493
|
+
}
|
|
494
|
+
}
|
|
254
495
|
}
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
496
|
+
|
|
497
|
+
/**
|
|
498
|
+
* Stop handing out `server`'s connection, and disconnect it now or when the
|
|
499
|
+
* last call still using it finishes.
|
|
500
|
+
*/
|
|
501
|
+
async evict(server: string): Promise<void> {
|
|
502
|
+
const record = this.records.get(server);
|
|
503
|
+
if (record === undefined) return;
|
|
504
|
+
// Delete before awaiting: a call arriving during `disconnect` must open a
|
|
505
|
+
// fresh connection rather than join the one being torn down.
|
|
506
|
+
this.records.delete(server);
|
|
507
|
+
clearIdleTimer(record);
|
|
508
|
+
if (record.inflight > 0) {
|
|
509
|
+
record.retired = true;
|
|
510
|
+
return;
|
|
511
|
+
}
|
|
512
|
+
await closeRecord(record);
|
|
259
513
|
}
|
|
260
|
-
return record;
|
|
261
|
-
}
|
|
262
514
|
|
|
263
|
-
/**
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
515
|
+
/**
|
|
516
|
+
* Return the cached connection for `server`, opening one lazily if needed,
|
|
517
|
+
* and mark a call in flight so idle eviction can't disconnect underneath it.
|
|
518
|
+
* Concurrent first-callers dedupe onto a single connect handshake by awaiting
|
|
519
|
+
* the same record. Every caller must {@link release} once its call completes.
|
|
520
|
+
*/
|
|
521
|
+
acquire(server: string, factory: () => McpClient): ConnectionRecord {
|
|
522
|
+
let record = this.records.get(server);
|
|
523
|
+
if (record === undefined) {
|
|
524
|
+
const entry: ConnectionRecord = {
|
|
525
|
+
inflight: 0,
|
|
526
|
+
retired: false,
|
|
527
|
+
client: (async () => {
|
|
528
|
+
const client = factory();
|
|
529
|
+
if (
|
|
530
|
+
client == null ||
|
|
531
|
+
typeof client.connect !== 'function' ||
|
|
532
|
+
typeof client.disconnect !== 'function' ||
|
|
533
|
+
typeof client.listTools !== 'function' ||
|
|
534
|
+
typeof client.callTool !== 'function'
|
|
535
|
+
) {
|
|
536
|
+
throw ApplicationFailure.nonRetryable(
|
|
537
|
+
`MCP client factory '${server}' returned ${describeValue(client)}, not a client with ` +
|
|
538
|
+
'connect(), disconnect(), listTools() and callTool() methods.',
|
|
539
|
+
'MCPClientFactoryTypeError'
|
|
540
|
+
);
|
|
541
|
+
}
|
|
542
|
+
await client.connect();
|
|
543
|
+
return client;
|
|
544
|
+
})(),
|
|
545
|
+
};
|
|
546
|
+
// If the connect handshake fails, drop the rejected promise so the next
|
|
547
|
+
// call retries instead of caching the failure forever.
|
|
548
|
+
entry.client.catch(() => {
|
|
549
|
+
if (this.records.get(server) === entry) this.records.delete(server);
|
|
550
|
+
});
|
|
551
|
+
this.records.set(server, entry);
|
|
552
|
+
record = entry;
|
|
553
|
+
}
|
|
554
|
+
record.inflight += 1;
|
|
555
|
+
clearIdleTimer(record);
|
|
556
|
+
return record;
|
|
557
|
+
}
|
|
558
|
+
|
|
559
|
+
/**
|
|
560
|
+
* Flag `record` as suspect after a failed call. It is unpublished at once so
|
|
561
|
+
* new calls open a fresh connection, but not disconnected until the calls
|
|
562
|
+
* still using it have released it (see {@link release}).
|
|
563
|
+
*/
|
|
564
|
+
retire(server: string, record: ConnectionRecord): void {
|
|
565
|
+
// Already evicted or replaced; whoever did that is closing it.
|
|
566
|
+
if (this.records.get(server) !== record) return;
|
|
567
|
+
record.retired = true;
|
|
568
|
+
this.records.delete(server);
|
|
569
|
+
clearIdleTimer(record);
|
|
570
|
+
}
|
|
571
|
+
|
|
572
|
+
/**
|
|
573
|
+
* Mark a call done. Once no calls remain in flight, disconnect a retired
|
|
574
|
+
* connection or arm idle eviction for a healthy one.
|
|
575
|
+
*/
|
|
576
|
+
release(server: string, record: ConnectionRecord): void {
|
|
577
|
+
record.inflight -= 1;
|
|
578
|
+
if (record.retired) {
|
|
579
|
+
if (record.inflight === 0) void closeRecord(record);
|
|
580
|
+
return;
|
|
581
|
+
}
|
|
582
|
+
// Only the record still cached under this server arms a timer; a record
|
|
583
|
+
// already evicted must not schedule one, or it could later evict a
|
|
584
|
+
// different, healthy connection for the same server.
|
|
585
|
+
if (record.inflight > 0 || this.records.get(server) !== record) return;
|
|
586
|
+
const timer = setTimeout(() => {
|
|
587
|
+
// `acquire` clears this timer synchronously, so a pending timer implies
|
|
588
|
+
// the connection is still idle; re-checked to keep that invariant local.
|
|
589
|
+
if (record.inflight === 0) void this.evict(server);
|
|
590
|
+
}, this.idleMs);
|
|
591
|
+
// Don't let an idle MCP connection keep the worker process alive.
|
|
592
|
+
timer.unref?.();
|
|
593
|
+
record.idleTimer = timer;
|
|
594
|
+
}
|
|
279
595
|
}
|
|
280
596
|
|
|
281
597
|
/**
|
|
282
|
-
* Builds the per-server `{server}-callTool` activity. Reuses
|
|
283
|
-
*
|
|
284
|
-
*
|
|
285
|
-
*
|
|
286
|
-
* {@link MCP_CONNECTION_IDLE_MS}).
|
|
598
|
+
* Builds the per-server `{server}-callTool` activity. Reuses the plugin's MCP
|
|
599
|
+
* session, opened lazily through the user-supplied factory — successive calls
|
|
600
|
+
* share one connection rather than reconnecting per call. Idle connections are
|
|
601
|
+
* disconnected after the plugin's idle timeout.
|
|
287
602
|
*/
|
|
288
603
|
export function buildCallToolActivity(
|
|
289
604
|
server: string,
|
|
290
605
|
factory: () => McpClient,
|
|
291
|
-
|
|
606
|
+
connections: McpConnections
|
|
292
607
|
): (input: CallToolInput) => Promise<JSONValue> {
|
|
293
608
|
const name = callToolActivityName(server);
|
|
294
609
|
const fn = async (input: CallToolInput): Promise<JSONValue> => {
|
|
295
610
|
ActivityContext.current().log.debug(`Calling MCP tool ${input.toolName} on server ${server}`, {
|
|
296
611
|
activityId: activityInfo().activityId,
|
|
297
612
|
});
|
|
298
|
-
const record =
|
|
613
|
+
const record = connections.acquire(server, factory);
|
|
299
614
|
// Dispatch by name without re-listing tools on the connection: the agent
|
|
300
615
|
// already has the schema from `listTools`, and `McpClient.callTool` only
|
|
301
616
|
// reads `tool.name` to build the request. A minimal `{ name }` matches the
|
|
@@ -305,13 +620,14 @@ export function buildCallToolActivity(
|
|
|
305
620
|
const client = await record.client;
|
|
306
621
|
return await client.callTool(tool, input.args);
|
|
307
622
|
} catch (err) {
|
|
308
|
-
// The session may be broken;
|
|
309
|
-
|
|
623
|
+
// The session may be broken; stop handing it out so the next call
|
|
624
|
+
// reconnects. It is closed once the calls still using it have finished.
|
|
625
|
+
connections.retire(server, record);
|
|
310
626
|
throw err;
|
|
311
627
|
} finally {
|
|
312
|
-
//
|
|
313
|
-
//
|
|
314
|
-
|
|
628
|
+
// Closes the connection if it was retired and this was the last in-flight
|
|
629
|
+
// call; otherwise lets idle eviction resume.
|
|
630
|
+
connections.release(server, record);
|
|
315
631
|
}
|
|
316
632
|
};
|
|
317
633
|
Object.defineProperty(fn, 'name', { value: name });
|