@chatpanel/events 0.2.0

package/kernel.js

@@ -0,0 +1,255 @@
+// The plugin kernel — the part that cannot itself be a plugin.
+//
+// Everything in ChatPanel is a plugin: the loop, tools, skills, storage, renderers, UI
+// slots, sources, model providers, presets, redaction POLICY. This file is what makes
+// that safe to say.
+//
+// "Security is a mandatory plugin" is only meaningful if something that is NOT a plugin
+// enforces the mandate — otherwise mandatory is a config value, and a config value is
+// disableable. So the kernel SHRINKS rather than grows. It does three things, none of
+// them extensible, and deliberately nothing else:
+//
+//   1. load plugins (delegated to the registry — revertible effects, reactive availability);
+//   2. refuse to run when a required plugin is absent or failed;
+//   3. enforce guard monotonicity — a guard may reduce permission, never widen it.
+//
+// POLICY VS MECHANISM. Redaction policy (what counts as sensitive, which dial the user
+// picked, whether an org gets visibility) is a plugin. The redaction mechanism and the
+// egress guard are not. That is what lets privacy be a real on/off dial without ever
+// creating a path where bytes leave unguarded: security is not a dial, privacy is.
+//
+// NO DEPENDENCY ON THE EVENT LOG, matching registry.js — `onEvent` is a plain hook the
+// host maps to schema events if it wants them. That keeps the kernel runnable in the
+// extension, the gateway and the bridge unchanged.
+
+import { createRegistry } from './registry.js';
+
+export class KernelError extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.name = 'KernelError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+/** The default non-negotiables. A host may require more; it may not require fewer. */
+export const REQUIRED_PLUGINS = Object.freeze(['security']);
+
+/**
+ * A decision is a permission, not a boolean: `allow` plus the scopes it covers.
+ * Kept deliberately small — anything richer invites a lattice we cannot check.
+ */
+export const ALLOW_ALL = Object.freeze({ allow: true, scopes: null, reasons: [] });
+
+const asScopeSet = (s) => (s == null ? null : new Set(s));
+
+/**
+ * The MEET of two decisions — the heart of the monotonicity guarantee.
+ *
+ * A guard cannot widen because widening is never constructed, not because we inspect the
+ * result and complain. Detect-and-reject would leave a window in which the widened value
+ * existed and could be read by whatever ran next; a meet has no such window.
+ *
+ * `scopes: null` means "unscoped / all", so it is the top of the lattice and intersecting
+ * with it is identity — that keeps a guard that does not care about scopes from
+ * accidentally narrowing to nothing.
+ */
+export function meetDecisions(a, b) {
+  const as = asScopeSet(a.scopes);
+  const bs = asScopeSet(b.scopes);
+  let scopes = null;
+  if (as && bs) scopes = [...as].filter((s) => bs.has(s));
+  else if (as) scopes = [...as];
+  else if (bs) scopes = [...bs];
+  return {
+    allow: !!a.allow && !!b.allow,
+    scopes,
+    reasons: [...(a.reasons || []), ...(b.reasons || [])],
+  };
+}
+
+/** True when `out` asked for more than `input` allowed — a misbehaving or hostile plugin. */
+function widened(input, out) {
+  if (!input.allow && out.allow) return true;
+  const is = asScopeSet(input.scopes);
+  const os = asScopeSet(out.scopes);
+  if (!is) return false;              // input was unscoped: nothing to widen past
+  if (!os) return true;               // guard tried to drop scoping entirely
+  return [...os].some((s) => !is.has(s));
+}
+
+/**
+ * @param required plugin ids that must be active before `start()` resolves. Callers may
+ *        add to REQUIRED_PLUGINS; they cannot remove from it.
+ * @param onEvent `{ event, ...detail }` — 'plugin:activated' | 'plugin:failed' |
+ *        'guard:widened' | 'started' | 'stopped'.
+ */
+export function createKernel({ required = [], onEvent = null } = {}) {
+  const requiredIds = [...new Set([...REQUIRED_PLUGINS, ...required])];
+  const registry = createRegistry({
+    onEvent: (d) => emit(`registry:${d.event}`, d),
+  });
+
+  const declared = new Map();   // id -> declaration
+  const handles = new Map();    // id -> registry handle
+  const guards = new Map();     // name -> [{ pluginId, fn }]
+  let started = false;
+
+  const emit = (event, detail = {}) => { if (onEvent) onEvent({ event, ...detail }); };
+
+  /**
+   * Declare a plugin. Declaration is NOT activation: manifests are static so the kernel
+   * can answer "what is installed" without executing anything, and `activate` is where a
+   * host does its `await import()`. A kernel that had to load every plugin to know what
+   * it had would put the whole graph on first paint, and first paint is a release gate.
+   */
+  function define(plugin) {
+    const { id, requires = [], activate, load } = plugin || {};
+    if (!id || typeof id !== 'string') throw new KernelError('BAD_PLUGIN', 'plugin.id required');
+    if (typeof activate !== 'function' && typeof load !== 'function') {
+      throw new KernelError('BAD_PLUGIN', `plugin '${id}': activate or load required`);
+    }
+    if (declared.has(id)) throw new KernelError('DUPLICATE', `plugin '${id}' is already defined`);
+    declared.set(id, { ...plugin, requires: [...requires] });
+    return () => remove(id);
+  }
+
+  function remove(id) {
+    if (requiredIds.includes(id)) {
+      // Not a permission check that could be satisfied — there is no argument that makes
+      // removing the security plugin acceptable, so it is not expressible.
+      throw new KernelError('REQUIRED', `plugin '${id}' is required and cannot be removed`);
+    }
+    declared.delete(id);
+    const h = handles.get(id);
+    handles.delete(id);
+    for (const [name, list] of guards) {
+      const kept = list.filter((g) => g.pluginId !== id);
+      if (kept.length) guards.set(name, kept); else guards.delete(name);
+    }
+    return h ? h.dispose() : Promise.resolve();
+  }
+
+  /** The scope a plugin's `activate` receives — the registry's, plus guard registration. */
+  function scopeFor(id, inner) {
+    return {
+      ...inner,
+      /**
+       * Register a guard. It receives `(request, decision)` and returns a decision; the
+       * kernel meets its answer with what came in, so it can only ever narrow.
+       */
+      guard(name, fn) {
+        if (typeof fn !== 'function') throw new KernelError('BAD_GUARD', `guard '${name}' must be a function`);
+        const list = guards.get(name) || [];
+        list.push({ pluginId: id, fn });
+        guards.set(name, list);
+        return () => {
+          const cur = (guards.get(name) || []).filter((g) => g.fn !== fn);
+          if (cur.length) guards.set(name, cur); else guards.delete(name);
+        };
+      },
+    };
+  }
+
+  /**
+   * Run every guard for `name` and return the narrowest decision any of them permits.
+   * Order-independent by construction: meet is associative and commutative, so guards
+   * cannot race each other into a different answer — which is what lets them be plugins.
+   */
+  function decide(name, request, initial = ALLOW_ALL) {
+    let decision = { allow: !!initial.allow, scopes: initial.scopes ?? null, reasons: [...(initial.reasons || [])] };
+    for (const { pluginId, fn } of guards.get(name) || []) {
+      let out;
+      try {
+        out = fn(request, decision);
+      } catch (err) {
+        // A guard that throws is a guard that did not permit. Fail closed: the
+        // alternative is that crashing a guard becomes a way to bypass it.
+        decision = meetDecisions(decision, { allow: false, scopes: null, reasons: [`${pluginId}: guard threw (${err.message})`] });
+        continue;
+      }
+      if (out == null) continue;                       // abstained
+      if (out === true) continue;                      // permitted, unchanged
+      if (out === false) out = { allow: false, scopes: null, reasons: [`${pluginId}: denied`] };
+      const norm = { allow: out.allow !== false, scopes: out.scopes ?? null, reasons: out.reasons || [] };
+      if (widened(decision, norm)) emit('guard:widened', { guard: name, pluginId });
+      decision = meetDecisions(decision, norm);
+    }
+    return decision;
+  }
+
+  /**
+   * Activate everything declared, then verify the required set is genuinely ACTIVE —
+   * not merely declared. A required plugin that failed to activate is the same problem
+   * as one that was never installed, and the kernel must not be the component that
+   * papers over the difference.
+   */
+  async function start() {
+    if (started) return kernel;
+    const missing = requiredIds.filter((id) => !declared.has(id));
+    if (missing.length) {
+      throw new KernelError('MISSING_REQUIRED', `kernel will not start: required plugin(s) not defined: ${missing.join(', ')}`, missing);
+    }
+    // Required plugins first, so a dependent that reaches for security during its own
+    // activation finds it — the same ordering rule the registry applies to teardown.
+    const ordered = [...declared.values()].sort(
+      (a, b) => (requiredIds.includes(b.id) ? 1 : 0) - (requiredIds.includes(a.id) ? 1 : 0),
+    );
+    // Resolve `load` BEFORE registering. Registry activation is synchronous — an effect
+    // registered after activation returned would not be in the disposer stack, so the
+    // inverse would not run. Awaiting the import here is what keeps a manifest static
+    // (the kernel knows what is installed without executing it) while the module itself
+    // still only costs anything when it activates.
+    for (const p of ordered) {
+      if (handles.has(p.id)) continue;
+      let activate = p.activate;
+      if (!activate) {
+        try {
+          const mod = await p.load();
+          activate = mod?.activate || mod?.default;
+        } catch (err) {
+          throw new KernelError('LOAD_FAILED', `plugin '${p.id}' failed to load: ${err.message}`, p.id);
+        }
+        if (typeof activate !== 'function') {
+          throw new KernelError('BAD_PLUGIN', `plugin '${p.id}': loaded module exports no activate`, p.id);
+        }
+      }
+      handles.set(p.id, registry.register({
+        name: p.id,
+        requires: p.requires,
+        apply: (inner) => activate(scopeFor(p.id, inner)),
+      }));
+    }
+    const notActive = requiredIds.filter((id) => handles.get(id)?.state !== 'active');
+    if (notActive.length) {
+      const detail = notActive.map((id) => ({ id, error: handles.get(id)?.error?.message || 'inactive', waitingFor: registry.pending().find((p) => p.name === id)?.waitingFor || [] }));
+      await registry.dispose();
+      throw new KernelError('REQUIRED_INACTIVE', `kernel will not start: required plugin(s) not active: ${notActive.join(', ')}`, detail);
+    }
+    started = true;
+    emit('started', { plugins: registry.active() });
+    return kernel;
+  }
+
+  const kernel = {
+    define,
+    remove,
+    decide,
+    start,
+    get started() { return started; },
+    /** What is installed, whether or not it activated — a manifest question. */
+    list: () => [...declared.keys()].sort(),
+    active: () => registry.active(),
+    pending: () => registry.pending(),
+    required: () => [...requiredIds],
+    guards: () => [...guards.keys()].sort(),
+    registry,
+    async stop() {
+      started = false;
+      await registry.dispose();
+      emit('stopped', {});
+    },
+  };
+  return kernel;
+}

