@framers/agentos 0.12.3 → 0.12.5

package/dist/cognition/substrate/GMI.js

@@ -25,6 +25,31 @@ import { feedbackTraceMessage } from './userFeedback.js';
 import { resolveReasoningTraceLimits } from './reasoningTraceLimits.js';
 const DEFAULT_MAX_CONVERSATION_HISTORY_TURNS = 20;
 const DEFAULT_SELF_REFLECTION_INTERVAL_TURNS = 5;
+/** The completion options a persona's defaults and a turn's `metadata.options` may set (design D4b). */
+const FORWARDED_COMPLETION_OPTION_KEYS = [
+    'temperature', 'maxTokens', 'topP', 'frequencyPenalty', 'presencePenalty', 'thinking', 'effort', 'cache',
+    'promptCacheKey', 'promptCacheRetention', 'serviceTier', 'requestTimeout', 'customModelParams',
+    'stopSequences', 'responseFormat', 'toolChoice',
+];
+/** The forwarded completion options `source` sets; unset keys are left out so a later layer can fill them. */
+function pickCompletionOptions(source) {
+    const picked = {};
+    if (!source)
+        return picked;
+    for (const key of FORWARDED_COMPLETION_OPTION_KEYS) {
+        if (source[key] !== undefined)
+            picked[key] = source[key];
+    }
+    return picked;
+}
+/** Adds one provider usage report to the turn's total. */
+function addUsage(total, usage) {
+    total.promptTokens += usage.promptTokens || 0;
+    total.completionTokens += usage.completionTokens || 0;
+    total.totalTokens = total.promptTokens + total.completionTokens;
+    if (usage.costUSD)
+        total.totalCostUSD = (total.totalCostUSD || 0) + usage.costUSD;
+}
 /**
  * @class GMI
  * @implements {IGMI}
@@ -421,6 +446,21 @@ export class GMI {
     hydrateConversationHistory(conversationHistory) {
         this.conversationHistoryManager.hydrate(conversationHistory);
     }
+    /**
+     * Makes `messages` the whole conversation history. An empty array is
+     * authoritative: it empties the history (unlike
+     * `metadata.conversationHistoryForPrompt`, which a turn ignores when empty).
+     * The sentiment tracker and the metaprompts read the same history.
+     */
+    replaceHistory(messages) {
+        this.conversationHistoryManager.clear();
+        if (messages.length > 0)
+            this.conversationHistoryManager.hydrate(messages);
+    }
+    /** Empties the conversation history. */
+    clearHistory() {
+        this.conversationHistoryManager.clear();
+    }
     hydrateTurnContext(context) {
         if (typeof context.sessionId === 'string' && context.sessionId.trim()) {
             this.reasoningTrace.sessionId = context.sessionId.trim();
@@ -561,6 +601,25 @@ export class GMI {
             return 'google_function_calling';
         return 'openai_functions';
     }
+    /**
+     * The model target of a turn without a completion gateway: the runtime
+     * path's lookup through the provider manager, with the 8192-token window
+     * and no capabilities when the manager knows nothing about the model.
+     */
+    async legacyModelTargetInfo(modelId, providerId) {
+        const modelDetails = await this.llmProviderManager.getModelInfo(modelId, providerId);
+        return {
+            modelId,
+            providerId: modelDetails?.providerId || providerId || this.llmProviderManager.getProviderForModel(modelId)?.providerId || 'unknown',
+            maxContextTokens: modelDetails?.contextWindowSize || 8192,
+            capabilities: modelDetails?.capabilities || [],
+            promptFormatType: this.determinePromptFormat(),
+            toolSupport: {
+                supported: modelDetails?.capabilities.includes('tool_use') || false,
+                format: this.determineToolFormat(modelDetails, providerId),
+            },
+        };
+    }
     /** @inheritdoc */
     async *processTurnStream(turnInput) {
         const continuationAllowedStates = turnInput.metadata?.isToolContinuation === true
@@ -572,6 +631,10 @@ export class GMI {
         }
         this.state = GMIPrimeState.PROCESSING;
         const turnNumber = ++this.turnSequence;
+        // A user turn starts at the primary hop; a tool continuation stays on the
+        // hop that served the step it continues.
+        if (turnInput.metadata?.isToolContinuation !== true)
+            this.turnResolution = undefined;
         this.stateOwnerTurn = turnNumber;
         // False once a newer turn has started; lifecycle writes below check it.
         const ownsState = () => this.stateOwnerTurn === turnNumber;
@@ -787,41 +850,13 @@ export class GMI {
                     assembledMemoryContext: assembledMemoryContext ?? undefined,
                     // tools: this.activePersona.embeddedTools, // If ITool[] and PromptComponents.tools takes ITool[]
                 };
+                const gateway = this.config.completionGateway;
                 const preferredModelIdFromInput = turnInput.metadata?.options?.preferredModelId;
                 const modelIdToUse = preferredModelIdFromInput || this.activePersona.defaultModelId || this.config.defaultLlmModelId;
                 const providerIdForModel = this.activePersona.defaultProviderId || this.config.defaultLlmProviderId;
                 if (!modelIdToUse) {
                     throw new GMIError("Could not determine modelId for LLM call.", GMIErrorCode.CONFIGURATION_ERROR, { turnId });
                 }
-                const modelDetails = await this.llmProviderManager.getModelInfo(modelIdToUse, providerIdForModel);
-                const modelTargetInfo = {
-                    modelId: modelIdToUse,
-                    providerId: modelDetails?.providerId || providerIdForModel || this.llmProviderManager.getProviderForModel(modelIdToUse)?.providerId || 'unknown',
-                    maxContextTokens: modelDetails?.contextWindowSize || 8192, // Default fallback
-                    capabilities: modelDetails?.capabilities || [],
-                    promptFormatType: this.determinePromptFormat(),
-                    toolSupport: {
-                        supported: modelDetails?.capabilities.includes('tool_use') || false,
-                        format: this.determineToolFormat(modelDetails, providerIdForModel),
-                    },
-                };
-                const promptEngineResult = await this.promptEngine.constructPrompt(promptComponents, modelTargetInfo, promptExecContext);
-                promptEngineResult.issues?.forEach(issue => this.addTraceEntry(ReasoningEntryType.WARNING, `Prompt Engine Issue: ${issue.message}`, issue));
-                // A failed template leaves the prompt empty, and every provider takes
-                // a non-empty ChatMessage[]; fail the turn rather than send nothing.
-                const promptMessages = promptEngineResult.prompt;
-                if (!Array.isArray(promptMessages) || promptMessages.length === 0) {
-                    throw new GMIError(`Prompt construction produced no chat messages for model '${modelTargetInfo.modelId}' (template '${promptEngineResult.metadata?.templateUsed ?? 'unknown'}').`, GMIErrorCode.GMI_PROCESSING_ERROR, {
-                        turnId,
-                        templateUsed: promptEngineResult.metadata?.templateUsed,
-                        issues: promptEngineResult.issues?.filter((issue) => issue.type === 'error'),
-                    });
-                }
-                this.addTraceEntry(ReasoningEntryType.PROMPT_CONSTRUCTION_COMPLETE, `Prompt constructed for model ${modelTargetInfo.modelId}.`);
-                const provider = this.llmProviderManager.getProvider(modelTargetInfo.providerId);
-                if (!provider) {
-                    throw new GMIError(`LLM Provider '${modelTargetInfo.providerId}' not found or not initialized.`, GMIErrorCode.LLM_PROVIDER_UNAVAILABLE);
-                }
                 const plannedToolFailureMode = turnInput.metadata?.executionPolicy?.toolFailureMode === 'fail_closed'
                     ? 'fail_closed'
                     : 'fail_open';
@@ -846,77 +881,231 @@ export class GMI {
                         toolsForLLM = discoveredTools;
                     }
                 }
+                // Every completion option the persona and the turn set (D4b); temperature and
+                // the output budget keep their defaults; tools, user and streaming are the GMI's.
+                const turnOptions = (turnInput.metadata?.options ?? {});
+                const personaOptions = (this.activePersona.defaultModelCompletionOptions ?? {});
                 const llmOptions = {
-                    temperature: turnInput.metadata?.options?.temperature ?? this.activePersona.defaultModelCompletionOptions?.temperature ?? 0.7,
-                    maxTokens: turnInput.metadata?.options?.maxTokens ?? this.activePersona.defaultModelCompletionOptions?.maxTokens ?? 2048,
+                    ...pickCompletionOptions(personaOptions),
+                    ...pickCompletionOptions(turnOptions),
+                    temperature: turnOptions.temperature ?? personaOptions.temperature ?? 0.7,
+                    maxTokens: turnOptions.maxTokens ?? personaOptions.maxTokens ?? 2048,
                     tools: toolsForLLM.length > 0 ? toolsForLLM.map(t => ({ type: "function", function: { name: t.name, description: t.description, parameters: t.inputSchema } })) : undefined,
-                    toolChoice: turnInput.metadata?.options?.toolChoice || (toolsForLLM.length > 0 ? "auto" : undefined),
+                    toolChoice: turnOptions.toolChoice ?? personaOptions.toolChoice ?? (toolsForLLM.length > 0 ? "auto" : undefined),
                     userId: this.currentUserContext.userId,
-                    stream: true, // For generateCompletionStream
-                    responseFormat: turnInput.metadata?.options?.responseFormat,
+                    stream: true,
                 };
-                this.addTraceEntry(ReasoningEntryType.LLM_CALL_START, `Streaming from ${modelTargetInfo.modelId}. Tools: ${toolsForLLM.length}.`);
+                // A schema travels to the gateway, which lowers it per hop (D9); it is not a provider option.
+                const responseSchema = turnOptions.responseSchema;
+                const schemaName = turnOptions.schemaName;
+                // The gateway's route: the model asked for, the user's text as the router's
+                // task hint, the tools, and the call options each fallback hop derives its
+                // overrides from. Every hop that could not start is traced.
+                let lastHopError;
+                const userText = this.stringifyTurnContent(turnInput.content) ?? '';
+                const route = gateway
+                    ? {
+                        modelId: modelIdToUse,
+                        providerId: providerIdForModel,
+                        messages: userText ? [{ role: 'user', content: userText }] : [],
+                        tools: llmOptions.tools,
+                        callOptions: { maxTokens: llmOptions.maxTokens, effort: llmOptions.effort, cache: llmOptions.cache },
+                        onFallback: ({ from, to, hop, error }) => this.addTraceEntry(ReasoningEntryType.WARNING, `Model fallback from '${from}' to '${to}' (hop ${hop}): ${error.message}`),
+                        onHopFailure: ({ providerId, hop, error }) => {
+                            lastHopError = error;
+                            this.addTraceEntry(ReasoningEntryType.WARNING, `Provider '${providerId}' (hop ${hop}) could not start: ${error.message}`);
+                        },
+                    }
+                    : undefined;
+                // The hop that serves this step: the one that served the turn's last
+                // step, else the route's first hop that can start. Resolved before the
+                // prompt is built, so the prompt is budgeted for the serving model (D1).
+                let resolution = null;
+                if (gateway && route) {
+                    resolution = this.turnResolution ?? (await gateway.resolve(route));
+                    if (!resolution) {
+                        throw new GMIError(`No model provider could serve the turn${lastHopError ? `: ${lastHopError.message}` : '.'}`, GMIErrorCode.LLM_PROVIDER_UNAVAILABLE, { turnId });
+                    }
+                }
+                // What the serving attempt produced; read after the hop loop.
                 let currentIterationTextResponse = "";
                 let currentIterationToolCallRequests = [];
-                // Extended-thinking blocks emitted this iteration (Opus 4.7/4.8 with
-                // thinking enabled). Captured from the final chunk + stored on the
-                // assistant turn so the next tool turn replays them verbatim, which
-                // Anthropic requires. Empty for every non-thinking turn, so the stored
-                // turn is unchanged on the normal path.
+                // Extended-thinking blocks emitted this step (Anthropic with thinking
+                // enabled). Captured from the final chunk and stored on the assistant
+                // turn so the next tool turn replays them verbatim, which Anthropic
+                // requires. Empty for every non-thinking step.
                 let currentIterationThinkingBlocks = [];
-                let textDeltaEmitted = false;
-                for await (const chunk of provider.generateCompletionStream(modelTargetInfo.modelId, promptMessages, llmOptions)) {
-                    if (chunk.error) {
-                        throw new GMIError(`LLM stream error: ${chunk.error.message}`, GMIErrorCode.LLM_PROVIDER_ERROR, chunk.error.details);
+                let stepUsage;
+                let stepFinishReason = null;
+                let stepFinalChunk;
+                let stepStructuredOutput;
+                let modelTargetInfo;
+                // One attempt per hop. A failure before any output moves to the next
+                // hop and rebuilds the prompt for that hop's model (D3); after output
+                // there is no fallback for the step. Without a gateway the loop runs once.
+                hopLoop: for (;;) {
+                    if (resolution) {
+                        this.llmProviderManager.setResolution?.(resolution);
                     }
-                    if (chunk.responseTextDelta) {
-                        currentIterationTextResponse += chunk.responseTextDelta;
-                        aggregatedResponseText += chunk.responseTextDelta; // Aggregate for final output
-                        yield this.createOutputChunk(turnInput.interactionId, GMIOutputChunkType.TEXT_DELTA, chunk.responseTextDelta, { usage: chunk.usage });
-                        textDeltaEmitted = true;
+                    modelTargetInfo = resolution
+                        ? {
+                            modelId: resolution.modelId,
+                            providerId: resolution.providerId,
+                            maxContextTokens: resolution.maxContextTokens,
+                            capabilities: resolution.capabilities,
+                            promptFormatType: this.determinePromptFormat(),
+                            toolSupport: { supported: resolution.capabilities.includes('tool_use'), format: resolution.toolFormat },
+                        }
+                        : await this.legacyModelTargetInfo(modelIdToUse, providerIdForModel);
+                    const promptEngineResult = await this.promptEngine.constructPrompt(promptComponents, modelTargetInfo, promptExecContext);
+                    promptEngineResult.issues?.forEach(issue => this.addTraceEntry(ReasoningEntryType.WARNING, `Prompt Engine Issue: ${issue.message}`, issue));
+                    // A failed template leaves the prompt empty, and every provider takes
+                    // a non-empty ChatMessage[]; fail the turn rather than send nothing.
+                    const promptMessages = promptEngineResult.prompt;
+                    if (!Array.isArray(promptMessages) || promptMessages.length === 0) {
+                        throw new GMIError(`Prompt construction produced no chat messages for model '${modelTargetInfo.modelId}' (template '${promptEngineResult.metadata?.templateUsed ?? 'unknown'}').`, GMIErrorCode.GMI_PROCESSING_ERROR, {
+                            turnId,
+                            templateUsed: promptEngineResult.metadata?.templateUsed,
+                            issues: promptEngineResult.issues?.filter((issue) => issue.type === 'error'),
+                        });
                     }
-                    // Handle fully formed tool_calls if present in the chunk's message
-                    const choice = chunk.choices?.[0];
-                    // Capture extended-thinking blocks from the final chunk so they ride
-                    // the assistant turn into history (replayed verbatim next tool turn).
-                    if (choice?.message?.thinkingBlocks?.length) {
-                        currentIterationThinkingBlocks = choice.message.thinkingBlocks;
+                    this.addTraceEntry(ReasoningEntryType.PROMPT_CONSTRUCTION_COMPLETE, `Prompt constructed for model ${modelTargetInfo.modelId}.`);
+                    let attempt;
+                    let attemptOutcome;
+                    if (gateway && resolution) {
+                        const gatewayAttempt = gateway.stream(resolution, promptMessages, llmOptions, responseSchema, schemaName);
+                        attempt = gatewayAttempt;
+                        attemptOutcome = gatewayAttempt.outcome;
                     }
-                    if (choice?.message?.tool_calls && choice.message.tool_calls.length > 0) {
-                        currentIterationToolCallRequests = choice.message.tool_calls.map((tc) => ({
-                            id: tc.id || `toolcall-${uuidv4()}`, // Ensure ID
-                            name: tc.function.name,
-                            arguments: typeof tc.function.arguments === 'string'
-                                ? JSON.parse(tc.function.arguments)
-                                : tc.function.arguments,
-                            ...(tc.thoughtSignature ? { thoughtSignature: tc.thoughtSignature } : {}),
-                        }));
-                        aggregatedToolCalls.push(...currentIterationToolCallRequests); // Aggregate for final output
-                        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 });
+                    else {
+                        const provider = this.llmProviderManager.getProvider(modelTargetInfo.providerId);
+                        if (!provider) {
+                            throw new GMIError(`LLM Provider '${modelTargetInfo.providerId}' not found or not initialized.`, GMIErrorCode.LLM_PROVIDER_UNAVAILABLE);
+                        }
+                        attempt = provider.generateCompletionStream(modelTargetInfo.modelId, promptMessages, llmOptions);
                     }
-                    if (chunk.isFinal && choice?.finishReason) {
-                        this.addTraceEntry(ReasoningEntryType.LLM_CALL_COMPLETE, `LLM stream part finished. Reason: ${choice.finishReason}`, { usage: chunk.usage });
+                    this.addTraceEntry(ReasoningEntryType.LLM_CALL_START, `Streaming from ${modelTargetInfo.modelId}${resolution ? ` (hop ${resolution.hop})` : ''}. Tools: ${toolsForLLM.length}.`);
+                    let textDeltaEmitted = false;
+                    for await (const chunk of attempt) {
+                        if (chunk.error) {
+                            throw new GMIError(`LLM stream error: ${chunk.error.message}`, GMIErrorCode.LLM_PROVIDER_ERROR, chunk.error.details);
+                        }
+                        if (chunk.responseTextDelta) {
+                            currentIterationTextResponse += chunk.responseTextDelta;
+                            aggregatedResponseText += chunk.responseTextDelta; // Aggregate for final output
+                            yield this.createOutputChunk(turnInput.interactionId, GMIOutputChunkType.TEXT_DELTA, chunk.responseTextDelta, { usage: chunk.usage });
+                            textDeltaEmitted = true;
+                        }
+                        // Handle fully formed tool_calls if present in the chunk's message
+                        const choice = chunk.choices?.[0];
+                        // Capture extended-thinking blocks from the final chunk so they ride
+                        // the assistant turn into history (replayed verbatim next tool turn).
+                        if (choice?.message?.thinkingBlocks?.length) {
+                            currentIterationThinkingBlocks = choice.message.thinkingBlocks;
+                        }
+                        // The gateway lifts a streamed schema tool call into `structuredOutput` (D9).
+                        const structured = chunk.structuredOutput;
+                        if (structured !== undefined)
+                            stepStructuredOutput = structured;
+                        if (choice?.message?.tool_calls && choice.message.tool_calls.length > 0) {
+                            currentIterationToolCallRequests = choice.message.tool_calls.map((tc) => ({
+                                id: tc.id || `toolcall-${uuidv4()}`, // Ensure ID
+                                name: tc.function.name,
+                                arguments: typeof tc.function.arguments === 'string'
+                                    ? JSON.parse(tc.function.arguments)
+                                    : tc.function.arguments,
+                                ...(tc.thoughtSignature ? { thoughtSignature: tc.thoughtSignature } : {}),
+                            }));
+                            aggregatedToolCalls.push(...currentIterationToolCallRequests); // Aggregate for final output
+                            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 });
+                        }
+                        // A provider that sends no deltas: its final content is the step's text, emitted once (D4d).
+                        if (chunk.isFinal && !textDeltaEmitted && typeof choice?.message?.content === 'string' && choice.message.content.length > 0) {
+                            currentIterationTextResponse = choice.message.content;
+                            aggregatedResponseText += choice.message.content;
+                            yield this.createOutputChunk(turnInput.interactionId, GMIOutputChunkType.TEXT_DELTA, choice.message.content, { usage: chunk.usage });
+                            textDeltaEmitted = true;
+                        }
+                        if (chunk.isFinal && choice?.finishReason) {
+                            stepFinishReason = choice.finishReason;
+                            this.addTraceEntry(ReasoningEntryType.LLM_CALL_COMPLETE, `LLM stream part finished. Reason: ${choice.finishReason}`, { usage: chunk.usage });
+                        }
+                        if (chunk.isFinal)
+                            stepFinalChunk = chunk;
+                        // Usage on every chunk that carries it, choice or not (D4c). Providers report
+                        // the request's running total, so the turn total takes the step's last value once.
                         if (chunk.usage) {
+                            stepUsage = chunk.usage;
                             yield this.createOutputChunk(turnInput.interactionId, GMIOutputChunkType.USAGE_UPDATE, chunk.usage);
-                            // Aggregate 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;
+                        }
+                    } // End LLM stream
+                    if (gateway && route && resolution && attemptOutcome) {
+                        const outcome = await attemptOutcome;
+                        if (outcome.kind === 'hopFailed') {
+                            const failedHop = resolution;
+                            lastHopError = outcome.error;
+                            this.addTraceEntry(ReasoningEntryType.WARNING, `Provider '${failedHop.providerId}' (hop ${failedHop.hop}) failed before any output: ${outcome.error.message}`);
+                            // A failed attempt can still be billed (a refused turn reports its
+                            // usage). It counts toward the turn once, whether or not the turn
+                            // goes on, and is reported on its own USAGE_UPDATE: no STEP_FINISHED
+                            // carries it.
+                            if (outcome.usage) {
+                                addUsage(aggregatedUsage, outcome.usage);
+                                yield this.createOutputChunk(turnInput.interactionId, GMIOutputChunkType.USAGE_UPDATE, outcome.usage, {
+                                    metadata: { attemptFailed: true, hop: failedHop.hop, providerId: failedHop.providerId, modelId: failedHop.modelId },
+                                });
+                            }
+                            if (!outcome.retryable) {
+                                throw new GMIError(`LLM provider error: ${outcome.error.message}`, GMIErrorCode.LLM_PROVIDER_ERROR, { turnId, providerId: failedHop.providerId, hop: failedHop.hop });
+                            }
+                            const next = await gateway.resolve(route, failedHop);
+                            if (!next) {
+                                throw new GMIError(`LLM provider error after ${failedHop.hop + 1} hop(s): ${lastHopError.message}`, GMIErrorCode.LLM_PROVIDER_ERROR, { turnId, providerId: failedHop.providerId, hop: failedHop.hop });
+                            }
+                            // Nothing of the failed attempt carries over to the next hop.
+                            currentIterationTextResponse = "";
+                            currentIterationToolCallRequests = [];
+                            currentIterationThinkingBlocks = [];
+                            stepUsage = undefined;
+                            stepFinishReason = null;
+                            stepFinalChunk = undefined;
+                            stepStructuredOutput = undefined;
+                            resolution = next;
+                            continue hopLoop;
                         }
                     }
-                } // End LLM stream
-                // Ensure at least one TEXT_DELTA is emitted for this turn if text was produced
-                if (!textDeltaEmitted && aggregatedResponseText) {
-                    yield this.createOutputChunk(turnInput.interactionId, GMIOutputChunkType.TEXT_DELTA, aggregatedResponseText);
+                    break hopLoop;
                 }
+                if (resolution)
+                    this.turnResolution = resolution;
+                // The step's usage, counted once (D4c).
+                if (stepUsage)
+                    addUsage(aggregatedUsage, stepUsage);
+                // The step boundary (D4d): the step's own text, finish reason, hop and usage.
+                const stepPayload = {
+                    stepIndex: safetyBreak - 1,
+                    text: currentIterationTextResponse,
+                    finishReason: stepFinishReason,
+                    providerId: modelTargetInfo.providerId,
+                    modelId: modelTargetInfo.modelId,
+                    hop: resolution?.hop ?? 0,
+                    ...(stepUsage ? { usage: stepUsage } : {}),
+                    ...(stepFinalChunk?.modelId ? { responseModel: stepFinalChunk.modelId } : {}),
+                    ...(stepFinalChunk?.serviceTier ? { serviceTier: stepFinalChunk.serviceTier } : {}),
+                    ...(stepFinalChunk?.id ? { providerMessageId: stepFinalChunk.id } : {}),
+                    ...(stepFinalChunk?.cacheDiagnostics !== undefined ? { cacheDiagnostics: stepFinalChunk.cacheDiagnostics } : {}),
+                    ...(stepStructuredOutput !== undefined ? { structuredOutput: stepStructuredOutput } : {}),
+                };
+                yield this.createOutputChunk(turnInput.interactionId, GMIOutputChunkType.STEP_FINISHED, stepPayload, {
+                    ...(stepFinishReason ? { finishReason: stepFinishReason } : {}),
+                    ...(stepUsage ? { usage: stepUsage } : {}),
+                });
                 const assistantMessage = {
                     role: 'assistant',
                     content: currentIterationTextResponse || null,
@@ -968,14 +1157,21 @@ export class GMI {
                         toolExecutionResults.push(...this.resultsForUnfinishedToolCalls(currentIterationToolCallRequests, toolExecutionResults.length, callInFlight, error));
                     }
                     // Recorded on success and failure alike, so the history this turn
-                    // leaves answers every call its assistant message declared.
+                    // leaves answers every call its assistant message declared. Each
+                    // recorded result is also published as a TOOL_RESULT chunk (D4e).
                     for (const tcResult of toolExecutionResults) {
                         turnMessages.push(this.conversationHistoryManager.updateWithToolResult(tcResult));
+                        const toolResultPayload = {
+                            toolCallId: tcResult.toolCallId,
+                            name: tcResult.toolName,
+                            result: tcResult.output,
+                            isError: tcResult.isError === true,
+                            ...(tcResult.errorDetails !== undefined ? { errorDetails: tcResult.errorDetails } : {}),
+                        };
+                        yield this.createOutputChunk(turnInput.interactionId, GMIOutputChunkType.TOOL_RESULT, toolResultPayload);
                     }
                     if (toolRoundFailure)
                         throw toolRoundFailure.error;
-                    currentIterationTextResponse = ""; // Reset for next iteration if any
-                    currentIterationToolCallRequests = []; // Reset
                     if (ownsState())
                         this.state = GMIPrimeState.PROCESSING;
                     continue main_processing_loop;
@@ -1004,7 +1200,9 @@ export class GMI {
             return finalTurnOutput; // Return the aggregated output
         }
         catch (error) {
-            const gmiError = createGMIErrorFromError(error, GMIErrorCode.GMI_PROCESSING_ERROR, { turnId }, `Error in GMI turn '${turnId}'.`);
+            // A GMIError keeps its code (an in-band provider error stays
+            // LLM_PROVIDER_ERROR); anything else is a processing error (D4f).
+            const gmiError = createGMIErrorFromError(error, error instanceof GMIError ? error.code : GMIErrorCode.GMI_PROCESSING_ERROR, { turnId }, `Error in GMI turn '${turnId}'.`);
             if (ownsState())
                 this.state = GMIPrimeState.ERRORED;
             lastErrorForOutput = { code: gmiError.code, message: gmiError.message, details: gmiError.details };