@meetsmore-oss/use-ai-server 1.2.1

package/dist/src/plugins/types.d.ts

@@ -0,0 +1,69 @@
+import type { ClientSession } from '../agents/types';
+import type { UseAIClientMessage } from '../types';
+/**
+ * Message handler function type for plugin-registered message handlers.
+ *
+ * @param session - The client session context
+ * @param message - The incoming message from the client
+ */
+export type MessageHandler = (session: ClientSession, message: UseAIClientMessage) => Promise<void> | void;
+/**
+ * Plugin interface for extending UseAIServer functionality.
+ *
+ * Plugins can register custom message handlers, react to client lifecycle events,
+ * and add new capabilities to the server without modifying core code.
+ *
+ * @example
+ * ```typescript
+ * class WorkflowsPlugin implements UseAIServerPlugin {
+ *   getName() {
+ *     return 'workflows';
+ *   }
+ *
+ *   registerHandlers(server) {
+ *     server.registerMessageHandler('run_workflow', async (session, message) => {
+ *       // Handle workflow execution
+ *     });
+ *   }
+ *
+ *   onClientConnect(session) {
+ *     console.log('Client connected:', session.clientId);
+ *   }
+ *
+ *   onClientDisconnect(session) {
+ *     console.log('Client disconnected:', session.clientId);
+ *   }
+ * }
+ * ```
+ */
+export interface UseAIServerPlugin {
+    /**
+     * Returns the unique identifier for this plugin.
+     * Used for logging and debugging purposes.
+     *
+     * @returns Plugin name (e.g., 'workflows', 'analytics', 'auth')
+     */
+    getName(): string;
+    /**
+     * Called when the plugin is registered with the server.
+     * Use this to register custom message handlers.
+     *
+     * @param server - Object with registerMessageHandler method
+     */
+    registerHandlers(server: {
+        registerMessageHandler(type: string, handler: MessageHandler): void;
+    }): void;
+    /**
+     * Optional lifecycle hook called when a client connects.
+     *
+     * @param session - The newly created client session
+     */
+    onClientConnect?(session: ClientSession): void;
+    /**
+     * Optional lifecycle hook called when a client disconnects.
+     *
+     * @param session - The disconnecting client session
+     */
+    onClientDisconnect?(session: ClientSession): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/plugins/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/plugins/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE3G;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,OAAO,IAAI,MAAM,CAAC;IAElB;;;;;OAKG;IACH,gBAAgB,CAAC,MAAM,EAAE;QACvB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;KACrE,GAAG,IAAI,CAAC;IAET;;;;OAIG;IACH,eAAe,CAAC,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAE/C;;;;OAIG;IACH,kBAAkB,CAAC,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;CACnD"}

package/dist/src/plugins.integration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=plugins.integration.test.d.ts.map

package/dist/src/plugins.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.integration.test.d.ts","sourceRoot":"","sources":["../../src/plugins.integration.test.ts"],"names":[],"mappings":""}

package/dist/src/rate-limiting.integration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rate-limiting.integration.test.d.ts.map

package/dist/src/rate-limiting.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiting.integration.test.d.ts","sourceRoot":"","sources":["../../src/rate-limiting.integration.test.ts"],"names":[],"mappings":""}

package/dist/src/rateLimiter.d.ts

@@ -0,0 +1,17 @@
+export interface RateLimiterConfig {
+    maxRequests: number;
+    windowMs: number;
+}
+export declare class RateLimiter {
+    private requests;
+    private config;
+    constructor(config: RateLimiterConfig);
+    isEnabled(): boolean;
+    checkLimit(ipAddress: string): {
+        allowed: boolean;
+        retryAfterMs?: number;
+    };
+    removeIpAddress(ipAddress: string): void;
+    cleanup(): void;
+}
+//# sourceMappingURL=rateLimiter.d.ts.map

package/dist/src/rateLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimiter.d.ts","sourceRoot":"","sources":["../../src/rateLimiter.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAoC;IACpD,OAAO,CAAC,MAAM,CAAoB;gBAEtB,MAAM,EAAE,iBAAiB;IAIrC,SAAS,IAAI,OAAO;IAIpB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;IAuB1E,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIxC,OAAO,IAAI,IAAI;CAchB"}

package/dist/src/rateLimiter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rateLimiter.test.d.ts.map

package/dist/src/rateLimiter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimiter.test.d.ts","sourceRoot":"","sources":["../../src/rateLimiter.test.ts"],"names":[],"mappings":""}

package/dist/src/server.d.ts

@@ -0,0 +1,140 @@
+import type { UseAIServerConfig } from './types';
+import type { MessageHandler } from './plugins/types';
+export type { ClientSession } from './agents/types';
+/**
+ * WebSocket server that coordinates between client applications and AI agents.
+ * Supports pluggable agents (AISDKAgent, etc.) via AG-UI protocol.
+ *
+ * Responsibilities:
+ * - Manages WebSocket connections from clients
+ * - Accepts RunAgentInput messages
+ * - Delegates to pluggable agents (AISDKAgent, etc.)
+ * - Emits AG-UI events (TEXT_MESSAGE_*, TOOL_CALL_*, etc.)
+ * - Routes tool execution requests back to clients
+ * - Maintains conversation history and state per session
+ * - Handles rate limiting
+ * - Supports plugins for extending functionality
+ *
+ * @example
+ * ```typescript
+ * import { UseAIServer, AISDKAgent } from '@meetsmore-oss/use-ai-server';
+ * import { createAnthropic } from '@ai-sdk/anthropic';
+ * import { openai } from '@ai-sdk/openai';
+ *
+ * // Single agent (Claude)
+ * const anthropic = createAnthropic({
+ *   apiKey: process.env.ANTHROPIC_API_KEY,
+ * });
+ * const claudeAgent = new AISDKAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ * });
+ * const server = new UseAIServer({
+ *   port: 8081,
+ *   agents: { claude: claudeAgent },
+ *   defaultAgent: 'claude', // Default agent name
+ * });
+ *
+ * // Multiple agents (Claude + OpenAI)
+ * const gptAgent = new AISDKAgent({
+ *   model: openai('gpt-4-turbo'),
+ * });
+ * const multiServer = new UseAIServer({
+ *   port: 8081,
+ *   agents: {
+ *     claude: claudeAgent,
+ *     'gpt-4': gptAgent,
+ *   },
+ *   runner: 'claude', // Default for chat
+ * });
+ * ```
+ */
+export declare class UseAIServer {
+    private io;
+    private httpServer;
+    private agent;
+    private defaultAgentId;
+    private agents;
+    private clients;
+    private config;
+    private rateLimiter;
+    private cleanupInterval;
+    private clientIdCounter;
+    private plugins;
+    private messageHandlers;
+    private mcpEndpoints;
+    /**
+     * Creates a new UseAI server instance.
+     *
+     * @param config - Server configuration options
+     * @throws Error if the specified agent name does not exist in the agents map
+     */
+    constructor(config: UseAIServerConfig);
+    /**
+     * Initializes the server by fetching MCP tools from all endpoints.
+     * Must be called before the server starts accepting connections.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Initialize all plugins by calling their registerHandlers method.
+     * This allows plugins to register custom message handlers.
+     */
+    private initializePlugins;
+    /**
+     * Register a custom message handler for a specific message type.
+     * Used by plugins to handle custom message types.
+     *
+     * @param type - The message type to handle (e.g., 'run_workflow')
+     * @param handler - The handler function to call when this message type is received
+     */
+    registerMessageHandler(type: string, handler: MessageHandler): void;
+    private setupSocketIOServer;
+    private handleClientMessage;
+    private handleRunAgent;
+    private buildSystemPrompt;
+    private handleToolResult;
+    private handleAbortRun;
+    private sendEvent;
+    /**
+     * Gets MCP tools for a session, using caching with authentication headers.
+     * Lazily fetches tools on first request, then caches per-session.
+     *
+     * Cache is invalidated when:
+     * 1. Headers hash changes (different user/token)
+     * 2. TTL expires (if configured per endpoint)
+     *
+     * @param session - The client session
+     * @param mcpHeaders - Optional MCP headers map with per-endpoint auth headers
+     * @returns Array of remote tool definitions from all MCP endpoints
+     */
+    private getMcpToolsForSession;
+    /**
+     * Checks if the MCP tools cache is still valid for a session.
+     *
+     * @param session - The client session
+     * @param currentHeadersHash - Hash of current auth headers
+     * @param now - Current timestamp
+     * @returns true if cache is valid, false if refresh is needed
+     */
+    private isMcpToolsCacheValid;
+    /**
+     * Creates a hash of MCP headers for use as a cache key.
+     *
+     * @param mcpHeaders - Optional MCP headers map
+     * @returns Hash string (16 chars), or 'no-auth' if no headers
+     */
+    private hashMcpHeaders;
+    /**
+     * Resolves headers for a specific MCP endpoint from the headers map.
+     *
+     * @param endpointUrl - The endpoint URL to match
+     * @param mcpHeaders - Optional MCP headers map
+     * @returns Headers to use for this endpoint (empty object if no match)
+     */
+    private resolveHeadersForEndpoint;
+    /**
+     * Closes the server and cleans up resources.
+     * Stops accepting new connections and terminates all existing connections.
+     */
+    close(): void;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/src/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,iBAAiB,EAUlB,MAAM,SAAS,CAAC;AAMjB,OAAO,KAAK,EAAqB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAKzE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,EAAE,CAAiB;IAC3B,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,MAAM,CAAkJ;IAChK,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,eAAe,CAAiB;IACxC,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,eAAe,CAA0C;IACjE,OAAO,CAAC,YAAY,CAAgC;IAEpD;;;;;OAKG;gBACS,MAAM,EAAE,iBAAiB;IA2ErC;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAqBjC;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;;;;;OAMG;IACI,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAS1E,OAAO,CAAC,mBAAmB;YA0Eb,mBAAmB;YA2BnB,cAAc;IAgQ5B,OAAO,CAAC,iBAAiB;IAqCzB,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,SAAS;IAMjB;;;;;;;;;;;OAWG;YACW,qBAAqB;IA+CnC;;;;;;;OAOG;IACH,OAAO,CAAC,oBAAoB;IAwC5B;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAoBtB;;;;;;OAMG;IACH,OAAO,CAAC,yBAAyB;IAYjC;;;OAGG;IACI,KAAK;CASb"}

package/dist/src/server.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=server.test.d.ts.map

package/dist/src/server.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.test.d.ts","sourceRoot":"","sources":["../../src/server.test.ts"],"names":[],"mappings":""}

package/dist/src/test-preload.d.ts

@@ -0,0 +1,25 @@
+declare const logFile: string;
+declare const originalConsole: {
+    log: {
+        (...data: any[]): void;
+        (...data: any[]): void;
+        (message?: any, ...optionalParams: any[]): void;
+    };
+    info: {
+        (...data: any[]): void;
+        (...data: any[]): void;
+        (message?: any, ...optionalParams: any[]): void;
+    };
+    warn: {
+        (...data: any[]): void;
+        (...data: any[]): void;
+        (message?: any, ...optionalParams: any[]): void;
+    };
+    error: {
+        (...data: any[]): void;
+        (...data: any[]): void;
+        (message?: any, ...optionalParams: any[]): void;
+    };
+};
+export { logFile, originalConsole };
+//# sourceMappingURL=test-preload.d.ts.map

package/dist/src/test-preload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-preload.d.ts","sourceRoot":"","sources":["../../src/test-preload.ts"],"names":[],"mappings":"AAIA,QAAA,MAAM,OAAO,QAA6B,CAAC;AAY3C,QAAA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;CAKpB,CAAC;AAmBF,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/src/tool-execution.integration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool-execution.integration.test.d.ts.map

package/dist/src/tool-execution.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-execution.integration.test.d.ts","sourceRoot":"","sources":["../../src/tool-execution.integration.test.ts"],"names":[],"mappings":""}

package/dist/src/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Configuration for an MCP (Model Context Protocol) endpoint.
+ * MCP endpoints provide tools that can be discovered and executed server-side.
+ */
+export interface McpEndpointConfig {
+    /** The full HTTP URL of the MCP endpoint (e.g., 'http://backend.com/mcp') */
+    url: string;
+    /** Optional HTTP headers for authentication (e.g., { 'Authorization': 'Bearer token' }) */
+    headers?: Record<string, string>;
+    /**
+     * Tool execution timeout in milliseconds.
+     * Default: 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Optional namespace prefix for tools from this endpoint.
+     * Useful to avoid naming conflicts when using multiple MCP endpoints.
+     * Example: namespace='backend' → tool 'calculator' becomes 'backend_calculator'
+     */
+    namespace?: string;
+    /**
+     * Cache TTL for tool lists in milliseconds.
+     * After this duration, tools are re-fetched on next run_agent.
+     * Default: 0 (cache for entire session, no TTL)
+     */
+    toolsCacheTtl?: number;
+}
+/**
+ * Configuration options for the UseAI server.
+ *
+ * @template TAgents - Object mapping agent names to agent instances
+ */
+export interface UseAIServerConfig<TAgents extends Record<string, import('./agents/types').Agent> = Record<string, import('./agents/types').Agent>> {
+    /** Object mapping agent names to agent instances. */
+    agents: TAgents;
+    /** Name of the default agent to use for chat (run_agent). Must be a key in agents object. */
+    defaultAgent: keyof TAgents & string;
+    /** The port number for the WebSocket server. Default: 8081 */
+    port?: number;
+    /** Maximum number of requests allowed per time window. Set to 0 to disable rate limiting. Default: 0 */
+    rateLimitMaxRequests?: number;
+    /** Time window in milliseconds for rate limiting. Default: 60000 (1 minute) */
+    rateLimitWindowMs?: number;
+    /** Optional array of plugins to extend server functionality */
+    plugins?: import('./plugins/types').UseAIServerPlugin[];
+    /**
+     * Optional array of MCP endpoints to fetch tools from.
+     * Tools from these endpoints will be automatically available to all agents and workflows.
+     */
+    mcpEndpoints?: McpEndpointConfig[];
+    /**
+     * Maximum HTTP buffer size in bytes for Socket.IO payloads.
+     * Increase this if you need to support larger file uploads.
+     * Default: 20MB (20 * 1024 * 1024)
+     */
+    maxHttpBufferSize?: number;
+}
+export type { ToolDefinition, ClientMessage, Tool, Message, Context, RunAgentInput, State, RunAgentMessage, ToolResultMessage, AbortRunMessage, RunStartedEvent, RunFinishedEvent, RunErrorEvent, StepStartedEvent, StepFinishedEvent, TextMessageStartEvent, TextMessageContentEvent, TextMessageEndEvent, TextMessageChunkEvent, ToolCallStartEvent, ToolCallArgsEvent, ToolCallEndEvent, ToolCallChunkEvent, ToolCallResultEvent, StateSnapshotEvent, StateDeltaEvent, MessagesSnapshotEvent, RawEvent, CustomEvent, ActivitySnapshotEvent, ActivityDeltaEvent, AGUIEvent, WorkflowStatus, UseAIClientMessage, RunWorkflowMessage, } from '@meetsmore-oss/use-ai-core';
+export { EventType, ErrorCode } from '@meetsmore-oss/use-ai-core';
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,gBAAgB,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,gBAAgB,EAAE,KAAK,CAAC;IAChJ,qDAAqD;IACrD,MAAM,EAAE,OAAO,CAAC;IAChB,6FAA6F;IAC7F,YAAY,EAAE,MAAM,OAAO,GAAG,MAAM,CAAC;IACrC,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wGAAwG;IACxG,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,iBAAiB,EAAE,iBAAiB,EAAE,CAAC;IACxD;;;OAGG;IACH,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACnC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAGD,YAAY,EACV,cAAc,EACd,aAAa,EAEb,IAAI,EACJ,OAAO,EACP,OAAO,EACP,aAAa,EACb,KAAK,EACL,eAAe,EACf,iBAAiB,EACjB,eAAe,EAEf,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,QAAQ,EACR,WAAW,EACX,qBAAqB,EACrB,kBAAkB,EAClB,SAAS,EAET,cAAc,EACd,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/src/utils/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Utility functions for use-ai server.
+ */
+export { createClientToolExecutor } from './toolConverter';
+export { isRemoteTool, createGlobFilter, and, or, not, } from './toolFilters';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,GAAG,EACH,EAAE,EACF,GAAG,GACJ,MAAM,eAAe,CAAC"}

package/dist/src/utils/patternMatcher.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Generic utility for matching strings against patterns using picomatch.
+ *
+ * Supported pattern types:
+ * 1. **Constant strings** - Exact match
+ * 2. **Glob patterns** - Wildcard matching (via picomatch)
+ *
+ * @example
+ * ```typescript
+ * // Constant
+ * matchesPattern('https://api.example.com', 'https://api.example.com')
+ *
+ * // Glob with wildcards
+ * matchesPattern('https://api.meetsmore.com', 'https://*.meetsmore.com')
+ * matchesPattern('https://api.example.com', '*://*.example.com')
+ * ```
+ */
+/**
+ * Matches a string against a pattern (constant string or glob).
+ */
+export declare function matchesPattern(str: string, pattern: string): boolean;
+/**
+ * Finds the first matching pattern and its value from a pattern map.
+ * Exact string matches have priority over glob patterns.
+ *
+ * @param str - The string to match against patterns
+ * @param patternMap - A map of patterns to values
+ * @returns The value for the first matching pattern, or undefined if no match
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   'https://api.example.com': { key: 'exact' },
+ *   'https://*.example.com': { key: 'wildcard' }
+ * };
+ * findMatch('https://api.example.com', config); // { key: 'exact' }
+ * findMatch('https://other.example.com', config); // { key: 'wildcard' }
+ * ```
+ */
+export declare function findMatch<T>(str: string, patternMap: Record<string, T>): T | undefined;
+//# sourceMappingURL=patternMatcher.d.ts.map

package/dist/src/utils/patternMatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patternMatcher.d.ts","sourceRoot":"","sources":["../../../src/utils/patternMatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAMpE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,GAC5B,CAAC,GAAG,SAAS,CAgBf"}

package/dist/src/utils/patternMatcher.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=patternMatcher.test.d.ts.map

package/dist/src/utils/patternMatcher.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patternMatcher.test.d.ts","sourceRoot":"","sources":["../../../src/utils/patternMatcher.test.ts"],"names":[],"mappings":""}

package/dist/src/utils/toolConverter.d.ts

@@ -0,0 +1,22 @@
+import type { ClientSession } from '../agents/types';
+/**
+ * Generic tool arguments type - tools receive key-value pairs
+ */
+type ToolArguments = Record<string, unknown>;
+/**
+ * Generic tool result type - tools can return any value
+ */
+type ToolResult = unknown;
+/**
+ * Creates execute function for client-side tools.
+ * Note: TOOL_CALL events are emitted from the stream loop, not here.
+ * The toolCallId is provided by AI SDK in the execute options.
+ *
+ * @param session - The client session containing pendingToolCalls map
+ * @returns An async function that waits for client tool execution and returns the result
+ */
+export declare function createClientToolExecutor(session: ClientSession): (args: ToolArguments, options: {
+    toolCallId: string;
+}) => Promise<ToolResult>;
+export {};
+//# sourceMappingURL=toolConverter.d.ts.map

package/dist/src/utils/toolConverter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolConverter.d.ts","sourceRoot":"","sources":["../../../src/utils/toolConverter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;GAEG;AACH,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE7C;;GAEG;AACH,KAAK,UAAU,GAAG,OAAO,CAAC;AAE1B;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,aAAa,GACrB,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,UAAU,CAAC,CAS/E"}

package/dist/src/utils/toolFilters.d.ts

@@ -0,0 +1,101 @@
+import type { ToolDefinition } from '../types';
+import type { RemoteToolDefinition } from '../mcp';
+/**
+ * Type guard to check if a tool is a remote MCP tool.
+ *
+ * @param tool - Tool definition to check
+ * @returns True if tool has MCP remote provider, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isRemoteTool(tool)) {
+ *   // tool is RemoteToolDefinition with _remote property
+ *   await tool._remote.provider.executeTool(...);
+ * }
+ * ```
+ */
+export declare function isRemoteTool(tool: ToolDefinition): tool is RemoteToolDefinition;
+/**
+ * Combines multiple filter functions with AND logic.
+ * All filters must return true for the tool to pass.
+ *
+ * @param filters - Filter functions to combine
+ * @returns Combined filter function
+ *
+ * @example
+ * ```typescript
+ * const agent = new AISDKAgent({
+ *   model: anthropic('claude-3-5-sonnet-20241022'),
+ *   toolFilter: and(
+ *     createMcpGlobAllowFilter(['db_*']),
+ *     (tool) => tool.description.includes('read-only')
+ *   )
+ * });
+ * ```
+ */
+export declare function and(...filters: Array<(tool: ToolDefinition) => boolean>): (tool: ToolDefinition) => boolean;
+/**
+ * Combines multiple filter functions with OR logic.
+ * At least one filter must return true for the tool to pass.
+ *
+ * @param filters - Filter functions to combine
+ * @returns Combined filter function
+ *
+ * @example
+ * ```typescript
+ * const agent = new AISDKAgent({
+ *   model: anthropic('claude-3-5-sonnet-20241022'),
+ *   toolFilter: or(
+ *     createMcpGlobAllowFilter(['db_*']),
+ *     createMcpGlobAllowFilter(['file_*'])
+ *   )
+ * });
+ * ```
+ */
+export declare function or(...filters: Array<(tool: ToolDefinition) => boolean>): (tool: ToolDefinition) => boolean;
+/**
+ * Inverts a filter function with NOT logic.
+ *
+ * @param filter - Filter function to invert
+ * @returns Inverted filter function
+ *
+ * @example
+ * ```typescript
+ * // Block MCP tools matching delete patterns (equivalent to disallow filter)
+ * const agent = new AISDKAgent({
+ *   model: anthropic('claude-3-5-sonnet-20241022'),
+ *   toolFilter: and(
+ *     or(not(isRemoteTool), createMcpGlobAllowFilter(['db_*'])),
+ *     not(createMcpGlobAllowFilter(['*_delete']))
+ *   )
+ * });
+ * ```
+ */
+export declare function not(filter: (tool: ToolDefinition) => boolean): (tool: ToolDefinition) => boolean;
+/**
+ * Creates a filter function that matches tools by glob patterns.
+ * Returns true if tool name matches any of the provided patterns.
+ *
+ * @param patterns - Glob patterns to match tool names (e.g., `['db_*', 'file_*']`)
+ * @returns Filter function for use with `AISDKAgentConfig.toolFilter`
+ *
+ * @example
+ * ```typescript
+ * // Only allow database MCP tools (client tools always pass)
+ * const agent = new AISDKAgent({
+ *   model: anthropic('claude-3-5-sonnet-20241022'),
+ *   toolFilter: or(not(isRemoteTool), createGlobFilter(['db_*']))
+ * });
+ *
+ * // Allow db_* but exclude *_delete
+ * const agent = new AISDKAgent({
+ *   model: anthropic('claude-3-5-sonnet-20241022'),
+ *   toolFilter: and(
+ *     or(not(isRemoteTool), createGlobFilter(['db_*'])),
+ *     not(createGlobFilter(['*_delete']))
+ *   )
+ * });
+ * ```
+ */
+export declare function createGlobFilter(patterns: string[]): (tool: ToolDefinition) => boolean;
+//# sourceMappingURL=toolFilters.d.ts.map

package/dist/src/utils/toolFilters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolFilters.d.ts","sourceRoot":"","sources":["../../../src/utils/toolFilters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAGnD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,IAAI,oBAAoB,CAE/E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,GAAG,CAAC,GAAG,OAAO,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAE3G;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,EAAE,CAAC,GAAG,OAAO,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAE1G;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,GAAG,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAEhG;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAOtF"}