@framers/agentos 0.1.112 → 0.1.114

package/dist/api/variateImage.js

@@ -0,0 +1,154 @@
+/**
+ * @file variateImage.ts
+ * Provider-agnostic image variation generation for the AgentOS high-level API.
+ *
+ * Creates visual variations of a source image — each variation maintains the
+ * general composition and subject matter but differs in details, style, or
+ * perspective.
+ *
+ * Provider support:
+ * - **OpenAI** — `POST /v1/images/variations` (dedicated endpoint).
+ * - **Stability AI** — Implemented via img2img with low strength (high similarity).
+ * - **Stable Diffusion Local** — Implemented via img2img with low `denoising_strength`.
+ * - **Replicate** — Model-specific (img2img with low strength).
+ */
+import { createImageProvider } from '../core/images/index.js';
+import { ImageVariationNotSupportedError } from '../core/images/ImageOperationError.js';
+import { imageToBuffer } from '../core/images/imageToBuffer.js';
+import { resolveModelOption, resolveMediaProvider } from './model.js';
+import { attachUsageAttributes, toTurnMetricUsage } from './observability.js';
+import { recordAgentOSUsage } from './usageLedger.js';
+import { recordAgentOSTurnMetrics, withAgentOSSpan } from '../core/observability/otel.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Generates visual variations of a source image using a provider-agnostic interface.
+ *
+ * Resolves credentials via `resolveMediaProvider()`, initialises the
+ * matching image provider, converts the input image to a `Buffer`, and
+ * dispatches to the provider's `variateImage` method.
+ *
+ * For providers without a native variation endpoint, the high-level API falls
+ * back to an img2img call with `strength = variance` to produce similar output.
+ *
+ * @param opts - Variation options including the source image and desired count.
+ * @returns A promise resolving to the variation result with image data.
+ *
+ * @throws {ImageVariationNotSupportedError} When the resolved provider does not
+ *   implement image variations and has no img2img fallback.
+ * @throws {Error} When no provider can be determined or credentials are missing.
+ *
+ * @example
+ * ```ts
+ * const result = await variateImage({
+ *   provider: 'openai',
+ *   image: 'https://example.com/hero.png',
+ *   n: 4,
+ * });
+ * result.images.forEach((img, i) => console.log(`Variation ${i}:`, img.url));
+ * ```
+ */
+export async function variateImage(opts) {
+    const startedAt = Date.now();
+    let metricStatus = 'ok';
+    let metricUsage;
+    let metricProviderId;
+    let metricModelId;
+    try {
+        return await withAgentOSSpan('agentos.api.variate_image', async (span) => {
+            const { providerId, modelId } = resolveModelOption(opts, 'image');
+            const resolved = resolveMediaProvider(providerId, modelId, {
+                apiKey: opts.apiKey,
+                baseUrl: opts.baseUrl,
+            });
+            metricProviderId = resolved.providerId;
+            metricModelId = resolved.modelId;
+            span?.setAttribute('llm.provider', resolved.providerId);
+            span?.setAttribute('llm.model', resolved.modelId);
+            span?.setAttribute('agentos.api.variance', opts.variance ?? 0.5);
+            const provider = createImageProvider(resolved.providerId);
+            await provider.initialize({
+                apiKey: resolved.apiKey,
+                baseURL: resolved.baseUrl,
+                defaultModelId: resolved.modelId,
+            });
+            const imageBuffer = await imageToBuffer(opts.image);
+            let result;
+            if (typeof provider.variateImage === 'function') {
+                // Native variation support (e.g. OpenAI /v1/images/variations).
+                result = await provider.variateImage({
+                    modelId: resolved.modelId,
+                    image: imageBuffer,
+                    n: opts.n,
+                    variance: opts.variance,
+                    size: opts.size,
+                    providerOptions: opts.providerOptions,
+                });
+            }
+            else if (typeof provider.editImage === 'function') {
+                // Fallback: use img2img with low strength to produce "variations".
+                // The variance parameter maps to edit strength — lower variance means
+                // the output stays closer to the original.
+                result = await provider.editImage({
+                    modelId: resolved.modelId,
+                    image: imageBuffer,
+                    prompt: 'Create a variation of this image.',
+                    mode: 'img2img',
+                    strength: opts.variance ?? 0.5,
+                    n: opts.n,
+                    size: opts.size,
+                    providerOptions: opts.providerOptions,
+                });
+            }
+            else {
+                throw new ImageVariationNotSupportedError(resolved.providerId);
+            }
+            metricUsage = result.usage;
+            span?.setAttribute('agentos.api.images_count', result.images.length);
+            attachUsageAttributes(span, {
+                totalCostUSD: result.usage?.totalCostUSD,
+            });
+            return {
+                images: result.images,
+                provider: result.providerId,
+                model: result.modelId,
+                usage: { costUSD: result.usage?.totalCostUSD },
+            };
+        });
+    }
+    catch (error) {
+        metricStatus = 'error';
+        throw error;
+    }
+    finally {
+        try {
+            await recordAgentOSUsage({
+                providerId: metricProviderId,
+                modelId: metricModelId,
+                usage: metricUsage
+                    ? {
+                        costUSD: metricUsage.totalCostUSD,
+                    }
+                    : undefined,
+                options: {
+                    ...opts.usageLedger,
+                    source: opts.usageLedger?.source ?? 'variateImage',
+                },
+            });
+        }
+        catch {
+            // Best-effort — usage persistence must not break the variation operation.
+        }
+        recordAgentOSTurnMetrics({
+            durationMs: Date.now() - startedAt,
+            status: metricStatus,
+            usage: toTurnMetricUsage(metricUsage
+                ? {
+                    totalCostUSD: metricUsage.totalCostUSD,
+                }
+                : undefined),
+        });
+    }
+}
+//# sourceMappingURL=variateImage.js.map

