@agentforge/core 0.11.7 → 0.12.0

package/dist/index.d.ts

@@ -1559,7 +1559,7 @@ declare function createToolExecutor(config?: ToolExecutorConfig): {
  * Tool Lifecycle Management - Manage tool initialization, cleanup, and resources
  * @module tools/lifecycle
  */
-interface HealthCheckResult {
+interface ToolHealthCheckResult {
     healthy: boolean;
     error?: string;
     metadata?: Record<string, any>;
@@ -1570,7 +1570,7 @@ interface ManagedToolConfig<TContext = any, TInput = any, TOutput = any> {
     initialize?: (this: ManagedTool<TContext, TInput, TOutput>) => Promise<void>;
     execute: (this: ManagedTool<TContext, TInput, TOutput>, input: TInput) => Promise<TOutput>;
     cleanup?: (this: ManagedTool<TContext, TInput, TOutput>) => Promise<void>;
-    healthCheck?: (this: ManagedTool<TContext, TInput, TOutput>) => Promise<HealthCheckResult>;
+    healthCheck?: (this: ManagedTool<TContext, TInput, TOutput>) => Promise<ToolHealthCheckResult>;
     context?: TContext;
     autoCleanup?: boolean;
     healthCheckInterval?: number;
@@ -1581,7 +1581,7 @@ interface ManagedToolStats {
     successfulExecutions: number;
     failedExecutions: number;
     lastExecutionTime?: number;
-    lastHealthCheck?: HealthCheckResult;
+    lastHealthCheck?: ToolHealthCheckResult;
     lastHealthCheckTime?: number;
 }
 /**
@@ -1628,7 +1628,7 @@ declare class ManagedTool<TContext = any, TInput = any, TOutput = any> {
     /**
      * Run health check
      */
-    healthCheck(): Promise<HealthCheckResult>;
+    healthCheck(): Promise<ToolHealthCheckResult>;
     /**
      * Get tool statistics
      */
@@ -5157,4 +5157,324 @@ declare class CircuitBreaker {
 }
 declare function createCircuitBreaker(options: CircuitBreakerOptions): CircuitBreaker;
 
-export { AgentError, type AgentResumedEventData, type AgentWaitingEventData, type AggregateNode, type AnyInterrupt, type ApprovalRequiredInterrupt, type BackoffStrategy, type BatchOptions, BatchProcessor, type BatchProcessorOptions, type BatchStats, type CacheKeyGenerator, type CachingOptions, type CheckInterruptOptions, type CheckpointHistoryOptions, type CheckpointerOptions, type ChunkOptions, CircuitBreaker, type CircuitBreakerOptions, type CircuitBreakerStats, type CircuitState, type ComposeGraphsOptions, type ComposeOptions, type ComposeToolConfig, type ComposedTool, type ConcurrencyOptions, type ConditionalConfig, type ConditionalRouter, type ConditionalRouterConfig, ConnectionPool, type ConnectionPoolOptions, type ConversationConfig, type CustomInterrupt, type DatabaseConfig, type DatabaseConnection, DatabasePool, type DatabasePoolOptions, type DevelopmentPresetOptions, type ErrorContext, type ErrorHandlerOptions, type ErrorReporter, type ErrorReporterOptions, type EventHandler, type EvictionStrategy, type ExecutionMetrics, type HealthCheckConfig, type HealthCheckResult, type HttpClient, type HttpConfig, HttpPool, type HttpPoolConfig, type HttpPoolOptions, type HttpResponse, type HumanInLoopEventData, type HumanInLoopEventType, type HumanRequest, type HumanRequestEventData, type HumanRequestInterrupt, type HumanRequestPriority, type HumanRequestStatus, type HumanResponseEventData, type InterruptData, type InterruptEventData, type InterruptType, type LangSmithConfig, type LogEntry, LogLevel, type Logger, type LoggerOptions, type LoggingOptions, ManagedTool, type ManagedToolConfig, type ManagedToolStats, MemoryManager, type MemoryManagerOptions, type MemoryStats, type MetricEntry, MetricType, type Metrics, type MetricsNodeOptions, type Middleware, MiddlewareChain, type MiddlewareContext, type MiddlewareFactory, type MiddlewareMetadata, type MiddlewareWithMetadata, MissingDescriptionError, type MockToolConfig, type MockToolResponse, type NodeFunction, type NodeFunctionWithContext, type ParallelNode, type ParallelWorkflowConfig, type ParallelWorkflowOptions, type PoolConfig, type PoolStats, type Priority$1 as Priority, type ProductionPresetOptions, type Progress, type ProgressTracker, type ProgressTrackerOptions, type PromptOptions, type RateLimitOptions, type RateLimitStrategy, type ReducerFunction, RegistryEvent, type RequestConfig, type ResumeCommand, type ResumeEventData, type ResumeOptions, type RetryOptions, type RetryPolicy, type RouteCondition, type RouteMap, type RouteName, type SSEEvent, type SSEFormatter, type SSEFormatterOptions, type SequentialNode, type SequentialWorkflowOptions, type SimpleMiddleware, type SqliteCheckpointerOptions, type StateChannelConfig, type SubgraphBuilder, type TestingPresetOptions, type ThreadConfig, type ThreadInfo, type ThreadStatus, type ThrottleOptions, TimeoutError, type TimeoutOptions, type Timer, type Tool, type BackoffStrategy$1 as ToolBackoffStrategy, ToolBuilder, ToolCategory, ToolCategorySchema, type ToolExample, ToolExampleSchema, type ToolExecution, type ToolExecutorConfig, type ToolInvocation, type ToolMetadata, ToolMetadataSchema, ToolNameSchema, ToolRegistry, type ToolRelations, ToolRelationsSchema, type ToolSimulatorConfig, type TracingOptions, type ValidationErrorHandler, type ValidationMode, type ValidationOptions, type ValidatorFunction, type WebSocketHandlerOptions, type WebSocketMessage, batch, broadcast, cache, chain, chunk, clearThread, collect, compose, composeGraphs, composeTool, composeWithOptions, conditional, configureLangSmith, createApprovalRequiredInterrupt, createBatchProcessor, createBinaryRouter, createCircuitBreaker, createConditionalRouter, createConnectionPool, createConversationConfig, createCustomInterrupt, createDatabasePool, createErrorReporter, createHeartbeat, createHttpPool, createHumanRequestInterrupt, createLogger, createManagedTool, createMemoryCheckpointer, createMemoryManager, createMessage, createMetrics, createMiddlewareContext, createMockTool, createMultiRouter, createParallelWorkflow, createProgressTracker, createSSEFormatter, createSequentialWorkflow, createSharedCache, createSharedConcurrencyController, createSharedRateLimiter, createSqliteCheckpointer, createStateAnnotation, createSubgraph, createThreadConfig, createTool, createToolExecutor, createToolSimulator, createToolUnsafe, createWebSocketHandler, development, filter, formatAgentResumedEvent, formatAgentWaitingEvent, formatHumanRequestEvent, formatHumanResponseEvent, formatInterruptEvent, formatResumeEvent, generateThreadId, getCheckpointHistory, getLangSmithConfig, getLatestCheckpoint, getMissingDescriptions, getThreadStatus, getToolDescription, getToolJsonSchema, isApprovalRequiredInterrupt, isCustomInterrupt, isHumanRequestInterrupt, isMemoryCheckpointer, isTracingEnabled, map, merge, mergeState, parallel, parseSSEEvent, presets, production, reduce, retry, safeValidateSchemaDescriptions, sendMessage, sequential, sequentialBuilder, take, testing, throttle, timeout, toLangChainTool, toLangChainTools, toolBuilder, validateSchemaDescriptions, validateState, validateTool, validateToolMetadata, validateToolName, withCache, withConcurrency, withErrorHandler, withLogging, withMetrics, withRateLimit, withRetry, withTimeout, withTracing, withValidation };
+/**
+ * Health check system for production monitoring
+ */
+type HealthStatus = 'healthy' | 'unhealthy' | 'degraded';
+interface HealthCheckResult {
+    healthy: boolean;
+    status?: HealthStatus;
+    message?: string;
+    error?: string;
+    timestamp?: number;
+    duration?: number;
+    metadata?: Record<string, any>;
+}
+interface HealthCheck {
+    (): Promise<HealthCheckResult>;
+}
+interface HealthCheckerOptions {
+    checks: Record<string, HealthCheck>;
+    timeout?: number;
+    interval?: number;
+    onHealthChange?: (health: HealthReport) => void;
+    onCheckFail?: (name: string, error: Error) => void;
+}
+interface HealthReport {
+    healthy: boolean;
+    status: HealthStatus;
+    timestamp: number;
+    checks: Record<string, HealthCheckResult>;
+    uptime: number;
+}
+declare class HealthChecker {
+    private options;
+    private checkTimer?;
+    private lastReport?;
+    private startTime;
+    private running;
+    constructor(options: HealthCheckerOptions);
+    start(): void;
+    stop(): void;
+    getHealth(): Promise<HealthReport>;
+    getLiveness(): Promise<HealthCheckResult>;
+    getReadiness(): Promise<HealthReport>;
+    private runChecks;
+}
+declare function createHealthChecker(options: HealthCheckerOptions): HealthChecker;
+
+/**
+ * Performance profiling for execution monitoring
+ */
+interface ProfilerOptions {
+    enabled?: boolean;
+    sampleRate?: number;
+    includeMemory?: boolean;
+    includeStack?: boolean;
+    maxSamples?: number;
+}
+interface ProfileSample {
+    timestamp: number;
+    duration: number;
+    memory?: {
+        heapUsed: number;
+        heapTotal: number;
+        external: number;
+    };
+    stack?: string;
+}
+interface ProfileStats {
+    calls: number;
+    totalTime: number;
+    avgTime: number;
+    minTime: number;
+    maxTime: number;
+    p50: number;
+    p95: number;
+    p99: number;
+    memory?: {
+        avgHeapUsed: number;
+        maxHeapUsed: number;
+        minHeapUsed: number;
+    };
+    samples: ProfileSample[];
+}
+interface ProfileReport {
+    [key: string]: ProfileStats;
+}
+declare class Profiler {
+    private profiles;
+    private enabled;
+    private sampleRate;
+    private includeMemory;
+    private includeStack;
+    private maxSamples;
+    constructor(options?: ProfilerOptions);
+    profile<TArgs extends any[], TReturn>(name: string, fn: (...args: TArgs) => Promise<TReturn>): (...args: TArgs) => Promise<TReturn>;
+    wrap<T>(name: string, promise: Promise<T>): Promise<T>;
+    private recordSample;
+    getReport(): ProfileReport;
+    private percentile;
+    reset(name?: string): void;
+    export(path: string): void;
+}
+declare function createProfiler(options?: ProfilerOptions): Profiler;
+
+/**
+ * Alert system for production monitoring
+ */
+type AlertSeverity = 'info' | 'warning' | 'error' | 'critical';
+interface Alert {
+    name: string;
+    severity: AlertSeverity;
+    message: string;
+    timestamp?: number;
+    data?: Record<string, any>;
+}
+interface AlertChannel {
+    type: string;
+    config: Record<string, any>;
+}
+interface AlertRule {
+    name: string;
+    condition: (metrics: any) => boolean;
+    severity: AlertSeverity;
+    channels: string[];
+    throttle?: number;
+    message?: string;
+}
+interface AlertManagerOptions {
+    channels: Record<string, AlertChannel>;
+    rules?: AlertRule[];
+    onAlert?: (alert: Alert) => void;
+}
+declare class AlertManager {
+    private options;
+    private lastAlertTime;
+    private monitorTimer?;
+    private running;
+    constructor(options: AlertManagerOptions);
+    start(metrics?: () => any, interval?: number): void;
+    stop(): void;
+    alert(alert: Alert): Promise<void>;
+    private checkRules;
+    private isThrottled;
+    sendToChannel(channelName: string, alert: Alert): Promise<void>;
+    getAlertHistory(name?: string, limit?: number): Alert[];
+    clearAlertHistory(name?: string): void;
+}
+declare function createAlertManager(options: AlertManagerOptions): AlertManager;
+
+/**
+ * Audit logging for compliance and tracking
+ */
+interface AuditLogEntry {
+    id?: string;
+    userId: string;
+    action: string;
+    resource: string;
+    timestamp?: number;
+    input?: any;
+    output?: any;
+    metadata?: Record<string, any>;
+    success?: boolean;
+    error?: string;
+}
+interface AuditLogQuery {
+    userId?: string;
+    action?: string;
+    resource?: string;
+    startDate?: Date;
+    endDate?: Date;
+    limit?: number;
+    offset?: number;
+}
+interface AuditLoggerOptions {
+    storage?: {
+        type: 'memory' | 'database' | 'file';
+        config?: Record<string, any>;
+    };
+    retention?: {
+        days: number;
+        autoCleanup?: boolean;
+    };
+    fields?: {
+        userId?: boolean;
+        action?: boolean;
+        resource?: boolean;
+        timestamp?: boolean;
+        ip?: boolean;
+        userAgent?: boolean;
+        input?: boolean;
+        output?: boolean;
+    };
+    onLog?: (entry: AuditLogEntry) => void;
+}
+declare class AuditLogger {
+    private options;
+    private logs;
+    private cleanupTimer?;
+    constructor(options?: AuditLoggerOptions);
+    log(entry: AuditLogEntry): Promise<void>;
+    query(query?: AuditLogQuery): Promise<AuditLogEntry[]>;
+    export(path: string, options?: {
+        format?: 'json' | 'csv';
+        startDate?: Date;
+        endDate?: Date;
+    }): Promise<void>;
+    private convertToCSV;
+    private startCleanup;
+    private cleanup;
+    private generateId;
+    stop(): void;
+}
+declare function createAuditLogger(options?: AuditLoggerOptions): AuditLogger;
+
+/**
+ * Prompt Template Loader
+ *
+ * Utility for loading and rendering prompt templates from .md files.
+ * Supports variable substitution and conditional blocks.
+ *
+ * SECURITY: This module includes protection against prompt injection attacks
+ * by sanitizing variable values before substitution.
+ */
+/**
+ * Options for rendering templates with security controls
+ */
+interface RenderTemplateOptions {
+    /**
+     * Variables from trusted sources (config files, hardcoded values)
+     * These will NOT be sanitized
+     */
+    trustedVariables?: Record<string, any>;
+    /**
+     * Variables from untrusted sources (user input, API calls, databases)
+     * These WILL be sanitized to prevent prompt injection
+     */
+    untrustedVariables?: Record<string, any>;
+}
+/**
+ * Sanitize a value to prevent prompt injection attacks
+ *
+ * Protections:
+ * - Removes markdown headers (prevents structure hijacking)
+ * - Removes newlines (prevents multi-line injection)
+ * - Limits length (prevents prompt bloat)
+ *
+ * @param value - The value to sanitize
+ * @returns Sanitized string safe for use in prompts
+ */
+declare function sanitizeValue(value: any): string;
+/**
+ * Render a template string with variable substitution
+ *
+ * Supports:
+ * - Simple variables: {{variableName}}
+ * - Conditional blocks: {{#if variableName}}...{{/if}}
+ *
+ * SECURITY: Distinguishes between trusted and untrusted variables.
+ * - Trusted variables (from config) are used as-is
+ * - Untrusted variables (from user input) are sanitized
+ *
+ * @param template - Template string with {{variable}} placeholders
+ * @param options - Variables and security options
+ * @returns Rendered template string
+ *
+ * @example
+ * ```typescript
+ * // Safe: Trusted variables from config
+ * const result = renderTemplate(template, {
+ *   trustedVariables: {
+ *     companyName: 'Acme Corp',  // From config file
+ *     premium: true
+ *   }
+ * });
+ *
+ * // Safe: Untrusted variables are sanitized
+ * const result = renderTemplate(template, {
+ *   untrustedVariables: {
+ *     userName: req.body.name,  // User input - will be sanitized
+ *   }
+ * });
+ *
+ * // Mixed: Some trusted, some untrusted
+ * const result = renderTemplate(template, {
+ *   trustedVariables: {
+ *     companyName: 'Acme Corp',  // From config
+ *   },
+ *   untrustedVariables: {
+ *     userName: req.body.name,  // User input
+ *   }
+ * });
+ * ```
+ */
+declare function renderTemplate(template: string, options: RenderTemplateOptions | Record<string, any>): string;
+/**
+ * Load and render a prompt template from a .md file
+ *
+ * Looks for prompts in a `prompts/` directory relative to the caller's location.
+ *
+ * @param promptName - Name of the prompt file (without .md extension)
+ * @param options - Variables and security options
+ * @param promptsDir - Optional custom prompts directory path
+ * @returns Rendered prompt string
+ *
+ * @example
+ * ```typescript
+ * // Backwards compatible: all variables treated as trusted
+ * loadPrompt('system', { companyName: 'Acme' });
+ *
+ * // Explicit: separate trusted and untrusted
+ * loadPrompt('system', {
+ *   trustedVariables: { companyName: 'Acme' },
+ *   untrustedVariables: { userName: userInput }
+ * });
+ *
+ * // Custom prompts directory
+ * loadPrompt('system', { companyName: 'Acme' }, '/path/to/prompts');
+ * ```
+ */
+declare function loadPrompt(promptName: string, options?: RenderTemplateOptions | Record<string, any>, promptsDir?: string): string;
+
+export { AgentError, type AgentResumedEventData, type AgentWaitingEventData, type AggregateNode, type Alert, type AlertChannel, AlertManager, type AlertManagerOptions, type AlertRule, type AlertSeverity, type AnyInterrupt, type ApprovalRequiredInterrupt, type AuditLogEntry, type AuditLogQuery, AuditLogger, type AuditLoggerOptions, type BackoffStrategy, type BatchOptions, BatchProcessor, type BatchProcessorOptions, type BatchStats, type CacheKeyGenerator, type CachingOptions, type CheckInterruptOptions, type CheckpointHistoryOptions, type CheckpointerOptions, type ChunkOptions, CircuitBreaker, type CircuitBreakerOptions, type CircuitBreakerStats, type CircuitState, type ComposeGraphsOptions, type ComposeOptions, type ComposeToolConfig, type ComposedTool, type ConcurrencyOptions, type ConditionalConfig, type ConditionalRouter, type ConditionalRouterConfig, ConnectionPool, type ConnectionPoolOptions, type ConversationConfig, type CustomInterrupt, type DatabaseConfig, type DatabaseConnection, DatabasePool, type DatabasePoolOptions, type DevelopmentPresetOptions, type ErrorContext, type ErrorHandlerOptions, type ErrorReporter, type ErrorReporterOptions, type EventHandler, type EvictionStrategy, type ExecutionMetrics, type HealthCheck, type HealthCheckConfig, type HealthCheckResult, HealthChecker, type HealthCheckerOptions, type HealthReport, type HealthStatus, type HttpClient, type HttpConfig, HttpPool, type HttpPoolConfig, type HttpPoolOptions, type HttpResponse, type HumanInLoopEventData, type HumanInLoopEventType, type HumanRequest, type HumanRequestEventData, type HumanRequestInterrupt, type HumanRequestPriority, type HumanRequestStatus, type HumanResponseEventData, type InterruptData, type InterruptEventData, type InterruptType, type LangSmithConfig, type LogEntry, LogLevel, type Logger, type LoggerOptions, type LoggingOptions, ManagedTool, type ManagedToolConfig, type ManagedToolStats, MemoryManager, type MemoryManagerOptions, type MemoryStats, type MetricEntry, MetricType, type Metrics, type MetricsNodeOptions, type Middleware, MiddlewareChain, type MiddlewareContext, type MiddlewareFactory, type MiddlewareMetadata, type MiddlewareWithMetadata, MissingDescriptionError, type MockToolConfig, type MockToolResponse, type NodeFunction, type NodeFunctionWithContext, type ParallelNode, type ParallelWorkflowConfig, type ParallelWorkflowOptions, type PoolConfig, type PoolStats, type Priority$1 as Priority, type ProductionPresetOptions, type ProfileReport, type ProfileSample, type ProfileStats, Profiler, type ProfilerOptions, type Progress, type ProgressTracker, type ProgressTrackerOptions, type PromptOptions, type RateLimitOptions, type RateLimitStrategy, type ReducerFunction, RegistryEvent, type RenderTemplateOptions, type RequestConfig, type ResumeCommand, type ResumeEventData, type ResumeOptions, type RetryOptions, type RetryPolicy, type RouteCondition, type RouteMap, type RouteName, type SSEEvent, type SSEFormatter, type SSEFormatterOptions, type SequentialNode, type SequentialWorkflowOptions, type SimpleMiddleware, type SqliteCheckpointerOptions, type StateChannelConfig, type SubgraphBuilder, type TestingPresetOptions, type ThreadConfig, type ThreadInfo, type ThreadStatus, type ThrottleOptions, TimeoutError, type TimeoutOptions, type Timer, type Tool, type BackoffStrategy$1 as ToolBackoffStrategy, ToolBuilder, ToolCategory, ToolCategorySchema, type ToolExample, ToolExampleSchema, type ToolExecution, type ToolExecutorConfig, type ToolHealthCheckResult, type ToolInvocation, type ToolMetadata, ToolMetadataSchema, ToolNameSchema, ToolRegistry, type ToolRelations, ToolRelationsSchema, type ToolSimulatorConfig, type TracingOptions, type ValidationErrorHandler, type ValidationMode, type ValidationOptions, type ValidatorFunction, type WebSocketHandlerOptions, type WebSocketMessage, batch, broadcast, cache, chain, chunk, clearThread, collect, compose, composeGraphs, composeTool, composeWithOptions, conditional, configureLangSmith, createAlertManager, createApprovalRequiredInterrupt, createAuditLogger, createBatchProcessor, createBinaryRouter, createCircuitBreaker, createConditionalRouter, createConnectionPool, createConversationConfig, createCustomInterrupt, createDatabasePool, createErrorReporter, createHealthChecker, createHeartbeat, createHttpPool, createHumanRequestInterrupt, createLogger, createManagedTool, createMemoryCheckpointer, createMemoryManager, createMessage, createMetrics, createMiddlewareContext, createMockTool, createMultiRouter, createParallelWorkflow, createProfiler, createProgressTracker, createSSEFormatter, createSequentialWorkflow, createSharedCache, createSharedConcurrencyController, createSharedRateLimiter, createSqliteCheckpointer, createStateAnnotation, createSubgraph, createThreadConfig, createTool, createToolExecutor, createToolSimulator, createToolUnsafe, createWebSocketHandler, development, filter, formatAgentResumedEvent, formatAgentWaitingEvent, formatHumanRequestEvent, formatHumanResponseEvent, formatInterruptEvent, formatResumeEvent, generateThreadId, getCheckpointHistory, getLangSmithConfig, getLatestCheckpoint, getMissingDescriptions, getThreadStatus, getToolDescription, getToolJsonSchema, isApprovalRequiredInterrupt, isCustomInterrupt, isHumanRequestInterrupt, isMemoryCheckpointer, isTracingEnabled, loadPrompt, map, merge, mergeState, parallel, parseSSEEvent, presets, production, reduce, renderTemplate, retry, safeValidateSchemaDescriptions, sanitizeValue, sendMessage, sequential, sequentialBuilder, take, testing, throttle, timeout, toLangChainTool, toLangChainTools, toolBuilder, validateSchemaDescriptions, validateState, validateTool, validateToolMetadata, validateToolName, withCache, withConcurrency, withErrorHandler, withLogging, withMetrics, withRateLimit, withRetry, withTimeout, withTracing, withValidation };