@nylorun/agents 0.6.0-beta → 0.8.0-beta

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @nylorun/agents
 
+## 0.8.0-beta
+
+### Minor Changes
+
+- a322696: **`@nylorun/agents/ag-ui`: serve agents to AG-UI clients from your own server.** `createAgUiHandler({ basePath, agents, subject })` returns a web-standard `fetch` handler (plus `run`, `history`, `reattach` and `cancel`), and `toNodeListener` adapts it to `node:http` and Express.
+
+  - One session per person, agent and thread; the AG-UI message id is the idempotency key, so a retried run replays the same turn.
+  - Approvals become AG-UI interrupts and resume through `runAgent({ resume })`.
+  - History returns a plain AG-UI `Message[]` with the ids the live run used; reattach continues a run from `Last-Event-ID`.
+  - Needs a Runtime with `transcript-events`. Adds the `@ag-ui/core` dependency (`~1.0.0`), loaded only by this subpath.
+
+  `AgentsClient.hostFeatures()` returns the Runtime's protocol features, including optional ones.
+
+- 844bff3: **Act for a person: `Nylorun-Subject` and `Nylorun-Scopes`.** An app server that holds the Tenant key can name the person each request is for, and the Runtime enforces it (optional Host feature `subject-headers`).
+
+  - `client.as(subject, { scopes })` in `@nylorun/agents` sends both headers on every call, event streams included. Scopes: `agents:read`, `agents:write`, `sessions:own`, `vaults:own`, `tenant:settings`; default `["sessions:own"]`.
+  - The Runtime limits a subject to the routes its scopes allow (`403 scope_required`) and to its own sessions and vaults: another owner's session, vault or sandbox is the same `404` as a missing one, including `PUT` on its session id (was `409`). Reset, config seed, executors, actions and the sandbox tool routes are open to no subject. Only application keys may send the headers.
+  - The AG-UI handler calls the Runtime as each person and requires `subject-headers`; new optional `scopes` option. The host's `session()` parameters can no longer replace a session's id, agent or owner.
+  - Core exports `SUBJECT_HEADER`, `SCOPES_HEADER`, `SUBJECT_SCOPES` and `parseSubjectHeaders`. Postgres Tenant schemas migrate to version 2 (an indexed session owner column).
+
+  Requests without `Nylorun-Subject` are unchanged.
+
+### Patch Changes
+
+- 42272f8: The AG-UI handler answers `400` (`invalid_request`) when the Runtime refuses what the client sent, such as a `Last-Event-ID` it cannot read, instead of `502`.
+- Pin core to the tested release.
+- Updated dependencies [a322696]
+- Updated dependencies [844bff3]
+- Updated dependencies [a322696]
+  - @nylorun/core@0.7.0-beta
+
+## 0.7.0-beta
+
+### Minor Changes
+
+- bf1c2da: **Tenants can register a Studio principal.** `CreateTenantRequest` gains optional `studioCredentialHash` behind the new protocol feature `studio-principal`; the Runtime stores it as application principal `studio`, and idempotent create compares it too. `@nylorun/admin` exports `deriveStudioToken(adminKey, tenantId)` (HMAC-SHA256 over `nylorun/studio/v1`, NUL, Tenant id) and `createTenant` sends the hash of that key, so Studio can reach any Tenant's API with a key derived from the admin key. Clients require the new feature, so upgrade the Runtime with them.
+
+### Patch Changes
+
+- ba1b239: **`nylorun` sets up the local stack; `@nylorun/cli` becomes the Runtime client `nylo` (breaking beta).**
+
+  - New unscoped package **`nylorun`**: `npx nylorun up` sets up the Docker stack on the first run and starts it after that, from any directory; `npx nylorun down` stops it (volumes are kept). `up` and `down` are aliases of `start` and `stop`. It also owns `status`, `logs`, `studio`, `reset` and `doctor`, pins the Runtime and Studio images (`package.json` `nylorun.runtime` / `nylorun.studio`), depends on `@nylorun/core` only, and never creates Tenants.
+  - **`@nylorun/cli`** is the Runtime client with the command **`nylo`**: `nylo tenant create [name]` (creates the Tenant; in a project, writes the Project link and seeds the model provider and sandbox from `.env`), `nylo tenant current|list|use|status|reset|delete`, `nylo configure`, `nylo env` (was `nylorun status --env`) and `nylo doctor sandbox`. It no longer provides the `nylorun` command or the stack commands.
+  - **Removed:** `nylorun dev` and `nylorun dev --ephemeral`. Link once with `nylo tenant create`, then run the project's own `npm run dev`. Moved commands exit 2 and name their replacement.
+  - **Starter:** the generated project depends on `@nylorun/agents` only (no Nylorun devDependency); `dev` is `tsx watch --env-file-if-exists=.env src/main.ts`. `npm create @nylorun/agent` installs the project and prints the next steps (`npx nylorun up`, `npx @nylorun/cli tenant create`, `npm run dev`) instead of starting development; `--no-open` is accepted and ignored.
+  - `connectAgents` names those steps when it finds no Runtime connection. Runtime repair hints, model errors and core's sandbox message name `nylo` and `nylorun up`.
+
+- bf1c2da: **The microsandbox backend is removed; the Runtime runs sandbox tools on the virtual backend only.** The optional `microsandbox` dependency is gone. `sandbox.backend` and `NYLORUN_SANDBOX` accept `auto` or `virtual`, and `auto` selects `virtual`. A Tenant that stored `microsandbox` reads it as `auto`. `nylorun doctor sandbox` and the `nylorun dev` banner report only the virtual shell.
+- Pin core to the tested release.
+- Updated dependencies [bf1c2da]
+- Updated dependencies [ba1b239]
+- Updated dependencies [bf1c2da]
+- Updated dependencies [bf1c2da]
+- Updated dependencies [bf1c2da]
+  - @nylorun/core@0.6.0-beta
+
 ## 0.6.0-beta
 
 ### Minor Changes

