@anuma/sdk 3.0.0 → 3.1.0

package/dist/expo/index.d.mts

@@ -2786,6 +2786,13 @@ type SendMessageArgs = BaseSendMessageArgs & {
      * This is typically extracted text from preprocessed file attachments.
      */
     fileContext?: string;
+    /**
+     * Tool-set guidance to inject as a system message — the persona/usage prompt
+     * for whichever tool sets activated this turn (e.g. the app-builder prompt).
+     * Additive: composes with the other context messages, never replaces them.
+     * Mirrors react's useChat toolGuidance channel.
+     */
+    toolGuidance?: string;
     /**
      * Override the API type for this request only.
      * Useful when different models need different APIs.
@@ -3130,6 +3137,33 @@ interface CachedServerTools {
     /** Checksum from the server for cache invalidation */
     checksum?: string;
 }
+/**
+ * Pluggable persistence for the fetched server-tools list.
+ *
+ * The default backend ({@link localStorageToolsCache}) writes to browser
+ * `localStorage` and is a silent no-op where `localStorage` is undefined
+ * (Node, React Native). Pass a custom backend to `getServerTools` to cache
+ * somewhere that survives on those platforms — e.g. an AsyncStorage/MMKV
+ * adapter on RN, or an in-memory `Map` on a server. Methods may be sync or
+ * async; `getServerTools` awaits them either way.
+ *
+ * The stored payload carries a `version`; `getServerTools` discards any entry
+ * whose version does not match the current cache format, so a stale custom
+ * backend can never feed an incompatible shape back into selection.
+ */
+interface ToolsCacheBackend {
+    /** Return the cached payload, or null when absent/unreadable. */
+    get(): CachedServerTools | null | Promise<CachedServerTools | null>;
+    /** Persist the payload. Implementations should swallow write failures. */
+    set(value: CachedServerTools): void | Promise<void>;
+    /**
+     * Remove the cached payload. Optional — a read/write-only backend may omit it,
+     * in which case `clearServerToolsCache` (and the version-mismatch
+     * invalidation) is a no-op for that backend. The default
+     * {@link localStorageToolsCache} implements it.
+     */
+    clear?(): void | Promise<void>;
+}
 /**
  * Options for fetching server tools
  */
@@ -3144,6 +3178,12 @@ interface ServerToolsOptions {
     getToken?: () => Promise<string | null>;
     /** Direct API key for server-side usage (uses X-API-Key header) */
     apiKey?: string;
+    /**
+     * Where to read/write the cached tools list. Defaults to
+     * {@link localStorageToolsCache} (browser `localStorage`; no-op elsewhere).
+     * Provide a backend to enable caching on Node / React Native.
+     */
+    cache?: ToolsCacheBackend;
 }
 /** Default cache expiration: 1 day */
 declare const DEFAULT_CACHE_EXPIRATION_MS: number;
@@ -3152,14 +3192,18 @@ declare const DEFAULT_CACHE_EXPIRATION_MS: number;
  */
 declare function getCachedServerTools(): CachedServerTools | null;
 /**
- * Clear the server tools cache
+ * Clear the cached server tools. Defaults to the browser-`localStorage` backend;
+ * pass the SAME {@link ToolsCacheBackend} you gave `getServerTools` to invalidate
+ * a custom backend (a no-op when that backend defines no `clear`). Returns the
+ * backend's clear result, which may be async.
  */
 declare function clearServerToolsCache(): void;
+declare function clearServerToolsCache(cache: ToolsCacheBackend): void | Promise<void>;
 /**
  * Get server tools with caching support.
  *
  * Flow:
- * 1. Check localStorage cache
+ * 1. Check the cache backend (localStorage by default; override via `cache`)
  * 2. If cache valid and not force refresh, return cached tools
  * 3. Otherwise, fetch from API, cache, and return
  * 4. On fetch failure, return cached tools if available (stale-while-error)
@@ -3179,6 +3223,52 @@ interface DeferLoadingConfig {
     /** Server-tool names to keep non-deferred (besides the tool-search tool), in priority order. */
     hotToolNames: readonly string[];
 }
