@nylorun/runtime 0.23.0-beta → 0.24.0-beta

package/dist/harness-api/server.js

@@ -25,10 +25,10 @@
  * `connection.lost`.
  */
 import { randomUUID } from "node:crypto";
-import { HARNESS_API_VERSION, HARNESS_CLAIMS, HarnessApiError, } from "@nylorun/core/harness-api";
+import { DEFAULT_HARNESS, HARNESS_API_VERSION, HARNESS_CLAIMS, MAX_HARNESS_STATE_BYTES, isHarnessId, HarnessApiError, } from "@nylorun/core/harness-api";
 import { definitionFilesOf } from "@nylorun/core/contracts";
 import { isOwnershipLost } from "../store/ownership.js";
-import { ownedSession } from "../tenant/context.js";
+import { harnessOf, ownedSession } from "../tenant/context.js";
 import { mcpDiscovered, pinDeferral, sessionToolsOf, } from "../mcp/snapshot.js";
 import { contextWindowOf } from "../model/catalog.js";
 import { turnManifestOf } from "../tenant/session.js";
@@ -36,6 +36,7 @@ import { sandboxWorkspaceKey, workspacePrefix } from "../sandbox/records.js";
 import { abortKind } from "../tenant/worker.js";
 import { readDefinitionFile } from "../tenant/definition-files.js";
 import { recordIntent, recordOutcome } from "./record.js";
+import { redactTokens } from "./redact.js";
 import { beat, renewEveryMs, tokenOf } from "./renew.js";
 /** No attached harness serves workspaces (or, with `pod`, that pod sandbox's). */
 export class NoWorkspaceHarness extends Error {
@@ -48,6 +49,8 @@ export class NoWorkspaceHarness extends Error {
         this.pod = pod;
     }
 }
