@inflexa-ai/harness 0.1.1

package/dist/sandbox/sandbox-step-translate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pure translation between the agent-loop / sandbox event stream and the
+ * typed per-step parts the frontend renders. No DBOS, no per-run state — just the
+ * label mapping, the file-tree delta extraction/fold, and the chat-data-part
+ * narrowing the `sandbox-step` workflow body composes into its emitters.
+ */
+import type { ChatDataPart, EmitFn } from "../loop/types.js";
+export declare function activityForTool(name: string, input?: unknown): string;
+/** On-change working-tree delta the sandbox executor posts per exec (paths
+ *  only; the executor skips directories). */
+export interface SandboxTreeDelta {
+    added?: string[];
+    modified?: string[];
+    removed?: string[];
+}
+/** Extract the tree delta from a `data-sandbox-event` part, or null when the
+ *  part is some other sandbox event. The wrapper shape is set by
+ *  `run-exec.ts`: `{ type: "data-sandbox-event", data: { execId, event } }`
+ *  where `event` is the executor's `eventPayload`. */
+export declare function sandboxTreeDelta(part: {
+    type: string;
+    data?: unknown;
+}): SandboxTreeDelta | null;
+/** Apply one on-change delta to the per-step cumulative path set. `added`
+ *  and `modified` add the path; `removed` deletes it. Folding many deltas
+ *  (one stream per exec, all against the same step working dir) yields the
+ *  full set of files the step has produced so far. */
+export declare function applyTreeDelta(files: Set<string>, delta: SandboxTreeDelta): void;
+/**
+ * Narrow an `EmitFn` payload to `ChatDataPart`. The discriminator is the
+ * `data-` prefix on `type`: orchestration events (`iteration`,
+ * `tool-started`, `tool-finished`) and `ChatStreamEvent` (`text-delta`,
+ * `done`) never start with `data-`.
+ */
+export declare function isChatDataPart(event: Parameters<EmitFn>[0]): event is ChatDataPart;

package/dist/sandbox/sandbox-step-translate.js

@@ -0,0 +1,76 @@
+/**
+ * Pure translation between the agent-loop / sandbox event stream and the
+ * typed per-step parts the frontend renders. No DBOS, no per-run state — just the
+ * label mapping, the file-tree delta extraction/fold, and the chat-data-part
+ * narrowing the `sandbox-step` workflow body composes into its emitters.
+ */
+/** Friendly live-activity label per sandbox tool id. Falls back to the raw
+ *  tool name so a newly added tool still reads sensibly. */
+const TOOL_ACTIVITY = {
+    execute_command: "Running script",
+    write_file: "Writing file",
+    edit_file: "Editing file",
+    read_file: "Reading file",
+    grep: "Searching files",
+    list_files: "Listing files",
+};
+/** Last path segment of a posix/win path-like string. */
+function baseName(p) {
+    const parts = p.split(/[\\/]/);
+    return parts[parts.length - 1] || p;
+}
+/** Display file name for a tool's live-activity label, or null when the input
+ *  carries no sensible name. Path tools (`write_file`/`edit_file`/`read_file`)
+ *  carry `path`; `execute_command` carries an argv `command` whose first
+ *  script-like token names what's running. */
+function activityFileName(name, input) {
+    if (input === null || typeof input !== "object")
+        return null;
+    const obj = input;
+    if (name === "execute_command") {
+        const cmd = obj.command;
+        if (!Array.isArray(cmd))
+            return null;
+        const script = cmd.find((a) => typeof a === "string" && /\.(py|R|r|sh|js|ts|ipynb)$/.test(a));
+        return script ? baseName(script) : null;
+    }
+    return typeof obj.path === "string" && obj.path.length > 0 ? baseName(obj.path) : null;
+}
+export function activityForTool(name, input) {
+    const label = TOOL_ACTIVITY[name] ?? `Running ${name}`;
+    const file = activityFileName(name, input);
+    return file ? `${label} ${file}` : label;
+}
+/** Extract the tree delta from a `data-sandbox-event` part, or null when the
+ *  part is some other sandbox event. The wrapper shape is set by
+ *  `run-exec.ts`: `{ type: "data-sandbox-event", data: { execId, event } }`
+ *  where `event` is the executor's `eventPayload`. */
+export function sandboxTreeDelta(part) {
+    if (part.type !== "data-sandbox-event")
+        return null;
+    const inner = part.data?.event;
+    if (!inner || inner.kind !== "file-tree" || !inner.tree)
+        return null;
+    return inner.tree;
+}
+/** Apply one on-change delta to the per-step cumulative path set. `added`
+ *  and `modified` add the path; `removed` deletes it. Folding many deltas
+ *  (one stream per exec, all against the same step working dir) yields the
+ *  full set of files the step has produced so far. */
+export function applyTreeDelta(files, delta) {
+    for (const p of delta.added ?? [])
+        files.add(p);
+    for (const p of delta.modified ?? [])
+        files.add(p);
+    for (const p of delta.removed ?? [])
+        files.delete(p);
+}
+/**
+ * Narrow an `EmitFn` payload to `ChatDataPart`. The discriminator is the
+ * `data-` prefix on `type`: orchestration events (`iteration`,
+ * `tool-started`, `tool-finished`) and `ChatStreamEvent` (`text-delta`,
+ * `done`) never start with `data-`.
+ */
+export function isChatDataPart(event) {
+    return typeof event.type === "string" && event.type.startsWith("data-");
+}

