@boardwalk-labs/runner 0.2.17 → 0.3.0

package/dist/runtime/program_runner.js

@@ -1,55 +1,64 @@
-// WorkflowProgramRunner — executes a workflow program (the JS-body model, the workflow runtime design).
+// WorkflowProgramRunner — executes a workflow program (the workflow-format redesign, P3).
 //
 // A run is the execution of a built program ARTIFACT: the worker is handed the VERIFIED tarball
 // (its sha256 already checked against the pinned digest by the orchestrator) plus the entry module
-// name. This module is the mechanism: it installs the host adapter + trigger payload onto the
-// `@boardwalk-labs/workflow` singleton, extracts the artifact into a unique temp dir under the
-// program root, chdirs to the workspace, and dynamic-imports the entry so the program's body runs. The
-// program's `import { agent, sleep, … } from "@boardwalk-labs/workflow"` resolves to the SAME package
-// instance the host was installed on (one instance per process), so the hooks reach our adapter.
+// name. This module is the mechanism, the runner side of the host protocol (P3.1):
 //
-// The artifact is already BUILT JS (the CLI esbuild-bundles packages; the api-server type-strips
-// single files) — so the worker NEVER transpiles and NEVER installs. It only extracts + imports.
-// `@boardwalk-labs/workflow` is left external in the bundle, so the imported program resolves it to the SDK
-// package present in the worker image (giving up its own copy would break the dual-adapter).
+//   1. Start the {@link WorkflowHostServer} on a Unix socket and export its path as
+//      `BOARDWALK_HOST_SOCK` — the one env key the platform owns for the program's lifetime.
+//   2. Extract the artifact into a unique temp dir under the program root, chdir to the workspace.
+//   3. LOADER: connect the SDK's protocol client (the same `@boardwalk-labs/workflow` instance the
+//      program will import — `ensureSdkLink` guarantees it), `bootstrap()` → `{input, context}`
+//      (the client applies the schema-guided revival pass: a `date-time` field arrives as a
+//      `Date`), dynamic-import the entry, and call its DEFAULT-EXPORT `run(input, context)` —
+//      positional, Lambda-style; a `run()` declaring fewer params is fine.
+//   4. Report the return via `reportReturn` — the server validates it against the stored
+//      `output_schema` (mismatch ⇒ the run fails VALIDATION_FAILED) and `void` ⇒ `null`.
 //
-// Two places, both explicit, neither derived from `process.cwd()` (docs/WORKSPACE_PERSISTENCE.md I1/I2):
-//   - `workspaceRoot` — the run's `/workspace`. The working directory + HOME for AUTHOR code, so a
-//     relative write is the correct write and lands in what `workspace.persist` archives.
-//   - `programRoot`   — where the artifact extracts (`<programRoot>/.bw-runs/<runId>-<uuid>`). Must be
-//     OUTSIDE the workspace, or the bundle rides into every snapshot and accumulates across runs.
-// The extracted tree needs no node_modules-reachable ancestor: `ensureSdkLink` (below) links the SDK
-// into the exec dir, so the bare `@boardwalk-labs/workflow` import resolves from any root.
+// Importing is no longer running: the entry's module body only DEFINES `run`; execution is the
+// explicit call. The old module-body top-to-bottom execution path (ambient `input`, `output()`,
+// the installHost singleton) is DELETED with the redesign — there is no other program shape.
 //
-// Durability: the body runs once, in-process. `sleep`/`workflows.call` hold in-process via the host
-// (no checkpoint, no exit). A crash mid-run restarts the run from the top (handled by the
-// worker/scheduler-sweep, not here). Output capture is deferred (v0 returns null).
+// The artifact is already BUILT JS (the CLI bundles packages; the api-server type-strips single
+// files) — the worker NEVER transpiles and NEVER installs. `@boardwalk-labs/workflow` is left
+// external in the bundle and `ensureSdkLink` links THIS runtime's copy into the exec dir, so the
+// program's capability imports share the loader's connected client (one module instance).
+//
+// Two places, both explicit, neither derived from `process.cwd()` (docs/WORKSPACE_PERSISTENCE.md
+// I1/I2):
+//   - `workspaceRoot` — the run's `/workspace`. The working directory + HOME for AUTHOR code.
+//   - `programRoot`   — where the artifact extracts (`<programRoot>/.bw-runs/<runId>-<uuid>`),
+//     OUTSIDE the workspace so the bundle never rides into a snapshot.
+//
+// Durability: `run()` executes once, in-process. Waiting seams (sleep / humanInput /
+// workflows.call) hold or freeze inside the capability layer; a crash restarts the run from the
+// top (handled by the worker/scheduler-sweep, not here).
 import { mkdir, writeFile, rm, symlink, lstat } from "node:fs/promises";
 import { dirname, join, isAbsolute, relative, resolve, sep } from "node:path";
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
 import { randomUUID } from "node:crypto";
