wisp-agents 0.6.0 → 0.8.0

package/server/protocol.js

@@ -42,6 +42,13 @@ diff, the test run, the command output — over prose. Use file paths relative t
   A test/lint/type-check run you actually executed. Prefer this over "terminal" for test runs.
 - {"type":"commits","items":[{"hash":"a1b2c3d","message":"feat(auth): add rate limiter","files":3,"additions":120,"deletions":8}],"branch":"feat/limit"}
   Commits you created, if any.
+- {"type":"graph","title":"Refresh sessions in auth","ref":"#128","state":"open|draft|merged|closed","into":"main","merge":"conflict|ready|merged|blocked|pending",
+   "commits":[{"hash":"d29f50","message":"Add refresh tests","branch":"feat/refresh","author":"You","when":"now"},{"hash":"5be27d","message":"Rotate keys","branch":"main","author":"Lena","when":"6m","conflict":true}],
+   "conflicts":[{"file":"src/auth.ts","line":42,"commit":"5be27d","detail":"Both sides rewrote getSession()","ours":"refresh(token)","theirs":"rotate(key)","resolution":"Rotate first, then refresh"}],
+   "checks":[{"label":"Tests","value":"42 passed","status":"pass|fail|pending"}],"action":{"label":"Resolve conflicts","reply":"Merge main in and resolve the conflicts"}}
+  Branch graph, newest commit first; each commit's "branch" gives its lane ("into" is the base lane).
+  Use it to explain merge conflicts, a rebase, or where branches diverged. Mark the base commits that
+  conflict with "conflict":true; optional "parents":[hash,…] for merge commits.
 - {"type":"tree","title":"…","items":[{"path":"src/auth/limiter.ts","change":"added","note":"…"}]}
   A file tree; use for new modules/scaffolding where structure matters.
 - {"type":"code","language":"ts","code":"…","caption":"…","file":"src/a.ts","line":10,"highlight":[3,4]}
@@ -58,6 +65,8 @@ diff, the test run, the command output — over prose. Use file paths relative t
   A screenshot or generated image on disk.
 - {"type":"question","question":"…","options":[{"label":"Short choice","reply":"full message sent back to you"}]}
   When you need a decision. The user's click resumes you with the reply.
+- {"type":"actions","title":"…","items":[{"label":"Run tests","command":"npm test"},{"label":"Follow up","reply":"…"}]}
+  One-click shell commands (executed in the project root) or follow-up actions the user may want to trigger.
 - {"type":"next","items":["Suggested follow-up the user might send", "…"]}
   Usually last. 2–4 concrete follow-ups.
 
@@ -82,7 +91,8 @@ const ASK_BLOCK = `- If a decision would change the rest of the work (ambiguous
   The user's answer comes back as a follow-up in this same session.`;
 
 // askTool: how the harness names wisp's injected ask_user tool, or null if it can't take one.
-export const systemPrompt = ({ askTool = 'mcp__wisp__ask_user' } = {}) => PROTOCOL.replace('{{ASK}}', askTool ? ASK_TOOL(askTool) : ASK_BLOCK);
+// ask: replaces the ask guidance outright (subagents, who have nobody to ask).
+export const systemPrompt = ({ askTool = 'mcp__wisp__ask_user', ask } = {}) => PROTOCOL.replace('{{ASK}}', ask || (askTool ? ASK_TOOL(askTool) : ASK_BLOCK));
 export const SYSTEM_PROMPT = systemPrompt();
 
 // Only the opener is matched by regex. The closing fence can't be: the JSON itself often

package/server/recipes.js

