@mcpmesh/sdk 1.3.4 → 2.0.0-beta.1

package/dist/a2a/producer/dispatcher.js

@@ -0,0 +1,896 @@
+import { randomUUID } from "node:crypto";
+import { JobProxy } from "@mcpmesh/core";
+import { A2A_CANCELED, A2A_COMPLETED, A2A_FAILED, A2A_WORKING, fromMesh, isTerminal, meshStatusOf, } from "./state-translator.js";
+/** JSON-RPC: Parse error (request body is not valid JSON). Spec §4.1. */
+export const JSONRPC_PARSE_ERROR = -32700;
+/** JSON-RPC: Invalid Request (well-formed JSON but missing `method` field). Spec §4.1. */
+export const JSONRPC_INVALID_REQUEST = -32600;
+/** JSON-RPC: Method not found (unknown `tasks/*` verb). Spec §4.1. */
+export const JSONRPC_METHOD_NOT_FOUND = -32601;
+/** JSON-RPC: Invalid params (missing or unknown task id). Spec §4.4. */
+export const JSONRPC_INVALID_PARAMS = -32602;
+/**
+ * Build an Express request handler that dispatches `POST {path}` requests
+ * for a single surface.
+ *
+ * Routes JSON-RPC envelopes that return a single response body
+ * (`tasks/send`, `tasks/get`, `tasks/cancel`). SSE verbs
+ * (`tasks/sendSubscribe`, `tasks/resubscribe`) are dispatched by a
+ * sibling middleware ({@link buildSseDispatcherMiddleware}) that the
+ * mount wires in front of this one — when the SSE middleware sees an
+ * SSE-eligible method it consumes the request; otherwise it calls
+ * `next()` and execution falls through here.
+ */
+export function buildDispatcherMiddleware(deps) {
+    const { surface, handler, taskStore, routeRegistry, jobSubmitterProvider } = deps;
+    return async function a2aDispatcher(req, res) {
+        // Spec §4.1: malformed body → HTTP 400 + JSON-RPC -32700. Express's
+        // `express.json()` middleware should have parsed the body; defensively
+        // handle the case where it wasn't installed by checking for a missing
+        // body object (req.body will be `undefined` then).
+        const body = req.body;
+        if (body === undefined || body === null) {
+            writeJsonRpcParseErrorHttp400(res, "Parse error: request body is empty or not parsed (did you install express.json()?)");
+            return;
+        }
+        if (typeof body !== "object" || Array.isArray(body)) {
+            writeJsonRpcParseErrorHttp400(res, "Parse error: request body must be a JSON-RPC object");
+            return;
+        }
+        const envelope = body;
+        const reqId = extractRequestId(envelope);
+        const method = envelope["method"];
+        if (typeof method !== "string" || method.length === 0) {
+            // Spec §4.1: well-formed JSON missing the required `method` member is
+            // an Invalid Request (-32600), NOT Method not found (-32601). Without
+            // this guard the default branch would emit a misleading
+            // "Method not implemented: 'null'" — the bug surfaced in issue #934
+            // when the Java body-read path silently dropped the parsed body.
+            writeJsonRpc(res, jsonRpcError(reqId, JSONRPC_INVALID_REQUEST, "Invalid Request: 'method' field is required and must be a string"));
+            return;
+        }
+        const params = readParams(envelope["params"]);
+        switch (method) {
+            case "tasks/send":
+                await handleTasksSend(req, res, reqId, params, {
+                    surface,
+                    handler,
+                    taskStore,
+                    routeRegistry,
+                    jobSubmitterProvider,
+                });
+                return;
+            case "tasks/get":
+                await handleTasksGet(res, reqId, params, taskStore);
+                return;
+            case "tasks/cancel":
+                await handleTasksCancel(res, reqId, params, taskStore);
+                return;
+            case "tasks/sendSubscribe":
+            case "tasks/resubscribe":
+                // SSE methods are handled by the sibling SSE-middleware. If we
+                // see them here it means the SSE middleware fell through — most
+                // commonly because the client did not send `Accept: text/event-stream`.
+                // Surface a clear error matching Java's MeshA2ADispatcher.
+                writeJsonRpc(res, jsonRpcError(reqId, JSONRPC_METHOD_NOT_FOUND, `Method '${method}' requires an SSE-capable client. ` +
+                    `Set 'Accept: text/event-stream' or use a streaming HTTP client.`));
+                return;
+            default:
+                writeJsonRpc(res, jsonRpcError(reqId, JSONRPC_METHOD_NOT_FOUND, `Method not implemented: '${method}'. ` +
+                    `Supported A2A v1.0 methods: tasks/send, tasks/get, tasks/cancel, tasks/sendSubscribe, tasks/resubscribe.`));
+                return;
+        }
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────
+// tasks/send
+// ─────────────────────────────────────────────────────────────────────────
+async function handleTasksSend(_req, res, reqId, params, deps) {
+    // Spec §4.2: extract (task_id, session_id, message).
+    let taskId = stringFromParams(params, "id");
+    if (!taskId) {
+        taskId = randomUUID();
+    }
+    let sessionId = stringFromParams(params, "sessionId");
+    if (!sessionId) {
+        sessionId = taskId;
+    }
+    const message = mapFromParams(params, "message");
+    // Spec §4.3: duplicate in-flight task_id → -32602 already in use.
+    // Terminal entries within the eviction window are also rejected.
+    // Atomic reservation — closes the race between two concurrent
+    // tasks/send requests with the same id (the pre-check + handler
+    // await yields control, so a separate `contains()` then `put()`
+    // would let both slip through).
+    const reserved = deps.taskStore.reserveTask(taskId, {
+        sessionId,
+        requestMessage: hasOwn(message) ? message : undefined,
+        jobProxy: null,
+    });
+    if (!reserved) {
+        writeJsonRpc(res, jsonRpcError(reqId, JSONRPC_INVALID_PARAMS, `A2A task id '${taskId}' is already in use`));
+        return;
+    }
+    // Resolve dependencies the same way mesh.route() does — via the shared
+    // RouteRegistry. The surface registered a synthetic route at mount time
+    // (see mount.ts); resolved McpMeshTool proxies surface here keyed by
+    // capability name.
+    const resolvedDeps = deps.routeRegistry.getDependenciesForRoute(deps.surface.routeId);
+    // Ensure every declared capability key is present (null when unresolved)
+    // — the user's destructure shouldn't crash on a partially-resolved
+    // dependency graph.
+    for (const dep of deps.surface.dependencies) {
+        if (resolvedDeps[dep.capability] === undefined) {
+            resolvedDeps[dep.capability] = null;
+        }
+    }
+    const jobSubmitter = deps.jobSubmitterProvider
+        ? deps.jobSubmitterProvider()
+        : null;
+    let handlerResult;
+    try {
+        handlerResult = await deps.handler(resolvedDeps, message, jobSubmitter);
+    }
+    catch (err) {
+        // Spec §4.3 "Response — handler raised": exceptions become
+        // state=failed Tasks, NOT JSON-RPC errors. Upgrade the placeholder
+        // reservation to a terminal failed envelope.
+        const errorText = errorTextOf(err);
+        const envelope = buildFailedTask(taskId, sessionId, message, errorText);
+        deps.taskStore.put(taskId, {
+            sessionId,
+            requestMessage: hasOwn(message) ? message : undefined,
+            terminalEnvelope: envelope,
+            terminalAt: Date.now(),
+            jobProxy: null,
+        });
+        writeJsonRpc(res, jsonRpcSuccess(reqId, envelope));
+        return;
+    }
+    // Spec §4.3 long-running branch: handler returned a JobProxy →
+    // park the task and respond with state=working immediately. The
+    // client polls tasks/get / tasks/sendSubscribe for progress and
+    // the terminal artifact.
+    if (isJobProxy(handlerResult)) {
+        const envelope = buildWorkingTask(taskId, sessionId, message);
+        parkLongRunning(deps.taskStore, taskId, sessionId, message, handlerResult);
+        writeJsonRpc(res, jsonRpcSuccess(reqId, envelope));
+        return;
+    }
+    // Sync path: handler returned a value → state=completed envelope.
+    // Upgrade the placeholder reservation to the terminal record.
+    const envelope = buildCompletedTask(taskId, sessionId, message, handlerResult);
+    deps.taskStore.put(taskId, {
+        sessionId,
+        requestMessage: hasOwn(message) ? message : undefined,
+        terminalEnvelope: envelope,
+        terminalAt: Date.now(),
+        jobProxy: null,
+    });
+    writeJsonRpc(res, jsonRpcSuccess(reqId, envelope));
+}
+// ─────────────────────────────────────────────────────────────────────────
+// tasks/get
+// ─────────────────────────────────────────────────────────────────────────
+async function handleTasksGet(res, reqId, params, taskStore) {
+    const taskId = stringFromParams(params, "id");
+    if (!taskId) {
+        writeJsonRpc(res, jsonRpcError(reqId, JSONRPC_INVALID_PARAMS, "Invalid params: 'id' is required for tasks/get"));
+        return;
+    }
+    const record = taskStore.get(taskId);
+    if (!record) {
+        writeJsonRpc(res, jsonRpcError(reqId, JSONRPC_INVALID_PARAMS, `Unknown task id: ${taskId}`));
+        return;
+    }
+    if (record.terminalEnvelope) {
+        writeJsonRpc(res, jsonRpcSuccess(reqId, record.terminalEnvelope));
+        return;
+    }
+    // Non-terminal record: pull live status from the parked JobProxy.
+    // Per spec §4.4 "transient unreachability": if status() throws we
+    // return state=working with the error text in status.message rather
+    // than a JSON-RPC error — the registry's transient failure isn't
+    // authoritative evidence the job is dead.
+    const envelope = await buildTaskFromLiveStatus(taskStore, taskId, record);
+    writeJsonRpc(res, jsonRpcSuccess(reqId, envelope));
+}
+// ─────────────────────────────────────────────────────────────────────────
+// tasks/cancel
+// ─────────────────────────────────────────────────────────────────────────
+async function handleTasksCancel(res, reqId, params, taskStore) {
+    const taskId = stringFromParams(params, "id");
+    if (!taskId) {
+        writeJsonRpc(res, jsonRpcError(reqId, JSONRPC_INVALID_PARAMS, "Invalid params: 'id' is required for tasks/cancel"));
+        return;
+    }
+    const record = taskStore.get(taskId);
+    if (!record) {
+        writeJsonRpc(res, jsonRpcError(reqId, JSONRPC_INVALID_PARAMS, `Unknown task id: ${taskId}`));
+        return;
+    }
+    // Idempotent ack: already-terminal task → echo the cached envelope.
+    // Spec §4.5 "Idempotent; best-effort".
+    if (record.terminalEnvelope) {
+        writeJsonRpc(res, jsonRpcSuccess(reqId, record.terminalEnvelope));
+        return;
+    }
+    const reason = stringFromParams(params, "reason") ?? undefined;
+    const proxy = record.jobProxy ?? null;
+    let cancelThrew = false;
+    if (proxy) {
+        try {
+            await proxy.cancel(reason);
+        }
+        catch {
+            // Spec §4.5: cancel exceptions are logged and swallowed — the
+            // underlying job may already be terminal.
+            cancelThrew = true;
+        }
+    }
+    // Re-read status post-cancel so the response reflects the latest
+    // state. Java's BLOCKER fix from #934: if BOTH cancel() AND status()
+    // throw (double-failure), synthesize a state=canceled envelope rather
+    // than propagating exceptions (spec §4.5 fallback).
+    let envelope;
+    let statusThrew = false;
+    if (proxy) {
+        try {
+            envelope = await buildTaskFromLiveStatusInternal(taskId, record, proxy);
+        }
+        catch {
+            statusThrew = true;
+            envelope = buildCanceledTask(taskId, record.sessionId, record.requestMessage, reason);
+        }
+    }
+    else {
+        // Lost-JobProxy on a non-terminal record — spec §4.5 best-effort
+        // cancel says synthesize state=canceled rather than returning an
+        // error. Match Java's behaviour.
+        envelope = buildCanceledTask(taskId, record.sessionId, record.requestMessage, reason);
+    }
+    // If the post-cancel state is terminal, mark the record so future
+    // tasks/get calls hit the cached envelope and don't re-poll a closed
+    // JobProxy.
+    const statusObj = envelope["status"];
+    const state = typeof statusObj?.["state"] === "string" ? statusObj["state"] : null;
+    if (state && isTerminal(state)) {
+        taskStore.markTerminal(taskId, envelope);
+    }
+    else if (cancelThrew && statusThrew) {
+        // Double-failure path already produced a synthesized canceled
+        // envelope above — mark terminal so the client sees a stable cached
+        // response on retry.
+        taskStore.markTerminal(taskId, envelope);
+    }
+    else {
+        // Status didn't show terminal yet but cancel was requested —
+        // synthesize a canceled envelope so the client gets a clean terminal
+        // response. Matches Python's a2a.py:817-826 fallback.
+        const synth = buildCanceledTask(taskId, record.sessionId, record.requestMessage, reason);
+        taskStore.markTerminal(taskId, synth);
+        envelope = synth;
+    }
+    writeJsonRpc(res, jsonRpcSuccess(reqId, envelope));
+}
+// ─────────────────────────────────────────────────────────────────────────
+// tasks/sendSubscribe + tasks/resubscribe (SSE plan builders)
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Build the SSE stream plan for a `tasks/sendSubscribe` request. The
+ * dispatcher invokes the user handler eagerly (before the stream opens)
+ * so handler exceptions become a single SSE failed frame, not an opaque
+ * HTTP error mid-stream (spec §4.6).
+ */
+export async function buildSendSubscribeStream(reqId, params, deps) {
+    let taskId = stringFromParams(params, "id");
+    if (!taskId) {
+        taskId = randomUUID();
+    }
+    let sessionId = stringFromParams(params, "sessionId");
+    if (!sessionId) {
+        sessionId = taskId;
+    }
+    const message = mapFromParams(params, "message");
+    // Atomic reservation — closes the race between two concurrent
+    // tasks/sendSubscribe requests with the same id (await deps.handler
+    // yields control between a separate `contains()` and `put()`).
+    const reserved = deps.taskStore.reserveTask(taskId, {
+        sessionId,
+        requestMessage: hasOwn(message) ? message : undefined,
+        jobProxy: null,
+    });
+    if (!reserved) {
+        // Duplicate in-flight task_id — surface as a single SSE failed
+        // event so the SSE client sees a structured A2A failure rather
+        // than an opaque HTTP error (Python a2a.py:1143-1149).
+        return sseSingleFrame(buildStatusUpdateFrame(reqId, taskId, A2A_FAILED, `A2A task id '${taskId}' is already in use`, true, null));
+    }
+    const resolvedDeps = deps.routeRegistry.getDependenciesForRoute(deps.surface.routeId);
+    for (const dep of deps.surface.dependencies) {
+        if (resolvedDeps[dep.capability] === undefined) {
+            resolvedDeps[dep.capability] = null;
+        }
+    }
+    const jobSubmitter = deps.jobSubmitterProvider
+        ? deps.jobSubmitterProvider()
+        : null;
+    let handlerResult;
+    try {
+        handlerResult = await deps.handler(resolvedDeps, message, jobSubmitter);
+    }
+    catch (err) {
+        const errorText = errorTextOf(err);
+        // Cache the failed envelope so a subsequent tasks/get returns it
+        // consistently with the JSON-RPC path.
+        const failed = buildFailedTask(taskId, sessionId, message, errorText);
+        deps.taskStore.put(taskId, {
+            sessionId,
+            requestMessage: hasOwn(message) ? message : undefined,
+            terminalEnvelope: failed,
+            terminalAt: Date.now(),
+            jobProxy: null,
+        });
+        return sseSingleFrame(buildStatusUpdateFrame(reqId, taskId, A2A_FAILED, errorText, true, null));
+    }
+    if (isJobProxy(handlerResult)) {
+        parkLongRunning(deps.taskStore, taskId, sessionId, message, handlerResult);
+        return sseLongRunning(reqId, taskId, handlerResult);
+    }
+    // Sync handler over tasks/sendSubscribe: per spec §5.3, emit one
+    // artifact event then one final status event (state=completed).
+    const artifactFrame = buildArtifactUpdateFrame(reqId, taskId, handlerResult);
+    const terminalFrame = buildStatusUpdateFrame(reqId, taskId, A2A_COMPLETED, null, true, null);
+    // Cache the resulting envelope so a follow-up tasks/get returns the
+    // same payload deterministically.
+    const envelope = buildCompletedTask(taskId, sessionId, message, handlerResult);
+    deps.taskStore.put(taskId, {
+        sessionId,
+        requestMessage: hasOwn(message) ? message : undefined,
+        terminalEnvelope: envelope,
+        terminalAt: Date.now(),
+        jobProxy: null,
+    });
+    return sseSyncCompleted(reqId, taskId, artifactFrame, terminalFrame);
+}
+/**
+ * Build the SSE stream plan for a `tasks/resubscribe` request (spec §4.7).
+ * Looks up the parked task, emits an initial state=working event, then
+ * resumes polling from the registry's current view (no replay).
+ */
+export function buildResubscribeStream(reqId, params, taskStore) {
+    const taskId = stringFromParams(params, "id");
+    if (!taskId) {
+        // Spec §4.7 errors: return JSON-RPC, not SSE — the response has not
+        // been promoted to text/event-stream yet.
+        return sseError(jsonRpcError(reqId, JSONRPC_INVALID_PARAMS, "Invalid params: 'id' is required for tasks/resubscribe"), 200);
+    }
+    const record = taskStore.get(taskId);
+    if (!record) {
+        return sseError(jsonRpcError(reqId, JSONRPC_INVALID_PARAMS, `Unknown task id: ${taskId}`), 200);
+    }
+    if (record.terminalEnvelope) {
+        // Already terminal — emit ONE terminal status event and close.
+        // No replay per Python's a2a.py:1175-1178.
+        const env = record.terminalEnvelope;
+        const statusObj = env["status"];
+        let state = A2A_COMPLETED;
+        let msgText = null;
+        if (statusObj) {
+            const st = statusObj["state"];
+            if (typeof st === "string")
+                state = st;
+            const msg = statusObj["message"];
+            if (msg && typeof msg === "object") {
+                const parts = msg["parts"];
+                if (Array.isArray(parts) && parts.length > 0) {
+                    const first = parts[0];
+                    const text = first?.["text"];
+                    if (text !== undefined && text !== null) {
+                        msgText = String(text);
+                    }
+                }
+            }
+        }
+        return sseSingleFrame(buildStatusUpdateFrame(reqId, taskId, state, msgText, true, null));
+    }
+    const proxy = record.jobProxy ?? null;
+    if (!proxy) {
+        // Non-terminal record without a JobProxy is an inconsistent state.
+        // Java's BLOCKER fix from #934: emit a single failed terminal event
+        // so the client doesn't hang the SSE connection.
+        return sseSingleFrame(buildStatusUpdateFrame(reqId, taskId, A2A_FAILED, "Task state inconsistent: no live JobProxy and no terminal envelope", true, null));
+    }
+    return sseLongRunning(reqId, taskId, proxy);
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Live-status poll (shared by tasks/get + SSE emitter terminal frame)
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Pull the latest status from a parked task's `JobProxy` and project it
+ * into an A2A v1.0 Task envelope. Handles the "transient unreachability"
+ * branch per spec §4.4 by returning `state=working` with the error text
+ * in `status.message` rather than throwing — matches Python's
+ * `a2a.py:718-735` behavior.
+ *
+ * Used by `tasks/get` (top-level dispatcher) and exposed via
+ * {@link projectLiveStatus} for the SSE emitter's terminal-frame
+ * synthesis.
+ */
+export async function buildTaskFromLiveStatus(taskStore, taskId, record) {
+    const proxy = record.jobProxy ?? null;
+    if (!proxy) {
+        return buildWorkingTask(taskId, record.sessionId, record.requestMessage);
+    }
+    const envelope = await buildTaskFromLiveStatusInternal(taskId, record, proxy);
+    // Persist terminal envelopes so subsequent tasks/get calls hit the cache
+    // and don't re-poll the JobProxy (spec §4.4 / Appendix B item 5). For
+    // working / live states leave the record as-is — the next tasks/get
+    // should re-poll for fresh progress.
+    const statusObj = envelope["status"];
+    const state = statusObj && typeof statusObj["state"] === "string"
+        ? statusObj["state"]
+        : null;
+    if (state === A2A_COMPLETED || state === A2A_FAILED || state === A2A_CANCELED) {
+        taskStore.markTerminal(taskId, envelope);
+    }
+    return envelope;
+}
+async function buildTaskFromLiveStatusInternal(taskId, record, proxy) {
+    let status;
+    try {
+        const raw = (await proxy.status());
+        status = (raw && typeof raw === "object" && !Array.isArray(raw))
+            ? raw
+            : {};
+    }
+    catch (err) {
+        // Spec §4.4: transient unreachability → state=working + error text in
+        // status.message. Do NOT escalate to JSON-RPC error.
+        return buildWorkingTask(taskId, record.sessionId, record.requestMessage, `status unavailable: ${errorTextOf(err)}`);
+    }
+    const meshState = meshStatusOf(status);
+    const a2aState = fromMesh(meshState);
+    // On completed, attempt proxy.wait(timeoutSecs=1) to fetch the final
+    // artifact synchronously. Tight timeout per spec §4.4 so we don't
+    // block on a transiently-unreachable payload — fall back to no
+    // artifact in that case. On failed/canceled, do NOT call wait() —
+    // it would throw and the error text is already in status.error /
+    // status.progress_message.
+    let finalResult = null;
+    let hasFinalResult = false;
+    if (a2aState === A2A_COMPLETED) {
+        try {
+            finalResult = await proxy.wait(1.0);
+            hasFinalResult = true;
+        }
+        catch {
+            // Best-effort: artifact omitted if the result payload is
+            // transiently unreachable.
+        }
+    }
+    return buildTaskFromStatus(taskId, record.sessionId, record.requestMessage, a2aState, status, finalResult, hasFinalResult);
+}
+/**
+ * Project the live status of a parked task into an A2A v1.0 Task
+ * envelope. Exposed for the SSE emitter so it can render terminal
+ * frames consistently with `tasks/get`.
+ */
+export async function projectLiveStatus(taskStore, taskId) {
+    const record = taskStore.get(taskId);
+    if (!record)
+        return null;
+    if (record.terminalEnvelope)
+        return record.terminalEnvelope;
+    return buildTaskFromLiveStatus(taskStore, taskId, record);
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Task envelope builders (spec §4.3)
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Build a `state=completed` Task envelope (spec §4.3). The handler result
+ * is stringified per the spec — string returns pass through verbatim,
+ * everything else is JSON-stringified. `null` / `undefined` produce an
+ * empty-string artifact.
+ *
+ * Exported for testability + the symmetry with the SSE artifact frame
+ * builder.
+ */
+export function buildCompletedTask(taskId, sessionId, requestMessage, result) {
+    const text = stringifyResult(result);
+    return {
+        id: taskId,
+        sessionId,
+        status: {
+            state: A2A_COMPLETED,
+            timestamp: utcIso8601(),
+        },
+        artifacts: [
+            {
+                name: "result",
+                // Appendix A: parts[0].type MUST be emitted as "text" for forward
+                // compatibility even though consumers ignore it.
+                parts: [{ type: "text", text }],
+                index: 0,
+            },
+        ],
+        history: historyOf(requestMessage),
+    };
+}
+/**
+ * Build a `state=failed` Task envelope (spec §4.3 "handler raised"
+ * branch). The error text is folded into `status.message.parts[0].text`.
+ */
+export function buildFailedTask(taskId, sessionId, requestMessage, errorText) {
+    return {
+        id: taskId,
+        sessionId,
+        status: {
+            state: A2A_FAILED,
+            timestamp: utcIso8601(),
+            message: {
+                role: "agent",
+                parts: [{ type: "text", text: errorText }],
+            },
+        },
+        artifacts: [],
+        history: historyOf(requestMessage),
+    };
+}
+/**
+ * Build a `state=working` Task envelope (spec §4.3 long-running branch /
+ * spec §4.4 transient unreachability fallback).
+ */
+export function buildWorkingTask(taskId, sessionId, requestMessage, progressMessage, progress) {
+    const status = {
+        state: A2A_WORKING,
+        timestamp: utcIso8601(),
+    };
+    if (progressMessage && progressMessage.length > 0) {
+        status.message = {
+            role: "agent",
+            parts: [{ type: "text", text: progressMessage }],
+        };
+    }
+    const envelope = {
+        id: taskId,
+        sessionId,
+        status,
+        artifacts: [],
+        history: historyOf(requestMessage ?? {}),
+    };
+    if (progress !== undefined && progress !== null) {
+        envelope.metadata = { progress };
+    }
+    return envelope;
+}
+/**
+ * Build a `state=canceled` Task envelope (spec §4.5 cancel fallback / spec
+ * §7.2). Used when:
+ * - `tasks/cancel` post-cancel status read didn't show terminal yet, OR
+ * - both `proxy.cancel()` AND `proxy.status()` threw, OR
+ * - the parked task lost its `JobProxy` reference.
+ */
+export function buildCanceledTask(taskId, sessionId, requestMessage, reason) {
+    const status = {
+        state: A2A_CANCELED,
+        timestamp: utcIso8601(),
+    };
+    if (reason && reason.length > 0) {
+        status.message = {
+            role: "agent",
+            parts: [{ type: "text", text: reason }],
+        };
+    }
+    return {
+        id: taskId,
+        sessionId,
+        status,
+        artifacts: [],
+        history: historyOf(requestMessage ?? {}),
+    };
+}
+/**
+ * Build a Task envelope from a `JobProxy.status()` result dict (spec
+ * §4.4). Mirrors Python's `_build_task_from_status` and Java's
+ * `MeshA2ADispatcher.buildTaskFromStatus` — folds `error` /
+ * `progress_message` into A2A `status.message`, materialises an artifact
+ * for completed tasks when the final result is available, and lifts
+ * `progress` to `metadata.progress`.
+ *
+ * Per Appendix A, `progress` is emitted as a real JSON number (no
+ * stringification) and `parts[0].type` is always `"text"`.
+ */
+export function buildTaskFromStatus(taskId, sessionId, requestMessage, a2aState, meshStatus, finalResult, hasFinalResult) {
+    const status = {
+        state: a2aState,
+        timestamp: utcIso8601(),
+    };
+    let msgText = null;
+    if (a2aState === A2A_FAILED) {
+        const err = meshStatus["error"];
+        if (err !== null && err !== undefined && String(err).length > 0) {
+            msgText = String(err);
+        }
+        else {
+            const pm = meshStatus["progress_message"];
+            if (pm !== null && pm !== undefined && String(pm).length > 0) {
+                msgText = String(pm);
+            }
+        }
+    }
+    else {
+        const pm = meshStatus["progress_message"];
+        if (pm !== null && pm !== undefined && String(pm).length > 0) {
+            msgText = String(pm);
+        }
+    }
+    if (msgText) {
+        status.message = {
+            role: "agent",
+            parts: [{ type: "text", text: msgText }],
+        };
+    }
+    const artifacts = [];
+    if (hasFinalResult && a2aState === A2A_COMPLETED) {
+        artifacts.push({
+            name: "result",
+            parts: [{ type: "text", text: stringifyResult(finalResult) }],
+            index: 0,
+        });
+    }
+    const envelope = {
+        id: taskId,
+        sessionId,
+        status,
+        artifacts,
+        history: historyOf(requestMessage ?? {}),
+    };
+    // Appendix A: `metadata.progress` MUST be a real JSON number. If the
+    // underlying status payload exposes `progress` as a non-number
+    // (string, boolean, object), omit `metadata` entirely rather than
+    // emitting a spec-violating typed-value. Mirrors the SSE emitter's
+    // `typeof progress === "number" ? progress : null` coercion.
+    const progressRaw = meshStatus["progress"];
+    if (typeof progressRaw === "number") {
+        envelope.metadata = { progress: progressRaw };
+    }
+    return envelope;
+}
+/**
+ * Stringify a handler return value as the text body of the `result`
+ * artifact. `string` returns pass through verbatim; everything else is
+ * JSON-stringified. Non-serializable returns fall back to `String(value)`
+ * so the artifact is always well-formed (mirrors Python's `default=str`
+ * coercion in `a2a.py:403`).
+ */
+export function stringifyResult(value) {
+    if (value === null || value === undefined) {
+        return "";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    try {
+        // JSON.stringify returns `undefined` (the literal value, NOT a string)
+        // for functions / symbols / and undefined itself. Coerce via String()
+        // so the artifact text body is always a real string.
+        const serialized = JSON.stringify(value);
+        return typeof serialized === "string" ? serialized : String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function historyOf(requestMessage) {
+    if (!requestMessage || !hasOwn(requestMessage)) {
+        return [];
+    }
+    return [{ ...requestMessage }];
+}
+// ─────────────────────────────────────────────────────────────────────────
+// SSE frame builders (spec §5)
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Build a JSON-RPC envelope carrying an A2A v1.0 `TaskStatusUpdateEvent`
+ * (spec §5.2).
+ *
+ * Per Appendix A:
+ * - `final` MUST be a real JSON boolean (no stringification).
+ * - `progress` (when non-null) MUST be a JSON number.
+ * - `parts[0].type` MUST be emitted as `"text"`.
+ *
+ * @param reqId       JSON-RPC request id to echo
+ * @param taskId      A2A task id
+ * @param a2aState    one of the four enumerated A2A states
+ * @param messageText optional text for `status.message.parts[0].text`
+ * @param finalFlag   `true` only on the terminal frame
+ * @param progress    optional numeric progress; emitted as `metadata.progress`
+ */
+export function buildStatusUpdateFrame(reqId, taskId, a2aState, messageText, finalFlag, progress) {
+    const status = {
+        state: a2aState,
+        timestamp: utcIso8601(),
+    };
+    if (messageText && messageText.length > 0) {
+        status.message = {
+            role: "agent",
+            parts: [{ type: "text", text: messageText }],
+        };
+    }
+    const result = {
+        id: taskId,
+        status,
+        // Appendix A: real boolean, not a string.
+        final: finalFlag,
+    };
+    if (progress !== null && progress !== undefined) {
+        result.metadata = { progress };
+    }
+    return {
+        jsonrpc: "2.0",
+        id: reqId ?? null,
+        result,
+    };
+}
+/**
+ * Build a JSON-RPC envelope carrying an A2A v1.0 `TaskArtifactUpdateEvent`
+ * (spec §5.2). The handler result is stringified per the
+ * {@link stringifyResult} contract.
+ */
+export function buildArtifactUpdateFrame(reqId, taskId, value) {
+    return {
+        jsonrpc: "2.0",
+        id: reqId ?? null,
+        result: {
+            id: taskId,
+            artifact: {
+                name: "result",
+                parts: [{ type: "text", text: stringifyResult(value) }],
+                index: 0,
+            },
+        },
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────
+// JobProxy detection
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * `instanceof`-based detection with duck-type fallback. JobProxy is a
+ * napi-rs class that survives across module loaders; using `instanceof`
+ * first matches Java's branching. The duck-type fallback covers any
+ * future case where a JobProxy-shaped object is returned (subclass /
+ * test double).
+ */
+function isJobProxy(value) {
+    if (value instanceof JobProxy)
+        return true;
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value !== "object")
+        return false;
+    const v = value;
+    return (typeof v["status"] === "function" &&
+        typeof v["wait"] === "function" &&
+        typeof v["cancel"] === "function" &&
+        typeof v["jobId"] === "string");
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Task store helpers
+// ─────────────────────────────────────────────────────────────────────────
+function parkLongRunning(taskStore, taskId, sessionId, message, proxy) {
+    taskStore.put(taskId, {
+        sessionId,
+        requestMessage: hasOwn(message) ? message : undefined,
+        // terminalEnvelope + terminalAt undefined: non-terminal record.
+        jobProxy: proxy,
+    });
+}
+// ─────────────────────────────────────────────────────────────────────────
+// JSON-RPC helpers
+// ─────────────────────────────────────────────────────────────────────────
+function jsonRpcSuccess(reqId, result) {
+    return { jsonrpc: "2.0", id: reqId ?? null, result };
+}
+function jsonRpcError(reqId, code, message) {
+    return {
+        jsonrpc: "2.0",
+        error: { code, message },
+        id: reqId ?? null,
+    };
+}
+function writeJsonRpc(res, body) {
+    res.status(200).type("application/json").send(JSON.stringify(body));
+}
+function writeJsonRpcParseErrorHttp400(res, message) {
+    res.status(400).type("application/json").send(JSON.stringify({
+        jsonrpc: "2.0",
+        error: { code: JSONRPC_PARSE_ERROR, message },
+        id: null,
+    }));
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Param + envelope parsing
+// ─────────────────────────────────────────────────────────────────────────
+function extractRequestId(envelope) {
+    // Spec §4.1: `id` MAY be any JSON value the client picks; echo back
+    // verbatim (including `null` and 0). Returning `undefined` here causes
+    // `jsonRpcSuccess` / `jsonRpcError` to substitute `null` per JSON-RPC.
+    if (!Object.prototype.hasOwnProperty.call(envelope, "id")) {
+        return undefined;
+    }
+    return envelope["id"];
+}
+function readParams(params) {
+    if (params === null || params === undefined)
+        return {};
+    if (typeof params !== "object" || Array.isArray(params))
+        return {};
+    return params;
+}
+function stringFromParams(params, key) {
+    const v = params[key];
+    if (v === null || v === undefined)
+        return null;
+    if (typeof v === "string")
+        return v.length === 0 ? null : v;
+    return String(v);
+}
+function mapFromParams(params, key) {
+    const v = params[key];
+    if (v === null || v === undefined)
+        return {};
+    if (typeof v !== "object" || Array.isArray(v))
+        return {};
+    return { ...v };
+}
+function hasOwn(obj) {
+    if (!obj)
+        return false;
+    for (const _key in obj) {
+        if (Object.prototype.hasOwnProperty.call(obj, _key))
+            return true;
+    }
+    return false;
+}
+function errorTextOf(err) {
+    if (err instanceof Error) {
+        return err.message || err.name || "Error";
+    }
+    if (typeof err === "string")
+        return err;
+    try {
+        // JSON.stringify returns `undefined` (the literal value, NOT a string)
+        // for functions / symbols / and undefined itself. Coerce via String()
+        // so callers always receive a real string.
+        const serialized = JSON.stringify(err);
+        return typeof serialized === "string" ? serialized : String(err);
+    }
+    catch {
+        return String(err);
+    }
+}
+/**
+ * UTC ISO-8601 with the `Z` suffix (NOT `+00:00`) per spec §5.2 /
+ * Appendix A. `Date.prototype.toISOString()` already emits the right form
+ * (`2026-05-11T12:34:56.789Z`).
+ */
+function utcIso8601() {
+    return new Date().toISOString();
+}
+function sseError(errorBody, httpStatus) {
+    return { kind: "error", errorBody, httpStatus };
+}
+function sseSingleFrame(frame) {
+    return { kind: "single-frame", frame };
+}
+function sseSyncCompleted(reqId, taskId, artifactFrame, terminalFrame) {
+    return { kind: "sync-completed", reqId, taskId, artifactFrame, terminalFrame };
+}
+function sseLongRunning(reqId, taskId, proxy) {
+    return { kind: "long-running", reqId, taskId, proxy };
+}
+// Re-export helpers under more obvious names for the SSE emitter so it
+// doesn't need to import every individual builder.
+export { isJobProxy as __isJobProxyForTests, };
+//# sourceMappingURL=dispatcher.js.map