@boardwalk-labs/runner 0.1.21 → 0.2.1

package/dist/runtime/suspension.js

@@ -1,120 +1,27 @@
-// Durable-suspension primitives for the JS-body worker (the durable-suspension design).
+// Suspension primitives for the JS-body worker (the snapshot-substrate model).
 //
-// A run SUSPENDS at a durable seam — a long `sleep`, a `humanInput()` gate, or the in-leaf
-// `human_input` tool — by releasing its Fargate task and re-acquiring one on wake. The mechanism is
-// a JOURNAL: every memoizable seam (`agent` / `step` / `humanInput` / `sleep`) is keyed by a
-// synchronous monotonic `seq` and records its whole result, so a resumed run RESTARTS from the top
-// and replays through the journal (a hit returns the memoized value instantly; we never replay an
-// LLM turn — we memoize whole results, the `findChildCall` pattern generalized). This is NOT
-// Temporal-style turn replay, so it does not violate the no-replay-engine rule (CLAUDE.md).
+// A run SUSPENDS at a waiting seam — a long `sleep`, a `humanInput()` gate, or the in-leaf
+// `human_input` tool — by freezing the WHOLE microVM: the freeze coordinator quiesces platform
+// streams, the host snapshots memory, and the wake restores the literal heap, so the seam's
+// `await` resolves in place. There is no journal and no replay — the heap is the durable unit.
 //
-// This file holds the SHARED pieces the host + worker + broker client agree on: the suspend signal a
-// seam raises, the journal seam the host reads/writes, the seq sequencer driving silent replay, and
-// the determinism fingerprint. The behavior is conformance-pinned to the OSS engine's
-// `src/run/child_host.ts` — the two runtimes must suspend + resume identically.
-import { createHash } from "node:crypto";
-import { z } from "zod";
-import { AppError, ErrorCode } from "./support/index.js";
+// A runtime with NO freeze substrate (a self-hosted runner daemon, unit tests, the Fargate
+// break-glass) HOLDS instead: the seam blocks the live process until its condition is met. One
+// mechanism serves every non-snapshot surface; the run pays for the idle wait.
+//
+// This file holds the SHARED pieces the host + worker + broker client agree on: the suspend
+// signal a seam raises (what the broker persists as the wake condition) and the human-input gate
+// it carries.
 /**
- * Sleeps at/above this hold-vs-release boundary SUSPEND (release the task; a timer re-dispatches the
- * run when due); shorter ones HOLD the process in-memory, where a release + replay round-trip costs
- * more than it saves. Mirrors the engine's `SUSPEND_THRESHOLD_MS` so the two runtimes draw the line
- * in the same place.
+ * Sleeps at/above this boundary SUSPEND on the snapshot substrate (freeze the VM; the wake fires
+ * when the sleep is due); shorter ones HOLD the process in-memory, where a snapshot round-trip
+ * costs more than it saves. Without a freeze substrate every sleep holds, whatever its length.
  */
 export const SUSPEND_THRESHOLD_MS = 30_000;
