@parcha/agentrun-kernel 0.0.0-bootstrap.0 → 0.1.0-beta.29

package/dist/host/overhead.d.ts

@@ -0,0 +1,53 @@
+/** What of a request decides what its provider adds: whether it offers tools, how it asks for them, and its images. */
+export interface InputShape {
+    /** The request offers at least one tool. */
+    tools: boolean;
+    /** Its tool_choice, as Anthropic names them; absent for the provider's default. */
+    toolChoice?: "auto" | "none" | "any" | "tool";
+    /** Its image inputs, at any depth (a tool's result included). */
+    images: number;
+}
+/**
+ * The tool-use system prompt the Messages API adds to a request with tools, in tokens, by tool_choice. Documented per
+ * model under "Pricing" in https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview, and taken at the largest
+ * figure listed for any current model (Claude Opus 4.7's): 675 for auto or none, 804 for any or tool. None without tools.
+ */
+export declare const ANTHROPIC_TOOL_USE_SYSTEM_PROMPT_TOKENS: Readonly<{
+    autoOrNone: 675;
+    anyOrTool: 804;
+}>;
+/**
+ * The most tokens one image is billed as on the Messages API, whatever its bytes: Claude bills 28x28-pixel patches of the
+ * image as it resized it. The largest "Max visual tokens" documented for any model in "Resolution and token cost",
+ * https://platform.claude.com/docs/en/build-with-claude/vision: 4,784 on the high-resolution tier (Claude 4.7 and later),
+ * against 1,568 on the standard tier.
+ */
+export declare const ANTHROPIC_IMAGE_TOKENS_MAX = 4784;
+/**
+ * The most input tokens one image can be billed as on the Responses API, whatever its bytes. An image is covered by 32 px
+ * patches, one over 30,000 patches is rejected, and its patches are multiplied by the model's multiplier, at most 2.46
+ * among the models listed ("Calculating costs", https://developers.openai.com/api/docs/guides/images-vision). The guide
+ * states no per-image maximum, so this is that ceiling: 30,000 x 2.46. The tile-based models cost less per image. The
+ * Responses API documents no prompt of its own that it adds for tools.
+ */
+export declare const OPENAI_IMAGE_TOKENS_MAX = 73800;
+/**
+ * The tool prompt assumed for an API whose provider documents none: 2,048 tokens a request with tools. It is an
+ * assumption, not a documented figure, and it is above the largest documented one (Anthropic's 804), so a provider that
+ * adds a prompt of its own for tools, as Anthropic and OpenAI do, is not undercounted where its figure is unknown.
+ */
+export declare const ASSUMED_TOOL_PROMPT_TOKENS = 2048;
+/**
+ * The API kinds whose figures are documented, as pi names them. Azure's and Codex's Responses are billed as OpenAI's.
+ * Every other kind (pi's "mistral-conversations", "bedrock-converse-stream", "google-generative-ai", "google-vertex",
+ * "pi-messages", a faux "faux:<id>", or any other) gets the general figure: nothing for its text, which the byte bound
+ * covers, `ASSUMED_TOOL_PROMPT_TOKENS` when it has tools, and OpenAI's per-image maximum, the largest documented, for each
+ * image.
+ */
+export declare const INPUT_OVERHEAD_APIS: readonly string[];
+/**
+ * The input tokens a provider bills for a request of `shape` beyond its body's bytes, on the API `api` (pi's names:
+ * "anthropic-messages", "openai-responses", ...). A documented API gets its documented figures; any other gets the
+ * general figure (`INPUT_OVERHEAD_APIS`). Never undefined: an input that cannot be measured is the body's, not the API's.
+ */
+export declare function providerInputOverhead(api: string, shape: InputShape): number;

package/dist/host/overhead.js

