@chatpanel/events 0.73.0 → 0.75.0

package/budget.js

@@ -0,0 +1,110 @@
+// A budget — the number a run may not exceed, and the record of what it spent.
+//
+// There was no spend cap anywhere. A live monitor is declared class C and starts model turns
+// for the length of a meeting; a spoken "keep an eye on X" arms that with nothing bounding
+// it; `jobs.js` caps a per-day job COUNT, not spend. The class declarations on every intent
+// and rule were made for exactly this, and nothing read them.
+//
+// A budget is a VALUE: declared on the thing that spends (a team, a schedule, a monitor),
+// charged by whatever runs it, and carried on the run record so the ledger can say what a
+// run cost in the same units it was capped in. Four dimensions, because the expensive thing
+// differs by executor: tokens and calls for a model, wall time for an agent that thinks for
+// minutes, cost when the gateway can report it. Any dimension may be absent; an absent one is
+// not enforced. A budget with NO dimension is not a budget — `validateBudget` refuses it, and
+// a team without one does not run (F8, O1).
+//
+// Pure. `now` is injected so a wall-time cap is testable.
+
+export const BUDGET_DIMENSIONS = Object.freeze(['tokens', 'calls', 'ms', 'usd']);
+
+export class BudgetError extends Error {
+  constructor(code, message) { super(message); this.name = 'BudgetError'; this.code = code; }
+}
+
+/** `{ ok, errors }` — a budget must cap at least one thing, and every cap must be a positive number. */
+export function validateBudget(b) {
+  const errors = [];
+  if (!b || typeof b !== 'object') return { ok: false, errors: ['budget must be an object'] };
+  let any = false;
+  for (const k of BUDGET_DIMENSIONS) {
+    if (b[k] === undefined || b[k] === null) continue;
+    const n = Number(b[k]);
+    if (!Number.isFinite(n) || n <= 0) errors.push(`${k}: a positive number`);
+    else any = true;
+  }
+  for (const k of Object.keys(b)) if (!BUDGET_DIMENSIONS.includes(k)) errors.push(`${k}: not a budget dimension (${BUDGET_DIMENSIONS.join(', ')})`);
+  if (!any) errors.push('a budget must cap at least one of tokens, calls, ms, usd');
+  return { ok: errors.length === 0, errors };
+}
+
+/** Only the declared dimensions, as numbers. */
+export function normalizeBudget(b) {
+  const out = {};
+  for (const k of BUDGET_DIMENSIONS) {
+    const n = Number(b?.[k]);
+    if (Number.isFinite(n) && n > 0) out[k] = n;
+  }
+  return out;
+}
+
+/**
+ * The usage a model call reports, in the shapes the providers use, as one record:
+ * `{ tokens, calls, usd }`. `ms` is measured by the budget itself.
+ */
+export function usageOf(u = {}) {
+  const tokens = Number(u.tokens ?? u.total_tokens ?? ((Number(u.input_tokens ?? u.prompt_tokens) || 0) + (Number(u.output_tokens ?? u.completion_tokens) || 0)));
+  return { tokens: Number.isFinite(tokens) ? tokens : 0, calls: Number(u.calls ?? 1) || 0, usd: Number(u.usd ?? u.cost) || 0 };
+}
+
+/**
+ * A live budget for one run.
+ *
+ *   charge(usage)        add a model call's usage; returns what is left
+ *   canAfford(estimate)  false when an estimated call would cross a cap — ask BEFORE calling
+ *   exhausted()          the dimension that ran out, or null
+ *   snapshot()           { cap, spent, remaining, exhausted } for the run record and the meter
+ */
+export function createBudget(declared, { now = () => Date.now() } = {}) {
+  const v = validateBudget(declared);
+  if (!v.ok) throw new BudgetError('INVALID', v.errors.join('; '));
+  const cap = normalizeBudget(declared);
+  const startedAt = now();
+  const spent = { tokens: 0, calls: 0, usd: 0 };
+  const elapsed = () => now() - startedAt;
+  const remaining = () => {
+    const out = {};
+    for (const k of BUDGET_DIMENSIONS) {
+      if (cap[k] === undefined) continue;
+      out[k] = Math.max(0, cap[k] - (k === 'ms' ? elapsed() : spent[k]));
+    }
+    return out;
+  };
+  const exhausted = () => {
+    for (const k of BUDGET_DIMENSIONS) {
+      if (cap[k] === undefined) continue;
+      if ((k === 'ms' ? elapsed() : spent[k]) >= cap[k]) return k;
+    }
+    return null;
+  };
+  return {
+    cap,
+    charge(usage) {
+      const u = usageOf(usage);
+      spent.tokens += u.tokens; spent.calls += u.calls; spent.usd += u.usd;
+      return remaining();
+    },
+    canAfford(estimate = {}) {
+      if (exhausted()) return false;
+      const e = usageOf({ calls: 1, ...estimate });
+      for (const k of ['tokens', 'calls', 'usd']) {
+        if (cap[k] !== undefined && spent[k] + e[k] > cap[k]) return false;
+      }
+      return true;
+    },
+    remaining,
+    exhausted,
+    snapshot() {
+      return { cap, spent: { ...spent, ms: elapsed() }, remaining: remaining(), exhausted: exhausted() };
+    },
+  };
+}

package/client-prefs.js

