@chatpanel/events 0.69.1 → 0.71.0

package/context-attachments.js

@@ -0,0 +1,148 @@
+// ATTACHED CONTEXT, AS THE MODEL SEES IT — the same on every client.
+//
+// A message carries `attachments`: pages, selections, fetched links, files, images, and the
+// user's own records. This is how they reach a model: text sources folded into the message
+// as <context> blocks, images as image blocks in the provider's wire shape, and — when the
+// turn has tools and the sources are big — a MANIFEST plus a `source` tool instead of the
+// full text, so "hi" on a long page does not pay for the page.
+//
+// Moved out of the extension's providers.js so the desktop's turn assembles attachments
+// exactly the way the panel does. Pure: nothing here fetches or renders.
+
+import { makeSourceStore, manifestText, readSource, approxTokens } from './sources-retrieval.js';
+
+// Flatten a stored message (with attachments) into the text the model sees.
+// Image attachments are excluded here — they go to the model as image blocks
+// (see toMultimodalMessages), not as text.
+export function renderContent(m) {
+  let text = m.content || '';
+  const ctx = (m.attachments || []).filter((a) => a.kind !== 'image');
+  if (ctx.length) {
+    const blocks = ctx
+      .map((a) => {
+        const head = `[${a.kind || 'context'}] ${a.title || a.url || ''}`.trim();
+        return `<context source="${(a.url || a.title || '').replace(/"/g, '')}">\n# ${head}\n${a.text || ''}\n</context>`;
+      })
+      .join('\n\n');
+    text = text ? `${text}\n\n${blocks}` : blocks;
+  }
+  return text;
+}
+
+export function toChatMessages(messages) {
+  return messages
+    .filter((m) => m.role === 'user' || m.role === 'assistant')
+    .map((m) => ({ role: m.role, content: renderContent(m) }));
+}
+
+// Image attachments on a message: { dataUrl: 'data:<media>;base64,<...>' }.
+export function imageAttachmentsOf(m) {
+  return (m.attachments || []).filter((a) => a.kind === 'image' && a.dataUrl);
+}
+
+// Like toChatMessages, but emits multimodal content (text + image blocks) for
+// user messages that carry images, in the given provider's wire format. Falls
+// back to plain string content when there are no images. `provider` is
+// 'openai' | 'anthropic'.
+export function toMultimodalMessages(messages, provider) {
+  return messages
+    .filter((m) => m.role === 'user' || m.role === 'assistant')
+    .map((m) => {
+      const text = renderContent(m);
+      const imgs = m.role === 'user' ? imageAttachmentsOf(m) : [];
+      if (imgs.length === 0) return { role: m.role, content: text };
+      if (provider === 'anthropic') {
+        const content = [];
+        for (const a of imgs) {
+          const match = /^data:([^;]+);base64,(.+)$/s.exec(a.dataUrl);
+          if (match) content.push({ type: 'image', source: { type: 'base64', media_type: match[1], data: match[2] } });
+        }
+        if (text) content.push({ type: 'text', text });
+        return { role: 'user', content: content.length ? content : text };
+      }
+      // openai (and OpenAI-compatible vision endpoints)
+      const content = [];
+      if (text) content.push({ type: 'text', text });
+      for (const a of imgs) content.push({ type: 'image_url', image_url: { url: a.dataUrl } });
+      return { role: 'user', content: content.length ? content : text };
+    });
+}
+
+/**
+ * Hand the model a MANIFEST of what is attached, and a tool to read it.
+ *
+ * Attachments used to be flattened into the first message — every attached tab, in full,
+ * before the model had said anything. "hi" on a long page paid for the whole page, and five
+ * attached tabs put five documents in the prompt to answer a question about one paragraph of
+ * one of them.
+ *
+ * Two conditions, both necessary:
+ *   - THE TURN MUST CARRY TOOLS. Deferring content a model cannot then fetch does not save
+ *     tokens, it deletes the context — the worst possible outcome, and silently.
+ *   - IT MUST BE WORTH A ROUND TRIP. Below the threshold the extra call costs more than the
+ *     text it avoids, so small attachments still travel inline.
+ *
+ * Returns the rewritten messages plus a store, or null when nothing was deferred.
+ */
+export function deferAttachedSources(messages, tools, { minTokens = 700 } = {}) {
+  if (!tools?.specs?.length) return null;
+  const carried = [];
+  for (const m of messages || []) {
+    for (const a of m?.attachments || []) {
+      if (a?.kind === 'image' || !a?.text) continue;
+      carried.push(a);
+    }
+  }
+  if (!carried.length) return null;
+  const store = makeSourceStore(carried.map((a) => ({
+    kind: a.kind || 'context', title: a.title, url: a.url, text: a.text,
+  })));
+  if (store.tokens < minTokens) return null;
+  // Same index, same id: the manifest and the store must agree or the model asks for
+  // something real and is told it does not exist.
+  const idFor = new Map(carried.map((a, i) => [a, store.entries[i]?.id]));
+  const out = (messages || []).map((m) => {
+    if (!m?.attachments?.some((a) => idFor.get(a))) return m;
+    return {
+      ...m,
+      attachments: m.attachments.map((a) => {
+        const id = idFor.get(a);
+        // The stub keeps the title and url — knowing WHAT is attached is what lets the model
+        // decide whether to read it, and that part is cheap.
+        return id ? { ...a, text: `(not included — read with \`source\`: id ${id}, ~${approxTokens(a.text)} tokens)` } : a;
+      }),
+    };
+  });
+  return { messages: out, store };
+}
+
+export const SOURCE_TOOL_SPEC = {
+  name: 'source',
+  description: 'Read an attached source (a page, tab, selection or file the user attached). Their content is NOT in the conversation — read what you need from here.',
+  parameters: {
+    type: 'object',
+    properties: {
+      id: { type: 'string', description: 'The source id from the manifest, e.g. page-1.' },
+      query: { type: 'string', description: 'What you are looking for. A large source returns the matching sections rather than its first page.' },
+    },
+    required: ['id'],
+  },
+};
+
+/** Add `source` to an existing toolset without disturbing what is already there. */
+export function withSourceTool(tools, store) {
+  const spec = { ...SOURCE_TOOL_SPEC };
+  const system = [
+    tools?.system,
+    `${manifestText(store)}\n\nTheir content is NOT in this conversation. Call \`source\` with an id — and a query when the source is large — to read what you need.`,
+  ].filter(Boolean).join('\n\n');
+  return {
+    ...tools,
+    specs: [...(tools?.specs || []), spec],
+    system,
+    systemParts: { ...(tools?.systemParts || {}), source: approxTokens(manifestText(store)) },
+    execute: async (name, input, meta) => (name === 'source'
+      ? JSON.stringify(readSource(store, typeof input === 'string' ? JSON.parse(input || '{}') : (input || {})))
+      : tools.execute(name, input, meta)),
+  };
+}

