@wacry/codeks-bridge 0.0.0-stage → 0.0.3

package/dist/errors.js

@@ -0,0 +1,141 @@
+import { forwardResponseHeaders } from "./headers.js";
+/** Native Responses HTTP failures retain their transport-level meaning. */
+export class UpstreamHttpError extends Error {
+    status;
+    body;
+    headers;
+    constructor(status, body, headers) {
+        super(`Upstream returned HTTP ${status}`);
+        this.name = "UpstreamHttpError";
+        this.status = status;
+        this.body = body;
+        this.headers = headers;
+    }
+}
+/** A Responses failure belongs to the SSE protocol, not HTTP classification. */
+export class ResponsesStreamError extends Error {
+    error;
+    response;
+    event;
+    headers;
+    constructor(error, response, event, headers) {
+        super(typeof error.message === "string" ? error.message : "The upstream response failed");
+        this.name = "ResponsesStreamError";
+        this.error = error;
+        this.response = response;
+        this.event = event;
+        this.headers = headers;
+    }
+}
+/** An incomplete response has its own client termination and usage semantics. */
+export class ResponsesIncompleteError extends Error {
+    response;
+    event;
+    constructor(response, event) {
+        super(`The upstream response is incomplete: ${String(response.incomplete_details?.reason ?? "unknown")}`);
+        this.name = "ResponsesIncompleteError";
+        this.response = response;
+        this.event = event;
+    }
+}
+/** Client retry classification is separate from the unmodified upstream failure. */
+export class BridgeError extends Error {
+    code;
+    status;
+    headers;
+    upstream;
+    constructor(message, code = "invalid_prompt", status = 400, headers, options) {
+        super(message, options);
+        this.name = "BridgeError";
+        this.code = code;
+        this.status = status;
+        this.headers = headers;
+        this.upstream = options?.upstream;
+    }
+}
+function record(value) {
+    return value !== null && typeof value === "object" ? value : undefined;
+}
+function retryAfter(value) {
+    if (value instanceof Headers)
+        return value.get("retry-after") ?? undefined;
+    for (const [name, content] of Object.entries(record(value) ?? {})) {
+        if (name.toLowerCase() === "retry-after" && (typeof content === "string" || typeof content === "number"))
+            return String(content);
+    }
+    return undefined;
+}
+/** Keep native fields; only supplement missing retry advice from HTTP headers. */
+export function responsesStreamError(payload, headers, event) {
+    const envelope = record(payload);
+    const response = envelope?.error !== undefined && (envelope.object === "response" || typeof envelope.status === "string" ||
+        (event?.type === "response.failed" && event.response !== undefined)) ? envelope : undefined;
+    let error = record(envelope?.error ?? payload) ?? {};
+    const delay = retryAfter(headers);
+    if (delay !== undefined && retryAfter(error.headers) === undefined) {
+        error = { ...error, headers: { ...record(error.headers), "retry-after": delay } };
+    }
+    return new ResponsesStreamError(error, response ? { ...response, error } : undefined, event, headers);
+}
+/** Translate non-Responses protocols into errors understood by the client. */
+export function upstreamError(status, payload, headers) {
+    const envelope = record(payload);
+    const raw = envelope?.error ?? payload;
+    const error = record(raw);
+    const message = typeof error?.message === "string" ? error.message
+        : typeof raw === "string" && raw.length ? raw
+            : status !== undefined ? `Upstream returned HTTP ${status}` : "The upstream response failed";
+    const kind = [error?.code, error?.type].filter((value) => typeof value === "string").join(" ");
+    let code;
+    if (/context_length|too_many_tokens/.test(kind) || /prompt is too long|maximum context length|too many tokens/i.test(message))
+        code = "context_length_exceeded";
+    else if (/quota|billing|credit|balance/.test(kind) || /insufficient (quota|credit|balance)/i.test(message))
+        code = "insufficient_quota";
+    else if (status === 429 || /rate_limit|slow_down/.test(kind))
+        code = "rate_limit_exceeded";
+    else if (status === 503 || status === 529 || /overload/.test(kind))
+        code = "server_is_overloaded";
+    else if (/stream_error/.test(kind))
+        code = "stream_error";
+    else if (/invalid|authentication|permission|not_found/.test(kind))
+        code = "invalid_prompt";
+    else
+        code = status !== undefined && status < 500 ? "invalid_prompt" : "upstream_error";
+    const mappedStatus = code === "rate_limit_exceeded" || code === "insufficient_quota" ? 429
+        : code === "server_is_overloaded" ? 503
+            : code === "invalid_prompt" || code === "context_length_exceeded" ? 400 : 502;
+    const delay = retryAfter(headers) ?? retryAfter(error?.headers) ?? retryAfter(envelope?.headers);
+    const forwarded = headers ? forwardResponseHeaders(headers) : {};
+    if (delay !== undefined)
+        forwarded["retry-after"] = delay;
+    return new BridgeError(message, code, status ?? mappedStatus, Object.keys(forwarded).length ? forwarded : undefined, {
+        upstream: { ...(status !== undefined ? { status } : {}), body: payload },
+    });
+}
+function transportFailure(value, seen = new Set()) {
+    const error = record(value);
+    const result = { message: typeof error?.message === "string" ? error.message : typeof value === "string" ? value : "Upstream request failed" };
+    if (seen.has(value))
+        return result;
+    seen.add(value);
+    if (typeof error?.name === "string")
+        result.name = error.name;
+    if (typeof error?.code === "string")
+        result.code = error.code;
+    if (error?.cause !== undefined)
+        result.cause = transportFailure(error.cause, seen);
+    if (Array.isArray(error?.errors))
+        result.errors = error.errors.map((cause) => transportFailure(cause, seen));
+    return result;
+}
+function transportMessage(error) {
+    const own = error.code ? `${error.message} (${error.code})` : error.message;
+    return [own, ...(error.cause ? [transportMessage(error.cause)] : []), ...(error.errors?.map(transportMessage) ?? [])].filter(Boolean).join(": ");
+}
+/** Pick only diagnostics; fetch options and credential-command output must not escape. */
+export function transportError(cause) {
+    if (cause instanceof BridgeError)
+        return cause;
+    const failure = transportFailure(cause);
+    return new BridgeError(transportMessage(failure), "upstream_error", 502, undefined, { cause: failure });
+}

