overai 1.4.0

package/dist/ai/telemetry.js

@@ -0,0 +1,311 @@
+"use strict";
+/**
+ * Telemetry - AI SDK v6 Compatible Telemetry
+ *
+ * Provides telemetry settings compatible with AI SDK v6's experimental_telemetry.
+ * Optionally bridges to OpenTelemetry for production observability.
+ */
+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.configureTelemetry = configureTelemetry;
+exports.getTelemetrySettings = getTelemetrySettings;
+exports.enableTelemetry = enableTelemetry;
+exports.disableTelemetry = disableTelemetry;
+exports.isTelemetryEnabled = isTelemetryEnabled;
+exports.initOpenTelemetry = initOpenTelemetry;
+exports.getTracer = getTracer;
+exports.createAISpan = createAISpan;
+exports.withSpan = withSpan;
+exports.createTelemetryMiddleware = createTelemetryMiddleware;
+exports.recordEvent = recordEvent;
+exports.getEvents = getEvents;
+exports.clearEvents = clearEvents;
+exports.createTelemetrySettings = createTelemetrySettings;
+// ============================================================================
+// Global State
+// ============================================================================
+let globalTelemetrySettings = {
+    isEnabled: false,
+    recordInputs: true,
+    recordOutputs: true,
+};
+let otelTracer = null;
+// ============================================================================
+// Configuration Functions
+// ============================================================================
+/**
+ * Configure global telemetry settings.
+ *
+ * @example
+ * ```typescript
+ * configureTelemetry({
+ *   isEnabled: true,
+ *   functionId: 'my-app',
+ *   metadata: { version: '1.0.0' }
+ * });
+ * ```
+ */
+function configureTelemetry(settings) {
+    globalTelemetrySettings = {
+        ...globalTelemetrySettings,
+        ...settings,
+    };
+}
+/**
+ * Get current telemetry settings.
+ */
+function getTelemetrySettings() {
+    return { ...globalTelemetrySettings };
+}
+/**
+ * Enable telemetry globally.
+ */
+function enableTelemetry(options) {
+    globalTelemetrySettings = {
+        ...globalTelemetrySettings,
+        ...options,
+        isEnabled: true,
+    };
+}
+/**
+ * Disable telemetry globally.
+ */
+function disableTelemetry() {
+    globalTelemetrySettings.isEnabled = false;
+}
+/**
+ * Check if telemetry is enabled.
+ */
+function isTelemetryEnabled() {
+    return globalTelemetrySettings.isEnabled ?? false;
+}
+// ============================================================================
+// OpenTelemetry Integration
+// ============================================================================
+/**
+ * Initialize OpenTelemetry integration.
+ *
+ * @example
+ * ```typescript
+ * import { trace } from '@opentelemetry/api';
+ *
+ * initOpenTelemetry({
+ *   tracer: trace.getTracer('praisonai'),
+ *   serviceName: 'my-ai-app'
+ * });
+ * ```
+ */
+async function initOpenTelemetry(options) {
+    if (options?.tracer) {
+        otelTracer = options.tracer;
+        globalTelemetrySettings.tracer = options.tracer;
+        return;
+    }
+    // Try to auto-initialize OpenTelemetry
+    try {
+        const otelApi = await Promise.resolve().then(() => __importStar(require('@opentelemetry/api')));
+        otelTracer = otelApi.trace.getTracer(options?.serviceName || 'praisonai');
+        globalTelemetrySettings.tracer = otelTracer || undefined;
+    }
+    catch {
+        console.warn('⚠️  @opentelemetry/api not installed. Install with:\n' +
+            '   npm install @opentelemetry/api @opentelemetry/sdk-node\n' +
+            '   or: pnpm add @opentelemetry/api @opentelemetry/sdk-node');
+    }
+}
+/**
+ * Get the OpenTelemetry tracer.
+ */
+function getTracer() {
+    return otelTracer;
+}
+// ============================================================================
+// Span Helpers
+// ============================================================================
+/**
+ * Create a span for an AI operation.
+ *
+ * @example
+ * ```typescript
+ * const span = createAISpan('generateText', {
+ *   model: 'gpt-4o',
+ *   provider: 'openai'
+ * });
+ *
+ * try {
+ *   const result = await generateText({ ... });
+ *   span.setAttribute('tokens', result.usage.totalTokens);
+ *   span.setStatus({ code: 'ok' });
+ * } catch (error) {
+ *   span.recordException(error);
+ *   span.setStatus({ code: 'error', message: error.message });
+ * } finally {
+ *   span.end();
+ * }
+ * ```
+ */
+function createAISpan(name, attributes) {
+    if (!globalTelemetrySettings.isEnabled || !otelTracer) {
+        return createNoopSpan();
+    }
+    return otelTracer.startSpan(`ai.${name}`, {
+        attributes: {
+            'ai.operation': name,
+            ...attributes,
+        },
+        kind: 'client',
+    });
+}
+/**
+ * Execute a function within a span.
+ */
+async function withSpan(name, attributes, fn) {
+    const span = createAISpan(name, attributes);
+    try {
+        const result = await fn(span);
+        span.setStatus({ code: 'ok' });
+        return result;
+    }
+    catch (error) {
+        span.recordException(error);
+        span.setStatus({ code: 'error', message: error.message });
+        throw error;
+    }
+    finally {
+        span.end();
+    }
+}
+// ============================================================================
+// Noop Span (when telemetry is disabled)
+// ============================================================================
+function createNoopSpan() {
+    return {
+        setAttribute: function () { return this; },
+        setAttributes: function () { return this; },
+        addEvent: function () { return this; },
+        setStatus: function () { return this; },
+        end: function () { },
+        recordException: function () { },
+        isRecording: function () { return false; },
+    };
+}
+// ============================================================================
+// Telemetry Middleware
+// ============================================================================
+/**
+ * Create middleware that adds telemetry to AI SDK calls.
+ */
+function createTelemetryMiddleware(settings) {
+    const mergedSettings = {
+        ...globalTelemetrySettings,
+        ...settings,
+    };
+    return {
+        transformParams: async ({ params }) => {
+            if (!mergedSettings.isEnabled) {
+                return params;
+            }
+            return {
+                ...params,
+                experimental_telemetry: {
+                    isEnabled: true,
+                    recordInputs: mergedSettings.recordInputs,
+                    recordOutputs: mergedSettings.recordOutputs,
+                    functionId: mergedSettings.functionId,
+                    metadata: mergedSettings.metadata,
+                    tracer: mergedSettings.tracer,
+                },
+            };
+        },
+    };
+}
+const eventBuffer = [];
+const MAX_BUFFER_SIZE = 1000;
+/**
+ * Record a telemetry event.
+ */
+function recordEvent(name, attributes = {}) {
+    if (!globalTelemetrySettings.isEnabled) {
+        return;
+    }
+    const event = {
+        name,
+        timestamp: Date.now(),
+        attributes: {
+            ...attributes,
+            functionId: globalTelemetrySettings.functionId,
+            ...globalTelemetrySettings.metadata,
+        },
+    };
+    eventBuffer.push(event);
+    // Prevent memory leak
+    if (eventBuffer.length > MAX_BUFFER_SIZE) {
+        eventBuffer.shift();
+    }
+}
+/**
+ * Get recorded events.
+ */
+function getEvents() {
+    return [...eventBuffer];
+}
+/**
+ * Clear recorded events.
+ */
+function clearEvents() {
+    eventBuffer.length = 0;
+}
+// ============================================================================
+// AI SDK Telemetry Helpers
+// ============================================================================
+/**
+ * Create telemetry settings for AI SDK calls.
+ */
+function createTelemetrySettings(options) {
+    if (!globalTelemetrySettings.isEnabled) {
+        return undefined;
+    }
+    return {
+        isEnabled: true,
+        functionId: options?.functionId || globalTelemetrySettings.functionId,
+        metadata: {
+            ...globalTelemetrySettings.metadata,
+            ...options?.metadata,
+        },
+        recordInputs: options?.recordInputs ?? globalTelemetrySettings.recordInputs,
+        recordOutputs: options?.recordOutputs ?? globalTelemetrySettings.recordOutputs,
+        tracer: globalTelemetrySettings.tracer,
+    };
+}

