@chatpanel/events 0.2.0

package/store.js

@@ -0,0 +1,171 @@
+// The log store and the blob store.
+//
+// PERSISTENCE IS A HOST ADAPTER. The spine is host-independent, so the *semantics* live
+// here and each host supplies the storage underneath: IndexedDB in the extension,
+// SQLite on a gateway or daemon, a capped ring buffer colocated. One in-memory adapter
+// ships here because tests, colocated hosts and the replay harness all want it.
+//
+// TWO STORES, DELIBERATELY SEPARATE.
+//   • the LOG holds events — small, uniform, append-only, ~300-500 B each;
+//   • the BLOB store holds content, addressed by hash and deduped, so the same note
+//     excerpt attached across a hundred turns costs one copy.
+// Keeping them apart is what makes crypto-shredding work: drop a blob and the event
+// skeleton, causality chain and audit trail all survive.
+//
+// APPEND IS IDEMPOTENT ON EVENT ID. Replicating the log to a warm tier can retry
+// safely — the log-level counterpart of the idempotency keys capabilities carry.
+
+import { validateEvent, EventError } from './event.js';
+import { linearize } from './order.js';
+
+/**
+ * Minimal adapter contract a host implements.
+ *   get(key) -> value | undefined      put(key, value)      delete(key)
+ *   keys(prefix?) -> string[]          size() -> bytes (approximate)
+ */
+export function createMemoryAdapter() {
+  const map = new Map();
+  return {
+    get: (k) => map.get(k),
+    put: (k, v) => { map.set(k, v); },
+    delete: (k) => map.delete(k),
+    keys: (prefix = '') => [...map.keys()].filter((k) => k.startsWith(prefix)).sort(),
+    size: () => {
+      let n = 0;
+      for (const [k, v] of map) n += k.length + (typeof v === 'string' ? v.length : JSON.stringify(v).length);
+      return n;
+    },
+    clear: () => map.clear(),
+  };
+}
+
+const EV = 'e/';   // event by id
+const SEQ = 's/';  // host -> highest seq seen
+
+/** The append-only event log over a host adapter. */
+export function createLogStore(adapter = createMemoryAdapter()) {
+  const store = {
+    /**
+     * Append a validated event. Idempotent on `id`: re-appending the same event is a
+     * no-op returning `{ appended: false }`, so replication retries are safe.
+     * Rejects a seq that moves backwards for a host — that is a corrupt writer, not a gap.
+     */
+    append(event) {
+      validateEvent(event);
+      if (adapter.get(EV + event.id) !== undefined) return { appended: false, event };
+      const highest = adapter.get(SEQ + event.host);
+      if (highest !== undefined && event.seq <= highest) {
+        throw new EventError('SEQ', `seq ${event.seq} <= ${highest} already seen for host ${event.host}`, event.host);
+      }
+      adapter.put(EV + event.id, event);
+      adapter.put(SEQ + event.host, event.seq);
+      return { appended: true, event };
+    },
+
+    appendAll(events) {
+      const res = events.map((e) => store.append(e));
+      return { appended: res.filter((r) => r.appended).length, total: events.length };
+    },
+
+    get: (id) => adapter.get(EV + id),
+    has: (id) => adapter.get(EV + id) !== undefined,
+
+    all: () => adapter.keys(EV).map((k) => adapter.get(k)),
+
+    /** Every event in replay order — the only ordering anything should read. */
+    ordered: () => linearize(store.all()),
+
+    byType: (type) => store.all().filter((e) => e.type === type),
+
+    /** One host's slice, for replication cursors. */
+    range({ host, fromSeq = 0, toSeq = Infinity } = {}) {
+      return store.all()
+        .filter((e) => (!host || e.host === host) && e.seq >= fromSeq && e.seq <= toSeq)
+        .sort((a, b) => a.seq - b.seq);
+    },
+
+    /** Highest seq per host — the cursor a replica sends to ask for what it lacks. */
+    cursor() {
+      const out = {};
+      for (const k of adapter.keys(SEQ)) out[k.slice(SEQ.length)] = adapter.get(k);
+      return out;
+    },
+
+    /** Events a replica with this cursor has not seen. */
+    since(cursor = {}) {
+      return store.all()
+        .filter((e) => e.seq > (cursor[e.host] ?? -1))
+        .sort((a, b) => (a.host === b.host ? a.seq - b.seq : a.host < b.host ? -1 : 1));
+    },
+
+    /** Walk the causality chain backwards from an event. */
+    ancestry(id, seen = new Set()) {
+      const e = store.get(id);
+      if (!e || seen.has(id)) return [];
+      seen.add(id);
+      return [e, ...e.causes.flatMap((c) => store.ancestry(c, seen))];
+    },
+
+    stats: () => ({ events: adapter.keys(EV).length, bytes: adapter.size() }),
+  };
+  return store;
+}
+
+/**
+ * Content-addressed blob store. Dedupes by hash, so attaching the same excerpt a
+ * hundred times costs one copy — the rule that keeps the log from growing linearly in
+ * content.
+ *
+ * `digest` is injected: no ambient dependency on a crypto implementation, and tests stay
+ * deterministic. Defaults to SHA-256 via WebCrypto, present in browsers and Node >= 18.
+ */
+export function createBlobStore(adapter = createMemoryAdapter(), { digest = sha256Hex } = {}) {
+  const B = 'b/';
+  const store = {
+    async put(content) {
+      const hash = await digest(content);
+      const key = B + hash;
+      if (adapter.get(key) === undefined) adapter.put(key, content);
+      return hash;
+    },
+    get: (hash) => adapter.get(B + hash),
+    has: (hash) => adapter.get(B + hash) !== undefined,
+
+    /**
+     * CRYPTO-SHRED. Drops the payload and leaves a tombstone, so "delete this meeting"
+     * can be honoured against an append-only log: the content is unrecoverable while
+     * every event that referenced it, and the causality chain, stay intact. Replay then
+     * reports verified-but-unavailable rather than substituting current content.
+     */
+    shred(hash) {
+      if (adapter.get(B + hash) === undefined) return false;
+      adapter.delete(B + hash);
+      adapter.put(`t/${hash}`, { shredded: true });
+      return true;
+    },
+    isShredded: (hash) => adapter.get(`t/${hash}`) !== undefined,
+
+    /** Resolve a Ref the way replay must: exact, shredded, or absent. */
+    lookup(ref) {
+      const value = store.get(ref.hash);
+      if (value === undefined) return null;
+      return { hash: ref.hash, value };
+    },
+
+    stats: () => ({
+      blobs: adapter.keys(B).length,
+      shredded: adapter.keys('t/').length,
+      bytes: adapter.size(),
+    }),
+  };
+  return store;
+}
+
+// Global WebCrypto: present in every browser and in Node from 19 onward. Callers on an
+// older or unusual runtime inject their own `digest` rather than the package reaching
+// for `node:crypto`, which would put a Node import in a browser-first module.
+async function sha256Hex(content) {
+  const bytes = typeof content === 'string' ? new TextEncoder().encode(content) : content;
+  const buf = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+  return `sha256:${[...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, '0')).join('')}`;
+}

