@koreanhole/opencodex 2.96.0 → 2.97.0

package/AGENTS_INSTALL.md

@@ -23,11 +23,17 @@ To use Gemini instead, authenticate it through its official CLI and select the
 provider:
 
 ```bash
-gemini   # official login or existing GEMINI_API_KEY configuration
+gemini   # configure a Gemini Developer API or Vertex AI API key
 ocx provider add gemini-cli --set-default
 ocx start
+ocx codex sync
 ```
 
+`ocx codex sync` refreshes the Codex app catalog with locally discovered Gemini
+models and reasoning levels. Restart the Codex app/app-server after refresh. The
+catalog file is written only when `model_catalog_json` names an opencodex catalog
+or through the documented default path; unrelated Codex settings are not changed.
+
 ## Credential rules
 
 - Use the operator's existing Cline or Gemini CLI sign-in. Do not copy vendor
@@ -37,7 +43,12 @@ ocx start
 - Do not edit the operator's real Cline provider store unless the operator asks.
 - Do not import or replay Gemini OAuth/API-key material; the Gemini CLI remains
   the authentication authority.
-- The proxy writes only under `$OPENCODEX_HOME` (default `~/.opencodex`).
+- Third-party use must use a Gemini Developer API key or Vertex AI GenAI API key.
+  Gemini CLI's official FAQ identifies third-party use of its personal Google
+  OAuth authentication as a terms violation. OAuth is not a supported
+  opencodex setup path.
+- The proxy writes under `$OPENCODEX_HOME` (default `~/.opencodex`) and may update
+  the active opencodex Codex model catalog selected by `model_catalog_json`.
 
 ## Operation
 
@@ -59,6 +70,7 @@ bun run typecheck
 bun test tests/e2e/cline-only.test.ts
 bun run test:e2e:gemini
 bun run test:e2e:gemini-tool
+bun run test:e2e:gemini-reasoning
 ```
 
 Report whether each evidence path used a deterministic ACP fixture or a real

package/README.md

@@ -17,13 +17,19 @@ npm install -g cline
 cline auth
 
 npm install -g @google/gemini-cli
-gemini   # use the official login or configure GEMINI_API_KEY
+gemini   # configure GEMINI_API_KEY before using it through opencodex
 ```
 
 Gemini authentication remains in Gemini CLI's own home/settings. The proxy never
 copies, logs, or stores an API key, OAuth token, bearer token, or full request
 body.
 
+For third-party clients such as opencodex, use a Gemini Developer API key
+(Google AI Studio) or a Vertex AI GenAI API key. Do not use Gemini CLI's
+personal Google OAuth flow: Gemini CLI's official FAQ identifies third-party
+software piggybacking on its OAuth authentication as a terms violation and says
+the supported third-party method is an API key.
+
 ## Install
 
 ```bash
@@ -56,6 +62,7 @@ name = "opencodex (Cline or Gemini CLI)"
 base_url = "http://127.0.0.1:10100/v1"
 wire_api = "responses"
 requires_openai_auth = false
+model_catalog_url = "http://127.0.0.1:10100/v1/model-catalog"
 ```
 
 The model list is live. Cline ACP models are exposed as `cline-cli/<encoded-id>`;
@@ -63,6 +70,20 @@ Gemini ACP models are exposed as `gemini-cli/<encoded-id>`. Each provider keeps
 `default` selector. A provider prefix routes only to that vendor; unprefixed
 `default` uses the configured default provider.
 
+Gemini model IDs and reasoning ladders are discovered from the installed Gemini
+CLI. Thinking-capable models expose the locally supported levels; non-thinking
+models do not get an invented ladder. For a running Codex app, refresh the active
+catalog and reload the app/app-server:
+
+```bash
+bun run src/cli/index.ts codex sync
+```
+
+The command updates the root `model_catalog_json` target when it names an
+opencodex catalog, otherwise it writes `$CODEX_HOME/opencodex-catalog.json` and
+prints the activation setting. `model_catalog_url` avoids the file when the app
+catalog is fetched dynamically.
+
 ## Claude Code
 
 ```bash
@@ -114,6 +135,7 @@ bun test tests
 bun run test:e2e
 bun run test:e2e:gemini
 bun run test:e2e:gemini-tool
+bun run test:e2e:gemini-reasoning
 bun run privacy:scan
 bun run structure:check
 ```
