@wacry/codeks-bridge 0.0.0-stage → 0.0.3

package/dist/backends/chat.js

@@ -0,0 +1,284 @@
+import { encodeReasoning } from "../carrier.js";
+import { BridgeError, transportError, upstreamError } from "../errors.js";
+import { prepareHistory } from "../history.js";
+import { parseJsonSse } from "../sse.js";
+import { buildToolSet, normalizeToolDeclarations } from "../tools.js";
+import { upstreamFetch } from "../upstream.js";
+function contentParts(content) {
+    if (typeof content === "string")
+        return [{ type: "text", text: content }];
+    if (!Array.isArray(content))
+        throw new BridgeError("Chat message content must be text or a content array.");
+    return content.map((part) => {
+        if (["input_text", "output_text", "text"].includes(part?.type) && typeof part.text === "string") {
+            return { type: "text", text: part.text };
+        }
+        if (part?.type === "refusal" && typeof part.refusal === "string")
+            return { type: "text", text: part.refusal };
+        if (part?.type === "input_image" && typeof part.image_url === "string") {
+            if (!/^(https?:\/\/|data:image\/)/.test(part.image_url)) {
+                throw new BridgeError("Chat images require an HTTP(S) URL or an image data URL.");
+            }
+            return { type: "image_url", image_url: {
+                    url: part.image_url,
+                    ...(part.detail ? { detail: part.detail === "original" ? "high" : part.detail } : {}),
+                } };
+        }
+        throw new BridgeError(`Chat does not support content part ${String(part?.type)}.`);
+    });
+}
+function messageContent(parts) {
+    return parts.every((p) => p.type === "text") ? parts.map((p) => p.text).join("\n") : parts;
+}
+function convertHistory(context, tools, reasoningField) {
+    const messages = [];
+    let assistant;
+    let pendingImages = [];
+    const flushAssistant = () => {
+        if (assistant)
+            messages.push(assistant);
+        assistant = undefined;
+    };
+    const flushImages = () => {
+        if (pendingImages.length)
+            messages.push({ role: "user", content: pendingImages });
+        pendingImages = [];
+    };
+    const getAssistant = () => assistant ??= { role: "assistant", content: "", [reasoningField]: "" };
+    if (context.request.instructions)
+        messages.push({ role: "system", content: context.request.instructions });
+    for (const item of prepareHistory(context.request.input, context.route)) {
+        if (item.type === "bridge_reasoning") {
+            flushImages();
+            // A reasoning item starts the next assistant response, even if the
+            // previous response ended without a tool or user message.
+            flushAssistant();
+            if (typeof item.state.data !== "string")
+                throw new BridgeError("Invalid Chat reasoning data.");
+            getAssistant()[reasoningField] = item.state.data;
+        }
+        else if (item.type === "message" || (!item.type && item.role)) {
+            const parts = contentParts(item.content);
+            if (item.role === "assistant") {
+                flushImages();
+                if (parts.some((p) => p.type !== "text"))
+                    throw new BridgeError("Chat assistant history cannot contain images.");
+                const a = getAssistant();
+                const text = messageContent(parts);
+                a.content += (a.content && text ? "\n" : "") + text;
+            }
+            else {
+                flushAssistant();
+                flushImages();
+                if (!["system", "developer", "user"].includes(item.role)) {
+                    throw new BridgeError(`Chat does not support message role ${String(item.role)}.`);
+                }
+                if (item.role !== "user" && parts.some((p) => p.type !== "text")) {
+                    throw new BridgeError("Chat system and developer messages must contain text only.");
+                }
+                messages.push({ role: item.role === "developer" ? "system" : item.role, content: messageContent(parts) });
+            }
+        }
+        else if (item.type === "function_call" || item.type === "custom_tool_call") {
+            flushImages();
+            if (typeof item.call_id !== "string" || typeof item.name !== "string")
+                throw new BridgeError("Invalid Chat tool call history.");
+            const a = getAssistant();
+            a.tool_calls ??= [];
+            a.tool_calls.push({
+                id: item.call_id, type: "function", function: {
+                    name: tools.flatFor(item.namespace, item.name),
+                    arguments: item.type === "custom_tool_call" ? JSON.stringify({ input: item.input }) : item.arguments,
+                },
+            });
+        }
+        else if (item.type === "function_call_output" || item.type === "custom_tool_call_output") {
+            flushAssistant();
+            if (typeof item.call_id !== "string")
+                throw new BridgeError("Chat tool output has no call_id.");
+            const parts = contentParts(item.output);
+            const images = parts.filter((p) => p.type === "image_url");
+            messages.push({ role: "tool", tool_call_id: item.call_id, content: messageContent(parts.filter((p) => p.type === "text")) });
+            if (images.length) {
+                pendingImages.push({ type: "text", text: `Images from tool call ${item.call_id}:` }, ...images);
+            }
+        }
+        else {
+            throw new BridgeError(`Chat does not support history item ${String(item.type)}.`);
+        }
+    }
+    flushAssistant();
+    flushImages();
+    return messages;
+}
+function toolChoice(choice, tools) {
+    if (choice === undefined)
+        return undefined;
+    if (["auto", "none", "required"].includes(choice))
+        return choice;
+    if (choice && typeof choice === "object") {
+        const selected = choice;
+        if (["function", "custom"].includes(selected.type) && typeof selected.name === "string") {
+            const tool = tools.get(selected.namespace, selected.name);
+            if (!tool || tool.kind !== selected.type) {
+                throw new BridgeError("The selected tool is not available on the Chat backend.");
+            }
+            return { type: "function", function: { name: tool.flatName } };
+        }
+    }
+    throw new BridgeError("Chat does not support this tool_choice.");
+}
+export function buildChatRequest(context, dialect) {
+    context = { ...context, request: normalizeToolDeclarations(context.request) };
+    const { request, route } = context;
+    const tools = buildToolSet(request.tools);
+    const body = { ...dialect.requestParameters(context) };
+    const limit = request.max_output_tokens ?? route.profile.max_output_tokens;
+    if (limit !== undefined)
+        body.max_tokens = limit;
+    for (const name of ["temperature", "top_p", "parallel_tool_calls"]) {
+        if (request[name] !== undefined)
+            body[name] = request[name];
+    }
+    const choice = toolChoice(request.tool_choice, tools);
+    if (choice !== undefined)
+        body.tool_choice = choice;
+    const format = request.text?.format;
+    if (format?.type === "json_object")
+        body.response_format = { type: "json_object" };
+    else if (format?.type === "json_schema") {
+        body.response_format = { type: "json_schema", json_schema: { name: format.name, schema: format.schema, strict: format.strict } };
+    }
+    else if (format && format.type !== "text")
+        throw new BridgeError(`Chat does not support text format ${String(format.type)}.`);
+    Object.assign(body, route.upstream.options, route.config.options, {
+        model: route.config.model,
+        messages: convertHistory(context, tools, dialect.reasoningField),
+        stream: true,
+    });
+    body.stream_options = { ...body.stream_options, include_usage: true };
+    if (tools.entries.length)
+        body.tools = tools.entries.map((tool) => ({
+            type: "function", function: { name: tool.flatName, description: tool.description, parameters: tool.parameters },
+        }));
+    else
+        delete body.tools;
+    if (context.compacting) {
+        delete body.response_format;
+    }
+    return { body, tools };
+}
+async function* chatEvents(body, signal) {
+    try {
+        yield* parseJsonSse(body);
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw signal.reason;
+        throw transportError(error);
+    }
+}
+export async function runChat(context, writer, dialect) {
+    const { body, tools } = buildChatRequest(context, dialect);
+    const { reasoningField } = dialect;
+    const response = await upstreamFetch(context.route, "chat/completions", body, context.signal, context.requestHeaders);
+    context.onAccepted?.(response.headers);
+    if (!response.body)
+        throw new BridgeError("Chat upstream returned no stream.", "upstream_error", 502);
+    let reasoning = "";
+    let reasoningSeen = false;
+    let reasoningClosed = false;
+    let finish;
+    let usage;
+    let visible = false;
+    const calls = new Map();
+    const closeReasoning = () => {
+        if (reasoningSeen && !reasoningClosed) {
+            writer.endReasoning(encodeReasoning({ source: context.route.origin, format: context.route.profile.reasoning_format, data: reasoning }));
+            reasoningClosed = true;
+        }
+    };
+    for await (const { json } of chatEvents(response.body, context.signal)) {
+        if (json.error)
+            throw upstreamError(undefined, json, response.headers);
+        if (json.usage)
+            usage = dialect.readUsage(json.usage);
+        for (const choice of json.choices ?? []) {
+            if (choice.index !== 0)
+                throw new BridgeError("Chat returned more than one completion.", "upstream_error", 502);
+            if (choice.finish_reason)
+                finish = choice.finish_reason;
+            const delta = choice.delta ?? {};
+            if (delta.refusal)
+                throw new BridgeError(String(delta.refusal));
+            if (delta[reasoningField] !== undefined && delta[reasoningField] !== null) {
+                if (typeof delta[reasoningField] !== "string" || reasoningClosed)
+                    throw new BridgeError("Chat returned unsupported reasoning ordering or content.", "upstream_error", 502);
+                reasoningSeen = true;
+                reasoning += delta[reasoningField];
+                writer.reasoningDelta(delta[reasoningField]);
+            }
+            if (delta.content !== undefined && delta.content !== null && delta.content !== "") {
+                if (typeof delta.content !== "string")
+                    throw new BridgeError("Chat returned non-text output.", "upstream_error", 502);
+                closeReasoning();
+                writer.textDelta(delta.content);
+                visible = true;
+            }
+            for (const part of delta.tool_calls ?? []) {
+                if (!Number.isInteger(part.index) || part.index < 0 || (part.type && part.type !== "function")) {
+                    throw new BridgeError("Chat returned an invalid tool call.", "upstream_error", 502);
+                }
+                const call = calls.get(part.index) ?? { id: "", name: "", arguments: "" };
+                if (part.id)
+                    call.id += part.id;
+                if (part.function?.name)
+                    call.name += part.function.name;
+                if (part.function?.arguments)
+                    call.arguments += part.function.arguments;
+                calls.set(part.index, call);
+            }
+        }
+    }
+    if (!finish)
+        throw new BridgeError("Chat stream ended before a finish_reason.", "upstream_error", 502);
+    if (finish === "length")
+        throw new BridgeError("Chat output reached its token limit; increase max_output_tokens.");
+    const failure = dialect.failureReason(finish);
+    if (failure)
+        throw failure;
+    if (finish !== "stop" && finish !== "tool_calls")
+        throw new BridgeError(`Chat stopped with ${finish}.`);
+    if (!usage)
+        throw new BridgeError("Chat stream ended without token usage.", "upstream_error", 502);
+    if (finish === "tool_calls" && !calls.size)
+        throw new BridgeError("Chat ended with tool_calls but returned no calls.", "upstream_error", 502);
+    if (!visible && !calls.size)
+        throw new BridgeError("Chat returned no text or tool calls.", "upstream_error", 502);
+    closeReasoning();
+    // Validate every call before exposing any of them for execution.
+    const completed = [...calls.entries()].sort(([a], [b]) => a - b).map(([, call]) => {
+        const tool = tools.resolve(call.name);
+        if (!tool || !call.id)
+            throw new BridgeError("Chat returned an unknown or incomplete tool call.", "upstream_error", 502);
+        let args;
+        try {
+            args = JSON.parse(call.arguments);
+        }
+        catch {
+            throw new BridgeError("Chat returned invalid tool arguments.", "upstream_error", 502);
+        }
+        if (!args || typeof args !== "object" || Array.isArray(args))
+            throw new BridgeError("Chat tool arguments must be an object.", "upstream_error", 502);
+        if (tool.kind === "custom" && typeof args.input !== "string")
+            throw new BridgeError("Chat custom tool call has no string input.", "upstream_error", 502);
+        return { call, tool, args };
+    });
+    for (const { call, tool, args } of completed) {
+        if (tool.kind === "custom")
+            writer.addCustomToolCall({ call_id: call.id, name: tool.name, namespace: tool.namespace, input: args.input });
+        else
+            writer.addFunctionCall({ call_id: call.id, name: tool.name, namespace: tool.namespace, arguments: call.arguments });
+    }
+    return { usage, endTurn: calls.size === 0 };
+}

