@boardwalk-labs/runner 0.1.2

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

@@ -0,0 +1,37 @@
+/** S3 key for a workflow's persistent workspace snapshot. Scoped PER WORKFLOW (not per run), so the
+ *  snapshot carries across every run of the workflow. Derived server-side from the run token's
+ *  org + workflow, so a runner can only ever reach its own workflow's workspace. */
+export declare function workspaceS3Key(orgId: string, workflowId: string): string;
+/** Tag key/value the lifecycle rule filters on. */
+export declare const RUN_ARTIFACT_RETENTION_TAG: {
+    key: string;
+    value: string;
+};
+/** The same tag as the URL-encoded query string S3's `Tagging` param / `x-amz-tagging` header want. */
+export declare const RUN_ARTIFACT_RETENTION_TAGGING: string;
+/** S3 key for a run's artifact. The prefix is the per-run isolation boundary the broker enforces:
+ *  `orgs/{org}/runs/{run}/...` (ArtifactService.register re-checks it). */
+export declare function artifactS3Key(orgId: string, runId: string, token: string, name: string, contentType: string): string;
+/** Pick a file extension: prefer the name's own, else map the content type, else none. */
+export declare function extFor(name: string, contentType: string): string;
+/**
+ * Map an agent-supplied content type to one safe to serve inline from a Boardwalk origin. Active
+ * types are forced to text/plain so the browser renders them as inert text instead of executing
+ * embedded script (review #32). The base type (before any `;` params) is what's matched. The body is
+ * never altered — only the type the object is SERVED as.
+ *
+ * MUST run server-side (in the broker), never on the untrusted runner: the served content type is
+ * what the CDN returns, so the runner must not be able to choose an active type.
+ */
+export declare function neutralizeActiveContentType(contentType: string): string;
+/** Largest raw artifact body the broker will accept INLINE (proxied). Comfortably under the 5 MiB
+ *  control-plane body cap so the base64 string + JSON envelope fit. Above this ⇒ presigned PUT. */
+export declare const ARTIFACT_PROXY_MAX_BYTES: number;
+/** Hard ceiling on a single artifact (presigned path included) — bounds runner + broker memory. */
+export declare const ARTIFACT_MAX_BYTES: number;
+/** True when a body must use the presigned-PUT path instead of the inline proxy (it's too big to
+ *  buffer through the broker). Pure — the worker's BrokerArtifactStore routes on it. */
+export declare function shouldPresignArtifact(byteLength: number): boolean;
+/** Decode an artifact body string to its raw bytes (base64 → binary, else UTF-8). The decoded length
+ *  is the artifact's true byte size — what the proxy/presign routing + the catalog row key off. */
+export declare function decodeArtifactBody(body: string, encoding?: "utf8" | "base64"): Buffer;

package/dist/runtime/wire/artifact_storage.js

