@mcpmesh/sdk 1.4.1 → 2.0.0-beta.1

package/dist/sse-stream.js

@@ -0,0 +1,173 @@
+/**
+ * SSE streaming helper for Express route handlers.
+ *
+ * Pipes any ``AsyncIterable<string>`` to an Express ``Response`` as
+ * ``text/event-stream``. Designed to be called from inside a ``mesh.route``
+ * handler — for example, to forward chunks from a remote streaming tool to
+ * a browser client via SSE.
+ *
+ * Wire format mirrors the Python ``mesh.route`` SSE adapter:
+ * - ``data: <chunk>\n\n`` per item
+ * - ``data: [DONE]\n\n`` terminator on normal completion
+ * - ``event: error\ndata: <json>\n\n`` on per-chunk error
+ *
+ * @example
+ * ```typescript
+ * import { mesh } from "@mcpmesh/sdk";
+ *
+ * app.post("/plan", mesh.route(["trip_planner"], async (req, res, { trip_planner }) => {
+ *   if (!trip_planner) return res.status(503).end();
+ *   await mesh.sseStream(res, trip_planner.stream(req.body));
+ * }));
+ * ```
+ */
+const SSE_HEADERS = {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache",
+    Connection: "keep-alive",
+    // Disable nginx response buffering so chunks reach the browser immediately
+    "X-Accel-Buffering": "no",
+};
+/**
+ * Format a single chunk as SSE ``data:`` lines per spec.
+ *
+ * Each newline in the chunk becomes its own ``data:`` line; the record is
+ * terminated by a blank line. Empty chunks still emit a single ``data:``
+ * line so consumers see a heartbeat-style event (matches Python behavior).
+ */
+function frameChunkAsSSE(chunk) {
+    // splitlines() in Python splits on any line boundary; in JS we normalize
+    // CRLF to LF first then split on \n. An empty chunk still emits one frame.
+    const normalized = chunk.replace(/\r\n/g, "\n");
+    const lines = normalized === "" ? [""] : normalized.split("\n");
+    return lines.map((l) => `data: ${l}\n`).join("") + "\n";
+}
+/**
+ * Pipe an ``AsyncIterable<string>`` to an Express ``Response`` as SSE.
+ *
+ * Sets the standard SSE headers, writes one ``data: <chunk>\n\n`` frame per
+ * item from the iterable, and terminates with ``data: [DONE]\n\n``. On
+ * per-chunk error (e.g. the upstream stream throws), writes
+ * ``event: error\ndata: <json>\n\n`` and ends the response.
+ *
+ * Resolves when the response has been fully written. Callers do not need to
+ * call ``res.end()`` themselves.
+ *
+ * If the consumer disconnects mid-stream (``res.writableEnded``), iteration
+ * stops cleanly via the iterable's ``return()`` method (so the upstream
+ * proxy stream's ``finally`` block can release its underlying reader).
+ *
+ * @param res - Express response object
+ * @param source - Async iterable yielding strings
+ */
+export async function sseStream(res, source) {
+    // Set headers if not already sent. Use writeHead for a single atomic flush
+    // so the browser sees the full set immediately (some proxies buffer until
+    // headers arrive). If the caller already wrote headers we just continue.
+    if (!res.headersSent) {
+        for (const [k, v] of Object.entries(SSE_HEADERS)) {
+            res.setHeader(k, v);
+        }
+        // Some Express versions need an explicit flushHeaders() to commit before
+        // the first data frame; call it if available.
+        if (typeof res.flushHeaders === "function") {
+            res.flushHeaders();
+        }
+    }
+    // Track whether end() has been called so we never double-end (which would
+    // throw "ERR_STREAM_WRITE_AFTER_END" on Node). ``writable`` flips to false
+    // when further writes will fail (e.g. socket closed) but we still want to
+    // call res.end() exactly once for cleanup.
+    let endCalled = false;
+    let writable = true;
+    const safeEnd = () => {
+        if (endCalled)
+            return;
+        endCalled = true;
+        try {
+            res.end();
+        }
+        catch {
+            // ignore — response may already be torn down
+        }
+    };
+    const safeWrite = (data) => {
+        if (!writable)
+            return false;
+        if (res.writableEnded || res.destroyed) {
+            writable = false;
+            return false;
+        }
+        try {
+            return res.write(data);
+        }
+        catch {
+            writable = false;
+            return false;
+        }
+    };
+    const iterator = source[Symbol.asyncIterator]();
+    try {
+        while (true) {
+            const { value, done } = await iterator.next();
+            if (done)
+                break;
+            if (typeof value !== "string") {
+                // v1 supports str only — surface a structured error and stop
+                const errPayload = JSON.stringify({
+                    error: `sseStream: expected string chunk, got ${typeof value}`,
+                    type: "TypeError",
+                });
+                safeWrite(`event: error\ndata: ${errPayload}\n\n`);
+                safeEnd();
+                // best-effort cleanup of upstream
+                if (typeof iterator.return === "function") {
+                    try {
+                        await iterator.return();
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+                return;
+            }
+            const wroteOk = safeWrite(frameChunkAsSSE(value));
+            if (!wroteOk) {
+                // Consumer disconnected (or write threw) — clean up upstream and end.
+                if (typeof iterator.return === "function") {
+                    try {
+                        await iterator.return();
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+                safeEnd();
+                return;
+            }
+        }
+        safeWrite("data: [DONE]\n\n");
+        safeEnd();
+    }
+    catch (err) {
+        const errPayload = JSON.stringify({
+            error: err instanceof Error ? err.message : String(err),
+            type: err instanceof Error ? err.constructor.name : "Error",
+        });
+        safeWrite(`event: error\ndata: ${errPayload}\n\n`);
+        safeEnd();
+        // Release the upstream iterator if the failure originated outside the
+        // iterator itself (e.g. safeWrite threw). Without this, an upstream
+        // proxy.stream() generator's finally block — which cancels the
+        // OkHttp/fetch reader — never runs until GC, leaking the connection.
+        if (typeof iterator.return === "function") {
+            try {
+                await iterator.return();
+            }
+            catch {
+                /* upstream cleanup is best-effort */
+            }
+        }
+    }
+}
+//# sourceMappingURL=sse-stream.js.map

package/dist/sse-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-stream.js","sourceRoot":"","sources":["../src/sse-stream.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -37,6 +37,76 @@ export interface MediaParamMeta {
  */
 export declare function mediaParam(mediaType?: string): z.ZodOptional<z.ZodString>;
 export type { JsAgentHandle, JsMeshEvent, JsAgentSpec, JsToolSpec, JsDependencySpec, JsLlmAgentSpec, JsLlmToolInfo, JsLlmProviderInfo, } from "@mcpmesh/core";
+/**
+ * Type marker for DDDI injection of a long-running-task handle (Phase 1
+ * — MeshJob substrate).
+ *
+ * Used as a parameter-position type annotation on a tool registered with
+ * `agent.addTool({ task: true, ... })` (producer) or `mesh.route(...)`
+ * with a `task=true` dependency (consumer). The mesh runtime injects:
+ *
+ * - On the **producer side** (a tool decorated `{ task: true }` invoked
+ *   via the inbound job-dispatch path or claim worker): a
+ *   `JobController` exposing
+ *   `await job.updateProgress(...)` /
+ *   `await job.complete(result)` / `await job.fail(error)`.
+ *
+ * - On the **consumer side** (a function depending on a remote
+ *   `task=true` capability): a submitter that returns a `JobProxy`
+ *   exposing `await proxy.wait(timeoutSecs?)` / `await proxy.status()`
+ *   / `await proxy.cancel(reason?)`.
+ *
+ * A MeshJob parameter is **orthogonal** to positional MeshTool slots
+ * per `MESHJOB_DDDI_CONTRACT.md` — it does not consume a positional
+ * dependency-injection index.
+ *
+ * If a function declaring a MeshJob param is invoked as a regular
+ * synchronous tool call (no `X-Mesh-Job-Id` header, no claim path),
+ * the runtime injects `null` for the slot. Producer code SHOULD treat
+ * `null` as a fast path with no progress reporting.
+ *
+ * The type itself is structurally minimal because TypeScript erases
+ * structural types at runtime; the DDDI resolver records signature
+ * positions explicitly when the SDK builds the tool definition (see
+ * `__tests__/resolver-meshjob.spec.ts`).
+ *
+ * @example Producer
+ * ```typescript
+ * agent.addTool({
+ *   name: "plan_trip",
+ *   capability: "plan_trip",
+ *   task: true,
+ *   parameters: z.object({ userId: z.string() }),
+ *   dependencies: [{ capability: "weather" }],
+ *   meshJobParamIndex: 2,  // signature position of `job` below
+ *   execute: async (
+ *     { userId },
+ *     weather: McpMeshTool | null = null,
+ *     job: MeshJob | null = null,
+ *   ) => {
+ *     await job?.updateProgress(0.1, "checking weather");
+ *     const w = await weather?.({ city: "PDX" });
+ *     await job?.updateProgress(0.9, "done");
+ *     return { itinerary: w };
+ *   },
+ * });
+ * ```
+ */
+export interface MeshJob {
+    jobId?: string;
+    updateProgress?(progress: number, message?: string): Promise<void>;
+    complete?(result: unknown): Promise<void>;
+    fail?(error: string): Promise<void>;
+    submit?(payload?: Record<string, unknown>, options?: {
+        maxDuration?: number;
+        maxRetries?: number;
+        totalDeadline?: number;
+        ownerInstanceId?: string;
+    }): Promise<MeshJob>;
+    wait?(timeoutSecs?: number): Promise<unknown>;
+    status?(): Promise<Record<string, unknown>>;
+    cancel?(reason?: string): Promise<void>;
+}
 /**
  * Dependency specification for mesh tool DI.
  *
@@ -69,6 +139,16 @@ export type DependencySpec = string | {
     tags?: TagSpec[];
     /** Version constraint (e.g., ">=2.0.0") */
     version?: string;
+    /** Issue #547: optional Zod schema describing the expected provider response.
+     * When set, the registry uses the canonical hash to filter producers
+     * whose output schema matches under {@link matchMode}. Backward compat:
+     * if omitted, no schema check is performed.
+     */
+    expectedSchema?: z.ZodType<unknown>;
+    /** Issue #547: how to compare producer output schema against
+     * {@link expectedSchema}. Defaults to "subset" when expectedSchema is set.
+     */
+    matchMode?: "subset" | "strict";
 };
 /**
  * Normalized dependency specification (after processing).
@@ -77,6 +157,13 @@ export interface NormalizedDependency {
     capability: string;
     tags: TagSpec[];
     version?: string;
+    /** Issue #547: raw JSON Schema (post-zodToJsonSchema) for the expected
+     * dependency response. Normalization is deferred to the heartbeat pipeline
+     * to keep decorator-time work cheap and consistent with Python parity.
+     */
+    expectedSchemaRaw?: object;
+    /** Issue #547: schema match mode ("subset" or "strict"). */
+    matchMode?: "subset" | "strict";
 }
 /**
  * Resolved dependency info from registry.
@@ -155,6 +242,42 @@ export interface DependencyKwargs {
     /** Max response body size in bytes. Defaults to 10MB (10485760) */
     maxResponseSize?: number;
 }
+/**
+ * Per-tool A2A bridge configuration (issue #917).
+ *
+ * When set on a `MeshToolDef`, the framework constructs a per-config
+ * `A2AClient` and injects it into the user's `execute` function as the
+ * LAST positional argument (after the standard dependency proxies and
+ * — for `task: true` tools — after the `JobController`). Multiple
+ * tools sharing the same `(url, skillId, auth, timeoutMs)` tuple share
+ * one cached client so the underlying undici connection pool is
+ * amortised.
+ *
+ * The presence of `a2aConfig` ALSO opts the tool into auto-tag
+ * injection: at heartbeat-build time the framework appends the
+ * surrounding agent name to the tool's tags array so downstream
+ * resolvers can pin a specific bridge via the tag selector. Mirrors
+ * Python's `@mesh.a2a_consumer` and Java's `@A2AConsumer`.
+ */
+export interface MeshA2AConfig {
+    /** Required: A2A endpoint URL. Trailing slashes are stripped. */
+    url: string;
+    /** Optional: skill ID to invoke. Defaults to the tool's `capability`. */
+    skillId?: string;
+    /** Optional: bearer credential (instance or `{ tokenEnv }` / `{ token }` config). */
+    auth?: {
+        token?: string;
+        tokenEnv?: string;
+    } | {
+        authorizationHeader: () => string;
+    };
+    /** Optional: per-call deadline (ms). Default 30_000. */
+    timeoutMs?: number;
+    /** Optional: initial backoff between `tasks/get` polls (ms). Default 500. */
+    pollIntervalMs?: number;
+    /** Optional: cap on the backoff between polls (ms). Default 2_000. */
+    pollIntervalMaxMs?: number;
+}
 /**
  * Tool definition for MeshAgent.
  */
@@ -171,6 +294,143 @@ export interface MeshToolDef<T extends z.ZodType = z.ZodType> {
     version?: string;
     /** Zod schema for input parameters */
     parameters: T;
+    /**
+     * Issue #547: Zod schema for the tool's return value.
+     *
+     * Optional, opt-in. When provided, the SDK extracts and normalizes the
+     * output schema and ships it to the registry alongside the input schema
+     * so consumers can match producers by canonical schema hash.
+     *
+     * Zod cannot infer the return type from the handler signature (unlike
+     * Python's reflection on Pydantic return annotations), so users must
+     * provide this explicitly.
+     */
+    outputSchema?: z.ZodType<unknown>;
+    /**
+     * Issue #547 Phase 4: per-tool override for the schema verdict policy.
+     *
+     * When `true` (default), a BLOCK verdict from the schema normalizer
+     * refuses agent startup. Set to `false` as a producer-side escape hatch
+     * to demote BLOCK to WARN for this specific tool. Wins even when the
+     * cluster-wide `MCP_MESH_SCHEMA_STRICT=true` env var is set (which
+     * otherwise promotes WARN to BLOCK across all tools).
+     */
+    outputSchemaStrict?: boolean;
+    /**
+     * Phase 1 MeshJob substrate: mark this tool as long-running.
+     *
+     * When `true`, producers advertise `task=true` in their tool
+     * metadata so consumers know to invoke this capability via job
+     * semantics (`mesh.MeshJob.submit(...) → wait/poll`) rather than as
+     * a regular synchronous `tools/call`. The actual job-context binding
+     * happens at inbound call time via the dispatch wrapper.
+     *
+     * Constraints (validated at `addTool` time):
+     *
+     *   - `execute` MUST be an `async` function (long-running tools need
+     *     a Promise-based control flow to drive `MeshJob.updateProgress()`,
+     *     cancellation, and outbound polling). Sync `execute` raises a
+     *     clear error at registration.
+     *
+     * Default: `false` (regular synchronous tool). See
+     * `MESHJOB_DESIGN.org` "Producer-side flow".
+     */
+    task?: boolean;
+    /**
+     * Phase 1 MeshJob substrate (producer-side): signature position of
+     * the `MeshJob` parameter on the user's `execute` function.
+     *
+     * When set on a `task: true` tool, the runtime injects a
+     * `JobController` at this position when the tool is invoked under
+     * a job context (claim path or inbound call carrying
+     * `X-Mesh-Job-Id`). When the tool is invoked synchronously without
+     * a job context, the runtime injects `null` per
+     * `MESHJOB_DDDI_CONTRACT.md`.
+     *
+     * Position 0 is reserved for `args`; deps start at 1. The
+     * `MeshJob` slot is orthogonal to MeshTool positional indexing —
+     * MeshTool deps skip the `meshJobParamIndex` position and shift
+     * accordingly. See `resolver-meshjob.ts` for the contract test
+     * seam.
+     *
+     * Producer example with one MeshTool dep and a MeshJob slot:
+     * ```ts
+     * agent.addTool({
+     *   task: true,
+     *   dependencies: ["weather"],
+     *   meshJobParamIndex: 2,  // job at sig pos 2
+     *   execute: async (
+     *     { city },
+     *     weather: McpMeshTool | null = null,  // dep at sig pos 1
+     *     job: MeshJob | null = null,           // controller at sig pos 2
+     *   ) => { ... },
+     * });
+     * ```
+     */
+    meshJobParamIndex?: number;
+    /**
+     * Phase 1 MeshJob substrate (consumer-side): index into
+     * `dependencies` whose proxy should be injected as a
+     * `MeshJobSubmitter` (returns a `JobProxy`) instead of a regular
+     * `McpMeshTool` proxy.
+     *
+     * Use this when the consumer wants to call a remote `task: true`
+     * capability via job semantics (submit + poll/wait) rather than as
+     * a regular synchronous `tools/call`. The user function receives a
+     * `MeshJob`-typed handle at the dep's positional slot.
+     *
+     * Consumer example:
+     * ```ts
+     * agent.addTool({
+     *   name: "commission_report",
+     *   dependencies: ["generate_report"],
+     *   meshJobDepIndex: 0,  // generate_report is task=true
+     *   execute: async ({ userId }, generateReport: MeshJob | null = null) => {
+     *     const proxy = await generateReport!.submit(
+     *       { user_id: userId, sections: ["intro"] },
+     *       { maxDuration: 60 },
+     *     );
+     *     return await proxy.wait(60);
+     *   },
+     * });
+     * ```
+     */
+    meshJobDepIndex?: number;
+    /**
+     * Issue #894: per-tool retry-eligible exception whitelist.
+     *
+     * When a `task: true` handler raises an Error whose constructor matches
+     * one of the entries (`err instanceof cls`), the dispatch wrapper calls
+     * `controller.releaseLease(reason)` instead of `controller.fail(reason)`.
+     * The registry then resets `owner_instance_id` so a peer replica can
+     * re-claim within ~5s — useful for transient failures (network blips,
+     * upstream unavailable) where the next attempt on a different replica
+     * is likely to succeed.
+     *
+     * Constraints (validated at `addTool` time):
+     *
+     *   - requires `task: true` (no-op for synchronous tools — non-job
+     *     handlers don't have a controller, so retry has no meaning);
+     *   - entries must be Error constructor classes (functions); anything
+     *     else throws at registration.
+     *
+     * Default: `undefined` (no retry-eligible exceptions; all raises mark
+     * the row failed). Empty array is equivalent.
+     *
+     * @example
+     * ```ts
+     * agent.addTool({
+     *   task: true,
+     *   retryOn: [TransientUpstreamError, AbortError],
+     *   execute: async (args, job: MeshJob | null = null) => {
+     *     // If this throws TransientUpstreamError, the registry will
+     *     // hand the job to a peer replica within ~5s.
+     *     return await callFlakeyApi(args);
+     *   },
+     * });
+     * ```
+     */
+    retryOn?: Array<new (...args: unknown[]) => Error>;
     /**
      * Dependencies required by this tool.
      * Injected positionally as McpMeshTool params after args.
@@ -192,6 +452,13 @@ export interface MeshToolDef<T extends z.ZodType = z.ZodType> {
      * Supports duplicate capabilities with different settings.
      */
     dependencyKwargs?: DependencyKwargs[];
+    /**
+     * Issue #917: A2A bridge configuration. When set, the framework
+     * constructs a cached `A2AClient` and injects it at the trailing
+     * positional slot of `execute` (after deps + JobController). Also
+     * opts the tool into consumer-name auto-tag injection.
+     */
+    a2aConfig?: MeshA2AConfig;
     /**
      * Tool implementation.
      *
@@ -225,7 +492,7 @@ export interface MeshToolDef<T extends z.ZodType = z.ZodType> {
      * }
      * ```
      */
-    execute: (args: z.infer<T>, ...deps: (McpMeshTool | null)[]) => Promise<unknown> | unknown;
+    execute: (args: z.infer<T>, ...deps: (McpMeshTool | MeshJob | null)[]) => Promise<unknown> | unknown;
 }
 /**
  * Proxy for calling remote MCP tools.
@@ -261,6 +528,27 @@ export interface McpMeshTool {
     callTool(toolName: string, args?: Record<string, unknown>, options?: {
         headers?: Record<string, string>;
     }): Promise<unknown>;
+    /**
+     * Stream text chunks from a remote ``Stream[str]`` tool.
+     *
+     * Returns an async iterable that yields each chunk the producer emits via
+     * MCP ``notifications/progress``. The final result message ends the stream
+     * (its content is NOT yielded — iterate to get the whole stream).
+     *
+     * NOTE: If the producer doesn't actually emit progress notifications, the
+     * underlying SSE response will only contain the final ``result`` and this
+     * iterable will yield nothing.
+     *
+     * @example
+     * ```typescript
+     * for await (const chunk of planner.stream({ destination: "Tokyo" })) {
+     *   process.stdout.write(chunk);
+     * }
+     * ```
+     */
+    stream(args?: Record<string, unknown>, options?: {
+        headers?: Record<string, string>;
+    }): AsyncIterable<string>;
     /**
      * Get the endpoint URL for this dependency.
      */
@@ -291,26 +579,49 @@ export interface ToolMeta {
     tags: string[];
     description: string;
     inputSchema?: string;
+    /** Issue #547: raw JSON Schema (post-zodToJsonSchema) for return type. */
+    outputSchemaRaw?: object;
+    /** Issue #547 Phase 4: per-tool override for the schema verdict policy
+     * (default true). When false, a BLOCK verdict for this tool is demoted
+     * to WARN instead of refusing startup. */
+    outputSchemaStrict?: boolean;
     /** Normalized dependencies for this tool */
     dependencies: NormalizedDependency[];
     /** Per-dependency configuration indexed by position (matches dependencies array) */
     dependencyKwargs?: DependencyKwargs[];
+    /** Phase 1 MeshJob substrate: producer flag advertising this tool as
+     * long-running so consumers invoke via job semantics. See
+     * MeshToolDef.task for full semantics. */
+    task?: boolean;
+    /** Phase 1 MeshJob substrate: producer-side signature position of
+     * the MeshJob param. Used by the inbound dispatch wrapper to inject
+     * a JobController when running as a job. */
+    meshJobParamIndex?: number;
+    /** Phase 1 MeshJob substrate: consumer-side index into dependencies
+     * whose slot should hold a MeshJobSubmitter (instead of a regular
+     * McpMeshTool proxy). */
+    meshJobDepIndex?: number;
+    /** Issue #917: A2A bridge marker — when true, the heartbeat-build
+     * pass appends the surrounding agent name to the tool's tags before
+     * the registry sees them. */
+    a2aConsumer?: boolean;
+    /** Issue #917: agent name captured at addTool time so the heartbeat
+     * pass injects the correct value (in case the agent is renamed via
+     * env between addTool and heartbeat). */
+    a2aAgentName?: string;
 }
 /**
  * LLM provider specification.
- * Can be a direct LiteLLM provider string or mesh delegation config.
+ * Mesh delegation only — describes the capability/tag filter used to
+ * discover an ``@mesh.llm_provider`` in the mesh.
  *
  * @example
  * ```typescript
- * // Direct LiteLLM provider
- * provider: "claude"
- * provider: "openai"
- *
  * // Mesh delegation (discover LLM provider via mesh)
  * provider: { capability: "llm", tags: ["+claude"] }
  * ```
  */
-export type LlmProviderSpec = string | {
+export type LlmProviderSpec = {
     /** Capability name to discover in mesh */
     capability: string;
     /** Tags for filtering (e.g., ["+claude", "-deprecated"]) */
@@ -346,7 +657,7 @@ export interface LlmMeta {
     toolCalls: LlmToolCall[];
     /** Model used for generation */
     model: string;
-    /** Provider used (litellm provider name or mesh agent ID) */
+    /** Provider used (e.g., ``mesh:<endpoint>`` or ``mesh:<capability>``) */
     provider: string;
 }
 /**
@@ -476,7 +787,7 @@ export interface MeshLlmConfig<TParams extends z.ZodType, TReturns extends z.Zod
     tags?: string[];
     /** Version of this capability. Defaults to "1.0.0" */
     version?: string;
-    /** LLM provider - direct string (LiteLLM) or mesh delegation object */
+    /** LLM provider — mesh-delegation spec (capability + tag filter) */
     provider: LlmProviderSpec;
     /** Model override (e.g., "anthropic/claude-sonnet-4-5") */
     model?: string;
@@ -567,6 +878,37 @@ export interface LlmAgent<T = string> {
      * @param prompt - New system prompt (inline or "file://path.hbs")
      */
     setSystemPrompt(prompt: string): void;
+    /**
+     * Stream the assistant's text response chunk-by-chunk from a streaming
+     * mesh-delegated provider (Python's ``@mesh.llm_provider`` exposes a
+     * ``process_chat_stream`` MCP tool tagged ``ai.mcpmesh.stream``).
+     *
+     * **Tag opt-in (REQUIRED):** TypeScript users must explicitly add
+     * ``"ai.mcpmesh.stream"`` to their provider tags to discriminate the
+     * streaming variant from the buffered one. Python's ``@mesh.llm`` does
+     * this automatically based on the function's ``Stream[str]`` return type;
+     * TS does not perform that return-type analysis at decorator time, so the
+     * opt-in must be explicit:
+     *
+     * ```ts
+     * server.addTool(mesh.llm({
+     *   name: "chat_stream",
+     *   provider: { capability: "llm", tags: ["+claude", "ai.mcpmesh.stream"] },
+     *   parameters: z.object({ message: z.string() }),
+     *   execute: async ({ message }, { llm }) => {
+     *     for await (const chunk of llm.stream(message)) {
+     *       process.stdout.write(chunk);
+     *     }
+     *     return "ok";
+     *   },
+     * }));
+     * ```
+     *
+     * @param message - User message (string or multi-turn array)
+     * @param options - Same runtime overrides as the callable form
+     * @returns AsyncIterable of text chunks (final accumulated result is NOT yielded)
+     */
+    stream(message: LlmMessageInput, options?: LlmCallOptions): AsyncIterable<string>;
 }
 /**
  * Context merge mode for runtime context override.