@framers/agentos 0.1.113 → 0.1.114

package/dist/api/AgentOSOrchestrator.js

@@ -9,11 +9,12 @@
  */
 import { TaskOutcomeTelemetryManager, evaluateTaskOutcome, resolveTaskOutcomeTelemetryConfig, resolveAdaptiveExecutionConfig, } from './TaskOutcomeTelemetryManager.js';
 import { StreamChunkEmitter } from './StreamChunkEmitter.js';
-import { executeRollingSummaryPhase } from './turn-phases/rolling-summary.js';
+import { executeRollingSummaryPhase, } from './turn-phases/rolling-summary.js';
 import { executePromptProfilePhase } from './turn-phases/prompt-profile.js';
 import { executeLongTermMemoryPhase } from './turn-phases/long-term-memory.js';
 import { assembleConversationHistory } from './turn-phases/conversation-history.js';
 import { AgentOSResponseChunkType, } from './types/AgentOSResponse.js';
+import { AGENTOS_PENDING_EXTERNAL_TOOL_REQUEST_METADATA_KEY } from './types/AgentOSExternalToolRequest.js';
 import { GMIInteractionType, // Added for GMITurnInput
 GMIOutputChunkType, // Added for comparisons
  } from '../cognitive_substrate/IGMI.js';
@@ -23,7 +24,7 @@ import { GMIError, GMIErrorCode } from '../utils/errors.js';
 import { normalizeUsage, snapshotPersonaDetails } from '../core/orchestration/helpers.js';
 import { DEFAULT_PROMPT_PROFILE_CONFIG, } from '../core/prompting/PromptProfileRouter.js';
 import { DEFAULT_ROLLING_SUMMARY_COMPACTION_CONFIG, } 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 { DEFAULT_LONG_TERM_MEMORY_POLICY, hasAnyLongTermMemoryScope, LONG_TERM_MEMORY_POLICY_METADATA_KEY, ORGANIZATION_ID_METADATA_KEY, resolveLongTermMemoryPolicy, } from '../core/conversation/LongTermMemoryPolicy.js';
 import { recordAgentOSToolResultMetrics, recordAgentOSTurnMetrics, recordExceptionOnActiveSpan, runWithSpanContext, startAgentOSSpan, withAgentOSSpan, } from '../core/observability/otel.js';
 // TaskOutcomeKpiWindowEntry imported from types/OrchestratorConfig.ts
 // AdaptiveExecutionDecision imported from TaskOutcomeTelemetryManager
@@ -115,6 +116,17 @@ function resolveTenantRoutingConfig(config) {
         strictOrganizationIsolation: Boolean(config?.strictOrganizationIsolation),
     };
 }
