wisp-agents 0.6.0 → 0.8.0

package/server/runner.js

@@ -9,13 +9,27 @@ 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';
 
 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');
+// 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);
 
+// 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;
+
+// Worktree sessions get told where they are, so they don't go looking for the main checkout.
+function workspaceNote(s) {
+  const wt = s.worktree;
+  if (!wt) return '';
+  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).`;
+}
+
 function autoTitle(prompt) {
   const line = prompt.trim().split('\n')[0].replace(/\s+/g, ' ');
   return line.length > 64 ? `${line.slice(0, 63)}…` : line;
@@ -26,6 +40,9 @@ export function summarize(s, store) {
   const last = s.turns.at(-1);
   const hero = heroOf(last?.presentation);
   const lastAct = last?.activity?.findLast?.((a) => a.kind !== 'text');
+  // A lead blocked on its subagents says who it's waiting for.
+  const busy = last?.status === 'running' ? (last.delegations || []).filter((d) => store?.get(d.sessionId)?.turns.find((t) => t.id === d.turnId)?.status === 'running') : [];
+  const waitingOn = busy.length ? `Waiting on ${[...new Set(busy.map((d) => d.name))].join(', ')}` : '';
   return {
     id: s.id,
     title: s.title,
@@ -46,9 +63,21 @@ export function summarize(s, store) {
     queued: s.queue?.length || 0,
     status: last?.status === 'running' ? 'running' : hero?.status || (last?.status === 'error' ? 'blocked' : 'info'),
     preview: hero?.summary || '',
-    live: s.ask ? `Asks: ${s.ask.question}` : last?.status === 'running' ? lastAct?.label || 'Starting up' : '',
+    live: s.ask ? `Asks: ${s.ask.question}` : last?.status === 'running' ? waitingOn || lastAct?.label || 'Starting up' : '',
     asks: !!s.ask || !!last?.presentation?.blocks?.some((b) => b.type === 'question'),
     question: s.ask?.question || '',
+    branch: s.worktree?.branch || '',
+    pr: s.pr ? { number: s.pr.number, url: s.pr.url, state: s.pr.state, draft: s.pr.draft, review: s.pr.review, checks: s.pr.checks } : null,
+    groupId: s.groupId || null,
+    origin: s.origin || null, // { kind: 'recipe' | 'trigger', id, name }
+    // The roster, for the stacked logos on the card: used = delegated to at least once, busy = working now.
+    team: (s.subagents || []).flatMap((m) =>
+      copies(m).map((name) => {
+        const child = store?.get(s.children?.[name]);
+        return { name, agent: m.agent, model: m.model, effort: m.effort, used: !!child, busy: child?.state === 'running' };
+      }),
+    ),
+    ...(s.parentId && { parentId: s.parentId, member: s.member }),
   };
 }
 
@@ -62,6 +91,7 @@ export class Runner extends EventEmitter {
     this.stopping = new Set();
     this.interrupting = new Set();
     this.answers = new Map(); // askId -> answer, until the MCP server picks it up
+    this.promptExtra = () => ''; // (session) => text appended to the system prompt (learned preferences)
 
     // Anything that was mid-flight when wisp last died is now orphaned.
     for (const s of store.all()) {
@@ -75,11 +105,12 @@ export class Runner extends EventEmitter {
     }
   }
 
-  create({ prompt, cwd, agent = 'claude', mode = 'edits', model = '', effort = '', attachments = [] }) {
+  // subagents: the team a lead may delegate to. parentId/member: this session is one of them.
+  create({ id = newId(), prompt, cwd, agent = 'claude', mode = 'edits', model = '', effort = '', attachments = [], worktree = null, groupId = null, origin = null, subagents = [], parentId = null, member = '' }) {
     if (!adapters[agent]) throw new Error(`Unknown agent: ${agent}`);
     const now = Date.now();
     const session = {
-      id: newId(),
+      id,
       title: autoTitle(prompt),
       titleAuto: true,
       agent,
@@ -94,9 +125,14 @@ export class Runner extends EventEmitter {
       agentSessionId: null,
       queue: [],
       turns: [],
+      ...(worktree && { worktree }),
+      ...(groupId && { groupId }),
+      ...(origin && { origin }),
+      ...(subagents.length && { subagents, children: {} }),
+      ...(parentId && { parentId, member }),
     };
     this.store.put(session);
-    this.store.touchProject(cwd);
+    if (!parentId) this.store.touchProject(cwd); // a subagent's cwd may be the lead's worktree
     this.#startTurn(session, prompt, attachments);
     return session;
   }
@@ -183,9 +219,75 @@ export class Runner extends EventEmitter {
     return open ? { pending: true } : { cancelled: true };
   }
 
+  // delegate: the lead hands tasks to members of its team. Each member is one child session,
+  // 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 });
+    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 });
+    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]);
+    for (const task of Array.isArray(tasks) ? tasks.slice(0, 12) : []) {
+      const want = String(task?.subagent || '').trim();
+      const m = team.find((x) => x.name === want || copies(x).includes(want));
+      const prompt = String(task?.prompt || '').trim();
+      if (!m) {
+        out.push({ subagent: want, error: `No subagent named "${want}". The team: ${team.map((x) => x.name).join(', ')}.` });
+        continue;
+      }
+      if (!prompt) {
+        out.push({ subagent: want, error: 'The task prompt is empty.' });
+        continue;
+      }
+      // A member name goes to its first free copy; a copy name (codex#2) to that copy.
+      const slot = (want === m.name ? copies(m) : [want]).find((n) => !busy(n));
+      if (!slot) {
+        out.push({ subagent: want, error: `${want} is still working${m.count > 1 && want === m.name ? ` (all ${m.count} copies)` : ''} on earlier tasks. Wait with subagent_results, then delegate again.` });
+        continue;
+      }
+      claimed.add(slot);
+      let child = this.store.get(lead.children?.[slot]);
+      if (child) {
+        child.cwd = workdir(lead); // follows the lead if its worktree moved
+        this.#startTurn(child, prompt);
+      } else {
+        child = this.create({ prompt, cwd: workdir(lead), agent: m.agent, mode: lead.mode, model: m.model, effort: m.effort, parentId: lead.id, member: slot });
+        (lead.children ||= {})[slot] = child.id;
+      }
+      const d = { id: newId(), name: slot, member: m.name, agent: m.agent, model: m.model, effort: m.effort, sessionId: child.id, turnId: child.turns.at(-1).id, prompt, startedAt: Date.now() };
+      (turn.delegations ||= []).push(d);
+      out.push(d);
+    }
+    const sent = out.filter((d) => !d.error);
+    if (sent.length) this.#onEvent(lead, turn, { type: 'tool', kind: 'agent', label: `Delegated to ${[...new Set(sent.map((d) => d.name))].join(', ')}` });
+    this.#touch(lead, { turn: turn.id });
+    return out;
+  }
+
+  // Delegations by id (any turn), or the current turn's when ids is empty, with their child sessions.
+  delegations(lead, ids = []) {
+    const all = lead.turns.flatMap((t) => t.delegations || []);
+    const list = ids.length ? all.filter((d) => ids.includes(d.id)) : lead.turns.at(-1)?.delegations || [];
+    return list.map((d) => ({ d, child: this.store.get(d.sessionId) }));
+  }
+
+  // A child's state changed: the lead's card shows it, so the lead's turn re-renders too.
+  #touchLead(child) {
+    const lead = child.parentId && this.store.get(child.parentId);
+    if (!lead) return;
+    const turn = lead.turns.findLast((t) => t.delegations?.some((d) => d.sessionId === child.id)) || lead.turns.at(-1);
+    this.#touch(lead, { turn: turn?.id });
+  }
+
   stop(session) {
     session.queue = [];
     delete session.ask;
+    for (const cid of Object.values(session.children || {})) {
+      const child = this.store.get(cid);
+      if (child) this.stop(child);
+    }
     if (!this.live.has(session.id)) return;
     this.stopping.add(session.id);
     this.live.get(session.id).stop();
@@ -200,8 +302,16 @@ export class Runner extends EventEmitter {
   }
 
   #startTurn(session, prompt, attachments = []) {
+    const id = newId();
+    // A subagent's edits land in the lead's turn, whose checkpoint already covers them.
+    const checkpoint =
+      session.agent === 'wisp' || session.parentId
+        ? null
+        : !session.turns.length && session.worktree?.head
+          ? freshCheckpoint(session.worktree)
+          : captureCheckpoint(workdir(session), session.id, id);
     const turn = {
-      id: newId(),
+      id,
       prompt,
       agent: session.agent,
       model: session.model,
@@ -210,6 +320,7 @@ export class Runner extends EventEmitter {
       startedAt: Date.now(),
       endedAt: null,
       status: 'running',
+      checkpoint,
       activity: [],
       changes: [],
       presentation: null,
@@ -220,28 +331,40 @@ export class Runner extends EventEmitter {
     session.unread = false;
     delete session.archived;
     this.#touch(session, { turn: turn.id });
+    this.#touchLead(session);
     this.emit('started', { session, turn });
 
     let released = false;
     let linger;
     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'));
     const handle = adapter.run({
       prompt,
       attachments,
-      cwd: session.cwd,
+      cwd: workdir(session),
       resumeId: session.agentSessionId,
       mode: session.mode,
       model: session.model,
       effort: session.effort || '',
-      systemPrompt: systemPrompt({ askTool: adapter.askTool }),
-      mcpServers: this.bridge && adapter.askTool !== null
+      systemPrompt: prompt0 + workspaceNote(session) + this.promptExtra(session),
+      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 },
+              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) }))) }),
+              },
             },
           }
         : {},
@@ -293,10 +416,24 @@ export class Runner extends EventEmitter {
       }
       case 'change': {
         let entry = turn.changes.find((c) => c.file === ev.file);
-        if (!entry) turn.changes.push((entry = { file: ev.file, op: ev.op, edits: [] }));
+        if (!entry) {
+          let beforeFile = ev.beforeFile;
+          if (turn.checkpoint?.commit && !path.isAbsolute(ev.file)) {
+            const fromGit = readGitFile(workdir(session), turn.checkpoint.commit, ev.file);
+            if (fromGit !== null) beforeFile = fromGit;
+            else if (!(turn.checkpoint.untracked || []).includes(ev.file)) beforeFile = null;
+          }
+          turn.changes.push((entry = { file: ev.file, op: ev.op, ...(beforeFile !== undefined ? { beforeFile } : {}), edits: [] }));
+        }
         if (ev.op === 'create' && entry.edits.length === 0) entry.op = 'create';
+        delete entry.reverted;
         entry.edits.push(...ev.edits);
+        if (ev.by && !entry.by?.includes(ev.by)) (entry.by ||= []).push(ev.by);
         this.store.save(session);
+        // A subagent's edits are the lead's too: they show up in its files, diffs and Ship it.
+        const lead = session.parentId && this.store.get(session.parentId);
+        const leadTurn = lead?.turns.at(-1);
+        if (leadTurn?.status === 'running') this.#onEvent(lead, leadTurn, { ...ev, by: session.member });
         return;
       }
       case 'result':
@@ -336,15 +473,18 @@ export class Runner extends EventEmitter {
       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;
+      // Compare runs keep the prompt's title: they're one task, and one run's headline shouldn't name it.
+      if (hero?.title && session.titleAuto && session.turns.length === 1 && !session.groupId) session.title = hero.title;
     }
     session.state = 'review';
     session.unread = !interrupted;
     this.store.save(session, { now: true });
     this.#touch(session, { turn: turn.id });
     this.emit('ended', { session, turn, interrupted, errorText: ev.isError && !ev.stopped ? ev.text : '' });
-    // The follow-up starts right away; don't notify for the run it replaced.
-    if (!interrupted) this.emit('finished', { session: summarize(session, this.store) });
+    this.#touchLead(session);
+    // The follow-up starts right away; don't notify for the run it replaced. A subagent reports
+    // to its lead, not to the user.
+    if (!interrupted && !session.parentId) this.emit('finished', { session: summarize(session, this.store) });
   }
 
   #touch(session, { turn, quiet } = {}) {

package/server/store.js

@@ -9,6 +9,10 @@ import { parsePresentation } from './protocol.js';
 const DEFAULT_CONFIG = {
   projects: [], // [{ id, name, path, color, addedAt }]
   defaults: { agent: 'claude', mode: 'edits', model: '', effort: '' },
+  recipes: [], // saved prompts with {params}: server/recipes.js
+  triggers: [], // schedules and GitHub watchers: server/triggers.js
+  teams: [], // saved subagent presets: server/subagents.js
+  remote: {}, // phone channels (ntfy, Telegram): server/remote.js
 };
 
 const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg']);
@@ -47,6 +51,10 @@ export class Store {
       const raw = JSON.parse(fs.readFileSync(path.join(this.home, 'config.json'), 'utf8'));
       const cfg = { ...structuredClone(DEFAULT_CONFIG), ...raw, defaults: { ...DEFAULT_CONFIG.defaults, ...raw.defaults } };
       cfg.projects ||= [];
+      cfg.recipes ||= [];
+      cfg.triggers ||= [];
+      cfg.teams ||= [];
+      cfg.remote ||= {};
       return cfg;
     } catch {
       return structuredClone(DEFAULT_CONFIG);
@@ -130,7 +138,7 @@ export class Store {
     (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 src = path.resolve(session.worktree?.cwd || session.cwd || this.home, rel);
       const ext = path.extname(src).toLowerCase();
       if (!IMAGE_EXT.has(ext) || src.startsWith(this.shots + path.sep)) return;
       try {

package/server/subagents.js

@@ -0,0 +1,85 @@
+// Subagents: a team the user picks at launch (any harness, model and thinking level each) that
+// the lead agent can hand work to through wisp's injected `delegate` tool. Each member is a
+// hidden child session working in the lead's folder; delegating to it again resumes it.
+
+import { blocksToMarkdown } from './render.js';
+
+export const MAX_SUBAGENTS = 6; // rows in the team
+export const MAX_COPIES = 5; // parallel copies of one row
+export const MAX_INSTANCES = 12; // copies across the whole team
+const EFFORT = /^[\w-]{1,20}$/;
+const MAX_USE = 300;
+const slug = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24);
+
+// [{ name?, agent, model?, effort?, use?, count? }] → a clean roster with unique names (codex, codex-2, …).
+// use: the user's note on when to pick this one ("image work", "research"), shown to the lead.
+// count: how many parallel copies of this member the lead gets (codex#1, codex#2, …).
+export function normalizeTeam(list, adapters) {
+  if (!Array.isArray(list)) return [];
+  const taken = new Set();
+  const team = list.slice(0, MAX_SUBAGENTS).map((m) => {
+    const agent = String(m?.agent || '');
+    if (!adapters[agent] || agent === 'wisp') throw Object.assign(new Error(`unknown subagent harness: ${agent}`), { status: 400 });
+    let base = slug(m.name) || agent;
+    let name = base;
+    for (let i = 2; taken.has(name); i++) name = `${base}-${i}`;
+    taken.add(name);
+    const use = String(m.use || '').replace(/\s+/g, ' ').trim().slice(0, MAX_USE);
+    const count = Math.min(MAX_COPIES, Math.max(1, Math.floor(Number(m.count)) || 1));
+    return { name, agent, model: typeof m.model === 'string' ? m.model.slice(0, 120) : '', effort: EFFORT.test(m.effort || '') ? m.effort : '', use, count };
+  });
+  const total = team.reduce((n, m) => n + m.count, 0);
+  if (total > MAX_INSTANCES) throw Object.assign(new Error(`At most ${MAX_INSTANCES} subagents in all (this team has ${total}).`), { status: 400 });
+  return team;
+}
+
+// The sessions a member runs as: itself, or one per copy (`#` can't appear in a name, so no clashes).
+export const copies = (m) => ((m.count || 1) > 1 ? Array.from({ length: m.count }, (_, i) => `${m.name}#${i + 1}`) : [m.name]);
+
+// Saved teams the user can reuse from the launcher: { id, name, members }.
+export function normalizePreset(body, adapters, prev = {}) {
+  const name = String(body?.name ?? prev.name ?? '').trim().slice(0, 60);
+  if (!name) throw Object.assign(new Error('A preset needs a name.'), { status: 400 });
+  const members = body?.members !== undefined ? normalizeTeam(body.members, adapters) : prev.members || [];
+  if (!members.length) throw Object.assign(new Error('A preset needs at least one subagent.'), { status: 400 });
+  return { id: prev.id || slug(name) + '-' + Math.random().toString(36).slice(2, 6), name, members, updatedAt: Date.now() };
+}
+
+const who = (m, adapters) => [adapters[m.agent]?.name || m.agent, m.model || 'default model', m.effort && `${m.effort} thinking`].filter(Boolean).join(' · ');
+
+// Appended to the lead's system prompt. `tool` is how its harness names the delegate tool.
+export function teamNote(team, adapters, tool) {
+  if (!team?.length || !tool) return '';
+  const rows = team
+    .map((m) => `- \`${m.name}\`${m.count > 1 ? ` ×${m.count} (copies ${copies(m).map((c) => `\`${c}\``).join(', ')})` : ''}: ${who(m, adapters)}${m.use ? `. Use it for: ${m.use}` : ''}`)
+    .join('\n');
+  const multi = team.find((m) => m.count > 1);
+  return `\n\n## Subagents
+
+The user gave you a team of subagents, each a separate coding agent running on its own harness and model:
+
+${rows}
+
+Hand them work with the \`delegate\` tool (${tool}): pass one or more tasks, \`{ "subagent": "<name>", "prompt": "…" }\`. Tasks in one call run in parallel and the call returns when all of them finish, with each subagent's report and the files it changed. With \`wait: false\` it returns at once; collect the reports later with \`subagent_results\`. Delegating to the same subagent again continues its conversation, so it remembers earlier tasks.
+
+${multi ? `- A subagent with ×N has N identical copies that run at once. Put several tasks for \`${multi.name}\` in one delegate call and each goes to a free copy; name a copy (\`${copies(multi)[1]}\`) to continue that copy's conversation.\n` : ''}- Subagents work in your folder and see each other's edits. Give parallel subagents separate files or concerns.
+- Brief them like a colleague: goal, files, constraints, how to verify. They cannot see your conversation or ask the user.
+- Follow the user's "use it for" notes when you pick a subagent: send each kind of work to the one meant for it.
+- Use them when the user's request calls for it or when the work splits cleanly; you stay responsible for the result. Review what they changed before you report.
+- Your presentation covers the whole task; wisp shows each subagent's report next to it, so don't repeat them in full.`;
+}
+
+// Replaces the ask_user guidance for a subagent's own system prompt.
+export const SUBAGENT_ASK = `- You are a subagent: a lead agent delegated this task to you and will read your presentation.
+  You cannot ask the user anything. Make the call yourself, note the assumption in a "callout"
+  block, and finish. Don't commit unless the task says to.`;
+
+// What the lead gets back for one delegation.
+export function delegationReport(d, child, adapters) {
+  const turn = child?.turns.find((t) => t.id === d.turnId);
+  const head = `### ${d.name} (${who(d, adapters)}) — ${turn?.status || 'gone'}`;
+  if (!turn) return `${head}\n\nThe subagent session is gone.`;
+  if (turn.status === 'running') return `${head}\n\nStill working. Call subagent_results to wait for it.`;
+  const files = turn.changes.length ? `\n\nFiles it changed: ${turn.changes.map((c) => `\`${c.file}\``).join(', ')}` : '';
+  return `${head}\n\n${blocksToMarkdown(turn.presentation?.blocks || [], turn).trim() || '_No report._'}${files}`;
+}