@nylorun/runtime 0.22.0-beta → 0.24.0-beta

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

@@ -1,7 +1,7 @@
 /**
  * The Tool Gate's wire format (blueprint §12, F4.1): the routes the loop calls on the gates
- * service for remote MCP servers and HTTP tools. Internal, like the model call route
- * (`contract.ts`): same optional Tenant header, not in the published OpenAPI documents.
+ * service for remote MCP servers and HTTP tools. Like the model call route (`contract.ts`): same
+ * optional Tenant header, bodies published in `@nylorun/core/harness-api` (R4.5).
  *
  * Credentials (F5). A session's MCP requests carry its run token, and the gate takes the
  * session from it: `server.sessionId` is then absent (or the token's). Core's credential
@@ -25,9 +25,9 @@
  * answer, not a gate error. A tool call's failure is coded (`error.failure`, R2b C7), and neither
  * a result nor a failure carries a credential value the gate sent (C8). An answer past 8 MiB is
  * `mcp.too-large` (C11), as an HTTP tool's is `http.too-large`; core shapes what fits into a
- * result the model can take (`tenant/tool-results.ts`). A keyed call whose
- * earlier attempt was lost with the gateway answers `{ok: false, error: {uncertain: true}}` and
- * is never run again.
+ * result the model can take (`tenant/tool-results.ts`). A keyed call whose earlier attempt was
+ * lost with the gateway runs again under the same key (R5.3); one another gateway process holds
+ * answers `{ok: false, error: {uncertain: true}}`, and the caller sends it again.
  *
  * HTTP tools (R2 M3). `POST /nylorun/v1/http-calls` `{tool, effectId, turnId, input}`: one call
  * of an HTTP tool. The loop names the tool (`{sessionId?, agentId?, capabilityId, toolName}`), or a
@@ -36,67 +36,10 @@
  * (`gates/http-tool.ts`). A run token's turn is the call's; `turnId` counts only under core's
  * credential. Keyed like a tool call, and cancelled by the same route. It answers
  * `200 {ok: true, result}` with the tool outcome (a failed request is a failed outcome the
- * model sees), or `{ok: false, error: {uncertain: true}}` for a call lost with the gateway.
+ * model sees), or `{ok: false, error: {uncertain: true}}` for a call another gateway process holds.
  */
-import { z } from "zod";
 import type { McpCallFailure } from "../mcp/connect.js";
