@loicngr/kobo 1.6.0 → 1.6.2

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;
+        },
+    };
+}

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

@@ -0,0 +1,23 @@
+import { existsSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const MCP_FILENAME = '.mcp.json';
+export function writeMcpConfig(workingDir, servers) {
+    const filePath = join(workingDir, MCP_FILENAME);
+    const mcpServers = {};
+    for (const s of servers) {
+        mcpServers[s.name] = { command: s.command, args: s.args, env: s.env };
+    }
+    writeFileSync(filePath, JSON.stringify({ mcpServers }, null, 2));
+    return filePath;
+}
+export function cleanupMcpConfig(workingDir) {
+    const filePath = join(workingDir, MCP_FILENAME);
+    if (existsSync(filePath)) {
+        try {
+            unlinkSync(filePath);
+        }
+        catch {
+            // Best-effort cleanup
+        }
+    }
+}

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

@@ -0,0 +1,224 @@
+function normalizeResetsAt(raw) {
+    if (typeof raw === 'string' && raw.length > 0)
+        return raw;
+    if (typeof raw === 'number' && Number.isFinite(raw))
+        return new Date(raw * 1000).toISOString();
+    return undefined;
+}
+function extractUsedPct(source) {
+    const raw = (source.utilization ?? source.used_percent ?? source.percent_used ?? source.usedPct);
+    if (typeof raw === 'number' && Number.isFinite(raw))
+        return raw <= 1 ? raw * 100 : raw;
+    const used = source.used ?? source.current ?? source.spent;
+    const limit = source.limit ?? source.max ?? source.allowed;
+    if (typeof used === 'number' && typeof limit === 'number' && limit > 0)
+        return (used / limit) * 100;
+    return null;
+}
+function makeBucket(id, source) {
+    const usedPct = extractUsedPct(source) ?? source.__fallbackPct ?? null;
+    if (usedPct === null)
+        return null;
+    const resetsAt = normalizeResetsAt(source.resets_at ?? source.reset_at ?? source.resetsAt ?? source.resetAt);
+    const label = (typeof source.label === 'string' && source.label) || undefined;
+    const used = source.used ?? source.current ?? source.spent;
+    const limit = source.limit ?? source.max ?? source.allowed;
+    const details = used !== undefined && limit !== undefined ? `${String(used)} / ${String(limit)}` : undefined;
+    return { id, label, usedPct: Math.max(0, Math.min(100, usedPct)), resetsAt, details };
+}
+function normalizeRateLimitInfo(info) {
+    const buckets = [];
+    if (typeof info.rateLimitType === 'string') {
+        const b = makeBucket(info.rateLimitType, { ...info, __fallbackPct: 0 });
+        if (b)
+            buckets.push(b);
+    }
+    if (Array.isArray(info.buckets)) {
+        for (const entry of info.buckets) {
+            if (!entry || typeof entry !== 'object')
+                continue;
+            const obj = entry;
+            const id = (typeof obj.id === 'string' && obj.id) ||
+                (typeof obj.name === 'string' && obj.name) ||
+                (typeof obj.rateLimitType === 'string' && obj.rateLimitType) ||
+                'unknown';
+            const b = makeBucket(id, obj);
+            if (b)
+                buckets.push(b);
+        }
+    }
+    return { buckets };
+}
+export function createParserState() {
+    return { sessionStartedEmitted: false, openMessages: new Map() };
+}
+export function parseClaudeLine(line, state) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return { events: [], state };
+    // The marker can appear as a raw stdout line OR inside an assistant text block.
+    // We detect it in the raw line first so even unparseable lines that contain it
+    // still emit the signal. The assistant-branch handling below catches the
+    // structured case.
+    const markerDetected = trimmed.includes('[BRAINSTORM_COMPLETE]');
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        const events = [{ kind: 'message:raw', content: line }];
+        if (markerDetected)
+            events.push({ kind: 'session:brainstorm-complete' });
+        return { events, state };
+    }
+    const events = [];
+    const type = parsed.type;
+    const subtype = parsed.subtype;
+    const sessionId = typeof parsed.session_id === 'string' ? parsed.session_id : undefined;
+    if (type === 'system') {
+        if (subtype === 'compact' || subtype === 'compact_boundary') {
+            events.push({ kind: 'session:compacted' });
+            return { events, state };
+        }
+        if (subtype === 'rate_limit_event') {
+            const info = parsed.rate_limit_info;
+            if (info && typeof info === 'object') {
+                events.push({ kind: 'rate_limit', info: normalizeRateLimitInfo(info) });
+            }
+            return { events, state };
+        }
+        if (subtype === 'task_started' || subtype === 'task_progress' || subtype === 'task_notification') {
+            const toolCallId = typeof parsed.tool_use_id === 'string' ? parsed.tool_use_id : undefined;
+            if (toolCallId) {
+                const usage = parsed.usage;
+                const taskStatus = typeof parsed.status === 'string' ? parsed.status : undefined;
+                const isDone = subtype === 'task_notification' &&
+                    taskStatus !== undefined &&
+                    ['completed', 'stopped', 'failed', 'cancelled'].includes(taskStatus);
+                events.push({
+                    kind: 'subagent:progress',
+                    toolCallId,
+                    status: isDone ? 'done' : 'running',
+                    description: typeof parsed.description === 'string' ? parsed.description : undefined,
+                    taskType: typeof parsed.task_type === 'string' ? parsed.task_type : undefined,
+                    lastToolName: typeof parsed.last_tool_name === 'string' ? parsed.last_tool_name : undefined,
+                    totalTokens: typeof usage?.total_tokens === 'number' ? usage.total_tokens : undefined,
+                    toolUses: typeof usage?.tool_uses === 'number' ? usage.tool_uses : undefined,
+                    durationMs: typeof usage?.duration_ms === 'number' ? usage.duration_ms : undefined,
+                });
+            }
+            return { events, state };
+        }
+    }
+    if (type === 'system' && subtype === 'init') {
+        if (sessionId && (!state.sessionStartedEmitted || state.sessionId !== sessionId)) {
+            events.push({
+                kind: 'session:started',
+                engineSessionId: sessionId,
+                model: typeof parsed.model === 'string' ? parsed.model : undefined,
+            });
+            state.sessionStartedEmitted = true;
+            state.sessionId = sessionId;
+        }
+        if (Array.isArray(parsed.slash_commands) && parsed.slash_commands.length > 0) {
+            events.push({ kind: 'skills:discovered', skills: parsed.slash_commands });
+        }
+        return { events, state };
+    }
+    if (type === 'assistant') {
+        const message = parsed.message;
+        const messageId = typeof message?.id === 'string' ? message.id : 'unknown';
+        const content = Array.isArray(message?.content) ? message?.content : [];
+        // A new messageId arriving means any previously-open message is done.
+        // Claude CLI's stream-json output doesn't always carry an explicit
+        // `stop_reason` or `message_stop` on the last chunk; some runs finish
+        // implicitly when the next turn begins. Close stale openMessages here
+        // so the UI's streaming spinner doesn't hang forever.
+        for (const openId of Array.from(state.openMessages.keys())) {
+            if (openId !== messageId) {
+                events.push({ kind: 'message:end', messageId: openId });
+                state.openMessages.delete(openId);
+            }
+        }
+        if (!state.openMessages.has(messageId)) {
+            state.openMessages.set(messageId, { sawText: false });
+        }
+        const msgState = state.openMessages.get(messageId);
+        for (const block of content) {
+            const blockType = block.type;
+            if (blockType === 'text' && typeof block.text === 'string') {
+                events.push({ kind: 'message:text', messageId, text: block.text, streaming: true });
+                msgState.sawText = true;
+            }
+            if (blockType === 'tool_use') {
+                events.push({
+                    kind: 'tool:call',
+                    messageId,
+                    toolCallId: typeof block.id === 'string' ? block.id : 'unknown',
+                    name: typeof block.name === 'string' ? block.name : 'unknown',
+                    input: block.input ?? {},
+                });
+            }
+            if (blockType === 'thinking') {
+                events.push({
+                    kind: 'message:thinking',
+                    messageId,
+                    text: typeof block.thinking === 'string' ? block.thinking : '',
+                });
+            }
+            if (blockType === 'text' &&
+                typeof block.text === 'string' &&
+                block.text.includes('[BRAINSTORM_COMPLETE]')) {
+                events.push({ kind: 'session:brainstorm-complete' });
+            }
+        }
+        // Claude CLI sends many intermediate deltas for the same message; most of
+        // them carry `stop_reason: null`. Only a truly terminal event has either
+        // `message_stop: true` at the root, or a non-null `stop_reason`. Checking
+        // `!== undefined` would spuriously emit message:end on every delta.
+        const stopReason = message?.stop_reason;
+        const isStop = parsed.message_stop === true || (stopReason !== undefined && stopReason !== null);
+        if (isStop) {
+            events.push({ kind: 'message:end', messageId });
+            state.openMessages.delete(messageId);
+        }
+        return { events, state };
+    }
+    if (type === 'user') {
+        const message = parsed.message;
+        const content = Array.isArray(message?.content) ? message?.content : [];
+        for (const block of content) {
+            if (block.type === 'tool_result') {
+                events.push({
+                    kind: 'tool:result',
+                    toolCallId: typeof block.tool_use_id === 'string' ? block.tool_use_id : 'unknown',
+                    output: block.content ?? null,
+                    isError: block.is_error === true,
+                });
+            }
+        }
+        return { events, state };
+    }
+    if (type === 'result') {
+        // Terminal event — close any message still considered "streaming".
+        for (const openId of Array.from(state.openMessages.keys())) {
+            events.push({ kind: 'message:end', messageId: openId });
+            state.openMessages.delete(openId);
+        }
+        const usage = parsed.usage;
+        if (usage) {
+            events.push({
+                kind: 'usage',
+                inputTokens: Number(usage.input_tokens ?? 0),
+                outputTokens: Number(usage.output_tokens ?? 0),
+                cacheRead: typeof usage.cache_read_input_tokens === 'number' ? usage.cache_read_input_tokens : undefined,
+                cacheWrite: typeof usage.cache_creation_input_tokens === 'number'
+                    ? usage.cache_creation_input_tokens
+                    : undefined,
+                costUsd: typeof parsed.cost_usd === 'number' ? parsed.cost_usd : undefined,
+            });
+        }
+        return { events, state };
+    }
+    return { events, state };
+}

