@wacry/codeks-bridge 0.0.6 → 0.0.7

package/README.md

@@ -6,7 +6,7 @@
 
 ## 安装和使用
 
-需要 Node.js ≥ 22.18 和已安装的 codeks。
+需要 Node.js ≥ 20.19 和已安装的 codeks。
 
 ```sh
 npm install -g @wacry/codeks-bridge
@@ -38,4 +38,4 @@ codeks-bridge config-snippet --config /absolute/path/bridge.json
 
 `serve` 加 `--capture` 后打开日志里的 `/inspect/` 地址，可以逐条查看 codeks 请求、发往上游的请求、上游原始响应和写回 codeks 的响应，以及 reasoning 与压缩状态的回放决定。记录只在内存中，也可以在页面上开关捕获、清空或导出。详见[调试检查器](docs/inspect.md)。
 
-[配置与模型目录](docs/config.md) · [整体设计](docs/design.md) · [Reasoning](docs/reasoning.md) · [压缩](docs/compaction.md) · [工具](docs/tools.md) · [调试检查器](docs/inspect.md) · [验证](docs/testing.md) · [发布](docs/releasing.md)
+[配置与模型目录](docs/config.md) · [嵌入现有服务](docs/embedding.md) · [整体设计](docs/design.md) · [Reasoning](docs/reasoning.md) · [压缩](docs/compaction.md) · [工具](docs/tools.md) · [调试检查器](docs/inspect.md) · [验证](docs/testing.md) · [发布](docs/releasing.md)

package/dist/backends/anthropic.js

@@ -253,7 +253,7 @@ function validateUsage(value, required) {
 }
 export const runAnthropic = async (context, writer) => {
     const { body, tools, betas, continuationBefore } = buildAnthropicRequest(context);
-    const response = await upstreamFetch(context.route, "/messages", body, context.signal, context.requestHeaders, { "anthropic-beta": betas });
+    const response = await upstreamFetch(context.route, "/messages", body, context.signal, context.requestHeaders, { "anthropic-beta": betas }, context.fetch);
     context.onAccepted?.(response.headers);
     if (!response.body)
         throw new BridgeError("Messages returned an empty stream.", "upstream_error", 502);

package/dist/backends/chat.js

@@ -195,7 +195,7 @@ async function* chatEvents(body, signal) {
 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);
+    const response = await upstreamFetch(context.route, "chat/completions", body, context.signal, context.requestHeaders, undefined, context.fetch);
     context.onAccepted?.(response.headers);
     if (!response.body)
         throw new BridgeError("Chat upstream returned no stream.", "upstream_error", 502);

package/dist/backends/responses.js

@@ -92,7 +92,7 @@ function completedUsage(response) {
 /** 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);
+    const response = await upstreamFetch(context.route, "/responses", responsesBody(context), context.signal, context.requestHeaders, context.responsesLite ? { "x-openai-internal-codex-responses-lite": "true" } : undefined, context.fetch);
     context.onAccepted?.(response.headers);
     const states = new Map();
     const phases = new Map();

package/dist/compaction-handoff.js

@@ -78,6 +78,7 @@ export class CompactionHandoffStore {
             const result = await collectHandoff({
                 request: { ...request, model: route.slug }, route, signal,
                 requestHeaders: context.requestHeaders,
+                fetch: context.fetch,
                 responsesLite: carrier.handoff.responsesLite,
             }, this.backends[route.profile.id]);
             signal.throwIfAborted();

package/dist/config.js

@@ -60,8 +60,10 @@ export function validateConfig(value) {
             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))
+        if (up.stream_idle_timeout_ms !== undefined && up.stream_idle_timeout_ms !== null && (!Number.isSafeInteger(up.stream_idle_timeout_ms) || up.stream_idle_timeout_ms <= 0))
             fail(`upstream ${name}: invalid stream_idle_timeout_ms`);
+        if (up.headers_timeout_ms !== undefined && up.headers_timeout_ms !== null && (!Number.isSafeInteger(up.headers_timeout_ms) || up.headers_timeout_ms <= 0))
+            fail(`upstream ${name}: invalid headers_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))))

