@chatpanel/events 0.91.0 → 0.92.0

package/index.js

@@ -197,7 +197,7 @@ 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 { emptyRun, foldRun, runFromEvents, checkpointFrom, isResumable, LIVE_RUN_STATUSES, RESUMABLE_RUN_STATUSES , spendOf, describeSpend, runState, priorWorkFor, STALLED_AFTER_MS } from './team-record.js';
 export { validateProject, normalizeProject, defineProject, canTransition as canProjectTransition, blankProject, projectFromForm, emptyProjectRecord, foldProject, projectProgress, ProjectError, PROJECT_STATUSES, PROJECT_ID_RE } from './project.js';
 // Job POSTINGS (F8 §12) — `jobs.js` is the scheduler and keeps `defineJob`; a posting is a JobPost here.
 export { validateJob as validateJobPost, normalizeJob as normalizeJobPost, defineJob as defineJobPost, canTransition as canJobPostTransition, applyAll, jobToRole, readyJobs, blankJob as blankJobPost, jobFromForm as jobPostFromForm, JobError as JobPostError, JOB_STATUSES as JOB_POST_STATUSES, JOB_ID_RE as JOB_POST_ID_RE } from './job.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.91.0",
+  "version": "0.92.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",

package/team-board.js

@@ -234,7 +234,7 @@ export function createBoard({ now = () => Date.now(), newId = null, state = null
 function asFinding(st) {
   return (p) => {
     const t = st.threads.find((x) => x.id === p.threadId);
-    return { id: p.id, kind: p.finding?.kind || 'claim', text: p.text, refs: p.refs || [], confidence: p.finding?.confidence ?? null, role: p.by, taskId: t?.taskId || null, at: p.at, status: p.status };
+    return { id: p.id, kind: p.finding?.kind || 'claim', text: p.text, refs: p.refs || [], confidence: p.finding?.confidence ?? null, role: p.by, taskId: t?.taskId || null, at: p.at, status: p.status, ...(p.finding?.prior ? { prior: true } : {}) };
   };
 }
 

package/team-record.js

@@ -122,3 +122,85 @@ export function isResumable(run) {
   if (RESUMABLE_RUN_STATUSES.includes(run.status)) return true;
   return !!run.stale && LIVE_RUN_STATUSES.includes(run.status); // its client went away mid-run
 }
+
+/**
+ * The run's spend against its cap, as a board shows it: the record's last `run.usage` (or
+ * nothing spent yet) with `ms` measured LIVE for a run still going — the stored figure is as
+ * of the last task's end, and a board read "0 s" through a ten-minute research task.
+ */
+export function spendOf(run, { now = Date.now() } = {}) {
+  const cap = run?.usage?.cap || run?.budget || null;
+  if (!cap || !Object.keys(cap).length) return null;
+  const spent = { tokens: 0, calls: 0, usd: 0, ms: 0, ...(run?.usage?.spent || {}) };
+  // The clock runs while the client is writing, and STOPS where it stopped: a run whose
+  // record says `running` because its client died (or its end never landed) is not still
+  // spending — it read "18m13s / 5m00s" and counting for a member that had finished.
+  const st = runState(run, { now });
+  if (LIVE_RUN_STATUSES.includes(run?.status) && run?.startedAt) spent.ms = Math.max(spent.ms || 0, (st.key === 'stalled' ? Number(run.lastEventAt) || now : now) - run.startedAt);
+  const pct = cap.tokens ? Math.min(100, Math.round(((spent.tokens || 0) / cap.tokens) * 100)) : cap.ms ? Math.min(100, Math.round(((spent.ms || 0) / cap.ms) * 100)) : null;
+  const over = BUDGET_KEYS.filter((k) => cap[k] && (spent[k] || 0) >= cap[k]);
+  return { cap, spent, pct, exhausted: run?.usage?.exhausted || over[0] || null, over };
+}
+const BUDGET_KEYS = ['tokens', 'calls', 'usd', 'ms'];
+
+export const STALLED_AFTER_MS = 2 * 60_000;
+
+/**
+ * What a run IS right now, for a person: the record's status read against the clock. A
+ * record that says `running` with no event for minutes is STALLED — its client stopped
+ * writing (died, or its end never landed) — not running. `{ key, label, tone, detail }`;
+ * `tone` is the chip: on · warn · ok · err · muted.
+ */
+export function runState(run, { now = Date.now(), stalledAfterMs = STALLED_AFTER_MS } = {}) {
+  const s = String(run?.status || 'planning');
+  const quiet = Number.isFinite(run?.quietMs) ? run.quietMs : Math.max(0, now - (Number(run?.lastEventAt) || now));
+  const agoText = (ms) => { const sec = Math.round(ms / 1000); return sec < 60 ? `${sec} s` : sec < 3600 ? `${Math.round(sec / 60)} min` : `${Math.round(sec / 3600)} h`; };
+  if (s === 'waiting') return { key: 'waiting', label: 'waiting on you', tone: 'warn', detail: '' };
+  if (LIVE_RUN_STATUSES.includes(s)) {
+    if (run?.stale === true || quiet > stalledAfterMs) return { key: 'stalled', label: 'stalled', tone: 'err', detail: `no events for ${agoText(quiet)} — its client stopped writing; Resume here picks it up from the record` };
+    return { key: 'running', label: s === 'merging' ? 'merging' : s === 'planning' ? 'planning' : 'running', tone: 'on', detail: `last event ${agoText(quiet)} ago` };
+  }
+  if (s === 'completed') return { key: 'done', label: 'done', tone: 'ok', detail: '' };
+  if (s === 'partial') return { key: 'partial', label: 'done with failures', tone: 'warn', detail: 'a member failed; the rest merged' };
+  if (s === 'answered') return { key: 'answered', label: 'answered — resume to continue', tone: 'warn', detail: '' };
+  if (s === 'over-budget') return { key: 'over-budget', label: 'over budget', tone: 'err', detail: 'stopped with what it had' };
+  if (s === 'stopped') return { key: 'stopped', label: 'stopped', tone: 'muted', detail: '' };
+  if (s === 'failed') return { key: 'failed', label: 'failed', tone: 'err', detail: '' };
+  return { key: s, label: s, tone: 'muted', detail: '' };
+}
+
+/**
+ * Earlier runs whose work a new run should read before repeating it (§12.2.6, the librarian's
+ * first step): the same team (or any, when `team` is empty), a request that says the same
+ * thing (word overlap ≥ `minSimilarity`), findings on the record, not the run itself, newest
+ * first. `runs` is the store's list (`findings` is a count there). Returns
+ * `[{ id, at, similarity, findings }]`; the host fetches the record for the findings.
+ */
+export function priorWorkFor(runs, { team = '', request = '', excludeId = null, minSimilarity = 0.6, maxAgeMs = 7 * 24 * 3600_000, now = Date.now(), limit = 3 } = {}) {
+  const words = (t) => new Set(String(t || '').toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, ' ').split(/\s+/).filter((w) => w.length > 2));
+  const want = words(request);
+  if (!want.size) return [];
+  const sim = (t) => { const have = words(t); if (!have.size) return 0; let hit = 0; for (const w of want) if (have.has(w)) hit += 1; return hit / Math.max(want.size, have.size); };
+  return (runs || [])
+    .filter((r) => r && r.id && r.id !== excludeId && (!team || r.team === team) && !LIVE_RUN_STATUSES.includes(r.status) && (Number(r.findings) || (Array.isArray(r.board) ? r.board.length : 0)) > 0 && now - (Number(r.createdAt) || 0) <= maxAgeMs)
+    .map((r) => ({ id: r.id, at: r.createdAt, similarity: Math.round(sim(r.request) * 100) / 100, findings: Number(r.findings) || (Array.isArray(r.board) ? r.board.length : 0), status: r.status }))
+    .filter((r) => r.similarity >= minSimilarity)
+    .sort((a, b) => b.similarity - a.similarity || b.at - a.at)
+    .slice(0, limit);
+}
+
+const secs = (ms) => { const s = Math.max(0, Math.round((Number(ms) || 0) / 1000)); return s >= 60 ? `${Math.floor(s / 60)}m${String(s % 60).padStart(2, '0')}s` : `${s}s`; };
+const num = (n) => (Number(n) || 0).toLocaleString('en-US');
+
+/** One line: `1,240 / 40,000 tokens · 3 / 20 calls · 2m10s / 15m00s`. Only the capped dimensions. */
+export function describeSpend(spend) {
+  if (!spend?.cap) return '';
+  const { cap, spent } = spend;
+  const over = (k) => ((spend.over || []).includes(k) ? ' (over)' : '');
+  return [
+    cap.tokens ? `${num(spent.tokens)} / ${num(cap.tokens)} tokens${over('tokens')}` : '',
+    cap.calls ? `${num(spent.calls)} / ${num(cap.calls)} calls${over('calls')}` : '',
+    cap.usd ? `$${(Number(spent.usd) || 0).toFixed(2)} / $${Number(cap.usd).toFixed(2)}${over('usd')}` : '',
+    cap.ms ? `${secs(spent.ms)} / ${secs(cap.ms)}${over('ms')}` : '',
+  ].filter(Boolean).join(' · ');
+}

package/team-run.js

@@ -127,6 +127,10 @@ export async function runTeam({
   // model from the board, on either client; the runner continues the task's transcript there.
   control = null,
   recruit = null, projectId = null,
+  // Earlier runs' findings for the same request (team-record.js priorWorkFor, fetched by the
+  // host): `[{ runId, at, request?, findings: [...] }]`. Posted as a "Prior work" thread every
+  // member reads before repeating a lookup — the librarian's first step (§12.2.6).
+  prior = null,
 } = {}) {
   if (typeof callModel !== 'function') throw new TeamRunError('BAD_RUN', 'callModel required');
   const t = normalizeTeam(team); // throws on a team without a budget — O1
@@ -197,6 +201,24 @@ export async function runTeam({
   say('plan.ready', { by: planBy, tasks: tasks.map((x) => ({ id: x.id, role: x.role, title: x.title, dependsOn: x.dependsOn, ...(x.parent ? { parent: x.parent, requestedBy: x.requestedBy || null } : {}), ...(x.grants ? { grants: x.grants, why: x.why || '' } : {}) })) });
   // A thread per task, before anything runs: a member's findings and replies have a home.
   for (const task of tasks) board.openThread({ taskId: task.id, kind: 'task', title: task.title || task.id, by: task.requestedBy || RUNNER, ...(task.parent ? { parent: task.parent } : {}), ...(task.role && task.parent ? { holder: task.role } : {}) });
+  // PRIOR WORK: what an earlier run already found for this request is on the board before
+  // anyone starts — a discussion thread per run, its findings as posts with their refs — so a
+  // second run of the same question reads instead of re-searching. Only findings a person did
+  // not reject; at most 40 per run.
+  if (!resume && Array.isArray(prior)) {
+    for (const pr of prior.filter((x) => x && Array.isArray(x.findings) && x.findings.length)) {
+      const age = Number.isFinite(pr.at) ? Math.max(0, Math.round((now() - pr.at) / 60000)) : null;
+      const th = board.openThread({ kind: 'discussion', title: `Prior work — run ${pr.runId}${age != null ? ` (${age < 60 ? `${age} min` : `${Math.round(age / 60)} h`} ago)` : ''}`, by: RUNNER });
+      board.post({ threadId: th.id, by: RUNNER, kind: 'note', text: `An earlier run answered ${pr.request ? `"${String(pr.request).slice(0, 200)}"` : 'the same request'}. Its findings follow — read them, verify what is stale, and do not repeat lookups already made.`, refs: [`run:${pr.runId}`] });
+      let n = 0;
+      for (const f of pr.findings) {
+        if (!f || !f.text || f.status === 'rejected' || n >= 40) continue;
+        board.post({ threadId: th.id, by: f.role || RUNNER, kind: 'finding', text: String(f.text).slice(0, 2000), refs: [...(Array.isArray(f.refs) ? f.refs : []), `run:${pr.runId}`].slice(0, 8), finding: { kind: f.kind || 'claim', confidence: f.confidence ?? null, prior: true } });
+        n += 1;
+      }
+      say('run.prior', { from: pr.runId, threadId: th.id, findings: n });
+    }
+  }
   // The planner's TOOL PROPOSAL (§15.2): which tools each task will need and why, as a
   // proposal thread a person reads — and what the nudge below holds the member to.
   if (!resume && tasks.some((x) => x.grants?.length)) {