package/dist/server/services/agent/engines/registry.js

@@ -0,0 +1,21 @@
+import { createClaudeCodeEngine } from './claude-code/engine.js';
+const ENGINES = {
+    'claude-code': createClaudeCodeEngine(),
+};
+export function listEngines() {
+    return Object.values(ENGINES);
+}
+export function resolveEngine(id) {
+    const engine = ENGINES[id];
+    if (!engine)
+        throw new Error(`Unknown agent engine '${id}'`);
+    return engine;
+}
+/**
+ * Test-only seam. Replaces or adds an engine at runtime. Do not use in
+ * production — the static `ENGINES` map is the source of truth; this helper
+ * exists only so unit tests can inject fakes without wiring a DI container.
+ */
+export function _registerEngineForTest(engine) {
+    ENGINES[engine.id] = engine;
+}

package/dist/server/services/agent/engines/types.js

@@ -0,0 +1,18 @@
+/** Every AgentEvent kind, as a const for exhaustive iteration in tests. */
+export const ALL_AGENT_EVENT_KINDS = [
+    'session:started',
+    'session:ended',
+    'session:compacted',
+    'session:brainstorm-complete',
+    'message:text',
+    'message:thinking',
+    'message:end',
+    'message:raw',
+    'tool:call',
+    'tool:result',
+    'subagent:progress',
+    'skills:discovered',
+    'usage',
+    'rate_limit',
+    'error',
+];

package/dist/server/services/agent/event-router.js

@@ -0,0 +1,4 @@
+import { emit } from '../websocket-service.js';
+export function routeEvent(workspaceId, agentSessionId, event) {
+    emit(workspaceId, 'agent:event', event, agentSessionId);
+}