@gram-ai/elements 1.37.1 → 1.38.0

package/src/components/ui/tool-ui.tsx

@@ -7,7 +7,11 @@ import {
   ChevronRightIcon,
   ChevronUpIcon,
   CopyIcon,
+  EyeIcon,
+  EyeOffIcon,
   LoaderIcon,
+  SearchIcon,
+  TriangleAlertIcon,
   XIcon,
 } from "lucide-react";
 import { cn } from "@/lib/utils";
@@ -65,6 +69,33 @@ interface ToolAnnotations {
   openWorldHint?: boolean;
 }
 
+/** Marks a tool section (arguments/output) as containing flagged substrings,
+ * so the section header shows a warning and the expanded body lets you jump
+ * between matches. */
+/** One flagged finding within a tool section. */
+interface SectionMatch {
+  /** Literal substring to highlight and step to. */
+  value: string;
+  /** Short rule label shown when this match is active (e.g. "pii.phone_number"). */
+  label?: string;
+  /** Optional action for this finding, surfaced as a button while it is the
+   * active match (e.g. open the create-exclusion flow). */
+  onExclude?: () => void;
+}
+
+interface SectionHighlight {
+  /** Findings to highlight and step through with the next/prev controls. */
+  matches: SectionMatch[];
+  /** Dot out the matched characters until the viewer reveals them (secrets). */
+  masked?: boolean;
+  /** Optional host-supplied badge rendered in the section header (e.g. a risk
+   * pill). Replaces the default warning icon when present. */
+  headerBadge?: React.ReactNode;
+  /** Mark colour: "risk" (red, default) for findings, "search" (yellow) for a
+   * text-search hit. */
+  tone?: "risk" | "search";
+}
+
 interface ToolUIProps {
   /** Display name of the tool */
   name: string;
@@ -80,6 +111,16 @@ interface ToolUIProps {
   result?: string | Record<string, unknown> | { content: ContentItem[] };
   /** Whether the tool card starts expanded */
   defaultExpanded?: boolean;
+  /** Flag matches inside the arguments (risk review). */
+  requestHighlight?: SectionHighlight;
+  /** Flag matches inside the output (risk review). */
+  resultHighlight?: SectionHighlight;
+  /** When set, highlight occurrences of this query (case-insensitive) in the
+   * tool name — e.g. a thread search for "customer" lights up `get_customer`. */
+  nameQuery?: string;
+  /** Whether this tool holds the active thread-search match: bright highlights
+   * (name + sections) when true, pale when false. */
+  searchActive?: boolean;
   /** Additional class names */
   className?: string;
   /** MCP tool annotations */
@@ -101,6 +142,11 @@ interface ToolUISectionProps {
   highlightSyntax?: boolean;
   /** Language hint for syntax highlighting */
   language?: BundledLanguage;
+  /** Flagged substrings — renders a navigable highlighted view + header icon. */
+  highlight?: SectionHighlight;
+  /** Search tone only: whether this tool holds the active thread match (bright
+   * vs pale marks). */
+  searchActive?: boolean;
 }
 
 /* -----------------------------------------------------------------------------
@@ -255,7 +301,7 @@ function SyntaxHighlightedCode({
         {
           pre(node) {
             node.properties.class =
-              "w-full py-3 px-4 max-h-[300px] overflow-y-auto whitespace-pre-wrap text-left text-sm";
+              "w-full py-3 px-4 max-h-[300px] overflow-y-auto whitespace-pre-wrap break-all text-left text-sm";
           },
         },
       ],
@@ -280,7 +326,7 @@ function SyntaxHighlightedCode({
   if (!canHighlight || !highlightedCode) {
     return (
       <div className={cn("w-full", className)}>
-        <pre className="max-h-[300px] w-full overflow-y-auto bg-slate-800/90 px-4 py-3 text-sm whitespace-pre-wrap text-slate-100">
+        <pre className="max-h-[300px] w-full overflow-y-auto bg-slate-800/90 px-4 py-3 text-sm break-all whitespace-pre-wrap text-slate-100">
           {displayText}
         </pre>
         {showMoreButton}
@@ -299,6 +345,234 @@ function SyntaxHighlightedCode({
   );
 }
 
+/* -----------------------------------------------------------------------------
+ * HighlightedCode - plain code view with flagged matches you can step through
+ * -------------------------------------------------------------------------- */
+
+interface MatchHit {
+  start: number;
+  end: number;
+  /** Index into the `matches` array that produced this hit. */
+  matchIndex: number;
+}
+
+function findMatchHits(
+  text: string,
+  values: string[],
+  caseInsensitive = false,
+): MatchHit[] {
+  // Risk findings match an exact value; a text-search hit matches case-
+  // insensitively (the server search is ILIKE). Tool content is monospace
+  // code/JSON, so lowercasing doesn't shift offsets in practice.
+  const haystack = caseInsensitive ? text.toLowerCase() : text;
+  const hits: MatchHit[] = [];
+  values.forEach((value, matchIndex) => {
+    if (!value) return;
+    const needle = caseInsensitive ? value.toLowerCase() : value;
+    let from = 0;
+    let idx = haystack.indexOf(needle, from);
+    while (idx !== -1) {
+      hits.push({ start: idx, end: idx + value.length, matchIndex });
+      from = idx + value.length;
+      idx = haystack.indexOf(needle, from);
+    }
+  });
+  hits.sort((a, b) => a.start - b.start);
+  // Coalesce overlapping ranges so the renderer's sequential, non-overlapping
+  // slice walk stays correct. A merged range keeps the first hit's matchIndex
+  // (overlapping distinct findings are rare; correct rendering wins).
+  const merged: MatchHit[] = [];
+  for (const hit of hits) {
+    const last = merged[merged.length - 1];
+    if (last && hit.start <= last.end) last.end = Math.max(last.end, hit.end);
+    else merged.push({ ...hit });
+  }
+  return merged;
+}
+
+function maskMatch(value: string): string {
+  // Mask character-for-character so toggling reveal doesn't change the length
+  // (the tool view is monospace, so equal length means zero layout shift).
+  return "•".repeat(value.length);
+}
+
+function HighlightedCode({
+  text,
+  matches,
+  masked,
+  tone = "risk",
+  searchActive = false,
+}: {
+  text: string;
+  matches: SectionMatch[];
+  masked?: boolean;
+  tone?: "risk" | "search";
+  /** Search tone only: whether this tool holds the active thread match. Active
+   * → bright marks; inactive → pale. (Risk tone steps per-section instead.) */
+  searchActive?: boolean;
+}): React.JSX.Element {
+  const hits = React.useMemo(
+    () =>
+      findMatchHits(
+        text,
+        matches.map((m) => m.value),
+        tone === "search",
+      ),
+    [text, matches, tone],
+  );
+  const count = hits.length;
+  const [active, setActive] = useState(0);
+  const [revealed, setRevealed] = useState(!masked);
+  const markRefs = React.useRef<Array<HTMLElement | null>>([]);
+  const preRef = React.useRef<HTMLPreElement>(null);
+
+  useEffect(() => {
+    if (active >= count && count > 0) setActive(0);
+  }, [count, active]);
+  // Center the active match within the code block *only* — adjust the <pre>'s
+  // own scrollTop rather than scrollIntoView(), which would also yank the
+  // surrounding sheet. Runs on mount (focus the first match) and on each step.
+  useEffect(() => {
+    const pre = preRef.current;
+    const mark = markRefs.current[active];
+    if (!pre || !mark) return;
+    const markRect = mark.getBoundingClientRect();
+    const preRect = pre.getBoundingClientRect();
+    pre.scrollTop +=
+      markRect.top - preRect.top - pre.clientHeight / 2 + markRect.height / 2;
+  }, [active, count]);
+
+  const go = (delta: number) => {
+    if (count === 0) return;
+    setActive((a) => (a + delta + count) % count);
+  };
+
+  const activeMatch = hits[active]
+    ? matches[hits[active]!.matchIndex]
+    : undefined;
+
+  const segments: React.ReactNode[] = [];
+  let pos = 0;
+  hits.forEach((hit, i) => {
+    if (hit.start > pos)
+      segments.push(<span key={`t${i}`}>{text.slice(pos, hit.start)}</span>);
+    const value = text.slice(hit.start, hit.end);
+    segments.push(
+      <mark
+        key={`m${i}`}
+        ref={(el) => {
+          markRefs.current[i] = el;
+        }}
+        className={cn(
+          // Fixed-width mono chip, lightened for the dark code surface. The active
+          // (currently navigated) match pops so prev/next navigation + auto-scroll
+          // have a visible target; the rest stay a darker shade. Risk findings are
+          // red; a plain text-search hit is yellow.
+          "rounded-sm px-0.5 font-mono ring-1",
+          tone === "search"
+            ? // Search nav is per-row, so all occurrences here share the row's
+              // active state: bright when this tool is the active match, else pale.
+              searchActive
+              ? "bg-yellow-400 text-yellow-950 ring-yellow-300"
+              : "bg-yellow-800/50 text-yellow-200/90 ring-yellow-700/50"
+            : i === active
+              ? "bg-red-700 text-red-50 ring-red-400"
+              : "bg-red-900 text-red-300 ring-red-800",
+        )}
+      >
+        {masked && !revealed ? maskMatch(value) : value}
+      </mark>,
+    );
+    pos = hit.end;
+  });
+  if (pos < text.length)
+    segments.push(<span key="tail">{text.slice(pos)}</span>);
+
+  return (
+    <div className="w-full">
+      {count > 0 && (
+        <div className="flex items-center justify-between gap-3 bg-slate-900 px-4 py-2 text-xs text-slate-300">
+          <div className="flex min-w-0 items-center gap-2">
+            {tone === "search" ? (
+              <span className="flex shrink-0 items-center gap-1.5 font-medium text-yellow-300">
+                <SearchIcon className="size-3.5" />
+                {count} {count === 1 ? "match" : "matches"}
+              </span>
+            ) : (
+              <span className="flex shrink-0 items-center gap-1.5 font-medium text-amber-400">
+                <TriangleAlertIcon className="size-3.5" />
+                {count} flagged {count === 1 ? "match" : "matches"}
+              </span>
+            )}
+            {activeMatch?.label && (
+              <span className="truncate rounded bg-slate-700/60 px-1.5 py-0.5 font-mono text-slate-300">
+                {activeMatch.label}
+              </span>
+            )}
+            {activeMatch?.onExclude && (
+              <button
+                type="button"
+                onClick={activeMatch.onExclude}
+                title="Create an exclusion for this finding"
+                className="shrink-0 rounded px-1.5 py-0.5 text-slate-300 transition-colors hover:bg-slate-700 hover:text-white"
+              >
+                Create exclusion
+              </button>
+            )}
+          </div>
+          <div className="flex shrink-0 items-center gap-3 text-slate-400">
+            {masked && (
+              <button
+                type="button"
+                onClick={() => setRevealed((r) => !r)}
+                className="inline-flex items-center gap-1 transition-colors hover:text-slate-100"
+              >
+                {revealed ? (
+                  <EyeIcon className="size-3.5" />
+                ) : (
+                  <EyeOffIcon className="size-3.5" />
+                )}
+                {revealed ? "Hide" : "Reveal"}
+              </button>
+            )}
+            {count >= 1 && (
+              <div className="flex items-center gap-0.5">
+                <button
+                  type="button"
+                  onClick={() => go(-1)}
+                  disabled={count <= 1}
+                  className="rounded p-1 transition-colors hover:bg-slate-700 hover:text-slate-100 disabled:opacity-40 disabled:hover:bg-transparent"
+                  aria-label="Previous match"
+                >
+                  <ChevronUpIcon className="size-3.5" />
+                </button>
+                <span className="text-slate-300 tabular-nums">
+                  {active + 1}/{count}
+                </span>
+                <button
+                  type="button"
+                  onClick={() => go(1)}
+                  disabled={count <= 1}
+                  className="rounded p-1 transition-colors hover:bg-slate-700 hover:text-slate-100 disabled:opacity-40 disabled:hover:bg-transparent"
+                  aria-label="Next match"
+                >
+                  <ChevronDownIcon className="size-3.5" />
+                </button>
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+      <pre
+        ref={preRef}
+        className="max-h-[300px] w-full overflow-y-auto bg-slate-800/90 px-4 py-3 text-sm break-all whitespace-pre-wrap text-slate-100"
+      >
+        {segments}
+      </pre>
+    </div>
+  );
+}
+
 /* -----------------------------------------------------------------------------
  * ImageContent - Display base64 encoded images with checkerboard background
  * -------------------------------------------------------------------------- */
@@ -355,7 +629,7 @@ function StructuredResultContent({
             return (
               <pre
                 key={index}
-                className="px-4 py-3 text-sm whitespace-pre-wrap"
+                className="px-4 py-3 text-sm break-all whitespace-pre-wrap"
               >
                 {JSON.stringify(item, null, 2)}
               </pre>
@@ -376,6 +650,8 @@ function ToolUISection({
   defaultExpanded = false,
   highlightSyntax = true,
   language = "json",
+  highlight,
+  searchActive = false,
 }: ToolUISectionProps): React.JSX.Element {
   const [isExpanded, setIsExpanded] = useState(defaultExpanded);
 
@@ -387,13 +663,28 @@ function ToolUISection({
       ? content
       : JSON.stringify(content, null, 2);
 
+  const matchCount = highlight?.matches?.length ?? 0;
+
+  let headerIndicator: React.ReactNode = null;
+  if (highlight?.headerBadge) headerIndicator = highlight.headerBadge;
+  else if (matchCount > 0)
+    headerIndicator =
+      highlight?.tone === "search" ? (
+        <SearchIcon className="size-3.5 text-yellow-500" />
+      ) : (
+        <TriangleAlertIcon className="size-3.5 text-amber-500" />
+      );
+
   return (
     <div data-slot="tool-ui-section" className="border-t border-border">
       <button
         onClick={() => setIsExpanded(!isExpanded)}
         className="flex w-full cursor-pointer items-center justify-between px-5 py-2.5 text-left transition-colors hover:bg-accent/50"
       >
-        <span className="text-sm text-muted-foreground">{title}</span>
+        <span className="flex items-center gap-2 text-sm text-muted-foreground">
+          {title}
+          {headerIndicator}
+        </span>
         <div className="flex items-center gap-1">
           <CopyButton content={contentString} />
           <ChevronRightIcon
@@ -406,12 +697,22 @@ function ToolUISection({
       </button>
       {isExpanded && (
         <div className="border-t border-border">
-          {isStructured ? (
+          {matchCount > 0 ? (
+            // Flagged content must go through the masked/highlighted view even
+            // when it's structured, otherwise secrets render in clear text.
+            <HighlightedCode
+              text={contentString}
+              matches={highlight!.matches}
+              masked={highlight?.masked}
+              tone={highlight?.tone}
+              searchActive={searchActive}
+            />
+          ) : isStructured ? (
             <StructuredResultContent content={content} />
           ) : highlightSyntax ? (
             <SyntaxHighlightedCode text={contentString} language={language} />
           ) : (
-            <pre className="overflow-x-auto px-4 py-3 text-sm whitespace-pre-wrap text-foreground">
+            <pre className="px-4 py-3 text-sm break-all whitespace-pre-wrap text-foreground">
               {contentString}
             </pre>
           )}
@@ -427,6 +728,42 @@ type ApprovalMode = "one-time" | "for-session";
  * ToolUI - Main component
  * -------------------------------------------------------------------------- */
 
+// Highlight every case-insensitive occurrence of `query` in a short label (the
+// tool name), preserving original casing. Matches over the original string so
+// offsets stay aligned; escapes regex metacharacters in the user query.
+function highlightLabel(
+  text: string,
+  query?: string,
+  active = false,
+): React.ReactNode {
+  const q = query?.trim();
+  if (!q) return text;
+  const re = new RegExp(q.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "gi");
+  // Active match bright, others pale.
+  const markClass = active
+    ? "rounded-sm bg-yellow-300/80 px-0.5 text-foreground"
+    : "rounded-sm bg-yellow-200/30 px-0.5 text-foreground";
+  const nodes: React.ReactNode[] = [];
+  let pos = 0;
+  let k = 0;
+  for (let m = re.exec(text); m !== null; m = re.exec(text)) {
+    if (m[0].length === 0) {
+      re.lastIndex++;
+      continue;
+    }
+    if (m.index > pos) nodes.push(text.slice(pos, m.index));
+    nodes.push(
+      <mark key={k++} className={markClass}>
+        {m[0]}
+      </mark>,
+    );
+    pos = m.index + m[0].length;
+  }
+  if (pos === 0) return text;
+  if (pos < text.length) nodes.push(text.slice(pos));
+  return nodes;
+}
+
 function ToolUI({
   name,
   icon,
@@ -435,6 +772,10 @@ function ToolUI({
   request,
   result,
   defaultExpanded = false,
+  requestHighlight,
+  resultHighlight,
+  nameQuery,
+  searchActive = false,
   className,
   annotations,
   onApproveOnce,
@@ -520,7 +861,7 @@ function ToolUI({
             !provider && isApprovalPending && "shimmer",
           )}
         >
-          {displayName}
+          {highlightLabel(displayName, nameQuery, searchActive)}
         </span>
         {hasContent && (
           <ChevronDownIcon
@@ -542,6 +883,9 @@ function ToolUI({
               content={request}
               highlightSyntax
               language="json"
+              highlight={requestHighlight}
+              searchActive={searchActive}
+              defaultExpanded={(requestHighlight?.matches?.length ?? 0) > 0}
             />
           )}
           {/* Hide output when approval is pending */}
@@ -551,6 +895,9 @@ function ToolUI({
               content={result}
               highlightSyntax
               language="json"
+              highlight={resultHighlight}
+              searchActive={searchActive}
+              defaultExpanded={(resultHighlight?.matches?.length ?? 0) > 0}
             />
           )}
         </div>
@@ -797,6 +1144,10 @@ function ToolUIGroup({
  * Exports
  * -------------------------------------------------------------------------- */
 
+ToolUI.displayName = "ToolUI";
+ToolUISection.displayName = "ToolUISection";
+SyntaxHighlightedCode.displayName = "SyntaxHighlightedCode";
+
 export {
   ToolUI,
   ToolUISection,
@@ -811,4 +1162,6 @@ export type {
   ToolUIGroupProps,
   ToolStatus,
   ContentItem,
+  SectionHighlight,
+  SectionMatch,
 };

package/src/contexts/ElementsProvider.tsx

@@ -438,7 +438,8 @@ const ElementsProviderInner = ({ children, config }: ElementsProviderProps) => {
           const nonSystemMessages = cleanedMessages.filter(
             (m) => m.role !== "system",
           );
-          const rawModelMessages = convertToModelMessages(nonSystemMessages);
+          const rawModelMessages =
+            await convertToModelMessages(nonSystemMessages);
 
           // Auto-compact older turns if the estimated input is approaching
           // the model's context window. System prompt + last few turns are

package/src/hooks/useGramThreadListAdapter.tsx

@@ -135,6 +135,54 @@ async function resolveAdapterHeaders(
   return options.getHeaders ? options.getHeaders() : options.headers;
 }
 
+// chat.load paginates by seq keyset and returns only the newest page by default.
+// assistant-ui's history adapter is one-shot (it imports the whole thread at
+// once), so page backwards to the start and return the chat with every message
+// in ascending order. Without this a long thread would render only its newest
+// page with no way to reach the rest.
+const FULL_LOAD_PAGE_SIZE = 200;
+
+async function loadFullChat(
+  apiUrl: string,
+  chatId: string,
+  headers: Record<string, string>,
+): Promise<GramChat | null> {
+  let beforeSeq: number | undefined;
+  let all: GramChatMessage[] = [];
+  let base: GramChat | null = null;
+
+  for (;;) {
+    const cursor = beforeSeq !== undefined ? `&before_seq=${beforeSeq}` : "";
+    const response = await fetch(
+      `${apiUrl}/rpc/chat.load?id=${encodeURIComponent(chatId)}&limit=${FULL_LOAD_PAGE_SIZE}${cursor}`,
+      { headers },
+    );
+    if (!response.ok) {
+      // First page failed → nothing to show. A later page failing means we'd
+      // silently truncate the thread, so log loudly rather than passing partial
+      // history off as complete.
+      if (!base) {
+        console.error("Failed to load chat:", response.status);
+        return null;
+      }
+      console.error(
+        `Failed to load full chat history (status ${response.status}); ` +
+          `returning ${all.length} of ${base.numMessages ?? "?"} messages — transcript is truncated.`,
+      );
+      return { ...base, messages: all };
+    }
+    const page = (await response.json()) as GramChat;
+    if (!base) base = page;
+    // Each page is ascending; older pages prepend.
+    all = [...page.messages, ...all];
+    const oldest = page.messages[0];
+    if (!page.has_more_before || !oldest || oldest.seq === undefined) break;
+    beforeSeq = oldest.seq;
+  }
+
+  return base ? { ...base, messages: all } : null;
+}
+
 /**
  * Thread history adapter that loads messages from Gram API.
  * Note: We use `as ThreadHistoryAdapter` cast because the withFormat generic
@@ -188,17 +236,15 @@ class GramThreadHistoryAdapter {
     }
 
     try {
-      const response = await fetch(
-        `${this.apiUrl}/rpc/chat.load?id=${encodeURIComponent(remoteId)}`,
-        { headers: await this.getHeaders() },
+      const chat = await loadFullChat(
+        this.apiUrl,
+        remoteId,
+        await this.getHeaders(),
       );
-
-      if (!response.ok) {
-        console.error("Failed to load chat:", response.status);
+      if (!chat) {
+        console.error("Failed to load chat");
         return { messages: [], headId: null };
       }
-
-      const chat = (await response.json()) as GramChat;
       return convertGramMessagesToExported(this.applyTransform(chat.messages));
     } catch (error) {
       console.error("Error loading chat:", error);
@@ -222,17 +268,15 @@ class GramThreadHistoryAdapter {
           return { messages: [], headId: null };
         }
 
-        const response = await fetch(
-          `${this.apiUrl}/rpc/chat.load?id=${encodeURIComponent(remoteId)}`,
-          { headers: await this.getHeaders() },
+        const chat = await loadFullChat(
+          this.apiUrl,
+          remoteId,
+          await this.getHeaders(),
         );
-
-        if (!response.ok) {
-          console.error("Failed to load chat (withFormat):", response.status);
+        if (!chat) {
+          console.error("Failed to load chat (withFormat)");
           return { messages: [], headId: null };
         }
-
-        const chat = (await response.json()) as GramChat;
         return convertGramMessagesToUIMessages(
           this.applyTransform(chat.messages),
         );
@@ -509,8 +553,10 @@ export function useGramThreadListAdapter(
         }
 
         try {
+          // Only chat metadata (id/title) is needed here, so request the
+          // smallest page instead of a full message page.
           const response = await fetch(
-            `${optionsRef.current.apiUrl}/rpc/chat.load?id=${encodeURIComponent(threadId)}`,
+            `${optionsRef.current.apiUrl}/rpc/chat.load?id=${encodeURIComponent(threadId)}&limit=1`,
             {
               headers: await resolveAdapterHeaders(optionsRef.current),
             },

package/src/hooks/useMCPTools.ts

@@ -1,7 +1,7 @@
 import { assert } from "@/lib/utils";
 import type { MCPServerEntry } from "@/types";
 import { ToolsFilter } from "@/types";
-import { experimental_createMCPClient as createMCPClient } from "@ai-sdk/mcp";
+import { createMCPClient } from "@ai-sdk/mcp";
 import { useQuery, type UseQueryResult } from "@tanstack/react-query";
 import { useMemo, useRef } from "react";
 import { trackError } from "@/lib/errorTracking";

package/src/index.ts

@@ -20,6 +20,24 @@ export type { ShareButtonProps } from "@/components/ShareButton";
 export { ToolFallback } from "@/components/assistant-ui/tool-fallback";
 export { MessageContent } from "@/components/MessageContent";
 export type { MessageContentProps } from "@/components/MessageContent";
+export { Markdown } from "@/components/Markdown";
+export type { MarkdownProps } from "@/components/Markdown";
+
+// Static presentation primitives — render with no ElementsProvider/runtime, so
+// the dashboard's chat detail panel can reuse the elements tool UI directly.
+export {
+  ToolUI,
+  ToolUISection,
+  SyntaxHighlightedCode,
+} from "@/components/ui/tool-ui";
+export type {
+  ToolUIProps,
+  ToolUISectionProps,
+  ToolStatus,
+  ContentItem,
+  SectionHighlight,
+  SectionMatch,
+} from "@/components/ui/tool-ui";
 
 // Replay
 export { Replay } from "@/components/Replay";

package/src/lib/messageConverter.ts

@@ -71,6 +71,8 @@ export type GramChatContent = string | GramChatContentPart[];
  */
 export interface GramChatMessage {
   id: string;
+  // Monotonic sequence number; used as the keyset cursor when paging chat.load.
+  seq?: number;
   model: string;
   created_at: Date | string;
   role: "system" | "developer" | "user" | "assistant" | "tool";
@@ -92,6 +94,9 @@ export interface GramChat {
   messages: GramChatMessage[];
   createdAt: Date | string;
   updatedAt: Date | string;
+  // chat.load paginates by seq keyset; true when older messages remain before
+  // the first message in `messages` (snake_case to match the wire payload).
+  has_more_before?: boolean;
 }
 
 /**