wisp-agents 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-17
+
+### Added
+
+- Codex (`codex exec --json`), opencode (`opencode run --format json`) and Cursor CLI (`cursor-agent -p`) adapters, next to Claude Code. Pick the harness and model together in the launcher, or pass `--agent` on the CLI.
+- One harness · model picker in the launcher: harnesses (with logos) on the left, that harness's models on the right, searchable and grouped by provider for opencode. The model is remembered per harness. opencode and Cursor model lists are read from the CLIs themselves.
+- `ask_user` works in Codex and opencode (injected MCP server). Cursor has no flag to inject one, so Cursor agents ask with a `question` block instead.
+- Diffs for harnesses that only report "file changed" are taken against the file as it was when the turn started (`git stash create`), or the agent's own before/after content when available.
+- Windows: harness CLIs installed through npm (`.cmd` shims) and PowerShell-only installs now start. npm shims run as `node <script>`, so arguments reach the CLI unchanged. Stopping a run ends the whole process tree (`taskkill /T`).
+- Take over on Windows (Windows Terminal, PowerShell, Command Prompt) and on more Linux terminals (GNOME Terminal, Konsole, Xfce Terminal, Alacritty, xterm). The settings list only shows terminals for your OS.
+- Test suite (`npm test`) and CI on Linux, macOS, and Windows, plus `npm run test:real` to smoke-test the real CLIs.
+- Images an agent shows are copied into `~/.wisp/shots/<session>/` when the turn finishes, so screenshots saved to `/tmp` survive reboots. Existing sessions are backfilled on startup if their files still exist. Deleting a session deletes its copies.
+- Command palette (`⌘K` / `Ctrl+K`, or the Search button in the top bar): fuzzy search across sessions (title, project, summary, agent), project filters, global actions, and actions on the focused session.
+- Archive tasks: right-click a task (or press `A`) to archive it. Archived tasks move to a collapsed *Archived* section and keep their state; a new question or turn brings them back.
+- Right-click menus on tasks (open, rename, mark done, archive, delete), project chips (remove) and queued follow-ups (cancel).
+- `⌘L` / `Ctrl+L` focuses the launcher from anywhere. `M` renames the focused item. Menus show key hints.
+- Queued follow-ups are listed above the composer and can be cancelled from an × button, with confirmation.
+- Task cards and requests show the harness logo, with a "harness · model" tooltip.
+
+### Fixed
+
+- Image blocks pointing outside the project (e.g. `/tmp/shot.png`) no longer render broken.
+- Replying to a finished agent no longer gets queued behind a CLI that keeps running after its result. A run now ends on exit, 3s after its result, or when a follow-up arrives.
+- Removing a project or deleting a session no longer fails silently (body-less `DELETE`s now send a JSON content type).
+- The notifications setting is a real on/off switch.
+- Finished cards fold up unless you are looking at them.
+- Shortcut labels read `⌘L` on macOS and `Ctrl+L` elsewhere, and modifier shortcuts work on non-Latin keyboard layouts.
+
+### Changed
+
+- A follow-up sent while an agent is working now goes out right away: wisp interrupts the run and resumes the session with your message. To get the old behaviour back (wait until the run finishes), turn on the **Queue** toggle next to the send button. It shows while the agent is working, and wisp remembers the choice.
+- The Plan / Edits / Full auto control is now one compact button with a menu. It shows a label only for a non-default mode; `Shift+Tab` in the prompt cycles modes.
+- The top bar no longer shows harness status; Settings lists each harness with its version.
+- Slimmer scrollbars that don't shift the layout.
+
 ## [0.2.2] - 2026-10-16
 
 ### Fixed
@@ -41,7 +76,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 - Session queue with follow-ups, answers to agent questions, terminal takeover and mark-as-done.
 - Older turns are folded, with a floating collapse-all button and back-to-top.
 
