@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
@@ -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 only carries the server name (which selects the registered
73
- * factory) and the per-call activity options.
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
- return infos.map((info) => new TemporalMCPTool(this.server, info, this.activityOptions)) as never[];
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
- * {@link TemporalAgent} calls this on each agent turn when `cacheTools` is
126
- * `false` so a mid-workflow MCP-server restart is reflected in the next call.
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 fresh = await this.listTools();
133
- const freshNames = new Set((fresh as unknown as { name: string }[]).map((t) => t.name));
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 instanceof TemporalMCPTool && tool.server === this.server && !freshNames.has(tool.name)) {
136
- registry.remove(tool.name);
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
- registry.addOrReplace(fresh);
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 shared worker-process connection on every call, so the
154
- * agent sees the server's current tools even if it is redeployed mid-workflow.
155
- * Runs whenever a workflow calls {@link TemporalMCPClient.listTools}.
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
- idleMs: number = MCP_CONNECTION_IDLE_MS
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 = acquireConnection(server, factory);
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); drop it so
175
- // the next call reconnects to the current deployment.
176
- await _evictConnection(server);
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
- // No more in-flight call on this connection; let idle eviction resume
180
- // (no-op if the connection was just evicted above).
181
- releaseConnection(server, record, idleMs);
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 worker via `StrandsPlugin({ mcpConnectionIdleTimeout })`.
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
- // Worker-process cache, keyed by server name. Activities run in the worker's
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
- * Return the cached connection for `server`, opening one lazily if needed, and
231
- * mark a call in flight so idle eviction can't disconnect underneath it.
232
- * Concurrent first-callers dedupe onto a single connect handshake by awaiting
233
- * the same record. Every caller must {@link releaseConnection} once its call
234
- * completes.
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
- function acquireConnection(server: string, factory: () => McpClient): ConnectionRecord {
237
- let record = CONNECTIONS.get(server);
238
- if (record === undefined) {
239
- const entry: ConnectionRecord = {
240
- inflight: 0,
241
- client: (async () => {
242
- const client = factory();
243
- await client.connect();
244
- return client;
245
- })(),
246
- };
247
- // If the connect handshake fails, drop the rejected promise so the next
248
- // call retries instead of caching the failure forever.
249
- entry.client.catch(() => {
250
- if (CONNECTIONS.get(server) === entry) CONNECTIONS.delete(server);
251
- });
252
- CONNECTIONS.set(server, entry);
253
- record = entry;
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
- record.inflight += 1;
256
- if (record.idleTimer !== undefined) {
257
- clearTimeout(record.idleTimer);
258
- record.idleTimer = undefined;
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
- /** Mark a call done; arm idle eviction once no calls remain in flight. */
264
- function releaseConnection(server: string, record: ConnectionRecord, idleMs: number): void {
265
- record.inflight -= 1;
266
- // Only the record still cached under this server arms a timer; a record
267
- // already evicted must not schedule one, or it could later evict a
268
- // different, healthy connection for the same server.
269
- if (record.inflight > 0 || CONNECTIONS.get(server) !== record) return;
270
- const timer = setTimeout(() => {
271
- // `acquireConnection` clears this timer synchronously, so a pending timer
272
- // implies the connection is still idle; re-checked to keep that invariant
273
- // local.
274
- if (record.inflight === 0) void _evictConnection(server);
275
- }, idleMs);
276
- // Don't let an idle MCP connection keep the worker process alive.
277
- timer.unref?.();
278
- record.idleTimer = timer;
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 a worker-process
283
- * MCP session opened lazily through the user-supplied factory — successive
284
- * calls share one connection rather than reconnecting per call. Idle
285
- * connections are disconnected after `idleMs` (defaults to
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
- idleMs: number = MCP_CONNECTION_IDLE_MS
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 = acquireConnection(server, factory);
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; drop it so the next call reconnects.
309
- await _evictConnection(server);
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
- // No more in-flight call on this connection; let idle eviction resume
313
- // (no-op if the connection was just evicted above).
314
- releaseConnection(server, record, idleMs);
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 });