@anuma/sdk 6.3.0 → 6.4.0

package/dist/expo/index.mjs

@@ -4986,6 +4986,153 @@ async function cleanupConversationSummary(database, conversationId) {
   }
 }
 
+// src/lib/chat/toolResultMessage.ts
+var HEADER = "[Tool Execution Results]\n\n";
+var FOOTER = "\n\nBased on these results, continue with the task.";
+var ENTRY_SEPARATOR = "\n\n";
+var TOOL_RESULT_FOOTER_LINE = FOOTER.trim();
+var MAX_PERSISTED_TOOL_RESULT_CHARS = 1e5;
+function buildToolResultContent(results) {
+  const entries = results.map((r) => `Tool "${r.name}" returned: ${JSON.stringify(r.result)}`);
+  const framing = HEADER.length + FOOTER.length + ENTRY_SEPARATOR.length * Math.max(0, entries.length - 1);
+  const summary = capEntries(entries, MAX_PERSISTED_TOOL_RESULT_CHARS - framing).join(
+    ENTRY_SEPARATOR
+  );
+  return `${HEADER}${summary}${FOOTER}`;
+}
+function capToolResultEntries(entries, budget) {
+  return capEntries(entries, budget);
+}
+function capEntries(entries, budget) {
+  const smallestFirst = entries.map((_, index) => index).sort((a, b) => entries[a].length - entries[b].length);
+  const capped = [...entries];
+  let remaining = budget;
+  let unassigned = entries.length;
+  for (const index of smallestFirst) {
+    capped[index] = truncateEntry(entries[index], Math.floor(remaining / unassigned));
+    remaining -= capped[index].length;
+    unassigned--;
+  }
+  return capped;
+}
+function truncateEntry(entry, allowance) {
+  if (entry.length <= allowance) return entry;
+  const keep = allowance - truncationMarker(entry.length).length;
+  if (keep <= 0) return entry.slice(0, Math.max(0, allowance));
+  return `${entry.slice(0, keep)}${truncationMarker(entry.length - keep)}`;
+}
+function truncationMarker(omitted) {
+  return `
+
+... (tool output truncated, ${omitted} characters omitted)`;
+}
+
+// src/lib/chat/toolResults.ts
+var TOOL_RESULTS_PREFIX = "[Tool Execution Results]";
+var DISPLAY_CARD_PLACEHOLDER = "[displayed a card to the user with the tool result]";
+var TOOL_LINE = /^Tool "([^"]+)" returned: (.*)$/;
+var TOOL_RESULT_ORIGIN = "tool_result";
+function isToolResultsRow(row) {
+  if (row.origin === TOOL_RESULT_ORIGIN) return true;
+  if (typeof row.origin === "string") return false;
+  if (row.role !== "user" || !row.content.startsWith(TOOL_RESULTS_PREFIX)) return false;
+  return parseToolResultSegments(row.content).length > 0;
+}
+function parseToolResultSegments(content) {
+  const segments = [];
+  for (const raw of content.split("\n")) {
+    const line = raw.trim();
+    const match = TOOL_LINE.exec(line);
+    if (match) {
+      segments.push({ name: match[1], line });
+      continue;
+    }
+    const current = segments[segments.length - 1];
+    if (!current || line === "" || line === TOOL_RESULT_FOOTER_LINE) continue;
+    if (line === TOOL_RESULTS_PREFIX) continue;
+    current.line = `${current.line}
+${line}`;
+  }
+  return segments;
+}
+function prepareToolResultsForReplay(rows, options) {
+  if (options.fold) {
+    return foldToolResultsRows(rows, {
+      exclude: options.exclude,
+      placeholder: options.placeholder
+    });
+  }
+  return rows.filter((row) => !isToolResultsRow(row));
+}
+function foldToolResultsRows(rows, options) {
+  const exclude = new Set(options?.exclude ?? []);
+  const out = [];
+  const pending = [];
+  const assistantIndexById = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    if (isToolResultsRow(row)) {
+      pending.push({ row, insertionPoint: out.length });
+      continue;
+    }
+    out.push(row);
+    if (row.role === "assistant" && row.uniqueId) {
+      assistantIndexById.set(row.uniqueId, out.length - 1);
+    }
+  }
+  const byTarget = /* @__PURE__ */ new Map();
+  for (const { row, insertionPoint } of pending) {
+    const target = resolveFoldTarget(out, row, insertionPoint, assistantIndexById);
+    if (target === void 0) continue;
+    const group = byTarget.get(target);
+    if (group) group.push(row);
+    else byTarget.set(target, [row]);
+  }
+  for (const [target, groupedRows] of byTarget) {
+    const assistant = out[target];
+    const kept = groupedRows.flatMap((row) => parseToolResultSegments(row.content)).filter((segment) => !exclude.has(segment.name));
+    if (kept.length > 0) {
+      out[target] = { ...assistant, content: appendToolResults(assistant.content, kept) };
+    } else if (!assistant.content.trim() && options?.placeholder) {
+      out[target] = { ...assistant, content: options.placeholder };
+    }
+  }
+  return out;
+}
+function resolveFoldTarget(out, row, insertionPoint, assistantIndexById) {
+  const linked = row.parentMessageId ? assistantIndexById.get(row.parentMessageId) : void 0;
+  if (linked !== void 0) return linked;
+  let previous;
+  for (let i = insertionPoint - 1; i >= 0; i--) {
+    if (out[i].role === "assistant") {
+      previous = i;
+      break;
+    }
+  }
+  let next;
+  for (let i = insertionPoint; i < out.length; i++) {
+    if (out[i].role === "assistant") {
+      next = i;
+      break;
+    }
+  }
+  if (previous === void 0) return next;
+  if (next === void 0) return previous;
+  return next - insertionPoint < insertionPoint - previous ? next : previous;
+}
+var MAX_FOLDED_APPENDIX_CHARS = 2e4;
+function appendToolResults(assistantContent, kept) {
+  const framing = TOOL_RESULTS_PREFIX.length + 1 + (kept.length - 1);
+  const capped = capToolResultEntries(
+    kept.map((segment) => segment.line),
+    MAX_FOLDED_APPENDIX_CHARS - framing
+  );
+  const appendix = `${TOOL_RESULTS_PREFIX}
+${capped.join("\n")}`;
+  return assistantContent.trim() ? `${assistantContent}
+
+${appendix}` : appendix;
+}
+
 // src/lib/db/chat/lazyDecrypt.ts
 var LRU_CAPACITY = 256;
 var titleCache = /* @__PURE__ */ new Map();
