@loicngr/kobo 1.7.7 → 1.7.8

package/AGENTS.md

@@ -171,6 +171,35 @@ When adding features touching `notion-service.ts`, remember: **no token = no fea
 
 See the "Notion integration" section of the README for the end-user setup guide.
 
+### Agent engines
+
+Two engines live under `src/server/services/agent/engines/`, both implementing the `AgentEngine` contract in `types.ts`:
+
+**Claude Code** (`claude-code/`) — uses `@anthropic-ai/claude-agent-sdk` (in-process async iterator). Spawns no subprocess. Auth via `~/.claude.json` or `ANTHROPIC_API_KEY` env var.
+
+**OpenAI Codex** (`codex/`) — uses the **`codex app-server` JSON-RPC protocol** (line-delimited JSON over stdio with a long-lived `codex` subprocess). The engine layers are:
+- `jsonrpc/transport.ts` + `jsonrpc/peer.ts` — generic JSON-RPC 2.0 stdio peer (request correlation, notifications, server-initiated requests)
+- `client.ts` — typed `AppServerClient` wrapping the peer (initialize / thread.start / thread.resume / turn.start / turn.interrupt)
+- `protocol/types.ts` — hand-written subset of the Codex v2 protocol types (camelCase field names — `agentMessage`, `commandExecution`, etc.). The full canonical bindings are generated by `codex app-server generate-ts` if the protocol drifts.
+- `event-mapper.ts` — translates app-server notifications (`item/started`, `item/completed`, `item/agentMessage/delta`, `turn/completed`, `thread/tokenUsage/updated`, `account/rateLimits/updated`, `error`) into Kōbō `AgentEvent` union
+- `server-requests.ts` — handles server-initiated approval/elicitation requests (`item/commandExecution/requestApproval`, `item/fileChange/requestApproval`, `item/tool/requestUserInput`, `item/permissions/requestApproval`, plus v1 legacy aliases `execCommandApproval` / `applyPatchApproval`)
+- `engine.ts` — `createCodexEngine()` factory wiring everything into `AgentEngine`
+- `spawn.ts` — locates the `codex` binary via `@openai/codex` dependency and spawns `codex app-server`
+
+Auth: delegated to the `codex` CLI which reads `OPENAI_API_KEY` from env or `~/.codex/auth.json`. Kōbō ships no Codex credentials. The `@openai/codex` package (binary) is a direct dependency.
+
+Background: the engine was migrated from `@openai/codex-sdk` (one-shot `codex exec`) to `codex app-server` in May 2026 to unlock features the SDK didn't surface (sub-agent visibility, interactive approvals, `request_user_input`, structured rate limits). The original migration plan and wire-capture notes live at `docs/superpowers/plans/2026-05-11-codex-app-server-migration.md` and `2026-05-11-codex-app-server-wire-capture.md`.
+
+**Protocol gotchas worth remembering** (post-migration findings):
+
+- **`experimentalApi: true` is mandatory in the `initialize` handshake.** Without it, any turn using experimental fields — most importantly `turn/start.collaborationMode` — is rejected with `-32600: requires experimentalApi capability`. See `client.ts:connect()`.
+- **`collaborationMode` is sticky server-side.** Once a turn ran in `mode: 'plan'`, every subsequent turn on the same thread stays in plan until we explicitly send `mode: 'default'` again. The engine therefore always emits the field on `turn/start` — never omits it — so a Plan → Bypass switch actually takes effect. Mapping: Kōbō `plan` → `plan`, every other Kōbō mode → `default`. Plan mode is the only one that unlocks Codex's internal `request_user_input` tool.
+- **Permission mode vs collaboration mode are independent.** Sandbox + approvalPolicy control *what the agent may do at OS level* (read-only / workspace-write, never / on-request / unless-trusted). `collaborationMode` is a separate session-level flag that gates internal Codex behaviour (notably interactive Q&A). Kōbō hides both behind a single "permission mode" selector and maps them together.
+- **Sub-agents map to `collabAgentToolCall`.** Codex's analogue of Claude's Task tool is `collabAgentToolCall` (`spawnAgent` / `sendInput` / `resumeAgent` / `wait` / `closeAgent`). The mapper emits **both** a `tool:call` named `Task` (chat card) and a `subagent:progress` event (right-hand panel) per call — same dual-emission Claude does. See `event-mapper.ts` `handleItemStarted` / `handleItemCompleted` for the `collabAgentToolCall` branch.
+- **`fileChange` items carry a unified-diff blob.** The protocol shape is `{ path, kind: PatchChangeKind, diff: string }` per change; `kind` is a discriminated union, not a string. The mapper flattens the first change into a Claude-style Edit input (`{ file_path, diff, change_kind, move_path? }`) so the existing `ToolCallItem` renderer picks it up. The client parses the unified diff into `DiffLine[]` via `parseUnifiedDiff` in `inline-diff.ts`.
+- **Streaming bursts trip auto-scroll.** Codex emits one `message:text` event per token-delta (50-200 per message), versus Claude which emits ~1 per content block. The naive `eventCount` watcher in `ActivityFeed.vue` triggered an animated `scrollToBottom(180)` per event, causing stacked animations and visible jank. The fix coalesces requests through `requestAnimationFrame` and only animates the *first* scroll after a quiet period — subsequent scrolls during a burst snap instantly.
+- **`MCP tools` need `default_tools_approval_mode: 'auto'` in `config.mcp_servers`.** Without it Codex flags every MCP tool call as needing user approval ("user cancelled MCP tool call"). Kōbō trusts every tool it spawns, so the options-builder pre-approves the namespace.
+
 ## Code conventions
 
 **Service layer** throws descriptive errors; the route layer catches and maps to HTTP status codes. Error messages follow the pattern `` `Workspace '${id}' not found` `` / `` `... is already archived` ``.

