@anuma/sdk 3.0.0 → 3.1.1

package/dist/tools/selection/index.d.mts

@@ -0,0 +1,1380 @@
+type LlmapiChatCompletionTool = {
+    [key: string]: unknown;
+};
+
+/**
+ * Tool executor function type
+ */
+type ToolExecutor = (args: Record<string, unknown>) => Promise<unknown> | unknown;
+/**
+ * Tool configuration with optional executor
+ */
+type ToolConfig = LlmapiChatCompletionTool & {
+    /**
+     * Function to execute when the tool is called.
+     * If provided, the tool will be executed automatically when the LLM calls it.
+     * If not provided, an onToolCall event will be emitted instead.
+     */
+    executor?: ToolExecutor;
+    /**
+     * Whether to skip sending the tool result back to the model as a continuation.
+     * When true, the tool is executed but its result is not fed back to the model.
+     * Useful for display-only tools (charts, weather cards) that render client-side
+     * and don't need a model follow-up.
+     */
+    skipContinuation?: boolean;
+    /**
+     * Whether to remove this tool from the tools list after it has been
+     * successfully executed. This prevents smaller models from calling
+     * the same tool repeatedly in continuation requests.
+     *
+     * Only applies when the tool has an executor. The tool is kept if
+     * execution fails, allowing the model to retry.
+     */
+    removeAfterExecution?: boolean;
+    /**
+     * Timeout in milliseconds for this tool's executor.
+     * Overrides the default 30-second timeout.
+     * Set to `Infinity` to disable the timeout (e.g. for interactive tools
+     * that wait for user input).
+     * @default 30000
+     */
+    executorTimeout?: number;
+    /**
+     * When PII redaction is active, de-anonymize this tool's call arguments
+     * (restore original values for any `[CATEGORY_n]` placeholders) BEFORE the
+     * executor runs, using the same redactor that redacted the request this turn.
+     * Opt in only for tools that act on data that stays on the device — e.g.
+     * `memory_vault_save`, which must persist the real value, not a placeholder.
+     * Leave off for tools that forward arguments off-device (connectors), so PII
+     * stays redacted on the wire.
+     * @default false
+     */
+    deAnonymizeArgs?: boolean;
+    /**
+     * Tool names that this tool depends on. When multiple tools are called in
+     * the same response, tools with `dependsOn` will wait for the named tools
+     * to finish executing before starting.
+     *
+     * Example: `display_slides` depends on `create_file` because it reads
+     * files from IndexedDB that `create_file` writes.
+     */
+    dependsOn?: string[];
+};
+
+/**
+ * Server-side tools caching module
+ *
+ * Fetches and caches tools from /api/v1/tools endpoint
+ * with configurable expiration and localStorage persistence.
+ */
+
+/** Tool parameters schema */
+interface ToolParameters {
+    properties: Record<string, unknown>;
+    required: string[];
+    type: "object";
+}
+/** Current API response format (description and parameters at top level) */
+interface ServerToolsResponseItemCurrent {
+    description: string;
+    name: string;
+    parameters: ToolParameters;
+}
+/** New API response format with schema wrapper */
+interface ServerToolsResponseItemNew {
+    name: string;
+    schema: {
+        name: string;
+        description: string;
+        parameters: ToolParameters;
+    };
+    cost?: number;
+    embedding?: number[];
+}
+/** Response item can be either format */
+type ServerToolsResponseItem = ServerToolsResponseItemCurrent | ServerToolsResponseItemNew;
+/** Tools object mapping tool names to their definitions */
+type ServerToolsMap = {
+    [toolName: string]: ServerToolsResponseItem;
+};
+/**
+ * Response format from /api/v1/tools endpoint.
+ * New format includes checksum and tools wrapper.
+ * Legacy format is just the tools map directly.
+ */
+type ServerToolsResponse = {
+    checksum: string;
+    tools: ServerToolsMap;
+} | ServerToolsMap;
+/**
+ * Server tool definition with parameters field.
+ * This is the neutral format stored in cache.
+ * Strategies transform this to the correct API format.
+ */
+interface ServerTool {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: Record<string, unknown>;
+        required: string[];
+    };
+    /** Optional embedding vector for semantic matching */
+    embedding?: number[];
+}
+/**
+ * Cached tools structure stored in localStorage
+ */
+interface CachedServerTools {
+    tools: ServerTool[];
+    timestamp: number;
+    version: string;
+    /** 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
+ */
+interface ServerToolsOptions {
+    /** Base URL for the API (defaults to BASE_URL from clientConfig) */
+    baseUrl?: string;
+    /** Cache expiration time in milliseconds (default: 5 minutes) */
+    cacheExpirationMs?: number;
+    /** Force refresh even if cache is valid */
+    forceRefresh?: boolean;
+    /** Authentication token getter (uses Authorization: Bearer header) */
+    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;
+/** Minimum prompt length for tool matching. Shorter prompts skip embedding. */
+declare const MIN_CONTENT_LENGTH_FOR_TOOLS = 5;
+/**
+ * Max client tools to include after automatic semantic filtering.
+ * Set high — CLIENT_TOOLS_RELEVANCE_RATIO does the real trimming; this
+ * is just a safety cap to avoid pathological cases.
+ */
+declare const MAX_CLIENT_TOOLS_AFTER_FILTER = 10;
+/** Minimum similarity for client tool semantic matching. */
+declare const CLIENT_TOOLS_MIN_SIMILARITY = 0.53;
+/**
+ * Client-tool relevance ratio: drop tools scoring below this fraction of the
+ * top match. 0.75, not 0.9 — multi-intent prompts ("weather in Tokyo, and
+ * chart the temperature trend") embed dominated by one intent, so the second
+ * tool lands around 75-80% of the top score; at 0.9 the second intent could
+ * NEVER survive, no matter how good its description (measured: display_chart
+ * 0.62 vs display_weather 0.81 → ratio 0.77).
+ */
+declare const CLIENT_TOOLS_RELEVANCE_RATIO = 0.75;
+/**
+ * Result of parsing server tools response
+ */
+interface ParsedServerToolsResponse {
+    tools: ServerTool[];
+    checksum?: string;
+}
+/**
+ * Get cached tools from localStorage
+ */
+declare function getCachedServerTools(): CachedServerTools | null;
+declare const localStorageToolsCache: ToolsCacheBackend;
+/**
+ * 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 the checksum of the currently cached tools, or undefined when there is no
+ * cache / no stored checksum. Defaults to the browser-`localStorage` backend;
+ * pass the SAME backend you gave `getServerTools` to read a custom backend's
+ * checksum (an async backend yields a promise).
+ */
+declare function getToolsChecksum(): string | undefined;
+declare function getToolsChecksum(cache: ToolsCacheBackend): string | undefined | Promise<string | undefined>;
+/**
+ * Check if tools should be refreshed based on checksum comparison.
+ * Returns true if:
+ * - responseChecksum is provided and differs from cached checksum
+ * - No cached checksum exists (first time with checksum support)
+ *
+ * Returns false if:
+ * - responseChecksum is not provided (legacy response)
+ * - Checksums match
+ */
+declare function shouldRefreshTools(responseChecksum: string | undefined): boolean;
+declare function shouldRefreshTools(responseChecksum: string | undefined, cache: ToolsCacheBackend | undefined): boolean | Promise<boolean>;
+/**
+ * Get server tools with caching support.
+ *
+ * Flow:
+ * 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)
+ */
+declare function getServerTools(options: ServerToolsOptions): Promise<ServerTool[]>;
+/**
+ * Filter server tools by name.
+ * @param serverTools - All server tools
+ * @param includeNames - Names to include (undefined = all, [] = none)
+ */
+declare function filterServerTools(serverTools: ServerTool[], includeNames?: string[]): ServerTool[];
+/**
+ * Opt-in defer-loading config for {@link mergeTools}. OFF by default — when absent or `enabled:false`,
+ * tools are emitted exactly as today (no ordering change, no defer flags, no search tool). When ON, the
+ * server tools are emitted as the full catalog in a deterministic, byte-stable order every turn:
+ * `[tool-search] → [hot, in hotToolNames order] → [deferred, name-sorted]`, with `defer_loading:true` on
+ * every tool that is neither hot nor the search tool. Deferred tools keep their FULL definition (so
+ * Anthropic's matcher can index them); they are not reduced to names. This stabilizes the leading `tools`
+ * prefix so Anthropic prompt caching can hit across turns.
+ */
+interface DeferLoadingConfig {
+    enabled: boolean;
+    /** Server-tool names to keep non-deferred (besides the tool-search tool), in priority order. */
+    hotToolNames: readonly string[];
+}
+declare function mergeTools(serverTools: ServerTool[], clientTools: Array<LlmapiChatCompletionTool | ToolConfig> | undefined, apiType?: "responses" | "completions", deferConfig?: DeferLoadingConfig): Array<Record<string, unknown>>;
+/**
+ * Result of tool matching with similarity score
+ */
+interface ToolMatchResult {
+    tool: ServerTool;
+    similarity: number;
+}
+/**
+ * Options for findMatchingTools
+ */
+interface ToolMatchOptions {
+    /** Maximum number of tools to return (default: 5) */
+    limit?: number;
+    /** Minimum similarity threshold 0-1 (default: 0.3) */
+    minSimilarity?: number;
+    /**
+     * When enabled, returns empty results if the top match doesn't clearly
+     * stand out from the runner-up. This filters out generic prompts like
+     * "hello" or "tell me a joke" where all tools score similarly low.
+     *
+     * A match is considered ambiguous when:
+     * - The top score is below `ambiguityThreshold` (default: 0.55), AND
+     * - The gap between the top score and the runner-up is below `minLead` (default: 0.04)
+     */
+    filterAmbiguous?: boolean;
+    /** Top score must be above this to skip the ambiguity check (default: 0.55) */
+    ambiguityThreshold?: number;
+    /** Minimum gap between top and runner-up scores (default: 0.04) */
+    minLead?: number;
+    /**
+     * Only keep tools scoring at least this fraction of the top match's score.
+     * Filters out the tail of weakly-related tools that fill up the limit.
+     * For example, 0.85 means a tool must score within 85% of the top match.
+     * Set to 0 to disable. Default: 0 (disabled).
+     */
+    relevanceRatio?: number;
+}
+/**
+ * Find tools that semantically match prompt embedding(s).
+ *
+ * Accepts either a single embedding or an array of embeddings (e.g., from chunked messages).
+ * When multiple embeddings are provided, uses max similarity across all chunks for each tool.
+ *
+ * @param promptEmbeddings - Single embedding vector or array of embeddings (for chunked messages)
+ * @param tools - Array of server tools (with embeddings) to search through
+ * @param options - Optional matching configuration
+ * @returns Array of matching tools with similarity scores, sorted by relevance
+ *
+ * @example
+ * ```ts
+ * // Single embedding
+ * const matches = findMatchingTools(embedding, tools, { limit: 5 });
+ *
+ * // Multiple embeddings (chunked message) - uses max similarity
+ * const matches = findMatchingTools(chunkEmbeddings, tools, { limit: 5 });
+ * ```
+ */
+declare function findMatchingTools(promptEmbeddings: number[] | number[][], tools: ServerTool[], options?: ToolMatchOptions): ToolMatchResult[];
+/**
+ * Compute the raw max similarity for every tool with a valid embedding,
+ * without any filtering (no `minSimilarity`, no `relevanceRatio`, no
+ * ambiguity check, no limit). Use this when you need true per-tool scores
+ * — e.g., to drive `expandToolSetsAdditive`'s anchor activation without
+ * letting `findMatchingTools`' relevance cutoff silently drop sub-threshold
+ * anchors that should still trigger their set.
+ */
+declare function scoreTools(promptEmbeddings: number[] | number[][], tools: ServerTool[]): Map<string, number>;
+/**
+ * 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;
+}
+/** Built-in tool sets. Consumers can extend this with their own. */
+declare const BUILT_IN_TOOL_SETS: ToolSet[];
+/**
+ * Apply tool set logic to a set of semantic match results.
+ *
+ * For each defined tool set, if any anchor tool appears in `matchedNames`,
+ * all set members present in `availableNames` are added and non-member
+ * tools are removed (unless they scored above `independentThreshold`).
+ *
+ * @param matchedNames - Names selected by semantic matching
+ * @param availableNames - All tool names available for selection
+ * @param scores - Map of tool name → similarity score (from semantic matching)
+ * @param toolSets - Tool sets to apply (defaults to BUILT_IN_TOOL_SETS)
+ * @param independentThreshold - Non-set tools scoring above this survive (default: 0.65)
+ */
+declare function applyToolSets(matchedNames: Set<string>, availableNames: Set<string>, scores: Map<string, number>, toolSets?: ToolSet[], independentThreshold?: number): Set<string>;
+/**
+ * Additively expand tool sets: when any anchor of a set scores at or above
+ * its `anchorMinSimilarity`, all set members are added to the result.
+ * Original matches are preserved; multiple sets can expand independently.
+ *
+ * Members of sets that *don't* activate are kept if they were individually
+ * matched. We deliberately don't strip orphans: the cost of a single
+ * borderline tool slipping into the request is cheap (a few extra bytes,
+ * no behavioral impact) but stripping legitimate matches like
+ * `create_file 0.55` on prompts where `patch_file` doesn't also clear the
+ * anchor threshold would silently break app-creation flows. Recall over
+ * precision.
+ *
+ * Use this for server-side toolkit suites where the LLM needs the full
+ * call chain (e.g. search_web → read_url / parallel_read_url, or
+ * geocoding before the OpenMeteo data tools). Differs from `applyToolSets`,
+ * which replaces non-set matches when a set activates.
+ *
+ * To express "any member triggers the set" (not specific anchors), pass
+ * `anchors: members` when defining the ToolSet.
+ *
+ * @param matchedNames - Names selected by semantic matching
+ * @param availableNames - All tool names available for selection
+ * @param scores - Map of tool name → similarity score
+ * @param toolSets - Tool sets to evaluate
+ * @param activeSetNames - Set names that should expand unconditionally,
+ *   bypassing the anchor-similarity check. Use this when conversation state
+ *   implies a set should be present regardless of how the current prompt is
+ *   phrased (e.g., a slide deck artifact already exists in the conversation).
+ * @returns Set including original matches plus members of any activated set
+ */
+declare function expandToolSetsAdditive(matchedNames: Set<string>, availableNames: Set<string>, scores: Map<string, number>, toolSets: ToolSet[], activeSetNames?: ReadonlySet<string>): Set<string>;
+/**
+ * Names of the tool sets that *activated* for a request — the exact gate
+ * {@link expandToolSetsAdditive} uses to pull in members: an anchor whose
+ * similarity cleared `anchorMinSimilarity`, or a set the caller forced active
+ * via `activeSetNames`. Drives {@link toolSetSystemPrompts} so a set's persona
+ * rides in only on genuine activation, not on a borderline anchor that was kept
+ * by recall-over-precision (below the activation floor) without the set
+ * actually activating.
+ *
+ * @param scores - Tool name → similarity score (from semantic matching).
+ * @param toolSets - Tool sets to evaluate (defaults to {@link BUILT_IN_TOOL_SETS}).
+ * @param activeSetNames - Set names forced active regardless of score.
+ */
+declare function activatedToolSetNames(scores: ReadonlyMap<string, number>, toolSets?: ToolSet[], activeSetNames?: ReadonlySet<string>): Set<string>;
+/**
+ * Collect the `systemPrompt` of every tool set that activated for a request,
+ * for the caller to APPEND to its base system prompt.
+ *
+ * Pass `activatedSetNames` (from {@link activatedToolSetNames}) to gate on
+ * genuine activation — an anchor that cleared `anchorMinSimilarity` or a forced
+ * set. This is the correct gate: `expandToolSetsAdditive` keeps borderline
+ * anchor matches in the selection even when the set did NOT activate (recall
+ * over precision), so gating on mere anchor *presence* would inject a set's
+ * persona on prompts it has nothing to do with (e.g. the App Builder prompt on
+ * "write a story"). When `activatedSetNames` is omitted, falls back to anchor
+ * presence for legacy callers that don't compute scores.
+ *
+ * Additive by design: append the returned fragments, never replace the base
+ * prompt, so persona / memory survive. De-duplicated, order preserved.
+ *
+ * @param selectedToolNames - Final selected tool names (client + server tools).
+ * @param toolSets - Tool sets to consult (defaults to {@link BUILT_IN_TOOL_SETS}).
+ * @param activatedSetNames - Set names that genuinely activated (see above).
+ * @returns Mode prompts for active sets, in `toolSets` order, deduplicated.
+ */
+declare function toolSetSystemPrompts(selectedToolNames: Iterable<string>, toolSets?: ToolSet[], activatedSetNames?: ReadonlySet<string>): string[];
+/**
+ * Options for createServerToolsFilter.
+ */
+interface CreateServerToolsFilterOptions {
+    /**
+     * Tool sets to expand additively. When any anchor scores at or above the
+     * set's `anchorMinSimilarity`, all members are included alongside the
+     * original semantic matches.
+     */
+    toolSets?: ToolSet[];
+    /** Tool names to always drop from results, even when they match. */
+    excludeTools?: Iterable<string>;
+    /** Options forwarded to `findMatchingTools`. */
+    matchOptions?: ToolMatchOptions;
+}
+/**
+ * Build a server-tools filter function for use with `useChatStorage`'s
+ * `serverTools` option. Composes `findMatchingTools`, `expandToolSetsAdditive`,
+ * and an exclude-list into a single (embeddings, tools) → string[] callback.
+ *
+ * @example
+ * ```ts
+ * import { createServerToolsFilter } from "@anuma/sdk/tools";
+ *
+ * const serverTools = createServerToolsFilter({
+ *   toolSets: [
+ *     {
+ *       name: "research",
+ *       members: ["AnumaJinaMCP-search_web", "AnumaJinaMCP-read_url", ...],
+ *       anchors: ["AnumaJinaMCP-search_web"],
+ *       anchorMinSimilarity: 0.7,
+ *     },
+ *   ],
+ *   excludeTools: ["OpenMeteoMCP-weather_forecast"],
+ *   matchOptions: { limit: 5, minSimilarity: 0.5 },
+ * });
+ * ```
+ */
+declare function createServerToolsFilter(options?: CreateServerToolsFilterOptions): (embeddings: number[] | number[][], tools: ServerTool[]) => string[];
+/**
+ * Default exclusions baked into `defaultServerToolsFilter`.
+ *
+ * - `AnumaVisionMCP-anuma_analyze_image`: modern frontier models have native
+ *   vision via image content blocks; routing through a server-side vision
+ *   tool just adds a hop.
+ * - `OpenMeteoMCP-weather_forecast`: redundant when the consumer registers
+ *   `createWeatherTool` (the client-side display tool handles geocoding
+ *   internally and renders a card inline). Including the server-side
+ *   equivalent causes the model to prefer raw data over the card. Consumers
+ *   who don't register `createWeatherTool` should instead build their own
+ *   filter via `createServerToolsFilter`. NOTE: `OpenMeteoMCP-geocoding` is
+ *   deliberately NOT excluded — the non-weather OpenMeteo data tools
+ *   (air_quality, marine_weather, …) require lat/lon and depend on it via the
+ *   openmeteo-geocode set; excluding it stranded them. Bare geocoding doesn't
+ *   compete with the weather card (it returns coordinates, not weather).
+ */
+declare const DEFAULT_EXCLUDED_SERVER_TOOLS: readonly string[];
+/** Default match options for the server-tools filter (limit 5, minSim 0.5). */
+declare const DEFAULT_SERVER_TOOLS_MATCH_OPTIONS: ToolMatchOptions;
+/**
+ * Dependency edges between server tools: when an entry tool (anchor) matches
+ * a prompt, its continuation tools ride in even though they can never match
+ * the prompt themselves.
+ *
+ * These exist because semantic selection structurally cannot reach a tool
+ * whose job is step 2 of a call-chain. Measured against the live catalog
+ * (June 2026): on "research the latest news on X", `search_web` scores 0.64
+ * but `parallel_read_url` scores 0.33 and `parallel_search_web` 0.47 — below
+ * the 0.5 floor, unreachable at ANY match limit. No threshold or limit tuning
+ * fixes this; an explicit edge is the only mechanism that does.
+ *
+ * Deliberately NOT grouped: same-vendor siblings (`extract_pdf`,
+ * `search_images`, weather/finance variants…). Those
+ * embed near the prompts that need them and survive plain top-5 selection on
+ * their own — vendor-wide expansion just dilutes the toolset. Keep this list
+ * to genuine call-chains.
+ *
+ * Tool names are EXACT `/api/v1/tools` catalog matches — all filtering in
+ * this module is exact-string, so a stale name silently selects nothing (the
+ * May 2026 `Anuma` prefix rename broke every consumer keeping copies of
+ * these lists). The toolSelection e2e suite asserts every name below exists
+ * in the live catalog.
+ */
+declare const SERVER_TOOL_DEPENDENCY_SETS: ToolSet[];
+/**
+ * Pre-configured server-tools filter ready to drop into `useChatStorage`'s
+ * `serverTools` option. Semantic matching against the user prompt with the
+ * default exclusion list applied, plus call-chain expansion via
+ * {@link SERVER_TOOL_DEPENDENCY_SETS} so continuation tools (read-after-search,
+ * geocode-before-weather) ride in with their entry tool.
+ *
+ * @example
+ * ```ts
+ * import { defaultServerToolsFilter, useChatStorage } from "@anuma/sdk/react";
+ *
+ * useChatStorage({
+ *   ...,
+ *   serverTools: defaultServerToolsFilter,
+ * });
+ * ```
+ *
+ * If you need to customize (extra excludes, different limits, opt into
+ * tool-set expansion), call `createServerToolsFilter` directly.
+ */
+declare const defaultServerToolsFilter: (embeddings: number[] | number[][], tools: ServerTool[]) => string[];
+/**
+ * Type for a server-tools filter — a function that takes prompt embeddings
+ * and the full server tool catalog and returns the names of tools to keep.
+ * Matches `useChatStorage`'s `serverTools` callback signature.
+ */
+type ServerToolsFilterFunction = (embeddings: number[] | number[][], tools: ServerTool[]) => string[];
+/**
+ * Options for `selectServerToolsForPrompt`.
+ */
+interface SelectServerToolsForPromptOptions {
+    /** User prompt to match tools against. */
+    prompt: string;
+    /**
+     * Filter to apply: either a function (called with the prompt embedding +
+     * full catalog) or a static list of tool names. Same shape `useChatStorage`
+     * accepts on its `serverTools` option. Pass `defaultServerToolsFilter` to
+     * mirror the default chat-flow selection.
+     */
+    serverToolsFilter?: string[] | ServerToolsFilterFunction;
+    /** Function that resolves an auth token (Bearer). */
+    getToken: () => Promise<string | null>;
+    /** Base URL for the API. */
+    baseUrl?: string;
+    /** Embedding model override. Falls back to the SDK default. */
+    embeddingModel?: string;
+    /** Cache expiration in ms for the server-tools catalog fetch. */
+    cacheExpirationMs?: number;
+    /**
+     * Where to read/write the cached catalog. Defaults to browser `localStorage`
+     * (a no-op on Node/RN); pass a backend to persist on those platforms.
+     */
+    cache?: ToolsCacheBackend;
+    /**
+     * Phase 3 defer-loading. When `enabled`, this helper returns the FULL catalog (skipping semantic/
+     * static filtering) to mirror useChatStorage's responses send path, which swaps in the full catalog
+     * for mergeTools + tool-search. Omit/disabled → today's filtered selection.
+     */
+    deferLoading?: DeferLoadingConfig;
+}
+/**
+ * Select server-side tools for a prompt using the same path
+ * `useChatStorage` runs internally. Use this anywhere outside the chat
+ * hook — background-task workers, server scripts, debug tools — that needs
+ * the same selection the chat flow would produce.
+ *
+ * Mirrors the responses-API branch of `sendMessage`: fetch catalog with
+ * caching, optionally embed the prompt (only when the filter is a function),
+ * apply the filter, return matching `ServerTool[]` (with embeddings and
+ * descriptions intact for downstream serialization).
+ *
+ * Returns `[]` on any of: undefined/empty filter, empty prompt for a
+ * function filter, failed catalog fetch, or failed embedding.
+ *
+ * @example
+ * ```ts
+ * import { defaultServerToolsFilter, selectServerToolsForPrompt } from "@anuma/sdk/server";
+ *
+ * const tools = await selectServerToolsForPrompt({
+ *   prompt: "Generate a slide deck about AI",
+ *   serverToolsFilter: defaultServerToolsFilter,
+ *   getToken: async () => identityToken,
+ *   baseUrl: process.env.API_URL,
+ * });
+ * ```
+ */
+declare function selectServerToolsForPrompt(options: SelectServerToolsForPromptOptions): Promise<ServerTool[]>;
+/**
+ * Options for selectServerSideTools
+ */
+interface SelectServerSideToolsOptions {
+    /** The user prompt to match tools against */
+    prompt: string;
+    /** Function to get auth token (uses Authorization: Bearer header) */
+    getToken?: () => Promise<string | null>;
+    /** Direct API key for server-side usage (uses X-API-Key header) */
+    apiKey?: string;
+    /** Base URL for the API */
+    baseUrl?: string;
+    /** Cache expiration in ms (default: 24h) */
+    cacheExpirationMs?: number;
+    /** Force refresh tools cache */
+    forceRefresh?: boolean;
+    /** Embedding model to use */
+    embeddingModel?: string;
+    /** Max tools to return (default: 10) */
+    limit?: number;
+    /** Minimum cosine similarity 0-1 (default: 0.3) */
+    minSimilarity?: number;
+    /** API format for returned tools (default: "responses") */
+    apiType?: "responses" | "completions";
+}
+/**
+ * Select server tools that are semantically relevant to a prompt.
+ *
+ * Fetches available tools (with caching), generates embeddings for the prompt,
+ * runs cosine-similarity matching, and returns tool schemas in the requested
+ * API format (Responses or Completions).
+ *
+ * @example
+ * ```ts
+ * import { selectServerSideTools } from "@anuma/sdk/tools";
+ *
+ * const tools = await selectServerSideTools({
+ *   prompt: "Draw me a cat",
+ *   getToken: async () => identityToken,
+ * });
+ *
+ * const response = await postApiV1Responses({
+ *   body: {
+ *     messages: [{ role: "user", content: [{ type: "text", text: "Draw me a cat" }] }],
+ *     model: "fireworks/accounts/fireworks/models/kimi-k2p5",
+ *     tools,
+ *   },
+ *   headers: { Authorization: `Bearer ${identityToken}` },
+ * });
+ * ```
+ */
+declare function selectServerSideTools(options: SelectServerSideToolsOptions): Promise<Array<Record<string, unknown>>>;
+
+/**
+ * Client-tool selection — the per-turn semantic filter over a client-tool
+ * catalog.
+ *
+ * Extracted out of `../../react/useChatStorage` (a `"use client"` React +
+ * WatermelonDB file) so the identical selection can run anywhere the engine
+ * runs: the standalone council path that bypasses the hook, Node unit tests,
+ * and the node/RN-safe `@anuma/sdk/tools/selection` subpath. The hook re-imports
+ * these — behavior is unchanged from when they lived inline.
+ *
+ * Dependency-safe by construction: `generateEmbeddings` comes from the db-free
+ * `../memoryEngine/generate` core and `RECALL_TOOL_NAME` from the
+ * dependency-free `../memory/recallConstants`, so nothing here drags in the
+ * WatermelonDB data layer.
+ */
+
+/** Typed accessor for client tool name (handles function-call style and flat). */
+declare function getToolName(t: LlmapiChatCompletionTool): string;
+/** Typed accessor for client tool description. */
+declare function getToolDescription(t: LlmapiChatCompletionTool): string;
+/**
+ * Build the tool-set guidance to inject for a request: the `systemPrompt` of
+ * every tool set whose tools ended up selected (e.g. the App Builder prompt
+ * when app-gen tools are pulled in — by an explicit force-include OR an
+ * implicit semantic match). Returned as one string for useChat's `toolGuidance`
+ * channel, which adds it as a separate system message (additive — composes with
+ * the persona, doesn't replace it). `undefined` when no selected set carries a
+ * prompt, so non-app turns are unaffected.
+ */
+declare function computeToolGuidance(selectedServerTools: ServerTool[], selectedClientTools: LlmapiChatCompletionTool[] | undefined, extraToolSets: ToolSet[], activatedSetNames?: ReadonlySet<string>): string | undefined;
+/**
+ * Automatically filter client tools using embedding-based semantic matching.
+ * Generates embeddings for tool descriptions (cached), then selects the most
+ * relevant tools for the user's prompt. This prevents sending 20+ tool
+ * definitions that eat up the context window.
+ *
+ * @returns Filtered client tools, or the original array if filtering fails/skips.
+ */
+declare function autoFilterClientTools(clientTools: LlmapiChatCompletionTool[], promptEmbeddings: number[] | number[][] | null, cache: Map<string, number[]>, embeddingOptions: {
+    getToken?: () => Promise<string | null>;
+    apiKey?: string;
+    baseUrl?: string;
+    model?: string;
+}, extraToolSets?: ToolSet[], activeToolSets?: string[], 
+/**
+ * Why `promptEmbeddings` is null. "short-prompt" (the length gate —
+ * deliberate) sends NO tools; "error" (embedding generation failed —
+ * transient) degrades to the FULL catalog so an embeddings outage never
+ * strips every tool from every request.
+ */
+noEmbeddingsReason?: "short-prompt" | "error"): Promise<{
+    tools: LlmapiChatCompletionTool[];
+    activatedSetNames?: ReadonlySet<string>;
+}>;
+
+/**
+ * Connector tool catalog + denied-tools system-prompt rider.
+ *
+ * Granular connector access works by ALLOW/DENY-ing individual SDK tools.
+ * Denying a tool means it's never handed to the model that turn, so it
+ * physically can't be called — bypass-proof at the model layer.
+ *
+ * Consumer contract (this PR ships the foundation only — it does NOT wire
+ * anything into runtime filtering or the client; those are later phases):
+ *
+ *   1. Hide the denied tools from the model — pass the denied tool names as
+ *      `createServerToolsFilter({ excludeTools })` so they're dropped from the
+ *      toolset before it reaches the LLM.
+ *   2. Tell the user how to re-enable — append `buildDeniedToolsRider(denied)`
+ *      to the system prompt. Because the tool is absent, the model can't name
+ *      it on its own and would give a generic "I don't have access". The rider
+ *      gives it the specific capability names (grouped by connector) so it can
+ *      tell the user to re-enable that exact tool in Connected Apps settings.
+ *
+ * `TOOL_CATALOG` is the single source of truth for connector tool → friendly
+ * label + provider. `provider` is the canonical logical-provider identifier the
+ * portal and SDK already key on (matches `internal/oauth/providers.go` and the
+ * `createConnectorTokenGetter` call sites) — Phase 2/3 use it to group and
+ * persist per-tool denial. `connector` is the human-facing UI display string.
+ * Consumers (portal, client) read this on a version bump rather than re-encoding
+ * tool names. Labels are placeholders that will be refined later — keep them
+ * sensible.
+ */
+
+interface ToolCatalogEntry {
+    label: string;
+    /** Canonical logical-provider id (e.g. "gmail", "gcalendar", "gdrive"). */
+    provider: string;
+    /** Human-facing connector display name (UI label). */
+    connector: string;
+}
+declare const TOOL_CATALOG: Record<string, ToolCatalogEntry>;
+/**
+ * Build a system-prompt fragment telling the model which connector capabilities
+ * the user has turned off, so it can give the specific "re-enable this tool"
+ * message instead of a generic refusal.
+ *
+ * Unknown names (not in {@link TOOL_CATALOG}) are skipped. Returns `""` when the
+ * input is empty or every name is unknown — callers append the result
+ * conditionally, so an empty string is a no-op.
+ */
+declare function buildDeniedToolsRider(deniedToolNames: Iterable<string>): string;
+interface ConnectorGuidanceInput {
+    /** The candidate tools for this turn (the final assembled set). */
+    tools: ToolConfig[];
+    /**
+     * Logical provider codes connected for the user — the same codes used as
+     * {@link TOOL_CATALOG} `provider` values (e.g. "gmail", "gcalendar",
+     * "gdrive", "notion", "github", "dropbox").
+     */
+    connectedProviders: string[];
+    /** Exact SDK tool-name strings the user turned off ({@link TOOL_CATALOG} keys). */
+    deniedToolNames: string[];
+}
+interface ConnectorGuidance {
+    /** `input.tools` with any denied tool removed (the helper owns filtering). */
+    tools: ToolConfig[];
+    /** Compact system-prompt block, or "" when there's nothing actionable. */
+    rider: string;
+}
+/**
+ * Single helper both web and mobile use so neither re-implements connector
+ * tool filtering or the accuracy messaging. It enforces denial (drops denied
+ * tools from the turn's toolset) AND builds a compact rider letting the model
+ * give an accurate message for each connector state instead of a generic
+ * "I don't have access":
+ *
+ * 1. Toggled off — connected provider whose tool is denied → "turned off,
+ *    re-enable in Connected Apps".
+ * 2a. Pruned / 2b. no tool — covered by a general line telling the model not to
+ *    claim no-access for a connected app. It rides along only when another
+ *    section is present (on its own it isn't actionable).
+ * 3. Not connected — catalog provider absent from `connectedProviders` →
+ *    "connect it in Connected Apps".
+ *
+ * State 3 is derived from {@link TOOL_CATALOG}'s provider set — providers with
+ * no tools (e.g. Disconnect-only Dropbox) aren't actionable via tools, so they
+ * aren't surfaced here. Everything is sorted alphabetically for deterministic
+ * output (no cache / snapshot churn). `rider` is "" when nothing is actionable
+ * (every catalog provider connected and nothing denied).
+ */
+declare function buildConnectorGuidance(input: ConnectorGuidanceInput): ConnectorGuidance;
+
+/**
+ * `deriveActiveToolSets` — event-shape-agnostic sticky tool-set derivation
+ * (issue #702, Phase 4).
+ *
+ * Web derived sticky sets by scanning `ChatMessage[]` for two web-specific
+ * signals: synthetic tool-result user messages (`Tool "<name>" returned: …`)
+ * and `ActivityPhase.id`s shaped `server-tool-<name>-<n>`. This module keeps the
+ * exact matching logic but keys on a neutral {@link ToolActivationEvent[]}, so
+ * both apps feed it through a tiny adapter that maps their own message/activity
+ * store to events. That closes the terse-follow-up gap on mobile: a 3-char
+ * "yes" inside a slide conversation keeps the slide toolkit because the set
+ * stays sticky.
+ *
+ * Pure and node/RN-safe.
+ */
+
+/**
+ * A neutral activation signal derived from conversation history.
+ *
+ * - `tool-result` — a tool ran and returned; `toolName` is the tool's name.
+ * - `server-tool-phase` — a server-tool activity phase occurred; `phaseId` is
+ *   the phase id (shaped like `server-tool-<name>-<n>` on web).
+ */
+interface ToolActivationEvent {
+    kind: "tool-result" | "server-tool-phase";
+    /** The tool name, for `tool-result` events. */
+    toolName?: string;
+    /** The phase id, for `server-tool-phase` events. */
+    phaseId?: string;
+}
+/**
+ * Derive the set of tool-set names that have "genuinely activated" across a
+ * conversation's activation events. Accumulation is monotonic: a set, once
+ * detected, stays detected; the scan early-exits once every set is active.
+ *
+ * @param events - Neutral activation signals, oldest-to-newest.
+ * @param sets - Tool sets to test against (defaults to `BUILT_IN_TOOL_SETS`).
+ * @returns The active tool-set names, to pass as `activeToolSets`.
+ */
+declare function deriveActiveToolSets(events: ToolActivationEvent[], sets?: readonly ToolSet[]): string[];
+/**
+ * Merge freshly-derived sticky sets into an existing sticky list without ever
+ * removing (append-only union). Mirrors web's Zustand `setFor`: an empty
+ * detection means a truncated/paginated history window, not "drop stickiness".
+ * Returns the same array reference when nothing changed.
+ */
+declare function mergeActiveToolSets(current: string[], derived: string[]): string[];
+
+/**
+ * Tool-selection vocabulary — the neutral, product-agnostic types that let the
+ * SDK own the "which tools this turn" orchestration both `apps/web` and
+ * `apps/mobile` previously hand-duplicated (see issue #702).
+ *
+ * The split of ownership is deliberate:
+ *
+ * - The SDK owns the neutral {@link CreationIntent}→client-factory mapping
+ *   ({@link CREATION_INTENT_CLIENT_FACTORIES}) and the send-policy rules.
+ * - Each app owns its UI→{@link ToolIntentDescriptor} mapper and injects a
+ *   {@link ServerToolCatalog} (built from its own static server-tool lists) and
+ *   {@link ../assembleClientTools.ToolSelectionAdapters | adapters}. The SDK
+ *   never imports the app's tool lists — the dependency direction stays
+ *   app→SDK.
+ *
+ * This module has no runtime dependency on React, the DOM, WatermelonDB, or the
+ * generated HTTP client, so it is safe to import from the node/RN-safe
+ * `@anuma/sdk/tools/selection` subpath.
+ */
+
+/**
+ * Which orchestration path a turn runs through.
+ *
+ * - `chat` — the ordinary single-model chat turn (per-mode client + server
+ *   tools, send-policy overrides).
+ * - `council` — the multi-model comparison path; each worker sees the full
+ *   semantic server-tool filter and (optionally) its own per-worker memory
+ *   tools, and no per-mode client toolkit.
+ * - `aggregation` — the council "unify" worker; like `council` but must never
+ *   persist memories (no `memory_vault_save`).
+ */
+type ToolLane = "chat" | "council" | "aggregation";
+/**
+ * The neutral creation intent for a chat turn. This is the union of web's
+ * `(chatMode, activeTool)` triple and mobile's `ChatMode`, normalized so a
+ * single resolver reproduces both.
+ *
+ * `music` / `sfx` scope a coerced turn to a single audio generator; `audio` is
+ * the free-choice bundle (music + sfx). Apps that expose only a combined audio
+ * mode use `audio`; the scoped keys exist so a `tool_choice: "required"` turn
+ * cannot call the wrong generator.
+ */
+type CreationIntent = "plain" | "image" | "audio" | "music" | "sfx" | "video" | "remove-image-bg" | "app" | "slides" | "document" | "web-search" | "deep-research";
+/**
+ * A client-tool factory the SDK (or the host, for `saved`/`background`/
+ * `schedule`) can instantiate. Presence of the matching adapter in
+ * {@link ../assembleClientTools.ToolSelectionAdapters} GATES the factory — an
+ * absent adapter yields zero tools, which is what lets one unified plan produce
+ * web's full toolkit and mobile's subset automatically.
+ */
+type ClientFactoryKey = "memory" | "connectors" | "slides" | "app" | "document" | "ui" | "saved" | "background" | "schedule";
+/**
+ * How the assembled client tools are trimmed for the turn.
+ *
+ * - `auto` — the SDK semantic filter (`autoFilterClientTools`): send only the
+ *   tools relevant to the prompt (plus always-on memory + sticky sets).
+ * - `include-all` — send every assembled tool (builder modes: slides/app).
+ * - `slide-editor` — keep only the slide-editing tools (the fullscreen-editor
+ *   overlay); everything else is dropped even off-topic.
+ */
+type ClientToolsFilterMode = "auto" | "include-all" | "slide-editor";
+/** A custom client-tools filter: given the assembled tools, return the subset to send. */
+type AssembledToolsFilterFn<TTool = unknown> = (tools: TTool[]) => TTool[] | Promise<TTool[]>;
+/**
+ * App-facing thinking hint. There is intentionally no `ThinkingMode` type in
+ * the SDK core — each app translates this hint into its provider reasoning
+ * config (e.g. web's `getReasoningConfigForModel`). The SDK only carries the
+ * neutral hint so both apps agree on when a mode is "fast" vs "extended".
+ */
+type ThinkingModeHint = "fast" | "thinking" | "extended";
+/** Resolved tool-choice coercion for the turn. */
+type ToolChoice = "auto" | "required";
+/** A server-tools filter: a static allow-list of names, or a semantic filter fn. */
+type ServerToolsFilter = string[] | ServerToolsFilterFunction;
+/** Post-resolution client-tool mutations, applied by the host at send time. */
+type PostFilterKey = 
+/** Strip `memory_vault_save` because the turn coerces a single tool (`tool_choice: "required"`). */
+"strip-memory-save-when-coerced"
+/** Web: strip `memory_vault_save` on a pure retrieval-intent prompt. */
+ | "strip-memory-save-on-retrieval-intent"
+/** Web: strip ALL server tools on a save-intent prompt (avoid a search loop before saving). */
+ | "strip-server-tools-on-save-intent";
+/**
+ * The neutral description of a turn a host hands to {@link ../plan.resolvePlan}.
+ * Each app writes a small UI→descriptor mapper; the resolver is otherwise
+ * identical across apps.
+ */
+interface ToolIntentDescriptor {
+    /** Which orchestration path (chat / council / aggregation). */
+    lane: ToolLane;
+    /** The creation intent for the turn. Ignored for council/aggregation lanes. */
+    creation: CreationIntent;
+    /** Sticky tool-set names carried from conversation history (see `deriveActiveToolSets`). */
+    activeToolSets?: string[];
+    /** Attachments present on this turn — drives attachment-aware server-tool filters. */
+    attachments?: {
+        hasImages: boolean;
+        hasVideos: boolean;
+    };
+    /** The fullscreen editor open behind an ordinary chat turn, if any. */
+    editorPinned?: "slides" | null;
+    /** Message-aware escalation: the prompt reads as "make me a deck". */
+    slideDeckIntent?: boolean;
+    /**
+     * Message-aware signal that the prompt reads as an image edit. When true it
+     * SUPPRESSES slide-deck escalation (`slideDeckIntent`) in `resolvePlan` — an
+     * image-edit turn must not be re-routed into the slide builder. Mirrors web's
+     * `!imageEditActive` guard on slide-deck intent.
+     */
+    imageEditIntent?: boolean;
+}
+/**
+ * Context passed to a catalog entry's server-tools factory form so it can vary
+ * by attachments (e.g. drop background-removal when only a video is attached).
+ */
+interface ServerToolsFilterContext {
+    attachments?: {
+        hasImages: boolean;
+        hasVideos: boolean;
+    };
+}
+/**
+ * One creation intent's server-tool policy plus its send-policy defaults,
+ * supplied by the app.
+ *
+ * Provide EITHER a static `serverTools` value (an allow-list or a semantic
+ * filter function) OR the attachment-aware `resolveServerTools` factory — the
+ * latter takes precedence and is what the plain-chat entry uses (it binds a
+ * logger and drops background-removal on a video-only attachment, which a
+ * static value cannot express). The two are separate fields, not a union,
+ * because a semantic filter is itself a function and would be indistinguishable
+ * from a `(ctx) => filter` factory by shape alone.
+ */
+interface ServerToolCatalogEntry {
+    /** The server tools for this intent — a static allow-list or a semantic filter function. */
+    serverTools?: ServerToolsFilter;
+    /**
+     * Attachment-aware form: produces the server tools for the turn from its
+     * context. Takes precedence over `serverTools` when present.
+     */
+    resolveServerTools?: (ctx: ServerToolsFilterContext) => ServerToolsFilter;
+    /** Override the default client-tools filter for this intent. */
+    clientToolsFilter?: ClientToolsFilterMode | AssembledToolsFilterFn;
+    /** Explicit tool-choice; omit to let the shape of `serverTools` decide (see `resolveToolChoice`). */
+    toolChoice?: ToolChoice;
+    /** Per-intent max tool rounds (web uses a flat 35; mobile varies by mode). */
+    maxToolRounds?: number;
+    /** Per-intent thinking hint (e.g. slides→fast, deep-research→extended). */
+    thinkingMode?: ThinkingModeHint;
+    /** An authoritative system prompt for this intent (e.g. the slide/deep-research prompt). */
+    systemPrompt?: string;
+    /** Server tools that must always be present regardless of filtering. */
+    forcedServerTools?: string[];
+}
+/**
+ * The app-supplied catalog: a per-intent (and per-lane, for council) map of
+ * {@link ServerToolCatalogEntry}. Built by each app from its own static
+ * server-tool lists via a `buildServerToolCatalog()` helper and injected into
+ * `resolvePlan(descriptor, { catalog })`. The SDK stays catalog-agnostic — this
+ * is the seam that keeps the SDK from ever importing the app's tool lists.
+ *
+ * Named `ServerToolCatalog` (not `ToolCatalog`) to stay distinct from the SDK's
+ * existing `TOOL_CATALOG` (a connector→label map for the denied-tools rider).
+ */
+type ServerToolCatalog = Partial<Record<CreationIntent | ToolLane, ServerToolCatalogEntry>>;
+/**
+ * The fully-resolved plan for a turn: what `resolvePlan` produces and
+ * `assembleClientTools` + the host's send layer consume.
+ */
+interface ToolPlanSpec {
+    /** Which client-tool factories to instantiate (capability-gated at assembly). */
+    clientFactories: ClientFactoryKey[];
+    /** How to trim the assembled client tools. */
+    clientToolsFilter: ClientToolsFilterMode | AssembledToolsFilterFn;
+    /** The server-tools filter for the turn (resolved value, factory already applied). */
+    serverTools: ServerToolsFilter;
+    /** Server tools that must always be present. */
+    forcedServerTools?: string[];
+    /** Sticky tool-set names to force-activate in the semantic client filter. */
+    activeToolSets: string[];
+    /** The resolved tool-choice coercion. */
+    toolChoice: ToolChoice;
+    /** Max tool rounds (undefined → the host/SDK default). */
+    maxToolRounds?: number;
+    /** Thinking hint (undefined → the host default). */
+    thinkingMode?: ThinkingModeHint;
+    /** Authoritative system-prompt riders for the turn (tool-set personas ride in separately). */
+    systemPromptRiders: string[];
+    /** Client-tool mutations the host applies at send time. */
+    postFilters: PostFilterKey[];
+}
+/**
+ * Full generative client toolkit — the unified plain-chat / creation-mode
+ * factory set. Web registers all of these unconditionally today; mobile
+ * registers only the subset whose adapters it wires. Under capability-gated
+ * assembly the SAME list yields web's superset and mobile's subset, so "make me
+ * a deck" works from plain chat on whichever platform wires the slides adapter.
+ */
+declare const FULL_GENERATIVE_CLIENT_FACTORIES: readonly ClientFactoryKey[];
+/**
+ * The neutral {@link CreationIntent}→{@link ClientFactoryKey}[] mapping the SDK
+ * owns. Creation modes (image/audio/video/…) share the full generative set —
+ * the server-tool coercion + semantic filter do the narrowing, exactly as web's
+ * fall-through does today. Builder modes (`app`, `slides`) are deliberately
+ * restrictive.
+ */
+declare const CREATION_INTENT_CLIENT_FACTORIES: Record<CreationIntent, readonly ClientFactoryKey[]>;
+/**
+ * Default client-tools filter per intent. Generative modes use the semantic
+ * filter; builder modes send their full toolkit (`include-all`).
+ */
+declare const CREATION_INTENT_CLIENT_FILTER: Record<CreationIntent, ClientToolsFilterMode>;
+/**
+ * Built-in tool-set names (mirrors `BUILT_IN_TOOL_SETS[].name`). The generative
+ * toolkits that a creation intent should force-activate as sticky sets — so a
+ * builder mode's persona/toolkit rides in, and a follow-up stays in that lane.
+ */
+declare const CREATION_INTENT_TOOL_SET: Partial<Record<CreationIntent, string>>;
+
+/**
+ * `assembleClientTools` — capability-gated client-tool assembly (issue #702,
+ * Phase 3). Given a resolved plan's `clientFactories` and a set of adapters, it
+ * instantiates only the factories whose adapter is present and concatenates
+ * them in a canonical order.
+ *
+ * The presence of an adapter GATES its factory — the generalization of
+ * `createDocumentTools` returning `[]` when `displayDocument` is absent
+ * (src/tools/document/index.ts). This is what lets ONE unified plan produce
+ * web's full toolkit and mobile's subset automatically: web wires every
+ * builder, mobile wires only the ones its RN surface supports, and the absent
+ * ones contribute nothing.
+ *
+ * The SDK deliberately owns the GATING, ORDER, and filter application — not the
+ * per-factory wiring. Each app's factory instantiation (slide auto-display,
+ * app-lineage tracking, RN-vs-web storage, logging instrumentation) is
+ * genuinely app-specific and stays app-side, expressed as a builder here.
+ *
+ * Pure and node/RN-safe.
+ */
+
+/** Minimal logger the assembler uses when a builder throws. */
+interface SelectionLogger {
+    warn(message: string, context?: unknown): void;
+    error(message: string, context?: unknown): void;
+    debug?(message: string, context?: unknown): void;
+}
+/**
+ * A per-factory builder: returns the tools for one {@link ClientFactoryKey}.
+ * Synchronous — factory instantiation is synchronous in both apps, and this
+ * lets `assembleClientTools` run inside a synchronous React `useMemo`. Resolve
+ * any async work (e.g. fetching saved tools) before calling.
+ */
+type ClientFactoryBuilder<TTool = ToolConfig> = () => TTool[];
+/**
+ * Adapters for {@link assembleClientTools}. The `builders` map is the gate: a
+ * factory key with a builder produces its tools; a key with no builder produces
+ * nothing. Each app supplies the builders for the capabilities its surface
+ * supports (web: all; mobile: memory/connectors/document/slides today).
+ */
+interface ToolSelectionAdapters<TTool = ToolConfig> {
+    /** Logged to when a builder throws; assembly continues without that factory. */
+    logger?: SelectionLogger;
+    /** Per-factory builders. Presence gates the factory on. */
+    builders: Partial<Record<ClientFactoryKey, ClientFactoryBuilder<TTool>>>;
+}
+/**
+ * Instantiate the plan's client factories, gated by adapter presence, in the
+ * canonical `clientFactories` order. A builder that throws is logged and
+ * skipped so one failing capability never takes down the whole turn.
+ *
+ * The result is the CANDIDATE array. Apply {@link filterAssembledClientTools}
+ * (or the semantic `autoFilterClientTools`) to trim it for the turn.
+ *
+ * Synchronous, so it can run directly inside a React `useMemo` (which is how
+ * both apps build their per-turn client-tool list).
+ */
+declare function assembleClientTools<TTool = ToolConfig>(spec: Pick<ToolPlanSpec, "clientFactories">, adapters: ToolSelectionAdapters<TTool>): TTool[];
+/**
+ * Apply the plan's static client-tools filter to the assembled candidates.
+ *
+ * - `include-all` → every tool (builder modes).
+ * - `slide-editor` → only tools whose name is in `slideEditorToolNames`; when
+ *   that set is absent it fails CLOSED (returns `[]`) so a missing name set can
+ *   never leave the overlay silently unrestricted. Callers that want the full
+ *   toolkit use `include-all`, not slide-editor-without-names.
+ * - `auto` → returned unchanged; the caller runs the semantic
+ *   `autoFilterClientTools` (which needs prompt embeddings) instead.
+ * - a function → applied directly.
+ */
+declare function filterAssembledClientTools<TTool = ToolConfig>(tools: TTool[], mode: ClientToolsFilterMode | AssembledToolsFilterFn<TTool>, opts?: {
+    /** Tool names the slide-editor overlay keeps (the slide tool set members). */
+    slideEditorToolNames?: ReadonlySet<string>;
+    /** Name accessor; defaults to the SDK's client-tool name reader. */
+    getName?: (t: TTool) => string;
+}): TTool[] | Promise<TTool[]>;
+
+/**
+ * `resolvePlan` — the single source of truth for "which tools this turn"
+ * (issue #702, Phase 2). Given a neutral {@link ToolIntentDescriptor} and an
+ * app-injected {@link ServerToolCatalog}, it produces a fully-resolved
+ * {@link ToolPlanSpec} that both web and mobile consume, replacing each app's
+ * hand-written per-mode switch.
+ *
+ * Pure and node/RN-safe. The plan is data — the host feeds `clientFactories`
+ * into `assembleClientTools`, and `serverTools`/`toolChoice`/`maxToolRounds`/
+ * `thinkingMode` into its send layer.
+ */
+
+/** Context for {@link resolvePlan}: the injected catalog plus host defaults. */
+interface ResolvePlanContext {
+    /** The app-built per-intent/-lane server-tool catalog. */
+    catalog: ServerToolCatalog;
+    /** Fallback max tool rounds when a catalog entry doesn't set one (web: 35). */
+    defaultMaxToolRounds?: number;
+    /** Fallback thinking hint when a catalog entry doesn't set one. */
+    defaultThinkingMode?: ThinkingModeHint;
+    /**
+     * App-detected memory intents for the turn (web only today). When present,
+     * they add the corresponding post-filters so the host strips the vault-save
+     * tool on a retrieval-intent prompt and the server tools on a save-intent
+     * prompt. Mobile omits this.
+     */
+    memoryIntent?: {
+        retrieval?: boolean;
+        save?: boolean;
+    };
+}
+/**
+ * Resolve the complete tool plan for a turn.
+ *
+ * Chat lane: keys on the creation intent — client factories from the neutral
+ * SDK mapping, server tools + send-policy knobs from the catalog, tool-choice
+ * shape-derived unless the intent is a builder mode or a slide-deck intent
+ * (both forced `auto`). Council/aggregation lanes carry no per-mode client
+ * toolkit here — `resolveCouncilPlan` (council.ts) adds per-worker memory tools
+ * on top of this server-tool plan.
+ */
+declare function resolvePlan(descriptor: ToolIntentDescriptor, ctx: ResolvePlanContext): ToolPlanSpec;
+
+/**
+ * Council tool resolution (issue #702, Phase 6).
+ *
+ * The council path bypasses the per-mode chat switch: each worker sees the full
+ * semantic server-tool filter and its OWN per-worker memory tools (built from
+ * that worker's model so a private-capable model sees `['private','shared']`
+ * and a standard model sees `['shared']` only). The aggregation ("unify")
+ * worker must never persist — its `memory_vault_save` is dropped.
+ *
+ * This module composes each worker's client-tool candidate array and runs it
+ * through the SAME `autoFilterClientTools` the chat hook uses, so council and
+ * chat share one selection. Building this on the exported selector is what lets
+ * mobile council gain per-worker memory tools without re-implementing anything.
+ *
+ * Pure and node/RN-safe.
+ */
+
+/**
+ * Resolve the council/aggregation server-tool plan. This is the chat resolver's
+ * council-lane path: a semantic server-tool filter, no per-mode client toolkit,
+ * and (for aggregation) a coerced-save strip. Per-worker client tools are added
+ * separately via {@link selectCouncilClientTools}.
+ */
+declare function resolveCouncilPlan(descriptor: ToolIntentDescriptor, ctx: ResolvePlanContext): ToolPlanSpec;
+/** The council/aggregation server-tools filter (a semantic filter, from the catalog). */
+declare function resolveCouncilServerTools(descriptor: ToolIntentDescriptor, ctx: ResolvePlanContext): ServerToolsFilter;
+/** Inputs to compose one council worker's client-tool candidate array. */
+interface CouncilClientToolsInput<TTool extends LlmapiChatCompletionTool = ToolConfig> {
+    /**
+     * Memory tools built from THIS worker's model (via the host's per-model
+     * memory-tool factory). Empty for workers that carry no memory tools.
+     */
+    memoryTools: TTool[];
+    /** Model-agnostic shared client tools for council (connectors, saved). */
+    sharedTools?: TTool[];
+    /**
+     * Whether this worker may persist memories. `false` for the aggregation /
+     * unify worker — its `memory_vault_save` is dropped.
+     */
+    canPersistMemory: boolean;
+}
+/**
+ * Compose a council worker's client-tool candidate array: per-worker memory
+ * tools first, then the shared tools, with `memory_vault_save` removed when the
+ * worker may not persist (aggregation).
+ */
+declare function composeCouncilClientTools<TTool extends LlmapiChatCompletionTool = ToolConfig>(input: CouncilClientToolsInput<TTool>): TTool[];
+/** Options forwarded to the shared `autoFilterClientTools` selection. */
+interface CouncilClientSelectionOptions {
+    promptEmbeddings: number[] | number[][] | null;
+    cache: Map<string, number[]>;
+    embeddingOptions: {
+        getToken?: () => Promise<string | null>;
+        apiKey?: string;
+        baseUrl?: string;
+        model?: string;
+    };
+    extraToolSets?: ToolSet[];
+    activeToolSets?: string[];
+    noEmbeddingsReason?: "short-prompt" | "error";
+}
+/**
+ * Select a council worker's client tools by composing its candidate array and
+ * running the SAME semantic filter the chat hook runs. Returns the filtered
+ * tools plus which tool sets genuinely activated (for persona injection).
+ */
+declare function selectCouncilClientTools<TTool extends LlmapiChatCompletionTool = ToolConfig>(input: CouncilClientToolsInput<TTool>, options: CouncilClientSelectionOptions): Promise<{
+    tools: LlmapiChatCompletionTool[];
+    activatedSetNames?: ReadonlySet<string>;
+}>;
+
+/**
+ * Send-policy primitives — the per-turn `tool_choice` / `maxToolRounds` /
+ * thinking-mode / coerced-memory-write rules, unified so web and mobile stop
+ * hand-duplicating them (issue #702, Phase 1).
+ *
+ * These were previously spread across web's `useChatSetup` + `useChatSubmitHandler`
+ * + `webChatSendMessage` and mobile's `chatModeRouting`. They are pure and
+ * node/RN-safe.
+ */
+
+/** The vault-save tool name — the one client tool stripped on a coerced turn. */
+declare const MEMORY_SAVE_TOOL_NAME = "memory_vault_save";
+/**
+ * Resolve the turn's tool-choice from the SHAPE of its server-tools filter,
+ * unless the caller/catalog set an explicit value.
+ *
+ * The rule (matching both apps today): an explicit choice wins; otherwise a
+ * non-empty static array of server tools coerces `required` (creation modes
+ * like image/audio/video/remove-bg must call their one tool), while a filter
+ * function or an empty array defers to `auto` (plain chat, and builder modes
+ * whose server list is empty).
+ *
+ * This is load-bearing: naively defaulting an unset choice to `auto` would
+ * silently downgrade image/audio/video/remove-bg from single-forced-tool to
+ * `auto` — a real behavior regression.
+ */
+declare function resolveToolChoice(serverTools: ServerToolsFilter, explicit?: ToolChoice): ToolChoice;
+/**
+ * The per-turn max tool rounds. Returns the catalog entry's value when set,
+ * else the supplied fallback (e.g. web's flat 35), else undefined to let the
+ * SDK/host default apply.
+ */
+declare function getMaxToolRounds(entry: ServerToolCatalogEntry | undefined, fallback?: number): number | undefined;
+/**
+ * The per-turn thinking hint. Returns the catalog entry's value when set, else
+ * undefined so the host applies its model-dependent default (e.g. web's
+ * gemini-fast→`fast`, otherwise `thinking`). The app translates the hint into
+ * its provider reasoning config.
+ */
+declare function getThinkingMode(entry: ServerToolCatalogEntry | undefined, fallback?: ThinkingModeHint): ThinkingModeHint | undefined;
+/**
+ * Remove `memory_vault_save` from a client-tool list when the turn coerces a
+ * single tool (`tool_choice: "required"`). Under coercion the model MUST call
+ * exactly one tool; leaving the save tool in risks the model "saving" instead
+ * of running the coerced generator. Both apps do this today.
+ *
+ * `recall_memory` and every other tool are preserved. Returns the same array
+ * reference when nothing changed, so callers can cheaply skip re-renders.
+ */
+declare function stripCoercedMemoryWrite<T extends LlmapiChatCompletionTool>(clientTools: T[], toolChoice: ToolChoice): T[];
+
+/**
+ * Server-tools policy — resolve the concrete server-tools filter for a turn
+ * from the app-injected {@link ServerToolCatalog} (issue #702, Phase 2).
+ *
+ * The catalog is opaque to the SDK: each app builds it from its own static
+ * server-tool lists (`IMAGE_SERVER_TOOLS`, `SLIDE_SERVER_TOOLS`, …) and passes
+ * it in. This module only knows how to pick the right entry and, when the entry
+ * is an attachment-aware factory, apply it with the turn's context.
+ */
+
+/**
+ * Look up the catalog entry for a descriptor. Chat turns key on the creation
+ * intent; council/aggregation turns key on the lane.
+ */
+declare function getCatalogEntry(descriptor: ToolIntentDescriptor, catalog: ServerToolCatalog): ServerToolCatalogEntry | undefined;
+/**
+ * Resolve a catalog entry's server tools to a concrete filter. The
+ * attachment-aware `resolveServerTools` factory takes precedence over the
+ * static `serverTools` value. When the intent has no catalog entry (or an empty
+ * one) the fallback is used — defaulting to an empty allow-list, which
+ * `resolveToolChoice` reads as `auto`.
+ */
+declare function resolveServerTools(descriptor: ToolIntentDescriptor, catalog: ServerToolCatalog, fallback?: ServerToolsFilter): ServerToolsFilter;
+/**
+ * A creation intent whose server tools are a coercing (non-empty static) list —
+ * useful for tests and diagnostics. Distinguishes the "required" creation modes
+ * from the semantic-filter chat modes without resolving a full plan.
+ */
+declare function isCoercingIntent(creation: CreationIntent, catalog: ServerToolCatalog): boolean;
+
+export { type AssembledToolsFilterFn, BUILT_IN_TOOL_SETS, CLIENT_TOOLS_MIN_SIMILARITY, CLIENT_TOOLS_RELEVANCE_RATIO, CREATION_INTENT_CLIENT_FACTORIES, CREATION_INTENT_CLIENT_FILTER, CREATION_INTENT_TOOL_SET, type CachedServerTools, type ClientFactoryBuilder, type ClientFactoryKey, type ClientToolsFilterMode, type ConnectorGuidance, type ConnectorGuidanceInput, type CouncilClientSelectionOptions, type CouncilClientToolsInput, type CreateServerToolsFilterOptions, type CreationIntent, DEFAULT_CACHE_EXPIRATION_MS, DEFAULT_EXCLUDED_SERVER_TOOLS, DEFAULT_SERVER_TOOLS_MATCH_OPTIONS, type DeferLoadingConfig, FULL_GENERATIVE_CLIENT_FACTORIES, MAX_CLIENT_TOOLS_AFTER_FILTER, MEMORY_SAVE_TOOL_NAME, MIN_CONTENT_LENGTH_FOR_TOOLS, type ParsedServerToolsResponse, type PostFilterKey, type ResolvePlanContext, SERVER_TOOL_DEPENDENCY_SETS, type SelectServerSideToolsOptions, type SelectServerToolsForPromptOptions, type SelectionLogger, type ServerTool, type ServerToolCatalog, type ServerToolCatalogEntry, type ServerToolsFilter, type ServerToolsFilterContext, type ServerToolsFilterFunction, type ServerToolsOptions, type ServerToolsResponse, TOOL_CATALOG, type ThinkingModeHint, type ToolActivationEvent, type ToolChoice, type ToolConfig, type ToolExecutor, type ToolIntentDescriptor, type ToolLane, type ToolMatchOptions, type ToolMatchResult, type ToolPlanSpec, type ToolSelectionAdapters, type ToolSet, type ToolsCacheBackend, activatedToolSetNames, applyToolSets, assembleClientTools, autoFilterClientTools, buildConnectorGuidance, buildDeniedToolsRider, clearServerToolsCache, composeCouncilClientTools, computeToolGuidance, createServerToolsFilter, defaultServerToolsFilter, deriveActiveToolSets, expandToolSetsAdditive, filterAssembledClientTools, filterServerTools, findMatchingTools, getCachedServerTools, getCatalogEntry, getMaxToolRounds, getServerTools, getThinkingMode, getToolDescription, getToolName, getToolsChecksum, isCoercingIntent, localStorageToolsCache, mergeActiveToolSets, mergeTools, resolveCouncilPlan, resolveCouncilServerTools, resolvePlan, resolveServerTools, resolveToolChoice, scoreTools, selectCouncilClientTools, selectServerSideTools, selectServerToolsForPrompt, shouldRefreshTools, stripCoercedMemoryWrite, toolSetSystemPrompts };