@nylorun/runtime 0.17.0-beta → 0.19.1-beta

package/CHANGELOG.md

@@ -1,5 +1,160 @@
 # Changelog
 
+## 0.19.1-beta
+
+### Patch Changes
+
+- 4b499ee: **The Runtime API's reference lists the Service endpoints last.** The Runtime API's tag groups are now Agents, Sessions, Sandboxes, Artifacts and Service. Service holds what was the Runtime tag under Get started: `/health`, `/ready`, `/v1/me`, the JWKS and `/openapi/runtime.json`. Sandboxes and Artifacts are a group each. The document no longer lists the `/openapi.json` alias; the Runtime still serves it.
+
+## 0.19.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.
+- Pin harness 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]
+- Updated dependencies
+  - @nylorun/core@0.15.0-beta
+  - @nylorun/harness@0.23.0-beta
+
+## 0.18.0-beta
+
+### Major Changes
+
+- 7f763c3: **The Admin API and the operator listener are gone (Runtime and Management APIs, step A5).** Host work moves to the machine: `nylorun` runs `nylorun-operate` inside the runtime container, and every remote client uses the Runtime API or the Management API.
+
+  - **Breaking (`@nylorun/runtime`):** `/v1/admin/*` (status, host, shutdown, keys, openapi.json) is removed; it answers like any unknown route. The operator listener, `NYLORUN_ADMIN_LISTEN_PORT`, `NYLORUN_ADMIN_LISTEN_HOST`, `NYLORUN_ADMIN_ALLOWED_HOSTS` and `host.json`'s `adminPort` are gone, and so is the `admin-openapi.json` package file. Stop the Host with SIGTERM. `nylorun-operate status [--json]` reports the version, protocol and the Tenant's id, name, state and cause, exiting 2 when the Tenant is not open. `/ready` adds `harness: { mode, connected }` while the Tenant is open. `startEphemeralRuntime` loses `operatorListener` and `adminUrl`. The admin key stays: it derives Studio's key.
+  - **Breaking (`@nylorun/admin`):** `createAdmin()` is the Management API client (`tenant`, `keys`, `models`, `vaults`, `signingKeys`, `settings`) with a management key: explicit `{ url, key }`, else `NYLORUN_RUNTIME_URL` + `NYLORUN_MANAGEMENT_KEY`, else the Project link's or the local Host root's management key. `status()`, `adminUrl`, the Admin API keys, `NYLORUN_ADMIN_URL`/`NYLORUN_ADMIN_KEY` and `OPERATOR_KEYS_FEATURE` are removed; `deriveStudioToken` and `mintStudioLoginToken` stay.
+  - **Breaking (`@nylorun/core`):** `admin-status` leaves `PROTOCOL_FEATURES` (the Host still advertises it for protocol 5–7 clients) and `operator-keys` is removed; `AdminStatusSchema`, `AdminHostStatusSchema`, `HostAggregateSchema` and `HostShutdownResponseSchema` are removed.
+  - **Breaking (`nylorun`):** no admin port: `NYLORUN_ADMIN_PORT` is no longer written or published (an existing one is ignored). `nylorun start` waits for `/ready`, and `nylorun status` reads readiness from `/ready` and the Tenant from `nylorun-operate status`.
+  - `@nylorun/cli`: `nylo status` no longer falls back to the Admin API; when the Tenant does not answer it points to `npx nylorun status`.
+
+- 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
+
+- 3b3bdc6: **The clients use management keys (Runtime and Management APIs, step A3).** The protocol stays at 7; every client keeps working against a protocol 7 Runtime's routes.
+
+  - `nylorun`: `nylorun start` keeps an application key (`project`) and a management key (`project-management`) for a Project, in `<Host root>/project-credentials.json` and the Project's `.nylorun/credentials.json` (still format 1, with new `managementKey` and `managementPrincipalId` fields). A credentials file holding only an application key gains a management key at the next start. Commands outside a project keep `cli` and `cli-management`. Keys are issued through `nylorun-operate` in the runtime container instead of the Admin API, and `nylorun key put <id> --management` puts a management key. Seeding the Tenant and `nylorun mcp connect` use the management key (`/v1/tenant/vaults`). Studio reaches the Runtime's public listener.
+  - `@nylorun/cli`: `status`, `reset`, `configure`, `doctor` and `access signing-keys` use the Management API through `@nylorun/admin` with the Project's management key, or `NYLORUN_MANAGEMENT_KEY`.
+  - `@nylorun/studio`: local Studio needs no login. A request on the published loopback address (`localhost` or `127.0.0.1` at Studio's port) acts as signed in; hosts behind a sign-in proxy and embedding keep their login, and state-changing requests still need Studio's own `Origin`. Studio learns its Tenant from `GET /v1/tenant` with its key instead of the Admin API, and its Connections page manages vaults through `@nylorun/admin/client` at `/v1/tenant/vaults`.
+  - **Breaking (`@nylorun/admin`, `@nylorun/runtime`): Studio's key is derived from the admin key alone.** `deriveStudioToken(adminKey)` takes no Tenant id (HMAC-SHA256 over `nylorun/studio/v2`). The Host registers the new key's hash at its next start, replacing the old one; an app that embeds Studio and derives its key must update.
+  - `@nylorun/core`: `ProjectCredentialsFileSchema` gains optional `managementKey` and `managementPrincipalId`.
+
+- 6576e12: **Key roles and management keys (Runtime and Management APIs, step A1).** Additive; the protocol stays at 7. Application keys keep reaching every route they reach today.
+
+  - `@nylorun/runtime`: a key now has a role. `application` keys are unchanged. A new **management key** (role `management`) reaches the Management API (`/v1/tenant/*`) and `/v1/me` only, as itself: `Nylorun-Subject` or `Nylorun-Scopes` with it is `403 subject_invalid`, an `Origin` is `403 origin_rejected`, and any other route is `403 key_role_mismatch`. `/v1/me` reports it as `via: management:<id>` with no scopes and no agents. Studio's derived key has role `studio`, which reaches both. Migration `0011_key_roles` gives the existing `studio` principal its role.
+  - `@nylorun/runtime`: management keys are issued only on the Tenant's machine, with the new `nylorun-operate` command in the runtime image (`nylorun-operate keys list | put <id> [--role application|management] | rm <id>`), or from `NYLORUN_MANAGEMENT_KEY_FILE` (64 hex characters), which the Host registers as the key `bootstrap` at every start and replaces when the file changes. `bootstrap` is reserved like `studio`. Rotating a key keeps its role; putting an id that holds the other role is refused.
+  - `@nylorun/core`: `KEY_ROLES`, `KeyRole`, `BOOTSTRAP_KEY_ID` and the error code `key_role_mismatch`.
+
+- a6108f4: **The Management API's routes and client (Runtime and Management APIs, step A2).** Additive; the protocol stays at 7.
+
+  - `@nylorun/runtime`: `GET /v1/tenant/keys`, `PUT /v1/tenant/keys/{keyId}` and `DELETE /v1/tenant/keys/{keyId}` manage the Tenant's application keys with a management key. A management key's name, `studio` and `bootstrap` are refused, so no API call creates, rotates or deletes a management key. Vaults (`/v1/tenant/vaults…`, including `…/oauth/start`) and signing keys (`/v1/tenant/signing-keys…`) are also served under `/v1/tenant`, for management keys only; the old `/v1/vaults…` and `/v1/access/signing-keys…` paths keep serving application keys until protocol 8. `GET /v1/oauth/callback` and `GET /v1/access/jwks` keep their paths.
+  - `@nylorun/admin`: `createManagementClient({ url, key })` is the Management API's client: `tenant` (status, seed, reset), `keys` (application keys), `models` (catalog, providers, get, put, select, usage, budgets), `vaults` (with credentials and `startOAuth`), `signingKeys` and `settings` (sandbox, artifacts). `@nylorun/admin/client` exports it with no Node module, for browser apps behind a proxy that adds the key.
+
+- 005a200: **Two reference documents (Runtime and Management APIs, step A6).** The Runtime serves the Runtime API's OpenAPI document at `/openapi/runtime.json` (`/openapi.json` stays as its alias) and the Management API's at `/openapi/management.json`, both without a key. The package ships them as `@nylorun/runtime/openapi.json` and the new `@nylorun/runtime/management-openapi.json`, and both are attached to each release. Each document has described tags, every operation in one of them, in the order a developer uses them, and only the schemas it uses. The Runtime API's tags are grouped (`x-tagGroups`): Get started (Runtime), Agents (Agents, Action endpoints, Deliveries), Sessions (Sessions API, AG-UI, A2A), Sandboxes & artifacts. The Management API's tags are Tenant, Application keys, Models, Vaults, Signing keys and Settings.
+- 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
+
+- b387620: **A flow agent's tool step that asks now pauses the flow.** A tool step calling `ctx.approve(...)` or `ctx.ask(...)` used to settle its `interaction-required` outcome as the step's output, so the flow moved on and `turn.completed` carried that object, resume token and all. Now the flow session pauses with `turn.paused` and a wait (with the tool node's `path` and `toolName`); `session.approve(...)` or `session.respond(...)` on the flow's own session runs the tool again with the answer and its resume token, and the steps before it replay from the journal. A rejected approval settles the step `denied` without running the tool again, as in an agent's turn, so the turn fails with `tool.denied`. A flow's resume stays in its checkpoint segment (`FlowCheckpoint.resumes`), so its wake is keyed by the interaction. Waits a workflow copied from its linked sessions are no longer read back as its own.
+- 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.
+
+- 92faa35: **`nylorun-operate keys` names a database error.** When the Tenant's database cannot be read (a connection or driver failure), `nylorun-operate keys` now exits 2 with `The Tenant's database cannot be read: <cause>` instead of reporting that the database holds no Tenant.
+- Pin core to the tested release.
+- Pin harness to the tested release.
+- Updated dependencies [3b3bdc6]
+- Updated dependencies [b387620]
+- Updated dependencies [6576e12]
+- Updated dependencies [b28bdd7]
+- Updated dependencies [cc107b1]
+- Updated dependencies [7f763c3]
+- Updated dependencies [98b0d37]
+- Updated dependencies [c66d8ed]
+- Updated dependencies
+  - @nylorun/core@0.14.0-beta
+  - @nylorun/harness@0.22.2-beta
+
 ## 0.17.0-beta
 
 ### Major Changes

package/README.md

@@ -2,8 +2,10 @@
 
 The independent OSS **Runtime Host** consumes `@nylorun/harness/run` and
 `@nylorun/core/contracts`. Cloud installs published `@nylorun/harness` from npm
-and does not import this package. Client authoring and sessions belong to
-`@nylorun/agents`; the Host's status and operator keys belong to `@nylorun/admin`.
+and does not import this package. Every Tenant serves two APIs on one URL: the
+**Runtime API** for developers (agents, sessions with AG-UI and
+A2A, sandboxes, artifacts), whose client is `@nylorun/agents`, and the
+**Management API** for operators (`/v1/tenant/*`), whose client is `@nylorun/admin`.
 Vocabulary: [src/CONTEXT.md](./src/CONTEXT.md).
 
 Requires Node 24+. Build from the repository root:
@@ -35,14 +37,16 @@ transaction under an advisory lock, records them in `nylorun.__drizzle_migration
 refuses a database holding a migration it does not ship (`schema-too-new`); then, on
 first start, it creates the Tenant there: its id (`NYLORUN_TENANT_ID`, default a
 new one), its name (`NYLORUN_TENANT_NAME`, default `default`) and its Studio principal,
-whose key the admin key derives (the only derived key). Operator keys (`/v1/admin/keys`) add, rotate and delete the Tenant's
-application keys after that; a rotated or deleted key stops authenticating at once. A database written by a Runtime that kept several Tenants in one
+whose key the admin key derives (the only derived key). Management keys come from
+`nylorun-operate` or `NYLORUN_MANAGEMENT_KEY_FILE` (below), and a management key adds,
+rotates and deletes the Tenant's application keys (`PUT /v1/tenant/keys/{keyId}`); a rotated
+or deleted key stops authenticating at once. A database written by a Runtime that kept several Tenants in one
 database (`tenant_<id>` schemas), or by a pre-release build of one Tenant per database
 (`schema_version` tables), is refused: this release starts fresh on a new database. Restate runs one advance of a session at a time and holds the Tenant's sweep
 timer (Durable Session Execution); every session's events are relayed from the record to
 its own S2 stream, which history and SSE read (Durable Streams). One image runs every **service**,
-and `--service` picks what a process runs: `core` serves the Tenant API, Admin
-API and SSE and runs the stream relay, `loop` runs advances (the Worker), and
+and `--service` picks what a process runs: `core` serves the Runtime API, the
+Management API and SSE and runs the stream relay, `loop` runs advances (the Worker), and
 `gates` is the Model Gate, the only process that reads a model credential and
 calls providers. `core` and `loop` may share a process; `gates` never joins
 them. A local Tenant packs `core,loop` into the `runtime` container and
@@ -50,8 +54,7 @@ them. A local Tenant packs `core,loop` into the `runtime` container and
 api|worker|all` is the deprecated name of `--service core`, `loop` and
 `core,loop`.
 
-`harness` runs alone: agent turns, stdio MCP servers and workspaces, apart from
-core. With `NYLORUN_HARNESS=remote`, core runs no turn itself and opens the
+`harness` runs alone: agent turns and workspaces, apart from core. With `NYLORUN_HARNESS=remote`, core runs no turn itself and opens the
 Harness API listener (`NYLORUN_HARNESS_LISTEN_HOST`, `NYLORUN_HARNESS_LISTEN_PORT`,
 default 4200, `NYLORUN_HARNESS_ALLOWED_HOSTS`), which accepts only
 `NYLORUN_HARNESS_TOKEN`; `in-process` (the default outside Compose) runs turns in
@@ -67,16 +70,15 @@ sets: `NYLORUN_DATABASE_URL` (required), `NYLORUN_RESTATE_INGRESS_URL`,
 `NYLORUN_RESTATE_ADMIN_URL`, `NYLORUN_WORKER_URL` and
 `NYLORUN_RESTATE_IDENTITY_KEY` (Restate), `NYLORUN_S2_ENDPOINT` and
 `NYLORUN_S2_TOKEN`, and in container mode `NYLORUN_LISTEN_HOST`,
-`NYLORUN_LISTEN_PORT`, `NYLORUN_ALLOWED_HOSTS` and `NYLORUN_PUBLIC_URL`, plus
-the operator listener
-(`NYLORUN_ADMIN_LISTEN_PORT`, `NYLORUN_ADMIN_LISTEN_HOST`,
-`NYLORUN_ADMIN_ALLOWED_HOSTS`). `NYLORUN_IDENTITY_FILE` names the identity
-file, a YAML list of the trusted issuers whose JWTs the Tenant API accepts
+`NYLORUN_LISTEN_PORT`, `NYLORUN_ALLOWED_HOSTS` and `NYLORUN_PUBLIC_URL`.
+`NYLORUN_MANAGEMENT_KEY_FILE` names the bootstrap secret (below).
+`NYLORUN_IDENTITY_FILE` names the identity
+file, a YAML list of the trusted issuers whose JWTs the Runtime API accepts
 (Host feature `trusted-issuers`), read once at boot; a malformed file stops the
 boot ([DEPLOYMENT.md](../DEPLOYMENT.md#trusted-issuers)). A process that runs `loop` sends its model
 calls to the gate at `NYLORUN_GATES_URL`; in a container it refuses to start
 without it and `NYLORUN_GATES_TOKEN`. That token is core's credential: the gate
-accepts only it for vault writes, token signing and Action deliveries. Model and
+accepts only it for vault writes and token signing. Model, HTTP tool and
 remote MCP calls carry a run token instead, which the loop mints for each
 session it advances, and the gate takes the call's session, turn and agent from
 it; a token whose turn was cancelled or whose session another process took over
@@ -95,12 +97,25 @@ egress-gate on `NYLORUN_EGRESS_LISTEN_HOST`:`NYLORUN_EGRESS_LISTEN_PORT`
 tunnels only to the hosts its sandbox spec allows, on 443 or 80, never to a
 private address. `NYLORUN_PACKING` (`combined` or `split`) is logged at startup.
 
-With an operator listener (a local Tenant's default: container port 4001), the Host
-serves two ports. The public one serves the Tenant API, to browsers too (with a
-trusted issuer's token), and answers admin routes with the opaque `404`. The
-operator one serves the Admin API, Host shutdown and the Tenant API, never to
-browsers; keep it on loopback or a private network and never proxy it. Outside
-a container, `adminPort` in `host.json` does the same on loopback.
+The Host has one listener, which serves both APIs. Host work runs on the machine
+instead, with `nylorun-operate`, the image's operator command, inside the runtime
+container (`docker compose exec runtime nylorun-operate …`, or
+`kubectl exec … -- nylorun-operate …`). It reads the Tenant's database from
+`NYLORUN_DATABASE_URL`, does one job and exits: being able to run it is the
+authorization.
+
+```sh
+nylorun-operate status [--json]      # version, protocol, the Tenant's id, name, state and cause; exit 2 when not open
+nylorun-operate keys list [--json]   # every key: id, role, when issued
+nylorun-operate keys put <id> [--role application|management] [--json]   # prints the key once
+nylorun-operate keys rm <id> [--json]
+```
+
+`status` needs no key, so it reports why a Tenant cannot open. Where no one can run
+`nylorun-operate`, `NYLORUN_MANAGEMENT_KEY_FILE` names a file holding a management key
+(64 hex characters), the **bootstrap secret**: the Host registers it as the key
+`bootstrap` at every start, and replaces it when the file changes. Stop the Host with
+SIGTERM.
 
 The Host root is `NYLORUN_HOME` or `~/.nylorun` (for a local Tenant,
 `~/.nylorun/tenants/<name>/`, bind-mounted at `/nylorun` in its containers). What stays on the Host is under `tenant/`.
@@ -109,11 +124,11 @@ The Host root is `NYLORUN_HOME` or `~/.nylorun` (for a local Tenant,
 
 ```text
 <host root>/
-  host.json                 # format 1: hostId, host, port, adminPort?, runtimeVersion, …
-  host-credentials.json     # adminKey (0600)
+  host.json                 # format 1: hostId, host, port, runtimeVersion, …
+  host-credentials.json     # adminKey (0600): the root secret Studio's key derives from
   identity.yaml             # optional: trusted issuers (NYLORUN_IDENTITY_FILE)
   docker/                   # compose.yaml, .env (0600), Restate identity key
-  tenant/                   # vault-kek, plugin-data, logs, home, tmp, sandboxes
+  tenant/                   # logs, home, sandboxes
 ```
 
 ## HTTP surface
@@ -121,29 +136,27 @@ The Host root is `NYLORUN_HOME` or `~/.nylorun` (for a local Tenant,
 | Route | Auth | Notes |
 | --- | --- | --- |
 | `GET /health` | none | `service: "nylorun-runtime"`, `hostId`, protocol `{min,max,features}`, pid |
-| `GET /ready` | none | Listener up, the Tenant open, and Postgres, Restate and S2 answer (`checks`) |
-| `GET /openapi.json` | none | The Tenant API's OpenAPI 3.2 document (below); refuses an `Origin` |
-| `GET /v1/admin/status` | admin key | `AdminStatusSchema`: the Host, its protocol and its Tenant (`tenant`: id, name, `open` or `unavailable`, and the cause when it could not be opened); alias `GET /v1/admin/host`. On the operator listener when there is one |
-| `POST /v1/admin/host/shutdown` | admin key | Host-private; not in `@nylorun/admin` |
-| `PUT /v1/admin/keys/{id}` | admin key | Operator keys (Host feature `operator-keys`): creates key `id` or rotates it, and returns it once (`PutOperatorKeyResponse`); `studio` is refused |
-| `GET /v1/admin/keys` | admin key | Every key of the Tenant: id, role, when issued (`ListOperatorKeysResponse`), never the keys |
-| `DELETE /v1/admin/keys/{id}` | admin key | The key stops authenticating at once; `404` when there is none |
-| `GET /v1/admin/openapi.json` | admin key | The Admin API's OpenAPI 3.2 document |
-| `/v1/*` Tenant routes | application key, trusted issuer's token or delivery token | Require `Nylorun-Protocol`; nothing names the Tenant |
-| `POST /v1/vaults/{vaultId}/oauth/start` | application key | MCP OAuth connect into an installation vault (F9 C2): `{url, server, clientId?}` → `{authorizeUrl, expiresAt}`; the gateway's keys module does discovery, registration and the exchange. `oauth_client_required` without DCR or a `clientId` |
+| `GET /ready` | none | Listener up, the Tenant open, and Postgres, Restate and S2 answer (`checks`); `harness: { mode, connected }` while the Tenant is open |
+| `GET /openapi/runtime.json` | none | The Runtime API's OpenAPI 3.2 document (below); alias `GET /openapi.json`. Refuses an `Origin` |
+| `GET /openapi/management.json` | none | The Management API's OpenAPI 3.2 document. Refuses an `Origin` |
+| `/v1/*` Runtime API routes (all but `/v1/tenant/*`) | application key or trusted issuer's token | Require `Nylorun-Protocol`; nothing names the Tenant. A management key is `403 key_role_mismatch`, except on `/v1/me` and the public `GET /v1/access/jwks` |
+| `/v1/tenant/*` Management API routes | management key | Require `Nylorun-Protocol`. An application key, alone or acting for a subject, is `403 key_role_mismatch`; a management key with `Nylorun-Subject` or `Nylorun-Scopes` is `403 subject_invalid` |
+| `PUT /v1/tenant/keys/{keyId}` | management key | Creates application key `keyId` or rotates it, and returns it once; `GET /v1/tenant/keys` lists every key (id, role, when issued, never the keys) and `DELETE` deletes one. `studio`, `bootstrap` and management keys are refused |
+| `POST /v1/tenant/vaults/{vaultId}/oauth/start` | management key | MCP OAuth connect into an installation vault (F9 C2): `{url, server, clientId?}` → `{authorizeUrl, expiresAt}`; the gateway's keys module does discovery, registration and the exchange. `oauth_client_required` without DCR or a `clientId` |
 | `GET /v1/oauth/callback` | the `state` itself | Where the authorization server sends the browser back: no credential, no `Nylorun-Protocol`; finishes the connect once (`oauth_state_invalid` after) and answers a small HTML page. Its base is `NYLORUN_PUBLIC_URL`, else the start request's origin |
 | `GET /v1/artifact-links/{token}` | the link itself | A capability link to one artifact version (protocol 6): no credential, no `Nylorun-Protocol`, Range supported; a folder's link opens its zip, or one of its files |
 
 Every route checks `Host` first (`421 host_rejected`) and rejects non-JSON bodies
 with `415 unsupported_media_type`, except an artifact upload (`POST /v1/artifacts`,
 `POST /v1/artifacts/{id}/versions`), whose body is the file in any media type. An `Origin` is `403 origin_rejected` on
-`/health`, `/ready`, admin routes and the operator listener. On Tenant routes a browser
-presents a trusted issuer's token; application keys and delivery tokens are refused
-from browsers before they are looked up. The Runtime sends no CORS headers, and answers
+`/health`, `/ready` and the OpenAPI documents. On `/v1` routes a browser
+presents a trusted issuer's token; keys (application and management)
+are refused from browsers before they are looked up. The Runtime sends no CORS headers, and answers
 `OPTIONS` with `204` and `Allow` only: the operator's reverse proxy answers preflights
 ([DEPLOYMENT.md](../DEPLOYMENT.md#calling-the-runtime-from-browsers-and-apps)). Missing or
-unsupported protocol → `426` before authentication (the Host serves protocols 4 to 7;
-protocol 7 removes subject tokens, the access policy, revocations, browser keys and
+unsupported protocol → `426` before authentication (the Host serves protocols 4 to 8;
+protocol 8 gives keys roles, moves vaults and signing keys under `/v1/tenant` and removes
+the Admin API, and those old paths answer `404` with no alias; protocol 7 removes subject tokens, the access policy, revocations, browser keys and
 derived principals, whose routes answer `404`; protocol 6 adds file and folder artifacts and message `parts`; at each turn's end the
 Runtime exports `/workspace/outputs` of the session's sandbox as a version of its
 `outputs` folder, read at `/v1/artifacts/{id}/versions/{n|latest}/tree`, `/files/{path}`,
@@ -157,21 +170,28 @@ once the caller is known.
 The Runtime describes its APIs as OpenAPI 3.2 documents, generated from the routes it serves,
 so they cannot drift from its answers:
 
-| Document | In the package | Served | On each release |
+| Document | In the package | Served (no key) | On each release |
 | --- | --- | --- | --- |
-| Tenant API | `@nylorun/runtime/openapi.json` | `GET /openapi.json` | `openapi.json` |
-| Admin API | `@nylorun/runtime/admin-openapi.json` | `GET /v1/admin/openapi.json` (admin key) | `admin-openapi.json` |
+| Runtime API | `@nylorun/runtime/openapi.json` | `GET /openapi/runtime.json` (alias `GET /openapi.json`) | `openapi.json` |
+| Management API | `@nylorun/runtime/management-openapi.json` | `GET /openapi/management.json` | `management-openapi.json` |
 
 The release assets are on the `@nylorun/runtime@<version>` GitHub Release. Point any OpenAPI 3.2
 tool at one of them; for [Scalar](https://scalar.com), the package file of a version works as is:
 
 ```text
 https://cdn.jsdelivr.net/npm/@nylorun/runtime@<version>/dist/openapi.json
+https://cdn.jsdelivr.net/npm/@nylorun/runtime@<version>/dist/management-openapi.json
 ```
 
-Each operation's `security` says which credentials it takes (application key, trusted
-issuer's token, delivery token, admin key), and its `x-nylorun-credentials` and
-`x-nylorun-scopes` (the subject scopes that reach it) fields say who may call it. Event streams are `text/event-stream` with an `itemSchema`. `runtime/openapi/` holds the committed snapshots: a change to a route changes
+Each document has described tags, in the order a developer uses them. The Runtime API's are
+grouped (`x-tagGroups`): Agents (Agents, Definition files), Sessions (Sessions API, AG-UI,
+A2A), Sandboxes, Artifacts and Service (health, readiness, `/v1/me`, the JWKS and the
+document; the `/openapi.json` alias is served but not listed). The Management API's are
+Tenant, Application keys, Models, Vaults, Signing keys and Settings. Each operation's
+`security` says which credentials it takes (application key and trusted issuer's token in
+the Runtime API; management key in the Management API), and its
+`x-nylorun-credentials` and `x-nylorun-scopes` (the subject scopes that reach it) fields say
+who may call it. Event streams are `text/event-stream` with an `itemSchema`. `runtime/openapi/` holds the committed snapshots: a change to a route changes
 them (`node scripts/build-openapi.mjs --write`), and `check-package` fails until they are
 updated.
 
@@ -180,15 +200,16 @@ updated.
 Routes are Hono routes (`@hono/zod-openapi`), each declared once with who may call it
 (`api/http/define.ts`): that declaration serves the route, checks subject scopes and makes
 the OpenAPI document. `host/` holds the listeners, the `Host`
-check (in Node, before Hono) and the Host pipeline (`host/app.ts`); `api/` the Tenant and
-Admin routes (`api/http/routes/`, `api/ag-ui/`, `api/a2a/`, `host/admin-api.ts`). Only `host/`
-and `api/` import Hono.
+check (in Node, before Hono) and the Host pipeline (`host/app.ts`); `api/` the routes of
+both APIs (`api/http/routes/`, `api/ag-ui/`, `api/a2a/`). Only `host/` and `api/` import
+Hono. `nylorun-operate` is `host/operate.ts`.
 
 ## Embedding and tests
 
 Tests and ephemeral embeds use `startEphemeralRuntime()` from
 `@nylorun/runtime/core`: private Host on port 0, temporary Host root, one Tenant,
-returns `{ url, tenantId, applicationKey, adminKey, close() }`. Its Tenant is the
+returns `{ url, tenantId, applicationKey, managementKey, adminKey, close() }`
+(`managementKey` is the key `bootstrap`, for the Management API). Its Tenant is the
 one Tenant of the Postgres database you pass as `database` (required): a pool, which
 you end, or a URL, for which it opens a pool and ends it on `close()`. It creates the
 Tenant there on first start, as a Host does (with `tenantId`, `name` and an application
@@ -210,10 +231,11 @@ The package's own tests run every Session Store on Postgres: `npm test` gives ea
 test file a database on the Docker test stack (`test/stack/compose.yaml`) and starts
 the stack when it is down; see [CONTRIBUTING.md](../CONTRIBUTING.md).
 
-Register Action endpoints with `PUT /v1/endpoints` using the application principal
-(`createActionHandler(...).register({ url })` in `@nylorun/agents` does this). The
-Runtime delivers each Action there with an `http` or `https` POST, so the URL must be
-reachable from the Runtime. Model gateway
+Save agents with `PUT /v1/agents/{agentId}` using the application principal (`saveAgent`
+in `@nylorun/agents`). The Runtime runs the agent from its manifest and never calls your
+code during a session: a definition with a tool that would (`tool({ run })`, a flow's tool
+stage) is refused. Your services are reached as tools: HTTP tools, POSTed from the Runtime,
+so their URLs must be reachable from it, and remote MCP servers. Model gateway
 and sandbox backend are Tenant configuration (vault / seed), not Host process
 env.
 
@@ -221,12 +243,10 @@ env.
 
 The session-first `/v1` API is specified in
 [HOST_CONTRACT.md](../harness/HOST_CONTRACT.md). Application tokens authorize
-definition/session APIs. The Runtime delivers Actions to Action endpoints, and a
-delivery token authorizes only its own Action's heartbeat, result and sandbox calls.
-Session observers cannot submit action results.
+definition/session APIs.
 
 Postgres transactions persist session checkpoints, command receipts, individual
-effects/actions, waits and the record of session events — in the Tenant's database; history is
+effects, waits and the record of session events — in the Tenant's database; history is
 read from Durable Streams (S2). An advance owns its session through a lease with
 an epoch; a Worker that takes over after a crash marks in-flight effects
 `uncertain`. Vault ciphertext needs that Tenant's own KEK.
@@ -246,14 +266,25 @@ the Project link (outside a project it runs the Tenant `default`); the project's
 | Symptom | What to do |
 | --- | --- |
 | `kek-missing` | Restore `vault-kek` in the Tenant directory |
-| `GET /ready` is 503 and `/v1/admin/status` names a `tenant.cause` | The Tenant could not be opened; every Tenant request is the opaque `404`. Follow the cause's `repair`, then restart the Runtime |
+| `GET /ready` is 503 with `checks.tenant: false` | The Tenant could not be opened; every `/v1` request is the opaque `404`. `nylorun status` on a local Tenant, or `nylorun-operate status` in the runtime container, names the cause and its repair. Follow it, then restart the Runtime; otherwise the Runtime's log names the cause |
 | `corrupt` / `migration-failed` / `envelope-invalid` / `open-failed` / `open-timeout` | Follow the cause's `repair` string |
 | `schema-too-new` | Run a Runtime at least as new as the one that migrated the database |
 | `database-layout-old` | The database holds `tenant_<id>` schemas of an older Runtime, or the `schema_version` tables of a pre-release one: point the Runtime at a new database (locally, a new Tenant: `nylorun start --tenant <new name>`); the old one is left as it is |
 | `426 protocol_unsupported` | Upgrade clients or Host to a compatible set |
-| `421 host_rejected` / `403 origin_rejected` | In a container, list the `Host` in `NYLORUN_ALLOWED_HOSTS`. From a browser, send a trusted issuer's token, never a Tenant key |
+| `421 host_rejected` / `403 origin_rejected` | In a container, list the `Host` in `NYLORUN_ALLOWED_HOSTS`. From a browser, send a trusted issuer's token, never a key |
+| `403 key_role_mismatch` | The key belongs to the other API: use a management key on `/v1/tenant/*` (`@nylorun/admin`) and an application key everywhere else (`@nylorun/agents`) |
 | `503` for a Tenant | Postgres or Restate is unreachable; `GET /ready` names which |
 | Port in use | Change `NYLORUN_PORT` in `~/.nylorun/tenants/<name>/docker/.env` and run `nylorun start` |
 | Logs | `nylorun logs runtime` |
 
 Definitions have no `agent.run()`; applications use `@nylorun/agents`.
+
+## Session reads
+
+Hosts advertising `session-reads` serve pinned session manifests, recorded usage, model-call
+pages and opt-in session/history/sandbox pagination. `calls-export` adds the Management API's
+unfiltered, resumable model ledger export (`GET /v1/tenant/calls/model`, a management key) in
+safe transaction order. Existing list/history
+requests without `limit` retain their response shapes. These are public APIs for Studio,
+CLI and custom clients; clients never need database access. See the
+[API contracts, authorization, SDK examples and Studio handoff](https://github.com/nylorun/agents/blob/main/runtime/docs/session-reads.md).

package/dist/adapters/execution/restate.d.ts

@@ -96,11 +96,9 @@ export declare class RestateExecution implements DurableExecution {
         session: string;
         tenant: string;
         timer: string;
-        action: string;
         sandbox: string;
     };
     wake(tenantId: string, sessionId: string, wake: Wake): Promise<void>;
-    deliver(tenantId: string, actionId: string): Promise<void>;
     sandbox(tenantId: string, sandboxId: string, signal: SandboxSignal): Promise<void>;
     timer(tenantId: string, key: string, at: Date): Promise<void>;
     armSweep(tenantId: string): Promise<void>;
@@ -118,7 +116,7 @@ export declare class RestateExecution implements DurableExecution {
     private definitions;
     /**
      * Runs a Worker handler with a signal aborted by `stop` or by the end of the Restate
-     * attempt (`advance` and `deliver`).
+     * attempt (`advance` and `reconcile`).
      */
     private runAborted;
     /** Runs a Worker handler so that `stop` waits for it. Refuses once stopping; Restate retries. */

package/dist/adapters/execution/restate.js

@@ -17,11 +17,6 @@
  * - `<prefix>NylorunTimer`, key `<tenantId>:<timer key>`. `set` records the
  *   latest time and sends a delayed `fire`; a `fire` for an older time is a
  *   no-op, which is how setting a key again replaces it.
- * - `<prefix>NylorunAction`, key `<tenantId>:<actionId>`. Its exclusive
- *   `deliver` handler calls `WorkerHandlers.deliver`. Like `advance`, it keeps
- *   no state and makes no `ctx.run`: its only journal entry is the delayed
- *   self-send after a `retry` result, so an endpoint that is down never spends
- *   the retry budget, which is for infrastructure errors.
  * - `<prefix>NylorunSandbox`, key `<tenantId>:<sandboxId>` (F7.2). Its
  *   exclusive handlers serialize a pod sandbox's reconciles and timers:
  *   `reconcile` calls `WorkerHandlers.sandbox`; `arm` records a timer's latest
@@ -29,7 +24,7 @@
  *   `fire`; a `fire` for an older time is a no-op, as the timer object's.
  *   What a run answers arms its timers and its retry.
  *
- * Wakes, deliveries, timers and sweep arming go through the ingress as one-way
+ * Wakes, sandbox reconciles, timers and sweep arming go through the ingress as one-way
  * sends, so an API node can call them without ever calling `start`.
  */
 import { createServer } from "node:http2";
@@ -60,7 +55,6 @@ export class RestateExecution {
             session: `${prefix}NylorunSession`,
             tenant: `${prefix}NylorunTenant`,
             timer: `${prefix}NylorunTimer`,
-            action: `${prefix}NylorunAction`,
             sandbox: `${prefix}NylorunSandbox`,
         };
         this.ingressUrl = options.ingressUrl.replace(/\/+$/, "");
@@ -76,9 +70,6 @@ export class RestateExecution {
             throw new Error(`Unknown wake reason: ${String(wake.reason)}`);
         await this.send(this.names.session, sessionKey(tenantId, sessionId), "advance", { reason: wake.reason }, wake.dedupeKey);
     }
-    async deliver(tenantId, actionId) {
-        await this.send(this.names.action, sessionKey(tenantId, actionId), "deliver", {});
-    }
     async sandbox(tenantId, sandboxId, signal) {
         const key = sessionKey(tenantId, sandboxId);
         if (signal.kind === "reconcile")
@@ -259,24 +250,6 @@ export class RestateExecution {
             },
             options: serviceOptions,
         });
-        const action = restate.object({
-            name: names.action,
-            handlers: {
-                deliver: async (ctx, _input) => {
-                    const { tenantId, sessionId: actionId } = parseSessionKey(ctx.key);
-                    const result = await this.runAborted(ctx.request().attemptCompletedSignal, (handlers, signal) => {
-                        if (!handlers.deliver)
-                            throw new Error("WorkerHandlers.deliver is required for deliveries");
-                        return handlers.deliver(tenantId, actionId, signal);
-                    });
-                    if (result.status === "retry")
-                        ctx
-                            .objectSendClient({ name: names.action }, ctx.key)
-                            .deliver({}, restate.rpc.sendOpts({ delay: Math.max(0, result.retryAfterMs) }));
-                },
-            },
-            options: serviceOptions,
-        });
         /** Sets a sandbox timer: the latest time wins; `fire` checks it. */
         const armSandbox = async (ctx, input) => {
             ctx.set(`at:${input.timer}`, input.at);
@@ -318,11 +291,11 @@ export class RestateExecution {
             },
             options: serviceOptions,
         });
