@koreanhole/opencodex 2.98.0 → 3.0.0

package/AGENTS_INSTALL.md

@@ -1,4 +1,4 @@
-# Installing and Operating the Cline + Gemini CLI Proxy
+# Installing and Operating the OpenCodex ACP Distribution
 
 This file is for an agent that is installing or operating this package, not for
 an agent changing its source code.
@@ -6,11 +6,14 @@ an agent changing its source code.
 ## Install
 
 ```bash
-curl -fsSL https://bun.sh/install | bash
-export PATH="$HOME/.bun/bin:$PATH"
-bun install
+npm install -g @koreanhole/opencodex
 ```
 
+The package installs the pinned original opencodex runtime automatically. Do not
+install or clone the original project separately. The original dashboard,
+clients, providers, lifecycle, service, and update commands remain available
+through the same command.
+
 Use the package CLI rather than invoking internal modules directly:
 
 ```bash
@@ -29,6 +32,10 @@ ocx start
 ocx codex sync
 ```
 
+`ocx start` journals the native Codex config and injects the managed routing.
+`ocx stop` restores it. Use `ocx restore`/`ocx eject` to restore while keeping
+the proxy alive, and `ocx restore back` to re-enable routing.
+
 `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
@@ -57,22 +64,31 @@ or through the documented default path; unrelated Codex settings are not changed
 ```bash
 ocx status
 ocx stop
+ocx restore [--json] [--remove-codex-provider-table]
+ocx restore back [--json]
+ocx eject
 ```
 
-The default listener is loopback-only. A non-loopback bind is refused unless a
-token is configured. There is no dashboard and no management GUI; if a command
-or URL for one is suggested, it is stale and must not be used.
+The adapter gateway is loopback-only and uses a per-run bearer token. The
+original opencodex listener and management surface follow upstream policy,
+including the dashboard and non-loopback authentication rule.
+
+`ocx update` is managed by this distribution. Install the package update with
+`npm install -g @koreanhole/opencodex@latest`; never let the upstream updater
+target `@bitkyc08/opencodex`.
 
 ## Verification
 
 Before claiming the proxy works, run:
 
 ```bash
+bun run verify:upstream
 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
+bun run test:e2e:codex-restore
 ```
 
 Report whether each evidence path used a deterministic ACP fixture or a real

package/README.md

@@ -1,232 +1,141 @@
-# opencodex: Cline + Gemini CLI proxy
+# opencodex: full upstream runtime + Cline and Gemini CLI ACP adapters
 
-`ocx` is a small local proxy that lets OpenAI Codex and Claude Code use a locally
-installed Cline CLI or Gemini CLI as their model transport.
+This distribution keeps the complete original
+[`@bitkyc08/opencodex`](https://github.com/lidge-jun/opencodex) runtime and adds
+locally installed Cline CLI and Gemini CLI as model providers through ACP.
 
-This fork contains only those two local CLI paths. There is no dashboard, desktop
-app, macOS widget, client-config integration writer, account pool, docs site, or
-GitHub Actions workflow.
+The original package is an exact npm dependency. This repository does not copy,
+patch, delete, or rewrite upstream source files. The `ocx` entrypoint loads the
+original CLI in-process and attaches the two CLI adapters through a loopback
+Responses gateway.
 
-## Requirements
+## Install
+
+```bash
+npm install -g @koreanhole/opencodex
+```
+
+That single package installs the pinned upstream runtime as a normal dependency.
+Do not install the original package separately and do not clone either project
+just to run this distribution.
 
-- Bun 1.4.4 (the npm launcher installs the pinned runtime)
-- A locally installed and authenticated Cline CLI, Gemini CLI, or both
+Vendor prerequisites remain separate:
 
 ```bash
 npm install -g cline
 cline auth
 
 npm install -g @google/gemini-cli
-gemini   # configure GEMINI_API_KEY before using it through opencodex
+gemini
 ```
 
-Cline must advertise ACP (`cline --help` includes `--acp`). opencodex uses ACP
-only and fails closed with `cline_acp_unsupported` for older one-shot-only
-builds.
-
-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
-bun install
-bun run src/cli/index.ts provider add cline-cli --set-default
-bun run src/cli/index.ts start
-```
+For third-party clients, use a Gemini Developer API key or Vertex AI GenAI API
+key. Do not use personal Google OAuth for third-party software.
 
