@wacry/codeks-bridge 0.0.0-stage → 0.0.1

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,205 @@
+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;
+    };
+    const cached = value?.input_tokens_details?.cached_tokens;
+    const reasoning = value?.output_tokens_details?.reasoning_tokens;
+    const cacheWrite = value?.input_tokens_details?.cache_write_tokens;
+    return {
+        input_tokens: count(value?.input_tokens, "input_tokens"),
+        output_tokens: count(value?.output_tokens, "output_tokens"),
+        ...(cached !== undefined ? { cached_tokens: count(cached, "input_tokens_details.cached_tokens") } : {}),
+        ...(cacheWrite !== undefined ? { cache_write_tokens: count(cacheWrite, "input_tokens_details.cache_write_tokens") } : {}),
+        ...(reasoning !== undefined ? { reasoning_tokens: count(reasoning, "output_tokens_details.reasoning_tokens") } : {}),
+    };
+}
+/** 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 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") {
+            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 = usageFrom(result.usage);
+        // A whole JSON response, or a terminal-only stream, still needs item events
+        // because codeks persists the history from output_item.done.
+        for (const [index, item] of (result.output ?? []).entries()) {
+            if (!states.get(index)?.done)
+                outputEvent({ type: "response.output_item.done", output_index: index, item });
+        }
+        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: [] } });
+        }
+        if (result.status === "incomplete") {
+            // An interrupted whole response has no earlier item events. Publish its
+            // partial history before the terminal event, still withholding any tool suffix.
+            for (const [index, item] of (result.output ?? []).entries()) {
+                outputEvent({ type: "response.output_item.done", output_index: index, item });
+            }
+        }
+        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;

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 {};