overai 1.4.0

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

@@ -0,0 +1,92 @@
+/**
+ * AI SDK Tools Registry - Core Registry Implementation
+ *
+ * Singleton-safe registry for managing built-in and custom tools.
+ * Supports lazy loading, middleware, and multi-agent safety.
+ */
+import type { ToolMetadata, ToolFactory, PraisonTool, ToolHooks, ToolMiddleware, ToolInstallStatus } from './types';
+/**
+ * Tools Registry - Manages tool registration, lookup, and instantiation
+ */
+export declare class ToolsRegistry {
+    private tools;
+    private middleware;
+    private hooks;
+    private installCache;
+    /**
+     * Register a tool with the registry
+     */
+    register(metadata: ToolMetadata, factory: ToolFactory): this;
+    /**
+     * Unregister a tool
+     */
+    unregister(id: string): boolean;
+    /**
+     * Check if a tool is registered
+     */
+    has(id: string): boolean;
+    /**
+     * Get tool metadata
+     */
+    getMetadata(id: string): ToolMetadata | undefined;
+    /**
+     * List all registered tools
+     */
+    list(): ToolMetadata[];
+    /**
+     * List tools by tag
+     */
+    listByTag(tag: string): ToolMetadata[];
+    /**
+     * List tools by capability
+     */
+    listByCapability(capability: keyof ToolMetadata['capabilities']): ToolMetadata[];
+    /**
+     * Create a tool instance (lazy loads the dependency)
+     */
+    create<TConfig = unknown, TInput = unknown, TOutput = unknown>(id: string, config?: TConfig): PraisonTool<TInput, TOutput>;
+    /**
+     * Add middleware to the pipeline
+     */
+    use(middleware: ToolMiddleware): this;
+    /**
+     * Set hooks
+     */
+    setHooks(hooks: ToolHooks): this;
+    /**
+     * Check if a tool's optional dependency is installed
+     */
+    checkInstalled(id: string): Promise<boolean>;
+    /**
+     * Check environment variables for a tool
+     */
+    checkEnvVars(id: string): string[];
+    /**
+     * Get installation status for a tool
+     */
+    getInstallStatus(id: string): Promise<ToolInstallStatus | null>;
+    /**
+     * Get installation status for all tools
+     */
+    getAllInstallStatus(): Promise<ToolInstallStatus[]>;
+    /**
+     * Clear the registry
+     */
+    clear(): void;
+    /**
+     * Get the number of registered tools
+     */
+    get size(): number;
+}
+/**
+ * Get the global tools registry (singleton)
+ */
+export declare function getToolsRegistry(): ToolsRegistry;
+/**
+ * Create a new isolated registry (for testing or multi-agent scenarios)
+ */
+export declare function createToolsRegistry(): ToolsRegistry;
+/**
+ * Reset the global registry (mainly for testing)
+ */
+export declare function resetToolsRegistry(): void;

package/dist/tools/registry/registry.js

