wisp-agents 0.0.0-stage → 0.1.0

package/server/mcp-ask.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// Minimal stdio MCP server exposing `ask_user`, injected into every agent wisp launches.
+// The call is relayed to the wisp server, which surfaces it in the queue and blocks
+// (by polling) until the user answers — so the agent keeps its full context.
+
+import readline from 'node:readline';
+
+const { WISP_URL, WISP_TOKEN, WISP_SESSION } = process.env;
+
+const TOOL = {
+  name: 'ask_user',
+  description:
+    'Ask the user a question through wisp and wait for their answer. Use when a decision would change the rest of your work ' +
+    '(ambiguous requirements, risky/destructive steps, choosing between approaches). The user may take minutes or hours to answer. ' +
+    'Do not use it for trivial choices you can make yourself.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      question: { type: 'string', description: 'The question, one or two sentences.' },
+      context: { type: 'string', description: 'Optional markdown: what you found so far and why you are asking.' },
+      options: { type: 'array', items: { type: 'string' }, description: 'Optional suggested answers (2–4). The user can always type their own.' },
+    },
+    required: ['question'],
+  },
+};
+
+const send = (msg) => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...msg }) + '\n');
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function call(path, body) {
+  const res = await fetch(`${WISP_URL}${path}`, {
+    method: body ? 'POST' : 'GET',
+    headers: { 'content-type': 'application/json', 'x-wisp-token': WISP_TOKEN },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) throw new Error(`wisp ${res.status}: ${await res.text()}`);
+  return res.json();
+}
+
+async function askUser(args) {
+  const { id } = await call(`/api/internal/ask`, { session: WISP_SESSION, ...args });
+  for (;;) {
+    await sleep(1500);
+    let r;
+    try {
+      r = await call(`/api/internal/ask/${id}`);
+    } catch {
+      continue; // wisp restarting — keep waiting
+    }
+    if (r.answer !== undefined) return r.answer;
+    if (r.cancelled) return null;
+  }
+}
+
+readline.createInterface({ input: process.stdin }).on('line', async (line) => {
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    return;
+  }
+  const { id, method, params } = msg;
+  if (id === undefined) return; // notification
+
+  try {
+    if (method === 'initialize') {
+      send({ id, result: { protocolVersion: params?.protocolVersion || '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'wisp', version: '0.1.0' } } });
+    } else if (method === 'tools/list') {
+      send({ id, result: { tools: [TOOL] } });
+    } else if (method === 'tools/call' && params?.name === 'ask_user') {
+      const answer = await askUser(params.arguments || {});
+      const text = answer === null ? 'The user did not answer (the question was cancelled). Use your best judgment and note the assumption.' : `The user answered: ${answer}`;
+      send({ id, result: { content: [{ type: 'text', text }] } });
+    } else if (method === 'ping') {
+      send({ id, result: {} });
+    } else {
+      send({ id, error: { code: -32601, message: `Method not found: ${method}` } });
+    }
+  } catch (err) {
+    send({ id, result: { isError: true, content: [{ type: 'text', text: `wisp could not reach the user: ${err.message}` }] } });
+  }
+});

package/server/protocol.js

@@ -0,0 +1,114 @@
+// The wisp protocol: what we tell the agent, and how we read its answer back.
+// Agent-agnostic — any harness that can take an extra system prompt (or a prompt
+// prefix) and return a final text message can speak it.
+
+export const SYSTEM_PROMPT = `
+# You are running inside wisp
+
+wisp launched you to do a task on the user's behalf. The user is a software engineer who will NOT
+read your transcript, tool calls or intermediate messages. The only thing they will see is the
+presentation you put in your final message. Work autonomously:
+
+- Make sensible assumptions for small decisions, note them, keep going.
+- If a decision would change the rest of the work (ambiguous requirement, destructive or risky step,
+  two very different approaches), call the \`ask_user\` tool (mcp__wisp__ask_user). It pauses you until
+  the user answers in wisp — you keep all your context. Ask one crisp question with 2–4 options.
+- If the task is done but there is a choice for later, end with a "question" block instead.
+- Verify your work where it is cheap (tests, type-check, lint, build) and report results honestly,
+  including failures. Never claim something passes that you did not run.
+- The user can follow up; follow-ups resume this same session.
+- Attached files (images, video, docs) are listed in an <attachments> section of the prompt.
+
+## Your final message
+
+End your final message with exactly ONE fenced code block tagged \`wisp\` containing a JSON object
+\`{"blocks": [...]}\`. Anything outside the block is ignored. Write like a strong engineer's PR
+description for a busy reviewer: technical, precise, skimmable. Name files, functions, commands and
+numbers. No filler, no praise, no restating the task. Usually 4–8 blocks. Lead with evidence — the
+diff, the test run, the command output — over prose. Use file paths relative to the project root.
+
+### Blocks
+
+- {"type":"hero","title":"<what happened, ≤8 words>","summary":"<1–2 sentences>","status":"done|partial|blocked|info"}
+  Always first.
+- {"type":"markdown","text":"<github-flavoured markdown>"}
+- {"type":"steps","title":"…","items":[{"title":"…","detail":"…","status":"done|skipped|failed"}]}
+  What you did, in order.
+- {"type":"stats","items":[{"label":"tests passing","value":42,"unit":"","delta":"+6","tone":"good|bad|neutral"}]}
+  Numbers animate; use real numbers only.
+- {"type":"files","items":[{"path":"src/a.ts","change":"added|modified|deleted|renamed","note":"why"}]}
+- {"type":"diff","file":"src/a.ts","caption":"…"}
+  Shows the REAL diff of your edits to that file (wisp captured them). Use for the 1–3 most important changes.
+  Optionally add "before"/"after" strings to show a hand-picked snippet instead.
+- {"type":"tests","command":"npm test","passed":48,"failed":1,"skipped":2,"durationMs":5300,"failures":[{"name":"auth > rejects expired token","message":"expected 401, got 500","file":"test/auth.test.ts:42"}]}
+  A test/lint/type-check run you actually executed. Prefer this over "terminal" for test runs.
+- {"type":"commits","items":[{"hash":"a1b2c3d","message":"feat(auth): add rate limiter","files":3,"additions":120,"deletions":8}],"branch":"feat/limit"}
+  Commits you created, if any.
+- {"type":"tree","title":"…","items":[{"path":"src/auth/limiter.ts","change":"added","note":"…"}]}
+  A file tree; use for new modules/scaffolding where structure matters.
+- {"type":"code","language":"ts","code":"…","caption":"…","file":"src/a.ts","line":10,"highlight":[3,4]}
+  Key snippet (new API, signature, config) — not whole files.
+- {"type":"compare","before":{"label":"Before","items":["…"]},"after":{"label":"After","items":["…"]}}
+- {"type":"flow","title":"…","nodes":[{"id":"a","label":"Request","note":"…"}],"edges":[["a","b","label"]]}
+  Architecture / data flow / sequence. Edges optional (nodes are chained in order if omitted).
+- {"type":"chart","title":"…","unit":"ms","items":[{"label":"before","value":420},{"label":"after","value":95}]}
+- {"type":"terminal","command":"npm test","output":"<trimmed output>","exitCode":0}
+- {"type":"checklist","title":"…","items":[{"text":"…","done":true}]}
+- {"type":"callout","tone":"info|success|warn|danger","title":"…","text":"…"}
+  Risks, caveats, assumptions you made.
+- {"type":"image","path":"relative/or/absolute.png","caption":"…"}
+  A screenshot or generated image on disk.
+- {"type":"question","question":"…","options":[{"label":"Short choice","reply":"full message sent back to you"}]}
+  When you need a decision. The user's click resumes you with the reply.
+- {"type":"next","items":["Suggested follow-up the user might send", "…"]}
+  Usually last. 2–4 concrete follow-ups.
+
+Strings must be valid JSON (escape newlines as \\n and quotes as \\"). Example:
+
+\`\`\`wisp
+{"blocks":[
+  {"type":"hero","title":"Login now rate-limited","summary":"Added a sliding-window limiter to /login. 5 attempts per minute per IP.","status":"done"},
+  {"type":"diff","file":"src/auth/login.ts"},
+  {"type":"tests","command":"npm test","passed":48,"failed":0,"skipped":0,"durationMs":4100},
+  {"type":"callout","tone":"warn","title":"Assumption","text":"Behind a proxy, so I read the IP from X-Forwarded-For."},
+  {"type":"next","items":["Make the limit configurable","Add the same limiter to /reset-password"]}
+]}
+\`\`\`
+`.trim();
+
+const FENCE = /```wisp[^\n]*\n([\s\S]*?)\n?```/g;
+
+export function parsePresentation(text = '') {
+  const matches = [...text.matchAll(FENCE)];
+  const last = matches.at(-1);
+  if (last) {
+    const json = tryJson(last[1]);
+    const blocks = Array.isArray(json) ? json : json?.blocks;
+    if (Array.isArray(blocks) && blocks.length) {
+      const extra = text.slice(0, last.index).trim();
+      return { blocks: blocks.filter((b) => b && typeof b.type === 'string'), notes: extra || undefined };
+    }
+  }
+  // The agent ignored (or broke) the protocol — show its answer as plain markdown.
+  return {
+    fallback: true,
+    blocks: [{ type: 'markdown', text: text.replace(FENCE, '').trim() || '_The agent finished without a message._' }],
+  };
+}
+
+function tryJson(src) {
+  try {
+    return JSON.parse(src);
+  } catch {}
+  // Common LLM slips: trailing commas, smart quotes.
+  const relaxed = src.replace(/,\s*([}\]])/g, '$1').replace(/[“”]/g, '"');
+  try {
+    return JSON.parse(relaxed);
+  } catch {
+    return null;
+  }
+}
+
+export function heroOf(presentation) {
+  return presentation?.blocks?.find((b) => b.type === 'hero');
+}

package/server/runner.js

@@ -0,0 +1,282 @@
+// Session orchestration: launches turns on adapters, folds their events into the
+// session record, and queues follow-ups that arrive while the agent is busy.
+
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { adapters } from './adapters/index.js';
+import { SYSTEM_PROMPT, parsePresentation, heroOf } from './protocol.js';
+
+const MAX_ACTIVITY = 400;
+const ASK_SERVER = path.join(path.dirname(fileURLToPath(import.meta.url)), 'mcp-ask.js');
+
+export const newId = () => randomUUID().replace(/-/g, '').slice(0, 12);
+
+function autoTitle(prompt) {
+  const line = prompt.trim().split('\n')[0].replace(/\s+/g, ' ');
+  return line.length > 64 ? `${line.slice(0, 63)}…` : line;
+}
+
+export function summarize(s, store) {
+  const project = store?.projectFor(s.cwd);
+  const last = s.turns.at(-1);
+  const hero = heroOf(last?.presentation);
+  const lastAct = last?.activity?.findLast?.((a) => a.kind !== 'text');
+  return {
+    id: s.id,
+    title: s.title,
+    agent: s.agent,
+    cwd: s.cwd,
+    project: s.agent === 'wisp' ? 'tour' : project?.name || path.basename(s.cwd || ''),
+    projectId: project?.id || null,
+    color: project?.color || 'slate',
+    mode: s.mode,
+    model: s.model,
+    state: s.state,
+    unread: s.unread,
+    createdAt: s.createdAt,
+    updatedAt: s.updatedAt,
+    turnCount: s.turns.length,
+    queued: s.queue?.length || 0,
+    status: last?.status === 'running' ? 'running' : hero?.status || (last?.status === 'error' ? 'blocked' : 'info'),
+    preview: hero?.summary || '',
+    live: s.ask ? `Asks: ${s.ask.question}` : last?.status === 'running' ? lastAct?.label || 'Starting up' : '',
+    asks: !!s.ask || !!last?.presentation?.blocks?.some((b) => b.type === 'question'),
+    question: s.ask?.question || '',
+  };
+}
+
+export class Runner extends EventEmitter {
+  // bridge: { url, token } — how the injected ask_user MCP server reaches us.
+  constructor(store, bridge) {
+    super();
+    this.store = store;
+    this.bridge = bridge;
+    this.live = new Map(); // sessionId -> adapter handle
+    this.stopping = new Set();
+    this.answers = new Map(); // askId -> answer, until the MCP server picks it up
+
+    // Anything that was mid-flight when wisp last died is now orphaned.
+    for (const s of store.all()) {
+      const t = s.turns.at(-1);
+      delete s.ask;
+      if (s.state === 'running' || s.state === 'waiting' || t?.status === 'running') {
+        if (t?.status === 'running') this.#finishTurn(s, t, { isError: true, stopped: true, text: '' }, 'wisp was restarted while this was running.');
+        s.state = 'review';
+        store.save(s);
+      }
+    }
+  }
+
+  create({ prompt, cwd, agent = 'claude', mode = 'edits', model = '', attachments = [] }) {
+    if (!adapters[agent]) throw new Error(`Unknown agent: ${agent}`);
+    const now = Date.now();
+    const session = {
+      id: newId(),
+      title: autoTitle(prompt),
+      titleAuto: true,
+      agent,
+      cwd,
+      mode,
+      model,
+      state: 'running',
+      unread: false,
+      createdAt: now,
+      updatedAt: now,
+      agentSessionId: null,
+      queue: [],
+      turns: [],
+    };
+    this.store.put(session);
+    this.store.touchProject(cwd);
+    this.#startTurn(session, prompt, attachments);
+    return session;
+  }
+
+  reply(session, text, attachments = []) {
+    if (session.ask) {
+      this.answer(session, text);
+      return { answered: true };
+    }
+    if (this.live.has(session.id)) {
+      session.queue.push({ text, attachments });
+      this.#touch(session);
+      return { queued: true };
+    }
+    this.#startTurn(session, text, attachments);
+    return { queued: false };
+  }
+
+  // ask_user: the agent is blocked inside a tool call until answer() is called.
+  ask(session, { question, context, options }) {
+    const turn = session.turns.at(-1);
+    session.ask = {
+      id: newId(),
+      question: String(question || '').trim() || 'The agent has a question.',
+      context: context ? String(context) : '',
+      options: Array.isArray(options) ? options.map(String).slice(0, 6) : [],
+      askedAt: Date.now(),
+    };
+    session.state = 'waiting';
+    session.unread = true;
+    if (turn) this.#onEvent(session, turn, { type: 'tool', kind: 'ask', label: `Asked you: ${session.ask.question}` });
+    this.#touch(session, { turn: turn?.id });
+    this.emit('finished', { session: summarize(session, this.store) });
+    return session.ask.id;
+  }
+
+  answer(session, text) {
+    const ask = session.ask;
+    if (!ask) return false;
+    ask.answer = text;
+    this.answers.set(ask.id, text);
+    delete session.ask;
+    session.state = this.live.has(session.id) ? 'running' : 'review';
+    const turn = session.turns.at(-1);
+    if (turn) this.#onEvent(session, turn, { type: 'tool', kind: 'answer', label: `You answered: ${text}` });
+    this.#touch(session, { turn: turn?.id });
+    return true;
+  }
+
+  pollAnswer(askId) {
+    if (this.answers.has(askId)) {
+      const answer = this.answers.get(askId);
+      this.answers.delete(askId);
+      return { answer };
+    }
+    const open = this.store.all().some((s) => s.ask?.id === askId);
+    return open ? { pending: true } : { cancelled: true };
+  }
+
+  stop(session) {
+    session.queue = [];
+    delete session.ask;
+    if (!this.live.has(session.id)) return;
+    this.stopping.add(session.id);
+    this.live.get(session.id).stop();
+  }
+
+  #startTurn(session, prompt, attachments = []) {
+    const turn = {
+      id: newId(),
+      prompt,
+      attachments: attachments.map(({ id, name, mime, size }) => ({ id, name, mime, size })),
+      startedAt: Date.now(),
+      endedAt: null,
+      status: 'running',
+      activity: [],
+      changes: [],
+      presentation: null,
+      stats: null,
+    };
+    session.turns.push(turn);
+    session.state = 'running';
+    session.unread = false;
+    this.#touch(session, { turn: turn.id });
+
+    const adapter = adapters[session.agent];
+    const handle = adapter.run({
+      prompt,
+      attachments,
+      cwd: session.cwd,
+      resumeId: session.agentSessionId,
+      mode: session.mode,
+      model: session.model,
+      systemPrompt: SYSTEM_PROMPT,
+      mcpServers: this.bridge
+        ? {
+            wisp: {
+              command: process.execPath,
+              args: [ASK_SERVER],
+              env: { WISP_URL: this.bridge.url, WISP_TOKEN: this.bridge.token, WISP_SESSION: session.id },
+            },
+          }
+        : {},
+      onEvent: (ev) => this.#onEvent(session, turn, ev),
+    });
+    this.live.set(session.id, handle);
+
+    handle.done.finally(() => {
+      this.live.delete(session.id);
+      if (turn.status === 'running') this.#finishTurn(session, turn, { isError: true, text: 'The agent exited without a result.' });
+      const next = session.queue.shift();
+      if (next && this.store.get(session.id)) this.#startTurn(session, next.text, next.attachments);
+      else this.#touch(session);
+    });
+  }
+
+  #onEvent(session, turn, ev) {
+    switch (ev.type) {
+      case 'session':
+        session.agentSessionId = ev.id;
+        return;
+      case 'tool':
+      case 'tool_error':
+      case 'text': {
+        const item = { t: Date.now(), kind: ev.type === 'tool' ? ev.kind : ev.type === 'text' ? 'text' : 'error' };
+        if (ev.type === 'tool') Object.assign(item, { label: ev.label, file: ev.file, detail: ev.detail });
+        else if (ev.type === 'text') item.label = ev.text.slice(0, 600);
+        else item.label = `${ev.name || 'Tool'} failed: ${ev.text}`;
+        turn.activity.push(item);
+        if (turn.activity.length > MAX_ACTIVITY) turn.activity.splice(0, turn.activity.length - MAX_ACTIVITY);
+        this.emit('activity', { sessionId: session.id, turnId: turn.id, item });
+        this.#touch(session, { quiet: ev.type === 'text' });
+        return;
+      }
+      case 'change': {
+        let entry = turn.changes.find((c) => c.file === ev.file);
+        if (!entry) turn.changes.push((entry = { file: ev.file, op: ev.op, edits: [] }));
+        if (ev.op === 'create' && entry.edits.length === 0) entry.op = 'create';
+        entry.edits.push(...ev.edits);
+        this.store.save(session);
+        return;
+      }
+      case 'result':
+        this.#finishTurn(session, turn, ev);
+        return;
+    }
+  }
+
+  #finishTurn(session, turn, ev, reason) {
+    turn.endedAt = Date.now();
+    turn.stats = ev.stats || null;
+    delete session.ask;
+    if (this.stopping.delete(session.id)) ev = { ...ev, stopped: true };
+    if (ev.stopped) {
+      turn.status = 'stopped';
+      turn.presentation = {
+        blocks: [
+          { type: 'hero', title: 'Stopped', summary: reason || 'You stopped this run. Follow up to pick it back up.', status: 'partial' },
+          ...(turn.changes.length ? [{ type: 'files', items: turn.changes.map((c) => ({ path: c.file, change: c.op === 'create' ? 'added' : 'modified' })) }] : []),
+        ],
+      };
+    } else if (ev.isError) {
+      turn.status = 'error';
+      turn.presentation = {
+        blocks: [
+          { type: 'hero', title: 'Something went wrong', summary: 'The agent run ended with an error.', status: 'blocked' },
+          { type: 'terminal', command: `${session.agent} run`, output: ev.text || 'No output.', exitCode: 1 },
+          { type: 'next', items: ['Try again', 'Explain what went wrong'] },
+        ],
+      };
+    } else {
+      turn.status = 'done';
+      turn.presentation = parsePresentation(ev.text);
+      const hero = heroOf(turn.presentation);
+      if (hero?.title && session.titleAuto && session.turns.length === 1) session.title = hero.title;
+    }
+    session.state = 'review';
+    session.unread = true;
+    this.store.save(session, { now: true });
+    this.#touch(session, { turn: turn.id });
+    this.emit('finished', { session: summarize(session, this.store) });
+  }
+
+  #touch(session, { turn, quiet } = {}) {
+    session.updatedAt = Date.now();
+    this.store.save(session);
+    if (!quiet) this.emit('summary', summarize(session, this.store));
+    if (turn) this.emit('turn', { sessionId: session.id, turnId: turn });
+  }
+}