package/README.md

@@ -1,6 +1,6 @@
 # Kōbō
 
-> **Kōbō** (工房) — Japanese for *workshop*. A multi-workspace agent manager for [Claude Code](https://claude.com/claude-code).
+> **Kōbō** (工房) — Japanese for *workshop*. A multi-workspace agent manager for [Claude Code](https://claude.com/claude-code) and [OpenAI Codex](https://developers.openai.com/codex/) *(Codex support is still experimental — see [the section below](#openai-codex-integration))*.
 
 > [!NOTE]
 > 🚧 **Active development** — breaking changes may still land on `develop`. The database layer ships with forward-only migrations and a timestamped pre-migration backup of `kobo.db` before any schema change, so upgrades preserve your data even across invasive refactors.
@@ -12,7 +12,7 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 ## Features
 
 - **Isolated git worktrees** — every workspace runs on its own branch in its own directory, with a configurable global worktrees root for new workspaces, so concurrent Claude sessions never step on each other
-- **Pluggable agent engine** — Kōbō talks to agents through an `AgentEngine` contract with a normalised `AgentEvent` stream (`src/server/services/agent/engines/`). The `claude-code` engine runs on the official [`@anthropic-ai/claude-agent-sdk`](https://github.com/anthropics/claude-agent-sdk-typescript); adding a second runtime (e.g. Codex) only requires a new adapter, not a rewrite of the UI or orchestration layer
+- **Pluggable agent engine — two runtimes shipped** — Kōbō talks to agents through an `AgentEngine` contract with a normalised `AgentEvent` stream (`src/server/services/agent/engines/`). The `claude-code` engine runs on the official [`@anthropic-ai/claude-agent-sdk`](https://github.com/anthropics/claude-agent-sdk-typescript); the `codex` engine speaks the [`codex app-server`](https://github.com/openai/codex) JSON-RPC protocol over stdio with the official [`@openai/codex`](https://www.npmjs.com/package/@openai/codex) binary. Engine is chosen per-workspace at creation time, with a single normalised UI (sub-agents, tool calls, todos, reasoning, permission modes, MCP servers, auto-loop) covering both. Adding a third runtime only requires a new adapter, not a rewrite of the UI or orchestration layer
 - **Interactive `AskUserQuestion`** — when the agent invokes `AskUserQuestion`, Kōbō pauses the session via the SDK's `defer` pattern, surfaces a question panel in the UI, and resumes the agent once the user answers. The session does not occupy any resources while it waits
 - **Rich chat feed** — live streaming text, thinking blocks, inline tool calls with expandable diffs for Edit/Write, per-turn session cards, markdown rendering, jump-to-previous-user-message button, and infinite scroll-up over persisted history
 - **Task & acceptance criteria tracking** — the agent reports progress through a dedicated MCP server (`kobo-tasks`) that reads and updates tasks directly from the SQLite database
@@ -27,7 +27,7 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 - **Prompt templates** — personal library of reusable prompts with variable substitution (`{working_branch}`, `{commit_count}`, etc.), insertable from the chat input via `/` autocomplete; editable in Settings > Templates
 - **Favorites and tags** — pin workspaces to the top via right-click favourite, organise with per-workspace tags filterable from the sidebar; a global tag catalogue keeps colours consistent across workspaces
 - **Health panel + config export/import** — inspect backend health (agent sessions, migration state, dev servers, DB size) and roundtrip your Kōbō config (settings, templates, skills) between machines via JSON
-- **Account-level quota panel** — a colored mini-bar badge in the chat footer shows the current Claude Code 5-hour and 7-day usage, fed by a backend service that polls Anthropic's OAuth usage endpoint every 60 seconds. Click to open a popover with full bars, reset times, a "Refresh now" button, and a one-click jump to the Stats tab. Pluggable per-provider (Codex-ready), persisted in SQLite so the badge is populated on cold start, and account-level so it's the same across workspaces sharing the same engine
+- **Account-level quota panel** — a colored mini-bar badge in the chat footer shows the current Claude Code 5-hour and 7-day usage (Claude workspaces) or live Codex rate-limit buckets (Codex workspaces — driven by the structured `account/rateLimits/updated` app-server notification). Click to open a popover with full bars, reset times, a "Refresh now" button, and a one-click jump to the Stats tab. Pluggable per-provider, persisted in SQLite so the badge is populated on cold start, and account-level so it's the same across workspaces sharing the same engine
 - **Resizable right drawer** — drag-to-resize horizontally and vertically, with tab state and split ratio persisted to localStorage
 - **Soft interrupt** — pause an agent mid-execution (SIGINT, like pressing Escape in Claude Code) without killing the process; the agent stops the current tool and waits for the next message
 - **Archive instead of delete** — soft-remove workspaces without losing the worktree, branches, or history; unarchive restores the exact pre-archive state
@@ -51,7 +51,9 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 ### Prerequisites
 
 - Node.js ≥ 20
-- [Claude Code](https://claude.com/claude-code) authenticated via `claude /login` once. The `claude` CLI is **no longer required at runtime** — Kōbō embeds the official [`@anthropic-ai/claude-agent-sdk`](https://github.com/anthropics/claude-agent-sdk-typescript), which reuses the same login.
+- At least one agent runtime, authenticated:
+  - [Claude Code](https://claude.com/claude-code) — `claude /login` once. The `claude` CLI is **no longer required at runtime** — Kōbō embeds the official [`@anthropic-ai/claude-agent-sdk`](https://github.com/anthropics/claude-agent-sdk-typescript), which reuses the same login.
+  - [OpenAI Codex](https://developers.openai.com/codex/) — `codex login` once, or export `OPENAI_API_KEY` in the env. See [OpenAI Codex integration](#openai-codex-integration). Workspaces pick an engine at creation time, so you only need to set up the one(s) you use.
 - Git
 - Optional: Docker (if you configure per-workspace dev servers)
 - Optional: `gh` CLI (if you use the PR automation)
@@ -155,6 +157,62 @@ If you need to pin a specific version of the Notion MCP server, use a fork, or a
 
 Without a valid token configured, the Notion import field in the workspace creation form will return an error when you click **Refresh** or submit a Notion URL — the rest of Kōbō (workspaces, agents, tasks, Git integration) keeps working independently.
 
+## OpenAI Codex integration
+
+> [!WARNING]
+> 🧪 **Experimental** — the Codex engine has shipped but is still maturing. The Claude Code engine remains the primary, battle-tested path. Expect occasional rough edges on Codex-only flows (tool rendering for less common item types, sub-agent interactions, edge cases around `collaborationMode` and approval prompts). Bugs and feedback welcome on the issue tracker.
+
+Kōbō ships a second agent engine that runs on top of the official **OpenAI Codex** CLI. Pick `OpenAI Codex` in the engine selector when you create a workspace and the agent talks to the `codex` binary instead of Claude Code, with the same UI surface: streaming text, reasoning blocks, tool cards (Bash, Edit, Read, WebSearch, MCP tools, ImageGeneration), sub-agents (Codex's `collabAgentToolCall` family is mapped onto the same `Task` panel Claude's Task tool feeds), todo list, permission modes, interactive approvals, structured rate limits, auto-loop. **This feature is opt-in and requires you to authenticate the `codex` CLI separately from Claude Code** — Kōbō ships no OpenAI credentials.
+
+Under the hood, Kōbō spawns a long-lived `codex app-server` subprocess per workspace and speaks the [Codex app-server JSON-RPC protocol](https://github.com/openai/codex/tree/main/codex-rs/app-server) over stdio. The `codex` binary is pulled in via the [`@openai/codex`](https://www.npmjs.com/package/@openai/codex) npm package, which is a direct dependency — no separate install required.
+
+### Authenticating the Codex CLI
+
+Two paths, pick one:
+
+1. **`codex login` (recommended)** — run `codex login` once. The CLI writes a token to `~/.codex/auth.json` which Kōbō's spawned `codex app-server` reuses automatically:
+
+   ```bash
+   codex login
+   ```
+
+2. **`OPENAI_API_KEY` env var** — set the variable before launching Kōbō:
+
+   ```bash
+   OPENAI_API_KEY=sk-your-key-here PORT=9999 npx @loicngr/kobo@latest
+   ```
+
+Kōbō does not store or proxy the key. If you change the credential or revoke it, Kōbō follows automatically on the next session start.
+
+### Permission modes (Codex)
+
+Kōbō's four permission modes (`plan` / `bypass` / `strict` / `interactive`) map to Codex's `sandbox` + `approvalPolicy` pair, plus a separate `collaborationMode` flag that gates interactive questions:
+
+| Kōbō mode | Codex sandbox | Codex approvalPolicy | Codex collaborationMode | Effect |
+|---|---|---|---|---|
+| `plan` | `read-only` | `never` | `plan` | Read-only sandbox + the agent can ask interactive questions (`request_user_input`) |
+| `bypass` | `workspace-write` | `never` | `default` | Full autonomy in the worktree, no approvals |
+| `strict` | `workspace-write` | `on-request` | `default` | Writes allowed, approval prompted on sensitive commands |
+| `interactive` | `workspace-write` | `unless-trusted` | `default` | Writes allowed, approval prompted on every untrusted action |
+
+Interactive Q&A (`request_user_input`) is only available in `plan` — this is a constraint of Codex itself, not Kōbō. The typical workflow is: brainstorm in `plan` until the agent has the context it needs, then switch to `bypass`/`strict` for execution.
+
+### Models and reasoning effort
+
+The Codex engine exposes the OpenAI model catalogue (`gpt-5-codex`, `gpt-5.4`, `o4-mini`, `o3`) and the standard reasoning-effort scale (`auto` / `minimal` / `low` / `medium` / `high` / `xhigh`). Both selectors switch automatically when you flip the workspace's engine.
+
+### Sub-agents
+
+When the Codex agent uses its `spawnAgent` collab tool, Kōbō renders a **Task** card in the chat (like Claude's Task tool) and a live entry in the **SUB-AGENTS** panel of the right drawer — same plumbing the Claude engine uses. The same panel is hidden for engines that don't expose sub-agents.
+
+### MCP servers
+
+The `kobo-tasks` MCP server (and any other MCP server you configure on the workspace) is plumbed into Codex through the standard `config.mcp_servers` entry. Tool calls under those servers are pre-approved (`default_tools_approval_mode: 'auto'`) so the agent doesn't get blocked on every call.
+
+### When the binary is missing
+
+Without a working `codex` install or a valid credential, creating a `codex`-engine workspace returns a clear error at first turn and the workspace transitions to `error` status. The rest of Kōbō (Claude-engine workspaces, tasks, Git, dev servers) keeps working independently.
+
 ## Voice transcription (local Whisper)
 
 Kōbō supports local voice transcription with push-to-talk in both:

package/dist/mcp-server/kobo-tasks-server.js

@@ -119,6 +119,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             name: 'list_tasks',
             description: 'CALL FIRST on any non-trivial turn to know what the user wants done and what is already completed. Returns every task and acceptance criterion for the current workspace with its id and status. Re-call periodically (before marking something done, or after the user asks for a status) to stay in sync with user-added or external updates.',
             inputSchema: { type: 'object', properties: {}, required: [] },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         },
         {
             name: 'mark_task_done',
@@ -130,11 +131,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
                 required: ['task_id'],
             },
+            annotations: { destructiveHint: false, openWorldHint: false },
         },
         {
             name: 'mark_auto_loop_ready',
             description: 'CALL ONLY at the end of a `/kobo-prep-autoloop` grooming session, once all tasks look atomic and implementable in one session. Flips a flag on the workspace that unlocks the auto-loop toggle in the UI. Do NOT call during normal sessions.',
             inputSchema: { type: 'object', properties: {}, required: [] },
+            annotations: { destructiveHint: false, openWorldHint: false },
         },
         {
             name: 'create_task',
@@ -150,6 +153,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
                 required: ['title'],
             },
+            annotations: { destructiveHint: false, openWorldHint: false },
         },
         {
             name: 'update_task',
@@ -171,6 +175,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
                 required: ['task_id'],
             },
+            annotations: { destructiveHint: false, openWorldHint: false },
         },
         {
             name: 'delete_task',
@@ -182,11 +187,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
                 required: ['task_id'],
             },
+            annotations: { destructiveHint: false, openWorldHint: false },
         },
         {
             name: 'get_workspace_info',
             description: 'CALL EARLY in a session to confirm project path, working/source branch, worktree path, model, and notion link. Cheap read — useful when the user refers to "this workspace" or when you need the worktree path to locate files.',
             inputSchema: { type: 'object', properties: {}, required: [] },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         },
         {
             name: 'set_workspace_agent_description',
@@ -201,6 +208,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
                 required: ['description'],
             },
+            annotations: { destructiveHint: false, openWorldHint: false },
         },
         {
             name: 'cron_create',
@@ -232,6 +240,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
                 required: ['expression', 'prompt'],
             },
+            annotations: { destructiveHint: false, openWorldHint: false },
         },
         {
             name: 'cron_delete',
@@ -243,16 +252,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
                 required: ['id'],
             },
+            annotations: { destructiveHint: false, openWorldHint: false },
         },
         {
             name: 'cron_list',
             description: 'List all crons currently armed on THIS workspace, including their next and last fire times.',
             inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         },
         {
             name: 'get_git_info',
             description: 'CALL BEFORE creating a PR, committing in batches, or reporting progress to the user. Returns commit count ahead of source, files changed, insertions/deletions, and existing PR URL if any.',
             inputSchema: { type: 'object', properties: {}, required: [] },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         },
         {
             name: 'set_workspace_status',
@@ -268,26 +280,31 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
                 required: ['status'],
             },
+            annotations: { destructiveHint: false, openWorldHint: false },
         },
         {
             name: 'get_notion_ticket',
             description: 'CALL when the user references "the ticket", "the Notion page", or when you need the source-of-truth text for the mission. Returns the Notion URL + locally-extracted ticket content from .ai/thoughts/.',
             inputSchema: { type: 'object', properties: {}, required: [] },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         },
         {
             name: 'get_dev_server_status',
             description: 'CALL BEFORE asking the user whether the app is running, or when your change is dev-server-sensitive. Returns running/stopped/starting/error + URL, port, container names.',
             inputSchema: { type: 'object', properties: {}, required: [] },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         },
         {
             name: 'start_dev_server',
             description: 'CALL WHEN the user asks you to test the running app and the dev server is stopped.',
             inputSchema: { type: 'object', properties: {}, required: [] },
+            annotations: { destructiveHint: false, openWorldHint: false },
         },
         {
             name: 'stop_dev_server',
             description: 'CALL WHEN the user explicitly asks to stop the dev server, or before destructive operations that require a clean boot.',
             inputSchema: { type: 'object', properties: {}, required: [] },
+            annotations: { destructiveHint: false, openWorldHint: false },
         },
         {
             name: 'get_dev_server_logs',
@@ -299,11 +316,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
                 required: [],
             },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         },
         {
             name: 'list_workspace_images',
             description: 'CALL WHEN the user mentions "the screenshot", "the attached image", or when you need to reference a previously-uploaded image. Returns uid, originalName, relativePath, createdAt for every image in .ai/images/.',
             inputSchema: { type: 'object', properties: {}, required: [] },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         },
         {
             name: 'get_settings',
@@ -318,12 +337,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
                 required: [],
             },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         },
         // ── Knowledge / context tools ─────────────────────────────────────────────
         {
             name: 'list_documents',
             description: 'CALL EARLY on a new session to discover plans, specs, and thoughts previously written for this workspace. Recursively lists every .md under docs/plans/, docs/superpowers/, and .ai/thoughts/. Before writing a new plan, check if one already exists.',
             inputSchema: { type: 'object', properties: {}, required: [] },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         },
         {
             name: 'read_document',
@@ -338,6 +359,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
                 required: ['path'],
             },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         },
         {
             name: 'log_thought',
@@ -354,6 +376,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
                 required: ['title', 'content'],
             },
