overai 1.4.0

package/dist/tools/decorator.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * Tool Decorator and Registry - Type-safe tool creation and management
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolRegistry = exports.FunctionTool = void 0;
+exports.tool = tool;
+exports.getRegistry = getRegistry;
+exports.registerTool = registerTool;
+exports.getTool = getTool;
+/**
+ * Tool class - Represents an executable tool
+ */
+class FunctionTool {
+    constructor(config) {
+        this.name = config.name;
+        this.description = config.description || `Function ${config.name}`;
+        this.parameters = this.normalizeParameters(config.parameters);
+        this.category = config.category;
+        this.executeFn = config.execute;
+    }
+    normalizeParameters(params) {
+        if (!params) {
+            return { type: 'object', properties: {}, required: [] };
+        }
+        // Check if it's a Zod schema
+        if (params && typeof params.parse === 'function' && typeof params._def === 'object') {
+            return this.zodToJsonSchema(params);
+        }
+        // Already a JSON schema
+        return params;
+    }
+    zodToJsonSchema(zodSchema) {
+        // Basic Zod to JSON Schema conversion
+        // For full support, use zod-to-json-schema package
+        const def = zodSchema._def;
+        if (def.typeName === 'ZodObject') {
+            const properties = {};
+            const required = [];
+            for (const [key, value] of Object.entries(def.shape())) {
+                const fieldDef = value._def;
+                properties[key] = this.zodFieldToJsonSchema(fieldDef);
+                // Check if field is required (not optional)
+                if (fieldDef.typeName !== 'ZodOptional' && fieldDef.typeName !== 'ZodDefault') {
+                    required.push(key);
+                }
+            }
+            return { type: 'object', properties, required };
+        }
+        return { type: 'object', properties: {}, required: [] };
+    }
+    zodFieldToJsonSchema(def) {
+        const typeName = def.typeName;
+        switch (typeName) {
+            case 'ZodString':
+                return { type: 'string', description: def.description };
+            case 'ZodNumber':
+                return { type: 'number', description: def.description };
+            case 'ZodBoolean':
+                return { type: 'boolean', description: def.description };
+            case 'ZodArray':
+                return { type: 'array', items: this.zodFieldToJsonSchema(def.type._def) };
+            case 'ZodEnum':
+                return { type: 'string', enum: def.values };
+            case 'ZodOptional':
+                return this.zodFieldToJsonSchema(def.innerType._def);
+            case 'ZodDefault':
+                const inner = this.zodFieldToJsonSchema(def.innerType._def);
+                inner.default = def.defaultValue();
+                return inner;
+            default:
+                return { type: 'string' };
+        }
+    }
+    async execute(params, context) {
+        // Validate parameters if we have a schema
+        // For now, just execute - validation can be added later
+        return this.executeFn(params, context);
+    }
+    /**
+     * Get the tool definition for LLM
+     */
+    getDefinition() {
+        return {
+            name: this.name,
+            description: this.description,
+            parameters: this.parameters,
+            category: this.category,
+        };
+    }
+    /**
+     * Get OpenAI-compatible tool format
+     */
+    toOpenAITool() {
+        return {
+            type: 'function',
+            function: {
+                name: this.name,
+                description: this.description,
+                parameters: this.parameters,
+            },
+        };
+    }
+}
+exports.FunctionTool = FunctionTool;
+/**
+ * Create a tool from a configuration object
+ */
+function tool(config) {
+    return new FunctionTool(config);
+}
+/**
+ * Tool Registry - Manages tool registration and lookup
+ */
+class ToolRegistry {
+    constructor() {
+        this.tools = new Map();
+    }
+    register(tool, options) {
+        if (this.tools.has(tool.name) && !options?.overwrite) {
+            throw new Error(`Tool '${tool.name}' is already registered. Use { overwrite: true } to replace.`);
+        }
+        this.tools.set(tool.name, tool);
+        return this;
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    has(name) {
+        return this.tools.has(name);
+    }
+    list() {
+        return Array.from(this.tools.values());
+    }
+    getByCategory(category) {
+        return this.list().filter(t => t.category === category);
+    }
+    getDefinitions() {
+        return this.list().map(t => t.getDefinition());
+    }
+    toOpenAITools() {
+        return this.list().map(t => t.toOpenAITool());
+    }
+    delete(name) {
+        return this.tools.delete(name);
+    }
+    clear() {
+        this.tools.clear();
+    }
+}
+exports.ToolRegistry = ToolRegistry;
+// Global registry instance
+let globalRegistry = null;
+function getRegistry() {
+    if (!globalRegistry) {
+        globalRegistry = new ToolRegistry();
+    }
+    return globalRegistry;
+}
+function registerTool(tool, options) {
+    getRegistry().register(tool, options);
+}
+function getTool(name) {
+    return getRegistry().get(name);
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,8 @@
+export { BaseTool, ToolResult, ToolValidationError, validateTool, createTool, type ToolParameters } from './base';
+export * from './decorator';
+export * from './arxivTools';
+export * from './mcpSse';
+export * from './registry';
+export * from './builtins';
+export { tools, registerBuiltinTools } from './tools';
+export type { default as ToolsFacade } from './tools';

package/dist/tools/index.js

@@ -0,0 +1,36 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerBuiltinTools = exports.tools = exports.createTool = exports.validateTool = exports.ToolValidationError = exports.BaseTool = void 0;
+// Export base tool interfaces and classes
+var base_1 = require("./base");
+Object.defineProperty(exports, "BaseTool", { enumerable: true, get: function () { return base_1.BaseTool; } });
+Object.defineProperty(exports, "ToolValidationError", { enumerable: true, get: function () { return base_1.ToolValidationError; } });
+Object.defineProperty(exports, "validateTool", { enumerable: true, get: function () { return base_1.validateTool; } });
+Object.defineProperty(exports, "createTool", { enumerable: true, get: function () { return base_1.createTool; } });
+// Export decorator and registry (legacy)
+__exportStar(require("./decorator"), exports);
+// Export all tool modules
+__exportStar(require("./arxivTools"), exports);
+__exportStar(require("./mcpSse"), exports);
+// Export new registry system
+__exportStar(require("./registry"), exports);
+// Export built-in tools
+__exportStar(require("./builtins"), exports);
+// Export tools facade
+var tools_1 = require("./tools");
+Object.defineProperty(exports, "tools", { enumerable: true, get: function () { return tools_1.tools; } });
+Object.defineProperty(exports, "registerBuiltinTools", { enumerable: true, get: function () { return tools_1.registerBuiltinTools; } });

package/dist/tools/mcpSse.d.ts

@@ -0,0 +1,43 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { BaseTool } from './base';
+export interface MCPToolInfo {
+    name: string;
+    description?: string;
+    inputSchema?: any;
+}
+export declare class MCPTool extends BaseTool<any, any> {
+    name: string;
+    description: string;
+    private client;
+    private inputSchema;
+    constructor(info: MCPToolInfo, client: Client);
+    get schemaProperties(): Record<string, any> | undefined;
+    run(args?: any): Promise<any>;
+    toOpenAITool(): {
+        type: string;
+        function: {
+            name: string;
+            description: string;
+            parameters: any;
+        };
+    };
+}
+export declare class MCP implements Iterable<MCPTool> {
+    private url;
+    private debug;
+    tools: MCPTool[];
+    private client;
+    constructor(url: string, debug?: boolean);
+    initialize(): Promise<void>;
+    [Symbol.iterator](): Iterator<MCPTool>;
+    toOpenAITools(): {
+        type: string;
+        function: {
+            name: string;
+            description: string;
+            parameters: any;
+        };
+    }[];
+    close(): Promise<void>;
+    get isConnected(): boolean;
+}

package/dist/tools/mcpSse.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP = exports.MCPTool = void 0;
+const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
+const sse_js_1 = require("@modelcontextprotocol/sdk/client/sse.js");
+const base_1 = require("./base");
+class MCPTool extends base_1.BaseTool {
+    constructor(info, client) {
+        super();
+        this.name = info.name;
+        this.description = info.description || `Call the ${info.name} tool`;
+        this.client = client;
+        this.inputSchema = info.inputSchema || { type: 'object', properties: {}, required: [] };
+    }
+    get schemaProperties() {
+        return this.inputSchema?.properties;
+    }
+    async run(args = {}) {
+        try {
+            const result = await this.client.callTool({ name: this.name, arguments: args });
+            if (result.structuredContent) {
+                return result.structuredContent;
+            }
+            if (Array.isArray(result.content) && result.content.length > 0) {
+                const item = result.content[0];
+                if (typeof item.text === 'string')
+                    return item.text;
+            }
+            return result;
+        }
+        catch (error) {
+            throw new Error(`Failed to execute tool ${this.name}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    toOpenAITool() {
+        return {
+            type: 'function',
+            function: {
+                name: this.name,
+                description: this.description,
+                parameters: this.inputSchema
+            }
+        };
+    }
+}
+exports.MCPTool = MCPTool;
+class MCP {
+    constructor(url, debug = false) {
+        this.url = url;
+        this.debug = debug;
+        this.tools = [];
+        this.client = null;
+        if (debug) {
+            console.log(`MCP client initialized for URL: ${url}`);
+        }
+    }
+    async initialize() {
+        if (this.client) {
+            if (this.debug)
+                console.log('MCP client already initialized');
+            return;
+        }
+        try {
+            this.client = new index_js_1.Client({ name: 'praisonai-ts-mcp', version: '1.0.0' });
+            const transport = new sse_js_1.SSEClientTransport(new URL(this.url));
+            await this.client.connect(transport);
+            const { tools } = await this.client.listTools();
+            this.tools = tools.map((t) => new MCPTool({
+                name: t.name,
+                description: t.description,
+                inputSchema: t.inputSchema
+            }, this.client));
+            if (this.debug)
+                console.log(`Initialized MCP with ${this.tools.length} tools`);
+        }
+        catch (error) {
+            if (this.client) {
+                await this.client.close().catch(() => { });
+                this.client = null;
+            }
+            throw new Error(`Failed to initialize MCP client: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    [Symbol.iterator]() {
+        return this.tools[Symbol.iterator]();
+    }
+    toOpenAITools() {
+        return this.tools.map(t => t.toOpenAITool());
+    }
+    async close() {
+        if (this.client) {
+            try {
+                await this.client.close();
+            }
+            catch (error) {
+                if (this.debug) {
+                    console.warn('Error closing MCP client:', error);
+                }
+            }
+            finally {
+                this.client = null;
+                this.tools = [];
+            }
+        }
+    }
+    get isConnected() {
+        return this.client !== null;
+    }
+}
+exports.MCP = MCP;

package/dist/tools/registry/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * AI SDK Tools Registry - Main Exports
+ *
+ * Lazy-loaded exports for the tools registry system.
+ */
+export type { ToolExecutionContext, ToolLimits, RedactionHooks, ToolLogger, ToolCapabilities, InstallHints, ToolMetadata, ToolExecutionResult, PraisonTool, ToolParameterSchema, ToolParameterProperty, ToolMiddleware, ToolHooks, ToolFactory, RegisteredTool, ToolInstallStatus, } from './types';
+export { MissingDependencyError, MissingEnvVarError } from './types';
+export { ToolsRegistry, getToolsRegistry, createToolsRegistry, resetToolsRegistry, } from './registry';
+export { createLoggingMiddleware, createTimeoutMiddleware, createRedactionMiddleware, createRateLimitMiddleware, createRetryMiddleware, createTracingMiddleware, createValidationMiddleware, composeMiddleware, } from './middleware';

package/dist/tools/registry/index.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * AI SDK Tools Registry - Main Exports
+ *
+ * Lazy-loaded exports for the tools registry system.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeMiddleware = exports.createValidationMiddleware = exports.createTracingMiddleware = exports.createRetryMiddleware = exports.createRateLimitMiddleware = exports.createRedactionMiddleware = exports.createTimeoutMiddleware = exports.createLoggingMiddleware = exports.resetToolsRegistry = exports.createToolsRegistry = exports.getToolsRegistry = exports.ToolsRegistry = exports.MissingEnvVarError = exports.MissingDependencyError = void 0;
+// Errors
+var types_1 = require("./types");
+Object.defineProperty(exports, "MissingDependencyError", { enumerable: true, get: function () { return types_1.MissingDependencyError; } });
+Object.defineProperty(exports, "MissingEnvVarError", { enumerable: true, get: function () { return types_1.MissingEnvVarError; } });
+// Registry
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "ToolsRegistry", { enumerable: true, get: function () { return registry_1.ToolsRegistry; } });
+Object.defineProperty(exports, "getToolsRegistry", { enumerable: true, get: function () { return registry_1.getToolsRegistry; } });
+Object.defineProperty(exports, "createToolsRegistry", { enumerable: true, get: function () { return registry_1.createToolsRegistry; } });
+Object.defineProperty(exports, "resetToolsRegistry", { enumerable: true, get: function () { return registry_1.resetToolsRegistry; } });
+// Middleware
+var middleware_1 = require("./middleware");
+Object.defineProperty(exports, "createLoggingMiddleware", { enumerable: true, get: function () { return middleware_1.createLoggingMiddleware; } });
+Object.defineProperty(exports, "createTimeoutMiddleware", { enumerable: true, get: function () { return middleware_1.createTimeoutMiddleware; } });
+Object.defineProperty(exports, "createRedactionMiddleware", { enumerable: true, get: function () { return middleware_1.createRedactionMiddleware; } });
+Object.defineProperty(exports, "createRateLimitMiddleware", { enumerable: true, get: function () { return middleware_1.createRateLimitMiddleware; } });
+Object.defineProperty(exports, "createRetryMiddleware", { enumerable: true, get: function () { return middleware_1.createRetryMiddleware; } });
+Object.defineProperty(exports, "createTracingMiddleware", { enumerable: true, get: function () { return middleware_1.createTracingMiddleware; } });
+Object.defineProperty(exports, "createValidationMiddleware", { enumerable: true, get: function () { return middleware_1.createValidationMiddleware; } });
+Object.defineProperty(exports, "composeMiddleware", { enumerable: true, get: function () { return middleware_1.composeMiddleware; } });

package/dist/tools/registry/middleware.d.ts

@@ -0,0 +1,43 @@
+/**
+ * AI SDK Tools Registry - Middleware Pipeline
+ *
+ * Composable middleware for tool execution:
+ * - Logging
+ * - Tracing
+ * - Rate limiting
+ * - Redaction
+ * - Timeout handling
+ */
+import type { ToolMiddleware, ToolLogger } from './types';
+/**
+ * Create a logging middleware
+ */
+export declare function createLoggingMiddleware(logger?: ToolLogger): ToolMiddleware;
+/**
+ * Create a timeout middleware
+ */
+export declare function createTimeoutMiddleware(defaultTimeoutMs?: number): ToolMiddleware;
+/**
+ * Create a redaction middleware for PII/sensitive data
+ */
+export declare function createRedactionMiddleware(patterns?: RegExp[]): ToolMiddleware;
+/**
+ * Create a rate limiting middleware (simple token bucket)
+ */
+export declare function createRateLimitMiddleware(maxRequests?: number, windowMs?: number): ToolMiddleware;
+/**
+ * Create a retry middleware with exponential backoff
+ */
+export declare function createRetryMiddleware(maxRetries?: number, baseDelayMs?: number): ToolMiddleware;
+/**
+ * Create a tracing middleware that adds trace context
+ */
+export declare function createTracingMiddleware(): ToolMiddleware;
+/**
+ * Create a validation middleware that checks input against limits
+ */
+export declare function createValidationMiddleware(): ToolMiddleware;
+/**
+ * Compose multiple middleware into a single middleware
+ */
+export declare function composeMiddleware(...middlewares: ToolMiddleware[]): ToolMiddleware;

package/dist/tools/registry/middleware.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * AI SDK Tools Registry - Middleware Pipeline
+ *
+ * Composable middleware for tool execution:
+ * - Logging
+ * - Tracing
+ * - Rate limiting
+ * - Redaction
+ * - Timeout handling
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLoggingMiddleware = createLoggingMiddleware;
+exports.createTimeoutMiddleware = createTimeoutMiddleware;
+exports.createRedactionMiddleware = createRedactionMiddleware;
+exports.createRateLimitMiddleware = createRateLimitMiddleware;
+exports.createRetryMiddleware = createRetryMiddleware;
+exports.createTracingMiddleware = createTracingMiddleware;
+exports.createValidationMiddleware = createValidationMiddleware;
+exports.composeMiddleware = composeMiddleware;
+/**
+ * Create a logging middleware
+ */
+function createLoggingMiddleware(logger) {
+    const log = logger || console;
+    return async (input, context, next) => {
+        const startTime = Date.now();
+        const traceId = context.traceId || 'unknown';
+        log.debug?.(`[${traceId}] Tool call started`, { input });
+        try {
+            const result = await next();
+            const duration = Date.now() - startTime;
+            log.debug?.(`[${traceId}] Tool call completed in ${duration}ms`);
+            return result;
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            log.error?.(`[${traceId}] Tool call failed after ${duration}ms`, error);
+            throw error;
+        }
+    };
+}
+/**
+ * Create a timeout middleware
+ */
+function createTimeoutMiddleware(defaultTimeoutMs = 30000) {
+    return async (input, context, next) => {
+        const timeoutMs = context.limits?.timeoutMs || defaultTimeoutMs;
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(new Error(`Tool execution timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+        });
+        return Promise.race([next(), timeoutPromise]);
+    };
+}
+/**
+ * Create a redaction middleware for PII/sensitive data
+ */
+function createRedactionMiddleware(patterns) {
+    const defaultPatterns = [
+        // Email
+        /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
+        // SSN
+        /\b\d{3}-\d{2}-\d{4}\b/g,
+        // Credit card
+        /\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b/g,
+        // Phone (US)
+        /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/g,
+    ];
+    const allPatterns = [...defaultPatterns, ...(patterns || [])];
+    const redact = (value) => {
+        if (typeof value === 'string') {
+            let result = value;
+            for (const pattern of allPatterns) {
+                result = result.replace(pattern, '[REDACTED]');
+            }
+            return result;
+        }
+        if (Array.isArray(value)) {
+            return value.map(redact);
+        }
+        if (value && typeof value === 'object') {
+            const result = {};
+            for (const [k, v] of Object.entries(value)) {
+                result[k] = redact(v);
+            }
+            return result;
+        }
+        return value;
+    };
+    return async (input, context, next) => {
+        // Redact input if hooks are set
+        const redactedInput = context.redaction?.redactInput
+            ? context.redaction.redactInput(input)
+            : redact(input);
+        // Execute with redacted input
+        const result = await next();
+        // Redact output if hooks are set
+        const redactedOutput = context.redaction?.redactOutput
+            ? context.redaction.redactOutput(result)
+            : redact(result);
+        return redactedOutput;
+    };
+}
+/**
+ * Create a rate limiting middleware (simple token bucket)
+ */
+function createRateLimitMiddleware(maxRequests = 10, windowMs = 1000) {
+    const requests = [];
+    return async (input, context, next) => {
+        const now = Date.now();
+        // Remove old requests outside the window
+        while (requests.length > 0 && requests[0] < now - windowMs) {
+            requests.shift();
+        }
+        if (requests.length >= maxRequests) {
+            const waitTime = requests[0] + windowMs - now;
+            throw new Error(`Rate limit exceeded. Try again in ${waitTime}ms`);
+        }
+        requests.push(now);
+        return next();
+    };
+}
+/**
+ * Create a retry middleware with exponential backoff
+ */
+function createRetryMiddleware(maxRetries = 3, baseDelayMs = 1000) {
+    return async (input, context, next) => {
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await next();
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                if (attempt < maxRetries) {
+                    const delay = baseDelayMs * Math.pow(2, attempt);
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                }
+            }
+        }
+        throw lastError;
+    };
+}
+/**
+ * Create a tracing middleware that adds trace context
+ */
+function createTracingMiddleware() {
+    return async (input, context, next) => {
+        // Generate trace ID if not present
+        if (!context.traceId) {
+            context.traceId = generateTraceId();
+        }
+        // Add span for this tool call
+        const spanId = generateSpanId();
+        const startTime = Date.now();
+        try {
+            const result = await next();
+            // Log span completion
+            if (context.logger) {
+                context.logger.debug('Tool span completed', {
+                    traceId: context.traceId,
+                    spanId,
+                    durationMs: Date.now() - startTime,
+                });
+            }
+            return result;
+        }
+        catch (error) {
+            if (context.logger) {
+                context.logger.error('Tool span failed', {
+                    traceId: context.traceId,
+                    spanId,
+                    durationMs: Date.now() - startTime,
+                    error,
+                });
+            }
+            throw error;
+        }
+    };
+}
+/**
+ * Create a validation middleware that checks input against limits
+ */
+function createValidationMiddleware() {
+    return async (input, context, next) => {
+        const limits = context.limits;
+        if (limits?.maxPayloadBytes) {
+            const size = JSON.stringify(input).length;
+            if (size > limits.maxPayloadBytes) {
+                throw new Error(`Input payload size (${size} bytes) exceeds limit (${limits.maxPayloadBytes} bytes)`);
+            }
+        }
+        return next();
+    };
+}
+/**
+ * Compose multiple middleware into a single middleware
+ */
+function composeMiddleware(...middlewares) {
+    return async (input, context, next) => {
+        let index = 0;
+        const composedNext = async () => {
+            if (index < middlewares.length) {
+                const mw = middlewares[index++];
+                return mw(input, context, composedNext);
+            }
+            return next();
+        };
+        return composedNext();
+    };
+}
+// Helper functions
+function generateTraceId() {
+    return `trace_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 11)}`;
+}
+function generateSpanId() {
+    return `span_${Math.random().toString(36).slice(2, 11)}`;
+}