+/**
+ * A tool set defines a group of tools that work together. When any "anchor"
+ * tool in the set is matched semantically (with a score at or above
+ * `anchorMinSimilarity`), the set is activated and all of its members are
+ * pulled into the selection.
+ *
+ * Two activation strategies consume this interface:
+ * - `expandToolSetsAdditive` (used by `useChatStorage` and
+ *   `createServerToolsFilter`) keeps all original matches and adds the
+ *   set's members on top — non-set tools are never dropped.
+ * - `applyToolSets` is exclusive: it keeps only set members plus non-set
+ *   tools that scored above `independentThreshold`.
+ *
+ * Pick `expandToolSetsAdditive` when you want recall over precision
+ * (typical), and `applyToolSets` when you specifically want non-set
+ * matches stripped on activation.
+ */
+interface ToolSet {
+    /** Human-readable name for logging/debugging */
+    name: string;
+    /** All tool names in the set */
+    members: string[];
+    /**
+     * Tools that trigger the set when selected. If any anchor appears in the
+     * semantic match results with a score at or above `anchorMinSimilarity`,
+     * all members are pulled in.
+     */
+    anchors: string[];
+    /**
+     * Minimum similarity an anchor must reach to activate the set.
+     * Prevents false activation on prompts where the anchor barely passes
+     * the global minSimilarity threshold. Default: 0.60
+     */
+    anchorMinSimilarity?: number;
+    /**
+     * System-prompt fragment to APPEND to the base prompt when this set
+     * activates. Additive, never a replacement — it composes with the host's
+     * persona / memory. Gated on genuine activation (anchor score ≥
+     * `anchorMinSimilarity`, or a forced set) via {@link activatedToolSetNames} →
+     * {@link toolSetSystemPrompts}, NOT on mere anchor presence — a borderline
+     * anchor kept by recall-over-precision must not drag this persona in. Write
+     * it to be self-limiting too (condition its behavior on the user actually
+     * wanting what the set does), so a borderline activation doesn't bias the turn.
+     */
+    systemPrompt?: string;
+}
 
 /**
  * Function type for dynamic server tools filtering based on prompt embeddings.
@@ -3541,6 +3631,13 @@ interface BaseUseChatStorageOptions {
          * {@link DeferLoadingConfig}.
          */
         deferLoading?: DeferLoadingConfig;
+        /**
+         * Where to read/write the cached server-tools catalog. Defaults to browser
+         * `localStorage`, which is a silent no-op on React Native — so on RN pass an
+         * AsyncStorage/MMKV-backed {@link ToolsCacheBackend} here or every send
+         * refetches the whole catalog. Forwarded to `getServerTools`.
+         */
+        cache?: ToolsCacheBackend;
     };
     /**
      * Automatically generate embeddings for messages after saving.
@@ -5892,14 +5989,14 @@ declare function createChunkVectorCache(maxSize?: number): ChunkVectorCache;
 declare function recall(query: string, ctx: RecallContext, options?: RecallOptions): Promise<RecallResult>;
 
 /**
- * Unified Recall Tool
+ * Recall tool constants — deliberately dependency-free.
  *
- * Single chat-completion tool that searches both vault facts and
- * conversation chunks via `recall()`. Replaces the legacy pair of
- * `memory_vault_search` (facts) + `search_memory` (chunks) — the LLM no
- * longer has to route between two tools.
+ * Split out of `recallTool.ts` so the tool NAME can be referenced from
+ * node/React-Native-safe modules (e.g. the client-tool selector in
+ * `../tools/clientToolSelection`) without dragging `recall()` and its
+ * WatermelonDB-backed operations into the module graph. `recallTool.ts`
+ * re-exports these to preserve their public identity.
  */
-
 /** Tool name surfaced to the LLM. Exported so bench harnesses and chat
  * clients reference the same string — drift between prod and bench would
  * mask tool-routing bugs in eval. */
@@ -5907,6 +6004,16 @@ declare const RECALL_TOOL_NAME = "recall_memory";
 /** Maximum results the executor will return to the LLM, regardless of
  * the LLM-supplied `limit`. */
 declare const RECALL_MAX_LIMIT = 50;
