@boardwalk-labs/runner 0.1.21 → 0.2.0

package/dist/runtime/workflow_host.js

@@ -12,7 +12,7 @@
 import { AppError, ErrorCode } from "./support/index.js";
 import { LeafParked } from "@boardwalk-labs/engine/core";
 import { normalizeHumanInputResult } from "./wire/human_input.js";
-import { SeamSequencer, SuspendError, childRunIdSchema, determinismError, leafResumeSchema, seamFingerprint, SUSPEND_THRESHOLD_MS, } from "./suspension.js";
+import { SuspensionCounter, SUSPEND_THRESHOLD_MS } from "./suspension.js";
 import { throwIfAborted } from "./run_abort.js";
 /** Parse a `humanInput({ timeout })` string (`"48h"`, `"30m"`, `"90s"`, `"7d"`) to milliseconds, or
  *  null when absent/unparseable (the gate then waits indefinitely). */
@@ -68,7 +68,7 @@ export class WorkerWorkflowHost {
     now;
     maxSleepMs;
     heldPollIntervalMs;
-    /** Synchronous durable-seam counter + silent-replay live flag (the durable-suspension design). */
+    /** Monotonic per-run counter keying suspensions + their HITL gate rows. */
     seq;
     /** Run context + on-demand public-API bearer the SDK `runtime` accessor reads off the host. */
     runtime;
@@ -78,25 +78,9 @@ export class WorkerWorkflowHost {
         this.now = deps.now ?? Date.now;
         this.maxSleepMs = deps.maxSleepMs ?? MAX_SLEEP_MS;
         this.heldPollIntervalMs = deps.heldPollIntervalMs ?? 3_000;
-        this.seq = new SeamSequencer(deps.replayFrontier ?? 0);
+        this.seq = new SuspensionCounter();
         this.runtime = deps.runtime;
     }
-    /** 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() {
-        return this.seq.isReplaying();
-    }
-    /** 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}. */
-    suspend(signal) {
-        if (this.deps.onSuspend === undefined)
-            return Promise.reject(new SuspendError(signal));
-        this.deps.onSuspend(signal);
-        return new Promise(() => {
-            /* never settles: the worker races this against the body and tears the task down */
-        });
-    }
     /** 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
@@ -185,6 +169,31 @@ export class WorkerWorkflowHost {
             });
         }
     }
+    /**
+     * 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.
+     */
+    async holdForAnswer(seq, gate) {
+        const held = this.deps.heldInput;
+        if (held === undefined || gate === undefined) {
+            throw new AppError(ErrorCode.VALIDATION_FAILED, "humanInput is not available in this runtime (no control-plane connection to register the gate)", { kind: "human_input_unavailable" });
+        }
+        await held.register(seq, gate);
+        for (;;) {
+            throwIfAborted(this.deps.signal);
+            try {
+                const answers = await held.poll(seq);
+                if (gate.key in answers)
+                    return answers[gate.key];
+            }
+            catch {
+                /* transient — retry next tick */
+            }
+            await this.sleeper.hold(this.heldPollIntervalMs, this.deps.signal);
+        }
+    }
     /** Map a froze/aborted freeze outcome to the gate's answer (or throw on an unexpected abort). */
     resolveFreezeAnswer(outcome, key) {
         if (outcome.kind !== "wake") {
@@ -204,64 +213,40 @@ export class WorkerWorkflowHost {
     }
     setPhase(name, opts) {
         throwIfAborted(this.deps.signal);
-        // Suppressed during replay: the marker was already emitted in the prior segment.
-        if (this.seq.isReplaying())
-            return;
         this.deps.phases?.set(name, opts);
     }
     agent(prompt, opts) {
         return this.guarded(() => this.agentSeam(prompt, opts));
     }
-    /** 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). */
     async agentSeam(prompt, opts) {
+        // One suspension key for the whole leaf: every gate this leaf raises registers under it, and
+        // a wake joins ALL of its answered rows, so answers accumulate server-side across parks.
         const seq = this.seq.next();
-        const fingerprint = seamFingerprint([
-            "agent",
-            opts?.provider ?? null,
-            opts?.model ?? null,
-            prompt,
-            opts?.schema ?? null,
-        ]);
-        let resume;
-        if (this.deps.journal !== undefined) {
-            const existing = await this.deps.journal.get(seq);
-            if (existing !== null) {
-                if (existing.fingerprint !== fingerprint)
-                    throw determinismError(seq, "agent", existing.kind);
-                if (existing.state === "resolved")
-                    return existing.result;
-                // A `suspended` entry is a parked leaf (tool-level human_input): re-enter it from the stored
-                // checkpoint + the answers the broker joined in.
-                resume = leafResumeSchema.parse(existing.result);
-            }
-        }
         // Bind a computer-use session's tools (browser tier ⇒ its in-VM Playwright MCP) if one was passed.
-        // Done AFTER the fingerprint so the injected MCP never perturbs determinism (the fingerprint keys
-        // on provider/model/prompt/schema only — an mcp/session change must not invalidate a journal hit).
         const effectiveOpts = this.bindBrowserSession(opts);
+        // Held-path answers accumulate locally too: a turn with several human_input calls parks once
+        // per unanswered gate, and each re-entry must still see every earlier answer.
+        const heldAnswers = {};
+        let resume;
         for (;;) {
             try {
-                const result = await this.deps.leaf.run(prompt, effectiveOpts, this.deps.signal, resume);
-                await this.deps.journal?.put({
-                    seq,
-                    kind: "agent",
-                    fingerprint,
-                    label: prompt.slice(0, 120),
-                    result,
-                });
-                return result;
+                return await this.deps.leaf.run(prompt, effectiveOpts, this.deps.signal, resume);
             }
             catch (err) {
                 if (!(err instanceof LeafParked))
                     throw err;
                 // The model paused for a person (the in-leaf `human_input` tool).
+                if (err.checkpoint === undefined) {
+                    throw new AppError(ErrorCode.INTERNAL_ERROR, "Parked agent leaf has no checkpoint to resume from", { kind: "leaf_parked_no_checkpoint", seq });
+                }
                 const signal = {
                     reason: "human_input",
                     seq,
-                    fingerprint,
-                    ...(err.checkpoint !== undefined ? { leafCheckpoint: err.checkpoint } : {}),
+                    leafCheckpoint: err.checkpoint,
                     humanInput: {
                         key: err.request.toolCallId,
                         prompt: err.request.prompt,
@@ -269,14 +254,15 @@ export class WorkerWorkflowHost {
                     },
                 };
                 const freeze = this.deps.freeze;
-                if (freeze === undefined)
-                    return this.suspend(signal);
-                // Snapshot substrate: freeze in place; the wake carries the answers and the leaf
-                // re-enters from its checkpoint — heap intact, no journal round-trip. A leaf may park
-                // again on a later turn, so this loops.
-                if (err.checkpoint === undefined) {
-                    throw new AppError(ErrorCode.INTERNAL_ERROR, "Parked agent leaf has no checkpoint to resume from", { kind: "leaf_parked_no_checkpoint", seq });
+                if (freeze === undefined) {
+                    // Hold path: register the gate and poll until answered; the transcript stays in memory.
+                    heldAnswers[err.request.toolCallId] = await this.holdForAnswer(seq, signal.humanInput);
+                    resume = { checkpoint: err.checkpoint, answers: { ...heldAnswers } };
+                    continue;
                 }
+                // Snapshot substrate: freeze in place; the wake carries the answers and the leaf
+                // re-enters from its checkpoint — heap intact. A leaf may park again on a later turn,
+                // so this loops.
                 const outcome = await this.freezeWait(freeze, signal);
                 if (outcome.kind !== "wake") {
                     throw new AppError(ErrorCode.INTERNAL_ERROR, "Suspend aborted surfaced to a human-input seam (the coordinator retries these)", { kind: "unexpected_abort", seq });
@@ -288,32 +274,19 @@ export class WorkerWorkflowHost {
             }
         }
     }
-    /** 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) {
         return this.guarded(() => this.humanInputSeam(opts));
     }
     async humanInputSeam(opts) {
         const seq = this.seq.next();
         const key = opts.key ?? `seam-${String(seq)}`;
-        const fingerprint = seamFingerprint(["human_input", key, opts.prompt, opts.input]);
-        if (this.deps.journal !== undefined) {
-            const existing = await this.deps.journal.get(seq);
-            if (existing !== null) {
-                if (existing.fingerprint !== fingerprint) {
-                    throw determinismError(seq, "human_input", existing.kind);
-                }
-                // A resolved entry is the human's validated response; a still-pending entry is a spurious
-                // wake without an answer, so fall through and re-suspend.
-                if (existing.state === "resolved")
-                    return normalizeHumanInputResult(existing.result);
-            }
-        }
         const expiresAt = this.timeoutExpiry(opts.timeout);
         const signal = {
             reason: "human_input",
             seq,
-            fingerprint,
             humanInput: {
                 key,
                 prompt: opts.prompt,
@@ -327,111 +300,51 @@ export class WorkerWorkflowHost {
         if (freeze !== undefined) {
             return await this.freezeHumanInput(freeze, signal, key);
         }
-        return this.suspend(signal);
+        // Hold path: register the gate and poll until a person answers.
+        return normalizeHumanInputResult(await this.holdForAnswer(seq, signal.humanInput));
     }
     /** Absolute wake time for a `humanInput({ timeout })`, or null when there is none / it's unparseable. */
     timeoutExpiry(timeout) {
         const ms = parseTimeoutMs(timeout);
         return ms === null ? null : this.now() + ms;
     }
-    /** `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, fn) {
-        return this.guarded(() => this.stepSeam(name, fn));
-    }
-    async stepSeam(name, fn) {
-        const seq = this.seq.next();
-        const fingerprint = seamFingerprint(["step", name]);
-        if (this.deps.journal !== undefined) {
-            const existing = await this.deps.journal.get(seq);
-            if (existing !== null) {
-                if (existing.fingerprint !== fingerprint)
-                    throw determinismError(seq, "step", existing.kind);
-                if (existing.state === "resolved")
-                    return existing.result;
-            }
-        }
-        const result = await fn();
-        await this.deps.journal?.put({ seq, kind: "step", fingerprint, label: name, result });
-        return result;
-    }
     callWorkflow(slug, input, opts) {
         return this.guarded(() => this.callWorkflowSeam(slug, input, opts));
     }
-    /** 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. */
     async callWorkflowSeam(slug, input, opts) {
-        if (this.deps.journal === undefined) {
+        const freeze = this.deps.freeze;
+        if (freeze === undefined) {
+            // Hold path: the dispatcher's in-process hold-and-poll until the child is terminal.
             return this.deps.children.call(slug, input, opts, this.deps.signal);
         }
-        const seq = this.seq.next();
-        const fingerprint = seamFingerprint([
-            "workflow_call",
-            slug,
-            input ?? null,
-            opts?.idempotencyKey ?? null,
-        ]);
-        let knownChildId;
-        const existing = await this.deps.journal.get(seq);
-        if (existing !== null) {
-            if (existing.fingerprint !== fingerprint) {
-                throw determinismError(seq, "workflow_call", existing.kind);
-            }
-            if (existing.state === "resolved")
-                return existing.result;
-            // A pending entry holds the child run id we suspended waiting on (resume polls it).
-            knownChildId = childRunIdSchema.parse(existing.result);
-        }
-        // First execution starts (idempotently) the child; a resume polls the journaled one.
-        const child = knownChildId === undefined
-            ? await this.deps.children.start(slug, input, opts, this.deps.signal)
-            : await this.deps.children.poll(knownChildId);
-        if (child === null) {
-            throw new AppError(ErrorCode.INTERNAL_ERROR, `Called workflow's child run vanished`, {
-                slug,
-                childRunId: knownChildId,
-            });
-        }
-        if (child.status === "completed") {
-            await this.deps.journal.put({
-                seq,
-                kind: "workflow_call",
-                fingerprint,
-                label: slug,
-                result: child.output,
-            });
+        const child = await this.deps.children.start(slug, input, opts, this.deps.signal);
+        if (child.status === "completed")
             return child.output;
-        }
         if (child.status === "failed" || child.status === "cancelled") {
             throw new AppError(ErrorCode.VALIDATION_FAILED, `Called workflow "${slug}" ${child.status} (run ${child.childRunId})`, { childRunId: child.childRunId, status: child.status });
         }
-        // Still running → suspend; the child's finalize wakes us.
-        const signal = {
+        // Still running → park in place; the wake carries the finalized child directly (the heap
+        // holds this whole frame across the freeze).
+        const seq = this.seq.next();
+        const outcome = await this.freezeWait(freeze, {
             reason: "workflow_call",
             seq,
-            fingerprint,
             childRunId: child.childRunId,
-        };
-        const freeze = this.deps.freeze;
-        if (freeze !== undefined) {
-            // Snapshot substrate: park in place; the wake carries the finalized child directly (no
-            // journal write for the wake-derived value — the heap holds it and nothing replays).
-            const outcome = await this.freezeWait(freeze, signal);
-            if (outcome.kind !== "wake") {
-                throw new AppError(ErrorCode.INTERNAL_ERROR, "Suspend aborted surfaced to a child-wait seam (the coordinator retries these)", { kind: "unexpected_abort", seq });
-            }
-            const woken = outcome.wake.child;
-            if (outcome.wake.kind !== "workflow_call" || woken === undefined) {
-                throw new AppError(ErrorCode.INTERNAL_ERROR, `Wake value does not carry the awaited child run (got kind "${outcome.wake.kind}")`, { kind: "wake_mismatch", childRunId: child.childRunId });
-            }
-            if (woken.status === "completed")
-                return woken.output;
-            throw new AppError(ErrorCode.VALIDATION_FAILED, `Called workflow "${slug}" ${woken.status} (run ${woken.run_id})`, { childRunId: woken.run_id, status: woken.status });
+        });
+        if (outcome.kind !== "wake") {
+            throw new AppError(ErrorCode.INTERNAL_ERROR, "Suspend aborted surfaced to a child-wait seam (the coordinator retries these)", { kind: "unexpected_abort", seq });
+        }
+        const woken = outcome.wake.child;
+        if (outcome.wake.kind !== "workflow_call" || woken === undefined) {
+            throw new AppError(ErrorCode.INTERNAL_ERROR, `Wake value does not carry the awaited child run (got kind "${outcome.wake.kind}")`, { kind: "wake_mismatch", childRunId: child.childRunId });
         }
-        return this.suspend(signal);
+        if (woken.status === "completed")
+            return woken.output;
+        throw new AppError(ErrorCode.VALIDATION_FAILED, `Called workflow "${slug}" ${woken.status} (run ${woken.run_id})`, { childRunId: woken.run_id, status: woken.status });
     }
     /** Fire-and-forget trigger of another workflow; resolves to the new run's id (no hold/poll). */
     runWorkflow(slug, input, opts) {
@@ -465,7 +378,7 @@ export class WorkerWorkflowHost {
     }
     /** `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) {
         return this.guarded(async () => {
             if (this.deps.browserSessions === undefined) {
@@ -492,42 +405,26 @@ export class WorkerWorkflowHost {
     sleep(arg) {
         return this.guarded(() => this.sleepSeam(arg));
     }
-    /** 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). */
     async sleepSeam(arg) {
         const ms = this.resolveSleepMs(arg);
         if (ms > this.maxSleepMs) {
             throw new AppError(ErrorCode.VALIDATION_FAILED, `Sleep exceeds the ${String(this.maxSleepMs)}ms (7-day) maximum`, { kind: "sleep_cap" });
         }
-        const seq = this.seq.next();
-        const fingerprint = seamFingerprint(["sleep"]);
-        if (this.deps.journal !== undefined) {
-            const existing = await this.deps.journal.get(seq);
-            if (existing !== null) {
-                if (existing.fingerprint !== fingerprint)
-                    throw determinismError(seq, "sleep", existing.kind);
-                // A journaled sleep already elapsed in a prior segment — a resumed run only progresses past a
-                // sleep once it is due, so on replay this returns immediately.
-                return;
-            }
-        }
         // A non-positive duration (incl. an `until` already in the past) is a no-op hold, not an error.
         const holdMs = Math.max(0, ms);
         if (holdMs === 0)
             return;
         const freeze = this.deps.freeze;
         if (holdMs >= SUSPEND_THRESHOLD_MS && freeze !== undefined) {
-            // Snapshot substrate: freeze in place; the wake (when the sleep is due) resolves this very
-            // await, heap intact. An abort falls back to holding the REMAINDER in-process — the
-            // two-ways rule: snapshot or hold, never replay.
+            // Snapshot substrate: freeze in place. An abort falls back to holding the REMAINDER
+            // in-process.
             const requestedAt = this.now();
-            const outcome = await this.freezeWait(freeze, {
-                reason: "sleep",
-                seq,
-                fingerprint,
-                durationMs: holdMs,
-            });
+            const seq = this.seq.next();
+            const outcome = await this.freezeWait(freeze, { reason: "sleep", seq, durationMs: holdMs });
             if (outcome.kind === "wake")
                 return;
             const remaining = holdMs - (this.now() - requestedAt);
@@ -538,14 +435,7 @@ export class WorkerWorkflowHost {
             await this.sleeper.hold(remaining, this.deps.signal);
             return;
         }
-        // Long wait (transitional substrate): SUSPEND (release the task). The broker records the
-        // (resolved) sleep journal entry + the wake time transactionally, so on wake this seam replays
-        // past it (the journal hit above). Only when a journal is wired — without it there is no
-        // resume, so fall back to holding.
-        if (holdMs >= SUSPEND_THRESHOLD_MS && this.deps.journal !== undefined) {
-            return this.suspend({ reason: "sleep", seq, fingerprint, durationMs: holdMs });
-        }
-        // Short wait: HOLD the process (no journal — a crash-restart simply re-holds). Snapshot the
+        // Hold: the process sleeps in place (a crash-restart simply re-holds). Snapshot the
         // persistent workspace first so a crash during the hold can restore it. An abort mid-hold rejects.
         if (this.deps.onBeforeSleep !== undefined)
             await this.deps.onBeforeSleep();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boardwalk-labs/runner",
-  "version": "0.1.21",
+  "version": "0.2.0",
   "description": "Boardwalk self-hosted runner: execute cloud-scheduled runs on your own machines. Currently: the canonical runner contract types.",
   "license": "Apache-2.0",
   "repository": {
@@ -53,8 +53,8 @@
     "prebuild": "prebuildify --napi --strip -t 24.0.0"
   },
   "dependencies": {
-    "@boardwalk-labs/engine": "^0.1.35",
-    "@boardwalk-labs/workflow": "^0.1.29",
+    "@boardwalk-labs/engine": "^0.2.0",
+    "@boardwalk-labs/workflow": "^0.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "node-gyp-build": "^4.8.4",
     "tar": "^7.5.16",