/** * AI SDK Tools Registry - Type Definitions * * Standard interfaces for tool registration, execution, and middleware. */ import { PraisonAIError } from '../../errors'; /** * 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; } /** * 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 { /** 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; } /** * Base interface for all PraisonAI tools */ export interface PraisonTool { /** 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; } /** * JSON Schema for tool parameters */ export interface ToolParameterSchema { type: 'object'; properties: Record; required?: string[]; } /** * Individual parameter property schema */ export interface ToolParameterProperty { type: string; description?: string; enum?: string[]; default?: unknown; items?: ToolParameterProperty; properties?: Record; } /** * Middleware function type */ export type ToolMiddleware = (input: unknown, context: ToolExecutionContext, next: () => Promise) => Promise; /** * Before/after hook types */ export interface ToolHooks { beforeToolCall?: (toolName: string, input: unknown, context: ToolExecutionContext) => Promise | void; afterToolCall?: (toolName: string, input: unknown, output: unknown, context: ToolExecutionContext) => Promise | void; onError?: (toolName: string, error: Error, context: ToolExecutionContext) => Promise | void; } /** * Tool factory function type */ export type ToolFactory = (config?: TConfig) => PraisonTool; /** * 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); } /** * Keyword options of `BudgetExceededError` (Python's new-style constructor). * Python parity: praisonaiagents/errors.py:192-202 (`BudgetExceededError.__init__`) */ export interface BudgetExceededErrorOptions { /** What ran out: `"tokens"` (default), `"cost"`, `"time"`, ... */ budgetType?: string; /** The configured ceiling. Recorded in `context.limit` (`null` when unknown). */ limit?: number | null; /** How much was consumed. Recorded in `context.used` (`null` when unknown). */ used?: number | null; agentId?: string; runId?: string; context?: Record; } /** * Budget limits exceeded (tokens, time, cost, ...). Category `"billing"`, * never retryable without intervention. * Python parity: praisonaiagents/errors.py:185-266 (`BudgetExceededError`) * * Two constructor forms, exactly as in Python: * * new BudgetExceededError('Token budget exhausted', { budgetType: 'tokens', limit: 1000, used: 1200 }) * new BudgetExceededError(agentName, totalCost, maxBudget) // legacy, cost-based * * The legacy form derives the message * `Agent '' exceeded budget: $ >= $` (4 decimals), sets * `budgetType` to `"cost"` and uses the agent name as `agentId`. * * Usage: * try { await agent.start("..."); } * catch (e) { * if (e instanceof BudgetExceededError) * console.log(`Agent '${e.agentName}' spent $${e.totalCost} of $${e.maxBudget}`); * } */ export declare class BudgetExceededError extends PraisonAIError { readonly budgetType: string; readonly limit: number | null; readonly used: number | null; /** Legacy alias: the agent name (legacy form) or `agentId` (new form). */ readonly agentName: string; /** Legacy alias of `used`. */ readonly totalCost: number | null; /** Legacy alias of `limit`. */ readonly maxBudget: number | null; constructor(message: string, options?: BudgetExceededErrorOptions); /** Legacy cost-based form: `(agentName, totalCost, maxBudget)`. */ constructor(agentName: string, totalCost: number, maxBudget: number); }