+/** What our harness said in `hello` before harness ids (R4.1): refused, with the new id. */
+const LEGACY_NAME = "@nylorun/harness";
 const OUTPUTS = [
     "turn.completed",
     "turn.paused",
@@ -62,8 +65,11 @@ export function createHarnessApiServer(ctx, options = {}) {
     const queued = [];
     const runs = new Map();
     let closed = false;
-    /** A harness may take a run: a pod sandbox's host its sandbox's runs, any other the rest. */
-    const takes = (connection, run) => connection.host?.sandboxId === run.offer.pod;
+    /**
+     * A harness may take a run of its own harness id (R4.1): a pod sandbox's host its sandbox's
+     * runs, any other the rest.
+     */
+    const takes = (connection, run) => connection.harness === (run.offer.harness ?? DEFAULT_HARNESS) && connection.host?.sandboxId === run.offer.pod;
     /** Hands queued runs to waiting harnesses that may take them, in order. */
     const match = () => {
         for (let i = 0; i < queued.length;) {
@@ -89,16 +95,30 @@ export function createHarnessApiServer(ctx, options = {}) {
             throw new HarnessApiError("run_not_held", `Run ${runId} is not held by this harness`);
         return run;
     };
+    /** What a harness reports is its claim (R4.9): its harness id and, in a run, the run. */
+    const writerOf = (connection, runId) => ({
+        source: { kind: "harness", id: connection.harness ?? connection.peer.name },
+        evidence: "claimed",
+        ...(runId === undefined ? {} : { runId }),
+    });
     const scope = (run) => ({
         ctx,
         lease: run.offer.lease,
         signal: run.offer.controller.signal,
+        ...(run.connection?.tools ? { nativeTools: run.connection.tools } : {}),
+        ...(run.connection ? { writer: writerOf(run.connection, run.grant.runId) } : {}),
     });
     const serve = (connection) => async (method, params, signal) => {
         const p = params;
         if (method === "hello") {
-            const { capabilities } = p;
+            const { api, name, capabilities } = p;
+            // R3's next version adds a window of supported versions; until then there is one.
+            if (api !== HARNESS_API_VERSION)
+                throw new HarnessApiError("invalid", `unsupported Harness API version ${api}: this Runtime speaks ${HARNESS_API_VERSION}`);
+            connection.harness = await harnessIdOf(connection, name);
             connection.workspace = capabilities.workspace !== undefined;
+            if (capabilities.tools?.length)
+                connection.tools = new Set(capabilities.tools.map((tool) => tool.name));
             return {
                 api: HARNESS_API_VERSION,
                 tenantId: ctx.config.tenantId,
@@ -109,6 +129,8 @@ export function createHarnessApiServer(ctx, options = {}) {
         }
         if (method === "event")
             return claim(connection, p);
+        if (method === "lease" && connection.harness === undefined)
+            throw new HarnessApiError("invalid", "Say hello first: a harness leases runs of the id it names");
         if (method === "lease")
             return new Promise((resolve, reject) => {
                 const entry = { connection, resolve };
@@ -121,8 +143,12 @@ export function createHarnessApiServer(ctx, options = {}) {
                 });
                 match();
             });
-        if (OUTPUTS.includes(method))
-            return output(held(connection, String(p.runId), method), method, p);
+        if (OUTPUTS.includes(method)) {
+            const run = held(connection, String(p.runId), method);
+            if (connection.harness !== DEFAULT_HARNESS)
+                checkCustomOutput(run, method, p);
+            return output(run, method, p);
+        }
         const run = held(connection, String(p.runId));
         switch (method) {
             case "lease.renew":
@@ -150,6 +176,27 @@ export function createHarnessApiServer(ctx, options = {}) {
                 throw new HarnessApiError("invalid", `Unknown request ${method}`);
         }
     };
+    /**
+     * The harness id a `hello` names (R4.1): a harness id, and the one the connection's credential
+     * is for. A pod's host must be its Environment's harness, so an image that is not the harness
+     * its recipe names never takes the Environment's runs.
+     */
+    const harnessIdOf = async (connection, name) => {
+        if (!isHarnessId(name))
+            throw new HarnessApiError("invalid", name === LEGACY_NAME
+                ? `A harness names its harness id in hello: ours is ${DEFAULT_HARNESS}. Update the harness image (it said ${LEGACY_NAME}).`
+                : `hello.name ${JSON.stringify(name)} is not a harness id: lowercase letters, digits and dashes, starting with a letter`);
+        const bound = connection.peer.harness;
+        if (bound !== undefined && bound !== name)
+            throw new HarnessApiError("invalid", `This credential is for the ${bound} harness, not ${name}`);
+        if (connection.host) {
+            const environment = await ctx.store.tx((t) => t.environment(connection.host.sandboxId));
+            const expected = environment?.applied.harness ?? DEFAULT_HARNESS;
+            if (expected !== name)
+                throw new HarnessApiError("invalid", `Environment ${connection.host.sandboxId} runs the ${expected} harness, and this pod says ${name}`);
+        }
+        return name;
+    };
     /**
      * A `sandbox.*` event the harness claims: for a run it holds (the run's session, or the
      * session owning its sandbox), or a session one of its workspace requests acts for. A
@@ -169,7 +216,7 @@ export function createHarnessApiServer(ctx, options = {}) {
             throw new HarnessApiError("run_not_held", `This harness may not claim events of ${event.sessionId}`);
         const record = event.record;
         if (record &&
-            (event.type !== "sandbox.state" ||
+            (event.type !== "environment.state" ||
                 record.sessionId !== event.sessionId ||
                 !record.key.startsWith(workspacePrefix(ctx.config.tenantId)) ||
                 (connection.host !== undefined &&
@@ -179,7 +226,7 @@ export function createHarnessApiServer(ctx, options = {}) {
             await ctx.store.tx(async (t) => {
                 if (record)
                     await t.put("sandboxes", record.key, record);
-                await t.event(event.sessionId, event.turnId, event.type, event.payload);
+                await t.event(event.sessionId, event.turnId, event.type, redactTokens(event.payload), writerOf(connection, event.runId));
             });
         }
         catch (error) {
@@ -211,7 +258,7 @@ export function createHarnessApiServer(ctx, options = {}) {
                 current.mcpSnapshot = pinDeferral(snapshot, current.manifest, contextWindow);
                 current.mcpDiagnostics = diagnostics;
                 await t.put("sessions", current.id, current);
-                await t.event(current.id, run.grant.turnId, "mcp.discovered", mcpDiscovered(current.mcpSnapshot, diagnostics));
+                await t.event(current.id, run.grant.turnId, "mcp.discovered", mcpDiscovered(current.mcpSnapshot, diagnostics), run.connection ? writerOf(run.connection, run.grant.runId) : undefined);
             }
             else if (diagnostics.length > 0) {
                 const prior = [...(current.mcpDiagnostics ?? [])];
@@ -241,6 +288,27 @@ export function createHarnessApiServer(ctx, options = {}) {
             throw new HarnessApiError("unavailable", `The Object store has no bytes for ${sha256}`);
         return { base64: Buffer.from(bytes).toString("base64") };
     };
+    /**
+     * A custom harness's output (R4.2): its state is its own, stored as sent and never read, so it
+     * must be JSON and at most `MAX_HARNESS_STATE_BYTES`; a larger one fails the turn, as an engine
+     * that threw would. It cannot pause for approvals in v2 (Q14): approvals read our engine's plan
+     * until R5 makes them core holds.
+     */
+    const checkCustomOutput = (run, method, params) => {
+        if (method === "turn.paused")
+            throw new HarnessApiError("invalid", "A custom harness cannot pause for approvals in Harness API 2");
+        if (params.state === undefined || run.outputs.has(method))
+            return;
+        const bytes = Buffer.byteLength(JSON.stringify(params.state) ?? "");
+        if (bytes <= MAX_HARNESS_STATE_BYTES)
+            return;
+        output(run, "turn.failed", {
+            runId: run.grant.runId,
+            status: "failed",
+            thrown: { code: "invalid", message: `The harness's state is ${bytes} bytes, over ${MAX_HARNESS_STATE_BYTES}` },
+        }).catch(() => undefined);
+        throw new HarnessApiError("invalid", `state over 256 KiB (${bytes} bytes): the turn failed`);
+    };
     const output = (run, method, params) => {
         const known = run.outputs.get(method);
         if (known)
@@ -262,7 +330,10 @@ export function createHarnessApiServer(ctx, options = {}) {
         status() {
             return {
                 connected: connections.size,
-                workspace: [...connections].some((connection) => connection.workspace && !connection.host && !connection.channel.closed),
+                workspace: [...connections].some((connection) => connection.workspace &&
+                    !connection.host &&
+                    connection.harness === DEFAULT_HARNESS &&
+                    !connection.channel.closed),
             };
         },
         hosting(sandboxId) {
@@ -275,10 +346,19 @@ export function createHarnessApiServer(ctx, options = {}) {
         },
         async workspace(method, params, signal, target) {
             const pod = target?.pod;
-            const connection = [...connections].find((item) => item.workspace && !item.channel.closed && item.host?.sandboxId === pod);
+            const session = params.session?.ownerId;
+            // A pod's workspace is its host's, whatever harness it is. Any other session's is served
+            // by its own harness, if that harness serves workspaces: our harness's workspaces are not
+            // a custom harness's files (R4.1). Sweeps and removes go to ours.
+            const harness = pod !== undefined || session === undefined
+                ? DEFAULT_HARNESS
+                : harnessOf((await ctx.store.tx((t) => t.get("sessions", session))) ?? {});
+            const connection = [...connections].find((item) => item.workspace &&
+                !item.channel.closed &&
+                item.host?.sandboxId === pod &&
+                (pod !== undefined || item.harness === harness));
             if (!connection)
                 throw new NoWorkspaceHarness(pod);
-            const session = params.session?.ownerId;
             if (session)
                 connection.claims.set(session, (connection.claims.get(session) ?? 0) + 1);
             else

package/dist/harness-api/start.d.ts

@@ -1,6 +1,7 @@
 import type { RecordedOutcome, TurnStart } from "@nylorun/core/harness-api";
 import type { SandboxPodState } from "../store/types.js";
 import { type Lease, type Session, type TenantContext } from "../tenant/context.js";
+import { type TraceContext } from "../traces/ids.js";
 /** A segment ready to run: the session as it starts, and its transcript folded from the record. */
 export interface SegmentStart {
     readonly current: Session;
@@ -10,18 +11,24 @@ export interface SegmentStart {
     /** The record position of `transcript` (`foldTranscriptWithCursor`). */
     readonly cursor: number;
     readonly outcomes: RecordedOutcome[];
-    /** The tree's sandbox workspace: its owning session, and the sandbox resource it is attached to. */
+    /** The session's sandbox workspace: the session, and the Environment whose workspace it is. */
     readonly sandbox: {
         readonly ownerId: string;
-        readonly sandboxId?: string;
+        readonly environmentId?: string;
         /** Variables every sandbox command gets (R2c): secret names set to the sentinel, plain values. */
         readonly environment?: Readonly<Record<string, string>>;
     };
-    /** The sandbox is a pod sandbox (F7.2): its engine runs the segment. Its lifecycle state. */
+    /**
+     * The Environment is a pod (F7.2): its engine runs the segment. Its lifecycle state, and
+     * whether its new volume is still being seeded from a disk version (R2d step 3).
+     */
     readonly pod?: {
         readonly id: string;
         readonly pod: SandboxPodState;
+        readonly seeding?: boolean;
     };
+    /** The turn's span context (R7.4): what `TurnStart.trace` hands the harness. */
+    readonly trace?: TraceContext;
 }
 /** The segment's starting transaction and fold. */
 export declare function startSegment(ctx: TenantContext, lease: Lease, 

package/dist/harness-api/start.js

@@ -1,11 +1,14 @@
 import { isWorkflowManifest } from "../core/flow-host.js";
 import { sandboxWorkspaceOf } from "../sandbox/share.js";
 import { ownedTx } from "../store/ownership.js";
-import { sandboxLookup } from "../tenant/context.js";
+import { harnessOf } from "../tenant/context.js";
+import { HARNESS_ID } from "../sandbox/placement.js";
 import { checkParity, foldTranscriptWithCursor, leanState, transcriptOf, transcriptUpdates, withTranscript, } from "../tenant/history.js";
 import { usesFixtureModel } from "../tenant/model-setting.js";
-import { rebaseSessionState, sessionToolsOf, turnManifestOf } from "../tenant/session.js";
+import { sessionToolsOf, turnManifestOf } from "../tenant/session.js";
 import { bulkOutcomes } from "./record.js";
+import { traceKey } from "../traces/key.js";
+import { traceparentOf, turnSpanOf, turnTraceIdOf, } from "../traces/ids.js";
 /** Segment rollover defaults (Model Calls §10), well inside the advance deadline. */
 const ROLLOVER_STEPS = 50;
 const ROLLOVER_MS = 20 * 60_000;
@@ -14,9 +17,12 @@ export async function startSegment(ctx, lease,
 /** For a harness: also the segment's outcomes and the sandbox's owner. */
 options = {}) {
     const id = lease.sessionId;
+    // Read before the transaction: the first read of the Tenant may create the key.
+    const key = options.harness ? await traceKey(ctx.store) : undefined;
     const started = await ownedTx(ctx.store, id, lease.epoch, async (t, current) => {
-        if (!isWorkflowManifest(current.manifest) && current.checkpoint) {
-            rebaseSessionState(current, current.checkpoint.manifestHash);
+        // A transcript left on our engine's state by an older Runtime is recorded once; another
+        // harness's state is its own (R4.2).
+        if (!isWorkflowManifest(current.manifest) && current.checkpoint && harnessOf(current) === HARNESS_ID) {
             await adoptStoredTranscript(t, current);
             const cp = current.checkpoint;
             current.checkpoint = { ...cp, state: current.state };
@@ -25,22 +31,33 @@ options = {}) {
         const fixtureModel = await usesFixtureModel(t);
         if (!options.harness)
             return { current, fixtureModel, outcomes: [], sandbox: { ownerId: id } };
-        const workspace = sandboxWorkspaceOf(current, await sandboxLookup(t, current.id));
-        const resource = workspace.sandboxId === undefined ? undefined : await t.sandboxResource(workspace.sandboxId);
-        const { environment } = await ctx.vault.sessionEnvironment(t, current.vaultIds ?? []);
+        const workspace = sandboxWorkspaceOf(current);
+        const resource = workspace.environmentId === undefined ? undefined : await t.environment(workspace.environmentId);
+        const environment = await ctx.vault.environmentVariables(t, current.environmentId);
         const sandbox = Object.keys(environment).length > 0 ? { ...workspace, environment } : workspace;
+        const turnId = current.activeTurnId;
         return {
             current,
             fixtureModel,
             outcomes: current.checkpoint ? await bulkOutcomes(t, current, current.checkpoint) : [],
             sandbox,
-            ...(resource?.pod ? { pod: { id: resource.id, pod: resource.pod } } : {}),
+            ...(key && turnId ? { trace: turnContextOf(key, ctx.store.tenantId, current, turnId) } : {}),
+            ...(resource?.pod
+                ? { pod: { id: resource.id, pod: resource.pod, ...(resource.diskSeed ? { seeding: true } : {}) } }
+                : {}),
         };
     });
     // One history (P0.3): the engine resumes from the transcript folded from the record.
     const { current } = started;
     const cp = current.checkpoint;
-    if (isWorkflowManifest(current.manifest) || !cp?.state)
+    if (isWorkflowManifest(current.manifest))
+        return { ...started, transcript: [], cursor: -1 };
+    // Another harness's state says nothing about its transcript (R4.2): fold it every segment.
+    if (harnessOf(current) !== HARNESS_ID) {
+        const { transcript, cursor } = await foldSession(ctx, current);
+        return { ...started, transcript, cursor };
+    }
+    if (!cp?.state)
         return { ...started, transcript: [], cursor: -1 };
     const { transcript, cursor } = await foldSession(ctx, current);
     checkParity(id, transcript, transcriptOf(cp.state));
@@ -56,7 +73,7 @@ export function buildTurnStart(ctx, segment) {
         type: !flow && (input?.kind === "approve" || input?.kind === "respond") ? "approval.answer" : "turn.start",
         engine: flow ? "flow" : "agent",
         manifest: flow ? current.manifest : turnManifestOf(current),
-        checkpoint: !flow && cp.state
+        checkpoint: !flow && cp.state && harnessOf(current) === HARNESS_ID
             ? { ...cp, state: withTranscript(cp.state, []) }
             : cp,
         // The turn's manifest: a variant may have disabled MCP tools or required their approval.
@@ -74,6 +91,19 @@ export function buildTurnStart(ctx, segment) {
             ...(current.mcpSnapshot ? { mcpSnapshot: current.mcpSnapshot } : {}),
             sandbox: segment.sandbox,
         },
+        ...(segment.trace ? { trace: segment.trace } : {}),
+    };
+}
+/**
+ * The context of turn `turnId`'s span (R7.4): its trace (the caller's when its message carried a
+ * `traceparent`) and its span, as the trace projector derives them, with the caller's
+ * `tracestate`.
+ */
+function turnContextOf(key, tenantId, s, turnId) {
+    const traceId = turnTraceIdOf(key, { tenantId, sessionId: s.id, turnId }, s.turnTrace);
+    return {
+        traceparent: traceparentOf(traceId, turnSpanOf(key, turnId)),
+        ...(s.turnTrace?.tracestate ? { tracestate: s.turnTrace.tracestate } : {}),
     };
 }
 /** The engine's yield budget for a segment. */

package/dist/harness-api/tool-journal.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The effect journal's tool calls (R5): every tool call is a row of `nylorun.effects`, and how
+ * it ends is one `tool.completed` with its status, kind, server, attempts and duration (R5.1).
+ *
+ * Delivery (R5.3, R5.4). A tool call is sent at least once, and every send carries its effect
+ * id as the key. After a crash, a shutdown or a lost gate hop, a row still `invoking` is sent
+ * again: an MCP or HTTP tool call (it crosses the Tool Gate, which hands the tool the key) up to
+ * `MAX_TOOL_ATTEMPTS` sends, then it fails to the model as `tool.interrupted`. A sandbox or
+ * core-served call has no key to dedupe on, so a crash fails it to the model at once, and
+ * nothing runs it again (Q2). No tool call leaves its session `uncertain`.
+ *
+ * The row body keeps the journal's facts: `toolKind`, `server`, `attempts`, `startedAt` and
+ * `settledAt`. A row written before R5 has none of them.
+ *
+ * Spans (R7.1). `tool.completed` also carries the call's effect id, the Tool Gate's own start
+ * and end of its last send (`gate`, from its `tool_crossings` row: MCP and HTTP calls through
+ * the gateway, while the row is kept), and what the tool policy did when it did more than allow
+ * (`policy`). A flow's HTTP stage, which names no tool call, ends in `node.completed` instead.
+ */
+import type { EventWriter } from "@nylorun/core/contracts";
+import type { AgentManifest } from "@nylorun/core/define";
+import type { HostEffect } from "@nylorun/harness/run";
+import type { Session } from "../tenant/context.js";
+import { type GateTimes, type ToolCallFacts, type ToolCallKind, type ToolCallStatus, type ToolPolicyFact } from "../tenant/transcript.js";
+import type { EffectDoc, Tx } from "../store/types.js";
+/** How many times a tool call is sent before it fails to the model as `tool.interrupted`. */
+export declare const MAX_TOOL_ATTEMPTS = 3;
+/** A tool row's journal facts (R5), kept in its body. */
+export interface ToolRowFacts {
+    /** Why the Tool Gate held the call for approval, and since when (R5 step 2). */
+    hold?: {
+        reason: string;
+        at: string;
+    };
+    /** A person's approval of a held call (R5 step 2): the gate then sends it. */
+    approval?: {
+        approved: true;
+        at: string;
+        by?: string;
+    };
+    toolKind?: ToolCallKind;
+    server?: string;
+    attempts?: number;
+    startedAt?: string;
+    settledAt?: string;
+    /**
+     * The tool span's context (R7.4), `00-<trace>-<span>-01`: the Tool Gate reads it with the row
+     * and sends it as `traceparent`, and a harness hands it to a sandbox command as `TRACEPARENT`.
+     */
+    traceparent?: string;
+}
+export type ToolRow = EffectDoc & ToolRowFacts & {
+    requestHash?: string;
+    outcome?: {
+        value: unknown;
+        statePatch?: Record<string, unknown>;
+    };
+    error?: string;
+};
+/** Where a tool call runs, and its MCP server or HTTP tool capability. */
+export declare function toolKindOf(s: Pick<Session, "manifest" | "mcpSnapshot">, agentManifest: AgentManifest | undefined, request: HostEffect): {
+    toolKind: ToolCallKind;
+    server?: string;
+};
+/** The facts a new tool row starts with: its first send, now. */
+export declare function firstSend(kind: {
+    toolKind: ToolCallKind;
+    server?: string;
+}, now?: Date): ToolRowFacts;
+/** A failed outcome the Runtime gives a call a crash interrupted: it may have run. */
+export declare function interrupted(message: string): {
+    kind: string;
+    code: string;
+    message: string;
+    retryable: boolean;
+};
+/** The facts `tool.completed` carries for `row`, settled with `status`, and the gate's times. */
+export declare function factsOf(row: ToolRow, status: ToolCallStatus, gate?: GateTimes): ToolCallFacts;
+/**
+ * What the Tenant's tool policy did with `row` (R5 step 2), when it did more than allow it: held
+ * it for a person (`ask`, with who approved it, when someone did), or refused it unsent (`deny`).
+ */
+export declare function policyOf(row: ToolRow): ToolPolicyFact | undefined;
+/**
+ * Settles a tool row with `value` (`completed`) or as `cancelled`, and writes its one
+ * `tool.completed` (an agent's tool call), or `node.completed` (a flow's HTTP stage or verifier,
+ * which names no call, R7.1). Writes `row`.
+ */
+export declare function settleToolRow(t: Tx, s: Pick<Session, "id">, row: ToolRow, value: unknown, options?: {
+    cancelled?: boolean;
+    now?: Date;
+    /** Who reported the outcome (R4.9): the harness that ran the call; absent, core. */
+    writer?: EventWriter;
+}): Promise<{
+    value: unknown;
+}>;

package/dist/harness-api/tool-journal.js

@@ -0,0 +1,102 @@
+import { isFlowToolEffect } from "../core/flow-host.js";
+import { isHttpToolCall } from "../gates/http-tool.js";
+import { mcpToolOf } from "../mcp/snapshot.js";
+import { sandboxCapabilityOf } from "../sandbox/capability.js";
+import { toolCompleted, } from "../tenant/transcript.js";
+import { toolCallDuration, toolCallStatus } from "./tool-status.js";
+/** How many times a tool call is sent before it fails to the model as `tool.interrupted`. */
+export const MAX_TOOL_ATTEMPTS = 3;
+/** Where a tool call runs, and its MCP server or HTTP tool capability. */
+export function toolKindOf(s, agentManifest, request) {
+    const mcp = mcpToolOf(s.mcpSnapshot, request);
+    if (mcp)
+        return { toolKind: "mcp", server: mcp.serverName };
+    if (isHttpToolCall(s.manifest, request))
+        return { toolKind: "http", ...(request.capabilityId ? { server: request.capabilityId } : {}) };
+    if (sandboxCapabilityOf(agentManifest, request.capabilityId, request.toolName))
+        return { toolKind: "sandbox" };
+    return { toolKind: "platform" };
+}
+/** The facts a new tool row starts with: its first send, now. */
+export function firstSend(kind, now = new Date()) {
+    return { ...kind, attempts: 1, startedAt: now.toISOString() };
+}
+/** A failed outcome the Runtime gives a call a crash interrupted: it may have run. */
+export function interrupted(message) {
+    return { kind: "failed", code: "tool.interrupted", message, retryable: false };
+}
+/** The facts `tool.completed` carries for `row`, settled with `status`, and the gate's times. */
+export function factsOf(row, status, gate) {
+    const durationMs = toolCallDuration(row);
+    const policy = policyOf(row);
+    return {
+        status,
+        ...(row.toolKind === undefined ? {} : { kind: row.toolKind }),
+        ...(row.server === undefined ? {} : { server: row.server }),
+        ...(row.attempts === undefined ? {} : { attempts: row.attempts }),
+        ...(durationMs === undefined ? {} : { durationMs }),
+        effectId: row.request.effectId,
+        ...(gate === undefined ? {} : { gate }),
+        ...(policy === undefined ? {} : { policy }),
+    };
+}
+/**
+ * What the Tenant's tool policy did with `row` (R5 step 2), when it did more than allow it: held
+ * it for a person (`ask`, with who approved it, when someone did), or refused it unsent (`deny`).
+ */
+export function policyOf(row) {
+    if (row.hold)
+        return {
+            decision: "ask",
+            reason: row.hold.reason,
+            ...(row.approval?.by === undefined ? {} : { approvedBy: row.approval.by }),
+        };
+    const value = row.outcome?.value;
+    // `bypolicy` refuses a call before its first send.
+    if (row.attempts === 0 && value?.code === "tool.denied")
+        return { decision: "deny", reason: String(value.message ?? "") };
+    return undefined;
+}
+/**
+ * The Tool Gate's own start and end of `row`'s last send (R7.1), from its `tool_crossings` row:
+ * an MCP or HTTP call the gateway ran and settled. Undefined for any other call, one never sent,
+ * and one whose crossing is gone (pruned a day after it settled) or not settled.
+ */
+async function gateOf(t, row) {
+    if ((row.toolKind !== "mcp" && row.toolKind !== "http") || !row.attempts)
+        return undefined;
+    const crossing = await t.toolCrossing(row.request.effectId);
+    return crossing?.settledAt ? { startedAt: crossing.startedAt, endedAt: crossing.settledAt } : undefined;
+}
+/**
+ * Settles a tool row with `value` (`completed`) or as `cancelled`, and writes its one
+ * `tool.completed` (an agent's tool call), or `node.completed` (a flow's HTTP stage or verifier,
+ * which names no call, R7.1). Writes `row`.
+ */
+export async function settleToolRow(t, s, row, value, options = {}) {
+    const request = row.request;
+    row.status = options.cancelled ? "cancelled" : "completed";
+    row.outcome = { value };
+    row.settledAt = (options.now ?? new Date()).toISOString();
+    await t.put("effects", request.effectId, row);
+    const status = toolCallStatus(row);
+    const gate = await gateOf(t, row);
+    if (isFlowToolEffect(request)) {
+        const durationMs = toolCallDuration(row);
+        await t.event(s.id, request.turnId, "node.completed", {
+            path: request.path,
+            kind: row.toolKind ?? "http",
+            key: request.key,
+            ...(request.iterations !== undefined ? { iterations: request.iterations } : {}),
+            effectId: request.effectId,
+            status,
+            ...(durationMs === undefined ? {} : { durationMs }),
+            ...(gate === undefined ? {} : { gate }),
+        }, options.writer);
+        return row.outcome;
+    }
+    const transcript = toolCompleted(request, value, factsOf(row, status, gate));
+    if (transcript)
+        await t.event(s.id, request.turnId, "tool.completed", transcript, options.writer);
+    return row.outcome;
+}

package/dist/harness-api/tool-status.d.ts

@@ -0,0 +1,13 @@
+/** What a tool row's body says of how it ended. */
+export interface ToolRowState {
+    readonly status: string;
+    readonly outcome?: {
+        readonly value: unknown;
+    };
+    readonly startedAt?: string;
+    readonly settledAt?: string;
+}
+/** How a tool row ended, as `tool.completed` and `/calls/tool` say it. */
+export declare function toolCallStatus(row: ToolRowState): "completed" | "failed" | "cancelled" | "invoking" | "held" | "uncertain";
+/** From the first send to the outcome, or undefined when the call never ran or has not ended. */
+export declare function toolCallDuration(row: ToolRowState): number | undefined;

package/dist/harness-api/tool-status.js

@@ -0,0 +1,26 @@
+/**
+ * How a tool row of the effect journal reads (R5.1, R5.2), from its body alone: shared by the
+ * journal (`tool-journal.ts`) and the session reads (`/calls/tool`).
+ */
+import { durationBetween } from "../tenant/transcript.js";
+/** The codes of a call the Runtime ended rather than the tool: its status is `failed`. */
+const RUNTIME_ENDED = new Set(["tool.disabled", "tool.unavailable", "tool.interrupted", "tool.denied"]);
+/** How a tool row ended, as `tool.completed` and `/calls/tool` say it. */
+export function toolCallStatus(row) {
+    if (row.status === "cancelled")
+        return "cancelled";
+    if (row.status === "held")
+        return "held";
+    if (row.status === "uncertain")
+        return "uncertain";
+    if (row.status !== "completed")
+        return "invoking";
+    const value = row.outcome?.value;
+    return value?.kind === "failed" && typeof value.code === "string" && RUNTIME_ENDED.has(value.code)
+        ? "failed"
+        : "completed";
+}
+/** From the first send to the outcome, or undefined when the call never ran or has not ended. */
+export function toolCallDuration(row) {
+    return durationBetween(row.startedAt, row.settledAt);
+}

package/dist/harness-api/workspace.d.ts

@@ -1,5 +1,6 @@
 import type { CapabilityManifest, SandboxToolName } from "@nylorun/core/define";
 import type { SandboxManager, SandboxSessionRef } from "../sandbox/manager.js";
+import { type DiskOp } from "../sandbox/disk-fs.js";
 import type { SandboxSelectionReport } from "../sandbox/select.js";
 import type { SandboxToolOutcome } from "../sandbox/tools.js";
 import type { SessionStore } from "../store/types.js";
@@ -17,6 +18,8 @@ export interface WorkspacePort {
     listFiles(session: SandboxSessionRef, capability: CapabilityManifest, dir: string, maxEntries: number, signal: AbortSignal): ReturnType<SandboxManager["listFiles"]>;
     /** Reads a file of the workspace of `session` as bytes, at most `maxBytes` (`save_artifact`). */
     readBytes(session: SandboxSessionRef, capability: CapabilityManifest, path: string, maxBytes: number, signal: AbortSignal): ReturnType<SandboxManager["readBytes"]>;
+    /** One operation on the disk of the workspace of `session` (R2d step 3). */
+    disk(session: SandboxSessionRef, capability: CapabilityManifest, op: DiskOp, signal: AbortSignal): ReturnType<SandboxManager["disk"]>;
     report(): Promise<WorkspaceReport>;
     /** One Tenant sweep pass: stop idle workspaces, remove those whose owner is gone. */
     sweep(options: {
@@ -24,8 +27,8 @@ export interface WorkspacePort {
         sessionExists: Exists;
         sandboxExists: Exists;
     }): Promise<void>;
-    /** Deletes sandbox resource `sandboxId`'s workspace (the resource was deleted). */
-    removeSandbox(sandboxId: string): Promise<void>;
+    /** Deletes sandbox resource `environmentId`'s workspace (the resource was deleted). */
+    removeSandbox(environmentId: string): Promise<void>;
     /** Deletes every workspace with its files (a sandboxes reset). */
     removeAll(): Promise<void>;
     close(): Promise<void>;
@@ -48,6 +51,6 @@ export declare function remoteWorkspace(options: RemoteWorkspaceOptions): Worksp
  * everything else goes to `base`. `podOf` says whether a sandbox resource is a pod sandbox.
  */
 export declare function withPodWorkspaces(base: WorkspacePort, options: Omit<RemoteWorkspaceOptions, "pod"> & {
-    readonly isPod: (sandboxId: string) => Promise<boolean>;
+    readonly isPod: (environmentId: string) => Promise<boolean>;
 }): WorkspacePort;
 export {};