@nifrajs/ag-ui 3.2.0

package/dist/index.js

@@ -0,0 +1,637 @@
+/**
+ * `@nifrajs/ag-ui` - mount a nifra agent as an AG-UI (Agent-User Interaction protocol) endpoint.
+ *
+ * The package is a protocol bridge over the `@nifrajs/agent` runner, mirroring the `mountAgent`
+ * seam: one HTTP POST accepting the AG-UI `RunAgentInput` body, the bounded runner in the middle,
+ * a stream of AG-UI events out. The request body is read through core's single bounded,
+ * proto-guarded framing lane (`@nifrajs/core/edge-kit`); the model, durable state store, and
+ * approval transport arrive through a per-request `ports` factory and never live in this package.
+ *
+ * Wire contract (default path `/agui`):
+ * - `POST {path}` body `RunAgentInput` (`threadId` and `runId` required) -> SSE where each `data:`
+ *   field is one AG-UI event:
+ *   - `RUN_STARTED`, then `CUSTOM { name: "nifra.turn", value: { turnId } }` announcing the
+ *     runner's turn id.
+ *   - Step evidence maps to `TOOL_CALL_START`/`TOOL_CALL_END` for tool effects, followed by a
+ *     `TOOL_CALL_RESULT` whose `content` is the token-only outcome (`{ outcome, code? }` - the
+ *     runtime never carries tool payloads), and `STEP_STARTED`/`STEP_FINISHED` for everything
+ *     else. Evidence-derived events carry the evidence `timestamp`.
+ *   - A model port that streams (`request.onDelta`) turns into live token frames:
+ *     `TEXT_MESSAGE_START`/`_CONTENT` for text deltas, `REASONING_*` for reasoning deltas, and
+ *     `TOOL_CALL_START` + `TOOL_CALL_ARGS` for the tool call being formed - the following tool
+ *     evidence closes that same call (`TOOL_CALL_END` + `TOOL_CALL_RESULT`) instead of opening a
+ *     second one. When any text was streamed, the terminal `TEXT_MESSAGE_*` block is suppressed -
+ *     the streamed text IS the assistant message, so a streaming port must stream all
+ *     user-visible text. A non-streaming port keeps the single terminal
+ *     `TEXT_MESSAGE_START`/`_CONTENT`/`_END` block. `usage` deltas are summed per
+ *     `(provider, model)` across the run's model decisions and stamped as the spec's
+ *     `usage: TokenUsage[]` array on the terminal `RUN_FINISHED` event (success and interrupt
+ *     alike) - they never produce a frame of their own. Deltas are transient: a `Last-Event-ID`
+ *     replay carries evidence frames and the stored (unsuppressed) terminal events only - the
+ *     stored `RUN_FINISHED` keeps its `usage`.
+ *   - The `ports` factory receives `(c, run)` where `run.sharedState` is the run's
+ *     `AgentSharedState` channel: `body.state` seeds the document (announced as an upfront
+ *     `STATE_SNAPSHOT` when present), every `patch` streams as `STATE_DELTA` (RFC 6902 ops), and
+ *     a first patch without a seeded document announces itself as a `STATE_SNAPSHOT`.
+ *   - A completed run ends `RUN_FINISHED` with `result` and `outcome: { type: "success" }`, after
+ *     an optional `MESSAGES_SNAPSHOT` (see `emitMessagesSnapshot`); a failed one ends `RUN_ERROR`.
+ *   - A suspended run (approval, budget, model retry, max turns) emits
+ *     `CUSTOM { name: "nifra.pending", value: { turnId, reason, continuation } }` and then
+ *     `RUN_FINISHED` with `outcome: { type: "interrupt", interrupts: [{ id: turnId, reason,
+ *     toolCallId?, responseSchema, metadata: { turnId, continuation } }] }`. Resume with the
+ *     spec `resume` array - `[{ interruptId: turnId, status, payload: { continuation,
+ *     approval? } }]` where `payload.continuation` echoes `metadata.continuation` (the runtime is
+ *     stateless, so the client must send it back) - or with the legacy
+ *     `forwardedProps.resume` (`{ continuation, approval? }`) plus `forwardedProps.turnId`. A
+ *     `status: "cancelled"` entry without an explicit approval resumes as a denial. The runtime
+ *     keeps state token-only, so a suspended tool's input must be replayed in
+ *     `continuation.input`. A resume that fails validation is ignored and the POST starts a
+ *     fresh run.
+ * - Agent input is `forwardedProps.input` when present, otherwise the content of the last
+ *   `role: "user"` message.
+ * - With an `evidenceLog` configured, evidence-derived frames carry SSE `id: <seq>` and a dropped
+ *   connection is resumable: re-POST the same body with a `Last-Event-ID` header to replay the
+ *   missed events and rejoin the still-running turn - the run is never re-executed. Without the
+ *   log the header is ignored and every POST starts a run.
+ * - The seam performs no authentication or authorization. Wrap it with the app's own route guards,
+ *   and scope the store/model returned by `ports` to the caller.
+ */
+import { combineAgentDeltaSinks, combineAgentTelemetry, createAgentSharedState, createAgentState, resumeAgent, runAgent, } from "@nifrajs/agent";
+import { createAgentEvidenceStream, } from "@nifrajs/agent/events";
+import { EMPTY_RESPONSE_CONTROLS, plainError, readBodyFramed, toResponse, } from "@nifrajs/core/edge-kit";
+const DEFAULT_PATH = "/agui";
+const DEFAULT_MAX_BODY_BYTES = 1_000_000;
+const PENDING_KINDS = ["approval", "budget", "model", "cancelled"];
+const TURN_ID_PATTERN = /^[a-zA-Z0-9._:-]{1,128}$/;
+const LAST_EVENT_ID_PATTERN = /^\d{1,15}$/;
+/** Mount a single agent as an AG-UI `POST {path}` SSE endpoint. */
+export function mountAgUI(app, options) {
+    const path = options.path ?? DEFAULT_PATH;
+    const maxBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    const proto = options.protoPoisoning ?? "reject";
+    const runOptions = options.maxTurns === undefined ? {} : { maxTurns: options.maxTurns };
+    app.post(path, (c) => readBodyFramed(c.req, maxBytes, proto, (parsed) => execute(c, parsed, options, runOptions), (rejection) => render(rejection), () => render(plainError(400, "bad_request"))).catch(() => render(plainError(400, "bad_request"))));
+}
+async function execute(c, parsed, options, runOptions) {
+    const body = asRecord(parsed);
+    const threadId = body === undefined ? undefined : body.threadId;
+    const runId = body === undefined ? undefined : body.runId;
+    if (body === undefined || typeof threadId !== "string" || typeof runId !== "string")
+        return jsonResponse(400, { error: "invalid_run_agent_input" });
+    const forwarded = asRecord(body.forwardedProps) ?? {};
+    const forwardedTurnId = typeof forwarded.turnId === "string" ? forwarded.turnId : undefined;
+    if (forwardedTurnId !== undefined && !TURN_ID_PATTERN.test(forwardedTurnId))
+        return jsonResponse(400, { error: "invalid_turn_id" });
+    // Legacy resume names the turn in forwardedProps; spec resume names it via the interrupt id.
+    const entry = parseResumeEntry(body.resume);
+    const turnId = forwardedTurnId ?? entry?.turnId ?? (TURN_ID_PATTERN.test(runId) ? runId : crypto.randomUUID());
+    const input = Object.hasOwn(forwarded, "input") ? forwarded.input : lastUserMessage(body.messages);
+    const resume = parseResume(forwarded.resume) ?? entry?.resume;
+    const log = options.evidenceLog;
+    const identity = { threadId, runId, turnId };
+    // A reconnect replays recorded evidence and rejoins the turn; it never starts a second run.
+    const lastEventId = c.req.headers.get("last-event-id");
+    if (log !== undefined && lastEventId !== null) {
+        if (!LAST_EVENT_ID_PATTERN.test(lastEventId))
+            return jsonResponse(400, { error: "invalid_last_event_id" });
+        const replay = await log.replay(turnId, Number(lastEventId));
+        if (replay === undefined)
+            return jsonResponse(409, { error: "replay_unavailable" });
+        return sseReplayResponse(identity, replay);
+    }
+    // `body.state` seeds the run's shared UI state document; patches stream as STATE_DELTA.
+    const sharedState = createAgentSharedState(body.state === undefined ? {} : body.state);
+    const basePorts = await options.ports(c, { turnId, sharedState });
+    const start = (telemetry, deltas) => {
+        // Compose rather than replace: the SSE evidence stream must not displace a telemetry port or
+        // delta sink the caller injected through `ports`.
+        const combined = combineAgentTelemetry(basePorts.telemetry, log?.open(turnId), telemetry);
+        const sinks = combineAgentDeltaSinks(basePorts.deltas, deltas);
+        const ports = {
+            ...basePorts,
+            ...(combined === undefined ? {} : { telemetry: combined }),
+            ...(sinks === undefined ? {} : { deltas: sinks }),
+        };
+        if (resume !== undefined) {
+            return resumeAgent(options.agent, turnId, { value: input, resume }, ports, runOptions);
+        }
+        return runAgent(options.agent, { value: input }, ports, {
+            ...runOptions,
+            state: createAgentState(turnId),
+        });
+    };
+    const snapshotMessages = options.emitMessagesSnapshot === true ? body.messages : undefined;
+    return sseResponse(identity, start, log, snapshotMessages, {
+        channel: sharedState,
+        announced: body.state !== undefined,
+    });
+}
+function sseResponse(identity, start, log, snapshotMessages, state) {
+    const stream = createAgentEvidenceStream();
+    // `id:` frames are only meaningful when a log can serve the reconnect they invite.
+    const withIds = log !== undefined;
+    const body = new ReadableStream({
+        async start(controller) {
+            const send = sseSender(controller);
+            const projector = createDeltaProjector(send, identity.turnId);
+            const run = start(stream, projector.sink);
+            // The evidence stream must terminate whether the run resolves or throws, or the `for await`
+            // below would hang; the run result (or the error) is still reported in-band after it drains.
+            run
+                .then(() => { }, () => { })
+                .finally(() => stream.complete());
+            send({ type: "RUN_STARTED", threadId: identity.threadId, runId: identity.runId });
+            send({ type: "CUSTOM", name: "nifra.turn", value: { turnId: identity.turnId } });
+            let announced = state.announced;
+            if (announced)
+                send({ type: "STATE_SNAPSHOT", snapshot: state.channel.snapshot(), timestamp: Date.now() });
+            // A first patch on an unseeded document announces the whole document instead of a delta
+            // against a base the client never saw.
+            const unsubscribe = state.channel.subscribe((ops) => {
+                if (!announced) {
+                    announced = true;
+                    send({
+                        type: "STATE_SNAPSHOT",
+                        snapshot: state.channel.snapshot(),
+                        timestamp: Date.now(),
+                    });
+                    return;
+                }
+                send({ type: "STATE_DELTA", delta: ops, timestamp: Date.now() });
+            });
+            try {
+                for await (const evidence of stream) {
+                    const openToolCallId = projector.adopt(evidence);
+                    sendEvidence(send, evidence, identity.turnId, withIds, openToolCallId);
+                }
+                const { streamedText, usage } = projector.finish();
+                const events = terminalEvents(identity, await run, snapshotMessages, usage);
+                // Store the terminal events before delivering them, so a client that misses them can
+                // replay. The stored form is always the unsuppressed one - a replayed stream saw no
+                // deltas, so it needs the full terminal text block.
+                await finishQuietly(log, identity.turnId, { events });
+                for (const event of events) {
+                    // Streamed text IS the assistant message; re-sending it as a terminal block would
+                    // duplicate it on the live client.
+                    if (streamedText && String(event.type).startsWith("TEXT_MESSAGE_"))
+                        continue;
+                    send(event);
+                }
+            }
+            catch {
+                projector.finish();
+                const events = [{ type: "RUN_ERROR", message: "run_failed", timestamp: Date.now() }];
+                await finishQuietly(log, identity.turnId, { events });
+                for (const event of events)
+                    send(event);
+            }
+            finally {
+                unsubscribe();
+                controller.close();
+            }
+        },
+    });
+    return sseHeaders(body);
+}
+function sseReplayResponse(identity, replay) {
+    const body = new ReadableStream({
+        async start(controller) {
+            const send = sseSender(controller);
+            send({ type: "RUN_STARTED", threadId: identity.threadId, runId: identity.runId });
+            send({ type: "CUSTOM", name: "nifra.turn", value: { turnId: identity.turnId } });
+            try {
+                for (const evidence of replay.evidence)
+                    sendEvidence(send, evidence, identity.turnId, true);
+                if (replay.live !== undefined)
+                    for await (const evidence of replay.live)
+                        sendEvidence(send, evidence, identity.turnId, true);
+                const events = asTerminalEvents(await replay.result);
+                if (events === undefined)
+                    send({ type: "RUN_ERROR", message: "run_failed" });
+                else
+                    for (const event of events)
+                        send(event);
+            }
+            catch {
+                send({ type: "RUN_ERROR", message: "run_failed" });
+            }
+            finally {
+                controller.close();
+            }
+        },
+    });
+    return sseHeaders(body);
+}
+function sseSender(controller) {
+    const encoder = new TextEncoder();
+    return (event, id) => {
+        const head = id === undefined ? "" : `id: ${id}\n`;
+        controller.enqueue(encoder.encode(`${head}data: ${JSON.stringify(event)}\n\n`));
+    };
+}
+/**
+ * Emit one evidence item's events, stamping the `seq` only on the item's LAST frame: SSE
+ * `Last-Event-ID` points at the last frame received, so a partially delivered multi-event item
+ * (a TOOL_CALL_START without its END) is replayed whole on reconnect instead of losing its tail.
+ */
+function sendEvidence(send, evidence, turnId, withIds, openToolCallId) {
+    const events = evidenceEvents(evidence, turnId, openToolCallId);
+    for (let index = 0; index < events.length; index += 1) {
+        const event = events[index];
+        if (withIds && index === events.length - 1)
+            send(event, evidence.seq);
+        else
+            send(event);
+    }
+}
+function sseHeaders(body) {
+    return new Response(body, {
+        status: 200,
+        headers: {
+            "content-type": "text/event-stream; charset=utf-8",
+            "cache-control": "no-cache, no-transform",
+            connection: "keep-alive",
+        },
+    });
+}
+const USAGE_TOKEN_FIELDS = [
+    "inputTokens",
+    "outputTokens",
+    "totalTokens",
+    "reasoningTokens",
+    "cachedInputTokens",
+];
+/**
+ * Project model deltas onto live AG-UI frames. Text deltas open a `TEXT_MESSAGE`, reasoning
+ * deltas a `REASONING` message, tool-args deltas a provisional `TOOL_CALL` - each stream closes
+ * when a different delta kind starts, when tool evidence lands, or at the end of the run. Deltas
+ * are transient observer data: none of this is persisted or replayed.
+ */
+function createDeltaProjector(send, turnId) {
+    let counter = 0;
+    let textId;
+    let reasoningId;
+    let callId;
+    let streamedText = false;
+    let usage;
+    const closeText = () => {
+        if (textId === undefined)
+            return;
+        send({ type: "TEXT_MESSAGE_END", messageId: textId, timestamp: Date.now() });
+        textId = undefined;
+    };
+    const closeReasoning = () => {
+        if (reasoningId === undefined)
+            return;
+        const timestamp = Date.now();
+        send({ type: "REASONING_MESSAGE_END", messageId: reasoningId, timestamp });
+        send({ type: "REASONING_END", messageId: reasoningId, timestamp });
+        reasoningId = undefined;
+    };
+    const closeCall = () => {
+        if (callId === undefined)
+            return;
+        send({ type: "TOOL_CALL_END", toolCallId: callId, timestamp: Date.now() });
+        callId = undefined;
+    };
+    const sink = {
+        delta(delta) {
+            // Usage is terminal metadata for the whole run, not a frame: sum per (provider, model)
+            // across model decisions without disturbing whichever stream is open.
+            if (delta.kind === "usage") {
+                usage = usage ?? new Map();
+                const key = `${delta.provider ?? ""}${delta.model ?? ""}`;
+                let entry = usage.get(key);
+                if (entry === undefined) {
+                    entry = {
+                        ...(delta.provider === undefined ? {} : { provider: delta.provider }),
+                        ...(delta.model === undefined ? {} : { model: delta.model }),
+                    };
+                    usage.set(key, entry);
+                }
+                for (const field of USAGE_TOKEN_FIELDS) {
+                    const value = delta[field];
+                    // A non-finite figure must not poison the sum; a never-reported field stays absent.
+                    if (typeof value === "number" && Number.isFinite(value))
+                        entry[field] = (entry[field] ?? 0) + value;
+                }
+                return;
+            }
+            const timestamp = Date.now();
+            if (delta.kind === "text") {
+                closeReasoning();
+                closeCall();
+                if (textId === undefined) {
+                    textId = `${turnId}:stream:${counter}`;
+                    counter += 1;
+                    send({ type: "TEXT_MESSAGE_START", messageId: textId, role: "assistant", timestamp });
+                }
+                send({ type: "TEXT_MESSAGE_CONTENT", messageId: textId, delta: delta.text, timestamp });
+                streamedText = true;
+                return;
+            }
+            if (delta.kind === "reasoning") {
+                closeText();
+                closeCall();
+                if (reasoningId === undefined) {
+                    reasoningId = `${turnId}:reasoning:${counter}`;
+                    counter += 1;
+                    send({ type: "REASONING_START", messageId: reasoningId, timestamp });
+                    send({
+                        type: "REASONING_MESSAGE_START",
+                        messageId: reasoningId,
+                        role: "reasoning",
+                        timestamp,
+                    });
+                }
+                send({
+                    type: "REASONING_MESSAGE_CONTENT",
+                    messageId: reasoningId,
+                    delta: delta.text,
+                    timestamp,
+                });
+                return;
+            }
+            closeText();
+            closeReasoning();
+            if (callId === undefined) {
+                callId = `${turnId}:call:${counter}`;
+                counter += 1;
+                send({
+                    type: "TOOL_CALL_START",
+                    toolCallId: callId,
+                    toolCallName: delta.name ?? "tool",
+                    timestamp,
+                });
+            }
+            send({ type: "TOOL_CALL_ARGS", toolCallId: callId, delta: delta.argsText, timestamp });
+        },
+    };
+    return {
+        sink,
+        adopt(evidence) {
+            if (evidence.kind !== "tool" || evidence.outcome === "started")
+                return undefined;
+            closeText();
+            closeReasoning();
+            if (callId === undefined)
+                return undefined;
+            const adopted = callId;
+            callId = undefined;
+            return adopted;
+        },
+        finish() {
+            closeCall();
+            closeReasoning();
+            closeText();
+            return { streamedText, ...(usage === undefined ? {} : { usage: [...usage.values()] }) };
+        },
+    };
+}
+/** JSON Schema for the payload a spec `resume` entry must carry back. */
+const RESUME_RESPONSE_SCHEMA = {
+    type: "object",
+    required: ["continuation"],
+    properties: {
+        continuation: {
+            type: "object",
+            description: "Echo of the interrupt's metadata.continuation, with the tool input replayed.",
+        },
+        approval: {
+            type: "object",
+            properties: { granted: { type: "boolean" }, reason: { type: "string" } },
+        },
+    },
+};
+/** The events that close a run, derived once so live delivery and replay stay identical. */
+function terminalEvents(identity, result, snapshotMessages, usage) {
+    const timestamp = Date.now();
+    // Usage rides the spec's RUN_FINISHED `usage` array, so the stored terminal events keep it
+    // and a replayed stream reports the same totals as the live one.
+    const withUsage = usage === undefined ? {} : { usage };
+    if (result.status === "completed") {
+        if (result.error !== undefined)
+            return [{ type: "RUN_ERROR", message: result.error.code, timestamp }];
+        const messageId = `${identity.turnId}:output`;
+        const delta = typeof result.output === "string" ? result.output : JSON.stringify(result.output);
+        return [
+            { type: "TEXT_MESSAGE_START", messageId, role: "assistant", timestamp },
+            { type: "TEXT_MESSAGE_CONTENT", messageId, delta, timestamp },
+            { type: "TEXT_MESSAGE_END", messageId, timestamp },
+            ...messagesSnapshot(snapshotMessages, messageId, delta, timestamp),
+            {
+                type: "RUN_FINISHED",
+                threadId: identity.threadId,
+                runId: identity.runId,
+                result: result.output,
+                outcome: { type: "success" },
+                ...withUsage,
+                timestamp,
+            },
+        ];
+    }
+    if (result.status === "suspended") {
+        return [
+            {
+                type: "CUSTOM",
+                name: "nifra.pending",
+                value: { turnId: identity.turnId, reason: result.reason, continuation: result.pending },
+                timestamp,
+            },
+            {
+                type: "RUN_FINISHED",
+                threadId: identity.threadId,
+                runId: identity.runId,
+                outcome: {
+                    type: "interrupt",
+                    interrupts: [
+                        {
+                            id: identity.turnId,
+                            reason: result.reason,
+                            ...(result.pending.tool === undefined ? {} : { toolCallId: result.pending.effectId }),
+                            responseSchema: RESUME_RESPONSE_SCHEMA,
+                            metadata: { turnId: identity.turnId, continuation: result.pending },
+                        },
+                    ],
+                },
+                ...withUsage,
+                timestamp,
+            },
+        ];
+    }
+    return [
+        {
+            type: "RUN_FINISHED",
+            threadId: identity.threadId,
+            runId: identity.runId,
+            ...withUsage,
+            timestamp,
+        },
+    ];
+}
+/**
+ * The optional authoritative message list: the client-sent messages echoed back with the
+ * assistant output appended. Emitted only when `emitMessagesSnapshot` is on.
+ */
+function messagesSnapshot(messages, messageId, content, timestamp) {
+    if (messages === undefined)
+        return [];
+    const echoed = Array.isArray(messages) ? messages : [];
+    return [
+        {
+            type: "MESSAGES_SNAPSHOT",
+            messages: [...echoed, { id: messageId, role: "assistant", content }],
+            timestamp,
+        },
+    ];
+}
+/** Parse the stored terminal value - a durable log adapter may hand back anything. */
+function asTerminalEvents(value) {
+    const record = asRecord(value);
+    if (record === undefined || !Array.isArray(record.events))
+        return undefined;
+    const events = [];
+    for (const event of record.events) {
+        const parsed = asRecord(event);
+        if (parsed === undefined)
+            return undefined;
+        events.push(parsed);
+    }
+    return events;
+}
+/** Telemetry-grade storage: a failing log must not fail the turn or mask its result. */
+async function finishQuietly(log, turnId, result) {
+    if (log === undefined)
+        return;
+    try {
+        await log.finish(turnId, result);
+    }
+    catch {
+        // Replay degrades to unavailable; the in-band response is unaffected.
+    }
+}
+/** Map one step-evidence item onto AG-UI events. Evidence is token-only by design. */
+function evidenceEvents(evidence, turnId, openToolCallId) {
+    const timestamp = evidence.at;
+    if (evidence.kind === "tool") {
+        // When the model streamed this call's arguments, its TOOL_CALL_START (with TOOL_CALL_ARGS)
+        // already went out under the projector's provisional id - close that call instead of
+        // opening a second one under the effect id.
+        const toolCallId = openToolCallId ?? evidence.effectId ?? `${evidence.kind}:${evidence.seq}`;
+        const start = {
+            type: "TOOL_CALL_START",
+            toolCallId,
+            toolCallName: evidence.name ?? "tool",
+            timestamp,
+        };
+        // The runner records one terminal evidence item per tool effect (committed/failed/denied),
+        // so a single item expands to the START/END/RESULT triple AG-UI clients expect. The RESULT
+        // content is the token-only outcome - the runtime never carries tool payloads.
+        if (evidence.outcome === "started")
+            return openToolCallId === undefined ? [start] : [];
+        return [
+            ...(openToolCallId === undefined ? [start] : []),
+            { type: "TOOL_CALL_END", toolCallId, timestamp },
+            {
+                type: "TOOL_CALL_RESULT",
+                messageId: `${turnId}:tool:${evidence.seq}`,
+                toolCallId,
+                role: "tool",
+                content: JSON.stringify({
+                    outcome: evidence.outcome,
+                    ...(evidence.code === undefined ? {} : { code: evidence.code }),
+                }),
+                timestamp,
+            },
+        ];
+    }
+    const stepName = evidence.name === undefined ? evidence.kind : `${evidence.kind}:${evidence.name}`;
+    if (evidence.outcome === "started")
+        return [{ type: "STEP_STARTED", stepName, timestamp }];
+    return [{ type: "STEP_FINISHED", stepName, timestamp }];
+}
+function lastUserMessage(messages) {
+    if (!Array.isArray(messages))
+        return undefined;
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = asRecord(messages[index]);
+        if (message !== undefined && message.role === "user")
+            return message.content;
+    }
+    return undefined;
+}
+function parseResume(raw) {
+    const record = asRecord(raw);
+    if (record === undefined)
+        return undefined;
+    const continuation = asRecord(record.continuation);
+    if (continuation === undefined)
+        return undefined;
+    const kind = continuation.kind;
+    if (typeof kind !== "string" || !PENDING_KINDS.includes(kind))
+        return undefined;
+    if (typeof continuation.effectId !== "string")
+        return undefined;
+    if (continuation.tool !== undefined && typeof continuation.tool !== "string")
+        return undefined;
+    const approval = asRecord(record.approval);
+    return {
+        continuation: {
+            kind: kind,
+            ...(continuation.tool === undefined ? {} : { tool: continuation.tool }),
+            ...(Object.hasOwn(continuation, "input") ? { input: continuation.input } : {}),
+            effectId: continuation.effectId,
+        },
+        ...(approval !== undefined && typeof approval.granted === "boolean"
+            ? {
+                approval: {
+                    granted: approval.granted,
+                    ...(typeof approval.reason === "string" ? { reason: approval.reason } : {}),
+                },
+            }
+            : {}),
+    };
+}
+/**
+ * Parse the spec `RunAgentInput.resume` array. The runtime holds no interrupt registry - the
+ * interrupt id IS the turn id, and the entry's `payload` must echo the interrupt's
+ * `metadata.continuation`. A single pending suspension means a single entry; extras are ignored.
+ */
+function parseResumeEntry(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const entry = asRecord(raw[0]);
+    if (entry === undefined)
+        return undefined;
+    const interruptId = entry.interruptId;
+    if (typeof interruptId !== "string" || !TURN_ID_PATTERN.test(interruptId))
+        return undefined;
+    const status = entry.status;
+    if (status !== "resolved" && status !== "cancelled")
+        return undefined;
+    const payload = asRecord(entry.payload) ?? {};
+    const approval = asRecord(payload.approval);
+    const resume = parseResume({
+        continuation: payload.continuation,
+        // A cancelled entry without an explicit approval decision resumes as a denial.
+        approval: approval ?? (status === "cancelled" ? { granted: false } : undefined),
+    });
+    if (resume === undefined)
+        return undefined;
+    return { turnId: interruptId, resume };
+}
+function asRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    return value;
+}
+function jsonResponse(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json; charset=utf-8" },
+    });
+}
+function render(response) {
+    return response instanceof Response ? response : toResponse(response, EMPTY_RESPONSE_CONTROLS);
+}
+//# sourceMappingURL=index.js.map