@juspay/neurolink 9.82.0 → 9.84.0

package/dist/neurolink.js

@@ -90,6 +90,8 @@ import { runWorkflow } from "./workflow/core/workflowRunner.js";
 import { ModelPool, classifyProviderError } from "./routing/index.js";
 import { ClassifierRouter } from "./routing/classifierRouter.js";
 import { looksLikeModelAccessDenied as sharedLooksLikeModelAccessDenied, isNonRetryableProviderError as sharedIsNonRetryableProviderError, } from "./utils/providerErrorClassification.js";
+import { detectAndRedactPII } from "./utils/piiDetector.js";
+import { validateResponse } from "./utils/responseValidator.js";
 /**
  * NL-002: Classify MCP error messages into categories for AI disambiguation.
  * Returns a human-readable error category based on error message content.
@@ -3063,6 +3065,41 @@ Current user's request: ${currentInput}`;
         if (!hasSttAudio && !isMediaModalityMode) {
             this.assertInputText(options.input?.text, "Input text is required and must be a non-empty string");
         }
+        // Input validation (trimWhitespace, minLength, maxLength, requireContent).
+        // Guard on a string input.text — release's media-only / STT flows may leave
+        // it empty/undefined, and those never carry inputValidation anyway.
+        if (options.inputValidation && typeof options.input.text === "string") {
+            const iv = options.inputValidation;
+            if (iv.trimWhitespace) {
+                options.input.text = options.input.text.trim();
+            }
+            if (iv.requireContent && !options.input.text.trim()) {
+                throw new Error("Input content is required but was empty or whitespace");
+            }
+            if (iv.minLength && options.input.text.length < iv.minLength) {
+                throw new Error(`Input text is too short (${options.input.text.length} < ${iv.minLength})`);
+            }
+            if (iv.maxLength && options.input.text.length > iv.maxLength) {
+                throw new Error(`Input text is too long (${options.input.text.length} > ${iv.maxLength})`);
+            }
+        }
+        // PII detection and redaction
+        if (options.piiDetection?.enabled &&
+            typeof options.input.text === "string") {
+            const piiResult = await detectAndRedactPII(options.input.text, {
+                enabled: true,
+                action: options.piiDetection.action ?? "warn",
+                detectTypes: options.piiDetection.detectTypes,
+                customPatterns: options.piiDetection.customPatterns,
+                allowList: options.piiDetection.allowList,
+                redactionText: options.piiDetection.redactionText,
+            });
+            if (piiResult.action === "abort") {
+                throw new Error(piiResult.feedback ?? "Request blocked: PII detected in input");
+            }
+            // Replace input text with redacted version
+            options.input.text = piiResult.text;
+        }
         this.enforceSessionBudget(options.maxBudgetUsd);
         this.applyGenerateLifecycleMiddleware(options);
         await this.applyAuthenticatedRequestContext(options);
@@ -3702,6 +3739,29 @@ Current user's request: ${currentInput}`;
             reasoningTokens: textResult.reasoningTokens,
             ...(textResult.retries && { retries: textResult.retries }),
         };
+        // Response validation (if configured)
+        if (options.responseValidation) {
+            const validationResult = validateResponse(generateResult.content ?? "", {
+                minLength: options.responseValidation.minLength,
+                maxLength: options.responseValidation.maxLength,
+                requiredPhrases: options.responseValidation.requiredPhrases,
+                forbiddenPhrases: options.responseValidation.forbiddenPhrases,
+                jsonSchema: options.responseValidation.jsonSchema,
+                customValidator: options.responseValidation.customValidator,
+                truncationAction: options.responseValidation.truncationAction,
+                truncationSuffix: options.responseValidation.truncationSuffix,
+                retryOnFailure: options.responseValidation.retryOnFailure,
+                maxRetries: options.responseValidation.maxRetries,
+            });
+            if (validationResult.action === "abort") {
+                throw new Error(validationResult.feedback ??
+                    `Response validation failed: ${validationResult.issues.map((i) => i.message).join("; ")}`);
+            }
+            // Apply validated/truncated text
+            if (validationResult.text !== generateResult.content) {
+                generateResult.content = validationResult.text;
+            }
+        }
         if (generateResult.analytics?.cost && generateResult.analytics.cost > 0) {
             this._sessionCostUsd += generateResult.analytics.cost;
         }
@@ -6452,6 +6512,37 @@ Current user's request: ${currentInput}`;
     }
     async validateStreamRequestOptions(options, startTime) {
         await this.validateStreamInput(options);
+        // Input validation for stream
+        if (options.inputValidation && options.input?.text) {
+            const iv = options.inputValidation;
+            if (iv.trimWhitespace) {
+                options.input.text = options.input.text.trim();
+            }
+            if (iv.requireContent && !options.input.text.trim()) {
+                throw new Error("Input content is required but was empty or whitespace");
+            }
+            if (iv.minLength && options.input.text.length < iv.minLength) {
+                throw new Error(`Input text is too short (${options.input.text.length} < ${iv.minLength})`);
+            }
+            if (iv.maxLength && options.input.text.length > iv.maxLength) {
+                throw new Error(`Input text is too long (${options.input.text.length} > ${iv.maxLength})`);
+            }
+        }
+        // PII detection and redaction for stream
+        if (options.piiDetection?.enabled && options.input?.text) {
+            const piiResult = await detectAndRedactPII(options.input.text, {
+                enabled: true,
+                action: options.piiDetection.action ?? "warn",
+                detectTypes: options.piiDetection.detectTypes,
+                customPatterns: options.piiDetection.customPatterns,
+                allowList: options.piiDetection.allowList,
+                redactionText: options.piiDetection.redactionText,
+            });
+            if (piiResult.action === "abort") {
+                throw new Error(piiResult.feedback ?? "Request blocked: PII detected in input");
+            }
+            options.input.text = piiResult.text;
+        }
         this.enforceSessionBudget(options.maxBudgetUsd);
         await this.applyAuthenticatedRequestContext(options);
         this.emitStreamStartEvents(options, startTime);
@@ -11216,6 +11307,191 @@ Current user's request: ${currentInput}`;
         const { getPreset } = await withTimeout(import("./evaluation/pipeline/index.js"), 10000, ErrorFactory.evaluationTimeout("evaluation module load", 10000));
         return getPreset(presetName);
     }
+    // ============================================================================
+    // MULTI-AGENT ORCHESTRATION METHODS
+    // ============================================================================
+    /**
+     * Create an Agent instance for multi-agent orchestration.
+     *
+     * Agents are specialized AI entities with defined instructions, tools, and behavior.
+     * They can be composed into networks for complex task orchestration.
+     *
+     * @param definition - Agent definition specifying behavior and capabilities
+     * @returns A new Agent instance
+     *
+     * @example
+     * ```typescript
+     * const researcher = neurolink.createAgent({
+     *   id: 'researcher',
+     *   name: 'Research Agent',
+     *   description: 'Searches and analyzes information from various sources',
+     *   instructions: 'You are a research assistant. Search thoroughly and cite sources.',
+     *   tools: ['websearchGrounding', 'readFile'],
+     *   model: 'gpt-4o'
+     * });
+     *
+     * const result = await researcher.execute('Find recent AI breakthroughs');
+     * ```
+     *
+     * @see {@link AgentDefinition} for definition options
+     * @see {@link Agent} for agent methods
+     * @since 8.38.0
+     */
+    async createAgent(definition) {
+        const { Agent } = await import("./agent/agent.js");
+        logger.debug("[NeuroLink] Creating agent", {
+            id: definition.id,
+            name: definition.name,
+            tools: definition.tools?.length || 0,
+        });
+        return new Agent(definition, this);
+    }
+    /**
+     * Create an AgentNetwork for multi-agent orchestration.
+     *
+     * Networks coordinate multiple agents, workflows, and tools with intelligent
+     * LLM-powered routing. The router agent analyzes tasks and delegates to
+     * the most appropriate primitive.
+     *
+     * @param config - Network configuration with agents, workflows, and routing settings
+     * @returns A new AgentNetwork instance
+     *
+     * @example
+     * ```typescript
+     * const network = neurolink.createNetwork({
+     *   name: 'Content Team',
+     *   description: 'Collaborative content creation pipeline',
+     *   agents: [
+     *     {
+     *       id: 'researcher',
+     *       name: 'Researcher',
+     *       description: 'Finds and verifies information',
+     *       instructions: 'Research topics thoroughly...',
+     *     },
+     *     {
+     *       id: 'writer',
+     *       name: 'Writer',
+     *       description: 'Creates engaging content',
+     *       instructions: 'Write clear, engaging content...',
+     *     },
+     *     {
+     *       id: 'editor',
+     *       name: 'Editor',
+     *       description: 'Reviews and improves content',
+     *       instructions: 'Review for clarity and accuracy...',
+     *     }
+     *   ],
+     *   router: {
+     *     model: 'gpt-4o',
+     *     confidenceThreshold: 0.7
+     *   }
+     * });
+     *
+     * const result = await network.execute({
+     *   message: 'Write an article about quantum computing'
+     * });
+     * ```
+     *
+     * @see {@link AgentNetworkConfig} for configuration options
+     * @see {@link AgentNetwork} for network methods
+     * @since 8.38.0
+     */
+    async createNetwork(config) {
+        const { AgentNetwork } = await import("./agent/agentNetwork.js");
+        logger.debug("[NeuroLink] Creating agent network", {
+            name: config.name,
+            agentCount: config.agents.length,
+            workflowCount: config.workflows?.length || 0,
+            toolCount: config.tools?.length || 0,
+        });
+        return new AgentNetwork(config, this);
+    }
+    /**
+     * Execute an agent network with the given input.
+     *
+     * @param network - The agent network to execute
+     * @param input - Execution input (message and context)
+     * @param options - Optional execution options
+     * @returns Network execution result with content, trace, and usage
+     *
+     * @see {@link NetworkExecutionInput} for input options
+     * @see {@link NetworkExecutionResult} for result structure
+     * @since 8.38.0
+     */
+    async executeNetwork(network, input, options) {
+        logger.debug("[NeuroLink] Executing agent network", {
+            networkId: network.id,
+            networkName: network.name,
+            hasContext: !!input.context,
+        });
+        return network.execute(input, options);
+    }
+    /**
+     * Stream agent network execution with real-time events.
+     *
+     * @param network - The agent network to stream
+     * @param input - Execution input (message and context)
+     * @param options - Optional execution options
+     * @returns Async iterable of network stream chunks
+     *
+     * @see {@link NetworkStreamChunk} for chunk types
+     * @since 8.38.0
+     */
+    async *streamNetwork(network, input, options) {
+        logger.debug("[NeuroLink] Streaming agent network", {
+            networkId: network.id,
+            networkName: network.name,
+            hasContext: !!input.context,
+        });
+        yield* network.stream(input, options);
+    }
+    // ============================================================================
+    // ADVANCED ORCHESTRATION METHODS
+    // ============================================================================
+    /**
+     * Create a NetworkOrchestrator for managing multiple agent networks.
+     *
+     * @param config - Orchestrator configuration options
+     * @returns A new NetworkOrchestrator instance
+     * @since 8.38.0
+     */
+    async createOrchestrator(config) {
+        const { NetworkOrchestrator } = await import("./agent/orchestration/index.js");
+        logger.debug("[NeuroLink] Creating network orchestrator", {
+            maxConcurrentExecutions: config?.maxConcurrentExecutions,
+            defaultMode: config?.defaultMode,
+        });
+        return new NetworkOrchestrator(this, config);
+    }
+    /**
+     * Create an AgentCoordinator for managing agent coordination strategies.
+     *
+     * @param config - Coordinator configuration options
+     * @returns A new AgentCoordinator instance
+     * @since 8.38.0
+     */
+    async createCoordinator(config) {
+        const { AgentCoordinator } = await import("./agent/coordination/index.js");
+        logger.debug("[NeuroLink] Creating agent coordinator", {
+            strategy: config?.strategy,
+            maxConcurrency: config?.maxConcurrency,
+        });
+        return new AgentCoordinator(config);
+    }
+    /**
+     * Create a MessageBus for inter-agent communication.
+     *
+     * @param config - Message bus configuration options
+     * @returns A new MessageBus instance
+     * @since 8.38.0
+     */
+    async createMessageBus(config) {
+        const { MessageBus } = await import("./agent/communication/index.js");
+        logger.debug("[NeuroLink] Creating message bus", {
+            maxHistorySize: config?.maxHistorySize,
+        });
+        return new MessageBus(config);
+    }
     /**
      * Dispose of all resources and cleanup connections
      * Call this method when done using the NeuroLink instance to prevent resource leaks

package/dist/processors/config/index.d.ts

@@ -26,7 +26,7 @@
  * const maxSize = SIZE_LIMITS.IMAGE_MAX_MB; // 10
  * ```
  */
