@koreanhole/opencodex 2.95.10 → 2.97.0

package/AGENTS_INSTALL.md

@@ -1,4 +1,4 @@
-# Installing and Operating the Cline-only Proxy
+# Installing and Operating the Cline + Gemini CLI Proxy
 
 This file is for an agent that is installing or operating this package, not for
 an agent changing its source code.
@@ -19,14 +19,36 @@ ocx provider add cline-cli --set-default
 ocx start
 ```
 
+To use Gemini instead, authenticate it through its official CLI and select the
+provider:
+
+```bash
+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 CLI sign-in. Do not copy vendor tokens into
-  config, environment files, logs, prompts, or package content.
+- Use the operator's existing Cline or Gemini CLI sign-in. Do not copy vendor
+  tokens into config, environment files, logs, prompts, or package content.
 - Do not authenticate on a request path. If Cline reports `auth_required`, stop
   and ask the operator to run `ocx login cline-cli`.
 - Do not edit the operator's real Cline provider store unless the operator asks.
-- The proxy writes only under `$OPENCODEX_HOME` (default `~/.opencodex`).
+- Do not import or replay Gemini OAuth/API-key material; the Gemini CLI remains
+  the authentication authority.
+- 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
 
@@ -46,7 +68,12 @@ Before claiming the proxy works, run:
 ```bash
 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 the evidence used the deterministic ACP fixture or a real Cline
-binary/account. Never report a skipped or synthetic run as a real login.
+Report whether each evidence path used a deterministic ACP fixture or a real
+vendor binary/account. The Gemini command above is a hard live gate: missing
+binaries, authentication, a Flash Lite model, or cleanup evidence must fail.
+Never report a skipped or synthetic run as a real login.

package/README.md

@@ -1,112 +1,181 @@
-# opencodex: Cline-only proxy
+# opencodex: Cline + Gemini CLI proxy
 
 `ocx` is a small local proxy that lets OpenAI Codex and Claude Code use a locally
-installed Cline CLI as their model transport.
+installed Cline CLI or Gemini CLI as their model transport.
 
-This fork contains only that path. There is no dashboard, desktop app, macOS
-widget, client-config integration writer, multi-provider router, account pool, or
+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.
 
 ## Requirements
 
 - Bun 1.4.4 (the npm launcher installs the pinned runtime)
-- A locally installed and authenticated `cline` CLI
+- A locally installed and authenticated Cline CLI, Gemini CLI, or both
 
 ```bash
 npm install -g cline
 cline auth
+
+npm install -g @google/gemini-cli
+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
 bun install
-bun run src/cli/index.ts login cline-cli
 bun run src/cli/index.ts provider add cline-cli --set-default
 bun run src/cli/index.ts start
 ```
 
+Select the Gemini transport instead with:
+
+```bash
+bun run src/cli/index.ts provider add gemini-cli --set-default
+bun run src/cli/index.ts 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.
+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.
 
 ## Codex
 
 Use a Responses provider pointed at the proxy:
 
 ```toml
-model = "cline-cli/default"
+model = "gemini-cli/gemini-3.5-flash-lite"
 model_provider = "opencodex"
 
 [model_providers.opencodex]
-name = "opencodex (Cline CLI)"
+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's ACP session supplies native model ids, exposed as
-`cline-cli/<encoded-id>`. `cline-cli/default` always remains available.
+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:
+
+```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
 ANTHROPIC_BASE_URL=http://127.0.0.1:10100 \
 ANTHROPIC_AUTH_TOKEN=local \
-ANTHROPIC_MODEL=cline-cli/default \
+ANTHROPIC_MODEL=gemini-cli/gemini-3.5-flash-lite \
 claude
 ```
 
-The proxy translates `/v1/messages` to the same Cline turn and returns Anthropic
-JSON or SSE.
+Use a `cline-cli/...` model to route the same Messages surface to Cline.
 
 ## Security boundary
 
-- Cline receives no filesystem or terminal capability from the proxy.
-- Cline permission requests are denied; tool intent is returned to Codex for its
-  own approval and execution.
-- Vendor credentials remain in Cline's real home. The proxy stores no Cline token.
+- Neither Cline nor Gemini receives filesystem or terminal capability from the proxy.
+- 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.
+- 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. 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, video, and audio input are rejected before a Cline process starts.
+- Image, video, and audio input are rejected before a vendor process starts.
 
 ## Commands
 
 ```bash
 bun run src/cli/index.ts login cline-cli [--json] [--no-wait]
-bun run src/cli/index.ts provider add cline-cli [--set-default]
-bun run src/cli/index.ts provider use cline-cli
+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]
 ```
 
+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.
+
 ## Tests
 
 ```bash
 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-reasoning
 bun run privacy:scan
 bun run structure:check
 ```
 
-The end-to-end test starts the real HTTP server, uses the deterministic ACP
-fixture, exercises model discovery, buffered and streamed Responses, Anthropic
-Messages, a native model selection, and child-process cleanup. It fails rather
-than skipping when any part is missing.
+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-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.
 
-To exercise a real Cline binary, set `CLINE_BIN_PATH` to its executable and run
-the same test. A real account is not required by the automated fixture; never
-describe synthetic evidence as a real-account verification.
+Optional overrides are `CLINE_BIN_PATH`, `GEMINI_BIN_PATH`, and `CODEX_BIN_PATH`.
 
 ## Troubleshooting
 
 - **Cline not found**: install `cline` and verify `cline --help` works.
-- **Authentication required**: run `ocx login cline-cli`, then retry the turn.
-- **ACP unavailable**: the adapter falls back to the one-shot JSON path when the
-  model is `default`; native model selection requires ACP.
+- **Cline authentication required**: run `ocx login cline-cli`, then retry.
+- **Cline ACP unavailable**: the adapter falls back to the one-shot JSON path when
+  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 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,7 +1,7 @@
 {
   "name": "@koreanhole/opencodex",
-  "version": "2.95.10",
-  "description": "Cline CLI-only provider proxy for OpenAI Codex and Claude Code",
+  "version": "2.97.0",
+  "description": "Cline and Gemini CLI provider proxy for OpenAI Codex and Claude Code",
   "type": "module",
   "main": "./bin/package-main.mjs",
   "exports": {
@@ -30,6 +30,9 @@
     "start": "bun run src/cli/index.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\"",
+    "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",
@@ -47,6 +50,7 @@
   },
   "keywords": [
     "cline",
+    "gemini",
     "codex",
     "claude-code",
     "proxy",