@@ -22,6 +22,7 @@ export const PREF_SECTIONS = Object.freeze([
   { id: 'skills', label: 'Skills', path: ['skills'], kind: 'array' },
   { id: 'skillDirs', label: 'Skill folders', path: ['ui', 'skillDirs'], kind: 'array' },
   { id: 'recipes', label: 'Recipes', path: ['recipes'], kind: 'array' },
+  { id: 'teams', label: 'Agent teams', path: ['teams'], kind: 'array' },
   { id: 'webSearch', label: 'Web search', path: ['ui', 'webSearch'], kind: 'object' },
   { id: 'tools', label: 'Tools', path: null, kind: 'object', keys: ['mcpToolsMode', 'maxToolsPerTurn', 'historyTools', 'historyContextMode', 'dataDispatch', 'toolResultMaxChars'] },
   { id: 'suggestions', label: 'Smart suggestions', path: ['ui', 'suggestions'], kind: 'object' },

package/index.js

@@ -188,6 +188,16 @@ 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';
+// Agent teams (F8): a team is data, a run is a turn of turns under a budget, members talk
+// through a typed board, nothing lands without a person.
+export { createBudget, validateBudget, normalizeBudget, usageOf, BudgetError, BUDGET_DIMENSIONS } from './budget.js';
+export { defineTeam, validateTeam, normalizeTeam, normalizeGrants, grantAllows, describeRole, TeamError, ROLE_MODES, MERGE_POLICIES, PLAN_MODES, GRANTABLE } from './team.js';
+export { fixedPlan, parsePlan, plannerPrompt, waves, breakCycles, TEAM_PLAN_SCHEMA } from './team-plan.js';
+export { createBoard, parseFindings, boardText, findingsInstruction, toBriefClaims, FINDINGS_SCHEMA, FINDING_KINDS } from './team-board.js';
+export { runTeam, dryRunTeam, TeamRunError, RUN_STATUSES } from './team-run.js';
+export { teamToolProvider, teamToolSpec, describeTeamForApproval, TEAM_TOOL_NAME } from './team-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,30 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.73.0",
+  "version": "0.75.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",
+    "./budget.js": "./budget.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 +36,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 +61,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",
@@ -78,38 +89,35 @@
     "./sync-plan.js": "./sync-plan.js",
     "./synthesis.js": "./synthesis.js",
     "./tags.js": "./tags.js",
+    "./team-board.js": "./team-board.js",
+    "./team-plan.js": "./team-plan.js",
+    "./team-run.js": "./team-run.js",
+    "./team-tool.js": "./team-tool.js",
+    "./team.js": "./team.js",
     "./text-search.js": "./text-search.js",
     "./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",
@@ -117,13 +125,14 @@
     "adapters.js",
     "adaptive-tool-policy.js",
     "backup-envelope.js",
+    "budget.js",
     "capability.js",
     "citations.js",
     "client-prefs.js",
     "context-attachments.js",
     "cowriter-router.js",
-    "cowriter.js",
     "cowriter-writer.js",
+    "cowriter.js",
     "curate.js",
     "distance.js",
     "entitlement.js",
@@ -144,6 +153,7 @@
     "markdown-authoring.js",
     "markdown-render.js",
     "mcp-client.js",
+    "mcp-dispatch.js",
     "mcp-errors.js",
     "mcp-manager.js",
     "media-transcript.js",
@@ -166,6 +176,7 @@
     "promotion.js",
     "queue.js",
     "reach.js",
+    "recipe-tool.js",
     "recipe.js",
     "record-list.js",
     "redaction-tokens.js",
@@ -192,6 +203,11 @@
     "sync-plan.js",
     "synthesis.js",
     "tags.js",
+    "team-board.js",
+    "team-plan.js",
+    "team-run.js",
+    "team-tool.js",
+    "team.js",
     "text-search.js",
     "theme.js",
     "titles.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.` });
+    },
+  };
+}

package/team-board.js

