@nylorun/agents 0.7.0-beta → 0.8.0-beta

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @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

package/README.md

@@ -286,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[];

package/dist/ag-ui/history.js

@@ -0,0 +1,60 @@
+import { parseTranscriptEvent } from "@nylorun/core/contracts";
+import { outputText, toolResultOf } from "./translate.js";
+export function messagesFromEvents(items) {
+    const messages = [];
+    const results = new Set();
+    let sawAssistant = false;
+    for (const raw of items) {
+        if (raw.type === "command.message") {
+            const p = (raw.payload ?? {});
+            messages.push({
+                // The handler sends the client's message id as the idempotency key.
+                id: p.idempotencyKey ?? raw.eventId,
+                role: "user",
+                content: typeof p.content === "string" ? p.content : JSON.stringify(p.data),
+            });
+            sawAssistant = false;
+            continue;
+        }
+        const event = parseTranscriptEvent(raw);
+        if (!event)
+            continue;
+        const result = toolResultOf(event);
+        if (result) {
+            if (results.has(result.callId))
+                continue;
+            results.add(result.callId);
+            messages.push({
+                id: `${result.callId}:result`,
+                role: "tool",
+                toolCallId: result.callId,
+                content: result.content,
+            });
+            continue;
+        }
+        if (event.type === "message.assistant" && !event.payload.agent) {
+            const p = event.payload;
+            sawAssistant = true;
+            const message = { id: p.invocationId, role: "assistant" };
+            if (p.text)
+                message.content = p.text;
+            if (p.toolCalls.length)
+                message.toolCalls = p.toolCalls.map((call) => ({
+                    id: call.callId,
+                    type: "function",
+                    function: { name: call.name, arguments: JSON.stringify(call.input ?? {}) },
+                }));
+            messages.push(message);
+        }
+        else if (event.type === "turn.completed" && !sawAssistant) {
+            const output = event.payload.output;
+            if (output !== undefined && output !== null && outputText(output))
+                messages.push({
+                    id: raw.eventId,
+                    role: "assistant",
+                    content: outputText(output),
+                });
+        }
+    }
+    return messages;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * `@nylorun/agents/ag-ui`: serve the Tenant's agents to AG-UI clients from the app's own
+ * server. The only entry point that loads `@ag-ui/core`.
+ */
+export { createAgUiHandler } from "./handler.js";
+export type { AgUiHandler, AgUiHandlerOptions, AgUiSessionOptions, } from "./handler.js";
+export { toNodeListener } from "./node.js";

package/dist/ag-ui/index.js

@@ -0,0 +1,6 @@
+/**
+ * `@nylorun/agents/ag-ui`: serve the Tenant's agents to AG-UI clients from the app's own
+ * server. The only entry point that loads `@ag-ui/core`.
+ */
+export { createAgUiHandler } from "./handler.js";
+export { toNodeListener } from "./node.js";

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

@@ -0,0 +1,5 @@
+/** `node:http` and Express adapter for a fetch-style handler. */
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare function toNodeListener(handler: {
+    readonly fetch: (request: Request) => Promise<Response>;
+}): (req: IncomingMessage, res: ServerResponse) => void;

package/dist/ag-ui/node.js

@@ -0,0 +1,51 @@
+import { Readable } from "node:stream";
+export function toNodeListener(handler) {
+    return (req, res) => {
+        void (async () => {
+            // A closed connection aborts the request, which stops the read, never the turn.
+            const controller = new AbortController();
+            res.on("close", () => controller.abort());
+            const host = req.headers.host ?? "localhost";
+            const url = new URL(req.url ?? "/", `http://${host}`);
+            const headers = new Headers();
+            for (const [name, value] of Object.entries(req.headers)) {
+                if (value === undefined)
+                    continue;
+                for (const item of Array.isArray(value) ? value : [value])
+                    headers.append(name, item);
+            }
+            const hasBody = req.method !== "GET" && req.method !== "HEAD";
+            const request = new Request(url, {
+                method: req.method,
+                headers,
+                signal: controller.signal,
+                ...(hasBody
+                    ? {
+                        body: Readable.toWeb(req),
+                        duplex: "half",
+                    }
+                    : {}),
+            });
+            let response;
+            try {
+                response = await handler.fetch(request);
+            }
+            catch {
+                response = new Response(JSON.stringify({ error: "Internal error" }), {
+                    status: 500,
+                    headers: { "content-type": "application/json" },
+                });
+            }
+            res.writeHead(response.status, Object.fromEntries(response.headers));
+            if (!response.body) {
+                res.end();
+                return;
+            }
+            res.flushHeaders();
+            const body = Readable.fromWeb(response.body);
+            body.on("error", () => res.destroy());
+            res.on("close", () => body.destroy());
+            body.pipe(res);
+        })();
+    };
+}

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

@@ -0,0 +1,9 @@
+/**
+ * AG-UI over server-sent events: one `data:` line of JSON per event. The last AG-UI event
+ * made from a Runtime event carries that event's cursor as `id:`, so a client that resumes
+ * from `Last-Event-ID` never lands inside a group.
+ */
+import type { BaseEvent } from "@ag-ui/core";
+export declare const SSE_CONTENT_TYPE = "text/event-stream";
+export declare function sseFrame(event: BaseEvent, id?: string): string;
+export declare const SSE_HEARTBEAT = ": keep-alive\n\n";

package/dist/ag-ui/sse.js

@@ -0,0 +1,7 @@
+export const SSE_CONTENT_TYPE = "text/event-stream";
+export function sseFrame(event, id) {
+    // Cursors are opaque base64; a line break would end the field early.
+    const idLine = id && !/[\r\n]/.test(id) ? `id: ${id}\n` : "";
+    return `${idLine}data: ${JSON.stringify(event)}\n\n`;
+}
+export const SSE_HEARTBEAT = ": keep-alive\n\n";

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

@@ -0,0 +1,38 @@
+/**
+ * Runtime transcript events → AG-UI 1.0 events for one run. Ids: an assistant message is its
+ * model call's `invocationId`, a tool call is the model's `callId`, a tool result is
+ * `<callId>:result`, so live runs and `messagesFromEvents` agree.
+ */
+import { type BaseEvent } from "@ag-ui/core";
+import { type LiveEvent, type TranscriptEvent } from "@nylorun/core/contracts";
+/** The text a tool result shows; `undefined` while there is no result yet. */
+export declare function toolResultText(result: unknown): string | undefined;
+export declare function outputText(output: unknown): string;
+/** One Runtime event's result for a run: AG-UI events, and whether the run ended. */
+export interface Step {
+    readonly events: BaseEvent[];
+    readonly finished: boolean;
+}
+/** A tool result from any of the three places a call can end. */
+export declare function toolResultOf(event: TranscriptEvent): {
+    callId: string;
+    content: string;
+} | undefined;
+export declare class RunTranslator {
+    private readonly threadId;
+    private readonly runId;
+    /** Tool invocation → the model's call id, for interrupts that name the invocation. */
+    private readonly callIds;
+    private readonly closed;
+    private sawAssistant;
+    /**
+     * `reattached`: the run continues from a cursor, so earlier assistant messages already
+     * reached the client and a workflow's output is not repeated as text.
+     */
+    constructor(threadId: string, runId: string, options?: {
+        reattached?: boolean;
+    });
+    translate(raw: LiveEvent): Step;
+    started(): BaseEvent;
+    private finished;
+}

package/dist/ag-ui/translate.js

@@ -0,0 +1,222 @@
+/**
+ * Runtime transcript events → AG-UI 1.0 events for one run. Ids: an assistant message is its
+ * model call's `invocationId`, a tool call is the model's `callId`, a tool result is
+ * `<callId>:result`, so live runs and `messagesFromEvents` agree.
+ */
+import { EventType } from "@ag-ui/core";
+import { parseTranscriptEvent, } from "@nylorun/core/contracts";
+/** The text a tool result shows; `undefined` while there is no result yet. */
+export function toolResultText(result) {
+    const value = result;
+    switch (value?.kind) {
+        case "completed":
+            return outputText(value.output ?? null);
+        case "failed":
+            return JSON.stringify({ error: value.code, message: value.message });
+        case "denied":
+            return JSON.stringify({ denied: true, reason: value.reason });
+        default:
+            // interaction-required and deferred: the call is still open.
+            return undefined;
+    }
+}
+export function outputText(output) {
+    return typeof output === "string" ? output : JSON.stringify(output);
+}
+const none = { events: [], finished: false };
+/** A tool result from any of the three places a call can end. */
+export function toolResultOf(event) {
+    switch (event.type) {
+        case "action.completed": {
+            const p = event.payload;
+            if (p.kind !== "tool" || !p.callId || p.agent)
+                return undefined;
+            const content = toolResultText(p.result);
+            return content === undefined ? undefined : { callId: p.callId, content };
+        }
+        case "tool.completed": {
+            const p = event.payload;
+            if (p.agent)
+                return undefined;
+            return {
+                callId: p.callId,
+                content: p.error !== undefined
+                    ? JSON.stringify({ error: p.error.code, message: p.error.message })
+                    : outputText(p.output ?? null),
+            };
+        }
+        case "delegation.completed": {
+            // An agent used as a tool: its own work stays inside it; the parent sees the result.
+            const p = event.payload;
+            if (!p.callId)
+                return undefined;
+            const content = toolResultText(p.outcome);
+            return content === undefined ? undefined : { callId: p.callId, content };
+        }
+        default:
+            return undefined;
+    }
+}
+export class RunTranslator {
+    threadId;
+    runId;
+    /** Tool invocation → the model's call id, for interrupts that name the invocation. */
+    callIds = new Map();
+    closed = new Set();
+    sawAssistant;
+    /**
+     * `reattached`: the run continues from a cursor, so earlier assistant messages already
+     * reached the client and a workflow's output is not repeated as text.
+     */
+    constructor(threadId, runId, options = {}) {
+        this.threadId = threadId;
+        this.runId = runId;
+        this.sawAssistant = options.reattached ?? false;
+    }
+    translate(raw) {
+        const event = parseTranscriptEvent(raw);
+        if (!event)
+            return none;
+        if (event.type === "action.pending" || event.type === "action.completed") {
+            const { callId, invocationId } = event.payload;
+            if (callId && invocationId)
+                this.callIds.set(invocationId, callId);
+        }
+        const result = toolResultOf(event);
+        if (result) {
+            if (this.closed.has(result.callId))
+                return none;
+            this.closed.add(result.callId);
+            return {
+                events: [
+                    {
+                        type: EventType.TOOL_CALL_RESULT,
+                        messageId: `${result.callId}:result`,
+                        toolCallId: result.callId,
+                        content: result.content,
+                        role: "tool",
+                    },
+                ],
+                finished: false,
+            };
+        }
+        switch (event.type) {
+            case "message.assistant": {
+                const p = event.payload;
+                if (p.agent)
+                    return none;
+                this.sawAssistant = true;
+                return { events: assistantEvents(p), finished: false };
+            }
+            case "turn.completed": {
+                const p = event.payload;
+                // Workflows finish without a model step of their own: show their output.
+                const text = this.sawAssistant || p.output === undefined || p.output === null
+                    ? []
+                    : textEvents(raw.eventId, outputText(p.output));
+                return {
+                    events: [...text, this.finished({ type: "success" }, p.output)],
+                    finished: true,
+                };
+            }
+            case "turn.paused": {
+                const interrupts = event.payload.interactions.map((w) => {
+                    const interaction = w.interaction;
+                    const toolCallId = this.callIds.get(w.invocationId);
+                    return {
+                        id: interaction.id,
+                        reason: interaction.kind === "approval" ? "tool_approval" : "input_required",
+                        ...(typeof interaction.prompt === "string"
+                            ? { message: interaction.prompt }
+                            : {}),
+                        ...(toolCallId ? { toolCallId } : {}),
+                        ...(interaction.kind === "approval"
+                            ? {
+                                responseSchema: {
+                                    type: "object",
+                                    properties: { approved: { type: "boolean" } },
+                                    required: ["approved"],
+                                },
+                            }
+                            : {}),
+                        metadata: { nylorun: { kind: interaction.kind } },
+                    };
+                });
+                return {
+                    events: [this.finished({ type: "interrupt", interrupts })],
+                    finished: true,
+                };
+            }
+            case "turn.cancelled":
+                return { events: [this.finished({ type: "cancelled" })], finished: true };
+            case "turn.failed": {
+                const p = event.payload;
+                return {
+                    events: [
+                        {
+                            type: EventType.RUN_ERROR,
+                            message: p.error?.message ?? p.message ?? "The agent failed",
+                            code: p.error?.code ?? "turn.failed",
+                        },
+                    ],
+                    finished: true,
+                };
+            }
+            case "effect.uncertain":
+            case "action.uncertain":
+                // The Runtime cannot tell whether a side effect happened; the run goes on.
+                return {
+                    events: [
+                        {
+                            type: EventType.CUSTOM,
+                            name: "nylorun.uncertain",
+                            value: event.payload,
+                        },
+                    ],
+                    finished: false,
+                };
+            default:
+                return none;
+        }
+    }
+    started() {
+        return {
+            type: EventType.RUN_STARTED,
+            threadId: this.threadId,
+            runId: this.runId,
+        };
+    }
+    finished(outcome, result) {
+        return {
+            type: EventType.RUN_FINISHED,
+            threadId: this.threadId,
+            runId: this.runId,
+            outcome,
+            ...(result === undefined ? {} : { result }),
+        };
+    }
+}
+function textEvents(messageId, text) {
+    if (!text)
+        return [];
+    return [
+        { type: EventType.TEXT_MESSAGE_START, messageId, role: "assistant" },
+        { type: EventType.TEXT_MESSAGE_CONTENT, messageId, delta: text },
+        { type: EventType.TEXT_MESSAGE_END, messageId },
+    ];
+}
+function assistantEvents(p) {
+    const events = textEvents(p.invocationId, p.text);
+    for (const call of p.toolCalls)
+        events.push({
+            type: EventType.TOOL_CALL_START,
+            toolCallId: call.callId,
+            toolCallName: call.name,
+            parentMessageId: p.invocationId,
+        }, {
+            type: EventType.TOOL_CALL_ARGS,
+            toolCallId: call.callId,
+            delta: JSON.stringify(call.input ?? {}),
+        }, { type: EventType.TOOL_CALL_END, toolCallId: call.callId });
+    return events;
+}

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import type { AgentManifest, BuiltAgent, BuiltWorkflow, JsonValue, SandboxToolName, WorkflowManifest } from "@nylorun/core/define";
-import { type CredentialInfo, type CredentialSelection, type SessionCommand, type VaultInfo } from "@nylorun/core/contracts";
+import { type SubjectScope, type CredentialInfo, type CredentialSelection, type SessionCommand, type VaultInfo } from "@nylorun/core/contracts";
 import { Transport, type Destination } from "./http.js";
 /** Application-principal access to a session's sandbox built-ins (workflows.md §8). */
 export type SessionSandbox = {
@@ -22,9 +22,26 @@ export interface SessionView {
     waits?: unknown;
     [key: string]: unknown;
 }
+export interface ActAsOptions {
+    /** What the subject may do; the Runtime grants nothing else. Default `["sessions:own"]`. */
+    scopes?: readonly SubjectScope[];
+}
 export declare class AgentsClient {
     readonly transport: Transport;
+    /** The subject this client acts for (`as`), or `undefined` for the principal itself. */
+    readonly subject: string | undefined;
     constructor(destination?: Destination);
+    /**
+     * A client that acts for `subject`: every call sends `Nylorun-Subject` and
+     * `Nylorun-Scopes`, and the Runtime limits it to the scopes and to the subject's own sessions
+     * and vaults (Host feature `subject-headers`). For app servers, which authenticate the person
+     * themselves and hold the key; nothing is minted, cached or refreshed.
+     */
+    as(subject: string, options?: ActAsOptions): AgentsClient;
+    /** The Runtime's protocol features, including optional ones such as `transcript-events`. */
+    hostFeatures(options?: {
+        signal?: AbortSignal;
+    }): Promise<readonly string[]>;
     listAgents(options?: {
         signal?: AbortSignal;
     }): Promise<{

package/dist/client.js

@@ -1,5 +1,6 @@
 import { SANDBOX_TOOL_NAMES, delegateOf, isBuiltWorkflow, isSandboxToolName, } from "@nylorun/core/define";
-import { LiveEventSchema, SessionItemsResponseSchema, } from "@nylorun/core/contracts";
+import { SCOPES_HEADER, SUBJECT_HEADER } from "@nylorun/core/compatibility";
+import { LiveEventSchema, SessionItemsResponseSchema, parseSubjectHeaders, } from "@nylorun/core/contracts";
 import { resolveConnection } from "./connection.js";
 import { Transport, id, segment } from "./http.js";
 import { observeSSE } from "./sse.js";
@@ -57,8 +58,37 @@ export function assertNoMiddlewareClosures(agent) {
 }
 export class AgentsClient {
     transport;
+    /** The subject this client acts for (`as`), or `undefined` for the principal itself. */
+    subject;
     constructor(destination = {}) {
         this.transport = new Transport(destination);
+        this.subject = undefined;
+    }
+    /**
+     * A client that acts for `subject`: every call sends `Nylorun-Subject` and
+     * `Nylorun-Scopes`, and the Runtime limits it to the scopes and to the subject's own sessions
+     * and vaults (Host feature `subject-headers`). For app servers, which authenticate the person
+     * themselves and hold the key; nothing is minted, cached or refreshed.
+     */
+    as(subject, options = {}) {
+        if (this.subject !== undefined)
+            throw new Error(`This client already acts for ${this.subject}`);
+        const scopes = [...(options.scopes ?? ["sessions:own"])].join(" ");
+        const parsed = parseSubjectHeaders(subject, scopes);
+        if (!parsed.ok)
+            throw new TypeError(parsed.message);
+        const client = Object.create(AgentsClient.prototype);
+        return Object.assign(client, {
+            transport: this.transport.withHeaders({
+                [SUBJECT_HEADER]: subject,
+                [SCOPES_HEADER]: [...parsed.scopes].join(" "),
+            }),
+            subject,
+        });
+    }
+    /** The Runtime's protocol features, including optional ones such as `transcript-events`. */
+    hostFeatures(options = {}) {
+        return this.transport.hostFeatures(options.signal);
     }
     listAgents(options = {}) {
         return this.transport.json("/v1/agents", "GET", undefined, options.signal);

package/dist/http.d.ts

@@ -26,11 +26,20 @@ export declare class Transport {
     readonly key: string;
     readonly tenant: string;
     readonly fetcher: typeof fetch;
-    private compatible;
+    /** Sent on every request, e.g. `Nylorun-Subject` and `Nylorun-Scopes` (`withHeaders`). */
+    readonly headers: Readonly<Record<string, string>>;
+    private readonly check;
     constructor(options?: Destination, role?: "server" | "executor");
+    /**
+     * The same destination with `headers` added to every request. The copy shares this
+     * transport's compatibility check, so a copy made per request does not repeat `/health`.
+     */
+    withHeaders(headers: Readonly<Record<string, string>>): Transport;
     /** Clears the cached Host compatibility result (used after a 426). */
     clearCompatibilityCache(): void;
     private ensureCompatible;
+    /** The Host's protocol features, including optional ones, from its `/health`. */
+    hostFeatures(signal?: AbortSignal): Promise<readonly string[]>;
     private authHeaders;
     request(path: string, init?: RequestInit, options?: {
         retried426?: boolean;

package/dist/http.js

@@ -57,7 +57,9 @@ export class Transport {
     key;
     tenant;
     fetcher;
-    compatible = false;
+    /** Sent on every request, e.g. `Nylorun-Subject` and `Nylorun-Scopes` (`withHeaders`). */
+    headers = {};
+    check = { compatible: false, features: [] };
     constructor(options = {}, role = "server") {
         const url = options.url ?? env("NYLORUN_RUNTIME_URL");
         const key = options.key ??
@@ -75,12 +77,22 @@ export class Transport {
         this.tenant = tenant;
         this.fetcher = options.fetch ?? globalThis.fetch;
     }
+    /**
+     * The same destination with `headers` added to every request. The copy shares this
+     * transport's compatibility check, so a copy made per request does not repeat `/health`.
+     */
+    withHeaders(headers) {
+        const copy = Object.create(Transport.prototype);
+        return Object.assign(copy, this, {
+            headers: Object.freeze({ ...this.headers, ...headers }),
+        });
+    }
     /** Clears the cached Host compatibility result (used after a 426). */
     clearCompatibilityCache() {
-        this.compatible = false;
+        this.check.compatible = false;
     }
     async ensureCompatible(signal) {
-        if (this.compatible)
+        if (this.check.compatible)
             return;
         const response = await this.fetcher(`${this.url}/health`, {
             method: "GET",
@@ -110,10 +122,18 @@ export class Transport {
         const result = checkCompatibility({ version: PROTOCOL_VERSION, required: [...PROTOCOL_FEATURES] }, protocol);
         if (!result.ok)
             throw new IncompatibleRuntimeError(result);
-        this.compatible = true;
+        this.check.features = [...protocol.features];
+        this.check.compatible = true;
+    }
+    /** The Host's protocol features, including optional ones, from its `/health`. */
+    async hostFeatures(signal) {
+        await this.ensureCompatible(signal);
+        return this.check.features;
     }
     authHeaders(init = {}) {
         const headers = new Headers(init.headers);
+        for (const [name, value] of Object.entries(this.headers))
+            headers.set(name, value);
         headers.set("Authorization", `Bearer ${this.key}`);
         headers.set(TENANT_HEADER, this.tenant);
         headers.set(PROTOCOL_HEADER, String(PROTOCOL_VERSION));

package/dist/index.d.ts

@@ -1,10 +1,11 @@
-export { hashManifest, PROTOCOL_VERSION, PROTOCOL_FEATURES, HOST_PROTOCOL, DEFINITION_SCHEMA_VERSION, TENANT_HEADER, PROTOCOL_HEADER, TENANT_ID_PATTERN, isTenantId, newTenantId, newPrincipalId, checkCompatibility, compareVersions, ERROR_CODES, } from "@nylorun/core/compatibility";
+export { hashManifest, PROTOCOL_VERSION, PROTOCOL_FEATURES, HOST_PROTOCOL, DEFINITION_SCHEMA_VERSION, TENANT_HEADER, PROTOCOL_HEADER, SUBJECT_HEADER, SCOPES_HEADER, TENANT_ID_PATTERN, isTenantId, newTenantId, newPrincipalId, checkCompatibility, compareVersions, ERROR_CODES, } from "@nylorun/core/compatibility";
 export type { ProtocolFeature, ProtocolRange, Compatibility, ErrorCode, } from "@nylorun/core/compatibility";
 export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError, Loop, Chain, Switch, Parallel, Map, VerdictSchema, isVerdict, withInstructions, withoutTools, WorkflowBuildError, isBuiltWorkflow, capability, tool, defineSchema, ToolError, } from "@nylorun/core/define";
 export type { AgentOptions, AgentManifest, BuiltAgent, BuiltWorkflow, LoopOptions, LoopDecideArgs, LoopVerifyArgs, LoopDecision, ChainOptions, SwitchOptions, ParallelOptions, MapOptions, Verdict, WorkflowBinding, WorkflowManifest, ToolDefinition, ToolExecutionContext, ToolOutcome, Patch, Decision, TurnDecision, HookScope, BeforeHook, AfterHook, JsonValue, JsonObject, } from "@nylorun/core/define";
-export type { LiveEvent, SessionCommand, Action, ActionOutcome, CredentialInfo, CredentialSelection, VaultInfo, } from "@nylorun/core/contracts";
+export type { LiveEvent, SessionCommand, Action, ActionOutcome, CredentialInfo, CredentialSelection, VaultInfo, SubjectScope, } from "@nylorun/core/contracts";
+export { SUBJECT_SCOPES } from "@nylorun/core/contracts";
 export { AgentsClient, SessionClient, createClient } from "./client.js";
-export type { AgentSource, SessionView, CommandOptions, SessionSandbox, } from "./client.js";
+export type { ActAsOptions, AgentSource, SessionView, CommandOptions, SessionSandbox, } from "./client.js";
 export { connectAgents } from "./executor.js";
 export type { ConnectOptions, AgentConnection } from "./executor.js";
 export type { ExecuteActionOptions, ExecutableDefinition, } from "./execute-action.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 // Definition authoring and wire contracts are the only harness runtime imports.
-export { hashManifest, PROTOCOL_VERSION, PROTOCOL_FEATURES, HOST_PROTOCOL, DEFINITION_SCHEMA_VERSION, TENANT_HEADER, PROTOCOL_HEADER, TENANT_ID_PATTERN, isTenantId, newTenantId, newPrincipalId, checkCompatibility, compareVersions, ERROR_CODES, } from "@nylorun/core/compatibility";
+export { hashManifest, PROTOCOL_VERSION, PROTOCOL_FEATURES, HOST_PROTOCOL, DEFINITION_SCHEMA_VERSION, TENANT_HEADER, PROTOCOL_HEADER, SUBJECT_HEADER, SCOPES_HEADER, TENANT_ID_PATTERN, isTenantId, newTenantId, newPrincipalId, checkCompatibility, compareVersions, ERROR_CODES, } from "@nylorun/core/compatibility";
 export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError, Loop, Chain, Switch, Parallel, Map, VerdictSchema, isVerdict, withInstructions, withoutTools, WorkflowBuildError, isBuiltWorkflow, capability, tool, defineSchema, ToolError, } from "@nylorun/core/define";
+export { SUBJECT_SCOPES } from "@nylorun/core/contracts";
 export { AgentsClient, SessionClient, createClient } from "./client.js";
 export { connectAgents } from "./executor.js";
 export { resolveConnection, ConnectionError } from "./connection.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/agents",
-  "version": "0.7.0-beta",
+  "version": "0.8.0-beta",
   "description": "Nylorun agent definitions, session client and connected executor",
   "type": "module",
   "license": "Apache-2.0",
@@ -27,6 +27,10 @@
     "./executor": {
       "types": "./dist/executor.d.ts",
       "import": "./dist/executor.js"
+    },
+    "./ag-ui": {
+      "types": "./dist/ag-ui/index.d.ts",
+      "import": "./dist/ag-ui/index.js"
     }
   },
   "scripts": {
@@ -35,7 +39,8 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@nylorun/core": "0.6.0-beta",
+    "@ag-ui/core": "~1.0.0",
+    "@nylorun/core": "0.7.0-beta",
     "gray-matter": "^4.0.3"
   },
   "peerDependencies": {
@@ -51,7 +56,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/nylorun/harness.git",
+    "url": "git+https://github.com/nylorun/agents.git",
     "directory": "agents"
   },
   "publishConfig": {