@boardwalk-labs/runner 0.2.17 → 0.3.0-alpha.1

package/dist/runtime/index.js

@@ -34,13 +34,15 @@ import { BUDGET_GUARDRAIL_RATE } from "./agent/model_rates.js";
 import { SecretRedactor } from "./agent/secret_redactor.js";
 import { RecordingSecretResolver } from "./recording_secret_resolver.js";
 import { EngineLeafExecutor } from "./leaf_executor.js";
-import { BudgetGate } from "./budget_gate.js";
+import { BudgetGate, ComputeBreachWatcher } from "./budget_gate.js";
 import { parseByoProviders } from "./direct_inference.js";
 import { applyIdentityToEnv, connectIdentityRelayFd, relayFdFromEnv, workerDiagnostics, } from "./identity_relay.js";
 import { FreezeCoordinator } from "./freeze_coordinator.js";
 import { reseedUserspaceCsprng } from "./uniqueness_reseed.js";
 import { resetHttpConnectionPool } from "./http_pool_reset.js";
 import { WorkerWorkflowHost } from "./workflow_host.js";
+import { buildHostCapabilities } from "./host_capabilities.js";
+import { runShell } from "./shell_exec.js";
 import { BrowserSessionManager } from "./browser_session.js";
 import { loadGuestBrowserConfig, makeGuestBrowserBackend, connectSessionMcp, } from "./browser_session_backend.js";
 import { ScreenCapture } from "./screen_capture.js";
@@ -165,10 +167,6 @@ export function assembleWorkerDeps(runtime) {
             // the bill — the platform meters the actual per-leaf usage.
             rate: BUDGET_GUARDRAIL_RATE,
             startedAt: Date.now(),
-            // deadline_seconds is WALL-CLOCK from the run's ORIGINAL start (incl. suspended idle), so a run
-            // resumed past its deadline trips on its first cap check. Falls back to now on the first session
-            // (startedAt is being set this session anyway).
-            deadlineStartedAt: run.startedAt ?? Date.now(),
         });
         // Per-session id for per-turn metering identifiers (`<runId>:<sessionId>:<leafIndex>:<turnSeq>`) —
         // a fresh value per worker session keeps a resumed run's events from colliding with a prior
