@chatpanel/events 0.81.1 → 0.82.0

package/index.js

@@ -196,6 +196,7 @@ export { defineTeam, validateTeam, normalizeTeam, normalizeGrants, grantAllows,
 export { fixedPlan, parsePlan, plannerPrompt, waves, breakCycles, TEAM_PLAN_SCHEMA } from './team-plan.js';
 export { createBoard, parseFindings, boardText, findingsInstruction, toBriefClaims, FINDINGS_SCHEMA, FINDING_KINDS, THREAD_KINDS, THREAD_STATUSES, POST_KINDS, POST_STATUSES, ASK_TYPES, emptyBoardState, foldBoard, findingsOf } from './team-board.js';
 export { boardToolProvider, boardToolSpec, createAnswerBox, withBoardTool, BOARD_TOOL_NAME, DEFAULT_ASK_TIMEOUT_MS } from './board-tool.js';
+export { createRunCache, withRunCache } from './team-cache.js';
 export { runTeam, resumeTeam, dryRunTeam, isModelUnavailable, TeamRunError, RUN_STATUSES } from './team-run.js';
 export { teamToolProvider, teamToolSpec, describeTeamForApproval, TEAM_TOOL_NAME } from './team-tool.js';
 export { teamLine, teamLanes } from './team-trail.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.81.1",
+  "version": "0.82.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",
@@ -91,6 +91,7 @@
     "./tags.js": "./tags.js",
     "./team-board.js": "./team-board.js",
     "./board-tool.js": "./board-tool.js",
+    "./team-cache.js": "./team-cache.js",
     "./team-plan.js": "./team-plan.js",
     "./team-run.js": "./team-run.js",
     "./team-tool.js": "./team-tool.js",
@@ -207,6 +208,7 @@
     "tags.js",
     "team-board.js",
     "board-tool.js",
+    "team-cache.js",
     "team-plan.js",
     "team-run.js",
     "team-tool.js",

package/team-cache.js

@@ -0,0 +1,63 @@
+// One lookup per run — a run-scoped cache over read-only tools.
+//
+// Three members of a travel team searched "Snoqualmie Valley School District calendar" five
+// times between them. Each member's own turn already dedupes its own repeats; the RUN did
+// not, and members in one wave cannot read each other's findings yet. So: a read-only call
+// with the same name and arguments, from any member, runs once per run; the rest get the
+// first answer back, marked as shared. Only tools that declare themselves read-only (MCP
+// annotations, the shared retrieval tools) are cached; a dispatcher's paging (`get_result`)
+// and the board are per-member and never are.
+
+const NEVER = new Set(['get_result', 'board', 'team', 'recipe']);
+const READ_ONLY_NAME_RE = /^(find|web_search|history_search|history_get_source|history_list|meeting_live_transcript|read|fetch|get_|list_|search)/i;
+
+function stableKey(name, input) {
+  const walk = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? Object.keys(v).sort().reduce((o, k) => { o[k] = walk(v[k]); return o; }, {}) : Array.isArray(v) ? v.map(walk) : v);
+  try { return `${name} ${JSON.stringify(walk(input ?? {}))}`; } catch { return `${name} ?`; }
+}
+
+export function createRunCache() {
+  const hits = new Map(); // key -> { result, by, at }
+  let shared = 0;
+  return {
+    get: (k) => hits.get(k) || null,
+    set: (k, v) => { hits.set(k, v); },
+    delete: (k) => { hits.delete(k); },
+    countShared: () => { shared += 1; },
+    get size() { return hits.size; },
+    get shared() { return shared; },
+  };
+}
+
+function isReadOnly(toolset, name) {
+  if (NEVER.has(name)) return false;
+  const spec = (toolset.specs || []).find((s) => s.name === name);
+  if (spec?.annotations?.readOnlyHint === true) return true;
+  if (spec?.annotations && spec.annotations.readOnlyHint === false) return false;
+  const t = toolset.traits instanceof Map ? toolset.traits.get(name) : null;
+  if (t && typeof t.readOnly === 'boolean') return t.readOnly;
+  return READ_ONLY_NAME_RE.test(name);
+}
+
+/** The toolset with its read-only calls served from the run's cache. */
+export function withRunCache(toolset, cache, { role = '' } = {}) {
+  if (!toolset || !cache) return toolset;
+  return {
+    ...toolset,
+    execute: async (name, input, ...rest) => {
+      if (!isReadOnly(toolset, name)) return toolset.execute(name, input, ...rest);
+      const key = stableKey(name, input);
+      const hit = cache.get(key);
+      if (hit) {
+        // Members in one wave ask at the same moment: the second waits on the first's call.
+        cache.countShared();
+        const result = await hit.promise;
+        const note = `[shared: ${hit.by || 'another member'} already ran this in this run]\n`;
+        return typeof result === 'string' ? note + result : result;
+      }
+      const promise = Promise.resolve().then(() => toolset.execute(name, input, ...rest));
+      cache.set(key, { promise, by: role, at: Date.now() });
+      try { return await promise; } catch (e) { cache.delete(key); throw e; }
+    },
+  };
+}