-Select the Gemini transport instead with:
+## Start
 
 ```bash
-bun run src/cli/index.ts provider add gemini-cli --set-default
-bun run src/cli/index.ts start
+ocx provider add gemini-cli --set-default
+ocx provider add cline-cli
+ocx start
 ```
 
-The default config is `~/.opencodex/config.json`; set `OPENCODEX_HOME` to isolate
-it. The proxy listens on `http://127.0.0.1:10100/v1` by default. Existing
-Cline-only configs load unchanged and keep Cline as the default.
+The original opencodex commands, dashboard, client integrations, account and
+model management, service lifecycle, and restore behavior remain available
+through the same `ocx` command.
 
-## Codex
+The managed provider rows appear as `gemini-cli/...` and `cline-cli/...`.
+Their local model discovery, reasoning metadata, session continuation, and tool
+intent behavior come from this distribution's ACP implementation.
 
-Use a Responses provider pointed at the proxy:
+## Commands
 
-```toml
-model = "gemini-cli/gemini-3.5-flash-lite"
-model_provider = "opencodex"
+Adapter-specific compatibility commands:
 
-[model_providers.opencodex]
-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"
+```bash
+ocx login cline-cli [--json] [--no-wait]
+ocx provider add <cline-cli|gemini-cli> [--set-default]
+ocx provider use <cline-cli|gemini-cli>
+ocx provider list [--json]
+ocx adapter detach
 ```
 
-The model list is live. Cline ACP models are exposed as `cline-cli/<encoded-id>`;
-Gemini ACP models are exposed as `gemini-cli/<encoded-id>`. Each provider keeps a
-`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:
+All other commands are delegated to the immutable upstream CLI. Examples:
 
 ```bash
-bun run src/cli/index.ts codex sync
+ocx start
+ocx status
+ocx stop
+ocx restore
+ocx sync
+ocx service install
+ocx gui
+ocx doctor
 ```
 
-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.
+`ocx adapter detach` removes only the two managed provider rows or restores
+their previous values from the mode-0600 journal.
 
-Codex 0.165.0 can use the Responses WebSocket transport when the provider sets
-`supports_websockets = true` and the process is started with
-`--enable responses_websockets`. opencodex accepts the WebSocket on
-`/v1/responses`, handles the `generate=false` warmup, and maps the following
-`previous_response_id` onto the stored Gemini session. HTTP remains the fallback.
+## Upstream updates
 
-Gemini context capacity, prompt modalities, and session-load support are
-discovered from the installed ACP agent at runtime; the proxy does not hardcode a
-model context window. A reusable Codex conversation uses
-`previous_response_id`, `prompt_cache_key`, or a documented conversation header
-to load the vendor session and send only the new input. Tool-use turns fall back
-to bounded replay because the vendor session is cancelled when a tool intent is
-captured.
+The dependency is pinned exactly:
 
-## Claude Code
-
-```bash
-ANTHROPIC_BASE_URL=http://127.0.0.1:10100 \
-ANTHROPIC_AUTH_TOKEN=local \
-ANTHROPIC_MODEL=gemini-cli/gemini-3.5-flash-lite \
-claude
+```json
+{
+  "@bitkyc08/opencodex": "2.94.0"
+}
 ```
 
-Use a `cline-cli/...` model to route the same Messages surface to Cline.
+To adopt an upstream release:
 
-## Security boundary
+1. Change only the exact dependency version and refresh the lockfile.
+2. Run `bun run verify:upstream`.
+3. Run `bun run typecheck`, `bun test tests`, `bun run test:e2e`, and
+   `bun run test:e2e:gemini`.
+4. Accept the update only when every gate passes.
 
-- Neither Cline nor Gemini receives filesystem or terminal capability from the proxy.
-- Cline turns use a request-scoped Cline home with built-in/plugin tools, hooks,
-  telemetry, updates, and automatic approval disabled. The real vendor provider
-  store is immutable; a mode-0600 copy inside the staged home lets the vendor CLI
-  refresh auth state and is removed after the turn.
-- Gemini native tools are removed by a per-turn deny policy; permission requests
-  are cancelled, and no ACP filesystem/terminal client capabilities are advertised.
-  User MCP servers, extensions, skills, and hooks are disabled for the session; only
-  the isolated `opencodex` MCP catalog can receive a client tool call.
-- Gemini runs with a staged `GEMINI_CLI_HOME` under opencodex control; only the
-  minimum vendor auth files are linked from the real home, and staged session
-  state is bounded and reclaimed.
-- Declared client tools are exposed only through a request-scoped MCP process that
-  records bounded intent and never executes; Codex owns approval and execution.
-- Vendor credentials remain in the vendor's real home or authenticated
-  environment. Cline's request-scoped copy is never logged or persisted beyond
-  the turn. The proxy stores no vendor token.
-- Request-path traffic never starts an interactive login.
-- The listener is loopback-only by default; a non-loopback listener requires an
-  explicit API token.
-- Image input is forwarded only when the selected Gemini model and ACP agent
-  advertise image capability; video and audio input are rejected before a vendor
-  process starts.
+No patch series or upstream source tree is maintained in this repository.
 
-## Commands
+`ocx update` and `ocx system update` are intercepted because the upstream
+updater is hardcoded to the original package name. Update this distribution with:
 
 ```bash
