@juspay/neurolink 12.21.1 → 12.22.0

package/dist/providers/googleAiStudio/client.js

@@ -9,7 +9,7 @@ import { logger } from "../../utils/logger.js";
 import { drainDetachedPump } from "../../utils/drainDetachedPump.js";
 import { createGeminiLoopAdapter } from "../../core/geminiLoopAdapter.js";
 import { runAgenticLoop } from "../../core/loopEngine.js";
-import { DEFAULT_TOOL_MAX_RETRIES } from "../../core/constants.js";
+import { DEFAULT_TOOL_MAX_RETRIES, resolveToolTimeoutMs, } from "../../core/constants.js";
 import { isToolsSchemaExclusionInForce } from "../../core/modules/structuredOutputPolicy.js";
 import { GEMINI_ELISION_NOTE, planGeminiLoopReclaim, previewGeminiToolResponseText, } from "../../context/geminiLoopGuard.js";
 import { getAvailableInputTokens, getContextWindowSize, } from "../../constants/contextWindows.js";
@@ -18,7 +18,7 @@ import { withTimeout } from "../../utils/async/index.js";
 import { estimateTokens } from "../../utils/tokenEstimation.js";
 import { transformToolExecutions } from "../../utils/transformationUtils.js";
 import { resolveToolExecutionRecords } from "../../core/toolExecutionRecorder.js";
-import { buildDedupedEngineTools, buildGeminiResponseSchema, buildNativeConfig, computeMaxSteps, createContextGuard, buildUserPartsWithMultimodal, extractThoughtSignature, handleMaxStepsTermination, prependConversationMessages, } from "../googleNativeGemini3/index.js";
+import { buildDedupedEngineTools, buildGeminiResponseSchema, buildLoopExitMessage, buildNativeConfig, buildWrapupNudgeText, computeMaxSteps, createContextGuard, createTurnClock, buildUserPartsWithMultimodal, extractThoughtSignature, handleMaxStepsTermination, mapGeminiFinishReason, prependConversationMessages, resolveTurnStopReason, } from "../googleNativeGemini3/index.js";
 import { createStreamChannel } from "../../core/streamChannel.js";
 import { toNativeToolDeclarations } from "../../core/nativeToolFormat.js";
 import { warnGoogleSdkIgnoresProxy } from "../../proxy/proxyFetch.js";
@@ -687,8 +687,51 @@ export class GoogleAIStudioProvider extends BaseProvider {
                     responseSchema: nativeResponseSchema,
                 }, toolsConfig);
                 const maxSteps = computeMaxSteps(options.maxSteps);
-                // Compose abort signal from user signal + timeout
-                const composedSignal = composeAbortSignals(options.abortSignal, timeoutController?.controller.signal);
+                // Abort fan-in. The caller's signal, the pre-existing per-request
+                // timeout controller and the turn clock's watchdogs all trip one
+                // internal controller, and everything downstream (SDK request,
+                // engine, guarded tool executors) rides its signal — so a deadline
+                // reaches a tool mid-execution, not only the next step boundary.
+                const upstreamSignal = composeAbortSignals(options.abortSignal, timeoutController?.controller.signal);
+                const internalAbort = new AbortController();
+                const onUpstreamAbort = () => internalAbort.abort();
+                upstreamSignal?.addEventListener("abort", onUpstreamAbort);
+                if (upstreamSignal?.aborted) {
+                    internalAbort.abort();
+                }
+                const toolExecTimeoutMs = resolveToolTimeoutMs(options.toolTimeoutMs);
+                // No `defaultTurnTimeoutMs`: this path already carries a whole-turn
+                // bound in `timeoutController`, and arming a second timer for the
+                // same instant would make which one fired a race. The clock owns an
+                // explicit `turnTimeoutMs` and the stall watchdog; the controller
+                // keeps the default deadline it always had, and `timedOut` below
+                // reads both so either one is reported as a time-limit exit.
+                const turnClock = createTurnClock({
+                    ...(options.turnTimeoutMs !== undefined
+                        ? { turnTimeoutMs: options.turnTimeoutMs }
+                        : {}),
+                    ...(options.stallTimeoutMs !== undefined
+                        ? { stallTimeoutMs: options.stallTimeoutMs }
+                        : {}),
+                    ...(options.wrapupTimeLeadMs !== undefined
+                        ? { wrapupTimeLeadMs: options.wrapupTimeLeadMs }
+                        : {}),
+                    onDeadline: (kind) => {
+                        logger.warn(kind === "timeout"
+                            ? `[GoogleAIStudio] Native Gemini turn exceeded its ${options.turnTimeoutMs}ms time budget — aborting`
+                            : `[GoogleAIStudio] Native Gemini turn made no progress for ${options.stallTimeoutMs}ms — aborting`);
+                        internalAbort.abort();
+                    },
+                });
+                const composedSignal = internalAbort.signal;
+                /**
+                 * True when a wall-clock bound ended the turn. Both the turn clock's
+                 * explicit deadline and the pre-existing per-request controller are
+                 * time limits, so an exit caused by either must not be reported as a
+                 * bare caller abort.
+                 */
+                const hitTimeLimit = () => turnClock.timedOut ||
+                    timeoutController?.controller.signal.aborted === true;
                 // Create a push-based text channel so the caller receives tokens as
                 // they arrive from the network rather than after full buffering.
                 const channel = createStreamChannel();
