@boardwalk-labs/runner 0.1.11 → 0.1.13

package/dist/runtime/runner_control_client.js

@@ -19,20 +19,41 @@ export class RunnerControlClient {
     /** The live bearer. Mutable: on the snapshot substrate a wake carries a FRESH run token (the
      *  frozen one expired while suspended) and the worker swaps it at runtime. */
     runToken;
+    controlTimeoutMs;
+    bulkTimeoutMs;
     constructor(cfg) {
         this.cfg = cfg;
         this.base = cfg.baseUrl.replace(/\/+$/, "");
         this.fetchImpl = cfg.fetchImpl ?? fetch;
         this.runToken = cfg.runToken;
+        this.controlTimeoutMs = cfg.controlTimeoutMs ?? 30_000;
+        this.bulkTimeoutMs = cfg.bulkTimeoutMs ?? 300_000;
     }
     /** Swap the bearer for a fresh run token (the wake path). Every subsequent call uses it. */
     swapRunToken(token) {
         this.runToken = token;
     }
+    /**
+     * Every SHORT control call (claim / renew / cancel / credit / journal / …) goes through here so
+     * it carries a hard timeout. Without one, a poll frozen mid-flight on the snapshot substrate
+     * hangs FOREVER on restore (the socket is dead but never reset), and since a watcher serializes
+     * its ticks, one hung tick wedges that watcher — the dead-connections gotcha for the
+     * background pollers (lease/cancel/credit), which run on untracked timers the quiescence gate
+     * doesn't cover. Also plain robustness: no broker call should hang on a network blip. The
+     * streaming inference call is the ONE exception (long-lived NDJSON) and bypasses this.
+     */
+    controlFetch(url, init) {
+        return this.fetchImpl(url, { ...init, signal: AbortSignal.timeout(this.controlTimeoutMs) });
+    }
+    /** Bulk transfers (artifact + workspace up/download over presigned S3) — a much larger ceiling
+     *  than a control call, but still bounded so a dead socket can't hang the run. */
+    bulkFetch(url, init) {
+        return this.fetchImpl(url, { ...init, signal: AbortSignal.timeout(this.bulkTimeoutMs) });
+    }
     /** 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"), {
+        const res = await this.controlFetch(this.url("claim"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ workerId, leaseSeconds }),
@@ -54,7 +75,7 @@ export class RunnerControlClient {
      *  `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"), {
+        const res = await this.controlFetch(this.url("renew"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ workerId, leaseSeconds }),
@@ -70,7 +91,7 @@ export class RunnerControlClient {
      *  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"), {
+        const res = await this.controlFetch(this.url("finalize"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ status, output, workerId }),
@@ -81,7 +102,7 @@ export class RunnerControlClient {
     /** Look up a durable-seam journal entry by its seq (the durable-suspension design), 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))}`), {
+        const res = await this.controlFetch(this.url(`journal/${encodeURIComponent(String(seq))}`), {
             method: "GET",
             headers: this.headers(false),
         });
@@ -94,7 +115,7 @@ export class RunnerControlClient {
     /** 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"), {
+        const res = await this.controlFetch(this.url("journal"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify(entry),
@@ -106,7 +127,7 @@ export class RunnerControlClient {
      *  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"), {
+        const res = await this.controlFetch(this.url("suspend"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ ...signal, workerId }),
@@ -123,7 +144,7 @@ export class RunnerControlClient {
     }
     /** 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"), {
+        const res = await this.controlFetch(this.url("version"), {
             method: "GET",
             headers: this.headers(false),
         });
@@ -136,7 +157,7 @@ export class RunnerControlClient {
     /** 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"), {
+        const res = await this.controlFetch(this.url("usage"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ runtimeSeconds, identifier }),
@@ -145,10 +166,10 @@ export class RunnerControlClient {
             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}. */
+     *  broker gates on the run's per-connection `billed_by_boardwalk` server-side + meters usage to the
+     *  platform; `identifier` makes a retried/duplicate flush idempotent. Satisfies {@link TokenUsageReporter}. */
     async meterTokens(input) {
-        const res = await this.fetchImpl(this.url("usage/tokens"), {
+        const res = await this.controlFetch(this.url("usage/tokens"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify(input),
@@ -157,9 +178,9 @@ export class RunnerControlClient {
             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). */
+     *  live billing balance server-side; `false` means out of credit (the watcher then aborts the run). */
     async checkCredit() {
-        const res = await this.fetchImpl(this.url("credit"), {
+        const res = await this.controlFetch(this.url("credit"), {
             method: "GET",
             headers: this.headers(false),
         });
@@ -171,7 +192,7 @@ export class RunnerControlClient {
      *  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"), {
+        const res = await this.controlFetch(this.url("cancel"), {
             method: "GET",
             headers: this.headers(false),
         });
@@ -179,10 +200,33 @@ export class RunnerControlClient {
             throw await brokerError(res, "cancel");
         return (await res.json()).cancelRequested;
     }
+    /** Register-without-release: register a HELD HITL gate's request row
+     *  so it is answerable while the run keeps running — no suspend. Idempotent. Returns whether a new
+     *  gate was registered. */
+    async registerInput(seq, gate) {
+        const res = await this.controlFetch(this.url("inputs"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({ seq, humanInput: gate }),
+        });
+        if (res.status !== 200)
+            throw await brokerError(res, "register-input");
+        return (await res.json()).registered;
+    }
+    /** Poll the resolved answers for a held gate at `seq` (empty until a human responds). */
+    async pollInputAnswers(seq) {
+        const res = await this.controlFetch(this.url(`inputs/${encodeURIComponent(String(seq))}`), {
+            method: "GET",
+            headers: this.headers(false),
+        });
+        if (res.status !== 200)
+            throw await brokerError(res, "poll-inputs");
+        return (await res.json()).answers;
+    }
     /** 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). */
+     *  persistence). `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"), {
+        const res = await this.controlFetch(this.url("workspace/hydrate-url"), {
             method: "POST",
             headers: this.headers(false),
         });
@@ -195,7 +239,7 @@ export class RunnerControlClient {
      *  (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"), {
+        const res = await this.controlFetch(this.url("workspace/persist-url"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ sizeBytes }),
@@ -208,7 +252,7 @@ export class RunnerControlClient {
     /** 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" });
+        const res = await this.bulkFetch(url, { method: "GET" });
         if (res.status === 404)
             return null;
         if (!res.ok)
@@ -219,7 +263,7 @@ export class RunnerControlClient {
      *  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"), {
+        const res = await this.controlFetch(this.url("oidc/token"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ audience }),
@@ -231,7 +275,7 @@ export class RunnerControlClient {
     /** 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"), {
+        const res = await this.controlFetch(this.url("telemetry"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ frames }),
@@ -242,7 +286,7 @@ export class RunnerControlClient {
     /** 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"), {
+        const res = await this.controlFetch(this.url("artifacts"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify(input),
@@ -255,7 +299,7 @@ export class RunnerControlClient {
      *  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"), {
+        const res = await this.controlFetch(this.url("artifacts/presign"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify(input),
@@ -268,7 +312,7 @@ export class RunnerControlClient {
      *  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 });
+        const res = await this.bulkFetch(url, { method: "PUT", headers, body });
         if (!res.ok)
             throw await brokerError(res, "artifacts-upload");
     }
@@ -277,7 +321,7 @@ export class RunnerControlClient {
      *  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"), {
+        const res = await this.controlFetch(this.url("artifacts/commit"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify(input),
@@ -288,7 +332,7 @@ export class RunnerControlClient {
     }
     /** List the artifacts this run has produced. */
     async listArtifacts() {
-        const res = await this.fetchImpl(this.url("artifacts"), {
+        const res = await this.controlFetch(this.url("artifacts"), {
             method: "GET",
             headers: this.headers(false),
         });
@@ -298,7 +342,7 @@ export class RunnerControlClient {
     }
     /** 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`), {
+        const res = await this.controlFetch(this.url(`artifacts/${encodeURIComponent(artifactId)}/signed-url`), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ ttlSeconds }),
@@ -310,7 +354,7 @@ export class RunnerControlClient {
     /** 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"), {
+        const res = await this.controlFetch(this.url("secrets/resolve"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ name }),
@@ -325,7 +369,7 @@ export class RunnerControlClient {
      *  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"), {
+        const res = await this.controlFetch(this.url("mcp/token"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({
@@ -344,7 +388,7 @@ export class RunnerControlClient {
     /** 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"), {
+        const res = await this.controlFetch(this.url("tools/web_search"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify(input),
@@ -355,7 +399,7 @@ export class RunnerControlClient {
     }
     /** Create (or idempotently re-attach to) a child run for `workflows.call`. */
     async startChild(slug, input) {
-        const res = await this.fetchImpl(this.url("children"), {
+        const res = await this.controlFetch(this.url("children"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ slug, input }),
@@ -367,7 +411,7 @@ export class RunnerControlClient {
     }
     /** 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"), {
+        const res = await this.controlFetch(this.url("schedules"), {
             method: "POST",
             headers: this.headers(true),
             body: JSON.stringify({ slug, input, ...spec }),
@@ -378,7 +422,7 @@ export class RunnerControlClient {
     }
     /** 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)}`), {
+        const res = await this.controlFetch(this.url(`children/${encodeURIComponent(childRunId)}`), {
             method: "GET",
             headers: this.headers(false),
         });

package/dist/runtime/runtime_flusher.d.ts

@@ -30,7 +30,7 @@ export declare class RuntimeFlusher {
     private excludedMs;
     constructor(deps: RuntimeFlusherDeps);
     /** Book everything unbilled right now (the pre-freeze flush: suspended time must never appear as
-     *  billed runtime, so the tail is booked BEFORE the snapshot — SUSPEND_POLICY billing rule). */
+     *  billed runtime, so the tail is booked BEFORE the snapshot — the suspension billing rule). */
     flushNow(): Promise<void>;
     /** Exclude `ms` of wall-clock from billing — the frozen window on a wake (computed from the wake's
      *  authoritative wall clock, since the guest's own clock was stopped). Never lets elapsed go

package/dist/runtime/runtime_flusher.js

@@ -1,10 +1,10 @@
 // RuntimeFlusher — meters a run's held-task runtime as periodic DELTAS, instead of one charge at
-// terminal (the platform spec). The heartbeat counterpart to the credit / cancel
+// terminal. 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
+// the billing balance, 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
@@ -36,7 +36,7 @@ export class RuntimeFlusher {
         this.deps = deps;
     }
     /** Book everything unbilled right now (the pre-freeze flush: suspended time must never appear as
-     *  billed runtime, so the tail is booked BEFORE the snapshot — SUSPEND_POLICY billing rule). */
+     *  billed runtime, so the tail is booked BEFORE the snapshot — the suspension billing rule). */
     async flushNow() {
         await this.flush(false);
     }

package/dist/runtime/support/index.js

@@ -1,11 +1,10 @@
 // SPDX-License-Identifier: Apache-2.0
-// Runtime support shims — the small slice of the platform's `@boardwalk/common` +
-// `domain/authz` the worker runtime depends on, ported verbatim where it matters
-// (AppError taxonomy) and minimally where it doesn't (the logger: structured JSON to
-// stdout, same call surface as the platform's Powertools child logger).
+// Runtime support shims — a small, self-contained slice of the error taxonomy and logging the
+// worker runtime depends on. The AppError taxonomy mirrors the platform's error codes so brokered
+// responses map cleanly; the logger emits structured JSON to stdout.
 import { randomUUID } from "node:crypto";
-// ---- errors (ported from boardwalk-backend src/common/errors.ts; keep in sync until the
-// backend consumes this package and the copy there is deleted) ----
+// ---- errors (the shared AppError taxonomy — mirrors the platform's error codes so brokered
+// responses deserialize to the same shape) ----
 export var ErrorCode;
 (function (ErrorCode) {
     ErrorCode["VALIDATION_FAILED"] = "VALIDATION_FAILED";

package/dist/runtime/tools/artifacts.js

@@ -1,4 +1,4 @@
-// artifacts — persist + reference run outputs (the platform spec). Available to any agent
+// artifacts — persist + reference run outputs. Available to any agent
 // (no sandbox required). Three operations:
 //   * write(name, content_type, body)   → store a file under the run's prefix; returns id + a signed URL.
 //   * list()                            → artifacts produced in THIS run.

package/dist/runtime/tools/types.d.ts

@@ -3,7 +3,7 @@ import type { AuthContext } from "../support/index.js";
 import type { SecretRefManifest } from "../wire/manifest.js";
 /**
  * Per-invocation context the worker threads through to a tool. Equivalent to
- * Strands' `ToolContext` but typed in Boardwalk's idiom (AuthContext + run id +
+ * a tool framework's `ToolContext` but typed in Boardwalk's idiom (AuthContext + run id +
  * secret resolver scoped to this run's permissions).
  */
 export interface ToolContext {
@@ -27,7 +27,7 @@ export interface SecretResolver {
  *   * Return a `ToolReturn` body — synchronous "normal" tools (echo, http,
  *     web_search). The body lands in the conversation as the assistant's
  *     tool-result block.
- *   * Return a `ToolControlSignal` — the legacy Strands-level sleep/workflows.call path. The
+ *   * Return a `ToolControlSignal` — the legacy tool-level sleep/workflows.call path. The
  *     current JS-body worker exposes these as program SDK hooks instead; agent() leaves strip
  *     control-flow tools before registering model-callable tools.
  */
@@ -41,8 +41,8 @@ export interface BoardwalkTool<TInput = unknown, TOutput = unknown> {
     /**
      * Zod schema for the tool's SUCCESS output (the `TOutput` shape — never the
      * control-signal branch). The adapter validates the tool's return value
-     * against this before it lands in the LLM conversation, per the code standards
-     * §2.1/§8.3 (LLM-facing output is treated like untrusted external input).
+     * against this before it lands in the LLM conversation
+     * (LLM-facing output is treated like untrusted external input).
      */
     readonly outputSchema: z.ZodType<TOutput>;
     /**
@@ -64,7 +64,7 @@ export interface BoardwalkTool<TInput = unknown, TOutput = unknown> {
     normalizeInput?(raw: unknown): unknown;
     /**
      * Invoke the tool. `input` (LLM-supplied) comes first, `ctx` (worker-supplied)
-     * second — see the `Tool` naming note in SPEC §9. Returns either the typed
+     * second — see the `Tool` naming note in SPEC.md. Returns either the typed
      * `TOutput` body or a `ToolControlSignal` (sleep / workflows.call) the worker
      * intercepts before serialization.
      */

package/dist/runtime/tools/types.js

@@ -1,15 +1,15 @@
 // Boardwalk's internal Tool contract. Concrete tools (`echo`, `http`, `web_search`, `sleep`,
-// `workflows.call`, …) implement this interface; the worker registers a `ZodTool`-flavored
-// adapter into Strands at agent construction time.
+// `workflows.call`, …) implement this interface; the worker registers a schema-typed
+// adapter into the agent leaf at construction time.
 //
-// Why a Boardwalk-side interface instead of using `ZodTool` directly?
-//   * Tests can drive tool logic without instantiating Strands.
+// Why a Boardwalk-side interface instead of the leaf's native tool type?
+//   * Tests can drive tool logic without instantiating the agent leaf.
 //   * Control-signal tools (`sleep`, `workflows.call`) need to return a
 //     specially-shaped value the worker interprets — they don't really "run";
-//     they bubble a signal up to the engine. Our adapter (lands with the worker
-//     in Phase 10.5) translates between this interface and the Strands surface.
+//     they bubble a signal up to the engine. Our adapter translates between
+//     this interface and the agent leaf's tool surface.
 //
-// Per the platform spec: tools NEVER see secret values. Secrets resolve to
+// Tools NEVER see secret values. Secrets resolve to
 // short-lived bearer tokens, ARNs, etc. via the injected `SecretResolver`.
 export function isControlSignal(value) {
     return (typeof value === "object" &&

package/dist/runtime/tools/web_search.js

@@ -1,12 +1,11 @@
 // web_search — wraps the Tavily API (https://docs.tavily.com/docs/api-reference).
 //
-// Per the platform spec: Tavily is Boardwalk's default web-search provider. API
-// key fetched from Secrets Manager (`boardwalk/<stage>/tavily/api-key`) and
-// cached at the module level per container, NEVER appearing in the agent's
-// conversation.
+// The platform's default web-search provider. API
+// key fetched from the org's secret store and cached at the module level per
+// container, NEVER appearing in the agent's conversation.
 //
-// 429 from Tavily → `AppError(RATE_LIMIT)` so Strands' retry strategy handles
-// backoff. 5xx → `AppError(TOOL_ERROR)`. Network-level fetch failures fall
+// 429 from the provider → `AppError(RATE_LIMIT)` so the agent loop's retry strategy
+// handles backoff. 5xx → `AppError(TOOL_ERROR)`. Network-level fetch failures fall
 // back to `TOOL_ERROR`.
 import { z } from "zod";
 import { AppError, ErrorCode } from "../support/index.js";

package/dist/runtime/uniqueness_reseed.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Reseed the userspace CSPRNG at a restore boundary (fresh-run identity injection AND every wake —
+ * clause 3), before any run code draws randomness. Idempotent and side-effect-free beyond the
+ * reseed; safe to call repeatedly. Returns whether the reseed ran (false = addon unavailable, the
+ * degraded no-op path). Never throws.
+ */
+export declare function reseedUserspaceCsprng(): boolean;

package/dist/runtime/uniqueness_reseed.js

@@ -0,0 +1,65 @@
+// Snapshot-uniqueness reseed — clause 3 of the SNAPSHOT_UNIQUENESS_CONTRACT, the one sliver of
+// the determinism contract that survives the journal's deletion.
+//
+// A memory snapshot freezes OpenSSL's DRBG, so two clones of one base snapshot hand every run
+// byte-identical `crypto.*` output (proven, contract). The kernel CSPRNG diverges across
+// clones (VMGenID) but that reseed never reaches OpenSSL, and a pure-JS monkeypatch was proven
+// insufficient (named ESM imports of `node:crypto` bypass it — measured 2026-07-09). So the robust
+// fix is a native step that reseeds OpenSSL's DRBG UNDERNEATH every caller: the `bw_reseed` addon
+// (native/reseed.c) chains EVP_RAND_reseed over the primary/public/private DRBGs from the
+// (VMGenID-diverged) OS entropy.
+//
+// This module is the platform-owned JS entry point. It loads the prebuilt addon opportunistically
+// and NO-OPS with a warning when it is unavailable (a platform with no prebuild — e.g. the ARM64
+// Fargate worker, where there is no snapshot and thus nothing to reseed; or a self-host on an
+// unsupported arch). It never throws: a reseed that cannot run must not fail a run.
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { createLogger } from "./support/index.js";
+const log = createLogger("uniqueness_reseed");
+/** undefined = not yet attempted; null = unavailable (no prebuild for this platform). */
+let addon;
+function loadAddon() {
+    if (addon !== undefined)
+        return addon;
+    try {
+        const require = createRequire(import.meta.url);
+        // node-gyp-build resolves prebuilds/<platform>-<arch>/*.node (production) or build/Release
+        // (a local dev build), throwing when neither exists for this platform.
+        const nodeGypBuild = require("node-gyp-build");
+        // dist/runtime/uniqueness_reseed.js → the package root two levels up (holds prebuilds/ + build/).
+        const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+        addon = nodeGypBuild(pkgRoot);
+    }
+    catch (err) {
+        addon = null;
+        log.warn("uniqueness_reseed_addon_unavailable", {
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+    return addon;
+}
+/**
+ * Reseed the userspace CSPRNG at a restore boundary (fresh-run identity injection AND every wake —
+ * clause 3), before any run code draws randomness. Idempotent and side-effect-free beyond the
+ * reseed; safe to call repeatedly. Returns whether the reseed ran (false = addon unavailable, the
+ * degraded no-op path). Never throws.
+ */
+export function reseedUserspaceCsprng() {
+    const a = loadAddon();
+    if (a === null)
+        return false;
+    try {
+        const ok = a.reseed();
+        if (!ok)
+            log.warn("uniqueness_reseed_partial", {});
+        return ok;
+    }
+    catch (err) {
+        log.error("uniqueness_reseed_failed", {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return false;
+    }
+}

package/dist/runtime/wire/artifact_storage.js

@@ -1,5 +1,5 @@
 // Artifact storage policy — the server-side rules for turning an agent's artifact-write request into
-// a stored S3 object (the platform spec). These used to live in the `artifacts` TOOL,
+// a stored S3 object. These used to live in the `artifacts` TOOL,
 // which runs on the UNTRUSTED runner; under the Runner Credential Broker (the Runner Credential Broker model) the
 // broker owns them so a malicious runner can't bypass content-type neutralization or escape its
 // run's key prefix. Pure functions — unit-tested exhaustively.
@@ -10,7 +10,7 @@ import * as nodePath from "node:path";
 export function workspaceS3Key(orgId, workflowId) {
     return `orgs/${orgId}/workflows/${workflowId}/workspace.tar.gz`;
 }
-// ---- run-artifact retention tag (Phase 18.5 S3 lifecycle safety net) ----
+// ---- run-artifact retention tag (S3 lifecycle safety net) ----
 //
 // Run artifacts share the `orgs/{org}/...` prefix with workspace snapshots (`.../workflows/...`) and
 // program artifacts (`.../program-artifacts/...`), and S3 lifecycle prefix filters can't express

package/dist/runtime/wire/inference_proxy.d.ts

@@ -57,7 +57,7 @@ export declare function parseInferenceRequest(body: string): InferenceProxyReque
 /** Serialize one streamed text delta as a single NDJSON line (trailing "\n" included). */
 export declare function serializeDeltaFrame(text: string): string;
 /** Serialize the single terminal turn result as one NDJSON line. `costMicros` is the turn's EXACT
- *  upstream cost (OpenRouter `usage.cost` × 1e6) on the managed lane — 0 for BYO or when unavailable.
+ *  upstream cost (the managed provider's per-request cost × 1e6) on the managed lane — 0 for BYO or when unavailable.
  *  The worker feeds it to the budget guardrail so `max_usd` tracks real spend, not a token estimate. */
 export declare function serializeResultFrame(turn: ChatTurn, modelRef: string, costMicros?: number): string;
 /** Serialize a terminal error as a single NDJSON line. */

package/dist/runtime/wire/inference_proxy.js

@@ -13,7 +13,7 @@
 //
 // Transport: the response is **newline-delimited JSON** (one frame per line). A model turn streams
 // many text deltas; NDJSON lets the runner consume them incrementally over the raw socket (the
-// buffered REST path can't stream — the platform spec). Each frame is one of:
+// buffered REST path can't stream). Each frame is one of:
 //   { "t": "delta",  "text": <string> }                  — a streamed assistant-text chunk
 //   { "t": "result", "turn": <ChatTurn>, "modelRef": <string>, "costMicros": <number> }  — terminal turn
 //   { "t": "error",  "error": { code, message } }         — a terminal model/broker error
@@ -77,7 +77,7 @@ export function serializeDeltaFrame(text) {
     return `${JSON.stringify({ t: "delta", text })}\n`;
 }
 /** Serialize the single terminal turn result as one NDJSON line. `costMicros` is the turn's EXACT
- *  upstream cost (OpenRouter `usage.cost` × 1e6) on the managed lane — 0 for BYO or when unavailable.
+ *  upstream cost (the managed provider's per-request cost × 1e6) on the managed lane — 0 for BYO or when unavailable.
  *  The worker feeds it to the budget guardrail so `max_usd` tracks real spend, not a token estimate. */
 export function serializeResultFrame(turn, modelRef, costMicros = 0) {
     return `${JSON.stringify({ t: "result", turn, modelRef, costMicros })}\n`;