wisp-agents 0.5.0 → 0.7.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,204 @@
+// 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')) } } },
+      '/update': {
+        get: { summary: 'Current and latest published version, and how this copy updates (global | npx | git). ?check forces a registry check', responses: { 200: json({ type: 'object' }) } },
+        post: { summary: 'Install the latest version and relaunch. 409 while agents run unless { force: true }', responses: { 202: json({ type: 'object' }), 409: json({ type: 'object' }) } },
+      },
+      '/preferences': {
+        get: { summary: 'What wisp learned: { enabled, global: { preferences, lessons }, projects: [{ path, name, preferences, lessons }], history }', responses: { 200: json({ type: 'object' }) } },
+        put: {
+          summary: 'Replace one learned list',
+          requestBody: body({
+            type: 'object',
+            required: ['scope', 'kind', 'items'],
+            properties: {
+              scope: { type: 'string', description: '"global" or an absolute project path' },
+              kind: { type: 'string', enum: ['preferences', 'lessons'] },
+              items: { type: 'array', items: { type: 'string' }, description: 'Deduped and capped at 10 items of 180 characters' },
+            },
+          }),
+          responses: { 200: json({ type: 'object' }), 400: err[400] },
+        },
+      },
+      '/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, preferences, 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'] },
+          },
+        },
+      },
+    },
+  };
+}