+            annotations: { destructiveHint: false, openWorldHint: false },
         },
         {
             name: 'search_codebase',
@@ -375,11 +398,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
                 required: ['query'],
             },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         },
         {
             name: 'get_session_usage',
             description: 'CALL when you need to self-regulate on long missions — returns token/cost totals for the workspace lifetime and for the currently running agent_session. Useful before spawning heavy subagents or deep reasoning on already-expensive sessions.',
             inputSchema: { type: 'object', properties: {}, required: [] },
+            annotations: { readOnlyHint: true, openWorldHint: false },
         },
         {
             name: 'schedule_wakeup',
@@ -402,11 +427,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
                 required: ['delaySeconds', 'prompt'],
             },
+            annotations: { destructiveHint: false, openWorldHint: false },
         },
         {
             name: 'cancel_wakeup',
             description: 'CALL to cancel any pending wakeup on this workspace (e.g. the condition you were waiting on resolved early, or you decided not to continue). Idempotent — safe to call when nothing is pending.',
             inputSchema: { type: 'object', properties: {}, required: [] },
+            annotations: { destructiveHint: false, openWorldHint: false },
         },
     ],
 }));

package/dist/server/routes/health.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import { Hono } from 'hono';
 import { getDb } from '../db/index.js';
 import { SCHEMA_VERSION } from '../db/migrations.js';
