wisp-agents 0.4.0 → 0.6.0

package/server/mcp-wisp.js

@@ -0,0 +1,164 @@
+// `wisp mcp`: a stdio MCP server that lets any MCP-capable agent or editor (Claude Code, Codex,
+// opencode, Cursor, Antigravity, Claude Desktop, Zed, …) hand tasks to wisp and read the results back.
+// It talks to the running wisp over HTTP (starting a headless one if needed) via the client SDK.
+//
+//   claude mcp add wisp -- npx -y wisp-agents mcp
+
+import readline from 'node:readline';
+import fs from 'node:fs';
+import { WispClient } from './client.js';
+
+const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const AGENTS = ['claude', 'codex', 'opencode', 'cursor', 'antigravity'];
+const DEFAULT_WAIT_S = 240; // stay under typical MCP client tool-call timeouts; call wisp_wait again for more
+
+const TOOLS = [
+  {
+    name: 'wisp_launch',
+    description:
+      'Hand a coding task to a background agent in wisp. The agent works autonomously in the given folder and ends with a ' +
+      'presentation (summary, diffs, test results). Returns the session id at once; pass wait=true to block until it finishes ' +
+      'or asks a question. Use for independent, well-scoped tasks that can run in parallel with your own work.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prompt: { type: 'string', description: 'The task, written as you would brief a colleague: goal, constraints, how to verify.' },
+        cwd: { type: 'string', description: 'Absolute path of the project folder. Default: this MCP server’s working directory.' },
+        agent: { type: 'string', enum: AGENTS, description: 'Harness to run. Default: the user’s last pick in wisp.' },
+        mode: { type: 'string', enum: ['plan', 'edits', 'auto'], description: 'plan = read-only, edits = auto-accept file edits, auto = no permission prompts. Default: the user’s pick.' },
+        model: { type: 'string', description: 'Model id for that harness. Default: the user’s pick.' },
+        effort: { type: 'string', description: 'Thinking level, e.g. low | medium | high.' },
+        wait: { type: 'boolean', description: 'Block until the agent finishes or asks (up to timeout_seconds).' },
+        timeout_seconds: { type: 'number', description: `Max wait when wait=true. Default ${DEFAULT_WAIT_S}.` },
+      },
+      required: ['prompt'],
+    },
+  },
+  {
+    name: 'wisp_list',
+    description: 'List wisp sessions, newest first, with state (running | waiting | review | done) and a one-line summary.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        state: { type: 'string', description: 'Comma-separated filter, e.g. "running,waiting".' },
+        cwd: { type: 'string', description: 'Only sessions in this folder (or below).' },
+        limit: { type: 'number', description: 'Default 20.' },
+      },
+    },
+  },
+  {
+    name: 'wisp_get',
+    description: 'Read a session: its state and the latest presentation as markdown (diffs, tests, next steps), plus any question the agent is waiting on.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+  },
+  {
+    name: 'wisp_wait',
+    description: 'Block until a session finishes or asks a question, then return it like wisp_get. Returns early with timed_out if it is still running.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' }, timeout_seconds: { type: 'number', description: `Default ${DEFAULT_WAIT_S}.` } }, required: ['id'] },
+  },
+  {
+    name: 'wisp_reply',
+    description:
+      'Send a follow-up to a session; it resumes the same agent conversation. If the agent is waiting on a question, this answers it. ' +
+      'A follow-up sent while it runs interrupts it (queue=true waits for the run to finish instead).',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' }, text: { type: 'string' }, queue: { type: 'boolean' } }, required: ['id', 'text'] },
+  },
+  {
+    name: 'wisp_stop',
+    description: 'Stop a running session.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+  },
+  {
+    name: 'wisp_agents',
+    description: 'Which harnesses are installed, with their models and thinking levels.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+let client;
+const wisp = async () => (client ||= await WispClient.connect());
+
+const line = (s) => `- \`${s.id}\` **${s.title}** — ${s.state}${s.state === 'running' ? ` (${s.live})` : s.preview ? `: ${s.preview}` : ''}${s.question ? ` — asks: ${s.question}` : ''} [${s.agent}, ${s.project}]`;
+
+async function describe(id, extra = '') {
+  const c = await wisp();
+  const [s, p] = await Promise.all([c.session(id), c.presentation(id)]);
+  const head = `Session \`${id}\` — **${s?.title}** — state: **${s?.state}**${extra}`;
+  const hint =
+    s?.state === 'waiting' ? '\n\n_Answer with wisp_reply._' : s?.state === 'running' ? '\n\n_Still running. Call wisp_wait to block until it finishes._' : '';
+  return `${head}\n\n${p.markdown}${hint}`;
+}
+
+async function callTool(name, a = {}) {
+  const c = await wisp();
+  const waitFor = async (id) => {
+    const s = await c.wait(id, { timeoutMs: (Number(a.timeout_seconds) || DEFAULT_WAIT_S) * 1000 });
+    return describe(id, s.timedOut ? ' (timed out waiting; still running)' : '');
+  };
+  switch (name) {
+    case 'wisp_launch': {
+      if (!a.prompt?.trim()) throw new Error('prompt is required');
+      const s = await c.launch({ prompt: a.prompt, cwd: a.cwd || process.cwd(), agent: a.agent, mode: a.mode, model: a.model, effort: a.effort });
+      if (a.wait) return waitFor(s.id);
+      return `Launched session \`${s.id}\` (“${s.title}”) on ${s.agent} in ${s.cwd}, mode ${s.mode}. Call wisp_wait or wisp_get with this id for the result.`;
+    }
+    case 'wisp_list': {
+      const list = await c.sessions({ state: a.state, cwd: a.cwd, limit: Number(a.limit) || 20 });
+      return list.length ? list.map(line).join('\n') : 'No sessions.';
+    }
+    case 'wisp_get':
+      return describe(a.id);
+    case 'wisp_wait':
+      return waitFor(a.id);
+    case 'wisp_reply': {
+      if (!a.text?.trim()) throw new Error('text is required');
+      const r = await c.reply(a.id, a.text.trim(), { queue: a.queue });
+      return r.answered ? 'Answered the agent’s question; it is continuing.' : r.interrupted ? 'Interrupted the run; it resumes with your message.' : r.queued ? 'Queued; it goes out when the current run finishes.' : 'Sent; the agent is working on it.';
+    }
+    case 'wisp_stop':
+      await c.stop(a.id);
+      return `Stopped \`${a.id}\`.`;
+    case 'wisp_agents':
+      return (await c.agents())
+        .map((x) => `- **${x.id}** (${x.name}) — ${x.available ? `installed${x.version ? ` ${x.version}` : ''}; models: ${(x.models || []).map((m) => m.id).filter(Boolean).slice(0, 12).join(', ') || 'default'}` : 'not installed'}`)
+        .join('\n');
+    default:
+      throw Object.assign(new Error(`Unknown tool: ${name}`), { code: -32602 });
+  }
+}
+
+export function serveMcp({ input = process.stdin, output = process.stdout } = {}) {
+  const send = (msg) => output.write(JSON.stringify({ jsonrpc: '2.0', ...msg }) + '\n');
+  readline.createInterface({ input }).on('line', async (raw) => {
+    let msg;
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    const { id, method, params } = msg;
+    if (id === undefined) return; // notification
+    if (method === 'initialize')
+      return send({
+        id,
+        result: {
+          protocolVersion: params?.protocolVersion || '2025-06-18',
+          capabilities: { tools: {} },
+          serverInfo: { name: 'wisp', version: VERSION },
+          instructions: 'wisp runs coding agents in the background. Launch with wisp_launch, then wisp_wait / wisp_get for the result; wisp_reply to follow up or answer a question.',
+        },
+      });
+    if (method === 'tools/list') return send({ id, result: { tools: TOOLS } });
+    if (method === 'ping') return send({ id, result: {} });
+    if (method === 'tools/call') {
+      try {
+        const text = await callTool(params?.name, params?.arguments || {});
+        return send({ id, result: { content: [{ type: 'text', text }] } });
+      } catch (err) {
+        if (err.code === -32602) return send({ id, error: { code: err.code, message: err.message } });
+        return send({ id, result: { isError: true, content: [{ type: 'text', text: `wisp: ${err.message}` }] } });
+      }
+    }
+    send({ id, error: { code: -32601, message: `Method not found: ${method}` } });
+  });
+}

package/server/openapi.js

@@ -0,0 +1,184 @@
+// OpenAPI 3.1 description of the public HTTP API, served at GET /api/openapi.json.
+// Feed it to any OpenAPI client generator, Postman, or an agent's tool loader.
+// Routes under /api/internal are wisp's own plumbing and deliberately left out.
+
+const ref = (name) => ({ $ref: `#/components/schemas/${name}` });
+const json = (schema, description = 'OK') => ({ description, content: { 'application/json': { schema } } });
+const id = { name: 'id', in: 'path', required: true, schema: { type: 'string' }, description: 'Session id' };
+const body = (schema) => ({ required: true, content: { 'application/json': { schema } } });
+const err = { 400: json(ref('Error'), 'Bad request'), 404: json(ref('Error'), 'Not found') };
+const ok = json({ type: 'object', properties: { ok: { type: 'boolean' } } });
+
+export function openapi({ version, port }) {
+  return {
+    openapi: '3.1.0',
+    info: {
+      title: 'wisp',
+      version,
+      description:
+        'Local API of wisp, a launcher and queue for coding agents (Claude Code, Codex, opencode, Cursor, Antigravity). ' +
+        'Binds to 127.0.0.1 only. Requests must carry a Host of 127.0.0.1/localhost:<port>; non-GET requests must be ' +
+        'application/json (uploads: application/octet-stream) and, if they send an Origin, a local one. ' +
+        'The running server advertises { url, port, pid, version } in ~/.wisp/server.json.',
+    },
+    servers: [{ url: `http://127.0.0.1:${port}/api` }],
+    paths: {
+      '/health': { get: { summary: 'Liveness, version and pid', responses: { 200: json(ref('Health')) } } },
+      '/agents': { get: { summary: 'Installed harnesses with their models and thinking levels', responses: { 200: json({ type: 'array', items: ref('Agent') }) } } },
+      '/config': {
+        get: { summary: 'Launcher defaults, projects, webhooks', responses: { 200: json({ type: 'object' }) } },
+        patch: {
+          summary: 'Update defaults and/or webhooks',
+          requestBody: body({
+            type: 'object',
+            properties: {
+              defaults: { type: 'object', description: 'Merged into the current defaults (agent, mode, model, models, effort, efforts, followUp, terminal, …)' },
+              webhooks: { type: 'array', items: { oneOf: [{ type: 'string', format: 'uri' }, ref('Webhook')] }, description: 'Replaces the webhook list' },
+            },
+          }),
+          responses: { 200: json({ type: 'object' }), 400: err[400] },
+        },
+      },
+      '/projects': {
+        get: { summary: 'List projects', responses: { 200: json({ type: 'array', items: ref('Project') }) } },
+        post: { summary: 'Add a folder as a project', requestBody: body({ type: 'object', required: ['path'], properties: { path: { type: 'string' }, name: { type: 'string' } } }), responses: { 201: json(ref('Project')), 400: err[400] } },
+      },
+      '/projects/{pid}': {
+        parameters: [{ name: 'pid', in: 'path', required: true, schema: { type: 'string' } }],
+        patch: { summary: 'Rename or recolor', requestBody: body({ type: 'object', properties: { name: { type: 'string' }, color: { type: 'string' } } }), responses: { 200: json(ref('Project')), 404: err[404] } },
+        delete: { summary: 'Remove the project (sessions are kept)', responses: { 200: ok, 404: err[404] } },
+      },
+      '/sessions': {
+        get: {
+          summary: 'List sessions, newest first',
+          parameters: [
+            { name: 'state', in: 'query', schema: { type: 'string' }, description: 'Comma-separated: running,waiting,review,done' },
+            { name: 'agent', in: 'query', schema: { type: 'string' } },
+            { name: 'project', in: 'query', schema: { type: 'string' }, description: 'Project id or name' },
+            { name: 'cwd', in: 'query', schema: { type: 'string' }, description: 'Sessions in this folder or below' },
+            { name: 'archived', in: 'query', schema: { type: 'boolean' } },
+            { name: 'limit', in: 'query', schema: { type: 'integer' } },
+          ],
+          responses: { 200: json({ type: 'array', items: ref('Summary') }) },
+        },
+        post: { summary: 'Launch a task', requestBody: body(ref('Launch')), responses: { 201: json(ref('Summary')), 400: err[400] } },
+      },
+      '/sessions/{id}': {
+        parameters: [id],
+        get: { summary: 'Full session record: turns, activity, captured edits, presentations', responses: { 200: json({ type: 'object' }), 404: err[404] } },
+        patch: {
+          summary: 'Rename, mark done/review, mark read, archive',
+          requestBody: body({ type: 'object', properties: { title: { type: 'string' }, state: { enum: ['done', 'review'] }, unread: { type: 'boolean' }, archived: { type: 'boolean' } } }),
+          responses: { 200: json(ref('Summary')), 404: err[404] },
+        },
+        delete: { summary: 'Stop and delete', responses: { 200: ok, 404: err[404] } },
+      },
+      '/sessions/{id}/wait': {
+        parameters: [id, { name: 'timeout', in: 'query', schema: { type: 'integer', default: 60, maximum: 290 }, description: 'Seconds' }],
+        get: { summary: 'Long-poll until the session needs you (finished or asking)', responses: { 200: json({ allOf: [ref('Summary'), { type: 'object', properties: { timedOut: { type: 'boolean' } } }] }), 404: err[404] } },
+      },
+      '/sessions/{id}/presentation': {
+        parameters: [
+          id,
+          { name: 'turn', in: 'query', schema: { type: 'string' }, description: 'Turn id or index (negative counts from the end). Default: latest' },
+          { name: 'format', in: 'query', schema: { enum: ['json', 'markdown'] } },
+        ],
+        get: { summary: 'A turn’s presentation as blocks and markdown', responses: { 200: json(ref('Presentation')), 404: err[404] } },
+      },
+      '/sessions/{id}/reply': {
+        parameters: [id],
+        post: {
+          summary: 'Follow up (answers a pending ask_user question if there is one)',
+          requestBody: body({ type: 'object', required: ['text'], properties: { text: { type: 'string' }, attachments: { type: 'array', items: { type: 'string' } }, queue: { type: 'boolean', description: 'Wait for the current run instead of interrupting it' } } }),
+          responses: { 200: json({ type: 'object', properties: { answered: { type: 'boolean' }, queued: { type: 'boolean' }, interrupted: { type: 'boolean' }, ahead: { type: 'integer' } } }), 400: err[400] },
+        },
+      },
+      '/sessions/{id}/answer': { parameters: [id], post: { summary: 'Answer the pending ask_user question', requestBody: body({ type: 'object', required: ['text'], properties: { text: { type: 'string' } } }), responses: { 200: ok } } },
+      '/sessions/{id}/stop': { parameters: [id], post: { summary: 'Stop the run and drop queued follow-ups', responses: { 200: ok } } },
+      '/sessions/{id}/queue': { parameters: [id, { name: 'item', in: 'query', required: true, schema: { type: 'string' } }], delete: { summary: 'Cancel a queued follow-up', responses: { 200: ok, 404: err[404] } } },
+      '/sessions/{id}/takeover': {
+        parameters: [id],
+        get: { summary: 'The shell command that resumes this agent session interactively', responses: { 200: json({ type: 'object', properties: { command: { type: 'string' } } }) } },
+        post: { summary: 'Stop the run and open the resume command in the user’s terminal', responses: { 200: json({ type: 'object', properties: { command: { type: 'string' } } }) } },
+      },
+      '/uploads': {
+        post: {
+          summary: 'Upload an attachment (raw body). Pass the returned id in attachments',
+          parameters: [{ name: 'name', in: 'query', schema: { type: 'string' } }, { name: 'type', in: 'query', schema: { type: 'string' }, description: 'MIME type' }],
+          requestBody: { required: true, content: { 'application/octet-stream': { schema: { type: 'string', format: 'binary' } } } },
+          responses: { 201: json({ type: 'object', properties: { id: { type: 'string' }, name: { type: 'string' }, size: { type: 'integer' }, mime: { type: 'string' } } }) },
+        },
+      },
+      '/events': {
+        get: {
+          summary: 'Server-sent events: summary, activity, turn, finished, removed, config, ping',
+          responses: { 200: { description: 'text/event-stream', content: { 'text/event-stream': { schema: { type: 'string' } } } } },
+        },
+      },
+    },
+    components: {
+      schemas: {
+        Error: { type: 'object', properties: { error: { type: 'string' } } },
+        Health: { type: 'object', properties: { ok: { type: 'boolean' }, name: { const: 'wisp' }, version: { type: 'string' }, apiVersion: { type: 'integer' }, pid: { type: 'integer' }, url: { type: 'string' } } },
+        Agent: { type: 'object', properties: { id: { type: 'string' }, name: { type: 'string' }, available: { type: 'boolean' }, version: { type: 'string' }, models: { type: 'array', items: { type: 'object' } }, efforts: { type: 'array', items: { type: 'string' } } } },
+        Project: { type: 'object', properties: { id: { type: 'string' }, name: { type: 'string' }, path: { type: 'string' }, color: { type: 'string' } } },
+        Webhook: { type: 'object', required: ['url'], properties: { url: { type: 'string', format: 'uri' }, events: { type: 'array', items: { enum: ['session.finished', 'session.waiting'] } } } },
+        Launch: {
+          type: 'object',
+          required: ['prompt'],
+          properties: {
+            prompt: { type: 'string' },
+            cwd: { type: 'string', description: 'Project folder (absolute; ~ allowed). Default: the server’s cwd' },
+            agent: { enum: ['claude', 'codex', 'opencode', 'cursor', 'antigravity'], default: 'claude' },
+            mode: { enum: ['plan', 'edits', 'auto'], default: 'edits' },
+            model: { type: 'string' },
+            effort: { type: 'string', description: 'Thinking level: low, medium, high, xhigh, max (per harness)' },
+            attachments: { type: 'array', items: { type: 'string' }, description: 'Upload ids' },
+          },
+        },
+        Summary: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+            title: { type: 'string' },
+            agent: { type: 'string' },
+            cwd: { type: 'string' },
+            project: { type: 'string' },
+            projectId: { type: ['string', 'null'] },
+            mode: { type: 'string' },
+            model: { type: 'string' },
+            effort: { type: 'string' },
+            state: { enum: ['running', 'waiting', 'review', 'done'] },
+            status: { enum: ['running', 'done', 'partial', 'blocked', 'info'] },
+            preview: { type: 'string', description: 'The hero summary of the latest turn' },
+            live: { type: 'string', description: 'One-line status while running, or the pending question' },
+            asks: { type: 'boolean' },
+            question: { type: 'string' },
+            unread: { type: 'boolean' },
+            archived: { type: 'boolean' },
+            queued: { type: 'integer' },
+            turnCount: { type: 'integer' },
+            createdAt: { type: 'integer' },
+            updatedAt: { type: 'integer' },
+          },
+        },
+        Presentation: {
+          type: 'object',
+          properties: {
+            sessionId: { type: 'string' },
+            turnId: { type: 'string' },
+            turnIndex: { type: 'integer' },
+            state: { type: 'string' },
+            status: { enum: ['running', 'done', 'error', 'stopped'] },
+            prompt: { type: 'string' },
+            blocks: { type: 'array', items: { type: 'object', required: ['type'], properties: { type: { type: 'string' } } } },
+            markdown: { type: 'string' },
+            ask: { type: ['object', 'null'], properties: { id: { type: 'string' }, question: { type: 'string' }, context: { type: 'string' }, options: { type: 'array', items: { type: 'string' } } } },
+            changes: { type: 'array', items: { type: 'object', properties: { file: { type: 'string' }, op: { type: 'string' }, edits: { type: 'integer' } } } },
+            stats: { type: ['object', 'null'] },
+          },
+        },
+      },
+    },
+  };
+}

