@chatpanel/events 0.2.0

package/rules.js

@@ -0,0 +1,142 @@
+// 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;
+    },
+  };
+}

package/search-engines.js

@@ -0,0 +1,81 @@
+// Search engines as declarations, not as a literal in two files.
+//
+// This one is not speculative. The engine list existed as an array in the search runtime
+// AND as a copy in the settings page, and when a broken engine was removed from one it kept
+// appearing in the other. Two implementations of one list disagree eventually; the only
+// reliable fix is for there to be one list.
+//
+// It is also where the plugin model pays off soonest for a USER: an engine is a name, a URL
+// template, and a way to read the result. That is a thing someone could contribute without
+// touching any code we wrote.
+
+export class SearchEngineError extends Error {
+  constructor(code, message) { super(message); this.name = 'SearchEngineError'; this.code = code; }
+}
+
+export const ENGINE_KINDS = Object.freeze(['serp', 'api']);
+
+/**
+ * @param kind    'serp' — an HTML results page to read; 'api' — a service that answers
+ *                directly. The distinction is not cosmetic: a SERP can be blocked and
+ *                needs a fallback, an API can need a key and must not run without one.
+ * @param needsKey the engine sends queries to a third party that requires credentials.
+ *                Engines that need a key stay OFF until one exists, because a default that
+ *                sends the user's queries somewhere they never chose is not a default.
+ */
+export function defineSearchEngine({ id, name, url, kind = 'serp', enabled = false, needsKey = false, retired = false }) {
+  if (!id) throw new SearchEngineError('BAD_ENGINE', 'engine.id required');
+  if (!ENGINE_KINDS.includes(kind)) throw new SearchEngineError('BAD_ENGINE', `engine '${id}': unknown kind '${kind}'`);
+  if (!retired && !url) throw new SearchEngineError('BAD_ENGINE', `engine '${id}': url required`);
+  return Object.freeze({ id, name: name || id, url, kind, enabled, needsKey, retired });
+}
+
+/**
+ * Reconcile a user's stored list against the declared engines.
+ *
+ * The one function both the runtime and the settings page call, so what search uses and
+ * what settings shows cannot drift — which is the entire bug this replaces.
+ */
+export function reconcileEngines(stored, declared, { hasKey = false } = {}) {
+  const byId = new Map(declared.map((e) => [e.id, e]));
+  const retired = new Set(declared.filter((e) => e.retired).map((e) => e.id));
+
+  let out = (Array.isArray(stored) && stored.length ? stored : declared)
+    .filter((e) => e?.id && !retired.has(e.id))
+    .map((e) => ({ ...(byId.get(e.id) || {}), ...e }));
+
+  // Anything declared but never seen by this user is added, off unless it ships on. A user
+  // who has saved settings once must still receive new engines.
+  for (const d of declared) {
+    if (d.retired || out.some((e) => e.id === d.id)) continue;
+    out.push({ ...d });
+  }
+
+  out = out.map((e) => {
+    const d = byId.get(e.id);
+    if (!d?.needsKey) return e;
+    // "They turned it off" and "it has never been offered" are different states: a key
+    // enables the second, never overrides the first.
+    const known = Array.isArray(stored) && stored.some((s) => s?.id === e.id);
+    const declined = known && stored.find((s) => s.id === e.id)?.enabled === false;
+    return { ...e, enabled: hasKey && !declined };
+  });
+
+  // Never leave the user with nothing usable. Retiring an engine can empty a list that
+  // contained only that engine, and a search feature that silently has no engines is a
+  // worse failure than the one being fixed.
+  if (!out.some((e) => e.enabled !== false && !e.needsKey)) {
+    for (const d of declared) {
+      if (d.retired || d.needsKey) continue;
+      const have = out.find((e) => e.id === d.id);
+      if (have) have.enabled = d.enabled !== false;
+    }
+  }
+  return out;
+}
+
+/** The order to actually try: enabled first (in list order), then the rest as fallbacks. */
+export function attemptOrder(engines) {
+  const live = engines.filter((e) => !e.retired);
+  return [...live.filter((e) => e.enabled !== false), ...live.filter((e) => e.enabled === false)];
+}

package/sources-retrieval.js

