@nylorun/runtime 0.23.0-beta → 0.24.0-beta

package/dist/gates/egress.js

@@ -21,8 +21,17 @@
  * `environment_secret` of a live session on the sandbox is bound to. There the gate terminates
  * TLS and sets the credential's header on every request (`egress-credentials.ts`), still sending
  * only to the checked address. Every other host gets the tunnel. Any other request
- * (an absolute-form plain HTTP request included) is answered 405. Refusals are logged, never as
- * events; the token never is. Tunnels close after `idleMs` without traffic in either direction.
+ * (an absolute-form plain HTTP request included) is answered 405. Refusals are logged; the token
+ * never is. Tunnels close after `idleMs` without traffic in either direction.
+ *
+ * Every connection to a named host on a live token is recorded once (R7.3, Q6, Q7), when it
+ * closes or at once when the gate refuses it: `egress.connection` on the session log of the turn
+ * that held the Environment when it opened (read as the name resolves), else `environment.egress`
+ * on the Environment's own stream. Host, port, outcome, bytes, duration and, for a credential
+ * host, the request count and credential ids; never a header value, a path or a body. A refusal
+ * before that (no token, a stale one, no `host:port`) stays a log line, and a client that hangs up
+ * before the gate answers leaves nothing. A write never holds the tunnel up, and a failed one is
+ * logged (`egress_record_failed`).
  */
 import { lookup as dnsLookup } from "node:dns/promises";
 import { createServer } from "node:http";
@@ -30,7 +39,9 @@ import { BlockList, connect, isIP } from "node:net";
 import { isSandboxHostPattern } from "@nylorun/core/define";
 import { isPrivateAddress } from "../tenant/outbound.js";
 import { bindListener } from "../host/http.js";
-import { credentialTerminator } from "./egress-credentials.js";
+import { CONNECT_ESTABLISHED, credentialTerminator, } from "./egress-credentials.js";
+/** egress-gate as the writer of its events (R4.9): the gate saw the connection itself. */
+export const EGRESS_WRITER = { source: { kind: "egress-gate", id: "egress" }, evidence: "observed" };
 /** Ports a tunnel may open. */
 export const EGRESS_PORTS = [443, 80];
 /** Tunnels one sandbox may hold open at once. */
@@ -134,6 +145,49 @@ function answer(socket, status, message, headers = []) {
         body,
     ].join("\r\n"));
 }
