@agentforge/core 0.11.6 → 0.11.7

package/dist/index.d.ts

@@ -1507,7 +1507,7 @@ declare class ToolRegistry {
  * Tool Executor - Async tool execution with resource management
  * @module tools/executor
  */
-type Priority = 'low' | 'normal' | 'high' | 'critical';
+type Priority$1 = 'low' | 'normal' | 'high' | 'critical';
 type BackoffStrategy$1 = 'linear' | 'exponential' | 'fixed';
 interface RetryPolicy {
     maxAttempts: number;
@@ -1520,7 +1520,7 @@ interface ToolExecutorConfig {
     maxConcurrent?: number;
     timeout?: number;
     retryPolicy?: RetryPolicy;
-    priorityFn?: (tool: any) => Priority;
+    priorityFn?: (tool: any) => Priority$1;
     onExecutionStart?: (tool: any, input: any) => void;
     onExecutionComplete?: (tool: any, input: any, result: any, duration: number) => void;
     onExecutionError?: (tool: any, input: any, error: Error, duration: number) => void;
@@ -1528,7 +1528,7 @@ interface ToolExecutorConfig {
 interface ToolExecution {
     tool: any;
     input: any;
-    priority?: Priority;
+    priority?: Priority$1;
 }
 interface ExecutionMetrics {
     totalExecutions: number;
@@ -1536,14 +1536,14 @@ interface ExecutionMetrics {
     failedExecutions: number;
     totalDuration: number;
     averageDuration: number;
-    byPriority: Record<Priority, number>;
+    byPriority: Record<Priority$1, number>;
 }
 /**
  * Create a tool executor with resource management
  */
 declare function createToolExecutor(config?: ToolExecutorConfig): {
     execute: (tool: any, input: any, options?: {
-        priority?: Priority;
+        priority?: Priority$1;
     }) => Promise<any>;
     executeParallel: (executions: ToolExecution[]) => Promise<any[]>;
     getMetrics: () => ExecutionMetrics;
@@ -3339,6 +3339,346 @@ interface TracingOptions {
  */
 declare function withTracing<State>(node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>, options: TracingOptions): (state: State) => Promise<State | Partial<State>>;
 
+/**
+ * Caching Middleware for LangGraph Nodes
+ *
+ * Provides caching capabilities with TTL, LRU eviction, and custom key generation.
+ */
+
+/**
+ * Cache key generator function
+ */
+type CacheKeyGenerator<State> = (state: State) => string;
+/**
+ * Cache eviction strategy
+ */
+type EvictionStrategy = 'lru' | 'lfu' | 'fifo';
+/**
+ * Options for caching middleware
+ */
+interface CachingOptions<State> {
+    /**
+     * Time-to-live in milliseconds
+     * @default 3600000 (1 hour)
+     */
+    ttl?: number;
+    /**
+     * Maximum number of cache entries
+     * @default 100
+     */
+    maxSize?: number;
+    /**
+     * Eviction strategy when cache is full
+     * @default 'lru'
+     */
+    evictionStrategy?: EvictionStrategy;
+    /**
+     * Custom cache key generator
+     * @default JSON.stringify
+     */
+    keyGenerator?: CacheKeyGenerator<State>;
+    /**
+     * Whether to cache errors
+     * @default false
+     */
+    cacheErrors?: boolean;
+    /**
+     * Optional callback when cache hit occurs
+     */
+    onCacheHit?: (key: string, value: State | Partial<State>) => void;
+    /**
+     * Optional callback when cache miss occurs
+     */
+    onCacheMiss?: (key: string) => void;
+    /**
+     * Optional callback when cache entry is evicted
+     */
+    onEviction?: (key: string, value: State | Partial<State>) => void;
+}
+/**
+ * Wraps a node function with caching logic.
+ *
+ * @example
+ * ```typescript
+ * const cachedNode = withCache(expensiveNode, {
+ *   ttl: 3600000, // 1 hour
+ *   maxSize: 100,
+ *   evictionStrategy: 'lru',
+ *   keyGenerator: (state) => state.userId,
+ *   onCacheHit: (key) => console.log('Cache hit:', key),
+ * });
+ *
+ * graph.addNode('cached', cachedNode);
+ * ```
+ *
+ * @param node - The node function to wrap
+ * @param options - Caching configuration options
+ * @returns A wrapped node function with caching
+ */
+declare function withCache<State>(node: NodeFunction<State>, options?: CachingOptions<State>): NodeFunction<State>;
+/**
+ * Create a cache instance that can be shared across multiple nodes
+ */
+declare function createSharedCache<State>(options?: Omit<CachingOptions<State>, 'keyGenerator'>): {
+    withCache: (node: NodeFunction<State>, keyGenerator?: CacheKeyGenerator<State>) => NodeFunction<State>;
+    clear: () => void;
+    size: () => number;
+};
+
+/**
+ * Rate limiting strategy
+ */
+type RateLimitStrategy = 'token-bucket' | 'sliding-window' | 'fixed-window';
+/**
+ * Rate limiting options
+ */
+interface RateLimitOptions {
+    /**
+     * Maximum number of requests allowed
+     */
+    maxRequests: number;
+    /**
+     * Time window in milliseconds
+     */
+    windowMs: number;
+    /**
+     * Rate limiting strategy
+     * @default 'token-bucket'
+     */
+    strategy?: RateLimitStrategy;
+    /**
+     * Callback when rate limit is exceeded
+     */
+    onRateLimitExceeded?: (key: string) => void;
+    /**
+     * Callback when rate limit is reset
+     */
+    onRateLimitReset?: (key: string) => void;
+    /**
+     * Key generator function to identify unique clients/requests
+     * @default Returns a constant key (global rate limit)
+     */
+    keyGenerator?: <State>(state: State) => string;
+}
+/**
+ * Rate limiting middleware
+ */
+declare function withRateLimit<State>(node: NodeFunction<State>, options: RateLimitOptions): NodeFunction<State>;
+/**
+ * Create a shared rate limiter that can be used across multiple nodes
+ */
+declare function createSharedRateLimiter(options: Omit<RateLimitOptions, 'keyGenerator'>): {
+    withRateLimit: <State>(node: NodeFunction<State>, keyGenerator?: (state: State) => string) => NodeFunction<State>;
+    reset: (key?: string) => void;
+};
+
+/**
+ * Validation mode
+ */
+type ValidationMode = 'input' | 'output' | 'both';
+/**
+ * Custom validator function
+ */
+type ValidatorFunction<T> = (value: T) => boolean | Promise<boolean>;
+/**
+ * Validation error handler
+ */
+type ValidationErrorHandler<State> = (error: z.ZodError | Error, state: State, mode: 'input' | 'output') => State | Partial<State> | never;
+/**
+ * Validation options
+ */
+interface ValidationOptions<State> {
+    /**
+     * Zod schema for input validation
+     */
+    inputSchema?: z.ZodSchema<State>;
+    /**
+     * Zod schema for output validation
+     */
+    outputSchema?: z.ZodSchema<State | Partial<State>>;
+    /**
+     * Custom input validator function
+     */
+    inputValidator?: ValidatorFunction<State>;
+    /**
+     * Custom output validator function
+     */
+    outputValidator?: ValidatorFunction<State | Partial<State>>;
+    /**
+     * Validation mode
+     * @default 'both'
+     */
+    mode?: ValidationMode;
+    /**
+     * Whether to throw on validation error
+     * @default true
+     */
+    throwOnError?: boolean;
+    /**
+     * Custom error handler
+     */
+    onValidationError?: ValidationErrorHandler<State>;
+    /**
+     * Callback when validation succeeds
+     */
+    onValidationSuccess?: (state: State | Partial<State>, mode: 'input' | 'output') => void;
+    /**
+     * Whether to strip unknown properties
+     * @default false
+     */
+    stripUnknown?: boolean;
+}
+/**
+ * Validation middleware
+ */
+declare function withValidation<State>(node: NodeFunction<State>, options: ValidationOptions<State>): NodeFunction<State>;
+
+/**
+ * Priority level for queued tasks
+ */
+type Priority = 'low' | 'normal' | 'high';
+/**
+ * Concurrency control options
+ */
+interface ConcurrencyOptions<State> {
+    /**
+     * Maximum number of concurrent executions
+     * @default 1
+     */
+    maxConcurrent?: number;
+    /**
+     * Maximum queue size (0 = unlimited)
+     * @default 0
+     */
+    maxQueueSize?: number;
+    /**
+     * Priority function to determine task priority
+     * @default () => 'normal'
+     */
+    priorityFn?: (state: State) => Priority;
+    /**
+     * Callback when task is queued
+     */
+    onQueued?: (queueSize: number, state: State) => void;
+    /**
+     * Callback when task starts executing
+     */
+    onExecutionStart?: (activeCount: number, state: State) => void;
+    /**
+     * Callback when task completes
+     */
+    onExecutionComplete?: (activeCount: number, state: State) => void;
+    /**
+     * Callback when queue is full
+     */
+    onQueueFull?: (state: State) => void;
+    /**
+     * Timeout for queued tasks (ms)
+     * @default 0 (no timeout)
+     */
+    queueTimeout?: number;
+}
+/**
+ * Concurrency control middleware
+ */
+declare function withConcurrency<State>(node: NodeFunction<State>, options?: ConcurrencyOptions<State>): NodeFunction<State>;
+/**
+ * Create a shared concurrency controller
+ */
+declare function createSharedConcurrencyController<State>(options?: ConcurrencyOptions<State>): {
+    withConcurrency: (node: NodeFunction<State>) => NodeFunction<State>;
+    getStats: () => {
+        activeCount: number;
+        queueSize: number;
+    };
+    clear: () => void;
+};
+
+/**
+ * Logging Middleware
+ *
+ * Provides structured logging for LangGraph nodes with input/output tracking,
+ * duration measurement, and error logging.
+ *
+ * @module langgraph/middleware/logging
+ */
+
+/**
+ * Options for logging middleware
+ */
+interface LoggingOptions {
+    /**
+     * Logger instance to use
+     * If not provided, a new logger will be created with the given name
+     */
+    logger?: Logger;
+    /**
+     * Name for the logger (used if logger is not provided)
+     */
+    name?: string;
+    /**
+     * Log level
+     * @default 'info'
+     */
+    level?: LogLevel;
+    /**
+     * Whether to log node inputs
+     * @default true
+     */
+    logInput?: boolean;
+    /**
+     * Whether to log node outputs
+     * @default true
+     */
+    logOutput?: boolean;
+    /**
+     * Whether to log execution duration
+     * @default true
+     */
+    logDuration?: boolean;
+    /**
+     * Whether to log errors
+     * @default true
+     */
+    logErrors?: boolean;
+    /**
+     * Custom function to extract loggable data from state
+     * Use this to avoid logging sensitive information
+     */
+    extractData?: <State>(state: State) => Record<string, any>;
+    /**
+     * Callback when node execution starts
+     */
+    onStart?: <State>(state: State) => void;
+    /**
+     * Callback when node execution completes
+     */
+    onComplete?: <State>(state: State, result: State | Partial<State>, duration: number) => void;
+    /**
+     * Callback when node execution fails
+     */
+    onError?: (error: Error, duration: number) => void;
+}
+/**
+ * Create a logging middleware that wraps a node with structured logging.
+ *
+ * @example
+ * ```typescript
+ * import { withLogging } from '@agentforge/core/langgraph/middleware';
+ *
+ * const loggedNode = withLogging({
+ *   name: 'my-node',
+ *   level: 'info',
+ *   logInput: true,
+ *   logOutput: true,
+ * })(myNode);
+ * ```
+ *
+ * @param options - Logging configuration options
+ * @returns A middleware function that adds logging to a node
+ */
+declare const withLogging: MiddlewareFactory<any, LoggingOptions>;
+
 /**
  * Checkpointer Factory Functions
  *
@@ -4817,4 +5157,4 @@ 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 CheckInterruptOptions, type CheckpointHistoryOptions, type CheckpointerOptions, type ChunkOptions, CircuitBreaker, type CircuitBreakerOptions, type CircuitBreakerStats, type CircuitState, type ComposeGraphsOptions, type ComposeOptions, type ComposeToolConfig, type ComposedTool, 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 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, 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, type ProductionPresetOptions, type Progress, type ProgressTracker, type ProgressTrackerOptions, type PromptOptions, 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 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, 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, withErrorHandler, withMetrics, withRetry, withTimeout, withTracing };
+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 };