package/index.js

@@ -201,7 +201,8 @@ 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 { 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,
@@ -284,3 +285,5 @@ export { mcpSharedSystem, mcpInventorySystem, sourceCitationSystem, combineSyste
 export { adaptiveToolRetryHint, createAdaptiveToolPolicy, isInvalidToolParametersResult } from './adaptive-tool-policy.js';
 export { getMcpProviders, testMcpServer, resetMcp } from './mcp-manager.js';
 export { WEATHER_TOOL_NAME, WEATHER_TOOL_SYSTEM, weatherToolProvider } from './weather-tool.js';
+// Attached context as the model sees it — <context> blocks, image blocks, deferred sources.
+export { renderContent, toChatMessages, toMultimodalMessages, imageAttachmentsOf, deferAttachedSources, withSourceTool, SOURCE_TOOL_SPEC } from './context-attachments.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.69.1",
+  "version": "0.71.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",
@@ -67,6 +67,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",
@@ -106,7 +107,8 @@
     "./adaptive-tool-policy.js": "./adaptive-tool-policy.js",
     "./mcp-client.js": "./mcp-client.js",
     "./mcp-manager.js": "./mcp-manager.js",
-    "./weather-tool.js": "./weather-tool.js"
+    "./weather-tool.js": "./weather-tool.js",
+    "./context-attachments.js": "./context-attachments.js"
   },
   "files": [
     "LICENSE",
@@ -117,6 +119,7 @@
     "capability.js",
     "citations.js",
     "client-prefs.js",
+    "context-attachments.js",
     "cowriter-router.js",
     "cowriter.js",
     "curate.js",
@@ -177,6 +180,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}` : ''}`;
+}