@@ -0,0 +1,93 @@
+// Artifact storage policy — the server-side rules for turning an agent's artifact-write request into
+// a stored S3 object (MASTER_SPEC §13.6, review #32). These used to live in the `artifacts` TOOL,
+// which runs on the UNTRUSTED runner; under the Runner Credential Broker (docs/RUNNER_BROKER.md) 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.
+import * as nodePath from "node:path";
+/** S3 key for a workflow's persistent workspace snapshot. Scoped PER WORKFLOW (not per run), so the
+ *  snapshot carries across every run of the workflow. Derived server-side from the run token's
+ *  org + workflow, so a runner can only ever reach its own workflow's workspace. */
+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 artifacts share the `orgs/{org}/...` prefix with workspace snapshots (`.../workflows/...`) and
+// program artifacts (`.../program-artifacts/...`), and S3 lifecycle prefix filters can't express
+// `orgs/*/runs/*` (the org id is a wildcard segment). So the safety-net rule keys off an OBJECT TAG
+// applied at write time to run artifacts ONLY — never to workspace snapshots or program code, which
+// must persist. The bucket's lifecycle rule (cdk/foundation/buckets.ts) expires objects carrying this
+// tag after 365 days, catching orphans the reaper never sees (e.g. a large upload that never committed
+// a catalog row). Tag at PUT time (inline + presigned) so an uncommitted orphan is still covered.
+/** Tag key/value the lifecycle rule filters on. */
+export const RUN_ARTIFACT_RETENTION_TAG = { key: "boardwalk-retention", value: "run-artifact" };
+/** The same tag as the URL-encoded query string S3's `Tagging` param / `x-amz-tagging` header want. */
+export const RUN_ARTIFACT_RETENTION_TAGGING = `${RUN_ARTIFACT_RETENTION_TAG.key}=${RUN_ARTIFACT_RETENTION_TAG.value}`;
+/** S3 key for a run's artifact. The prefix is the per-run isolation boundary the broker enforces:
+ *  `orgs/{org}/runs/{run}/...` (ArtifactService.register re-checks it). */
+export function artifactS3Key(orgId, runId, token, name, contentType) {
+    return `orgs/${orgId}/runs/${runId}/${token}${extFor(name, contentType)}`;
+}
+const EXT_BY_CONTENT_TYPE = {
+    "application/json": ".json",
+    "text/plain": ".txt",
+    "text/csv": ".csv",
+    "text/markdown": ".md",
+    "text/html": ".html",
+    "application/pdf": ".pdf",
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+};
+/** Pick a file extension: prefer the name's own, else map the content type, else none. */
+export function extFor(name, contentType) {
+    const fromName = nodePath.extname(name);
+    if (fromName !== "")
+        return fromName;
+    return EXT_BY_CONTENT_TYPE[contentType.toLowerCase()] ?? "";
+}
+/** Content types a browser renders as ACTIVE content (can run script) when navigated to. */
+const ACTIVE_CONTENT_TYPES = new Set([
+    "text/html",
+    "application/xhtml+xml",
+    "image/svg+xml",
+    "application/xml",
+    "text/xml",
+    "text/javascript",
+    "application/javascript",
+    "application/ecmascript",
+]);
+const NEUTRAL_CONTENT_TYPE = "text/plain; charset=utf-8";
+/**
+ * Map an agent-supplied content type to one safe to serve inline from a Boardwalk origin. Active
+ * types are forced to text/plain so the browser renders them as inert text instead of executing
+ * embedded script (review #32). The base type (before any `;` params) is what's matched. The body is
+ * never altered — only the type the object is SERVED as.
+ *
+ * MUST run server-side (in the broker), never on the untrusted runner: the served content type is
+ * what the CDN returns, so the runner must not be able to choose an active type.
+ */
+export function neutralizeActiveContentType(contentType) {
+    const base = (contentType.split(";")[0] ?? "").trim().toLowerCase();
+    return ACTIVE_CONTENT_TYPES.has(base) ? NEUTRAL_CONTENT_TYPE : contentType;
+}
+// ---- size policy: proxy small bodies through the broker, presign large ones straight to S3 ----
+//
+// The proxy path (`POST .../artifacts`) buffers the base64 body through the Runner Control body
+// limit (5 MiB wire), so it's bounded WELL under that. Anything larger takes the presigned-PUT path
+// (`POST .../artifacts/presign`, docs/RUNNER_BROKER.md §7 step 4): the broker signs an S3 PUT and the
+// runner streams the bytes straight to S3, so the body never passes through the control plane.
+/** Largest raw artifact body the broker will accept INLINE (proxied). Comfortably under the 5 MiB
+ *  control-plane body cap so the base64 string + JSON envelope fit. Above this ⇒ presigned PUT. */
+export const ARTIFACT_PROXY_MAX_BYTES = 4 * 1024 * 1024;
+/** Hard ceiling on a single artifact (presigned path included) — bounds runner + broker memory. */
+export const ARTIFACT_MAX_BYTES = 100 * 1024 * 1024;
+/** True when a body must use the presigned-PUT path instead of the inline proxy (it's too big to
+ *  buffer through the broker). Pure — the worker's BrokerArtifactStore routes on it. */
+export function shouldPresignArtifact(byteLength) {
+    return byteLength > ARTIFACT_PROXY_MAX_BYTES;
+}
+/** Decode an artifact body string to its raw bytes (base64 → binary, else UTF-8). The decoded length
+ *  is the artifact's true byte size — what the proxy/presign routing + the catalog row key off. */
+export function decodeArtifactBody(body, encoding) {
+    return Buffer.from(body, encoding === "base64" ? "base64" : "utf8");
+}

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