-bun run src/cli/index.ts login cline-cli [--json] [--no-wait]
-bun run src/cli/index.ts provider add <cline-cli|gemini-cli> [--set-default]
-bun run src/cli/index.ts provider use <cline-cli|gemini-cli>
-bun run src/cli/index.ts provider list [--json]
-bun run src/cli/index.ts start [--port 10100] [--host 127.0.0.1]
-bun run src/cli/index.ts status [--json]
-bun run src/cli/index.ts stop [--json]
+npm install -g @koreanhole/opencodex@latest
 ```
 
-Gemini has no proxy login command. Authenticate it through the official CLI
-(`gemini` or its API-key configuration); `ocx login gemini-cli` returns that
-guidance without prompting for or accepting a credential.
+Automatic upstream update checks are disabled for the delegated runtime.
+
+## Security boundary
+
+- Neither Cline nor Gemini receives filesystem or terminal capability from the
+  proxy.
+- Cline runs with request-scoped, mode-0600 settings. Its built-in tools, user
+  MCP servers, hooks, plugins, telemetry, updates, and self-approval are disabled.
+- Gemini native tools are denied, user extensions/MCP/skills/hooks are disabled,
+  and only the isolated request-scoped MCP catalog can receive tool intent.
+- Tool intent is returned to Codex for approval and execution.
+- Vendor credentials stay in vendor homes or authenticated environments. The
+  proxy does not store or log vendor tokens.
+- The adapter gateway binds `127.0.0.1` only and uses a per-run bearer token.
+- Request bodies, API keys, bearer tokens, and full vendor diagnostics are never
+  logged.
 
 ## Tests
 
 ```bash
+bun run verify:upstream
 bun run typecheck
 bun test tests
 bun run test:e2e
 bun run test:e2e:gemini