package/dist/backends/deepseek.d.ts

@@ -0,0 +1,6 @@
+import type { Backend, BackendContext } from "../types.ts";
+export declare function buildDeepSeekRequest(context: BackendContext): {
+    body: Record<string, any>;
+    tools: import("../tools.ts").ToolSet;
+};
+export declare const runDeepSeek: Backend;

package/dist/backends/deepseek.js

@@ -0,0 +1,37 @@
+import { BridgeError } from "../errors.js";
+import { reasoningEffort } from "../profiles.js";
+import { buildChatRequest, runChat } from "./chat.js";
+const deepseek = {
+    reasoningField: "reasoning_content",
+    requestParameters({ request, route }) {
+        const effort = reasoningEffort(route, request.reasoning?.effort);
+        return effort === "none"
+            ? { thinking: { type: "disabled" } }
+            : { thinking: { type: "enabled" }, reasoning_effort: effort };
+    },
+    failureReason(reason) {
+        if (reason === "insufficient_system_resource" || reason === "aborted") {
+            return new BridgeError(`DeepSeek generation stopped with ${reason}.`, "server_is_overloaded", 503);
+        }
+    },
+    readUsage(value) {
+        const count = (value) => {
+            if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+                throw new BridgeError("Chat stream has no valid token usage.", "upstream_error", 502);
+            }
+            return value;
+        };
+        const cached = value?.prompt_cache_hit_tokens ?? value?.prompt_tokens_details?.cached_tokens;
+        const reasoning = value?.completion_tokens_details?.reasoning_tokens;
+        return {
+            input_tokens: count(value?.prompt_tokens),
+            output_tokens: count(value?.completion_tokens),
+            ...(cached !== undefined ? { cached_tokens: count(cached) } : {}),
+            ...(reasoning !== undefined ? { reasoning_tokens: count(reasoning) } : {}),
+        };
+    },
+};
+export function buildDeepSeekRequest(context) {
+    return buildChatRequest(context, deepseek);
+}
+export const runDeepSeek = (context, writer) => runChat(context, writer, deepseek);

