@chatpanel/events 0.70.0 → 0.72.0

package/cowriter-writer.js

@@ -0,0 +1,199 @@
+// cowriter-writer.js — the WRITER's half of the co-writer: when it may draft, what it is
+// asked, and how much it may spend.
+//
+// The Editor's half (lint, diff, the copy-editor prompt) is cowriter.js. This is the member
+// that WRITES — a continuation from the caret on ⌘↵, a section under a heading you paused on,
+// the next line toward a goal, or the result of an instruction typed into the note — and it
+// lived as a dozen functions inside the extension's notes.js until the desktop needed the
+// same member. Everything here is a decision or a string; the ghost text, the keys and the
+// stream are the client's.
+//
+// The standing rule of this member: IT OFFERS, THE USER ACCEPTS. Every draft is a suggestion
+// with an accept and a reject, and nothing here writes into a document.
+
+// ── What the cursor line affords ─────────────────────────────────────────────────
+
+/** The line the caret is on, as `{ text, start, end }` — `end` excludes the newline. */
+export function lineAt(text, caret) {
+  const src = String(text ?? '');
+  const pos = Math.max(0, Math.min(caret ?? 0, src.length));
+  const start = src.lastIndexOf('\n', pos - 1) + 1;
+  const nl = src.indexOf('\n', pos);
+  const end = nl < 0 ? src.length : nl;
+  return { text: src.slice(start, end), start, end };
+}
+
+/**
+ * What the cursor line affords the Writer: an empty outline item, a TODO marker, or a
+ * heading whose section has no body yet → `{ kind, at, label }`, or null. Detecting the
+ * spot is free; drafting it is a model call, and only happens on a nudge, ⌘↵ or Focus.
+ */
+export function writerAffordance(text, caret) {
+  const v = String(text ?? '');
+  const line = lineAt(v, caret);
+  const t = line.text;
+  if (/^\s*([-*]|\d+\.)\s*(\[ \]\s*)?$/.test(t)) return { kind: 'item', at: line.end, label: 'this item' };
+  if (/\b(TODO|TK|TBD)\b:?\s*$/i.test(t)) return { kind: 'todo', at: line.end, label: 'this to-do' };
+  if (/^#{1,6}\s+\S/.test(t)) { // a heading whose section has no body yet
+    const next = v.slice(line.end).replace(/^\n/, '').split('\n', 1)[0] || '';
+    if (!next.trim() || /^#{1,6}\s/.test(next)) return { kind: 'section', at: line.end, label: 'this section' };
+  }
+  if (!t.trim()) { // a blank line directly under a heading
+    const before = v.slice(0, line.start).replace(/\n$/, '');
+    const prev = before.slice(before.lastIndexOf('\n') + 1);
+    if (/^#{1,6}\s+\S/.test(prev)) return { kind: 'section', at: line.start, label: 'this section' };
+  }
+  return null;
+}
+
+/**
+ * An imperative line the user wants ACTED on — "summarize the above in 3 sentences", "list
+ * the key risks", "rewrite this as bullets" — as distinct from prose to continue. A
+ * conservative verb-led match, never an @mention or a /command line (those run elsewhere).
+ */
+export const INSTRUCTION_RE = /^\s*(?:please\s+|can you\s+|now\s+)?(summari[sz]e|recap|tl;?dr|rewrite|re-?write|reword|rephrase|expand|elaborate|continue|list|enumerate|outline|draft|write|compose|generate|create|add|explain|describe|define|compare|contrast|shorten|condense|tighten|simplify|translate|convert|turn\s+.+\s+into|make\s+(?:this|it|these|a\b)|bullet|brainstorm|suggest|proofread|polish|improve)\b/i;
+
+export function instructionOnLine(text, caret) {
+  const line = lineAt(text, caret);
+  const t = line.text.trim();
+  if (t.length < 6) return null;
+  if (/^[@/]/.test(t) || /@\[[^\]]+\]/.test(t)) return null;
+  if (!INSTRUCTION_RE.test(t)) return null;
+  return { text: t, start: line.start, end: line.end };
+}
+
+// ── Goal-drive ───────────────────────────────────────────────────────────────────
+
+/** Chars of the user's OWN writing required between two automatic drafts. */
+export const GOAL_MIN_NEW = 24;
+
+/**
+ * May the goal draft the next line now?
+ *
+ * It must NOT loop: without this guard it re-fires on every pause (each Enter changes the
+ * length) and re-drafts near-duplicates. So it fires at most once per burst of the user's
+ * own writing — the document must have grown by `minNew` chars since the last draft, the
+ * caret must sit at a line end, and there must be real context to continue. `lastLen` is
+ * the body length at the last draft (-1 = armed: fire once there is context); the caller
+ * re-baselines it when a draft is accepted, so an accepted line does not trigger the next.
+ */
+export function goalDraftAllowed({ text, caret, lastLen = -1, minNew = GOAL_MIN_NEW } = {}) {
+  const v = String(text ?? '');
+  const from = Math.max(0, Math.min(caret ?? 0, v.length));
+  if (from !== v.length && v[from] !== '\n') return false;
+  if (v.slice(0, from).trim().length < 24) return false;
+  if (lastLen >= 0 && v.length <= lastLen + minNew) return false;
+  return true;
+}
+
+// ── Spend ────────────────────────────────────────────────────────────────────────
+
+/**
+ * A rolling per-minute cap on MODEL calls the team makes on its own. Free work — the
+ * deterministic Editor pass, retrieval-only research — never counts; over the cap the
+ * spending members skip until the window clears. Visible, so "why did it stop" has an answer.
+ */
+export function createSpendMeter({ capPerMin = 20, now = Date.now } = {}) {
+  let calls = [];
+  const prune = () => { const t = now(); calls = calls.filter((c) => t - c < 60_000); };
+  return {
+    cap: capPerMin,
+    ok() { prune(); return calls.length < capPerMin; },
+    spend() { calls.push(now()); },
+    used() { prune(); return calls.length; },
+  };
+}
+
+// ── Prompts ──────────────────────────────────────────────────────────────────────
+
+/** The tail of the note the Writer continues from — capped, with the title as context. */
+export function writerTail(before, title = '') {
+  const b = String(before ?? '');
+  const tail = b.length > 1600 ? `…${b.slice(-1600)}` : b;
+  const t = String(title || '').trim();
+  return (t ? `# ${t}\n\n` : '') + tail;
+}
+
+/** Where an instruction's result goes: on its own line under the instruction. */
+export function draftSeparator(before) {
+  const b = String(before ?? '');
+  return b.endsWith('\n\n') ? '' : b.endsWith('\n') ? '\n' : '\n\n';
+}
+
+/** The Researcher's shelf, as the lines the Writer may draw on — a handoff, not a dump. */
+export function groundingBlock(cards = [], { limit = 5 } = {}) {
+  const list = (Array.isArray(cards) ? cards : []).filter((c) => c && c.title).slice(0, limit);
+  if (!list.length) return '';
+  return '\n\nRelated material you may draw on (only if genuinely useful — cite as [[title]] or [text](url)):\n'
+    + list.map((c) => `- ${c.title}${c.snippet ? ` — ${c.snippet}` : ''}`).join('\n');
+}
+
+/**
+ * The Writer's request: a continuation from where the note stops, or an instruction executed
+ * over the note above it. -> { system, user, maxTokens, temperature }
+ */
+export function writerRequest({ before, title = '', instruction = '', contextBefore = null, intent = '', cards = [] } = {}) {
+  const grounding = groundingBlock(cards);
+  const goal = String(intent || '').trim();
+  if (instruction) {
+    return {
+      system: `You are executing an instruction inside the user's note. Use the note as context and do EXACTLY what the instruction says. Match the note's voice, tone, and markdown style. Output ONLY the resulting markdown to insert — no preamble, no restating the instruction, no meta commentary.${goal ? ` The note's goal: ${goal}.` : ''}${grounding}`,
+      user: `NOTE SO FAR:\n${writerTail(contextBefore ?? before, title)}\n\nINSTRUCTION (do exactly this, output only the result):\n${instruction}`,
+      maxTokens: 600,
+      temperature: 0.4,
+    };
+  }
+  return {
+    system: `${goal ? `The note's goal (guide your writing toward it): ${goal}.\n\n` : ''}You continue the user's note from where it stops. Match their voice, tone, and markdown style exactly. Write only the NEXT one or two sentences (or finish the current one) — concise, natural, no preamble, no repetition of prior text, no meta commentary. Output ONLY the continuation.${grounding}`,
+    user: writerTail(before, title),
+    maxTokens: 220,
+    temperature: 0.6,
+  };
+}
+
+/** Inline autocomplete: a few words, at most one sentence, at the very end of the note. */
+export const AUTOCOMPLETE_SYSTEM = 'You are an inline writing autocomplete. Continue the note from EXACTLY where it stops with a SHORT continuation — a few words up to one sentence. Match the voice and markdown. Output ONLY the text to append: no quotes, no preamble, no repetition of prior text. If nothing sensible follows, output nothing.';
+export const AUTOCOMPLETE_MAX_TOKENS = 48;
+export const AUTOCOMPLETE_TEMPERATURE = 0.1;
+
+/** Keep a completion short: the first line, and at most the first sentence of it. */
+export function clipCompletion(s) {
+  let t = String(s ?? '').replace(/^\s+/, '');
+  const nl = t.indexOf('\n');
+  if (nl >= 0) t = t.slice(0, nl);
+  const m = t.match(/^.*?[.!?](\s|$)/);
+  if (m) t = m[0];
+  return t.replace(/\s+$/, '');
+}
+
+// ── The switches, in one voice ───────────────────────────────────────────────────
+
+/** The two gears — and what each DOES to your text, which is the question. */
+export const GEARS = Object.freeze([
+  Object.freeze({ id: 'ambient', name: 'Suggest', note: 'Nothing is written for you. Typo fixes, links and research collect quietly in the Co-writer tab, and you decide what to take. Press ⌘↵ any time to draft ahead.' }),
+  Object.freeze({ id: 'focus', name: 'Write with me', note: 'The team writes alongside you: it drafts a section when you pause on a heading, and every draft is still accept-or-reject. The per-minute spend cap still applies.' }),
+]);
+
+/** The opt-ins. Each is a model call the team may make WITHOUT being asked, so each is off. */
+export const WRITER_PREFS = Object.freeze([
+  Object.freeze({ k: 'revealFixes', label: 'Show fixes as they land', desc: 'Open the Co-writer tab when a typo fix or a draft is ready — no hunting for the badge.', spends: false }),
+  Object.freeze({ k: 'actOnInstructions', label: 'Act on instruction lines', desc: 'A line like “summarize the above in 3 sentences” becomes a task the Writer drafts (accept/reject).', spends: true }),
+  Object.freeze({ k: 'goalDrive', label: 'Let the goal keep writing', desc: 'With a goal set, draft the next line toward it whenever you pause at a line end. Always accept/reject; respects the spend cap.', spends: true }),
+  Object.freeze({ k: 'autocomplete', label: 'Autocomplete as I type', desc: 'A short ghost continuation at the end of the note after a pause — one small call per pause, Tab keeps it. Counts against the spend cap.', spends: true }),
+]);
+
+export const WRITER_PREF_DEFAULTS = Object.freeze({ gear: 'ambient', revealFixes: false, actOnInstructions: false, goalDrive: false, autocomplete: false });
+
+/** A stored prefs object, with unknown keys dropped and missing ones defaulted. */
+export function normalizeWriterPrefs(stored) {
+  const s = stored && typeof stored === 'object' ? stored : {};
+  const out = { ...WRITER_PREF_DEFAULTS };
+  out.gear = s.gear === 'focus' ? 'focus' : 'ambient';
+  for (const p of WRITER_PREFS) out[p.k] = s[p.k] === true;
+  return out;
+}
+
+/** A note's goal, as stored: one line, capped. */
+export function normalizeIntent(v) {
+  return String(v || '').replace(/\s+/g, ' ').trim().slice(0, 200);
+}

package/index.js

@@ -201,7 +201,9 @@ export {
 } from './memory.js';
 export { SOURCE_TRUST, SkillSourceError, defineSkillSource, createSkillSourceRegistry } from './skill-sources.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 { SKILL_VARS, SKILL_VAR_NAMES, skillVar, skillVarPattern, parseSkillVars, lintSkillPrompt, suggestSkillVar, substituteSkillVars, expandSkillPrompt, skillVarGuidance, SkillVarError } from './skill-vars.js';
+export { lineAt, writerAffordance, INSTRUCTION_RE, instructionOnLine, GOAL_MIN_NEW, goalDraftAllowed, createSpendMeter, writerTail, draftSeparator, groundingBlock, writerRequest, AUTOCOMPLETE_SYSTEM, AUTOCOMPLETE_MAX_TOKENS, AUTOCOMPLETE_TEMPERATURE, clipCompletion, GEARS, WRITER_PREFS, WRITER_PREF_DEFAULTS, normalizeWriterPrefs, normalizeIntent } from './cowriter-writer.js';
+export { SLASH_TYPING_RE, enabledSkills, slashCommandItems, matchSlashSkill, matchSlashRecipe, recipeInvocationText, slashCommandInsert, skillInvocationOf, skillInvocationLabel } from './slash-commands.js';
 export { outlineOf, parseListItem, continueList, indentSelection, toggleWrap, toggleLinePrefix, toggleTask, toggleLink, docStats, selectionStats } from './markdown-authoring.js';
 export {
   MAX_TAG_LENGTH, MAX_TAGS, normalizeTag, normalizeTags, hasTag, addTag, removeTag, toggleTag,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.70.0",
+  "version": "0.72.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",
@@ -13,6 +13,7 @@
     "./citations.js": "./citations.js",
     "./cowriter-router.js": "./cowriter-router.js",
     "./cowriter.js": "./cowriter.js",
+    "./cowriter-writer.js": "./cowriter-writer.js",
     "./curate.js": "./curate.js",
     "./distance.js": "./distance.js",
     "./entitlement.js": "./entitlement.js",
@@ -67,6 +68,7 @@
     "./skill-scan.js": "./skill-scan.js",
     "./skill-sources.js": "./skill-sources.js",
     "./skill-vars.js": "./skill-vars.js",
+    "./slash-commands.js": "./slash-commands.js",
     "./sources-retrieval.js": "./sources-retrieval.js",
     "./sources.js": "./sources.js",
     "./store.js": "./store.js",
@@ -121,6 +123,7 @@
     "context-attachments.js",
     "cowriter-router.js",
     "cowriter.js",
+    "cowriter-writer.js",
     "curate.js",
     "distance.js",
     "entitlement.js",
@@ -179,6 +182,7 @@
     "skill-scan.js",
     "skill-sources.js",
     "skill-vars.js",
+    "slash-commands.js",
     "sources-retrieval.js",
     "sources.js",
     "store.js",

package/skill-vars.js

@@ -224,6 +224,22 @@ export async function substituteSkillVars(text, { args = '', resolvers = {} } =
   return { text: out, filled, empty, unknown: lint.unknown };
 }
 
+/**
+ * The prompt a `/command args` sends.
+ *
+ * The typed args fill `{{input}}` when the author left a slot for them, and are appended
+ * after the prompt when not — never both, which is how "/fix this sentence" once landed
+ * in the prompt twice. Everything else `substituteSkillVars` reports (an empty selection,
+ * an invented placeholder) comes back untouched, so the caller can say so out loud.
+ */
+export async function expandSkillPrompt(prompt, { args = '', resolvers = {} } = {}) {
+  const src = String(prompt || '');
+  const a = String(args || '').trim();
+  const inline = lintSkillPrompt(src).hasInput;
+  const body = src + (!inline && a ? `\n\n${a}` : '');
+  return substituteSkillVars(body, { args: a, resolvers });
+}
+
 /**
  * The sentence prompt-assist needs so the model stops inventing placeholders.
  * Generated from SKILL_VARS so a variable added here reaches the assist prompt

package/slash-commands.js

@@ -0,0 +1,133 @@
+// slash-commands.js — the `/command` grammar of a chat composer, declared ONCE.
+//
+// A skill, a saved recipe and a client's built-in command all answer to a slash. Which
+// ones exist, how a half-typed prefix is matched, what a chosen item inserts, and how a
+// sent run is LABELLED all lived in the extension's side panel, and the desktop had to copy
+// them the day its composer wanted `/summarize` too. This module is that copy, made the
+// original: a third client (mobile, a channel bot) inherits the grammar instead of
+// re-deriving it.
+//
+// What is NOT here is deliberate:
+//   • the BUILT-IN list — `/search`, `/history`, `/monitor` — is what a client can DO,
+//     and a desktop with no live meeting has no `/tldr`. Each client passes its own.
+//   • the prompt expansion — `expandSkillPrompt` in skill-vars.js, so a composer that only
+//     needs the menu never pays for the variable layer.
+//   • the entitlement — `skillsAllowed` is decided by the caller against its licence.
+
+function normalizePrefix(prefix) {
+  return String(prefix || '')
+    .toLowerCase()
+    .replace(/^\//, '')
+    .replace(/\s+/g, ' ');
+}
+
+function skillItem(skill) {
+  return {
+    type: 'skill',
+    command: skill.command || '',
+    icon: skill.icon || '🎓',
+    description: skill.description || skill.name || '',
+    skill,
+  };
+}
+
+// A saved recipe is a /command too. It is not a skill: nothing is expanded into a prompt.
+// The line becomes a plain request to run it, and the `recipe` tool does the rest.
+function recipeItem(recipe) {
+  return { type: 'recipe', command: recipe.name || '', icon: '🧩', description: recipe.description || 'Saved recipe', recipe };
+}
+
+/** Skills that are switched on. Absence of the flag means enabled (older records have none). */
+export function enabledSkills(skills) {
+  return (Array.isArray(skills) ? skills : []).filter((s) => !!s && s.enabled !== false);
+}
+
+/**
+ * The items a composer offers for what has been typed so far.
+ *
+ * @param builtins      the client's own commands — `{ command, icon, description, feature? }`.
+ *                      One with a `feature` is shown LOCKED when `features[feature]` is
+ *                      false: a Free user should still discover what Pro unlocks.
+ * @param skills        the user's skills; only enabled ones with a command are offered
+ * @param recipes       saved recipes; enabled ones by name
+ * @param prefix        what follows the slash, possibly with a subcommand ("history m")
+ * @param skillsAllowed whether skills are offered at all (Pro on the extension)
+ * @param features      `{ liveMeetings: true }` — what the licence unlocks
+ */
+export function slashCommandItems({
+  builtins = [],
+  skills = [],
+  recipes = [],
+  prefix = '',
+  skillsAllowed = false,
+  features = {},
+} = {}) {
+  const normalized = normalizePrefix(prefix);
+  const own = (Array.isArray(builtins) ? builtins : []).map((item) => ({
+    type: 'builtin',
+    ...item,
+    locked: !!item.feature && !features[item.feature],
+  }));
+  const skillItems = skillsAllowed ? enabledSkills(skills).map(skillItem) : [];
+  const recipeItems = (recipes || []).filter((r) => r && r.enabled !== false && r.name).map(recipeItem);
+  return [...own, ...skillItems, ...recipeItems]
+    .filter((item) => item.command && item.command.toLowerCase().startsWith(normalized))
+    .slice(0, 12);
+}
+
+/** Is the composer's text a slash command still being typed — the moment to show the menu? */
+export const SLASH_TYPING_RE = /^\/([a-z0-9_-]*(?:\s+[a-z0-9_-]*)?)$/i;
+
+/** "/summarize the thread" → the enabled skill whose command is `summarize`, and the rest. */
+export function matchSlashSkill(text, skills = []) {
+  const m = /^\/([a-z0-9_-]+)\s*([\s\S]*)$/i.exec(String(text || ''));
+  if (!m) return null;
+  const skill = enabledSkills(skills).find((s) => String(s.command || '').toLowerCase() === m[1].toLowerCase());
+  return skill ? { skill, args: m[2].trim() } : null;
+}
+
+/** "/open_bug Crash on start" → the recipe, and the rest of the line as its input. */
+export function matchSlashRecipe(text, recipes = []) {
+  const m = /^\/([a-z0-9_-]+)\s*([\s\S]*)$/i.exec(String(text || ''));
+  if (!m) return null;
+  const recipe = (recipes || []).find((r) => r && r.enabled !== false && String(r.name || '').toLowerCase() === m[1].toLowerCase());
+  return recipe ? { recipe, args: m[2].trim() } : null;
+}
+
+/** What the model receives for a recipe command: a request, not a prompt expansion. */
+export function recipeInvocationText(recipe, args = '') {
+  const a = String(args || '').trim();
+  return `Run the saved recipe "${recipe.name}"${a ? ` with this input: ${a}` : ''}. Use the recipe tool; if a parameter is missing, ask for it.`;
+}
+
+export function slashCommandInsert(item) {
+  return item?.command ? `/${item.command} ` : '/';
+}
+
+/**
+ * How a skill invocation should READ once it has been sent.
+ *
+ * The model must receive the whole prompt — that is what a skill IS. The user's own bubble
+ * echoing it back is a separate question with a different answer: a screen of instructions
+ * they wrote themselves buries the thread the skill was asked to read. So the send keeps
+ * the expansion as the message CONTENT (model, exports and memory capture see exactly what
+ * they always saw) and carries this beside it, for display only.
+ *
+ * Null for anything that is not a command, so callers attach it unconditionally and older
+ * messages — which have none — keep rendering as they did.
+ */
+export function skillInvocationOf(skill, args = '') {
+  if (!skill?.command) return null;
+  return {
+    command: skill.command,
+    args: String(args || '').trim(),
+    name: skill.name || '',
+    icon: skill.icon || '🎓',
+  };
+}
+
+/** The one line an invocation is worth: `/command args`, exactly as typed. */
+export function skillInvocationLabel(inv) {
+  if (!inv?.command) return '';
+  return `/${inv.command}${inv.args ? ` ${inv.args}` : ''}`;
+}