@@ -708,6 +751,9 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 });
                 // Shared metadata object mutated by the background loop so the
                 // returned object reflects the final values after stream completion.
+                // Typed against StreamResult so the turn-exit fields the loop fills
+                // in at close (stopReason / rawFinishReason / stepsUsed) are the
+                // declared ones rather than late additions to an inferred shape.
                 const metadata = {
                     streamId: `native-${Date.now()}`,
                     startTime,
@@ -723,6 +769,13 @@ export class GoogleAIStudioProvider extends BaseProvider {
                     let totalCacheReadTokens = 0;
                     let totalReasoningTokens = 0;
                     let step = 0;
+                    // Model calls the engine actually made, reported from the
+                    // per-step request hook. `step` above counts only steps that
+                    // produced tool calls, so it misses the final text-only step and
+                    // would under-report `stepsUsed`, which is a public field.
+                    let stepsTaken = 0;
+                    let wasAborted = false;
+                    let lastFinishReason;
                     // Cheap trigger for the in-turn reclaim, mirroring the Vertex twin.
                     // Planning serializes the WHOLE accumulated history to estimate it,
                     // so running it unconditionally charges that once per step for the
@@ -744,6 +797,13 @@ export class GoogleAIStudioProvider extends BaseProvider {
                             // what makes an always-failing tool dispatch exactly twice.
                             toolFailureBreaker: { maxRetries: DEFAULT_TOOL_MAX_RETRIES },
                             liveTools: options.tools ?? {},
+                            // A tool hydrated mid-turn gets the same bound, abort race
+                            // and stall ping as one declared up front.
+                            toolGuards: {
+                                toolTimeoutMs: toolExecTimeoutMs,
+                                abortSignal: composedSignal,
+                                onProgress: () => turnClock.noteProgress(),
+                            },
                             ...(declarationsResult
                                 ? { declarations: declarationsResult }
                                 : {}),
@@ -751,11 +811,23 @@ export class GoogleAIStudioProvider extends BaseProvider {
                                 model: modelName,
                                 contents,
                                 config,
-                                ...(composedSignal
-                                    ? { httpOptions: { signal: composedSignal } }
-                                    : {}),
                             }),
-                            sendStep: async (request) => client.models.generateContentStream(request),
+                            // `config.abortSignal` is the ONLY cancellation channel
+                            // @google/genai reads (ApiClient forwards
+                            // `params.config.abortSignal` to fetch). This loop previously
+                            // passed a top-level `httpOptions.signal`, which is not a key
+                            // the SDK looks at, so nothing could cancel an in-flight
+                            // request — a caller abort or a blown deadline only took
+                            // effect at the next step boundary, and never at all against a
+                            // provider that had gone quiet mid-stream.
+                            sendStep: async (request, signal) => {
+                                turnClock.noteProgress();
+                                const built = request;
+                                return client.models.generateContentStream({
+                                    ...built,
+                                    config: { ...(built.config ?? {}), abortSignal: signal },
+                                });
+                            },
                             noteUsage: (inputTokens, outputTokens) => {
                                 contextGuard.noteUsage(inputTokens, outputTokens);
                             },
@@ -780,6 +852,15 @@ export class GoogleAIStudioProvider extends BaseProvider {
                         // late write and lose the per-step thought signature.
                         const adapter = {
                             ...baseAdapter,
+                            // Counted HERE, not in buildToolResultMessages: this runs once
+                            // per model call, including the final text-only step that asks
+                            // for no tools. Counting in the tool-result hook reports one
+                            // step fewer for every turn that ends normally.
+                            buildStepRequest: (contents, engineStep) => {
+                                stepsTaken = engineStep + 1;
+                                turnClock.noteProgress();
+                                return baseAdapter.buildStepRequest(contents, engineStep);
+                            },
                             buildToolResultMessages: (contents, stepResult, toolResults, engineStep) => {
                                 // The engine's own step, not a count of times this hook ran.
                                 // The two agree only while nothing skips the hook mid-turn:
@@ -832,6 +913,19 @@ export class GoogleAIStudioProvider extends BaseProvider {
                                     });
                                 }
                                 const next = baseAdapter.buildToolResultMessages(contents, stepResult, toolResults, engineStep);
+                                // Time-budget wrap-up nudge (twin of the Vertex Gemini
+                                // loops'): with the turn deadline approaching, tell the
+                                // model to consolidate. Rides as a trailing text part on the
+                                // tool-response user turn. Only fires against an EXPLICIT
+                                // turnTimeoutMs — createTurnClock refuses to nudge against a
+                                // defensive default, so no caller gains injected prompt text
+                                // without asking for a time budget.
+                                if (turnClock.shouldNudgeWrapup()) {
+                                    const last = next[next.length - 1];
+                                    if (last && Array.isArray(last.parts)) {
+                                        last.parts.push({ text: buildWrapupNudgeText(false) });
+                                    }
+                                }
                                 // Project this step's growth: the appended tool results ride
                                 // the next prompt, which the provider has not reported on yet.
                                 try {
@@ -847,45 +941,82 @@ export class GoogleAIStudioProvider extends BaseProvider {
                         // Through the turn's DedupExecuteMap, NOT the raw executors:
                         // `.get()` returns the dedup wrapper that answers an identical
                         // repeated {name, args} from the per-turn cache (BZ-3327).
-                        const engineTools = buildDedupedEngineTools(declarationsResult, options.tools);
+                        const engineTools = buildDedupedEngineTools(declarationsResult, options.tools, {
+                            toolTimeoutMs: toolExecTimeoutMs,
+                            abortSignal: composedSignal,
+                            onProgress: () => turnClock.noteProgress(),
+                        });
                         const { stream: engineStream, resultPromise } = runAgenticLoop(adapter, currentContents, {
                             tools: engineTools,
-                            ...(composedSignal ? { abortSignal: composedSignal } : {}),
-                            // This loop guards no executor of its own, so the engine's
-                            // per-tool bound is the only thing standing between a wedged
-                            // tool and a turn that never ends. Honour the caller's value
-                            // when there is one; the engine defaults otherwise.
-                            ...(options.toolTimeoutMs !== undefined
-                                ? { toolTimeoutMs: options.toolTimeoutMs }
-                                : {}),
+                            abortSignal: composedSignal,
+                            // The engine bounds every tool call itself. Passing the same
+                            // value the guards above use keeps the engine's backstop from
+                            // being tighter than what the caller asked for.
+                            toolTimeoutMs: toolExecTimeoutMs,
                         });
                         const pump = (async () => {
                             for await (const chunk of engineStream) {
+                                // Every chunk is progress, which is what keeps a productive
+                                // but slow turn away from the stall watchdog.
+                                turnClock.noteProgress();
                                 channel.push(chunk);
                             }
                         })();
                         let engineResult;
+                        let turnFailure;
                         try {
                             engineResult = await resultPromise;
                         }
                         catch (error) {
-                            await drainDetachedPump(pump, "GoogleAIStudio");
-                            logger.error("[GoogleAIStudio] Native SDK error", error);
-                            throw this.handleProviderError(error);
+                            turnFailure = error;
+                        }
+                        // Drained unconditionally and tolerantly: when the turn ends by
+                        // abort the channel rejects too, and re-awaiting a settled
+                        // rejection would rethrow the very error the branch below has
+                        // already decided to absorb.
+                        await drainDetachedPump(pump, "GoogleAIStudio");
+                        if (turnFailure !== undefined) {
+                            // A turn ended by its own time budget or by the caller is not
+                            // a provider failure. Rethrowing one would surface a deadline
+                            // as a network error and, worse, send the caller down an
+                            // unbounded fallback path right after a blown budget. A
+                            // provider timeout keeps throwing exactly as before, because
+                            // classifying it is what produces the timeout error callers
+                            // already handle.
+                            if (turnClock.expired || options.abortSignal?.aborted) {
+                                wasAborted = true;
+                            }
+                            else {
+                                logger.error("[GoogleAIStudio] Native SDK error", turnFailure);
+                                throw this.handleProviderError(turnFailure);
+                            }
+                        }
+                        if (engineResult) {
+                            totalInputTokens += engineResult.usage.inputTokens;
+                            totalOutputTokens += engineResult.usage.outputTokens;
+                            totalCacheReadTokens += engineResult.usage.cacheReadTokens ?? 0;
+                            totalReasoningTokens += engineResult.usage.reasoningTokens ?? 0;
+                            lastFinishReason =
+                                engineResult.rawStopReason ?? lastFinishReason;
+                            if (engineResult.aborted) {
+                                wasAborted = true;
+                            }
+                        }
+                        if (composedSignal.aborted) {
+                            wasAborted = true;
                         }
-                        await pump;
-                        totalInputTokens += engineResult.usage.inputTokens;
-                        totalOutputTokens += engineResult.usage.outputTokens;
-                        totalCacheReadTokens += engineResult.usage.cacheReadTokens ?? 0;
-                        totalReasoningTokens += engineResult.usage.reasoningTokens ?? 0;
                         // The turn produced a final answer when the model stopped
                         // calling tools of its own accord, rather than being cut off at
                         // the cap.
-                        const completedWithFinalAnswer = engineResult.toolCalls.length === 0 ||
-                            engineResult.finishReason !== "tool-calls";
+                        const completedWithFinalAnswer = engineResult !== undefined &&
+                            (engineResult.toolCalls.length === 0 ||
+                                engineResult.finishReason !== "tool-calls");
                         // Handle max-steps termination: if the model was still calling
                         // tools when we hit the limit, push a synthetic final message.
-                        const hitStepLimitWithoutFinalAnswer = step >= maxSteps && !completedWithFinalAnswer;
+                        // An aborted turn is NOT a step-cap turn — a killed 3-step turn
+                        // claiming it "reached the 200-step limit" is the exact
+                        // mislabeling this loop is being fixed for.
+                        const hitStepLimitWithoutFinalAnswer = !wasAborted && step >= maxSteps && !completedWithFinalAnswer;
                         if (hitStepLimitWithoutFinalAnswer) {
                             const fallback = handleMaxStepsTermination("[GoogleAIStudio]", step, maxSteps, "", // finalText is empty — model didn't stop on its own
                             lastStepText);
@@ -893,10 +1024,57 @@ export class GoogleAIStudioProvider extends BaseProvider {
                                 channel.push({ content: fallback });
                             }
                         }
+                        else if (wasAborted && !completedWithFinalAnswer) {
+                            // Exactly one honest terminal chunk, matching the actual exit
+                            // cause, and only when the consumer has not already been given
+                            // the model's own prose.
+                            logger.warn(`[GoogleAIStudio] Tool call loop ended mid-turn ` +
+                                `(${hitTimeLimit() ? "turn time limit" : turnClock.stalled ? "stall watchdog" : "caller abort"}); ` +
+                                `returning an honest terminal message.`);
+                            channel.push({
+                                content: buildLoopExitMessage({
+                                    timedOut: hitTimeLimit(),
+                                    stalled: turnClock.stalled,
+                                    elapsedMs: turnClock.elapsedMs(),
+                                    wasAborted,
+                                    ...(options.stallTimeoutMs !== undefined
+                                        ? { stallTimeoutMs: options.stallTimeoutMs }
+                                        : {}),
+                                    maxSteps,
+                                    toolCallCount: allToolCalls.length,
+                                }),
+                            });
+                        }
                         const responseTime = Date.now() - startTime;
+                        // Turn-exit discriminator, independent of the provider-shaped
+                        // finishReason — consumers branch on this instead of sniffing
+                        // strings. It reports only conditions this loop can actually
+                        // observe: it never claims a context-cap, because the reclaim
+                        // planner here has no stop-the-turn branch to report.
+                        const stopReason = resolveTurnStopReason({
+                            timedOut: hitTimeLimit(),
+                            stalled: turnClock.stalled,
+                            wasAborted,
+                            cappedWithoutAnswer: hitStepLimitWithoutFinalAnswer,
+                            finishReason: mapGeminiFinishReason(lastFinishReason),
+                        });
+                        if (stopReason !== "completed") {
+                            this.emitTurnEvent({
+                                phase: stopReason,
+                                step: stepsTaken,
+                                maxSteps,
+                                toolCallCount: allToolCalls.length,
+                                elapsedMs: turnClock.elapsedMs(),
+                            });
+                        }
                         // Update shared metadata so the returned object reflects final values.
                         metadata.responseTime = responseTime;
                         metadata.totalToolExecutions = allToolCalls.length;
+                        metadata.stopReason = stopReason;
+                        metadata.stepsUsed = stepsTaken;
+                        if (lastFinishReason !== undefined) {
+                            metadata.rawFinishReason = lastFinishReason;
+                        }
                         // Set token usage and finish reason on the span
                         span.setAttribute(ATTR.GEN_AI_INPUT_TOKENS, totalInputTokens);
                         span.setAttribute(ATTR.GEN_AI_OUTPUT_TOKENS, totalOutputTokens);
@@ -929,6 +1107,16 @@ export class GoogleAIStudioProvider extends BaseProvider {
                             },
                             requestDuration: responseTime,
                             timestamp: new Date().toISOString(),
+                            // Turn-lifecycle telemetry. The generate path gets these for
+                            // free because createAnalytics reads them off the result;
+                            // this path settles its own analytics, so they are set here.
+                            stepsUsed: stepsTaken,
+                            toolCallCount: allToolCalls.length,
+                            stopReason,
+                            elapsedMs: turnClock.elapsedMs(),
+                            ...(lastFinishReason !== undefined
+                                ? { rawFinishReason: lastFinishReason }
+                                : {}),
                         });
                         channel.close();
                     }
@@ -937,6 +1125,8 @@ export class GoogleAIStudioProvider extends BaseProvider {
                         analyticsReject(err);
                     }
                     finally {
+                        turnClock.dispose();
+                        upstreamSignal?.removeEventListener("abort", onUpstreamAbort);
                         timeoutController?.cleanup();
                     }
                 })();
