@boardwalk-labs/runner 0.1.2

package/dist/runtime/runner_control_client.js

@@ -0,0 +1,501 @@
+// RunnerControlClient — the worker's HTTP client for the Runner Control API (docs/RUNNER_BROKER.md).
+//
+// Under the broker model the worker reaches run lifecycle through the api-server, not the DB directly:
+// it presents its per-run token (BOARDWALK_RUN_TOKEN) as a bearer credential and calls the broker for
+// claim / finalize / version. The client is bound to ONE run (the token is too), so every call targets
+// `…/runner/v1/runs/<runId>/…`.
+//
+// Thin + injectable (fetch is overridable) so it's unit-tested without a live server. Status mapping
+// mirrors the broker handlers: claim 409 ⇒ "claim lost" (null), version 404 ⇒ missing (null); any
+// other non-success status throws so the worker fails loud (→ restart, lease reclaimed).
+import { createLogger } from "./support/index.js";
+import { journalLookupSchema, } from "./suspension.js";
+import { INFERENCE_NDJSON_CONTENT_TYPE, parseInferenceFrame, serializeInferenceRequest, } from "./wire/inference_proxy.js";
+const log = createLogger("RunnerControlClient");
+export class RunnerControlClient {
+    cfg;
+    base;
+    fetchImpl;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.base = cfg.baseUrl.replace(/\/+$/, "");
+        this.fetchImpl = cfg.fetchImpl ?? fetch;
+    }
+    /** 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". */
+    async claim(workerId, leaseSeconds) {
+        const res = await this.fetchImpl(this.url("claim"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({ workerId, leaseSeconds }),
+        });
+        if (res.status === 409)
+            return null;
+        if (res.status !== 201)
+            throw await brokerError(res, "claim");
+        const body = (await res.json());
+        return {
+            run: body.run,
+            lastEventCursor: body.lastEventCursor ?? 0,
+            // The replay frontier for silent replay (docs/SUSPENSION.md): the highest journaled seq, so a
+            // resumed run knows which seams already ran (suppress their re-emitted observability).
+            lastJournalSeq: body.lastJournalSeq ?? 0,
+        };
+    }
+    /** 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". */
+    async renewLease(workerId, leaseSeconds) {
+        const res = await this.fetchImpl(this.url("renew"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({ workerId, leaseSeconds }),
+        });
+        if (res.status === 409)
+            return null;
+        if (res.status !== 200)
+            throw await brokerError(res, "renew");
+        const body = (await res.json());
+        return body.leaseUntil;
+    }
+    /** 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. */
+    async finalize(status, output, workerId) {
+        const res = await this.fetchImpl(this.url("finalize"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({ status, output, workerId }),
+        });
+        if (res.status !== 204)
+            throw await brokerError(res, "finalize");
+    }
+    /** 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. */
+    async journalGet(seq) {
+        const res = await this.fetchImpl(this.url(`journal/${encodeURIComponent(String(seq))}`), {
+            method: "GET",
+            headers: this.headers(false),
+        });
+        if (res.status === 404)
+            return null;
+        if (res.status !== 200)
+            throw await brokerError(res, "journal-get");
+        return journalLookupSchema.parse(await res.json());
+    }
+    /** 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. */
+    async journalPut(entry) {
+        const res = await this.fetchImpl(this.url("journal"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify(entry),
+        });
+        if (res.status !== 204)
+            throw await brokerError(res, "journal-put");
+    }
+    /** 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. */
+    async suspend(signal, workerId) {
+        const res = await this.fetchImpl(this.url("suspend"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({ ...signal, workerId }),
+        });
+        if (res.status !== 204)
+            throw await brokerError(res, "suspend");
+    }
+    /** The {@link JournalSeam} the worker host reads/writes — a thin adapter over the broker methods. */
+    journalSeam() {
+        return {
+            get: (seq) => this.journalGet(seq),
+            put: (entry) => this.journalPut(entry),
+        };
+    }
+    /** Fetch the run's pinned manifest + program source, or null when the version is missing (404). */
+    async getVersion() {
+        const res = await this.fetchImpl(this.url("version"), {
+            method: "GET",
+            headers: this.headers(false),
+        });
+        if (res.status === 404)
+            return null;
+        if (res.status !== 200)
+            throw await brokerError(res, "version");
+        return (await res.json());
+    }
+    /** 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. */
+    async reportUsage(runtimeSeconds, identifier) {
+        const res = await this.fetchImpl(this.url("usage"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({ runtimeSeconds, identifier }),
+        });
+        if (res.status !== 204)
+            throw await brokerError(res, "usage");
+    }
+    /** 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}. */
+    async meterTokens(input) {
+        const res = await this.fetchImpl(this.url("usage/tokens"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify(input),
+        });
+        if (res.status !== 204)
+            throw await brokerError(res, "usage/tokens");
+    }
+    /** 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). */
+    async checkCredit() {
+        const res = await this.fetchImpl(this.url("credit"), {
+            method: "GET",
+            headers: this.headers(false),
+        });
+        if (res.status !== 200)
+            throw await brokerError(res, "credit");
+        return (await res.json()).funded;
+    }
+    /** 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. */
+    async checkCancelled() {
+        const res = await this.fetchImpl(this.url("cancel"), {
+            method: "GET",
+            headers: this.headers(false),
+        });
+        if (res.status !== 200)
+            throw await brokerError(res, "cancel");
+        return (await res.json()).cancelRequested;
+    }
+    /** 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). */
+    async workspaceHydrateUrl() {
+        const res = await this.fetchImpl(this.url("workspace/hydrate-url"), {
+            method: "POST",
+            headers: this.headers(false),
+        });
+        if (res.status !== 200)
+            throw await brokerError(res, "workspace/hydrate-url");
+        return (await res.json()).url;
+    }
+    /** 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. */
+    async workspacePersistUrl(sizeBytes) {
+        const res = await this.fetchImpl(this.url("workspace/persist-url"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({ sizeBytes }),
+        });
+        if (res.status !== 200)
+            throw await brokerError(res, "workspace/persist-url");
+        const body = (await res.json());
+        return body.url === null ? null : { url: body.url, contentType: body.contentType ?? "" };
+    }
+    /** 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. */
+    async downloadBytes(url) {
+        const res = await this.fetchImpl(url, { method: "GET" });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw await brokerError(res, "workspace-download");
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    /** 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. */
+    async requestOidcToken(audience) {
+        const res = await this.fetchImpl(this.url("oidc/token"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({ audience }),
+        });
+        if (res.status !== 200)
+            throw await brokerError(res, "oidc/token");
+        return (await res.json());
+    }
+    /** 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. */
+    async publishTelemetry(frames) {
+        const res = await this.fetchImpl(this.url("telemetry"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({ frames }),
+        });
+        if (res.status !== 204)
+            throw await brokerError(res, "telemetry");
+    }
+    /** 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. */
+    async writeArtifact(input) {
+        const res = await this.fetchImpl(this.url("artifacts"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify(input),
+        });
+        if (res.status !== 201)
+            throw await brokerError(res, "artifacts");
+        return (await res.json());
+    }
+    /** 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. */
+    async presignArtifact(input) {
+        const res = await this.fetchImpl(this.url("artifacts/presign"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify(input),
+        });
+        if (res.status !== 201)
+            throw await brokerError(res, "artifacts/presign");
+        return (await res.json());
+    }
+    /** 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. */
+    async uploadBytes(url, headers, body) {
+        const res = await this.fetchImpl(url, { method: "PUT", headers, body });
+        if (!res.ok)
+            throw await brokerError(res, "artifacts-upload");
+    }
+    /** 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. */
+    async commitArtifact(input) {
+        const res = await this.fetchImpl(this.url("artifacts/commit"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify(input),
+        });
+        if (res.status !== 201)
+            throw await brokerError(res, "artifacts/commit");
+        return (await res.json());
+    }
+    /** List the artifacts this run has produced. */
+    async listArtifacts() {
+        const res = await this.fetchImpl(this.url("artifacts"), {
+            method: "GET",
+            headers: this.headers(false),
+        });
+        if (res.status !== 200)
+            throw await brokerError(res, "artifacts-list");
+        return (await res.json()).artifacts;
+    }
+    /** Mint a fresh signed download URL for one of this run's artifacts. */
+    async signArtifactUrl(artifactId, ttlSeconds) {
+        const res = await this.fetchImpl(this.url(`artifacts/${encodeURIComponent(artifactId)}/signed-url`), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({ ttlSeconds }),
+        });
+        if (res.status !== 200)
+            throw await brokerError(res, "artifacts-sign");
+        return (await res.json());
+    }
+    /** 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. */
+    async resolveSecret(name) {
+        const res = await this.fetchImpl(this.url("secrets/resolve"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({ name }),
+        });
+        if (res.status !== 200)
+            throw await brokerError(res, "secrets/resolve");
+        const body = (await res.json());
+        return body.value;
+    }
+    /** 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. */
+    async mcpToken(serverUrl, invalidateToken) {
+        const res = await this.fetchImpl(this.url("mcp/token"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({
+                serverUrl,
+                ...(invalidateToken !== undefined ? { invalidateToken } : {}),
+            }),
+        });
+        if (res.status === 403) {
+            return { accessToken: null, hint: await brokerForbiddenHint(res) };
+        }
+        if (res.status !== 200)
+            throw await brokerError(res, "mcp/token");
+        const body = (await res.json());
+        return { accessToken: body.accessToken };
+    }
+    /** 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. */
+    async webSearch(input) {
+        const res = await this.fetchImpl(this.url("tools/web_search"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify(input),
+        });
+        if (res.status !== 200)
+            throw await brokerError(res, "tools/web_search");
+        return (await res.json());
+    }
+    /** Create (or idempotently re-attach to) a child run for `workflows.call`. */
+    async startChild(slug, input) {
+        const res = await this.fetchImpl(this.url("children"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({ slug, input }),
+        });
+        // The broker returns 201 for a fresh child, 200 for an idempotent re-attach.
+        if (res.status !== 200 && res.status !== 201)
+            throw await brokerError(res, "children");
+        return (await res.json());
+    }
+    /** Provision a durable schedule for `workflows.schedule`; returns the new schedule's id. */
+    async scheduleWorkflow(slug, input, spec) {
+        const res = await this.fetchImpl(this.url("schedules"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({ slug, input, ...spec }),
+        });
+        if (res.status !== 201)
+            throw await brokerError(res, "schedules");
+        return (await res.json()).scheduleId;
+    }
+    /** Poll a child run's status/output, or null when it isn't this run's child (404). */
+    async getChild(childRunId) {
+        const res = await this.fetchImpl(this.url(`children/${encodeURIComponent(childRunId)}`), {
+            method: "GET",
+            headers: this.headers(false),
+        });
+        if (res.status === 404)
+            return null;
+        if (res.status !== 200)
+            throw await brokerError(res, "children-get");
+        return (await res.json());
+    }
+    /**
+     * 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.
+     */
+    async *streamInference(req) {
+        const res = await this.fetchImpl(this.url("inference"), {
+            method: "POST",
+            headers: { ...this.headers(true), accept: INFERENCE_NDJSON_CONTENT_TYPE },
+            body: serializeInferenceRequest(req),
+        });
+        if (res.status !== 200 || res.body === null) {
+            throw await inferenceHttpError(res);
+        }
+        for await (const line of readNdjsonLines(res.body)) {
+            yield parseInferenceFrame(line);
+        }
+    }
+    url(suffix) {
+        return `${this.base}/runner/v1/runs/${encodeURIComponent(this.cfg.runId)}/${suffix}`;
+    }
+    headers(json) {
+        const h = {
+            authorization: `Bearer ${this.cfg.runToken}`,
+            accept: "application/json",
+        };
+        if (json)
+            h["content-type"] = "application/json";
+        return h;
+    }
+}
+/** Yield complete newline-delimited lines from a streaming response body (NDJSON inference frames),
+ *  buffering partial chunks and flushing any trailing line. Blank lines are skipped. */
+async function* readNdjsonLines(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buf += decoder.decode(value, { stream: true });
+            for (;;) {
+                const idx = buf.indexOf("\n");
+                if (idx < 0)
+                    break;
+                const line = buf.slice(0, idx).trim();
+                buf = buf.slice(idx + 1);
+                if (line.length > 0)
+                    yield line;
+            }
+        }
+        const tail = (buf + decoder.decode()).trim();
+        if (tail.length > 0)
+            yield tail;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/** Build a redacted-enough error from a non-success broker response (status + a clipped body). Used
+ *  for the internal control-plane ops (claim/finalize/usage/…), whose failures crash+restart the run
+ *  rather than surface to the customer — so the op+status framing is the useful debugging detail. */
+async function brokerError(res, op) {
+    let detail = "";
+    try {
+        detail = (await res.text()).slice(0, 500);
+    }
+    catch {
+        /* body unreadable — status alone is enough */
+    }
+    log.warn("broker_call_failed", { op, status: res.status });
+    return new Error(`Runner Control ${op} failed: ${String(res.status)} ${detail}`);
+}
+/** Best-effort human hint from a broker 403 body (the error envelope's message, else the raw text)
+ *  — surfaced to the model when an MCP server can't be reached. Never includes a token (403s carry
+ *  none). */
+async function brokerForbiddenHint(res) {
+    let text = "";
+    try {
+        text = (await res.text()).slice(0, 500);
+    }
+    catch {
+        return "MCP connection is not available for this server.";
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed.error?.message === "string")
+            return parsed.error.message;
+    }
+    catch {
+        /* not JSON — fall through to the raw text */
+    }
+    return text === "" ? "MCP connection is not available for this server." : text;
+}
+/** Clean Error from a non-200 INFERENCE response. Unlike {@link brokerError}, this becomes the run's
+ *  customer-facing error, so it surfaces the broker's already-classified `{error:{message}}` directly
+ *  (HTTP status / op stay in the log, not the user text). Falls back to a generic line if unparsable. */
+async function inferenceHttpError(res) {
+    let message = "Inference failed.";
+    try {
+        const parsed = JSON.parse(await res.text());
+        if (typeof parsed.error?.message === "string" && parsed.error.message.length > 0) {
+            message = parsed.error.message;
+        }
+    }
+    catch {
+        /* non-JSON body — keep the generic message */
+    }
+    log.warn("broker_inference_failed", { status: res.status });
+    return new Error(message);
+}

