@boardwalk-labs/runner 0.1.2

package/dist/runtime/recording_secret_resolver.js

@@ -0,0 +1,22 @@
+// RecordingSecretResolver — the redaction feeder (MASTER_SPEC §12, plan #9).
+//
+// Decorates any SecretResolver so EVERY value a run resolves — whether the workflow program asked
+// via `secrets.get(name)` or a tool asked via `ctx.secrets.resolve(ref)` — is recorded into the
+// run's SecretRedactor. The leaf executor then scrubs those known values out of all LLM-bound
+// content. Wrapping at the resolver level means there is exactly one chokepoint: a value cannot be
+// resolved without becoming redactable.
+//
+// A failed resolve (FORBIDDEN/NOT_FOUND) records nothing — the error propagates unchanged.
+export class RecordingSecretResolver {
+    inner;
+    redactor;
+    constructor(inner, redactor) {
+        this.inner = inner;
+        this.redactor = redactor;
+    }
+    async resolve(ref) {
+        const value = await this.inner.resolve(ref);
+        this.redactor.record(value);
+        return value;
+    }
+}

package/dist/runtime/run_abort.d.ts

@@ -0,0 +1,16 @@
+/** Why a run was aborted mid-flight. Extensible — user-initiated cancel will add to this.
+ *  `lease_lost`: another worker reclaimed this run (our lease expired + a sweep re-dispatched it),
+ *  so we must stop WITHOUT finalizing — the new owner owns the terminal write. */
+export type AbortReason = "credit_exhausted" | "cancelled" | "lease_lost";
+/** Thrown by WorkflowHost hooks once the run's AbortSignal has fired, so the program unwinds. A plain
+ *  Error subclass (no AppError/model coupling) carrying the machine-readable reason. */
+export declare class RunAbortedError extends Error {
+    readonly reason: AbortReason;
+    constructor(reason: AbortReason);
+}
+/** The reason an aborted signal carries (set via `controller.abort(new RunAbortedError(reason))`), or
+ *  null when the signal isn't aborted / wasn't aborted with a RunAbortedError. */
+export declare function abortReason(signal: AbortSignal): AbortReason | null;
+/** Throw if the signal has already aborted — the guard every WorkflowHost hook calls at entry. Re-uses
+ *  the signal's own RunAbortedError when present, so the reason propagates verbatim. */
+export declare function throwIfAborted(signal: AbortSignal | undefined): void;

package/dist/runtime/run_abort.js