@@ -0,0 +1,280 @@
+"use strict";
+/**
+ * AI SDK Tools Registry - Core Registry Implementation
+ *
+ * Singleton-safe registry for managing built-in and custom tools.
+ * Supports lazy loading, middleware, and multi-agent safety.
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolsRegistry = void 0;
+exports.getToolsRegistry = getToolsRegistry;
+exports.createToolsRegistry = createToolsRegistry;
+exports.resetToolsRegistry = resetToolsRegistry;
+/**
+ * Tools Registry - Manages tool registration, lookup, and instantiation
+ */
+class ToolsRegistry {
+    constructor() {
+        this.tools = new Map();
+        this.middleware = [];
+        this.hooks = {};
+        this.installCache = new Map();
+    }
+    /**
+     * Register a tool with the registry
+     */
+    register(metadata, factory) {
+        this.tools.set(metadata.id, { metadata, factory });
+        return this;
+    }
+    /**
+     * Unregister a tool
+     */
+    unregister(id) {
+        return this.tools.delete(id);
+    }
+    /**
+     * Check if a tool is registered
+     */
+    has(id) {
+        return this.tools.has(id);
+    }
+    /**
+     * Get tool metadata
+     */
+    getMetadata(id) {
+        return this.tools.get(id)?.metadata;
+    }
+    /**
+     * List all registered tools
+     */
+    list() {
+        return Array.from(this.tools.values()).map(t => t.metadata);
+    }
+    /**
+     * List tools by tag
+     */
+    listByTag(tag) {
+        return this.list().filter(t => t.tags.includes(tag));
+    }
+    /**
+     * List tools by capability
+     */
+    listByCapability(capability) {
+        return this.list().filter(t => t.capabilities[capability]);
+    }
+    /**
+     * Create a tool instance (lazy loads the dependency)
+     */
+    create(id, config) {
+        const registered = this.tools.get(id);
+        if (!registered) {
+            throw new Error(`Tool "${id}" is not registered. Available tools: ${this.list().map(t => t.id).join(', ')}`);
+        }
+        // Create the tool using the factory
+        const tool = registered.factory(config);
+        // Wrap execute with middleware and hooks
+        const originalExecute = tool.execute.bind(tool);
+        tool.execute = async (input, context) => {
+            const ctx = context || {};
+            // Call beforeToolCall hook
+            if (this.hooks.beforeToolCall) {
+                await this.hooks.beforeToolCall(tool.name, input, ctx);
+            }
+            try {
+                // Build middleware chain
+                let result;
+                const executeWithMiddleware = async () => {
+                    return originalExecute(input, ctx);
+                };
+                if (this.middleware.length === 0) {
+                    result = await executeWithMiddleware();
+                }
+                else {
+                    // Chain middleware
+                    let index = 0;
+                    const next = async () => {
+                        if (index < this.middleware.length) {
+                            const mw = this.middleware[index++];
+                            return mw(input, ctx, next);
+                        }
+                        return executeWithMiddleware();
+                    };
+                    result = await next();
+                }
+                // Call afterToolCall hook
+                if (this.hooks.afterToolCall) {
+                    await this.hooks.afterToolCall(tool.name, input, result, ctx);
+                }
+                return result;
+            }
+            catch (error) {
+                // Call onError hook
+                if (this.hooks.onError && error instanceof Error) {
+                    await this.hooks.onError(tool.name, error, ctx);
+                }
+                throw error;
+            }
+        };
+        return tool;
+    }
+    /**
+     * Add middleware to the pipeline
+     */
+    use(middleware) {
+        this.middleware.push(middleware);
+        return this;
+    }
+    /**
+     * Set hooks
+     */
+    setHooks(hooks) {
+        this.hooks = { ...this.hooks, ...hooks };
+        return this;
+    }
+    /**
+     * Check if a tool's optional dependency is installed
+     */
+    async checkInstalled(id) {
+        // Check cache first
+        if (this.installCache.has(id)) {
+            return this.installCache.get(id);
+        }
+        const registered = this.tools.get(id);
+        if (!registered) {
+            return false;
+        }
+        const { packageName } = registered.metadata;
+        try {
+            // Try to resolve the package
+            await Promise.resolve(`${packageName}`).then(s => __importStar(require(s)));
+            this.installCache.set(id, true);
+            return true;
+        }
+        catch {
+            this.installCache.set(id, false);
+            return false;
+        }
+    }
+    /**
+     * Check environment variables for a tool
+     */
+    checkEnvVars(id) {
+        const registered = this.tools.get(id);
+        if (!registered) {
+            return [];
+        }
+        const missing = [];
+        for (const envVar of registered.metadata.requiredEnv) {
+            if (!process.env[envVar]) {
+                missing.push(envVar);
+            }
+        }
+        return missing;
+    }
+    /**
+     * Get installation status for a tool
+     */
+    async getInstallStatus(id) {
+        const registered = this.tools.get(id);
+        if (!registered) {
+            return null;
+        }
+        const installed = await this.checkInstalled(id);
+        const missingEnvVars = this.checkEnvVars(id);
+        return {
+            id,
+            installed,
+            missingEnvVars,
+            installCommand: installed ? undefined : registered.metadata.install.npm,
+        };
+    }
+    /**
+     * Get installation status for all tools
+     */
+    async getAllInstallStatus() {
+        const statuses = [];
+        for (const id of this.tools.keys()) {
+            const status = await this.getInstallStatus(id);
+            if (status) {
+                statuses.push(status);
+            }
+        }
+        return statuses;
+    }
+    /**
+     * Clear the registry
+     */
+    clear() {
+        this.tools.clear();
+        this.middleware = [];
+        this.hooks = {};
+        this.installCache.clear();
+    }
+    /**
+     * Get the number of registered tools
+     */
+    get size() {
+        return this.tools.size;
+    }
+}
+exports.ToolsRegistry = ToolsRegistry;
+// Global registry instance
+let globalRegistry = null;
+/**
+ * Get the global tools registry (singleton)
+ */
+function getToolsRegistry() {
+    if (!globalRegistry) {
+        globalRegistry = new ToolsRegistry();
+    }
+    return globalRegistry;
+}
+/**
+ * Create a new isolated registry (for testing or multi-agent scenarios)
+ */
+function createToolsRegistry() {
+    return new ToolsRegistry();
+}
+/**
+ * Reset the global registry (mainly for testing)
+ */
+function resetToolsRegistry() {
+    if (globalRegistry) {
+        globalRegistry.clear();
+    }
+    globalRegistry = null;
+}

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

