@alia.onl/sdk 15.7.0 → 19.0.0

package/src/runtime/thread/thread-history.ts

@@ -0,0 +1,139 @@
+import type { Message } from '../types';
+
+/**
+ * The history of a thread: everything said before the stretch on screen.
+ *
+ * ## A thread is many conversations, and the screen only holds one
+ *
+ * `/@pepe` shows one continuous history, but underneath it is a run of ordinary
+ * conversations sharing an `agentId`, and the chat screen is streaming into the
+ * most recent one. `GET /agents/thread/:username/messages` is what crosses
+ * those seams; this module turns its pages into the list that goes above the
+ * live messages, and says where the joins are.
+ *
+ * Everything here is pure. The fetching lives in `use-thread-history.ts` and
+ * `use-thread-search.ts`; the scrolling and the anchoring are Bloom's `AiChatThread`'s.
+ */
+
+/**
+ * A message as the thread endpoint sends it.
+ *
+ * Two fields more than an ordinary message, and neither is decorative:
+ * `conversationId` is the only thing a client can draw a seam from — there is
+ * no table of breaks — and `cursor` addresses this exact message, which is what
+ * makes both paging and jumping to a search hit possible.
+ *
+ * `id` is OPTIONAL on the wire, because it is the CLIENT's id and a message
+ * written by the server never had one.
+ */
+export interface WireThreadMessage extends Omit<Message, 'id'> {
+  id?: string;
+  conversationId: string;
+  cursor: string;
+}
+
+/** What is behind the conversation on screen: the rest of an agent's thread. */
+export interface ThreadHistory {
+  /** Everything said before the conversation on screen, oldest first. */
+  messages: ThreadMessage[];
+  /** A page is on its way; the reader is at the top waiting for it. */
+  loading: boolean;
+  /** Ask for the page above. Absent where nothing older remains, which also turns the anchor off. */
+  loadMore?: () => void;
+}
+
+/**
+ * One hit of a search in a thread. `messageId` is the client's id, which a message the server
+ * wrote has none of.
+ */
+export interface ThreadSearchHit {
+  messageId: string | null;
+  conversationId: string;
+  role: string;
+  snippet: string;
+  createdAt: string;
+  /** Where this message is, in the only form that can be asked for. */
+  cursor: string;
+}
+
+/** One page of history, oldest-first, with the cursor for the page above it. */
+export interface ThreadPage {
+  messages: readonly WireThreadMessage[];
+  /** `null` when nothing older remains. Never inferred from a page's length. */
+  nextCursor: string | null;
+}
+
+/** A history message, once it is sure to have an id to be keyed and voted by. */
+export interface ThreadMessage extends Message {
+  conversationId: string;
+  cursor: string;
+}
+
+/**
+ * The pages, flattened into the messages that go ABOVE the live conversation.
+ *
+ * Two orderings meet here and they run opposite ways: pages arrive newest-first
+ * (each one is the window before the last), while the messages inside a page
+ * are oldest-first. So the pages are walked backwards and their contents
+ * forwards, which is what puts the whole thing in reading order.
+ *
+ * **The active stretch is dropped.** Its messages are already on screen, held
+ * by the streaming hook, and they are the only ones that can still change —
+ * keeping the endpoint's copy too would show every one of them twice and freeze
+ * the duplicate at the state it was fetched in. Dropping them here is also what
+ * makes starting a new stretch work for free: the messages of the conversation
+ * that was active a moment ago stop matching, so they reappear as history
+ * without a second request.
+ *
+ * The cursor stands in for a missing id. A server-written message has no client
+ * id, `id` is what the list keys on and what the vote URL carries, and a cursor
+ * is unique to one message by construction.
+ */
+export function threadHistory(
+  pages: readonly ThreadPage[],
+  activeConversationId: string,
+): ThreadMessage[] {
+  const history: ThreadMessage[] = [];
+  for (let page = pages.length - 1; page >= 0; page -= 1) {
+    for (const message of pages[page].messages) {
+      if (message.conversationId === activeConversationId) continue;
+      history.push({ ...message, id: message.id ?? message.cursor });
+    }
+  }
+  return history;
+}
+
+/**
+ * Which messages BEGIN a new conversation, keyed by id.
+ *
+ * A seam is deduced from the data — the conversation a message belongs to
+ * changed — and never from elapsed time. "More than N hours passed" is the
+ * tempting version and it lies the day somebody returns a week later to finish
+ * the same thought: the model is still being given that conversation, so the
+ * screen would draw a break where the context has none.
+ *
+ * The topmost loaded message never carries one, deliberately: whether a break
+ * sits above it is a fact about the page that has not been loaded yet. It
+ * appears when that page arrives, which is the only moment it is known.
+ *
+ * The live messages are one stretch, so at most one seam concerns them — above
+ * the first — and it is drawn only when there is history above to be separated
+ * from.
+ */
+export function threadSeamIds(
+  history: readonly ThreadMessage[],
+  live: readonly { id: string }[],
+  activeConversationId: string,
+): Set<string> {
+  const seams = new Set<string>();
+  let previous: string | null = null;
+  for (const message of history) {
+    if (previous !== null && message.conversationId !== previous) seams.add(message.id);
+    previous = message.conversationId;
+  }
+  const firstLive = live[0];
+  if (firstLive !== undefined && previous !== null && previous !== activeConversationId) {
+    seams.add(firstLive.id);
+  }
+  return seams;
+}