-export declare const MCP_CONNECT_PATH = "/nylorun/v1/mcp/connect";
-export declare const MCP_LIST_PATH = "/nylorun/v1/mcp/list";
-export declare const MCP_CLOSE_PATH = "/nylorun/v1/mcp/close";
-export declare const TOOL_CALLS_PATH = "/nylorun/v1/tool-calls";
-export declare const HTTP_CALLS_PATH = "/nylorun/v1/http-calls";
-/** Largest tool call body the gate reads. */
-export declare const MAX_TOOL_BODY_BYTES: number;
-export declare const McpServerRefSchema: z.ZodObject<{
-    sessionId: z.ZodOptional<z.ZodString>;
-    agentId: z.ZodOptional<z.ZodString>;
-    capabilityId: z.ZodString;
-    serverName: z.ZodString;
-}, z.core.$strip>;
-export declare const McpServerBodySchema: z.ZodObject<{
-    server: z.ZodObject<{
-        sessionId: z.ZodOptional<z.ZodString>;
-        agentId: z.ZodOptional<z.ZodString>;
-        capabilityId: z.ZodString;
-        serverName: z.ZodString;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-export declare const McpListBodySchema: z.ZodObject<{
-    server: z.ZodObject<{
-        sessionId: z.ZodOptional<z.ZodString>;
-        agentId: z.ZodOptional<z.ZodString>;
-        capabilityId: z.ZodString;
-        serverName: z.ZodString;
-    }, z.core.$strip>;
-    cursor: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export declare const ToolCallBodySchema: z.ZodObject<{
-    server: z.ZodObject<{
-        sessionId: z.ZodOptional<z.ZodString>;
-        agentId: z.ZodOptional<z.ZodString>;
-        capabilityId: z.ZodString;
-        serverName: z.ZodString;
-    }, z.core.$strip>;
-    effectId: z.ZodString;
-    name: z.ZodString;
-    arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-}, z.core.$strip>;
-export type ToolCallBody = z.infer<typeof ToolCallBodySchema>;
-export declare const HttpCallBodySchema: z.ZodObject<{
-    tool: z.ZodUnion<readonly [z.ZodObject<{
-        sessionId: z.ZodOptional<z.ZodString>;
-        agentId: z.ZodOptional<z.ZodString>;
-        capabilityId: z.ZodString;
-        toolName: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
-        sessionId: z.ZodOptional<z.ZodString>;
-        stage: z.ZodString;
-    }, z.core.$strip>]>;
-    effectId: z.ZodString;
-    turnId: z.ZodString;
-    input: z.ZodUnknown;
-}, z.core.$strip>;
-export type HttpCallBody = z.infer<typeof HttpCallBodySchema>;
+export { HTTP_CALLS_PATH, HttpCallBodySchema, MAX_TOOL_BODY_BYTES, MCP_CLOSE_PATH, MCP_CONNECT_PATH, MCP_LIST_PATH, McpListBodySchema, McpServerBodySchema, McpServerRefSchema, TOOL_CALLS_PATH, ToolCallBodySchema, type HttpCallBody, type ToolCallBody, } from "@nylorun/core/harness-api";
 /** Why an MCP request failed, as the loop's diagnostics read it (`mcp/connect.ts`). */
 export interface McpGateError {
     readonly message: string;
@@ -104,13 +47,12 @@ export interface McpGateError {
     readonly code?: number;
     /** The vault credentials a refused authorization names. */
     readonly credentialIds?: readonly string[];
-    /** The call may have run: its earlier attempt was lost with the gateway. Never re-run. */
+    /** Not answered here: another gateway process holds the keyed call. Send it again (R5.3). */
     readonly uncertain?: boolean;
     /**
      * How the request failed, coded (R2b C1, C7): the loop's `McpCallFailed`, which a tool call
-     * turns into a failed outcome the model sees (`mcp.lost` only for a read-only or idempotent
-     * tool). `credential_rejected` for a `401`, with the server and the scope of the vault whose
-     * credential was sent. Its message has no credential value in it (C8).
+     * turns into a failed outcome the model sees (`mcp.lost` included). `credential_rejected` for a
+     * `401`, with the server. Its message has no credential value in it (C8).
      */
     readonly failure?: McpCallFailure;
 }

package/dist/gates/tool-contract.js

@@ -1,85 +1 @@
-/**
- * The Tool Gate's wire format (blueprint §12, F4.1): the routes the loop calls on the gates
- * service for remote MCP servers and HTTP tools. Internal, like the model call route
- * (`contract.ts`): same optional Tenant header, not in the published OpenAPI documents.
- *
- * Credentials (F5). A session's MCP requests carry its run token, and the gate takes the
- * session from it: `server.sessionId` is then absent (or the token's). Core's credential
- * (`NYLORUN_GATES_TOKEN`) is accepted too, for requests made outside a run, and then
- * `server.sessionId` names the session.
- *
- * Remote MCP. The gate holds the connection and the vault credential; the loop names the
- * server, never a URL or a credential, and the gate finds it in the session's pinned manifest.
- * - `POST /nylorun/v1/mcp/connect` `{server}`: opens the server's connection (vault
- *   authorization included), or keeps the open one. Its result is `{instructions}` when the
- *   server gave instructions at `initialize` (R2b C10, for the note on its deferred tools), else
- *   `null`.
- * - `POST /nylorun/v1/mcp/list` `{server, cursor?}`: one page of `tools/list`.
- * - `POST /nylorun/v1/tool-calls` `{server, effectId, name, arguments}`: one
- *   `tools/call`. With an `Idempotency-Key` (the effect id) the call outlives its client and runs
- *   once (G3); a re-send joins it or gets its outcome.
- * - `POST /nylorun/v1/tool-calls/{key}/cancel`: aborts a keyed call; `204` either way, `403
- *   gate_forbidden` for another session's call under a run token.
- * - `POST /nylorun/v1/mcp/close` `{server}`: closes the server's connection; `204`.
- * Each answers `200 {ok: true, result}` or `200 {ok: false, error}`: an MCP failure is an
- * answer, not a gate error. A tool call's failure is coded (`error.failure`, R2b C7), and neither
- * a result nor a failure carries a credential value the gate sent (C8). An answer past 8 MiB is
- * `mcp.too-large` (C11), as an HTTP tool's is `http.too-large`; core shapes what fits into a
- * result the model can take (`tenant/tool-results.ts`). A keyed call whose
- * earlier attempt was lost with the gateway answers `{ok: false, error: {uncertain: true}}` and
- * is never run again.
- *
- * HTTP tools (R2 M3). `POST /nylorun/v1/http-calls` `{tool, effectId, turnId, input}`: one call
- * of an HTTP tool. The loop names the tool (`{sessionId?, agentId?, capabilityId, toolName}`), or a
- * flow's HTTP stage or HTTP verifier by its stage key (`{sessionId?, stage}`); the gate finds its
- * URL, method and credential in the session's pinned manifest
- * (`gates/http-tool.ts`). A run token's turn is the call's; `turnId` counts only under core's
- * credential. Keyed like a tool call, and cancelled by the same route. It answers
- * `200 {ok: true, result}` with the tool outcome (a failed request is a failed outcome the
- * model sees), or `{ok: false, error: {uncertain: true}}` for a call lost with the gateway.
- */
-import { z } from "zod";
-export const MCP_CONNECT_PATH = "/nylorun/v1/mcp/connect";
-export const MCP_LIST_PATH = "/nylorun/v1/mcp/list";
-export const MCP_CLOSE_PATH = "/nylorun/v1/mcp/close";
-export const TOOL_CALLS_PATH = "/nylorun/v1/tool-calls";
-export const HTTP_CALLS_PATH = "/nylorun/v1/http-calls";
-/** Largest tool call body the gate reads. */
-export const MAX_TOOL_BODY_BYTES = 8 * 1024 * 1024;
-export const McpServerRefSchema = z.object({
-    /** Required with core's credential; a run token names the session itself. */
-    sessionId: z.string().min(1).optional(),
-    agentId: z.string().min(1).optional(),
-    capabilityId: z.string().min(1),
-    serverName: z.string().min(1),
-});
-export const McpServerBodySchema = z.object({ server: McpServerRefSchema });
-export const McpListBodySchema = z.object({
-    server: McpServerRefSchema,
-    cursor: z.string().optional(),
-});
-export const ToolCallBodySchema = z.object({
-    server: McpServerRefSchema,
-    effectId: z.string().min(1),
-    name: z.string().min(1),
-    arguments: z.record(z.string(), z.unknown()),
-});
-export const HttpCallBodySchema = z.object({
-    tool: z.union([
-        z.object({
-            /** Required with core's credential; a run token names the session itself. */
-            sessionId: z.string().min(1).optional(),
-            agentId: z.string().min(1).optional(),
-            capabilityId: z.string().min(1),
-            toolName: z.string().min(1),
-        }),
-        z.object({
-            sessionId: z.string().min(1).optional(),
-            /** A flow's HTTP stage or HTTP verifier. */
-            stage: z.string().min(1),
-        }),
-    ]),
-    effectId: z.string().min(1),
-    turnId: z.string().min(1),
-    input: z.unknown(),
-});
+export { HTTP_CALLS_PATH, HttpCallBodySchema, MAX_TOOL_BODY_BYTES, MCP_CLOSE_PATH, MCP_CONNECT_PATH, MCP_LIST_PATH, McpListBodySchema, McpServerBodySchema, McpServerRefSchema, TOOL_CALLS_PATH, ToolCallBodySchema, } from "@nylorun/core/harness-api";

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

@@ -28,7 +28,7 @@ export interface ToolGate {
     /**
      * True when a keyed MCP or HTTP tool call outlives the caller's process (the gates service,
      * G3): after a takeover or a shutdown, re-sending it joins the call or returns its outcome,
-     * and a call lost with the gateway answers `uncertain` instead of running again.
+     * and a call lost with the gateway runs again under the same key (R5.3).
      */
     readonly recovers?: boolean;
     /** Stops a keyed tool call that outlives its caller (a user cancel). Never rejects. */

package/dist/harness/calls.d.ts

@@ -26,7 +26,7 @@ export interface ToolRouting {
     readonly mcpSnapshot?: McpSnapshot;
     /** The session that owns the tree's sandbox, and the sandbox resource it is attached to. */
     readonly sandboxOwnerId: 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>>;
     readonly activeTurnId: string | null;
@@ -36,9 +36,12 @@ export interface ToolRouting {
 /**
  * Call the model for one effect. A provider failure comes back as a failure outcome
  * (Model Calls §6), whichever provider serves the call; only an abort throws, and the
- * advance decides what the abort means.
+ * advance decides what the abort means. `atGate` sends the call to the Model Gate even when the
+ * Tenant's model is not from the vault: the Tenant's fixture model is answered there (R4.3).
  */
-export declare function invokeModel(route: ModelRoute, request: HostEffect, signal: AbortSignal, model?: ModelProvider): Promise<unknown>;
+export declare function invokeModel(route: ModelRoute, request: HostEffect, signal: AbortSignal, options?: {
+    readonly atGate?: boolean;
+}): Promise<unknown>;
 /**
  * A signal that follows `signal` only for the abort kinds in `kinds`. An MCP call stops on a
  * cancel; at the Tool Gate it also stops waiting on a shutdown, since the gate keeps the call
@@ -52,11 +55,15 @@ export declare function isSaveArtifactCall(manifest: AgentManifest | undefined,
 export declare function isReadArtifactCall(manifest: AgentManifest | undefined, request: HostEffect): boolean;
 /** True when `request` calls a tool of a declared MCP server (every one is remote). */
 export declare function isRemoteMcpCall(routing: Pick<ToolRouting, "rootManifest" | "mcpSnapshot">, request: HostEffect): boolean;
-export declare function callMcpTool(mcp: McpPool, routing: ToolRouting, request: HostEffect, signal: AbortSignal): Promise<unknown>;
+export declare function callMcpTool(mcp: McpPool, routing: ToolRouting, request: HostEffect, signal: AbortSignal, 
+/** The call's span context (R7.4), sent as `traceparent` where this process holds the connection. */
+traceparent?: string): Promise<unknown>;
 /**
  * Calls an HTTP tool through the Tool Gate (R2 M3), keyed by the effect id: an agent's (the
  * effect's agent used as a tool, or the root), or a flow's HTTP stage or HTTP verifier. Its
  * outcome is the effect's value; a throw leaves the effect `uncertain`.
  */
-export declare function callHttpTool(gate: Pick<ToolGate, "callHttp">, request: HostEffect, signal: AbortSignal): Promise<unknown>;
+export declare function callHttpTool(gate: Pick<ToolGate, "callHttp">, request: HostEffect, signal: AbortSignal, 
+/** The call's span context (R7.4); the gates service reads its own from the journal. */
+traceparent?: string): Promise<unknown>;
 export declare function callSandboxTool(sandbox: SandboxManager, routing: ToolRouting, request: HostEffect, signal: AbortSignal): Promise<unknown>;

package/dist/harness/calls.js

@@ -13,13 +13,13 @@ import { sandboxCapabilityOf } from "../sandbox/capability.js";
 /**
  * Call the model for one effect. A provider failure comes back as a failure outcome
  * (Model Calls §6), whichever provider serves the call; only an abort throws, and the
- * advance decides what the abort means.
+ * advance decides what the abort means. `atGate` sends the call to the Model Gate even when the
+ * Tenant's model is not from the vault: the Tenant's fixture model is answered there (R4.3).
  */
-export async function invokeModel(route, request, signal, model) {
+export async function invokeModel(route, request, signal, options = {}) {
+    const atGate = route.useVaultModel || options.atGate === true;
     try {
-        if (model)
-            return await model(request, signal);
-        if (!route.useVaultModel)
+        if (!atGate)
             return await route.modelProvider(request, signal);
         return await route.modelGate.call({
             tenantId: route.tenantId,
@@ -35,7 +35,7 @@ export async function invokeModel(route, request, signal, model) {
         if (signal.aborted) {
             // A call that outlives this process stops only when told to: on a user cancel. After a
             // shutdown or a lost lease the next owner re-sends it and picks up its outcome (P1.2).
-            if (!model && route.useVaultModel && runAbortKind(signal) === "cancel" && route.modelGate.cancel)
+            if (atGate && runAbortKind(signal) === "cancel" && route.modelGate.cancel)
                 await route.modelGate.cancel({
                     tenantId: route.tenantId,
                     sessionId: request.sessionId,
@@ -89,7 +89,9 @@ export function isRemoteMcpCall(routing, request) {
         return false;
     return findServer(routing.rootManifest, tool.agentId, tool.capabilityId, tool.serverName) !== undefined;
 }
-export async function callMcpTool(mcp, routing, request, signal) {
+export async function callMcpTool(mcp, routing, request, signal, 
+/** The call's span context (R7.4), sent as `traceparent` where this process holds the connection. */
+traceparent) {
     const tool = mcpToolOf(routing.mcpSnapshot, request);
     if (!tool)
         throw new Error(`MCP tool '${request.toolName ?? ""}' is not in the session snapshot`);
@@ -102,8 +104,7 @@ export async function callMcpTool(mcp, routing, request, signal) {
         args: request.input,
         manifest: routing.rootManifest,
         effectId: request.effectId,
-        // A read-only or idempotent tool's lost answer is the model's to retry (R2b C7, Q15).
-        retrySafe: tool.annotations?.readOnlyHint === true || tool.annotations?.idempotentHint === true,
+        ...(traceparent ? { traceparent } : {}),
         signal,
     });
 }
@@ -112,10 +113,18 @@ export async function callMcpTool(mcp, routing, request, signal) {
  * effect's agent used as a tool, or the root), or a flow's HTTP stage or HTTP verifier. Its
  * outcome is the effect's value; a throw leaves the effect `uncertain`.
  */
-export async function callHttpTool(gate, request, signal) {
+export async function callHttpTool(gate, request, signal, 
+/** The call's span context (R7.4); the gates service reads its own from the journal. */
+traceparent) {
     if (!gate.callHttp)
         throw new Error("This Runtime has no Tool Gate for HTTP tools");
-    return gate.callHttp({ tool: httpToolRefOf(request), effectId: request.effectId, turnId: request.turnId, input: request.input }, signal);
+    return gate.callHttp({
+        tool: httpToolRefOf(request),
+        effectId: request.effectId,
+        turnId: request.turnId,
+        input: request.input,
+        ...(traceparent ? { traceparent } : {}),
+    }, signal);
 }
 export async function callSandboxTool(sandbox, routing, request, signal) {
     const capability = sandboxCapabilityOf(manifestFor(routing.rootManifest, request.agent), request.capabilityId, request.toolName);
@@ -126,7 +135,7 @@ export async function callSandboxTool(sandbox, routing, request, signal) {
         id: routing.sandboxOwnerId,
         activeTurnId: routing.activeTurnId,
         manifest: routing.rootManifest,
-        ...(routing.sandboxId === undefined ? {} : { sandboxId: routing.sandboxId }),
+        ...(routing.environmentId === undefined ? {} : { environmentId: routing.environmentId }),
         ...(routing.environment === undefined ? {} : { environment: routing.environment }),
         ...(routing.claim === undefined ? {} : { claim: routing.claim }),
     }, capability, request.toolName, request.input, signal);

package/dist/harness/executors.js

@@ -8,13 +8,11 @@
  * (`--service harness`, `main.ts`) its own, whose sandbox events it claims from core.
  */
 import { hashManifest } from "@nylorun/core/define";
-import { toolFixtureModel } from "../core/provider.js";
+import { GateCallLost } from "../gates/tool-client.js";
 import { serversOf } from "../mcp/pool.js";
 import { mcpToolOf } from "../mcp/snapshot.js";
 import { isHttpToolCall } from "../gates/http-tool.js";
 import { abortOn, callHttpTool, callMcpTool, callSandboxTool, invokeModel, isRemoteMcpCall, isSaveArtifactCall, } from "./calls.js";
-/** The Tenant's model of the fixture-model setting. Stateless. */
-const fixture = toolFixtureModel();
 export function harnessExecutors(options) {
     const recoversTools = options.toolGate.recovers === true;
     const atGate = (effect, run) => {
@@ -23,16 +21,19 @@ export function harnessExecutors(options) {
     };
     const recovered = (effect, run) => recoversTools && atGate(effect, run);
     return {
-        model: (effect, signal, run) => invokeModel(options.model, effect, signal, run.start.options.fixtureModel ? fixture : undefined),
-        tool(effect, signal, run) {
+        // With the Tenant's fixture model on, the Model Gate answers it (R4.3), metered like any call.
+        model: (effect, signal, run) => invokeModel(options.model, effect, signal, { atGate: run.start.options.fixtureModel }),
+        tool(effect, signal, run, call) {
             const routing = routingOf(run);
+            const traceparent = call?.traceparent;
             // A call at the Tool Gate outlives a shutdown there; a local one finishes and is recorded.
             const kinds = recovered(effect, run) ? ["cancel", "shutdown"] : ["cancel"];
             if (isHttpToolCall(routing.rootManifest, effect))
-                return callHttpTool(options.toolGate, effect, abortOn(signal, kinds));
+                return callHttpTool(options.toolGate, effect, abortOn(signal, kinds), traceparent);
+            // A sandbox command joins its call's span (R7.4): a CLI that reads TRACEPARENT traces under it.
             if (!mcpToolOf(routing.mcpSnapshot, effect))
-                return callSandboxTool(options.sandbox(), routing, effect, signal);
-            return callMcpTool(options.mcp, routing, effect, abortOn(signal, kinds));
+                return callSandboxTool(options.sandbox(), traceparent ? { ...routing, environment: { ...routing.environment, TRACEPARENT: traceparent } } : routing, effect, signal);
+            return callMcpTool(options.mcp, routing, effect, abortOn(signal, kinds), traceparent);
         },
         recovers: {
             get model() {
@@ -40,6 +41,8 @@ export function harnessExecutors(options) {
             },
             tool: recovered,
         },
+        // A gate hop that lost the answer: the call is sent again with its key (R5.3).
+        resends: (effect, error, run) => error instanceof GateCallLost && atGate(effect, run),
         async cancelAtGate(effect) {
             await options.toolGate.cancel?.({
                 tenantId: options.model.tenantId,
@@ -94,7 +97,7 @@ export function routingOf(run) {
         rootManifest: routing.rootManifest,
         ...(routing.mcpSnapshot ? { mcpSnapshot: routing.mcpSnapshot } : {}),
         sandboxOwnerId: routing.sandbox?.ownerId ?? run.grant.sessionId,
-        ...(routing.sandbox?.sandboxId === undefined ? {} : { sandboxId: routing.sandbox.sandboxId }),
+        ...(routing.sandbox?.environmentId === undefined ? {} : { environmentId: routing.sandbox.environmentId }),
         ...(routing.sandbox?.environment === undefined ? {} : { environment: routing.sandbox.environment }),
         activeTurnId: run.grant.turnId,
         claim: run.runId,

package/dist/harness/main.js

@@ -10,8 +10,9 @@
  *
  * In a pod sandbox (`NYLORUN_SANDBOX_KIND=pod`, F7.2) it is that sandbox's engine: it first waits
  * until the pod's NetworkPolicy is in force (`awaitNetworkPolicy`), then joins with the
- * pod's join token instead of a harness token (`pod.ts`), and runs its sandbox's tools in the
- * pod itself (the `local` backend), with egress through egress-gate. SIGTERM (tini forwards
+ * pod's join token instead of a harness token (`pod.ts`), runs its disk's setup on a new volume
+ * (`setup.ts`), and runs its sandbox's tools in the pod itself (the `local` backend), with egress
+ * through egress-gate. SIGTERM (tini forwards
  * it; the pod's grace is 10 s by default) gives its runs back and exits.
  */
 import { mkdirSync } from "node:fs";
@@ -21,9 +22,10 @@ import { httpModelGate } from "../gates/http-client.js";
 import { httpToolGate } from "../gates/tool-client.js";
 import { createHostLogger } from "../host/logger.js";
 import { RUNTIME_VERSION } from "../version.js";
-import { localBackend } from "../adapters/sandbox/local.js";
+import { localBackend, localExec } from "../adapters/sandbox/local.js";
 import { awaitNetworkPolicy } from "../sandbox/pods/network-gate.js";
 import { podHost } from "./pod.js";
+import { prepareDisk } from "./setup.js";
 import { harnessRunTokens } from "./run-tokens.js";
 import { startHarnessService } from "./service.js";
 /**
@@ -48,6 +50,16 @@ export async function runHarness(stack, baseline) {
             volumeFile: join(config.root, "volume-id"),
             caBundleFile: join(config.root, "egress-ca-bundle.pem"),
         });
+        // Join, then make the disk ready (R2d step 2) before taking any turn.
+        await pod.token();
+        const host = pod;
+        await prepareDisk({
+            host,
+            exec: localExec({ env: baseline, proxyEnv: () => host.proxyEnv() }),
+            volumeFile: join(config.root, "volume-id"),
+            markerFile: join(config.root, "setup.json"),
+            logger,
+        });
     }
     const token = pod ? () => pod.token() : config.token;
     if (token === undefined)
@@ -56,13 +68,14 @@ export async function runHarness(stack, baseline) {
     const service = startHarnessService({
         url: config.url,
         token,
-        ...(pod ? { sandboxBackends: [localBackend({ env: baseline, proxyEnv: () => pod.proxyEnv() })] } : {}),
+        ...(pod
+            ? { sandboxBackends: [localBackend({ env: baseline, proxyEnv: () => pod.proxyEnv(), harnessRoot: config.root })] }
+            : {}),
         paths,
         modelGate: httpModelGate({ url: config.gatesUrl, runTokens }),
         useVaultModel: true,
         toolGate: httpToolGate({ url: config.gatesUrl, runTokens }),
         logger,
-        name: pod ? `sandbox ${config.pod.sandboxId}` : "harness",
         version: RUNTIME_VERSION,
         onGrant: (grant) => runTokens.grant(grant),
     });

package/dist/harness/pod.d.ts

@@ -1,6 +1,27 @@
 import type { PodHostConfig } from "../host/stack-config.js";
 /** How often the host and egress tokens are renewed. */
 export declare const RENEW_MS: number;
+/** What to run and copy on a new disk (`sandbox/setup.ts` in core), from the join answer. */
+export interface DiskSetup {
+    readonly recipeVersion: number;
+    readonly commands: readonly {
+        readonly command: string;
+        readonly cwd: string;
+        readonly timeoutMs: number;
+    }[];
+    readonly files: readonly {
+        readonly index: number;
+        readonly path: string;
+    }[];
+    readonly environment: Readonly<Record<string, string>>;
+}
+/** How a setup ended, as the engine reports it. */
+export interface DiskSetupReport {
+    readonly status: "ok" | "failed";
+    readonly index?: number;
+    readonly exitCode?: number;
+    readonly output?: string;
+}
 export interface PodHost {
     /** A current host token, for the next connection. Throws when neither renewal nor join works. */
     token(): Promise<string>;
@@ -8,6 +29,19 @@ export interface PodHost {
     proxyEnv(): Record<string, string>;
     /** The host epoch of the tokens held. */
     readonly epoch: number | undefined;
+    /** The disk's setup from the last join, if its recipe has one. */
+    readonly setup: DiskSetup | undefined;
+    /** The last join's volume starts from a disk version core writes: no setup runs on it. */
+    readonly seeded: boolean;
+    /** Whether to run the setup again after a failure, with the plan to run now. */
+    setupState(): Promise<{
+        retry: boolean;
+        setup?: DiskSetup;
+    }>;
+    /** Reports how the setup ended. */
+    reportSetup(report: DiskSetupReport): Promise<void>;
+    /** Input file `index` (a file's bytes or a folder's listing), or one file of a folder. */
+    setupFile(index: number, path?: string): Promise<Response>;
     stop(): void;
 }
 export declare function podHost(config: PodHostConfig, logger: {

package/dist/harness/pod.js

@@ -31,6 +31,8 @@ class Refused extends Error {
 export function podHost(config, logger, options = {}) {
     const call = options.fetch ?? fetch;
     let held;
+    let setup;
+    let seeded = false;
     /** The CA in the bundle on disk, once one is written. */
     let bundled;
     const post = async (path, init) => {
@@ -51,6 +53,10 @@ export function podHost(config, logger, options = {}) {
         const body = JSON.parse(text);
         if (typeof body.caCertificate === "string")
             await writeBundle(body.caCertificate);
+        if (path === "join") {
+            setup = body.setup;
+            seeded = body.seeded === true;
+        }
         return {
             hostToken: body.hostToken,
             egressToken: body.egressToken,
@@ -99,6 +105,15 @@ export function podHost(config, logger, options = {}) {
         logger.info("sandbox_host_joined", { sandboxId: config.sandboxId, epoch: held.epoch });
         return held;
     };
+    /** A request with a current host token: the held one, renewed near expiry, or a new join. */
+    const authorized = async (path, init) => {
+        const current = held && held.expiresAt - Date.now() > 60_000 ? held : ((await renew()) ?? (await join()));
+        return call(`${config.httpUrl}/nylorun/harness/v1/host/${path}`, {
+            ...init,
+            headers: { ...init.headers, authorization: `Bearer ${current.hostToken}` },
+            signal: AbortSignal.timeout(5 * 60_000),
+        });
+    };
     const renew = async () => {
         if (!held)
             return undefined;
@@ -147,6 +162,32 @@ export function podHost(config, logger, options = {}) {
         get epoch() {
             return held?.epoch;
         },
+        get setup() {
+            return setup;
+        },
+        get seeded() {
+            return seeded;
+        },
+        async setupState() {
+            const response = await authorized("setup", { method: "GET" });
+            if (!response.ok)
+                throw new Error(`host/setup answered ${response.status}`);
+            return (await response.json());
+        },
+        async reportSetup(report) {
+            const response = await authorized("setup", {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(report),
+            });
+            await response.body?.cancel();
+            if (!response.ok)
+                throw new Error(`host/setup answered ${response.status}`);
+        },
+        setupFile(index, path) {
+            const suffix = path === undefined ? "" : `/${path.split("/").map(encodeURIComponent).join("/")}`;
+            return authorized(`files/${index}${suffix}`, { method: "GET" });
+        },
         stop() {
             clearInterval(timer);
         },

package/dist/harness/service.d.ts

@@ -31,7 +31,6 @@ export interface HarnessServiceOptions {
     /** Delete the workspaces on stop (an ephemeral Runtime's loopback harness). */
     readonly ephemeral?: boolean;
     readonly logger: HarnessClientOptions["logger"];
-    readonly name?: string;
     readonly version?: string;
     readonly onGrant?: HarnessOptions["onGrant"];
     readonly backoff?: HarnessClientOptions["backoff"];

package/dist/harness/service.js

@@ -9,8 +9,9 @@
  * keeps its compute records in `<sandboxes>/records.json` and claims its events from core
  * (`event`): for the run that made the call, or the workspace request core sent.
  */
+import { fromWireOp, toWireAnswer } from "../sandbox/disk-fs.js";
 import { join } from "node:path";
-import { HarnessApiError, } from "@nylorun/core/harness-api";
+import { DEFAULT_HARNESS, HarnessApiError, } from "@nylorun/core/harness-api";
 import { McpPool } from "../mcp/pool.js";
 import { SandboxManager } from "../sandbox/manager.js";
 import { fileSandboxRecords, workspacePrefix } from "../sandbox/records.js";
@@ -33,7 +34,7 @@ function refOf(session) {
     return {
         id: session.ownerId,
         activeTurnId: session.activeTurnId,
-        ...(session.sandboxId === undefined ? {} : { sandboxId: session.sandboxId }),
+        ...(session.environmentId === undefined ? {} : { environmentId: session.environmentId }),
     };
 }
 const noModel = async () => {
@@ -78,6 +79,12 @@ export function startHarnessService(options) {
             case "workspace.read":
             case "workspace.write":
             case "workspace.exec": {
+                if ("disk" in params) {
+                    // A disk version's read or write (R2d step 3).
+                    const call = params;
+                    const answer = await sandbox().disk(refOf(call.session), { id: "sandbox", type: "agent", sandbox: call.spec, tools: [] }, fromWireOp(call.disk), signal);
+                    return "code" in answer ? answer : toWireAnswer(answer);
+                }
                 if (method === "workspace.read" && "list" in params) {
                     const call = params;
                     return sandbox().listFiles(refOf(call.session), { id: "sandbox", type: "agent", sandbox: call.spec, tools: [] }, call.list.dir, call.list.maxEntries, signal);
@@ -102,7 +109,7 @@ export function startHarnessService(options) {
                 return { workspaces: await sandbox().workspaces() };
             }
             case "workspace.remove": {
-                const { keys, sandboxIds, all } = params;
+                const { keys, environmentIds, all } = params;
                 const workspaces = sandbox();
                 if (all) {
                     await workspaces.reconcile(() => false, () => false);
@@ -114,7 +121,7 @@ export function startHarnessService(options) {
                         throw new HarnessApiError("invalid", `${key} is not a workspace of this Tenant`);
                     await workspaces.remove(key);
                 }
-                for (const id of sandboxIds ?? [])
+                for (const id of environmentIds ?? [])
                     await workspaces.removeSandbox(id);
                 return {};
             }
@@ -128,7 +135,8 @@ export function startHarnessService(options) {
         logger,
         executors,
         serve,
-        name: options.name ?? "harness",
+        // Our harness: its hello names our harness id (R4.1).
+        name: DEFAULT_HARNESS,
         ...(options.version ? { version: options.version } : {}),
         capabilities: { workspace: { backends: backends.map((backend) => backend.name) } },
         onHello(answer) {