@@ -0,0 +1 @@
+export declare function verifyArtifactDigest(bytes: Uint8Array, expectedDigest: string): boolean;

package/dist/runtime/wire/artifact_verify.js

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: Apache-2.0
+// Content-addressed program verification (runner/CONTRACT.md invariant 3): the digest is
+// checked BEFORE extraction; a mismatch aborts the run.
+import { createHash } from "node:crypto";
+export function verifyArtifactDigest(bytes, expectedDigest) {
+    const actual = createHash("sha256").update(bytes).digest("hex");
+    return actual === expectedDigest.toLowerCase();
+}

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

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import type { HumanInputResult, JsonValue } from "@boardwalk-labs/workflow";
+/** The response form a gate presents — discriminated on `kind`. Mirrors SDK `HumanInputSpec` (the
+ *  inferred output widens optionals to `T | undefined`; {@link parseHumanInputSpec} returns it). */
+export declare const humanInputSpecSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"text">;
+    multiline: z.ZodOptional<z.ZodBoolean>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"choice">;
+    options: z.ZodArray<z.ZodString>;
+    allowOther: z.ZodOptional<z.ZodBoolean>;
+    otherLabel: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"multiselect">;
+    options: z.ZodArray<z.ZodString>;
+    allowOther: z.ZodOptional<z.ZodBoolean>;
+    otherLabel: z.ZodOptional<z.ZodString>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>], "kind">;
+/** Parsed spec shape (optionals as `T | undefined`); a SDK `HumanInputSpec` is assignable to it. */
+export type ParsedHumanInputSpec = z.infer<typeof humanInputSpecSchema>;
+/** Parse an `unknown` (jsonb) spec into a typed spec. A tool-level gate may omit a spec entirely
+ *  (the model just asked a free-text question) → text; a malformed/foreign spec also degrades to
+ *  free text rather than stranding the gate unanswerable. */
+export declare function parseHumanInputSpec(raw: unknown): ParsedHumanInputSpec;
+/** Re-hydrate a stored (jsonb) human-input result into the exact-optional SDK {@link HumanInputResult}
+ *  (the host returns it from a resumed `humanInput()` seam). The value was validated on submit, so a
+ *  parse failure here is a corrupt journal — surfaced as a clear program error. */
+export declare function normalizeHumanInputResult(raw: unknown): HumanInputResult;
+/** Convert a validated {@link HumanInputResult} to a {@link JsonValue} for storage (the result is an
+ *  interface with optional props, which TS won't structurally accept as JsonValue; an explicit object
+ *  literal IS assignable to the index signature). The inverse of {@link normalizeHumanInputResult}. */
+export declare function humanInputResultToJson(result: HumanInputResult): JsonValue;
+/** What to do when a gate's `timeout` elapses with no answer (docs/SUSPENSION.md §4.3). Mirrors the
+ *  SDK's `HumanInputOptions.onTimeout`: fail the run, or resolve the gate with a default value. */
+export type OnTimeoutPolicy = {
+    kind: "fail";
+} | {
+    kind: "value";
+    value: HumanInputResult;
+};
+/** Parse a stored (jsonb) `on_timeout` into a policy. NULL / unrecognized ⇒ the SDK default `fail`;
+ *  a `{ value }` whose value doesn't validate as a result also degrades to `fail` (never strands). */
+export declare function parseOnTimeout(raw: unknown): OnTimeoutPolicy;
+/** A responder's raw submission, before validation against the gate's spec. */
+export interface RawHumanInputSubmission {
+    /** Free text, or the chosen option / typed "other" value for a `choice` gate. */
+    value?: unknown;
+    /** Selected values for a `multiselect` gate. */
+    values?: unknown;
+    /** The typed freeform value for a `multiselect` "Other..." entry. */
+    other?: unknown;
+}
+/**
+ * Validate a raw submission against the gate's spec, producing the typed {@link HumanInputResult}
+ * the program receives. Throws `VALIDATION_FAILED` with a precise message on any mismatch — the
+ * respond surfaces turn that into a 400 so a bad answer never resumes the run with garbage.
+ */
+export declare function validateHumanInputResponse(spec: ParsedHumanInputSpec, raw: RawHumanInputSubmission): HumanInputResult;

