@chatpanel/events 0.3.0 → 0.5.0

package/index.js

@@ -43,4 +43,5 @@ export { createManifest, ManifestError, SOURCES } from './manifest.js';
 export { createKernel, meetDecisions, KernelError, REQUIRED_PLUGINS, ALLOW_ALL } from './kernel.js';
 export { replay, formatReport, parseJsonl, toJsonl } from './harness.js';
 export { compileQuery, findMatches, matchIndexFor, expandReplacement, replaceMatch, replaceAll, replaceAllInRange, MAX_MATCHES } from './text-search.js';
+export { SKILL_VARS, SKILL_VAR_NAMES, skillVar, skillVarPattern, parseSkillVars, lintSkillPrompt, suggestSkillVar, substituteSkillVars, skillVarGuidance, SkillVarError } from './skill-vars.js';
 export { outlineOf, parseListItem, continueList, indentSelection, toggleWrap, toggleLinePrefix, toggleTask, toggleLink, docStats, selectionStats } from './markdown-authoring.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.3.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.5.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": {
@@ -25,6 +25,7 @@
     "./router.js": "./router.js",
     "./rules.js": "./rules.js",
     "./search-engines.js": "./search-engines.js",
+    "./skill-vars.js": "./skill-vars.js",
     "./sources-retrieval.js": "./sources-retrieval.js",
     "./sources.js": "./sources.js",
     "./store.js": "./store.js",
