@loicngr/kobo 1.6.0 → 1.6.1

package/AGENTS.md

@@ -58,7 +58,12 @@ src/
 │   │   └── migrations.ts           # incremental migrations, bumped per feature
 │   ├── services/                   # business logic — pure functions over db + external processes
 │   │   ├── workspace-service.ts    # workspaces + tasks + agent_sessions CRUD
-│   │   ├── agent-manager.ts        # spawns Claude Code CLI, streams stdout, tracks sessions, interrupt/stop
+│   │   ├── agent/                  # agent engine abstraction (replaces former agent-manager.ts)
+│   │   │   ├── orchestrator.ts     # per-workspace engine map, retry/quota handling, watchdog, public API
+│   │   │   ├── session-controller.ts # lifecycle wrapper around an AgentEngine instance
+│   │   │   ├── event-router.ts     # maps engine AgentEvent stream to WS emit + DB side-effects
+│   │   │   └── engines/claude-code/ # Claude Code engine (spawn + stream-parser + args-builder + mcp-config + capabilities)
+│   │   ├── content-migration-service.ts # runtime legacy ws_events → normalised AgentEvent migration
 │   │   ├── templates-service.ts    # prompt templates CRUD (JSON file persistence, seeding)
 │   │   ├── dev-server-service.ts   # per-workspace dev server lifecycle (docker or npm process)
 │   │   ├── websocket-service.ts    # emit / emitEphemeral to subscribed clients

package/README.md

@@ -4,8 +4,10 @@
 
 > [!WARNING]
 > 🚧 **Work in progress** — This project is under active development. Breaking changes may occur at any time.
+> ⚠️ **Planned refactor with potential data loss** — A major refactor is planned and may require database/schema changes that can cause data loss.
+> ❌ **Do not use in production** until this refactor is complete and a stable migration path is documented.
 >