+function connectionRecord(sink, logger, client, at) {
+    let holding;
+    let written = false;
+    const holder = (to) => (holding ??= to.holder(at.environmentId));
+    const write = (fields) => {
+        if (written || !sink)
+            return;
+        written = true;
+        const socket = client;
+        const allowed = fields.outcome === "allowed";
+        const connection = {
+            environmentId: at.environmentId,
+            host: at.host,
+            port: at.port,
+            ...fields,
+            mode: record.credentialBound ? "credential" : "tunnel",
+            credentialBound: record.credentialBound,
+            // Up is what the sandbox sent after its CONNECT, down what it got after the gate's 200.
+            bytesUp: allowed ? Math.max(0, (socket.bytesRead ?? 0) - at.upFrom) : 0,
+            bytesDown: allowed ? Math.max(0, (socket.bytesWritten ?? 0) - CONNECT_ESTABLISHED.length) : 0,
+            durationMs: Math.max(0, Date.now() - at.startedAt.getTime()),
+            startedAt: at.startedAt.toISOString(),
+        };
+        holder(sink)
+            .then((held) => sink.write(held, connection))
+            .catch((error) => logger.error("egress_record_failed", {
+            sandboxId: at.environmentId,
+            host: at.host,
+            error: error instanceof Error ? error.message : String(error),
+        }));
+    };
+    const record = {
+        credentialBound: false,
+        // A failed read is logged when the write needs it.
+        holder: () => void (sink && holder(sink).catch(() => undefined)),
+        refused: (status, reason) => write({ outcome: "refused", reason, status }),
+        closed: (tally) => write({
+            outcome: "allowed",
+            ...(tally ? { requests: tally.requests, credentialIds: [...tally.credentialIds] } : {}),
+        }),
+    };
+    return record;
+}
 export async function startEgressGate(options) {
     const { logger, sandboxes } = options;
     const idleMs = options.idleMs ?? EGRESS_IDLE_MS;
@@ -160,11 +214,17 @@ export async function startEgressGate(options) {
         : undefined;
     const open = new Map();
     const tunnels = new Set();
+    /** Each connection's record, once its Environment and target are known. */
+    const records = new WeakMap();
     async function onConnect(req, client, head) {
+        const startedAt = new Date();
+        // What the sandbox sent before the tunnel: its CONNECT, less the bytes after it (`head`).
+        const upFrom = (client.bytesRead ?? 0) - head.length;
         const target = parseTarget(req.url);
         const refuse = (status, reason, fields = {}, message) => {
             logger.warn("egress_refused", { status, reason, ...(target ? { host: target.host, port: target.port } : {}), ...fields });
             answer(client, status, message ?? reason, status === 407 ? ['proxy-authenticate: Basic realm="nylorun-egress"'] : []);
+            records.get(client)?.refused(status, reason);
         };
         const raw = proxyToken(req.headers["proxy-authorization"]);
         if (!raw)
@@ -183,12 +243,22 @@ export async function startEgressGate(options) {
         if (!target)
             return refuse(403, "target_invalid", { sandboxId }, "CONNECT needs host:port");
         const { host, port } = target;
+        const record = connectionRecord(options.record, logger, client, {
+            environmentId: sandboxId,
+            host,
+            port,
+            startedAt,
+            upFrom,
+        });
+        records.set(client, record);
         if (!EGRESS_PORTS.includes(port))
             return refuse(403, "port_refused", { sandboxId }, `port ${port} is not allowed; tunnels open to 443 or 80 only`);
         if (isIP(host.replace(/^\[|\]$/g, "")) !== 0 || !isSandboxHostPattern(host) || host.startsWith("*."))
             return refuse(403, "not_a_host_name", { sandboxId }, `${host} is not a host name; IP literals are refused`);
         if (!egressAllows(host, sandbox.allow))
             return refuse(403, "host_not_allowed", { sandboxId }, `${host} is not in this sandbox's network.allow`);
+        // Who holds the Environment as the connection opens, read while the name resolves.
+        record.holder();
         let mine = open.get(sandboxId);
         if (!mine)
             open.set(sandboxId, (mine = new Set()));
@@ -217,10 +287,13 @@ export async function startEgressGate(options) {
         if (client.destroyed)
             return;
         if (terminator && port === 443 && (await options.credentials.bound(sandboxId, host))) {
+            record.credentialBound = true;
             // A client that spoke before the 200 is not one this path serves.
             if (head.length > 0)
                 return refuse(403, "early_data", { sandboxId }, "wait for the CONNECT answer before sending");
-            return terminator.terminate(client, { sandboxId, host, addresses: allowed });
+            const tally = { requests: 0, credentialIds: new Set() };
+            client.once("close", () => record.closed(tally));
+            return terminator.terminate(client, { sandboxId, host, addresses: allowed, tally });
         }
         const upstream = await dialFirst(allowed.map((entry) => entry.address), port);
         if (!upstream)
@@ -237,8 +310,11 @@ export async function startEgressGate(options) {
         upstream.on("timeout", close);
         upstream.on("error", close);
         upstream.on("close", () => client.destroy());
-        client.on("close", () => upstream.destroy());
-        client.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+        client.on("close", () => {
+            upstream.destroy();
+            record.closed();
+        });
+        client.write(CONNECT_ESTABLISHED);
         if (head.length > 0)
             upstream.write(head);
         upstream.pipe(client);
@@ -284,6 +360,7 @@ export async function startEgressGate(options) {
         onConnect(req, client, head).catch((error) => {
             logger.error("egress_failed", { error: error instanceof Error ? error.message : String(error) });
             answer(client, 502, "the tunnel failed");
+            records.get(client)?.refused(502, "egress_failed");
         });
     });
     server.on("clientError", (_error, socket) => {
@@ -311,22 +388,50 @@ export async function startEgressGate(options) {
 /**
  * `EgressSandboxes` over the Tenant's `sandbox_resources` (one indexed read): a pod sandbox's
  * host epoch, the pod that joined at it and its spec's allowlist; nothing for a virtual
- * sandbox, or one deleted, lost or expired, as `staleHost` judges a host token.
+ * Environment, or one deleted or lost, as `staleHost` judges a host token.
  */
 export function storeEgressSandboxes(store) {
     return {
         async live(sandboxId) {
-            const sandbox = await store.tx((t) => t.sandboxResource(sandboxId));
+            const sandbox = await store.tx((t) => t.environment(sandboxId));
             const pod = sandbox?.pod;
             if (!sandbox || sandbox.kind !== "pod" || !pod)
                 return undefined;
-            if (pod.desired === "deleted" || pod.observed === "lost" || pod.observed === "expired")
+            if (pod.desired === "deleted" || pod.observed === "lost")
                 return undefined;
             return {
                 epoch: pod.hostEpoch,
                 ...(pod.podUid ? { podUid: pod.podUid } : {}),
-                allow: sandbox.spec.network?.allow ?? [],
+                // The applied allowlist: a recipe change writes it at once (Q8).
+                allow: sandbox.applied.network?.allowedHosts ?? [],
             };
         },
     };
 }
+/**
+ * `EgressRecord` over the Tenant's record (R7.3). The holder is the session on the Environment
+ * whose body has an `activeTurnId` (turns are serial per Environment). With a holder, the write
+ * is `egress.connection` on its session log, at that turn, under the session row's lock; without
+ * one, `environment.egress` on the Environment's stream, under its row's lock. A deleted
+ * Environment gets nothing.
+ */
+export function storeEgressRecord(store) {
+    return {
+        async holder(environmentId) {
+            const sessions = await store.tx((t) => t.sessionsOnEnvironment(environmentId));
+            const holding = sessions.find((session) => typeof session.activeTurnId === "string");
+            return holding ? { sessionId: holding.id, turnId: holding.activeTurnId } : undefined;
+        },
+        async write(holder, connection) {
+            await store.tx(async (t) => {
+                if (holder) {
+                    await t.event(holder.sessionId, holder.turnId, "egress.connection", connection, EGRESS_WRITER);
+                    return;
+                }
+                if (!(await t.environment(connection.environmentId, { lock: true })))
+                    return;
+                await t.environmentEvent(connection.environmentId, "environment.egress", connection);
+            });
+        },
+    };
+}

package/dist/gates/fixture-model.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The fixture model (R4.3): a deterministic, scripted model the Model Gate answers with when the
+ * Tenant's setting `model.fixture` is on (`PUT /v1/tenant/config/seed {fixtureModel: true}`).
+ * The gate answers it itself, metered like any model (a `model_usage` row per call, provider
+ * `fixture`, tokens counted from the text, cost 0), so every harness that calls the gate is seen
+ * the same way: ours, and one written from the published contract.
+ *
+ * What it answers is read from the call: the last user message and the offered tools.
+ * - `fixture:text`: one text answer, `fixture ok`.
+ * - `fixture:tool <name> <json>`: one call of the offered tool `<name>` with `<json>` as its
+ *   arguments; once the tool's result is in the prompt, a text answer that quotes it.
+ * - `fixture:unoffered <name> <json>`: the same call of a tool `<name>` the call does *not*
+ *   offer (a model that names a tool it was never given), for the check that such a call runs
+ *   nothing; once a result is in the prompt, a text answer that quotes it.
+ * - `fixture:budget`: a `budget_exhausted` failure.
+ * - `fixture:slow <seconds>`: a text answer after that long (at most 60 s), or nothing once
+ *   the call is aborted, for cancel checks.
+ * - Anything else keeps the release demo: with a `lookup_order` tool it looks up order
+ *   `demo-123` once, then answers with the result; on a later user message it says what the
+ *   first one was; otherwise it says hello.
+ */
+import type { ModelCandidate, ModelFailureOutcome } from "@nylorun/core/harness-api";
+import type { RuntimeModelCall } from "../contracts.js";
+export declare const FIXTURE_PROVIDER = "fixture";
+type Answer = ModelCandidate | ModelFailureOutcome;
+/** The fixture model's answer to `call`. */
+export declare function fixtureAnswer(call: RuntimeModelCall, signal?: AbortSignal): Promise<Answer>;
+export {};

package/dist/gates/fixture-model.js

@@ -0,0 +1,92 @@
+export const FIXTURE_PROVIDER = "fixture";
+const MARKER = /^fixture:(\w+)(?:\s+([\s\S]*))?$/;
+/** The fixture model's answer to `call`. */
+export async function fixtureAnswer(call, signal) {
+    const last = call.prompt.at(-1);
+    const users = call.prompt.filter((item) => item.kind === "message" && item.role === "user");
+    const marker = MARKER.exec(textOf(users.at(-1)?.content ?? []).trim());
+    if (marker)
+        return scripted(call, marker[1], marker[2]?.trim() ?? "", last, signal);
+    if (last?.kind === "tool-result")
+        return candidate(call, `Order lookup complete: ${textOf(last.content, true)}`);
+    if (users.length > 1)
+        return candidate(call, `I remember: ${textOf(users[0].content)}`);
+    if (!call.tools.some((tool) => tool.name === "lookup_order"))
+        return candidate(call, "Hello from the fixture model.");
+    return candidate(call, [{ type: "tool-call", id: "fixture_lookup", name: "lookup_order", args: { orderId: "demo-123" } }]);
+}
+async function scripted(call, kind, rest, last, signal) {
+    switch (kind) {
+        case "text":
+            return candidate(call, "fixture ok");
+        case "tool":
+        case "unoffered": {
+            if (last?.kind === "tool-result")
+                return candidate(call, `fixture tool ${last.status}: ${textOf(last.content, true)}`);
+            const space = rest.indexOf(" ");
+            const name = space < 0 ? rest : rest.slice(0, space);
+            const offered = call.tools.some((tool) => tool.name === name);
+            if (kind === "tool" && !offered)
+                return candidate(call, `fixture: no tool ${name} is offered`);
+            if (kind === "unoffered" && offered)
+                return candidate(call, `fixture: tool ${name} is offered`);
+            let args = {};
+            try {
+                if (space >= 0)
+                    args = JSON.parse(rest.slice(space + 1));
+            }
+            catch {
+                return candidate(call, "fixture: the tool arguments are not JSON");
+            }
+            if (typeof args !== "object" || args === null || Array.isArray(args))
+                return candidate(call, "fixture: the tool arguments are not an object");
+            return candidate(call, [{ type: "tool-call", id: "fixture_call", name, args: args }]);
+        }
+        case "budget":
+            return {
+                kind: "failed",
+                code: "budget_exhausted",
+                message: "The fixture model's budget is exhausted (fixture:budget)",
+                retryable: false,
+            };
+        case "slow": {
+            const seconds = Math.min(Math.max(Number(rest) || 0, 0), 60);
+            await sleep(seconds * 1000, signal);
+            return candidate(call, `fixture slept ${seconds} s`);
+        }
+        default:
+            return candidate(call, `fixture: unknown marker ${kind}`);
+    }
+}
+function candidate(call, output) {
+    const blocks = typeof output === "string" ? [{ type: "text", text: output }] : output;
+    const inputTokens = tokens(JSON.stringify(call.prompt));
+    const outputTokens = tokens(JSON.stringify(blocks));
+    return {
+        output: blocks,
+        finishReason: blocks.some((block) => block.type === "tool-call") ? "tool-calls" : "stop",
+        usage: { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens, costUsd: 0 },
+        evidence: {
+            resolvedModel: FIXTURE_PROVIDER,
+            extras: { producer: { provider: FIXTURE_PROVIDER, model: FIXTURE_PROVIDER }, costKnown: true },
+        },
+    };
+}
+/** About four characters a token, at least one. */
+const tokens = (text) => Math.max(1, Math.ceil(text.length / 4));
+function textOf(content, json = false) {
+    return content
+        .map((part) => (part.type === "text" ? (part.text ?? "") : json ? JSON.stringify(part) : ""))
+        .join(" ");
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        }, { once: true });
+    });
+}

package/dist/gates/handler.js

@@ -1,12 +1,12 @@
 /**
  * Serves one model call in the gates service: opens the Tenant's vault (the database's one
- * Tenant; a call naming another is refused) and calls the model
- * through `inProcessModelGate`, the same code the loop ran before the gate, so outcomes,
+ * Tenant; a call naming another is refused) and calls the model (the fixture model while the
+ * Tenant's `model.fixture` is on, R4.3) through `inProcessModelGate`, the same code the loop ran before the gate, so outcomes,
  * retries, classification and redaction are unchanged. The meter records the call's usage in
  * the Tenant's ledger. Logs one line per call, never the prompt, the output or a credential.
  */
 import { classifyThrown } from "../model/classify.js";
-import { callFiles, inProcessModelGate } from "./in-process.js";
+import { callFiles, inProcessModelGate, serve } from "./in-process.js";
 import { createMeter } from "./meter.js";
 import { GateRefusal } from "./tenant-vaults.js";
 export function createModelCallHandler(options) {
@@ -28,7 +28,7 @@ export function createModelCallHandler(options) {
                     ...(settings ? { settings } : {}),
                     ...(blobs ? { files: callFiles(vault.store, blobs) } : {}),
                 });
-                outcome = await meter.call(vault.store, call, () => gate.call(call, signal));
+                outcome = await meter.call(vault.store, call, () => serve(vault.store, gate, call, signal));
             }
             catch (error) {
                 if (signal.aborted) {

package/dist/gates/http-tool.d.ts

@@ -17,9 +17,8 @@ export type HttpOutcome = {
     readonly kind: "failed";
     readonly code: string;
     readonly message: string;
-    /** With `credential_rejected`: the tool's `credential`, and the scope of its vault. */
+    /** With `credential_rejected`: the tool's `credential`. */
     readonly server?: string;
-    readonly vault?: "installation" | "user";
     /** How many credential values the message had in it, replaced (R2b C8). */
     readonly redacted?: number;
 };
@@ -45,6 +44,11 @@ export interface HttpToolCall {
     readonly effectId: string;
     readonly turnId: string;
     readonly input: unknown;
+    /**
+     * The call's span context (R7.4), sent as `traceparent`: in the gates service, from the call's
+     * journal row (`gates/journal.ts`); in process, from core's `execute` answer. Never a body field.
+     */
+    readonly traceparent?: string;
 }
 /** What `runHttpTool` reads of the Tenant: the session's pinned manifest and its credentials. */
 export interface HttpToolTenant {

package/dist/gates/http-tool.js

@@ -163,7 +163,6 @@ export async function runHttpTool(tenant, call, options) {
         let credential = {};
         let identity;
         let target = http;
-        let vault;
         if (http.credential !== undefined) {
             const authorized = await tenant.authorize(tool.sessionId, {
                 url: http.url,
@@ -172,10 +171,9 @@ 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 vaults hold no credential '${http.credential}' for ${authorized.url}`);
+                return failed("http.credential", `The session's Environment holds no credential '${http.credential}' for ${authorized.url}`);
             credential = authorized.headers;
             identity = authorized.identity;
-            vault = authorized.vault;
             // A credential with `via` sends the call there, a gateway (R2b C2, Q9).
             if (authorized.via !== undefined)
                 target = { ...http, url: authorized.via };
@@ -187,6 +185,7 @@ export async function runHttpTool(tenant, call, options) {
                 [TURN_ID_HEADER]: call.turnId,
                 [AGENT_ID_HEADER]: agentId ?? session.manifest.id,
                 "idempotency-key": call.effectId,
+                ...(call.traceparent ? { traceparent: call.traceparent } : {}),
             },
             policy: options.policy,
             signal: options.signal,
@@ -199,9 +198,8 @@ export async function runHttpTool(tenant, call, options) {
             return outcome;
         return {
             ...outcome,
-            message: `The service answered HTTP 401: it rejected the credential '${http.credential}' from the ${vault} vault`,
+            message: `The service answered HTTP 401: it rejected the credential '${http.credential}' from the session's Environment`,
             server: http.credential,
-            ...(vault === undefined ? {} : { vault }),
         };
     }
 }

package/dist/gates/in-process.d.ts

@@ -41,4 +41,9 @@ export declare function tenantModelGate(options: {
     /** The Tenant's Object store, for the files a prompt names. */
     readonly blobs?: BlobStore;
 }): ModelGate;
+/**
+ * Serves one call: from the fixture model while the Tenant's `model.fixture` setting is on (R4.3),
+ * else from `gate`. Read per call, so a seed applies to the next call.
+ */
+export declare function serve(store: SessionStore, gate: ModelGate, request: ModelGateRequest, signal: AbortSignal): ReturnType<ModelGate["call"]>;
 export declare function inProcessModelGate(options: InProcessModelGateOptions): ModelGate;

package/dist/gates/in-process.js

@@ -2,6 +2,8 @@ import { piModel } from "../model/pi-model.js";
 import { HostModelVault } from "../vault/host-model.js";
 import { createMeter } from "./meter.js";
 import { artifactFiles } from "../artifacts/files.js";
+import { usesFixtureModel } from "../tenant/model-setting.js";
+import { fixtureAnswer } from "./fixture-model.js";
 /**
  * The files a call names, from the Tenant's artifacts, limited to the call's session: in
  * process, the loop's own request; over HTTP, the session of the run token's claims, which the
@@ -26,9 +28,18 @@ export function tenantModelGate(options) {
     });
     const meter = createMeter({ logger: options.logger });
     return {
-        call: (request, signal) => meter.call(options.store, request, () => gate.call(request, signal)),
+        call: (request, signal) => meter.call(options.store, request, () => serve(options.store, gate, request, signal)),
     };
 }
+/**
+ * Serves one call: from the fixture model while the Tenant's `model.fixture` setting is on (R4.3),
+ * else from `gate`. Read per call, so a seed applies to the next call.
+ */
+export async function serve(store, gate, request, signal) {
+    if (await store.tx((t) => usesFixtureModel(t)))
+        return fixtureAnswer(request.call, signal);
+    return gate.call(request, signal);
+}
 export function inProcessModelGate(options) {
     return {
         async call(request, signal) {

package/dist/gates/journal.d.ts

@@ -0,0 +1,30 @@
+import type { McpServerRef } from "../mcp/pool.js";
+import type { RunClaims } from "../tenant/run-token.js";
+import { type HttpToolRef } from "./http-tool.js";
+import type { TenantVaults } from "./tenant-vaults.js";
+/** The call a run asks the gate to send, as the gate's body names it. */
+export type GateToolCall = {
+    readonly kind: "mcp";
+    readonly server: McpServerRef;
+    readonly name: string;
+    readonly arguments: Record<string, unknown>;
+} | {
+    readonly kind: "http";
+    readonly tool: HttpToolRef;
+    readonly input: unknown;
+};
+/**
+ * What the journal says of a call: why it does not hold it, or that it does, with the call's span
+ * context from the row (R7.4), which the gate sends on as `traceparent`.
+ */
+export type JournalAnswer = {
+    readonly refused: string;
+} | {
+    readonly refused?: undefined;
+    readonly traceparent?: string;
+};
+export interface JournalCheck {
+    /** Whether the journal holds `call` under `key` for the run `claims` names. */
+    check(tenantId: string | undefined, claims: RunClaims, key: string, call: GateToolCall): Promise<JournalAnswer>;
+}
+export declare function journalCheck(vaults: TenantVaults): JournalCheck;

package/dist/gates/journal.js

@@ -0,0 +1,52 @@
+import { mcpToolOf } from "../mcp/snapshot.js";
+import { canonical } from "../store/canonical.js";
+import { httpToolRefOf } from "./http-tool.js";
+export function journalCheck(vaults) {
+    return {
+        async check(tenantId, claims, key, call) {
+            const store = (await vaults.open(tenantId)).store;
+            const refusal = await store.tx(async (t) => {
+                const row = await t.get("effects", key);
+                if (!row)
+                    return `No journaled call has the effect id '${key}'`;
+                const request = row.request;
+                if (request.kind !== "tool" ||
+                    request.sessionId !== claims.sessionId ||
+                    request.turnId !== claims.turnId)
+                    return `Effect '${key}' is not a tool call of this run's turn`;
+                if (row.status !== "invoking")
+                    return `Effect '${key}' is not running: it is ${row.status}`;
+                if (call.kind === "http") {
+                    const { sessionId: _journaled, ...expected } = httpToolRefOf(request);
+                    const { sessionId: _named, ...named } = call.tool;
+                    if (canonical(expected) !== canonical(named))
+                        return `Effect '${key}' calls another tool`;
+                    if (canonical(request.input ?? null) !== canonical(call.input ?? null))
+                        return `Effect '${key}' was journaled with other input`;
+                    return held(row);
+                }
+                const session = await t.get("sessions", request.sessionId);
+                const tool = mcpToolOf(session?.mcpSnapshot, request);
+                if (!tool ||
+                    tool.capabilityId !== call.server.capabilityId ||
+                    tool.serverName !== call.server.serverName ||
+                    (tool.agentId ?? null) !== (call.server.agentId ?? null) ||
+                    tool.serverToolName !== call.name)
+                    return `Effect '${key}' calls another tool`;
+                if (canonical(argumentsOf(request.input)) !== canonical(call.arguments))
+                    return `Effect '${key}' was journaled with other input`;
+                return held(row);
+            });
+            return typeof refusal === "string" ? { refused: refusal } : refusal;
+        },
+    };
+}
+/** A journaled call: its span context, when core recorded one (R7.4). */
+function held(row) {
+    const traceparent = row.traceparent;
+    return typeof traceparent === "string" ? { traceparent } : {};
+}
+/** A tool call's input as `tools/call` arguments (`callMcpTool`): an object, else none. */
+function argumentsOf(input) {
+    return input && typeof input === "object" && !Array.isArray(input) ? input : {};
+}

package/dist/gates/mcp-handler.d.ts

@@ -29,6 +29,10 @@ export interface McpHandler {
         effectId: string;
         name: string;
         arguments: Record<string, unknown>;
+        /** The call's `Idempotency-Key`, sent to the server in `_meta` (R5.5). */
+        key?: string;
+        /** The call's span context from its journal row (R7.4), sent as `traceparent`. */
+        traceparent?: string;
     }, signal: AbortSignal): Promise<McpAnswer<Record<string, unknown>>>;
     close(server: McpServerRef): Promise<void>;
     /** Closes connections idle past the timeout. */

package/dist/gates/mcp-handler.js

@@ -114,7 +114,11 @@ export function createMcpHandler(options) {
     async function callOnce(tenantId, request, signal) {
         for (let attempt = 0;; attempt += 1) {
             try {
-                return await use(tenantId, request.server, (entry) => entry.connection.client.callTool({ name: request.name, arguments: request.arguments }, { signal }), true);
+                return await use(tenantId, request.server, (entry) => entry.connection.client.callTool({ name: request.name, arguments: request.arguments }, {
+                    signal,
+                    ...(request.key === undefined ? {} : { key: request.key }),
+                    ...(request.traceparent === undefined ? {} : { traceparent: request.traceparent }),
+                }), true);
             }
             catch (error) {
                 if (!(error instanceof McpConnectionStale) || attempt > 0)

package/dist/gates/meter.d.ts

@@ -13,8 +13,16 @@ export interface MeterOptions {
     readonly now?: () => Date;
 }
 export declare function createMeter(options: MeterOptions): Meter;
-/** The ledger row of an outcome that carries usage; undefined for a failure. */
-export declare function usageRow(request: ModelGateRequest, outcome: ModelGateOutcome, at: Date): ModelUsageWrite | undefined;
+/** When the gate sent a call and when its answer was complete (R7.1). */
+export interface CallTiming {
+    readonly startedAt: Date;
+    readonly endedAt: Date;
+}
+/**
+ * The ledger row of an outcome that carries usage; undefined for a failure. With `timing`, the
+ * row keeps the gate's start and end of the call, and the adapter's `firstTokenMs`.
+ */
+export declare function usageRow(request: ModelGateRequest, outcome: ModelGateOutcome, at: Date, timing?: CallTiming): ModelUsageWrite | undefined;
 /**
  * Why the budget refuses another call, or undefined. Calls in flight count at the scope's
  * average cost per recorded call.

package/dist/gates/meter.js

@@ -8,6 +8,10 @@
  * the scope at the scope's average cost per call, reaches its limit. Calls in a turn run one
  * at a time, so a scope overspends by at most one call per concurrent call. The refusal is a
  * `budget_exhausted` failure, which the turn does not retry.
+ *
+ * The row also keeps the gate's own timing of the call (R7.1): `now()` before the call and
+ * after it, and the adapter's `firstTokenMs` (`evidence.extras`), so a model call's span is
+ * what the gate measured.
  */
 import { randomUUID } from "node:crypto";
 import { failure } from "../model/classify.js";
@@ -60,8 +64,9 @@ export function createMeter(options) {
             for (const key of keys)
                 inflight.set(key, (inflight.get(key) ?? 0) + 1);
             try {
+                const startedAt = now();
                 const outcome = await call();
-                await record(store, request, outcome);
+                await record(store, request, outcome, { startedAt, endedAt: now() });
                 return outcome;
             }
             finally {
@@ -75,8 +80,8 @@ export function createMeter(options) {
             }
         },
     };
-    async function record(store, request, outcome) {
-        const row = usageRow(request, outcome, now());
+    async function record(store, request, outcome, timing) {
+        const row = usageRow(request, outcome, timing.endedAt, timing);
         if (!row)
             return;
         try {
@@ -96,11 +101,15 @@ export function createMeter(options) {
         }
     }
 }
-/** The ledger row of an outcome that carries usage; undefined for a failure. */
-export function usageRow(request, outcome, at) {
+/**
+ * The ledger row of an outcome that carries usage; undefined for a failure. With `timing`, the
+ * row keeps the gate's start and end of the call, and the adapter's `firstTokenMs`.
+ */
+export function usageRow(request, outcome, at, timing) {
     if (typeof outcome !== "object" || "kind" in outcome || !outcome.usage)
         return undefined;
     const usage = outcome.usage;
+    const firstTokenMs = outcome.evidence?.extras?.firstTokenMs;
     const producer = producerOf(outcome);
     const inputTokens = count(usage.inputTokens);
     const outputTokens = count(usage.outputTokens);
@@ -126,6 +135,12 @@ export function usageRow(request, outcome, at) {
         reasoningTokens: count(usage.reasoningTokens),
         costUsd: Number.isFinite(usage.costUsd) && usage.costUsd > 0 ? usage.costUsd : 0,
         createdAt: at.toISOString(),
+        ...(timing
+            ? { startedAt: timing.startedAt.toISOString(), endedAt: timing.endedAt.toISOString() }
+            : {}),
+        ...(typeof firstTokenMs === "number" && Number.isFinite(firstTokenMs) && firstTokenMs >= 0
+            ? { firstTokenMs: Math.round(firstTokenMs) }
+            : {}),
     };
 }
 /** The ledger rows a budget counts for `request`; undefined when it doesn't apply. */