@@ -35,6 +36,8 @@
     "./upcast.js": "./upcast.js"
   },
   "files": [
+    "LICENSE",
+    "README.md",
     "adapters.js",
     "capability.js",
     "citations.js",
@@ -55,6 +58,7 @@
     "router.js",
     "rules.js",
     "search-engines.js",
+    "skill-vars.js",
     "sources-retrieval.js",
     "sources.js",
     "store.js",
@@ -62,9 +66,7 @@
     "tool-groups.js",
     "tool-need.js",
     "trajectory.js",
-    "upcast.js",
-    "LICENSE",
-    "README.md"
+    "upcast.js"
   ],
   "scripts": {
     "test": "node --test tests/*.test.js"

package/router.js

@@ -144,6 +144,12 @@ const TIE_BAND = 0.10;
 // worth a few seconds, which is the same reasoning the provider order already encodes.
 const SECONDS_PER_UNIT_COST = 5;
 
+// How much closer-to-home is worth in the balanced score. Lower is better, so a model on the
+// user's own machine gets a discount and a third party pays full price. Deliberately gentle:
+// a 30% edge decides between comparable candidates and loses to any real difference in speed,
+// cost or quality — privacy that ELIMINATES is the reach ceiling, and it lives in route().
+const REACH_WEIGHT = Object.freeze({ device: 0.7, trusted: 0.85, any: 1 });
+
 /**
  * The model name stripped of provider prefix and tag, so the SAME model matches across hosts:
  * `deepseek-ai/DeepSeek-V4-Flash` and `deepseek/deepseek-v4-flash` are one model reached two
@@ -182,8 +188,21 @@ export function signalsFrom(request = {}) {
     // short. The keyword heuristics are not, so those need enough surrounding text to be
     // describing code rather than mentioning it: prose can say "import" or end a line with a
     // semicolon without being a programming task.
+    // ASKING FOR CODE IS A CODING REQUEST, not only pasting some.
+    //
+    // This read the MATERIAL and nothing else, so "write a function that debounces this" —
+    // no fence, too short for the token heuristic — required no coding capability at all.
+    // That made the per-model Coding checkbox unreachable for most real coding requests:
+    // turning it off for one agent changed nothing, because nothing ever asked for it, and
+    // the agent kept being chosen. A lever that only moves on pasted code is a lever the
+    // user cannot see working.
+    //
+    // Deliberately a VERB NEXT TO A CODE NOUN rather than either alone: 'test' and 'api'
+    // appear in ordinary prose constantly, and a signal that fires on prose would put a
+    // quality floor on every message.
     code: /```/.test(text)
-      || (chars > 80 && /\bfunction\b|\bclass\b|=>|;\s*$|\bdef\b|\bimport\b|\bconst\b/m.test(text)),
+      || (chars > 80 && /\bfunction\b|\bclass\b|=>|;\s*$|\bdef\b|\bimport\b|\bconst\b/m.test(text))
+      || /\b(write|fix|debug|refactor|implement|optimi[sz]e|review|explain|generate|add|update|port|migrate)\b[^.?!]{0,60}\b(code|function|method|class|script|bug|regex|query|unit ?test|module|component|endpoint|snippet|compiler?|stack ?trace|typescript|javascript|python|rust|golang|sql|css|html)\b/i.test(text),
     complexity: (chars > 4000 || /```/.test(text)
       || (chars >= 200 && /\bstep by step\b|\bplan\b|\brefactor\b|\bmigrate\b|\banalyse|\banalyze/i.test(text)))
       ? 'high'
@@ -203,8 +222,20 @@ export function signalsFrom(request = {}) {
     // bare, they demanded a word boundary immediately after the prefix, so "summarize this
     // document" matched nothing and was classified as SMALL TALK. A prefix that can never
     // fire is worse than an absent one — it reads as covered.
+    // ASKING A QUESTION ABOUT SOMETHING IS WORK. The list below was a list of things you DO,
+    // so a request to UNDERSTAND — "can you explain what this does", "why is this failing",
+    // "how does routing pick a model" — matched nothing and came back as small talk. That is
+    // not a cosmetic misfile: small talk is what makes preferenceFor ask for LATENCY, and the
+    // latency axis reads nothing but milliseconds, so a genuine question was routed for speed
+    // and went past a free local model to a third party. The verbs of explanation and of
+    // changing code belong here for the same reason 'summarise' does.
     smalltalk: chars < 100 && !/```/.test(text)
-      && !/\b(draw|click|open|fill|read|find|search|edit|write|create|update|delete|run|fix|change|add|remove|select|scroll|extract|summar\w*|analy\w*|check|review|list|show|go to|navigate|my|mine|this page|here|it|that)\b/i.test(text),
+      && !/\b(draw|click|open|fill|read|find|search|edit|write|create|update|delete|run|fix|change|add|remove|select|scroll|extract|summar\w*|analy\w*|check|review|list|show|go to|navigate|my|mine|this page|here|it|that)\b/i.test(text)
+      && !/\b(explain|describe|define|compare|translate|why|debug|refactor|implement|improve|optimi[sz]e|convert|calculate|generate|draft|rename|build|test|install|deploy|design|plan)\b/i.test(text)
+      // 'how' only when it opens a question about something — bare "how are you" is the
+      // pleasantry this whole test exists to catch, and putting it in the word list would
+      // have reclassified the one case everybody agrees on.
+      && !/\bhow\s+(do|does|did|can|could|should|would|to|much|many|long)\b/i.test(text),
     chars,
   };
 }
@@ -592,10 +623,26 @@ export function createModelRouter({ models = [], middleware = [], strategies = [
         // zero — burying every model we have not benchmarked would make the router
         // permanently prefer whatever it happened to measure first.
         const q = Number.isFinite(m.quality) ? Math.max(0.1, m.quality) : 0.5;
-        if (prefer === 'latency') return m.latencyMs * busy;
-        if (prefer === 'cost') return m.costPer1k * busy;
+        // NEARER IS WORTH SOMETHING, and the trade-making axes are where it can be said.
+        //
+        // The provider order already claims it — "the user's own machine: no quota, no
+        // outage, no third party" is its first rung — but providerRank only arranges a
+        // near-tie, and a local model and a hosted one are almost never within the tie band.
+        // So every preference weighed time and money and ignored where the request goes, and
+        // a free model on the user's own machine lost to a third party over a latency figure
+        // that is itself a guess.
+        //
+        // A multiplier, not a term, and a small one: it shifts a close call and cannot rescue
+        // a model that is genuinely slower AND worse. Applied to 'latency', 'cost' and
+        // 'balanced' — all of which trade one number against another — and NOT to 'quality',
+        // because a nearer model is not a better one and saying so would invert that axis the
+        // way dividing by quality once inverted these. Reach remains a ceiling in route():
+        // this only orders survivors, it never admits a candidate the ceiling excluded.
+        const near = REACH_WEIGHT[m.reach] ?? 1;
+        if (prefer === 'latency') return m.latencyMs * busy * near;
+        if (prefer === 'cost') return m.costPer1k * busy * near;
         if (prefer === 'quality') return busy / q;
-        return ((m.latencyMs / 1000) + m.costPer1k * SECONDS_PER_UNIT_COST) * busy / q;
+        return ((m.latencyMs / 1000) + m.costPer1k * SECONDS_PER_UNIT_COST) * busy * near / q;
       };
       // ORDER IS A SETTING, NOT A TIE-BREAK THAT NEVER FIRES.
       //

package/skill-vars.js

@@ -0,0 +1,237 @@
+// skill-vars.js — the placeholders a skill prompt may carry, declared ONCE.
+//
+// A skill prompt can interpolate a few runtime values: what the user typed, the
+// selection, the page URL/title, today's date. Until this module existed that set
+// lived as a regex chain inside the extension's side panel, and nothing else knew
+// it — so three things drifted apart:
+//
+//   • the EDITOR advertised placeholders in a placeholder attribute,
+//   • the PANEL substituted a different set,
+//   • prompt-assist was told to "preserve any {{placeholders}} verbatim" without
+//     being told which ones exist — so the model invented {{content}}, guarded it,
+//     and the user shipped a prompt with a slot nothing would ever fill.
+//
+// That last failure is silent by construction: an unknown placeholder is just text,
+// so the model receives the literal characters `{{content}}` and usually papers over
+// it. The skill looks broken for a reason no surface names. Declaring the set once
+// makes the same list authoritative for the editor's lint, the assist prompt, and
+// substitution — a fourth client (mobile, the gateway, the bridge) inherits it
+// rather than re-deriving it.
+//
+// Platform access is INJECTED, never imported: the page URL comes from `chrome.tabs`
+// in the extension, from the request in the gateway, and from nothing at all in a
+// batch run. This module knows the contract; the host knows how to satisfy it.
+
+export class SkillVarError extends Error {
+  constructor(code, message) { super(message); this.name = 'SkillVarError'; this.code = code; }
+}
+
+/**
+ * The complete set. `source` says where the value comes from, which is what the
+ * lint and the assist guidance need to explain it:
+ *   'args'     — the text the user supplied with the invocation
+ *   'resolver' — the host fills it (page URL, title, selection, date)
+ */
+export const SKILL_VARS = Object.freeze([
+  Object.freeze({
+    name: 'input',
+    source: 'args',
+    labelled: true, // {{input:label}} — the label is a hint to the author, not sent
+    summary: 'What the user typed after the /command — or whatever is already in the composer when they pick the skill from the menu.',
+  }),
+  Object.freeze({
+    name: 'selection',
+    source: 'resolver',
+    summary: 'The text selected on the page right now.',
+  }),
+  Object.freeze({
+    name: 'url',
+    source: 'resolver',
+    summary: "The active tab's URL.",
+  }),
+  Object.freeze({
+    name: 'title',
+    source: 'resolver',
+    summary: "The active tab's title.",
+  }),
+  Object.freeze({
+    name: 'date',
+    source: 'resolver',
+    summary: "Today's date.",
+  }),
+]);
+
+export const SKILL_VAR_NAMES = Object.freeze(SKILL_VARS.map((v) => v.name));
+
+const BY_NAME = new Map(SKILL_VARS.map((v) => [v.name, v]));
+
+export function skillVar(name) {
+  return BY_NAME.get(String(name || '').trim().toLowerCase()) || null;
+}
+
+// Any {{ token }}, with an optional :label. Deliberately permissive on what it
+// CAPTURES — an unknown name has to be recognised as a placeholder before it can be
+// reported as unknown. A pattern that only matched known names would make the
+// {{content}} class of bug invisible all over again.
+const TOKEN = /\{\{\s*([a-z_][a-z0-9_-]*)\s*(?::([^}]*))?\s*\}\}/gi;
+
+/** The token pattern for one variable — `g` and `i`, fresh each call (no lastIndex sharing). */
+export function skillVarPattern(name) {
+  const v = skillVar(name);
+  if (!v) throw new SkillVarError('UNKNOWN_VAR', `unknown skill variable '${name}'`);
+  return v.labelled
+    ? new RegExp(`\\{\\{\\s*${v.name}(?::[^}]*)?\\s*\\}\\}`, 'gi')
+    : new RegExp(`\\{\\{\\s*${v.name}\\s*\\}\\}`, 'gi');
+}
+
+/**
+ * Every placeholder in a prompt, in source order.
+ * -> [{ name, label, raw, index, known }]
+ */
+export function parseSkillVars(text) {
+  const out = [];
+  const src = String(text || '');
+  TOKEN.lastIndex = 0;
+  let m = TOKEN.exec(src);
+  while (m) {
+    const name = m[1].toLowerCase();
+    out.push({
+      name,
+      label: (m[2] || '').trim(),
+      raw: m[0],
+      index: m.index,
+      known: BY_NAME.has(name),
+    });
+    m = TOKEN.exec(src);
+  }
+  return out;
+}
+
+// Damerau-free Levenshtein, bounded by the short names we compare. Enough to turn
+// {{content}} → {{input}}? No — those are not near neighbours, which is the point:
+// a bad suggestion is worse than none, so `suggestSkillVar` falls back to the input
+// slot only when the unknown name READS like a content slot.
+function distance(a, b) {
+  const m = a.length;
+  const n = b.length;
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  for (let i = 1; i <= m; i += 1) {
+    const row = [i];
+    for (let j = 1; j <= n; j += 1) {
+      row[j] = Math.min(
+        prev[j] + 1,
+        row[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    prev = row;
+  }
+  return prev[n];
+}
+
+// Names a model reaches for when it invents a "put the user's text here" slot. These
+// are NOT aliases — nothing substitutes them, because silently filling a placeholder
+// the user never agreed to is how a prompt starts meaning something else. They only
+// make the suggestion in the lint concrete.
+const INPUT_SHAPED = new Set([
+  'content', 'text', 'body', 'draft', 'document', 'doc', 'args', 'arguments',
+  'query', 'question', 'task', 'request', 'prompt', 'message', 'user_input', 'userinput',
+]);
+
+/** Nearest known variable for a misspelling or an invented name, or '' if none is close. */
+export function suggestSkillVar(name) {
+  const q = String(name || '').trim().toLowerCase();
+  if (!q || BY_NAME.has(q)) return '';
+  if (INPUT_SHAPED.has(q)) return 'input';
+  let best = '';
+  let bestD = Infinity;
+  for (const known of SKILL_VAR_NAMES) {
+    const d = distance(q, known);
+    if (d < bestD) { bestD = d; best = known; }
+  }
+  // Two edits, or a third of a longer name — enough to catch a transposition
+  // ("titel") without turning an unrelated word into a confident wrong guess.
+  return bestD <= Math.max(2, Math.floor(q.length / 3)) ? best : '';
+}
+
+/**
+ * Static check of a prompt, for the skill editor.
+ * -> { known: [names], unknown: [{ name, raw, suggestion }], hasInput: boolean }
+ *
+ * `hasInput` is what decides whether the caller's text goes INTO the prompt or gets
+ * appended after it, so the editor can explain which of the two will happen.
+ */
+export function lintSkillPrompt(text) {
+  const seen = parseSkillVars(text);
+  const known = [];
+  const unknown = [];
+  const dedupe = new Set();
+  for (const tok of seen) {
+    if (dedupe.has(tok.name)) continue;
+    dedupe.add(tok.name);
+    if (tok.known) known.push(tok.name);
+    else unknown.push({ name: tok.name, raw: tok.raw, suggestion: suggestSkillVar(tok.name) });
+  }
+  return { known, unknown, hasInput: dedupe.has('input') };
+}
+
+/**
+ * Fill a prompt's placeholders.
+ *
+ * @param text      the skill prompt
+ * @param args      the user's text, for {{input}}
+ * @param resolvers { selection, url, title, date } — each () => string | Promise<string>.
+ *                  A resolver is called ONLY when its variable actually appears, so a
+ *                  prompt without {{selection}} never pays for a tab read. A missing
+ *                  resolver, or one that throws, yields '' and is reported in `empty`
+ *                  rather than failing the turn.
+ *
+ * -> { text, filled: [names], empty: [names], unknown: [{ name, raw, suggestion }] }
+ *
+ * UNKNOWN PLACEHOLDERS ARE LEFT ALONE. Rewriting a user's prompt because we did not
+ * recognise a token would be a silent edit of the thing they wrote; reporting it lets
+ * the caller say so out loud, which is the actual fix.
+ */
+export async function substituteSkillVars(text, { args = '', resolvers = {} } = {}) {
+  const src = String(text || '');
+  const lint = lintSkillPrompt(src);
+  if (!lint.known.length) return { text: src, filled: [], empty: [], unknown: lint.unknown };
+
+  const filled = [];
+  const empty = [];
+  let out = src;
+
+  for (const name of lint.known) {
+    let value = '';
+    if (name === 'input') {
+      value = args == null ? '' : String(args);
+    } else {
+      const resolve = resolvers[name];
+      if (typeof resolve === 'function') {
+        try {
+          value = (await resolve()) ?? '';
+        } catch {
+          value = ''; // a dead tab or a denied permission is an empty slot, not a failure
+        }
+      }
+      value = String(value);
+    }
+    if (value.trim()) filled.push(name);
+    else empty.push(name);
+    out = out.replace(skillVarPattern(name), () => value);
+  }
+
+  return { text: out, filled, empty, unknown: lint.unknown };
+}
+
+/**
+ * The sentence prompt-assist needs so the model stops inventing placeholders.
+ * Generated from SKILL_VARS so a variable added here reaches the assist prompt
+ * without anyone remembering to update a string.
+ */
+export function skillVarGuidance() {
+  const list = SKILL_VARS.map((v) => `{{${v.name}}} (${v.summary})`).join(' ');
+  return `The prompt may use ONLY these placeholders, and they are filled at run time: ${list} `
+    + 'Preserve the ones already present verbatim, and never invent another — an unrecognised '
+    + `placeholder is sent to the model as literal text. For the user's own text use {{input}}.`;
+}