@microfox/ai-router 1.1.2 → 2.0.0

package/dist/index.js

@@ -35,14 +35,17 @@ __export(index_exports, {
   AiKitError: () => AiKitError,
   AiRouter: () => AiRouter,
   MaxCallDepthExceededError: () => MaxCallDepthExceededError,
+  MemoryStore: () => MemoryStore,
   StreamWriter: () => StreamWriter,
   ToolNotFoundError: () => ToolNotFoundError,
   ToolValidationError: () => ToolValidationError,
   findFirstElement: () => findFirstElement,
   findLastElement: () => findLastElement,
   findLastMessageWith: () => findLastMessageWith,
+  getGlobalLogger: () => getGlobalLogger,
   getTextParts: () => getTextParts,
-  getTextPartsContent: () => getTextPartsContent
+  getTextPartsContent: () => getTextPartsContent,
+  setGlobalLogger: () => setGlobalLogger
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -105,26 +108,26 @@ var StreamWriter = class {
       });
     };
     this.writeCustomTool = (tool2) => {
-      const toolCallId = tool2.toolName?.toString() + "-" + this.generateId();
+      const toolCallId = tool2.toolCallId || tool2.toolName?.toString() + "-" + this.generateId();
       if ("input" in tool2 && tool2.input) {
         this.writer.write({
           type: "tool-input-available",
           input: tool2.input,
-          toolCallId: toolCallId || tool2.toolCallId || "",
+          toolCallId,
           toolName: tool2.toolName
         });
       }
       if (tool2.inputTextDelta && tool2.inputTextDelta.length > 0 || "output" in tool2 && tool2.output) {
         this.writer.write({
           type: "tool-input-start",
-          toolCallId: toolCallId || tool2.toolCallId || "",
+          toolCallId,
           toolName: tool2.toolName
         });
         if (tool2.inputTextDelta) {
           for (const delta of tool2.inputTextDelta) {
             this.writer.write({
               type: "tool-input-delta",
-              toolCallId: toolCallId || tool2.toolCallId || "",
+              toolCallId,
               inputTextDelta: delta
             });
           }
@@ -133,13 +136,13 @@ var StreamWriter = class {
       if ("output" in tool2 && tool2.output) {
         this.writer.write({
           type: "tool-output-available",
-          toolCallId: toolCallId || tool2.toolCallId || "",
+          toolCallId,
           output: tool2.output
         });
       }
     };
     this.writeObjectAsTool = (tool2) => {
-      if (!tool2.result.object) {
+      if (!tool2.result?.object) {
         throw new Error("No object found in the GenerateObjectResult");
       }
       const toolCallId = tool2.toolName.toString() + "-" + this.generateId();
@@ -151,17 +154,17 @@ var StreamWriter = class {
       this.writer.write({
         type: "tool-input-available",
         toolCallId,
-        input: {
-          usage: tool2.result.usage,
-          warnings: tool2.result.warnings,
-          finishReason: tool2.result.finishReason
-        },
+        input: tool2.input ?? tool2.result ? {
+          usage: tool2.result?.usage,
+          warnings: tool2.result?.warnings,
+          finishReason: tool2.result?.finishReason
+        } : void 0,
         toolName: tool2.toolName
       });
       this.writer.write({
         type: "tool-output-available",
         toolCallId,
-        output: tool2.result.object
+        output: tool2.result?.object
       });
     };
     this.writer = writer;
@@ -189,6 +192,90 @@ var findLastMessageWith = (message, filters) => {
 
 // src/router.ts
 var import_path = __toESM(require("path"));
+
+// src/store.ts
+var MemoryStore = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+  }
+  async get(key) {
+    return this.store.get(key);
+  }
+  async set(key, value) {
+    this.store.set(key, value);
+  }
+  async delete(key) {
+    this.store.delete(key);
+  }
+  async has(key) {
+    return this.store.has(key);
+  }
+};
+
+// src/router.ts
+var globalLogger = void 0;
+function setGlobalLogger(logger) {
+  globalLogger = logger;
+}
+function getGlobalLogger() {
+  return globalLogger;
+}
+function clubParts(parts) {
+  if (!parts || parts.length === 0) return parts;
+  const clubbedParts = [];
+  const toolCallIdGroups = /* @__PURE__ */ new Map();
+  const dataIdGroups = /* @__PURE__ */ new Map();
+  for (const part of parts) {
+    if (part.type?.startsWith("tool-") && part.toolCallId) {
+      const toolCallId = part.toolCallId;
+      if (!toolCallIdGroups.has(toolCallId)) {
+        toolCallIdGroups.set(toolCallId, []);
+      }
+      toolCallIdGroups.get(toolCallId).push(part);
+    } else if (part.type?.startsWith("data-") && part.id) {
+      const id = part.id;
+      if (!dataIdGroups.has(id)) {
+        dataIdGroups.set(id, []);
+      }
+      dataIdGroups.get(id).push(part);
+    } else {
+      clubbedParts.push(part);
+    }
+  }
+  for (const [toolCallId, toolParts] of toolCallIdGroups) {
+    if (toolParts.length === 1) {
+      clubbedParts.push(toolParts[0]);
+    } else {
+      const mergedPart = { ...toolParts[0] };
+      for (let i = 1; i < toolParts.length; i++) {
+        const currentPart = toolParts[i];
+        Object.keys(currentPart).forEach((key) => {
+          if (key !== "type" && key !== "toolCallId") {
+            mergedPart[key] = currentPart[key];
+          }
+        });
+      }
+      clubbedParts.push(mergedPart);
+    }
+  }
+  for (const [id, dataParts] of dataIdGroups) {
+    if (dataParts.length === 1) {
+      clubbedParts.push(dataParts[0]);
+    } else {
+      const mergedPart = { ...dataParts[0] };
+      for (let i = 1; i < dataParts.length; i++) {
+        const currentPart = dataParts[i];
+        Object.keys(currentPart).forEach((key) => {
+          if (key !== "type" && key !== "id") {
+            mergedPart[key] = currentPart[key];
+          }
+        });
+      }
+      clubbedParts.push(mergedPart);
+    }
+  }
+  return clubbedParts;
+}
 var AiKitError = class extends Error {
   constructor(message) {
     super(message);
@@ -268,14 +355,14 @@ var AiRouter = class _AiRouter {
   constructor(stack, options) {
     this.stack = [];
     this.actAsToolDefinitions = /* @__PURE__ */ new Map();
-    this.logger = console;
+    this.logger = void 0;
+    this._store = new MemoryStore();
+    this.toolExecutionPromise = Promise.resolve();
     /** Configuration options for the router instance. */
     this.options = {
       maxCallDepth: 10
     };
     this.pendingExecutions = 0;
-    this.logger = options?.logger ?? console;
-    this.logger.log("AiAgentKit v3 initialized.");
     if (stack) {
       this.stack = stack;
     }
@@ -283,6 +370,25 @@ var AiRouter = class _AiRouter {
       this.options.maxCallDepth = options.maxCallDepth;
     }
   }
+  setStore(store) {
+    this._store = store;
+  }
+  /**
+   * Sets a logger for this router instance.
+   * If no logger is set, the router will fall back to the global logger.
+   * @param logger The logger to use for this router instance, or undefined to use global logger
+   */
+  setLogger(logger) {
+    this.logger = logger;
+  }
+  /**
+   * Gets the effective logger for this router instance.
+   * Returns instance logger if set, otherwise falls back to global logger.
+   * @returns The effective logger or undefined if no logging should occur
+   */
+  _getEffectiveLogger() {
+    return this.logger ?? globalLogger;
+  }
   /**
    * Registers a middleware-style agent that runs for a specific path prefix, regex pattern, or wildcard.
    * Agents can modify the context and must call `next()` to pass control to the next handler in the chain.
@@ -303,7 +409,7 @@ var AiRouter = class _AiRouter {
         if (handler instanceof _AiRouter && typeof prefix === "string") {
           const stackToMount = handler.getStackWithPrefix(prefix);
           this.stack.push(...stackToMount);
-          this.logger.log(
+          this.logger?.log(
             `Router mounted: path=${prefix}, layers=${stackToMount.length}`
           );
           const mountPath = prefix.toString();
@@ -323,7 +429,7 @@ var AiRouter = class _AiRouter {
         isAgent: true
         // Mark as an agent
       });
-      this.logger.log(`Agent registered: path=${prefix}`);
+      this.logger?.log(`Agent registered: path=${prefix}`);
     }
     return this;
   }
@@ -374,19 +480,62 @@ var AiRouter = class _AiRouter {
    */
   actAsTool(path2, options) {
     this.actAsToolDefinitions.set(path2, options);
-    this.logger.log(
-      `[actAsTool] Added definition: ${path2} -> ${JSON.stringify(options)}`
-    );
-    this.logger.log(
+    this.logger?.log(`[actAsTool] Added definition: at path ${path2}`);
+    this.logger?.log(
       `[actAsTool] Router now has ${this.actAsToolDefinitions.size} definitions`
     );
     return this;
   }
+  getToolSet() {
+    let allTools = Array.from(this.actAsToolDefinitions.entries()).map(
+      ([key, value]) => {
+        return {
+          ...value,
+          metadata: {
+            ...value.metadata,
+            absolutePath: key
+          }
+        };
+      }
+    );
+    return allTools.reduce((acc, _tool) => {
+      const { inputSchema, outputSchema } = _tool;
+      acc[_tool.id] = {
+        ...(0, import_ai.tool)(
+          _tool
+        ),
+        metadata: {
+          ..._tool.metadata,
+          toolKey: _tool.id,
+          name: _tool.name,
+          description: _tool.description
+        }
+      };
+      return acc;
+    }, {});
+  }
+  getToolDefinition(path2) {
+    let definition = this.actAsToolDefinitions.get(path2);
+    if (!definition) {
+      this.logger?.error(
+        `[getToolDefinition] No definition found for path: ${path2}`
+      );
+      throw new AgentDefinitionMissingError(path2);
+    }
+    return definition;
+  }
+  /**
+   * @deprecated Use agent-as-tools pattern instead. Create an agent and use `.actAsTool()` to expose it as a tool.
+   * This method will be removed in a future version.
+   */
   // Implementation
   tool(path2, optionsOrFactory, handler) {
-    this.logger.log(`[AiAgentKit][tool] Registering tool at path:`, path2);
+    this.logger?.warn(
+      `[DEPRECATION WARNING] router.tool() is deprecated and will be removed in a future version. Please migrate to the agent-as-tools pattern: router.agent('${path2}', async (ctx) => {...}).actAsTool('${path2}', {...})`
+    );
+    this.logger?.log(`[AiAgentKit][tool] Registering tool at path:`, path2);
     if (this.stack.some((l) => l.isTool && l.path === path2)) {
-      this.logger.error(
+      this.logger?.error(
         `[AiAgentKit][tool] Tool already registered for path: ${path2}`
       );
       throw new AiKitError(`A tool is already registered for path: ${path2}`);
@@ -395,7 +544,7 @@ var AiRouter = class _AiRouter {
       const factory = optionsOrFactory;
       const isDynamicPath = typeof path2 === "string" && hasDynamicParams(path2);
       const toolMiddleware = async (ctx, _next) => {
-        this.logger.log(
+        this.logger?.log(
           `[Tool Middleware] Executing factory for path "${path2}". Messages in context: ${ctx.request.messages?.length ?? "undefined"}`
         );
         const toolObject = factory(ctx);
@@ -406,14 +555,14 @@ var AiRouter = class _AiRouter {
         }
         const schema = toolObject.inputSchema;
         if (!schema) {
-          this.logger.warn(
+          this.logger?.warn(
             `[AiAgentKit][tool] Factory-based tool at path ${path2} has no inputSchema. Executing without params.`
           );
           return toolObject.execute({}, {});
         }
         const parsedParams = schema.safeParse(ctx.request.params);
         if (!parsedParams.success) {
-          this.logger.error(
+          this.logger?.error(
             `[AiAgentKit][tool] Tool call validation failed for path: ${path2}:`,
             parsedParams.error.message
           );
@@ -435,7 +584,7 @@ var AiRouter = class _AiRouter {
         isAgent: false,
         hasDynamicParams: isDynamicPath
       });
-      this.logger.log(
+      this.logger?.log(
         `Tool registered: path=${path2}, type=factory${isDynamicPath ? " (dynamic)" : ""}`
       );
       return this;
@@ -447,7 +596,7 @@ var AiRouter = class _AiRouter {
       const toolMiddleware = async (ctx, _next) => {
         if (isDynamicPath && typeof path2 === "string") {
           const pathParams = extractPathParams(path2, ctx.request.path || "");
-          this.logger.log(
+          this.logger?.log(
             `[AiAgentKit][tool] Extracted dynamic path params:`,
             pathParams
           );
@@ -460,7 +609,7 @@ var AiRouter = class _AiRouter {
         }
         const parsedParams = options.schema.safeParse(ctx.request.params);
         if (!parsedParams.success) {
-          this.logger.error(
+          this.logger?.error(
             `[AiAgentKit][tool] Tool call validation failed for path: ${path2}:`,
             parsedParams.error.message
           );
@@ -483,12 +632,12 @@ var AiRouter = class _AiRouter {
         hasDynamicParams: isDynamicPath,
         paramNames: dynamicParamInfo?.paramNames
       });
-      this.logger.log(
+      this.logger?.log(
         `Tool registered: path=${path2}, type=static${isDynamicPath ? " (dynamic)" : ""}`
       );
       return this;
     }
-    this.logger.error(
+    this.logger?.error(
       `[AiAgentKit][tool] Invalid arguments for tool registration at path: ${path2}`
     );
     throw new AiKitError(
@@ -523,6 +672,54 @@ var AiRouter = class _AiRouter {
       };
     });
   }
+  /**
+   * Outputs all registered paths, and the tool definitions, middlewares, and agents registered on each path.
+   * @returns A map of paths to their registered handlers.
+   */
+  registry() {
+    const registryMap = {};
+    for (const layer of this.stack) {
+      const pathKey = layer.path.toString();
+      if (!registryMap[pathKey]) {
+        registryMap[pathKey] = { middlewares: [], tools: [], agents: [] };
+      }
+      if (layer.isTool) {
+        let toolInfo = { type: layer.toolOptions?.type };
+        if (layer.toolOptions?.type === "static") {
+          toolInfo = {
+            ...toolInfo,
+            schema: layer.toolOptions.schema,
+            description: layer.toolOptions.description
+          };
+        } else if (layer.toolOptions?.type === "factory") {
+          toolInfo = {
+            ...toolInfo,
+            factory: layer.toolOptions.factory.toString()
+          };
+        }
+        registryMap[pathKey].tools.push(toolInfo);
+      } else if (layer.isAgent) {
+        const agentInfo = {
+          handler: layer.handler.name || "anonymous"
+        };
+        const actAsToolDef = this.actAsToolDefinitions.get(layer.path);
+        if (actAsToolDef) {
+          agentInfo.actAsTool = {
+            ...actAsToolDef
+          };
+        }
+        registryMap[pathKey].agents.push(agentInfo);
+      } else {
+        registryMap[pathKey].middlewares.push({
+          handler: layer.handler.name || "anonymous"
+        });
+      }
+    }
+    return {
+      map: registryMap,
+      tools: this.getToolSet()
+    };
+  }
   /**
    * Resolves a path based on the parent path and the requested path.
    * - If path starts with `@/`, it's an absolute path from the root.
@@ -549,6 +746,7 @@ var AiRouter = class _AiRouter {
       // State is passed by reference to allow sub-agents to modify the parent's state.
       // The execution context is a shallow copy to ensure call-specific data is isolated.
       state: parentCtx.state,
+      store: parentCtx.store,
       executionContext: {
         ...parentCtx.executionContext,
         currentPath: options.path,
@@ -584,13 +782,24 @@ var AiRouter = class _AiRouter {
    * @internal
    */
   _createLogger(requestId, path2, callDepth = 0) {
+    const effectiveLogger = this._getEffectiveLogger();
+    if (!effectiveLogger) {
+      return {
+        log: () => {
+        },
+        warn: () => {
+        },
+        error: () => {
+        }
+      };
+    }
     const indent = "  ".repeat(callDepth);
     const prefix = `${indent}[${path2.toString()}]`;
     const fullPrefix = `[${requestId}]${prefix}`;
     return {
-      log: (...args) => this.logger.log(fullPrefix, ...args),
-      warn: (...args) => this.logger.warn(fullPrefix, ...args),
-      error: (...args) => this.logger.error(fullPrefix, ...args)
+      log: (...args) => effectiveLogger.log(fullPrefix, ...args),
+      warn: (...args) => effectiveLogger.warn(fullPrefix, ...args),
+      error: (...args) => effectiveLogger.error(fullPrefix, ...args)
     };
   }
   /**
@@ -725,83 +934,162 @@ var AiRouter = class _AiRouter {
    * @returns A standard `Response` object containing the rich UI stream.
    */
   handle(path2, initialContext) {
-    this.logger.log(`Handling request for path: ${path2}`);
+    this.logger?.log(`Handling request for path: ${path2}`);
     const self = this;
     let executionCompletionResolver = null;
     const executionCompletionPromise = new Promise((resolve) => {
       executionCompletionResolver = resolve;
     });
     return (0, import_ai.createUIMessageStreamResponse)({
-      stream: (0, import_ai.createUIMessageStream)({
-        originalMessages: initialContext.request.messages,
-        execute: async ({ writer }) => {
-          const streamWriter = new StreamWriter(writer);
-          const requestId = (0, import_ai.generateId)();
-          const ctx = {
-            ...initialContext,
-            request: {
-              ...initialContext.request,
-              path: path2
-              // Set the initial path for the root context
-            },
-            state: {},
-            executionContext: { currentPath: path2, callDepth: 0 },
-            requestId,
-            logger: self._createLogger(requestId, path2, 0),
-            response: {
-              ...streamWriter.writer,
-              writeMessageMetadata: streamWriter.writeMessageMetadata,
-              writeCustomTool: streamWriter.writeCustomTool,
-              writeObjectAsTool: streamWriter.writeObjectAsTool,
-              generateId: import_ai.generateId
-            },
-            next: void 0,
-            // Will be replaced right after
-            _onExecutionStart: () => {
-              self.pendingExecutions++;
-              self.logger.log(
-                `[AiAgentKit][lifecycle] Execution started. Pending: ${self.pendingExecutions}`
-              );
-            },
-            _onExecutionEnd: () => {
-              self.pendingExecutions--;
-              self.logger.log(
-                `[AiAgentKit][lifecycle] Execution ended. Pending: ${self.pendingExecutions}`
+      stream: self.handleStream(
+        path2,
+        initialContext,
+        executionCompletionPromise,
+        executionCompletionResolver
+      )
+    });
+  }
+  handleStream(path2, initialContext, executionCompletionPromise, executionCompletionResolver) {
+    const self = this;
+    return (0, import_ai.createUIMessageStream)({
+      originalMessages: initialContext.request.messages,
+      execute: async ({ writer }) => {
+        const streamWriter = new StreamWriter(writer);
+        const requestId = (0, import_ai.generateId)();
+        const store = self._store instanceof MemoryStore ? new MemoryStore() : self._store;
+        const ctx = {
+          ...initialContext,
+          request: {
+            ...initialContext.request,
+            path: path2
+            // Set the initial path for the root context
+          },
+          state: {},
+          store,
+          executionContext: { currentPath: path2, callDepth: 0 },
+          requestId,
+          logger: self._createLogger(requestId, path2, 0),
+          response: {
+            ...streamWriter.writer,
+            writeMessageMetadata: streamWriter.writeMessageMetadata,
+            writeCustomTool: streamWriter.writeCustomTool,
+            writeObjectAsTool: streamWriter.writeObjectAsTool,
+            generateId: import_ai.generateId
+          },
+          next: void 0,
+          // Will be replaced right after
+          _onExecutionStart: () => {
+            self.pendingExecutions++;
+            self.logger?.log(
+              `[AiAgentKit][lifecycle] Execution started. Pending: ${self.pendingExecutions}`
+            );
+          },
+          _onExecutionEnd: () => {
+            self.pendingExecutions--;
+            self.logger?.log(
+              `[AiAgentKit][lifecycle] Execution ended. Pending: ${self.pendingExecutions}`
+            );
+            if (self.pendingExecutions === 0 && executionCompletionResolver) {
+              self.logger?.log(
+                `[AiAgentKit][lifecycle] All executions finished. Resolving promise.`
               );
-              if (self.pendingExecutions === 0 && executionCompletionResolver) {
-                self.logger.log(
-                  `[AiAgentKit][lifecycle] All executions finished. Resolving promise.`
-                );
-                executionCompletionResolver();
-              }
+              executionCompletionResolver();
             }
-          };
-          ctx.next = new NextHandler(
-            ctx,
-            self,
-            ctx._onExecutionStart,
-            ctx._onExecutionEnd
-          );
-          ctx._onExecutionStart();
-          self.logger.log(
-            `[AiAgentKit][lifecycle] Main execution chain started.`
-          );
-          try {
-            await self._execute(path2, ctx);
-          } catch (err) {
-            ctx.logger.error("Unhandled error in main execution chain", err);
-          } finally {
-            ctx._onExecutionEnd();
-            self.logger.log(
-              `[AiAgentKit][lifecycle] Main execution chain finished.`
-            );
           }
-          await executionCompletionPromise;
-          self.logger.log(
-            `[AiAgentKit][lifecycle] All executions truly finished. Stream can be safely closed.`
+        };
+        ctx.next = new NextHandler(
+          ctx,
+          self,
+          ctx._onExecutionStart,
+          ctx._onExecutionEnd
+        );
+        ctx._onExecutionStart();
+        self.logger?.log(
+          `[AiAgentKit][lifecycle] Main execution chain started.`
+        );
+        try {
+          const response = await self._execute(path2, ctx);
+          const toolDefinition = this.actAsToolDefinitions.get(path2);
+          if (toolDefinition && !toolDefinition.metadata?.hideUI) {
+            ctx.response.writeCustomTool({
+              toolName: toolDefinition.id,
+              toolCallId: toolDefinition.id + "-" + ctx.response.generateId(),
+              output: response
+            });
+          }
+          return response;
+        } catch (err) {
+          ctx.logger.error("Unhandled error in main execution chain", err);
+        } finally {
+          ctx._onExecutionEnd();
+          self.logger?.log(
+            `[AiAgentKit][lifecycle] Main execution chain finished.`
           );
         }
-      })
+        await executionCompletionPromise;
+        self.logger?.log(
+          `[AiAgentKit][lifecycle] All executions truly finished. Stream can be safely closed.`
+        );
+      }
+    });
+  }
+  /**
+   * Handles an incoming request and returns a promise that resolves with the full,
+   * non-streamed response. This is useful for environments where streaming is not
+   * desired or for testing.
+   *
+   * @param path The path of the agent or tool to execute.
+   * @param initialContext The initial context for the request, typically containing messages.
+   * @returns A `Promise<Response>` that resolves with the final JSON response.
+   */
+  async toAwaitResponse(path2, initialContext) {
+    this.logger?.log(`Handling request for path: ${path2}`);
+    const self = this;
+    let executionCompletionResolver = null;
+    const executionCompletionPromise = new Promise((resolve) => {
+      executionCompletionResolver = resolve;
+    });
+    const stream = this.handleStream(
+      path2,
+      initialContext,
+      executionCompletionPromise,
+      executionCompletionResolver
+    );
+    const messageStream = (0, import_ai.readUIMessageStream)({
+      stream,
+      onError: (error) => {
+        this.logger?.error("Error reading UI message stream", error);
+      }
+    });
+    let finalMessages = [];
+    const thisMessageId = (0, import_ai.generateId)();
+    for await (const message of messageStream) {
+      if (message.id?.length > 0) {
+        finalMessages.push(message);
+      } else if (finalMessages.find((m) => m.id === thisMessageId)) {
+        finalMessages = finalMessages.map(
+          (m) => m.id === thisMessageId ? {
+            ...m,
+            metadata: {
+              ...m.metadata ?? {},
+              ...message.metadata ?? {}
+            },
+            parts: clubParts([
+              ...m.parts ?? [],
+              ...message.parts ?? []
+            ])
+          } : m
+        );
+      } else {
+        finalMessages.push({
+          ...message,
+          id: thisMessageId
+        });
+      }
+    }
+    const responseBody = JSON.stringify(finalMessages);
+    return new Response(responseBody, {
+      headers: { "Content-Type": "application/json" }
     });
   }
 };
@@ -831,14 +1119,30 @@ var NextHandler = class {
       const subContext = this.router._createSubContext(this.ctx, {
         type: "agent",
         path: resolvedPath,
-        params,
+        params: params ?? {},
         messages: this.ctx.request.messages
       });
+      const definition = this.router.actAsToolDefinitions.get(resolvedPath);
+      const toolCallId = definition?.id + "-" + this.ctx.response.generateId();
+      if (options?.streamToUI && definition) {
+        this.ctx.response.writeCustomTool({
+          toolName: definition?.id,
+          toolCallId,
+          input: subContext.request.params
+        });
+      }
       const data = await this.router._execute(
         resolvedPath,
         subContext,
         true
       );
+      if (options?.streamToUI && definition) {
+        this.ctx.response.writeCustomTool({
+          toolName: definition?.id,
+          toolCallId,
+          output: data
+        });
+      }
       return { ok: true, data };
     } catch (error) {
       this.ctx.logger.error(`[callAgent] Error:`, error);
@@ -847,7 +1151,23 @@ var NextHandler = class {
       this.onExecutionEnd();
     }
   }
+  /**
+   * @deprecated Use agent-as-tools pattern instead. Use `ctx.next.callAgent()` to call agents that are exposed as tools.
+   * This method will be removed in a future version.
+   *
+   * Example migration:
+   * ```typescript
+   * // Old way (deprecated):
+   * const result = await ctx.next.callTool('/calculator', { a: 5, b: 3 });
+   *
+   * // New way (recommended):
+   * const result = await ctx.next.callAgent('/calculator', { a: 5, b: 3 });
+   * ```
+   */
   async callTool(toolPath, params, options) {
+    this.ctx.logger.warn(
+      `[DEPRECATION WARNING] ctx.next.callTool() is deprecated and will be removed in a future version. Please use ctx.next.callAgent() instead to call agents that are exposed as tools.`
+    );
     this.onExecutionStart();
     try {
       const parentPath = this.ctx.executionContext.currentPath || "/";
@@ -859,7 +1179,7 @@ var NextHandler = class {
       const subContext = this.router._createSubContext(this.ctx, {
         type: "tool",
         path: resolvedPath,
-        params,
+        params: params ?? {},
         messages: this.ctx.request.messages
       });
       const data = await this.router._execute(
@@ -875,7 +1195,23 @@ var NextHandler = class {
       this.onExecutionEnd();
     }
   }
+  /**
+   * @deprecated Use agent-as-tools pattern instead. Use `ctx.next.agentAsTool()` to attach agents as tools.
+   * This method will be removed in a future version.
+   *
+   * Example migration:
+   * ```typescript
+   * // Old way (deprecated):
+   * const tool = ctx.next.attachTool('/calculator');
+   *
+   * // New way (recommended):
+   * const tool = ctx.next.agentAsTool('/calculator');
+   * ```
+   */
   attachTool(toolPath, _tool) {
+    this.ctx.logger.warn(
+      `[DEPRECATION WARNING] ctx.next.attachTool() is deprecated and will be removed in a future version. Please use ctx.next.agentAsTool() instead to attach agents as tools.`
+    );
     const parentPath = this.ctx.executionContext.currentPath || "/";
     const resolvedPath = this.router._resolvePath(
       parentPath,
@@ -953,14 +1289,81 @@ var NextHandler = class {
       );
       throw new AgentDefinitionMissingError(resolvedPath);
     }
+    const { id, metadata, ...restDefinition } = definition;
     return {
-      ...definition,
-      execute: async (params, options) => {
-        const result = await this.callAgent(agentPath, params, options);
-        if (!result.ok) {
-          throw result.error;
+      [id]: {
+        ...restDefinition,
+        metadata: {
+          ...metadata,
+          toolKey: id,
+          name: restDefinition.name,
+          description: restDefinition.description,
+          absolutePath: restDefinition.path
+        },
+        execute: (params, options) => {
+          const executeInternal = async () => {
+            const result = await this.callAgent(agentPath, params, options);
+            if (!result.ok) {
+              throw result.error;
+            }
+            return result.data;
+          };
+          const newPromise = this.router.toolExecutionPromise.then(
+            executeInternal,
+            executeInternal
+          );
+          this.router.toolExecutionPromise = newPromise;
+          return newPromise;
         }
-        return result.data;
+      }
+    };
+  }
+  getToolDefinition(agentPath) {
+    const parentPath = this.ctx.executionContext.currentPath || "/";
+    const resolvedPath = this.router._resolvePath(
+      parentPath,
+      agentPath
+    );
+    let preDefined;
+    const pathsToTry = [resolvedPath];
+    if (typeof agentPath === "string" && agentPath.startsWith("/")) {
+      pathsToTry.unshift(agentPath);
+    }
+    for (const pathToTry of pathsToTry) {
+      for (const [key, value] of this.router.actAsToolDefinitions) {
+        if (typeof key === "string") {
+          if (key === pathToTry) {
+            preDefined = value;
+            break;
+          }
+          if (extractPathParams(key, pathToTry) !== null) {
+            preDefined = value;
+            break;
+          }
+        }
+        if (key instanceof RegExp && key.test(pathToTry)) {
+          preDefined = value;
+          break;
+        }
+      }
+      if (preDefined) break;
+    }
+    const definition = preDefined;
+    if (!definition) {
+      this.ctx.logger.error(
+        `[agentAsTool] No definition found for agent at resolved path: ${resolvedPath}`
+      );
+      throw new AgentDefinitionMissingError(resolvedPath);
+    }
+    const { metadata, ...restDefinition } = definition;
+    return {
+      ...restDefinition,
+      metadata: {
+        ...metadata,
+        toolKey: restDefinition.id,
+        name: restDefinition.name,
+        description: restDefinition.description,
+        absolutePath: restDefinition.path
       }
     };
   }
@@ -972,13 +1375,16 @@ var NextHandler = class {
   AiKitError,
   AiRouter,
   MaxCallDepthExceededError,
+  MemoryStore,
   StreamWriter,
   ToolNotFoundError,
   ToolValidationError,
   findFirstElement,
   findLastElement,
   findLastMessageWith,
+  getGlobalLogger,
   getTextParts,
-  getTextPartsContent
+  getTextPartsContent,
+  setGlobalLogger
 });
 //# sourceMappingURL=index.js.map