package/README.md

@@ -19,8 +19,10 @@ await connectAgents({ agents }).ready;
 Application mode saves definitions, registers **derived** executor credentials
 (HMAC of the application key + Tenant + agent id), and connects. Restarts and
 replicas re-register the same hashes; tokens are never stored in the Project.
-The same entry runs under `nylorun dev` and as `node dist/src/main.js`
-(`npm start`). See [MIGRATION.md](../MIGRATION.md#runtime-clients-and-admin-api-breaking-beta)
+The same entry runs under the project's `npm run dev` (`tsx watch`) and as
+`node dist/src/main.js` (`npm start`). It finds the Runtime through the three
+`NYLORUN_*` variables or the Project link that `npx @nylorun/cli tenant create`
+writes; with neither, it fails with `connection_missing` and names those steps. See [MIGRATION.md](../MIGRATION.md#runtime-clients-and-admin-api-breaking-beta)
 for upgrading from `nylorun serve`.
 
 ## Connection resolution
@@ -84,7 +86,7 @@ await connection.close();
 ```
 
 ```sh
-eval "$(npx nylorun runtime status --env)"
+eval "$(npx @nylorun/cli env)"
 # → NYLORUN_RUNTIME_URL, NYLORUN_SERVER_KEY, NYLORUN_TENANT
 ```
 
@@ -143,7 +145,7 @@ const analyst = Agent({
 }).use(sandbox());
 ```
 
-The model gets `bash`, `read`, `write`, `edit`, `grep` and `glob` on a Linux machine with a persistent `/workspace`. These tools run in the Runtime, not in your process, so sandbox-only agents need no connected executor. The agent declares what it needs; the Runtime decides where it runs (a microsandbox VM where the machine supports it, otherwise an emulated shell). Every option is optional plain data:
+The model gets `bash`, `read`, `write`, `edit`, `grep` and `glob` on a Linux machine with a persistent `/workspace`. These tools run in the Runtime, not in your process, so sandbox-only agents need no connected executor. The agent declares what it needs; the Runtime decides where it runs (today an emulated shell in the Runtime process). Every option is optional plain data:
 
 ```ts
 .use(sandbox({
@@ -154,7 +156,7 @@ The model gets `bash`, `read`, `write`, `edit`, `grep` and `glob` on a Linux mac
 }))
 ```
 
-The `dev` preset allows package registries and code hosts. Private networks, loopback, the host and cloud metadata endpoints are always blocked. Options from the full design that are not in this version (`setup`, `files`, `secrets`, `mount`, `onStart`, …) throw a `SandboxError` that says so. See [the sandbox design](../docs/design/sandboxes.md).
+The `dev` preset allows package registries and code hosts. Private networks, loopback, the host and cloud metadata endpoints are always blocked. Options from the full design that are not in this version (`setup`, `files`, `secrets`, `mount`, `onStart`, …) throw a `SandboxError` that says so.
 
 Put an agent in another agent's `tools` to let the model delegate to it:
 
@@ -284,4 +286,107 @@ After registration, `connectAgents` opens authenticated fetch SSE before discove
 
 Tools receive state, info, identity, resume, signal, approval/response helpers and memoized `step`. Step outcomes survive a persisted wait result; they do not establish exactly-once external effects after an unacknowledged crash. `sleep` and `waitFor` currently return inspectable deferred outcomes; automatic timer/event wakeups remain runtime implementation work. Remote `onModelCall` convenience and progress-event transport are not supplied in this pass. Arbitrary middleware closures are rejected for durable definitions; use `before`/`after` hooks. The executor runs every capability registered at a hook point in one action. Agent definitions have no `.run()`; explicit local execution is available through `@nylorun/harness/run`.
 
-The SDK depends only on core within the Nylorun packages; installing it does not install harness. Use `/define`, `/client`, or `/executor` for focused imports, or the root for convenience. Studio uses `/client`. See [the adopted host contract](../harness/HOST_CONTRACT.md).
+## AG-UI
+
+`@nylorun/agents/ag-ui` serves the Tenant's agents to any
+[AG-UI](https://docs.ag-ui.com) client (`@ag-ui/client`'s `HttpAgent`,
+CopilotKit, a desktop renderer) from your own server. Your server signs people
+in and names the person each request is for; the handler maps each AG-UI thread
+to one session per person, agent and thread, and streams it as AG-UI events.
+
+```ts
+import { createServer } from "node:http";
+import { createAgUiHandler, toNodeListener } from "@nylorun/agents/ag-ui";
+import support from "./agents/support.js";
+
+const agui = createAgUiHandler({
+  basePath: "/api/agui",
+  agents: [support], // nothing else is reachable
+  subject: async (request) => (await getSignedInUser(request))?.id, // undefined → 401
+});
+
+createServer(toNodeListener(agui)).listen(3000);
+// Next.js, Hono, Bun, Deno, Workers: export or mount `agui.fetch` directly.
+```
+
+| Method and path under `basePath` | Operation |
+| --- | --- |
+| `POST /{agentId}` | Run: an AG-UI `RunAgentInput` in, server-sent events out |
+| `GET /{agentId}/threads/{threadId}/messages` | History as a plain AG-UI `Message[]`, usable as `HttpAgent`'s `initialMessages` |
+| `GET /{agentId}/threads/{threadId}/events` | Reattach: the rest of a run after a dropped connection, from `Last-Event-ID` (or `?cursor=`); `204` when nothing is left |
+| `POST /{agentId}/threads/{threadId}/cancel` | Cancel the running turn |
+
+`run`, `history`, `reattach` and `cancel` are also on the handler for your own
+routing. The default `client` is `createClient()`; pass `client` to use another
+one, and `session(subject, agentId)` to add the person's `vaultIds` or
+`credentialSelections` (keep `info` stable: it is part of the session's
+identity).
+
+- Each AG-UI message id is the command's idempotency key: a retried run replays
+  the same turn instead of starting a second one.
+- An approval ends the run with an AG-UI interrupt (`reason: "tool_approval"`,
+  `toolCallId` the model's call id). Resume with
+  `runAgent({ resume: [{ interruptId, status: "resolved", payload: { approved: true } }] })`.
+  Other interactions answer with `payload` as the response.
+- Every event that ends a group carries the Runtime cursor as its SSE `id`.
+  `HttpAgent` does not reconnect by itself; call the reattach route with the
+  last id you received.
+- Closing the connection stops reading; it never cancels the turn.
+- A busy or paused thread ends the run with `RUN_ERROR` code `session_busy`.
+- The handler calls the Runtime as each person (`client.as(subject, { scopes })`,
+  below), so the Runtime itself keeps one person out of another's threads.
+  `scopes` defaults to `["sessions:own"]`; add `"vaults:own"` when `session()`
+  attaches the person's vaults. A `subject` the Runtime cannot name (see below)
+  answers `500` (`subject_invalid`).
+- The handler needs a Runtime with the optional features `transcript-events`
+  and `subject-headers` and answers `502` (`runtime_feature_missing`) without
+  them.
+
+A complete web backend with a test is in
+[examples/src/ag-ui](../examples/README.md#an-agent-in-your-web-app-ag-ui).
+
+Limitations: assistant text arrives once per model step (no token streaming);
+no reasoning, state, activity or subagent events, and an agent used as a tool
+shows only its result; frontend tools in `RunAgentInput.tools` are rejected
+(`400`); one text part per user message; earlier messages cannot be edited or
+regenerated. Browsers always go through your server: never let one call the
+Runtime directly.
+
+## Acting for a person (app servers)
+
+A server that signs people in and calls the Runtime for them (an "app server")
+keeps the Tenant key to itself and names the person on each call:
+
+```ts
+import { createClient } from "@nylorun/agents";
+
+const app = createClient(); // the Tenant key, on the server only
+
+// Per request, after your own sign-in:
+const person = app.as(`app:${user.id}`, { scopes: ["sessions:own", "vaults:own"] });
+await person.createSession({ agentId: "support", ownerUserId: `app:${user.id}` });
+await person.listSessions(); // only this person's sessions
+```
+
+`as()` sends `Nylorun-Subject` and `Nylorun-Scopes` on every call, event
+streams included, and the Runtime (optional feature `subject-headers`)
+enforces both: another person's sessions and vaults answer the same `404` as
+missing ones, and a route outside the scopes answers `403` (`scope_required`).
+Nothing is minted, cached or refreshed, and the copy shares the client's
+compatibility check, so calling `as()` per request is cheap.
+
+| Scope | Allows |
+| --- | --- |
+| `sessions:own` | The person's own sessions: create, list, read, stream, message, approve, respond, cancel |
+| `vaults:own` | The person's own vaults and credentials |
+| `agents:read` | Listing the Tenant's agents |
+| `agents:write` | Saving agents; listing agents, models and providers |
+| `tenant:settings` | The Tenant's status, model provider and sandbox settings |
+
+No scope reaches Tenant reset, config seed, executors, actions or the sandbox
+tool routes; call those without `as()`. A subject is 1–200 visible ASCII
+characters (spaces only inside) and `host` is reserved. Your server must drop
+any `Nylorun-*` header its own clients send, and only an application key can act
+for a subject: an executor key that tries is `403`.
+
+The SDK depends only on core within the Nylorun packages; installing it does not install harness. `/ag-ui` adds `@ag-ui/core`; nothing else imports it. Use `/define`, `/client`, `/executor` or `/ag-ui` for focused imports, or the root for convenience. Studio uses `/client`. See [the adopted host contract](../harness/HOST_CONTRACT.md).

package/dist/ag-ui/handler.d.ts

@@ -0,0 +1,42 @@
+import type { BuiltWorkflow } from "@nylorun/core/define";
+import { type SubjectScope } from "@nylorun/core/contracts";
+import { type AgentSource, type AgentsClient } from "../client.js";
+/** Per-session parameters the host may add, such as the person's vault for MCP servers. */
+export interface AgUiSessionOptions {
+    /** Part of the session's identity: keep it stable for a subject and agent, or runs get 409. */
+    info?: Record<string, unknown>;
+    vaultIds?: readonly string[];
+    credentialSelections?: Parameters<AgentsClient["createSession"]>[0]["credentialSelections"];
+}
+export interface AgUiHandlerOptions {
+    /** Agents this endpoint may run: built agents, workflows or their ids. Nothing else is reachable. */
+    agents: readonly (AgentSource | BuiltWorkflow | string)[];
+    /** The signed-in person the request is for. `undefined` answers 401; there is no anonymous mode. */
+    subject(request: Request): string | undefined | Promise<string | undefined>;
+    /** Where `fetch` is mounted, e.g. `/api/agui`. Default `/`. */
+    basePath?: string;
+    /** Application client. Default: `createClient()`, from the environment or the Project link. */
+    client?: AgentsClient | Promise<AgentsClient>;
+    /**
+     * What each subject may do through this endpoint. Default `["sessions:own"]`; add
+     * `vaults:own` if `session()` attaches the person's vaults.
+     */
+    scopes?: readonly SubjectScope[];
+    /** Optional per-session parameters, e.g. the person's vault for connected accounts. */
+    session?(subject: string, agentId: string): AgUiSessionOptions | Promise<AgUiSessionOptions>;
+}
+export interface AgUiHandler {
+    /** One entry point that routes by method and path under `basePath`. Bound. */
+    readonly fetch: (request: Request) => Promise<Response>;
+    /** `POST`: an AG-UI `RunAgentInput` in, the run's events out as server-sent events. */
+    run(request: Request, agentId: string): Promise<Response>;
+    /** `GET`: the thread's messages as a plain AG-UI `Message[]`. */
+    history(request: Request, agentId: string, threadId: string): Promise<Response>;
+    /** `GET`: the rest of a run after a dropped connection, from `Last-Event-ID` or `?cursor=`. */
+    reattach(request: Request, agentId: string, threadId: string): Promise<Response>;
+    /** `POST`: cancels the thread's running turn. */
+    cancel(request: Request, agentId: string, threadId: string): Promise<Response>;
+}
+/** A session per subject, agent and thread; one subject can never name another's session. */
+export declare function sessionIdFor(subject: string, agentId: string, threadId: string): string;
+export declare function createAgUiHandler(options: AgUiHandlerOptions): AgUiHandler;

package/dist/ag-ui/handler.js

@@ -0,0 +1,397 @@
+/**
+ * An AG-UI endpoint over the Tenant's agents, as web-standard `Request` → `Response`
+ * handlers. The host authenticates people (`subject`); the handler maps each AG-UI thread to
+ * one session per subject, agent and thread, and streams the session's transcript events as
+ * AG-UI events. It never trusts a session id from the client, and it calls the Runtime as the
+ * subject (`client.as`), so the Runtime itself keeps one subject out of another's sessions.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { EventType } from "@ag-ui/core";
+import { RunAgentInputSchema } from "@ag-ui/core/schemas";
+import { parseSubjectHeaders, } from "@nylorun/core/contracts";
+import { createClient, } from "../client.js";
+import { IncompatibleRuntimeError, RuntimeError } from "../http.js";
+import { messagesFromEvents } from "./history.js";
+import { SSE_CONTENT_TYPE, SSE_HEARTBEAT, sseFrame } from "./sse.js";
+import { RunTranslator } from "./translate.js";
+const HEARTBEAT_MS = 15_000;
+/** Host features the handler needs: the chat transcript, and acting for each subject. */
+const REQUIRED_FEATURES = ["transcript-events", "subject-headers"];
+const DEFAULT_SCOPES = ["sessions:own"];
+const TERMINAL = new Set([
+    "turn.completed",
+    "turn.paused",
+    "turn.failed",
+    "turn.cancelled",
+]);
+class Problem extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+function problem(status, message, code) {
+    return Response.json({ error: message, ...(code ? { code } : {}) }, { status });
+}
+function problemOf(error) {
+    if (error instanceof Problem)
+        return error;
+    if (error instanceof RuntimeError) {
+        if (error.status === 404)
+            return new Problem(404, "Not found");
+        // The Runtime refused what the client sent (e.g. a cursor it cannot read).
+        if (error.status === 400)
+            return new Problem(400, "The request was rejected", "invalid_request");
+        if (error.status === 409)
+            return new Problem(409, "The agent is busy or waiting for an answer to an open interrupt", "session_busy");
+        return new Problem(502, "The agent service failed", "runtime_error");
+    }
+    if (error instanceof IncompatibleRuntimeError)
+        return new Problem(502, error.message, "runtime_incompatible");
+    return new Problem(500, "Internal error");
+}
+/** A session per subject, agent and thread; one subject can never name another's session. */
+export function sessionIdFor(subject, agentId, threadId) {
+    return createHash("sha256")
+        .update(`${subject}\u0000${agentId}\u0000${threadId}`)
+        .digest("hex")
+        .slice(0, 32);
+}
+/** The trailing user message: the Runtime keeps the transcript, AG-UI resends all of it. */
+function lastUserMessage(messages) {
+    const last = messages.at(-1);
+    if (!last || last.role !== "user")
+        throw new Problem(400, "The run's last message must be a user message");
+    const text = typeof last.content === "string"
+        ? last.content
+        : last.content
+            .filter((part) => part.type === "text")
+            .map((part) => part.text)
+            .join("\n");
+    if (!text.trim())
+        throw new Problem(400, "The user message has no text");
+    return { id: last.id, text };
+}
+function normalizeBase(basePath = "/") {
+    const trimmed = basePath.replace(/\/+$/, "");
+    return trimmed === "" ? "" : trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+export function createAgUiHandler(options) {
+    const allowed = new Set(options.agents.map((agent) => (typeof agent === "string" ? agent : agent.id)));
+    const base = normalizeBase(options.basePath);
+    const scopes = options.scopes ?? DEFAULT_SCOPES;
+    const checked = parseSubjectHeaders("probe", scopes.join(" "));
+    if (!checked.ok)
+        throw new TypeError(`createAgUiHandler: ${checked.message}`);
+    let ready;
+    /** The client, once the Runtime is known to have every required feature. Retries after a failure. */
+    function connected() {
+        ready ??= (async () => {
+            const client = await (options.client ?? createClient());
+            const features = await client.hostFeatures();
+            const missing = REQUIRED_FEATURES.filter((f) => !features.includes(f));
+            if (missing.length > 0)
+                throw new Problem(502, `The Runtime does not support ${missing.join(", ")}; upgrade the stack (nylorun up).`, "runtime_feature_missing");
+            return client;
+        })();
+        ready.catch(() => {
+            ready = undefined;
+        });
+        return ready;
+    }
+    /** The client acting for `subject`: the Runtime limits it to the subject's own sessions. */
+    async function clientFor(subject) {
+        const client = await connected();
+        try {
+            return client.as(subject, { scopes });
+        }
+        catch (error) {
+            // The host's `subject` returned something the Runtime cannot name (see `as`).
+            throw new Problem(500, error.message, "subject_invalid");
+        }
+    }
+    async function subjectOf(request) {
+        const subject = await options.subject(request);
+        if (!subject)
+            throw new Problem(401, "Sign in required");
+        return subject;
+    }
+    function assertAgent(agentId) {
+        if (!allowed.has(agentId))
+            throw new Problem(404, "Not found");
+    }
+    async function sessionFor(request, agentId, threadId) {
+        assertAgent(agentId);
+        const subject = await subjectOf(request);
+        const client = await clientFor(subject);
+        return {
+            client,
+            subject,
+            session: client.session(sessionIdFor(subject, agentId, threadId)),
+        };
+    }
+    async function submit(session, input) {
+        if (input.resume?.length) {
+            let cursor = null;
+            // The interaction's kind is on the pending view, not in its id.
+            const pending = await session.pending();
+            const waits = Array.isArray(pending) ? pending : [];
+            for (const entry of input.resume) {
+                const wait = waits.find((w) => w?.interaction?.id === entry.interruptId);
+                const key = `${input.runId}:${entry.interruptId}`;
+                const payload = entry.payload;
+                const accepted = (wait?.interaction?.kind ?? "approval") === "approval"
+                    ? await session.approve(entry.interruptId, entry.status === "resolved" &&
+                        (payload === true ||
+                            (typeof payload === "object" && payload?.approved === true)), { idempotencyKey: key })
+                    : entry.status === "cancelled"
+                        ? await session.cancel({ idempotencyKey: key, reason: "interrupt cancelled" })
+                        : await session.respond(entry.interruptId, (entry.payload ?? null), {
+                            idempotencyKey: key,
+                        });
+                cursor ??= accepted.cursor;
+            }
+            return cursor;
+        }
+        const message = lastUserMessage(input.messages);
+        // The AG-UI message id is the idempotency key: a retried run replays the same turn,
+        // and history gives the message back its client id.
+        const accepted = await session.input(message.text, {
+            idempotencyKey: message.id,
+        });
+        return accepted.cursor;
+    }
+    /** Streams translated events until the run ends. Closing the response stops the read only. */
+    function stream(request, translator, source, preface = []) {
+        const reading = new AbortController();
+        request.signal.addEventListener("abort", () => reading.abort(), { once: true });
+        const bytes = new TextEncoder();
+        const body = new ReadableStream({
+            async start(controller) {
+                const write = (text) => {
+                    try {
+                        controller.enqueue(bytes.encode(text));
+                    }
+                    catch {
+                        reading.abort();
+                    }
+                };
+                const heartbeat = setInterval(() => write(SSE_HEARTBEAT), HEARTBEAT_MS);
+                try {
+                    write(sseFrame(translator.started()));
+                    for (const event of preface)
+                        write(sseFrame(event));
+                    if (source)
+                        for await (const event of source(reading.signal)) {
+                            const step = translator.translate(event);
+                            step.events.forEach((out, index) => write(sseFrame(out, index === step.events.length - 1 ? event.cursor : undefined)));
+                            if (step.finished || reading.signal.aborted)
+                                break;
+                        }
+                }
+                catch (error) {
+                    if (!reading.signal.aborted) {
+                        const failure = problemOf(error);
+                        write(sseFrame({
+                            type: EventType.RUN_ERROR,
+                            message: failure.message,
+                            ...(failure.code ? { code: failure.code } : {}),
+                        }));
+                    }
+                }
+                finally {
+                    clearInterval(heartbeat);
+                    reading.abort();
+                    try {
+                        controller.close();
+                    }
+                    catch {
+                        /* the client is gone */
+                    }
+                }
+            },
+            cancel() {
+                reading.abort();
+            },
+        });
+        return new Response(body, {
+            headers: {
+                "content-type": SSE_CONTENT_TYPE,
+                "cache-control": "no-cache, no-transform",
+                "x-accel-buffering": "no",
+            },
+        });
+    }
+    async function run(request, agentId) {
+        try {
+            assertAgent(agentId);
+            const subject = await subjectOf(request);
+            const parsed = RunAgentInputSchema.safeParse(await request.json().catch(() => undefined));
+            if (!parsed.success)
+                throw new Problem(400, "Invalid RunAgentInput");
+            const input = parsed.data;
+            // Nylorun tools run in the Runtime or the app's executor; the browser runs none.
+            if (input.tools?.length)
+                throw new Problem(400, "Frontend tools are not supported");
+            const client = await clientFor(subject);
+            const extra = (await options.session?.(subject, agentId)) ?? {};
+            const translator = new RunTranslator(input.threadId, input.runId);
+            let session;
+            try {
+                // The host's parameters first: they never replace the session's identity.
+                session = await client.createSession({
+                    ...extra,
+                    id: sessionIdFor(subject, agentId, input.threadId),
+                    agentId,
+                    ownerUserId: subject,
+                });
+            }
+            catch (error) {
+                if (error instanceof RuntimeError && error.status === 409)
+                    throw new Problem(409, "The thread's session was opened with other parameters", "session_conflict");
+                throw error;
+            }
+            let cursor;
+            try {
+                cursor = await submit(session, input);
+            }
+            catch (error) {
+                const failure = problemOf(error);
+                // A busy or paused session is a run that could not start, not a transport failure.
+                if (failure.status !== 409)
+                    throw failure;
+                return stream(request, translator, undefined, [
+                    {
+                        type: EventType.RUN_ERROR,
+                        message: failure.message,
+                        code: failure.code,
+                    },
+                ]);
+            }
+            return stream(request, translator, (signal) => session.observe({ ...(cursor ? { cursor } : {}), signal }));
+        }
+        catch (error) {
+            const failure = problemOf(error);
+            return problem(failure.status, failure.message, failure.code);
+        }
+    }
+    async function history(request, agentId, threadId) {
+        try {
+            const { session } = await sessionFor(request, agentId, threadId);
+            const items = [];
+            let cursor;
+            try {
+                for (;;) {
+                    const page = await session.history({ ...(cursor ? { cursor } : {}) });
+                    items.push(...page.items);
+                    if (!page.cursor || page.cursor === cursor || page.items.length === 0)
+                        break;
+                    cursor = page.cursor;
+                }
+            }
+            catch (error) {
+                // A thread that never ran has no session yet.
+                if (error instanceof RuntimeError && error.status === 404)
+                    return Response.json([]);
+                throw error;
+            }
+            return Response.json(messagesFromEvents(items));
+        }
+        catch (error) {
+            const failure = problemOf(error);
+            return problem(failure.status, failure.message, failure.code);
+        }
+    }
+    async function reattach(request, agentId, threadId) {
+        try {
+            const { session } = await sessionFor(request, agentId, threadId);
+            const url = new URL(request.url);
+            const cursor = request.headers.get("last-event-id") ?? url.searchParams.get("cursor");
+            if (!cursor)
+                throw new Problem(400, "Last-Event-ID or ?cursor= is required");
+            const view = await session.inspect();
+            const runId = url.searchParams.get("runId") ??
+                view.activeTurnId ??
+                (typeof view.lastTurnId === "string" ? view.lastTurnId : randomUUID());
+            const translator = new RunTranslator(threadId, runId, { reattached: true });
+            if (view.activeTurnId)
+                return stream(request, translator, (signal) => session.observe({ cursor, signal }));
+            // No turn is running: send what the client missed, if the run ended after the cursor.
+            const missed = [];
+            let from = cursor;
+            for (;;) {
+                const page = await session.history({ cursor: from });
+                missed.push(...page.items);
+                if (!page.cursor || page.cursor === from || page.items.length === 0)
+                    break;
+                from = page.cursor;
+            }
+            if (!missed.some((event) => TERMINAL.has(event.type)))
+                return new Response(null, { status: 204 });
+            return stream(request, translator, () => iterate(missed));
+        }
+        catch (error) {
+            const failure = problemOf(error);
+            return problem(failure.status, failure.message, failure.code);
+        }
+    }
+    async function cancel(request, agentId, threadId) {
+        try {
+            const { session } = await sessionFor(request, agentId, threadId);
+            await session.cancel({ idempotencyKey: `cancel:${randomUUID()}` });
+            return new Response(null, { status: 204 });
+        }
+        catch (error) {
+            const failure = problemOf(error);
+            return problem(failure.status, failure.message, failure.code);
+        }
+    }
+    async function route(request) {
+        const path = new URL(request.url).pathname;
+        if (path !== base && !path.startsWith(`${base}/`))
+            return problem(404, "Not found");
+        let segments;
+        try {
+            segments = path
+                .slice(base.length)
+                .split("/")
+                .slice(1)
+                .map((segment) => decodeURIComponent(segment));
+        }
+        catch {
+            return problem(404, "Not found");
+        }
+        if (segments.some((segment) => segment === ""))
+            return problem(404, "Not found");
+        const [agentId, threads, threadId, action] = segments;
+        const method = request.method.toUpperCase();
+        const operation = (allow, handle) => {
+            if (!agentId || !allowed.has(agentId))
+                return problem(404, "Not found");
+            if (method !== allow)
+                return new Response(JSON.stringify({ error: "Method not allowed" }), {
+                    status: 405,
+                    headers: { allow, "content-type": "application/json" },
+                });
+            return handle();
+        };
+        if (segments.length === 1)
+            return operation("POST", () => run(request, agentId));
+        if (segments.length === 4 && threads === "threads") {
+            if (action === "messages")
+                return operation("GET", () => history(request, agentId, threadId));
+            if (action === "events")
+                return operation("GET", () => reattach(request, agentId, threadId));
+            if (action === "cancel")
+                return operation("POST", () => cancel(request, agentId, threadId));
+        }
+        return problem(404, "Not found");
+    }
+    return { fetch: route, run, history, reattach, cancel };
+}
+async function* iterate(items) {
+    yield* items;
+}

package/dist/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[];