feat(desktop): add Codex (GPT-5.5) as a local-CLI harness (#492)

## What

Adds **Codex (GPT-5.5)** as a third pluggable agent harness in Freebuff
Desktop, alongside Claude Code and the hosted Freebuff agent. It drives
the user's **local, ChatGPT-authenticated Codex CLI** via
`@openai/codex-sdk` — reusing `~/.codex` login with no key plumbing,
exactly like the Claude Code harness reuses the Anthropic subscription.


## How it works

- **Model picker** gains a CODEX group (GPT-5.5). The per-thread pick
persists (schema **v16** `codex_model`). The `-codex` model variants are
rejected because they 400 on ChatGPT-account auth.
- **Rendering**: Codex's JSONL events fold into the shared `parts` model
— reasoning, assistant messages, and tool calls (`command_execution` /
`file_change` / `mcp_tool_call` / `web_search`) render in stream order
with friendly labels (`formatTool`).
- **Auth**: reuses `~/.codex/auth.json` (strips
`OPENAI_API_KEY`/`CODEX_API_KEY` so the subscription login wins).
Signed-out → a `codex-auth` recovery card (Open Terminal + copy `codex
login`), mirroring the Claude Code card.
- **Freebuff custom tools** (`suggest_prompts` / `write_doc` /
`browser_check`): Codex has no in-process tool transport, so each turn
hosts a tiny **dependency-free localhost streamable-HTTP MCP server**
bound to that turn's `toolDeps`, wired via `config.mcp_servers`. (The
MCP SDK is deliberately avoided — the monorepo pins zod v4 and the SDK
needs v3.)
- **Not bundled**: the ~240 MB platform binary is too heavy to ship, so
we use the user's **installed** codex. When none is available, the
picker shows the Codex agent **disabled** ("Not installed", with an
install tooltip) and the agent route rejects the pick.
`FREEBUFF_CODEX_DISABLED=1` is an ops/test kill-switch.

## Autonomy

Runs with `sandbox = danger-full-access` + `approval = never` — the
analog of Claude Code's `bypassPermissions` (each thread is an isolated
worktree). `workspace-write` invokes Codex's own macOS seatbelt, which
SIGKILLs under nested sandboxing.

## Verification

Driven end-to-end against a real, isolated orchestrator (fresh `HOME`,
scratch repo):
- ✅ CODEX picker group renders; GPT-5.5 selectable & persists; invalid
model rejected (400).
- ✅ A real turn ran on Codex — tool calls + assistant messages render in
order; file created.
- ✅ `suggest_prompts` MCP tool round-trips → suggestion parked in the
thread queue.
- ✅ Resume carries context across turns.
- ✅ Signed-out CLI → `codex-auth` recovery card.
- ✅ Unavailable → Codex option `disabled=True` + route 400; available →
`disabled=False` + 200.
- ✅ **226 desktop tests pass**; both tsconfigs typecheck; UI builds.

## Notes / follow-ups

- Adds `@openai/codex-sdk` (which pulls the platform `@openai/codex`
binary in dev).
- In dev, `@openai/codex` is in `node_modules` so the SDK self-resolves;
a packaged build with no installed codex → the disabled flow applies.
- `scripts/codex-smoke.ts` added as a dev harness (mirrors
`claude-smoke.ts`).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: jahooma

bun.lock

