@nylorun/runtime 0.13.0-beta → 0.14.0-beta

package/dist/api/a2a/routes.js

@@ -0,0 +1,289 @@
+/**
+ * The A2A endpoint (Host feature `a2a-endpoint`): `POST /v1/a2a/agents/:agent` answers A2A 1.0
+ * JSON-RPC for one subject, and `GET /v1/a2a/agents/:agent/card` returns the agent's card
+ * without interfaces. v1 serves `SendMessage` (blocking, or `returnImmediately`), `GetTask`
+ * and `CancelTask`; every other operation answers with the error the specification defines
+ * for it (docs: `implementation/a2a-implementation.md`).
+ *
+ * Every task operation goes through the session contract as the caller: `command` with the
+ * caller's scope (limits and owner checks apply), sessions derived from the caller's own
+ * subject, history from Durable Streams. A task id from the client only selects a context and
+ * a turn within the caller's own sessions, so another subject's task is `TaskNotFoundError`.
+ */
+import { randomUUID } from "node:crypto";
+import { SessionCommandSchema, } from "@nylorun/core/contracts";
+import { commandKey } from "../../core/flow-host.js";
+import { agentCard } from "./card.js";
+import { A2aError, a2aFail, checkVersion, jsonRpcError, jsonRpcResult, parseEnvelope, parseSendParams, parseTaskParams, } from "./protocol.js";
+import { SETTLED_EVENTS, buildTask, contextSessionId, newContextId, parseTaskId, pendingInteraction, taskIdOf, } from "./tasks.js";
+import { accessOf } from "../../tenant/auth.js";
+import { command } from "../../tenant/commands.js";
+import { loadSession, } from "../../tenant/context.js";
+import { HttpError, fail } from "../../tenant/http.js";
+import { observeSession, readHistory } from "../../tenant/session-streams.js";
+import { putSession } from "../../tenant/sessions.js";
+/**
+ * How long a blocking `SendMessage` waits for the task to end or ask for input. After it, the
+ * task is returned `WORKING` and keeps running; the caller polls `GetTask`.
+ */
+export const A2A_BLOCKING_WAIT_MS = 5 * 60_000;
+/** `GET /v1/a2a/agents/:agent/card`: the agent's card, for a caller who may use the agent. */
+export async function a2aCard(ctx, scope, agentId) {
+    return agentCard(agentId, await definitionFor(ctx, agentId, accessOf(scope)));
+}
+/**
+ * `POST /v1/a2a/agents/:agent`: one A2A JSON-RPC call, for a subject. JSON-RPC answers (errors
+ * included) are the body to send with 200; HTTP-level refusals (unknown agent, no subject,
+ * limits) are thrown as `HttpError` like any Tenant route. `body` is read once the agent is
+ * known to be the caller's; closing `response` stops a blocking wait, never the task.
+ */
+export async function a2aCall(ctx, scope, agentId, input, response) {
+    const access = accessOf(scope);
+    if (!access)
+        return fail(400, "Acting for a subject is required: send Nylorun-Subject and Nylorun-Scopes", {
+            code: "subject_required",
+        });
+    await definitionFor(ctx, agentId, access);
+    const envelope = parseEnvelope(await input.body());
+    if (!envelope.ok)
+        return jsonRpcError(envelope.id, envelope.error);
+    // A blocking call stops waiting when the caller hangs up; the task keeps running.
+    const hangup = new AbortController();
+    response.on("close", () => hangup.abort());
+    const caller = { ctx, scope, access, agentId };
+    const { id } = envelope.request;
+    try {
+        checkVersion(input.version);
+        return jsonRpcResult(id, await operation(caller, envelope.request, hangup.signal));
+    }
+    catch (error) {
+        if (error instanceof A2aError)
+            return jsonRpcError(id, error);
+        // Limits, scopes and unavailable streams stay HTTP answers, as on every Tenant route.
+        if (error instanceof HttpError && [403, 429, 503].includes(error.status))
+            throw error;
+        ctx.config.logger.warn("a2a request failed", {
+            agentId,
+            method: envelope.request.method,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return jsonRpcError(id, new A2aError("internal", "Internal error"));
+    }
+}
+async function operation(caller, request, signal) {
+    switch (request.method) {
+        case "SendMessage":
+            return sendMessage(caller, request.params, signal);
+        case "GetTask": {
+            const params = parseTaskParams(request.params);
+            return (await ownedTask(caller, params.id, params.historyLength)).task;
+        }
+        case "CancelTask":
+            return cancelTask(caller, parseTaskParams(request.params).id);
+        case "ListTasks":
+            return a2aFail("unsupportedOperation", "ListTasks is not supported by this agent yet");
+        case "SendStreamingMessage":
+        case "SubscribeToTask":
+            return a2aFail("unsupportedOperation", "Streaming is not supported: the Agent Card declares capabilities.streaming false");
+        case "CreateTaskPushNotificationConfig":
+        case "GetTaskPushNotificationConfig":
+        case "ListTaskPushNotificationConfigs":
+        case "DeleteTaskPushNotificationConfig":
+            return a2aFail("pushNotSupported", "Push notifications are not supported");
+        case "GetExtendedAgentCard":
+            return a2aFail("unsupportedOperation", "This agent has no extended Agent Card");
+        default:
+            return a2aFail("methodNotFound", `Method ${request.method} not found`);
+    }
+}
+/** The agent's definition, or a `404` when it is missing or the caller may not use it. */
+async function definitionFor(ctx, agentId, access) {
+    if (access?.agents !== undefined && !access.agents.has(agentId))
+        return fail(404, "Agent not found");
+    const definition = await ctx.store.tx((t) => t.get("definitions", agentId));
+    return definition ?? fail(404, "Agent not found");
+}
+const taskNotFound = (taskId) => a2aFail("taskNotFound", "Task not found", { taskId });
+/** The caller's session for a context, or undefined when it does not exist yet. */
+async function contextSession(caller, sessionId) {
+    try {
+        return await loadSession(caller.ctx, sessionId, caller.access);
+    }
+    catch (error) {
+        if (error instanceof HttpError && error.status === 404)
+            return undefined;
+        throw error;
+    }
+}
+/** The events of one turn, in stream order. */
+async function turnEvents(ctx, sessionId, turnId) {
+    const { items } = await readHistory(ctx, sessionId, undefined, undefined);
+    return items.filter((event) => event.turnId === turnId);
+}
+async function ownedTask(caller, taskId, historyLength) {
+    const ids = parseTaskId(taskId) ?? taskNotFound(taskId);
+    const sessionId = contextSessionId(caller.access.owner, caller.agentId, ids.contextId);
+    const session = (await contextSession(caller, sessionId)) ?? taskNotFound(taskId);
+    const task = buildTask({
+        ...ids,
+        session,
+        events: await turnEvents(caller.ctx, sessionId, ids.turnId),
+        ...(historyLength !== undefined ? { historyLength } : {}),
+    }) ?? taskNotFound(taskId);
+    return { task, session, sessionId, ...ids };
+}
+/** Runs a session command as the caller, mapping the Runtime's refusals to A2A errors. */
+async function run(caller, sessionId, input, 
+/** The error for a `409` conflict: the session is busy or no longer waiting. */
+conflict) {
+    try {
+        const accepted = (await command(caller.ctx, sessionId, SessionCommandSchema.parse(input), caller.scope));
+        return { turnId: accepted.turnId, cursor: accepted.cursor };
+    }
+    catch (error) {
+        if (!(error instanceof HttpError) || error.status !== 409)
+            throw error;
+        if (error.message.startsWith("Idempotency key"))
+            return a2aFail("invalidParams", "message.messageId was already used for a different message", {}, "message.messageId");
+        throw await conflict();
+    }
+}
+/** Opens the caller's session for a context: created when missing, never changed after. */
+async function openContext(caller, sessionId) {
+    const existing = await contextSession(caller, sessionId);
+    if (existing)
+        return existing;
+    return putSession(caller.ctx, sessionId, {
+        requestId: randomUUID(),
+        agentId: caller.agentId,
+        ownerUserId: caller.access.owner,
+    }, caller.access);
+}
+async function sendMessage(caller, params, signal) {
+    const send = parseSendParams(params);
+    const idempotencyKey = `a2a:${send.messageId}`;
+    const value = "content" in send.input ? send.input.content : send.input.data;
+    let contextId;
+    let sessionId;
+    let accepted;
+    if (send.taskId !== undefined) {
+        // A reply on an existing task: only a question it is waiting on can take it.
+        const ids = parseTaskId(send.taskId) ?? taskNotFound(send.taskId);
+        if (send.contextId !== undefined && send.contextId !== ids.contextId)
+            a2aFail("invalidParams", "message.contextId does not match the task's context", {}, "message.contextId");
+        contextId = ids.contextId;
+        sessionId = contextSessionId(caller.access.owner, caller.agentId, contextId);
+        const session = (await contextSession(caller, sessionId)) ?? taskNotFound(send.taskId);
+        const prior = await caller.ctx.store.tx((t) => t.get("commands", commandKey(sessionId, idempotencyKey)));
+        // A retried reply replays through `command`, which compares it with the first one.
+        const interactionId = prior?.command.type === "respond"
+            ? prior.command.interactionId
+            : prior
+                ? a2aFail("invalidParams", "message.messageId was already used for a different message", {}, "message.messageId")
+                : await replyTarget(caller, session, sessionId, ids.turnId, send.taskId);
+        accepted = await run(caller, sessionId, {
+            type: "respond",
+            requestId: randomUUID(),
+            idempotencyKey,
+            interactionId,
+            value,
+        }, async () => new A2aError("unsupportedOperation", "The task is no longer waiting for input", {
+            taskId: send.taskId,
+        }));
+        accepted = { ...accepted, turnId: ids.turnId };
+    }
+    else {
+        contextId =
+            send.contextId ?? newContextId(caller.access.owner, caller.agentId, send.messageId);
+        sessionId = contextSessionId(caller.access.owner, caller.agentId, contextId);
+        await openContext(caller, sessionId);
+        const context = contextId;
+        accepted = await run(caller, sessionId, {
+            type: "message",
+            requestId: randomUUID(),
+            idempotencyKey,
+            ...send.input,
+        }, async () => {
+            const active = (await contextSession(caller, sessionId))?.activeTurnId;
+            const taskId = active ? taskIdOf(context, active) : undefined;
+            return taskId
+                ? new A2aError("unsupportedOperation", `The context has a task in progress (${taskId}); reply to it or cancel it`, { taskId })
+                : new A2aError("unsupportedOperation", "The context has unresolved work; start a new context");
+        });
+    }
+    if (!send.returnImmediately)
+        await settled(caller.ctx, sessionId, accepted.turnId, accepted.cursor, signal);
+    const { task } = await ownedTask(caller, taskIdOf(contextId, accepted.turnId), send.historyLength);
+    return { task };
+}
+/** The interaction a reply answers: the task must be active and paused on a question. */
+async function replyTarget(caller, session, sessionId, turnId, taskId) {
+    if (session.activeTurnId !== turnId) {
+        // Ended, or never this caller's: a terminal task takes no more messages.
+        const task = buildTask({
+            contextId: parseTaskId(taskId).contextId,
+            turnId,
+            session,
+            events: await turnEvents(caller.ctx, sessionId, turnId),
+        });
+        if (!task)
+            return taskNotFound(taskId);
+        return a2aFail("unsupportedOperation", "The task is in a terminal state and accepts no more messages; send a new message without taskId", { taskId });
+    }
+    const pending = session.status === "paused" ? pendingInteraction(session) : undefined;
+    if (!pending)
+        return a2aFail("unsupportedOperation", "The task is working and not waiting for input; wait for it or cancel it", { taskId });
+    if (pending.kind === "approval")
+        return a2aFail("unsupportedOperation", "The task waits for an approval, which A2A callers cannot give yet; cancel the task instead", { taskId });
+    return pending.id;
+}
+async function cancelTask(caller, taskId) {
+    const owned = await ownedTask(caller, taskId);
+    if (owned.session.activeTurnId !== owned.turnId) {
+        if (owned.task.status.state === "TASK_STATE_CANCELED")
+            return owned.task;
+        return a2aFail("taskNotCancelable", "The task has already finished and cannot be canceled", {
+            taskId,
+            state: owned.task.status.state,
+        });
+    }
+    try {
+        await command(caller.ctx, owned.sessionId, {
+            type: "cancel",
+            requestId: randomUUID(),
+            idempotencyKey: `a2a-cancel:${owned.turnId}`,
+            reason: "Canceled by the A2A client",
+        }, caller.scope);
+    }
+    catch (error) {
+        if (!(error instanceof HttpError) || error.status !== 409)
+            throw error;
+    }
+    return (await ownedTask(caller, taskId)).task;
+}
+/**
+ * Waits until the turn ends, pauses or has an uncertain effect, the caller hangs up, or
+ * `A2A_BLOCKING_WAIT_MS` passes. Follows the session's shared stream from the command's
+ * cursor, so the events the task is built from are there when it returns. A feed that ends
+ * (reset, deleted, closing) ends the wait: the task says what the session says then.
+ */
+async function settled(ctx, sessionId, turnId, cursor, signal) {
+    const stop = new AbortController();
+    const timer = setTimeout(() => stop.abort(), A2A_BLOCKING_WAIT_MS);
+    timer.unref();
+    const hangup = () => stop.abort();
+    signal.addEventListener("abort", hangup, { once: true });
+    if (signal.aborted)
+        stop.abort();
+    try {
+        for await (const event of observeSession(ctx, sessionId, cursor, {
+            signal: stop.signal,
+        }))
+            if (event.turnId === turnId && SETTLED_EVENTS.has(event.type))
+                return;
+    }
+    finally {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", hangup);
+    }
+}

package/dist/api/a2a/tasks.d.ts

@@ -0,0 +1,50 @@
+import type { LiveEvent } from "@nylorun/core/contracts";
+import type { Message, Task } from "./protocol.js";
+export declare function taskIdOf(contextId: string, turnId: string): string;
+/** The context and turn a task id names, or undefined for anything this Runtime never issued. */
+export declare function parseTaskId(id: string): {
+    contextId: string;
+    turnId: string;
+} | undefined;
+/** The session behind a subject's A2A context with one agent. */
+export declare function contextSessionId(subject: string, agentId: string, contextId: string): string;
+/**
+ * The context the Runtime generates for a message that names none: derived from the message
+ * id, so a retried message lands in the same context and replays instead of starting a task.
+ * UUID-shaped, and opaque to clients.
+ */
+export declare function newContextId(subject: string, agentId: string, messageId: string): string;
+/** The session fields a task's state comes from (`Session` in `tenant/context.ts`). */
+export interface SessionSnapshot {
+    readonly status: string;
+    readonly activeTurnId: string | null;
+    readonly lastTurnId?: string;
+    readonly lastOutput?: unknown;
+    readonly waits?: unknown;
+}
+/** An interaction the paused turn waits for. */
+export interface PendingInteraction {
+    readonly id: string;
+    readonly kind: string;
+    readonly prompt: string;
+}
+/** The first interaction a paused session waits for. */
+export declare function pendingInteraction(session: SessionSnapshot): PendingInteraction | undefined;
+/** Events after which a blocking `SendMessage` returns: the turn ended or is interrupted. */
+export declare const SETTLED_EVENTS: ReadonlySet<string>;
+/** The turn's conversation as A2A messages: what the caller sent and what the agent said. */
+export declare function historyOf(events: readonly LiveEvent[], contextId: string, taskId: string): Message[];
+export interface BuildTaskInput {
+    readonly contextId: string;
+    readonly turnId: string;
+    readonly session: SessionSnapshot;
+    /** Every event of the turn, in stream order. */
+    readonly events: readonly LiveEvent[];
+    readonly historyLength?: number;
+}
+/**
+ * The task for one turn, or undefined when the session never had that turn. An active turn
+ * takes its state from the session row; an ended one from its terminal event, or from the row
+ * while that event has not reached the stream yet.
+ */
+export declare function buildTask(input: BuildTaskInput): Task | undefined;

package/dist/api/a2a/tasks.js

@@ -0,0 +1,186 @@
+/**
+ * A2A tasks over Nylorun sessions: a context is one session per subject, agent and
+ * `contextId`; a task is one turn of it. The task id names both (`t1.<context>.<turn>`) until
+ * the turn index lets a turn id stand alone; it is parsed, never trusted, because the session
+ * is always derived from the caller's own subject. `buildTask` reads the state from the session
+ * row and the turn's events; nothing here touches the store.
+ */
+import { createHash } from "node:crypto";
+const TASK_ID_PREFIX = "t1";
+export function taskIdOf(contextId, turnId) {
+    return `${TASK_ID_PREFIX}.${Buffer.from(contextId, "utf8").toString("base64url")}.${turnId}`;
+}
+/** The context and turn a task id names, or undefined for anything this Runtime never issued. */
+export function parseTaskId(id) {
+    const [prefix, context, turnId, ...rest] = id.split(".");
+    if (prefix !== TASK_ID_PREFIX || !context || !turnId || rest.length > 0)
+        return undefined;
+    if (!/^[A-Za-z0-9_-]+$/.test(context) || !/^[A-Za-z0-9-]{1,64}$/.test(turnId))
+        return undefined;
+    const contextId = Buffer.from(context, "base64url").toString("utf8");
+    // Only the canonical encoding: two ids must never name one task.
+    if (taskIdOf(contextId, turnId) !== id)
+        return undefined;
+    return { contextId, turnId };
+}
+/** The session behind a subject's A2A context with one agent. */
+export function contextSessionId(subject, agentId, contextId) {
+    return createHash("sha256")
+        .update(`a2a\u0000${subject}\u0000${agentId}\u0000${contextId}`)
+        .digest("hex")
+        .slice(0, 32);
+}
+/**
+ * The context the Runtime generates for a message that names none: derived from the message
+ * id, so a retried message lands in the same context and replays instead of starting a task.
+ * UUID-shaped, and opaque to clients.
+ */
+export function newContextId(subject, agentId, messageId) {
+    const hex = createHash("sha256")
+        .update(`a2a-context\u0000${subject}\u0000${agentId}\u0000${messageId}`)
+        .digest("hex");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-8${hex.slice(13, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+/** The first interaction a paused session waits for. */
+export function pendingInteraction(session) {
+    if (!Array.isArray(session.waits))
+        return undefined;
+    for (const call of session.waits) {
+        const interaction = call?.interaction;
+        if (call?.status !== "interaction" || typeof interaction?.id !== "string")
+            continue;
+        return {
+            id: interaction.id,
+            kind: typeof interaction.kind === "string" ? interaction.kind : "response",
+            prompt: typeof interaction.prompt === "string" ? interaction.prompt : "",
+        };
+    }
+    return undefined;
+}
+const ENDED = new Set(["turn.completed", "turn.failed", "turn.cancelled"]);
+/** Events after which a blocking `SendMessage` returns: the turn ended or is interrupted. */
+export const SETTLED_EVENTS = new Set([
+    ...ENDED,
+    "turn.paused",
+    "effect.uncertain",
+]);
+/** A turn output as one part: text for a string, JSON data for anything else. */
+function outputPart(output) {
+    return typeof output === "string"
+        ? { text: output }
+        : { data: output, mediaType: "application/json" };
+}
+function valuePart(value) {
+    return typeof value === "string" ? { text: value } : { data: value ?? null };
+}
+/** The client's own message id when an A2A caller sent the command. */
+function clientMessageId(event) {
+    const key = event.payload?.idempotencyKey;
+    return typeof key === "string" && key.startsWith("a2a:") ? key.slice(4) : event.eventId;
+}
+/** The turn's conversation as A2A messages: what the caller sent and what the agent said. */
+export function historyOf(events, contextId, taskId) {
+    const messages = [];
+    const add = (messageId, role, parts) => messages.push({ messageId, role, parts, contextId, taskId });
+    for (const event of events) {
+        const payload = (event.payload ?? {});
+        switch (event.type) {
+            case "command.message":
+                add(clientMessageId(event), "ROLE_USER", ["content" in payload ? { text: String(payload.content) } : valuePart(payload.data)]);
+                break;
+            case "command.respond":
+                add(clientMessageId(event), "ROLE_USER", [valuePart(payload.value)]);
+                break;
+            case "message.assistant":
+                // Agents used as tools speak inside the turn; only the agent's own words are history.
+                if (!payload.agent && typeof payload.text === "string" && payload.text.trim() !== "")
+                    add(event.eventId, "ROLE_AGENT", [{ text: payload.text }]);
+                break;
+            case "turn.paused":
+                for (const entry of Array.isArray(payload.interactions) ? payload.interactions : []) {
+                    const interaction = entry?.interaction;
+                    if (typeof interaction?.id === "string" && typeof interaction.prompt === "string")
+                        add(interaction.id, "ROLE_AGENT", [{ text: interaction.prompt }]);
+                }
+                break;
+        }
+    }
+    return messages;
+}
+function agentMessage(messageId, text, contextId, taskId) {
+    return { messageId, role: "ROLE_AGENT", parts: [{ text }], contextId, taskId };
+}
+function failureText(code) {
+    return typeof code === "string" && code !== ""
+        ? `The agent failed (${code}).`
+        : "The agent failed.";
+}
+/**
+ * The task for one turn, or undefined when the session never had that turn. An active turn
+ * takes its state from the session row; an ended one from its terminal event, or from the row
+ * while that event has not reached the stream yet.
+ */
+export function buildTask(input) {
+    const { contextId, turnId, session, events } = input;
+    const taskId = taskIdOf(contextId, turnId);
+    const active = session.activeTurnId === turnId;
+    const terminal = [...events].reverse().find((event) => ENDED.has(event.type));
+    const latest = session.lastTurnId === turnId && !active;
+    if (!active && !terminal && !latest && events.length === 0)
+        return undefined;
+    let state;
+    let message;
+    let artifacts;
+    const complete = (output) => {
+        state = "TASK_STATE_COMPLETED";
+        if (output !== undefined && output !== null)
+            artifacts = [{ artifactId: "output", name: "output", parts: [outputPart(output)] }];
+    };
+    if (active) {
+        const pending = session.status === "paused" ? pendingInteraction(session) : undefined;
+        if (pending) {
+            state = "TASK_STATE_INPUT_REQUIRED";
+            message = agentMessage(pending.id, pending.prompt, contextId, taskId);
+        }
+        else {
+            state = "TASK_STATE_WORKING";
+            if (session.status === "uncertain")
+                message = agentMessage(`${turnId}:uncertain`, "An action's outcome is uncertain; the agent's operator must resolve it before the task continues.", contextId, taskId);
+        }
+    }
+    else if (terminal) {
+        const payload = (terminal.payload ?? {});
+        if (terminal.type === "turn.completed")
+            complete(payload.output);
+        else if (terminal.type === "turn.cancelled")
+            state = "TASK_STATE_CANCELED";
+        else {
+            state = "TASK_STATE_FAILED";
+            message = agentMessage(`${turnId}:failed`, failureText(payload.error?.code), contextId, taskId);
+        }
+    }
+    else if (latest && session.status === "completed")
+        complete(session.lastOutput);
+    else if (latest && session.status === "cancelled")
+        state = "TASK_STATE_CANCELED";
+    else if (latest && session.status === "failed") {
+        state = "TASK_STATE_FAILED";
+        message = agentMessage(`${turnId}:failed`, failureText(undefined), contextId, taskId);
+    }
+    else
+        state = "TASK_STATE_WORKING";
+    const timestamp = events.at(-1)?.time;
+    const history = historyOf(events, contextId, taskId);
+    const limit = input.historyLength;
+    return {
+        id: taskId,
+        contextId,
+        status: {
+            state: state,
+            ...(message ? { message } : {}),
+            ...(timestamp ? { timestamp } : {}),
+        },
+        ...(artifacts ? { artifacts } : {}),
+        ...(limit === 0 ? {} : { history: limit === undefined ? history : history.slice(-limit) }),
+    };
+}

package/dist/api/ag-ui/endpoint.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The AG-UI endpoint's routes (`/v1/ag-ui/agents/{agentId}/**`), declared for serving and for
+ * the Runtime's OpenAPI document. What each does is in `routes.ts`; a run and a reattached run
+ * stream AG-UI events on the Node response, as server-sent events.
+ */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { TenantEnv } from "../http/app.js";
+export declare function agUiRoutes(api: OpenAPIHono<TenantEnv>): void;

package/dist/api/ag-ui/endpoint.js

@@ -0,0 +1,126 @@
+import { RESPONSE_ALREADY_SENT } from "@hono/node-server/utils/response";
+import { z } from "zod";
+import { EventSchemas, MessageSchema, RunAgentInputSchema } from "@ag-ui/core/schemas";
+import { readJson } from "../http/body.js";
+import { tenantRoute } from "../http/define.js";
+import { jsonResponse } from "../http/respond.js";
+import { agUiCaller, cancelRun, reattachRun, startRun, threadMessages } from "./routes.js";
+import { sessionIdFor } from "./session-id.js";
+/**
+ * AG-UI's own schemas (`@ag-ui/core`), as components of the document. They are converted by
+ * Zod itself: zod-to-openapi does not know some of the types they use.
+ */
+const COMPONENTS = {
+    AgUiRunAgentInput: RunAgentInputSchema,
+    AgUiEvent: EventSchemas,
+    AgUiMessage: MessageSchema,
+};
+const ref = (name) => ({ $ref: `#/components/schemas/${name}` });
+function registerComponents(api) {
+    for (const [name, schema] of Object.entries(COMPONENTS)) {
+        const { $schema: _dialect, ...component } = z.toJSONSchema(schema, {
+            io: "input",
+            reused: "inline",
+            unrepresentable: "any",
+        });
+        api.openAPIRegistry.registerComponent("schemas", name, component);
+    }
+}
+const FOR_A_PERSON = {
+    credentials: ["subject", "token"],
+    scopes: ["sessions:own"],
+    browser: true,
+};
+const events = (description) => ({
+    description,
+    content: { "text/event-stream": { itemSchema: ref("AgUiEvent") } },
+});
+const agentId = z.object({ agentId: z.string() });
+const thread = agentId.extend({ threadId: z.string() });
+const TAGS = ["AG-UI"];
+/** The person the request acts for, who may use the agent. */
+function callerOf(c) {
+    const scope = c.get("scope");
+    return { scope, ...agUiCaller(scope, c.req.param("agentId")) };
+}
+export function agUiRoutes(api) {
+    registerComponents(api);
+    tenantRoute(api, FOR_A_PERSON, {
+        method: "post",
+        path: "/v1/ag-ui/agents/{agentId}",
+        tags: TAGS,
+        summary: "Run an agent",
+        description: "For a person, named by a subject token or by `Nylorun-Subject`. The thread is one session per person, agent and thread, created on its first run with `forwardedProps.nylorun.session`. The trailing user message starts a turn (its id is the idempotency key); `resume` answers interrupts. A busy session or a turn limit is a `RUN_ERROR` in the stream.",
+        request: {
+            params: agentId,
+            body: {
+                required: true,
+                content: { "application/json": { schema: ref("AgUiRunAgentInput") } },
+            },
+        },
+        responses: { 200: events("The run's events, from RUN_STARTED to its end") },
+    }, async (c) => {
+        const { scope, subject, access } = callerOf(c);
+        await startRun(c.env.tenant, scope, c.req.param("agentId"), { subject, access }, await readJson(c.req.raw), c.env.outgoing);
+        return RESPONSE_ALREADY_SENT;
+    });
+    tenantRoute(api, FOR_A_PERSON, {
+        method: "get",
+        path: "/v1/ag-ui/agents/{agentId}/threads/{threadId}/messages",
+        tags: TAGS,
+        summary: "Get a thread's messages",
+        request: { params: thread },
+        responses: {
+            200: {
+                description: "The thread's messages; none before its first run",
+                content: {
+                    "application/json": { schema: { type: "array", items: ref("AgUiMessage") } },
+                },
+            },
+        },
+    }, async (c) => {
+        const { subject, access } = callerOf(c);
+        const id = sessionIdFor(subject, c.req.param("agentId"), c.req.param("threadId"));
+        return jsonResponse(200, await threadMessages(c.env.tenant, id, access));
+    });
+    tenantRoute(api, FOR_A_PERSON, {
+        method: "get",
+        path: "/v1/ag-ui/agents/{agentId}/threads/{threadId}/events",
+        tags: TAGS,
+        summary: "Reattach to a run",
+        description: "The rest of a run after a dropped connection, from `Last-Event-ID` or `cursor`.",
+        request: {
+            params: thread,
+            query: z.object({
+                cursor: z.string().optional(),
+                runId: z.string().optional().meta({ description: "The run to report events as" }),
+            }),
+        },
+        responses: {
+            200: events("The run's remaining events"),
+            204: { description: "Nothing to send: no run is going, and none ended after the cursor" },
+        },
+    }, async (c) => {
+        const { scope, subject, access } = callerOf(c);
+        const threadId = c.req.param("threadId");
+        const header = c.env.incoming.headers["last-event-id"];
+        await reattachRun(c.env.tenant, scope, access, { threadId, id: sessionIdFor(subject, c.req.param("agentId"), threadId) }, {
+            lastEventId: typeof header === "string" ? header : undefined,
+            cursor: c.req.query("cursor"),
+            runId: c.req.query("runId"),
+        }, c.env.outgoing);
+        return RESPONSE_ALREADY_SENT;
+    });
+    tenantRoute(api, FOR_A_PERSON, {
+        method: "post",
+        path: "/v1/ag-ui/agents/{agentId}/threads/{threadId}/cancel",
+        tags: TAGS,
+        summary: "Cancel a thread's running turn",
+        request: { params: thread },
+        responses: { 204: { description: "Cancelled" } },
+    }, async (c) => {
+        const { scope, subject } = callerOf(c);
+        await cancelRun(c.env.tenant, sessionIdFor(subject, c.req.param("agentId"), c.req.param("threadId")), scope);
+        return new Response(null, { status: 204 });
+    });
+}

package/dist/api/ag-ui/history.d.ts

@@ -0,0 +1,7 @@
+/**
+ * An AG-UI transcript rebuilt from a session's log, with the ids a live run gave each
+ * message (see `translate.ts`), usable as `HttpAgent`'s `initialMessages`.
+ */
+import type { Message } from "@ag-ui/core";
+import { type LiveEvent } from "@nylorun/core/contracts";
+export declare function messagesFromEvents(items: readonly LiveEvent[]): Message[];