@@ -7061,6 +7208,9 @@ async function extractFacts(messages, options) {
     ...options.apiKey !== void 0 && { apiKey: options.apiKey },
     ...options.getToken !== void 0 && { getToken: options.getToken },
     ...options.baseUrl !== void 0 && { baseUrl: options.baseUrl },
+    ...options.endpointOverride !== void 0 && {
+      endpointOverride: options.endpointOverride
+    },
     model: options.model ?? DEFAULT_EXTRACTION_MODEL,
     systemPrompt: SYSTEM_PROMPT2,
     userMessage: `Today's date is ${today}. Resolve any relative dates ("yesterday", "next week") against it.
@@ -10530,11 +10680,17 @@ function useChatStorage(options) {
     onPiiRedacted,
     nerDetector,
     onServerToolCall,
-    onToolCallArgumentsDelta
+    onToolCallArgumentsDelta,
+    toolResultsHistoryExclude,
+    foldToolResultsInHistory
   } = options;
   const [currentConversationId, setCurrentConversationId] = useState4(
     initialConversationId || null
   );
+  const toolResultsHistoryExcludeRef = useRef4(toolResultsHistoryExclude);
+  toolResultsHistoryExcludeRef.current = toolResultsHistoryExclude;
+  const foldToolResultsInHistoryRef = useRef4(foldToolResultsInHistory);
+  foldToolResultsInHistoryRef.current = foldToolResultsInHistory;
   const nerDetectorRef = useRef4(nerDetector);
   nerDetectorRef.current = nerDetector;
   const resolvedPiiRedaction = useMemo(
@@ -11402,7 +11558,13 @@ function useChatStorage(options) {
       }
       if (includeHistory) {
         const validMessages = storedMessages.filter((msg) => !msg.error);
-        const limitedMessages = validMessages.slice(-maxHistoryMessages);
+        const replayableMessages = prepareToolResultsForReplay(validMessages, {
+          fold: foldToolResultsInHistoryRef.current === true,
+          exclude: toolResultsHistoryExcludeRef.current,
+          placeholder: DISPLAY_CARD_PLACEHOLDER
+        });
+        const limitedMessages = replayableMessages.slice(-maxHistoryMessages);
+        const foldedHistory = limitedMessages;
         if (summarizeHistory && !getTokenRef.current) {
           getLogger().warn(
             "[summarize] summarizeHistory is enabled but getToken is not provided \u2014 summarization will be skipped"
@@ -11412,7 +11574,7 @@ function useChatStorage(options) {
         const { messagesToConvert, summarySystemMessage } = await maybeSummarizeHistory({
           database,
           conversationId: convId,
-          messages: limitedMessages,
+          messages: foldedHistory,
           summarizeHistory,
           summaryTokenThreshold,
           summaryMinWindowMessages,
@@ -11782,6 +11944,7 @@ function useChatStorage(options) {
         uniqueId: effectiveAssistantUniqueId
       };
       let storedAssistantMessage;
+      let assistantMsgQueueId;
       try {
         const assistantMsgResult = await writeOrQueue(
           "createMessage",
@@ -11791,6 +11954,7 @@ function useChatStorage(options) {
           userMsgQueueId ? [userMsgQueueId] : []
         );
         storedAssistantMessage = assistantMsgResult.result;
+        assistantMsgQueueId = assistantMsgResult.queueId;
         if (!assistantMsgResult.queued) {
           void embedMessageAsync(storedAssistantMessage, maskForCall);
         }
@@ -11801,6 +11965,29 @@ function useChatStorage(options) {
           userMessage: storedUserMessage
         };
       }
+      const autoToolResults = result.autoExecutedToolResults;
+      let storedToolResultsMessage;
+      if (autoToolResults && autoToolResults.length > 0) {
+        const toolResultsOpts = {
+          conversationId: convId,
+          role: "user",
+          content: buildToolResultContent(autoToolResults),
+          model: "",
+          parentMessageId: storedAssistantMessage.uniqueId,
+          origin: TOOL_RESULT_ORIGIN
+        };
+        try {
+          const toolResultsWrite = await writeOrQueue(
+            "createMessage",
+            toolResultsOpts,
+            () => createMessageOp(storageCtx, toolResultsOpts),
+            () => makeSyntheticStoredMessage(toolResultsOpts),
+            assistantMsgQueueId ? [assistantMsgQueueId] : []
+          );
+          storedToolResultsMessage = toolResultsWrite.result;
+        } catch {
+        }
+      }
       const refreshGetToken = getTokenRef.current;
       if (refreshGetToken) {
         Promise.resolve().then(() => shouldRefreshTools(getToolsChecksum(responseData), serverToolsConfig?.cache)).then((refresh) => {
@@ -11820,7 +12007,9 @@ function useChatStorage(options) {
         data: responseData,
         error: null,
         userMessage: storedUserMessage,
-        assistantMessage: storedAssistantMessage
+        assistantMessage: storedAssistantMessage,
+        autoExecutedToolResults: autoToolResults,
+        toolResultsMessage: storedToolResultsMessage
       };
     },
     [

package/dist/react/index.cjs

@@ -14936,6 +14936,7 @@ async function cleanupConversationSummary(database, conversationId) {
 var HEADER = "[Tool Execution Results]\n\n";
 var FOOTER = "\n\nBased on these results, continue with the task.";
 var ENTRY_SEPARATOR = "\n\n";
+var TOOL_RESULT_FOOTER_LINE = FOOTER.trim();
 var MAX_PERSISTED_TOOL_RESULT_CHARS = 1e5;
 function buildToolResultContent(results) {
   const entries = results.map((r) => `Tool "${r.name}" returned: ${JSON.stringify(r.result)}`);
@@ -14945,6 +14946,9 @@ function buildToolResultContent(results) {
   );
   return `${HEADER}${summary}${FOOTER}`;
 }
+function capToolResultEntries(entries, budget) {
+  return capEntries(entries, budget);
+}
 function capEntries(entries, budget) {
   const smallestFirst = entries.map((_, index) => index).sort((a, b) => entries[a].length - entries[b].length);
   const capped = [...entries];
@@ -14969,6 +14973,112 @@ function truncationMarker(omitted) {
 ... (tool output truncated, ${omitted} characters omitted)`;
 }
 
