wisp-agents 0.2.2 → 0.4.0

package/server/proc.js

@@ -0,0 +1,127 @@
+// Cross-platform process launching. On macOS/Linux this is a thin wrapper over spawn(). On
+// Windows, CLIs installed through npm (claude, codex, opencode…) are `.cmd` shims, which
+// spawn() can't start without a shell. Wrapping them in cmd.exe would mangle arguments wisp
+// passes (JSON, newlines in the system prompt), so npm shims are unwrapped into
+// `node <script>` and only unknown batch files go through cmd.exe, with careful escaping.
+
+import { spawn as nodeSpawn, execFile as nodeExecFile, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Find `bin` on PATH the way cmd.exe would (PATHEXT). Returns an absolute path or null.
+// A copied env object loses Windows' case-insensitive keys, so PATH may be spelled "Path".
+export function whichWindows(bin, env = process.env) {
+  const p = path.win32;
+  const exts = (env.PATHEXT || env.Pathext || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean).map((e) => e.toLowerCase());
+  // .ps1 isn't in PATHEXT, but some installers (Cursor) only drop a PowerShell script.
+  const names = p.extname(bin) ? [bin] : [...exts.map((e) => bin + e), bin + '.ps1'];
+  const dirs = /[\\/]/.test(bin) ? [''] : (env.PATH ?? env.Path ?? '').split(';').filter(Boolean);
+  for (const dir of dirs) {
+    for (const name of names) {
+      const full = dir ? p.join(dir, name) : name;
+      try {
+        if (fs.statSync(full).isFile()) return full;
+      } catch {}
+    }
+  }
+  return null;
+}
+
+// npm/pnpm/yarn `.cmd` shims end by running node on a script, or by running the target directly:
+//   ... & "%_prog%"  "%dp0%\node_modules\@openai\codex\bin\codex.js" %*
+//   "%~dp0\node.exe"  "%~dp0\..\opencode-ai\bin\opencode" %*
+//   "%dp0%\node_modules\some-cli\bin\tool.exe"   %*
+// Returns { script } or { exe }, relative to the shim's folder, or null if it isn't recognisable.
+export function parseCmdShim(text) {
+  const line = String(text).split(/\r?\n/).map((l) => l.trim()).findLast((l) => /%\*$/.test(l));
+  if (!line) return null;
+  const quoted = [...line.matchAll(/"([^"]+)"/g)].map((m) => m[1]);
+  const fromDp0 = (s) => s?.match(/^%~?dp0%?\\?(.+)$/i)?.[1] ?? null;
+  const target = fromDp0(quoted.at(-1));
+  if (!target) return null;
+  const prog = quoted.length > 1 ? quoted.at(-2) : '';
+  if (/^%_prog%$|(^|\\)node(\.exe)?$/i.test(prog) || /\.[cm]?js$/i.test(target)) return { script: target };
+  if (/\.(exe|com)$/i.test(target)) return { exe: target };
+  return null;
+}
+
+// cmd.exe escaping, as in cross-spawn: quote for CommandLineToArgvW, then caret-escape cmd's
+// metacharacters (twice when the target is itself a batch file, which re-parses its line).
+const META = /([()\][%!^"`<>&|;, *?])/g;
+export const escapeCmdCommand = (s) => String(s).replace(META, '^$1');
+export function escapeCmdArgument(arg, doubleEscape = false) {
+  let s = String(arg);
+  s = s.replace(/(?=(\\+?)?)\1"/g, '$1$1\\"');
+  s = s.replace(/(?=(\\+?)?)\1$/, '$1$1');
+  s = `"${s}"`.replace(META, '^$1');
+  return doubleEscape ? s.replace(META, '^$1') : s;
+}
+
+// Resolve `bin args` into something spawn() can run directly on this platform.
+// Returns { command, args, verbatim }; verbatim => pass windowsVerbatimArguments.
+export function resolveCommand(bin, args = [], { platform = process.platform, env = process.env } = {}) {
+  if (platform !== 'win32') return { command: bin, args, verbatim: false };
+  const file = whichWindows(bin, env);
+  if (!file) return { command: bin, args, verbatim: false }; // let spawn report ENOENT
+  const ext = path.win32.extname(file).toLowerCase();
+  if (ext === '.exe' || ext === '.com') return { command: file, args, verbatim: false };
+  if (ext === '.ps1') {
+    return { command: 'powershell.exe', args: ['-NoLogo', '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', file, ...args], verbatim: false };
+  }
+  if (ext === '.cmd' || ext === '.bat') {
+    let shim = null;
+    try {
+      shim = parseCmdShim(fs.readFileSync(file, 'utf8'));
+    } catch {}
+    const dir = path.win32.dirname(file);
+    if (shim?.exe) {
+      const exe = path.win32.resolve(dir, shim.exe);
+      if (fs.existsSync(exe)) return { command: exe, args, verbatim: false };
+    }
+    if (shim?.script) {
+      const script = path.win32.resolve(dir, shim.script);
+      if (fs.existsSync(script)) {
+        const localNode = path.win32.join(dir, 'node.exe');
+        return { command: fs.existsSync(localNode) ? localNode : whichWindows('node', env) || 'node', args: [script, ...args], verbatim: false };
+      }
+    }
+    // Unknown batch file: go through cmd.exe. Newlines can't survive cmd's parser.
+    const line = [escapeCmdCommand(file), ...args.map((a) => escapeCmdArgument(String(a).replace(/\r?\n/g, ' '), true))].join(' ');
+    return { command: env.ComSpec || env.COMSPEC || 'cmd.exe', args: ['/d', '/s', '/c', `"${line}"`], verbatim: true };
+  }
+  return { command: file, args, verbatim: false };
+}
+
+export function spawn(bin, args, opts = {}) {
+  const r = resolveCommand(bin, args, { env: opts.env || process.env });
+  return nodeSpawn(r.command, r.args, { ...opts, windowsHide: true, windowsVerbatimArguments: r.verbatim });
+}
+
+export function execFile(bin, args, opts, cb) {
+  const r = resolveCommand(bin, args, { env: opts?.env || process.env });
+  return nodeExecFile(r.command, r.args, { ...opts, windowsHide: true, windowsVerbatimArguments: r.verbatim }, cb);
+}
+
+// Stop a child and everything it started. On Windows, kill() only ends the direct child
+// (e.g. node, leaving the agent's own subprocesses running), so use taskkill /T.
+export function killTree(child) {
+  if (!child || child.exitCode !== null || child.signalCode !== null) return;
+  if (process.platform === 'win32' && child.pid) {
+    const r = spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+    if (r.status === 0) return;
+  }
+  child.kill('SIGTERM');
+}
+
+// Is `bin` runnable from PATH?
+export function onPath(bin, env = process.env) {
+  if (process.platform === 'win32') return !!whichWindows(bin, env);
+  return (env.PATH || '').split(path.delimiter).some((d) => {
+    try {
+      fs.accessSync(path.join(d, bin), fs.constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}

package/server/protocol.js

@@ -2,7 +2,7 @@
 // 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 = `
+const PROTOCOL = `
 # 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
@@ -10,9 +10,7 @@ read your transcript, tool calls or intermediate messages. The only thing they w
 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.
+{{ASK}}
 - 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.
@@ -76,6 +74,17 @@ Strings must be valid JSON (escape newlines as \\n and quotes as \\"). Example:
 \`\`\`
 `.trim();
 
+const ASK_TOOL = (tool) => `- 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 (${tool}). It pauses you until
+  the user answers in wisp — you keep all your context. Ask one crisp question with 2–4 options.`;
+const ASK_BLOCK = `- If a decision would change the rest of the work (ambiguous requirement, destructive or risky step,
+  two very different approaches), stop before acting on it and end with a "question" block (2–4 options).
+  The user's answer comes back as a follow-up in this same session.`;
+
+// askTool: how the harness names wisp's injected ask_user tool, or null if it can't take one.
+export const systemPrompt = ({ askTool = 'mcp__wisp__ask_user' } = {}) => PROTOCOL.replace('{{ASK}}', askTool ? ASK_TOOL(askTool) : ASK_BLOCK);
+export const SYSTEM_PROMPT = systemPrompt();
+
 // Only the opener is matched by regex. The closing fence can't be: the JSON itself often
 // contains ``` (a markdown block with a code sample), and a lazy match would cut it there.
 const OPEN = /```wisp[^\n]*\n/g;

package/server/runner.js

@@ -1,14 +1,17 @@
 // Session orchestration: launches turns on adapters, folds their events into the
-// session record, and queues follow-ups that arrive while the agent is busy.
+// session record, and handles follow-ups that arrive while the agent is busy: by default
+// they interrupt the run and resume the session with the new message; with the `queue`
+// setting they wait until the run finishes.
 
 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';
+import { systemPrompt, parsePresentation, heroOf } from './protocol.js';
 
 const MAX_ACTIVITY = 400;
+const LINGER_MS = 3000; // how long a CLI may keep running after it reported its result
 const ASK_SERVER = path.join(path.dirname(fileURLToPath(import.meta.url)), 'mcp-ask.js');
 
 export const newId = () => randomUUID().replace(/-/g, '').slice(0, 12);
@@ -33,8 +36,10 @@ export function summarize(s, store) {
     color: project?.color || 'slate',
     mode: s.mode,
     model: s.model,
+    effort: s.effort || '',
     state: s.state,
     unread: s.unread,
+    archived: !!s.archived,
     createdAt: s.createdAt,
     updatedAt: s.updatedAt,
     turnCount: s.turns.length,
@@ -55,6 +60,7 @@ export class Runner extends EventEmitter {
     this.bridge = bridge;
     this.live = new Map(); // sessionId -> adapter handle
     this.stopping = new Set();
+    this.interrupting = 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.
@@ -69,7 +75,7 @@ export class Runner extends EventEmitter {
     }
   }
 
-  create({ prompt, cwd, agent = 'claude', mode = 'edits', model = '', attachments = [] }) {
+  create({ prompt, cwd, agent = 'claude', mode = 'edits', model = '', effort = '', attachments = [] }) {
     if (!adapters[agent]) throw new Error(`Unknown agent: ${agent}`);
     const now = Date.now();
     const session = {
@@ -80,6 +86,7 @@ export class Runner extends EventEmitter {
       cwd,
       mode,
       model,
+      effort,
       state: 'running',
       unread: false,
       createdAt: now,
@@ -94,20 +101,46 @@ export class Runner extends EventEmitter {
     return session;
   }
 
-  reply(session, text, attachments = []) {
+  reply(session, text, attachments = [], { queue = false } = {}) {
     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 };
+    const handle = this.live.get(session.id);
+    if (handle) {
+      const turn = session.turns.at(-1);
+      // The run already produced its result and the CLI is only lingering on its way out:
+      // there's nothing to wait for, so let it go and start the follow-up now.
+      if (turn?.status !== 'running') {
+        session.queue.push({ id: newId(), text, attachments });
+        handle.release();
+        return { queued: session.queue.length > 0 };
+      }
+      // Interrupting needs an agent session to resume; before the agent reports one, queue.
+      if (queue || !session.agentSessionId) {
+        session.queue.push({ id: newId(), text, attachments });
+        this.#touch(session);
+        return { queued: true, ahead: session.queue.length - 1 };
+      }
+      // Ahead of anything queued, but after earlier interrupting follow-ups, so they keep their order.
+      const at = session.queue.findIndex((q) => !q.now);
+      session.queue.splice(at < 0 ? session.queue.length : at, 0, { id: newId(), text, attachments, now: true });
+      this.#interrupt(session);
+      return { interrupted: true };
     }
     this.#startTurn(session, text, attachments);
     return { queued: false };
   }
 
+  // Drop a follow-up that hasn't gone out yet.
+  unqueue(session, itemId) {
+    const at = session.queue.findIndex((q) => q.id === itemId);
+    if (at < 0) return false;
+    session.queue.splice(at, 1);
+    this.#touch(session);
+    return true;
+  }
+
   // 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);
@@ -120,6 +153,7 @@ export class Runner extends EventEmitter {
     };
     session.state = 'waiting';
     session.unread = true;
+    delete session.archived; // a question needs the user, so it comes back to the feed
     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) });
@@ -157,10 +191,21 @@ export class Runner extends EventEmitter {
     this.live.get(session.id).stop();
   }
 
+  // Stop the current run but keep the queue: done.finally() starts the next follow-up.
+  #interrupt(session) {
+    if (this.interrupting.has(session.id)) return; // already on its way down
+    this.interrupting.add(session.id);
+    this.stopping.add(session.id);
+    this.live.get(session.id).stop();
+  }
+
   #startTurn(session, prompt, attachments = []) {
     const turn = {
       id: newId(),
       prompt,
+      agent: session.agent,
+      model: session.model,
+      effort: session.effort || '',
       attachments: attachments.map(({ id, name, mime, size }) => ({ id, name, mime, size })),
       startedAt: Date.now(),
       endedAt: null,
@@ -173,8 +218,11 @@ export class Runner extends EventEmitter {
     session.turns.push(turn);
     session.state = 'running';
     session.unread = false;
+    delete session.archived;
     this.#touch(session, { turn: turn.id });
 
+    let released = false;
+    let linger;
     const adapter = adapters[session.agent];
     const handle = adapter.run({
       prompt,
@@ -183,8 +231,9 @@ export class Runner extends EventEmitter {
       resumeId: session.agentSessionId,
       mode: session.mode,
       model: session.model,
-      systemPrompt: SYSTEM_PROMPT,
-      mcpServers: this.bridge
+      effort: session.effort || '',
+      systemPrompt: systemPrompt({ askTool: adapter.askTool }),
+      mcpServers: this.bridge && adapter.askTool !== null
         ? {
             wisp: {
               command: process.execPath,
@@ -195,17 +244,32 @@ export class Runner extends EventEmitter {
             },
           }
         : {},
-      onEvent: (ev) => this.#onEvent(session, turn, ev),
+      onEvent: (ev) => {
+        if (released) return; // a lingering process we already let go of
+        this.#onEvent(session, turn, ev);
+        // A CLI can outlive its result (flushing, or a background process it spawned holding
+        // stdout open, so 'close' never fires). Don't hold the session hostage to that.
+        if (ev.type === 'result') linger = setTimeout(release, LINGER_MS);
+      },
     });
-    this.live.set(session.id, handle);
-
-    handle.done.finally(() => {
-      this.live.delete(session.id);
+    // Ends the run exactly once: on exit, LINGER_MS after the result, or when a follow-up arrives.
+    const release = () => {
+      if (released) return;
       if (turn.status === 'running') this.#finishTurn(session, turn, { isError: true, text: 'The agent exited without a result.' });
+      released = true;
+      clearTimeout(linger);
+      handle.stop();
+      if (this.live.get(session.id) !== handle) return;
+      this.live.delete(session.id);
+      this.interrupting.delete(session.id);
+      this.stopping.delete(session.id); // a stop that landed after the result has nothing left to stop
       const next = session.queue.shift();
       if (next && this.store.get(session.id)) this.#startTurn(session, next.text, next.attachments);
       else this.#touch(session);
-    });
+    };
+    handle.release = release;
+    this.live.set(session.id, handle);
+    handle.done.finally(release);
   }
 
   #onEvent(session, turn, ev) {
@@ -245,11 +309,14 @@ export class Runner extends EventEmitter {
     turn.stats = ev.stats || null;
     delete session.ask;
     if (this.stopping.delete(session.id)) ev = { ...ev, stopped: true };
+    const interrupted = ev.stopped && this.interrupting.has(session.id);
     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' },
+          interrupted
+            ? { type: 'hero', title: 'Interrupted', summary: 'You sent a follow-up while this was running, so it picked that up instead.', status: 'partial' }
+            : { 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' })) }] : []),
         ],
       };
@@ -266,14 +333,16 @@ export class Runner extends EventEmitter {
       turn.status = 'done';
       turn.raw = ev.text; // kept so the turn can be re-parsed if the parser improves
       turn.presentation = parsePresentation(ev.text);
+      this.store.keepImages(session, turn);
       const hero = heroOf(turn.presentation);
       if (hero?.title && session.titleAuto && session.turns.length === 1) session.title = hero.title;
     }
     session.state = 'review';
-    session.unread = true;
+    session.unread = !interrupted;
     this.store.save(session, { now: true });
     this.#touch(session, { turn: turn.id });
-    this.emit('finished', { session: summarize(session, this.store) });
+    // The follow-up starts right away; don't notify for the run it replaced.
+    if (!interrupted) this.emit('finished', { session: summarize(session, this.store) });
   }
 
   #touch(session, { turn, quiet } = {}) {

package/server/store.js

@@ -3,19 +3,24 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { randomUUID } from 'node:crypto';
 import { parsePresentation } from './protocol.js';
 
 const DEFAULT_CONFIG = {
   projects: [], // [{ id, name, path, color, addedAt }]
-  defaults: { agent: 'claude', mode: 'edits', model: '' },
+  defaults: { agent: 'claude', mode: 'edits', model: '', effort: '' },
 };
 
+const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg']);
+const MAX_KEPT_IMAGE = 25 * 1024 * 1024;
+
 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');
+    this.shots = path.join(home, 'shots');
     fs.mkdirSync(this.dir, { recursive: true });
     this.sessions = new Map();
     this.timers = new Map();
@@ -27,6 +32,10 @@ export class Store {
         const s = JSON.parse(fs.readFileSync(path.join(this.dir, f), 'utf8'));
         reparse(s);
         this.sessions.set(s.id, s);
+        // Backfill: follow-ups queued before items had ids can't be cancelled without one.
+        const ids = (s.queue || []).filter((q) => !q.id).map((q) => (q.id = randomUUID().replace(/-/g, '').slice(0, 12)));
+        // Backfill: keep screenshots from older turns while their files still exist.
+        if ((s.turns || []).map((t) => this.keepImages(s, t)).some(Boolean) || ids.length) this.save(s, { now: true });
       } catch (err) {
         console.warn(`wisp: skipping unreadable session ${f}: ${err.message}`);
       }
@@ -111,6 +120,34 @@ export class Store {
     clearTimeout(this.timers.get(id));
     this.sessions.delete(id);
     fs.rmSync(path.join(this.dir, `${id}.json`), { force: true });
+    fs.rmSync(path.join(this.shots, id), { recursive: true, force: true });
+  }
+
+  // Agents save screenshots to /tmp, which macOS clears. Copy every local image a turn shows
+  // into ~/.wisp/shots/<session>/ and point the block at the copy; `source` keeps the original.
+  keepImages(session, turn) {
+    let changed = false;
+    (turn.presentation?.blocks || []).forEach((b, i) => {
+      const rel = b?.type === 'image' && (b.path || b.src);
+      if (typeof rel !== 'string' || !rel || /^https?:/.test(rel)) return;
+      const src = path.resolve(session.cwd || this.home, rel);
+      const ext = path.extname(src).toLowerCase();
+      if (!IMAGE_EXT.has(ext) || src.startsWith(this.shots + path.sep)) return;
+      try {
+        const st = fs.statSync(src);
+        if (!st.isFile() || st.size > MAX_KEPT_IMAGE) return;
+        const dir = path.join(this.shots, session.id);
+        fs.mkdirSync(dir, { recursive: true });
+        const dest = path.join(dir, `${turn.id}-${i}${ext}`);
+        fs.copyFileSync(src, dest);
+        Object.assign(b, { path: dest, source: rel });
+        delete b.src;
+        changed = true;
+      } catch {
+        // gone or unreadable: leave the block as it was
+      }
+    });
+    return changed;
   }
 
   flush() {