@nylorun/agents 0.8.0-beta → 0.10.0-beta

package/README.md

@@ -1,51 +1,64 @@
 # @nylorun/agents
 
-Tenant API client package: definition authoring, a session client, and a
-connected customer executor. Depends only on `@nylorun/core` among Nylorun
+Tenant API client package: definition authoring, a session client, and the
+Action endpoint that runs your tools (`createActionHandler`). Depends only on `@nylorun/core` among Nylorun
 packages. A developer application's production tree should contain only this
 package and `@nylorun/core` from Nylorun. Vocabulary:
 [runtime/src/CONTEXT.md](../runtime/src/CONTEXT.md).
 
-## Application entry (preferred)
+## Application entry (preferred): an Action endpoint
 
 ```ts
 // src/main.ts
-import { connectAgents } from "@nylorun/agents";
+import { createServer } from "node:http";
+import { createActionHandler } from "@nylorun/agents";
 import { agents } from "../agents/index.js";
 
-await connectAgents({ agents }).ready;
+const url = process.env.NYLORUN_ACTIONS_URL ?? "http://localhost:3001/nylorun/actions";
+const actions = createActionHandler({ agents, url });
+createServer(actions.node).listen(3001); // or actions.fetch in Hono, Next.js, Workers, Bun
+await actions.register({ url });
 ```
 
-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 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)
+The Runtime delivers each tool call, hook and workflow function of these agents
+to `url`, signed with a short-lived **delivery token** that the handler checks
+(Tenant, URL, Action, generation and body) before any code runs. `register`
+saves the definitions, registers the URL and pings it through the Runtime. A
+process that only serves Actions needs no key: pass `runtime: { url, tenant }`
+and it reads the Tenant's public keys. Mark a long tool
+`tool({ …, background: true })`: the handler answers at once, heartbeats and
+posts the result. `npx @nylorun/cli tenant endpoints` shows each endpoint and
+how its deliveries are doing.
+
+The URL must be one the Runtime can reach: `localhost` on the local stack
+(its Runtime runs in Docker and maps `localhost` to this machine), a public URL
+in production, or a tunnel (ngrok, Cloudflare Tunnel) for a remote Runtime.
+
+`connectAgents` and executors were removed in protocol 3: mount
+`createActionHandler` instead (see [MIGRATION.md](../MIGRATION.md)). The handler
+finds the Runtime through the three `NYLORUN_*` variables or the Project link
+that `npx @nylorun/cli tenant create` writes; with neither, `register` 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
 
-`resolveConnection` / `createClient()` / `connectAgents({ agents })`:
+`resolveConnection` / `createClient()` / `createActionHandler({ agents })`:
 
 1. Explicit `{ url, tenant, key }`
-2. Environment — if any of `NYLORUN_RUNTIME_URL`, `NYLORUN_TENANT`,
-   `NYLORUN_SERVER_KEY` or `NYLORUN_EXECUTOR_KEY` is set, all required pieces
-   must be present (role `executor` when `NYLORUN_EXECUTOR_KEY` is set)
-3. Project link — `.nylorun/link.json` + `credentials.json` (application role)
+2. Environment — if any of `NYLORUN_RUNTIME_URL`, `NYLORUN_TENANT` or
+   `NYLORUN_SERVER_KEY` is set, all three must be present
+3. Project link — `.nylorun/link.json` + `credentials.json` (the application key)
 
 Sources never mix. Partial environment fails with `connection_missing`.
 
 ```ts
-import { Agent, createClient, connectAgents, tool } from "@nylorun/agents";
+import { Agent, createActionHandler, createClient, tool } from "@nylorun/agents";
 import { z } from "zod";
 
-const assistant = Agent({
-  id: "assistant",
-  name: "Assistant",
-  instructions: "Use the available tools.",
-  tools: [
+const assistant = Agent({ id: "assistant", name: "Assistant" })
+  .instructions("Use the available tools.")
+  .tools(
     tool({
       name: "lookup",
       input: z.object({ id: z.string() }),
@@ -53,8 +66,7 @@ const assistant = Agent({
         return { id, owner: ctx.info };
       },
     }),
-  ],
-});
+  );
 
 // Explicit Tenant API client (options or env / link via createClient()).
 const client = createClient({
@@ -70,19 +82,22 @@ const session = await client.createSession({
 await session.input("Look up item 123", { idempotencyKey: requestId });
 const history = await session.history();
 
-// Executor-only mode when you already hold an executor key:
-const connection = connectAgents({
+// A process that only serves Actions holds no key: it reads the Tenant's public keys.
+const actions = createActionHandler({
   agents: [assistant],
   implementationVersion: "app-1",
   runtime: {
-    url: process.env.NYLORUN_RUNTIME_URL,
-    key: process.env.NYLORUN_EXECUTOR_KEY,
-    tenant: process.env.NYLORUN_TENANT,
+    url: process.env.NYLORUN_RUNTIME_URL!,
+    tenant: process.env.NYLORUN_TENANT!,
   },
+  url: "https://app.example.com/nylorun/actions",
   onError: console.error,
 });
-await connection.ready;
-await connection.close();
+app.post("/nylorun/actions", actions.node);
+// A deploy step with the application key registers the URL once:
+await createActionHandler({ agents: [assistant], client }).register({
+  url: "https://app.example.com/nylorun/actions",
+});
 ```
 
 ```sh
@@ -97,68 +112,51 @@ throws `IncompatibleRuntimeError` / `incompatible_host` when the Host range or
 required features do not match. Re-exports include `PROTOCOL_FEATURES`,
 `ERROR_CODES` and `compareVersions`.
 
-Load Agent Skills from a local catalog folder with `skills(path)`:
+Load Agent Skills from a local catalog folder with `.skills(path)`:
 
 ```ts
