@chatpanel/events 0.96.0 → 0.97.0

package/citations.js

@@ -77,3 +77,52 @@ export function linkifyCitations(answer, sources, { heading = 'Sources' } = {})
     .join('\n');
   return `${linked.trimEnd()}\n\n**${heading}**\n${list}\n`;
 }
+
+// ---------------------------------------------------------------------------------------
+// The collector — what a turn was GIVEN, gathered as its tools return it, and put back
+// under the answer as links. Was the extension's `citationCollector`; the desktop had none,
+// so its answers cited `[1]` with nothing to click.
+// ---------------------------------------------------------------------------------------
+
+/** Tools whose job is to RETURN material rather than to act on something. */
+export const RETRIEVAL_TOOLS = Object.freeze(new Set(['find', 'source', 'history_search', 'web_search', 'search', 'fetch', 'read_page']));
+
+const retrievalName = (name) => String(name || '').replace(/^mcp[_-]/, '').split('__')[0];
+
+/**
+ * Wrap a toolset so every result is read for numbered sources.
+ *
+ * @param tools        `{ execute, … }`; returned as `.tools`, wrapped
+ * @param onRetrieved  `({ tool, count, chars, sources }) => void` — RETRIEVAL IS INPUT. Called
+ *                     per call that returned material, so the turn shows what it was given and
+ *                     by which tool. A retrieval tool that returned no LINKS still returned
+ *                     material (notes, past chats), and is reported with `count: 0` — silence
+ *                     there would under-report exactly the private sources this makes visible.
+ * @returns `{ tools, list(), apply(answer) }`
+ */
+export function createCitationCollector(tools, { onRetrieved = null } = {}) {
+  const sources = new Map();
+  const collect = (name, out) => {
+    const body = typeof out === 'string' ? out : (out?.text || '');
+    if (!body) return;
+    const found = sourcesFromToolText(body);
+    for (const s of found) if (!sources.has(s.rank)) sources.set(s.rank, s);
+    if (!onRetrieved) return;
+    try {
+      if (found.length) onRetrieved({ tool: name, count: found.length, chars: body.length, sources: found.slice(0, 20).map((x) => ({ rank: x.rank, title: x.title || '', url: x.url || '' })) });
+      else if (RETRIEVAL_TOOLS.has(retrievalName(name))) onRetrieved({ tool: name, count: 0, chars: body.length, sources: [] });
+    } catch { /* reporting never breaks a turn */ }
+  };
+  const wrapped = tools && typeof tools.execute === 'function'
+    ? { ...tools, execute: async (name, input, meta) => { const out = await tools.execute(name, input, meta); collect(name, out); return out; } }
+    : tools;
+  return {
+    tools: wrapped,
+    list: () => [...sources.values()],
+    /** The answer with its `[n]` citations linked and a Sources section — or the answer untouched when nothing was retrieved. */
+    apply(answer) {
+      if (!sources.size || !answer || typeof answer !== 'string') return answer;
+      try { return linkifyCitations(answer, [...sources.values()]); } catch { return answer; }
+    },
+  };
+}

package/client-prefs.js

@@ -40,6 +40,10 @@ export const PREF_SECTIONS = Object.freeze([
   { id: 'watch', label: 'Watch', path: ['ui', 'watch'], kind: 'object' },
   { id: 'meetings', label: 'Meetings', path: null, kind: 'object', keys: ['meetingWindowMin', 'liveNotesIntervalMin', 'alertSound'] },
   { id: 'redaction', label: 'Redaction (client-side)', path: ['ui', 'piiRedaction'], kind: 'object' },
+  // Internal sites (source-gate.js): which hosts are internal and how far their content may
+  // travel. A rule the desktop enforces too, or a page internal in the panel is sent
+  // anywhere from the desk.
+  { id: 'internalSites', label: 'Internal sites', path: ['privacy'], kind: 'object' },
 ]);
 
 export const PREF_SECTION_IDS = Object.freeze(PREF_SECTIONS.map((s) => s.id));

package/index.js

