@inflexa-ai/harness 0.1.1

package/dist/sandbox/await-exec.js

@@ -0,0 +1,406 @@
+/**
+ * `awaitExec` — awaits a submitted exec's terminal result, forwarding progress
+ * events, under one of two transports selected by `options.transport`:
+ *
+ *   - `poll` (default): {@link awaitExecPoll} loops durable pull steps against
+ *     `GET /exec/{execId}?since={cursor}`. The sandbox initiates nothing; the
+ *     host asks. Inherently restart-proof — a recovered workflow just resumes
+ *     polling from its current identity — so the recovery wedge (#41) does not
+ *     apply. A machine that dies mid-exec fast-fails in-loop: sustained
+ *     `unavailable` polls escalate to a backend-inspect probe (`liveness.ts`)
+ *     and an observably dead machine returns the synthetic-failure result
+ *     instead of waiting out the deadline.
+ *   - `callback`: {@link awaitExecCallback} is the recv loop below, with the
+ *     pull as its recovery backstop.
+ *
+ * Both run in the workflow body (NOT a step) — `DBOS.recv`, `DBOS.writeStream`,
+ * and `DBOS.sleepms` are body-only — and both verify every result against the
+ * per-sandbox HMAC, treating a bad/stale signature as a hard cancel.
+ *
+ * ## Callback mode: the recv loop
+ *
+ * On each received envelope:
+ *
+ *   1. If it carries `signature: null` and the payload is a
+ *      `synthetic-failure` done-marker, accept it — the watchdog is an
+ *      in-process trusted sender. Any other null-signature message
+ *      hard-cancels.
+ *   2. Otherwise HMAC-verify against the per-sandbox `callbackSecret`.
+ *      A bad or stale signature throws `HardCancelError`, which DBOS
+ *      treats as a fatal workflow error (no retry).
+ *   3. If the verified payload is a done-marker, return its `result`.
+ *   4. Otherwise forward the payload via `emit` and continue.
+ *
+ * `deadline` is an absolute unix-ms timestamp — the durable backstop
+ * (typically `step.timeout`). `T` is liveness-agnostic recv pacing: we
+ * use `min(5s, remaining)` so the loop returns often enough to honour
+ * the deadline.
+ *
+ * ## Recv is not the only way home
+ *
+ * The completion callback is a *push* to an address baked into the container at
+ * creation. A host that dies mid-exec comes back with a different ingress port,
+ * so the push can never land — the sandbox retries into a void while the
+ * recovered recv waits for a message that will never arrive. That is the
+ * recovery wedge (#41), and it is silent: a `running` row that never advances.
+ *
+ * So whenever the topic falls quiet, this loop stops waiting and *asks*:
+ * `GET /exec/{execId}` on the sandbox itself returns the terminal result,
+ * signed fresh at request time. The bytes are the ones the callback would have
+ * carried, so the provenance frame survives the recovery path intact and one
+ * verification path serves both. Push remains the fast path; pull is what makes
+ * the protocol durable rather than merely optimistic.
+ *
+ * The pull is a DBOS step, not a bare `fetch`: a body-level call whose result
+ * varied between replays would desynchronise the recorded function-ID sequence.
+ */
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { signCallback, verifyCallback } from "./hmac.js";
+import { createEscalationPolicy, probeLiveness, syntheticFailureReason, syntheticFailureResult } from "./liveness.js";
+import { ExecResultSchema, isDoneMarker, isSyntheticFailure, PollResponseSchema, } from "./types.js";
+const DEFAULT_FRESHNESS_SECONDS = 300;
+const MAX_RECV_TIMEOUT_SECONDS = 5;
+/**
+ * Two-phase poll cadence. Every poll writes a durable step row (plus a durable
+ * sleep), so the interval is a direct multiplier on DBOS system-table growth
+ * for the life of the exec: 1.5s for the first 40 attempts (~the exec's first
+ * minute) keeps short commands snappy; 10s thereafter keeps an hours-long
+ * exec's row growth bounded, at a terminal-latency cost that is noise at that
+ * runtime. Attempt-derived, so the schedule is a pure function of the
+ * checkpointed step sequence and replays identically.
+ */
+const DEFAULT_POLL_INTERVAL_MS = 1_500;
+const DEFAULT_FAST_POLL_ATTEMPTS = 40;
+const DEFAULT_SLOW_POLL_INTERVAL_MS = 10_000;
+/**
+ * Silent recv slices to tolerate before pulling. At `MAX_RECV_TIMEOUT_SECONDS`
+ * per slice this is ~30s of silence — long enough that a chatty exec never
+ * pulls at all, short enough that a recovered workflow converges quickly. Each
+ * pull is a durable step, so polling every slice would write a step row every
+ * five seconds for the life of a quiet three-hour exec.
+ */
+const PULL_AFTER_SILENT_SLICES = 6;
+const PULL_HTTP_TIMEOUT_MS = 10_000;
+/**
+ * Fetch the terminal result for `execId` directly from sandbox-server.
+ *
+ * Never throws: every failure mode collapses to `unavailable`, because a failed
+ * pull is not a failed exec. Returning an error here would fail the enclosing
+ * DBOS step and take the workflow with it, when the correct response is simply
+ * to keep waiting for the push.
+ *
+ * A terminal response is distinguished by the presence of the signature header
+ * — sandbox-server leaves a still-running exec unsigned, having nothing to
+ * attest to yet.
+ */
+async function pullExecResult(fetchImpl, ref, execId) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), PULL_HTTP_TIMEOUT_MS);
+    try {
+        // The result discloses the command's output, so sandbox-server requires a
+        // signed request. Sign an empty body over the same construction as the
+        // callbacks. `Date.now()` is safe: this runs inside a `DBOS.runStep` whose
+        // cached result is replayed without re-executing the body.
+        const reqTimestamp = Math.floor(Date.now() / 1000);
+        const reqSignature = signCallback({ execId, body: "", timestamp: reqTimestamp, secret: ref.callbackSecret });
+        const res = await fetchImpl(`http://${ref.host}:${ref.port}/exec/${encodeURIComponent(execId)}`, {
+            method: "GET",
+            headers: {
+                "x-sandbox-signature": reqSignature,
+                "x-sandbox-timestamp": String(reqTimestamp),
+            },
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            await res.text().catch(() => "");
+            return { kind: "unavailable", detail: `status ${res.status}` };
+        }
+        const signature = res.headers.get("x-sandbox-signature");
+        const raw = await res.text();
+        if (signature === null)
+            return { kind: "running" };
+        const tsHeader = res.headers.get("x-sandbox-timestamp");
+        const parsedTs = tsHeader === null ? null : Number.parseInt(tsHeader, 10);
+        return {
+            kind: "completed",
+            raw,
+            signature,
+            // An unparseable timestamp forwards as null so `verifyCallback`
+            // reports `missing` rather than us guessing a wall-clock.
+            timestamp: parsedTs === null || Number.isNaN(parsedTs) ? null : parsedTs,
+        };
+    }
+    catch (cause) {
+        return { kind: "unavailable", detail: cause instanceof Error ? cause.message : String(cause) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export class HardCancelError extends Error {
+    execId;
+    reason;
+    constructor(execId, reason, detail) {
+        super(`awaitExec[${execId}]: hard cancel — ${reason}${detail ? ` (${detail})` : ""}`);
+        this.execId = execId;
+        this.reason = reason;
+    }
+}
+export class ExecTimeoutError extends Error {
+    execId;
+    constructor(execId) {
+        super(`awaitExec[${execId}]: deadline exceeded before done-marker`);
+        this.execId = execId;
+    }
+}
+/**
+ * Await a submitted exec's terminal result. Dispatches on transport — `poll`
+ * (default) or `callback`. Both verify every result against the per-sandbox
+ * HMAC and are bounded by `deadlineMs`.
+ */
+export async function awaitExec(ref, execId, emit, deadlineMs, options = {}) {
+    const transport = options.transport ?? "poll";
+    return transport === "callback" ? awaitExecCallback(ref, execId, emit, deadlineMs, options) : awaitExecPoll(ref, execId, emit, deadlineMs, options);
+}
+/**
+ * Body of the recv loop (callback transport). Hoisted so it's testable without
+ * spinning up DBOS — `recv` is injectable and `now` is overridable.
+ */
+export async function awaitExecCallback(ref, execId, emit, deadlineMs, options = {}) {
+    const topic = `exec-event:${execId}`;
+    const callbackSecret = ref.callbackSecret;
+    const now = options.now ?? (() => DBOS.now());
+    const recv = options.recv ?? (async (t, sec) => DBOS.recv(t, sec));
+    const fetchImpl = options.fetch ?? fetch;
+    const runStep = options.runStep ?? ((fn, c) => DBOS.runStep(fn, c));
+    // Both counters are pure functions of the checkpointed recv sequence, so a
+    // replay issues exactly the same pulls in exactly the same order — which is
+    // what keeps the DBOS function-ID sequence stable.
+    let silentSlices = 0;
+    let pullAttempt = 0;
+    /** Ask the sandbox directly. Returns null when the exec has not finished. */
+    const pull = async () => {
+        pullAttempt += 1;
+        const pulled = await runStep(() => pullExecResult(fetchImpl, ref, execId), {
+            name: `sandbox.pull-exec-result.${execId}.${pullAttempt}`,
+        });
+        if (pulled.kind !== "completed")
+            return null;
+        // Identical treatment to a pushed completion: the bytes were signed by
+        // the same secret, so a forgery is as fatal here as it is there.
+        const verified = verifyCallback({
+            execId,
+            body: Buffer.from(pulled.raw, "utf8"),
+            signature: pulled.signature,
+            timestamp: pulled.timestamp,
+            secret: callbackSecret,
+            nowSec: Math.floor((await now()) / 1000),
+            freshnessSec: DEFAULT_FRESHNESS_SECONDS,
+        });
+        if (!verified.valid) {
+            throw new HardCancelError(execId, verified.reason, "pulled result");
+        }
+        return ExecResultSchema.parse(JSON.parse(pulled.raw));
+    };
+    while (true) {
+        const remainingMs = deadlineMs - (await now());
+        if (remainingMs <= 0) {
+            // A lost callback is not a slow command. Ask once before declaring a
+            // timeout — the result may have been sitting in the sandbox the whole
+            // time, and reporting a timeout would discard a completed analysis.
+            const pulled = await pull();
+            if (pulled !== null)
+                return pulled;
+            throw new ExecTimeoutError(execId);
+        }
+        const timeoutSec = Math.min(MAX_RECV_TIMEOUT_SECONDS, Math.max(1, Math.ceil(remainingMs / 1000)));
+        const msg = await recv(topic, timeoutSec);
+        if (msg === null) {
+            silentSlices += 1;
+            if (silentSlices >= PULL_AFTER_SILENT_SLICES) {
+                silentSlices = 0;
+                const pulled = await pull();
+                if (pulled !== null)
+                    return pulled;
+            }
+            continue;
+        }
+        silentSlices = 0;
+        if (msg.signature === null) {
+            if (isSyntheticFailure(msg.payload)) {
+                return ExecResultSchema.parse(msg.payload.result);
+            }
+            throw new HardCancelError(execId, "synthetic-without-marker");
+        }
+        // Verify against the exact bytes sandbox-server signed. The route
+        // preserves them as `payloadRaw`; the JSON.stringify fallback exists
+        // only for messages persisted before that field was added — re-
+        // serializing diverges from Go's HTML-escaping encoder.
+        const bodyBytes = Buffer.from(msg.payloadRaw ?? JSON.stringify(msg.payload), "utf8");
+        const result = verifyCallback({
+            execId,
+            body: bodyBytes,
+            signature: msg.signature,
+            timestamp: msg.timestamp,
+            secret: callbackSecret,
+            nowSec: Math.floor((await now()) / 1000),
+            freshnessSec: DEFAULT_FRESHNESS_SECONDS,
+        });
+        if (!result.valid) {
+            throw new HardCancelError(execId, result.reason);
+        }
+        if (isDoneMarker(msg.payload)) {
+            return ExecResultSchema.parse(msg.payload.result);
+        }
+        await emit(msg.payload);
+    }
+}
+async function pollExecOnce(fetchImpl, ref, execId, cursor) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), PULL_HTTP_TIMEOUT_MS);
+    try {
+        // The response discloses the command's output, so the request is signed
+        // over an empty body — the same construction as the callbacks. `Date.now()`
+        // is safe: this runs inside a `DBOS.runStep` whose cached result is
+        // replayed without re-executing the body.
+        const reqTimestamp = Math.floor(Date.now() / 1000);
+        const reqSignature = signCallback({ execId, body: "", timestamp: reqTimestamp, secret: ref.callbackSecret });
+        const res = await fetchImpl(`http://${ref.host}:${ref.port}/exec/${encodeURIComponent(execId)}?since=${cursor}`, {
+            method: "GET",
+            headers: {
+                "x-sandbox-signature": reqSignature,
+                "x-sandbox-timestamp": String(reqTimestamp),
+            },
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            await res.text().catch(() => "");
+            return { kind: "unavailable", detail: `status ${res.status}` };
+        }
+        const signature = res.headers.get("x-sandbox-signature");
+        const raw = await res.text();
+        if (signature === null)
+            return { kind: "unavailable", detail: "poll response missing signature" };
+        const tsHeader = res.headers.get("x-sandbox-timestamp");
+        const parsedTs = tsHeader === null ? null : Number.parseInt(tsHeader, 10);
+        return {
+            kind: "ok",
+            raw,
+            signature,
+            timestamp: parsedTs === null || Number.isNaN(parsedTs) ? null : parsedTs,
+        };
+    }
+    catch (cause) {
+        return { kind: "unavailable", detail: cause instanceof Error ? cause.message : String(cause) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Body of the poll loop (poll transport). No `DBOS.recv`, no per-exec topic, no
+ * callback handler: a sequence of durable pull steps named
+ * `sandbox.poll-exec-result.${execId}.${n}`, each fetching the signed
+ * `{ status, events, cursor, result? }`, verifying it exactly as a pushed
+ * completion is verified, forwarding new events via `emit`, advancing the
+ * cursor, and returning `result` once terminal. `sleep`, `now`, `fetch`,
+ * `runStep`, and `isAlive` are injectable so the loop is testable without DBOS.
+ *
+ * Liveness: when the `isAlive` seam is wired (the client always wires it),
+ * consecutive `unavailable` polls past the module threshold escalate to a
+ * durable probe step `sandbox.probe-liveness.${execId}.${k}`; a dead verdict
+ * returns the synthetic-failure result in-loop — the poll-mode analogue of the
+ * watchdog's synthetic-complete, minus the topic and the race gate, since the
+ * verdict is produced and consumed by the same workflow in sequence.
+ *
+ * The `cursor`, `pollAttempt`, and `probeAttempt` counters are pure functions
+ * of the cached step sequence, so a replay issues the same polls and probes in
+ * the same order and the DBOS function-ID sequence stays stable.
+ */
+export async function awaitExecPoll(ref, execId, emit, deadlineMs, options = {}) {
+    const callbackSecret = ref.callbackSecret;
+    const now = options.now ?? (() => DBOS.now());
+    const fetchImpl = options.fetch ?? fetch;
+    const runStep = options.runStep ?? ((fn, c) => DBOS.runStep(fn, c));
+    const sleep = options.sleep ?? ((ms) => DBOS.sleepms(ms));
+    const warn = options.warn ?? ((message) => DBOS.logger.warn(message));
+    const isAlive = options.isAlive;
+    let cursor = 0;
+    let pollAttempt = 0;
+    // Sustained-unavailability escalation (`liveness.ts`): consecutive
+    // `unavailable` polls arm a backend-inspect probe; poll failures alone
+    // never fail the exec (`unavailable` conflates unreachable with unknown
+    // execId / non-200). Policy state and the probe counter are pure functions
+    // of the checkpointed poll outcomes, so replays walk the identical
+    // poll/probe step sequence.
+    const escalation = createEscalationPolicy();
+    let probeAttempt = 0;
+    while (true) {
+        pollAttempt += 1;
+        const polled = await runStep(() => pollExecOnce(fetchImpl, ref, execId, cursor), {
+            name: `sandbox.poll-exec-result.${execId}.${pollAttempt}`,
+        });
+        if (polled.kind === "ok") {
+            // Identical treatment to a pushed completion: the bytes were signed by
+            // the same secret, so a forgery is as fatal here as it is there.
+            const verified = verifyCallback({
+                execId,
+                body: Buffer.from(polled.raw, "utf8"),
+                signature: polled.signature,
+                timestamp: polled.timestamp,
+                secret: callbackSecret,
+                nowSec: Math.floor((await now()) / 1000),
+                freshnessSec: DEFAULT_FRESHNESS_SECONDS,
+            });
+            if (!verified.valid) {
+                throw new HardCancelError(execId, verified.reason, "poll response");
+            }
+            const resp = PollResponseSchema.parse(JSON.parse(polled.raw));
+            // Forward only events past the local cursor, before returning, so
+            // trailing progress lands ahead of the terminal result. The filter is
+            // load-bearing: the signature covers the body but not the request's
+            // `since`, so any validly-signed snapshot verifies against any poll —
+            // a replayed or crossed response must not re-emit delivered events.
+            const newEvents = resp.events.filter((ev) => ev.seq > cursor);
+            // Sequence numbers are per-exec contiguous, so a hole between the
+            // local cursor and the next delivered (or high-water) seq is exact
+            // proof the ring shed events before the host saw them. Advisory: the
+            // terminal result, not the event stream, is the authoritative outcome.
+            const nextSeq = newEvents.length > 0 ? newEvents[0].seq : resp.cursor > cursor ? resp.cursor + 1 : cursor + 1;
+            const lost = nextSeq - cursor - 1;
+            if (lost > 0) {
+                warn(`awaitExecPoll[${execId}]: ${lost} progress event(s) (seq ${cursor + 1}-${cursor + lost}) shed by the sandbox ring before delivery; the terminal result is unaffected`);
+            }
+            for (const ev of newEvents) {
+                await emit(ev.payload);
+            }
+            if (resp.cursor > cursor)
+                cursor = resp.cursor;
+            if (resp.result !== undefined)
+                return resp.result;
+        }
+        if (isAlive && escalation.onPoll(polled.kind === "ok" ? "ok" : "unavailable")) {
+            probeAttempt += 1;
+            const verdict = await runStep(() => probeLiveness(isAlive, ref), {
+                name: `sandbox.probe-liveness.${execId}.${probeAttempt}`,
+            });
+            // Only an observably dead machine fails the exec — the result lives
+            // in that machine and nowhere else, so it is unrecoverable and the
+            // synthetic failure races nothing. `alive` (live-but-slow exec,
+            // evicted execId) and `inconclusive` (backend API error) both
+            // resume polling, bounded by the deadline.
+            if (verdict.kind === "dead") {
+                return syntheticFailureResult(execId, syntheticFailureReason({ oomKilled: verdict.oomKilled }));
+            }
+        }
+        // The deadline gate sits AFTER the poll so the loop always asks once more
+        // before declaring a timeout — same reasoning as the callback loop's
+        // deadline pull: a lost poll window is not a slow command, and reporting
+        // a timeout would discard a completed analysis.
+        const remainingMs = deadlineMs - (await now());
+        if (remainingMs <= 0)
+            throw new ExecTimeoutError(execId);
+        const intervalMs = pollAttempt <= DEFAULT_FAST_POLL_ATTEMPTS ? DEFAULT_POLL_INTERVAL_MS : DEFAULT_SLOW_POLL_INTERVAL_MS;
+        await sleep(Math.min(intervalMs, remainingMs));
+    }
+}

package/dist/sandbox/client.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `SandboxClient` — the five-method seam every sandbox-backed module in
+ * the harness sits on. Implementations are backend-selected
+ * (`docker`/`k8s`) by `createSandboxClient()` in `create-sandbox.ts` and
+ * injected at the composition root as a construction-time dependency
+ * (see the harness-durable-runtime spec). Callers do NOT import a backend module directly.
+ *
+ * The interface is split across three files:
+ * - `client.ts` (here) — the interface and the per-method types.
+ * - `create-sandbox.ts` — the factory + per-backend `createSandbox` /
+ *   `teardown` / `isAlive` implementations.
+ * - `submit-exec.ts` + `await-exec.ts` — `submitExec` and the workflow-
+ *   body recv loop, which are backend-agnostic (HTTP + DBOS messages).
+ *
+ * Lifetime separation (CONTEXT.md "Sandbox exec"):
+ * - The **sandbox machine** lifetime is `createSandbox → ... → teardown`.
+ *   Many execs may fire against the same machine.
+ * - The **exec** lifetime is one `submitExec → awaitExec`.
+ *
+ * `awaitExec` runs in the workflow body (not as a DBOS step) because
+ * `DBOS.recv` and `DBOS.writeStream` are body-only.
+ */
+import type { CreateSandboxMeta, ExecEmit, ExecResult, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SubmitExecBody } from "./types.js";
+export interface SandboxClient {
+    /**
+     * DBOS step (`sandbox.create`) — the spawn half of the two-step create
+     * (see the harness-sandbox-exec spec). Launches the sandbox-base container/Job under the
+     * pre-minted `identity` (name + HMAC secret checkpointed by `sandbox.mint`),
+     * stamps ownership labels, waits for `/health`, records the live handle in
+     * the active-sandbox registry, and returns the in-memory `SandboxRef`. A
+     * recovery re-run whose machine already exists (the crash window between
+     * spawn and checkpoint) **adopts** it rather than leaking a second one.
+     */
+    createSandbox(meta: CreateSandboxMeta, identity: SandboxIdentity): Promise<SandboxRef>;
+    /**
+     * DBOS step (`sandbox.submit-exec.${execId}`). POSTs the command to
+     * sandbox-server's `/exec` and returns after the HTTP 202 ack. Does NOT
+     * wait for command completion. Replay-safe: the cached step output is
+     * returned on subsequent invocations; any duplicate POST that reaches
+     * sandbox-server during the in-flight window is deduped server-side
+     * (PR #3 change 4) on `execId`.
+     */
+    submitExec(ref: SandboxRef, body: SubmitExecBody): Promise<void>;
+    /**
+     * Awaits a submitted exec's terminal result under the client's transport.
+     * Poll (default) loops durable, signed `GET /exec/{execId}?since={cursor}`
+     * steps against the sandbox in `ref`; callback loops
+     * `DBOS.recv("exec-event:${execId}", T)` with a signed pull as its
+     * recovery backstop. Both HMAC-verify every body against
+     * `ref.callbackSecret`, forward progress events via `emit`, and are
+     * bounded by `deadline` (absolute unix-ms timestamp).
+     */
+    awaitExec(ref: SandboxRef, execId: string, emit: ExecEmit, deadline: number): Promise<ExecResult>;
+    /**
+     * Per-sandbox-machine liveness. `alive: false` only when observably dead
+     * (terminal pod phase, missing container); `oomKilled` marks a death the
+     * backend attributes to the machine's memory limit. Transient API errors
+     * throw, so callers can decide whether to retry — silently lying about
+     * dead sandboxes would race the synthetic-complete path.
+     */
+    isAlive(ref: SandboxRef): Promise<SandboxLiveness>;
+    /**
+     * DBOS step (`sandbox.teardown`). Deletes the K8s Job / removes the
+     * Docker container, clears the active-sandbox registry. Idempotent —
+     * "already gone" is a successful teardown.
+     */
+    teardown(ref: SandboxRef): Promise<void>;
+    /**
+     * Delete a sandbox machine by id alone — the reaper path (see the harness-sandbox-exec spec), which
+     * holds a `sandboxId` from the cluster sweep but no full `SandboxRef`.
+     * Does NOT touch the registry; the reaper reconciles the row itself.
+     * Idempotent: "already gone" is success.
+     */
+    teardownById(sandboxId: string): Promise<void>;
+    /**
+     * Enumerate every Cortex-managed sandbox machine the backend is running,
+     * scoped to the configured namespace (`app.kubernetes.io/managed-by=cortex`).
+     * The cluster→registry direction the reaper needs — every other op takes a
+     * ref the caller already holds; this one finds machines Cortex has forgotten.
+     */
+    listManagedSandboxes(): Promise<ManagedSandbox[]>;
+}

package/dist/sandbox/client.js

@@ -0,0 +1,23 @@
+/**
+ * `SandboxClient` — the five-method seam every sandbox-backed module in
+ * the harness sits on. Implementations are backend-selected
+ * (`docker`/`k8s`) by `createSandboxClient()` in `create-sandbox.ts` and
+ * injected at the composition root as a construction-time dependency
+ * (see the harness-durable-runtime spec). Callers do NOT import a backend module directly.
+ *
+ * The interface is split across three files:
+ * - `client.ts` (here) — the interface and the per-method types.
+ * - `create-sandbox.ts` — the factory + per-backend `createSandbox` /
+ *   `teardown` / `isAlive` implementations.
+ * - `submit-exec.ts` + `await-exec.ts` — `submitExec` and the workflow-
+ *   body recv loop, which are backend-agnostic (HTTP + DBOS messages).
+ *
+ * Lifetime separation (CONTEXT.md "Sandbox exec"):
+ * - The **sandbox machine** lifetime is `createSandbox → ... → teardown`.
+ *   Many execs may fire against the same machine.
+ * - The **exec** lifetime is one `submitExec → awaitExec`.
+ *
+ * `awaitExec` runs in the workflow body (not as a DBOS step) because
+ * `DBOS.recv` and `DBOS.writeStream` are body-only.
+ */
+export {};

package/dist/sandbox/create-sandbox.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Backend-selected `SandboxClient` factory.
+ *
+ * Docker for local dev, K8s for production — the single place the
+ * `SANDBOX_BACKEND` env decision lives. Injected at the composition root
+ * as a construction-time dependency (see the harness-durable-runtime spec); callers do NOT import a
+ * backend module directly.
+ *
+ * Registry write/clear callbacks are wired here so the per-backend
+ * `createSandbox` / `teardown` implementations stay free of state-layer
+ * coupling (they just call the closures we hand them). `submitExec` and
+ * `awaitExec` are backend-agnostic — they only need the SandboxRef.
+ */
+import type { V1Toleration } from "@kubernetes/client-node";
+import type { Pool } from "pg";
+import type pino from "pino";
+import { type ResourceLimits } from "../config/resource-limits.js";
+import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
+import { clearSandboxRef } from "../state/index.js";
+import { type AwaitExecOptions } from "./await-exec.js";
+import type { SandboxClient } from "./client.js";
+import { type SubmitExecDeps } from "./submit-exec.js";
+import { type SandboxTransport } from "./types.js";
+/**
+ * Narrow config slice the sandbox factory reads off `Env` — the backend
+ * default and the K8s namespace fallback. Composition roots map their
+ * validated `Env` onto this.
+ */
+export interface SandboxBackendConfig {
+    readonly backend: "docker" | "k8s";
+    readonly namespace: string;
+}
+export interface CreateSandboxClientConfig {
+    /** App pool — used for registry writes inside the create/teardown steps. */
+    pool: Pool;
+    /** Backend default + namespace fallback source. */
+    env: SandboxBackendConfig;
+    /** Cortex base URL injected into sandbox-server's env for callbacks. */
+    cortexBaseUrl: string;
+    /**
+     * Result transport for every sandbox this client creates. Threaded to the
+     * container as `SANDBOX_TRANSPORT` and to `awaitExec`'s loop selection.
+     * Defaults to `poll`.
+     */
+    transport?: SandboxTransport;
+    /** Default sandbox-base image when the workflow doesn't override per-step. */
+    image: string;
+    /** Cluster resource ceilings; every sandbox request is clamped to these. */
+    resourceLimits: ResourceLimits;
+    /** K8s namespace; only used by the k8s backend. */
+    namespace?: string;
+    /**
+     * Workspace-root resolution seam (see workspace/paths.ts). Docker binds
+     * each analysis's resolved root; on K8s the resolved roots live under the
+     * session PVC. Always required: the writable step dir is pre-created under
+     * the resolved root regardless of backend.
+     */
+    resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    /** Docker: host dir bind-mounted read-only at `/mnt/libs`. */
+    libStorePath?: string;
+    /** Docker: host dir bind-mounted read-only at `/mnt/refs`. */
+    refStorePath?: string;
+    /** Docker: force the container platform (e.g. `linux/amd64`) so the sandbox matches the mounted lib store's arch. */
+    platform?: string;
+    /** K8s: PVC claim backing the session PVC the workspace roots live under. */
+    sessionPvc?: string;
+    /**
+     * K8s: absolute mountpoint of `sessionPvc` on this process's filesystem. Required with
+     * `sessionPvc` — the pod's `subPath` is a resolved workspace root taken relative to it,
+     * which is what keeps the pre-created step tree and the mounted step tree the same one.
+     */
+    sessionPvcRoot?: string;
+    /** K8s: PVC claim mounted read-only at `/mnt/libs`. */
+    libStorePvc?: string;
+    /** K8s: PVC claim mounted read-only at `/mnt/refs`. */
+    refStorePvc?: string;
+    /** K8s: node selector pinning sandbox pods to the dedicated agent pool. */
+    nodeSelector?: Record<string, string>;
+    /** K8s: tolerations letting sandbox pods land on the tainted agent nodes. */
+    tolerations?: V1Toleration[];
+    /** K8s: RuntimeClass for runtime isolation (e.g. `gvisor`). */
+    runtimeClassName?: string;
+    /** Override the backend selection — defaults to `env.SANDBOX_BACKEND`. */
+    backend?: "docker" | "k8s";
+    /**
+     * Optional logger forwarded to the Docker backend so a lib-store degradation
+     * (a configured store whose `current` vanished/went incomplete mid-session) is
+     * observable rather than a silent mount drop. No-op when unset.
+     */
+    logger?: Pick<pino.Logger, "info" | "warn" | "error">;
+    /** Dependency seams (fetch, durable step/sleep, clock, recv, warn sink) forwarded to submit/await. */
+    submitDeps?: SubmitExecDeps;
+    awaitOptions?: AwaitExecOptions;
+}
+/**
+ * Assemble `awaitExec`'s options: the liveness probe self-wires from the
+ * backend ops (the poll loop's escalation always has its arbiter under the
+ * client), explicit seam injections in `base` win over the self-wired probe,
+ * and the transport is client-owned — never overridable through the seam bag.
+ * Exported for tests.
+ */
+export declare function composeAwaitOptions(base: AwaitExecOptions | undefined, transport: SandboxTransport, isAlive: NonNullable<AwaitExecOptions["isAlive"]>): AwaitExecOptions;
+export declare function createSandboxClient(config: CreateSandboxClientConfig): SandboxClient;
+/** Re-exports so consumers import once from this module. */
+export { clearSandboxRef };