wisp-agents 0.14.0 → 0.16.0

package/server/runner.js

@@ -4,23 +4,23 @@
 // 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 { systemPrompt, parsePresentation, heroOf } from './protocol.js';
 import { captureCheckpoint, freshCheckpoint, readGitFile } from './checkpoint.js';
 import { teamNote, copies, SUBAGENT_ASK } from './subagents.js';
+import { handoffNote } from './handoff.js';
+import { bad, MODES, newId } from './util.js';
 
 const MAX_ACTIVITY = 400;
-const MODES = new Set(['plan', 'edits', 'auto']);
 const LINGER_MS = 3000; // how long a CLI may keep running after it reported its result
 const BACKGROUND_MAX_MS = 60 * 60_000; // how long a turn may wait on its background tasks
 const ASK_SERVER = path.join(path.dirname(fileURLToPath(import.meta.url)), 'mcp-ask.js');
 // The delegate tool lives on the same injected server, so harnesses name it like ask_user.
 const delegateTool = (askTool) => askTool && askTool.replace(/ask_user$/, 'delegate');
 
-export const newId = () => randomUUID().replace(/-/g, '').slice(0, 12);
+export { newId };
 
 // Where the agent actually works: its own worktree when it has one, else the project folder.
 export const workdir = (s) => s.worktree?.cwd || s.cwd;
@@ -32,6 +32,16 @@ function workspaceNote(s) {
   return `\n\n## Workspace\n\nYou are in an isolated git worktree (${wt.path}) on branch \`${wt.branch}\`, created from \`${wt.baseRef}\` for this task only. Other agents may be working in the user's main checkout, so make every change here. Dependencies and build output (node_modules, virtualenvs, dist/) are not shared with the main checkout: install them if a command needs them. Leave your changes uncommitted unless the user asks you to commit; the user ships them from wisp (commit, push, pull request).`;
 }
 
+// A follow-up's { agent, model, effort }, or null when it's what the session already runs on.
+// Fields left out keep the session's; a new harness without a model gets its default.
+function changedRun(session, run) {
+  if (!run || typeof run !== 'object') return null;
+  const agent = run.agent || session.agent;
+  const same = agent === session.agent;
+  const next = { agent, model: String(run.model ?? (same ? session.model : '') ?? ''), effort: String(run.effort ?? (same ? session.effort : '') ?? '') };
+  return same && next.model === (session.model || '') && next.effort === (session.effort || '') ? null : next;
+}
+
 function autoTitle(prompt) {
   const line = prompt.trim().split('\n')[0].replace(/\s+/g, ' ');
   return line.length > 64 ? `${line.slice(0, 63)}…` : line;
@@ -82,7 +92,7 @@ export function summarize(s, store) {
     ),
     ...(s.parentId && { parentId: s.parentId, member: s.member }),
     // Auto: what it picked and why, for the card's tooltip.
-    route: s.route ? { goal: s.route.goal, type: s.route.type, label: s.route.label, chance: s.route.chance, n: s.route.n, usd: s.route.usd, explored: s.route.explored, trying: s.route.trying, alternatives: s.route.alternatives } : null,
+    route: s.route ? { goal: s.route.goal, type: s.route.type, label: s.route.label, chance: s.route.chance, n: s.route.n, usd: s.route.usd, explored: s.route.explored, trying: s.route.trying, alternatives: s.route.alternatives, ...(s.route.switched && { switched: true }) } : null,
   };
 }
 
@@ -129,6 +139,7 @@ export class Runner extends EventEmitter {
       createdAt: now,
       updatedAt: now,
       agentSessionId: null,
+      agentSessions: {}, // harness -> its own conversation id, so switching back resumes it
       queue: [],
       turns: [],
       ...(worktree && { worktree }),
@@ -145,10 +156,13 @@ export class Runner extends EventEmitter {
   }
 
   // mode: switch the permission mode (plan / edits / auto) from this follow-up on. A queued
-  // follow-up keeps its own, so the run before it isn't affected.
-  reply(session, text, attachments = [], { queue = false, mode } = {}) {
+  // follow-up keeps its own, so the run before it isn't affected. run: { agent, model, effort }
+  // switches the harness, model and thinking level the same way (see #switchRun).
+  reply(session, text, attachments = [], { queue = false, mode, run } = {}) {
     if (!MODES.has(mode) || mode === session.mode) mode = undefined;
-    if (session.ask && !mode) {
+    run = changedRun(session, run);
+    const extra = { ...(mode && { mode }), ...(run && { run }) };
+    if (session.ask && !mode && !run) {
       this.answer(session, text);
       return { answered: true };
     }
@@ -158,27 +172,46 @@ export class Runner extends EventEmitter {
       // 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, ...(mode && { mode }) });
+        session.queue.push({ id: newId(), text, attachments, ...extra });
         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, ...(mode && { mode }) });
+        session.queue.push({ id: newId(), text, attachments, ...extra });
         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, ...(mode && { mode }) });
+      session.queue.splice(at < 0 ? session.queue.length : at, 0, { id: newId(), text, attachments, now: true, ...extra });
       this.#interrupt(session);
       return { interrupted: true };
     }
     if (mode) session.mode = mode;