-import { installHost, installInput, installConfig, takeDeclaredOutput, resetRuntime, } from "@boardwalk-labs/workflow/runtime";
-import { AppError, ErrorCode, createLogger } from "./support/index.js";
+import { HOST_SOCK_ENV, HostError, connectHost, resetHost, } from "@boardwalk-labs/workflow/runtime";
+import { OUTPUT_MISMATCH_HINT, WorkflowHostServer } from "./host_server.js";
+import { PYTHON_SOURCE_DIR, invokePythonProgram, isPythonEntry } from "./python_program.js";
+import { AppError, ErrorCode, createLogger, errorCodeOf } from "./support/index.js";
 const log = createLogger("ProgramRunner");
 /** Subdirectory (under the work root) that holds transient extracted program trees. */
 const RUN_DIR = ".bw-runs";
 /**
  * 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 async function ensureSdkLink(execDir) {
     // A program tarball that ships its own `node_modules/@boardwalk-labs/workflow` would shadow the
-    // runtime's copy — the host adapter is installed on OUR instance, so the program's hooks would
-    // silently throw "no host installed". Fail loudly instead of link-then-EEXIST-swallow. Only a
-    // REAL entry is a vendored copy; a symlink is our own link (idempotent re-invocation), left be.
+    // runtime's copy — the loader's connected client lives on OUR instance, so the program's hooks
+    // would open a SECOND lazy connection at best and fail at worst. Fail loudly instead of
+    // link-then-EEXIST-swallow. Only a REAL entry is a vendored copy; a symlink is our own link
+    // (idempotent re-invocation), left be.
     const linkPath = join(execDir, "node_modules", "@boardwalk-labs", "workflow");
     const existing = await lstat(linkPath).catch(() => null);
     if (existing !== null) {
@@ -86,13 +95,25 @@ export function resolveEntryPath(dir, entry) {
     }
     return resolved;
 }
+/**
+ * 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 function resolveProgramEntryPath(dir, entry) {
+    return isPythonEntry(entry)
+        ? resolveEntryPath(join(dir, PYTHON_SOURCE_DIR), entry)
+        : resolveEntryPath(dir, entry);
+}
 /** Scratch filename for the in-flight artifact tarball inside a run's dir. */
 const ARTIFACT_FILE = "__program.tgz";
 /**
- * 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.
+ * Enforce I2: the extracted program must not live inside the run's workspace. Compares RESOLVED
+ * paths, and treats "the workspace itself" as inside.
  */
 export function assertProgramRootOutsideWorkspace(programRoot, workspaceRoot) {
     const rel = relative(resolve(workspaceRoot), resolve(programRoot));
@@ -103,44 +124,43 @@ export function assertProgramRootOutsideWorkspace(programRoot, workspaceRoot) {
 /** An engine `EngineError` carries a one-line actionable `hint` alongside its message. It reaches us
  *  as a thrown value across the SDK/engine package boundary, so DUCK-TYPE it rather than `instanceof`
  *  (a dual-package copy of the class would defeat the check) — any thrown error carrying a non-empty
- *  string `hint` is surfaced. Without this the hint is dropped here, and on a hosted run there is no
- *  other place it could survive: the runner reports a failure as `{ code, message, hint? }` and the
- *  broker persists exactly that. */
+ *  string `hint` is surfaced. A capability error that crossed the protocol carries its hint on
+ *  `HostError.data.hint` (see host_server's protocolErrorOf), so that lane is read too — without it
+ *  a hosted author would lose every engine hint to the wire. */
 function errorHint(err) {
     if (typeof err !== "object" || err === null)
         return undefined;
     const hint = err.hint;
-    return typeof hint === "string" && hint !== "" ? hint : undefined;
-}
-/** A machine-readable error code shaped like one: SCREAMING_SNAKE, as an engine `EngineError.code`
- *  (`VALIDATION`, `PROVIDER_ERROR`, …) and a Node syscall error (`ENOENT`) both are. */
-const ERROR_CODE_RE = /^[A-Z][A-Z0-9_]{0,63}$/;
-/**
- * The SEMANTIC code of a thrown error, preferred over its class name. An engine `EngineError` carries
- * `code: "VALIDATION"`; reporting `err.name` instead surfaced the useless `"EngineError"` on every
- * hosted failure (and `"Error"` for anything else). Duck-typed for the same reason as {@link errorHint}.
- *
- * Two guards, because a thrown value is author-controlled: the SCREAMING_SNAKE shape keeps prose (or a
- * stray object field) out of a field the UI renders as a code, and the CALLER redacts the result — an
- * uppercase-alnum secret would satisfy the pattern, so the shape check is hygiene, not the boundary.
- */
-function errorCode(err) {
-    if (typeof err !== "object" || err === null)
-        return undefined;
-    const code = err.code;
-    return typeof code === "string" && ERROR_CODE_RE.test(code) ? code : undefined;
+    if (typeof hint === "string" && hint !== "")
+        return hint;
+    const data = err.data;
+    if (typeof data === "object" && data !== null) {
+        const dataHint = data.hint;
+        if (typeof dataHint === "string" && dataHint !== "")
+            return dataHint;
+    }
+    return undefined;
 }
 /**
- * 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 async function runWorkflowProgram(args, deps) {
     const dir = join(deps.programRoot, RUN_DIR, `${args.runId}-${randomUUID()}`);
-    installHost(deps.host);
-    installInput(args.input);
-    // The run row's config is arbitrary JSON (jsonb); it IS valid JSON, so narrow to the SDK's JsonValue.
-    installConfig(args.config);
+    const server = new WorkflowHostServer({
+        capabilities: deps.capabilities,
+        bootstrap: {
+            // Boundary cast: the input arrived as JSON (the trigger payload / run row), so it is
+            // wire-safe by construction.
+            input: (args.input ?? null),
+            inputSchema: args.inputSchema,
+            context: args.context,
+        },
+        outputSchema: args.outputSchema,
+        signal: deps.signal,
+        sockDir: deps.sockDir,
+    });
     try {
         assertProgramRootOutsideWorkspace(deps.programRoot, deps.workspaceRoot);
         await mkdir(dir, { recursive: true });
@@ -152,28 +172,37 @@ export async function runWorkflowProgram(args, deps) {
         await rm(tgzPath, { force: true });
         // The bundled tree is now on disk — let the worker point the agent() leaf at `<dir>/skills/*.md`.
         deps.onExtracted?.(dir);
-        // Make the bare `@boardwalk-labs/workflow` import resolve from ANY work root — hosted images
-        // provide it via an ancestor node_modules, but a self-hosted daemon's workspace has none.
-        await ensureSdkLink(dir);
-        // Re-validate the entry here even though the control plane checked it at deploy: a self-hosted
-        // runner may point at an arbitrary control plane, so refuse an entry that could escape the
-        // extraction dir (absolute path or `..` segment) before importing it.
-        const entryPath = resolveEntryPath(dir, args.entry);
-        // Run the program body to its natural completion / failure. A waiting seam freezes with the
-        // VM (snapshot substrate) or holds the process — either way the body's own await continues.
-        return await runProgramBody(entryPath, deps);
+        // Language dispatch by entry extension (P5.5): a `.py` entry runs as a SUBPROCESS speaking
+        // the same host protocol (`python -m boardwalk._loader <entry>`, provided by the image's
+        // Python SDK — no JS SDK link to make); everything else keeps the in-process TS loader.
+        const python = isPythonEntry(args.entry);
+        // Make the bare `@boardwalk-labs/workflow` import resolve from ANY work root.
+        if (!python)
+            await ensureSdkLink(dir);
+        // Re-validate the entry here even though the control plane checked it at deploy (defense-in-depth
+        // for a self-hosted runner pointed at an arbitrary control plane).
+        const entryPath = resolveProgramEntryPath(dir, args.entry);
+        const sockPath = await server.listen();
+        // The ONE platform-owned env key a program keeps: how its SDK (and any subprocess speaking
+        // the protocol) finds the host — the documented discovery contract. Removed in finally.
+        process.env[HOST_SOCK_ENV] = sockPath;
+        // Invoke run(input, context) to its natural completion / failure. A waiting seam freezes with
+        // the VM (snapshot substrate) or holds the process — either way the await continues.
+        return python
+            ? await invokePythonProgram(entryPath, dir, sockPath, server, deps)
+            : await invokeProgram(entryPath, sockPath, server, deps);
     }
     catch (err) {
         const redactText = deps.redactText ?? ((s) => s);
         // Redact BEFORE both sinks: the message can carry a secret the program resolved then threw.
         const message = redactText(err instanceof Error ? err.message : String(err));
-        // The hint is author-facing guidance ("write `builtins: [...]`"); redact it too — it is built from
-        // the same untrusted inputs as the message and could echo a resolved secret.
+        // The hint is author-facing guidance; redact it too — it is built from the same untrusted
+        // inputs as the message and could echo a resolved secret.
         const rawHint = errorHint(err);
         const hint = rawHint === undefined ? undefined : redactText(rawHint);
         // The error's own code when it has one ("VALIDATION"), else the class name ("Error"). Redacted
         // like the rest: it is read off an author-controlled throw, not trusted to be a literal.
-        const rawCode = errorCode(err);
+        const rawCode = errorCodeOf(err);
         const code = rawCode !== undefined
             ? redactText(rawCode)
             : err instanceof Error
@@ -191,7 +220,11 @@ export async function runWorkflowProgram(args, deps) {
         };
     }
     finally {
-        resetRuntime();
+        Reflect.deleteProperty(process.env, HOST_SOCK_ENV);
+        // Clear the SDK's active-host singleton so a later run (tests; the local path) reconnects
+        // fresh rather than reusing a client whose server is gone.
+        resetHost();
+        await server.close();
         await rm(dir, { recursive: true, force: true }).catch((rmErr) => {
             log.warn("program_cleanup_failed", {
                 runId: args.runId,
@@ -201,19 +234,15 @@ export async function runWorkflowProgram(args, deps) {
     }
 }
 /**
- * Import (= run) the program entry and capture its declared output. Resolves to a `completed`
- * result; a program failure THROWS and is handled by the caller. A unique dir per run gives a
- * fresh URL so the module cache never returns an already-run program; `@vite-ignore` keeps
- * vitest/vite from statically analyzing the runtime URL.
+ * The LOADER (P3.1): connect the protocol client, `bootstrap()`, import the entry, call its
+ * default-export `run(input, context)`, and report the return. Resolves to a `completed` result;
+ * a failure THROWS and is curated by the caller.
  *
- * The chdir to the workspace (I1) happens HERE, at the boundary where author code starts, and only
- * after the artifact is extracted from {@link ProgramRunnerDeps.programRoot} — so the program's
- * files land in the workspace while the bundle stays out of it. Module resolution is unaffected:
- * Node resolves file-relative (the entry is imported by absolute URL, the SDK via `ensureSdkLink`),
- * never cwd-relative. The engine's local path has run exactly this shape since dev-on-engine
- * (`boardwalk/src/run/child.ts`), and the self-hosted daemon spawns with the same cwd.
+ * The chdir to the workspace (I1) happens HERE, at the boundary where author code starts.
+ * Module resolution is unaffected: Node resolves file-relative (the entry is imported by
+ * absolute URL, the SDK via `ensureSdkLink`), never cwd-relative.
  */
-async function runProgramBody(entryPath, deps) {
+async function invokeProgram(entryPath, sockPath, server, deps) {
     const callerCwd = process.cwd();
     try {
         process.chdir(deps.workspaceRoot);
@@ -222,20 +251,46 @@ async function runProgramBody(entryPath, deps) {
         // Fail loud. Running author code from an arbitrary cwd is what silently threw writes away.
         throw new AppError(ErrorCode.VALIDATION_FAILED, `The run's workspace "${deps.workspaceRoot}" is not usable as the working directory: ${err instanceof Error ? err.message : String(err)}`);
     }
+    let client = null;
     try {
-        await import(/* @vite-ignore */ pathToFileURL(entryPath).href);
-        // The program declares its result via `output(value)` (top-level code can't `return`); null when it
-        // never called it. This becomes the run's persisted output + a `workflows.call` parent's value, and
-        // (when actually declared) an `output` entry in the run's activity log.
-        const declared = takeDeclaredOutput();
-        if (declared !== null)
-            deps.onOutput?.(declared.value);
-        return { kind: "completed", output: declared !== null ? declared.value : null };
+        // Connect eagerly and install as the SDK's active host: the program's capability imports
+        // (same module instance, via ensureSdkLink) then share this client instead of lazily opening
+        // a second connection.
+        client = await connectHost({ sockPath });
+        const { input, context } = await client.bootstrap();
+        // A unique dir per run gives a fresh URL so the module cache never returns an already-loaded
+        // program; `@vite-ignore` keeps vitest/vite from statically analyzing the runtime URL.
+        const mod = await import(/* @vite-ignore */ pathToFileURL(entryPath).href);
+        const runFn = mod.default;
+        if (typeof runFn !== "function") {
+            throw Object.assign(new Error("The workflow entry has no `run` function default export."), {
+                code: "VALIDATION",
+                hint: "Export the entry as `export default async function run(input, context) { … }`.",
+            });
+        }
+        // Positional, Lambda-style: input = param 0, context = param 1; a run() declaring fewer
+        // params simply ignores the rest.
+        const value = await runFn(input, context);
+        try {
+            await client.reportReturn(value);
+        }
+        catch (err) {
+            if (err instanceof HostError && err.code === "VALIDATION_FAILED") {
+                // Curate the schema mismatch: message = what's wrong (the server's detail), hint = what
+                // to do. The failure code rides the HostError's own code.
+                throw Object.assign(err, { hint: OUTPUT_MISMATCH_HINT });
+            }
+            throw err;
+        }
+        const output = server.reportedReturn();
+        if (output !== null)
+            deps.onOutput?.(output);
+        return { kind: "completed", output };
     }
     finally {
-        // One run per process in production, so this matters for tests + the local/dev path — but a
-        // function that permanently moves its caller's cwd is a trap either way. Best-effort: the caller's
-        // dir may itself be gone, and that must not mask the run's real outcome.
+        client?.close();
+        // One run per process in production, so this matters for tests + the local path — but a
+        // function that permanently moves its caller's cwd is a trap either way. Best-effort.
         try {
             process.chdir(callerCwd);
         }

package/dist/runtime/program_worker.d.ts

@@ -1,13 +1,19 @@
 import type { Run } from "./wire/run.js";
 import { type WorkflowManifest } from "./wire/manifest.js";
-import type { WorkflowHost } from "@boardwalk-labs/workflow/runtime";
+import type { HostCapabilities } from "./host_server.js";
+import { type ClaimContextExtras } from "./run_context.js";
 import type { SecretRedactor } from "./agent/secret_redactor.js";
 import { type LogStream } from "./program_log_capture.js";
 /** Default 5-minute lease (matches the engine spec). */
 export declare const DEFAULT_LEASE_MS: number;
-/** Race-safe claim surface — RunRepository satisfies it. */
+/** Race-safe claim surface — the broker claim adapter satisfies it. Returns the claimed run row
+ *  plus the claim payload's context siblings (`workflowVersion` int, `environment {id,name}|null`
+ *  — P3.7), or null when the claim was lost. */
 export interface RunClaimer {
-    claimForWorker(runId: string, workerId: string, leaseUntil: number, nowMs: number): Promise<Run | null>;
+    claimForWorker(runId: string, workerId: string, leaseUntil: number, nowMs: number): Promise<{
+        run: Run;
+        context: ClaimContextExtras;
+    } | null>;
 }
 /** The pinned program's download reference (the worker fetches + verifies + extracts it). */
 export interface ProgramRef {
@@ -63,15 +69,14 @@ export interface LspLifecycleHandle {
 export interface RunOutputHandle {
     output(value: unknown): void;
 }
-/** Builds the per-run host (leaf + sleep + children + secrets) for a claimed run. Receives the run's
- *  cooperative-cancellation `signal` so every host hook honors it (credit exhaustion / cancel).
- *  Returns the run's `SecretRedactor` alongside the host so the orchestrator can scrub a terminal
- *  error with the SAME instance every resolved secret was recorded into; `readUsage` — a
- *  sampler over the run-level BudgetMeter the token flusher meters from; and an optional `workspace`
- *  handle (when the workflow opted into persistence) the orchestrator hydrates at start + persists at
- *  terminal (the host's `sleep` also persists, wired inside buildHost). */
+/** Builds the per-run capability seam (leaf + sleep + children + secrets + shell + usage + auth)
+ *  for a claimed run — what the host-protocol server dispatches onto. Receives the run's
+ *  cooperative-cancellation `signal` so every hook honors it (credit exhaustion / cancel).
+ *  Returns the run's `SecretRedactor` alongside so the orchestrator can scrub a terminal
+ *  error with the SAME instance every resolved secret was recorded into, and an optional
+ *  `workspace` handle the orchestrator hydrates at start + persists at terminal. */
 export type ProgramHostBuilder = (run: Run, manifest: WorkflowManifest, signal: AbortSignal) => Promise<{
-    host: WorkflowHost;
+    capabilities: HostCapabilities;
     redactor: SecretRedactor;
     workspace?: WorkspaceHandle;
     phases?: PhaseLifecycleHandle;
@@ -98,6 +103,12 @@ export type ProgramHostBuilder = (run: Run, manifest: WorkflowManifest, signal:
         start(): Promise<void>;
         stopAndFlush(): Promise<void>;
     };
+    /** The compute-budget breach watcher (budget_gate.ts): detects a `max_compute_seconds` breach
+     *  between capability seams. The orchestrator stops it on EVERY terminal path (its interval is
+     *  unref'd, so this is hygiene, not liveness). Absent on paths without a budget gate. */
+    budgetWatch?: {
+        stop(): void;
+    };
 }>;
 /** Handle to a running per-session loop (metering or credit watch); `stop()` ends + drains it. */
 export interface RunSessionHandle {

package/dist/runtime/program_worker.js

@@ -22,6 +22,7 @@
 // v0 deferral (a clear seam): run-level outcome validation (needs program output capture).
 import { createLogger } from "./support/index.js";
 import { workflowManifestSchema } from "./wire/manifest.js";
+import { buildContextData } from "./run_context.js";
 // Import from the pure file (NOT the domain/workflow barrel, which pulls in `typescript`) so the
 // worker bundle stays free of the TS compiler — the worker never transpiles.
 import { verifyArtifactDigest } from "./wire/artifact_verify.js";
@@ -36,20 +37,23 @@ export async function runProgramWorker(runId, deps) {
     const leaseMs = deps.leaseMs ?? DEFAULT_LEASE_MS;
     // Runtime-billing baseline: when THIS worker session began.
     const sessionStartMs = now();
-    const claimed = await deps.runs.claimForWorker(runId, deps.workerId, sessionStartMs + leaseMs, sessionStartMs);
-    if (claimed === null) {
+    const claim = await deps.runs.claimForWorker(runId, deps.workerId, sessionStartMs + leaseMs, sessionStartMs);
+    if (claim === null) {
         log.info("worker_claim_lost", { runId, workerId: deps.workerId });
         return { kind: "claim_lost" };
     }
     log.info("worker_claimed", { runId, workerId: deps.workerId });
+    const claimed = claim.run;
+    /** Pre-flight/setup failure: no program ran (and none will) — finalize failed and exit. */
+    const failEarly = async (reason, error, logEvent, logFields) => {
+        await deps.finalizer.finalize(runId, "failed", { error });
+        log.error(logEvent, { runId, ...logFields });
+        return { kind: "failed", reason };
+    };
     const loaded = await loadVersion(deps, claimed);
     if (loaded === null) {
         // Pre-flight integrity failure — no program ran, so no charge.
-        await deps.finalizer.finalize(runId, "failed", {
-            error: { code: "INTERNAL_ERROR", message: "Run version missing, or manifest invalid" },
-        });
-        log.error("worker_version_invalid", { runId, workflowVersionId: claimed.workflowVersionId });
-        return { kind: "failed", reason: "version_invalid" };
+        return failEarly("version_invalid", { code: "INTERNAL_ERROR", message: "Run version missing, or manifest invalid" }, "worker_version_invalid", { workflowVersionId: claimed.workflowVersionId });
     }
     // Fetch + verify the program ARTIFACT before any work (pre-flight; an integrity failure = no charge,
     // no run). The bytes are the EXACT artifact the manifest was derived from at deploy; verifying the
@@ -59,38 +63,10 @@ export async function runProgramWorker(runId, deps) {
         tarball = await deps.fetchProgram(loaded.program.downloadUrl);
     }
     catch (err) {
-        await deps.finalizer.finalize(runId, "failed", {
-            error: { code: "PROGRAM_FETCH_FAILED", message: "Could not download the program artifact" },
-        });
-        log.error("worker_program_fetch_failed", {
-            runId,
-            error: err instanceof Error ? err.message : String(err),
-        });
-        return { kind: "failed", reason: "program_fetch_failed" };
+        return failEarly("program_fetch_failed", { code: "PROGRAM_FETCH_FAILED", message: "Could not download the program artifact" }, "worker_program_fetch_failed", { error: err instanceof Error ? err.message : String(err) });
     }
     if (!verifyArtifactDigest(tarball, loaded.program.digest)) {
-        await deps.finalizer.finalize(runId, "failed", {
-            error: { code: "PROGRAM_INTEGRITY", message: "Program artifact digest mismatch" },
-        });
-        log.error("worker_program_integrity", { runId, workflowVersionId: claimed.workflowVersionId });
-        return { kind: "failed", reason: "program_integrity" };
-    }
-    // deadline_seconds: a WALL-CLOCK cap from the run's ORIGINAL start (incl. suspended idle). Enforced
-    // HERE, before running — so a run RESUMED past its deadline (e.g. it slept/awaited longer than the
-    // cap) fails even when its program has NO agent() turn (the BudgetMeter's per-turn check would never
-    // fire for those). Orthogonal to max_duration_seconds (active compute, the BudgetMeter's job).
-    const deadlineSeconds = loaded.manifest.budget?.deadline_seconds;
-    if (deadlineSeconds !== undefined &&
-        claimed.startedAt !== null &&
-        Date.now() - claimed.startedAt > deadlineSeconds * 1000) {
-        await deps.finalizer.finalize(runId, "failed", {
-            error: {
-                code: "BUDGET_EXCEEDED",
-                message: `Run exceeded budget.deadline_seconds (${deadlineSeconds.toString()}s wall-clock) and was terminated.`,
-            },
-        });
-        log.info("worker_deadline_exceeded", { runId, deadlineSeconds });
-        return { kind: "failed", reason: "deadline_exceeded" };
+        return failEarly("program_integrity", { code: "PROGRAM_INTEGRITY", message: "Program artifact digest mismatch" }, "worker_program_integrity", { workflowVersionId: claimed.workflowVersionId });
     }
     // Cooperative-cancellation signal for the run. The credit watcher (and, later, user-initiated
     // cancel) aborts it; the WorkflowHost honors it at every hook so the program unwinds.
@@ -104,15 +80,9 @@ export async function runProgramWorker(runId, deps) {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        await deps.finalizer.finalize(runId, "failed", {
-            error: { code: "HOST_BUILD_FAILED", message },
-        });
-        log.error("worker_host_build_failed", { runId, error: message });
-        return { kind: "failed", reason: "host_build_failed" };
+        return failEarly("host_build_failed", { code: "HOST_BUILD_FAILED", message }, "worker_host_build_failed", { error: message });
     }
-    const { host, redactor, workspace, phases, activity, setProgramDir, lsp } = built;
-    const browserSessions = built.browserSessions;
-    const capture = built.capture;
+    const { capabilities, redactor, workspace, phases, activity, setProgramDir, lsp, browserSessions, capture, budgetWatch, } = built;
     // Guarantee the /workspace sandbox dir exists for EVERY run (persist or not) so a program can write
     // to /workspace without a defensive mkdir. Runs before hydrate (whose extract targets the dir).
     // Best-effort — the image pre-creates the dir; a failure here would resurface at the program's write.
@@ -184,16 +154,21 @@ export async function runProgramWorker(runId, deps) {
             tarball,
             entry: loaded.program.entry,
             input: claimed.input ?? claimed.triggerPayload,
-            config: claimed.config ?? {},
+            // The stored derived I/O schemas ride the manifest (P4): the input schema crosses on
+            // `bootstrap` (the SDK's revival pass), the output schema gates `report_return`.
+            inputSchema: loaded.manifest.input_schema ?? null,
+            outputSchema: loaded.manifest.output_schema ?? null,
+            context: buildContextData(claimed, deps.workspaceRoot, claim.context),
         }, 
         // redactText scrubs a thrown error's message before it is logged + finalized into run output.
-        // onOutput emits the `output` activity entry into the run's log when the program declared one.
+        // onOutput emits the `output` activity entry into the run's log when the program returned one.
         {
-            host,
+            capabilities,
             workspaceRoot: deps.workspaceRoot,
             programRoot: deps.programRoot,
             redactText: (text) => redactor.redactText(text),
             extract: deps.extractArchive,
+            signal: controller.signal,
             ...(setProgramDir !== undefined ? { onExtracted: setProgramDir } : {}),
             ...(activity !== undefined
                 ? {
@@ -216,6 +191,9 @@ export async function runProgramWorker(runId, deps) {
             await lease.stop();
         if (runtimeFlush !== undefined)
             await runtimeFlush.stop();
+        // Stop the compute-budget breach watcher (sync, never throws).
+        if (budgetWatch !== undefined)
+            budgetWatch.stop();
         // Shut down the run's language server(s) on EVERY terminal path (success/failure/throw) so no
         // language-server process leaks. `close()` is idempotent + never throws, so this best-effort call
         // is safe (it runs before the workspace snapshot, which is the slowest step).

package/dist/runtime/python_program.d.ts

@@ -0,0 +1,68 @@
+import { type WorkflowHostServer } from "./host_server.js";
+import type { ProgramResult, ProgramRunnerDeps } from "./program_runner.js";
+/** Default interpreter, resolved on PATH — the base image bakes one CPython (P5.3). */
+export declare const DEFAULT_PYTHON_INTERPRETER = "python3";
+/** Where the ratified Python artifact layout keeps the author's SOURCE tree. A stored Python
+ *  entry (`main.py`) is relative to THIS dir — Python has no bundle step, so the shipped source
+ *  is what runs (`<extractDir>/.bw-src/main.py`), never a root module like the TS `index.mjs`. */
+export declare const PYTHON_SOURCE_DIR = ".bw-src";
+/** Where the ratified layout keeps the uv-materialized frozen dependency tree (build-time
+ *  `uv lock` → `export --frozen` → `pip install --target`; never installed on the hot path). */
+export declare const PYTHON_SITE_PACKAGES_DIR: string;
+/**
+ * The platform-owned `PYTHONPATH` for a Python program run:
+ *
+ *     <programDir>/.bw-src  <sep>  <programDir>/.bw-machine/site-packages
+ *
+ * ORDER (deliberate): the author's sources BEFORE the frozen deps, so an author module wins a
+ * name collision with a dependency. That mirrors CPython's own convention — the interpreter puts
+ * a script's directory ahead of site-packages — extended to the whole tree, which needs an
+ * explicit entry because the loader is launched `-m` style (sys.path[0] is the workspace cwd,
+ * not `.bw-src`) yet sibling imports (`import helper`) must resolve from the source tree. The
+ * file an author can SEE in the Code tab beating an invisible dep is the predictable reading.
+ *
+ * The value REPLACES any PYTHONPATH inherited from the worker's env: for a Python run the
+ * module path is platform-owned (the guest image provides python3 with the `boardwalk` loader
+ * package importable at site level; nothing from the worker's own environment may steer author
+ * import resolution). A no-dep package ships no site-packages dir at all — Python silently
+ * skips a nonexistent sys.path entry, so the value is set unconditionally, never stat-gated.
+ */
+export declare function pythonModulePath(programDir: string): string;
+/** The loader module the guest image's `boardwalk` package provides (`python -m <module> <entry>`). */
+export declare const PYTHON_LOADER_MODULE = "boardwalk._loader";
+/** How long after SIGTERM an aborted child gets before SIGKILL. */
+export declare const DEFAULT_PYTHON_KILL_GRACE_MS = 5000;
+/** How many trailing stderr lines are kept for failure curation (the traceback tail). */
+export declare const STDERR_TAIL_LINES = 20;
+/** The language dispatch decision (P5.5): `.py` takes the subprocess path; everything else
+ *  (`.ts`/`.js`/`.mjs`) keeps the in-process TS loader. Case-insensitive on the extension. */
+export declare function isPythonEntry(entry: string): boolean;
+/** Split a piped stream into complete lines (LF or CRLF). `flush()` emits a trailing partial
+ *  line (a crash mid-line must not swallow the last words of the traceback). */
+export declare function lineSplitter(onLine: (line: string) => void): {
+    push: (chunk: string) => void;
+    flush: () => void;
+};
+/** What the child process ended as, for failure curation. */
+export interface PythonExitFacts {
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    /** The last {@link STDERR_TAIL_LINES} stderr lines, oldest first. */
+    stderrTail: readonly string[];
+}
+/**
+ * Curate a child that ended WITHOUT completing the loader contract (no `report_return`) into a
+ * throwable the runner's failure path understands (`{code, message, hint}`, duck-typed). The
+ * caller redacts — nothing here needs to.
+ */
+export declare function curatePythonFailure(facts: PythonExitFacts): Error;
+/** Fail CLOSED on a spawn failure: a missing interpreter gets an UNSUPPORTED-class error naming
+ *  the image expectation instead of a bare ENOENT; anything else passes through untouched. */
+export declare function curateSpawnFailure(interpreter: string, err: NodeJS.ErrnoException): Error;
+/**
+ * Run a Python workflow program to completion: spawn the loader subprocess against the already
+ * -listening host server, stream its output into the program log capture, and read the terminal
+ * state off the server once the child exits. Resolves `completed` when `report_return` landed;
+ * THROWS on failure (the caller curates + redacts, same as the TS path).
+ */
+export declare function invokePythonProgram(entryPath: string, programDir: string, sockPath: string, server: WorkflowHostServer, deps: ProgramRunnerDeps): Promise<ProgramResult>;