@boardwalk-labs/runner 0.1.2

package/dist/runtime/broker_child_dispatcher.js

@@ -0,0 +1,88 @@
+// BrokerChildDispatcher — the broker-backed `workflows.call` (docs/RUNNER_BROKER.md). The host's
+// ChildDispatcher under the broker model: instead of touching the DB/SQS directly (the
+// WorkerChildDispatcher path), it asks the Runner Control API to create the child (resolve + the
+// `callable_by` gate + idempotent re-attach happen server-side) and then HOLDS the parent task,
+// polling the child to terminal over the run token. Same hold-and-poll shape as WorkerChildDispatcher
+// — only the data source changes (broker HTTP, not the repos).
+import { AppError, ErrorCode, createLogger } from "./support/index.js";
+import { throwIfAborted } from "./run_abort.js";
+const log = createLogger("BrokerChildDispatcher");
+const TERMINAL_CHILD_STATUSES = new Set(["completed", "failed", "cancelled"]);
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+export class BrokerChildDispatcher {
+    deps;
+    sleep;
+    pollIntervalMs;
+    constructor(deps) {
+        this.deps = deps;
+        this.sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        this.pollIntervalMs = deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    }
+    /** Create (or re-attach to) the child, then hold + poll to terminal and return its output. An
+     *  abort (`signal`) stops the hold within one poll interval and throws RunAbortedError. */
+    async call(slug, input, _opts, signal) {
+        throwIfAborted(signal);
+        const child = await this.deps.client.startChild(slug, input);
+        if (TERMINAL_CHILD_STATUSES.has(child.status)) {
+            return this.childOutput(slug, child.childRunId, child.status, child.output);
+        }
+        return this.pollToCompletion(slug, child.childRunId, signal);
+    }
+    /** Start (or idempotently re-attach to) the child and resolve its CURRENT state — no hold. The
+     *  durable callWorkflow seam decides whether to suspend (non-terminal) or return (terminal). */
+    async start(slug, input, _opts, signal) {
+        throwIfAborted(signal);
+        const child = await this.deps.client.startChild(slug, input);
+        return { childRunId: child.childRunId, status: child.status, output: child.output };
+    }
+    /** Poll a child's current state by id (the resume path), or null when it isn't this run's child. */
+    async poll(childRunId) {
+        const child = await this.deps.client.getChild(childRunId);
+        return child === null
+            ? null
+            : { childRunId: child.id, status: child.status, output: child.output };
+    }
+    /** Fire-and-forget: create (or re-attach to) the child and return its id without holding. */
+    async run(slug, input, _opts) {
+        const child = await this.deps.client.startChild(slug, input);
+        return child.childRunId;
+    }
+    /** Provision a durable schedule via the broker; returns the new schedule's id. A `Date` `at` is
+     *  normalized to an ISO string (the broker spec carries string | number, not Date). */
+    async schedule(slug, input, opts) {
+        const spec = {};
+        if (opts.cron !== undefined)
+            spec.cron = opts.cron;
+        if (opts.rate !== undefined)
+            spec.rate = opts.rate;
+        if (opts.at !== undefined)
+            spec.at = opts.at instanceof Date ? opts.at.toISOString() : opts.at;
+        if (opts.timezone !== undefined)
+            spec.timezone = opts.timezone;
+        if (opts.idempotencyKey !== undefined)
+            spec.idempotencyKey = opts.idempotencyKey;
+        return await this.deps.client.scheduleWorkflow(slug, input, spec);
+    }
+    async pollToCompletion(slug, childRunId, signal) {
+        for (;;) {
+            throwIfAborted(signal);
+            const child = await this.deps.client.getChild(childRunId);
+            if (child === null) {
+                throw new AppError(ErrorCode.INTERNAL_ERROR, `Called workflow's child run ${childRunId} vanished`);
+            }
+            if (TERMINAL_CHILD_STATUSES.has(child.status)) {
+                return this.childOutput(slug, child.id, child.status, child.output);
+            }
+            await this.sleep(this.pollIntervalMs);
+            // Re-check after the wait so an abort during the inter-poll sleep stops within one interval.
+            throwIfAborted(signal);
+        }
+    }
+    /** A completed child returns its output; a failed/cancelled child rejects the parent's await. */
+    childOutput(slug, childRunId, status, output) {
+        if (status === "completed")
+            return output;
+        log.warn("child_workflow_nonterminal_output", { slug, childRunId, status });
+        throw new AppError(ErrorCode.INTERNAL_ERROR, `Called workflow "${slug}" ${status} (run ${childRunId})`, { childRunId, status });
+    }
+}