-import { Agent, skills } from "@nylorun/agents";
-
-const assistant = Agent({
-  id: "assistant",
-  name: "Order assistant",
-  instructions: "Use lookup_order for orders.",
-  tools: [lookupOrder],
-}).use(skills("./assistant-skills"));
+import { Agent } from "@nylorun/agents";
+
+const assistant = Agent({ id: "assistant", name: "Order assistant" })
+  .instructions("Use lookup_order for orders.")
+  .tools(lookupOrder)
+  .skills("./assistant-skills");
 ```
 
 Each subdirectory under the catalog must contain a `SKILL.md` with YAML frontmatter (`name`, `description`) per [Agent Skills](https://agentskills.io/home). Supporting files (for example `references/`) are available through `read_skill_resource` after `load_skill`. The helper sets both the manifest skill catalog and the on-disk skill records so you do not duplicate content.
 
-Declare MCP servers with `mcp(...)` (same map shape as agent-plugins `mcpServers` / manifest v3):
+Declare MCP servers with `.mcp(...)` (same map shape as agent-plugins `mcpServers`):
 
 ```ts
-import { Agent, mcp } from "@nylorun/agents";
-
-const assistant = Agent({
-  id: "assistant",
-  name: "Assistant",
-  instructions: "Use the available tools.",
-}).use(
-  mcp({
-    github: {
-      name: "github",
-      type: "streamable-http",
-      url: "https://mcp.example.com/github",
-    },
-  }),
-);
+import { Agent } from "@nylorun/agents";
+
+const assistant = Agent({ id: "assistant", name: "Assistant" })
+  .instructions("Use the available tools.")
+  .mcp({
+    github: { type: "streamable-http", url: "https://mcp.example.com/github" },
+  });
 ```
 
-Each key must equal that server's `name`. Transports follow [Agent Plugins MCP servers](https://agent-plugins.org/plugin-authors/mcp-servers): `stdio`, `streamable-http`, and `sse`. Pass `{ id: "…" }` as the second argument to override the default capability id `"mcp"`.
+Each key names a server; its `name` defaults to the key and, when given, must equal it. Repeated `.mcp()` calls add servers to the same capability. Transports follow [Agent Plugins MCP servers](https://agent-plugins.org/plugin-authors/mcp-servers): `stdio`, `streamable-http`, and `sse`. Attach an Agent Plugin package with `.plugin(path)`.
 
-Give an agent an isolated computer with `sandbox()`:
+Give a session a sandbox when you open it. The agent declares nothing, so the same agent runs with or without one, in any Tenant:
 
 ```ts