@@ -0,0 +1,114 @@
+# Codex in Freebuff Desktop
+
+Codex is one of the three pluggable agent **harnesses** a thread can run on
+(alongside the hosted Freebuff agent and Claude Code). It drives the user's
+**local, ChatGPT-authenticated Codex CLI** via `@openai/codex-sdk`, reusing their
+`~/.codex` login with no API-key plumbing — exactly how the Claude Code harness
+reuses the Anthropic subscription.
+
+Code: `src/app/agents/codex-harness.ts` (+ `freebuff-mcp-server.ts`,
+`src/core/codex-models.ts`). This doc is the "why", not a line-by-line tour.
+
+## How it works
+
+- **Auth** — the SDK spawns `codex exec`, which reads the credentials
+  `codex login` stored in `~/.codex/auth.json`. This only works when **no**
+  `OPENAI_API_KEY` / `CODEX_API_KEY` is set (a key overrides the subscription
+  login), so `codexEnv()` strips both before spawning. `CODEX_HOME` relocates the
+  config dir (used in tests: fresh `HOME` for isolation + real `CODEX_HOME`).
+- **Model** — GPT-5.5 (`src/core/codex-models.ts`), persisted per-thread
+  (`schema v16`, `codex_model`). The `-codex` variants (e.g. `gpt-5.5-codex`) are
+  deliberately **not** offered: they `400` on a ChatGPT-account login, which is
+  this harness's only auth path.
+- **Streaming** — the SDK surfaces Codex's JSONL as typed `ThreadEvent`s. Codex
+  buffers a whole reasoning block / assistant message and emits it once at
+  `item.completed` (no token-level deltas like Claude Code). `consumeCodexStream`
+  folds these into the shared parts model: reasoning → `onReasoning`,
+  agent_message → `onText`, and command/file/mcp/web/todo items → `tool_call`
+  (command & mcp emit on `item.started` so the call shows as it's dispatched; the
+  rest on `item.completed`). MCP calls surface as `mcp__<server>__<tool>` so the
+  UI's `formatTool` strips the prefix like it does for Claude Code.
+- **Resume** — the `thread.started` event's `thread_id` is carried back as the
+  harness state, so the next turn `resumeThread(id)` keeps context/caching.
+- **Autonomy** — `sandboxMode: 'danger-full-access'` + `approvalPolicy: 'never'`,
+  the direct analog of the Claude Code harness's `bypassPermissions` (see the
+  sandbox trade-off below).
+- **Signed out** — an unauthenticated CLI throws `CodexAuthError`, which the
+  engine renders as a `codex-auth` recovery card ("Open Terminal" + copy
+  `codex login`), mirroring the Claude Code auth card.
+
+## Custom Freebuff tools over a local MCP server
+
+The Codebuff/Claude harnesses expose `suggest_prompts` / `write_doc` /
+`browser_check` to the model. Codex has **no in-process tool transport**, so each
+turn stands up a tiny localhost **streamable-HTTP MCP server**
+(`freebuff-mcp-server.ts`) whose handlers close over that turn's `ThreadToolDeps`,
+and points Codex at it via `config.mcp_servers.freebuff.url`. The server is
+hand-rolled (a small JSON-RPC subset: `initialize` / `tools/list` / `tools/call`
+/ notifications) rather than using `@modelcontextprotocol/sdk` — see the zod
+trade-off below.
+
+**Access control.** Even on 127.0.0.1 for a few seconds on a random port, the
+handlers have side effects (write files, launch a browser), so every request must
+carry a **per-turn bearer token** (minted per turn, handed to Codex via
+`mcp_servers.freebuff.http_headers`) **and** a loopback `Host` header. This blocks
+any stray local process or DNS-rebinding webpage from reaching the tools during
+the turn's window.
+
+## Availability (we don't bundle Codex)
+
+The `codex` binary is ~240 MB/platform — too heavy to ship in the installer. So
+the packaged app uses the user's **installed** `codex`:
+
+- `resolveCodexExecutable()` — `FREEBUFF_CODEX_PATH` override → the SDK's own
+  bundled binary when `@openai/codex` is on disk (dev) → the user's installed
+  codex (packaged, no `node_modules`).
+- When no codex is available, `isCodexAvailable()` is false and the engine marks
+  the Codex option **disabled** in the picker (greyed, "Not installed", with an
+  install tooltip); the `/api/thread/{id}/agent` route also `400`s a Codex pick.
+- Env knobs: `FREEBUFF_CODEX_PATH` (force a specific binary),
+  `FREEBUFF_CODEX_DISABLED=1` (force the agent off), `CODEX_HOME` (config dir).
+
+## Trade-offs we hit (and how we resolved them)
+
+| Decision | Options | Chose | Why / cost |
+|---|---|---|---|
+| **Binary distribution** | bundle (+240 MB) · use installed codex · download-on-demand | **installed codex** | Small installer; but only works if the user has codex (hence the disabled picker state) and runs *their* version (protocol-drift risk). Download-on-demand is the "best of both" follow-up. |
+| **Sandbox** | `workspace-write` (seatbelt, worktree-confined) · `danger-full-access` (no sandbox) | **`danger-full-access`** | Matches Claude Code's `bypassPermissions`, and `workspace-write`'s macOS seatbelt gets SIGKILLed when Freebuff runs inside a nested sandbox (CI/dev). Cost: no OS confinement — a prompt injection could act outside the worktree. Revisit: prefer `workspace-write` on real machines with a full-access fallback. |
+| **CLI wrapper** | `@openai/codex-sdk` · raw-spawn `codex exec --experimental-json` | **SDK** (for now) | Insulates us from the *experimental* JSON flag/schema churn and keeps parity with Claude Code (also SDK-wrapped). But the SDK is a thin wrapper and `consumeCodexStream` is already SDK-agnostic, so dropping it later is contained. Cost: a heavy dev-only dependency. |
+| **MCP server** | `@modelcontextprotocol/sdk` · hand-rolled JSON-RPC | **hand-rolled** | The monorepo pins zod to **v4** (root `overrides`); the MCP SDK needs zod **v3** and its internals throw under v4. Hand-rolling the small subset Codex uses also drops a dependency. |
+| **Model id** | `gpt-5.5` · `gpt-5.5-codex` | **`gpt-5.5`** | The `-codex` variants `400` on ChatGPT-account auth. |
+
+## Future ideas
+
+- **Download-on-demand binary** — fetch the SDK-pinned `@openai/codex-<platform>`
+  into app-support on first Codex turn, cache it, and point `codexPathOverride`
+  there. Gives version consistency (kills the protocol-drift risk) and works
+  without an installed codex — all without a bigger installer. Caveats: a one-time
+  ~80–100 MB download, first-turn latency, and macOS quarantine/Gatekeeper on the
+  fetched binary.
+- **Prefer `workspace-write`** on end-user machines (OS-confined to the worktree),
+  falling back to `danger-full-access` only where the seatbelt can't run.
+- **Drop the SDK**, spawning `codex exec --experimental-json` directly — removes
+  the heavy dependency and the dev-vs-packaged binary-resolution split, since the
+  stream consumer is already decoupled. Weigh against owning the experimental CLI
+  surface.
+- **Refresh availability** without an app restart (a "Recheck" affordance), so
+  installing codex mid-session enables the picker.
+- **Token-level streaming** if/when Codex's JSON mode exposes deltas (today
+  reasoning/messages arrive buffered at `item.completed`).
+- **Multimodal** — forward attached images as SDK content instead of relying on
+  Codex reading the referenced path.
+- **Quieter auth failures** — suppress the item-level `401` transport note that
+  currently prints just before the sign-in recovery card.
+
+## Testing
+
+- Unit: `codex-harness.test.ts` (stream mapping, error/auth classification, env,
+  resolver, availability), `freebuff-mcp-server.test.ts` (JSON-RPC + the
+  token/Host access control).
+- Manual: `scripts/codex-smoke.ts` runs one real Codex turn against the local
+  login (mirrors `scripts/claude-smoke.ts`).
+- End-to-end via the HTTP/SSE API: see `docs/desktop/e2e-testing.md` — set
+  `CODEX_HOME=~/.codex` alongside a fresh `HOME` so the harness reuses the real
+  login while the orchestrator stays isolated.