-> **Engine refactor planned.** Kōbō currently drives the `claude` CLI via `spawn(..., ['-p', ...])` and parses stdout, which is brittle on edge cases (interrupts, long-running sessions, MCP lifecycle, tool-use streaming). A rewrite is planned to use the [Claude Agent SDK](https://docs.anthropic.com/en/docs/agents-and-tools/claude-agent-sdk/overview) directly so the agent runs in-process, with proper streaming primitives, structured tool-use events, and cleaner interrupt / resume semantics. Expect churn in `src/server/services/agent-manager.ts` and the WebSocket event shape during that migration.
+> **Engine refactor in progress.** The legacy `agent-manager.ts` has been split into an agent engine abstraction (`src/server/services/agent/`) with a pluggable `AgentEngine` contract, a shared `Orchestrator`, and a normalised `AgentEvent` stream. The Claude Code CLI is now one engine among potentially several (`src/server/services/agent/engines/claude-code/`). A runtime migration (`content-migration-service.ts`) converts legacy `ws_events` into the new normalised form on first boot after upgrade; **a timestamped copy of `kobo.db` is written alongside it before the migration runs**, so you can roll back by restoring the backup if anything goes sideways. Expect continued churn until the WebSocket event surface and UI stream reducers stabilise.
 
 Kōbō lets you delegate multiple coding missions to Claude Code agents in parallel. Each workspace lives in its own isolated git worktree with its own branch, its own Claude session, optionally its own dev server, and a custom MCP tools server the agent uses to track progress. A Vue 3 dashboard shows live agent output, tasks, acceptance criteria, and git state across every workspace.
 
@@ -92,7 +94,9 @@ npm start           # runs the compiled server
 ### Test & lint
 
 ```bash
-npm test            # full vitest suite (366+ tests)
+npm test            # backend vitest suite (740+ tests)
+npm run test:client # client vitest suite (Pinia stores + pure utils, 85+ tests)
+npm run test:all    # backend + client suites
 npm run lint        # biome check (lint + format verification)
 npm run lint:fix    # biome check with safe auto-fixes
 npm run format      # biome format --write
@@ -207,22 +211,31 @@ Then start a new workspace in Kōbō — the agent will pick up the skills autom
 
 ```
 src/
-├── server/                         # Hono backend
-│   ├── index.ts                    # app bootstrap + WS upgrade
-│   ├── db/                         # SQLite schema and singleton
-│   ├── services/                   # business logic (workspace, agent, dev-server, ws, notion, settings, pr-template)
-│   ├── routes/                     # Hono handlers
-│   └── utils/                      # git-ops, process-tracker
-├── client/                         # Vue 3 + Quasar SPA
+├── server/                                 # Hono backend
+│   ├── index.ts                            # app bootstrap + WS upgrade
+│   ├── db/                                 # SQLite schema, migrations, singleton
+│   ├── services/
+│   │   ├── agent/                          # agent engine abstraction (replaces agent-manager.ts)
+│   │   │   ├── orchestrator.ts             # per-workspace engine map, retry/quota, watchdog, public API
+│   │   │   ├── session-controller.ts       # lifecycle wrapper around one AgentEngine instance
+│   │   │   ├── event-router.ts             # maps engine AgentEvent stream to WS emit + DB side-effects
+│   │   │   └── engines/claude-code/        # spawn + NDJSON stream-parser + args-builder + mcp-config + capabilities
+│   │   ├── content-migration-service.ts    # legacy ws_events → normalised AgentEvent rows, with DB backup
+│   │   └── …                               # workspace, dev-server, ws, notion, sentry, settings, pr-template
+│   ├── routes/                             # Hono handlers (workspaces, engines, migration, templates, …)
+│   └── utils/                              # git-ops, process-tracker, paths
+├── shared/                                 # modules shared by backend and frontend (e.g. model catalogue)
+├── client/                                 # Vue 3 + Quasar SPA
 │   └── src/
-│       ├── stores/                 # Pinia state management
-│       ├── components/             # WorkspaceList, NotionPanel, ChatInput, GitPanel, …
-│       ├── pages/                  # WorkspacePage, CreatePage, SettingsPage
+│       ├── stores/                         # Pinia: workspace, websocket, agent-stream, migration, settings, …
+│       ├── components/                     # ActivityFeed, TurnCard, WorkspaceList, ChatInput, GitPanel, …
+│       ├── services/                       # agent-event-view (foldEvents), conversation-turns (groupIntoTurns), inline-diff
+│       ├── pages/                          # WorkspacePage, CreatePage, SettingsPage
 │       └── router/
-├── mcp-server/                     # Standalone MCP server spawned per workspace
-│   ├── kobo-tasks-server.ts        # entry point, registers list_tasks & mark_task_done
-│   └── kobo-tasks-handlers.ts      # pure handlers over SQLite
-└── __tests__/                      # Vitest suite
+├── mcp-server/                             # standalone MCP server spawned per workspace
+│   ├── kobo-tasks-server.ts                # entry point, registers list_tasks & mark_task_done
+│   └── kobo-tasks-handlers.ts              # pure handlers over SQLite
+└── __tests__/                              # Vitest suite (engines, orchestrator, migration, routes, …)
 ```
 
 See [`AGENTS.md`](./AGENTS.md) for a deeper dive into conventions, data model, WebSocket protocol, and contribution guidelines.

package/dist/server/db/index.js

@@ -1,9 +1,17 @@
+import os from 'node:os';
+import path from 'node:path';
 import Database from 'better-sqlite3';
 import { ensureKoboHome, getDbPath } from '../utils/paths.js';
 let instance = null;
 /**
  * Return the singleton SQLite database connection, creating it on first call.
  * Configures WAL mode, busy timeout, and foreign keys.
+ *
+ * Safety guard: when running under vitest, refuse to open any DB located
+ * under the user's real home directory. If the caller didn't pass a
+ * custom path AND KOBO_HOME wasn't pinned to a temp dir, the vitest
+ * global setup is misconfigured — better to fail loudly than to silently
+ * mutate production data.
  */
 export function getDb(dbPath) {
     if (instance)
@@ -13,6 +21,15 @@ export function getDb(dbPath) {
         ensureKoboHome();
         resolvedPath = getDbPath();
     }
+    if (process.env.VITEST) {
+        const home = os.homedir();
+        const resolved = path.resolve(resolvedPath);
+        if (resolved.startsWith(home) && !resolved.startsWith(path.resolve(os.tmpdir()))) {
+            throw new Error(`[kobo-db] Refusing to open production DB under a user home directory while VITEST is active: ${resolved}. ` +
+                `This is a safety guard against tests leaking into the developer's ~/.config/kobo/. ` +
+                `Ensure vitest.setup.ts sets KOBO_HOME to a tmp directory, or pass an explicit dbPath to getDb().`);
+        }
+    }
     instance = new Database(resolvedPath);
     instance.pragma('journal_mode=WAL');
     instance.pragma('busy_timeout=5000');

