kapi-ui 0.2.2 → 0.3.1

package/dist/browser/styles/overlay.css

@@ -0,0 +1,181 @@
+:host {
+  /* Reset anything inheritable coming from the host page. */
+  all: initial;
+
+  --kapi-bg: #1e1e1f;
+  --kapi-bg-hover: #3b3b3f;
+  --kapi-bg-active: #3b3b3f;
+  --kapi-ring: rgba(255, 255, 255, 0.14);
+  --kapi-divider: rgba(255, 255, 255, 0.16);
+
+  position: fixed;
+  top: 0;
+  left: 0;
+  z-index: 2147483647;
+  color-scheme: dark;
+  touch-action: none;
+}
+
+.kapi-bar {
+  display: flex;
+  align-items: center;
+  box-sizing: border-box;
+  width: 40px;
+  height: 40px;
+  padding: 4px;
+  gap: 6px;
+  border-radius: 12px;
+  background: var(--kapi-bg);
+  box-shadow:
+    inset 0 0 0 1px var(--kapi-ring),
+    0 2px 4px rgba(0, 0, 0, 0.2),
+    0 8px 16px rgba(0, 0, 0, 0.2);
+  overflow: hidden;
+  transition:
+    width 260ms cubic-bezier(0.34, 1.56, 0.64, 1),
+    border-radius 260ms ease;
+  transition-delay: 120ms, 120ms;
+}
+
+.kapi-bar.kapi-expanded {
+  width: var(--kapi-expanded-width, 40px);
+  border-radius: 12px;
+  transition-delay: 0ms, 0ms;
+}
+
+.kapi-btn {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  flex: none;
+  width: 32px;
+  height: 32px;
+  padding: 0;
+  margin: 0;
+  border: none;
+  border-radius: 8px;
+  background: transparent;
+  cursor: pointer;
+  user-select: none;
+  -webkit-tap-highlight-color: transparent;
+  transition: background 150ms ease, transform 150ms ease;
+}
+
+.kapi-btn:hover { background: var(--kapi-bg-hover); }
+.kapi-btn:active { background: var(--kapi-bg-active); transform: scale(0.92); transition: none; }
+.kapi-btn:focus-visible { outline: 2px solid #fff; outline-offset: 2px; }
+.kapi-logo-btn { cursor: pointer; touch-action: none; }
+
+.kapi-logo-btn.kapi-dragging {
+  cursor: grabbing;
+  background: var(--kapi-bg-active);
+  transform: scale(0.95);
+  transition: none;
+}
+
+.kapi-icon { pointer-events: none; }
+
+.kapi-logo-icon {
+  width: 20px;
+  height: auto;
+  margin-top: 2px;
+  animation: kapi-bounce 1.6s ease-in-out infinite;
+}
+
+.kapi-logo-btn.kapi-dragging .kapi-logo-icon { animation-play-state: paused; }
+
+@keyframes kapi-bounce {
+  0%, 100% { transform: translateY(0) rotate(0deg); }
+  50% { transform: translateY(-3px) rotate(-6deg); }
+}
+
+@keyframes kapi-icon-fade-out {
+  from { opacity: 1; transform: scale(1); }
+  to { opacity: 0; transform: scale(0.8); }
+}
+
+@keyframes kapi-icon-fade-in {
+  from { opacity: 0; transform: scale(0.8); }
+  to { opacity: 1; transform: scale(1); }
+}
+
+.kapi-logo-btn.kapi-animating-out { animation: kapi-icon-fade-out 200ms ease; }
+.kapi-logo-btn.kapi-animating-in { animation: kapi-icon-fade-in 200ms ease; }
+.kapi-ai-icon { width: 16.5px; height: auto; }
+.kapi-copy-icon { width: 16.5px; height: auto; color: white; }
+.kapi-check-icon { width: 16.5px; height: auto; color: rgb(34, 197, 94); }
+
+/* Copy button success feedback: swap copy <-> checkmark with a
+   fade/scale/blur transition. .kapi-busy fully blocks clicks meanwhile. */
+.kapi-btn.kapi-busy { pointer-events: none; }
+.kapi-copy-out { animation: kapi-copy-icon-out 180ms ease forwards; }
+.kapi-copy-in { animation: kapi-copy-icon-in 180ms ease forwards; }
+
+@keyframes kapi-copy-icon-out {
+  from { opacity: 1; transform: scale(1); filter: blur(0); }
+  to { opacity: 0; transform: scale(0.6); filter: blur(3px); }
+}
+
+@keyframes kapi-copy-icon-in {
+  from { opacity: 0; transform: scale(0.6); filter: blur(3px); }
+  to { opacity: 1; transform: scale(1); filter: blur(0); }
+}
+
+.kapi-delete-icon {
+  width: 15px;
+  height: auto;
+  color: white;
+  transition: color 150ms ease;
+}
+
+.kapi-btn:has(.kapi-delete-icon):hover,
+.kapi-btn:has(.kapi-delete-icon):active { background: rgba(255, 77, 79, 0.15); }
+
+.kapi-btn:hover .kapi-delete-icon,
+.kapi-btn:active .kapi-delete-icon { color: #ff4d4f; }
+
+.kapi-stop-icon {
+  width: 20px;
+  height: auto;
+  transition: stroke 150ms ease, color 150ms ease;
+}
+
+.kapi-logo-btn.kapi-stop-mode:hover .kapi-stop-icon,
+.kapi-logo-btn.kapi-stop-mode:active .kapi-stop-icon { stroke: #ff4d4f; color: #ff4d4f; }
+
+.kapi-logo-btn.kapi-stop-mode:hover,
+.kapi-logo-btn.kapi-stop-mode:active { background: rgba(255, 77, 79, 0.15); }
+
+.kapi-extra {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex: none;
+  opacity: 0.6;
+  transform: scale(0.9);
+  filter: blur(4px);
+  transition: opacity 160ms ease, transform 160ms ease, filter 160ms ease;
+  transition-delay: 0ms;
+}
+
+.kapi-bar.kapi-expanded .kapi-extra {
+  opacity: 1;
+  transform: scale(1);
+  filter: blur(0);
+  transition-delay: 140ms;
+}
+
+.kapi-btn-group { display: flex; align-items: center; gap: 0; flex: none; }
+
+.kapi-divider {
+  flex: none;
+  width: 1px;
+  height: 18px;
+  background: var(--kapi-divider);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .kapi-bar, .kapi-btn, .kapi-extra { transition: none; }
+  .kapi-logo-icon { animation: none; }
+}

package/dist/browser/trace-record.js

@@ -0,0 +1,33 @@
+// Vue re-creates vnode objects on every re-render, but a given template
+// position's `props` object is a stable identity for that call site within a
+// single render pass — good enough to key a lookup that only needs to survive
+// from "vnode created" to "el mounted" a few lines later in the same tick.
+const vnodeToPos = new WeakMap();
+/**
+ * Called by the wrapper the vite plugin injects around every vnode-creation
+ * call (`_createElementVNode`, etc.) in a component's compiled render
+ * function. Tags the vnode's `props` object with where that call came from in
+ * the original `.vue` source, so it can be recovered later via `el.__vnode`.
+ */
+export function recordPosition(file, line, column, vnode) {
+    const node = vnode;
+    // `h(...)` (unlike the underscore-prefixed compiler helpers) can also be a
+    // user-defined identifier unrelated to Vue's hyperscript function — only
+    // tag objects Vue itself marked as vnodes, so a colliding `h` never gets
+    // mutated with a spurious `.props`.
+    if (!node || typeof node !== 'object' || node.__v_isVNode !== true)
+        return vnode;
+    const props = (node.props ?? (node.props = {}));
+    vnodeToPos.set(props, { file, line, column });
+    return vnode;
+}
+/**
+ * Reads Vue's own non-enumerable `el.__vnode` back-reference (set by Vue's
+ * renderer on every DOM node it creates) to recover the source location
+ * recorded for that exact element, if any.
+ */
+export function findTraceFromElement(el) {
+    const vnode = el.__vnode;
+    const props = vnode?.props;
+    return (props && vnodeToPos.get(props)) ?? null;
+}

package/dist/browser/types.js

@@ -0,0 +1,4 @@
+// Shared type definitions for the browser tier (overlay, inspector,
+// comments, trace-record). Kept separate from implementation so the shapes
+// can be referenced without pulling in a module's runtime code.
+export {};

package/dist/cli/setup.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+import { stdin as input, stdout as output } from 'process';
+import { installKapi, injectVitePlugin, injectNuxtModule, detectFramework, detectInstalledAgents, KAPI_PACKAGE_NAME, } from './utils.js';
+// How the chosen agent renders in config: a quoted agent name, or bare `false`
+// for the manual copy/paste-only workflow.
+const agentConfigValue = (agent) => (agent === false ? 'false' : `'${agent}'`);
+const FRAMEWORK_SETUP = {
+    nuxt: {
+        label: 'Nuxt',
+        inject: injectNuxtModule,
+        manualInstructions: (agent) => `
+Add this manually to your nuxt.config:
+
+  export default defineNuxtConfig({
+    modules: ['${KAPI_PACKAGE_NAME}/nuxt'],
+    kapi: { agent: ${agentConfigValue(agent)} },
+  })
+`,
+    },
+    vite: {
+        label: 'Vite + Vue',
+        inject: injectVitePlugin,
+        manualInstructions: (agent) => `
+Add this manually to your vite.config:
+
+  import kapi from '${KAPI_PACKAGE_NAME}/vite-plugin'
+
+  export default defineConfig({
+    plugins: [kapi({ agent: ${agentConfigValue(agent)} })],
+  })
+`,
+    },
+};
+const AGENT_LABELS = {
+    claude: 'Claude Code',
+    codex: 'Codex (experimental)',
+};
+const modeLabel = (agent) => (agent === false ? 'manual copy/paste' : AGENT_LABELS[agent]);
+// Minimal dependency-free single-select list: renders bulleted options and
+// lets the user move with ↑/↓ (or j/k) and confirm with Enter, redrawing the
+// list in place. Falls back to the default option when stdin isn't a TTY
+// (piped/CI), where raw-mode key reading isn't available.
+function promptSelect(question, options, defaultIndex = 0) {
+    return new Promise((resolve) => {
+        if (!input.isTTY) {
+            resolve(options[defaultIndex].value);
+            return;
+        }
+        let index = defaultIndex;
+        const render = (redraw) => {
+            if (redraw)
+                output.write(`[${options.length}A`); // move up over the option lines
+            for (let i = 0; i < options.length; i++) {
+                const selected = i === index;
+                // ● highlighted (cyan) for the current row, ○ for the rest.
+                const line = selected ? `❯ ● ${options[i].label}` : `  ○ ${options[i].label}`;
+                output.write(`${line}\n`); // clear line, then draw
+            }
+        };
+        const cleanup = () => {
+            input.off('data', onData);
+            input.setRawMode(false);
+            input.pause();
+            output.write('[?25h'); // show cursor
+        };
+        const onData = (data) => {
+            const key = data.toString();
+            if (key === '') {
+                // Ctrl+C
+                cleanup();
+                output.write('\n');
+                process.exit(130);
+            }
+            else if (key === '' || key === 'k') {
+                index = (index - 1 + options.length) % options.length;
+                render(true);
+            }
+            else if (key === '' || key === 'j') {
+                index = (index + 1) % options.length;
+                render(true);
+            }
+            else if (key === '\r' || key === '\n') {
+                cleanup();
+                resolve(options[index].value);
+            }
+        };
+        output.write(`${question}\n(↑/↓ to move · Enter to select)\n`);
+        output.write('[?25l'); // hide cursor
+        render(false);
+        input.setRawMode(true);
+        input.resume();
+        input.on('data', onData);
+    });
+}
+function parseFrameworkFlag() {
+    const args = process.argv.slice(2);
+    if (args.includes('--nuxt'))
+        return 'nuxt';
+    if (args.includes('--vite'))
+        return 'vite';
+    return null;
+}
+function parseAgentFlag() {
+    const args = process.argv.slice(2);
+    const inlineValue = args.find((arg) => arg.startsWith('--agent='))?.split('=')[1];
+    if (inlineValue === 'claude' || inlineValue === 'codex')
+        return inlineValue;
+    if (inlineValue)
+        throw new Error(`Unknown agent "${inlineValue}". Use "claude" or "codex".`);
+    const flagIndex = args.indexOf('--agent');
+    const value = flagIndex === -1 ? undefined : args[flagIndex + 1];
+    if (flagIndex === -1)
+        return null;
+    if (value === 'claude' || value === 'codex')
+        return value;
+    throw new Error('Missing or invalid --agent value. Use "claude" or "codex".');
+}
+// `--manual` (or `--agent=false`/`--agent=none`) forces the copy/paste-only
+// workflow without prompting.
+function parseManualFlag() {
+    const args = process.argv.slice(2);
+    if (args.includes('--manual'))
+        return true;
+    const inline = args.find((arg) => arg.startsWith('--agent='))?.split('=')[1];
+    return inline === 'false' || inline === 'none';
+}
+async function chooseMode() {
+    if (parseManualFlag())
+        return false;
+    const requestedAgent = parseAgentFlag();
+    const installedAgents = detectInstalledAgents();
+    if (requestedAgent) {
+        if (!installedAgents.includes(requestedAgent)) {
+            throw new Error(`${requestedAgent} CLI is not installed. Install it, or run setup with --manual.`);
+        }
+        return requestedAgent;
+    }
+    // No agent installed → nothing to send to, so set up the manual workflow.
+    if (installedAgents.length === 0) {
+        console.log('No coding agent (Claude Code or Codex) detected — setting up the manual copy/paste workflow.');
+        return false;
+    }
+    const useAgent = await promptSelect('How should Kapi handle your comments?', [
+        { label: 'Send them to a coding agent', value: true },
+        { label: 'Manual copy & paste only', value: false },
+    ]);
+    if (!useAgent)
+        return false;
+    if (installedAgents.length === 1)
+        return installedAgents[0];
+    return promptSelect('Which coding agent should Kapi use?', installedAgents.map((agent) => ({ label: AGENT_LABELS[agent], value: agent })));
+}
+async function setup() {
+    console.log(`
+██   ██  █████  ██████  ██
+██  ██  ██   ██ ██   ██ ██
+█████   ███████ ██████  ██
+██  ██  ██   ██ ██      ██
+██   ██ ██   ██ ██      ██
+  `);
+    const cwd = process.cwd();
+    const framework = parseFrameworkFlag() ?? detectFramework(cwd);
+    if (!framework) {
+        console.error(`Could not detect a Vue project in ${cwd}.`);
+        console.error(`kapi-ui only supports Vue apps (Vite + Vue, or Nuxt).`);
+        console.error(`If this is a Vue project, re-run with --vite or --nuxt to skip detection.`);
+        process.exit(1);
+    }
+    let agent;
+    try {
+        agent = await chooseMode();
+    }
+    catch (err) {
+        console.error(`Unable to choose a coding agent: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    const { label, inject, manualInstructions } = FRAMEWORK_SETUP[framework];
+    console.log(`\n✨ Detected ${label}; using ${modeLabel(agent)} — setting up kapi...\n`);
+    try {
+        installKapi(cwd);
+        await inject(cwd, agent);
+        console.log('done!');
+    }
+    catch (err) {
+        console.error('Failed to update your config automatically:', err);
+        console.log(manualInstructions(agent));
+        process.exit(1);
+    }
+}
+setup().catch(console.error);

package/dist/cli/types.js

@@ -0,0 +1,2 @@
+// Shared type definitions for the CLI tier (setup + utils).
+export {};

package/dist/{utils.js → cli/utils.js}

@@ -3,18 +3,46 @@ import { addVitePlugin, addNuxtModule } from 'magicast/helpers';
 import { existsSync, readFileSync } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { execSync } from 'child_process';
-// dist/utils.js -> package root (one level up from dist/)
-const kapiRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+import { execSync, spawnSync } from 'child_process';
+// dist/cli/utils.js -> package root (two levels up from dist/cli/)
+const kapiRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const kapiPkg = JSON.parse(readFileSync(path.join(kapiRoot, 'package.json'), 'utf-8'));
 export const KAPI_PACKAGE_NAME = kapiPkg.name;
 export function installKapi(cwd) {
     console.log(`Installing ${KAPI_PACKAGE_NAME}...`);
     execSync(`npm install ${KAPI_PACKAGE_NAME} -D`, { cwd, stdio: 'inherit' });
 }
-export async function injectVitePlugin(cwd) {
-    const candidates = ['vite.config.ts', 'vite.config.js', 'vite.config.mjs'];
-    const configFile = candidates.find((f) => existsSync(path.join(cwd, f)));
+export const NUXT_CONFIG_CANDIDATES = ['nuxt.config.ts', 'nuxt.config.js', 'nuxt.config.mjs', 'nuxt.config.mts', 'nuxt.config.cjs'];
+export const VITE_CONFIG_CANDIDATES = ['vite.config.ts', 'vite.config.js', 'vite.config.mjs', 'vite.config.mts', 'vite.config.cjs'];
+// kapi only supports Vue apps, so setup detects which of the two Vue build
+// tools it's dealing with instead of asking — a nuxt.config file means Nuxt
+// (Nuxt apps don't always list `vue` as a direct dependency), otherwise a
+// `vue` dependency means a plain Vite + Vue app.
+export function detectFramework(cwd) {
+    if (NUXT_CONFIG_CANDIDATES.some((f) => existsSync(path.join(cwd, f))))
+        return 'nuxt';
+    const pkgPath = path.join(cwd, 'package.json');
+    if (!existsSync(pkgPath))
+        return null;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        const hasVue = Boolean(pkg.dependencies?.vue || pkg.devDependencies?.vue);
+        return hasVue ? 'vite' : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function isAgentInstalled(agent) {
+    const result = spawnSync(agent, ['--version'], { stdio: 'ignore' });
+    const error = result.error;
+    return error?.code !== 'ENOENT';
+}
+export function detectInstalledAgents() {
+    return ['claude', 'codex'].filter(isAgentInstalled);
+}
+export async function injectVitePlugin(cwd, agent) {
+    const configFile = VITE_CONFIG_CANDIDATES.find((f) => existsSync(path.join(cwd, f)));
     if (!configFile) {
         throw new Error('No vite.config found.');
     }
@@ -29,14 +57,14 @@ export async function injectVitePlugin(cwd) {
     addVitePlugin(mod, {
         from: importSpecifier,
         imported: 'default',
-        constructor: 'kapi'
+        constructor: 'kapi',
+        options: { agent },
     });
     await writeFile(mod, configPath);
     console.log(`✔ Added kapi plugin to ${configFile}`);
 }
-export async function injectNuxtModule(cwd) {
-    const candidates = ['nuxt.config.ts', 'nuxt.config.js', 'nuxt.config.mjs'];
-    const configFile = candidates.find((f) => existsSync(path.join(cwd, f)));
+export async function injectNuxtModule(cwd, agent) {
+    const configFile = NUXT_CONFIG_CANDIDATES.find((f) => existsSync(path.join(cwd, f)));
     if (!configFile) {
         throw new Error('No nuxt.config found.');
     }
@@ -52,7 +80,7 @@ export async function injectNuxtModule(cwd) {
     // overlay can't be injected as a plain Vite plugin the way it is for Vite
     // apps. Registering it as a Nuxt module (kapi-ui/nuxt) lets it inject the
     // overlay script via unhead and add the Vite plugin through @nuxt/kit.
-    addNuxtModule(mod, moduleSpecifier);
+    addNuxtModule(mod, moduleSpecifier, 'kapi', { agent });
     await writeFile(mod, configPath);
     console.log(`✔ Added kapi module to ${configFile}`);
 }

package/dist/node/claude-agent.js

@@ -0,0 +1,185 @@
+// One warm `claude -p --input-format stream-json` process serves every
+// submission, across every tab (they share one session anyway — see
+// kapi/CLAUDE.md's Session Management section). This avoids CLI cold-start
+// and --resume-from-disk overhead on each comment: the process, its
+// tool-use context, and the prompt cache all stay warm between submissions.
+import { spawn } from 'child_process';
+const KAPI_SESSION_PROMPT = "You're applying UI edits from visual comments. Each comment gives the exact file:line:col — go straight there, don't search for it. Make only the requested edit. " +
+    "Before finishing, check whether a higher-precedence rule on the same element would override the property you just changed — an inline `style` attribute, `!important`, a more specific selector, or a utility class applied after it. You have no way to see the rendered result, so if such a conflict exists, edit the highest-precedence source instead of (or in addition to) the one you found first, so the change actually takes visible effect. " +
+    "Stay terse: no narration between tool calls, and finish with at most one short sentence.";
+function describeToolUse(name, input) {
+    switch (name) {
+        case 'Read':
+            return `Reading ${input?.file_path ?? 'a file'}`;
+        case 'Edit':
+        case 'Write':
+            return `Editing ${input?.file_path ?? 'a file'}`;
+        case 'Bash':
+            return `Running: ${String(input?.command ?? '').slice(0, 60)}`;
+        case 'Grep':
+            return `Searching for "${input?.pattern ?? ''}"`;
+        case 'Glob':
+            return `Finding files matching ${input?.pattern ?? ''}`;
+        default:
+            return `Using ${name}`;
+    }
+}
+function sessionIdFromEvent(event) {
+    return typeof event?.session_id === 'string' ? event.session_id : null;
+}
+function describeEvent(event) {
+    if (event?.type !== 'assistant' || !event.message?.content)
+        return null;
+    for (const block of event.message.content) {
+        if (block.type === 'tool_use')
+            return describeToolUse(block.name, block.input);
+        if (block.type === 'text' && block.text)
+            return block.text.slice(0, 120);
+        // Thinking content isn't exposed by the API (comes back redacted/empty),
+        // but the block itself still arrives — surface it so "Starting..."
+        // doesn't sit frozen for the several seconds Claude spends reasoning
+        // before its first visible tool call.
+        if (block.type === 'thinking')
+            return 'Thinking...';
+    }
+    return null;
+}
+let cwd = process.cwd();
+let sessionId = null;
+let claudeProc = null;
+let busy = false; // a turn is currently running on the process
+// Which client to notify when the running turn finishes. Null for the
+// startup turn that sends KAPI_SESSION_PROMPT — there's no tab yet.
+let activeClient = null;
+// FIFO queue of turns waiting for the process to free up. The very first
+// entry, queued at server startup, is the KAPI_SESSION_PROMPT itself.
+const pendingPrompts = [];
+function ensureClaudeProc() {
+    if (claudeProc && claudeProc.exitCode === null)
+        return claudeProc;
+    const args = ['-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose', '--permission-mode', 'acceptEdits', '--allowedTools', 'Read,Edit,Write'];
+    if (sessionId)
+        args.push('--resume', sessionId);
+    let claude;
+    try {
+        claude = spawn('claude', args, { cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+    }
+    catch (err) {
+        console.error('[kapi] failed to spawn claude:', err);
+        return null;
+    }
+    claudeProc = claude;
+    let buffer = '';
+    claude.stdout.on('data', (chunk) => {
+        buffer += chunk.toString();
+        let newlineIndex;
+        while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+            const line = buffer.slice(0, newlineIndex).trim();
+            buffer = buffer.slice(newlineIndex + 1);
+            if (!line)
+                continue;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const nextSessionId = sessionIdFromEvent(event);
+            if (nextSessionId && nextSessionId !== sessionId) {
+                sessionId = nextSessionId;
+                console.log(`[kapi] claude session started: ${sessionId}`);
+            }
+            if (event.type === 'result') {
+                // Turn finished — notify the submitter (if any) and start the next queued turn.
+                busy = false;
+                activeClient?.send('kapi:done');
+                activeClient = null;
+                processQueue();
+                continue;
+            }
+            const status = describeEvent(event);
+            if (status)
+                activeClient?.send('kapi:processing', { status });
+        }
+    });
+    claude.stderr.pipe(process.stderr);
+    claude.on('error', (err) => {
+        console.error('[kapi] claude process error:', err);
+    });
+    // Writes to stdin can outrace process teardown (e.g. right after a kill()
+    // from stop()); without this listener that throws an uncaught EPIPE.
+    claude.stdin.on('error', (err) => {
+        console.error('[kapi] claude stdin error:', err);
+    });
+    claude.on('close', () => {
+        if (claudeProc === claude)
+            claudeProc = null;
+        // A queued turn (or the killed-and-stopped one's successor) respawns
+        // the process, resuming the same session via --resume.
+        busy = false;
+        processQueue();
+    });
+    return claude;
+}
+function processQueue() {
+    if (busy || pendingPrompts.length === 0)
+        return;
+    const claude = ensureClaudeProc();
+    if (!claude || !claude.stdin) {
+        console.error('[kapi] cannot process comments: claude process unavailable');
+        // Nothing will retry this later, so drain the whole backlog now rather
+        // than stranding everything behind the first failed prompt.
+        const stranded = pendingPrompts.splice(0, pendingPrompts.length);
+        for (const { client } of stranded)
+            client?.send('kapi:done');
+        return;
+    }
+    const next = pendingPrompts.shift();
+    busy = true;
+    activeClient = next.client;
+    next.client?.send('kapi:processing', { status: 'Starting...' });
+    try {
+        claude.stdin.write(JSON.stringify({
+            type: 'user',
+            message: { role: 'user', content: [{ type: 'text', text: next.prompt }] },
+        }) + '\n');
+    }
+    catch (err) {
+        console.error('[kapi] failed to write prompt to claude stdin:', err);
+        busy = false;
+        activeClient = null;
+        processQueue();
+    }
+}
+export const claudeAgent = {
+    start(startCwd) {
+        cwd = startCwd;
+        // Send the kapi instructions as the session's first turn, before any
+        // tab connects — also warms Claude's prompt cache so the user's actual
+        // first submission (turn 2) doesn't pay a cold-cache latency hit.
+        pendingPrompts.push({ prompt: KAPI_SESSION_PROMPT, client: null });
+        processQueue();
+    },
+    submit(prompt, client) {
+        pendingPrompts.push({ prompt, client });
+        processQueue();
+    },
+    stop(client) {
+        // Drop anything this client queued but hasn't started.
+        for (let i = pendingPrompts.length - 1; i >= 0; i--) {
+            if (pendingPrompts[i].client === client)
+                pendingPrompts.splice(i, 1);
+        }
+        if (activeClient === client && claudeProc) {
+            console.log('[kapi] stopping claude process');
+            claudeProc.kill();
+            // close handler respawns the process (resuming the session) so the
+            // next queued turn — from any tab — continues normally.
+        }
+    },
+    onClose(client) {
+        // A closed tab shouldn't leave orphaned queued work or a stuck queue.
+        claudeAgent.stop(client);
+    },
+};