package/dist/backends/responses.d.ts

@@ -0,0 +1,5 @@
+import type { Backend, BackendContext } from "../types.ts";
+/** Replay complete content, never a server-side item reference. */
+export declare function responsesBody({ request, route, compacting }: BackendContext): Record<string, any>;
+/** Transform only bridge-owned fields; native events keep their original shape. */
+export declare const runResponses: Backend;

package/dist/backends/responses.js

@@ -0,0 +1,227 @@
+import { encodeReasoning } from "../carrier.js";
+import { BridgeError, ResponsesIncompleteError, responsesStreamError } from "../errors.js";
+import { prepareHistory } from "../history.js";
+import { reasoningEffort } from "../profiles.js";
+import { parseJsonSse } from "../sse.js";
+import { upstreamFetch } from "../upstream.js";
+/** Replay complete content, never a server-side item reference. */
+export function responsesBody({ request, route, compacting }) {
+    if (request.previous_response_id) {
+        throw new BridgeError("previous_response_id is unsupported; send the complete conversation items");
+    }
+    const input = prepareHistory(request.input, route).map((item) => {
+        // An assistant message id can reference a reasoning item that was filtered
+        // during a model switch or an agent fork. Full content needs neither id.
+        delete item.id;
+        if (item.type === "bridge_reasoning") {
+            if (typeof item.state.data !== "string")
+                throw new BridgeError("Invalid Responses reasoning data.");
+            return { type: "reasoning", summary: item.summary, encrypted_content: item.state.data };
+        }
+        return item;
+    });
+    const body = {
+        ...(route.profile.max_output_tokens ? { max_output_tokens: route.profile.max_output_tokens } : {}),
+        ...request,
+        reasoning: { ...request.reasoning, effort: reasoningEffort(route, request.reasoning?.effort) },
+        ...route.upstream.options,
+        ...route.config.options,
+        model: route.config.model,
+        input,
+        tools: request.tools,
+        store: false,
+        stream: true,
+    };
+    body.include = [...new Set([...(Array.isArray(body.include) ? body.include : []), "reasoning.encrypted_content"])];
+    delete body.previous_response_id;
+    if (input.some((item) => item.type === "compaction_trigger")) {
+        // Native compaction has its own output budget requirements. An ordinary
+        // response limit can be smaller than its provider-enforced minimum.
+        delete body.max_output_tokens;
+    }
+    else if (compacting) {
+        delete body.text;
+    }
+    return body;
+}
+function usageFrom(value) {
+    const count = (value, field) => {
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+            throw new BridgeError(`Missing or invalid Responses usage field: ${field}`, "upstream_error", 502);
+        }
+        return value;
+    };
+    // These fields are required by codeks when their enclosing objects exist.
+    count(value?.total_tokens, "total_tokens");
+    const cached = value?.input_tokens_details == null ? undefined
+        : count(value.input_tokens_details.cached_tokens, "input_tokens_details.cached_tokens");
+    const reasoning = value?.output_tokens_details == null ? undefined
+        : count(value.output_tokens_details.reasoning_tokens, "output_tokens_details.reasoning_tokens");
+    const cacheWrite = value?.input_tokens_details?.cache_write_tokens;
+    if (value?.codex_rollout_budget_units != null && !Number.isFinite(value.codex_rollout_budget_units)) {
+        throw new BridgeError("Invalid Responses usage field: codex_rollout_budget_units", "upstream_error", 502);
+    }
+    return {
+        input_tokens: count(value?.input_tokens, "input_tokens"),
+        output_tokens: count(value?.output_tokens, "output_tokens"),
+        ...(cached !== undefined ? { cached_tokens: cached } : {}),
+        ...(cacheWrite !== undefined ? { cache_write_tokens: count(cacheWrite, "input_tokens_details.cache_write_tokens") } : {}),
+        ...(reasoning !== undefined ? { reasoning_tokens: reasoning } : {}),
+    };
+}
+/** Validate the client terminal contract before any buffered tools can run. */
+function completedUsage(response) {
+    const invalid = (field) => {
+        throw new BridgeError(`Missing or invalid Responses completed field: ${field}`, "upstream_error", 502);
+    };
+    if (typeof response.id !== "string")
+        invalid("id");
+    if (response.end_turn != null && typeof response.end_turn !== "boolean")
+        invalid("end_turn");
+    const metadata = response.usage_metadata;
+    if (metadata != null) {
+        if (typeof metadata !== "object" || Array.isArray(metadata))
+            invalid("usage_metadata");
+        if (metadata.amount != null && typeof metadata.amount !== "string")
+            invalid("usage_metadata.amount");
+    }
+    return usageFrom(response.usage);
+}
+/** Transform only bridge-owned fields; native events keep their original shape. */
+export const runResponses = async (context, writer) => {
+    writer.useNativeResponses();
+    const response = await upstreamFetch(context.route, "/responses", responsesBody(context), context.signal, context.requestHeaders, context.responsesLite ? { "x-openai-internal-codex-responses-lite": "true" } : undefined);
+    context.onAccepted?.(response.headers);
+    const states = new Map();
+    const phases = new Map();
+    let pendingPhase;
+    let held = [];
+    function itemFor(item, index) {
+        const result = { ...item };
+        if (item.type === "reasoning" && typeof item.encrypted_content === "string" && item.encrypted_content) {
+            result.encrypted_content = encodeReasoning({
+                source: context.route.origin, format: context.route.profile.reasoning_format, data: item.encrypted_content,
+            });
+        }
+        if (item.type === "function_call") {
+            if (item.encrypted_function_args?.length) {
+                throw new BridgeError("Encrypted tool arguments are unsupported; use plaintext client tools");
+            }
+            result.encrypted_function_args ??= [];
+        }
+        if (item.type === "message" && item.phase === undefined) {
+            const phase = phases.get(index) ?? states.get(index)?.item.phase;
+            if (phase !== undefined)
+                result.phase = phase;
+        }
+        return result;
+    }
+    function responseFor(value) {
+        return {
+            ...value, model: context.request.model,
+            ...(Array.isArray(value.output) ? { output: value.output.map(itemFor) } : {}),
+        };
+    }
+    function releasePhase(phase) {
+        if (pendingPhase && phase !== undefined) {
+            pendingPhase.item.phase = phase;
+            phases.set(pendingPhase.index, phase);
+        }
+        pendingPhase = undefined;
+        const events = held;
+        held = [];
+        for (const event of events)
+            writer.nativeEvent(event);
+    }
+    function emit(event) {
+        if (event.type === "response.output_item.added" || event.type === "response.output_item.done") {
+            const index = event.output_index ?? 0;
+            if (pendingPhase && index !== pendingPhase.index && event.item.type !== "reasoning")
+                releasePhase("commentary");
+            if (event.type === "response.output_item.done" && event.item.type === "message" && event.item.phase === undefined) {
+                pendingPhase = { index, item: event.item };
+            }
+        }
+        if (pendingPhase)
+            held.push(event);
+        else
+            writer.nativeEvent(event);
+    }
+    function outputEvent(event) {
+        const index = event.output_index ?? 0;
+        const item = itemFor(event.item, index);
+        const state = states.get(index) ?? { item, added: false, done: false };
+        if (event.type === "response.output_item.done" && !state.added) {
+            emit({ type: "response.output_item.added", output_index: index, item });
+            state.added = true;
+        }
+        state.item = item;
+        state.added ||= event.type === "response.output_item.added";
+        state.done ||= event.type === "response.output_item.done";
+        states.set(index, state);
+        emit({ ...event, item });
+    }
+    function reconcileOutput(result) {
+        // codeks persists item events, not the terminal response.output. This also
+        // applies to partial history returned only by an incomplete terminal event.
+        for (const [index, item] of (result.output ?? []).entries()) {
+            if (!states.get(index)?.done)
+                outputEvent({ type: "response.output_item.done", output_index: index, item });
+        }
+    }
+    function terminal(event) {
+        const result = event.response;
+        if (event.type === "response.failed" || result?.status === "failed" || result?.error) {
+            releasePhase();
+            throw responsesStreamError(responseFor(result), response.headers, event);
+        }
+        if (event.type === "response.incomplete" || result?.status === "incomplete") {
+            reconcileOutput(result);
+            releasePhase();
+            throw new ResponsesIncompleteError(responseFor(result), event);
+        }
+        if (result?.status !== "completed") {
+            throw new BridgeError("The upstream did not return a completed response", "stream_error", 502);
+        }
+        const usage = completedUsage(result);
+        reconcileOutput(result);
+        for (const state of states.values()) {
+            if (!state.done)
+                throw new BridgeError("The upstream completed with an unfinished output item", "stream_error", 502);
+        }
+        const hasCalls = [...states.values()].some(({ item }) => ["function_call", "custom_tool_call"].includes(item.type));
+        const endTurn = result.end_turn ?? !hasCalls;
+        if (pendingPhase) {
+            releasePhase(result.output?.[pendingPhase.index]?.phase ?? (endTurn ? "final_answer" : "commentary"));
+        }
+        writer.nativeEvent({ ...event, response: { ...responseFor(result), end_turn: endTurn } });
+        return { usage, endTurn };
+    }
+    if (response.headers.get("content-type")?.includes("application/json")) {
+        const result = await response.json();
+        if (result.status === "completed" || result.status === "incomplete") {
+            writer.nativeEvent({ type: "response.created", response: { ...result, model: context.request.model, status: "in_progress", output: [] } });
+        }
+        return terminal({ type: result.status === "incomplete" ? "response.incomplete" : "response.completed", response: result });
+    }
+    if (!response.body)
+        throw new BridgeError("The upstream returned an empty response", "stream_error", 502);
+    for await (const { json: event } of parseJsonSse(response.body)) {
+        switch (event.type) {
+            case "response.output_item.added":
+            case "response.output_item.done":
+                outputEvent(event);
+                break;
+            case "response.completed":
+            case "response.failed":
+            case "response.incomplete":
+                return terminal(event);
+            case "error":
+                releasePhase();
+                throw responsesStreamError(event.error ?? event, response.headers, event);
+            default:
+                emit(event.response ? { ...event, response: responseFor(event.response) } : event);
+        }
+    }
+    throw new BridgeError("The upstream stream ended before response.completed", "stream_error", 502);
+};