package/dist/runtime/broker_event_publisher.d.ts

@@ -0,0 +1,25 @@
+import type { RedisPublisher } from "./agent/events.js";
+export interface BrokerEventPublisherOptions {
+    /** Ship a batch of frames to the broker (RunnerControlClient.publishTelemetry). */
+    send: (frames: string[]) => Promise<void>;
+    /** Flush once this many frames are buffered (default 16). */
+    maxBatch?: number;
+    /** Flush a partial batch after this long since the first buffered frame (default 200ms). */
+    maxDelayMs?: number;
+}
+export declare class BrokerEventPublisher implements RedisPublisher {
+    private readonly send;
+    private readonly maxBatch;
+    private readonly maxDelayMs;
+    private buffer;
+    private timer;
+    constructor(opts: BrokerEventPublisherOptions);
+    /** RedisPublisher contract: buffer the frame; flush on size, else arm the delay timer. The
+     *  `channel` is ignored — the broker derives it from the run token (the run's own channel). The
+     *  return value (subscriber count) is unused by the run-event emitter, so we resolve 0. */
+    publish(_channel: string, message: string): Promise<number>;
+    /** Ship whatever is buffered now (and cancel any pending timer). Errors are logged, not thrown. */
+    flush(): Promise<void>;
+    /** Drain the final batch at run end (the worker calls this in cleanup). */
+    close(): Promise<void>;
+}

package/dist/runtime/broker_event_publisher.js