package/loop.js

@@ -0,0 +1,132 @@
+// The loop contract — turn lifetime belongs to the kernel, not to the loop.
+//
+// We already run four loops: chat, meeting scribe, watch, and the notes swarm. They were
+// never expressed once; each surface grew its own, and the shared parts were copied. On
+// 2026-08-16 that produced a real bug — `streamChat` opened a turn, one exit path
+// returned above the close, and every finished note reported itself as still running.
+//
+// The fix that day was to route both exits through one helper. The fix here is that
+// there is nothing to route: a loop's `run` receives a context with NO way to open or
+// close a turn. The runner opens before calling it and closes in `finally`, so "forgot to
+// close on one path" is not a mistake a loop author is able to make. That is the
+// difference between a bug fixed and a bug class removed.
+//
+// The runner takes `now`/`newId` rather than reading a clock, matching event.js: this
+// package stays pure so the identical code runs in the extension, gateway and bridge, and
+// so replay is reproducible (order.js never consults wall time; I6 asserts it).
+
+export const LOOP_KINDS = Object.freeze(['chat', 'note', 'meeting', 'watch', 'assist', 'suggestion', 'topics', 'other']);
+
+export class LoopError extends Error {
+  constructor(code, message) { super(message); this.name = 'LoopError'; this.code = code; }
+}
+
+/**
+ * Declare a loop. A declaration is inert — it names a kind and supplies `run`; the runner
+ * supplies everything about when a turn exists.
+ */
+export function defineLoop({ id, kind = 'other', run, background = false }) {
+  if (!id) throw new LoopError('BAD_LOOP', 'loop.id required');
+  if (typeof run !== 'function') throw new LoopError('BAD_LOOP', `loop '${id}': run required`);
+  return Object.freeze({ id, kind, run, background: !!background });
+}
+
+/**
+ * @param emit    `(type, payload)` — the host maps these to the event schema. Kept as a
+ *                plain hook so this module has no dependency on the log, matching registry.js.
+ * @param decide  optional `(guard, request) => decision` — normally `kernel.decide`. A
+ *                security plugin can refuse a turn before any model call happens, which is
+ *                the whole reason guards exist below the loop rather than inside it.
+ */
+export function createTurnRunner({ now = () => 0, newId, emit = () => {}, decide = null } = {}) {
+  if (typeof newId !== 'function') throw new LoopError('BAD_RUNNER', 'newId required — the runner must not invent identity');
+
+  /**
+   * Run one turn of `loop`. Returns whatever `run` returned.
+   *
+   * `request.turnId` lets a caller supply identity it already has (the side panel's
+   * assistant-message id), so the turn record and the tool events that reference it group
+   * into ONE run rather than two — the mismatch that split runs in Activity.
+   */
+  async function run(loop, request = {}) {
+    if (!loop || typeof loop.run !== 'function') throw new LoopError('BAD_LOOP', 'runner.run needs a loop with run()');
+
+    const turnId = request.turnId || newId();
+    const kind = request.kind || loop.kind || 'other';
+
+    // Ask BEFORE opening a turn: a denied turn should leave no trace of having started,
+    // and a guard that only ran after the model call would be documentation, not a guard.
+    if (decide) {
+      const d = decide('turn.start', { turnId, kind, loopId: loop.id, ...request });
+      if (d && d.allow === false) {
+        emit('policy.denied', { turnId, kind, loopId: loop.id, reasons: d.reasons || [] });
+        throw new LoopError('DENIED', `turn denied: ${(d.reasons || []).join('; ') || 'policy'}`);
+      }
+    }
+
+    // The turn began when the USER acted, not when the model call did. Everything between
+    // — assembling tools, connecting to MCP servers — is time they waited, and a duration
+    // that excludes it says 2.6s about a message that took 48. Callers that know the real
+    // moment pass it; the rest fall back to now.
+    const startedAt = Number.isFinite(request.startedAt) ? request.startedAt : now();
+    let closed = false;
+    // Facts the loop learns while running — token usage, the model that actually served
+    // it — belong on the turn record. The loop may CONTRIBUTE them; it still cannot
+    // decide when the turn ends. Handing over the payload is not the same as handing over
+    // the lifetime, and only the second one was ever the problem.
+    let reported = {};
+    // The ONE place a turn closes. Idempotent because a retry path or a double-catch must
+    // not be able to write two endings for one turn — a log that can say a turn ended
+    // twice cannot be replayed.
+    const close = (reason, produced) => {
+      if (closed) return;
+      closed = true;
+      emit('turn.ended', { ...reported, turnId, reason, stepped: !!produced, ms: now() - startedAt, kind });
+    };
+
+    emit('turn.started', {
+      turnId, kind, loopId: loop.id,
+      agentId: request.agentId || null,
+      // WHICH THREAD THIS BELONGS TO. A run on its own is not the unit anyone reasons about —
+      // a conversation is, and a meeting or a note can hold many runs (live monitors,
+      // summaries, a swarm of agents). Without both halves the log is 1,205 unrelated rows.
+      surface: request.surface || null,
+      sourceId: request.sourceId || null,
+      background: request.background ?? loop.background,
+    });
+
+    let produced = false;
+    try {
+      // NOTE what this context does NOT contain: no close, no end, no turn handle. A loop
+      // cannot leave its own turn open because it was never given the ability to close it.
+      const result = await loop.run({
+        turnId,
+        kind,
+        signal: request.signal,
+        request,
+        /** Report that something reached the user — this is a fact about the turn, not control over it. */
+        produced: () => { produced = true; },
+        /**
+         * Contribute facts to the turn record (tokens, model, cost). Merged into
+         * `turn.ended`, and never able to overwrite the fields the runner owns — a loop
+         * that could rewrite its own turnId or reason would be holding lifetime again by
+         * another name.
+         */
+        report: (fields) => { if (fields && typeof fields === 'object') reported = { ...reported, ...fields }; },
+        /** Loops emit their own domain events; lifetime is still not theirs. */
+        emit: (type, payload) => emit(type, { turnId, ...payload }),
+      });
+      if (result !== undefined && result !== null && result !== '') produced = true;
+      close(request.signal?.aborted ? 'aborted' : 'ok', produced);
+      return result;
+    } catch (err) {
+      // An abort is not a failure: the user asking it to stop and the loop breaking are
+      // different facts, and collapsing them makes the log useless for the question people
+      // actually ask ("did it fail, or did I stop it?").
+      close(request.signal?.aborted ? 'aborted' : 'error', produced);
+      throw err;
+    }
+  }
+
+  return { run };
+}

