@nylorun/agents 0.14.0-beta → 0.16.0-beta

package/CHANGELOG.md

@@ -1,5 +1,117 @@
 # @nylorun/agents
 
+## 0.16.0-beta
+
+### Major Changes
+
+- 4bd2a0b: **Flows run no code: workflow manifest v3 (manifest-only agents, step M2).** A flow agent is data: each stage gets the previous stage's output, a switch reads it, a map runs over it and a loop asks a verifier agent. See MIGRATION.md for what replaces each function.
+
+  - **Breaking (`@nylorun/core`, `@nylorun/agents`):** stage `input` functions, `switch` `on`, loop `verify` functions and `decide` are removed; a builder option that names one is refused with what replaces it. `.loop()` takes a verifier agent and a required `max`. New `.pipe(...children)` adds one stage per child; `.step()` is a deprecated alias (`NYLORUN_DEP_STEP`). `Chain`, `Switch`, `Parallel`, `Map`, `Loop`, `withInstructions`, `withoutTools`, `isSlot`, `functionKey` and the `StageArgs`, `LoopVerifyFn`, `LoopDecideArgs`, `LoopChoice` and v1 workflow types are removed. `Agent.from` for a flow takes tool nodes only.
+  - **Breaking (`@nylorun/core`):** workflow manifests are `workflowSchemaVersion: 3`; no node carries `input`, a switch has no `on`, a loop's `verify` is an agent and `max` is required. A v1 or v2 manifest is refused with a message naming the change. The `fn` and `verify` Actions and effect kinds, and the `loop.decided` event, are removed. `WorkflowManifestV2` / `WorkflowNodeV2` / `isWorkflowManifestV2` are now `WorkflowManifest` / `WorkflowNode` / `isWorkflowManifest`.
+  - **Breaking (`@nylorun/harness`):** the flow engine is `flow-3` and runs only v3 manifests; v1 and v2 engines, `agentTurnValue` and the `fn` / `verify` effect kinds are removed. A switch picks the case named by the previous output or its `route` field, a map runs over an array or an `items` array, and a loop retries with its verifier's feedback until `max`. An `agent` effect carries the flow's input as `flowInput` when the stage's input differs.
+  - **Breaking (`@nylorun/runtime`):** no `fn` or `verify` Actions are offered or delivered. An agent stage's message shows the flow's input as the original request before its own input, and each verifier verdict is recorded as `loop.verified`.
+  - `@nylorun/studio`: the workflow tree draws v3 manifests (a loop shows its verifier agent and `max`); the loop timeline drops decide outcomes, and `loop.verified` shows the feedback.
+
+- 713e676: **Remote MCP servers only (blueprint D47).** Nylorun accepts `streamable-http` and `sse` MCP servers, declared by URL and reached through the gates; stdio servers and plugin roots are gone. See MIGRATION.md.
+
+  - **Breaking (`@nylorun/core`):** `McpServerManifest` and the manifest schema keep only `streamable-http` and `sse`. A `stdio` server is refused by `.mcp({...})` (`McpError`, code `mcp.stdio`), by `Agent.from` and by the wire schema, all with one message (`stdioMcpRefusal`): "MCP server 'x' uses stdio; Nylorun accepts remote MCP servers only (streamable-http or sse). Run the server behind an HTTP transport and declare its URL." `PutAgentRequest` loses `pluginRoots`, `CapabilityDeclaration` loses `pluginRoot`, and the Harness API's `RunRouting` loses `pluginRoots`.
+  - **Breaking (`@nylorun/agents`):** `.plugin()` and `plugin()` throw `PluginError` (code `plugin.mcp-stdio`) for a stdio server in a plugin's `mcp.json`; its remote servers and skills load as before. `saveAgent` no longer sends plugin roots. `prepareStdioLaunch`, `expandPluginPlaceholders` and `StdioLaunch` are removed.
+  - **Breaking (`@nylorun/runtime`):** no stdio MCP launcher: `PUT /v1/agents/:id` refuses a stdio server (`400`) and `pluginRoots`. `TenantConfig.childEnv`, `TenantPaths.pluginData` and `tmp`, `tenantChildEnvironment`, `startEphemeralRuntime({ baseline })` and `configForFactory`'s `baseline` and `hostConfig` are removed; the harness service no longer takes `childEnv` or `paths.pluginData`.
+  - `nylorun`: the local stack no longer mounts the Host root's `plugins/` into the runtime and harness containers, nor the Tenant's `plugin-data/`, `home/` and `tmp/` into the harness, which now mounts only `sandboxes/`.
+
+- c135267: **Action endpoints are removed (manifest-only agents, M6).** The Runtime runs no code of yours during a session: an agent's tools are HTTP tools, remote MCP servers, agents used as tools and the Runtime's built-ins. Protocol stays 8; the `action-endpoints` feature is gone, so a client that requires it is refused. See MIGRATION.md, "Action endpoints are removed".
+
+  - **Breaking (`@nylorun/core`):** the `Action`, endpoint (`PutEndpointsRequest`, `Endpoint`, `EndpointHealth`, …) and delivery schemas, `SIGNATURE_HEADER`, `OUTCOME_HEADER`, `DELIVERY_TOKEN_TYPE` and the `action.*` events (`action.pending`, `.delivered`, `.delivery_failed`, `.completed`, `.uncertain`) are removed, and `ToolDefinition.background` with them. `ActionOutcome` is renamed `EffectOutcome`. Tenant status loses `checks.endpoints`, `agents[].registered` and `agents[].endpoint`, and `counts.pendingActions`; the session view loses `actions`. A `turn.paused` interaction carries the tool call's `callId`. New `codeToolsOf` and `codeToolRefusal` name a definition's tools that would run your code. The Harness API is v2 (`HARNESS_API_VERSION = 2`): `TurnStart.options.holdMs` and `effect.resolved` are removed.
+  - **Breaking (`@nylorun/harness`):** held runs are gone: `createHarness` loses `holdMs`, and `apiHost` its `hold` option.
+  - **Breaking (`@nylorun/agents`):** `createActionHandler`, `executeAction`, `createActionSandbox`, `definitionDeclaresSandbox`, `isActionSandboxTool` and the `Action`, `ActionOutcome`, `ActionHandler`, `ActionHandlerOptions`, `RegisterOptions`, `ExecuteActionOptions` and `ExecutableDefinition` types are removed. `saveAgent` refuses a code tool (`tool({ run })`) or a flow tool stage before sending; its `implementationVersion` is optional (`NYLORUN_IMPLEMENTATION_VERSION`, else `dev`).
+  - **Breaking (`@nylorun/runtime`):** `/v1/endpoints` and `/v1/actions/*` answer `404`; delivery tokens, the deliverer, background tools, held runs (`TenantConfig.actionHoldMs`), `DurableExecution.deliver`, the Restate `NylorunAction` object, the `action_result` wake and the gates service's `/nylorun/v1/deliveries` are removed, and a migration drops the `actions` and `endpoints` tables. `PUT /v1/agents/:id` refuses a definition with a code tool or a flow tool stage (`400`); a tool the Runtime cannot run fails with `tool.unavailable`. The fixture model answers in text when the agent offers no `lookup_order` tool.
+  - **Breaking (`@nylorun/cli`):** `nylo endpoints` is removed (a usage error that says why); `nylo status` shows uncertain effects instead of pending Actions.
+  - **Breaking (`@nylorun/create-agent`):** the starter saves its agent with `saveAgent` and runs no server: no Action endpoint, `PORT` or `NYLORUN_ACTIONS_URL`. Its assistant has no tools, with a commented `http()` tool to start from.
+  - `nylorun`: the local stack's comments speak of MCP servers and HTTP tools on this machine, not Action endpoints.
+  - `@nylorun/studio`: the `action.*` event views and delivery status are removed; the chat shows `tool.completed`, and the Agent Manifest tab lists tools without a target as code tools.
+
+- d36f0d9: **Hooks are removed; manifests are v5 (manifest-only agents, step M1).** The Runtime no longer calls the developer's code before or after a turn or a model call. See MIGRATION.md for what replaces each use.
+
+  - **Breaking (`@nylorun/core`, `@nylorun/agents`):** `.beforeTurn()`, `.beforeModel()`, `.afterModel()`, `.afterTurn()`, the deprecated `.before()` / `.after()`, a capability's `before` / `after`, and the `Patch`, `Decision`, `TurnDecision`, `BeforeHook`, `AfterHook`, `HookScope` types and `runHookPoint` / `hooksFrom` helpers are removed. A capability that still passes `before` or `after` is refused with `hooks were removed: …`.
+  - **Breaking (`@nylorun/core`):** `manifestSchemaVersion` is 5. `capabilities[].hooks` is gone; a manifest that names it, or a v3/v4 manifest, is refused with a message naming the change. The `hook` Action and the `hook` effect kind of the Harness API are removed.
+  - **Breaking (`@nylorun/harness`):** the turn loop runs no hooks; the turn state a checkpoint carries is `{ turnId }`, and the engine version is `hosted-4`, so checkpoints of earlier engines are refused.
+  - `@nylorun/runtime`: no `hook` Actions are offered or delivered.
+  - `@nylorun/studio`: the Agent Manifest tab drops the Hooks count and the turn lifecycle.
+
+- 107b07d: **Skills are files the Runtime holds and serves itself (track R2 M4).** Breaking: a skill's manifest names every file of its folder, and the skill tools no longer run in the developer's process. The protocol stays at 8 until the track ships.
+
+  - `@nylorun/core`: `SkillManifest` gains `files`, each path of the skill's folder (`SKILL.md` required, `/`-separated, no `..`, at most 500 files) mapped to `sha256:<hex>`, so the manifest hash pins them. `skillRecords` and `SkillRecord` are gone; a declaration's `skillFiles` holds the bytes to upload (`SkillFileSource`). `load_skill` and `read_skill_resource` keep their names and input schemas but fail with `skills.runtime-only` outside a Runtime. New `DefinitionFileViewSchema`, error code `definition_files_missing`, Harness API request `definition.file`, and `definitionFilesOf`, `isSkillTool` and the definition-file limits. A top-level `functions` key is reserved and refused ("Functions are not available yet").
+  - `@nylorun/runtime`: `PUT /v1/files/sha256:<hex>` stores a definition file (application key; at most 10 MiB; a body of another hash is `400`; `201` stored, `200` held already) in the Object store at `definitions/sha256/<hex>`, and `HEAD` says whether the Tenant holds one. New tables `definition_files` and `definition_file_uses` (migration `0013_definition_files`). `PUT /v1/agents/{id}` refuses a definition, nested agents and flow agents included, that names a file the Tenant lacks (`400 definition_files_missing`). Core serves `load_skill` (the `SKILL.md` body, the other files' paths, and `sandboxPath` with a sandbox) and `read_skill_resource` (text files only) from those files, with no Action. A session's sandbox gets each skill's files read-only under `/skills/<name>/` before the first call that opens it, and the sandbox's instructions name them; pod sandboxes mount an `emptyDir` at `/skills`. Unused files are not deleted yet.
+  - `@nylorun/agents`: `.skills()`, `skills()` and `.plugin()` read every file of a skill's folder, binary included (not `.git/`, `node_modules/`, OS files or `.env` files), and hash it; a file over 10 MiB or more than 500 files fail the build. `saveAgent` uploads the files the Runtime lacks before the definition; `client.files` (`has`, `upload`, `ensure`) does it by hand.
+  - `@nylorun/harness`: tests only.
+  - `@nylorun/studio`: the agent's manifest lists each skill's files.
+
+### Minor Changes
+
+- a64aaca: **HTTP in flows (manifest-only agents, after M2 and M3).** An `http()` tool is a flow stage, and `http({ url })` is a Loop's HTTP verifier; the Runtime makes both requests through its Tool Gate, with no Action endpoint.
+
+  - `@nylorun/core`: an HTTP tool may be a stage in `.pipe()`, a switch case, a Map item or a Loop body; its tool node carries its `http` target and binds nothing. The build refuses an HTTP stage whose input is known to be the wrong type (`flow.input-mismatch`, e.g. after an agent with no `.output()`) and `approval: "always"` on one (`flow.approval-unsupported`). `http()` without a name and an input returns an `HttpTarget`, an HTTP verifier: `.loop(body, { verify: http({ url, method?, credential?, timeoutMs? }), max })`, in the manifest `loop.verify: { http }`. `fn` and `command` verify targets are refused ("Functions are not available yet"). New `flowHttpTarget()` finds an HTTP stage or verifier by stage key; `isHttpTarget()`, `WorkflowHttpVerify` and `WorkflowLoopVerify` are exported.
+  - `@nylorun/harness`: the flow engine checks an HTTP stage's input against its schema (`tool.invalid-input`), runs it as a `tool` effect and fails the stage on a failed outcome (`http.status`, `http.timeout`, `tool.invalid-output`, …). An HTTP verifier is a `tool` effect with `{ input, output, iteration }` and `context.role: "verify-http"`; a non-verdict or a failed request is `loop.verify-failed`. A Loop body that starts with an HTTP stage is retried with the Loop's input.
+  - `@nylorun/agents`: `http()` builds HTTP verifiers too.
+  - `@nylorun/runtime`: a flow's HTTP stages and verifiers are executed like an agent's HTTP tool: address policy, the flow session's vault credential, `Nylorun-Session-Id`/`-Turn-Id`/`-Agent-Id` (the flow agent's id) and the flow effect id as `Idempotency-Key`, run once at the gates service (`POST /nylorun/v1/http-calls` takes `tool: { sessionId?, stage }`) and `uncertain` when the answer is lost. An HTTP verifier's verdict is recorded as `loop.verified`.
+  - `@nylorun/studio`: the workflow tree shows HTTP stages and HTTP verifiers with their method and URL.
+
+- 40b7648: **HTTP tools and static approval (manifest-only agents, M3).** A tool can be one HTTP request the Runtime makes through its Tool Gate, with no Action endpoint; code tools keep working.
+
+  - `@nylorun/core`: `ToolManifest` gains `http` (`url`, `method` `POST`/`PUT`/`PATCH`, `credential`, `timeoutMs` up to 300000) and `approval` (`never`/`always`, HTTP tools only); a tool is never both an agent and an HTTP request, and `fn` and `command` are refused ("Functions are not available yet"). Remote MCP servers take `approval`. `http()` builds an HTTP tool, `httpToolOf()` reads one; `SESSION_ID_HEADER`, `TURN_ID_HEADER` and `AGENT_ID_HEADER` name the headers it sends. `Agent.from` rebuilds HTTP tools without an implementation; an HTTP tool is refused as a flow stage.
+  - `@nylorun/harness`: hosted HTTP tools keep their target, and `approval: "always"` (an HTTP tool's, or `DurableSessionTool.approval` for a remote MCP server's tools) pauses each call for approval. **Breaking:** `HarnessExecutors.recovers.remoteMcp` is renamed `recovers.tool`.
+  - `@nylorun/agents`: exports `http` and the identity header constants.
+  - `@nylorun/runtime`: the Tool Gate runs HTTP tool calls (`POST /nylorun/v1/http-calls` at the gates service, or in process): the input as JSON under the Host's address policy, the session's vault credential bound to the URL, `Nylorun-Session-Id`/`-Turn-Id`/`-Agent-Id` and the effect id as `Idempotency-Key`. A keyed call runs once (`tool_crossings`), so a re-send after a takeover joins it and one lost with the gateway is `uncertain`. Non-2xx answers, timeouts, refused addresses, missing credentials and output mismatches are tool errors the model sees. The credential resolver is asked with `target.kind: "http"` and the tool's `credential` name.
+  - `@nylorun/studio`: the Agent Manifest tab lists HTTP tools with their method and URL, and marks tools and MCP servers that wait for approval.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [4bd2a0b]
+- Updated dependencies [a64aaca]
+- Updated dependencies [40b7648]
+- Updated dependencies [713e676]
+- Updated dependencies [c135267]
+- Updated dependencies [d36f0d9]
+- Updated dependencies [107b07d]
+  - @nylorun/core@0.15.0-beta
+
+## 0.15.0-beta
+
+### Major Changes
+
+- 98b0d37: **Protocol 8: the Runtime API and the Management API take separate keys (Runtime and Management APIs, step A4).** Upgrade every package together; `nylorun`, `@nylorun/cli` and Studio already use management keys (A3).
+
+  - **Breaking (`@nylorun/runtime`): `/v1/tenant/*` takes only a management key.** An application key there, alone or acting for a subject, is `403 key_role_mismatch`; a management key acting for a subject is `403 subject_invalid`. This covers the Tenant's status, seed and reset, models, providers, usage and budgets, sandbox and artifact settings, application keys, vaults and signing keys. A management key on any other route but `/v1/me` and the public `/v1/access/jwks` is `403 key_role_mismatch`.
+  - **Breaking (`@nylorun/runtime`): vaults and signing keys moved.** They are at `/v1/tenant/vaults…` (including `…/oauth/start`) and `/v1/tenant/signing-keys…`; `/v1/vaults…` and `/v1/access/signing-keys…` are gone, with no alias. Opening a session with `vaultIds` is unchanged, as are `GET /v1/oauth/callback` and `GET /v1/access/jwks`.
+  - **Breaking (`@nylorun/core`, `@nylorun/runtime`): `tenant:settings` is retired.** It leaves `SUBJECT_SCOPES`; `Nylorun-Scopes` may still name it and it grants nothing. `/v1/tenant/models` and `/v1/tenant/providers` no longer admit `agents:write` subjects: apps don't read the model catalog.
+  - **Breaking (`@nylorun/agents`):** the vault methods (`createVault`, `listVaults`, `getVault`, `deleteVault`, `createCredential`, `listCredentials`, `getCredential`, `rotateCredential`, `deleteCredential`) and `client.access.signingKeys` / `SigningKeysClient` are removed; use `admin.vaults` and `admin.signingKeys` from `@nylorun/admin`'s `createManagementClient`. `client.access.jwks()` stays.
+  - `@nylorun/core`: `PROTOCOL_VERSION` is 8 and `HOST_PROTOCOL` 4–8, with the required feature `management-api`. Runtime API routes keep their request and response shapes.
+  - `@nylorun/runtime`: `startEphemeralRuntime` registers a management key (`managementKey`, the key `bootstrap`).
+
+### Minor Changes
+
+- c66d8ed: Add optional session reads and a resumable model-ledger export: pinned manifests, usage totals, model calls, and opt-in session/history/sandbox pages (Host feature `session-reads`), and `GET /v1/tenant/calls/model` on the Management API (Host feature `calls-export`). Usage and model calls take an application key acting as itself; the export takes a management key. Runtime reads use a separate bounded, read-only Drizzle pool. The additive migration `0012_session_reads` preserves unknown legacy creation times and usage quality; the export uses safe transaction order without skipping committed rows. `@nylorun/agents` adds `client.sessions.page()`, `session.manifest()`, `session.usage()`, `session.modelCalls()`, `session.history({ limit })` and `client.sandboxes.page()`; `@nylorun/admin` adds `models.exportCalls()`. Legacy unpaged responses are unchanged.
+
+### Patch Changes
+
+- b28bdd7: **Local MCP servers work on a local Tenant, and a server that does not connect shows.** Additive; the protocol stays at 7.
+
+  - `@nylorun/runtime`: remote MCP servers (`streamable-http`, `sse`) are reached under the Host's address policy, as Action endpoints are (`NYLORUN_ENDPOINT_*`, `tenant/outbound.ts`). In the local Docker stack `localhost`, `127.0.0.1` and `[::1]` now mean the machine that runs Docker (`host.docker.internal`), so `.mcp({ x: { type: "streamable-http", url: "http://localhost:3002/x" } })` connects where it used to fail with `fetch failed`. With `NYLORUN_ENDPOINT_PRIVATE=refuse` a server on a private address is refused; with `NYLORUN_ENDPOINT_HTTP=refuse` an `http` server is refused. Redirects are still not followed. A connection failure now names its cause (`connect ECONNREFUSED …`) instead of `fetch failed`. This applies in the gateway, a harness process and an in-process Tenant. `guardedFetch` takes `stream: true`: the answer streams, unbounded, with no timeout but the caller's signal.
+  - `@nylorun/core`: new session event `mcp.discovered`, recorded once on the session's first turn with the MCP snapshot: one entry per declared server with `outcome` (`connected`, `refused`, `failed`), `message` and the number of `tools` it added (`McpDiscoveredPayloadSchema`, `McpServerOutcomeSchema`). A server that does not connect adds no tools for the session's life; this is where that shows in the event log, beside `mcpDiagnostics`.
+  - `@nylorun/agents`: `.plugin()` and `plugin()` emit a process warning (`NylorunPluginWarning`, the diagnostic's code) for each part of the package they skip, so building or registering the agent says when a plugin's MCP server was dropped. The `plugin.mcp-server-skipped` message now says why: for example, plain `http` is accepted only for `localhost`, `127.0.0.1` or `[::1]`.
+  - `@nylorun/studio`: the event list labels `mcp.discovered` and summarizes each server's outcome.
+
+- Pin core to the tested release.
+- Updated dependencies [3b3bdc6]
+- Updated dependencies [6576e12]
+- Updated dependencies [b28bdd7]
+- Updated dependencies [cc107b1]
+- Updated dependencies [7f763c3]
+- Updated dependencies [98b0d37]
+- Updated dependencies [c66d8ed]
+  - @nylorun/core@0.14.0-beta
+
 ## 0.14.0-beta
 
 ### Major Changes

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.
 
@@ -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.
+
+```ts
+import { Agent, http } from "@nylorun/agents";
+import { z } from "zod";
 
-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`.
+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
 
@@ -377,7 +446,7 @@ 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 trusted issuer's token,
-never with a Tenant key.
+never with a key.
 
 ## A2A
 
@@ -495,12 +564,12 @@ 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"] });
@@ -519,22 +588,25 @@ compatibility check, so calling `as()` per request is cheap.
 | --- | --- |
 | `sessions:own` | The person's own sessions: create, list, read, stream, message, approve, respond, cancel; and their artifacts |
 | `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, vaults or
-the sandbox tool routes; call those without `as()`. Vaults are the
-installation's (`createVault({ scope: "installation", … })`); a person's own
-credentials come from your credential resolver
+| `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.
 
-The Tenant's signing keys sign delivery tokens and capability links:
-`app.access.signingKeys.list()`, `.rotate()` (`{ force: true }` for incidents),
-`.revoke(kid)` and `app.access.jwks()`, or `nylo access signing-keys …` from the
-terminal.
+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