+    if (run) this.#switchRun(session, run);
     this.#startTurn(session, text, attachments);
     return { queued: false };
   }
 
+  // A follow-up on another harness, model or thinking level. A model or level change resumes the
+  // same conversation; a harness change resumes that harness's own one (if it ran earlier in this
+  // task) or starts it fresh, and #startTurn hands it the turns it missed.
+  #switchRun(session, { agent, model, effort }) {
+    session.agentSessions ||= {};
+    // Sessions from before agentSessions: their conversation belongs to the harness they ran on.
+    if (session.agentSessionId) session.agentSessions[session.agent] = session.agentSessionId;
+    for (const t of session.turns) t.agent ||= session.agent;
+    // Auto's pick was overruled: the card stops crediting it, and the router learns (services/auto.js).
+    if (session.route && (agent !== session.agent || model !== session.model)) session.route.switched = true;
+    if (agent !== session.agent) {
+      session.agent = agent;
+      session.agentSessionId = session.agentSessions[agent] || null;
+    }
+    session.model = model;
+    session.effort = effort;
+  }
+
   // Drop a follow-up that hasn't gone out yet.
   unqueue(session, itemId) {
     const at = session.queue.findIndex((q) => q.id === itemId);
@@ -234,9 +267,9 @@ export class Runner extends EventEmitter {
   // created on first use and resumed after that. Returns one record (or { error }) per task.
   delegate(lead, tasks) {
     const turn = lead.turns.at(-1);
-    if (turn?.status !== 'running') throw Object.assign(new Error('The lead agent is not running.'), { status: 409 });
+    if (turn?.status !== 'running') throw bad('The lead agent is not running.', 409);
     const team = lead.subagents || [];
-    if (!team.length) throw Object.assign(new Error('This session has no subagents. The user can add them when launching.'), { status: 400 });
+    if (!team.length) throw bad('This session has no subagents. The user can add them when launching.');
     const out = [];
     const claimed = new Set(); // copies handed a task in this call
     const busy = (name) => claimed.has(name) || this.live.has(lead.children?.[name]);
@@ -320,7 +353,8 @@ export class Runner extends EventEmitter {
     this.live.get(session.id).stop();
   }
 
-  #startTurn(session, prompt, attachments = []) {
+  // The record of a new turn, with the checkpoint taken before the agent touches anything.
+  #newTurn(session, prompt, attachments) {
     const id = newId();
     // A subagent's edits land in the lead's turn, whose checkpoint already covers them.
     const checkpoint =
@@ -329,7 +363,7 @@ export class Runner extends EventEmitter {
         : !session.turns.length && session.worktree?.head
           ? freshCheckpoint(session.worktree)
           : captureCheckpoint(workdir(session), session.id, id);
-    const turn = {
+    return {
       id,
       prompt,
       agent: session.agent,
@@ -346,6 +380,38 @@ export class Runner extends EventEmitter {
       presentation: null,
       stats: null,
     };
+  }
+
+  // The wisp protocol for this run: a lead hears about its team, a subagent that it can't ask.
+  #systemPrompt(session, adapter, team) {
+    const base = session.parentId
+      ? systemPrompt({ ask: SUBAGENT_ASK })
+      : systemPrompt({ askTool: adapter.askTool }) + teamNote(team, adapters, delegateTool(adapter.askTool ?? 'mcp__wisp__ask_user'));
+    return base + workspaceNote(session) + this.promptExtra(session);
+  }
+
+  // wisp's own MCP server (ask_user, delegate), for harnesses that take one. Subagents get none.
+  #mcpServers(session, adapter, team) {
+    if (!this.bridge || adapter.askTool === null || session.parentId) return {};
+    return {
+      wisp: {
+        command: process.execPath,
+        args: [ASK_SERVER],
+        // Inside the desktop app execPath is the Electron binary; without
+        // ELECTRON_RUN_AS_NODE it boots a second app (extra Dock icon) per turn.
+        env: {
+          ELECTRON_RUN_AS_NODE: '1',
+          WISP_URL: this.bridge.url,
+          WISP_TOKEN: this.bridge.token,
+          WISP_SESSION: session.id,
+          ...(team.length && { WISP_TEAM: JSON.stringify(team.map((m) => ({ name: m.name, agent: adapters[m.agent]?.name || m.agent, model: m.model, effort: m.effort, use: m.use, count: m.count || 1, copies: copies(m) }))) }),
+        },
+      },
+    };
+  }
+
+  #startTurn(session, prompt, attachments = []) {
+    const turn = this.#newTurn(session, prompt, attachments);
     session.turns.push(turn);
     session.state = 'running';
     session.unread = false;
@@ -359,37 +425,20 @@ export class Runner extends EventEmitter {
     const adapter = adapters[session.agent];
     // Leads get the delegate tool next to ask_user; subagents get neither (nobody to ask).
     const team = adapter.askTool !== null ? session.subagents || [] : [];
-    const prompt0 = session.parentId
-      ? systemPrompt({ ask: SUBAGENT_ASK })
-      : systemPrompt({ askTool: adapter.askTool }) + teamNote(team, adapters, delegateTool(adapter.askTool ?? 'mcp__wisp__ask_user'));
+    // A harness that hasn't seen every earlier turn (the user switched to it) gets them first.
+    const handoff = session.parentId ? '' : handoffNote(session, session.agent, session.agentSessionId, (t) => adapters[t.agent]?.name || t.agent);
     const handle = adapter.run({
-      prompt,
+      prompt: handoff ? `${handoff}\n\n${prompt}` : prompt,
       attachments,
       cwd: workdir(session),
       resumeId: session.agentSessionId,
       mode: session.mode,
       model: session.model,
       effort: session.effort || '',
-      systemPrompt: prompt0 + workspaceNote(session) + this.promptExtra(session),
+      systemPrompt: this.#systemPrompt(session, adapter, team),
       // A lead with a team delegates through wisp, so the harness's own subagent tool is switched off.
       delegating: team.length > 0 && !!this.bridge,
-      mcpServers: this.bridge && adapter.askTool !== null && !session.parentId
-        ? {
-            wisp: {
-              command: process.execPath,
-              args: [ASK_SERVER],
-              // Inside the desktop app execPath is the Electron binary; without
-              // ELECTRON_RUN_AS_NODE it boots a second app (extra Dock icon) per turn.
-              env: {
-                ELECTRON_RUN_AS_NODE: '1',
-                WISP_URL: this.bridge.url,
-                WISP_TOKEN: this.bridge.token,
-                WISP_SESSION: session.id,
-                ...(team.length && { WISP_TEAM: JSON.stringify(team.map((m) => ({ name: m.name, agent: adapters[m.agent]?.name || m.agent, model: m.model, effort: m.effort, use: m.use, count: m.count || 1, copies: copies(m) }))) }),
-              },
-            },
-          }
-        : {},
+      mcpServers: this.#mcpServers(session, adapter, team),
       onEvent: (ev) => {
         if (released) return; // a lingering process we already let go of
         const waiting = this.#onEvent(session, turn, ev) === 'waiting';
@@ -417,6 +466,7 @@ export class Runner extends EventEmitter {
       this.stopping.delete(session.id); // a stop that landed after the result has nothing left to stop
       const next = session.queue.shift();
       if (next?.mode) session.mode = next.mode;
+      if (next?.run && adapters[next.run.agent]) this.#switchRun(session, next.run);
       if (next && this.store.get(session.id)) this.#startTurn(session, next.text, next.attachments);
       else this.#touch(session);
     };
@@ -429,6 +479,7 @@ export class Runner extends EventEmitter {
     switch (ev.type) {
       case 'session':
         session.agentSessionId = ev.id;
+        (session.agentSessions ||= {})[session.agent] = ev.id;
         return;
       case 'tool':
       case 'tool_error':

package/server/services/auto.js

@@ -0,0 +1,67 @@
+// Auto: wisp picks harness and model per task and learns from outcomes (server/router.js).
+// This wires the router to the rest of the server: which harnesses are installed here, the
+// user's Auto settings, and the outcome signals that come back from summaries.
+
+import { listAgents } from '../adapters/index.js';
+import { GOALS } from '../router.js';
+import { bad } from '../util.js';
+
+export function createAuto(app) {
+  const { store, router } = app;
+  let agentsHere = [];
+
+  const detect = async (opts) => {
+    const agents = await listAgents(opts);
+    agentsHere = agents;
+    const added = router.sync(agents);
+    if (added.length) app.broadcast('router', { added });
+    return agents;
+  };
+  // This computer's harnesses: the last ones detected, else detected now.
+  const agents = async () => (agentsHere.length ? agentsHere : await detect());
+
+  const opts = () => {
+    const r = store.config.defaults.router || {};
+    return { explore: r.explore !== 'off', allowed: Array.isArray(r.allowed) && r.allowed.length ? r.allowed : null };
+  };
+  const goalOf = (model) => (GOALS[model] ? model : GOALS[store.config.defaults.models?.auto] ? store.config.defaults.models.auto : 'balanced');
+
+  // Subagents set to Auto are routed on their first task, from this computer's harnesses.
+  app.runner.routeAuto = (prompt) => router.choose({ prompt, agents: agentsHere, goal: goalOf(), ...opts() });
+
+  // A routed session's outcome so far, from its summary: works the same for sessions on machines.
+  // Follow-ups after the first turn count as corrections; a merged or closed PR settles it, unless
+  // the user moved the task to another harness or model first.
+  const signals = (sum) => {
+    if (!sum?.id || !router.route(sum.id) || sum.status === 'running' || sum.state === 'running') return;
+    const pr = sum.pr?.state;
+    router.signal(sum.id, {
+      hero: ['done', 'partial', 'blocked', 'info'].includes(sum.status) ? sum.status : undefined,
+      followups: Math.max(0, (sum.turnCount || 1) - 1),
+      merged: pr === 'MERGED' || undefined,
+      closed: pr === 'CLOSED' || undefined,
+      switched: sum.route?.switched || undefined,
+    });
+  };
+
+  // agent 'auto' (and compare entries set to it) → a harness and model picked by the router from
+  // `agents`: this computer's, or the machine's the launch goes to. Model is the goal for Auto.
+  const resolve = async (body, agents, { team = false } = {}) => {
+    const want = [{ agent: body.agent, model: body.model, effort: body.effort }, ...(Array.isArray(body.compare) ? body.compare : [])];
+    if (!want.some((r) => r.agent === 'auto')) return body;
+    const taken = [];
+    const out = want.map((r, i) => {
+      if (r.agent !== 'auto') return r;
+      const pick = router.choose({ prompt: body.prompt, attachments: (body.attachments || []).length, agents, goal: goalOf(r.model), important: !!body.important, exclude: taken, needDelegate: i === 0 && team, ...opts() });
+      if (!pick) throw bad('Auto found no installed harness to run this on.');
+      taken.push(pick.key);
+      return { agent: pick.agent, model: pick.model, effort: '', route: pick.route };
+    });
+    return { ...body, ...out[0], compare: out.slice(1) };
+  };
+
+  // What the Auto view shows: goals, settings, and what the router learned.
+  const view = async () => ({ goals: GOALS, goal: goalOf(), settings: { explore: opts().explore, allowed: opts().allowed }, ...router.report(await agents()) });
+
+  return { detect, agents, opts, goalOf, signals, resolve, view };
+}

package/server/services/feedback.js

@@ -0,0 +1,53 @@
+// Feedback for the wisp team: thumbs on a turn and/or a note.
+// A rating sticks to its turn (it shows on the card and can be taken back). What goes out is
+// the rating, the user's own words, and how the run was set up — never the prompt or the result.
+
+import { splitId } from '../machines.js';
+import { feedbackAvailable } from '../telemetry.js';
+import { bad } from '../util.js';
+import { runProps } from './telemetry.js';
+
+export function createFeedback(app) {
+  const { store, machines, telemetry } = app;
+
+  return async function sendFeedback({ rating, text, sessionId, turnId, source } = {}) {
+    if (rating !== undefined && rating !== null && rating !== 'up' && rating !== 'down') throw bad('rating must be up or down');
+    text = String(text || '').trim();
+    if (rating === undefined && !text) throw bad('Write something, or pick 👍 / 👎.');
+    // A session on a machine: that wisp keeps the rating on its turn and sends it.
+    const at = sessionId && splitId(sessionId);
+    if (sessionId && turnId && rating !== undefined) app.router.signal(sessionId, { feedback: rating });
+    if (at) {
+      try {
+        return await machines.json(at.machine, 'POST', '/feedback', { rating, text, sessionId: at.id, turnId, source });
+      } catch (err) {
+        if (err.status === 400) throw err; // offline, or an older wisp there: send it from here, without the run
+      }
+    }
+    const s = sessionId && !at ? store.get(sessionId) : null;
+    if (sessionId && !at && !s) throw bad('no such session', 404);
+    const turn = s && (turnId ? s.turns.find((t) => t.id === turnId) : s.turns.at(-1));
+    if (turnId && s && !turn) throw bad('no such turn', 404);
+    // Only thumbs on a turn stick to it; a rating in the feedback dialog is about wisp as a whole.
+    if (turn && turnId && rating !== undefined) {
+      turn.feedback = rating ? { rating, at: Date.now() } : undefined;
+      store.save(s);
+      app.broadcast('turn', { sessionId: s.id, turnId: turn.id });
+    }
+    const blocks = turn?.presentation?.blocks || [];
+    const context = turn && {
+      ...runProps(s, turn),
+      status: turn.status,
+      heroStatus: blocks.find((b) => b.type === 'hero')?.status,
+      blockTypes: [...new Set(blocks.map((b) => b.type))],
+      durationMs: turn.endedAt ? turn.endedAt - turn.startedAt : undefined,
+      tour: s.agent === 'wisp' || undefined,
+    };
+    const props = { ...context, rating: rating || undefined, source: String(source || (turn ? 'turn' : 'app')).slice(0, 20), machine: at ? true : undefined };
+    // Thumbs on a turn count as a rating; anything written, or sent from the dialog, is 'feedback'.
+    const event = text || !turnId ? 'feedback' : 'turn_rated';
+    if (event === 'turn_rated' && rating === null) props.cleared = true;
+    const sent = await telemetry.feedback(event, { ...props, text: text || undefined });
+    return { ok: true, sent, available: feedbackAvailable() };
+  };
+}

package/server/services/install.js

@@ -0,0 +1,69 @@
+// One-click setup for people with no harness yet. opencode is the one wisp installs: its free
+// models work without an account, so a fresh computer can run a task right away. It goes into
+// wisp's own folder (~/.wisp/tools) through npm, which every wisp install already has: no sudo,
+// no shell profile edits, the same on Windows. The opencode adapter finds it there.
+
+import fs from 'node:fs';
+import { spawn } from '../proc.js';
+import { bad, toolsDir } from '../util.js';
+
+export const INSTALLABLE = {
+  opencode: { pkg: 'opencode-ai', name: 'opencode' },
+};
+const TIMEOUT_MS = 5 * 60_000;
+
+// npm install --prefix <dir> <pkg>@latest. Resolves when it worked, rejects with the tail of
+// npm's output when it didn't: a 424, since offline or a broken npm isn't a wisp bug (it's
+// counted in the harness_install event instead of reported as an exception).
+export function npmInstall(pkg, dir, { npm = process.env.WISP_NPM || 'npm', timeout = TIMEOUT_MS } = {}) {
+  fs.mkdirSync(dir, { recursive: true });
+  const env = { ...process.env };
+  delete env.ELECTRON_RUN_AS_NODE; // the desktop app's node mode must not leak into npm
+  return new Promise((resolve, reject) => {
+    const child = spawn(npm, ['install', '--prefix', dir, '--no-audit', '--no-fund', '--loglevel=error', `${pkg}@latest`], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = '';
+    const keep = (d) => (out = (out + d).slice(-4000));
+    child.stdout.on('data', keep);
+    child.stderr.on('data', keep);
+    const timer = setTimeout(() => child.kill(), timeout);
+    child.on('error', (err) => (clearTimeout(timer), reject(bad(err.code === 'ENOENT' ? 'npm isn’t on PATH, so wisp can’t install it. Install Node.js (it comes with npm), then try again.' : err.message, 424))));
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      if (code === 0) return resolve();
+      const tail = out.trim().split('\n').filter(Boolean).slice(-3).join(' ');
+      reject(bad(`npm install ${pkg} ${signal ? 'timed out' : 'failed'}${tail ? `: ${tail}` : ''}`, 424));
+    });
+  });
+}
+
+export function createInstaller(app, { install = npmInstall } = {}) {
+  const running = new Map(); // id -> promise: a second click (or tab) waits for the same install
+
+  // Installs the harness, detects again and returns the harness list. Throws when the install
+  // failed or the harness still isn't found afterwards.
+  async function run(id) {
+    const spec = INSTALLABLE[id];
+    if (!spec) throw bad(`wisp can’t install ${id}. Install it yourself, then re-check.`);
+    if (!running.has(id)) {
+      const job = (async () => {
+        const started = Date.now();
+        try {
+          await install(spec.pkg, toolsDir());
+        } catch (err) {
+          app.telemetry?.track('harness_install', { agent: id, ok: false, ms: Date.now() - started });
+          throw err;
+        }
+        const agents = await app.auto.detect({ fresh: true });
+        const ok = agents.find((a) => a.id === id)?.available;
+        app.telemetry?.track('harness_install', { agent: id, ok: !!ok, ms: Date.now() - started });
+        if (!ok) throw bad(`${spec.name} was installed but doesn’t start: ${agents.find((a) => a.id === id)?.error || 'unknown error'}`, 500);
+        app.broadcast('agents', {});
+        return agents;
+      })().finally(() => running.delete(id));
+      running.set(id, job);
+    }
+    return running.get(id);
+  }
+
+  return { run, installing: (id) => running.has(id) };
+}

package/server/services/launch.js

@@ -0,0 +1,127 @@
+// One way in for every launch (the launcher, the CLI, recipes, triggers, the phone and compare
+// runs), here or on a machine, plus the follow-ups and "done" that every surface shares.
+
+import fs from 'node:fs';
+import { adapters } from '../adapters/index.js';
+import { createWorktree, worktreeSource, ensureWorktree, removeWorktree } from '../git.js';
+import { qualify } from '../machines.js';
+import { fill, positional } from '../recipes.js';
+import { summarize } from '../runner.js';
+import { normalizeTeam } from '../subagents.js';
+import { bad, expand, MODES, newId } from '../util.js';
+
+export const MAX_COMPARE = 4;
+
+export function createLaunch(app) {
+  const { store, runner, machines } = app;
+
+  // body: { prompt, cwd, agent, mode, model, effort, attachments: [uploadId], worktree, compare,
+  //         subagents: [{ name, agent, model, effort, use }] | preset: teamId }
+  async function launch(body, origin = null) {
+    if (!String(body.prompt || '').trim()) throw bad('prompt required');
+    const cwd = expand(body.cwd || process.cwd());
+    if (!fs.existsSync(cwd) || !fs.statSync(cwd).isDirectory()) throw bad(`Not a directory: ${cwd}`);
+    const d = store.config.defaults;
+    const preset = body.preset && store.config.teams.find((t) => t.id === body.preset);
+    if (body.preset && !preset && !body.subagents) throw bad(`no such subagent preset: ${body.preset}`);
+    const subagents = normalizeTeam(body.subagents ?? preset?.members, adapters);
+    // compare: more { agent, model, effort } to run the same task on, side by side. 'auto' is
+    // resolved here: the router picks a harness and model (a different one per compare run).
+    const resolved = await app.auto.resolve(body, await app.auto.agents(), { team: subagents.length > 0 });
+    const runners = [{ agent: resolved.agent, model: resolved.model, effort: resolved.effort, route: resolved.route }, ...(resolved.compare || [])].slice(0, MAX_COMPARE).map((r, i) => {
+      const agent = r.agent || (i ? d.agent : '') || 'claude';
+      if (!adapters[agent]) throw bad(`unknown agent: ${agent}`);
+      return { agent, model: r.model ?? (i ? d.models?.[agent] || '' : ''), effort: /^[\w-]{1,20}$/.test(r.effort || '') ? r.effort : '', ...(r.route && { route: r.route }) };
+    });
+    const mode = MODES.has(body.mode) ? body.mode : 'edits';
+    // Worktrees are on by default in git repos (off in Plan mode: nothing gets written). Compare
+    // runs need one each, or the harnesses would edit the same files.
+    const comparing = runners.length > 1;
+    const wantTree = body.worktree ?? (comparing || (mode !== 'plan' && d.worktree !== 'off'));
+    // groupId: one launch sent to several machines (or here and there) shows as one task.
+    const groupId = /^[a-f0-9]{12}$/.test(body.groupId || '') ? body.groupId : comparing ? newId() : null;
+    const attachments = app.uploads.resolve(body.attachments);
+    const ids = runners.map(() => newId());
+    let trees = ids.map(() => null);
+    if (wantTree) {
+      const must = body.worktree === true || (comparing && mode !== 'plan');
+      // One fetch for the whole launch, then the checkouts side by side: compare runs used to
+      // fetch and check out one after the other before anything showed up in the feed.
+      const results = await worktreeSource(cwd).then(
+        (source) => source && Promise.allSettled(ids.map((id) => createWorktree({ cwd, home: store.home, id, title: body.prompt, source }))),
+        (err) => [{ status: 'rejected', reason: err }],
+      );
+      const failed = results?.find((x) => x.status === 'rejected')?.reason;
+      trees = ids.map((_, i) => (results?.[i]?.status === 'fulfilled' ? results[i].value : null));
+      if (must && (failed || trees.some((t) => !t))) {
+        await Promise.all(trees.map((t) => t && removeWorktree(t, { force: true, branch: 'force' }).catch(() => {})));
+        if (failed) throw bad(`Could not create a worktree: ${failed.message}`);
+        throw bad(comparing ? 'Compare needs a git repo with at least one commit, so each harness gets its own worktree.' : 'Not a git repo with commits, so there is nothing to make a worktree from.');
+      }
+      if (failed) console.warn(`wisp: no worktree for ${cwd}: ${failed.message}`);
+    }
+    return runners.map((r, i) => runner.create({ id: ids[i], prompt: body.prompt, cwd, ...r, mode, attachments, worktree: trees[i], groupId, origin, subagents }));
+  }
+
+  // Where a launch runs: body.machine, else a project folder that only exists on a machine
+  // (recipes and schedules keep just the path). null = here.
+  function machineFor(body) {
+    if (body.machine) return machines.get(String(body.machine)).id;
+    const cwd = String(body.cwd || '');
+    if (!cwd || fs.existsSync(expand(cwd))) return null;
+    return store.config.projects.find((p) => p.machine && (cwd === p.path || cwd.startsWith(`${p.path}/`)))?.machine || null;
+  }
+
+  // Attachments are uploaded here; a machine gets its own copies before a launch or reply.
+  async function pushUploads(mid, ids) {
+    const out = [];
+    for (const u of app.uploads.resolve(ids)) out.push((await machines.upload(mid, u)).id);
+    return out;
+  }
+
+  // launch(), here or on a machine. Resolves with summaries (a compare launch has several).
+  async function launchAny(body, origin = null) {
+    const mid = machineFor(body);
+    if (!mid) return (await launch(body, origin)).map((x) => summarize(x, store));
+    // Auto for a machine: routed here, with the harnesses that machine has; its outcomes come
+    // back through the summaries it streams (auto.signals), so one router learns from every place.
+    const routed = await app.auto.resolve(body, machines.agentsOf(mid) || [], { team: !!(body.subagents?.length || body.preset) });
+    const routes = [routed.route, ...(routed.compare || []).map((c) => c.route)];
+    const sendBody = { ...routed, compare: routed.compare?.map(({ route, ...c }) => c) };
+    delete sendBody.route;
+    if (!sendBody.compare?.length && !body.compare) delete sendBody.compare;
+    const out = await machines.launch(mid, { ...sendBody, attachments: await pushUploads(mid, body.attachments), ...(origin && { origin }) });
+    (out.group || [out]).forEach((x, i) => routes[i] && app.router.record(qualify(x.id, mid), routes[i]));
+    const known = store.projectFor(out.cwd, mid);
+    (known || store.addProject(out.cwd, { machine: mid })).lastUsedAt = Date.now();
+    store.saveConfig();
+    if (!known) app.broadcast('config', {});
+    return (out.group || [out]).map((x) => machines.summary(mid, x));
+  }
+
+  // A follow-up from anywhere (UI, CLI, phone). An archived session may have lost its worktree.
+  async function replyTo(s, text, attachments = [], queue, mode, run) {
+    await ensureWorktree(s.worktree);
+    return runner.reply(s, text, attachments, { queue: queue ?? store.config.defaults.followUp === 'queue', mode, run });
+  }
+
+  function markDone(s) {
+    if (s.state === 'running' || s.state === 'waiting') return false;
+    s.state = 'done';
+    s.unread = false;
+    app.retro.schedule(s, 0);
+    app.sessionChanged(s);
+    return true;
+  }
+
+  async function runRecipe(r, { params = {}, words, cwd, machine, agent, model, effort, mode } = {}) {
+    const values = words ? { ...positional(r.prompt, words), ...params } : params;
+    const [s] = await launchAny({ prompt: fill(r.prompt, values), cwd: r.cwd || cwd, machine, agent: agent || r.agent || undefined, model: model ?? (r.model || undefined), effort: effort || r.effort || undefined, mode: mode || r.mode || undefined }, { kind: 'recipe', id: r.id, name: r.name });
+    r.runs = (r.runs || 0) + 1;
+    r.lastRunAt = Date.now();
+    app.configChanged();
+    return s;
+  }
+
+  return { launch, launchAny, machineFor, pushUploads, replyTo, markDone, runRecipe };
+}

package/server/services/phone.js

@@ -0,0 +1,65 @@
+// Phone (ntfy / Telegram): what a tap or a reply there does to a session, here or on a machine.
+
+import { splitId } from '../machines.js';
+
+export function phoneActions(app) {
+  const { store, runner, machines } = app;
+
+  // What the phone can do to a session, here or on a machine: { s, answer, reply, done } or null.
+  async function sessionOps(sessionId) {
+    const at = splitId(sessionId);
+    if (!at) {
+      const s = store.get(sessionId);
+      return s && { s, answer: (a) => runner.answer(s, a), reply: (t) => app.launcher.replyTo(s, t), done: () => app.launcher.markDone(s) };
+    }
+    const call = (method, p, body) => machines.json(at.machine, method, `/sessions/${at.id}${p}`, body);
+    const s = await call('GET', '').catch((err) => {
+      if (err.status === 404) return null;
+      throw err;
+    });
+    const live = s && (s.state === 'running' || s.state === 'waiting');
+    return s && { s: machines.session(at.machine, s), answer: (a) => call('POST', '/answer', { text: a }), reply: (t) => call('POST', '/reply', { text: t }), done: async () => !live && !!(await call('PATCH', '', { state: 'done' })) };
+  }
+
+  return {
+    // /new from Telegram: the launcher's remembered harness, model and mode, like `wisp "…"`.
+    launch: async ({ project, prompt }) => {
+      const d = store.config.defaults;
+      const agent = d.agent || 'claude';
+      const model = d.models?.[agent] ?? d.model ?? '';
+      const [s] = await app.launcher.launchAny({ prompt, cwd: project.path, machine: project.machine || undefined, agent, model, mode: d.mode || 'edits' }, { kind: 'telegram', name: 'Telegram' });
+      app.broadcast('config', {});
+      return s;
+    },
+    act: async ({ sessionId, kind, ref, index, text }) => {
+      const ops = await sessionOps(sessionId).catch((err) => ({ error: err.message }));
+      if (ops?.error) return `Can’t reach it: ${ops.error}`;
+      if (!ops) return 'That session is gone.';
+      const { s } = ops;
+      if (kind === 'answer') {
+        if (!s.ask || s.ask.id !== ref) return 'That question was already answered.';
+        const answer = s.ask.options[index];
+        if (answer === undefined) return 'Unknown option.';
+        await ops.answer(answer);
+        return `✓ Answered: ${answer}`;
+      }
+      if (kind === 'reply') {
+        const turn = s.turns.at(-1);
+        if (!turn || turn.id !== ref || s.state === 'running') return 'That was already answered.';
+        const q = turn.presentation?.blocks?.findLast((b) => b?.type === 'question');
+        const o = q?.options?.[index];
+        const msg = typeof o === 'string' ? o : o?.reply || o?.label;
+        if (!msg) return 'Unknown option.';
+        await ops.reply(msg);
+        return `✓ Sent: ${typeof o === 'string' ? o : o.label || msg}`;
+      }
+      if (kind === 'done') {
+        if (s.turns.at(-1)?.id !== ref && ref) return 'There is newer work on that session; open wisp to review it.';
+        return (await ops.done()) ? '✓ Marked done' : 'It is still working.';
+      }
+      if (s.agent === 'wisp') return 'That is the tour; it can’t take follow-ups.';
+      const r = await ops.reply(String(text || '').trim());
+      return r.answered ? '✓ Answered' : r.interrupted ? '✓ Sent; the agent picked it up mid-run' : r.queued ? '✓ Queued for when it finishes' : '✓ Sent';
+    },
+  };
+}