@nylorun/runtime 0.22.0-beta → 0.24.0-beta

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 {};

package/dist/harness-api/workspace.js

@@ -15,9 +15,10 @@
  * - **Pod sandboxes** (F7.2, `withPodWorkspaces`): a session attached to a pod sandbox has its
  *   workspace in the pod, served by the sandbox's engine (its host connection). Its tool calls,
  *   listings and reads go there whatever serves the other workspaces; with the pod stopped or
- *   starting they are `409 sandbox_unavailable`.
+ *   starting they are `409 environment_unavailable`.
  */
 import { HarnessApiError } from "@nylorun/core/harness-api";
+import { fromWireAnswer, toWireOp } from "../sandbox/disk-fs.js";
 import { DEFAULT_SANDBOX_IMAGE } from "../sandbox/policy.js";
 import { fail } from "../tenant/http.js";
 import { NoWorkspaceHarness } from "./server.js";
@@ -27,9 +28,10 @@ export function localWorkspace(manager) {
         run: (session, capability, toolName, input, signal) => manager.run(session, capability, toolName, input, signal),
         listFiles: (session, capability, dir, maxEntries, signal) => manager.listFiles(session, capability, dir, maxEntries, signal),
         readBytes: (session, capability, path, maxBytes, signal) => manager.readBytes(session, capability, path, maxBytes, signal),
+        disk: (session, capability, op, signal) => manager.disk(session, capability, op, signal),
         report: () => manager.report(),
         sweep: (options) => manager.sweep(options),
-        removeSandbox: (sandboxId) => manager.removeSandbox(sandboxId),
+        removeSandbox: (environmentId) => manager.removeSandbox(environmentId),
         removeAll: () => manager.reconcile(() => false, () => false),
         close: () => manager.close(),
     };
