@nylorun/agents 0.13.0-beta → 0.16.0-beta

package/README.md

@@ -1,49 +1,85 @@
 # @nylorun/agents
 
-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
+Runtime API client package: definition authoring and a session client. The Tenant's
+settings, models, vaults, signing keys and application keys are the Management
+API's, through [`@nylorun/admin`](../admin/README.md). 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): an Action endpoint
+## Application entry: save your agents
 
 ```ts
 // src/main.ts
-import { createServer } from "node:http";
-import { createActionHandler } from "@nylorun/agents";
+import { createClient } from "@nylorun/agents";
 import { agents } from "../agents/index.js";
 
-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 });
+const client = createClient();
+for (const agent of agents) await client.saveAgent(agent);
 ```
 
-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 a local Tenant
-(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`.
+The Runtime runs each agent from its manifest and the files saved with it (skills), and
+never calls your code during a session. Your services are reached as tools: [HTTP
+tools](#http-tools) and remote MCP servers. `saveAgent` refuses, before sending anything, an
+agent with a tool that would run your code (`tool({ run })`) or a flow agent with a tool
+stage: make it an `http()` tool or serve it from a remote MCP server. `tool({ run })` still
+runs in the local engine (`@nylorun/harness/run`). `implementationVersion` defaults to
+`NYLORUN_IMPLEMENTATION_VERSION`, else `dev`.
+
+`createClient()` finds the Runtime through the two `NYLORUN_*` variables or the Project link
+that `npx nylorun start` writes; with neither, it fails with `connection_missing` and names
+those steps. Action endpoints (`createActionHandler`), and before them `connectAgents` and
+executors, were removed; see [MIGRATION.md](../MIGRATION.md#action-endpoints-are-removed).
+
+## HTTP tools
+
+A tool can be one HTTP request to your service, made by the Runtime itself: no code of
+yours runs during the session.
+
+```ts
+import { Agent, http } from "@nylorun/agents";
+import { z } from "zod";
+
+const refundOrder = http({
+  name: "refund_order",
+  description: "Refund an order.",
+  input: z.object({ orderId: z.string(), amount: z.number() }), // or a JSON Schema object
+  output: z.object({ refundId: z.string() }), // optional
+  url: "https://billing.example.com/refunds",
+  method: "POST", // default; or PUT, PATCH
+  credential: "billing", // optional: a vault credential bound to this URL
+  timeoutMs: 20_000, // default 60000, at most 300000
+  approval: "always", // optional: each call waits for session.approve()
+});
+
+export const support = Agent({ id: "support" }).tools(refundOrder);
+```
+
+The tool goes into the manifest as `http` (and `approval`), and the Runtime's
+Tool Gate sends the model's input as the JSON body, under the Host's address
+policy (`NYLORUN_ENDPOINT_*`), with `content-type: application/json`,
+`Nylorun-Session-Id`, `Nylorun-Turn-Id`, `Nylorun-Agent-Id` and an
+`Idempotency-Key` that is the same when the Runtime re-sends the call after a
+restart, so your service can drop duplicates. A `2xx` JSON answer is the output
+(text when it is not JSON and the tool has no `output`), checked against
+`output`. Any other status (with the start of its body), a timeout, a refused
+address or a mismatched output is a tool error the model sees. A call whose
+answer was lost with the gateway is `uncertain` and never sent again.
+
+`credential` works as for a remote MCP server: the session's attached vaults
+must hold a credential bound to the tool's exact URL (a `credentialSelections`
+entry whose `serverName` is the `credential` picks one when several are), else
+the operator's credential resolver is asked; without one the call fails before
+it is sent. `approval: "always"` pauses the turn for `session.approve()`; a
+denied call never runs and the model sees the denial. A remote MCP server takes
+`approval: "always"` too, for every one of its tools:
+`.mcp({ shop: { type: "streamable-http", url, approval: "always" } })`.
+An HTTP tool is also a flow stage (see [Flow agents](#flow-agents)), and runs
+only on the Runtime (a local `run()` reports `http.runtime-only`).
 
 ## Connection resolution
 
-`resolveConnection` / `createClient()` / `createActionHandler({ agents })`:
+`resolveConnection` / `createClient()`:
 
 1. Explicit `{ url, key }`
 2. Environment — if `NYLORUN_RUNTIME_URL` or `NYLORUN_SERVER_KEY` is set, both
@@ -59,22 +95,20 @@ Runtime serves one Tenant, so nothing names it: the `tenant` option is gone
 is ignored.
 
 ```ts
-import { Agent, createActionHandler, createClient, tool } from "@nylorun/agents";
+import { Agent, createClient, http } from "@nylorun/agents";
 import { z } from "zod";
 
 const assistant = Agent({ id: "assistant", name: "Assistant" })
   .instructions("Use the available tools.")
   .tools(
-    tool({
+    http({
       name: "lookup",
       input: z.object({ id: z.string() }),
-      async run({ id }, ctx) {
-        return { id, owner: ctx.info };
-      },
+      url: "https://items.example.com/lookup",
     }),
   );
 
-// Explicit Tenant API client (options or env / link via createClient()).
+// Explicit Runtime API client (options or env / link via createClient()).
 const client = createClient({
   url: process.env.NYLORUN_RUNTIME_URL,
   key: process.env.NYLORUN_SERVER_KEY,
@@ -86,20 +120,6 @@ const session = await client.createSession({
 });
 await session.input("Look up item 123", { idempotencyKey: requestId });
 const history = await session.history();
-
-// 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! },
-  url: "https://app.example.com/nylorun/actions",
-  onError: console.error,
-});
-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
@@ -125,7 +145,9 @@ const assistant = Agent({ id: "assistant", name: "Order assistant" })
   .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.
+Each subdirectory under the catalog must contain a `SKILL.md` with YAML frontmatter (`name`, `description`) per [Agent Skills](https://agentskills.io/home). Every file of a skill's folder, binary included (not `.git/`, `node_modules/`, OS files like `.DS_Store`, or `.env` and `.env.*` files, which hold secrets), is part of the definition: the manifest names each one by path and SHA-256 (`skills.<name>.files`), at most 500 files of 10 MiB each. `saveAgent` uploads the files the Runtime does not hold (`client.files`, `PUT /v1/files/sha256:<hex>`) before it puts the definition, which the Runtime refuses while it names a file it lacks (`400 definition_files_missing`).
+
+The Runtime serves the skills itself, with no call to your process: `load_skill` returns a skill's `SKILL.md` body and the paths of its other files, and `read_skill_resource` returns a text file. A session with a sandbox also has each skill's files read-only under `/skills/<name>/`, so the model can run a skill's scripts with `bash`. Run without a Runtime, the skill tools only say so.
 
 Declare MCP servers with `.mcp(...)` (same map shape as agent-plugins `mcpServers`):
 
@@ -139,7 +161,7 @@ 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)`.
+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. Nylorun accepts remote servers only: `streamable-http` and `sse` ([Agent Plugins MCP servers](https://agent-plugins.org/plugin-authors/mcp-servers)); a `stdio` server is refused, so run it behind an HTTP transport and declare its URL. Attach an Agent Plugin package with `.plugin(path)`: its skills and remote MCP servers join the agent, and a stdio server in its `mcp.json` throws.
 
 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:
 
@@ -154,7 +176,7 @@ const session = await client.createSession({
 });
 ```
 
-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 model gets `bash`, `read`, `write`, `edit`, `grep` and `glob` on a persistent `/workspace`. These tools run in the Runtime, not in your process. 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`.
 
 `sandbox` takes `false` for none, `{ id }` to attach a sandbox resource (below), or an inline sandbox as above; omit it for the Tenant's default. `{ session }`, sharing another session's sandbox, still works and is deprecated. 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.
 
@@ -171,7 +193,7 @@ await client.sandboxes.ensure("team-a/proj-42", { labels: { project: "acme" } })
 await client.createSession({ agentId: "analyst", ownerUserId, sandbox: { id: "team-a/proj-42" } });
 ```
 
-Sessions attached to one sandbox share its `/workspace`, and one turn runs in it at a time: a second session's turn is refused with `409 sandbox_busy` until the first ends. Deleting a session only detaches it. A spec is fixed once the sandbox exists; `labels` can change. `client.sandboxes.list({ labels })`, `get(id)` and `delete(id)` manage them, and `npx nylorun sandbox ls | rm` does the same on a local Tenant. A subject token reaches only the sandboxes it is minted for, checked at every turn start: `client.tokens.create({ subject, role, sandboxes: ["team-a/*", "user-42"] })` takes exact ids or prefixes ending in `/*`. Creating and deleting through a subject token needs a role with `sandboxes:write`. The Tenant holds at most `limits.sandboxes` of them (`PUT /v1/tenant/sandbox`, default 100).
+Sessions attached to one sandbox share its `/workspace`, and one turn runs in it at a time: a second session's turn is refused with `409 sandbox_busy` until the first ends. Deleting a session only detaches it. A spec is fixed once the sandbox exists; `labels` can change. `client.sandboxes.list({ labels })`, `get(id)` and `delete(id)` manage them, and `npx nylorun sandbox ls | rm` does the same on a local Tenant. A trusted issuer's token reaches only the sandboxes its issuer grants (the identity file's `sandboxes` templates, exact ids or prefixes ending in `/*`), checked at every turn start; creating and deleting through one needs `sandboxes:write`. The Tenant holds at most `limits.sandboxes` of them (`PUT /v1/tenant/sandbox`, default 100).
 
 Add an agent with `.subagents()` to let the model delegate to it:
 
@@ -196,35 +218,46 @@ 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 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).
+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, skills and MCP servers, saved with the parent, 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 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.
+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. 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.
+Delegate when the parent should keep the answer. When a specialist should own the rest of the conversation, send the next message with a turn manifest that has the specialist's instructions 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.
 
 ## 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.
+An agent's body is either a ReAct loop (the model decides) or a flow (its manifest
+decides). A flow agent is built from stages 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 v3
+(`kind: "workflow"`, `workflowSchemaVersion: 3`) 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.
+
+A flow runs no code of yours: the first stage gets the flow's input, and every later stage
+gets the previous stage's output. So each agent returns, through its `.output()` schema,
+what the next stage needs.
 
 ```ts
-import { Agent, tool } from "@nylorun/agents";
+import { Agent, VerdictSchema, tool } from "@nylorun/agents";
 import { z } from "zod";
 
 const planner = Agent({ id: "planner" })
-  .instructions("Return { tasks: string[] }.")
-  .output(z.object({ tasks: z.array(z.string()) }));
+  .instructions("Return { items: string[] }, one task each.")
+  .output(z.object({ items: z.array(z.string()) }));
 
 const coder = Agent({ id: "coder" })
   .instructions("Implement one task. Return { summary }.")
   .output(z.object({ summary: z.string() }));
 
+const reviewer = Agent({ id: "reviewer" })
+  .instructions("Pass the response when its summary says what changed.")
+  .output(VerdictSchema);
+
+const prWriter = Agent({ id: "pr-writer" })
+  .instructions("Return the summaries you are given as { summaries }.")
+  .output(z.object({ summaries: z.array(z.string()) }));
+
 const openPr = tool({
   name: "open-pr",
   input: z.object({ summaries: z.array(z.string()) }),
@@ -235,52 +268,88 @@ const openPr = tool({
 });
 
 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,
-    }),
-    { id: "implement", input: ({ input }) => input.tasks },
-  )
-  .step(openPr, { input: ({ input }) => ({ summaries: input.map((item) => item.summary) }) });
+  .pipe(planner)
+  .map(Agent({ id: "code" }).loop(coder, { verify: reviewer, max: 2 }), { id: "implement" })
+  .pipe(prWriter, openPr);
 
 export const agents = [shipFeature];
 ```
 
 | Stage | Role |
 | --- | --- |
-| **`.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 |
+| **`.pipe(a, b, …)`** | Run agents, tools or `flow()`s in order; each one's output is the next one's input |
+| **`.switch({ ...cases, default? })`** | Run the case the previous output names: a string, or its `route` field |
 | **`.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` |
+| **`.map(each)`** | Run `each` once per item of the previous output: an array, or its `items`; output is an array |
+| **`.loop(body, { verify, max })`** | Run `body`, ask `verify` (an agent, or `http({ url })`), run again with its feedback until it passes, at most `max` times |
+
+Every stage takes `{ id }` to name it (`.loop` takes it beside `verify` and `max`).
+`flow()` builds a sequence with no id for a case, branch, map item or loop body that
+is more than one step. A verifier agent gets `{ task, response, iteration }` and returns
+a verdict, `{ pass, feedback? }` (`VerdictSchema`), with feedback when it fails; the
+verdict is recorded as a `loop.verified` event. An agent after the first stage also
+sees the flow's input, as the original request, before its own input. Types flow from
+each stage's `.output()` schema to the flow agent's output. `.step(x, { id })` is a
+deprecated alias for `.pipe(x.withId(id))`.
+
+An [HTTP tool](#http-tools) is a stage too: in `.pipe()`, a case, a Map item or a Loop
+body. Its input is the previous output, which must match the tool's `input` (an
+object); a mismatch the build can see, such as an agent with no `.output()` before it,
+is refused (`flow.input-mismatch`), and any other fails the stage when it runs
+(`tool.invalid-input`). The Runtime makes the request as for an agent's HTTP tool, with
+`Nylorun-Agent-Id` set to the flow agent's id and `credential` taken from the flow
+session's vaults; its answer is the next stage's input. A failure status, a timeout or
+an answer that does not match `output` fails the stage with its code (`http.status`,
+`http.timeout`, `tool.invalid-output`, …). A Loop body that starts with an HTTP stage
+is retried with the Loop's input, not the feedback. `approval: "always"` is not
+supported on a flow stage yet (`flow.approval-unsupported`).
+
+A Loop may be judged by your service instead of an agent: `http({ url, method?,
+credential?, timeoutMs? })`, with no name or input, is an HTTP verifier. The Runtime
+sends `{ input, output, iteration }` (the Loop's input, the attempt's output, its
+number) and reads a verdict, `{ pass, feedback? }`, from the answer; anything else, or a
+failed request, fails the Loop (`loop.verify-failed`). Its verdicts are recorded as
+`loop.verified`, as an agent's are.
 
-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`.
+```ts
+import { Agent, http } from "@nylorun/agents";
+import { z } from "zod";
+
+const order = Agent({ id: "order" })
+  .instructions("Name the order to refund as { orderId }.")
+  .output(z.object({ orderId: z.string() }));
+
+const refund = http({
+  name: "refund",
+  input: z.object({ orderId: z.string() }),
+  output: z.object({ refundId: z.string() }),
+  url: "https://billing.example.com/refunds",
+  credential: "billing",
+});
+
+const fixer = Agent({ id: "fixer" }).instructions("Fix the failing test.");
+
+export const refunds = Agent({ id: "refunds" }).pipe(order, refund);
+export const fixTests = Agent({ id: "fix-tests" }).loop(fixer, {
+  verify: http({ url: "https://ci.example.com/verify", credential: "ci" }),
+  max: 3,
+});
+```
 
 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.
+named by the agent: its id (or `.withId("…")`), 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 `writer.withId("final-writer")`
+(`flow.duplicate-leaf`). A code tool stage (`.pipe(tool({ run }))`) runs only in the local
+engine: the Runtime runs no code of yours, so `saveAgent` refuses a flow agent with one. Use
+an HTTP stage instead.
 
 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 other sessions by opening them all on one sandbox resource
+`createSession({ …, sandbox: { … } })`, and every agent in the flow uses it. Share it
+with other sessions by opening them all on one sandbox resource
 (`sandbox: { id }`, see `client.sandboxes`), and call
-built-ins via `session.sandbox` (application) or `ctx.sandbox` (a tool).
+built-ins via `session.sandbox` (application).
 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:
@@ -293,15 +362,15 @@ 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`. `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
+then `dev`. Agents do not hash the manifest; the Runtime pins the digest of the
+definition a session opens with. Model selection and model credentials belong to
 the Tenant.
 
-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 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`.
+The Runtime makes a lost HTTP tool call `uncertain` instead of repeating its external effect.
+In the local engine (`@nylorun/harness/run`), `tool({ run })` tools receive state, info,
+identity, resume, signal, approval/response helpers and memoized `step`. Arbitrary middleware
+closures are rejected for durable definitions. Agent definitions have no `.run()`; explicit
+local execution is available through `@nylorun/harness/run`.
 
 ## AG-UI
 
@@ -313,9 +382,10 @@ 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.
+- **From the page itself**, with `@ag-ui/client`'s `HttpAgent` and a `fetch`
+  that sends your identity provider's 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.
@@ -362,8 +432,7 @@ created, on its first run; later runs keep them. Whatever the browser sends in
 - A busy or paused thread ends the run with `RUN_ERROR` code `session_busy`.
 - The handler calls the Runtime as each person (`client.as(subject, { scopes })`,
   below), so the Runtime itself keeps one person out of another's threads.
-  `scopes` defaults to `["sessions:own"]`; add `"vaults:own"` when `session()`
-  attaches the person's vaults. A `subject` the Runtime cannot name (see below)
+  `scopes` defaults to `["sessions:own"]`. A `subject` the Runtime cannot name (see below)
   answers `500` (`subject_invalid`).
 - 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
@@ -376,8 +445,8 @@ 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. A browser reaches the Runtime only with a subject token and a
-publishable key, never with a Tenant key.
+regenerated. A browser reaches the Runtime only with a trusted issuer's token,
+never with a key.
 
 ## A2A
 
@@ -467,7 +536,7 @@ made as an artifact of the session; each new artifact or version appears in the
 session's events as `artifact.created` or `artifact.version.created`. The Tenant's
 limits (`PUT /v1/tenant/artifacts`: 100 MiB per file and 10 GiB in all by default)
 refuse a larger upload with `413 limit_exceeded`, and nothing is stored. Acting for
-a person (`as()`, a subject token), a client reaches only the artifacts of that
+a person (`as()`, or a trusted issuer's token), a client reaches only the artifacts of that
 person's sessions, and an upload names one of them.
 
 ### Outputs: folder artifacts
@@ -495,155 +564,69 @@ completes.
 ## Acting for a person (app servers)
 
 A server that signs people in and calls the Runtime for them (an "app server")
-keeps the Tenant key to itself and names the person on each call:
+keeps its application key to itself and names the person on each call:
 
 ```ts
 import { createClient } from "@nylorun/agents";
 
-const app = createClient(); // the Tenant key, on the server only
+const app = createClient(); // the application key, on the server only
 
 // Per request, after your own sign-in:
-const person = app.as(`app:${user.id}`, { scopes: ["sessions:own", "vaults:own"] });
+const person = app.as(`app:${user.id}`, { scopes: ["sessions:own"] });
 await person.createSession({ agentId: "support", ownerUserId: `app:${user.id}` });
 await person.listSessions(); // only this person's sessions
 ```
 
 `as()` sends `Nylorun-Subject` and `Nylorun-Scopes` on every call, event
 streams included, and the Runtime (optional feature `subject-headers`)
-enforces both: another person's sessions and vaults answer the same `404` as
-missing ones, and a route outside the scopes answers `403` (`scope_required`).
+enforces both: another person's sessions answer the same `404` as missing
+ones, and a route outside the scopes answers `403` (`scope_required`).
 Nothing is minted, cached or refreshed, and the copy shares the client's
 compatibility check, so calling `as()` per request is cheap.
 
 | Scope | Allows |
 | --- | --- |
 | `sessions:own` | The person's own sessions: create, list, read, stream, message, approve, respond, cancel; and their artifacts |
-| `vaults:own` | The person's own vaults and credentials |
 | `agents:read` | Listing the Tenant's agents |
-| `agents:write` | Saving agents; listing agents, models and providers |
-| `tenant:settings` | The Tenant's status, model provider and sandbox settings |
-
-No scope reaches Tenant reset, config seed, Action endpoints, actions or the sandbox
-tool routes; call those without `as()`. A subject is 1–200 visible ASCII
+| `agents:write` | Saving agents; listing agents |
+
+No scope reaches the sandbox tool routes; call them without `as()`. `tenant:settings` is retired (protocol 8): it grants
+nothing, and no subject reaches the Management API (`/v1/tenant/*`). Vaults are
+the installation's, created through the Management API with a management key
+(`admin.vaults.create({ scope: "installation", … })` in
+[`@nylorun/admin`](../admin/README.md)); a session attaches them with
+`vaultIds`, and a person's own credentials come from your credential resolver
+([DEPLOYMENT.md](../DEPLOYMENT.md#credentials)). 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.
 
-## 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,
-});
-```
+The Tenant's signing keys sign capability links and run tokens.
+`app.access.jwks()` reads the public keys (`GET /v1/access/jwks`, no key
+needed). Listing, rotating
+and revoking them is management: `admin.signingKeys.list()`, `.rotate()`
+(`{ force: true }` for incidents) and `.revoke(kid)` in `@nylorun/admin`, or
+`nylo access signing-keys …` from the terminal.
 
 ## 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`.
+A web page or an app calls the Runtime directly with the JWT your identity
+provider gave the person: list the provider in the Runtime's identity file
+([Trusted issuers](../DEPLOYMENT.md#trusted-issuers)), and the Runtime takes the
+token's subject, scopes, agents and sandbox grants from it. Nylorun mints no
+token and ships no browser client: use your provider's SDK for sign-in and send
+the token as `Authorization: Bearer <token>` with `Nylorun-Protocol`, through a
+reverse proxy that answers CORS (the Runtime sends no CORS headers). An expired
+token answers `401` with `code: "token_expired"`; `GET /v1/me` shows what a token
+renders to. For a chat UI, give `@ag-ui/client`'s `HttpAgent` a `fetch` that adds
+those headers.
 
-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).
+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` or `/a2a` 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
+shows it in an iframe. It exports the message schema
 (`StudioEmbedMessageSchema`, envelope `{ type: "nylorun.studio", protocol, kind }`),
 the login-token and session schemas, `STUDIO_EMBED_PROTOCOLS` and
 `parseFrameAncestors`.
@@ -662,4 +645,6 @@ window.addEventListener("message", (event) => {
 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`.
+`NYLORUN_STUDIO_FRAME_ANCESTORS`, empty by default: list your app's origins with
+`nylorun start --studio-embed-origin <origin>`. The message `open.session`
+(`{ sessionId }`) asks the embedding app to open that session in its own UI.