+function buildToolCallChunkMetadata(streamContext, extra) {
+    const metadata = {
+        sessionId: streamContext.sessionId,
+        conversationId: streamContext.conversationId,
+        ...extra,
+    };
+    if (streamContext.organizationId) {
+        metadata.organizationId = streamContext.organizationId;
+    }
+    return metadata;
+}
 /**
  * @class AgentOSOrchestrator
  * @description
@@ -151,7 +163,11 @@ export class AgentOSOrchestrator {
             console.warn('AgentOSOrchestrator already initialized. Skipping re-initialization.');
             return;
         }
-        if (!dependencies.gmiManager || !dependencies.toolOrchestrator || !dependencies.conversationManager || !dependencies.streamingManager || !dependencies.modelProviderManager) {
+        if (!dependencies.gmiManager ||
+            !dependencies.toolOrchestrator ||
+            !dependencies.conversationManager ||
+            !dependencies.streamingManager ||
+            !dependencies.modelProviderManager) {
             throw new GMIError('AgentOSOrchestrator: Missing essential dependencies (gmiManager, toolOrchestrator, conversationManager, streamingManager, modelProviderManager).', GMIErrorCode.CONFIGURATION_ERROR);
         }
         this.config = {
@@ -163,7 +179,10 @@ export class AgentOSOrchestrator {
                 : (config.promptProfileConfig ?? DEFAULT_PROMPT_PROFILE_CONFIG),
             rollingSummaryCompactionConfig: config.rollingSummaryCompactionConfig === null
                 ? null
-                : { ...DEFAULT_ROLLING_SUMMARY_COMPACTION_CONFIG, ...(config.rollingSummaryCompactionConfig ?? {}) },
+                : {
+                    ...DEFAULT_ROLLING_SUMMARY_COMPACTION_CONFIG,
+                    ...(config.rollingSummaryCompactionConfig ?? {}),
+                },
             rollingSummaryCompactionProfilesConfig: config.rollingSummaryCompactionProfilesConfig ?? null,
             rollingSummarySystemPrompt: config.rollingSummarySystemPrompt ?? '',
             rollingSummaryStateKey: config.rollingSummaryStateKey ?? 'rollingSummaryState',
@@ -194,10 +213,7 @@ export class AgentOSOrchestrator {
         const tenantConfig = this.config.tenantRouting;
         if (tenantConfig.mode === 'single_tenant') {
             const fallback = tenantConfig.defaultOrganizationId;
-            if (tenantConfig.strictOrganizationIsolation &&
-                inbound &&
-                fallback &&
-                inbound !== fallback) {
+            if (tenantConfig.strictOrganizationIsolation && inbound && fallback && inbound !== fallback) {
                 throw new GMIError(`organizationId '${inbound}' does not match configured single-tenant org '${fallback}'.`, GMIErrorCode.VALIDATION_ERROR, {
                     mode: tenantConfig.mode,
                     inboundOrganizationId: inbound,
@@ -304,6 +320,100 @@ export class AgentOSOrchestrator {
         });
         return agentOSStreamId;
     }
+    async orchestrateResumedToolResults(pendingRequest, toolResults, options = {}) {
+        this.ensureInitialized();
+        const agentOSStreamId = await this.dependencies.streamingManager.createStream();
+        console.log(`AgentOSOrchestrator: Resuming external tool request for conversation ${pendingRequest.conversationId} on new stream ${agentOSStreamId}.`);
+        const rootSpan = startAgentOSSpan('agentos.resume_external_tool_request', {
+            attributes: {
+                'agentos.stream_id': agentOSStreamId,
+                'agentos.user_id': pendingRequest.userId,
+                'agentos.session_id': pendingRequest.sessionId,
+                'agentos.conversation_id': pendingRequest.conversationId,
+                'agentos.persona_id': pendingRequest.personaId,
+                'agentos.tool_result_count': toolResults.length,
+            },
+        });
+        const run = async () => this._resumeToolResultsInternal(agentOSStreamId, pendingRequest, toolResults, options);
+        const promise = rootSpan ? runWithSpanContext(rootSpan, run) : run();
+        promise
+            .catch(async (criticalError) => {
+            if (rootSpan) {
+                try {
+                    rootSpan.recordException(criticalError);
+                }
+                catch {
+                    // ignore
+                }
+            }
+            console.error(`AgentOSOrchestrator: Critical unhandled error in _resumeToolResultsInternal for stream ${agentOSStreamId}:`, criticalError);
+            try {
+                await this.chunks.pushError(agentOSStreamId, pendingRequest.personaId || 'unknown_persona', pendingRequest.gmiInstanceId || 'orchestrator_resume_critical', GMIErrorCode.INTERNAL_SERVER_ERROR, `A critical external-tool resume error occurred: ${criticalError.message}`, { name: criticalError.name, stack: criticalError.stack });
+                await this.dependencies.streamingManager.closeStream(agentOSStreamId, 'Critical external-tool resume error');
+            }
+            catch (cleanupError) {
+                console.error(`AgentOSOrchestrator: Error during resume critical-error cleanup for stream ${agentOSStreamId}:`, cleanupError);
+            }
+            this.activeStreamContexts.delete(agentOSStreamId);
+        })
+            .finally(() => {
+            try {
+                rootSpan?.end();
+            }
+            catch {
+                // ignore
+            }
+        });
+        return agentOSStreamId;
+    }
+    async _resumeToolResultsInternal(agentOSStreamId, pendingRequest, toolResults, options) {
+        if (!Array.isArray(toolResults) || toolResults.length === 0) {
+            throw new GMIError('At least one tool result is required to resume an external tool request.', GMIErrorCode.VALIDATION_ERROR, { agentOSStreamId, conversationId: pendingRequest.conversationId });
+        }
+        const gmiResult = await withAgentOSSpan('agentos.gmi.resume_get_or_create', async (span) => {
+            span?.setAttribute('agentos.user_id', pendingRequest.userId);
+            span?.setAttribute('agentos.session_id', pendingRequest.sessionId);
+            span?.setAttribute('agentos.conversation_id', pendingRequest.conversationId);
+            span?.setAttribute('agentos.persona_id', pendingRequest.personaId);
+            return this.dependencies.gmiManager.getOrCreateGMIForSession(pendingRequest.userId, pendingRequest.sessionId, pendingRequest.personaId, pendingRequest.conversationId, options.preferredModelId, options.preferredProviderId, options.userApiKeys);
+        });
+        const gmi = gmiResult.gmi;
+        const conversationContext = gmiResult.conversationContext;
+        const currentPersonaId = gmi.getCurrentPrimaryPersonaId();
+        const gmiInstanceIdForChunks = gmi.getGMIId();
+        const storedOrganizationId = conversationContext.getMetadata(ORGANIZATION_ID_METADATA_KEY);
+        const resolvedOrganizationId = this.resolveOrganizationContext(options.organizationId ?? storedOrganizationId);
+        const streamContext = {
+            gmi,
+            userId: pendingRequest.userId,
+            sessionId: pendingRequest.sessionId,
+            personaId: currentPersonaId,
+            conversationId: conversationContext.sessionId,
+            organizationId: resolvedOrganizationId,
+            conversationContext,
+            userApiKeys: options.userApiKeys,
+            processingOptions: {
+                preferredModelId: options.preferredModelId,
+                preferredProviderId: options.preferredProviderId,
+            },
+        };
+        this.activeStreamContexts.set(agentOSStreamId, streamContext);
+        if (gmi.hydrateConversationHistory) {
+            gmi.hydrateConversationHistory(conversationContext.getHistory(undefined, [MessageRole.ERROR, MessageRole.THOUGHT]));
+        }
+        if (gmi.hydrateTurnContext) {
+            gmi.hydrateTurnContext({
+                sessionId: pendingRequest.sessionId,
+                conversationId: conversationContext.sessionId,
+                organizationId: resolvedOrganizationId,
+            });
+        }
+        await this.chunks.pushChunk(agentOSStreamId, AgentOSResponseChunkType.SYSTEM_PROGRESS, gmiInstanceIdForChunks, currentPersonaId, false, {
+            message: `Resuming external tool request for conversation ${conversationContext.sessionId}...`,
+            progressPercentage: 10,
+        });
+        await this.orchestrateToolResults(agentOSStreamId, toolResults);
+    }
     /**
      * Internal processing logic for a turn, designed to be called without await by `orchestrateTurn`.
      * @private
@@ -346,15 +456,25 @@ export class AgentOSOrchestrator {
             gmiInstanceIdForChunks = gmi.getGMIId();
             turnMetricsPersonaId = currentPersonaId;
             const streamContext = {
-                gmi, userId: input.userId, sessionId: input.sessionId, personaId: currentPersonaId,
+                gmi,
+                userId: input.userId,
+                sessionId: input.sessionId,
+                personaId: currentPersonaId,
+                organizationId: organizationIdForMemory,
                 conversationId: conversationContext.sessionId, // Use actual conversation ID from context
-                conversationContext, userApiKeys: input.userApiKeys, processingOptions: input.options
+                conversationContext,
+                userApiKeys: input.userApiKeys,
+                processingOptions: input.options,
             };
             this.activeStreamContexts.set(agentOSStreamId, streamContext);
-            await this.chunks.pushChunk(agentOSStreamId, AgentOSResponseChunkType.SYSTEM_PROGRESS, gmiInstanceIdForChunks, currentPersonaId, false, { message: `Initializing persona ${currentPersonaId}... GMI: ${gmiInstanceIdForChunks}`, progressPercentage: 10 });
+            await this.chunks.pushChunk(agentOSStreamId, AgentOSResponseChunkType.SYSTEM_PROGRESS, gmiInstanceIdForChunks, currentPersonaId, false, {
+                message: `Initializing persona ${currentPersonaId}... GMI: ${gmiInstanceIdForChunks}`,
+                progressPercentage: 10,
+            });
             const gmiInput = this.constructGMITurnInput(agentOSStreamId, input, streamContext);
             let turnPlan = null;
             const resolvedOrganizationId = this.resolveOrganizationContext(input.organizationId);
+            streamContext.organizationId = resolvedOrganizationId;
             if (this.dependencies.turnPlanner) {
                 const planningMessage = gmiInput.type === GMIInteractionType.TEXT && typeof gmiInput.content === 'string'
                     ? gmiInput.content
@@ -475,7 +595,9 @@ export class AgentOSOrchestrator {
                     else if (gmiInput.type === GMIInteractionType.SYSTEM_MESSAGE) {
                         conversationContext.addMessage({
                             role: MessageRole.SYSTEM,
-                            content: typeof gmiInput.content === 'string' ? gmiInput.content : JSON.stringify(gmiInput.content),
+                            content: typeof gmiInput.content === 'string'
+                                ? gmiInput.content
+                                : JSON.stringify(gmiInput.content),
                             metadata: { agentPersonaId: currentPersonaId, source: 'agentos_input_system' },
                         });
                     }
@@ -490,7 +612,8 @@ export class AgentOSOrchestrator {
                 }
             }
             // Build conversationHistoryForPrompt after compaction/routing so it can reflect rolling-summary trimming.
-            const modeForRouting = typeof input.options?.customFlags?.mode === 'string' && input.options.customFlags.mode.trim()
+            const modeForRouting = typeof input.options?.customFlags?.mode === 'string' &&
+                input.options.customFlags.mode.trim()
                 ? input.options.customFlags.mode.trim()
                 : currentPersonaId;
             // --- Rolling summary compaction (delegated to turn-phases/rolling-summary) ---
@@ -504,7 +627,7 @@ export class AgentOSOrchestrator {
                 rollingSummaryStateKey: this.config.rollingSummaryStateKey,
                 modelProviderManager: this.dependencies.modelProviderManager,
             });
-            const { result: rollingSummaryResult, profileId: rollingSummaryProfileId, configForTurn: rollingSummaryConfigForTurn } = rollingSummaryPhase;
+            const { result: rollingSummaryResult, profileId: rollingSummaryProfileId, configForTurn: rollingSummaryConfigForTurn, } = rollingSummaryPhase;
             const rollingSummaryEnabled = rollingSummaryPhase.enabled;
             const rollingSummaryText = rollingSummaryPhase.summaryText;
             if (!gmiInput.metadata) {
@@ -753,20 +876,26 @@ export class AgentOSOrchestrator {
             // Send a final response chunk if not already implicitly sent by an error or final GMI chunk transform.
             // This part needs careful consideration of what `lastGMIOutput` represents here.
             // It should represent the *actual* TReturn from the GMI's processing.
-            const finalGMIStateForResponse = lastGMIOutput ||
-                {
-                    isFinal: true,
-                    responseText: gmi ? 'Processing complete.' : 'Processing ended.',
-                };
+            const finalGMIStateForResponse = lastGMIOutput || {
+                isFinal: true,
+                responseText: gmi ? 'Processing complete.' : 'Processing ended.',
+            };
             if (finalGMIStateForResponse.isFinal === false &&
                 Array.isArray(finalGMIStateForResponse.toolCalls) &&
                 finalGMIStateForResponse.toolCalls.length > 0) {
                 keepStreamContextActive = true;
+                if (conversationContext) {
+                    await this.persistPendingExternalToolRequest(agentOSStreamId, streamContext, gmiInstanceIdForChunks, finalGMIStateForResponse.toolCalls, finalGMIStateForResponse.responseText ||
+                        'Agent requires tool execution before it can complete the turn.');
+                }
                 if (!streamedToolCallRequest) {
                     await this.chunks.pushChunk(agentOSStreamId, AgentOSResponseChunkType.TOOL_CALL_REQUEST, gmiInstanceIdForChunks, currentPersonaId, false, {
                         toolCalls: finalGMIStateForResponse.toolCalls,
                         rationale: finalGMIStateForResponse.responseText ||
                             'Agent requires tool execution before it can complete the turn.',
+                        executionMode: 'external',
+                        requiresExternalToolResult: true,
+                        metadata: buildToolCallChunkMetadata(streamContext),
                     });
                 }
                 return;
@@ -777,7 +906,9 @@ export class AgentOSOrchestrator {
                     totalTokens: normalizedUsage.totalTokens,
                     promptTokens: normalizedUsage.promptTokens,
                     completionTokens: normalizedUsage.completionTokens,
-                    totalCostUSD: typeof normalizedUsage.totalCostUSD === 'number' ? normalizedUsage.totalCostUSD : undefined,
+                    totalCostUSD: typeof normalizedUsage.totalCostUSD === 'number'
+                        ? normalizedUsage.totalCostUSD
+                        : undefined,
                 };
             }
             if (didForceTerminate || Boolean(finalGMIStateForResponse.error)) {
@@ -844,18 +975,23 @@ export class AgentOSOrchestrator {
                     },
                 });
             }
+            if (conversationContext) {
+                await this.clearPendingExternalToolRequest(conversationContext);
+            }
             // 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()) {
+                    if (typeof finalGMIStateForResponse.responseText === 'string' &&
+                        finalGMIStateForResponse.responseText.trim()) {
                         conversationContext.addMessage({
                             role: MessageRole.ASSISTANT,
                             content: finalGMIStateForResponse.responseText,
                             metadata: { agentPersonaId: currentPersonaId, source: 'agentos_output' },
                         });
                     }
-                    else if (finalGMIStateForResponse.toolCalls && finalGMIStateForResponse.toolCalls.length > 0) {
+                    else if (finalGMIStateForResponse.toolCalls &&
+                        finalGMIStateForResponse.toolCalls.length > 0) {
                         conversationContext.addMessage({
                             role: MessageRole.ASSISTANT,
                             content: null,
@@ -885,10 +1021,12 @@ export class AgentOSOrchestrator {
                 usage: normalizedUsage,
                 reasoningTrace: finalGMIStateForResponse.reasoningTrace,
                 error: finalGMIStateForResponse.error,
-                updatedConversationContext: conversationContext ? conversationContext.toJSON() : undefined,
+                updatedConversationContext: conversationContext
+                    ? conversationContext.toJSON()
+                    : undefined,
                 activePersonaDetails: snapshotPersonaDetails(gmi?.getPersona?.()),
             });
-            await this.dependencies.streamingManager.closeStream(agentOSStreamId, "Processing complete.");
+            await this.dependencies.streamingManager.closeStream(agentOSStreamId, 'Processing complete.');
         }
         catch (error) {
             turnMetricsStatus = 'error';
@@ -929,7 +1067,8 @@ export class AgentOSOrchestrator {
                 },
             });
             await this.chunks.pushError(agentOSStreamId, currentPersonaId ?? 'unknown_persona', gmiInstanceIdForChunks, gmiErr.code, gmiErr.message, gmiErr.details);
-            await this.dependencies.streamingManager.closeStream(agentOSStreamId, "Error during turn processing.");
+            await this.clearPendingExternalToolRequest(conversationContext);
+            await this.dependencies.streamingManager.closeStream(agentOSStreamId, 'Error during turn processing.');
         }
         finally {
             recordAgentOSTurnMetrics({
@@ -969,67 +1108,150 @@ export class AgentOSOrchestrator {
      * @throws {GMIError} If stream context is not found or GMI fails to handle result.
      */
     async orchestrateToolResult(agentOSStreamId, toolCallId, toolName, toolOutput, isSuccess, errorMessage) {
+        return this.orchestrateToolResults(agentOSStreamId, [
+            {
+                toolCallId,
+                toolName,
+                toolOutput,
+                isSuccess,
+                errorMessage,
+            },
+        ]);
+    }
+    async orchestrateToolResults(agentOSStreamId, toolResults) {
         this.ensureInitialized();
         const startedAt = Date.now();
+        if (!Array.isArray(toolResults) || toolResults.length === 0) {
+            throw new GMIError('At least one tool result is required to continue the stream.', GMIErrorCode.VALIDATION_ERROR, { agentOSStreamId });
+        }
         const streamContext = this.activeStreamContexts.get(agentOSStreamId);
         if (!streamContext) {
-            const errMsg = `Orchestrator: Received tool result for unknown or inactive streamId: ${agentOSStreamId}. Tool: ${toolName}, CallID: ${toolCallId}`;
+            const errMsg = `Orchestrator: Received tool result for unknown or inactive streamId: ${agentOSStreamId}.`;
             console.error(errMsg);
             // Cannot push to a non-existent stream context. This is a critical failure.
-            throw new GMIError(errMsg, GMIErrorCode.RESOURCE_NOT_FOUND, { agentOSStreamId, toolCallId });
+            throw new GMIError(errMsg, GMIErrorCode.RESOURCE_NOT_FOUND, {
+                agentOSStreamId,
+                toolResults: toolResults.map((toolResult) => ({
+                    toolCallId: toolResult.toolCallId,
+                    toolName: toolResult.toolName,
+                })),
+            });
         }
         const { gmi, userId, personaId, conversationContext, userApiKeys } = streamContext;
         const gmiInstanceIdForChunks = gmi.getGMIId();
-        const toolResultPayload = isSuccess
-            ? { type: 'success', result: toolOutput }
-            : { 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.`);
+        const metricToolName = toolResults.length === 1 ? toolResults[0].toolName : '__batch_external_tools__';
+        const metricToolSuccess = toolResults.every((toolResult) => toolResult.isSuccess);
+        console.log(`AgentOSOrchestrator: Feeding ${toolResults.length} tool result(s) for stream ${agentOSStreamId}, GMI ${gmiInstanceIdForChunks} back to GMI.`);
         try {
             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);
+                span?.setAttribute('agentos.tool_result_count', toolResults.length);
+                span?.setAttribute('agentos.tool_call_ids', JSON.stringify(toolResults.map((toolResult) => toolResult.toolCallId)));
+                span?.setAttribute('agentos.tool_names', JSON.stringify(toolResults.map((toolResult) => toolResult.toolName)));
+                span?.setAttribute('agentos.tool_success', metricToolSuccess);
                 try {
-                    // Emit the tool result itself as a chunk
-                    await this.chunks.pushChunk(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 {
+                    await this.clearPendingExternalToolRequest(conversationContext);
+                    for (const toolResult of toolResults) {
+                        await this.chunks.pushChunk(agentOSStreamId, AgentOSResponseChunkType.TOOL_RESULT_EMISSION, gmiInstanceIdForChunks, personaId, false, {
+                            toolCallId: toolResult.toolCallId,
+                            toolName: toolResult.toolName,
+                            toolResult: toolResult.toolOutput,
+                            isSuccess: toolResult.isSuccess,
+                            errorMessage: toolResult.errorMessage,
+                        });
+                        if (this.config.enableConversationalPersistence && conversationContext) {
                             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 },
+                                content: typeof toolResult.toolOutput === 'string'
+                                    ? toolResult.toolOutput
+                                    : JSON.stringify(toolResult.toolOutput),
+                                tool_call_id: toolResult.toolCallId,
+                                name: toolResult.toolName,
+                                metadata: {
+                                    agentPersonaId: personaId,
+                                    source: 'agentos_tool_result',
+                                    isSuccess: toolResult.isSuccess,
+                                },
                             });
+                        }
+                    }
+                    if (this.config.enableConversationalPersistence && conversationContext) {
+                        try {
                             await withAgentOSSpan('agentos.conversation.save', async (child) => {
                                 child?.setAttribute('agentos.stage', 'tool_result');
                                 child?.setAttribute('agentos.stream_id', agentOSStreamId);
+                                child?.setAttribute('agentos.tool_result_count', toolResults.length);
                                 await this.dependencies.conversationManager.saveConversation(conversationContext);
                             });
                         }
                         catch (persistError) {
-                            console.warn(`AgentOSOrchestrator: Failed to persist tool result to ConversationContext for stream ${agentOSStreamId}.`, persistError);
+                            console.warn(`AgentOSOrchestrator: Failed to persist tool results 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 || {});
+                        child?.setAttribute('agentos.tool_result_count', toolResults.length);
+                        child?.setAttribute('agentos.tool_call_ids', JSON.stringify(toolResults.map((toolResult) => toolResult.toolCallId)));
+                        child?.setAttribute('agentos.tool_names', JSON.stringify(toolResults.map((toolResult) => toolResult.toolName)));
+                        child?.setAttribute('agentos.tool_success', metricToolSuccess);
+                        if (toolResults.length > 1) {
+                            if (!gmi.handleToolResults) {
+                                throw new GMIError(`GMI ${gmiInstanceIdForChunks} does not support batched external tool continuation.`, GMIErrorCode.INVALID_STATE, {
+                                    agentOSStreamId,
+                                    gmiInstanceId: gmiInstanceIdForChunks,
+                                    toolResults: toolResults.map((toolResult) => ({
+                                        toolCallId: toolResult.toolCallId,
+                                        toolName: toolResult.toolName,
+                                    })),
+                                });
+                            }
+                            return gmi.handleToolResults(toolResults.map((toolResult) => ({
+                                toolCallId: toolResult.toolCallId,
+                                toolName: toolResult.toolName,
+                                output: toolResult.isSuccess
+                                    ? toolResult.toolOutput
+                                    : {
+                                        code: 'EXTERNAL_TOOL_ERROR',
+                                        message: toolResult.errorMessage ||
+                                            `External tool '${toolResult.toolName}' execution failed.`,
+                                    },
+                                isError: !toolResult.isSuccess,
+                                errorDetails: toolResult.isSuccess
+                                    ? undefined
+                                    : {
+                                        code: 'EXTERNAL_TOOL_ERROR',
+                                        message: toolResult.errorMessage ||
+                                            `External tool '${toolResult.toolName}' execution failed.`,
+                                    },
+                            })), userId, userApiKeys || {});
+                        }
+                        const [toolResult] = toolResults;
+                        const toolResultPayload = toolResult.isSuccess
+                            ? { type: 'success', result: toolResult.toolOutput }
+                            : {
+                                type: 'error',
+                                error: {
+                                    code: 'EXTERNAL_TOOL_ERROR',
+                                    message: toolResult.errorMessage ||
+                                        `External tool '${toolResult.toolName}' execution failed.`,
+                                },
+                            };
+                        return gmi.handleToolResult(toolResult.toolCallId, toolResult.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.persistPendingExternalToolRequest(agentOSStreamId, streamContext, gmiInstanceIdForChunks, gmiOutputAfterTool.toolCalls, gmiOutputAfterTool.responseText || 'Agent requires further tool execution.');
                         await this.chunks.pushChunk(agentOSStreamId, AgentOSResponseChunkType.TOOL_CALL_REQUEST, gmiInstanceIdForChunks, personaId, false, // Not final, more interaction expected
                         {
                             toolCalls: gmiOutputAfterTool.toolCalls,
                             rationale: gmiOutputAfterTool.responseText || 'Agent requires further tool execution.',
+                            executionMode: 'external',
+                            requiresExternalToolResult: true,
+                            metadata: buildToolCallChunkMetadata(streamContext),
                         });
                         // The orchestrator now waits for another external call to `orchestrateToolResult` for these new calls.
                     }
@@ -1046,7 +1268,8 @@ export class AgentOSOrchestrator {
                                         metadata: { agentPersonaId: personaId, source: 'agentos_output' },
                                     });
                                 }