@@ -990,6 +1180,10 @@ export class GoogleAIStudioProvider extends BaseProvider {
             const startTime = Date.now();
             const timeout = this.getTimeout(options);
             const timeoutController = createTimeoutController(timeout, this.providerName, "generate");
+            // Declared out here so the finally below can release the watchdog
+            // timers and the caller-signal listener on every exit, including the
+            // throws inside the try that never reach the clock's own scope.
+            let releaseTurnResources = () => { };
             try {
                 const apiKey = this.getApiKey();
                 const client = await createGoogleGenAIClient(apiKey, this.getBaseURL());
@@ -1064,7 +1258,44 @@ export class GoogleAIStudioProvider extends BaseProvider {
                     wantsJsonOutput: wantsNativeJson,
                     responseSchema: nativeResponseSchema,
                 }, toolsConfig);
-                const composedSignal = composeAbortSignals(options.abortSignal, timeoutController?.controller.signal);
+                // Abort fan-in — see the streaming twin for why the turn clock
+                // drives an internal controller rather than composing a third
+                // signal at each call site.
+                const upstreamSignal = composeAbortSignals(options.abortSignal, timeoutController?.controller.signal);
+                const internalAbort = new AbortController();
+                const onUpstreamAbort = () => internalAbort.abort();
+                upstreamSignal?.addEventListener("abort", onUpstreamAbort);
+                if (upstreamSignal?.aborted) {
+                    internalAbort.abort();
+                }
+                const toolExecTimeoutMs = resolveToolTimeoutMs(options.toolTimeoutMs);
+                // No `defaultTurnTimeoutMs`: the pre-existing whole-turn bound on
+                // this path is `timeoutController`, and `hitTimeLimit()` reads it,
+                // so no new default deadline is introduced by arming the clock.
+                const turnClock = createTurnClock({
+                    ...(options.turnTimeoutMs !== undefined
+                        ? { turnTimeoutMs: options.turnTimeoutMs }
+                        : {}),
+                    ...(options.stallTimeoutMs !== undefined
+                        ? { stallTimeoutMs: options.stallTimeoutMs }
+                        : {}),
+                    ...(options.wrapupTimeLeadMs !== undefined
+                        ? { wrapupTimeLeadMs: options.wrapupTimeLeadMs }
+                        : {}),
+                    onDeadline: (kind) => {
+                        logger.warn(kind === "timeout"
+                            ? `[GoogleAIStudio] Native Gemini generate turn exceeded its ${options.turnTimeoutMs}ms time budget — aborting`
+                            : `[GoogleAIStudio] Native Gemini generate turn made no progress for ${options.stallTimeoutMs}ms — aborting`);
+                        internalAbort.abort();
+                    },
+                });
+                const composedSignal = internalAbort.signal;
+                releaseTurnResources = () => {
+                    turnClock.dispose();
+                    upstreamSignal?.removeEventListener("abort", onUpstreamAbort);
+                };
+                const hitTimeLimit = () => turnClock.timedOut ||
+                    timeoutController?.controller.signal.aborted === true;
                 const maxSteps = computeMaxSteps(options.maxSteps);
                 let finalText = "";
                 let lastStepText = "";
@@ -1075,6 +1306,11 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 const allToolCalls = [];
                 const toolExecutions = [];
                 let step = 0;
+                // Model calls made — see the streaming twin for why this is not
+                // `step`.
+                let stepsTaken = 0;
+                let wasAborted = false;
+                let lastFinishReason;
                 // Cheap reclaim trigger — see the stream twin.
                 const contextGuard = createContextGuard(getContextWindowSize("googleAiStudio", modelName));
                 // Agentic loop for tool calling
@@ -1087,16 +1323,27 @@ export class GoogleAIStudioProvider extends BaseProvider {
                     maxSteps,
                     toolFailureBreaker: { maxRetries: DEFAULT_TOOL_MAX_RETRIES },
                     liveTools: options.tools ?? {},
+                    toolGuards: {
+                        toolTimeoutMs: toolExecTimeoutMs,
+                        abortSignal: composedSignal,
+                        onProgress: () => turnClock.noteProgress(),
+                    },
                     ...(declarationsResult ? { declarations: declarationsResult } : {}),
                     buildRequest: (contents) => ({
                         model: modelName,
                         contents,
                         config,
-                        ...(composedSignal
-                            ? { httpOptions: { signal: composedSignal } }
-                            : {}),
                     }),
-                    sendStep: async (request) => client.models.generateContentStream(request),
+                    // See the streaming twin: `config.abortSignal` is the only
+                    // cancellation channel the SDK reads.
+                    sendStep: async (request, signal) => {
+                        turnClock.noteProgress();
+                        const built = request;
+                        return client.models.generateContentStream({
+                            ...built,
+                            config: { ...(built.config ?? {}), abortSignal: signal },
+                        });
+                    },
                     noteUsage: (inputTokens, outputTokens) => {
                         contextGuard.noteUsage(inputTokens, outputTokens);
                     },
@@ -1114,6 +1361,13 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 });
                 const adapter = {
                     ...baseAdapter,
+                    // Once per model call, including the final text-only step — see
+                    // the streaming twin.
+                    buildStepRequest: (contents, engineStep) => {
+                        stepsTaken = engineStep + 1;
+                        turnClock.noteProgress();
+                        return baseAdapter.buildStepRequest(contents, engineStep);
+                    },
                     buildToolResultMessages: (contents, stepResult, toolResults, engineStep) => {
                         // Same as the streaming twin: the engine's step, not a count of
                         // hook invocations. See the comment there.
@@ -1153,6 +1407,13 @@ export class GoogleAIStudioProvider extends BaseProvider {
                             });
                         }
                         const next = baseAdapter.buildToolResultMessages(contents, stepResult, toolResults, engineStep);