@@ -0,0 +1,64 @@
+// Recipes: saved prompts for tasks you send again and again. `{name}` in the prompt is a
+// parameter, filled in when the recipe runs (the run dialog, `wisp run release 0.8.0`, a trigger).
+
+import path from 'node:path';
+import { newId } from './runner.js';
+
+const PARAM = /\{([a-zA-Z][\w-]{0,30})\}/g;
+const MODES = new Set(['plan', 'edits', 'auto']);
+
+export const params = (prompt) => [...new Set([...String(prompt || '').matchAll(PARAM)].map((m) => m[1]))];
+
+// strict: every parameter needs a value (a person ran it). Otherwise unknown ones become ''
+// (a trigger filling in an empty issue body). Values are inserted once, never re-expanded.
+export function fill(prompt, values = {}, { strict = true } = {}) {
+  const has = (k) => values[k] !== undefined && values[k] !== null && String(values[k]).trim() !== '';
+  const missing = params(prompt).filter((k) => !has(k));
+  if (strict && missing.length) throw Object.assign(new Error(`Missing ${missing.map((k) => `{${k}}`).join(', ')}`), { status: 400 });
+  return String(prompt).replace(PARAM, (_, k) => (has(k) ? String(values[k]) : ''));
+}
+
+// Fill positional CLI words into the parameters in the order they appear.
+export function positional(prompt, words = []) {
+  const out = {};
+  params(prompt).forEach((k, i) => words[i] !== undefined && (out[k] = words[i]));
+  return out;
+}
+
+const bad = (msg) => Object.assign(new Error(msg), { status: 400 });
+
+export function normalizeRecipe(body, prev = null) {
+  const name = String(body.name ?? prev?.name ?? '').trim().slice(0, 60);
+  const prompt = String(body.prompt ?? prev?.prompt ?? '').trim();
+  if (!name) throw bad('A recipe needs a name.');
+  if (!prompt) throw bad('A recipe needs a prompt.');
+  const cwd = body.cwd !== undefined ? String(body.cwd || '') : prev?.cwd || '';
+  if (cwd && !path.isAbsolute(cwd)) throw bad('cwd must be an absolute project path (or empty for any project).');
+  const mode = body.mode ?? prev?.mode ?? '';
+  if (mode && !MODES.has(mode)) throw bad('mode must be plan, edits or auto.');
+  const pick = (k) => String(body[k] ?? prev?.[k] ?? '');
+  return {
+    id: prev?.id || newId(),
+    name,
+    prompt,
+    cwd, // '' = whichever project it's run in
+    agent: pick('agent'),
+    model: pick('model'),
+    effort: /^[\w-]{0,20}$/.test(pick('effort')) ? pick('effort') : '',
+    mode,
+    createdAt: prev?.createdAt || Date.now(),
+    updatedAt: Date.now(),
+    runs: prev?.runs || 0,
+    lastRunAt: prev?.lastRunAt || null,
+  };
+}
+
+// By id, else by name (case- and punctuation-insensitive), so `wisp run "Release"` and
+// `wisp run release` both work.
+export function findRecipe(recipes, key) {
+  const k = String(key || '');
+  const loose = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '');
+  return recipes.find((r) => r.id === k) || recipes.find((r) => loose(r.name) === loose(k)) || null;
+}
+
+export const recipeView = (r) => ({ ...r, params: params(r.prompt) });

package/server/remote.js

