@framers/agentos 0.1.112 → 0.1.114

package/dist/api/AgentOS.js

@@ -32,37 +32,40 @@
  * - Ensuring adherence to TypeScript best practices, including strict type safety,
  * comprehensive JSDoc documentation, and robust error management.
  *
- * @see {@link ./interfaces/IAgentOS.ts} for the `IAgentOS` interface contract.
- * @see {@link ./AgentOSOrchestrator.ts} for the orchestration logic.
- * @see {@link ../cognitive_substrate/GMIManager.ts} for GMI lifecycle management.
- * @see {@link ../core/streaming/StreamingManager.ts} for real-time data streaming.
- * @see {@link @framers/agentos/utils/errors.ts} for custom error definitions.
+ * @see {@link IAgentOS} for the public interface contract.
+ * @see {@link AgentOSOrchestrator} for the orchestration logic.
+ * @see {@link GMIManager} for GMI lifecycle management.
+ * See `StreamingManager` for real-time data streaming internals.
+ * See `@framers/agentos/utils/errors` for shared error definitions.
  */
-import { AgentOSResponseChunkType } from './types/AgentOSResponse.js';
+import { AGENTOS_PENDING_EXTERNAL_TOOL_REQUEST_METADATA_KEY } from './types/AgentOSExternalToolRequest.js';
+import { AgentOSResponseChunkType, isActionableToolCallRequestChunk, } from './types/AgentOSResponse.js';
 import { AgentOSOrchestrator, } from './AgentOSOrchestrator.js';
 import { GMIManager } from '../cognitive_substrate/GMIManager.js';
-import { AIModelProviderManager } from '../core/llm/providers/AIModelProviderManager.js';
+import { AIModelProviderManager, } from '../core/llm/providers/AIModelProviderManager.js';
 import { PromptEngine } from '../core/llm/PromptEngine.js';
 import { ToolOrchestrator } from '../core/tools/ToolOrchestrator.js';
 import { ToolExecutor } from '../core/tools/ToolExecutor.js';
 import { ToolPermissionManager } from '../core/tools/permissions/ToolPermissionManager.js';
 import { LLMUtilityAI } from '../core/ai_utilities/LLMUtilityAI.js';
-import { ConversationManager } from '../core/conversation/ConversationManager.js';
-import { StreamingManager } from '../core/streaming/StreamingManager.js';
+import { ConversationManager, } from '../core/conversation/ConversationManager.js';
+import { StreamingManager, } from '../core/streaming/StreamingManager.js';
 import { GMIError, GMIErrorCode } from '../utils/errors.js';
 import { uuidv4 } from '../utils/uuid.js';
 import { createLogger } from '../logging/loggerFactory.js';
-import { configureAgentOSObservability } from '../core/observability/otel.js';
+import { configureAgentOSObservability, } from '../core/observability/otel.js';
 import { GuardrailAction } from '../core/guardrails/IGuardrailService.js';
 import { evaluateInputGuardrails, createGuardrailBlockedStream, wrapOutputGuardrails, } from '../core/guardrails/guardrailDispatcher.js';
 import { ExtensionManager, EXTENSION_KIND_GUARDRAIL, EXTENSION_KIND_MESSAGING_CHANNEL, EXTENSION_KIND_PROVENANCE, EXTENSION_KIND_TOOL, EXTENSION_KIND_WORKFLOW, } from '../extensions/index.js';
 import { createMemoryToolsPack } from '../memory/extension/MemoryToolsExtension.js';
 import { createStandaloneMemoryLongTermRetriever, createStandaloneMemoryRollingSummarySink, } from '../memory/integration/StandaloneMemoryBridge.js';
+import { listExternalToolDefinitionsForLLM, normalizeExternalToolRegistry, } from './externalToolRegistry.js';
+import { adaptTools, adaptToolsToMap } from './toolAdapter.js';
 import { createSchemaOnDemandPack } from '../extensions/packs/schema-on-demand-pack.js';
 import { WorkflowRuntime } from '../core/workflows/runtime/WorkflowRuntime.js';
 import { AgencyRegistry } from '../core/agency/AgencyRegistry.js';
 import { AgentOSTurnPlanner, } from '../core/orchestration/TurnPlanner.js';
-import { CapabilityDiscoveryEngine, createDiscoverCapabilitiesTool, } from '../discovery/index.js';
+import { CapabilityDiscoveryEngine, createDiscoverCapabilitiesTool } from '../discovery/index.js';
 import { EmbeddingManager } from '../rag/EmbeddingManager.js';
 import { InMemoryVectorStore } from '../rag/implementations/vector_stores/InMemoryVectorStore.js';
 import { WorkflowEngine } from '../core/workflows/WorkflowEngine.js';
