@juspay/neurolink 9.83.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 &&
@@ -808,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) {

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

package/dist/providers/googleVertex.js

@@ -24,7 +24,7 @@ import { convertZodToJsonSchema, inlineJsonSchema, ensureNestedSchemaTypes, } fr
 import { createNativeThinkingConfig } from "../utils/thinkingConfig.js";
 import { TimeoutError, raceWithAbort, withTimeout, } from "../utils/async/index.js";
 import { parseTimeout } from "../utils/timeout.js";
-import { appendStepText, buildAbortedTurnMessage, buildContextCapMessage, buildToolLoopCapMessage, buildTurnStalledMessage, buildTurnTimeoutMessage, buildWrapupNudgeText, createContextGuard, createTextChannel, createTurnClock, extractThoughtSignature, isAbortError, mapGeminiFinishReason, prependConversationMessages, resolveTurnStopReason, } from "./googleNativeGemini3.js";
+import { appendStepText, buildAbortedTurnMessage, buildContextCapMessage, buildToolLoopCapMessage, buildTurnStalledMessage, buildTurnTimeoutMessage, buildWrapupNudgeText, createContextGuard, createTextChannel, createTurnClock, extractThoughtSignature, isAbortError, mapGeminiFinishReason, prependConversationMessages, resolveTurnStopReason, DedupExecuteMap, } from "./googleNativeGemini3.js";
 import { getContextWindowSize } from "../constants/contextWindows.js";
 import { ATTR, LANGFUSE_ATTR, spanJsonAttribute, tracers, withClientSpan, withClientStreamSpan, withSpan, } from "../telemetry/index.js";
 import { SpanKind, SpanStatusCode, context as otelContext, trace as otelTrace, } from "@opentelemetry/api";
@@ -1138,7 +1138,7 @@ export class GoogleVertexProvider extends BaseProvider {
         });
         // Convert Vercel AI SDK tools to @google/genai FunctionDeclarations
         let tools;
-        const executeMap = new Map();
+        const executeMap = new DedupExecuteMap();
         if (options.tools &&
             Object.keys(options.tools).length > 0 &&
             !options.disableTools) {
@@ -2085,7 +2085,7 @@ export class GoogleVertexProvider extends BaseProvider {
         const combinedTools = !options.disableTools ? options.tools || {} : {};
         // Convert Vercel AI SDK tools to @google/genai FunctionDeclarations
         let tools;
-        const executeMap = new Map();
+        const executeMap = new DedupExecuteMap();
         if (Object.keys(combinedTools).length > 0) {
             const functionDeclarations = [];
             for (const [name, tool] of Object.entries(combinedTools)) {
@@ -3116,7 +3116,7 @@ export class GoogleVertexProvider extends BaseProvider {
             : userContentParts);
         // Convert tools to Anthropic format if present
         let tools;
-        const executeMap = new Map();
+        const executeMap = new DedupExecuteMap();
         if (options.tools &&
             Object.keys(options.tools).length > 0 &&
             !options.disableTools) {
@@ -4425,7 +4425,7 @@ export class GoogleVertexProvider extends BaseProvider {
             : userContentParts);
         // Convert tools to Anthropic format if present
         let tools;
-        const executeMap = new Map();
+        const executeMap = new DedupExecuteMap();
         const toolExecutions = [];
         // Defensive guard: Vertex generate() bypasses BaseProvider.generate(), so
         // disableTools must be checked here before native tool declarations are