@@ -0,0 +1,75 @@
+// The input a provider bills for a request beyond the bytes of its body, by the provider's API: one place for the figures
+// and their sources, used by the model proxy's policies and by a host that bounds a request it sends itself. Written for
+// AgentRun.
+//
+// A request's input can never be more tokens than its body's UTF-8 bytes (`inputTokensMaxOf`), except for what the
+// provider adds or bills by another measure: a prompt it adds itself when tools are present, and images, which it bills by
+// their area after it resizes them, not by their bytes. Each figure is the largest the provider documents for any current
+// model, so no model is undercounted.
+/**
+ * The tool-use system prompt the Messages API adds to a request with tools, in tokens, by tool_choice. Documented per
+ * model under "Pricing" in https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview, and taken at the largest
+ * figure listed for any current model (Claude Opus 4.7's): 675 for auto or none, 804 for any or tool. None without tools.
+ */
+export const ANTHROPIC_TOOL_USE_SYSTEM_PROMPT_TOKENS = Object.freeze({ autoOrNone: 675, anyOrTool: 804 });
+/**
+ * The most tokens one image is billed as on the Messages API, whatever its bytes: Claude bills 28x28-pixel patches of the
+ * image as it resized it. The largest "Max visual tokens" documented for any model in "Resolution and token cost",
+ * https://platform.claude.com/docs/en/build-with-claude/vision: 4,784 on the high-resolution tier (Claude 4.7 and later),
+ * against 1,568 on the standard tier.
+ */
+export const ANTHROPIC_IMAGE_TOKENS_MAX = 4_784;
+/**
+ * The most input tokens one image can be billed as on the Responses API, whatever its bytes. An image is covered by 32 px
+ * patches, one over 30,000 patches is rejected, and its patches are multiplied by the model's multiplier, at most 2.46
+ * among the models listed ("Calculating costs", https://developers.openai.com/api/docs/guides/images-vision). The guide
+ * states no per-image maximum, so this is that ceiling: 30,000 x 2.46. The tile-based models cost less per image. The
+ * Responses API documents no prompt of its own that it adds for tools.
+ */
+export const OPENAI_IMAGE_TOKENS_MAX = 73_800;
+/**
+ * Chat Completions ("openai-completions") is spoken by OpenAI and by OpenAI-compatible gateways, which route to other
+ * providers' models (Anthropic's among them). Its figure is the largest of any provider it may reach:
+ *  - messages: nothing. It adds formatting tokens around each message, 3 a message, 1 for a name and 3 that prime the
+ *    reply (num_tokens_from_messages in https://developers.openai.com/cookbook/examples/how_to_count_tokens_with_tiktoken),
+ *    and each message's own JSON in the body ({"role":...,"content":...}, some 30 bytes of keys) is more bytes than that,
+ *    so the byte bound covers them;
+ *  - tools: never nothing. A gateway that routes to an Anthropic model is billed Anthropic's tool-use system prompt
+ *    whatever API it speaks, and OpenAI renders tools into a prompt of its own with a fixed header; the largest documented
+ *    of these is Anthropic's, 804 tokens (`ANTHROPIC_TOOL_USE_SYSTEM_PROMPT_TOKENS.anyOrTool`), taken whatever the
+ *    tool_choice, since a gateway may not pass it through as Anthropic reads it;
+ *  - images: OpenAI's per-image maximum, which is above Anthropic's, so a gateway routing to either is covered.
+ */
+const CHAT_COMPLETIONS = "openai-completions";
+/**
+ * The tool prompt assumed for an API whose provider documents none: 2,048 tokens a request with tools. It is an
+ * assumption, not a documented figure, and it is above the largest documented one (Anthropic's 804), so a provider that
+ * adds a prompt of its own for tools, as Anthropic and OpenAI do, is not undercounted where its figure is unknown.
+ */
+export const ASSUMED_TOOL_PROMPT_TOKENS = 2_048;
+/**
+ * The API kinds whose figures are documented, as pi names them. Azure's and Codex's Responses are billed as OpenAI's.
+ * Every other kind (pi's "mistral-conversations", "bedrock-converse-stream", "google-generative-ai", "google-vertex",
+ * "pi-messages", a faux "faux:<id>", or any other) gets the general figure: nothing for its text, which the byte bound
+ * covers, `ASSUMED_TOOL_PROMPT_TOKENS` when it has tools, and OpenAI's per-image maximum, the largest documented, for each
+ * image.
+ */
+export const INPUT_OVERHEAD_APIS = Object.freeze(["anthropic-messages", "openai-responses", "azure-openai-responses", "openai-codex-responses", CHAT_COMPLETIONS]);
+/** The tool-use prompt Anthropic adds for a request of `shape`: none without tools. */
+const anthropicToolPrompt = (shape) => (!shape.tools ? 0 : shape.toolChoice === "any" || shape.toolChoice === "tool" ? ANTHROPIC_TOOL_USE_SYSTEM_PROMPT_TOKENS.anyOrTool : ANTHROPIC_TOOL_USE_SYSTEM_PROMPT_TOKENS.autoOrNone);
+/**
+ * The input tokens a provider bills for a request of `shape` beyond its body's bytes, on the API `api` (pi's names:
+ * "anthropic-messages", "openai-responses", ...). A documented API gets its documented figures; any other gets the
+ * general figure (`INPUT_OVERHEAD_APIS`). Never undefined: an input that cannot be measured is the body's, not the API's.
+ */
+export function providerInputOverhead(api, shape) {
+    if (!Number.isSafeInteger(shape.images) || shape.images < 0)
+        throw new Error(`not an image count: ${String(shape.images).slice(0, 40)}`);
+    if (api === "anthropic-messages")
+        return anthropicToolPrompt(shape) + shape.images * ANTHROPIC_IMAGE_TOKENS_MAX;
+    if (api === CHAT_COMPLETIONS)
+        return (shape.tools ? ANTHROPIC_TOOL_USE_SYSTEM_PROMPT_TOKENS.anyOrTool : 0) + shape.images * OPENAI_IMAGE_TOKENS_MAX;
+    if (INPUT_OVERHEAD_APIS.includes(api))
+        return shape.images * OPENAI_IMAGE_TOKENS_MAX;
+    return (shape.tools ? ASSUMED_TOOL_PROMPT_TOKENS : 0) + shape.images * OPENAI_IMAGE_TOKENS_MAX;
+}