@@ -0,0 +1,123 @@
+// The board — what a team's members say to each other, as typed findings, not talk.
+//
+// Members do not read each other's transcripts. A task ends with FINDINGS: claims with the
+// refs they came from (the brief shape, I-K1), drafts, links, questions. A later task reads
+// the board, sized like a shielded tool result so a long-running team does not feed a
+// later member forty thousand characters of earlier members. The board is the run's record:
+// durable, attributable per role, and — after a run — the thing that can become draft
+// briefs and be promoted on convergence (W7), rather than evaporating with the run.
+//
+// Findings are parsed GENEROUSLY from a model's answer through the structured layer, and a
+// task whose answer cannot be read as findings is not lost: its whole answer becomes one
+// `draft` finding. A member that only wrote prose still contributed.
+
+import { defineSchema, describeSchema, coerce } from './structured.js';
+
+export const FINDING_KINDS = Object.freeze(['claim', 'draft', 'link', 'question', 'answer']);
+export const MAX_FINDINGS_PER_TASK = 40;
+export const BOARD_TEXT_MAX = 12_000;
+
+export const FINDINGS_SCHEMA = defineSchema({
+  name: 'findings',
+  purpose: 'what this task established, each item on its own with where it came from',
+  fields: {
+    findings: {
+      type: 'object[]', required: true, maxItems: MAX_FINDINGS_PER_TASK,
+      describe: 'one entry per fact, draft, link or open question — never a paragraph of several',
+      fields: {
+        kind: { type: 'enum', values: FINDING_KINDS, default: 'claim' },
+        text: { type: 'string', required: true, max: 2000 },
+        refs: { type: 'string[]', maxItems: 8, describe: 'record ids or URLs this rests on, when any' },
+        confidence: { type: 'number', describe: '0–1, how sure' },
+      },
+    },
+  },
+  nothing: { findings: [] },
+});
+
+/** The instruction appended to every task so the answer can be read as findings. */
+export function findingsInstruction() {
+  return `When you are done, end your answer with your findings in this shape:\n${describeSchema(FINDINGS_SCHEMA)}`;
+}
+
+/**
+ * Read a task's answer into findings. The JSON block, when present; otherwise the whole
+ * answer as one draft — a member that only wrote prose still contributed.
+ */
+export function parseFindings(text, { role, taskId } = {}) {
+  const raw = String(text || '').trim();
+  if (!raw) return [];
+  const got = coerce(raw, FINDINGS_SCHEMA);
+  const list = Array.isArray(got?.value?.findings) ? got.value.findings.filter((f) => f && String(f.text || '').trim()) : [];
+  const stamp = (f, i) => ({
+    id: `${taskId || 't'}:${i + 1}`,
+    kind: FINDING_KINDS.includes(f.kind) ? f.kind : 'claim',
+    text: String(f.text).trim().slice(0, 2000),
+    refs: Array.isArray(f.refs) ? f.refs.map(String).filter(Boolean).slice(0, 8) : [],
+    // Absent or zero reads as "not stated": a model that gives no number is not 0% sure.
+    confidence: Number.isFinite(Number(f.confidence)) && Number(f.confidence) > 0 ? Math.min(1, Number(f.confidence)) : null,
+    role: role || null,
+    taskId: taskId || null,
+  });
+  if (list.length) return list.slice(0, MAX_FINDINGS_PER_TASK).map(stamp);
+  // No JSON block: the prose is the finding. Strip a fenced JSON tail that failed to parse.
+  const prose = raw.replace(/```json[\s\S]*$/i, '').trim() || raw;
+  return [stamp({ kind: 'draft', text: prose.slice(0, 2000), refs: [] }, 0)];
+}
+
+export function createBoard({ now = () => Date.now() } = {}) {
+  const findings = [];
+  const listeners = new Set();
+  return {
+    add(list) {
+      const at = now();
+      for (const f of Array.isArray(list) ? list : [list]) {
+        if (!f || !f.text) continue;
+        const entry = { ...f, at };
+        findings.push(entry);
+        for (const l of listeners) l(entry);
+      }
+      return findings.length;
+    },
+    all: () => [...findings],
+    byTask: (taskId) => findings.filter((f) => f.taskId === taskId),
+    byRole: (role) => findings.filter((f) => f.role === role),
+    onFinding(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+    get size() { return findings.length; },
+  };
+}
+
+/**
+ * What a later task READS: the findings of the tasks it depends on (or everything so far),
+ * sized. Newest are kept whole; the oldest are what get cut, and the cut is stated.
+ */
+export function boardText(findings, { taskIds = null, max = BOARD_TEXT_MAX } = {}) {
+  const list = (findings || []).filter((f) => !taskIds || taskIds.includes(f.taskId));
+  if (!list.length) return '';
+  const lines = list.map((f) => `- [${f.kind}${f.role ? ` · ${f.role}` : ''}${f.confidence != null ? ` · ${Math.round(f.confidence * 100)}%` : ''}] ${f.text}${f.refs?.length ? ` (refs: ${f.refs.join(', ')})` : ''}`);
+  let out = lines.join('\n');
+  if (out.length <= max) return `Findings so far:\n${out}`;
+  let kept = [];
+  let size = 0;
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    if (size + lines[i].length + 1 > max) break;
+    kept.unshift(lines[i]);
+    size += lines[i].length + 1;
+  }
+  return `Findings so far (${lines.length - kept.length} earlier ones omitted for length):\n${kept.join('\n')}`;
+}
+
+/** Findings → the claim shape a draft brief takes (W7): text + refs as `{ kind, id }`. */
+export function toBriefClaims(findings) {
+  return (findings || [])
+    .filter((f) => f.kind === 'claim' && f.text)
+    .map((f) => ({
+      text: f.text,
+      refs: (f.refs || []).map((r) => {
+        const m = /^([a-z][a-z0-9_-]*):(?!\/\/)(.+)$/.exec(String(r));
+        return m ? { kind: m[1], id: m[2] } : { kind: 'url', id: String(r) };
+      }),
+      by: f.role || 'team',
+      confidence: f.confidence,
+    }));
+}

package/team-plan.js

@@ -0,0 +1,121 @@
+// Planning a run: which tasks, for which roles, in what order.
+//
+// Two ways. `fixed` — one task per role, each given the request and its own prompt, run in
+// declaration order with the dependencies the roles declare; no model is asked how to
+// split the work, so the plan is free and reproducible. `planner` — the strongest appointed
+// role is asked, through the shared structured layer (never a hand-typed JSON prompt), to
+// break the request into tasks and assign each to a role it may use. A planner that returns
+// nothing readable falls back to the fixed plan, which is why a run can always start.
+//
+// A task's `dependsOn` is what the fan-out turns into barriers: a task with no unmet
+// dependency runs alongside the others (the round's pool), a dependent one waits and reads
+// the board. That is the whole scheduling model — the same one a tool round uses.
+
+import { defineSchema, describeSchema, coerce } from './structured.js';
+
+export const MAX_TASKS = 12;
+
+export const TEAM_PLAN_SCHEMA = defineSchema({
+  name: 'team_plan',
+  purpose: 'the tasks a team will run for a request, each assigned to one role',
+  fields: {
+    tasks: {
+      type: 'object[]', required: true, maxItems: MAX_TASKS,
+      describe: 'concrete, independent where possible; a task that needs another\'s result names it in dependsOn',
+      fields: {
+        id: { type: 'string', required: true, max: 32, describe: 'a short id like t1' },
+        role: { type: 'string', required: true, max: 32, describe: 'the id of the role that runs it' },
+        title: { type: 'string', required: true, max: 80 },
+        prompt: { type: 'string', required: true, max: 1200, describe: 'the focused instruction for this task' },
+        dependsOn: { type: 'string[]', maxItems: 6, describe: 'task ids whose findings this one needs' },
+      },
+    },
+  },
+  nothing: { tasks: [] },
+});
+
+/** The planner's instruction — the request, the roles it may use, the shape it must answer in. */
+export function plannerPrompt(team, request) {
+  const roles = (team.roles || []).map((r) => `- ${r.id}: ${r.name || r.id} — ${r.prompt.slice(0, 200)}${r.grants?.length ? ` (tools: ${r.grants.join(', ')})` : ''}`).join('\n');
+  return [
+    `You are the planner of a team named "${team.name}". Break the request into 2–${Math.min(MAX_TASKS, Math.max(2, (team.roles || []).length * 2))} tasks and assign each to ONE of these roles by id:`,
+    roles,
+    '',
+    `Request: ${String(request || '').trim()}`,
+    '',
+    'Prefer tasks that can run at the same time; use dependsOn only when a task truly needs another\'s findings. Do not assign a role a task it has no tools for.',
+    '',
+    describeSchema(TEAM_PLAN_SCHEMA),
+  ].join('\n');
+}
+
+/** One task per role, in declaration order, with the roles' own dependencies. */
+export function fixedPlan(team, request) {
+  const req = String(request || '').trim();
+  return (team.roles || []).map((r) => ({
+    id: `t_${r.id}`,
+    role: r.id,
+    title: r.name || r.id,
+    prompt: r.prompt ? `${r.prompt}\n\nRequest: ${req}` : req,
+    dependsOn: (r.dependsOn || []).map((d) => `t_${d}`),
+  }));
+}
+
+/**
+ * Read a planner's answer into tasks, dropping what cannot run: an unknown role, a
+ * dependency on nothing, a cycle. Returns [] when nothing survives, so the caller falls back.
+ */
+export function parsePlan(text, team) {
+  const got = coerce(text, TEAM_PLAN_SCHEMA);
+  const roles = new Set((team.roles || []).map((r) => r.id));
+  const raw = Array.isArray(got?.value?.tasks) ? got.value.tasks : [];
+  const tasks = raw
+    .filter((t) => t && roles.has(String(t.role || '')) && String(t.prompt || '').trim())
+    .map((t, i) => ({
+      id: String(t.id || `t${i + 1}`).replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 32) || `t${i + 1}`,
+      role: String(t.role),
+      title: String(t.title || t.prompt).slice(0, 80),
+      prompt: String(t.prompt).trim(),
+      dependsOn: Array.isArray(t.dependsOn) ? t.dependsOn.map(String) : [],
+    }))
+    .slice(0, MAX_TASKS);
+  const ids = new Set(tasks.map((t) => t.id));
+  for (const t of tasks) t.dependsOn = t.dependsOn.filter((d) => ids.has(d) && d !== t.id);
+  return breakCycles(tasks);
+}
+
+/** A task whose dependencies cannot all be satisfied loses them, rather than never running. */
+export function breakCycles(tasks) {
+  const byId = new Map(tasks.map((t) => [t.id, t]));
+  const state = new Map(); // id -> 'visiting' | 'done'
+  const visit = (t, stack) => {
+    if (state.get(t.id) === 'done') return;
+    if (state.get(t.id) === 'visiting') return;
+    state.set(t.id, 'visiting');
+    t.dependsOn = t.dependsOn.filter((d) => {
+      const dep = byId.get(d);
+      if (!dep) return false;
+      if (state.get(d) === 'visiting' || stack.has(d)) return false; // a cycle: drop the edge
+      visit(dep, new Set([...stack, t.id]));
+      return true;
+    });
+    state.set(t.id, 'done');
+  };
+  for (const t of tasks) visit(t, new Set());
+  return tasks;
+}
+
+/** Tasks in waves: everything runnable now, then what those unblock — the barrier order. */
+export function waves(tasks) {
+  const out = [];
+  const done = new Set();
+  let rest = [...tasks];
+  while (rest.length) {
+    const ready = rest.filter((t) => (t.dependsOn || []).every((d) => done.has(d)));
+    if (!ready.length) { out.push(rest); break; } // cannot happen after breakCycles; never loop forever
+    out.push(ready);
+    for (const t of ready) done.add(t.id);
+    rest = rest.filter((t) => !done.has(t.id));
+  }
+  return out;
+}

package/team-run.js

@@ -0,0 +1,209 @@
+// A run — a turn of turns: plan, fan out, merge, propose. One runner for every client.
+//
+// The runner never speaks to a model and never runs a tool. `callModel` is the host's own
+// model turn (the extension's streamChat, the desktop's gateway call — redaction on the way
+// out, restore on the way back, the tool loop with its round, shield and gate inside it);
+// `toolsFor(role)` is the host's own toolset narrowed to the role's grants. A team therefore
+// cannot reach what a single turn cannot, and every guard a client earned stays in force.
+//
+// Tasks run in WAVES (team-plan.js): everything with its dependencies met runs together
+// through the same pool a tool round uses; a dependent task waits and reads the board. A
+// task ends with findings; the merge turns the board into ONE proposal — agreed claims
+// (converge, W7), a judged answer, or the members' work side by side — and the proposal is
+// what a person sees. Nothing here lands anywhere.
+//
+// Budget first. `createBudget` refuses a team without one; before every model call the run
+// asks `canAfford`, and a run that cannot afford its next call stops with what it has and
+// says so (`status: 'over-budget'`). Stop is one signal, fanned out.
+
+import { normalizeTeam } from './team.js';
+import { createBudget } from './budget.js';
+import { fixedPlan, plannerPrompt, parsePlan, waves } from './team-plan.js';
+import { createBoard, parseFindings, boardText, findingsInstruction, toBriefClaims } from './team-board.js';
+import { converge } from './promotion.js';
+
+export const RUN_STATUSES = Object.freeze(['planning', 'running', 'merging', 'completed', 'partial', 'over-budget', 'stopped', 'failed']);
+const DEFAULT_CONCURRENCY = 3;
+
+export class TeamRunError extends Error {
+  constructor(code, message) { super(message); this.name = 'TeamRunError'; this.code = code; }
+}
+
+async function pool(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  const worker = async () => { while (next < items.length) { const i = next++; out[i] = await fn(items[i], i); } };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) || 1 }, worker));
+  return out;
+}
+
+const TIER = { cheap: 0, balanced: 1, strong: 2 };
+const strongestRole = (team) => [...team.roles].sort((a, b) => (TIER[b.prefer] ?? 1) - (TIER[a.prefer] ?? 1))[0];
+
+/**
+ * What a person sees before approving a run: every role with the model it would get, its
+ * grants and mode; the plan when it is fixed (a planner plans at run time); the budget.
+ */
+export function dryRunTeam(team, request, { appoint = null } = {}) {
+  const t = normalizeTeam(team);
+  const roles = t.roles.map((r) => {
+    const a = appoint ? appoint(r) : null;
+    return { id: r.id, name: r.name, mode: r.mode, prefer: r.prefer, model: a?.model || r.model || null, appointed: !!(a?.model || r.model), grants: r.grants, ...(r.recipe ? { recipe: r.recipe } : {}) };
+  });
+  const missing = roles.filter((r) => r.mode !== 'recipe' && !r.appointed).map((r) => r.id);
+  return {
+    name: t.name, description: t.description, plan: t.plan, merge: t.merge, judge: t.judge, budget: t.budget, roles,
+    tasks: t.plan === 'fixed' ? fixedPlan(t, request) : null,
+    ok: missing.length === 0,
+    missing,
+  };
+}
+
+/**
+ * @param callModel  `async ({ runId, taskId, role, model, mode, system, prompt, tools, signal, onDelta }) =>
+ *                   { ok, text, usage?, error?, aborted? }` — the host's model turn
+ * @param toolsFor   `(role) => toolset | undefined` — narrowed to the role's grants by the host
+ * @param appoint    `(role) => { model, mode } | null` — the host's roster through cowriter-router
+ * @param runRecipe  `async (name, params) => result` for `mode: 'recipe'` roles (optional)
+ * @param emit       `(type, payload)` — run.started · plan.ready · task.started · task.finding ·
+ *                   task.done · task.failed · run.merging · run.done; the host forwards them to
+ *                   its UI and to the gateway's run store
+ */
+export async function runTeam({
+  team, request, callModel, toolsFor = () => undefined, appoint = null, runRecipe = null,
+  now = () => Date.now(), newId = () => `run_${Math.random().toString(36).slice(2, 10)}`,
+  emit = () => {}, signal = null, maxConcurrency = DEFAULT_CONCURRENCY, runId = null,
+} = {}) {
+  if (typeof callModel !== 'function') throw new TeamRunError('BAD_RUN', 'callModel required');
+  const t = normalizeTeam(team); // throws on a team without a budget — O1
+  const id = runId || newId();
+  const budget = createBudget(t.budget, { now });
+  const board = createBoard({ now });
+  const startedAt = now();
+  const tasksOut = [];
+  const say = (type, payload = {}) => emit(type, { runId: id, at: now(), ...payload });
+  const roleOf = (rid) => t.roles.find((r) => r.id === rid);
+  const modelFor = (r) => (appoint ? appoint(r) : null) || (r.model ? { model: r.model, mode: r.mode } : null);
+  const stopped = () => !!signal?.aborted;
+
+  say('run.started', { team: t.name, request: String(request || ''), budget: t.budget, roles: t.roles.map((r) => r.id) });
+
+  // ── plan ──────────────────────────────────────────────────────────────────────────────
+  let tasks;
+  let planBy = 'fixed';
+  if (t.plan === 'planner') {
+    const planner = strongestRole(t);
+    const m = modelFor(planner);
+    if (m && budget.canAfford({ tokens: 0 })) {
+      const res = await callModel({ runId: id, taskId: 'plan', role: planner.id, model: m.model, mode: 'model', system: '', prompt: plannerPrompt(t, request), tools: undefined, signal });
+      if (res?.usage) budget.charge(res.usage);
+      const parsed = res?.ok ? parsePlan(res.text, t) : [];
+      if (parsed.length) { tasks = parsed; planBy = 'planner'; }
+    }
+  }
+  if (!tasks) tasks = fixedPlan(t, request);
+  say('plan.ready', { by: planBy, tasks: tasks.map((x) => ({ id: x.id, role: x.role, title: x.title, dependsOn: x.dependsOn })) });
+
+  const finish = (status, extra = {}) => {
+    const usage = budget.snapshot();
+    const out = { runId: id, team: t.name, status, plan: { by: planBy, tasks }, tasks: tasksOut, board: board.all(), usage, startedAt, endedAt: now(), ...extra };
+    say('run.done', { status, usage, proposal: out.proposal || null, failedTaskIds: tasksOut.filter((x) => x.status === 'failed').map((x) => x.id) });
+    return out;
+  };
+
+  // ── fan out, in waves ─────────────────────────────────────────────────────────────────
+  let overBudget = false;
+  for (const wave of waves(tasks)) {
+    if (stopped() || overBudget) break;
+    await pool(wave, maxConcurrency, async (task) => {
+      if (stopped() || overBudget) { tasksOut.push({ id: task.id, role: task.role, status: 'skipped', text: '', findings: [] }); return; }
+      const role = roleOf(task.role);
+      const t0 = now();
+      say('task.started', { taskId: task.id, role: task.role, title: task.title });
+      let text = '';
+      let usage = null;
+      let status = 'ok';
+      let error = null;
+      try {
+        if (role.mode === 'recipe') {
+          if (typeof runRecipe !== 'function') throw new Error('this host cannot run recipes');
+          const r = await runRecipe(role.recipe, { request: String(request || ''), task: task.prompt });
+          text = typeof r === 'string' ? r : JSON.stringify(r);
+        } else {
+          const m = modelFor(role);
+          if (!m?.model) throw new Error(`no model for role "${role.id}"`);
+          // A call's tokens are unknown until it returns; what can be asked beforehand is
+          // whether the budget is already exhausted and whether one more call is allowed.
+          if (!budget.canAfford({ tokens: 0 })) { overBudget = true; throw new Error('over budget'); }
+          const prior = boardText(board.all(), { taskIds: task.dependsOn?.length ? task.dependsOn : null });
+          const prompt = [task.prompt, prior, findingsInstruction()].filter(Boolean).join('\n\n');
+          const res = await callModel({
+            runId: id, taskId: task.id, role: role.id, model: m.model, mode: m.mode || role.mode,
+            system: role.prompt, prompt, tools: toolsFor(role), signal,
+            onDelta: (delta, full) => say('task.delta', { taskId: task.id, role: role.id, delta, text: full }),
+          });
+          usage = res?.usage || null;
+          if (usage) budget.charge(usage);
+          if (res?.aborted) { status = 'stopped'; }
+          else if (!res?.ok) throw new Error(res?.error || 'the model did not answer');
+          text = String(res?.text || '');
+        }
+      } catch (e) {
+        status = overBudget ? 'over-budget' : 'failed';
+        error = String(e?.message || e);
+      }
+      const findings = status === 'ok' ? parseFindings(text, { role: role.id, taskId: task.id }) : [];
+      if (findings.length) { board.add(findings); for (const f of findings) say('task.finding', { taskId: task.id, role: role.id, finding: f }); }
+      const row = { id: task.id, role: task.role, title: task.title, status, text, error, usage, ms: now() - t0, findings };
+      tasksOut.push(row);
+      say(status === 'ok' ? 'task.done' : 'task.failed', { taskId: task.id, role: task.role, status, error, ms: row.ms, findings: findings.length });
+      if (budget.exhausted()) overBudget = true;
+    });
+  }
+  // Every planned task gets a row — what never ran is recorded as skipped, not forgotten.
+  for (const task of tasks) if (!tasksOut.some((x) => x.id === task.id)) tasksOut.push({ id: task.id, role: task.role, title: task.title, status: 'skipped', text: '', findings: [] });
+  if (stopped()) return finish('stopped');
+  if (overBudget) return finish('over-budget', { proposal: mergeCheap(t, board.all(), tasksOut) });
+
+  // ── merge ─────────────────────────────────────────────────────────────────────────────
+  say('run.merging', { policy: t.merge });
+  const okTasks = tasksOut.filter((x) => x.status === 'ok');
+  let proposal;
+  if (!okTasks.length) return finish('failed', { proposal: null });
+  if (t.merge === 'judge') {
+    const judge = roleOf(t.judge) || strongestRole(t);
+    const m = modelFor(judge);
+    if (m?.model && budget.canAfford({ tokens: 0 })) {
+      const prompt = [
+        `You are the ${judge.name || judge.id} of team "${t.name}". Review the team's findings for the request below and write the final answer — accurate, concise, and only what the findings support. Flag anything the members disagreed on.`,
+        `Request: ${String(request || '').trim()}`,
+        boardText(board.all()),
+      ].join('\n\n');
+      const res = await callModel({ runId: id, taskId: 'merge', role: judge.id, model: m.model, mode: 'model', system: judge.prompt, prompt, tools: undefined, signal });
+      if (res?.usage) budget.charge(res.usage);
+      proposal = res?.ok ? { kind: 'answer', text: String(res.text || ''), by: judge.id } : mergeCheap(t, board.all(), tasksOut);
+    } else {
+      proposal = mergeCheap(t, board.all(), tasksOut);
+    }
+  } else if (t.merge === 'converge') {
+    const drafts = okTasks.map((x) => ({ claims: toBriefClaims(x.findings) }));
+    const { agreed, disputed } = converge(drafts, { minAgree: Math.min(2, drafts.length) });
+    proposal = { kind: 'claims', agreed, disputed, by: 'converge' };
+  } else if (t.merge === 'first') {
+    proposal = { kind: 'answer', text: okTasks[0].text, by: okTasks[0].role };
+  } else {
+    proposal = mergeCheap(t, board.all(), tasksOut);
+  }
+  const failed = tasksOut.some((x) => x.status !== 'ok');
+  return finish(failed ? 'partial' : 'completed', { proposal });
+}
+
+/** No model: the members' work side by side, findings first — always available. */
+function mergeCheap(team, findings, tasks) {
+  const sections = tasks.filter((x) => x.status === 'ok').map((x) => {
+    const role = team.roles.find((r) => r.id === x.role);
+    const own = (x.findings || []).map((f) => `- ${f.text}${f.refs?.length ? ` (${f.refs.join(', ')})` : ''}`).join('\n');
+    return `### ${role?.name || x.role}\n${own || x.text}`;
+  });
+  return { kind: 'answer', text: sections.join('\n\n'), by: 'concat' };
+}