@@ -0,0 +1,189 @@
+/**
+ * SOURCES ARE QUERIED, NOT POURED IN.
+ *
+ * Attached context used to be flattened into the first message: every attached tab, in full,
+ * before the model had said anything. So "hi" on a long page paid for the whole page, and
+ * five attached tabs meant five documents in the prompt to answer a question that concerned
+ * one paragraph of one of them.
+ *
+ * The model is instead shown a MANIFEST — what exists, how big it is, where it came from —
+ * and pulls what it needs. Three things follow that are not just savings:
+ *
+ *   - The turn starts small, so a cheap model can handle a greeting on a heavy page.
+ *   - What was read is a fact in the log rather than an assumption about the prompt.
+ *   - Retrieval takes a QUERY, so a large source returns the relevant part instead of its
+ *     first N characters — which is what truncation gives you, and it is rarely the part
+ *     that matters.
+ *
+ * Pure and dependency-free: the extension, the gateway and the bridge all have attached
+ * sources, and three implementations of "what did the model actually read" would drift.
+ */
+
+const CHUNK_SPLIT = /\n{2,}/;
+
+/** ~4 chars per token — the same estimate the dispatcher budget uses. One rough number beats two. */
+export const approxTokens = (s) => Math.ceil(String(s || '').length / 4);
+
+/**
+ * A stable, short id for a source. The model has to type this back, so it is derived from the
+ * title rather than from a random string: `page-2` is recoverable from a manifest a model
+ * half-remembers in a way that `k3f9a1` is not.
+ */
+export function sourceId(source, index = 0) {
+  const base = String(source?.kind || 'src').toLowerCase().replace(/[^a-z0-9]+/g, '') || 'src';
+  return `${base}-${index + 1}`;
+}
+
+/**
+ * Build the manifest the model sees INSTEAD of the content.
+ *
+ * Deliberately includes the size. A model that can see one source is 300 tokens and another
+ * is 40,000 can decide to read the small one whole and query the large one — a decision it
+ * cannot make when both are simply "a document".
+ */
+export function makeSourceStore(sources = []) {
+  const entries = (Array.isArray(sources) ? sources : [sources])
+    .filter((s) => s && (s.text || s.url))
+    .map((s, i) => ({
+      id: s.id || sourceId(s, i),
+      kind: s.kind || 'context',
+      title: s.title || s.url || 'Untitled',
+      url: s.url || '',
+      text: String(s.text || ''),
+      tokens: approxTokens(s.text),
+    }));
+  const byId = new Map(entries.map((e) => [e.id, e]));
+  return {
+    entries,
+    get: (id) => byId.get(String(id || '').trim()) || null,
+    get tokens() { return entries.reduce((a, e) => a + e.tokens, 0); },
+  };
+}
+
+/**
+ * WHERE IT CAME FROM, not the whole address bar.
+ *
+ * A Google results URL carries about a thousand characters of tracking parameters — sca_esv,
+ * gs_lp, sclient — and the manifest printed every one of them, on every turn, in a line whose
+ * job is "here is a source you may read". That is a quarter of a thousand tokens of noise the
+ * model cannot use and must still read past.
+ *
+ * The host and path identify the source; the query string is kept only when it is short
+ * enough to be meaning rather than machinery. An unparseable URL is left exactly as given —
+ * guessing at a string we could not read is how a source becomes unidentifiable.
+ */
+export function shortUrl(url, max = 120) {
+  const raw = String(url || '');
+  if (!raw || raw.length <= max) return raw;
+  try {
+    const u = new URL(raw);
+    const base = `${u.host}${u.pathname}`.replace(/\/$/, '');
+    // A short query is often the whole point of the address ("?q=how+do+tides+work");
+    // a long one is machinery. Keep the first parameter when it fits, drop the rest.
+    const first = [...u.searchParams.entries()][0];
+    const q = first && `${first[0]}=${first[1]}`;
+    const withQ = q && `${base}?${q}`;
+    const out = withQ && withQ.length <= max ? withQ : base;
+    return out.length <= max ? `${out}…` : `${out.slice(0, max)}…`;
+  } catch {
+    return `${raw.slice(0, max)}…`;
+  }
+}
+
+/** One line per source: what it is, where it came from, what it would cost to read. */
+export function manifestText(store) {
+  if (!store?.entries?.length) return '';
+  const lines = store.entries.map((e) => `- ${e.id} — ${e.title}${e.url ? ` (${shortUrl(e.url)})` : ''} · ~${e.tokens} tokens`);
+  return [
+    'Attached sources (NOT included below — read them with the `source` tool):',
+    ...lines,
+  ].join('\n');
+}
+
+/**
+ * Score a chunk against the query by term overlap.
+ *
+ * Deliberately not a model call and not an embedding: retrieval that needs a model to decide
+ * what to retrieve costs a round trip before the real one, and this runs on every source read.
+ * Term overlap is crude and instant, and for "which paragraph of this page mentions X" crude
+ * is usually right.
+ */
+function scoreChunk(chunk, terms) {
+  if (!terms.length) return 0;
+  const hay = chunk.toLowerCase();
+  let score = 0;
+  for (const t of terms) {
+    if (!hay.includes(t)) continue;
+    // Rarer terms are worth more, approximated by length: 'authentication' discriminates,
+    // 'the' does not.
+    score += Math.min(3, t.length / 4);
+  }
+  return score;
+}
+
+const STOP = new Set(['the', 'and', 'for', 'this', 'that', 'with', 'from', 'what', 'when', 'where', 'which', 'have', 'has', 'was', 'are', 'you', 'your', 'can', 'about', 'into', 'does', 'did', 'how', 'why', 'all', 'any', 'its']);
+
+export function queryTerms(query) {
+  return String(query || '')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length > 2 && !STOP.has(t));
+}
+
+/**
+ * Read a source, optionally narrowed by a query.
+ *
+ * Returns `{ id, title, url, text, truncated, of }`. `truncated` is stated rather than
+ * implied: a model handed a silently-cut document answers confidently about the part it was
+ * not given, and there is no way for it — or the person reading the answer — to tell.
+ */
+export function readSource(store, { id, query = '', maxTokens = 2000 } = {}) {
+  const entry = store?.get?.(id);
+  if (!entry) {
+    const known = (store?.entries || []).map((e) => e.id).join(', ');
+    return { error: `No attached source '${id}'.${known ? ` Available: ${known}.` : ' Nothing is attached.'}` };
+  }
+  const budget = Math.max(200, Number(maxTokens) || 2000);
+  if (entry.tokens <= budget) {
+    return { id: entry.id, title: entry.title, url: entry.url, text: entry.text, truncated: false, of: entry.tokens };
+  }
+  const terms = queryTerms(query);
+  const chunks = entry.text.split(CHUNK_SPLIT).filter((c) => c.trim());
+  if (!terms.length) {
+    // No query: the head is the honest default — it is the only part we can justify choosing
+    // without being told what matters.
+    const text = entry.text.slice(0, budget * 4);
+    return { id: entry.id, title: entry.title, url: entry.url, text, truncated: true, of: entry.tokens,
+      note: `Showing the first ~${approxTokens(text)} of ${entry.tokens} tokens. Pass a query to get the relevant parts instead.` };
+  }
+  // Keep the ORIGINAL ORDER of whatever is selected. Ranking by score and presenting in score
+  // order rearranges a document, and a reordered document reads as a different argument.
+  const ranked = chunks
+    .map((c, i) => ({ c, i, s: scoreChunk(c, terms) }))
+    .filter((x) => x.s > 0)
+    .sort((a, b) => b.s - a.s);
+  const picked = [];
+  let used = 0;
+  for (const x of ranked) {
+    const t = approxTokens(x.c);
+    if (used + t > budget) continue;
+    picked.push(x);
+    used += t;
+  }
+  if (!picked.length) {
+    const text = entry.text.slice(0, budget * 4);
+    return { id: entry.id, title: entry.title, url: entry.url, text, truncated: true, of: entry.tokens,
+      note: `Nothing in this source matched '${query}'. Showing the beginning instead.` };
+  }
+  picked.sort((a, b) => a.i - b.i);
+  const gaps = picked.some((x, n) => n > 0 && x.i !== picked[n - 1].i + 1);
+  return {
+    id: entry.id,
+    title: entry.title,
+    url: entry.url,
+    text: picked.map((x) => x.c).join(gaps ? '\n\n[…]\n\n' : '\n\n'),
+    truncated: true,
+    of: entry.tokens,
+    note: `${picked.length} of ${chunks.length} sections, matched on '${query}'.`,
+  };
+}

