@nylorun/runtime 0.23.0-beta → 0.24.0-beta

package/CHANGELOG.md

@@ -1,5 +1,153 @@
 # Changelog
 
+## 0.24.0-beta
+
+### Minor Changes
+
+- e917bd6: **Bring your own harness: harness ids, harness-owned state, and who wrote each event (R4.1, R4.2, R4.4, R4.9).**
+
+  - **Harness ids and routing.** An Environment's `harness` takes any harness id (`^[a-z][a-z0-9-]{1,62}$`). It is no longer only `nylorun`.
+    - **The pin.** A session pins its harness when it opens: its Environment's harness, else `nylorun`. A flow always runs `nylorun`. `GET /v1/sessions/{id}` returns the pin as `harness`.
+    - **Routing.** Only a connection whose `hello.name` is that id takes the session's runs.
+    - **Our harness's name.** It now says `nylorun` in `hello`. A harness that says `@nylorun/harness` is refused with a message naming the new id, so an older harness image needs this Runtime's.
+    - **Placement.** It is keyed by the real harness id, and `"*": {hosts: []}` refuses any harness the map does not name.
+    - **Drift.** A turn on an Environment that now runs another harness is `409 harness_mismatch`; open a new session. For a pod Environment, a changed `harness` applies at the pod's next wake, like its image.
+  - **Per-harness tokens.** `nylorun-operate harness token put <id>` makes a custom harness container's own Harness API credential, bound to its id; `list` and `rm` manage them. `NYLORUN_HARNESS_TOKEN` stays ours, bound to `nylorun`.
+  - **A custom harness as a pod's image.** A pod Environment whose harness is not ours runs its `image` as the harness: the image's own entrypoint (`entrypoint: "image"` to the sandboxes service), with nothing copied in. It needs `image`.
+  - **Harness-owned state.** Core stores a harness's turn state as sent and never reads it. Our engine now aligns its state with the turn's manifest itself.
+    - **Limits for a custom harness.** Its state is at most 256 KiB, or its turn fails. It cannot pause for approvals in Harness API 2.
+    - **Native tools.** It may declare the tools it runs itself in `hello` (`capabilities.tools`). Their calls (capability `harness`) are journaled like built-ins, and the log records a real `tool.completed` instead of `tool.unavailable`.
+  - **Who wrote each event.** The writer sets an event's `source` and `evidence`; the event's type no longer decides them. Events written before this release still say `loop` or `api`.
+    - **`client`**: a command, with a new `principal` taken from its credential.
+    - **`harness`**: what a harness reported, with its harness id and `runId`. Evidence `claimed`.
+    - **`core`**: core's own logic. Evidence `observed`.
+  - **`effectId` on model calls.** `GET /v1/sessions/{id}/calls/model` returns each call's `effectId`, so a metered call joins the effect journal.
+  - **The published contract grows.** It adds `HarnessCheckpointSchema` (the checkpoint fields a harness reads), `NativeToolSchema`, the harness id helpers, `HARNESS_TOOLS_CAPABILITY`, `MAX_HARNESS_STATE_BYTES`, and the gate error codes `key_required` and `effect_not_journaled`. It also documents the effect context keys, the model request hash rule and how a turn's status maps to its output method.
+
+- 5165451: **A pod's disk can start prepared, and every Environment's disk has versions (R2d steps 2 and 3).** Before, a new pod volume was empty and a disk could only be kept or reset. Now:
+
+  - **Setup and input files** (pods, Host feature `environment-setup`): `PUT /v1/environments/{id}` takes `files` (versions of Tenant-wide artifacts, copied in: a file at its `path`, a folder under it) and `setup` (commands run in order with `/bin/sh -c`, `cwd` default `/workspace`, `timeout` default 10m and at most 30m, at most 16 of each). They run once per new disk, after the pod's engine joins and before its first turn, with the Environment's variables, secrets (as the sentinel) and egress. A failed command fails the pod (`observed: failed`, reason `setup: command N …`, an `environment.failed` event with the exit code and the end of the output) and the turn waiting for it; the next turn start runs the setup again. A virtual Environment refuses both with a `400`.
+  - **Disk versions** (Host feature `environment-disk-versions`): `POST /v1/environments/{id}/snapshot` keeps a version of the disk between turns (`/workspace`, and a pod's `/harness` but the engine's own files) as a version of a folder artifact the Environment owns, with modes, modification times, links and empty directories (folder manifest `nylorun.folder.v2`); each file's bytes are stored once, and an unchanged disk makes no version. `POST .../restore` puts a version back: a virtual Environment at once, a pod on a new volume seeded before its next turn (`disk.operation` in the view meanwhile; turns wait). `PUT` with `from: { environment, version }` creates an Environment from another's version. `GET .../versions` and `DELETE .../versions/{n}` list and delete them; their trees, files, diffs and zips read through `/v1/artifacts`. A lost pod volume with a version is recovered from the latest one instead of refusing turns until a reset. Snapshot and restore during a turn are `409 environment_busy`. `EnvironmentView.disk` gives the latest version and the copy in progress. Migration `0021_disk_versions`.
+  - `@nylorun/agents`: `client.environments.snapshot`, `restore`, `versions` and `deleteVersion`; `put` takes `setup`, `files` and `from`.
+
+- 35e29b7: **Environments replace sandboxes and vaults (protocol 11). This is a fresh start: upgrading deletes your sandboxes, their disks and every vault except the model's, and closes every open session (its history stays readable).** List what you have before upgrading; see "Environments replace sandboxes and vaults" in MIGRATION.md.
+
+  An Environment is where sessions run: one sandbox (kind `virtual`, `pod` or `none`) with a recipe that can change, and one vault of secrets for its shell, MCP servers and HTTP tools. The app decides who uses which Environment; the Runtime keeps it by id and holds its lifecycle.
+
+  - `@nylorun/core`: protocol 11 (the Host accepts 11 only; older clients get `426`), required feature `environments`. `PutEnvironmentRequestSchema`, `EnvironmentViewSchema` (`recipe`, `version`, `appliedVersion`, `ownerUserId`, `lastUsedAt`), `PutEnvironmentSecretRequestSchema`, `EnvironmentSecretViewSchema`, `ENVIRONMENT_EVENT_TYPES`, `TenantEnvironmentsConfigSchema`, `environmentGranted`. `PutSessionRequest.environment` replaces `sandbox`, `vaultIds` and `credentialSelections`; `SessionView.environment` replaces the session's sandbox and vault fields. Error codes `environment_busy`, `environment_unavailable`, `environment_lost`, `environment_not_granted`, `environment_owner_mismatch` and `session_closed` (the `sandbox_*` codes and `sandbox_expired` are gone); session events `environment.state`, `environment.exec` and `environment.attached`; scope `environments:write`. Credential coverage takes `environmentId` and answers `covered` or `missing`; the MCP preview takes `environmentId`. The vault Management schemas are removed.
+  - `@nylorun/runtime`: `/v1/environments/{id}` replaces `/v1/sandboxes/{id}`: `PUT` creates, finds or changes one (`kind` and `storage` fixed; a recipe change bumps `version`; a pod gets a new image or resources at its next start from stopped, a new allowlist within seconds), with list by label, events (`nylorun.environment-event/1`), stop, reset and delete. Each Environment owns one vault: `PUT|GET|DELETE /v1/environments/{id}/secrets/{name}` on the Runtime API, write-only, with a second credential for a host or URL refused at the write (`409 credential_conflict`). An optional owner guard (`ownerUserId`) is checked when a session opens and at every turn start. `lifecycle.deleteAfter` deletes an Environment unused that long; TTL and `onExpiry` are gone. Kind `none` holds secrets for MCP-only agents. `/v1/tenant/vaults`, user and installation vaults, the Tenant's default sandbox, inline sandboxes and `{ session }` sharing are removed. The Tenant setting is `environments.config` (`limits.environments`). Identity files grant `environments:` (an old `sandboxes:` key, or `sandboxes:write`, stops the Runtime with a message naming the new key). Migration `0020_environments`.
+  - `@nylorun/harness`: the Harness API claims `environment.state` and `environment.exec`, and its workspace fields name `environmentId`.
+  - `@nylorun/agents`: `client.environments` (`put`, `get`, `list`, `page`, `stop`, `reset`, `delete`, `events`, `secrets.put|list|get|delete`, `forSession`) replaces `client.sandboxes`; `createSession({ environment })`; `sessions.page({ environmentId })` filters by Environment. The AG-UI handler's session options take `environment`.
+  - `@nylorun/admin`: `admin.coverage({ agentId, environmentId })` replaces `admin.vaults`; `admin.mcp.preview({ url, environmentId })`.
+  - `@nylorun/studio`: Environments replace Sandboxes, with a create form, stop, reset, delete and their secrets; the Credentials forms write an Environment's secrets; New session picks an Environment and shows its coverage.
+  - `nylorun`: `nylorun sandbox ls|rm` list and delete Environments; `nylorun mcp inspect --environment <id>` replaces `--vault`; `nylo reset --environments` replaces `--sandboxes`; `nylo doctor sandbox` reports the Environment limits.
+
+- e917bd6: **The Harness API is a published contract (R4.5).** Everything a harness sends or reads now has a schema in `@nylorun/core/harness-api`, and the Runtime validates with those same schemas:
+  - the transport and the pod join (`HARNESS_API_PATH`, `HARNESS_API_HEADER`, `HOST_JOIN_PATH`, `HostJoinRequestSchema`, `HostJoinAnswerSchema`);
+  - the Model and Tool Gate bodies (`ModelCallBodySchema`, `ToolCallBodySchema`, `HttpCallBodySchema`, the MCP bodies, `GATE_ERROR_CODES`);
+  - the MCP snapshot (`McpSnapshotSchema`);
+  - transcript entries (`TranscriptEntrySchema`);
+  - the effect id rule (`effectIdOf`, `isEffectIdOf`).
+
+  The build also writes them as one JSON Schema document, `@nylorun/core/harness-api/schema.json`, for harnesses written in other languages.
+
+  Other changes:
+  - `TurnStart` gains an optional `trace` (W3C `traceparent`) for the turn's trace context. Nothing fills it yet.
+  - Core refuses a `hello` whose `api` is not `2`.
+  - **The fixture model answers at the Model Gate (R4.3).** With a Tenant's `fixtureModel` seeded, the gate answers model calls itself and meters each one, like any model: a `model_usage` row with provider `fixture` and cost 0, readable at `GET /v1/sessions/{id}/calls/model`. Our harness no longer answers it locally.
+  - The fixture model also answers scripted markers: `fixture:text`, `fixture:tool <name> <json>`, `fixture:budget` and `fixture:slow <seconds>`.
+  - **The sandboxes service can run a harness image (R4.4, Go).** `PUT /v1/pods/{name}` accepts `entrypoint: "image"`: the workload image's own `ENTRYPOINT` and `CMD` run, with no engine copied in and no `harnessImage`. The default, `entrypoint: "engine"`, is unchanged. The Runtime starts sending it with the harness pin in a later change.
+
+- 3013501: **Tool calls are delivered at least once, and every one is on the record (R5 step 1).** A gateway restart used to park the sessions it interrupted as `uncertain` until someone cancelled them, a harness could call tools with no record, and nothing listed a session's tool calls. Now every tool call ends in the log with its outcome, a crash sends it again with the same key, and the gateway runs only calls the effect journal recorded.
+
+  - **Every outcome in the log.** Each tool call ends in one `tool.completed` with `status` (`completed`: the tool answered; `failed`: the Runtime ended it, `tool.disabled`, `tool.unavailable` or `tool.interrupted`; `cancelled`), `kind` (`mcp`, `http`, `sandbox`, `platform`), `server`, `attempts` and `durationMs`. Refused and cancelled calls are in the log for the first time.
+  - **`GET /v1/sessions/{id}/calls/tool`** pages a session's tool calls from the effect journal, in the order they were first sent: tool, input, status, sends, error and timing. Same credentials and paging as `/calls/model`; `@nylorun/agents` adds `session.toolCalls()`. Host feature `tool-calls`.
+  - **At least once, with the same key.** An MCP or HTTP tool call that a crash, a shutdown or a lost gateway hop interrupted is sent again with its effect id as the key, up to 3 sends; then it fails to the model as `tool.interrupted` ("may have run") and the session continues. A gateway that restarts mid call runs the call again under its key instead of answering `uncertain`. HTTP tools get the key as `Idempotency-Key`, as before; MCP servers now get it in `_meta["nylorun/idempotency-key"]` on `tools/call`. A tool that honors the key acts once; `attempts` above 1 marks where one may have acted twice.
+  - **Sandbox commands are never run twice.** A sandbox or core-served call a crash interrupted has no key to dedupe on, so it fails to the model as `tool.interrupted` at once, and the model decides whether to run it again.
+  - **No tool call parks a session.** The `uncertain` state for tool calls, its cancel-only exit and R2b's read-only/idempotent `mcp.lost` exception are gone: a lost MCP answer is `mcp.lost` to the model for every tool. Model calls keep their own rules.
+  - **The gateway runs only journaled calls.** Under a run token, `/nylorun/v1/tool-calls` and `/nylorun/v1/http-calls` need the call's effect id as `Idempotency-Key` (`400 key_required`), and the effect journal must hold it running, for the run's turn, the same tool and the same input (`409 effect_not_journaled`). A harness that skips the journal gets nothing run.
+  - `@nylorun/harness`: `HarnessExecutors.resends(effect, error, run)` says a gate hop lost a call's answer; the harness then asks core again with the same intent and sends the call again.
+  - **Approval** stays in the manifest and our harness still asks for it. Only the Runtime's own harness asks: one built from the Harness API can skip it until tool policy moves to the gateway (R5 step 2).
+
+- 6061a3a: **Tool approvals are the Tenant's tool policy (R5 step 2).** An agent's manifest used to say which tool calls wait for a person, and only the Runtime's own harness asked; a harness built from the Harness API could skip it. Now the operator sets one tool policy for every agent and every harness, and the Runtime enforces it before anything is sent.
+
+  - **`GET`/`PUT /v1/tenant/tool-policy`** (the Management API; `admin.toolPolicy.get()`/`.put({ rules })`): rules `{ effect: "allow" | "ask" | "deny", tool?, server?, kind?, agent?, when?, reason? }`. A rule matches a call when every selector it sets matches (`tool` and `server` take `*` globs; `when` tests input fields by dotted path with `equals`, `in`, `gt`, `gte`, `lt`, `lte` or `matches`). The strictest matching rule decides; a call no rule matches runs.
+  - **Enforced for every harness.** Core decides an MCP or HTTP tool call as it journals it. `deny` fails it to the model as `tool.denied`, unsent. `ask` holds the call (`held` at `/calls/tool`) and pauses the turn with one `approval` interaction per held call (`turn.paused`, with the tool, its input and the reason). `approve` sends that exact call, or fails it as `tool.denied`. The Tool Gate runs only calls the journal holds running, so a held or refused call cannot run. Nothing holds a process while it waits: an approval survives a restart. A flow's HTTP stages are decided the same way.
+  - **`approval` leaves the manifest.** `PUT /v1/agents/:id` and `saveAgent()` refuse a definition that sets `approval` on an HTTP tool, an MCP server or an MCP tool's settings; `http({ approval })` and `.mcp({ … approval })` throw; a turn manifest can no longer add one. The engine never asks for an HTTP or MCP tool's approval itself. A session pinned to a manifest saved with `approval: "always"` keeps it, as an ask.
+  - `@nylorun/studio`: a paused session shows an approval card for each held call, with its tool, why it is held and its input, and **Approve** / **Deny**.
+  - Migration: move each `approval: "always"` to an `ask` rule (see MIGRATION.md).
+
+- 7d496e4: **Every connection a pod Environment makes to the internet is on the record (R7, egress events).** egress-gate used to keep only log lines, so a session's log could not say which hosts its turn reached or what the gate refused. Now each connection through egress-gate is one event, written by the gate itself.
+
+  - **`egress.connection`** in the session log of the turn that held the Environment when the connection opened, with that turn's id even if the turn has ended by the time it closes. Source `egress-gate`, evidence `observed`.
+  - **`environment.egress`**, the same payload, on the Environment's own stream (`GET /v1/environments/{id}/events`) for traffic while no turn holds the Environment.
+  - **The payload:** `environmentId`, `host`, `port`, `outcome` (`allowed` or `refused`), `reason` and `status` for a refusal, `mode` (`tunnel` or `credential`), `credentialBound`, `bytesUp` and `bytesDown`, `startedAt` (the gate's clock at CONNECT) and `durationMs`. A host a shell credential is bound to adds `requests` and the `credentialIds` the gate set. It never carries a header value, a URL path or a body.
+  - **One event per connection:** written when it closes, or at once when the gate refuses it (a host not in `network.allowedHosts`, a port other than 443 or 80, a private address, too many tunnels, a name that does not resolve). A refusal before the Environment is known (no token, an expired or stale one) stays a log line only.
+  - **Never in the way:** a write happens after the connection closes or is answered, and a failed write is logged as `egress_record_failed` without touching the tunnel. The gateway's `egress_refused` and `egress_terminated` log lines stay.
+
+- 81c783e: **Every row that ends a call or a turn carries its own timing (R7.1).** The session log said what happened but not how long it took: a model call's outcome had no time at all, a tool call's only core's window, a flow's HTTP stage had no outcome row, and a turn's end had neither its duration nor its cost. Now each one is a span on its own, ready for the traces that follow, with no protocol change.
+
+  - **Model calls.** `message.assistant`, `model.failed` and `context.compacted` carry the call's `effectId` and `durationMs` (from the intent to the outcome). When the Model Gate metered the call they also carry the gate's own `gate: { startedAt, endedAt }`, `firstTokenMs` (to the provider's first stream event) and `meteredUsage` (`inputTokens`, `outputTokens`, `totalTokens`, and `cachedTokens` and `costUsd` when not zero), beside the `usage` the harness reported. The usage ledger keeps the gate's times (migration 0022: `model_usage.started_at`, `ended_at`, `first_token_ms`).
+  - **One row per model call.** A step that said nothing (no text, no tool calls, as a structured answer) now writes `message.assistant` with `text: ""`, and each partial summary of a long compaction writes `context.compacted` with `partial: true`. The AG-UI and A2A histories skip both; `isEmptyAssistantMessage` in `@nylorun/core/contracts` tells your own UI which steps said nothing.
+  - **Tool calls.** `tool.completed` carries the call's `effectId`, the Tool Gate's own `gate: { startedAt, endedAt }` for an MCP or HTTP call it ran (absent for sandbox and core-served tools), and `policy: { decision: "ask" | "deny", reason, approvedBy? }` when the Tenant's tool policy held or refused the call.
+  - **Flow HTTP stages.** A new event type, `node.completed` (`path`, `kind`, `key`, `iterations`, `effectId`, `status`, `durationMs`, `gate`), ends each HTTP stage and HTTP verifier that `node.started` began, and a tool stage the Runtime refused to run. Clients ignore event types they do not know.
+  - **Turns.** `turn.completed`, `turn.failed` and `turn.cancelled` carry `durationMs` (from the turn's start to its end, waits for a person included), `pausedMs` (how much of that it waited paused), `agentId` and `totals: { steps, tokens, costUsd }`, the same totals `GET /v1/tenant/usage?scope=turn` returns. A turn started before this release has no `durationMs`.
+
+- 7800358: **Each turn is one OpenTelemetry trace, projected from the session log (R7).** An operator could not see what a turn did or where its time went without grepping container logs. Now every turn is a trace with a span for each model call, tool call and egress tunnel, exported over OTLP to any collector, readable per turn from the Runtime, and joined to the trace of the app that started it. No protocol change.
+
+  - **Traces from the log.** A turn's end is its root span, `invoke_agent <agent>`; each model call is a `chat <model>` span, each tool call and flow HTTP stage an `execute_tool <tool>` span, each egress-gate tunnel a `CONNECT <host>` span, and each pause and answer a marker. A model or gate tool span is the gate's own start and end; usage and cost are the gate's (`nylorun.usage.mismatch` when the harness reported other numbers). Attribute names follow the OTel GenAI conventions at one pinned commit, recorded as `nylorun.semconv.genai` on the resource. Ids are derived from the log under a key the Tenant keeps (setting `trace.key`), so every export and read of a turn gives the same ids.
+  - **OTLP export, off until you set an endpoint.** With `OTEL_EXPORTER_OTLP_ENDPOINT` (or `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`) the Runtime posts OTLP/HTTP JSON from a replication slot of its own, `nylorun_trace_export`, in batches of up to 512 spans or every 2 s; `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES` work as usual. No turn waits for it. A collector that is down costs only its spans: after three retries a batch is dropped and logged as `trace_export_dropped`, and the slot moves on, so Postgres keeps no WAL for it. `nylorun start` passes these variables to the runtime container.
+  - **References by default.** Spans point at log events (`nylorun.event.cursor`) and carry no content unless you opt in per kind with `NYLORUN_TRACE_CONTENT` (`user`, `outputs`, `tool-results`, `errors`), or all of them with `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true`, each cut at 8 KiB. A span never carries a credential value, a prompt, a person's id, an identity header or an idempotency key.
+  - **`GET /v1/sessions/{id}/turns/{turnId}/trace`** answers a turn's spans as OTLP JSON, the same spans the exporter posts: look at a turn without a collector, or post it to one to backfill. Application keys, as the `/calls` reads. Host feature `traces`; `@nylorun/agents` adds `session.trace(turnId)`, and `@nylorun/core/contracts` `TurnTraceSchema`.
+  - **Trace context in and out.** A `traceparent` (and `tracestate`) on `POST /v1/sessions/{id}/commands`, an AG-UI run or an A2A message puts the turn in the caller's trace; `command.message` records it as `trace`. The turn hands its context on: to the harness in `TurnStart.trace`, to HTTP tools as `traceparent` beside `Idempotency-Key`, to MCP servers as `traceparent` on the call's requests, and to sandbox commands as `TRACEPARENT`.
+  - **Harness API** (additive): the `effect.intent` answer `execute` may carry the tool call's `traceparent`. `@nylorun/harness`: `HarnessExecutors.tool` takes it as a fourth argument (`ToolCallContext`).
+
+### Patch Changes
+
+- 17a97e9: **An artifact names the Environment whose disk it holds.** `ArtifactView` (and so `ArtifactListItem` in artifact pages) gains optional `environmentId`: set on the folder artifact that holds an Environment's disk versions (R2d step 3), absent on a session's or the Tenant's own artifacts. Before, such an artifact read as a Tenant-owned one with no way to tell whose disk it was.
+- b6214d9: Add opt-in artifact metadata pagination to `GET /v1/artifacts?limit=…`, shared
+  `ArtifactListItem`/`ArtifactPage` contracts and SDK `artifacts.page()` (default 50,
+  maximum 200). Hosts advertise `artifact-reads`. Pages order by creation time and
+  ID descending, filter by session, kind and labels, bind cursors to the Tenant and
+  filters, and reapply ownership and agent grants on each read. Legacy unpaged
+  responses remain unchanged. A Drizzle migration adds the creation-order index;
+  pages reuse the existing bounded read-only pool. Studio and every other Runtime
+  client can consume this public API without database access.
+- a708b27: **The example harness, on harness ids (R4.8).**
+
+  - **A new fixture marker.** `fixture:unoffered <name> <json>` makes the fixture model call a tool the turn does not offer, so a test can see that such a call runs nothing and the turn goes on. The other markers are unchanged.
+  - **The example harness.** `examples/harness-minimal` says `minimal` in `hello`, connects with its own token from `nylorun-operate harness token put minimal`, and runs beside ours: sessions on an Environment whose `harness` is `minimal` go to it. As a pod Environment's `image` it is the pod's harness.
+  - **A session's workspace is its own harness's.** Off a pod, a session's sandbox routes, `save_artifact` and turn-end export go only to a connection of the session's harness that serves workspaces. Before, a custom harness's session was served from our harness's workspace, which is not that harness's files. Without such a connection the request is refused. Sweeps and removes still go to ours.
+  - **The Harness API reference and guide.** `guides/HARNESS_API.md` covers every section a harness implements, with a walkthrough for building one.
+
+- dec813c: **A gateway shutdown no longer leaves an unhandled rejection.** When a keyed MCP or HTTP tool call was re-sent and the re-send's client went away before the gateway joined the running call, closing the gateway mid call rejected that join with nobody listening ("The gateway is shutting down"), which Node reports as an unhandled rejection. The gateway now handles it: the call still stops on shutdown and the next gateway sends it again under its key, as before.
+- 11c3b2a: **The Runtime's own tokens never reach a session's record from what a harness reports.** A harness's commands hold the egress token in their proxy variables, and a command that prints its environment, or a model that repeats it, would put that token into a tool result. Core now replaces every Nylorun-signed token before recording it:
+  - where it looks: tool and model outcomes, error messages, claimed sandbox events, and a turn's output, state and transcript edits;
+  - what a token is: a compact JWT whose `typ` starts with `nylorun-`, such as egress, run or host tokens;
+  - what replaces it: `[nylorun token redacted]`.
+
+  This applies to every harness, ours included. The leak showed when the example harness ran as a sandbox pod's image. Other values are unchanged.
+
+- 02c2d24: **The runtime image keeps the repository's new layout.** The Runtime's code moved to `runtime/server/` and the harness to `runtime/harness/` in the repository, and the image follows it: the entry point is `/app/runtime/server/dist/host/main.js` (was `/app/runtime/dist/host/main.js`). The image's `ENTRYPOINT`, `nylorun-operate` and the sandboxes service (`ghcr.io/nylorun/sandboxes`, released with the Runtime) use the new path; anything that runs a file under `/app/runtime/dist/` directly needs the new one.
+- a0cbca1: **Clearer wording when a definition runs your code.** The refusal for a code tool or a flow's tool stage, the `hooks were removed` error and `nylo endpoints` now say that the Runtime runs agents from their manifests alone, instead of that it runs no code of yours during a session. Only the message text changed; anything matching the old wording (for example `runs no code of yours during a session`) needs the new text.
+- Pin core to the tested release.
+- Pin harness to the tested release.
+- Updated dependencies [17a97e9]
+- Updated dependencies [b6214d9]
+- Updated dependencies [e917bd6]
+- Updated dependencies [5165451]
+- Updated dependencies [35e29b7]
+- Updated dependencies [e917bd6]
+- Updated dependencies [a0cbca1]
+- Updated dependencies [3013501]
+- Updated dependencies [6061a3a]
+- Updated dependencies [7d496e4]
+- Updated dependencies [81c783e]
+- Updated dependencies [7800358]
+- Updated dependencies
+  - @nylorun/core@0.20.0-beta
+  - @nylorun/harness@0.26.0-beta
+
 ## 0.23.0-beta
 
 ### Minor Changes

package/README.md

@@ -4,7 +4,7 @@ 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. 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
+A2A, Environments and their secrets, 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).
 
@@ -24,7 +24,7 @@ Restate and S2: `nylorun start` runs them, as a local Tenant, on a developer mac
 package is a library with no bin; its Host entry is `@nylorun/runtime/server`
 (`dist/host/main.js`), which requires `NYLORUN_DATABASE_URL`. For tests and
 ephemeral embeds, use `startEphemeralRuntime()` from `@nylorun/runtime/core`.
-See [MIGRATION.md](../MIGRATION.md).
+See [MIGRATION.md](../../guides/MIGRATION.md).
 
 A Runtime serves one **Tenant**: an installation is one Runtime with its own
 Postgres database, Restate and S2 basin, and two Tenants are two installations. No
@@ -45,7 +45,7 @@ database (`tenant_<id>` schemas), or by a pre-release build of one Tenant per da
 (`schema_version` tables), is refused: this release starts fresh on a new database. Restate runs one advance of a session at a time, delivers its wakes and holds
 its timers and the Tenant's sweep (Durable Session Execution), and journals no effect:
 checkpoints, effects, events and the outbox are the Session Store's, and a wake or a pod
-sandbox's reconcile is written to the outbox in the transaction that causes it, so a commit
+Environment's reconcile is written to the outbox in the transaction that causes it, so a commit
 never loses it ([src/CONTEXT.md](src/CONTEXT.md)); 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 Runtime API, the
@@ -66,7 +66,7 @@ core's process. A `harness` process needs `NYLORUN_HARNESS_URL`,
 `/harness`), answers `/health` on `127.0.0.1:4300`, and refuses to start with a
 database, Restate, keys or gates credential in its environment. A local Tenant
 runs it in the `harness` container, on a network with only the runtime and the
-gateway ([DEPLOYMENT.md](../DEPLOYMENT.md#the-harness-agent-turns-mcp-servers-and-workspaces)).
+gateway ([DEPLOYMENT.md](../../guides/DEPLOYMENT.md#the-harness-agent-turns-mcp-servers-and-workspaces)).
 
 The container is configured by its environment, which a local Tenant's Compose file
 sets: `NYLORUN_DATABASE_URL` (required), `NYLORUN_RESTATE_INGRESS_URL`,
@@ -91,7 +91,7 @@ Host) the registration replaces the deployment at that URL.
 `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
+boot ([DEPLOYMENT.md](../../guides/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 and token signing. Model, HTTP tool and
@@ -103,16 +103,16 @@ is refused with `409 run_stale`. A `gates` process needs only
 (`NYLORUN_GATES_LISTEN_HOST`, `NYLORUN_GATES_LISTEN_PORT`, default 4100, and
 `NYLORUN_GATES_ALLOWED_HOSTS`) and the Host's `tenant/` directory, which it
 never writes; it serves the database's one Tenant. A session's MCP servers and
-HTTP tools get their credentials from its attached vaults only: a `bearer` token
+HTTP tools get their credentials from the vault of its Environment only: a `bearer` token
 or a `headers` map per URL, sent to an MCP gateway instead when it has `via`,
 with the session owner in its identity header
-([DEPLOYMENT.md](../DEPLOYMENT.md#mcp-servers-and-http-tools)); the credential resolver is gone
+([DEPLOYMENT.md](../../guides/DEPLOYMENT.md#mcp-servers-and-http-tools)); the credential resolver is gone
 (protocol 10), and a process that still sets a `NYLORUN_RESOLVER_*` variable logs
 `resolver_removed` and ignores it. With `egress`
 (`--service gates,keys,egress`, for pod sandboxes) the same process runs
 egress-gate on `NYLORUN_EGRESS_LISTEN_HOST`:`NYLORUN_EGRESS_LISTEN_PORT`
 (default `0.0.0.0:4200`): a CONNECT proxy that admits a pod's egress token and
-tunnels only to the hosts its sandbox spec allows, on 443 or 80, never to a
+tunnels only to the hosts its Environment allows (`network.allowedHosts`), on 443 or 80, never to a
 private address. `NYLORUN_PACKING` (`combined` or `split`) is logged at startup.
 
 The Host has one listener, which serves both APIs. Host work runs on the machine
@@ -169,9 +169,12 @@ with `415 unsupported_media_type`, except an artifact upload (`POST /v1/artifact
 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
+([DEPLOYMENT.md](../../guides/DEPLOYMENT.md#calling-the-runtime-from-browsers-and-apps)). Missing or
 unsupported protocol → `426` before authentication, unless the request sends neither
-`Nylorun-Protocol` nor `Authorization` (the Host serves protocols 4 to 10; protocol 10 removes
+`Nylorun-Protocol` nor `Authorization` (the Host serves protocol 11 only; protocol 11 replaces
+sandbox resources, the Tenant's default sandbox, inline sandboxes and user and installation
+vaults with Environments, each one sandbox and one vault, under `/v1/environments`, and
+removes the Management API's vault routes, so a protocol 10 client gets `426`; protocol 10 removes
 the MCP OAuth connect, the vault's `oauth` credentials and the credential resolver, and adds
 `headers` credentials, `via` and the identity header, manifest v6 and
 `POST /v1/tenant/mcp/preview`; protocol 9 makes the Runtime API an OAuth 2.1 resource server: a missing or rejected credential is `401
@@ -182,8 +185,7 @@ the Admin API, and those old paths answer `404` with no alias; protocol 7 remove
 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}`,
-`/diff?from=` and `/zip`). Protocol 5 and later clients name no Tenant. A protocol 4 client's `Nylorun-Tenant` naming
-another Tenant (or malformed) and a Tenant that
+`/diff?from=` and `/zip`). Clients name no Tenant (since protocol 5). A Tenant that
 could not be opened → opaque `404` with identical body. A path or method no route serves is `404 Route not found`
 once the caller is known.
 
@@ -207,13 +209,13 @@ https://cdn.jsdelivr.net/npm/@nylorun/runtime@<version>/dist/management-openapi.
 
 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
+A2A), Environments, 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
+Tenant, Application keys, Models, Credential coverage, MCP servers, 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
+who may call it. Event streams are `text/event-stream` with an `itemSchema`. `runtime/server/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.
 
@@ -251,18 +253,22 @@ const runtime = await startEphemeralRuntime({
 
 The package's own tests run every Session Store on Postgres: `npm test` gives each
 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).
+the stack when it is down; see [CONTRIBUTING.md](../../CONTRIBUTING.md).
 
 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. The operator gives
-each URL a vault credential, previews an MCP server's tools (`nylorun mcp inspect`),
-and the manifest says which tools are enabled, need approval or are deferred
-([DEPLOYMENT.md](../DEPLOYMENT.md#mcp-servers-and-http-tools)). Model gateway
-and sandbox backend are Tenant configuration (vault / seed), not Host process
-env.
+so their URLs must be reachable from it, and remote MCP servers. Each URL gets a
+credential in the vault of the Environment a session names (`PUT
+/v1/environments/{id}/secrets/{name}`), the operator previews an MCP server's tools
+(`nylorun mcp inspect --environment <id>`),
+and the manifest says which tools are enabled or deferred
+([DEPLOYMENT.md](../../guides/DEPLOYMENT.md#mcp-servers-and-http-tools)). Which calls wait for a
+person, or are refused, is the Tenant's tool policy
+([DEPLOYMENT.md](../../guides/DEPLOYMENT.md#tool-policy)). Model gateway
+and sandbox backend are Tenant configuration (the Tenant's own vault, Tenant
+settings and seed), not Host process env.
 
 ## Session behaviour
 
@@ -273,11 +279,12 @@ definition/session APIs.
 Postgres transactions persist session checkpoints, command receipts, individual
 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.
+an epoch; a Worker that takes over after a crash marks in-flight model effects
+`uncertain`, and sends an interrupted MCP or HTTP tool call again with the same key (R5). Vault ciphertext needs that Tenant's own KEK.
 
-Agents that declare `.use(sandbox())` get Runtime-executed sandbox tools. The
-Tenant owns each sandbox; backend names are prefixed `nylorun-<tenant-id>-`.
+A session that names an Environment of kind `virtual` or `pod` gets Runtime-executed
+sandbox tools; the agent declares nothing. The Tenant owns each Environment; backend
+names are prefixed `nylorun-<tenant-id>-`.
 
 ## Local Project workflow
 
@@ -307,9 +314,53 @@ 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
+pages and opt-in session/history/Environment 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
+safe transaction order. `tool-calls` adds `GET /v1/sessions/{id}/calls/tool`: each tool call of
+the session from the effect journal, with its input, status and sends. 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).
+
+## Artifact pages
+
+Hosts advertising `artifact-reads` accept `GET /v1/artifacts?limit=50`, returning
+`{ artifacts: ArtifactListItem[], nextCursor: string | null }`. An explicit `limit`
+of 1–200 opts into paging; without it the existing `{ artifacts: ArtifactView[] }`
+list remains oldest first. Pages order by `(createdAt DESC, artifactId DESC)` and
+contain metadata only: id, kind, name, current content type, latest version number,
+optional session and labels, and creation/update timestamps. Use the existing
+artifact detail, numbered version and download APIs for history and bytes.
+
+Paged reads accept equality filters `sessionId`, `kind=file|folder` and repeated
+`label=key=value` (all labels must match). `sessionId` includes only that session's
+artifacts, excluding Tenant-owned artifacts. An application key acting as itself
+sees every artifact; subjects and issuer tokens see only artifacts of their owned
+sessions and permitted agents. Missing or inaccessible session filters return 404.
+Management keys cannot use this Runtime API route.
+
+Send `nextCursor` as `cursor` with the same normalized filters until it is null.
+Cursors are bound to the Tenant, route and filters; invalid or mismatched cursors
+return 400 (`cursor_invalid` or `cursor_mismatch`). Each page reapplies current
+authorization and is an independent read: it is not a frozen snapshot. Newer
+inserts require a fresh traversal; deleted rows disappear and versions/metadata
+may change between pages. Creation time and ID remain the paging position.
+
+These pages reuse the separate bounded, read-only Drizzle pool (four connections,
+two-second statement timeout). Migration `0023_artifact_pages` adds only the
+creation-order index; the existing session index also serves session pages in
+reverse order. No data backfill, protocol bump or direct client database access is
+required. Studio can discover `artifact-reads` through `/health` before enabling
+a tenant-wide table; `@nylorun/agents` exposes the same API as `artifacts.page()`.
+
+[Recorded query plans](docs/artifact-pages-evidence.json) use a disposable local
+Postgres 17 fixture: the public SDK drained 10,006 artifacts in 201 pages of at
+most 50 rows, without gaps or duplicates, in 796 ms. First/deep page queries used
+backward index scans with a tuple index condition on the deep page (0.014/0.028 ms).
+These are fixture timings, not production throughput estimates. Reproduce after
+building dependencies with:
+
+```sh
+ARTIFACT_READS_EVIDENCE="$PWD/runtime/server/docs/artifact-pages-evidence.json" \
+  npm test --workspace @nylorun/runtime -- test/http/artifact-pages.test.ts
+```

package/dist/adapters/execution/restate.js

@@ -314,7 +314,7 @@ export class RestateExecution {
                     if ((await ctx.get(`at:${input.timer}`)) !== input.at)
                         return;
                     ctx.clear(`at:${input.timer}`);
-                    await runSandbox(ctx, input.timer === "retry" ? "reconcile" : input.timer);
+                    await runSandbox(ctx, input.timer === "idle" ? "idle" : "reconcile");
                 },
             },
             options: serviceOptions,

package/dist/adapters/replication/pgoutput.d.ts

@@ -13,6 +13,8 @@ export interface PgoutputSourceOptions {
     publication?: string;
     /** The schema of the record tables. Default `nylorun_streams`. */
     schema?: string;
+    /** The connections' `application_name`. Default `nylorun-stream-relay`. */
+    applicationName?: string;
     /** Wait between attempts to take the slot. Default 5 s. */
     retryMs?: number;
     log?: (message: string, fields?: Record<string, unknown>) => void;

package/dist/adapters/replication/pgoutput.js

@@ -1,7 +1,9 @@
 /**
  * The stream relay's change source on Postgres logical replication (Durable Streams §7.1,
  * §7.4, §7.6): a persistent `pgoutput` slot on the `nylorun_stream_relay` publication, read
- * with `pg-logical-replication`. The only file importing it (with `pg`, which it needs).
+ * with `pg-logical-replication`. The only file importing it (with `pg`, which it needs). The
+ * trace projector (R7.2) reads the same publication from a slot of its own
+ * (`traces/projector.ts`); for it a fresh slot means nothing to reconcile.
  *
  * - **One reader per slot.** Postgres lets one connection hold a slot, so every Runtime
  *   process can run a source and exactly one is active; the others retry every few seconds
@@ -25,12 +27,13 @@ export function createPgoutputSource(options) {
     const publication = options.publication ?? "nylorun_stream_relay";
     const schema = options.schema ?? "nylorun_streams";
     const retryMs = options.retryMs ?? 5000;
+    const applicationName = options.applicationName ?? "nylorun-stream-relay";
     const { tenantId } = options;
     const log = options.log ?? (() => { });
     const pool = new pg.Pool({
         connectionString: options.connectionString,
         max: 2,
-        application_name: "nylorun-stream-relay",
+        application_name: applicationName,
     });
     let service;
     let stopped = false;
@@ -72,7 +75,7 @@ export function createPgoutputSource(options) {
         // `stop()` during `prepareSlot` had no service to stop: do not start one it cannot.
         if (stopped)
             return;
-        const current = new LogicalReplicationService({ connectionString: options.connectionString, application_name: "nylorun-stream-relay" }, { acknowledge: { auto: false, timeoutSeconds: 0 }, flowControl: { enabled: false } });
+        const current = new LogicalReplicationService({ connectionString: options.connectionString, application_name: applicationName }, { acknowledge: { auto: false, timeoutSeconds: 0 }, flowControl: { enabled: false } });
         service = current;
         let decoding;
         current.on("start", () => handlers.onActive({ fresh }));

package/dist/adapters/sandbox/local.d.ts

@@ -1,4 +1,4 @@
-import type { SandboxBackend } from "../../sandbox/types.js";
+import type { ExecRequest, ExecResult, SandboxBackend } from "../../sandbox/types.js";
 export interface LocalBackendOptions {
     /** Default `/workspace`. */
     readonly workspace?: string;
@@ -6,5 +6,13 @@ export interface LocalBackendOptions {
     readonly proxyEnv?: () => Readonly<Record<string, string>>;
     /** The base environment of commands (the engine's allowlisted one); `NYLORUN_*` is dropped. */
     readonly env: Readonly<Record<string, string | undefined>>;
+    /** The engine's `/harness` on the same volume, a disk root of its versions (R2d step 3). */
+    readonly harnessRoot?: string;
 }
+/**
+ * How the pod runs a command: `/bin/sh -c` in its own process group, with the base environment,
+ * the request's variables and the proxy of the moment. The sandbox tools and the disk's setup
+ * (`harness/setup.ts`) both run commands this way.
+ */
+export declare function localExec(options: LocalBackendOptions): (request: ExecRequest, signal: AbortSignal) => Promise<ExecResult>;
 export declare function localBackend(options: LocalBackendOptions): SandboxBackend;

package/dist/adapters/sandbox/local.js

@@ -49,10 +49,14 @@ function collector() {
         },
     };
 }
-export function localBackend(options) {
-    const workspace = options.workspace ?? SANDBOX_WORKSPACE;
-    const env = baseEnv(options.env, workspace);
-    const exec = (request, signal) => new Promise((resolve, reject) => {
+/**
+ * How the pod runs a command: `/bin/sh -c` in its own process group, with the base environment,
+ * the request's variables and the proxy of the moment. The sandbox tools and the disk's setup
+ * (`harness/setup.ts`) both run commands this way.
+ */
+export function localExec(options) {
+    const env = baseEnv(options.env, options.workspace ?? SANDBOX_WORKSPACE);
+    return (request, signal) => new Promise((resolve, reject) => {
         if (signal.aborted)
             return reject(signal.reason ?? new Error("Turn cancelled"));
         const child = spawn("/bin/sh", ["-c", request.command], {
@@ -102,10 +106,18 @@ export function localBackend(options) {
             });
         });
     });
+}
+export function localBackend(options) {
+    const workspace = options.workspace ?? SANDBOX_WORKSPACE;
+    const exec = localExec(options);
     const missing = (error) => error?.code === "ENOENT" || error?.code === "ENOTDIR";
     const handle = {
         workspace,
         exec,
+        diskRoots: {
+            workspace,
+            ...(options.harnessRoot === undefined ? {} : { harness: options.harnessRoot }),
+        },
         async readFile(path) {
             try {
                 return await readFile(path, "utf8");

package/dist/adapters/sandbox/virtual.js

@@ -1,5 +1,6 @@
 /**
- * Virtual backend: an emulated bash with a virtual filesystem, running in the Runtime process.
+ * Virtual backend: an emulated bash with a virtual filesystem, running in the harness's process
+ * (the harness container, or the Runtime process with NYLORUN_HARNESS=in-process).
  * `/workspace` is backed by a host directory so files survive stop and Runtime restarts.
  * It is not a VM boundary; it exists so the first run and CI work on any machine.
  */
@@ -67,6 +68,8 @@ export function virtualBackend(options) {
                 ...(network ? { network } : {}),
             });
             return {
+                // A virtual workspace's disk is its host directory: `/workspace` only.
+                diskRoots: { workspace: root },
                 async exec(request, signal) {
                     const controller = new AbortController();
                     let timedOut = false;

package/dist/api/a2a/endpoint.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { readText } from "../http/body.js";
-import { tenantRoute } from "../http/define.js";
+import { TraceHeaders, tenantRoute } from "../http/define.js";
+import { traceContextOf } from "../../traces/ids.js";
 import { jsonResponse } from "../http/respond.js";
 import { a2aCall, a2aCard } from "./routes.js";
 const A2A_SPECIFICATION = {
@@ -63,6 +64,7 @@ export function a2aRoutes(api) {
                 "A2A-Version": z.string().optional().meta({ description: "Or the `A2A-Version` header: `1.0`" }),
             }),
             body: { required: true, content: { "application/json": { schema: JsonRpcRequest } } },
+            headers: TraceHeaders,
         },
         responses: {
             200: {
@@ -73,9 +75,11 @@ export function a2aRoutes(api) {
     }, async (c) => {
         const scope = c.get("scope");
         const version = c.env.incoming.headers["a2a-version"];
+        const trace = traceContextOf(c.req.raw.headers);
         return jsonResponse(200, await a2aCall(c.env.tenant, scope, c.req.param("agentId"), {
             body: () => readText(c.req.raw),
             version: typeof version === "string" ? version : (c.req.query("A2A-Version") ?? null),
+            ...(trace ? { trace } : {}),
         }, c.env.outgoing));
     });
 }

package/dist/api/a2a/routes.d.ts

@@ -1,5 +1,6 @@
 import type { ServerResponse } from "node:http";
 import { type AuthScope, type TenantContext } from "../../tenant/context.js";
+import type { TraceContext } from "../../traces/ids.js";
 /**
  * How long a blocking `SendMessage` waits for the task to end or ask for input. After it, the
  * task is returned `WORKING` and keeps running; the caller polls `GetTask`.
@@ -16,4 +17,5 @@ export declare function a2aCard(ctx: TenantContext, scope: AuthScope, agentId: s
 export declare function a2aCall(ctx: TenantContext, scope: AuthScope, agentId: string, input: {
     body: () => Promise<string>;
     version: string | null;
+    trace?: TraceContext;
 }, response: ServerResponse): Promise<unknown>;

package/dist/api/a2a/routes.js

@@ -50,7 +50,7 @@ export async function a2aCall(ctx, scope, agentId, input, response) {
     // A blocking call stops waiting when the caller hangs up; the task keeps running.
     const hangup = new AbortController();
     response.on("close", () => hangup.abort());
-    const caller = { ctx, scope, access, agentId };
+    const caller = { ctx, scope, access, agentId, ...(input.trace ? { trace: input.trace } : {}) };
     const { id } = envelope.request;
     try {
         checkVersion(input.version);
@@ -137,7 +137,7 @@ async function run(caller, sessionId, input,
 /** The error for a `409` conflict: the session is busy or no longer waiting. */
 conflict) {
     try {
-        const accepted = (await command(caller.ctx, sessionId, SessionCommandSchema.parse(input), caller.scope));
+        const accepted = (await command(caller.ctx, sessionId, SessionCommandSchema.parse(input), caller.scope, caller.trace ? { trace: caller.trace } : {}));
         return { turnId: accepted.turnId, cursor: accepted.cursor };
     }
     catch (error) {

package/dist/api/a2a/tasks.js

@@ -97,7 +97,8 @@ export function historyOf(events, contextId, taskId) {
                 add(clientMessageId(event), "ROLE_USER", [valuePart(payload.value)]);
                 break;
             case "message.assistant":
-                // Agents used as tools speak inside the turn; only the agent's own words are history.
+                // Agents used as tools speak inside the turn; only the agent's own words are history. A
+                // step that said nothing (`text: ""`, R7.1) is none.
                 if (!payload.agent && typeof payload.text === "string" && payload.text.trim() !== "")
                     add(event.eventId, "ROLE_AGENT", [{ text: payload.text }]);
                 break;