-export { ARCHIVE_MIME_TYPES, AUDIO_MIME_TYPES, DATA_MIME_TYPES, DOCUMENT_MIME_TYPES, EXTENSION_MIME_MAP, getMimeTypeForExtension, IMAGE_MIME_TYPES, MIME_TYPES, SOURCE_CODE_MIME_TYPES, TEXT_MIME_TYPES, VIDEO_MIME_TYPES, } from "./mimeTypes.js";
-export { ADA_EXTENSIONS, AI_VISION_EXTENSIONS, ARCHIVE_EXTENSIONS, ASSEMBLY_EXTENSIONS, AUDIO_EXTENSIONS, C_EXTENSIONS, CLOJURE_EXTENSIONS, COBOL_EXTENSIONS, CONFIG_EXTENSIONS, CPP_EXTENSIONS, CRYSTAL_EXTENSIONS, CSHARP_EXTENSIONS, CSS_EXTENSIONS, CSV_EXTENSIONS, D_EXTENSIONS, DART_EXTENSIONS, DATA_EXTENSIONS, DATABASE_EXTENSIONS, DESIGN_EXTENSIONS, DOCKERFILE_EXTENSIONS, DOCUMENT_EXTENSIONS, EJS_EXTENSIONS, ELIXIR_EXTENSIONS, ERLANG_EXTENSIONS, EXCEL_EXTENSIONS, EXECUTABLE_EXTENSIONS, FILE_EXTENSIONS, FORTRAN_EXTENSIONS, FSHARP_EXTENSIONS, GO_EXTENSIONS, GROOVY_EXTENSIONS, HANDLEBARS_EXTENSIONS, HASKELL_EXTENSIONS, HTML_EXTENSIONS, IMAGE_EXTENSIONS, JAVA_EXTENSIONS, JAVASCRIPT_EXTENSIONS, JSON_EXTENSIONS, JULIA_EXTENSIONS, KOTLIN_EXTENSIONS, LESS_EXTENSIONS, LISP_EXTENSIONS, LUA_EXTENSIONS, MAKEFILE_EXTENSIONS, MARKDOWN_EXTENSIONS, NIM_EXTENSIONS, OBJECTIVE_C_EXTENSIONS, OCAML_EXTENSIONS, OPENDOCUMENT_EXTENSIONS, PASCAL_EXTENSIONS, PDF_EXTENSIONS, PERL_EXTENSIONS, PHP_EXTENSIONS, POWERPOINT_EXTENSIONS, POWERSHELL_EXTENSIONS, PUG_EXTENSIONS, PYTHON_EXTENSIONS, R_EXTENSIONS, RTF_EXTENSIONS, RUBY_EXTENSIONS, RUST_EXTENSIONS, SCALA_EXTENSIONS, SCHEME_EXTENSIONS, SCSS_EXTENSIONS, SHELL_EXTENSIONS, SOURCE_CODE_EXTENSIONS, SQL_EXTENSIONS, STYLUS_EXTENSIONS, SVELTE_EXTENSIONS, SWIFT_EXTENSIONS, TEXT_EXTENSIONS, TYPESCRIPT_EXTENSIONS, V_EXTENSIONS, VIDEO_EXTENSIONS, VUE_EXTENSIONS, WORD_EXTENSIONS, XML_EXTENSIONS, YAML_EXTENSIONS, ZIG_EXTENSIONS, } from "./fileTypes.js";
+export { ARCHIVE_MIME_TYPES, AUDIO_MIME_TYPES, DATA_MIME_TYPES, DOCUMENT_MIME_TYPES, EXTENSION_MIME_MAP, getMimeTypeForExtension, IMAGE_MIME_TYPES, MIME_TYPES, SOURCE_CODE_MIME_TYPES, TEXT_MIME_TYPES, VIDEO_MIME_TYPES, } from "./mimeConstants.js";
+export { ADA_EXTENSIONS, AI_VISION_EXTENSIONS, ARCHIVE_EXTENSIONS, ASSEMBLY_EXTENSIONS, AUDIO_EXTENSIONS, C_EXTENSIONS, CLOJURE_EXTENSIONS, COBOL_EXTENSIONS, CONFIG_EXTENSIONS, CPP_EXTENSIONS, CRYSTAL_EXTENSIONS, CSHARP_EXTENSIONS, CSS_EXTENSIONS, CSV_EXTENSIONS, D_EXTENSIONS, DART_EXTENSIONS, DATA_EXTENSIONS, DATABASE_EXTENSIONS, DESIGN_EXTENSIONS, DOCKERFILE_EXTENSIONS, DOCUMENT_EXTENSIONS, EJS_EXTENSIONS, ELIXIR_EXTENSIONS, ERLANG_EXTENSIONS, EXCEL_EXTENSIONS, EXECUTABLE_EXTENSIONS, FILE_EXTENSIONS, FORTRAN_EXTENSIONS, FSHARP_EXTENSIONS, GO_EXTENSIONS, GROOVY_EXTENSIONS, HANDLEBARS_EXTENSIONS, HASKELL_EXTENSIONS, HTML_EXTENSIONS, IMAGE_EXTENSIONS, JAVA_EXTENSIONS, JAVASCRIPT_EXTENSIONS, JSON_EXTENSIONS, JULIA_EXTENSIONS, KOTLIN_EXTENSIONS, LESS_EXTENSIONS, LISP_EXTENSIONS, LUA_EXTENSIONS, MAKEFILE_EXTENSIONS, MARKDOWN_EXTENSIONS, NIM_EXTENSIONS, OBJECTIVE_C_EXTENSIONS, OCAML_EXTENSIONS, OPENDOCUMENT_EXTENSIONS, PASCAL_EXTENSIONS, PDF_EXTENSIONS, PERL_EXTENSIONS, PHP_EXTENSIONS, POWERPOINT_EXTENSIONS, POWERSHELL_EXTENSIONS, PUG_EXTENSIONS, PYTHON_EXTENSIONS, R_EXTENSIONS, RTF_EXTENSIONS, RUBY_EXTENSIONS, RUST_EXTENSIONS, SCALA_EXTENSIONS, SCHEME_EXTENSIONS, SCSS_EXTENSIONS, SHELL_EXTENSIONS, SOURCE_CODE_EXTENSIONS, SQL_EXTENSIONS, STYLUS_EXTENSIONS, SVELTE_EXTENSIONS, SWIFT_EXTENSIONS, TEXT_EXTENSIONS, TYPESCRIPT_EXTENSIONS, V_EXTENSIONS, VIDEO_EXTENSIONS, VUE_EXTENSIONS, WORD_EXTENSIONS, XML_EXTENSIONS, YAML_EXTENSIONS, ZIG_EXTENSIONS, } from "./fileExtensions.js";
 export { detectLanguageFromFilename, EXACT_FILENAME_MAP, getLanguageIdentifier, getSupportedExtensions, getSupportedFilenames, isSourceCodeFile, LANGUAGE_MAP, } from "./languageMap.js";
 export { ARCHIVE_LIMITS, bytesToMB, formatBytes, getSizeLimitForType, isWithinSizeLimit, mbToBytes, PROCESSING_LIMITS, SIZE_LIMITS, SIZE_LIMITS_BYTES, SIZE_LIMITS_MB, validateFileSize, YAML_LIMITS, } from "./sizeLimits.js";