@@ -119,12 +119,12 @@ export {
 } from './observability.js';
 export { routeGraph, projectChain } from './route-graph.js';
 export { defineAdapter, createAdapterRegistry, AdapterError } from './adapters.js';
-export { linkifyCitations, sourcesFromToolText } from './citations.js';
+export { linkifyCitations, sourcesFromToolText, createCitationCollector, RETRIEVAL_TOOLS } from './citations.js';
 export { buildTrajectory, phasesOf, lanesOf, filterEntries, displayName, ENTRY_KINDS, threadsOf, threadTitle, promptEntries, turnsOf, threadTree } from './trajectory.js';
 export { createTurnRunner, defineLoop, LOOP_KINDS, LoopError } from './loop.js';
 export { defineModel, defineMiddleware, defineRouteStrategy, createModelRouter, signalsFrom, requirementsFor, requirementsForStep, preferenceFor, failoverOrder, pinnedOrderOf, FAILOVER_CLASS_GAP, FAILOVER_CAPABILITY_GAP, sameModelKey, RouterError } from './router.js';
 export { makeSourceStore, manifestText, shortUrl, readSource, sourceId } from './sources-retrieval.js';
-export { classifySource, extractUrls, hostMatches, meetReach, sourcePolicyFor, DEFAULT_INTERNAL_PATTERNS, INTERNAL_PATTERN_CATALOG } from './sources.js';
+export { classifySource, extractUrls, hostMatches, meetReach, sourcePolicyFor, sourceUrlsOf, DEFAULT_INTERNAL_PATTERNS, INTERNAL_PATTERN_CATALOG } from './sources.js';
 export { defineRule, createRuleEngine, SUPPRESSED, RuleError } from './rules.js';
 export {
   VAULT_VERSION, KDF_ITERATIONS, KDF_HASH, DEFAULT_LOCK_MS, VaultError,
@@ -182,6 +182,9 @@ export {
 // next model.
 export { classifyFailure, createModelHealth, COOLDOWN_MS, UNAVAILABLE_REASONS, normModelName } from './model-health.js';
 export { runWithFailover, failoverExhausted, FAILOVER_MAX_ATTEMPTS } from './failover.js';
+// The source ceiling as a gate, and the citation collector — the last two pieces of the turn
+// wrapper that were the extension's alone.
+export { sourcePolicySettings, sourceGuardFor, sourceGate, isSourceGateError, withinReach } from './source-gate.js';
 export {
   runTurnLoop, createCallRunner, roundCap, withToolSystem, describeCall as describeToolCall, stepResultText, addUsage, normalizeUsage,
   openAiTranscript, anthropicTranscript,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.96.0",
+  "version": "0.97.0",
   "description": "The canonical ChatPanel event-log and capability contracts — 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",
@@ -88,6 +88,7 @@
     "./skill-vars.js": "./skill-vars.js",
     "./slash-commands.js": "./slash-commands.js",
     "./sources-retrieval.js": "./sources-retrieval.js",
+    "./source-gate.js": "./source-gate.js",
     "./sources.js": "./sources.js",
     "./store.js": "./store.js",
     "./structured.js": "./structured.js",
@@ -226,6 +227,7 @@
     "skill-vars.js",
     "slash-commands.js",
     "sources-retrieval.js",
+    "source-gate.js",
     "sources.js",
     "store.js",
     "structured.js",

package/source-gate.js

@@ -0,0 +1,92 @@
+// The source ceiling — would this turn send internal material to a model that is too far
+// away? — as a GATE, not a ranking.
+//
+// Routing is not enough. A router returns null in every uncertain case and null means
+// "leave the choice alone", which is right for a preference and catastrophic for a privacy
+// rule: an internal page with no local model available would have gone to the third party
+// the user had selected. And routing only runs under Auto, so a manually chosen cloud model
+// bypassed it entirely. So this runs on every turn, after routing has had its chance to
+// pick something local, and it REFUSES rather than substituting: silently answering from a
+// different model is the substitution this codebase keeps removing, and silently sending
+// anyway is the leak it exists to stop.
+//
+// Was the extension's `sourceGate` + `sourcePolicySettings` + `sourceUrlsOf`; the desktop
+// had none of it and sent internal pages wherever the picker pointed. The policy (which
+// hosts are internal, how far their content may travel) is the user's and travels in the
+// shared `internalSites` preference section, so both clients enforce the same rule.
+//
+// Class R: no I/O. The target's reach comes from `reachOf` (a bridge agent is 'trusted', a
+// localhost endpoint 'device', the rest 'any') unless the caller already knows it.
+
+import { sourcePolicyFor, sourceUrlsOf, DEFAULT_INTERNAL_PATTERNS } from './sources.js';
+import { reachOf } from './model-candidates.js';
+import { REACH, reachRank } from './reach.js';
+
+// `sourceUrlsOf` lives in sources.js (no router on its graph) so a client's first paint can
+// list a turn's addresses without pulling the router in; it is re-exported here for callers
+// that have the gate anyway.
+export { sourceUrlsOf };
+
+/**
+ * The internal-source policy, read from the `privacy` settings object in ONE place.
+ *
+ * NEVER CONFIGURED and CONFIGURED TO NOTHING are different answers. Undefined means the
+ * user has not been here yet, so the built-ins apply; an array — even an empty one — is a
+ * list they edited, and prepending our own to it would make a default impossible to
+ * remove. Someone testing against localhost has a real reason to delete that line.
+ */
+export function sourcePolicySettings(privacy = {}) {
+  const cfg = privacy || {};
+  const saved = cfg.internalPatterns;
+  const list = Array.isArray(saved)
+    ? saved
+    : (saved == null ? DEFAULT_INTERNAL_PATTERNS : String(saved).split(/[\s,]+/));
+  return {
+    enabled: cfg.internalGuard !== false,
+    patterns: list.map((x) => String(x || '').trim().toLowerCase()).filter(Boolean),
+    ceiling: cfg.internalCeiling === 'trusted' ? 'trusted' : 'device',
+  };
+}
+
+/** What the sources of a turn allow. Null when the guard is off or nothing matched. */
+export function sourceGuardFor(policy, sources = []) {
+  if (!policy || !policy.enabled || !sources?.length) return null;
+  const p = sourcePolicyFor(sources, { patterns: policy.patterns, ceiling: policy.ceiling });
+  return p.internal ? p : null;
+}
+
+/**
+ * The gate. `{ blocked, why, reach, message }` when the target is out of reach for these
+ * sources; null when the turn may go.
+ *
+ * @param policy    `sourcePolicySettings(privacy)`
+ * @param messages  the conversation as it will be sent
+ * @param sources   anything else the caller knows was attached
+ * @param target    `{ kind, baseUrl }` (reach computed) or `{ reach }` (reach known)
+ * @param label     how to name the target in the message
+ */
+export function sourceGate({ policy, messages = [], sources = [], target = {}, label = '' } = {}) {
+  const guard = sourceGuardFor(policy, sourceUrlsOf(messages, sources));
+  if (!guard) return null;
+  const actual = REACH.includes(target?.reach) ? target.reach : reachOf(target || {});
+  if (reachRank(actual) <= reachRank(guard.reach)) return null;
+  const where = guard.reach === 'device' ? 'stay on this device' : 'stay inside your workspace';
+  return {
+    blocked: true,
+    why: guard.why,
+    reach: guard.reach,
+    // Name the source, the model and the way out. A refusal a person cannot act on gets
+    // switched off wholesale, which would leave them worse protected than before.
+    message: `Not sent: ${guard.why}. "${label || 'this model'}" is outside that, and content from an internal source must ${where}. `
+      + 'Pick a local model (or run one), or remove this site under Settings → Privacy → Internal sites.',
+  };
+}
+
+/** Is this error the gate's refusal? A runner reads it as "this model, not this task". */
+export const isSourceGateError = (err) => /^Not sent: /.test(String(err?.message || err || ''));
+
+/** The candidates a turn under `guard` may be handed at all — for a roster, before appointment. */
+export function withinReach(candidates = [], guard = null) {
+  if (!guard) return candidates;
+  return (candidates || []).filter((c) => reachRank(REACH.includes(c?.reach) ? c.reach : reachOf(c || {})) <= reachRank(guard.reach));
+}

package/sources.js

@@ -254,3 +254,20 @@ export function sourcePolicyFor(sources = [], { patterns, ceiling = 'device', ba
     why: `${hits[0].host || 'the source'} matches '${hits[0].matched}' — kept ${safeCeiling === 'device' ? 'on this device' : 'inside your workspace'}`,
   };
 }
+
+/**
+ * Every address a conversation carries: each attachment's `url`, every URL in a message
+ * body (an internal link pasted into a message — or arriving in a tool result written back
+ * into the conversation — is internal material just as much as an attachment is), plus
+ * anything the caller states outright. The WHOLE conversation, because an internal page
+ * attached three turns ago is still in the text being sent now.
+ */
+export function sourceUrlsOf(messages, extraSources = []) {
+  const urls = [];
+  for (const m of messages || []) {
+    for (const a of m?.attachments || []) if (a?.url) urls.push(a.url);
+    for (const u of extractUrls(typeof m?.content === 'string' ? m.content : '')) urls.push(u);
+  }
+  for (const s of extraSources || []) if (s) urls.push(typeof s === 'string' ? s : (s.url || s.href || ''));
+  return urls.filter(Boolean);
+}

package/team-record.js

@@ -70,7 +70,10 @@ export function foldRun(run, ev) {
       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.model': { const t = taskOf(run, p.taskId); if (t) { t.model = p.model; t.attempts = [...(t.attempts || []), { model: p.model, ...(p.label ? { label: p.label } : {}), at, attempt: p.attempt }]; } break; }
+    // Which engine the attempt runs on (pillars §13): kept on the attempt, so a record folded
+    // from events names the model the way the runner's own `attempts` do.
+    case 'task.routed': { const t = taskOf(run, p.taskId); const a = t?.attempts?.at?.(-1); if (a && p.engine && (a.attempt == null || a.attempt === p.attempt)) a.engine = p.engine; 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; }

package/team-run.js

@@ -69,6 +69,9 @@ export function isModelUnavailable(error) {
   // fetch" (the extension reports it as "network error") — a local model killed mid-run
   // arrived as the latter and ended the task on its first attempt with Claude Code sitting
   // idle on the roster.
+  // The source gate's refusal (source-gate.js) is about THIS model's reach, not the task:
+  // the next appointment, within reach, can do it.
+  if (/^Not sent: /.test(m)) return true;
   return /model[_ ]not[_ ]found|not found|not deployed|inaccessible|does not exist|no such model|unknown model|unsupported model|not available|unavailable|no api key|not configured|"status":\s*(404|401|403|500|502|503)\b|\b(404|401|403|502|503)\b|exited \d+|returned no answer|did not answer|closed the connection|couldn't reach|could not reach|ECONNREFUSED|ECONNRESET|ENOTFOUND|EHOSTUNREACH|socket hang up|fetch failed|failed to fetch|load failed|network ?error|overloaded|capacity/i.test(m);
 }
 
@@ -414,7 +417,9 @@ export async function runTeam({
           // 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.
-          const exclude = new Set();
+          // A resumed task does not walk back into the models that were unavailable the last
+          // time it ran — that is how one task read `A → B → A → B → A → B` on the board.
+          const exclude = new Set((was?.attempts || []).filter((a) => a && a.model && a.status === 'error' && isModelUnavailable(a.error)).map((a) => a.model));
           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;
@@ -440,10 +445,12 @@ export async function runTeam({
             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 && 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 });
+            say('task.model', { taskId: task.id, role: role.id, model: m.model, label: m.label || null, attempt });
             routed = routeOf(m, role, { attempt, exclude, handoff: handoffNow });
             say('task.routed', { taskId: task.id, role: role.id, attempt, ...routed });
-            attempts.push({ model: m.model, engine: routed.engine, at: now(), continued: !!note });
+            // The label beside the id: a work log that reads `mqk41ucyhmz1au → mqqzh4970js34c` names
+            // nothing to the person reading it.
+            attempts.push({ model: m.model, label: m.label || routed.engine?.label || routed.engine?.model || null, engine: routed.engine, at: now(), continued: !!note });
             attemptNo = attempts.length;
             const sent = messagesFor({ transcript }, { prompt, note });
             // The record grows AS THE ATTEMPT GOES: a host that reports each wire message the
@@ -525,7 +532,7 @@ export async function runTeam({
       // the board sees "researcher failed: network error" where it happened, and what was tried.
       if (thread && status === 'ok') board.setThreadStatus(thread.id, 'resolved');
       else if (thread && status !== 'waiting') {
-        board.post({ threadId: thread.id, by: RUNNER, kind: 'note', text: `${role?.id || task.role} ${status === 'over-budget' ? 'stopped at the budget' : 'failed'}${error ? `: ${String(error).slice(0, 300)}` : ''}${attempts.length > 1 ? ` (after ${attempts.length} models: ${attempts.map((a) => a.model).join(', ')})` : ''}.` });
+        board.post({ threadId: thread.id, by: RUNNER, kind: 'note', text: `${role?.id || task.role} ${status === 'over-budget' ? 'stopped at the budget' : 'failed'}${error ? `: ${String(error).slice(0, 300)}` : ''}${attempts.length > 1 ? ` (after ${attempts.length} models: ${attempts.map((a) => a.label || a.model).join(', ')})` : ''}.` });
         board.setThreadStatus(thread.id, 'failed');
       }
       const row = { id: task.id, role: task.role, title: task.title, status, text, error, usage, ms: now() - t0, findings, transcript: clipTranscript(transcript), attempts, ...(task.parent ? { parent: task.parent } : {}), ...(routed ? { routed } : {}), ...(scm ? { scm } : {}), ...(askedAndWaiting ? { waitingOn: askedAndWaiting } : {}) };

package/team-worklog.js

@@ -49,7 +49,7 @@ export function workLogFor(run, taskId) {
   const out = [];
   const attempts = Array.isArray(task.attempts) ? task.attempts : [];
   const baseAt = num(task.startedAt, num(attempts[0]?.at, num(run?.startedAt, 0)));
-  attempts.forEach((a, i) => out.push({ id: `attempt:${i + 1}`, kind: 'attempt', at: num(a.at, baseAt + i), by: 'runner', attempt: i + 1, model: a.model || '', engine: a.engine || null, continued: !!a.continued, status: a.status || null, error: a.error || null }));
+  attempts.forEach((a, i) => out.push({ id: `attempt:${i + 1}`, kind: 'attempt', at: num(a.at, baseAt + i), by: 'runner', attempt: i + 1, model: a.label || a.engine?.label || a.engine?.model || a.model || '', modelId: a.model || '', engine: a.engine || null, continued: !!a.continued, status: a.status || null, error: a.error || null }));
 
   // Steps: stamped ones sort by their time; unstamped ones follow their attempt in order.
   const steps = Array.isArray(task.transcript) ? task.transcript : [];
@@ -101,7 +101,7 @@ export function workLogFor(run, taskId) {
 }
 
 function endText(task, attempts) {
-  const tried = attempts.length > 1 ? ` after ${attempts.length} models (${attempts.map((a) => a.model).join(' → ')})` : '';
+  const tried = attempts.length > 1 ? ` after ${attempts.length} models (${attempts.map((a) => a.label || a.engine?.label || a.engine?.model || a.model).join(' → ')})` : '';
   const s = task.status;
   if (s === 'ok') return `done${tried} · ${task.findings || 0} finding${task.findings === 1 ? '' : 's'} · ${task.tools || 0} tool call${task.tools === 1 ? '' : 's'}`;
   if (s === 'waiting') return 'waiting on a person';