@microfox/ai-router 2.1.1 → 2.1.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @microfox/ai-router
 
+## 2.1.2
+
+### Patch Changes
+
+- 56b7b6e: Changes from PR #36: middlewar-changes-before-after
+
 ## 2.1.1
 
 ### Patch Changes

package/dist/index.d.mts

@@ -130,6 +130,7 @@ type Layer<METADATA extends Record<string, any> = Record<string, any>, ContextSt
     path: string | RegExp;
     handler: AiMiddleware<METADATA, ContextState, PARAMS, PARTS, TOOLS>;
     isAgent: boolean;
+    timing?: 'before' | 'after';
     hasDynamicParams?: boolean;
     paramNames?: string[];
 };
@@ -212,13 +213,21 @@ declare class AiRouter<KIT_METADATA extends Record<string, any> = Record<string,
      */
     agent<const TAgents extends (AiMiddleware<any, any, any, any, any> | AiRouter<any, any, any, any, any, any>)[]>(agentPath: string | RegExp | AiMiddleware<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS>, ...agents: TAgents): AiRouter<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS, REGISTERED_TOOLS & (TAgents[number] extends AiRouter<any, any, any, any, any, infer R> ? R : {})>;
     /**
-     * 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.
+     * Registers middleware that runs BEFORE agent execution for a specific path prefix, regex pattern, or wildcard.
+     * The middleware can modify the context and must call `next()` to pass control to the next handler.
      *
-     * @param path The path prefix to mount the handler on.
+     * @param mountPathArg The path prefix, regex pattern, or "*" for wildcard matching.
      * @param handler The middleware function or AiAgentKit router instance to mount.
      */
-    use<THandler extends AiMiddleware<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS> | AiRouter<any, any, any, any, any, any>>(mountPathArg: string | RegExp, handler: THandler): AiRouter<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS, REGISTERED_TOOLS & (THandler extends AiRouter<any, any, any, any, any, infer R> ? R : {})>;
+    before<THandler extends AiMiddleware<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS> | AiRouter<any, any, any, any, any, any>>(mountPathArg: string | RegExp, handler: THandler): AiRouter<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS, REGISTERED_TOOLS & (THandler extends AiRouter<any, any, any, any, any, infer R> ? R : {})>;
+    /**
+     * Registers middleware that runs AFTER agent execution for a specific path prefix, regex pattern, or wildcard.
+     * The middleware can modify the context and must call `next()` to pass control to the next handler.
+     *
+     * @param mountPathArg The path prefix, regex pattern, or "*" for wildcard matching.
+     * @param handler The middleware function or AiAgentKit router instance to mount.
+     */
+    after<THandler extends AiMiddleware<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS> | AiRouter<any, any, any, any, any, any>>(mountPathArg: string | RegExp, handler: THandler): AiRouter<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS, REGISTERED_TOOLS & (THandler extends AiRouter<any, any, any, any, any, infer R> ? R : {})>;
     /**
      * 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.
@@ -242,8 +251,9 @@ declare class AiRouter<KIT_METADATA extends Record<string, any> = Record<string,
      */
     registry(): {
         map: Record<string, {
-            middlewares: any[];
+            before: any[];
             agents: any[];
+            after: any[];
         }>;
         tools: REGISTERED_TOOLS;
     };

package/dist/index.d.ts

@@ -130,6 +130,7 @@ type Layer<METADATA extends Record<string, any> = Record<string, any>, ContextSt
     path: string | RegExp;
     handler: AiMiddleware<METADATA, ContextState, PARAMS, PARTS, TOOLS>;
     isAgent: boolean;
+    timing?: 'before' | 'after';
     hasDynamicParams?: boolean;
     paramNames?: string[];
 };