package/tool-groups.js

@@ -0,0 +1,81 @@
+// Tool groups as plugins — "here is a set of capabilities, and when to offer them".
+//
+// The extension assembles a turn's toolset from three hardcoded blocks: the user's own
+// data, their MCP servers, and the page. Each block is the same shape — decide whether it
+// applies, build a provider, collapse it behind a dispatcher — written out three times, so
+// a fourth means editing a shared function and no other client can contribute one at all.
+//
+// The failure this prevents is not hypothetical. A duplicated search-engine list in two
+// files produced a retired engine that kept reappearing in settings; two implementations of
+// one decision disagree eventually. A registry makes that unrepresentable: there is one
+// list, and it is the registrations.
+//
+// A group DECIDES and BUILDS; it does not know about the others. Ordering is explicit
+// priority rather than call order, because "which tools does the model see first" should be
+// a stated decision and not an accident of where someone added a line.
+
+export class ToolGroupError extends Error {
+  constructor(code, message) { super(message); this.name = 'ToolGroupError'; this.code = code; }
+}
+
+/**
+ * @param applies (ctx) => boolean — cheap, synchronous, no side effects. Kept separate from
+ *        `build` so "should this be offered" can be answered without paying to construct
+ *        it: MCP construction connects to servers, and asking that question should not.
+ * @param build   async (ctx) => provider | null. Returning null is normal (nothing
+ *        configured), not an error.
+ */
+export function defineToolGroup({ id, label, applies, build, priority = 0 }) {
+  if (!id) throw new ToolGroupError('BAD_GROUP', 'group.id required');
+  if (typeof build !== 'function') throw new ToolGroupError('BAD_GROUP', `group '${id}': build required`);
+  return Object.freeze({
+    id,
+    label: label || id,
+    priority,
+    applies: typeof applies === 'function' ? applies : () => true,
+    build,
+  });
+}
+
+export function createToolGroupRegistry() {
+  const groups = [];
+  return {
+    add(group) {
+      groups.push(group);
+      return () => { const i = groups.indexOf(group); if (i >= 0) groups.splice(i, 1); };
+    },
+
+    list: () => [...groups].sort((a, b) => b.priority - a.priority),
+
+    /**
+     * Build every group that applies, in priority order.
+     *
+     * Groups are built CONCURRENTLY because one of them connects to remote servers and
+     * serialising would add its latency to every turn — but the RESULT is re-sorted by
+     * priority, so the order the model sees never depends on which finished first.
+     *
+     * A group that throws is dropped with a report, not propagated: a broken MCP server
+     * must not cost the user their history tools. Same isolation rule as the source
+     * registry and the adapter registry, for the same reason.
+     */
+    async build(ctx, { onError = () => {}, admit = null } = {}) {
+      const eligible = this.list().filter((g) => {
+        // Admission is checked BEFORE `applies`, and both before `build`. A group the user
+        // switched off must not do its work and be discarded afterwards — for MCP that work
+        // is connecting to servers, which is what once made a first turn wait 45 seconds.
+        if (admit && !admit(g)) return false;
+        try { return !!g.applies(ctx); } catch (e) { onError(g.id, e); return false; }
+      });
+      const built = await Promise.all(eligible.map(async (g) => {
+        try { return { id: g.id, priority: g.priority, provider: await g.build(ctx) }; } catch (e) {
+          onError(g.id, e);
+          return null;
+        }
+      }));
+      return built
+        .filter((b) => b && b.provider)
+        .sort((a, b) => b.priority - a.priority)
+        .map((b) => ({ id: b.id, provider: b.provider }));
+    },
+  };
+}