package/dist/api/variateImage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variateImage.js","sourceRoot":"","sources":["../../src/api/variateImage.ts"],"names":[],"mappings":"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"}

package/dist/cognitive_substrate/GMI.d.ts

@@ -11,8 +11,9 @@
  * @see ../core/tools/IToolOrchestrator.ts for tool orchestration.
  * @see ../core/ai_utilities/IUtilityAI.ts for utility functions.
  */
-import { IGMI, GMIBaseConfig, GMITurnInput, GMIOutputChunk, GMIPrimeState, ReasoningTrace, GMIHealthReport, MemoryLifecycleEvent, LifecycleActionResponse, ToolResultPayload, GMIOutput } from './IGMI';
+import { IGMI, GMIBaseConfig, GMITurnInput, GMIOutputChunk, GMIPrimeState, ReasoningTrace, GMIHealthReport, MemoryLifecycleEvent, LifecycleActionResponse, ToolCallResult, ToolResultPayload, GMIOutput } from './IGMI';
 import { IPersonaDefinition } from './personas/IPersonaDefinition';
+import { ConversationMessage } from '../core/conversation/ConversationMessage';
 import type { ICognitiveMemoryManager } from '../memory/CognitiveMemoryManager.js';
 /**
  * @class GMI
@@ -92,6 +93,9 @@ export declare class GMI implements IGMI {
     private assembleCognitiveMemoryContext;
     private encodeCognitiveMemory;
     private syncCognitiveMemoryForTurn;
+    private getConversationIdForTurn;
+    private getOrganizationIdForTurn;
+    private buildToolSessionData;
     /**
      * Ensures the GMI is initialized and in a READY state.
      * @private
@@ -119,6 +123,14 @@ export declare class GMI implements IGMI {
      */
     private buildConversationHistoryForPrompt;
     private convertChatMessageToConversationMessage;
+    private convertConversationMessageToChatMessage;
+    private normalizeConversationMessageContent;
+    hydrateConversationHistory(conversationHistory: ConversationMessage[]): void;
+    hydrateTurnContext(context: {
+        sessionId?: string;
+        conversationId?: string;
+        organizationId?: string;
+    }): void;
     private mapChatRoleToMessageRole;
     private normalizeChatMessageContent;
     private parseToolCallArguments;
