@juspay/neurolink 9.64.0 → 9.65.0

package/dist/providers/googleNativeGemini3.js

@@ -17,6 +17,61 @@ import { logger } from "../utils/logger.js";
 import { convertZodToJsonSchema, ensureNestedSchemaTypes, inlineJsonSchema, isZodSchema, normalizeJsonSchemaObject, } from "../utils/schemaConversion.js";
 import { createNativeThinkingConfig } from "../utils/thinkingConfig.js";
 // ── Functions ──
+/**
+ * Google's `function_declarations[].name` validator regex.
+ *
+ * Empirically (and per the Vertex/AI Studio API error message), the server
+ * enforces `[A-Za-z_][A-Za-z0-9_.:-]{0,127}`. Tool names that don't match
+ * fail with HTTP 400 "Invalid function name", which surfaces as a misleading
+ * tool-calling failure for the whole request.
+ *
+ * MCP-imported or user-registered tools may legally contain characters
+ * outside this set (e.g. `/`, spaces, unicode), so we sanitize defensively
+ * before sending to Google. The sanitized name is also used as the
+ * `executeMap` key so the round-trip from Google's function-call response
+ * back to our executor still works.
+ */
+const GOOGLE_FN_NAME_REGEX = /^[A-Za-z_][A-Za-z0-9_.:-]{0,127}$/;
+const GOOGLE_FN_NAME_MAX_LENGTH = 128;
+export function sanitizeForGoogleFunctionName(name) {
+    if (GOOGLE_FN_NAME_REGEX.test(name)) {
+        return name;
+    }
+    let sanitized = name.replace(/[^A-Za-z0-9_.:-]/g, "_");
+    if (!/^[A-Za-z_]/.test(sanitized)) {
+        sanitized = `_${sanitized}`;
+    }
+    if (sanitized.length > GOOGLE_FN_NAME_MAX_LENGTH) {
+        sanitized = sanitized.slice(0, GOOGLE_FN_NAME_MAX_LENGTH);
+    }
+    return sanitized;
+}
+/**
+ * Resolve a sanitized Gemini tool name to one that is both unique within
+ * the current request and at most 128 characters. When the candidate
+ * collides with an already-used name we append `_2`, `_3`, … — but
+ * reserve room for the suffix by truncating the base first so the
+ * resolved name never exceeds Google's `function_declarations[].name`
+ * limit.
+ *
+ * @param base       The already-sanitized candidate name.
+ * @param isTaken    Predicate that returns true if `name` is already used.
+ */
+export function resolveUniqueGoogleFunctionName(base, isTaken) {
+    if (!isTaken(base)) {
+        return base;
+    }
+    let suffix = 2;
+    while (true) {
+        const suffixStr = `_${suffix}`;
+        const trimmedBase = base.slice(0, GOOGLE_FN_NAME_MAX_LENGTH - suffixStr.length);
+        const candidate = `${trimmedBase}${suffixStr}`;
+        if (!isTaken(candidate)) {
+            return candidate;
+        }
+        suffix++;
+    }
+}
 /**
  * Sanitize a JSON Schema for Gemini's proto-based API.
  *
@@ -102,6 +157,40 @@ export function sanitizeSchemaForGemini(schema) {
             result[branch] = sanitizeSchemaForGemini(result[branch]);
         }
     }
+    // JSON Schema Draft-4 `exclusiveMinimum: true` / `exclusiveMaximum: true`
+    // (boolean form) is rejected by Gemini's OpenAPI 3.0 validator, which
+    // expects a numeric bound. zod-to-json-schema's openApi3 target still
+    // emits the Draft-4 form for `z.number().positive()` etc. Translate to
+    // the numeric form when paired with `minimum`/`maximum`, or drop.
+    if (typeof result.exclusiveMinimum === "boolean") {
+        if (result.exclusiveMinimum === true &&
+            typeof result.minimum === "number") {
+            result.exclusiveMinimum = result.minimum;
+            delete result.minimum;
+        }
+        else {
+            delete result.exclusiveMinimum;
+        }
+    }
+    if (typeof result.exclusiveMaximum === "boolean") {
+        if (result.exclusiveMaximum === true &&
+            typeof result.maximum === "number") {
+            result.exclusiveMaximum = result.maximum;
+            delete result.maximum;
+        }
+        else {
+            delete result.exclusiveMaximum;
+        }
+    }
+    // Clamp `maximum`/`minimum` past int32 — Gemini's protobuf serializer
+    // treats `type: "integer"` as int32 and rejects bounds beyond ~2.1e9.
+    const INT32_MAX = 2147483647;
+    if (typeof result.maximum === "number" && result.maximum > INT32_MAX) {
+        delete result.maximum;
+    }
+    if (typeof result.minimum === "number" && result.minimum < -INT32_MAX) {
+        delete result.minimum;
+    }
     return result;
 }
 /**
@@ -117,8 +206,27 @@ export function sanitizeSchemaForGemini(schema) {
 export function sanitizeToolsForGemini(tools) {
     const sanitized = {};
     const dropped = [];
+    const renamed = [];
+    const originalNameMap = new Map();
     for (const [name, tool] of Object.entries(tools)) {
         try {
+            // Sanitize the tool name to fit Google's function_declarations regex.
+            // Without this, MCP-imported or user-registered tools whose names contain
+            // characters outside [A-Za-z_][A-Za-z0-9_.:-]{0,127} cause the entire
+            // request to 400 with "Invalid function name", surfacing as a misleading
+            // tool-calling failure. Distinct originals that collapse onto the same
+            // sanitized name (e.g. "my/tool" and "my-tool" → "my_tool") are
+            // disambiguated with a numeric suffix that preserves Google's 128-char
+            // ceiling.
+            const candidate = sanitizeForGoogleFunctionName(name);
+            const safeName = resolveUniqueGoogleFunctionName(candidate, (n) => n in sanitized);
+            // Always record the mapping so downstream code can translate every
+            // safeName back to the original — including the no-rename identity
+            // mapping, which simplifies the lookup path.
+            originalNameMap.set(safeName, name);
+            if (safeName !== name) {
+                renamed.push({ from: name, to: safeName });
+            }
             // Access the legacy `parameters` field that may exist on older AI SDK tools.
             // AI SDK v6 uses `inputSchema`, but v3/v4 tools and third-party wrappers use `parameters`.
             const legacyTool = tool;
@@ -134,8 +242,8 @@ export function sanitizeToolsForGemini(tools) {
                 // additionalProperties are removed. The resulting schema is Gemini-compatible
                 // but loses some type constraints from the original Zod schema.
                 const sanitizedSchema = sanitizeSchemaForGemini(inlined);
-                sanitized[name] = createAISDKTool({
-                    description: tool.description || `Tool: ${name}`,
+                sanitized[safeName] = createAISDKTool({
+                    description: tool.description || `Tool: ${safeName}`,
                     inputSchema: aiJsonSchema(sanitizedSchema),
                     execute: tool.execute,
                 });
@@ -147,14 +255,14 @@ export function sanitizeToolsForGemini(tools) {
                 const rawSchema = params
                     .jsonSchema;
                 const sanitizedSchema = sanitizeSchemaForGemini(inlineJsonSchema(rawSchema));
-                sanitized[name] = createAISDKTool({
-                    description: tool.description || `Tool: ${name}`,
+                sanitized[safeName] = createAISDKTool({
+                    description: tool.description || `Tool: ${safeName}`,
                     inputSchema: aiJsonSchema(sanitizedSchema),
                     execute: tool.execute,
                 });
             }
             else {
-                sanitized[name] = tool;
+                sanitized[safeName] = tool;
             }
         }
         catch (error) {
@@ -163,7 +271,12 @@ export function sanitizeToolsForGemini(tools) {
             dropped.push(name);
         }
     }
-    return { tools: sanitized, dropped };
+    if (renamed.length > 0) {
+        logger.warn(`[Gemini] ${renamed.length} tool name(s) sanitized for Google's function-name regex: ${renamed
+            .map((r) => `"${r.from}" -> "${r.to}"`)
+            .join(", ")}`);
+    }
+    return { tools: sanitized, dropped, originalNameMap };
 }
 export function normalizeToolsForJsonSchemaProvider(tools) {
     const normalizedTools = {};
@@ -212,11 +325,29 @@ export function buildNativeToolDeclarations(tools) {
     const functionDeclarations = [];
     const executeMap = new Map();
     const skippedTools = [];
+    const renamedTools = [];
+    // Disambiguate distinct originals that collapse onto the same sanitized
+    // name (e.g. "my/tool" and "my-tool" both → "my_tool") via
+    // resolveUniqueGoogleFunctionName, which appends `_N` while keeping the
+    // final string within Google's 128-char limit. Track all assigned names
+    // regardless of whether the tool has an `execute` function (tools without
+    // execute are still pushed to functionDeclarations). The originalNameMap
+    // lets the calling stream loop translate Google-returned function-call
+    // names back to the consumer-facing identifier so the sanitization is
+    // transport-only.
+    const usedNames = new Set();
+    const originalNameMap = new Map();
     for (const [name, tool] of Object.entries(tools)) {
         try {
+            const candidate = sanitizeForGoogleFunctionName(name);
+            const safeName = resolveUniqueGoogleFunctionName(candidate, (n) => usedNames.has(n));
+            originalNameMap.set(safeName, name);
+            if (safeName !== name) {
+                renamedTools.push({ from: name, to: safeName });
+            }
             const decl = {
-                name,
-                description: tool.description || `Tool: ${name}`,
+                name: safeName,
+                description: tool.description || `Tool: ${safeName}`,
             };
             // Access legacy `parameters` (AI SDK v3/v4) or current `inputSchema` (v6)
             const legacyTool = tool;
@@ -241,8 +372,9 @@ export function buildNativeToolDeclarations(tools) {
                 decl.parametersJsonSchema = sanitizeSchemaForGemini(inlineJsonSchema(rawSchema));
             }
             functionDeclarations.push(decl);
+            usedNames.add(safeName);
             if (tool.execute) {
-                executeMap.set(name, tool.execute);
+                executeMap.set(decl.name, tool.execute);
             }
         }
         catch (err) {
@@ -253,7 +385,16 @@ export function buildNativeToolDeclarations(tools) {
     if (skippedTools.length > 0) {
         logger.warn(`[buildNativeToolDeclarations] ${skippedTools.length} tool(s) skipped due to schema errors: ${skippedTools.join(", ")}`);
     }
-    return { toolsConfig: [{ functionDeclarations }], executeMap };
+    if (renamedTools.length > 0) {
+        logger.warn(`[buildNativeToolDeclarations] ${renamedTools.length} tool name(s) sanitized for Google's function-name regex: ${renamedTools
+            .map((r) => `"${r.from}" -> "${r.to}"`)
+            .join(", ")}`);
+    }
+    return {
+        toolsConfig: [{ functionDeclarations }],
+        executeMap,
+        originalNameMap,
+    };
 }
 /**
  * Build the native @google/genai config object shared by stream and generate.
@@ -493,27 +634,38 @@ export function extractTextFromParts(rawResponseParts) {
  * @param executeMap - Map of tool name to execute function
  * @param failedTools - Mutable map tracking per-tool failure counts
  * @param allToolCalls - Mutable array accumulating all tool call records
- * @param options - Optional settings for execution tracking and cancellation
+ * @param options - Optional settings for execution tracking and cancellation,
+ *                  plus an `originalNameMap` (Google-safe → consumer-supplied
+ *                  identifier) so the sanitization stays transport-only and
+ *                  consumers see the names they registered.
  * @returns Array of function responses for conversation history
  */
 export async function executeNativeToolCalls(logLabel, stepFunctionCalls, executeMap, failedTools, allToolCalls, options) {
     const functionResponses = [];
+    // Translate a Google-safe sanitized name back to the consumer-facing
+    // original name. Falls back to the safe name if the map is missing or
+    // doesn't contain the call (e.g. tool added mid-conversation).
+    const externalName = (safeName) => options?.originalNameMap?.get(safeName) ?? safeName;
     for (const call of stepFunctionCalls) {
-        allToolCalls.push({ toolName: call.name, args: call.args });
+        const exposedName = externalName(call.name);
+        allToolCalls.push({ toolName: exposedName, args: call.args });
         // Check if this tool has already exceeded retry limit
         const failedInfo = failedTools.get(call.name);
         if (failedInfo && failedInfo.count >= DEFAULT_TOOL_MAX_RETRIES) {
-            logger.warn(`${logLabel} Tool "${call.name}" has exceeded retry limit (${DEFAULT_TOOL_MAX_RETRIES}), skipping execution`);
+            logger.warn(`${logLabel} Tool "${exposedName}" has exceeded retry limit (${DEFAULT_TOOL_MAX_RETRIES}), skipping execution`);
             const errorOutput = {
-                error: `TOOL_PERMANENTLY_FAILED: The tool "${call.name}" has failed ${failedInfo.count} times and will not be retried. Last error: ${failedInfo.lastError}. Please proceed without using this tool or inform the user that this functionality is unavailable.`,
+                error: `TOOL_PERMANENTLY_FAILED: The tool "${exposedName}" has failed ${failedInfo.count} times and will not be retried. Last error: ${failedInfo.lastError}. Please proceed without using this tool or inform the user that this functionality is unavailable.`,
                 status: "permanently_failed",
                 do_not_retry: true,
             };
+            // Wire transport-side `name: call.name` (Google needs the sanitized
+            // form to match the function declaration) while exposing the
+            // consumer-facing name in toolExecutions metadata.
             functionResponses.push({
                 functionResponse: { name: call.name, response: errorOutput },
             });
             options?.toolExecutions?.push({
-                name: call.name,
+                name: exposedName,
                 input: call.args,
                 output: errorOutput,
             });
@@ -534,7 +686,7 @@ export async function executeNativeToolCalls(logLabel, stepFunctionCalls, execut
                     functionResponse: { name: call.name, response: { result } },
                 });
                 options?.toolExecutions?.push({
-                    name: call.name,
+                    name: exposedName,
                     input: call.args,
                     output: result,
                 });
@@ -549,12 +701,12 @@ export async function executeNativeToolCalls(logLabel, stepFunctionCalls, execut
                 currentFailInfo.count++;
                 currentFailInfo.lastError = errorMessage;
                 failedTools.set(call.name, currentFailInfo);
-                logger.warn(`${logLabel} Tool "${call.name}" failed (attempt ${currentFailInfo.count}/${DEFAULT_TOOL_MAX_RETRIES}): ${errorMessage}`);
+                logger.warn(`${logLabel} Tool "${exposedName}" failed (attempt ${currentFailInfo.count}/${DEFAULT_TOOL_MAX_RETRIES}): ${errorMessage}`);
                 // Determine if this is a permanent failure
                 const isPermanentFailure = currentFailInfo.count >= DEFAULT_TOOL_MAX_RETRIES;
                 const errorOutput = {
                     error: isPermanentFailure
-                        ? `TOOL_PERMANENTLY_FAILED: The tool "${call.name}" has failed ${currentFailInfo.count} times with error: ${errorMessage}. This tool will not be retried. Please proceed without using this tool or inform the user that this functionality is unavailable.`
+                        ? `TOOL_PERMANENTLY_FAILED: The tool "${exposedName}" has failed ${currentFailInfo.count} times with error: ${errorMessage}. This tool will not be retried. Please proceed without using this tool or inform the user that this functionality is unavailable.`
                         : `TOOL_EXECUTION_ERROR: ${errorMessage}. Retry attempt ${currentFailInfo.count}/${DEFAULT_TOOL_MAX_RETRIES}.`,
                     status: isPermanentFailure ? "permanently_failed" : "failed",
                     do_not_retry: isPermanentFailure,
@@ -565,7 +717,7 @@ export async function executeNativeToolCalls(logLabel, stepFunctionCalls, execut
                     functionResponse: { name: call.name, response: errorOutput },
                 });
                 options?.toolExecutions?.push({
-                    name: call.name,
+                    name: exposedName,
                     input: call.args,
                     output: errorOutput,
                 });
@@ -574,7 +726,7 @@ export async function executeNativeToolCalls(logLabel, stepFunctionCalls, execut
         else {
             // Tool not found is a permanent error
             const errorOutput = {
-                error: `TOOL_NOT_FOUND: The tool "${call.name}" does not exist. Do not attempt to call this tool again.`,
+                error: `TOOL_NOT_FOUND: The tool "${exposedName}" does not exist. Do not attempt to call this tool again.`,
                 status: "permanently_failed",
                 do_not_retry: true,
             };
@@ -582,7 +734,7 @@ export async function executeNativeToolCalls(logLabel, stepFunctionCalls, execut
                 functionResponse: { name: call.name, response: errorOutput },
             });
             options?.toolExecutions?.push({
-                name: call.name,
+                name: exposedName,
                 input: call.args,
                 output: errorOutput,
             });

package/dist/providers/googleVertex.js

@@ -18,7 +18,7 @@ import { convertZodToJsonSchema, inlineJsonSchema, ensureNestedSchemaTypes, } fr
 import { createNativeThinkingConfig } from "../utils/thinkingConfig.js";
 import { TimeoutError } from "../utils/async/index.js";
 import { prependConversationMessages } from "./googleNativeGemini3.js";
-import { ATTR, tracers, withClientSpan, withSpan } from "../telemetry/index.js";
+import { ATTR, tracers, withClientSpan, withClientStreamSpan, withSpan, } from "../telemetry/index.js";
 import { calculateCost } from "../utils/pricing.js";
 // Import proper types for multimodal message handling
 // Dynamic import helper for native Anthropic Vertex SDK
@@ -35,6 +35,110 @@ const hasAnthropicSupport = () => {
     // Actual availability is checked at runtime when creating the client
     return true;
 };
+/**
+ * Recursively strip JSON-schema fields that Vertex Gemini's function-call
+ * validator rejects with 400 INVALID_ARGUMENT. Vertex implements OpenAPI 3.0
+ * Schema strictly and rejects extension fields that the broader JSON Schema
+ * spec allows. The fields stripped here have no semantic meaning for the
+ * model, so removing them is safe for every caller.
+ *
+ * Fields removed:
+ * - `additionalProperties` — extension; Vertex rejects on any nested object.
+ * - `default` — Vertex rejects defaults on object/array-typed properties and
+ *   on properties that are also marked `required`. Safest to strip globally
+ *   because the model never inspects them.
+ * - `$schema`, `$id`, `$ref`, `definitions`, `$defs` — JSON-Schema-meta
+ *   fields that Vertex doesn't recognise.
+ * - `examples` — accepted by some Gemini variants but not 2.5-flash; strip
+ *   to avoid the model rejecting tool schemas under that path.
+ */
+function stripAdditionalPropertiesDeep(schema) {
+    if (!schema || typeof schema !== "object") {
+        return;
+    }
+    const FIELDS_TO_STRIP = [
+        "additionalProperties",
+        "default",
+        "$schema",
+        "$id",
+        "$ref",
+        "definitions",
+        "$defs",
+        "examples",
+    ];
+    for (const field of FIELDS_TO_STRIP) {
+        if (field in schema) {
+            delete schema[field];
+        }
+    }
+    // JSON Schema Draft-4 `exclusiveMinimum: true` / `exclusiveMaximum: true`
+    // (boolean form) is rejected by Vertex's OpenAPI 3.0 validator, which
+    // expects a numeric bound. zod-to-json-schema's openApi3 target still
+    // emits the Draft-4 form for `z.number().positive()` etc. Translate the
+    // boolean form into the numeric form when paired with `minimum` /
+    // `maximum`; otherwise drop it (the model doesn't validate, so the
+    // constraint is informational only).
+    if (typeof schema.exclusiveMinimum === "boolean") {
+        if (schema.exclusiveMinimum === true &&
+            typeof schema.minimum === "number") {
+            schema.exclusiveMinimum = schema.minimum;
+            delete schema.minimum;
+        }
+        else {
+            delete schema.exclusiveMinimum;
+        }
+    }
+    if (typeof schema.exclusiveMaximum === "boolean") {
+        if (schema.exclusiveMaximum === true &&
+            typeof schema.maximum === "number") {
+            schema.exclusiveMaximum = schema.maximum;
+            delete schema.maximum;
+        }
+        else {
+            delete schema.exclusiveMaximum;
+        }
+    }
+    // Strip `maximum` values that exceed int32 range — Vertex's protobuf
+    // serializer treats `type: "integer"` as int32 and rejects bounds beyond
+    // 2^31. zod's `.positive().int()` emits Number.MAX_SAFE_INTEGER as the
+    // upper bound (8.9e15), which trips this. The constraint is informational
+    // for the model anyway, so dropping it is safe.
+    const INT32_MAX = 2147483647;
+    if (typeof schema.maximum === "number" && schema.maximum > INT32_MAX) {
+        delete schema.maximum;
+    }
+    if (typeof schema.minimum === "number" && schema.minimum < -INT32_MAX) {
+        delete schema.minimum;
+    }
+    if (schema.properties && typeof schema.properties === "object") {
+        for (const child of Object.values(schema.properties)) {
+            if (child && typeof child === "object") {
+                stripAdditionalPropertiesDeep(child);
+            }
+        }
+    }
+    if (schema.items && typeof schema.items === "object") {
+        if (Array.isArray(schema.items)) {
+            for (const item of schema.items) {
+                if (item && typeof item === "object") {
+                    stripAdditionalPropertiesDeep(item);
+                }
+            }
+        }
+        else {
+            stripAdditionalPropertiesDeep(schema.items);
+        }
+    }
+    for (const key of ["allOf", "anyOf", "oneOf"]) {
+        if (Array.isArray(schema[key])) {
+            for (const branch of schema[key]) {
+                if (branch && typeof branch === "object") {
+                    stripAdditionalPropertiesDeep(branch);
+                }
+            }
+        }
+    }
+}
 // Configuration helpers - now using consolidated utility
 const getVertexProjectId = () => {
     return validateApiKey(createVertexProjectConfig());
@@ -604,7 +708,7 @@ export class GoogleVertexProvider extends BaseProvider {
         // the test:tracing observability harness sees the same span hierarchy
         // it sees for AI Studio. BaseProvider.stream does NOT emit this span
         // for any provider — each native provider has to add it itself.
-        return withClientSpan({
+        return withClientStreamSpan({
             name: "neurolink.provider.stream",
             tracer: tracers.provider,
             attributes: {
@@ -671,7 +775,7 @@ export class GoogleVertexProvider extends BaseProvider {
                 this.emitStreamEnd(modelName, streamStartTime, false, error);
                 throw error;
             }
-        });
+        }, (r) => r.stream, (r, wrapped) => ({ ...r, stream: wrapped }));
     }
     /**
      * Emit `stream:end` so the Pipeline B observability listener creates a
@@ -746,8 +850,11 @@ export class GoogleVertexProvider extends BaseProvider {
         });
         // Build contents from input with multimodal support
         const contents = [];
-        // Build user message parts - start with text
-        const userParts = [{ text: options.input.text }];
+        // Build user message parts - start with text.
+        // `options.input.text` is `string | undefined` in strict mode; the
+        // VertexNativePart `text` field requires `string`, so coerce to "" if
+        // unset (the multimodal-only path still appends other parts below).
+        const userParts = [{ text: options.input.text ?? "" }];
         // Add PDF files as inlineData parts if present
         // Cast input to access multimodal properties that may exist at runtime
         const multimodalInput = options.input;
@@ -886,6 +993,12 @@ export class GoogleVertexProvider extends BaseProvider {
                     // ensureNestedSchemaTypes recursively adds missing type fields to tool schemas
                     // Note: convertZodToJsonSchema now uses openApi3 target which produces nullable: true
                     const typedSchema = ensureNestedSchemaTypes(inlinedSchema);
+                    // Strip `additionalProperties` recursively — Vertex Gemini's
+                    // function-call validator rejects it on object schemas (returns
+                    // 400 INVALID_ARGUMENT) even though it's valid OpenAPI 3. The
+                    // field has no semantic meaning to the model, so dropping it
+                    // before send is safe for every caller.
+                    stripAdditionalPropertiesDeep(typedSchema);
                     decl.parametersJsonSchema = typedSchema;
                 }
                 functionDeclarations.push(decl);
@@ -1426,6 +1539,12 @@ export class GoogleVertexProvider extends BaseProvider {
                     // ensureNestedSchemaTypes recursively adds missing type fields to tool schemas
                     // Note: convertZodToJsonSchema now uses openApi3 target which produces nullable: true
                     const typedSchema = ensureNestedSchemaTypes(inlinedSchema);
+                    // Strip `additionalProperties` recursively — Vertex Gemini's
+                    // function-call validator rejects it on object schemas (returns
+                    // 400 INVALID_ARGUMENT) even though it's valid OpenAPI 3. The
+                    // field has no semantic meaning to the model, so dropping it
+                    // before send is safe for every caller.
+                    stripAdditionalPropertiesDeep(typedSchema);
                     decl.parametersJsonSchema = typedSchema;
                 }
                 functionDeclarations.push(decl);
@@ -2736,6 +2855,17 @@ export class GoogleVertexProvider extends BaseProvider {
                 this.emitGenerationEnd(modelName, videoResult, generateStartTime, true);
                 return videoResult;
             }
+            // TTS direct-synthesis mode: when caller passes `tts.enabled` without
+            // `tts.useAiResponse`, route to the shared `handleDirectTTSSynthesis`
+            // (synthesise the input text directly; no LLM call). BaseProvider's
+            // standard generate() does the same dispatch — we replicate it here
+            // because Vertex's override bypasses that path.
+            if (options.tts?.enabled && !options.tts?.useAiResponse) {
+                logger.info("[GoogleVertex] Routing TTS direct-synthesis to handleDirectTTSSynthesis", { model: modelName });
+                const ttsResult = await this.handleDirectTTSSynthesis(options, generateStartTime);
+                this.emitGenerationEnd(modelName, ttsResult, generateStartTime, true);
+                return ttsResult;
+            }
             // Check if this is an image generation model - route to executeImageGeneration without tools
             const isImageModel = IMAGE_GENERATION_MODELS.some((m) => modelName.toLowerCase().startsWith(m.toLowerCase()));
             if (isImageModel) {
@@ -2796,23 +2926,41 @@ export class GoogleVertexProvider extends BaseProvider {
                 "";
             try {
                 let result;
-                // Route Claude models to native Anthropic SDK
-                if (isAnthropicModel(modelName)) {
-                    logger.info("[GoogleVertex] Routing Claude generate to native @anthropic-ai/vertex-sdk", {
-                        model: modelName,
-                        totalToolCount: Object.keys(mergedOptions.tools).length,
-                    });
-                    result = await this.executeNativeAnthropicGenerate(mergedOptions);
-                }
-                else {
-                    // ALL Gemini models use native @google/genai SDK
+                // Wrap the actual native generate call in `neurolink.executeGeneration`
+                // so the observability span chain (tested by
+                // "Tracing: Generate Span Chain") sees a third inner span on the
+                // native @google/genai / @anthropic-ai/vertex-sdk path — Pipeline A
+                // gets this for free from GenerationHandler.executeGeneration.
+                result = await withSpan({
+                    name: "neurolink.executeGeneration",
+                    tracer: tracers.provider,
+                    attributes: {
+                        [ATTR.GEN_AI_SYSTEM]: this.providerName,
+                        [ATTR.GEN_AI_MODEL]: modelName,
+                        "neurolink.path": isAnthropicModel(modelName)
+                            ? "native.anthropic"
+                            : "native.google-genai",
+                    },
+                }, async () => {
+                    if (isAnthropicModel(modelName)) {
+                        logger.info("[GoogleVertex] Routing Claude generate to native @anthropic-ai/vertex-sdk", {
+                            model: modelName,
+                            totalToolCount: Object.keys(mergedOptions.tools).length,
+                        });
+                        return this.executeNativeAnthropicGenerate(mergedOptions);
+                    }
                     logger.info("[GoogleVertex] Routing Gemini generate to native @google/genai", {
                         model: modelName,
                         totalToolCount: Object.keys(mergedOptions.tools).length,
                     });
-                    result = await this.executeNativeGemini3Generate(mergedOptions);
-                }
+                    return this.executeNativeGemini3Generate(mergedOptions);
+                });
                 this.attachUsageAndCostAttributes(generateSpan, modelName, result?.usage);
+                // Pipe through TTS-of-AI-response when caller asks for it. The
+                // shared `synthesizeAIResponseIfNeeded` no-ops when tts is not
+                // enabled / useAiResponse is false, so the cost is zero on
+                // non-TTS paths.
+                result = await this.synthesizeAIResponseIfNeeded(result, options);
                 // Fire onFinish lifecycle callback for the native generate path.
                 // Pipeline A providers get this for free via the AI SDK middleware
                 // wrapper (LifecycleMiddleware); native @google/genai bypasses
@@ -3052,6 +3200,14 @@ export class GoogleVertexProvider extends BaseProvider {
                 ? { error: error instanceof Error ? error.message : String(error) }
                 : {}),
         });
+        // Mark on the result so the SDK-level runStandardGenerateRequest knows
+        // this provider already emitted `generation:end` itself and skips its
+        // own duplicate emission. Without this flag the public event listener
+        // (and the observability test) would see two events per generate call.
+        if (result && typeof result === "object") {
+            result._generationEndEmitted =
+                true;
+        }
     }
     formatProviderError(error) {
         const errorRecord = error;

package/dist/providers/groq.d.ts

@@ -0,0 +1,33 @@
+import { type LanguageModel } from "ai";
+import type { AIProviderName } from "../constants/enums.js";
+import { BaseProvider } from "../core/baseProvider.js";
+import type { NeurolinkCredentials, StreamOptions, StreamResult, ValidationSchema } from "../types/index.js";
+/**
+ * Groq Provider
+ *
+ * Sub-100ms inference of Llama / Mistral / Gemma at api.groq.com/openai/v1
+ * (OpenAI-compatible). Best for low-latency tier; trade-off vs other open
+ * model hosts is throughput latency, not quality.
+ *
+ * @see https://console.groq.com/docs/quickstart
+ */
+export declare class GroqProvider extends BaseProvider {
+    private model;
+    private apiKey;
+    private baseURL;
+    constructor(modelName?: string, sdk?: unknown, _region?: string, credentials?: NeurolinkCredentials["groq"]);
+    protected executeStream(options: StreamOptions, _analysisSchema?: ValidationSchema): Promise<StreamResult>;
+    private executeStreamInner;
+    protected getProviderName(): AIProviderName;
+    protected getDefaultModel(): string;
+    protected getAISDKModel(): LanguageModel;
+    protected formatProviderError(error: unknown): Error;
+    validateConfiguration(): Promise<boolean>;
+    getConfiguration(): {
+        provider: AIProviderName;
+        model: string;
+        defaultModel: string;
+        baseURL: string;
+    };
+}
+export default GroqProvider;