@chatpanel/events 0.72.0 → 0.74.0

package/index.js

@@ -188,6 +188,8 @@ export { FIND_TOOL_NAME, FIND_DESCRIPTION, FIND_RESIDENT, findDispatchProvider }
 export { WEB_SEARCH_TOOL_NAME, WEB_SEARCH_TOOL_SYSTEM, WEB_SEARCH_SPEC, searchResultsToText, webSearchToolProvider } from './web-search-tool.js';
 export { compressToolSpec, compressToolSpecs, compressionStats, trimDescription, COMPRESSION_MODES, DEFAULT_COMPRESSION } from './tool-schema.js';
 export { validateRecipe, expandRecipe, recipeParams, mapInput, dryRunRecipe, runPlan, runRecipe, RecipeError, RECIPE_MODES } from './recipe.js';
+export { recipeToolProvider, recipeToolSpec, describeRecipeForApproval, RECIPE_TOOL_NAME } from './recipe-tool.js';
+export { mcpDispatchProvider, MCP_TOOL_NAME } from './mcp-dispatch.js';
 export { createManifest, ManifestError, SOURCES } from './manifest.js';
 export { createKernel, meetDecisions, KernelError, REQUIRED_PLUGINS, ALLOW_ALL } from './kernel.js';
 export { replay, formatReport, parseJsonl, toJsonl } from './harness.js';
@@ -275,9 +277,11 @@ export { renderMarkdown, defaultLinkPolicy } from './markdown-render.js';
 // extension writes and MCP reads, so every client shows one transcript, not three.
 export { parseMeetingText, speakerStats, densityRibbon } from './meeting-text.js';
 export { speakerBreakdown, speakerTimeline, formatTalkTime, SPEAKER_SLOTS } from './meeting-shape.js';
+export { isSpeakerImageValue, speakerLabeller } from './meeting-shape.js';
 // A list of records as a person reads it, and what a meeting settled — both read, never derived.
 export { SORT_MODES, SORT_LABELS, sortStamp, sortRecords, filterRecords, dayBucket, rowTime, groupRecords } from './record-list.js';
 export { INSIGHT_KINDS, summarySections, insightKindOf, meetingInsights, hasInsights } from './meeting-insights.js';
+export { demd, NOTE_SECTIONS, noteSectionKind, MOMENT_BADGES, momentBadge, parseMeetingNotes, groupActionsByOwner } from './meeting-insights.js';
 // The settings every client shares, and how two edited copies reconcile (per-section LWW).
 export { PREF_SECTIONS, PREF_SECTION_IDS, sectionValue, pickSections, applySections, sectionHash, mergeStamped, changedSections } from './client-prefs.js';
 // The MCP client (one per server, http or stdio-via-bridge) and the prompt text about tools.

package/mcp-dispatch.js

@@ -0,0 +1,52 @@
+// PROGRESSIVE DISCLOSURE for MCP servers — one registered tool instead of dozens.
+//
+// MCP is the largest resident cost by far: every connected server contributes a full JSON
+// schema per tool plus an inventory block, and the shared MCP rulebook (~600 tokens of
+// citation policy, argument-forming rules and fallback etiquette) is added once on top.
+// On a setup with a few servers that is thousands of tokens on every turn — including
+// turns that never touch a server.
+//
+// The existing defence was a relevance cap that DROPS tools beyond it. That is a real
+// loss of capability, silently: a tool the model needed but that ranked low simply was
+// not there. A dispatcher keeps every tool reachable and pays only for the menu, so the
+// cap stops being a capability decision and becomes a menu-length decision.
+//
+// PRIVACY: these tools call third parties, so the provider stays flagged `remote`. The
+// harness uses that flag to keep PII off remote tools under "redact remote" — a
+// dispatcher that dropped it would quietly convert redacted tools into unredacted ones.
+// That is the one property here worth a test of its own.
+
+import { makeDispatchProvider } from './tool-dispatch.js';
+
+// Deliberately NOT `mcp_*`. buildToolset adds the ~600-token shared MCP rulebook whenever
+// a spec name matches /^mcp[_-]/, so a dispatcher called `mcp_call` would collapse the
+// per-server schemas and then re-admit the rulebook it was meant to defer. The rulebook
+// travels with `describe` instead, and remoteness is carried by the provider's `remote`
+// flag rather than inferred from the name — which is where it should have come from
+// anyway.
+export const MCP_TOOL_NAME = 'mcp';
+
+const DESCRIPTION =
+  'Call a tool on a connected MCP server (the user\'s own integrations). Pass an `action` '
+  + 'and put that action\'s own arguments inside `args`, e.g. '
+  + '{"action":"mcp_jira__search","args":{"query":"ATLAS-1"}}. Unsure of an action\'s '
+  + 'arguments? {"action":"describe","args":{"tool":"<action>"}} returns its full schema '
+  + 'and how to use that server. Match the request\'s domain to the server\'s domain, and '
+  + 'do not call these when the page or provided context already answers the question.';
+
+export function mcpDispatchProvider(inner, { all = null, rank = undefined } = {}) {
+  return makeDispatchProvider({
+    all,
+    rank,
+    name: MCP_TOOL_NAME,
+    description: DESCRIPTION,
+    // Same lesson as the data and page groups: name the capability, not just the tool.
+    resident:
+      "You HAVE access to the user's connected MCP servers — their own integrations — "
+      + 'through the `mcp` tool. When a request matches a connected server\'s domain, call '
+      + 'it rather than saying the integration is unavailable.',
+    inner,
+    // Load-bearing for redaction, not bookkeeping. See the note above.
+    remote: true,
+  });
+}

