@boardwalk-labs/runner 0.1.2

package/dist/runtime/leaf_executor.js

@@ -0,0 +1,333 @@
+// EngineLeafExecutor — the `agent()` leaf, run by the OPEN-SOURCE engine's agent loop.
+//
+// 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
+// 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.
+//
+// What it deliberately does NOT do:
+//   - no checkpoint / resume (hold-and-pay; a crash restarts the run from the top).
+//   - no control-flow tools — `sleep` / `workflows.call` are PROGRAM hooks (they pause the run),
+//     not LLM tools; the engine's tool set is per-call inline ToolDefs / skills / memory only.
+//   - no run-level billing/credit/outcome — those live one level up, in the worker.
+//
+// MCP servers ARE supported on hosted runs, but constrained: only the `http` transport, and only to
+// hosts in the egress allowlist (the worker can reach nothing else through the forward proxy). A leaf
+// naming a `stdio` server or a non-allowlisted host fails up-front with a clear error. Static bearer
+// auth (a token in the server's `headers`, typically from `secrets.get`) needs no further wiring — the
+// engine tries those first. OAuth servers broker a short-lived token via `brokerMcpToken` (the
+// control-plane vault); the token state never lives on the worker.
+import { join } from "node:path";
+import { runAgentLeaf, Redactor, EngineError, } from "@boardwalk-labs/engine/core";
+import { AppError, ErrorCode } from "./support/index.js";
+import { directProviderFor, streamDirectTurn, } from "./direct_inference.js";
+import { throwIfAborted } from "./run_abort.js";
+/**
+ * Per-run leaf executor. The worker constructs one bound to the run + run-level budget, and wires it
+ * as the `LeafExecutor` on the run's WorkflowHost, so every `agent()` the program calls runs here
+ * through the engine's loop.
+ */
+export class EngineLeafExecutor {
+    deps;
+    leafCount = 0;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async run(prompt, opts, signal, resume) {
+        // Cooperative cancellation: don't even start the leaf if the run is already aborted.
+        throwIfAborted(signal);
+        // Validate any named MCP servers up-front (before the engine tries to connect) so a leaf naming
+        // an unsupported transport or a non-allowlisted host fails clearly and deterministically at the
+        // leaf boundary, rather than deep in the engine loop. The broker re-checks the host authoritatively
+        // when it vends a token (the worker can't widen egress).
+        assertHostedMcpAllowed(opts?.mcp);
+        const leafIndex = ++this.leafCount;
+        const agentName = opts?.name;
+        const identity = {
+            agentId: `agent-${String(leafIndex)}`,
+            ...(agentName !== undefined ? { agentName } : {}),
+        };
+        const sink = this.deps.makeEventSink(leafIndex, identity);
+        // Seed a fresh engine Redactor from the run's recorded secret values — the loop scrubs them out
+        // of every model-bound string (prompt, tool args/results) before the model sees them. Labels are
+        // immaterial (the placeholder never reveals which secret matched); index them for distinctness.
+        const redactor = new Redactor();
+        this.deps.redactor.values.forEach((value, i) => {
+            redactor.add(`secret-${String(i)}`, value);
+        });
+        const io = this.buildLeafIo({ identity, sink, redactor, leafIndex, signal });
+        try {
+            // `resume` (a tool-level human-input resume) re-enters a parked leaf from its checkpoint + the
+            // answers. A leaf that PARKS throws LeafParked, which propagates to the host (the executor never
+            // catches it — the host turns it into a suspend).
+            return await runAgentLeaf(prompt, opts, io, resume);
+        }
+        finally {
+            // The run's AbortSignal is authoritative: if it fired during the leaf (credit exhaustion / a
+            // user cancel), unwind the program even if the loop returned (e.g. an aborted stream that
+            // resolved). The streamModel seam below rejects in-flight calls when the signal is aborted.
+            throwIfAborted(signal);
+        }
+    }
+    /** Assemble the broker-backed `LeafIo` the engine loop drives for one leaf call. */
+    buildLeafIo(ctx) {
+        const { identity, sink, redactor, leafIndex, signal } = ctx;
+        const skillsDir = this.deps.skillsDir?.() ?? null;
+        const programDir = this.deps.programDir?.() ?? null;
+        // The broker stamps each turn's exact upstream cost on the result frame, but the engine hands
+        // `reportUsage` only `ChatTurn.usage` (input/output tokens, no cost). So `streamModel` stashes the
+        // result frame's `costMicros` here for the matching `reportUsage` to consume — one slot per leaf
+        // io (children get their own via `forChild`), and the loop is strictly streamModel→reportUsage per
+        // turn, so a single slot never races. Null ⇒ no upstream cost for the next turn (BYO / unavailable).
+        let pendingCostMicros = null;
+        return {
+            identity,
+            redactor,
+            // `host` lights up the host-backed built-ins (webfetch/web_search/artifacts); `lspService` lights
+            // up the engine-native `diagnostics` tool + diagnostics-after-edit. Each is omitted when its
+            // backend isn't wired (then that surface stays absent — the correct degradation). `workspaceDir`
+            // drives the WORKSPACE `AGENTS.md` tier (a codebase the run cloned, root + nested) and `programDir`
+            // the BUNDLED tier (the package-root AGENTS.md, the author's standing instructions) — both
+            // default-on, read by every agent(). `exactOptionalPropertyTypes` ⇒ conditional-spread, never an
+            // explicit `undefined`.
+            capabilities: {
+                workspaceDir: this.deps.workspaceRoot,
+                skillsDir,
+                ...(programDir !== null ? { programDir } : {}),
+                ...(this.deps.toolHost !== undefined ? { host: this.deps.toolHost } : {}),
+                ...(this.deps.lspService !== undefined ? { lspService: this.deps.lspService } : {}),
+            },
+            // One model turn → the broker (the runner holds no model creds). The broker resolves the real
+            // model server-side, invokes the matching adapter, and streams text back; we surface each delta
+            // through providerIo.onDelta and return the terminal turn. An aborted run rejects in-flight.
+            streamModel: async (req, providerIo) => {
+                throwIfAborted(signal);
+                return this.streamModel(req, providerIo, signal, (costMicros) => {
+                    pendingCostMicros = (pendingCostMicros ?? 0) + costMicros;
+                });
+            },
+            // turn_started rides a NEW stride block (the supervisor opens it); subsequent leaf events ride
+            // the same block. The shared emitter owns the run-global cursor.
+            startTurn: (turnId) => {
+                sink.beginTurn(turnId, { kind: "turn_started", ...identity });
+            },
+            // Engine LeafEventBody → the platform's v1 RunEventBody. The platform already adopted the SDK
+            // v1 wire format, and the engine emits the same kinds, so this is a near-identity mapping.
+            emit: (turnId, body) => {
+                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.
+            reportUsage: (modelRefForUsage, usage) => {
+                const delta = toUsageDelta(usage);
+                // Cap on the turn's REAL upstream cost when the broker reported one (the result frame's
+                // costMicros, stashed by streamModel just above) so max_usd tracks actual spend rather than a
+                // representative-rate token estimate that's blind to prompt-cache discounts. Null ⇒ BYO / no
+                // upstream price ⇒ addUsage falls back to the estimate. Consume-once so the next turn is clean.
+                const realCostUsd = pendingCostMicros === null ? undefined : pendingCostMicros / 1_000_000;
+                pendingCostMicros = null;
+                this.deps.budget.addUsage(delta, realCostUsd);
+                const breach = this.deps.budget.capBreachReason();
+                if (breach !== null) {
+                    throw new EngineError("BUDGET_EXCEEDED", `agent() leaf exceeded the run budget cap (${breach})`);
+                }
+                this.deps.meterUsage?.({
+                    model: modelRefForUsage,
+                    inputTokens: delta.inputTokens ?? 0,
+                    outputTokens: delta.outputTokens ?? 0,
+                    ...(delta.cacheReadTokens === undefined
+                        ? {}
+                        : { cachedReadTokens: delta.cacheReadTokens }),
+                    ...(delta.cacheWriteTokens === undefined
+                        ? {}
+                        : { cachedWriteTokens: delta.cacheWriteTokens }),
+                    leafIndex,
+                });
+            },
+            // A memory dir (`agent({ memory })`) is workspace-relative; the run's whole `/workspace` is
+            // already persisted by the worker when the manifest opts in (workspace.persist), so this only
+            // needs to validate the dir is inside the workspace (defense-in-depth) — there is no separate
+            // per-dir snapshot to register. The engine's buildToolSet already shape-validates the path.
+            memoryUsed: (dir) => {
+                const abs = join(this.deps.workspaceRoot, dir);
+                if (abs !== this.deps.workspaceRoot && !abs.startsWith(this.deps.workspaceRoot + "/")) {
+                    throw new EngineError("VALIDATION", `agent() memory dir "${dir}" escapes the workspace.`);
+                }
+            },
+            // OAuth bearer brokering for a hosted MCP server. Called REACTIVELY by the engine — only after a
+            // server 401s the static `headers` — so static-bearer / no-auth servers never reach here. When
+            // the broker hook is wired, the token comes from the control-plane vault (never stored on the
+            // worker); `invalidateToken` names a just-rejected token so the broker forces a refresh. Absent
+            // hook ⇒ no token, and the engine surfaces a clean failure with the hint (correct degradation).
+            mcpToken: (serverUrl, invalidateToken) => this.deps.brokerMcpToken?.(serverUrl, invalidateToken) ??
+                Promise.resolve({
+                    accessToken: null,
+                    hint: `No OAuth connection is configured for MCP server "${serverUrl}". Connect it in the ` +
+                        `Boardwalk console, or provide a bearer token via the server's headers.`,
+                }),
+            // Derive a child leaf io for a `subagent` tool call (engine ≥0.1.11): a fresh run-unique
+            // identity over the SAME sinks. `makeEventSink` returns the one run-global emitter, so every
+            // leaf's events ride a single monotonic cursor; the child's usage feeds the SAME run budget
+            // and meters under its own `leafIndex`. Reuses the parent leaf's redactor (same run secrets)
+            // and AbortSignal. A child gets no `subagent` tool, so its own forkLeaf is never invoked.
+            forkLeaf: (childOpts) => {
+                const childIndex = ++this.leafCount;
+                const childIdentity = {
+                    agentId: `agent-${String(childIndex)}`,
+                    ...(childOpts.name !== undefined ? { agentName: childOpts.name } : {}),
+                };
+                return this.buildLeafIo({
+                    identity: childIdentity,
+                    sink: this.deps.makeEventSink(childIndex, childIdentity),
+                    redactor,
+                    leafIndex: childIndex,
+                    signal,
+                });
+            },
+        };
+    }
+    /** POST one model turn to the broker's `/inference` and adapt its NDJSON stream into the engine's
+     *  ModelTurnResult: each `delta` frame drives providerIo.onDelta; the terminal `result` frame is
+     *  the turn. An `error` frame throws (the broker already classified it). An abort mid-stream throws. */
+    async streamModel(req, providerIo, signal, onCost) {
+        // Runner-direct BYO (D7): the org's own endpoint + key, called with the same engine adapters
+        // the broker uses. No platform cost (BYO is never metered) — onCost stays untouched.
+        // A direct turn needs an explicit model (an omitted model means the managed auto lane,
+        // which is always brokered).
+        const directModel = req.model;
+        const direct = this.deps.byo === undefined || directModel === undefined
+            ? null
+            : directProviderFor(this.deps.byo.registry, req.provider);
+        if (direct !== null && this.deps.byo !== undefined && directModel !== undefined) {
+            throwIfAborted(signal);
+            const out = await streamDirectTurn(this.deps.byo, direct, {
+                model: directModel,
+                messages: req.messages,
+                tools: req.tools,
+                ...(req.reasoning !== undefined ? { reasoning: req.reasoning } : {}),
+            }, providerIo.onDelta);
+            throwIfAborted(signal);
+            return { turn: out.turn, modelRef: out.modelRef };
+        }
+        let result = null;
+        for await (const frame of this.deps.inference.streamInference({
+            model: req.model,
+            provider: req.provider,
+            messages: req.messages,
+            tools: req.tools,
+            ...(req.reasoning !== undefined ? { reasoning: req.reasoning } : {}),
+        })) {
+            throwIfAborted(signal);
+            if (frame.kind === "delta") {
+                providerIo.onDelta?.(frame.text);
+            }
+            else if (frame.kind === "result") {
+                result = { turn: frame.turn, modelRef: frame.modelRef };
+                // The broker stamps the turn's exact upstream cost on the result frame (0 ⇒ none / BYO); hand
+                // it to the budget guardrail via the caller's stash so max_usd caps on real spend.
+                if (frame.costMicros > 0)
+                    onCost?.(frame.costMicros);
+            }
+            else if (frame.kind === "error") {
+                // The broker already classified this into a clean, customer-facing message — surface it
+                // verbatim (the loop records it as the run's error).
+                throw new Error(frame.error.message);
+            }
+            // else: a `ping` heartbeat keeping the connection alive during a long turn — nothing to do.
+        }
+        if (result === null) {
+            throw new Error("Inference stream ended without a result frame");
+        }
+        return result;
+    }
+}
+/**
+ * Gate the MCP servers a hosted leaf may use: only the `http` transport (no arbitrary `stdio`
+ * processes on the worker) and a parseable URL. Throws a clear VALIDATION_FAILED for the first
+ * offending ref so the leaf fails at its boundary, before the engine connects out.
+ *
+ * Reachability of the host is NOT gated here: a hosted run's egress is OPEN by default (the forward
+ * proxy allows all public destinations; a workflow restricts it via manifest.egress), and the proxy
+ * is the single enforcement point — a server blocked by a restrictive egress fails at the proxy when
+ * the engine connects, not via an MCP-specific allowlist that would be stricter than the platform.
+ */
+export function assertHostedMcpAllowed(refs) {
+    for (const ref of refs ?? []) {
+        if (ref.transport !== "http") {
+            throw new AppError(ErrorCode.VALIDATION_FAILED, `MCP server "${ref.name}" uses the "${ref.transport}" transport, which hosted runs do not ` +
+                `support — use transport: "http".`);
+        }
+        if (!isParsableUrl(ref.url)) {
+            throw new AppError(ErrorCode.VALIDATION_FAILED, `MCP server "${ref.name}" has an invalid URL: ${ref.url}`);
+        }
+    }
+}
+/** True when `url` parses (a malformed server URL should fail the leaf early). */
+function isParsableUrl(url) {
+    try {
+        new URL(url);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Map the engine loop's `TokenUsage` to the worker's `UsageDelta` (only numeric fields kept). */
+function toUsageDelta(usage) {
+    const delta = {};
+    if (typeof usage.inputTokens === "number")
+        delta.inputTokens = usage.inputTokens;
+    if (typeof usage.outputTokens === "number")
+        delta.outputTokens = usage.outputTokens;
+    if (typeof usage.cacheReadTokens === "number")
+        delta.cacheReadTokens = usage.cacheReadTokens;
+    if (typeof usage.cacheCreationTokens === "number")
+        delta.cacheWriteTokens = usage.cacheCreationTokens;
+    return delta;
+}
+/**
+ * Project an engine `LeafEventBody` onto the platform's v1 `RunEventBody`. Both are the SDK's v1
+ * event kinds (the platform consumes `@boardwalk-labs/workflow`; the engine emits the same shapes),
+ * so this is a near-identity copy — `turn_ended` re-stamps the leaf identity the platform tracks,
+ * and the body is otherwise passed through verbatim. A discriminated switch keeps it exhaustive
+ * (any new engine kind surfaces as a compile error here, not a silent drop).
+ */
+function toRunEventBody(body, identity) {
+    switch (body.kind) {
+        case "turn_ended":
+            return {
+                kind: "turn_ended",
+                ...identity,
+                reason: body.reason,
+                ...(body.usage === undefined ? {} : { usage: body.usage }),
+                ...(body.error === undefined ? {} : { error: body.error }),
+            };
+        case "text_start":
+            return { kind: "text_start", blockId: body.blockId };
+        case "text_delta":
+            return { kind: "text_delta", blockId: body.blockId, text: body.text };
+        case "text_end":
+            return { kind: "text_end", blockId: body.blockId };
+        case "tool_call_start":
+            return { kind: "tool_call_start", toolCallId: body.toolCallId, toolName: body.toolName };
+        case "tool_call_input_complete":
+            return { kind: "tool_call_input_complete", toolCallId: body.toolCallId, input: body.input };
+        case "tool_call_executing":
+            return { kind: "tool_call_executing", toolCallId: body.toolCallId };
+        case "tool_output_delta":
+            return {
+                kind: "tool_output_delta",
+                toolCallId: body.toolCallId,
+                stream: body.stream,
+                text: body.text,
+            };
+        case "tool_call_result":
+            return { kind: "tool_call_result", toolCallId: body.toolCallId, result: body.result };
+        case "tool_call_error":
+            return { kind: "tool_call_error", toolCallId: body.toolCallId, error: body.error };
+    }
+}

package/dist/runtime/lease_renewer.d.ts

@@ -0,0 +1,31 @@
+/** Renew cadence — well under the 5-min lease so a renewed lease always has minutes of headroom (a
+ *  missed tick still has time to recover before the lease expires). */
+export declare const DEFAULT_LEASE_RENEW_INTERVAL_MS = 120000;
+export interface LeaseRenewerDeps {
+    /** The run being kept alive (for correlation/logging). */
+    runId: string;
+    /** Extend the lease; resolves true while we still hold it, false once it's definitively lost
+     *  (brokered: `RunnerControlClient.renewLease` → `POST /renew`). */
+    renew: () => Promise<boolean>;
+    /** Fired exactly once the first time the lease is seen to be lost. */
+    onLost: () => void;
+    intervalMs?: number;
+}
+export declare class LeaseRenewer {
+    private readonly deps;
+    private timer;
+    private firing;
+    private lost;
+    private stopped;
+    constructor(deps: LeaseRenewerDeps);
+    /** Begin periodic lease renewal. */
+    start(): void;
+    /** Stop renewing and drain any in-flight renew. Idempotent. */
+    stop(): Promise<void>;
+    /** Whether the lease was definitively lost (the orchestrator may read this to shape the outcome). */
+    isLost(): boolean;
+    /** True once the renewer should no longer act. A method (re-evaluated after an `await`) so `stop()`
+     *  can flip `stopped` mid-tick. */
+    private done;
+    private tick;
+}

package/dist/runtime/lease_renewer.js

@@ -0,0 +1,80 @@
+// LeaseRenewer — keeps a long run's lease fresh so the recovery sweep doesn't reclaim a STILL-ALIVE
+// worker (docs/RUNNER_BROKER.md; MASTER_SPEC §6).
+//
+// A run is claimed with a fixed lease (DEFAULT_LEASE_MS, 5 min). The worker never used to renew it,
+// so any run longer than the lease (an Opus agentic loop is routinely 7+ min) had its lease expire
+// mid-flight; the 1-min recovery sweep then reclaimed the live run and re-dispatched it — a redundant
+// concurrent attempt that doubled the spend. This watcher (the heartbeat counterpart to the credit /
+// cancel watchers) re-extends the lease on a timer through the broker (`POST /renew`, since the runner
+// holds no DB credential).
+//
+// On a transient renew failure it just retries next tick (the renew cadence leaves several minutes of
+// lease headroom, so a blip is harmless). On a DEFINITIVE loss (the broker says the run is no longer
+// ours — another worker reclaimed it), it fires `onLost` once: the orchestrator aborts with
+// `lease_lost`, and the worker stops WITHOUT finalizing so it can't clobber the new owner's run.
+import { createLogger } from "./support/index.js";
+const log = createLogger("LeaseRenewer");
+/** Renew cadence — well under the 5-min lease so a renewed lease always has minutes of headroom (a
+ *  missed tick still has time to recover before the lease expires). */
+export const DEFAULT_LEASE_RENEW_INTERVAL_MS = 120_000;
+export class LeaseRenewer {
+    deps;
+    timer = null;
+    firing = Promise.resolve();
+    lost = false;
+    stopped = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Begin periodic lease renewal. */
+    start() {
+        if (this.timer !== null)
+            return;
+        const interval = this.deps.intervalMs ?? DEFAULT_LEASE_RENEW_INTERVAL_MS;
+        this.timer = setInterval(() => {
+            this.firing = this.firing.then(() => this.tick());
+        }, interval);
+        // Don't keep the worker process alive solely for the renew timer.
+        this.timer.unref();
+    }
+    /** Stop renewing and drain any in-flight renew. Idempotent. */
+    async stop() {
+        this.stopped = true;
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.firing.catch(() => undefined);
+    }
+    /** Whether the lease was definitively lost (the orchestrator may read this to shape the outcome). */
+    isLost() {
+        return this.lost;
+    }
+    /** True once the renewer should no longer act. A method (re-evaluated after an `await`) so `stop()`
+     *  can flip `stopped` mid-tick. */
+    done() {
+        return this.stopped || this.lost;
+    }
+    async tick() {
+        if (this.done())
+            return;
+        let held;
+        try {
+            held = await this.deps.renew();
+        }
+        catch (err) {
+            // A transient renew failure must NOT kill a live run — log and let the next tick retry while
+            // the current lease still has headroom.
+            log.warn("lease_renew_failed", {
+                runId: this.deps.runId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return;
+        }
+        if (held || this.done())
+            return;
+        this.lost = true;
+        log.info("run_lease_lost", { runId: this.deps.runId });
+        this.deps.onLost();
+    }
+}

package/dist/runtime/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/main.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: Apache-2.0
+// Process entrypoint for one run: `node .../runtime/main.js` with the platform env contract
+// (RUN_ID + BOARDWALK_CONTROL_PLANE_URL + BOARDWALK_RUN_TOKEN [+ BOARDWALK_API_KEY]). Used by
+// the Boardwalk-hosted Fargate container AND spawned per-run by the self-hosted daemon —
+// one worker, two homes (docs/RUNNER_BROKER.md §6). Import `./index.js` for the library.
+import { main } from "./index.js";
+void main();

package/dist/runtime/phase_tracker.d.ts

@@ -0,0 +1,26 @@
+import type { PhaseOptions } from "@boardwalk-labs/workflow/runtime";
+import type { TurnEventSink } from "./agent/events.js";
+export type PhaseCloseStatus = "completed" | "failed" | "cancelled";
+export interface PhaseTrackerOptions {
+    /** The run's shared event emitter — phases ride the one ordered stream. */
+    sink: TurnEventSink;
+}
+/**
+ * Tracks the author-visible `phase("...")` marker for live run details. v1 wire semantics: a
+ * `phase` event is a MARKER — everything after it belongs to that phase until the next marker or
+ * run end (no phase_completed/failed events on the wire; consumers derive spans from positions).
+ * This is observability only: it never checkpoints JS execution or replays/skips user code.
+ */
+export declare class PhaseTracker {
+    private readonly sink;
+    private readonly storage;
+    private readonly seenIds;
+    private current;
+    private seq;
+    constructor(opts: PhaseTrackerOptions);
+    set(name: string, opts: PhaseOptions | undefined): void;
+    /** v1 phases are markers — nothing to emit at close; clear the current span. */
+    close(_status: PhaseCloseStatus): void;
+    capture(): string | null;
+    runInPhase<T>(phaseId: string | null, fn: () => Promise<T>): Promise<T>;
+}

package/dist/runtime/phase_tracker.js

@@ -0,0 +1,45 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { AppError, ErrorCode } from "./support/index.js";
+/**
+ * Tracks the author-visible `phase("...")` marker for live run details. v1 wire semantics: a
+ * `phase` event is a MARKER — everything after it belongs to that phase until the next marker or
+ * run end (no phase_completed/failed events on the wire; consumers derive spans from positions).
+ * This is observability only: it never checkpoints JS execution or replays/skips user code.
+ */
+export class PhaseTracker {
+    sink;
+    storage = new AsyncLocalStorage();
+    seenIds = new Set();
+    current = null;
+    seq = 0;
+    constructor(opts) {
+        this.sink = opts.sink;
+    }
+    set(name, opts) {
+        const trimmed = name.trim();
+        if (trimmed.length === 0) {
+            throw new AppError(ErrorCode.VALIDATION_FAILED, "Phase name must not be empty");
+        }
+        // Use the caller's id only when it's a non-empty string after trimming; an empty trim falls
+        // back to a generated id (so `??` would be wrong here — it wouldn't catch `""`).
+        const trimmedId = opts?.id?.trim();
+        const id = trimmedId !== undefined && trimmedId !== "" ? trimmedId : `phase-${String(this.seq + 1)}`;
+        if (this.seenIds.has(id)) {
+            throw new AppError(ErrorCode.VALIDATION_FAILED, `Phase id already used: ${id}`);
+        }
+        this.seq += 1;
+        this.seenIds.add(id);
+        this.current = { id, name: trimmed };
+        this.sink.emit({ kind: "phase", name: trimmed, id });
+    }
+    /** v1 phases are markers — nothing to emit at close; clear the current span. */
+    close(_status) {
+        this.current = null;
+    }
+    capture() {
+        return this.current?.id ?? null;
+    }
+    runInPhase(phaseId, fn) {
+        return this.storage.run(phaseId, fn);
+    }
+}

package/dist/runtime/program_log_capture.d.ts

@@ -0,0 +1,20 @@
+import type { TurnEventSink } from "./agent/events.js";
+export type LogStream = "stdout" | "stderr";
+/**
+ * Patch the global console so each call is forwarded to the original AND handed (formatted) to
+ * `sink`. Returns a restore function — ALWAYS call it (the worker runs `restore()` in a finally).
+ */
+export declare function captureConsole(sink: (stream: LogStream, text: string) => void): () => void;
+export interface ProgramLogSinkOptions {
+    /** The run's shared event emitter — program logs ride the one ordered stream (`log` channel). */
+    sink: TurnEventSink;
+    /** Stop emitting after this many frames (the rest still print to CloudWatch). Default 10_000. */
+    maxFrames?: number;
+    /** Truncate a single line longer than this many chars. Default 8 KiB. */
+    maxLineLength?: number;
+}
+/**
+ * Build the sink `captureConsole` feeds: turn each formatted console line into a v1
+ * `program_output` event (best-effort). Caps + truncates to stay efficient.
+ */
+export declare function createProgramLogSink(opts: ProgramLogSinkOptions): (stream: LogStream, text: string) => void;

package/dist/runtime/program_log_capture.js

@@ -0,0 +1,79 @@
+// Capture a workflow program's console output as run-events, so a plain `console.log` program shows
+// up in the run's activity tail (not just the worker's CloudWatch logs).
+//
+// Boundary: we patch the GLOBAL `console` only for the duration of the program body. The worker's
+// own structured logger (Powertools) captured its console reference at construction (module load,
+// before the program runs), so its logs are NOT captured here — only the program's `console.*`,
+// which resolves the global at call time. Each call is still forwarded to the original console (so
+// it also lands in CloudWatch), then formatted and handed to the sink.
+//
+// Performance: lines ride the run's shared event emitter (→ the batched BrokerEventPublisher the
+// run-event path uses), so logging is off the per-line HTTP hot path. We cap total frames + truncate
+// huge lines so a runaway `console.log` loop can't flood Redis/S3/the broker. Frames are v1
+// `program_output` events (`log` channel) interleaved on the run's single ordered cursor stream.
+import { format } from "node:util";
+/** `console` methods mapped to a stream. log/info/debug → stdout; warn/error → stderr. */
+const STREAM_BY_METHOD = {
+    log: "stdout",
+    info: "stdout",
+    debug: "stdout",
+    warn: "stderr",
+    error: "stderr",
+};
+/**
+ * Patch the global console so each call is forwarded to the original AND handed (formatted) to
+ * `sink`. Returns a restore function — ALWAYS call it (the worker runs `restore()` in a finally).
+ */
+export function captureConsole(sink) {
+    const console_ = globalThis.console;
+    const originals = {};
+    for (const [method, stream] of Object.entries(STREAM_BY_METHOD)) {
+        const original = console_[method];
+        if (typeof original !== "function")
+            continue;
+        originals[method] = original;
+        console_[method] = (...args) => {
+            original.apply(console_, args); // still print to the container stdout (CloudWatch)
+            try {
+                sink(stream, format(...args));
+            }
+            catch {
+                // best-effort — a telemetry hiccup must never break the program's own logging
+            }
+        };
+    }
+    return () => {
+        for (const [method, original] of Object.entries(originals)) {
+            console_[method] = original;
+        }
+    };
+}
+const DEFAULT_MAX_FRAMES = 10_000;
+const DEFAULT_MAX_LINE = 8 * 1024;
+/**
+ * Build the sink `captureConsole` feeds: turn each formatted console line into a v1
+ * `program_output` event (best-effort). Caps + truncates to stay efficient.
+ */
+export function createProgramLogSink(opts) {
+    const maxFrames = opts.maxFrames ?? DEFAULT_MAX_FRAMES;
+    const maxLine = opts.maxLineLength ?? DEFAULT_MAX_LINE;
+    let frames = 0;
+    let truncationNoticeSent = false;
+    return (stream, text) => {
+        if (frames >= maxFrames) {
+            if (!truncationNoticeSent) {
+                // Emit one truncation notice, then go quiet (still prints to CloudWatch above).
+                truncationNoticeSent = true;
+                opts.sink.emit({
+                    kind: "program_output",
+                    stream: "stderr",
+                    text: "… console output truncated (too many lines)",
+                });
+            }
+            return;
+        }
+        const line = text.length > maxLine ? `${text.slice(0, maxLine)}… (truncated)` : text;
+        frames += 1;
+        opts.sink.emit({ kind: "program_output", stream, text: line });
+    };
+}