@@ -0,0 +1,38 @@
+// run_abort — the provider-agnostic cooperative-cancellation substrate for a run (docs/RUNNER_BROKER.md
+// §15 credit watching; the foundation user-initiated cancel will reuse).
+//
+// The cancellation primitive is a Web-standard `AbortSignal` — NOT a Strands/model concept. The worker
+// owns one `AbortController` per run session; a watcher (credit, later user-cancel) calls
+// `controller.abort(new RunAbortedError(reason))`. The WorkflowHost honors that signal at every hook
+// boundary (`agent`/`sleep`/`workflows.call`/…), unwinding the program. The ONLY place that translates
+// the signal into a model-specific stop is the Strands leaf (signal → `agent.cancel()`); a future
+// non-Strands leaf honors the SAME `AbortSignal` its own way. So nothing here, in the host, or in the
+// program-facing SDK depends on the model backend.
+//
+// `signal.aborted` is AUTHORITATIVE at the orchestrator: a program that catches RunAbortedError and
+// keeps going still stops, because every subsequent host hook re-throws and the orchestrator finalizes
+// the run terminal based on the signal regardless of how the program returned.
+/** Thrown by WorkflowHost hooks once the run's AbortSignal has fired, so the program unwinds. A plain
+ *  Error subclass (no AppError/model coupling) carrying the machine-readable reason. */
+export class RunAbortedError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Run aborted: ${reason}`);
+        this.reason = reason;
+        this.name = "RunAbortedError";
+    }
+}
+/** The reason an aborted signal carries (set via `controller.abort(new RunAbortedError(reason))`), or
+ *  null when the signal isn't aborted / wasn't aborted with a RunAbortedError. */
+export function abortReason(signal) {
+    const r = signal.reason;
+    return r instanceof RunAbortedError ? r.reason : null;
+}
+/** Throw if the signal has already aborted — the guard every WorkflowHost hook calls at entry. Re-uses
+ *  the signal's own RunAbortedError when present, so the reason propagates verbatim. */
+export function throwIfAborted(signal) {
+    if (signal?.aborted === true) {
+        const r = signal.reason;
+        throw r instanceof RunAbortedError ? r : new RunAbortedError("cancelled");
+    }
+}

package/dist/runtime/run_event_emitter.d.ts

@@ -0,0 +1,24 @@
+import type { RunEvent, RunEventBody, RedisPublisher } from "./agent/events.js";
+export interface RunEventEmitterOptions {
+    runId: string;
+    publisher: RedisPublisher;
+    /** The durable store's max cursor at claim (0 ⇒ fresh run). Restart resumes in the next block. */
+    resumeAfterCursor?: number;
+    /** Injected clock for deterministic tests. Defaults to Date.now. */
+    now?: () => number;
+}
+export declare class WorkerRunEventEmitter {
+    private readonly runId;
+    private readonly publisher;
+    private readonly now;
+    private turn;
+    private seq;
+    constructor(opts: RunEventEmitterOptions);
+    /** Stamp + publish a run-level or agent frame. Agent frames pass their turnId. */
+    emit(body: RunEventBody, turnId?: string): RunEvent;
+    /** Restart resume: jump past the previous session's frames (claim carries the store max). */
+    resumeAfter(maxCursor: number): void;
+    /** Open a new agent stride block and emit its opening `turn_started` frame (built by the caller,
+     *  which names the leaf). */
+    beginTurn(turnId: string, started: RunEventBody): void;
+}

package/dist/runtime/run_event_emitter.js

@@ -0,0 +1,63 @@
+// WorkerRunEventEmitter — the run's SINGLE event envelope counter, engine-parity
+// (boardwalk-labs/boardwalk supervisor semantics):
+//
+//   * One shared `{turn, seq}` per run session. Every emit bumps `seq` (1-based);
+//     `cursor = makeCursor(turn, seq)` is run-globally monotonic.
+//   * `beginTurn(turnId)` opens a new agent stride block: `turn += 1`, `seq = 0`, then emits
+//     the block's opening `turn_started` frame.
+//   * Run-level frames (run_status / phase / output / program_output) carry `turnId = runId`
+//     and ride the CURRENT block — there is no separate "program band", which is what keeps
+//     cursors monotonic when program logs interleave with agent turns.
+//   * Resume (crash-restart re-runs the program from the top): the claim response carries the
+//     store's max cursor; the emitter starts in the NEXT stride block so new frames always
+//     order after the previous session's.
+//
+// Frames publish as the stored row shape `{cursor, event}` (JSON) on `run:<id>` — the broker's
+// telemetry endpoint fans out + appends verbatim. Publishing is best-effort (telemetry must
+// never fail a run); the publisher (BrokerEventPublisher) batches.
+import { makeCursor, TURN_CURSOR_STRIDE } from "./agent/events.js";
+export class WorkerRunEventEmitter {
+    runId;
+    publisher;
+    now;
+    turn;
+    seq;
+    constructor(opts) {
+        this.runId = opts.runId;
+        this.publisher = opts.publisher;
+        this.now = opts.now ?? Date.now;
+        const max = opts.resumeAfterCursor ?? 0;
+        this.turn = max > 0 ? Math.floor(max / TURN_CURSOR_STRIDE) + 1 : 0;
+        this.seq = 0;
+    }
+    /** Stamp + publish a run-level or agent frame. Agent frames pass their turnId. */
+    emit(body, turnId) {
+        this.seq += 1;
+        const event = {
+            ...body,
+            runId: this.runId,
+            turnId: turnId ?? this.runId,
+            seq: this.seq,
+            t: this.now(),
+        };
+        const cursor = makeCursor(this.turn, this.seq);
+        this.publisher
+            .publish(`run:${this.runId}`, JSON.stringify({ cursor, event }))
+            .catch(() => undefined); // best-effort; the publisher logs its own failures
+        return event;
+    }
+    /** Restart resume: jump past the previous session's frames (claim carries the store max). */
+    resumeAfter(maxCursor) {
+        if (maxCursor > 0) {
+            this.turn = Math.floor(maxCursor / TURN_CURSOR_STRIDE) + 1;
+            this.seq = 0;
+        }
+    }
+    /** Open a new agent stride block and emit its opening `turn_started` frame (built by the caller,
+     *  which names the leaf). */
+    beginTurn(turnId, started) {
+        this.turn += 1;
+        this.seq = 0;
+        this.emit(started, turnId);
+    }
+}

package/dist/runtime/runner_control_client.d.ts

@@ -0,0 +1,184 @@
+import type { McpTokenResult } from "@boardwalk-labs/engine/core";
+import type { Run } from "./wire/run.js";
+import { type JournalKind, type JournalLookup, type JournalSeam, type SuspendSignal } from "./suspension.js";
+import type { WebSearchOutput } from "./tools/web_search.js";
+import type { ArtifactCommitInput, ArtifactPresignInput, ArtifactPresignResult, ArtifactSignResult, ArtifactSummary, ArtifactWriteInput, ArtifactWriteResult } from "./tools/artifacts.js";
+import { type InferenceFrame, type InferenceProxyRequest } from "./wire/inference_proxy.js";
+export interface RunnerControlClientConfig {
+    /** Base URL of the Runner Control API (BOARDWALK_CONTROL_PLANE_URL). */
+    baseUrl: string;
+    /** The per-run bearer token (BOARDWALK_RUN_TOKEN). */
+    runToken: string;
+    /** The run this client (and token) is bound to. */
+    runId: string;
+    /** Injected fetch (defaults to global fetch). */
+    fetchImpl?: typeof fetch;
+}
+/** The pinned program's download reference (the worker fetches + verifies + extracts it). */
+export interface BrokerProgram {
+    entry: string;
+    digest: string;
+    sdkVersion: string;
+    downloadUrl: string;
+}
+export interface BrokerVersion {
+    manifest: unknown;
+    program: BrokerProgram;
+}
+/** The schedule spec the worker sends for `workflows.schedule` (exactly one of cron/rate/at). `at`
+ *  is a ms epoch or ISO string — a Date is serialized to ISO by the host before it reaches here. */
+export interface BrokerScheduleSpec {
+    cron?: string;
+    rate?: string;
+    at?: string | number;
+    timezone?: string;
+    idempotencyKey?: string;
+}
+/** A child run's terminal-relevant state, as returned by the `children` create/poll endpoints. */
+export interface BrokerChild {
+    childRunId: string;
+    status: string;
+    output: unknown;
+}
+export declare class RunnerControlClient {
+    private readonly cfg;
+    private readonly base;
+    private readonly fetchImpl;
+    constructor(cfg: RunnerControlClientConfig);
+    /** Claim the run's lease. Returns the run on success, or null when it isn't claimable (409 —
+     *  another worker has it, or it isn't pending), which the worker treats as "claim lost". */
+    claim(workerId: string, leaseSeconds: number): Promise<{
+        run: Run;
+        lastEventCursor: number;
+        lastJournalSeq: number;
+    } | null>;
+    /** Heartbeat: extend our lease so a long run isn't reclaimed mid-flight. Returns the new
+     *  `leaseUntil`, or null when the lease was lost (409 — another worker reclaimed the run), which
+     *  the worker treats as "stop". */
+    renewLease(workerId: string, leaseSeconds: number): Promise<number | null>;
+    /** Mark the run terminal. `workerId` lets the broker reject a finalize from a DISPLACED worker (one
+     *  whose lease expired and whose run was reclaimed + re-dispatched to a new owner), so a
+     *  hung/partitioned worker that later recovers can't clobber the live run or revive a terminal one. */
+    finalize(status: "completed" | "failed", output: unknown, workerId: string): Promise<void>;
+    /** Look up a durable-seam journal entry by its seq (docs/SUSPENSION.md), or null on a replay miss
+     *  (404). The broker joins a parked agent leaf's answers into the result server-side. */
+    journalGet(seq: number): Promise<JournalLookup | null>;
+    /** Record a RESOLVED seam result (idempotent on the run + seq server-side; a resolved entry is
+     *  immutable). The broker writes the memoized value the next replay returns. */
+    journalPut(entry: {
+        seq: number;
+        kind: JournalKind;
+        fingerprint: string;
+        label: string;
+        result: unknown;
+    }): Promise<void>;
+    /** Persist a durable SUSPENSION: the broker records the wake condition (a pending/suspended journal
+     *  entry + a human-input request row for HITL, or the wake time for a long sleep), flips the run to
+     *  its suspended status, and releases the lease — transactionally. No finalize; a wake re-dispatches. */
+    suspend(signal: SuspendSignal, workerId: string): Promise<void>;
+    /** The {@link JournalSeam} the worker host reads/writes — a thin adapter over the broker methods. */
+    journalSeam(): JournalSeam;
+    /** Fetch the run's pinned manifest + program source, or null when the version is missing (404). */
+    getVersion(): Promise<BrokerVersion | null>;
+    /** Book a runtime-seconds DELTA (the worker's RuntimeFlusher → broker). `identifier` makes a
+     *  retried/duplicate flush idempotent; distinct per-flush ids sum into the run's runtime total. */
+    reportUsage(runtimeSeconds: number, identifier: string): Promise<void>;
+    /** Report a token-usage delta for incremental in-run metering (the usage flusher → broker). The
+     *  broker gates on the run's per-connection `billed_by_boardwalk` server-side + meters to Stripe;
+     *  `identifier` makes a retried/duplicate flush idempotent. Satisfies {@link TokenUsageReporter}. */
+    meterTokens(input: {
+        inputTokens: number;
+        outputTokens: number;
+        model?: string;
+        identifier: string;
+        /** Cache-served input tokens — display-only annotation (omitted when zero/unknown). */
+        cachedReadTokens?: number;
+        cachedWriteTokens?: number;
+    }): Promise<void>;
+    /** Check whether the run's org is still funded (the CreditWatcher → broker). The broker reads the
+     *  live Stripe balance server-side; `false` means out of credit (the watcher then aborts the run). */
+    checkCredit(): Promise<boolean>;
+    /** Check whether the run has been asked to cancel (the CancelWatcher → broker). `true` once the user
+     *  cancelled the run (the broker flipped it to `cancelling`/`cancelled`); the watcher then aborts the
+     *  run. Brokered because the runner holds no DB/Redis — this replaces the unreachable Redis channel. */
+    checkCancelled(): Promise<boolean>;
+    /** Mint a presigned GET URL to restore this workflow's last `/workspace` snapshot (workspace
+     *  persistence, §5). `null` when the run isn't eligible (not opted-in, or self-hosted). */
+    workspaceHydrateUrl(): Promise<string | null>;
+    /** Mint a presigned PUT URL to snapshot this workflow's `/workspace` (the worker uploads the tarball
+     *  straight to S3). `null` when the run isn't eligible. `sizeBytes` is the archive's on-disk size
+     *  (the worker tars BEFORE requesting the URL) — the broker records it for the org storage counter +
+     *  daily meter; the snapshot overwrites one per-workflow key, so it's the workflow's full footprint. */
+    workspacePersistUrl(sizeBytes: number): Promise<{
+        url: string;
+        contentType: string;
+    } | null>;
+    /** Download bytes from a presigned S3 URL (workspace hydrate). `null` on 404 (no snapshot yet —
+     *  e.g. the workflow's first run); throws on any other non-2xx. Goes straight to S3, not the broker. */
+    downloadBytes(url: string): Promise<Uint8Array | null>;
+    /** Request an OIDC run id-token for `audience` (§OIDC). The broker mints an asymmetric,
+     *  third-party-verifiable token (gated server-side on `permissions.id_token: "write"`) — used to
+     *  federate into the org's OWN cloud (AWS/GCP). DIFFERENT from this client's run token. */
+    requestOidcToken(audience: string): Promise<{
+        token: string;
+        expiresIn: number;
+    }>;
+    /** Publish a batch of live agent-event frames (the SSE live-tail source) — the broker publishes
+     *  them to the run's Redis channel server-side, so the runner holds no Redis credential. */
+    publishTelemetry(frames: string[]): Promise<void>;
+    /** Store a run artifact through the broker (which holds the S3 credential + neutralizes the served
+     *  content type server-side). Returns the catalog id + a signed download URL. */
+    writeArtifact(input: ArtifactWriteInput): Promise<ArtifactWriteResult>;
+    /** Phase 1 of the LARGE-artifact path (docs/RUNNER_BROKER.md §7 step 4): presign an S3 PUT. The
+     *  broker derives the S3 key + neutralizes/pins the served content type; it returns the upload URL +
+     *  required headers + the `s3Key` to echo back at commit. No catalog row exists yet. */
+    presignArtifact(input: ArtifactPresignInput): Promise<ArtifactPresignResult>;
+    /** Upload bytes to a presigned S3 URL (the large-artifact path). The `headers` come from the
+     *  presign response and MUST be sent verbatim — the content type is pinned into the signature, so
+     *  S3 rejects a mismatch. This call goes straight to S3, not the broker. */
+    uploadBytes(url: string, headers: Record<string, string>, body: Uint8Array): Promise<void>;
+    /** Phase 2 of the LARGE-artifact path: register the catalog row AFTER the bytes have landed in S3
+     *  (called only on a successful {@link uploadBytes}, so a failed upload leaves no dangling row). The
+     *  broker re-validates the run prefix + re-neutralizes the content type, then returns the catalog id
+     *  + a signed download URL. */
+    commitArtifact(input: ArtifactCommitInput): Promise<ArtifactWriteResult>;
+    /** List the artifacts this run has produced. */
+    listArtifacts(): Promise<ArtifactSummary[]>;
+    /** Mint a fresh signed download URL for one of this run's artifacts. */
+    signArtifactUrl(artifactId: string, ttlSeconds: number): Promise<ArtifactSignResult>;
+    /** Resolve an org secret the run's manifest allows (the program's `secrets.get`). The broker
+     *  enforces the allowlist + returns the value; a forbidden/missing secret surfaces as a throw. */
+    resolveSecret(name: string): Promise<string>;
+    /** Broker a short-lived OAuth bearer for a hosted MCP server (the engine's `mcpToken` hook, called
+     *  reactively after a 401). The broker vends from the org's connection vault and re-checks egress.
+     *  A 403 (no active connection / non-allowlisted host) degrades to `{ accessToken: null, hint }` so
+     *  the engine surfaces a clean failure instead of a thrown 500 mid-run; the token is never logged. */
+    mcpToken(serverUrl: string, invalidateToken?: string): Promise<McpTokenResult>;
+    /** Proxy a web_search through the broker (which holds the Tavily key) — the runner sends the
+     *  query, the broker calls Tavily and returns the results. */
+    webSearch(input: unknown): Promise<WebSearchOutput>;
+    /** Create (or idempotently re-attach to) a child run for `workflows.call`. */
+    startChild(slug: string, input: unknown): Promise<BrokerChild>;
+    /** Provision a durable schedule for `workflows.schedule`; returns the new schedule's id. */
+    scheduleWorkflow(slug: string, input: unknown, spec: BrokerScheduleSpec): Promise<string>;
+    /** Poll a child run's status/output, or null when it isn't this run's child (404). */
+    getChild(childRunId: string): Promise<{
+        id: string;
+        status: string;
+        output: unknown;
+    } | null>;
+    /**
+     * Proxy one model turn through the broker (docs/RUNNER_BROKER.md §4 — Inference). POSTs the
+     * neutral conversation; the broker resolves the REAL model server-side (the runner holds no model
+     * creds), invokes the matching engine adapter, and relays the model's stream back as NDJSON
+     * `InferenceFrame`s (delta / result / error). Yields each frame; the engine-backed leaf surfaces
+     * deltas via `providerIo.onDelta`, takes the terminal `result` as the turn, and throws on `error`.
+     *
+     * Backs {@link InferenceProxyTransport} (inference_transport.ts) — the model swap is invisible to
+     * the engine loop, which keeps the runner provider-agnostic (the broker owns model invocation). A
+     * non-200 (a failure BEFORE the stream began) throws the broker's already-classified message.
+     */
+    streamInference(req: InferenceProxyRequest): AsyncGenerator<InferenceFrame, void, undefined>;
+    private url;
+    private headers;
+}