wisp-agents 0.1.0 → 0.2.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/wisp.js

@@ -1,22 +1,27 @@
 #!/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';
 
 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 +29,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 +52,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 +76,38 @@ 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
+    return typeof bin === 'string' && existsSync(bin) ? bin : null;
+  } 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/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.0",
   "description": "Launch coding agents, skip the transcript, read the presentation.",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   },
   "files": [
     "bin/",
+    "electron/",
     "server/",
     "web/"
   ],
@@ -17,7 +18,7 @@
     "app": "electron .",
     "dev": "WISP_DEV=1 electron .",
     "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 -e \"import('./server/index.js')\" && node --check electron/main.js"
   },
   "engines": {
     "node": ">=20"
@@ -42,7 +43,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;
+  }
+}