@runtypelabs/persona 4.8.0 → 4.10.0

package/src/utils/mention-llm-format.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from "vitest";
+import { formatMentionBlock } from "./mention-llm-format";
+import type { AgentWidgetMentionLlmEntry } from "../types";
+
+function entry(label: string, text: string): AgentWidgetMentionLlmEntry {
+  return {
+    label,
+    text,
+    ref: { sourceId: "files", itemId: label, label },
+    item: { id: label, label },
+  };
+}
+
+describe("formatMentionBlock", () => {
+  it("fenced (default): label in the info string, body inside a ``` fence", () => {
+    expect(formatMentionBlock(entry("App.tsx", "FILE BODY"), 0)).toBe(
+      "```App.tsx\nFILE BODY\n```"
+    );
+    // Passing "fenced" explicitly is identical to the default.
+    expect(formatMentionBlock(entry("App.tsx", "FILE BODY"), 0, "fenced")).toBe(
+      "```App.tsx\nFILE BODY\n```"
+    );
+  });
+
+  it("fenced: escalates to four backticks when the body contains a ``` fence", () => {
+    const body = "before\n```\ncode\n```\nafter";
+    expect(formatMentionBlock(entry("Doc", body), 0)).toBe(
+      "````Doc\n" + body + "\n````"
+    );
+  });
+
+  it("fenced: escalates past the longest run when the body contains a ```` fence", () => {
+    const body = "````\nnested\n````";
+    expect(formatMentionBlock(entry("Doc", body), 0)).toBe(
+      "`````Doc\n" + body + "\n`````"
+    );
+  });
+
+  it("fenced: escalates past fences indented up to three spaces (CommonMark)", () => {
+    // A closing fence indented by up to three spaces is valid CommonMark, so an
+    // indented ``` inside the body must still force a four-backtick wrapper.
+    const body = "- item\n   ```\n   code\n   ```";
+    expect(formatMentionBlock(entry("Doc", body), 0)).toBe(
+      "````Doc\n" + body + "\n````"
+    );
+    // Four or more spaces is an indented code block, not a fence: no escalation.
+    expect(formatMentionBlock(entry("Doc", "    ```"), 0)).toBe(
+      "```Doc\n    ```\n```"
+    );
+  });
+
+  it("function form: a throwing template falls back to fenced instead of rejecting", () => {
+    const block = formatMentionBlock(entry("App.tsx", "FILE BODY"), 0, () => {
+      throw new Error("host template bug");
+    });
+    // One bad host template must not reject finalize() and drop every
+    // mention's context from the outgoing message.
+    expect(block).toBe("```App.tsx\nFILE BODY\n```");
+  });
+
+  it("document: Anthropic shape with a 1-based index", () => {
+    expect(formatMentionBlock(entry("App.tsx", "FILE BODY"), 0, "document")).toBe(
+      '<document index="1">\n' +
+        "<source>App.tsx</source>\n" +
+        "<document_content>\nFILE BODY\n</document_content>\n" +
+        "</document>"
+    );
+    // index is 0-based in, rendered 1-based out.
+    expect(formatMentionBlock(entry("Two", "B"), 1, "document")).toContain(
+      '<document index="2">'
+    );
+  });
+
+  it("document: falls back to the fenced block when the body carries the closing tag", () => {
+    const body = "spoofed </document_content> injection";
+    // Would break the XML boundary → fenced instead.
+    expect(formatMentionBlock(entry("Doc", body), 0, "document")).toBe(
+      "```Doc\n" + body + "\n```"
+    );
+  });
+
+  it("function form: receives {entry, index} and its return is used verbatim", () => {
+    const seen: { label: string; index: number }[] = [];
+    const out = formatMentionBlock(entry("App.tsx", "BODY"), 3, (e, i) => {
+      seen.push({ label: e.label, index: i });
+      return `CUSTOM(${e.item.id}):${e.text}`;
+    });
+    expect(out).toBe("CUSTOM(App.tsx):BODY");
+    expect(seen).toEqual([{ label: "App.tsx", index: 3 }]);
+  });
+});

