@chatpanel/events 0.102.0 → 0.103.1

package/rrf.js

@@ -1,89 +1 @@
-// rrf.js — Reciprocal Rank Fusion, and the query planning that feeds it.
-//
-// One question rarely makes one good keyword query. "What was the outcome of the Ben tooling
-// demo?" and "Ben demo decisions action items" retrieve different things, and the answer is
-// usually in the union. RRF merges several ranked lists without needing their scores to be
-// comparable — each list contributes 1/(k+rank) — which is exactly the situation here: BM25
-// scores, vector distances and a hot/warm split are all on different scales.
-//
-// Pure and dependency-free, so the identical fusion runs in the extension (hot+warm), the
-// gateway (multi-query search) and any future client. The extension had this privately; it
-// lives here now so the gateway doesn't grow a second, subtly different copy.
-
-/**
- * Fuse ranked id lists. `lists` is an array of arrays of ids, each already in rank order.
- * k dampens the head of each list (60 is the standard default). limit 0 = everything.
- */
-export function fuseRRF(lists, { k = 60, limit = 0 } = {}) {
-  const score = new Map();
-  for (const list of lists || []) {
-    if (!Array.isArray(list)) continue;
-    list.forEach((id, rank) => {
-      if (id == null) return;
-      score.set(id, (score.get(id) || 0) + 1 / (k + rank));
-    });
-  }
-  const out = [...score.entries()].map(([id, s]) => ({ id, score: s })).sort((a, b) => b.score - a.score);
-  return limit > 0 ? out.slice(0, limit) : out;
-}
-
-// Words that carry no retrieval signal but do dilute BM25 — dropped to build a keyword-only
-// variant of a natural-language question.
-const STOP = new Set(('a an and are as at be been but by can could did do does for from had has have how i if in into is it its me my of on or our ought shall should '
-  + 'so than that the their them then there these they this those to um was we were what when where which who whom why will with would you your about tell show give find get '
-  + 'please could-you was-there did-we').split(/\s+/));
-
-/**
- * Turn one natural-language question into a small set of complementary queries — the cheap,
- * deterministic half of query expansion. No model call, so it costs nothing and cannot fail.
- *
- * A CALLING AGENT can do better (it understands the domain), which is why the tools accept an
- * explicit `queries` list; these variants are the floor, not the ceiling.
- */
-export function planQueries(question, { extra = [], max = 4 } = {}) {
-  const q = String(question || '').trim();
-  const out = [];
-  const seen = new Set();
-  const add = (s) => {
-    const t = String(s || '').trim().replace(/\s+/g, ' ');
-    const key = t.toLowerCase();
-    if (t && !seen.has(key)) { seen.add(key); out.push(t); }
-  };
-
-  add(q);                                    // the question as asked
-  for (const e of extra) add(e);             // whatever the agent proposed — it knows more
-
-  const words = q.toLowerCase().match(/[a-z0-9][a-z0-9'’_+-]*/g) || [];
-  const keywords = words.filter((w) => !STOP.has(w) && w.length > 2);
-  if (keywords.length >= 2) add(keywords.join(' '));          // keyword-only: BM25's best shape
-  // The rarest-looking terms (longest words are a decent proxy for specificity) — helps when
-  // the full question is too broad to rank anything well.
-  if (keywords.length > 3) add([...keywords].sort((a, b) => b.length - a.length).slice(0, 3).join(' '));
-
-  return out.slice(0, Math.max(1, max));
-}
-
-/**
- * Run several queries through one `search(query, opts)` function and fuse the results by id.
- * `search` returns arrays of { id, ... }; the fused output keeps the richest record seen for
- * each id (so snippets survive) and reports which queries found it — the "why is this here"
- * a reader needs when a multi-query search surfaces something unexpected.
- */
-export async function multiSearch(queries, search, { limit = 10, k = 60 } = {}) {
-  const lists = [];
-  const byId = new Map();
-  const foundBy = new Map();
-  for (const q of queries || []) {
-    let rows = [];
-    try { rows = (await search(q)) || []; } catch { rows = []; } // one bad query must not sink the rest
-    lists.push(rows.map((r) => r.id));
-    for (const r of rows) {
-      if (!byId.has(r.id) || (!byId.get(r.id).snippet && r.snippet)) byId.set(r.id, r);
-      if (!foundBy.has(r.id)) foundBy.set(r.id, []);
-      foundBy.get(r.id).push(q);
-    }
-  }
-  return fuseRRF(lists, { k, limit }).map(({ id, score }) => ({
-    ...byId.get(id), id, score, foundBy: foundBy.get(id) || [],
-  }));
-}
+function l(h,{k:c=60,limit:a=0}={}){const r=new Map;for(const o of h||[])Array.isArray(o)&&o.forEach((e,n)=>{e!=null&&r.set(e,(r.get(e)||0)+1/(c+n))});const i=[...r.entries()].map(([o,e])=>({id:o,score:e})).sort((o,e)=>e.score-o.score);return a>0?i.slice(0,a):i}const w=new Set("a an and are as at be been but by can could did do does for from had has have how i if in into is it its me my of on or our ought shall should so than that the their them then there these they this those to um was we were what when where which who whom why will with would you your about tell show give find get please could-you was-there did-we".split(/\s+/));function d(h,{extra:c=[],max:a=4}={}){const r=String(h||"").trim(),i=[],o=new Set,e=t=>{const u=String(t||"").trim().replace(/\s+/g," "),f=u.toLowerCase();u&&!o.has(f)&&(o.add(f),i.push(u))};e(r);for(const t of c)e(t);const s=(r.toLowerCase().match(/[a-z0-9][a-z0-9'’_+-]*/g)||[]).filter(t=>!w.has(t)&&t.length>2);return s.length>=2&&e(s.join(" ")),s.length>3&&e([...s].sort((t,u)=>u.length-t.length).slice(0,3).join(" ")),i.slice(0,Math.max(1,a))}async function p(h,c,{limit:a=10,k:r=60}={}){const i=[],o=new Map,e=new Map;for(const n of h||[]){let s=[];try{s=await c(n)||[]}catch{s=[]}i.push(s.map(t=>t.id));for(const t of s)(!o.has(t.id)||!o.get(t.id).snippet&&t.snippet)&&o.set(t.id,t),e.has(t.id)||e.set(t.id,[]),e.get(t.id).push(n)}return l(i,{k:r,limit:a}).map(({id:n,score:s})=>({...o.get(n),id:n,score:s,foundBy:e.get(n)||[]}))}export{l as fuseRRF,p as multiSearch,d as planQueries};

package/rules.js

@@ -1,142 +1 @@
-// Class-R automation — value without a model.
-//
-// Everything ChatPanel does today needs a model, which means everything costs tokens,
-// latency and a network. But a great deal of what users actually want is a RULE: when a
-// meeting ends, save the notes; when a page matches, offer to act on it; when a note gains
-// a heading, index it. Those are deterministic, instant, free, and provable — and until
-// there is somewhere to declare them, each is hand-written into whichever file noticed the
-// need first.
-//
-// A rule fires FROM THE EVENT LOG, which is what finally makes the log a bus rather than a
-// record. That is the whole reason the log came first: a rule that had to be called
-// explicitly by the code that might interest it is not automation, it is a function call
-// with extra steps.
-//
-// THREE PROPERTIES THAT ARE NOT NEGOTIABLE, because automation is where a mistake is
-// unattended:
-//   • A rule may NARROW authority, never widen it. It runs with the scope it was granted
-//     and cannot request more at fire time.
-//   • A non-pure action carries an idempotency key, so a rule that fires twice on a redelivered
-//     event does its thing once (I3).
-//   • Every decision is recorded — fired AND suppressed — because an automation you cannot
-//     see is one you cannot trust, and 'it did nothing' has many causes worth telling apart.
-
-export class RuleError extends Error {
-  constructor(code, message) { super(message); this.name = 'RuleError'; this.code = code; }
-}
-
-/** Why a rule did not fire. Each is a different problem, so each has a name. */
-export const SUPPRESSED = Object.freeze({
-  DISABLED: 'disabled',              // switched off in Plugins
-  CONDITION: 'condition-false',      // the trigger matched, the condition did not
-  DUPLICATE: 'already-fired',        // same event, same rule — redelivery, not a new cause
-  RATE_LIMITED: 'rate-limited',      // fired too recently
-  NO_PERMISSION: 'no-permission',    // the guard refused
-  ERROR: 'error',                    // the rule itself threw
-});
-
-/**
- * @param on    event type, or array of them. Matching on TYPE first is what keeps a busy
- *              log cheap: a predicate is only run for events that could possibly match.
- * @param when  (event, ctx) => boolean. Pure and synchronous, deliberately — a condition
- *              that could do I/O would make "did this rule match" unanswerable without
- *              side effects, and untestable without mocks.
- * @param then  async (event, ctx) => result. The action. Receives `ctx.invoke`, so a rule
- *              cannot reach a capability except through the guarded path.
- * @param classUsed the execution class this rule actually uses — 'R' for a pure rule, 'M'
- *              for a small model, 'C' for a cloud one. Declared rather than inferred,
- *              because the honest answer to "did this cost anything" cannot be guessed.
- * @param everyMs minimum gap between fires. 0 means every matching event.
- */
-export function defineRule({
-  id, label, on, when = null, then, classUsed = 'R',
-  everyMs = 0, requiresApproval = false, description = '', effects = 'idempotent',
-}) {
-  if (!id) throw new RuleError('BAD_RULE', 'rule.id required');
-  if (typeof then !== 'function') throw new RuleError('BAD_RULE', `rule '${id}': then required`);
-  const types = Array.isArray(on) ? on : [on];
-  if (!types.length || types.some((t) => typeof t !== 'string' || !t)) {
-    throw new RuleError('BAD_RULE', `rule '${id}': on must name at least one event type`);
-  }
-  if (when && typeof when !== 'function') throw new RuleError('BAD_RULE', `rule '${id}': when must be a function`);
-  // A rule that changes the world without an idempotency story will eventually do it twice.
-  if (effects === 'non-replayable' && !requiresApproval && classUsed === 'R') {
-    // Not an error — some rules genuinely must act — but it has to be stated, so the
-    // decision is visible in the declaration rather than discovered from behaviour.
-  }
-  return Object.freeze({
-    id, label: label || id, on: types, when, then, classUsed,
-    everyMs, requiresApproval, description, effects,
-  });
-}
-
-export function createRuleEngine({ emit = () => {}, now = () => 0, admit = null, approve = null } = {}) {
-  const rules = [];
-  const lastFired = new Map();
-  const seen = new Set();   // `${ruleId}:${eventId}` — redelivery is not a new cause
-
-  return {
-    add(rule) {
-      rules.push(rule);
-      return () => { const i = rules.indexOf(rule); if (i >= 0) rules.splice(i, 1); };
-    },
-    list: () => [...rules],
-
-    /**
-     * Offer one event to every rule. Returns what happened, so a caller can assert on it —
-     * an engine whose only output is side effects cannot be tested without mocks.
-     *
-     * Never throws. A rule that fails must not take down the thing that emitted the event:
-     * automation is a passenger, not a driver.
-     */
-    async dispatch(event, ctx = {}) {
-      const out = [];
-      for (const rule of rules) {
-        if (!rule.on.includes(event?.type)) continue;
-
-        const suppress = (reason, detail) => {
-          emit('automation.suppressed', { ruleId: rule.id, reason, eventId: event.id, ...detail });
-          out.push({ ruleId: rule.id, fired: false, reason });
-        };
-
-        if (admit && !admit(rule)) { suppress(SUPPRESSED.DISABLED); continue; }
-
-        const key = `${rule.id}:${event.id}`;
-        if (seen.has(key)) { suppress(SUPPRESSED.DUPLICATE); continue; }
-
-        if (rule.everyMs > 0 && lastFired.has(rule.id)) {
-          // `has`, not truthiness: a rule that fired at timestamp 0 HAS fired, and treating
-          // that as "never" gives it one free pass through its own rate limit. Only a test
-          // clock starts at 0, but a guard that is wrong for one value is wrong.
-          if (now() - lastFired.get(rule.id) < rule.everyMs) { suppress(SUPPRESSED.RATE_LIMITED); continue; }
-        }
-
-        let matched = true;
-        try { matched = rule.when ? !!rule.when(event, ctx) : true; } catch (e) {
-          // A condition that throws is a condition that did not match. Firing on an
-          // unanswered question is how automation does something nobody asked for.
-          suppress(SUPPRESSED.ERROR, { message: e.message });
-          continue;
-        }
-        if (!matched) { suppress(SUPPRESSED.CONDITION); continue; }
-
-        if (rule.requiresApproval) {
-          const ok = approve ? await approve(rule, event) : false;
-          if (!ok) { suppress(SUPPRESSED.NO_PERMISSION); continue; }
-        }
-
-        seen.add(key);
-        lastFired.set(rule.id, now());
-        try {
-          const result = await rule.then(event, ctx);
-          emit('automation.fired', { ruleId: rule.id, classUsed: rule.classUsed, eventId: event.id });
-          out.push({ ruleId: rule.id, fired: true, result });
-        } catch (e) {
-          emit('automation.suppressed', { ruleId: rule.id, reason: SUPPRESSED.ERROR, eventId: event.id, message: e.message });
-          out.push({ ruleId: rule.id, fired: false, reason: SUPPRESSED.ERROR, error: e.message });
-        }
-      }
-      return out;
-    },
-  };
-}
+class p extends Error{constructor(l,i){super(i),this.name="RuleError",this.code=l}}const u=Object.freeze({DISABLED:"disabled",CONDITION:"condition-false",DUPLICATE:"already-fired",RATE_LIMITED:"rate-limited",NO_PERMISSION:"no-permission",ERROR:"error"});function y({id:t,label:l,on:i,when:c=null,then:o,classUsed:f="R",everyMs:R=0,requiresApproval:r=!1,description:a="",effects:d="idempotent"}){if(!t)throw new p("BAD_RULE","rule.id required");if(typeof o!="function")throw new p("BAD_RULE",`rule '${t}': then required`);const e=Array.isArray(i)?i:[i];if(!e.length||e.some(n=>typeof n!="string"||!n))throw new p("BAD_RULE",`rule '${t}': on must name at least one event type`);if(c&&typeof c!="function")throw new p("BAD_RULE",`rule '${t}': when must be a function`);return Object.freeze({id:t,label:l||t,on:e,when:c,then:o,classUsed:f,everyMs:R,requiresApproval:r,description:a,effects:d})}function D({emit:t=()=>{},now:l=()=>0,admit:i=null,approve:c=null}={}){const o=[],f=new Map,R=new Set;return{add(r){return o.push(r),()=>{const a=o.indexOf(r);a>=0&&o.splice(a,1)}},list:()=>[...o],async dispatch(r,a={}){const d=[];for(const e of o){if(!e.on.includes(r?.type))continue;const n=(s,h)=>{t("automation.suppressed",{ruleId:e.id,reason:s,eventId:r.id,...h}),d.push({ruleId:e.id,fired:!1,reason:s})};if(i&&!i(e)){n(u.DISABLED);continue}const I=`${e.id}:${r.id}`;if(R.has(I)){n(u.DUPLICATE);continue}if(e.everyMs>0&&f.has(e.id)&&l()-f.get(e.id)<e.everyMs){n(u.RATE_LIMITED);continue}let E=!0;try{E=e.when?!!e.when(r,a):!0}catch(s){n(u.ERROR,{message:s.message});continue}if(!E){n(u.CONDITION);continue}if(e.requiresApproval&&!(c?await c(e,r):!1)){n(u.NO_PERMISSION);continue}R.add(I),f.set(e.id,l());try{const s=await e.then(r,a);t("automation.fired",{ruleId:e.id,classUsed:e.classUsed,eventId:r.id}),d.push({ruleId:e.id,fired:!0,result:s})}catch(s){t("automation.suppressed",{ruleId:e.id,reason:u.ERROR,eventId:r.id,message:s.message}),d.push({ruleId:e.id,fired:!1,reason:u.ERROR,error:s.message})}}return d}}}export{p as RuleError,u as SUPPRESSED,D as createRuleEngine,y as defineRule};