@anuma/sdk 6.12.0 → 6.13.0

package/dist/react/index.mjs

@@ -11499,6 +11499,20 @@ function clientToolToCompletionsFormat(tool) {
 }
 var TOOL_SEARCH_TOOL_TYPE = "tool_search_tool_regex_20251119";
 var TOOL_SEARCH_TOOL_NAME = "tool_search_tool_regex";
+function resolveDeferredServerTools(allServerTools, serverToolsFilter, config) {
+  const allowed = serverToolsFilter === void 0 || typeof serverToolsFilter === "function" ? allServerTools : filterServerTools(allServerTools, [...serverToolsFilter]);
+  const excluded = new Set(config.excludeTools ?? []);
+  if (typeof serverToolsFilter === "function") {
+    for (const name of serverToolsFilter.excludeTools ?? []) excluded.add(name);
+  }
+  if (excluded.size === 0) return allowed;
+  return allowed.filter((tool) => !excluded.has(tool.name));
+}
+function deferFormattingConfig(serverToolsFilter, config) {
+  if (!config?.enabled) return config;
+  const isExplicitList = serverToolsFilter !== void 0 && typeof serverToolsFilter !== "function";
+  return isExplicitList ? void 0 : config;
+}
 function byNameAscending(a, b) {
   if (a.name < b.name) return -1;
   if (a.name > b.name) return 1;
@@ -11825,7 +11839,7 @@ function createServerToolsFilter(options = {}) {
   const exclude = new Set(options.excludeTools ?? []);
   const sets = options.toolSets ?? [];
   const matchOpts = options.matchOptions;
-  return (embeddings, tools) => {
+  const filter = (embeddings, tools) => {
     const matches = findMatchingTools(embeddings, tools, matchOpts);
     if (matches.length === 0) return [];
     const matchedNames = new Set(matches.map((m) => m.tool.name));
@@ -11843,6 +11857,10 @@ function createServerToolsFilter(options = {}) {
     for (const name of exclude) finalNames.delete(name);
     return [...finalNames];
   };
+  return Object.defineProperty(filter, "excludeTools", {
+    value: Object.freeze([...exclude]),
+    enumerable: false
+  });
 }
 var DEFAULT_EXCLUDED_SERVER_TOOLS = [
   "AnumaVisionMCP-anuma_analyze_image",
@@ -11924,7 +11942,8 @@ async function selectServerToolsForPrompt(options) {
     return [];
   }
   if (allServerTools.length === 0) return [];
-  if (deferLoading?.enabled) return allServerTools;
+  if (deferLoading?.enabled)
+    return resolveDeferredServerTools(allServerTools, serverToolsFilter, deferLoading);
   if (typeof serverToolsFilter === "function") {
     if (prompt.length < MIN_CONTENT_LENGTH_FOR_TOOLS) return [];
     let promptEmbedding;
@@ -12351,7 +12370,8 @@ async function previewToolSelection(options) {
           cache: serverToolsConfig?.cache
         });
         const allow = new Set(serverToolsFilter);
-        gatedServerNames = allServerTools.filter((t) => allow.has(t.name)).map((t) => t.name);
+        const gated = allServerTools.filter((t) => allow.has(t.name));
+        gatedServerNames = (serverToolsConfig?.deferLoading?.enabled ? resolveDeferredServerTools(gated, serverToolsFilter, serverToolsConfig.deferLoading) : gated).map((t) => t.name);
       } catch {
       }
     }
@@ -12400,7 +12420,11 @@ async function previewToolSelection(options) {
         cache: serverToolsConfig?.cache
       });
       if (serverToolsConfig?.deferLoading?.enabled) {
-        serverToolNames = allServerTools.map((t) => t.name);
+        serverToolNames = resolveDeferredServerTools(
+          allServerTools,
+          serverToolsFilter,
+          serverToolsConfig.deferLoading
+        ).map((t) => t.name);
       } else if (typeof serverToolsFilter === "function") {
         serverToolNames = serverToolsFilter(promptEmbedding, allServerTools);
       } else {
@@ -13416,7 +13440,11 @@ function useChatStorage(options) {
               cache: serverToolsConfig?.cache
             });
             if (serverToolsConfig?.deferLoading?.enabled) {
-              filteredServerTools2 = allServerTools;
+              filteredServerTools2 = resolveDeferredServerTools(
+                allServerTools,
+                serverToolsFilter,
+                serverToolsConfig.deferLoading
+              );
             } else if (isServerToolsFunction2) {
               if (skipStorageEmbeddings) {
                 const toolNames = serverToolsFilter(skipStorageEmbeddings, allServerTools);
@@ -13457,7 +13485,7 @@ function useChatStorage(options) {
             filteredServerTools2,
             filteredClientTools2,
             effectiveApiType2,
-            serverToolsConfig?.deferLoading
+            deferFormattingConfig(serverToolsFilter, serverToolsConfig?.deferLoading)
           );
         }
         if (onToolSelection) {
@@ -13816,7 +13844,11 @@ function useChatStorage(options) {
         if (allServerTools) {
           try {
             if (serverToolsConfig?.deferLoading?.enabled && effectiveApiType === "responses") {
-              filteredServerTools = allServerTools;
+              filteredServerTools = resolveDeferredServerTools(
+                allServerTools,
+                serverToolsFilter,
+                serverToolsConfig.deferLoading
+              );
             } else if (isServerToolsFunction) {
               if (userMessageEmbeddings) {
                 const toolNames = serverToolsFilter(userMessageEmbeddings, allServerTools);
@@ -13896,7 +13928,7 @@ function useChatStorage(options) {
           filteredServerTools,
           filteredClientTools,
           effectiveApiType,
-          serverToolsConfig?.deferLoading
+          deferFormattingConfig(serverToolsFilter, serverToolsConfig?.deferLoading)
         );
       }
       if (onToolSelection) {

package/dist/server/index.cjs

@@ -32068,6 +32068,15 @@ function filterServerTools(serverTools, includeNames) {
   const includeSet = new Set(includeNames);
   return serverTools.filter((tool) => includeSet.has(tool.name));
 }
+function resolveDeferredServerTools(allServerTools, serverToolsFilter, config) {
+  const allowed = serverToolsFilter === void 0 || typeof serverToolsFilter === "function" ? allServerTools : filterServerTools(allServerTools, [...serverToolsFilter]);
+  const excluded = new Set(config.excludeTools ?? []);
+  if (typeof serverToolsFilter === "function") {
+    for (const name of serverToolsFilter.excludeTools ?? []) excluded.add(name);
+  }
+  if (excluded.size === 0) return allowed;
+  return allowed.filter((tool) => !excluded.has(tool.name));
+}
 var DEFAULT_TOOL_MATCH_OPTIONS = {
   limit: 5,
   minSimilarity: 0.3,
@@ -32344,7 +32353,7 @@ function createServerToolsFilter(options = {}) {
   const exclude = new Set(options.excludeTools ?? []);
   const sets = options.toolSets ?? [];
   const matchOpts = options.matchOptions;
-  return (embeddings, tools) => {
+  const filter = (embeddings, tools) => {
     const matches = findMatchingTools(embeddings, tools, matchOpts);
     if (matches.length === 0) return [];
     const matchedNames = new Set(matches.map((m) => m.tool.name));
@@ -32362,6 +32371,10 @@ function createServerToolsFilter(options = {}) {
     for (const name of exclude) finalNames.delete(name);
     return [...finalNames];
   };
+  return Object.defineProperty(filter, "excludeTools", {
+    value: Object.freeze([...exclude]),
+    enumerable: false
+  });
 }
 var DEFAULT_EXCLUDED_SERVER_TOOLS = [
   "AnumaVisionMCP-anuma_analyze_image",
@@ -32443,7 +32456,8 @@ async function selectServerToolsForPrompt(options) {
     return [];
   }
   if (allServerTools.length === 0) return [];
-  if (deferLoading?.enabled) return allServerTools;
+  if (deferLoading?.enabled)
+    return resolveDeferredServerTools(allServerTools, serverToolsFilter, deferLoading);
   if (typeof serverToolsFilter === "function") {
     if (prompt.length < MIN_CONTENT_LENGTH_FOR_TOOLS) return [];
     let promptEmbedding;

package/dist/server/index.d.mts

@@ -3013,6 +3013,22 @@ interface DeferLoadingConfig {
     enabled: boolean;
     /** Server-tool names to keep non-deferred (besides the tool-search tool), in priority order. */
     hotToolNames: readonly string[];
+    /**
+     * Server-tool names to drop entirely while defer-loading is on.
+     *
+     * Defer widens the per-turn selection to the whole catalog, which also bypasses the `excludeTools`
+     * baked into a caller's semantic filter. A filter built by {@link createServerToolsFilter} tags itself
+     * with its own exclusions and those are honoured automatically — so most callers need nothing here.
+     *
+     * Set this when the filter's tag can't be seen: a hand-written filter, a filter wrapped in a plain
+     * closure (the wrapper drops the tag), or a static-array `serverToolsFilter`. Anything excluded
+     * UNCONDITIONALLY (a tool the app replaces with its own UI, a capability the model already has
+     * natively) belongs in one of the two places, or defer quietly hands it back to the model.
+     *
+     * This list is UNIONED with the filter's own tag, never a replacement for it — so adding one name
+     * here cannot re-admit the tools the filter already excludes.
+     */
+    excludeTools?: readonly string[];
 }
 /**
  * Result of tool matching with similarity score
@@ -3192,7 +3208,7 @@ interface CreateServerToolsFilterOptions {
  * });
  * ```
  */
-declare function createServerToolsFilter(options?: CreateServerToolsFilterOptions): (embeddings: number[] | number[][], tools: ServerTool[]) => string[];
+declare function createServerToolsFilter(options?: CreateServerToolsFilterOptions): ServerToolsFilterFunction;
 /**
  * Default exclusions baked into `defaultServerToolsFilter`.
  *
@@ -3258,13 +3274,21 @@ declare const SERVER_TOOL_DEPENDENCY_SETS: ToolSet[];
  * 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[];
+declare const defaultServerToolsFilter: ServerToolsFilterFunction;
 /**
  * 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[];
+type ServerToolsFilterFunction = ((embeddings: number[] | number[][], tools: ServerTool[]) => string[]) & {
+    /**
+     * The unconditional exclusions this filter applies, exposed by
+     * {@link createServerToolsFilter} so defer-loading can honour them without the caller
+     * repeating the list — see {@link resolveDeferredServerTools}. Absent on a hand-written
+     * filter, or on one wrapped in a plain closure.
+     */
+    readonly excludeTools?: readonly string[];
+};
 /**
  * Options for `selectServerToolsForPrompt`.
  */
@@ -3292,9 +3316,10 @@ interface SelectServerToolsForPromptOptions {
      */
     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.
+     * Phase 3 defer-loading. When `enabled`, this helper skips SEMANTIC filtering to mirror
+     * useChatStorage's responses send path, which hands the catalog to mergeTools + tool-search. The
+     * caller's unconditional constraints still apply — an explicit static array, and exclusions (see
+     * {@link resolveDeferredServerTools}). Omit/disabled → today's filtered selection.
      */
     deferLoading?: DeferLoadingConfig;
 }

package/dist/server/index.d.ts

@@ -3013,6 +3013,22 @@ interface DeferLoadingConfig {
     enabled: boolean;
     /** Server-tool names to keep non-deferred (besides the tool-search tool), in priority order. */
     hotToolNames: readonly string[];
+    /**
+     * Server-tool names to drop entirely while defer-loading is on.
+     *
+     * Defer widens the per-turn selection to the whole catalog, which also bypasses the `excludeTools`
+     * baked into a caller's semantic filter. A filter built by {@link createServerToolsFilter} tags itself
+     * with its own exclusions and those are honoured automatically — so most callers need nothing here.
+     *
+     * Set this when the filter's tag can't be seen: a hand-written filter, a filter wrapped in a plain
+     * closure (the wrapper drops the tag), or a static-array `serverToolsFilter`. Anything excluded
+     * UNCONDITIONALLY (a tool the app replaces with its own UI, a capability the model already has
+     * natively) belongs in one of the two places, or defer quietly hands it back to the model.
+     *
+     * This list is UNIONED with the filter's own tag, never a replacement for it — so adding one name
+     * here cannot re-admit the tools the filter already excludes.
+     */
+    excludeTools?: readonly string[];
 }
 /**
  * Result of tool matching with similarity score
@@ -3192,7 +3208,7 @@ interface CreateServerToolsFilterOptions {
  * });
  * ```
  */
-declare function createServerToolsFilter(options?: CreateServerToolsFilterOptions): (embeddings: number[] | number[][], tools: ServerTool[]) => string[];
+declare function createServerToolsFilter(options?: CreateServerToolsFilterOptions): ServerToolsFilterFunction;
 /**
  * Default exclusions baked into `defaultServerToolsFilter`.
  *
@@ -3258,13 +3274,21 @@ declare const SERVER_TOOL_DEPENDENCY_SETS: ToolSet[];
  * 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[];
+declare const defaultServerToolsFilter: ServerToolsFilterFunction;
 /**
  * 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[];
+type ServerToolsFilterFunction = ((embeddings: number[] | number[][], tools: ServerTool[]) => string[]) & {
+    /**
+     * The unconditional exclusions this filter applies, exposed by
+     * {@link createServerToolsFilter} so defer-loading can honour them without the caller
+     * repeating the list — see {@link resolveDeferredServerTools}. Absent on a hand-written
+     * filter, or on one wrapped in a plain closure.
+     */
+    readonly excludeTools?: readonly string[];
+};
 /**
  * Options for `selectServerToolsForPrompt`.
  */
@@ -3292,9 +3316,10 @@ interface SelectServerToolsForPromptOptions {
      */
     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.
+     * Phase 3 defer-loading. When `enabled`, this helper skips SEMANTIC filtering to mirror
+     * useChatStorage's responses send path, which hands the catalog to mergeTools + tool-search. The
+     * caller's unconditional constraints still apply — an explicit static array, and exclusions (see
+     * {@link resolveDeferredServerTools}). Omit/disabled → today's filtered selection.
      */
     deferLoading?: DeferLoadingConfig;
 }

package/dist/server/index.mjs

@@ -8302,6 +8302,15 @@ function filterServerTools(serverTools, includeNames) {
   const includeSet = new Set(includeNames);
   return serverTools.filter((tool) => includeSet.has(tool.name));
 }
+function resolveDeferredServerTools(allServerTools, serverToolsFilter, config) {
+  const allowed = serverToolsFilter === void 0 || typeof serverToolsFilter === "function" ? allServerTools : filterServerTools(allServerTools, [...serverToolsFilter]);
+  const excluded = new Set(config.excludeTools ?? []);
+  if (typeof serverToolsFilter === "function") {
+    for (const name of serverToolsFilter.excludeTools ?? []) excluded.add(name);
+  }
+  if (excluded.size === 0) return allowed;
+  return allowed.filter((tool) => !excluded.has(tool.name));
+}
 var DEFAULT_TOOL_MATCH_OPTIONS = {
   limit: 5,
   minSimilarity: 0.3,
@@ -8578,7 +8587,7 @@ function createServerToolsFilter(options = {}) {
   const exclude = new Set(options.excludeTools ?? []);
   const sets = options.toolSets ?? [];
   const matchOpts = options.matchOptions;
-  return (embeddings, tools) => {
+  const filter = (embeddings, tools) => {
     const matches = findMatchingTools(embeddings, tools, matchOpts);
     if (matches.length === 0) return [];
     const matchedNames = new Set(matches.map((m) => m.tool.name));
@@ -8596,6 +8605,10 @@ function createServerToolsFilter(options = {}) {
     for (const name of exclude) finalNames.delete(name);
     return [...finalNames];
   };
+  return Object.defineProperty(filter, "excludeTools", {
+    value: Object.freeze([...exclude]),
+    enumerable: false
+  });
 }
 var DEFAULT_EXCLUDED_SERVER_TOOLS = [
   "AnumaVisionMCP-anuma_analyze_image",
@@ -8677,7 +8690,8 @@ async function selectServerToolsForPrompt(options) {
     return [];
   }
   if (allServerTools.length === 0) return [];
-  if (deferLoading?.enabled) return allServerTools;
+  if (deferLoading?.enabled)
+    return resolveDeferredServerTools(allServerTools, serverToolsFilter, deferLoading);
   if (typeof serverToolsFilter === "function") {
     if (prompt.length < MIN_CONTENT_LENGTH_FOR_TOOLS) return [];
     let promptEmbedding;

package/dist/tools/selection/index.cjs

@@ -86,6 +86,7 @@ __export(index_exports, {
   computeToolGuidance: () => computeToolGuidance,
   createServerToolsFilter: () => createServerToolsFilter,
   defaultServerToolsFilter: () => defaultServerToolsFilter,
+  deferFormattingConfig: () => deferFormattingConfig,
   deriveActiveToolSets: () => deriveActiveToolSets,
   expandToolSetsAdditive: () => expandToolSetsAdditive,
   filterAssembledClientTools: () => filterAssembledClientTools,
@@ -105,6 +106,7 @@ __export(index_exports, {
   mergeTools: () => mergeTools,
   resolveCouncilPlan: () => resolveCouncilPlan,
   resolveCouncilServerTools: () => resolveCouncilServerTools,
+  resolveDeferredServerTools: () => resolveDeferredServerTools,
   resolvePlan: () => resolvePlan,
   resolveServerTools: () => resolveServerTools,
   resolveToolChoice: () => resolveToolChoice,
@@ -1658,6 +1660,20 @@ function clientToolToCompletionsFormat(tool) {
 }
 var TOOL_SEARCH_TOOL_TYPE = "tool_search_tool_regex_20251119";
 var TOOL_SEARCH_TOOL_NAME = "tool_search_tool_regex";
+function resolveDeferredServerTools(allServerTools, serverToolsFilter, config) {
+  const allowed = serverToolsFilter === void 0 || typeof serverToolsFilter === "function" ? allServerTools : filterServerTools(allServerTools, [...serverToolsFilter]);
+  const excluded = new Set(config.excludeTools ?? []);
+  if (typeof serverToolsFilter === "function") {
+    for (const name of serverToolsFilter.excludeTools ?? []) excluded.add(name);
+  }
+  if (excluded.size === 0) return allowed;
+  return allowed.filter((tool) => !excluded.has(tool.name));
+}
+function deferFormattingConfig(serverToolsFilter, config) {
+  if (!config?.enabled) return config;
+  const isExplicitList = serverToolsFilter !== void 0 && typeof serverToolsFilter !== "function";
+  return isExplicitList ? void 0 : config;
+}
 function byNameAscending(a, b) {
   if (a.name < b.name) return -1;
   if (a.name > b.name) return 1;
@@ -2013,7 +2029,7 @@ function createServerToolsFilter(options = {}) {
   const exclude = new Set(options.excludeTools ?? []);
   const sets = options.toolSets ?? [];
   const matchOpts = options.matchOptions;
-  return (embeddings, tools) => {
+  const filter = (embeddings, tools) => {
     const matches = findMatchingTools(embeddings, tools, matchOpts);
     if (matches.length === 0) return [];
     const matchedNames = new Set(matches.map((m) => m.tool.name));
@@ -2031,6 +2047,10 @@ function createServerToolsFilter(options = {}) {
     for (const name of exclude) finalNames.delete(name);
     return [...finalNames];
   };
+  return Object.defineProperty(filter, "excludeTools", {
+    value: Object.freeze([...exclude]),
+    enumerable: false
+  });
 }
 var DEFAULT_EXCLUDED_SERVER_TOOLS = [
   "AnumaVisionMCP-anuma_analyze_image",
@@ -2112,7 +2132,8 @@ async function selectServerToolsForPrompt(options) {
     return [];
   }
   if (allServerTools.length === 0) return [];
-  if (deferLoading?.enabled) return allServerTools;
+  if (deferLoading?.enabled)
+    return resolveDeferredServerTools(allServerTools, serverToolsFilter, deferLoading);
   if (typeof serverToolsFilter === "function") {
     if (prompt.length < MIN_CONTENT_LENGTH_FOR_TOOLS) return [];
     let promptEmbedding;
@@ -2738,6 +2759,7 @@ async function selectCouncilClientTools(input, options) {
   computeToolGuidance,
   createServerToolsFilter,
   defaultServerToolsFilter,
+  deferFormattingConfig,
   deriveActiveToolSets,
   expandToolSetsAdditive,
   filterAssembledClientTools,
@@ -2757,6 +2779,7 @@ async function selectCouncilClientTools(input, options) {
   mergeTools,
   resolveCouncilPlan,
   resolveCouncilServerTools,
+  resolveDeferredServerTools,
   resolvePlan,
   resolveServerTools,
   resolveToolChoice,

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

@@ -272,7 +272,63 @@ interface DeferLoadingConfig {
     enabled: boolean;
     /** Server-tool names to keep non-deferred (besides the tool-search tool), in priority order. */
     hotToolNames: readonly string[];
+    /**
+     * Server-tool names to drop entirely while defer-loading is on.
+     *
+     * Defer widens the per-turn selection to the whole catalog, which also bypasses the `excludeTools`
+     * baked into a caller's semantic filter. A filter built by {@link createServerToolsFilter} tags itself
+     * with its own exclusions and those are honoured automatically — so most callers need nothing here.
+     *
+     * Set this when the filter's tag can't be seen: a hand-written filter, a filter wrapped in a plain
+     * closure (the wrapper drops the tag), or a static-array `serverToolsFilter`. Anything excluded
+     * UNCONDITIONALLY (a tool the app replaces with its own UI, a capability the model already has
+     * natively) belongs in one of the two places, or defer quietly hands it back to the model.
+     *
+     * This list is UNIONED with the filter's own tag, never a replacement for it — so adding one name
+     * here cannot re-admit the tools the filter already excludes.
+     */
+    excludeTools?: readonly string[];
 }
+/**
+ * The server-tool set defer-loading should format for one turn.
+ *
+ * Defer changes how tools are SENT (full definitions + `defer_loading` + a tool-search tool, for a
+ * byte-stable cacheable prefix). It must not change WHICH tools the caller allowed, so two things
+ * survive that a plain "just use the whole catalog" discards:
+ *
+ * 1. **an explicit static array** — `serverToolsFilter: ['x']` is a deliberate scoping, and callers
+ *    commonly pair it with `tool_choice:'required'`. Replacing it with the catalog turns "you must
+ *    call x" into "you must call something, here is everything". Defer still applies, within the array.
+ * 2. **unconditional exclusions** — see {@link DeferLoadingConfig.excludeTools}.
+ *
+ * A filter FUNCTION is deliberately NOT consulted: it is per-prompt semantic narrowing, and skipping it
+ * is the whole point of defer (the model reaches everything else through tool-search). Only the
+ * caller's unconditional constraints survive.
+ */
+declare function resolveDeferredServerTools(allServerTools: ServerTool[], serverToolsFilter: readonly string[] | ServerToolsFilterFunction | undefined, config: DeferLoadingConfig): ServerTool[];
+/**
+ * The defer config {@link mergeTools} should FORMAT this request with — `undefined` when defer
+ * formatting must be skipped even though defer-loading is enabled.
+ *
+ * Scoping the selection to a caller's explicit static array (see {@link resolveDeferredServerTools})
+ * is only half the job. `formatServerToolsWithDefer` still marks every non-hot tool `defer_loading`
+ * and prepends the tool-search tool, so for a one-tool array whose tool isn't hot — every creation
+ * mode: video, music, sfx, image, slides — the search tool becomes the ONLY directly callable entry
+ * in the request. Callers pair those arrays with `tool_choice:'required'`, so "you must call the video
+ * generator" silently degrades to "you must call tool-search", and a caller scanning tool-call events
+ * for the generator's name never sees it.
+ *
+ * An explicit array is a closed set the caller already narrowed: there is nothing left to discover, so
+ * defer has no work to do and its formatting is pure downside. Sending those tools normally is exactly
+ * today's (defer-off) behavior for that request.
+ *
+ * Note this is NOT the same as treating the array as `hotToolNames`: hot tools are non-deferred, but
+ * `formatServerToolsWithDefer` prepends the tool-search tool unconditionally, so a `required` turn
+ * could still satisfy the constraint by calling it. Skipping the formatting is what actually fixes it.
+ *
+ * The catalog path (a filter function, or no filter) is untouched — full tool-search + hot + deferred.
+ */
+declare function deferFormattingConfig(serverToolsFilter: readonly string[] | ServerToolsFilterFunction | undefined, config: DeferLoadingConfig | undefined): DeferLoadingConfig | undefined;
 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
@@ -509,7 +565,7 @@ interface CreateServerToolsFilterOptions {
  * });
  * ```
  */
-declare function createServerToolsFilter(options?: CreateServerToolsFilterOptions): (embeddings: number[] | number[][], tools: ServerTool[]) => string[];
+declare function createServerToolsFilter(options?: CreateServerToolsFilterOptions): ServerToolsFilterFunction;
 /**
  * Default exclusions baked into `defaultServerToolsFilter`.
  *
@@ -575,13 +631,21 @@ declare const SERVER_TOOL_DEPENDENCY_SETS: ToolSet[];
  * 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[];
+declare const defaultServerToolsFilter: ServerToolsFilterFunction;
 /**
  * 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[];
+type ServerToolsFilterFunction = ((embeddings: number[] | number[][], tools: ServerTool[]) => string[]) & {
+    /**
+     * The unconditional exclusions this filter applies, exposed by
+     * {@link createServerToolsFilter} so defer-loading can honour them without the caller
+     * repeating the list — see {@link resolveDeferredServerTools}. Absent on a hand-written
+     * filter, or on one wrapped in a plain closure.
+     */
+    readonly excludeTools?: readonly string[];
+};
 /**
  * Options for `selectServerToolsForPrompt`.
  */
@@ -609,9 +673,10 @@ interface SelectServerToolsForPromptOptions {
      */
     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.
+     * Phase 3 defer-loading. When `enabled`, this helper skips SEMANTIC filtering to mirror
+     * useChatStorage's responses send path, which hands the catalog to mergeTools + tool-search. The
+     * caller's unconditional constraints still apply — an explicit static array, and exclusions (see
+     * {@link resolveDeferredServerTools}). Omit/disabled → today's filtered selection.
      */
     deferLoading?: DeferLoadingConfig;
 }
@@ -1377,4 +1442,4 @@ declare function resolveServerTools(descriptor: ToolIntentDescriptor, catalog: S
  */
 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 };
+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, deferFormattingConfig, deriveActiveToolSets, expandToolSetsAdditive, filterAssembledClientTools, filterServerTools, findMatchingTools, getCachedServerTools, getCatalogEntry, getMaxToolRounds, getServerTools, getThinkingMode, getToolDescription, getToolName, getToolsChecksum, isCoercingIntent, localStorageToolsCache, mergeActiveToolSets, mergeTools, resolveCouncilPlan, resolveCouncilServerTools, resolveDeferredServerTools, resolvePlan, resolveServerTools, resolveToolChoice, scoreTools, selectCouncilClientTools, selectServerSideTools, selectServerToolsForPrompt, shouldRefreshTools, stripCoercedMemoryWrite, toolSetSystemPrompts };