package/manifest.js

@@ -0,0 +1,107 @@
+// What is installed, and what the user has switched off.
+//
+// Four registries now exist — adapters, tool groups, search engines, sources — and each is
+// small and correct on its own. What none of them can answer is the question a user asks:
+// "what is running, and can I turn that off?" Answering it in four places would be the
+// duplication that already bit us with the engine list, one level up.
+//
+// So the KERNEL owns the manifest and the registries consult it. This is admission control,
+// not a rewrite: a registry keeps its own shape and simply refuses to offer something the
+// user has disabled. It is also the seam that makes user-contributed plugins possible —
+// once a plugin can arrive from outside, "is this allowed to run" must be asked somewhere
+// that is not the plugin itself.
+//
+// Persistence is INJECTED. Where the toggles live is a platform question (chrome.storage,
+// a file, a database) and the manifest has no business knowing.
+
+export class ManifestError extends Error {
+  constructor(code, message) { super(message); this.name = 'ManifestError'; this.code = code; }
+}
+
+/** Where a plugin came from. `user` is the one that must never skip a guard. */
+export const SOURCES = Object.freeze(['built-in', 'user']);
+
+/**
+ * @param required ids that cannot be disabled, whatever the stored state says. Security is
+ *        the canonical member: a mandatory plugin the user can switch off is not mandatory,
+ *        it is a default.
+ * @param disabled the user's stored choices — ids they have turned OFF. Stored as the
+ *        exception rather than the full state on purpose: a plugin added in a later release
+ *        is then enabled by default without a migration, because absence means "not
+ *        disabled" rather than "unknown".
+ */
+export function createManifest({ required = ['security'], disabled = [], onChange = null } = {}) {
+  const entries = new Map();
+  const off = new Set(disabled);
+  const req = new Set(required);
+
+  const notify = () => { if (onChange) onChange([...off].sort()); };
+
+  return {
+    /**
+     * Declare something installed. Idempotent, so a registry can register on every build
+     * without accumulating duplicates.
+     */
+    register({ id, kind, label, source = 'built-in', description = '' }) {
+      if (!id) throw new ManifestError('BAD_ENTRY', 'plugin id required');
+      if (!SOURCES.includes(source)) throw new ManifestError('BAD_ENTRY', `plugin '${id}': unknown source '${source}'`);
+      entries.set(id, { id, kind: kind || 'plugin', label: label || id, source, description });
+      return () => entries.delete(id);
+    },
+
+    /**
+     * The question every registry asks. Unknown ids are ENABLED: a registry may consult the
+     * manifest before anything has registered, and defaulting to off would make a plugin
+     * silently vanish because of a load-order accident.
+     */
+    isEnabled(id) {
+      if (req.has(id)) return true;
+      return !off.has(id);
+    },
+
+    /** Turn something on or off. Required plugins refuse rather than reporting success. */
+    setEnabled(id, enabled) {
+      if (req.has(id) && !enabled) {
+        throw new ManifestError('REQUIRED', `'${id}' is required and cannot be disabled`);
+      }
+      const was = !off.has(id);
+      if (enabled) off.delete(id); else off.add(id);
+      if (was !== !!enabled) notify();
+      return this.isEnabled(id);
+    },
+
+    /** Everything installed, with its current state — what a settings page renders. */
+    list() {
+      return [...entries.values()]
+        .map((e) => ({ ...e, enabled: this.isEnabled(e.id), required: req.has(e.id) }))
+        .sort((a, b) => (a.kind === b.kind ? a.label.localeCompare(b.label) : a.kind.localeCompare(b.kind)));
+    },
+
+    /** Only the ids that are OFF — the shape that persists (see the note above). */
+    disabledIds: () => [...off].sort(),
+
+    /**
+     * Adopt state changed elsewhere.
+     *
+     * A manifest is not a fact read once at startup: the user toggles a plugin in one place
+     * (a settings page, another window, another device) and every OTHER place holding a
+     * manifest is now wrong. Without this, a toggle appears to do nothing until reload —
+     * which reads as the switch being broken.
+     *
+     * Deliberately does NOT notify: this is the arrival of someone else's change, and
+     * echoing it back is how two contexts write over each other forever.
+     */
+    sync(ids) {
+      const next = new Set(Array.isArray(ids) ? ids : []);
+      if (next.size === off.size && [...next].every((id) => off.has(id))) return false;
+      off.clear();
+      for (const id of next) off.add(id);
+      return true;
+    },
+
+    /** Filter a registry's candidates. The one call a registry needs to make. */
+    filter(items, idOf = (x) => x?.id) {
+      return (items || []).filter((x) => this.isEnabled(idOf(x)));
+    },
+  };
+}

