@tanstack/ai 0.26.1 → 0.28.0

package/skills/ai-core/tool-calling/SKILL.md

@@ -375,6 +375,293 @@ gets the full schema, then calls `compareProducts` directly.
 Once discovered, a tool stays available for the conversation.
 When all lazy tools are discovered, the discovery tool is removed automatically.
 
+## MCP Tools
+
+`@tanstack/ai-mcp` lets a server-side `chat()` call discover and invoke tools
+hosted on any MCP server (Streamable HTTP, SSE, or stdio).
+
+### Basic usage — auto-discovery
+
+```typescript
+// src/routes/api.chat.ts
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const { messages } = await request.json()
+
+        // 1. Connect to the MCP server.
+        const mcp = await createMCPClient({
+          transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+        })
+
+        // 2. Discover all tools from the server (returns ServerTool[]).
+        const mcpTools = await mcp.tools()
+
+        // 3. Spread them into chat() — they work exactly like hand-written tools.
+        // Caller owns the lifecycle — chat() never closes the client. Tools run
+        // while the response streams, so close in a middleware terminal hook
+        // (a try/finally around the return would close before tools execute).
+        const stream = chat({
+          adapter: openaiText('gpt-5.5'),
+          messages,
+          tools: [...mcpTools],
+          middleware: [
+            {
+              name: 'mcp-close',
+              onFinish: () => mcp.close(),
+              onAbort: () => mcp.close(),
+              onError: () => mcp.close(),
+            },
+          ],
+        })
+        return toServerSentEventsResponse(stream)
+      },
+    },
+  },
+})
+```
+
+### Typed path — pass toolDefinition instances
+
+Pass bare `toolDefinition()` instances (no `.server()`) to `client.tools([...])`.
+The MCP client supplies a `callTool` proxy as the execute function, while
+input/output validation and types come from the definitions' Zod schemas.
+
+```typescript
+import { toolDefinition } from '@tanstack/ai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+import { z } from 'zod'
+
+const getWeather = toolDefinition({
+  name: 'get_weather',
+  description: 'Current weather for a city',
+  inputSchema: z.object({ city: z.string() }),
+  outputSchema: z.object({ temperature: z.number(), conditions: z.string() }),
+})
+
+const mcp = await createMCPClient({
+  transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+})
+
+// Returns ServerTool[] typed to the definitions' input/output schemas.
+// Throws MCPToolNotFoundError if the server does not expose a tool with that name.
+const tools = await mcp.tools([getWeather])
+
+const stream = chat({ adapter: openaiText('gpt-5.5'), messages, tools })
+```
+
+### Multiple servers with `createMCPClients`
+
+```typescript
+import { createMCPClients } from '@tanstack/ai-mcp'
+
+// Each key becomes the default prefix for that server's tools.
+await using pool = await createMCPClients({
+  github: { transport: { type: 'http', url: 'https://mcp.github.com/mcp' } },
+  linear: { transport: { type: 'http', url: 'https://mcp.linear.app/mcp' } },
+})
+
+// Tools auto-prefixed: 'github_search_repos', 'linear_create_issue', etc.
+const tools = await pool.tools()
+
+const stream = chat({ adapter: openaiText('gpt-5.5'), messages, tools })
+```
+
+Use `pool.clients.<name>` for typed per-server access (resources, prompts, typed
+`tools([defs])` overload).
+
+### `ToolExecutionContext.abortSignal` — cancelling long-running tools
+
+Every server tool's execute function now receives `abortSignal` in its context.
+When the chat run aborts (e.g. the client disconnects or calls the run's
+`abortController`), the signal fires and any in-flight `callTool` call is
+cancelled automatically.
+
+You can also forward it from your own server tools:
+
+```typescript
+const longRunningTool = myToolDef.server(async (args, ctx) => {
+  // Forward to fetch, a DB query, or an MCP callTool call.
+  const response = await fetch('https://slow.api/data', {
+    signal: ctx?.abortSignal,
+  })
+  return response.json()
+})
+```
+
+MCP tools wire this automatically — `makeMcpExecute` passes `ctx?.abortSignal`
+as the `signal` option to `client.callTool(...)`, so MCP server calls cancel
+with the chat run without any extra code.
+
+### stdio transport (Node-only)
+
+```typescript
+import { createMCPClient } from '@tanstack/ai-mcp'
+import { stdioTransport } from '@tanstack/ai-mcp/stdio'
+
+const mcp = await createMCPClient({
+  transport: stdioTransport({ command: 'npx', args: ['-y', 'my-mcp-server'] }),
+})
+```
+
+Import `stdioTransport` from the `/stdio` subpath only — it contains Node.js
+`child_process` imports and must not be bundled for edge runtimes.
+
+### `chat({ mcp })` — discovery + lifecycle in one prop
+
+Instead of manually calling `client.tools()` and managing `close()`, pass an
+`mcp` object and let `chat()` handle discovery and lifecycle.
+
+```typescript
+// Prop shape (ChatMCPOptions):
+// mcp: {
+//   clients: Array<MCPClient | MCPClients>,
+//   connection?: 'close' | 'keep-alive',  // default: 'close'
+//   lazyTools?: boolean,
+//   onDiscoveryError?: (error: unknown, source) => void,
+// }
+```
+
+- At run start, `chat()` calls `.tools()` on every entry in `clients` and merges
+  the results — identical to spreading `await client.tools()` into `tools: [...]`.
+- `lazyTools: true` is forwarded to `tools({ lazy: true })`.
+- `onDiscoveryError`: throw to fail-fast; return to skip that source.
+- `connection: 'close'` (default) closes each client when the run ends (after
+  the agent loop completes and the stream is drained). With `'keep-alive'`,
+  `chat()` never closes the clients — the caller owns their lifecycle (keep
+  connections warm across requests).
+
+**When to use `mcp` vs. the tools spread:**
+
+| Approach                                                | Use when                                                                          |
+| ------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `chat({ mcp: { clients: [...] } })`                     | Convenience: discovery + lifecycle in one place; untyped tool args are acceptable |
+| `tools: [...await client.tools([toolDefinition(...)])]` | Fully-typed tool args/results via Zod schemas                                     |
+
+**Example:**
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const { messages } = await request.json()
+
+        const mcpClient = await createMCPClient({
+          transport: { type: 'http', url: 'https://mcp.example.com/mcp' },
+        })
+
+        const stream = chat({
+          adapter: openaiText('gpt-5.5'),
+          messages,
+          mcp: {
+            clients: [mcpClient],
+            connection: 'keep-alive',
+            onDiscoveryError: (err, source) => {
+              console.warn('MCP discovery failed, skipping source:', err)
+              // returning (not throwing) skips this source and continues
+            },
+          },
+        })
+
+        return toServerSentEventsResponse(stream)
+      },
+    },
+  },
+})
+```
+
+## Provider Skills
+
+> **Not to be confused with `@tanstack/ai-code-mode-skills`**, which are locally-generated TypeScript functions executed client-side. Provider Skills are hosted, provider-managed bundles that the model loads on demand and runs inside the provider's server-side sandbox.
+
+Provider Skills are inert without an execution tool. The execution tool is what activates the sandbox; skills are additional capability bundles that run inside it:
+
+- **Anthropic**: skills require the `code_execution` tool (`@tanstack/ai-anthropic/tools`).
+- **OpenAI**: skills live inside the `shell` tool (`@tanstack/ai-openai/tools`) and are Responses API only.
+
+### Anthropic: `codeExecutionTool` with skills
+
+Import from `@tanstack/ai-anthropic/tools`:
+
+```typescript
+import { codeExecutionTool } from '@tanstack/ai-anthropic/tools'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+
+export async function POST(request: Request) {
+  const { messages } = await request.json()
+  const stream = chat({
+    adapter: anthropicText('claude-sonnet-4-5'),
+    messages,
+    tools: [
+      codeExecutionTool(
+        { type: 'code_execution_20250825', name: 'code_execution' },
+        {
+          skills: [{ type: 'anthropic', skill_id: 'pptx', version: 'latest' }],
+        },
+      ),
+    ],
+  })
+  return toServerSentEventsResponse(stream)
+}
+```
+
+`AnthropicContainerSkill` shape: `{ type: 'anthropic' | 'custom'; skill_id: string; version?: string }`. Constraints: max 8 skills per request; `skill_id` must be 1–64 characters.
+
+The adapter automatically:
+
+- Lifts the skills into the request's top-level `container.skills` param (the shape Anthropic's API requires).
+- Attaches the required beta headers (`code-execution-2025-08-25` plus `skills-2025-10-02` when skills are present). You do not set these manually.
+
+**Deprecation:** Setting skills via `modelOptions.container.skills` is deprecated. Use `codeExecutionTool(config, { skills })` instead — the legacy path bypasses the beta-header wiring.
+
+### OpenAI: `shellTool` with skills (Responses API only)
+
+Import from `@tanstack/ai-openai/tools`:
+
+```typescript
+import { shellTool } from '@tanstack/ai-openai/tools'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+
+export async function POST(request: Request) {
+  const { messages } = await request.json()
+  const stream = chat({
+    adapter: openaiText('gpt-5.2'),
+    messages,
+    tools: [
+      shellTool({
+        environment: {
+          type: 'container_auto',
+          skills: [
+            { type: 'skill_reference', skill_id: 'skill_abc', version: '2' },
+          ],
+        },
+      }),
+    ],
+  })
+  return toServerSentEventsResponse(stream)
+}
+```
+
+`SkillReference` shape: `{ type: 'skill_reference'; skill_id: string; version?: string }`. `version` is a string — use a positive integer as a string (e.g. `'2'`) or `'latest'`. This is Responses API only; Chat Completions does not support the shell tool.
+
+### Scope
+
+Only hosted/managed-by-id skills (`type: 'anthropic'` / `type: 'custom'` for Anthropic; `type: 'skill_reference'` for OpenAI) are wired. Inline bundles, local-path, and upload-API skill creation are not handled by these factories.
+
 ## Common Mistakes
 
 ### a. HIGH: Not passing tool definitions to both server and client

package/src/activities/chat/index.ts

@@ -25,6 +25,7 @@ import {
 import { maxIterations as maxIterationsStrategy } from './agent-loop-strategies'
 import { convertMessagesToModelMessages, generateMessageId } from './messages'
 import { MiddlewareRunner } from './middleware/compose'
+import { MCPManager } from './mcp/manager'
 import type {
   ApprovalRequest,
   ClientToolRequest,
@@ -69,6 +70,7 @@ import type {
   MergeContext,
   UnionToIntersection,
 } from './runtime-context-types'
+import type { ChatMCPOptions } from './mcp/types'
 
 // ===========================
 // Activity Kind
@@ -208,12 +210,12 @@ export interface TextActivityOptions<
         | ProviderTool<string, TAdapter['~types']['toolCapabilities'][number]>
       >
     | undefined
-  /** Controls the randomness of the output. Higher values make output more random. Range: [0.0, 2.0] */
-  temperature?: TextOptions['temperature']
-  /** Nucleus sampling parameter. The model considers tokens with topP probability mass. */
-  topP?: TextOptions['topP']
-  /** The maximum number of tokens to generate in the response. */
-  maxTokens?: TextOptions['maxTokens']
+  /**
+   * Hand MCP clients/pools to chat(): their tools are discovered at run start
+   * and merged into the run; `connection` controls whether chat() closes them
+   * when the run ends. See docs/tools/mcp.md "Managing MCP clients with chat()".
+   */
+  mcp?: ChatMCPOptions
   /** Additional metadata to attach to the request. */
   metadata?: TextOptions['metadata']
   /** Model-specific provider options (type comes from adapter) */
@@ -438,6 +440,28 @@ interface TextEngineConfig<
 type ToolPhaseResult = 'continue' | 'stop' | 'wait'
 type CyclePhase = 'processText' | 'executeToolCalls'
 
+/**
+ * Combine two optional AbortSignals into one that aborts when either does.
+ * Returns the other signal directly when one is absent or already aborted.
+ * (Manual implementation — `AbortSignal.any` requires Node >= 20.3.)
+ */
+function combineAbortSignals(
+  a: AbortSignal | undefined,
+  b: AbortSignal | undefined,
+): AbortSignal | undefined {
+  if (!a) return b
+  if (!b) return a
+  if (a.aborted) return a
+  if (b.aborted) return b
+  const controller = new AbortController()
+  const onAbort = (source: AbortSignal) => () => {
+    controller.abort(source.reason)
+  }
+  a.addEventListener('abort', onAbort(a), { once: true })
+  b.addEventListener('abort', onAbort(b), { once: true })
+  return controller.signal
+}
+
 class TextEngine<
   TAdapter extends AnyTextAdapter,
   TContext = unknown,
@@ -492,6 +516,9 @@ class TextEngine<
   private readonly deferredPromises: Array<Promise<unknown>> = []
   private abortReason?: string
   private readonly middlewareAbortController?: AbortController
+  // Combines the caller's signal with middleware abort() so running tools
+  // observe both cancellation sources via ctx.abortSignal.
+  private readonly toolAbortSignal?: AbortSignal
   private terminalHookCalled = false
 
   private readonly logger: InternalLogger
@@ -589,6 +616,10 @@ class TextEngine<
     ]
     this.middlewareRunner = new MiddlewareRunner(allMiddleware, logger)
     this.middlewareAbortController = new AbortController()
+    this.toolAbortSignal = combineAbortSignals(
+      this.effectiveSignal,
+      this.middlewareAbortController.signal,
+    )
     this.middlewareCtx = {
       requestId: this.requestId,
       streamId: this.streamId,
@@ -844,13 +875,10 @@ class TextEngine<
 
   private beforeRun(): void {
     this.streamStartTime = Date.now()
-    const { tools, temperature, topP, maxTokens, metadata } = this.params
+    const { tools, metadata } = this.params
 
     // Gather flattened options into an object for context
     const options: Record<string, unknown> = {}
-    if (temperature !== undefined) options.temperature = temperature
-    if (topP !== undefined) options.topP = topP
-    if (maxTokens !== undefined) options.maxTokens = maxTokens
     if (metadata !== undefined) options.metadata = metadata
 
     this.eventOptions = Object.keys(options).length > 0 ? options : undefined
@@ -897,7 +925,7 @@ class TextEngine<
   }
 
   private async *streamModelResponse(): AsyncGenerator<StreamChunk> {
-    const { temperature, topP, maxTokens, metadata, modelOptions } = this.params
+    const { metadata, modelOptions } = this.params
     const tools = this.tools
 
     // Convert tool schemas to JSON Schema before passing to adapter
@@ -941,9 +969,6 @@ class TextEngine<
       model: this.params.model,
       messages: this.messages,
       tools: toolsWithJsonSchemas,
-      temperature,
-      topP,
-      maxTokens,
       metadata,
       request: this.effectiveRequest,
       modelOptions,
@@ -1237,6 +1262,7 @@ class TextEngine<
         },
       },
       this.middlewareCtx.context,
+      this.toolAbortSignal,
     )
 
     // Consume the async generator, yielding custom events and collecting the return value
@@ -1398,6 +1424,7 @@ class TextEngine<
         },
       },
       this.middlewareCtx.context,
+      this.toolAbortSignal,
     )
 
     // Consume the async generator, yielding custom events and collecting the return value
@@ -1869,9 +1896,6 @@ class TextEngine<
       chatOptions: {
         model: this.params.model,
         messages: this.messages,
-        temperature: postOnConfig.temperature,
-        topP: postOnConfig.topP,
-        maxTokens: postOnConfig.maxTokens,
         metadata: postOnConfig.metadata,
         modelOptions: postOnConfig.modelOptions,
         systemPrompts: postOnConfig.systemPrompts,
@@ -2351,9 +2375,6 @@ class TextEngine<
       messages: this.messages,
       systemPrompts: [...this.systemPrompts],
       tools: [...this.tools],
-      temperature: this.params.temperature,
-      topP: this.params.topP,
-      maxTokens: this.params.maxTokens,
       metadata: this.params.metadata,
       modelOptions: this.params.modelOptions,
     }
@@ -2365,9 +2386,6 @@ class TextEngine<
     this.tools = config.tools
     this.params = {
       ...this.params,
-      temperature: config.temperature,
-      topP: config.topP,
-      maxTokens: config.maxTokens,
       metadata: config.metadata,
       modelOptions: config.modelOptions,
     }
@@ -2589,10 +2607,16 @@ export function chat<
 async function* runStreamingText<TContext = unknown>(
   options: TextActivityOptions<AnyTextAdapter, undefined, true, TContext>,
 ): AsyncIterable<StreamChunk> {
-  const { adapter, middleware, context, debug, ...textOptions } = options
+  const { adapter, middleware, context, debug, mcp, ...textOptions } = options
   const model = adapter.model
   const logger = resolveDebugOption(debug)
 
+  const mcpManager = MCPManager.from(mcp)
+  const mcpTools = await mcpManager.discover()
+  if (mcpTools.length > 0) {
+    textOptions.tools = [...(textOptions.tools ?? []), ...mcpTools]
+  }
+
   const engine = new TextEngine(
     {
       adapter,
@@ -2607,8 +2631,12 @@ async function* runStreamingText<TContext = unknown>(
     logger,
   )
 
-  for await (const chunk of engine.run()) {
-    yield chunk
+  try {
+    for await (const chunk of engine.run()) {
+      yield chunk
+    }
+  } finally {
+    await mcpManager.dispose()
   }
 }
 
@@ -2645,8 +2673,15 @@ async function runAgenticStructuredOutput<
 >(
   options: TextActivityOptions<AnyTextAdapter, TSchema, boolean, TContext>,
 ): Promise<InferSchemaType<TSchema>> {
-  const { adapter, outputSchema, middleware, context, debug, ...textOptions } =
-    options
+  const {
+    adapter,
+    outputSchema,
+    middleware,
+    context,
+    debug,
+    mcp,
+    ...textOptions
+  } = options
   const model = adapter.model
   const logger = resolveDebugOption(debug)
 
@@ -2680,6 +2715,12 @@ async function runAgenticStructuredOutput<
   const nativeCombined =
     adapter.supportsCombinedToolsAndSchema?.(options.modelOptions) === true
 
+  const mcpManager = MCPManager.from(mcp)
+  const mcpTools = await mcpManager.discover()
+  if (mcpTools.length > 0) {
+    textOptions.tools = [...(textOptions.tools ?? []), ...mcpTools]
+  }
+
   const engine = new TextEngine(
     {
       adapter,
@@ -2700,9 +2741,13 @@ async function runAgenticStructuredOutput<
     logger,
   )
 
-  // Consume the stream — chunks pipe through middleware but are not yielded externally
-  for await (const _chunk of engine.run()) {
-    // intentionally empty
+  try {
+    // Consume the stream — chunks pipe through middleware but are not yielded externally
+    for await (const _chunk of engine.run()) {
+      // intentionally empty
+    }
+  } finally {
+    await mcpManager.dispose()
   }
 
   const finalizationError = engine.getFinalizationError()
@@ -2933,8 +2978,15 @@ async function* runStreamingStructuredOutputImpl<
   options: TextActivityOptions<AnyTextAdapter, TSchema, true, TContext>,
   jsonSchema: NonNullable<ReturnType<typeof convertSchemaToJsonSchema>>,
 ): StructuredOutputStreamInternal<InferSchemaType<TSchema>> {
-  const { adapter, outputSchema, middleware, context, debug, ...textOptions } =
-    options
+  const {
+    adapter,
+    outputSchema,
+    middleware,
+    context,
+    debug,
+    mcp,
+    ...textOptions
+  } = options
   const model = adapter.model
   const logger = resolveDebugOption(debug)
 
@@ -2948,6 +3000,12 @@ async function* runStreamingStructuredOutputImpl<
   const nativeCombined =
     adapter.supportsCombinedToolsAndSchema?.(options.modelOptions) === true
 
+  const mcpManager = MCPManager.from(mcp)
+  const mcpTools = await mcpManager.discover()
+  if (mcpTools.length > 0) {
+    textOptions.tools = [...(textOptions.tools ?? []), ...mcpTools]
+  }
+
   // Inputs may be UIMessages (from useChat) or ModelMessages (from server-side
   // callers). TextEngine handles the conversion uniformly.
   const engine = new TextEngine(
@@ -2969,8 +3027,12 @@ async function* runStreamingStructuredOutputImpl<
     logger,
   )
 
-  for await (const chunk of engine.run()) {
-    yield chunk
+  try {
+    for await (const chunk of engine.run()) {
+      yield chunk
+    }
+  } finally {
+    await mcpManager.dispose()
   }
 
   // Schema validation for the streaming variant remains the consumer's

package/src/activities/chat/mcp/manager.ts

@@ -0,0 +1,85 @@
+import type { ServerTool } from '../tools/tool-definition'
+import type { ChatMCPOptions, MCPToolSource } from './types'
+
+export class MCPDuplicateToolNameError extends Error {
+  constructor(public readonly toolName: string) {
+    super(
+      `Duplicate MCP tool name "${toolName}" in chat({ mcp.clients }). ` +
+        `Set a unique \`prefix\` on one of the MCP clients (or use a pool, ` +
+        `which auto-prefixes) to disambiguate.`,
+    )
+    this.name = 'MCPDuplicateToolNameError'
+  }
+}
+
+/**
+ * Encapsulates MCP tool discovery + connection lifecycle for chat().
+ * Built from chat()'s `mcp` option; runners only call `discover()` then
+ * `dispose()`. A manager built from `undefined` is an inert no-op
+ * (`discover()` → `[]`, `dispose()` → no-op), so runners need no branching.
+ */
+export class MCPManager {
+  static from(options: ChatMCPOptions | undefined): MCPManager {
+    return new MCPManager(options)
+  }
+
+  readonly #sources: ReadonlyArray<MCPToolSource>
+  readonly #shouldClose: boolean
+  readonly #lazyTools: boolean
+  readonly #onDiscoveryError?: (
+    error: unknown,
+    source: MCPToolSource,
+  ) => void | Promise<void>
+
+  private constructor(options: ChatMCPOptions | undefined) {
+    this.#sources = options?.clients ?? []
+    // default 'close'; only 'keep-alive' disables closing
+    this.#shouldClose = options ? options.connection !== 'keep-alive' : false
+    this.#lazyTools = options?.lazyTools ?? false
+    this.#onDiscoveryError = options?.onDiscoveryError
+  }
+
+  /**
+   * Discover + merge tools from all sources. Throws on a fatal discovery error
+   * (no `onDiscoveryError`, or it re-threw) or a duplicate tool name; in that
+   * case it first closes any connected sources when the policy is 'close'.
+   */
+  async discover(): Promise<Array<ServerTool>> {
+    if (this.#sources.length === 0) return []
+    try {
+      const settled = await Promise.allSettled(
+        this.#sources.map((s) => s.tools({ lazy: this.#lazyTools })),
+      )
+      const tools: Array<ServerTool> = []
+      const zipped = this.#sources.map(
+        (source, i) => [source, settled[i]] as const,
+      )
+      for (const [source, result] of zipped) {
+        if (result === undefined) continue
+        if (result.status === 'fulfilled') {
+          tools.push(...result.value)
+        } else if (this.#onDiscoveryError) {
+          // throw/reject inside handler ⇒ propagate (fail-fast); return ⇒ skip
+          await this.#onDiscoveryError(result.reason, source)
+        } else {
+          throw result.reason
+        }
+      }
+      const seen = new Set<string>()
+      for (const t of tools) {
+        if (seen.has(t.name)) throw new MCPDuplicateToolNameError(t.name)
+        seen.add(t.name)
+      }
+      return tools
+    } catch (err) {
+      await this.dispose() // cleanup-on-failure (no-op if keep-alive)
+      throw err
+    }
+  }
+
+  /** Close sources iff policy is 'close'. Idempotent; never throws. */
+  async dispose(): Promise<void> {
+    if (!this.#shouldClose || this.#sources.length === 0) return
+    await Promise.allSettled(this.#sources.map((s) => s.close()))
+  }
+}