package/dist/headers.d.ts

@@ -0,0 +1,6 @@
+import type { IncomingHttpHeaders } from "node:http";
+export type HeaderRecord = Record<string, string | string[]>;
+export declare function incomingHeaders(input: IncomingHttpHeaders): Headers;
+/** Credentials belong to the selected upstream, never to the bridge client. */
+export declare function forwardRequestHeaders(input?: Headers, authHeader?: string): Headers;
+export declare function forwardResponseHeaders(input: Headers, rewritten?: boolean): HeaderRecord;

package/dist/headers.js

@@ -0,0 +1,39 @@
+const HOP_BY_HOP = ["connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "proxy-connection", "te", "trailer", "transfer-encoding", "upgrade"];
+/** Each HTTP leg owns its framing; metadata is forwarded unless it conflicts. */
+function withoutTransportHeaders(input) {
+    const headers = new Headers(input);
+    const connection = (headers.get("connection") ?? "").split(",").map(name => name.trim()).filter(Boolean);
+    for (const name of [...connection, ...HOP_BY_HOP, "content-length", "content-encoding", "content-md5", "digest", "content-digest", "repr-digest"])
+        headers.delete(name);
+    return headers;
+}
+export function incomingHeaders(input) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(input)) {
+        for (const item of Array.isArray(value) ? value : value === undefined ? [] : [value])
+            headers.append(name, item);
+    }
+    return headers;
+}
+/** Credentials belong to the selected upstream, never to the bridge client. */
+export function forwardRequestHeaders(input, authHeader) {
+    const headers = withoutTransportHeaders(input);
+    for (const name of ["host", "accept-encoding", "authorization", "x-api-key", "api-key", "cookie", ...(authHeader ? [authHeader] : [])])
+        headers.delete(name);
+    return headers;
+}
+export function forwardResponseHeaders(input, rewritten = true) {
+    const headers = withoutTransportHeaders(input);
+    // The catalog belongs to the bridge even when the selected upstream also
+    // serves Codex. Rewritten bodies need their own content type.
+    headers.delete("x-models-etag");
+    if (rewritten) {
+        headers.delete("content-type");
+        headers.delete("etag");
+    }
+    const result = Object.fromEntries(headers);
+    const cookies = headers.getSetCookie();
+    if (cookies.length)
+        result["set-cookie"] = cookies;
+    return result;
+}

package/dist/history.d.ts

@@ -0,0 +1,7 @@
+import { type CompactionCarrier, type StatePayload } from "./carrier.ts";
+import type { ResolvedModel, ResponsesRequest } from "./types.ts";
+/** Replay policy for decoded state. The inspector reports the same decisions. */
+export declare function replaysReasoning(carrier: StatePayload, route: ResolvedModel): boolean;
+export declare function restoresNativeCompaction(carrier: CompactionCarrier, route: ResolvedModel): boolean;
+/** Selects model-specific opaque state without changing the stored history. */
+export declare function prepareHistory(input: ResponsesRequest["input"], route: ResolvedModel): Record<string, any>[];