@@ -45,7 +47,7 @@ const METHODS = {
 function sessionOf(session) {
     return {
         ownerId: session.id,
-        ...(session.sandboxId === undefined ? {} : { sandboxId: session.sandboxId }),
+        ...(session.environmentId === undefined ? {} : { environmentId: session.environmentId }),
         activeTurnId: session.activeTurnId,
     };
 }
@@ -55,7 +57,7 @@ export function remoteWorkspace(options) {
     const target = options.pod === undefined ? undefined : { pod: options.pod };
     const unavailable = (error) => error.pod === undefined
         ? fail(503, error.message, { code: "request_rejected" })
-        : fail(409, error.message, { code: "sandbox_unavailable" });
+        : fail(409, error.message, { code: "environment_unavailable" });
     /** The harness's answer, or `undefined` when none serves workspaces. */
     const ask = async (method, params, signal) => {
         try {
@@ -74,9 +76,9 @@ export function remoteWorkspace(options) {
         const { workspaces } = answer;
         const gone = [];
         for (const record of workspaces) {
-            const kept = record.sandboxId === undefined
+            const kept = record.environmentId === undefined
                 ? await sessionExists(record.sessionId)
-                : await sandboxExists(record.sandboxId);
+                : await sandboxExists(record.environmentId);
             if (!kept)
                 gone.push(record.key);
         }
@@ -154,6 +156,19 @@ export function remoteWorkspace(options) {
                 throw error;
             }
         },
+        async disk(session, capability, op, signal) {
+            try {
+                const answer = (await options.server.workspace("list" in op || "read" in op ? "workspace.read" : "workspace.write", { session: sessionOf(session), spec: capability.sandbox ?? {}, disk: toWireOp(op) }, signal, target));
+                return answer.kind === "failed"
+                    ? { kind: "failed", code: String(answer.code), message: String(answer.message) }
+                    : fromWireAnswer(answer);
+            }
+            catch (error) {
+                if (error instanceof NoWorkspaceHarness)
+                    return unavailable(error);
+                throw error;
+            }
+        },
         async report() {
             const answer = await ask("workspace.report", {}).catch(() => undefined);
             if (answer)
@@ -168,12 +183,12 @@ export function remoteWorkspace(options) {
             };
         },
         sweep: (pass) => sweep(pass.sessionExists, pass.sandboxExists, pass.now),
-        async removeSandbox(sandboxId) {
+        async removeSandbox(environmentId) {
             // With no harness connected, the next sweep removes it: its resource is gone.
-            await ask("workspace.remove", { sandboxIds: [sandboxId] });
+            await ask("workspace.remove", { environmentIds: [environmentId] });
             await store.tx(async (t) => {
                 for (const row of await t.listSandboxes())
-                    if (row.sandboxId === sandboxId)
+                    if (row.environmentId === environmentId)
                         await t.delete("sandboxes", row.key);
             });
         },
@@ -188,13 +203,14 @@ export function remoteWorkspace(options) {
  * everything else goes to `base`. `podOf` says whether a sandbox resource is a pod sandbox.
  */
 export function withPodWorkspaces(base, options) {
-    const routed = async (session) => session.sandboxId !== undefined && (await options.isPod(session.sandboxId))
-        ? remoteWorkspace({ ...options, pod: session.sandboxId })
+    const routed = async (session) => session.environmentId !== undefined && (await options.isPod(session.environmentId))
+        ? remoteWorkspace({ ...options, pod: session.environmentId })
         : base;
     return {
         ...base,
         run: async (session, capability, toolName, input, signal) => (await routed(session)).run(session, capability, toolName, input, signal),
         listFiles: async (session, capability, dir, maxEntries, signal) => (await routed(session)).listFiles(session, capability, dir, maxEntries, signal),
         readBytes: async (session, capability, path, maxBytes, signal) => (await routed(session)).readBytes(session, capability, path, maxBytes, signal),
+        disk: async (session, capability, op, signal) => (await routed(session)).disk(session, capability, op, signal),
     };
 }

package/dist/harness-api/ws-server.d.ts

@@ -1,11 +1,14 @@
 import { type Server } from "node:http";
 import { type HarnessChannel } from "@nylorun/core/harness-api";
+import { HOST_JOIN_PATH, HOST_RENEW_PATH } from "@nylorun/core/harness-api";
 import { type WsPortOptions } from "../harness/ws-port.js";
 import { type HostAuthority } from "../sandbox/join.js";
 import type { HarnessPeer } from "./server.js";
-/** Where a pod's engine exchanges its join token, and renews its host token. */
-export declare const HOST_JOIN_PATH = "/nylorun/harness/v1/host/join";
-export declare const HOST_RENEW_PATH = "/nylorun/harness/v1/host/renew";
+export { HOST_JOIN_PATH, HOST_RENEW_PATH };
+/** Where a pod's engine reads its setup and reports it (R2d step 2, `sandbox/setup.ts`). */
+export declare const HOST_SETUP_PATH = "/nylorun/harness/v1/host/setup";
+/** Where it reads its input files: `/{index}`, and a folder's file `/{index}/{path}`. */
+export declare const HOST_FILES_PATH = "/nylorun/harness/v1/host/files";
 /** Attaches a harness's channel to the open Tenant; returns a function that detaches it. */
 export type HarnessAttach = (channel: HarnessChannel, peer: HarnessPeer) => () => void;
 export interface HarnessListenerOptions {
@@ -17,6 +20,11 @@ export interface HarnessListenerOptions {
     readonly token?: string;
     /** The open Tenant's `attachHarness`, or undefined while there is none. */
     readonly attach: () => Promise<HarnessAttach | undefined>;
+    /**
+     * The custom harness a per-harness token is for (R4.1), or undefined. Absent, only the harness
+     * token and host tokens are accepted.
+     */
+    readonly harnessOfToken?: (token: string) => Promise<string | undefined>;
     /** The open Tenant's host authority (sandbox pods, F7.2), or undefined without one. */
     readonly hosts?: () => Promise<HostAuthority | undefined>;
     readonly logger: {