package/dist/runtime/wire/human_input.js

@@ -0,0 +1,156 @@
+// Human-input form spec + response validation (docs/SUSPENSION.md §4.3).
+//
+// The `HumanInputSpec` is the single source of truth for BOTH the UI form and server-side
+// validation, so a `humanInput()` gate needs no JSON Schema. A responder's raw submission (from
+// REST / MCP / CLI / web) is validated here against the gate's stored spec into a typed
+// `HumanInputResult`, which becomes the seam's memoized journal value. Pure + exhaustively testable.
+//
+// These mirror the SDK's `@boardwalk-labs/workflow` types exactly (the wire contract); we re-derive
+// them as Zod schemas because the stored `input_spec` is `unknown` jsonb that must be parsed at the
+// boundary, never trusted (CLAUDE.md: predicates/Zod, no casts).
+import { z } from "zod";
+import { AppError, ErrorCode } from "../support/index.js";
+/** The response form a gate presents — discriminated on `kind`. Mirrors SDK `HumanInputSpec` (the
+ *  inferred output widens optionals to `T | undefined`; {@link parseHumanInputSpec} returns it). */
+export const humanInputSpecSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("text"),
+        multiline: z.boolean().optional(),
+        placeholder: z.string().optional(),
+        required: z.boolean().optional(),
+    }),
+    z.object({
+        kind: z.literal("choice"),
+        options: z.array(z.string()).min(1),
+        allowOther: z.boolean().optional(),
+        otherLabel: z.string().optional(),
+    }),
+    z.object({
+        kind: z.literal("multiselect"),
+        options: z.array(z.string()).min(1),
+        allowOther: z.boolean().optional(),
+        otherLabel: z.string().optional(),
+        min: z.number().int().nonnegative().optional(),
+        max: z.number().int().nonnegative().optional(),
+    }),
+]);
+/** The validated per-kind result, for parsing a stored (jsonb) result back. */
+const storedResultSchema = z.union([
+    z.object({ value: z.string(), isOther: z.boolean() }).strict(),
+    z.object({ value: z.string() }).strict(),
+    z.object({ values: z.array(z.string()), other: z.string().optional() }).strict(),
+]);
+/** Parse an `unknown` (jsonb) spec into a typed spec. A tool-level gate may omit a spec entirely
+ *  (the model just asked a free-text question) → text; a malformed/foreign spec also degrades to
+ *  free text rather than stranding the gate unanswerable. */
+export function parseHumanInputSpec(raw) {
+    if (raw === undefined || raw === null)
+        return { kind: "text" };
+    const parsed = humanInputSpecSchema.safeParse(raw);
+    return parsed.success ? parsed.data : { kind: "text" };
+}
+/** Re-hydrate a stored (jsonb) human-input result into the exact-optional SDK {@link HumanInputResult}
+ *  (the host returns it from a resumed `humanInput()` seam). The value was validated on submit, so a
+ *  parse failure here is a corrupt journal — surfaced as a clear program error. */
+export function normalizeHumanInputResult(raw) {
+    const parsed = storedResultSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new AppError(ErrorCode.INTERNAL_ERROR, "Stored human-input result is malformed", {
+            kind: "human_input_corrupt",
+        });
+    }
+    const r = parsed.data;
+    if ("values" in r)
+        return r.other !== undefined ? { values: r.values, other: r.other } : { values: r.values };
+    if ("isOther" in r)
+        return { value: r.value, isOther: r.isOther };
+    return { value: r.value };
+}
+/** Convert a validated {@link HumanInputResult} to a {@link JsonValue} for storage (the result is an
+ *  interface with optional props, which TS won't structurally accept as JsonValue; an explicit object
+ *  literal IS assignable to the index signature). The inverse of {@link normalizeHumanInputResult}. */
+export function humanInputResultToJson(result) {
+    if ("values" in result) {
+        return result.other !== undefined
+            ? { values: result.values, other: result.other }
+            : { values: result.values };
+    }
+    if ("isOther" in result)
+        return { value: result.value, isOther: result.isOther };
+    return { value: result.value };
+}
+/** Parse a stored (jsonb) `on_timeout` into a policy. NULL / unrecognized ⇒ the SDK default `fail`;
+ *  a `{ value }` whose value doesn't validate as a result also degrades to `fail` (never strands). */
+export function parseOnTimeout(raw) {
+    if (raw === null || raw === undefined || raw === "fail")
+        return { kind: "fail" };
+    if (typeof raw === "object" && "value" in raw) {
+        const result = storedResultSchema.safeParse(raw.value);
+        if (result.success)
+            return { kind: "value", value: normalizeHumanInputResult(raw.value) };
+    }
+    return { kind: "fail" };
+}
+/**
+ * Validate a raw submission against the gate's spec, producing the typed {@link HumanInputResult}
+ * the program receives. Throws `VALIDATION_FAILED` with a precise message on any mismatch — the
+ * respond surfaces turn that into a 400 so a bad answer never resumes the run with garbage.
+ */
+export function validateHumanInputResponse(spec, raw) {
+    switch (spec.kind) {
+        case "text":
+            return validateText(spec, raw);
+        case "choice":
+            return validateChoice(spec, raw);
+        case "multiselect":
+            return validateMultiSelect(spec, raw);
+    }
+}
+function fail(message) {
+    throw new AppError(ErrorCode.VALIDATION_FAILED, message, { kind: "human_input_invalid" });
+}
+function validateText(spec, raw) {
+    if (typeof raw.value !== "string")
+        fail("This question expects a text `value`.");
+    const value = raw.value;
+    if (spec.required === true && value.trim().length === 0)
+        fail("A response is required.");
+    return { value };
+}
+function validateChoice(spec, raw) {
+    if (typeof raw.value !== "string")
+        fail("This question expects a single `value`.");
+    const value = raw.value;
+    const isOther = !spec.options.includes(value);
+    if (isOther && spec.allowOther === false) {
+        fail(`"${value}" is not one of the allowed options.`);
+    }
+    return { value, isOther };
+}
+function validateMultiSelect(spec, raw) {
+    if (!Array.isArray(raw.values) || !raw.values.every((v) => typeof v === "string")) {
+        fail("This question expects an array of string `values`.");
+    }
+    const values = raw.values;
+    for (const v of values) {
+        if (!spec.options.includes(v))
+            fail(`"${v}" is not one of the allowed options.`);
+    }
+    let other;
+    if (raw.other !== undefined) {
+        if (typeof raw.other !== "string")
+            fail("`other` must be a string.");
+        if (spec.allowOther === false)
+            fail("This question does not allow an open-text answer.");
+        if (raw.other.trim().length > 0)
+            other = raw.other;
+    }
+    const total = values.length + (other !== undefined ? 1 : 0);
+    if (spec.min !== undefined && total < spec.min) {
+        fail(`Select at least ${String(spec.min)} option(s).`);
+    }
+    if (spec.max !== undefined && total > spec.max) {
+        fail(`Select at most ${String(spec.max)} option(s).`);
+    }
+    return other !== undefined ? { values, other } : { values };
+}

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