package/dist/history.js

@@ -0,0 +1,85 @@
+import { decodeCompaction, decodeReasoning } from "./carrier.js";
+import { BridgeError } from "./errors.js";
+import { SUMMARY_PREFIX } from "./prompts.js";
+import { translateToolHistory } from "./tool-history.js";
+/** Replay policy for decoded state. The inspector reports the same decisions. */
+export function replaysReasoning(carrier, route) {
+    return route.replay.reasoning.has(carrier.source.id) && carrier.format === route.profile.reasoning_format;
+}
+export function restoresNativeCompaction(carrier, route) {
+    return !!carrier.native && route.compaction.native_replay &&
+        route.replay.native_compaction.has(carrier.native.source.id) &&
+        carrier.native.format === route.profile.native_compaction_format;
+}
+/** Selects model-specific opaque state without changing the stored history. */
+export function prepareHistory(input, route) {
+    if (typeof input === "string") {
+        return [{ type: "message", role: "user", content: [{ type: "input_text", text: input }] }];
+    }
+    if (input === undefined)
+        return [];
+    if (!Array.isArray(input))
+        throw new BridgeError("input must be a string or an array of items");
+    const result = [];
+    for (const original of input) {
+        if (!original || typeof original !== "object" || Array.isArray(original)) {
+            throw new BridgeError("Each input item must be an object");
+        }
+        const item = structuredClone(original);
+        if (item.type === "bridge_reasoning") {
+            throw new BridgeError("Internal reasoning items cannot be supplied as request history");
+        }
+        if (item.type === "item_reference") {
+            throw new BridgeError("Stored item references are unsupported; send the complete conversation items");
+        }
+        if (item.type === "reasoning") {
+            const carrier = decodeReasoning(item.encrypted_content);
+            if (carrier && replaysReasoning(carrier, route)) {
+                result.push({ type: "bridge_reasoning", state: carrier, summary: item.summary ?? [] });
+            }
+            continue;
+        }
+        if (item.type === "agent_message" && route.profile.api !== "responses") {
+            if (typeof item.author !== "string" || typeof item.recipient !== "string" || !Array.isArray(item.content)) {
+                throw new BridgeError("An agent message requires author, recipient, and content");
+            }
+            if (item.encrypted_content || item.content.some((part) => part?.type === "encrypted_content")) {
+                throw new BridgeError("Encrypted agent messages are unsupported on this backend; use plaintext agent messages");
+            }
+            for (const part of item.content) {
+                if (!["input_text", "input_image"].includes(part?.type)) {
+                    throw new BridgeError(`Unsupported agent message content: ${String(part?.type)}`);
+                }
+            }
+            result.push({
+                type: "message", role: "user",
+                content: [
+                    { type: "input_text", text: `Agent message from ${JSON.stringify(item.author)} to ${JSON.stringify(item.recipient)}:\n` },
+                    ...item.content,
+                ],
+            });
+            continue;
+        }
+        if (item.type === "compaction" || item.type === "compaction_summary") {
+            const carrier = decodeCompaction(item.encrypted_content);
+            if (!carrier) {
+                throw new BridgeError("This compaction item has no portable summary or handoff recipe; use history created through this bridge");
+            }
+            if (restoresNativeCompaction(carrier, route)) {
+                result.push(carrier.native.data);
+            }
+            else {
+                if (!carrier.summary)
+                    throw new BridgeError("Deferred compaction summary has not been materialized");
+                result.push({
+                    type: "message",
+                    role: "user",
+                    content: [{ type: "input_text", text: `${SUMMARY_PREFIX}\n\n${carrier.summary}` }],
+                });
+            }
+            continue;
+        }
+        result.push(item);
+    }
+    return route.profile.api === "responses" ? result : translateToolHistory(result);
+}

package/dist/ids.d.ts

@@ -0,0 +1 @@
+export declare function newId(prefix: string): string;

package/dist/ids.js