-/**
- * The control signal a host seam raises to suspend the run. Unlike the engine (a child process the
- * supervisor kills out-of-band), the backend worker runs the program IN-PROCESS, so a suspend is
- * surfaced by the host calling `onSuspend(signal)` and returning a NEVER-resolving promise; the
- * worker races that against the program body and tears down. This class exists so a seam that has no
- * `onSuspend` wired (the local/test path) can still raise a typed, catchable signal.
- */
-export class SuspendError extends Error {
-    signal;
-    constructor(signal) {
-        super(`run suspended (${signal.reason}) at seam ${String(signal.seq)}`);
-        this.name = "SuspendError";
-        this.signal = signal;
-    }
-}
-/** Journal-entry states (mirrors `run_journal.state` + the engine's IPC). */
-export const JOURNAL_STATES = ["pending", "suspended", "resolved"];
-/** Validate the broker's journal_get response (the worker's run token doesn't exempt the channel from
- *  validation). The result is genuinely heterogeneous JSON (an agent return / a LeafResume / a
- *  HumanInputResult), parsed per-kind downstream — so it stays `unknown` here, the validation seam. */
-export const journalLookupSchema = z.object({
-    seq: z.number().int().positive(),
-    kind: z.enum(["agent", "step", "human_input", "sleep", "workflow_call"]),
-    fingerprint: z.string(),
-    state: z.enum(JOURNAL_STATES),
-    result: z.unknown(),
-});
-/**
- * The synchronous, monotonic durable-seam counter. Incremented at each journaled seam's ENTRY:
- * because a program's synchronous call order is deterministic (even under `Promise.all`, whose
- * `.map(...)` runs left-to-right synchronously), the same logical call gets the same `seq` on every
- * execution — the journal key that lets a resumed run return a memoized result.
- *
- * It also drives SILENT REPLAY: a resume starts suppressed (observability — console output, phase
- * markers — was already emitted last segment) and goes `live` the moment it reaches the suspending
- * seam (the frontier = the highest journaled seq). A fresh run (frontier 0) is live immediately.
- */
-export class SeamSequencer {
-    replayFrontier;
+/** A monotonic per-run counter for suspension/gate keys (the `seq` on {@link SuspendSignal}). */
+export class SuspensionCounter {
     count = 0;
-    liveFlag;
-    constructor(replayFrontier = 0) {
-        this.replayFrontier = replayFrontier;
-        this.liveFlag = replayFrontier === 0;
-    }
     next() {
-        const seq = ++this.count;
-        if (seq >= this.replayFrontier)
-            this.liveFlag = true;
-        return seq;
-    }
-    /** True once execution has crossed the replay frontier — output after this point is NEW. */
-    get isLive() {
-        return this.liveFlag;
+        return ++this.count;
     }
-    /** True while re-running already-journaled seams on a resume (observability suppressed). */
-    isReplaying() {
-        return !this.liveFlag;
-    }
-}
-/** The child run id a `workflow_call` seam journals while it waits (parsed back on resume). */
-export const childRunIdSchema = z.string().min(1);
-/** A stable content hash of a seam's salient args — the determinism check on replay. Identical
- *  construction to the engine's `seamFingerprint` so a journal written by one runtime validates in
- *  the other (the conformance promise). */
-export function seamFingerprint(parts) {
-    return createHash("sha256").update(JSON.stringify(parts)).digest("hex");
 }
-/** A seam reached on replay didn't match what the journal recorded at that seq — the workflow's code
- *  on the path to a suspend changed (a different prompt/model/step name, or a different seam kind).
- *  Fails the run loudly rather than returning a stale memoized result for the wrong call. */
-export function determinismError(seq, got, recorded) {
-    const detail = got === recorded
-        ? `the same "${got}" seam but with different arguments (a changed prompt, model, or step name)`
-        : `a "${recorded}" call, but this execution reached a "${got}" call`;
-    return new AppError(ErrorCode.VALIDATION_FAILED, `Nondeterministic replay at seam ${String(seq)}: the journal recorded ${detail}. A workflow's ` +
-        `code on the path to a suspend/resume must be deterministic — route nondeterministic I/O ` +
-        `through agent(), step.run(), or workflows.call so it is journaled.`, { kind: "nondeterministic_replay", seq });
-}
-/**
- * The shape of a SUSPENDED agent leaf's journal result on resume: the transcript checkpoint plus the
- * answers the broker joined from the resolved request rows, keyed by tool-call id. `messages` is the
- * engine's own serialized transcript round-tripping through JSON — handed straight back to the leaf,
- * not re-validated field-by-field. Structurally a {@link LeafResume}.
- */
-export const leafResumeSchema = z.object({
-    checkpoint: z.object({
-        messages: z.array(z.custom()),
-        iteration: z.number().int(),
-        totals: z.object({
-            inputTokens: z.number().int(),
-            outputTokens: z.number().int(),
-        }),
-    }),
-    answers: z.record(z.string(), z.unknown()),
-});

package/dist/runtime/wire/human_input.d.ts

@@ -28,7 +28,7 @@ export type ParsedHumanInputSpec = z.infer<typeof humanInputSpecSchema>;
 export declare function parseHumanInputSpec(raw: unknown): ParsedHumanInputSpec;
 /** Re-hydrate a stored (jsonb) human-input result into the exact-optional SDK {@link HumanInputResult}
  *  (the host returns it from a resumed `humanInput()` seam). The value was validated on submit, so a
- *  parse failure here is a corrupt journal — surfaced as a clear program error. */
+ *  parse failure here is a corrupt stored answer — surfaced as a clear program error. */
 export declare function normalizeHumanInputResult(raw: unknown): HumanInputResult;
 /** Convert a validated {@link HumanInputResult} to a {@link JsonValue} for storage (the result is an
  *  interface with optional props, which TS won't structurally accept as JsonValue; an explicit object

package/dist/runtime/wire/human_input.js

@@ -3,7 +3,7 @@
 // The `HumanInputSpec` is the single source of truth for BOTH the UI form and server-side
 // validation, so a `humanInput()` gate needs no JSON Schema. A responder's raw submission (from
 // REST / MCP / CLI / web) is validated here against the gate's stored spec into a typed
-// `HumanInputResult`, which becomes the seam's memoized journal value. Pure + exhaustively testable.
+// `HumanInputResult`, the value the seam returns to the program. Pure + exhaustively testable.
 //
 // These mirror the SDK's `@boardwalk-labs/workflow` types exactly (the wire contract); we re-derive
 // them as Zod schemas because the stored `input_spec` is `unknown` jsonb that must be parsed at the
@@ -51,7 +51,7 @@ export function parseHumanInputSpec(raw) {
 }
 /** Re-hydrate a stored (jsonb) human-input result into the exact-optional SDK {@link HumanInputResult}
  *  (the host returns it from a resumed `humanInput()` seam). The value was validated on submit, so a
- *  parse failure here is a corrupt journal — surfaced as a clear program error. */
+ *  parse failure here is a corrupt stored answer — surfaced as a clear program error. */
 export function normalizeHumanInputResult(raw) {
     const parsed = storedResultSchema.safeParse(raw);
     if (!parsed.success) {

package/dist/runtime/workflow_host.d.ts

@@ -1,7 +1,7 @@
 import type { WorkflowHost, AgentOptions, ArtifactBody, ArtifactRef, BrowserSession, BrowserSessionOptions, CallOptions, HumanInputOptions, HumanInputResult, PhaseOptions, SleepArg } from "@boardwalk-labs/workflow/runtime";
 import type { BrowserSessionManager } from "./browser_session.js";
 import { type LeafResume } from "@boardwalk-labs/engine/core";
-import { type JournalSeam, type SuspendSignal } from "./suspension.js";
+import { type SuspendSignal } from "./suspension.js";
 import type { FreezeCoordinator } from "./freeze_coordinator.js";
 /** Parse a `humanInput({ timeout })` string (`"48h"`, `"30m"`, `"90s"`, `"7d"`) to milliseconds, or
  *  null when absent/unparseable (the gate then waits indefinitely). */
@@ -36,16 +36,15 @@ export interface ChildResult {
     status: string;
     output: unknown;
 }
-/** Dispatches child runs: `call` holds + returns output (the no-journal path); `start`/`poll` back the
- *  DURABLE callWorkflow seam (start once, suspend `waiting_for_child` on a non-terminal child, poll on
- *  resume); `run` is fire-and-forget → run id; `schedule` provisions a durable future/recurring run →
- *  schedule id. The `signal` lets a hold/start abort promptly when the parent run is cancelled. */
+/** Dispatches child runs: `call` holds in-process + returns the completed child's output (the
+ *  hold path); `start`/`poll` back the snapshot-substrate callWorkflow seam (start once, freeze
+ *  `waiting_for_child` on a non-terminal child); `run` is fire-and-forget → run id; `schedule`
+ *  provisions a durable future/recurring run → schedule id. The `signal` lets a hold/start abort
+ *  promptly when the parent run is cancelled. */
 export interface ChildDispatcher {
     call(slug: string, input: unknown, opts: CallOptions | undefined, signal?: AbortSignal): Promise<unknown>;
     /** Start (or idempotently re-attach to) a child run; resolves its current state. */
     start(slug: string, input: unknown, opts: CallOptions | undefined, signal?: AbortSignal): Promise<ChildResult>;
-    /** Poll a child run's current state by id, or null when it isn't this run's child. */
-    poll(childRunId: string): Promise<ChildResult | null>;
     run(slug: string, input: unknown, opts: CallOptions | undefined): Promise<string>;
     schedule(slug: string, input: unknown, opts: ScheduleOptions): Promise<string>;
 }
@@ -53,9 +52,10 @@ export interface ChildDispatcher {
 export interface SecretAccessor {
     get(name: string): Promise<string>;
 }
-/** Register-without-release: register a HELD HITL gate so it is
- *  answerable while the run keeps running, and poll for the answer. Backed by the broker's
- *  `inputs` endpoints. Absent ⇒ a held gate is only answerable once it freezes. */
+/** Register a HELD HITL gate so it is answerable while the run keeps its process, and poll for
+ *  the answer. Backed by the broker's `inputs` endpoints. On the snapshot substrate this is the
+ *  register-without-release half of a freeze; on a no-freeze runtime (a self-hosted daemon) it is
+ *  the WHOLE mechanism — the seam registers, then holds and polls until answered. */
 export interface HeldInputPort {
     register(seq: number, gate: SuspendSignal["humanInput"]): Promise<unknown>;
     poll(seq: number): Promise<Record<string, unknown>>;
@@ -130,39 +130,21 @@ export interface WorkerWorkflowHostDeps {
     now?: () => number;
     /** Override the 7-day hold ceiling (tests). */
     maxSleepMs?: number;
-    /**
-     * Durable-suspension journal (the durable-suspension design): the host memoizes each `agent`/`step`/`sleep`/
-     * `humanInput` seam here, so a resumed run replays journaled seams instantly instead of re-running
-     * them. Backed by the broker over the run token on hosted runs. Absent ⇒ no memoization (the
-     * local/test path): seams run live every time and a suspend can't be resumed.
-     */
-    journal?: JournalSeam;
-    /**
-     * Raise a durable suspension: the host calls this from a suspending seam, then returns a
-     * never-resolving promise; the worker races that against the program body and tears the task down
-     * (the program's own `try/catch` can't swallow a suspend this way). Absent ⇒ a suspending seam
-     * rejects with {@link SuspendError} instead (the local/test path).
-     */
-    onSuspend?: (signal: SuspendSignal) => void;
     /**
      * Snapshot-substrate suspension (the microVM freeze model): when present, a suspending seam
-     * BLOCKS on the coordinator instead of raising `onSuspend` — the platform freezes the whole VM
-     * and a wake resolves the seam in place, heap intact (no exit, no journal replay). Every hook
-     * also runs under the coordinator's quiescence gate: a freeze never captures a live platform
-     * stream, and work arriving while a freeze is pending queues until the wake.
+     * BLOCKS on the coordinator — the platform freezes the whole VM and a wake resolves the seam in
+     * place, heap intact. Every hook also runs under the coordinator's quiescence gate: a freeze
+     * never captures a live platform stream, and work arriving while a freeze is pending queues
+     * until the wake. Absent ⇒ the no-substrate HOLD path: a waiting seam blocks the live process
+     * for the whole wait (self-hosted daemons, the Fargate break-glass, unit tests).
      */
     freeze?: FreezeCoordinator;
-    /** Register-without-release for HELD human-input gates. Only
-     *  meaningful alongside `freeze`; absent ⇒ a held gate is answerable only once it freezes. */
+    /** Register + poll for HELD human-input gates (see {@link HeldInputPort}). Absent alongside
+     *  `freeze` ⇒ a held gate is answerable only once it freezes; absent WITHOUT `freeze` ⇒
+     *  humanInput is unsupported in this runtime and rejects clearly. */
     heldInput?: HeldInputPort;
     /** Poll interval for a held gate's answer (default 3s). */
     heldPollIntervalMs?: number;
-    /**
-     * The highest journaled seq at claim (0 on a fresh run). While re-running seams up to this
-     * frontier on a resume, the host is REPLAYING and observability (phase markers, program logs) is
-     * suppressed — those lines were emitted in the prior segment.
-     */
-    replayFrontier?: number;
 }
 export declare class WorkerWorkflowHost implements WorkflowHost {
     private readonly deps;
@@ -170,18 +152,11 @@ export declare class WorkerWorkflowHost implements WorkflowHost {
     private readonly now;
     private readonly maxSleepMs;
     private readonly heldPollIntervalMs;
-    /** Synchronous durable-seam counter + silent-replay live flag (the durable-suspension design). */
+    /** Monotonic per-run counter keying suspensions + their HITL gate rows. */
     private readonly seq;
     /** Run context + on-demand public-API bearer the SDK `runtime` accessor reads off the host. */
     readonly runtime: RuntimeContext;
     constructor(deps: WorkerWorkflowHostDeps);
-    /** True while re-running already-journaled seams on a resume (the worker suppresses program-log +
-     *  phase observability during this window — those lines were emitted in the prior segment). */
-    isReplaying(): boolean;
-    /** Raise a durable suspension. With `onSuspend` wired (the real worker) the host signals out-of-band
-     *  and returns a never-resolving promise, so the program's own try/catch can't swallow it; without
-     *  it (the local/test path) it rejects with {@link SuspendError}. */
-    private suspend;
     /** Run `fn` only if the run isn't aborted; otherwise REJECT (never throw synchronously) with the
      *  signal's RunAbortedError — every Promise-returning hook funnels through this so callers always
      *  get a rejected promise on abort, not a sync throw. On the snapshot substrate the body also runs
@@ -207,6 +182,13 @@ export declare class WorkerWorkflowHost implements WorkflowHost {
      *  the answer value; never rejects the run (a transient poll error just retries next tick). Runs
      *  OUTSIDE the quiescence gate (it is not run work — it must not block a freeze). */
     private pollHeldAnswer;
+    /**
+     * The no-freeze HOLD for a human-input gate: register it with the broker (it surfaces in the
+     * inbox/API at once), then poll until the answer arrives — the process stays alive and pays
+     * for the wait. Rejects promptly when the run's abort signal fires (cancel / credit stop),
+     * which is also how a server-side gate expiry that fails the run unwinds this loop.
+     */
+    private holdForAnswer;
     /** Map a froze/aborted freeze outcome to the gate's answer (or throw on an unexpected abort). */
     private resolveFreezeAnswer;
     /** The wake's answer for one gate key. A wake whose value is missing the parked gate means the
@@ -215,26 +197,46 @@ export declare class WorkerWorkflowHost implements WorkflowHost {
     private gateAnswer;
     setPhase(name: string, opts: PhaseOptions | undefined): void;
     agent(prompt: string, opts: AgentOptions | undefined): Promise<unknown>;
-    /** The `agent()` durable seam: a journal hit returns the memoized result (never re-runs the LLM); a
-     *  `suspended` hit resumes a parked leaf from its checkpoint + answers; a miss runs the leaf and
-     *  journals the result. A leaf that PARKS (the model called `human_input`) suspends the run. */
+    /** The `agent()` seam: run the leaf to completion. A leaf that PARKS (the model called the
+     *  `human_input` tool) waits for the answer — a freeze on the snapshot substrate, a held poll
+     *  otherwise — and re-enters from its in-memory checkpoint. Nothing is memoized: a crash-restart
+     *  re-runs the leaf (restart-from-top semantics). */
     private agentSeam;
-    /** Program-level `humanInput()`: suspend the run on a gate, resume with the validated answer. The
-     *  SDK marks this optional; the hosted host always implements it. */
+    /** Program-level `humanInput()`: wait on a gate — a freeze on the snapshot substrate, a held
+     *  poll otherwise — and return the validated answer. The SDK marks this optional; the hosted
+     *  host always implements it. */
     humanInput(opts: HumanInputOptions): Promise<HumanInputResult>;
     private humanInputSeam;
+    /**
+     * Park the run at a BUDGET gate and resolve with the responder's answer (docs/SUSPEND_POLICY.md
+     * Decision 3). Called by the leaf executor's `streamModel` seam when the run's `max_usd` cap is
+     * breached, i.e. from INSIDE an in-flight `agent()` — which drives two deliberate differences from
+     * {@link humanInputSeam}:
+     *
+     *  - **No `guarded()` wrapper.** The enclosing `agent()` seam already counted this leaf as work via
+     *    `trackWork`. Wrapping again would double-count it, and the extra count would never be released
+     *    — quiescence would never be reached and the freeze would hang forever. `freezeHumanInput` →
+     *    `freezeWait` does the right thing here: it `endWork`s for the duration of the park (this leaf
+     *    is waiting, not working, which is exactly what lets the run reach quiescence and freeze) and
+     *    rejoins on resume.
+     *  - **Abort is not re-checked up front.** `streamModel` has just done it; a park is not a new
+     *    entry point.
+     *
+     * The gate itself is an ordinary {@link HumanInputGate} keyed `budget`, so it persists, surfaces in
+     * the inbox, and is answered by the same machinery as any other gate. No timeout: an unanswered
+     * budget gate is aged out by the control plane's inactive-cancel reaper, not by a wake we schedule.
+     */
+    budgetClearance(gate: {
+        prompt: string;
+        inputSpec: unknown;
+    }): Promise<HumanInputResult>;
     /** Absolute wake time for a `humanInput({ timeout })`, or null when there is none / it's unparseable. */
     private timeoutExpiry;
-    /** `step.run(name, fn)`: run `fn` exactly once across restarts, memoizing its result in the journal
-     *  (the escape hatch for nondeterministic work on a suspend/resume path). */
-    step(name: string, fn: () => unknown): Promise<unknown>;
-    private stepSeam;
     callWorkflow(slug: string, input: unknown, opts: CallOptions | undefined): Promise<unknown>;
-    /** The `workflows.call` durable seam (the durable-suspension design): start the child once + memoize its
-     *  output; a non-terminal child SUSPENDS the parent (`waiting_for_child`, the child's id journaled)
-     *  — the parent releases its task and is woken when the child finalizes. On resume the seam polls
-     *  the journaled child and returns its output (or throws on a failed child). Without a journal (the
-     *  local/test path) it falls back to the in-process hold-and-poll. */
+    /** The `workflows.call` seam: start the child once (idempotently — the child's run row is the
+     *  durable memo, so a crash-restarted parent re-attaches instead of re-spawning). A non-terminal
+     *  child suspends the parent `waiting_for_child` on the snapshot substrate (the wake carries the
+     *  finalized child, heap intact); without one the parent HOLDS in-process and polls. */
     private callWorkflowSeam;
     /** Fire-and-forget trigger of another workflow; resolves to the new run's id (no hold/poll). */
     runWorkflow(slug: string, input: unknown, opts: CallOptions | undefined): Promise<string>;
@@ -245,7 +247,7 @@ export declare class WorkerWorkflowHost implements WorkflowHost {
     writeArtifact(name: string, contentType: string, body: ArtifactBody, metadata: Record<string, unknown> | undefined): Promise<ArtifactRef>;
     /** `computer.openBrowser()`: open a program-owned, in-VM browser session (the browser tier of
      *  computer use). Not a durable seam — a session is a live resource, reaped at run end, never
-     *  journaled/replayed. Absent backend ⇒ a clear "not available" error. */
+     *  persisted. Absent backend ⇒ a clear "not available" error. */
     openBrowserSession(opts: BrowserSessionOptions | undefined): Promise<BrowserSession>;
     /** Translate `agent({ session })` into the leaf's `mcp`: append the browser session's in-VM
      *  Playwright MCP (its http ref, which passes assertHostedMcpAllowed and reaches localhost without
@@ -253,9 +255,10 @@ export declare class WorkerWorkflowHost implements WorkflowHost {
      *  no session is bound. */
     private bindBrowserSession;
     sleep(arg: SleepArg): Promise<void>;
-    /** A short sleep HOLDS the task in-process (cheaper than a release + replay round-trip); a long one
-     *  (≥ {@link SUSPEND_THRESHOLD_MS}) SUSPENDS — releases the task, and a timer re-dispatches the run
-     *  when due. Journaled so a resumed run replays past an already-elapsed sleep instantly. */
+    /** A short sleep HOLDS the task in-process (cheaper than a snapshot round-trip); a long one
+     *  (≥ {@link SUSPEND_THRESHOLD_MS}) SUSPENDS on the snapshot substrate — the VM freezes and the
+     *  wake resolves this very await, heap intact. Without a freeze substrate EVERY sleep holds,
+     *  whatever its length (the no-substrate rule: snapshot or hold, never replay). */
     private sleepSeam;
     /** Resolve any {@link SleepArg} shape to a millisecond duration from now. */
     private resolveSleepMs;