@@ -131,6 +153,11 @@ Codex's `exec_command`, Codex executes a fixed read-only `printf`, and Gemini
 returns the final answer. Both commands use no retries. Missing binaries,
 authentication, or a Flash Lite model cause a hard failure.
 
+`test:e2e:gemini-reasoning` discovers a thinking-capable model and level from the
+local Gemini CLI, validates the refreshed Codex catalog, and runs one minimal
+reasoning-enabled turn. It fails when the authenticated account cannot execute
+the discovered model.
+
 Optional overrides are `CLINE_BIN_PATH`, `GEMINI_BIN_PATH`, and `CODEX_BIN_PATH`.
 
 ## Troubleshooting
@@ -141,9 +168,14 @@ Optional overrides are `CLINE_BIN_PATH`, `GEMINI_BIN_PATH`, and `CODEX_BIN_PATH`
   the model is `default`; native model selection requires ACP.
 - **Gemini not found**: install it and verify `gemini --help` works, or set
   `GEMINI_BIN_PATH`.
-- **Gemini authentication required**: configure Gemini CLI's official login or API
-  key; do not pass the key to opencodex.
+- **Gemini authentication required**: configure a Gemini Developer API key or
+  Vertex AI API key for Gemini CLI; do not use personal Google OAuth with this
+  third-party proxy and do not pass the key to opencodex.
 - **Gemini ACP unavailable**: upgrade Gemini CLI to a version advertising `--acp`.
+- **Gemini Pro quota exhausted**: reasoning-capable models may require paid Pro
+  quota; the catalog stays accurate but that model cannot complete a live turn.
+- **Codex model picker is stale**: run `ocx codex sync`, then restart the Codex
+  app/app-server.
 - **Port in use**: choose another port with `ocx start --port <port>`.
 - **Stale runtime state**: run `ocx stop`; it removes stale state only when the
   recorded process and health endpoint cannot be verified.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koreanhole/opencodex",
-  "version": "2.96.0",
+  "version": "2.97.0",
   "description": "Cline and Gemini CLI provider proxy for OpenAI Codex and Claude Code",
   "type": "module",
   "main": "./bin/package-main.mjs",
@@ -32,6 +32,7 @@
     "test:e2e": "bun test tests/e2e/cline-only.test.ts",
     "test:e2e:gemini": "bun test ./tests/e2e/gemini-codex.live.ts -t \"one minimal Flash Lite completion\"",
     "test:e2e:gemini-tool": "bun test ./tests/e2e/gemini-codex.live.ts -t \"one short Gemini tool call\"",
+    "test:e2e:gemini-reasoning": "bun test ./tests/e2e/gemini-reasoning.live.ts",
     "typecheck": "bun check --no-script --noEmit",
     "privacy:scan": "bun scripts/privacy-scan.ts",
     "structure:check": "bun scripts/structure-check.ts",

package/src/adapters/cli-agent/gemini/acp.ts

@@ -203,8 +203,35 @@ export interface GeminiAcpWorkspace {
   cleanup: () => Promise<void>;
 }
 
