letagents 0.12.33 → 0.12.35

package/shared/code-highlighting.mjs

@@ -0,0 +1,345 @@
+export const CANONICAL_LANGUAGES = Object.freeze([
+  'javascript',
+  'typescript',
+  'python',
+  'bash',
+  'json',
+  'yaml',
+  'xml',
+  'css',
+  'sql',
+  'diff',
+  'rust',
+  'go',
+  'c',
+  'cpp',
+  'java',
+  'csharp',
+  'dockerfile',
+  'ruby',
+  'php',
+  'swift',
+  'kotlin',
+  'ini',
+]);
+
+const CANONICAL_SET = new Set(CANONICAL_LANGUAGES);
+
+export const LANGUAGE_ALIASES = new Map([
+  // JavaScript
+  ['js', 'javascript'],
+  ['jsx', 'javascript'],
+  ['mjs', 'javascript'],
+  ['cjs', 'javascript'],
+  // TypeScript
+  ['ts', 'typescript'],
+  ['tsx', 'typescript'],
+  ['mts', 'typescript'],
+  ['cts', 'typescript'],
+  // Python
+  ['py', 'python'],
+  // Bash / Shell
+  ['sh', 'bash'],
+  ['zsh', 'bash'],
+  ['shell', 'bash'],
+  // YAML
+  ['yml', 'yaml'],
+  // XML / HTML / SVG
+  ['html', 'xml'],
+  ['xhtml', 'xml'],
+  ['svg', 'xml'],
+  // Rust
+  ['rs', 'rust'],
+  // Go
+  ['golang', 'go'],
+  // C / C++
+  ['c++', 'cpp'],
+  ['cc', 'cpp'],
+  ['cxx', 'cpp'],
+  ['hpp', 'cpp'],
+  ['h', 'c'],
+  // C#
+  ['cs', 'csharp'],
+  // Dockerfile
+  ['docker', 'dockerfile'],
+  // Ruby
+  ['rb', 'ruby'],
+  // Kotlin
+  ['kt', 'kotlin'],
+  ['kts', 'kotlin'],
+  // INI / TOML
+  ['toml', 'ini'],
+]);
+
+export const MAX_HIGHLIGHT_CHARS = 5_000;
+export const MAX_HIGHLIGHT_LINES = 250;
+export const MAX_HIGHLIGHT_LINE_LENGTH = 1_000;
+export const MAX_CACHE_ENTRIES = 500;
+export const MAX_CACHE_CHARS = 2_000_000;
+
+export const DEFAULT_TIME_BUDGET_MS = 250;
+export const DEFAULT_TIME_WINDOW_MS = 1_000;
+
+export function escapeHtml(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+export function escapeAttribute(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+export function resolveLanguage(rawTag) {
+  if (!rawTag || typeof rawTag !== 'string') return null;
+  const normalized = rawTag.trim().toLowerCase();
+  if (!normalized) return null;
+
+  if (CANONICAL_SET.has(normalized)) {
+    return {
+      canonical: normalized,
+      label: normalized,
+    };
+  }
+
+  const aliasTarget = LANGUAGE_ALIASES.get(normalized);
+  if (aliasTarget && CANONICAL_SET.has(aliasTarget)) {
+    return {
+      canonical: aliasTarget,
+      label: normalized,
+    };
+  }
+
+  return null;
+}
+
+export class CodeHighlightCache {
+  constructor(maxEntries = MAX_CACHE_ENTRIES, maxChars = MAX_CACHE_CHARS) {
+    this.maxEntries = maxEntries;
+    this.maxChars = maxChars;
+    this.map = new Map();
+    this.currentChars = 0;
+  }
+
+  get(key) {
+    if (!this.map.has(key)) return undefined;
+    const value = this.map.get(key);
+    this.map.delete(key);
+    this.map.set(key, value);
+    return value;
+  }
+
+  set(key, value) {
+    const entryChars = key.length + value.length;
+    if (this.map.has(key)) {
+      const oldVal = this.map.get(key);
+      this.currentChars -= (key.length + oldVal.length);
+      this.map.delete(key);
+    }
+    this.currentChars += entryChars;
+    this.map.set(key, value);
+    while (this.map.size > this.maxEntries || this.currentChars > this.maxChars) {
+      const oldestKey = this.map.keys().next().value;
+      if (oldestKey === undefined) break;
+      const oldestVal = this.map.get(oldestKey);
+      this.currentChars -= (oldestKey.length + oldestVal.length);
+      this.map.delete(oldestKey);
+    }
+  }
+
+  clear() {
+    this.map.clear();
+    this.currentChars = 0;
+  }
+
+  get size() {
+    return this.map.size;
+  }
+
+  get totalChars() {
+    return this.currentChars;
+  }
+}
+
+export function createCodeHighlighter(options) {
+  const highlight = options?.highlight;
+  const now = options?.now ?? (() => (typeof performance !== 'undefined' ? performance.now() : Date.now()));
+  const maxBudgetMs = options?.maxBudgetMs ?? DEFAULT_TIME_BUDGET_MS;
+  const windowMs = options?.windowMs ?? DEFAULT_TIME_WINDOW_MS;
+
+  const cache = new CodeHighlightCache();
+
+  // Sliding window execution time tracker
+  // Worst-case main-thread freeze per second:
+  // An attacker sending 200 distinct worst-case blocks in a single message can trigger
+  // at most one block that starts when spentTime < 250ms (e.g. at 249ms plus one block
+  // taking ~60ms), bounding synchronous computation to ~310ms per 1,000ms sliding window.
+  // Once the 250ms budget is reached, subsequent blocks in that window immediately
+  // fall back to plain escaped text (<0.01ms each) without caching the fallback.
+  const budgetEntries = [];
+
+  function getSpentTime(currentTime) {
+    const cutoff = currentTime - windowMs;
+    while (budgetEntries.length > 0 && budgetEntries[0].timestamp <= cutoff) {
+      budgetEntries.shift();
+    }
+    let total = 0;
+    for (let i = 0; i < budgetEntries.length; i++) {
+      total += budgetEntries[i].duration;
+    }
+    return total;
+  }
+
+  function renderCodeBlock(code, rawTag) {
+    const resolved = resolveLanguage(rawTag);
+    const codeString = String(code ?? '');
+
+    let exceedsSize = codeString.length > MAX_HIGHLIGHT_CHARS;
+    if (!exceedsSize) {
+      let lineCount = 1;
+      let currentLineLen = 0;
+      for (let i = 0; i < codeString.length; i++) {
+        const ch = codeString.charCodeAt(i);
+        if (ch === 10) {
+          lineCount++;
+          if (lineCount > MAX_HIGHLIGHT_LINES) {
+            exceedsSize = true;
+            break;
+          }
+          currentLineLen = 0;
+        } else {
+          currentLineLen++;
+          if (currentLineLen > MAX_HIGHLIGHT_LINE_LENGTH) {
+            exceedsSize = true;
+            break;
+          }
+        }
+      }
+    }
+
+    let codeHtml;
+    if (!resolved || exceedsSize || typeof highlight !== 'function') {
+      codeHtml = escapeHtml(codeString);
+    } else {
+      const cacheKey = `${resolved.canonical}:${codeString}`;
+      const cached = cache.get(cacheKey);
+      if (cached !== undefined) {
+        // Cache hit: costs nothing against the sliding time budget
+        codeHtml = cached;
+      } else {
+        const currentTime = now();
+        const spent = getSpentTime(currentTime);
+        if (spent >= maxBudgetMs) {
+          // Budget exhausted: fall back to plain escaped text, do NOT cache
+          codeHtml = escapeHtml(codeString);
+        } else {
+          const t0 = now();
+          try {
+            const highlighted = highlight(codeString, resolved.canonical);
+            codeHtml = typeof highlighted === 'string' ? highlighted : escapeHtml(codeString);
+          } catch {
+            codeHtml = escapeHtml(codeString);
+          }
+          const t1 = now();
+          const duration = Math.max(0, t1 - t0);
+          budgetEntries.push({ timestamp: t0, duration });
+          cache.set(cacheKey, codeHtml);
+        }
+      }
+    }
+
+    const headerContent = resolved
+      ? `<span class="fenced-code-block-lang" data-lang="${escapeAttribute(resolved.label)}"></span><button type="button" class="fenced-code-block-copy" data-code-copy aria-label="Copy code"></button>`
+      : `<button type="button" class="fenced-code-block-copy" data-code-copy aria-label="Copy code"></button>`;
+
+    const langClass = resolved ? ` language-${escapeAttribute(resolved.label)}` : '';
+
+    return `<div class="fenced-code-block"><div class="fenced-code-block-header">${headerContent}</div><pre><code class="fenced-code-block-content${langClass}">${codeHtml}</code></pre></div>`;
+  }
+
+  return {
+    renderCodeBlock,
+    cache,
+    resolveLanguage,
+  };
+}
+
+export async function executeCodeBlockCopy(button, textToCopy, copyFn, copyTimers = new WeakMap()) {
+  let success = false;
+  if (textToCopy !== null && typeof textToCopy === 'string') {
+    try {
+      success = Boolean(await copyFn(textToCopy));
+    } catch {
+      success = false;
+    }
+  }
+
+  // Clear previous timer AFTER the await to avoid timer races on rapid clicks
+  const prevTimer = copyTimers.get(button);
+  if (prevTimer !== undefined) {
+    clearTimeout(prevTimer);
+    copyTimers.delete(button);
+  }
+
+  if (!button.isConnected) return { success, timerId: null };
+
+  if (success) {
+    button.setAttribute('data-copied', 'true');
+    button.setAttribute('aria-label', 'Copied to clipboard');
+  } else {
+    button.setAttribute('data-copied', 'error');
+    button.setAttribute('aria-label', 'Failed to copy to clipboard');
+  }
+
+  const timerId = setTimeout(() => {
+    if (copyTimers.get(button) === timerId) {
+      copyTimers.delete(button);
+    }
+    if (button.isConnected) {
+      button.removeAttribute('data-copied');
+      button.setAttribute('aria-label', 'Copy code');
+    }
+  }, 2000);
+
+  copyTimers.set(button, timerId);
+  return { success, timerId };
+}
+
+export function setupCodeBlockCopyListener(copyFn) {
+  if (typeof document === 'undefined') return () => {};
+
+  const copyTimers = new WeakMap();
+
+  async function handleCopyClick(event) {
+    const target = event?.target;
+    const button = target && typeof target.closest === 'function' ? target.closest('[data-code-copy]') : null;
+    if (!button) return;
+
+    // Prevent default button actions, but do NOT stop propagation so outside-click
+    // listeners (e.g. popover dismissal) still see the event.
+    event.preventDefault();
+
+    const container = button.closest('.fenced-code-block');
+    const codeEl = container?.querySelector('pre code.fenced-code-block-content') || container?.querySelector('code');
+    if (!codeEl) {
+      await executeCodeBlockCopy(button, null, copyFn, copyTimers);
+      return;
+    }
+
+    const textToCopy = codeEl.textContent ?? '';
+    await executeCodeBlockCopy(button, textToCopy, copyFn, copyTimers);
+  }
+
+  document.addEventListener('click', handleCopyClick, true);
+  return () => {
+    document.removeEventListener('click', handleCopyClick, true);
+  };
+}

package/shared/codex-owner-isolation.d.mts

@@ -0,0 +1,34 @@
+export const CODEX_OWNER_FEATURE_OVERRIDES: readonly string[];
+export const LETAGENTS_MCP_SERVER_NAME: "letagents";
+
+export type CodexMcpListRunner = (
+  codexBin: string,
+  args: string[],
+  options: { cwd?: string; env: NodeJS.ProcessEnv },
+) => Promise<string>;
+
+export function codexHomeDirectory(env: NodeJS.ProcessEnv): string;
+export function codexPersonalSkillFiles(env: NodeJS.ProcessEnv): Promise<string[]>;
+export function codexSkillDisableOverride(skillFiles: readonly string[]): string | null;
+export function codexMcpServerDisableOverride(serverNames: readonly string[]): string | null;
+export const runCodexMcpList: CodexMcpListRunner;
+export type CodexMcpServerEntry = { name: string; enabled?: boolean; transport?: unknown; [key: string]: unknown };
+export function listCodexMcpServers(
+  codexBin: string,
+  options: { cwd?: string; env: NodeJS.ProcessEnv; configOverrides: readonly string[] },
+  run?: CodexMcpListRunner,
+): Promise<CodexMcpServerEntry[]>;
+export function assertProjectKeepsLetAgentsServer(
+  inProject: readonly CodexMcpServerEntry[],
+  outsideProject: readonly CodexMcpServerEntry[],
+): void;
+export function listCodexMcpServerNames(
+  codexBin: string,
+  options: { cwd?: string; env: NodeJS.ProcessEnv; configOverrides: readonly string[] },
+  run?: CodexMcpListRunner,
+): Promise<string[]>;
+export function codexOwnerIsolationOverrides(
+  codexBin: string,
+  options: { cwd?: string; env: NodeJS.ProcessEnv; configOverrides?: readonly string[] },
+  run?: CodexMcpListRunner,
+): Promise<string[]>;

package/shared/codex-owner-isolation.mjs

@@ -0,0 +1,210 @@
+import { execFile } from "node:child_process";
+import { readdir, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, parse } from "node:path";
+
+// A Codex app-server that LetAgents launches works for a room, not as the
+// owner, yet it shares the owner's CODEX_HOME so Codex sign-in keeps working.
+// These launch overrides turn the owner's extensions off for that launch only.
+// The owner's config, auth and session history are not modified, and the
+// project's own skills and AGENTS.md still load. Codex has no launch switch
+// for its global AGENTS.md or its saved command rules, so those still reach
+// the agent. Shared by the desktop and the published MCP package, so it uses
+// nothing but Node.
+
+/** Plugins (with their MCP servers and skills), app connectors, computer and browser use, hooks, memories, notifier. */
+export const CODEX_OWNER_FEATURE_OVERRIDES = Object.freeze([
+  "features.plugins=false",
+  "features.apps=false",
+  "features.computer_use=false",
+  "features.browser_use=false",
+  "features.browser_use_external=false",
+  "features.hooks=false",
+  "features.memories=false",
+  "notify=[]",
+]);
+
+/** The room's own MCP server, the one server a LetAgents-launched Codex keeps. */
+export const LETAGENTS_MCP_SERVER_NAME = "letagents";
+
+// `codex mcp list` checks OAuth for HTTP servers, which can take seconds when
+// one is unreachable. A launch waits this long at most, then fails.
+const MCP_LIST_TIMEOUT_MS = 10_000;
+// Codex finds a SKILL.md at most six directories below a skill root.
+const MAX_SKILL_DEPTH = 6;
+const MAX_SKILL_FILES = 1_000;
+const MAX_SKILL_DIRECTORIES = 10_000;
+
+export function codexHomeDirectory(env) {
+  return env.CODEX_HOME?.trim() || join(env.HOME?.trim() || homedir(), ".codex");
+}
+
+/**
+ * SKILL.md files in Codex's user skill roots: CODEX_HOME/skills, apart from
+ * Codex's own bundled `.system` skills, and ~/.agents/skills. Both are
+ * searched to the same depth as Codex, including inside other skills.
+ */
+export async function codexPersonalSkillFiles(env) {
+  const files = [];
+  const visited = new Set();
+  const walk = async (directory, depth) => {
+    if (depth > MAX_SKILL_DEPTH || files.length >= MAX_SKILL_FILES || visited.size >= MAX_SKILL_DIRECTORIES) return;
+    let entries;
+    try {
+      const canonical = await realpath(directory);
+      if (visited.has(canonical)) return;
+      visited.add(canonical);
+      entries = await readdir(directory);
+    } catch {
+      return;
+    }
+    for (const name of entries.sort()) {
+      if (files.length >= MAX_SKILL_FILES) return;
+      // Hidden entries include Codex's bundled `.system` skills.
+      if (name.startsWith(".")) continue;
+      const path = join(directory, name);
+      let entry;
+      try {
+        entry = await stat(path);
+      } catch {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        await walk(path, depth + 1);
+      } else if (name === "SKILL.md" && entry.isFile()) {
+        files.push(path);
+        try {
+          const real = await realpath(path);
+          if (real !== path) files.push(real);
+        } catch {
+          // The listed path is enough when it cannot be resolved.
+        }
+      }
+    }
+  };
+  await walk(join(codexHomeDirectory(env), "skills"), 0);
+  await walk(join(env.HOME?.trim() || homedir(), ".agents", "skills"), 0);
+  return [...new Set(files)];
+}
+
+export function codexSkillDisableOverride(skillFiles) {
+  if (!skillFiles.length) return null;
+  const entries = skillFiles.map((path) => `{ path = ${JSON.stringify(path)}, enabled = false }`);
+  return `skills.config=[${entries.join(", ")}]`;
+}
+
+/**
+ * Codex's dotted -c paths split on every dot, even inside quotes, so a server
+ * name with a dot cannot be addressed that way. A parent-table override is
+ * merged into the configured servers and names each one exactly.
+ */
+export function codexMcpServerDisableOverride(serverNames) {
+  const names = [...new Set(serverNames)].filter((name) => name !== LETAGENTS_MCP_SERVER_NAME).sort();
+  if (!names.length) return null;
+  return `mcp_servers={ ${names.map((name) => `${JSON.stringify(name)} = { enabled = false }`).join(", ")} }`;
+}
+
+export function runCodexMcpList(codexBin, args, options) {
+  return new Promise((resolve, reject) => {
+    const child = execFile(codexBin, args, {
+      ...(options.cwd ? { cwd: options.cwd } : {}),
+      env: options.env,
+      encoding: "utf8",
+      timeout: MCP_LIST_TIMEOUT_MS,
+      killSignal: "SIGKILL",
+      maxBuffer: 4 * 1024 * 1024,
+    }, (error, stdout) => {
+      if (error) reject(error);
+      else resolve(String(stdout));
+    });
+    child.stdin?.end();
+  });
+}
+
+/**
+ * Every MCP server a launch would configure, as Codex itself resolves them
+ * from the owner's config and any trusted project config. Pass the launch's
+ * own overrides so the list matches what the app-server will see.
+ */
+export async function listCodexMcpServers(codexBin, options, run = runCodexMcpList) {
+  let output;
+  try {
+    output = await run(codexBin, [
+      "mcp", "list", "--json",
+      ...options.configOverrides.flatMap((override) => ["-c", override]),
+    ], { cwd: options.cwd, env: options.env });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message.split("\n")[0] : String(error);
+    throw new Error(
+      `Codex could not list its MCP servers, so LetAgents will not start it with the owner's own tools: ${detail}`,
+    );
+  }
+  let parsed = null;
+  try {
+    parsed = JSON.parse(output);
+  } catch {
+    // Rejected below.
+  }
+  if (!Array.isArray(parsed) || !parsed.every((entry) => entry && typeof entry === "object" && typeof entry.name === "string")) {
+    throw new Error("Codex returned an unreadable MCP server list, so LetAgents will not start it.");
+  }
+  return parsed;
+}
+
+export async function listCodexMcpServerNames(codexBin, options, run = runCodexMcpList) {
+  return (await listCodexMcpServers(codexBin, options, run)).map((entry) => entry.name);
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+
+/** How Codex would start a server: its transport (command, args, env, URL...) and whether it is on. */
+function serverLaunchShape(entry) {
+  return entry ? stableJson({ enabled: entry.enabled ?? null, transport: entry.transport ?? null }) : null;
+}
+
+/**
+ * The LetAgents server keeps the owner's credentials, so a project must not
+ * change how it starts. Codex merges a trusted project's config into it key by
+ * key: a project could swap its args for its own script, or add NODE_OPTIONS,
+ * and run that with the owner's LETAGENTS_TOKEN. A launch override cannot
+ * remove merged keys, so such a launch is refused instead.
+ */
+export function assertProjectKeepsLetAgentsServer(inProject, outsideProject) {
+  const find = (entries) => entries.find((entry) => entry.name === LETAGENTS_MCP_SERVER_NAME);
+  if (serverLaunchShape(find(inProject)) !== serverLaunchShape(find(outsideProject))) {
+    throw new Error(
+      "This project's Codex config changes the LetAgents MCP server, so LetAgents will not start Codex here. "
+      + "Remove [mcp_servers.letagents] from the project's .codex/config.toml, or stop trusting the project in Codex.",
+    );
+  }
+}
+
+/**
+ * Every override a LetAgents launch adds: the features, each personal skill,
+ * and every MCP server but LetAgents. `cwd` is where the app-server starts and
+ * `configOverrides` are the launch's own (for example the room's server), used to
+ * list servers as the launch will see them. A launch that cannot list its
+ * servers, or whose project changes the LetAgents server, fails here.
+ */
+export async function codexOwnerIsolationOverrides(codexBin, options, run = runCodexMcpList) {
+  const listOptions = {
+    env: options.env,
+    configOverrides: [...(options.configOverrides ?? []), ...CODEX_OWNER_FEATURE_OVERRIDES],
+  };
+  const [inProject, outsideProject, skillFiles] = await Promise.all([
+    listCodexMcpServers(codexBin, { ...listOptions, cwd: options.cwd }, run),
+    // Outside any project only the owner's own config applies.
+    options.cwd ? listCodexMcpServers(codexBin, { ...listOptions, cwd: parse(options.cwd).root || "/" }, run) : null,
+    codexPersonalSkillFiles(options.env),
+  ]);
+  if (outsideProject) assertProjectKeepsLetAgentsServer(inProject, outsideProject);
+  const skills = codexSkillDisableOverride(skillFiles);
+  const servers = codexMcpServerDisableOverride(inProject.map((entry) => entry.name));
+  return [...CODEX_OWNER_FEATURE_OVERRIDES, ...(skills ? [skills] : []), ...(servers ? [servers] : [])];
+}

package/shared/message-link-preview-store.d.mts

@@ -0,0 +1,10 @@
+import type { LinkPreviewReference, MessageLinkPreview, MessageLinkPreviewsResponse } from "./message-link-previews.mjs";
+export function createMessageLinkPreviewStore(options: {
+  load(references: LinkPreviewReference[]): Promise<MessageLinkPreviewsResponse>;
+  onChange?(): void; refreshDelayMs?: number;
+}): {
+  track(message: { id: string; references: LinkPreviewReference[] }): () => void;
+  get(messageId: string): MessageLinkPreview[];
+  refresh(): Promise<void>;
+  reset(): void;
+};

package/shared/message-link-preview-store.mjs

@@ -0,0 +1,77 @@
+import { LINK_PREVIEW_BATCH_LIMIT, linkPreviewKey } from "./message-link-previews.mjs";
+
+/** Separate from messages: one bounded read chain for the references rendered in a room. */
+export function createMessageLinkPreviewStore({ load, onChange, refreshDelayMs = 50 }) {
+  let epoch = 0;
+  let tracked = new Map();
+  let previews = new Map();
+  let timer = null;
+  let reading = null;
+  function schedule() {
+    if (timer !== null) return;
+    timer = setTimeout(() => { timer = null; void refresh(); }, refreshDelayMs);
+  }
+  function track(message) {
+    if (!message.references.length) return () => {};
+    const token = Symbol();
+    tracked.set(token, message);
+    onChange?.();
+    if (message.references.some((ref) => !previews.has(linkPreviewKey(ref)))) schedule();
+    return () => {
+      tracked.delete(token);
+      const used = new Set([...tracked.values()].flatMap((entry) => entry.references.map(linkPreviewKey)));
+      for (const key of previews.keys()) if (!used.has(key)) previews.delete(key);
+    };
+  }
+  function get(messageId) {
+    const message = [...tracked.values()].find((entry) => entry.id === messageId);
+    return (message?.references ?? []).flatMap((ref) => previews.get(linkPreviewKey(ref)) ?? []);
+  }
+  function refresh() {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+    if (reading) { reading.again = true; return reading.promise; }
+    const startedIn = epoch;
+    const cycle = { again: false, promise: null };
+    reading = cycle;
+    cycle.promise = (async () => {
+      do {
+        cycle.again = false;
+        const unique = new Map([...tracked.values()].flatMap((entry) => entry.references.map((ref) => [linkPreviewKey(ref), ref])));
+        const references = [...unique.values()];
+        for (let i = 0; i < references.length; i += LINK_PREVIEW_BATCH_LIMIT) {
+          if (startedIn !== epoch) return;
+          const batch = references.slice(i, i + LINK_PREVIEW_BATCH_LIMIT);
+          try {
+            const result = await load(batch);
+            if (startedIn !== epoch) return;
+            const values = new Map(result.previews.map((preview) => [linkPreviewKey(preview), preview]));
+            let changed = false;
+            const used = new Set([...tracked.values()].flatMap((entry) => entry.references.map(linkPreviewKey)));
+            for (const ref of batch) {
+              const key = linkPreviewKey(ref);
+              if (!used.has(key)) continue;
+              const next = values.get(key) ?? null;
+              if (JSON.stringify(previews.get(key) ?? null) !== JSON.stringify(next)) changed = true;
+              previews.set(key, next);
+            }
+            if (changed) onChange?.();
+          } catch {
+            // Retry on the next stream update, reconnect or registration.
+          }
+        }
+      } while (cycle.again && startedIn === epoch);
+    })().finally(() => { if (reading === cycle) reading = null; });
+    return cycle.promise;
+  }
+  function reset() {
+    epoch++;
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+    reading = null;
+    tracked = new Map();
+    previews = new Map();
+    onChange?.();
+  }
+  return { track, get, refresh, reset };
+}

package/shared/message-link-previews.d.mts

@@ -0,0 +1,16 @@
+export const LINK_PREVIEW_BATCH_LIMIT: 50;
+export const LINK_PREVIEW_MESSAGE_LIMIT: 3;
+export interface LinkPreviewReference { kind: "pull" | "issue"; number: number }
+export interface GitHubLinkReference extends LinkPreviewReference { repository: string; url: string }
+export interface MessageLinkPreview extends GitHubLinkReference { title: string; state: "merged" | "closed" | "draft" | "open" }
+export interface MessageLinkPreviewsResponse { room_id: string; previews: MessageLinkPreview[]; available?: boolean }
+export function parseGitHubLinkReference(value: unknown): GitHubLinkReference | null;
+export function normalizePreviewRepository(value: unknown): string | null;
+export function linkPreviewKey(reference: LinkPreviewReference): string;
+export function parseLinkPreviewReferences(value: unknown): LinkPreviewReference[] | null;
+export function eligibleLinkPreviewReferences(urls: readonly string[], repository: string | null): LinkPreviewReference[];
+export function linkPreviewState(state: unknown, metadata?: { merged?: unknown; draft?: unknown } | null): MessageLinkPreview["state"] | null;
+export function linkPreviewPresentation(preview: MessageLinkPreview): {
+  kind: "pull-request" | "issue"; kindLabel: string; tone: "emerald" | "slate" | "amber" | "violet";
+  statusLabel: string; headline: string; detail: null; repository: string; taskId: null; url: string; urlLabel: string;
+};