package/server/render.js

@@ -0,0 +1,100 @@
+// Presentation → plain markdown, for places that can't run the web UI: the CLI, MCP clients,
+// webhooks, chat apps. Lossy by design (no animation, no syntax colours), never throws.
+
+import { diffLines, hunks } from '../web/js/diff.js';
+
+const STATUS = { done: '✅ Done', partial: '🟡 Partly done', blocked: '⛔ Blocked', info: 'ℹ️ Report' };
+const CHANGE = { added: 'A', modified: 'M', deleted: 'D', renamed: 'R' };
+const fence = (text, lang = '') => {
+  const s = String(text ?? '');
+  const ticks = '`'.repeat(Math.max(3, ...[...s.matchAll(/`+/g)].map((m) => m[0].length + 1)));
+  return `${ticks}${lang}\n${s.replace(/\n$/, '')}\n${ticks}`;
+};
+const list = (v) => (Array.isArray(v) ? v : []);
+const str = (v) => (v === undefined || v === null ? '' : String(v));
+
+function findChange(turn, file) {
+  if (!file || !turn?.changes) return null;
+  return turn.changes.find((c) => c.file === file) || turn.changes.find((c) => c.file.endsWith('/' + file) || file.endsWith('/' + c.file));
+}
+
+function unified(edits) {
+  return edits
+    .map((e) =>
+      hunks(diffLines(str(e.before), str(e.after)), 3)
+        .map((o) => (o.op === '…' ? `@@ ${o.count} unchanged line${o.count > 1 ? 's' : ''} @@` : `${o.op}${o.text}`))
+        .join('\n'),
+    )
+    .join('\n@@ … @@\n');
+}
+
+const R = {
+  hero: (b) => `## ${str(b.title) || 'Done'}\n\n**${STATUS[b.status] || STATUS.done}**${b.summary ? ` — ${b.summary}` : ''}`,
+  markdown: (b) => str(b.text),
+  steps: (b) =>
+    `${b.title ? `**${b.title}**\n\n` : ''}${list(b.items)
+      .map((s, i) => `${i + 1}. ${s.status === 'failed' ? '❌' : s.status === 'skipped' ? '⏭️' : '✔︎'} **${str(s.title)}**${s.detail ? ` — ${s.detail}` : ''}`)
+      .join('\n')}`,
+  stats: (b) => list(b.items).map((s) => `- **${str(s.label)}:** ${str(s.value)}${str(s.unit)}${s.delta ? ` (${s.delta})` : ''}`).join('\n'),
+  files: (b) => list(b.items).map((f) => `- \`${CHANGE[f.change] || 'M'}\` \`${str(f.path)}\`${f.note ? ` — ${f.note}` : ''}`).join('\n'),
+  tree: (b) => `${b.title ? `**${b.title}**\n\n` : ''}${list(b.items).map((f) => `- \`${str(f.path)}\`${f.change ? ` (${f.change})` : ''}${f.note ? ` — ${f.note}` : ''}`).join('\n')}`,
+  diff: (b, turn) => {
+    const file = str(b.file || b.path);
+    const edits = b.before !== undefined || b.after !== undefined ? [{ before: b.before, after: b.after }] : findChange(turn, file)?.edits;
+    const head = `**\`${file}\`**${b.caption ? ` — ${b.caption}` : ''}`;
+    return edits?.length ? `${head}\n\n${fence(unified(edits), 'diff')}` : `${head} _(no captured edits)_`;
+  },
+  code: (b) => `${b.file ? `**\`${b.file}${b.line ? `:${b.line}` : ''}\`**${b.caption ? ` — ${b.caption}` : ''}\n\n` : b.caption ? `${b.caption}\n\n` : ''}${fence(b.code, str(b.language))}`,
+  tests: (b) => {
+    const n = (k) => Number(b[k]) || 0;
+    const head = `**Tests** \`${str(b.command)}\` — ${n('passed')} passed, ${n('failed')} failed${n('skipped') ? `, ${n('skipped')} skipped` : ''}${b.durationMs ? ` (${(n('durationMs') / 1000).toFixed(1)}s)` : ''}`;
+    const fails = list(b.failures).map((f) => `- ❌ ${str(f.name)}${f.message ? `: ${f.message}` : ''}${f.file ? ` (\`${f.file}\`)` : ''}`);
+    return [head, ...fails].join('\n');
+  },
+  commits: (b) =>
+    `${b.branch ? `**Branch** \`${b.branch}\`\n\n` : ''}${list(b.items)
+      .map((c) => `- \`${str(c.hash).slice(0, 7)}\` ${str(c.message)}${c.additions !== undefined ? ` (+${c.additions}/−${c.deletions ?? 0})` : ''}`)
+      .join('\n')}`,
+  terminal: (b) => fence(`$ ${str(b.command)}\n${str(b.output)}${b.exitCode !== undefined && b.exitCode !== 0 ? `\n[exit ${b.exitCode}]` : ''}`, 'console'),
+  compare: (b) => ['before', 'after'].map((k) => `**${str(b[k]?.label) || (k === 'before' ? 'Before' : 'After')}**\n${list(b[k]?.items).map((i) => `- ${str(i)}`).join('\n')}`).join('\n\n'),
+  flow: (b) => {
+    const nodes = list(b.nodes);
+    const label = (id) => nodes.find((n) => n.id === id)?.label || id;
+    const edges = list(b.edges).length ? list(b.edges) : nodes.slice(1).map((n, i) => [nodes[i].id, n.id]);
+    return `${b.title ? `**${b.title}**\n\n` : ''}${edges.map(([a, z, l]) => `- ${label(a)} → ${label(z)}${l ? ` _(${l})_` : ''}`).join('\n')}`;
+  },
+  chart: (b) => `${b.title ? `**${b.title}**\n\n` : ''}${list(b.items).map((i) => `- ${str(i.label)}: ${str(i.value)}${str(b.unit)}`).join('\n')}`,
+  checklist: (b) => `${b.title ? `**${b.title}**\n\n` : ''}${list(b.items).map((i) => `- [${i.done ? 'x' : ' '}] ${str(i.text)}`).join('\n')}`,
+  callout: (b) => `> **${b.tone === 'danger' ? '⛔' : b.tone === 'warn' ? '⚠️' : b.tone === 'success' ? '✅' : 'ℹ️'} ${str(b.title)}**\n> ${str(b.text).replace(/\n/g, '\n> ')}`,
+  image: (b) => `🖼️ \`${str(b.path || b.src)}\`${b.caption ? ` — ${b.caption}` : ''}`,
+  question: (b) => `**❓ ${str(b.question)}**\n${list(b.options).map((o, i) => `${i + 1}. ${str(o.label || o)}`).join('\n')}`,
+  next: (b) => `**Next**\n${list(b.items).map((i) => `- ${str(i)}`).join('\n')}`,
+};
+
+// blocks: presentation blocks; turn (optional) supplies captured edits for diff blocks.
+export function blocksToMarkdown(blocks = [], turn = null) {
+  return list(blocks)
+    .map((b) => {
+      try {
+        return R[b?.type] ? R[b.type](b, turn) : fence(JSON.stringify(b, null, 2), 'json');
+      } catch {
+        return '';
+      }
+    })
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+// A whole session's latest state as markdown: the newest turn's presentation, plus a pending
+// ask_user question if the agent is blocked on one.
+export function sessionToMarkdown(session) {
+  const turn = session.turns?.at(-1);
+  const out = [];
+  if (turn?.status === 'running') out.push(`_Working… (${turn.activity?.findLast?.((a) => a.kind !== 'text')?.label || 'starting up'})_`);
+  else if (turn?.presentation) out.push(blocksToMarkdown(turn.presentation.blocks, turn));
+  if (session.ask) {
+    out.push(`**❓ The agent is waiting for your answer:** ${session.ask.question}${session.ask.context ? `\n\n${session.ask.context}` : ''}`);
+    if (session.ask.options?.length) out.push(session.ask.options.map((o, i) => `${i + 1}. ${o}`).join('\n'));
+  }
+  return out.join('\n\n');
+}

package/server/runner.js

@@ -220,6 +220,7 @@ export class Runner extends EventEmitter {
     session.unread = false;
     delete session.archived;
     this.#touch(session, { turn: turn.id });
+    this.emit('started', { session, turn });
 
     let released = false;
     let linger;
@@ -341,6 +342,7 @@ export class Runner extends EventEmitter {
     session.unread = !interrupted;
     this.store.save(session, { now: true });
     this.#touch(session, { turn: turn.id });
+    this.emit('ended', { session, turn, interrupted, errorText: ev.isError && !ev.stopped ? ev.text : '' });
     // The follow-up starts right away; don't notify for the run it replaced.
     if (!interrupted) this.emit('finished', { session: summarize(session, this.store) });
   }

package/server/telemetry.js

@@ -0,0 +1,132 @@
+// Anonymous usage analytics + error reports, sent to PostHog over its plain HTTP API (no SDK, to
+// stay dependency-free). What goes out is fixed values only — agent, model, mode, status, timings,
+// counts — never prompts, paths, project names or agent output. Error messages and stacks are
+// scrubbed of the home directory and truncated.
+//
+// Off when any of: no API key, DO_NOT_TRACK=1, WISP_TELEMETRY=0, CI, or "telemetry": "off" in
+// settings. See the Telemetry section of the README.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+// PostHog project API key: write-only, safe to ship in the client.
+const KEY = process.env.WISP_POSTHOG_KEY ?? 'phc_wowwZkbP8e4zYuwT67JtX6oxdPwkMWL5kKnrUmYYXhcD';
+const HOST = (process.env.WISP_POSTHOG_HOST || 'https://us.i.posthog.com').replace(/\/$/, '');
+const FLUSH_MS = 15_000;
+const MAX_QUEUE = 50;
+const TIMEOUT_MS = 3000;
+
+const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const truthy = (v) => !!v && !/^(0|false|no|off)$/i.test(v);
+
+export function envDisabled(env = process.env) {
+  return !KEY || truthy(env.DO_NOT_TRACK) || /^(0|false|no|off)$/i.test(env.WISP_TELEMETRY || '') || truthy(env.CI);
+}
+
+const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+// Paths in messages and stacks would leak usernames and project names: wisp's own files keep
+// their package-relative path, anything else is cut down to its file name.
+export function scrub(text = '', { home = os.homedir(), root = ROOT } = {}) {
+  let s = String(text).split(root).join('<wisp>');
+  if (home) s = s.split(home).join('~');
+  // Any other absolute path keeps only its file name.
+  return s
+    .replace(/(?<![\w<>~.:/\\-])(?:~|[A-Za-z]:)?[/\\](?:[^\s'"`():/\\]+[/\\])+([^\s'"`():/\\]*)/g, (m, base) => `…/${base}`)
+    .slice(0, 500);
+}
+
+function frames(stack = '') {
+  return String(stack)
+    .split('\n')
+    .slice(1, 30)
+    .map((l) => l.trim().match(/^at (?:(.+?) \()?(.+?):(\d+):(\d+)\)?$/))
+    .filter(Boolean)
+    .map(([, fn, file, line, col]) => ({ platform: 'custom', lang: 'javascript', function: fn || '?', filename: scrub(file.replace(/^file:\/\//, '')), lineno: +line, colno: +col, in_app: file.includes(ROOT) && !file.includes('node_modules') }))
+    .reverse(); // PostHog wants the innermost frame last
+}
+
+export class Telemetry {
+  constructor(store, { shell = process.versions.electron ? 'electron' : 'browser' } = {}) {
+    this.store = store;
+    this.queue = [];
+    this.pendingFile = path.join(store.home, 'telemetry-pending.json');
+    this.common = {
+      $lib: 'wisp',
+      $process_person_profile: false, // anonymous events: no person profiles
+      version: VERSION,
+      os: process.platform,
+      osRelease: os.release(),
+      arch: process.arch,
+      node: process.versions.node,
+      electron: process.versions.electron || undefined,
+      shell,
+    };
+    this.timer = setInterval(() => this.flush(), FLUSH_MS);
+    this.timer.unref();
+    this.#sendPending();
+  }
+
+  get enabled() {
+    return !envDisabled() && this.store.config.defaults.telemetry !== 'off';
+  }
+
+  track(event, props = {}) {
+    if (!this.enabled) return;
+    if (!this.store.config.telemetryId) {
+      this.store.config.telemetryId = randomUUID(); // random per install, not tied to the machine or user
+      this.store.saveConfig();
+    }
+    this.queue.push({ event, timestamp: new Date().toISOString(), properties: { ...this.common, ...props, distinct_id: this.store.config.telemetryId } });
+    if (this.queue.length >= MAX_QUEUE) this.flush();
+  }
+
+  // PostHog error tracking format.
+  captureError(err, props = {}) {
+    const e = err instanceof Error ? err : new Error(String(err));
+    this.track('$exception', {
+      ...props,
+      $exception_list: [{ type: props.type || e.name || 'Error', value: scrub(e.message), mechanism: { handled: props.handled ?? true, synthetic: false }, stacktrace: { type: 'raw', frames: frames(e.stack) } }],
+    });
+  }
+
+  async flush() {
+    if (!this.queue.length) return;
+    const batch = this.queue.splice(0);
+    try {
+      await fetch(`${HOST}/batch/`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ api_key: KEY, batch }),
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+      });
+    } catch {} // offline or blocked: drop it, telemetry must never get in the way
+  }
+
+  // Shutdown and crashes leave no time for a request: write what's queued to disk (sync) and
+  // send it on the next start.
+  persist() {
+    clearInterval(this.timer);
+    if (!this.queue.length) return;
+    try {
+      fs.writeFileSync(this.pendingFile, JSON.stringify(this.queue.splice(0)));
+    } catch {}
+  }
+
+  crashed(err) {
+    if (!this.enabled) return;
+    this.captureError(err, { handled: false, type: err?.name || 'UncaughtException' });
+    this.persist();
+  }
+
+  #sendPending() {
+    try {
+      const pending = JSON.parse(fs.readFileSync(this.pendingFile, 'utf8'));
+      fs.rmSync(this.pendingFile, { force: true });
+      if (this.enabled && Array.isArray(pending)) this.queue.push(...pending.slice(-200));
+    } catch {}
+  }
+}

package/skills/wisp/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: wisp
+description: Delegate coding tasks to background agents (Claude Code, Codex, opencode, Cursor, Antigravity) through wisp, then read back their presentation (summary, diffs, tests). Use when the user asks to "send this to wisp", run something in the background or in parallel, fan a task out to other agents, or check on / follow up a wisp session.
+---
+
+# wisp: hand tasks to background agents
+
+wisp runs coding agents in the background and queues their results for the user. Each task
+becomes a **session**; when the agent finishes it leaves a presentation (hero summary, diffs, test
+runs, next steps) and the session waits in the user's queue. The user sees every session in the
+wisp app, so anything you launch is visible to them.
+
+Prefer the MCP tools if they are available (`wisp_launch`, `wisp_wait`, `wisp_get`, `wisp_reply`,
+`wisp_list`, `wisp_stop`, `wisp_agents`). Otherwise use the `wisp` CLI below (`npx -y wisp-agents`
+works in place of `wisp` if it isn't installed). Every command takes `--json`.
+
+## Launch
+
+```sh
+wisp "fix the flaky auth test in test/auth.test.ts; run npm test to verify" --json
+wisp "audit dependencies for known CVEs" --mode plan --agent codex --json
+wisp "add pagination to /api/users" --cwd ~/code/api --wait     # block until done, print the result
+```
+
+Options: `--agent claude|codex|opencode|cursor|antigravity`, `--mode plan|edits|auto`, `--model ID`,
+`--effort low|medium|high`, `--cwd DIR` (default: current folder), `--wait`, `--json`.
+`--json` prints the session summary; its `id` is what every other command takes.
+
+Write the prompt as a self-contained brief: the agent cannot see your conversation. Include the
+goal, relevant files, constraints, and how to verify (which test command to run).
+
+## Follow the session
+
+```sh
+wisp wait <id>            # block until it finishes or asks a question; prints the presentation
+wisp show <id>            # current state + latest presentation as markdown
+wisp ls --state running,waiting
+wisp reply <id> "also cover the empty-list case"   # follow-up; answers a pending question too
+wisp stop <id>
+```
+
+`state` is one of `running`, `waiting` (blocked on a question to the user), `review` (finished,
+unread by the user) or `done`.
+
+## Rules
+
+- **Don't answer questions meant for the user.** When a session is `waiting`, relay the question
+  to the user unless they already told you the answer. Only then `wisp reply`.
+- **Mode is a permission level.** Default to what the user picked in wisp (omit `--mode`). Use
+  `--mode plan` for read-only investigations. Only use `--mode auto` if the user asked for it.
+- **Parallel work goes in separate folders or worktrees.** Two agents editing the same checkout
+  will step on each other; launch the second in a `git worktree` if both write.
+- **Report the result, not the transcript.** Summarize the hero line, files changed and test
+  outcome from `wisp show`; point the user at the session in wisp for the full presentation.
+- `wisp wait` can take minutes. If you have other work, launch first, do it, then wait.