package/mcp-errors.js

@@ -0,0 +1,87 @@
+// Turn an MCP launch failure into something a person can act on.
+//
+// A local MCP server that will not start reports whatever its process printed, and that is
+// usually a wall of shell noise. A real example: a published package whose executable has
+// no `#!/usr/bin/env node` line, so the SHELL ran a JavaScript file and produced twelve
+// lines of "import: command not found". Nothing in that says what is wrong, whose fault it
+// is, or what to do — and the natural reading is "ChatPanel is broken", which is the one
+// interpretation that is definitely false.
+//
+// The signatures are recognisable, so recognising them is cheap. Where we cannot recognise
+// one, the raw output is still shown: a wrong explanation is worse than none.
+//
+// Shared because the gateway and the bridge launch the same servers and will hit the same
+// failures — diagnosing them in three places would produce three different diagnoses.
+
+const RULES = [
+  {
+    id: 'missing-shebang',
+    // `import:`/`const:` "command not found" means a shell executed JavaScript.
+    test: (t) => /(import|const|export):\s*(command not found|not found)/i.test(t)
+      || /syntax error near unexpected token/i.test(t) && /command not found/i.test(t),
+    explain: (pkg) => ({
+      summary: `${pkg || 'This MCP server'} cannot start: its executable is missing a shebang.`,
+      detail:
+        'The package\'s entry file is JavaScript but has no `#!/usr/bin/env node` first line, so the '
+        + 'shell tries to run it as a shell script. That is a bug in the published package, not in your '
+        + 'setup — nothing you configure here can fix it.',
+      fix: 'Report it to the package author, pin an earlier version that worked, or use a different server.',
+      blame: 'package',
+    }),
+  },
+  {
+    id: 'not-found',
+    test: (t) => /npm ERR!.*(404|E404)|could not determine executable|command not found: npx/i.test(t),
+    explain: (pkg) => ({
+      summary: `${pkg || 'The package'} could not be found or has no runnable command.`,
+      detail: 'npm resolved nothing to run for this package name and version.',
+      fix: 'Check the package name and version, and that the registry in use publishes it.',
+      blame: 'config',
+    }),
+  },
+  {
+    id: 'no-bridge',
+    test: (t) => /can'?t reach the chatpanel bridge|ECONNREFUSED.*4319/i.test(t),
+    explain: () => ({
+      summary: 'The ChatPanel Bridge is not running.',
+      detail: 'Local MCP servers are launched by the bridge, so nothing can start without it.',
+      fix: 'Start it with `npx @chatpanel/bridge`, then try again.',
+      blame: 'setup',
+    }),
+  },
+  {
+    id: 'node-version',
+    test: (t) => /requires node|unsupported engine|SyntaxError: Unexpected token '\?\?'/i.test(t),
+    explain: (pkg) => ({
+      summary: `${pkg || 'This server'} needs a newer Node than the one launching it.`,
+      detail: 'The process started but failed on syntax its Node version does not support.',
+      fix: 'Upgrade Node, or run the server with a version manager that selects a newer one.',
+      blame: 'setup',
+    }),
+  },
+];
+
+/**
+ * @returns { id, summary, detail, fix, blame, raw } — or null when nothing is recognised,
+ * because a confident wrong explanation costs more than showing the output as it came.
+ */
+export function explainMcpError(text, { packageName = '' } = {}) {
+  const t = String(text || '');
+  if (!t.trim()) return null;
+  for (const rule of RULES) {
+    if (!rule.test(t)) continue;
+    return { id: rule.id, ...rule.explain(packageName), raw: t };
+  }
+  return null;
+}
+
+/** The package a command was trying to run, for naming it in the explanation. */
+export function packageFromArgs(args = []) {
+  for (const a of args) {
+    const s = String(a);
+    if (s.startsWith('-')) continue;
+    if (s === 'npx' || s === 'node') continue;
+    return s;
+  }
+  return '';
+}

