@nylorun/runtime 0.23.0-beta → 0.24.0-beta

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) {

package/dist/harness/setup.d.ts

@@ -0,0 +1,27 @@
+import type { ExecRequest, ExecResult } from "../sandbox/types.js";
+import type { PodHost } from "./pod.js";
+/** How often a failed setup asks whether to run again. */
+export declare const SETUP_RETRY_POLL_MS = 5000;
+export interface DiskSetupOptions {
+    readonly host: Pick<PodHost, "setup" | "setupState" | "reportSetup" | "setupFile"> & {
+        /** The volume starts from a disk version (R2d step 3): it holds what setup made. */
+        readonly seeded?: boolean;
+    };
+    /** Runs one command as the sandbox tools do (`localExec`). */
+    readonly exec: (request: ExecRequest, signal: AbortSignal) => Promise<ExecResult>;
+    /** The volume's id file (`/harness/volume-id`). */
+    readonly volumeFile: string;
+    /** The marker (`/harness/setup.json`). */
+    readonly markerFile: string;
+    readonly logger: {
+        info(message: string, fields?: Record<string, unknown>): void;
+        warn(message: string, fields?: Record<string, unknown>): void;
+    };
+    readonly pollMs?: number;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Runs the disk's setup when this volume has not had it, reports how it ended, and after a
+ * failure waits for core to ask for it again. Resolves once the setup is done (or there is none).
+ */
+export declare function prepareDisk(options: DiskSetupOptions): Promise<void>;

package/dist/harness/setup.js

@@ -0,0 +1,150 @@
+/**
+ * The disk's setup in a pod Environment's engine (R2d step 2): after it joins and before it takes
+ * any turn, the engine copies the recipe's input files and runs its setup commands, once per
+ * volume. A marker on the volume (`/harness/setup.json`, `{ volumeId, recipeVersion, status }`)
+ * says it was done: a resume finds it and skips, a reset (a new volume, a new volume id) runs it
+ * again. Commands run as the sandbox tools' do (`localExec`): `/bin/sh -c` in `cwd`, with the
+ * Environment's variables and secrets (as the sentinel) and egress through egress-gate.
+ *
+ * A failure is reported to core, which fails the pod and the turn waiting for it; the engine then
+ * polls until a turn start asks the pod to run again, and runs the setup again from the start.
+ */
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname, posix } from "node:path";
+/** How often a failed setup asks whether to run again. */
+export const SETUP_RETRY_POLL_MS = 5_000;
+/** The end of a failed command's output kept in its report. */
+const REPORT_TAIL = 4 * 1024;
+async function readText(path) {
+    try {
+        return (await readFile(path, "utf8")).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Writes `bytes` at `path`, by way of a temporary name, creating its directory. */
+async function writeAtomic(path, bytes) {
+    await mkdir(dirname(path), { recursive: true });
+    const next = `${path}.${randomUUID()}.tmp`;
+    await writeFile(next, bytes);
+    await rename(next, path);
+}
+/** A folder entry's path joined under `base`, refused when it would leave it. */
+function under(base, relative) {
+    const joined = posix.normalize(posix.join(base, relative));
+    if (joined !== base && !joined.startsWith(`${base.replace(/\/$/, "")}/`))
+        throw new Error(`${relative} would leave ${base}`);
+    return joined;
+}
+/** Copies input file `file` into place: a file artifact at its path, a folder under it. */
+async function copyFile(host, file) {
+    const first = await host.setupFile(file.index);
+    if (!first.ok)
+        throw new Error(`input file ${file.index + 1} answered ${first.status}`);
+    if (first.headers.get("x-nylorun-artifact-kind") !== "folder") {
+        await writeAtomic(file.path, new Uint8Array(await first.arrayBuffer()));
+        return;
+    }
+    const { entries } = (await first.json());
+    for (const entry of entries) {
+        const answer = await host.setupFile(file.index, entry.path);
+        if (!answer.ok)
+            throw new Error(`input file ${file.index + 1}, ${entry.path}, answered ${answer.status}`);
+        await writeAtomic(under(file.path, entry.path), new Uint8Array(await answer.arrayBuffer()));
+    }
+}
+/** Runs `setup` once: files first, then commands in order; the report of how it ended. */
+async function runOnce(options, setup) {
+    for (const file of setup.files) {
+        try {
+            await copyFile(options.host, file);
+        }
+        catch (error) {
+            return { status: "failed", output: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    for (const [index, command] of setup.commands.entries()) {
+        options.logger.info("environment_setup_command", { index, cwd: command.cwd });
+        await mkdir(command.cwd, { recursive: true }).catch(() => undefined);
+        let result;
+        try {
+            result = await options.exec({ command: command.command, cwd: command.cwd, timeoutMs: command.timeoutMs, env: setup.environment }, options.signal ?? new AbortController().signal);
+        }
+        catch (error) {
+            return { status: "failed", index, output: error instanceof Error ? error.message : String(error) };
+        }
+        if (result.exitCode !== 0) {
+            const output = `${result.stdout}${result.stderr ? `\n${result.stderr}` : ""}${result.timedOut ? "\n[timed out]" : ""}`;
+            return { status: "failed", index, exitCode: result.exitCode, output: output.slice(-REPORT_TAIL) };
+        }
+    }
+    return { status: "ok" };
+}
+/**
+ * Runs the disk's setup when this volume has not had it, reports how it ended, and after a
+ * failure waits for core to ask for it again. Resolves once the setup is done (or there is none).
+ */
+export async function prepareDisk(options) {
+    let setup = options.host.setup;
+    const volumeId = await readText(options.volumeFile);
+    if (options.host.seeded) {
+        // A volume seeded from a disk version: the version holds what setup made, so mark it done.
+        if (volumeId) {
+            const done = { volumeId, recipeVersion: setup?.recipeVersion ?? 0, status: "ok" };
+            await writeAtomic(options.markerFile, new TextEncoder().encode(`${JSON.stringify(done)}\n`));
+        }
+        options.logger.info("environment_setup_skipped", { reason: "seeded" });
+        return;
+    }
+    if (!setup)
+        return;
+    const marker = await readText(options.markerFile);
+    if (marker && volumeId) {
+        try {
+            const done = JSON.parse(marker);
+            if (done.volumeId === volumeId && done.status === "ok")
+                return;
+        }
+        catch {
+            /* a broken marker: run the setup again */
+        }
+    }
+    for (;;) {
+        if (options.signal?.aborted)
+            return;
+        options.logger.info("environment_setup_started", { recipeVersion: setup.recipeVersion });
+        const report = await runOnce(options, setup);
+        if (report.status === "ok") {
+            if (volumeId) {
+                const done = { volumeId, recipeVersion: setup.recipeVersion, status: "ok" };
+                await writeAtomic(options.markerFile, new TextEncoder().encode(`${JSON.stringify(done)}\n`));
+            }
+            await options.host.reportSetup(report).catch((error) => options.logger.warn("environment_setup_report_failed", {
+                message: error instanceof Error ? error.message : String(error),
+            }));
+            options.logger.info("environment_setup_done", { recipeVersion: setup.recipeVersion });
+            return;
+        }
+        options.logger.warn("environment_setup_failed", { index: report.index, exitCode: report.exitCode });
+        let reported = false;
+        // Report it, then wait until a turn start asks the pod to run again, and run it again.
+        for (;;) {
+            if (!reported)
+                reported = await options.host.reportSetup(report).then(() => true, () => false);
+            await new Promise((resolve) => setTimeout(resolve, options.pollMs ?? SETUP_RETRY_POLL_MS));
+            if (options.signal?.aborted)
+                return;
+            if (!reported)
+                continue;
+            const state = await options.host.setupState().catch(() => undefined);
+            if (!state?.retry)
+                continue;
+            if (!state.setup)
+                return;
+            setup = state.setup;
+            break;
+        }
+    }
+}

package/dist/harness/ws-client.js

@@ -9,7 +9,8 @@
 import { createChannel } from "@nylorun/core/harness-api";
 import { createHarness } from "@nylorun/harness/api";
 import { WebSocket } from "ws";
-import { HARNESS_API_HEADER, HARNESS_MAX_PAYLOAD, wsPort } from "./ws-port.js";
+import { HARNESS_API_HEADER, HARNESS_API_TRANSPORT, HARNESS_MAX_PAYLOAD } from "@nylorun/core/harness-api";
+import { wsPort } from "./ws-port.js";
 export function connectHarness(options) {
     const { logger } = options;
     const backoff = options.backoff ?? { minMs: 500, maxMs: 10_000 };
@@ -23,7 +24,7 @@ export function connectHarness(options) {
         const token = typeof options.token === "string" ? options.token : await options.token();
         return new Promise((resolve, reject) => {
             const socket = new WebSocket(options.url, {
-                headers: { authorization: `Bearer ${token}`, [HARNESS_API_HEADER]: "1" },
+                headers: { authorization: `Bearer ${token}`, [HARNESS_API_HEADER]: HARNESS_API_TRANSPORT },
                 maxPayload: HARNESS_MAX_PAYLOAD,
                 handshakeTimeout: 10_000,
             });

package/dist/harness/ws-port.d.ts

@@ -6,11 +6,7 @@
  */
 import type { Port } from "@nylorun/core/harness-api";
 import { WebSocket } from "ws";
-/** The URL path of the Harness API, and the header naming its version. */
-export declare const HARNESS_API_PATH = "/nylorun/harness/v1";
-export declare const HARNESS_API_HEADER = "nylorun-harness-api";
-/** Largest frame either end accepts. */
-export declare const HARNESS_MAX_PAYLOAD: number;
+export { HARNESS_API_HEADER, HARNESS_API_PATH, HARNESS_API_TRANSPORT, HARNESS_MAX_PAYLOAD, } from "@nylorun/core/harness-api";
 export declare const DEFAULT_PING_MS = 30000;
 export declare const DEFAULT_SILENCE_MS = 90000;
 export interface WsPortOptions {