package/dist/host/parent-death.d.ts

@@ -0,0 +1,15 @@
+/** A command and its arguments. */
+export interface LaunchCommand {
+    command: string;
+    args: string[];
+}
+/** How a child is tied to its parent: the kernel's parent-death signal, or the shim that watches. */
+export type ParentWatch = "pdeathsig" | "shim";
+/** The util-linux setpriv that sets the parent-death signal. */
+export declare const SETPRIV = "/usr/bin/setpriv";
+/** The shim, run with this process's node where setpriv cannot be. */
+export declare const PARENT_WATCH_SHIM: string;
+/** The watch this machine supports: pdeathsig on Linux with a setpriv that has `--pdeathsig`, else the shim. Read once. */
+export declare function parentWatchHere(): ParentWatch;
+/** `child`, started so that it dies with this process (`how`, default what this machine supports). */
+export declare function parentWatched(child: Readonly<LaunchCommand>, how?: ParentWatch): LaunchCommand;

package/dist/host/parent-death.js

@@ -0,0 +1,42 @@
+// A harness's own process (its CLI, its app-server) dies with the process that started it. Written for AgentRun.
+//
+// A session machine starts that process detached, in its own process group, so its group kill (abort, close) ends it
+// and everything it started. A SIGKILLed host runs no close, and a detached child outlives it: reparented, it sleeps on
+// (the pinned Claude Agent CLI does not exit when its stdin closes), one more per crash. So the child is started with a
+// watch on its parent:
+//  - Linux with util-linux setpriv: `setpriv --pdeathsig KILL --` in front of it. setpriv sets the parent-death signal
+//    and execs the child in place (the same pid, still the host's direct child), so the kernel sends it SIGKILL the
+//    moment the host's spawning thread exits: libuv spawns from the event loop's thread, the main one, so a worker
+//    thread's exit does not trigger it. The signal survives the exec, as the child is not set-user-ID.
+//  - elsewhere (macOS, or no setpriv): `node parent-watch.js <host pid> -- <child>`, a shim that runs the child and
+//    kills it when the shim is reparented, checked four times a second.
+// The watch goes INSIDE the host's confinement (the machine applies its confine prefix to the watched command): the
+// kernel clears a parent-death signal when credentials change, so it is set after any switch of user the prefix makes.
+// The child's environment is the machine's: the watch adds nothing to it.
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/** The util-linux setpriv that sets the parent-death signal. */
+export const SETPRIV = "/usr/bin/setpriv";
+/** The shim, run with this process's node where setpriv cannot be. */
+export const PARENT_WATCH_SHIM = fileURLToPath(new URL("./parent-watch.js", import.meta.url));
+let here;
+/** The watch this machine supports: pdeathsig on Linux with a setpriv that has `--pdeathsig`, else the shim. Read once. */
+export function parentWatchHere() {
+    if (here)
+        return here;
+    let pdeathsig = false;
+    if (process.platform === "linux" && existsSync(SETPRIV)) {
+        try {
+            pdeathsig = execFileSync(SETPRIV, ["--help"], { encoding: "utf8", env: { PATH: "/usr/bin:/bin" }, timeout: 5_000 }).includes("--pdeathsig");
+        }
+        catch { }
+    }
+    return (here = pdeathsig ? "pdeathsig" : "shim");
+}
+/** `child`, started so that it dies with this process (`how`, default what this machine supports). */
+export function parentWatched(child, how = parentWatchHere()) {
+    if (how === "pdeathsig")
+        return { command: SETPRIV, args: ["--pdeathsig", "KILL", "--", child.command, ...child.args] };
+    return { command: process.execPath, args: [PARENT_WATCH_SHIM, String(process.pid), "--", child.command, ...child.args] };
+}