package/dist/runtime/runtime_flusher.d.ts

@@ -0,0 +1,41 @@
+/** Flush cadence — runtime is billed within ~this window of accruing, so a long/perpetual run can't
+ *  burn unbilled compute and the credit watcher sees the spend promptly. */
+export declare const DEFAULT_RUNTIME_FLUSH_INTERVAL_MS = 60000;
+export interface RuntimeFlusherDeps {
+    /** The run being metered (for the id base + correlation). */
+    runId: string;
+    /** This worker session's id (fresh per claim) — separates a restarted run's sessions in the id. */
+    sessionId: string;
+    /** Wall-clock at which this session's runtime starts accruing (the claim time). */
+    startedAtMs: number;
+    /** vCPUs provisioned for the task. Runtime is billed per vCPU-SECOND, so each delta is wall-clock
+     *  seconds × this. Defaults to 1 (the 1-vCPU `small` size → vCPU-seconds == wall-clock). */
+    vcpus?: number;
+    /** Monotonic-ish clock; injected for tests. */
+    now: () => number;
+    /** Book a runtime vCPU-seconds delta under `identifier` (brokered: `RunnerControlClient.reportUsage`). */
+    report: (deltaSeconds: number, identifier: string) => Promise<void>;
+    intervalMs?: number;
+}
+export declare class RuntimeFlusher {
+    private readonly deps;
+    private timer;
+    private firing;
+    private stopped;
+    /** Total vCPU-seconds already booked (across successful flushes). The next delta is `total - this`. */
+    private flushedSeconds;
+    /** Per-flush sequence — advances only on a successful flush, so a retry reuses the same id. */
+    private seq;
+    constructor(deps: RuntimeFlusherDeps);
+    /** Begin periodic delta flushing. */
+    start(): void;
+    /** Stop the periodic timer and drain any in-flight flush. Does NOT book the final tail — call
+     *  {@link flushFinal} for that on a clean terminal. Idempotent. */
+    stop(): Promise<void>;
+    /** Book the remaining runtime since the last successful flush (the terminal tail). Runs even after
+     *  {@link stop}; it's the replacement for the old single terminal runtime charge. */
+    flushFinal(): Promise<void>;
+    /** Compute the unbilled delta and book it under a fixed per-flush id. `final` lets the terminal tail
+     *  flush after `stop()`; the timer path skips once stopped. */
+    private flush;
+}

