@microfox/ai-router 2.0.0 → 2.0.1-beta.2

package/dist/index.d.mts

@@ -1,448 +0,0 @@
-import * as ai from 'ai';
-import { UIMessageStreamWriter, UIMessage, GenerateObjectResult, UIDataTypes, generateId, ToolSet, JSONValue, Tool, ToolCallOptions } from 'ai';
-import { z, ZodObject } from 'zod';
-import { S as Store } from './store-BBHh-uTh.mjs';
-export { M as MemoryStore } from './store-BBHh-uTh.mjs';
-
-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> {
-    writer: UIMessageStreamWriter<UIMessage<METADATA, any, TOOLS>>;
-    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;
-    }) => void;
-    writeObjectAsTool: <K extends keyof TOOLS>(tool: {
-        toolName: K;
-        result?: GenerateObjectResult<TOOLS[K]["output"]>;
-        input?: GenerateObjectResult<TOOLS[K]["input"]>;
-    }) => 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, ai.UITools> | null | undefined;
-
-/**
- * Sets a global logger that will be used by all router instances when no instance-specific logger is set.
- * This is useful for debugging across multiple router instances.
- * @param logger The logger to use globally, or undefined to disable global logging
- */
-declare function setGlobalLogger(logger?: AiLogger): void;
-/**
- * Gets the current global logger.
- * @returns The current global logger or undefined if none is set
- */
-declare function getGlobalLogger(): AiLogger | undefined;
-declare class AiKitError extends Error {
-    constructor(message: string);
-}
-declare class AgentNotFoundError extends AiKitError {
-    constructor(path: string);
-}
-/**
- * @deprecated This error class is deprecated and will be removed in a future version.
- * Use agent-as-tools pattern instead.
- */
-declare class ToolNotFoundError extends AiKitError {
-    constructor(path: string);
-}
-/**
- * @deprecated This error class is deprecated and will be removed in a future version.
- * Use agent-as-tools pattern instead.
- */
-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 = unknown, 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 extends Record<string, any> = Record<string, any>, ContextState extends Record<string, any> = Record<string, any>, PARAMS extends Record<string, any> = Record<string, any>, PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools> = {
-    request: {
-        /** The message history for the current request. */
-        messages: UIMessage<METADATA, PARTS, TOOLS>[];
-        /** Parameters passed from an internal tool or agent call. */
-        params: PARAMS;
-        [key: string]: any;
-    } & METADATA;
-    /** A shared, mutable state object that persists for the lifetime of a single request. */
-    state: ContextState;
-    /** A shared, mutable store object that persists for the lifetime of a single request. */
-    store: Store;
-    /**
-     * 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<Partial<METADATA>, PARTS, TOOLS>;
-    /**
-     * Provides functions for an agent to dispatch calls to other agents or tools.
-     * @internal
-     */
-    next: NextHandler<METADATA, ContextState, PARAMS, PARTS, TOOLS>;
-    _onExecutionStart?: () => void;
-    _onExecutionEnd?: () => void;
-};
-/** Represents the `next` function in a middleware chain, used to pass control to the next handler. */
-type NextFunction = () => Promise<any>;
-/** A function that handles a request for a specific agent path. */
-type AiHandler<METADATA extends Record<string, any> = Record<string, any>, ContextState extends Record<string, any> = Record<string, any>, PARAMS extends Record<string, any> = Record<string, any>, PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools> = (ctx: AiContext<METADATA, ContextState, PARAMS, PARTS, TOOLS>) => Promise<any>;
-/**
- * @deprecated Use agent-as-tools pattern instead. This type will be removed in a future version.
- * Create agents and use `.actAsTool()` to expose them as tools.
- */
-type AiToolHandler<METADATA extends Record<string, any> = Record<string, any>, ContextState extends Record<string, any> = Record<string, any>, PARAMS extends Record<string, any> = Record<string, any>, PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools> = ((ctx: AiContext<METADATA, ContextState, PARAMS, PARTS, TOOLS>, params: PARAMS) => Promise<any>) | ((ctx: AiContext<METADATA, ContextState, PARAMS, PARTS, TOOLS>) => Tool<any, any>);
-/**
- * @deprecated Use agent-as-tools pattern instead. This type will be removed in a future version.
- * Create agents and use `.actAsTool()` to expose them as tools.
- */
-type AiToolFactory<METADATA extends Record<string, any> = Record<string, any>, ContextState extends Record<string, any> = Record<string, any>, PARAMS extends Record<string, any> = Record<string, any>, PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools> = (ctx: AiContext<METADATA, ContextState, PARAMS, PARTS, TOOLS>) => Tool<any, any>;
-/** A function that acts as middleware, processing a request and optionally passing control to the next handler. */
-type AiMiddleware<METADATA extends Record<string, any> = Record<string, any>, ContextState extends Record<string, any> = Record<string, any>, PARAMS extends Record<string, any> = Record<string, any>, PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools> = (ctx: AiContext<METADATA, ContextState, PARAMS, PARTS, TOOLS>, next: NextFunction) => Promise<any>;
-/** 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 extends Record<string, any> = Record<string, any>, ContextState extends Record<string, any> = Record<string, any>, PARAMS extends Record<string, any> = Record<string, any>, PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools> = {
-    path: string | RegExp;
-    handler: AiMiddleware<METADATA, ContextState, PARAMS, PARTS, TOOLS>;
-    isTool: boolean;
-    toolOptions?: {
-        type: 'static';
-        schema: ZodObject<any>;
-        description?: string;
-        handler: AiToolHandler<METADATA, ContextState, PARAMS, PARTS, TOOLS>;
-    } | {
-        type: 'factory';
-        factory: AiToolFactory<METADATA, ContextState, PARAMS, PARTS, TOOLS>;
-    };
-    isAgent: boolean;
-    hasDynamicParams?: boolean;
-    paramNames?: string[];
-};
-type AgentTool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any> = Tool<INPUT, OUTPUT> & {
-    name: string;
-    id: string;
-    metadata?: Record<string, any> & {
-        absolutePath?: string;
-        name?: string;
-        description?: string;
-        toolKey?: string;
-        icon?: string;
-        parentTitle?: string;
-        title?: string;
-        hideUI?: boolean;
-    };
-};
-type AgentData = {
-    metadata?: Record<string, any> & {
-        absolutePath?: string;
-        name?: string;
-        description?: string;
-        toolKey?: string;
-        icon?: string;
-        parentTitle?: string;
-        title?: string;
-        hideUI?: boolean;
-    };
-    [key: string]: any;
-};
-/**
- * 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 extends Record<string, any> = Record<string, any>, ContextState extends Record<string, any> = {}, PARAMS extends Record<string, any> = Record<string, any>, PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools, REGISTERED_TOOLS extends ToolSet = {}> {
-    private stack;
-    actAsToolDefinitions: Map<string | RegExp, AgentTool<any, any>>;
-    private logger?;
-    private _store;
-    toolExecutionPromise: Promise<any>;
-    /** 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, ContextState, PARAMS, PARTS, TOOLS>[], options?: {
-        maxCallDepth?: number;
-        logger?: AiLogger;
-    });
-    setStore(store: Store): void;
-    /**
-     * 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?: AiLogger): void;
-    /**
-     * 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
-     */
-    private _getEffectiveLogger;
-    /**
-     * 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<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.
-     *
-     * @param path The path prefix to mount the handler on.
-     * @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 : {})>;
-    /**
-     * 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<const TPath extends string | RegExp, const TTool extends AgentTool<any, any>>(path: TPath, options: TTool): AiRouter<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS, REGISTERED_TOOLS & {
-        [K in TTool['id']]: Tool<z.infer<TTool['inputSchema']>, z.infer<TTool['outputSchema']>> & {
-            metadata: TTool['metadata'] & {
-                toolKey: TTool['id'];
-                name: TTool['name'];
-                description: TTool['description'];
-            };
-        };
-    }>;
-    getToolSet(): REGISTERED_TOOLS;
-    getToolDefinition(path: string): AgentTool<any, any>;
-    /**
-     * @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.
-     *
-     * Example migration:
-     * ```typescript
-     * // Old way (deprecated):
-     * router.tool('/calculator', { schema: z.object({...}) }, async (ctx, params) => {...});
-     *
-     * // New way (recommended):
-     * router.agent('/calculator', async (ctx) => {...})
-     *   .actAsTool('/calculator', { id: 'calculator', name: 'Calculator', ... });
-     * ```
-     */
-    tool<TOOL_METADATA extends Record<string, any> = Record<string, any>, TOOL_TOOLS extends UITools = UITools, TOOL_STATE extends Record<string, any> = 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>;
-    /**
-     * @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.
-     */
-    tool<TOOL_METADATA extends Record<string, any> = Record<string, any>, TOOL_TOOLS extends UITools = UITools, TOOL_STATE extends Record<string, any> = Record<string, any>, TOOL_PARAMS extends ZodObject<any> = ZodObject<any>>(path: string | RegExp, options: {
-        schema: TOOL_PARAMS;
-        description?: string;
-    }, handler: (ctx: AiContext<TOOL_METADATA, ContextState & TOOL_STATE, z.infer<TOOL_PARAMS>, PARTS, TOOL_TOOLS>, 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, ContextState, PARAMS, PARTS, TOOLS>[];
-    /**
-     * 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, ContextState, PARAMS, PARTS, TOOLS>;
-        isTool: boolean;
-        toolOptions?: {
-            type: "static";
-            schema: ZodObject<any>;
-            description?: string;
-            handler: AiToolHandler<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS>;
-        } | {
-            type: "factory";
-            factory: AiToolFactory<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS>;
-        } | undefined;
-        isAgent: boolean;
-        hasDynamicParams?: boolean;
-        paramNames?: string[];
-    }[];
-    /**
-     * 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(): {
-        map: Record<string, {
-            middlewares: any[];
-            tools: any[];
-            agents: any[];
-        }>;
-        tools: REGISTERED_TOOLS;
-    };
-    /**
-     * 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, ContextState, PARAMS, PARTS, TOOLS>, 'state' | 'response' | 'next' | 'requestId' | 'logger' | 'executionContext' | 'store'>): Response;
-    handleStream(path: string, initialContext: Omit<AiContext<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS>, 'state' | 'response' | 'next' | 'requestId' | 'logger' | 'executionContext' | 'store'>, executionCompletionPromise: Promise<void>, executionCompletionResolver: (() => void) | null): ReadableStream<ai.InferUIMessageChunk<UIMessage<KIT_METADATA, PARTS, TOOLS>>>;
-    /**
-     * 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.
-     */
-    toAwaitResponse(path: string, initialContext: Omit<AiContext<KIT_METADATA, ContextState, PARAMS, PARTS, TOOLS>, 'state' | 'response' | 'next' | 'requestId' | 'logger' | 'executionContext' | 'store'>): Promise<Response>;
-}
-type AiRouterType = typeof AiRouter;
-declare class NextHandler<METADATA extends Record<string, any> = Record<string, any>, ContextState extends Record<string, any> = Record<string, any>, PARAMS extends Record<string, any> = Record<string, any>, PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools> {
-    private ctx;
-    private router;
-    private onExecutionStart;
-    private onExecutionEnd;
-    maxCallDepth: number;
-    constructor(ctx: AiContext<METADATA, ContextState, PARAMS, PARTS, TOOLS>, router: AiRouter<METADATA, ContextState, PARAMS, PARTS, TOOLS>, onExecutionStart: () => void, onExecutionEnd: () => void, parentNext?: NextHandler<METADATA, ContextState, PARAMS, PARTS, TOOLS>);
-    callAgent(agentPath: string, params?: Record<string, any>, options?: {
-        streamToUI?: boolean;
-    }): Promise<{
-        ok: true;
-        data: any;
-    } | {
-        ok: false;
-        error: Error;
-    }>;
-    /**
-     * @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 });
-     * ```
-     */
-    callTool<T extends z.ZodObject<any>>(toolPath: string, params: z.infer<T>, options?: ToolCallOptions): Promise<{
-        ok: true;
-        data: any;
-    } | {
-        ok: false;
-        error: Error;
-    }>;
-    /**
-     * @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<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?: AgentTool<INPUT, OUTPUT>): {
-        [x: number]: Tool<INPUT, OUTPUT>;
-    };
-    getToolDefinition(agentPath: string | RegExp): AgentTool<any, any>;
-}
-
-export { type AgentData, AgentDefinitionMissingError, AgentNotFoundError, type AgentTool, type AiContext, type AiHandler, AiKitError, type AiLogger, type AiMiddleware, AiRouter, type AiRouterType, type AiStreamWriter, type AiToolFactory, type AiToolHandler, MaxCallDepthExceededError, type NextFunction, Store, StreamWriter, ToolNotFoundError, ToolValidationError, type UITools, findFirstElement, findLastElement, findLastMessageWith, getGlobalLogger, getTextParts, getTextPartsContent, setGlobalLogger };