package/team-tool.js

@@ -0,0 +1,124 @@
+// The `team` tool — a team invoked from any chat: run, dry_run, save.
+//
+// The recipe tool's twin, on purpose: one registered tool whose description is the
+// catalogue, `dry_run` showing what a person would approve, `save` proposing a team from the
+// conversation and storing it only on the card's Allow, `run` executing through the host's
+// own runner. A team run is a tool call inside an ordinary turn, so it streams, can be
+// stopped, and is queued and steered like anything else the model does.
+//
+// Everything the model sees is here; the card, the store and the runner's `callModel` are
+// the host's, injected. Bound late (`bind`) to the toolset it lives in: a team's members
+// receive the host's toolset narrowed to their grants, and the host builds that from the
+// same providers this tool is a member of.
+
+import { validateTeam, normalizeTeam, describeRole, TEAM_NAME_RE } from './team.js';
+import { dryRunTeam } from './team-run.js';
+
+export const TEAM_TOOL_NAME = 'team';
+
+function catalogue(teams) {
+  const list = (teams || []).filter((t) => t && t.enabled !== false && t.name);
+  if (!list.length) return 'No teams saved yet.';
+  return `Saved teams: ${list.map((t) => `${t.name} (${(t.roles || []).map((r) => r.id).join(', ')})${t.description ? ` — ${t.description}` : ''}`).join('; ')}.`;
+}
+
+export function teamToolSpec(teams) {
+  return {
+    name: TEAM_TOOL_NAME,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    description:
+      `Saved agent teams — several roles working a request in parallel, merged into one answer. ${catalogue(teams)} `
+      + 'Actions: {"action":"run","name":"<team>","request":"<what to do>"} runs one (streams; may take a while); '
+      + '{"action":"dry_run","name":"<team>","request":"…"} shows roles, models, tools and budget without running; '
+      + '{"action":"save","team":{…}} proposes a NEW team after a task that would benefit from several roles — the user approves it on a card. '
+      + 'A team: {"name":"research","description":"…","roles":[{"id":"researcher","prompt":"…","prefer":"balanced","grants":["data","web"]},{"id":"writer","prompt":"…","prefer":"strong","grants":["none"]}],"merge":"judge","judge":"writer","budget":{"tokens":40000,"ms":300000}}. '
+      + 'grants: none | data | web | history | mcp | mcp:<server>. merge: judge | converge | concat | first. A budget is required.',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['run', 'dry_run', 'save'] },
+        name: { type: 'string', description: 'Team name, for run / dry_run.' },
+        request: { type: 'string', description: 'What the team should do, for run / dry_run.' },
+        team: { type: 'object', description: 'The team to save, for save.', additionalProperties: true },
+      },
+      required: ['action'],
+    },
+  };
+}
+
+/** The card a person approves a new team on. */
+export function describeTeamForApproval(team, dry) {
+  const lines = [`${team.name}${team.description ? ` — ${team.description}` : ''}`, `Plan: ${team.plan || 'fixed'} · merge: ${team.merge || 'concat'}${team.judge ? ` (judge: ${team.judge})` : ''}`];
+  for (const r of dry?.roles || team.roles || []) lines.push(`• ${describeRole({ ...r, model: r.model || undefined })}${r.appointed === false ? ' — NO MODEL AVAILABLE' : ''}`);
+  const b = team.budget || {};
+  lines.push(`Budget: ${Object.entries(b).map(([k, v]) => `${k} ${v}`).join(' · ')}`);
+  lines.push('Runs go through your own models and tools; a team may not act on a page. Nothing a team produces lands without you.');
+  return lines.join('\n');
+}
+
+const json = (v) => JSON.stringify(v);
+
+/**
+ * @param teams        the saved list (the `teams` prefs section)
+ * @param run          `async ({ team, request, onEvent }) => runResult` — the host's runTeam binding
+ * @param appoint      `(role) => { model, mode } | null` for the dry run
+ * @param confirmSave  `async (detail, team) => 'allow' | 'deny'`; absent = save refused
+ * @param saveTeam     `async (team) => void`
+ */
+export function teamToolProvider({ teams = [], run = null, appoint = null, confirmSave = null, saveTeam = null } = {}) {
+  const byName = new Map((teams || []).filter((t) => t?.name && t.enabled !== false).map((t) => [t.name, t]));
+  let bound = null;
+  return {
+    id: 'team',
+    specs: [teamToolSpec(teams)],
+    system: byName.size ? 'Saved agent teams exist (see the `team` tool). When a request is broad enough that several roles would do it better — research plus writing, several sources to reconcile — run the matching team rather than doing it all in one turn.' : '',
+    bind(toolset) { bound = toolset; },
+    async execute(name, input) {
+      if (name !== TEAM_TOOL_NAME) return json({ error: `Unknown tool: ${name}` });
+      const action = String(input?.action || '');
+
+      if (action === 'save') {
+        const team = input?.team;
+        const v = validateTeam(team);
+        if (!v.ok) return json({ error: 'The team is not valid.', problems: v.errors, hint: 'A team needs a name, roles with prompts and grants, and a budget.' });
+        if (!TEAM_NAME_RE.test(team.name)) return json({ error: 'name must be a short identifier.' });
+        if (byName.has(team.name)) return json({ error: `A team named "${team.name}" already exists. Pick another name.` });
+        if (!confirmSave || !saveTeam) return json({ error: 'Saving a team needs the user\'s approval, which this surface cannot ask for. Describe the team and suggest saving it from the side panel or the desktop.' });
+        const norm = normalizeTeam(team);
+        const dry = dryRunTeam(norm, '', { appoint });
+        const decision = await confirmSave(describeTeamForApproval(norm, dry), norm);
+        if (decision !== 'allow') return json({ error: `The user did not save "${norm.name}". Do not propose it again this turn.`, declined: true });
+        const stored = { ...norm, createdAt: Date.now() };
+        await saveTeam(stored);
+        byName.set(stored.name, stored);
+        return json({ saved: stored.name, roles: stored.roles.map((r) => r.id), hint: `Run it with {"action":"run","name":"${stored.name}","request":"…"} or by typing /${stored.name}.` });
+      }
+
+      const team = byName.get(String(input?.name || ''));
+      if (!team) return json({ error: `No team named "${input?.name}".`, available: [...byName.keys()] });
+      const request = String(input?.request || '').trim();
+
+      if (action === 'dry_run') {
+        const dry = dryRunTeam(team, request, { appoint });
+        return json({ name: team.name, ok: dry.ok, missing: dry.missing, roles: dry.roles, plan: dry.plan, tasks: dry.tasks, merge: dry.merge, budget: dry.budget });
+      }
+      if (action === 'run') {
+        if (!request) return json({ error: 'run needs a request — what should the team do?' });
+        if (typeof run !== 'function') return json({ error: 'This surface cannot run a team.' });
+        const dry = dryRunTeam(team, request, { appoint });
+        if (!dry.ok) return json({ error: `No model is available for role(s): ${dry.missing.join(', ')}.`, roles: dry.roles });
+        const result = await run({ team, request, toolset: bound });
+        const findings = (result.board || []).map((f) => ({ role: f.role, kind: f.kind, text: f.text, refs: f.refs }));
+        return json({
+          name: team.name, runId: result.runId, status: result.status,
+          proposal: result.proposal,
+          tasks: (result.tasks || []).map((x) => ({ id: x.id, role: x.role, status: x.status, ms: x.ms, findings: (x.findings || []).length, error: x.error || undefined })),
+          findings,
+          usage: result.usage,
+          hint: result.status === 'over-budget' ? 'The team stopped at its budget; the proposal is what it had. Say so.' : undefined,
+        });
+      }
+      return json({ error: `Unknown action "${action}". Use run, dry_run or save.` });
+    },
+  };
+}