@@ -212,13 +213,21 @@ declare class AiRouter<KIT_METADATA extends Record<string, any> = Record<string,
      */
     agent<const TAgents extends (AiMiddleware<any, any, any, any, any> | AiRouter<any, any, any, any, any, any>)[]>(agentPath: string | RegExp | AiMiddleware<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS>, ...agents: TAgents): AiRouter<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS, REGISTERED_TOOLS & (TAgents[number] extends AiRouter<any, any, any, any, any, infer R> ? R : {})>;
     /**
-     * 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.
+     * Registers middleware that runs BEFORE agent execution for a specific path prefix, regex pattern, or wildcard.
+     * The middleware can modify the context and must call `next()` to pass control to the next handler.
      *
-     * @param path The path prefix to mount the handler on.
+     * @param mountPathArg The path prefix, regex pattern, or "*" for wildcard matching.
      * @param handler The middleware function or AiAgentKit router instance to mount.
      */
-    use<THandler extends AiMiddleware<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS> | AiRouter<any, any, any, any, any, any>>(mountPathArg: string | RegExp, handler: THandler): AiRouter<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS, REGISTERED_TOOLS & (THandler extends AiRouter<any, any, any, any, any, infer R> ? R : {})>;
+    before<THandler extends AiMiddleware<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS> | AiRouter<any, any, any, any, any, any>>(mountPathArg: string | RegExp, handler: THandler): AiRouter<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS, REGISTERED_TOOLS & (THandler extends AiRouter<any, any, any, any, any, infer R> ? R : {})>;
+    /**
+     * Registers middleware that runs AFTER agent execution for a specific path prefix, regex pattern, or wildcard.
+     * The middleware can modify the context and must call `next()` to pass control to the next handler.
+     *
+     * @param mountPathArg The path prefix, regex pattern, or "*" for wildcard matching.
+     * @param handler The middleware function or AiAgentKit router instance to mount.
+     */
+    after<THandler extends AiMiddleware<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS> | AiRouter<any, any, any, any, any, any>>(mountPathArg: string | RegExp, handler: THandler): AiRouter<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS, REGISTERED_TOOLS & (THandler extends AiRouter<any, any, any, any, any, infer R> ? R : {})>;
     /**
      * 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.
@@ -242,8 +251,9 @@ declare class AiRouter<KIT_METADATA extends Record<string, any> = Record<string,
      */
     registry(): {
         map: Record<string, {
-            middlewares: any[];
+            before: any[];
             agents: any[];
+            after: any[];
         }>;
         tools: REGISTERED_TOOLS;
     };

package/dist/index.js

