feat(ai-providers): add Codex as a provider (ChatGPT OAuth login and/or CLI integration)

[hyskasoftware]

Summary

Add Codex (OpenAI's terminal coding agent, https://github.com/openai/codex) as a first-class AI provider in HysCode, supporting both sign-in methods available in the Codex CLI:

1. ChatGPT OAuth login — reuse the Codex auth flow (codex login) so users with a ChatGPT plan (Plus/Pro/Business/Edu/Enterprise) can use Codex inside HysCode without an API key.
2. API key / access token — codex login --with-api-key (usage-based billing) and enterprise access tokens (codex login --with-access-token).

Background / Research

Verified 2026-08-01 from https://developers.openai.com/codex/auth and https://developers.openai.com/codex/sdk:

• Install: npm install -g @openai/codex; Windows: irm https://chatgpt.com/codex/install.ps1 | iex.
• Sign-in methods:
  • ChatGPT (OAuth): codex login opens a browser flow; tokens auto-refresh during use. Device-code variant codex login --device-auth (beta) for headless/remote setups.
  • API key: printenv OPENAI_API_KEY | codex login --with-api-key (standard API rates, platform billing).
  • Enterprise access token: printenv CODEX_ACCESS_TOKEN | codex login --with-access-token (ChatGPT Enterprise workspaces).
• Credentials cached in ~/.codex/auth.json (plaintext) or the OS keyring via cli_auth_credentials_store = "file | keyring | auto" in config.toml. The CLI and IDE extension share the same cache; login state can be queried with codex login status.
• Codex SDK (TypeScript): @openai/codex-sdk — new Codex(), codex.startThread(), thread.run(prompt), codex.resumeThread(id). Requires Node.js 18+; it spawns/controls the local Codex runtime. This matches the pattern HysCode already uses for the Claude Agent sidecar.
• The Codex CLI also supports non-interactive execution and can run as an MCP server — alternative integration seams.

Proposed integration (decision needed at implementation time)

Option A — SDK sidecar (recommended, mirrors claude-agent-sidecar)

• New package packages/codex-sidecar bundling @openai/codex-sdk (same shape as packages/claude-agent-sidecar).
• New provider codex in packages/ai-providers/src/providers/codex.ts following ClaudeAgentProvider (packages/ai-providers/src/providers/claude-agent.ts): model catalog + chat() delegating to an injected CodexInvoke transport.
• New Tauri command codex_run in apps/desktop/src-tauri/src/commands/ (mirrors claude_agent.rs) that spawns the sidecar.
• Auth: detect existing ~/.codex/auth.json / keyring; optionally drive codex login from the app for the ChatGPT OAuth flow. No API keys stored in TS/SQLite — use the existing Rust keychain layer.
• Registration in packages/ai-providers/src/registry.ts (initialize + reinitializeProvider).

Option B — Codex CLI as MCP server: connect through the existing packages/mcp-client (stdio transport). Less code, but coarser integration (thread model, streaming, tool routing) and a weaker fit with the AIProvider.chat() contract.

Scope

• Decide Option A vs B (or hybrid: SDK for agentic runs, plain OpenAI provider for chat-only)
• Provider registration + model catalog (Codex models, context window, pricing, tool/streaming flags)
• Auth UX in Settings: API key input and/or "Sign in with ChatGPT" browser flow; honor ~/.codex/auth.json if present
• Sidecar bundling + Tauri command
• Settings tab UI (parity with other providers)
• Tests: model catalog, provider contract (streaming/tools), integration
• Docs: docs/architecture/AI_PROVIDERS.md

Acceptance criteria

• Provider codex appears in the provider picker and works with both ChatGPT login and API key
• Streaming (AsyncIterable<StreamChunk>) and tool calls work through the harness
• No API keys in TypeScript or SQLite (Rust keychain layer only)
• npm run lint && npm run typecheck green
• Rust changes (if any): cargo test, cargo clippy, cargo fmt green
• ./scripts/agent-preflight.sh (or PowerShell equivalent) green
• Docs updated

Notes

• The Codex CLI shares its auth cache with the IDE extension — reading ~/.codex/auth.json must be done carefully (plaintext token file, treated like a password).
• Out of scope for now: Codex cloud / workspace agents, codex app desktop-app integration, Codex security scans.

[hyskasoftware]

🤖 claiming — implementing Option A (SDK sidecar) with full ChatGPT login flow.

[hyskasoftware]

Implementation complete (Option A — SDK sidecar)

Implemented on branch feat/32-codex-provider. No PR opened.

What was built

New package packages/codex-sidecar — Bun-compiled sidecar wrapping @openai/codex-sdk:

• src/index.ts: 1 JSON request on stdin → NDJSON events on stdout; runs one agentic Codex turn per request via codex exec --experimental-json; maps agent_message → text, reasoning → thinking, command_execution/file_change/mcp_tool_call/web_search → tool_use, turn.completed → usage + done, failures → error.
• scripts/copy-codex-cli.mjs: copies the full vendored Codex CLI runtime (@openai/codex-<platform> vendor/<triple>, incl. codex-resources/ and codex-path/rg.exe) into binaries/codex-cli-runtime/ — required because the SDK's createRequire() CLI resolution does not work inside Bun-compiled binaries (codexPathOverride used instead).
• Sandbox decision (confirmed): danger-full-access + approval_policy=never (HysCode harness approvals remain the guardrail).

Rust apps/desktop/src-tauri/src/commands/codex.rs (+ mod.rs, lib.rs):

• codex_run: spawns codex-sidecar next to current_exe(), streams codex:chunk Tauri events; real cancellation — codex_cancel kills the child process via managed CodexRequestState (improvement over the fake cancel of claude_agent_cancel).
• codex_login (spawns bundled codex login browser OAuth flow), codex_login_status (checks ~/.codex/auth.json + keychain), codex_logout.
• API key read from keychain hyscode:codex_api_key with request-provided key taking precedence.

Provider packages/ai-providers/src/providers/codex.ts:

• CodexProvider (id codex, "Codex (Agent)") + CodexInvoke type; registered always when the transport is available (works keyless via ChatGPT login); isConfigured() = API key or cached login.
• Model catalog: gpt-5.6-sol/terra/luna, gpt-5.5, gpt-5.4, gpt-5.4-mini (400K ctx, openai reasoning minimal→xhigh).
• Registry: initialize()/reinitializeProvider() extended.

Desktop wiring:

• tauri-codex-transport.ts (listens codex:chunk, runs in the active workspace root via useFileStore), typed entries in tauri-invoke.ts, init-providers.ts (passes invoke + login status).
• Settings: provider-catalog.ts entry, codex-auth-row.tsx (Sign in with ChatGPT + status + refresh + sign out), ai-tab.tsx placeholder replaced, provider-setup-guide.tsx Codex guide.

Build/bundling: hyscode.iss ships the sidecars + codex-cli-runtime; build-windows.ps1 copies them next to the release exe; npm run copy:sidecars for dev (target/debug); .gitignore updated.

Tests & docs: codex.test.ts (10 tests) + Rust unit tests (5) for the NDJSON parser; docs/architecture/AI_PROVIDERS.md and docs/MODELS_REFERENCE.md updated.

Verification

• npm run typecheck — 11/11 tasks green
• npm run lint — 0 errors
• npm test (ai-providers 31 passed incl. 10 codex; desktop 139 passed)
• cargo test --lib — 46 passed (5 codex), cargo clippy no new warnings, cargo fmt applied
• Sidecar smoke-tested end-to-end (SDK → bundled CLI → OpenAI, correct 401 on invalid key)
• scripts/agent-preflight.ps1 — passed

Notes / known gaps

• NSIS/MSI don't bundle the sidecars (same pre-existing gap as claude-agent — Inno installer covers it; externalBin intentionally not introduced).
• CI doesn't build the sidecar packages (bun not installed there) — installer builds must run locally or CI must be extended (future task).
• Pricing entries for the Codex models are reference values — confirm against the OpenAI API pricing page before release.

[hyskasoftware]

CI gap closed — sidecars now built and shipped in production installers

Follow-up on the known gap ("bun not installed on CI runners"):

Why the gap existed: bun is a global dev tool (not an npm devDependency), CI never ran the sidecar package builds (beforeBuildCommand = desktop tsc -b && vite build, not turbo), and the binaries are gitignored — so the Inno installer published from release.yml silently skipped the sidecar files (skipifsourcedoesntexist).

Fixes implemented (same branch, feat/32-codex-provider):

1. ci.yml — new sidecar job (matrix ubuntu-latest + windows-latest): oven-sh/setup-bun, npm ci, npm run build:sidecars (both packages), smoke test per binary (Invalid JSON input check — no network), upload artifact. Wired into ci-success gate. Runs on every PR/main push.
2. release.yml (Windows job) — setup-bun + npm run build:sidecars after npm ci, then node scripts/copy-sidecars.mjs --target .../target/x86_64-pc-windows-msvc/release before the ISCC step — the published Inno installer now ships claude-agent.exe, codex-sidecar.exe and the full codex-cli-runtime/ directory.
3. package.json (root) — new build:sidecars script (turbo-filtered for both sidecar packages).
4. scripts/copy-sidecars.mjs — now accepts repeatable --target <dir> (defaults to dev debug dirs); used by CI, build-windows.ps1, and dev.
5. scripts/build-windows.ps1 — step 3.5 reuses the shared script; added a bun prerequisite check with a loud warning.

Verified locally: npm run build:sidecars (both compile), copy with --target (incl. recursive codex-cli-runtime/), smoke tests output Invalid JSON input, workflow YAML parses, npm run lint + npm run typecheck green, scripts/agent-preflight.ps1 passed.

Remaining (documented) limitation: NSIS/MSI/Linux/macOS bundles still don't include the sidecars — bundle.externalBin/resources cannot carry the multi-file codex-cli-runtime/ directory and hard-fail the build when globs match nothing (verified in tauri-utils ResourcePaths). The Windows Inno installer is the shipping path and is now complete.

[hyskasoftware]

Design change: Codex CLI is NOT bundled — user installs it on demand

Per maintainer decision, the ~342 MB Codex CLI runtime is no longer shipped with HysCode. Instead:

New behavior (implemented on feat/32-codex-provider):

1. Detection: the sidecar (packages/codex-sidecar) resolves the codex executable at runtime from: system PATH → ~/.codex/bin (official installer location) → legacy vendored dir (pre-unbundling builds, transitional fallback).
2. Install prompt: CodexAuthRow (AI & Providers settings) calls the new codex_cli_status Tauri command on mount. If the CLI is missing, it shows an amber warning with the install command (npm install -g @openai/codex), a copy button, and a "I've installed it — check again" re-check button (which also re-registers the provider).
3. Runtime error: if a chat is attempted without the CLI, the sidecar emits "Codex CLI not found. Install it with: npm install -g @openai/codex ..." as an error chunk in the agent panel.
4. codex login now spawns the user-installed CLI from PATH (was the bundled runtime).
5. Bundling cleanup: copy-codex-cli.mjs deleted (build is now just bun build --compile), codex-cli-runtime removed from hyscode.iss/copy-sidecars.mjs (excluded)/.gitignore, @openai/codex direct dep dropped from the sidecar package, docs updated. Installer now ships only the small sidecars (codex-sidecar.exe ~few MB, claude-agent.exe).
6. CI: sidecar build matrix job + smoke tests unchanged (the Invalid JSON input check runs before CLI detection). Release Inno installer ships the sidecars without the CLI.

Verified: sidecar rebuilt; with codex absent from PATH the sidecar returns the install-instruction error; with garbage JSON it returns Invalid JSON input; new Rust unit test for PATH lookup (find_executable_in_path); cargo test 6/6 codex tests, clippy clean for codex.rs, lint/typecheck green, preflight passed.

UX flow: user activates Codex in Settings → sees "Codex CLI not installed" + command → installs → clicks re-check → signs in with ChatGPT (or pastes API key) → uses Codex.

[hyskasoftware]

Fix: Codex CLI detection now finds the ChatGPT/Codex desktop app bundled CLI

Bug reported: CLI installed (latest) but codex_cli_status / scan button never detected it.

Root cause (verified on the reporter's machine): the actual binary lives at
C:\Users\estev\AppData\Local\OpenAI\Codex\bin\<version-hash>\codex.exe — the Codex CLI bundled with the official ChatGPT/Codex desktop app (v0.146.0-alpha.9.2, matches ~/.codex/version.json). Detection only checked:

• system PATH for codex.exe — fails: the npm global bin dir isn't on PATH, and npm global installs only create .cmd shims (no codex.exe), so the shim was also missed;
• ~/.codex/bin — doesn't exist (official CLI installer not used).

Fix (Rust resolve_codex_cli + sidecar findCodexCli, same order in both):

1. system PATH: codex.exe/codex, plus npm .cmd shims resolved to the real platform binary (<npm-prefix>\node_modules\@openai\codex-win32-x64\vendor\<triple>\bin\codex.exe)
2. ~/.codex/bin (official CLI installer)
3. NEW: %LOCALAPPDATA%\OpenAI\Codex\bin\<version-hash>\codex.exe — ChatGPT/Codex desktop app bundled CLI (Windows)
4. legacy vendored runtime (pre-unbundling builds)

Also fixed a latent bug found by the new unit test: the npm vendor layout is vendor/<triple>/bin/codex.exe (extra bin/ level) — resolve_npm_shim now descends correctly.

Verified:

• sidecar rebuilt: with an invalid API key it now reaches OpenAI and gets a real 401 (invalid_api_key) instead of "Codex CLI not found" — i.e. it finds and spawns the user's CLI
• codex --version on the discovered binary: codex-cli 0.146.0-alpha.9.2
• new Rust unit tests: PATH lookup, one-level-deep dir scan, npm shim resolution (8/8 pass)
• cargo clippy clean for codex.rs, lint/typecheck green, preflight passed

The Settings UI will now show "Codex CLI 0.146.0-alpha.9.2 detected" and the ChatGPT sign-in flow works with the desktop-app CLI.

[hyskasoftware]

Cross-platform closure: sidecars now bundled on ALL platforms + macOS CI/release

Following the review ("does it cover Linux/macOS?"), the remaining gaps were closed on feat/32-codex-provider:

1. bundle.externalBin (tauri.conf.json) — ["binaries/codex-sidecar", "binaries/claude-agent"]. Verified in tauri-utils external_binaries(): only triple-suffixed names are resolved (no plain-name fallback), and tauri-build fails the build if they're missing — so each sidecar build now also emits <name>-<host-triple>(.exe) via the new scripts/tag-sidecar-triple.mjs (host triple derived from process.platform/arch; matches the rustc host triple on the same machine/runner). tauri-build strips the suffix when copying next to the exe, so runtime resolution (current_exe() + plain name) is unchanged. Result: NSIS/MSI (Windows), deb/AppImage (Linux) and macOS .app/.dmg now ship the sidecars — the previously documented limitation is gone.

2. Sidecars are now built by Tauri itself: beforeDevCommand/beforeBuildCommand run npm run build:sidecars first (apps/desktop/package.json → turbo-filtered). Side effect: bun is now required for tauri dev/tauri build (documented in AI_PROVIDERS.md); the manual copy:sidecars step is no longer needed in dev (build.rs copies external bins automatically — verified: cargo check placed claude-agent.exe/codex-sidecar.exe next to the debug exe).

3. CI (ci.yml):

• sidecar matrix now includes macos-latest (build + smoke test + artifact).
• rust job installs Node + bun + npm run build:sidecars before cargo clippy/cargo build (build.rs validates externalBin).

4. Release (release.yml):

• build-linux: added oven-sh/setup-bun (beforeBuildCommand builds sidecars).
• New build-macos job (macos-latest): builds and uploads the .app/.dmg bundle with sidecars; wired into publish-release needs.
• Windows job unchanged (already had setup-bun; tauri build now emits the sidecars into the release dir for the Inno script).

Verified: npm run build:sidecars produces triple-tagged binaries; cargo check passes with externalBin (build.rs resolves + copies them); workflow YAML parses (jobs: create-release, build-windows, build-linux, build-macos, publish-release; publish needs all four); tauri.conf.json valid; lint/typecheck green; preflight passed. Also added *.tsbuildinfo to .gitignore (new package artifact) and restored the claude-agent one.

[hyskasoftware]

Fix: informational tool calls from agentic providers (Codex / Claude Agent) now render

Reported: chat output showed only plain text — no tool call cards, no thinking elements.

Root cause (two parts):

1. Design gap: the harness/UI only ever rendered tool calls the harness itself routes/executes. For agentic sidecar providers (Codex, Claude Agent), tool calls are executed internally by the agent — the harness had no concept of "informational" tool calls: if the chunks arrived, it would try to route shell/apply_patch (unknown tools → errors), and the frontend never rendered them. (In the reporter's specific run the harness recorded "0 tool calls" — the running dev session also had a stale sidecar; the current binary demonstrably emits tool_use events, verified via raw NDJSON.)
2. The thinking path already worked (thinking_delta → ThinkingBlock) once reasoning items arrive.

Implemented:

• ProviderCapabilities.agenticToolExecution flag (ai-providers types.ts); set on CodexProvider and ClaudeAgentProvider.
• Harness: when the provider is agentic, streamed tool calls are treated as informational — emits tool_call_start/tool_call_result (renders ToolCallGroup cards), records them in history + turn summary, and ends the iteration normally instead of routing them.
• New harness unit test covering the informational path (220/221 agent-harness tests pass; ai-providers 31 pass; typecheck + lint green; preflight OK).

After restarting the app, Codex runs show tool call cards (shell/apply_patch/mcp/web_search), the thinking block (when the model emits reasoning items), and the final text.

[hyskasoftware]

Fix: Codex interim messages now render as separate chat messages

Reported: the Codex output appeared as a single paragraph — the agent's working notes ("Vou mapear...", "Base confirmado...", "Rust passou completo...") glued together with the final answer.

Root cause: Codex streams one agent_message item per interim step, but the harness concatenated every text_delta into a single assistantText per iteration → one chat message for the whole turn.

Implemented:

1. New message_boundary StreamChunk (ai-providers types).
2. Sidecar: emits message_boundary lazily before each subsequent non-empty agent_message (no trailing boundary, so the final segment stays the response).
3. Transport: maps the sidecar event to the chunk.
4. Harness: on message_boundary, finalizes the completed segment (adds it to history, emits transcript_message + new assistant_segment_end event, resets the buffers); the final segment flows through the normal iteration-end path (response = last segment).
5. Bridge: assistant_segment_end → flush current message + begin a new assistant message.

Verified: raw NDJSON from the real sidecar shows text → tool_use → message_boundary → text → message_boundary → text(final) → done; new harness test (segment splitting: 2 transcripts + 1 segment_end, response = final segment) — 221 harness tests pass, 10 codex Rust tests pass (new boundary parse test), typecheck/lint green, preflight OK.

After restarting the app, each Codex step appears as its own chat message (with tool cards between them), and the final answer is the last message.

[hyskasoftware]

Follow-up commits (no push): message splitting, official model specs, model selection fix

Three atomic commits on feat/32-codex-provider:

1. 96fe98b fix(codex): render each Codex interim message as a separate chat message
Codex's working notes ("Vou mapear...", "Base confirmado...") were glued with the final answer into one paragraph. Added a message_boundary StreamChunk; the sidecar emits it lazily before each subsequent non-empty agent_message; the harness finalizes each segment (history + transcript_message + new assistant_segment_end event); the bridge starts a new assistant message per segment. Final segment remains the response (no trailing boundary).

2. 2414c0e feat(ai-providers): use official Codex model specs (context window + pricing)
Verified against developers.openai.com/api/docs/models: all 5.6-family + gpt-5.5 + gpt-5.4 are 1.05M context (were 400K) and prices updated (e.g. sol $5/$0.5/$30, terra $2/$0.2/$12, luna $0.2/$0.02/$1.2, gpt-5.4-mini 400K $0.75/$0.075/$4.5 — input/cached/output per 1M tokens). Docs table updated.

3. 3b3ad16 fix(ai-providers): fall back to catalog model when model id is empty
Confirmed the selected model reaches the CLI end-to-end (verified in ~/.codex/sessions rollout: "model":"gpt-5.6-luna"). Found a real edge case: empty modelId (provider switch with no enabled models) was forwarded as model:'', and the Codex SDK treats '' as no --model → the CLI silently used its own default model. Now registry.chat falls back to the provider's first catalog model, and CodexProvider.chat guards params.model || gpt-5.6-sol. Invalid (non-empty) model ids still surface explicit CLI errors.

All checks green: 32 ai-providers tests, 221 agent-harness tests, 10 codex Rust tests, typecheck/lint/preflight.