wisp-agents 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to `wisp-agents` are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-10-16
+
+### Added
+
+- Desktop app: native right-click menu with spelling suggestions, Copy Link, undo/redo, cut/copy/paste and select all. Inspect Element appears only in dev mode.
+
+### Fixed
+
+- macOS: the Dock shows "wisp" with the wisp icon instead of "Electron". The app now launches from a renamed clone of `Electron.app`, cached per Electron version under `~/Library/Caches/wisp`.
+
+## [0.2.0] - 2026-10-16
+
+### Added
+
+- `npx wisp-agents` opens the desktop app. Electron is now an optional dependency that is fetched on first launch. The CLI starts the app detached and falls back to the browser when Electron isn't available.
+- `--browser` flag to keep the browser-only behaviour.
+
+### Fixed
+
+- Parsing of the `wisp` fence is more robust: malformed blocks are salvaged instead of dropped, and the raw turn text is kept.
+
+## [0.1.0] - 2026-10-16
+
+### Added
+
+- First public release on npm as `wisp-agents`, with `wisp` and `wisp-agents` bins and a `--version` / `-v` flag.
+- Launch Claude Code agents in the background and read the presentation they hand back: diffs, tests, commits, flows and questions.
+- Session queue with follow-ups, answers to agent questions, terminal takeover and mark-as-done.
+- Older turns are folded, with a floating collapse-all button and back-to-top.
+
+[Unreleased]: https://github.com/M0xoo/wisp/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/M0xoo/wisp/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/M0xoo/wisp/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/M0xoo/wisp/releases/tag/v0.1.0

package/README.md

@@ -8,6 +8,7 @@
 
 Launch coding agents in the background, skip the transcript, and read the presentation they hand back when they finish.
 