package/dist/sandbox/submit-exec.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `submitExec` — backend-agnostic DBOS step that POSTs a command to
+ * sandbox-server's `/exec` and returns after the HTTP 202 ack (ADR
+ * 0002). `submitExec` wraps its own POST in a `DBOS.runStep` keyed
+ * `sandbox.submit-exec.${execId}`.
+ *
+ * Step name: `sandbox.submit-exec.${execId}` — `execId` is already unique
+ * across the workflow (`${workflowId}:${stepId}:${functionId}`), so it
+ * doubles as the DBOS step replay cache key. On replay the cached step
+ * output is returned without re-POSTing; any duplicate POST that
+ * actually reaches sandbox-server during a narrow in-flight window is
+ * deduped server-side (PR #3 change 4) on the same `execId`.
+ *
+ * A non-202 status throws — the step boundary is throw-based by design
+ * (the `resultStep` principle): durability records a step as failed only
+ * on a thrown exception, and a throw lets DBOS cancellation propagate
+ * untouched.
+ */
+import type { SandboxRef, SubmitExecBody } from "./types.js";
+export interface SubmitExecDeps {
+    /** Injected for tests. Defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** Injected for tests. Defaults to `DBOS.runStep`. */
+    runStep?: <T>(fn: () => Promise<T>, config: {
+        name: string;
+    }) => Promise<T>;
+}
+/**
+ * Submit an exec as a DBOS step. The step name is unique per execId, so
+ * a workflow that has already submitted the exec replays without issuing
+ * another POST.
+ */
+export declare function submitExec(ref: SandboxRef, body: SubmitExecBody, deps?: SubmitExecDeps): Promise<void>;

package/dist/sandbox/submit-exec.js

@@ -0,0 +1,68 @@
+/**
+ * `submitExec` — backend-agnostic DBOS step that POSTs a command to
+ * sandbox-server's `/exec` and returns after the HTTP 202 ack (ADR
+ * 0002). `submitExec` wraps its own POST in a `DBOS.runStep` keyed
+ * `sandbox.submit-exec.${execId}`.
+ *
+ * Step name: `sandbox.submit-exec.${execId}` — `execId` is already unique
+ * across the workflow (`${workflowId}:${stepId}:${functionId}`), so it
+ * doubles as the DBOS step replay cache key. On replay the cached step
+ * output is returned without re-POSTing; any duplicate POST that
+ * actually reaches sandbox-server during a narrow in-flight window is
+ * deduped server-side (PR #3 change 4) on the same `execId`.
+ *
+ * A non-202 status throws — the step boundary is throw-based by design
+ * (the `resultStep` principle): durability records a step as failed only
+ * on a thrown exception, and a throw lets DBOS cancellation propagate
+ * untouched.
+ */
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { signCallback } from "./hmac.js";
+const SUBMIT_HTTP_TIMEOUT_MS = 30_000;
+async function postExec(fetchImpl, ref, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), SUBMIT_HTTP_TIMEOUT_MS);
+    try {
+        // Sign the exact bytes we send, over the same HMAC construction the
+        // sandbox uses for its callbacks — sandbox-server authenticates every
+        // inbound request. `Date.now()` is safe here: this whole POST runs inside
+        // a `DBOS.runStep` whose cached result is replayed without re-executing
+        // the body, so the timestamp never re-computes on recovery.
+        const raw = JSON.stringify(body);
+        const timestamp = Math.floor(Date.now() / 1000);
+        const signature = signCallback({ execId: body.execId, body: raw, timestamp, secret: ref.callbackSecret });
+        const res = await fetchImpl(`http://${ref.host}:${ref.port}/exec`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "x-sandbox-signature": signature,
+                "x-sandbox-timestamp": String(timestamp),
+            },
+            body: raw,
+            signal: controller.signal,
+        });
+        if (res.status !== 202) {
+            const text = await res.text().catch(() => "");
+            throw Object.assign(new Error(`submitExec: sandbox-server returned ${res.status} for execId=${body.execId}: ${text}`), { statusCode: res.status });
+        }
+        // The 202 body carries either `{ status: "started" }` (fresh) or a
+        // dedup-hit summary. Both are success — read and discard so the
+        // socket is released.
+        await res.text().catch(() => "");
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Submit an exec as a DBOS step. The step name is unique per execId, so
+ * a workflow that has already submitted the exec replays without issuing
+ * another POST.
+ */
+export async function submitExec(ref, body, deps = {}) {
+    const fetchImpl = deps.fetch ?? fetch;
+    const runStep = deps.runStep ?? ((fn, c) => DBOS.runStep(fn, c));
+    await runStep(() => postExec(fetchImpl, ref, body), {
+        name: `sandbox.submit-exec.${body.execId}`,
+    });
+}

