wisp-agents 0.24.1 → 0.25.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-10-21
+
+### Added
+
+- **Spells: change wisp itself, by asking.** A spell is a change wisp layers over itself at runtime: a floating button that opens all your PRs (with how many), a top bar button with your tool stats, a `deploy` block agents can use in their reports, compact cards with an Open PR button on hover, quick replies above the follow-up box, a monospace prompt box with a *Plan on Codex* button, a hook that sends a task back once when its tests fail. Cast one from ⌘K → *Cast a spell…*, Settings → Spells, `/spell …` in the prompt box or `wisp spell cast "…"`. An agent writes it in an empty folder of its own, using new `wisp_spell_schema`, `wisp_spells`, `wisp_spell_data` and `wisp_spell_check` tools, and its report ends with the spell: a live preview with your real data and what it does in plain words. **Try it** applies it to the window only; **Keep** turns it on; a follow-up changes it. Spells add buttons, chips and panels to named places (top bar, floating, prompt box, follow-up box, card head / hover / menu / body, ⌘K, above the feed), restyle or hide named parts, recolour wisp, add block types and prompt rules for agents, `/commands`, settings (shown as *Set by …* in Settings) and hooks. Their data comes from read-only wisp routes and read-only `gh` commands that wisp runs; their code runs in a sandboxed frame with no network, DOM or API and can only return values and blocks. Each spell says how far it reaches (Safe, Acts for you, Reads GitHub, Runs commands). Turning one off puts wisp back exactly as it was; `WISP_SAFE=1` turns them all off. Share a spell as a `.spell.json` file, pasted JSON or a link: Settings → Spells (export, copy, import by file, paste or link) or `wisp spell install|on|off|rm|export`. API: `/spells` (list, install, `check`, on/off, export, data, `try-data`, `off`), `POST /open`, `GET /usage/tools`, and `kind: "spell"` on `POST /sessions`.
+
+### Fixed
+
+- **Spell inputs look like the rest of wisp.** In Settings → Spells and the *Cast a spell* dialog the prompt box was a 32px input squeezed to one line with its resize grip over the text, and *Paste JSON or a link* was monospace; both sat flush against their panel's edge. They now use wisp's standard text box and input, inset like every other settings row.
+- **Settings → Spells casts from a prompt box like the launcher's.** The Cast button no longer sits beside the text box: the prompt is a rounded box with the launcher's focus ring and an Enter button in a bar under the text, it grows as you type, and a click anywhere on it puts the cursor in. Long example prompts wrap inside their chip instead of running over the next one.
+- **Space above "Needs you" is back.** When something needed you, the first feed group sat flush under the launcher's recipes row.
+- **Codex can use wisp's tools outside Full auto.** In Edits and Plan mode `codex exec` refused every MCP call ("requires approval, but approval policy is never"), so `ask_user` and the other wisp tools failed there. wisp's own MCP server is now pre-approved.
+- **A report whose last block lost a closing brace keeps that block.** Agents sometimes drop a `}` after a long string (a spell's script); wisp used to skip the block with a warning, and now closes it.
+
 ## [0.24.1] - 2026-10-20
 
 ### Fixed
@@ -442,7 +456,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 - Session queue with follow-ups, answers to agent questions, terminal takeover and mark-as-done.
 - Older turns are folded, with a floating collapse-all button and back-to-top.
 
-[Unreleased]: https://github.com/M0xoo/wisp/compare/v0.24.1...HEAD
+[Unreleased]: https://github.com/M0xoo/wisp/compare/v0.25.0...HEAD
+[0.25.0]: https://github.com/M0xoo/wisp/compare/v0.24.1...v0.25.0
 [0.24.1]: https://github.com/M0xoo/wisp/compare/v0.24.0...v0.24.1
 [0.24.0]: https://github.com/M0xoo/wisp/compare/v0.23.0...v0.24.0
 [0.23.0]: https://github.com/M0xoo/wisp/compare/v0.22.0...v0.23.0

package/README.md

@@ -56,7 +56,8 @@ From there you can **follow up**, **answer its questions**, **take it over** in
 | 🤝 **Subagents** | Give the lead agent a team on other harnesses (e.g. Claude Code hands tests to Codex ×3). It delegates through a `delegate` tool; their edits land in its worktree. See [Subagents](#subagents). |
 | ⏪ **Checkpoints & rollback** | Every turn is snapshotted first. Restore to before any turn, revert a single file, or re-run a command block from the presentation. |
 | ⚖️ **Compare** | Run one task on two harnesses side by side, and keep the better run. |
-| 🧾 **Recipes & triggers** | Saved prompts with `{params}` (`wisp run release 0.24.1`), run by hand, on a schedule, when CI fails, or when an issue is labelled. |
+| ✨ **Spells** | Change wisp itself while it runs: ask for a floating button that opens your PRs, a panel with your tool stats, a block agents can use in their reports, a different prompt box, quick replies, buttons on cards, a new look. An agent writes it as a *spell*; you try it in the window and keep it. Share one as a file, and turn any of them off to put wisp back as it was. See [Spells](#spells). |
+| 🧾 **Recipes & triggers** | Saved prompts with `{params}` (`wisp run release 0.25.0`), run by hand, on a schedule, when CI fails, or when an issue is labelled. |
 | 📊 **Usage** | Spend, success rate and questions per project and per harness · model. |
 | 📱 **Phone** | Questions and finished tasks on ntfy or Telegram; answer from there, or start a task with `/new`. |
 | 🔐 **Permission modes** | Choose **Plan** (read-only), **Edits** (file edits auto-accepted), or **Full auto** (no permission prompts, the default) for each launch. `Shift+Tab` in the prompt cycles modes. In Edits mode, anything the permissions block comes to you: Claude Code waits for **Allow / Always / Deny**, and the other harnesses show an **Allow & retry** card. |
@@ -85,7 +86,7 @@ brew install m0xoo/tap/wisp-agents             # Homebrew: CLI and browser mode,
 wisp "fix the flaky auth test"
 ```
 
-The Homebrew formula lives in [M0xoo/homebrew-tap](https://github.com/M0xoo/homebrew-tap). `install.sh` honors `WISP_VERSION` to pin a release (`curl -fsSL https://trywisp.dev/install.sh | WISP_VERSION=0.24.1 bash`).
+The Homebrew formula lives in [M0xoo/homebrew-tap](https://github.com/M0xoo/homebrew-tap). `install.sh` honors `WISP_VERSION` to pin a release (`curl -fsSL https://trywisp.dev/install.sh | WISP_VERSION=0.25.0 bash`).
 
 From source:
 
@@ -135,7 +136,7 @@ wisp btw <id> "did you do X?"     # ask on the side without interrupting the run
 wisp stop <id>
 wisp ship <id> [--draft]          # commit, push and open a PR for a worktree task
 wisp merge <id>                   # squash-merge its PR, fast-forward your local main
-wisp run release 0.24.1            # run a recipe; values fill its {params} (or version=0.24.1)
+wisp run release 0.25.0            # run a recipe; values fill its {params} (or version=0.25.0)
 wisp recipes                      # list recipes
 wisp usage [--days 7]             # spend and outcomes
 wisp mcp                          # MCP server for other agents and editors
@@ -354,7 +355,7 @@ Before each turn, wisp snapshots the git working tree (pinned at `refs/wisp/chec
 Prepare release {version}: update CHANGELOG, README and docs/, bump package.json, tag v{version}.
 ```
 
-Make one from ⌘K → *Recipes*, or *Save as recipe…* on any card. A recipe may pin a project, harness, model and mode. Run it from ⌘K (*Run: Release*), from the Recipes view, or from a terminal: `wisp run release 0.24.1` fills the fields in order, `wisp run release version=0.24.1` by name.
+Make one from ⌘K → *Recipes*, or *Save as recipe…* on any card. A recipe may pin a project, harness, model and mode. Run it from ⌘K (*Run: Release*), from the Recipes view, or from a terminal: `wisp run release 0.25.0` fills the fields in order, `wisp run release version=0.25.0` by name.
 
 **Triggers** launch sessions on their own while wisp is open (⌘K → *Triggers*):
 
@@ -366,6 +367,45 @@ Make one from ⌘K → *Recipes*, or *Save as recipe…* on any card. A recipe m
 
 GitHub triggers poll with your `gh` login (every 2–60 minutes), so nothing has to reach your machine; the first check only records what already exists. Issue triggers start in Plan mode: issue text comes from whoever can open issues, so think twice before giving it Full auto.
 
+## Spells
+
+A spell is a change to wisp that wisp layers over itself at runtime, without anyone editing its code: buttons, panels, blocks agents can use, a different look, how agents behave. Each is one JSON file in `~/.wisp/spells/`. Turning one off puts back exactly what it changed, and the file is all you need to share it.
+
+**Cast one.** ⌘K → *Cast a spell…*, Settings → Spells, or `/spell …` in the prompt box. Say what you want:
+
+```text
+/spell a floating button that opens all my open PRs on GitHub, with how many there are
+/spell a top bar button with my wisp tool stats for the last 30 days
+/spell a "deploy" block agents can use to show where they deployed and whether it's healthy
+/spell compact cards, the PR first, and an Open PR button on cards that have one
+/spell quick replies above the follow-up box: Run the tests, Explain why…
+/spell when a task finishes with failing tests, send it back once
+```
+
+An agent (in an empty folder of its own) reads the spell reference, samples the real data, checks the spell with wisp and hands it back as a card with a live preview: the buttons as they will look, panels drawn with your data, and what the spell does in plain words. **Try it** applies it to this window only (**Undo** takes it back); **Keep** turns it on. Ask a follow-up to change it, or "remove the … spell" to drop it.
+
+**What a spell can do**
+
+| | |
+|---|---|
+| Add | Buttons in the top bar, floating in a corner (grouped into a menu), in the prompt box and the follow-up box, on cards (on hover, in the head, in the menu) and in ⌘K. Chips and quick replies. Panels as a dialog, a drawer, above the feed or inside each card. |
+| Change | Restyle or hide named parts (`card.title`, `launcher.compare`, `topbar.machines`, …), reorder a card's head, set the prompt box's placeholder, rows and font, recolour wisp (`--accent`, …). |
+| Agents | New block types for reports (`deploy`, …), rules added to agents' prompts (all or per project / harness), `/commands`, settings while the spell is on. |
+| On its own | Hooks: when a turn finishes or fails, a task starts or waits for you, reply once, mark done, archive, notify or POST to a URL. |
+| Data | Read-only wisp routes (`/sessions`, `/usage/tools`, …) and read-only `gh` commands (`search prs`, `pr checks`, `run list`, …). wisp fetches them; spell code never touches the network. |
+
+A spell's code (`script`) runs only in a sandboxed frame with no network, no DOM and no wisp API: it gets the data wisp fetched and returns values or blocks, which wisp checks and draws with its own renderer. Every spell shows how far it reaches: **Safe**, **Acts for you** (follow-ups, launches; only when you click, or a hook), **Reads GitHub**, or **Runs commands**. Questions, approvals and Settings → Spells can't be restyled or hidden. Start wisp with `WISP_SAFE=1` to turn every spell off, or use **Turn every spell off** in Settings → Spells.
+
+**Share one.** Settings → Spells → export (a `.spell.json` file) or copy (JSON for a chat). Your colleague drops the file on wisp, pastes it or a link (https or `gist:<id>`) into Settings → Spells, or runs `wisp spell install ./my-prs.spell.json`. They see the same review before anything changes, and it stays off until they turn it on.
+
+```sh
+wisp spell                         # list: ● on  ○ off
+wisp spell cast "a /explain command that asks for a plain-words explanation"
+wisp spell install my-prs.spell.json --on
+wisp spell export my-prs > my-prs.spell.json
+wisp spell off --all
+```
+
 ## Usage
 
 ⌘K → *Usage* shows spend per day and, per project and per harness · model: spend, turns, how often the run worked (finished, not partial or blocked), how often the agent had to ask you, and the average time. Claude Code, opencode and Grok report cost (Grok only when its plan does); Codex, Cursor and Antigravity only report tokens, so their turns are counted but not priced. Also `wisp usage` and `GET /api/usage?days=30`.

package/bin/wisp.js

@@ -6,6 +6,7 @@
 //   wisp add [path]            add a folder as a project (default: current folder)
 //   wisp ls | show | wait | reply | btw | stop    script sessions (see --help)
 //   wisp run <recipe> [values…]             run a saved recipe
+//   wisp spell [ls|cast|install|on|off|rm|export]  spells: changes to wisp itself
 //   wisp mcp                   stdio MCP server, so other agents and editors can use wisp
 //   wisp skill [install]       the agent skill that teaches other agents to use wisp
 
@@ -33,6 +34,11 @@ const HELP = `usage:
   wisp run <recipe> [values…]   run a saved recipe; values fill its {params} in order, or key=value
   wisp recipes                  list recipes
   wisp usage                    spend and outcomes   (--days 7|30|90)
+  wisp spell                    list spells (changes to wisp itself: buttons, panels, blocks, looks)
+  wisp spell cast "<change>"    an agent writes a spell for it; keep it in the app   (--wait)
+  wisp spell install <file|url> add a spell someone sent (https, gist:<id>); off until --on
+  wisp spell on|off|rm <id>     turn a spell on or off, or remove it   (wisp spell off --all)
+  wisp spell export <id>        print the spell file to share
   wisp mcp                      run the MCP server (stdio) for other agents and editors
   wisp skill [install]          print / install the wisp agent skill   (--agent claude|codex|opencode|all  --project)
   wisp -- "ls the repo"         a task that starts with a command name
@@ -41,7 +47,7 @@ launch options: --mode plan|edits|auto  --agent claude|codex|opencode|cursor|ant
                 --cwd DIR  --also DIR (repeatable)  --wait  --json  --no-worktree  --compare agent[:model],…
 options:        --port N  --browser  --no-open  --json  --version`;
 
-const COMMANDS = new Set(['add', 'ls', 'list', 'show', 'wait', 'reply', 'btw', 'stop', 'mcp', 'skill', 'ship', 'merge', 'run', 'recipes', 'usage']);
+const COMMANDS = new Set(['add', 'ls', 'list', 'show', 'wait', 'reply', 'btw', 'stop', 'mcp', 'skill', 'ship', 'merge', 'run', 'recipes', 'usage', 'spell', 'spells']);
 const argv = process.argv.slice(2);
 const flags = { open: true, browser: false, port: Number(process.env.WISP_PORT) || 4477, mode: null, agent: null, model: null, effort: null, cwd: null, also: [], json: false, wait: false, queue: undefined, state: null, limit: null, project: false, worktree: undefined, compare: null, draft: false, days: null };
 const words = [];
@@ -69,6 +75,8 @@ for (let i = 0; i < argv.length; i++) {
   else if (a === '--worktree') flags.worktree = true;
   else if (a === '--compare') flags.compare = argv[++i].split(',').filter(Boolean).map((x) => ({ agent: x.split(':')[0], model: x.split(':').slice(1).join(':') || undefined }));
   else if (a === '--draft') flags.draft = true;
+  else if (a === '--on') flags.on = true;
+  else if (a === '--all') flags.all = true;
   else if (a === '--days') flags.days = Number(argv[++i]);
   else if (a === '--version' || a === '-v') {
     console.log(JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url))).version);
@@ -171,6 +179,9 @@ async function scripted(cmd, args) {
       if (!flags.json) console.error(`  ◌ launched: ${s.title}  (${s.id}) — waiting…`);
       return show(s.id, await wisp.wait(s.id));
     }
+    case 'spell':
+    case 'spells':
+      return spellCommand(wisp, args, { out, need, show });
     case 'usage': {
       const u = await wisp.usage({ days: flags.days || 30 });
       const money = (v) => `$${v.toFixed(2)}`;
@@ -181,6 +192,49 @@ async function scripted(cmd, args) {
   }
 }
 
+// wisp spell …: list, cast, install, turn on/off, remove and export spells (server/routes/spells.js).
+async function spellCommand(wisp, [sub = 'ls', ...rest], { out, need, show }) {
+  const api = (method, p, body) => wisp.request(method, p, body);
+  const line = (s) => `${s.enabled ? '●' : '○'} ${s.id.padEnd(24)} ${`v${s.version}`.padEnd(8)} ${s.kind.padEnd(5)}  ${s.name}${s.description ? ` — ${s.description}` : ''}`;
+  switch (sub) {
+    case 'ls':
+    case 'list': {
+      const r = await api('GET', '/spells');
+      return out(r, [r.safe ? '! safe mode: every spell is off' : '', ...r.spells.map(line), ...r.broken.map((b) => `! ${b.id}: ${b.error}`)].filter(Boolean).join('\n') || 'No spells yet. Cast one: wisp spell cast "a floating button that opens my PRs"');
+    }
+    case 'cast': {
+      const s = await wisp.launch({ prompt: need(rest.join(' ').trim(), 'what to change'), kind: 'spell', agent: flags.agent || undefined, model: flags.model ?? undefined, effort: flags.effort ?? undefined });
+      if (!flags.wait) return out(s, `  ✨ casting: ${s.title}  (${s.id})\n  Try it and keep it from its card in wisp.`);
+      if (!flags.json) console.error(`  ✨ casting: ${s.title}  (${s.id}) — waiting…`);
+      return show(s.id, await wisp.wait(s.id));
+    }
+    case 'install':
+    case 'add': {
+      const src = need(rest[0], 'a .spell.json file or a link');
+      const body = /^(https:\/\/|gist:)/i.test(src) ? { url: src } : { text: fs.readFileSync(path.resolve(src), 'utf8'), name: path.basename(src) };
+      const check = await api('POST', '/spells/check', body);
+      if (!check.ok) die(`That spell has problems:\n- ${check.problems.join('\n- ')}`);
+      const r = await api('POST', '/spells', { ...body, enable: !!flags.on });
+      return out(r, [`  ✓ ${r.updated ? 'updated' : 'added'} ${r.spell.name} (${r.spell.id} v${r.spell.version}, ${r.spell.kind})${r.spell.enabled ? ', on' : ' — off; turn it on with: wisp spell on ' + r.spell.id}`, ...check.summary.map((l) => `    · ${l}`)].join('\n'));
+    }
+    case 'on':
+    case 'off': {
+      if (sub === 'off' && flags.all) return out(await api('POST', '/spells/off', {}), '  ✓ every spell is off');
+      const r = await api('PATCH', `/spells/${encodeURIComponent(need(rest[0], 'spell id'))}`, { enabled: sub === 'on' });
+      return out(r, `  ✓ ${r.name} is ${r.enabled ? 'on' : 'off'}`);
+    }
+    case 'rm':
+    case 'remove':
+      return out(await api('DELETE', `/spells/${encodeURIComponent(need(rest[0], 'spell id'))}`, {}), '  ✓ removed');
+    case 'export': {
+      const s = await api('GET', `/spells/${encodeURIComponent(need(rest[0], 'spell id'))}/export`);
+      return console.log(JSON.stringify(s, null, 2));
+    }
+    default:
+      die(`unknown: wisp spell ${sub} (ls, cast, install, on, off, rm, export)`);
+  }
+}
+
 // Installs skills/wisp/SKILL.md where each harness looks for skills.
 function skill(sub) {
   const src = fileURLToPath(new URL('../skills/wisp/SKILL.md', import.meta.url));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wisp-agents",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": "Run Claude Code, Codex, Cursor and other coding agents in parallel, in the background, on any of your machines. Skip the transcript, read the report.",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "app": "node bin/wisp.js",
     "dev": "WISP_DEV=1 node bin/wisp.js",
     "dev:web": "node --watch-path=server bin/wisp.js --no-open",
-    "test": "node --test test/proc.test.js test/terminal.test.js test/adapters.test.js test/e2e.test.js test/fuzzy.test.js test/integrations.test.js test/update.test.js test/learn.test.js test/ship.test.js test/subagents.test.js test/machines.test.js test/feedback.test.js test/router.test.js test/routes.test.js test/adapters-exit.test.js test/web-pure.test.js test/install.test.js test/install-script.test.js test/mentions.test.js test/clone.test.js test/pipeline.test.js test/commands.test.js test/btw.test.js test/site.test.js",
+    "test": "node --test test/proc.test.js test/terminal.test.js test/adapters.test.js test/e2e.test.js test/fuzzy.test.js test/integrations.test.js test/update.test.js test/learn.test.js test/ship.test.js test/subagents.test.js test/machines.test.js test/feedback.test.js test/router.test.js test/routes.test.js test/adapters-exit.test.js test/web-pure.test.js test/install.test.js test/install-script.test.js test/mentions.test.js test/clone.test.js test/pipeline.test.js test/commands.test.js test/btw.test.js test/site.test.js test/spells.test.js",
     "site": "node scripts/site.mjs",
     "test:real": "node test/real-clis.mjs",
     "prepublishOnly": "node --check bin/wisp.js && node --check bin/mac-app.js && node -e \"import('./server/index.js').then(() => import('./server/mcp-wisp.js'))\" && node --check electron/main.js"

package/server/adapters/codex.js

@@ -83,6 +83,9 @@ export default {
       args.push('-c', `${key}.command=${toml(srv.command)}`, '-c', `${key}.args=${toml(srv.args || [])}`);
       if (srv.env) args.push('-c', `${key}.env=${toml(srv.env)}`);
       args.push('-c', `${key}.tool_timeout_sec=${ASK_TIMEOUT_MS / 1000}`);
+      // wisp's own tools (ask_user, the spell tools…) need no approval: outside Full auto, codex
+      // exec's approval policy is never, which otherwise refuses every MCP call.
+      args.push('-c', `${key}.default_tools_approval_mode=${toml('approve')}`);
     }
     const images = attachments.filter((a) => IMAGE.test(a.mime));
     for (const img of images) args.push('-i', img.path);

package/server/client.js

@@ -133,14 +133,14 @@ export class WispClient {
   // runs the same task on more harnesses at once, each in its own worktree. subagents:
   // [{ name, agent, model, effort, use }] (or preset: a saved team's id) the lead can delegate to.
   // also: more folders the same task works in (each git repo gets its own worktree and PR).
-  async launch({ prompt, cwd = process.cwd(), also, agent, mode, model, effort, attachments, worktree, compare, subagents, preset } = {}) {
+  async launch({ prompt, cwd = process.cwd(), also, agent, mode, model, effort, attachments, worktree, compare, subagents, preset, kind } = {}) {
     if (!agent || !mode || model === undefined) {
       const { defaults = {} } = await this.config();
       agent ||= defaults.agent || 'auto';
       mode ||= defaults.mode || 'auto';
       model ??= defaults.models?.[agent] ?? (agent === defaults.agent ? defaults.model || '' : '');
     }
-    return this.request('POST', '/sessions', { prompt, cwd: path.resolve(cwd), also: also?.length ? also.map((d) => path.resolve(d)) : undefined, agent, mode, model, effort, attachments, worktree, compare, subagents, preset });
+    return this.request('POST', '/sessions', { prompt, cwd: path.resolve(cwd), also: also?.length ? also.map((d) => path.resolve(d)) : undefined, agent, mode, model, effort, attachments, worktree, compare, subagents, preset, kind });
   }
 
   // Ship it: commit the session's worktree, push its branch, open (or update) the PR.

package/server/index.js

@@ -16,6 +16,10 @@ import { welcomeSession } from './welcome.js';
 import { Telemetry } from './telemetry.js';
 import { Updater } from './update.js';
 import { Preferences, Retro } from './preferences.js';
+import { Spells, overlayDefaults } from './spells.js';
+import { createSpellData } from './spells-data.js';
+import { setSpellBlocks } from './render.js';
+import { createSpellHooks } from './services/spell-hooks.js';
 import { Triggers } from './triggers.js';
 import { Remote } from './remote.js';
 import { Machines, splitId } from './machines.js';
@@ -47,11 +51,12 @@ import * as machineRoutes from './routes/machines.js';
 import * as proxyRoutes from './routes/proxy.js';
 import * as sessionRoutes from './routes/sessions.js';
 import * as shipRoutes from './routes/ship.js';
+import * as spellRoutes from './routes/spells.js';
 
 export { API_VERSION };
 
 // Order matters only where patterns overlap: the machine proxy claims <id>@<machine> first.
-const ROUTES = [metaRoutes, autoRoutes, internalRoutes, uploadRoutes, settingsRoutes, automationRoutes, machineRoutes, proxyRoutes, sessionRoutes, shipRoutes];
+const ROUTES = [metaRoutes, autoRoutes, internalRoutes, uploadRoutes, settingsRoutes, automationRoutes, machineRoutes, proxyRoutes, sessionRoutes, shipRoutes, spellRoutes];
 
 // Idle keep-alive connections are closed by the client first (Node's fetch: 4s, browsers: longer
 // but they retry). With Node's 5s default the two raced, and a request sent on a socket the
@@ -87,6 +92,14 @@ export async function startServer({ port = DEFAULT_PORT, host = '127.0.0.1', han
 
   if (store.all().length === 0) store.put(welcomeSession());
 
+  // Spells: changes layered over wisp at runtime (server/spells.js). Settings a spell sets win
+  // while it's on; config.json keeps only yours.
+  app.spells = new Spells(store.home);
+  store.config.defaults = overlayDefaults(store.config.defaults, () => app.spells.settings());
+  app.spells.onChange = () => app.configChanged();
+  app.spellData = createSpellData(app);
+  setSpellBlocks((type) => app.spells.enabled().flatMap((x) => x.blocks || []).find((b) => b.type === type) || null);
+
   runner.on('summary', (s) => app.broadcast('summary', s));
   runner.on('activity', (a) => app.broadcast('activity', a));
   runner.on('turn', (t) => app.broadcast('turn', t));
@@ -122,7 +135,8 @@ export async function startServer({ port = DEFAULT_PORT, host = '127.0.0.1', han
   app.prefs = new Preferences(store.home);
   app.learning = () => store.config.defaults.learn !== 'off';
   const projectOf = (cwd) => store.projectFor(cwd)?.path || cwd;
-  runner.promptExtra = (s) => (app.learning() && s.agent !== 'wisp' ? app.prefs.prompt(projectOf(s.cwd)) : '') + scoutNote(s.scout);
+  runner.promptExtra = (s) => (app.learning() && s.agent !== 'wisp' ? app.prefs.prompt(projectOf(s.cwd)) : '') + (s.parentId ? '' : app.spells.promptFor(s, store.projectFor(s.cwd))) + scoutNote(s.scout);
+  runner.spellBlocks = (s) => app.spells.blocksFor(s, store.projectFor(s.cwd));
   app.retro = new Retro({
     store,
     runner,
@@ -158,6 +172,7 @@ export async function startServer({ port = DEFAULT_PORT, host = '127.0.0.1', han
   // Phone: answers and follow-ups coming back from ntfy / Telegram.
   app.remote = new Remote({ store, onChange: () => app.broadcast('remote', {}), ...phoneActions(app) });
   app.ship = createShip(app);
+  createSpellHooks(app);
 
   const routes = new Routes();
   for (const mod of ROUTES) mod.register(routes, app);

package/server/mcp-ask.js

@@ -9,10 +9,12 @@
 // `wisp_stats` is read-only: tool counts, spend and success rate across the user's wisp sessions.
 // `wisp_sessions` and `wisp_session` are read-only too: list the user's other tasks and read one's
 // reports, e.g. a task the user mentioned in the prompt.
+// With WISP_SPELLS (a Cast a spell task): `wisp_spells`, `wisp_spell_schema`, `wisp_spell_data` and
+// `wisp_spell_check`, to write a spell for the user to keep.
 
 import readline from 'node:readline';
 
-const { WISP_URL, WISP_TOKEN, WISP_SESSION, WISP_APPROVE } = process.env;
+const { WISP_URL, WISP_TOKEN, WISP_SESSION, WISP_APPROVE, WISP_SPELLS } = process.env;
 let TEAM = [];
 try {
   TEAM = JSON.parse(process.env.WISP_TEAM || '[]');
@@ -96,6 +98,44 @@ const SESSION = {
   },
 };
 
+// Cast a spell tasks (WISP_SPELLS) get the tools to write one: what's installed, the reference,
+// a data source's real answer, and a check that validates without installing anything.
+const SPELL_TOOLS = [
+  {
+    name: 'wisp_spells',
+    description: 'The spells the user has (on or off), each as its full JSON with a plain-words summary. Read-only.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'wisp_spell_schema',
+    description: 'The complete reference for writing a spell: fields, slots, parts, props, style properties, tokens, icons, actions, data sources and worked examples.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'wisp_spell_data',
+    description: 'Run a spell data source and return a sample of its real answer, so script reads the right shape. Read-only (wisp GET routes from the allowlist, read-only gh commands).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        source: { type: 'object', description: '{ "wisp": "/usage/tools?days=30" } or { "gh": ["search", "prs", "--author", "@me", "--json", "url,title"] }' },
+        task: { type: 'string', description: 'Optional task id, to fill {field} templates in gh args from that task (e.g. {pr.number}).' },
+      },
+      required: ['source'],
+    },
+  },
+  {
+    name: 'wisp_spell_check',
+    description: 'Validate a spell without installing it. Returns ok and what it does in plain words, or every problem to fix. The script is compiled, never run.',
+    inputSchema: { type: 'object', properties: { spell: { type: 'object', description: 'The whole spell JSON.' } }, required: ['spell'] },
+  },
+];
+
+async function spellTool(name, args = {}) {
+  if (name === 'wisp_spell_data') return (await call(`/api/internal/spell-data/${WISP_SESSION}`, args)).text;
+  if (name === 'wisp_spell_check') return (await call(`/api/internal/spell-check/${WISP_SESSION}`, args)).text;
+  return (await call(`/api/internal/${name === 'wisp_spells' ? 'spells' : 'spell-schema'}/${WISP_SESSION}`)).text;
+}
+
 async function sessions(args = {}) {
   const q = new URLSearchParams(Object.entries(args).filter(([, v]) => v !== undefined && v !== '').map(([k, v]) => [k, String(v)]));
   return (await call(`/api/internal/sessions/${WISP_SESSION}?${q}`)).text;
@@ -228,7 +268,7 @@ readline.createInterface({ input: process.stdin }).on('line', async (line) => {
     if (method === 'initialize') {
       send({ id, result: { protocolVersion: params?.protocolVersion || '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'wisp', version: '0.1.0' } } });
     } else if (method === 'tools/list') {
-      send({ id, result: { tools: [TOOL, STATS, SESSIONS, SESSION, ...(WISP_APPROVE ? [APPROVE] : []), ...(TEAM.length ? TEAM_TOOLS : [])] } });
+      send({ id, result: { tools: [TOOL, STATS, SESSIONS, SESSION, ...(WISP_APPROVE ? [APPROVE] : []), ...(TEAM.length ? TEAM_TOOLS : []), ...(WISP_SPELLS ? SPELL_TOOLS : [])] } });
     } else if (method === 'tools/call' && params?.name === 'ask_user') {
       const answer = await askUser(params.arguments || {});
       const text = answer === null ? 'The user did not answer (the question was cancelled). Use your best judgment and note the assumption.' : `The user answered: ${answer}`;
@@ -246,6 +286,8 @@ readline.createInterface({ input: process.stdin }).on('line', async (line) => {
     } else if (method === 'tools/call' && TEAM.length && params?.name === 'subagent_results') {
       const a = params.arguments || {};
       send({ id, result: { content: [{ type: 'text', text: await results(a.ids, a.wait !== false) }] } });
+    } else if (method === 'tools/call' && WISP_SPELLS && SPELL_TOOLS.some((t) => t.name === params?.name)) {
+      send({ id, result: { content: [{ type: 'text', text: await spellTool(params.name, params.arguments || {}) }] } });
     } else if (method === 'ping') {
       send({ id, result: {} });
     } else {

package/server/openapi.js

@@ -6,6 +6,7 @@ const ref = (name) => ({ $ref: `#/components/schemas/${name}` });
 const json = (schema, description = 'OK') => ({ description, content: { 'application/json': { schema } } });
 const id = { name: 'id', in: 'path', required: true, schema: { type: 'string' }, description: 'Session id' };
 const body = (schema) => ({ required: true, content: { 'application/json': { schema } } });
+const spellId = { name: 'id', in: 'path', required: true, schema: { type: 'string' }, description: 'Spell id' };
 const err = { 400: json(ref('Error'), 'Bad request'), 404: json(ref('Error'), 'Not found') };
 const ok = json({ type: 'object', properties: { ok: { type: 'boolean' } } });
 
@@ -219,6 +220,42 @@ export function openapi({ version, port }) {
           responses: { 200: json({ type: 'object' }) },
         },
       },
+      '/usage/tools': {
+        get: {
+          summary: 'Tool calls by kind, harness, project and day, with turns, cost and success rate (what wisp_stats tells agents)',
+          parameters: [{ name: 'days', in: 'query', schema: { type: 'integer', default: 30, maximum: 365 } }, { name: 'agent', in: 'query', schema: { type: 'string' } }, { name: 'project', in: 'query', schema: { type: 'string' }, description: 'Project id or name' }],
+          responses: { 200: json({ type: 'object' }) },
+        },
+      },
+      '/spells': {
+        get: { summary: 'Every spell: its JSON, on or off, where it came from, a plain-words summary and its kind (safe | acts | reads | runs); broken files; safe mode', responses: { 200: json({ type: 'object' }) } },
+        post: {
+          summary: 'Install or update a spell from { spell }, { text } (pasted JSON) or { url } (https or gist:<id>). It stays off unless enable: true',
+          requestBody: body({ type: 'object', properties: { spell: { type: 'object' }, text: { type: 'string' }, url: { type: 'string' }, enable: { type: 'boolean' } } }),
+          responses: { 200: json({ type: 'object' }), 201: json({ type: 'object' }), 400: err[400], 409: json({ type: 'object' }) },
+        },
+      },
+      '/spells/check': {
+        post: {
+          summary: 'Validate a spell without installing it: { ok, spell, summary, kind, warnings, installed } or { ok: false, problems }',
+          requestBody: body({ type: 'object', properties: { spell: { type: 'object' }, text: { type: 'string' }, url: { type: 'string' } } }),
+          responses: { 200: json({ type: 'object' }), 400: err[400] },
+        },
+      },
+      '/spells/try-data': { post: { summary: "Fetch a data source of a spell that isn't installed (Try it); the spell is validated first", requestBody: body({ type: 'object', required: ['spell', 'name'], properties: { spell: { type: 'object' }, name: { type: 'string' }, session: { type: 'string' } } }), responses: { 200: json({ type: 'object', properties: { value: {} } }), 400: err[400], 404: err[404] } } },
+      '/spells/off': { post: { summary: 'Turn every spell off', responses: { 200: json({ type: 'object' }) } } },
+      '/spells/{id}': {
+        parameters: [spellId],
+        get: { summary: 'One spell', responses: { 200: json({ type: 'object' }), 404: err[404] } },
+        patch: { summary: 'Turn a spell on or off. 409 when its block types or slash commands clash with one that is on', requestBody: body({ type: 'object', required: ['enabled'], properties: { enabled: { type: 'boolean' } } }), responses: { 200: json({ type: 'object' }), 404: err[404], 409: json({ type: 'object' }) } },
+        delete: { summary: 'Remove a spell', responses: { 200: json({ type: 'object' }), 404: err[404] } },
+      },
+      '/spells/{id}/export': { parameters: [spellId], get: { summary: 'The spell file to share (.spell.json)', responses: { 200: json({ type: 'object' }), 404: err[404] } } },
+      '/spells/{id}/data/{name}': {
+        parameters: [spellId, { name: 'name', in: 'path', required: true, schema: { type: 'string' } }],
+        post: { summary: "Fetch one of a spell's data sources. session: the card's task, for per-task sources; fresh skips the cache", requestBody: body({ type: 'object', properties: { session: { type: 'string' }, fresh: { type: 'boolean' } } }), responses: { 200: json({ type: 'object', properties: { value: {} } }), 404: err[404] } },
+      },
+      '/open': { post: { summary: 'Open http(s) links in the default browser (at most 20)', requestBody: body({ type: 'object', required: ['urls'], properties: { urls: { type: 'array', items: { type: 'string' } } } }), responses: { 200: json({ type: 'object' }), 400: err[400] } } },
       '/sessions/{id}/wait': {
         parameters: [id, { name: 'timeout', in: 'query', schema: { type: 'integer', default: 60, maximum: 290 }, description: 'Seconds' }],
         get: { summary: 'Long-poll until the session needs you (finished or asking)', responses: { 200: json({ allOf: [ref('Summary'), { type: 'object', properties: { timedOut: { type: 'boolean' } } }] }), 404: err[404] } },
@@ -315,6 +352,7 @@ export function openapi({ version, port }) {
             cwd: { type: 'string', description: 'Project folder (absolute; ~ allowed). Default: the server’s cwd' },
             also: { type: 'array', maxItems: 8, items: { type: 'string' }, description: 'More folders the same task works in (absolute; ~ allowed). The agent gets each; git repos get their own worktree, and Ship it opens a PR in each' },
             scratch: { type: 'boolean', description: 'No project folder: run in an empty scratch directory (no worktree). Overrides cwd' },
+            kind: { type: 'string', enum: ['spell'], description: 'spell: Cast a spell. The agent writes a spell that changes wisp (an empty scratch folder, Edits mode, this computer); its report ends with a spell block to keep' },
             agent: { enum: ['auto', 'claude', 'codex', 'opencode', 'cursor', 'antigravity', 'grok'], default: 'auto', description: 'auto: wisp picks the harness and model from what worked before; model is then the goal (cheap, balanced, best)' },
             important: { type: 'boolean', description: 'With agent auto: no exploring, take the pick with the best record' },
             mode: { enum: ['plan', 'edits', 'auto'], default: 'auto' },

package/server/protocol.js

@@ -103,7 +103,13 @@ const ASK_BLOCK = `- If a decision would change the rest of the work (ambiguous
 
 // askTool: how the harness names wisp's injected ask_user tool, or null if it can't take one.
 // 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));
+// extraBlocks: block types spells add ({ type, doc, spell }), listed with the built-in ones.
+export const systemPrompt = ({ askTool = 'mcp__wisp__ask_user', ask, extraBlocks = [] } = {}) => {
+  const out = PROTOCOL.replace('{{ASK}}', ask || (askTool ? ASK_TOOL(askTool) : ASK_BLOCK));
+  if (!extraBlocks.length) return out;
+  const docs = extraBlocks.map((b) => `- ${b.doc.trim().startsWith('{') ? b.doc.trim().replace(/\}\s+(?=\S)/, '}\n  ') : `{"type":"${b.type}"} ${b.doc}`}\n  (From the user's spell ${b.spell}.)`).join('\n');
+  return out.replace('\nStrings must be valid JSON', `\n${docs}\n\nStrings must be valid JSON`);
+};
 export const SYSTEM_PROMPT = systemPrompt();
 
 // Only the opener is matched by regex. The closing fence can't be: the JSON itself often
@@ -164,8 +170,15 @@ function salvageBlocks(src) {
     while (/[\s,]/.test(src[i] || '')) i++;
     if (src[i] !== '{') break;
     const len = jsonEnd(src.slice(i));
-    if (len < 0) break;
-    const block = tryJson(src.slice(i, i + len));
+    if (len < 0) {
+      // The last block is missing closing braces (a common slip after a long string): close it.
+      const fixed = closeBraces(src.slice(i));
+      if (fixed) blocks.push(fixed);
+      else bad++;
+      break;
+    }
+    // A bracket count that ends early on a `]` usually means a block lost a closing brace.
+    const block = tryJson(src.slice(i, i + len)) || closeBraces(src.slice(i, i + len));
     if (block && typeof block === 'object') blocks.push(block);
     else bad++;
     i += len;
@@ -175,6 +188,22 @@ function salvageBlocks(src) {
   return blocks;
 }
 
+// A block whose closing braces went missing at the end of the answer: cut it at each of its last
+// few `}` and add up to three more until it parses. null when that doesn't help.
+function closeBraces(src) {
+  const body = src.replace(/```[\s\S]*$/, '').trimEnd();
+  let cut = body.length;
+  for (let tries = 0; tries < 6 && cut > 0; tries++) {
+    cut = body.lastIndexOf('}', cut - 1);
+    if (cut < 0) return null;
+    for (let k = 1; k <= 3; k++) {
+      const json = tryJson(body.slice(0, cut + 1) + '}'.repeat(k));
+      if (json && typeof json === 'object' && typeof json.type === 'string') return json;
+    }
+  }
+  return null;
+}
+
 function jsonEnd(src) {
   const start = src.search(/\S/);
   if (src[start] !== '{' && src[start] !== '[') return -1;

package/server/render.js

@@ -89,12 +89,27 @@ const R = {
   next: (b) => `**Next**\n${list(b.items).map((i) => `- ${str(i)}`).join('\n')}`,
 };
 
+// Block types spells add: their summary template stands in for them here (set from server/index.js).
+let spellBlock = () => null;
+export const setSpellBlocks = (fn) => (spellBlock = fn);
+const fillFields = (tpl, o) => String(tpl).replace(/\{([a-zA-Z_][\w.]*)\}/g, (_, k) => str(k.split('.').reduce((x, y) => x?.[y], o)));
+
+R.spell = (b) => {
+  const remove = b.remove || (!b.spell?.wispSpell && b.spell?.remove);
+  if (remove) return `**✨ Spell:** remove \`${str(remove)}\``;
+  const s = b.spell || {};
+  return `**✨ Spell: ${str(s.name) || str(s.id)}**${s.description ? ` — ${s.description}` : ''}\n\n_Keep it in wisp to turn it on._`;
+};
+
 // blocks: presentation blocks; turn (optional) supplies captured edits for diff blocks.
 export function blocksToMarkdown(blocks = [], turn = null) {
   return list(blocks)
     .map((b) => {
       try {
-        return R[b?.type] ? R[b.type](b, turn) : fence(JSON.stringify(b, null, 2), 'json');
+        if (R[b?.type]) return R[b.type](b, turn);
+        const def = spellBlock(b?.type);
+        if (def?.summary) return `${fillFields(def.summary, b)}`;
+        return fence(JSON.stringify(b, null, 2), 'json');
       } catch {
         return '';
       }

package/server/routes/automations.js

@@ -6,7 +6,9 @@ import { normalizeTrigger, triggerView } from '../triggers.js';
 export function register(r, app) {
   const { store } = app;
 
-  r.route('GET', '/recipes', (c) => c.send(200, store.config.recipes.map(recipeView)));
+  // Yours, then the ones spells add (read-only: they belong to the spell).
+  const all = () => [...store.config.recipes, ...app.spells.recipes()];
+  r.route('GET', '/recipes', (c) => c.send(200, all().map(recipeView)));
   r.route('POST', '/recipes', async (c) => {
     const x = normalizeRecipe(await c.body());
     store.config.recipes.push(x);
@@ -14,9 +16,10 @@ export function register(r, app) {
     c.send(201, recipeView(x));
   });
   // A recipe by id or by name (loosely: "Fix Bug" finds fix-bug).
-  const recipe = (fn) => async (c) => {
-    const x = findRecipe(store.config.recipes, c.params.key);
+  const recipe = (fn, { mine = false } = {}) => async (c) => {
+    const x = findRecipe(all(), c.params.key);
     if (!x) return c.send(404, { error: 'no such recipe' });
+    if (mine && x.spell) return c.send(409, { error: `This recipe comes from the spell ${x.spell.name}; change the spell instead.` });
     return fn(c, x);
   };
   r.route('GET', '/recipes/:key', recipe((c, x) => c.send(200, recipeView(x))));
@@ -27,7 +30,7 @@ export function register(r, app) {
       Object.assign(x, normalizeRecipe(await c.body(), x));
       app.configChanged();
       c.send(200, recipeView(x));
-    }),
+    }, { mine: true }),
   );
   r.route(
     'DELETE',
@@ -36,7 +39,7 @@ export function register(r, app) {
       store.config.recipes = store.config.recipes.filter((y) => y !== x);
       app.configChanged();
       c.send(200, { ok: true });
-    }),
+    }, { mine: true }),
   );
   // POST /recipes/:key/run { params | words, cwd, … }. machine: run it in a project there
   // (r.cwd empty, or a path on that machine).