-import { Agent, sandbox } from "@nylorun/agents";
-
-const analyst = Agent({
-  id: "analyst",
-  instructions: "Analyse the data the user gives you. Use Python.",
-}).use(sandbox());
+const session = await client.createSession({
+  agentId: "analyst",
+  ownerUserId,
+  sandbox: {
+    network: { allow: ["pypi.org", "files.pythonhosted.org"] }, // no egress unless you list hosts
+    resources: { cpus: 2, memory: "2GiB" },
+  },
+});
 ```
 
-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({
-  image: "python:3.13",                           // any OCI image; default python:3.13-slim
-  network: { preset: "dev", allow: ["api.example.com"] }, // "none" | "dev" (default) | "open"
-  resources: { cpus: 2, memory: "2GiB" },
-  idle: "15m",                                    // stop compute when idle; files persist
-}))
-```
+The model gets `bash`, `read`, `write`, `edit`, `grep` and `glob` on a persistent `/workspace`. These tools run in the Runtime, not in your process, so sandbox-only agents need no Action endpoint. The Runtime decides where the sandbox runs: today an emulated shell in the Runtime process, which is not a VM boundary and takes no `image`.
 
-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.
+`sandbox` takes `false` for none, `{ session }` to share another session's sandbox, or an inline sandbox as above; omit it for the Tenant's default. The Runtime checks it against the Tenant's limits (`GET`/`PUT /v1/tenant/sandbox`: a network ceiling, a resource maximum, the idle timeout) and answers `400` with every problem it finds. A caller acting for a user (`app.as(...)`) can't define one inline; it gets the Tenant's default or `false`. Private networks, loopback, the host and cloud metadata endpoints are always blocked.
 
-Put an agent in another agent's `tools` to let the model delegate to it:
+Add an agent with `.subagents()` to let the model delegate to it:
 
 ```ts
 import { Agent } from "@nylorun/agents";
@@ -168,54 +166,47 @@ const researcher = Agent({
   id: "researcher",
   description:
     "Investigates an order's history. Returns a short summary with the ids it relied on.",
-  instructions:
-    "Investigate one question about one order. Be exhaustive, then be brief.",
-  tools: [searchOrders, readTicket],
-  outputSchema: z.object({
-    summary: z.string(),
-    evidence: z.array(z.string()),
-  }),
-});
+})
+  .instructions("Investigate one question about one order. Be exhaustive, then be brief.")
+  .tools(searchOrders, readTicket)
+  .output(z.object({ summary: z.string(), evidence: z.array(z.string()) }));
 
-const support = Agent({
-  id: "support",
-  instructions:
+const support = Agent({ id: "support" })
+  .instructions(
     "For anything needing more than two lookups, delegate to researcher with a complete, self-contained task.",
-  tools: [lookupOrder, refundOrder, researcher],
-});
+  )
+  .tools(lookupOrder, refundOrder)
+  .subagents(researcher);
 ```
 
-The tool is named after the agent's `id` and takes `{ task: string }`; the agent's `description` (required) is what the parent's model reads to decide when to delegate. The child starts with a fresh context: it sees its own instructions and the task, nothing of the parent's conversation, and only its final text (or `outputSchema` result) comes back. It keeps its own tools, hooks, skills and MCP servers, served by the executor you already run for the parent (`connectAgents({ agents: [support] })` serves both), shares the session's sandbox, and starts with empty `ctx.state`. Tools can read `ctx.agent` (`{ id, path, delegationId }`). Several delegation calls in one model response run in parallel. An empty answer, a failure (with the child's last text marked as evidence) or a cancelled child reaches the parent's model as a failed tool result, never as success. The Runtime emits `delegation.started` and `delegation.completed`; `session.history({ agent })` filters by `delegationId` (one child invocation) or by path such as `support/researcher` (every concurrent child that shares that path).
+The tool is named after the agent's `id` and takes `{ task: string }`; the agent's `description` (required) is what the parent's model reads to decide when to delegate. The child starts with a fresh context: it sees its own instructions and the task, nothing of the parent's conversation, and only its final text (or `outputSchema` result) comes back. It keeps its own tools, hooks, skills and MCP servers, served by the Action endpoint you already mount for the parent (`createActionHandler({ agents: [support] })` serves both), shares the session's sandbox, and starts with empty `ctx.state`. Tools can read `ctx.agent` (`{ id, path, delegationId }`). Several delegation calls in one model response run in parallel. An empty answer, a failure (with the child's last text marked as evidence) or a cancelled child reaches the parent's model as a failed tool result, never as success. The Runtime emits `delegation.started` and `delegation.completed`; `session.history({ agent })` filters by `delegationId` (one child invocation) or by path such as `support/researcher` (every concurrent child that shares that path).
 
