@boardwalk-labs/runner 0.2.17 → 0.3.0

package/dist/runtime/budget_gate.js

@@ -1,10 +1,70 @@
 // SPDX-License-Identifier: MIT
+// The budget gate (docs/SUSPEND_POLICY.md Decision 3): when a run hits ANY of its budget caps —
+// `max_usd`, `max_tokens`, or `max_compute_seconds` — PARK and ask a person instead of failing the
+// run.
+//
+// Why park rather than throw: on the snapshot fleet a park costs a memory snapshot and releases the
+// host, so "wait for a human" is effectively free — while a hard failure discards everything the run
+// has done (a real run lost ~40 minutes of paid agent work to a cap breach with no warning). The cap
+// stops being a cliff and becomes a checkpoint.
+//
+// This module is the POLICY (when to park, what to ask, what an answer means). The MECHANISM is the
+// host's `budgetClearance` (register-without-release + freeze), which is the same machinery any
+// `humanInput()` gate uses.
+//
+// ## Park points (where `clear()` is awaited)
+//
+//   - the leaf executor's `streamModel` seam, before EVERY model call — the only place `usd` and
+//     `tokens` can move, so they always park here within one in-flight turn of the breach;
+//   - the workflow host's blocking/spending capability seams (`sleep`, `shell`, `workflows.call`) —
+//     `compute` burns continuously, so a breach between model calls parks at whichever capability
+//     the program touches next;
+//   - between seams, {@link ComputeBreachWatcher} detects a compute breach on a timer. It cannot
+//     itself freeze the VM (see its doc block — true park-anywhere needs fleet-host coordination),
+//     so its job is prompt detection + logging; the park still lands at the next seam above.
+//
+// ## The answer wire format (what backend/web/CLI must send back)
+//
+// The gate registers as an ordinary human-input row, key `budget`, with a `choice` input spec:
+//
+//   { kind: "choice", options: [<dimension presets>, "cancel"], other: true }
+//
+// The presets are dimension-native (render them as the row's buttons verbatim):
+//
+//   usd      "+$10"   | "+$25" | "+$100"
+//   tokens   "+100k"  | "+1M"  | "+10M"
+//   compute  "+15min" | "+1h"  | "+4h"
+//
+// The ANSWER is a single string (a chosen option, or a free-form value via the choice's `other`),
+// interpreted against the dimension the gate asked about (the runner knows which dimension parked;
+// the answer does not repeat it). Grammar, per dimension — `+` prefix = INCREMENT on the current
+// cap, no prefix = ABSOLUTE new cap:
+//
+//   usd      "+$25", "+25"            → cap + 25 dollars;   "50", "$50"       → cap = $50
+//   tokens   "+100k", "+1M", "+2500000" → cap + that many;  "5M", "750k", "2000000" → cap = that
+//            (k = thousand, M = million, case-insensitive, fractions allowed: "+2.5M")
+//   compute  "+15min", "+1h", "+90s", "+600" → cap + that;  "2h", "90min", "5400" → cap = that
+//            (bare number = seconds; s / min / m = minutes / h accepted, fractions allowed: "1.5h")
+//
+// "cancel" (any case), an empty answer, an unparseable answer, or an absolute value at or below the
+// current cap (it would re-park instantly) all CANCEL the run — never guess at a misread answer,
+// resuming spends real money. An approved increment too small to clear the breach re-asks (the
+// `clear()` loop), so a responder can never resume a run into an instant re-park.
+//
+// NOTE (inherited from the usd-only gate): concurrent leaves that breach together each register
+// their own `budget` gate row; answering each with an increment applies each increment. Approvals
+// are explicit per-row human actions, so this compounds by design.
+import { createLogger } from "./support/index.js";
+const log = createLogger("BudgetGate");
 /** The stable key a responder answers a budget gate by (`boardwalk respond <runId> budget …`). */
 export const BUDGET_GATE_KEY = "budget";