+                        // Wrap-up nudge — see the streaming twin.
+                        if (turnClock.shouldNudgeWrapup()) {
+                            const last = next[next.length - 1];
+                            if (last && Array.isArray(last.parts)) {
+                                last.parts.push({ text: buildWrapupNudgeText(false) });
+                            }
+                        }
                         try {
                             const appended = next[next.length - 1];
                             contextGuard.noteAppendedChars(JSON.stringify(appended?.parts ?? []).length);
@@ -1164,40 +1425,102 @@ export class GoogleAIStudioProvider extends BaseProvider {
                     },
                 };
                 // Same dedup routing as the streaming twin above.
-                const engineTools = buildDedupedEngineTools(declarationsResult, options.tools);
+                const engineTools = buildDedupedEngineTools(declarationsResult, options.tools, {
+                    toolTimeoutMs: toolExecTimeoutMs,
+                    abortSignal: composedSignal,
+                    onProgress: () => turnClock.noteProgress(),
+                });
                 const { stream: engineStream, resultPromise } = runAgenticLoop(adapter, currentContents, {
                     tools: engineTools,
-                    ...(composedSignal ? { abortSignal: composedSignal } : {}),
-                    // This loop guards no executor of its own — see the streaming
-                    // path above for why the engine's bound has to be reachable.
-                    ...(options.toolTimeoutMs !== undefined
-                        ? { toolTimeoutMs: options.toolTimeoutMs }
-                        : {}),
+                    abortSignal: composedSignal,
+                    toolTimeoutMs: toolExecTimeoutMs,
                 });
                 // Drained, not consumed: nothing streams out of generate(), but an
                 // undrained channel would stall the engine mid-turn.
                 const drain = (async () => {
                     for await (const chunk of engineStream) {
                         void chunk;
+                        turnClock.noteProgress();
                     }
                 })();
                 let engineResult;