package/dist/processors/config/index.js

@@ -36,7 +36,7 @@ EXTENSION_MIME_MAP, getMimeTypeForExtension,
 IMAGE_MIME_TYPES, 
 // Types
 // Combined MIME types
-MIME_TYPES, SOURCE_CODE_MIME_TYPES, TEXT_MIME_TYPES, VIDEO_MIME_TYPES, } from "./mimeTypes.js";
+MIME_TYPES, SOURCE_CODE_MIME_TYPES, TEXT_MIME_TYPES, VIDEO_MIME_TYPES, } from "./mimeConstants.js";
 // =============================================================================
 // FILE EXTENSIONS
 // =============================================================================
@@ -66,7 +66,7 @@ JSON_EXTENSIONS, JULIA_EXTENSIONS, KOTLIN_EXTENSIONS, LESS_EXTENSIONS, LISP_EXTE
 // Text extensions
 TEXT_EXTENSIONS, TYPESCRIPT_EXTENSIONS, V_EXTENSIONS, 
 // Multimedia extensions
-VIDEO_EXTENSIONS, VUE_EXTENSIONS, WORD_EXTENSIONS, XML_EXTENSIONS, YAML_EXTENSIONS, ZIG_EXTENSIONS, } from "./fileTypes.js";
+VIDEO_EXTENSIONS, VUE_EXTENSIONS, WORD_EXTENSIONS, XML_EXTENSIONS, YAML_EXTENSIONS, ZIG_EXTENSIONS, } from "./fileExtensions.js";
 // =============================================================================
 // LANGUAGE DETECTION
 // =============================================================================