package/dist/server/db/migrations.js

@@ -78,6 +78,16 @@ export const migrations = [
             db.prepare("ALTER TABLE workspaces ADD COLUMN tags TEXT NOT NULL DEFAULT '[]'").run();
         },
     },
+    {
+        version: 10,
+        name: 'agent-engine-abstraction',
+        migrate: (db) => {
+            db.transaction(() => {
+                db.prepare("ALTER TABLE workspaces ADD COLUMN engine TEXT NOT NULL DEFAULT 'claude-code'").run();
+                db.prepare('ALTER TABLE agent_sessions RENAME COLUMN claude_session_id TO engine_session_id').run();
+            })();
+        },
+    },
 ];
 /** Current schema version — always equals the highest migration version. */
 export const SCHEMA_VERSION = migrations.length > 0 ? migrations[migrations.length - 1].version : 1;

package/dist/server/db/schema.js

@@ -18,6 +18,7 @@ export function initSchema(db) {
       archived_at TEXT,
       favorited_at TEXT,
       tags TEXT NOT NULL DEFAULT '[]',
+      engine TEXT NOT NULL DEFAULT 'claude-code',
       created_at TEXT NOT NULL,
       updated_at TEXT NOT NULL
     );
@@ -37,7 +38,7 @@ export function initSchema(db) {
       id TEXT PRIMARY KEY,
       workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
       pid INTEGER,
-      claude_session_id TEXT,
+      engine_session_id TEXT,
       status TEXT NOT NULL DEFAULT 'running',
       started_at TEXT NOT NULL,
       ended_at TEXT,

package/dist/server/index.js

@@ -8,9 +8,11 @@ import WebSocket, { WebSocketServer } from 'ws';
 import { closeDb, getDb } from './db/index.js';
 import { runMigrations } from './db/migrations.js';
 import devServerRouter from './routes/dev-server.js';
+import { enginesRouter } from './routes/engines.js';
 import gitRouter from './routes/git.js';
 import healthRouter from './routes/health.js';
 import imagesRouter from './routes/images.js';
+import { migrationRouter } from './routes/migration.js';
 import notionRouter from './routes/notion.js';
 import plansRouter from './routes/plans.js';
 import searchRouter from './routes/search.js';
@@ -18,7 +20,8 @@ import sentryRouter from './routes/sentry.js';
 import settingsRouter from './routes/settings.js';
 import templatesRouter from './routes/templates.js';
 import workspacesRouter from './routes/workspaces.js';
-import { getAvailableSkills, sendMessage, setBackendPort, startAgent, startWatchdog, stopAgent, stopWatchdog, } from './services/agent-manager.js';
+import { getAvailableSkills, reconcileOrphanSessions, sendMessage, setBackendPort, startAgent, startWatchdog, stopAgent, stopWatchdog, } from './services/agent/orchestrator.js';
+import { runContentMigrationIfNeeded } from './services/content-migration-service.js';
 import { createDailyDbBackupIfNeeded } from './services/db-backup-service.js';
 import { startDevServer, stopDevServer } from './services/dev-server-service.js';
 import { startPrWatcher, stopPrWatcher } from './services/pr-watcher-service.js';
@@ -52,6 +55,7 @@ void createDailyDbBackupIfNeeded(db, getDbPath()).then((r) => {
 });
 // Initialize process cleanup, agent watchdog, and PR watcher
 initProcessCleanup();
+reconcileOrphanSessions();
 startWatchdog();
 startPrWatcher();
 // Create Hono app
@@ -70,6 +74,8 @@ app.route('/api/templates', templatesRouter);
 app.route('/api/workspaces', plansRouter);
 app.route('/api/search', searchRouter);
 app.route('/api/health', healthRouter);
+app.route('/api/engines', enginesRouter);
+app.route('/api/migration', migrationRouter);
 // Skills endpoint
 app.get('/api/skills', (c) => c.json(getAvailableSkills()));
 const PORT = parseInt(process.env.SERVER_PORT || process.env.PORT || '3000', 10);
@@ -120,6 +126,13 @@ const server = serve({
 }, (info) => {
     setBackendPort(info.port);
     console.log(`Server running at http://localhost:${info.port}`);
+    // Content migration runs AFTER the HTTP listener is up so the frontend
+    // can observe progress via WS broadcasts + GET /api/migration/status.
+    // Not awaited — the callback returns quickly, the migration runs in the
+    // background.
+    void runContentMigrationIfNeeded(getDb(), getDbPath()).catch((err) => {
+        console.error('[boot] content migration failed:', err);
+    });
 });
 // Create WebSocketServer attached to the HTTP server
 const wss = new WebSocketServer({ noServer: true });
@@ -212,7 +225,7 @@ terminalWss.on('connection', (ws, workspaceId) => {
         }
     });
 });