-        return [session, tenant, timer, action, sandbox];
+        return [session, tenant, timer, sandbox];
     }
     /**
      * Runs a Worker handler with a signal aborted by `stop` or by the end of the Restate
-     * attempt (`advance` and `deliver`).
+     * attempt (`advance` and `reconcile`).
      */
     async runAborted(attemptDone, fn) {
         const controller = new AbortController();
@@ -424,7 +397,7 @@ export async function listStuckInvocations(options) {
     const prefix = options.servicePrefix ?? "";
     if (!/^[A-Za-z0-9_]*$/.test(prefix))
         throw new Error(`Invalid Restate service prefix: ${prefix}`);
-    const services = ["NylorunSession", "NylorunTenant", "NylorunTimer", "NylorunAction", "NylorunSandbox"].map((name) => `'${prefix}${name}'`);
+    const services = ["NylorunSession", "NylorunTenant", "NylorunTimer", "NylorunSandbox"].map((name) => `'${prefix}${name}'`);
     const clauses = [
         `target_service_name IN (${services.join(", ")})`,
         `status IN ('paused', 'backing-off')`,

package/dist/adapters/replication/pgoutput.js

@@ -146,7 +146,7 @@ export function createPgoutputSource(options) {
         },
         async lag() {
             // An idle relay confirms one byte past the last record, ahead of pg_current_wal_lsn():
-            // that is no lag, not -1 (the Admin status refuses a negative lag).
+            // that is no lag, not -1.
             const { rows } = await pool.query(`SELECT GREATEST(pg_wal_lsn_diff(pg_current_wal_lsn(), confirmed_flush_lsn), 0)::text AS lag
          FROM pg_replication_slots WHERE slot_name = $1`, [slot]);
             return rows[0]?.lag == null ? undefined : Number(rows[0].lag);

package/dist/adapters/sandbox/local.js

@@ -164,7 +164,7 @@ export function localBackend(options) {
             return { entries, truncated: !complete };
         },
         async writeFile(path, content) {
-            await writeFile(path, content, "utf8");
+            await (typeof content === "string" ? writeFile(path, content, "utf8") : writeFile(path, content));
         },
         async stop() { },
     };

package/dist/adapters/sandbox/virtual.js

@@ -140,7 +140,7 @@ export function virtualBackend(options) {
                     return { entries, truncated: !complete };
                 },
                 async writeFile(path, content) {
-                    await fs.writeFile(path, content, "utf8");
+                    await (typeof content === "string" ? fs.writeFile(path, content, "utf8") : fs.writeFile(path, content));
                 },
                 async stop() { },
             };