@chatpanel/events 0.4.0 → 0.6.0

package/index.js

@@ -43,4 +43,6 @@ 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_MANIFEST_VERSION, SKILL_CONTEXTS, SKILL_HISTORY_SCOPES, SKILL_MCP_MODES, SKILL_TRUST, SKILL_FILE_KINDS, SKILL_UPCASTERS, SkillManifestError, isSafeSkillPath, originOf, trustOf, skillFiles, needsBridge, declaredAccess, originLabel, sameSkillOrigin, skillIsStale, validateSkill, upcastSkill, upcastSkills, normalizeSkill } from './skill-manifest.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.4.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.6.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,8 @@
     "./router.js": "./router.js",
     "./rules.js": "./rules.js",
     "./search-engines.js": "./search-engines.js",
+    "./skill-manifest.js": "./skill-manifest.js",
+    "./skill-vars.js": "./skill-vars.js",
     "./sources-retrieval.js": "./sources-retrieval.js",
     "./sources.js": "./sources.js",
     "./store.js": "./store.js",
@@ -35,6 +37,8 @@
     "./upcast.js": "./upcast.js"
   },
   "files": [
+    "LICENSE",
+    "README.md",
     "adapters.js",
     "capability.js",
     "citations.js",
@@ -55,6 +59,8 @@
     "router.js",
     "rules.js",
     "search-engines.js",
+    "skill-manifest.js",
+    "skill-vars.js",
     "sources-retrieval.js",
     "sources.js",
     "store.js",
@@ -62,9 +68,7 @@
     "tool-groups.js",
     "tool-need.js",
     "trajectory.js",
-    "upcast.js",
-    "LICENSE",
-    "README.md"
+    "upcast.js"
   ],
   "scripts": {
     "test": "node --test tests/*.test.js"

package/skill-manifest.js

@@ -0,0 +1,330 @@
+// skill-manifest.js — what a skill IS, for every client that stores or runs one.
+//
+// A skill was a settings record: a prompt plus a few dropdowns, normalized by whichever
+// client happened to save it. That was survivable while every skill was hand-written by
+// the person running it. It stops being survivable the moment a skill can ARRIVE from
+// somewhere — a hub, a repo, another agent's skill directory — because the questions
+// change from "what does this prompt say" to "where did it come from, what may it reach,
+// and has anything checked it".
+//
+// So this module owns the record. Not the storage (a platform question), not the UI (a
+// platform question), not the fetching (F6 S3) — the shape, its evolution, and the two
+// derivations no client may compute for itself:
+//
+//   • TRUST IS DERIVED, NEVER DECLARED. A skill cannot say it is trusted. `trustOf()`
+//     reads provenance: shipped by us -> 'built-in', fetched -> 'community', neither ->
+//     'user'. A stored `trust` field is stripped on normalize, and `builtin` is forced
+//     false whenever an origin is present — otherwise "trusted" would be a string an
+//     importer sets.
+//   • DECLARED ACCESS IS COMPUTED FROM THE RECORD. Everything a skill can reach is
+//     readable before it runs, which is what makes load-time approval possible (P10).
+//     If a reviewer's summary were assembled by the install screen, the install screen
+//     would be the security boundary.
+//
+// Versioning follows the log's discipline: additive only, absence means the previous
+// default, and the upcast chain exists from the start so adding v3 does not mean
+// rewriting every reader.
+
+import { DATA_SCOPES } from './capability.js';
+
+export class SkillManifestError extends Error {
+  constructor(code, message) { super(message); this.name = 'SkillManifestError'; this.code = code; }
+}
+
+/** Schema version of the RECORD. Distinct from `version`, which is the author's semver. */
+export const SKILL_MANIFEST_VERSION = 2;
+
+export const SKILL_CONTEXTS = Object.freeze(['auto', 'page', 'selection', 'tabs', 'none']);
+export const SKILL_HISTORY_SCOPES = Object.freeze(['none', 'chats', 'meetings', 'all']);
+export const SKILL_MCP_MODES = Object.freeze(['none', 'selected', 'default']);
+
+/**
+ * Derived, never stored. 'community' is deliberately the level for a skill fetched from
+ * a vendor repo with a famous name — only what we ship went through our review.
+ */
+export const SKILL_TRUST = Object.freeze(['built-in', 'user', 'community']);
+
+/**
+ * The directories a package may carry, matching the agentskills.io layout. `scripts` is
+ * the tier-3 one: it cannot run in a browser extension and must not be offered as if it
+ * could (see `needsBridge`).
+ */
+export const SKILL_FILE_KINDS = Object.freeze(['references', 'scripts', 'assets', 'templates', 'examples']);
+
+const str = (v) => typeof v === 'string' && v.length > 0;
+
+// A slash command is typed by a human and matched case-insensitively against a stored
+// string; anything outside this grammar either cannot be typed or collides with the
+// leading-slash parse.
+const COMMAND = /^[a-z0-9][a-z0-9_-]*$/;
+
+/**
+ * A file path inside a package directory.
+ *
+ * The check is a security boundary, not tidiness: these strings become filesystem paths
+ * in the bridge's skill store, and a package is authored by a stranger. Rejected are
+ * absolute paths, any `..` segment, backslashes (a Windows separator that a POSIX
+ * `split('/')` would not see as one), leading/trailing whitespace and control characters.
+ * Allowing one of them is a directory-traversal write on someone's machine.
+ */
+export function isSafeSkillPath(p) {
+  if (!str(p) || p.length > 255) return false;
+  if (p !== p.trim()) return false;
+  if (p.includes('\\')) return false;
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f]/.test(p)) return false;
+  if (p.startsWith('/') || /^[a-z]:/i.test(p)) return false;
+  const parts = p.split('/');
+  if (parts.some((seg) => seg === '' || seg === '.' || seg === '..')) return false;
+  return true;
+}
+
+/** Did this skill come from somewhere, or did the user write it? */
+export function originOf(skill) {
+  const o = skill?.origin;
+  return o && typeof o === 'object' && str(o.source) && str(o.id) ? o : null;
+}
+
+/**
+ * Derived from provenance, never read from the record. A skill that arrived from outside
+ * is 'community' whoever published it; 'built-in' means we shipped it.
+ */
+export function trustOf(skill) {
+  if (originOf(skill)) return 'community';
+  return skill?.builtin ? 'built-in' : 'user';
+}
+
+/** The files a package carries, per directory, already filtered to safe paths. */
+export function skillFiles(skill) {
+  const files = skill?.files;
+  const out = {};
+  if (!files || typeof files !== 'object') return out;
+  for (const kind of SKILL_FILE_KINDS) {
+    const list = Array.isArray(files[kind]) ? files[kind].filter(isSafeSkillPath) : [];
+    if (list.length) out[kind] = [...new Set(list)];
+  }
+  return out;
+}
+
+/**
+ * True when running this skill fully needs a host that can execute code — i.e. the
+ * bridge. The extension may still store, show and run the PROMPT half; what it may not
+ * do is pretend the scripts ran.
+ */
+export function needsBridge(skill) {
+  return (skillFiles(skill).scripts || []).length > 0;
+}
+
+/**
+ * Everything this skill can reach, computed from the record. This is what an install
+ * review, the Plugins lens and an admin export all read — one derivation, so the three
+ * cannot disagree about what was approved.
+ */
+export function declaredAccess(skill = {}) {
+  const files = skillFiles(skill);
+  const mcpMode = SKILL_MCP_MODES.includes(skill.mcpMode) ? skill.mcpMode : 'none';
+  const context = SKILL_CONTEXTS.includes(skill.context) ? skill.context : 'auto';
+  const history = SKILL_HISTORY_SCOPES.includes(skill.historyContext) ? skill.historyContext : 'none';
+  const reads = new Set(Array.isArray(skill.reads) ? skill.reads.filter((r) => DATA_SCOPES.includes(r)) : []);
+  // The dropdowns ARE access statements; a record that declared `reads` separately from
+  // them could claim less than it takes.
+  if (context !== 'none') reads.add('page');
+  if (history === 'chats' || history === 'all') reads.add('chats');
+  if (history === 'meetings' || history === 'all') reads.add('meetings');
+  return {
+    trust: trustOf(skill),
+    reads: [...reads].sort(),
+    page: context,
+    history,
+    mcp: mcpMode,
+    mcpServerIds: mcpMode === 'selected' && Array.isArray(skill.mcpServerIds) ? [...skill.mcpServerIds] : [],
+    sources: Array.isArray(skill.sources) ? [...new Set(skill.sources.filter(str))].sort() : [],
+    surfaces: Array.isArray(skill.surfaces) ? [...new Set(skill.surfaces.filter(str))].sort() : [],
+    scripts: files.scripts || [],
+    needsBridge: needsBridge(skill),
+    meeting: !!skill.meeting,
+  };
+}
+
+/** Human label for where a skill came from, for the surfaces that must show provenance. */
+export function originLabel(skill) {
+  const o = originOf(skill);
+  if (!o) return trustOf(skill) === 'built-in' ? 'Built-in' : 'Written here';
+  return o.id.length > 48 ? `${o.source} · …${o.id.slice(-40)}` : `${o.source} · ${o.id}`;
+}
+
+/** Two records describing the same upstream skill — for update checks and dedupe. */
+export function sameSkillOrigin(a, b) {
+  const x = originOf(a);
+  const y = originOf(b);
+  return !!x && !!y && x.source === y.source && x.id === y.id;
+}
+
+/**
+ * Has upstream changed since this was installed? `null` when unanswerable (no origin, or
+ * nothing was hashed) — which callers must treat as "do not claim it is current" rather
+ * than as "up to date".
+ */
+export function skillIsStale(skill, upstreamHash) {
+  const o = originOf(skill);
+  if (!o || !str(o.hash) || !str(upstreamHash)) return null;
+  return o.hash !== upstreamHash;
+}
+
+/**
+ * Validate a skill DECLARATION — the static surface approved before anything runs.
+ * Throws on the first problem, like `validateCapability`.
+ */
+export function validateSkill(skill) {
+  if (!skill || typeof skill !== 'object') throw new SkillManifestError('SHAPE', 'skill must be an object');
+  if (!str(skill.id)) throw new SkillManifestError('SHAPE', 'skill.id required');
+  if (!str(skill.name)) throw new SkillManifestError('SHAPE', `skill '${skill.id}': name required`);
+  if (skill.prompt != null && typeof skill.prompt !== 'string') {
+    throw new SkillManifestError('SHAPE', `skill '${skill.id}': prompt must be a string`);
+  }
+  if (skill.command != null && skill.command !== '' && !COMMAND.test(String(skill.command))) {
+    throw new SkillManifestError('SHAPE', `skill '${skill.id}': command must match ${COMMAND}`);
+  }
+  for (const [field, allowed] of [
+    ['context', SKILL_CONTEXTS], ['historyContext', SKILL_HISTORY_SCOPES], ['mcpMode', SKILL_MCP_MODES],
+  ]) {
+    if (skill[field] != null && !allowed.includes(skill[field])) {
+      throw new SkillManifestError('SHAPE', `skill '${skill.id}': ${field} must be one of ${allowed}`);
+    }
+  }
+  if (skill.reads != null) {
+    if (!Array.isArray(skill.reads) || !skill.reads.every((r) => DATA_SCOPES.includes(r))) {
+      throw new SkillManifestError('SHAPE', `skill '${skill.id}': reads must be within ${DATA_SCOPES}`);
+    }
+  }
+  for (const field of ['sources', 'surfaces']) {
+    if (skill[field] != null && (!Array.isArray(skill[field]) || !skill[field].every(str))) {
+      throw new SkillManifestError('SHAPE', `skill '${skill.id}': ${field} must be an array of ids`);
+    }
+  }
+  if (skill.origin != null) {
+    const o = skill.origin;
+    if (typeof o !== 'object') throw new SkillManifestError('SHAPE', `skill '${skill.id}': origin must be an object`);
+    // Without a source and an id it cannot be re-fetched or compared, which is the whole
+    // reason the field exists; a half-origin is worse than none because it looks answered.
+    if (!str(o.source) || !str(o.id)) {
+      throw new SkillManifestError('ORIGIN', `skill '${skill.id}': origin needs both source and id`);
+    }
+  }
+  if (skill.files != null) {
+    if (typeof skill.files !== 'object') throw new SkillManifestError('SHAPE', `skill '${skill.id}': files must be an object`);
+    for (const kind of Object.keys(skill.files)) {
+      if (!SKILL_FILE_KINDS.includes(kind)) {
+        throw new SkillManifestError('FILES', `skill '${skill.id}': unknown file kind '${kind}'`);
+      }
+      const list = skill.files[kind];
+      if (!Array.isArray(list) || !list.every(str)) {
+        throw new SkillManifestError('FILES', `skill '${skill.id}': files.${kind} must be an array of paths`);
+      }
+      const bad = list.find((p) => !isSafeSkillPath(p));
+      if (bad) throw new SkillManifestError('PATH', `skill '${skill.id}': unsafe path in files.${kind}: ${JSON.stringify(bad)}`);
+    }
+  }
+  // Files without an origin means someone hand-wrote a package record; that is allowed,
+  // but scripts without an origin cannot be scanned against anything, and an unscannable
+  // script is exactly what the admission gate exists to refuse.
+  if (!originOf(skill) && (skill.files?.scripts || []).length) {
+    throw new SkillManifestError('ORIGIN', `skill '${skill.id}': scripts require an origin to be scannable`);
+  }
+  return skill;
+}
+
+/**
+ * v(n) -> v(n+1). Each MUST be total: it may not throw for any record of its version.
+ *
+ * v1 -> v2 stamps the version and nothing else, on purpose. Every field F6 adds is
+ * absence-means-the-old-default, so there is nothing to fill in — the same discipline as
+ * storing which plugins are DISABLED rather than the full state, so a field added later
+ * needs no migration.
+ */
+export const SKILL_UPCASTERS = Object.freeze({
+  1: (s) => ({ ...s, v: SKILL_MANIFEST_VERSION }),
+});
+
+/** Carry a stored skill forward to the current schema. Pure; never mutates the input. */
+export function upcastSkill(stored) {
+  if (!stored || typeof stored !== 'object') throw new SkillManifestError('SHAPE', 'skill must be an object');
+  // A record written before the version existed is v1 by definition.
+  let s = typeof stored.v === 'number' ? stored : { ...stored, v: 1 };
+  let guard = 0;
+  while (s.v < SKILL_MANIFEST_VERSION) {
+    const step = SKILL_UPCASTERS[s.v];
+    if (!step) throw new SkillManifestError('UPCAST', `no upcaster from v${s.v}`);
+    s = step(s);
+    if (++guard > 64) throw new SkillManifestError('UPCAST', 'upcaster chain did not terminate');
+  }
+  if (s.v > SKILL_MANIFEST_VERSION) {
+    throw new SkillManifestError('UPCAST', `skill is v${s.v}; this reader only knows v${SKILL_MANIFEST_VERSION}`);
+  }
+  return s;
+}
+
+export function upcastSkills(stored) {
+  return (Array.isArray(stored) ? stored : []).map(upcastSkill);
+}
+
+/**
+ * Coerce a record into the canonical shape a writer stores. Total and forgiving — this
+ * runs on save, where throwing would cost a user their edit; `validateSkill` is the
+ * strict gate, used where a record ARRIVES.
+ *
+ * The security-relevant coercions are the ones that cannot be left to a caller:
+ * `trust` is never persisted, `builtin` cannot survive an origin, and an unsafe file
+ * path is dropped rather than stored and rejected later.
+ */
+export function normalizeSkill(skill) {
+  if (!skill || typeof skill !== 'object') return skill;
+  const out = { ...upcastSkill(skill) };
+
+  // Skills predate the enabled flag — absence means enabled.
+  out.enabled = out.enabled !== false;
+
+  const mode = String(out.mcpMode || 'none').toLowerCase();
+  out.mcpMode = SKILL_MCP_MODES.includes(mode) ? mode : 'none';
+  const ids = Array.isArray(out.mcpServerIds) ? out.mcpServerIds : [];
+  out.mcpServerIds = out.mcpMode === 'selected'
+    ? [...new Set(ids.map((id) => String(id || '').trim()).filter(Boolean))]
+    : [];
+
+  // Derived, never stored: a record that could assert its own trust would make every
+  // check downstream a formality.
+  delete out.trust;
+
+  const origin = originOf(out);
+  if (origin) {
+    out.builtin = false; // "we shipped it" is not something an import may claim
+    out.origin = {
+      source: origin.source,
+      id: origin.id,
+      ...(str(origin.url) ? { url: origin.url } : {}),
+      ...(str(origin.hash) ? { hash: origin.hash } : {}),
+      ...(origin.scanned && typeof origin.scanned === 'object' ? { scanned: { ...origin.scanned } } : {}),
+    };
+  } else if (out.origin != null) {
+    delete out.origin; // a half-origin looks answered and is not
+  }
+
+  if (out.reads != null) {
+    out.reads = [...new Set((Array.isArray(out.reads) ? out.reads : []).filter((r) => DATA_SCOPES.includes(r)))].sort();
+  }
+  for (const field of ['sources', 'surfaces']) {
+    if (out[field] != null) {
+      out[field] = [...new Set((Array.isArray(out[field]) ? out[field] : []).filter(str))];
+    }
+  }
+
+  if (out.files != null) {
+    const files = skillFiles(out);
+    if (Object.keys(files).length) out.files = files;
+    else delete out.files;
+  }
+
+  if (out.version != null && !str(out.version)) delete out.version;
+
+  return out;
+}

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}}.`;
+}