@nylorun/agents 0.9.0-beta → 0.10.0-beta

package/CHANGELOG.md

@@ -1,5 +1,136 @@
 # @nylorun/agents
 
+## 0.10.0-beta
+
+### Major Changes
+
+- c121144: **Definitions no longer declare a sandbox.** `.sandbox()` on ReAct and flow agents, and the `sandbox`, `SandboxError`, `SandboxOptions` and `SandboxCapability` exports, are removed. Open the session with one instead, `createSession({ sandbox: { … } })`, or set the Tenant's default; see `MIGRATION.md`.
+
+  - **Build and registration.** A capability that still carries `sandbox` fails the build (`sandbox.in-definition`), and `PUT /v1/agents/:id` refuses such a definition with a `400` that names it. Definitions stored before this release keep their sandbox.
+  - **Trees.** `sandbox.mismatch` and `workflow.sandbox-mismatch` are gone, with the workflow manifest's derived `sandbox`: a tree shares the sandbox its session was opened with.
+  - **Executors.** The action claim reports whether the session has a sandbox (`ActionClaim.sandbox`), and `ctx.sandbox` follows it.
+
+- 9546ac7: **Protocol 4: every session event is typed, on the `nylorun.event/2` envelope.**
+
+  - **The catalog.** `EVENT_CATALOG` in `@nylorun/core/contracts` lists every event type the Runtime writes, with its payload schema, its schema version and its source. `SessionEventSchema` is their union, discriminated on `type`; `parseSessionEvent` types a known event and returns an unknown one as the bare envelope.
+  - **The envelope.** Events carry `schema`, `seq`, `epoch`, `runId`, `incarnation`, `schemaVersion`, `source`, `evidence`, `visibility`, `retention` and an optional `trace`. `createdAt` is renamed `time`. The envelope is no longer strict, so later fields never break a client.
+  - **Validated writes.** `Tx.event` is typed by the catalog, and both Session Stores check each event against it before it commits (`InvalidEventError`). Workflow `action.pending` payloads may carry `path` and `key`.
+  - **OpenAPI.** Each event type is a component (`MessageAssistantEvent`, …), `SessionEvent` is their union, and the session SSE and history responses refer to them.
+  - **Clients.** `@nylorun/agents` reads events with `parseSessionEvent`, so a newer Runtime's event types reach your code instead of failing the stream. Studio reads `time`.
+
+  See `MIGRATION.md`.
+
+### Minor Changes
+
+- c7614a4: **A2A: serve agents to other agents (v1, gateway mode).** The Runtime answers [A2A](https://a2a-protocol.org) 1.0 over JSON-RPC for the Tenant's agents (optional Host feature `a2a-endpoint`), and the app server publishes them with `createA2aHandler`.
+
+  - **Runtime.** `POST /v1/a2a/agents/:agent` acts for a subject with `sessions:own`. It serves `SendMessage` (blocking up to 5 minutes, or `returnImmediately`), `GetTask` and `CancelTask`. A context is one session per subject, agent and `contextId`, and a task is one turn. A question pauses the task as `TASK_STATE_INPUT_REQUIRED` until the caller replies on the same task. The `messageId` is the idempotency key. `ListTasks`, streaming, push notifications and the extended card answer with their A2A errors, and approvals cannot be answered over A2A yet. `GET /v1/a2a/agents/:agent/card` returns the card built from the manifest, without interfaces. `observeSession` lets in-process readers join a session's shared event feed.
+  - **Agents SDK.** `@nylorun/agents/a2a`: `createA2aHandler({ agents, subject, publicUrl, card })` forwards each partner's JSON-RPC request to the Runtime as that partner's subject, and serves the Agent Card with its own URL, provider and security schemes. It loads no A2A package. `Transport.forward` returns the Runtime's raw response.
+
+- 5f23047: **Action endpoints: `createActionHandler` (preview; needs a Runtime with the `action-endpoints` feature to register).** An application serves its agents' tools, hooks and workflow functions from one HTTP handler, which the Runtime will call, in place of `connectAgents`.
+
+  - `createActionHandler({ agents })` returns `{ fetch, node, register }`. `fetch` is a web-standard handler and `node` serves `node:http` and Express. Each request is verified before any code runs: its delivery token (`Nylorun-Signature`) must be an ES256 token signed by the Tenant's signing key, for this Tenant, this URL, this Action and generation, and the exact body. The Action then runs through the same code executors use, with the request's signal as `ctx.signal`. The answer is the tagged outcome (`Nylorun-Outcome: 1`). An agent or tool it does not serve answers `404`, and a workflow Action for another version of the workflow answers `409`. A token signed with a key the handler has not seen yet (just after a rotation) answers `503`, which the Runtime retries.
+  - A process that only serves Actions needs no key: set `runtime: { url, tenant }` and it reads the Tenant's public keys, or pass them in `jwks`. Verification uses WebCrypto; the SDK takes no JWT dependency.
+  - `register({ url })` saves the definitions (`saveDefinitions: false` skips it), registers the URL for every served agent, and pings each one through the Runtime. It refuses a Runtime without `action-endpoints` before sending anything.
+  - `ctx.sandbox` calls back with the delivery token. `createActionSandbox` accepts no claim for this case, and `Transport.withKey` copies a transport with another bearer, sharing its compatibility check.
+
+- 4282d5f: **Breaking: executors are removed; protocol 3.** The Runtime delivers every Action (tool, hook, `fn`, `verify`) to the Action endpoint an agent registers. It no longer offers Actions for executors to claim. See `MIGRATION.md`, "Action endpoints replace executors".
+
+  - **Core.** `PROTOCOL_VERSION` is 3 and a Host serves only protocol 3. `action-endpoints` is a protocol feature instead of an optional Host feature. Removed:
+
+    - the executor, claim and Action-list schemas;
+    - `action_result` from `SessionCommandSchema`;
+    - the `claimed` Action status, `claimId` and `leaseExpiresAt`.
+
+    New: `ActionResultReceiptSchema`, the receipt of `POST /v1/actions/:id/result`, which is `AcceptedResponse` without `requestId`.
+
+  - **Runtime.** Removed:
+
+    - `PUT`/`GET /v1/executors`, `DELETE /v1/executors/:agentId`, `GET /v1/executors/connect`;
+    - `GET /v1/actions`, `POST /v1/actions/:id/claim`, and the executor form of `POST /v1/actions/:id/heartbeat`;
+    - the `tenant/work` stream;
+    - claim expiry;
+    - executor credentials.
+
+    `POST /v1/actions/:id/sandbox/:tool` takes the delivery token only. Tenant summaries report `inFlightDeliveries` instead of `connectedExecutors`. Tenant status lists each agent's endpoint and has an `endpoints` check instead of `executors`.
+
+    Postgres migration 6 drops the `executors` table. Actions an executor had claimed are handled like lost deliveries: a tool becomes `uncertain`, and a hook, `fn` or `verify` is delivered again.
+
+  - **Agents.** Removed: `connectAgents`, the `@nylorun/agents/executor` subpath, derived executor keys and `NYLORUN_EXECUTOR_KEY`. Serve agents with `createActionHandler` and call `register({ url })`.
+  - **CLI.** Executor keys are gone from Project credentials. `nylo tenant endpoints` shows each endpoint and its health.
+
+- 82d95ef: **Action endpoints: background tools, CLI and Studio.**
+
+  - **Background tools (core, agents).** `tool({ …, background: true })` marks a tool that runs longer than an endpoint's timeout. The option is code-only and never serialized into the manifest. `createActionHandler` answers its delivery at once with `202`, runs the tool, heartbeats on the deadline the Runtime returns (each time with the newest delivery token), and posts the outcome. A heartbeat answered `409` (cancelled, lost or sent again) aborts the tool's `ctx.signal`, and nothing is posted. The new `waitUntil` option hands the background work to platforms that end a request's work with its response.
+  - **CLI.** `nylo tenant endpoints [--json]` lists each agent's Action endpoint and how it is doing, and `nylo tenant endpoints ping <agent>` pings one through the Runtime.
+  - **Studio.** Shows `action.delivered` ("Action delivered") and `action.delivery_failed` ("Delivery failed", with the endpoint's error and when it retries).
+
+- e28b8a9: **New projects serve their tools as an Action endpoint.** Everything Nylorun ships now uses Action endpoints instead of executors. `connectAgents` still works, but it is deprecated.
+
+  - **Starter (`create-agent`).** `src/main.ts` serves the agents with `createActionHandler` on `http://localhost:3001/nylorun/actions` (`PORT`, `NYLORUN_ACTIONS_URL`) and registers it. `npm run dev` and `npm start` work as before. The README explains which URL the Runtime must reach.
+  - **Local stack (`nylorun`).** The Runtime container sets `NYLORUN_ENDPOINT_LOOPBACK=docker-host` and maps `host.docker.internal` to the Docker host, so a `localhost` endpoint on the developer's machine is reachable, on Linux Docker Engine too.
+  - **Examples.** The AG-UI and browser-direct apps serve their Action endpoint at `/nylorun/actions` beside their other routes, and `register(origin)` replaces `connection.ready`.
+  - **Docs.** The README, `DEPLOYMENT.md` and the `@nylorun/agents` README describe Action endpoints.
+
+- 50d0fb5: **AG-UI in the Runtime.** The Runtime serves AG-UI itself at `/v1/ag-ui/agents/:agent` (optional Host feature `ag-ui-endpoint`), and pages reach it directly with a subject token. `@nylorun/agents` no longer contains or depends on any AG-UI package.
+
+  - **Runtime.** `POST /v1/ag-ui/agents/:agent` runs (a `RunAgentInput` in, server-sent AG-UI events out); `GET …/threads/:thread/messages`, `GET …/threads/:thread/events` (reattach) and `POST …/threads/:thread/cancel`. For a person named by a subject token (limited to the role's agents) or by subject headers; an application key alone is `400`. A thread's session (`sessionIdFor`, unchanged, so existing threads keep their sessions) is created on its first run with `forwardedProps.nylorun.session` (`vaultIds`, `credentialSelections`, and `info` from app servers only) and never changed afterwards. Limits and a busy session are streamed as `RUN_ERROR`. A stream opened with a token ends at the token's expiry or revocation with `CUSTOM nylorun.stream_closed`. The translation moves here from `@nylorun/agents`, and `@ag-ui/core` becomes a Runtime dependency.
+  - **Agents SDK.** `createAgUiHandler` keeps its options and routes and forwards each request to the Runtime acting for the signed-in person; it now needs a Runtime with `ag-ui-endpoint` (`502 runtime_feature_missing` otherwise). `session()` options apply when a thread's session is created; whatever the browser sends in `forwardedProps.nylorun` is replaced. `@ag-ui/core` is no longer a dependency. `@nylorun/agents/browser` adds `agUi(agentId)`, a `{ url, fetch }` for `HttpAgent` that adds the key and a current token and reattaches a run the Runtime ended at token expiry, so the agent sees one run, and `agUiHistory()`. The transport gains `forward()`, which returns the Runtime's response as it is.
+
+- 50d0fb5: **Browser access: web pages and apps call the Runtime with a publishable key.** A page ships a publishable key and gets subject tokens from its app server; the Runtime answers it directly, with CORS (optional Host feature `browser-access`).
+
+  - **Publishable keys.** `nr_pub_<tenantId>_…`, sent in `Nylorun-Key`, name the Tenant and one app, with an origin allowlist (exact origins, or `http://localhost:*` and `http://127.0.0.1:*` for development; none for native apps). `GET`/`POST /v1/access/publishable-keys`, `PUT`/`DELETE …/:id`. A key alone grants the policy's `anon` role, at most the public agent list, and reaches no session or vault. Postgres migration 4.
+  - **Host.** With browser access on, requests with an `Origin` reach Tenant routes; `/health`, `/ready` and admin routes still refuse them. Preflights for browser routes (agents, sessions, vaults, AG-UI, JWKS) are answered from the route alone and grant no credentials; the actual request must carry a publishable key whose allowlist names the origin, and only then do responses (JSON, errors, `401`, `429`, event streams) carry CORS headers. A disallowed origin or unknown key gets the opaque `404`. Tenant and executor keys sent with an `Origin` are refused before they are looked up. `Nylorun-Tenant` may be left out when `Nylorun-Key` names the Tenant; both must agree when both are sent. Browser access is on in the stack (`NYLORUN_BROWSER_ACCESS=off` turns it off) and off for a Host started from `host.json` unless `browserAccess` is true.
+  - **JWKS.** `GET /v1/access/jwks` is readable by any caller that reaches the Tenant.
+  - **Agents SDK.** `@nylorun/agents/browser`: `createBrowserClient({ url, publishableKey, token })` keeps subject tokens in memory, refreshes them a minute before expiry or after `401 token_expired`, one fetch at a time, and creates sessions and vaults owned by the token's subject; it loads no Node module. `createTokenEndpoint()` is the app server's token route. `client.access.publishableKeys` manages keys. The transport accepts a `token` source and a `publishableKey`, and event streams the Runtime ends at token expiry reconnect at once. The Tenant API client classes move to a module with no Node imports; `@nylorun/agents` and `/client` export the same names.
+  - **CLI.** `nylo access keys list|create|set-origins|revoke`.
+
+- c121144: **Choose a session's sandbox when you open it.** `createSession({ sandbox })` (`PutSessionRequest.sandbox`) now takes `false`, `{ session }` to share, or an inline sandbox: `image`, `network.allow` and `resources`. Omit it for the Tenant's default. The agent definition needs no `.sandbox()`: the Runtime resolves the request against the Tenant's limits, pins it on the session and adds the six sandbox tools to that session only (capability `nylorun.sandbox`). The registered definition is unchanged.
+
+  - **Tenant configuration.** `GET /v1/tenant/sandbox` adds `config`; `PUT /v1/tenant/sandbox` sets `default` (`none`, `virtual` or an inline sandbox) and `limits` (`network` ceiling, `resources` maximum, `defaultResources`, `idle`). Unset, a Tenant's default is `none` and its ceiling is the package registries and code hosts of today's `dev` preset. `SeedTenantConfigRequest.sandbox.config` seeds it.
+  - **Checks at open.** A request outside the limits is a `400` that lists every problem. An inline sandbox from a caller acting for a subject is a `403`; such callers get the Tenant default or `false`. An `image` is refused: the virtual sandbox has no images. The sandbox is fixed for the session's life: a different one on a later `PUT` is a `409`.
+  - **Trees inherit.** The agent sessions of a flow agent, the agents a session uses as tools, and sessions attached with `{ session }` use the sandbox the session was opened with, and get its tools.
+  - **Compatible.** An agent that declares `.sandbox()` keeps working as before; opening its session with a `sandbox` value is a `400` that says to remove `.sandbox()` from the agent.
+
+- 9d52189: **Studio embedding contract.** `@nylorun/core/contracts` defines the contract between Studio and an app that embeds it in an iframe, and `@nylorun/agents/studio-embed` re-exports it for Studio's web app and embedders such as Babai Desktop.
+
+  - `StudioEmbedMessageSchema`: every `postMessage` between the two, on the envelope `{ type: "nylorun.studio", protocol, kind }`. Kinds: `ready`, `init`, `token.refresh`, `theme.changed`, `navigate`, `session`, `token.expiring`, `route.changed`, `open.external`, `open.babai`, `error`. `STUDIO_EMBED_PROTOCOLS` is `[1]`.
+  - `StudioLoginTokenRequestSchema` and `StudioLoginTokenResponseSchema` for `POST /_studio/login-tokens` (now with optional `tenant` and `subject`), and `StudioSessionRequestSchema` and `StudioSessionResponseSchema` for `POST /_studio/sessions`.
+  - `parseFrameAncestors` and `isFrameAncestor` validate `NYLORUN_STUDIO_FRAME_ANCESTORS`: exact origins only, no wildcards, keywords, scheme-only entries or paths.
+
+- 50d0fb5: **Subject tokens: a person's own credential for the Runtime.** An app server mints a short-lived token for one signed-in person, and their app calls the Runtime directly (optional Host feature `subject-tokens`). Requests with application keys and subject headers are unchanged.
+
+  - **Runtime.** `POST /v1/tokens` (application key only) mints an ES256 JWT for a subject and a role, valid 60–900 seconds. The Tenant API accepts it as a bearer and resolves its scopes and agents from the role on every request. Forged, foreign or malformed tokens get the opaque `404`; an expired token, a revoked subject, a revoked key or a removed role gets `401 token_expired` with `WWW-Authenticate`. Tokens carry only `agents:read`, `sessions:own` and `vaults:own`; they may not set session `info`, send `message.manifest` or store OAuth refresh credentials, and `GET /v1/agents` shows them `{ agentId, name, description }` of their role's agents only.
+  - **Access policy.** `GET`/`PUT /v1/access/policy`: roles with token scopes, an agent allowlist and limits (`turnsPerHour`, `concurrentTurns`, answered with `429 limit_exceeded` and `Retry-After`). Without roles nothing is minted.
+  - **Signing keys.** Per Tenant, the private key sealed with the vault KEK: `GET /v1/access/signing-keys`, `POST …/rotate` (refused while the previous key may still verify live tokens; `force` for incidents), `POST …/:kid/revoke`, `GET /v1/access/jwks`. A Tenant with signing keys and no KEK is quarantined `kek-missing`.
+  - **Revocation.** `POST /v1/access/revocations` ends a subject's tokens; their open event streams end with `event: nylorun.closed` on every process. A stream opened with a token also ends when the token expires.
+  - Postgres migration 3 adds `signing_keys`, `subject_epochs`, `subject_usage` and an index on the session owner and status. New error codes `token_expired` and `limit_exceeded`.
+  - **Agents SDK.** `client.tokens.create()`, `client.access.getPolicy()`/`putPolicy()`/`revokeSubject()`/`jwks()` and `client.access.signingKeys.list()`/`rotate()`/`revoke()`, each checking the Host feature first.
+  - **CLI.** `nylo access policy get|set|init`, `nylo access signing-keys list|rotate|revoke`, `nylo access revoke <subject>` and `nylo access token` for trying the API.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [c7614a4]
+- Updated dependencies [679c488]
+- Updated dependencies [c85cd9e]
+- Updated dependencies [4282d5f]
+- Updated dependencies [82d95ef]
+- Updated dependencies [f48f12f]
+- Updated dependencies [50d0fb5]
+- Updated dependencies [50d0fb5]
+- Updated dependencies [c121144]
+- Updated dependencies [6ab4c59]
+- Updated dependencies [6ab4c59]
+- Updated dependencies [2ab8ed1]
+- Updated dependencies [c121144]
+- Updated dependencies [9546ac7]
+- Updated dependencies [9546ac7]
+- Updated dependencies [9d52189]
+- Updated dependencies [50d0fb5]
+- Updated dependencies [18468d9]
+  - @nylorun/core@0.9.0-beta
+
 ## 0.9.0-beta
 
 ### Minor Changes

package/README.md

@@ -1,44 +1,59 @@
 # @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" })
@@ -67,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
@@ -121,28 +139,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 +179,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 +259,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 +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";
@@ -305,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.
@@ -325,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).
@@ -336,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)
 
@@ -370,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`.