-Delegate when the parent should keep the answer. When a specialist should own the rest of the conversation, switch capabilities with a `before("step")` patch instead. This version is one level deep and non-interactive: a delegated agent cannot use agents as tools, its tools cannot declare `approval` (keep those on the parent), and `ctx.ask`, `ctx.approve`, `ctx.sleep` or `ctx.waitFor` inside it fail with `delegation.interaction-unsupported`. Delegation is not an approval boundary; approvals live on tools.
+A flow agent can be a subagent too: `.subagents(researchFlow)` with a `description` like any other. Its manifest is inlined in the parent's, so it is saved with the parent and served by the parent's Action endpoint. When the model calls it, the flow runs on the Runtime in its own linked session (a fresh one per call, linked from the parent's with a `node.agent` event at `support/<flow id>`), its agents in theirs, and the flow's output comes back as the tool result; a failed flow is a failed tool result. Cancelling the parent cancels the flow. Flow agents as subagents run on the Runtime only, not in a local `run()`. An approval asked for inside the flow waits on the flow's own session.
 
-## Workflows
+Delegate when the parent should keep the answer. When a specialist should own the rest of the conversation, switch capabilities with a `.beforeModel()` patch instead. This version is one level deep and non-interactive: a delegated agent cannot use agents as tools, its tools cannot declare `approval` (keep those on the parent), and `ctx.ask`, `ctx.approve`, `ctx.sleep` or `ctx.waitFor` inside it fail with `delegation.interaction-unsupported`. Delegation is not an approval boundary; approvals live on tools.
 
-Nest `Chain`, `Switch`, `Parallel`, `Map`, and `Loop` around agents and `tool()` to
-build durable flows. A workflow is a definition with `kind: "workflow"`: register
-it in `export const agents` (or `saveAgent(workflow)` — referenced agents are
-saved first), then `createSession({ agentId })` and `session.input(value)` like
-any agent. `input` sends string values as `content` and other JSON as `data`.
-`connectAgents({ agents: [workflow] })` saves the tree and connects executors for
-the workflow id and every referenced agent. Tool nodes, pure functions (slot
-`input`, Switch `on`, Map `over`, Loop `decide`), and Loop `verify` run as Actions
-routed by `(workflowId, key)`.
+## Flow agents
+
+An agent's body is either a ReAct loop (the model decides) or a flow (your code
+decides). A flow agent is built from stages, each shaped `.stage(whatRuns, { how })`,
+and is registered, saved and opened as a session like any agent: put it in
+`export const agents`, `saveAgent(flowAgent)`, then `createSession({ agentId })`
+and `session.input(value)`. `input` sends string values as `content` and other JSON
+as `data`. On the wire a flow agent is a workflow manifest v2 (`kind: "workflow"`,
+`workflowSchemaVersion: 2`) that embeds the agents it runs, so one document and one
+manifest hash cover the whole flow; its agents are not listed on their own.
 
 ```ts
-import { Agent, Chain, Loop, Map, tool } from "@nylorun/agents";
+import { Agent, tool } from "@nylorun/agents";
 import { z } from "zod";
 
-const planner = Agent({
-  id: "planner",
-  instructions: "Return { tasks: string[] }.",
-  outputSchema: z.object({ tasks: z.array(z.string()) }),
-}).build();
+const planner = Agent({ id: "planner" })
+  .instructions("Return { tasks: string[] }.")
+  .output(z.object({ tasks: z.array(z.string()) }));
 
-const coder = Agent({
-  id: "coder",
-  instructions: "Implement one task. Return { summary }.",
-  outputSchema: z.object({ summary: z.string() }),
-}).build();
+const coder = Agent({ id: "coder" })
+  .instructions("Implement one task. Return { summary }.")
+  .output(z.object({ summary: z.string() }));
 
 const openPr = tool({
   name: "open-pr",
@@ -226,44 +217,52 @@ const openPr = tool({
   },
 });
 
-export const shipFeature = Chain({
-  id: "ship-feature",
-  steps: [
-    planner,
-    Map({
-      id: "implement",
-      over: (plan) => plan.tasks,
-      each: Loop({
-        id: "code",
-        run: coder,
-        verify: () => ({ pass: true }),
-        decide: ({ output }) => ({ output }),
-      }),
+export const shipFeature = Agent({ id: "ship-feature" })
+  .step(planner)
+  .map(
+    Agent({ id: "code" }).loop(coder, {
+      verify: ({ output }) => (output.summary ? { pass: true } : { pass: false, feedback: "Say what you changed." }),
+      max: 2,
     }),
-    {
-      run: openPr,
-      input: ({ value }) => ({
-        summaries: value.map((item: { summary: string }) => item.summary),
-      }),
-    },
-  ],
-});
+    { id: "implement", input: ({ input }) => input.tasks },
+  )
+  .step(openPr, { input: ({ input }) => ({ summaries: input.map((item) => item.summary) }) });
 
 export const agents = [shipFeature];
 ```
 
