@nylorun/agents 0.9.0-beta → 0.11.0-beta

package/README.md

@@ -1,44 +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 }` 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 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 two `NYLORUN_*` variables or the Project link
+that `npx nylorun start` 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)
+1. Explicit `{ url, key }`
+2. Environment — if `NYLORUN_RUNTIME_URL` or `NYLORUN_SERVER_KEY` is set, both
+   must be present
+3. Project link — `.nylorun/link.json` + `credentials.json` (the application
+   key), written by `npx nylorun start`. A link from before one Tenant per
+   installation (format 0 or 1) fails with `connection_missing`: run
+   `npx nylorun start` in the project again.
 
-Sources never mix. Partial environment fails with `connection_missing`.
+Sources never mix. Partial environment fails with `connection_missing`. A
+Runtime serves one Tenant, so nothing names it: the `tenant` option and
+`NYLORUN_TENANT` are gone (protocol 5).
 
 ```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" })
@@ -57,7 +77,6 @@ const assistant = Agent({ id: "assistant", name: "Assistant" })
 const client = createClient({
   url: process.env.NYLORUN_RUNTIME_URL,
   key: process.env.NYLORUN_SERVER_KEY,
-  tenant: process.env.NYLORUN_TENANT,
 });
 await client.saveAgent(assistant, { implementationVersion: "app-1" });
 const session = await client.createSession({
@@ -67,28 +86,28 @@ 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,
-  },
+  runtime: { url: process.env.NYLORUN_RUNTIME_URL! },
+  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
 eval "$(npx @nylorun/cli env)"
-# → NYLORUN_RUNTIME_URL, NYLORUN_SERVER_KEY, NYLORUN_TENANT
+# → NYLORUN_RUNTIME_URL, NYLORUN_SERVER_KEY
 ```
 
-Every request sets `Nylorun-Tenant` and `Nylorun-Protocol`. A `tenant` field in a
-body or query is never read from caller input. Before the first authenticated
+Every request sets `Nylorun-Protocol` (5) and no `Nylorun-Tenant`: the Runtime
+serves one Tenant. Before the first authenticated
 request, `Transport` fetches `/health` once, checks protocol compatibility, and
 throws `IncompatibleRuntimeError` / `incompatible_host` when the Host range or
 required features do not match. Re-exports include `PROTOCOL_FEATURES`,
@@ -121,28 +140,22 @@ const assistant = Agent({ id: "assistant", name: "Assistant" })
 
 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 } from "@nylorun/agents";
-
-const analyst = Agent({ id: "analyst" })
-  .instructions("Analyse the data the user gives you. Use Python.")
-  .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:
+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`.
 
-```ts
-.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 `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.
 
 Add an agent with `.subagents()` to let the model delegate to it:
 
@@ -167,9 +180,9 @@ const support = Agent({ id: "support" })
   .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).
 
-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 executor. 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.
+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.
 
 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.
 
@@ -247,10 +260,10 @@ 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: declare it with `.sandbox(spec)` on the
-flow agent and give the agents that use it `.sandbox()` with no options (an agent
-that declares its own spec must match), attach with `createSession({ …, sandbox: { session } })`, call
-built-ins via `session.sandbox` (application) or `ctx.sandbox` (executor).
+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:
@@ -263,23 +276,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";
@@ -305,9 +327,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.
@@ -325,9 +348,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).
@@ -336,8 +359,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)
 
@@ -370,10 +456,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>`.
+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`.

package/dist/a2a/handler.d.ts

@@ -0,0 +1,59 @@
+/**
+ * An A2A endpoint over the Tenant's agents, as a web-standard `Request` → `Response` handler
+ * (gateway mode). The host authenticates each partner (`subject`); the handler forwards the
+ * partner's JSON-RPC request to the Runtime as that subject, and the Runtime speaks A2A (Host
+ * feature `a2a-endpoint`). It parses no A2A message and sends no header the partner chose
+ * except `A2A-Version` and `A2A-Extensions`, so a partner can never name a subject or scopes.
+ * The Agent Card comes from the Runtime, with this endpoint's URL and the host's provider and
+ * security schemes added.
+ */
+import type { BuiltWorkflow } from "@nylorun/core/define";
+import { type AgentSource, type AgentsClient } from "../client.js";
+/** A partner as the host authenticated it: its subject, and optionally fewer agents. */
+export interface A2aCaller {
+    /** Owner of the partner's tasks, e.g. `a2a:acme`. Keep it stable for a partner. */
+    subject: string;
+    /** Agents this partner may use, among the handler's `agents`. Default: all of them. */
+    agents?: readonly string[];
+}
+/** What the published Agent Card adds to the Runtime's: who serves it and how to authenticate. */
+export interface A2aCardOptions {
+    provider?: {
+        organization: string;
+        url: string;
+    };
+    documentationUrl?: string;
+    iconUrl?: string;
+    /** A2A `securitySchemes`, e.g. `{ partnerKey: { apiKeySecurityScheme: { location: "header", name: "X-Partner-Key" } } }`. */
+    securitySchemes?: Record<string, unknown>;
+    /** A2A `securityRequirements`, e.g. `[{ schemes: { partnerKey: { list: [] } } }]`. */
+    securityRequirements?: readonly unknown[];
+}
+export interface A2aHandlerOptions {
+    /** Agents this endpoint serves: built agents, workflows or their ids. Nothing else is reachable. */
+    agents: readonly (AgentSource | BuiltWorkflow | string)[];
+    /**
+     * The partner the request is from, authenticated by the host. `undefined` answers `401`;
+     * there is no anonymous mode. Not called for the Agent Card, which is public.
+     */
+    subject(request: Request): string | A2aCaller | undefined | Promise<string | A2aCaller | undefined>;
+    /** Where `fetch` is mounted, e.g. `/a2a`. Default `/`. */
+    basePath?: string;
+    /**
+     * The public URL of `basePath` as partners reach it, e.g. `https://api.example.com/a2a`.
+     * Default: the origin of each card request. Set it behind a proxy.
+     */
+    publicUrl?: string;
+    /** Application client. Default: `createClient()`, from the environment or the Project link. */
+    client?: AgentsClient | Promise<AgentsClient>;
+    card?: A2aCardOptions;
+}
+export interface A2aHandler {
+    /** One entry point that routes by method and path under `basePath`. Bound. */
+    readonly fetch: (request: Request) => Promise<Response>;
+    /** `POST {basePath}/{agent}`: one A2A JSON-RPC request, forwarded. */
+    call(request: Request, agentId: string): Promise<Response>;
+    /** `GET {basePath}/{agent}/.well-known/agent-card.json`: the agent's card. */
+    card(request: Request, agentId: string): Promise<Response>;
+}
+export declare function createA2aHandler(options: A2aHandlerOptions): A2aHandler;