-// Wire websocket-service message handler to agent-manager
+// Wire websocket-service message handler to the agent orchestrator
 setMessageHandler((type, payload) => {
     const p = payload;
     if (type === 'chat:message' && p?.workspaceId && p?.content) {
@@ -226,7 +239,15 @@ setMessageHandler((type, payload) => {
         try {
             sendMessage(p.workspaceId, p.content);
         }
-        catch {
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            // Only resume on the specific "No agent running" path. Other errors
+            // (stdin closed, process dead mid-write, etc.) should surface to the
+            // logs instead of silently respawning a fresh agent.
+            if (!msg.includes('No agent running')) {
+                console.error(`[ws] chat:message failed for workspace ${p.workspaceId}:`, err);
+                return;
+            }
             // Agent not running — resume the session hinted by the client if any,
             // otherwise the most-recent active session.
             try {

package/dist/server/middleware/migration-guard.js

@@ -0,0 +1,15 @@
+import { getContentMigrationStatus } from '../services/content-migration-service.js';
+/**
+ * Blocks mutating requests while the content migration is running.
+ *
+ * Returns 503 with `{ error: 'migration-in-progress' }` whenever the migration
+ * state is anything other than `idle` or `done`. Mounted per-handler on routes
+ * that write to `ws_events` or spawn agents so the user can still observe
+ * progress through GETs and `/api/migration/status` while the migration runs.
+ */
+export const migrationGuard = async (c, next) => {
+    const state = getContentMigrationStatus().state;
+    if (state === 'idle' || state === 'done')
+        return next();
+    return c.json({ error: 'migration-in-progress' }, 503);
+};

package/dist/server/routes/dev-server.js

@@ -1,4 +1,5 @@
 import { Hono } from 'hono';
+import { migrationGuard } from '../middleware/migration-guard.js';
 import { getDevServerLogs, getStatus, startDevServer, stopDevServer } from '../services/dev-server-service.js';
 import { getWorkspace } from '../services/workspace-service.js';
 /** Hono sub-router for per-workspace dev server lifecycle (start, stop, status, logs). */
@@ -24,7 +25,7 @@ app.get('/:workspaceId/status', (c) => {
     }
 });
 // POST /api/dev-server/:workspaceId/start
-app.post('/:workspaceId/start', (c) => {
+app.post('/:workspaceId/start', migrationGuard, (c) => {
     try {
         const workspaceId = c.req.param('workspaceId');
         const workspace = getWorkspace(workspaceId);
@@ -40,7 +41,7 @@ app.post('/:workspaceId/start', (c) => {
     }
 });
 // POST /api/dev-server/:workspaceId/stop
-app.post('/:workspaceId/stop', (c) => {
+app.post('/:workspaceId/stop', migrationGuard, (c) => {
     try {
         const workspaceId = c.req.param('workspaceId');
         const workspace = getWorkspace(workspaceId);

package/dist/server/routes/engines.js

@@ -0,0 +1,9 @@
+import { Hono } from 'hono';
+import { listEngines } from '../services/agent/engines/registry.js';
+/** Hono sub-router exposing `GET /` — the list of registered agent engines with capabilities. */
+export const enginesRouter = new Hono();
+enginesRouter.get('/', (c) => c.json(listEngines().map((e) => ({
+    id: e.id,
+    displayName: e.displayName,
+    capabilities: e.capabilities,
+}))));

package/dist/server/routes/migration.js

@@ -0,0 +1,5 @@
+import { Hono } from 'hono';
+import { getContentMigrationStatus } from '../services/content-migration-service.js';
+/** Hono sub-router exposing `GET /status` for the runtime content migration. */
+export const migrationRouter = new Hono();
+migrationRouter.get('/status', (c) => c.json(getContentMigrationStatus()));

package/dist/server/routes/workspaces.js

@@ -5,7 +5,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { Hono } from 'hono';
 import { getDb } from '../db/index.js';
-import * as agentManager from '../services/agent-manager.js';
+import { migrationGuard } from '../middleware/migration-guard.js';
+import { listEngines } from '../services/agent/engines/registry.js';
+import * as agentManager from '../services/agent/orchestrator.js';
 import * as devServerService from '../services/dev-server-service.js';
 import * as notionService from '../services/notion-service.js';
 import { renderPrTemplate } from '../services/pr-template-service.js';
@@ -32,12 +34,21 @@ app.get('/', (c) => {
     }
 });
 // POST /api/workspaces — create workspace
-app.post('/', async (c) => {
+app.post('/', migrationGuard, async (c) => {
     try {
         const body = await c.req.json();
         if (!body.name || !body.projectPath || !body.sourceBranch || !body.workingBranch) {
             return c.json({ error: 'Missing required fields: name, projectPath, sourceBranch, workingBranch' }, 400);
         }
+        // Validate the engine id (if provided) against the registry. An unknown
+        // 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);
+            if (!validEngineIds.includes(body.engine)) {
+                return c.json({ error: `Unknown engine '${body.engine}'. Valid engines: ${validEngineIds.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).
         try {
@@ -61,6 +72,7 @@ app.post('/', async (c) => {
             model: body.model,
             reasoningEffort: body.reasoningEffort,
             permissionMode: body.permissionMode || globalSettings.defaultPermissionMode || 'plan',
+            engine: body.engine,
         });
         let notionContent = null;
         let sentryContent = null;
@@ -446,7 +458,7 @@ app.post('/', async (c) => {
     }
 });
 // POST /api/workspaces/:id/sessions — create a new idle agent session
-app.post('/:id/sessions', (c) => {
+app.post('/:id/sessions', migrationGuard, (c) => {
     try {
         const id = c.req.param('id');
         const workspace = workspaceService.getWorkspace(id);
@@ -803,7 +815,7 @@ app.put('/:id/tags', async (c) => {
     }
 });
 // PATCH /api/workspaces/:id — update workspace fields (status, model, permissionMode, name)
-app.patch('/:id', async (c) => {
+app.patch('/:id', migrationGuard, async (c) => {
     try {
         const id = c.req.param('id');
         const body = await c.req.json();
@@ -930,7 +942,7 @@ app.post('/:id/run-setup-script', async (c) => {
     }
 });
 // POST /api/workspaces/:id/archive — mark workspace as archived (soft-delete)
-app.post('/:id/archive', (c) => {
+app.post('/:id/archive', migrationGuard, (c) => {
     try {
         const id = c.req.param('id');
         const workspace = workspaceService.getWorkspace(id);
@@ -969,7 +981,7 @@ app.post('/:id/archive', (c) => {
     }
 });
 // POST /api/workspaces/:id/unarchive — restore an archived workspace
-app.post('/:id/unarchive', (c) => {
+app.post('/:id/unarchive', migrationGuard, (c) => {
     try {
         const id = c.req.param('id');
         const workspace = workspaceService.getWorkspace(id);
@@ -989,7 +1001,7 @@ app.post('/:id/unarchive', (c) => {
     }
 });
 // DELETE /api/workspaces/:id — delete workspace
-app.delete('/:id', async (c) => {
+app.delete('/:id', migrationGuard, async (c) => {
     try {
         const id = c.req.param('id');
         const workspace = workspaceService.getWorkspace(id);
@@ -1053,13 +1065,25 @@ app.delete('/:id', async (c) => {
     }
 });
 // POST /api/workspaces/:id/start — start/restart agent
-app.post('/:id/start', async (c) => {
+app.post('/:id/start', migrationGuard, async (c) => {
     try {
         const id = c.req.param('id');
         const workspace = workspaceService.getWorkspace(id);
         if (!workspace) {
             return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
+        // If the workspace declares an engine, ensure it is still registered.
+        // Otherwise startAgent() would throw from deep inside resolveEngine and
+        // surface as an opaque 500 — better to fail fast with a clear 400.
+        const workspaceEngine = workspace.engine;
+        if (workspaceEngine) {
+            const validEngineIds = listEngines().map((e) => e.id);
+            if (!validEngineIds.includes(workspaceEngine)) {
+                return c.json({
+                    error: `Workspace uses engine '${workspaceEngine}' which is no longer available. Recreate or reconfigure the workspace.`,
+                }, 400);
+            }
+        }
         const body = await c.req
             .json()
             .catch(() => ({ prompt: undefined, agentSessionId: undefined, resume: undefined }));
@@ -1269,7 +1293,7 @@ app.post('/:id/git/abort', (c) => {
     }
 });
 /** Hand off merge/rebase conflicts to the workspace agent with an intelligent-resolution prompt. */
-app.post('/:id/git/resolve-with-agent', async (c) => {
+app.post('/:id/git/resolve-with-agent', migrationGuard, async (c) => {
     try {
         const id = c.req.param('id');
         const workspace = workspaceService.getWorkspace(id);
@@ -1489,7 +1513,7 @@ app.post('/:id/mark-read', (c) => {
     }
 });
 // POST /api/workspaces/:id/stop — stop agent
-app.post('/:id/stop', (c) => {
+app.post('/:id/stop', migrationGuard, (c) => {
     try {
         const id = c.req.param('id');
         const workspace = workspaceService.getWorkspace(id);
@@ -1517,7 +1541,7 @@ app.post('/:id/stop', (c) => {
     }
 });
 // POST /api/workspaces/:id/interrupt — soft-interrupt agent (SIGINT, like Escape in Claude Code)
-app.post('/:id/interrupt', (c) => {
+app.post('/:id/interrupt', migrationGuard, (c) => {
     try {
         const id = c.req.param('id');
         const workspace = workspaceService.getWorkspace(id);

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

@@ -0,0 +1,22 @@
+export function buildClaudeArgs(input) {
+    const args = ['--output-format', 'stream-json', '--verbose'];
+    if (input.skipPermissions)
+        args.push('--dangerously-skip-permissions');
+    let prompt = input.prompt;
+    if (input.permissionMode === 'plan') {
+        prompt = `[PLAN MODE] You are in PLAN/READ-ONLY mode. You MUST NOT create, edit, write, or delete any files. Only use read-only tools (Read, Grep, Glob, LS, Bash for read-only commands). Analyze the codebase, plan your approach, and present your findings — but do NOT execute any changes.\n\n${prompt}`;
+    }
+    if (input.model && input.model !== 'auto')
+        args.push('--model', input.model);
+    if (input.effort && input.effort !== 'auto')
+        args.push('--effort', input.effort);
+    if (input.mcpConfigPath)
+        args.push('--mcp-config', input.mcpConfigPath);
+    if (input.resumeFromEngineSessionId) {
+        args.push('--resume', input.resumeFromEngineSessionId, '-p', prompt);
+    }
+    else {
+        args.push('-p', prompt);
+    }
+    return { args, effectivePrompt: prompt };
+}

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

@@ -0,0 +1,17 @@
+import { CLAUDE_MODELS } from '../../../../../shared/models.js';
+export const CLAUDE_CODE_CAPABILITIES = {
+    // Models come from the shared catalogue in `src/shared/models.ts` — the
+    // 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 })),
+    effortLevels: [
+        { id: 'auto', label: 'Auto' },
+        { id: 'low', label: 'Low' },
+        { id: 'medium', label: 'Medium' },
+        { id: 'high', label: 'High' },
+    ],
+    permissionModes: ['auto-accept', 'plan'],
+    supportsResume: true,
+    supportsMcp: true,
+    supportsSkills: true,
+};

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

@@ -0,0 +1,163 @@
+import { spawn } from 'node:child_process';
+import readline from 'node:readline';
+import { buildClaudeArgs } from './args-builder.js';
+import { CLAUDE_CODE_CAPABILITIES } from './capabilities.js';
+import { cleanupMcpConfig, writeMcpConfig } from './mcp-config.js';
+import { createParserState, parseClaudeLine } from './stream-parser.js';
+export function createClaudeCodeEngine() {
+    return {
+        id: 'claude-code',
+        displayName: 'Claude Code',
+        capabilities: CLAUDE_CODE_CAPABILITIES,
+        async start(options, onEvent) {
+            // Write MCP config if any servers requested + engine supports MCP
+            let mcpConfigPath;
+            if (options.mcpServers && options.mcpServers.length > 0) {
+                mcpConfigPath = writeMcpConfig(options.workingDir, options.mcpServers);
+            }
+            const { args } = buildClaudeArgs({
+                prompt: options.prompt,
+                model: options.model,
+                effort: options.effort,
+                permissionMode: options.permissionMode ?? 'auto-accept',
+                skipPermissions: options.settings.dangerouslySkipPermissions ?? true,
+                resumeFromEngineSessionId: options.resumeFromEngineSessionId,
+                mcpConfigPath,
+            });
+            const proc = spawn('claude', args, {
+                cwd: options.workingDir,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            const parserState = createParserState();
+            if (!proc.stdout)
+                throw new Error('Claude process has no stdout');
+            const rl = readline.createInterface({
+                input: proc.stdout,
+                crlfDelay: Number.POSITIVE_INFINITY,
+            });
+            let discoveredSessionId;
+            rl.on('line', (line) => {
+                const { events } = parseClaudeLine(line, parserState);
+                for (const ev of events) {
+                    if (ev.kind === 'session:started')
+                        discoveredSessionId = ev.engineSessionId;
+                    onEvent(ev);
+                }
+            });
+            // Line-buffer stderr so we see one event per log line instead of
+            // arbitrary byte chunks, and restrict quota detection to clear rate-
+            // limit signals (not every occurrence of the word "rate" or "quota").
+            // Non-quota stderr lines are logged to the console but do NOT emit
+            // an error event — this avoids false positives flooding the UI.
+            const stderrRl = proc.stderr
+                ? readline.createInterface({
+                    input: proc.stderr,
+                    crlfDelay: Number.POSITIVE_INFINITY,
+                })
+                : undefined;
+            // Known benign stderr lines from the Claude CLI that should NOT be
+            // logged — they flood the dev console and carry no actionable info.
+            // Strip ANSI color codes before matching.
+            // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escapes by design
+            const stripAnsi = (s) => s.replace(/\u001b\[\d+m/g, '');
+            function isBenignStderr(line) {
+                const cleaned = stripAnsi(line).trim();
+                return /^warning: no stdin data received in \d+s/i.test(cleaned);
+            }
+            stderrRl?.on('line', (line) => {
+                const lower = line.toLowerCase();
+                const isQuota = lower.includes('rate limit exceeded') ||
+                    lower.includes('rate_limit_exceeded') ||
+                    (lower.includes('429') && lower.includes('rate')) ||
+                    lower.includes('quota exceeded');
+                if (isQuota) {
+                    onEvent({ kind: 'error', category: 'quota', message: line });
+                }
+                else if (line.trim().length > 0 && !isBenignStderr(line)) {
+                    console.warn(`[claude-engine stderr] ${line}`);
+                }
+            });
+            // 'error' fires when spawn itself fails (e.g. ENOENT if the `claude`
+            // binary is missing from PATH). In that case 'exit' never fires, so we
+            // emit the lifecycle pair here and clean the MCP config ourselves.
+            proc.on('error', (err) => {
+                onEvent({ kind: 'error', category: 'spawn_failed', message: err.message });
+                onEvent({ kind: 'session:ended', reason: 'error', exitCode: null });
+                cleanupMcpConfig(options.workingDir);
+                rl.close();
+                stderrRl?.close();
+            });
+            proc.on('exit', (code) => {
+                cleanupMcpConfig(options.workingDir);
+                rl.close();
+                stderrRl?.close();
+                onEvent({
+                    kind: 'session:ended',
+                    reason: code === 0 ? 'completed' : code === null ? 'killed' : 'error',
+                    exitCode: code,
+                });
+            });
+            const engineProcess = {
+                get pid() {
+                    return proc.pid;
+                },
+                get engineSessionId() {
+                    return discoveredSessionId;
+                },
+                sendMessage(text) {
+                    if (!proc.stdin?.writable)
+                        throw new Error('Agent stdin not writable');
+                    proc.stdin.write(`${text}\n`);
+                },
+                interrupt() {
+                    if (proc.pid !== undefined)
+                        process.kill(proc.pid, 'SIGINT');
+                },
+                stop() {
+                    return new Promise((resolve) => {
+                        if (proc.killed || proc.exitCode !== null)
+                            return resolve();
+                        let resolved = false;
+                        let killTimer;
+                        let hardTimeout;
+                        const doResolve = () => {
+                            if (resolved)
+                                return;
+                            resolved = true;
+                            if (killTimer)
+                                clearTimeout(killTimer);
+                            if (hardTimeout)
+                                clearTimeout(hardTimeout);
+                            resolve();
+                        };
+                        proc.once('exit', doResolve);
+                        try {
+                            proc.kill('SIGTERM');
+                        }
+                        catch {
+                            // Already dead
+                        }
+                        killTimer = setTimeout(() => {
+                            try {
+                                if (!proc.killed)
+                                    proc.kill('SIGKILL');
+                            }
+                            catch {
+                                // Ignore
+                            }
+                        }, 5000);
+                        killTimer.unref?.();
+                        // Hard-timeout safety net: if the process hasn't exited within 10s
+                        // (5s after SIGKILL), resolve anyway so callers never hang forever.
+                        hardTimeout = setTimeout(() => {
+                            console.warn('[claude-engine] stop() hard-timeout reached, resolving anyway');
+                            doResolve();
+                        }, 10000);
+                        hardTimeout.unref?.();
+                    });
+                },
+            };
+            return engineProcess;
+        },
+    };
+}