@nylorun/runtime 0.28.0-beta → 0.29.0-beta

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.29.0-beta
+
+### Minor Changes
+
+- eeb6294: Session usage as one ledger (protocol 18). The usage ledger keeps each model call's cost by token kind (uncached input, cache read, cache write, output) at the prices the adapter applied (migration 0037). For a protocol 18 client, `GET /v1/sessions/{id}/calls/model` returns each call's `startedAt`, `endedAt` and `usage.costSplit` (null for a call recorded before), and `GET /v1/sessions/{id}/usage` adds `costSplit` with `splitCalls`, and the calls' durations added up as `modelTimeMs` with `timedCalls`. A protocol 16 or 17 client reads usage as before. Studio's Usage tab is rebuilt on them: a Session card with one tokens bar and a ledger of tokens and cost by kind adding up to a total row, then the model calls grouped by turn with the same columns (cached, uncached, output, total, time, cost), and a row menu whose View event opens the call's event in the Events tab.
+
+### Patch Changes
+
+- ed08ba8: Credential failures name the session's Agent, not its Environment: an HTTP tool's `http.credential` failure says "The session's Agent holds no credential '…' for …", and an MCP server's `credential_rejected` says the credential came from, or is missing in, the session's Agent.
+- ed08ba8: A flow's HTTP stage or HTTP verifier, and an HTTP tool of an agent the harness section embeds (a flow's `agents`, or an agent used as a tool), now has its `credential` checked when the manifest is saved, as an agent's own HTTP tool has: it must name a `bearer` or `headers` slot of `runtime.secrets` bound to its URL, or the save is `422 manifest_inconsistent` naming it (`harness.root stage "refund" http.credential "checks" is not a secret slot in runtime.secrets`). Before, such a manifest saved and each call failed at run time with `http.credential`.
+- ed08ba8: The Runtime API's Agent manifests tag no longer says a save changes no Agent: a save moves every Agent that tracks the manifest to the new version, and a pinned one stays.
+- ed08ba8: Public text names no internal roadmap codes: the OpenAPI documents' descriptions, the type comments of `@nylorun/core`, `@nylorun/agents` and `@nylorun/admin`, and the CLI's help, README and generated compose file. A Runtime test fails when either OpenAPI document names one.
+- ed08ba8: Webhook URLs name the Runtime's public URL. A trigger's `webhookUrl` is at `NYLORUN_PUBLIC_URL`, else the origin the request reached, so behind a reverse proxy that rewrites `Host` to `localhost:<port>` it is the proxy's URL, not `http://localhost:<port>`; the Runtime API's `401` challenges name it too. `nylorun start` passes `NYLORUN_PUBLIC_URL` from its shell to the runtime container (default `http://localhost:<port>`).
+- ed08ba8: The tool policy's documentation matches how rules match: `tool` is the tool's identity (an MCP tool's own name on its `server`, or an HTTP tool's declared name), never the model-facing `server__tool`, which is refused; `agent` is the agent manifest's name, or the id of an agent used as a tool or of a flow's agent. `PUT /v1/tenant/tool-policy` describes each selector, and `GET` documents its `409` for a stored rule it cannot apply.
+- ed08ba8: `POST /v1/webhooks/{endpointId}` takes no credential and ignores one that is sent: a delivery with an `Authorization` header is no longer checked against the Tenant's keys, since its Standard Webhooks signature is its grant. The OpenAPI document says so: `security: []`, no `Nylorun-*` headers, and `webhook-id`, `webhook-timestamp` and `webhook-signature` required.
+- Pin core to the tested release.
+- Pin harness to the tested release.
+- Updated dependencies [ed08ba8]
+- Updated dependencies [ed08ba8]
+- Updated dependencies [ed08ba8]
+- Updated dependencies [eeb6294]
+- Updated dependencies [ed08ba8]
+- Updated dependencies
+  - @nylorun/core@0.25.0-beta
+  - @nylorun/harness@0.29.1-beta
+
 ## 0.28.0-beta
 
 ### Minor Changes
