@microfox/ai-router 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 1.0.1
+
+### Patch Changes
+
+- de2e3cc: Changes from PR #559: suno
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2025-07-02
+
+### Added
+
+- Initial release
+- Basic SDK structure
+- TypeScript support
+
+<!-- Add your changes here using this format:
+
+## [1.1.0] - YYYY-MM-DD
+
+### Added
+- New feature
+
+### Changed
+- Updated feature
+
+### Fixed
+- Bug fix
+
+### Removed
+- Deprecated feature
+-->

package/README.md

@@ -0,0 +1,227 @@
+# AiRouter: An Agentic Application Framework
+
+`AiRouter` is a lightweight, powerful framework for building complex, multi-agent applications in TypeScript. Inspired by web frameworks like Express or Fastify, it provides a robust routing system for creating, composing, and calling AI agents and tools in a structured and predictable way.
+
+Stop thinking in single-shot API calls and start building hierarchies of agents that can call each other, use tools, and stream responses back to the user from any point in the chain.
+
+## Quick Start: Your First Agent
+
+See how easy it is to get started. In just a few lines of code, you can create a router, define an agent, and handle a request.
+
+```typescript
+import { AiRouter } from './router';
+
+// 1. Create a new agent router
+const app = new AiRouter();
+
+// 2. Define an agent that streams a response
+app.agent('/hello', async (ctx) => {
+  ctx.response.write({ type: 'text', text: 'Hello, ' });
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  ctx.response.write({ type: 'text', text: 'world!' });
+});
+
+// 3. Handle an incoming request and get a standard Response object
+const request = new Request('http://localhost/hello');
+const response = app.handle(new URL(request.url).pathname, { request });
+
+// You can now return this response from your API endpoint.
+```
+
+---
+
+## Core Concepts
+
+- **`AiRouter`**: The main class, which acts as a router. You create an instance of this to register all your agents, tools, and middleware.
+- **Agents**: The primary actors in the system. An agent is a function that receives a `context` (`ctx`) object and can perform actions, such as streaming text, calling other agents, using tools, or modifying state.
+- **Tools**: Schema-defined functions that an agent can call. Tools are typically used for deterministic operations or for interacting with external APIs. They receive the `context` and a parsed, schema-validated input object.
+- **The Context (`ctx`)**: A per-request object that is passed to every handler. It contains everything needed for an agent to do its work:
+  - `ctx.response`: The stream writer to send data back to the end-user.
+  - `ctx.next`: An object with methods for internal dispatching (`callAgent`, `callTool`, etc.).
+  - `ctx.state`: A mutable object that lives for the duration of a single request, allowing agents and middleware to share data.
+  - `ctx.logger`: A structured logger that automatically includes a unique `requestId` and the current agent `path` for easy debugging.
+  - `ctx.request`: The initial request object.
+- **Hierarchical Routing**: Just like in web frameworks, you can mount entire `AiRouter` instances on a path, allowing you to build modular and reusable collections of agents.
+
+---
+
+## Installation
+
+```bash
+# This package is internal to the project for now.
+# To use it, import it directly from your local path.
+import { AiRouter } from "../packages/ai-utils/src/router";
+```
+
+---
+
+## Step-by-Step Documentation
+
+### 1. Initialization
+
+Create a new `AiRouter` router. You can create as many as you need to organize your application.
+
+```typescript
+const app = new AiRouter();
+```
+
+### 2. Defining an Agent
+
+Use the `.agent()` method to define a handler for a specific path. The handler is an async function that receives the `ctx` object.
+
+```typescript
+app.agent('/simple', async (ctx) => {
+  ctx.response.write({ type: 'text', text: 'This is a simple agent.' });
+});
+```
+
+### 3. Defining a Tool
+
+Use the `.tool()` method to define a tool. You must provide a Zod schema for the input `parameters`, which will be automatically validated. The handler receives the `ctx` and the parsed parameters.
+
+```typescript
+import { z } from 'zod';
+
+app.tool(
+  '/getWeather',
+  {
+    description: 'Gets the weather for a given location.',
+    schema: z.object({
+      city: z.string().describe('The city to get the weather for.'),
+    }),
+  },
+  async (ctx, { city }) => {
+    // In a real app, you'd call a weather API here.
+    const weather = `The weather in ${city} is 72°F and sunny.`;
+    ctx.logger.log('Weather tool executed successfully.');
+    return { weather };
+  }
+);
+```
+
+### 4. Mounting Routers with `.use()`
+
+Organize your code by creating separate routers and mounting them on a main router using `.use()`. This prefixes all routes in the mounted router.
+
+```typescript
+const adminRouter = new AiRouter();
+adminRouter.agent("/dashboard", async (ctx) => { ... });
+
+const mainApp = new AiRouter();
+// All routes from adminRouter will now be prefixed with '/admin'
+// e.g., the above agent is now available at '/admin/dashboard'
+mainApp.use("/admin", adminRouter);
+```
+
+You can also use `.use()` to register middleware, which is useful for authentication, logging, or modifying the state before an agent runs.
+
+```typescript
+app.use('*', async (ctx, next) => {
+  ctx.state.user = await getUserFromDb(ctx.request);
+  ctx.logger.log('User authenticated.');
+  await next(); // Don't forget to call next() to continue!
+});
+```
+
+---
+
+## Advanced Usage
+
+### Internal Calling & Error Handling
+
+Agents can call other agents and tools using `ctx.next`. This is the key to building complex, chained behaviors. These calls are resilient; they return a result object (`{ ok, data }` or `{ ok, error }`) instead of throwing, allowing the calling agent to handle failures gracefully.
+
+```typescript
+app.agent('/weather-reporter', async (ctx) => {
+  ctx.response.write({ type: 'text', text: 'Checking the weather...' });
+
+  const result = await ctx.next.callTool('/getWeather', {
+    city: 'San Francisco',
+  });
+
+  if (result.ok) {
+    ctx.response.write({
+      type: 'text',
+      text: `\nReport: ${result.data.weather}`,
+    });
+  } else {
+    ctx.logger.error('Failed to get weather:', result.error);
+    ctx.response.write({
+      type: 'text',
+      text: `\nSorry, I couldn't get the weather.`,
+    });
+  }
+});
+```
+
+### Agent as a Tool
+
+For an LLM to call one of your agents, it must be presented as a `Tool`. `AiRouter` makes this easy with a two-step pattern:
+
+**Step 1: Define the Tool Schema with `.actAsTool()`**
+When creating an agent, specify how it should look to an LLM.
+
+```typescript
+import { z } from 'zod';
+const casualRouter = new AiRouter();
+
+casualRouter
+  .actAsTool('/casual', {
+    description: 'A friendly, casual greeting.',
+    inputSchema: z.object({ name: z.string() }),
+  })
+  .agent('/casual', async ({ response, request }) => {
+    // The 'params' come from the LLM tool call
+    const name = (request.params as any)?.toolInfo?.params?.name || 'there';
+    response.write({ type: 'text', text: `Yo, what's up ${name}! 👋` });
+  });
+```
+
+**Step 2: Provide the Tool to the LLM with `next.agentAsTool()`**
+Inside another agent, use this method to create the final Vercel AI SDK `Tool` object.
+
+```typescript
+import { streamText } from 'ai';
+
+greetingRouter.agent('/decide', async ({ response, next }) => {
+  const { textStream } = await streamText({
+    model: openai('gpt-4-turbo'),
+    prompt: 'Should I greet Chairman Meow casually?',
+    tools: {
+      // The framework handles connecting this to the agent's implementation
+      casualChat: next.agentAsTool('/greeting/casual'),
+    },
+  });
+
+  for await (const textPart of textStream) {
+    response.write({ type: 'text', text: textPart });
+  }
+});
+```
+
+### Dynamic Tool Attachment with `next.attachTool()`
+
+Similarly, you can provide any registered `.tool()` handler to an LLM using `next.attachTool()`.
+
+```typescript
+const { textStream } = await streamText({
+  model: openai('gpt-4-turbo'),
+  prompt: '...',
+  tools: {
+    getWeather: next.attachTool('/getWeather'),
+  },
+});
+```
+
+### Logging and Debugging
+
+The built-in logger (`ctx.logger`) is your best friend for debugging. It automatically tags every log message with a unique `requestId` and the `path` of the currently executing handler. This makes it easy to trace the flow of a request, even through multiple internal calls.
+
+```
+[aK4xLp8VnI2C] [/decide] -> Running middleware
+[aK4xLp8VnI2C] [/decide] User authenticated.
+[aK4xLp8VnI2C] [/decide] -> Executing agent handler
+[aK4xLp8VnI2C] [/greeting/casual] -> Executing agent handler
+[aK4xLp8VnI2C] [/greeting/casual] <- Finished agent
+[aK4xLp8VnI2C] [/decide] <- Finished agent
+```

package/dist/index.d.mts

@@ -0,0 +1,300 @@
+import { UIMessageStreamWriter, UIMessage, GenerateObjectResult, UIDataTypes, generateId, Tool, ToolCallOptions, JSONValue } from 'ai';
+import { z, ZodObject } from 'zod';
+
+type UITools = Record<string, {
+    input: unknown;
+    output: unknown | undefined;
+}>;
+
+declare const findLastElement: <T>(array: T[]) => T;
+declare const findFirstElement: <T>(array: T[]) => T;
+declare class StreamWriter<METADATA, TOOLS extends UITools> {
+    private writer;
+    constructor(writer: UIMessageStreamWriter<UIMessage<METADATA, any, TOOLS>>);
+    generateId: () => string;
+    writeMessageMetadata: <NEW_METADATA extends METADATA>(metadata: NEW_METADATA) => void;
+    writeCustomTool: <K extends keyof TOOLS>(tool: {
+        toolCallId?: string;
+        toolName: K;
+        inputTextDelta?: string[];
+        input?: any;
+        output?: any;
+    } & Omit<TOOLS[K], "toolCallId">) => void;
+    writeObjectAsTool: <K extends keyof TOOLS>(tool: {
+        toolName: K;
+        result: GenerateObjectResult<TOOLS[K]["output"]>;
+    }) => void;
+}
+declare const getTextParts: (message: UIMessage | null | undefined) => string[];
+declare const getTextPartsContent: (message: UIMessage | null | undefined) => string;
+declare const findLastMessageWith: <T>(message: UIMessage[] | null | undefined, filters: {
+    role?: "user" | "assistant" | "system";
+    metadata?: Record<string, any>;
+}) => UIMessage<unknown, UIDataTypes, {
+    [x: string]: {
+        input: unknown;
+        output: unknown | undefined;
+    };
+}> | null | undefined;
+
+declare class AiKitError extends Error {
+    constructor(message: string);
+}
+declare class AgentNotFoundError extends AiKitError {
+    constructor(path: string);
+}
+declare class ToolNotFoundError extends AiKitError {
+    constructor(path: string);
+}
+declare class ToolValidationError extends AiKitError {
+    constructor(path: string, validationError: z.ZodError);
+}
+declare class MaxCallDepthExceededError extends AiKitError {
+    constructor(maxDepth: number);
+}
+declare class AgentDefinitionMissingError extends AiKitError {
+    constructor(path: string);
+}
+type AiStreamWriter<METADATA, PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools> = UIMessageStreamWriter<UIMessage<METADATA, PARTS, TOOLS>> & Omit<StreamWriter<METADATA, TOOLS>, 'writer'> & {
+    generateId: typeof generateId;
+};
+/**
+ * The context object passed to every agent, tool, and middleware. It contains
+ * all the necessary information and utilities for a handler to perform its work.
+ * @template METADATA - The type for custom metadata in UI messages.
+ * @template PARTS - The type for custom parts in UI messages.
+ * @template TOOLS - The type for custom tools in UI messages.
+ * @template ContextState - The type for the shared state object.
+ */
+type AiContext<METADATA, PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools, ContextState extends Record<string, any> = Record<string, any>> = {
+    request: {
+        /** The message history for the current request. */
+        messages: UIMessage<METADATA, PARTS, TOOLS>[];
+        /** Parameters passed from an internal tool or agent call. */
+        params?: Record<string, any>;
+        [key: string]: any;
+    };
+    /** A shared, mutable state object that persists for the lifetime of a single request. */
+    state: ContextState;
+    /**
+     * Internal execution context for the router. Should not be modified by user code.
+     * @internal
+     */
+    executionContext: {
+        handlerPathStack?: string[];
+        currentPath?: string;
+        callDepth?: number;
+        [key: string]: any;
+    };
+    /**
+     * A unique ID for the top-level request, useful for logging and tracing.
+     */
+    requestId: string;
+    /**
+     * A structured logger that automatically includes the `requestId` and current handler path.
+     */
+    logger: AiLogger;
+    /**
+     * The stream writer to send data back to the end-user's UI.
+     * Includes helpers for writing structured data like tool calls and metadata.
+     */
+    response: AiStreamWriter<METADATA, PARTS, TOOLS>;
+    /**
+     * Provides functions for an agent to dispatch calls to other agents or tools.
+     * @internal
+     */
+    next: NextHandler<METADATA, PARTS, TOOLS, ContextState>;
+    _onExecutionStart?: () => void;
+    _onExecutionEnd?: () => void;
+};
+/** Represents the `next` function in a middleware chain, used to pass control to the next handler. */
+type NextFunction = () => Promise<void>;
+/** A function that handles a request for a specific agent path. */
+type AiHandler<METADATA, PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools, ContextState extends Record<string, any> = Record<string, any>> = (ctx: AiContext<METADATA, PARTS, TOOLS, ContextState>) => Promise<void>;
+/** A function that handles a request for a specific tool path, with validated parameters. */
+type AiToolHandler<METADATA, PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools, ContextState extends Record<string, any> = Record<string, any>> = ((ctx: AiContext<METADATA, PARTS, TOOLS, ContextState>, params: Record<string, any>) => Promise<any>) | ((ctx: AiContext<METADATA, PARTS, TOOLS, ContextState>) => Tool<any, any>);
+/** A function that creates a Tool on-demand with access to the request context. */
+type AiToolFactory<METADATA, PARTS extends UIDataTypes, TOOLS extends UITools, ContextState extends Record<string, any>> = (ctx: AiContext<METADATA, PARTS, TOOLS, ContextState>) => Tool<any, any>;
+/** A function that acts as middleware, processing a request and optionally passing control to the next handler. */
+type AiMiddleware<METADATA, PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools, ContextState extends Record<string, any> = Record<string, any>> = (ctx: AiContext<METADATA, PARTS, TOOLS, ContextState>, next: NextFunction) => Promise<void>;
+/** A simple structured logger interface. */
+type AiLogger = {
+    log: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+};
+/** Internal representation of a registered handler in the router's stack. */
+type Layer<METADATA, PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools, ContextState extends Record<string, any> = Record<string, any>> = {
+    path: string | RegExp;
+    handler: AiMiddleware<METADATA, PARTS, TOOLS, ContextState>;
+    isTool: boolean;
+    toolOptions?: {
+        type: 'static';
+        schema: ZodObject<any>;
+        description?: string;
+        handler: AiToolHandler<METADATA, PARTS, TOOLS, ContextState>;
+    } | {
+        type: 'factory';
+        factory: AiToolFactory<METADATA, PARTS, TOOLS, ContextState>;
+    };
+    isAgent: boolean;
+    hasDynamicParams?: boolean;
+    paramNames?: string[];
+};
+/**
+ * A composable router for building structured, multi-agent AI applications.
+ * It allows you to define agents and tools, compose them together, and handle
+ * requests in a predictable, middleware-style pattern.
+ *
+ * @template KIT_METADATA - The base metadata type for all UI messages in this router.
+ * @template PARTS - The base custom parts type for all UI messages.
+ * @template TOOLS - The base custom tools type for all UI messages.
+ * @template ContextState - The base type for the shared state object.
+ */
+declare class AiRouter<KIT_METADATA, PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools, ContextState extends Record<string, any> = {}> {
+    private stack;
+    private actAsToolDefinitions;
+    private logger;
+    /** Configuration options for the router instance. */
+    options: {
+        /** The maximum number of agent-to-agent calls allowed in a single request to prevent infinite loops. */
+        maxCallDepth: number;
+    };
+    /**
+     * 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?: Layer<KIT_METADATA, PARTS, TOOLS, any>[], options?: {
+        maxCallDepth?: number;
+        logger?: AiLogger;
+    });
+    /**
+     * 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<MW_METADATA, MW_TOOLS extends UITools, MW_STATE extends Record<string, any>>(path: string | RegExp | AiMiddleware<MW_METADATA, PARTS, MW_TOOLS, ContextState & MW_STATE>, ...agents: (AiMiddleware<MW_METADATA, PARTS, MW_TOOLS, ContextState & MW_STATE> | AiRouter<MW_METADATA, PARTS, MW_TOOLS, ContextState & MW_STATE>)[]): AiRouter<KIT_METADATA | MW_METADATA, PARTS, TOOLS & MW_TOOLS, ContextState & MW_STATE>;
+    /**
+     * 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: string | RegExp, handler: AiMiddleware<KIT_METADATA, PARTS, TOOLS, ContextState> | AiRouter<any, any, any, any>): 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(path: string | RegExp, options: {
+        description?: string;
+        inputSchema: ZodObject<any>;
+    }): this;
+    tool<TOOL_METADATA, TOOL_TOOLS extends UITools, TOOL_STATE extends Record<string, any>>(path: string | RegExp, factory: AiToolFactory<TOOL_METADATA, PARTS, TOOL_TOOLS, ContextState & TOOL_STATE>): AiRouter<KIT_METADATA | TOOL_METADATA, PARTS, TOOLS & TOOL_TOOLS, ContextState & TOOL_STATE>;
+    tool<TOOL_METADATA, TOOL_TOOLS extends UITools, TOOL_STATE extends Record<string, any>, TOOL_PARAMS extends ZodObject<any>>(path: string | RegExp, options: {
+        schema: TOOL_PARAMS;
+        description?: string;
+    }, handler: (ctx: AiContext<TOOL_METADATA, PARTS, TOOL_TOOLS, ContextState & TOOL_STATE>, params: z.infer<TOOL_PARAMS>) => Promise<any>): AiRouter<KIT_METADATA | TOOL_METADATA, PARTS, TOOLS & TOOL_TOOLS, ContextState & TOOL_STATE>;
+    /**
+     * Returns the internal stack of layers. Primarily used for manual router composition.
+     * @deprecated Prefer using `.use()` for router composition.
+     */
+    getStack(): Layer<KIT_METADATA, PARTS, TOOLS, any>[];
+    /**
+     * 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: string): {
+        path: string | RegExp;
+        handler: AiMiddleware<KIT_METADATA, PARTS, TOOLS, any>;
+        isTool: boolean;
+        toolOptions?: {
+            type: "static";
+            schema: ZodObject<any>;
+            description?: string;
+            handler: AiToolHandler<KIT_METADATA, PARTS, TOOLS, any>;
+        } | {
+            type: "factory";
+            factory: AiToolFactory<KIT_METADATA, PARTS, TOOLS, any>;
+        } | undefined;
+        isAgent: boolean;
+        hasDynamicParams?: boolean;
+        paramNames?: string[];
+    }[];
+    /**
+     * 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
+     */
+    private _resolvePath;
+    /**
+     * 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
+     */
+    private _createSubContext;
+    /**
+     * Creates a new logger instance with a structured prefix.
+     * @internal
+     */
+    private _createLogger;
+    /**
+     * 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
+     */
+    private _getSpecificityScore;
+    /**
+     * The core execution engine. It finds all matching layers for a given path
+     * and runs them in a middleware-style chain.
+     * @internal
+     */
+    private _execute;
+    private pendingExecutions;
+    /**
+     * 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(path: string, initialContext: Omit<AiContext<KIT_METADATA, PARTS, TOOLS, ContextState>, 'state' | 'response' | 'next' | 'requestId' | 'logger' | 'executionContext'>): Response;
+}
+declare class NextHandler<METADATA, PARTS extends UIDataTypes, TOOLS extends UITools, ContextState extends Record<string, any>> {
+    private ctx;
+    private router;
+    private onExecutionStart;
+    private onExecutionEnd;
+    maxCallDepth: number;
+    constructor(ctx: AiContext<METADATA, PARTS, TOOLS, ContextState>, router: AiRouter<METADATA, PARTS, TOOLS, ContextState>, onExecutionStart: () => void, onExecutionEnd: () => void, parentNext?: NextHandler<METADATA, PARTS, TOOLS, ContextState>);
+    callAgent(agentPath: string, params?: Record<string, any>, options?: ToolCallOptions): Promise<{
+        ok: true;
+        data: any;
+    } | {
+        ok: false;
+        error: Error;
+    }>;
+    callTool<T extends z.ZodObject<any>>(toolPath: string, params: z.infer<T>, options?: ToolCallOptions): Promise<{
+        ok: true;
+        data: any;
+    } | {
+        ok: false;
+        error: Error;
+    }>;
+    attachTool<SCHEMA extends z.ZodObject<any>>(toolPath: string, _tool?: Omit<Tool<z.infer<SCHEMA>, any>, 'description'>): Tool<z.infer<SCHEMA>, any>;
+    agentAsTool<INPUT extends JSONValue | unknown | never = any, OUTPUT = any>(agentPath: string, toolDefinition?: Tool<INPUT, OUTPUT>): Tool<INPUT, OUTPUT>;
+}
+
+export { AgentDefinitionMissingError, AgentNotFoundError, type AiContext, type AiHandler, AiKitError, type AiLogger, type AiMiddleware, AiRouter, type AiStreamWriter, type AiToolFactory, type AiToolHandler, MaxCallDepthExceededError, type NextFunction, StreamWriter, ToolNotFoundError, ToolValidationError, type UITools, findFirstElement, findLastElement, findLastMessageWith, getTextParts, getTextPartsContent };