-| Primitive | Role |
+| Stage | Role |
 | --- | --- |
-| **Chain** | Steps in order; slots reshape with `{ run, id?, input? }` |
-| **Switch** | Pure `on(input) → key`, then the matching case (or `default`) |
-| **Parallel** | Fixed named branches at once; output is an object |
-| **Map** | Pure `over(input) → items`, one child per item; output is an array |
-| **Loop** | `run` → `verify` → `decide` until `{ output }` |
-
-Agents inside a workflow keep their own sessions (linked from the workflow
-session) and share one sandbox: declare identical specs on every agent that
-uses one, attach with `createSession({ …, sandbox: { session } })`, call
-built-ins via `session.sandbox` (application) or `ctx.sandbox` (executor).
+| **`.step(x, { id?, input? })`** | Run one agent, tool or `flow()`; its output is the next stage's input |
+| **`.switch({ ...cases, default? }, { on })`** | `on({ input })` returns a case name; exactly that case runs |
+| **`.parallel(branches)`** | Fixed named branches at once, same input; output is an object |
+| **`.map(each)`** | Run `each` once per item of the input, which must be an array; output is an array |
+| **`.loop(body, { verify, max?, decide? })`** | Run, verify, run again with the feedback until it passes; needs `max` or `decide` |
+
+Every function receives one object: `{ input, results, flowInput }`. `input` is
+what the stage received, `results` holds earlier steps' outputs by step id, and
+`flowInput` is the agent's own input. The `input` option computes a stage's input;
+the `id` option names a step. `flow()` builds a sequence with no id for a case,
+branch, map item or loop body that is more than one step. Types flow from each
+step's `.output()` schema to the next stage's `input`.
+
+Agents inside a flow keep their own sessions, linked from the flow's session and
+named by the agent: a step's id (the agent's id, or `{ id }`), with `[i]` for each
+Map item and a nested flow agent's id in front of its own agents'. Control stages
+add nothing, so wrapping a step in `.loop()` or moving it between cases keeps its
+session. An agent may appear once per flow; use it again under a new id with
+`.step(writer, { id: "final-writer" })` or `writer.withId("…")`
+(`flow.duplicate-leaf`). Functions are bound under stage keys: a stage's `id`, or
+its position such as `@1.default.1`, plus `:input`, `:on`, `:verify` or `:decide`.
+Name the stages you may reorder.
+
+`Chain`, `Switch`, `Parallel`, `Map` and `Loop` still build workflow manifest v1
+directly and run as before; a flow agent can't be a child of them.
+
+The agents in a flow share one sandbox: open the flow's session with it,
+`createSession({ …, sandbox: { … } })`, and every agent, tool step and `verify` in the
+flow uses it. Share it with another session with `sandbox: { session }`, and call
+built-ins via `session.sandbox` (application) or `ctx.sandbox` (a tool).
 Observe with `session.observe({ follow: true })` to merge linked agent streams;
 `pending()` lists waits across the tree. Studio renders the manifest tree and
 live node status. Source examples:
