@boardwalk-labs/runner 0.2.17 → 0.3.0

package/dist/runtime/workflow_host.d.ts

@@ -1,4 +1,5 @@
-import type { WorkflowHost, AgentOptions, ArtifactBody, ArtifactRef, BrowserSession, BrowserSessionOptions, CallOptions, HumanInputOptions, HumanInputResult, PhaseOptions, SleepArg } from "@boardwalk-labs/workflow/runtime";
+import type { AgentOptions, ArtifactBody, ArtifactRef, BrowserSession, BrowserSessionOptions, CallOptions, HumanInputOptions, HumanInputResult, PhaseOptions, ShellResult, SleepArg, UsageSnapshot } from "@boardwalk-labs/workflow/runtime";
+import type { ShellOptions } from "@boardwalk-labs/workflow";
 import type { BrowserSessionManager } from "./browser_session.js";
 import { type LeafResume } from "@boardwalk-labs/engine/core";
 import { type SuspendSignal } from "./suspension.js";
@@ -30,11 +31,19 @@ export interface ScheduleOptions {
     timezone?: string;
     idempotencyKey?: string;
 }
-/** A child run's terminal-relevant state, as the start/poll seams return it. */
+/** A child run's terminal-relevant state, as the start/poll seams return it. `outputSchema` is
+ *  the callee's PINNED version's stored `output_schema` (what lets the SDK revive a typed child's
+ *  return); null = untyped callee or a payload that predates the field. */
 export interface ChildResult {
     childRunId: string;
     status: string;
     output: unknown;
+    outputSchema: Record<string, unknown> | null;
+}
+/** What `workflows.call` resolves: the completed child's output + the callee's output schema. */
+export interface ChildCallOutput {
+    output: unknown;
+    outputSchema: Record<string, unknown> | null;
 }
 /** 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
@@ -42,7 +51,11 @@ export interface ChildResult {
  *  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>;
+    call(slug: string, input: unknown, opts: CallOptions | undefined, signal?: AbortSignal): Promise<ChildCallOutput>;
+    /** Poll a child run's current state (used by the freeze-wake path to fetch the callee's
+     *  output schema — the wake payload carries the output but not the schema); null = not this
+     *  run's child. */
+    poll(childRunId: string): Promise<ChildResult | null>;
     /** 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>;
     run(slug: string, input: unknown, opts: CallOptions | undefined): Promise<string>;
@@ -145,8 +158,26 @@ export interface WorkerWorkflowHostDeps {
     heldInput?: HeldInputPort;
     /** Poll interval for a held gate's answer (default 3s). */
     heldPollIntervalMs?: number;
+    /** Backs the protocol's `shell` capability (shell_exec's runShell in production). Absent ⇒
+     *  `shell()` is unsupported in this runtime and rejects clearly. */
+    shell?: (cmd: string, opts: ShellOptions | undefined) => Promise<ShellResult>;
+    /** Live budget state for `usage.get` (the BudgetMeter's usageSnapshot in production). Absent ⇒
+     *  `usage.get()` is unsupported in this runtime and rejects clearly. */
+    usage?: () => UsageSnapshot;
+    /**
+     * Budget clearance (docs/SUSPEND_POLICY.md Decision 3), awaited at the host's blocking/spending
+     * capability seams — `sleep`, `shell`, `workflows.call` — in addition to the leaf executor's
+     * `streamModel` seam. `usd`/`tokens` only move at model calls, but `max_compute_seconds` burns
+     * continuously, so a breach between model calls parks at whichever capability the program touches
+     * next (the park-at-next-seam contract; see budget_gate.ts). Runs INSIDE `guarded()` so the park's
+     * `budgetClearance` work-accounting (endWork around the freeze wait) balances, exactly like the
+     * leaf seam. Absent ⇒ no host-seam parks (tests / legacy paths).
+     */
+    budgetGate?: {
+        clear(): Promise<void>;
+    };
 }