package/dist/sandbox/types.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Sandbox-client types — the wire/persistence shapes that cross the
+ * submit/recv protocol (see the harness-sandbox-exec spec) and the active-sandbox registry.
+ *
+ * `SandboxRef` is the in-memory handle the harness uses to talk to a live
+ * sandbox; it carries the per-sandbox `callbackSecret` (see the harness-sandbox-exec spec). The
+ * persistable subset is `PersistedSandboxRef` (from `harness/state/schema.ts`)
+ * — that one OMITS the secret, which lives only in the cached
+ * `createSandbox` DBOS step output.
+ */
+import { z } from "zod";
+import type { ResourceSpec } from "../config/resource-limits.js";
+export declare const SandboxBackend: z.ZodEnum<{
+    docker: "docker";
+    k8s: "k8s";
+}>;
+export type SandboxBackend = z.infer<typeof SandboxBackend>;
+/**
+ * How a command's progress events and terminal result reach the host. Chosen by
+ * the embedder at its composition root and carried into the container as
+ * `SANDBOX_TRANSPORT`; backend-independent. The OSS default is `poll`.
+ *
+ * - `poll`: the host polls `GET /exec/{execId}?since={cursor}`; the sandbox
+ *   never dials out and needs no egress.
+ * - `callback`: the sandbox POSTs signed event/completion callbacks; the
+ *   embedder runs an ingress. `GET /exec/{execId}` stays the recovery backstop.
+ */
+export declare const SandboxTransportSchema: z.ZodEnum<{
+    poll: "poll";
+    callback: "callback";
+}>;
+export type SandboxTransport = z.infer<typeof SandboxTransportSchema>;
+/**
+ * Per-sandbox-machine liveness verdict. `oomKilled` is meaningful only when
+ * `alive` is false: true when the backend reports the machine was killed for
+ * exceeding its memory limit (Docker `State.OOMKilled`; K8s container
+ * terminated reason `OOMKilled`) — the watchdog surfaces it as the
+ * `sandbox-oom-killed` failure reason instead of the generic `sandbox-dead`.
+ */
+export interface SandboxLiveness {
+    readonly alive: boolean;
+    readonly oomKilled: boolean;
+}
+export declare const SandboxRefSchema: z.ZodObject<{
+    sandboxId: z.ZodString;
+    host: z.ZodString;
+    port: z.ZodNumber;
+    backend: z.ZodEnum<{
+        docker: "docker";
+        k8s: "k8s";
+    }>;
+    callbackSecret: z.ZodString;
+}, z.core.$strip>;
+export type SandboxRef = z.infer<typeof SandboxRefSchema>;
+/** Strip the secret before persisting to the active-sandbox registry. */
+export declare function toPersistedRef(ref: SandboxRef): {
+    sandboxId: string;
+    host: string;
+    port: number;
+    backend: SandboxBackend;
+};
+/**
+ * One tracked file operation in the sandbox-server provenance frame.
+ * Mirrors Go's `ProvenanceEntry` (`images/sandbox-base/server/provenance.go`):
+ * an absolute container path plus the capture layers that observed it.
+ */
+export declare const ProvenanceFrameEntrySchema: z.ZodObject<{
+    path: z.ZodString;
+    layers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type ProvenanceFrameEntry = z.infer<typeof ProvenanceFrameEntrySchema>;
+/**
+ * Runtime file-I/O frame sandbox-server attaches to the `/complete`
+ * callback. Mirrors Go's `provenancePayload` — every field is
+ * `omitempty` on the wire, so each arm defaults so a completion that
+ * omits the frame (or any arm) still parses.
+ */
+export declare const ProvenanceFrameSchema: z.ZodObject<{
+    disabled: z.ZodDefault<z.ZodBoolean>;
+    reads: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        layers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    writes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        layers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    deletes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        layers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ProvenanceFrame = z.infer<typeof ProvenanceFrameSchema>;
+/**
+ * Final outcome of a single exec, returned by `awaitExec`. Mirrors the
+ * sandbox-server completion payload plus a discriminant for synthetic
+ * (watchdog-emitted) failures.
+ */
+export declare const ExecResultSchema: z.ZodObject<{
+    execId: z.ZodString;
+    exitCode: z.ZodNullable<z.ZodNumber>;
+    stdout: z.ZodDefault<z.ZodString>;
+    stderr: z.ZodDefault<z.ZodString>;
+    durationMs: z.ZodNullable<z.ZodNumber>;
+    timedOut: z.ZodDefault<z.ZodBoolean>;
+    syntheticFailure: z.ZodOptional<z.ZodObject<{
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+    provenance: z.ZodOptional<z.ZodObject<{
+        disabled: z.ZodDefault<z.ZodBoolean>;
+        reads: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            layers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+        writes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            layers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+        deletes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            layers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ExecResult = z.infer<typeof ExecResultSchema>;
+/**
+ * Per-message envelope on the per-exec DBOS topic. Real callbacks carry
+ * a non-null `signature` and `timestamp`; the in-process watchdog uses a
+ * `null` signature + a `synthetic-failure` payload (see `await-exec.ts`).
+ *
+ * `payloadRaw` is the exact bytes sandbox-server POSTed — sandbox-server's
+ * HMAC signs the raw body, and Go's `encoding/json` HTML-escapes `<`, `>`,
+ * `&` by default, so verifying against a JS re-serialization of the parsed
+ * payload would diverge for any output containing those characters
+ * (common in bioinformatics: FASTA headers, shell stderr, command pipelines).
+ * Optional only for back-compat with messages that pre-date this field.
+ */
+export declare const ExecEventMessageSchema: z.ZodObject<{
+    payload: z.ZodUnknown;
+    payloadRaw: z.ZodOptional<z.ZodString>;
+    signature: z.ZodNullable<z.ZodString>;
+    timestamp: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type ExecEventMessage = z.infer<typeof ExecEventMessageSchema>;
+/**
+ * One buffered progress event in a poll response: the sandbox's monotonic
+ * per-exec sequence number (the poll cursor) plus the event payload the host
+ * forwards via `emit` — the same payload a callback-mode event POST carries.
+ */
+export declare const PollEventSchema: z.ZodObject<{
+    seq: z.ZodNumber;
+    payload: z.ZodUnknown;
+}, z.core.$strip>;
+export type PollEvent = z.infer<typeof PollEventSchema>;
+/**
+ * Body of `GET /exec/{execId}?since={cursor}` in poll mode. Mirrors Go's
+ * `pollResponseBody`: the events newer than the caller's cursor, the new
+ * high-water `cursor`, a `truncated` marker set once the ring shed an event,
+ * and — once the exec is terminal — the completion `result` (with its
+ * provenance frame). The whole body is HMAC-signed, verified exactly as a
+ * pushed completion is.
+ */
+export declare const PollResponseSchema: z.ZodObject<{
+    status: z.ZodString;
+    events: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        seq: z.ZodNumber;
+        payload: z.ZodUnknown;
+    }, z.core.$strip>>>;
+    cursor: z.ZodNumber;
+    truncated: z.ZodDefault<z.ZodBoolean>;
+    result: z.ZodOptional<z.ZodObject<{
+        execId: z.ZodString;
+        exitCode: z.ZodNullable<z.ZodNumber>;
+        stdout: z.ZodDefault<z.ZodString>;
+        stderr: z.ZodDefault<z.ZodString>;
+        durationMs: z.ZodNullable<z.ZodNumber>;
+        timedOut: z.ZodDefault<z.ZodBoolean>;
+        syntheticFailure: z.ZodOptional<z.ZodObject<{
+            reason: z.ZodString;
+        }, z.core.$strip>>;
+        provenance: z.ZodOptional<z.ZodObject<{
+            disabled: z.ZodDefault<z.ZodBoolean>;
+            reads: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                layers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>>;
+            writes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                layers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>>;
+            deletes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                layers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PollResponse = z.infer<typeof PollResponseSchema>;
+/**
+ * Done-marker shape the recv loop unwraps. Both real completion POSTs
+ * (wrapped by the `/complete` handler) and watchdog synthetic-failure
+ * sends use this discriminant.
+ */
+export interface DoneMarker {
+    done: true;
+    result: ExecResult;
+}
+export interface SyntheticFailureMarker {
+    done: true;
+    result: ExecResult;
+    kind: "synthetic-failure";
+    reason: string;
+}
+export declare function isDoneMarker(value: unknown): value is DoneMarker;
+export declare function isSyntheticFailure(value: unknown): value is SyntheticFailureMarker;
+/** Wire shape `submitExec` POSTs to sandbox-server's `/exec` (change 4). */
+export interface SubmitExecBody {
+    command: string[];
+    execId: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutSeconds?: number;
+}
+/** Step-meta passed to `createSandbox` — what the registry row needs. */
+export interface CreateSandboxMeta {
+    runId: string;
+    stepId: string;
+    analysisId: string;
+    /** The first `execId` that will fire against this sandbox; nullable for
+     *  early-create flows where the workflow mints the first execId later. */
+    execId?: string | null;
+    /** Owning DBOS child workflow id (`"${parentRunId}-${N}"`). Stamped onto the
+     *  sandbox machine as the `cortex/owner-workflow-id` label so the reaper can
+     *  map a cluster-side machine back to its workflow and check liveness. */
+    childWorkflowId: string;
+    /** Backend-specific extras carried through to the per-backend impl. */
+    image?: string;
+    extraEnv?: Record<string, string>;
+    /** CPU/memory/GPU request for the sandbox machine. Required of every
+     *  caller — `createSandboxClient` clamps it to cluster limits and rejects
+     *  a sandbox with none. */
+    resources: ResourceSpec;
+    /** Enforced read-only: provision with no read-write step mount, only the
+     *  read-only analysis tree. Used by the ephemeral executor. */
+    readOnly?: boolean;
+}
+/**
+ * The identity minted for a sandbox machine *before* it is spawned — the
+ * durable half of the two-step create (see the harness-sandbox-exec spec). Step 1 checkpoints this so a
+ * recovery re-run of the spawn step adopts the already-created machine under
+ * the same name and HMAC secret instead of leaking a second one.
+ */
+export interface SandboxIdentity {
+    /** `sbx-{run8}-{uuid4}` — informative for `kubectl`, not load-bearing; the
+     *  checkpoint, not the name, is what makes create idempotent. */
+    sandboxId: string;
+    /** 32-byte base64 HMAC secret (see the harness-sandbox-exec spec); rides into the machine's env. */
+    callbackSecret: string;
+}
+/**
+ * A sandbox machine the backend is running that Cortex *manages*
+ * (`app.kubernetes.io/managed-by=cortex`), enumerated by the reaper for the
+ * cluster→registry sweep (see the harness-sandbox-exec spec). The `ownerWorkflowId` comes from the
+ * `cortex/owner-workflow-id` label and may be null for legacy/label-less
+ * machines, which are only reaped past a creation-time grace.
+ */
+export interface ManagedSandbox {
+    sandboxId: string;
+    ownerWorkflowId: string | null;
+    createdAtMs: number | null;
+}
+/**
+ * Per-step `emit` callback handed to `awaitExec`. May be async — `awaitExec`
+ * runs in the workflow body (see the harness-tools spec) and `await`s each emit so the body-path
+ * `DBOS.writeStream` it drives lands at a deterministic function-ID (see the harness-durable-runtime spec).
+ */
+export type ExecEmit = (event: unknown) => void | Promise<void>;

package/dist/sandbox/types.js

@@ -0,0 +1,147 @@
+/**
+ * Sandbox-client types — the wire/persistence shapes that cross the
+ * submit/recv protocol (see the harness-sandbox-exec spec) and the active-sandbox registry.
+ *
+ * `SandboxRef` is the in-memory handle the harness uses to talk to a live
+ * sandbox; it carries the per-sandbox `callbackSecret` (see the harness-sandbox-exec spec). The
+ * persistable subset is `PersistedSandboxRef` (from `harness/state/schema.ts`)
+ * — that one OMITS the secret, which lives only in the cached
+ * `createSandbox` DBOS step output.
+ */
+import { z } from "zod";
+import { PersistedSandboxRefSchema } from "../state/schema.js";
+export const SandboxBackend = z.enum(["docker", "k8s"]);
+/**
+ * How a command's progress events and terminal result reach the host. Chosen by
+ * the embedder at its composition root and carried into the container as
+ * `SANDBOX_TRANSPORT`; backend-independent. The OSS default is `poll`.
+ *
+ * - `poll`: the host polls `GET /exec/{execId}?since={cursor}`; the sandbox
+ *   never dials out and needs no egress.
+ * - `callback`: the sandbox POSTs signed event/completion callbacks; the
+ *   embedder runs an ingress. `GET /exec/{execId}` stays the recovery backstop.
+ */
+export const SandboxTransportSchema = z.enum(["poll", "callback"]);
+export const SandboxRefSchema = PersistedSandboxRefSchema.extend({
+    /**
+     * 32-byte high-entropy bytes, base64-encoded. Minted once at
+     * `createSandbox` and handed to the sandbox container via
+     * `SANDBOX_CALLBACK_SECRET`. Never persisted outside the DBOS
+     * step-output cache.
+     */
+    callbackSecret: z.string(),
+});
+/** Strip the secret before persisting to the active-sandbox registry. */
+export function toPersistedRef(ref) {
+    return {
+        sandboxId: ref.sandboxId,
+        host: ref.host,
+        port: ref.port,
+        backend: ref.backend,
+    };
+}
+/**
+ * One tracked file operation in the sandbox-server provenance frame.
+ * Mirrors Go's `ProvenanceEntry` (`images/sandbox-base/server/provenance.go`):
+ * an absolute container path plus the capture layers that observed it.
+ */
+export const ProvenanceFrameEntrySchema = z.object({
+    path: z.string(),
+    layers: z.array(z.string()).default([]),
+});
+/**
+ * Runtime file-I/O frame sandbox-server attaches to the `/complete`
+ * callback. Mirrors Go's `provenancePayload` — every field is
+ * `omitempty` on the wire, so each arm defaults so a completion that
+ * omits the frame (or any arm) still parses.
+ */
+export const ProvenanceFrameSchema = z.object({
+    disabled: z.boolean().default(false),
+    reads: z.array(ProvenanceFrameEntrySchema).default([]),
+    writes: z.array(ProvenanceFrameEntrySchema).default([]),
+    /**
+     * Reserved. All four sandbox capture layers report deletes per the
+     * sandbox-provenance-tracking spec, but the harness has no consumer —
+     * `feedExecFrame` reads only `reads`/`writes`. Kept on the wire for a
+     * future invalidation mapping.
+     */
+    deletes: z.array(ProvenanceFrameEntrySchema).default([]),
+});
+/**
+ * Final outcome of a single exec, returned by `awaitExec`. Mirrors the
+ * sandbox-server completion payload plus a discriminant for synthetic
+ * (watchdog-emitted) failures.
+ */
+export const ExecResultSchema = z.object({
+    execId: z.string(),
+    exitCode: z.number().nullable(),
+    stdout: z.string().default(""),
+    stderr: z.string().default(""),
+    durationMs: z.number().nullable(),
+    timedOut: z.boolean().default(false),
+    /** Set when the watchdog synthesises a completion for a dead sandbox. */
+    syntheticFailure: z
+        .object({
+        reason: z.string(),
+    })
+        .optional(),
+    /**
+     * Runtime file-I/O frame from sandbox-server. Optional so synthetic
+     * watchdog failures and pre-change cached recv messages parse; rides
+     * the recv payload into the durable DBOS step output.
+     */
+    provenance: ProvenanceFrameSchema.optional(),
+});
+/**
+ * Per-message envelope on the per-exec DBOS topic. Real callbacks carry
+ * a non-null `signature` and `timestamp`; the in-process watchdog uses a
+ * `null` signature + a `synthetic-failure` payload (see `await-exec.ts`).
+ *
+ * `payloadRaw` is the exact bytes sandbox-server POSTed — sandbox-server's
+ * HMAC signs the raw body, and Go's `encoding/json` HTML-escapes `<`, `>`,
+ * `&` by default, so verifying against a JS re-serialization of the parsed
+ * payload would diverge for any output containing those characters
+ * (common in bioinformatics: FASTA headers, shell stderr, command pipelines).
+ * Optional only for back-compat with messages that pre-date this field.
+ */
+export const ExecEventMessageSchema = z.object({
+    payload: z.unknown(),
+    payloadRaw: z.string().optional(),
+    signature: z.string().nullable(),
+    timestamp: z.number().int().nullable(),
+});
+/**
+ * One buffered progress event in a poll response: the sandbox's monotonic
+ * per-exec sequence number (the poll cursor) plus the event payload the host
+ * forwards via `emit` — the same payload a callback-mode event POST carries.
+ */
+export const PollEventSchema = z.object({
+    seq: z.number().int(),
+    payload: z.unknown(),
+});
+/**
+ * Body of `GET /exec/{execId}?since={cursor}` in poll mode. Mirrors Go's
+ * `pollResponseBody`: the events newer than the caller's cursor, the new
+ * high-water `cursor`, a `truncated` marker set once the ring shed an event,
+ * and — once the exec is terminal — the completion `result` (with its
+ * provenance frame). The whole body is HMAC-signed, verified exactly as a
+ * pushed completion is.
+ */
+export const PollResponseSchema = z.object({
+    status: z.string(),
+    events: z.array(PollEventSchema).default([]),
+    cursor: z.number().int(),
+    /**
+     * Sticky ring-shed marker. Deliberately unused by the poll loop — the
+     * seq-gap arithmetic detects sheds without it — but kept on the wire for
+     * consumers that want the sandbox's own flag rather than deriving it.
+     */
+    truncated: z.boolean().default(false),
+    result: ExecResultSchema.optional(),
+});
+export function isDoneMarker(value) {
+    return (typeof value === "object" && value !== null && value.done === true && typeof value.result === "object");
+}
+export function isSyntheticFailure(value) {
+    return isDoneMarker(value) && value.kind === "synthetic-failure";
+}