package/dist/host/parent-watch.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/host/parent-watch.js

@@ -0,0 +1,38 @@
+// The parent watch where the kernel's parent-death signal is not available (parent-death.ts). Written for AgentRun.
+//   node parent-watch.js <parent pid> -- <command> [args...]
+// Runs the command with this process's stdio and environment, in this process's group (so a group kill ends both),
+// passes TERM, INT and HUP on to it, exits as it exits, and kills it when this process is reparented: its parent, the
+// host, is gone.
+import { spawn } from "node:child_process";
+const [parentArg, separator, command, ...args] = process.argv.slice(2);
+const parent = Number(parentArg);
+if (!Number.isSafeInteger(parent) || parent < 1 || separator !== "--" || !command) {
+    process.stderr.write("usage: parent-watch.js <parent pid> -- <command> [args...]\n");
+    process.exit(2);
+}
+// Started after the host was already gone: nothing to run for.
+if (process.ppid !== parent)
+    process.exit(1);
+const child = spawn(command, args, { stdio: "inherit" });
+const passed = ["SIGTERM", "SIGINT", "SIGHUP"];
+for (const signal of passed)
+    process.on(signal, () => child.kill(signal));
+child.on("error", (error) => {
+    process.stderr.write(`parent-watch: ${error.message}\n`);
+    process.exit(127);
+});
+const watch = setInterval(() => {
+    if (process.ppid === parent)
+        return;
+    child.kill("SIGKILL");
+    process.exit(1);
+}, 250);
+child.on("exit", (code, signal) => {
+    clearInterval(watch);
+    if (code !== null)
+        process.exit(code);
+    // Ended by a signal: end the same way, so the host sees what the child saw.
+    for (const s of passed)
+        process.removeAllListeners(s);
+    process.kill(process.pid, signal ?? "SIGKILL");
+});

package/dist/host/pinned-binary.d.ts

@@ -0,0 +1,6 @@
+/** The sha256 of the file at `path`, as hex, read a chunk at a time. Throws as `openSync` and `readSync` do. */
+export declare function sha256OfFile(path: string): string;
+/** `check`'s result for the binary at `path` against `pins`, run once per identity in this process: a result `ok` calls
+ *  passed is kept, and answered again at once while the binary stays the same file, unchanged; any other is never kept.
+ *  A binary that changed while it was checked is not kept, and is checked again next time. */
+export declare function checkedOnce<T>(path: string, pins: string, check: () => T, ok: (result: T) => boolean): T;

package/dist/host/pinned-binary.js

