@koreanhole/opencodex 2.96.0 → 2.98.0

package/src/lib/codex-catalog.ts

@@ -0,0 +1,351 @@
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import type { OcxProviderModel } from "../types";
+import { discoverClineLiveModels } from "../adapters/cli-agent/cline/live-models";
+import { discoverGeminiLiveModels } from "../adapters/cli-agent/gemini/live-models";
+import type { ClineTurnDeps } from "../adapters/cli-agent/cline/adapter";
+import type { GeminiTurnDeps } from "../adapters/cli-agent/gemini/adapter";
+
+// Cline ACP descriptors expose no context source; this fallback is Cline-only.
+const CATALOG_FALLBACK_CONTEXT = 128_000;
+const BASE_INSTRUCTIONS = "You are a helpful coding assistant.";
+const MANAGED_PREFIXES = ["cline-cli/", "gemini-cli/"] as const;
+
+export interface CodexCatalogModel {
+  slug: string;
+  display_name: string;
+  description: string;
+  default_reasoning_level: string;
+  supported_reasoning_levels: Array<{ effort: string; description: string }>;
+  shell_type: "unified_exec";
+  visibility: "list";
+  supported_in_api: true;
+  priority: number;
+  base_instructions: string;
+  web_search_tool_type: "text_and_image";
+  supports_search_tool: false;
+  tool_mode: "code_mode_only";
+  context_window: number;
+  max_context_window: number;
+  auto_compact_token_limit: number;
+  input_modalities: Array<"text" | "image" | "audio">;
+  node_repl_disabled: false;
+  node_repl_auto_review_required: false;
+  include_plugin_usage_instructions: false;
+  include_apps_usage_instructions: false;
+  include_skills_usage_instructions: false;
+  supports_reasoning_summaries: boolean;
+  default_reasoning_summary: string;
+  support_verbosity: boolean;
+  default_verbosity: "low";
+  apply_patch_tool_type: "freeform";
+  truncation_policy: { mode: "tokens"; limit: number };
+  supports_parallel_tool_calls: true;
+  supports_image_detail_original: false;
+  experimental_supported_tools: [];
+  effective_context_window_percent: number;
+  comp_hash: null;
+  multi_agent_version: "v1";
+  auto_review_model_override: null;
+  supports_reasoning_effort_updates: false;
+  use_responses_lite: false;
+  additional_speed_tiers: [];
+  service_tiers: [];
+  availability_nux: null;
+  upgrade: null;
+}
+
+export interface CodexCatalogDocument {
+  fetched_at: string;
+  etag: null;
+  client_version: string;
+  identity: string;
+  models: CodexCatalogModel[];
+}
+
+export interface CodexCatalogDiscoveryOptions {
+  env?: NodeJS.ProcessEnv;
+  clineDeps?: ClineTurnDeps;
+  geminiDeps?: GeminiTurnDeps;
+  geminiBinary?: string;
+  geminiPackageRoot?: string;
+  now?: Date;
+  forceRefresh?: boolean;
+}
+
+export interface CodexCatalogModels {
+  models: CodexCatalogModel[];
+  warnings: string[];
+}
+
+export type CodexCatalogSyncResult =
+  | {
+      ok: true;
+      path: string;
+      configured: boolean;
+      written: boolean;
+      modelCount: number;
+      geminiModelCount: number;
+      reasoningModelCount: number;
+      reloadRequired: true;
+      warnings: string[];
+    }
+  | {
+      ok: false;
+      path?: string;
+      reason: "unsafe_path" | "malformed_catalog" | "write_failed" | "discovery_failed";
+      message: string;
+    };
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function encodeRoutedId(id: string): string {
+  return id.replaceAll("/", "-");
+}
+
+export function buildCodexCatalogModel(providerId: "cline-cli" | "gemini-cli", model: OcxProviderModel, index: number): CodexCatalogModel {
+  const levels = (model.supportedReasoningLevels ?? []).map(level => ({
+    effort: level.effort,
+    description: level.description,
+  }));
+  const defaultLevel = model.defaultReasoningLevel ?? levels[0]?.effort ?? "low";
+  const isDefault = model.id === "default";
+  const providerLabel = providerId === "gemini-cli" ? "Gemini CLI" : "Cline CLI";
+  const contextWindow = model.contextWindowTokens ?? (providerId === "cline-cli" ? CATALOG_FALLBACK_CONTEXT : undefined);
+  if (contextWindow === undefined) {
+    throw new Error(`Gemini model "${model.id}" has no runtime context window.`);
+  }
+  const deterministicThreshold = providerId === "gemini-cli"
+    ? model.compressionThreshold
+    : model.compressionThreshold ?? 0.9;
+  const compactLimit = deterministicThreshold !== undefined
+    ? Math.max(1, Math.floor(contextWindow * deterministicThreshold))
+    : contextWindow;
+  const effectivePercent = deterministicThreshold !== undefined
+    ? Math.max(1, Math.min(100, Math.round(deterministicThreshold * 100)))
+    : 100;
+  return {
+    slug: `${providerId}/${encodeRoutedId(model.id)}`,
+    display_name: model.name ?? (isDefault ? `${providerLabel} default` : model.id),
+    description: model.description ?? `Routed via opencodex -> ${providerLabel}.`,
+    default_reasoning_level: levels.length > 0 ? defaultLevel : "low",
+    supported_reasoning_levels: levels,
+    shell_type: "unified_exec",
+    visibility: "list",
+    supported_in_api: true,
+    priority: 10 + index,
+    base_instructions: BASE_INSTRUCTIONS,
+    web_search_tool_type: "text_and_image",
+    supports_search_tool: false,
+    tool_mode: "code_mode_only",
+    context_window: contextWindow,
+    max_context_window: model.maxContextWindowTokens ?? contextWindow,
+    auto_compact_token_limit: compactLimit,
+    input_modalities: [...(model.inputModalities ?? ["text"])],
+    node_repl_disabled: false,
+    node_repl_auto_review_required: false,
+    include_plugin_usage_instructions: false,
+    include_apps_usage_instructions: false,
+    include_skills_usage_instructions: false,
+    supports_reasoning_summaries: levels.length > 0,
+    default_reasoning_summary: levels.length > 0 ? "auto" : "none",
+    support_verbosity: false,
+    default_verbosity: "low",
+    apply_patch_tool_type: "freeform",
+    truncation_policy: { mode: "tokens", limit: 10_000 },
+    supports_parallel_tool_calls: true,
+    supports_image_detail_original: false,
+    experimental_supported_tools: [],
+    effective_context_window_percent: effectivePercent,
+    comp_hash: null,
+    multi_agent_version: "v1",
+    auto_review_model_override: null,
+    supports_reasoning_effort_updates: false,
+    use_responses_lite: false,
+    additional_speed_tiers: [],
+    service_tiers: [],
+    availability_nux: null,
+    upgrade: null,
+  };
+}
+
+function defaultModel(): OcxProviderModel {
+  return { id: "default" };
+}
+
+function normalizedModels(models: readonly OcxProviderModel[]): OcxProviderModel[] {
+  const seen = new Set<string>();
+  const out: OcxProviderModel[] = [];
+  for (const model of [defaultModel(), ...models]) {
+    if (!seen.has(model.id)) {
+      seen.add(model.id);
+      out.push(model);
+    }
+  }
+  return out;
+}
+
+export async function discoverCodexCatalogModels(options: CodexCatalogDiscoveryOptions = {}): Promise<CodexCatalogModels> {
+  const env = options.env ?? process.env;
+  const [cline, gemini] = await Promise.all([
+    discoverClineLiveModels({ env, ...(options.clineDeps ? { deps: options.clineDeps } : {}) }),
+    discoverGeminiLiveModels({
+      env,
+      ...(options.geminiBinary ? { binary: options.geminiBinary } : {}),
+      ...(options.geminiDeps ? { deps: options.geminiDeps } : {}),
+      ...(options.geminiPackageRoot ? { packageRoot: options.geminiPackageRoot } : {}),
+      ...(options.forceRefresh ? { forceRefresh: true } : {}),
+    }),
+  ]);
+  const warnings: string[] = [];
+  if (!cline.ok && cline.reason !== "not_found" && env.OPENCODEX_CLINE_ACP?.trim() !== "0") warnings.push(`Cline: ${cline.detail}`);
+  if (!gemini.ok && gemini.reason !== "not_found" && env.OPENCODEX_GEMINI_ACP?.trim() !== "0") warnings.push(`Gemini: ${gemini.detail}`);
+  if (gemini.ok && gemini.metadataWarning) warnings.push(`Gemini metadata: ${gemini.metadataWarning}`);
+  const clineModels = normalizedModels(cline.ok ? cline.models.map(id => ({ id })) : []);
+  const geminiModels = normalizedModels(gemini.ok ? gemini.modelInfo : []);
+  const geminiDefault = geminiModels.find(model => model.id === "default");
+  const geminiContexts = geminiModels.flatMap(model => model.contextWindowTokens !== undefined ? [model.contextWindowTokens] : []);
+  if (geminiDefault && geminiContexts.length > 0) {
+    const conservative = Math.min(...geminiContexts);
+    geminiDefault.contextWindowTokens = conservative;
+    geminiDefault.maxContextWindowTokens = conservative;
+    geminiDefault.compressionThreshold = geminiModels.find(model => model.compressionThreshold !== undefined)?.compressionThreshold;
+    const modalities = geminiModels.flatMap(model => model.inputModalities ?? []);
+    geminiDefault.inputModalities = [...new Set(modalities.length > 0 ? modalities : ["text" as const])]
+      .filter((value): value is "text" | "image" | "audio" => value === "text" || value === "image" || value === "audio");
+  }
+  const models: CodexCatalogModel[] = [];
+  for (const model of clineModels) {
+    models.push(buildCodexCatalogModel("cline-cli", model, models.length));
+  }
+  for (const model of geminiModels) {
+    if (model.contextWindowTokens === undefined) {
+      warnings.push(`Gemini model "${model.id}" has no runtime context window; omitted from the Codex catalog.`);
+      continue;
+    }
+    models.push(buildCodexCatalogModel("gemini-cli", model, models.length));
+  }
+  return {
+    models,
+    warnings,
+  };
+}
+
+export function buildCodexCatalogDocument(
+  models: CodexCatalogModel[],
+  now = new Date(),
+  preserved: CodexCatalogModel[] = [],
+): CodexCatalogDocument {
+  return {
+    fetched_at: now.toISOString(),
+    etag: null,
+    client_version: "0.165.0",
+    identity: "opencodex",
+    models: [...preserved, ...models],
+  };
+}
+
+function readRootTomlString(text: string, key: string): string | undefined {
+  const firstTable = text.search(/^\s*\[/m);
+  const root = firstTable < 0 ? text : text.slice(0, firstTable);
+  const match = new RegExp(`^\\s*${key}\\s*=\\s*"([^"]+)"`, "m").exec(root);
+  return match?.[1]?.trim() || undefined;
+}
+
+export async function writeCodexCatalog(
+  path: string,
+  document: CodexCatalogDocument,
+): Promise<void> {
+  const parent = dirname(path);
+  await mkdir(parent, { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await chmod(temporary, 0o600);
+    await rename(temporary, path);
+    await chmod(path, 0o600).catch(() => undefined);
+  } finally {
+    await rm(temporary, { force: true }).catch(() => undefined);
+  }
+}
+
+function managedSlug(slug: unknown): boolean {
+  return typeof slug === "string" && MANAGED_PREFIXES.some(prefix => slug.startsWith(prefix));
+}
+
+export async function syncCodexCatalog(
+  options: CodexCatalogDiscoveryOptions & {
+    path?: string;
+    discover?: typeof discoverCodexCatalogModels;
+  } = {},
+): Promise<CodexCatalogSyncResult> {
+  const env = options.env ?? process.env;
+  const codexHome = env.CODEX_HOME?.trim() || join(homedir(), ".codex");
+  let configuredPath: string | undefined;
+  try {
+    configuredPath = readRootTomlString(await readFile(join(codexHome, "config.toml"), "utf8"), "model_catalog_json");
+  } catch {
+    configuredPath = undefined;
+  }
+  const configured = configuredPath !== undefined;
+  const selected = options.path
+    ? (isAbsolute(options.path) ? options.path : resolve(options.path))
+    : configuredPath
+      ? resolve(codexHome, configuredPath)
+      : join(codexHome, "opencodex-catalog.json");
+  if (configured && basename(selected) !== "opencodex-catalog.json") {
+    return { ok: false, path: selected, reason: "unsafe_path", message: "Configured model_catalog_json is not an opencodex catalog; refusing to overwrite it." };
+  }
+
+  let existing: Record<string, unknown> = {};
+  try {
+    const parsed = asRecord(JSON.parse(await readFile(selected, "utf8")));
+    if (!parsed) return { ok: false, path: selected, reason: "malformed_catalog", message: "Existing Codex catalog is not a JSON object." };
+    existing = parsed;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      return { ok: false, path: selected, reason: "malformed_catalog", message: "Existing Codex catalog could not be parsed; it was preserved." };
+    }
+  }
+
+  let discovered: CodexCatalogModels;
+  try {
+    discovered = await (options.discover ?? discoverCodexCatalogModels)({ ...options, forceRefresh: true });
+  } catch (error) {
+    return { ok: false, reason: "discovery_failed", message: error instanceof Error ? error.message : String(error) };
+  }
+  const existingModels = Array.isArray(existing.models) ? existing.models : [];
+  if (existing.models !== undefined && !Array.isArray(existing.models)) {
+    return { ok: false, path: selected, reason: "malformed_catalog", message: "Existing Codex catalog models field is not an array; it was preserved." };
+  }
+  if (existingModels.some(model => !asRecord(model))) {
+    return { ok: false, path: selected, reason: "malformed_catalog", message: "Existing Codex catalog contains a non-object model row; it was preserved." };
+  }
+  const preserved = existingModels.filter(model => !managedSlug(asRecord(model)?.slug));
+  const document = buildCodexCatalogDocument(
+    discovered.models,
+    options.now ?? new Date(),
+    preserved as CodexCatalogModel[],
+  );
+  try {
+    await writeCodexCatalog(selected, document);
+  } catch (error) {
+    return { ok: false, path: selected, reason: "write_failed", message: error instanceof Error ? error.message : String(error) };
+  }
+  return {
+    ok: true,
+    path: selected,
+    configured,
+    written: true,
+    modelCount: document.models.length,
+    geminiModelCount: document.models.filter(model => model.slug.startsWith("gemini-cli/")).length,
+    reasoningModelCount: document.models.filter(model => model.slug.startsWith("gemini-cli/") && (model.supported_reasoning_levels?.length ?? 0) > 0).length,
+    reloadRequired: true,
+    warnings: discovered.warnings,
+  };
+}

package/src/server/index.ts

@@ -12,8 +12,14 @@ import type { ClineTurnDeps } from "../adapters/cli-agent/cline/adapter";
 import type { GeminiTurnDeps } from "../adapters/cli-agent/gemini/adapter";
 import { discoverClineLiveModels } from "../adapters/cli-agent/cline/live-models";
 import { discoverGeminiLiveModels } from "../adapters/cli-agent/gemini/live-models";
-import { handleResponses, modelList, RequestValidationError, UnsupportedMediaError, type ProviderModels } from "./responses";
+import { buildCodexCatalogDocument, discoverCodexCatalogModels } from "../lib/codex-catalog";
+import { handleResponses, modelList, RequestValidationError, UnsupportedMediaError, UnsupportedOptionError, type ProviderModels } from "./responses";
 import { handleCountTokens, handleMessages } from "./messages";
+import {
+  createWebSocketHandlers,
+  type WebSocketData,
+  type WebSocketRequestObservation,
+} from "./websocket";
 
 const MAX_REQUEST_BYTES = 32 * 1024 * 1024;
 const REQUEST_TIMEOUT_MS = 300_000;
@@ -22,6 +28,8 @@ export interface ServerOptions {
   env?: NodeJS.ProcessEnv;
   clineDeps?: ClineTurnDeps;
   geminiDeps?: GeminiTurnDeps;
+  geminiPackageRoot?: string;
+  onWebSocketRequest?: (observation: WebSocketRequestObservation) => void;
 }
 
 export interface RunningServer {
@@ -64,6 +72,9 @@ async function boundedJson(req: Request): Promise<unknown> {
 }
 
 function errorResponse(error: unknown): Response {
+  if (error instanceof UnsupportedOptionError) {
+    return Response.json({ error: { message: error.message, type: error.type, code: error.code } }, { status: error.status });
+  }
   if (error instanceof UnsupportedMediaError) {
     return Response.json({ error: { message: error.message, type: error.type, code: error.code } }, { status: error.status });
   }
@@ -80,10 +91,11 @@ async function discoverModels(
   env: NodeJS.ProcessEnv,
   clineDeps: ClineTurnDeps | undefined,
   geminiDeps: GeminiTurnDeps | undefined,
+  geminiPackageRoot: string | undefined,
 ): Promise<ProviderModels> {
   const [cline, gemini] = await Promise.all([
     discoverClineLiveModels({ env, ...(clineDeps ? { deps: clineDeps } : {}) }),
-    discoverGeminiLiveModels({ env, ...(geminiDeps ? { deps: geminiDeps } : {}) }),
+    discoverGeminiLiveModels({ env, ...(geminiDeps ? { deps: geminiDeps } : {}), ...(geminiPackageRoot ? { packageRoot: geminiPackageRoot } : {}) }),
   ]);
   if (!cline.ok && cline.reason !== "not_found" && env.OPENCODEX_CLINE_ACP?.trim() !== "0") {
     console.warn(`[opencodex] Cline model discovery degraded [${cline.reason}]: ${cline.detail}`);
@@ -93,7 +105,9 @@ async function discoverModels(
   }
   return {
     "cline-cli": cline.ok ? ["default", ...cline.models.filter(id => id !== "default")] : ["default"],
-    "gemini-cli": gemini.ok ? ["default", ...gemini.models.filter(id => id !== "default")] : ["default"],
+    "gemini-cli": gemini.ok
+      ? ["default", ...gemini.modelInfo.filter(model => model.id !== "default")]
+      : ["default"],
   };
 }
 
@@ -109,7 +123,7 @@ export function startServer(config: RuntimeConfig | number, options: ServerOptio
   const token = apiToken(config, env);
   let server: ReturnType<typeof Bun.serve>;
 
-  const fetch = async (req: Request): Promise<Response> => {
+  const fetch = async (req: Request, bunServer: Bun.Server<WebSocketData>): Promise<Response | undefined> => {
     const url = new URL(req.url);
     if (url.pathname === "/healthz") {
       return Response.json({ ok: true, service: "opencodex", version: packageInfo.version });
@@ -117,21 +131,35 @@ export function startServer(config: RuntimeConfig | number, options: ServerOptio
     if (!authorized(req, token)) {
       return Response.json({ error: { message: "Unauthorized", type: "authentication_error", code: "unauthorized" } }, { status: 401 });
     }
+    if (req.method === "GET" && url.pathname === "/v1/responses" && req.headers.get("upgrade")?.toLowerCase() === "websocket") {
+      const data: WebSocketData = { headers: req.headers, queue: Promise.resolve(), closed: false };
+      if (bunServer.upgrade(req, { data })) return undefined;
+      return new Response("WebSocket upgrade failed.", { status: 400 });
+    }
     try {
       if (req.method === "GET" && url.pathname === "/v1/models") {
-        const known = await discoverModels(env, options.clineDeps, options.geminiDeps);
+        const known = await discoverModels(env, options.clineDeps, options.geminiDeps, options.geminiPackageRoot);
         return Response.json({ object: "list", data: modelList(known) });
       }
+      if (req.method === "GET" && url.pathname === "/v1/model-catalog") {
+        const discovered = await discoverCodexCatalogModels({
+          env,
+          ...(options.clineDeps ? { clineDeps: options.clineDeps } : {}),
+          ...(options.geminiDeps ? { geminiDeps: options.geminiDeps } : {}),
+          ...(options.geminiPackageRoot ? { geminiPackageRoot: options.geminiPackageRoot } : {}),
+        });
+        return Response.json(buildCodexCatalogDocument(discovered.models));
+      }
       if (req.method === "POST" && url.pathname === "/v1/responses") {
         const body = await boundedJson(req);
-        const known = await discoverModels(env, options.clineDeps, options.geminiDeps);
+        const known = await discoverModels(env, options.clineDeps, options.geminiDeps, options.geminiPackageRoot);
         const signal = AbortSignal.any([req.signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]);
         const incoming: IncomingMeta = { headers: req.headers, abortSignal: signal };
         return await handleResponses(body, incoming, known, turnDeps, config.defaultProvider);
       }
       if (req.method === "POST" && url.pathname === "/v1/messages") {
         const body = await boundedJson(req);
-        const known = await discoverModels(env, options.clineDeps, options.geminiDeps);
+        const known = await discoverModels(env, options.clineDeps, options.geminiDeps, options.geminiPackageRoot);
         const signal = AbortSignal.any([req.signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]);
         return await handleMessages(body, { headers: req.headers, abortSignal: signal }, known, turnDeps, config.defaultProvider);
       }
@@ -144,7 +172,20 @@ export function startServer(config: RuntimeConfig | number, options: ServerOptio
     }
   };
 
-  server = Bun.serve({ hostname: config.host, port: config.port, idleTimeout: 255, fetch });
+  const websocketContext = {
+    knownModels: () => discoverModels(env, options.clineDeps, options.geminiDeps, options.geminiPackageRoot),
+    deps: turnDeps,
+    defaultProvider: config.defaultProvider,
+    timeoutMs: REQUEST_TIMEOUT_MS,
+    ...(options.onWebSocketRequest ? { onRequest: options.onWebSocketRequest } : {}),
+  };
+  server = Bun.serve({
+    hostname: config.host,
+    port: config.port,
+    idleTimeout: 255,
+    fetch,
+    websocket: createWebSocketHandlers(websocketContext),
+  });
   return {
     port: server.port ?? config.port,
     host: config.host,