package/src/runtime/thread/timeline.ts

@@ -0,0 +1,202 @@
+import type { Message } from '../types';
+
+/**
+ * The chat timeline as data: which rows are mounted, which just arrived, and
+ * which facts about the list a streamed token can and cannot change.
+ *
+ * Everything here is pure. `hooks/useTimelineWindow.ts` holds the state
+ * and talks to the thread; `components/thread/AliaThread.tsx` draws the rows.
+ *
+ * ## Why a paged window and not virtualization
+ *
+ * Bloom's `AiChatThread` is a plain `ScrollView` on native and the document on
+ * web, with no virtualization and no `scrollToIndex` (#608, gap 3 in
+ * `docs/bloom-adoption.mdx`). A spacer-based virtualizer on top of it would
+ * swap estimated heights for measured ones ABOVE the reader, and the thread
+ * only compensates growth it asked for — so every estimate that was wrong
+ * would move the text being read. What the thread does anchor exactly is a
+ * page landing above after `onStartReached`, and that is the one move this
+ * window makes: it mounts the newest rows, and reveals older ones a page at a
+ * time when the reader comes near the top, through the same anchored growth
+ * history paging already uses. Rows are only ever dropped from the top while
+ * the reader is at the bottom, where nothing above them is on screen.
+ */
+
+/** How many rows a thread opens with, counted from the newest. */
+export const INITIAL_ROWS = 40;
+/** How many older rows each approach to the top reveals. */
+export const PAGE_ROWS = 30;
+/** Rows kept above a cursor-jump target, so it does not land on the window's edge. */
+export const FOCUS_MARGIN = 5;
+/**
+ * How far past its opening size the window may grow before it is folded back.
+ * Folding is only done at the bottom with no turn in flight, so a reader who
+ * went up a long way does not keep every row they passed mounted forever.
+ */
+export const COLLAPSE_AFTER = INITIAL_ROWS + 2 * PAGE_ROWS;
+
+/**
+ * Where the mounted range starts.
+ *
+ *  - `tail`: the newest `INITIAL_ROWS`. Only held until the rows are known;
+ *    the hook pins it to a row as soon as there are rows, so rows appended by
+ *    a turn grow the window instead of sliding it.
+ *  - `top`: from the first row loaded. Set when the reader has reached the top
+ *    and asked for history, so the page that lands is shown.
+ *  - `row`: from this row, by id — ids survive rows being added on either side.
+ */
+export type TimelineAnchor = { kind: 'tail' } | { kind: 'top' } | { kind: 'row'; id: string };
+
+export const TAIL: TimelineAnchor = Object.freeze({ kind: 'tail' });
+export const TOP: TimelineAnchor = Object.freeze({ kind: 'top' });
+
+/** The index of the first mounted row. */
+export function resolveStart(
+  anchor: TimelineAnchor,
+  ids: readonly string[],
+  focusIndex = -1,
+): number {
+  let start: number;
+  if (anchor.kind === 'top') start = 0;
+  else if (anchor.kind === 'row') {
+    const index = ids.indexOf(anchor.id);
+    // A row that is gone (a refetched history, a replaced conversation) falls
+    // back to the newest page rather than to everything.
+    start = index === -1 ? tailStart(ids.length) : index;
+  } else start = tailStart(ids.length);
+  // A jump's target is always mounted, with a few rows of context above it.
+  if (focusIndex !== -1) start = Math.min(start, Math.max(0, focusIndex - FOCUS_MARGIN));
+  return start;
+}
+
+function tailStart(count: number): number {
+  return Math.max(0, count - INITIAL_ROWS);
+}
+
+/** The anchor that keeps exactly the rows mounted now, from the row at `start`. */
+export function pinAnchor(ids: readonly string[], start: number): TimelineAnchor {
+  if (start <= 0 || ids.length === 0) return TOP;
+  return { kind: 'row', id: ids[start] };
+}
+
+/**
+ * The reader came near the top: one more page of the rows already loaded, or,
+ * with none left above, `null` — the thread's own history is what comes next.
+ */
+export function revealAbove(ids: readonly string[], start: number): TimelineAnchor | null {
+  if (start <= 0) return null;
+  return pinAnchor(ids, Math.max(0, start - PAGE_ROWS));
+}
+
+/** Fold a window that grew back to its opening size, or `null` if it has not grown enough. */
+export function collapseToTail(ids: readonly string[], start: number): TimelineAnchor | null {
+  if (ids.length - start <= COLLAPSE_AFTER) return null;
+  return pinAnchor(ids, tailStart(ids.length));
+}
+
+/**
+ * The facts about a message the timeline's derived data is built from — the
+ * day separators, the seams, the turn timings, which answer is the last of
+ * Alia's — and nothing a token changes.
+ */
+type Shape = Pick<Message, 'id' | 'role' | 'createdAt' | 'agentInfo'>;
+
+function sameShape(a: Shape, b: Shape): boolean {
+  return (
+    a === b ||
+    (a.id === b.id &&
+      a.role === b.role &&
+      a.createdAt === b.createdAt &&
+      a.agentInfo?.id === b.agentInfo?.id)
+  );
+}
+
+/**
+ * Whether two versions of the list differ only in what their messages SAY.
+ *
+ * A streamed token replaces the last message object and the array around it,
+ * so identity alone says "changed" twenty times a second. This compares the
+ * fields the derived data reads; the per-element check is a pointer comparison
+ * for every message but the one being written, which is why it costs next to
+ * nothing where recomputing the derivations cost a pass over the whole thread.
+ */
+export function sameTimelineShape(previous: readonly Shape[], next: readonly Shape[]): boolean {
+  if (previous === next) return true;
+  if (previous.length !== next.length) return false;
+  for (let i = 0; i < next.length; i += 1) {
+    if (!sameShape(previous[i], next[i])) return false;
+  }
+  return true;
+}
+
+/**
+ * The ids that ARRIVED in this render — the rows that may animate in.
+ *
+ * Not "every id the last render did not have". Three things change the list
+ * without anything arriving, and each would otherwise replay every message as
+ * if it had just been said:
+ *
+ *  - the first render of a screen: everything on it is already there;
+ *  - switching conversation in place: the list is REPLACED, so nothing it
+ *    shares with the last one is the tell;
+ *  - a conversation's messages landing after its load: the list fills from
+ *    empty in one batch, where a send adds a question and the answer's
+ *    placeholder — never more than two.
+ */
+export function arrivedIds(
+  previous: readonly string[] | null,
+  previousLoading: boolean,
+  next: readonly { id: string }[],
+): ReadonlySet<string> {
+  if (previous === null || previousLoading) return EMPTY_IDS;
+  const known = new Set(previous);
+  const arrived = next.filter((m) => !known.has(m.id));
+  if (arrived.length === 0) return EMPTY_IDS;
+  const replaced = previous.length > 0 && arrived.length === next.length;
+  const loaded = previous.length === 0 && arrived.length > 2;
+  if (replaced || loaded) return EMPTY_IDS;
+  return new Set(arrived.map((m) => m.id));
+}
+
+const EMPTY_IDS: ReadonlySet<string> = new Set();
+
+/**
+ * Where the reader was in a conversation, kept for the session so returning to
+ * it lands there instead of at whatever the scroller last held.
+ *
+ * `probeId` is a row that was mounted when this was saved. The position is only
+ * restored once that row is on screen again, because until then the list may
+ * still be the previous conversation's — the streaming hook swaps its messages
+ * in an effect, a render after the conversation id changes.
+ */
+export interface TimelinePosition {
+  anchor: TimelineAnchor;
+  /** px from the thread's top, in the frame `scrollToOffset` takes. */
+  offset: number;
+  atBottom: boolean;
+  probeId: string;
+}
+
+/**
+ * The session's saved positions, by conversation. Never persisted: a reload
+ * opens at the newest turn. Not partitioned by account either, because a
+ * conversation id belongs to one account and an offset says nothing about what
+ * the conversation contains.
+ */
+export class TimelinePositions {
+  private readonly positions = new Map<string, TimelinePosition>();
+
+  save(key: string, position: TimelinePosition): void {
+    this.positions.set(key, position);
+  }
+
+  read(key: string): TimelinePosition | undefined {
+    return this.positions.get(key);
+  }
+
+  clear(): void {
+    this.positions.clear();
+  }
+}
+
+export const timelinePositions = new TimelinePositions();

package/src/runtime/thread/title-tags.ts

@@ -0,0 +1,8 @@
+// Known translations of "TITLE" that LLMs may produce
+const TAG = String.raw`ALIA_TITLE|TITLE|TÍTULO|TITRE|TITOLO|TITEL|ЗАГОЛОВОК`;
+
+/** Matches complete [TITLE]...[/TITLE] and <TITLE>...</TITLE> tags (including translated variants) */
+export const TITLE_STRIP_RE = new RegExp(
+  String.raw`\[(${TAG})\].*?\[\/\1\]|<(${TAG})>.*?<\/\2>`,
+  'gi',
+);