@@ -0,0 +1,48 @@
+// A harness's binary, checked against its pins (codex's, claude-agent's): its sha256 read a chunk at a time, and each
+// check that passed kept for the process by what the binary is. A binary is hundreds of MiB; read whole, each check held
+// all of it in memory, and a host that checks it again for each model it resolves held it again each time. Here a process
+// holds one chunk at most, and checks a binary once per identity: its path, the file it names (device and inode), its
+// size and its modification and change times, with the pins it met. Replaced or touched, it is checked again; a check
+// that failed is never kept, so the next one runs again.
+import { createHash } from "node:crypto";
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+/** The bytes read at a time. */
+const CHUNK = 1 << 20;
+/** The sha256 of the file at `path`, as hex, read a chunk at a time. Throws as `openSync` and `readSync` do. */
+export function sha256OfFile(path) {
+    const hash = createHash("sha256");
+    const fd = openSync(path, "r");
+    try {
+        const chunk = Buffer.allocUnsafe(CHUNK);
+        for (let read; (read = readSync(fd, chunk, 0, CHUNK, null)) > 0;)
+            hash.update(chunk.subarray(0, read));
+    }
+    finally {
+        closeSync(fd);
+    }
+    return hash.digest("hex");
+}
+/** What the file at `path` is, for `pins` (any text that names them): undefined when it cannot be read. */
+function identityOf(path, pins) {
+    try {
+        const file = statSync(path, { bigint: true });
+        return [path, file.dev, file.ino, file.size, file.mtimeNs, file.ctimeNs, pins].join("\0");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** What each check that passed answered, by the binary's identity. */
+const passed = new Map();
+/** `check`'s result for the binary at `path` against `pins`, run once per identity in this process: a result `ok` calls
+ *  passed is kept, and answered again at once while the binary stays the same file, unchanged; any other is never kept.
+ *  A binary that changed while it was checked is not kept, and is checked again next time. */
+export function checkedOnce(path, pins, check, ok) {
+    const identity = identityOf(path, pins);
+    if (identity !== undefined && passed.has(identity))
+        return passed.get(identity);
+    const result = check();
+    if (identity !== undefined && ok(result) && identityOf(path, pins) === identity)
+        passed.set(identity, result);
+    return result;
+}

package/dist/host/proxy.d.ts

@@ -0,0 +1,179 @@
+import { type IncomingHttpHeaders } from "node:http";
+/** A route a policy admits: its method, its exact path, and the request headers forwarded with it. */
+export interface ProxyRoute {
+    readonly method: string;
+    readonly path: string;
+    /** Exact query strings it admits besides none (`beta=true`); forwarded as the table has them. */
+    readonly query?: readonly string[];
+    readonly headers?: readonly string[];
+    /** Answered here with this status and an empty body, never forwarded (a client's connectivity check). */
+    readonly local?: number;
+    /** Not a paid request (a token count): forwarded without asking the runner, and no usage is reported. */
+    readonly free?: boolean;
+}
+/** Token counts a response reports. */
+export interface ProxyUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite?: number;
+}
+/** What one provider's API may carry through the proxy. */
+export interface ProviderPolicy {
+    /** A name for messages. */
+    readonly id: string;
+    readonly routes: readonly ProxyRoute[];
+    /** The key the client sent, from its headers ("" when it sent none). */
+    keyOf(headers: IncomingHttpHeaders): string;
+    /** The headers that carry the provider's credential. */
+    authHeaders(credential: string): Record<string, string>;
+    /** A listed request header's value as forwarded, or undefined to drop it; a `ProxyRefusal` refuses the request before
+     *  the runner is asked (a beta the policy does not know). Default: as sent. */
+    header?(name: string, value: string): string | undefined;
+    /** The body the provider gets for a request on `route`: throw a `ProxyRefusal` to refuse it. */
+    apply(body: unknown, route: ProxyRoute): Record<string, unknown>;
+    /** The usage a completed response reports, if it reports one: from its whole text, or, for a long one, its first and
+     *  last 64 KiB (a provider may report input tokens as a stream starts and output tokens as it ends). */
+    usageOf(text: string): ProxyUsage | undefined;
+    /** Called once for each request the proxy forwards that the provider answers, as the answer starts. Requests overlap (a
+     *  client's background calls run beside its turn), so what it keeps is for the sink to tell apart: each call returns its own
+     *  observer. The observer is given each piece of the answer as text, BEFORE that piece is written to the client, so what it
+     *  saw of an answer, the client has not yet acted on: the one thing the proxy can say causally about what a client does
+     *  next. `end` is called when the answer is over, however it ended. It only reads; one that throws is reported, `failed` is
+     *  called (the answer was not watched to its end) and the answer goes on. A `watch` must not throw after it has told its
+     *  sink the answer started (its sink counts open answers, and only `end` closes one): do that last. */
+    watch?(): {
+        chunk(text: string): void;
+        failed?(): void;
+        end?(): void;
+    } | undefined;
+    /** Called when `watch` threw: this answer is not watched, so nothing the policy knew of an earlier one may stand for it. */
+    unwatched?(): void;
+    /** The model the body `apply` returned asks for, once `apply` checked it is one this session may use (its own, or a
+     *  smaller one for a client's background calls). The runner is asked about, and the price taken for, that model.
+     *  Absent, or undefined for a body: the session's model. */
+    modelOf?(body: Record<string, unknown>): string | undefined;
+    /** The input tokens the provider bills for the body `apply` returned that the body does not carry: a prompt it adds
+     *  itself, such as a tool-use system prompt. Added to the body's bytes for `inputTokensMax`. Undefined: the body has
+     *  no input bound the policy can state (a hosted tool that reads pages into the input), so `inputTokensMax` is
+     *  undefined, never 0 or the body's bytes alone. Absent: none. */
+    serverInputOverhead?(body: Record<string, unknown>): number | undefined;
+    /** The output tokens the body `apply` returned asks for at most (its own limit, as `apply` shaped it). Absent or
+     *  undefined: the body does not say. */
+    outputAsked?(body: Record<string, unknown>): number | undefined;
+    /** The least output the body may be limited to and still answer: 1,024 tokens for the answer, plus the least thinking
+     *  its provider takes when it thinks. Absent: 1,024. */
+    outputLeast?(body: Record<string, unknown>): number;
+    /** The body `apply` returned with its output limited to `max` tokens, thinking included (what is left of a spend cap
+     *  can buy): never more than it asked for, and never longer as sent, since its input bound was measured on it. A host
+     *  that limits a request's output needs it: without it such a request is refused, never sent unlimited. */
+    limitOutput?(body: Record<string, unknown>, max: number): Record<string, unknown>;
+    /** The status a request the runner refused gets: one the client does not retry. Default 400. */
+    readonly refusedStatus?: number;
+}
+export interface ModelUsageReport extends ProxyUsage {
+    /** The provider's (or its gateway's) own figure when the response gave one (`reportedCostOf`); else the price table's,
+     *  `estimated`; null when neither is known. */
+    usd: number | null;
+    estimated?: boolean;
+    /** Beside a reported figure, what the price table makes of the same usage: kept to audit the table. */
+    tableUsd?: number | null;
+    /** The ids the response's headers gave it (`providerIdsOf`), when they came. */
+    providerIds?: Record<string, string>;
+    /** A response its client left before its end (a stop), with the bytes of it the client was sent: what streamed. Not
+     *  set for one the provider ended early (an error part way), nor for one the client read whole. */
+    stoppedAfterBytes?: number;
+}
+/** A paid request as the host is asked about it, before it leaves. */
+export interface ProxyRequest {
+    model: string;
+    /** The most input tokens it can be billed for (see `inputTokensMaxOf`), undefined when that could not be measured. */
+    inputTokensMax?: number;
+    /** The most output tokens it asks for (the policy's `outputAsked`), when the body says. */
+    outputTokensAsked?: number;
+    /** The least output it may be limited to and still answer (the policy's `outputLeast`). */
+    outputTokensLeast?: number;
+}
+export interface ModelProxyHooks {
+    /** Before a paid request leaves; a throw refuses it. What it returns (a ticket) is handed back to this request's
+     *  `afterRequest`, since requests may be in flight together. A ticket's `outputTokensMax` limits the request's output
+     *  (thinking included) to that many tokens, written into its body by the policy's `limitOutput` before it is sent. */
+    beforeRequest(request: ProxyRequest): Promise<unknown>;
+    /** When a request's response has completed, with its usage and the ticket its `beforeRequest` returned. */
+    afterRequest(usage: ModelUsageReport, ticket?: unknown): Promise<void>;
+    /** When a paid request's response headers arrive, before its body: the ids they give it (`providerIdsOf`), so a
+     *  request a crash cuts off after this point is known to have reached the provider, under those ids. */
+    responded?(ids: Record<string, string>, ticket?: unknown): Promise<void>;
+}
+export interface ModelProxyOptions {
+    policy: ProviderPolicy;
+    hooks: ModelProxyHooks;
+    /** The session's model, as the runner names it to `beforeRequest`. The policy fixes the body's model. */
+    model: string;
+    /** The provider's base: its origin and, for a gateway that serves the API under a path, that path
+     *  (`https://api.example.com`, `https://gateway.example/api`). A route's path is appended to it. A base with userinfo, a
+     *  query or a fragment is refused, so the key goes only where the base reads. */
+    origin: string;
+    /** The provider's credential, read for each request. */
+    credential: () => string | Promise<string>;
+    /** The price of a response, or null when it is unknown. */
+    price?: (model: string, usage: ProxyUsage) => number | null;
+    log?: (message: string, detail?: Record<string, unknown>) => void;
+    /** Told each forwarded request's route and the provider's status once it answers: what a route does on this
+     *  provider (a free route it may not serve), as a status code only, never a body or a key. */
+    onResponse?: (response: {
+        method: string;
+        path: string;
+        free: boolean;
+        status: number;
+    }) => void;
+    /** Headers the host adds to every request it forwards (a gateway's spend tags, LiteLLM's `x-litellm-tags`, say):
+     *  after the client's, so the client can neither set nor override them, and before the credential's. Checked when the
+     *  proxy starts (`hostHeaderProblems`). */
+    headers?: Readonly<Record<string, string>>;
+    /** For tests: the fetch the proxy forwards with. */
+    fetch?: typeof fetch;
+}
+/** What is wrong with headers a host would add to forwarded requests: a name that is not a token or is reserved, a value
+ *  an HTTP header cannot carry (a line break or other control character, or a character beyond Latin-1, which the fetch
+ *  the proxy forwards with refuses) or over 1 KiB. Empty when they are fine. */
+export declare function hostHeaderProblems(headers: Readonly<Record<string, unknown>> | undefined): string[];
+export interface ModelProxy {
+    /** The proxy's origin, `http://127.0.0.1:<port>`. */
+    readonly url: string;
+    /** The key the harness sends, which the proxy admits. */
+    readonly key: string;
+    close(): Promise<void>;
+}
+/** The ids a response's headers give its request, by header name, so a run's books can be joined to the provider's (or
+ *  a gateway's) request by request; undefined when there are none. Only id-named headers with id-shaped values. */
+export declare function providerIdsOf(headers: Headers): Record<string, string> | undefined;
+/** What a response's headers say it cost, when they say so: LiteLLM's `x-litellm-response-cost`, or its `-original` when
+ *  the discount and margin it reports are both exactly 0. Only a positive number counts. A missing, malformed or zero
+ *  figure is unknown, never $0: a streamed answer's headers leave before it is priced, and LiteLLM writes 0.0 there. */
+export declare function reportedCostOf(headers: Headers): number | undefined;
+export declare class ProxyRefusal extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** Match a request's method and path text against the routes, never parsing the path as a URL: the route, and the
+ *  query it carried, which is one the route lists exactly, or none. */
+export declare function matchRoute(routes: readonly ProxyRoute[], method: string, path: string): {
+    route: ProxyRoute;
+    query: string;
+};
+/** Parse one JSON value, refusing a duplicate key at any depth and nesting past 64 levels. */
+export declare function parseStrict(text: string): unknown;
+/** Whether `given` is `key`, in time that does not depend on where they differ. */
+export declare const sameKey: (given: string, key: string) => boolean;
+/** Start a session's model proxy on the loopback interface, admitting `key`. */
+/**
+ * The most input tokens a request with body `sent` (the body `apply` returned, as it is sent) can be billed for: its UTF-8
+ * byte count, plus the input the policy says the provider adds that the body does not carry. A provider's tokenizer is a
+ * byte-level BPE, whose every token covers at least one byte of what it encodes, so the text the body carries can never
+ * be more tokens than bytes, however dense (CJK, emoji, base64). It is not an average of characters per token, which
+ * undercounts dense text. Undefined, never 0, when the policy says the body has no bound (its undefined) or its figure
+ * cannot be read (a throw, or no count, which is reported): the input is then unmeasured.
+ */
+export declare function inputTokensMaxOf(policy: ProviderPolicy, body: Record<string, unknown>, sent: string, say?: (message: string, detail?: Record<string, unknown>) => void): number | undefined;
+export declare function startModelProxy(options: ModelProxyOptions, key: string): Promise<ModelProxy>;