@framers/agentos 0.1.13 → 0.1.14

package/dist/api/AgentOSOrchestrator.js

@@ -18,6 +18,7 @@ import { normalizeUsage, snapshotPersonaDetails } from '../core/orchestration/he
 import { DEFAULT_PROMPT_PROFILE_CONFIG, selectPromptProfile, } from '../core/prompting/PromptProfileRouter.js';
 import { DEFAULT_ROLLING_SUMMARY_COMPACTION_CONFIG, maybeCompactConversationMessages, } from '../core/conversation/RollingSummaryCompactor.js';
 import { DEFAULT_LONG_TERM_MEMORY_POLICY, hasAnyLongTermMemoryScope, LONG_TERM_MEMORY_POLICY_METADATA_KEY, resolveLongTermMemoryPolicy, } from '../core/conversation/LongTermMemoryPolicy.js';
+import { getActiveTraceMetadata, recordAgentOSToolResultMetrics, recordAgentOSTurnMetrics, recordExceptionOnActiveSpan, runWithSpanContext, shouldIncludeTraceInAgentOSResponses, startAgentOSSpan, withAgentOSSpan, } from '../core/observability/otel.js';
 function normalizeMode(value) {
     return (value || '').trim().toLowerCase();
 }
@@ -150,6 +151,16 @@ export class AgentOSOrchestrator {
             if (!baseChunk.metadata.language)
                 baseChunk.metadata.language = ctx.languageNegotiation;
         }