@@ -12,7 +38,7 @@
 
 - 1ded443: Track T3, Agents that evolve: an Agent moves between versions of its manifest in place, with its id, disk, vault and sessions. `PUT /v1/agents/{id}` with another version moves it (`?dryRun=true` answers the plan, `AgentMovePlan`), and saving a manifest moves every Agent that tracks it. A harness-only change applies at once; a runtime change a pod applies only when it starts (image, resources, network, setup, files) leaves the Agent outdated (`targetVersion`, `waitingFor: "start"`) until its pod's next start, on the same volume; a version that adds a required secret waits for its value (`waitingFor: "secrets"`, state `input_required`). Its manifest's name, kind, harness and storage are fixed: `409 agent_fixed_field` replaces `409 agent_upgrade_unavailable`. Only secrets that fill a slot of the running version are used; others stay in the vault, dormant. New events `agent.outdated` and `agent.version_changed`, `GET /v1/agents?outdated=true`, and the save plan's `moves` and `agents_move` warning. Migration 0033 adds the Agent's target and failed versions and its start check.
 - 76dcd11: Track T3, the next start and its check: a pod Agent's start on a new version is checked until the new pod's harness joins (`startCheck` on the Agent). A failed setup, a failed pod, or a start slower than the Host's `tenant.upgradeStartMs` (10 minutes) takes the Agent back to the version it ran, its definition and not its disk, records `agent.start_failed`, and names the version `failedVersion` (state `failing`), which a tracking Agent does not move to again. A new version's setup runs on the same volume when its commands or files changed (`setupHash` in the setup plan and the volume's marker). While a pod waits to start on a new version it idles at most `tenant.upgradeIdleMs` (1 minute). `POST /v1/agents/{id}/restart` applies a pending version now; `retry: true` tries the failed version again.
-- 4fa160d: Agent memory, storage and API (track T5, D72). An agent manifest's `harness.memory` (`access`: `read_write` or `read_only`; `instructions`, at most 4,096 characters) turns on the Agent's memory: Markdown files under `/memories` it keeps across sessions, wakes and upgrades. The Runtime keeps them in Postgres (`memories`, `memory_versions`, migration 0036) with a version per change and who made it. `GET /v1/agents/{id}/memories` lists them (`pathPrefix`), `GET`, `PUT` (whole content, with an optional `contentSha256` precondition: `409 memory_conflict`) and `DELETE /v1/agents/{id}/memories/{path}` read, write and delete one (or a folder), and `GET /v1/agents/{id}/memory_versions` and `.../memory_versions/{versionId}` page the versions. A fork copies the memories (the fork plan adds `memories`); a delete removes them. `@nylorun/core` adds `memoryPathOf`, `memoryDescriptionOf` and the memory contracts; new Runtime limits `memoryBytes` (100 KB) and `memoriesPerAgent` (10,000); new error code `memory_conflict`. The SDK adds `client.agents.memories`; the CLI adds `nylorun agents memories ls|cat|put|rm|versions`. The model's `memory` tool arrives in the next steps of T5.
+- 4fa160d: Agent memory, storage and API (track T5, D72). An agent manifest's `harness.memory` (`access`: `read_write` or `read_only`; `instructions`, at most 4,096 characters) turns on the Agent's memory: Markdown files under `/memories` it keeps across sessions, wakes and upgrades. The Runtime keeps them in Postgres (`memories`, `memory_versions`, migration 0036) with a version per change and who made it. `GET /v1/agents/{id}/memories` lists them (`pathPrefix`), `GET`, `PUT` (whole content, with an optional `contentSha256` precondition: `409 memory_conflict`) and `DELETE /v1/agents/{id}/memories/{path}` read, write and delete one (or a folder), and `GET /v1/agents/{id}/memory_versions` and `.../memory_versions/{versionId}` page the versions. A fork copies the memories (the fork plan adds `memories`); a delete removes them. `@nylorun/core` adds `memoryPathOf`, `memoryDescriptionOf` and the memory contracts; new Runtime limits `memoryBytes` (100 KiB) and `memoriesPerAgent` (10,000); new error code `memory_conflict`. The SDK adds `client.agents.memories`; the CLI adds `nylorun agents memories ls|cat|put|rm|versions`. The model's `memory` tool arrives in the next steps of T5.
 - 9fed948: The `memory` tool's calls (track T5, D72). A new effect target, `{kind: "runtime", operation: "memory"}` (additive on Harness API 5), carries Anthropic's memory tool input (`command`: `view`, `create`, `str_replace`, `insert`, `delete`, `rename`, and its parameters); core serves it in the intent's own transaction, so a replayed turn applies a write once. A malformed call fails with text for the model and changes nothing; a write from a `read_only` agent or a sub-agent is `memory.forbidden`. Each write is a memory version naming the turn's manifest version, session, turn and the trigger run that started the turn, with a new session event `memory.updated` and Agent event `agent.memory_updated`. `turn.start.memory` (`TurnMemorySchema`) carries the Agent's memory access, instructions and the index a harness pins, newest first, within the new Runtime limits `memoryIndexLines` (200) and `memoryIndexBytes` (25 KiB).
 - ffeb3bb: `schedule_wake` (track T4, D77). An agent manifest's `runtime.selfWake: true` offers the agent `schedule_wake`: `{in | at, note}` books its session's next turn, replacing the booking before, and `{cancel: true}` removes it. The Runtime serves the call in its own transaction (a new effect target, `{kind: "runtime", operation: "schedule_wake"}`, additive on Harness API 5; `turn.start.agent.selfWake` tells a harness to offer it), so a replayed turn books once. The booking fires as a trigger run of kind `wake`, its note the turn's message with `cause.kind: "self"`. New session events `wake.booked` and `wake.cancelled`, tool call kind `runtime`, and Runtime limits `wakeMaxAheadMs` and `wakeNoteChars`.
 - 9e60e40: Protocol 17, a queue per session (track T4, D76). A message sent while the session's turn runs or waits is queued (`{status: "queued", queuedMessageId, position}`, `message.queued`) and starts the next turn when this one ends, with every queued message, each its own user message (`queue.taken`); a cancel ends the turn, not the queue. `delivery: "reject"` keeps the refusal, now `409 session_busy`, and a protocol 16 client's messages default to it, so the Host serves protocol 16 and 17. The queue holds at most the Runtime limit `sessionQueuedMessages` (`429 queue_full`), and session reads count `queuedMessages`. Our engine takes `{kind: "messages", messages}` as a turn's input. The SDK's `input` and `inputParts` take `delivery`, and the CLI's `sessions send` takes `--reject-if-busy`. See MIGRATION.md.

package/README.md

@@ -295,7 +295,7 @@ 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 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.
+`uncertain`, and sends an interrupted MCP or HTTP tool call again with the same key. Vault ciphertext needs that Tenant's own KEK.
 
 A session that names an Environment of kind `virtual` or `pod` gets a sandbox, its spec pinned
 on the session: our harness offers the sandbox tools and `save_artifact` and writes their notes

package/dist/api/components.d.ts

@@ -13964,6 +13964,8 @@ export declare const ModelCall: z.ZodObject<{
     provider: z.ZodNullable<z.ZodString>;
     model: z.ZodNullable<z.ZodString>;
     at: z.ZodString;
+    startedAt: z.ZodNullable<z.ZodString>;
+    endedAt: z.ZodNullable<z.ZodString>;
     outcome: z.ZodEnum<{
         completed: "completed";
         failed: "failed";
@@ -13979,6 +13981,12 @@ export declare const ModelCall: z.ZodObject<{
         duplicate: z.ZodBoolean;
         tokensReported: z.ZodNullable<z.ZodBoolean>;
         costKnown: z.ZodNullable<z.ZodBoolean>;
+        costSplit: z.ZodNullable<z.ZodObject<{
+            input: z.ZodNumber;
+            cacheRead: z.ZodNumber;
+            cacheWrite: z.ZodNumber;
+            output: z.ZodNumber;
+        }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const SessionPage: z.ZodObject<{
@@ -19499,6 +19507,15 @@ export declare const SessionUsageTotals: z.ZodObject<{
     unpricedCalls: z.ZodNumber;
     unreportedCalls: z.ZodNumber;
     unknownQualityCalls: z.ZodNumber;
+    costSplit: z.ZodObject<{
+        input: z.ZodNumber;
+        cacheRead: z.ZodNumber;
+        cacheWrite: z.ZodNumber;
+        output: z.ZodNumber;
+    }, z.core.$strict>;
+    splitCalls: z.ZodNumber;
+    modelTimeMs: z.ZodNumber;
+    timedCalls: z.ZodNumber;
 }, z.core.$strict>;
 export declare const ModelCallsPage: z.ZodObject<{
     nextCursor: z.ZodNullable<z.ZodString>;
@@ -19512,6 +19529,8 @@ export declare const ModelCallsPage: z.ZodObject<{
         provider: z.ZodNullable<z.ZodString>;
         model: z.ZodNullable<z.ZodString>;
         at: z.ZodString;
+        startedAt: z.ZodNullable<z.ZodString>;
+        endedAt: z.ZodNullable<z.ZodString>;
         outcome: z.ZodEnum<{
             completed: "completed";
             failed: "failed";
@@ -19527,6 +19546,12 @@ export declare const ModelCallsPage: z.ZodObject<{
             duplicate: z.ZodBoolean;
             tokensReported: z.ZodNullable<z.ZodBoolean>;
             costKnown: z.ZodNullable<z.ZodBoolean>;
+            costSplit: z.ZodNullable<z.ZodObject<{
+                input: z.ZodNumber;
+                cacheRead: z.ZodNumber;
+                cacheWrite: z.ZodNumber;
+                output: z.ZodNumber;
+            }, z.core.$strict>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -19543,6 +19568,8 @@ export declare const ModelCallExportPage: z.ZodObject<{
         provider: z.ZodNullable<z.ZodString>;
         model: z.ZodNullable<z.ZodString>;
         at: z.ZodString;
+        startedAt: z.ZodNullable<z.ZodString>;
+        endedAt: z.ZodNullable<z.ZodString>;
         outcome: z.ZodEnum<{
             completed: "completed";
             failed: "failed";
@@ -19558,6 +19585,12 @@ export declare const ModelCallExportPage: z.ZodObject<{
             duplicate: z.ZodBoolean;
             tokensReported: z.ZodNullable<z.ZodBoolean>;
             costKnown: z.ZodNullable<z.ZodBoolean>;
+            costSplit: z.ZodNullable<z.ZodObject<{
+                input: z.ZodNumber;
+                cacheRead: z.ZodNumber;
+                cacheWrite: z.ZodNumber;
+                output: z.ZodNumber;
+            }, z.core.$strict>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;

package/dist/api/http/define.d.ts

@@ -24,6 +24,10 @@ import type { TenantEnv } from "./app.js";
  */
 export type Credential = "application" | "subject" | "management" | "token";
 export interface RouteAccess {
+    /**
+     * The credentials the route takes. None (with `anonymous`): the route takes no credential and
+     * ignores one that is sent, as a webhook delivery, whose signature is its grant.
+     */
     readonly credentials: readonly Credential[];
     /** The subject scopes that reach the route: any one of them, none (`never`), or all (`any`). */
     readonly scopes: readonly SubjectScope[] | "never" | "any";

package/dist/api/http/define.js

@@ -63,6 +63,11 @@ export function declaredRoute(method, segments) {
             (segment.startsWith("{") && segments[index] !== "")))?.access;
 }
 function authenticated(access) {
+    if (access.credentials.length === 0)
+        return async (c, next) => {
+            c.set("scope", { kind: "anonymous" });
+            await next();
+        };
     return async (c, next) => {
         const keys = keyAccess(access);
         const scope = await authenticateCaller(c, access.anonymous === true, keys);
@@ -82,9 +87,12 @@ export const TraceHeaders = z.object({
 export function tenantRoute(api, access, route, handler) {
     const takes = (credential) => access.credentials.includes(credential);
     const schemes = [...new Set(access.credentials.map((credential) => SCHEMES[credential]))];
+    // A route that takes no credential is called by others than Nylorun's clients: it documents
+    // neither a credential nor `Nylorun-*` headers.
+    const open = access.credentials.length === 0;
     const protocol = z.string().meta({ description: `The protocol version, \`${PROTOCOL_VERSION}\`` });
     const headers = z.object({
-        "Nylorun-Protocol": access.unversioned ? protocol.optional() : protocol,
+        ...(open ? {} : { "Nylorun-Protocol": access.unversioned ? protocol.optional() : protocol }),
         ...(takes("subject")
             ? {
                 "Nylorun-Subject": z
@@ -100,11 +108,10 @@ export function tenantRoute(api, access, route, handler) {
     });
     api.openAPIRegistry.registerPath({
         ...route,
-        // `{}`: no credential needed (OpenAPI's optional security).
-        security: [
-            ...schemes.map((scheme) => ({ [scheme]: [] })),
-            ...(access.anonymous ? [{}] : []),
-        ],
+        // `{}`: no credential needed (OpenAPI's optional security); none at all: `[]`.
+        security: open
+            ? []
+            : [...schemes.map((scheme) => ({ [scheme]: [] })), ...(access.anonymous ? [{}] : [])],
         // A route's own headers (`traceparent`, R7.4) beside the common ones.
         request: {
             ...route.request,
@@ -115,9 +122,13 @@ export function tenantRoute(api, access, route, handler) {
             401: rejected(takes("token")
                 ? "No credential (`credential_required`), one the Tenant does not accept (`credential_invalid`), a token that expired (`token_expired`), or a token whose issuer's keys cannot be fetched now (`issuer_unavailable`). `WWW-Authenticate: Bearer` names the protected resource metadata (`resource_metadata`)"
                 : "No credential (`credential_required`), or one the Tenant does not accept (`credential_invalid`), with a `WWW-Authenticate: Bearer` challenge"),
-            403: rejected(takes("management")
-                ? "Not allowed for this credential, a key of the other API (`key_role_mismatch`), a key from a browser (`origin_rejected`) or a management key acting for a subject"
-                : "Not allowed for this credential or subject scope (`scope_required`; a token also gets `WWW-Authenticate: Bearer error=\"insufficient_scope\"` and the scope), a key of the other API (`key_role_mismatch`), or an application key from a browser (`origin_rejected`)"),
+            ...(open
+                ? {}
+                : {
+                    403: rejected(takes("management")
+                        ? "Not allowed for this credential, a key of the other API (`key_role_mismatch`), a key from a browser (`origin_rejected`) or a management key acting for a subject"
+                        : "Not allowed for this credential or subject scope (`scope_required`; a token also gets `WWW-Authenticate: Bearer error=\"insufficient_scope\"` and the scope), a key of the other API (`key_role_mismatch`), or an application key from a browser (`origin_rejected`)"),
+                }),
             404: rejected("Not found (`not_found`)"),
             426: { description: "`Nylorun-Protocol` missing or unsupported", content: { "application/json": { schema: ProtocolRejected } } },
             503: rejected("The Tenant's storage or streams are unavailable"),

package/dist/api/http/routes/agent-manifests.d.ts

@@ -1,7 +1,7 @@
 /**
  * Agent manifests (`/v1/agent-manifests/**`, protocol 16): save, read, list and delete the named,
  * versioned documents Agents are made from, each with a harness and a runtime section. A save
- * never changes an Agent. Reading needs `agents:read` (or a write scope), saving and deleting
+ * moves every Agent that tracks the manifest to the new version; a pinned one stays. Reading needs `agents:read` (or a write scope), saving and deleting
  * `agent-manifests:write`, from any client (Q12). A token caller reaches none: a manifest holds
  * an agent's instructions, tools and servers.
  */

package/dist/api/http/routes/agent-manifests.js

@@ -59,7 +59,7 @@ export function agentManifestRoutes(api) {
         path: "/v1/agent-manifests/{name}",
         tags: ["Agent manifests"],
         summary: "Save an agent manifest",
-        description: "Saves the manifest as its next version, or answers the latest unchanged when nothing differs. Every Agent that tracks the manifest moves to the new version (track T3): at once, at its pod's next start for a runtime change a pod applies only when it starts, or once a required secret the version adds is set; a pinned one stays, and so does one whose kind, harness or storage the version changes (`agents_behind`). The Runtime checks the harness and runtime sections against each other: a custom harness needs a pod with an image, every credential the harness names is a declared slot of the right type, and the runtime's kind gives the loop the sandbox it needs; every gap is named in one `422 manifest_inconsistent` (`details.gaps`). `If-Match: <version>` refuses the save with `412 manifest_changed` when the latest version is no longer the one you read (`0` for a manifest that does not exist yet). With `?dryRun=true` the answer is the plan: the changes by section, every reason a save would be refused (`errors`, the gaps first), warnings, the Agents it would move (`moves`) and how many stay on older versions (`behind`); nothing is saved. Clients compose the authoring files and drop their `$schema` before they send one document.",
+        description: "Saves the manifest as its next version, or answers the latest unchanged when nothing differs. Every Agent that tracks the manifest moves to the new version: at once, at its pod's next start for a runtime change a pod applies only when it starts, or once a required secret the version adds is set; a pinned one stays, and so does one whose kind, harness or storage the version changes (`agents_behind`). The Runtime checks the harness and runtime sections against each other: a custom harness needs a pod with an image, every credential the harness names is a declared slot of the right type, and the runtime's kind gives the loop the sandbox it needs; every gap is named in one `422 manifest_inconsistent` (`details.gaps`). `If-Match: <version>` refuses the save with `412 manifest_changed` when the latest version is no longer the one you read (`0` for a manifest that does not exist yet). With `?dryRun=true` the answer is the plan: the changes by section, every reason a save would be refused (`errors`, the gaps first), warnings, the Agents it would move (`moves`) and how many stay on older versions (`behind`); nothing is saved. Clients compose the authoring files and drop their `$schema` before they send one document.",
         request: {
             params: namePath,
             query: z.object({

package/dist/api/http/routes/agents.js

@@ -72,7 +72,7 @@ export function agentRoutes(api) {
         path: "/v1/agents",
         tags: ["Agents"],
         summary: "List Agents",
-        description: "Every Agent with all the labels asked for, in `state`, made from `manifest` and `outdated` (moving to another version, track T3) when given, by id. A token caller sees only the Agents its grants reach, and a caller acting for a person only that person's sessions on each. `limit` opts into pages.",
+        description: "Every Agent with all the labels asked for, in `state`, made from `manifest` and `outdated` (moving to another version) when given, by id. A token caller sees only the Agents its grants reach, and a caller acting for a person only that person's sessions on each. `limit` opts into pages.",
         request: {
             query: pageQuery.extend({
                 label: z
@@ -122,7 +122,7 @@ export function agentRoutes(api) {
         path: "/v1/agents/{agentId}",
         tags: ["Agents"],
         summary: "Create, find or move an Agent",
-        description: "Creates the Agent, its vault and its compute from a saved agent manifest, within the Tenant's limits, or answers the one with this id, so get-or-create is one call. `manifest: \"name\"` records that it tracks the manifest (its latest version, and each version saved later) and `\"name@n\"` that it is pinned; the version it runs is `resolvedVersion`. On an existing one, labels replace, `owner` sets or (with `null`) clears the owner guard, and `manifest` moves it (track T3) with its id, disk, vault and sessions: a harness-only change applies at once (each session's next turn runs it), a runtime change of a pod at its next start (`targetVersion`, `waitingFor: start`), and a version that adds a required secret once a value is set (`waitingFor: secrets`). Its manifest's name, kind, harness and storage are fixed (`409 agent_fixed_field`): fork it to change them. `?dryRun=true` answers the move's plan and changes nothing. Creating an Agent opens no session (D71). Kind `pod` needs sandbox pods (`nylorun local sandbox enable`) and is created at once.",
+        description: "Creates the Agent, its vault and its compute from a saved agent manifest, within the Tenant's limits, or answers the one with this id, so get-or-create is one call. `manifest: \"name\"` records that it tracks the manifest (its latest version, and each version saved later) and `\"name@n\"` that it is pinned; the version it runs is `resolvedVersion`. On an existing one, labels replace, `owner` sets or (with `null`) clears the owner guard, and `manifest` moves it with its id, disk, vault and sessions: a harness-only change applies at once (each session's next turn runs it), a runtime change of a pod at its next start (`targetVersion`, `waitingFor: start`), and a version that adds a required secret once a value is set (`waitingFor: secrets`). Its manifest's name, kind, harness and storage are fixed (`409 agent_fixed_field`): fork it to change them. `?dryRun=true` answers the move's plan and changes nothing. Creating an Agent opens no session. Kind `pod` needs sandbox pods (`nylorun local sandbox enable`) and is created at once.",
         request: {
             params: agentId,
             query: z.object({
@@ -161,7 +161,7 @@ export function agentRoutes(api) {
         path: "/v1/agents/{agentId}/events",
         tags: ["Agents"],
         summary: "Read an Agent's events",
-        description: "`agent.created`, `.attached`, `.detached`, `.deleted`, a pod's `.running`, `.suspended`, `.relaunched`, `.lost`, `.reset` and `.failed`, `.forked`, a move's `.outdated`, `.version_changed` and `.start_failed` (track T3), and `agent.egress` for every connection its sandbox opens through egress-gate, naming the turns that were running (D67), in order, numbered from 0, at most the Tenant's Runtime limit `environmentEventItems` (default 1000) per call: `from` reads on.",
+        description: "`agent.created`, `.attached`, `.detached`, `.deleted`, a pod's `.running`, `.suspended`, `.relaunched`, `.lost`, `.reset` and `.failed`, `.forked`, a move's `.outdated`, `.version_changed` and `.start_failed`, and `agent.egress` for every connection its sandbox opens through egress-gate, naming the turns that were running, in order, numbered from 0, at most the Tenant's Runtime limit `environmentEventItems` (default 1000) per call: `from` reads on.",
         request: {
             params: agentId,
             query: z.object({
@@ -244,7 +244,7 @@ export function agentRoutes(api) {
         path: "/v1/agents/{agentId}/restart",
         tags: ["Agents"],
         summary: "Restart an Agent on its pending version",
-        description: "Applies a version the Agent waits to apply (track T3): a running pod stops, so the next turn starts it on the version, on the same volume; a stopped or failed one is asked to run at once. `retry: true` first moves it to the version that failed to start (`failedVersion`) again. Kinds `virtual` and `none` apply a version at once, so there is nothing to wait for. Refused during a turn (`agent_busy`). The body is optional.",
+        description: "Applies a version the Agent waits to apply: a running pod stops, so the next turn starts it on the version, on the same volume; a stopped or failed one is asked to run at once. `retry: true` first moves it to the version that failed to start (`failedVersion`) again. Kinds `virtual` and `none` apply a version at once, so there is nothing to wait for. Refused during a turn (`agent_busy`). The body is optional.",
         request: {
             params: agentId,
             body: { required: false, content: { "application/json": { schema: RestartAgentRequest } } },
@@ -304,7 +304,7 @@ export function agentRoutes(api) {
         path: "/v1/agents/{agentId}/fork",
         tags: ["Agents"],
         summary: "Fork an Agent",
-        description: "Copies the Agent into a new one (Q15), which is how an Agent changes what is fixed for its life: a new Agent `id`, made from `manifest` (default the source's manifest name, tracking, at its latest version), its disk started from a version of this one's (`disk`: `latest`, the default, takes a snapshot first; a version number; or `empty`) and its secrets copied inside the Runtime (`secrets`: `copy`, the default, copies those the new manifest declares; `none`). On a fork onto other setup the new manifest's setup runs on the copied disk before its first turn. This Agent keeps what it runs, its disk and its sessions. `dryRun` answers the plan and makes nothing. To move an Agent to another version of the same manifest, with the same kind, harness and storage, `PUT` it instead (track T3).",
+        description: "Copies the Agent into a new one, which is how an Agent changes what is fixed for its life: a new Agent `id`, made from `manifest` (default the source's manifest name, tracking, at its latest version), its disk started from a version of this one's (`disk`: `latest`, the default, takes a snapshot first; a version number; or `empty`) and its secrets copied inside the Runtime (`secrets`: `copy`, the default, copies those the new manifest declares; `none`). On a fork onto other setup the new manifest's setup runs on the copied disk before its first turn. This Agent keeps what it runs, its disk and its sessions. `dryRun` answers the plan and makes nothing. To move an Agent to another version of the same manifest, with the same kind, harness and storage, `PUT` it instead.",
         request: {
             params: agentId,
             body: { required: true, content: { "application/json": { schema: ForkAgentRequest } } },
@@ -378,7 +378,7 @@ export function agentRoutes(api) {
         path: "/v1/agents/{agentId}/secrets/{name}",
         tags: ["Agents"],
         summary: "Write an Agent's secret",
-        description: "Creates or replaces one credential of the Agent's vault: an `environment_secret` (the variable `name` reads the sentinel `nylorun_managed` in the sandbox, and egress-gate sets the value as a header on requests to `allowedHosts`), an `environment_variable` (a plain variable), or a `bearer` token or `headers` map for the MCP servers and HTTP tools at `url`. The same name and type re-seals the value and binding; another type replaces it. A rotated value is used from the next request. A second credential for a host or a URL is `409 credential_conflict`. When the Agent's manifest declares secret slots (D64; while it moves to another version, that version's), send only the value (`{ value }`, or `{ headers }` for a `headers` slot): the type and binding come from the slot, and a name it does not declare is `409 secret_not_in_manifest`.",
+        description: "Creates or replaces one credential of the Agent's vault: an `environment_secret` (the variable `name` reads the sentinel `nylorun_managed` in the sandbox, and egress-gate sets the value as a header on requests to `allowedHosts`), an `environment_variable` (a plain variable), or a `bearer` token or `headers` map for the MCP servers and HTTP tools at `url`. The same name and type re-seals the value and binding; another type replaces it. A rotated value is used from the next request. A second credential for a host or a URL is `409 credential_conflict`. When the Agent's manifest declares secret slots (while it moves to another version, that version's), send only the value (`{ value }`, or `{ headers }` for a `headers` slot): the type and binding come from the slot, and a name it does not declare is `409 secret_not_in_manifest`.",
         request: {
             params: secretPath,
             body: {

package/dist/api/http/routes/reads.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { SESSION_STATUSES } from "@nylorun/core/contracts";
+import { PROTOCOL_HEADER } from "@nylorun/core/compatibility";
 import { SessionManifestView, SessionUsageTotals, ModelCallsPage, ModelCallExportPage, ToolCallsPage, TurnTrace, } from "../../components.js";
 import { turnTrace } from "../../../traces/read.js";
 import { readAccess, readStoreOf } from "../../../reads/access.js";
@@ -8,6 +9,27 @@ import { fail } from "../../../tenant/http.js";
 import { readRuntimeLimits } from "../../../tenant/runtime-limits.js";
 import { tenantRoute } from "../define.js";
 import { jsonResponse } from "../respond.js";
+/**
+ * Whether a client speaks protocol 18, whose usage reads carry the calls' timing and the cost by
+ * token kind. An older client's SDK parses these reads strictly, so it gets them without.
+ */
+function usageByKind(header) {
+    const protocol = Number(header?.trim());
+    return Number.isInteger(protocol) && protocol >= 18;
+}
+/** A session's usage as a protocol 16 or 17 client reads it. */
+function totalsBefore18(totals) {
+    const { costSplit: _split, splitCalls: _splitCalls, modelTimeMs: _time, timedCalls: _timed, ...rest } = totals;
+    return rest;
+}
+/** A model call as a protocol 16 or 17 client reads it. */
+function callBefore18(call) {
+    const { startedAt: _started, endedAt: _ended, usage, ...rest } = call;
+    if (usage === null)
+        return { ...rest, usage };
+    const { costSplit: _split, ...counts } = usage;
+    return { ...rest, usage: counts };
+}
 /** A page's `limit`, held to the Tenant's Runtime limit `pageItems` (`pageSize`). */
 const limitParam = (fallback) => z.coerce
     .number()
@@ -105,14 +127,16 @@ export function readRoutes(api) {
             },
         }, async (c) => {
             requirePrincipal(c.get("scope"));
-            const store = readStoreOf(c.env.tenant), access = readAccess(c.get("scope")), id = c.req.param("sessionId");
+            const store = readStoreOf(c.env.tenant), access = readAccess(c.get("scope")), id = c.req.param("sessionId"), current = usageByKind(c.req.header(PROTOCOL_HEADER));
             if (kind === "usage") {
                 const q = parseQuery(turnQuery, c.req.query());
-                return jsonResponse(200, await store.usage(id, q.turnId, access));
+                const totals = await store.usage(id, q.turnId, access);
+                return jsonResponse(200, current ? totals : totalsBefore18(totals));
             }
             const q = parseQuery(callsQuery, c.req.query());
             const limit = await pageSize(c.env.tenant, q.limit, { fallback: CALLS_PAGE_DEFAULT });
-            return jsonResponse(200, await store.modelCalls(id, q.turnId, { ...q, limit }, access));
+            const page = await store.modelCalls(id, q.turnId, { ...q, limit }, access);
+            return jsonResponse(200, current ? page : { ...page, calls: page.calls.map(callBefore18) });
         });
     }
     const toolCallsQuery = turnQuery
@@ -193,6 +217,7 @@ export function readRoutes(api) {
     }, async (c) => {
         const q = parseQuery(exportQuery, c.req.query());
         const limit = await pageSize(c.env.tenant, q.limit, { fallback: EXPORT_PAGE_DEFAULT, name: "exportPageItems" });
-        return jsonResponse(200, await readStoreOf(c.env.tenant).exportModel(q.after, limit));
+        const page = await readStoreOf(c.env.tenant).exportModel(q.after, limit);
+        return jsonResponse(200, usageByKind(c.req.header(PROTOCOL_HEADER)) ? page : { ...page, calls: page.calls.map(callBefore18) });
     });
 }

package/dist/api/http/routes/tenant.js

@@ -307,7 +307,10 @@ export function tenantRoutes(api) {
         path: "/v1/tenant/tool-policy",
         tags: ["Tenant"],
         summary: "Get the Tenant's tool policy",
-        responses: { 200: json(ToolPolicy, "The rules the Tool Gate applies to every MCP and HTTP tool call") },
+        responses: {
+            200: json(ToolPolicy, "The rules the Tool Gate applies to every MCP and HTTP tool call"),
+            409: { description: "A stored rule names an MCP tool by its model-facing `server__tool` name: every call is refused until the policy is set again" },
+        },
     }, async (c) => {
         try {
             return jsonResponse(200, await c.env.tenant.store.tx((t) => readToolPolicy(t)));
@@ -325,7 +328,7 @@ export function tenantRoutes(api) {
         path: "/v1/tenant/tool-policy",
         tags: ["Tenant"],
         summary: "Set the Tenant's tool policy",
-        description: "Replaces every rule. The Tool Gate applies them to each MCP and HTTP tool call of every harness, before it sends the call: the strictest rule that matches decides. `deny` refuses the call (the model gets `tool.denied`), `ask` holds it and pauses the turn until a person answers it with an `approve` command on the session, `allow` runs it. A call no rule matches runs. A rule matches when every selector it sets matches: `tool` (the name the model calls it by; `*` matches any run of characters), `server` (an MCP server's name), `kind` (`mcp` or `http`), `agent` (the agent that calls it) and `when` (fields of the call's input by dotted path, each tested with `equals`, `in`, `gt`, `gte`, `lt`, `lte` or `matches`). Sandbox tools never cross the gate. An empty list allows every call.",
+        description: "Replaces every rule. The Tool Gate applies them to each MCP and HTTP tool call of every harness, before it sends the call: the strictest rule that matches decides. `deny` refuses the call (the model gets `tool.denied`), `ask` holds it and pauses the turn until a person answers it with an `approve` command on the session, `allow` runs it. A call no rule matches runs. A rule matches when every selector it sets matches: `tool` (the tool's identity: an MCP tool's own name on its `server`, or an HTTP tool's declared name, never the name the model calls it by; `*` matches any run of characters), `server` (an MCP server's name), `kind` (`mcp` or `http`), `agent` (the agent that calls it: the agent manifest's name, or the id of an agent used as a tool or of a flow's agent, never an Agent's id) and `when` (fields of the call's input by dotted path, each tested with `equals`, `in`, `gt`, `gte`, `lt`, `lte` or `matches`). A `tool` with `__` in it, a model-facing `server__tool` name, is refused (`400`): name an MCP tool by `server` and `tool`. A stored policy with such a rule refuses every call until it is set again. Sandbox tools never cross the gate. An empty list allows every call.",
         request: { body: body(PutToolPolicyRequest) },
         responses: { 200: json(ToolPolicy, "The policy now in force") },
     }, async (c) => {

package/dist/api/http/routes/triggers.js

@@ -44,7 +44,7 @@ export function triggerRoutes(api) {
     }, async (c) => {
         const id = idOf(c.req.param("agentId"));
         assertReaches(c.get("scope"), id);
-        return jsonResponse(200, await listTriggers(c.env.tenant, id, originOf(c.req.url)));
+        return jsonResponse(200, await listTriggers(c.env.tenant, id, originOf(c)));
     });
     for (const action of ["pause", "resume"])
         tenantRoute(api, WRITE, {
@@ -63,7 +63,7 @@ export function triggerRoutes(api) {
         }, async (c) => {
             const id = idOf(c.req.param("agentId"));
             assertReaches(c.get("scope"), id);
-            return jsonResponse(200, await setTriggerStatus(c.env.tenant, id, c.req.param("triggerId"), action, originOf(c.req.url)));
+            return jsonResponse(200, await setTriggerStatus(c.env.tenant, id, c.req.param("triggerId"), action, originOf(c)));
         });
     tenantRoute(api, WRITE, {
         method: "post",
@@ -111,7 +111,7 @@ export function triggerRoutes(api) {
 }
 /** A delivery: no credential, no protocol header, any body; the endpoint id and the signature are the grant. */
 const DELIVERY = {
-    credentials: ["application", "subject", "token"],
+    credentials: [],
     scopes: "any",
     anonymous: true,
     unversioned: true,
@@ -132,20 +132,20 @@ export function webhookRoutes(api) {
     }, async (c) => {
         const id = idOf(c.req.param("agentId"));
         assertReaches(c.get("scope"), id);
-        return jsonResponse(200, await rotateWebhookSecret(c.env.tenant, id, c.req.param("triggerId"), originOf(c.req.url)));
+        return jsonResponse(200, await rotateWebhookSecret(c.env.tenant, id, c.req.param("triggerId"), originOf(c)));
     });
     tenantRoute(api, DELIVERY, {
         method: "post",
         path: "/v1/webhooks/{endpointId}",
         tags: ["Triggers"],
         summary: "Deliver to a webhook trigger",
-        description: "A sender's delivery, signed with Standard Webhooks (`webhook-id`, `webhook-timestamp` within 5 minutes by default, `webhook-signature`): no credential and no `Nylorun-Protocol`. The body, any media type, at most the Runtime limit `webhookBodyBytes`, is read as bytes and verified before anything else. It runs the trigger once per `webhook-id`: a retry answers the first run. The body reaches the model as data under the trigger's prompt. Other senders (GitHub, Stripe, Slack) are relayed by an app.",
+        description: "A sender's delivery, signed with Standard Webhooks (`webhook-id`, `webhook-timestamp` within 5 minutes by default, `webhook-signature`): no credential (an `Authorization` header is ignored) and no `Nylorun-Protocol`. The body, any media type, at most the Runtime limit `webhookBodyBytes`, is read as bytes and verified before anything else. It runs the trigger once per `webhook-id`: a retry answers the first run. The body reaches the model as data under the trigger's prompt. Other senders (GitHub, Stripe, Slack) are relayed by an app.",
         request: {
             params: z.object({ endpointId: z.string().meta({ description: "The trigger's endpoint id, `wh_…`" }) }),
             headers: z.object({
-                "webhook-id": z.string().optional().meta({ description: "The delivery's id; a retry sends the same" }),
-                "webhook-timestamp": z.string().optional().meta({ description: "Seconds since the epoch" }),
-                "webhook-signature": z.string().optional().meta({ description: "`v1,<base64>`, space-separated" }),
+                "webhook-id": z.string().meta({ description: "The delivery's id; a retry sends the same" }),
+                "webhook-timestamp": z.string().meta({ description: "Seconds since the epoch" }),
+                "webhook-signature": z.string().meta({ description: "`v1,<base64>`, space-separated" }),
             }),
             body: {
                 required: true,
@@ -155,7 +155,7 @@ export function webhookRoutes(api) {
         },
         responses: {
             202: json(WebhookAcceptedResponse, "The run it made: started, queued, skipped or failed"),
-            401: { description: "Not signed with the endpoint's secret, or a timestamp out of tolerance" },
+            401: { description: "Unsigned, not signed with the endpoint's secret, or a timestamp out of tolerance" },
             404: { description: "No endpoint has this id" },
             409: { description: "The trigger is paused (`trigger_paused`)" },
             413: { description: "Over `webhookBodyBytes`" },
@@ -174,7 +174,10 @@ export function webhookRoutes(api) {
         }));
     });
 }
-/** The origin a request reached: where its webhook URLs live. */
-function originOf(url) {
-    return new URL(url).origin;
+/**
+ * Where its webhook URLs live: the Runtime's public URL (`NYLORUN_PUBLIC_URL`), else the origin
+ * the request reached, which behind a proxy that rewrites `Host` is the Runtime's own.
+ */
+function originOf(c) {
+    return c.env.tenant.config.publicUrl ?? new URL(c.req.url).origin;
 }

package/dist/api/openapi.js

@@ -112,7 +112,7 @@ const RUNTIME_TAGS = [
     {
         name: "Agent manifests",
         group: "Agents",
-        description: "Named, versioned agent manifests (protocol 16): one document with what runs inside an agent's loop (`harness`) and what the Runtime provides around it (`runtime`), checked against each other when it is saved. Save one with a plan first (`?dryRun=true`) and `If-Match`; an Agent is made from one version and keeps it, so a save changes no Agent. `client.agentManifests` in `@nylorun/agents`, and `nylorun apply`.",
+        description: "Named, versioned agent manifests (protocol 16): one document with what runs inside an agent's loop (`harness`) and what the Runtime provides around it (`runtime`), checked against each other when it is saved. Save one with a plan first (`?dryRun=true`) and `If-Match`; an Agent runs one version at a time, and a save moves every Agent that tracks the manifest to the new version, while a pinned one stays. `client.agentManifests` in `@nylorun/agents`, and `nylorun apply`.",
         operations: [
             "PUT /v1/agent-manifests/{name}",
             "GET /v1/agent-manifests",
@@ -155,7 +155,7 @@ const RUNTIME_TAGS = [
     {
         name: "Triggers",
         group: "Agents",
-        description: "What starts an Agent's turns with no client connected (track T4, D74): the schedules, one-shot times and webhook endpoints its manifest's `runtime.triggers` declare. Each trigger's status is the Agent's: pause and resume it, run it now, make a webhook trigger's signing secret, and read its runs (`started`, `queued`, `skipped` or `failed`, with a reason). In `@nylorun/agents` and `nylorun agents triggers`.",
+        description: "What starts an Agent's turns with no client connected: the schedules, one-shot times and webhook endpoints its manifest's `runtime.triggers` declare. Each trigger's status is the Agent's: pause and resume it, run it now, make a webhook trigger's signing secret, and read its runs (`started`, `queued`, `skipped` or `failed`, with a reason). In `@nylorun/agents` and `nylorun agents triggers`.",
         operations: [
             "GET /v1/agents/{agentId}/triggers",
             "POST /v1/agents/{agentId}/triggers/{triggerId}/pause",
@@ -169,7 +169,7 @@ const RUNTIME_TAGS = [
     {
         name: "Memory",
         group: "Agents",
-        description: "An Agent's memories (track T5, D72): Markdown files under `/memories` it keeps across sessions, wakes and upgrades, shaped like Anthropic's memory stores. List and read them, write one whole (with a `content_sha256` precondition), delete one or a folder, and read the version every change leaves, with who made it. In `@nylorun/agents` and `nylorun agents memories`.",
+        description: "An Agent's memories: Markdown files under `/memories` it keeps across sessions, wakes and upgrades, shaped like Anthropic's memory stores. List and read them, write one whole (with a `content_sha256` precondition), delete one or a folder, and read the version every change leaves, with who made it. In `@nylorun/agents` and `nylorun agents memories`.",
         operations: [
             "GET /v1/agents/{agentId}/memories",
             "GET /v1/agents/{agentId}/memories/{path}",

package/dist/gates/http-tool.js

@@ -198,7 +198,7 @@ export async function runHttpTool(tenant, call, options) {
             if (authorized.status === "refused")
                 return failed("http.credential", `The credential '${http.credential}' was refused: ${authorized.reason}`);
             if (authorized.status === "unauthenticated")
-                return failed("http.credential", `The session's Environment holds no credential '${http.credential}' for ${authorized.url}`);
+                return failed("http.credential", `The session's Agent holds no credential '${http.credential}' for ${authorized.url}`);
             credential = authorized.headers;
             identity = authorized.identity;
             // A credential with `via` sends the call there, a gateway (R2b C2, Q9): to its one URL, so

package/dist/gates/meter.js

@@ -142,6 +142,22 @@ export function usageRow(request, outcome, at, timing) {
         ...(typeof firstTokenMs === "number" && Number.isFinite(firstTokenMs) && firstTokenMs >= 0
             ? { firstTokenMs: Math.round(firstTokenMs) }
             : {}),
+        ...costSplitColumns(outcome.evidence?.extras?.costSplit),
+    };
+}
+/** The ledger's cost-by-kind columns from the adapter's `costSplit`; none unless all four are costs. */
+function costSplitColumns(split) {
+    if (!split || typeof split !== "object" || Array.isArray(split))
+        return {};
+    const { input, cacheRead, cacheWrite, output } = split;
+    const parts = [input, cacheRead, cacheWrite, output];
+    if (!parts.every((part) => typeof part === "number" && Number.isFinite(part) && part >= 0))
+        return {};
+    return {
+        costInputUsd: input,
+        costCacheReadUsd: cacheRead,
+        costCacheWriteUsd: cacheWrite,
+        costOutputUsd: output,
     };
 }
 /** The ledger rows a budget counts for `request`; undefined when it doesn't apply. */

package/dist/gates/tenant-vaults.d.ts

@@ -29,7 +29,7 @@ export interface TenantVault {
     session(sessionId: string): Promise<Session | undefined>;
     /**
      * The authorization of one request to a session's remote MCP server or HTTP tool: its
-     * credential from the vault of the session's Environment.
+     * credential from the vault of the session's Agent.
      */
     authorizeMcp(sessionId: string, request: McpCredentialRequest): Promise<AuthorizeResult>;
     /** Vault writes and token signing with the Tenant's vault key (the keys service, F4.2). */

package/dist/host/config-for.d.ts

@@ -14,4 +14,6 @@ export declare function configForFactory(options: {
     delivery?: TenantConfig["delivery"];
     /** The trusted issuers of the identity file (`NYLORUN_IDENTITY_FILE`). */
     issuers?: TenantConfig["issuers"];
+    /** The URL clients reach the Runtime API at (`NYLORUN_PUBLIC_URL`). */
+    publicUrl?: string;
 }): (id: string) => TenantConfig;

package/dist/host/config-for.js

@@ -16,6 +16,7 @@ export function configForFactory(options) {
             model: options.model ?? { kind: "vault" },
             ...(options.delivery ? { delivery: options.delivery } : {}),
             ...(options.issuers ? { issuers: options.issuers } : {}),
+            ...(options.publicUrl ? { publicUrl: options.publicUrl } : {}),
             logger: {
                 info: (message, fields) => options.logger.info(message, { tenantId: id, ...fields }),
                 warn: (message, fields) => options.logger.warn(message, { tenantId: id, ...fields }),

package/dist/host/main.js

@@ -279,6 +279,7 @@ export async function main() {
         logger,
         ...(stack.delivery ? { delivery: stack.delivery } : {}),
         ...(issuers ? { issuers } : {}),
+        ...(stack.publicUrl ? { publicUrl: stack.publicUrl } : {}),
     });
     // The process's Durable Session Execution: Restate when its endpoints are set, else the
     // in-process memory execution. An invocation that arrives while the Tenant opens waits for it.