@@ -0,0 +1,279 @@
+// Phone: push "needs you" moments to ntfy or Telegram and take the answers back. Both run on
+// outbound connections only (wisp polls them), so nothing has to reach this machine.
+//
+//   ntfy      notification with up to 3 buttons. A tap makes the ntfy app POST a signed answer to
+//             <topic>-reply, which wisp polls. No free text (ntfy has no reply box).
+//   Telegram  a bot message with buttons; reply to the message to answer in your own words or
+//             send a follow-up. Linked to one chat with a one-time code.
+
+import { createHmac, randomBytes, randomInt, timingSafeEqual } from 'node:crypto';
+
+const KIND = { a: 'answer', r: 'reply', d: 'done' };
+const CODE = { answer: 'a', reply: 'r', done: 'd' };
+const MAX_TG_IDS = 20;
+const sleep = (ms, signal) => new Promise((r) => (signal?.aborted ? r() : (setTimeout(r, ms).unref?.(), signal?.addEventListener('abort', r, { once: true }))));
+const clip = (s, n) => (String(s || '').length > n ? `${String(s).slice(0, n - 1)}…` : String(s || ''));
+export const mask = (t) => (t ? `••••${String(t).slice(-4)}` : '');
+
+export class Remote {
+  // act({ sessionId, kind: answer|reply|done|text, ref, index, text }) → a short result line.
+  constructor({ store, act, onChange = () => {} }) {
+    Object.assign(this, { store, act, onChange });
+    this.status = { ntfy: null, telegram: null };
+    this.ac = null;
+    this.ntfyPollMs = 4000;
+    this.tgLongPoll = 25;
+  }
+
+  get cfg() {
+    return (this.store.config.remote ||= {});
+  }
+
+  get secret() {
+    if (!this.cfg.secret) {
+      this.cfg.secret = randomBytes(16).toString('hex');
+      this.store.saveConfig();
+    }
+    return this.cfg.secret;
+  }
+
+  get on() {
+    const c = this.cfg;
+    return !!((c.ntfy?.enabled && c.ntfy.topic) || (c.telegram?.enabled && c.telegram.token));
+  }
+
+  start() {
+    this.stop();
+    const ac = (this.ac = new AbortController());
+    const c = this.cfg;
+    if (c.ntfy?.enabled && c.ntfy.topic) this.#ntfyLoop(ac.signal);
+    if (c.telegram?.enabled && c.telegram.token) {
+      if (!c.telegram.chatId && !c.telegram.linkCode) (c.telegram.linkCode = String(randomInt(100000, 999999))), this.store.saveConfig();
+      this.#tgLoop(ac.signal);
+    }
+  }
+
+  stop() {
+    this.ac?.abort();
+    this.ac = null;
+  }
+
+  // What the phone gets for a session that needs you, and the buttons under it.
+  message(s, summary) {
+    const where = `${summary?.project || ''}: ${s.title}`;
+    if (s.ask) {
+      return {
+        title: `❓ ${where}`,
+        text: [s.ask.question, s.ask.context && clip(s.ask.context, 600)].filter(Boolean).join('\n\n'),
+        actions: (s.ask.options || []).map((label, index) => ({ label, kind: 'answer', ref: s.ask.id, index })),
+      };
+    }
+    const turn = s.turns.at(-1);
+    const blocks = turn?.presentation?.blocks || [];
+    const hero = blocks.find((b) => b?.type === 'hero');
+    const q = blocks.findLast((b) => b?.type === 'question');
+    const icon = { done: '✅', partial: '🟡', blocked: '⛔' }[hero?.status] || (turn?.status === 'error' ? '⛔' : '📝');
+    const options = (q?.options || []).map((o) => (typeof o === 'string' ? { label: o } : o));
+    return {
+      title: `${icon} ${where}`,
+      text: [hero?.title && hero.title !== s.title ? hero.title : '', hero?.summary || summary?.preview || 'Ready for review.', q?.question].filter(Boolean).join('\n\n'),
+      actions: options.length ? options.map((o, index) => ({ label: o.label || String(o.reply || ''), kind: 'reply', ref: turn.id, index })) : [{ label: 'Mark done', kind: 'done', ref: turn?.id || '', index: 0 }],
+    };
+  }
+
+  async notify(s, summary) {
+    if (!this.on || !s || s.agent === 'wisp') return;
+    const event = s.state === 'waiting' ? 'waiting' : 'finished';
+    if (!(this.cfg.events || ['waiting', 'finished']).includes(event)) return;
+    await this.send(this.message(s, summary), s);
+  }
+
+  async send(msg, s = null) {
+    const c = this.cfg;
+    const jobs = [];
+    if (c.ntfy?.enabled && c.ntfy.topic) jobs.push(this.#ntfyPublish(msg, s).then(() => this.#mark('ntfy', { ok: true }), (e) => this.#mark('ntfy', { ok: false, error: e.message })));
+    if (c.telegram?.enabled && c.telegram.token && c.telegram.chatId) jobs.push(this.#tgPublish(msg, s).then(() => this.#mark('telegram', { ok: true }), (e) => this.#mark('telegram', { ok: false, error: e.message })));
+    await Promise.all(jobs);
+    return jobs.length;
+  }
+
+  #mark(channel, st) {
+    this.status[channel] = { ...this.status[channel], ...st, at: Date.now() };
+    this.onChange();
+  }
+
+  // --- answers: signed, so a stranger who guesses the topic can't steer your agents ------------
+
+  sign(sessionId, kind, ref, index) {
+    return createHmac('sha256', this.secret).update(`${sessionId}.${kind}.${ref}.${index}`).digest('base64url').slice(0, 22);
+  }
+
+  verify(p) {
+    if (!p || typeof p !== 'object' || !KIND[p.k] || typeof p.sig !== 'string') return false;
+    const want = Buffer.from(this.sign(p.s, KIND[p.k], p.r, p.i));
+    const got = Buffer.from(p.sig);
+    return want.length === got.length && timingSafeEqual(want, got);
+  }
+
+  // --- ntfy ------------------------------------------------------------------------------------
+
+  #ntfy() {
+    const n = this.cfg.ntfy;
+    const server = String(n.server || 'https://ntfy.sh').replace(/\/+$/, '');
+    return { server, topic: n.topic, headers: n.token ? { authorization: `Bearer ${n.token}` } : {} };
+  }
+
+  async #ntfyPublish(msg, s) {
+    const { server, topic, headers } = this.#ntfy();
+    const actions = (s ? msg.actions : []).slice(0, 3).map((a) => {
+      const k = CODE[a.kind];
+      return { action: 'http', label: clip(a.label, 40), url: `${server}/${topic}-reply`, method: 'POST', headers, body: JSON.stringify({ s: s.id, k, r: a.ref, i: a.index, sig: this.sign(s.id, a.kind, a.ref, a.index) }), clear: true };
+    });
+    const r = await fetch(server, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...headers },
+      body: JSON.stringify({ topic, title: clip(msg.title, 200), message: clip(msg.text, 3000), tags: ['wisp'], ...(actions.length && { actions }) }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!r.ok) throw new Error(`ntfy: ${r.status} ${(await r.text().catch(() => '')).slice(0, 120)}`);
+  }
+
+  async #ntfyLoop(signal) {
+    let since = String(Math.floor(Date.now() / 1000));
+    while (!signal.aborted) {
+      try {
+        const { server, topic, headers } = this.#ntfy();
+        const r = await fetch(`${server}/${topic}-reply/json?poll=1&since=${since}`, { headers, signal });
+        if (!r.ok) throw new Error(`ntfy: ${r.status}`);
+        for (const line of (await r.text()).split('\n')) {
+          if (!line.trim()) continue;
+          const m = JSON.parse(line);
+          if (m.id) since = m.id;
+          if (m.event !== 'message') continue;
+          let p = null;
+          try {
+            p = JSON.parse(m.message);
+          } catch {}
+          if (!this.verify(p)) continue; // not ours, or forged
+          await this.act({ sessionId: p.s, kind: KIND[p.k], ref: p.r, index: Number(p.i) }).catch(() => {});
+        }
+        if (this.status.ntfy?.error) this.#mark('ntfy', { ok: true, error: '' });
+      } catch (err) {
+        if (signal.aborted) return;
+        this.#mark('ntfy', { ok: false, error: err.message });
+      }
+      await sleep(this.ntfyPollMs, signal);
+    }
+  }
+
+  // --- Telegram --------------------------------------------------------------------------------
+
+  async #tg(method, body, signal) {
+    const base = (process.env.WISP_TELEGRAM_API || 'https://api.telegram.org').replace(/\/+$/, '');
+    const r = await fetch(`${base}/bot${this.cfg.telegram.token}/${method}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: signal || AbortSignal.timeout(15_000),
+    });
+    const j = await r.json().catch(() => ({}));
+    if (!j.ok) throw new Error(`Telegram: ${j.description || r.status}`);
+    return j.result;
+  }
+
+  async #tgPublish(msg, s) {
+    const buttons = (s ? msg.actions : []).map((a) => [{ text: clip(a.label, 60), callback_data: `${CODE[a.kind]}:${s.id}:${a.ref}:${a.index}` }]);
+    const sent = await this.#tg('sendMessage', {
+      chat_id: this.cfg.telegram.chatId,
+      text: clip(`${msg.title}\n\n${msg.text}${s ? '\n\n↩ Reply to this message to answer or follow up.' : ''}`, 4000),
+      ...(buttons.length && { reply_markup: { inline_keyboard: buttons } }),
+    });
+    if (s && sent?.message_id) {
+      s.remote = { ...s.remote, tg: [...(s.remote?.tg || []), sent.message_id].slice(-MAX_TG_IDS) };
+      this.store.save(s);
+    }
+  }
+
+  async #tgLoop(signal) {
+    let offset = 0;
+    while (!signal.aborted) {
+      try {
+        const updates = await this.#tg('getUpdates', { offset, timeout: this.tgLongPoll, allowed_updates: ['message', 'callback_query'] }, signal);
+        if (this.status.telegram?.error) this.#mark('telegram', { ok: true, error: '' });
+        for (const u of updates) {
+          offset = u.update_id + 1;
+          await this.#fromTelegram(u).catch((err) => console.warn(`wisp: telegram: ${err.message}`));
+        }
+      } catch (err) {
+        if (signal.aborted) return;
+        this.#mark('telegram', { ok: false, error: err.message });
+        await sleep(5000, signal);
+      }
+    }
+  }
+
+  async #fromTelegram(u) {
+    const t = this.cfg.telegram;
+    const say = (text, extra = {}) => this.#tg('sendMessage', { chat_id: t.chatId, text, ...extra });
+    if (u.callback_query) {
+      const q = u.callback_query;
+      if (!t.chatId || String(q.message?.chat?.id) !== String(t.chatId)) return;
+      const [k, sessionId, ref, i] = String(q.data || '').split(':');
+      const result = KIND[k] ? await this.act({ sessionId, kind: KIND[k], ref, index: Number(i) }) : 'Unknown button.';
+      await this.#tg('answerCallbackQuery', { callback_query_id: q.id, text: clip(result, 190) }).catch(() => {});
+      await this.#tg('editMessageReplyMarkup', { chat_id: t.chatId, message_id: q.message.message_id, reply_markup: { inline_keyboard: [] } }).catch(() => {});
+      return;
+    }
+    const m = u.message;
+    if (!m?.text) return;
+    if (!t.chatId) {
+      // Linking: only the chat that sends the code shown in wisp's settings gets attached.
+      if (t.linkCode && m.text.replace(/^\/(start|link)\s*/, '').trim() === t.linkCode) {
+        Object.assign(t, { chatId: m.chat.id, chatName: m.chat.title || [m.chat.first_name, m.chat.last_name].filter(Boolean).join(' ') || m.chat.username || '', linkCode: '' });
+        this.store.saveConfig();
+        this.#mark('telegram', { ok: true, error: '' });
+        await say('✓ Linked to wisp. Questions and finished tasks will show up here.');
+      }
+      return;
+    }
+    if (String(m.chat.id) !== String(t.chatId)) return;
+    const replyTo = m.reply_to_message?.message_id;
+    const s = replyTo && this.store.all().find((x) => x.remote?.tg?.includes(replyTo));
+    if (!s) return say('Reply to one of wisp’s messages to answer it or send a follow-up.');
+    await say(await this.act({ sessionId: s.id, kind: 'text', text: m.text }), { reply_to_message_id: m.message_id });
+  }
+
+  // For the settings view: config with secrets masked, plus channel health.
+  view() {
+    const c = this.cfg;
+    return {
+      events: c.events || ['waiting', 'finished'],
+      ntfy: { enabled: !!c.ntfy?.enabled, server: c.ntfy?.server || 'https://ntfy.sh', topic: c.ntfy?.topic || '', token: mask(c.ntfy?.token) },
+      telegram: { enabled: !!c.telegram?.enabled, token: mask(c.telegram?.token), linked: !!c.telegram?.chatId, chatName: c.telegram?.chatName || '', linkCode: c.telegram?.chatId ? '' : c.telegram?.linkCode || '' },
+      status: this.status,
+    };
+  }
+
+  // PUT body: { events, ntfy: {…}, telegram: {…, unlink} }. Masked tokens mean "unchanged".
+  update(body = {}) {
+    const c = this.cfg;
+    const keep = (v, prev) => (typeof v === 'string' && v.startsWith('••••') ? prev : v);
+    if (Array.isArray(body.events)) c.events = body.events.filter((e) => e === 'waiting' || e === 'finished');
+    if (body.ntfy) {
+      const n = { ...c.ntfy, ...body.ntfy };
+      n.token = keep(body.ntfy.token, c.ntfy?.token) || '';
+      if (n.server && !/^https?:\/\/\S+$/.test(n.server)) throw Object.assign(new Error('ntfy server must be an http(s) URL'), { status: 400 });
+      if (n.topic && !/^[\w-]{1,64}$/.test(n.topic)) throw Object.assign(new Error('ntfy topic: letters, digits, - and _ only'), { status: 400 });
+      c.ntfy = { enabled: !!n.enabled, server: n.server || 'https://ntfy.sh', topic: n.topic || '', token: n.token };
+    }
+    if (body.telegram) {
+      const prev = c.telegram || {};
+      const token = keep(body.telegram.token, prev.token) || '';
+      const relink = body.telegram.unlink || token !== prev.token;
+      c.telegram = { ...prev, enabled: !!(body.telegram.enabled ?? prev.enabled), token, ...(relink && { chatId: null, chatName: '', linkCode: token ? String(randomInt(100000, 999999)) : '' }) };
+    }
+    this.store.saveConfig();
+    this.start();
+    return this.view();
+  }
+}

package/server/render.js

@@ -55,6 +55,18 @@ const R = {
     `${b.branch ? `**Branch** \`${b.branch}\`\n\n` : ''}${list(b.items)
       .map((c) => `- \`${str(c.hash).slice(0, 7)}\` ${str(c.message)}${c.additions !== undefined ? ` (+${c.additions}/−${c.deletions ?? 0})` : ''}`)
       .join('\n')}`,
+  graph: (b) => {
+    const head = `**${str(b.title) || 'Branches'}**${b.ref ? ` ${b.ref}` : ''}${b.state ? ` · ${b.state}` : ''}${b.into ? ` → \`${b.into}\`${b.merge ? ` (${b.merge})` : ''}` : ''}`;
+    const commits = list(b.commits).map((c) => `- ${c.conflict ? '⚠️ ' : ''}\`${str(c.hash).slice(0, 7)}\` ${str(c.message)}${c.branch ? ` [${c.branch}]` : ''}${c.author ? ` — ${c.author}${c.when ? `, ${c.when}` : ''}` : ''}`);
+    const conflicts = list(b.conflicts).map((c, i) => {
+      const o = typeof c === 'string' ? { file: c } : c || {};
+      return `${i + 1}. \`${str(o.file)}${o.line || o.lines ? `:${o.line || o.lines}` : ''}\`${o.detail ? ` — ${o.detail}` : ''}${o.ours ? `\n   - ours: \`${o.ours}\`` : ''}${o.theirs ? `\n   - theirs: \`${o.theirs}\`` : ''}${o.resolution ? `\n   - ✔︎ ${o.resolution}` : ''}`;
+    });
+    const checks = list(b.checks).map((c) => `${c.status === 'fail' ? '❌' : c.status === 'pending' ? '⏳' : '✅'} ${str(c.label || c)}${c.value ? ` ${c.value}` : ''}`);
+    return [head, commits.join('\n'), conflicts.length ? `**Conflicts**\n${conflicts.join('\n')}` : '', checks.join(' · '), b.summary ? str(b.summary) : '']
+      .filter(Boolean)
+      .join('\n\n');
+  },
   terminal: (b) => fence(`$ ${str(b.command)}\n${str(b.output)}${b.exitCode !== undefined && b.exitCode !== 0 ? `\n[exit ${b.exitCode}]` : ''}`, 'console'),
   compare: (b) => ['before', 'after'].map((k) => `**${str(b[k]?.label) || (k === 'before' ? 'Before' : 'After')}**\n${list(b[k]?.items).map((i) => `- ${str(i)}`).join('\n')}`).join('\n\n'),
   flow: (b) => {
@@ -68,6 +80,10 @@ const R = {
   callout: (b) => `> **${b.tone === 'danger' ? '⛔' : b.tone === 'warn' ? '⚠️' : b.tone === 'success' ? '✅' : 'ℹ️'} ${str(b.title)}**\n> ${str(b.text).replace(/\n/g, '\n> ')}`,
   image: (b) => `🖼️ \`${str(b.path || b.src)}\`${b.caption ? ` — ${b.caption}` : ''}`,
   question: (b) => `**❓ ${str(b.question)}**\n${list(b.options).map((o, i) => `${i + 1}. ${str(o.label || o)}`).join('\n')}`,
+  actions: (b) =>
+    `${b.title ? `**${b.title}**\n` : '**Actions**\n'}${list(b.items)
+      .map((a) => (typeof a === 'string' ? `- ${a}` : `- **${str(a.label || a.command)}**${a.command ? ` — \`$ ${str(a.command)}\`` : a.reply ? ` — _${str(a.reply)}_` : ''}${a.detail ? ` (${str(a.detail)})` : ''}`))
+      .join('\n')}`,
   next: (b) => `**Next**\n${list(b.items).map((i) => `- ${str(i)}`).join('\n')}`,
 };
 
@@ -96,5 +112,7 @@ export function sessionToMarkdown(session) {
     out.push(`**❓ The agent is waiting for your answer:** ${session.ask.question}${session.ask.context ? `\n\n${session.ask.context}` : ''}`);
     if (session.ask.options?.length) out.push(session.ask.options.map((o, i) => `${i + 1}. ${o}`).join('\n'));
   }
+  // Worktree sessions: say where the changes are, since they aren't in the caller's checkout.
+  if (session.worktree && turn?.status !== 'running') out.push(`_Changes are on branch \`${session.worktree.branch}\` in the worktree \`${session.worktree.path}\`${session.pr ? ` · PR #${session.pr.number} (${String(session.pr.state).toLowerCase()}): ${session.pr.url}` : ''}._`);
   return out.join('\n\n');
 }