@microfox/ai-router 1.0.1

package/dist/index.d.ts

@@ -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 };