+import { resolveCodexBinary } from '../services/agent/engines/codex/spawn.js';
 import { getGlobalSettings, getProjectSettings, SETTINGS_SCHEMA_VERSION } from '../services/settings-service.js';
 import { getDbPath, getKoboHome } from '../utils/paths.js';
 import { slugifyProjectName } from '../utils/project-slug.js';
@@ -19,6 +20,18 @@ function checkClaudeCli() {
         return { available: false, version: null };
     }
 }
+function checkCodexCli() {
+    try {
+        const bin = resolveCodexBinary();
+        const r = spawnSync(bin, ['--version'], { encoding: 'utf-8' });
+        if (r.error || r.status !== 0)
+            return { available: false, version: null };
+        return { available: true, version: (r.stdout ?? '').trim() || null };
+    }
+    catch {
+        return { available: false, version: null };
+    }
+}
 function isProcessAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -142,6 +155,7 @@ app.get('/report', (c) => {
         },
         settings: { schemaVersion: SETTINGS_SCHEMA_VERSION },
         claudeCli: checkClaudeCli(),
+        codexCli: checkCodexCli(),
         workspaces: {
             total: settingsRow.n,
             archived: archivedRow.n,

package/dist/server/routes/workspaces.js

@@ -42,18 +42,16 @@ function isAgentPermissionMode(value) {
  *
  * Cascade: explicit body field → global default (validated) → 'bypass'.
  *
- * Legacy `defaultPermissionMode` values ('plan' / 'auto-accept') are honored:
- * 'plan' stays 'plan'; 'auto-accept' falls through to 'bypass' (the safest
- * non-plan default — matches the pre-refactor "skip prompts" behaviour).
+ * The per-engine default lives in `defaultPermissionModeByEngine[engineId]`
+ * (added in settings v20). If the engine id is missing or its entry is invalid,
+ * we fall back to 'bypass' (the safest non-plan default).
  */
-function resolveCreateAgentPermissionMode(bodyValue, _projectPath, globalSettings) {
+function resolveCreateAgentPermissionMode(bodyValue, _projectPath, globalSettings, engineId) {
     if (isAgentPermissionMode(bodyValue))
         return bodyValue;
-    const global = globalSettings.defaultPermissionMode;
+    const global = globalSettings.defaultPermissionModeByEngine?.[engineId];
     if (isAgentPermissionMode(global))
         return global;
-    if (global === 'plan')
-        return 'plan';
     return 'bypass';
 }
 app.get('/', (c) => {
@@ -82,10 +80,25 @@ app.post('/', migrationGuard, async (c) => {
         // engine is rejected up-front so we don't create orphan workspaces that
         // can't spawn an agent.
         if (body.engine) {
-            const validEngineIds = listEngines().map((e) => e.id);
+            const engines = listEngines();
+            const validEngineIds = engines.map((e) => e.id);
             if (!validEngineIds.includes(body.engine)) {
                 return c.json({ error: `Unknown engine '${body.engine}'. Valid engines: ${validEngineIds.join(', ')}` }, 400);
             }
+            // Cross-validate engine × permission mode: each engine declares which
+            // modes it supports via `capabilities.permissionModes`. The UI already
+            // filters, but API consumers can still send any combo. Reject up-front
+            // so we don't park workspaces in a permanently broken state (e.g. Codex
+            // workspaces with `interactive` mode hang on the first tool call).
+            if (body.agentPermissionMode) {
+                const engine = engines.find((e) => e.id === body.engine);
+                const supported = engine?.capabilities.permissionModes ?? [];
+                if (!supported.includes(body.agentPermissionMode)) {
+                    return c.json({
+                        error: `Engine '${body.engine}' does not support agentPermissionMode '${body.agentPermissionMode}'. Supported: ${supported.join(', ')}`,
+                    }, 400);
+                }
+            }
         }
         // Fetch the source branch from origin first — if this fails, block creation
         // immediately (no DB records created, user stays on the create page).
@@ -222,7 +235,7 @@ app.post('/', migrationGuard, async (c) => {
             worktreeOwned: !useReusedWorktree,
             model: body.model,
             reasoningEffort: body.reasoningEffort,
-            agentPermissionMode: resolveCreateAgentPermissionMode(body.agentPermissionMode, body.projectPath, globalSettings),
+            agentPermissionMode: resolveCreateAgentPermissionMode(body.agentPermissionMode, body.projectPath, globalSettings, body.engine ?? 'claude-code'),
             engine: body.engine,
             ...(useReusedWorktree ? {} : { worktreesPath: globalSettings.worktreesPath }),
         });
@@ -1451,6 +1464,17 @@ app.patch('/:id', migrationGuard, async (c) => {
             if (!isAgentPermissionMode(body.agentPermissionMode)) {
                 return c.json({ error: `Invalid agentPermissionMode. Must be one of: ${VALID_AGENT_PERMISSION_MODES.join(', ')}` }, 400);
             }
+            // Cross-validate against the engine's declared capabilities — see the
+            // POST route for the same guard. Prevents parking a workspace in a mode
+            // its engine cannot honour.
+            const engineId = workspace.engine;
+            const engine = listEngines().find((e) => e.id === engineId);
+            const supported = engine?.capabilities.permissionModes ?? [];
+            if (engine && !supported.includes(body.agentPermissionMode)) {
+                return c.json({
+                    error: `Engine '${engineId}' does not support agentPermissionMode '${body.agentPermissionMode}'. Supported: ${supported.join(', ')}`,
+                }, 400);
+            }
             updated = workspaceService.updateAgentPermissionMode(id, body.agentPermissionMode);
         }
         if (body.status) {

package/dist/server/services/agent/engines/claude-code/capabilities.js

@@ -4,14 +4,21 @@ export const CLAUDE_CODE_CAPABILITIES = {
     // ONE source of truth, consumed both by this file (for /api/engines and
     // for validation in POST /api/workspaces) and by the frontend selectors.
     models: CLAUDE_MODELS.map((m) => ({ id: m.id, label: m.label })),
+    // Reasoning effort values passed verbatim via `options.extraArgs.effort` to
+    // the Claude SDK. `auto` is a Kōbō sentinel meaning "let the SDK pick its
+    // default" (we omit the arg).
     effortLevels: [
         { id: 'auto', label: 'Auto' },
         { id: 'low', label: 'Low' },
         { id: 'medium', label: 'Medium' },
         { id: 'high', label: 'High' },
+        { id: 'xhigh', label: 'Extra High' },
+        { id: 'max', label: 'Max' },
     ],
     permissionModes: ['plan', 'bypass', 'strict', 'interactive'],
     supportsResume: true,
     supportsMcp: true,
     supportsSkills: true,
+    supportsSubagents: true,
+    supportsQuotaStatus: true,
 };

package/dist/server/services/agent/engines/codex/capabilities.js

@@ -0,0 +1,18 @@
+import { CODEX_MODELS } from '../../../../../shared/codex-models.js';
+export const CODEX_CAPABILITIES = {
+    models: CODEX_MODELS.map((m) => ({ id: m.id, label: m.label })),
+    effortLevels: [
+        { id: 'auto', label: 'Auto' },
+        { id: 'minimal', label: 'Minimal' },
+        { id: 'low', label: 'Low' },
+        { id: 'medium', label: 'Medium' },
+        { id: 'high', label: 'High' },
+        { id: 'xhigh', label: 'Extra High' },
+    ],
+    permissionModes: ['plan', 'bypass', 'strict', 'interactive'],
+    supportsResume: true,
+    supportsMcp: true,
+    supportsSkills: false,
+    supportsSubagents: true,
+    supportsQuotaStatus: true,
+};

package/dist/server/services/agent/engines/codex/client.js

@@ -0,0 +1,36 @@
+import { createJsonRpcPeer } from './jsonrpc/peer.js';
+export function createAppServerClient(opts) {
+    const peer = createJsonRpcPeer({
+        stdin: opts.stdin,
+        stdout: opts.stdout,
+        onNotification: opts.onNotification ?? (() => { }),
+        onServerRequest: opts.onServerRequest ?? (() => { }),
+        onError: opts.onError,
+    });
+    return {
+        peer,
+        async connect() {
+            // Without experimentalApi the server rejects collaborationMode (-32600).
+            const params = {
+                clientInfo: opts.clientInfo,
+                capabilities: { experimentalApi: true },
+            };
+            return peer.request('initialize', params);
+        },
+        startThread(params) {
+            return peer.request('thread/start', params);
+        },
+        resumeThread(params) {
+            return peer.request('thread/resume', params);
+        },
+        startTurn(params) {
+            return peer.request('turn/start', params);
+        },
+        async interruptTurn(params) {
+            await peer.request('turn/interrupt', params);
+        },
+        close() {
+            peer.close();
+        },
+    };
+}