@juspay/neurolink 9.79.2 → 9.80.0

package/dist/neurolink.js

@@ -87,6 +87,7 @@ import { isNonNullObject } from "./utils/typeUtils.js";
 import { getWorkflow } from "./workflow/core/workflowRegistry.js";
 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";
 /**
  * NL-002: Classify MCP error messages into categories for AI disambiguation.
@@ -388,6 +389,9 @@ export class NeuroLink {
     // RequestRouter: pluggable pre-call provider/model selector.
     // Stored directly from config.requestRouter; null when not configured.
     requestRouter;
+    // ClassifierRouter: opt-in "classify → pick model + tools" pre-call router.
+    // Built from config.classifierRouter; null when not configured.
+    classifierRouter;
     /**
      * Merge instance-level credentials with per-call credentials.
      *
@@ -796,6 +800,17 @@ export class NeuroLink {
         this.modelPool = config?.modelPool ? new ModelPool(config.modelPool) : null;
         // RequestRouter: store the host-supplied function; null when not configured.
         this.requestRouter = config?.requestRouter ?? null;
+        // ClassifierRouter: opt-in. The LLM strategy reuses this instance's
+        // generate() (marked so it never recursively re-routes). Fails open.
+        this.classifierRouter = config?.classifierRouter?.enabled
+            ? new ClassifierRouter(config.classifierRouter, {
+                generate: (genOptions) => this.generate(genOptions),
+                logger: {
+                    debug: (message, meta) => logger.debug(message, meta),
+                    warn: (message, meta) => logger.warn(message, meta),
+                },
+            })
+            : null;
         logger.setEventEmitter(this.emitter);
         // Read tool cache duration from environment variables, with a default
         const cacheDurationEnv = process.env.NEUROLINK_TOOL_CACHE_DURATION;
@@ -3105,6 +3120,13 @@ Current user's request: ${currentInput}`;
     }
     async runStandardGenerateRequest(options, originalPrompt, generateSpan) {
         const startTime = Date.now();
+        // Pre-call classifier router: opt-in. Classifies the request and selects a
+        // provider/model from the configured base pool (and optionally narrows the
+        // tool set) BEFORE orchestration/requestRouter, so it takes precedence.
+        // Fails open.
+        await this.applyClassifierRouting(options, options.input?.text ?? originalPrompt ?? "", !options.disableTools &&
+            (!!(options.tools && Object.keys(options.tools).length > 0) ||
+                this.getCustomTools().size > 0), !!(options.input?.images && options.input.images.length > 0), options.thinkingConfig?.thinkingLevel);
         await this.maybeApplyGenerateOrchestration(options);
         // Pre-call request router: opt-in, only when the caller did not set both
         // provider+model. Fails open (any router error leaves options unchanged).
@@ -3241,6 +3263,12 @@ Current user's request: ${currentInput}`;
         if (!this.requestRouter) {
             return;
         }
+        // Stand down if the classifier router already selected a provider/model on
+        // this turn — one explicit precedence order: classifierRouter wins.
+        if (options.context
+            ?.__classifierRouted) {
+            return;
+        }
         // Skip if the caller explicitly set both provider AND model — they know
         // what they want; the router should not override an intentional choice.
         if (options.provider && options.model) {
@@ -3307,6 +3335,103 @@ Current user's request: ${currentInput}`;
             });
         }
     }
+    /**
+     * Applies the host-configured `classifierRouter` to `options` in place.
+     *
+     * Classifies the request by difficulty and selects a provider/model from the
+     * configured base pool (cheaper/faster for easy tasks, more capable for hard
+     * ones), and optionally narrows the tool set via `toolFilter`/`excludeTools`.
+     *
+     * Skipped when: no router is configured; the inbound call is the classifier's
+     * own generate() (marked `__classifierRouted`); the caller pinned BOTH
+     * provider and model; or a ModelPool is configured (the pool owns selection).
+     * Fails open — any error leaves options unchanged.
+     */
+    async applyClassifierRouting(options, promptText, hasTools, requiresVision, thinkingLevel) {
+        if (!this.classifierRouter) {
+            return;
+        }
+        const opt = options;
+        // Prevent recursion: the LLM classifier itself calls generate() with this
+        // marker set. Also respect any explicit prior routing decision.
+        if (opt.context?.__classifierRouted) {
+            return;
+        }
+        // Honor an intentional caller choice of BOTH provider and model.
+        if (options.provider && options.model) {
+            return;
+        }
+        // A ModelPool overrides provider/model per member unconditionally; let it
+        // own selection (mirrors applyRequestRouter precedence).
+        if (this.modelPool) {
+            logger.debug("[NeuroLink] applyClassifierRouting: skipped — modelPool takes precedence");
+            return;
+        }
+        const sessionId = typeof opt.context?.sessionId === "string"
+            ? opt.context.sessionId
+            : undefined;
+        try {
+            const decision = await this.classifierRouter.route({
+                prompt: promptText,
+                estimatedInputTokens: Math.ceil((promptText?.length ?? 0) / 4),
+                hasTools,
+                requiresVision,
+                thinkingLevel,
+                sessionId,
+            });
+            if (!decision) {
+                return;
+            }
+            // Apply provider/model/region as a coherent set (same discipline as
+            // applyRequestRouter): only fill fields the caller did not pin.
+            if (decision.provider && !options.provider) {
+                options.provider = decision.provider;
+                if (decision.model && !options.model) {
+                    options.model = decision.model;
+                }
+                if (decision.region && !options.region) {
+                    options.region = decision.region;
+                }
+            }
+            else if (!decision.provider && decision.model && !options.model) {
+                options.model = decision.model;
+            }
+            // Narrow tools unless the caller disabled tools entirely.
+            if (!opt.disableTools) {
+                if (decision.excludeTools && decision.excludeTools.length > 0) {
+                    opt.excludeTools = Array.from(new Set([...(opt.excludeTools ?? []), ...decision.excludeTools]));
+                }
+                if (decision.toolFilter && decision.toolFilter.length > 0) {
+                    const allow = decision.toolFilter;
+                    opt.toolFilter =
+                        opt.toolFilter && opt.toolFilter.length > 0
+                            ? opt.toolFilter.filter((t) => allow.includes(t))
+                            : [...allow];
+                }
+            }
+            // Mark routed so orchestration/requestRouter stand down this turn.
+            if (decision.provider || decision.model) {
+                const ctx = opt.context ?? {};
+                ctx.__classifierRouted = true;
+                opt.context = ctx;
+            }
+            if (decision.reason) {
+                logger.debug("[NeuroLink] classifierRouter decision", {
+                    reason: decision.reason,
+                    difficulty: decision.difficulty,
+                    provider: options.provider,
+                    model: options.model,
+                });
+            }
+        }
+        catch (classifierErr) {
+            logger.warn("[NeuroLink] classifierRouter threw — proceeding unrouted", {
+                error: classifierErr instanceof Error
+                    ? classifierErr.message
+                    : String(classifierErr),
+            });
+        }
+    }
     async prepareGenerateAugmentations(options) {
         if (options.rag?.files?.length) {
             try {
@@ -5829,6 +5954,12 @@ Current user's request: ${currentInput}`;
             // classify correctly. After the workflow short-circuit, so workflow
             // streams skip it.
             await context.with(streamSpanContext, () => this.setLangfuseContextFromOptions(options, () => this.applyToolRoutingExclusions(options, originalPrompt)));
+            // Pre-call classifier router for stream: opt-in, fails open. Runs before
+            // the request router so it takes precedence.
+            await this.applyClassifierRouting(options, originalPrompt, !options.disableTools &&
+                (!!(options.tools && Object.keys(options.tools).length > 0) ||
+                    this.getCustomTools().size > 0), !!(options.input?.images && options.input.images.length > 0), options
+                .thinking?.thinkingLevel);
             // Pre-call request router for stream: opt-in, fails open.
             await this.applyRequestRouter(options, originalPrompt, !options.disableTools &&
                 (!!(options.tools && Object.keys(options.tools).length > 0) ||

package/dist/providers/googleNativeGemini3.d.ts

@@ -96,6 +96,32 @@ export declare function buildNativeConfig(options: {
  * Compute a safe, clamped maxSteps value.
  */
 export declare function computeMaxSteps(rawMaxSteps?: number): number;
+/**
+ * Map a `@google/genai` `Candidate.finishReason` enum value onto NeuroLink's
+ * unified finish reason, mirroring anthropic.ts `mapAnthropicStopReason`.
+ *
+ * Enum values per `@google/genai` `FinishReason`: STOP, MAX_TOKENS, SAFETY,
+ * RECITATION, LANGUAGE, OTHER, BLOCKLIST, PROHIBITED_CONTENT, SPII,
+ * MALFORMED_FUNCTION_CALL, IMAGE_SAFETY, UNEXPECTED_TOOL_CALL,
+ * FINISH_REASON_UNSPECIFIED. Unknown / unset / non-terminal values default to
+ * "stop" (a clean completion is the safe assumption).
+ *
+ * Returns a plain string (not a `{ unified, raw }` object): the Vertex result
+ * builders and the consuming layer (neurolink.ts `finishReason || "unknown"`
+ * and `finishReason === "length"`) compare against plain strings.
+ */
+export declare function mapGeminiFinishReason(raw: string | null | undefined): "stop" | "length" | "tool-calls" | "content-filter";
+/**
+ * Append a step's text to a running cross-step accumulator, ignoring empty
+ * steps and inserting a single newline between non-empty contributions.
+ *
+ * The native Gemini loops overwrite per-step text into `lastStepText`, so when
+ * the loop is force-terminated by the step cap the intermediate tool-step prose
+ * is lost and a canned placeholder becomes the answer. Accumulating here mirrors
+ * the Vertex-Claude loop's `aggregatedTurnText += block.text` so the gathered
+ * text can be surfaced at the maxSteps-exhaustion exit instead of the placeholder.
+ */
+export declare function appendStepText(accumulated: string, stepText: string): string;
 /**
  * Process stream chunks to extract raw response parts, function calls, and usage metadata.
  *

package/dist/providers/googleNativeGemini3.js

@@ -450,6 +450,54 @@ export function computeMaxSteps(rawMaxSteps) {
         ? Math.min(Math.floor(value), GEMINI3_NATIVE_MAX_STEPS)
         : Math.min(DEFAULT_MAX_STEPS, GEMINI3_NATIVE_MAX_STEPS);
 }
+/**
+ * Map a `@google/genai` `Candidate.finishReason` enum value onto NeuroLink's
+ * unified finish reason, mirroring anthropic.ts `mapAnthropicStopReason`.
+ *
+ * Enum values per `@google/genai` `FinishReason`: STOP, MAX_TOKENS, SAFETY,
+ * RECITATION, LANGUAGE, OTHER, BLOCKLIST, PROHIBITED_CONTENT, SPII,
+ * MALFORMED_FUNCTION_CALL, IMAGE_SAFETY, UNEXPECTED_TOOL_CALL,
+ * FINISH_REASON_UNSPECIFIED. Unknown / unset / non-terminal values default to
+ * "stop" (a clean completion is the safe assumption).
+ *
+ * Returns a plain string (not a `{ unified, raw }` object): the Vertex result
+ * builders and the consuming layer (neurolink.ts `finishReason || "unknown"`
+ * and `finishReason === "length"`) compare against plain strings.
+ */
+export function mapGeminiFinishReason(raw) {
+    switch (raw) {
+        case "MAX_TOKENS":
+            return "length";
+        case "MALFORMED_FUNCTION_CALL":
+        case "UNEXPECTED_TOOL_CALL":
+            return "tool-calls";
+        case "SAFETY":
+        case "RECITATION":
+        case "BLOCKLIST":
+        case "PROHIBITED_CONTENT":
+        case "SPII":
+        case "IMAGE_SAFETY":
+            return "content-filter";
+        default:
+            return "stop";
+    }
+}
+/**
+ * Append a step's text to a running cross-step accumulator, ignoring empty
+ * steps and inserting a single newline between non-empty contributions.
+ *
+ * The native Gemini loops overwrite per-step text into `lastStepText`, so when
+ * the loop is force-terminated by the step cap the intermediate tool-step prose
+ * is lost and a canned placeholder becomes the answer. Accumulating here mirrors
+ * the Vertex-Claude loop's `aggregatedTurnText += block.text` so the gathered
+ * text can be surfaced at the maxSteps-exhaustion exit instead of the placeholder.
+ */
+export function appendStepText(accumulated, stepText) {
+    if (!stepText) {
+        return accumulated;
+    }
+    return accumulated ? `${accumulated}\n${stepText}` : stepText;
+}
 /**
  * Process stream chunks to extract raw response parts, function calls, and usage metadata.
  *

package/dist/providers/googleVertex.d.ts

@@ -160,6 +160,22 @@ export declare class GoogleVertexProvider extends BaseProvider {
      * This bypasses @ai-sdk/google-vertex to properly handle thought_signature
      */
     private executeNativeGemini3Generate;
+    /**
+     * One-shot, tools-disabled model call used when a native Gemini agentic loop
+     * is force-terminated by the step cap with no text produced. Lets the model
+     * synthesize a final answer from the function results already in `contents`
+     * instead of returning a canned placeholder (Bug 1, part b).
+     *
+     * Tools are disabled by OMITTING `config.tools` — the codebase's established
+     * mechanism. `@google/genai`'s `FunctionCallingConfigMode.NONE` is documented
+     * as equivalent to passing no function declarations, and `functionCallingConfig`
+     * is not used anywhere in this codebase. When the structured-output
+     * (`final_result`) pattern was active, a trailing instruction countermands the
+     * earlier "you MUST call final_result" directive so the model answers in plain
+     * text. Never throws — returns empty text so the caller falls back to the
+     * placeholder, guaranteeing no new failure path.
+     */
+    private synthesizeFinalAnswerWithoutTools;
     /**
      * Create native AnthropicVertex client for Claude models
      */

package/dist/providers/googleVertex.js

@@ -22,7 +22,7 @@ import { convertZodToJsonSchema, inlineJsonSchema, ensureNestedSchemaTypes, } fr
 import { createNativeThinkingConfig } from "../utils/thinkingConfig.js";
 import { TimeoutError, withTimeout } from "../utils/async/index.js";
 import { parseTimeout } from "../utils/timeout.js";
-import { createTextChannel, extractThoughtSignature, prependConversationMessages, } from "./googleNativeGemini3.js";
+import { appendStepText, createTextChannel, extractThoughtSignature, mapGeminiFinishReason, prependConversationMessages, } from "./googleNativeGemini3.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";
 import { calculateCost } from "../utils/pricing.js";
@@ -786,7 +786,7 @@ export class GoogleVertexProvider extends BaseProvider {
                 // lifecycle callbacks. Pipeline A gets these via the AI SDK
                 // wrapStream middleware; the native path has to fire them here.
                 const wrappedResult = this.wrapStreamResultWithLifecycle(options, result, streamStartTime);
-                this.emitStreamEnd(modelName, streamStartTime, true);
+                this.emitStreamEnd(modelName, streamStartTime, true, undefined, result.finishReason);
                 return wrappedResult;
             }
             catch (error) {
@@ -801,7 +801,7 @@ export class GoogleVertexProvider extends BaseProvider {
      * `model.generation` span for native Vertex stream traffic. Mirrors
      * `emitGenerationEnd` (used by `generate()`).
      */
-    emitStreamEnd(modelName, startTime, success, error) {
+    emitStreamEnd(modelName, startTime, success, error, resolvedFinishReason) {
         const emitter = this.neurolink?.getEventEmitter();
         if (!emitter) {
             return;
@@ -815,7 +815,7 @@ export class GoogleVertexProvider extends BaseProvider {
                 usage: { input: 0, output: 0, total: 0 },
                 model: modelName,
                 provider: this.providerName,
-                finishReason: success ? "stop" : "error",
+                finishReason: success ? (resolvedFinishReason ?? "stop") : "error",
             },
             success,
             ...(error
@@ -1156,7 +1156,10 @@ export class GoogleVertexProvider extends BaseProvider {
             : Math.min(DEFAULT_MAX_STEPS, 100);
         const currentContents = [...contents];
         let finalText = "";
-        let lastStepText = ""; // Track text from last step for maxSteps termination
+        // Last SDK finish reason seen across steps (Bug 2: previously never read,
+        // so callers fell back to "unknown"). Last non-empty value wins — the
+        // terminal chunk is authoritative.
+        let lastFinishReason;
         const allToolCalls = [];
         // Mirrors the generate-path shape so StreamResult.toolExecutions can be
         // populated (parity with AI-SDK-driven providers) and so the storage
@@ -1200,6 +1203,12 @@ export class GoogleVertexProvider extends BaseProvider {
                     const chunkRecord = chunk;
                     const candidates = chunkRecord.candidates;
                     const firstCandidate = candidates?.[0];
+                    // Capture the SDK finish reason (Bug 2: previously dropped). Last
+                    // non-empty value across chunks wins.
+                    const chunkFinishReason = firstCandidate?.finishReason;
+                    if (typeof chunkFinishReason === "string" && chunkFinishReason) {
+                        lastFinishReason = chunkFinishReason;
+                    }
                     const chunkContent = firstCandidate?.content;
                     if (chunkContent && Array.isArray(chunkContent.parts)) {
                         for (const part of chunkContent.parts) {
@@ -1253,8 +1262,6 @@ export class GoogleVertexProvider extends BaseProvider {
                         break;
                     }
                 }
-                // Track the last step text for maxSteps termination
-                lastStepText = stepText;
                 // Execute function calls
                 logger.debug(`[GoogleVertex] Executing ${stepFunctionCalls.length} function calls`);
                 // Add model response with ALL parts (including thoughtSignature) to history
@@ -1426,14 +1433,50 @@ export class GoogleVertexProvider extends BaseProvider {
                 throw this.handleProviderError(error);
             }
         }
-        // Handle maxSteps termination - if we exited the loop due to maxSteps being reached
+        // Handle maxSteps termination — the loop exited because the step cap was
+        // reached while the model was still calling tools. Surface a real answer
+        // instead of the canned placeholder (Bug 1) and a meaningful finishReason
+        // (Bug 2).
+        let hitStepLimit = false;
+        let synthesizedFinalAnswer = false;
         if (step >= maxSteps && !finalText) {
-            logger.warn(`[GoogleVertex] Tool call loop terminated after reaching maxSteps (${maxSteps}). ` +
-                `Model was still calling tools. Using accumulated text from last step.`);
-            finalText =
-                lastStepText ||
-                    `[Tool execution limit reached after ${maxSteps} steps. The model continued requesting tool calls beyond the limit.]`;
+            hitStepLimit = true;
+            // The consumer receives text via `incrementalTextChunks`; any text the
+            // model emitted across steps is already preserved there. Only synthesize
+            // when NOTHING was produced (the pure-functionCall case that otherwise
+            // surfaces the placeholder) so we never waste a round-trip whose output
+            // the stream would ignore.
+            if (incrementalTextChunks.length === 0) {
+                logger.warn(`[GoogleVertex] Tool call loop terminated after reaching maxSteps (${maxSteps}) ` +
+                    `with no text; synthesizing a final answer with tools disabled.`);
+                const synth = await this.synthesizeFinalAnswerWithoutTools(client, modelName, config, currentContents, useFinalResultTool, parseTimeout(options.timeout) ?? 300_000);
+                if (synth.text) {
+                    synthesizedFinalAnswer = true;
+                    finalText = synth.text;
+                    incrementalTextChunks.push(synth.text);
+                    totalInputTokens += synth.inputTokens;
+                    totalOutputTokens += synth.outputTokens;
+                    if (synth.finishReason) {
+                        lastFinishReason = synth.finishReason;
+                    }
+                }
+                else {
+                    finalText = `[Tool execution limit reached after ${maxSteps} steps. The model continued requesting tool calls beyond the limit.]`;
+                }
+            }
+            else {
+                logger.warn(`[GoogleVertex] Tool call loop terminated after reaching maxSteps (${maxSteps}); ` +
+                    `returning text already gathered from prior steps.`);
+            }
         }
+        // Unified finish reason: a step-cap exhaustion that did NOT end in a clean
+        // synthesized answer is reported as "tool-calls" (the model still wanted
+        // tools) — NOT "length", which neurolink.ts treats as token truncation
+        // (jsonTruncated + WARNING span). A clean completion maps from the SDK
+        // finish reason.
+        const resolvedFinishReason = hitStepLimit && !synthesizedFinalAnswer
+            ? "tool-calls"
+            : mapGeminiFinishReason(lastFinishReason);
         const responseTime = Date.now() - startTime;
         // Yield each text part separately so the CLI receives multiple stream
         // chunks instead of a single coalesced buffer. The SDK already gave us
@@ -1460,6 +1503,7 @@ export class GoogleVertexProvider extends BaseProvider {
             stream: createTextStream(),
             provider: this.providerName,
             model: modelName,
+            finishReason: resolvedFinishReason,
             usage: {
                 input: totalInputTokens,
                 output: totalOutputTokens,
@@ -1791,7 +1835,11 @@ export class GoogleVertexProvider extends BaseProvider {
             : Math.min(DEFAULT_MAX_STEPS, 100);
         const currentContents = [...contents];
         let finalText = "";
-        let lastStepText = ""; // Track text from last step for maxSteps termination
+        // Cross-step text accumulation + last SDK finish reason, so the
+        // maxSteps-exhaustion exit can surface real gathered text (Bug 1) and a
+        // meaningful finishReason (Bug 2) instead of a placeholder / "unknown".
+        let accumulatedText = "";
+        let lastFinishReason;
         const allToolCalls = [];
         const toolExecutions = [];
         let step = 0;
@@ -1826,6 +1874,12 @@ export class GoogleVertexProvider extends BaseProvider {
                     const chunkRecord = chunk;
                     const candidates = chunkRecord.candidates;
                     const firstCandidate = candidates?.[0];
+                    // Capture the SDK finish reason (Bug 2: previously dropped). Last
+                    // non-empty value across chunks wins.
+                    const chunkFinishReason = firstCandidate?.finishReason;
+                    if (typeof chunkFinishReason === "string" && chunkFinishReason) {
+                        lastFinishReason = chunkFinishReason;
+                    }
                     const chunkContent = firstCandidate?.content;
                     if (chunkContent && Array.isArray(chunkContent.parts)) {
                         rawResponseParts.push(...chunkContent.parts);
@@ -1874,8 +1928,11 @@ export class GoogleVertexProvider extends BaseProvider {
                         break;
                     }
                 }
-                // Track the last step text for maxSteps termination
-                lastStepText = stepText;
+                // Accumulate non-empty step text across steps so the
+                // maxSteps-exhaustion exit can surface the prose the model produced
+                // instead of a canned placeholder (Bug 1). Mirrors the Vertex-Claude
+                // loop's text accumulation.
+                accumulatedText = appendStepText(accumulatedText, stepText);
                 // Execute function calls
                 logger.debug(`[GoogleVertex] Generate executing ${stepFunctionCalls.length} function calls`);
                 // Add model response with ALL parts (including thoughtSignature) to history
@@ -2036,14 +2093,49 @@ export class GoogleVertexProvider extends BaseProvider {
                 throw this.handleProviderError(error);
             }
         }
-        // Handle maxSteps termination - if we exited the loop due to maxSteps being reached
+        // Handle maxSteps termination — the loop exited because the step cap was
+        // reached while the model was still calling tools. Surface a real answer
+        // instead of the canned placeholder (Bug 1) and a meaningful finishReason
+        // (Bug 2).
+        let hitStepLimit = false;
+        let synthesizedFinalAnswer = false;
         if (step >= maxSteps && !finalText) {
-            logger.warn(`[GoogleVertex] Generate tool call loop terminated after reaching maxSteps (${maxSteps}). ` +
-                `Model was still calling tools. Using accumulated text from last step.`);
-            finalText =
-                lastStepText ||
-                    `[Tool execution limit reached after ${maxSteps} steps. The model continued requesting tool calls beyond the limit.]`;
+            hitStepLimit = true;
+            if (accumulatedText) {
+                // Prefer the prose the model already produced across steps.
+                logger.warn(`[GoogleVertex] Generate tool call loop terminated after reaching maxSteps (${maxSteps}); ` +
+                    `returning text already gathered from prior steps.`);
+                finalText = accumulatedText;
+            }
+            else {
+                // Pure functionCall turns leave no text — make one tools-disabled call
+                // so the model answers from the gathered tool results instead of the
+                // canned placeholder.
+                logger.warn(`[GoogleVertex] Generate tool call loop terminated after reaching maxSteps (${maxSteps}) ` +
+                    `with no text; synthesizing a final answer with tools disabled.`);
+                const synth = await this.synthesizeFinalAnswerWithoutTools(client, modelName, config, currentContents, useFinalResultTool, parseTimeout(options.timeout) ?? 300_000);
+                if (synth.text) {
+                    synthesizedFinalAnswer = true;
+                    finalText = synth.text;
+                    totalInputTokens += synth.inputTokens;
+                    totalOutputTokens += synth.outputTokens;
+                    if (synth.finishReason) {
+                        lastFinishReason = synth.finishReason;
+                    }
+                }
+                else {
+                    finalText = `[Tool execution limit reached after ${maxSteps} steps. The model continued requesting tool calls beyond the limit.]`;
+                }
+            }
         }
+        // Unified finish reason: a step-cap exhaustion that did NOT end in a clean
+        // synthesized answer is reported as "tool-calls" (the model still wanted
+        // tools) — NOT "length", which neurolink.ts treats as token truncation
+        // (jsonTruncated + WARNING span). A clean completion maps from the SDK
+        // finish reason.
+        const resolvedFinishReason = hitStepLimit && !synthesizedFinalAnswer
+            ? "tool-calls"
+            : mapGeminiFinishReason(lastFinishReason);
         const responseTime = Date.now() - startTime;
         // Filter out final_result from tool calls and executions as it's an internal pattern
         const externalToolCalls = allToolCalls.filter((tc) => tc.toolName !== "final_result");
@@ -2053,6 +2145,7 @@ export class GoogleVertexProvider extends BaseProvider {
             content: finalText,
             provider: this.providerName,
             model: modelName,
+            finishReason: resolvedFinishReason,
             usage: {
                 input: totalInputTokens,
                 output: totalOutputTokens,
@@ -2073,6 +2166,89 @@ export class GoogleVertexProvider extends BaseProvider {
         // Vertex Gemini generate path.
         return this.enhanceResult(result, options, startTime);
     }
+    /**
+     * One-shot, tools-disabled model call used when a native Gemini agentic loop
+     * is force-terminated by the step cap with no text produced. Lets the model
+     * synthesize a final answer from the function results already in `contents`
+     * instead of returning a canned placeholder (Bug 1, part b).
+     *
+     * Tools are disabled by OMITTING `config.tools` — the codebase's established
+     * mechanism. `@google/genai`'s `FunctionCallingConfigMode.NONE` is documented
+     * as equivalent to passing no function declarations, and `functionCallingConfig`
+     * is not used anywhere in this codebase. When the structured-output
+     * (`final_result`) pattern was active, a trailing instruction countermands the
+     * earlier "you MUST call final_result" directive so the model answers in plain
+     * text. Never throws — returns empty text so the caller falls back to the
+     * placeholder, guaranteeing no new failure path.
+     */
+    async synthesizeFinalAnswerWithoutTools(client, modelName, config, contents, useFinalResultTool, timeoutMs) {
+        try {
+            // Shallow clone so the loop's config is never mutated; dropping the
+            // top-level `tools` key is sufficient (nested thinkingConfig /
+            // systemInstruction are intentionally preserved).
+            const synthConfig = { ...config };
+            delete synthConfig.tools;
+            if (useFinalResultTool) {
+                const baseSystemInstruction = typeof synthConfig.systemInstruction === "string"
+                    ? synthConfig.systemInstruction
+                    : "";
+                synthConfig.systemInstruction =
+                    baseSystemInstruction +
+                        "\n\nThe final_result tool is no longer available. Provide your " +
+                        "final answer directly as plain text now, using the information " +
+                        "gathered so far.";
+            }
+            // Bound the whole connect + drain with a timeout. The surrounding
+            // try/catch only catches throws, not hangs, so without this a stalled
+            // Vertex endpoint would hang the maxSteps recovery path indefinitely.
+            // On timeout withTimeout rejects (TimeoutError) and the catch below
+            // falls back to the placeholder — no new failure path is introduced.
+            return await withTimeout((async () => {
+                const stream = await client.models.generateContentStream({
+                    model: modelName,
+                    contents,
+                    config: synthConfig,
+                });
+                const parts = [];
+                let finishReason;
+                let inputTokens = 0;
+                let outputTokens = 0;
+                for await (const chunk of stream) {
+                    const chunkRecord = chunk;
+                    const candidates = chunkRecord.candidates;
+                    const firstCandidate = candidates?.[0];
+                    const chunkFinishReason = firstCandidate?.finishReason;
+                    if (typeof chunkFinishReason === "string" && chunkFinishReason) {
+                        finishReason = chunkFinishReason;
+                    }
+                    const chunkContent = firstCandidate?.content;
+                    if (chunkContent && Array.isArray(chunkContent.parts)) {
+                        parts.push(...chunkContent.parts);
+                    }
+                    const usageMetadata = chunkRecord.usageMetadata;
+                    if (usageMetadata) {
+                        if (usageMetadata.promptTokenCount !== undefined &&
+                            usageMetadata.promptTokenCount > 0) {
+                            inputTokens = usageMetadata.promptTokenCount;
+                        }
+                        if (usageMetadata.candidatesTokenCount !== undefined &&
+                            usageMetadata.candidatesTokenCount > 0) {
+                            outputTokens = usageMetadata.candidatesTokenCount;
+                        }
+                    }
+                }
+                const text = parts
+                    .filter((part) => typeof part.text === "string")
+                    .map((part) => part.text)
+                    .join("");
+                return { text, finishReason, inputTokens, outputTokens };
+            })(), timeoutMs, "Gemini synthesis call timed out");
+        }
+        catch (error) {
+            logger.warn("[GoogleVertex] Tools-disabled synthesis call failed; falling back to placeholder", { error: error instanceof Error ? error.message : String(error) });
+            return { text: "", inputTokens: 0, outputTokens: 0 };
+        }
+    }
     /**
      * Create native AnthropicVertex client for Claude models
      */
@@ -3685,7 +3861,7 @@ export class GoogleVertexProvider extends BaseProvider {
                     }
                     : undefined,
                 duration: Date.now() - startTime,
-                finishReason: "stop",
+                finishReason: result?.finishReason ?? "stop",
             });
             Promise.resolve(callbackResult).catch((err) => logger.warn(`[GoogleVertex] onFinish callback rejected: ${err instanceof Error ? err.message : String(err)}`));
         }
@@ -3890,7 +4066,7 @@ export class GoogleVertexProvider extends BaseProvider {
                 usage,
                 model: modelName,
                 provider: this.providerName,
-                finishReason: success ? "stop" : "error",
+                finishReason: success ? (result?.finishReason ?? "stop") : "error",
             },
             success,
             ...(error