+                let turnFailure;
                 try {
                     engineResult = await resultPromise;
                 }
                 catch (error) {
-                    await drainDetachedPump(drain, "GoogleAIStudio");
-                    logger.error("[GoogleAIStudio] Native SDK generate error", error);
-                    throw this.handleProviderError(error);
+                    turnFailure = error;
+                }
+                await drainDetachedPump(drain, "GoogleAIStudio");
+                if (turnFailure !== undefined) {
+                    // Same split as the streaming twin: a blown time budget or a
+                    // caller abort ends the turn honestly, a provider failure still
+                    // throws.
+                    if (turnClock.expired || options.abortSignal?.aborted) {
+                        wasAborted = true;
+                    }
+                    else {
+                        logger.error("[GoogleAIStudio] Native SDK generate error", turnFailure);
+                        throw this.handleProviderError(turnFailure);
+                    }
+                }
+                if (engineResult) {
+                    totalInputTokens += engineResult.usage.inputTokens;
+                    totalOutputTokens += engineResult.usage.outputTokens;
+                    totalCacheReadTokens += engineResult.usage.cacheReadTokens ?? 0;
+                    totalReasoningTokens += engineResult.usage.reasoningTokens ?? 0;
+                    lastFinishReason = engineResult.rawStopReason ?? lastFinishReason;
+                    finalText = engineResult.text;
+                    if (engineResult.aborted) {
+                        wasAborted = true;
+                    }
+                }
+                if (composedSignal.aborted) {
+                    wasAborted = true;
+                }
+                const hitStepLimitWithoutAnswer = !wasAborted && step >= maxSteps && !finalText;
+                if (wasAborted && !finalText) {
+                    // Never the step-cap text for a turn the budget killed: prefer
+                    // the prose the model already produced, else an honest message
+                    // naming the actual exit cause.
+                    logger.warn(`[GoogleAIStudio] Generate tool call loop ended mid-turn ` +
+                        `(${hitTimeLimit() ? "turn time limit" : turnClock.stalled ? "stall watchdog" : "caller abort"}); ` +
+                        `returning gathered text or an honest terminal message.`);
+                    finalText =
+                        lastStepText ||
+                            buildLoopExitMessage({
+                                timedOut: hitTimeLimit(),
+                                stalled: turnClock.stalled,
+                                elapsedMs: turnClock.elapsedMs(),
+                                wasAborted,
+                                ...(options.stallTimeoutMs !== undefined
+                                    ? { stallTimeoutMs: options.stallTimeoutMs }
+                                    : {}),
+                                maxSteps,
+                                toolCallCount: allToolCalls.length,
+                            });
+                }
+                else {
+                    finalText = handleMaxStepsTermination("[GoogleAIStudio]", step, maxSteps, finalText, lastStepText);
                 }