-                                else if (gmiOutputAfterTool.toolCalls && gmiOutputAfterTool.toolCalls.length > 0) {
+                                else if (gmiOutputAfterTool.toolCalls &&
+                                    gmiOutputAfterTool.toolCalls.length > 0) {
                                     conversationContext.addMessage({
                                         role: MessageRole.ASSISTANT,
                                         content: null,
@@ -1088,6 +1311,7 @@ export class AgentOSOrchestrator {
                     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.clearPendingExternalToolRequest(conversationContext);
                     await this.chunks.pushError(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.');
@@ -1097,20 +1321,70 @@ export class AgentOSOrchestrator {
             recordAgentOSToolResultMetrics({
                 durationMs: Date.now() - startedAt,
                 status: 'ok',
-                toolName,
-                toolSuccess: isSuccess,
+                toolName: metricToolName,
+                toolSuccess: metricToolSuccess,
             });
         }
         catch (error) {
             recordAgentOSToolResultMetrics({
                 durationMs: Date.now() - startedAt,
                 status: 'error',
-                toolName,
-                toolSuccess: isSuccess,
+                toolName: metricToolName,
+                toolSuccess: metricToolSuccess,
             });
             throw error;
         }
     }
+    buildPendingExternalToolRequest(agentOSStreamId, streamContext, gmiInstanceId, toolCalls, rationale) {
+        return {
+            streamId: agentOSStreamId,
+            sessionId: streamContext.sessionId,
+            conversationId: streamContext.conversationId,
+            userId: streamContext.userId,
+            personaId: streamContext.personaId,
+            gmiInstanceId,
+            toolCalls,
+            rationale,
+            requestedAt: new Date().toISOString(),
+        };
+    }
+    async persistPendingExternalToolRequest(agentOSStreamId, streamContext, gmiInstanceId, toolCalls, rationale) {
+        const { conversationContext, personaId } = streamContext;
+        const pendingRequest = this.buildPendingExternalToolRequest(agentOSStreamId, streamContext, gmiInstanceId, toolCalls, rationale);
+        if (toolCalls.length > 0) {
+            conversationContext.addMessage({
+                role: MessageRole.ASSISTANT,
+                content: null,
+                tool_calls: toolCalls,
+                metadata: { agentPersonaId: personaId, source: 'agentos_output_tool_calls' },
+            });
+        }
+        conversationContext.setMetadata(AGENTOS_PENDING_EXTERNAL_TOOL_REQUEST_METADATA_KEY, pendingRequest);
+        if (this.config.enableConversationalPersistence) {
+            await withAgentOSSpan('agentos.conversation.save', async (span) => {
+                span?.setAttribute('agentos.stage', 'pending_external_tool_request');
+                span?.setAttribute('agentos.stream_id', agentOSStreamId);
+                await this.dependencies.conversationManager.saveConversation(conversationContext);
+            });
+        }
+        return pendingRequest;
+    }
+    async clearPendingExternalToolRequest(conversationContext) {
+        if (!conversationContext) {
+            return;
+        }
+        if (conversationContext.getMetadata(AGENTOS_PENDING_EXTERNAL_TOOL_REQUEST_METADATA_KEY) ===
+            undefined) {
+            return;
+        }
+        conversationContext.setMetadata(AGENTOS_PENDING_EXTERNAL_TOOL_REQUEST_METADATA_KEY, undefined);
+        if (this.config.enableConversationalPersistence) {
+            await withAgentOSSpan('agentos.conversation.save', async (span) => {
+                span?.setAttribute('agentos.stage', 'clear_pending_external_tool_request');
+                await this.dependencies.conversationManager.saveConversation(conversationContext);
+            });
+        }
+    }
     /**
      * Processes a GMIOutput object (typically from handleToolResult or the end of a processTurnStream)
      * and pushes relevant chunks to the client stream.
@@ -1128,6 +1402,7 @@ export class AgentOSOrchestrator {
             await this.chunks.pushChunk(agentOSStreamId, AgentOSResponseChunkType.UI_COMMAND, gmiInstanceIdForChunks, personaId, false, { uiCommands: gmiOutput.uiCommands });
         }
         if (gmiOutput.error) {
+            await this.clearPendingExternalToolRequest(conversationContext);
             await this.chunks.pushError(agentOSStreamId, personaId, gmiInstanceIdForChunks, gmiOutput.error.code, gmiOutput.error.message, gmiOutput.error.details);
             // If an error occurs in GMIOutput, it's usually final for this interaction path
             if (gmiOutput.isFinal) {
@@ -1139,6 +1414,7 @@ export class AgentOSOrchestrator {
         // Note: Tool calls from GMIOutput are handled by the calling method (orchestrateTurn or orchestrateToolResult)
         // to decide on looping or yielding ToolCallRequestChunks.
         if (gmiOutput.isFinal && (!gmiOutput.toolCalls || gmiOutput.toolCalls.length === 0)) {
+            await this.clearPendingExternalToolRequest(conversationContext);
             if (this.config.enableConversationalPersistence && conversationContext) {
                 await withAgentOSSpan('agentos.conversation.save', async (span) => {
                     span?.setAttribute('agentos.stage', 'gmi_output_final');
@@ -1160,7 +1436,7 @@ export class AgentOSOrchestrator {
                 activePersonaDetails: snapshotPersonaDetails(gmi.getPersona?.()),
             });
             this.activeStreamContexts.delete(agentOSStreamId);
-            await this.dependencies.streamingManager.closeStream(agentOSStreamId, "Processing complete.");
+            await this.dependencies.streamingManager.closeStream(agentOSStreamId, 'Processing complete.');
         }
     }
     /**
@@ -1185,8 +1461,17 @@ export class AgentOSOrchestrator {
             case GMIOutputChunkType.TOOL_CALL_REQUEST:
                 if (gmiChunk.content && Array.isArray(gmiChunk.content)) {
                     const toolCalls = gmiChunk.content;
+                    const executionMode = gmiChunk.metadata?.executionMode === 'external' ? 'external' : 'internal';
                     await this.chunks.pushChunk(agentOSStreamId, AgentOSResponseChunkType.TOOL_CALL_REQUEST, gmiInstanceIdForChunks, personaId, false, // Tool call request is not final for the AgentOS turn
-                    { toolCalls, rationale: gmiChunk.metadata?.rationale || "Agent requires tool execution." });
+                    {
+                        toolCalls,
+                        rationale: gmiChunk.metadata?.rationale || 'Agent requires tool execution.',
+                        executionMode,
+                        requiresExternalToolResult: typeof gmiChunk.metadata?.requiresExternalToolResult === 'boolean'
+                            ? gmiChunk.metadata.requiresExternalToolResult
+                            : executionMode === 'external',
+                        metadata: buildToolCallChunkMetadata(streamContext, gmiChunk.metadata),
+                    });
                 }
                 break;
             case GMIOutputChunkType.UI_COMMAND:
@@ -1227,13 +1512,19 @@ export class AgentOSOrchestrator {
             gmiId: gmi.getGMIId(),
             // Pass relevant options to GMI if it needs them
             options: options,
+            sessionId,
+            conversationId: streamContext.conversationId,
             // User API keys are handled by GMIManager when fetching/creating GMI,
             // but can be passed in metadata if GMI needs them per-turn for some reason.
             userApiKeys: input.userApiKeys,
             userFeedback: input.userFeedback,
             explicitPersonaSwitchId: input.selectedPersonaId,
             // Task hint can be more sophisticated, based on input analysis
-            taskHint: input.textInput ? 'user_text_query' : (input.visionInputs || input.audioInput) ? 'user_multimodal_query' : 'general_query',
+            taskHint: input.textInput
+                ? 'user_text_query'
+                : input.visionInputs || input.audioInput
+                    ? 'user_multimodal_query'
+                    : 'general_query',
             // GMI.ts specific fields if any, not standard in IGMI.GMITurnInput
             modelSelectionOverrides: {
                 preferredModelId: options?.preferredModelId,
@@ -1246,7 +1537,7 @@ export class AgentOSOrchestrator {
         };
         let type;
         let content;
-        if (input.visionInputs && input.visionInputs.length > 0 || input.audioInput) {
+        if ((input.visionInputs && input.visionInputs.length > 0) || input.audioInput) {
             type = GMIInteractionType.MULTIMODAL_CONTENT;
             const multiModalContent = {};
             if (input.textInput)
@@ -1264,7 +1555,7 @@ export class AgentOSOrchestrator {
         else {
             // Fallback or error if no meaningful input
             type = GMIInteractionType.SYSTEM_MESSAGE; // E.g. an empty ping or keep-alive
-            content = "No primary user input provided for this turn.";
+            content = 'No primary user input provided for this turn.';
             console.warn(`AgentOSOrchestrator: No primary input in AgentOSInput for stream ${agentOSStreamId}. Sending as system message to GMI.`);
         }
         return {
@@ -1291,7 +1582,7 @@ export class AgentOSOrchestrator {
         // Notify and close streams managed by StreamingManager for contexts held here
         for (const streamId of this.activeStreamContexts.keys()) {
             try {
-                await this.dependencies.streamingManager.closeStream(streamId, "Orchestrator shutting down.");
+                await this.dependencies.streamingManager.closeStream(streamId, 'Orchestrator shutting down.');
             }
             catch (e) {
                 console.error(`AgentOSOrchestrator: Error closing stream ${streamId} during shutdown: ${e.message}`);