@boardwalk-labs/engine 0.1.0

package/dist/agent/providers.js

@@ -0,0 +1,347 @@
+// Provider adapters for the agent() leaf — two wire protocols cover everything (SPEC §2.3):
+// Anthropic's Messages API (streamed) and OpenAI-style chat completions (the lingua franca of
+// OpenAI, Google's compat surface, vLLM, Ollama, Together, Fireworks, Groq…). Each adapter
+// maps the loop's neutral conversation (conversation.ts) to its wire format and executes ONE
+// model turn; the tool loop itself lives in leaf.ts.
+//
+// Zero SDK dependencies: plain fetch + Zod-validated responses (a provider's response is a
+// trust boundary like any other). Retry policy per CODE_QUALITY §4.3: exponential backoff with
+// jitter on 429/5xx/network errors; a non-rate-limit 4xx never retries.
+import { z } from "zod";
+import { EngineError } from "../errors.js";
+import { isJsonValue, isPlainObject } from "../json_value.js";
+import { sseDataLines } from "./sse.js";
+const DEFAULT_MAX_TOKENS = 8192;
+const RETRY_ATTEMPTS = 5;
+const RETRY_BASE_MS = 500;
+/** An HTTP failure that carries its status so the retry policy can classify it. */
+class ProviderHttpError extends Error {
+    status;
+    constructor(status, body) {
+        super(`provider returned ${String(status)}: ${body.slice(0, 300)}`);
+        this.status = status;
+    }
+}
+// ----------------------------------------------------------------------------
+// Anthropic Messages API (streaming)
+// ----------------------------------------------------------------------------
+function anthropicMessages(messages) {
+    return messages.map((message) => {
+        switch (message.role) {
+            case "user":
+                return { role: "user", content: [{ type: "text", text: message.text }] };
+            case "assistant": {
+                const content = [];
+                if (message.text.length > 0)
+                    content.push({ type: "text", text: message.text });
+                for (const call of message.toolCalls) {
+                    content.push({ type: "tool_use", id: call.id, name: call.name, input: call.input });
+                }
+                return { role: "assistant", content };
+            }
+            case "tool_results":
+                return {
+                    role: "user",
+                    content: message.results.map((result) => ({
+                        type: "tool_result",
+                        tool_use_id: result.id,
+                        content: result.content,
+                        is_error: result.isError,
+                    })),
+                };
+        }
+    });
+}
+const frameHeadSchema = z.looseObject({ type: z.string() });
+const messageStartSchema = z.looseObject({
+    message: z.looseObject({
+        usage: z.looseObject({ input_tokens: z.number().int().nonnegative().optional() }),
+    }),
+});
+const contentBlockStartSchema = z.looseObject({
+    content_block: z.looseObject({
+        type: z.string(),
+        id: z.string().optional(),
+        name: z.string().optional(),
+    }),
+});
+const contentBlockDeltaSchema = z.looseObject({
+    delta: z.looseObject({
+        type: z.string(),
+        text: z.string().optional(),
+        partial_json: z.string().optional(),
+    }),
+});
+const messageDeltaSchema = z.looseObject({
+    delta: z.looseObject({ stop_reason: z.string().nullable().optional() }).optional(),
+    usage: z.looseObject({ output_tokens: z.number().int().nonnegative().optional() }).optional(),
+});
+export async function chatAnthropic(args, io = {}) {
+    const doFetch = io.fetchImpl ?? fetch;
+    const response = await withRetry(io, async () => {
+        const res = await doFetch(`${args.baseUrl}/v1/messages`, {
+            method: "POST",
+            headers: {
+                "anthropic-version": "2023-06-01",
+                ...(args.apiKey !== null ? { "x-api-key": args.apiKey } : {}),
+                // Custom headers win over computed auth (the point: non-standard auth schemes);
+                // content-type comes last — the engine owns the body format.
+                ...args.headers,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                model: args.model,
+                max_tokens: args.maxTokens ?? DEFAULT_MAX_TOKENS,
+                stream: true,
+                messages: anthropicMessages(args.messages),
+                ...(args.tools.length > 0
+                    ? {
+                        tools: args.tools.map((tool) => ({
+                            name: tool.name,
+                            description: tool.description,
+                            input_schema: tool.inputSchema,
+                        })),
+                    }
+                    : {}),
+            }),
+        });
+        if (!res.ok)
+            throw new ProviderHttpError(res.status, await res.text());
+        return res;
+    });
+    let text = "";
+    let inputTokens;
+    let outputTokens;
+    let stopReason = null;
+    const toolCalls = [];
+    // The currently-streaming tool_use block: input arrives as partial JSON deltas.
+    let openToolCall = null;
+    for await (const data of sseDataLines(response)) {
+        const json = safeJson(data);
+        const head = frameHeadSchema.safeParse(json);
+        if (!head.success)
+            continue; // unknown frame kinds are forward compatibility, not errors
+        switch (head.data.type) {
+            case "message_start": {
+                const frame = messageStartSchema.safeParse(json);
+                if (frame.success)
+                    inputTokens = frame.data.message.usage.input_tokens ?? inputTokens;
+                break;
+            }
+            case "content_block_start": {
+                const frame = contentBlockStartSchema.safeParse(json);
+                if (frame.success && frame.data.content_block.type === "tool_use") {
+                    openToolCall = {
+                        id: frame.data.content_block.id ?? `call-${String(toolCalls.length + 1)}`,
+                        name: frame.data.content_block.name ?? "",
+                        partialJson: "",
+                    };
+                }
+                break;
+            }
+            case "content_block_delta": {
+                const frame = contentBlockDeltaSchema.safeParse(json);
+                if (!frame.success)
+                    break;
+                const chunk = frame.data.delta.text;
+                if (chunk !== undefined && chunk.length > 0) {
+                    text += chunk;
+                    io.onDelta?.(chunk);
+                }
+                if (frame.data.delta.partial_json !== undefined && openToolCall !== null) {
+                    openToolCall.partialJson += frame.data.delta.partial_json;
+                }
+                break;
+            }
+            case "content_block_stop": {
+                if (openToolCall !== null) {
+                    toolCalls.push({
+                        id: openToolCall.id,
+                        name: openToolCall.name,
+                        input: parseToolInput(openToolCall.partialJson, openToolCall.name),
+                    });
+                    openToolCall = null;
+                }
+                break;
+            }
+            case "message_delta": {
+                const frame = messageDeltaSchema.safeParse(json);
+                if (frame.success) {
+                    outputTokens = frame.data.usage?.output_tokens ?? outputTokens;
+                    stopReason = frame.data.delta?.stop_reason ?? stopReason;
+                }
+                break;
+            }
+        }
+    }
+    return {
+        text,
+        toolCalls,
+        usage: {
+            ...(inputTokens !== undefined ? { inputTokens } : {}),
+            ...(outputTokens !== undefined ? { outputTokens } : {}),
+        },
+        wantsTools: stopReason === "tool_use" || toolCalls.length > 0,
+    };
+}
+// ----------------------------------------------------------------------------
+// OpenAI-compatible chat completions (non-streaming in v0 — one final delta)
+// ----------------------------------------------------------------------------
+function openAiMessages(messages) {
+    const out = [];
+    for (const message of messages) {
+        switch (message.role) {
+            case "user":
+                out.push({ role: "user", content: message.text });
+                break;
+            case "assistant":
+                out.push({
+                    role: "assistant",
+                    content: message.text.length > 0 ? message.text : null,
+                    ...(message.toolCalls.length > 0
+                        ? {
+                            tool_calls: message.toolCalls.map((call) => ({
+                                id: call.id,
+                                type: "function",
+                                function: { name: call.name, arguments: JSON.stringify(call.input) },
+                            })),
+                        }
+                        : {}),
+                });
+                break;
+            case "tool_results":
+                for (const result of message.results) {
+                    out.push({ role: "tool", tool_call_id: result.id, content: result.content });
+                }
+                break;
+        }
+    }
+    return out;
+}
+const openAiResponseSchema = z.looseObject({
+    choices: z
+        .array(z.looseObject({
+        finish_reason: z.string().nullable().optional(),
+        message: z.looseObject({
+            content: z.string().nullable().optional(),
+            tool_calls: z
+                .array(z.looseObject({
+                id: z.string(),
+                function: z.looseObject({ name: z.string(), arguments: z.string() }),
+            }))
+                .optional(),
+        }),
+    }))
+        .min(1),
+    usage: z
+        .looseObject({
+        prompt_tokens: z.number().int().nonnegative().optional(),
+        completion_tokens: z.number().int().nonnegative().optional(),
+    })
+        .optional(),
+});
+export async function chatOpenAi(args, io = {}) {
+    const doFetch = io.fetchImpl ?? fetch;
+    const response = await withRetry(io, async () => {
+        const res = await doFetch(`${args.baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: {
+                ...(args.apiKey !== null ? { authorization: `Bearer ${args.apiKey}` } : {}),
+                // Custom headers win over computed auth (the point: non-standard auth schemes);
+                // content-type comes last — the engine owns the body format.
+                ...args.headers,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                model: args.model,
+                messages: openAiMessages(args.messages),
+                ...(args.tools.length > 0
+                    ? {
+                        tools: args.tools.map((tool) => ({
+                            type: "function",
+                            function: {
+                                name: tool.name,
+                                description: tool.description,
+                                parameters: tool.inputSchema,
+                            },
+                        })),
+                    }
+                    : {}),
+            }),
+        });
+        if (!res.ok)
+            throw new ProviderHttpError(res.status, await res.text());
+        return res;
+    });
+    const parsed = openAiResponseSchema.safeParse(await response.json());
+    if (!parsed.success) {
+        throw new EngineError("PROVIDER_ERROR", "Provider returned a malformed chat completion.");
+    }
+    const choice = parsed.data.choices[0];
+    const text = choice?.message.content ?? "";
+    if (text.length > 0)
+        io.onDelta?.(text);
+    const toolCalls = (choice?.message.tool_calls ?? []).map((call) => ({
+        id: call.id,
+        name: call.function.name,
+        input: parseToolInput(call.function.arguments, call.function.name),
+    }));
+    const usage = parsed.data.usage;
+    return {
+        text,
+        toolCalls,
+        usage: {
+            ...(usage?.prompt_tokens !== undefined ? { inputTokens: usage.prompt_tokens } : {}),
+            ...(usage?.completion_tokens !== undefined ? { outputTokens: usage.completion_tokens } : {}),
+        },
+        wantsTools: choice?.finish_reason === "tool_calls" || toolCalls.length > 0,
+    };
+}
+// ----------------------------------------------------------------------------
+// Shared plumbing
+// ----------------------------------------------------------------------------
+/** Model-produced tool input is untrusted (CODE_QUALITY §2.1): parse, demand a JSON object. */
+function parseToolInput(raw, toolName) {
+    const value = raw.trim().length === 0 ? {} : safeJson(raw);
+    if (isPlainObject(value) && isJsonValue(value)) {
+        return value;
+    }
+    throw new EngineError("PROVIDER_ERROR", `The model produced malformed input for tool "${toolName}" (not a JSON object).`);
+}
+/** Retry transient failures (429/5xx/network) with exponential backoff + jitter. */
+async function withRetry(io, fn) {
+    const sleep = io.sleepImpl ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    let lastError;
+    for (let attempt = 0; attempt < RETRY_ATTEMPTS; attempt++) {
+        if (attempt > 0) {
+            await sleep(RETRY_BASE_MS * 2 ** (attempt - 1) + Math.random() * 250);
+        }
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            if (err instanceof ProviderHttpError) {
+                const retryable = err.status === 429 || err.status >= 500;
+                if (!retryable) {
+                    throw new EngineError("PROVIDER_ERROR", err.message);
+                }
+                continue;
+            }
+            // fetch network failures surface as TypeError — retryable; anything else is a bug.
+            if (err instanceof TypeError)
+                continue;
+            throw err;
+        }
+    }
+    const detail = lastError instanceof Error ? lastError.message : String(lastError);
+    throw new EngineError("PROVIDER_ERROR", `Provider still failing after ${String(RETRY_ATTEMPTS)} attempts: ${detail}`);
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/agent/rates.d.ts

@@ -0,0 +1,13 @@
+export interface TokenRate {
+    /** USD per million input tokens. */
+    inUsdPerMtok: number;
+    /** USD per million output tokens. */
+    outUsdPerMtok: number;
+}
+/** The approximate rate for a model ref. Never returns zero — budgets must always accrue. */
+export declare function rateFor(modelRef: string): TokenRate;
+/** Approximate cost of a usage report in micro-USD (integers end-to-end; SQLite-friendly). */
+export declare function usageUsdMicros(modelRef: string, usage: {
+    inputTokens?: number | undefined;
+    outputTokens?: number | undefined;
+}): number;

package/dist/agent/rates.js

@@ -0,0 +1,35 @@
+// The approximate token-price table behind budget.max_usd (SPEC §2.2: "USD via a bundled
+// approximate rate table, documented as approximate").
+//
+// This is a GUARDRAIL, not a bill: the engine never charges anyone — it terminates a run that
+// crosses the author's declared ceiling. Prices drift; entries here are deliberately coarse
+// pattern matches with a conservative default, so an unknown model still consumes budget
+// rather than running unmetered.
+// Order matters: first match wins, most-specific first.
+const RULES = [
+    { pattern: /claude-opus/i, rate: { inUsdPerMtok: 15, outUsdPerMtok: 75 } },
+    { pattern: /claude-sonnet/i, rate: { inUsdPerMtok: 3, outUsdPerMtok: 15 } },
+    { pattern: /claude-haiku/i, rate: { inUsdPerMtok: 1, outUsdPerMtok: 5 } },
+    { pattern: /\bo[13](-|$)/i, rate: { inUsdPerMtok: 15, outUsdPerMtok: 60 } },
+    { pattern: /gpt-4o-mini/i, rate: { inUsdPerMtok: 0.15, outUsdPerMtok: 0.6 } },
+    { pattern: /gpt-4o|gpt-4\.1/i, rate: { inUsdPerMtok: 2.5, outUsdPerMtok: 10 } },
+    { pattern: /gemini-.*-pro/i, rate: { inUsdPerMtok: 1.25, outUsdPerMtok: 10 } },
+    { pattern: /gemini-.*-flash/i, rate: { inUsdPerMtok: 0.15, outUsdPerMtok: 0.6 } },
+];
+/** Why mid-tier: an unknown model priced at zero would make max_usd unenforceable. */
+const DEFAULT_RATE = { inUsdPerMtok: 3, outUsdPerMtok: 15 };
+/** The approximate rate for a model ref. Never returns zero — budgets must always accrue. */
+export function rateFor(modelRef) {
+    for (const rule of RULES) {
+        if (rule.pattern.test(modelRef))
+            return rule.rate;
+    }
+    return DEFAULT_RATE;
+}
+/** Approximate cost of a usage report in micro-USD (integers end-to-end; SQLite-friendly). */
+export function usageUsdMicros(modelRef, usage) {
+    const rate = rateFor(modelRef);
+    const inUsd = ((usage.inputTokens ?? 0) / 1_000_000) * rate.inUsdPerMtok;
+    const outUsd = ((usage.outputTokens ?? 0) / 1_000_000) * rate.outUsdPerMtok;
+    return Math.round((inUsd + outUsd) * 1_000_000);
+}

package/dist/agent/redact.d.ts

@@ -0,0 +1,9 @@
+export declare class Redactor {
+    private readonly values;
+    /** Register a secret value under a label (its declared name). Short values are ignored —
+     *  redacting 1–3 chars would shred ordinary text while protecting nothing. */
+    add(label: string, value: string): void;
+    /** Scrub every registered value out of `text`, longest value first so substrings of a longer
+     *  secret can't leave recoverable fragments behind. */
+    redact(text: string): string;
+}

package/dist/agent/redact.js

@@ -0,0 +1,27 @@
+// Secret redaction for the agent() leaf (MASTER_SPEC §6.2, CODE_QUALITY §7.4).
+//
+// The invariant: secret VALUES live only in deterministic program code; everything bound for a
+// model — prompts now, tool args/results/MCP traffic/skills/memory later — is scrubbed of every
+// known secret value first, so prompt injection has nothing to exfiltrate. "Known" means every
+// value the run has actually been handed: secrets.get results and provider API keys.
+export class Redactor {
+    values = new Map(); // value → label
+    /** Register a secret value under a label (its declared name). Short values are ignored —
+     *  redacting 1–3 chars would shred ordinary text while protecting nothing. */
+    add(label, value) {
+        if (value.length >= 4)
+            this.values.set(value, label);
+    }
+    /** Scrub every registered value out of `text`, longest value first so substrings of a longer
+     *  secret can't leave recoverable fragments behind. */
+    redact(text) {
+        if (this.values.size === 0)
+            return text;
+        let out = text;
+        const byLength = [...this.values.entries()].sort((a, b) => b[0].length - a[0].length);
+        for (const [value, label] of byLength) {
+            out = out.split(value).join(`[redacted:${label}]`);
+        }
+        return out;
+    }
+}

package/dist/agent/resolve.d.ts

@@ -0,0 +1,58 @@
+/** Wire protocol an endpoint speaks. Anthropic has its own; everything else is OpenAI-shaped. */
+export type ProviderProtocol = "anthropic" | "openai";
+/** The default provider when an agent() call names none. */
+export declare const BOARDWALK_PROVIDER = "boardwalk";
+/** A custom header value: a static string, or `{ from_env }` to read it from the engine's
+ *  environment at call time (for secret-bearing headers — values never sit in config). */
+export type HeaderValue = string | {
+    from_env: string;
+};
+/** One entry in the engine config's provider table. */
+export interface ProviderConfig {
+    /** OpenAI-compatible endpoint base URL (e.g. http://localhost:11434/v1 for a local Ollama). */
+    base_url: string;
+    /** Env var holding the API key. Omit for endpoints that need none (local servers). */
+    api_key_env?: string;
+    /** Defaults to "openai" — the lingua franca of self-hosted/compatible endpoints. */
+    protocol?: ProviderProtocol;
+    /**
+     * Extra request headers, for endpoints whose auth isn't bearer/x-api-key shaped (e.g. Azure
+     * OpenAI's `api-key`). Custom headers WIN over the computed auth header on collision;
+     * `content-type` is engine-owned and cannot be overridden. `{ from_env }` values are
+     * redacted from all model-bound context, like the API key.
+     */
+    headers?: Record<string, HeaderValue>;
+}
+export interface InferenceConfig {
+    /** Used when an agent() call omits `model` — still passed VERBATIM to the chosen provider. */
+    default_model?: string;
+    /** Named providers, selected per call via `opts.provider`. */
+    providers?: Record<string, ProviderConfig>;
+    /** Override the Boardwalk managed-inference gateway URL (else BOARDWALK_INFERENCE_URL, else the default). */
+    boardwalk_base_url?: string;
+}
+export interface ResolvedModel {
+    /** Who fulfills the call. */
+    provider: string;
+    /** The model string, exactly as the program supplied it (or the configured/auto default). */
+    model: string;
+    protocol: ProviderProtocol;
+    baseUrl: string;
+    /** Plaintext key, resolved from the environment. Null when the provider needs none. */
+    apiKey: string | null;
+    /** Extra request headers, already resolved (custom auth schemes, org headers, …). */
+    headers: Record<string, string>;
+    /** Names of `headers` whose values came from the environment — redacted like the API key. */
+    secretHeaderNames: readonly string[];
+}
+export interface ResolveArgs {
+    /** The agent() call's `model`, if given. Opaque — never parsed. */
+    model?: string | undefined;
+    /** The agent() call's `provider`, if given. Default: the Boardwalk managed lane. */
+    provider?: string | undefined;
+    config: InferenceConfig;
+    /** Secret/env lookup (the engine's env map layered over process.env). */
+    getEnv: (name: string) => string | undefined;
+}
+/** Resolve an agent() call to a concrete endpoint + key, or throw with a pointer at the fix. */
+export declare function resolveModel(args: ResolveArgs): ResolvedModel;

package/dist/agent/resolve.js

@@ -0,0 +1,153 @@
+// Model + provider resolution for the agent() leaf (SPEC §2.3 "model resolution").
+//
+// `provider` and `model` are ORTHOGONAL (decided 2026-06-12):
+//   - `provider` picks who FULFILLS the call. Default: `boardwalk` (managed inference).
+//   - `model` is an OPAQUE string passed VERBATIM to that provider. The engine never parses,
+//     prefixes, or rewrites it — if a local server hosts "anthropic/sonnet-4.5", that exact
+//     string is what the server receives.
+//
+// Inference is EXPLICIT: the engine never silently reaches for a user's own provider key.
+// Using your own key (a built-in vendor) or any configured endpoint — including a LOCAL
+// OpenAI-compatible server — requires naming the provider. With no provider named, the call
+// goes to the Boardwalk managed lane, which is "set up" iff BOARDWALK_API_KEY is present;
+// otherwise it errors with every way to fix it.
+//
+// Pure function: the supervisor calls it server-side so engine config and key material stay
+// out of reach of anything but the run that asked.
+import { EngineError } from "../errors.js";
+/** The default provider when an agent() call names none. */
+export const BOARDWALK_PROVIDER = "boardwalk";
+// What the managed lane is asked for when no model is named — the gateway routes ("Auto").
+// NOTE (pending the gateway contract): confirm the route-for-me signal against the real
+// Boardwalk inference gateway API; this engine sends model: "auto".
+const AUTO_MODEL = "auto";
+// The Boardwalk managed-inference gateway (OpenAI-compatible). `boardwalk.sh` is the placeholder
+// domain (MASTER_SPEC stack notes); override with BOARDWALK_INFERENCE_URL or config. The Auto
+// ROUTER itself lives in hosted Boardwalk — this engine only forwards to the gateway.
+const DEFAULT_BOARDWALK_INFERENCE_URL = "https://api.boardwalk.sh/v1";
+// Built-in direct-call providers — used only when NAMED explicitly; key from the conventional
+// env var. The engine never auto-selects one (that would be spending your key without you
+// asking); you opt in with `provider: "anthropic"` etc.
+const BUILTINS = {
+    anthropic: {
+        protocol: "anthropic",
+        baseUrl: "https://api.anthropic.com",
+        keyEnvs: ["ANTHROPIC_API_KEY"],
+    },
+    openai: {
+        protocol: "openai",
+        baseUrl: "https://api.openai.com/v1",
+        keyEnvs: ["OPENAI_API_KEY"],
+    },
+    google: {
+        // Why the /openai path: Google publishes an OpenAI-compatible surface for Gemini; using it
+        // keeps this engine at two wire protocols instead of three.
+        protocol: "openai",
+        baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai",
+        keyEnvs: ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
+    },
+};
+/** Resolve an agent() call to a concrete endpoint + key, or throw with a pointer at the fix. */
+export function resolveModel(args) {
+    const provider = args.provider ?? BOARDWALK_PROVIDER;
+    const model = args.model ?? args.config.default_model;
+    if (provider === BOARDWALK_PROVIDER) {
+        return resolveBoardwalk(model, args);
+    }
+    // Only the managed lane routes for you — an explicit provider needs a model.
+    if (model === undefined || model.length === 0) {
+        throw new EngineError("MODEL_UNRESOLVED", `Provider "${provider}" needs a model.`, `Pass { model: "..." } with whatever model id "${provider}" expects, or set ` +
+            "inference.default_model in the engine config.");
+    }
+    const configured = args.config.providers?.[provider];
+    if (configured !== undefined) {
+        return resolveConfigured(provider, model, configured, args.getEnv);
+    }
+    const builtin = BUILTINS[provider];
+    if (builtin !== undefined) {
+        return resolveBuiltin(provider, model, builtin, args.getEnv);
+    }
+    throw new EngineError("MODEL_UNRESOLVED", `Unknown inference provider "${provider}".`, `Built-ins: ${Object.keys(BUILTINS).join(", ")}, plus "${BOARDWALK_PROVIDER}" (managed, the ` +
+        `default). Any OpenAI-compatible endpoint — including a local server — works via ` +
+        `inference.providers.${provider} = { base_url, api_key_env } in the engine config.`);
+}
+/** The managed lane: forward to the Boardwalk gateway. "Set up" iff BOARDWALK_API_KEY is present. */
+function resolveBoardwalk(model, args) {
+    const apiKey = args.getEnv("BOARDWALK_API_KEY");
+    if (apiKey === undefined || apiKey.length === 0) {
+        throw new EngineError("MODEL_UNRESOLVED", "No inference is set up for this run. agent() defaults to Boardwalk managed inference, " +
+            "but BOARDWALK_API_KEY is not set.", "Set BOARDWALK_API_KEY to use Boardwalk managed inference, or name a provider explicitly: " +
+            '{ provider: "anthropic" } (or openai/google) with that provider\'s API key set, or ' +
+            "point inference.providers at any OpenAI-compatible server — including a local one " +
+            "like Ollama.");
+    }
+    const baseUrl = args.config.boardwalk_base_url ??
+        args.getEnv("BOARDWALK_INFERENCE_URL") ??
+        DEFAULT_BOARDWALK_INFERENCE_URL;
+    return {
+        provider: BOARDWALK_PROVIDER,
+        model: model !== undefined && model.length > 0 ? model : AUTO_MODEL,
+        protocol: "openai",
+        baseUrl,
+        apiKey,
+        headers: {},
+        secretHeaderNames: [],
+    };
+}
+function resolveConfigured(provider, model, configured, getEnv) {
+    let apiKey = null;
+    if (configured.api_key_env !== undefined) {
+        const value = getEnv(configured.api_key_env);
+        if (value === undefined || value.length === 0) {
+            throw new EngineError("PROVIDER_ERROR", `Provider "${provider}" needs an API key but ${configured.api_key_env} is not set.`, `Set ${configured.api_key_env} in the engine's environment.`);
+        }
+        apiKey = value;
+    }
+    const { headers, secretHeaderNames } = resolveHeaders(provider, configured.headers, getEnv);
+    return {
+        provider,
+        model,
+        protocol: configured.protocol ?? "openai",
+        baseUrl: configured.base_url,
+        apiKey,
+        headers,
+        secretHeaderNames,
+    };
+}
+/** Resolve a provider's custom header map; `{ from_env }` values are looked up fail-closed. */
+function resolveHeaders(provider, configured, getEnv) {
+    const headers = {};
+    const secretHeaderNames = [];
+    for (const [name, value] of Object.entries(configured ?? {})) {
+        if (name.toLowerCase() === "content-type") {
+            // The engine owns the body format; a configured content-type would silently break it.
+            throw new EngineError("VALIDATION", `Provider "${provider}" configures a content-type header — the engine owns that header.`);
+        }
+        if (typeof value === "string") {
+            headers[name] = value;
+            continue;
+        }
+        const resolved = getEnv(value.from_env);
+        if (resolved === undefined || resolved.length === 0) {
+            throw new EngineError("PROVIDER_ERROR", `Provider "${provider}" header "${name}" needs ${value.from_env}, which is not set.`, `Set ${value.from_env} in the engine's environment.`);
+        }
+        headers[name] = resolved;
+        secretHeaderNames.push(name);
+    }
+    return { headers, secretHeaderNames };
+}
+function resolveBuiltin(provider, model, builtin, getEnv) {
+    const apiKey = builtin.keyEnvs.map(getEnv).find((v) => v !== undefined && v.length > 0);
+    if (apiKey === undefined) {
+        throw new EngineError("PROVIDER_ERROR", `Provider "${provider}" needs an API key but ${builtin.keyEnvs.join(" / ")} is not set.`, `Set ${builtin.keyEnvs[0] ?? "the provider API key"} in the engine's environment.`);
+    }
+    return {
+        provider,
+        model,
+        protocol: builtin.protocol,
+        baseUrl: builtin.baseUrl,
+        apiKey,
+        headers: {},
+        secretHeaderNames: [],
+    };
+}

package/dist/agent/sse.d.ts

@@ -0,0 +1,2 @@
+/** Iterate the `data:` payloads of an SSE response body. */
+export declare function sseDataLines(response: Response): AsyncGenerator<string>;