@@ -389,7 +389,20 @@ var AiRouter = class _AiRouter {
     for (const handler of agents) {
       if (typeof handler !== "function") {
         if (handler instanceof _AiRouter && typeof prefix === "string") {
-          this.use(prefix, handler);
+          const router = handler;
+          const mountPath = prefix.toString().replace(/\/$/, "");
+          router.stack.forEach((layer) => {
+            const layerPath = layer.path.toString();
+            const relativeLayerPath = layerPath.startsWith("/") ? layerPath.substring(1) : layerPath;
+            const newPath = import_path.default.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 = import_path.default.posix.join(mountPath, relativeKeyPath);
+            this.actAsToolDefinitions.set(newKey, value);
+          });
         }
         continue;
       }
@@ -404,13 +417,13 @@ var AiRouter = class _AiRouter {
     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.
+   * Registers middleware that runs BEFORE agent execution for a specific path prefix, regex pattern, or wildcard.
+   * The middleware can modify the context and must call `next()` to pass control to the next handler.
    *
-   * @param path The path prefix to mount the handler on.
+   * @param mountPathArg The path prefix, regex pattern, or "*" for wildcard matching.
    * @param handler The middleware function or AiAgentKit router instance to mount.
    */
-  use(mountPathArg, handler) {
+  before(mountPathArg, handler) {
     if (mountPathArg instanceof RegExp && handler instanceof _AiRouter) {
       throw new AiKitError(
         "[AiAgentKit] Mounting a router on a RegExp path is not supported."
@@ -435,8 +448,50 @@ var AiRouter = class _AiRouter {
       this.stack.push({
         path: mountPathArg,
         handler,
-        isAgent: false
+        isAgent: false,
         // Middleware is not a terminal agent
+        timing: "before"
+        // Mark as before middleware
+      });
+    }
+    return this;
+  }
+  /**
+   * Registers middleware that runs AFTER agent execution for a specific path prefix, regex pattern, or wildcard.
+   * The middleware can modify the context and must call `next()` to pass control to the next handler.
+   *
+   * @param mountPathArg The path prefix, regex pattern, or "*" for wildcard matching.
+   * @param handler The middleware function or AiAgentKit router instance to mount.
+   */
+  after(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 = import_path.default.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 = import_path.default.posix.join(mountPath, relativeKeyPath);
+        this.actAsToolDefinitions.set(newKey, value);
+      });
+    } else {
+      this.stack.push({
+        path: mountPathArg,
+        handler,
+        isAgent: false,
+        // Middleware is not a terminal agent
+        timing: "after"
+        // Mark as after middleware
       });
     }
     return this;
@@ -502,7 +557,7 @@ var AiRouter = class _AiRouter {
     for (const layer of this.stack) {
       const pathKey = layer.path.toString();
       if (!registryMap[pathKey]) {
-        registryMap[pathKey] = { middlewares: [], agents: [] };
+        registryMap[pathKey] = { before: [], agents: [], after: [] };
       }
       if (layer.isAgent) {
         const agentInfo = {
@@ -516,9 +571,17 @@ var AiRouter = class _AiRouter {
         }
         registryMap[pathKey].agents.push(agentInfo);
       } else {
-        registryMap[pathKey].middlewares.push({
-          handler: layer.handler.name || "anonymous"
-        });
+        const middlewareInfo = {
+          handler: layer.handler.name || "anonymous",
+          timing: layer.timing || "middleware"
+        };
+        if (layer.timing === "before") {
+          registryMap[pathKey].before.push(middlewareInfo);
+        } else if (layer.timing === "after") {
+          registryMap[pathKey].after.push(middlewareInfo);
+        } else {
+          registryMap[pathKey].before.push(middlewareInfo);
+        }
       }
     }
     return {
@@ -671,31 +734,45 @@ var AiRouter = class _AiRouter {
         }
         return shouldRun;
       });
-      layersToRun.sort(
+      const beforeLayers = layersToRun.filter(
+        (l) => !l.isAgent && l.timing === "before"
+      );
+      const agentLayers = layersToRun.filter((l) => l.isAgent);
+      const afterLayers = layersToRun.filter(
+        (l) => !l.isAgent && l.timing === "after"
+      );
+      beforeLayers.sort(
         (a, b) => this._getSpecificityScore(a) - this._getSpecificityScore(b)
       );
-      const layerDescriptions = layersToRun.map(
-        (l) => `${l.path.toString()} (${l.isAgent ? "agent" : "middleware"})`
+      agentLayers.sort(
+        (a, b) => this._getSpecificityScore(a) - this._getSpecificityScore(b)
       );
+      afterLayers.sort(
+        (a, b) => this._getSpecificityScore(a) - this._getSpecificityScore(b)
+      );
+      const orderedLayers = [...beforeLayers, ...agentLayers, ...afterLayers];
+      const layerDescriptions = orderedLayers.map((l) => {
+        const type = l.isAgent ? "agent" : l.timing === "before" ? "before" : l.timing === "after" ? "after" : "middleware";
+        return `${l.path.toString()} (${type})`;
+      });
       ctx.logger.log(
-        `Found ${layersToRun.length} layers to run: [${layerDescriptions.join(
+        `Found ${orderedLayers.length} layers to run: [${layerDescriptions.join(
           ", "
         )}]`
       );
-      const hasAgent = layersToRun.some((l) => l.isAgent);
-      if (!layersToRun.length) {
+      if (!agentLayers.length && !beforeLayers.length && !afterLayers.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];
+        const layer = orderedLayers[index];
         if (!layer) {
           return;
         }
         const next = () => dispatch(index + 1);
         const layerPath = typeof layer.path === "string" ? layer.path : layer.path.toString();
-        const layerType = layer.isAgent ? "agent" : "middleware";
+        const layerType = layer.isAgent ? "agent" : layer.timing === "before" ? "before" : layer.timing === "after" ? "after" : "middleware";
         ctx.logger.log(`-> Running ${layerType}: ${layerPath}`);
         try {
           if (ctx._onExecutionStart) {