-[Unreleased]: https://github.com/M0xoo/wisp/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/M0xoo/wisp/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/M0xoo/wisp/compare/v0.2.2...v0.3.0
 [0.2.2]: https://github.com/M0xoo/wisp/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/M0xoo/wisp/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/M0xoo/wisp/compare/v0.1.0...v0.2.0

package/README.md

@@ -13,7 +13,7 @@ Launch coding agents in the background, skip the transcript, and read the presen
 [![Node](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org)
 [![Electron](https://img.shields.io/badge/desktop-Electron-47848f?logo=electron&logoColor=white)](https://www.electronjs.org)
 [![Zero runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)](package.json)
-[![Claude Code](https://img.shields.io/badge/harness-Claude%20Code-d97757)](https://claude.com/claude-code)
+[![Harnesses](https://img.shields.io/badge/harness-Claude%20Code%20·%20Codex%20·%20opencode%20·%20Cursor-d97757)](#adding-a-harness)
 
 [Quick start](#quick-start) · [Features](#features) · [CLI](#cli) · [Shortcuts](#keyboard-shortcuts) · [Architecture](#architecture) · [Adding a harness](#adding-a-harness) · [Roadmap](#roadmap)
 
@@ -23,7 +23,7 @@ Launch coding agents in the background, skip the transcript, and read the presen
 
 ## Why wisp?
 
-Agent transcripts are long, and you rarely need them. wisp runs agent harnesses (Claude Code today, with Codex and opencode planned) on your projects in the background. When an agent finishes, it hands you a short, animated **presentation**: diffs, test results, commits, flows, and decisions. The session then waits in your queue.
+Agent transcripts are long, and you rarely need them. wisp runs agent harnesses (Claude Code, Codex, opencode, and Cursor) on your projects in the background. When an agent finishes, it hands you a short, animated **presentation**: diffs, test results, commits, flows, and decisions. The session then waits in your queue.
 
 From there you can **follow up**, **answer its questions**, **take it over** in your terminal, or **mark it done**.
 
@@ -41,15 +41,18 @@ From there you can **follow up**, **answer its questions**, **take it over** in
 | 🎞️ **Presentations, not transcripts** | Agents end with structured blocks that render as an animated, skimmable report. |
 | ❓ **Live questions** | Agents get an `ask_user` tool, so they can pause mid-run. Your answer goes straight back to the running agent. |
 | 🧾 **Real diffs** | Edits come from the agent's own tool calls, so `diff` blocks show what actually changed. |
-| 📥 **A queue** | Sessions sort into *Needs you*, *Working* (with a live one-line status), and *Done*. |
-| 🖥️ **Take over** | Opens your terminal with `claude --resume <id>` in the project folder. Works with Terminal, iTerm, Ghostty, Warp, kitty, WezTerm, or a custom command. |
+| 📥 **A queue** | Sessions sort into *Needs you*, *Working* (with a live one-line status), and *Done*. Archive what you don't need to see. |
+| 💬 **Follow-ups that interrupt** | A follow-up sent mid-run interrupts the agent and resumes it with your message. Turn on **Queue** to wait for the run to finish instead; queued messages can be cancelled. |
+| 🔎 **Command palette** | `⌘K` / `Ctrl+K` fuzzy-searches sessions, projects, and actions. |
+| 🤖 **Any harness** | Claude Code, Codex, opencode, or Cursor CLI. Pick the harness and model together in the launcher; the model is remembered per harness. Each card shows the harness it ran on. |
+| 🖥️ **Take over** | Opens your terminal with the harness's resume command (`claude --resume <id>`, `codex resume <id>`, …) in the project folder. Works with Terminal, iTerm, Ghostty, Warp, kitty, WezTerm, GNOME Terminal, Konsole, Alacritty, Windows Terminal, PowerShell, or a custom command. |
 | 📎 **Attachments** | Paste screenshots or drop images, video, logs, or PDFs into the launcher. |
-| 🔐 **Permission modes** | Choose **Plan** (read-only), **Edits** (file edits auto-accepted), or **Full auto** for each launch. |
+| 🔐 **Permission modes** | Choose **Plan** (read-only), **Edits** (file edits auto-accepted), or **Full auto** for each launch. `Shift+Tab` in the prompt cycles modes. |
 | 🪶 **No runtime dependencies** | The server uses only Node built-ins. Electron is needed only for the desktop app. |
 
 ## Quick start
 
-> **Requirements:** Node.js ≥ 20 and [Claude Code](https://claude.com/claude-code) (`claude`) installed and signed in.
+> **Requirements:** macOS, Linux, or Windows; Node.js ≥ 20; and at least one harness installed and signed in: [Claude Code](https://claude.com/claude-code) (`claude`), [Codex](https://github.com/openai/codex) (`codex`), [opencode](https://opencode.ai) (`opencode`), or [Cursor CLI](https://cursor.com/cli) (`cursor-agent`). Override a binary path with `WISP_CLAUDE_BIN`, `WISP_CODEX_BIN`, `WISP_OPENCODE_BIN`, or `WISP_CURSOR_BIN`.
 
 ```sh
 npx wisp-agents                          # open the wisp desktop app
@@ -98,12 +101,14 @@ wisp                              # open wisp (or focus the running one)
 wisp "fix the flaky auth test"    # launch a task in this folder (it becomes a project)
 wisp add [path]                   # add a folder as a project (default: cwd)
 wisp --mode plan "audit deps"     # permission mode: plan | edits | auto
+wisp --agent codex "add a test"   # harness: claude | codex | opencode | cursor
 ```
 
 | Option | Description |
 |---|---|
 | `--port`, `-p N` | Port to use (default `4477`, or `WISP_PORT`) |
 | `--mode`, `-m` | `plan` · `edits` · `auto` |
+| `--agent`, `-a` | `claude` · `codex` · `opencode` · `cursor` (default: the agent last picked in the launcher) |
 | `--browser`, `-b` | Use the browser instead of the desktop app |
 | `--no-open` | Just run the server; open nothing |
 | `--version`, `-v` | Print the version |
@@ -114,7 +119,9 @@ wisp --mode plan "audit deps"     # permission mode: plan | edits | auto
 
 | Key | Action |
 |---|---|
-| `N` | New task (focus the launcher) |
+| `⌘ K` / `Ctrl K` | Command palette: fuzzy-search sessions, projects and actions |
+| `N` · `⌘ L` / `Ctrl L` | New task (focus the launcher; `⌘ L` works from anywhere) |
+| `⇧ Tab` | Cycle permission mode (in the launcher) |
 | `⌘ ↵` | Launch and keep the launcher open for the next task |
 | `J` / `K` | Move down / up through the queue |
 | `O` / `↵` | Open or collapse the focused session |
@@ -122,7 +129,11 @@ wisp --mode plan "audit deps"     # permission mode: plan | edits | auto
 | `1`–`9` | Pick an option in a pending question |
 | `T` | Take over in your terminal |
 | `E` | Mark done and jump to the next session that needs you |
+| `A` | Archive / unarchive |
+| `M` | Rename |
+| `⌫` | Delete |
 | `R` | Replay the presentation |
+| `C` | Collapse all |
 | `?` | Show all shortcuts |
 | `Esc` | Close, blur, or collapse |
 
@@ -131,7 +142,10 @@ File paths in presentations open in your editor. VS Code, Cursor, Zed, and JetBr
 ## Architecture
 
 ```text
-web/ (UI) ⇄ HTTP + SSE ⇄ server/ ── adapters/claude.js ── claude -p --output-format stream-json
+web/ (UI) ⇄ HTTP + SSE ⇄ server/ ── adapters/claude.js   ── claude -p --output-format stream-json
+                                 ├─ adapters/codex.js    ── codex exec --json
+                                 ├─ adapters/opencode.js ── opencode run --format json
+                                 ├─ adapters/cursor.js   ── cursor-agent -p --output-format stream-json
                                  └─ mcp-ask.js  (ask_user MCP tool, injected per run)
 ```
 
@@ -149,7 +163,11 @@ wisp/
 │   ├── welcome.js         # the gallery session
 │   └── adapters/
 │       ├── index.js       # adapter registry + contract
-│       └── claude.js      # Claude Code adapter
+│       ├── common.js      # shared spawn/JSONL plumbing, labels, diff capture
+│       ├── claude.js      # Claude Code adapter
+│       ├── codex.js       # Codex CLI adapter
+│       ├── opencode.js    # opencode adapter
+│       └── cursor.js      # Cursor CLI adapter
 ├── web/                   # vanilla JS UI, no build step
 │   ├── index.html
 │   ├── css/app.css
@@ -161,7 +179,7 @@ wisp/
 
 - **Protocol** (`server/protocol.js`): a system prompt tells agents to work autonomously and to end with a fenced `wisp` JSON block of presentation blocks. The parser reads that block, and falls back to plain markdown if it is missing.
 - **Adapters** (`server/adapters/`): one file per harness. An adapter turns a run into normalized events (`session`, `tool`, `change`, `text`, `result`, …) and provides a `resumeCommand` for take over.
-- **State** lives in `~/.wisp` (override with `WISP_HOME`): one JSON file per session, plus `config.json` and `uploads/`.
+- **State** lives in `~/.wisp` (override with `WISP_HOME`): one JSON file per session, plus `config.json`, `uploads/`, and `shots/` (copies of images agents showed).
 
 ### Presentation blocks
 
@@ -173,20 +191,30 @@ wisp/
 2. Implement `detect()`, `run()`, and `resumeCommand()`. The full contract is documented at the top of `server/adapters/index.js`.
 3. Register the adapter in `server/adapters/index.js`.
 
-If the harness has no system-prompt flag, prepend `systemPrompt` to the first prompt. If it supports MCP, pass `mcpServers` through so that `ask_user` works.
+If the harness has no system-prompt flag, prepend `systemPrompt` to the first prompt (`withProtocol` in `common.js`). If it supports MCP, pass `mcpServers` through so that `ask_user` works and set `askTool` to the name the agent sees; set `askTool: null` if it can't, and agents will ask with a `question` block instead.
 
 ## Roadmap
 
 - [x] Claude Code adapter
 - [x] Live `ask_user` questions
 - [x] Desktop app (Electron)
-- [ ] Codex adapter
-- [ ] opencode adapter
+- [x] Codex adapter
+- [x] opencode adapter
+- [x] Cursor CLI adapter
 
 ## Contributing
 
 Issues and PRs are welcome. wisp has no build step: edit `web/` or `server/`, then run `npm run dev` (or `npm run dev:web`) to see your changes.
 
+### Tests
+
+```sh
+npm test         # adapters, process launching, terminals, and the full ask_user loop
+npm run test:real  # smoke test against the real CLIs installed on this machine
+```
+
+`npm test` needs no network or accounts. A fake CLI (`test/fixtures/fake-agent.mjs`) speaks each harness's real output format, edits files, and calls `ask_user` through the real MCP bridge. On Windows the fakes are installed as npm-style `.cmd` shims, which is how npm installs the real CLIs. CI (`.github/workflows/test.yml`) runs the suite on Linux, macOS, and Windows with Node 20 and 22, then runs `test:real` against freshly installed Claude Code, Codex, opencode, and Cursor CLIs.
+
 ## License
 
 [MIT](LICENSE) © M0xoo

package/bin/wisp.js

@@ -6,6 +6,7 @@
 //   wisp add [path]        add a folder as a project (default: current folder)
 //   --port N               port (default 4477, or WISP_PORT)
 //   --mode plan|edits|auto permission mode for a launch
+//   --agent ID             claude, codex, opencode or cursor (default: the launcher's pick)
 //   --browser              use the browser instead of the desktop app
 //   --no-open              just run the server, open nothing
 
@@ -17,7 +18,7 @@ import { fileURLToPath } from 'node:url';
 import { wispAppBinary } from './mac-app.js';
 
 const argv = process.argv.slice(2);
-const flags = { open: true, browser: false, port: Number(process.env.WISP_PORT) || 4477, mode: null };
+const flags = { open: true, browser: false, port: Number(process.env.WISP_PORT) || 4477, mode: null, agent: null };
 const words = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -25,12 +26,13 @@ for (let i = 0; i < argv.length; i++) {
   else if (a === '--browser' || a === '-b') flags.browser = true;
   else if (a === '--port' || a === '-p') flags.port = Number(argv[++i]);
   else if (a === '--mode' || a === '-m') flags.mode = argv[++i];
+  else if (a === '--agent' || a === '-a') flags.agent = argv[++i];
   else if (a === '--version' || a === '-v') {
     const { readFileSync } = await import('node:fs');
     console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url))).version);
     process.exit(0);
   } else if (a === '--help' || a === '-h') {
-    console.log('usage:\n  wisp                    open wisp\n  wisp "task"             launch a task in this folder\n  wisp add [path]         add a project\n\noptions: --port N  --mode plan|edits|auto  --browser  --no-open  --version');
+    console.log('usage:\n  wisp                    open wisp\n  wisp "task"             launch a task in this folder\n  wisp add [path]         add a project\n\noptions: --port N  --mode plan|edits|auto  --agent claude|codex|opencode|cursor  --browser  --no-open  --version');
     process.exit(0);
   } else words.push(a);
 }
@@ -80,7 +82,10 @@ if (words[0] === 'add') {
   if (running || electron) process.exit(0);
 } else if (words.length) {
   const cfg = await api('/config');
-  const s = await api('/sessions', { prompt: words.join(' '), cwd: process.cwd(), agent: cfg.defaults.agent, mode: flags.mode || cfg.defaults.mode, model: cfg.defaults.model });
+  const agent = flags.agent || cfg.defaults.agent;
+  // Models are remembered per agent (ids aren't portable between harnesses).
+  const model = cfg.defaults.models?.[agent] ?? (agent === cfg.defaults.agent ? cfg.defaults.model : '');
+  const s = await api('/sessions', { prompt: words.join(' '), cwd: process.cwd(), agent, mode: flags.mode || cfg.defaults.mode, model });
   console.log(`  ◌ launched: ${s.title}`);
   openPath = `/#/s/${s.id}`;
   if (running || electron) process.exit(0); // the running wisp will show it in the queue

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wisp-agents",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Launch coding agents, skip the transcript, read the presentation.",
   "type": "module",
   "bin": {
@@ -19,6 +19,8 @@
     "app": "node bin/wisp.js",
     "dev": "WISP_DEV=1 node bin/wisp.js",
     "dev:web": "node --watch-path=server bin/wisp.js --no-open",
+    "test": "node --test test/proc.test.js test/terminal.test.js test/adapters.test.js test/e2e.test.js test/fuzzy.test.js",
+    "test:real": "node test/real-clis.mjs",
     "prepublishOnly": "node --check bin/wisp.js && node --check bin/mac-app.js && node -e \"import('./server/index.js')\" && node --check electron/main.js"
   },
   "engines": {

package/server/adapters/claude.js

@@ -1,12 +1,12 @@
 // Claude Code adapter — drives `claude -p --output-format stream-json`.
 
-import { spawn, execFile } from 'node:child_process';
 import readline from 'node:readline';
 import fs from 'node:fs';
 import path from 'node:path';
+import { spawn, killTree } from '../proc.js';
+import { ASK_TIMEOUT_MS, MAX_SNAPSHOT, attachmentNote, clip, detectVersion, flatten, rel } from './common.js';
 
 const BIN = process.env.WISP_CLAUDE_BIN || 'claude';
-const MAX_SNAPSHOT = 256 * 1024;
 
 const PERMISSION_MODES = {
   plan: 'plan',
@@ -30,11 +30,7 @@ export default {
   },
 
   detect() {
-    return new Promise((resolve) => {
-      execFile(BIN, ['--version'], { timeout: 10_000 }, (err, stdout) => {
-        resolve(err ? { available: false, error: err.message } : { available: true, version: stdout.trim() });
-      });
-    });
+    return detectVersion(BIN);
   },
 
   // Returns { stop(), done: Promise<void> }. Everything else is reported through onEvent.
@@ -54,12 +50,12 @@ export default {
     const dirs = [...new Set(attachments.map((a) => path.dirname(a.path)))];
     if (dirs.length) args.push('--add-dir', ...dirs);
     args.push('--verbose'); // terminates the variadic flags above
-    if (attachments.length) prompt += attachmentNote(attachments);
+    prompt += attachmentNote(attachments, 'Read images and PDFs with the Read tool');
 
     const env = { ...process.env };
     delete env.CLAUDECODE; // don't let a parent Claude Code session leak into the child
     delete env.CLAUDE_CODE_ENTRYPOINT;
-    env.MCP_TOOL_TIMEOUT ??= String(7 * 24 * 3600 * 1000); // ask_user may wait for the human a long time
+    env.MCP_TOOL_TIMEOUT ??= String(ASK_TIMEOUT_MS);
 
     const child = spawn(BIN, args, { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] });
     child.stdin.end(prompt);
@@ -119,6 +115,7 @@ export default {
       }
     });
 
+    let stopping = false;
     const done = new Promise((resolve) => {
       child.on('error', (err) => {
         onEvent({ type: 'result', isError: true, text: `Could not start \`${BIN}\`: ${err.message}` });
@@ -130,7 +127,7 @@ export default {
           onEvent({
             type: 'result',
             isError: true,
-            stopped: signal === 'SIGTERM' || signal === 'SIGINT',
+            stopped: stopping || signal === 'SIGTERM' || signal === 'SIGINT',
             text: stderr.trim() || `claude exited with ${signal || `code ${code}`}`,
           });
         }
@@ -141,27 +138,15 @@ export default {
     return {
       done,
       stop() {
-        if (child.exitCode === null) child.kill('SIGTERM');
+        stopping = true;
+        killTree(child);
       },
     };
   },
 };
 
-function attachmentNote(files) {
-  const lines = files.map((f) => `- ${f.path}  (${f.mime}, ${Math.max(1, Math.round(f.size / 1024))} KB)`);
-  return `\n\n<attachments>\nThe user attached these files. Read images and PDFs with the Read tool; for video/audio/other formats use the shell (e.g. ffmpeg, ffprobe) if needed.\n${lines.join('\n')}\n</attachments>`;
-}
 
-function rel(file, cwd) {
-  if (!file) return '';
-  const r = path.relative(cwd, file);
-  return r && !r.startsWith('..') ? r : file;
-}
 
-function clip(s, n = 80) {
-  s = String(s ?? '').replace(/\s+/g, ' ').trim();
-  return s.length > n ? `${s.slice(0, n - 1)}…` : s;
-}
 
 // Human sentence for the live ticker + a coarse kind for the trail summary.
 function describeTool(name, input, cwd) {
@@ -223,8 +208,3 @@ function captureChange(name, input, cwd) {
   return null;
 }
 
-function flatten(content) {
-  if (typeof content === 'string') return content;
-  if (Array.isArray(content)) return content.map((c) => c.text || '').join('\n');
-  return '';
-}

package/server/adapters/codex.js

@@ -0,0 +1,188 @@
+// Codex CLI adapter — drives `codex exec --json` (JSONL thread/turn/item events).
+
+import path from 'node:path';
+import { ASK_TIMEOUT_MS, attachmentNote, clip, detectVersion, fileTracker, rel, spawnJsonl, withProtocol } from './common.js';
+
+const BIN = process.env.WISP_CODEX_BIN || 'codex';
+const IMAGE = /^image\/(png|jpe?g|gif|webp)$/;
+
+// Codex has no "accept edits only" mode; workspace-write lets it edit the project and run
+// sandboxed commands without asking, which is the closest match.
+const SANDBOX = {
+  plan: 'read-only',
+  edits: 'workspace-write',
+};
+
+const toml = (v) =>
+  Array.isArray(v) ? `[${v.map(toml).join(',')}]` : typeof v === 'object' ? `{${Object.entries(v).map(([k, x]) => `${k}=${toml(x)}`).join(',')}}` : JSON.stringify(v);
+
+export default {
+  id: 'codex',
+  name: 'Codex',
+  askTool: 'mcp__wisp__ask_user',
+  models: [{ id: '', label: 'Default', hint: 'Whatever Codex is set to' }],
+
+  resumeCommand({ resumeId, model }) {
+    return [BIN, ...(resumeId ? ['resume', resumeId] : []), ...(model ? ['--model', model] : [])];
+  },
+
+  detect() {
+    return detectVersion(BIN);
+  },
+
+  run({ prompt, attachments = [], cwd, resumeId, mode, model, systemPrompt, mcpServers = {}, onEvent }) {
+    const args = ['exec', '--json', '--skip-git-repo-check'];
+    // `resume` doesn't take --sandbox, so set it through config for both paths.
+    if (mode === 'auto') args.push('--dangerously-bypass-approvals-and-sandbox');
+    else args.push('-c', `sandbox_mode=${toml(SANDBOX[mode] || 'workspace-write')}`);
+    if (model) args.push('-m', model);
+    for (const [name, srv] of Object.entries(mcpServers)) {
+      const key = `mcp_servers.${name}`;
+      args.push('-c', `${key}.command=${toml(srv.command)}`, '-c', `${key}.args=${toml(srv.args || [])}`);
+      if (srv.env) args.push('-c', `${key}.env=${toml(srv.env)}`);
+      args.push('-c', `${key}.tool_timeout_sec=${ASK_TIMEOUT_MS / 1000}`);
+    }
+    const images = attachments.filter((a) => IMAGE.test(a.mime));
+    for (const img of images) args.push('-i', img.path);
+    if (!resumeId) {
+      const dirs = [...new Set(attachments.map((a) => path.dirname(a.path)))];
+      for (const d of dirs) args.push('--add-dir', d);
+    }
+    if (resumeId) args.push('resume', resumeId);
+    // No prompt argument: codex reads it from stdin.
+
+    let input = withProtocol(prompt, systemPrompt, resumeId);
+    input += attachmentNote(attachments.filter((a) => !images.includes(a)), 'Read text files and PDFs from disk');
+    if (images.length) input += `\n\n(${images.length} image${images.length > 1 ? 's are' : ' is'} attached to this message.)`;
+
+    const files = fileTracker(cwd);
+    let lastMessage = '';
+    let failure = null;
+    let lastError = '';
+    let usage = null;
+    let completed = false;
+    const started = Date.now();
+
+    const onItem = (item, phase) => {
+      const type = item.type || item.item_type;
+      if (phase === 'started') {
+        if (type === 'command_execution') {
+          onEvent({ type: 'tool', kind: 'run', label: `Running ${clip(unwrapShell(item.command), 60)}`, detail: item.command });
+        } else if (type === 'mcp_tool_call') {
+          onEvent({ type: 'tool', ...describeMcp(item) });
+        } else if (type === 'web_search') {
+          onEvent({ type: 'tool', kind: 'web', label: item.query ? `Searching the web: ${clip(item.query, 50)}` : 'Searching the web' });
+        }
+        return;
+      }
+      if (phase === 'updated') {
+        if (type === 'todo_list') {
+          const next = item.items?.find((t) => !t.completed);
+          if (next) onEvent({ type: 'tool', kind: 'plan', label: clip(next.text) });
+        }
+        return;
+      }
+      // completed
+      switch (type) {
+        case 'agent_message':
+        case 'assistant_message':
+          if (item.text?.trim()) {
+            lastMessage = item.text;
+            onEvent({ type: 'text', text: item.text });
+          }
+          break;
+        case 'reasoning':
+          onEvent({ type: 'thinking' });
+          break;
+        case 'command_execution':
+          if (item.status === 'failed' || (item.exit_code != null && item.exit_code !== 0)) {
+            onEvent({ type: 'tool_error', name: clip(unwrapShell(item.command), 40), text: clip(item.aggregated_output || `exit ${item.exit_code}`, 400) });
+          }
+          break;
+        case 'file_change':
+          for (const c of item.changes || []) {
+            const f = rel(c.path, cwd);
+            onEvent({ type: 'tool', kind: 'edit', label: `${c.kind === 'add' ? 'Writing' : c.kind === 'delete' ? 'Deleting' : 'Editing'} ${f}`, file: f });
+            const change = files.change(c.path);
+            if (change) onEvent({ type: 'change', ...change });
+          }
+          if (item.status === 'failed') onEvent({ type: 'tool_error', name: 'apply_patch', text: 'The patch did not apply.' });
+          break;
+        case 'mcp_tool_call':
+          if (item.status === 'failed') onEvent({ type: 'tool_error', name: `${item.server}.${item.tool}`, text: clip(item.error?.message || 'failed', 400) });
+          break;
+        case 'todo_list': {
+          const next = item.items?.find((t) => !t.completed);
+          if (next) onEvent({ type: 'tool', kind: 'plan', label: clip(next.text) });
+          break;
+        }
+      }
+    };
+
+    return spawnJsonl({
+      bin: BIN,
+      args,
+      cwd,
+      env: process.env,
+      input,
+      onEvent,
+      onJson(msg) {
+        switch (msg.type) {
+          case 'thread.started':
+            if (msg.thread_id) onEvent({ type: 'session', id: msg.thread_id });
+            break;
+          case 'item.started':
+          case 'item.updated':
+          case 'item.completed':
+            if (msg.item) onItem(msg.item, msg.type.slice(5));
+            break;
+          case 'turn.completed':
+            completed = true;
+            usage = msg.usage || null;
+            break;
+          case 'turn.failed':
+            failure = msg.error?.message || 'The turn failed.';
+            break;
+          case 'error':
+            // "Reconnecting... n/5" is transient; keep the last one in case the turn dies.
+            if (msg.message) lastError = msg.message;
+            break;
+        }
+      },
+      onClose({ code, signal, stderr, stopped }) {
+        const ok = completed && !failure && code === 0;
+        onEvent({
+          type: 'result',
+          isError: !ok,
+          stopped,
+          text: ok ? lastMessage : failure || lastError || stderr || `codex exited with ${signal || `code ${code}`}`,
+          stats: {
+            durationMs: Date.now() - started,
+            inputTokens: usage?.input_tokens,
+            outputTokens: usage?.output_tokens,
+          },
+        });
+      },
+    });
+  },
+};
+
+// codex reports commands wrapped in a shell: `bash -lc '…'` on Unix, `powershell.exe -Command "…"`
+// on Windows. Show the inner command.
+export function unwrapShell(cmd) {
+  if (Array.isArray(cmd)) {
+    const i = cmd.findIndex((a) => /^(-l?c|-Command|\/c)$/i.test(a));
+    return i >= 0 && i === cmd.length - 2 ? cmd.at(-1) : cmd.join(' ');
+  }
+  const s = String(cmd ?? '');
+  const m =
+    s.match(/^(?:\S*\/)?(?:ba|z)?sh -l?c (['"])([\s\S]*)\1$/) ||
+    s.match(/^"?(?:[^"]*[\\/])?(?:powershell|pwsh)(?:\.exe)?"?(?: -NoProfile| -NoLogo)* -(?:Command|c) (['"]?)([\s\S]*)\1$/i) ||
+    s.match(/^"?(?:[^"]*[\\/])?cmd(?:\.exe)?"? \/[cC] (['"]?)([\s\S]*)\1$/);
+  return m ? m[2] : s;
+}
+
+function describeMcp(item) {
+  if (item.server === 'wisp' && item.tool === 'ask_user') return { kind: 'wait', label: 'Waiting for your answer' };
+  return { kind: 'tool', label: `Using ${item.server} · ${item.tool}` };
+}