wisp-agents 0.0.0-stage → 0.2.0

package/server/terminal.js

@@ -0,0 +1,73 @@
+// Open a command in the user's terminal so they can take over an agent session interactively.
+
+import { spawn, execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+
+export const TERMINALS = [
+  { id: 'auto', label: 'Auto-detect' },
+  { id: 'terminal', label: 'Terminal.app', mac: true },
+  { id: 'iterm', label: 'iTerm', mac: true, app: '/Applications/iTerm.app' },
+  { id: 'ghostty', label: 'Ghostty', app: '/Applications/Ghostty.app', bin: 'ghostty' },
+  { id: 'warp', label: 'Warp', mac: true, app: '/Applications/Warp.app' },
+  { id: 'kitty', label: 'kitty', app: '/Applications/kitty.app', bin: 'kitty' },
+  { id: 'wezterm', label: 'WezTerm', app: '/Applications/WezTerm.app', bin: 'wezterm' },
+  { id: 'custom', label: 'Custom command' },
+];
+
+export const shq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+
+const has = (bin) => {
+  try {
+    execFileSync('which', [bin], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+function detect() {
+  if (process.platform === 'darwin') {
+    if (process.env.TERM_PROGRAM === 'iTerm.app' && fs.existsSync('/Applications/iTerm.app')) return 'iterm';
+    if (process.env.TERM_PROGRAM === 'ghostty' && fs.existsSync('/Applications/Ghostty.app')) return 'ghostty';
+    return 'terminal';
+  }
+  for (const t of ['ghostty', 'kitty', 'wezterm']) if (has(t)) return t;
+  return 'x-terminal-emulator';
+}
+
+const osa = (script) => spawn('osascript', ['-e', script], { detached: true, stdio: 'ignore' }).unref();
+const asStr = (s) => `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+
+// argv: the agent's resume command, e.g. ['claude', '--resume', 'abc'].
+export function openInTerminal({ cwd, argv, terminal = 'auto', custom = '' }) {
+  const cmd = argv.map(shq).join(' ');
+  const line = `cd ${shq(cwd)} && ${cmd}`;
+  const t = terminal === 'auto' ? detect() : terminal;
+  const mac = process.platform === 'darwin';
+
+  switch (t) {
+    case 'terminal':
+      return osa(`tell application "Terminal"\nactivate\ndo script ${asStr(line)}\nend tell`);
+    case 'iterm':
+      return osa(`tell application "iTerm"\nactivate\nset w to (create window with default profile)\ntell current session of w to write text ${asStr(line)}\nend tell`);
+    case 'warp':
+      // Warp has no scripting API; open a tab in the folder and type via System Events.
+      spawn('open', ['-a', 'Warp', cwd], { detached: true, stdio: 'ignore' }).unref();
+      return setTimeout(() => osa(`tell application "System Events" to keystroke ${asStr(cmd)} & return`), 1200);
+    case 'ghostty':
+      if (mac) return spawn('open', ['-na', 'Ghostty', '--args', `--working-directory=${cwd}`, '-e', ...argv], { detached: true, stdio: 'ignore' }).unref();
+      return spawn('ghostty', [`--working-directory=${cwd}`, '-e', ...argv], { detached: true, stdio: 'ignore' }).unref();
+    case 'kitty':
+      if (mac) return spawn('open', ['-na', 'kitty', '--args', '--directory', cwd, ...argv], { detached: true, stdio: 'ignore' }).unref();
+      return spawn('kitty', ['--directory', cwd, ...argv], { detached: true, stdio: 'ignore' }).unref();
+    case 'wezterm':
+      return spawn(mac ? '/Applications/WezTerm.app/Contents/MacOS/wezterm' : 'wezterm', ['start', '--cwd', cwd, '--', ...argv], { detached: true, stdio: 'ignore' }).unref();
+    case 'custom': {
+      if (!custom) throw new Error('Set a custom terminal command in settings, e.g.  alacritty --working-directory {cwd} -e {cmd}');
+      const full = custom.replaceAll('{cwd}', shq(cwd)).replaceAll('{cmd}', cmd).replaceAll('{line}', shq(line));
+      return spawn('sh', ['-c', full], { detached: true, stdio: 'ignore' }).unref();
+    }
+    default:
+      return spawn('x-terminal-emulator', ['-e', 'sh', '-c', `${line}; exec $SHELL`], { detached: true, stdio: 'ignore' }).unref();
+  }
+}

package/server/welcome.js

@@ -0,0 +1,168 @@
+// The first thing a new user sees: a pre-rendered "session" that explains wisp
+// using the same blocks an agent would. Doubles as a living block gallery.
+
+import os from 'node:os';
+import { newId } from './runner.js';
+
+export function welcomeSession() {
+  const now = Date.now();
+  return {
+    id: newId(),
+    title: 'Welcome to wisp',
+    titleAuto: false,
+    agent: 'wisp',
+    cwd: os.homedir(),
+    mode: 'plan',
+    model: '',
+    state: 'review',
+    unread: true,
+    createdAt: now,
+    updatedAt: now,
+    agentSessionId: null,
+    queue: [],
+    turns: [
+      {
+        id: newId(),
+        prompt: 'What is wisp and how do I use it?',
+        startedAt: now - 94_000,
+        endedAt: now,
+        status: 'done',
+        stats: { costUsd: 0, durationMs: 94_000, turns: 1 },
+        activity: [
+          { t: now - 90_000, kind: 'read', label: 'Reading server/protocol.js', file: 'server/protocol.js' },
+          { t: now - 80_000, kind: 'search', label: 'Searching for “blocks”' },
+          { t: now - 60_000, kind: 'edit', label: 'Editing web/js/app.js', file: 'web/js/app.js' },
+          { t: now - 30_000, kind: 'run', label: 'Run the test suite', detail: 'npm test' },
+        ],
+        changes: [
+          {
+            file: 'src/session.ts',
+            op: 'edit',
+            edits: [
+              {
+                before: 'export async function run(agent, task) {\n  const log = await agent.exec(task);\n  return log; // 4,000 lines nobody reads\n}',
+                after: 'export async function run(agent, task) {\n  const log = await agent.exec(task);\n  return present(log); // what changed, why, what\'s next\n}',
+              },
+            ],
+          },
+        ],
+        presentation: {
+          blocks: [
+            {
+              type: 'hero',
+              title: 'Send agents off. Read the highlights.',
+              summary: 'wisp launches coding agents in the background and hands you a short visual brief when they finish — not a transcript. Follow up right here.',
+              status: 'info',
+            },
+            {
+              type: 'flow',
+              title: 'How a wisp travels',
+              nodes: [
+                { id: 'a', label: 'You launch', note: 'task + project' },
+                { id: 'b', label: 'Agent works', note: 'Claude Code, headless' },
+                { id: 'c', label: 'Presentation', note: 'blocks, not logs' },
+                { id: 'd', label: 'You follow up', note: 'or mark done' },
+              ],
+              edges: [['a', 'b'], ['b', 'c'], ['c', 'd'], ['d', 'b', 'resumes']],
+            },
+            {
+              type: 'stats',
+              items: [
+                { label: 'lines of transcript you skipped', value: 4182, tone: 'good' },
+                { label: 'agents running at once', value: 6, unit: '×' },
+                { label: 'block types', value: 19 },
+              ],
+            },
+            {
+              type: 'steps',
+              title: 'Using it',
+              items: [
+                { title: 'Launch', detail: 'Press N, describe the task, pick the project folder. Launch several — they run in parallel.' },
+                { title: 'Forget about it', detail: 'The queue on the left shows what each agent is doing in one line.' },
+                { title: 'Review', detail: 'Finished work lands in “Needs you” with a dot. Open it to see the brief.' },
+                { title: 'Follow up or close', detail: 'Reply to resume the same agent session, or press E to mark it done.' },
+              ],
+            },
+            { type: 'diff', file: 'src/session.ts', caption: 'Real diffs come from the agent’s own edits — no copy-paste.' },
+            {
+              type: 'tests',
+              command: 'npm test',
+              passed: 128,
+              failed: 1,
+              skipped: 3,
+              durationMs: 6400,
+              failures: [{ name: 'session › resumes after restart', message: 'expected state "review", received "running"', file: 'test/session.test.ts:88' }],
+            },
+            {
+              type: 'files',
+              items: [
+                { path: 'src/session.ts', change: 'modified', note: 'Returns a presentation instead of the raw log.' },
+                { path: 'src/present/blocks.ts', change: 'added', note: 'Block schema + validation.' },
+                { path: 'src/legacy/transcript.ts', change: 'deleted' },
+              ],
+            },
+            {
+              type: 'commits',
+              branch: 'feat/presentations',
+              items: [
+                { hash: 'a1f9c03', message: 'feat(session): return presentations', files: 3, additions: 142, deletions: 37 },
+                { hash: '7be21d4', message: 'test: cover resume after restart', files: 1, additions: 48, deletions: 0 },
+              ],
+            },
+            {
+              type: 'compare',
+              before: { label: 'Without wisp', items: ['Babysit a terminal per agent', 'Scroll 40 screens to find what changed', 'Lose track of which tab finished'] },
+              after: { label: 'With wisp', items: ['Fire and forget, many at once', 'One page: what, why, proof', 'A queue that tells you what needs you'] },
+            },
+            {
+              type: 'chart',
+              title: 'Time spent per finished task',
+              unit: 'min',
+              items: [
+                { label: 'reading transcripts', value: 11 },
+                { label: 'reading a wisp', value: 1.5 },
+              ],
+            },
+            { type: 'terminal', command: 'npx wisp "add dark mode to the settings page"', output: '  ◌ wisp is floating at http://localhost:4477\n\n  launched: add dark mode to the settings page', exitCode: 0 },
+            {
+              type: 'checklist',
+              title: 'Permission modes (pick per launch)',
+              items: [
+                { text: 'Plan — read-only, the agent proposes', done: true },
+                { text: 'Edits — the agent may change files, no shell prompts', done: true },
+                { text: 'Full auto — no permission prompts at all; use on trusted repos', done: false },
+              ],
+            },
+            {
+              type: 'code',
+              language: 'json',
+              caption: 'Agents answer with blocks like these — you can ask for any of them.',
+              code: '{"type":"stats","items":[{"label":"tests","value":48,"delta":"+4","tone":"good"}]}',
+            },
+            {
+              type: 'tree',
+              title: 'Agents can sketch structure too',
+              items: [
+                { path: 'src/present/blocks.ts', change: 'added' },
+                { path: 'src/present/render.ts', change: 'added', note: 'pure, no DOM' },
+                { path: 'src/session.ts', change: 'modified' },
+                { path: 'test/session.test.ts', change: 'modified' },
+              ],
+            },
+            { type: 'callout', tone: 'info', title: 'Agents can ask you mid-run', text: 'When a decision matters, the agent pauses with a question. The session jumps to **Needs you**; your answer goes straight back to the still-running agent.' },
+            { type: 'callout', tone: 'warn', title: 'Heads up', text: 'This tour is static. Launch a real wisp with **N** — or take any real session over in your terminal with **T**.' },
+            {
+              type: 'question',
+              question: 'Which agent harness should wisp support next?',
+              options: [
+                { label: 'Codex', reply: 'Codex next' },
+                { label: 'opencode', reply: 'opencode next' },
+              ],
+            },
+            { type: 'next', items: ['Summarize what changed on this branch', 'Find and fix the flakiest test', 'Write a README for this repo'] },
+          ],
+        },
+      },
+    ],
+  };
+}