@strands-agents/sdk 0.6.0 → 1.0.0-rc.0

package/dist/src/agent/agent.js

@@ -50,30 +50,31 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { AgentResult } from '../types/agent.js';
+import { AgentResult, } from '../types/agent.js';
 import { BedrockModel } from '../models/bedrock.js';
 import { contentBlockFromData, Message, TextBlock, ToolResultBlock, ToolUseBlock, } from '../types/messages.js';
 import { McpClient } from '../mcp.js';
 import {} from '../tools/tool.js';
 import { systemPromptFromData } from '../types/messages.js';
-import { normalizeError, ConcurrentInvocationError, MaxTokensError } from '../errors.js';
+import { normalizeError, ConcurrentInvocationError, StructuredOutputError } from '../errors.js';
 import { Model } from '../models/model.js';
 import { isModelStreamEvent } from '../models/streaming.js';
 import { ToolRegistry } from '../registry/tool-registry.js';
-import { AppState } from '../app-state.js';
+import { StateStore } from '../state-store.js';
 import { AgentPrinter, getDefaultAppender } from './printer.js';
+import { PluginRegistry } from '../plugins/registry.js';
 import { SlidingWindowConversationManager } from '../conversation-manager/sliding-window-conversation-manager.js';
+import { ConversationManager } from '../conversation-manager/conversation-manager.js';
 import { HookRegistryImplementation } from '../hooks/registry.js';
 import { InitializedEvent, AfterInvocationEvent, AfterModelCallEvent, AfterToolCallEvent, AfterToolsEvent, BeforeInvocationEvent, BeforeModelCallEvent, BeforeToolCallEvent, BeforeToolsEvent, HookableEvent, MessageAddedEvent, ModelStreamUpdateEvent, ContentBlockEvent, ModelMessageEvent, ToolResultEvent, AgentResultEvent, ToolStreamUpdateEvent, } from '../hooks/events.js';
-import { createStructuredOutputContext } from '../structured-output/context.js';
-import { StructuredOutputException } from '../structured-output/exceptions.js';
+import { StructuredOutputTool, STRUCTURED_OUTPUT_TOOL_NAME } from '../tools/structured-output-tool.js';
 import { Tracer } from '../telemetry/tracer.js';
 import { Meter } from '../telemetry/meter.js';
 import { logger } from '../logging/logger.js';
-/** Fallback name used when no agent name is provided in the config. */
+/** Default name assigned to agents when none is provided. */
 const DEFAULT_AGENT_NAME = 'Strands Agent';
-/** Fallback agent ID used when no agent ID is provided in the config. */
-const DEFAULT_AGENT_ID = 'default';
+/** Default identifier assigned to agents when none is provided. */
+const DEFAULT_AGENT_ID = 'agent';
 /**
  * Orchestrates the interaction between a model, a set of tools, and MCP clients.
  * The Agent is responsible for managing the lifecycle of tools and clients
@@ -88,16 +89,8 @@ export class Agent {
      * App state storage accessible to tools and application logic.
      * State is not passed to the model during inference.
      */
-    state;
-    /**
-     * Conversation manager for handling message history and context overflow.
-     */
-    conversationManager;
-    /**
-     * Hook registry for managing event callbacks.
-     * Hooks enable observing and extending agent behavior.
-     */
-    hooks;
+    appState;
+    _conversationManager;
     /**
      * The model provider used by the agent for inference.
      */