-/** Preset approvals, plus the two open-ended answers. Kept small: the point is a fast decision. */
-export const BUDGET_CHOICE_ADD_10 = "+$10";
-export const BUDGET_CHOICE_ADD_25 = "+$25";
-export const BUDGET_CHOICE_ADD_100 = "+$100";
+/** Preset approvals per dimension, plus the open-ended `other` answer. Kept small: the point is a
+ *  fast decision. These strings ARE the wire options — backend/web render them verbatim. */
+export const BUDGET_PRESETS = {
+    usd: ["+$10", "+$25", "+$100"],
+    tokens: ["+100k", "+1M", "+10M"],
+    compute: ["+15min", "+1h", "+4h"],
+};
 export const BUDGET_CHOICE_CANCEL = "cancel";
 /** Raised when a responder answers `cancel`: the run stops, deliberately, at the user's word. */
 export class BudgetGateCancelled extends Error {
@@ -17,51 +77,95 @@ export class BudgetGateCancelled extends Error {
 function usd(n) {
     return `$${n.toFixed(2)}`;
 }
+/** Token counts in a prompt: grouped digits ("1,200,000") — exact beats approximate at a gate. */
+function tokens(n) {
+    return Math.round(n).toLocaleString("en-US");
+}
+/** Compute time in a prompt: "1h 15m", "45m", "30s" — seconds only below a minute. */
+function computeTime(totalSeconds) {
+    const s = Math.max(0, Math.round(totalSeconds));
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    const sec = s % 60;
+    const parts = [];
+    if (h > 0)
+        parts.push(`${String(h)}h`);
+    if (m > 0)
+        parts.push(`${String(m)}m`);
+    if (parts.length === 0 || (h === 0 && sec > 0))
+        parts.push(`${String(sec)}s`);
+    return parts.join(" ");
+}
 /**
  * The gate's question. It states the two numbers that matter (spent vs. cap) so the responder can
- * decide without opening the dashboard, and names the run's own `max_usd` so it's obvious WHICH cap
- * was hit (not the org's credit balance — a different failure with a different fix).
+ * decide without opening the dashboard, and names the run's own manifest cap field so it's obvious
+ * WHICH cap was hit (not the org's credit balance — a different failure with a different fix).
  */
-export function budgetGatePrompt(spentUsd, capUsd) {
-    return (`Budget cap reached: this run has spent ${usd(spentUsd)} of its ${usd(capUsd)} ` +
-        `max_usd cap. Approve more spend to continue, or cancel the run.`);
+export function budgetGatePrompt(dimension, spent, cap) {
+    if (dimension === "usd") {
+        return (`Budget cap reached: this run has spent ${usd(spent)} of its ${usd(cap)} ` +
+            `max_usd cap. Approve more spend to continue, or cancel the run.`);
+    }
+    if (dimension === "tokens") {
+        return (`Budget cap reached: this run has used ${tokens(spent)} tokens of its ${tokens(cap)}-token ` +
+            `max_tokens cap. Approve more tokens to continue, or cancel the run.`);
+    }
+    return (`Budget cap reached: this run has used ${computeTime(spent)} of its ${computeTime(cap)} ` +
+        `max_compute_seconds cap. Approve more compute time to continue, or cancel the run.`);
 }
 /** The gate's response form — a choice, so the common answers are one click / one word. */
-export function budgetGateInputSpec() {
+export function budgetGateInputSpec(dimension) {
     return {
         kind: "choice",
-        options: [
-            BUDGET_CHOICE_ADD_10,
-            BUDGET_CHOICE_ADD_25,
-            BUDGET_CHOICE_ADD_100,
-            BUDGET_CHOICE_CANCEL,
-        ],
+        options: [...BUDGET_PRESETS[dimension], BUDGET_CHOICE_CANCEL],
         // `other` lets a responder type an absolute cap ("50") instead of taking a preset increment.
         other: true,
     };
 }
+/** Parse one numeric budget answer (`"25"`, `"2.5M"`, `"90min"`) into the dimension's native unit
+ *  (dollars / tokens / seconds), or null when unreadable. The `+` increment prefix is handled by
+ *  the caller — this reads only the magnitude. */
+function parseAmount(dimension, raw) {
+    if (dimension === "usd") {
+        const m = /^\$?\s*(\d+(?:\.\d+)?)$/.exec(raw);
+        return m?.[1] === undefined ? null : Number(m[1]);
+    }
+    if (dimension === "tokens") {
+        const m = /^(\d+(?:\.\d+)?)\s*([km])?$/i.exec(raw);
+        if (m?.[1] === undefined)
+            return null;
+        const mult = m[2]?.toLowerCase() === "k" ? 1_000 : m[2]?.toLowerCase() === "m" ? 1_000_000 : 1;
+        return Math.round(Number(m[1]) * mult);
+    }
+    const m = /^(\d+(?:\.\d+)?)\s*(s|sec|secs|m|min|mins|h|hr|hrs)?$/i.exec(raw);
+    if (m?.[1] === undefined)
+        return null;
+    const unit = m[2]?.toLowerCase() ?? "s";
+    const mult = unit.startsWith("h") ? 3600 : unit.startsWith("m") ? 60 : 1;
+    return Math.round(Number(m[1]) * mult);
+}
 /**
- * Interpret an answer as the NEW absolute `max_usd`, or null to cancel the run.
+ * Interpret an answer as the NEW absolute cap for `dimension`, or null to cancel the run.
  *
- * `+$N` is an INCREMENT on the current cap (the presets); a bare number is an ABSOLUTE new cap (the
- * "set a cap" escape hatch, via the choice's `other` entry). Anything unrecognized is treated as
- * cancel rather than guessed at — silently resuming a run on a misread answer spends real money.
+ * `+<amount>` is an INCREMENT on the current cap (the presets); a bare amount is an ABSOLUTE new
+ * cap (the "set a cap" escape hatch, via the choice's `other` entry). Anything unrecognized is
+ * treated as cancel rather than guessed at — silently resuming a run on a misread answer spends
+ * real money. See the module header for the full per-dimension grammar.
  */
-export function resolveBudgetAnswer(answer, currentCapUsd) {
+export function resolveBudgetAnswer(dimension, answer, currentCap) {
     const raw = answer.trim();
     if (raw === "" || raw.toLowerCase() === BUDGET_CHOICE_CANCEL)
         return null;
-    const increment = /^\+\s*\$?\s*(\d+(?:\.\d+)?)$/.exec(raw);
-    if (increment?.[1] !== undefined)
-        return currentCapUsd + Number(increment[1]);
-    const absolute = /^\$?\s*(\d+(?:\.\d+)?)$/.exec(raw);
-    if (absolute?.[1] !== undefined) {
-        const value = Number(absolute[1]);
-        // An "absolute" cap at or below what's already spent would re-park instantly — read it as a
-        // refusal to fund more, which is a cancel.
-        return value > currentCapUsd ? value : null;
+    if (raw.startsWith("+")) {
+        const amount = parseAmount(dimension, raw.slice(1).trim());
+        return amount === null ? null : currentCap + amount;
     }
-    return null;
+    const absolute = parseAmount(dimension, raw);
+    if (absolute === null)
+        return null;
+    // An "absolute" cap at or below the current one would re-park instantly — read it as a refusal
+    // to fund more, which is a cancel.
+    return absolute > currentCap ? absolute : null;
 }
 /** Pull the answer's text out of the SDK's result union (text | choice | multiselect). */
 function answerText(result) {
@@ -75,40 +179,117 @@ function answerText(result) {
     return "";
 }
 /**
- * Budget clearance, awaited before every model call. Fast path: no breach ⇒ resolve immediately (the
- * overwhelming majority of calls). On a `usd` breach: park at a gate, then apply the answer to the
- * live meter and let the call proceed.
+ * Budget clearance, awaited at every park point (see the module header). Fast path: no breach ⇒
+ * resolve immediately (the overwhelming majority of calls). On a breach of ANY dimension: park at
+ * a gate, then apply the answer to the live meter and let the call proceed.
  *
- * Scope (slice 1): ONLY the `usd` cap parks. A `tokens` / `duration` / `deadline` breach still fails
- * the run through the leaf executor's existing throw — those dimensions have no "approve more" story
- * yet, and `deadline` is wall-clock, which a park cannot pause by definition.
+ * The park's own wall-clock is EXCLUDED from the compute cap (`meter.excludeIdle`): parked time is
+ * not compute (SUSPEND_POLICY Decision 3.4), and on the snapshot fleet the guest clock resyncs
+ * across the frozen window — without the exclusion a compute park would re-breach the instant it
+ * woke, forever. `usage.get()` polled DURING a park may transiently show the parked wall-clock as
+ * compute spend; the exclusion lands when the park resolves.
  */
 export class BudgetGate {
     meter;
     host;
-    constructor(meter, host) {
+    now;
+    constructor(meter, host, now = Date.now) {
         this.meter = meter;
         this.host = host;
+        this.now = now;
     }
     async clear() {
         // Loop, don't `if`: a responder can approve an increment too small to clear the breach (spend
-        // already exceeds it), in which case we ask again rather than resume into an instant re-park.
-        while (this.meter.capBreachReason() === "usd") {
-            const cap = this.meter.usdCap();
+        // already exceeds it) — ask again rather than resume into an instant re-park — and clearing
+        // one dimension can reveal a second breached one, which parks next.
+        for (;;) {
+            const dimension = this.meter.capBreachReason();
+            if (dimension === null)
+                return;
+            const cap = this.meter.cap(dimension);
             if (cap === null)
                 return; // no cap ⇒ nothing to breach (defensive; capBreachReason implies one)
-            const spent = this.meter.snapshot().totalUsd;
+            const spent = this.meter.spent(dimension);
             // The park needs no bespoke event: registering the gate moves the run to `awaiting_input` and
             // the prompt below rides the gate row, so the live tail + `boardwalk inputs` explain the pause
             // through exactly the same path a humanInput() gate uses.
+            const parkedAt = this.now();
             const answer = await this.host.budgetClearance({
-                prompt: budgetGatePrompt(spent, cap),
-                inputSpec: budgetGateInputSpec(),
+                prompt: budgetGatePrompt(dimension, spent, cap),
+                inputSpec: budgetGateInputSpec(dimension),
             });
-            const newCap = resolveBudgetAnswer(answerText(answer), cap);
+            // Parked time is not compute — exclude it BEFORE re-checking the breach, or a compute park
+            // could never clear (the frozen/held wait would count as fresh compute spend).
+            this.meter.excludeIdle(this.now() - parkedAt);
+            const newCap = resolveBudgetAnswer(dimension, answerText(answer), cap);
             if (newCap === null)
                 throw new BudgetGateCancelled();
-            this.meter.raiseUsdCap(newCap);
+            this.meter.raiseCap(dimension, newCap);
+        }
+    }
+}
+/** How often the watcher samples the meter. Coarse is fine: compute presets are minutes. */
+export const DEFAULT_COMPUTE_WATCH_INTERVAL_MS = 15_000;
+/**
+ * Detects a `max_compute_seconds` breach BETWEEN park points. `usd`/`tokens` only move at the
+ * `streamModel` seam, but compute burns continuously — a breach can land mid-shell, mid-turn, or
+ * mid-program-compute, far from any model call.
+ *
+ * WHY THIS ONLY DETECTS AND DOES NOT PARK — true park-anywhere needs fleet-host work. The freeze
+ * machinery is quiescence-gated: `budgetClearance` may only be entered from a work-tracked seam
+ * (its `freezeWait` steps the CALLER out of the work count; from a timer context that corrupts the
+ * count and could freeze around live in-flight work, which SUSPEND_POLICY Decision 1 forbids). A
+ * timer-initiated park would need (a) a host-agent-initiated out-of-band VM pause that does not
+ * require runner quiescence, plus a wake path that re-arms the runner-side gate and applies the
+ * answer to the meter, and (b) on hold-only substrates a program-process stop (SIGSTOP) in the
+ * program runner. Until that lands, the honest contract is: the watcher logs the breach the moment
+ * it happens, and the run PARKS AT ITS NEXT SEAM (`streamModel`, `sleep`, `shell`,
+ * `workflows.call`) via the same {@link BudgetGate.clear} every park point awaits.
+ */
+export class ComputeBreachWatcher {
+    meter;
+    opts;
+    timer = null;
+    announced = false;
+    constructor(meter, opts = { runId: "" }) {
+        this.meter = meter;
+        this.opts = opts;
+    }
+    /** True while a compute breach is standing (sampled; resets when an approval clears it). */
+    get breachDetected() {
+        return this.announced;
+    }
+    start() {
+        if (this.timer !== null)
+            return;
+        this.timer = setInterval(() => {
+            this.sample();
+        }, this.opts.intervalMs ?? DEFAULT_COMPUTE_WATCH_INTERVAL_MS);
+        // Never keep the worker process alive solely for this watcher.
+        this.timer.unref();
+    }
+    stop() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** One sample tick (exposed for tests — real ticks come from the interval). */
+    sample() {
+        const cap = this.meter.cap("compute");
+        const breached = cap !== null && this.meter.spent("compute") > cap;
+        if (breached && !this.announced) {
+            this.announced = true;
+            log.warn("budget_compute_breach_between_seams", {
+                runId: this.opts.runId,
+                spentSeconds: this.meter.spent("compute"),
+                capSeconds: cap,
+                note: "run parks at its next capability seam (streamModel / sleep / shell / workflows.call)",
+            });
+        }
+        else if (!breached && this.announced) {
+            // The cap was raised at a gate — re-arm so a later breach of the NEW cap logs again.
+            this.announced = false;
         }
     }
 }

package/dist/runtime/host_capabilities.d.ts

@@ -0,0 +1,4 @@
+import type { HostCapabilities } from "./host_server.js";
+import type { WorkerWorkflowHost } from "./workflow_host.js";
+/** Build the protocol server's capability seam over the run's {@link WorkerWorkflowHost}. */
+export declare function buildHostCapabilities(host: WorkerWorkflowHost): HostCapabilities;

package/dist/runtime/host_capabilities.js

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: Apache-2.0
+/** Build the protocol server's capability seam over the run's {@link WorkerWorkflowHost}. */
+export function buildHostCapabilities(host) {
+    return {
+        agent: (prompt, opts) => host.agent(prompt, opts),
+        callWorkflow: async (slug, input, opts) => {
+            const { output, outputSchema } = await host.callWorkflow(slug, input, opts);
+            return { output, outputSchema };
+        },
+        runWorkflow: (slug, input, opts) => host.runWorkflow(slug, input, opts),
+        scheduleWorkflow: (slug, input, opts) => host.scheduleWorkflow(slug, input, opts),
+        sleep: (arg) => host.sleep(arg),
+        humanInput: (opts) => host.humanInput(opts),
+        getSecret: (name) => host.getSecret(name),
+        writeArtifact: (name, contentType, body, metadata) => host.writeArtifact(name, contentType, body, metadata),
+        openBrowser: (opts) => host.openBrowserSession(opts),
+        shell: (cmd, opts) => host.shell(cmd, opts),
+        phase: (name, opts) => {
+            host.setPhase(name, opts);
+        },
+        idToken: (audience) => host.idToken(audience),
+        apiToken: () => host.apiToken(),
+        usage: () => host.usage(),
+    };
+}

package/dist/runtime/host_server.d.ts

@@ -0,0 +1,137 @@
+import { type ContextData, type JsonValue, type ShellResult, type UsageSnapshot, type AgentOptions, type ArtifactBody, type ArtifactRef, type BrowserSession, type BrowserSessionOptions, type CallOptions, type HumanInputOptions, type HumanInputResult, type PhaseOptions, type ScheduleOptions, type SleepArg } from "@boardwalk-labs/workflow/runtime";
+import type { ShellOptions } from "@boardwalk-labs/workflow";
+/** The loader-side curation hint for a `report_return` output-schema mismatch. Shared by the
+ *  in-process TS loader and the Python subprocess path so the author sees ONE message. */
+export declare const OUTPUT_MISMATCH_HINT = "Return a value matching run()'s declared return type, or update the type and redeploy.";
+/** What `workflows.call` resolves at the capability seam: the child's output plus the CALLEE's
+ *  declared output schema (`null` for an untyped callee — the client passes the JSON through). */
+export interface CapabilityCallResult {
+    output: unknown;
+    outputSchema: Record<string, unknown> | null;
+}
+/**
+ * The typed seam the protocol server dispatches onto — the runner's existing machinery, one
+ * member per capability. Mirrors the SDK client's `HostInterface` so the two ends of the wire
+ * stay symmetric. `agent` receives NATIVE `AgentOptions`: the server has already turned wire
+ * tool declarations into executable `ToolDef`s (round-tripping `tool_invoke`) and resolved a
+ * wire `sessionId` to its live {@link BrowserSession}.
+ */
+export interface HostCapabilities {
+    agent(prompt: string, opts: AgentOptions | undefined): Promise<unknown>;
+    callWorkflow(slug: string, input: unknown, opts: CallOptions | undefined): Promise<CapabilityCallResult>;
+    runWorkflow(slug: string, input: unknown, opts: CallOptions | undefined): Promise<string>;
+    scheduleWorkflow(slug: string, input: unknown, opts: ScheduleOptions): Promise<string>;
+    sleep(arg: SleepArg): Promise<void>;
+    humanInput(opts: HumanInputOptions): Promise<HumanInputResult>;
+    getSecret(name: string): Promise<string>;
+    writeArtifact(name: string, contentType: string, body: ArtifactBody, metadata: Record<string, unknown> | undefined): Promise<ArtifactRef>;
+    openBrowser(opts: BrowserSessionOptions | undefined): Promise<BrowserSession>;
+    shell(cmd: string, opts: ShellOptions | undefined): Promise<ShellResult>;
+    phase(name: string, opts: PhaseOptions | undefined): void;
+    idToken(audience: string): Promise<string>;
+    apiToken(): Promise<string>;
+    usage(): Promise<UsageSnapshot>;
+}
+/** The `bootstrap` payload: the RAW JSON input + the stored input schema (`null` when untyped —
+ *  the CLIENT applies the schema-guided revival pass) + the context DATA (never `signal`). */
+export interface BootstrapData {
+    input: JsonValue;
+    inputSchema: Record<string, unknown> | null;
+    context: ContextData;
+}
+export interface WorkflowHostServerDeps {
+    capabilities: HostCapabilities;
+    bootstrap: BootstrapData;
+    /** The workflow's declared output schema; `null` ⇒ the return persists unvalidated. */
+    outputSchema: Record<string, unknown> | null;
+    /** The run's cooperative-cancellation signal: on abort, every connected client is sent the
+     *  `cancel` notification (the SDK aborts `context.signal`). */
+    signal?: AbortSignal | undefined;
+    /** Directory the Unix socket file is created in. Default `os.tmpdir()` — deliberately short:
+     *  `sun_path` caps a socket path at ~104 bytes on darwin. Ignored on win32 (named pipe). */
+    sockDir?: string | undefined;
+    /** Host-side ceiling on ONE `tool_invoke` round-trip. Default: none — parity with the engine,
+     *  which awaits an inline tool's `execute()` without a timeout. When set, expiry throws an
+     *  ordinary Error from `execute()` (a tool-error result to the model, never run-fatal) and the
+     *  late response is discarded by id. */
+    toolInvokeTimeoutMs?: number | undefined;
+}
+/**
+ * The protocol server for ONE run. `listen()` binds the socket (the runner then exports the
+ * path as `BOARDWALK_HOST_SOCK`); `close()` tears everything down. The validated return the
+ * program reported is read via {@link reportedReturn} after the loader completes.
+ */
+export declare class WorkflowHostServer {
+    private readonly deps;
+    private readonly server;
+    private readonly connections;
+    /** sessionId → live handle, backing `computer.browser.*` and `agent({ session })`. */
+    private readonly browserSessions;
+    private readonly validateOutput;
+    private nextInvokeId;
+    private sockPath;
+    private returned;
+    private reportFailure;
+    private cancelled;
+    private readonly onAbort;
+    constructor(deps: WorkflowHostServerDeps);
+    /** Bind the socket and resolve its path (a Unix socket path; a named pipe on win32). */
+    listen(): Promise<string>;
+    /** The bound socket path; null before `listen()`. */
+    get socketPath(): string | null;
+    /** The validated value the program's loader reported via `report_return`, or null when no
+     *  return was reported (the program never finished, or returned void ⇒ the client sent null). */
+    reportedReturn(): JsonValue | null;
+    /** Whether `report_return` was received at all (distinguishes "returned null" from "never
+     *  reported" for callers that care). */
+    hasReturn(): boolean;
+    /** The error the most recent `report_return` attempt failed with (the output-schema mismatch),
+     *  or null when none failed / a later report succeeded. An IN-PROCESS loader re-throws this
+     *  error itself; a SUBPROCESS loader (Python) can only propagate it as a traceback + non-zero
+     *  exit, so the runner reads it back here to curate the run's failure with the original
+     *  code/message instead of the traceback's last line. */
+    reportReturnFailure(): Error | null;
+    /** Push the `cancel` notification to every connected client (idempotent). */
+    notifyCancel(reason?: string): void;
+    /** Tear the server down: reject in-flight tool invokes, destroy connections, unlink the socket. */
+    close(): Promise<void>;
+    private onFrame;
+    private settleInvoke;
+    private handleNotification;
+    private handleRequest;
+    private dispatch;
+    private get caps();
+    /**
+     * One handler per client→host method, each typed by ITS OWN `HostMethodParams`/`HostMethodResult`
+     * pair via the mapped type — params arrive already narrowed (no per-case casts) and a handler
+     * returning another method's result shape is a COMPILE error (a switch over the union couldn't
+     * catch that). Exhaustive by construction: a new wire method fails the build until a handler
+     * exists. `req` carries the originating connection + request id for `agent`, whose inline tools
+     * round-trip `tool_invoke` on that same connection, correlated by this request's id.
+     */
+    private readonly handlers;
+    /** A live browser session by id, or a clear VALIDATION error for a closed/foreign one. */
+    private session;
+    /** Validate the program's return against the declared output schema (P3.4): a mismatch fails
+     *  the run — the loader's `reportReturn` rejects and the failure is curated. `null` (a void
+     *  return) skips validation per the contract. */
+    private assertReturnMatchesSchema;
+    /** Wire tool declarations → engine `ToolDef`s whose `execute()` round-trips `tool_invoke` to
+     *  the program, correlated by `call_id` = the originating agent request's own id (stringified).
+     *  Also resolves a wire `sessionId` back to its live browser session. */
+    private toAgentOptions;
+    /** One host → client `tool_invoke` round-trip. Concurrent invocations multiplex by this
+     *  request's own JSON-RPC id; the optional host-side timeout abandons the call (its late
+     *  response is discarded by id) and throws an ordinary Error — a tool-error result to the
+     *  model, never run-fatal. */
+    private invokeTool;
+}
+/** Map a thrown value to the wire's `{code, message, data?}` (string code, engine taxonomy).
+ *  An engine-style `hint` (the one-line "what to do") rides `data.hint` so it SURVIVES the wire —
+ *  the loader's failure curation reads it back into the run's `output.error.hint` (the
+ *  hint-reaches-hosted-authors contract). */
+export declare function protocolErrorOf(err: unknown): {
+    code: string;
+    message: string;
+    data?: unknown;
+};