package/dist/carrier.d.ts

@@ -0,0 +1,22 @@
+import type { ResponsesRequest, StateOrigin } from "./types.ts";
+export interface HandoffRecipe {
+    prefix: Record<string, any>[];
+    parameters: ResponsesRequest;
+    responsesLite: boolean;
+}
+export interface StatePayload {
+    source: StateOrigin;
+    format: string;
+    data: unknown;
+}
+export interface CompactionCarrier {
+    /** The prompt-based summary. Any model can read it. */
+    summary?: string;
+    native?: StatePayload;
+    /** Source request information needed to materialize a deferred summary. */
+    handoff?: HandoffRecipe;
+}
+export declare function encodeReasoning(state: StatePayload): string;
+export declare function decodeReasoning(value: unknown): StatePayload | undefined;
+export declare function encodeCompaction(carrier: CompactionCarrier): string;
+export declare function decodeCompaction(value: unknown): CompactionCarrier | undefined;

package/dist/carrier.js

@@ -0,0 +1,61 @@
+import { BridgeError } from "./errors.js";
+// Versioned, self-contained state stored in the client's encrypted_content field.
+// These envelopes encode source facts and payloads, never replay policy.
+const REASONING_PREFIX = "cxbr1:";
+const COMPACTION_PREFIX = "cxbc1:";
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function statePayload(value) {
+    return object(value) && object(value.source) &&
+        [value.source.id, value.source.connection, value.source.model, value.source.adapter, value.format]
+            .every((field) => typeof field === "string" && field.length > 0) &&
+        Object.hasOwn(value, "data") && value.data !== undefined;
+}
+function compactionCarrier(value) {
+    if (!object(value) || (value.native !== undefined && !statePayload(value.native)))
+        return false;
+    if (value.summary !== undefined && (typeof value.summary !== "string" || !value.summary.trim()))
+        return false;
+    if (value.handoff !== undefined && (!object(value.handoff) ||
+        !Array.isArray(value.handoff.prefix) || !value.handoff.prefix.every(object) ||
+        !object(value.handoff.parameters) || typeof value.handoff.parameters.model !== "string" ||
+        typeof value.handoff.responsesLite !== "boolean"))
+        return false;
+    return value.summary !== undefined || (value.native !== undefined && value.handoff !== undefined);
+}
+function encode(prefix, value) {
+    return prefix + Buffer.from(JSON.stringify(value), "utf8").toString("base64url");
+}
+function decode(value, prefix) {
+    if (typeof value !== "string" || !value.startsWith(prefix))
+        return undefined;
+    try {
+        return JSON.parse(Buffer.from(value.slice(prefix.length), "base64url").toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function encodeReasoning(state) {
+    if (!statePayload(state))
+        throw new TypeError("Invalid reasoning state envelope");
+    return encode(REASONING_PREFIX, state);
+}
+export function decodeReasoning(value) {
+    if (typeof value !== "string" || !value.startsWith(REASONING_PREFIX))
+        return undefined;
+    const decoded = decode(value, REASONING_PREFIX);
+    if (!statePayload(decoded))
+        throw new BridgeError("Malformed bridge reasoning state envelope");
+    return decoded;
+}
+export function encodeCompaction(carrier) {
+    if (!compactionCarrier(carrier))
+        throw new TypeError("Invalid compaction state envelope");
+    return encode(COMPACTION_PREFIX, carrier);
+}
+export function decodeCompaction(value) {
+    const decoded = decode(value, COMPACTION_PREFIX);
+    return compactionCarrier(decoded) ? decoded : undefined;
+}

package/dist/catalog.d.ts

@@ -0,0 +1,8 @@
+import type { BridgeConfig } from "./types.ts";
+/** Codex bounds downloads from an explicit model_catalog_url to 1 MiB. */
+export declare const MAX_HTTP_CATALOG_BYTES: number;
+/** Serve client-exposed aliases, using their own reviewed client behavior. */
+export declare function buildCatalog(config: BridgeConfig): {
+    models: Record<string, any>[];
+};
+export declare function configSnippet(config: BridgeConfig, catalogPath?: string): string;