package/dist/processors/index.js

@@ -122,3 +122,11 @@ export { getProcessorForFile, getSupportedFileTypes, isFileTypeSupported, proces
 // CLI HELPERS
 // =============================================================================
 export { detectMimeType, fileExists, getCliUsage, getFileExtension, getSupportedFileTypes as getCliSupportedFileTypes, listSupportedFileTypes, loadFileFromPath, processFileFromPath, } from "./cli/index.js";
+// =============================================================================
+// STANDALONE SAFETY UTILITIES (extracted from the former I/O processor system)
+// =============================================================================
+// PII detection, response validation, and tripwire evaluation are now
+// standalone utilities in src/lib/utils/ and wired directly into
+// generate() and stream() via native options (piiDetection, responseValidation,
+// inputValidation). See src/lib/utils/piiDetector.ts, responseValidator.ts,
+// and tripwireEvaluator.ts.

package/dist/providers/googleAiStudio.js

@@ -10,7 +10,7 @@ import { composeAbortSignals, createTimeoutController, TimeoutError, } from "../
 import { withTimeout } from "../utils/async/index.js";
 import { estimateTokens } from "../utils/tokenEstimation.js";
 import { transformToolExecutions } from "../utils/transformationUtils.js";
-import { buildGeminiResponseSchema, buildNativeConfig, buildNativeToolDeclarations, collectStreamChunks, collectStreamChunksIncremental, computeMaxSteps, createTextChannel, buildUserPartsWithMultimodal, executeNativeToolCalls, extractTextFromParts, extractThoughtSignature, handleMaxStepsTermination, prependConversationMessages, pushModelResponseToHistory, } from "./googleNativeGemini3.js";
+import { buildGeminiResponseSchema, buildNativeConfig, buildNativeToolDeclarations, collectStreamChunks, collectStreamChunksIncremental, computeMaxSteps, createTextChannel, buildUserPartsWithMultimodal, executeNativeToolCalls, extractTextFromParts, extractThoughtSignature, handleMaxStepsTermination, prependConversationMessages, pushModelResponseToHistory, DedupExecuteMap, } from "./googleNativeGemini3.js";
 import { createProxyFetch } from "../proxy/proxyFetch.js";
 // Google AI Live API types now imported from ../types/providerSpecific.js
 // Import proper types for multimodal message handling
@@ -521,7 +521,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 });
                 // Convert tools
                 let toolsConfig;
