@wacry/codeks-bridge 0.0.0-stage → 0.0.3

package/dist/catalog.js

@@ -0,0 +1,40 @@
+import { modelProfile } from "./profiles.js";
+import { BridgeError } from "./errors.js";
+/** Codex bounds downloads from an explicit model_catalog_url to 1 MiB. */
+export const MAX_HTTP_CATALOG_BYTES = 1024 * 1024;
+function exposedModels(config) {
+    return Object.entries(config.models).filter(([, model]) => model.expose !== false);
+}
+/** Serve client-exposed aliases, using their own reviewed client behavior. */
+export function buildCatalog(config) {
+    return { models: exposedModels(config).map(([slug, model], priority) => ({
+            ...modelProfile(model).model_info,
+            slug, display_name: slug, priority, visibility: "list", supported_in_api: true,
+        })) };
+}
+export function configSnippet(config, catalogPath) {
+    const first = exposedModels(config)[0]?.[0];
+    if (first === undefined)
+        throw new BridgeError("config-snippet requires at least one model with expose enabled");
+    const host = ["0.0.0.0", "::"].includes(config.host ?? "") ? "127.0.0.1" : config.host ?? "127.0.0.1";
+    const authority = host.includes(":") ? `[${host}]` : host;
+    const baseUrl = `http://${authority}:${config.port ?? 8787}/v1`;
+    const lines = [
+        `model = ${JSON.stringify(first)}`, 'model_provider = "bridge"',
+        ...(catalogPath ? [`model_catalog_json = ${JSON.stringify(catalogPath)}`] : []),
+        'web_search = "disabled"', "", "[features]", "image_generation = false", "",
+        // Outside the reserved "collaboration" namespace, codeks sends multi-agent task messages as plaintext.
+        "[features.multi_agent_v2]", 'tool_namespace = "agents"', "",
+        "[model_providers.bridge]", 'name = "Local bridge"',
+        `base_url = ${JSON.stringify(baseUrl)}`, 'wire_api = "responses"',
+    ];
+    if (!catalogPath)
+        lines.push(`model_catalog_url = ${JSON.stringify(`${baseUrl}/models`)}`);
+    if (config.token_env)
+        lines.push(`env_key = ${JSON.stringify(config.token_env)}`);
+    // Codex requires API-key auth mode for provider catalog discovery, even on loopback.
+    else if (!catalogPath)
+        lines.push('experimental_bearer_token = "codeks-bridge-local"');
+    lines.push("", "[model_providers.bridge.capabilities]", 'remote_compaction = "v2"', "");
+    return lines.join("\n");
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { loadConfig } from "./config.js";
+import { createBridgeServer } from "./server.js";
+import { buildCatalog, configSnippet } from "./catalog.js";
+const HELP = `Usage: codeks-bridge <command> --config <file> [options]
+
+Commands:
+  serve           Start the local Responses API server
+  catalog         Export the client-visible model catalog for codeks
+  config-snippet  Print the codeks provider configuration
+
+Options:
+  --output <file>        Write catalog JSON (otherwise stdout)
+  --catalog <file>       Use a static catalog instead of HTTP discovery
+  --capture              Start serve with inspector capture on
+  --help                Show this help
+`;
+async function main() {
+    const { values, positionals } = parseArgs({ allowPositionals: true, options: {
+            config: { type: "string" }, output: { type: "string" },
+            catalog: { type: "string" }, capture: { type: "boolean" }, help: { type: "boolean" },
+        } });
+    if (values.help || positionals.length === 0) {
+        process.stdout.write(HELP);
+        return;
+    }
+    const command = positionals[0];
+    if (positionals.length !== 1 || !["serve", "catalog", "config-snippet"].includes(command))
+        throw new Error("Unknown command. Use --help.");
+    if (!values.config)
+        throw new Error("--config is required");
+    const config = await loadConfig(values.config);
+    if (command === "catalog") {
+        const text = JSON.stringify(buildCatalog(config), null, 2) + "\n";
+        if (values.output)
+            await writeFile(values.output, text, { mode: 0o600 });
+        else
+            process.stdout.write(text);
+    }
+    else if (command === "config-snippet") {
+        process.stdout.write(configSnippet(config, values.catalog ? resolve(values.catalog) : undefined));
+    }
+    else {
+        if (values.capture)
+            config.inspect = { ...config.inspect, capture: true };
+        const server = createBridgeServer(config);
+        server.on("error", error => { process.stderr.write(`Server error: ${error.message}\n`); process.exitCode = 1; });
+        server.listen(config.port ?? 8787, config.host ?? "127.0.0.1", () => {
+            const address = server.address();
+            const port = typeof address === "object" ? address?.port : config.port;
+            const host = config.host ?? "127.0.0.1";
+            const shown = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host.includes(":") ? `[${host}]` : host;
+            process.stderr.write(`Listening on ${host}:${port}\n`);
+            process.stderr.write(`Inspector: http://${shown}:${port}/inspect/ (capture ${config.inspect?.capture ? "on" : "off"})\n`);
+        });
+        const stop = () => { server.close(); server.closeAllConnections(); };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+    }
+}
+main().catch(error => { process.stderr.write(`${error instanceof Error ? error.message : "Command failed"}\n`); process.exitCode = 1; });

package/dist/compaction-handoff.d.ts

@@ -0,0 +1,13 @@
+import type { AdapterId, Backend, BackendContext, BridgeConfig, ResponsesRequest } from "./types.ts";
+/** Successful exports survive restarts; each caller owns only its own cancellation. */
+export declare class CompactionHandoffStore {
+    readonly directory: string;
+    private readonly config;
+    private readonly backends;
+    private readonly pending;
+    constructor(config: BridgeConfig, backends: Record<AdapterId, Backend>);
+    private source;
+    private summary;
+    /** Only checkpoint predecessors enter the export; later work stays on the target. */
+    materialize(context: BackendContext): Promise<ResponsesRequest>;
+}

package/dist/compaction-handoff.js

@@ -0,0 +1,126 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { decodeCompaction, encodeCompaction } from "./carrier.js";
+import { collectHandoff, handoffRequest } from "./compaction.js";
+import { splitCompactionPrefix } from "./compaction-history.js";
+import { resolveModel } from "./config.js";
+import { BridgeError } from "./errors.js";
+import { restoresNativeCompaction } from "./history.js";
+function waitForTurn(previous, signal) {
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const abort = () => { signal.removeEventListener("abort", abort); reject(signal.reason); };
+        signal.addEventListener("abort", abort, { once: true });
+        previous.then(() => {
+            signal.removeEventListener("abort", abort);
+            if (signal.aborted)
+                reject(signal.reason);
+            else
+                resolve();
+        });
+    });
+}
+/** Successful exports survive restarts; each caller owns only its own cancellation. */
+export class CompactionHandoffStore {
+    directory;
+    config;
+    backends;
+    pending = new Map();
+    constructor(config, backends) {
+        this.config = config;
+        this.backends = backends;
+        this.directory = config.compaction_cache_dir ?? join(process.env.XDG_CACHE_HOME || join(homedir(), ".cache"), "codeks-bridge", "compaction");
+    }
+    source(carrier) {
+        const preferred = carrier.handoff.parameters.model;
+        const aliases = [...new Set([preferred, ...Object.keys(this.config.models)])];
+        for (const alias of aliases) {
+            if (!Object.hasOwn(this.config.models, alias))
+                continue;
+            const route = resolveModel(this.config, alias);
+            if (route.origin.id === carrier.native.source.id)
+                return route;
+        }
+        throw new BridgeError("The original compaction source is not configured; restore its model and upstream to generate a handoff.");
+    }
+    async summary(carrier, request, context) {
+        const { signal } = context;
+        const key = createHash("sha256").update(JSON.stringify({
+            source: carrier.native.source,
+            request,
+            responsesLite: carrier.handoff.responsesLite,
+        })).digest("hex");
+        const previous = this.pending.get(key) ?? Promise.resolve();
+        let release;
+        const gate = new Promise(resolve => { release = resolve; });
+        const tail = previous.then(() => gate);
+        this.pending.set(key, tail);
+        void tail.then(() => { if (this.pending.get(key) === tail)
+            this.pending.delete(key); });
+        try {
+            await waitForTurn(previous, signal);
+            const path = join(this.directory, `${key}.json`);
+            try {
+                const cached = JSON.parse(await readFile(path, "utf8"));
+                if (typeof cached.summary !== "string" || !cached.summary.trim())
+                    throw new BridgeError("Invalid cached compaction handoff.");
+                signal.throwIfAborted();
+                return cached.summary;
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            signal.throwIfAborted();
+            const route = this.source(carrier);
+            const result = await collectHandoff({
+                request: { ...request, model: route.slug }, route, signal,
+                requestHeaders: context.requestHeaders,
+                responsesLite: carrier.handoff.responsesLite,
+            }, this.backends[route.profile.id]);
+            signal.throwIfAborted();
+            await mkdir(this.directory, { recursive: true, mode: 0o700 });
+            const temporary = join(this.directory, `.${key}.${randomUUID()}.tmp`);
+            try {
+                // Usage belongs to this export, never to the destination model's context.
+                await writeFile(temporary, JSON.stringify(result), { mode: 0o600, flag: "wx" });
+                await rename(temporary, path);
+            }
+            finally {
+                await unlink(temporary).catch((error) => { if (error.code !== "ENOENT")
+                    throw error; });
+            }
+            signal.throwIfAborted();
+            return result.summary;
+        }
+        finally {
+            release();
+        }
+    }
+    /** Only checkpoint predecessors enter the export; later work stays on the target. */
+    async materialize(context) {
+        if (!Array.isArray(context.request.input))
+            return context.request;
+        let changed = false;
+        const input = context.request.input;
+        const prepared = [...input];
+        for (let i = 0; i < input.length; i++) {
+            const item = input[i];
+            if (item.type !== "compaction" && item.type !== "compaction_summary")
+                continue;
+            const carrier = decodeCompaction(item.encrypted_content);
+            if (!carrier || carrier.summary !== undefined || restoresNativeCompaction(carrier, context.route))
+                continue;
+            if (!carrier.native || !carrier.handoff)
+                throw new BridgeError("This compaction checkpoint has no handoff recipe.");
+            const { history } = splitCompactionPrefix(input.slice(0, i));
+            const request = handoffRequest(carrier.handoff, history, item);
+            const summary = await this.summary(carrier, request, context);
+            prepared[i] = { ...item, encrypted_content: encodeCompaction({ ...carrier, summary }) };
+            changed = true;
+        }
+        return changed ? { ...context.request, input: prepared } : context.request;
+    }
+}

package/dist/compaction-history.d.ts

@@ -0,0 +1,7 @@
+type Item = Record<string, any>;
+/** Save source instructions and Lite declarations, without saving old conversation turns. */
+export declare function splitCompactionPrefix(input: readonly Item[]): {
+    prefix: Item[];
+    history: Item[];
+};
+export {};

package/dist/compaction-history.js

@@ -0,0 +1,20 @@
+const isMessage = (item) => item.type === "message" || (!item.type && typeof item.role === "string");
+/** Save source instructions and Lite declarations, without saving old conversation turns. */
+export function splitCompactionPrefix(input) {
+    const prefix = [];
+    const history = [];
+    let leading = true;
+    for (const item of input) {
+        if (item.type === "additional_tools") {
+            prefix.push(item);
+        }
+        else if (leading && isMessage(item) && ["system", "developer"].includes(item.role)) {
+            prefix.push(item);
+        }
+        else {
+            leading = false;
+            history.push(item);
+        }
+    }
+    return { prefix, history };
+}

package/dist/compaction.d.ts

@@ -0,0 +1,20 @@
+import type { HandoffRecipe } from "./carrier.ts";
+import type { Backend, BackendContext, ResponsesRequest } from "./types.ts";
+import type { Usage } from "./writer.ts";
+type Item = Record<string, any>;
+export interface CompactionResult {
+    item: Record<string, unknown>;
+    usage: Usage;
+}
+export declare function isCompactionRequest(request: ResponsesRequest): boolean;
+/** Keep the shared prefix intact, including tools and any signed reasoning. */
+export declare function summaryRequest(request: ResponsesRequest): ResponsesRequest;
+/** Rephrase the checkpoint using the exact history retained by the client. */
+export declare function handoffRequest(recipe: HandoffRecipe, retained: Item[], checkpoint: Item): ResponsesRequest;
+export declare function collectHandoff(context: BackendContext, backend: Backend): Promise<{
+    summary: string;
+    usage: Usage;
+}>;
+/** Publish a complete native checkpoint or portable text summary. */
+export declare function compact(context: BackendContext, backend: Backend): Promise<CompactionResult>;
+export {};

package/dist/compaction.js

@@ -0,0 +1,134 @@
+import { encodeCompaction } from "./carrier.js";
+import { splitCompactionPrefix } from "./compaction-history.js";
+import { BridgeError, ResponsesIncompleteError, ResponsesStreamError } from "./errors.js";
+import { newId } from "./ids.js";
+import { withCaptureLabel } from "./inspect/capture.js";
+import { HANDOFF_PROMPT, SUMMARIZATION_PROMPT } from "./prompts.js";
+import { ResponseWriter } from "./writer.js";
+export function isCompactionRequest(request) {
+    return Array.isArray(request.input) && request.input.some((item) => item.type === "compaction_trigger");
+}
+function compactionInput(request) {
+    if (!Array.isArray(request.input))
+        throw new BridgeError("Compaction requires an input array.");
+    const triggers = request.input.filter((item) => item.type === "compaction_trigger");
+    if (triggers.length !== 1 || request.input.at(-1)?.type !== "compaction_trigger") {
+        throw new BridgeError("Compaction requires exactly one trigger at the end of input.");
+    }
+    return request.input.slice(0, -1);
+}
+/** Keep the shared prefix intact, including tools and any signed reasoning. */
+export function summaryRequest(request) {
+    const input = compactionInput(request);
+    const result = {
+        ...request,
+        input: [...input, { type: "message", role: "user", content: [{ type: "input_text", text: SUMMARIZATION_PROMPT }] }],
+        stream: true,
+    };
+    // A conversation's structured output schema does not describe a handoff summary.
+    delete result.text;
+    return result;
+}
+function handoffRecipe(context, prefix) {
+    // The handoff rebuilds input and transport mode; a summary is not a structured answer.
+    const { input: _input, stream: _stream, text: _text, ...parameters } = context.request;
+    parameters.reasoning = { ...parameters.reasoning, effort: parameters.reasoning?.effort ?? context.route.profile.default_effort };
+    return structuredClone({ prefix, parameters, responsesLite: context.responsesLite === true });
+}
+/** Rephrase the checkpoint using the exact history retained by the client. */
+export function handoffRequest(recipe, retained, checkpoint) {
+    return {
+        ...recipe.parameters,
+        input: [...recipe.prefix, ...retained, checkpoint,
+            { type: "message", role: "user", content: [{ type: "input_text", text: HANDOFF_PROMPT }] }],
+        stream: true,
+    };
+}
+async function collect(context, backend) {
+    const writer = new ResponseWriter({ write() { } }, { model: context.request.model, showSummary: false });
+    let result;
+    try {
+        result = await backend(context, writer);
+    }
+    catch (cause) {
+        // Auxiliary output and usage must not become the client's replacement history.
+        if (cause instanceof ResponsesIncompleteError) {
+            throw new BridgeError(cause.message, "invalid_prompt", 400, undefined, { upstream: { body: cause.response }, cause });
+        }
+        if (cause instanceof ResponsesStreamError && cause.response) {
+            const { output: _output, usage: _usage, ...response } = cause.response;
+            throw new ResponsesStreamError(cause.error, { ...response, output: [] }, cause.event, cause.headers);
+        }
+        throw cause;
+    }
+    context.signal.throwIfAborted();
+    writer.complete(result.usage);
+    return { output: writer.outputItems, usage: result.usage, endTurn: result.endTurn };
+}
+function summaryText({ output, endTurn }) {
+    const parts = [];
+    for (const value of output) {
+        const item = value;
+        if (item.type === "function_call" || item.type === "custom_tool_call") {
+            throw new BridgeError("Compaction returned a tool call instead of a summary. No tools were executed.");
+        }
+        if (item.type !== "message" || item.role !== "assistant" || !Array.isArray(item.content))
+            continue;
+        for (const part of item.content) {
+            if (part.type === "refusal")
+                throw new BridgeError("Compaction was refused.");
+            if (part.type === "output_text" && typeof part.text === "string")
+                parts.push(part.text);
+        }
+    }
+    if (endTurn === false)
+        throw new BridgeError("Compaction did not finish its response.");
+    const summary = parts.join("\n").trim();
+    if (!summary)
+        throw new BridgeError("Compaction returned an empty summary.");
+    return summary;
+}
+export async function collectHandoff(context, backend) {
+    // Generating text from the source's own native state is independent of whether
+    // that route normally chooses to replay native checkpoints in ordinary turns.
+    const route = { ...context.route, compaction: { ...context.route.compaction, native_replay: true } };
+    const result = await withCaptureLabel("handoff", () => collect({ ...context, route, compacting: true }, backend));
+    return { summary: summaryText(result), usage: result.usage };
+}
+function nativeItem(output) {
+    const items = output.filter((value) => {
+        const item = value;
+        return item.type === "compaction" || item.type === "compaction_summary";
+    });
+    if (items.length !== 1 || typeof items[0]?.encrypted_content !== "string" || !items[0].encrypted_content) {
+        throw new BridgeError("Native compaction must return exactly one nonempty compaction item.");
+    }
+    return items[0];
+}
+/** Publish a complete native checkpoint or portable text summary. */
+export async function compact(context, backend) {
+    const input = compactionInput(context.request);
+    context.signal.throwIfAborted();
+    const item = (carrier) => ({
+        type: "compaction", id: newId("cmp"), encrypted_content: encodeCompaction(carrier),
+    });
+    if (context.route.compaction.mode === "summary") {
+        const result = await withCaptureLabel("summary", () => collect({
+            ...context, compacting: true, request: summaryRequest(context.request),
+        }, backend));
+        return { item: item({ summary: summaryText(result) }), usage: result.usage };
+    }
+    const native = await withCaptureLabel("native", () => collect({
+        ...context, compacting: true, request: { ...context.request, stream: true },
+    }, backend));
+    if (native.endTurn === false)
+        throw new BridgeError("Compaction did not finish its response.");
+    const { prefix } = splitCompactionPrefix(input);
+    return {
+        item: item({
+            native: { source: context.route.origin, format: context.route.profile.native_compaction_format, data: nativeItem(native.output) },
+            handoff: handoffRecipe(context, prefix),
+        }),
+        usage: native.usage,
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+import type { BridgeConfig, ResolvedModel } from "./types.ts";
+export declare function validateConfig(value: unknown): BridgeConfig;
+export declare function loadConfig(path: string): Promise<BridgeConfig>;
+export declare function resolveModel(config: BridgeConfig, slug: string): ResolvedModel;
+/** Select one executor; the caller owns the generation mode, the executor owns replay. */
+export declare function resolveCompactionModel(config: BridgeConfig, caller: ResolvedModel): ResolvedModel;

package/dist/config.js

@@ -0,0 +1,170 @@
+import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { modelProfile } from "./profiles.js";
+import { getCatalogEntry } from "./model-catalog.js";
+import { BridgeError } from "./errors.js";
+import { validateAdapterConfig } from "./adapter-options.js";
+function object(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function fail(message) { throw new BridgeError(`Invalid configuration: ${message}`); }
+function strings(value) {
+    return Array.isArray(value) && value.every(v => typeof v === "string" && v.length > 0);
+}
+const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+/** Record provenance, never policy or credentials, in portable history. */
+function origin(config, model) {
+    const connection = hash([model.upstream, config.upstreams[model.upstream].base_url.replace(/\/+$/, "")]);
+    const { adapter } = getCatalogEntry(model.catalog);
+    return { connection, model: model.model, adapter, id: hash([connection, adapter, model.model]) };
+}
+export function validateConfig(value) {
+    if (!object(value) || !object(value.upstreams) || !object(value.models))
+        fail("upstreams and models must be objects");
+    if (!Object.keys(value.models).length)
+        fail("at least one model is required");
+    if (value.host !== undefined && (typeof value.host !== "string" || !value.host))
+        fail("host must be a string");
+    if (value.port !== undefined && (!Number.isInteger(value.port) || value.port < 0 || value.port > 65535))
+        fail("port must be 0..65535");
+    if (value.token_env !== undefined && (typeof value.token_env !== "string" || !value.token_env))
+        fail("token_env must name an environment variable");
+    if (value.compaction_cache_dir !== undefined && (typeof value.compaction_cache_dir !== "string" || !value.compaction_cache_dir.trim()))
+        fail("compaction_cache_dir must be a nonempty path");
+    if (value.inspect !== undefined) {
+        const inspect = value.inspect;
+        if (!object(inspect))
+            fail("inspect must be an object");
+        if (inspect.capture !== undefined && typeof inspect.capture !== "boolean")
+            fail("inspect.capture must be boolean");
+        if (inspect.max_mib !== undefined && (!Number.isSafeInteger(inspect.max_mib) || inspect.max_mib <= 0))
+            fail("inspect.max_mib must be a positive integer");
+    }
+    for (const [name, up] of Object.entries(value.upstreams)) {
+        if (!object(up))
+            fail(`upstream ${name}: expected a connection object`);
+        let url;
+        try {
+            url = new URL(up.base_url);
+        }
+        catch {
+            fail(`upstream ${name}: invalid base_url`);
+        }
+        if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.search || url.hash)
+            fail(`upstream ${name}: base_url must be an HTTP(S) URL without credentials, query, or fragment`);
+        if (up.api_key_env !== undefined && (typeof up.api_key_env !== "string" || !up.api_key_env))
+            fail(`upstream ${name}: invalid api_key_env`);
+        if (up.api_key_env && up.api_key_command)
+            fail(`upstream ${name}: choose api_key_env or api_key_command`);
+        if (up.api_key_command !== undefined && (!Array.isArray(up.api_key_command) || !up.api_key_command.length || up.api_key_command.some((arg) => typeof arg !== "string")))
+            fail(`upstream ${name}: api_key_command must be a nonempty argv array`);
+        if (up.stream_idle_timeout_ms !== undefined && (!Number.isSafeInteger(up.stream_idle_timeout_ms) || up.stream_idle_timeout_ms <= 0))
+            fail(`upstream ${name}: invalid stream_idle_timeout_ms`);
+        if (up.auth_header !== undefined && (typeof up.auth_header !== "string" || !/^[\w-]+$/.test(up.auth_header)))
+            fail(`upstream ${name}: invalid auth_header`);
+        if (up.headers !== undefined && (!object(up.headers) || Object.values(up.headers).some(v => typeof v !== "string" || /[\r\n]/.test(v))))
+            fail(`upstream ${name}: invalid headers`);
+        if (up.options !== undefined && !object(up.options))
+            fail(`upstream ${name}: options must be an object`);
+        validateAdapterConfig(up.adapters, `upstream ${name}`);
+    }
+    for (const [slug, model] of Object.entries(value.models)) {
+        if (!slug || !object(model) || typeof model.model !== "string" || !model.model || typeof model.upstream !== "string" || !Object.hasOwn(value.upstreams, model.upstream))
+            fail(`model ${slug}: model and an existing upstream are required`);
+        if (typeof model.catalog !== "string" || !model.catalog)
+            fail(`model ${slug}: catalog is required`);
+        if (model.expose !== undefined && typeof model.expose !== "boolean")
+            fail(`model ${slug}: expose must be boolean`);
+        for (const field of ["context_window", "max_output_tokens"]) {
+            if (model[field] !== undefined && (!Number.isSafeInteger(model[field]) || model[field] <= 0))
+                fail(`model ${slug}: ${field} must be a positive integer`);
+        }
+        if (model.options !== undefined && !object(model.options))
+            fail(`model ${slug}: options must be an object`);
+        if (model.input_modalities !== undefined && (!strings(model.input_modalities) || !model.input_modalities.length || model.input_modalities.some((m) => !["text", "image"].includes(m))))
+            fail(`model ${slug}: input_modalities must contain text or image`);
+        if (model.reasoning !== undefined) {
+            const r = model.reasoning;
+            if (!object(r))
+                fail(`model ${slug}: reasoning must be an object`);
+            if (r.default_effort !== undefined && (typeof r.default_effort !== "string" || !r.default_effort))
+                fail(`model ${slug}: invalid default_effort`);
+            if (r.effort_map !== undefined && (!object(r.effort_map) || !Object.keys(r.effort_map).length || Object.entries(r.effort_map).some(([key, native]) => !key || typeof native !== "string" || !native)))
+                fail(`model ${slug}: effort_map must map effort names to upstream values`);
+        }
+        const profile = modelProfile(model);
+        validateAdapterConfig(model.adapters, `model ${slug}`, profile.id);
+        if (Object.hasOwn(profile.effort_map, "ultra") && !profile.multi_agent_effort)
+            fail(`model ${slug}: ultra must map to the same upstream effort as an ordinary level`);
+        if (!Object.hasOwn(profile.effort_map, profile.default_effort))
+            fail(`model ${slug}: default_effort must appear in effort_map`);
+        if (model.replay !== undefined) {
+            if (!object(model.replay))
+                fail(`model ${slug}: replay must be an object`);
+            for (const field of ["reasoning_from", "native_compaction_from"]) {
+                if (model.replay[field] !== undefined && !strings(model.replay[field]))
+                    fail(`model ${slug}: ${field} must list source model aliases`);
+            }
+        }
+        if (model.compaction !== undefined) {
+            const c = model.compaction;
+            if (!object(c))
+                fail(`model ${slug}: compaction must be an object`);
+            if (c.mode !== undefined && !["summary", "native"].includes(c.mode))
+                fail(`model ${slug}: compaction.mode must be summary or native`);
+            if (c.model !== undefined && (typeof c.model !== "string" || !Object.hasOwn(value.models, c.model)))
+                fail(`model ${slug}: compaction.model must name an existing model alias`);
+            if (c.native_replay !== undefined && typeof c.native_replay !== "boolean")
+                fail(`model ${slug}: compaction.native_replay must be boolean`);
+            if (!profile.native_compaction_format && c.native_replay === true)
+                fail(`model ${slug}: adapter has no native compaction representation for replay`);
+        }
+    }
+    // References are directional. Validate decodability, not provider compatibility.
+    const config = value;
+    for (const [slug, model] of Object.entries(config.models)) {
+        const target = modelProfile(model);
+        for (const [field, format] of [["reasoning_from", "reasoning_format"], ["native_compaction_from", "native_compaction_format"]]) {
+            for (const name of model.replay?.[field] ?? []) {
+                if (!Object.hasOwn(config.models, name))
+                    fail(`model ${slug}: unknown replay source ${name}`);
+                const source = modelProfile(config.models[name]);
+                if (!target[format] || source[format] !== target[format])
+                    fail(`model ${slug}: cannot decode ${field} source ${name}`);
+            }
+        }
+    }
+    for (const slug of Object.keys(config.models)) {
+        const executor = resolveCompactionModel(config, resolveModel(config, slug));
+        if (executor.compaction.mode === "native" && !executor.profile.native_compaction_format)
+            fail(`model ${slug}: compaction model ${executor.slug} has no native compaction representation`);
+    }
+    return config;
+}
+export async function loadConfig(path) {
+    return validateConfig(JSON.parse(await readFile(path, "utf8")));
+}
+export function resolveModel(config, slug) {
+    if (typeof slug !== "string" || !Object.hasOwn(config.models, slug))
+        throw new BridgeError("Unknown model. Use GET /v1/models to list exposed models.");
+    const model = config.models[slug];
+    const profile = modelProfile(model);
+    const source = origin(config, model);
+    const allowed = (names = []) => new Set([source.id, ...names.map(name => origin(config, config.models[name]).id)]);
+    return {
+        slug, config: model, upstream: config.upstreams[model.upstream], profile, origin: source,
+        replay: { reasoning: allowed(model.replay?.reasoning_from), native_compaction: allowed(model.replay?.native_compaction_from) },
+        compaction: {
+            mode: model.compaction?.mode ?? (profile.native_compaction_format ? "native" : "summary"),
+            native_replay: model.compaction?.native_replay ?? !!profile.native_compaction_format,
+        },
+    };
+}
+/** Select one executor; the caller owns the generation mode, the executor owns replay. */
+export function resolveCompactionModel(config, caller) {
+    const slug = caller.config.compaction?.model;
+    if (slug === undefined || slug === caller.slug)
+        return caller;
+    const executor = resolveModel(config, slug);
+    return { ...executor, compaction: { ...executor.compaction, mode: caller.compaction.mode } };
+}

package/dist/errors.d.ts

@@ -0,0 +1,43 @@
+import { type HeaderRecord } from "./headers.ts";
+export interface UpstreamFailure {
+    status?: number;
+    body: unknown;
+}
+/** Native Responses HTTP failures retain their transport-level meaning. */
+export declare class UpstreamHttpError extends Error {
+    readonly status: number;
+    readonly body: string;
+    readonly headers: Headers;
+    constructor(status: number, body: string, headers: Headers);
+}
+/** A Responses failure belongs to the SSE protocol, not HTTP classification. */
+export declare class ResponsesStreamError extends Error {
+    readonly error: Record<string, unknown>;
+    readonly response?: Record<string, any>;
+    readonly event?: Record<string, any>;
+    readonly headers?: Headers;
+    constructor(error: Record<string, unknown>, response?: Record<string, any>, event?: Record<string, any>, headers?: Headers);
+}
+/** An incomplete response has its own client termination and usage semantics. */
+export declare class ResponsesIncompleteError extends Error {
+    readonly response: Record<string, any>;
+    readonly event?: Record<string, any>;
+    constructor(response: Record<string, any>, event?: Record<string, any>);
+}
+/** Client retry classification is separate from the unmodified upstream failure. */
+export declare class BridgeError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly headers?: HeaderRecord;
+    readonly upstream?: UpstreamFailure;
+    constructor(message: string, code?: string, status?: number, headers?: HeaderRecord, options?: {
+        upstream?: UpstreamFailure;
+        cause?: unknown;
+    });
+}
+/** Keep native fields; only supplement missing retry advice from HTTP headers. */
+export declare function responsesStreamError(payload: unknown, headers?: Headers, event?: Record<string, any>): ResponsesStreamError;
+/** Translate non-Responses protocols into errors understood by the client. */
+export declare function upstreamError(status: number | undefined, payload: unknown, headers?: Headers): BridgeError;
+/** Pick only diagnostics; fetch options and credential-command output must not escape. */
+export declare function transportError(cause: unknown): BridgeError;