+// src/lib/chat/toolResults.ts
+var TOOL_RESULTS_PREFIX = "[Tool Execution Results]";
+var DISPLAY_CARD_PLACEHOLDER = "[displayed a card to the user with the tool result]";
+var TOOL_LINE = /^Tool "([^"]+)" returned: (.*)$/;
+var TOOL_RESULT_ORIGIN = "tool_result";
+function isToolResultsRow(row) {
+  if (row.origin === TOOL_RESULT_ORIGIN) return true;
+  if (typeof row.origin === "string") return false;
+  if (row.role !== "user" || !row.content.startsWith(TOOL_RESULTS_PREFIX)) return false;
+  return parseToolResultSegments(row.content).length > 0;
+}
+function parseToolResultSegments(content) {
+  const segments = [];
+  for (const raw of content.split("\n")) {
+    const line = raw.trim();
+    const match = TOOL_LINE.exec(line);
+    if (match) {
+      segments.push({ name: match[1], line });
+      continue;
+    }
+    const current = segments[segments.length - 1];
+    if (!current || line === "" || line === TOOL_RESULT_FOOTER_LINE) continue;
+    if (line === TOOL_RESULTS_PREFIX) continue;
+    current.line = `${current.line}
+${line}`;
+  }
+  return segments;
+}
+function prepareToolResultsForReplay(rows, options) {
+  if (options.fold) {
+    return foldToolResultsRows(rows, {
+      exclude: options.exclude,
+      placeholder: options.placeholder
+    });
+  }
+  return rows.filter((row) => !isToolResultsRow(row));
+}
+function foldToolResultsRows(rows, options) {
+  const exclude = new Set(options?.exclude ?? []);
+  const out = [];
+  const pending = [];
+  const assistantIndexById = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    if (isToolResultsRow(row)) {
+      pending.push({ row, insertionPoint: out.length });
+      continue;
+    }
+    out.push(row);
+    if (row.role === "assistant" && row.uniqueId) {
+      assistantIndexById.set(row.uniqueId, out.length - 1);
+    }
+  }
+  const byTarget = /* @__PURE__ */ new Map();
+  for (const { row, insertionPoint } of pending) {
+    const target = resolveFoldTarget(out, row, insertionPoint, assistantIndexById);
+    if (target === void 0) continue;
+    const group = byTarget.get(target);
+    if (group) group.push(row);
+    else byTarget.set(target, [row]);
+  }
+  for (const [target, groupedRows] of byTarget) {
+    const assistant = out[target];
+    const kept = groupedRows.flatMap((row) => parseToolResultSegments(row.content)).filter((segment) => !exclude.has(segment.name));
+    if (kept.length > 0) {
+      out[target] = { ...assistant, content: appendToolResults(assistant.content, kept) };
+    } else if (!assistant.content.trim() && options?.placeholder) {
+      out[target] = { ...assistant, content: options.placeholder };
+    }
+  }
+  return out;
+}
+function resolveFoldTarget(out, row, insertionPoint, assistantIndexById) {
+  const linked = row.parentMessageId ? assistantIndexById.get(row.parentMessageId) : void 0;
+  if (linked !== void 0) return linked;
+  let previous;
+  for (let i = insertionPoint - 1; i >= 0; i--) {
+    if (out[i].role === "assistant") {
+      previous = i;
+      break;
+    }
+  }
+  let next;
+  for (let i = insertionPoint; i < out.length; i++) {
+    if (out[i].role === "assistant") {
+      next = i;
+      break;
+    }
+  }
+  if (previous === void 0) return next;
+  if (next === void 0) return previous;
+  return next - insertionPoint < insertionPoint - previous ? next : previous;
+}
+var MAX_FOLDED_APPENDIX_CHARS = 2e4;
+function appendToolResults(assistantContent, kept) {
+  const framing = TOOL_RESULTS_PREFIX.length + 1 + (kept.length - 1);
+  const capped = capToolResultEntries(
+    kept.map((segment) => segment.line),
+    MAX_FOLDED_APPENDIX_CHARS - framing
+  );
+  const appendix = `${TOOL_RESULTS_PREFIX}
+${capped.join("\n")}`;
+  return assistantContent.trim() ? `${assistantContent}
+
+${appendix}` : appendix;
+}
+
 // src/lib/db/chat/lazyDecrypt.ts
 init_useEncryption();
 init_encryption_utils();