@@ -0,0 +1,69 @@
+// BrokerEventPublisher — a `RedisPublisher` that ships the agent event-stream through the broker
+// instead of publishing to Redis directly (docs/RUNNER_BROKER.md §4 — Telemetry).
+//
+// The run-event live channel is a per-event `redis.publish(run:<id>, frame)`. Under the broker the
+// runner holds no Redis credential, so this stand-in BUFFERS frames and POSTs them in batches to the
+// Runner Control API's `/telemetry` endpoint; the broker publishes each to the run's Redis channel
+// server-side. Batching keeps it off the per-token-delta HTTP-call hot path (a turn can emit one
+// frame per token); the SSE consumer orders by the frame's `cursor`, so out-of-order batch delivery
+// is harmless.
+//
+// Best-effort, exactly like the direct Redis publish it replaces: a failed flush is logged, never
+// thrown — a telemetry hiccup must not kill the agent turn (the durable store is the durability
+// guarantee, once it lands). The worker calls `close()` in its cleanup to drain the final batch.
+import { createLogger } from "./support/index.js";
+const log = createLogger("BrokerEventPublisher");
+const DEFAULT_MAX_BATCH = 16;
+const DEFAULT_MAX_DELAY_MS = 200;
+export class BrokerEventPublisher {
+    send;
+    maxBatch;
+    maxDelayMs;
+    buffer = [];
+    timer = null;
+    constructor(opts) {
+        this.send = opts.send;
+        this.maxBatch = opts.maxBatch ?? DEFAULT_MAX_BATCH;
+        this.maxDelayMs = opts.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    }
+    /** RedisPublisher contract: buffer the frame; flush on size, else arm the delay timer. The
+     *  `channel` is ignored — the broker derives it from the run token (the run's own channel). The
+     *  return value (subscriber count) is unused by the run-event emitter, so we resolve 0. */
+    publish(_channel, message) {
+        this.buffer.push(message);
+        if (this.buffer.length >= this.maxBatch) {
+            void this.flush();
+        }
+        else if (this.timer === null) {
+            this.timer = setTimeout(() => {
+                void this.flush();
+            }, this.maxDelayMs);
+            this.timer.unref();
+        }
+        return Promise.resolve(0);
+    }
+    /** Ship whatever is buffered now (and cancel any pending timer). Errors are logged, not thrown. */
+    async flush() {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (this.buffer.length === 0)
+            return;
+        const batch = this.buffer;
+        this.buffer = [];
+        try {
+            await this.send(batch);
+        }
+        catch (err) {
+            log.warn("telemetry_flush_failed", {
+                frames: batch.length,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /** Drain the final batch at run end (the worker calls this in cleanup). */
+    async close() {
+        await this.flush();
+    }
+}

package/dist/runtime/broker_tool_host.d.ts

@@ -0,0 +1,49 @@
+import type { ToolHost } from "@boardwalk-labs/engine/core";
+import type { WebSearchInput, WebSearchOutput } from "./tools/web_search.js";
+import type { ArtifactStore } from "./tools/artifacts.js";
+/** Socket-safety ceiling on the RAW bytes read off a `webfetch` response, so a hostile URL can't
+ *  stream an unbounded body into the worker. This bounds MEMORY, not what the model sees (the
+ *  model-facing content is extracted + capped separately — see DEFAULT_FETCH_CONTENT_CHARS). The
+ *  engine's per-call `maxBytes` overrides this when set. */
+export declare const DEFAULT_FETCH_MAX_BYTES: number;
+/** Ceiling on the MODEL-FACING content of a `webfetch`, in chars, AFTER HTML→text extraction
+ *  (~12K tokens). Raw HTML is mostly `<script>`/`<style>`/markup the model doesn't need and which
+ *  then rides in context for the rest of the loop, so we extract the readable text and cap it. A
+ *  whole 5 MB page used to land in context verbatim; this is the single biggest webfetch token sink. */
+export declare const DEFAULT_FETCH_CONTENT_CHARS = 50000;
+/** The broker surface the web_search + read-artifact paths need (RunnerControlClient satisfies it).
+ *  `webSearch` proxies to Tavily server-side; `signArtifactUrl` + `downloadBytes` back `readArtifact`. */
+export interface ToolHostBroker {
+    webSearch(input: WebSearchInput): Promise<WebSearchOutput>;
+    signArtifactUrl(artifactId: string, ttlSeconds: number): Promise<{
+        signedUrl: string;
+    }>;
+    downloadBytes(url: string): Promise<Uint8Array | null>;
+}
+export interface BrokerToolHostDeps {
+    /** Broker client for web_search + read-artifact signing/download. */
+    broker: ToolHostBroker;
+    /** The artifact store the `artifacts` write/list path already uses (reused verbatim). */
+    artifacts: ArtifactStore;
+    /** Injected fetch for `webfetch` (defaults to global fetch — the proxy is applied by the runtime,
+     *  not here, so a plain global fetch already routes through the egress allowlist). */
+    fetchImpl?: typeof fetch;
+    /** Override the default `webfetch` RAW read cap, in bytes (tests). */
+    maxFetchBytes?: number;
+    /** Override the default `webfetch` model-facing content cap, in chars (tests). */
+    maxFetchContentChars?: number;
+}
+/**
+ * Build the engine `ToolHost` for one run, backed by the broker. Returned as a plain object literal so
+ * each hook closes over the injected deps; the shape matches the engine's optional-method interface
+ * (omitting `lsp` leaves that tool unregistered).
+ */
+export declare function buildBrokerToolHost(deps: BrokerToolHostDeps): ToolHost;
+/**
+ * Reduce an HTML document to readable text: drop non-content elements (script/style/head/etc.),
+ * turn block boundaries into newlines, strip remaining tags, decode common entities, and collapse
+ * whitespace. A pragmatic, dependency-free extractor — NOT a full readability pass (it does not
+ * score main-content vs. nav/ads), but it removes the bulk of the markup/script tokens that would
+ * otherwise flood the model. A heavier readability library could improve precision later.
+ */
+export declare function htmlToText(html: string): string;

package/dist/runtime/broker_tool_host.js

@@ -0,0 +1,240 @@
+// BrokerToolHost — the engine's `ToolHost` (the infrastructure seam for the host-backed built-in
+// coding tools `webfetch` / `http` / `web_search` / `artifacts`) wired over the Runner Credential Broker
+// (docs/RUNNER_BROKER.md). `@boardwalk-labs/engine` registers those three tools ONLY when the leaf's
+// `ToolSetContext.host` provides the backing hook; we supply one here so they light up on hosted
+// runs. Each hook delegates the privileged capability to whoever holds the credential/network/storage
+// — exactly as the broker model requires (security review #1): the untrusted worker holds no Tavily
+// key, no S3 credential, and only reaches the public network through the egress proxy.
+//
+//   web_search → broker /tools/web_search (the broker holds the Tavily key; the worker just forwards
+//                the query + maps the result rows into the engine's WebSearchResult shape).
+//   artifacts  → the existing BrokerArtifactStore (presigned write for large bodies; list + signed
+//                URL + an in-process S3 GET for read).
+//   webfetch   → an in-process fetch FROM the worker. The worker's egress is already gated by the
+//                Squid allowlist proxy (NODE_USE_ENV_PROXY / HTTP(S)_PROXY → egress-proxy boundary);
+//                we never bypass it. http(s)-only, response size-capped, HTML extracted to text.
+//   http       → the same in-process, proxy-gated fetch but with any method/headers/body and the RAW
+//                response (no HTML extraction) — for calling APIs. http(s)-only, response size-capped.
+//
+// LSP is NOT a `ToolHost` hook — it's engine-native (`capabilities.lspService`, supplied per run by
+// the worker's leaf wiring in index.ts), so it isn't this module's concern.
+//
+// Secrets-redaction invariant: every value a host hook returns flows back through the engine loop's
+// Redactor before it can reach model context (the leaf seeds it from the run's recorded secrets), so
+// nothing here can leak a secret. This module holds no provider key of its own.
+/** Socket-safety ceiling on the RAW bytes read off a `webfetch` response, so a hostile URL can't
+ *  stream an unbounded body into the worker. This bounds MEMORY, not what the model sees (the
+ *  model-facing content is extracted + capped separately — see DEFAULT_FETCH_CONTENT_CHARS). The
+ *  engine's per-call `maxBytes` overrides this when set. */
+export const DEFAULT_FETCH_MAX_BYTES = 5 * 1024 * 1024;
+/** Ceiling on the MODEL-FACING content of a `webfetch`, in chars, AFTER HTML→text extraction
+ *  (~12K tokens). Raw HTML is mostly `<script>`/`<style>`/markup the model doesn't need and which
+ *  then rides in context for the rest of the loop, so we extract the readable text and cap it. A
+ *  whole 5 MB page used to land in context verbatim; this is the single biggest webfetch token sink. */
+export const DEFAULT_FETCH_CONTENT_CHARS = 50_000;
+/** TTL for the short-lived signed URL minted to read an artifact's bytes back (`readArtifact`). The
+ *  download happens immediately in-process, so a minute is ample. */
+const READ_ARTIFACT_SIGN_TTL_SECONDS = 60;
+/**
+ * Build the engine `ToolHost` for one run, backed by the broker. Returned as a plain object literal so
+ * each hook closes over the injected deps; the shape matches the engine's optional-method interface
+ * (omitting `lsp` leaves that tool unregistered).
+ */
+export function buildBrokerToolHost(deps) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const maxFetchBytes = deps.maxFetchBytes ?? DEFAULT_FETCH_MAX_BYTES;
+    const maxFetchContentChars = deps.maxFetchContentChars ?? DEFAULT_FETCH_CONTENT_CHARS;
+    return {
+        // web_search → broker /tools/web_search. The engine hands a bare query + optional limit; we map
+        // `limit` onto the domain tool's `max_results` (the broker re-clamps to [1, 20] server-side) and
+        // project the rich WebSearchOutput rows down to the engine's title/url/snippet shape.
+        webSearch: async (query, opts) => {
+            const input = {
+                query,
+                ...(opts?.limit !== undefined ? { max_results: opts.limit } : {}),
+            };
+            const out = await deps.broker.webSearch(input);
+            return out.data.results.map((r) => ({
+                title: r.title,
+                url: r.url,
+                // `snippet` is optional on the engine shape; the domain row always has one (possibly empty).
+                snippet: r.snippet,
+            }));
+        },
+        // artifacts.write → the existing BrokerArtifactStore (small bodies proxy inline; large ones take
+        // the presigned-PUT path). The engine's ArtifactWriteResult is { id, name, url }, so surface the
+        // store's signed download URL as `url`.
+        writeArtifact: async (name, contentType, body, metadata) => {
+            const result = await deps.artifacts.write({
+                name,
+                contentType,
+                // The engine always hands a UTF-8 string for these host-backed writes (it has no binary
+                // channel); the store decodes per `encoding`.
+                body,
+                encoding: "utf8",
+                ...(metadata !== undefined ? { metadata } : {}),
+            });
+            return { id: result.id, name: result.name, url: result.signedUrl };
+        },
+        // artifacts read-back: the engine asks by NAME, so list this run's artifacts, find the most recent
+        // match, mint a short-lived signed URL through the broker, and fetch the bytes in-process. Fails
+        // loud when the name isn't found (so a typo surfaces, never a silent empty read).
+        readArtifact: async (name) => {
+            const artifacts = await deps.artifacts.list();
+            // Newest-first so a re-written name reads the latest version.
+            const match = artifacts
+                .filter((a) => a.name === name)
+                .sort((a, b) => b.createdAt - a.createdAt)[0];
+            if (match === undefined) {
+                throw new Error(`artifact "${name}" not found in this run`);
+            }
+            const { signedUrl } = await deps.broker.signArtifactUrl(match.id, READ_ARTIFACT_SIGN_TTL_SECONDS);
+            const bytes = await deps.broker.downloadBytes(signedUrl);
+            if (bytes === null) {
+                throw new Error(`artifact "${name}" could not be downloaded`);
+            }
+            return Buffer.from(bytes).toString("utf8");
+        },
+        // webfetch → an in-process fetch from the worker. Egress is gated by the Squid allowlist proxy
+        // (NODE_USE_ENV_PROXY in the worker), so this does NOT bypass it. http(s)-only; the body is read
+        // as a size-capped stream so a hostile URL can't exhaust memory.
+        fetchUrl: async (url, opts) => {
+            assertHttpUrl(url);
+            // maxBytes (when the caller sets it) bounds the RAW read; otherwise the socket-safety cap.
+            const rawCap = opts?.maxBytes ?? maxFetchBytes;
+            const res = await fetchImpl(url, { method: "GET", redirect: "follow" });
+            const contentType = res.headers.get("content-type") ?? undefined;
+            const { body: raw, truncated: rawTruncated } = await readCapped(res, rawCap);
+            // Extract readable text from HTML so the model isn't fed script/style/markup boilerplate, then
+            // cap the model-facing content (extraction already shrinks HTML a lot; this bounds the rest).
+            const extracted = isHtmlContentType(contentType) ? htmlToText(raw) : raw;
+            const body = extracted.length > maxFetchContentChars
+                ? extracted.slice(0, maxFetchContentChars)
+                : extracted;
+            const truncated = rawTruncated || body.length < extracted.length;
+            return { status: res.status, contentType, body, truncated };
+        },
+        // http → an in-process fetch from the worker with the model's method/headers/body, egress-gated
+        // by the same Squid allowlist proxy as webfetch (NODE_USE_ENV_PROXY). UNLIKE webfetch it returns
+        // the RAW response (no HTML→text extraction) — `http` is for calling APIs — so it skips the
+        // content-chars cap and only bounds RAW bytes against worker memory.
+        httpRequest: async (req, opts) => {
+            assertHttpUrl(req.url, "http");
+            const rawCap = opts?.maxBytes ?? maxFetchBytes;
+            const res = await fetchImpl(req.url, {
+                method: req.method ?? "GET",
+                redirect: "follow",
+                ...(req.headers !== undefined ? { headers: req.headers } : {}),
+                ...(req.body !== undefined ? { body: req.body } : {}),
+            });
+            const contentType = res.headers.get("content-type") ?? undefined;
+            const { body, truncated } = await readCapped(res, rawCap);
+            return { status: res.status, contentType, body, truncated };
+        },
+    };
+}
+/** Reject anything but http/https up front — `webfetch`/`http` must never reach `file:`, `data:`, or
+ *  other schemes that could read local state or smuggle the proxy. */
+function assertHttpUrl(url, tool = "webfetch") {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`${tool}: invalid URL "${url}"`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(`${tool}: only http(s) URLs are allowed (got "${parsed.protocol}")`);
+    }
+}
+/** Read a response body as UTF-8 text, stopping once `maxBytes` bytes have been consumed. Returns the
+ *  decoded text and whether it was truncated, so a huge document can't exhaust worker memory. Falls
+ *  back to a buffered read (still capped) when the body isn't a stream. */
+async function readCapped(res, maxBytes) {
+    const stream = res.body;
+    if (stream === null) {
+        return { body: "", truncated: false };
+    }
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    const chunks = [];
+    let total = 0;
+    let truncated = false;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const remaining = maxBytes - total;
+            if (value.length > remaining) {
+                chunks.push(value.subarray(0, remaining));
+                total = maxBytes;
+                truncated = true;
+                break;
+            }
+            chunks.push(value);
+            total += value.length;
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+    const body = chunks.map((c) => decoder.decode(c, { stream: true })).join("") + decoder.decode();
+    return { body, truncated };
+}
+/** Whether a content-type names HTML (so we should extract readable text from it). */
+function isHtmlContentType(contentType) {
+    if (contentType === undefined)
+        return false;
+    const ct = contentType.toLowerCase();
+    return ct.includes("text/html") || ct.includes("application/xhtml");
+}
+/**
+ * Reduce an HTML document to readable text: drop non-content elements (script/style/head/etc.),
+ * turn block boundaries into newlines, strip remaining tags, decode common entities, and collapse
+ * whitespace. A pragmatic, dependency-free extractor — NOT a full readability pass (it does not
+ * score main-content vs. nav/ads), but it removes the bulk of the markup/script tokens that would
+ * otherwise flood the model. A heavier readability library could improve precision later.
+ */
+export function htmlToText(html) {
+    let s = html;
+    // Non-content elements, dropped whole (including their contents).
+    s = s.replace(/<(script|style|head|noscript|svg|template)\b[^>]*>[\s\S]*?<\/\1>/gi, " ");
+    s = s.replace(/<!--[\s\S]*?-->/g, " ");
+    // Block-level closers + line breaks become newlines so document structure partly survives.
+    s = s.replace(/<\/(p|div|section|article|header|footer|li|tr|h[1-6]|blockquote|pre)\s*>/gi, "\n");
+    s = s.replace(/<(br|hr)\s*\/?>/gi, "\n");
+    s = s.replace(/<[^>]+>/g, " "); // strip all remaining tags
+    s = decodeHtmlEntities(s);
+    // Collapse intra-line whitespace, trim around newlines, cap blank-line runs.
+    return s
+        .replace(/[ \t\f\v]+/g, " ")
+        .replace(/ *\n */g, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+const NAMED_ENTITIES = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    nbsp: " ",
+};
+/** Decode the handful of HTML entities that show up in extracted prose, plus numeric refs. */
+function decodeHtmlEntities(s) {
+    return s.replace(/&(#x[0-9a-f]+|#\d+|[a-z][a-z0-9]*);/gi, (full, bodyRaw) => {
+        const body = bodyRaw.toLowerCase();
+        if (body.startsWith("#")) {
+            const codePoint = body.startsWith("#x")
+                ? Number.parseInt(body.slice(2), 16)
+                : Number.parseInt(body.slice(1), 10);
+            return Number.isFinite(codePoint) && codePoint > 0 && codePoint <= 0x10ffff
+                ? String.fromCodePoint(codePoint)
+                : full;
+        }
+        return Object.prototype.hasOwnProperty.call(NAMED_ENTITIES, body)
+            ? (NAMED_ENTITIES[body] ?? full)
+            : full;
+    });
+}

package/dist/runtime/cancel_watcher.d.ts

@@ -0,0 +1,31 @@
+/** Default cancel-poll cadence. Snappier than the 60s credit poll so a user's cancel lands within a few
+ *  seconds; each poll is a cheap brokered run-status read. */
+export declare const DEFAULT_CANCEL_CHECK_INTERVAL_MS = 5000;
+export interface CancelWatcherDeps {
+    /** The run being watched (for correlation/logging). */
+    runId: string;
+    /** Resolves true once the run has been asked to cancel. Brokered
+     *  (`RunnerControlClient.checkCancelled` → `GET /cancel`), so the runner never reads the DB. */
+    isCancelled: () => Promise<boolean>;
+    /** Fired exactly once the first time the run is seen to be cancelled. */
+    onCancelled: () => void;
+    intervalMs?: number;
+}
+export declare class CancelWatcher {
+    private readonly deps;
+    private timer;
+    private firing;
+    private cancelled;
+    private stopped;
+    constructor(deps: CancelWatcherDeps);
+    /** Begin periodic cancel checks. */
+    start(): void;
+    /** Stop checking and drain any in-flight check. Idempotent. */
+    stop(): Promise<void>;
+    /** Whether a cancel was detected (the orchestrator may read this to shape the terminal result). */
+    wasCancelled(): boolean;
+    /** True once the watcher should no longer act. A method (not an inline field read) so it's
+     *  re-evaluated after an `await` — `stop()` can flip `stopped` mid-check. */
+    private done;
+    private check;
+}

package/dist/runtime/cancel_watcher.js

@@ -0,0 +1,77 @@
+// CancelWatcher — stops a run when the user cancels it mid-flight (MASTER_SPEC §6 + docs/RUNNER_BROKER.md).
+//
+// The user-cancel counterpart to CreditWatcher. One per run session. On a timer it asks — through the
+// broker (`GET /cancel`, since the runner holds no DB/Redis credential) — whether the run has been
+// asked to cancel; the FIRST time it has, it fires `onCancelled` once (the orchestrator wires this to
+// `AbortController.abort(new RunAbortedError("cancelled"))`, which the WorkflowHost honors cooperatively
+// at the next hook boundary — a `sleep` hold wakes immediately, an `agent()`/`workflows.call` unwinds)
+// and stops checking.
+//
+// Why brokered + polled (not Redis pub/sub): the brokered worker holds NO Redis client, so the
+// api-server's `run-cancel:<id>` publish never reached it — a flipped-to-`cancelling` run just ran to
+// completion. The broker exposes the run's status; the worker polls it, like funding.
+import { createLogger } from "./support/index.js";
+const log = createLogger("CancelWatcher");
+/** Default cancel-poll cadence. Snappier than the 60s credit poll so a user's cancel lands within a few
+ *  seconds; each poll is a cheap brokered run-status read. */
+export const DEFAULT_CANCEL_CHECK_INTERVAL_MS = 5_000;
+export class CancelWatcher {
+    deps;
+    timer = null;
+    firing = Promise.resolve();
+    cancelled = false;
+    stopped = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Begin periodic cancel checks. */
+    start() {
+        if (this.timer !== null)
+            return;
+        const interval = this.deps.intervalMs ?? DEFAULT_CANCEL_CHECK_INTERVAL_MS;
+        this.timer = setInterval(() => {
+            this.firing = this.firing.then(() => this.check());
+        }, interval);
+        // Don't keep the worker process alive solely for the cancel timer.
+        this.timer.unref();
+    }
+    /** Stop checking and drain any in-flight check. Idempotent. */
+    async stop() {
+        this.stopped = true;
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.firing.catch(() => undefined);
+    }
+    /** Whether a cancel was detected (the orchestrator may read this to shape the terminal result). */
+    wasCancelled() {
+        return this.cancelled;
+    }
+    /** True once the watcher should no longer act. A method (not an inline field read) so it's
+     *  re-evaluated after an `await` — `stop()` can flip `stopped` mid-check. */
+    done() {
+        return this.stopped || this.cancelled;
+    }
+    async check() {
+        if (this.done())
+            return;
+        let cancelled;
+        try {
+            cancelled = await this.deps.isCancelled();
+        }
+        catch (err) {
+            // A failed cancel check must NOT kill a healthy run — log and let the next tick retry.
+            log.warn("cancel_check_failed", {
+                runId: this.deps.runId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return;
+        }
+        if (!cancelled || this.done())
+            return;
+        this.cancelled = true;
+        log.info("run_cancel_requested", { runId: this.deps.runId });
+        this.deps.onCancelled();
+    }
+}

package/dist/runtime/credit_watcher.d.ts

@@ -0,0 +1,30 @@
+/** Default funding-check cadence. */
+export declare const DEFAULT_CREDIT_CHECK_INTERVAL_MS = 60000;
+export interface CreditWatcherDeps {
+    /** The run being watched (for correlation/logging). */
+    runId: string;
+    /** Resolves true while the org can keep spending; false once it's out of credit. Brokered
+     *  (`RunnerControlClient.checkCredit` → `GET /credit`), so the runner never reads Stripe. */
+    isFunded: () => Promise<boolean>;
+    /** Fired exactly once when the org is first seen to be out of credit. */
+    onExhausted: () => void;
+    intervalMs?: number;
+}
+export declare class CreditWatcher {
+    private readonly deps;
+    private timer;
+    private firing;
+    private exhausted;
+    private stopped;
+    constructor(deps: CreditWatcherDeps);
+    /** Begin periodic funding checks. */
+    start(): void;
+    /** Stop checking and drain any in-flight check. Idempotent. */
+    stop(): Promise<void>;
+    /** Whether exhaustion was detected (the orchestrator may read this to shape the terminal result). */
+    isExhausted(): boolean;
+    /** True once the watcher should no longer act. A method (not an inline field read) so it's
+     *  re-evaluated after an `await` — `stop()` can flip `stopped` mid-check. */
+    private done;
+    private check;
+}