package/dist/runtime/runtime_flusher.js

@@ -0,0 +1,90 @@
+// RuntimeFlusher — meters a run's held-task runtime as periodic DELTAS, instead of one charge at
+// terminal (MASTER_SPEC §15; docs/RUNNER_BROKER.md). The heartbeat counterpart to the credit / cancel
+// / lease watchers.
+//
+// Why: runtime used to be booked once, at terminal (`now - sessionStart`). That left two holes — a run
+// that never terminates (a perpetual loop) NEVER billed its runtime (and the credit watcher, reading
+// Stripe, never saw the burn so it couldn't stop it); and a session that crashed before finalizing had
+// its whole runtime lost. Metering on a timer closes both: runtime is billed as it accrues, the credit
+// watcher sees it, and a crashed session keeps the deltas it already flushed (the fresh session bills
+// its own — distinct ids sum, so the restart isn't double-charged or under-charged for the overlap-free
+// portion).
+//
+// Idempotency: each flush is a delta with a fixed per-flush id (`<runId>:<sessionId>:rt:<seq>`); the
+// broker/usage store dedupes on it, so a retried flush bills once. On a report failure we DON'T advance
+// `flushedSeconds`/`seq`, so the next tick retries the SAME id (with a delta grown by the elapsed since)
+// — the dedup keeps whichever landed first, bounding any loss to ~one interval and NEVER double-billing.
+// `flushFinal()` books the tail (since the last successful flush) on a clean terminal; it is deliberately
+// NOT called on a `lease_lost` handoff (the new owner books its own runtime — see program_worker).
+import { createLogger } from "./support/index.js";
+const log = createLogger("RuntimeFlusher");
+/** Flush cadence — runtime is billed within ~this window of accruing, so a long/perpetual run can't
+ *  burn unbilled compute and the credit watcher sees the spend promptly. */
+export const DEFAULT_RUNTIME_FLUSH_INTERVAL_MS = 60_000;
+export class RuntimeFlusher {
+    deps;
+    timer = null;
+    firing = Promise.resolve();
+    stopped = false;
+    /** Total vCPU-seconds already booked (across successful flushes). The next delta is `total - this`. */
+    flushedSeconds = 0;
+    /** Per-flush sequence — advances only on a successful flush, so a retry reuses the same id. */
+    seq = 0;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Begin periodic delta flushing. */
+    start() {
+        if (this.timer !== null)
+            return;
+        const interval = this.deps.intervalMs ?? DEFAULT_RUNTIME_FLUSH_INTERVAL_MS;
+        this.timer = setInterval(() => {
+            this.firing = this.firing.then(() => this.flush(false));
+        }, interval);
+        // Don't keep the worker process alive solely for the flush timer.
+        this.timer.unref();
+    }
+    /** Stop the periodic timer and drain any in-flight flush. Does NOT book the final tail — call
+     *  {@link flushFinal} for that on a clean terminal. Idempotent. */
+    async stop() {
+        this.stopped = true;
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.firing.catch(() => undefined);
+    }
+    /** Book the remaining runtime since the last successful flush (the terminal tail). Runs even after
+     *  {@link stop}; it's the replacement for the old single terminal runtime charge. */
+    async flushFinal() {
+        await this.flush(true);
+    }
+    /** Compute the unbilled delta and book it under a fixed per-flush id. `final` lets the terminal tail
+     *  flush after `stop()`; the timer path skips once stopped. */
+    async flush(final) {
+        if (this.stopped && !final)
+            return;
+        // vCPU-seconds = wall-clock seconds × vCPUs (billed per vCPU-second). Rounding the cumulative
+        // product (not per-delta) keeps the booked total aligned with wall-clock×vcpus over many flushes.
+        const vcpus = this.deps.vcpus ?? 1;
+        const total = Math.max(0, Math.round(((this.deps.now() - this.deps.startedAtMs) / 1000) * vcpus));
+        const delta = total - this.flushedSeconds;
+        if (delta < 1)
+            return;
+        const identifier = `${this.deps.runId}:${this.deps.sessionId}:rt:${String(this.seq)}`;
+        try {
+            await this.deps.report(delta, identifier);
+        }
+        catch (err) {
+            // A transient report failure must NOT kill a live run — leave `flushedSeconds`/`seq` unadvanced
+            // so the next flush retries the SAME id (dedup => no double-bill; at most ~one interval lost).
+            log.warn("runtime_flush_failed", {
+                runId: this.deps.runId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return;
+        }
+        this.flushedSeconds = total;
+        this.seq += 1;
+    }
+}

package/dist/runtime/sandbox_config.d.ts

@@ -0,0 +1,21 @@
+import { type WorkflowManifest } from "./wire/manifest.js";
+export interface SandboxToolDeps {
+    /** Absolute sandbox root — every filesystem/shell/git op is confined here. */
+    root: string;
+    /** Non-secret env vars (resolved `manifest.env` literals) exposed to shell/git subprocesses. */
+    env?: Record<string, string>;
+    /** Env var name → granted secret name (`manifest.env`'s secret refs), resolved per-run. */
+    secretEnv?: Record<string, string>;
+    committerName?: string;
+    committerEmail?: string;
+    /** Manifest `tools[name=shell].config.extra_commands` allowlist additions. */
+    extraShellCommands?: readonly string[];
+}
+/** The manifest-derived subset of {@link SandboxToolDeps} (the worker adds `root`). */
+export type SandboxConfig = Omit<SandboxToolDeps, "root" | "committerName" | "committerEmail">;
+/**
+ * Split `manifest.env` into non-secret literals vs. `${{ secrets.X }}` references. Returns only the
+ * keys that have content, so the caller can spread it into the sandbox deps without injecting
+ * empty objects.
+ */
+export declare function sandboxConfigFromManifest(manifest: WorkflowManifest): SandboxConfig;