@@ -17543,6 +17653,9 @@ async function extractFacts(messages, options) {
     ...options.apiKey !== void 0 && { apiKey: options.apiKey },
     ...options.getToken !== void 0 && { getToken: options.getToken },
     ...options.baseUrl !== void 0 && { baseUrl: options.baseUrl },
+    ...options.endpointOverride !== void 0 && {
+      endpointOverride: options.endpointOverride
+    },
     model: options.model ?? DEFAULT_EXTRACTION_MODEL,
     systemPrompt: SYSTEM_PROMPT4,
     userMessage: `Today's date is ${today}. Resolve any relative dates ("yesterday", "next week") against it.
@@ -22321,11 +22434,17 @@ function useChatStorage(options) {
     preProcessors,
     piiRedaction,
     onPiiRedacted,
-    nerDetector
+    nerDetector,
+    toolResultsHistoryExclude,
+    foldToolResultsInHistory
   } = options;
   const [currentConversationId, setCurrentConversationId] = (0, import_react5.useState)(
     initialConversationId || null
   );
+  const toolResultsHistoryExcludeRef = (0, import_react5.useRef)(toolResultsHistoryExclude);
+  toolResultsHistoryExcludeRef.current = toolResultsHistoryExclude;
+  const foldToolResultsInHistoryRef = (0, import_react5.useRef)(foldToolResultsInHistory);
+  foldToolResultsInHistoryRef.current = foldToolResultsInHistory;
   const nerDetectorRef = (0, import_react5.useRef)(nerDetector);
   nerDetectorRef.current = nerDetector;
   const resolvedPiiRedaction = (0, import_react5.useMemo)(
@@ -23333,7 +23452,12 @@ function useChatStorage(options) {
       }
       if (includeHistory) {
         const validMessages = storedMessages.filter((msg) => !msg.error);
-        const limitedMessages = validMessages.slice(-maxHistoryMessages);
+        const replayableMessages = prepareToolResultsForReplay(validMessages, {
+          fold: foldToolResultsInHistoryRef.current === true,
+          exclude: toolResultsHistoryExcludeRef.current,
+          placeholder: DISPLAY_CARD_PLACEHOLDER
+        });
+        const limitedMessages = replayableMessages.slice(-maxHistoryMessages);
         if (!fileContextForRequest) {
           for (let i = limitedMessages.length - 1; i >= 0; i--) {
             const msg = limitedMessages[i];
@@ -23343,6 +23467,7 @@ function useChatStorage(options) {
             }
           }
         }
+        const foldedHistory = limitedMessages;
         let encryptionKey;
         if (walletAddress && hasEncryptionKey(walletAddress) && isOPFSSupported()) {
           try {
@@ -23359,7 +23484,7 @@ function useChatStorage(options) {
         const { messagesToConvert, summarySystemMessage } = await maybeSummarizeHistory({
           database,
           conversationId: convId,
-          messages: limitedMessages,
+          messages: foldedHistory,
           summarizeHistory,
           summaryTokenThreshold,
           summaryMinWindowMessages,
@@ -23817,37 +23942,25 @@ function useChatStorage(options) {
         }
       }
       const autoToolResults = result.autoExecutedToolResults;
+      let storedToolResultsMessage;
       if (autoToolResults && autoToolResults.length > 0) {
-        const toolResultContent = buildToolResultContent(autoToolResults);
+        const toolResultsOpts = {
+          conversationId: convId,
+          role: "user",
+          content: buildToolResultContent(autoToolResults),
+          model: "",
+          parentMessageId: storedAssistantMessage.uniqueId,
+          origin: TOOL_RESULT_ORIGIN
+        };
         try {
-          await writeOrQueue(
+          const toolResultsWrite = await writeOrQueue(
             "createMessage",
-            {
-              conversationId: convId,
-              role: "user",
-              content: toolResultContent,
-              model: "",
-              parentMessageId: storedAssistantMessage.uniqueId,
-              origin: "tool_result"
-            },
-            () => createMessageOp(storageCtx, {
-              conversationId: convId,
-              role: "user",
-              content: toolResultContent,
-              model: "",
-              parentMessageId: storedAssistantMessage.uniqueId,
-              origin: "tool_result"
-            }),
-            () => makeSyntheticStoredMessage({
-              conversationId: convId,
-              role: "user",
-              content: toolResultContent,
-              model: "",
-              parentMessageId: storedAssistantMessage.uniqueId,
-              origin: "tool_result"
-            }),
+            toolResultsOpts,
+            () => createMessageOp(storageCtx, toolResultsOpts),
+            () => makeSyntheticStoredMessage(toolResultsOpts),
             assistantMsgQueueId ? [assistantMsgQueueId] : []
           );
+          storedToolResultsMessage = toolResultsWrite.result;
         } catch {
         }
       }
@@ -23870,7 +23983,8 @@ function useChatStorage(options) {
         error: null,
         userMessage: storedUserMessage,
         assistantMessage: storedAssistantMessage,
-        autoExecutedToolResults: result.autoExecutedToolResults
+        autoExecutedToolResults: autoToolResults,
+        toolResultsMessage: storedToolResultsMessage
       };
     },
     // eslint-disable-next-line react-hooks/exhaustive-deps -- intentionally omitting stable refs and config values that don't change identity

package/dist/react/index.d.mts

@@ -5220,6 +5220,40 @@ interface BaseUseChatStorageOptions {
      * Defaults to the hardcoded MCP_R2_DOMAIN from clientConfig.
      */
     mcpR2Domain?: string;
+    /**
+     * Tool names whose persisted results must never be replayed to the model.
+     *
+     * A turn's auto-executed tool results are stored as a synthetic
+     * `[Tool Execution Results]` row and, on a replayed send, folded back onto the
+     * assistant turn they belong to — that is what lets a follow-up question about a
+     * tool's output work after a reload. Name a tool here when its payload exists for
+     * the RENDERER rather than the model: a display card can carry data the model was
+     * deliberately never given (People Nearby's card holds third parties' snapped
+     * coordinates, which the search result strips), and replaying it would hand that
+     * data straight back.
+     *
+     * Hook-level rather than per-send on purpose: an exclusion that has to be
+     * remembered at every call site is one bad send away from leaking.
+     */
+    toolResultsHistoryExclude?: string[];
+    /**
+     * Fold persisted `[Tool Execution Results]` rows onto the assistant turn that produced them
+     * when replaying stored history, instead of dropping them.
+     *
+     * **Defaults to `false`, and that default is deliberate.** Folding is the better behaviour —
+     * it is what lets a follow-up about a tool's output work after a reload — but it moves the
+     * payload from a `role: "user"` row onto an `assistant` row. Any consumer that scrubs these
+     * rows by checking `role === "user"` plus the content prefix (which is how both apps did it
+     * before this option existed) stops catching them the moment folding turns on, and starts
+     * replaying whatever the row held. Opting in is therefore a statement that the caller has
+     * checked its own filters and set {@link toolResultsHistoryExclude} for any payload that must
+     * not reach the model.
+     *
+     * With it off, rows are dropped from the replayed history rather than sent verbatim. Verbatim
+     * would put two consecutive `user` turns on the wire, and the model answers the previous turn
+     * instead of the new prompt.
+     */
+    foldToolResultsInHistory?: boolean;
     /**
      * Pre-processors run after the last user message is received but before
      * the first LLM request. Each receives the prompt text and a shared
@@ -7094,6 +7128,31 @@ interface QuarantinedMemoryInfo {
 interface ExtractFactsOptions extends PortalLlmAuth {
     baseUrl?: string;
     model?: string;
+    /**
+     * Optional per-call request path override, forwarded to
+     * {@link callPortalJsonCompletion}. When set, the extraction call POSTs to
+     * `baseUrl + endpointOverride` instead of the default
+     * `/api/v1/chat/completions` — path only, body unchanged. Lets callers route
+     * this internal-utility pass to a dedicated endpoint. Invalid values throw at
+     * call time (see {@link validateEndpointOverride}).
+     *
+     * Why this exists (anuma-ai/ai-memoryless-client#5536): auto-extraction is the
+     * highest-volume first-party background call in the product — one per
+     * extracting turn, on every platform — and it carries no flow fingerprint, so
+     * the portal's freeloader detector classifies it as scripted abuse. In reject
+     * mode that 403s every basic-tier extraction, which surfaces here as
+     * `onExhaustedEmpty` → `empty-after-retry` and leaves free-tier vaults empty.
+     * {@link TopicExtractOptions.endpointOverride} already exists for the same
+     * reason on the topic pass; this is the fact pass catching up.
+     *
+     * IMPORTANT — the utility endpoint clamps to a PRICE CEILING and never
+     * rejects, so pointing this at `/api/v1/utility/chat/completions` while the
+     * portal's ceiling prices below {@link DEFAULT_EXTRACTION_MODEL} silently
+     * rewrites the model instead of 403-ing. That trades a visible failure for an
+     * invisible quality regression: raise `PORTAL_UTILITY_CEILING_MODEL` to at
+     * least the extraction model's rate BEFORE setting this in a client.
+     */
+    endpointOverride?: string;
     /** Override the global fetch implementation (useful for tests). */
     fetchFn?: typeof fetch;
     /**
@@ -10329,6 +10388,12 @@ type SendMessageWithStorageResult = {
         name: string;
         result: unknown;
     }[];
+    /**
+     * The synthetic `[Tool Execution Results]` row those results were persisted as, so a caller can
+     * key its transient overlay on the id the SDK actually wrote instead of deriving one (#5519).
+     * Absent when no tool ran, or when that (non-fatal) write failed.
+     */
+    toolResultsMessage?: StoredMessage;
 } | {
     data: ApiResponse;
     error: null;

package/dist/react/index.d.ts

@@ -5220,6 +5220,40 @@ interface BaseUseChatStorageOptions {
      * Defaults to the hardcoded MCP_R2_DOMAIN from clientConfig.
      */
     mcpR2Domain?: string;
+    /**
+     * Tool names whose persisted results must never be replayed to the model.
+     *
+     * A turn's auto-executed tool results are stored as a synthetic
+     * `[Tool Execution Results]` row and, on a replayed send, folded back onto the
+     * assistant turn they belong to — that is what lets a follow-up question about a
+     * tool's output work after a reload. Name a tool here when its payload exists for
+     * the RENDERER rather than the model: a display card can carry data the model was
+     * deliberately never given (People Nearby's card holds third parties' snapped
+     * coordinates, which the search result strips), and replaying it would hand that
+     * data straight back.
+     *
+     * Hook-level rather than per-send on purpose: an exclusion that has to be
+     * remembered at every call site is one bad send away from leaking.
+     */
+    toolResultsHistoryExclude?: string[];
+    /**
+     * Fold persisted `[Tool Execution Results]` rows onto the assistant turn that produced them
+     * when replaying stored history, instead of dropping them.
+     *
+     * **Defaults to `false`, and that default is deliberate.** Folding is the better behaviour —
+     * it is what lets a follow-up about a tool's output work after a reload — but it moves the
+     * payload from a `role: "user"` row onto an `assistant` row. Any consumer that scrubs these
+     * rows by checking `role === "user"` plus the content prefix (which is how both apps did it
+     * before this option existed) stops catching them the moment folding turns on, and starts
+     * replaying whatever the row held. Opting in is therefore a statement that the caller has
+     * checked its own filters and set {@link toolResultsHistoryExclude} for any payload that must
+     * not reach the model.
+     *
+     * With it off, rows are dropped from the replayed history rather than sent verbatim. Verbatim
+     * would put two consecutive `user` turns on the wire, and the model answers the previous turn
+     * instead of the new prompt.
+     */
+    foldToolResultsInHistory?: boolean;
     /**
      * Pre-processors run after the last user message is received but before
      * the first LLM request. Each receives the prompt text and a shared
@@ -7094,6 +7128,31 @@ interface QuarantinedMemoryInfo {
 interface ExtractFactsOptions extends PortalLlmAuth {
     baseUrl?: string;
     model?: string;
+    /**
+     * Optional per-call request path override, forwarded to
+     * {@link callPortalJsonCompletion}. When set, the extraction call POSTs to
+     * `baseUrl + endpointOverride` instead of the default
+     * `/api/v1/chat/completions` — path only, body unchanged. Lets callers route
+     * this internal-utility pass to a dedicated endpoint. Invalid values throw at
+     * call time (see {@link validateEndpointOverride}).
+     *
+     * Why this exists (anuma-ai/ai-memoryless-client#5536): auto-extraction is the
+     * highest-volume first-party background call in the product — one per
+     * extracting turn, on every platform — and it carries no flow fingerprint, so
+     * the portal's freeloader detector classifies it as scripted abuse. In reject
+     * mode that 403s every basic-tier extraction, which surfaces here as
+     * `onExhaustedEmpty` → `empty-after-retry` and leaves free-tier vaults empty.
+     * {@link TopicExtractOptions.endpointOverride} already exists for the same
+     * reason on the topic pass; this is the fact pass catching up.
+     *
+     * IMPORTANT — the utility endpoint clamps to a PRICE CEILING and never
+     * rejects, so pointing this at `/api/v1/utility/chat/completions` while the
+     * portal's ceiling prices below {@link DEFAULT_EXTRACTION_MODEL} silently
+     * rewrites the model instead of 403-ing. That trades a visible failure for an
+     * invisible quality regression: raise `PORTAL_UTILITY_CEILING_MODEL` to at
+     * least the extraction model's rate BEFORE setting this in a client.
+     */
+    endpointOverride?: string;
     /** Override the global fetch implementation (useful for tests). */
     fetchFn?: typeof fetch;
     /**
@@ -10329,6 +10388,12 @@ type SendMessageWithStorageResult = {
         name: string;
         result: unknown;
     }[];
+    /**
+     * The synthetic `[Tool Execution Results]` row those results were persisted as, so a caller can
+     * key its transient overlay on the id the SDK actually wrote instead of deriving one (#5519).
+     * Absent when no tool ran, or when that (non-fatal) write failed.
+     */
+    toolResultsMessage?: StoredMessage;
 } | {
     data: ApiResponse;
     error: null;