package/src/utils/mention-llm-format.ts

@@ -0,0 +1,79 @@
+import type {
+  AgentWidgetContextMentionConfig,
+  AgentWidgetMentionLlmEntry,
+} from "../types";
+
+/**
+ * Longest run of leading backticks on any line of `text`. A fenced block whose
+ * fence is longer than this can safely wrap the body without the body's own
+ * fences closing it early. CommonMark treats a closing fence indented by up to
+ * three spaces as valid, so indented runs count too.
+ */
+function longestLeadingBacktickRun(text: string): number {
+  let longest = 0;
+  for (const line of text.split("\n")) {
+    const match = /^ {0,3}(`+)/.exec(line);
+    if (match && match[1].length > longest) longest = match[1].length;
+  }
+  return longest;
+}
+
+/**
+ * Wrap `text` in a fenced code block carrying `label` in the info string. The
+ * fence escalates past any backtick run inside the body (three backticks by
+ * default, four/five/… when the body itself contains a fence) so a mention body
+ * can never terminate its own wrapper.
+ */
+function fencedBlock(label: string, text: string): string {
+  const fence = "`".repeat(Math.max(3, longestLeadingBacktickRun(text) + 1));
+  return `${fence}${label}\n${text}\n${fence}`;
+}
+
+/**
+ * Anthropic's documented long-context document shape. `index` is 0-based here
+ * and rendered 1-based (`index + 1`) to match Anthropic's example numbering.
+ * A body containing the literal `</document_content>` closing tag would break
+ * the XML boundary, so that one entry falls back to the fenced block, which has
+ * no such collision.
+ */
+function documentBlock(label: string, text: string, index: number): string {
+  if (text.includes("</document_content>")) return fencedBlock(label, text);
+  return (
+    `<document index="${index + 1}">\n` +
+    `<source>${label}</source>\n` +
+    `<document_content>\n${text}\n</document_content>\n` +
+    `</document>`
+  );
+}
+
+/**
+ * Format one resolved mention into the ready-to-join LLM block string, per the
+ * widget's `contextMentions.llmFormat`. `index` is the 0-based position of this
+ * block among the message's contributed mention blocks (used by the `"document"`
+ * preset's 1-based numbering and passed through to the function form).
+ *
+ * A throwing function-form template falls back to the fenced preset for that
+ * entry instead of propagating: `finalize()` runs the whole assembly in one
+ * pass, so an uncaught throw here would reject the entire bundle and silently
+ * drop every mention's context (plus contentParts and structured context) from
+ * the outgoing message — far worse than one host-formatted block degrading.
+ */
+export function formatMentionBlock(
+  entry: AgentWidgetMentionLlmEntry,
+  index: number,
+  format: AgentWidgetContextMentionConfig["llmFormat"] = "fenced"
+): string {
+  if (typeof format === "function") {
+    try {
+      return format(entry, index);
+    } catch (error) {
+      console.warn(
+        "[persona] contextMentions.llmFormat threw; falling back to the fenced format for this mention",
+        error
+      );
+      return fencedBlock(entry.label, entry.text);
+    }
+  }
+  if (format === "document") return documentBlock(entry.label, entry.text, index);
+  return fencedBlock(entry.label, entry.text);
+}

package/src/utils/mention-matcher.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from "vitest";
+import { defaultMentionFilter, createStaticMentionSource } from "./mention-matcher";
+import type { AgentWidgetContextMentionItem } from "../types";
+
+const item = (
+  label: string,
+  extra: Partial<AgentWidgetContextMentionItem> = {}
+): AgentWidgetContextMentionItem => ({ id: label, label, ...extra });
+
+describe("defaultMentionFilter", () => {
+  it("returns all items recency-ordered for an empty query", () => {
+    const items = [
+      item("alpha", { recencyScore: 1 }),
+      item("beta", { recencyScore: 5 }),
+      item("gamma", { recencyScore: 3 }),
+    ];
+    expect(defaultMentionFilter(items, "").map((i) => i.label)).toEqual([
+      "beta",
+      "gamma",
+      "alpha",
+    ]);
+  });
+
+  it("ranks prefix > word-boundary > subsequence", () => {
+    const items = [
+      item("subsequence_app_x"), // 'app' as subsequence only? actually contains 'app' as substring
+      item("my-app-config"), // word boundary: 'app' starts the 'app' word
+      item("application"), // prefix
+      item("apricot pie"), // subsequence a-p-p? 'apricot pie' -> a,p,...,p (yes)
+    ];
+    const ranked = defaultMentionFilter(items, "app").map((i) => i.label);
+    expect(ranked[0]).toBe("application"); // prefix wins
+    expect(ranked.indexOf("my-app-config")).toBeLessThan(
+      ranked.indexOf("apricot pie")
+    );
+  });
+
+  it("drops non-matching items", () => {
+    const items = [item("dashboard"), item("settings")];
+    expect(defaultMentionFilter(items, "xyz")).toHaveLength(0);
+  });
+
+  it("is case-insensitive", () => {
+    const items = [item("README.md")];
+    expect(defaultMentionFilter(items, "readme")).toHaveLength(1);
+  });
+
+  it("treats camelCase boundaries as word starts", () => {
+    const items = [item("getUserName")];
+    const ranked = defaultMentionFilter(items, "user");
+    expect(ranked).toHaveLength(1);
+  });
+
+  it("breaks ties by recency then label", () => {
+    const items = [
+      item("appB", { recencyScore: 1 }),
+      item("appA", { recencyScore: 1 }),
+      item("appC", { recencyScore: 9 }),
+    ];
+    expect(defaultMentionFilter(items, "app").map((i) => i.label)).toEqual([
+      "appC",
+      "appA",
+      "appB",
+    ]);
+  });
+});
+
+describe("createStaticMentionSource", () => {
+  it("wires search() to defaultMentionFilter and passes resolve through", async () => {
+    const resolve = async () => ({ llmAppend: "x" });
+    const src = createStaticMentionSource({
+      id: "files",
+      label: "Files",
+      items: [item("App.tsx"), item("index.ts")],
+      resolve,
+      resolveOn: "submit",
+    });
+    expect(src.id).toBe("files");
+    expect(src.label).toBe("Files");
+    expect(src.resolveOn).toBe("submit");
+    const ctx = {} as never;
+    const results = await src.search("app", ctx);
+    expect(results.map((i) => i.label)).toEqual(["App.tsx"]);
+    expect(src.resolve).toBe(resolve);
+  });
+});

package/src/utils/mention-matcher.ts

@@ -0,0 +1,221 @@
+/**
+ * Default fuzzy matcher + static-source helper for context mentions.
+ *
+ * Pure and dependency-free so it can be exported for hosts (to filter
+ * client-side sources) and unit-tested in isolation. Ranking tiers, best first:
+ *   1. prefix       — label starts with the query
+ *   2. word-boundary — a word inside the label starts with the query
+ *   3. subsequence   — query chars appear in order anywhere in the label
+ * Ties break by `recencyScore` (desc) then label (asc). An empty query returns
+ * every item ordered by recency (recents/popular first).
+ */
+
+import type {
+  AgentWidgetContextMentionCommandContext,
+  AgentWidgetContextMentionItem,
+  AgentWidgetContextMentionSource,
+} from "../types";
+
+// Match tiers, best (lowest) first. Plain numbers rather than a const enum so
+// the module stays isolatedModules-safe.
+const TIER_PREFIX = 0;
+const TIER_WORD_BOUNDARY = 1;
+const TIER_SUBSEQUENCE = 2;
+const TIER_NONE = 3;
+
+function isSubsequence(needle: string, haystack: string): boolean {
+  if (!needle) return true;
+  let n = 0;
+  for (let h = 0; h < haystack.length && n < needle.length; h++) {
+    if (haystack[h] === needle[n]) n++;
+  }
+  return n === needle.length;
+}
+
+function scoreItem(label: string, query: string): number {
+  const l = label.toLowerCase();
+  const q = query.toLowerCase();
+  if (l.startsWith(q)) return TIER_PREFIX;
+  // Word boundaries: whitespace, hyphen, underscore, slash, dot, camelCase.
+  // Split camelCase by inserting a space at lower→upper transitions first
+  // (a lookbehind-free rewrite — lookbehind is a parse error on Safari < 16.4,
+  // and this module ships in the core bundle, so a regex literal there would
+  // break the whole widget on those browsers even with mentions disabled).
+  const words = label.replace(/([a-z])([A-Z])/g, "$1 $2").split(/[\s\-_/.]+/);
+  if (words.some((w) => w.toLowerCase().startsWith(q))) return TIER_WORD_BOUNDARY;
+  if (isSubsequence(q, l)) return TIER_SUBSEQUENCE;
+  return TIER_NONE;
+}
+
+function compareWithinTier(
+  a: AgentWidgetContextMentionItem,
+  b: AgentWidgetContextMentionItem
+): number {
+  const ra = a.recencyScore ?? 0;
+  const rb = b.recencyScore ?? 0;
+  if (rb !== ra) return rb - ra;
+  return a.label.localeCompare(b.label);
+}
+
+/**
+ * Filter + rank items for the current `@query`. An empty query keeps all items,
+ * recency-ordered. Non-matching items are dropped.
+ */
+export function defaultMentionFilter(
+  items: AgentWidgetContextMentionItem[],
+  query: string
+): AgentWidgetContextMentionItem[] {
+  const q = query.trim();
+  if (!q) {
+    return [...items].sort(compareWithinTier);
+  }
+  const scored: { item: AgentWidgetContextMentionItem; tier: number }[] = [];
+  for (const item of items) {
+    const tier = scoreItem(item.label, q);
+    if (tier !== TIER_NONE) scored.push({ item, tier });
+  }
+  scored.sort((a, b) => {
+    if (a.tier !== b.tier) return a.tier - b.tier;
+    return compareWithinTier(a.item, b.item);
+  });
+  return scored.map((s) => s.item);
+}
+
+/**
+ * Split a command-channel query into its command NAME (first token) and ARGS
+ * (everything after, trimmed). `"deploy staging"` → `{ name: "deploy", args:
+ * "staging" }`; `"deploy"` → `{ name: "deploy", args: "" }`. Shared by the
+ * slash-command source (matches on `name`) and the controller (captures `args`).
+ */
+export function splitCommandQuery(query: string): { name: string; args: string } {
+  const trimmed = query.replace(/^\s+/, "");
+  const sp = trimmed.search(/\s/);
+  if (sp === -1) return { name: trimmed, args: "" };
+  return { name: trimmed.slice(0, sp), args: trimmed.slice(sp + 1).trim() };
+}
+
+/**
+ * The easy path: a static, in-memory list filtered client-side with
+ * {@link defaultMentionFilter}. Supply your own `resolve()` to turn a selected
+ * item into a dispatch payload (lead with `llmAppend`).
+ */
+export function createStaticMentionSource(opts: {
+  id: string;
+  label: string;
+  items: AgentWidgetContextMentionItem[];
+  resolve: AgentWidgetContextMentionSource["resolve"];
+  resolveOn?: "select" | "submit";
+}): AgentWidgetContextMentionSource {
+  return {
+    id: opts.id,
+    label: opts.label,
+    resolveOn: opts.resolveOn,
+    search: (query) => defaultMentionFilter(opts.items, query),
+    resolve: opts.resolve,
+  };
+}
+
+/**
+ * A single slash-command definition for {@link createSlashCommandsSource}. Maps
+ * to a menu item plus its dispatch behavior (see `AgentWidgetContextMentionItem.command`):
+ *  - `"prompt"` (default): `prompt` text is written into the composer (a macro).
+ *  - `"action"`: `action()` runs in the browser (no message sent).
+ *  - `"server"`: `data` is sent to the backend via request `context.mentions`.
+ */
+export type SlashCommandDefinition = {
+  /** Command name shown after the trigger (e.g. "summarize" → `/summarize`). */
+  name: string;
+  /** Menu subtitle. */
+  description?: string;
+  /** Lucide icon name for the menu row / chip. */
+  iconName?: string;
+  /** Dispatch kind. @default "prompt" */
+  kind?: "prompt" | "action" | "server";
+  /** `kind:"prompt"` — composer text (static, or built from the typed args). */
+  prompt?: string | ((args: string) => string);
+  /** `kind:"prompt"` — insertion mode. @default "replace" */
+  insertMode?: "replace" | "insert-at-caret";
+  /** `kind:"prompt"` — submit the composer immediately after inserting. */
+  submitOnSelect?: boolean;
+  /**
+   * Free-text argument hint (e.g. "order id"). Shown as ghost text in the menu
+   * row (`lookup ‹order id›`) and switches the command to INLINE COMPLETION:
+   * selecting it fills `/name ` into the composer so you type the arg inline,
+   * and the command runs at SUBMIT with the typed args (Slack-style). Optional
+   * for `"prompt"`/`"action"`; `"server"` commands always complete inline.
+   */
+  argsPlaceholder?: string;
+  /** `kind:"action"` — the browser handler (receives parsed `args`). */
+  action?: (ctx: AgentWidgetContextMentionCommandContext) => void | Promise<void>;
+  /** `kind:"server"` — structured payload sent via `context.mentions.<sourceId>.<name>`. */
+  data?:
+    | Record<string, unknown>
+    | ((args: string) => Record<string, unknown>);
+};
+
+/**
+ * Build a `/`-slash-command SOURCE for `contextMentions.triggers`. Unlike a
+ * mention source, its items are COMMANDS (verbs): selecting one runs a prompt
+ * macro, a client action, or a server skill (see {@link SlashCommandDefinition}).
+ *
+ * Matching is on the command NAME only (the first token of the query), so
+ * `/deploy staging` still matches the `deploy` command while `staging` becomes
+ * the command's `args`. Pair it with a `"/"` channel, typically at line-start:
+ *
+ * ```ts
+ * contextMentions: {
+ *   enabled: true,
+ *   sources: [ ...mentionSources ],           // @ context
+ *   triggers: [{
+ *     trigger: "/",
+ *     triggerPosition: "line-start",
+ *     sources: [createSlashCommandsSource({ id: "cmd", label: "Commands", commands })],
+ *   }],
+ * }
+ * ```
+ */
+export function createSlashCommandsSource(opts: {
+  id: string;
+  label: string;
+  commands: SlashCommandDefinition[];
+}): AgentWidgetContextMentionSource {
+  const items: AgentWidgetContextMentionItem[] = opts.commands.map((c) => ({
+    id: c.name,
+    label: c.name,
+    description: c.description,
+    iconName: c.iconName,
+    command: c.kind ?? "prompt",
+    insertMode: c.insertMode,
+    submitOnSelect: c.submitOnSelect,
+    action: c.action,
+    commandArgsPlaceholder: c.argsPlaceholder,
+  }));
+  const byName = new Map(opts.commands.map((c) => [c.name, c]));
+  const itemByName = new Map(items.map((it) => [it.id, it]));
+
+  return {
+    id: opts.id,
+    label: opts.label,
+    // Exact-name lookup for submit-time inline-command dispatch (the query's
+    // first token) — not a fuzzy search.
+    matchCommand: (name) => itemByName.get(name),
+    // Server commands defer resolve to submit (args captured at select). Prompt
+    // commands call resolve synchronously from the controller; action commands
+    // never resolve. So "submit" is the correct source-level default here.
+    resolveOn: "submit",
+    search: (query) => defaultMentionFilter(items, splitCommandQuery(query).name),
+    resolve: (item, ctx) => {
+      const def = byName.get(item.id);
+      if (!def) return {};
+      if (def.kind === "server") {
+        const data =
+          typeof def.data === "function" ? def.data(ctx.args) : def.data;
+        return { context: data ?? {} };
+      }
+      // prompt (and the default): the composer-insert text.
+      const text =
+        typeof def.prompt === "function" ? def.prompt(ctx.args) : def.prompt ?? "";
+      return { insertText: text };
+    },
+  };
+}

package/src/utils/mention-token.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared builder for the inline mention TOKEN — the atomic styled pill that sits
+ * inside the sentence (Slack/Linear/Cursor style), used by both the contenteditable
+ * composer (inline chunk) and the read-only sent bubble (`message-bubble`, core).
+ *
+ * The default is a tinted pill: icon + `@label`, colored by
+ * `--persona-mention-token-accent` (from `ref.color`, else the theme accent), with
+ * a `data-mention-source` attribute so hosts can theme per source/type in CSS
+ * (`.persona-mention-token[data-mention-source="files"] { … }`). A host can replace
+ * the whole element via `render` (the `renderMentionToken` config hook).
+ *
+ * Display-only: no document model, safe to bundle in both the core and the inline
+ * chunk (a small duplicate, like other shared helpers).
+ */
+
+import { createElement, createNode, cx } from "./dom";
+import { renderLucideIcon } from "./icons";
+import type { AgentWidgetContextMentionRef } from "../types";
+
+export interface AgentWidgetContextMentionTokenRenderContext {
+  ref: AgentWidgetContextMentionRef;
+  readonly: boolean;
+}
+
+export interface CreateMentionTokenOptions {
+  /** True in the sent bubble (adds `persona-mention-token-readonly`). */
+  readonly?: boolean;
+  /** Full-custom token DOM (the `renderMentionToken` config hook). */
+  render?: (ctx: AgentWidgetContextMentionTokenRenderContext) => HTMLElement;
+}
+
+export function createMentionTokenElement(
+  ref: AgentWidgetContextMentionRef,
+  opts: CreateMentionTokenOptions = {}
+): HTMLElement {
+  if (opts.render) return opts.render({ ref, readonly: !!opts.readonly });
+
+  const token = createNode("span", {
+    className: cx(
+      "persona-mention-token",
+      opts.readonly && "persona-mention-token-readonly"
+    ),
+    // role="img" + aria-label makes the icon + `@label` announce as one atomic
+    // unit ("App.tsx mention") instead of the icon and text being read
+    // separately; the resolve-status hook may later swap this label (see
+    // composer-contenteditable `setMentionStatus`).
+    attrs: {
+      "data-mention-source": ref.sourceId,
+      title: ref.label,
+      role: "img",
+      "aria-label": `${ref.label} mention`,
+    },
+  });
+  // Per-item / per-type accent recolors the whole pill (bg tint + icon + text).
+  if (ref.color) {
+    token.style.setProperty("--persona-mention-token-accent", ref.color);
+  }
+
+  const iconEl = renderLucideIcon(ref.iconName ?? "at-sign", 13, "currentColor", 2);
+  if (iconEl) {
+    const iconHost = createElement("span", "persona-mention-token-icon");
+    iconHost.appendChild(iconEl);
+    token.appendChild(iconHost);
+  }
+  token.appendChild(
+    createNode("span", {
+      className: "persona-mention-token-label",
+      text: `@${ref.label}`,
+    })
+  );
+  return token;
+}