+
+/**
+ * Unified Recall Tool
+ *
+ * Single chat-completion tool that searches both vault facts and
+ * conversation chunks via `recall()`. Replaces the legacy pair of
+ * `memory_vault_search` (facts) + `search_memory` (chunks) — the LLM no
+ * longer has to route between two tools.
+ */
+
 interface RecallToolOptions {
     /** Lanes to search. Default: ["fact", "chunk"]. */
     types?: MemoryKind[];
@@ -6210,11 +6317,26 @@ declare function chunkText(text: string, options?: ChunkingOptions): TextChunk[]
 declare function shouldChunkMessage(content: string, chunkSize?: number): boolean;
 
 /**
- * Memory Retrieval Embeddings
+ * Embedding generation — dependency-free core.
  *
- * Functions for generating and storing embeddings for conversation messages.
+ * The raw "text → embedding" calls, split out of `embeddings.ts` so they can be
+ * imported by node/React-Native-safe modules (the server-tool + client-tool
+ * selection engine in `../tools`) WITHOUT pulling in the WatermelonDB-backed
+ * `db/chat/operations` that `embeddings.ts` needs for its message-persistence
+ * helpers (`embedMessage`, `embedAllMessages`, `chunkAndEmbed*`).
+ *
+ * Nothing here touches the database; the only I/O is the HTTP embeddings
+ * endpoint. `embeddings.ts` re-exports these so existing importers of
+ * `../memoryEngine/embeddings` (and the `../memoryEngine` barrel) keep working.
  */
 
+/**
+ * Generate an embedding for text using the API
+ *
+ * Supports two auth methods:
+ * - `apiKey`: Uses X-API-Key header (for server-side/CLI usage)
+ * - `getToken`: Uses Authorization: Bearer header (for Privy identity tokens)
+ */
 declare function generateEmbedding(text: string, options: EmbeddingOptions): Promise<number[]>;
 /**
  * Generate embeddings for multiple texts, automatically chunking large inputs.
@@ -6229,6 +6351,18 @@ declare function generateEmbedding(text: string, options: EmbeddingOptions): Pro
  * @returns Array of embeddings in the same order as input texts
  */
 declare function generateEmbeddings(texts: string[], options: EmbeddingOptions): Promise<number[][]>;
+
+/**
+ * Memory Retrieval Embeddings
+ *
+ * Message-level embedding + persistence helpers: find messages via the
+ * WatermelonDB-backed `db/chat/operations`, embed their content, and store the
+ * vectors/chunks back. The raw "text → embedding" calls live in `./generate`
+ * (dependency-free so the tool-selection engine can import them without the DB
+ * layer) and are re-exported here so existing importers of
+ * `../memoryEngine/embeddings` and the `../memoryEngine` barrel keep working.
+ */
+
 /**
  * Embed a single message and store the embedding in the database
  *
@@ -6523,6 +6657,31 @@ interface UseChatStorageOptions extends BaseUseChatStorageOptions {
      * Auto-flush queued operations when key becomes available. @default true
      */
     autoFlushOnKeyAvailable?: boolean;
+    /**
+     * Additional tool sets to apply on top of the built-in ones (app-generation,
+     * slides, github). When any anchor tool in a custom set is selected by
+     * semantic matching, all members of that set are included automatically.
+     *
+     * Treated as static config — set once at hook setup. Changing it across
+     * renders does not affect in-flight `sendMessage` calls; use
+     * `activeToolSets` for dynamic, conversation-state-driven overrides.
+     */
+    extraToolSets?: ToolSet[];
+    /**
+     * Tool set names that should expand unconditionally for this request,
+     * bypassing the anchor-similarity check. Use when conversation state
+     * implies a set should be present regardless of how the prompt is phrased
+     * — e.g., pass `["documents"]` when the conversation already contains a
+     * generated document, so short follow-up prompts ("make the background red")
+     * still get the full document toolkit.
+     *
+     * Read via a ref so updates are visible to in-flight `sendMessage` calls
+     * without rebuilding the callback.
+     *
+     * Names must match a set's `name` from `BUILT_IN_TOOL_SETS` or
+     * `extraToolSets`. Unknown names are ignored.
+     */
+    activeToolSets?: string[];
     /**
      * Opt into resumable streaming. When `true`, `sendMessage` sends the
      * resumable capability header, a stable `assistantUniqueId` is allocated for
@@ -6558,6 +6717,16 @@ interface UseChatStorageOptions extends BaseUseChatStorageOptions {
         model?: string;
         round?: number;
     }) => void;
+    /**
+     * Observability hook fired once per send with the tools actually selected for
+     * the turn (after server + client filtering). Never throws into the send path.
+     * Mirrors react's onToolSelection.
+     */
+    onToolSelection?: (info: {
+        prompt: string;
+        clientToolNames: string[];
+        serverToolNames: string[];
+    }) => void;
 }
 /**
  * Arguments for sendMessage with storage (Expo version)

package/dist/expo/index.d.ts

@@ -2786,6 +2786,13 @@ type SendMessageArgs = BaseSendMessageArgs & {
      * This is typically extracted text from preprocessed file attachments.
      */
     fileContext?: string;