@@ -0,0 +1,70 @@
+import type { ChatMessage, ChatTurn, ToolSpec } from "@boardwalk-labs/engine/core";
+import type { NormalizedReasoning } from "@boardwalk-labs/workflow";
+/** `POST /runner/v1/runs/{run_id}/inference` (run-token authed; the addressed run must match). */
+export declare const RUNNER_INFERENCE_PATH_RE: RegExp;
+/** Build the inference path for a run. */
+export declare function runnerInferencePath(runId: string): string;
+/** Response content type — newline-delimited JSON frames. */
+export declare const INFERENCE_NDJSON_CONTENT_TYPE = "application/x-ndjson";
+/**
+ * The request body the worker POSTs to `/inference` — one neutral model turn (the engine's
+ * `ModelTurnRequest`, minus the seam: no endpoint, no key). `model`/`provider` are the `agent()`
+ * call's (both opaque, both optional); the broker resolves them SERVER-SIDE against the run's org
+ * (the orgId comes from the verified run token, never the body — so this can't reach another org).
+ */
+export interface InferenceProxyRequest {
+    /** The model id, as the agent() call gave it (opaque, passed verbatim). Undefined ⇒ provider routes. */
+    model: string | undefined;
+    /** The provider the agent() call named (undefined ⇒ the managed `boardwalk` lane). */
+    provider: string | undefined;
+    /** The conversation so far. */
+    messages: readonly ChatMessage[];
+    /** The tools advertised to the model this turn. */
+    tools: readonly ToolSpec[];
+    /** Normalized reasoning-effort control (the agent() call's `AgentOptions.reasoning`, undefined ⇒
+     *  provider default). The broker encodes it into the resolved provider's wire body per protocol. */
+    reasoning?: NormalizedReasoning;
+}
+/** A broker/model error surfaced as the terminal frame so the worker's stream throws. */
+export interface ProxyError {
+    code: string;
+    message: string;
+}
+/** A parsed response frame. `ping` is a no-payload heartbeat the broker emits during a long model
+ *  turn to keep the connection producing bytes (so idle/body timeouts don't sever it); the worker
+ *  ignores it. */
+export type InferenceFrame = {
+    kind: "delta";
+    text: string;
+} | {
+    kind: "result";
+    turn: ChatTurn;
+    modelRef: string;
+    costMicros: number;
+} | {
+    kind: "error";
+    error: ProxyError;
+} | {
+    kind: "ping";
+};
+/** Serialize the request body. (Binary message content — multimodal image/doc bytes — is not yet
+ *  supported on this path; v0 agent flows are text + JSON tool results.) */
+export declare function serializeInferenceRequest(req: InferenceProxyRequest): string;
+/** Parse + minimally validate the request body (the runner is semi-trusted; fail closed on shape).
+ *  The conversation is shape-trusted past the array check — it was built by the engine loop on the
+ *  runner from the broker's own prior frames, and the broker's adapters re-render every field. */
+export declare function parseInferenceRequest(body: string): InferenceProxyRequest;
+/** 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.
+ *  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. */
+export declare function serializeErrorFrame(error: ProxyError): string;
+/** Serialize a heartbeat (no payload) as a single NDJSON line. The broker emits these on an interval
+ *  during a long model turn so the worker↔broker connection keeps producing bytes — neither side's
+ *  idle/body timeout fires while the model is generating but not yet streaming text. */
+export declare function serializeHeartbeatFrame(): string;
+/** Parse one NDJSON frame line. Throws on a malformed/unknown frame (the line must be non-empty). */
+export declare function parseInferenceFrame(line: string): InferenceFrame;