@@ -0,0 +1,217 @@
+/**
+ * AI SDK Tools Registry - Type Definitions
+ *
+ * Standard interfaces for tool registration, execution, and middleware.
+ */
+/**
+ * Tool execution context - passed to every tool call
+ */
+export interface ToolExecutionContext {
+    /** Unique identifier for the agent making the call */
+    agentId?: string;
+    /** Unique identifier for the current run/session */
+    runId?: string;
+    /** Trace ID for distributed tracing */
+    traceId?: string;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Logger instance */
+    logger?: ToolLogger;
+    /** Execution limits */
+    limits?: ToolLimits;
+    /** Redaction hooks for PII/sensitive data */
+    redaction?: RedactionHooks;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Tool execution limits
+ */
+export interface ToolLimits {
+    /** Maximum execution time in milliseconds */
+    timeoutMs?: number;
+    /** Maximum payload size in bytes */
+    maxPayloadBytes?: number;
+    /** Maximum number of results */
+    maxResults?: number;
+    /** Allowed domains (for search/scrape tools) */
+    allowedDomains?: string[];
+    /** Blocked domains (for search/scrape tools) */
+    blockedDomains?: string[];
+}
+/**
+ * Redaction hooks for sensitive data
+ */
+export interface RedactionHooks {
+    /** Redact input before tool execution */
+    redactInput?: (input: unknown) => unknown;
+    /** Redact output after tool execution */
+    redactOutput?: (output: unknown) => unknown;
+    /** Patterns to redact (regex strings) */
+    patterns?: string[];
+}
+/**
+ * Simple logger interface
+ */
+export interface ToolLogger {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}
+/**
+ * Tool capability flags
+ */
+export interface ToolCapabilities {
+    search?: boolean;
+    extract?: boolean;
+    crawl?: boolean;
+    sandbox?: boolean;
+    browser?: boolean;
+    security?: boolean;
+    rag?: boolean;
+    code?: boolean;
+}
+/**
+ * Install hints for different package managers
+ */
+export interface InstallHints {
+    npm: string;
+    pnpm: string;
+    yarn: string;
+    bun: string;
+}
+/**
+ * Tool metadata for registry
+ */
+export interface ToolMetadata {
+    /** Unique tool identifier (kebab-case) */
+    id: string;
+    /** Display name for UI */
+    displayName: string;
+    /** Tool description */
+    description: string;
+    /** Categorization tags */
+    tags: string[];
+    /** Required environment variables */
+    requiredEnv: string[];
+    /** Optional environment variables */
+    optionalEnv: string[];
+    /** Install commands for package managers */
+    install: InstallHints;
+    /** Documentation slug (relative path in docs) */
+    docsSlug: string;
+    /** Tool capabilities */
+    capabilities: ToolCapabilities;
+    /** NPM package name */
+    packageName: string;
+    /** Version constraint (semver) */
+    versionConstraint?: string;
+}
+/**
+ * Tool execution result
+ */
+export interface ToolExecutionResult<T = unknown> {
+    /** Result data */
+    data: T;
+    /** Execution success */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+    /** Execution duration in ms */
+    durationMs?: number;
+    /** Token/credit usage if applicable */
+    usage?: {
+        tokens?: number;
+        credits?: number;
+    };
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Base interface for all PraisonAI tools
+ */
+export interface PraisonTool<TInput = unknown, TOutput = unknown> {
+    /** Tool name (used in function calling) */
+    name: string;
+    /** Tool description (used by LLM) */
+    description: string;
+    /** JSON Schema for parameters */
+    parameters: ToolParameterSchema;
+    /** Execute the tool */
+    execute: (input: TInput, context?: ToolExecutionContext) => Promise<TOutput>;
+}
+/**
+ * JSON Schema for tool parameters
+ */
+export interface ToolParameterSchema {
+    type: 'object';
+    properties: Record<string, ToolParameterProperty>;
+    required?: string[];
+}
+/**
+ * Individual parameter property schema
+ */
+export interface ToolParameterProperty {
+    type: string;
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+    items?: ToolParameterProperty;
+    properties?: Record<string, ToolParameterProperty>;
+}
+/**
+ * Middleware function type
+ */
+export type ToolMiddleware = (input: unknown, context: ToolExecutionContext, next: () => Promise<unknown>) => Promise<unknown>;
+/**
+ * Before/after hook types
+ */
+export interface ToolHooks {
+    beforeToolCall?: (toolName: string, input: unknown, context: ToolExecutionContext) => Promise<void> | void;
+    afterToolCall?: (toolName: string, input: unknown, output: unknown, context: ToolExecutionContext) => Promise<void> | void;
+    onError?: (toolName: string, error: Error, context: ToolExecutionContext) => Promise<void> | void;
+}
+/**
+ * Tool factory function type
+ */
+export type ToolFactory<TConfig = unknown, TInput = unknown, TOutput = unknown> = (config?: TConfig) => PraisonTool<TInput, TOutput>;
+/**
+ * Registered tool entry in the registry
+ */
+export interface RegisteredTool {
+    metadata: ToolMetadata;
+    factory: ToolFactory;
+    /** Whether the optional dependency is installed */
+    isInstalled?: boolean;
+}
+/**
+ * Tool installation status
+ */
+export interface ToolInstallStatus {
+    id: string;
+    installed: boolean;
+    version?: string;
+    missingEnvVars: string[];
+    installCommand?: string;
+}
+/**
+ * Error thrown when optional dependency is missing
+ */
+export declare class MissingDependencyError extends Error {
+    readonly toolId: string;
+    readonly packageName: string;
+    readonly installHints: InstallHints;
+    readonly requiredEnv: string[];
+    readonly docsSlug: string;
+    constructor(toolId: string, packageName: string, installHints: InstallHints, requiredEnv: string[], docsSlug: string);
+}
+/**
+ * Error thrown when required environment variable is missing
+ */
+export declare class MissingEnvVarError extends Error {
+    readonly toolId: string;
+    readonly envVar: string;
+    readonly docsSlug: string;
+    constructor(toolId: string, envVar: string, docsSlug: string);
+}

package/dist/tools/registry/types.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * AI SDK Tools Registry - Type Definitions
+ *
+ * Standard interfaces for tool registration, execution, and middleware.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MissingEnvVarError = exports.MissingDependencyError = void 0;
+/**
+ * Error thrown when optional dependency is missing
+ */
+class MissingDependencyError extends Error {
+    constructor(toolId, packageName, installHints, requiredEnv, docsSlug) {
+        const installCmd = installHints.npm;
+        const envVarsMsg = requiredEnv.length > 0
+            ? `\n\nRequired environment variables:\n${requiredEnv.map(v => `  - ${v}`).join('\n')}`
+            : '';
+        super(`Tool "${toolId}" requires package "${packageName}" which is not installed.\n\n` +
+            `To install:\n  ${installCmd}\n` +
+            `Or with other package managers:\n` +
+            `  pnpm: ${installHints.pnpm}\n` +
+            `  yarn: ${installHints.yarn}\n` +
+            `  bun: ${installHints.bun}` +
+            envVarsMsg +
+            `\n\nDocs: https://docs.praison.ai/js/${docsSlug}`);
+        this.toolId = toolId;
+        this.packageName = packageName;
+        this.installHints = installHints;
+        this.requiredEnv = requiredEnv;
+        this.docsSlug = docsSlug;
+        this.name = 'MissingDependencyError';
+    }
+}
+exports.MissingDependencyError = MissingDependencyError;
+/**
+ * Error thrown when required environment variable is missing
+ */
+class MissingEnvVarError extends Error {
+    constructor(toolId, envVar, docsSlug) {
+        super(`Tool "${toolId}" requires environment variable "${envVar}" which is not set.\n\n` +
+            `Set it in your environment or .env file:\n  ${envVar}=your_value_here\n\n` +
+            `Docs: https://docs.praison.ai/js/${docsSlug}`);
+        this.toolId = toolId;
+        this.envVar = envVar;
+        this.docsSlug = docsSlug;
+        this.name = 'MissingEnvVarError';
+    }
+}
+exports.MissingEnvVarError = MissingEnvVarError;

package/dist/tools/test.js

@@ -0,0 +1 @@
+"use strict";