+export interface GeminiReasoningSelection {
+  modelId: string;
+  thinkingConfig: {
+    thinkingLevel?: string;
+    thinkingBudget?: number;
+    includeThoughts?: boolean;
+  };
+}
+
+function geminiSystemSettings(reasoning?: GeminiReasoningSelection): string {
+  const settings = JSON.parse(GEMINI_SYSTEM_SETTINGS) as Record<string, unknown>;
+  if (reasoning) {
+    settings.modelConfigs = {
+      customOverrides: [{
+        match: { model: reasoning.modelId },
+        modelConfig: {
+          generateContentConfig: {
+            thinkingConfig: reasoning.thinkingConfig,
+          },
+        },
+      }],
+    };
+  }
+  return `${JSON.stringify(settings, null, 2)}\n`;
+}
+
 export async function stageGeminiAcpWorkspace(
   catalog: readonly Record<string, unknown>[] = [],
+  reasoning?: GeminiReasoningSelection,
 ): Promise<GeminiAcpWorkspace> {
   const cwd = await mkdtemp(join(tmpdir(), "ocx-gemini-acp-"));
   const policyPath = join(cwd, "policy.toml");
@@ -213,7 +240,7 @@ export async function stageGeminiAcpWorkspace(
   const capturePath = join(cwd, "tool-intents.ndjson");
   await Promise.all([
     writeFile(policyPath, GEMINI_POLICY, { encoding: "utf8", mode: 0o600, flag: "wx" }),
-    writeFile(settingsPath, GEMINI_SYSTEM_SETTINGS, { encoding: "utf8", mode: 0o600, flag: "wx" }),
+    writeFile(settingsPath, geminiSystemSettings(reasoning), { encoding: "utf8", mode: 0o600, flag: "wx" }),
     writeFile(catalogPath, JSON.stringify(catalog), { encoding: "utf8", mode: 0o600, flag: "wx" }),
     ...(catalog.length > 0
       ? [writeFile(capturePath, "", { encoding: "utf8", mode: 0o600, flag: "wx" })]

package/src/adapters/cli-agent/gemini/adapter.ts

@@ -7,6 +7,11 @@ import { isStandaloneBinary } from "../../../lib/standalone";
 import type { CliAgentTurnDeps } from "../types";
 import { ToolIntentError } from "../tool-intent";
 import { resolveGeminiBinary } from "./binary";
+import {
+  discoverGeminiModelMetadata,
+  reasoningLevelForEffort,
+  type GeminiMetadataResult,
+} from "./model-metadata";
 import {
   GeminiAcpError,
   buildGeminiAcpEnv,
@@ -35,6 +40,7 @@ export interface GeminiTurnDeps extends CliAgentTurnDeps {
   env?: NodeJS.ProcessEnv;
   probeAcp?: typeof probeGeminiAcpSupport;
   stageAcp?: typeof stageGeminiAcpWorkspace;
+  metadata?: typeof discoverGeminiModelMetadata;
   runAcp?: (input: GeminiAcpTurnInput, emit: (event: AdapterEvent) => void, deps?: GeminiAcpDeps) => Promise<void>;
   acpDeps?: GeminiAcpDeps;
 }
@@ -159,6 +165,28 @@ export async function runGeminiTurn(
     return;
   }
 
+  let metadata: GeminiMetadataResult | undefined;
+  let reasoning;
+  try {
+    metadata = await (deps.metadata ?? discoverGeminiModelMetadata)({ binary, env: sourceEnv });
+    const capability = metadata.capabilities[requestedModel];
+    reasoning = reasoningLevelForEffort(capability, parsed.options.reasoning);
+    if (capability?.thinkingSupported && parsed.options.reasoning && !reasoning) {
+      emit({
+        type: "error",
+        message: `Gemini model "${requestedModel}" does not support reasoning effort "${parsed.options.reasoning}". Advertised levels: ${capability.reasoningLevels.map(level => level.effort).join(", ") || "none"}.`,
+        status: 400,
+        errorType: "invalid_request_error",
+        code: "reasoning_effort_unsupported",
+        retryable: false,
+      });
+      return;
+    }
+  } catch {
+    metadata = undefined;
+    reasoning = undefined;
+  }
+
   const acpDeps: GeminiAcpDeps = {
     ...deps.acpDeps,
     env: sourceEnv,
@@ -183,7 +211,10 @@ export async function runGeminiTurn(
 
   const vendorNames = toolNameMap(catalog);
   const vendorNameByWire = new Map([...catalog.emittedNameMap.values()].map(wireName => [wireName, wireName]));
-  const workspace = await (deps.stageAcp ?? stageGeminiAcpWorkspace)(catalog.tools);
+  const workspace = await (deps.stageAcp ?? stageGeminiAcpWorkspace)(
+    catalog.tools,
+    reasoning ? { modelId: requestedModel, thinkingConfig: reasoning.thinkingConfig } : undefined,
+  );
   try {
     const turnEnv = { ...acpEnv, GEMINI_CLI_SYSTEM_SETTINGS_PATH: workspace.settingsPath };
     const mcpServers = workspace.capturePath && catalog.emittedNameMap.size > 0

package/src/adapters/cli-agent/gemini/live-models.ts

@@ -12,6 +12,8 @@ import {
   probeGeminiAcpSupport,
   stageGeminiAcpWorkspace,
 } from "./acp";
+import { discoverGeminiModelMetadata, mergeGeminiModelDescriptors } from "./model-metadata";
+import type { OcxProviderModel } from "../../../types";
 
 export type GeminiLiveModelsFailure = "not_found" | "unsupported" | "auth_required" | "backoff" | "transport";
 
@@ -19,9 +21,11 @@ export type GeminiLiveModelsResult =
   | {
       ok: true;
       models: string[];
+      modelInfo: OcxProviderModel[];
       source: "models" | "default";
       fingerprint: string;
       stale?: true;
+      metadataWarning?: string;
     }
   | {
       ok: false;
@@ -34,16 +38,20 @@ export interface GeminiLiveModelsOptions {
   binary?: string;
   env?: NodeJS.ProcessEnv;
   deps?: AcpDeps;
+  packageRoot?: string;
   ttlMs?: number;
+  forceRefresh?: boolean;
   failureBackoffMs?: number;
   now?: () => number;
 }
 
 interface CacheEntry {
   models: string[];
+  modelInfo: OcxProviderModel[];
   source: "models" | "default";
   fetchedAt: number;
   lastFailureAt?: number;
+  metadataWarning?: string;
 }
 
 const cache = new Map<string, CacheEntry>();
@@ -59,6 +67,10 @@ function staleResult(fingerprint: string, entry: CacheEntry | undefined): Gemini
   return {
     ok: true,
     models: [...entry.models],
+    modelInfo: entry.modelInfo.map(model => ({
+      ...model,
+      supportedReasoningLevels: [...(model.supportedReasoningLevels ?? [])],
+    })),
     source: entry.source,
     fingerprint,
     stale: true,
@@ -79,8 +91,8 @@ export async function discoverGeminiLiveModels(options: GeminiLiveModelsOptions
   const fingerprint = geminiBinaryFingerprintSync(binary);
   const current = cache.get(fingerprint);
   const timestamp = now();
-  if (current && timestamp - current.fetchedAt < ttlMs) {
-    return { ok: true, models: [...current.models], source: current.source, fingerprint };
+  if (!options.forceRefresh && current && timestamp - current.fetchedAt < ttlMs) {
+    return { ok: true, models: [...current.models], modelInfo: current.modelInfo, source: current.source, fingerprint, ...(current.metadataWarning ? { metadataWarning: current.metadataWarning } : {}) };
   }
   const lastFailure = failureCache.get(fingerprint) ?? current?.lastFailureAt;
   if (lastFailure !== undefined && timestamp - lastFailure < failureBackoffMs) {
@@ -110,10 +122,18 @@ export async function discoverGeminiLiveModels(options: GeminiLiveModelsOptions
     }, options.deps);
     const session = await client.newSession({ cwd: workspace.cwd, mcpServers: [] });
     const models = geminiModelIds(session);
+    const metadata = await discoverGeminiModelMetadata({
+      binary,
+      env: sourceEnv,
+      ...(options.packageRoot ? { packageRoot: options.packageRoot } : {}),
+      ...(options.now ? { now: options.now } : {}),
+      ...(options.forceRefresh ? { ttlMs: 0 } : {}),
+    });
+    const modelInfo = mergeGeminiModelDescriptors(session.availableModels, metadata);
     const source = session.availableModels.length > 0 ? "models" : "default";
-    cache.set(fingerprint, { models, source, fetchedAt: timestamp });
+    cache.set(fingerprint, { models, modelInfo, source, fetchedAt: timestamp, ...(metadata.warning ? { metadataWarning: metadata.warning } : {}) });
     failureCache.delete(fingerprint);
-    return { ok: true, models, source, fingerprint };
+    return { ok: true, models, modelInfo, source, fingerprint, ...(metadata.warning ? { metadataWarning: metadata.warning } : {}) };
   } catch (error) {
     failureCache.set(fingerprint, timestamp);
     if (current) current.lastFailureAt = timestamp;

package/src/adapters/cli-agent/gemini/model-metadata.ts

@@ -0,0 +1,291 @@
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import type { OcxProviderModel, OcxReasoningLevel } from "../../../types";
+
+const DEFAULT_METADATA_TTL_MS = 5 * 60_000;
+
+export interface GeminiThinkingConfig {
+  thinkingLevel?: string;
+  thinkingBudget?: number;
+  includeThoughts?: boolean;
+}
+
+export interface GeminiReasoningLevel extends OcxReasoningLevel {
+  thinkingConfig: GeminiThinkingConfig;
+  originalEffort: string;
+}
+
+export interface GeminiModelCapability {
+  thinkingSupported: boolean;
+  reasoningLevels: GeminiReasoningLevel[];
+  defaultReasoningLevel?: string;
+}
+
+export interface GeminiMetadataResult {
+  packageRoot?: string;
+  settingsPath?: string;
+  capabilities: Record<string, GeminiModelCapability>;
+  warning?: string;
+}
+
+export interface GeminiMetadataOptions {
+  binary: string;
+  env?: NodeJS.ProcessEnv;
+  packageRoot?: string;
+  ttlMs?: number;
+  now?: () => number;
+}
+
+interface CachedMetadata extends GeminiMetadataResult {
+  fetchedAt: number;
+}
+
+const metadataCache = new Map<string, CachedMetadata>();
+
+export function resetGeminiMetadataCacheForTests(): void {
+  metadataCache.clear();
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function extractDefaultJsonValue(markdown: string, property: string): unknown {
+  const marker = `- **\`modelConfigs.${property}\`**`;
+  const start = markdown.indexOf(marker);
+  if (start < 0) return undefined;
+  const fenceStart = markdown.indexOf("```json", start);
+  if (fenceStart < 0) return undefined;
+  const bodyStart = markdown.indexOf("\n", fenceStart) + 1;
+  const fenceEnd = markdown.indexOf("```", bodyStart);
+  if (bodyStart <= 0 || fenceEnd < 0) return undefined;
+  try {
+    return JSON.parse(markdown.slice(bodyStart, fenceEnd).trim()) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+function extractDefaultJson(markdown: string, property: string): Record<string, unknown> | undefined {
+  return asRecord(extractDefaultJsonValue(markdown, property));
+}
+
+async function findPackageRoot(binary: string): Promise<string | undefined> {
+  let current: string;
+  try {
+    current = dirname(await realpath(binary));
+  } catch {
+    current = dirname(resolve(binary));
+  }
+  for (let depth = 0; depth < 10; depth++) {
+    try {
+      const manifest = JSON.parse(await readFile(join(current, "package.json"), "utf8")) as { name?: unknown };
+      if (manifest.name === "@google/gemini-cli") return current;
+    } catch {
+      // Keep walking toward the package root.
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return undefined;
+}
+
+async function readThinkingLevels(packageRoot: string): Promise<Array<{ effort: string; original: string }>> {
+  let files: string[];
+  try {
+    files = (await readdir(join(packageRoot, "bundle"))).filter(name => name.endsWith(".js"));
+  } catch {
+    return [];
+  }
+  const candidates = await Promise.all(files.map(async name => {
+    const path = join(packageRoot, "bundle", name);
+    const info = await stat(path).catch(() => undefined);
+    return info ? { path, size: info.size } : undefined;
+  }));
+  candidates.sort((left, right) => (left?.size ?? Infinity) - (right?.size ?? Infinity));
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    const text = await readFile(candidate.path, "utf8").catch(() => "");
+    if (!text.includes("ThinkingLevel2[\"LOW\"]")) continue;
+    const levels = [...text.matchAll(/ThinkingLevel2\["([A-Z0-9_]+)"\]/g)]
+      .map(match => match[1]!)
+      .filter(level => level !== "THINKING_LEVEL_UNSPECIFIED");
+    return [...new Set(levels)].map(level => ({ effort: level.toLowerCase(), original: level }));
+  }
+  return [];
+}
+
+function mergeConfig(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown> {
+  const out = { ...target };
+  for (const [key, value] of Object.entries(source)) {
+    const targetRecord = asRecord(out[key]);
+    const sourceRecord = asRecord(value);
+    out[key] = targetRecord && sourceRecord ? mergeConfig(targetRecord, sourceRecord) : value;
+  }
+  return out;
+}
+
+function resolveAlias(
+  id: string,
+  aliases: Record<string, unknown>,
+  seen = new Set<string>(),
+): Record<string, unknown> {
+  if (seen.has(id)) return {};
+  seen.add(id);
+  const alias = asRecord(aliases[id]);
+  if (!alias) return {};
+  const parent = stringValue(alias.extends);
+  const inherited = parent ? resolveAlias(parent, aliases, seen) : {};
+  return mergeConfig(inherited, asRecord(alias.modelConfig) ?? {});
+}
+
+function capabilitiesFromMetadata(
+  definitions: Record<string, unknown>,
+  aliases: Record<string, unknown>,
+  levels: Array<{ effort: string; original: string }>,
+  overrides: readonly unknown[],
+): Record<string, GeminiModelCapability> {
+  const capabilities: Record<string, GeminiModelCapability> = {};
+  for (const [modelId, rawDefinition] of Object.entries(definitions)) {
+    const definition = asRecord(rawDefinition);
+    const features = asRecord(definition?.features);
+    const thinkingSupported = features?.thinking === true;
+    if (!thinkingSupported) {
+      capabilities[modelId] = { thinkingSupported: false, reasoningLevels: [] };
+      continue;
+    }
+    let generateContentConfig = asRecord(resolveAlias(modelId, aliases).generateContentConfig) ?? {};
+    for (const rawOverride of overrides) {
+      const override = asRecord(rawOverride);
+      if (stringValue(asRecord(override?.match)?.model) !== modelId) continue;
+      generateContentConfig = mergeConfig(generateContentConfig, asRecord(asRecord(override?.modelConfig)?.generateContentConfig) ?? {});
+    }
+    const config = asRecord(generateContentConfig.thinkingConfig);
+    const configuredLevel = stringValue(config?.thinkingLevel)?.toLowerCase();
+    const includeThoughts = config?.includeThoughts === true;
+    const reasoningLevels = levels.map(level => ({
+      effort: level.effort,
+      originalEffort: level.original,
+      description: `Gemini CLI ${level.original} thinking level`,
+      thinkingConfig: {
+        thinkingLevel: level.original,
+        ...(includeThoughts ? { includeThoughts: true } : {}),
+      },
+    }));
+    const defaultReasoningLevel = reasoningLevels.some(level => level.effort === configuredLevel)
+      ? configuredLevel
+      : reasoningLevels.find(level => level.effort === "high")?.effort ?? reasoningLevels[0]?.effort;
+    capabilities[modelId] = {
+      thinkingSupported: true,
+      reasoningLevels,
+      ...(defaultReasoningLevel ? { defaultReasoningLevel } : {}),
+    };
+  }
+  return capabilities;
+}
+
+async function loadMetadata(options: GeminiMetadataOptions): Promise<GeminiMetadataResult> {
+  const env = options.env ?? process.env;
+  const packageRoot = options.packageRoot ?? await findPackageRoot(options.binary);
+  if (!packageRoot) return { capabilities: {}, warning: "Gemini CLI package metadata was not found." };
+  const docsPath = join(packageRoot, "bundle", "docs", "reference", "configuration.md");
+  let markdown: string;
+  try {
+    markdown = await readFile(docsPath, "utf8");
+  } catch {
+    return { packageRoot, capabilities: {}, warning: "Gemini CLI model configuration documentation was not found." };
+  }
+  const defaultAliases = extractDefaultJson(markdown, "aliases");
+  const defaultDefinitions = extractDefaultJson(markdown, "modelDefinitions");
+  const defaultOverrides = extractDefaultJsonValue(markdown, "overrides");
+  if (!defaultAliases || !defaultDefinitions) {
+    return { packageRoot, capabilities: {}, warning: "Gemini CLI model configuration metadata could not be parsed." };
+  }
+
+  const home = stringValue(env.GEMINI_CLI_HOME) ?? stringValue(env.HOME) ?? stringValue(env.USERPROFILE) ?? homedir();
+  const settingsPath = join(home, ".gemini", "settings.json");
+  let userSettings: Record<string, unknown> = {};
+  try {
+    userSettings = asRecord(JSON.parse(await readFile(settingsPath, "utf8"))) ?? {};
+  } catch {
+    // User settings are optional; absence is not a metadata failure.
+  }
+  const modelConfigs = asRecord(userSettings.modelConfigs) ?? {};
+  const aliases = mergeConfig(
+    mergeConfig(defaultAliases, asRecord(modelConfigs.customAliases) ?? {}),
+    asRecord(modelConfigs.aliases) ?? {},
+  );
+  const definitions = mergeConfig(defaultDefinitions, asRecord(modelConfigs.modelDefinitions) ?? {});
+  const overrides = [
+    ...(Array.isArray(defaultOverrides) ? defaultOverrides : []),
+    ...(Array.isArray(modelConfigs.overrides) ? modelConfigs.overrides : []),
+    ...(Array.isArray(modelConfigs.customOverrides) ? modelConfigs.customOverrides : []),
+  ];
+  const levels = await readThinkingLevels(packageRoot);
+  if (levels.length === 0) {
+    return { packageRoot, settingsPath, capabilities: {}, warning: "Gemini CLI thinking-level metadata was not found." };
+  }
+  return {
+    packageRoot,
+    settingsPath,
+    capabilities: capabilitiesFromMetadata(definitions, aliases, levels, overrides),
+  };
+}
+
+export async function discoverGeminiModelMetadata(options: GeminiMetadataOptions): Promise<GeminiMetadataResult> {
+  const env = options.env ?? process.env;
+  const key = [
+    options.packageRoot ?? "auto",
+    resolve(options.binary),
+    stringValue(env.GEMINI_CLI_HOME) ?? stringValue(env.HOME) ?? stringValue(env.USERPROFILE) ?? homedir(),
+  ].join("\n");
+  const now = options.now ?? Date.now;
+  const ttlMs = options.ttlMs ?? DEFAULT_METADATA_TTL_MS;
+  const cached = metadataCache.get(key);
+  if (cached && now() - cached.fetchedAt < ttlMs) return cached;
+  const result = await loadMetadata(options);
+  const entry: CachedMetadata = { ...result, fetchedAt: now() };
+  metadataCache.set(key, entry);
+  return entry;
+}
+
+export function mergeGeminiModelDescriptors(
+  advertised: readonly { modelId: string; name?: string; description?: string }[],
+  metadata: GeminiMetadataResult,
+): OcxProviderModel[] {
+  return advertised.map(model => {
+    const capability = metadata.capabilities[model.modelId];
+    const reasoningLevels = capability?.reasoningLevels.map(level => ({
+      effort: level.effort,
+      description: level.description,
+    })) ?? [];
+    return {
+      id: model.modelId,
+      ...(model.name ? { name: model.name } : {}),
+      ...(model.description ? { description: model.description } : {}),
+      supportedReasoningLevels: reasoningLevels,
+      ...(capability?.defaultReasoningLevel ? { defaultReasoningLevel: capability.defaultReasoningLevel } : {}),
+    };
+  });
+}
+
+export function reasoningLevelForEffort(
+  capability: GeminiModelCapability | undefined,
+  effort: string | undefined,
+): GeminiReasoningLevel | undefined {
+  if (!capability?.thinkingSupported || capability.reasoningLevels.length === 0) return undefined;
+  const wanted = effort?.trim().toLowerCase();
+  if (!wanted) {
+    return capability.reasoningLevels.find(level => level.effort === capability.defaultReasoningLevel)
+      ?? capability.reasoningLevels[0];
+  }
+  return capability.reasoningLevels.find(level => level.effort === wanted);
+}

package/src/cli/index.ts

@@ -19,6 +19,7 @@ import {
 import { startServer } from "../server";
 import { loginClineAcp } from "../adapters/cli-agent/cline/acp";
 import { runCodingAgentMcpServer } from "../adapters/cli-agent/mcp-server";
+import { syncCodexCatalog } from "../lib/codex-catalog";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -61,6 +62,7 @@ function help(): string {
     "  start [--port <port>] [--host <host>] Start the proxy",
     "  status [--json]                        Check the running proxy",
     "  stop [--json]                          Stop the running proxy",
+    "  codex sync [--json]                    Refresh the Codex model catalog",
     "  version                                Print the package version",
     "  help                                   Show this help",
     "",
@@ -177,6 +179,20 @@ async function startCommand(args: string[]): Promise<number> {
     config.port = parsed;
   }
   if (host !== undefined) config.host = host;
+  try {
+    const catalog = await syncCodexCatalog({ env });
+    if (catalog.ok && catalog.written) {
+      console.log(`Codex catalog refreshed: ${catalog.path}`);
+      console.log("Restart the Codex app/app-server to reload the model picker.");
+      if (!catalog.configured) {
+        console.log(`Activate it with: model_catalog_json = "${catalog.path}"`);
+      }
+    } else if (!catalog.ok) {
+      console.warn(`[opencodex] Codex catalog was not refreshed: ${catalog.message}`);
+    }
+  } catch (error) {
+    console.warn(`[opencodex] Codex catalog refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
   const running = startServer(config, { env });
   await writeRuntimeState({ pid: process.pid, port: running.port, host: running.host, startedAt: new Date().toISOString() }, env);
   console.log(`opencodex listening on http://${running.host}:${running.port}/v1 (default provider: ${config.defaultProvider})`);
@@ -194,6 +210,31 @@ async function startCommand(args: string[]): Promise<number> {
   return 0;
 }
 
+async function codexCommand(args: string[]): Promise<number> {
+  const sub = args.shift();
+  if (sub !== "sync") throw new ConfigError(`Unknown codex command: ${sub ?? "(missing)"}. Expected sync.`);
+  const json = takeFlag(args, "--json");
+  if (args.length > 0) throw new ConfigError(`Unknown codex sync option: ${args[0]}`);
+  const result = await syncCodexCatalog({ env: process.env });
+  if (!result.ok) {
+    if (json) console.log(JSON.stringify({ ok: false, path: result.path, reason: result.reason, message: result.message }));
+    else console.error(`ocx: ${result.message}`);
+    return 1;
+  }
+  if (json) {
+    console.log(JSON.stringify(result));
+  } else {
+    console.log(`Catalog: ${result.path}`);
+    console.log(`Models: ${result.modelCount} (Gemini ${result.geminiModelCount}, reasoning-enabled ${result.reasoningModelCount})`);
+    for (const warning of result.warnings) console.warn(`[opencodex] ${warning}`);
+    if (!result.configured) {
+      console.log(`Activate it with: model_catalog_json = "${result.path}"`);
+    }
+    console.log("Codex reload required: restart the Codex app or app-server model picker.");
+  }
+  return 0;
+}
+
 async function statusCommand(args: string[]): Promise<number> {
   const json = takeFlag(args, "--json");
   if (args.length > 0) throw new ConfigError(`Unknown status option: ${args[0]}`);
@@ -256,10 +297,11 @@ async function main(argv: string[]): Promise<number> {
   }
   if (command === "login") return await loginCommand(argv);
   if (command === "provider") return await providerCommand(argv);
+  if (command === "codex") return await codexCommand(argv);
   if (command === "start") return await startCommand(argv);
   if (command === "status") return await statusCommand(argv);
   if (command === "stop") return await stopCommand(argv);
-  throw new ConfigError(`Unknown command: ${command}. Expected login, provider, start, status, stop, version, or help.`);
+  throw new ConfigError(`Unknown command: ${command}. Expected login, provider, codex, start, status, stop, version, or help.`);
 }
 
 try {

package/src/lib/codex-catalog.ts

@@ -0,0 +1,318 @@
+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";
+
+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: ["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: boolean;
+  default_reasoning_summary: string;
+  support_verbosity: true;
+  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: 95;
+  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";
+  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: CATALOG_FALLBACK_CONTEXT,
+    max_context_window: CATALOG_FALLBACK_CONTEXT,
+    auto_compact_token_limit: Math.floor(CATALOG_FALLBACK_CONTEXT * 0.9),
+    input_modalities: ["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: true,
+    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: 95,
+    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 : []);
+  return {
+    models: [
+      ...clineModels.map((model, index) => buildCodexCatalogModel("cline-cli", model, index)),
+      ...geminiModels.map((model, index) => buildCodexCatalogModel("gemini-cli", model, clineModels.length + index)),
+    ],
+    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,6 +12,7 @@ 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 { buildCodexCatalogDocument, discoverCodexCatalogModels } from "../lib/codex-catalog";
 import { handleResponses, modelList, RequestValidationError, UnsupportedMediaError, type ProviderModels } from "./responses";
 import { handleCountTokens, handleMessages } from "./messages";
 
@@ -22,6 +23,7 @@ export interface ServerOptions {
   env?: NodeJS.ProcessEnv;
   clineDeps?: ClineTurnDeps;
   geminiDeps?: GeminiTurnDeps;
+  geminiPackageRoot?: string;
 }
 
 export interface RunningServer {
@@ -80,10 +82,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 +96,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"],
   };
 }
 
@@ -119,19 +124,28 @@ export function startServer(config: RuntimeConfig | number, options: ServerOptio
     }
     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);
       }

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";
@@ -275,7 +276,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 +299,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 +333,30 @@ 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 } : {}),
+        ...(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: [] }),
       });
     }
   }

package/src/types.ts

@@ -96,6 +96,19 @@ 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;
+}
+
 export type AdapterEvent =
   | { type: "heartbeat" }
   | { type: "text_delta"; text: string }