letagents 0.12.34 → 0.12.35

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

package/shared/message-link-previews.mjs

@@ -0,0 +1,70 @@
+export const LINK_PREVIEW_BATCH_LIMIT = 50;
+export const LINK_PREVIEW_MESSAGE_LIMIT = 3;
+
+export function parseGitHubLinkReference(value) {
+  if (typeof value !== "string" || value.length > 2048) return null;
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "https:" || url.hostname !== "github.com" || url.port || url.username || url.password) return null;
+    const match = /^\/([\w.-]+)\/([\w.-]+)\/(pull|issues)\/([1-9]\d*)\/?$/.exec(url.pathname);
+    if (!match) return null;
+    const number = Number(match[4]);
+    if (!Number.isSafeInteger(number)) return null;
+    const repository = `${match[1]}/${match[2]}`.toLowerCase();
+    const kind = match[3] === "pull" ? "pull" : "issue";
+    return { repository, kind, number, url: `https://github.com/${repository}/${match[3]}/${number}` };
+  } catch { return null; }
+}
+
+export function normalizePreviewRepository(value) {
+  if (typeof value !== "string") return null;
+  const name = value.replace(/^https:\/\//i, "").replace(/^github\.com\//i, "").replace(/\/$/, "");
+  return /^[\w.-]+\/[\w.-]+$/.test(name) ? name.toLowerCase() : null;
+}
+
+export function linkPreviewKey(reference) { return `${reference.kind}:${reference.number}`; }
+
+export function parseLinkPreviewReferences(value) {
+  if (!Array.isArray(value) || value.length > LINK_PREVIEW_BATCH_LIMIT) return null;
+  const references = new Map();
+  for (const ref of value) {
+    if (!ref || typeof ref !== "object" || Object.keys(ref).length !== 2
+      || !["pull", "issue"].includes(ref.kind) || !Number.isSafeInteger(ref.number) || ref.number <= 0) return null;
+    references.set(linkPreviewKey(ref), { kind: ref.kind, number: ref.number });
+  }
+  return [...references.values()];
+}
+
+export function eligibleLinkPreviewReferences(urls, repository) {
+  const repo = normalizePreviewRepository(repository);
+  if (!repo) return [];
+  const refs = new Map();
+  for (const url of urls) {
+    const ref = parseGitHubLinkReference(url);
+    if (!ref || ref.repository !== repo) continue;
+    refs.set(linkPreviewKey(ref), { kind: ref.kind, number: ref.number });
+    if (refs.size === LINK_PREVIEW_MESSAGE_LIMIT) break;
+  }
+  return [...refs.values()];
+}
+
+/** State is a last-observed snapshot, never a request to GitHub. */
+export function linkPreviewState(state, metadata) {
+  if (state === "merged" || metadata?.merged === true) return "merged";
+  if (state === "closed") return "closed";
+  if (state === "draft" || state === "open" && metadata?.draft === true) return "draft";
+  return state === "open" ? "open" : null;
+}
+
+export function linkPreviewPresentation(preview) {
+  const pull = preview.kind === "pull";
+  return {
+    kind: pull ? "pull-request" : "issue",
+    kindLabel: pull ? "Pull request" : "Issue",
+    tone: preview.state === "merged" ? "emerald" : preview.state === "closed" ? "slate" : preview.state === "draft" ? "amber" : "violet",
+    statusLabel: preview.state,
+    headline: `#${preview.number} ${preview.title}`,
+    detail: null, repository: preview.repository, taskId: null,
+    url: preview.url, urlLabel: pull ? "Open pull request" : "Open issue",
+  };
+}

package/shared/message-pin-store.d.mts

@@ -0,0 +1,20 @@
+import type { MessagePin, MessagePinsResponse } from "./message-pins.mjs";
+export interface MessagePinState {
+  pins: MessagePin[];
+  available: boolean;
+  loading: boolean;
+  pending: string | null;
+  error: string | null;
+}
+export function createMessagePinStore<Context>(options: {
+  load(context: Context): Promise<MessagePinsResponse>;
+  mutate(context: Context, messageId: string, pinned: boolean): Promise<unknown>;
+  onChange?(state: MessagePinState): void;
+  onError?(message: string): void;
+}): {
+  readonly state: MessagePinState;
+  reset(context?: Context | null): void;
+  refresh(): Promise<unknown>;
+  setPinned(messageId: string, pinned: boolean): Promise<unknown>;
+  dispose(): void;
+};

package/shared/message-pin-store.mjs

@@ -0,0 +1,102 @@
+import { isPinMessageId, MESSAGE_PIN_LIMIT } from "./message-pins.mjs";
+
+/** One authoritative, bounded room list. All async work is fenced by context. */
+export function createMessagePinStore(options) {
+  let epoch = 0;
+  let generation = 0;
+  let context = null;
+  let disposed = false;
+  let reading = null;
+  let queued = false;
+  let mutation = null;
+  let state = { pins: [], available: false, loading: false, pending: null, error: null };
+  const changed = () => options.onChange?.(state);
+  function reset(next = null) {
+    epoch++;
+    generation++;
+    context = next;
+    reading = null;
+    mutation = null;
+    queued = false;
+    state = { pins: [], available: false, loading: false, pending: null, error: null };
+    changed();
+    if (next && !disposed) void refresh();
+  }
+  async function refresh() {
+    if (!context || disposed) return;
+    if (reading || mutation) { queued = true; return reading ?? mutation; }
+    const ownEpoch = epoch;
+    const ownGeneration = generation;
+    const ownContext = context;
+    state = { ...state, loading: true };
+    changed();
+    const job = Promise.resolve().then(async () => {
+      if (ownEpoch !== epoch || disposed) return;
+      try {
+        const response = await options.load(ownContext);
+        if (ownEpoch !== epoch || ownGeneration !== generation || disposed) return;
+        const seen = new Set();
+        const pins = (response.pins ?? []).filter((pin) => {
+          if (!isPinMessageId(pin.message_id) || seen.has(pin.message_id)) return false;
+          seen.add(pin.message_id);
+          return true;
+        }).slice(0, MESSAGE_PIN_LIMIT);
+        state = { ...state, pins, available: response.available !== false, error: null, pending: null };
+      } catch (error) {
+        if (ownEpoch === epoch && ownGeneration === generation && !disposed) {
+          state = { ...state, pending: null, error: error instanceof Error ? error.message : "Pins could not be loaded." };
+        }
+      } finally {
+        if (ownEpoch === epoch && !disposed) {
+          reading = null;
+          state = { ...state, loading: false };
+          changed();
+          if (queued && !mutation) { queued = false; void refresh(); }
+        }
+      }
+    });
+    reading = job;
+    return job;
+  }
+  async function setPinned(messageId, pinned) {
+    if (disposed || !context || !state.available || mutation || state.pending || !isPinMessageId(messageId)) return;
+    const ownEpoch = epoch;
+    const ownContext = context;
+    // A read started before this write is no longer authoritative.
+    generation++;
+    state = { ...state, pending: messageId, error: null };
+    changed();
+    const job = Promise.resolve().then(async () => {
+      if (ownEpoch !== epoch || disposed) return;
+      let succeeded = false;
+      try {
+        await options.mutate(ownContext, messageId, pinned);
+        succeeded = true;
+      } catch (error) {
+        if (ownEpoch === epoch && !disposed) {
+          const message = error instanceof Error ? error.message : "Pins could not be saved.";
+          state = { ...state, error: message };
+          options.onError?.(message);
+        }
+      } finally {
+        if (ownEpoch === epoch && !disposed) {
+          mutation = null;
+          state = { ...state, pending: succeeded ? messageId : null };
+          changed();
+        }
+      }
+      if (ownEpoch === epoch && !disposed && (succeeded || queued)) {
+        // If an older read is still running it must finish before the repair.
+        queued = false;
+        await refresh();
+      }
+    });
+    mutation = job;
+    return job;
+  }
+  return {
+    get state() { return state; },
+    reset, refresh, setPinned,
+    dispose() { disposed = true; reset(); },
+  };
+}

package/shared/message-pins.d.mts

@@ -0,0 +1,25 @@
+export const MESSAGE_PIN_LIMIT: 50;
+export const MESSAGE_PIN_SNIPPET_LENGTH: 240;
+export const MESSAGE_PIN_LIMIT_NOTICE: string;
+export function isPinMessageId(value: unknown): value is string;
+export function messagePinSnippet(text: string, displayText?: string | null): string;
+export interface MessagePin {
+  message_id: string;
+  sender: string;
+  source: string | null;
+  timestamp: string;
+  thread_root_id: string | null;
+  snippet: string;
+  pinned_at: string;
+  pinned_by: { login: string; name: string; avatar_url: string | null };
+}
+export interface MessagePinsResponse {
+  room_id: string;
+  pins: MessagePin[];
+  available?: boolean;
+}
+export interface MessagePinMutationResponse {
+  room_id: string;
+  message_id: string;
+  changed: boolean;
+}

package/shared/message-pins.mjs

@@ -0,0 +1,16 @@
+export const MESSAGE_PIN_LIMIT = 50;
+export const MESSAGE_PIN_SNIPPET_LENGTH = 240;
+export const MESSAGE_PIN_LIMIT_NOTICE = "This room already has 50 pinned messages. Unpin a message first.";
+
+export function isPinMessageId(value) {
+  return typeof value === "string" && /^msg_[1-9]\d*$/.test(value)
+    && Number(value.slice(4)) <= 2147483647;
+}
+
+/** Match the clients' displayed-text fallback; return text, never HTML. */
+export function messagePinSnippet(text, displayText) {
+  const chars = Array.from((displayText || text || "").replace(/\s+/gu, " ").trim());
+  return chars.length > MESSAGE_PIN_SNIPPET_LENGTH
+    ? chars.slice(0, MESSAGE_PIN_SNIPPET_LENGTH - 1).join("") + "…"
+    : chars.join("");
+}

package/shared/message-reaction-store.d.mts

@@ -0,0 +1,51 @@
+import type { MessageReaction, MessageReactor } from "./message-reactions.mjs";
+
+export interface MessageReactionStoreOptions {
+  /**
+   * Read the reactions of the messages from `firstMessageId` to `lastMessageId`
+   * (at most MESSAGE_REACTION_RANGE_MAX_SPAN apart). The answer may stop early
+   * and name the message to continue from.
+   */
+  load(firstMessageId: string, lastMessageId: string): Promise<{
+    reactions: Record<string, unknown>;
+    viewer_reactions?: Record<string, unknown>;
+    next_first_message_id?: string | null;
+  }>;
+  /** Add (`reacted: true`) or remove the viewer's reaction; resolves with the message's reactions. */
+  mutate(messageId: string, emoji: string, reacted: boolean): Promise<{ reactions: unknown }>;
+  /** The signed-in person, or null when nobody can react. */
+  viewer(): MessageReactor | null;
+  onChange?(): void;
+  onError?(error: unknown, during: "load" | "mutate"): void;
+  /** How long newly tracked messages are gathered before one read confirms them. */
+  refreshDelayMs?: number;
+}
+
+export interface MessageReactionStore {
+  /** A stable empty list when the message has no reactions. */
+  get(messageId: string): readonly MessageReaction[];
+  viewerReacted(messageId: string, emoji: string): boolean;
+  /**
+   * A rendered message registers itself; the returned function unregisters it.
+   * Its reactions start from what it carried and are confirmed by a read a
+   * moment after it is first tracked.
+   */
+  track(message: { id: string; reactions?: unknown }): () => void;
+  /** Re-read the reactions of every message on screen. */
+  refresh(): Promise<void>;
+  /** Add the viewer's reaction, or remove it if it is already there. */
+  toggle(messageId: string, emoji: string): Promise<void>;
+  /**
+   * Forget everything. With `keepTracked` the messages on screen stay
+   * registered (the signed-in person changed); without it they are dropped
+   * too (the room changed).
+   */
+  reset(options?: { keepTracked?: boolean }): void;
+}
+
+/**
+ * The client-side state of a room's reactions, shared by the desktop and web
+ * apps: seeded from the messages on screen, confirmed and kept current by
+ * reading the server.
+ */
+export function createMessageReactionStore(options: MessageReactionStoreOptions): MessageReactionStore;