@@ -276,23 +275,32 @@ Use `session.observe({ cursor, signal })` for resumable canonical events, `sessi
 
 Connection defaults follow `resolveConnection` (options → environment → Project
 link). Implementation version defaults from `NYLORUN_IMPLEMENTATION_VERSION`,
-then `dev`. Application mode of `connectAgents({ agents })` registers derived
-executor principals; executor-only mode still takes an explicit executor key.
-Agents do not hash the manifest, and an in-flight action stays claimable after
+then `dev`. `register` saves the definitions and registers one endpoint per
+served agent with the application key; serving deliveries needs no key.
+Agents do not hash the manifest, and an in-flight action is still delivered after
 the registered digest changes. Model selection and model credentials belong to
 the Tenant.
 
-After registration, `connectAgents` opens authenticated fetch SSE before discovering actions, rediscovers after reconnection, and claims pending actions for a connected agent id. It renews leases while executing, then retries HTTP result delivery with the same recorded outcome and idempotency key. Reconnect delay is bounded at 30 seconds. Notifications confer no execution authority. There is no periodic action-discovery polling. Close aborts the stream, HTTP requests and lease timers and signals running functions; JavaScript cannot forcibly terminate a function that ignores its signal. The host makes expired in-flight actions uncertain instead of automatically repeating external effects.
+After registration, the Runtime POSTs each Action to the endpoint with a delivery token signed by the Tenant's key; the handler verifies it before any code runs and answers with the outcome. A background tool answers `202`, heartbeats with the newest token and posts its result. A cancel aborts the request, which reaches the tool as `ctx.signal`; JavaScript cannot forcibly terminate a function that ignores its signal. The host makes lost in-flight deliveries uncertain instead of automatically repeating external effects.
 
-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`.
+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 Action endpoint 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`.
 
 ## 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.
+The Runtime serves the Tenant's agents to any [AG-UI](https://docs.ag-ui.com)
+client (`@ag-ui/client`'s `HttpAgent`, CopilotKit, a desktop renderer) at
+`/v1/ag-ui/agents/{agentId}` (optional feature `ag-ui-endpoint`). Each AG-UI
+thread is one session per person, agent and thread. There are two ways in:
+
+- **From your own server**, with `@nylorun/agents/ag-ui` (below): your server
+  signs people in and the handler forwards each request to the Runtime acting
+  for that person. The browser never sees the Runtime.
+- **From the page itself**, with `@nylorun/agents/browser`'s `agUi()` and a
+  subject token ([In the browser](#in-the-browser)). No chat traffic passes
+  through your server.
+
+Both reach the same threads: one started through the handler continues from
+the page.
 
 ```ts
 import { createServer } from "node:http";
@@ -318,9 +326,10 @@ createServer(toNodeListener(agui)).listen(3000);
 
 `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).
+one, and `session(subject, agentId)` to add the person's `vaultIds`,
+`credentialSelections` or `info`. They apply when the thread's session is
+created, on its first run; later runs keep them. Whatever the browser sends in
+`forwardedProps.nylorun` is replaced.
 
 - Each AG-UI message id is the command's idempotency key: a retried run replays
   the same turn instead of starting a second one.
@@ -338,9 +347,9 @@ identity).
   `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.
