@chatpanel/events 0.76.0 → 0.78.0

package/index.js

@@ -192,11 +192,12 @@ export { recipeToolProvider, recipeToolSpec, describeRecipeForApproval, RECIPE_T
 // 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 { defineTeam, validateTeam, normalizeTeam, normalizeGrants, grantAllows, describeRole, TeamError, ROLE_MODES, MERGE_POLICIES, PLAN_MODES, GRANTABLE, STARTER_TEAMS, starterTeams, blankTeam, teamFromForm } 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 { teamLine, teamLanes } from './team-trail.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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.76.0",
+  "version": "0.78.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",
@@ -93,6 +93,7 @@
     "./team-plan.js": "./team-plan.js",
     "./team-run.js": "./team-run.js",
     "./team-tool.js": "./team-tool.js",
+    "./team-trail.js": "./team-trail.js",
     "./team.js": "./team.js",
     "./text-search.js": "./text-search.js",
     "./theme.js": "./theme.js",
@@ -207,6 +208,7 @@
     "team-plan.js",
     "team-run.js",
     "team-tool.js",
+    "team-trail.js",
     "team.js",
     "text-search.js",
     "theme.js",

package/team-trail.js

@@ -0,0 +1,37 @@
+// A team run as a trail reads it: one line per event in the trail's own vocabulary, and
+// the run's lanes — one per task — folded from the same events. Both clients draw a run
+// from these; neither decides for itself what "task.done" means in words. The event
+// vocabulary is team-run.js's `emit`; the lanes are what a pane, a card or a phone renders.
+
+/** One trail line per team event, in the trail's own vocabulary. */
+export function teamLine(ev) {
+  const role = ev.role ? `${ev.role}` : 'team';
+  switch (ev.type) {
+    case 'run.started': return { type: 'status', text: `team ${ev.team}: ${(ev.roles || []).join(', ')}` };
+    case 'plan.ready': return { type: 'status', text: `plan: ${(ev.tasks || []).length} task${(ev.tasks || []).length === 1 ? '' : 's'} (${ev.by})` };
+    case 'task.started': return { type: 'tool', name: role, text: `${role} · ${ev.title || ev.taskId}` };
+    case 'task.tool': return { type: 'tool', name: ev.name, text: `${role} ran ${ev.name}${ev.text ? ` — ${ev.text}` : ''}` };
+    case 'task.finding': return { type: 'status', text: `${role}: ${String(ev.finding?.text || '').slice(0, 140)}` };
+    case 'task.done': return { type: 'status', text: `${role} done · ${ev.findings || 0} finding${ev.findings === 1 ? '' : 's'}` };
+    case 'task.failed': return { type: 'error', text: `${role} ${ev.status || 'failed'}${ev.error ? ` — ${ev.error}` : ''}` };
+    case 'run.merging': return { type: 'status', text: `merging (${ev.policy})` };
+    case 'run.done': return { type: 'status', text: `team ${ev.status}${ev.usage?.spent?.tokens ? ` · ${ev.usage.spent.tokens} tokens` : ''}` };
+    default: return null;
+  }
+}
+
+/** The run's lanes — one per task — folded from its events, for the pane. */
+export function teamLanes(prev, ev) {
+  const lanes = prev ? { ...prev, tasks: { ...prev.tasks } } : { runId: ev.runId, team: '', status: 'running', tasks: {}, findings: 0 };
+  switch (ev.type) {
+    case 'run.started': lanes.team = ev.team; lanes.roles = ev.roles; break;
+    case 'plan.ready': for (const t of ev.tasks || []) lanes.tasks[t.id] = { id: t.id, role: t.role, title: t.title, status: 'pending', findings: 0 }; break;
+    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.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 'run.done': lanes.status = ev.status; lanes.usage = ev.usage; break;
+    default: break;
+  }
+  return lanes;
+}

package/team.js

@@ -121,3 +121,78 @@ export function describeRole(r) {
   const grants = (r.grants || ['none']).join(', ');
   return `${r.name || r.id} — ${who}${r.mode && r.mode !== 'model' ? ` (${r.mode})` : ''} · tools: ${grants}`;
 }
+
+// ── Starters and the editor's form ───────────────────────────────────────────────────────
+//
+// A team is usually proposed in conversation, but a person's first team should not depend
+// on a model deciding to propose one. Both clients' Settings → Teams offer these as "Add
+// starter" and edit them on the same form as a blank team; `teamFromForm` is the one shaping
+// of that form into a team, so a field's meaning does not differ between clients.
+
+export const STARTER_TEAMS = Object.freeze([
+  {
+    name: 'research',
+    description: 'Research a question from the web and your own notes, then write it up.',
+    plan: 'fixed', merge: 'judge', judge: 'writer',
+    roles: [
+      { id: 'researcher', prompt: 'Research the request thoroughly. Search the web and the user\'s own history. Report each fact as a finding with where it came from; note disagreements between sources.', prefer: 'balanced', grants: ['web', 'data'] },
+      { id: 'writer', prompt: 'Write the answer the user asked for from the board\'s findings, citing them. Say plainly what was not found.', prefer: 'strong', grants: ['none'] },
+    ],
+    budget: { tokens: 40000, ms: 300000 },
+  },
+  {
+    name: 'review',
+    description: 'Two independent reads of a draft, reconciled into one set of comments.',
+    plan: 'fixed', merge: 'converge',
+    roles: [
+      { id: 'editor', prompt: 'Read the draft as an editor: structure, clarity, what is missing. One finding per issue, with the passage it refers to.', prefer: 'strong', grants: ['none'] },
+      { id: 'checker', prompt: 'Read the draft as a fact-checker: every claim that could be wrong, with what you checked against. Use the user\'s history and the web.', prefer: 'balanced', grants: ['data', 'web'] },
+    ],
+    budget: { tokens: 30000, ms: 240000 },
+  },
+]);
+
+/** Fresh copies — a starter is a template, never the stored record. */
+export function starterTeams() {
+  return STARTER_TEAMS.map((t) => ({ ...t, roles: t.roles.map((r) => ({ ...r, grants: [...r.grants] })), budget: { ...t.budget } }));
+}
+
+/** A blank team for the editor: one role, the smallest budget that is still a budget. */
+export function blankTeam() {
+  return { name: '', description: '', plan: 'fixed', merge: 'concat', judge: null, roles: [{ id: 'role1', prompt: '', prefer: 'balanced', grants: ['none'] }], budget: { tokens: 20000, ms: 300000 } };
+}
+
+/**
+ * The editor's form → a team, or the errors. Grants come as text ("web, data, mcp:srv"),
+ * the budget as numbers that may be blank; a blank judge under `merge: judge` is the last
+ * role, which is the writer in every starter.
+ */
+export function teamFromForm(form) {
+  const roles = (Array.isArray(form.roles) ? form.roles : []).map((r) => ({
+    id: String(r.id || '').trim(),
+    name: String(r.name || '').trim() || undefined,
+    prompt: String(r.prompt || ''),
+    prefer: r.prefer || 'balanced',
+    ...(r.model ? { model: String(r.model) } : {}),
+    grants: String(Array.isArray(r.grants) ? r.grants.join(',') : r.grants || 'none').split(/[,\s]+/).map((g) => g.trim()).filter(Boolean),
+  }));
+  const budget = {};
+  for (const k of ['tokens', 'calls', 'ms', 'usd']) {
+    const v = Number(form.budget?.[k]);
+    if (form.budget?.[k] !== '' && form.budget?.[k] != null && Number.isFinite(v) && v > 0) budget[k] = v;
+  }
+  const merge = form.merge || 'concat';
+  const team = {
+    name: String(form.name || '').trim(),
+    description: String(form.description || '').trim(),
+    plan: form.plan || 'fixed',
+    merge,
+    judge: merge === 'judge' ? (form.judge || roles[roles.length - 1]?.id || null) : null,
+    roles,
+    budget,
+    enabled: form.enabled !== false,
+    ...(form.createdAt ? { createdAt: form.createdAt } : {}),
+  };
+  const v = validateTeam(team);
+  return v.ok ? { ok: true, team: normalizeTeam(team) } : { ok: false, errors: v.errors };
+}