package/meeting-insights.js

@@ -60,3 +60,105 @@ export function hasInsights(markdown) {
   const i = meetingInsights(markdown);
   return i.decisions.length + i.actions.length + i.questions.length > 0;
 }
+
+// ── The meeting page's own read of the notes ──────────────────────────────────────
+//
+// The Insights tab on a meeting is five tiles — Summary, Topics, Key Moments, Shared Links,
+// Action Items — and the extension's meetings page parsed them out of the notes with its own
+// section matcher, badge reader and owner/due grammar, inline. The desktop's meeting page
+// draws the same five tiles, so the parse is here: one answer to "which line is a risk".
+//
+// Different from `meetingInsights` above on purpose: that groups by what a line MEANS
+// (decisions / actions / questions) for a dashboard count; this keeps the notes' own
+// sections and the marks inside them (a [Risk] badge, an _(owner)_, a due date).
+
+const isBullet = (l) => /^\s*([-*+]|\d+\.)\s+/.test(l);
+const stripBullet = (l) => l.replace(/^\s*([-*+]|\d+\.)\s+/, '').trim();
+
+/** Plain text of a markdown-ish line: bold, italic, code and underscores unwrapped. */
+export const demd = (s) => String(s ?? '').replace(/\*\*(.+?)\*\*/g, '$1').replace(/(^|[^*])\*(?!\s)(.+?)\*/g, '$1$2').replace(/`(.+?)`/g, '$1').replace(/_(.+?)_/g, '$1').trim();
+
+export const NOTE_SECTIONS = Object.freeze(['summary', 'topics', 'moments', 'links', 'actions']);
+
+/** Which of the five tiles a heading belongs to, or null. */
+export function noteSectionKind(heading) {
+  const s = String(heading || '').toLowerCase();
+  if (/tl;?dr|summary|overview|recap/.test(s)) return 'summary';
+  if (/topic|agenda/.test(s)) return 'topics';
+  if (/key moment|moments|highlight|decision/.test(s)) return 'moments';
+  if (/shared link|link|url|resource|reference/.test(s)) return 'links';
+  if (/action|task|next step|to-?do|follow-?up/.test(s)) return 'actions';
+  return null;
+}
+
+export const MOMENT_BADGES = Object.freeze(['decision', 'risk', 'question', 'highlight']);
+
+/** A key moment's badge — `[Risk] the replica…` → risk — defaulting to highlight. */
+export function momentBadge(text) {
+  const t = String(text ?? '');
+  // `**Risk:**` puts the colon before the closing stars; `**Risk**:` after. Both are a badge.
+  // Anchored: a badge is how the line STARTS — "a plain highlight" is not a highlight badge.
+  const m = t.match(/^\s*\*{0,2}\[?\s*(decision|risk|question|highlight)\s*\]?\s*:?\*{0,2}\s*:?/i);
+  if (m) return { badge: m[1].toLowerCase(), text: t.slice(m.index + m[0].length).trim() };
+  return { badge: 'highlight', text: t };
+}
+
+/**
+ * The five tiles, read out of a meeting's notes.
+ * -> { summary, topics: [], moments: [{ badge, text }], links: [], actions: [{ text, done, owner, due, lineIndex }], hasAny }
+ *
+ * An action item is `- [ ] text _(owner)_ — due` in any of its looser forms; a plain bullet
+ * under the actions heading is an item with nothing known about it.
+ */
+export function parseMeetingNotes(md) {
+  const out = { summary: '', topics: [], moments: [], links: [], actions: [], hasAny: false };
+  const src = String(md ?? '');
+  if (!src.trim()) return out;
+  let cur = 'summary';
+  const summaryParts = [];
+  src.replace(/\r\n?/g, '\n').split('\n').forEach((raw, idx) => {
+    const line = raw.replace(/\s+$/, '');
+    const h = line.match(/^#{1,6}\s+(.*)$/);
+    if (h) { cur = noteSectionKind(h[1]); return; }
+    if (!line.trim()) return;
+    if (cur === 'summary') summaryParts.push(isBullet(line) ? stripBullet(line) : line.trim());
+    else if (cur === 'topics') { if (isBullet(line)) out.topics.push(demd(stripBullet(line))); }
+    else if (cur === 'moments') { if (isBullet(line)) { const b = momentBadge(stripBullet(line)); out.moments.push({ badge: b.badge, text: demd(b.text) }); } }
+    else if (cur === 'links') {
+      if (isBullet(line)) {
+        const value = demd(stripBullet(line));
+        if (value && !/^no shared links\.?$/i.test(value)) out.links.push(value);
+      }
+    } else if (cur === 'actions') {
+      const m = line.match(/^\s*[-*+]\s*\[([ xX])\]\s*(.*)$/);
+      if (m) {
+        let text = m[2].trim(); let owner = ''; let due = '';
+        const ow = text.match(/_\(([^)]+)\)_|\(([^)]+)\)/);
+        if (ow) { owner = (ow[1] || ow[2] || '').trim(); text = text.replace(ow[0], '').trim(); }
+        const du = text.match(/[—-]\s*_?([^_]+?)_?\s*$/);
+        if (du && /due|\d|mon|tue|wed|thu|fri|sat|sun|jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec|today|tomorrow|eod|eow|next/i.test(du[1])) {
+          due = du[1].replace(/^due\s*/i, '').trim(); text = text.slice(0, du.index).trim();
+        }
+        out.actions.push({ text: demd(text), done: m[1].toLowerCase() === 'x', owner: demd(owner), due, lineIndex: idx });
+      } else if (isBullet(line)) out.actions.push({ text: demd(stripBullet(line)), done: false, owner: '', due: '', lineIndex: idx });
+    }
+  });
+  out.summary = demd(summaryParts.join(' ').trim());
+  out.hasAny = !!(out.summary || out.topics.length || out.moments.length || out.links.length || out.actions.length);
+  return out;
+}
+
+/** Action items grouped by owner, named owners first, "Unassigned" last. */
+export function groupActionsByOwner(actions) {
+  const groups = new Map();
+  (actions || []).forEach((action, index) => {
+    const owner = (action.owner || '').trim() || 'Unassigned';
+    if (!groups.has(owner)) groups.set(owner, { owner, items: [] });
+    groups.get(owner).items.push({ action, index });
+  });
+  return [...groups.values()].sort((a, b) => {
+    if (a.owner === 'Unassigned') return 1;
+    if (b.owner === 'Unassigned') return -1;
+    return a.owner.localeCompare(b.owner);
+  });
+}

