@koreanhole/opencodex 2.96.0 → 2.98.0

package/src/server/responses.ts

@@ -6,6 +6,7 @@ import type {
   OcxTool,
   OcxToolChoice,
   OcxUsage,
+  OcxProviderModel,
 } from "../types";
 import { runClineTurn, type ClineTurnDeps } from "../adapters/cli-agent/cline/adapter";
 import { runGeminiTurn, type GeminiTurnDeps } from "../adapters/cli-agent/gemini/adapter";
@@ -48,6 +49,15 @@ export class UnsupportedMediaError extends RequestValidationError {
   }
 }
 
+export class UnsupportedOptionError extends RequestValidationError {
+  readonly code = "unsupported_option";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "UnsupportedOptionError";
+  }
+}
+
 function record(value: unknown): Record<string, unknown> | undefined {
   return value && typeof value === "object" && !Array.isArray(value)
     ? value as Record<string, unknown>
@@ -86,12 +96,42 @@ function assertNoMedia(value: unknown): void {
   for (const part of value) {
     const row = record(part);
     if (!row) continue;
-    if (row.type === "input_image" || row.type === "image_url" || row.type === "input_audio" || row.type === "video_url") {
+    if (row.type === "input_audio" || row.type === "video_url") {
       throw new UnsupportedMediaError();
     }
   }
 }
 
+function userContent(content: unknown): string | Array<{ type: "text"; text: string } | { type: "image"; imageUrl?: string; mimeType?: string }> {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts: Array<{ type: "text"; text: string } | { type: "image"; imageUrl?: string; mimeType?: string }> = [];
+  for (const raw of content) {
+    const row = record(raw);
+    if (!row) continue;
+    if (row.type === "input_text" || row.type === "text" || row.type === "output_text") {
+      if (typeof row.text === "string") parts.push({ type: "text", text: row.text });
+      continue;
+    }
+    if (row.type === "input_image" || row.type === "image_url") {
+      const imageUrl = typeof row.image_url === "string"
+        ? row.image_url
+        : typeof row.image_url === "object" && row.image_url && typeof (row.image_url as Record<string, unknown>).url === "string"
+          ? String((row.image_url as Record<string, unknown>).url)
+          : undefined;
+      if (!imageUrl) throw new UnsupportedMediaError();
+      parts.push({
+        type: "image",
+        imageUrl,
+        ...(typeof row.mime_type === "string" ? { mimeType: row.mime_type } : {}),
+      });
+      continue;
+    }
+    if (row.type === "input_audio" || row.type === "video_url") throw new UnsupportedMediaError();
+  }
+  return parts;
+}
+
 function parseToolChoice(value: unknown): OcxToolChoice | undefined {
   if (value === undefined || value === null) return undefined;
   if (value === "auto" || value === "none" || value === "required") return { type: value };
@@ -172,7 +212,7 @@ export function parseResponsesRequest(body: unknown): ParsedResponsesRequest {
       } else if (role === "assistant") {
         messages.push({ role: "assistant", content: [{ type: "text", text: textContent(content) }], timestamp: Date.now() });
       } else {
-        messages.push({ role: "user", content: textContent(content), timestamp: Date.now() });
+        messages.push({ role: "user", content: userContent(content), timestamp: Date.now() });
       }
       return;
     }
@@ -234,6 +274,29 @@ export function parseResponsesRequest(body: unknown): ParsedResponsesRequest {
     ...(typeof row.parallel_tool_calls === "boolean" ? { parallelToolCalls: row.parallel_tool_calls } : {}),
     ...(typeof record(row.reasoning)?.effort === "string" ? { reasoning: record(row.reasoning)!.effort as string } : {}),
   };
+  const previousResponseId = typeof row.previous_response_id === "string" && row.previous_response_id.trim()
+    ? row.previous_response_id.trim()
+    : undefined;
+  const promptCacheKey = typeof row.prompt_cache_key === "string" && row.prompt_cache_key.trim()
+    ? row.prompt_cache_key.trim()
+    : undefined;
+  const ignoredOptions = [
+    ...(typeof row.max_output_tokens === "number" ? ["max_output_tokens"] : []),
+    ...(typeof row.temperature === "number" ? ["temperature"] : []),
+    ...(typeof row.top_p === "number" ? ["top_p"] : []),
+    ...(row.stop !== undefined ? ["stop"] : []),
+    ...(typeof row.parallel_tool_calls === "boolean" ? ["parallel_tool_calls"] : []),
+    ...(row.text !== undefined ? ["text"] : []),
+    ...(row.store !== undefined ? ["store"] : []),
+    ...(row.include !== undefined ? ["include"] : []),
+    ...(row.service_tier !== undefined ? ["service_tier"] : []),
+  ];
+  if (row.store === true) throw new UnsupportedOptionError("store=true is not supported by the CLI transport.");
+  const text = record(row.text);
+  if (text?.format !== undefined) throw new UnsupportedOptionError("text.format is not supported by the CLI transport.");
+  if (typeof row.service_tier === "string" && row.service_tier !== "auto" && row.service_tier !== "default") {
+    throw new UnsupportedOptionError("The requested service_tier is not supported by the CLI transport.");
+  }
   return {
     requestedModel: row.model,
     declared,
@@ -246,6 +309,9 @@ export function parseResponsesRequest(body: unknown): ParsedResponsesRequest {
         ...(declaredTools.length > 0 ? { tools: declaredTools.map(entry => entry.tool) } : {}),
       },
       options,
+      ...(previousResponseId ? { previousResponseId } : {}),
+      ...(promptCacheKey ? { promptCacheKey } : {}),
+      ...(ignoredOptions.length > 0 ? { ignoredOptions } : {}),
       _rawBody: body,
     },
   };
@@ -275,7 +341,8 @@ export function resolveClineModel(requested: string, known: Iterable<string>): s
   return decodeRoutedModelId(suffix, known);
 }
 