+    /**
+     * Tool-set guidance to inject as a system message — the persona/usage prompt
+     * for whichever tool sets activated this turn (e.g. the app-builder prompt).
+     * Additive: composes with the other context messages, never replaces them.
+     * Mirrors react's useChat toolGuidance channel.
+     */
+    toolGuidance?: string;
     /**
      * Override the API type for this request only.
      * Useful when different models need different APIs.
@@ -3130,6 +3137,33 @@ interface CachedServerTools {
     /** Checksum from the server for cache invalidation */
     checksum?: string;
 }
+/**
+ * Pluggable persistence for the fetched server-tools list.
+ *
+ * The default backend ({@link localStorageToolsCache}) writes to browser
+ * `localStorage` and is a silent no-op where `localStorage` is undefined
+ * (Node, React Native). Pass a custom backend to `getServerTools` to cache
+ * somewhere that survives on those platforms — e.g. an AsyncStorage/MMKV
+ * adapter on RN, or an in-memory `Map` on a server. Methods may be sync or
+ * async; `getServerTools` awaits them either way.
+ *
+ * The stored payload carries a `version`; `getServerTools` discards any entry
+ * whose version does not match the current cache format, so a stale custom
+ * backend can never feed an incompatible shape back into selection.
+ */
+interface ToolsCacheBackend {
+    /** Return the cached payload, or null when absent/unreadable. */
+    get(): CachedServerTools | null | Promise<CachedServerTools | null>;
+    /** Persist the payload. Implementations should swallow write failures. */
+    set(value: CachedServerTools): void | Promise<void>;
+    /**
+     * Remove the cached payload. Optional — a read/write-only backend may omit it,
+     * in which case `clearServerToolsCache` (and the version-mismatch
+     * invalidation) is a no-op for that backend. The default
+     * {@link localStorageToolsCache} implements it.
+     */
+    clear?(): void | Promise<void>;
+}
 /**
  * Options for fetching server tools
  */
@@ -3144,6 +3178,12 @@ interface ServerToolsOptions {
     getToken?: () => Promise<string | null>;
     /** Direct API key for server-side usage (uses X-API-Key header) */
     apiKey?: string;
+    /**
+     * Where to read/write the cached tools list. Defaults to
+     * {@link localStorageToolsCache} (browser `localStorage`; no-op elsewhere).
+     * Provide a backend to enable caching on Node / React Native.
+     */
+    cache?: ToolsCacheBackend;
 }
 /** Default cache expiration: 1 day */
 declare const DEFAULT_CACHE_EXPIRATION_MS: number;
@@ -3152,14 +3192,18 @@ declare const DEFAULT_CACHE_EXPIRATION_MS: number;
  */
 declare function getCachedServerTools(): CachedServerTools | null;
 /**
- * Clear the server tools cache
+ * Clear the cached server tools. Defaults to the browser-`localStorage` backend;
+ * pass the SAME {@link ToolsCacheBackend} you gave `getServerTools` to invalidate
+ * a custom backend (a no-op when that backend defines no `clear`). Returns the
+ * backend's clear result, which may be async.
  */
 declare function clearServerToolsCache(): void;
+declare function clearServerToolsCache(cache: ToolsCacheBackend): void | Promise<void>;
 /**
  * Get server tools with caching support.
  *
  * Flow:
- * 1. Check localStorage cache
+ * 1. Check the cache backend (localStorage by default; override via `cache`)
  * 2. If cache valid and not force refresh, return cached tools
  * 3. Otherwise, fetch from API, cache, and return
  * 4. On fetch failure, return cached tools if available (stale-while-error)
@@ -3179,6 +3223,52 @@ interface DeferLoadingConfig {
     /** Server-tool names to keep non-deferred (besides the tool-search tool), in priority order. */
     hotToolNames: readonly string[];
 }