package/server/store.js

@@ -0,0 +1,120 @@
+// Persistence: one JSON file per session under ~/.wisp/sessions, plus config.json.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const DEFAULT_CONFIG = {
+  projects: [], // [{ id, name, path, color, addedAt }]
+  defaults: { agent: 'claude', mode: 'edits', model: '' },
+};
+
+export const PROJECT_COLORS = ['violet', 'teal', 'amber', 'rose', 'sky', 'lime', 'orange', 'indigo'];
+
+export class Store {
+  constructor(home = process.env.WISP_HOME || path.join(os.homedir(), '.wisp')) {
+    this.home = home;
+    this.dir = path.join(home, 'sessions');
+    fs.mkdirSync(this.dir, { recursive: true });
+    this.sessions = new Map();
+    this.timers = new Map();
+    this.config = this.#loadConfig();
+
+    for (const f of fs.readdirSync(this.dir)) {
+      if (!f.endsWith('.json')) continue;
+      try {
+        const s = JSON.parse(fs.readFileSync(path.join(this.dir, f), 'utf8'));
+        this.sessions.set(s.id, s);
+      } catch (err) {
+        console.warn(`wisp: skipping unreadable session ${f}: ${err.message}`);
+      }
+    }
+  }
+
+  #loadConfig() {
+    try {
+      const raw = JSON.parse(fs.readFileSync(path.join(this.home, 'config.json'), 'utf8'));
+      const cfg = { ...structuredClone(DEFAULT_CONFIG), ...raw, defaults: { ...DEFAULT_CONFIG.defaults, ...raw.defaults } };
+      cfg.projects ||= [];
+      return cfg;
+    } catch {
+      return structuredClone(DEFAULT_CONFIG);
+    }
+  }
+
+  saveConfig() {
+    fs.writeFileSync(path.join(this.home, 'config.json'), JSON.stringify(this.config, null, 2));
+  }
+
+  // --- projects: plain folders, matched to sessions by path prefix ---
+
+  projectFor(cwd = '') {
+    let best = null;
+    for (const p of this.config.projects)
+      if ((cwd === p.path || cwd.startsWith(p.path + path.sep)) && (!best || p.path.length > best.path.length)) best = p;
+    return best;
+  }
+
+  addProject(dir, { name, color } = {}) {
+    const existing = this.config.projects.find((p) => p.path === dir);
+    if (existing) return existing;
+    const used = new Set(this.config.projects.map((p) => p.color));
+    const project = {
+      id: Math.random().toString(36).slice(2, 10),
+      name: name || path.basename(dir) || dir,
+      path: dir,
+      color: color || PROJECT_COLORS.find((c) => !used.has(c)) || PROJECT_COLORS[this.config.projects.length % PROJECT_COLORS.length],
+      addedAt: Date.now(),
+    };
+    this.config.projects.push(project);
+    this.saveConfig();
+    return project;
+  }
+
+  touchProject(dir) {
+    const p = this.projectFor(dir) || this.addProject(dir);
+    p.lastUsedAt = Date.now();
+    this.saveConfig();
+    return p;
+  }
+
+  all() {
+    return [...this.sessions.values()];
+  }
+
+  get(id) {
+    return this.sessions.get(id);
+  }
+
+  put(session) {
+    this.sessions.set(session.id, session);
+    this.save(session);
+  }
+
+  // Debounced write so streaming activity doesn't hammer the disk.
+  save(session, { now = false } = {}) {
+    clearTimeout(this.timers.get(session.id));
+    const write = () => {
+      this.timers.delete(session.id);
+      if (!this.sessions.has(session.id)) return;
+      const file = path.join(this.dir, `${session.id}.json`);
+      fs.writeFileSync(`${file}.tmp`, JSON.stringify(session));
+      fs.renameSync(`${file}.tmp`, file);
+    };
+    if (now) write();
+    else this.timers.set(session.id, setTimeout(write, 400));
+  }
+
+  delete(id) {
+    clearTimeout(this.timers.get(id));
+    this.sessions.delete(id);
+    fs.rmSync(path.join(this.dir, `${id}.json`), { force: true });
+  }
+
+  flush() {
+    for (const id of [...this.timers.keys()]) {
+      const s = this.sessions.get(id);
+      if (s) this.save(s, { now: true });
+    }
+  }
+}

