@nylorun/runtime 0.22.0-beta → 0.24.0-beta

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 {

package/dist/harness/ws-port.js

@@ -1,9 +1,5 @@
 import { WebSocket } from "ws";
-/** The URL path of the Harness API, and the header naming its version. */
-export const HARNESS_API_PATH = "/nylorun/harness/v1";
-export const HARNESS_API_HEADER = "nylorun-harness-api";
-/** Largest frame either end accepts. */
-export const HARNESS_MAX_PAYLOAD = 64 * 1024 * 1024;
+export { HARNESS_API_HEADER, HARNESS_API_PATH, HARNESS_API_TRANSPORT, HARNESS_MAX_PAYLOAD, } from "@nylorun/core/harness-api";
 export const DEFAULT_PING_MS = 30_000;
 export const DEFAULT_SILENCE_MS = 90_000;
 export function wsPort(socket, options = {}) {

package/dist/harness-api/in-process.js

@@ -9,7 +9,7 @@
  * SandboxManager and no store, as `--service harness` runs one.
  */
 import { randomBytes } from "node:crypto";
-import { memoryChannels } from "@nylorun/core/harness-api";
+import { DEFAULT_HARNESS, memoryChannels } from "@nylorun/core/harness-api";
 import { createHarness } from "@nylorun/harness/api";
 import { harnessExecutors } from "../harness/executors.js";
 import { startHarnessService } from "../harness/service.js";
@@ -36,7 +36,8 @@ export async function startInProcessHarness(ctx, tools, options = {}) {
             sandbox: () => tools.sandbox,
         }),
         logger: ctx.config.logger,
-        name: "in-process",
+        // Our harness: its hello names our harness id (R4.1).
+        name: DEFAULT_HARNESS,
     });
     await harness.start();
     return {
@@ -77,7 +78,6 @@ export async function startLoopbackHarness(ctx, options = {}) {
         ...(ctx.config.delivery ? { delivery: ctx.config.delivery } : {}),
         ...(options.sandboxBackends ? { sandboxBackends: options.sandboxBackends } : {}),
         logger: quietLogger(ctx),
-        name: "loopback",
         ephemeral: ctx.config.mode === "ephemeral",
         backoff: { minMs: 50, maxMs: 500 },
     });

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

@@ -11,8 +11,15 @@
  *
  * Rows store the request's hash (`requestHash`) and, for a model call, the request without its
  * prompt: drift is a hash compare. Rows written before carry their full request, hashed on read.
+ *
+ * Every row a run journals keeps when it was journaled (`startedAt`, R7.1), and a rejoin keeps
+ * it: an outcome's `durationMs` is the journal's window, from the intent to the outcome. A model
+ * call's outcome event also carries what the meter recorded for it (`modelOutcomeFacts`). A tool
+ * row keeps its span's context (`traceparent`, R7.4), which the `execute` answer carries to the
+ * harness and the Tool Gate reads with the row.
  */
 import { type EffectIntent, type IntentAnswer, type OutcomeAnswer, type RecordedOutcome } from "@nylorun/core/harness-api";
+import type { EventWriter } from "@nylorun/core/contracts";
 import { type Lease, type Session, type TenantContext } from "../tenant/context.js";
 import type { Tx } from "../store/types.js";
 /** What a run's journal writes are scoped by: the advance's lease and its signal. */
@@ -20,6 +27,13 @@ export interface RecordScope {
     readonly ctx: TenantContext;
     readonly lease: Lease;
     readonly signal: AbortSignal;
+    /** The tools the run's harness declared it runs itself (`hello` `capabilities.tools`, R4.2). */
+    readonly nativeTools?: ReadonlySet<string>;
+    /**
+     * Who reported what this scope records (R4.9): the run's harness, so the events derived from
+     * its intents and outcomes are its claim. Absent, core recorded what it saw itself.
+     */
+    readonly writer?: EventWriter;
 }
 /** The hash a journal row's request was recorded with. */
 export declare function hashOf(row: {
@@ -41,7 +55,7 @@ export declare function recordIntent(scope: RecordScope, effect: EffectIntent, r
  * `error` that left it uncertain. Only a cancel discards an outcome in hand (§10.7): after any
  * other abort (shutdown, deadline) it is recorded, so the next advance replays it.
  */
-export declare function recordOutcome(scope: RecordScope, effectId: string, result: {
+export declare function recordOutcome(scope: RecordScope, effectId: string, reported: {
     value: unknown;
 } | {
     error: string;