+/**
+ * A tool set defines a group of tools that work together. When any "anchor"
+ * tool in the set is matched semantically (with a score at or above
+ * `anchorMinSimilarity`), the set is activated and all of its members are
+ * pulled into the selection.
+ *
+ * Two activation strategies consume this interface:
+ * - `expandToolSetsAdditive` (used by `useChatStorage` and
+ *   `createServerToolsFilter`) keeps all original matches and adds the
+ *   set's members on top — non-set tools are never dropped.
+ * - `applyToolSets` is exclusive: it keeps only set members plus non-set
+ *   tools that scored above `independentThreshold`.
+ *
+ * Pick `expandToolSetsAdditive` when you want recall over precision
+ * (typical), and `applyToolSets` when you specifically want non-set
+ * matches stripped on activation.
+ */
+interface ToolSet {
+    /** Human-readable name for logging/debugging */
+    name: string;
+    /** All tool names in the set */
+    members: string[];
+    /**
+     * Tools that trigger the set when selected. If any anchor appears in the
+     * semantic match results with a score at or above `anchorMinSimilarity`,
+     * all members are pulled in.
+     */
+    anchors: string[];
+    /**
+     * Minimum similarity an anchor must reach to activate the set.
+     * Prevents false activation on prompts where the anchor barely passes
+     * the global minSimilarity threshold. Default: 0.60
+     */
+    anchorMinSimilarity?: number;
+    /**
+     * System-prompt fragment to APPEND to the base prompt when this set
+     * activates. Additive, never a replacement — it composes with the host's
+     * persona / memory. Gated on genuine activation (anchor score ≥
+     * `anchorMinSimilarity`, or a forced set) via {@link activatedToolSetNames} →
+     * {@link toolSetSystemPrompts}, NOT on mere anchor presence — a borderline
+     * anchor kept by recall-over-precision must not drag this persona in. Write
+     * it to be self-limiting too (condition its behavior on the user actually
+     * wanting what the set does), so a borderline activation doesn't bias the turn.
+     */
+    systemPrompt?: string;
+}
 
 /**
  * Function type for dynamic server tools filtering based on prompt embeddings.
@@ -3541,6 +3631,13 @@ interface BaseUseChatStorageOptions {
          * {@link DeferLoadingConfig}.
          */
         deferLoading?: DeferLoadingConfig;
+        /**
+         * Where to read/write the cached server-tools catalog. Defaults to browser
+         * `localStorage`, which is a silent no-op on React Native — so on RN pass an
+         * AsyncStorage/MMKV-backed {@link ToolsCacheBackend} here or every send
+         * refetches the whole catalog. Forwarded to `getServerTools`.
+         */
+        cache?: ToolsCacheBackend;
     };
     /**
      * Automatically generate embeddings for messages after saving.
@@ -5892,14 +5989,14 @@ declare function createChunkVectorCache(maxSize?: number): ChunkVectorCache;
 declare function recall(query: string, ctx: RecallContext, options?: RecallOptions): Promise<RecallResult>;
 
 /**
- * Unified Recall Tool
+ * Recall tool constants — deliberately dependency-free.
  *
- * Single chat-completion tool that searches both vault facts and
- * conversation chunks via `recall()`. Replaces the legacy pair of
- * `memory_vault_search` (facts) + `search_memory` (chunks) — the LLM no
- * longer has to route between two tools.
+ * Split out of `recallTool.ts` so the tool NAME can be referenced from
+ * node/React-Native-safe modules (e.g. the client-tool selector in
+ * `../tools/clientToolSelection`) without dragging `recall()` and its
+ * WatermelonDB-backed operations into the module graph. `recallTool.ts`
+ * re-exports these to preserve their public identity.
  */
-
 /** Tool name surfaced to the LLM. Exported so bench harnesses and chat
  * clients reference the same string — drift between prod and bench would
  * mask tool-routing bugs in eval. */
@@ -5907,6 +6004,16 @@ declare const RECALL_TOOL_NAME = "recall_memory";
 /** Maximum results the executor will return to the LLM, regardless of
  * the LLM-supplied `limit`. */
 declare const RECALL_MAX_LIMIT = 50;