@@ -0,0 +1,4 @@
+import { randomBytes } from "node:crypto";
+export function newId(prefix) {
+    return `${prefix}_${randomBytes(12).toString("hex")}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createBridgeServer } from "./server.ts";
+export { loadConfig, validateConfig, resolveModel } from "./config.ts";
+export { buildCatalog, configSnippet } from "./catalog.ts";
+export { BridgeError } from "./errors.ts";
+export type { BridgeConfig, UpstreamConfig, ModelConfig } from "./types.ts";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createBridgeServer } from "./server.js";
+export { loadConfig, validateConfig, resolveModel } from "./config.js";
+export { buildCatalog, configSnippet } from "./catalog.js";
+export { BridgeError } from "./errors.js";

package/dist/inspect/capture.d.ts

@@ -0,0 +1,119 @@
+import type { IncomingHttpHeaders, IncomingMessage, OutgoingHttpHeaders, ServerResponse } from "node:http";
+import type { BridgeConfig, ResolvedModel, ResponsesRequest } from "../types.ts";
+export declare const DEFAULT_CAPTURE_MIB = 256;
+export type EndKind = "active" | "complete" | "cancelled" | "error" | "unread";
+export type HeaderMap = Record<string, string>;
+export interface Part {
+    t: number;
+    text: string;
+}
+/** Lowercase names, join repeated values, and redact credentials. */
+export declare function headerMap(headers: Headers | IncomingHttpHeaders | OutgoingHttpHeaders | undefined, extra?: ReadonlySet<string>): HeaderMap;
+/** One HTTP message after its start line: status, headers, and timed body parts. */
+export declare class Message {
+    status?: number;
+    statusText?: string;
+    headers?: HeaderMap;
+    headersMs?: number;
+    endedMs?: number;
+    end: EndKind;
+    error?: string;
+    readonly parts: Part[];
+    bytes: number;
+    private readonly decoder;
+    private readonly exchange;
+    constructor(exchange: Exchange);
+    head(status: number, statusText: string | undefined, headers: HeaderMap): void;
+    push(chunk: Uint8Array | string): void;
+    finish(end: Exclude<EndKind, "active">, error?: unknown): void;
+    text(): string;
+    discard(): void;
+}
+/** One request from the bridge to an upstream. */
+export declare class Call {
+    readonly index: number;
+    readonly label: string;
+    readonly startedMs: number;
+    readonly method = "POST";
+    readonly url: string;
+    readonly headers: HeaderMap;
+    text: string;
+    bytes: number;
+    error?: string;
+    response?: Message;
+    private readonly exchange;
+    constructor(exchange: Exchange, label: string, url: string, headers: HeaderMap, text: string);
+    received(response: Response): void;
+    chunk(value: Uint8Array): void;
+    done(end: Exclude<EndKind, "active">, error?: unknown): void;
+    failed(error: unknown): void;
+    discard(): void;
+}
+export interface RequestMeta {
+    model: string | null;
+    kind: "turn" | "compaction" | "invalid";
+    stream: boolean | null;
+    input_items: number | null;
+    preview: string | null;
+}
+/** One client request and everything it caused. */
+export declare class Exchange {
+    readonly id: string;
+    readonly seq: number;
+    rev: number;
+    readonly startedAt: number;
+    durationMs?: number;
+    closed: boolean;
+    readonly method: string;
+    readonly path: string;
+    readonly headers: HeaderMap;
+    requestText?: string;
+    requestBytes: number;
+    meta: RequestMeta;
+    route?: ResolvedModel;
+    responsesLite?: boolean;
+    readonly calls: Call[];
+    readonly response: Message;
+    bytes: number;
+    readonly inspector: Inspector;
+    private readonly t0;
+    constructor(inspector: Inspector, seq: number, req: IncomingMessage, res: ServerResponse);
+    now(): number;
+    touch(): void;
+    account(bytes: number): void;
+    received(text: string): void;
+    parsed(request: ResponsesRequest): void;
+    routed(route: ResolvedModel, responsesLite: boolean): void;
+    /** Records what the bridge writes, at the same calls that write it. */
+    private tap;
+    private close;
+    /** Releases captured data without stopping the underlying HTTP exchange. */
+    discard(): void;
+}
+/** Process-wide capture store. Nothing is kept unless capture is on. */
+export declare class Inspector {
+    capturing: boolean;
+    readonly maxBytes: number;
+    bytes: number;
+    evicted: number;
+    rev: number;
+    private seq;
+    readonly startedAt: number;
+    readonly exchanges: Map<string, Exchange>;
+    readonly config: BridgeConfig;
+    private readonly redactions;
+    constructor(config: BridgeConfig);
+    /** Runs one server request with a slot for its exchange. */
+    scope<T>(fn: () => T): T;
+    begin(req: IncomingMessage, res: ServerResponse): Exchange | undefined;
+    /** Records one upstream request made inside the current exchange. */
+    upstream(url: string, headers: Headers, text: string): Call | undefined;
+    account(exchange: Exchange, bytes: number): void;
+    /** Rechecks the soft cap when bytes arrive or an active exchange closes. */
+    evict(): void;
+    clear(): void;
+}
+/** Labels upstream calls made inside fn, such as native compaction or a handoff. */
+export declare function withCaptureLabel<T>(label: string, fn: () => T): T;
+/** Records an upstream request when the current server request is being captured. */
+export declare function captureUpstream(url: string, headers: Headers, text: string): Call | undefined;