@vybestack/llxprt-code-agents 0.10.0-nightly.260613.1adad3b34

package/dist/src/core/StreamProcessor.js

@@ -0,0 +1,660 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FinishReason, } from '@google/genai';
+import { isRetryableError, retryWithBackoff, } from '@vybestack/llxprt-code-core/utils/retry.js';
+import { prependAsyncGenerator } from '@vybestack/llxprt-code-core/utils/asyncIterator.js';
+// @plan:PLAN-20260608-ISSUE1586.P15 — auth types from auth package
+import { flushRuntimeAuthScope } from '@vybestack/llxprt-code-auth';
+import { isFunctionResponse } from '@vybestack/llxprt-code-core/utils/messageInspectors.js';
+import { DebugLogger } from '@vybestack/llxprt-code-core/debug/index.js';
+import { ContentConverters } from '@vybestack/llxprt-code-core/services/history/ContentConverters.js';
+import { isValidResponse, isValidNonThoughtTextPart, convertIContentToResponse, } from './MessageConverter.js';
+import { logApiRequest, logApiResponse, logApiError } from './turnLogging.js';
+import { InvalidStreamError, EmptyStreamError, isSchemaDepthError, isThoughtPart, } from '@vybestack/llxprt-code-core/core/chatSessionTypes.js';
+import { analyzeResponseOutcome } from '@vybestack/llxprt-code-core/utils/generateContentResponseUtilities.js';
+import { hasCycleInSchema } from '@vybestack/llxprt-code-tools';
+import { isStructuredError } from '@vybestack/llxprt-code-core/utils/quotaErrorDetection.js';
+import { AgentExecutionStoppedError, AgentExecutionBlockedError, } from './chatSession.js';
+import { attachHookRestrictedAllowedTools, filterHookRestrictedContent, filterHookRestrictedFunctionCalls, filterHookRestrictedParts, getHookRestrictedAllowedTools, getHookRestrictedFunctionCallsFromParts, mergeHookRestrictedFunctionCalls, } from './hookToolRestrictions.js';
+import { canonicalizeToolName } from './toolGovernance.js';
+function isMissingFinishReason(finishReason) {
+    return finishReason == null || finishReason === '';
+}
+export class StreamProcessor {
+    runtimeContext;
+    conversationManager;
+    compressionHandler;
+    providerResolver;
+    providerRuntimeBuilder;
+    historyService;
+    generationConfig;
+    logger = new DebugLogger('llxprt:gemini:stream-processor');
+    constructor(runtimeContext, conversationManager, compressionHandler, providerResolver, providerRuntimeBuilder, historyService, generationConfig) {
+        this.runtimeContext = runtimeContext;
+        this.conversationManager = conversationManager;
+        this.compressionHandler = compressionHandler;
+        this.providerResolver = providerResolver;
+        this.providerRuntimeBuilder = providerRuntimeBuilder;
+        this.historyService = historyService;
+        this.generationConfig = generationConfig;
+    }
+    /**
+     * Makes an API call with retry and returns a stream processor.
+     * This is the outer method that resolves the provider, enforces context window,
+     * makes the API call with retry, and returns processStreamResponse.
+     */
+    async makeApiCallAndProcessStream(params, promptId, pendingTokens, userContent) {
+        const provider = this.providerResolver('stream');
+        const providerBaseUrl = this.runtimeContext.state.baseUrl;
+        this.logger.debug(() => '[StreamProcessor] Active provider snapshot before stream request', {
+            providerName: provider.name,
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- Preserve defensive runtime boundary guard despite current static types.
+            providerDefaultModel: provider.getDefaultModel?.(),
+            configModel: this.runtimeContext.state.model,
+            baseUrl: providerBaseUrl,
+        });
+        // Enforce context window limits before proceeding
+        await this.compressionHandler.enforceContextWindow(pendingTokens, promptId, provider);
+        // Check if provider supports IContent interface
+        if (typeof provider.generateChatCompletion !== 'function') {
+            throw new Error(`Provider ${provider.name} does not support IContent interface`);
+        }
+        const streamResponse = await this._executeStreamApiCall(params, promptId, userContent, provider);
+        return this._createCancellableStream(streamResponse, userContent);
+    }
+    _createCancellableStream(streamResponse, userContent) {
+        let processedStream;
+        const ensureProcessedStream = () => {
+            processedStream ??= this.processStreamResponse(streamResponse, userContent);
+            return processedStream;
+        };
+        const cancellableStream = {
+            async next(value) {
+                return ensureProcessedStream().next(value);
+            },
+            async return(value) {
+                if (processedStream) {
+                    return typeof processedStream.return === 'function'
+                        ? processedStream.return(value)
+                        : { done: true, value: undefined };
+                }
+                if (typeof streamResponse.return === 'function') {
+                    await streamResponse.return(value);
+                }
+                return { done: true, value: undefined };
+            },
+            async throw(error) {
+                if (processedStream) {
+                    if (typeof processedStream.throw === 'function') {
+                        return processedStream.throw(error);
+                    }
+                    throw error;
+                }
+                if (typeof streamResponse.throw === 'function') {
+                    return streamResponse.throw(error);
+                }
+                if (typeof streamResponse.return === 'function') {
+                    await streamResponse.return(undefined);
+                }
+                throw error;
+            },
+            [Symbol.asyncIterator]() {
+                return this;
+            },
+        };
+        return cancellableStream;
+    }
+    /**
+     * Execute the stream API call with retry and bucket failover.
+     * Split from makeApiCallAndProcessStream to keep methods under 80 lines.
+     */
+    async _executeStreamApiCall(params, promptId, userContent, provider) {
+        const apiCall = () => this._buildAndSendStreamRequest(params, promptId, userContent, provider);
+        const retryFetchErrors = params.config?.retryFetchErrors;
+        return retryWithBackoff(apiCall, {
+            onPersistent429: () => this._handleBucketFailover(),
+            signal: params.config?.abortSignal,
+            retryFetchErrors,
+            shouldRetryOnError: (error, currentRetryFetchErrors) => error instanceof EmptyStreamError ||
+                isRetryableError(error, currentRetryFetchErrors),
+        });
+    }
+    async _buildAndSendStreamRequest(params, promptId, userContent, provider) {
+        const requestContents = this._buildRequestContents(userContent);
+        const configForHooks = this.runtimeContext.providerRuntime.config;
+        const requestTools = this._selectRequestTools(params);
+        const toolSelection = await this._applyToolSelectionHook(configForHooks, requestTools);
+        const tools = toolSelection.tools;
+        const { requestPayload, baseRuntimeContext, runtimeContext } = this._prepareRequestPayload(requestContents, tools, params);
+        const finalContents = await this._fireBeforeModelHook(configForHooks, requestPayload.contents, tools, toolSelection.allowedFunctionNames);
+        requestPayload.contents = finalContents;
+        logApiRequest(this.runtimeContext, this.runtimeContext.state, ContentConverters.toGeminiContents(requestPayload.contents), this.runtimeContext.state.model, promptId);
+        return this._sendProviderRequest(provider, requestPayload, runtimeContext, baseRuntimeContext, params, promptId, toolSelection.allowedFunctionNames);
+    }
+    /**
+     * Fire BeforeModel hook and return possibly-modified requestContents.
+     * Throws if the hook requests execution stop or blocking.
+     */
+    async _fireBeforeModelHook(configForHooks, requestContents, tools, hookRestrictedAllowedTools) {
+        if (configForHooks === undefined ||
+            typeof configForHooks.getEnableHooks !== 'function' ||
+            configForHooks.getEnableHooks() !== true) {
+            return requestContents;
+        }
+        const hookSystem = typeof configForHooks.getHookSystem === 'function'
+            ? configForHooks.getHookSystem()
+            : undefined;
+        if (hookSystem === undefined)
+            return requestContents;
+        await hookSystem.initialize();
+        const beforeModelResult = await hookSystem.fireBeforeModelEvent({
+            contents: requestContents,
+            tools,
+        });
+        if (beforeModelResult?.shouldStopExecution() === true) {
+            const reason = beforeModelResult.getEffectiveReason();
+            throw new AgentExecutionStoppedError(reason !== undefined && reason !== null && reason !== ''
+                ? reason
+                : 'Execution stopped by BeforeModel hook', beforeModelResult.systemMessage);
+        }
+        if (beforeModelResult?.isBlockingDecision() === true) {
+            let syntheticResponse = beforeModelResult.getSyntheticResponse();
+            // eslint-disable-next-line sonarjs/nested-control-flow -- Existing structure is intentionally preserved; refactoring this boundary is outside the lint slice.
+            if (syntheticResponse) {
+                const candidate = syntheticResponse.candidates?.[0];
+                const candidateFinishReason = candidate?.finishReason;
+                if (candidate && isMissingFinishReason(candidateFinishReason)) {
+                    syntheticResponse = this._patchMissingFinishReason(syntheticResponse, candidate);
+                }
+            }
+            const reason = beforeModelResult.getEffectiveReason();
+            throw new AgentExecutionBlockedError(reason !== undefined && reason !== null && reason !== ''
+                ? reason
+                : 'Request blocked by BeforeModel hook', syntheticResponse === undefined
+                ? undefined
+                : attachHookRestrictedAllowedTools(syntheticResponse, hookRestrictedAllowedTools));
+        }
+        return this._applyRequestModifications(beforeModelResult, requestContents);
+    }
+    _patchMissingFinishReason(syntheticResponse, candidate) {
+        return {
+            ...syntheticResponse,
+            candidates: [{ ...candidate, finishReason: FinishReason.STOP }],
+        };
+    }
+    _applyRequestModifications(beforeModelResult, requestContents) {
+        if (!beforeModelResult)
+            return requestContents;
+        const modifiedRequest = beforeModelResult.applyLLMRequestModifications({
+            model: this.runtimeContext.state.model || '',
+            contents: ContentConverters.toGeminiContents(requestContents),
+        });
+        const modifiedContents = modifiedRequest.contents;
+        if (modifiedContents !== undefined && modifiedContents !== null) {
+            return ContentConverters.toIContents(modifiedContents);
+        }
+        return requestContents;
+    }
+    _prepareRequestPayload(requestContents, tools, params) {
+        this.logger.debug(() => '[StreamProcessor] Calling provider.generateChatCompletion', {
+            providerName: this.providerResolver('stream').name,
+            model: this.runtimeContext.state.model,
+            historyLength: requestContents.length,
+            toolCount: tools?.length ?? 0,
+            baseUrl: this.runtimeContext.state.baseUrl,
+        });
+        const baseRuntimeContext = this.providerRuntimeBuilder('StreamProcessor.generateRequest', { historyLength: requestContents.length });
+        const requestPayload = { contents: requestContents, tools };
+        const runtimeContext = this._buildRuntimeContext(baseRuntimeContext, params, tools);
+        return { requestPayload, baseRuntimeContext, runtimeContext };
+    }
+    _buildRuntimeContext(baseRuntimeContext, params, tools) {
+        if (!params.config)
+            return baseRuntimeContext;
+        return {
+            ...baseRuntimeContext,
+            config: { ...baseRuntimeContext.config, ...params.config, tools },
+        };
+    }
+    async _sendProviderRequest(provider, requestPayload, runtimeContext, baseRuntimeContext, params, promptId, hookRestrictedAllowedTools) {
+        const startTime = Date.now();
+        try {
+            const streamResponse = provider.generateChatCompletion({
+                contents: requestPayload.contents,
+                tools: requestPayload.tools,
+                config: runtimeContext.config,
+                runtime: runtimeContext,
+                settings: runtimeContext.settingsService,
+                metadata: {
+                    ...runtimeContext.metadata,
+                    abortSignal: params.config?.abortSignal,
+                },
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- Preserve defensive runtime boundary guard despite current static types.
+                userMemory: baseRuntimeContext.config?.getUserMemory?.(),
+            });
+            return await this._consumeFirstChunkAndReturn(streamResponse, requestPayload, promptId, startTime, hookRestrictedAllowedTools);
+        }
+        catch (error) {
+            const durationMs = Date.now() - startTime;
+            logApiError(this.runtimeContext, this.runtimeContext.state, this.runtimeContext.state.model, promptId, durationMs, error);
+            throw error;
+        }
+    }
+    /**
+     * Eagerly consume first chunk within retry boundary (#1750).
+     */
+    async _consumeFirstChunkAndReturn(streamResponse, requestPayload, promptId, startTime, hookRestrictedAllowedTools) {
+        const convertedStream = this._convertIContentStream(streamResponse, requestPayload, { promptId, startTime }, hookRestrictedAllowedTools);
+        const firstChunk = await convertedStream.next();
+        if (firstChunk.done === true) {
+            throw new EmptyStreamError('Model stream ended immediately with no content.');
+        }
+        return prependAsyncGenerator(firstChunk.value, convertedStream);
+    }
+    _selectRequestTools(params) {
+        return params.config?.tools ?? this.generationConfig.tools;
+    }
+    async _applyToolSelectionHook(configForHooks, tools) {
+        if (configForHooks === undefined) {
+            return { tools, allowedFunctionNames: undefined };
+        }
+        const getToolSelectionHooksEnabled = configForHooks.getEnableHooks;
+        if (typeof getToolSelectionHooksEnabled !== 'function' ||
+            getToolSelectionHooksEnabled.call(configForHooks) !== true) {
+            return { tools, allowedFunctionNames: undefined };
+        }
+        const getToolSelectionHookSystem = configForHooks.getHookSystem;
+        const hookSystem = typeof getToolSelectionHookSystem === 'function'
+            ? getToolSelectionHookSystem.call(configForHooks)
+            : undefined;
+        if (hookSystem === undefined) {
+            return { tools, allowedFunctionNames: undefined };
+        }
+        await hookSystem.initialize();
+        const toolsFromConfig = Array.isArray(tools)
+            ? tools
+            : [];
+        const toolSelectionResult = await hookSystem.fireBeforeToolSelectionEvent(toolsFromConfig);
+        const modifiedConfig = toolSelectionResult?.applyToolConfigModifications({
+            tools: toolsFromConfig,
+        });
+        const toolConfig = modifiedConfig?.toolConfig;
+        if (
+        // eslint-disable-next-line sonarjs/expression-complexity -- Existing structure is intentionally preserved; refactoring this boundary is outside the lint slice.
+        toolConfig !== undefined &&
+            toolConfig !== null &&
+            typeof toolConfig === 'object' &&
+            'allowedFunctionNames' in toolConfig &&
+            Array.isArray(toolConfig.allowedFunctionNames)) {
+            const allowedFunctions = toolConfig.allowedFunctionNames;
+            const allowedNames = new Set(allowedFunctions.map(canonicalizeToolName));
+            const filteredTools = toolsFromConfig
+                .map((toolGroup) => ({
+                ...toolGroup,
+                functionDeclarations: Array.isArray(toolGroup.functionDeclarations)
+                    ? toolGroup.functionDeclarations.filter((fn) => typeof fn.name === 'string' &&
+                        allowedNames.has(canonicalizeToolName(fn.name)))
+                    : [],
+            }))
+                .filter((g) => g.functionDeclarations.length > 0);
+            return { tools: filteredTools, allowedFunctionNames: allowedFunctions };
+        }
+        return { tools: toolsFromConfig, allowedFunctionNames: undefined };
+    }
+    _buildRequestContents(userContent) {
+        const matcher = this.conversationManager.makePositionMatcher();
+        if (Array.isArray(userContent)) {
+            const userIContents = userContent.map((content) => {
+                const turnKey = this.historyService.generateTurnKey();
+                const idGen = this.historyService.getIdGeneratorCallback(turnKey);
+                return ContentConverters.toIContent(content, idGen, matcher, turnKey);
+            });
+            return this.historyService.getCuratedForProvider(userIContents);
+        }
+        const turnKey = this.historyService.generateTurnKey();
+        const idGen = this.historyService.getIdGeneratorCallback(turnKey);
+        const userIContent = ContentConverters.toIContent(userContent, idGen, matcher, turnKey);
+        return this.historyService.getCuratedForProvider([userIContent]);
+    }
+    async _handleBucketFailover() {
+        const failoverHandler = this.runtimeContext.providerRuntime.config?.getBucketFailoverHandler();
+        if (!failoverHandler)
+            return null;
+        this.logger.debug(() => 'Attempting bucket failover on persistent 429');
+        const success = await failoverHandler.tryFailover();
+        if (success) {
+            const runtimeId = this.runtimeContext.providerRuntime.runtimeId ??
+                this.runtimeContext.state.runtimeId;
+            if (typeof runtimeId === 'string' && runtimeId.trim() !== '') {
+                flushRuntimeAuthScope(runtimeId);
+            }
+            this.logger.debug(() => `Bucket failover successful, new bucket: ${failoverHandler.getCurrentBucket()}`);
+            return true;
+        }
+        this.logger.debug(() => 'Bucket failover failed - no more buckets available');
+        return false;
+    }
+    /**
+     * Convert IContent stream to GenerateContentResponse stream.
+     * Tracks token usage metadata from IContent format.
+     * Triggers AfterModel hook per streamed chunk.
+     */
+    async *_convertIContentStream(streamResponse, llmRequest, telemetryContext, hookRestrictedAllowedTools) {
+        let lastConvertedChunk;
+        for await (const iContent of streamResponse) {
+            this._trackPromptTokens(iContent);
+            const convertedChunk = attachHookRestrictedAllowedTools(convertIContentToResponse(iContent), hookRestrictedAllowedTools);
+            lastConvertedChunk = convertedChunk;
+            const hookResult = await this._processAfterModelHook(iContent, llmRequest, convertedChunk, hookRestrictedAllowedTools);
+            if (hookResult.type === 'modified') {
+                const restrictedResponse = attachHookRestrictedAllowedTools(hookResult.response, hookRestrictedAllowedTools);
+                lastConvertedChunk = restrictedResponse;
+                yield restrictedResponse;
+                continue;
+            }
+            yield convertedChunk;
+        }
+        this._logTelemetry(telemetryContext, lastConvertedChunk);
+    }
+    _trackPromptTokens(iContent) {
+        const promptTokens = iContent.metadata?.usage?.promptTokens;
+        if (promptTokens === undefined)
+            return;
+        const cacheReads = iContent.metadata?.usage?.cache_read_input_tokens ?? 0;
+        const cacheWrites = iContent.metadata?.usage?.cache_creation_input_tokens ?? 0;
+        const combinedPromptTokens = promptTokens + cacheReads + cacheWrites;
+        this.logger.debug(() => `[StreamProcessor] Tracking promptTokens from IContent: ${combinedPromptTokens}`);
+        this.compressionHandler.lastPromptTokenCount = combinedPromptTokens;
+    }
+    async _processAfterModelHook(iContent, llmRequest, convertedChunk, hookRestrictedAllowedTools) {
+        const hookConfig = this.runtimeContext.providerRuntime.config;
+        if (hookConfig === undefined ||
+            typeof hookConfig.getEnableHooks !== 'function' ||
+            hookConfig.getEnableHooks() !== true) {
+            return { type: 'passthrough' };
+        }
+        const hookSystem = typeof hookConfig.getHookSystem === 'function'
+            ? hookConfig.getHookSystem()
+            : undefined;
+        if (hookSystem === undefined)
+            return { type: 'passthrough' };
+        // eslint-disable-next-line sonarjs/nested-control-flow -- Existing structure is intentionally preserved; refactoring this boundary is outside the lint slice.
+        if (!hookSystem.isInitialized()) {
+            await hookSystem.initialize();
+        }
+        const filteredContent = filterHookRestrictedContent(convertIContentToResponse(iContent).candidates?.[0]?.content ?? {
+            role: 'model',
+            parts: [],
+        }, hookRestrictedAllowedTools);
+        const afterModelResult = await hookSystem.fireAfterModelEvent(llmRequest ?? {}, ContentConverters.toIContent(filteredContent));
+        // eslint-disable-next-line sonarjs/nested-control-flow -- Existing structure is intentionally preserved; refactoring this boundary is outside the lint slice.
+        if (afterModelResult?.shouldStopExecution() === true) {
+            const effectiveReason = afterModelResult.getEffectiveReason();
+            throw new AgentExecutionStoppedError(effectiveReason ?? 'Execution stopped by AfterModel hook', afterModelResult.systemMessage);
+        }
+        // eslint-disable-next-line sonarjs/nested-control-flow -- Existing structure is intentionally preserved; refactoring this boundary is outside the lint slice.
+        if (afterModelResult?.isBlockingDecision() === true) {
+            const modifiedResponse = afterModelResult.getModifiedResponse();
+            const syntheticResponse = attachHookRestrictedAllowedTools(modifiedResponse ?? convertedChunk, hookRestrictedAllowedTools);
+            const effectiveReason = afterModelResult.getEffectiveReason();
+            throw new AgentExecutionBlockedError(effectiveReason ?? 'Execution blocked by AfterModel hook', syntheticResponse, afterModelResult.systemMessage);
+        }
+        const modifiedResponse = afterModelResult?.getModifiedResponse();
+        // eslint-disable-next-line sonarjs/nested-control-flow -- Existing structure is intentionally preserved; refactoring this boundary is outside the lint slice.
+        if (modifiedResponse) {
+            return { type: 'modified', response: modifiedResponse };
+        }
+        return { type: 'passthrough' };
+    }
+    _logTelemetry(telemetryContext, lastConvertedChunk) {
+        if (telemetryContext && lastConvertedChunk) {
+            const durationMs = Date.now() - telemetryContext.startTime;
+            logApiResponse(this.runtimeContext, this.runtimeContext.state, this.runtimeContext.state.model, telemetryContext.promptId, durationMs, lastConvertedChunk.usageMetadata, JSON.stringify(lastConvertedChunk));
+        }
+    }
+    /**
+     * Process streaming response chunks into a complete conversation turn.
+     * Yields each chunk immediately as it arrives from the provider stream,
+     * while simultaneously tracking metadata for validation and history.
+     *
+     * CRITICAL: This method must yield chunks inline during the for-await loop.
+     * Collecting all chunks first (as was done in a prior refactoring) blocks
+     * the entire pipeline — no output reaches the user, no abort signal checks
+     * run, and stalled provider streams hang indefinitely. See #1846.
+     */
+    async *processStreamResponse(streamResponse, userInput) {
+        const acc = this._createStreamAccumulator();
+        const includeThoughts = this.runtimeContext.ephemerals.reasoning.includeInContext();
+        for await (const chunk of streamResponse) {
+            const filteredChunk = attachHookRestrictedAllowedTools(chunk, getHookRestrictedAllowedTools(chunk));
+            this._accumulateChunkMetadata(filteredChunk, acc, includeThoughts);
+            yield filteredChunk;
+        }
+        await this._finalizeStreamProcessing(acc, userInput);
+    }
+    _createStreamAccumulator() {
+        return {
+            modelResponseParts: [],
+            outcome: {
+                hasVisibleText: false,
+                hasThinking: false,
+                hasToolCalls: false,
+                isActionable: false,
+            },
+            finishReason: undefined,
+            allChunks: [],
+        };
+    }
+    _accumulateChunkMetadata(chunk, acc, includeThoughts) {
+        const candidateWithReason = chunk.candidates?.find((c) => c.finishReason !== undefined);
+        if (candidateWithReason !== undefined)
+            acc.finishReason = candidateWithReason.finishReason;
+        const allowedTools = getHookRestrictedAllowedTools(chunk);
+        const parts = chunk.candidates?.[0]?.content?.parts ?? [];
+        const effectiveParts = isValidResponse(chunk)
+            ? filterHookRestrictedParts(parts, allowedTools)
+            : [];
+        const allowedPartCalls = getHookRestrictedFunctionCallsFromParts(effectiveParts, allowedTools);
+        const allowedMergedCalls = mergeHookRestrictedFunctionCalls(allowedPartCalls, filterHookRestrictedFunctionCalls(chunk.functionCalls ?? [], allowedTools));
+        const allowedTopLevelCallParts = allowedMergedCalls
+            .slice(allowedPartCalls.length)
+            .map((functionCall) => ({ functionCall }));
+        const outcomeParts = [...effectiveParts, ...allowedTopLevelCallParts];
+        if (outcomeParts.length > 0) {
+            const chunkOutcome = analyzeResponseOutcome(outcomeParts);
+            acc.outcome = {
+                hasVisibleText: acc.outcome.hasVisibleText || chunkOutcome.hasVisibleText,
+                hasThinking: acc.outcome.hasThinking || chunkOutcome.hasThinking,
+                hasToolCalls: acc.outcome.hasToolCalls || chunkOutcome.hasToolCalls,
+                isActionable: acc.outcome.isActionable || chunkOutcome.isActionable,
+            };
+            acc.modelResponseParts.push(...(includeThoughts
+                ? outcomeParts
+                : outcomeParts.filter((p) => !isThoughtPart(p))));
+        }
+        const chunkText = typeof chunk.text === 'string' ? chunk.text : '';
+        this.logger.debug(() => `[stream:terminal] observed converted chunk`, {
+            chunkFinishReason: candidateWithReason?.finishReason,
+            partCount: effectiveParts.length,
+            toolCallCount: allowedMergedCalls.length,
+            textLength: chunkText.length,
+            hasUsageMetadata: Boolean(chunk.usageMetadata),
+        });
+        if (chunk.usageMetadata?.promptTokenCount !== undefined) {
+            const chunkUsage = chunk.usageMetadata;
+            this.compressionHandler.lastPromptTokenCount =
+                chunk.usageMetadata.promptTokenCount +
+                    (chunkUsage.cache_read_input_tokens ?? 0) +
+                    (chunkUsage.cache_creation_input_tokens ?? 0);
+        }
+        acc.allChunks.push(chunk);
+    }
+    async _finalizeStreamProcessing(acc, userInput) {
+        const consolidatedParts = this._consolidateTextParts(acc.modelResponseParts);
+        const responseText = this._extractResponseText(consolidatedParts);
+        if (isMissingFinishReason(acc.finishReason)) {
+            this.logger.debug(() => `[stream:terminal] stream ended without finishReason (hasToolCall=${String(acc.outcome.hasToolCalls)}, hasTextResponse=${String(acc.outcome.hasVisibleText)}, hasThinkingResponse=${String(acc.outcome.hasThinking)}, responseTextLength=${responseText.length})`);
+        }
+        else {
+            this.logger.debug(() => `[stream:terminal] finalized stream with finishReason`, {
+                finishReason: acc.finishReason,
+                hasToolCall: acc.outcome.hasToolCalls,
+                hasTextResponse: acc.outcome.hasVisibleText,
+                hasThinkingResponse: acc.outcome.hasThinking,
+                responseTextLength: responseText.length,
+                chunkCount: acc.allChunks.length,
+            });
+        }
+        this._validateStreamCompletion(userInput, acc.outcome, acc.finishReason, responseText);
+        await this._recordHistoryWithUsage(userInput, consolidatedParts, acc.allChunks);
+    }
+    /**
+     * Consolidate adjacent text parts.
+     */
+    _consolidateTextParts(modelResponseParts) {
+        const consolidatedParts = [];
+        for (const part of modelResponseParts) {
+            const lastPart = consolidatedParts[consolidatedParts.length - 1];
+            if (
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- Preserve defensive runtime boundary guard despite current static types.
+            lastPart?.text &&
+                isValidNonThoughtTextPart(lastPart) &&
+                isValidNonThoughtTextPart(part)) {
+                lastPart.text += part.text;
+            }
+            else {
+                consolidatedParts.push(part);
+            }
+        }
+        return consolidatedParts;
+    }
+    /**
+     * Extract response text from consolidated parts.
+     */
+    _extractResponseText(consolidatedParts) {
+        return consolidatedParts
+            .filter((part) => isValidNonThoughtTextPart(part))
+            .map((part) => part.text)
+            .join('')
+            .trim();
+    }
+    /**
+     * Validate stream completion and throw appropriate errors.
+     */
+    _validateStreamCompletion(userInput, outcome, finishReason, responseText) {
+        const isToolContinuationInput = Array.isArray(userInput)
+            ? userInput.some(isFunctionResponse)
+            : isFunctionResponse(userInput);
+        const validationContext = {
+            hasToolCall: outcome.hasToolCalls,
+            hasTextResponse: outcome.hasVisibleText,
+            hasThinkingResponse: outcome.hasThinking,
+            finishReason,
+            responseTextLength: responseText.length,
+            isToolContinuationInput,
+        };
+        this.logger.debug(() => `[stream:terminal] validating converted stream completion`, validationContext);
+        const hasMissingFinishAndNoText = isMissingFinishReason(finishReason) && !outcome.hasVisibleText;
+        const isEmptyResponse = responseText === '';
+        const noRelevantContent = !outcome.hasToolCalls && !isToolContinuationInput && !outcome.hasThinking;
+        const isInvalidResponse = noRelevantContent && (hasMissingFinishAndNoText || isEmptyResponse);
+        if (isInvalidResponse) {
+            this._throwMissingResponseError(finishReason, outcome.hasVisibleText, validationContext);
+        }
+        if (finishReason === FinishReason.MALFORMED_FUNCTION_CALL) {
+            this.logger.warn(() => `[stream:terminal] validation failed: malformed function call finishReason`, validationContext);
+            throw new InvalidStreamError('Model stream ended with malformed function call.', 'MALFORMED_FUNCTION_CALL');
+        }
+    }
+    _throwMissingResponseError(finishReason, hasTextResponse, validationContext) {
+        if (isMissingFinishReason(finishReason) && !hasTextResponse) {
+            this.logger.warn(() => `[stream:terminal] validation failed: missing finishReason and text`, validationContext);
+            throw new InvalidStreamError('Model stream ended without a finish reason and no text response.', 'NO_FINISH_REASON_NO_TEXT');
+        }
+        this.logger.warn(() => `[stream:terminal] validation failed: empty response text`, validationContext);
+        throw new InvalidStreamError('Model stream ended with empty response text.', 'NO_RESPONSE_TEXT');
+    }
+    /**
+     * Record history with usage metadata and sync token counts.
+     */
+    async _recordHistoryWithUsage(userInput, consolidatedParts, allChunks) {
+        // Use recordHistory to correctly save the conversation turn.
+        const modelOutput = [
+            { role: 'model', parts: consolidatedParts },
+        ];
+        // Capture usage metadata from the stream
+        let streamingUsageMetadata = null;
+        let actualPromptTokens = null;
+        // Find the last chunk that has usage metadata (similar to getLastChunkWithMetadata logic)
+        const lastChunkWithMetadata = allChunks
+            .slice()
+            .reverse()
+            .find((chunk) => chunk.usageMetadata);
+        if (lastChunkWithMetadata?.usageMetadata) {
+            streamingUsageMetadata = {
+                promptTokens: lastChunkWithMetadata.usageMetadata.promptTokenCount ?? 0,
+                completionTokens: lastChunkWithMetadata.usageMetadata.candidatesTokenCount ?? 0,
+                totalTokens: lastChunkWithMetadata.usageMetadata.totalTokenCount ?? 0,
+            };
+            const usageMetadata = lastChunkWithMetadata.usageMetadata;
+            const cacheReads = usageMetadata.cache_read_input_tokens ?? 0;
+            const cacheWrites = usageMetadata.cache_creation_input_tokens ?? 0;
+            actualPromptTokens =
+                streamingUsageMetadata.promptTokens + cacheReads + cacheWrites;
+        }
+        // Record history first (adds estimated tokens)
+        this.conversationManager.recordHistory(userInput, modelOutput, undefined, streamingUsageMetadata);
+        // Ensure token estimation updates are complete before syncing to actual API prompt tokens.
+        await this.historyService.waitForTokenUpdates();
+        // Sync token counts AFTER recording history to replace estimated tokens with actual API prompt tokens
+        // Use explicit check for undefined to allow 0 values
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition, sonarjs/different-types-comparison -- preserve defensive runtime boundary guard despite current static types.
+        if (actualPromptTokens !== null && actualPromptTokens !== undefined) {
+            if (actualPromptTokens > 0) {
+                this.logger.debug(() => `[StreamProcessor] Syncing prompt token count to HistoryService: ${actualPromptTokens}`);
+                this.historyService.syncTotalTokens(actualPromptTokens);
+                await this.historyService.waitForTokenUpdates();
+            }
+        }
+        else if (this.compressionHandler.lastPromptTokenCount !== null) {
+            if (this.compressionHandler.lastPromptTokenCount > 0) {
+                this.logger.debug(() => `[StreamProcessor] Syncing prompt token count to HistoryService: ${this.compressionHandler.lastPromptTokenCount}`);
+                this.historyService.syncTotalTokens(this.compressionHandler.lastPromptTokenCount);
+                await this.historyService.waitForTokenUpdates();
+            }
+        }
+        else {
+            this.logger.debug(() => `[StreamProcessor] No token count to sync (lastPromptTokenCount: ${this.compressionHandler.lastPromptTokenCount})`);
+        }
+    }
+    /**
+     * Enrich schema depth errors with diagnostic information.
+     * Adapted from maybeIncludeSchemaDepthContext in chatSession.ts.
+     */
+    _enrichSchemaDepthError(error) {
+        // Check for potentially problematic cyclic tools with cyclic schemas
+        // and include a recommendation to remove potentially problematic tools.
+        if (isStructuredError(error) && isSchemaDepthError(error.message)) {
+            const toolNames = this.runtimeContext.tools.listToolNames();
+            const cyclicSchemaTools = [];
+            // Check each tool's metadata for cyclic schemas
+            for (const toolName of toolNames) {
+                const metadata = this.runtimeContext.tools.getToolMetadata(toolName);
+                if (metadata?.parameterSchema &&
+                    hasCycleInSchema(metadata.parameterSchema)) {
+                    cyclicSchemaTools.push(toolName);
+                }
+            }
+            if (cyclicSchemaTools.length > 0) {
+                const extraDetails = `\n\nThis error was probably caused by cyclic schema references in one of the following tools, try disabling them:\n\n - ` +
+                    cyclicSchemaTools.join(`\n - `) +
+                    `\n`;
+                error.message += extraDetails;
+            }
+        }
+    }
+}
+//# sourceMappingURL=StreamProcessor.js.map