@bitkyc08/opencodex 1.9.3 → 1.9.5

package/README.ko.md

@@ -77,8 +77,13 @@ codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"
 - **OAuth, API 키, 또는 ChatGPT forward.** xAI / Anthropic / Kimi 계정으로 로그인하거나(토큰은
   자동 갱신됩니다), `codex login`을 forward 하거나, 키를 붙여넣으세요(`${ENV_VARS}` 지원). 18개 프로바이더의
   API 키 카탈로그(**Ollama Cloud** 포함)가 기본 내장되어 있습니다.
-- **Codex에 바로 통합.** `$CODEX_HOME/config.toml`(기본값 `~/.codex/config.toml`)에 `[model_providers.opencodex]` 테이블을 주입하고
-  라우팅된 모델을 Codex의 카탈로그와 서브에이전트 선택기에 병합합니다 — 완전히 되돌릴 수 있습니다.
+- **Codex CLI, TUI, App, SDK에 바로 통합.** `$CODEX_HOME/config.toml`(기본값 `~/.codex/config.toml`)에
+  `[model_providers.opencodex]` 테이블을 주입하고 공유 Codex 모델 카탈로그를 작성하여 라우팅된 모델이
+  Codex 모델 선택기에 표시되게 합니다.
+- **서브에이전트 제어.** `subagentModels` 또는 웹 대시보드에서 최대 5개의 라우팅/네이티브 모델을
+  Codex `spawn_agent` 선택기에 우선 노출할 수 있습니다.
+- **기본은 HTTP/SSE, WebSocket은 opt-in.** 프록시는 Responses WebSocket 엔드포인트를 갖고 있지만,
+  `"websockets": true`일 때만 `supports_websockets`를 광고합니다.
 - **Sidecar.** OpenAI가 아닌 모델에도 ChatGPT 로그인을 통한 `gpt-5.4-mini`를 사용해 실제 **웹 검색**과
   **이미지 이해** 기능을 제공합니다.
 - 프로바이더, OAuth 로그인, 모델 선택, 요청 로그를 위한 **웹 대시보드**.
@@ -111,6 +116,7 @@ ocx login <xai|anthropic|kimi> # OAuth login
 ocx logout <provider>          # remove a stored login
 ocx gui                        # open the web dashboard
 ocx service <install|start|stop|status|uninstall>   # run as a background service
+ocx update                     # update opencodex to the latest published version
 ```
 
 ## 설정
@@ -138,15 +144,21 @@ ocx service <install|start|stop|status|uninstall>   # run as a background servic
 }
 ```
 