package/dist/index.d.ts

@@ -2,4 +2,4 @@ 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";
+export type { BridgeConfig, UpstreamConfig, ModelConfig, BridgeServerOptions, ResponsesRequest } from "./types.ts";

package/dist/server.d.ts

@@ -1,4 +1,4 @@
 import { type Server } from "node:http";
-import type { BridgeConfig } from "./types.ts";
+import type { BridgeConfig, BridgeServerOptions } from "./types.ts";
 /** Creates a server without opening a socket, so callers control its lifecycle. */
-export declare function createBridgeServer(value: BridgeConfig): Server;
+export declare function createBridgeServer(value: BridgeConfig, options?: BridgeServerOptions): Server;

package/dist/server.js

@@ -71,7 +71,7 @@ function authenticated(req, token) {
     return actual.length === expected.length && timingSafeEqual(actual, expected);
 }
 /** Creates a server without opening a socket, so callers control its lifecycle. */
-export function createBridgeServer(value) {
+export function createBridgeServer(value, options = {}) {
     const config = validateConfig(value);
     const compactions = new CompactionHandoffStore(config, BACKENDS);
     const catalog = JSON.stringify(buildCatalog(config));
@@ -124,7 +124,9 @@ export function createBridgeServer(value) {
             }
             res.setHeader("x-models-etag", catalogEtag);
             const exchange = inspector.begin(req, res);
-            const request = await readRequest(req, config.request_max_mib ?? 512, exchange);
+            const original = await readRequest(req, config.request_max_mib ?? 512, exchange);
+            const requestHeaders = incomingHeaders(req.headers);
+            const request = await options.transformRequest?.(original, { headers: requestHeaders }) ?? original;
             const caller = resolveModel(config, request.model);
             const compacting = isCompactionRequest(request);
             // Restore history for the actual consumer before materializing any handoffs.
@@ -139,7 +141,10 @@ export function createBridgeServer(value) {
             exchange?.routed(route, responsesLite);
             const backend = BACKENDS[route.profile.id];
             const streaming = request.stream === true;
-            writer = new ResponseWriter(streaming ? res : { write() { } }, { model: request.model, showSummary: reasoningSummaryRequested(request) });
+            writer = new ResponseWriter(streaming ? res : { write() { } }, {
+                model: request.model, showSummary: reasoningSummaryRequested(request),
+                onEvent: options.onResponseEvent ? event => options.onResponseEvent(request, event) : undefined,
+            });
             if (streaming)
                 startStream = () => {
                     if (res.headersSent || controller.signal.aborted)
@@ -155,7 +160,7 @@ export function createBridgeServer(value) {
                 };
             else
                 writer.start();
-            const context = { request: executionRequest, route, signal: controller.signal, requestHeaders: incomingHeaders(req.headers), responsesLite, onAccepted: (headers) => {
+            const context = { request: executionRequest, route, signal: controller.signal, requestHeaders, fetch: options.fetch, responsesLite, onAccepted: (headers) => {
                     for (const [name, value] of Object.entries(headers ? forwardResponseHeaders(headers) : {}))
                         res.setHeader(name, value);
                     startStream?.();
@@ -227,7 +232,13 @@ export function createBridgeServer(value) {
         finally {
             if (keepalive)
                 clearInterval(keepalive);
+            // A hook can fail after acceptance but before the backend reads the body.
+            controller.abort();
             res.off("close", abort);
         }
+    }).catch(() => {
+        // Failure delivery can itself throw, including from a terminal observer.
+        // Close only this response; never leave the async request unhandled.
+        res.destroy();
     }));
 }

package/dist/types.d.ts

@@ -16,7 +16,9 @@ export interface UpstreamConfig {
     /** An argv array. The command writes a short-lived credential to stdout. */
     api_key_command?: string[];
     auth_header?: string;
-    stream_idle_timeout_ms?: number;
+    /** Defaults to stream_idle_timeout_ms; null disables the wait-for-headers timer. */
+    headers_timeout_ms?: number | null;
+    stream_idle_timeout_ms?: number | null;
     headers?: Record<string, string>;
     options?: Record<string, unknown>;
     adapters?: AdapterConfig;
@@ -110,12 +112,23 @@ export interface ResponsesRequest {
     stream?: boolean;
     [key: string]: any;
 }
+export interface BridgeServerOptions {
+    /** Used by every upstream call, including compaction and handoffs. */
+    fetch?: typeof globalThis.fetch;
+    /** Runs once before routing. Return a replacement or change the request in place. */
+    transformRequest?: (request: ResponsesRequest, context: {
+        headers: Headers;
+    }) => ResponsesRequest | void | Promise<ResponsesRequest | void>;
+    /** Observes committed client response events, including non-streaming responses. */
+    onResponseEvent?: (request: ResponsesRequest, event: Record<string, any>) => void;
+}
 export interface BackendContext {
     request: ResponsesRequest;
     route: ResolvedModel;
     signal: AbortSignal;
     /** Client metadata; transport framing and credentials are replaced upstream. */
     requestHeaders?: Headers;
+    fetch?: typeof globalThis.fetch;
     compacting?: boolean;
     /** Transport mode received from the client, including tool-free Lite requests. */
     responsesLite?: boolean;

package/dist/upstream.d.ts

@@ -1,3 +1,3 @@
 import type { ResolvedModel } from "./types.ts";
 /** base_url includes any API version prefix; path is appended, never resolved from /. */
-export declare function upstreamFetch(route: ResolvedModel, path: string, body: unknown, signal: AbortSignal, requestHeaders?: Headers, protocolHeaders?: Record<string, string | string[]>): Promise<Response>;
+export declare function upstreamFetch(route: ResolvedModel, path: string, body: unknown, signal: AbortSignal, requestHeaders?: Headers, protocolHeaders?: Record<string, string | string[]>, fetch?: typeof globalThis.fetch): Promise<Response>;

package/dist/upstream.js

@@ -2,7 +2,7 @@ import { upstreamHeaders } from "./auth.js";
 import { BridgeError, transportError, upstreamError, UpstreamHttpError } from "./errors.js";
 import { captureUpstream } from "./inspect/capture.js";
 /** base_url includes any API version prefix; path is appended, never resolved from /. */
-export async function upstreamFetch(route, path, body, signal, requestHeaders, protocolHeaders) {
+export async function upstreamFetch(route, path, body, signal, requestHeaders, protocolHeaders, fetch = globalThis.fetch) {
     const url = route.upstream.base_url.replace(/\/+$/, "") + "/" + path.replace(/^\/+/, "");
     const headers = await upstreamHeaders(route.upstream, route.profile.api, signal, requestHeaders);
     for (const [name, value] of Object.entries(protocolHeaders ?? {})) {
@@ -16,13 +16,18 @@ export async function upstreamFetch(route, path, body, signal, requestHeaders, p
     const call = captureUpstream(url, headers, payload);
     const idle = new AbortController();
     const combined = AbortSignal.any([signal, idle.signal]);
-    const timeoutMs = route.upstream.stream_idle_timeout_ms ?? 300_000;
+    const timeoutMs = route.upstream.stream_idle_timeout_ms === undefined ? 300_000 : route.upstream.stream_idle_timeout_ms;
     let timer;
-    const reset = () => {
+    const reset = (duration = timeoutMs) => {
         clearTimeout(timer);
-        timer = setTimeout(() => idle.abort(new BridgeError("Upstream stream timed out", "stream_error", 504)), timeoutMs).unref();
+        timer = undefined;
+        if (duration === null)
+            return;
+        timer = setTimeout(() => idle.abort(new BridgeError("Upstream stream timed out", "stream_error", 504)), duration).unref();
     };
-    reset();
+    const headersTimeout = route.upstream.headers_timeout_ms === undefined ? timeoutMs : route.upstream.headers_timeout_ms;
+    if (headersTimeout !== null)
+        reset(headersTimeout);
     let response;
     try {
         response = await fetch(url, { method: "POST", headers, body: payload, signal: combined, redirect: "error" });
@@ -34,8 +39,9 @@ export async function upstreamFetch(route, path, body, signal, requestHeaders, p
             throw combined.reason;
         throw transportError(error);
     }
-    // Downstream keepalives do not count as upstream progress. Time out both the
-    // wait for headers and an idle response body, including a stalled error body.
+    // Downstream keepalives do not count as upstream progress. The body timer
+    // starts after headers, including when the header wait has no deadline.
+    reset();
     call?.received(response);
     if (response.body) {
         const reader = response.body.getReader();

package/dist/writer.d.ts

@@ -40,10 +40,12 @@ export declare class ResponseWriter {
     private nativeEnd;
     private started;
     private finished;
+    private onEvent?;
     constructor(sink: Sink, opts: {
         model: string;
         showSummary?: boolean;
         responseId?: string;
+        onEvent?: (event: Record<string, any>) => void;
     });
     get responseId(): string;
     get nativeResponse(): Record<string, any> | undefined;

package/dist/writer.js

@@ -45,11 +45,13 @@ export class ResponseWriter {
     nativeEnd;
     started = false;
     finished = false;
+    onEvent;
     constructor(sink, opts) {
         this.sink = sink;
         this.model = opts.model;
         this.showSummary = opts.showSummary ?? true;
         this.id = opts.responseId ?? newId("resp");
+        this.onEvent = opts.onEvent;
     }
     get responseId() { return this.id; }
     get nativeResponse() { return this.nativeEnd?.response; }
@@ -63,7 +65,16 @@ export class ResponseWriter {
         return this.nextOutputIndex > 0 || this.calls > 0 || this.message !== undefined;
     }
     write(event, native = false) {
-        this.sink.write(formatSse(native ? event : { sequence_number: this.seq++, ...event }));
+        const emitted = native ? event : { sequence_number: this.seq++, ...event };
+        this.sink.write(formatSse(emitted));
+        try {
+            this.onEvent?.(emitted);
+        }
+        catch (error) {
+            // The request's failure event must not re-enter a failed observer.
+            this.onEvent = undefined;
+            throw error;
+        }
     }
     send(event, native = false) {
         if (this.suffix)
@@ -117,8 +128,8 @@ export class ResponseWriter {
     keepalive() {
         if (!this.started || this.finished)
             return;
-        // Heartbeats bypass an ordered suffix while the upstream is still working.
-        this.write({ type: "keepalive" }, this.native);
+        // Transport heartbeats bypass both the ordered suffix and the observer.
+        this.sink.write(formatSse({ ...(!this.native ? { sequence_number: this.seq++ } : {}), type: "keepalive" }));
     }
     /** Native Responses events retain their own ids, envelopes and metadata. */
     useNativeResponses() { this.native = true; }

package/docs/config.md

@@ -64,7 +64,8 @@
 | `api_key_env` | API key 环境变量名称 |
 | `api_key_command` | 与 `api_key_env` 二选一；argv 数组，程序 stdout 返回当前凭据 |
 | `auth_header` | 覆盖鉴权 header 名；默认 GPT/DeepSeek 用 `authorization: Bearer …`，Claude 用 `x-api-key` |
-| `stream_idle_timeout_ms` | 等待上游 headers 或后续字节的最长空闲时间，默认 300000 ms |
+| `headers_timeout_ms` | 等待上游响应头的最长时间；省略时沿用 `stream_idle_timeout_ms`，`null` 表示禁用 |
+| `stream_idle_timeout_ms` | 收到上游响应头后，等待下一批字节的最长空闲时间，默认 300000 ms；`null` 表示禁用 |
 | `headers` | 静态 header，覆盖同名客户端 header，例如 API 版本 |
 | `options` | 原生请求参数，覆盖 adapter 推导出的参数 |
 | `adapters` | 按 adapter ID 分组的桥接行为；供使用该连接的模型继承 |

package/docs/embedding.md

@@ -0,0 +1,37 @@
+# 嵌入现有服务
+
+npm 包可直接创建标准 Node HTTP server。运行已编译的包需要 Node.js ≥ 20.19；直接运行仓库里的 TypeScript 开发脚本需要 ≥ 22.18。
+
+```ts
+import { createBridgeServer, loadConfig } from "@wacry/codeks-bridge";
+
+const config = await loadConfig("/absolute/path/bridge.json");
+const server = createBridgeServer(config, {
+  async transformRequest(request, { headers }) {
+    const model = headers.get("x-example-model");
+    if (model) request.model = model;
+  },
+  fetch: (input, init) => fetch(input, init),
+  onResponseEvent(request, event) {
+    if (event.type === "response.output_item.done") {
+      console.log(request.model, event.item.type);
+    }
+  },
+});
+
+server.listen(8123, "127.0.0.1");
+```
+
+第二个参数 `BridgeServerOptions` 可省略，不影响 CLI 和默认传输。各选项只作用于当前 server，不替换全局 fetch。
+
+| 选项 | 调用边界 |
+| --- | --- |
+| `transformRequest(request, { headers })` | 入口鉴权与 JSON 解析之后、模型路由和历史转换之前，主请求调用一次。可原位修改并返回 `void`，也可返回替换请求，支持 Promise。`headers` 是该请求的 HTTP headers。辅助压缩和按需复述不会再次调用它。 |
+| `fetch` | 与标准 `fetch` 签名相同，承接全部模型请求，包括压缩、委托压缩及按需复述。可接入宿主的代理、凭据和传输策略；须保留传入的取消信号并返回标准 `Response`。 |
+| `onResponseEvent(request, event)` | 同步观察主响应实际提交的标准 Responses 事件；`request` 是变换后的请求。缓冲后因失败丢弃的工具事件、辅助请求和 keepalive 不进入观察器。JSON 请求也产生同样的语义事件，其中每个已提交输出项有一次 `response.output_item.done`。 |
+
+观察器应只读取参数，不修改请求或事件，也不返回 Promise。它在事件写出后同步执行；抛出的异常会进入现有请求错误处理，并停止该请求的后续观察，已经写出的事件无法撤回。如果交付终止错误时观察器自身抛错，bridge 关闭当前响应连接，不再尝试发送第二个错误；其他请求仍可继续。请求结束时取消仍在进行的上游调用，重试由客户端或宿主决定。原始上游帧及辅助调用的调试使用[检查器](inspect.md)。
+
+宿主可通过 `AsyncLocalStorage` 在请求处理作用域中保存自己的关联信息，供 fetch 与观察器读取。bridge 不要求特定宿主元数据格式，也不管理宿主的重试。
+
+如果宿主已有超时策略，分别设置连接的 `headers_timeout_ms` 和 `stream_idle_timeout_ms`；`null` 禁用对应阶段，省略保持默认行为，详见[连接配置](config.md#上游连接)。

package/docs/releasing.md

@@ -4,7 +4,7 @@
 
 ## 日常验证
 
-GitHub Actions 工作流 `codeks-bridge-npm.yml` 只手动触发，不在每次提交时运行。默认 `publish=false`：安装开发依赖、类型检查、测试、构建、公开信息检查，再生成并安装测试 npm tarball。工作流保存实际测试过的 tarball，发布步骤直接使用同一份文件。
+GitHub Actions 工作流 `codeks-bridge-npm.yml` 只手动触发，不在每次提交时运行。默认 `publish=false`：安装开发依赖、类型检查、测试、构建、公开信息检查，再生成 npm tarball，并在 Node.js 24 和最低运行时 20.19 上安装验证公开 API、类型、CLI、嵌入请求与 UI 资源。工作流保存实际测试过的 tarball，发布步骤直接使用同一份文件。
 
 ```sh
 gh workflow run codeks-bridge-npm.yml --ref main

package/docs/responses-stream.md

@@ -87,4 +87,4 @@ GPT 保留原始 usage，包括提供的 cache write 等分项；DeepSeek 使用
 
 按需复述的等待可能覆盖完整的辅助推理，客户端空闲超时应足以容纳该等待。
 
-上游空闲超时独立控制，默认 300 秒，可设置 `upstreams.<id>.stream_idle_timeout_ms`，也覆盖等待响应头和读取错误体的阶段。只有上游字节重置它，下游 keepalive 不延长它。因此已接受的慢压缩可以保持客户端连接，卡住的上游仍会超时报错。
+上游响应体空闲超时由 `upstreams.<id>.stream_idle_timeout_ms` 控制，默认 300 秒，也覆盖读取错误体。只有上游字节重置它，下游 keepalive 不延长它。等待响应头的时限由 `headers_timeout_ms` 控制，省略时沿用响应体空闲时限；收到响应头后重新开始响应体计时。任一字段设为 `null` 可禁用对应阶段的时限；两者均省略时保留原来的 300 秒行为。宿主已有传输重试或超时策略时，可据此分开配置，bridge 本身仍不重试。

package/docs/testing.md

@@ -1,5 +1,7 @@
 # 验证
 
+开发与直接运行 TypeScript 源码需要 Node.js ≥ 22.18；已发布 JavaScript 包支持 Node.js ≥ 20.19。
+
 桥接器的测试只使用 Node 内置测试器和本地假上游，不需要模型密钥。普通测试不启动 codeks，也不编译其 Rust 项目。
 
 ```sh
@@ -25,6 +27,7 @@ npm run check
 - 保留历史：按需复述使用客户端实际保留的历史而不再裁剪；源指令与工具声明恢复，检查点后的工作留给目标请求。
 - 后端与历史：各 API 的消息、工具、图片、schema、thinking、usage 与错误转换；Claude 空工具结果、上下文边界停止及不完整工具不交付。
 - 检查器：四段内容逐字节保存、只脱敏凭据 header、上游调用标签、标注与实际回放决定一致、捕获开关与结束时的软上限淘汰、清空释放数据且不打断请求、客户端断开、无 token 时的 loopback 与同源限制、token 鉴权、静态文件路径、导出格式和跨块 SSE 解析；Responses Lite 结构视图补全输出且保留原始事件。
+- 嵌入：请求在路由前同步或异步变换；出站 fetch 按服务实例注入并覆盖三种 adapter、压缩及按需复述；观察器只接收主响应实际提交的 Responses 事件，流式与 JSON 保持一致，失败时未提交工具不外泄；响应头和响应体超时可分别禁用。
 - Header 与错误：会话、路由及未知 header 默认透传；鉴权归所选上游，必要的传输字段移除；等待上游响应头时不发送 200；GPT HTTP status/body 与原生 SSE error 字段保留；辅助复述成功时返回目标 header，失败时返回该失败的 header；Claude/DeepSeek 继续转换协议；验证没有额外请求或自动降级。
 
 这些测试检查协议和客户端行为；假上游不会验证模型是否理解提示词，也不会验证真实服务的缓存命中率、容量和区域之间的密文兼容性。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wacry/codeks-bridge",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Configurable local Responses API bridge for codeks with GPT, Claude Messages, and DeepSeek Chat adapters.",
   "license": "Apache-2.0",
   "author": "David Zhang",
@@ -31,7 +31,7 @@
     "NOTICE"
   ],
   "engines": {
-    "node": ">=22.18"
+    "node": ">=20.19"
   },
   "scripts": {
     "prepack": "npm run build",