-bun run test:e2e:gemini-tool
-bun run test:e2e:gemini-multiturn
-bun run test:e2e:gemini-previous-response
-bun run test:e2e:gemini-websocket
-bun run test:e2e:gemini-websocket-tool
-bun run test:e2e:gemini-reasoning
 bun run privacy:scan
 bun run structure:check
 ```
 
-The deterministic suite uses ACP fixtures for both providers and fails rather than
-skipping missing fixture/process behavior. `test:e2e` covers Cline HTTP behavior.
-
-`test:e2e:gemini` is the one-completion text gate. It starts an isolated
-opencodex listener, discovers the real authenticated Gemini roster, chooses an
-advertised Flash Lite model, writes an isolated `CODEX_HOME`, runs one real Codex
-prompt, and asserts the response marker, observed model, and child cleanup.
-
-`test:e2e:gemini-tool` exercises the two-completion tool loop: Gemini requests
-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-multiturn` starts a persisted real Codex session, resumes it with
-`codex exec resume`, and asserts that the proxy loads the Gemini session and
-sends only the new turn. Codex 0.165.0 sends `prompt_cache_key` for this path.
-
-`test:e2e:gemini-previous-response` sends a direct Responses continuation with
-`previous_response_id` and verifies that the proxy loads the stored Gemini
-session and sends only the new input.
-
-`test:e2e:gemini-websocket` and `test:e2e:gemini-websocket-tool` enable Codex's
-actual WebSocket transport with `supports_websockets = true` and
-`--enable responses_websockets`. They verify the `generate=false` warmup, the
-real request's non-empty `previous_response_id`, and the WebSocket tool loop.
-
-`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
-
-- **Cline not found**: install `cline` and verify `cline --help` works.
-- **Cline authentication required**: run `ocx login cline-cli`, then retry.
-- **Cline ACP unavailable**: opencodex no longer falls back to the one-shot JSON
-  path. Upgrade Cline so `cline --help` advertises `--acp`, or set
-  `OPENCODEX_CLINE_ACP=1`; otherwise requests fail with
-  `cline_acp_unsupported`.
-- **Gemini not found**: install it and verify `gemini --help` works, or set
-  `GEMINI_BIN_PATH`.
-- **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.
-
-## License
-
-MIT. See [LICENSE](LICENSE).
+`test:e2e:gemini` starts the original runtime and the adapter gateway, then uses
+a real Codex client and a real authenticated Gemini CLI. It fails, not skips, on
+a missing binary, authentication, Flash Lite model, response marker, or child
+cleanup assertion.
+
+Optional overrides are `CLINE_BIN_PATH`, `GEMINI_BIN_PATH`, and
+`CODEX_BIN_PATH`.

package/bin/ocx.mjs

@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";
 
 const require = createRequire(import.meta.url);
 const here = dirname(fileURLToPath(import.meta.url));
-const cli = join(here, "..", "src", "cli", "index.ts");
+const cli = join(here, "..", "src", "cli", "entry.ts");
 
 function bundledBun() {
   try {

package/bin/package-main.mjs

@@ -1,3 +1,7 @@
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
 export const packageName = "@koreanhole/opencodex";
 export const cliCommand = "ocx";
 
@@ -5,5 +9,11 @@ export async function loadBunApi() {
   if (typeof Bun === "undefined") {
     throw new Error("The opencodex programmatic API requires Bun. Use `ocx` for the CLI.");
   }
-  return import("../src/index.ts");
+  const require = createRequire(import.meta.url);
+  const upstreamPackage = require.resolve("@bitkyc08/opencodex/package.json");
+  const upstream = await import(
+    pathToFileURL(join(dirname(upstreamPackage), "src", "index.ts")).href
+  );
+  const local = await import("../src/index.ts");
+  return { ...upstream, ...local, upstream, local };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@koreanhole/opencodex",
-  "version": "2.98.0",
-  "description": "Cline and Gemini CLI provider proxy for OpenAI Codex and Claude Code",
+  "version": "3.0.0",
+  "description": "Full opencodex runtime with Cline and Gemini CLI ACP provider adapters",
   "type": "module",
   "main": "./bin/package-main.mjs",
   "exports": {
@@ -26,8 +26,8 @@
     "node": ">=18"
   },
   "scripts": {
-    "dev": "bun run src/cli/index.ts start",
-    "start": "bun run src/cli/index.ts start",
+    "dev": "bun run src/cli/entry.ts start",
+    "start": "bun run src/cli/entry.ts start",
     "test": "bun test tests",
     "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\"",
@@ -37,14 +37,17 @@
     "test:e2e:gemini-websocket": "bun test ./tests/e2e/gemini-codex.live.ts -t \"runs a live Codex WebSocket turn\"",
     "test:e2e:gemini-websocket-tool": "bun test ./tests/e2e/gemini-codex.live.ts -t \"runs a live Codex WebSocket tool loop\"",
     "test:e2e:gemini-reasoning": "bun test ./tests/e2e/gemini-reasoning.live.ts",
+    "test:e2e:codex-restore": "bun test ./tests/e2e/codex-restore.live.ts",
     "typecheck": "bun check --no-script --noEmit",
     "privacy:scan": "bun scripts/privacy-scan.ts",
     "structure:check": "bun scripts/structure-check.ts",
-    "prepush": "bun run typecheck && bun run test && bun run privacy:scan && bun run structure:check",
-    "prepublishOnly": "bun run typecheck && bun run test"
+    "verify:upstream": "bun scripts/verify-upstream.ts",
+    "prepush": "bun run verify:upstream && bun run typecheck && bun run test && bun run privacy:scan && bun run structure:check",
+    "prepublishOnly": "bun run verify:upstream && bun run typecheck && bun run test"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "1.9.0",
+    "@bitkyc08/opencodex": "2.94.0",
     "@modelcontextprotocol/sdk": "^1.32.1",
     "bun": "1.4.4"
   },