+        if (shouldIncludeTraceInAgentOSResponses() &&
+            (type === AgentOSResponseChunkType.METADATA_UPDATE ||
+                type === AgentOSResponseChunkType.FINAL_RESPONSE ||
+                type === AgentOSResponseChunkType.ERROR)) {
+            const traceMeta = getActiveTraceMetadata();
+            if (traceMeta) {
+                baseChunk.metadata = baseChunk.metadata || {};
+                baseChunk.metadata.trace = traceMeta;
+            }
+        }
         let chunk;
         switch (type) {
             case AgentOSResponseChunkType.TEXT_DELTA:
@@ -290,18 +301,46 @@ export class AgentOSOrchestrator {
         this.ensureInitialized();
         const agentOSStreamId = await this.dependencies.streamingManager.createStream();
         console.log(`AgentOSOrchestrator: Starting turn for AgentOS Stream ${agentOSStreamId}, User ${input.userId}, Session ${input.sessionId}`);
+        const rootSpan = startAgentOSSpan('agentos.turn', {
+            attributes: {
+                'agentos.stream_id': agentOSStreamId,
+                'agentos.user_id': input.userId,
+                'agentos.session_id': input.sessionId,
+                'agentos.conversation_id': input.conversationId ?? '',
+                'agentos.persona_id': input.selectedPersonaId ?? '',
+            },
+        });
+        const run = async () => this._processTurnInternal(agentOSStreamId, input);
+        const promise = rootSpan ? runWithSpanContext(rootSpan, run) : run();
         // Execute the turn processing asynchronously without awaiting it here,
         // so this method can return the streamId quickly.
-        this._processTurnInternal(agentOSStreamId, input).catch(async (criticalError) => {
+        promise
+            .catch(async (criticalError) => {
+            if (rootSpan) {
+                try {
+                    rootSpan.recordException(criticalError);
+                }
+                catch {
+                    // ignore
+                }
+            }
             console.error(`AgentOSOrchestrator: Critical unhandled error in _processTurnInternal for stream ${agentOSStreamId}:`, criticalError);
             try {
                 await this.pushErrorChunk(agentOSStreamId, input.selectedPersonaId || 'unknown_persona', 'orchestrator_critical', GMIErrorCode.INTERNAL_SERVER_ERROR, `A critical orchestration error occurred: ${criticalError.message}`, { name: criticalError.name, stack: criticalError.stack });
-                await this.dependencies.streamingManager.closeStream(agentOSStreamId, "Critical orchestrator error");
+                await this.dependencies.streamingManager.closeStream(agentOSStreamId, 'Critical orchestrator error');
             }
             catch (cleanupError) {
                 console.error(`AgentOSOrchestrator: Error during critical error cleanup for stream ${agentOSStreamId}:`, cleanupError);
             }
             this.activeStreamContexts.delete(agentOSStreamId);
+        })
+            .finally(() => {
+            try {
+                rootSpan?.end();
+            }
+            catch {
+                // ignore
+            }
         });
         return agentOSStreamId;
     }
@@ -310,24 +349,38 @@ export class AgentOSOrchestrator {
      * @private
      */
     async _processTurnInternal(agentOSStreamId, input) {
-        if (!input.selectedPersonaId) {
-            throw new GMIError('AgentOSOrchestrator requires a selectedPersonaId on AgentOSInput.', GMIErrorCode.VALIDATION_ERROR);
-        }
+        const turnStartedAt = Date.now();
+        let turnMetricsStatus = 'ok';
+        let turnMetricsPersonaId = input.selectedPersonaId;
+        let turnMetricsUsage;
+        const selectedPersonaId = input.selectedPersonaId;
         let gmi;
         let conversationContext;
         let currentPersonaId = input.selectedPersonaId;
         let gmiInstanceIdForChunks = 'gmi_pending_init';
         let organizationIdForMemory;
         let longTermMemoryPolicy = null;
+        let didForceTerminate = false;
         try {
-            const gmiResult = await this.dependencies.gmiManager.getOrCreateGMIForSession(input.userId, input.sessionId, // This is AgentOS's session ID, GMI might have its own.
-            input.selectedPersonaId, // Can be undefined, GMIManager handles default.
-            input.conversationId, // Can be undefined, GMIManager might default to sessionId.
-            input.options?.preferredModelId, input.options?.preferredProviderId, input.userApiKeys);
+            if (!selectedPersonaId) {
+                throw new GMIError('AgentOSOrchestrator requires a selectedPersonaId on AgentOSInput.', GMIErrorCode.VALIDATION_ERROR);
+            }
+            const gmiResult = await withAgentOSSpan('agentos.gmi.get_or_create', async (span) => {
+                span?.setAttribute('agentos.user_id', input.userId);
+                span?.setAttribute('agentos.session_id', input.sessionId);
+                span?.setAttribute('agentos.persona_id', selectedPersonaId);
+                if (typeof input.conversationId === 'string' && input.conversationId.trim()) {
+                    span?.setAttribute('agentos.conversation_id', input.conversationId.trim());
+                }
+                return this.dependencies.gmiManager.getOrCreateGMIForSession(input.userId, input.sessionId, // This is AgentOS's session ID, GMI might have its own.
+                selectedPersonaId, input.conversationId, // Can be undefined, GMIManager might default to sessionId.
+                input.options?.preferredModelId, input.options?.preferredProviderId, input.userApiKeys);
+            });
             gmi = gmiResult.gmi;
             conversationContext = gmiResult.conversationContext;
             currentPersonaId = gmi.getCurrentPrimaryPersonaId(); // Get actual personaId from GMI
             gmiInstanceIdForChunks = gmi.getGMIId();
+            turnMetricsPersonaId = currentPersonaId;
             const streamContext = {
                 gmi, userId: input.userId, sessionId: input.sessionId, personaId: currentPersonaId,
                 conversationId: conversationContext.sessionId, // Use actual conversation ID from context
@@ -369,6 +422,7 @@ export class AgentOSOrchestrator {
             // Persist inbound user/system message to ConversationContext BEFORE any LLM call so persona switches
             // and restarts preserve memory, even if the LLM fails.
             if (this.config.enableConversationalPersistence && conversationContext) {
+                const persistContext = conversationContext;
                 try {
                     if (gmiInput.type === GMIInteractionType.TEXT && typeof gmiInput.content === 'string') {
                         conversationContext.addMessage({
@@ -393,7 +447,11 @@ export class AgentOSOrchestrator {
                             metadata: { agentPersonaId: currentPersonaId, source: 'agentos_input_system' },
                         });
                     }
-                    await this.dependencies.conversationManager.saveConversation(conversationContext);
+                    await withAgentOSSpan('agentos.conversation.save', async (span) => {
+                        span?.setAttribute('agentos.stage', 'inbound');
+                        span?.setAttribute('agentos.stream_id', agentOSStreamId);
+                        await this.dependencies.conversationManager.saveConversation(persistContext);
+                    });
                 }
                 catch (persistError) {
                     console.warn(`AgentOSOrchestrator: Failed to persist inbound message to ConversationContext for stream ${agentOSStreamId}.`, persistError);
@@ -615,8 +673,13 @@ export class AgentOSOrchestrator {
             }
             // Persist any compaction/router metadata updates prior to the main LLM call.
             if (this.config.enableConversationalPersistence && conversationContext) {
+                const persistContext = conversationContext;
                 try {
-                    await this.dependencies.conversationManager.saveConversation(conversationContext);
+                    await withAgentOSSpan('agentos.conversation.save', async (span) => {
+                        span?.setAttribute('agentos.stage', 'metadata');
+                        span?.setAttribute('agentos.stream_id', agentOSStreamId);
+                        await this.dependencies.conversationManager.saveConversation(persistContext);
+                    });
                 }
                 catch (metadataPersistError) {
                     console.warn(`AgentOSOrchestrator: Failed to persist conversation metadata updates for stream ${agentOSStreamId}.`, metadataPersistError);
@@ -681,7 +744,6 @@ export class AgentOSOrchestrator {
             let lastGMIOutput; // To store the result from handleToolResult or final processTurnStream result
             while (continueProcessing && currentToolCallIteration < this.config.maxToolCallIterations) {
                 currentToolCallIteration++;
-                let gmiStreamIterator;
                 if (lastGMIOutput?.toolCalls && lastGMIOutput.toolCalls.length > 0) {
                     // This case should be handled by external call to orchestrateToolResult.
                     // If GMI's handleToolResult itself requests more tools *synchronously* in its GMIOutput,
@@ -708,33 +770,41 @@ export class AgentOSOrchestrator {
                     continueProcessing = false;
                     break;
                 }
-                else {
-                    gmiStreamIterator = gmi.processTurnStream(gmiInput); // For initial turn or if GMI internally continues
+                if (!gmi) {
+                    throw new Error('AgentOSOrchestrator: GMI not initialized (unexpected).');
                 }
-                // Consume the async generator manually so we can capture its return value (GMIOutput).
-                // `for await...of` does not expose the generator return value, which caused placeholder
-                // FINAL_RESPONSE payloads (e.g. "Turn processing sequence complete.").
-                while (true) {
-                    const { value, done } = await gmiStreamIterator.next();
-                    if (done) {
-                        lastGMIOutput = value;
-                        continueProcessing = false;
-                        break;
-                    }
-                    const gmiChunk = value;
-                    await this.transformAndPushGMIChunk(agentOSStreamId, streamContext, gmiChunk);
-                    // NOTE: Tool calls may be executed internally by the GMI/tool orchestrator. Do not stop
-                    // streaming on TOOL_CALL_REQUEST; treat it as informational for observers/UI.
-                    if (gmiChunk.isFinal || gmiChunk.type === GMIOutputChunkType.FINAL_RESPONSE_MARKER) {
-                        // Still keep consuming to capture the generator's return value.
-                        continueProcessing = false;
+                const gmiForTurn = gmi;
+                await withAgentOSSpan('agentos.gmi.process_turn_stream', async (span) => {
+                    span?.setAttribute('agentos.stream_id', agentOSStreamId);
+                    span?.setAttribute('agentos.gmi_id', gmiInstanceIdForChunks);
+                    span?.setAttribute('agentos.tool_call_iteration', currentToolCallIteration);
+                    const gmiStreamIterator = gmiForTurn.processTurnStream(gmiInput); // For initial turn or if GMI internally continues
+                    // Consume the async generator manually so we can capture its return value (GMIOutput).
+                    // `for await...of` does not expose the generator return value, which caused placeholder
+                    // FINAL_RESPONSE payloads (e.g. "Turn processing sequence complete.").
+                    while (true) {
+                        const { value, done } = await gmiStreamIterator.next();
+                        if (done) {
+                            lastGMIOutput = value;
+                            continueProcessing = false;
+                            break;
+                        }
+                        const gmiChunk = value;
+                        await this.transformAndPushGMIChunk(agentOSStreamId, streamContext, gmiChunk);
+                        // NOTE: Tool calls may be executed internally by the GMI/tool orchestrator. Do not stop
+                        // streaming on TOOL_CALL_REQUEST; treat it as informational for observers/UI.
+                        if (gmiChunk.isFinal || gmiChunk.type === GMIOutputChunkType.FINAL_RESPONSE_MARKER) {
+                            // Still keep consuming to capture the generator's return value.
+                            continueProcessing = false;
+                        }
                     }
-                }
+                });
                 if (!continueProcessing)
                     break; // Exit the while loop
             } // End while
             if (currentToolCallIteration >= this.config.maxToolCallIterations && continueProcessing) {
                 console.warn(`AgentOSOrchestrator: Max tool call iterations reached for stream ${agentOSStreamId}. Forcing termination.`);
+                didForceTerminate = true;
                 await this.pushErrorChunk(agentOSStreamId, currentPersonaId, gmiInstanceIdForChunks, GMIErrorCode.RATE_LIMIT_EXCEEDED, // Or a more specific code
                 'Agent reached maximum tool call iterations.', { maxIterations: this.config.maxToolCallIterations });
             }
@@ -750,8 +820,21 @@ export class AgentOSOrchestrator {
                     isFinal: true,
                     responseText: gmi ? 'Processing complete.' : 'Processing ended.',
                 };
+            const normalizedUsage = normalizeUsage(finalGMIStateForResponse.usage);
+            if (normalizedUsage) {
+                turnMetricsUsage = {
+                    totalTokens: normalizedUsage.totalTokens,
+                    promptTokens: normalizedUsage.promptTokens,
+                    completionTokens: normalizedUsage.completionTokens,
+                    totalCostUSD: typeof normalizedUsage.totalCostUSD === 'number' ? normalizedUsage.totalCostUSD : undefined,
+                };
+            }
+            if (didForceTerminate || Boolean(finalGMIStateForResponse.error)) {
+                turnMetricsStatus = 'error';
+            }
             // Persist assistant output into ConversationContext for durable memory / prompt reconstruction.
             if (this.config.enableConversationalPersistence && conversationContext) {
+                const persistContext = conversationContext;
                 try {
                     if (typeof finalGMIStateForResponse.responseText === 'string' && finalGMIStateForResponse.responseText.trim()) {
                         conversationContext.addMessage({
@@ -768,7 +851,11 @@ export class AgentOSOrchestrator {
                             metadata: { agentPersonaId: currentPersonaId, source: 'agentos_output_tool_calls' },
                         });
                     }
-                    await this.dependencies.conversationManager.saveConversation(conversationContext);
+                    await withAgentOSSpan('agentos.conversation.save', async (span) => {
+                        span?.setAttribute('agentos.stage', 'assistant_output');
+                        span?.setAttribute('agentos.stream_id', agentOSStreamId);
+                        await this.dependencies.conversationManager.saveConversation(persistContext);
+                    });
                 }
                 catch (persistError) {
                     console.warn(`AgentOSOrchestrator: Failed to persist assistant output to ConversationContext for stream ${agentOSStreamId}.`, persistError);
@@ -783,7 +870,7 @@ export class AgentOSOrchestrator {
                 finalUiCommands: finalGMIStateForResponse.uiCommands,
                 audioOutput: finalGMIStateForResponse.audioOutput,
                 imageOutput: finalGMIStateForResponse.imageOutput,
-                usage: normalizeUsage(finalGMIStateForResponse.usage),
+                usage: normalizedUsage,
                 reasoningTrace: finalGMIStateForResponse.reasoningTrace,
                 error: finalGMIStateForResponse.error,
                 updatedConversationContext: conversationContext ? conversationContext.toJSON() : undefined,
@@ -792,13 +879,21 @@ export class AgentOSOrchestrator {
             await this.dependencies.streamingManager.closeStream(agentOSStreamId, "Processing complete.");
         }
         catch (error) {
+            turnMetricsStatus = 'error';
+            recordExceptionOnActiveSpan(error, `Error in orchestrateTurn for stream ${agentOSStreamId}`);
             const gmiErr = GMIError.wrap?.(error, GMIErrorCode.GMI_PROCESSING_ERROR, `Error in orchestrateTurn for stream ${agentOSStreamId}`) ||
                 new GMIError(`Error in orchestrateTurn for stream ${agentOSStreamId}: ${error.message}`, GMIErrorCode.GMI_PROCESSING_ERROR, error);
             console.error(`AgentOSOrchestrator: Error during _processTurnInternal for stream ${agentOSStreamId}:`, gmiErr);
-            await this.pushErrorChunk(agentOSStreamId, currentPersonaId, gmiInstanceIdForChunks, gmiErr.code, gmiErr.message, gmiErr.details);
+            await this.pushErrorChunk(agentOSStreamId, currentPersonaId ?? 'unknown_persona', gmiInstanceIdForChunks, gmiErr.code, gmiErr.message, gmiErr.details);
             await this.dependencies.streamingManager.closeStream(agentOSStreamId, "Error during turn processing.");
         }
         finally {
+            recordAgentOSTurnMetrics({
+                durationMs: Date.now() - turnStartedAt,
+                status: turnMetricsStatus,
+                personaId: turnMetricsPersonaId,
+                usage: turnMetricsUsage,
+            });
             // Stream is closed explicitly in the success/error paths; this finally block always
             // clears internal state to avoid leaks.
             this.activeStreamContexts.delete(agentOSStreamId);
@@ -823,6 +918,7 @@ export class AgentOSOrchestrator {
      */
     async orchestrateToolResult(agentOSStreamId, toolCallId, toolName, toolOutput, isSuccess, errorMessage) {
         this.ensureInitialized();
+        const startedAt = Date.now();
         const streamContext = this.activeStreamContexts.get(agentOSStreamId);
         if (!streamContext) {
             const errMsg = `Orchestrator: Received tool result for unknown or inactive streamId: ${agentOSStreamId}. Tool: ${toolName}, CallID: ${toolCallId}`;
@@ -837,86 +933,128 @@ export class AgentOSOrchestrator {
             : { type: 'error', error: { code: 'EXTERNAL_TOOL_ERROR', message: errorMessage || `External tool '${toolName}' execution failed.` } };
         console.log(`AgentOSOrchestrator: Feeding tool result for stream ${agentOSStreamId}, GMI ${gmiInstanceIdForChunks}, tool call ${toolCallId} (${toolName}) back to GMI.`);
         try {
-            // Emit the tool result itself as a chunk
-            await this.pushChunkToStream(agentOSStreamId, AgentOSResponseChunkType.TOOL_RESULT_EMISSION, gmiInstanceIdForChunks, personaId, false, { toolCallId, toolName, toolResult: toolOutput, isSuccess, errorMessage });
-            // Persist tool result into ConversationContext for durable memory / prompt reconstruction.
-            if (this.config.enableConversationalPersistence && conversationContext) {
+            await withAgentOSSpan('agentos.tool_result', async (span) => {
+                span?.setAttribute('agentos.stream_id', agentOSStreamId);
+                span?.setAttribute('agentos.gmi_id', gmiInstanceIdForChunks);
+                span?.setAttribute('agentos.tool_call_id', toolCallId);
+                span?.setAttribute('agentos.tool_name', toolName);
+                span?.setAttribute('agentos.tool_success', isSuccess);
                 try {
-                    conversationContext.addMessage({
-                        role: MessageRole.TOOL,
-                        content: typeof toolOutput === 'string' ? toolOutput : JSON.stringify(toolOutput),
-                        tool_call_id: toolCallId,
-                        name: toolName,
-                        metadata: { agentPersonaId: personaId, source: 'agentos_tool_result', isSuccess },
-                    });
-                    await this.dependencies.conversationManager.saveConversation(conversationContext);
-                }
-                catch (persistError) {
-                    console.warn(`AgentOSOrchestrator: Failed to persist tool result to ConversationContext for stream ${agentOSStreamId}.`, persistError);
-                }
-            }
-            // GMI processes the tool result and gives a *final output for that step*
-            const gmiOutputAfterTool = await gmi.handleToolResult(toolCallId, toolName, toolResultPayload, userId, userApiKeys || {});
-            // Process the GMIOutput (which is not a stream of chunks)
-            await this.processGMIOutput(agentOSStreamId, streamContext, gmiOutputAfterTool, false);
-            // If GMIOutput indicates further tool calls are needed by the GMI
-            if (gmiOutputAfterTool.toolCalls && gmiOutputAfterTool.toolCalls.length > 0) {
-                await this.pushChunkToStream(agentOSStreamId, AgentOSResponseChunkType.TOOL_CALL_REQUEST, gmiInstanceIdForChunks, personaId, false, // Not final, more interaction expected
-                { toolCalls: gmiOutputAfterTool.toolCalls, rationale: gmiOutputAfterTool.responseText || "Agent requires further tool execution." });
-                // The orchestrator now waits for another external call to `orchestrateToolResult` for these new calls.
-            }
-            else if (gmiOutputAfterTool.isFinal) {
-                if (this.config.enableConversationalPersistence && conversationContext) {
-                    try {
-                        if (typeof gmiOutputAfterTool.responseText === 'string' && gmiOutputAfterTool.responseText.trim()) {
+                    // Emit the tool result itself as a chunk
+                    await this.pushChunkToStream(agentOSStreamId, AgentOSResponseChunkType.TOOL_RESULT_EMISSION, gmiInstanceIdForChunks, personaId, false, { toolCallId, toolName, toolResult: toolOutput, isSuccess, errorMessage });
+                    // Persist tool result into ConversationContext for durable memory / prompt reconstruction.
+                    if (this.config.enableConversationalPersistence && conversationContext) {
+                        try {
                             conversationContext.addMessage({
-                                role: MessageRole.ASSISTANT,
-                                content: gmiOutputAfterTool.responseText,
-                                metadata: { agentPersonaId: personaId, source: 'agentos_output' },
+                                role: MessageRole.TOOL,
+                                content: typeof toolOutput === 'string' ? toolOutput : JSON.stringify(toolOutput),
+                                tool_call_id: toolCallId,
+                                name: toolName,
+                                metadata: { agentPersonaId: personaId, source: 'agentos_tool_result', isSuccess },
                             });
-                        }
-                        else if (gmiOutputAfterTool.toolCalls && gmiOutputAfterTool.toolCalls.length > 0) {
-                            conversationContext.addMessage({
-                                role: MessageRole.ASSISTANT,
-                                content: null,
-                                tool_calls: gmiOutputAfterTool.toolCalls,
-                                metadata: { agentPersonaId: personaId, source: 'agentos_output_tool_calls' },
+                            await withAgentOSSpan('agentos.conversation.save', async (child) => {
+                                child?.setAttribute('agentos.stage', 'tool_result');
+                                child?.setAttribute('agentos.stream_id', agentOSStreamId);
+                                await this.dependencies.conversationManager.saveConversation(conversationContext);
                             });
                         }
-                        await this.dependencies.conversationManager.saveConversation(conversationContext);
+                        catch (persistError) {
+                            console.warn(`AgentOSOrchestrator: Failed to persist tool result to ConversationContext for stream ${agentOSStreamId}.`, persistError);
+                        }
+                    }
+                    // GMI processes the tool result and gives a *final output for that step*
+                    const gmiOutputAfterTool = await withAgentOSSpan('agentos.gmi.handle_tool_result', async (child) => {
+                        child?.setAttribute('agentos.stream_id', agentOSStreamId);
+                        child?.setAttribute('agentos.tool_call_id', toolCallId);
+                        child?.setAttribute('agentos.tool_name', toolName);
+                        child?.setAttribute('agentos.tool_success', isSuccess);
+                        return gmi.handleToolResult(toolCallId, toolName, toolResultPayload, userId, userApiKeys || {});
+                    });
+                    // Process the GMIOutput (which is not a stream of chunks)
+                    await this.processGMIOutput(agentOSStreamId, streamContext, gmiOutputAfterTool, false);
+                    // If GMIOutput indicates further tool calls are needed by the GMI
+                    if (gmiOutputAfterTool.toolCalls && gmiOutputAfterTool.toolCalls.length > 0) {
+                        await this.pushChunkToStream(agentOSStreamId, AgentOSResponseChunkType.TOOL_CALL_REQUEST, gmiInstanceIdForChunks, personaId, false, // Not final, more interaction expected
+                        {
+                            toolCalls: gmiOutputAfterTool.toolCalls,
+                            rationale: gmiOutputAfterTool.responseText || 'Agent requires further tool execution.',
+                        });
+                        // The orchestrator now waits for another external call to `orchestrateToolResult` for these new calls.
                     }
-                    catch (persistError) {
-                        console.warn(`AgentOSOrchestrator: Failed to persist assistant output after tool result for stream ${agentOSStreamId}.`, persistError);
+                    else if (gmiOutputAfterTool.isFinal) {
+                        if (this.config.enableConversationalPersistence && conversationContext) {
+                            try {
+                                if (typeof gmiOutputAfterTool.responseText === 'string' &&
+                                    gmiOutputAfterTool.responseText.trim()) {
+                                    conversationContext.addMessage({
+                                        role: MessageRole.ASSISTANT,
+                                        content: gmiOutputAfterTool.responseText,
+                                        metadata: { agentPersonaId: personaId, source: 'agentos_output' },
+                                    });
+                                }
+                                else if (gmiOutputAfterTool.toolCalls && gmiOutputAfterTool.toolCalls.length > 0) {
+                                    conversationContext.addMessage({
+                                        role: MessageRole.ASSISTANT,
+                                        content: null,
+                                        tool_calls: gmiOutputAfterTool.toolCalls,
+                                        metadata: { agentPersonaId: personaId, source: 'agentos_output_tool_calls' },
+                                    });
+                                }
+                                await withAgentOSSpan('agentos.conversation.save', async (child) => {
+                                    child?.setAttribute('agentos.stage', 'assistant_output_after_tool');
+                                    child?.setAttribute('agentos.stream_id', agentOSStreamId);
+                                    await this.dependencies.conversationManager.saveConversation(conversationContext);
+                                });
+                            }
+                            catch (persistError) {
+                                console.warn(`AgentOSOrchestrator: Failed to persist assistant output after tool result for stream ${agentOSStreamId}.`, persistError);
+                            }
+                        }
+                        // If it's final and no more tool calls, the interaction for this GMI processing cycle might be done.
+                        // Push a final response marker or the already pushed final data from processGMIOutput takes precedence.
+                        await this.pushChunkToStream(agentOSStreamId, AgentOSResponseChunkType.FINAL_RESPONSE, gmiInstanceIdForChunks, personaId, true, {
+                            finalResponseText: gmiOutputAfterTool.responseText,
+                            finalToolCalls: gmiOutputAfterTool.toolCalls,
+                            finalUiCommands: gmiOutputAfterTool.uiCommands,
+                            audioOutput: gmiOutputAfterTool.audioOutput,
+                            imageOutput: gmiOutputAfterTool.imageOutput,
+                            usage: normalizeUsage(gmiOutputAfterTool.usage),
+                            reasoningTrace: gmiOutputAfterTool.reasoningTrace,
+                            error: gmiOutputAfterTool.error,
+                            updatedConversationContext: conversationContext.toJSON(),
+                            activePersonaDetails: snapshotPersonaDetails(gmi.getPersona?.()),
+                        });
+                        this.activeStreamContexts.delete(agentOSStreamId); // Clean up context for this completed flow
+                        await this.dependencies.streamingManager.closeStream(agentOSStreamId, 'Tool processing complete and final response generated.');
                     }
+                    // If not final and no tool calls, the GMI might have provided intermediate text.
+                    // The stream remains open for further GMI internal processing or new user input.
                 }
-                // If it's final and no more tool calls, the interaction for this GMI processing cycle might be done.
-                // Push a final response marker or the already pushed final data from processGMIOutput takes precedence.
-                await this.pushChunkToStream(agentOSStreamId, AgentOSResponseChunkType.FINAL_RESPONSE, gmiInstanceIdForChunks, personaId, true, {
-                    finalResponseText: gmiOutputAfterTool.responseText,
-                    finalToolCalls: gmiOutputAfterTool.toolCalls,
-                    finalUiCommands: gmiOutputAfterTool.uiCommands,
-                    audioOutput: gmiOutputAfterTool.audioOutput,
-                    imageOutput: gmiOutputAfterTool.imageOutput,
-                    usage: normalizeUsage(gmiOutputAfterTool.usage),
-                    reasoningTrace: gmiOutputAfterTool.reasoningTrace,
-                    error: gmiOutputAfterTool.error,
-                    updatedConversationContext: conversationContext.toJSON(),
-                    activePersonaDetails: snapshotPersonaDetails(gmi.getPersona?.()),
-                });
-                this.activeStreamContexts.delete(agentOSStreamId); // Clean up context for this completed flow
-                await this.dependencies.streamingManager.closeStream(agentOSStreamId, "Tool processing complete and final response generated.");
-            }
-            // If not final and no tool calls, the GMI might have provided intermediate text.
-            // The stream remains open for further GMI internal processing or new user input.
+                catch (error) {
+                    const gmiErr = GMIError.wrap?.(error, GMIErrorCode.TOOL_ERROR, `Error in orchestrateToolResult for stream ${agentOSStreamId}`) ||
+                        new GMIError(`Error in orchestrateToolResult for stream ${agentOSStreamId}: ${error.message}`, GMIErrorCode.TOOL_ERROR, error);
+                    console.error(`AgentOSOrchestrator: Critical error processing tool result for stream ${agentOSStreamId}:`, gmiErr);
+                    await this.pushErrorChunk(agentOSStreamId, personaId, gmiInstanceIdForChunks, gmiErr.code, gmiErr.message, gmiErr.details);
+                    this.activeStreamContexts.delete(agentOSStreamId);
+                    await this.dependencies.streamingManager.closeStream(agentOSStreamId, 'Critical error during tool result processing.');
+                    throw gmiErr; // Re-throw to signal failure to caller if necessary
+                }
+            });
+            recordAgentOSToolResultMetrics({
+                durationMs: Date.now() - startedAt,
+                status: 'ok',
+                toolName,
+                toolSuccess: isSuccess,
+            });
         }
         catch (error) {
-            const gmiErr = GMIError.wrap?.(error, GMIErrorCode.TOOL_ERROR, `Error in orchestrateToolResult for stream ${agentOSStreamId}`) ||
-                new GMIError(`Error in orchestrateToolResult for stream ${agentOSStreamId}: ${error.message}`, GMIErrorCode.TOOL_ERROR, error);
-            console.error(`AgentOSOrchestrator: Critical error processing tool result for stream ${agentOSStreamId}:`, gmiErr);
-            await this.pushErrorChunk(agentOSStreamId, personaId, gmiInstanceIdForChunks, gmiErr.code, gmiErr.message, gmiErr.details);
-            this.activeStreamContexts.delete(agentOSStreamId);
-            await this.dependencies.streamingManager.closeStream(agentOSStreamId, "Critical error during tool result processing.");
-            throw gmiErr; // Re-throw to signal failure to caller if necessary
+            recordAgentOSToolResultMetrics({
+                durationMs: Date.now() - startedAt,
+                status: 'error',
+                toolName,
+                toolSuccess: isSuccess,
+            });
+            throw error;
         }
     }
     /**
@@ -948,7 +1086,11 @@ export class AgentOSOrchestrator {
         // to decide on looping or yielding ToolCallRequestChunks.
         if (gmiOutput.isFinal && (!gmiOutput.toolCalls || gmiOutput.toolCalls.length === 0)) {
             if (this.config.enableConversationalPersistence && conversationContext) {
-                await this.dependencies.conversationManager.saveConversation(conversationContext);
+                await withAgentOSSpan('agentos.conversation.save', async (span) => {
+                    span?.setAttribute('agentos.stage', 'gmi_output_final');
+                    span?.setAttribute('agentos.stream_id', agentOSStreamId);
+                    await this.dependencies.conversationManager.saveConversation(conversationContext);
+                });
             }
             // This is a final response without further tool calls
             await this.pushChunkToStream(agentOSStreamId, AgentOSResponseChunkType.FINAL_RESPONSE, gmiInstanceIdForChunks, personaId, true, {