-export declare class WorkerWorkflowHost implements WorkflowHost {
+export declare class WorkerWorkflowHost {
     private readonly deps;
     private readonly sleeper;
     private readonly now;
@@ -207,10 +238,16 @@ export declare class WorkerWorkflowHost implements WorkflowHost {
      *  host always implements it. */
     humanInput(opts: HumanInputOptions): Promise<HumanInputResult>;
     private humanInputSeam;
+    /** Wait a registered gate out on whichever substrate the run has: freeze in place on the
+     *  snapshot fleet, or (self-hosted runner / local dev) hold the live process and poll until a
+     *  person answers. The one place the freeze-vs-hold decision for a gate is made. */
+    private awaitGate;
     /**
      * 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
+     * Decision 3). Called when any budget cap (`max_usd` / `max_tokens` / `max_compute_seconds`) is
+     * breached — by the leaf executor's `streamModel` seam (from INSIDE an in-flight `agent()`) and by
+     * the host's own `sleep`/`shell`/`workflows.call` seams (from inside their `guarded()` bodies).
+     * Either way the caller is already work-tracked, which drives two deliberate differences from
      * {@link humanInputSeam}:
      *
      *  - **No `guarded()` wrapper.** The enclosing `agent()` seam already counted this leaf as work via
@@ -232,7 +269,7 @@ export declare class WorkerWorkflowHost implements WorkflowHost {
     }): Promise<HumanInputResult>;
     /** Absolute wake time for a `humanInput({ timeout })`, or null when there is none / it's unparseable. */
     private timeoutExpiry;
-    callWorkflow(slug: string, input: unknown, opts: CallOptions | undefined): Promise<unknown>;
+    callWorkflow(slug: string, input: unknown, opts: CallOptions | undefined): Promise<ChildCallOutput>;
     /** 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
@@ -260,6 +297,15 @@ export declare class WorkerWorkflowHost implements WorkflowHost {
      *  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;
+    /** The protocol's `shell` capability. Runs under the same abort/freeze gate as every hook, so
+     *  a freeze never snapshots around an unguarded seam and an aborted run rejects promptly. */
+    shell(cmd: string, opts: ShellOptions | undefined): Promise<ShellResult>;
+    /** Live budget state for `usage.get` — every dimension `{spent, cap, remaining}`. */
+    usage(): Promise<UsageSnapshot>;
+    /** `auth.idToken(audience)` — minted per call by the broker via {@link RuntimeContext}. */
+    idToken(audience: string): Promise<string>;
+    /** `auth.apiToken()` — the run's short-lived, manifest-scoped public-API bearer. */
+    apiToken(): Promise<string>;
     /** Resolve any {@link SleepArg} shape to a millisecond duration from now. */
     private resolveSleepMs;
 }

package/dist/runtime/workflow_host.js

@@ -1,5 +1,5 @@
-// WorkerWorkflowHost — the real WorkflowHost the worker installs onto @boardwalk-labs/workflow
-// before running a program (the workflow runtime design). The program's hooks delegate here:
+// WorkerWorkflowHost — the runner's capability layer behind the host protocol (the
+// workflow-format redesign). The protocol server's `HostCapabilities` seam delegates here:
 //
 //   agent(prompt, opts)        → an ephemeral agent leaf (the demoted agent loop)
 //   sleep(arg)                 → an IN-PROCESS hold (hold-and-pay; no checkpoint, no exit)
@@ -281,11 +281,11 @@ export class WorkerWorkflowHost {
     humanInput(opts) {
         return this.guarded(() => this.humanInputSeam(opts));
     }
-    async humanInputSeam(opts) {
+    humanInputSeam(opts) {
         const seq = this.seq.next();
         const key = opts.key ?? `seam-${String(seq)}`;
         const expiresAt = this.timeoutExpiry(opts.timeout);
-        const signal = {
+        return this.awaitGate({
             reason: "human_input",
             seq,
             humanInput: {
@@ -296,18 +296,24 @@ export class WorkerWorkflowHost {
                 // A timeout only matters with a wake to fire at; carry onTimeout alongside expiresAt.
                 ...(expiresAt !== null ? { expiresAt, onTimeout: opts.onTimeout ?? "fail" } : {}),
             },
-        };
+        });
+    }
+    /** Wait a registered gate out on whichever substrate the run has: freeze in place on the
+     *  snapshot fleet, or (self-hosted runner / local dev) hold the live process and poll until a
+     *  person answers. The one place the freeze-vs-hold decision for a gate is made. */
+    async awaitGate(signal) {
         const freeze = this.deps.freeze;
         if (freeze !== undefined) {
-            return await this.freezeHumanInput(freeze, signal, key);
+            return await this.freezeHumanInput(freeze, signal, signal.humanInput.key);
         }
-        // Hold path: register the gate and poll until a person answers.
-        return normalizeHumanInputResult(await this.holdForAnswer(seq, signal.humanInput));
+        return normalizeHumanInputResult(await this.holdForAnswer(signal.seq, signal.humanInput));
     }
     /**
      * 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
+     * Decision 3). Called when any budget cap (`max_usd` / `max_tokens` / `max_compute_seconds`) is
+     * breached — by the leaf executor's `streamModel` seam (from INSIDE an in-flight `agent()`) and by
+     * the host's own `sleep`/`shell`/`workflows.call` seams (from inside their `guarded()` bodies).
+     * Either way the caller is already work-tracked, which drives two deliberate differences from
      * {@link humanInputSeam}:
      *
      *  - **No `guarded()` wrapper.** The enclosing `agent()` seam already counted this leaf as work via
@@ -323,20 +329,12 @@ export class WorkerWorkflowHost {
      * 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.
      */
-    async budgetClearance(gate) {
-        const seq = this.seq.next();
-        const key = BUDGET_GATE_KEY;
-        const signal = {
+    budgetClearance(gate) {
+        return this.awaitGate({
             reason: "budget",
-            seq,
-            humanInput: { key, prompt: gate.prompt, inputSpec: gate.inputSpec },
-        };
-        const freeze = this.deps.freeze;
-        if (freeze !== undefined) {
-            return await this.freezeHumanInput(freeze, signal, key);
-        }
-        // No freeze substrate (self-hosted runner / local dev): hold the live process until answered.
-        return normalizeHumanInputResult(await this.holdForAnswer(seq, signal.humanInput));
+            seq: this.seq.next(),
+            humanInput: { key: BUDGET_GATE_KEY, prompt: gate.prompt, inputSpec: gate.inputSpec },
+        });
     }
     /** Absolute wake time for a `humanInput({ timeout })`, or null when there is none / it's unparseable. */
     timeoutExpiry(timeout) {
@@ -344,7 +342,12 @@ export class WorkerWorkflowHost {
         return ms === null ? null : this.now() + ms;
     }
     callWorkflow(slug, input, opts) {
-        return this.guarded(() => this.callWorkflowSeam(slug, input, opts));
+        return this.guarded(async () => {
+            // Park BEFORE dispatching the child: a budget-breached parent doesn't get to spawn more
+            // (org-billed) work until a responder clears the breach.
+            await this.deps.budgetGate?.clear();
+            return this.callWorkflowSeam(slug, input, opts);
+        });
     }
     /** 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
@@ -358,7 +361,7 @@ export class WorkerWorkflowHost {
         }
         const child = await this.deps.children.start(slug, input, opts, this.deps.signal);
         if (child.status === "completed")
-            return child.output;
+            return { output: child.output, outputSchema: child.outputSchema };
         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 });
         }
@@ -377,38 +380,39 @@ export class WorkerWorkflowHost {
         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;
+        if (woken.status === "completed") {
+            // The wake payload carries the finalized child's OUTPUT but not the callee's schema; one
+            // post-wake poll fetches it so a typed child's return still revives. Best-effort: a poll
+            // failure degrades to plain JSON (null schema), never fails the parent.
+            let outputSchema = null;
+            try {
+                outputSchema = (await this.deps.children.poll(woken.run_id))?.outputSchema ?? null;
+            }
+            catch {
+                outputSchema = null;
+            }
+            return { output: woken.output, outputSchema };
+        }
         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) {
-        return this.guarded(async () => {
-            const id = await this.deps.children.run(slug, input, opts);
-            return id;
-        });
+        return this.guarded(() => this.deps.children.run(slug, input, opts));
     }
     /** Provision a durable schedule (one-shot/recurring) that fires the target later; resolves to the
      *  new schedule's id WITHOUT running it now. Satisfies the SDK's optional `scheduleWorkflow`. */
     scheduleWorkflow(slug, input, opts) {
-        return this.guarded(async () => {
-            const id = await this.deps.children.schedule(slug, input, opts);
-            return id;
-        });
+        return this.guarded(() => this.deps.children.schedule(slug, input, opts));
     }
     getSecret(name) {
-        return this.guarded(async () => {
-            const value = await this.deps.secrets.get(name);
-            return value;
-        });
+        return this.guarded(() => this.deps.secrets.get(name));
     }
     writeArtifact(name, contentType, body, metadata) {
         return this.guarded(async () => {
             if (this.deps.writeArtifact === undefined) {
                 throw new AppError(ErrorCode.VALIDATION_FAILED, "artifacts.write is not available in this runtime");
             }
-            const ref = await this.deps.writeArtifact(name, contentType, body, metadata);
-            return ref;
+            return await this.deps.writeArtifact(name, contentType, body, metadata);
         });
     }
     /** `computer.openBrowser()`: open a program-owned, in-VM browser session (the browser tier of
@@ -438,7 +442,12 @@ export class WorkerWorkflowHost {
         return { ...rest, mcp: [...(rest.mcp ?? []), ref] };
     }
     sleep(arg) {
-        return this.guarded(() => this.sleepSeam(arg));
+        return this.guarded(async () => {
+            // A compute-breached run parks HERE rather than sleeping first and parking later — no forward
+            // progress while a budget cap is breached (the budget-gate park-at-next-seam contract).
+            await this.deps.budgetGate?.clear();
+            return this.sleepSeam(arg);
+        });
     }
     /** 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
@@ -476,6 +485,37 @@ export class WorkerWorkflowHost {
             await this.deps.onBeforeSleep();
         await this.sleeper.hold(holdMs, this.deps.signal);
     }
+    /** The protocol's `shell` capability. Runs under the same abort/freeze gate as every hook, so
+     *  a freeze never snapshots around an unguarded seam and an aborted run rejects promptly. */
+    shell(cmd, opts) {
+        return this.guarded(async () => {
+            if (this.deps.shell === undefined) {
+                throw new AppError(ErrorCode.VALIDATION_FAILED, "shell is not available in this runtime");
+            }
+            // Compute burns hardest in long shell commands — a breach parks before starting another one.
+            await this.deps.budgetGate?.clear();
+            return await this.deps.shell(cmd, opts);
+        });
+    }
+    /** Live budget state for `usage.get` — every dimension `{spent, cap, remaining}`. */
+    usage() {
+        return this.guarded(async () => {
+            if (this.deps.usage === undefined) {
+                throw new AppError(ErrorCode.VALIDATION_FAILED, "usage.get is not available in this runtime");
+            }
+            // Promise.resolve keeps the arrow's async-without-await acceptable to require-await; the
+            // arrow stays async so the guard above REJECTS (guarded's contract) rather than throwing.
+            return Promise.resolve(this.deps.usage());
+        });
+    }
+    /** `auth.idToken(audience)` — minted per call by the broker via {@link RuntimeContext}. */
+    idToken(audience) {
+        return this.guarded(() => this.deps.runtime.idToken(audience));
+    }
+    /** `auth.apiToken()` — the run's short-lived, manifest-scoped public-API bearer. */
+    apiToken() {
+        return this.guarded(() => this.deps.runtime.apiToken());
+    }
     /** Resolve any {@link SleepArg} shape to a millisecond duration from now. */
     resolveSleepMs(arg) {
         if (typeof arg === "number")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boardwalk-labs/runner",
-  "version": "0.2.17",
+  "version": "0.3.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,9 +53,10 @@
     "prebuild": "prebuildify --napi --strip -t 24.0.0"
   },
   "dependencies": {
-    "@boardwalk-labs/engine": "0.2.12",
-    "@boardwalk-labs/workflow": "0.2.6",
+    "@boardwalk-labs/engine": "0.3.0",
+    "@boardwalk-labs/workflow": "0.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "ajv": "^8.20.0",
     "node-gyp-build": "^4.8.4",
     "tar": "^7.5.16",
     "undici": "^6.27.0",