@boardwalk-labs/runner 0.1.2

package/dist/runtime/credit_watcher.js

@@ -0,0 +1,78 @@
+// CreditWatcher — stops a run when its org runs out of prepaid credit mid-flight (MASTER_SPEC §15 +
+// docs/CODING_AGENT.md §6/§10).
+//
+// One per run session. On a timer it asks — through the broker (`GET /credit`, since the runner holds
+// no Stripe credential) — whether the org is still funded; the FIRST time it isn't, it fires
+// `onExhausted` once (the orchestrator wires this to `AbortController.abort`, which the WorkflowHost
+// honors cooperatively) and stops checking. This is the org-level counterpart to the per-run
+// BudgetMeter cap: the run can't see Stripe balances, so funding is enforced here, out of band,
+// against the live balance that incremental token metering keeps fresh.
+//
+// "Prompt, not instant": Stripe meter aggregation is eventually-consistent and the host honors the
+// abort at the next hook boundary, so a run stops within ~one check interval (plus Stripe's lag) of
+// going unfunded — bounding overshoot, not eliminating it. Applies to MANAGED and BYOK runs alike,
+// since runtime always burns credit (the gate requires the runtime floor regardless of token billing).
+import { createLogger } from "./support/index.js";
+const log = createLogger("CreditWatcher");
+/** Default funding-check cadence. */
+export const DEFAULT_CREDIT_CHECK_INTERVAL_MS = 60_000;
+export class CreditWatcher {
+    deps;
+    timer = null;
+    firing = Promise.resolve();
+    exhausted = false;
+    stopped = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Begin periodic funding checks. */
+    start() {
+        if (this.timer !== null)
+            return;
+        const interval = this.deps.intervalMs ?? DEFAULT_CREDIT_CHECK_INTERVAL_MS;
+        this.timer = setInterval(() => {
+            this.firing = this.firing.then(() => this.check());
+        }, interval);
+        // Don't keep the worker process alive solely for the credit timer.
+        this.timer.unref();
+    }
+    /** Stop checking and drain any in-flight check. Idempotent. */
+    async stop() {
+        this.stopped = true;
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.firing.catch(() => undefined);
+    }
+    /** Whether exhaustion was detected (the orchestrator may read this to shape the terminal result). */
+    isExhausted() {
+        return this.exhausted;
+    }
+    /** True once the watcher should no longer act. A method (not an inline field read) so it's
+     *  re-evaluated after an `await` — `stop()` can flip `stopped` mid-check. */
+    done() {
+        return this.stopped || this.exhausted;
+    }
+    async check() {
+        if (this.done())
+            return;
+        let funded;
+        try {
+            funded = await this.deps.isFunded();
+        }
+        catch (err) {
+            // A failed balance check must NOT kill a paying run — log and let the next tick retry.
+            log.warn("credit_check_failed", {
+                runId: this.deps.runId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return;
+        }
+        if (funded || this.done())
+            return;
+        this.exhausted = true;
+        log.info("run_credit_exhausted", { runId: this.deps.runId });
+        this.deps.onExhausted();
+    }
+}

package/dist/runtime/direct_inference.d.ts

@@ -0,0 +1,29 @@
+import type { ChatMessage, ChatTurn, ToolSpec } from "@boardwalk-labs/engine/core";
+import type { NormalizedReasoning } from "@boardwalk-labs/workflow";
+import { type ByoInferenceProvider } from "../contract.js";
+/** Parse the claim-delivered registry (BOARDWALK_BYO_PROVIDERS). Absent/malformed ⇒ empty —
+ *  the run still works; BYO calls simply fall back to the broker's clear error. */
+export declare function parseByoProviders(raw: string | undefined): ByoInferenceProvider[];
+/** The registry entry for a per-`agent()` provider name, when the runtime may call it
+ *  directly. Null ⇒ use the broker (managed lane, unknown provider, or a brokered-only
+ *  source like bedrock). */
+export declare function directProviderFor(registry: readonly ByoInferenceProvider[], provider: string | undefined): ByoInferenceProvider | null;
+export interface DirectTurnRequest {
+    model: string;
+    messages: readonly ChatMessage[];
+    tools: readonly ToolSpec[];
+    reasoning?: NormalizedReasoning;
+}
+export interface DirectInferenceDeps {
+    registry: readonly ByoInferenceProvider[];
+    /** Resolves the provider's auth secret by NAME (the run's RecordingSecretResolver, so the
+     *  value registers with the redactor). */
+    resolveSecret: (name: string) => Promise<string>;
+    fetchImpl?: typeof fetch;
+}
+/** One model turn, straight to the org's endpoint. Returns the ChatTurn + canonical model ref;
+ *  BYO carries no platform cost (costMicros stays 0 — BYO is never metered). */
+export declare function streamDirectTurn(deps: DirectInferenceDeps, entry: ByoInferenceProvider, req: DirectTurnRequest, onDelta: ((text: string) => void) | undefined): Promise<{
+    turn: ChatTurn;
+    modelRef: string;
+}>;

package/dist/runtime/direct_inference.js

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+// Runner-direct BYO inference (docs/SELF_HOSTED_RUNNERS.md D7): the managed lane stays
+// brokered (the platform key never leaves the platform), but a BYO provider is the ORG'S OWN
+// endpoint + key — class-3 material the runner may hold — so the runtime calls it directly
+// with the SAME engine adapters the broker uses. This is what makes a LAN-only model work on
+// a runner inside that LAN, and it removes a hop for public BYO endpoints.
+//
+// Scope: key-based HTTP providers (openai_compatible / openai / azure_openai / anthropic).
+// `bedrock` (and anything credentialed by a cross-account role rather than an org secret)
+// STAYS brokered — that credential is the broker's to assume, never the runner's.
+//
+// The provider registry arrives as DATA on the claim (BOARDWALK_BYO_PROVIDERS: name, adapter
+// source, base_url, auth secret NAME). The key resolves once per provider through the broker's
+// secrets endpoint via the run's RecordingSecretResolver, so the value registers with the
+// SecretRedactor and can never leak into LLM context, events, or logs.
+import { chatAnthropic, chatOpenAi } from "@boardwalk-labs/engine/core";
+import { z } from "zod";
+import { byoInferenceProviderSchema } from "../contract.js";
+import { createLogger } from "./support/index.js";
+const log = createLogger("DirectInference");
+/** The adapter sources the runtime can call directly (a key-based HTTP request). */
+const DIRECT_SOURCES = new Set(["openai_compatible", "openai", "azure_openai", "anthropic"]);
+/** Parse the claim-delivered registry (BOARDWALK_BYO_PROVIDERS). Absent/malformed ⇒ empty —
+ *  the run still works; BYO calls simply fall back to the broker's clear error. */
+export function parseByoProviders(raw) {
+    if (raw === undefined || raw.trim().length === 0)
+        return [];
+    try {
+        const parsed = z.array(byoInferenceProviderSchema).safeParse(JSON.parse(raw));
+        if (!parsed.success) {
+            log.warn("byo_registry_invalid", { issues: parsed.error.issues.length });
+            return [];
+        }
+        return parsed.data;
+    }
+    catch {
+        log.warn("byo_registry_unparseable", {});
+        return [];
+    }
+}
+/** The registry entry for a per-`agent()` provider name, when the runtime may call it
+ *  directly. Null ⇒ use the broker (managed lane, unknown provider, or a brokered-only
+ *  source like bedrock). */
+export function directProviderFor(registry, provider) {
+    if (provider === undefined || provider === "boardwalk")
+        return null;
+    const entry = registry.find((p) => p.name === provider);
+    if (entry === undefined)
+        return null;
+    if (!DIRECT_SOURCES.has(entry.source) || entry.base_url === null)
+        return null;
+    return entry;
+}
+/** One model turn, straight to the org's endpoint. Returns the ChatTurn + canonical model ref;
+ *  BYO carries no platform cost (costMicros stays 0 — BYO is never metered). */
+export async function streamDirectTurn(deps, entry, req, onDelta) {
+    const apiKey = entry.auth_secret_name === null ? null : await deps.resolveSecret(entry.auth_secret_name);
+    if (entry.base_url === null) {
+        throw new Error(`BYO provider '${entry.name}' has no base_url`);
+    }
+    const args = {
+        baseUrl: entry.base_url,
+        apiKey,
+        model: req.model,
+        messages: req.messages,
+        tools: req.tools,
+        ...(req.reasoning !== undefined ? { reasoning: req.reasoning } : {}),
+    };
+    const io = {
+        ...(deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {}),
+        ...(onDelta !== undefined ? { onDelta } : {}),
+    };
+    log.debug("direct_turn", { provider: entry.name, source: entry.source, model: req.model });
+    const turn = entry.source === "anthropic"
+        ? await chatAnthropic(args, io)
+        : await chatOpenAi({ ...args, reasoningStyle: "openai_effort" }, io);
+    return { turn, modelRef: `${entry.name}/${req.model}` };
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,85 @@
+import type { AuthContext } from "./support/index.js";
+import type { Run } from "./wire/run.js";
+import type { ByoInferenceProvider } from "../contract.js";
+import { type ProgramWorkerDeps } from "./program_worker.js";
+/** Constructed primitives the pure assembly consumes (real ones in main(), fakes in tests). The
+ *  runner holds NO platform credential — only the per-run control-plane handle (run token + broker
+ *  URL); everything else is reached through the Runner Control API (docs/RUNNER_BROKER.md). */
+export interface WorkerRuntime {
+    /** Stable worker identity stamped onto the lease (ECS task arn / hostname / run-derived). */
+    workerId: string;
+    /** Sandbox workspace root for filesystem/shell/git tools. */
+    workspaceRoot: string;
+    /** The run this worker task is executing (RUN_ID) — binds the Runner Control API client. */
+    runId: string;
+    /** The org's BYO inference providers (claim-delivered, BOARDWALK_BYO_PROVIDERS) for the
+     *  runner-direct model path (D7). Empty/omitted ⇒ every model call goes through the broker. */
+    byoProviders?: readonly ByoInferenceProvider[];
+    /** Broker control-plane handle (run token + base URL), injected by the dispatcher as
+     *  BOARDWALK_CONTROL_PLANE_URL + BOARDWALK_RUN_TOKEN. The runner's ONLY broker credential.
+     *  `apiToken` is the run's separate public-API bearer (was BOARDWALK_API_KEY) — served to the
+     *  program on demand via `runtime.apiToken()`, never placed back into process.env. */
+    controlPlane: {
+        baseUrl: string;
+        runToken: string;
+        apiToken?: string;
+    };
+    /** vCPUs provisioned for this task (the dispatcher's resolved machine size ÷ 1024 cpu units). Runtime
+     *  is billed per vCPU-SECOND, so the RuntimeFlusher scales wall-clock by this. Defaults to 1. */
+    vcpus: number;
+}
+/** Durable events are deferred (run_step_events table) — live fan-out via the broker only. */
+/** Synthesize the run's AuthContext. The run was already authorized at trigger time; the
+ *  worker acts on the org's behalf, so it carries the org + an owner role. Tool-level
+ *  boundaries (the broker's server-side manifest allowlist) are the real guard.
+ *
+ *  source='workflow' (NOT 'session_jwt'): the program must never perform SESSION_JWT_ONLY
+ *  credential mutations (§12.11), so a tool that ever exposed such a service is denied by
+ *  construction regardless of the owner role. */
+export declare function workerAuthContext(run: Run): AuthContext;
+/**
+ * Sequencer for per-call token-metering identifiers, `<runId>:<sessionId>:<leafIndex>:<turnSeq>`.
+ *
+ * The worker's `meterUsage` hook fires once per model TURN (the engine's leaf loop reports usage
+ * after every model call), but the display aggregate is idempotent on this identifier
+ * (UsageEventRepository.recordAndAggregate → `onConflictDoNothing`). A key that didn't vary per call
+ * (it was `<runId>:<sessionId>:<leafIndex>`) collapsed every turn after a leaf's first into a dropped
+ * duplicate — so `runs.tokens_in/out` reflected only each leaf's FIRST turn and under-reported
+ * multi-turn leaves by orders of magnitude, even as the BudgetMeter (which accumulates every turn)
+ * still tripped on the real spend. Bumping a per-session counter gives every turn its own idempotent
+ * event. Restart safety rides the session id (a fresh `meteringSessionId` per worker session) — a
+ * restart genuinely re-spends inference, so it must re-meter rather than dedupe against a prior run.
+ */
+export declare function tokenMeterIdentifiers(runId: string, sessionId: string): (leafIndex: number) => string;
+/** Pure wiring: build the full ProgramWorkerDeps from the control-plane handle. The runner reaches
+ *  every privileged seam through the broker over its run token — no DB / Redis / Stripe / model creds. */
+export declare function assembleWorkerDeps(runtime: WorkerRuntime): ProgramWorkerDeps;
+/**
+ * The per-run platform values the dispatcher injects as container env (ecs_run_task_client.ts). They
+ * are captured into private worker state at bootstrap and DELETED from `process.env` before any user
+ * program / agent leaf / subprocess can run — the run token + API token are credentials, and nothing
+ * untrusted run code touches should inherit them (docs/RUN_ENV_AND_CREDS.md). The user owns the rest
+ * of `process.env` outright.
+ */
+export declare const PLATFORM_ENV_KEYS: readonly ["RUN_ID", "BOARDWALK_CONTROL_PLANE_URL", "BOARDWALK_RUN_TOKEN", "BOARDWALK_API_KEY", "BOARDWALK_TASK_CPU_UNITS"];
+/** The captured platform context, shaped to feed {@link assembleWorkerDeps}. */
+export interface PlatformContext {
+    runId: string;
+    controlPlane: {
+        baseUrl: string;
+        runToken: string;
+        apiToken?: string;
+    };
+    vcpus: number;
+}
+/** The public-API origin a run uses for raw API / MCP / CLI calls. The broker (Runner Control API)
+ *  is hosted on the api-server, so the public API shares its origin; the program appends `/v1` or
+ *  `/mcp/v1`. Falls back to the broker URL unchanged if it can't be parsed. */
+export declare function publicApiOrigin(controlPlaneBaseUrl: string): string;
+/**
+ * Read the dispatcher-injected platform context from `env`, then DELETE every {@link PLATFORM_ENV_KEYS}
+ * key from it so the user program, the agent leaf, and any subprocess inherit none of them. Mutates
+ * `env` (called once on `process.env` at the very top of `main`, before any run code can read it).
+ */
+export declare function capturePlatformContext(env: NodeJS.ProcessEnv): PlatformContext;
+export declare function main(): Promise<void>;