+WebSocket 전송은 기본적으로 꺼져 있습니다. Codex가 HTTP/SSE 대신 Responses WebSocket 경로를 광고하고
+사용하게 하려면 `"websockets": true`를 명시하세요.
+
 모든 필드에 대한 자세한 내용은 **[설정 레퍼런스](https://lidge-jun.github.io/opencodex/ko/reference/configuration/)**
 를 참고하세요.
 
 ## 문서
 
-전체 개발자 문서 — 아키텍처, 모든 adapter, 요청 라이프사이클, sidecar,
-Codex 통합, CLI/설정 레퍼런스 — 는 [`docs-site/`](./docs-site) 아래의 Astro 사이트이며
+공개 문서 — 설치, 프로바이더, 라우팅, sidecar, Codex 통합, Codex App 모델 선택기,
+CLI/설정 레퍼런스 — 는 [`docs-site/`](./docs-site) 아래의 Astro 사이트이며
 **[lidge-jun.github.io/opencodex](https://lidge-jun.github.io/opencodex/ko/)**에 게시됩니다.
 
+유지보수용 source of truth는 [`structure/`](./structure)에 있고, 과거 조사/진단 노트는
+[`docs/`](./docs)에 남아 있습니다.
+
 ## 개발
 
 ```bash

package/README.md

@@ -87,9 +87,13 @@ codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"
 - **OAuth, API key, or ChatGPT forward.** Log in with your xAI / Anthropic / Kimi account (tokens
   auto-refresh), forward your `codex login`, or paste a key (`${ENV_VARS}` supported). An 18-provider
   API-key catalog (incl. **Ollama Cloud**) is built in.
-- **Drops into Codex.** Injects a `[model_providers.opencodex]` table into
-  `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`) and merges routed models into Codex's
-  catalog and subagent picker — fully reversible.
+- **Drops into Codex CLI, TUI, App, and SDK.** Injects a `[model_providers.opencodex]` table into
+  `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`) and writes a shared Codex model catalog
+  so routed models appear in Codex model pickers.
+- **Subagent control.** Feature up to five routed or native models in Codex's `spawn_agent` picker
+  from `subagentModels` or the web dashboard.
+- **HTTP/SSE by default, WebSocket opt-in.** The proxy has a Responses WebSocket endpoint, but it
+  only advertises `supports_websockets` when `"websockets": true` is set.
 - **Sidecars.** Give non-OpenAI models real **web search** and **image understanding** via a
   `gpt-5.4-mini` over your ChatGPT login.
 - **Web dashboard** for providers, OAuth login, model selection, and request logs.
@@ -104,7 +108,7 @@ codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"
 | xAI Grok | `openai-chat` | oauth / key |
 | Kimi (Moonshot) | `openai-chat` | oauth / key |
 | Google Gemini | `google` | key |
-| Azure OpenAI | `azure-openai` | key |
+| Azure OpenAI | `azure` | key |
 | Ollama Cloud + 17-provider catalog | `openai-chat` | key |
 | Ollama / vLLM / LM Studio (local) | `openai-chat` | key (usually blank) |
 | Any OpenAI-compatible endpoint | `openai-chat` | key |
@@ -150,16 +154,20 @@ Config lives at `~/.opencodex/config.json`. Minimal example:
 }
 ```
 
+WebSocket transport is off by default. Set `"websockets": true` only if you want Codex to advertise
+and use the Responses WebSocket path instead of HTTP/SSE.
+
 See the **[Configuration reference](https://lidge-jun.github.io/opencodex/reference/configuration/)**
 for every field.
 
 ## Documentation
 
-The full developer documentation — architecture, every adapter, the request lifecycle, the sidecars,
-Codex integration, and the CLI/config reference — is an Astro site under [`docs-site/`](./docs-site)
-and published to **[lidge-jun.github.io/opencodex](https://lidge-jun.github.io/opencodex/)**.
-Deep implementation notes live under [`docs/`](./docs), including the Codex App/model catalog path
-that makes routed opencodex models appear in the Codex App picker.
+The public docs — install, providers, routing, sidecars, Codex integration, Codex App model picker,
+and CLI/config reference — are built from [`docs-site/`](./docs-site) and published to
+**[lidge-jun.github.io/opencodex](https://lidge-jun.github.io/opencodex/)**.
+
+Maintainer source-of-truth notes live under [`structure/`](./structure). Historical investigations
+remain under [`docs/`](./docs).
 
 ## Development
 

package/README.zh-CN.md

@@ -77,8 +77,13 @@ codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"
 - **OAuth、API key 或 ChatGPT 转发（forward）。** 用你的 xAI / Anthropic / Kimi 账户登录（token
   自动刷新）、转发你的 `codex login`，或直接粘贴一个 key（支持 `${ENV_VARS}`）。内置一份 18 家 provider 的
   API-key 目录（含 **Ollama Cloud**）。
-- **无缝接入 Codex。** 向 `$CODEX_HOME/config.toml`（默认 `~/.codex/config.toml`）注入一个 `[model_providers.opencodex]` 表，并
-  将已路由的模型合并进 Codex 的目录和 subagent 选择器 —— 完全可逆。
+- **无缝接入 Codex CLI、TUI、App 和 SDK。** 向 `$CODEX_HOME/config.toml`（默认 `~/.codex/config.toml`）
+  注入一个 `[model_providers.opencodex]` 表，并写入共享的 Codex 模型目录，让已路由的模型出现在
+  Codex 模型选择器中。
+- **Subagent 控制。** 通过 `subagentModels` 或 Web 仪表盘，将最多 5 个路由或原生模型优先展示在
+  Codex 的 `spawn_agent` 选择器中。
+- **默认 HTTP/SSE，WebSocket 需要显式开启。** 代理有 Responses WebSocket 端点，但只有设置
+  `"websockets": true` 时才会广告 `supports_websockets`。
 - **Sidecars。** 通过基于你 ChatGPT 登录的 `gpt-5.4-mini`，为非 OpenAI 模型提供真正的**网页搜索**和**图像理解**能力。
 - **Web 仪表盘**，用于管理 provider、OAuth 登录、模型选择和请求日志。
 
@@ -110,6 +115,7 @@ ocx login <xai|anthropic|kimi> # OAuth login
 ocx logout <provider>          # remove a stored login
 ocx gui                        # open the web dashboard
 ocx service <install|start|stop|status|uninstall>   # run as a background service
+ocx update                     # update opencodex to the latest published version
 ```
 
 ## 配置
@@ -137,14 +143,19 @@ ocx service <install|start|stop|status|uninstall>   # run as a background servic
 }
 ```
 
+WebSocket 传输默认关闭。只有当你希望 Codex 广告并使用 Responses WebSocket 路径而不是 HTTP/SSE 时，
+才需要设置 `"websockets": true`。
+
 每个字段的说明请参阅 **[配置参考](https://lidge-jun.github.io/opencodex/zh-cn/reference/configuration/)**。
 
 ## 文档
 
-完整的开发者文档 —— 架构、每个 adapter、请求生命周期、sidecars、
-Codex 集成，以及 CLI/配置参考 —— 是位于 [`docs-site/`](./docs-site) 下的一个 Astro 站点，
+公开文档 —— 安装、providers、路由、sidecars、Codex 集成、Codex App 模型选择器，
+以及 CLI/配置参考 —— 是位于 [`docs-site/`](./docs-site) 下的一个 Astro 站点，
 并发布于 **[lidge-jun.github.io/opencodex](https://lidge-jun.github.io/opencodex/zh-cn/)**。
 
+维护者 source of truth 位于 [`structure/`](./structure)，历史调查/诊断笔记保留在 [`docs/`](./docs)。
+
 ## 开发
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitkyc08/opencodex",
-  "version": "1.9.3",
+  "version": "1.9.5",
   "description": "Universal provider proxy for OpenAI Codex — use any LLM with Codex CLI/App/SDK",
   "type": "module",
   "main": "src/index.ts",

package/scripts/postinstall.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * postinstall — one-time GitHub-star prompt during `npm install -g opencx`.
+ * postinstall — one-time GitHub-star prompt during `npm install -g @bitkyc08/opencodex`.
  *
  * Behavior:
  *   - TTY-only (skips CI / piped installs)

package/src/cli.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
 import { restoreNativeCodex } from "./codex-inject";
 import { loadConfig, readPid, removePid, writePid } from "./config";
 import { serviceCommand } from "./service";
@@ -35,18 +36,22 @@ Examples:
 async function syncModelsToCodex(port?: number) {
   const config = loadConfig();
   const p = port ?? config.port ?? 10100;
-  const { injectCodexConfig } = await import("./codex-inject");
-  const result = await injectCodexConfig(p, config);
+  let catalogPath: string | null | undefined;
   try {
     const { invalidateCodexModelsCache, syncCatalogModels } = await import("./codex-catalog");
     const cat = await syncCatalogModels(config);
+    catalogPath = existsSync(cat.path) ? cat.path : null;
     if (cat.added > 0) {
       invalidateCodexModelsCache();
       console.log(`   + ${cat.added} models appended to Codex catalog (${cat.path})`);
+    } else if (catalogPath === null) {
+      console.error("catalog sync skipped: no Codex catalog source found; keeping Codex's native catalog.");
     }
   } catch (e) {
     console.error("catalog sync skipped:", e instanceof Error ? e.message : String(e));
   }
+  const { injectCodexConfig } = await import("./codex-inject");
+  const result = await injectCodexConfig(p, config, { catalogPath });
   console.log(result.message);
   return result;
 }

package/src/codex-inject.ts

@@ -1,11 +1,20 @@
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { atomicWriteFile, websocketsEnabled } from "./config";
 import { restoreCodexCatalog } from "./codex-catalog";
-import { CODEX_CONFIG_PATH, CODEX_PROFILE_PATH, DEFAULT_CATALOG_PATH, parseTomlString, readRootTomlString, tomlString } from "./codex-paths";
+import { CODEX_CONFIG_PATH, CODEX_PROFILE_PATH, DEFAULT_CATALOG_PATH, parseTomlString, readRootTomlString, resolveCodexConfigPath, tomlString } from "./codex-paths";
 import type { OcxConfig } from "./types";
 
 const OCX_SECTION_MARKER = "# Auto-injected by opencodex";
 
+export interface InjectCodexOptions {
+  /**
+   * Absolute or CODEX_HOME-relative catalog path to advertise to Codex. Pass `null` only when the
+   * opencodex catalog could not be materialized; Codex will then keep its native catalog instead of
+   * failing on a missing model_catalog_json file.
+   */
+  catalogPath?: string | null;
+}
+
 /**
  * The `[model_providers.opencodex]` TABLE only. A table is position-independent in TOML, so it is
  * safe to append at EOF. The bare root key `model_provider = "opencodex"` is NOT included here —
@@ -83,10 +92,20 @@ function readRootModelCatalogPath(content: string): string | null {
 }
 
 function setRootModelCatalogPath(content: string, catalogPath: string): string {
-  if (readRootModelCatalogPath(content)) return content;
   const lines = content.split("\n");
   const firstTable = lines.findIndex(l => /^\s*\[/.test(l));
   const key = `model_catalog_json = ${tomlString(catalogPath)}`;
+  const rootEnd = firstTable === -1 ? lines.length : firstTable;
+  for (let i = 0; i < rootEnd; i++) {
+    const m = lines[i].match(/^\s*model_catalog_json\s*=\s*("(?:\\.|[^"])*"|'[^']*')\s*$/);
+    if (!m) continue;
+    const existing = parseTomlString(m[1]);
+    if (isOpencodexCatalogPath(existing)) {
+      lines[i] = key;
+      return lines.join("\n");
+    }
+    return content;
+  }
   if (firstTable === -1) {
     return content.replace(/\n+$/, "") + "\n" + key + "\n";
   }
@@ -157,20 +176,30 @@ function stripOpencodexCatalogPath(content: string): string {
     .join("\n");
 }
 
-function buildProfileFile(port: number, catalogPath: string): string {
-  return [
+export function buildProfileFile(port: number, catalogPath?: string | null): string {
+  const lines = [
     "# OpenCodex proxy profile — use with: codex --profile opencodex",
     `# Routes all model requests through the opencodex proxy at localhost:${port}`,
     'model_provider = "opencodex"',
-    `model_catalog_json = ${tomlString(catalogPath)}`,
-    "",
-    "[features]",
-    "fast_mode = true",
-    "",
-  ].join("\n");
+  ];
+  if (catalogPath) lines.push(`model_catalog_json = ${tomlString(catalogPath)}`);
+  lines.push("", "[features]", "fast_mode = true", "");
+  return lines.join("\n");
+}
+
+export function chooseCatalogPathForInjection(content: string, requested?: string | null): string | null {
+  if (requested !== undefined) return requested;
+
+  const existing = readRootModelCatalogPath(content);
+  if (existing) {
+    const resolved = resolveCodexConfigPath(existing);
+    if (!isOpencodexCatalogPath(resolved) || existsSync(resolved)) return existing;
+  }
+
+  return existsSync(DEFAULT_CATALOG_PATH) ? DEFAULT_CATALOG_PATH : null;
 }
 
-export async function injectCodexConfig(port: number, config?: OcxConfig): Promise<{ success: boolean; message: string }> {
+export async function injectCodexConfig(port: number, config?: OcxConfig, options: InjectCodexOptions = {}): Promise<{ success: boolean; message: string }> {
   if (!existsSync(CODEX_CONFIG_PATH)) {
     return { success: false, message: `Codex config not found at ${CODEX_CONFIG_PATH}. Is Codex installed?` };
   }
@@ -189,8 +218,8 @@ export async function injectCodexConfig(port: number, config?: OcxConfig): Promi
   content = normalizeServiceTier(content);
   content = ensureFastModeFeature(content);
 
-  const catalogPath = readRootModelCatalogPath(content) ?? DEFAULT_CATALOG_PATH;
-  content = setRootModelCatalogPath(content, catalogPath);
+  const catalogPath = chooseCatalogPathForInjection(content, options.catalogPath);
+  content = catalogPath ? setRootModelCatalogPath(content, catalogPath) : stripOpencodexCatalogPath(content);
 
   // 1) Root key BEFORE the first table header (must be a global, not nested under a table).
   content = setRootModelProvider(content);
@@ -200,9 +229,13 @@ export async function injectCodexConfig(port: number, config?: OcxConfig): Promi
   writeFileSync(CODEX_CONFIG_PATH, content, "utf-8");
   writeFileSync(CODEX_PROFILE_PATH, buildProfileFile(port, catalogPath), "utf-8");
 
+  const catalogMessage = catalogPath
+    ? `  Codex model catalog: ${catalogPath}\n`
+    : `  Codex model catalog not injected because no opencodex catalog file exists yet.\n`;
   return {
     success: true,
     message: `Injected opencodex as default provider into Codex config.\n` +
+      catalogMessage +
       `  All models now route through opencodex proxy (like OpenRouter).\n` +
       `  OpenAI models (gpt-5.5, etc.) are passed through to OpenAI.\n` +
       `  Custom models route to their configured providers.\n` +