+[![npm](https://img.shields.io/npm/v/wisp-agents?color=cb3837&logo=npm)](https://www.npmjs.com/package/wisp-agents)
 [![License: MIT](https://img.shields.io/badge/license-MIT-6a5cff.svg)](#license)
 [![Node](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org)
 [![Electron](https://img.shields.io/badge/desktop-Electron-47848f?logo=electron&logoColor=white)](https://www.electronjs.org)
@@ -51,9 +52,13 @@ From there you can **follow up**, **answer its questions**, **take it over** in
 > **Requirements:** Node.js ≥ 20 and [Claude Code](https://claude.com/claude-code) (`claude`) installed and signed in.
 
 ```sh
-npx wisp-agents            # → http://localhost:4477
+npx wisp-agents                          # open the wisp desktop app
+npx wisp-agents "fix the flaky auth test" # launch a task in the current folder
+npx wisp-agents --browser                # or use it in the browser → http://localhost:4477
 ```
 
+The first run downloads Electron for the desktop app; if that isn't possible, wisp opens in the browser instead.
+
 Or install it globally to get the `wisp` command everywhere:
 
 ```sh
@@ -99,7 +104,8 @@ wisp --mode plan "audit deps"     # permission mode: plan | edits | auto
 |---|---|
 | `--port`, `-p N` | Port to use (default `4477`, or `WISP_PORT`) |
 | `--mode`, `-m` | `plan` · `edits` · `auto` |
-| `--no-open` | Don't open a browser |
+| `--browser`, `-b` | Use the browser instead of the desktop app |
+| `--no-open` | Just run the server; open nothing |
 | `--version`, `-v` | Print the version |
 
 > `npm install -g wisp-agents` (or `npm link` from a clone) puts `wisp` on your `PATH`. Without installing, use `npx wisp-agents …` with the same arguments.

package/bin/mac-app.js

@@ -0,0 +1,64 @@
+// macOS names the Dock tile, menu bar and Cmd-Tab entry after the running .app bundle's
+// Info.plist, not app.setName(). So run Electron from a clone of Electron.app renamed to wisp
+// (APFS clone: instant, no extra disk), cached per Electron version.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REV = 1; // bump when the patching below changes
+const ICON = fileURLToPath(new URL('../electron/icon.png', import.meta.url));
+
+// electronBin: …/Electron.app/Contents/MacOS/Electron → the same binary inside wisp.app, or the
+// original path if anything goes wrong (worst case the Dock says "Electron" again).
+export function wispAppBinary(electronBin) {
+  try {
+    const src = path.resolve(electronBin, '../../..');
+    if (!src.endsWith('.app')) return electronBin;
+    const version = readFileSync(path.join(src, '../version'), 'utf8').trim();
+    const root = path.join(os.homedir(), 'Library/Caches/wisp');
+    const app = path.join(root, `electron-${version}-r${REV}`, 'wisp.app');
+    const bin = path.join(app, 'Contents/MacOS', path.basename(electronBin));
+    if (existsSync(bin)) return bin;
+
+    mkdirSync(root, { recursive: true });
+    const tmp = mkdtempSync(path.join(root, 'build-'));
+    const out = path.join(tmp, 'wisp.app');
+    try {
+      execFileSync('cp', ['-cR', src, out], { stdio: 'ignore' });
+    } catch {
+      execFileSync('cp', ['-R', src, out], { stdio: 'ignore' }); // not APFS
+    }
+    const plist = path.join(out, 'Contents/Info.plist');
+    const set = (key, value) => execFileSync('/usr/libexec/PlistBuddy', ['-c', `Set :${key} ${value}`, plist]);
+    set('CFBundleName', 'wisp');
+    set('CFBundleDisplayName', 'wisp');
+    set('CFBundleIdentifier', 'dev.wisp.app');
+    try {
+      makeIcns(path.join(out, 'Contents/Resources/wisp.icns'), tmp);
+      set('CFBundleIconFile', 'wisp.icns');
+    } catch {}
+
+    mkdirSync(path.dirname(app), { recursive: true });
+    rmSync(app, { recursive: true, force: true });
+    renameSync(out, app);
+    rmSync(tmp, { recursive: true, force: true });
+    return bin;
+  } catch {
+    return electronBin;
+  }
+}
+
+function makeIcns(dest, tmp) {
+  const set = path.join(tmp, 'wisp.iconset');
+  mkdirSync(set);
+  for (const s of [16, 32, 128, 256, 512]) {
+    for (const [scale, suffix] of [[1, ''], [2, '@2x']]) {
+      const px = String(s * scale);
+      execFileSync('sips', ['-z', px, px, ICON, '--out', path.join(set, `icon_${s}x${s}${suffix}.png`)], { stdio: 'ignore' });
+    }
+  }
+  execFileSync('iconutil', ['-c', 'icns', set, '-o', dest], { stdio: 'ignore' });
+}

package/bin/wisp.js

@@ -1,22 +1,28 @@
 #!/usr/bin/env node
 // wisp — launcher + queue for coding agents.
 //
-//   wisp                   start wisp (or focus the running one) and open the browser
+//   wisp                   open the wisp desktop app (or focus the running one)
 //   wisp "fix the tests"   launch a wisp in the current folder
 //   wisp add [path]        add a folder as a project (default: current folder)
 //   --port N               port (default 4477, or WISP_PORT)
 //   --mode plan|edits|auto permission mode for a launch
-//   --no-open              don't open a browser
+//   --browser              use the browser instead of the desktop app
+//   --no-open              just run the server, open nothing
 
-import { exec } from 'node:child_process';
+import { exec, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { wispAppBinary } from './mac-app.js';
 
 const argv = process.argv.slice(2);
-const flags = { open: true, port: Number(process.env.WISP_PORT) || 4477, mode: null };
+const flags = { open: true, browser: false, port: Number(process.env.WISP_PORT) || 4477, mode: null };
 const words = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
   if (a === '--no-open') flags.open = false;
+  else if (a === '--browser' || a === '-b') flags.browser = true;
   else if (a === '--port' || a === '-p') flags.port = Number(argv[++i]);
   else if (a === '--mode' || a === '-m') flags.mode = argv[++i];
   else if (a === '--version' || a === '-v') {
@@ -24,7 +30,7 @@ for (let i = 0; i < argv.length; i++) {
     console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url))).version);
     process.exit(0);
   } else if (a === '--help' || a === '-h') {
-    console.log('usage:\n  wisp                    open wisp\n  wisp "task"             launch a task in this folder\n  wisp add [path]         add a project\n\noptions: --port N  --mode plan|edits|auto  --no-open  --version');
+    console.log('usage:\n  wisp                    open wisp\n  wisp "task"             launch a task in this folder\n  wisp add [path]         add a project\n\noptions: --port N  --mode plan|edits|auto  --browser  --no-open  --version');
     process.exit(0);
   } else words.push(a);
 }
@@ -47,7 +53,20 @@ try {
   running = true;
 } catch {}
 
-if (!running) {
+// The desktop app (Electron is an optional dependency) runs the server in its own process, so
+// it outlives this terminal. Without Electron, or with --browser/--no-open, serve from here.
+// A task or `add` sent to an already-running wisp just goes over the API, no window.
+const electron = flags.open && !flags.browser && (!running || !words.length) ? electronBinary() : null;
+if (electron) {
+  const child = spawn(electron, [fileURLToPath(new URL('..', import.meta.url))], {
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env, WISP_PORT: String(flags.port) },
+  });
+  child.unref();
+  if (!running) await waitForServer();
+  console.log(`\n  ◌ wisp is open\n`);
+} else if (!running) {
   const { startServer } = await import('../server/index.js');
   await startServer({ port: flags.port });
   console.log(`\n  ◌ wisp is floating at ${base}\n`);
@@ -58,16 +77,39 @@ if (words[0] === 'add') {
   const dir = path.resolve(words[1] || process.cwd());
   const p = await api('/projects', { path: dir }).catch((e) => console.error(`  ✗ ${e.message}`));
   if (p) console.log(`  ✓ project added: ${p.name}  (${p.path})`);
-  if (running) process.exit(0);
+  if (running || electron) process.exit(0);
 } else if (words.length) {
   const cfg = await api('/config');
   const s = await api('/sessions', { prompt: words.join(' '), cwd: process.cwd(), agent: cfg.defaults.agent, mode: flags.mode || cfg.defaults.mode, model: cfg.defaults.model });
   console.log(`  ◌ launched: ${s.title}`);
   openPath = `/#/s/${s.id}`;
-  if (running) process.exit(0); // the running wisp will show it in the queue
+  if (running || electron) process.exit(0); // the running wisp will show it in the queue
 }
 
+if (electron) process.exit(0);
 if (flags.open) {
   const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start ""' : 'xdg-open';
   exec(`${cmd} "${base}${openPath}"`);
 }
+
+function electronBinary() {
+  try {
+    const bin = createRequire(import.meta.url)('electron'); // the electron package exports its binary path
+    if (typeof bin !== 'string' || !existsSync(bin)) return null;
+    return process.platform === 'darwin' ? wispAppBinary(bin) : bin;
+  } catch {
+    return null;
+  }
+}
+
+async function waitForServer() {
+  for (let i = 0; i < 150; i++) {
+    try {
+      return await api('/config');
+    } catch {
+      await new Promise((r) => setTimeout(r, 200));
+    }
+  }
+  console.error('  ✗ the wisp app did not start in time — try `wisp --browser`');
+  process.exit(1);
+}

package/electron/icon.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#1d1c22"/><stop offset="1" stop-color="#0e0e10"/></linearGradient>
+    <radialGradient id="glow" cx="50%" cy="50%" r="50%"><stop offset="0" stop-color="#6a5cff" stop-opacity=".55"/><stop offset="1" stop-color="#6a5cff" stop-opacity="0"/></radialGradient>
+    <radialGradient id="orb" cx="36%" cy="32%" r="68%"><stop offset="0" stop-color="#fff"/><stop offset=".16" stop-color="#d9fff6"/><stop offset=".38" stop-color="#2fd0b4"/><stop offset=".78" stop-color="#6a5cff"/><stop offset="1" stop-color="#4b3fe0"/></radialGradient>
+  </defs>
+  <rect x="100" y="100" width="824" height="824" rx="190" fill="url(#bg)"/>
+  <circle cx="512" cy="512" r="330" fill="url(#glow)"/>
+  <circle cx="512" cy="512" r="210" fill="url(#orb)"/>
+  <circle cx="742" cy="360" r="16" fill="#fff" opacity=".9"/>
+  <circle cx="300" cy="650" r="10" fill="#bff" opacity=".7"/>
+  <circle cx="690" cy="720" r="7" fill="#fff" opacity=".6"/>
+</svg>

package/electron/main.js

@@ -1,7 +1,7 @@
 // wisp desktop shell. The Node server runs inside Electron's main process and
 // the window loads the same UI the browser mode serves.
 
-import { app, BrowserWindow, shell, nativeTheme, Menu, dialog, ipcMain } from 'electron';
+import { app, BrowserWindow, shell, nativeTheme, Menu, dialog, ipcMain, clipboard } from 'electron';
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -76,6 +76,23 @@ function createWindow() {
     app.setBadgeCount(n);
   });
 
+  // Electron has no right-click menu by default: give text and links the usual one.
+  win.webContents.on('context-menu', (_, p) => {
+    const f = p.editFlags;
+    const items = [
+      ...p.dictionarySuggestions.map((w) => ({ label: w, click: () => win.webContents.replaceMisspelling(w) })),
+      ...(p.misspelledWord ? [{ type: 'separator' }] : []),
+      ...(p.linkURL ? [{ label: 'Copy Link', click: () => clipboard.writeText(p.linkURL) }, { type: 'separator' }] : []),
+      ...(p.isEditable ? [{ role: 'undo', enabled: f.canUndo }, { role: 'redo', enabled: f.canRedo }, { type: 'separator' }] : []),
+      ...(p.isEditable ? [{ role: 'cut', enabled: f.canCut }] : []),
+      ...(p.isEditable || p.selectionText ? [{ role: 'copy', enabled: f.canCopy }] : []),
+      ...(p.isEditable ? [{ role: 'paste', enabled: f.canPaste }, { role: 'pasteAndMatchStyle', enabled: f.canPaste }] : []),
+      { role: 'selectAll', enabled: f.canSelectAll },
+      ...(DEV ? [{ type: 'separator' }, { label: 'Inspect Element', click: () => win.webContents.inspectElement(p.x, p.y) }] : []),
+    ];
+    Menu.buildFromTemplate(items).popup({ window: win });
+  });
+
   win.on('closed', () => (win = null));
 }
 

package/electron/preload.cjs

@@ -0,0 +1,6 @@
+// Minimal bridge for desktop-only niceties. Sandboxed preloads must be CommonJS.
+const { contextBridge, ipcRenderer } = require('electron');
+
+contextBridge.exposeInMainWorld('wispDesktop', {
+  pickFolder: () => ipcRenderer.invoke('wisp:pick-folder'),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wisp-agents",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Launch coding agents, skip the transcript, read the presentation.",
   "type": "module",
   "bin": {
@@ -9,15 +9,17 @@
   },
   "files": [
     "bin/",
+    "CHANGELOG.md",
+    "electron/",
     "server/",
     "web/"
   ],
   "scripts": {
     "start": "node bin/wisp.js",
-    "app": "electron .",
-    "dev": "WISP_DEV=1 electron .",
+    "app": "node bin/wisp.js",
+    "dev": "WISP_DEV=1 node bin/wisp.js",
     "dev:web": "node --watch-path=server bin/wisp.js --no-open",
-    "prepublishOnly": "node --check bin/wisp.js && node -e \"import('./server/index.js')\""
+    "prepublishOnly": "node --check bin/wisp.js && node --check bin/mac-app.js && node -e \"import('./server/index.js')\" && node --check electron/main.js"
   },
   "engines": {
     "node": ">=20"
@@ -42,7 +44,7 @@
     "url": "https://github.com/M0xoo/wisp/issues"
   },
   "main": "electron/main.js",
-  "devDependencies": {
+  "optionalDependencies": {
     "electron": "^44.8.0"
   }
 }

package/server/protocol.js

@@ -76,26 +76,94 @@ Strings must be valid JSON (escape newlines as \\n and quotes as \\"). Example:
 \`\`\`
 `.trim();
 
-const FENCE = /```wisp[^\n]*\n([\s\S]*?)\n?```/g;
+// 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;
 
 export function parsePresentation(text = '') {
-  const matches = [...text.matchAll(FENCE)];
-  const last = matches.at(-1);
-  if (last) {
-    const json = tryJson(last[1]);
+  const opens = [...text.matchAll(OPEN)];
+  for (let i = opens.length - 1; i >= 0; i--) {
+    const open = opens[i];
+    const json = readJson(text.slice(open.index + open[0].length));
     const blocks = Array.isArray(json) ? json : json?.blocks;
     if (Array.isArray(blocks) && blocks.length) {
-      const extra = text.slice(0, last.index).trim();
+      const extra = text.slice(0, open.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.
+  // The agent ignored (or broke) the protocol — show its answer as plain markdown, with any
+  // broken wisp payload kept verbatim in a fence rather than half-rendered as prose.
+  const last = opens.at(-1);
+  let md = text.trim();
+  if (last) {
+    const prose = text.slice(0, last.index).trim();
+    const raw = text.slice(last.index + last[0].length).replace(/\n?```\s*$/, '');
+    md = `${prose}\n\n\`\`\`\`\`json\n${raw}\n\`\`\`\`\``.trim();
+  }
   return {
     fallback: true,
-    blocks: [{ type: 'markdown', text: text.replace(FENCE, '').trim() || '_The agent finished without a message._' }],
+    blocks: [{ type: 'markdown', text: md || '_The agent finished without a message._' }],
   };
 }
 
+// Parse the JSON value at the start of `src` (the body after a ```wisp opener). First find its
+// end by bracket matching, respecting strings; if that fails (e.g. a stray unescaped quote), try
+// every ``` after it as the closing fence.
+function readJson(src) {
+  const end = jsonEnd(src);
+  if (end > 0) {
+    const json = tryJson(src.slice(0, end));
+    if (json) return json;
+  }
+  for (let i = src.indexOf('```'); i !== -1; i = src.indexOf('```', i + 3)) {
+    const json = tryJson(src.slice(0, i));
+    if (json) return json;
+  }
+  return salvageBlocks(src);
+}
+
+// Last resort: parse the blocks array one element at a time, so a single malformed block (an
+// unescaped quote in a terminal output, say) costs that block rather than the whole answer.
+function salvageBlocks(src) {
+  const m = /^\s*(\{\s*"blocks"\s*:\s*)?\[/.exec(src);
+  if (!m) return null;
+  const blocks = [];
+  let bad = 0;
+  let i = m[0].length;
+  while (i < src.length) {
+    while (/[\s,]/.test(src[i] || '')) i++;
+    if (src[i] !== '{') break;
+    const len = jsonEnd(src.slice(i));
+    if (len < 0) break;
+    const block = tryJson(src.slice(i, i + len));
+    if (block && typeof block === 'object') blocks.push(block);
+    else bad++;
+    i += len;
+  }
+  if (!blocks.length) return null;
+  if (bad) blocks.push({ type: 'callout', tone: 'warn', title: `${bad} block${bad > 1 ? 's' : ''} skipped`, text: 'Part of the agent\'s answer was malformed JSON and could not be shown.' });
+  return blocks;
+}
+
+function jsonEnd(src) {
+  const start = src.search(/\S/);
+  if (src[start] !== '{' && src[start] !== '[') return -1;
+  let depth = 0;
+  let inStr = false;
+  for (let i = start; i < src.length; i++) {
+    const c = src[i];
+    if (inStr) {
+      if (c === '\\') i++;
+      else if (c === '"') inStr = false;
+    } else if (c === '"') inStr = true;
+    else if (c === '{' || c === '[') depth++;
+    else if (c === '}' || c === ']') {
+      if (--depth === 0) return i + 1;
+    }
+  }
+  return -1;
+}
+
 function tryJson(src) {
   try {
     return JSON.parse(src);

package/server/runner.js

@@ -262,6 +262,7 @@ export class Runner extends EventEmitter {
       };
     } else {
       turn.status = 'done';
+      turn.raw = ev.text; // kept so the turn can be re-parsed if the parser improves
       turn.presentation = parsePresentation(ev.text);
       const hero = heroOf(turn.presentation);
       if (hero?.title && session.titleAuto && session.turns.length === 1) session.title = hero.title;

package/server/store.js

@@ -3,6 +3,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { parsePresentation } from './protocol.js';
 
 const DEFAULT_CONFIG = {
   projects: [], // [{ id, name, path, color, addedAt }]
@@ -24,6 +25,7 @@ export class Store {
       if (!f.endsWith('.json')) continue;
       try {
         const s = JSON.parse(fs.readFileSync(path.join(this.dir, f), 'utf8'));
+        reparse(s);
         this.sessions.set(s.id, s);
       } catch (err) {
         console.warn(`wisp: skipping unreadable session ${f}: ${err.message}`);
@@ -118,3 +120,13 @@ export class Store {
     }
   }
 }
+
+// Turns that fell back to plain text are re-parsed from their raw answer on load, so parser
+// fixes repair old turns too.
+function reparse(session) {
+  for (const t of session.turns || []) {
+    if (!t.presentation?.fallback || typeof t.raw !== 'string') continue;
+    const p = parsePresentation(t.raw);
+    if (!p.fallback) t.presentation = p;
+  }
+}