Function applyCacheControlToTools

src/common/utils/ai/cacheStrategy.ts:153–220

(
  tools: T,
  modelString: string,
  cacheTtl?: AnthropicCacheTtl | null
)

 * attaching providerOptions.
 */
export function applyCacheControlToTools<T extends Record<string, Tool>>(
  tools: T,
  modelString: string,
  cacheTtl?: AnthropicCacheTtl | null
): T {
  // Only apply cache control for Anthropic models
  if (!supportsAnthropicCache(modelString) || !tools || Object.keys(tools).length === 0) {
    return tools;
  }

  // Get the last tool key (tools are ordered, last one gets cached)
  const toolKeys = Object.keys(tools);
  const lastToolKey = toolKeys[toolKeys.length - 1];

  const cacheOpts = cacheTtl ? anthropicCacheControl(cacheTtl) : ANTHROPIC_CACHE_CONTROL;

  // Clone tools and add cache control ONLY to the last tool
  // Anthropic caches everything up to the cache breakpoint, so marking
  // only the last tool will cache all tools
  const cachedTools = {} as unknown as T;
  for (const [key, existingTool] of Object.entries(tools)) {
    if (key === lastToolKey) {
      if (isProviderNativeTool(existingTool)) {
        // Provider-native tools (e.g. Anthropic/OpenAI web search) cannot be recreated with
        // createTool(). Clone while preserving descriptors/getters and attach providerOptions.
        const cachedProviderTool = cloneToolPreservingDescriptors(
          existingTool
        ) as ProviderNativeTool;
        cachedProviderTool.providerOptions = cacheOpts;
        cachedTools[key as keyof T] = cachedProviderTool as unknown as T[keyof T];
      } else if (existingTool.execute == null) {
        // Some MCP/dynamic tools are valid without execute handlers (provider-/client-executed).
        // Keep their runtime shape and attach cache control without forcing recreation.
        const cachedDynamicTool = cloneToolPreservingDescriptors(existingTool);
        cachedDynamicTool.providerOptions = cacheOpts;
        cachedTools[key as keyof T] = cachedDynamicTool as unknown as T[keyof T];
      } else {
        assert(
          existingTool.execute != null,
          `Tool "${key}" must define execute before cache control is applied`
        );

        // Function tools with execute handlers: re-create with providerOptions (SDK requires this at creation time)
        const cachedTool = createTool({
          description: existingTool.description,
          inputSchema: existingTool.inputSchema,
          execute: existingTool.execute,
          providerOptions: cacheOpts,
        });
        // createTool() returns a fresh object that drops any extra own symbol markers attached
        // to the original (e.g. the built-in task-tool marker that lets sibling explore tasks run
        // in parallel). Copy them over so downstream wrappers still recognize the recreated tool.
        for (const marker of Object.getOwnPropertySymbols(existingTool)) {
          const descriptor = Object.getOwnPropertyDescriptor(existingTool, marker);
          if (descriptor) {
            Object.defineProperty(cachedTool, marker, descriptor);
          }
        }