package/meeting-analyzers.js

@@ -0,0 +1,83 @@
+// What a meeting produces, as declarations.
+//
+// A meeting already generates several kinds of derived thing: a running summary, insight
+// sections (decisions, action items, risks), and live monitors that watch for an answer to
+// a standing question. Each is written separately — its own prompt shape, its own cadence,
+// its own storage — so adding a fifth means touching several files and nothing outside the
+// extension can offer one.
+//
+// They are the same shape underneath: run over the transcript so far, on some trigger,
+// producing a typed result that is stored and shown. Declaring that shape gives three
+// things at once — a Plugins entry the user can switch off, a cadence the runtime can honour
+// without each analyzer implementing its own timer, and a contract the gateway could later
+// run server-side without rewriting callers.
+//
+// WHAT THIS IS NOT: a scheduler. Declaring "every 90 seconds" does not start a timer here;
+// the host decides when to run and this says what running means. Putting the clock in the
+// contract would make it untestable and unrunnable off a browser.
+
+export class AnalyzerError extends Error {
+  constructor(code, message) { super(message); this.name = 'AnalyzerError'; this.code = code; }
+}
+
+/** When an analyzer wants to run. The host maps these to its own timers and events. */
+export const CADENCES = Object.freeze([
+  'periodic',   // every `everyMs` while the meeting is live
+  'on-demand',  // only when the user asks
+  'on-end',     // once, when the meeting finishes
+]);
+
+/**
+ * @param produces what the result IS — 'summary' | 'sections' | 'answer' | 'text'. The host
+ *        uses it to decide where the output goes, so an analyzer never has to know about
+ *        storage.
+ * @param run   async ({ transcript, summary, previous, meeting, ask }) => result. `ask` is
+ *        the model call, injected: an analyzer that imported one could not run in the
+ *        gateway, and could not be tested without a network.
+ */
+export function defineMeetingAnalyzer({
+  id, label, produces = 'text', cadence = 'on-demand', everyMs = 0,
+  minTranscriptChars = 0, description = '', run,
+}) {
+  if (!id) throw new AnalyzerError('BAD_ANALYZER', 'analyzer.id required');
+  if (typeof run !== 'function') throw new AnalyzerError('BAD_ANALYZER', `analyzer '${id}': run required`);
+  if (!CADENCES.includes(cadence)) throw new AnalyzerError('BAD_ANALYZER', `analyzer '${id}': unknown cadence '${cadence}'`);
+  if (cadence === 'periodic' && !(everyMs > 0)) {
+    // A periodic analyzer with no interval would either never run or run every tick, and
+    // both look like a bug in the analyzer rather than in its declaration.
+    throw new AnalyzerError('BAD_ANALYZER', `analyzer '${id}': periodic cadence needs everyMs`);
+  }
+  return Object.freeze({ id, label: label || id, produces, cadence, everyMs, minTranscriptChars, description, run });
+}
+
+export function createAnalyzerRegistry() {
+  const analyzers = [];
+  return {
+    add(a) {
+      analyzers.push(a);
+      return () => { const i = analyzers.indexOf(a); if (i >= 0) analyzers.splice(i, 1); };
+    },
+    list: () => [...analyzers],
+    get: (id) => analyzers.find((a) => a.id === id) || null,
+
+    /**
+     * Which analyzers are due right now.
+     *
+     * `lastRunAt` is passed in rather than held here: the registry is a declaration, and a
+     * registry that remembered when things ran would be a second place for that truth to
+     * live — beside the meeting record that already has to store it.
+     */
+    due({ now, cadence = 'periodic', lastRunAt = {}, transcriptChars = 0, admit = null } = {}) {
+      return analyzers.filter((a) => {
+        if (a.cadence !== cadence) return false;
+        if (admit && !admit(a)) return false;
+        // Below the threshold there is nothing worth spending a model call on — an empty
+        // transcript summarised is a paragraph of apology.
+        if (transcriptChars < a.minTranscriptChars) return false;
+        if (a.cadence !== 'periodic') return true;
+        const last = lastRunAt[a.id] || 0;
+        return !last || (now - last) >= a.everyMs;
+      });
+    },
+  };
+}