@@ -93,7 +96,9 @@ function wrapStorageAdapterWithWriteHooks(adapter, hooks, options) {
             await hooks.onAfterWrite?.(context, result);
         }
         catch (error) {
-            options?.logger?.error?.('[AgentOS][StorageHooks] onAfterWrite failed', { error: error?.message ?? error });
+            options?.logger?.error?.('[AgentOS][StorageHooks] onAfterWrite failed', {
+                error: error?.message ?? error,
+            });
         }
         return result;
     };
@@ -108,7 +113,10 @@ function wrapStorageAdapterWithWriteHooks(adapter, hooks, options) {
         run: runWithHooks,
         transaction: async (fn) => {
             return adapter.transaction(async (trx) => {
-                const wrappedTrx = wrapStorageAdapterWithWriteHooks(trx, hooks, { inTransaction: true, logger: options?.logger });
+                const wrappedTrx = wrapStorageAdapterWithWriteHooks(trx, hooks, {
+                    inTransaction: true,
+                    logger: options?.logger,
+                });
                 return fn(wrappedTrx);
             });
         },
@@ -128,7 +136,10 @@ function wrapStorageAdapterWithWriteHooks(adapter, hooks, options) {
                     catch (error) {
                         results.push({ changes: 0, lastInsertRowid: null });
                         failed += 1;
-                        errors.push({ index: i, error: error instanceof Error ? error : new Error(String(error)) });
+                        errors.push({
+                            index: i,
+                            error: error instanceof Error ? error : new Error(String(error)),
+                        });
                     }
                 }
                 return {
@@ -139,7 +150,7 @@ function wrapStorageAdapterWithWriteHooks(adapter, hooks, options) {
                 };
             }
             : undefined,
-        prepare: adapter.prepare ? ((statement) => adapter.prepare(statement)) : undefined,
+        prepare: adapter.prepare ? (statement) => adapter.prepare(statement) : undefined,
     };
 }
 // Re-export from extracted module
@@ -191,8 +202,15 @@ export class AgentOS {
         }
         this.validateConfiguration(config);
         const resolvedConfig = this.resolveStandaloneMemoryConfig(config);
+        const normalizedConfigTools = adaptToolsToMap(resolvedConfig.tools);
+        const normalizedExternalTools = normalizeExternalToolRegistry(resolvedConfig.externalTools);
+        const { externalTools: _externalTools, tools: _tools, ...resolvedConfigWithoutNormalizedTools } = resolvedConfig;
         // Make the configuration immutable after validation to prevent runtime changes.
-        this.config = Object.freeze({ ...resolvedConfig });
+        this.config = Object.freeze({
+            ...resolvedConfigWithoutNormalizedTools,
+            ...(Object.keys(normalizedConfigTools).length > 0 ? { tools: normalizedConfigTools } : {}),
+            ...(normalizedExternalTools ? { externalTools: normalizedExternalTools } : {}),
+        });
         this.configureManagedStandaloneMemory();
         // Observability is opt-in (config + env). Safe no-op if OTEL is not installed by host.
         configureAgentOSObservability(this.config.observability);