freebuff-desktop/docs/codex.md

@@ -35,6 +35,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.195",
     "@codebuff/sdk": "workspace:*",
+    "@openai/codex-sdk": "^0.142.5",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",

freebuff-desktop/package.json

@@ -0,0 +1,65 @@
+/**
+ * Smoke-test the Codex harness against the user's LOCAL authenticated Codex CLI:
+ * spin up a temp git repo, run one turn asking it to create a file, and verify
+ * the file landed. Proves auth (ChatGPT/OpenAI login) + model (GPT-5.5) + real
+ * edits work end-to-end before wiring through the full desktop UI.
+ *
+ *   bun freebuff-desktop/scripts/codex-smoke.ts
+ */
+
+import { execSync } from 'child_process'
+import { existsSync, mkdtempSync, readFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+import { CodexHarness } from '../src/app/agents/codex-harness'
+
+const root = mkdtempSync(join(tmpdir(), 'codex-smoke-'))
+execSync('git init -q && git commit -q --allow-empty -m init', { cwd: root, shell: '/bin/bash' })
+console.log('repo:', root)
+
+const harness = new CodexHarness()
+let text = ''
+const tools: string[] = []
+
+const t0 = Date.now()
+const result = await harness.runTurn(
+  {
+    prompt:
+      'Create a file named hello.txt whose entire contents are exactly the line: hello world. Then stop.',
+    cwd: root,
+    toolDeps: {
+      onSuggest: () => {},
+      onWriteDoc: () => ({ ok: true }),
+      onBrowserCheck: async () =>
+        ({ loaded: false, rendered: false, title: '', renderDetail: '', consoleErrors: [], pageErrors: [] }) as any,
+    },
+    previousState: undefined,
+    abort: new AbortController(),
+  },
+  {
+    onText: (c) => {
+      text += c
+      process.stdout.write(c)
+    },
+    onReasoning: () => {},
+    onEvent: (ev) => {
+      if (ev.type === 'tool_call') {
+        tools.push(ev.toolName as string)
+        console.log(`\n  [tool] ${ev.toolName} ${JSON.stringify(ev.input).slice(0, 120)}`)
+      }
+      if (ev.type === 'finish') console.log('\n  [finish]')
+    },
+    drainSteering: () => [],
+  },
+)
+
+const file = join(root, 'hello.txt')
+const ok = existsSync(file)
+console.log('\n\n— RESULT —')
+console.log('tools used:', tools.join(', ') || '(none)')
+console.log('thread id:', (result.state as any)?.threadId ?? '(none)')
+console.log('elapsed:', ((Date.now() - t0) / 1000).toFixed(1) + 's')
+console.log('hello.txt exists:', ok)
+if (ok) console.log('hello.txt contents:', JSON.stringify(readFileSync(file, 'utf8')))
+process.exit(ok ? 0 : 1)