@chatpanel/events 0.73.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';

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/package.json

@@ -1,25 +1,29 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.73.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.` });
+    },
+  };
+}