wisp-agents 0.24.0 → 0.25.0

package/server/routes/internal.js

@@ -9,6 +9,9 @@ import { summarize } from '../runner.js';
 import { delegationReport } from '../subagents.js';
 import { toolStats, toolStatsText } from '../usage.js';
 import { clip } from '../util.js';
+import { describeSpell, normalizeSpell } from '../spells.js';
+import { spellReference } from '../spell-guide.js';
+import { ghProblem, wispPathProblem } from '../../web/js/spell-schema.js';
 
 export function register(r, app) {
   const { store, runner, telemetry } = app;
@@ -76,6 +79,64 @@ export function register(r, app) {
     opts,
   );
 
+  // Cast a spell: the tools a spell task writes its spell with. Only that task's token works.
+  const spellTask = (fn) =>
+    guarded(async (c) => {
+      const s = lead(c);
+      if (!s) return c.send(404, { error: 'no such session' });
+      if (s.kind !== 'spell') return c.send(403, { error: 'only a Cast a spell task can use this' });
+      return fn(c, s);
+    });
+  r.route(
+    'GET',
+    '/internal/spells/:id',
+    spellTask((c) => {
+      const { spells } = app.spells.list();
+      const one = (x) => [`### ${x.name} (\`${x.id}\` v${x.version}, ${x.enabled ? 'on' : 'off'})`, ...x.summary.map((l) => `- ${l}`), '', '```json', JSON.stringify(app.spells.exported(x.id), null, 2), '```'].join('\n');
+      const text = spells.length ? spells.map(one).join('\n\n') : 'The user has no spells yet.';
+      c.send(200, { text });
+    }),
+    opts,
+  );
+  r.route('GET', '/internal/spell-schema/:id', spellTask((c) => c.send(200, { text: JSON.stringify(spellReference(), null, 1) })), opts);
+  r.route(
+    'POST',
+    '/internal/spell-data/:id',
+    spellTask(async (c) => {
+      const { source, task } = await c.body();
+      const src = source && typeof source === 'object' ? source : {};
+      const problem = src.wisp !== undefined ? wispPathProblem(src.wisp) : src.gh !== undefined ? ghProblem(src.gh) : 'source is { "wisp": "/path" } or { "gh": [args] }';
+      if (problem) return c.send(200, { text: `Not allowed: ${problem}` });
+      const session = task ? store.get(String(task)) : null;
+      try {
+        const value = await app.spellData.get(`check-${c.params.id}`, 'sample', { ...src, refresh: 10 }, { session, summary: session ? summarize(session, store) : null, fresh: true });
+        const json = JSON.stringify(value, null, 1);
+        c.send(200, { text: json.length > 12_000 ? `${json.slice(0, 12_000)}\n… (cut; ${json.length} characters in all)` : json });
+      } catch (err) {
+        c.send(200, { text: `The source failed: ${err.message}` });
+      }
+    }),
+    opts,
+  );
+  r.route(
+    'POST',
+    '/internal/spell-check/:id',
+    spellTask(async (c) => {
+      const { spell } = await c.body();
+      try {
+        const { spell: n, warnings } = normalizeSpell(spell);
+        const d = describeSpell(n);
+        const was = app.spells.get(n.id);
+        c.send(200, {
+          text: [`ok — “${n.name}” (${d.kind}) would:`, ...d.lines.map((l) => `- ${l}`), ...(warnings.length ? ['', 'Warnings:', ...warnings.map((w) => `- ${w}`)] : []), ...(was ? ['', `The user already has \`${n.id}\` v${was.version}; yours replaces it${n.version === was.version ? ' (bump version)' : ''}.`] : []), '', 'End your report with {"type":"spell","spell":{…}} holding exactly this spell.'].join('\n'),
+        });
+      } catch (err) {
+        c.send(200, { text: err.problems ? `Not ok. Fix:\n${err.problems.map((p) => `- ${p}`).join('\n')}` : `Not ok: ${err.message}` });
+      }
+    }),
+    opts,
+  );
+
   // wisp_stats: read-only tool counts, spend and success across sessions. project=current is the
   // asking session's project.
   r.route(

package/server/routes/meta.js

@@ -4,7 +4,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { openapi } from '../openapi.js';
-import { usage } from '../usage.js';
+import { toolStats, usage } from '../usage.js';
 import { expandHome, VERSION } from '../util.js';
 
 export const API_VERSION = 1;
@@ -70,6 +70,10 @@ export function register(r, app) {
 
   // Spend and outcomes. ?days=7|30|90
   r.route('GET', '/usage', (c) => c.send(200, usage(store.all(), { days: Number(c.query.get('days')) || 30, project: (s) => store.projectFor(s.cwd) })));
+  // Tool calls by kind, harness, project and day (what wisp_stats tells agents).
+  r.route('GET', '/usage/tools', (c) =>
+    c.send(200, toolStats(store.all(), { days: Math.min(Math.max(Number(c.query.get('days')) || 30, 1), 365), project: (s) => store.projectFor(s.cwd), filter: { agent: c.query.get('agent') || '', project: c.query.get('project') || '' } })),
+  );
 
   // Feedback for the wisp team: thumbs on a turn and/or a note. { rating?, text?, sessionId?, turnId? }
   r.route('POST', '/feedback', async (c) => c.send(200, await app.sendFeedback(await c.body())));

package/server/routes/settings.js

@@ -18,19 +18,33 @@ export { cloneRoot };
 export function register(r, app) {
   const { store, telemetry, prefs, retro, remote, machines } = app;
 
+  // defaults are what's in effect: yours, with what spells set on top (lockedBy says which spell).
+  // spells: every spell that's on, for the page to apply. recipes: yours and the spells'.
+  const view = () => ({
+    ...store.config,
+    remote: undefined,
+    defaults: { ...store.config.defaults },
+    lockedBy: app.spells.settings().lockedBy,
+    recipes: [...store.config.recipes, ...app.spells.recipes()],
+    spells: app.spells.forPage(),
+    spellsSafe: app.spells.safe,
+  });
   r.route('GET', '/config', (c) =>
-    c.send(200, { ...store.config, remote: undefined, home: os.homedir(), cwd: process.cwd(), cloneDir: cloneRoot(store.config), terminals: TERMINALS, telemetry: { available: !envDisabled(), enabled: telemetry.enabled }, feedback: feedbackAvailable() }),
+    c.send(200, { ...view(), home: os.homedir(), cwd: process.cwd(), cloneDir: cloneRoot(store.config), terminals: TERMINALS, telemetry: { available: !envDisabled(), enabled: telemetry.enabled }, feedback: feedbackAvailable() }),
   );
   r.route('PATCH', '/config', async (c) => {
     const body = await c.body();
-    if (body.defaults) Object.assign(store.config.defaults, body.defaults);
+    const locked = app.spells.settings().lockedBy;
+    const clash = Object.keys(body.defaults || {}).find((k) => locked[k] && body.defaults[k] !== store.config.defaults[k]);
+    if (clash) return c.send(409, { error: `${clash} is set by the spell ${locked[clash].name}. Turn it off in Settings → Spells to change it.`, spell: locked[clash] });
+    if (body.defaults) Object.assign(store.config.defaults, Object.fromEntries(Object.entries(body.defaults).filter(([k]) => !locked[k])));
     if (body.webhooks !== undefined) {
       const { hooks, error } = normalizeWebhooks(body.webhooks);
       if (error) return c.send(400, { error });
       store.config.webhooks = hooks;
     }
     app.configChanged();
-    c.send(200, { ...store.config, remote: undefined });
+    c.send(200, view());
   });
 
   // What wisp learned: preferences and lessons, global and per project (scope = 'global' or a project path).

package/server/routes/spells.js

@@ -0,0 +1,147 @@
+// Spells: install, check, turn on and off, export, and the data and links spells use.
+
+import { spawn } from 'node:child_process';
+import { describeSpell, normalizeSpell } from '../spells.js';
+import { summarize } from '../runner.js';
+import { bad } from '../util.js';
+
+const MAX_SPELL_BYTES = 512 * 1024;
+const MAX_OPEN = 20;
+
+// Fetch a spell from a link: any https URL to the JSON, or gist:<id> (the first *.spell.json in it).
+export async function fetchSpell(src) {
+  const s = String(src || '').trim();
+  const gist = /^gist:([a-f0-9]{6,64})$/i.exec(s) || /^https:\/\/gist\.github\.com\/(?:[\w-]+\/)?([a-f0-9]{6,64})\/?$/i.exec(s);
+  const get = async (url, json) => {
+    const res = await fetch(url, { headers: { accept: json ? 'application/vnd.github+json' : 'application/json', 'user-agent': 'wisp' }, signal: AbortSignal.timeout(15_000) });
+    if (!res.ok) throw bad(`Couldn't fetch ${url}: ${res.status}`);
+    const text = await res.text();
+    if (text.length > MAX_SPELL_BYTES) throw bad('That spell is bigger than 512 KB.');
+    return text;
+  };
+  if (gist) {
+    const g = JSON.parse(await get(`https://api.github.com/gists/${gist[1]}`, true));
+    const file = Object.values(g.files || {}).find((f) => /\.spell\.json$/i.test(f.filename)) || Object.values(g.files || {}).find((f) => /\.json$/i.test(f.filename));
+    if (!file) throw bad('That gist has no .spell.json file.');
+    return { spell: JSON.parse(file.truncated ? await get(file.raw_url) : file.content), source: { kind: 'gist', url: `gist:${gist[1]}`, owner: g.owner?.login || '' } };
+  }
+  if (!/^https:\/\//i.test(s)) throw bad('A spell link is an https URL or gist:<id>.');
+  return { spell: JSON.parse(await get(s)), source: { kind: 'url', url: s } };
+}
+
+// The body's spell: { spell: {…} }, { text: '<json>' } (pasted), or { url } (fetched).
+async function spellOf(body) {
+  if (body.url) return fetchSpell(body.url);
+  if (typeof body.text === 'string') {
+    try {
+      return { spell: JSON.parse(body.text), source: { kind: 'file', name: String(body.name || '') } };
+    } catch (err) {
+      throw bad(`That isn't JSON: ${err.message}`);
+    }
+  }
+  if (body.spell && typeof body.spell === 'object') return { spell: body.spell, source: body.source && typeof body.source === 'object' ? { kind: String(body.source.kind || 'local'), ...(body.source.session && { session: String(body.source.session) }) } : null };
+  throw bad('Send { spell }, { text } or { url }.');
+}
+
+// Open links in the default browser (a page can open only one popup per click; this can open several).
+export function openUrls(urls) {
+  const list = (Array.isArray(urls) ? urls : [urls]).map(String).filter((u) => /^https?:\/\/[^\s"']+$/i.test(u));
+  if (!list.length) throw bad('Nothing to open: only http(s) links.');
+  for (const url of list.slice(0, MAX_OPEN)) {
+    const [cmd, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '""', url]] : ['xdg-open', [url]];
+    if (process.env.WISP_NO_OPEN === '1') continue; // tests
+    try {
+      spawn(cmd, args, { stdio: 'ignore', detached: true, windowsHide: true }).on('error', () => {}).unref();
+    } catch {}
+  }
+  return list.slice(0, MAX_OPEN);
+}
+
+export function register(r, app) {
+  const { spells, store } = app;
+  const one = (fn) => async (c) => {
+    const s = spells.get(c.params.id);
+    if (!s) return c.send(404, { error: 'no such spell' });
+    return fn(c, s);
+  };
+
+  r.route('GET', '/spells', (c) => c.send(200, spells.list()));
+
+  // Validate without installing: what it does, its riskiest kind, problems or warnings.
+  r.route('POST', '/spells/check', async (c) => {
+    const { spell: raw } = await spellOf(await c.body());
+    try {
+      const { spell, warnings } = normalizeSpell(raw);
+      const d = describeSpell(spell);
+      const installed = spells.get(spell.id);
+      c.send(200, { ok: true, spell, summary: d.lines, kind: d.kind, warnings, installed: installed ? { version: installed.version, enabled: spells.isOn(spell.id), same: JSON.stringify(installed) === JSON.stringify(spell) } : null });
+    } catch (err) {
+      if (!err.problems) throw err;
+      c.send(200, { ok: false, problems: err.problems, error: err.message });
+    }
+  });
+
+  // Install (or update). Off unless enable: true, which only the user's own click sends.
+  r.route('POST', '/spells', async (c) => {
+    const body = await c.body();
+    const { spell, source } = await spellOf(body);
+    const out = spells.install(spell, { source, enable: body.enable === true });
+    app.telemetry?.track('spell_installed', { source: source?.kind || 'local', enabled: body.enable === true, kind: out.spell.kind });
+    c.send(out.updated ? 200 : 201, out);
+  });
+
+  // Turn every spell off (the way out when one makes the page unusable).
+  r.route('POST', '/spells/off', (c) => {
+    for (const s of spells.enabled()) spells.setEnabled(s.id, false, { quiet: true });
+    spells.onChange();
+    c.send(200, spells.list());
+  });
+
+  r.route('GET', '/spells/:id', one((c, s) => c.send(200, spells.view(s))));
+  r.route(
+    'PATCH',
+    '/spells/:id',
+    one(async (c, s) => {
+      const body = await c.body();
+      if (typeof body.enabled !== 'boolean') return c.send(400, { error: 'enabled must be true or false' });
+      c.send(200, spells.setEnabled(s.id, body.enabled));
+    }),
+  );
+  r.route('DELETE', '/spells/:id', (c) => {
+    spells.remove(c.params.id);
+    c.send(200, { ok: true });
+  });
+  r.route('GET', '/spells/:id/export', one((c, s) => c.send(200, spells.exported(s.id))));
+
+  // A spell's data source, fetched for it. session: the card's task, for per-task sources.
+  r.route(
+    'POST',
+    '/spells/:id/data/:name',
+    one(async (c, s) => {
+      const body = await c.body();
+      const source = s.data?.[c.params.name];
+      if (!source) return c.send(404, { error: `${s.name} has no data source ${c.params.name}` });
+      const session = body.session ? store.get(String(body.session)) : null;
+      const value = await app.spellData.get(s.id, c.params.name, source, { session, summary: session ? summarize(session, store) : null, fresh: body.fresh === true });
+      c.send(200, { value });
+    }),
+  );
+
+  // Try it: a data source of a spell that isn't installed (or is, in another version), checked first.
+  r.route('POST', '/spells/try-data', async (c) => {
+    const body = await c.body();
+    const { spell } = normalizeSpell(body.spell);
+    const name = String(body.name || '');
+    const source = spell.data?.[name];
+    if (!source) return c.send(404, { error: `${spell.name} has no data source ${name}` });
+    const session = body.session ? store.get(String(body.session)) : null;
+    const value = await app.spellData.get(`try-${spell.id}`, name, source, { session, summary: session ? summarize(session, store) : null });
+    c.send(200, { value });
+  });
+
+  // Open http(s) links in the default browser.
+  r.route('POST', '/open', async (c) => {
+    const { urls } = await c.body();
+    c.send(200, { opened: openUrls(urls) });
+  });
+}

package/server/runner.js

@@ -8,6 +8,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { adapters } from './adapters/index.js';
 import { systemPrompt, parsePresentation, heroOf } from './protocol.js';
+import { spellGuide } from './spell-guide.js';
 import { captureCheckpoint, freshCheckpoint, readGitFile } from './checkpoint.js';
 import { teamNote, copies, SUBAGENT_ASK } from './subagents.js';
 import { handoffNote } from './handoff.js';
@@ -145,6 +146,7 @@ export function summarize(s, store) {
     conflictFix: s.conflictFix ? { step: s.conflictFix.step, why: s.conflictFix.why || '' } : null,
     groupId: s.groupId || null,
     origin: s.origin || null, // { kind: 'recipe' | 'trigger' | 'telegram', id, name }
+    ...(s.kind && { kind: s.kind }), // 'spell': a Cast a spell task
     moved: s.moved || null, // { from }: carried on here from another place (services/move.js)
     movedTo: s.movedTo || null, // { id, place }: this one carried on there, and was archived
     // The roster, for the stacked logos on the card: used = delegated to at least once, busy = working now.
@@ -187,6 +189,7 @@ export class Runner extends EventEmitter {
     this.answers = new Map(); // askId -> answer, until the MCP server picks it up
     this.sides = new Map(); // /btw id -> { sessionId, handle }: side questions being answered
     this.promptExtra = () => ''; // (session) => text appended to the system prompt (learned preferences)
+    this.spellBlocks = () => []; // (session) => block types spells add, for the protocol
     this.routeAuto = null; // (prompt, { cwd }) => { agent, model, route } for subagents set to Auto
     this.pipeline = null; // Auto's check / repair / hand-over steps (server/pipeline.js)
 
@@ -209,7 +212,7 @@ export class Runner extends EventEmitter {
   // subagents: the team a lead may delegate to. parentId/member: this session is one of them.
   // also: the task's other folders, [{ cwd, worktree }] (services/launch.js).
   // history / title / moved: a task moved here from another place, with the turns it had there.
-  create({ id = newId(), prompt, cwd, also = [], agent = 'claude', mode = 'auto', model = '', effort = '', attachments = [], worktree = null, groupId = null, origin = null, subagents = [], parentId = null, member = '', route = null, auto = null, scout = null, history = [], title = '', moved = null }) {
+  create({ id = newId(), prompt, cwd, also = [], agent = 'claude', mode = 'auto', model = '', effort = '', attachments = [], worktree = null, groupId = null, origin = null, subagents = [], parentId = null, member = '', route = null, auto = null, scout = null, history = [], title = '', moved = null, kind = '' }) {
     if (!adapters[agent]) throw new Error(`Unknown agent: ${agent}`);
     const now = Date.now();
     const session = {
@@ -230,6 +233,7 @@ export class Runner extends EventEmitter {
       queue: [],
       turns: [...history],
       ...(moved && { moved }),
+      ...(kind && { kind }), // 'spell': a Cast a spell task (server/spell-guide.js)
       ...(worktree && { worktree }),
       ...(also.length && { also }),
       ...(groupId && { groupId }),
@@ -625,10 +629,12 @@ export class Runner extends EventEmitter {
 
   // The wisp protocol for this run: a lead hears about its team, a subagent that it can't ask.
   #systemPrompt(session, adapter, team) {
+    const extraBlocks = session.parentId ? [] : this.spellBlocks(session);
     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);
+      : systemPrompt({ askTool: adapter.askTool, extraBlocks }) + teamNote(team, adapters, delegateTool(adapter.askTool ?? 'mcp__wisp__ask_user'));
+    const spell = session.kind === 'spell' ? spellGuide(adapter.askTool ?? 'mcp__wisp__ask_user') : '';
+    return base + spell + workspaceNote(session) + this.promptExtra(session);
   }
 
   // wisp's own MCP server (ask_user, delegate), for harnesses that take one. Subagents get none.
@@ -646,6 +652,7 @@ export class Runner extends EventEmitter {
           WISP_TOKEN: this.bridge.token,
           WISP_SESSION: session.id,
           ...(adapter.approveTool && { WISP_APPROVE: '1' }),
+          ...(session.kind === 'spell' && { WISP_SPELLS: '1' }),
           ...(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) }))) }),
         },
       },

package/server/services/launch.js

@@ -42,6 +42,11 @@ export function createLaunch(app) {
   //         subagents: [{ name, agent, model, effort, use }] | preset: teamId, moved: { from, title, turns, packs } }
   async function launch(body, origin = null) {
     if (!String(body.prompt || '').trim()) throw bad('prompt required');
+    // kind 'spell': Cast a spell. The agent changes wisp, not a project: an empty scratch folder of
+    // its own, one run. Edits mode, not Plan: Claude's Plan mode refuses MCP tools (the spell tools),
+    // and there is nothing in the folder to edit; wisp installs the spell only when you keep it.
+    const kind = body.kind === 'spell' ? 'spell' : '';
+    if (kind) body = { ...body, scratch: true, mode: 'edits', compare: undefined, subagents: undefined, preset: undefined, worktree: false };
     // scratch: no project folder (general questions); the task gets an empty directory of its own.
     const scratch = body.scratch === true;
     const cwd = scratch ? store.scratchDir(newId()) : expand(body.cwd || process.cwd());
@@ -109,7 +114,7 @@ export function createLaunch(app) {
         return made.map((worktree) => ({ cwd: dir, ...(worktree && { worktree }) }));
       }),
     );
-    return runners.map((r, i) => runner.create({ id: ids[i], prompt: body.prompt, cwd, also: extras.map((x) => x[i]), ...r, mode, attachments, worktree: trees[i], groupId, origin, subagents, ...(r.route && { auto: { strategy }, scout: resolved.scout || null }) }));
+    return runners.map((r, i) => runner.create({ id: ids[i], prompt: body.prompt, cwd, also: extras.map((x) => x[i]), ...r, mode, attachments, worktree: trees[i], groupId, origin, subagents, kind, ...(kind && { title: `Spell: ${String(body.prompt).trim().split('\n')[0].slice(0, 60)}` }), ...(r.route && { auto: { strategy }, scout: resolved.scout || null }) }));
   }
 
   // Where a launch runs: body.machine ('' = here), else a project folder that only exists on a
@@ -131,7 +136,7 @@ export function createLaunch(app) {
 
   // launch(), here or on a machine. Resolves with summaries (a compare launch has several).
   async function launchAny(body, origin = null) {
-    const mid = machineFor(body);
+    const mid = body.kind === 'spell' ? null : machineFor(body); // spells change this wisp, so they're cast here
     // Every project runs anywhere: its folders become the ones on that place, cloned there first if need be.
     body = await app.places.placeBody(body, mid);
     if (!mid) return (await launch(body, origin)).map((x) => summarize(x, store));

package/server/services/spell-hooks.js

@@ -0,0 +1,99 @@
+// Spell hooks: what spells do on their own when something happens to a task. A hook fires at most
+// its `max` times per task (default once), so a spell that replies to failed tests can't loop.
+//
+//   turn.finished    a turn ended with the agent's report     turn.failed   a turn ended in an error
+//   session.started  a new task started                       session.waiting  a task asks you something
+
+import { sessionToMarkdown } from '../render.js';
+import { summarize } from '../runner.js';
+import { fillTemplate } from '../../web/js/spell-schema.js';
+import { VERSION, clip } from '../util.js';
+
+// Did the turn's tests fail (its own tests block, or Auto's check)?
+export function testsFailed(session, turn) {
+  const blocks = turn?.presentation?.blocks || [];
+  if (blocks.some((b) => b.type === 'tests' && Number(b.failed) > 0)) return true;
+  return session.auto?.checks?.at(-1)?.verdict === 'fail';
+}
+
+export function hookMatches(cond = {}, { session, turn, summary }) {
+  const list = (v) => (Array.isArray(v) ? v : [v]);
+  if (cond.status !== undefined && !list(cond.status).includes(summary.status) && !list(cond.status).includes(turn?.status)) return false;
+  if (cond.testsFailed !== undefined && testsFailed(session, turn) !== !!cond.testsFailed) return false;
+  if (cond.agent !== undefined && !list(cond.agent).includes(session.agent)) return false;
+  if (cond.project !== undefined && !list(cond.project).some((p) => p === summary.project || p === summary.projectId)) return false;
+  if (cond.hasPr !== undefined && !!session.pr !== !!cond.hasPr) return false;
+  if (cond.mode !== undefined && !list(cond.mode).includes(session.mode)) return false;
+  return true;
+}
+
+export function createSpellHooks(app) {
+  const { runner, store, spells } = app;
+  const waiting = new Set(); // sessions already reported as waiting, until they move on
+
+  const skip = (s) => !s || s.agent === 'wisp' || s.parentId || s.kind === 'spell';
+
+  async function act(spell, hook, s) {
+    const [k, v] = Object.entries(hook.do || {})[0] || [];
+    const summary = summarize(s, store);
+    const text = typeof v === 'string' ? fillTemplate(v, summary) : v;
+    switch (k) {
+      case 'reply':
+        runner.reply(s, `${text}`, [], { by: 'wisp' });
+        break;
+      case 'done':
+        app.launcher.markDone(s);
+        break;
+      case 'archive':
+        if (s.state === 'running' || s.state === 'waiting') return;
+        s.archived = true;
+        s.unread = false;
+        app.sessionChanged(s);
+        break;
+      case 'notify':
+        app.broadcast('spell', { toast: clip(text, 200), spell: spell.name, session: s.id });
+        await app.remote?.send?.({ title: `✨ ${spell.name}`, text, actions: [] }).catch(() => {});
+        break;
+      case 'webhook':
+        await fetch(v, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', 'user-agent': `wisp/${VERSION}` },
+          body: JSON.stringify({ event: hook.on, spell: spell.id, session: summary, markdown: sessionToMarkdown(s), at: Date.now() }),
+          signal: AbortSignal.timeout(10_000),
+        });
+        break;
+      default:
+        return;
+    }
+    app.telemetry?.track('spell_hook', { on: hook.on, action: k });
+  }
+
+  function fire(event, s, turn = s?.turns?.at(-1)) {
+    if (skip(s)) return;
+    const summary = summarize(s, store);
+    for (const { spell, hook } of spells.hooks(event)) {
+      if (spell.harnesses && !spell.harnesses.includes('*') && !spell.harnesses.includes(s.agent)) continue;
+      if (spells.hookCount(spell.id, hook.id, s.id) >= hook.max) continue;
+      if (!hookMatches(hook.if, { session: s, turn, summary })) continue;
+      spells.countHook(spell.id, hook.id, s.id);
+      // After the event's own handlers: a reply must not start inside the turn that's ending.
+      setTimeout(() => act(spell, hook, s).catch((err) => console.warn(`wisp: spell ${spell.id} hook ${hook.id}: ${err.message}`)), 50);
+    }
+  }
+
+  runner.on('ended', ({ session, turn, interrupted }) => {
+    if (interrupted || turn.status === 'stopped') return;
+    fire(turn.status === 'error' ? 'turn.failed' : 'turn.finished', session, turn);
+  });
+  runner.on('started', ({ session }) => {
+    if (session.turns.length === 1) fire('session.started', session);
+  });
+  runner.on('summary', (sum) => {
+    if (sum.state !== 'waiting') return void waiting.delete(sum.id);
+    if (waiting.has(sum.id)) return;
+    waiting.add(sum.id);
+    fire('session.waiting', store.get(sum.id));
+  });
+
+  return { fire };
+}

package/server/spell-guide.js

@@ -0,0 +1,135 @@
+// What a Cast a spell agent is told: how spells work, what it may use, and how to hand one back.
+// The reference (slots, parts, actions, …) comes from web/js/spell-schema.js, so it never drifts
+// from what wisp accepts.
+
+import { ACTIONS, CARD_HEAD_ORDER, EVENTS, HOOK_ACTIONS, HOOK_IF, ICONS, PART_PROPS, PARTS, SETTINGS, SLOTS, STYLE_PROPS, TOKENS, WISP_DATA, GH_READ } from '../web/js/spell-schema.js';
+
+export const SPELL_EXAMPLES = [
+  {
+    ask: 'A floating button that opens all my open PRs',
+    spell: {
+      wispSpell: 1, id: 'my-prs', name: 'My PRs', version: '1.0.0', description: 'Open every PR you have open on GitHub, from a floating button.',
+      data: { prs: { gh: ['search', 'prs', '--author', '@me', '--state', 'open', '--json', 'url,title,repository'], refresh: 120 } },
+      buttons: [{ slot: 'float', icon: 'github', label: 'My PRs', badge: { count: 'prs' }, do: { openAll: { data: 'prs', field: 'url' } } }],
+    },
+  },
+  {
+    ask: 'A top bar button that shows my wisp tool stats',
+    spell: {
+      wispSpell: 1, id: 'tool-stats', name: 'Tool stats', version: '1.0.0',
+      data: { tools: { wisp: '/usage/tools?days=30' } },
+      buttons: [{ slot: 'topbar', icon: 'stats', label: 'Tools', do: { panel: 'tools' } }],
+      panels: [{ id: 'tools', title: 'Tool calls · last 30 days', as: 'dialog', data: ['tools'], render: 'tools' }],
+      script: "export function tools({ tools: t }) {\n  return [\n    { type: 'stats', items: [{ label: 'tool calls', value: t.total.calls }, { label: 'turns', value: t.total.turns }, { label: 'spend', value: Math.round(t.total.cost * 100) / 100, unit: '$' }] },\n    { type: 'chart', title: 'By kind', items: t.kinds.map((k) => ({ label: k.kind, value: k.calls })) },\n    { type: 'chart', title: 'By harness', items: t.agents.map((a) => ({ label: a.agent, value: a.calls })) },\n  ];\n}",
+    },
+  },
+  {
+    ask: 'A deploy block agents use after deploying',
+    spell: {
+      wispSpell: 1, id: 'deploy-block', name: 'Deploy block', version: '1.0.0',
+      blocks: [{ type: 'deploy', doc: '{"type":"deploy","env":"staging","url":"https://…","status":"ok|failed","checks":[{"label":"health","ok":true}]} After you deploy: where it went and whether it is healthy.', summary: 'Deployed {env} → {url} ({status})', render: 'deploy' }],
+      script: "export function deploy(b) {\n  return [\n    { type: 'callout', tone: b.status === 'ok' ? 'success' : 'danger', title: `${b.env} · ${b.status}`, text: b.url },\n    { type: 'checklist', items: (b.checks || []).map((c) => ({ text: c.label, done: !!c.ok })) },\n  ];\n}",
+    },
+  },
+  {
+    ask: 'Compact cards, bold titles, PR first, no machine or project, and Open PR on hover',
+    spell: {
+      wispSpell: 1, id: 'compact-cards', name: 'Compact cards', version: '1.0.0',
+      parts: { card: { props: { density: 'compact' } }, 'card.title': { style: { fontWeight: '650' } }, 'card.head': { order: ['pr', 'pill', 'time'] } },
+      ui: { hide: ['card.machine', 'card.project'] },
+      buttons: [{ slot: 'card.hover', icon: 'github', label: 'Open PR', when: { hasPr: true }, do: { open: '{pr.url}' } }],
+    },
+  },
+  {
+    ask: 'Quick replies above the follow-up box, and a second-opinion button',
+    spell: {
+      wispSpell: 1, id: 'quick-replies', name: 'Quick replies', version: '1.0.0',
+      buttons: [
+        { slot: 'composer.chips', label: 'Run the tests', do: { send: 'Run the tests and show me the output.' } },
+        { slot: 'composer.chips', label: 'Explain why…', do: { insert: 'Explain why ' } },
+        { slot: 'composer.bar', icon: 'agent', label: 'Second opinion', do: { rerun: { agent: 'codex', mode: 'plan', prompt: 'Review the changes on branch {branch} and say what you would do differently.' } } },
+      ],
+    },
+  },
+  {
+    ask: 'When tests fail, send the task back once',
+    spell: {
+      wispSpell: 1, id: 'fix-failing-tests', name: 'Fix failing tests', version: '1.0.0',
+      hooks: [{ on: 'turn.finished', if: { testsFailed: true }, max: 1, do: { reply: 'Some tests fail. Fix them, rerun the suite and report again.' } }],
+    },
+  },
+];
+
+// The full reference, as JSON (wisp_spell_schema).
+export function spellReference() {
+  return {
+    format: 'One JSON object. Required: wispSpell (1), id (lowercase-dashes), name. Everything else is optional.',
+    fields: {
+      version: '"1.0.0" — bump it when you change a spell the user already has',
+      description: 'one sentence',
+      harnesses: '["*"] or e.g. ["claude","codex"]: which harnesses its prompt rules, blocks and hooks apply to',
+      when: '{ project: [names|ids|paths], agent: [...], mode: [...] } scope for prompt rules, blocks and hooks',
+      data: '{ name: { wisp: "/path?query" } | { gh: [args], cwd?: "task", refresh?: seconds } } — fetched by wisp; script functions receive them as their first argument { name: value }. gh args may use {field} templates over the card\'s task (e.g. "{pr.number}").',
+      buttons: '[{ id?, slot, label, icon?, title?, badge?: { count: "<data>" } | { text: "{field}" } | { fn, with: [data] }, group?: "name" (float only: folds into one button), corner?: "bottom-left", when?: {hasPr, prState, state, status, agent, project, unread, hasBranch} (card slots), do }]',
+      chips: '[{ slot: "card.head" | "launcher.chips" | "composer.chips", text: "{field} template" | fn: "<script fn>" (returns a string), with?: [data], tone?: good|bad|warn|info|neutral, icon?, title?, when?, do? }]',
+      panels: '[{ id, title, icon?, as: dialog|drawer|feed|card, slot?: card.top|card.bottom (as card), data: [names], render: "<script fn>", refresh?: { every: seconds, on: [summary, finished] } }] — render returns an array of wisp presentation blocks (stats, chart, markdown, checklist, files, callout, steps, tree, flow, terminal, code, actions with url…)',
+      blocks: '[{ type, doc: "one-line JSON example + when to use it", summary: "{field} template for text-only places", render: "<script fn>" }] — new presentation blocks agents can use; render(block) returns wisp blocks',
+      parts: '{ "<part>": { style?: { cssProp: value }, props?: {...}, order?: [...] (card.head only) } }',
+      ui: '{ hide: [parts], tokens: { "--accent": "#7c5cff" }, dark: { … tokens for dark mode } }',
+      prompt: '["text", { text, when }] — added to agents\' system prompts while the spell is on',
+      settings: '{ key: value } — wins over the user\'s setting while the spell is on',
+      slash: '[{ name, args?, hint?, do }] — /name in a follow-up box; {args} in do\'s text is what the user typed after it',
+      commands: '[{ label, keywords?, icon?, key?, do }] — ⌘K items (key: a single key like "g" or "shift+g", only when no built-in uses it)',
+      hooks: `[{ on, if?, max?, do }] — on: ${Object.keys(EVENTS).join(' | ')}; if: { ${HOOK_IF.join(', ')} }; do: one of ${[...HOOK_ACTIONS].join(', ')}; max: times per task (default 1)`,
+      recipes: '[{ name, prompt with {params}, agent?, mode? }] — saved prompts',
+      script: 'JS with `export function name(data, ctx) { return … }` functions. It runs in a sandbox with no network, no DOM and no wisp API: it can only compute and return values (blocks, strings, numbers, lists of links). ctx: { session } (the card\'s task summary, when there is one), { block } for agent blocks (the block is also the first argument).',
+    },
+    templates: '{field} in text, labels, links and gh args is filled from the card\'s task summary: id, title, state, status, agent, model, mode, project, branch, cwd, preview, pr.number, pr.url, pr.state, pr.checks …; in slash commands {args} too. Missing fields become empty.',
+    slots: SLOTS,
+    parts: Object.keys(PARTS),
+    partProps: PART_PROPS,
+    cardHeadOrder: Object.keys(CARD_HEAD_ORDER),
+    styleProps: STYLE_PROPS,
+    tokens: TOKENS,
+    icons: ICONS,
+    actions: Object.fromEntries(Object.entries(ACTIONS).map(([k, v]) => [k, v.doc])),
+    settings: SETTINGS,
+    wispData: WISP_DATA,
+    ghReadOnly: Object.fromEntries(Object.entries(GH_READ).map(([k, v]) => [k, v || 'GET only'])),
+    examples: SPELL_EXAMPLES,
+  };
+}
+
+// The system-prompt section for a Cast a spell task (kind: 'spell').
+export function spellGuide(tool = 'mcp__wisp__ask_user') {
+  const t = (name) => tool.replace(/ask_user$/, name);
+  return `
+
+## This task: cast a spell on wisp
+
+The user wants to change wisp itself — add a button, a panel, a block agents can use, restyle or hide
+part of the UI, change how agents behave — without anyone editing wisp's code. You do it by writing a
+**spell**: one JSON object wisp layers over itself at runtime. You don't edit files and you don't run
+commands; wisp installs the spell when the user clicks **Keep** on your report.
+
+How to work:
+1. Call \`wisp_spell_schema\` (${t('wisp_spell_schema')}) for the full reference: slots, parts, actions,
+   icons, tokens, data sources, examples. Use only what it lists.
+2. Call \`wisp_spells\` (${t('wisp_spells')}) to see what the user has already. To change one, keep its id and
+   bump its version; to remove one, end with \`{"type":"spell","remove":"<id>"}\` (remove at the top
+   level of the block, no spell object).
+3. If you read data (a \`wisp\` or \`gh\` source), call \`wisp_spell_data\` (${t('wisp_spell_data')}) with the
+   source to see the real shape before writing script that reads it.
+4. Call \`wisp_spell_check\` (${t('wisp_spell_check')}) with your spell until it says ok. It validates and
+   compiles the script (without running it) and says in plain words what the spell does.
+5. End with a report whose blocks include exactly one \`spell\` block:
+   {"type":"spell","spell":{ …the whole spell… }}
+   Put a hero first (what the spell does, in a line), then the spell block, then anything worth
+   knowing (what you assumed, what it can't do). Keep it short: the spell block itself shows the user
+   a preview and what changes.
+
+Rules: prefer the smallest spell that does what was asked. Never invent slots, parts, actions or
+fields. Script functions are pure: no fetch, no DOM, no globals — they get data and return values.
+If the ask needs something spells can't do yet, say so in a callout and do the closest thing they can.
+`;
+}