@@ -239,10 +237,11 @@ export function assembleWorkerDeps(runtime) {
         // it). Workspace-rooted at the same `/workspace` the leaf + tools use. Closed on the run's teardown
         // (returned below as `lsp` → program_worker's finally) so no language-server process leaks.
         const lspService = new LspService({ workspaceDir: runtime.workspaceRoot });
-        // Budget gate (docs/SUSPEND_POLICY.md Decision 3): a `max_usd` breach PARKS the run for approval
-        // instead of failing it. The gate needs the HOST (to park) but the host is constructed below with
-        // `leaf` — a genuine cycle, broken with a late-bound ref: `clear()` only ever runs mid-run, long
-        // after both exist. Wired to `budgetHost` immediately after the host is built.
+        // Budget gate (docs/SUSPEND_POLICY.md Decision 3): a breach of ANY budget cap (`max_usd` /
+        // `max_tokens` / `max_compute_seconds`) PARKS the run for approval instead of failing it. The
+        // gate needs the HOST (to park) but the host is constructed below with `leaf` — a genuine
+        // cycle, broken with a late-bound ref: `clear()` only ever runs mid-run, long after both exist.
+        // Wired to `budgetHost` immediately after the host is built.
         let budgetHost = null;
         const budgetGate = new BudgetGate(budget, {
             budgetClearance: (gate) => {
@@ -253,6 +252,13 @@ export function assembleWorkerDeps(runtime) {
                 return budgetHost.budgetClearance(gate);
             },
         });
+        // Compute burns continuously (unlike usd/tokens, which only move at model calls), so a
+        // `max_compute_seconds` breach between seams is DETECTED on this timer and logged; the park
+        // itself lands at the run's next capability seam (see the watcher's doc block for why a
+        // timer-initiated park needs fleet-host coordination that doesn't exist yet). Stopped by the
+        // orchestrator on every terminal path via the returned `budgetWatch` handle.
+        const computeWatch = new ComputeBreachWatcher(budget, { runId: run.id });
+        computeWatch.start();
         const leaf = new EngineLeafExecutor({
             inference: broker,
             // Direct BYO (D7): the claim's registry + the run's RECORDING resolver, so a provider key
@@ -404,9 +410,20 @@ export function assembleWorkerDeps(runtime) {
             // (absent ⇒ the host throws "not available on this runner image").
             ...(browserSessions !== undefined ? { browserSessions } : {}),
             phases: phaseTracker,
+            // The protocol's `shell` capability: host-side execution in the run's workspace (the old
+            // in-process execSync moved behind the wire with the redesign).
+            shell: (cmd, opts) => runShell(cmd, opts, { workspaceRoot: runtime.workspaceRoot, signal }),
+            // Live budget state for `usage.get` — read off the run-level meter (run-cumulative).
+            usage: () => budget.usageSnapshot(),
+            // Budget clearance at the host's blocking/spending seams (sleep/shell/workflows.call): the
+            // park points for a compute breach that lands between model calls.
+            budgetGate,
         });
         // Close the budget gate's cycle: the leaf (built above) parks THROUGH the host (built just now).
         budgetHost = host;
+        // The protocol server's dispatch seam — a thin adapter over the host (workflows.call gains
+        // its output_schema slot, null until the broker delivers the callee's schema).
+        const capabilities = buildHostCapabilities(host);
         // Late-bind the coordinator's per-run hooks now that the run-scoped objects exist.
         if (freeze !== undefined) {
             const coordinator = freeze;
@@ -452,6 +469,11 @@ export function assembleWorkerDeps(runtime) {
                         redactor.record(wake.api_token);
                     }
                     activeFlusher?.excludeIdle(wake.wall_clock_ms - freezeWallMs);
+                    // The budget meter excludes the same frozen window: `max_compute_seconds` is ACTIVE
+                    // on-CPU compute by definition (it "EXCLUDES sleep/wait" — the manifest schema's own
+                    // words), so a sleep/humanInput/child-wait freeze must not count toward the cap any
+                    // more than it counts toward billing.
+                    budget.excludeIdle(wake.wall_clock_ms - freezeWallMs);
                     // Only now that the frozen window is excluded may the flush timer run again.
                     activeFlusher?.resume();
                     // Resume capture in a fresh segment epoch (a suspend/resume boundary is a segment boundary).
@@ -462,7 +484,7 @@ export function assembleWorkerDeps(runtime) {
         // Hand the redactor back too: the worker scrubs a terminal error's message with it;
         // workspace (when opted in) hydrates at start + persists at terminal.
         return Promise.resolve({
-            host,
+            capabilities,
             redactor,
             phases: phaseTracker,
             // The orchestrator closes the per-run LSP on every terminal path (close() is idempotent + never
@@ -479,6 +501,9 @@ export function assembleWorkerDeps(runtime) {
             setProgramDir: (dir) => {
                 programDir = dir;
             },
+            // The orchestrator stops the compute-breach watcher on every terminal path (the interval is
+            // unref'd, so this is hygiene, not liveness).
+            budgetWatch: { stop: () => computeWatch.stop() },
             // Always present now: hydrate must run BEFORE the program, but whether anything compounds
             // isn't known until the run's agent() calls have registered their memory dirs. A run that
             // selects nothing persists nothing and pays for nothing (WorkspaceStore.persist returns early).
@@ -508,7 +533,15 @@ export function assembleWorkerDeps(runtime) {
                 // lifecycle transition the claim IS — the wire's `running` frame.
                 runEvents.resumeAfter(claimed.lastEventCursor);
                 runEvents.emit({ kind: "run_status", status: "running" });
-                return claimed.run;
+                return {
+                    run: claimed.run,
+                    context: {
+                        ...(claimed.workflowVersion !== undefined
+                            ? { workflowVersion: claimed.workflowVersion }
+                            : {}),
+                        ...(claimed.environment !== undefined ? { environment: claimed.environment } : {}),
+                    },
+                };
             },
         },
         versions: {
@@ -528,7 +561,7 @@ export function assembleWorkerDeps(runtime) {
         // Extract the verified artifact tarball via system `tar` (same impl as workspace snapshots).
         extractArchive: (tgzPath, destDir) => new TarWorkspaceArchiver().extract(tgzPath, destDir),
         // Guarantee /workspace exists before the program runs (override-safe; the image also pre-creates
-        // it). Lets authors write to /workspace without a defensive mkdir — see WorkflowMeta.workspace.
+        // it). Lets authors write to /workspace without a defensive mkdir — see the descriptor's `workspace` field.
         ensureWorkspace: async () => {
             await mkdir(runtime.workspaceRoot, { recursive: true });
         },

package/dist/runtime/leaf_executor.d.ts

@@ -31,14 +31,17 @@ export interface EngineLeafExecutorDeps {
      *  breach so the loop terminates mid-flight (the budget authority). */
     budget: BudgetMeter;
     /**
-     * Budget clearance, awaited before EVERY model call (docs/SUSPEND_POLICY.md Decision 3). When the
-     * run's `max_usd` cap is breached this PARKS the run at a gate — the engine just sees a model call
-     * that took a long time, because the VM froze and resumed underneath it — and resolves once a
-     * responder raises the cap. Rejects with `BudgetGateCancelled` if they decline.
+     * Budget clearance, awaited before EVERY model call (docs/SUSPEND_POLICY.md Decision 3). When ANY
+     * of the run's budget caps (`max_usd` / `max_tokens` / `max_compute_seconds`) is breached this
+     * PARKS the run at a gate — the engine just sees a model call that took a long time, because the
+     * VM froze and resumed underneath it — and resolves once a responder raises the breached cap.
+     * Rejects with `BudgetGateCancelled` if they decline.
      *
      * Why here and not at the `reportUsage` breach check below: that callback is synchronous and fires
      * mid-turn, and per SUSPEND_POLICY Decision 1 a partial turn is never discarded. The model-call
      * boundary is the first safe place to park, which bounds overrun at one in-flight turn per leaf.
+     * (The workflow host adds further park points at its `sleep`/`shell`/`workflows.call` seams for
+     * the continuously-burning compute cap.)
      *
      * Absent ⇒ the legacy behavior: a breach fails the run at `reportUsage`.
      */

package/dist/runtime/leaf_executor.js

@@ -3,8 +3,8 @@
 // In the JS-body model the run is the workflow PROGRAM; the agent loop is no longer "the run" — it
 // is an ephemeral leaf the program invokes via `agent(prompt, opts)`. This is the LeafExecutor the
 // worker's WorkflowHost delegates `agent()` to. It runs ONE leaf to completion via the engine's
-// `runAgentLeaf` (`@boardwalk-labs/engine/core`) — the SAME loop `boardwalk dev` and the self-hosted
-// server run — supplying a broker-backed `LeafIo`: the model call routes through the Runner Control
+// `runAgentLeaf` (`@boardwalk-labs/engine/core`) — the SAME loop the self-hosted
+// server runs — supplying a broker-backed `LeafIo`: the model call routes through the Runner Control
 // API (the worker holds no model creds), events flow onto the run's v1 event stream, usage meters
 // per-leaf + per-model through the broker, and secrets are redacted out of all model-bound content.
 //
@@ -138,9 +138,14 @@ export class EngineLeafExecutor {
                 currentTurnId = turnId;
                 sink.emit(toRunEventBody(body, identity), turnId);
             },
-            // Usage flows to the budget authority after EVERY model call. Feed the run-level meter and, if
-            // a cap is now breached, THROW — the engine loop propagates it and the run fails BUDGET_EXCEEDED
-            // before another model call is dispatched. Also fire per-leaf, per-model metering to the broker.
+            // Usage flows to the budget authority after EVERY model call. Feed the run-level meter; what a
+            // breach then does depends on whether the budget gate is wired. With a gate (production): do
+            // NOT throw — the in-flight turn completes (its tools run; SUSPEND_POLICY Decision 1 never
+            // discards a partial turn) and the run PARKS at its next park point (the next `streamModel`
+            // clearance, or a host capability seam). Without a gate (legacy/test paths): THROW — the
+            // engine loop propagates it and the run fails BUDGET_EXCEEDED before another model call is
+            // dispatched. On the gate path the breach turn ALSO meters to the broker below — its tokens
+            // were genuinely spent and must be billed (the old always-throw path silently skipped that).
             reportUsage: (modelRefForUsage, usage) => {
                 const delta = toUsageDelta(usage);
                 // Cap on the turn's REAL upstream cost when the broker reported one (the result frame's
@@ -151,7 +156,7 @@ export class EngineLeafExecutor {
                 pendingCostMicros = null;
                 this.deps.budget.addUsage(delta, realCostUsd);
                 const breach = this.deps.budget.capBreachReason();
-                if (breach !== null) {
+                if (breach !== null && this.deps.budgetGate === undefined) {
                     throw new EngineError("BUDGET_EXCEEDED", `agent() leaf exceeded the run budget cap (${breach})`);
                 }
                 this.deps.meterUsage?.({

package/dist/runtime/program_runner.d.ts

@@ -1,14 +1,12 @@
-import type { WorkflowHost } from "@boardwalk-labs/workflow/runtime";
+import { type ContextData } from "@boardwalk-labs/workflow/runtime";
+import { type HostCapabilities } from "./host_server.js";
 /**
  * Link THIS runtime's `@boardwalk-labs/workflow` into the exec dir's `node_modules` so the program's
  * bare import resolves from ANY program root — this link, not an ancestor `node_modules`, is what
- * makes resolution work. (Worth stating plainly: a stale comment claiming the extraction dir had to
- * sit under `/app` so the import could walk up to `/app/node_modules` outlived this function by
- * several versions and sent a later reader chasing a dependency that no longer exists. The live
- * fleet has no `/app` at all and resolves fine.) A symlink — not a copy — is load-bearing: Node
- * resolves it to the REAL path, so the program gets the same module instance the host adapter was
- * installed on (the singleton contract). `junction` covers Windows without elevation; a failed link
- * is only logged, since a resolvable ancestor may still exist.
+ * makes resolution work. A symlink — not a copy — is load-bearing: Node resolves it to the REAL
+ * path, so the program gets the same module instance the loader's protocol client was installed
+ * on (the active-host singleton in the SDK's host_client). `junction` covers Windows without
+ * elevation; a failed link is only logged, since a resolvable ancestor may still exist.
  */
 export declare function ensureSdkLink(execDir: string): Promise<void>;
 /** Resolve the program's entry module inside the extraction dir, refusing any path that escapes it.
@@ -17,10 +15,18 @@ export declare function ensureSdkLink(execDir: string): Promise<void>;
  *  outside `dir` throws rather than importing code from elsewhere on the machine. */
 export declare function resolveEntryPath(dir: string, entry: string): string;
 /**
- * Enforce I2: the extracted program must not live inside the run's workspace. Incidental separation
- * is what broke before — the extraction root used to be `process.cwd()`, so it landed inside the
- * workspace on exactly the lanes whose cwd was already correct. Compares RESOLVED paths, and treats
- * "the workspace itself" as inside.
+ * Resolve a program entry by LANGUAGE, binding the ratified artifact layout: a TS/JS entry is a
+ * BUILT module at the artifact root (`index.mjs` — the CLI bundles, the api-server type-strips);
+ * a `.py` entry is a SOURCE path under `.bw-src/` (`main.py` ⇒ `<dir>/.bw-src/main.py` — Python
+ * has no bundle step, the shipped source is what runs). A leading `./` on the stored entry is
+ * tolerated (`join` collapses it). Both lanes keep the containment guard; for Python the guard's
+ * base is the `.bw-src` tree itself, so an escaping entry (`../evil.py`) is rejected even when
+ * it would still land inside the extract dir.
+ */
+export declare function resolveProgramEntryPath(dir: string, entry: string): string;
+/**
+ * Enforce I2: the extracted program must not live inside the run's workspace. Compares RESOLVED
+ * paths, and treats "the workspace itself" as inside.
  */
 export declare function assertProgramRootOutsideWorkspace(programRoot: string, workspaceRoot: string): void;
 export interface RunProgramArgs {
@@ -28,17 +34,24 @@ export interface RunProgramArgs {
     runId: string;
     /** The VERIFIED program artifact tarball (sha256 already checked against the pinned digest). */
     tarball: Uint8Array;
-    /** Entry module to import after extraction (a safe relative POSIX path, e.g. `index.mjs`). */
+    /** Entry module to import after extraction (a safe relative POSIX path). TS/JS: the BUILT
+     *  module at the artifact root (`index.mjs`). Python: the SOURCE path relative to the
+     *  artifact's `.bw-src/` tree (`main.py` ⇒ `.bw-src/main.py` on disk). */
     entry: string;
-    /** Trigger payload exposed to the program as `import { input } from "@boardwalk-labs/workflow"`. */
+    /** The run's RAW JSON input (trigger payload / inline input). The revival pass is CLIENT-side. */
     input: unknown;
-    /** Experiment config exposed as `import { config } from "@boardwalk-labs/workflow"` ({} for non-eval).
-     *  Arbitrary JSON from the run row; narrowed to the SDK's JsonValue at the installConfig boundary. */
-    config: Record<string, unknown>;
+    /** The stored derived input schema (`null` for an untyped workflow) — carried on `bootstrap`
+     *  so the SDK revives rich fields (`date-time` → `Date`, base64 → `Uint8Array`, …). */
+    inputSchema: Record<string, unknown> | null;
+    /** The stored derived output schema (`null` ⇒ the return persists unvalidated). */
+    outputSchema: Record<string, unknown> | null;
+    /** The context DATA for `bootstrap` (P3.3) — the client builds the live `Context` from it. */
+    context: ContextData;
 }
 export interface ProgramRunnerDeps {
-    /** The host adapter the program's hooks delegate to (agent leaf, sleep hold, child calls, secrets). */
-    host: WorkflowHost;
+    /** The capability seam the host server dispatches onto (agent leaf, sleep hold, child calls,
+     *  secrets, shell, usage, auth, browser, phase). */
+    capabilities: HostCapabilities;
     /**
      * The run's `/workspace` — the working directory AND `HOME` for author code (I1). Must already
      * exist (the orchestrator's `ensureWorkspace` guarantees it); a missing workspace fails the run
@@ -46,42 +59,49 @@ export interface ProgramRunnerDeps {
      */
     workspaceRoot: string;
     /**
-     * Root the program artifact extracts under. MUST be outside {@link workspaceRoot} (I2) — enforced,
-     * because a bundle inside the workspace is tarred into every pre-sleep snapshot and, since each
-     * run's dir name is unique, accumulates there forever.
+     * Root the program artifact extracts under. MUST be outside {@link workspaceRoot} (I2) —
+     * enforced, because a bundle inside the workspace is tarred into every pre-sleep snapshot.
      */
     programRoot: string;
     /**
      * Extract a gzipped tar file into a directory (created already). System `tar` in production
-     * (matches WorkspaceArchiver); injected in tests. The artifact's relative layout is preserved so
-     * on-disk assets (markdown skills, templates) sit where the program expects them.
+     * (matches WorkspaceArchiver); injected in tests.
      */
     extract: (tgzPath: string, destDir: string) => Promise<void>;
     /**
-     * Called once with the extracted program directory, right after the artifact is unpacked (before the
-     * program body runs). The worker uses it to point the `agent()` leaf at the run's bundled files
-     * (`<dir>/skills/<name>.md`). Optional — the local/test path may omit it.
+     * Called once with the extracted program directory, right after the artifact is unpacked
+     * (before `run()` is invoked). The worker uses it to point the `agent()` leaf at the run's
+     * bundled files (`<dir>/skills/<name>.md`).
      */
     onExtracted?: (programDir: string) => void;
     /**
-     * Scrubs known secret values out of a string (the run's `SecretRedactor.redactText`). Applied to a
-     * top-level throw's message before it is logged AND before it is returned to the worker — a program
-     * that resolves a secret and then throws it in an error message must NOT land that secret raw in the
-     * logs or the finalized run output. Defaults to identity (tests/local).
+     * Scrubs known secret values out of a string (the run's `SecretRedactor.redactText`). Applied
+     * to a thrown error's message/code/hint before logging + finalize. Defaults to identity.
      */
     redactText?: (text: string) => string;
     /**
-     * Called once with the program's declared output IFF the program called `output(value)` (so an
-     * explicit `output(null)` still fires, but a program that never declared one does NOT). The worker
-     * wires this to emit an `output` activity entry into the run's event log. Best-effort: it must not
-     * throw (a telemetry hiccup can't change the run's result). Absent ⇒ no output entry.
+     * Called once with the run's reported return IFF it is non-null (a void return sends null,
+     * which is not an author-declared output). The worker wires this to emit an `output` activity
+     * entry into the run's event log. Best-effort: it must not throw.
      */
     onOutput?: (value: unknown) => void;
+    /**
+     * The run's cooperative-cancellation signal. The host server pushes the `cancel` notification
+     * to the program when it fires (the SDK aborts `context.signal`); the capability layer already
+     * honors it server-side at every hook.
+     */
+    signal?: AbortSignal | undefined;
+    /** Override the socket directory (tests). Default `os.tmpdir()` (short paths — sun_path cap). */
+    sockDir?: string | undefined;
+    /** Interpreter a `.py` entry is launched with (P5.5). Default `python3`, resolved on PATH —
+     *  the base image bakes one CPython (P5.3). May be an absolute path. */
+    pythonInterpreter?: string | undefined;
+    /** How long after SIGTERM an aborted Python child gets before SIGKILL. Default 5s. */
+    pythonKillGraceMs?: number | undefined;
 }
-/** Terminal result of running a workflow program. `output` is what the program declared via
- *  `output(value)` (null when it never did); for a failure it's null and `error` is set. A waiting
- *  seam (sleep / humanInput / workflows.call) never surfaces here — it freezes with the VM or
- *  holds the process, and the body simply continues when the wait is over. */
+/** Terminal result of running a workflow program. `output` is the validated value `run()`
+ *  returned (`null` for void); for a failure it's null and `error` is set. A waiting seam never
+ *  surfaces here — it freezes with the VM or holds the process, and `run()` simply continues. */
 export type ProgramResult = {
     kind: "completed";
     output: unknown;
@@ -95,8 +115,8 @@ export type ProgramResult = {
     };
 };
 /**
- * Run a workflow program to completion. Installs the host + input, extracts the VERIFIED artifact +
- * dynamic-imports its entry (which runs the body), and returns the terminal result. Always tears the
- * runtime state down and removes the temp tree afterward.
+ * Run a workflow program to completion: start the host-protocol server, extract the VERIFIED
+ * artifact, drive the loader (`bootstrap` → import entry → `run(input, context)` →
+ * `reportReturn`), and return the terminal result. Always tears the server + temp tree down.
  */
 export declare function runWorkflowProgram(args: RunProgramArgs, deps: ProgramRunnerDeps): Promise<ProgramResult>;