package/team-plan.js

@@ -52,7 +52,11 @@ export function plannerPrompt(team, request) {
 /** 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) => ({
+  // The judge's work IS the merge: it reads the whole board and writes the answer. Giving it
+  // a task as well made a planner plan twice — once blind, in the first wave, and once at
+  // the end — and the first, done with no findings to read, was pure duplicate research.
+  const judge = team.merge === 'judge' ? team.judge : null;
+  return (team.roles || []).filter((r) => r.id !== judge || (team.roles || []).length === 1).map((r) => ({
     id: `t_${r.id}`,
     role: r.id,
     title: r.name || r.id,

package/team-run.js

@@ -21,6 +21,7 @@ import { createBudget } from './budget.js';
 import { fixedPlan, plannerPrompt, parsePlan, waves } from './team-plan.js';
 import { createBoard, parseFindings, boardText, findingsInstruction, toBriefClaims, RUNNER } from './team-board.js';
 import { boardToolProvider, createAnswerBox, withBoardTool, DEFAULT_ASK_TIMEOUT_MS } from './board-tool.js';
+import { createRunCache, withRunCache } from './team-cache.js';
 import { converge } from './promotion.js';
 
 export const RUN_STATUSES = Object.freeze(['planning', 'running', 'merging', 'waiting', 'completed', 'partial', 'over-budget', 'stopped', 'failed']);
@@ -106,6 +107,7 @@ export async function runTeam({
   const board = createBoard({ now, state: resume?.board || null, onEvent: (type, ev) => say(type, ev) });
   // No answer box from the host means nobody can answer: asks are off, a member that asks is
   // told to proceed on its own assumption at once, and the budget stop is final.
+  const runCache = createRunCache(); // one lookup per run, across members
   const box = answers || createAnswerBox();
   const askMs = answers ? askTimeoutMs : 0;
   const startedAt = resume?.startedAt || now();
@@ -144,7 +146,7 @@ export async function runTeam({
 
   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(), threads: board.state(), usage, startedAt, endedAt: now(), ...extra };
+    const out = { runId: id, team: t.name, status, plan: { by: planBy, tasks }, tasks: tasksOut, board: board.all(), threads: board.state(), usage, lookups: { distinct: runCache.size, shared: runCache.shared }, startedAt, endedAt: now(), ...extra };
     // What a resume needs, on the record: the plan, what finished, the board, the spend.
     if (status === 'waiting') out.checkpoint = { runId: id, startedAt, plan: { by: planBy, tasks }, tasks: tasksOut, board: board.state(), budget: { cap: budget.cap, spent: usage.spent } };
     say('run.done', { status, usage, proposal: out.proposal || null, failedTaskIds: tasksOut.filter((x) => x.status === 'failed').map((x) => x.id), waitingTaskIds: tasksOut.filter((x) => x.status === 'waiting').map((x) => x.id), ...(out.checkpoint ? { checkpoint: out.checkpoint } : {}) });
@@ -206,7 +208,7 @@ export async function runTeam({
               return a;
             } : null,
           });
-          const tools = withBoardTool(await toolsFor(role), boardTool);
+          const tools = withBoardTool(withRunCache(await toolsFor(role), runCache, { role: role.id }), boardTool);
           // A model that is not there — not deployed, no key, gone — is not the task failing:
           // the next model on the roster is appointed and the task tried again, up to three
           // models. Anything else (a refusal, a timeout, a bad request) fails the task.
@@ -215,6 +217,8 @@ export async function runTeam({
             const m = modelFor(role, exclude);
             if (!m?.model) throw new Error(exclude.size ? `no model left for role "${role.id}" after ${[...exclude].join(', ')}` : `no model for role "${role.id}"`);
             if (attempt > 1) say('task.reappointed', { taskId: task.id, role: role.id, model: m.model, after: [...exclude] });
+            // Who is doing this task, for a ledger that shows the lanes — said per attempt.
+            say('task.model', { taskId: task.id, role: role.id, model: m.model, attempt });
             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, signal: taskAc.signal,
@@ -245,6 +249,8 @@ export async function runTeam({
       const row = { id: task.id, role: task.role, title: task.title, status, text, error, usage, ms: now() - t0, findings, ...(askedAndWaiting ? { waitingOn: askedAndWaiting } : {}) };
       tasksOut.push(row);
       say(status === 'ok' ? 'task.done' : 'task.failed', { taskId: task.id, role: task.role, status, error, ms: row.ms, findings: findings.length, ...(askedAndWaiting ? { threadId: askedAndWaiting } : {}) });
+      // The spend so far, after every task — a ledger reads it live instead of at the end.
+      say('run.usage', { usage: budget.snapshot() });
       if (budget.exhausted()) overBudget = true;
     });
     // Over budget with work left: ask the person ONCE for more, on the board, before stopping.
@@ -274,13 +280,32 @@ export async function runTeam({
     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.`,
+        `You are the ${judge.name || judge.id} of team "${t.name}". The members' work is on the board below (and in the board tool). Write the team's FINAL ANSWER to the request: complete, well organised, only what the findings support, with the refs they came from. Say plainly what was not found or assumed. Flag anything the members disagreed on. Do not research from scratch — verify a figure with a tool only where the board is silent or contradictory.`,
         `Request: ${String(request || '').trim()}`,
         boardText(board),
       ].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);
+      // The judge works with its own grants (it may verify a figure) and the board — and it
+      // is a run member like the others: a model that is not there rotates.
+      say('task.started', { taskId: 'merge', role: judge.id, title: `merge (${judge.name || judge.id})` });
+      const judgeTools = withBoardTool(withRunCache(await toolsFor(judge), runCache, { role: judge.id }), boardToolProvider({ board, role: judge.id, taskId: 'merge', taskIds: null }));
+      let res = null;
+      const excl = new Set();
+      for (let attempt = 1; attempt <= MAX_APPOINTMENTS; attempt++) {
+        const mm = attempt === 1 ? m : modelFor(judge, excl);
+        if (!mm?.model) break;
+        if (attempt > 1) say('task.reappointed', { taskId: 'merge', role: judge.id, model: mm.model, after: [...excl] });
+        say('task.model', { taskId: 'merge', role: judge.id, model: mm.model, attempt });
+        res = await callModel({ runId: id, taskId: 'merge', role: judge.id, model: mm.model, mode: 'model', system: judge.prompt, prompt, tools: judgeTools, signal, onDelta: (delta, full) => say('task.delta', { taskId: 'merge', role: judge.id, delta, text: full }) });
+        if (res?.usage) budget.charge(res.usage);
+        if (res?.ok && String(res.text || '').trim()) break;
+        const err = res?.ok ? 'the model returned no answer' : (res?.error || 'the model did not answer');
+        if (stopped() || !isModelUnavailable(err)) break;
+        excl.add(mm.model);
+      }
+      const judged = res?.ok && String(res.text || '').trim();
+      say(judged ? 'task.done' : 'task.failed', { taskId: 'merge', role: judge.id, status: judged ? 'ok' : 'failed', error: judged ? null : (res?.error || 'the judge did not answer'), findings: 0 });
+      say('run.usage', { usage: budget.snapshot() });
+      proposal = judged ? { kind: 'answer', text: String(res.text || ''), by: judge.id } : mergeCheap(t, board.all(), tasksOut);
     } else {
       proposal = mergeCheap(t, board.all(), tasksOut);
     }

package/team-tool.js

@@ -36,7 +36,8 @@ export function teamToolSpec(teams) {
       + '{"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" (a short identifier: letters, digits, - _; used as /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.',
+      + 'grants: none | data | web | history | mcp | mcp:<server>. merge: judge | converge | concat | first. A budget is required. '
+      + 'Order the work with "dependsOn": a role that builds on another\'s findings (a budget checker on a researcher) lists it, so it runs after and reads the board instead of searching again. The judge does not need a task of its own - the merge is its work.',
     parameters: {
       type: 'object',
       properties: {

package/team-trail.js

@@ -35,6 +35,9 @@ export function teamLanes(prev, ev) {
     case 'task.started': lanes.tasks[ev.taskId] = { ...(lanes.tasks[ev.taskId] || { id: ev.taskId, role: ev.role, title: ev.title }), status: 'running' }; break;
     case 'task.delta': if (lanes.tasks[ev.taskId]) lanes.tasks[ev.taskId] = { ...lanes.tasks[ev.taskId], text: ev.text }; break;
     case 'task.finding': lanes.findings += 1; if (lanes.tasks[ev.taskId]) lanes.tasks[ev.taskId] = { ...lanes.tasks[ev.taskId], findings: (lanes.tasks[ev.taskId].findings || 0) + 1 }; break;
+    case 'task.model': if (lanes.tasks[ev.taskId]) lanes.tasks[ev.taskId] = { ...lanes.tasks[ev.taskId], model: ev.model }; break;
+    case 'task.tool': if (lanes.tasks[ev.taskId]) lanes.tasks[ev.taskId] = { ...lanes.tasks[ev.taskId], tools: (lanes.tasks[ev.taskId].tools || 0) + 1, lastTool: ev.text ? `${ev.name} ${ev.text}` : ev.name }; break;
+    case 'run.usage': lanes.usage = ev.usage; break;
     case 'task.waiting': if (lanes.tasks[ev.taskId]) lanes.tasks[ev.taskId] = { ...lanes.tasks[ev.taskId], status: 'waiting', waitingOn: ev.threadId }; lanes.waiting = [...(lanes.waiting || []), ev.threadId]; break;
     case 'task.done': case 'task.failed': if (lanes.tasks[ev.taskId]) lanes.tasks[ev.taskId] = { ...lanes.tasks[ev.taskId], status: ev.status || 'ok', ms: ev.ms }; break;
     case 'board.thread-status': if (ev.status !== 'waiting' && lanes.waiting) lanes.waiting = lanes.waiting.filter((x) => x !== ev.threadId); break;