package/server/terminal.js

@@ -0,0 +1,73 @@
+// Open a command in the user's terminal so they can take over an agent session interactively.
+
+import { spawn, execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+
+export const TERMINALS = [
+  { id: 'auto', label: 'Auto-detect' },
+  { id: 'terminal', label: 'Terminal.app', mac: true },
+  { id: 'iterm', label: 'iTerm', mac: true, app: '/Applications/iTerm.app' },
+  { id: 'ghostty', label: 'Ghostty', app: '/Applications/Ghostty.app', bin: 'ghostty' },
+  { id: 'warp', label: 'Warp', mac: true, app: '/Applications/Warp.app' },
+  { id: 'kitty', label: 'kitty', app: '/Applications/kitty.app', bin: 'kitty' },
+  { id: 'wezterm', label: 'WezTerm', app: '/Applications/WezTerm.app', bin: 'wezterm' },
+  { id: 'custom', label: 'Custom command' },
+];
+
+export const shq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+
+const has = (bin) => {
+  try {
+    execFileSync('which', [bin], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+function detect() {
+  if (process.platform === 'darwin') {
+    if (process.env.TERM_PROGRAM === 'iTerm.app' && fs.existsSync('/Applications/iTerm.app')) return 'iterm';
+    if (process.env.TERM_PROGRAM === 'ghostty' && fs.existsSync('/Applications/Ghostty.app')) return 'ghostty';
+    return 'terminal';
+  }
+  for (const t of ['ghostty', 'kitty', 'wezterm']) if (has(t)) return t;
+  return 'x-terminal-emulator';
+}
+
+const osa = (script) => spawn('osascript', ['-e', script], { detached: true, stdio: 'ignore' }).unref();
+const asStr = (s) => `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+
+// argv: the agent's resume command, e.g. ['claude', '--resume', 'abc'].
+export function openInTerminal({ cwd, argv, terminal = 'auto', custom = '' }) {
+  const cmd = argv.map(shq).join(' ');
+  const line = `cd ${shq(cwd)} && ${cmd}`;
+  const t = terminal === 'auto' ? detect() : terminal;
+  const mac = process.platform === 'darwin';
+
+  switch (t) {
+    case 'terminal':
+      return osa(`tell application "Terminal"\nactivate\ndo script ${asStr(line)}\nend tell`);
+    case 'iterm':
+      return osa(`tell application "iTerm"\nactivate\nset w to (create window with default profile)\ntell current session of w to write text ${asStr(line)}\nend tell`);
+    case 'warp':
+      // Warp has no scripting API; open a tab in the folder and type via System Events.
+      spawn('open', ['-a', 'Warp', cwd], { detached: true, stdio: 'ignore' }).unref();
+      return setTimeout(() => osa(`tell application "System Events" to keystroke ${asStr(cmd)} & return`), 1200);
+    case 'ghostty':
+      if (mac) return spawn('open', ['-na', 'Ghostty', '--args', `--working-directory=${cwd}`, '-e', ...argv], { detached: true, stdio: 'ignore' }).unref();
+      return spawn('ghostty', [`--working-directory=${cwd}`, '-e', ...argv], { detached: true, stdio: 'ignore' }).unref();
+    case 'kitty':
+      if (mac) return spawn('open', ['-na', 'kitty', '--args', '--directory', cwd, ...argv], { detached: true, stdio: 'ignore' }).unref();
+      return spawn('kitty', ['--directory', cwd, ...argv], { detached: true, stdio: 'ignore' }).unref();
+    case 'wezterm':
+      return spawn(mac ? '/Applications/WezTerm.app/Contents/MacOS/wezterm' : 'wezterm', ['start', '--cwd', cwd, '--', ...argv], { detached: true, stdio: 'ignore' }).unref();
+    case 'custom': {
+      if (!custom) throw new Error('Set a custom terminal command in settings, e.g.  alacritty --working-directory {cwd} -e {cmd}');
+      const full = custom.replaceAll('{cwd}', shq(cwd)).replaceAll('{cmd}', cmd).replaceAll('{line}', shq(line));
+      return spawn('sh', ['-c', full], { detached: true, stdio: 'ignore' }).unref();
+    }
+    default:
+      return spawn('x-terminal-emulator', ['-e', 'sh', '-c', `${line}; exec $SHELL`], { detached: true, stdio: 'ignore' }).unref();
+  }
+}