@@ -138,7 +150,9 @@ export declare class GMI implements IGMI {
     /** @inheritdoc */
     processTurnStream(turnInput: GMITurnInput): AsyncGenerator<GMIOutputChunk, GMIOutput, undefined>;
     /** @inheritdoc */
-    handleToolResult(toolCallId: string, toolName: string, resultPayload: ToolResultPayload, _userId: string): Promise<GMIOutput>;
+    handleToolResult(toolCallId: string, toolName: string, resultPayload: ToolResultPayload, userId: string): Promise<GMIOutput>;
+    /** @inheritdoc */
+    handleToolResults(toolResults: ToolCallResult[], _userId: string): Promise<GMIOutput>;
     /**
      * Performs post-turn RAG ingestion if configured.
      * @private

package/dist/cognitive_substrate/GMI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GMI.d.ts","sourceRoot":"","sources":["../../src/cognitive_substrate/GMI.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"GMI.d.ts","sourceRoot":"","sources":["../../src/cognitive_substrate/GMI.ts"],"names":[],"mappings":"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"}

package/dist/cognitive_substrate/GMI.js

@@ -308,15 +308,48 @@ export class GMI {
             });
         }
     }
+    getConversationIdForTurn(turnInput) {
+        const metadataConversationId = typeof turnInput.metadata?.conversationId === 'string'
+            ? turnInput.metadata.conversationId.trim()
+            : '';
+        if (metadataConversationId) {
+            return metadataConversationId;
+        }
+        const sessionId = typeof turnInput.sessionId === 'string' ? turnInput.sessionId.trim() : '';
+        return sessionId || undefined;
+    }
+    getOrganizationIdForTurn(turnInput) {
+        const organizationId = typeof turnInput.metadata?.organizationId === 'string'
+            ? turnInput.metadata.organizationId.trim()
+            : '';
+        return organizationId || undefined;
+    }
+    buildToolSessionData(turnInput) {
+        const sessionId = typeof turnInput.sessionId === 'string' ? turnInput.sessionId.trim() : '';
+        const conversationId = this.getConversationIdForTurn(turnInput);
+        const organizationId = this.getOrganizationIdForTurn(turnInput);
+        const sessionData = {};
+        if (sessionId) {
+            sessionData.sessionId = sessionId;
+        }
+        if (conversationId) {
+            sessionData.conversationId = conversationId;
+        }
+        if (organizationId) {
+            sessionData.organizationId = organizationId;
+        }
+        return Object.keys(sessionData).length > 0 ? sessionData : undefined;
+    }
     /**
      * Ensures the GMI is initialized and in a READY state.
      * @private
      */
-    ensureReady() {
+    ensureReady(additionallyAllowedStates = []) {
         if (!this.isInitialized) {
             throw new GMIError(`GMI (ID: ${this.gmiId}) is not initialized.`, GMIErrorCode.NOT_INITIALIZED);
         }
-        if (this.state !== GMIPrimeState.READY) {
+        if (this.state !== GMIPrimeState.READY &&
+            !additionallyAllowedStates.includes(this.state)) {
             throw new GMIError(`GMI (ID: ${this.gmiId}) is not in READY state. Current state: ${this.state}.`, GMIErrorCode.INVALID_STATE, { currentGMIState: this.state });
         }
     }
@@ -410,6 +443,62 @@ export class GMI {
         }
         return conversationMessage;
     }
+    convertConversationMessageToChatMessage(message) {
+        if (message.role === MessageRole.ERROR || message.role === MessageRole.THOUGHT) {
+            return null;
+        }
+        const role = message.role === MessageRole.SYSTEM || message.role === MessageRole.SUMMARY
+            ? 'system'
+            : message.role === MessageRole.ASSISTANT
+                ? 'assistant'
+                : message.role === MessageRole.TOOL
+                    ? 'tool'
+                    : 'user';
+        const content = message.role === MessageRole.SUMMARY && typeof message.content === 'string'
+            ? `[Conversation Summary]\n${message.content}`
+            : this.normalizeConversationMessageContent(message.content);
+        return {
+            role,
+            content,
+            name: message.name,
+            tool_call_id: message.tool_call_id,
+            tool_calls: Array.isArray(message.tool_calls)
+                ? message.tool_calls.map((toolCall) => ({
+                    id: toolCall.id,
+                    type: 'function',
+                    function: {
+                        name: toolCall.name,
+                        arguments: JSON.stringify(toolCall.arguments ?? {}),
+                    },
+                }))
+                : undefined,
+        };
+    }
+    normalizeConversationMessageContent(content) {
+        if (content === null || typeof content === 'string') {
+            return content;
+        }
+        if (Array.isArray(content)) {
+            return content.map((part) => ({ ...part }));
+        }
+        return JSON.stringify(content);
+    }
+    hydrateConversationHistory(conversationHistory) {
+        this.conversationHistory = conversationHistory
+            .map((message) => this.convertConversationMessageToChatMessage(message))
+            .filter((message) => message !== null);
+    }
+    hydrateTurnContext(context) {
+        if (typeof context.sessionId === 'string' && context.sessionId.trim()) {
+            this.reasoningTrace.sessionId = context.sessionId.trim();
+        }
+        if (typeof context.conversationId === 'string' && context.conversationId.trim()) {
+            this.reasoningTrace.conversationId = context.conversationId.trim();
+        }
+        if (typeof context.organizationId === 'string' && context.organizationId.trim()) {
+            this.reasoningTrace.organizationId = context.organizationId.trim();
+        }
+    }
     mapChatRoleToMessageRole(role) {
         switch (role) {
             case 'system':
@@ -493,12 +582,19 @@ export class GMI {
     }
     /** @inheritdoc */
     async *processTurnStream(turnInput) {
-        this.ensureReady();
+        const continuationAllowedStates = turnInput.metadata?.isToolContinuation === true
+            ? [GMIPrimeState.PROCESSING, GMIPrimeState.AWAITING_TOOL_RESULT]
+            : [];
+        this.ensureReady(continuationAllowedStates);
         this.state = GMIPrimeState.PROCESSING;
         const turnId = turnInput.interactionId || `turn-${uuidv4()}`;
         // Store turnId on reasoningTrace for current turn
-        if (this.reasoningTrace)
+        if (this.reasoningTrace) {
             this.reasoningTrace.turnId = turnId;
+            this.reasoningTrace.sessionId = turnInput.sessionId;
+            this.reasoningTrace.conversationId = this.getConversationIdForTurn(turnInput);
+            this.reasoningTrace.organizationId = this.getOrganizationIdForTurn(turnInput);
+        }
         this.addTraceEntry(ReasoningEntryType.INTERACTION_START, `Processing turn '${turnId}' for user '${turnInput.userId}'`, { inputType: turnInput.type, inputPreview: String(turnInput.content).substring(0, 100) });
         // Initialize aggregates for the final GMIOutput
         let aggregatedResponseText = "";
@@ -695,7 +791,12 @@ export class GMI {
                                 : tc.function.arguments,
                         }));
                         aggregatedToolCalls.push(...currentIterationToolCallRequests); // Aggregate for final output
-                        yield this.createOutputChunk(turnInput.interactionId, GMIOutputChunkType.TOOL_CALL_REQUEST, [...currentIterationToolCallRequests]);
+                        yield this.createOutputChunk(turnInput.interactionId, GMIOutputChunkType.TOOL_CALL_REQUEST, [...currentIterationToolCallRequests], {
+                            metadata: {
+                                executionMode: 'internal',
+                                requiresExternalToolResult: false,
+                            },
+                        });
                         this.addTraceEntry(ReasoningEntryType.TOOL_CALL_REQUESTED, `LLM requested tool(s).`, { requests: currentIterationToolCallRequests });
                     }
                     if (chunk.isFinal && choice?.finishReason) {
@@ -735,6 +836,7 @@ export class GMI {
                             gmiId: this.gmiId, personaId: this.activePersona.id,
                             personaCapabilities: this.activePersona.allowedCapabilities || [],
                             userContext: this.currentUserContext, correlationId: turnId,
+                            sessionData: this.buildToolSessionData(turnInput),
                         };
                         this.addTraceEntry(ReasoningEntryType.TOOL_EXECUTION_START, `Orchestrating tool: ${toolCallReq.name}`, { reqId: toolCallReq.id });
                         const result = await this.toolOrchestrator.processToolCall(requestDetails);
@@ -798,37 +900,68 @@ export class GMI {
         }
     }
     /** @inheritdoc */
-    async handleToolResult(toolCallId, toolName, resultPayload, _userId) {
+    async handleToolResult(toolCallId, toolName, resultPayload, userId) {
+        return this.handleToolResults([
+            {
+                toolCallId,
+                toolName,
+                output: resultPayload.type === 'success' ? resultPayload.result : resultPayload.error,
+                isError: resultPayload.type === 'error',
+                errorDetails: resultPayload.type === 'error' ? resultPayload.error : undefined,
+            },
+        ], userId);
+    }
+    /** @inheritdoc */
+    async handleToolResults(toolResults, _userId) {
         if (!this.isInitialized) {
             throw new GMIError("GMI is not initialized. Cannot handle tool result.", GMIErrorCode.NOT_INITIALIZED);
         }
+        if (!Array.isArray(toolResults) || toolResults.length === 0) {
+            throw new GMIError('At least one tool result is required to continue the turn.', GMIErrorCode.VALIDATION_ERROR);
+        }
         // Allow handling tool results if processing or specifically awaiting
-        if (this.state !== GMIPrimeState.AWAITING_TOOL_RESULT && this.state !== GMIPrimeState.PROCESSING) {
-            this.addTraceEntry(ReasoningEntryType.WARNING, `handleToolResult called when GMI state is ${this.state}. Expected AWAITING_TOOL_RESULT or PROCESSING.`, { toolCallId, toolName });
+        if (this.state !== GMIPrimeState.AWAITING_TOOL_RESULT &&
+            this.state !== GMIPrimeState.PROCESSING &&
+            this.state !== GMIPrimeState.READY) {
+            this.addTraceEntry(ReasoningEntryType.WARNING, `handleToolResults called when GMI state is ${this.state}. Expected READY, AWAITING_TOOL_RESULT, or PROCESSING.`, {
+                toolCallIds: toolResults.map((toolResult) => toolResult.toolCallId),
+                toolNames: toolResults.map((toolResult) => toolResult.toolName),
+            });
             // Depending on desired robustness, could throw an error or try to proceed.
         }
         this.state = GMIPrimeState.PROCESSING; // Set state to processing
         // Use current turnId if available, or generate a new interactionId for this specific handling
         const interactionId = this.reasoningTrace?.turnId || `tool_handler_turn_${uuidv4()}`;
-        this.addTraceEntry(ReasoningEntryType.TOOL_EXECUTION_RESULT, `Received external tool result for '${toolName}' (ID: ${toolCallId}) to be processed.`, { toolCallId, toolName, success: resultPayload.type === 'success', interactionId });
-        const toolCallResult = {
-            toolCallId,
-            toolName,
-            output: resultPayload.type === 'success' ? resultPayload.result : resultPayload.error,
-            isError: resultPayload.type === 'error',
-            errorDetails: resultPayload.type === 'error' ? resultPayload.error : undefined,
-        };
-        this.updateConversationHistoryWithToolResult(toolCallResult);
+        this.addTraceEntry(ReasoningEntryType.TOOL_EXECUTION_RESULT, toolResults.length === 1
+            ? `Received external tool result for '${toolResults[0].toolName}' (ID: ${toolResults[0].toolCallId}) to be processed.`
+            : `Received ${toolResults.length} external tool results to be processed together.`, {
+            interactionId,
+            toolResults: toolResults.map((toolResult) => ({
+                toolCallId: toolResult.toolCallId,
+                toolName: toolResult.toolName,
+                success: !toolResult.isError,
+            })),
+        });
+        toolResults.forEach((toolResult) => this.updateConversationHistoryWithToolResult(toolResult));
         // Construct a system turn input to represent the continuation after tool result
         const systemTurnInput = {
             interactionId,
             userId: this.currentUserContext.userId, // Use the GMI's current user context
             sessionId: this.reasoningTrace?.sessionId,
             type: GMIInteractionType.SYSTEM_MESSAGE, // Or a specific type for internal continuation
-            content: `Internally processing result for tool '${toolName}'.`, // System message content
+            content: toolResults.length === 1
+                ? `Internally processing result for tool '${toolResults[0].toolName}'.`
+                : `Internally processing ${toolResults.length} external tool results.`,
             metadata: {
                 isToolContinuation: true,
-                originalToolCallId: toolCallId,
+                originalToolCallId: toolResults.length === 1 ? toolResults[0].toolCallId : undefined,
+                originalToolCallIds: toolResults.map((toolResult) => toolResult.toolCallId),
+                ...(this.reasoningTrace?.conversationId
+                    ? { conversationId: this.reasoningTrace.conversationId }
+                    : {}),
+                ...(this.reasoningTrace?.organizationId
+                    ? { organizationId: this.reasoningTrace.organizationId }
+                    : {}),
             }
         };
         // Collect all chunks from processTurnStream to form a single GMIOutput
@@ -837,45 +970,44 @@ export class GMI {
         const aggregatedUsage = { totalTokens: 0, promptTokens: 0, completionTokens: 0, breakdown: [] };
         let _lastErrorForOutput = undefined;
         const stream = this.processTurnStream(systemTurnInput); // This now returns GMIOutput
-        const finalGmiOutputFromStream = await (async () => {
-            for await (const chunk of stream) {
-                // Process chunks as they arrive if needed for intermediate steps,
-                // but the final GMIOutput will be the generator's return value.
-                // Here, we mainly care about the final returned GMIOutput.
-                // However, if processTurnStream itself aggregates, this loop might just be to exhaust it.
-                if (chunk.type === GMIOutputChunkType.TEXT_DELTA && typeof chunk.content === 'string') {
-                    _aggregatedResponseText += chunk.content;
-                }
-                if (chunk.type === GMIOutputChunkType.TOOL_CALL_REQUEST && Array.isArray(chunk.content)) {
-                    aggregatedToolCalls.push(...chunk.content);
-                }
-                if (chunk.usage) {
-                    aggregatedUsage.promptTokens += chunk.usage.promptTokens || 0;
-                    aggregatedUsage.completionTokens += chunk.usage.completionTokens || 0;
-                    aggregatedUsage.totalTokens = aggregatedUsage.promptTokens + aggregatedUsage.completionTokens;
-                    if (chunk.usage.costUSD)
-                        aggregatedUsage.totalCostUSD = (aggregatedUsage.totalCostUSD || 0) + chunk.usage.costUSD;
-                }
-                if (chunk.type === GMIOutputChunkType.ERROR) {
-                    _lastErrorForOutput = chunk.errorDetails || { code: GMIErrorCode.GMI_PROCESSING_ERROR, message: String(chunk.content) };
-                }
+        let finalGmiOutputFromStream;
+        while (true) {
+            const { value, done } = await stream.next();
+            if (done) {
+                finalGmiOutputFromStream = value;
+                break;
+            }
+            const chunk = value;
+            if (chunk.type === GMIOutputChunkType.TEXT_DELTA && typeof chunk.content === 'string') {
+                _aggregatedResponseText += chunk.content;
+            }
+            if (chunk.type === GMIOutputChunkType.TOOL_CALL_REQUEST && Array.isArray(chunk.content)) {
+                aggregatedToolCalls.push(...chunk.content);
+            }
+            if (chunk.usage) {
+                aggregatedUsage.promptTokens += chunk.usage.promptTokens || 0;
+                aggregatedUsage.completionTokens += chunk.usage.completionTokens || 0;
+                aggregatedUsage.totalTokens = aggregatedUsage.promptTokens + aggregatedUsage.completionTokens;
+                if (chunk.usage.costUSD)
+                    aggregatedUsage.totalCostUSD = (aggregatedUsage.totalCostUSD || 0) + chunk.usage.costUSD;
             }
-            // The actual final GMIOutput comes from the generator's return value
-            // This requires `processTurnStream` to be `async function* (...) : AsyncGenerator<..., GMIOutput, ...>`
-            // and to have a `return finalOutput;` statement.
-            // The loop above will collect intermediate chunks, and the 'return' from the generator is the key.
-            // This structure is a bit complex with nested generators. Let's assume processTurnStream does return a GMIOutput.
-            // The way AsyncGenerator TReturn works, the last value is 'done: true, value: TReturn'.
-            // My processTurnStream is modified to return GMIOutput.
-            let result = await stream.next();
-            while (!result.done) {
-                // This loop is mainly to exhaust the stream if previous loop didn't fully.
-                // The crucial part is what processTurnStream *returns*.
-                result = await stream.next();
+            if (chunk.type === GMIOutputChunkType.ERROR) {
+                _lastErrorForOutput =
+                    chunk.errorDetails || { code: GMIErrorCode.GMI_PROCESSING_ERROR, message: String(chunk.content) };
             }
-            return result.value; // This is the GMIOutput
-        })();
-        this.addTraceEntry(ReasoningEntryType.INTERACTION_END, `Continuation after tool '${toolName}' (ID: ${toolCallId}) processed.`);
+        }
+        if (!finalGmiOutputFromStream) {
+            finalGmiOutputFromStream = {
+                isFinal: _lastErrorForOutput ? true : false,
+                responseText: _aggregatedResponseText || null,
+                toolCalls: aggregatedToolCalls.length > 0 ? aggregatedToolCalls : undefined,
+                usage: aggregatedUsage,
+                error: _lastErrorForOutput,
+            };
+        }
+        this.addTraceEntry(ReasoningEntryType.INTERACTION_END, toolResults.length === 1
+            ? `Continuation after tool '${toolResults[0].toolName}' (ID: ${toolResults[0].toolCallId}) processed.`
+            : `Continuation after ${toolResults.length} external tool results processed.`);
         return finalGmiOutputFromStream;
     }
     /**