package/dist/runtime/wire/inference_proxy.js

@@ -0,0 +1,157 @@
+// Inference proxy protocol (docs/RUNNER_BROKER.md §4 — "Inference (class 2)").
+//
+// The runner never invokes a model directly: under the Runner Credential Broker it holds no
+// managed-inference creds and no BYO provider key. Instead the `agent()` leaf's model turn (the
+// engine's `LeafIo.streamModel` seam) POSTs the conversation to the broker's `/inference`
+// endpoint; the broker resolves the REAL model server-side (managed under the broker's creds, or a
+// BYO key it reads from Secrets Manager), invokes the matching engine adapter, and streams the
+// model's text back so the loop can show it live.
+//
+// This module is the shared wire contract for that exchange — imported by both the worker client
+// (serialize request / parse response frames) and the broker handler (parse request / serialize
+// response frames), so the two can never drift.
+//
+// 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 — MASTER_SPEC §4.2). 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
+//
+// A well-formed stream is zero-or-more `delta` frames followed by EXACTLY ONE `result` frame, OR a
+// single terminal `error` frame. The neutral conversation shapes (ChatMessage / ChatTurn / ToolSpec)
+// are the engine's `@boardwalk-labs/engine/core` types — so the worker's loop and the broker's
+// adapters speak the same wire as `boardwalk dev` and the self-hosted server (one agent loop).
+/** `POST /runner/v1/runs/{run_id}/inference` (run-token authed; the addressed run must match). */
+export const RUNNER_INFERENCE_PATH_RE = /^\/runner\/v1\/runs\/([^/]+)\/inference$/;
+/** Build the inference path for a run. */
+export function runnerInferencePath(runId) {
+    return `/runner/v1/runs/${runId}/inference`;
+}
+/** Response content type — newline-delimited JSON frames. */
+export const INFERENCE_NDJSON_CONTENT_TYPE = "application/x-ndjson";
+// ---- request serialize / parse ----
+/** Serialize the request body. (Binary message content — multimodal image/doc bytes — is not yet
+ *  supported on this path; v0 agent flows are text + JSON tool results.) */
+export function serializeInferenceRequest(req) {
+    return JSON.stringify(req);
+}
+/** Parse + minimally validate the request body (the runner is semi-trusted; fail closed on shape).
+ *  The conversation is shape-trusted past the array check — it was built by the engine loop on the
+ *  runner from the broker's own prior frames, and the broker's adapters re-render every field. */
+export function parseInferenceRequest(body) {
+    const parsed = JSON.parse(body);
+    const rec = asRecord(parsed);
+    if (rec === null)
+        throw new Error("Inference request must be a JSON object");
+    if (rec.model !== undefined && typeof rec.model !== "string") {
+        throw new Error("Inference request `model` must be a string when present");
+    }
+    if (rec.provider !== undefined && typeof rec.provider !== "string") {
+        throw new Error("Inference request `provider` must be a string when present");
+    }
+    if (!Array.isArray(rec.messages)) {
+        throw new Error("Inference request requires a messages array");
+    }
+    if (!Array.isArray(rec.tools)) {
+        throw new Error("Inference request requires a tools array");
+    }
+    return {
+        model: typeof rec.model === "string" ? rec.model : undefined,
+        provider: typeof rec.provider === "string" ? rec.provider : undefined,
+        // The engine's ChatMessage/ToolSpec are plain JSON-shaped data (no class instances) — they
+        // round-trip through JSON unchanged, so the parsed arrays ARE the wire shapes.
+        messages: rec.messages,
+        tools: rec.tools,
+        // Reasoning is small JSON the engine built via `normalizeReasoning` on the runner; pass it
+        // through when present (an object), and let the broker's adapters render its fields. A
+        // non-object is dropped — the provider default then applies (no reasoning steering).
+        ...(asRecord(rec.reasoning) !== null
+            ? { reasoning: rec.reasoning }
+            : {}),
+    };
+}
+// ---- response frame serialize / parse ----
+/** Serialize one streamed text delta as a single NDJSON line (trailing "\n" included). */
+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.
+ *  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`;
+}
+/** Serialize a terminal error as a single NDJSON line. */
+export function serializeErrorFrame(error) {
+    return `${JSON.stringify({ t: "error", error })}\n`;
+}
+/** Serialize a heartbeat (no payload) as a single NDJSON line. The broker emits these on an interval
+ *  during a long model turn so the worker↔broker connection keeps producing bytes — neither side's
+ *  idle/body timeout fires while the model is generating but not yet streaming text. */
+export function serializeHeartbeatFrame() {
+    return `${JSON.stringify({ t: "ping" })}\n`;
+}
+/** Parse one NDJSON frame line. Throws on a malformed/unknown frame (the line must be non-empty). */
+export function parseInferenceFrame(line) {
+    const parsed = JSON.parse(line);
+    const rec = asRecord(parsed);
+    if (rec === null)
+        throw new Error("Malformed inference frame");
+    switch (rec.t) {
+        case "delta":
+            return { kind: "delta", text: typeof rec.text === "string" ? rec.text : "" };
+        case "result":
+            return {
+                kind: "result",
+                turn: toChatTurn(rec.turn),
+                modelRef: toModelRef(rec.modelRef),
+                // A pre-cost-forwarding broker (rolling deploy) omits this → 0 → the worker falls back to the
+                // representative-rate estimate, exactly as before. Non-number / negative also clamps to 0.
+                costMicros: typeof rec.costMicros === "number" && rec.costMicros > 0 ? rec.costMicros : 0,
+            };
+        case "error":
+            return { kind: "error", error: toProxyError(rec.error) };
+        case "ping":
+            return { kind: "ping" };
+        default:
+            throw new Error(`Unknown inference frame kind: ${String(rec.t)}`);
+    }
+}
+/** Narrow a parsed `result` frame's turn back to the engine's `ChatTurn`, failing closed on shape —
+ *  the worker's loop relies on `toolCalls`/`usage`/`wantsTools` being present and well-typed. */
+function toChatTurn(value) {
+    const rec = asRecord(value);
+    if (rec === null)
+        throw new Error("Inference result frame has no turn");
+    if (typeof rec.text !== "string")
+        throw new Error("Inference result turn missing text");
+    if (!Array.isArray(rec.toolCalls))
+        throw new Error("Inference result turn missing toolCalls");
+    const usage = asRecord(rec.usage) ?? {};
+    return {
+        text: rec.text,
+        toolCalls: rec.toolCalls,
+        usage: {
+            ...(typeof usage.inputTokens === "number" ? { inputTokens: usage.inputTokens } : {}),
+            ...(typeof usage.outputTokens === "number" ? { outputTokens: usage.outputTokens } : {}),
+        },
+        wantsTools: rec.wantsTools === true,
+    };
+}
+function toModelRef(value) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error("Inference result frame missing modelRef");
+    }
+    return value;
+}
+function toProxyError(value) {
+    const rec = asRecord(value);
+    const code = rec !== null && typeof rec.code === "string" ? rec.code : "INTERNAL_ERROR";
+    const message = rec !== null && typeof rec.message === "string" ? rec.message : "Inference failed";
+    return { code, message };
+}
+/** A plain object with string keys, or null. Avoids unsafe casts on parsed JSON. */
+function asRecord(value) {
+    return typeof value === "object" && value !== null ? value : null;
+}

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

@@ -0,0 +1,16 @@
+import type { SecretRef, WorkflowManifest } from "@boardwalk-labs/workflow";
+export { workflowManifestSchema } from "@boardwalk-labs/workflow";
+export type { WorkflowManifest } from "@boardwalk-labs/workflow";
+/** The manifest's zod-derived budget shape (matches the platform's `domain/models` alias). */
+export type Budget = NonNullable<WorkflowManifest["budget"]>;
+/** Pre-rename alias — runtime code (secret resolvers, tool context) imports this name. */
+export type SecretRefManifest = SecretRef;
+/** The secret name a whole-value `${{ secrets.NAME }}` env value references, or null. */
+export declare function parseSecretEnvRef(value: string): string | null;
+/**
+ * The secret names a run may resolve — mirrors the broker's server-side allowlist
+ * (`permissions.secrets` exactly; see the backend's domain/models/manifest.ts).
+ */
+export declare function effectiveSecretAllowlist(manifest: Pick<WorkflowManifest, "permissions">): {
+    name: string;
+}[];

package/dist/runtime/wire/manifest.js

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: Apache-2.0
+export { workflowManifestSchema } from "@boardwalk-labs/workflow";
+/** The ONLY supported interpolation: a whole-value `${{ secrets.NAME }}` reference. */
+const SECRET_ENV_REF_RE = /^\$\{\{\s*secrets\.([A-Za-z0-9_-]+)\s*\}\}$/;
+/** The secret name a whole-value `${{ secrets.NAME }}` env value references, or null. */
+export function parseSecretEnvRef(value) {
+    return SECRET_ENV_REF_RE.exec(value.trim())?.[1] ?? null;
+}
+/**
+ * The secret names a run may resolve — mirrors the broker's server-side allowlist
+ * (`permissions.secrets` exactly; see the backend's domain/models/manifest.ts).
+ */
+export function effectiveSecretAllowlist(manifest) {
+    const names = new Set();
+    for (const ref of manifest.permissions?.secrets ?? [])
+        names.add(ref.name);
+    return [...names].map((name) => ({ name }));
+}