+- The handler needs a Runtime with the optional feature `ag-ui-endpoint` and
+  answers `502` (`runtime_feature_missing`) without it. It loads no AG-UI
+  package itself: the Runtime does the protocol work.
 
 A complete web backend with a test is in
 [examples/src/ag-ui](../examples/README.md#an-agent-in-your-web-app-ag-ui).
@@ -349,8 +358,71 @@ 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.
+regenerated. A browser reaches the Runtime only with a subject token and a
+publishable key, never with a Tenant key.
+
+## A2A
+
+`@nylorun/agents/a2a` serves the Tenant's agents to other agents over
+[A2A](https://a2a-protocol.org) 1.0 (JSON-RPC) from your own server: the
+gateway. Your server authenticates each partner and names the subject its tasks
+belong to. The handler forwards each request to the Runtime, which speaks A2A,
+so the handler loads no A2A package and parses no message.
+
+```ts
+import { createServer } from "node:http";
+import { createA2aHandler, toNodeListener } from "@nylorun/agents/a2a";
+import support from "./agents/support.js";
+
+const a2a = createA2aHandler({
+  basePath: "/a2a",
+  agents: [support], // nothing else is reachable
+  // undefined → 401; return { subject, agents } to give a partner fewer agents
+  subject: (request) => partnerFor(request.headers.get("x-partner-key"))?.subject,
+  publicUrl: "https://api.example.com/a2a", // for the card; default: the request's origin
+  card: {
+    provider: { organization: "Example Inc.", url: "https://example.com" },
+    securitySchemes: {
+      partnerKey: { apiKeySecurityScheme: { location: "header", name: "X-Partner-Key" } },
+    },
+    securityRequirements: [{ schemes: { partnerKey: { list: [] } } }],
+  },
+});
+
+createServer(toNodeListener(a2a)).listen(3000);
+```
+
+| Method and path under `basePath` | Operation |
+| --- | --- |
+| `GET /{agentId}/.well-known/agent-card.json` | The Agent Card: name, description and one skill from the manifest, with this endpoint's URL and your provider and security schemes. Public; `subject` is not called |
+| `POST /{agentId}` | One A2A JSON-RPC request, answered by the Runtime |
+
+What the Runtime answers (Host feature `a2a-endpoint`):
+
+- `SendMessage` waits until the task completes, fails, is canceled or asks
+  for input, for at most 5 minutes (then it returns `WORKING`); with
+  `configuration.returnImmediately` it returns at once and the partner polls
+  `GetTask`. `CancelTask` works on a running task.
+- A `contextId` is one session per partner, agent and context; a task is one
+  turn. A message without `taskId` starts a task (one at a time per context).
+  A question from the agent pauses the task as `TASK_STATE_INPUT_REQUIRED`
+  with the question as the status message; the partner answers with a message
+  on the same `taskId`.
+- The `messageId` is the idempotency key: a retried message returns the same
+  task.
+- Text parts, or a single data part, in; the turn's output as the artifact
+  `output` (text, or JSON as a data part). Files are
+  `ContentTypeNotSupportedError`.
+- Clients must send `A2A-Version: 1.0` (header or `?A2A-Version=`).
+- Not yet: `ListTasks`, streaming and `SubscribeToTask`
+  (`UnsupportedOperationError`; the card says `streaming: false`), push
+  notifications, the extended card, and approvals. An agent that pauses for an
+  approval shows `INPUT_REQUIRED`, refuses a reply, and can be canceled, so do
+  not publish agents with approval-gated tools yet.
+- The handler calls the Runtime as the partner's subject with the scope
+  `sessions:own` only, so one partner never reaches another's tasks. It sends
+  no header the partner chose except `A2A-Version` and `A2A-Extensions`. Without
+  `a2a-endpoint` on the Runtime it answers `502` (`runtime_feature_missing`).
 
 ## Acting for a person (app servers)
 
@@ -383,10 +455,143 @@ compatibility check, so calling `as()` per request is cheap.
 | `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
+No scope reaches Tenant reset, config seed, Action endpoints, 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`.
+for a subject.
+
+## Minting subject tokens (app servers)
+
+To let a person's browser or app call the Runtime directly, your server mints a
+short-lived **subject token** for them instead of carrying their requests
+(optional feature `subject-tokens`). What a token may do comes from the Tenant's
+access policy, not from the caller:
+
+```ts
+import { createClient } from "@nylorun/agents";
+
+const app = createClient(); // the Tenant key, on the server only
+
+// Once: roles, their agents and limits (or `nylo access policy init`).
+await app.access.putPolicy({
+  version: 1,
+  roles: {
+    user: {
+      scopes: ["sessions:own", "agents:read"],
+      agents: ["support"],
+      limits: { turnsPerHour: 60, concurrentTurns: 2 },
+    },
+  },
+  anon: { scopes: [], agents: [] },
+  tokens: { maxTtlSeconds: 600 },
+});
+
+// Per signed-in person, from a same-origin POST route:
+const { token, expiresAt } = await app.tokens.create({
+  subject: `app:${user.id}`,
+  role: "user",
+});
+```
+
+The client sends it as `Authorization: Bearer <token>` with `Nylorun-Tenant`.
+Tokens carry only `sessions:own`, `vaults:own` and `agents:read`, live at most
+15 minutes, and see only `{ agentId, name, description }` of their role's
+agents. A token that expired or was revoked answers `401` with
+`code: "token_expired"`: fetch a new one and retry. Starting more turns than the
+role allows answers `429` with `code: "limit_exceeded"` and `Retry-After`.
+
+| Call | Does |
+| --- | --- |
+| `app.access.revokeSubject(subject)` | Ends every token minted so far for the person and their open event streams |
+| `app.access.signingKeys.rotate()` | Rotates the Tenant's signing keys without signing anyone out (`{ force: true }` for incidents) |
+| `app.access.signingKeys.list()`, `.revoke(kid)`, `app.access.jwks()` | Inspect and retire keys; the public keys |
+
+Keep tokens in memory on the client, never in `localStorage`, and serve the
+minting route without CORS. `nylo access …` does the same from the terminal.
+
+`createTokenEndpoint` is that route, ready to mount (Next.js, Hono or any
+`Request` → `Response` handler):
+
+```ts
+import { createTokenEndpoint } from "@nylorun/agents";
+
+export const POST = createTokenEndpoint({
+  client: app,
+  role: "user",
+  subject: (request) => userFromCookie(request)?.id,
+});
+```
+
+## In the browser
+
+`@nylorun/agents/browser` calls the Runtime from a web page or an app with a
+publishable key and the token route above (optional feature `browser-access`).
+It loads no Node module.
+
+```ts
+import { createBrowserClient } from "@nylorun/agents/browser";
+
+const nylo = createBrowserClient({
+  url: "https://runtime.example.com",
+  publishableKey: "nr_pub_tn_…", // app.access.publishableKeys.create({ name, origins })
+  token: () => fetch("/api/nylorun/token", { method: "POST" }).then((r) => r.json()),
+});
+
+const session = await nylo.createSession({ agentId: "support" }); // owned by the token's subject
+await session.input("Where is my order?", { idempotencyKey: crypto.randomUUID() });
+for await (const event of session.observe()) console.log(event.type);
+```
+
+For a chat UI, `agUi()` gives `@ag-ui/client`'s `HttpAgent` a `fetch` with the
+key and a current token:
+
+```ts
+import { HttpAgent } from "@ag-ui/client";
+
+const { url, fetch } = nylo.agUi("support");
+const agent = new HttpAgent({
+  url,
+  fetch,
+  threadId,
+  initialMessages: await nylo.agUiHistory("support", threadId),
+});
+```
+
+When the Runtime ends a run's stream because the token expired or was revoked,
+that `fetch` reattaches from the last event with a new token, so the agent sees
+one run. A person's token may attach their own vaults to a new thread
+(`forwardedProps: { nylorun: { session: { vaultIds } } }`) but not set `info`.
+
+The client keeps the token in memory, fetches a new one a minute before it
+expires or when the Runtime answers `401 token_expired`, and never asks for two
+at once. Event streams that the Runtime ends at token expiry or revocation
+reconnect from their last event with a new token. Create a publishable key per
+app with the origins that serve it (`http://localhost:*` for development);
+requests from other origins get the opaque `404`.
+
+The SDK depends only on core within the Nylorun packages; installing it does not install harness or any AG-UI or A2A package. Use `/define`, `/client`, `/ag-ui`, `/a2a` or `/browser` for focused imports, or the root for convenience. Studio uses `/client`. See [the adopted host contract](../harness/HOST_CONTRACT.md).
+
+## Embedding Studio (desktop apps)
+
+`@nylorun/agents/studio-embed` is the contract between Studio and an app that
+shows it in an iframe, such as Babai. It exports the message schema
+(`StudioEmbedMessageSchema`, envelope `{ type: "nylorun.studio", protocol, kind }`),
+the login-token and session schemas, `STUDIO_EMBED_PROTOCOLS` and
+`parseFrameAncestors`.
+
+```ts
+import { StudioEmbedMessageSchema } from "@nylorun/agents/studio-embed";
+
+window.addEventListener("message", (event) => {
+  if (event.source !== frame.contentWindow || event.origin !== studioOrigin) return;
+  const message = StudioEmbedMessageSchema.safeParse(event.data);
+  if (!message.success) return;
+  if (message.data.kind === "ready") frame.contentWindow!.postMessage(init, studioOrigin);
+});
+```
 
-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).
+The embedder's backend mints the login token with the admin key
+(`mintStudioLoginToken` in `@nylorun/admin`) and the page passes it to Studio in
+`init`. No key reaches the page. Studio's origin allowlist is
+`NYLORUN_STUDIO_FRAME_ANCESTORS`.