@microfox/ai-router 1.0.1

package/dist/index.mjs

@@ -0,0 +1,916 @@
+// src/router.ts
+import {
+  createUIMessageStream,
+  createUIMessageStreamResponse,
+  generateId,
+  convertToModelMessages
+} from "ai";
+
+// ../../node_modules/nanoid/index.js
+import crypto from "crypto";
+var POOL_SIZE_MULTIPLIER = 128;
+var pool;
+var poolOffset;
+var fillPool = (bytes) => {
+  if (!pool || pool.length < bytes) {
+    pool = Buffer.allocUnsafe(bytes * POOL_SIZE_MULTIPLIER);
+    crypto.randomFillSync(pool);
+    poolOffset = 0;
+  } else if (poolOffset + bytes > pool.length) {
+    crypto.randomFillSync(pool);
+    poolOffset = 0;
+  }
+  poolOffset += bytes;
+};
+var random = (bytes) => {
+  fillPool(bytes |= 0);
+  return pool.subarray(poolOffset - bytes, poolOffset);
+};
+var customRandom = (alphabet, defaultSize, getRandom) => {
+  let mask = (2 << 31 - Math.clz32(alphabet.length - 1 | 1)) - 1;
+  let step = Math.ceil(1.6 * mask * defaultSize / alphabet.length);
+  return (size = defaultSize) => {
+    let id = "";
+    while (true) {
+      let bytes = getRandom(step);
+      let i = step;
+      while (i--) {
+        id += alphabet[bytes[i] & mask] || "";
+        if (id.length === size) return id;
+      }
+    }
+  };
+};
+var customAlphabet = (alphabet, size = 21) => customRandom(alphabet, size, random);
+
+// src/helper.ts
+var findLastElement = (array) => {
+  return array[array.length - 1];
+};
+var findFirstElement = (array) => {
+  return array[0];
+};
+var StreamWriter = class {
+  constructor(writer) {
+    this.generateId = () => {
+      return customAlphabet("1234567890abcdefghijklmnopqrstuvwxyz", 10)();
+    };
+    this.writeMessageMetadata = (metadata) => {
+      return this.writer.write({
+        type: "message-metadata",
+        messageMetadata: metadata
+      });
+    };
+    this.writeCustomTool = (tool2) => {
+      const 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 || "",
+          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 || "",
+          toolName: tool2.toolName
+        });
+        if (tool2.inputTextDelta) {
+          for (const delta of tool2.inputTextDelta) {
+            this.writer.write({
+              type: "tool-input-delta",
+              toolCallId: toolCallId || tool2.toolCallId || "",
+              inputTextDelta: delta
+            });
+          }
+        }
+      }
+      if ("output" in tool2 && tool2.output) {
+        this.writer.write({
+          type: "tool-output-available",
+          toolCallId: toolCallId || tool2.toolCallId || "",
+          output: tool2.output
+        });
+      }
+    };
+    this.writeObjectAsTool = (tool2) => {
+      if (!tool2.result.object) {
+        throw new Error("No object found in the GenerateObjectResult");
+      }
+      const toolCallId = tool2.toolName.toString() + "-" + this.generateId();
+      this.writer.write({
+        type: "tool-input-start",
+        toolCallId,
+        toolName: tool2.toolName
+      });
+      this.writer.write({
+        type: "tool-input-available",
+        toolCallId,
+        input: {
+          usage: tool2.result.usage,
+          warnings: tool2.result.warnings,
+          finishReason: tool2.result.finishReason
+        },
+        toolName: tool2.toolName
+      });
+      this.writer.write({
+        type: "tool-output-available",
+        toolCallId,
+        output: tool2.result.object
+      });
+    };
+    this.writer = writer;
+  }
+};
+var getTextParts = (message) => {
+  if (!message) return [];
+  return message.parts.filter((part) => part.type === "text").map((part) => part.text);
+};
+var getTextPartsContent = (message) => {
+  if (!message) return "";
+  return message.parts.filter((part) => part.type === "text").map((part) => part.text).join("").trim();
+};
+var findLastMessageWith = (message, filters) => {
+  if (!message) return null;
+  return message.filter((m) => {
+    if (filters.role && m.role !== filters.role) return false;
+    if (filters.metadata) {
+      for (const key in filters.metadata) {
+      }
+    }
+    return true;
+  }).pop();
+};
+
+// src/router.ts
+import path from "path";
+var AiKitError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AiKitError";
+  }
+};
+var AgentNotFoundError = class extends AiKitError {
+  constructor(path2) {
+    super(`[AiAgentKit] Agent not found for path: ${path2}`);
+    this.name = "AgentNotFoundError";
+  }
+};
+var ToolNotFoundError = class extends AiKitError {
+  constructor(path2) {
+    super(`[AiAgentKit] Tool not found at path: ${path2}`);
+    this.name = "ToolNotFoundError";
+  }
+};
+var ToolValidationError = class extends AiKitError {
+  constructor(path2, validationError) {
+    const message = `[AiAgentKit] Tool call validation failed for path: ${path2}: ${validationError.message}`;
+    super(message);
+    this.name = "ToolValidationError";
+  }
+};
+var MaxCallDepthExceededError = class extends AiKitError {
+  constructor(maxDepth) {
+    super(`[AiAgentKit] Agent call depth limit (${maxDepth}) exceeded.`);
+    this.name = "MaxCallDepthExceededError";
+  }
+};
+var AgentDefinitionMissingError = class extends AiKitError {
+  constructor(path2) {
+    super(
+      `[AiAgentKit] agentAsTool: No definition found for "${path2}". Please define it using '.actAsTool()' or pass a definition as the second argument.`
+    );
+    this.name = "AgentDefinitionMissingError";
+  }
+};
+function parsePathPattern(pattern) {
+  const paramNames = [];
+  const parts = pattern.split(/(\/:[^\/]+)/);
+  const regexPattern = parts.map((part) => {
+    if (part.startsWith("/:")) {
+      paramNames.push(part.substring(2));
+      return "/([^/]+)";
+    }
+    return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }).join("");
+  const regex = new RegExp(`^${regexPattern}$`);
+  return { regex, paramNames };
+}
+function extractPathParams(pattern, path2) {
+  const { regex, paramNames } = parsePathPattern(pattern);
+  const match = path2.match(regex);
+  if (!match) {
+    return null;
+  }
+  const params = {};
+  paramNames.forEach((paramName, index) => {
+    const value = match[index + 1];
+    if (value !== void 0) {
+      params[paramName] = value;
+    }
+  });
+  return params;
+}
+function hasDynamicParams(pattern) {
+  return /\/:[^\/]+/.test(pattern);
+}
+var AiRouter = class _AiRouter {
+  /**
+   * Constructs a new AiAgentKit router.
+   * @param stack An optional initial stack of layers, used for composing routers.
+   * @param options Optional configuration for the router.
+   */
+  constructor(stack, options) {
+    this.stack = [];
+    this.actAsToolDefinitions = /* @__PURE__ */ new Map();
+    this.logger = console;
+    /** 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;
+    }
+    if (options?.maxCallDepth) {
+      this.options.maxCallDepth = options.maxCallDepth;
+    }
+  }
+  /**
+   * 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.
+   * This method is primarily for middleware. For terminal agents, see `.agent()` on an instance.
+   *
+   * @param path The path prefix, regex pattern, or "*" for wildcard matching.
+   * @param agents The agent middleware function(s).
+   */
+  agent(path2, ...agents) {
+    let prefix = "/";
+    if (typeof path2 === "string" || path2 instanceof RegExp) {
+      prefix = path2;
+    } else {
+      agents.unshift(path2);
+    }
+    for (const handler of agents) {
+      if (typeof handler !== "function") {
+        if (handler instanceof _AiRouter && typeof prefix === "string") {
+          const stackToMount = handler.getStackWithPrefix(prefix);
+          this.stack.push(...stackToMount);
+          this.logger.log(
+            `Router mounted: path=${prefix}, layers=${stackToMount.length}`
+          );
+        }
+        continue;
+      }
+      this.stack.push({
+        path: prefix,
+        handler,
+        isTool: false,
+        isAgent: true
+        // Mark as an agent
+      });
+      this.logger.log(`Agent registered: path=${prefix}`);
+    }
+    return this;
+  }
+  /**
+   * Mounts a middleware function or another AiAgentKit router at a specific path.
+   * This is the primary method for composing routers and applying cross-cutting middleware.
+   *
+   * @param path The path prefix to mount the handler on.
+   * @param handler The middleware function or AiAgentKit router instance to mount.
+   */
+  use(mountPathArg, handler) {
+    if (mountPathArg instanceof RegExp && handler instanceof _AiRouter) {
+      throw new AiKitError(
+        "[AiAgentKit] Mounting a router on a RegExp path is not supported."
+      );
+    }
+    if (handler instanceof _AiRouter) {
+      const router = handler;
+      const mountPath = mountPathArg.toString().replace(/\/$/, "");
+      router.stack.forEach((layer) => {
+        const layerPath = layer.path.toString();
+        const relativeLayerPath = layerPath.startsWith("/") ? layerPath.substring(1) : layerPath;
+        const newPath = path.posix.join(mountPath, relativeLayerPath);
+        this.stack.push({ ...layer, path: newPath });
+      });
+      router.actAsToolDefinitions.forEach((value, key) => {
+        const keyPath = key.toString();
+        const relativeKeyPath = keyPath.startsWith("/") ? keyPath.substring(1) : keyPath;
+        const newKey = path.posix.join(mountPath, relativeKeyPath);
+        this.actAsToolDefinitions.set(newKey, value);
+      });
+    } else {
+      this.stack.push({
+        path: mountPathArg,
+        handler,
+        isTool: false,
+        isAgent: false
+        // Middleware is not a terminal agent
+      });
+    }
+    return this;
+  }
+  /**
+   * Pre-defines the schema and description for an agent when it is used as a tool by an LLM.
+   * This allows `next.agentAsTool()` to create a valid `Tool` object without needing the definition at call time.
+   * @param path The path of the agent being defined.
+   * @param options The tool definition, including a Zod schema and description.
+   */
+  actAsTool(path2, options) {
+    this.actAsToolDefinitions.set(path2, options);
+    return this;
+  }
+  // Implementation
+  tool(path2, optionsOrFactory, handler) {
+    this.logger.log(`[AiAgentKit][tool] Registering tool at path:`, path2);
+    if (this.stack.some((l) => l.isTool && l.path === path2)) {
+      this.logger.error(
+        `[AiAgentKit][tool] Tool already registered for path: ${path2}`
+      );
+      throw new AiKitError(`A tool is already registered for path: ${path2}`);
+    }
+    if (typeof optionsOrFactory === "function" && !handler) {
+      const factory = optionsOrFactory;
+      const isDynamicPath = typeof path2 === "string" && hasDynamicParams(path2);
+      const toolMiddleware = async (ctx, _next) => {
+        this.logger.log(
+          `[Tool Middleware] Executing factory for path "${path2}". Messages in context: ${ctx.request.messages?.length ?? "undefined"}`
+        );
+        const toolObject = factory(ctx);
+        if (!toolObject.execute) {
+          throw new AiKitError(
+            `[AiAgentKit] Tool from factory at path ${path2} does not have an execute method.`
+          );
+        }
+        const schema = toolObject.inputSchema;
+        if (!schema) {
+          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(
+            `[AiAgentKit][tool] Tool call validation failed for path: ${path2}:`,
+            parsedParams.error.message
+          );
+          throw new ToolValidationError(path2.toString(), parsedParams.error);
+        }
+        return toolObject.execute(parsedParams.data, {
+          messages: convertToModelMessages(ctx.request.messages ?? []),
+          toolCallId: "tool-" + (path2.toString()?.split("/").pop() ?? "direct-call") + "-" + generateId()
+        });
+      };
+      this.stack.push({
+        path: path2,
+        handler: toolMiddleware,
+        isTool: true,
+        toolOptions: {
+          type: "factory",
+          factory
+        },
+        isAgent: false,
+        hasDynamicParams: isDynamicPath
+      });
+      this.logger.log(
+        `Tool registered: path=${path2}, type=factory${isDynamicPath ? " (dynamic)" : ""}`
+      );
+      return this;
+    }
+    if (typeof optionsOrFactory === "object" && handler) {
+      const options = optionsOrFactory;
+      const isDynamicPath = typeof path2 === "string" && hasDynamicParams(path2);
+      const dynamicParamInfo = isDynamicPath ? parsePathPattern(path2) : null;
+      const toolMiddleware = async (ctx, _next) => {
+        if (isDynamicPath && typeof path2 === "string") {
+          const pathParams = extractPathParams(path2, ctx.request.path || "");
+          this.logger.log(
+            `[AiAgentKit][tool] Extracted dynamic path params:`,
+            pathParams
+          );
+          if (pathParams) {
+            ctx.request.params = {
+              ...ctx.request.params,
+              ...pathParams
+            };
+          }
+        }
+        const parsedParams = options.schema.safeParse(ctx.request.params);
+        if (!parsedParams.success) {
+          this.logger.error(
+            `[AiAgentKit][tool] Tool call validation failed for path: ${path2}:`,
+            parsedParams.error.message
+          );
+          throw new ToolValidationError(path2.toString(), parsedParams.error);
+        }
+        const staticHandler = handler;
+        return staticHandler(ctx, parsedParams.data);
+      };
+      this.stack.push({
+        path: path2,
+        handler: toolMiddleware,
+        isTool: true,
+        toolOptions: {
+          type: "static",
+          schema: options.schema,
+          description: options.description,
+          handler
+        },
+        isAgent: false,
+        hasDynamicParams: isDynamicPath,
+        paramNames: dynamicParamInfo?.paramNames
+      });
+      this.logger.log(
+        `Tool registered: path=${path2}, type=static${isDynamicPath ? " (dynamic)" : ""}`
+      );
+      return this;
+    }
+    this.logger.error(
+      `[AiAgentKit][tool] Invalid arguments for tool registration at path: ${path2}`
+    );
+    throw new AiKitError(
+      `Invalid arguments for tool registration at path: ${path2}`
+    );
+  }
+  /**
+   * Returns the internal stack of layers. Primarily used for manual router composition.
+   * @deprecated Prefer using `.use()` for router composition.
+   */
+  getStack() {
+    return this.stack;
+  }
+  /**
+   * Returns the internal stack with a path prefix applied to each layer.
+   * @param prefix The prefix to add to each path.
+   * @deprecated Prefer using `.use()` for router composition.
+   */
+  getStackWithPrefix(prefix) {
+    return this.stack.map((layer) => {
+      let newPath;
+      if (layer.path instanceof RegExp) {
+        newPath = new RegExp(prefix.replace(/\\/g, "\\\\") + layer.path.source);
+      } else {
+        const layerPathStr = layer.path.toString();
+        const relativeLayerPath = layerPathStr.startsWith("/") ? layerPathStr.substring(1) : layerPathStr;
+        newPath = path.posix.join(prefix, relativeLayerPath);
+      }
+      return {
+        ...layer,
+        path: newPath
+      };
+    });
+  }
+  /**
+   * Resolves a path based on the parent path and the requested path.
+   * - If path starts with `@/`, it's an absolute path from the root.
+   * - Otherwise, it's a relative path.
+   * @internal
+   */
+  _resolvePath(parentPath, newPath) {
+    if (newPath.startsWith("@/")) {
+      return path.posix.normalize(newPath.substring(1));
+    }
+    const joinedPath = path.posix.join(parentPath, newPath);
+    return joinedPath;
+  }
+  /**
+   * Creates a new context for an internal agent or tool call.
+   * It inherits from the parent context but gets a new logger and call depth.
+   * @internal
+   */
+  _createSubContext(parentCtx, options) {
+    const parentDepth = parentCtx.executionContext.callDepth ?? 0;
+    const newCallDepth = parentDepth + (options.type === "agent" ? 1 : 0);
+    const subContext = {
+      ...parentCtx,
+      // Deep clone state and execution context to prevent race conditions.
+      state: JSON.parse(JSON.stringify(parentCtx.state)),
+      executionContext: {
+        ...parentCtx.executionContext,
+        currentPath: options.path,
+        callDepth: newCallDepth
+      },
+      request: {
+        ...parentCtx.request,
+        messages: options.messages || parentCtx.request.messages || [],
+        params: options.params,
+        path: options.path
+        // The path to execute
+      },
+      logger: this._createLogger(
+        parentCtx.requestId,
+        options.path,
+        newCallDepth
+      ),
+      next: void 0
+      // Will be replaced right after
+    };
+    subContext.executionContext.currentPath = options.path;
+    subContext.next = new NextHandler(
+      subContext,
+      this,
+      parentCtx._onExecutionStart,
+      parentCtx._onExecutionEnd,
+      parentCtx.next
+    );
+    return subContext;
+  }
+  /**
+   * Creates a new logger instance with a structured prefix.
+   * @internal
+   */
+  _createLogger(requestId, path2, callDepth = 0) {
+    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)
+    };
+  }
+  /**
+   * Calculates a specificity score for a layer to enable Express-style routing.
+   * Higher score means more specific.
+   * - Middleware is less specific than an agent/tool.
+   * - Deeper paths are more specific.
+   * - Static segments are more specific than dynamic segments.
+   * @internal
+   */
+  _getSpecificityScore(layer) {
+    const path2 = layer.path.toString();
+    let score = 0;
+    score += path2.split("/").length * 100;
+    score -= (path2.match(/:/g) || []).length * 10;
+    if (layer.path instanceof RegExp) {
+      score -= 50;
+    }
+    if (layer.isAgent || layer.isTool) {
+      score += 1;
+    }
+    return score;
+  }
+  /**
+   * The core execution engine. It finds all matching layers for a given path
+   * and runs them in a middleware-style chain.
+   * @internal
+   */
+  async _execute(path2, ctx, isInternalCall = false) {
+    try {
+      const normalizedPath = path2.length > 1 && path2.endsWith("/") ? path2.slice(0, -1) : path2;
+      ctx.logger.log(`Executing path. isInternalCall=${isInternalCall}`);
+      const layersToRun = this.stack.filter((layer) => {
+        let shouldRun = false;
+        if (layer.path instanceof RegExp) {
+          if (isInternalCall) {
+            const exactRegex = new RegExp(`^${layer.path.source}$`);
+            shouldRun = exactRegex.test(normalizedPath);
+          } else {
+            shouldRun = layer.path.test(normalizedPath);
+          }
+        } else if (typeof layer.path === "string") {
+          const layerPath = layer.path;
+          if (layerPath === "*") {
+            return !isInternalCall;
+          }
+          const normalizedLayerPath = layerPath.length > 1 && layerPath.endsWith("/") ? layerPath.slice(0, -1) : layerPath;
+          const isExactMatch = normalizedPath === normalizedLayerPath;
+          if (isInternalCall) {
+            if (layer.isTool && layer.hasDynamicParams) {
+              shouldRun = extractPathParams(layerPath, normalizedPath) !== null;
+            } else {
+              shouldRun = isExactMatch;
+            }
+          } else {
+            if (layer.isTool) {
+              if (layer.hasDynamicParams) {
+                shouldRun = extractPathParams(layerPath, normalizedPath) !== null;
+              } else {
+                shouldRun = isExactMatch;
+              }
+            } else if (layer.isAgent) {
+              shouldRun = isExactMatch;
+            } else {
+              shouldRun = normalizedPath.startsWith(normalizedLayerPath);
+            }
+          }
+        }
+        if (shouldRun) {
+          ctx.logger.log(
+            `[AiAgentKit][_execute] Layer MATCH: path=${normalizedPath}, layer.path=${layer.path}, isTool=${layer.isTool}, isAgent=${layer.isAgent}, isInternal=${isInternalCall}`
+          );
+        }
+        return shouldRun;
+      });
+      layersToRun.sort(
+        (a, b) => this._getSpecificityScore(a) - this._getSpecificityScore(b)
+      );
+      const layerDescriptions = layersToRun.map(
+        (l) => `${l.path.toString()} (${l.isTool ? "tool" : l.isAgent ? "agent" : "middleware"})`
+      );
+      ctx.logger.log(
+        `Found ${layersToRun.length} layers to run: [${layerDescriptions.join(
+          ", "
+        )}]`
+      );
+      const hasTool = layersToRun.some((l) => l.isTool);
+      const hasAgent = layersToRun.some((l) => l.isAgent);
+      if (!layersToRun.length) {
+        const errorMsg = `No agent or tool found for path: ${normalizedPath}`;
+        ctx.logger.error(errorMsg);
+        throw new AgentNotFoundError(normalizedPath);
+      }
+      const dispatch = async (index) => {
+        const layer = layersToRun[index];
+        if (!layer) {
+          return;
+        }
+        const next = () => dispatch(index + 1);
+        const layerPath = typeof layer.path === "string" ? layer.path : layer.path.toString();
+        const layerType = layer.isTool ? "tool" : layer.isAgent ? "agent" : "middleware";
+        ctx.logger.log(`-> Running ${layerType}: ${layerPath}`);
+        try {
+          if (ctx._onExecutionStart) {
+            ctx._onExecutionStart();
+          }
+          await layer.handler(ctx, next);
+          ctx.logger.log(`<- Finished ${layerType}: ${layerPath}`);
+        } catch (err) {
+          ctx.logger.error(
+            `Error in ${layerType} layer for path: ${layerPath}`,
+            err
+          );
+          throw err;
+        } finally {
+          if (ctx._onExecutionEnd) {
+            ctx._onExecutionEnd();
+          }
+        }
+      };
+      await dispatch(0);
+      return;
+    } finally {
+    }
+  }
+  /**
+   * The main public entry point for the router. It handles an incoming request,
+   * sets up the response stream, creates the root context, and starts the execution chain.
+   *
+   * @param path The path of the agent or tool to execute.
+   * @param initialContext The initial context for the request, typically containing messages.
+   * @returns A standard `Response` object containing the rich UI stream.
+   */
+  handle(path2, initialContext) {
+    this.logger.log(`Handling request for path: ${path2}`);
+    const self = this;
+    let executionCompletionResolver = null;
+    const executionCompletionPromise = new Promise((resolve) => {
+      executionCompletionResolver = resolve;
+    });
+    return createUIMessageStreamResponse({
+      stream: createUIMessageStream({
+        originalMessages: initialContext.request.messages,
+        execute: async ({ writer }) => {
+          const streamWriter = new StreamWriter(writer);
+          const requestId = 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: {
+              ...writer,
+              writeMessageMetadata: streamWriter.writeMessageMetadata,
+              writeCustomTool: streamWriter.writeCustomTool,
+              writeObjectAsTool: streamWriter.writeObjectAsTool,
+              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.`
+                );
+                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.`
+          );
+        }
+      })
+    });
+  }
+};
+var NextHandler = class {
+  constructor(ctx, router, onExecutionStart, onExecutionEnd, parentNext) {
+    this.ctx = ctx;
+    this.router = router;
+    this.onExecutionStart = onExecutionStart;
+    this.onExecutionEnd = onExecutionEnd;
+    this.maxCallDepth = this.router.options.maxCallDepth;
+  }
+  async callAgent(agentPath, params, options) {
+    this.onExecutionStart();
+    try {
+      const currentDepth = this.ctx.executionContext.callDepth ?? 0;
+      if (currentDepth >= this.maxCallDepth) {
+        const err = new MaxCallDepthExceededError(this.maxCallDepth);
+        this.ctx.logger.error(`[callAgent] Aborting. ${err.message}`);
+        throw err;
+      }
+      const parentPath = this.ctx.executionContext.currentPath || "/";
+      const resolvedPath = this.router._resolvePath(
+        parentPath,
+        agentPath
+      );
+      this.ctx.logger.log(`Calling agent: resolvedPath='${resolvedPath}'`);
+      const subContext = this.router._createSubContext(this.ctx, {
+        type: "agent",
+        path: resolvedPath,
+        params,
+        messages: this.ctx.request.messages
+      });
+      const data = await this.router._execute(
+        resolvedPath,
+        subContext,
+        true
+      );
+      return { ok: true, data };
+    } catch (error) {
+      this.ctx.logger.error(`[callAgent] Error:`, error);
+      return { ok: false, error };
+    } finally {
+      this.onExecutionEnd();
+    }
+  }
+  async callTool(toolPath, params, options) {
+    this.onExecutionStart();
+    try {
+      const parentPath = this.ctx.executionContext.currentPath || "/";
+      const resolvedPath = this.router._resolvePath(
+        parentPath,
+        toolPath
+      );
+      this.ctx.logger.log(`Calling tool: resolvedPath='${resolvedPath}'`);
+      const subContext = this.router._createSubContext(this.ctx, {
+        type: "tool",
+        path: resolvedPath,
+        params,
+        messages: this.ctx.request.messages
+      });
+      const data = await this.router._execute(
+        resolvedPath,
+        subContext,
+        true
+      );
+      return { ok: true, data };
+    } catch (error) {
+      this.ctx.logger.error(`[callTool] Error:`, error);
+      return { ok: false, error };
+    } finally {
+      this.onExecutionEnd();
+    }
+  }
+  attachTool(toolPath, _tool) {
+    const parentPath = this.ctx.executionContext.currentPath || "/";
+    const resolvedPath = this.router._resolvePath(
+      parentPath,
+      toolPath
+    );
+    this.ctx.logger.log(`Attaching tool: resolvedPath='${resolvedPath}'`);
+    const layer = this.router.stack.find((l) => {
+      if (!l.isTool) return false;
+      if (l.path === resolvedPath) return true;
+      if (l.hasDynamicParams && typeof l.path === "string") {
+        return extractPathParams(l.path, resolvedPath) !== null;
+      }
+      return false;
+    });
+    if (!layer || !layer.toolOptions) {
+      this.ctx.logger.error(
+        `[attachTool] Tool not found at resolved path: ${resolvedPath}`
+      );
+      throw new ToolNotFoundError(resolvedPath);
+    }
+    if (layer.toolOptions.type === "factory") {
+      return layer.toolOptions.factory(this.ctx);
+    }
+    const { description, schema } = layer.toolOptions;
+    return {
+      description,
+      inputSchema: schema,
+      ..._tool ?? {},
+      execute: async (params, options) => {
+        if (_tool?.execute) {
+          return await _tool.execute?.(params, options);
+        }
+        const result = await this.callTool(toolPath, params, options);
+        if (!result.ok) {
+          throw result.error;
+        }
+        return result.data;
+      }
+    };
+  }
+  agentAsTool(agentPath, toolDefinition) {
+    const parentPath = this.ctx.executionContext.currentPath || "/";
+    const resolvedPath = this.router._resolvePath(
+      parentPath,
+      agentPath
+    );
+    this.ctx.logger.log(
+      `Wrapping agent as tool: resolvedPath='${resolvedPath}'`
+    );
+    let preDefined;
+    for (const [key, value] of this.router.actAsToolDefinitions) {
+      if (typeof key === "string" && extractPathParams(key, resolvedPath) !== null) {
+        preDefined = value;
+        break;
+      }
+      if (key instanceof RegExp && key.test(resolvedPath)) {
+        preDefined = value;
+        break;
+      }
+    }
+    const definition = toolDefinition || preDefined;
+    if (!definition) {
+      this.ctx.logger.error(
+        `[agentAsTool] No definition found for agent at resolved path: ${resolvedPath}`
+      );
+      throw new AgentDefinitionMissingError(resolvedPath);
+    }
+    return {
+      ...definition,
+      execute: async (params, options) => {
+        const result = await this.callAgent(agentPath, params, options);
+        if (!result.ok) {
+          throw result.error;
+        }
+        return result.data;
+      }
+    };
+  }
+};
+export {
+  AgentDefinitionMissingError,
+  AgentNotFoundError,
+  AiKitError,
+  AiRouter,
+  MaxCallDepthExceededError,
+  StreamWriter,
+  ToolNotFoundError,
+  ToolValidationError,
+  findFirstElement,
+  findLastElement,
+  findLastMessageWith,
+  getTextParts,
+  getTextPartsContent
+};
+//# sourceMappingURL=index.mjs.map