package/team.js

@@ -0,0 +1,123 @@
+// A team, as data — roles with grants, a merge policy, a budget. Nothing runs here.
+//
+// The Notes co-writer swarm was one team, hard-wired: a planner, four roles appointed per
+// model, a shared board. The desktop was about to copy it, and every client would then hold
+// its own answer to "what is a researcher allowed to touch". So a team is declared once, in
+// this shape, and shared through the client-prefs document like a skill or a recipe: defined
+// in one client, invokable in the other at its next open.
+//
+// Two invariants are enforced here rather than trusted:
+//   • A role's GRANTS name tool groups, never tools — and `page` is not grantable. A tab is
+//     one person's; a team member acting on it is the one thing every guard was written to
+//     stop. `none` is a legitimate grant: a writer needs no tools.
+//   • A team has a BUDGET, or it is not a team (F8 O1). `validateTeam` refuses one without.
+//
+// Trust is derived, never declared (the skill-manifest rule): a stored `builtin` cannot
+// survive an `origin`, and a team a client stores as trusted is stored as nothing of the kind.
+
+import { validateBudget, normalizeBudget } from './budget.js';
+
+export const TEAM_NAME_RE = /^[a-z][a-z0-9_-]{0,63}$/i;
+export const ROLE_ID_RE = /^[a-z][a-z0-9_-]{0,31}$/i;
+export const ROLE_MODES = Object.freeze(['model', 'subagent', 'recipe']);
+export const ROLE_PREFERS = Object.freeze(['cheap', 'balanced', 'strong']);
+export const MERGE_POLICIES = Object.freeze(['judge', 'converge', 'concat', 'first']);
+export const PLAN_MODES = Object.freeze(['fixed', 'planner']);
+/** The tool groups a role may hold. `mcp:<server>` narrows to one server; `mcp` is all of them. */
+export const GRANTABLE = Object.freeze(['none', 'data', 'web', 'mcp', 'history']);
+export const GRANT_RE = /^(none|data|web|history|mcp|mcp:[a-zA-Z0-9_.:-]{1,64})$/;
+export const MAX_ROLES = 8;
+
+export class TeamError extends Error {
+  constructor(code, message) { super(message); this.name = 'TeamError'; this.code = code; }
+}
+
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** A role's grants, normalized: `none` alone means no tools; duplicates and `page` are dropped. */
+export function normalizeGrants(grants) {
+  const list = (Array.isArray(grants) ? grants : typeof grants === 'string' ? [grants] : []).map((g) => String(g || '').trim()).filter(Boolean);
+  const ok = [...new Set(list.filter((g) => GRANT_RE.test(g)))];
+  if (!ok.length || ok.includes('none')) return ['none'];
+  return ok;
+}
+
+export function validateTeam(team) {
+  const errors = [];
+  if (!isRecord(team)) return { ok: false, errors: ['team must be an object'] };
+  if (!TEAM_NAME_RE.test(String(team.name || ''))) errors.push('name: a short identifier (letters, digits, _ -)');
+  if (!Array.isArray(team.roles) || !team.roles.length) errors.push('roles: a non-empty array');
+  else {
+    if (team.roles.length > MAX_ROLES) errors.push(`roles: at most ${MAX_ROLES}`);
+    const seen = new Set();
+    team.roles.forEach((r, i) => {
+      const w = `roles[${i}]`;
+      if (!isRecord(r)) { errors.push(`${w}: must be an object`); return; }
+      if (!ROLE_ID_RE.test(String(r.id || ''))) errors.push(`${w}.id: a short identifier`);
+      else if (seen.has(r.id)) errors.push(`${w}.id: duplicate "${r.id}"`);
+      seen.add(r.id);
+      if (r.mode !== undefined && !ROLE_MODES.includes(r.mode)) errors.push(`${w}.mode: one of ${ROLE_MODES.join(', ')}`);
+      if (r.prefer !== undefined && !ROLE_PREFERS.includes(r.prefer)) errors.push(`${w}.prefer: one of ${ROLE_PREFERS.join(', ')}`);
+      if ((r.mode || 'model') === 'recipe' && !r.recipe) errors.push(`${w}.recipe: a recipe name is required in recipe mode`);
+      if ((r.mode || 'model') !== 'recipe' && !String(r.prompt || '').trim()) errors.push(`${w}.prompt: what this role does`);
+      const bad = (Array.isArray(r.grants) ? r.grants : []).filter((g) => !GRANT_RE.test(String(g)));
+      if (bad.length) errors.push(`${w}.grants: not grantable: ${bad.join(', ')}${bad.some((g) => /^page/.test(String(g))) ? ' (a tab is one person\'s; a team may not act on it)' : ''}`);
+    });
+  }
+  if (team.merge !== undefined && !MERGE_POLICIES.includes(team.merge)) errors.push(`merge: one of ${MERGE_POLICIES.join(', ')}`);
+  if (team.plan !== undefined && !PLAN_MODES.includes(team.plan)) errors.push(`plan: one of ${PLAN_MODES.join(', ')}`);
+  if (team.judge !== undefined && team.judge !== null && !(Array.isArray(team.roles) && team.roles.some((r) => r?.id === team.judge))) errors.push('judge: must name one of the roles');
+  const b = validateBudget(team.budget);
+  if (!b.ok) errors.push(...b.errors.map((e) => `budget: ${e}`));
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * The stored form. Defaults filled, grants normalized, trust derived: `builtin` only when the
+ * host says so, never from the record.
+ */
+export function normalizeTeam(team, { builtin = false } = {}) {
+  const v = validateTeam(team);
+  if (!v.ok) throw new TeamError('INVALID', v.errors.join('; '));
+  return {
+    name: String(team.name),
+    description: String(team.description || '').trim().slice(0, 300),
+    plan: PLAN_MODES.includes(team.plan) ? team.plan : 'fixed',
+    merge: MERGE_POLICIES.includes(team.merge) ? team.merge : (team.judge ? 'judge' : 'concat'),
+    judge: team.judge || null,
+    roles: team.roles.map((r) => ({
+      id: String(r.id),
+      name: String(r.name || r.id).slice(0, 60),
+      mode: ROLE_MODES.includes(r.mode) ? r.mode : 'model',
+      prefer: ROLE_PREFERS.includes(r.prefer) ? r.prefer : 'balanced',
+      ...(r.model ? { model: String(r.model) } : {}),
+      prompt: String(r.prompt || '').trim().slice(0, 4000),
+      grants: normalizeGrants(r.grants),
+      ...(r.recipe ? { recipe: String(r.recipe) } : {}),
+      ...(Array.isArray(r.dependsOn) ? { dependsOn: r.dependsOn.map(String).filter((d) => d !== r.id) } : {}),
+    })),
+    budget: normalizeBudget(team.budget),
+    enabled: team.enabled !== false,
+    ...(team.origin && isRecord(team.origin) ? { origin: { ...team.origin } } : {}),
+    ...(builtin ? { builtin: true } : {}),
+    ...(team.createdAt ? { createdAt: team.createdAt } : {}),
+  };
+}
+
+export function defineTeam(team) { return Object.freeze(normalizeTeam(team)); }
+
+/** Which of a client's tool groups a role may hold — `(groupId, serverId?) => boolean`. */
+export function grantAllows(grants, groupId, serverId = '') {
+  const g = normalizeGrants(grants);
+  if (g.includes('none')) return false;
+  if (groupId === 'page') return false;
+  if (groupId === 'mcp') return g.includes('mcp') || (!!serverId && g.includes(`mcp:${serverId}`));
+  return g.includes(groupId);
+}
+
+/** One line a person reads per role: name · tier/model · grants · mode. */
+export function describeRole(r) {
+  const who = r.model || r.prefer || 'balanced';
+  const grants = (r.grants || ['none']).join(', ');
+  return `${r.name || r.id} — ${who}${r.mode && r.mode !== 'model' ? ` (${r.mode})` : ''} · tools: ${grants}`;
+}