@bitkyc08/opencodex 0.2.1 → 1.9.0

package/src/types.ts

@@ -1,5 +1,6 @@
 export interface OcxParsedRequest {
   modelId: string;
+  previousResponseId?: string;
   context: OcxContext;
   stream: boolean;
   options: OcxRequestOptions;
@@ -149,6 +150,7 @@ export interface OcxRequestOptions {
 export type AdapterEvent =
   | { type: "text_delta"; text: string }
   | { type: "thinking_delta"; thinking: string }
+  | { type: "reasoning_raw_delta"; text: string }
   | { type: "tool_call_start"; id: string; name: string }
   | { type: "tool_call_delta"; arguments: string }
   | { type: "tool_call_end" }
@@ -158,6 +160,8 @@ export type AdapterEvent =
 export interface OcxUsage {
   inputTokens: number;
   outputTokens: number;
+  cachedInputTokens?: number;
+  reasoningOutputTokens?: number;
 }
 
 export interface OcxConfig {
@@ -171,6 +175,8 @@ export interface OcxConfig {
   subagentModels?: string[];
   /** Routed model ids ("<provider>/<model>") hidden from Codex (excluded from the catalog + /v1/models). */
   disabledModels?: string[];
+  /** Advertise supports_websockets so Codex opens the WS endpoint. Default false; set true to opt into WS. */
+  websockets?: boolean;
   /** Freshness window (ms) for the per-provider live `/models` cache. Defaults to 5 min. */
   modelCacheTtlMs?: number;
   /** Web-search sidecar: route web_search for non-OpenAI models through a gpt-mini via ChatGPT passthrough. */

package/src/vision/describe.ts

@@ -1,5 +1,6 @@
 import type { OcxProviderConfig } from "../types";
 import { FORWARD_HEADERS } from "../adapters/openai-responses";
+import { signalWithTimeout } from "../abort";
 import { parseSidecarSSE } from "../web-search/parse";
 
 export interface VisionSettings {
@@ -48,6 +49,7 @@ export async function describeImage(
   forwardProvider: OcxProviderConfig,
   incomingHeaders: Headers,
   settings: VisionSettings,
+  abortSignal?: AbortSignal,
 ): Promise<DescribeOutcome> {
   const invalid = validateImageUrl(imageUrl);
   if (invalid) return { text: "", error: invalid };
@@ -76,12 +78,13 @@ export async function describeImage(
     store: false,
     stream: true,
   };
+  const linkedSignal = signalWithTimeout(settings.timeoutMs, abortSignal);
   try {
     const res = await fetch(`${forwardProvider.baseUrl}/responses`, {
       method: "POST",
       headers,
       body: JSON.stringify(body),
-      signal: AbortSignal.timeout(settings.timeoutMs),
+      signal: linkedSignal.signal,
     });
     if (!res.ok) {
       const t = await res.text().catch(() => "");
@@ -94,5 +97,7 @@ export async function describeImage(
     return { text: parsed.text };
   } catch (e) {
     return { text: "", error: e instanceof Error ? e.message : String(e) };
+  } finally {
+    linkedSignal.cleanup();
   }
 }

package/src/vision/index.ts

@@ -107,6 +107,7 @@ export async function describeImagesInPlace(
   forwardProvider: OcxProviderConfig,
   incomingHeaders: Headers,
   settings: VisionSettings,
+  abortSignal?: AbortSignal,
 ): Promise<void> {
   // 1. Gather every image part across messages, each with its own message's text as context.
   const jobs: ImageJob[] = [];
@@ -129,7 +130,7 @@ export async function describeImagesInPlace(
 
   // 2. Describe all images with bounded concurrency (order preserved).
   const outcomes = await runBounded(jobs, VISION_CONCURRENCY, j =>
-    describeImage(j.imageUrl, j.detail, j.contextText, forwardProvider, incomingHeaders, settings));
+    describeImage(j.imageUrl, j.detail, j.contextText, forwardProvider, incomingHeaders, settings, abortSignal));
 
   // 3. Rebuild each message, replacing image parts with their descriptions in order.
   let oi = 0;

package/src/web-search/executor.ts

@@ -1,5 +1,6 @@
 import type { OcxProviderConfig } from "../types";
 import { FORWARD_HEADERS } from "../adapters/openai-responses";
+import { signalWithTimeout } from "../abort";
 import { parseSidecarSSE, type WebSearchResult } from "./parse";
 
 export interface SidecarSettings {
@@ -36,6 +37,7 @@ export async function runWebSearch(
   forwardProvider: OcxProviderConfig,
   incomingHeaders: Headers,
   settings: SidecarSettings,
+  abortSignal?: AbortSignal,
 ): Promise<SidecarOutcome> {
   const headers: Record<string, string> = { "Content-Type": "application/json" };
   if (forwardProvider.headers) Object.assign(headers, forwardProvider.headers);
@@ -57,12 +59,13 @@ export async function runWebSearch(
     stream: true,
   };
   const url = `${forwardProvider.baseUrl}/responses`;
+  const linkedSignal = signalWithTimeout(settings.timeoutMs, abortSignal);
   try {
     const res = await fetch(url, {
       method: "POST",
       headers,
       body: JSON.stringify(body),
-      signal: AbortSignal.timeout(settings.timeoutMs),
+      signal: linkedSignal.signal,
     });
     if (!res.ok) {
       const t = await res.text().catch(() => "");
@@ -71,5 +74,7 @@ export async function runWebSearch(
     return await parseSidecarSSE(res);
   } catch (e) {
     return { text: "", sources: [], error: e instanceof Error ? e.message : String(e) };
+  } finally {
+    linkedSignal.cleanup();
   }
 }

package/src/web-search/loop.ts

@@ -95,6 +95,7 @@ export interface WebSearchLoopDeps {
   incomingHeaders: Headers;
   settings: SidecarSettings;
   maxSearches: number;
+  abortSignal?: AbortSignal;
 }
 
 /**
@@ -104,7 +105,7 @@ export interface WebSearchLoopDeps {
  * streamed Responses SSE. web_search calls are executed internally and never relayed to Codex.
  */
 export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Response> {
-  const { parsed, adapter, incomingHeaders, forwardProvider, hostedTool, settings, maxSearches } = deps;
+  const { parsed, adapter, incomingHeaders, forwardProvider, hostedTool, settings, maxSearches, abortSignal } = deps;
   if (!adapter.parseResponse) return jsonError(500, "web-search sidecar requires a non-streaming adapter");
 
   const messages: OcxMessage[] = [...parsed.context.messages];
@@ -129,7 +130,12 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
     const request = adapter.buildRequest(iterParsed, { headers: incomingHeaders });
     let resp: Response;
     try {
-      resp = await fetch(request.url, { method: request.method, headers: request.headers, body: request.body });
+      resp = await fetch(request.url, {
+        method: request.method,
+        headers: request.headers,
+        body: request.body,
+        signal: abortSignal,
+      });
     } catch (e) {
       return jsonError(502, `Provider unreachable: ${e instanceof Error ? e.message : String(e)}`);
     }
@@ -159,7 +165,7 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
         outcome = { text: "", sources: [], error: "the model called web_search with an empty query" };
         searchesExecuted++;
       } else {
-        outcome = await runWebSearch(call.query, hostedTool, forwardProvider, incomingHeaders, settings);
+        outcome = await runWebSearch(call.query, hostedTool, forwardProvider, incomingHeaders, settings, abortSignal);
         searchesExecuted++;
         if (outcome.error) failedQueries.add(normalizeQuery(call.query));
       }

package/src/ws-bridge.ts

@@ -0,0 +1,359 @@
+import type { ServerWebSocket } from "bun";
+import { FORWARD_HEADERS } from "./adapters/openai-responses";
+
+const OPEN = 1;
+const TERMINAL_TYPES = new Set(["response.completed", "response.failed", "response.incomplete"]);
+const SAFE_RESPONSE_HEADER_EXACT = new Set([
+  "retry-after",
+  "x-request-id",
+  "openai-request-id",
+  "x-codex-turn-state",
+  "openai-model",
+  "x-models-etag",
+  "x-reasoning-included",
+]);
+
+export interface WsData {
+  headers?: Headers; // selected inbound upgrade headers only; never store full cookies/handshake internals
+  cancel?: () => void; // cancels the in-flight stream reader/fetch
+  turnId?: number; // monotonically increasing per socket; prevents stale frames after replacement turns
+}
+
+export class WsSendDroppedError extends Error {
+  constructor() {
+    super("websocket send dropped the message");
+  }
+}
+
+export function selectForwardHeaders(headers: Headers): Headers {
+  const selected = new Headers();
+  for (const name of FORWARD_HEADERS) {
+    const value = headers.get(name);
+    if (value) selected.set(name, value);
+  }
+  return selected;
+}
+
+export function safeResponseHeaders(headers: Headers): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [name, value] of headers) {
+    const lower = name.toLowerCase();
+    if (
+      SAFE_RESPONSE_HEADER_EXACT.has(lower) ||
+      lower.startsWith("x-ratelimit-") ||
+      /^x-codex(?:-[a-z0-9-]+)?-(primary|secondary)-(used-percent|window-minutes|reset-at)$/.test(lower) ||
+      /^x-codex(?:-[a-z0-9-]+)?-limit-name$/.test(lower)
+    ) {
+      out[lower] = value;
+    }
+  }
+  return out;
+}
+
+export function buildWarmupCompletionFrames(frame: Record<string, unknown>): string[] {
+  const createdAt = Math.floor(Date.now() / 1000);
+  const baseResponse: Record<string, unknown> = {
+    id: "",
+    object: "response",
+    created_at: createdAt,
+    model: typeof frame.model === "string" ? frame.model : undefined,
+    output: [],
+  };
+  return [
+    JSON.stringify({
+      type: "response.created",
+      sequence_number: 0,
+      response: { ...baseResponse, status: "in_progress" },
+    }),
+    JSON.stringify({
+      type: "response.completed",
+      sequence_number: 1,
+      response: { ...baseResponse, status: "completed" },
+    }),
+  ];
+}
+
+export function sendTextFrame(ws: ServerWebSocket<WsData>, payload: string): void {
+  if (ws.readyState !== OPEN) throw new WsSendDroppedError();
+  const result = ws.send(payload);
+  if (result === 0) throw new WsSendDroppedError();
+  // Bun returns -1 when queued with backpressure. That is accepted; a later 0 is the hard failure.
+}
+
+export function sendJsonFrame(ws: ServerWebSocket<WsData>, payload: Record<string, unknown>): void {
+  sendTextFrame(ws, JSON.stringify(payload));
+}
+
+export function buildWsErrorFrame(
+  status: number,
+  error: Record<string, unknown>,
+  headers?: Headers,
+): Record<string, unknown> {
+  return {
+    type: "error",
+    status,
+    error,
+    headers: headers ? safeResponseHeaders(headers) : {},
+  };
+}
+
+function parseSseBlock(block: string): string | null {
+  const data: string[] = [];
+  for (const line of block.split(/\r?\n/)) {
+    if (line.startsWith("data:")) {
+      const value = line.slice(5);
+      data.push(value.startsWith(" ") ? value.slice(1) : value);
+    }
+  }
+  return data.length > 0 ? data.join("\n") : null;
+}
+
+function nextSseBlock(buffer: string): { block: string; rest: string } | null {
+  const match = buffer.match(/\r?\n\r?\n/);
+  if (!match || match.index === undefined) return null;
+  return {
+    block: buffer.slice(0, match.index),
+    rest: buffer.slice(match.index + match[0].length),
+  };
+}
+
+function payloadType(payload: string): string | null {
+  try {
+    const json = JSON.parse(payload) as { type?: unknown };
+    return typeof json.type === "string" ? json.type : null;
+  } catch {
+    return null;
+  }
+}
+
+function protocolError(message: string): Record<string, unknown> {
+  return {
+    type: "protocol_error",
+    code: "websocket_protocol_error",
+    message,
+  };
+}
+
+function sendProtocolError(ws: ServerWebSocket<WsData>, status: number, message: string): void {
+  sendJsonFrame(ws, buildWsErrorFrame(status, protocolError(message)));
+}
+
+export async function pumpResponsesSseToWebSocket(
+  ws: ServerWebSocket<WsData>,
+  sseStream: ReadableStream<Uint8Array>,
+  options: { isCurrent?: () => boolean } = {},
+): Promise<void> {
+  const reader = sseStream.getReader();
+  const isCurrent = options.isCurrent ?? (() => true);
+  const cancel = () => {
+    void reader.cancel().catch(() => {});
+  };
+  ws.data.cancel = cancel;
+
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let terminalSeen = false;
+
+  const handlePayload = (payload: string): boolean => {
+    if (!isCurrent()) return true;
+    if (payload === "[DONE]") return false;
+    const type = payloadType(payload);
+    if (!type) {
+      sendProtocolError(ws, 502, "Invalid JSON payload in upstream SSE frame");
+      terminalSeen = true;
+      void reader.cancel().catch(() => {});
+      return true;
+    }
+    if (terminalSeen) return true;
+    sendTextFrame(ws, payload);
+    if (TERMINAL_TYPES.has(type)) {
+      terminalSeen = true;
+      void reader.cancel().catch(() => {});
+      return true;
+    }
+    return false;
+  };
+
+  try {
+    while (!terminalSeen) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let next: { block: string; rest: string } | null;
+      while ((next = nextSseBlock(buffer))) {
+        buffer = next.rest;
+        const payload = parseSseBlock(next.block);
+        if (payload && handlePayload(payload)) break;
+      }
+    }
+    buffer += decoder.decode();
+    if (!terminalSeen && buffer.trim()) {
+      const payload = parseSseBlock(buffer);
+      if (payload) handlePayload(payload);
+    }
+    if (!terminalSeen && isCurrent()) {
+      sendProtocolError(ws, 502, "Upstream stream ended before response terminal event");
+    }
+  } catch (err) {
+    if (!terminalSeen && isCurrent() && ws.readyState === OPEN) {
+      sendProtocolError(ws, 502, err instanceof Error ? err.message : String(err));
+    }
+  } finally {
+    if (ws.data.cancel === cancel) ws.data.cancel = undefined;
+  }
+}
+
+export function sendResponsesJsonAsEvents(
+  ws: ServerWebSocket<WsData>,
+  response: Record<string, unknown>,
+): void {
+  const output = Array.isArray(response.output) ? response.output : [];
+  sendJsonFrame(ws, {
+    type: "response.created",
+    response: { ...response, status: "in_progress", output: [] },
+  });
+  output.forEach((item, outputIndex) => {
+    sendJsonFrame(ws, {
+      type: "response.output_item.done",
+      output_index: outputIndex,
+      item,
+    });
+  });
+  sendJsonFrame(ws, {
+    type: "response.completed",
+    response: { ...response, status: "completed" },
+  });
+}
+
+function errorPayloadFromText(text: string): Record<string, unknown> {
+  try {
+    const json = JSON.parse(text) as { error?: unknown };
+    if (json.error && typeof json.error === "object" && !Array.isArray(json.error)) {
+      return json.error as Record<string, unknown>;
+    }
+  } catch {
+    /* fall through */
+  }
+  return {
+    type: "upstream_error",
+    message: text ? text.slice(0, 500) : "Upstream request failed",
+  };
+}
+
+export async function sendResponseToWebSocket(
+  ws: ServerWebSocket<WsData>,
+  response: Response,
+  isCurrent: () => boolean,
+): Promise<void> {
+  if (!isCurrent()) {
+    await response.body?.cancel().catch(() => {});
+    return;
+  }
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    if (!isCurrent()) return;
+    sendJsonFrame(ws, buildWsErrorFrame(response.status, errorPayloadFromText(text), response.headers));
+    return;
+  }
+
+  const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
+  if (!response.body) {
+    sendJsonFrame(ws, buildWsErrorFrame(502, {
+      type: "protocol_error",
+      code: "websocket_protocol_error",
+      message: `Unexpected successful upstream response without a body (${response.status})`,
+    }, response.headers));
+    return;
+  }
+
+  if (contentType.includes("text/event-stream")) {
+    await pumpResponsesSseToWebSocket(ws, response.body, { isCurrent });
+    return;
+  }
+
+  if (contentType.includes("application/json")) {
+    const text = await response.text();
+    if (!isCurrent()) return;
+    const json = JSON.parse(text) as Record<string, unknown>;
+    sendResponsesJsonAsEvents(ws, json);
+    return;
+  }
+
+  const { prefix, stream } = await readBoundedPrefix(response.body);
+  if (!isCurrent()) {
+    await stream.cancel().catch(() => {});
+    return;
+  }
+  if (looksLikeSse(prefix)) {
+    await pumpResponsesSseToWebSocket(ws, stream, { isCurrent });
+    return;
+  }
+
+  const text = await new Response(stream).text();
+  if (!isCurrent()) return;
+  const trimmed = text.trim();
+  if (trimmed.startsWith("{")) {
+    const json = JSON.parse(trimmed) as Record<string, unknown>;
+    sendResponsesJsonAsEvents(ws, json);
+    return;
+  }
+
+  sendJsonFrame(ws, buildWsErrorFrame(502, {
+    type: "protocol_error",
+    code: "websocket_protocol_error",
+    message: `Unexpected successful non-SSE upstream response (${contentType || "missing content-type"})`,
+  }, response.headers));
+}
+
+export async function readBoundedPrefix(
+  body: ReadableStream<Uint8Array>,
+  maxBytes = 4096,
+): Promise<{ prefix: Uint8Array; stream: ReadableStream<Uint8Array> }> {
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let remainder: Uint8Array | undefined;
+  let total = 0;
+  while (total < maxBytes) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    const take = Math.min(value.byteLength, maxBytes - total);
+    if (take > 0) {
+      chunks.push(value.slice(0, take));
+      total += take;
+    }
+    if (take < value.byteLength) {
+      remainder = value.slice(take);
+      break;
+    }
+  }
+  const prefix = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    prefix.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      if (prefix.byteLength > 0) controller.enqueue(prefix);
+      if (remainder && remainder.byteLength > 0) controller.enqueue(remainder);
+    },
+    async pull(controller) {
+      const { done, value } = await reader.read();
+      if (done) {
+        controller.close();
+        return;
+      }
+      controller.enqueue(value);
+    },
+    cancel(reason) {
+      return reader.cancel(reason);
+    },
+  });
+  return { prefix, stream };
+}
+
+export function looksLikeSse(prefix: Uint8Array): boolean {
+  const text = new TextDecoder().decode(prefix);
+  return /^\s*(event:|data:)/.test(text);
+}