@agent-native/core 0.78.0 → 0.78.2

package/corpus/core/src/client/composer/TiptapComposer.tsx

@@ -31,8 +31,17 @@ import {
   reasoningEffortLabel,
   type ReasoningEffort,
 } from "../../shared/reasoning-effort.js";
-import { sendToAgentChat, type AgentChatContextItem } from "../agent-chat.js";
+import {
+  AgentComposerReference,
+  normalizeAgentComposerReference,
+  sendToAgentChat,
+  type AgentChatContextItem,
+  AgentComposerReferenceInsertPayload,
+  AGENT_CHAT_INSERT_REFERENCE_EVENT,
+  AGENT_CHAT_INSERT_REFERENCE_MESSAGE_TYPE,
+} from "../agent-chat.js";
 import { tryDelegateBuildRequestToBuilder } from "../builder-frame.js";
+import { isTrustedBuilderMessage } from "../builder-frame.js";
 import {
   Popover,
   PopoverContent,
@@ -43,6 +52,7 @@ import {
   TooltipContent,
   TooltipTrigger,
 } from "../components/ui/tooltip.js";
+import { isTrustedFrameMessage } from "../frame.js";
 import { useBuilderConnectFlow } from "../settings/useBuilderStatus.js";
 import { ComposerPlusMenu } from "./ComposerPlusMenu.js";
 import { getComposerDraftKey } from "./draft-key.js";
@@ -67,10 +77,10 @@ import { useMentionSearch } from "./use-mention-search.js";
 import { useSkills } from "./use-skills.js";
 import { useVoiceDictation } from "./useVoiceDictation.js";
 import { VoiceButton, VoiceRecordingOverlay } from "./VoiceButton.js";
-
 export interface TiptapComposerHandle {
   focus(): void;
   setText(text: string): void;
+  insertReference(ref: AgentComposerReference): void;
 }
 
 export type ComposerSubmitIntent = "immediate" | "queued";
@@ -94,6 +104,120 @@ export function canSubmitComposerContent(options: {
 
 const MAX_DOCUMENT_ATTACHMENT_BYTES = 4 * 1024 * 1024;
 
+function composerReferenceFromMentionItem(
+  item: MentionItem,
+): AgentComposerReference {
+  return {
+    label: item.label,
+    icon: item.icon || "file",
+    source: item.source,
+    refType: item.refType,
+    refId: item.refId || null,
+    refPath: item.refPath || null,
+    slotKey: item.slotKey,
+    slotLabel: item.slotLabel,
+    metadata: item.metadata,
+    clearsSlots: item.clearsSlots,
+    relatedReferences: item.relatedReferences,
+  };
+}
+
+function mentionReferenceAttrs(ref: AgentComposerReference) {
+  return {
+    label: ref.label,
+    icon: ref.icon || "file",
+    source: ref.source,
+    refType: ref.refType,
+    refId: ref.refId || null,
+    refPath: ref.refPath || null,
+    slotKey: ref.slotKey || null,
+    slotLabel: ref.slotLabel || null,
+    metadata: ref.metadata || null,
+  };
+}
+
+function referenceFromComposerReference(
+  ref: AgentComposerReference,
+): Reference {
+  return {
+    type:
+      ref.refType === "file"
+        ? "file"
+        : ref.refType === "agent"
+          ? "agent"
+          : ref.refType === "custom-agent"
+            ? "custom-agent"
+            : "mention",
+    path: ref.refPath || "",
+    name: ref.label,
+    source: ref.source || "",
+    refType: ref.refType,
+    refId: ref.refId || undefined,
+    slotKey: ref.slotKey,
+    slotLabel: ref.slotLabel,
+    metadata: ref.metadata,
+  };
+}
+
+function applySlotReferenceChanges(
+  current: AgentComposerReference[],
+  references: AgentComposerReference[],
+): AgentComposerReference[] {
+  let next = current;
+
+  const applyOne = (ref: AgentComposerReference) => {
+    for (const related of ref.relatedReferences ?? []) {
+      applyOne(related);
+    }
+    if (!ref.slotKey) return;
+    const cleared = new Set([ref.slotKey, ...(ref.clearsSlots ?? [])]);
+    next = next.filter((existing) => !cleared.has(existing.slotKey ?? ""));
+    next = [...next, ref];
+  };
+
+  for (const ref of references) {
+    applyOne(ref);
+  }
+
+  return next;
+}
+
+function removeSlotReference(
+  current: AgentComposerReference[],
+  ref: AgentComposerReference,
+): AgentComposerReference[] {
+  const removed = new Set([ref.slotKey, ...(ref.clearsSlots ?? [])]);
+  return current.filter((existing) => !removed.has(existing.slotKey ?? ""));
+}
+
+function slotReferenceTitle(ref: AgentComposerReference): string {
+  return ref.slotLabel ? `${ref.slotLabel}: ${ref.label}` : ref.label;
+}
+
+function metadataString(
+  metadata: Record<string, unknown> | undefined,
+  key: string,
+): string | null {
+  const value = metadata?.[key];
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function filterMentionItemsForSlots(
+  items: MentionItem[],
+  slotReferences: AgentComposerReference[],
+): MentionItem[] {
+  return items.filter((item) => {
+    const requiredSlotKey = metadataString(item.metadata, "requiredSlotKey");
+    const requiredRefId = metadataString(item.metadata, "requiredRefId");
+    if (!requiredSlotKey || !requiredRefId) return true;
+    const selected = slotReferences.find(
+      (ref) => ref.slotKey === requiredSlotKey,
+    );
+    if (!selected?.refId) return true;
+    return selected.refId === requiredRefId;
+  });
+}
+
 function isDocumentAttachment(value: Record<string, unknown>): boolean {
   if (value.type === "document") return true;
   const contentType = String(value.contentType ?? "").toLowerCase();
@@ -165,6 +289,26 @@ function uniquifyComposerImageFile(file: File): File {
   return new File([file], uniqueName, { type: file.type });
 }
 
+function composerDocumentHasContent(doc: {
+  textContent: string;
+  descendants: (callback: (node: any) => boolean | void) => void;
+}): boolean {
+  if (doc.textContent.trim().length > 0) return true;
+  let hasContent = false;
+  doc.descendants((node: any) => {
+    if (
+      node.type.name === "mentionReference" ||
+      node.type.name === "fileReference" ||
+      node.type.name === "skillReference"
+    ) {
+      hasContent = true;
+      return false;
+    }
+    return true;
+  });
+  return hasContent;
+}
+
 export function handleComposerFileDrop(options: {
   event: Pick<DragEvent, "dataTransfer" | "preventDefault" | "stopPropagation">;
   addAttachment: (file: File) => Promise<unknown>;
@@ -1109,14 +1253,17 @@ export function TiptapComposer({
   const popoverRef = useRef<MentionPopoverRef>(null);
   const composerRuntime = useComposerRuntime();
   const [editorHasText, setEditorHasText] = useState(false);
+  const [slotReferences, setSlotReferences] = useState<
+    AgentComposerReference[]
+  >([]);
   const composerText = useComposer((state) => state.text);
   const composerAttachments = useComposer((state) => state.attachments);
   const canSend = canSubmitComposerContent({
-    hasEditorContent: editorHasText,
+    hasEditorContent: editorHasText || slotReferences.length > 0,
     attachmentCount: composerAttachments.length,
     disabled,
   });
-  const hasContextItems = contextItems.length > 0;
+  const hasContextRows = contextItems.length > 0 || slotReferences.length > 0;
   const [composerMode, setComposerMode] = useState<ComposerMode | null>(null);
   const composerModeRef = useRef<ComposerMode | null>(null);
   const isMac =
@@ -1138,6 +1285,10 @@ export function TiptapComposer({
     popover?.type === "@" ? popover.query : "",
     popover?.type === "@",
   );
+  const filteredMentionItems = useMemo(
+    () => filterMentionItemsForSlots(mentionItems, slotReferences),
+    [mentionItems, slotReferences],
+  );
 
   const {
     skills,
@@ -1186,8 +1337,8 @@ export function TiptapComposer({
   }, [allSlashSkills, popover]);
 
   // Keep refs in sync with state
-  const mentionItemsRef = useRef(mentionItems);
-  mentionItemsRef.current = mentionItems;
+  const mentionItemsRef = useRef(filteredMentionItems);
+  mentionItemsRef.current = filteredMentionItems;
   const filteredCommandsRef = useRef(filteredCommands);
   filteredCommandsRef.current = filteredCommands;
   const filteredSkillsRef = useRef(filteredSkills);
@@ -1197,6 +1348,7 @@ export function TiptapComposer({
   const onTextChangeRef = useRef(onTextChange);
   onTextChangeRef.current = onTextChange;
   const initialTextKeyRef = useRef<string | number | undefined>(undefined);
+  const seenReferenceInsertIdsRef = useRef<Set<string>>(new Set());
 
   const closePopover = useCallback(() => {
     setPopover(null);
@@ -1229,14 +1381,14 @@ export function TiptapComposer({
         if (initialText !== undefined) {
           ed.commands.setContent(plainTextToDoc(initialText));
           ed.commands.focus("end");
-          setEditorHasText(ed.state.doc.textContent.trim().length > 0);
+          setEditorHasText(composerDocumentHasContent(ed.state.doc));
           initialTextKeyRef.current = initialTextKey ?? initialText;
         } else {
           const saved = localStorage.getItem(draftKey);
           if (saved) {
             ed.commands.setContent(saved);
             ed.commands.focus("end");
-            setEditorHasText(ed.state.doc.textContent.trim().length > 0);
+            setEditorHasText(composerDocumentHasContent(ed.state.doc));
           }
         }
         onTextChangeRef.current?.(ed.state.doc.textContent.trim());
@@ -1245,21 +1397,7 @@ export function TiptapComposer({
     onUpdate: ({ editor: ed }) => {
       // Drive the send button's enabled state from the actual editor contents;
       // the composer runtime is only synced on submit, so its isEmpty lags.
-      let hasContent = ed.state.doc.textContent.trim().length > 0;
-      if (!hasContent) {
-        ed.state.doc.descendants((node: any) => {
-          if (
-            node.type.name === "mentionReference" ||
-            node.type.name === "fileReference" ||
-            node.type.name === "skillReference"
-          ) {
-            hasContent = true;
-            return false;
-          }
-          return true;
-        });
-      }
-      setEditorHasText(hasContent);
+      setEditorHasText(composerDocumentHasContent(ed.state.doc));
       onTextChangeRef.current?.(ed.state.doc.textContent.trim());
 
       // Debounce-save draft to localStorage
@@ -1267,7 +1405,7 @@ export function TiptapComposer({
       draftTimerRef.current = setTimeout(() => {
         try {
           const html = ed.getHTML();
-          const isEmpty = !ed.state.doc.textContent.trim();
+          const isEmpty = !composerDocumentHasContent(ed.state.doc);
           if (isEmpty) {
             localStorage.removeItem(draftKey);
           } else {
@@ -1503,6 +1641,106 @@ export function TiptapComposer({
     },
   });
 
+  const insertReference = useCallback(
+    (ref: AgentComposerReference) => {
+      const normalized = normalizeAgentComposerReference(ref);
+      const ed = editor;
+      if (!normalized || !ed) return;
+      if (normalized.slotKey) {
+        setSlotReferences((current) =>
+          applySlotReferenceChanges(current, [normalized]),
+        );
+        ed.commands.focus("end");
+        return;
+      }
+      if (normalized.relatedReferences?.some((item) => item.slotKey)) {
+        setSlotReferences((current) =>
+          applySlotReferenceChanges(
+            current,
+            normalized.relatedReferences ?? [],
+          ),
+        );
+      }
+      ed.chain()
+        .focus()
+        .insertContent({
+          type: "mentionReference",
+          attrs: mentionReferenceAttrs(normalized),
+        })
+        .insertContent(" ")
+        .run();
+      setEditorHasText(true);
+    },
+    [editor],
+  );
+
+  const insertReferenceIfEmpty = useCallback(
+    (payload: AgentComposerReferenceInsertPayload) => {
+      const insertMessageId =
+        typeof payload.insertMessageId === "string"
+          ? payload.insertMessageId
+          : "";
+      if (insertMessageId) {
+        if (seenReferenceInsertIdsRef.current.has(insertMessageId)) return;
+        seenReferenceInsertIdsRef.current.add(insertMessageId);
+      }
+      const ed = editor;
+      if (!ed || disabled || composerModeRef.current) return;
+      const normalized = normalizeAgentComposerReference(payload);
+      if (normalized?.slotKey) {
+        insertReference(normalized);
+        return;
+      }
+      if (composerAttachments.length > 0) return;
+      if (composerDocumentHasContent(ed.state.doc)) return;
+      insertReference(payload);
+    },
+    [composerAttachments.length, disabled, editor, insertReference],
+  );
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const handleEvent = (event: Event) => {
+      const payload = (event as CustomEvent).detail;
+      const normalized = normalizeAgentComposerReference(payload);
+      if (!normalized) return;
+      insertReferenceIfEmpty({
+        ...normalized,
+        insertMessageId:
+          typeof payload?.insertMessageId === "string"
+            ? payload.insertMessageId
+            : "",
+      });
+    };
+    const handleMessage = (event: MessageEvent) => {
+      if (!isTrustedFrameMessage(event) && !isTrustedBuilderMessage(event)) {
+        return;
+      }
+      if (event.data?.type !== AGENT_CHAT_INSERT_REFERENCE_MESSAGE_TYPE) {
+        return;
+      }
+      const payload = event.data.data;
+      const normalized = normalizeAgentComposerReference(payload);
+      if (!normalized) return;
+      insertReferenceIfEmpty({
+        ...normalized,
+        insertMessageId:
+          typeof payload?.insertMessageId === "string"
+            ? payload.insertMessageId
+            : "",
+      });
+    };
+    window.addEventListener(AGENT_CHAT_INSERT_REFERENCE_EVENT, handleEvent);
+    window.addEventListener("message", handleMessage);
+    return () => {
+      window.removeEventListener(
+        AGENT_CHAT_INSERT_REFERENCE_EVENT,
+        handleEvent,
+      );
+      window.removeEventListener("message", handleMessage);
+    };
+  }, [insertReferenceIfEmpty]);
+
   useImperativeHandle(focusRef, () => ({
     focus() {
       editor?.commands.focus("end");
@@ -1513,6 +1751,7 @@ export function TiptapComposer({
       editor.commands.focus("end");
       const trimmed = editor.state.doc.textContent.trim();
       setEditorHasText(trimmed.length > 0);
+      setSlotReferences([]);
       composerRuntime.setText(trimmed);
       onTextChangeRef.current?.(trimmed);
       try {
@@ -1523,6 +1762,7 @@ export function TiptapComposer({
         }
       } catch {}
     },
+    insertReference,
   }));
 
   const handleSelectMode = useCallback(
@@ -1663,10 +1903,15 @@ export function TiptapComposer({
   const extractComposerPayload = useCallback(() => {
     const ed = editor;
     if (!ed) {
-      return { text: "", references: [] as Reference[] };
+      return {
+        text: slotReferences.map((ref) => slotReferenceTitle(ref)).join(", "),
+        references: slotReferences.map(referenceFromComposerReference),
+      };
     }
 
-    const references: Reference[] = [];
+    const references: Reference[] = slotReferences.map(
+      referenceFromComposerReference,
+    );
 
     // Build text that preserves @mentions (getText() strips them).
     // Walk the document and reconstruct with @name for mention/file/skill nodes.
@@ -1691,7 +1936,10 @@ export function TiptapComposer({
         textParts.push("\n");
       }
     });
-    const text = textParts.join("").trim();
+    const rawText = textParts.join("").trim();
+    const text =
+      rawText ||
+      slotReferences.map((ref) => slotReferenceTitle(ref)).join(", ");
 
     ed.state.doc.descendants((node: any) => {
       if (node.type.name === "fileReference") {
@@ -1718,6 +1966,9 @@ export function TiptapComposer({
           source: node.attrs.source,
           refType: node.attrs.refType,
           refId: node.attrs.refId,
+          slotKey: node.attrs.slotKey,
+          slotLabel: node.attrs.slotLabel,
+          metadata: node.attrs.metadata,
         });
       } else if (node.type.name === "skillReference") {
         references.push({
@@ -1730,7 +1981,7 @@ export function TiptapComposer({
     });
 
     return { text, references };
-  }, [editor]);
+  }, [editor, slotReferences]);
 
   const syncComposerState = useCallback(() => {
     const { text, references } = extractComposerPayload();
@@ -1827,6 +2078,7 @@ export function TiptapComposer({
         cancelActiveVoice();
         ed.commands.clearContent();
         setEditorHasText(false);
+        setSlotReferences([]);
         setComposerMode(null);
         composerModeRef.current = null;
         try {
@@ -1849,6 +2101,7 @@ export function TiptapComposer({
         cancelActiveVoice();
         ed.commands.clearContent();
         setEditorHasText(false);
+        setSlotReferences([]);
         try {
           localStorage.removeItem(draftKey);
         } catch {}
@@ -1870,6 +2123,7 @@ export function TiptapComposer({
       cancelActiveVoice();
       ed.commands.clearContent();
       setEditorHasText(false);
+      setSlotReferences([]);
       try {
         localStorage.removeItem(draftKey);
       } catch {}
@@ -1901,22 +2155,8 @@ export function TiptapComposer({
     const currentPos = ed.state.selection.from;
     // startPos is after the trigger char, so -1 to include the @ or /
     const deleteFrom = Math.max(0, pop.startPos - 1);
-    ed.chain()
-      .focus()
-      .deleteRange({ from: deleteFrom, to: currentPos })
-      .insertContent({
-        type: "mentionReference",
-        attrs: {
-          label: item.label,
-          icon: item.icon || "file",
-          source: item.source,
-          refType: item.refType,
-          refId: item.refId || null,
-          refPath: item.refPath || null,
-        },
-      })
-      .insertContent(" ")
-      .run();
+    ed.chain().focus().deleteRange({ from: deleteFrom, to: currentPos }).run();
+    insertReference(composerReferenceFromMentionItem(item));
     popoverStateRef.current = null;
     setPopover(null);
   }
@@ -1968,22 +2208,11 @@ export function TiptapComposer({
         .chain()
         .focus()
         .deleteRange({ from: deleteFrom, to: currentPos })
-        .insertContent({
-          type: "mentionReference",
-          attrs: {
-            label: item.label,
-            icon: item.icon || "file",
-            source: item.source,
-            refType: item.refType,
-            refId: item.refId || null,
-            refPath: item.refPath || null,
-          },
-        })
-        .insertContent(" ")
         .run();
+      insertReference(composerReferenceFromMentionItem(item));
       closePopover();
     },
-    [editor, popover, closePopover],
+    [editor, popover, closePopover, insertReference],
   );
 
   const handleSelectCommand = useCallback(
@@ -2131,12 +2360,39 @@ export function TiptapComposer({
           />
         </div>
       )}
-      {hasContextItems && (
+      {hasContextRows && (
         <div
           data-agent-composer-variant={layoutVariant}
           data-agent-composer-slot="context-row"
           className="agent-composer-context-row flex flex-wrap gap-1.5 px-2.5 pt-2 pb-0"
         >
+          {slotReferences.map((ref) => (
+            <span
+              key={ref.slotKey}
+              className="inline-flex max-w-full items-center gap-1.5 rounded-md border border-border bg-background px-2 py-1 text-[11px] font-medium text-foreground shadow-sm"
+            >
+              <IconClipboardList className="h-3 w-3 shrink-0 text-muted-foreground" />
+              {ref.slotLabel && (
+                <span className="shrink-0 text-muted-foreground">
+                  {ref.slotLabel}
+                </span>
+              )}
+              <span className="min-w-0 truncate">{ref.label}</span>
+              <button
+                type="button"
+                onClick={() => {
+                  setSlotReferences((current) =>
+                    removeSlotReference(current, ref),
+                  );
+                  editor?.commands.focus("end");
+                }}
+                aria-label={`Remove ${slotReferenceTitle(ref)} reference`}
+                className="ms-0.5 flex h-4 w-4 shrink-0 items-center justify-center rounded text-muted-foreground hover:bg-accent hover:text-foreground"
+              >
+                <IconX className="h-3 w-3" />
+              </button>
+            </span>
+          ))}
           {contextItems.map((item) => (
             <span
               key={item.key}
@@ -2160,7 +2416,7 @@ export function TiptapComposer({
         data-agent-composer-variant={layoutVariant}
         data-agent-composer-slot="editor-wrap"
         className={`agent-composer-editor-wrap ${
-          composerMode || hasContextItems ? "px-2 pt-1 pb-1" : "px-2 pt-2 pb-1"
+          composerMode || hasContextRows ? "px-2 pt-1 pb-1" : "px-2 pt-2 pb-1"
         }`}
       >
         <EditorContent
@@ -2233,7 +2489,7 @@ export function TiptapComposer({
         ref={popoverRef}
         type={popover?.type ?? "@"}
         position={popover?.position ?? null}
-        mentionItems={mentionItems}
+        mentionItems={filteredMentionItems}
         skills={filteredSkills}
         commands={filteredCommands}
         hint={hint}

package/corpus/core/src/client/composer/extensions/MentionReference.tsx

@@ -66,6 +66,9 @@ export const MentionReference = Node.create({
       refType: { default: "file" },
       refId: { default: null },
       refPath: { default: null },
+      slotKey: { default: null },
+      slotLabel: { default: null },
+      metadata: { default: null },
     };
   },
 

package/corpus/core/src/client/composer/types.ts

@@ -22,6 +22,11 @@ export interface MentionItem {
   refPath?: string;
   refId?: string;
   section?: string;
+  slotKey?: string;
+  slotLabel?: string;
+  metadata?: Record<string, unknown>;
+  clearsSlots?: string[];
+  relatedReferences?: MentionReferenceInsert[];
 }
 
 export interface Reference {
@@ -31,6 +36,23 @@ export interface Reference {
   source: string;
   refType?: string;
   refId?: string;
+  slotKey?: string;
+  slotLabel?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface MentionReferenceInsert {
+  label: string;
+  icon?: string;
+  source?: string;
+  refType: string;
+  refId?: string | null;
+  refPath?: string | null;
+  slotKey?: string;
+  slotLabel?: string;
+  metadata?: Record<string, unknown>;
+  clearsSlots?: string[];
+  relatedReferences?: MentionReferenceInsert[];
 }
 
 export interface SlashCommand {

package/corpus/core/src/client/index.ts

@@ -11,7 +11,9 @@ export {
   appendAgentChatContextToMessage,
   clearAgentChatContext,
   formatAgentChatContextItemsForPrompt,
+  insertAgentComposerReference,
   listAgentChatContext,
+  normalizeAgentComposerReference,
   refreshAgentChatContext,
   removeAgentChatContextItem,
   sendToAgentChat,
@@ -27,6 +29,9 @@ export {
   type AgentChatContextSetOptions,
   type AgentChatContextState,
   type AgentChatMessage,
+  type AgentComposerReference,
+  type AgentComposerReferenceInsertOptions,
+  type AgentComposerReferenceInsertPayload,
 } from "./agent-chat.js";
 export {
   saveAgentEngineApiKey,

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -6660,6 +6660,11 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             refPath?: string;
             refId?: string;
             section?: string;
+            slotKey?: string;
+            slotLabel?: string;
+            metadata?: Record<string, unknown>;
+            clearsSlots?: string[];
+            relatedReferences?: unknown[];
           }
 
           const matchesQuery = (item: MentionItemResponse) =>
@@ -6796,6 +6801,11 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                         refPath: item.refPath,
                         refId: item.refId,
                         section: provider.label,
+                        slotKey: item.slotKey,
+                        slotLabel: item.slotLabel,
+                        metadata: item.metadata,
+                        clearsSlots: item.clearsSlots,
+                        relatedReferences: item.relatedReferences,
                       })),
                     );
                   } catch (e) {

package/corpus/core/src/server/request-context.ts

@@ -51,6 +51,14 @@ export interface RequestRunContext {
   engine?: import("../agent/engine/types.js").AgentEngine;
   /** Model name for this run (set by onEngineResolved). */
   model?: string;
+  /**
+   * True when this run is executing inside the durable background-function
+   * worker (the `_process-run` self-dispatch), not the synchronous foreground
+   * request. Template `extraContext` / system-prompt builders can read this to
+   * skip heavy, hang-prone enrichment (large data-dictionary DB reads, etc.)
+   * in the worker so it reliably claims its run within the setup budget.
+   */
+  isBackgroundWorker?: boolean;
   /** Tool calls made so far in the current agent loop. */
   toolCalls?: Array<{ name: string; input: unknown }>;
   /** Tool results returned so far in the current agent loop. */