+
+/**
+ * Unified Recall Tool
+ *
+ * Single chat-completion tool that searches both vault facts and
+ * conversation chunks via `recall()`. Replaces the legacy pair of
+ * `memory_vault_search` (facts) + `search_memory` (chunks) — the LLM no
+ * longer has to route between two tools.
+ */
+
 interface RecallToolOptions {
     /** Lanes to search. Default: ["fact", "chunk"]. */
     types?: MemoryKind[];
@@ -6210,11 +6317,26 @@ declare function chunkText(text: string, options?: ChunkingOptions): TextChunk[]
 declare function shouldChunkMessage(content: string, chunkSize?: number): boolean;
 
 /**
- * Memory Retrieval Embeddings
+ * Embedding generation — dependency-free core.
  *
- * Functions for generating and storing embeddings for conversation messages.
+ * The raw "text → embedding" calls, split out of `embeddings.ts` so they can be
+ * imported by node/React-Native-safe modules (the server-tool + client-tool
+ * selection engine in `../tools`) WITHOUT pulling in the WatermelonDB-backed
+ * `db/chat/operations` that `embeddings.ts` needs for its message-persistence
+ * helpers (`embedMessage`, `embedAllMessages`, `chunkAndEmbed*`).
+ *
+ * Nothing here touches the database; the only I/O is the HTTP embeddings
+ * endpoint. `embeddings.ts` re-exports these so existing importers of
+ * `../memoryEngine/embeddings` (and the `../memoryEngine` barrel) keep working.
  */
 
+/**
+ * Generate an embedding for text using the API
+ *
+ * Supports two auth methods:
+ * - `apiKey`: Uses X-API-Key header (for server-side/CLI usage)
+ * - `getToken`: Uses Authorization: Bearer header (for Privy identity tokens)
+ */
 declare function generateEmbedding(text: string, options: EmbeddingOptions): Promise<number[]>;
 /**
  * Generate embeddings for multiple texts, automatically chunking large inputs.
@@ -6229,6 +6351,18 @@ declare function generateEmbedding(text: string, options: EmbeddingOptions): Pro
  * @returns Array of embeddings in the same order as input texts
  */
 declare function generateEmbeddings(texts: string[], options: EmbeddingOptions): Promise<number[][]>;
+
+/**
+ * Memory Retrieval Embeddings
+ *
+ * Message-level embedding + persistence helpers: find messages via the
+ * WatermelonDB-backed `db/chat/operations`, embed their content, and store the
+ * vectors/chunks back. The raw "text → embedding" calls live in `./generate`
+ * (dependency-free so the tool-selection engine can import them without the DB
+ * layer) and are re-exported here so existing importers of
+ * `../memoryEngine/embeddings` and the `../memoryEngine` barrel keep working.
+ */
+
 /**
  * Embed a single message and store the embedding in the database
  *
@@ -6523,6 +6657,31 @@ interface UseChatStorageOptions extends BaseUseChatStorageOptions {
      * Auto-flush queued operations when key becomes available. @default true
      */
     autoFlushOnKeyAvailable?: boolean;
+    /**
+     * Additional tool sets to apply on top of the built-in ones (app-generation,
+     * slides, github). When any anchor tool in a custom set is selected by
+     * semantic matching, all members of that set are included automatically.
+     *
+     * Treated as static config — set once at hook setup. Changing it across
+     * renders does not affect in-flight `sendMessage` calls; use
+     * `activeToolSets` for dynamic, conversation-state-driven overrides.
+     */
+    extraToolSets?: ToolSet[];
+    /**
+     * Tool set names that should expand unconditionally for this request,
+     * bypassing the anchor-similarity check. Use when conversation state
+     * implies a set should be present regardless of how the prompt is phrased
+     * — e.g., pass `["documents"]` when the conversation already contains a
+     * generated document, so short follow-up prompts ("make the background red")
+     * still get the full document toolkit.
+     *
+     * Read via a ref so updates are visible to in-flight `sendMessage` calls
+     * without rebuilding the callback.
+     *
+     * Names must match a set's `name` from `BUILT_IN_TOOL_SETS` or
+     * `extraToolSets`. Unknown names are ignored.
+     */
+    activeToolSets?: string[];
     /**
      * Opt into resumable streaming. When `true`, `sendMessage` sends the
      * resumable capability header, a stable `assistantUniqueId` is allocated for
@@ -6558,6 +6717,16 @@ interface UseChatStorageOptions extends BaseUseChatStorageOptions {
         model?: string;
         round?: number;
     }) => void;
+    /**
+     * Observability hook fired once per send with the tools actually selected for
+     * the turn (after server + client filtering). Never throws into the send path.
+     * Mirrors react's onToolSelection.
+     */
+    onToolSelection?: (info: {
+        prompt: string;
+        clientToolNames: string[];
+        serverToolNames: string[];
+    }) => void;
 }
 /**
  * Arguments for sendMessage with storage (Expo version)