package/tool-need.js

@@ -0,0 +1,96 @@
+// Does this turn need tools AT ALL — asked before any of them are built.
+//
+// Every turn was armed with the same equipment regardless of what was said. "hi" arrived at
+// the model carrying a history dispatcher, an MCP dispatcher and ~1,200 tokens of rulebook
+// explaining how to use them, and that cost more than the prompt itself. That is not only
+// waste, it CHANGES THE ANSWER: a turn that carries tools requires a model that can call
+// them (see requirementsFor), so a greeting eliminated every model without the tools
+// capability and then paid a CLI agent two seconds to spawn a process in order to wave back.
+//
+// Equipment is not demand. The question "what does this turn need" has to be asked of the
+// MESSAGE, before the toolset exists — which is what the router already does for model
+// choice, from the same signals, for free.
+//
+// THE ERROR BIAS IS THE OPPOSITE OF THE ROUTER'S, which is why this is not simply
+// `signals.smalltalk`. Mis-routing a turn produces a worse answer; withholding the history
+// tools from "what did we decide in the standup" produces "I cannot access your meetings" —
+// wrong, and the exact thing the tool system prompt exists to prevent. So this does not try
+// to detect which turns need tools. It recognises the narrow class of turns that provably
+// cannot — pleasantries, and nothing else — and arms everything otherwise.
+//
+// Recognised by VOCABULARY rather than by absence: every word must be a conversational
+// move. An unknown word, a typo, a name, a question — anything at all — falls through to
+// "arm the tools", which is the safe direction. `smalltalk` still has to agree, so the two
+// definitions of trivial cannot drift apart.
+//
+// Class R: no model call, no network, no I/O. Reading a string.
+
+import { signalsFrom } from './router.js';
+
+// Greetings, thanks, acknowledgements, farewells — and the filler that attaches to them
+// ("hey there", "ok got it", "thanks so much"). Deliberately small: every addition widens
+// the set of turns that get no tools, so a word earns its place by being unable to appear
+// in a request.
+const PLEASANTRY = new Set([
+  'hi', 'hii', 'hiya', 'hey', 'heya', 'hello', 'helo', 'yo', 'sup', 'howdy', 'greetings',
+  'good', 'morning', 'afternoon', 'evening', 'night', 'day',
+  'thanks', 'thank', 'thankyou', 'thx', 'tnx', 'ty', 'cheers', 'appreciated',
+  'ok', 'okay', 'k', 'kk', 'got', 'sounds', 'perfect', 'great', 'cool', 'nice', 'awesome',
+  'lol', 'haha', 'hah', 'hehe', 'nvm', 'yep', 'yeah', 'yes', 'no', 'nope', 'sure',
+  'bye', 'goodbye', 'later', 'ya', 'cya', 'ciao', 'welcome', 'worries', 'problem', 'np',
+  'please', 'there', 'again', 'all', 'everyone', 'team', 'friend', 'mate', 'buddy',
+  'you', 'u', 'so', 'much', 'very', 'well', 'and', 'a', 'the',
+]);
+
+// At most a short phrase. A long message built entirely from these words is not a greeting,
+// it is something this rule does not understand — and not understanding means arm the tools.
+const MAX_PLEASANTRY_WORDS = 6;
+
+function isPleasantry(text) {
+  // Strip emoji, punctuation and digits: "hi!! 👋" is "hi". Anything left must be a word in
+  // the vocabulary.
+  const words = String(text || '')
+    .toLowerCase()
+    .replace(/[^\p{L}\s']/gu, ' ')
+    .split(/\s+/)
+    .filter(Boolean);
+  if (!words.length || words.length > MAX_PLEASANTRY_WORDS) return false;
+  return words.every((w) => PLEASANTRY.has(w));
+}
+
+/**
+ * @param request     { text } | { messages } — the turn, as the router already reads it.
+ * @param signals     precomputed signalsFrom(request), when the caller already has them.
+ * @param attachments anything the user attached; presence alone means there is material.
+ * @param explicit    the user or a skill ASKED for tools this turn (MCP mode 'on', the
+ *                    /history hint, a running skill). Never second-guessed.
+ * @returns { tools, why } — `tools: false` means build nothing at all this turn.
+ */
+export function toolNeedFor({ request = null, signals = null, attachments = [], explicit = false } = {}) {
+  if (explicit) return { tools: true, why: 'the turn asked for tools' };
+  // MATERIAL THE USER HANDED OVER — not the tab that happens to be open.
+  //
+  // The side panel auto-attaches the current page to every send, so "hi" on a search results
+  // page arrived carrying an attachment and armed the full toolset: three tools, ~2,300
+  // tokens and a page read, to say hello back. The open tab is METADATA about where the user
+  // is, not content they asked about; treating the two the same made the ambient page defeat
+  // this rule on every turn where it mattered.
+  //
+  // `auto` marks it. A page the user genuinely attached has no such mark and still counts —
+  // and a message that ASKS about the page ("summarise this") is not a pleasantry anyway, so
+  // it arms tools by the ordinary path rather than by what happens to be attached.
+  if ((attachments || []).some((a) => a && !a.auto)) {
+    return { tools: true, why: 'the turn carries an attachment' };
+  }
+
+  const text = String(request?.text ?? (request?.messages || []).map((m) => m?.content || '').join('\n'));
+  if (!isPleasantry(text)) return { tools: true, why: 'the request may need something fetched' };
+
+  // And the router has to agree it is trivial. Two definitions of "asks for nothing" that
+  // can disagree is the duplication this codebase keeps removing; requiring both means the
+  // stricter one always wins.
+  const sig = signals || signalsFrom(request || {});
+  if (!sig.smalltalk) return { tools: true, why: 'the request may need something fetched' };
+
+  return { tools: false, why: 'a greeting — nothing to look up' };
+}