package/meeting-shape.js

@@ -260,3 +260,23 @@ export function formatTalkTime(ms) {
   if (mins < 60) return `${mins} min`;
   return `${Math.floor(mins / 60)}h ${String(mins % 60).padStart(2, '0')}m`;
 }
+
+/**
+ * A "speaker" that is really an avatar URL. Some captures (Zoom among them) put the picture
+ * where the name goes, for a participant whose name was never captured. The URL is a fine
+ * identity — distinct people get distinct URLs, so the arithmetic above is right — but it
+ * is not a label, and printing it puts a tracking-shaped link in a legend. A chart calls
+ * such a speaker "Participant", numbered when there is more than one.
+ */
+export const isSpeakerImageValue = (value) => typeof value === 'string'
+  && /^https?:\/\/\S+$/i.test(value.trim())
+  && /\.(png|jpe?g|gif|webp|svg)(\?|#|$)|images\.zoom\.us|\/p\/v2\/|gravatar|avatar|googleusercontent|wbxcdn|teams\.(microsoft|live)/i.test(value);
+
+/** What to call each speaker on screen — names as they are, avatar URLs as "Participant n". */
+export function speakerLabeller(speakers) {
+  const names = (speakers || []).map((s) => (typeof s === 'string' ? s : s?.speaker));
+  const anon = names.filter(isSpeakerImageValue);
+  const numbered = anon.length > 1;
+  const index = new Map(anon.map((n, i) => [n, `Participant ${i + 1}`]));
+  return (name) => (isSpeakerImageValue(name) ? (numbered ? index.get(name) : 'Participant') : name);
+}

package/package.json

@@ -1,25 +1,29 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.72.0",
+  "version": "0.74.0",
   "description": "The canonical ChatPanel event-log and capability contracts \u2014 typed durable facts, clock-free deterministic linearization, schema upcasting, and the invariants the replay harness asserts. Pure, dependency-free ESM shared by the ChatPanel extension, gateway and bridge.",
   "type": "module",
   "main": "index.js",
   "exports": {
     ".": "./index.js",
     "./adapters.js": "./adapters.js",
+    "./adaptive-tool-policy.js": "./adaptive-tool-policy.js",
     "./attribution.js": "./attribution.js",
     "./backup-envelope.js": "./backup-envelope.js",
     "./capability.js": "./capability.js",
     "./citations.js": "./citations.js",
+    "./client-prefs.js": "./client-prefs.js",
+    "./context-attachments.js": "./context-attachments.js",
     "./cowriter-router.js": "./cowriter-router.js",
-    "./cowriter.js": "./cowriter.js",
     "./cowriter-writer.js": "./cowriter-writer.js",
+    "./cowriter.js": "./cowriter.js",
     "./curate.js": "./curate.js",
     "./distance.js": "./distance.js",
     "./entitlement.js": "./entitlement.js",
     "./entity.js": "./entity.js",
     "./event.js": "./event.js",
     "./extraction.js": "./extraction.js",
+    "./find-tool.js": "./find-tool.js",
     "./flowchart.js": "./flowchart.js",
     "./harness.js": "./harness.js",
     "./invariants.js": "./invariants.js",
@@ -31,9 +35,13 @@
     "./manifest.js": "./manifest.js",
     "./markdown-authoring.js": "./markdown-authoring.js",
     "./markdown-render.js": "./markdown-render.js",
+    "./mcp-client.js": "./mcp-client.js",
+    "./mcp-dispatch.js": "./mcp-dispatch.js",
     "./mcp-errors.js": "./mcp-errors.js",
+    "./mcp-manager.js": "./mcp-manager.js",
     "./media-transcript.js": "./media-transcript.js",
     "./meeting-analyzers.js": "./meeting-analyzers.js",
+    "./meeting-insights.js": "./meeting-insights.js",
     "./meeting-shape.js": "./meeting-shape.js",
     "./meeting-text.js": "./meeting-text.js",
     "./memory.js": "./memory.js",
@@ -52,7 +60,9 @@
     "./promotion.js": "./promotion.js",
     "./queue.js": "./queue.js",
     "./reach.js": "./reach.js",
+    "./recipe-tool.js": "./recipe-tool.js",
     "./recipe.js": "./recipe.js",
+    "./record-list.js": "./record-list.js",
     "./redaction-tokens.js": "./redaction-tokens.js",
     "./ref.js": "./ref.js",
     "./registry.js": "./registry.js",
@@ -82,34 +92,26 @@
     "./theme.js": "./theme.js",
     "./titles.js": "./titles.js",
     "./tool-discovery.js": "./tool-discovery.js",
+    "./tool-dispatch.js": "./tool-dispatch.js",
     "./tool-groups.js": "./tool-groups.js",
+    "./tool-hints.js": "./tool-hints.js",
     "./tool-need.js": "./tool-need.js",
     "./tool-result.js": "./tool-result.js",
     "./tool-round.js": "./tool-round.js",
     "./tool-schema.js": "./tool-schema.js",
     "./tool-traits.js": "./tool-traits.js",
+    "./toolset.js": "./toolset.js",
     "./trajectory.js": "./trajectory.js",
     "./upcast.js": "./upcast.js",
     "./vault.js": "./vault.js",
     "./view.js": "./view.js",
     "./voice-intents.js": "./voice-intents.js",
     "./voice-speaker.js": "./voice-speaker.js",
+    "./weather-tool.js": "./weather-tool.js",
     "./weather.js": "./weather.js",
-    "./web-search.js": "./web-search.js",
-    "./widget.js": "./widget.js",
-    "./toolset.js": "./toolset.js",
-    "./tool-dispatch.js": "./tool-dispatch.js",
-    "./find-tool.js": "./find-tool.js",
     "./web-search-tool.js": "./web-search-tool.js",
-    "./record-list.js": "./record-list.js",
-    "./meeting-insights.js": "./meeting-insights.js",
-    "./client-prefs.js": "./client-prefs.js",
-    "./tool-hints.js": "./tool-hints.js",
-    "./adaptive-tool-policy.js": "./adaptive-tool-policy.js",
-    "./mcp-client.js": "./mcp-client.js",
-    "./mcp-manager.js": "./mcp-manager.js",
-    "./weather-tool.js": "./weather-tool.js",
-    "./context-attachments.js": "./context-attachments.js"
+    "./web-search.js": "./web-search.js",
+    "./widget.js": "./widget.js"
   },
   "files": [
     "LICENSE",
@@ -122,8 +124,8 @@
     "client-prefs.js",
     "context-attachments.js",
     "cowriter-router.js",
-    "cowriter.js",
     "cowriter-writer.js",
+    "cowriter.js",
     "curate.js",
     "distance.js",
     "entitlement.js",
@@ -144,6 +146,7 @@
     "markdown-authoring.js",
     "markdown-render.js",
     "mcp-client.js",
+    "mcp-dispatch.js",
     "mcp-errors.js",
     "mcp-manager.js",
     "media-transcript.js",
@@ -166,6 +169,7 @@
     "promotion.js",
     "queue.js",
     "reach.js",
+    "recipe-tool.js",
     "recipe.js",
     "record-list.js",
     "redaction-tokens.js",

package/recipe-tool.js

@@ -0,0 +1,161 @@
+// The `recipe` tool — a workflow the model did once, kept as data, and run by name.
+//
+// The engine is @chatpanel/events recipe.js: a recipe is `call` / `parallel` / `batch` /
+// `pipeline` with `{ "$param": "x" }` slots, expanded, dry-run and run with no model in
+// the loop. What is here is the CONVERSATIONAL half the spine's amendment A2 asked for —
+// authored in chat, approved before it exists, declarative, never agent-written code:
+//
+//   save     the model proposes a recipe from what it just did ("you fetched two issues
+//            and compared them — keep that as `triage_pair`?"). The dry run is what the
+//            PERSON sees on the card: every step, every slot, every warning. Approval
+//            stores it; nothing runs.
+//   dry_run  the same report, on demand, for a saved recipe with real parameters.
+//   run      expand with the given parameters and execute through the turn's OWN toolset —
+//            so the destructive gate, redaction, the loop guard and the shield all apply
+//            to every step exactly as if the model had called it. A recipe composes calls;
+//            it is never a way around them.
+//
+// One registered tool, not three: a spec per verb is per-turn token cost on every armed
+// turn, and the description already lists the saved recipes by name and parameters, which
+// is the whole catalogue. Bound LATE to the toolset it lives in (`bind`), because the
+// toolset that runs its steps is the one it is a member of.
+//
+// Shared: the extension and the desktop arm the same tool over the same `recipes` prefs
+// section, so a recipe approved in one client runs in the other. The approval card and
+// the store are the host's (injected); everything the model sees is here.
+
+import { validateRecipe, expandRecipe, dryRunRecipe, runPlan, recipeParams, RECIPE_MODES } from './recipe.js';
+
+export const RECIPE_TOOL_NAME = 'recipe';
+
+const RECIPE_NAME_RE = /^[a-z][a-z0-9_-]{0,63}$/i;
+
+function catalogue(recipes) {
+  const list = (recipes || []).filter((r) => r && r.enabled !== false && r.name);
+  if (!list.length) return 'No recipes saved yet.';
+  return `Saved recipes: ${list.map((r) => {
+    const ps = recipeParams(r).map((p) => (p.required ? p.name : `${p.name}?`));
+    return `${r.name}(${ps.join(', ')})${r.description ? ` — ${r.description}` : ''}`;
+  }).join('; ')}.`;
+}
+
+/**
+ * One spec. The shape a model needs to `save` is spelled out once, compactly; the
+ * engine's validator names anything it got wrong.
+ */
+export function recipeToolSpec(recipes) {
+  return {
+    name: RECIPE_TOOL_NAME,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    description:
+      `Saved, repeatable tool workflows — run by name with no re-planning. ${catalogue(recipes)} `
+      + 'Actions: {"action":"run","name":"<recipe>","params":{…}} runs one; '
+      + '{"action":"dry_run","name":"<recipe>","params":{…}} shows what it would do without running; '
+      + '{"action":"save","recipe":{…}} proposes a NEW one after you have done a multi-step task the '
+      + 'user may repeat — the user approves it on a card. A recipe: {"name":"open_bug","description":"…",'
+      + '"mode":"call","tool":"<tool name, e.g. mcp_github__create_issue>","arguments":{"title":{"$param":"title"},"labels":["bug"]}}. '
+      + `Modes: ${RECIPE_MODES.join(' | ')} — parallel takes "calls":[{tool,arguments}], batch takes "tool"+"items":[{arguments}], `
+      + 'pipeline takes "steps":[{tool,arguments,inputMapping:{arg:"$json.path"|"$text"}}]. '
+      + 'Use {"$param":"x"} for anything the user will supply each time; a "default" makes it optional.',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['run', 'dry_run', 'save'] },
+        name: { type: 'string', description: 'Recipe name, for run / dry_run.' },
+        params: { type: 'object', description: 'Parameter values, for run / dry_run.', additionalProperties: true },
+        recipe: { type: 'object', description: 'The recipe to save, for save.', additionalProperties: true },
+      },
+      required: ['action'],
+    },
+  };
+}
+
+/** The card a person approves: what it does, step by step, and what the dry run flagged. */
+export function describeRecipeForApproval(recipe, report) {
+  const lines = [`${recipe.name}${recipe.description ? ` — ${recipe.description}` : ''}`, `Mode: ${recipe.mode}`];
+  const ps = recipeParams(recipe);
+  if (ps.length) lines.push(`Parameters: ${ps.map((p) => (p.required ? p.name : `${p.name} (optional)`)).join(', ')}`);
+  const calls = report?.calls || [];
+  calls.forEach((c, i) => {
+    const args = JSON.stringify(c.arguments);
+    lines.push(`${calls.length > 1 ? `${i + 1}. ` : ''}${c.tool}${args && args !== '{}' ? ` ${args.length > 140 ? `${args.slice(0, 137)}…` : args}` : ''}${c.mappedLater?.length ? ` (+ ${c.mappedLater.join(', ')} from the previous step)` : ''}`);
+  });
+  for (const w of report?.warnings || []) lines.push(`⚠ ${w.message}`);
+  lines.push('Saved recipes run with no further planning; destructive steps still ask each time.');
+  return lines.join('\n');
+}
+
+const json = (v) => JSON.stringify(v);
+
+/**
+ * @param recipes     the saved list (settings.recipes)
+ * @param confirmSave async (detail, recipe) => 'allow' | 'deny' — the surface's card. Absent on a
+ *                    surface with no window: `save` is then refused, `run` still works.
+ * @param saveRecipe  async (recipe) => void — persist an approved one
+ */
+export function recipeToolProvider({ recipes = [], confirmSave = null, saveRecipe = null } = {}) {
+  let bound = null; // { execute, specs, traits, hiddenVia }
+  const byName = new Map((recipes || []).filter((r) => r?.name && r.enabled !== false).map((r) => [r.name, r]));
+
+  // Steps name REAL tools; a tool that lives behind a dispatcher (`mcp_gh__get_issue`
+  // behind `mcp`) is reached through it, so every guard that keys on the action fires.
+  const execute = (tool, args, meta) => {
+    if (!bound) return json({ error: 'The recipe tool is not bound to a toolset yet.' });
+    const via = bound.hiddenVia?.get(tool);
+    return via ? bound.execute(via, { action: tool, args }, meta) : bound.execute(tool, args, meta);
+  };
+  const specsForDryRun = () => (bound ? [...(bound.specs || []), ...(bound.reach || [])].filter((s) => s?.name !== RECIPE_TOOL_NAME) : null);
+  const traitsOf = (tool) => bound?.traits?.get(tool) || null;
+
+  return {
+    id: 'recipe',
+    specs: [recipeToolSpec(recipes)],
+    system: byName.size ? 'Saved recipes exist (see the `recipe` tool). When the user asks for one by name or describes what one does, run it rather than re-planning the steps.' : '',
+    bind(toolset) {
+      bound = { execute: toolset.execute.bind(toolset), specs: toolset.specs, reach: toolset.reach, traits: toolset.traits, hiddenVia: toolset.hiddenVia };
+    },
+    async execute(name, input) {
+      if (name !== RECIPE_TOOL_NAME) return json({ error: `Unknown tool: ${name}` });
+      const action = String(input?.action || '');
+
+      if (action === 'save') {
+        const recipe = input?.recipe;
+        const v = validateRecipe(recipe);
+        if (!v.ok) return json({ error: 'The recipe is not valid.', problems: v.errors });
+        if (!RECIPE_NAME_RE.test(recipe.name)) return json({ error: 'name must be a short identifier: letters, digits, _ or -.' });
+        if (byName.has(recipe.name)) return json({ error: `A recipe named "${recipe.name}" already exists. Pick another name.` });
+        if (!confirmSave || !saveRecipe) return json({ error: 'Saving a recipe needs the user\'s approval, which this surface cannot ask for. Describe the recipe to the user and suggest saving it from the side panel.' });
+        const report = dryRunRecipe(recipe, {}, { specs: specsForDryRun(), traitsOf: bound ? (t) => traitsOf(t) || undefined : null });
+        // Missing parameters are the POINT of a template; only structural problems block.
+        const blocking = (report.warnings || []).filter((w) => w.code === 'unknown_tool');
+        if (blocking.length) return json({ error: 'The recipe names tools that are not available in this conversation.', problems: blocking.map((w) => w.message) });
+        const detail = describeRecipeForApproval(recipe, report);
+        const decision = await confirmSave(detail, recipe);
+        if (decision !== 'allow') return json({ error: `The user did not save "${recipe.name}". Do not propose it again this turn.`, declined: true });
+        const stored = { ...recipe, enabled: true, createdAt: Date.now() };
+        await saveRecipe(stored);
+        byName.set(stored.name, stored);
+        return json({ saved: stored.name, params: recipeParams(stored).map((p) => p.name), hint: `Run it later with {"action":"run","name":"${stored.name}","params":{…}} or by typing /${stored.name}.` });
+      }
+
+      const recipe = byName.get(String(input?.name || ''));
+      if (!recipe) return json({ error: `No recipe named "${input?.name}".`, available: [...byName.keys()] });
+      const params = input?.params && typeof input.params === 'object' ? input.params : {};
+
+      if (action === 'dry_run') {
+        const report = dryRunRecipe(recipe, params, { specs: specsForDryRun(), traitsOf: bound ? (t) => traitsOf(t) || undefined : null });
+        return json({ name: recipe.name, ok: report.ok, missing: report.missing, calls: report.calls.map((c) => ({ tool: c.tool, arguments: c.arguments, known: c.known, destructive: c.traits?.destructive === true, mappedLater: c.mappedLater })), warnings: report.warnings });
+      }
+
+      if (action === 'run') {
+        const ex = expandRecipe(recipe, params);
+        if (!ex.plan) return json({ error: 'The saved recipe is not valid.', problems: ex.errors });
+        if (!ex.ok) return json({ error: `Missing parameter(s): ${ex.missing.join(', ')}.`, params: recipeParams(recipe) });
+        const result = await runPlan(ex.plan, { execute, traitsOf: (t) => traitsOf(t) || undefined });
+        return json({ name: recipe.name, ...result });
+      }
+
+      return json({ error: `Unknown action "${action}". Use run, dry_run or save.` });
+    },
+  };
+}