@@ -113,11 +106,13 @@ export class Agent {
     /**
      * The unique identifier of the agent instance.
      */
-    agentId;
+    id;
     /**
      * Optional description of what the agent does.
      */
     description;
+    _hooksRegistry;
+    _pluginRegistry;
     _toolRegistry;
     _mcpClients;
     _initialized;
@@ -135,16 +130,12 @@ export class Agent {
     constructor(config) {
         // Initialize public fields
         this.messages = (config?.messages ?? []).map((msg) => (msg instanceof Message ? msg : Message.fromMessageData(msg)));
-        this.state = new AppState(config?.state);
-        this.conversationManager = config?.conversationManager ?? new SlidingWindowConversationManager({ windowSize: 40 });
+        this.appState = new StateStore(config?.appState);
+        this._conversationManager = config?.conversationManager ?? new SlidingWindowConversationManager({ windowSize: 40 });
         this.name = config?.name ?? DEFAULT_AGENT_NAME;
-        this.agentId = config?.agentId ?? DEFAULT_AGENT_ID;
+        this.id = config?.id ?? DEFAULT_AGENT_ID;
         if (config?.description !== undefined)
             this.description = config.description;
-        // Initialize hooks and register conversation manager hooks
-        this.hooks = new HookRegistryImplementation();
-        this.hooks.addHook(this.conversationManager);
-        this.hooks.addAllHooks(config?.hooks ?? []);
         if (typeof config?.model === 'string') {
             this.model = new BedrockModel({ modelId: config.model });
         }
@@ -154,6 +145,14 @@ export class Agent {
         const { tools, mcpClients } = flattenTools(config?.tools ?? []);
         this._toolRegistry = new ToolRegistry(tools);
         this._mcpClients = mcpClients;
+        // Initialize hooks registry
+        this._hooksRegistry = new HookRegistryImplementation();
+        // Initialize plugin registry with all plugins to be initialized during initialize()
+        this._pluginRegistry = new PluginRegistry([
+            this._conversationManager,
+            ...(config?.plugins ?? []),
+            ...(config?.sessionManager ? [config.sessionManager] : []),
+        ]);
         if (config?.systemPrompt !== undefined) {
             this.systemPrompt = systemPromptFromData(config.systemPrompt);
         }
@@ -168,20 +167,41 @@ export class Agent {
         this._tracer = new Tracer(config?.traceAttributes);
         // Initialize meter for local metrics accumulation
         this._meter = new Meter();
-        if (config?.sessionManager) {
-            this.hooks.addHook(config.sessionManager);
-        }
         this._initialized = false;
     }
+    /**
+     * Register a hook callback for a specific event type.
+     *
+     * @param eventType - The event class constructor to register the callback for
+     * @param callback - The callback function to invoke when the event occurs
+     * @returns Cleanup function that removes the callback when invoked
+     *
+     * @example
+     * ```typescript
+     * const agent = new Agent({ model })
+     *
+     * const cleanup = agent.addHook(BeforeInvocationEvent, (event) => {
+     *   console.log('Invocation started')
+     * })
+     *
+     * // Later, to remove the hook:
+     * cleanup()
+     * ```
+     */
+    addHook(eventType, callback) {
+        return this._hooksRegistry.addCallback(eventType, callback);
+    }
     async initialize() {
         if (this._initialized) {
             return;
         }
+        // Initialize MCP clients and register their tools
         await Promise.all(this._mcpClients.map(async (client) => {
             const tools = await client.listTools();
             this._toolRegistry.add(tools);
         }));
-        await this.hooks.invokeCallbacks(new InitializedEvent({ agent: this }));
+        await this._pluginRegistry.initialize(this);
+        await this._hooksRegistry.invokeCallbacks(new InitializedEvent({ agent: this }));
         this._initialized = true;
     }
     /**
@@ -274,24 +294,29 @@ export class Agent {
             await this.initialize();
             // Delegate to _stream and process events through printer and hooks
             const streamGenerator = this._stream(args, options);
-            let result = await streamGenerator.next();
-            while (!result.done) {
-                const event = result.value;
-                // Invoke hook callbacks for hookable events (all current events are hookable;
-                // the guard exists for future StreamEvent subclasses that may not be)
-                if (event instanceof HookableEvent) {
-                    await this.hooks.invokeCallbacks(event);
+            try {
+                let result = await streamGenerator.next();
+                while (!result.done) {
+                    yield await this._invokeCallbacks(result.value);
+                    result = await streamGenerator.next();
+                }
+                yield await this._invokeCallbacks(new AgentResultEvent({ agent: this, result: result.value }));
+                return result.value;
+            }
+            finally {
+                // Drain remaining events from _stream() so cleanup events (after events
+                // from finally blocks) still get their hooks and printer invoked.
+                let result = await streamGenerator.return(undefined);
+                while (!result.done) {
+                    try {
+                        yield await this._invokeCallbacks(result.value);
+                    }
+                    catch (error) {
+                        logger.warn(`event_type=<${result.value.type}>, error=<${error}> | error invoking callbacks during cleanup`);
+                    }
+                    result = await streamGenerator.next();
                 }
-                this._printer?.processEvent(event);
-                yield event;
-                result = await streamGenerator.next();
             }
-            // Yield final result as last event
-            const agentResultEvent = new AgentResultEvent({ agent: this, result: result.value });
-            await this.hooks.invokeCallbacks(agentResultEvent);
-            this._printer?.processEvent(agentResultEvent);
-            yield agentResultEvent;
-            return result.value;
         }
         catch (e_1) {
             env_1.error = e_1;
@@ -301,6 +326,19 @@ export class Agent {
             __disposeResources(env_1);
         }
     }
+    /**
+     * Invokes hook callbacks and printer for a stream event.
+     *
+     * @param event - The event to process
+     * @returns The event after processing
+     */
+    async _invokeCallbacks(event) {
+        if (event instanceof HookableEvent) {
+            await this._hooksRegistry.invokeCallbacks(event);
+        }
+        this._printer?.processEvent(event);
+        return event;
+    }
     /**
      * Internal implementation of the agent streaming logic.
      * Separated to centralize printer event processing in the public stream method.
@@ -311,11 +349,11 @@ export class Agent {
      */
     async *_stream(args, options) {
         let currentArgs = args;
-        let forcedToolChoice = undefined;
         let result;
-        // Create structured output context (uses null object pattern when no schema)
-        const schema = options?.structuredOutputSchema ?? this._structuredOutputSchema;
-        const context = createStructuredOutputContext(schema);
+        // Resolve structured output schema from per-invocation options or constructor config
+        const structuredOutputSchema = options?.structuredOutputSchema ?? this._structuredOutputSchema;
+        const structuredOutputTool = structuredOutputSchema ? new StructuredOutputTool(structuredOutputSchema) : undefined;
+        let structuredOutputChoice;
         // Emit event before the try block
         yield new BeforeInvocationEvent({ agent: this });
         // Normalize input to get the user messages for telemetry
@@ -326,18 +364,20 @@ export class Agent {
         const agentSpanOptions = {
             messages: inputMessages,
             agentName: this.name,
-            agentId: this.agentId,
+            agentId: this.id,
             tools: this.tools,
         };
         if (agentModelId)
             agentSpanOptions.modelId = agentModelId;
-        if (this.systemPrompt)
+        if (this.systemPrompt !== undefined)
             agentSpanOptions.systemPrompt = this.systemPrompt;
         const agentSpan = this._tracer.startAgentSpan(agentSpanOptions);
         let caughtError;
         try {
-            // Register structured output tool
-            context.registerTool(this._toolRegistry);
+            // Register structured output tool if schema provided
+            if (structuredOutputTool) {
+                this._toolRegistry.add(structuredOutputTool);
+            }
             // Main agent loop - continues until model stops without requesting tools
             while (true) {
                 // Start metrics cycle tracking
@@ -348,69 +388,65 @@ export class Agent {
                     messages: this.messages,
                 });
                 try {
-                    const modelResult = yield* this.invokeModel(currentArgs, forcedToolChoice);
-                    currentArgs = undefined; // Only pass args on first invocation
-                    const wasForced = forcedToolChoice !== undefined;
-                    forcedToolChoice = undefined; // Clear after use
-                    if (modelResult.stopReason !== 'toolUse') {
-                        // Special handling for maxTokens - always fail regardless of whether we have structured output
-                        if (modelResult.stopReason === 'maxTokens') {
-                            throw new MaxTokensError('The model reached maxTokens before producing structured output. Consider increasing maxTokens in your model configuration.', modelResult.message);
+                    // Normalize input and append user messages on first invocation only
+                    if (currentArgs !== undefined) {
+                        const messagesToAppend = this._normalizeInput(currentArgs);
+                        for (const message of messagesToAppend) {
+                            yield this._appendMessage(message);
                         }
-                        // Check if we need to force structured output tool
-                        if (!context.hasResult()) {
-                            if (wasForced) {
-                                // Already tried forcing - LLM refused to use the tool
-                                throw new StructuredOutputException('The model failed to invoke the structured output tool even after it was forced.');
+                        currentArgs = undefined;
+                    }
+                    const modelResult = yield* this._invokeModel(structuredOutputChoice);
+                    if (modelResult.stopReason !== 'toolUse') {
+                        // If structured output is required, force it
+                        if (structuredOutputTool) {
+                            if (structuredOutputChoice) {
+                                throw new StructuredOutputError('The model failed to invoke the structured output tool even after it was forced.');
                             }
-                            // Force the model to use the structured output tool
-                            const toolName = context.getToolName();
-                            forcedToolChoice = { tool: { name: toolName } };
-                            this._meter.endCycle(cycleStartTime);
-                            this._tracer.endAgentLoopSpan(cycleSpan);
-                            continue;
+                            structuredOutputChoice = { tool: { name: STRUCTURED_OUTPUT_TOOL_NAME } };
                         }
-                        // Loop terminates - no tool use requested (and structured output satisfied if needed)
-                        yield this._appendMessage(modelResult.message);
-                        // End cycle tracking
                         this._meter.endCycle(cycleStartTime);
-                        // End cycle span
                         this._tracer.endAgentLoopSpan(cycleSpan);
-                        const structuredOutput = context.getResult();
+                        yield this._appendMessage(modelResult.message);
+                        if (structuredOutputChoice) {
+                            continue;
+                        }
                         result = new AgentResult({
                             stopReason: modelResult.stopReason,
                             lastMessage: modelResult.message,
-                            structuredOutput,
+                            traces: this._tracer.localTraces,
                             metrics: this._meter.metrics,
                         });
                         return result;
                     }
-                    // Execute tools sequentially
+                    // Execute tools
                     const toolResultMessage = yield* this.executeTools(modelResult.message, this._toolRegistry);
                     /**
                      * Deferred append: both messages are added AFTER tool execution completes.
-                     * This keeps agent.messages in a valid, reinvokable state at all times:
-                     *
-                     * - If interrupted during tool execution, messages has no dangling toolUse
-                     *   without a matching toolResult, so the agent can be reinvoked cleanly.
-                     * - The Python SDK appends the assistant message BEFORE tool execution,
-                     *   requiring recovery logic (generate_missing_tool_result_content) on
-                     *   interrupts. We avoid that by deferring.
-                     * - Trade-off: MessageAddedEvent for the assistant message fires after tools
-                     *   complete (not before as in Python), and agent.messages is incomplete
-                     *   during tool execution. Events like BeforeToolsEvent.message and
-                     *   BeforeToolCallEvent.toolUse provide the data directly.
+                     * This keeps agent.messages in a valid, reinvokable state at all times.
+                     * If interrupted during tool execution, messages has no dangling toolUse
+                     * without a matching toolResult, so the agent can be reinvoked cleanly.
                      */
                     yield this._appendMessage(modelResult.message);
                     yield this._appendMessage(toolResultMessage);
-                    // End cycle tracking
                     this._meter.endCycle(cycleStartTime);
-                    // End cycle span
                     this._tracer.endAgentLoopSpan(cycleSpan);
-                    // Continue loop
+                    // Structured output captured: exit
+                    const structuredOutput = structuredOutputTool
+                        ? this._extractStructuredOutput(modelResult.message, toolResultMessage)
+                        : undefined;
+                    if (structuredOutput !== undefined) {
+                        result = new AgentResult({
+                            stopReason: modelResult.stopReason,
+                            lastMessage: modelResult.message,
+                            traces: this._tracer.localTraces,
+                            structuredOutput,
+                            metrics: this._meter.metrics,
+                        });
+                        return result;
+                    }
                 }
                 catch (error) {
-                    // End cycle tracking and span with error
                     this._meter.endCycle(cycleStartTime);
                     this._tracer.endAgentLoopSpan(cycleSpan, { error: error });
                     throw error;
@@ -428,12 +464,31 @@ export class Agent {
                 accumulatedUsage: this._meter.metrics.accumulatedUsage,
                 ...(result?.stopReason && { stopReason: result.stopReason }),
             });
-            // Cleanup structured output context
-            context.cleanup(this._toolRegistry);
+            // Cleanup structured output tool
+            if (structuredOutputTool) {
+                this._toolRegistry.remove(STRUCTURED_OUTPUT_TOOL_NAME);
+            }
             // Always emit final event
             yield new AfterInvocationEvent({ agent: this });
         }
     }
+    /**
+     * Extracts the validated structured output result from tool execution.
+     *
+     * @param toolUseMessage - The assistant message containing tool use blocks
+     * @param toolResultMessage - The message containing tool results
+     * @returns The parsed structured output, or undefined if not found
+     */
+    _extractStructuredOutput(toolUseMessage, toolResultMessage) {
+        const toolUse = toolUseMessage.content.find((block) => block.type === 'toolUseBlock' && block.name === STRUCTURED_OUTPUT_TOOL_NAME);
+        if (!toolUse)
+            return undefined;
+        const toolResult = toolResultMessage.content.find((block) => block.type === 'toolResultBlock' && block.toolUseId === toolUse.toolUseId && block.status === 'success');
+        if (!toolResult)
+            return undefined;
+        const firstContent = toolResult.content[0];
+        return firstContent?.type === 'jsonBlock' ? firstContent.json : undefined;
+    }
     /**
      * Normalizes agent invocation input into an array of messages to append.
      *
@@ -496,20 +551,15 @@ export class Agent {
      * @param toolChoice - Optional tool choice to force specific tool usage
      * @returns Object containing the assistant message, stop reason, and optional redaction message
      */
-    async *invokeModel(args, forcedToolChoice) {
-        // Normalize input and append messages to conversation
-        const messagesToAppend = this._normalizeInput(args);
-        for (const message of messagesToAppend) {
-            yield this._appendMessage(message);
-        }
+    async *_invokeModel(toolChoice) {
         const toolSpecs = this._toolRegistry.list().map((tool) => tool.toolSpec);
         const streamOptions = { toolSpecs };
         if (this.systemPrompt !== undefined) {
             streamOptions.systemPrompt = this.systemPrompt;
         }
-        // Add tool choice if provided (for structured output forcing)
-        if (forcedToolChoice) {
-            streamOptions.toolChoice = forcedToolChoice;
+        // Add tool choice if provided
+        if (toolChoice) {
+            streamOptions.toolChoice = toolChoice;
         }
         yield new BeforeModelCallEvent({ agent: this });
         // Start model span within loop span context
@@ -517,6 +567,7 @@ export class Agent {
         const modelSpan = this._tracer.startModelInvokeSpan({
             messages: this.messages,
             ...(modelId && { modelId }),
+            ...(this.systemPrompt !== undefined && { systemPrompt: this.systemPrompt }),
         });
         try {
             const result = yield* this._streamFromModel(this.messages, streamOptions);
@@ -524,10 +575,12 @@ export class Agent {
             this._meter.updateCycle(result.metadata);
             // End model span with usage
             const usage = result.metadata?.usage;
+            const metrics = result.metadata?.metrics;
             this._tracer.endModelInvokeSpan(modelSpan, {
                 output: result.message,
                 stopReason: result.stopReason,
                 ...(usage && { usage }),
+                ...(metrics && { metrics }),
             });
             yield new ModelMessageEvent({ agent: this, message: result.message, stopReason: result.stopReason });
             // Handle user content redaction if guardrails blocked input
@@ -542,7 +595,7 @@ export class Agent {
             const afterModelCallEvent = new AfterModelCallEvent({ agent: this, stopData });
             yield afterModelCallEvent;
             if (afterModelCallEvent.retry) {
-                return yield* this.invokeModel(args);
+                return yield* this._invokeModel(toolChoice);
             }
             return result;
         }
@@ -556,7 +609,7 @@ export class Agent {
             yield errorEvent;
             // After yielding, hooks have been invoked and may have set retry
             if (errorEvent.retry) {
-                return yield* this.invokeModel(args);
+                return yield* this._invokeModel(toolChoice);
             }
             // Re-throw error
             throw error;
@@ -604,26 +657,46 @@ export class Agent {
      * @returns User message containing tool results
      */
     async *executeTools(assistantMessage, toolRegistry) {
-        yield new BeforeToolsEvent({ agent: this, message: assistantMessage });
-        // Extract tool use blocks from assistant message
-        const toolUseBlocks = assistantMessage.content.filter((block) => block.type === 'toolUseBlock');
-        if (toolUseBlocks.length === 0) {
-            // No tool use blocks found even though stopReason is toolUse
-            throw new Error('Model indicated toolUse but no tool use blocks found in message');
-        }
+        const beforeToolsEvent = new BeforeToolsEvent({ agent: this, message: assistantMessage });
+        yield beforeToolsEvent;
         const toolResultBlocks = [];
-        for (const toolUseBlock of toolUseBlocks) {
-            const toolResultBlock = yield* this.executeTool(toolUseBlock, toolRegistry);
-            toolResultBlocks.push(toolResultBlock);
-            // Yield the tool result event as it's created
-            yield new ToolResultEvent({ agent: this, result: toolResultBlock });
+        let toolResultMessage;
+        try {
+            // Extract tool use blocks from assistant message
+            const toolUseBlocks = assistantMessage.content.filter((block) => block.type === 'toolUseBlock');
+            if (toolUseBlocks.length === 0) {
+                // No tool use blocks found even though stopReason is toolUse
+                throw new Error('Model indicated toolUse but no tool use blocks found in message');
+            }
+            // Cancel all tools if hook requested it
+            if (beforeToolsEvent.cancel) {
+                const cancelMessage = cancelToolMessage(beforeToolsEvent.cancel);
+                const cancelBlocks = toolUseBlocks.map((block) => new ToolResultBlock({
+                    toolUseId: block.toolUseId,
+                    status: 'error',
+                    content: [new TextBlock(cancelMessage)],
+                }));
+                for (const result of cancelBlocks) {
+                    yield new ToolResultEvent({ agent: this, result });
+                }
+                toolResultBlocks.push(...cancelBlocks);
+            }
+            else {
+                for (const toolUseBlock of toolUseBlocks) {
+                    const toolResultBlock = yield* this.executeTool(toolUseBlock, toolRegistry);
+                    toolResultBlocks.push(toolResultBlock);
+                    // Yield the tool result event as it's created
+                    yield new ToolResultEvent({ agent: this, result: toolResultBlock });
+                }
+            }
+        }
+        finally {
+            toolResultMessage = new Message({
+                role: 'user',
+                content: toolResultBlocks,
+            });
+            yield new AfterToolsEvent({ agent: this, message: toolResultMessage });
         }
-        // Create user message with tool results
-        const toolResultMessage = new Message({
-            role: 'user',
-            content: toolResultBlocks,
-        });
-        yield new AfterToolsEvent({ agent: this, message: toolResultMessage });
         return toolResultMessage;
     }
     /**
@@ -646,7 +719,28 @@ export class Agent {
         };
         // Retry loop for tool execution
         while (true) {
-            yield new BeforeToolCallEvent({ agent: this, toolUse, tool });
+            const beforeToolCallEvent = new BeforeToolCallEvent({ agent: this, toolUse, tool });
+            yield beforeToolCallEvent;
+            // Cancel individual tool if hook requested it
+            if (beforeToolCallEvent.cancel) {
+                const cancelMessage = cancelToolMessage(beforeToolCallEvent.cancel);
+                const toolResult = new ToolResultBlock({
+                    toolUseId: toolUseBlock.toolUseId,
+                    status: 'error',
+                    content: [new TextBlock(cancelMessage)],
+                });
+                const afterToolCallEvent = new AfterToolCallEvent({
+                    agent: this,
+                    toolUse,
+                    tool,
+                    result: toolResult,
+                });
+                yield afterToolCallEvent;
+                if (afterToolCallEvent.retry) {
+                    continue;
+                }
+                return toolResult;
+            }
             // Start tool span within loop span context
             const toolSpan = this._tracer.startToolCallSpan({
                 tool: toolUse,
@@ -774,7 +868,7 @@ export class Agent {
             }
             else if (lastMessage) {
                 // Unexpected state: redaction requested but last message is not from user
-                logger.warn(`role=<${lastMessage.role}> | received input redaction but last message is not from user | redaction skipped.`);
+                logger.warn(`role=<${lastMessage.role}> | received input redaction but last message is not from user | redaction skipped`);
             }
         }
     }
@@ -789,6 +883,14 @@ export class Agent {
         return new MessageAddedEvent({ agent: this, message });
     }
 }
+/**
+ * Returns the cancel message for a cancelled tool.
+ * @param cancelTool - The cancel value (true or custom message)
+ * @returns The cancel message string
+ */
+function cancelToolMessage(cancelTool) {
+    return typeof cancelTool === 'string' ? cancelTool : 'tool cancelled by hook';
+}
 /**
  * Recursively flattens nested arrays of tools into a single flat array.
  * @param tools - Tools or nested arrays of tools