package/sources.js

@@ -0,0 +1,256 @@
+/**
+ * WHERE THE CONTENT CAME FROM DECIDES HOW FAR IT MAY TRAVEL.
+ *
+ * A model was summarising an internal access-management page and the turn went to a public
+ * inference host, because routing asked what the WORK needed — tools, vision, quality — and
+ * never asked where the material came from. Capability decided; provenance did not exist.
+ *
+ * This module supplies the missing question. It classifies a source URL as internal or not,
+ * and turns that into a REACH CEILING the router already knows how to enforce. Two properties
+ * make it a guard rather than a preference:
+ *
+ *   - It only ever NARROWS. `meetReach` takes the tighter of two ceilings, so no later step,
+ *     plugin or user dial can widen what an internal source already restricted. A guard that
+ *     something downstream can relax is a suggestion.
+ *   - It fails CLOSED. An unparseable URL is treated as internal, because the alternative is
+ *     to send data outward on the strength of a string we could not read.
+ *
+ * Pure and dependency-free: the same rules must hold in the extension, the gateway and the
+ * bridge, or "internal" means three different things and the strictest one is not the one
+ * that runs.
+ */
+
+const REACH_ORDER = ['device', 'trusted', 'any'];
+
+/** The tighter of two reach ceilings. Guards compose by MEET — they can only narrow. */
+export function meetReach(a, b) {
+  const ia = REACH_ORDER.indexOf(a);
+  const ib = REACH_ORDER.indexOf(b);
+  // An unknown value is not a licence to travel further: treat it as the tightest.
+  if (ia < 0) return REACH_ORDER.includes(b) ? b : 'device';
+  if (ib < 0) return a;
+  return REACH_ORDER[Math.min(ia, ib)];
+}
+
+/**
+ * Hosts that are internal by NETWORK TOPOLOGY — the STARTING list, not a floor.
+ *
+ * Deliberately limited to what the address itself proves. A corporate wiki on a public SaaS
+ * domain looks exactly like any other public host from here — that case needs the user's own
+ * patterns, and pretending to detect it would give a false sense of coverage.
+ *
+ * These are seeded into the user's editable list rather than silently prepended to it,
+ * because "internal" is a fact about someone's network, not about ours: a developer testing
+ * against localhost may well want that traffic to reach a cloud model, and a rule they cannot
+ * see is a rule they cannot correct.
+ */
+export const INTERNAL_PATTERN_CATALOG = Object.freeze([
+  { pattern: 'localhost', label: 'This machine, by name' },
+  { pattern: '127.0.0.0/8', label: 'Loopback' },
+  { pattern: '::1', label: 'Loopback (IPv6)' },
+  { pattern: '0.0.0.0/8', label: 'This network' },
+  { pattern: '10.0.0.0/8', label: 'Private network' },
+  { pattern: '172.16.0.0/12', label: 'Private network' },
+  { pattern: '192.168.0.0/16', label: 'Private network (home / office)' },
+  { pattern: '100.64.0.0/10', label: 'Carrier-grade NAT — used by some corporate networks' },
+  { pattern: '169.254.0.0/16', label: 'Link-local — never routes off this segment' },
+  { pattern: 'fe80::/10', label: 'Link-local (IPv6)' },
+  { pattern: 'fc00::/7', label: 'Unique local (IPv6) — the 10.x of IPv6' },
+  { pattern: '*.internal', label: 'Reserved name' },
+  { pattern: '*.intranet', label: 'Reserved name' },
+  { pattern: '*.corp', label: 'Conventional corporate suffix' },
+  { pattern: '*.lan', label: 'Conventional LAN suffix' },
+  { pattern: '*.local', label: 'mDNS / Bonjour' },
+  { pattern: '*.localdomain', label: 'Default suffix on many routers' },
+  { pattern: '*.home', label: 'Home network' },
+  { pattern: '*.home.arpa', label: 'Home network (RFC 8375)' },
+  { pattern: '*.private', label: 'Conventional private suffix' },
+  { pattern: '*.test', label: 'Reserved for testing (RFC 2606)' },
+  { pattern: '*.invalid', label: 'Reserved as never-resolvable' },
+  { pattern: '<intranet>', label: 'Any bare hostname with no dots, e.g. http://wiki/ — includes localhost' },
+]);
+
+/**
+ * The patterns on by default. Derived from the catalog so the list a UI offers and the list
+ * the classifier applies cannot drift — two copies of this would mean a rule someone can see
+ * and not switch off, or switch off and not escape.
+ */
+export const DEFAULT_INTERNAL_PATTERNS = Object.freeze(INTERNAL_PATTERN_CATALOG.map((x) => x.pattern));
+const IPV4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+
+function ipToInt(host) {
+  const m = IPV4.exec(host);
+  if (!m) return null;
+  const parts = m.slice(1).map(Number);
+  if (parts.some((n) => n > 255)) return null;
+  return parts.reduce((acc, n) => acc * 256 + n, 0);
+}
+
+/**
+ * An IPv6 address as its 128 bits, or null if it is not one. Bits rather than a normalised
+ * string because prefix matching (fc00::/7, fe80::/10) is a bit-length comparison — a
+ * textual "starts with" would get /7 wrong, since the boundary falls inside a hex digit.
+ */
+function v6Bits(host) {
+  const h = String(host || '').replace(/^\[|\]$/g, '').toLowerCase();
+  if (!h.includes(':')) return null;
+  const [headRaw, tailRaw, ...rest] = h.split('::');
+  if (rest.length) return null;   // more than one '::' is not a valid address
+  const parse = (part) => (part ? part.split(':').filter((x) => x !== '') : []);
+  let head = parse(headRaw);
+  let tail = tailRaw === undefined ? [] : parse(tailRaw);
+  // A trailing IPv4 form (::ffff:10.0.0.1) — the last group is four octets, not two.
+  const last = (tail.length ? tail : head)[Math.max(0, (tail.length ? tail : head).length - 1)];
+  if (last && last.includes('.')) {
+    const v4 = ipToInt(last);
+    if (v4 == null) return null;
+    const pair = [(v4 >>> 16).toString(16), (v4 & 0xffff).toString(16)];
+    if (tail.length) tail = [...tail.slice(0, -1), ...pair];
+    else head = [...head.slice(0, -1), ...pair];
+  }
+  const missing = 8 - head.length - tail.length;
+  if (tailRaw === undefined ? missing !== 0 : missing < 0) return null;
+  const groups = [...head, ...Array(Math.max(0, missing)).fill('0'), ...tail];
+  if (groups.length !== 8) return null;
+  let bits = '';
+  for (const g of groups) {
+    if (!/^[0-9a-f]{1,4}$/.test(g)) return null;
+    bits += parseInt(g, 16).toString(2).padStart(16, '0');
+  }
+  return bits;
+}
+
+function inCidr(host, cidr) {
+  const [net, bitsRaw] = cidr.split('/');
+  const hostV6 = v6Bits(host);
+  const netV6 = v6Bits(net);
+  if (hostV6 || netV6) {
+    // A v4 host never sits inside a v6 range, and vice versa — comparing them would be a
+    // type confusion that quietly matches or quietly does not.
+    if (!hostV6 || !netV6) return false;
+    const n = Number(bitsRaw);
+    if (!Number.isFinite(n) || n < 0 || n > 128) return false;
+    return hostV6.slice(0, n) === netV6.slice(0, n);
+  }
+  const ip = ipToInt(host);
+  const base = ipToInt(net);
+  if (ip == null || base == null) return false;
+  const bits = Number(bitsRaw);
+  if (!Number.isFinite(bits) || bits < 0 || bits > 32) return false;
+  // Shifting by 32 is a no-op in JS, so /0 is spelled out rather than computed.
+  const mask = bits === 0 ? 0 : (-1 << (32 - bits)) >>> 0;
+  return (ip & mask) >>> 0 === (base & mask) >>> 0;
+}
+
+/**
+ * Does `host` match one pattern? Supported forms, in the order a person would expect:
+ *   `*.example.com`  the domain and every subdomain
+ *   `example.com`    the same — a bare domain covers its subdomains, because someone adding
+ *                    their company domain means the whole company, not one host
+ *   `10.0.0.0/8`     a CIDR range
+ *   `<intranet>`     any single-label host, which can only resolve on a private network
+ */
+export function hostMatches(host, pattern) {
+  const h = String(host || '').toLowerCase().replace(/\.$/, '');
+  const p = String(pattern || '').toLowerCase().trim();
+  if (!h || !p) return false;
+  // A NAME with no dots — not an address. A public IPv6 literal has no dots either, and
+  // sweeping it in here would have quietly pinned every v6 host on the internet as internal.
+  if (p === '<intranet>') return !h.includes('.') && !h.includes(':') && !h.startsWith('[') && !IPV4.test(h);
+  if (p.includes('/')) return inCidr(h, p);
+  // '::1' and '[::1]' and '0:0:0:0:0:0:0:1' are one address written three ways.
+  const pv6 = v6Bits(p);
+  if (pv6) return v6Bits(h) === pv6;
+  const bare = p.startsWith('*.') ? p.slice(2) : p;
+  if (h === bare) return true;
+  if (h.endsWith(`.${bare}`)) return true;
+  // A leading wildcard anywhere else ("*.corp.*") is not supported rather than
+  // half-supported: a pattern that silently matches nothing is worse than one that is
+  // rejected, because it looks like protection.
+  return false;
+}
+
+/**
+ * Classify one source. Returns `{ internal, host, matched }`.
+ *
+ * FAILS CLOSED. A URL we cannot parse counts as internal: we would rather keep a public page
+ * on-device than send an internal one out because a string was malformed. The same applies to
+ * non-http schemes — a `file:` path is local by definition.
+ */
+export function classifySource(url, { patterns = DEFAULT_INTERNAL_PATTERNS } = {}) {
+  const raw = String(url || '').trim();
+  if (!raw) return { internal: false, host: '', matched: null };
+  let host = '';
+  let scheme = '';
+  try {
+    const u = new URL(raw);
+    host = u.hostname;
+    scheme = u.protocol.replace(':', '');
+  } catch {
+    return { internal: true, host: '', matched: 'unparseable' };
+  }
+  if (scheme === 'file') return { internal: true, host, matched: 'file:' };
+  // Extension and browser-internal pages carry no third-party content, and are not sources
+  // anyone means to protect — treating them as internal would pin every turn to a local
+  // model for no reason.
+  if (/^(chrome|edge|about|moz|chrome-extension|data|blob)$/.test(scheme)) {
+    return { internal: false, host, matched: null };
+  }
+  for (const p of patterns) {
+    if (hostMatches(host, p)) return { internal: true, host, matched: p };
+  }
+  return { internal: false, host, matched: null };
+}
+
+/**
+ * Every url written in a piece of text.
+ *
+ * Declared sources are not the only way internal material enters a turn: someone pastes a
+ * link to an internal runbook, or a tool result comes back carrying one. The address is the
+ * evidence, and it is evidence wherever it appears — so the same classifier that reads the
+ * tab reads the body too.
+ *
+ * Explicit schemes only. A bare host like `wiki/page` is indistinguishable from an ordinary
+ * path, and matching it would pin turns on text that mentions no site at all — a guard that
+ * fires on prose gets switched off, which protects nobody.
+ */
+export function extractUrls(text) {
+  const out = [];
+  const re = /\b(?:https?|file):\/\/[^\s<>"'`)\]}]+/gi;
+  for (const m of String(text || '').matchAll(re)) {
+    // Trailing punctuation belongs to the sentence, not to the address.
+    out.push(m[0].replace(/[.,;:!?]+$/, ''));
+  }
+  return out;
+}
+
+/**
+ * Build the reach policy for a turn from everything it draws on.
+ *
+ * ANY internal source pins the WHOLE turn. A turn that mixes an internal page with a public
+ * one is still carrying the internal page, and splitting the difference would send it out.
+ *
+ * `ceiling` is what an internal source narrows to — 'device' for local models only, or
+ * 'trusted' to also allow a workspace gateway the user runs. It cannot widen anything: the
+ * result is always the tighter of the ceiling and what was already required.
+ */
+export function sourcePolicyFor(sources = [], { patterns, ceiling = 'device', base = 'any' } = {}) {
+  const list = (Array.isArray(sources) ? sources : [sources]).filter(Boolean);
+  const hits = [];
+  for (const s of list) {
+    const url = typeof s === 'string' ? s : (s?.url || s?.href || '');
+    if (!url) continue;
+    const c = classifySource(url, patterns ? { patterns } : undefined);
+    if (c.internal) hits.push({ url, host: c.host, matched: c.matched });
+  }
+  if (!hits.length) return { internal: false, reach: base, hits: [], why: null };
+  const safeCeiling = REACH_ORDER.includes(ceiling) ? ceiling : 'device';
+  return {
+    internal: true,
+    reach: meetReach(base, safeCeiling),
+    hits,
+    // Named so the person can see WHICH rule pinned the turn — an unexplained restriction
+    // gets switched off wholesale.
+    why: `${hits[0].host || 'the source'} matches '${hits[0].matched}' — kept ${safeCeiling === 'device' ? 'on this device' : 'inside your workspace'}`,
+  };
+}