package/dist/ai/tool-approval.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Tool Approval - Human-in-the-Loop Tool Execution
+ *
+ * Provides utilities for requiring human approval before tool execution.
+ * Compatible with AI SDK v6's needsApproval pattern.
+ */
+import { EventEmitter } from 'events';
+/**
+ * Tool approval configuration.
+ */
+export interface ToolApprovalConfig {
+    /** Tool name */
+    name: string;
+    /** Tool description */
+    description?: string;
+    /** Whether approval is needed - can be boolean or async function */
+    needsApproval?: boolean | ((input: unknown) => boolean | Promise<boolean>);
+    /** Timeout for approval in ms (default: 5 minutes) */
+    approvalTimeout?: number;
+    /** Auto-approve patterns (regex or function) */
+    autoApprove?: RegExp | ((input: unknown) => boolean);
+    /** Auto-deny patterns (regex or function) */
+    autoDeny?: RegExp | ((input: unknown) => boolean);
+}
+/**
+ * Tool approval request.
+ */
+export interface ToolApprovalRequest {
+    /** Unique ID for this approval request */
+    requestId: string;
+    /** Tool invocation ID */
+    toolInvocationId: string;
+    /** Tool name */
+    toolName: string;
+    /** Tool input arguments */
+    input: unknown;
+    /** Timestamp when request was created */
+    timestamp: number;
+    /** Optional context about why approval is needed */
+    reason?: string;
+}
+/**
+ * Tool approval response.
+ */
+export interface ToolApprovalResponse {
+    /** Request ID being responded to */
+    requestId: string;
+    /** Whether the tool call is approved */
+    approved: boolean;
+    /** Optional message from approver */
+    message?: string;
+    /** Who approved/denied (for audit) */
+    approver?: string;
+    /** Timestamp of response */
+    timestamp: number;
+}
+/**
+ * Approval state for tracking pending approvals.
+ */
+export type ApprovalState = 'pending' | 'approved' | 'denied' | 'timeout' | 'auto-approved' | 'auto-denied';
+/**
+ * Approval handler function type.
+ */
+export type ApprovalHandler = (request: ToolApprovalRequest) => Promise<boolean>;
+/**
+ * Manages tool approval requests and responses.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const manager = new ApprovalManager();
+ *
+ * // Register a handler
+ * manager.onApprovalRequest(async (request) => {
+ *   console.log(`Tool ${request.toolName} wants to run with:`, request.input);
+ *   return await askUser(`Approve ${request.toolName}?`);
+ * });
+ *
+ * // Request approval
+ * const approved = await manager.requestApproval({
+ *   toolName: 'deleteFile',
+ *   input: { path: '/important/file.txt' }
+ * });
+ * ```
+ */
+export declare class ApprovalManager extends EventEmitter {
+    private pendingRequests;
+    private handlers;
+    private defaultTimeout;
+    private autoApprovePatterns;
+    private autoDenyPatterns;
+    constructor(options?: {
+        defaultTimeout?: number;
+    });
+    /**
+     * Register an approval handler.
+     */
+    onApprovalRequest(handler: ApprovalHandler): void;
+    /**
+     * Add auto-approve pattern.
+     */
+    addAutoApprove(toolName: string | RegExp, inputPattern?: RegExp | ((input: unknown) => boolean)): void;
+    /**
+     * Add auto-deny pattern.
+     */
+    addAutoDeny(toolName: string | RegExp, inputPattern?: RegExp | ((input: unknown) => boolean)): void;
+    /**
+     * Check if a tool call should be auto-approved.
+     */
+    private checkAutoApprove;
+    /**
+     * Check if a tool call should be auto-denied.
+     */
+    private checkAutoDeny;
+    /**
+     * Request approval for a tool call.
+     */
+    requestApproval(options: {
+        toolInvocationId?: string;
+        toolName: string;
+        input: unknown;
+        reason?: string;
+        timeout?: number;
+    }): Promise<boolean>;
+    /**
+     * Respond to an approval request.
+     */
+    respond(response: ToolApprovalResponse): void;
+    /**
+     * Get all pending approval requests.
+     */
+    getPendingRequests(): ToolApprovalRequest[];
+    /**
+     * Cancel a pending request.
+     */
+    cancel(requestId: string): void;
+    /**
+     * Cancel all pending requests.
+     */
+    cancelAll(): void;
+}
+/**
+ * Get the global approval manager.
+ */
+export declare function getApprovalManager(): ApprovalManager;
+/**
+ * Set a custom global approval manager.
+ */
+export declare function setApprovalManager(manager: ApprovalManager): void;
+/**
+ * Wrap a tool with approval requirement.
+ *
+ * @example
+ * ```typescript
+ * const deleteFile = withApproval({
+ *   name: 'deleteFile',
+ *   needsApproval: true,
+ *   execute: async (args) => {
+ *     await fs.unlink(args.path);
+ *     return { success: true };
+ *   }
+ * });
+ * ```
+ */
+export declare function withApproval<TInput, TOutput>(options: {
+    name: string;
+    description?: string;
+    needsApproval?: boolean | ((input: TInput) => boolean | Promise<boolean>);
+    execute: (input: TInput) => Promise<TOutput>;
+    onDenied?: (input: TInput) => TOutput | Promise<TOutput>;
+    approvalManager?: ApprovalManager;
+}): (input: TInput) => Promise<TOutput>;
+/**
+ * Error thrown when tool approval is denied.
+ */
+export declare class ToolApprovalDeniedError extends Error {
+    readonly toolName: string;
+    readonly input: unknown;
+    constructor(toolName: string, input: unknown);
+}
+/**
+ * Error thrown when tool approval times out.
+ */
+export declare class ToolApprovalTimeoutError extends Error {
+    readonly toolName: string;
+    readonly input: unknown;
+    constructor(toolName: string, input: unknown);
+}
+/**
+ * Create a CLI-based approval prompt.
+ *
+ * @example
+ * ```typescript
+ * const manager = getApprovalManager();
+ * manager.onApprovalRequest(createCLIApprovalPrompt());
+ * ```
+ */
+export declare function createCLIApprovalPrompt(options?: {
+    /** Custom prompt message */
+    promptMessage?: (request: ToolApprovalRequest) => string;
+    /** Input stream (default: process.stdin) */
+    input?: NodeJS.ReadableStream;
+    /** Output stream (default: process.stdout) */
+    output?: NodeJS.WritableStream;
+}): ApprovalHandler;
+/**
+ * Common dangerous patterns that should require approval.
+ */
+export declare const DANGEROUS_PATTERNS: {
+    /** File deletion patterns */
+    fileDelete: RegExp;
+    /** Database destructive patterns */
+    dbDestructive: RegExp;
+    /** Shell command patterns */
+    shellDangerous: RegExp;
+    /** Network patterns */
+    networkSensitive: RegExp;
+};
+/**
+ * Check if input matches any dangerous pattern.
+ */
+export declare function isDangerous(input: unknown): boolean;
+/**
+ * Create a needsApproval function that checks for dangerous patterns.
+ */
+export declare function createDangerousPatternChecker(additionalPatterns?: RegExp[]): (input: unknown) => boolean;