@chatpanel/events 0.53.0 → 0.61.0

package/note-plan.js

@@ -0,0 +1,113 @@
+// Planning a goal into a note: the decomposition, the document it becomes, and who wrote
+// which part of it.
+//
+// "Plan this in a new note" is not one model call. A goal is decomposed into sub-tasks, each
+// sub-task is assigned a ROLE — research (needs facts, options, current information) or write
+// (drafting, structure, synthesis) — and each is then run by whichever member of the team
+// suits it. The note is rebuilt after every step, so the user watches a checklist fill in
+// rather than a spinner.
+//
+// What has to be shared is the SHAPE: the decomposition prompt and how its answer is read,
+// the document the tasks render into, and the authorship ledger that matches that document
+// character for character. What stays in the client is the orchestration — running the calls,
+// choosing the models, and painting the editor.
+//
+// THE LEDGER IS BUILT FROM THE SAME PARTS AS THE BODY, which is the whole reason `planParts`
+// exists rather than a template string. A plan note is written entirely by agents; attributing
+// it to "You" would be a lie the History tab then repeats forever. Building the text and the
+// run-list from one list of `{ author, text }` parts means the ledger cannot drift from the
+// document — it sums to its length by construction, which is the invariant every attribution
+// test asserts.
+
+import { mergeRuns } from './attribution.js';
+
+/** Roles a sub-task can be assigned. Anything a model invents is coerced to `write`. */
+export const PLAN_ROLES = Object.freeze(['research', 'write']);
+
+/** The authors a plan note's ledger can name — the team, not the user. */
+export const PLAN_AUTHORS = Object.freeze({ planner: 'Planner', research: 'Researcher', write: 'Writer' });
+
+export const PLAN_DECOMPOSE_SYSTEM = 'You are a planning orchestrator. Break the goal into 3–6 concrete sub-tasks. For each, pick a role: "research" (needs facts, options, prices, or current info — it will web + history search) or "write" (drafting, structure, synthesis). Return ONLY compact JSON: {"tasks":[{"title":"short title","role":"research|write","prompt":"a focused instruction for this sub-task"}]}';
+export const PLAN_DECOMPOSE_MAX_TOKENS = 600;
+export const PLAN_DECOMPOSE_TEMPERATURE = 0.2;
+
+/** The instruction for ONE drafted section of a plan. */
+export function planSectionSystem(goal, task) {
+  return `You are drafting ONE section of a plan for the goal "${goal}". Write the section titled "${task?.title || ''}". Instruction: ${task?.prompt || task?.title || ''}. Be concrete and actionable — bullets, - [ ] tasks, or a small table for options. Output ONLY the section's markdown content (no heading, no preamble).`;
+}
+export const PLAN_SECTION_MAX_TOKENS = 700;
+export const PLAN_SECTION_TEMPERATURE = 0.5;
+
+/**
+ * Read the decomposer's answer into tasks.
+ *
+ * Generous on purpose: this is a model returning JSON through whatever wrapper its provider
+ * felt like adding, and a plan that fails because the answer arrived in a fenced block is a
+ * plan that failed for no reason. The object is found inside the text, an unknown role
+ * becomes `write`, and a completely unreadable answer falls back to ONE task carrying the
+ * original goal — which still produces a useful note rather than an error.
+ */
+export function parsePlanTasks(raw, goal = '', max = 6) {
+  let tasks = [];
+  try {
+    const json = JSON.parse((String(raw || '').match(/\{[\s\S]*\}/) || ['{}'])[0]);
+    tasks = (Array.isArray(json.tasks) ? json.tasks : []).slice(0, max).map((t) => makeTask(t));
+  } catch { /* fall through to the single-task plan */ }
+  tasks = tasks.filter((t) => t.title || t.prompt);
+  if (!tasks.length && String(goal).trim()) tasks = [makeTask({ title: planTitleFor(goal), role: 'write', prompt: goal })];
+  return tasks;
+}
+
+const makeTask = (t) => ({
+  title: String(t?.title || 'Task').slice(0, 80),
+  role: t?.role === 'research' ? 'research' : 'write',
+  prompt: String(t?.prompt || t?.title || ''),
+  done: false,
+  working: false,
+  output: '',
+});
+
+/** A goal reduced to something that reads as a title — markdown stripped, one line, capped. */
+export function planTitleFor(goal, max = 60) {
+  return String(goal || '').replace(/[#*_`>~[\]]/g, '').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+
+/**
+ * The plan note, as `{ author, text }` parts.
+ *
+ * A checklist at the top that fills in as the work lands — so the note is a progress report
+ * at a glance — then one section per sub-task. A task with no output yet says which member is
+ * working on it rather than showing an empty heading, because a heading with nothing under it
+ * reads as a section that came back empty.
+ */
+export function planParts(goal, tasks) {
+  const list = Array.isArray(tasks) ? tasks : [];
+  const done = list.filter((t) => t.done).length;
+  const checklist = list
+    .map((t, i) => `- [${t.done ? 'x' : ' '}] ${i + 1}. ${t.title}${t.working ? ' — _working…_' : ''}`)
+    .join('\n');
+  const parts = [{
+    author: PLAN_AUTHORS.planner,
+    text: `# ${goal}\n\n**Plan** — ${done}/${list.length} sub-tasks done\n\n${checklist}\n\n---\n\n`,
+  }];
+  list.forEach((t, i) => {
+    const who = t.role === 'research' ? PLAN_AUTHORS.research : PLAN_AUTHORS.write;
+    parts.push({ author: PLAN_AUTHORS.planner, text: `## ${i + 1}. ${t.title}\n\n` });
+    parts.push({
+      author: t.output ? who : PLAN_AUTHORS.planner,
+      text: t.output || (t.working ? `_⏳ ${who} working…_` : '_pending_'),
+    });
+    parts.push({ author: PLAN_AUTHORS.planner, text: i < list.length - 1 ? '\n\n' : '\n' });
+  });
+  return parts;
+}
+
+/** The plan note's markdown. */
+export function planBody(goal, tasks) {
+  return planParts(goal, tasks).map((p) => p.text).join('');
+}
+
+/** The authorship run-list for `planBody(goal, tasks)` — equal in length by construction. */
+export function planAttribution(goal, tasks, at = Date.now()) {
+  return mergeRuns(planParts(goal, tasks).map((p) => ({ len: p.text.length, author: p.author, at })));
+}

package/note-research.js

@@ -0,0 +1,135 @@
+// What a note is ABOUT, and whether a search result is actually related to it.
+//
+// A research pane beside a note answers two questions, and both are ranking problems rather
+// than retrieval ones. The retrieval is already shared (`sources-retrieval.js`, `rrf.js`) and
+// the corpus differs per client; what has to be identical is the JUDGEMENT — what words the
+// query is built from, and which results are close enough to show.
+//
+// THE FAILURE THIS EXISTS TO PREVENT IS A PANE FULL OF PLAUSIBLE, UNRELATED THINGS. Any
+// ranker returns its top N for any query, so a note containing "can you check the plan today"
+// retrieves the user's whole history ranked by nothing. Every result looks like a result. The
+// fix is two-sided: build the query from the note's content-bearing words, then require a real
+// overlap before showing anything. **Empty is better than irrelevant** — an empty pane is read
+// as "nothing yet", a full one as "these are related", and only one of those can be wrong.
+//
+// Extracted from the extension's `notes-util.js`, where it was already pure.
+
+/**
+ * Words that carry no topic, dropped from every query and every relevance test.
+ *
+ * Beyond ordinary stop-words this drops NOTE-META and AGENT noise — claude, codex, agent,
+ * research, question, answer, summarize, https, www — because a note that says "ask Claude to
+ * research this" would otherwise be judged to be ABOUT Claude and research, and would match
+ * every other note in which the user typed the same sentence.
+ */
+const STOP = new Set(('the a an and or but for to of in on at by with from as is are was were be been being this that these those it its i you your my me we our they them he she his her can could would should will shall may might do does did done get got make made just like about into over under out up down off not no yes plan planning day today check please help note notes write writing claude code codex anthropic agent agents assistant research researcher question questions answer answers answered reply inline summary summarize source sources cite citation https http www com net org html url link links thing things using use used need needs want wants below above here there').split(/\s+/));
+
+/**
+ * The content-bearing terms of a query — lowercased words of 4+ characters that are not
+ * stop-words. Used to judge relevance, so it is about what the text IS, not how it is phrased.
+ */
+export function salientTerms(q) {
+  const out = new Set();
+  for (const w of String(q || '').toLowerCase().match(/[a-z0-9][a-z0-9'-]{3,}/g) || []) {
+    if (!STOP.has(w)) out.add(w);
+  }
+  return out;
+}
+
+/**
+ * A note's TOPIC terms, most-repeated first — what a good search query is built from.
+ *
+ * Ranked by FREQUENCY rather than position, because the words at the top of a note are
+ * usually its scaffolding ("Notes from the meeting about…") while the words it keeps
+ * returning to are its subject. Ties break toward the longer, more specific term.
+ */
+export function topicTerms(text, n = 8) {
+  const freq = new Map();
+  for (const w of String(text || '').toLowerCase().match(/[a-z][a-z'-]{3,}/g) || []) {
+    if (STOP.has(w)) continue;
+    freq.set(w, (freq.get(w) || 0) + 1);
+  }
+  return [...freq.entries()]
+    .sort((a, b) => b[1] - a[1] || b[0].length - a[0].length)
+    .slice(0, n)
+    .map(([w]) => w);
+}
+
+/**
+ * How related a result is to the query — 0 means "do not show this".
+ *
+ * A specific word (6+ characters) is worth twice a short one, and a WORKSPACE hit has to earn
+ * its place: two matching terms, or one specific one. A single generic word in common is how
+ * an unrelated note from March ends up in the pane.
+ *
+ * `web: true` relaxes that last rule, deliberately. A web result was fetched for a query the
+ * user explicitly asked for, and re-gating it on snippet overlap drops valid hits whose
+ * snippet happens to paraphrase — which is most of them.
+ */
+export function researchRelevance(card, salient, { web = false } = {}) {
+  if (!salient || !salient.size) return 0;
+  const hay = `${card?.title || ''} ${card?.snippet || ''}`.toLowerCase();
+  let hits = 0;
+  let specific = 0;
+  let score = 0;
+  for (const t of salient) {
+    if (!hay.includes(t)) continue;
+    hits += 1;
+    score += t.length >= 6 ? 2 : 1;
+    if (t.length >= 6) specific += 1;
+  }
+  if (!hits) return 0;
+  if (web || hits >= 2 || specific >= 1) return score;
+  return 0;
+}
+
+/** The web query for a note: its title plus its topic terms, capped at a sane length. */
+export function webQuery(title, terms) {
+  return [String(title || ''), [...(terms || [])].slice(0, 8).join(' ')]
+    .filter(Boolean).join(' ').replace(/\s+/g, ' ').trim()
+    .slice(0, 120);
+}
+
+/** One line of a source, flattened — enough to recognise it, not enough to read instead. */
+export function researchSnippet(text = '', max = 160) {
+  return String(text).replace(/\s+/g, ' ').trim().slice(0, max);
+}
+
+/**
+ * Rank and gate a set of candidate cards against the query.
+ *
+ * `{ kind, title, snippet, url, key }` in, the same objects out, ordered by relevance with
+ * the irrelevant dropped and `dismissed` keys removed. Web cards keep their retrieval order
+ * (the engine already ranked them and the user asked for them); workspace cards are re-ranked
+ * on overlap, which is the gate described above.
+ */
+export function rankResearchCards(cards, query, { dismissed = null, web = false } = {}) {
+  const salient = salientTerms(query);
+  const skip = dismissed instanceof Set ? dismissed : new Set(dismissed || []);
+  const kept = (Array.isArray(cards) ? cards : []).filter((c) => c && !skip.has(c.key ?? c.url));
+  if (web) return kept;
+  return kept
+    .map((c) => ({ c, s: researchRelevance(c, salient) }))
+    .filter((x) => x.s > 0)
+    .sort((a, b) => b.s - a.s)
+    .map((x) => x.c);
+}
+
+/**
+ * Merge the two lanes into one shelf.
+ *
+ * Web first when the user explicitly asked for a web search — that is what they pressed —
+ * then the grounded workspace hits, deduped by key across both.
+ */
+export function mergeResearchLanes(webCards, localCards, limit = 12) {
+  const out = [];
+  const seen = new Set();
+  for (const c of [...(webCards || []), ...(localCards || [])]) {
+    const k = c?.key ?? c?.url;
+    if (!k || seen.has(k)) continue;
+    seen.add(k);
+    out.push(c);
+    if (out.length >= limit) break;
+  }
+  return out;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.53.0",
-  "description": "The canonical ChatPanel event-log and capability contracts — typed durable facts, clock-free deterministic linearization, schema upcasting, and the invariants the replay harness asserts. Pure, dependency-free ESM shared by the ChatPanel extension, gateway and bridge.",
+  "version": "0.61.0",
+  "description": "The canonical ChatPanel event-log and capability contracts \u2014 typed durable facts, clock-free deterministic linearization, schema upcasting, and the invariants the replay harness asserts. Pure, dependency-free ESM shared by the ChatPanel extension, gateway and bridge.",
   "type": "module",
   "main": "index.js",
   "exports": {
@@ -11,6 +11,8 @@
     "./backup-envelope.js": "./backup-envelope.js",
     "./capability.js": "./capability.js",
     "./citations.js": "./citations.js",
+    "./cowriter-router.js": "./cowriter-router.js",
+    "./cowriter.js": "./cowriter.js",
     "./curate.js": "./curate.js",
     "./distance.js": "./distance.js",
     "./entitlement.js": "./entitlement.js",
@@ -33,6 +35,13 @@
     "./meeting-analyzers.js": "./meeting-analyzers.js",
     "./meeting-text.js": "./meeting-text.js",
     "./memory.js": "./memory.js",
+    "./model-picker.js": "./model-picker.js",
+    "./note-actions.js": "./note-actions.js",
+    "./note-graph.js": "./note-graph.js",
+    "./note-links.js": "./note-links.js",
+    "./note-mentions.js": "./note-mentions.js",
+    "./note-plan.js": "./note-plan.js",
+    "./note-research.js": "./note-research.js",
     "./observability.js": "./observability.js",
     "./omni.js": "./omni.js",
     "./order.js": "./order.js",
@@ -74,6 +83,7 @@
     "./view.js": "./view.js",
     "./voice-intents.js": "./voice-intents.js",
     "./weather.js": "./weather.js",
+    "./web-search.js": "./web-search.js",
     "./widget.js": "./widget.js"
   },
   "files": [
@@ -83,6 +93,8 @@
     "backup-envelope.js",
     "capability.js",
     "citations.js",
+    "cowriter-router.js",
+    "cowriter.js",
     "curate.js",
     "distance.js",
     "entitlement.js",
@@ -106,6 +118,13 @@
     "meeting-analyzers.js",
     "meeting-text.js",
     "memory.js",
+    "model-picker.js",
+    "note-actions.js",
+    "note-graph.js",
+    "note-links.js",
+    "note-mentions.js",
+    "note-plan.js",
+    "note-research.js",
     "observability.js",
     "omni.js",
     "order.js",
@@ -147,6 +166,7 @@
     "view.js",
     "voice-intents.js",
     "weather.js",
+    "web-search.js",
     "widget.js"
   ],
   "scripts": {

package/web-search.js

@@ -0,0 +1,160 @@
+// Reading a search engine's results page: the rules, without the DOM.
+//
+// Scraping a SERP is mostly judgement, and the judgement is identical everywhere: which
+// engines to ask, how to build their URL safely from a template the user can edit, how to
+// unwrap the redirector every engine wraps its links in, and which of the hundred anchors on
+// the page are actually RESULTS rather than the engine's own navigation, promos and
+// newsletter sign-ups.
+//
+// None of that needs a document. What does need one is turning HTML into a list of anchors,
+// and that is the single thing each host injects: the extension has `DOMParser`, the desktop's
+// main process has neither and uses a small extractor, and a gateway that grew one could pass
+// its own. So there is ONE scraper with three front doors, rather than three scrapers.
+//
+// THE DANGEROUS PART IS THE URL, NOT THE HTML. A search template is user input that becomes a
+// fetch, so `buildSearchUrl` refuses anything that is not https and anything without a query
+// placeholder — and the caller is required to pass the host guard it already owns
+// (`assertFetchable`), because deciding whether an address is safe to fetch is not a question
+// this module is allowed to answer on its own.
+
+/**
+ * The engines, in the order they are tried.
+ *
+ * `enabled` is what a fresh install starts with. Mojeek is absent rather than disabled:
+ * tested, it returns nothing at all, and an engine that never answers is not a fallback — it
+ * is latency plus a misleading "no results".
+ */
+export const SEARCH_ENGINES = Object.freeze([
+  Object.freeze({ id: 'startpage', name: 'Startpage', url: 'https://www.startpage.com/sp/search?query=%s', enabled: true }),
+  Object.freeze({ id: 'duckduckgo', name: 'DuckDuckGo', url: 'https://html.duckduckgo.com/html/?q=%s', enabled: true }),
+  Object.freeze({ id: 'google', name: 'Google', url: 'https://www.google.com/search?q=%s', enabled: false }),
+  Object.freeze({ id: 'bing', name: 'Bing', url: 'https://www.bing.com/search?q=%s', enabled: false }),
+]);
+
+/** How many results to take from one engine before moving on. */
+export const RESULTS_PER_ENGINE = 5;
+
+/**
+ * Turn a template into a URL, refusing the ones that are not safe to fetch.
+ *
+ * `assertFetchable` is INJECTED rather than implemented here: the SSRF/private-host guard is
+ * one shared primitive that the client, the gateway and the bridge all call, and a second
+ * opinion about what counts as a private address is how the two drift apart. Omitting it is
+ * allowed only where the caller has already checked — it throws loudly rather than silently
+ * skipping, so "I forgot" and "I checked elsewhere" cannot look the same.
+ */
+export function buildSearchUrl(template, query, { assertFetchable } = {}) {
+  const t = String(template || '').trim();
+  if (!/^https:\/\//i.test(t)) throw new Error('Search engine URL must start with https://');
+  if (!t.includes('%s') && !t.includes('{q}')) {
+    throw new Error('Search engine URL must contain a %s (or {q}) query placeholder');
+  }
+  const url = t.replace(/%s|\{q\}/g, encodeURIComponent(String(query || '').trim()));
+  if (typeof assertFetchable === 'function') assertFetchable(url);
+  return url;
+}
+
+/**
+ * Unwrap the redirector an engine wraps its results in, so what is fetched and CITED is the
+ * real destination rather than the engine's tracking URL.
+ */
+export function unwrapRedirect(href) {
+  try {
+    const u = new URL(href, 'https://duckduckgo.com');
+    const uddg = u.searchParams.get('uddg'); // DuckDuckGo /l/?uddg=<encoded>
+    if (uddg) return decodeURIComponent(uddg);
+    const other = u.searchParams.get('url') || u.searchParams.get('u');
+    if (other && /^https?:/i.test(other)) return other;
+    return u.href;
+  } catch {
+    return String(href || '');
+  }
+}
+
+/**
+ * Hosts that appear on a SERP and are never results: the engine's own family, and the promos
+ * they carry (Startpage's StartMail, Mojeek's newsletter).
+ *
+ * Deliberately NOT a broad denylist — real results legitimately point at YouTube, Yahoo and
+ * Google properties, and filtering those would be filtering the web.
+ */
+const JUNK_HOSTS = /(^|\.)(startpage\.com|startmail\.com|startpage\.dev|mojeek\.com|buttondown\.(com|email)|ecosia\.org|duckduckgo\.com|search\.brave\.com|qwant\.com)$/i;
+
+/** Is this a link off the engine's own page, or part of the engine itself? */
+export function isResultHost(hostname, engineHost = '') {
+  const host = String(hostname || '').toLowerCase();
+  if (!host) return false;
+  if (JUNK_HOSTS.test(host)) return false;
+  const engineDomain = String(engineHost || '').split('.').slice(-2).join('.').toLowerCase();
+  if (engineDomain && (host === engineDomain || host.endsWith(`.${engineDomain}`))) return false;
+  return true;
+}
+
+/**
+ * Turn a page's anchors into results.
+ *
+ * `anchors` is what the host's extractor produced: `{ href, text, snippet?, chrome? }`, where
+ * `chrome` marks an anchor that sat inside a nav, footer or promo block. Everything after this
+ * point is identical in every client, which is the reason the module exists.
+ *
+ * Deduped on origin+path rather than the full URL, so the same page offered twice with
+ * different tracking parameters counts once.
+ */
+export function pickResults(anchors, { engineHost = '', limit = RESULTS_PER_ENGINE, fallback = false } = {}) {
+  const out = [];
+  const seen = new Set();
+  for (const a of anchors || []) {
+    const href = unwrapRedirect(a?.href || '');
+    let u;
+    try { u = new URL(href); } catch { continue; }
+    if (u.protocol !== 'https:' && u.protocol !== 'http:') continue;
+    if (!isResultHost(u.hostname, engineHost)) continue;
+    // The generic sweep sees the WHOLE page, so it is filtered harder: an anchor inside the
+    // page's own chrome is navigation, not a result.
+    if (fallback && a.chrome) continue;
+    const title = String(a?.text || '').replace(/\s+/g, ' ').trim();
+    // A link whose visible text is a word or two is an icon, a "next", or a breadcrumb.
+    if (title.length < 6) continue;
+    const key = u.origin + u.pathname;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ url: href, title, snippet: String(a?.snippet || '').replace(/\s+/g, ' ').trim() });
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+/**
+ * Merge what several engines returned into one list.
+ *
+ * Engine ORDER is preserved rather than interleaved: the first engine is the one the user put
+ * first, and a result it ranked third is more likely to be wanted than the second engine's
+ * first. Deduped across engines on origin+path, so two engines agreeing shows once.
+ */
+export function mergeEngineResults(perEngine, limit = 8) {
+  const out = [];
+  const seen = new Set();
+  for (const results of perEngine || []) {
+    for (const r of results || []) {
+      let key;
+      try { const u = new URL(r.url); key = u.origin + u.pathname; } catch { key = r.url; }
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(r);
+      if (out.length >= limit) return out;
+    }
+  }
+  return out;
+}
+
+/**
+ * The engines to try, in order: the enabled ones first, then the rest.
+ *
+ * A search that found nothing should escalate to the engines the user configured but left off
+ * rather than report failure — being wrong about which engine works today is much more likely
+ * than the web having no answer.
+ */
+export function engineOrder(engines = SEARCH_ENGINES) {
+  const list = (Array.isArray(engines) ? engines : []).filter((e) => e && e.url && !e.retired);
+  return [...list.filter((e) => e.enabled !== false), ...list.filter((e) => e.enabled === false)];
+}