-export type ProviderModels = Partial<Record<ProviderId, readonly string[]>>;
+export type ProviderModelEntry = string | OcxProviderModel;
+export type ProviderModels = Partial<Record<ProviderId, readonly ProviderModelEntry[]>>;
 
 export interface RoutedModel {
   providerId: ProviderId;
@@ -297,10 +364,16 @@ export function resolveRoutedModel(
   const suffix = requested.startsWith(prefix) ? requested.slice(prefix.length) : requested;
   return {
     providerId,
-    modelId: suffix === "default" ? "default" : decodeRoutedModelId(suffix, known[providerId] ?? []),
+    modelId: suffix === "default"
+      ? "default"
+      : decodeRoutedModelId(suffix, (known[providerId] ?? []).map(modelIdOf)),
   };
 }
 
+function modelIdOf(model: ProviderModelEntry): string {
+  return typeof model === "string" ? model : model.id;
+}
+
 const PROVIDER_LABELS: Record<ProviderId, string> = {
   [CLINE_PROVIDER_ID]: "Cline CLI",
   [GEMINI_PROVIDER_ID]: "Gemini CLI",
@@ -325,14 +398,38 @@ export function modelList(known: string[] | ProviderModels): Array<Record<string
     display_name: "Configured default provider",
   }];
   for (const providerId of [CLINE_PROVIDER_ID, GEMINI_PROVIDER_ID] as const) {
-    const ids = ["default", ...(known[providerId] ?? []).filter(id => id !== "default")];
-    for (const id of new Set(ids)) {
+    const entries = ["default", ...(known[providerId] ?? []).filter(entry => modelIdOf(entry) !== "default")];
+    const seen = new Set<string>();
+    for (const entry of entries) {
+      const id = modelIdOf(entry);
+      if (seen.has(id)) continue;
+      seen.add(id);
+      const info = typeof entry === "string" ? { id: entry } as OcxProviderModel : entry;
+      const reasoning = info.supportedReasoningLevels ?? [];
       rows.push({
         id: `${providerId}/${encodeRoutedModelId(id)}`,
         object: "model",
         created: 0,
         owned_by: providerId,
-        display_name: id === "default" ? `${PROVIDER_LABELS[providerId]} default` : id,
+        display_name: info.name ?? (id === "default" ? `${PROVIDER_LABELS[providerId]} default` : id),
+        ...(info.description ? { description: info.description } : {}),
+        ...(info.contextWindowTokens !== undefined
+          ? {
+              context_window: info.contextWindowTokens,
+              max_context_window: info.maxContextWindowTokens ?? info.contextWindowTokens,
+            }
+          : {}),
+        ...(info.inputModalities ? { input_modalities: [...info.inputModalities] } : {}),
+        ...(info.loadSession !== undefined ? { load_session: info.loadSession } : {}),
+        ...(reasoning.length > 0
+          ? {
+              supported_reasoning_levels: reasoning.map(level => ({
+                effort: level.effort,
+                description: level.description,
+              })),
+              default_reasoning_level: info.defaultReasoningLevel ?? reasoning[0]!.effort,
+            }
+          : { supported_reasoning_levels: [] }),
       });
     }
   }
@@ -428,6 +525,7 @@ function outputMeta(declared: Map<string, DeclaredTool>, name: string): { name:
 export async function collectResponsesResult(
   parsed: ParsedResponsesRequest,
   run: (emit: (event: AdapterEvent) => void) => Promise<void>,
+  responseId = `resp_${crypto.randomUUID().replaceAll("-", "")}`,
 ): Promise<ResponsesResult> {
   const output: OutputItem[] = [];
   let currentText: OutputTextItem | undefined;
@@ -515,7 +613,7 @@ export async function collectResponsesResult(
   closeAll();
   if (failure) return { failure };
   const body = {
-    id: `resp_${crypto.randomUUID().replaceAll("-", "")}`,
+    id: responseId,
     object: "response",
     created_at: Math.floor(Date.now() / 1000),
     status: terminal?.type === "incomplete" ? "incomplete" : "completed",
@@ -534,9 +632,9 @@ export function streamResponsesResult(
   parsed: ParsedResponsesRequest,
   run: (emit: (event: AdapterEvent) => void) => Promise<void>,
   signal?: AbortSignal,
+  responseId = `resp_${crypto.randomUUID().replaceAll("-", "")}`,
 ): ReadableStream<Uint8Array> {
   const encoder = new TextEncoder();
-  const responseId = `resp_${crypto.randomUUID().replaceAll("-", "")}`;
   const createdAt = Math.floor(Date.now() / 1000);
   return new ReadableStream<Uint8Array>({
     async start(controller) {
@@ -703,15 +801,23 @@ export async function handleResponses(
   defaultProvider: ProviderId = CLINE_PROVIDER_ID,
 ): Promise<Response> {
   const parsed = parseResponsesRequest(body);
+  const responseId = `resp_${crypto.randomUUID().replaceAll("-", "")}`;
+  parsed.parsed.responseId = responseId;
+  const finish = (response: Response): Response => {
+    if (parsed.parsed.ignoredOptions?.length) {
+      response.headers.set("x-opencodex-ignored-options", parsed.parsed.ignoredOptions.join(","));
+    }
+    return response;
+  };
   const { run } = routedTurn(parsed.parsed, parsed.requestedModel, incoming, knownModels, deps, defaultProvider);
   if (parsed.parsed.stream) {
-    return new Response(streamResponsesResult(parsed, run, incoming.abortSignal), {
+    return finish(new Response(streamResponsesResult(parsed, run, incoming.abortSignal, responseId), {
       headers: { "content-type": "text/event-stream; charset=utf-8", "cache-control": "no-cache" },
-    });
+    }));
   }
-  const result = await collectResponsesResult(parsed, run);
+  const result = await collectResponsesResult(parsed, run, responseId);
   if (result.failure) {
-    return Response.json({ error: { message: result.failure.message, type: result.failure.type, code: result.failure.code ?? null } }, { status: result.failure.status });
+    return finish(Response.json({ error: { message: result.failure.message, type: result.failure.type, code: result.failure.code ?? null } }, { status: result.failure.status }));
   }
-  return Response.json(result.body);
+  return finish(Response.json(result.body));
 }

package/src/server/websocket.ts

@@ -0,0 +1,261 @@
+import type { ServerWebSocket } from "bun";
+import type { ProviderId } from "../config";
+import type { IncomingMeta } from "../types";
+import { hashMessages } from "../adapters/cli-agent/gemini/session-store";
+import {
+  parseResponsesRequest,
+  RequestValidationError,
+  routedTurn,
+  streamResponsesResult,
+  type ParsedResponsesRequest,
+  type ProviderModels,
+  type ProviderTurnDeps,
+} from "./responses";
+
+const MAX_FRAME_BYTES = 32 * 1024 * 1024;
+const WARMUP_TTL_MS = 5 * 60_000;
+const MAX_WARMUPS = 128;
+
+export interface WebSocketRequestObservation {
+  type: string;
+  generate: boolean;
+  previousResponseIdPresent: boolean;
+  inputItems: number;
+}
+
+export interface WebSocketData {
+  headers: Headers;
+  queue: Promise<void>;
+  active?: AbortController;
+  closed: boolean;
+}
+
+export type OcxWebSocket = ServerWebSocket<WebSocketData>;
+
+export interface WebSocketContext {
+  knownModels: () => Promise<ProviderModels>;
+  deps: ProviderTurnDeps;
+  defaultProvider: ProviderId;
+  timeoutMs: number;
+  onRequest?: (observation: WebSocketRequestObservation) => void;
+}
+
+interface ContextRecord {
+  parsed: ParsedResponsesRequest;
+  expiresAt: number;
+  warmup: boolean;
+}
+
+const contexts = new Map<string, ContextRecord>();
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function responseId(): string {
+  return `resp_${crypto.randomUUID().replaceAll("-", "")}`;
+}
+
+function storeContext(parsed: ParsedResponsesRequest, warmup: boolean): string {
+  const id = responseId();
+  rememberContext(id, parsed, warmup);
+  return id;
+}
+
+function rememberContext(id: string, parsed: ParsedResponsesRequest, warmup: boolean): void {
+  const now = Date.now();
+  for (const [key, value] of contexts) {
+    if (value.expiresAt <= now) contexts.delete(key);
+  }
+  while (contexts.size >= MAX_WARMUPS) {
+    const oldest = contexts.keys().next().value;
+    if (!oldest) break;
+    contexts.delete(oldest);
+  }
+  delete parsed.parsed._rawBody;
+  contexts.set(id, { parsed, expiresAt: now + WARMUP_TTL_MS, warmup });
+}
+
+function takeContext(id: string): ContextRecord | undefined {
+  const record = contexts.get(id);
+  contexts.delete(id);
+  if (!record || record.expiresAt <= Date.now()) return undefined;
+  return record;
+}
+
+function mergeContext(prior: ContextRecord, real: ParsedResponsesRequest): void {
+  const stored = prior.parsed.parsed;
+  const incoming = real.parsed;
+  const storedMessages = stored.context.messages;
+  const prefixMatches = incoming.context.messages.length >= storedMessages.length
+    && hashMessages(incoming.context.messages.slice(0, storedMessages.length)) === hashMessages(storedMessages);
+  if (!prefixMatches) {
+    incoming.context.messages = [...storedMessages, ...incoming.context.messages];
+  }
+  if (!incoming.context.systemPrompt?.length) incoming.context.systemPrompt = stored.context.systemPrompt;
+  if (!incoming.context.tools?.length) incoming.context.tools = stored.context.tools;
+  if (prior.warmup) {
+    incoming.previousResponseId = undefined;
+  }
+}
+
+function sendJson(ws: OcxWebSocket, value: Record<string, unknown>): void {
+  if (ws.data.closed) return;
+  try {
+    ws.send(JSON.stringify(value));
+  } catch {
+    ws.data.closed = true;
+  }
+}
+
+function sendError(ws: OcxWebSocket, error: unknown): void {
+  const validation = error instanceof RequestValidationError ? error : undefined;
+  const code = validation
+    ? (validation as RequestValidationError & { code?: string }).code ?? "invalid_request"
+    : "proxy_error";
+  sendJson(ws, {
+    type: "error",
+    error: {
+      message: error instanceof Error ? error.message : "Invalid WebSocket request.",
+      type: validation?.type ?? "invalid_request_error",
+      code,
+    },
+  });
+}
+
+function sendWarmup(ws: OcxWebSocket, id: string, model: string): void {
+  const base = {
+    id,
+    object: "response",
+    created_at: Math.floor(Date.now() / 1000),
+    model,
+    output: [],
+    usage: null,
+  };
+  sendJson(ws, { type: "response.created", response: { ...base, status: "in_progress" } });
+  sendJson(ws, { type: "response.completed", response: { ...base, status: "completed", end_turn: true } });
+}
+
+async function forwardStream(
+  ws: OcxWebSocket,
+  stream: ReadableStream<Uint8Array>,
+  signal: AbortSignal,
+): Promise<void> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (!ws.data.closed && !signal.aborted) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let boundary = buffer.indexOf("\n\n");
+      while (boundary >= 0) {
+        const frame = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+        const data = frame
+          .split("\n")
+          .filter(line => line.startsWith("data: "))
+          .map(line => line.slice(6))
+          .join("\n");
+        if (data && data !== "[DONE]") sendJson(ws, JSON.parse(data) as Record<string, unknown>);
+        boundary = buffer.indexOf("\n\n");
+      }
+    }
+  } finally {
+    try { await reader.cancel(); } catch { /* client gone */ }
+  }
+}
+
+async function handleFrame(ws: OcxWebSocket, raw: string, context: WebSocketContext): Promise<void> {
+  if (ws.data.closed) return;
+  if (Buffer.byteLength(raw) > MAX_FRAME_BYTES) {
+    sendError(ws, new RequestValidationError("WebSocket frame exceeds the byte limit."));
+    return;
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    sendError(ws, new RequestValidationError("WebSocket frame is not valid JSON."));
+    return;
+  }
+  const frame = record(value);
+  if (!frame || frame.type !== "response.create") {
+    sendError(ws, new RequestValidationError("WebSocket frame must be response.create."));
+    return;
+  }
+  const generate = frame.generate !== false;
+  const previousResponseId = typeof frame.previous_response_id === "string" && frame.previous_response_id.trim()
+    ? frame.previous_response_id.trim()
+    : undefined;
+  const inputItems = Array.isArray(frame.input) ? frame.input.length : typeof frame.input === "string" ? 1 : 0;
+  context.onRequest?.({
+    type: String(frame.type),
+    generate,
+    previousResponseIdPresent: Boolean(previousResponseId),
+    inputItems,
+  });
+
+  let parsed: ParsedResponsesRequest;
+  try {
+    parsed = parseResponsesRequest(frame);
+  } catch (error) {
+    sendError(ws, error);
+    return;
+  }
+
+  if (!generate) {
+    const id = storeContext(parsed, true);
+    sendWarmup(ws, id, parsed.requestedModel);
+    return;
+  }
+
+  const id = responseId();
+  parsed.parsed.responseId = id;
+  if (previousResponseId) {
+    const prior = takeContext(previousResponseId);
+    if (prior) mergeContext(prior, parsed);
+    else parsed.parsed.previousResponseId = previousResponseId;
+  }
+  rememberContext(id, parsed, false);
+
+  const controller = new AbortController();
+  ws.data.active = controller;
+  const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(context.timeoutMs)]);
+  const incoming: IncomingMeta = { headers: ws.data.headers, abortSignal: signal };
+  try {
+    const known = await context.knownModels();
+    const { run } = routedTurn(parsed.parsed, parsed.requestedModel, incoming, known, context.deps, context.defaultProvider);
+    const stream = streamResponsesResult(parsed, run, signal, id);
+    await forwardStream(ws, stream, signal);
+  } catch (error) {
+    sendError(ws, error);
+  } finally {
+    if (ws.data.active === controller) ws.data.active = undefined;
+  }
+}
+
+export function createWebSocketHandlers(context: WebSocketContext) {
+  return {
+    open(_ws: OcxWebSocket) {
+      // Connection state is initialized by the upgrade data.
+    },
+    message(ws: OcxWebSocket, message: string | Buffer) {
+      const raw = typeof message === "string" ? message : message.toString("utf8");
+      ws.data.queue = ws.data.queue
+        .then(() => handleFrame(ws, raw, context))
+        .catch(error => sendError(ws, error));
+    },
+    close(ws: OcxWebSocket) {
+      ws.data.closed = true;
+      ws.data.active?.abort();
+    },
+  };
+}
+
+export function resetWebSocketWarmupsForTests(): void {
+  contexts.clear();
+}

package/src/types.ts

@@ -31,7 +31,7 @@ export interface OcxToolCall {
 
 export interface OcxUserMessage {
   role: "user";
-  content: string | Array<OcxTextContent | { type: "image" | "video" | "audio"; text?: string; imageUrl?: string }>;
+  content: string | Array<OcxTextContent | { type: "image" | "video" | "audio"; text?: string; imageUrl?: string; mimeType?: string }>;
   timestamp: number;
 }
 
@@ -83,6 +83,12 @@ export interface OcxParsedRequest {
   stream: boolean;
   context: OcxContext;
   options: OcxRequestOptions;
+  previousResponseId?: string;
+  promptCacheKey?: string;
+  responseId?: string;
+  conversationKey?: string;
+  sessionKeySource?: string;
+  ignoredOptions?: readonly string[];
   _rawBody?: unknown;
 }
 
@@ -96,6 +102,24 @@ export interface OcxUsage {
   cacheCreationInputTokens?: number;
 }
 
+export interface OcxReasoningLevel {
+  effort: string;
+  description: string;
+}
+
+export interface OcxProviderModel {
+  id: string;
+  name?: string;
+  description?: string;
+  supportedReasoningLevels?: readonly OcxReasoningLevel[];
+  defaultReasoningLevel?: string;
+  contextWindowTokens?: number;
+  maxContextWindowTokens?: number;
+  compressionThreshold?: number;
+  inputModalities?: readonly ("text" | "image" | "audio")[];
+  loadSession?: boolean;
+}
+
 export type AdapterEvent =
   | { type: "heartbeat" }
   | { type: "text_delta"; text: string }