castle-web-cli 0.4.11 → 0.4.13

package/dist/agent.js

@@ -0,0 +1,952 @@
+// Agent panel backend for `castle-web serve`: a conversational "router" agent
+// chats with the user (chat-only -- it never edits files) and spawns
+// background task agents that do the actual deck edits, with maximum
+// concurrency. State lives under .castle/agent/ -- messages.json plus a
+// directory per task -- so the chat survives serve restarts and task agents
+// write progress / notes back through plain files the server polls.
+//
+// One router turn runs at a time: a new user message interrupts the
+// in-flight reply (its partial text stays in the log) and the next turn is
+// told to continue that work plus address the new message. Task lifecycle
+// shows up as small log messages (started / ready for review / completed)
+// instead of extra router turns.
+//
+// Backend CLI: cursor-agent in headless print mode (stream-json). The router
+// runs with --mode ask (read-only at the CLI level); task agents run with
+// --force. Claude support can slot in later behind runAgentCli.
+import { spawn } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { nanoid } from 'nanoid';
+import { WebSocketServer } from 'ws';
+import { rawDataToString } from './ide.js';
+import { buildRouterPrompt, buildTaskPrompt, userTurnInstruction, } from './agent-prompts.js';
+export const AGENT_WS_PATH = '/__castle/agent';
+export const AGENT_ATTACHMENT_PREFIX = '/__castle/agent/attachments/';
+const DEFAULT_SETTINGS = { router: 'claude', tasks: 'claude', claudeModel: 'opus' };
+function normalizeBackend(value) {
+    return value === 'cursor' || value === 'claude' ? value : null;
+}
+function normalizeClaudeModel(value) {
+    return value === 'sonnet' || value === 'opus' || value === 'fable' ? value : null;
+}
+// Build the headless CLI invocation for a backend/role. Cursor's router runs
+// in read-only ask mode; claude runs permission-mode auto for both roles (NOT
+// plan mode -- that makes it emit plan tool calls) at medium effort.
+function buildAgentInvocation(backend, role, prompt, claudeModel) {
+    if (backend === 'claude') {
+        return {
+            command: 'claude',
+            args: [
+                '-p',
+                '--verbose',
+                '--output-format',
+                'stream-json',
+                '--include-partial-messages',
+                '--permission-mode',
+                'auto',
+                '--model',
+                claudeModel,
+                '--effort',
+                'medium',
+                prompt,
+            ],
+        };
+    }
+    return {
+        command: 'cursor-agent',
+        args: [
+            '-p',
+            '--output-format',
+            'stream-json',
+            '--stream-partial-output',
+            '--trust',
+            ...(role === 'router' ? ['--mode', 'ask'] : ['--force']),
+            prompt,
+        ],
+    };
+}
+const ROUTER_TIMEOUT_MS = 3 * 60_000;
+const TASK_TIMEOUT_MS = 30 * 60_000;
+const MAX_TASK_ATTEMPTS = 3;
+const TASK_POLL_MS = 1_000;
+const FENCE_HOLDBACK = '```castle-';
+const RESULT_SUMMARY_CHARS = 600;
+const MAX_ATTACHMENTS = 6;
+const MAX_ATTACHMENT_BYTES = 8 * 1024 * 1024;
+const TERMINAL_STATUSES = ['done', 'failed', 'interrupted'];
+function nowIso() {
+    return new Date().toISOString();
+}
+function isTerminal(status) {
+    return TERMINAL_STATUSES.includes(status);
+}
+function readJsonFile(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+// How much of a router reply is safe to show while it is still streaming:
+// everything before the first castle-task fence, holding back a partial fence
+// marker at the tail so "```cast..." never flashes up before we know what it
+// is. The full cleaned text replaces the streamed text when the reply ends.
+function visibleLength(raw) {
+    const idx = raw.indexOf(FENCE_HOLDBACK);
+    if (idx >= 0)
+        return idx;
+    for (let k = FENCE_HOLDBACK.length - 1; k > 0; k--) {
+        if (raw.endsWith(FENCE_HOLDBACK.slice(0, k)))
+            return raw.length - k;
+    }
+    return raw.length;
+}
+// Pull ```castle-task fenced directives out of a finished router reply.
+// Block format: title line, then optional "after:" / "supersedes:" lines (in
+// either order), then the task prompt.
+function extractDirectives(full) {
+    const directives = [];
+    const checkoffs = [];
+    const doneRe = /```castle-done[ \t]*\r?\n([\s\S]*?)```/g;
+    const withoutDone = full.replace(doneRe, (_match, body) => {
+        for (const token of String(body).split(/[,\n]/)) {
+            const trimmed = token.trim();
+            if (trimmed)
+                checkoffs.push(trimmed);
+        }
+        return '';
+    });
+    const fenceRe = /```castle-task[ \t]*\r?\n([\s\S]*?)```/g;
+    const cleaned = withoutDone.replace(fenceRe, (_match, body) => {
+        const lines = String(body).replace(/\r/g, '').split('\n');
+        const title = (lines.shift() ?? '').trim();
+        const headers = { after: [], supersedes: [] };
+        while (lines.length > 0) {
+            const headerMatch = /^(after|supersedes):\s*(.*)$/i.exec((lines[0] ?? '').trim());
+            if (!headerMatch)
+                break;
+            lines.shift();
+            headers[headerMatch[1].toLowerCase()] = headerMatch[2]
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean);
+        }
+        const prompt = lines.join('\n').trim();
+        if (title) {
+            directives.push({ title, after: headers.after, supersedes: headers.supersedes, prompt });
+        }
+        return '';
+    });
+    return { cleaned: cleaned.replace(/\n{3,}/g, '\n\n').trim(), directives, checkoffs };
+}
+// Claude names tools directly (Read, Edit, Bash, ...).
+function claudeToolActivityLabel(name) {
+    const kind = name.toLowerCase();
+    if (['read', 'glob', 'grep', 'ls', 'webfetch', 'websearch'].some((p) => kind.startsWith(p))) {
+        return 'reading the deck';
+    }
+    if (['edit', 'write', 'notebookedit', 'multiedit'].some((p) => kind.startsWith(p))) {
+        return 'editing files';
+    }
+    if (kind.startsWith('bash'))
+        return 'running a command';
+    if (kind.startsWith('task'))
+        return 'delegating';
+    return 'working';
+}
+// Human-readable label for a tool_call event, e.g. readToolCall -> "reading
+// the deck". Shown as the streaming message's activity line.
+function toolActivityLabel(ev) {
+    const call = ev.tool_call;
+    const key = call ? Object.keys(call).find((k) => k.endsWith('ToolCall')) : undefined;
+    const kind = (key ?? '').slice(0, -'ToolCall'.length).toLowerCase();
+    if (['read', 'glob', 'grep', 'ls', 'list'].some((p) => kind.startsWith(p))) {
+        return 'reading the deck';
+    }
+    if (['write', 'edit', 'delete', 'mv'].some((p) => kind.startsWith(p)))
+        return 'editing files';
+    if (['shell', 'bash', 'terminal'].some((p) => kind.startsWith(p)))
+        return 'running a command';
+    return 'working';
+}
+// One headless agent CLI run (cursor or claude), normalized to the same
+// delta/activity/result hooks. Cursor: assistant events carrying timestamp_ms
+// are text deltas; the trailing assistant event without one repeats the whole
+// message (skipped). Claude: stream_event wraps anthropic SSE deltas. Both
+// end with a result event carrying the canonical final text.
+function runAgentCli(opts) {
+    return new Promise((resolve) => {
+        const child = spawn(opts.command, opts.args, {
+            cwd: opts.cwd,
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        opts.children.add(child);
+        opts.onSpawn?.(child.pid);
+        const log = opts.logPath ? fs.createWriteStream(opts.logPath, { flags: 'a' }) : null;
+        let settled = false;
+        let accumulated = '';
+        let finalText = '';
+        let resultIsError = false;
+        let sawResult = false;
+        let stderrTail = '';
+        let lineBuffer = '';
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            opts.children.delete(child);
+            log?.end();
+            resolve(result);
+        };
+        const timeout = setTimeout(() => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                /* already gone */
+            }
+            settle({ ok: false, finalText: finalText || accumulated, error: 'agent run timed out' });
+        }, opts.timeoutMs);
+        // Cursor closes each text segment (e.g. right before a tool call) by
+        // re-emitting the segment's full text as one more delta-shaped event;
+        // track the current segment so those re-emissions are dropped instead of
+        // duplicating lines. Segment boundaries also need a paragraph gap --
+        // cursor starts the next segment without one, which glues "Checking the
+        // deck..." lines onto the previous paragraph.
+        let segmentText = '';
+        let needsGap = false;
+        const emitDelta = (rawDelta) => {
+            let delta = rawDelta;
+            if (needsGap) {
+                needsGap = false;
+                if (accumulated && !accumulated.endsWith('\n\n')) {
+                    delta = (accumulated.endsWith('\n') ? '\n' : '\n\n') + delta;
+                }
+            }
+            segmentText += delta;
+            accumulated += delta;
+            opts.onDelta?.(delta);
+            opts.onActivity?.(null);
+        };
+        const handleClaudeEvent = (ev) => {
+            if (ev.type === 'stream_event') {
+                const e = ev.event;
+                if (e?.type === 'content_block_start') {
+                    if (e.content_block?.type === 'tool_use') {
+                        needsGap = true;
+                        opts.onActivity?.(claudeToolActivityLabel(String(e.content_block.name ?? '')));
+                    }
+                    else if (e.content_block?.type === 'thinking') {
+                        needsGap = true;
+                        opts.onActivity?.('thinking');
+                    }
+                }
+                else if (e?.type === 'content_block_delta') {
+                    if (e.delta?.type === 'text_delta' && typeof e.delta.text === 'string' && e.delta.text) {
+                        emitDelta(e.delta.text);
+                    }
+                    else if (e.delta?.type === 'thinking_delta') {
+                        opts.onActivity?.('thinking');
+                    }
+                }
+            }
+            else if (ev.type === 'result') {
+                sawResult = true;
+                finalText = typeof ev.result === 'string' ? ev.result : accumulated;
+                resultIsError = ev.is_error === true;
+            }
+        };
+        const handleEvent = (ev) => {
+            if (opts.parser === 'claude') {
+                handleClaudeEvent(ev);
+                return;
+            }
+            if (ev.type === 'assistant' && typeof ev.timestamp_ms === 'number') {
+                const message = ev.message;
+                const delta = (message?.content ?? [])
+                    .map((c) => (typeof c?.text === 'string' ? c.text : ''))
+                    .join('');
+                if (!delta)
+                    return;
+                const trimmed = delta.trim();
+                if (trimmed.length >= 16 && segmentText.trim().endsWith(trimmed))
+                    return;
+                emitDelta(delta);
+            }
+            else if (ev.type === 'tool_call') {
+                segmentText = '';
+                needsGap = true;
+                if (ev.subtype === 'started')
+                    opts.onActivity?.(toolActivityLabel(ev));
+            }
+            else if (ev.type === 'thinking') {
+                segmentText = '';
+                needsGap = true;
+                opts.onActivity?.('thinking');
+            }
+            else if (ev.type === 'result') {
+                sawResult = true;
+                finalText = typeof ev.result === 'string' ? ev.result : accumulated;
+                resultIsError = ev.is_error === true;
+            }
+        };
+        child.stdout.on('data', (chunk) => {
+            lineBuffer += chunk.toString('utf8');
+            let nl = lineBuffer.indexOf('\n');
+            while (nl >= 0) {
+                const line = lineBuffer.slice(0, nl);
+                lineBuffer = lineBuffer.slice(nl + 1);
+                if (line.trim()) {
+                    log?.write(line + '\n');
+                    try {
+                        handleEvent(JSON.parse(line));
+                    }
+                    catch {
+                        /* non-JSON noise on stdout -- ignore */
+                    }
+                }
+                nl = lineBuffer.indexOf('\n');
+            }
+        });
+        child.stderr.on('data', (chunk) => {
+            stderrTail = (stderrTail + chunk.toString('utf8')).slice(-2000);
+        });
+        child.on('error', (err) => {
+            settle({ ok: false, finalText: accumulated, error: `could not run cursor-agent: ${err.message}` });
+        });
+        child.on('close', (code) => {
+            const ok = code === 0 && !resultIsError && sawResult;
+            settle({
+                ok,
+                finalText: finalText || accumulated,
+                crashed: !sawResult,
+                error: ok ? undefined : `agent exited ${code}${stderrTail ? `: ${stderrTail.slice(-300)}` : ''}`,
+            });
+        });
+    });
+}
+// -- task store ---------------------------------------------------------------
+function persistTaskFile(tasksDir, task) {
+    fs.writeFileSync(path.join(tasksDir, task.id, 'task.json'), JSON.stringify(task, null, 2) + '\n');
+}
+// Tasks left "running" by a dead serve are as finished as they will get.
+function loadTasks(tasksDir) {
+    const tasks = new Map();
+    for (const entry of fs.existsSync(tasksDir) ? fs.readdirSync(tasksDir) : []) {
+        const rec = readJsonFile(path.join(tasksDir, entry, 'task.json'));
+        if (!rec)
+            continue;
+        if (rec.status === 'running') {
+            rec.status = 'interrupted';
+            rec.updatedAt = nowIso();
+            persistTaskFile(tasksDir, rec);
+        }
+        tasks.set(rec.id, rec);
+    }
+    return tasks;
+}
+// Task agents report through plain files: an integer in `progress`, free
+// text in `notes.md`. Pull both into the record; true when anything changed.
+function refreshTaskFiles(tasksDir, task) {
+    const dir = path.join(tasksDir, task.id);
+    let changed = false;
+    try {
+        const rawProgress = fs.readFileSync(path.join(dir, 'progress'), 'utf8').trim();
+        const value = Math.max(0, Math.min(100, parseInt(rawProgress, 10)));
+        if (Number.isFinite(value) && value !== task.progress) {
+            task.progress = value;
+            changed = true;
+        }
+    }
+    catch {
+        /* no progress file yet */
+    }
+    try {
+        const notes = fs.readFileSync(path.join(dir, 'notes.md'), 'utf8');
+        if (notes !== task.notes) {
+            task.notes = notes;
+            changed = true;
+        }
+    }
+    catch {
+        /* no notes file yet */
+    }
+    return changed;
+}
+// "after:" entries may reference task ids or titles -- including titles of
+// tasks spawned earlier in the same reply (spawn order follows block order).
+function resolveDeps(tasks, tokens) {
+    const resolved = [];
+    for (const token of tokens) {
+        if (tasks.has(token)) {
+            resolved.push(token);
+            continue;
+        }
+        const byTitle = [...tasks.values()]
+            .sort((a, b) => a.createdAt.localeCompare(b.createdAt))
+            .filter((t) => t.title.toLowerCase() === token.toLowerCase());
+        const last = byTitle[byTitle.length - 1];
+        if (last)
+            resolved.push(last.id);
+    }
+    return [...new Set(resolved)];
+}
+function depsSummaryFor(tasks, task) {
+    if (task.after.length === 0)
+        return undefined;
+    const lines = task.after
+        .map((id) => tasks.get(id))
+        .filter((dep) => !!dep)
+        .map((dep) => `- "${dep.title}" finished ${dep.status}${dep.notes.trim() ? `; notes: ${dep.notes.trim()}` : ''}`);
+    return lines.join('\n') || undefined;
+}
+function createTaskStore(opts) {
+    const { deckDir, deckLabel, tasksDir, children } = opts;
+    const tasks = loadTasks(tasksDir);
+    function sorted() {
+        return [...tasks.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+    function touch(task) {
+        task.updatedAt = nowIso();
+        persistTaskFile(tasksDir, task);
+        opts.onUpdate(task);
+    }
+    function depsAreSettled(task) {
+        return task.after.every((id) => {
+            const dep = tasks.get(id);
+            return !dep || isTerminal(dep.status);
+        });
+    }
+    function maybeStart(task) {
+        if (task.status !== 'waiting' || task.acknowledged || !depsAreSettled(task))
+            return;
+        start(task);
+    }
+    // Run the task agent, re-running if the process dies mid-task (crash, not
+    // a normal finish). After MAX_TASK_ATTEMPTS dead processes the task fails.
+    async function runTaskAgent(task, dir) {
+        const relDir = path.relative(deckDir, dir);
+        const backend = opts.backend();
+        const taskPrompt = buildTaskPrompt({
+            deckLabel,
+            taskId: task.id,
+            title: task.title,
+            prompt: task.prompt,
+            progressPath: path.join(relDir, 'progress'),
+            notesPath: path.join(relDir, 'notes.md'),
+            depsSummary: depsSummaryFor(tasks, task),
+        });
+        // /goal commits claude to finishing autonomously; cursor has no
+        // equivalent slash command.
+        const invocation = buildAgentInvocation(backend, 'task', backend === 'claude' ? `/goal ${taskPrompt}` : taskPrompt, opts.claudeModel());
+        let result = { ok: false, finalText: '', error: 'not run' };
+        let lineBuf = '';
+        const flushFeedLines = (delta) => {
+            lineBuf += delta;
+            let nl = lineBuf.indexOf('\n');
+            while (nl >= 0) {
+                const line = lineBuf.slice(0, nl).trim();
+                lineBuf = lineBuf.slice(nl + 1);
+                if (line)
+                    opts.onFeed(task, line);
+                nl = lineBuf.indexOf('\n');
+            }
+        };
+        for (let attempt = 1; attempt <= MAX_TASK_ATTEMPTS; attempt++) {
+            result = await runAgentCli({
+                cwd: deckDir,
+                command: invocation.command,
+                args: invocation.args,
+                parser: backend,
+                timeoutMs: TASK_TIMEOUT_MS,
+                logPath: path.join(dir, 'log.jsonl'),
+                children,
+                onSpawn: (pid) => {
+                    task.pid = pid;
+                },
+                onDelta: (delta) => flushFeedLines(delta),
+                onActivity: (activity) => {
+                    if (activity)
+                        opts.onFeed(task, `[${activity}]`);
+                },
+            });
+            if (!result.crashed)
+                return result;
+            if (attempt < MAX_TASK_ATTEMPTS)
+                opts.onRetry(task, attempt + 1);
+        }
+        result.error = `agent process kept dying (${MAX_TASK_ATTEMPTS} attempts): ${result.error ?? ''}`;
+        return result;
+    }
+    function start(task) {
+        const dir = path.join(tasksDir, task.id);
+        fs.writeFileSync(path.join(dir, 'progress'), '0\n');
+        if (!fs.existsSync(path.join(dir, 'notes.md')))
+            fs.writeFileSync(path.join(dir, 'notes.md'), '');
+        task.status = 'running';
+        task.startedAt = nowIso();
+        touch(task);
+        opts.onStarted(task);
+        void runTaskAgent(task, dir).then((result) => {
+            refreshTaskFiles(tasksDir, task);
+            task.status = result.ok ? 'done' : 'failed';
+            if (result.ok)
+                task.progress = 100;
+            task.finishedAt = nowIso();
+            task.resultSummary = result.ok
+                ? result.finalText.slice(-RESULT_SUMMARY_CHARS)
+                : `${result.error ?? 'failed'}\n${result.finalText.slice(-RESULT_SUMMARY_CHARS)}`;
+            touch(task);
+            opts.onFinished(task);
+            for (const waiting of tasks.values())
+                maybeStart(waiting);
+        });
+    }
+    function spawnFromDirective(directive, originMessageId) {
+        // A fix/redo task sweeps the rows it obsoletes off the user's board. A
+        // superseded task that never started must not start later either.
+        for (const id of resolveDeps(tasks, directive.supersedes)) {
+            const old = tasks.get(id);
+            if (old && !old.acknowledged) {
+                if (old.status === 'waiting')
+                    old.status = 'interrupted';
+                old.acknowledged = true;
+                touch(old);
+                opts.onSuperseded(old);
+            }
+        }
+        const task = {
+            id: nanoid(8),
+            title: directive.title,
+            prompt: directive.prompt,
+            after: resolveDeps(tasks, directive.after),
+            status: 'waiting',
+            progress: 0,
+            notes: '',
+            createdAt: nowIso(),
+            updatedAt: nowIso(),
+            originMessageId,
+        };
+        fs.mkdirSync(path.join(tasksDir, task.id), { recursive: true });
+        tasks.set(task.id, task);
+        persistTaskFile(tasksDir, task);
+        opts.onUpdate(task);
+        maybeStart(task);
+        return task.id;
+    }
+    function acknowledge(id, rejected) {
+        const task = tasks.get(id);
+        if (!task || !isTerminal(task.status) || task.acknowledged)
+            return undefined;
+        task.acknowledged = true;
+        if (rejected)
+            task.rejected = true;
+        touch(task);
+        return task;
+    }
+    const pollTimer = setInterval(() => {
+        for (const task of tasks.values()) {
+            if (task.status !== 'running')
+                continue;
+            if (refreshTaskFiles(tasksDir, task))
+                touch(task);
+        }
+    }, TASK_POLL_MS);
+    function shutdown() {
+        clearInterval(pollTimer);
+        for (const task of tasks.values()) {
+            if (task.status === 'running' || task.status === 'waiting') {
+                task.status = 'interrupted';
+                task.updatedAt = nowIso();
+                persistTaskFile(tasksDir, task);
+            }
+        }
+    }
+    // The router checks finished tasks off by title or id (castle-done fence).
+    function checkOff(tokens) {
+        for (const id of resolveDeps(tasks, tokens))
+            acknowledge(id, false);
+    }
+    return { sorted, get: (id) => tasks.get(id), spawnFromDirective, acknowledge, checkOff, shutdown };
+}
+// -- attachments ----------------------------------------------------------------
+const ATTACHMENT_MIME = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+};
+// Decode pasted/attached images (data URLs) into .castle/agent/attachments/.
+// Returns the saved file names.
+function saveAttachments(attachmentsDir, messageId, images) {
+    if (!Array.isArray(images))
+        return [];
+    const saved = [];
+    for (const [index, image] of images.slice(0, MAX_ATTACHMENTS).entries()) {
+        const dataUrl = image?.dataUrl;
+        if (typeof dataUrl !== 'string' || dataUrl.length > MAX_ATTACHMENT_BYTES * 1.4)
+            continue;
+        const match = /^data:image\/(png|jpe?g|gif|webp);base64,([A-Za-z0-9+/=]+)$/.exec(dataUrl);
+        if (!match)
+            continue;
+        const ext = match[1] === 'jpeg' ? 'jpg' : match[1];
+        const fileName = `${messageId}-${index}.${ext}`;
+        try {
+            fs.mkdirSync(attachmentsDir, { recursive: true });
+            fs.writeFileSync(path.join(attachmentsDir, fileName), Buffer.from(match[2], 'base64'));
+            saved.push(fileName);
+        }
+        catch {
+            /* disk trouble -- skip this image */
+        }
+    }
+    return saved;
+}
+function asPromptTask(task) {
+    return {
+        id: task.id,
+        title: task.title,
+        status: task.rejected ? 'rejected by user' : task.status,
+        progress: task.progress,
+        notes: task.notes,
+    };
+}
+function createTaskFeeds(broadcast) {
+    const map = new Map();
+    function push(task, entry) {
+        let feed = map.get(task.id);
+        if (!feed) {
+            feed = [];
+            map.set(task.id, feed);
+        }
+        if (feed[feed.length - 1] === entry)
+            return;
+        feed.push(entry);
+        if (feed.length > 80)
+            feed.splice(0, feed.length - 80);
+        broadcast({ type: 'task-feed', id: task.id, entry });
+    }
+    return { map, push };
+}
+function createMessageLog(messagesPath, broadcast) {
+    const loaded = readJsonFile(messagesPath) ?? [];
+    const messages = loaded
+        .filter((m) => m.text.trim() !== '' || m.role === 'user')
+        .map((m) => (m.status === 'streaming' ? { ...m, status: 'done' } : m));
+    function persist() {
+        fs.writeFileSync(messagesPath, JSON.stringify(messages, null, 2) + '\n');
+    }
+    function add(message) {
+        messages.push(message);
+        persist();
+        broadcast({ type: 'message-add', message });
+    }
+    function addLog(text) {
+        add({ id: nanoid(8), role: 'log', text, at: nowIso(), status: 'done' });
+    }
+    // Consecutive same-prefix log lines collapse into one ("working on: A, B").
+    function addGroupedLog(prefix, item) {
+        const last = messages[messages.length - 1];
+        if (last && last.role === 'log' && last.text.startsWith(prefix)) {
+            last.text += `, ${item}`;
+            persist();
+            broadcast({ type: 'message-done', id: last.id, text: last.text, status: 'done' });
+            return;
+        }
+        addLog(`${prefix}${item}`);
+    }
+    return { messages, persist, add, addLog, addGroupedLog };
+}
+// Serve attachment images saved under .castle/agent/attachments/.
+function makeAttachmentHandler(attachmentsDir) {
+    return (_req, res, reqPath) => {
+        if (!reqPath.startsWith(AGENT_ATTACHMENT_PREFIX))
+            return false;
+        const name = path.basename(reqPath.slice(AGENT_ATTACHMENT_PREFIX.length));
+        const ext = name.split('.').pop() ?? '';
+        const mime = ATTACHMENT_MIME[ext];
+        const filePath = path.join(attachmentsDir, name);
+        if (!mime || !fs.existsSync(filePath)) {
+            res.writeHead(404).end();
+            return true;
+        }
+        res.writeHead(200, { 'content-type': mime, 'cache-control': 'no-store' });
+        fs.createReadStream(filePath).pipe(res);
+        return true;
+    };
+}
+// One router turn: stream a reply message, then spawn the directives it
+// emitted (unless a newer user message superseded this turn).
+function runRouterTurnIn(ctx, instruction) {
+    const epoch = ctx.currentEpoch();
+    const message = {
+        id: nanoid(8),
+        role: 'assistant',
+        text: '',
+        at: nowIso(),
+        status: 'streaming',
+    };
+    ctx.log.messages.push(message);
+    ctx.broadcast({ type: 'message-add', message });
+    let raw = '';
+    let visibleSent = 0;
+    let lastActivity = null;
+    const prompt = buildRouterPrompt({
+        deckLabel: ctx.deckLabel,
+        messages: ctx.log.messages
+            .filter((m) => m.role !== 'log' && m.id !== message.id && m.status !== 'streaming')
+            .map((m) => ({ role: m.role, text: m.text })),
+        tasks: ctx.taskStore.sorted().map(asPromptTask),
+        instruction,
+    });
+    const backend = ctx.backend();
+    const invocation = buildAgentInvocation(backend, 'router', prompt, ctx.claudeModel());
+    void runAgentCli({
+        cwd: ctx.deckDir,
+        command: invocation.command,
+        args: invocation.args,
+        parser: backend,
+        timeoutMs: ROUTER_TIMEOUT_MS,
+        logPath: path.join(ctx.agentDir, 'router-log.jsonl'),
+        children: ctx.children,
+        onDelta: (delta) => {
+            raw += delta;
+            const visible = visibleLength(raw);
+            if (visible > visibleSent) {
+                const slice = raw.slice(visibleSent, visible);
+                visibleSent = visible;
+                message.text += slice;
+                ctx.broadcast({ type: 'message-delta', id: message.id, delta: slice });
+            }
+        },
+        onActivity: (activity) => {
+            if (activity === lastActivity)
+                return;
+            lastActivity = activity;
+            ctx.broadcast({ type: 'message-activity', id: message.id, activity });
+        },
+    }).then((result) => {
+        const interrupted = epoch !== ctx.currentEpoch() && !result.ok;
+        if (interrupted) {
+            // Keep whatever streamed; the continuation turn carries the draft.
+            message.status = 'done';
+            message.interrupted = true;
+            ctx.log.persist();
+            ctx.broadcast({
+                type: 'message-done',
+                id: message.id,
+                text: message.text,
+                status: message.status,
+                interrupted: true,
+                taskIds: [],
+            });
+            return;
+        }
+        const { cleaned, directives, checkoffs } = extractDirectives(result.finalText);
+        if (result.ok && checkoffs.length > 0)
+            ctx.taskStore.checkOff(checkoffs);
+        // Drop directives from stale turns, and any whose title matches a task
+        // already in flight (two runs reacting to the same ask).
+        const stale = epoch !== ctx.currentEpoch();
+        const inFlight = new Set(ctx.taskStore
+            .sorted()
+            .filter((t) => t.status === 'running' || t.status === 'waiting')
+            .map((t) => t.title.toLowerCase()));
+        const toSpawn = stale ? [] : directives.filter((d) => !inFlight.has(d.title.toLowerCase()));
+        const taskIds = toSpawn.map((d) => ctx.taskStore.spawnFromDirective(d, message.id));
+        message.text = result.ok
+            ? cleaned
+            : `${cleaned ? cleaned + '\n\n' : ''}[router error: ${result.error ?? 'unknown'}]`;
+        message.status = result.ok ? 'done' : 'error';
+        if (taskIds.length > 0)
+            message.taskIds = taskIds;
+        ctx.log.persist();
+        ctx.broadcast({
+            type: 'message-done',
+            id: message.id,
+            text: message.text,
+            status: message.status,
+            taskIds: message.taskIds ?? [],
+        });
+    });
+}
+// Merge settings changes from the client: validate, persist, broadcast, log.
+function applyAgentSettings(incoming, ctx) {
+    const { settings } = ctx;
+    const changes = [];
+    for (const key of ['router', 'tasks']) {
+        const value = normalizeBackend(incoming[key]);
+        if (value && value !== settings[key]) {
+            settings[key] = value;
+            changes.push(`${key} agent -> ${value}`);
+        }
+    }
+    const model = normalizeClaudeModel(incoming.claudeModel);
+    if (model && model !== settings.claudeModel) {
+        settings.claudeModel = model;
+        changes.push(`claude model -> ${model}`);
+    }
+    if (changes.length === 0)
+        return;
+    fs.writeFileSync(ctx.settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    ctx.broadcast({ type: 'settings', settings });
+}
+export function createAgentServer(opts) {
+    const { deckDir, deckLabel } = opts;
+    const agentDir = path.join(deckDir, '.castle', 'agent');
+    const tasksDir = path.join(agentDir, 'tasks');
+    const attachmentsDir = path.join(agentDir, 'attachments');
+    const messagesPath = path.join(agentDir, 'messages.json');
+    fs.mkdirSync(tasksDir, { recursive: true });
+    const taskChildren = new Set();
+    const routerChildren = new Set();
+    const clients = new Set();
+    function broadcast(body) {
+        const payload = JSON.stringify(body);
+        for (const socket of clients) {
+            if (socket.readyState === socket.OPEN)
+                socket.send(payload);
+        }
+    }
+    const log = createMessageLog(messagesPath, broadcast);
+    const messages = log.messages;
+    const addLog = (text) => log.addLog(text);
+    // Which CLI backs the router and the task agents -- independently
+    // switchable from the settings popover, persisted next to the chat state.
+    const settingsPath = path.join(agentDir, 'settings.json');
+    const storedSettings = readJsonFile(settingsPath);
+    const settings = {
+        router: normalizeBackend(storedSettings?.router) ?? DEFAULT_SETTINGS.router,
+        tasks: normalizeBackend(storedSettings?.tasks) ?? DEFAULT_SETTINGS.tasks,
+        claudeModel: normalizeClaudeModel(storedSettings?.claudeModel) ?? DEFAULT_SETTINGS.claudeModel,
+    };
+    const applySettings = (incoming) => applyAgentSettings(incoming, { settings, settingsPath, broadcast });
+    const taskFeeds = createTaskFeeds(broadcast);
+    const taskStore = createTaskStore({
+        deckDir,
+        deckLabel,
+        tasksDir,
+        children: taskChildren,
+        backend: () => settings.tasks,
+        claudeModel: () => settings.claudeModel,
+        // Task lifecycle stays on the board only -- log lines for it were spam.
+        onUpdate: (task) => broadcast({ type: 'task-update', task }),
+        onStarted: () => undefined,
+        onRetry: (task, attempt) => addLog(`agent died, retrying (${attempt}/${MAX_TASK_ATTEMPTS}): ${task.title}`),
+        onFinished: (task) => taskFeeds.map.delete(task.id),
+        onSuperseded: () => undefined,
+        onFeed: (task, entry) => taskFeeds.push(task, entry),
+    });
+    // A new user message interrupts the in-flight router reply: its partial
+    // text stays in the log, and the next turn continues both threads. The
+    // epoch also keeps a killed-but-racing run from spawning tasks.
+    let userEpoch = 0;
+    function interruptRouterRuns() {
+        const drafts = messages
+            .filter((m) => m.role === 'assistant' && m.status === 'streaming')
+            .map((m) => m.text.trim())
+            .filter(Boolean);
+        for (const child of routerChildren) {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                /* already gone */
+            }
+        }
+        return drafts.join('\n\n');
+    }
+    function runRouterTurn(instruction) {
+        runRouterTurnIn({
+            deckDir,
+            deckLabel,
+            agentDir,
+            children: routerChildren,
+            log,
+            broadcast,
+            taskStore,
+            currentEpoch: () => userEpoch,
+            backend: () => settings.router,
+            claudeModel: () => settings.claudeModel,
+        }, instruction);
+    }
+    function handleUserMessage(text, images) {
+        userEpoch += 1;
+        const interruptedDraft = interruptRouterRuns();
+        const messageId = nanoid(8);
+        const attachments = saveAttachments(attachmentsDir, messageId, images);
+        const message = {
+            id: messageId,
+            role: 'user',
+            text,
+            at: nowIso(),
+            status: 'done',
+        };
+        if (attachments.length > 0)
+            message.attachments = attachments;
+        log.add(message);
+        runRouterTurn(userTurnInstruction({
+            text,
+            interruptedDraft: interruptedDraft || undefined,
+            attachments: attachments.map((name) => path.join('.castle', 'agent', 'attachments', name)),
+        }));
+    }
+    function handleTaskAck(id, rejected) {
+        taskStore.acknowledge(id, rejected);
+    }
+    const wss = new WebSocketServer({ noServer: true });
+    function attachClient(socket) {
+        clients.add(socket);
+        const hello = { type: 'hello', messages, tasks: taskStore.sorted(), settings, feeds: Object.fromEntries(taskFeeds.map) };
+        socket.send(JSON.stringify(hello));
+        socket.on('message', (rawData) => {
+            let msg;
+            try {
+                msg = JSON.parse(rawDataToString(rawData));
+            }
+            catch {
+                return;
+            }
+            const hasText = typeof msg.text === 'string' && msg.text.trim() !== '';
+            const hasImages = Array.isArray(msg.images) && msg.images.length > 0;
+            if (msg.type === 'user-message' && (hasText || hasImages)) {
+                handleUserMessage(typeof msg.text === 'string' ? msg.text.trim() : '', msg.images);
+            }
+            else if (msg.type === 'task-ack' && typeof msg.id === 'string') {
+                handleTaskAck(msg.id, msg.rejected === true);
+            }
+            else if (msg.type === 'set-settings') {
+                applySettings(msg);
+            }
+        });
+        socket.on('close', () => {
+            clients.delete(socket);
+        });
+    }
+    function handleUpgrade(req, socket, head) {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        if (url.pathname !== AGENT_WS_PATH)
+            return false;
+        wss.handleUpgrade(req, socket, head, (ws) => attachClient(ws));
+        return true;
+    }
+    const handleHttpRequest = makeAttachmentHandler(attachmentsDir);
+    function shutdown() {
+        taskStore.shutdown();
+        for (const child of [...taskChildren, ...routerChildren]) {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                /* already gone */
+            }
+        }
+        wss.close();
+    }
+    return { handleUpgrade, handleHttpRequest, shutdown };
+}