@chatpanel/events 0.83.1 → 0.84.1

package/index.js

@@ -197,6 +197,8 @@ export { fixedPlan, parsePlan, plannerPrompt, waves, breakCycles, TEAM_PLAN_SCHE
 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 { emptyRun, foldRun, runFromEvents, checkpointFrom, isResumable, LIVE_RUN_STATUSES, RESUMABLE_RUN_STATUSES } from './team-record.js';
+export { messagesFor, mergeTranscript, clipTranscript, clipMessage, newSteps, continuationNote, createControl, STEP_MAX_CHARS, TASK_TRANSCRIPT_MAX_CHARS } from './team-task.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.83.1",
+  "version": "0.84.1",
   "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",
@@ -92,6 +92,8 @@
     "./team-board.js": "./team-board.js",
     "./board-tool.js": "./board-tool.js",
     "./team-cache.js": "./team-cache.js",
+    "./team-task.js": "./team-task.js",
+    "./team-record.js": "./team-record.js",
     "./team-plan.js": "./team-plan.js",
     "./team-run.js": "./team-run.js",
     "./team-tool.js": "./team-tool.js",
@@ -209,6 +211,8 @@
     "team-board.js",
     "board-tool.js",
     "team-cache.js",
+    "team-task.js",
+    "team-record.js",
     "team-plan.js",
     "team-run.js",
     "team-tool.js",

package/team-record.js

@@ -0,0 +1,102 @@
+// The run record — a team run folded from its events, the same way on the gateway's store
+// and in either client. One fold, so what the desktop shows, what the extension shows and
+// what the store holds never disagree; and enough on the record to RESUME the run from
+// anywhere: the plan, every task's status and transcript, the board, the spend.
+//
+// The gateway vendors this file (its store used to carry a mirror of it, which is the copy
+// that drifts). `checkpointFrom(run)` is what a client hands `resumeTeam` after reading a
+// run the process that started it no longer runs.
+
+import { foldBoard, emptyBoardState } from './team-board.js';
+
+export const LIVE_RUN_STATUSES = Object.freeze(['planning', 'running', 'merging', 'waiting']);
+export const RESUMABLE_RUN_STATUSES = Object.freeze(['waiting', 'stopped', 'failed', 'partial', 'over-budget', 'answered']);
+const TASK_TEXT_MAX = 20_000;
+
+export function emptyRun({ id, client = '', now = Date.now() } = {}) {
+  return { id, client: String(client || '').slice(0, 40), createdAt: now, lastEventAt: now, status: 'planning', team: '', request: '', roles: [], plan: null, tasks: [], board: [], threads: emptyBoardState(), checkpoint: null, proposal: null, usage: null, stopRequested: null, startedAt: null, endedAt: null };
+}
+
+const taskOf = (run, id) => run.tasks.find((x) => x.id === id);
+
+/** Fold one event (`{ type, at, payload }`, or a flat `{ type, at, ...payload }`) into the record. */
+export function foldRun(run, ev) {
+  const type = String(ev?.type || '');
+  const p = ev?.payload && typeof ev.payload === 'object' ? ev.payload : (ev || {});
+  const at = Number(ev?.at) || Date.now();
+  run.lastEventAt = at;
+  switch (type) {
+    case 'run.started':
+    case 'run.resumed':
+      run.team = p.team || run.team; run.request = p.request ?? run.request; run.budget = p.budget || run.budget;
+      run.roles = Array.isArray(p.roles) ? p.roles : run.roles; run.status = 'planning'; run.startedAt = run.startedAt || at;
+      if (type === 'run.resumed') { run.endedAt = null; run.checkpoint = null; run.resumedAt = at; }
+      break;
+    case 'plan.ready':
+      run.plan = { by: p.by || 'fixed', tasks: Array.isArray(p.tasks) ? p.tasks : [] };
+      // A resume replays the plan: keep what the tasks already hold (transcripts, attempts).
+      run.tasks = run.plan.tasks.map((t) => ({ ...(taskOf(run, t.id) || {}), id: t.id, role: t.role, title: t.title, status: taskOf(run, t.id)?.status === 'ok' ? 'ok' : 'pending', findings: taskOf(run, t.id)?.findings || 0 }));
+      run.status = 'running';
+      break;
+    case 'task.started': { const t = taskOf(run, p.taskId); if (t) { t.status = 'running'; t.startedAt = at; t.error = null; } run.status = 'running'; break; }
+    case 'task.model': { const t = taskOf(run, p.taskId); if (t) { t.model = p.model; t.attempts = [...(t.attempts || []), { model: p.model, at, attempt: p.attempt }]; } break; }
+    case 'task.step': { const t = taskOf(run, p.taskId); if (t && Array.isArray(p.steps)) t.transcript = [...(t.transcript || []), ...p.steps]; break; }
+    case 'task.handoff': { const t = taskOf(run, p.taskId); if (t) { t.model = p.to; t.handoffs = [...(t.handoffs || []), { from: p.from, to: p.to, by: p.by, reason: p.reason, at }]; } break; }
+    case 'task.tool': { const t = taskOf(run, p.taskId); if (t) t.tools = (t.tools || 0) + 1; break; }
+    case 'task.delta': { const t = taskOf(run, p.taskId); if (t) t.text = String(p.text || '').slice(0, TASK_TEXT_MAX); break; }
+    case 'task.finding':
+      if (p.finding && p.finding.text) { run.board.push({ ...p.finding, at }); const t = taskOf(run, p.taskId); if (t) t.findings += 1; }
+      break;
+    case 'task.waiting': { const t = taskOf(run, p.taskId); if (t) { t.status = 'waiting'; t.waitingOn = p.threadId; } break; }
+    case 'task.done':
+    case 'task.failed': { const t = taskOf(run, p.taskId); if (t) { t.status = p.status || (type === 'task.done' ? 'ok' : 'failed'); t.error = p.error || null; t.ms = p.ms; t.endedAt = at; } break; }
+    case 'run.merging': run.status = 'merging'; break;
+    case 'run.waiting': run.status = 'running'; break;
+    case 'run.usage': run.usage = p.usage || run.usage; break;
+    case 'run.done':
+      run.status = p.status || 'completed'; run.usage = p.usage || run.usage; run.proposal = p.proposal ?? run.proposal; run.endedAt = at;
+      if (p.checkpoint) run.checkpoint = p.checkpoint;
+      break;
+    case 'run.stop-requested': run.stopRequested = at; break;
+    case 'board.thread': case 'board.post': case 'board.decision': case 'board.thread-status':
+      run.threads = foldBoard(run.threads || emptyBoardState(), ev);
+      if (type === 'board.thread-status' && p.status !== 'waiting' && run.status === 'waiting' && !(run.threads.threads || []).some((t) => t.kind === 'ask' && t.status === 'waiting')) run.status = 'answered';
+      break;
+    default: break;
+  }
+  return run;
+}
+
+/** Fold a whole event list into a fresh record. */
+export function runFromEvents(id, events, opts = {}) {
+  const run = emptyRun({ id, ...opts });
+  for (const ev of events || []) foldRun(run, ev);
+  return run;
+}
+
+/**
+ * What `resumeTeam` needs, from the record alone — the runner's own checkpoint when the run
+ * ended with one, else one built from the folded tasks: whatever the process that ran it
+ * managed to write before it went. A task recorded `running` (its process died) resumes
+ * from its transcript like a waiting one.
+ */
+export function checkpointFrom(run) {
+  if (!run?.plan?.tasks?.length) return null;
+  if (run.checkpoint?.plan?.tasks?.length) return { ...run.checkpoint, board: run.threads && run.threads.threads?.length >= (run.checkpoint.board?.threads?.length || 0) ? run.threads : run.checkpoint.board };
+  return {
+    runId: run.id,
+    startedAt: run.startedAt || run.createdAt,
+    plan: run.plan,
+    tasks: run.tasks.map((t) => ({ id: t.id, role: t.role, title: t.title, status: t.status === 'running' || t.status === 'pending' ? 'stopped' : t.status, text: t.text || '', error: t.error || null, transcript: t.transcript || [], attempts: t.attempts || [], usage: null })),
+    board: run.threads || emptyBoardState(),
+    budget: { cap: run.usage?.cap || run.budget || {}, spent: run.usage?.spent || {} },
+    budgetAsked: false,
+  };
+}
+
+/** Can this record be picked up again? Not one that completed, not one still being run by a live client. */
+export function isResumable(run) {
+  if (!run?.plan?.tasks?.length) return false;
+  if (RESUMABLE_RUN_STATUSES.includes(run.status)) return true;
+  return !!run.stale && LIVE_RUN_STATUSES.includes(run.status); // its client went away mid-run
+}

package/team-run.js

@@ -22,6 +22,7 @@ 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 { messagesFor, mergeTranscript, clipTranscript, clipMessage as clipTranscriptOne, newSteps, continuationNote } from './team-task.js';
 import { converge } from './promotion.js';
 
 export const RUN_STATUSES = Object.freeze(['planning', 'running', 'merging', 'waiting', 'completed', 'partial', 'over-budget', 'stopped', 'failed']);
@@ -96,6 +97,9 @@ export async function runTeam({
   answers = null, askTimeoutMs = DEFAULT_ASK_TIMEOUT_MS,
   // A checkpoint from a run that ended `waiting` — see resumeTeam.
   resume = null,
+  // The host's control channel (team-task.js createControl): a person hands a task to another
+  // model from the board, on either client; the runner continues the task's transcript there.
+  control = null,
 } = {}) {
   if (typeof callModel !== 'function') throw new TeamRunError('BAD_RUN', 'callModel required');
   const t = normalizeTeam(team); // throws on a team without a budget — O1
@@ -111,9 +115,12 @@ export async function runTeam({
   const box = answers || createAnswerBox();
   const askMs = answers ? askTimeoutMs : 0;
   const startedAt = resume?.startedAt || now();
-  // Tasks a checkpoint already finished are carried over, not re-run.
+  // Tasks a checkpoint already finished are carried over, not re-run. Tasks it left
+  // interrupted — waiting, stopped, failed, or running when the process died — are resumed
+  // from their transcripts, not started again.
   const tasksOut = (resume?.tasks || []).filter((x) => x.status === 'ok').map((x) => ({ ...x }));
   const carried = new Set(tasksOut.map((x) => x.id));
+  const interrupted = new Map((resume?.tasks || []).filter((x) => x.status !== 'ok' && Array.isArray(x.transcript) && x.transcript.length).map((x) => [x.id, x]));
   const roleOf = (rid) => t.roles.find((r) => r.id === rid);
   // `exclude` holds what failed as unavailable this run; a re-appointment skips it. A role's
   // pinned model is tried first and, when it is the one that failed, the roster steps in.
@@ -153,7 +160,9 @@ export async function runTeam({
     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, 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 } };
+    // A run that did not complete can be resumed from its record — the plan, every task's
+    // transcript and status, the board, the spend — by any client, any time later.
+    if (status !== 'completed') out.checkpoint = { runId: id, startedAt, plan: { by: planBy, tasks }, tasks: tasksOut.map((x) => ({ ...x, findings: undefined })), board: board.state(), budget: { cap: budget.cap, spent: usage.spent }, budgetAsked: !!extra.budgetAsked };
     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 } : {}) });
     return out;
   };