-                await drain;
-                totalInputTokens += engineResult.usage.inputTokens;
-                totalOutputTokens += engineResult.usage.outputTokens;
-                totalCacheReadTokens += engineResult.usage.cacheReadTokens ?? 0;
-                totalReasoningTokens += engineResult.usage.reasoningTokens ?? 0;
-                finalText = engineResult.text;
-                finalText = handleMaxStepsTermination("[GoogleAIStudio]", step, maxSteps, finalText, lastStepText);
                 const responseTime = Date.now() - startTime;
+                // Turn-exit discriminator — see the streaming twin.
+                const stopReason = resolveTurnStopReason({
+                    timedOut: hitTimeLimit(),
+                    stalled: turnClock.stalled,
+                    wasAborted,
+                    cappedWithoutAnswer: hitStepLimitWithoutAnswer,
+                    finishReason: mapGeminiFinishReason(lastFinishReason),
+                });
+                if (stopReason !== "completed") {
+                    this.emitTurnEvent({
+                        phase: stopReason,
+                        step: stepsTaken,
+                        maxSteps,
+                        toolCallCount: allToolCalls.length,
+                        elapsedMs: turnClock.elapsedMs(),
+                    });
+                }
                 // Set token usage and finish reason on the span
                 span.setAttribute(ATTR.GEN_AI_INPUT_TOKENS, totalInputTokens);
                 span.setAttribute(ATTR.GEN_AI_OUTPUT_TOKENS, totalOutputTokens);
@@ -1214,6 +1537,14 @@ export class GoogleAIStudioProvider extends BaseProvider {
                     content: finalText,
                     provider: this.providerName,
                     model: modelName,
+                    // createAnalytics reads these off the result, so setting them
+                    // here is also what puts stepsUsed / stopReason / elapsedMs /
+                    // rawFinishReason on `result.analytics`.
+                    stopReason,
+                    stepsUsed: stepsTaken,
+                    ...(lastFinishReason !== undefined
+                        ? { rawFinishReason: lastFinishReason }
+                        : {}),
                     usage: {
                         input: adjustedInputTokens,
                         // Thinking tokens are billed at the output rate but Gemini
@@ -1243,6 +1574,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 return this.enhanceResult(baseResult, options, startTime);
             }
             finally {
+                releaseTurnResources();
                 timeoutController?.cleanup();
             }
         });