@@ -251,12 +269,16 @@ export class AgentOS {
                     .getActive('provenance-system');
                 const provenanceHooks = provenanceDescriptor?.payload?.result?.hooks;
                 if (provenanceHooks) {
-                    storageAdapter = wrapStorageAdapterWithWriteHooks(storageAdapter, provenanceHooks, { logger: this.logger });
+                    storageAdapter = wrapStorageAdapterWithWriteHooks(storageAdapter, provenanceHooks, {
+                        logger: this.logger,
+                    });
                     this.logger.info('[AgentOS][Provenance] Storage write hooks enabled');
                 }
             }
             catch (error) {
-                this.logger.warn?.('[AgentOS][Provenance] Failed to apply storage write hooks', { error: error?.message ?? error });
+                this.logger.warn?.('[AgentOS][Provenance] Failed to apply storage write hooks', {
+                    error: error?.message ?? error,
+                });
             }
         }
         try {
@@ -297,9 +319,7 @@ export class AgentOS {
                         }
                         const response = await provider.generateCompletion(model, [{ role: 'user', content: prompt }], {});
                         const firstContent = response.choices?.[0]?.message?.content ?? '';
-                        return typeof firstContent === 'string'
-                            ? firstContent
-                            : JSON.stringify(firstContent);
+                        return typeof firstContent === 'string' ? firstContent : JSON.stringify(firstContent);
                     },
                     storageAdapter: storageAdapter
                         ? {
@@ -311,8 +331,15 @@ export class AgentOS {
                         : undefined,
                 }
                 : undefined;
-            await this.toolOrchestrator.initialize(this.config.toolOrchestratorConfig, this.toolPermissionManager, this.toolExecutor, undefined, this.config.hitlManager, emergentOptions);
+            const initialConfigTools = adaptTools(this.config.tools);
+            await this.toolOrchestrator.initialize(this.config.toolOrchestratorConfig, this.toolPermissionManager, this.toolExecutor, initialConfigTools, this.config.hitlManager, emergentOptions);
             console.log('AgentOS: ToolOrchestrator initialized.');
+            if (initialConfigTools.length > 0) {
+                this.logger.info('[AgentOS] Config tools registered', {
+                    toolCount: initialConfigTools.length,
+                    toolNames: initialConfigTools.map((tool) => tool.name),
+                });
+            }
             await this.initializeTurnPlanner();
             if (this.capabilityDiscoveryEngine && this.toolOrchestrator.setEmergentDiscoveryIndexer) {
                 this.toolOrchestrator.setEmergentDiscoveryIndexer(async (tools) => {
@@ -356,9 +383,13 @@ export class AgentOS {
         }
         catch (error) {
             this.logger.error('AgentOS initialization failed', { error });
-            const err = error instanceof GMIError ? error : new GMIError(error instanceof Error ? error.message : 'Unknown error during AgentOS initialization', GMIErrorCode.GMI_INITIALIZATION_ERROR, // Corrected error code
-            error // details
-            );
+            const err = error instanceof GMIError
+                ? error
+                : new GMIError(error instanceof Error
+                    ? error.message
+                    : 'Unknown error during AgentOS initialization', GMIErrorCode.GMI_INITIALIZATION_ERROR, // Corrected error code
+                error // details
+                );
             console.error('AgentOS: Critical failure during core component initialization:', err.toJSON());
             throw AgentOSServiceError.wrap(err, err.code, 'AgentOS initialization failed', 'AgentOS.initialize');
         }
@@ -384,9 +415,15 @@ export class AgentOS {
         else {
             // Check for each required sub-configuration
             const requiredConfigs = [
-                'gmiManagerConfig', 'orchestratorConfig', 'promptEngineConfig',
-                'toolOrchestratorConfig', 'toolPermissionManagerConfig', 'conversationManagerConfig',
-                'streamingManagerConfig', 'modelProviderManagerConfig', 'defaultPersonaId'
+                'gmiManagerConfig',
+                'orchestratorConfig',
+                'promptEngineConfig',
+                'toolOrchestratorConfig',
+                'toolPermissionManagerConfig',
+                'conversationManagerConfig',
+                'streamingManagerConfig',
+                'modelProviderManagerConfig',
+                'defaultPersonaId',
             ];
             for (const key of requiredConfigs) {
                 if (!config[key]) {
@@ -436,7 +473,9 @@ export class AgentOS {
         if (missingParams.length > 0) {
             const message = `AgentOS Configuration Error: Missing essential parameters: ${missingParams.join(', ')}.`;
             console.error(message);
-            throw new AgentOSServiceError(message, GMIErrorCode.CONFIGURATION_ERROR, { missingParameters: missingParams });
+            throw new AgentOSServiceError(message, GMIErrorCode.CONFIGURATION_ERROR, {
+                missingParameters: missingParams,
+            });
         }
     }
     async registerConfigGuardrailService(context) {
@@ -466,14 +505,10 @@ export class AgentOS {
             };
         }
         if (!resolved.longTermMemoryRetriever && standalone.longTermRetriever) {
-            resolved.longTermMemoryRetriever = createStandaloneMemoryLongTermRetriever(memory, standalone.longTermRetriever === true
-                ? undefined
-                : standalone.longTermRetriever);
+            resolved.longTermMemoryRetriever = createStandaloneMemoryLongTermRetriever(memory, standalone.longTermRetriever === true ? undefined : standalone.longTermRetriever);
         }
         if (!resolved.rollingSummaryMemorySink && standalone.rollingSummarySink) {
-            resolved.rollingSummaryMemorySink = createStandaloneMemoryRollingSummarySink(memory, standalone.rollingSummarySink === true
-                ? undefined
-                : standalone.rollingSummarySink);
+            resolved.rollingSummaryMemorySink = createStandaloneMemoryRollingSummarySink(memory, standalone.rollingSummarySink === true ? undefined : standalone.rollingSummarySink);
         }
         return resolved;
     }
@@ -536,7 +571,8 @@ export class AgentOS {
                     payload: descriptor.payload,
                 });
             }
-            else if (event.type === 'descriptor:deactivated' && event.kind === EXTENSION_KIND_WORKFLOW) {
+            else if (event.type === 'descriptor:deactivated' &&
+                event.kind === EXTENSION_KIND_WORKFLOW) {
                 const descriptor = event.descriptor;
                 await this.handleWorkflowDescriptorDeactivated({
                     id: descriptor.id,
@@ -752,11 +788,17 @@ export class AgentOS {
             .trim()
             .replace(/\b\w/g, (c) => c.toUpperCase());
         const toolRegistry = this.extensionManager.getRegistry(EXTENSION_KIND_TOOL);
-        const tools = toolRegistry
+        const runtimeTools = new Map();
+        for (const tool of toolRegistry
             .listActive()
             .map((descriptor) => descriptor.payload)
-            .filter(Boolean)
-            .map((tool) => ({
+            .filter(Boolean)) {
+            runtimeTools.set(tool.name, tool);
+        }
+        for (const tool of adaptTools(this.config.tools)) {
+            runtimeTools.set(tool.name, tool);
+        }
+        const tools = Array.from(runtimeTools.values()).map((tool) => ({
             id: tool.id || `tool:${tool.name}`,
             name: tool.name,
             displayName: tool.displayName || titleCase(tool.name),
@@ -777,13 +819,13 @@ export class AgentOS {
             available: true,
         }));
         const workflowRegistry = this.extensionManager.getRegistry(EXTENSION_KIND_WORKFLOW);
-        const workflowExtensions = workflowRegistry.listActive().map((descriptor) => ({
+        const workflowExtensions = workflowRegistry
+            .listActive()
+            .map((descriptor) => ({
             id: `workflow:${descriptor.payload.definition.id}`,
             name: descriptor.payload.definition.id,
-            displayName: descriptor.payload.definition.displayName ||
-                titleCase(descriptor.payload.definition.id),
-            description: descriptor.payload.definition.description ||
-                'Workflow automation capability',
+            displayName: descriptor.payload.definition.displayName || titleCase(descriptor.payload.definition.id),
+            description: descriptor.payload.definition.description || 'Workflow automation capability',
             category: 'workflow',
             requiredSecrets: descriptor.payload.definition.metadata?.requiredSecrets,
             available: true,
@@ -803,11 +845,7 @@ export class AgentOS {
         }));
         return {
             tools,
-            extensions: [
-                ...packExtensions,
-                ...workflowExtensions,
-                ...(overrides?.extensions ?? []),
-            ],
+            extensions: [...packExtensions, ...workflowExtensions, ...(overrides?.extensions ?? [])],
             channels: [...channels, ...(overrides?.channels ?? [])],
             skills: overrides?.skills,
             manifests: overrides?.manifests,
@@ -839,8 +877,7 @@ export class AgentOS {
         const defaultProviderId = this.config.gmiManagerConfig.defaultGMIBaseConfigDefaults?.defaultLlmProviderId ||
             this.config.modelProviderManagerConfig.providers[0]?.providerId ||
             'openai';
-        const defaultModelId = this.config.gmiManagerConfig.defaultGMIBaseConfigDefaults?.defaultLlmModelId ||
-            'gpt-4o';
+        const defaultModelId = this.config.gmiManagerConfig.defaultGMIBaseConfigDefaults?.defaultLlmModelId || 'gpt-4o';
         await fallbackUtility.initialize({
             llmProviderManager: this.modelProviderManager,
             defaultProviderId,
@@ -960,6 +997,14 @@ export class AgentOS {
         this.ensureInitialized();
         return this.toolOrchestrator;
     }
+    getExternalToolRegistry() {
+        this.ensureInitialized();
+        return this.config.externalTools;
+    }
+    listExternalToolsForLLM() {
+        this.ensureInitialized();
+        return listExternalToolDefinitionsForLLM(this.config.externalTools);
+    }
     getModelProviderManager() {
         this.ensureInitialized();
         return this.modelProviderManager;
@@ -970,12 +1015,12 @@ export class AgentOS {
      *
      * This method orchestrates:
      * 1. Retrieval or creation of a {@link StreamId} via the {@link AgentOSOrchestrator}.
-     * 2. Registration of a temporary, request-scoped stream client to the {@link StreamingManager}.
+     * 2. Registration of a temporary, request-scoped stream client to the internal streaming manager.
      * 3. Yielding of {@link AgentOSResponse} chunks received by this client.
      * 4. Ensuring the temporary client is deregistered upon completion or error.
      *
      * The underlying {@link AgentOSOrchestrator} handles the GMI interaction and pushes
-     * chunks to the {@link StreamingManager}. This method acts as the bridge to make these
+     * chunks to the internal streaming manager. This method acts as the bridge to make these
      * chunks available as an `AsyncGenerator` to the caller (e.g., an API route handler).
      *
      * @public
@@ -1038,7 +1083,9 @@ export class AgentOS {
                     personaDefault: undefined,
                     configDefault: this.config.languageConfig.defaultLanguage,
                     supported: this.config.languageConfig.supportedLanguages,
-                    fallbackChain: this.config.languageConfig.fallbackLanguages || [this.config.languageConfig.defaultLanguage],
+                    fallbackChain: this.config.languageConfig.fallbackLanguages || [
+                        this.config.languageConfig.defaultLanguage,
+                    ],
                     preferSourceLanguageResponses: this.config.languageConfig.preferSourceLanguageResponses,
                     targetLanguage: orchestratorInput.targetLanguage,
                 });
@@ -1063,7 +1110,10 @@ export class AgentOS {
             });
             // The orchestrator creates/manages the actual stream and starts pushing chunks to StreamingManager.
             // We get the streamId it uses so our bridge can listen to it.
-            streamIdToListen = await this.agentOSOrchestrator.orchestrateTurn({ ...orchestratorInput, languageNegotiation });
+            streamIdToListen = await this.agentOSOrchestrator.orchestrateTurn({
+                ...orchestratorInput,
+                languageNegotiation,
+            });
             await this.streamingManager.registerClient(streamIdToListen, bridge);
             this.logger.debug?.('Bridge registered', { bridgeId: bridge.id, streamId: streamIdToListen });
             const guardrailWrappedStream = wrapOutputGuardrails(guardrailServices, guardrailContext, bridge.consume(), {
@@ -1076,7 +1126,9 @@ export class AgentOS {
                 try {
                     await this.startWorkflow(wfRequest.definitionId, orchestratorInput, {
                         workflowId: wfRequest.workflowId,
-                        conversationId: wfRequest.conversationId ?? orchestratorInput.conversationId ?? orchestratorInput.sessionId,
+                        conversationId: wfRequest.conversationId ??
+                            orchestratorInput.conversationId ??
+                            orchestratorInput.sessionId,
                         createdByUserId: orchestratorInput.userId,
                         context: wfRequest.context,
                         roleAssignments: wfRequest.roleAssignments,
@@ -1099,6 +1151,9 @@ export class AgentOS {
                     chunk.metadata.language = languageNegotiation;
                 }
                 yield chunk;
+                if (isActionableToolCallRequestChunk(chunk)) {
+                    break;
+                }
                 if (chunk.isFinal && chunk.type !== AgentOSResponseChunkType.ERROR) {
                     // If a non-error chunk is final, the primary interaction part might be done.
                     // The stream itself might remain open for a short while for cleanup or late messages.
@@ -1110,7 +1165,10 @@ export class AgentOS {
         catch (error) {
             const serviceError = AgentOSServiceError.wrap(error, GMIErrorCode.GMI_PROCESSING_ERROR, // Default code for facade-level processing errors
             `Error during AgentOS.processRequest for user '${orchestratorInput.userId}'`, 'AgentOS.processRequest');
-            this.logger.error('processRequest failed', { error: serviceError, streamId: streamIdToListen });
+            this.logger.error('processRequest failed', {
+                error: serviceError,
+                streamId: streamIdToListen,
+            });
             const errorChunk = {
                 type: AgentOSResponseChunkType.ERROR,
                 streamId: streamIdToListen || baseStreamDebugId, // Use known streamId if available
@@ -1130,7 +1188,9 @@ export class AgentOS {
                     .getActiveStreamIds()
                     .catch(() => []);
                 if (activeStreamIds.includes(streamIdToListen)) {
-                    await this.streamingManager.deregisterClient(streamIdToListen, bridge.id).catch((deregError) => {
+                    await this.streamingManager
+                        .deregisterClient(streamIdToListen, bridge.id)
+                        .catch((deregError) => {
                         this.logger.warn('Failed to deregister bridge client', {
                             bridgeId: bridge.id,
                             streamId: streamIdToListen,
@@ -1169,20 +1229,37 @@ export class AgentOS {
      * Errors during GMI processing are yielded as `AgentOSErrorChunk`s.
      */
     async *handleToolResult(streamId, toolCallId, toolName, toolOutput, isSuccess, errorMessage) {
+        yield* this.handleToolResults(streamId, [
+            {
+                toolCallId,
+                toolName,
+                toolOutput,
+                isSuccess,
+                errorMessage,
+            },
+        ]);
+    }
+    async *handleToolResults(streamId, toolResults) {
         this.ensureInitialized();
+        if (!Array.isArray(toolResults) || toolResults.length === 0) {
+            throw new AgentOSServiceError('At least one tool result is required to continue the stream.', GMIErrorCode.VALIDATION_ERROR, { streamId }, 'AgentOS.handleToolResults');
+        }
         // Create a new bridge client for this specific tool result handling phase
-        const bridge = new AsyncStreamClientBridge(`client-toolRes-${streamId.substring(0, 8)}-${toolCallId.substring(0, 8)}`);
+        const bridge = new AsyncStreamClientBridge(`client-toolRes-${streamId.substring(0, 8)}-${toolResults[0].toolCallId.substring(0, 8)}`);
         try {
-            console.log(`AgentOS.handleToolResult: Stream '${streamId}', ToolCall '${toolCallId}'. Orchestrator will push new chunks to this stream.`);
+            console.log(`AgentOS.handleToolResults: Stream '${streamId}', ${toolResults.length} tool result(s). Orchestrator will push new chunks to this stream.`);
             // Register the bridge client to listen for new chunks on the existing stream
             await this.streamingManager.registerClient(streamId, bridge);
-            console.log(`AgentOS.handleToolResult: Bridge client ${bridge.id} registered to stream ${streamId}.`);
-            // This call is `async Promise<void>`; it triggers the orchestrator to process the tool result
+            console.log(`AgentOS.handleToolResults: Bridge client ${bridge.id} registered to stream ${streamId}.`);
+            // This call is `async Promise<void>`; it triggers the orchestrator to process the tool result(s)
             // and push new chunks to the StreamingManager for the given streamId.
-            await this.agentOSOrchestrator.orchestrateToolResult(streamId, toolCallId, toolName, toolOutput, isSuccess, errorMessage);
+            await this.agentOSOrchestrator.orchestrateToolResults(streamId, toolResults);
             // Yield new chunks received by our bridge client on the same stream
             for await (const chunk of bridge.consume()) {
                 yield chunk;
+                if (isActionableToolCallRequestChunk(chunk)) {
+                    break;
+                }
                 if (chunk.isFinal && chunk.type !== AgentOSResponseChunkType.ERROR) {
                     break;
                 }
@@ -1190,7 +1267,7 @@ export class AgentOS {
         }
         catch (error) {
             const serviceError = AgentOSServiceError.wrap(error, GMIErrorCode.TOOL_ERROR, // Default code for facade-level tool result errors
-            `Error during AgentOS.handleToolResult for stream '${streamId}', tool '${toolName}'`, 'AgentOS.handleToolResult');
+            `Error during AgentOS.handleToolResults for stream '${streamId}'`, 'AgentOS.handleToolResults');
             console.error(`${serviceError.name}: ${serviceError.message}`, serviceError.toJSON());
             const errorChunk = {
                 type: AgentOSResponseChunkType.ERROR,
@@ -1206,14 +1283,13 @@ export class AgentOS {
             yield errorChunk;
         }
         finally {
-            console.log(`AgentOS.handleToolResult: Deregistering bridge client ${bridge.id} from stream ${streamId}.`);
+            console.log(`AgentOS.handleToolResults: Deregistering bridge client ${bridge.id} from stream ${streamId}.`);
             const activeStreamIds = await this.streamingManager
                 .getActiveStreamIds()
                 .catch(() => []);
             if (activeStreamIds.includes(streamId)) {
-                await this.streamingManager.deregisterClient(streamId, bridge.id)
-                    .catch((deregError) => {
-                    console.error(`AgentOS.handleToolResult: Error deregistering bridge client ${bridge.id}: ${deregError.message}`);
+                await this.streamingManager.deregisterClient(streamId, bridge.id).catch((deregError) => {
+                    console.error(`AgentOS.handleToolResults: Error deregistering bridge client ${bridge.id}: ${deregError.message}`);
                 });
             }
             bridge.forceClose();
@@ -1276,12 +1352,12 @@ export class AgentOS {
      */
     async listAvailablePersonas(userId) {
         this.ensureInitialized();
-        console.log(`AgentOS.listAvailablePersonas: Request for UserID: '${userId || "anonymous/system"}'.`);
+        console.log(`AgentOS.listAvailablePersonas: Request for UserID: '${userId || 'anonymous/system'}'.`);
         try {
             return await this.gmiManager.listAvailablePersonas(userId);
         }
         catch (error) {
-            throw AgentOSServiceError.wrap(error, GMIErrorCode.PERSONA_LOAD_ERROR, "Failed to list available personas", "AgentOS.listAvailablePersonas");
+            throw AgentOSServiceError.wrap(error, GMIErrorCode.PERSONA_LOAD_ERROR, 'Failed to list available personas', 'AgentOS.listAvailablePersonas');
         }
     }
     /**
@@ -1324,7 +1400,73 @@ export class AgentOS {
             return null; // Conversation not found
         }
         catch (error) {
-            throw AgentOSServiceError.wrap(error, GMIErrorCode.GMI_CONTEXT_ERROR, `Failed to retrieve conversation history for ID '${conversationId}'`, "AgentOS.getConversationHistory");
+            throw AgentOSServiceError.wrap(error, GMIErrorCode.GMI_CONTEXT_ERROR, `Failed to retrieve conversation history for ID '${conversationId}'`, 'AgentOS.getConversationHistory');
+        }
+    }
+    async getPendingExternalToolRequest(conversationId, userId) {
+        this.ensureInitialized();
+        const context = await this.getConversationHistory(conversationId, userId);
+        if (!context) {
+            return null;
+        }
+        const pendingRequest = context.getMetadata(AGENTOS_PENDING_EXTERNAL_TOOL_REQUEST_METADATA_KEY);
+        return pendingRequest ?? null;
+    }
+    async *resumeExternalToolRequest(pendingRequest, toolResults, options = {}) {
+        this.ensureInitialized();
+        let streamIdToListen;
+        let shouldDeregisterBridge = false;
+        const bridge = new AsyncStreamClientBridge(`client-resumeToolReq-${pendingRequest.conversationId}-${Date.now()}`);
+        try {
+            streamIdToListen = await this.agentOSOrchestrator.orchestrateResumedToolResults(pendingRequest, toolResults, options);
+            await this.streamingManager.registerClient(streamIdToListen, bridge);
+            for await (const chunk of bridge.consume()) {
+                yield chunk;
+                if (isActionableToolCallRequestChunk(chunk)) {
+                    shouldDeregisterBridge = true;
+                    break;
+                }
+                if (chunk.isFinal && chunk.type !== AgentOSResponseChunkType.ERROR) {
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            const serviceError = AgentOSServiceError.wrap(error, GMIErrorCode.TOOL_ERROR, `Error during AgentOS.resumeExternalToolRequest for conversation '${pendingRequest.conversationId}'`, 'AgentOS.resumeExternalToolRequest');
+            console.error(`${serviceError.name}: ${serviceError.message}`, serviceError.toJSON());
+            const errorChunk = {
+                type: AgentOSResponseChunkType.ERROR,
+                streamId: streamIdToListen || pendingRequest.streamId,
+                gmiInstanceId: serviceError.details?.gmiInstanceId ||
+                    pendingRequest.gmiInstanceId ||
+                    'agentos_facade_resume_error',
+                personaId: serviceError.details?.personaId || pendingRequest.personaId || 'unknown_persona',
+                isFinal: true,
+                timestamp: new Date().toISOString(),
+                code: serviceError.code.toString(),
+                message: serviceError.message,
+                details: serviceError.details || { name: serviceError.name, stack: serviceError.stack },
+            };
+            yield errorChunk;
+        }
+        finally {
+            if (streamIdToListen && shouldDeregisterBridge) {
+                const activeStreamIds = await this.streamingManager
+                    .getActiveStreamIds()
+                    .catch(() => []);
+                if (activeStreamIds.includes(streamIdToListen)) {
+                    await this.streamingManager
+                        .deregisterClient(streamIdToListen, bridge.id)
+                        .catch((deregError) => {
+                        this.logger.warn('Failed to deregister resume bridge client', {
+                            bridgeId: bridge.id,
+                            streamId: streamIdToListen,
+                            error: deregError.message,
+                        });
+                    });
+                }
+            }
+            bridge.forceClose();
         }
     }
     /**
@@ -1346,14 +1488,14 @@ export class AgentOS {
         this.ensureInitialized();
         // Basic authorization checks for the user can be performed here.
         // E.g., await this.authService.validateUserExists(userId);
-        console.log(`AgentOS.receiveFeedback: UserID '${userId}', SessionID '${sessionId}', PersonaID '${personaId}'. Payload:`, JSON.stringify(feedbackPayload).substring(0, 200) + "...");
+        console.log(`AgentOS.receiveFeedback: UserID '${userId}', SessionID '${sessionId}', PersonaID '${personaId}'. Payload:`, JSON.stringify(feedbackPayload).substring(0, 200) + '...');
         try {
             // Delegate feedback processing, typically to GMIManager or directly to the relevant GMI.
             await this.gmiManager.processUserFeedback(userId, sessionId, personaId, feedbackPayload);
             console.info(`AgentOS.receiveFeedback: Feedback processed successfully for UserID '${userId}', PersonaID '${personaId}'.`);
         }
         catch (error) {
-            throw AgentOSServiceError.wrap(error, GMIErrorCode.GMI_FEEDBACK_ERROR, "Failed to process user feedback", "AgentOS.receiveFeedback");
+            throw AgentOSServiceError.wrap(error, GMIErrorCode.GMI_FEEDBACK_ERROR, 'Failed to process user feedback', 'AgentOS.receiveFeedback');
         }
     }
     /**
@@ -1402,7 +1544,8 @@ export class AgentOS {
                 await this.streamingManager.shutdown();
                 console.log('AgentOS: StreamingManager shut down.');
             }
-            if (this.conversationManager?.shutdown && typeof this.conversationManager.shutdown === 'function') {
+            if (this.conversationManager?.shutdown &&
+                typeof this.conversationManager.shutdown === 'function') {
                 await this.conversationManager.shutdown();
                 console.log('AgentOS: ConversationManager shut down.');
             }
@@ -1423,7 +1566,8 @@ export class AgentOS {
                 await this.retrievalAugmentor.shutdown();
                 console.log('AgentOS: RetrievalAugmentor shut down.');
             }
-            if (this.manageRetrievalAugmentorLifecycle && this.ragVectorStoreManager?.shutdownAllProviders) {
+            if (this.manageRetrievalAugmentorLifecycle &&
+                this.ragVectorStoreManager?.shutdownAllProviders) {
                 await this.ragVectorStoreManager.shutdownAllProviders();
                 console.log('AgentOS: VectorStore providers shut down.');
             }
@@ -1451,7 +1595,7 @@ export class AgentOS {
         catch (error) {
             // Even if one component fails to shut down, attempt to log and continue if possible,
             // but report the overall failure.
-            const serviceError = AgentOSServiceError.wrap(error, GMIErrorCode.GMI_SHUTDOWN_ERROR, "Error during AgentOS service shutdown sequence", "AgentOS.shutdown");
+            const serviceError = AgentOSServiceError.wrap(error, GMIErrorCode.GMI_SHUTDOWN_ERROR, 'Error during AgentOS service shutdown sequence', 'AgentOS.shutdown');
             console.error(`${serviceError.name}: ${serviceError.message}`, serviceError.toJSON());
             throw serviceError; // Re-throw to indicate shutdown was problematic.
         }
@@ -1463,7 +1607,8 @@ export class AgentOS {
         // Prefer caller-provided augmentor instance.
         if (this.config.retrievalAugmentor) {
             this.retrievalAugmentor = this.config.retrievalAugmentor;
-            this.manageRetrievalAugmentorLifecycle = this.config.manageRetrievalAugmentorLifecycle === true;
+            this.manageRetrievalAugmentorLifecycle =
+                this.config.manageRetrievalAugmentorLifecycle === true;
             return;
         }
         const ragConfig = this.config.ragConfig;
@@ -1476,7 +1621,9 @@ export class AgentOS {
             const { RetrievalAugmentor } = await import('../rag/RetrievalAugmentor.js');
             const embeddingManager = new EmbeddingManager();
             await embeddingManager.initialize(ragConfig.embeddingManagerConfig, this.modelProviderManager);
-            const bindToStorageAdapter = ragConfig.bindToStorageAdapter === undefined ? true : ragConfig.bindToStorageAdapter === true;
+            const bindToStorageAdapter = ragConfig.bindToStorageAdapter === undefined
+                ? true
+                : ragConfig.bindToStorageAdapter === true;
             const patchedVectorStoreConfig = {
                 ...ragConfig.vectorStoreManagerConfig,
                 providers: ragConfig.vectorStoreManagerConfig.providers.map((provider) => {