@@ -179,16 +188,33 @@ export async function runTeam({
       if (stopped() || overBudget || waitingOnPerson) { 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 });
+      const was = interrupted.get(task.id) || null;
+      say('task.started', { taskId: task.id, role: task.role, title: task.title, ...(was ? { resumed: true, steps: was.transcript.length } : {}) });
       let text = '';
       let usage = null;
       let status = 'ok';
       let error = null;
+      // THE TASK'S TRANSCRIPT — its conversation so far, apart from any one model. An attempt
+      // continues it; a hand-off continues it on another model; a resume continues it from
+      // the record. Only a task that has never been attempted starts from the bare prompt.
+      let transcript = was ? [...was.transcript] : [];
+      const attempts = was?.attempts ? [...was.attempts] : [];
       // The task's own abort: an ask nobody answered in time stops THIS member's turn (the
-      // run then checkpoints), without stopping the run's other members.
-      const taskAc = new AbortController();
-      signal?.addEventListener?.('abort', () => taskAc.abort(), { once: true });
+      // run then checkpoints), without stopping the run's other members. A person's hand-off
+      // aborts it too, and names where the task continues.
+      let taskAc = new AbortController();
+      const onRunAbort = () => taskAc.abort();
+      signal?.addEventListener?.('abort', onRunAbort, { once: true });
       let askedAndWaiting = null;
+      let handoffTo = control?._pendingFor?.(task.id) || null;
+      const unsubscribe = control?._subscribe?.((req) => {
+        if (req.type !== 'handoff' || req.taskId !== task.id) return false;
+        handoffTo = req; taskAc.abort(); return true;
+      }) || null;
+      const recordSteps = (before, after) => {
+        const added = newSteps(before, after);
+        if (added.length) say('task.step', { taskId: task.id, role: role.id, steps: added.map((m) => clipTranscriptOne(m)) });
+      };
       try {
         if (role.mode === 'recipe') {
           if (typeof runRecipe !== 'function') throw new Error('this host cannot run recipes');
@@ -219,20 +245,53 @@ export async function runTeam({
           // models. Anything else (a refusal, a timeout, a bad request) fails the task.
           const exclude = new Set();
           let lastErr = '';
+          // What the next attempt is told, when it continues rather than starts.
+          let note = was ? continuationNote(was.status === 'waiting' ? { kind: 'answer', answer: 'see the board' } : { kind: 'resume', reason: was.error || was.status }) : null;
+          let lastModel = was?.attempts?.at?.(-1)?.model || null;
           for (let attempt = 1; ; attempt++) {
-            const m = modelFor(role, excluding(exclude));
+            let m;
+            if (handoffTo) {
+              // A person's hand-off names the model; the task continues there whatever the
+              // roster would have chosen. Said on the board, so everyone knows who has it.
+              m = { model: handoffTo.model, mode: role.mode };
+              const th = board.threadForTask(task.id);
+              if (th) board.post({ threadId: th.id, by: RUNNER, kind: 'decision', text: `Handed off from ${lastModel || 'the roster'} to ${handoffTo.model} by ${handoffTo.by}${handoffTo.reason ? ` — ${handoffTo.reason}` : ''}.` });
+              say('task.handoff', { taskId: task.id, role: role.id, from: lastModel, to: handoffTo.model, by: handoffTo.by, reason: handoffTo.reason || '' });
+              note = continuationNote({ kind: 'handoff', from: lastModel, to: handoffTo.model, reason: `handed off by ${handoffTo.by}` });
+              handoffTo = null;
+              taskAc = new AbortController(); signal?.addEventListener?.('abort', onRunAbort, { once: true });
+            } else {
+              m = modelFor(role, excluding(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], error: lastErr });
+            if (attempt > 1 && lastErr) say('task.reappointed', { taskId: task.id, role: role.id, model: m.model, after: [...exclude], error: lastErr });
             // 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 });
+            attempts.push({ model: m.model, at: now(), continued: !!note });
+            const sent = messagesFor({ transcript }, { prompt, note });
+            // The record grows AS THE ATTEMPT GOES: a host that reports each wire message the
+            // moment it exists (a tool call, its result) puts it on the record then, so a
+            // process that dies mid-attempt leaves the work so far behind it, not nothing.
+            let live = sent;
+            if (sent.length > transcript.length) recordSteps(transcript, sent);
+            const onStep = (message) => { if (message && message.role) { live = [...live, message]; say('task.step', { taskId: task.id, role: role.id, steps: [clipTranscriptOne(message)] }); } };
             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,
+              system: role.prompt, prompt, messages: sent, tools, signal: taskAc.signal,
               onDelta: (delta, full) => say('task.delta', { taskId: task.id, role: role.id, delta, text: full }),
+              onStep,
             });
             usage = res?.usage || null;
             if (usage) budget.charge(usage);
+            // Whatever the attempt did is the task's now — on the record, before any verdict.
+            // What the host already reported step by step is not reported again.
+            transcript = mergeTranscript(sent, res);
+            if (transcript.length < live.length) transcript = live;
+            recordSteps(live, transcript);
+            lastModel = m.model;
+            attempts[attempts.length - 1].status = res?.ok ? (String(res?.text || '').trim() ? 'ok' : 'empty') : 'error';
             if (askedAndWaiting) { status = 'waiting'; waitingOnPerson = true; break; }
+            if (handoffTo) { note = null; continue; } // the person moved it: continue the transcript there
             if (res?.aborted || taskAc.signal.aborted) { status = 'stopped'; break; }
             // A turn that ended with nothing to say — an agent that exited, a stream that
             // died after its tool calls — is not a done task: three members "completed" empty
@@ -249,19 +308,26 @@ export async function runTeam({
               if (mine.length) { text = mine.map((p) => p.text).join('\n\n'); say('task.note', { taskId: task.id, role: role.id, text: 'answered from its board posts' }); break; }
             }
             const err = res?.ok ? 'the model returned no answer' : (res?.error || 'the model did not answer');
+            attempts[attempts.length - 1].error = err;
             if (attempt >= MAX_APPOINTMENTS || stopped() || !isModelUnavailable(err)) throw new Error(err);
             exclude.add(m.model); runExclude.add(m.model); lastErr = err;
+            // The next model CONTINUES this transcript; it does not start over.
+            note = continuationNote({ kind: 'handoff', from: m.model, reason: err });
+            const th = board.threadForTask(task.id);
+            if (th) board.post({ threadId: th.id, by: RUNNER, kind: 'note', text: `${m.model} stopped (${err.slice(0, 160)}); the task continues on the next model with its work so far.` });
           }
         }
       } catch (e) {
         if (askedAndWaiting) { status = 'waiting'; waitingOnPerson = true; }
         else { status = overBudget ? 'over-budget' : 'failed'; error = String(e?.message || e); }
+      } finally {
+        unsubscribe?.();
       }
       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 thread = board.threadForTask(task.id);
       if (thread && status !== 'waiting') board.setThreadStatus(thread.id, 'resolved');
-      const row = { id: task.id, role: task.role, title: task.title, status, text, error, usage, ms: now() - t0, findings, ...(askedAndWaiting ? { waitingOn: askedAndWaiting } : {}) };
+      const row = { id: task.id, role: task.role, title: task.title, status, text, error, usage, ms: now() - t0, findings, transcript: clipTranscript(transcript), attempts, ...(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.
@@ -344,11 +410,14 @@ export async function runTeam({
   return finish(failed ? 'partial' : 'completed', { proposal });
 }
 
-/** Continue a run that ended `waiting` from its checkpoint — the answered ask is on the board. */
+/**
+ * Continue a run from its checkpoint — one that waited on a person, was stopped, failed, or
+ * whose process died. Finished tasks are carried; interrupted ones continue from their
+ * transcripts on whatever model the roster gives them now (or a hand-off names); the board
+ * and the spend carry over. Any client, any time later: the checkpoint is on the record.
+ */
 export function resumeTeam({ checkpoint, ...deps } = {}) {
   if (!checkpoint?.plan?.tasks) throw new TeamRunError('BAD_RESUME', 'a checkpoint with a plan is required');
-  // The waiting task runs again; its ask thread now holds the answer, and boardText gives it
-  // to the member. Tasks recorded `waiting`/`skipped` are dropped from the carried list.
   return runTeam({ ...deps, resume: checkpoint });
 }
 

package/team-task.js

@@ -0,0 +1,111 @@
+// A task is a conversation, and a model call is one attempt at continuing it.
+//
+// A member's task keeps its TRANSCRIPT — the wire messages so far: the request, what the
+// model said, the tools it called and what came back — apart from whichever model or CLI
+// agent happens to be answering. When that model fails, is handed off, or the process
+// itself dies and the run is resumed a month later from the store, the next model does not
+// start over: it is given the transcript and told to continue. The same thing a chat window
+// does when a person switches models mid-conversation; here it is what makes a run survive
+// a process, a model, or an API going away.
+//
+// Every attempt, hand-off and continuation is said on the board (a runner post in the
+// task's thread) and in the run's events, so the record — on the gateway, read by either
+// client — is enough to pick the task up from anywhere.
+
+export const STEP_MAX_CHARS = 4000; // one persisted message's content
+export const TASK_TRANSCRIPT_MAX_CHARS = 60_000; // a task's whole persisted transcript
+
+const clipStr = (s, n) => (typeof s === 'string' && s.length > n ? `${s.slice(0, n)}\n…[${s.length - n} more chars omitted from the record]` : s);
+
+/** A wire message trimmed for the record: tool results and long answers are clipped. */
+export function clipMessage(m) {
+  if (!m || typeof m !== 'object') return m;
+  const out = { role: m.role };
+  if (typeof m.content === 'string') out.content = clipStr(m.content, STEP_MAX_CHARS);
+  else if (m.content != null) out.content = m.content;
+  if (m.tool_calls) out.tool_calls = m.tool_calls.map((c) => ({ id: c.id, type: c.type || 'function', function: { name: c.function?.name, arguments: clipStr(String(c.function?.arguments ?? ''), STEP_MAX_CHARS) } }));
+  if (m.tool_call_id) out.tool_call_id = m.tool_call_id;
+  if (m.name) out.name = m.name;
+  return out;
+}
+
+/** The record's copy of a transcript: clipped per message and bounded as a whole (oldest tool traffic goes first). */
+export function clipTranscript(messages) {
+  const list = (Array.isArray(messages) ? messages : []).filter((m) => m && m.role && m.role !== 'system').map(clipMessage);
+  let size = list.reduce((n, m) => n + JSON.stringify(m).length, 0);
+  // Drop the oldest tool exchanges (assistant tool_calls + tool results) until it fits,
+  // never the first user message (the task) and never the last message.
+  for (let i = 1; size > TASK_TRANSCRIPT_MAX_CHARS && i < list.length - 1; ) {
+    const m = list[i];
+    if (m.role === 'tool' || (m.role === 'assistant' && m.tool_calls)) { size -= JSON.stringify(m).length; list.splice(i, 1); } else i += 1;
+  }
+  return list;
+}
+
+/** The messages beyond what the record already holds — what one attempt added. */
+export function newSteps(prev, next) {
+  const a = Array.isArray(prev) ? prev.length : 0;
+  return (Array.isArray(next) ? next : []).slice(a);
+}
+
+/**
+ * What the next model is told when it continues another's work. `kind`:
+ *   handoff  — the previous attempt (another model / agent) stopped: an error, a person's choice
+ *   resume   — the run itself was stopped or died and is being resumed from the record
+ *   answer   — the task waited on a person and the answer is now on the board
+ */
+export function continuationNote({ kind = 'handoff', from = '', to = '', reason = '', answer = '' } = {}) {
+  const who = from ? ` by ${from}` : '';
+  if (kind === 'answer') return `The user has answered your question on the board (see the board, or: ${answer}). Continue the task from where you left off — do not repeat work already done above — and finish with your findings.`;
+  if (kind === 'resume') return `This task was interrupted (${reason || 'the run was stopped'}) and is being resumed${to ? ` by ${to}` : ''}. Everything above is the work done so far — read it, do not redo it. Continue from where it stopped and finish with your findings.`;
+  return `You are continuing this task. A previous attempt${who} stopped (${reason || 'it did not finish'}). Everything above is its work so far — read it, do not redo lookups already made. Continue from where it stopped and finish with your findings.`;
+}
+
+/**
+ * The messages to send for an attempt: the task's transcript plus a continuation note when
+ * there is one; the bare task when there is not. `system` travels separately (the host puts
+ * it first) so a transcript never carries a role prompt that a later role might not share.
+ */
+export function messagesFor(task, { prompt, note = null } = {}) {
+  const transcript = Array.isArray(task?.transcript) ? task.transcript : [];
+  if (!transcript.length) return [{ role: 'user', content: String(prompt || '') }];
+  const last = transcript[transcript.length - 1];
+  // A transcript that ends in an unanswered tool call cannot be continued as-is: close it.
+  const closed = last?.role === 'assistant' && Array.isArray(last.tool_calls) && last.tool_calls.length
+    ? [...transcript, ...last.tool_calls.map((c) => ({ role: 'tool', tool_call_id: c.id, content: 'This call was not answered: the attempt stopped here.' }))]
+    : transcript;
+  return note ? [...closed, { role: 'user', content: note }] : closed;
+}
+
+/**
+ * Fold what a host returned into the task's transcript. A host that hands back its wire
+ * transcript (`res.transcript`) is taken as is (minus system); one that only returns text
+ * gets the messages it was sent plus one assistant message — still a continuation.
+ */
+export function mergeTranscript(sent, res) {
+  const returned = Array.isArray(res?.transcript) ? res.transcript.filter((m) => m && m.role !== 'system') : null;
+  if (returned && returned.length >= sent.length) return returned;
+  const text = String(res?.text || '');
+  return text ? [...sent, { role: 'assistant', content: text }] : sent;
+}
+
+/**
+ * The control channel a host holds on a running team: a person's hand-off of a task to a
+ * named model (from the board, either client), or a stop of one task. The runner subscribes.
+ */
+export function createControl() {
+  const listeners = new Set();
+  const pending = new Map(); // taskId -> { model, by } asked before the task subscribed
+  const api = {
+    handoff(taskId, model, by = 'person', reason = '') {
+      const req = { type: 'handoff', taskId, model, by, reason };
+      let taken = false;
+      for (const fn of listeners) { if (fn(req) === true) taken = true; }
+      if (!taken) pending.set(taskId, req);
+      return taken;
+    },
+    _subscribe(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+    _pendingFor(taskId) { const r = pending.get(taskId); if (r) pending.delete(taskId); return r || null; },
+  };
+  return api;
+}

package/team-trail.js

@@ -9,12 +9,15 @@ export function teamLine(ev) {
   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.started': return { type: 'tool', name: role, text: `${role} · ${ev.title || ev.taskId}${ev.resumed ? ` (resumed, ${ev.steps} steps so far)` : ''}` };
     case 'task.waiting': return { type: 'status', text: `${role} is waiting on you — ${ev.text || 'a question on the board'}` };
     case 'run.waiting': return { type: 'status', text: `waiting on you — ${ev.text || ev.type || 'a question on the board'}` };
     case 'run.resumed': return { type: 'status', text: `team ${ev.team} resumed${(ev.carried || []).length ? ` (${ev.carried.length} task${ev.carried.length === 1 ? '' : 's'} carried over)` : ''}` };
     case 'board.post': return ev.post && ev.post.kind !== 'finding' ? { type: 'status', text: `${ev.post.by} ${ev.post.replyTo ? 'replied' : 'posted'} (${ev.post.kind}): ${String(ev.post.text || '').slice(0, 120)}` } : null;
     case 'board.decision': return { type: 'status', text: `${ev.by || 'someone'} ${ev.status} a post` };
+    case 'task.note': return { type: 'status', text: `${role}: ${ev.text}` };
+    case 'task.handoff': return { type: 'status', text: `${role} handed off ${ev.from ? `from ${ev.from} ` : ''}to ${ev.to} by ${ev.by || 'person'}${ev.reason ? ` — ${ev.reason}` : ''}` };
+    case 'task.step': return null;
     case 'task.reappointed': return { type: 'status', text: `${role} → ${ev.model} (${(ev.after || []).join(', ')} unavailable${ev.error ? `: ${String(ev.error).slice(0, 120)}` : ''})` };
     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)}` };
@@ -35,8 +38,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.note': return { type: 'status', text: `${role}: ${ev.text}` };
     case 'task.model': if (lanes.tasks[ev.taskId]) lanes.tasks[ev.taskId] = { ...lanes.tasks[ev.taskId], model: ev.model }; break;
+    case 'task.handoff': if (lanes.tasks[ev.taskId]) lanes.tasks[ev.taskId] = { ...lanes.tasks[ev.taskId], model: ev.to, handoffs: (lanes.tasks[ev.taskId].handoffs || 0) + 1 }; break;
+    case 'task.step': if (lanes.tasks[ev.taskId]) lanes.tasks[ev.taskId] = { ...lanes.tasks[ev.taskId], steps: (lanes.tasks[ev.taskId].steps || 0) + (ev.steps || []).length }; 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;