-                let executeMap = new Map();
+                let executeMap = new DedupExecuteMap();
                 let originalNameMap = new Map();
                 if (options.tools &&
                     Object.keys(options.tools).length > 0 &&
@@ -584,6 +584,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                     let lastStepText = "";
                     let totalInputTokens = 0;
                     let totalOutputTokens = 0;
+                    let totalCacheReadTokens = 0;
                     let step = 0;
                     let completedWithFinalAnswer = false;
                     const failedTools = new Map();
@@ -614,6 +615,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                                 const chunkResult = await collectStreamChunksIncremental(rawStream, channel);
                                 totalInputTokens += chunkResult.inputTokens;
                                 totalOutputTokens += chunkResult.outputTokens;
+                                totalCacheReadTokens += chunkResult.cacheReadTokens ?? 0;
                                 const stepText = extractTextFromParts(chunkResult.rawResponseParts);
                                 // If no function calls, this was the final step — channel
                                 // already received all text parts incrementally.
@@ -698,13 +700,23 @@ export class GoogleAIStudioProvider extends BaseProvider {
                         span.setAttribute(ATTR.GEN_AI_INPUT_TOKENS, totalInputTokens);
                         span.setAttribute(ATTR.GEN_AI_OUTPUT_TOKENS, totalOutputTokens);
                         span.setAttribute(ATTR.GEN_AI_FINISH_REASON, hitStepLimitWithoutFinalAnswer ? "max_steps" : "stop");
+                        // Gemini promptTokenCount is OVERLAPPING: it already includes
+                        // cachedContentTokenCount. Subtract once here so calculateCost
+                        // bills the cached portion at the cheaper cacheRead rate without
+                        // double-counting. Total billable tokens are conserved.
+                        const adjustedInputTokens = Math.max(0, totalInputTokens - totalCacheReadTokens);
                         analyticsResolve({
                             provider: this.providerName,
                             model: modelName,
                             tokenUsage: {
-                                input: totalInputTokens,
+                                input: adjustedInputTokens,
                                 output: totalOutputTokens,
-                                total: totalInputTokens + totalOutputTokens,
+                                total: adjustedInputTokens +
+                                    totalCacheReadTokens +
+                                    totalOutputTokens,
+                                ...(totalCacheReadTokens > 0
+                                    ? { cacheReadTokens: totalCacheReadTokens }
+                                    : {}),
                             },
                             requestDuration: responseTime,
                             timestamp: new Date().toISOString(),
@@ -796,7 +808,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 });
                 // Convert tools (a0269210: trust options.tools — already merged + filtered upstream)
                 let toolsConfig;
-                let executeMap = new Map();
+                let executeMap = new DedupExecuteMap();
                 let originalNameMap = new Map();
                 const shouldUseTools = !options.disableTools;
                 if (shouldUseTools) {
@@ -831,6 +843,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 let lastStepText = "";
                 let totalInputTokens = 0;
                 let totalOutputTokens = 0;
+                let totalCacheReadTokens = 0;
                 const allToolCalls = [];
                 const toolExecutions = [];
                 let step = 0;
@@ -856,6 +869,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                         const chunkResult = await collectStreamChunks(stream);
                         totalInputTokens += chunkResult.inputTokens;
                         totalOutputTokens += chunkResult.outputTokens;
+                        totalCacheReadTokens += chunkResult.cacheReadTokens ?? 0;
                         const stepText = extractTextFromParts(chunkResult.rawResponseParts);
                         // If no function calls, we're done
                         if (chunkResult.stepFunctionCalls.length === 0) {
@@ -927,14 +941,21 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 // analytics / evaluation / tracing stay attached. The native AI
                 // Studio generate path bypasses BaseProvider.generate(), so
                 // skipping enhanceResult would silently drop those features.
+                // Gemini promptTokenCount is OVERLAPPING (already includes
+                // cachedContentTokenCount). Subtract once so the cached portion is
+                // billed at the cheaper cacheRead rate without double-counting.
+                const adjustedInputTokens = Math.max(0, totalInputTokens - totalCacheReadTokens);
                 const baseResult = {
                     content: finalText,
                     provider: this.providerName,
                     model: modelName,
                     usage: {
-                        input: totalInputTokens,
+                        input: adjustedInputTokens,
                         output: totalOutputTokens,
-                        total: totalInputTokens + totalOutputTokens,
+                        total: adjustedInputTokens + totalCacheReadTokens + totalOutputTokens,
+                        ...(totalCacheReadTokens > 0
+                            ? { cacheReadTokens: totalCacheReadTokens }
+                            : {}),
                     },
                     responseTime,
                     toolsUsed: allToolCalls.map((tc) => tc.toolName),

package/dist/providers/googleNativeGemini3.d.ts

@@ -10,6 +10,24 @@
  */
 import type { GenerateStopReason, ThinkingConfig, ChatMessage, CollectedChunkResult, MinimalChatMessage, NativeFunctionCall, NativeFunctionResponse, NativeToolDeclarationsResult, NativeToolsConfig, TextChannel, VertexNativePart, GeminiMultimodalInput } from "../types/index.js";
 import type { Tool } from "../types/index.js";
+/**
+ * A per-turn tool execute map that deduplicates identical tool calls.
+ *
+ * Gemini occasionally re-emits a tool call with identical arguments across
+ * agentic steps even though the prior result is already in the conversation
+ * history (BZ-3327). Re-executing produces duplicate side effects and
+ * duplicate reports for the user, plus wasted tokens. This map caches the
+ * result of each {tool name + args} executed within the turn and returns it
+ * for any identical re-request instead of running the tool again.
+ *
+ * Providers build a fresh executeMap per request, so the cache scope is
+ * exactly one turn. Only `.get()` is overridden (the sole access path used by
+ * the native agentic loops), so iteration still yields the raw executors.
+ */
+export declare class DedupExecuteMap extends Map<string, Tool["execute"]> {
+    private readonly resultCache;
+    get(name: string): Tool["execute"] | undefined;
+}
 export declare function sanitizeForGoogleFunctionName(name: string): string;
 /**
  * Resolve a sanitized Gemini tool name to one that is both unique within

package/dist/providers/googleNativeGemini3.js

@@ -17,6 +17,52 @@ import { convertZodToJsonSchema, ensureNestedSchemaTypes, inlineJsonSchema, isZo
 import { createNativeThinkingConfig } from "../utils/thinkingConfig.js";
 import { jsonSchema as aiJsonSchema, tool as createAISDKTool, } from "../utils/tool.js";
 // ── Functions ──
+/** Stable, key-order-independent serialization of tool args for the dedup key. */
+function stableStringifyForDedup(value) {
+    return JSON.stringify(value, (_key, val) => val && typeof val === "object" && !Array.isArray(val)
+        ? Object.keys(val)
+            .sort()
+            .reduce((acc, key) => {
+            acc[key] = val[key];
+            return acc;
+        }, {})
+        : val);
+}
+/**
+ * A per-turn tool execute map that deduplicates identical tool calls.
+ *
+ * Gemini occasionally re-emits a tool call with identical arguments across
+ * agentic steps even though the prior result is already in the conversation
+ * history (BZ-3327). Re-executing produces duplicate side effects and
+ * duplicate reports for the user, plus wasted tokens. This map caches the
+ * result of each {tool name + args} executed within the turn and returns it
+ * for any identical re-request instead of running the tool again.
+ *
+ * Providers build a fresh executeMap per request, so the cache scope is
+ * exactly one turn. Only `.get()` is overridden (the sole access path used by
+ * the native agentic loops), so iteration still yields the raw executors.
+ */
+export class DedupExecuteMap extends Map {
+    resultCache = new Map();
+    get(name) {
+        const execute = super.get(name);
+        if (!execute) {
+            return execute;
+        }
+        const resultCache = this.resultCache;
+        const wrapped = async (args, options) => {
+            const key = `${name}::${stableStringifyForDedup(args)}`;
+            if (resultCache.has(key)) {
+                logger.warn(`[DedupExecuteMap] Tool "${name}" re-requested with identical arguments in the same turn — reusing the previous result instead of re-executing.`);
+                return resultCache.get(key);
+            }
+            const result = await execute(args, options);
+            resultCache.set(key, result);
+            return result;
+        };
+        return wrapped;
+    }
+}
 /**
  * Google's `function_declarations[].name` validator regex.
  *
@@ -323,7 +369,7 @@ export function normalizeToolsForJsonSchemaProvider(tools) {
  */
 export function buildNativeToolDeclarations(tools) {
     const functionDeclarations = [];
-    const executeMap = new Map();
+    const executeMap = new DedupExecuteMap();
     const skippedTools = [];
     const renamedTools = [];
     // Disambiguate distinct originals that collapse onto the same sanitized
@@ -514,6 +560,7 @@ export async function collectStreamChunks(stream) {
     const stepFunctionCalls = [];
     let inputTokens = 0;
     let outputTokens = 0;
+    let cacheReadTokens = 0;
     for await (const chunk of stream) {
         // Extract raw parts from candidates FIRST
         // This avoids using chunk.text which triggers SDK warning when
@@ -533,9 +580,18 @@ export async function collectStreamChunks(stream) {
         if (usage) {
             inputTokens = Math.max(inputTokens, usage.promptTokenCount || 0);
             outputTokens = Math.max(outputTokens, usage.candidatesTokenCount || 0);
+            // cachedContentTokenCount is OVERLAPPING (a subset already inside
+            // promptTokenCount). Surface it so the call site subtracts once.
+            cacheReadTokens = Math.max(cacheReadTokens, usage.cachedContentTokenCount || 0);
         }
     }
-    return { rawResponseParts, stepFunctionCalls, inputTokens, outputTokens };
+    return {
+        rawResponseParts,
+        stepFunctionCalls,
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+    };
 }
 /**
  * Create a push-based text channel that bridges a background producer
@@ -627,6 +683,7 @@ export async function collectStreamChunksIncremental(stream, channel) {
     const stepFunctionCalls = [];
     let inputTokens = 0;
     let outputTokens = 0;
+    let cacheReadTokens = 0;
     for await (const chunk of stream) {
         const chunkRecord = chunk;
         const candidates = chunkRecord.candidates;
@@ -648,9 +705,18 @@ export async function collectStreamChunksIncremental(stream, channel) {
         if (usage) {
             inputTokens = Math.max(inputTokens, usage.promptTokenCount || 0);
             outputTokens = Math.max(outputTokens, usage.candidatesTokenCount || 0);
+            // cachedContentTokenCount is OVERLAPPING (a subset already inside
+            // promptTokenCount). Surface it so the call site subtracts once.
+            cacheReadTokens = Math.max(cacheReadTokens, usage.cachedContentTokenCount || 0);
         }
     }
-    return { rawResponseParts, stepFunctionCalls, inputTokens, outputTokens };
+    return {
+        rawResponseParts,
+        stepFunctionCalls,
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+    };
 }
 /**
  * Extract the thoughtSignature token from raw response parts.