@agentforge/core 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -2379,6 +2379,247 @@ interface ComposeGraphsOptions {
  */
 declare function composeGraphs<ParentState, SubState>(parentGraph: StateGraph<ParentState>, subgraph: ReturnType<StateGraph<SubState>['compile']>, options: ComposeGraphsOptions): StateGraph<ParentState>;
 
+/**
+ * Middleware System - Type Definitions
+ *
+ * Core types and interfaces for the middleware system.
+ * All middleware follows a consistent, composable pattern.
+ *
+ * @module langgraph/middleware/types
+ */
+/**
+ * A LangGraph node function that processes state.
+ *
+ * Node functions can return:
+ * - Full state (State)
+ * - Partial state update (Partial<State>)
+ * - Promise of either
+ *
+ * @template State - The state type for the node
+ */
+type NodeFunction<State> = (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>;
+/**
+ * A middleware function that wraps a node function.
+ *
+ * Middleware takes a node function and options, and returns a new node function
+ * with enhanced behavior (logging, metrics, retry, etc.).
+ *
+ * @template State - The state type for the node
+ * @template Options - Configuration options for the middleware
+ *
+ * @example
+ * ```typescript
+ * const loggingMiddleware: Middleware<MyState, LoggingOptions> = (node, options) => {
+ *   return async (state) => {
+ *     console.log('Before:', state);
+ *     const result = await node(state);
+ *     console.log('After:', result);
+ *     return result;
+ *   };
+ * };
+ * ```
+ */
+type Middleware<State, Options = unknown> = (node: NodeFunction<State>, options: Options) => NodeFunction<State>;
+/**
+ * A middleware factory that creates middleware with bound options.
+ *
+ * This is useful for creating reusable middleware configurations.
+ *
+ * @template State - The state type for the node
+ * @template Options - Configuration options for the middleware
+ *
+ * @example
+ * ```typescript
+ * const createLogger: MiddlewareFactory<MyState, LoggingOptions> = (options) => {
+ *   return (node) => {
+ *     return async (state) => {
+ *       // Logging logic using options
+ *       return await node(state);
+ *     };
+ *   };
+ * };
+ * ```
+ */
+type MiddlewareFactory<State, Options = unknown> = (options: Options) => (node: NodeFunction<State>) => NodeFunction<State>;
+/**
+ * A middleware that doesn't require options.
+ *
+ * @template State - The state type for the node
+ */
+type SimpleMiddleware<State> = (node: NodeFunction<State>) => NodeFunction<State>;
+/**
+ * Configuration for middleware composition.
+ */
+interface ComposeOptions {
+    /**
+     * Whether to execute middleware in reverse order.
+     * @default false
+     */
+    reverse?: boolean;
+    /**
+     * Name for the composed middleware (for debugging).
+     */
+    name?: string;
+    /**
+     * Whether to catch and handle errors in middleware.
+     * @default true
+     */
+    catchErrors?: boolean;
+}
+/**
+ * Metadata about a middleware function.
+ */
+interface MiddlewareMetadata {
+    /**
+     * Name of the middleware
+     */
+    name: string;
+    /**
+     * Description of what the middleware does
+     */
+    description?: string;
+    /**
+     * Version of the middleware
+     */
+    version?: string;
+    /**
+     * Tags for categorizing middleware
+     */
+    tags?: string[];
+}
+/**
+ * A middleware with attached metadata.
+ */
+interface MiddlewareWithMetadata<State, Options = unknown> {
+    /**
+     * The middleware function
+     */
+    middleware: Middleware<State, Options>;
+    /**
+     * Metadata about the middleware
+     */
+    metadata: MiddlewareMetadata;
+}
+/**
+ * Context passed through middleware chain.
+ *
+ * This allows middleware to share information without modifying state.
+ */
+interface MiddlewareContext {
+    /**
+     * Unique ID for this execution
+     */
+    executionId: string;
+    /**
+     * Timestamp when execution started
+     */
+    startTime: number;
+    /**
+     * Custom data that middleware can read/write
+     */
+    data: Record<string, unknown>;
+    /**
+     * Stack of middleware names that have been applied
+     */
+    middlewareStack: string[];
+}
+/**
+ * Enhanced node function with middleware context.
+ */
+type NodeFunctionWithContext<State> = (state: State, context: MiddlewareContext) => State | Promise<State> | Partial<State> | Promise<Partial<State>>;
+
+/**
+ * Middleware Composition Utilities
+ *
+ * Functions for composing multiple middleware into a single middleware chain.
+ *
+ * @module langgraph/middleware/compose
+ */
+
+/**
+ * Compose multiple middleware functions into a single middleware.
+ *
+ * Middleware are applied from left to right (first middleware wraps the node,
+ * second middleware wraps the first, etc.).
+ *
+ * @example
+ * ```typescript
+ * const enhanced = compose(
+ *   withLogging({ level: 'info' }),
+ *   withMetrics({ name: 'my-node' }),
+ *   withRetry({ maxAttempts: 3 })
+ * )(myNode);
+ * ```
+ *
+ * @param middleware - Middleware functions to compose
+ * @returns A function that takes a node and returns the enhanced node
+ */
+declare function compose<State>(...middleware: SimpleMiddleware<State>[]): SimpleMiddleware<State>;
+/**
+ * Compose middleware with options.
+ *
+ * @example
+ * ```typescript
+ * const enhanced = composeWithOptions(
+ *   { reverse: true, name: 'my-chain' },
+ *   withLogging({ level: 'info' }),
+ *   withMetrics({ name: 'my-node' })
+ * )(myNode);
+ * ```
+ *
+ * @param options - Composition options
+ * @param middleware - Middleware functions to compose
+ * @returns A function that takes a node and returns the enhanced node
+ */
+declare function composeWithOptions<State>(options: ComposeOptions, ...middleware: SimpleMiddleware<State>[]): SimpleMiddleware<State>;
+/**
+ * Create a middleware chain builder for fluent API.
+ *
+ * @example
+ * ```typescript
+ * const enhanced = chain<MyState>()
+ *   .use(withLogging({ level: 'info' }))
+ *   .use(withMetrics({ name: 'my-node' }))
+ *   .use(withRetry({ maxAttempts: 3 }))
+ *   .build(myNode);
+ * ```
+ */
+declare class MiddlewareChain<State> {
+    private middleware;
+    private options;
+    /**
+     * Add middleware to the chain.
+     */
+    use(middleware: SimpleMiddleware<State>): this;
+    /**
+     * Set composition options.
+     */
+    withOptions(options: ComposeOptions): this;
+    /**
+     * Build the middleware chain and apply it to a node.
+     */
+    build(node: NodeFunction<State>): NodeFunction<State>;
+    /**
+     * Get the number of middleware in the chain.
+     */
+    get length(): number;
+}
+/**
+ * Create a new middleware chain builder.
+ *
+ * @example
+ * ```typescript
+ * const enhanced = chain<MyState>()
+ *   .use(withLogging({ level: 'info' }))
+ *   .build(myNode);
+ * ```
+ */
+declare function chain<State>(): MiddlewareChain<State>;
+/**
+ * Create a middleware context for tracking execution.
+ */
+declare function createMiddlewareContext(): MiddlewareContext;
+
 /**
  * Retry pattern for LangGraph nodes
  *
@@ -2493,486 +2734,12 @@ interface ErrorHandlerOptions<State> {
 declare function withErrorHandler<State>(node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>, options: ErrorHandlerOptions<State>): (state: State) => Promise<State | Partial<State>>;
 
 /**
- * Timeout pattern for LangGraph nodes
+ * Structured Logging Utilities
  *
- * Wraps a node function with timeout logic.
+ * Provides consistent, structured logging for LangGraph agents.
  */
 /**
- * Options for timeout behavior
- */
-interface TimeoutOptions<State> {
-    /**
-     * Timeout duration in milliseconds
-     */
-    timeout: number;
-    /**
-     * Callback function to handle timeouts
-     * Should return a state update to apply when a timeout occurs
-     */
-    onTimeout: (state: State) => State | Partial<State> | Promise<State | Partial<State>>;
-    /**
-     * Optional callback for logging timeouts
-     */
-    logTimeout?: (state: State) => void;
-    /**
-     * Whether to throw an error on timeout
-     * @default false
-     */
-    throwOnTimeout?: boolean;
-}
-/**
- * Error thrown when a node times out
- */
-declare class TimeoutError extends Error {
-    constructor(timeout: number);
-}
-/**
- * Wraps a node function with timeout logic.
- *
- * @example
- * ```typescript
- * const timedNode = withTimeout(myNode, {
- *   timeout: 5000,
- *   onTimeout: (state) => ({
- *     ...state,
- *     timedOut: true,
- *     error: 'Operation timed out',
- *   }),
- *   logTimeout: () => {
- *     console.warn('Node timed out');
- *   },
- * });
- *
- * graph.addNode('timed', timedNode);
- * ```
- *
- * @param node - The node function to wrap
- * @param options - Timeout configuration options
- * @returns A wrapped node function with timeout logic
- */
-declare function withTimeout<State>(node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>, options: TimeoutOptions<State>): (state: State) => Promise<State | Partial<State>>;
-
-/**
- * Checkpointer Factory Functions
- *
- * Provides factory functions for creating LangGraph checkpointers with sensible defaults.
- *
- * @module langgraph/persistence/checkpointer
- */
-
-/**
- * Serializer protocol for checkpoint data
- */
-interface SerializerProtocol {
-}
-/**
- * Common options for all checkpointers
- */
-interface CheckpointerOptions {
-    /**
-     * Custom serializer for checkpoint data
-     * @default undefined (uses default serializer)
-     */
-    serializer?: SerializerProtocol;
-}
-/**
- * Options for SQLite checkpointer
- */
-interface SqliteCheckpointerOptions extends CheckpointerOptions {
-    /**
-     * Path to the SQLite database file
-     * @default ':memory:' (in-memory database)
-     */
-    path?: string;
-    /**
-     * Whether to automatically run migrations
-     * @default true
-     */
-    autoMigrate?: boolean;
-}
-/**
- * Create an in-memory checkpointer for development and testing.
- *
- * This checkpointer stores all checkpoints in memory and is lost when the process exits.
- * Ideal for development, testing, and experimentation.
- *
- * @example
- * ```typescript
- * import { createMemoryCheckpointer } from '@agentforge/core';
- *
- * const checkpointer = createMemoryCheckpointer();
- *
- * const app = workflow.compile({ checkpointer });
- * ```
- *
- * @param options - Optional checkpointer configuration
- * @returns A MemorySaver instance
- */
-declare function createMemoryCheckpointer(options?: CheckpointerOptions): MemorySaver;
-/**
- * Create a SQLite-based checkpointer for local persistence.
- *
- * This checkpointer stores checkpoints in a SQLite database file, providing
- * persistence across process restarts. Ideal for local development and
- * single-machine deployments.
- *
- * Note: Requires `@langchain/langgraph-checkpoint-sqlite` to be installed.
- *
- * @example
- * ```typescript
- * import { createSqliteCheckpointer } from '@agentforge/core';
- *
- * // Use a file-based database
- * const checkpointer = await createSqliteCheckpointer({
- *   path: './checkpoints.db',
- *   autoMigrate: true,
- * });
- *
- * const app = workflow.compile({ checkpointer });
- * ```
- *
- * @param options - SQLite checkpointer configuration
- * @returns A Promise that resolves to a SqliteSaver instance
- * @throws Error if @langchain/langgraph-checkpoint-sqlite is not installed
- */
-declare function createSqliteCheckpointer(options?: SqliteCheckpointerOptions): Promise<BaseCheckpointSaver>;
-/**
- * Type guard to check if a checkpointer is a MemorySaver
- *
- * @param checkpointer - The checkpointer to check
- * @returns True if the checkpointer is a MemorySaver
- */
-declare function isMemoryCheckpointer(checkpointer: BaseCheckpointSaver): checkpointer is MemorySaver;
-
-/**
- * Thread Management Utilities
- *
- * Provides utilities for managing conversation threads and configurations.
- *
- * @module langgraph/persistence/thread
- */
-
-/**
- * Configuration for a thread
- */
-interface ThreadConfig {
-    /**
-     * Unique identifier for the thread
-     */
-    threadId: string;
-    /**
-     * Optional checkpoint ID to resume from
-     */
-    checkpointId?: string;
-    /**
-     * Optional checkpoint namespace
-     */
-    checkpointNamespace?: string;
-    /**
-     * Additional metadata for the thread
-     */
-    metadata?: Record<string, any>;
-}
-/**
- * Configuration for a conversation
- */
-interface ConversationConfig {
-    /**
-     * User ID for the conversation
-     */
-    userId: string;
-    /**
-     * Optional session ID
-     */
-    sessionId?: string;
-    /**
-     * Additional metadata
-     */
-    metadata?: Record<string, any>;
-}
-/**
- * Generate a unique thread ID.
- *
- * If a seed is provided, generates a deterministic UUID v5 based on the seed.
- * Otherwise, generates a random UUID v4.
- *
- * @example
- * ```typescript
- * import { generateThreadId } from '@agentforge/core';
- *
- * // Random thread ID
- * const threadId = generateThreadId();
- *
- * // Deterministic thread ID from seed
- * const threadId2 = generateThreadId('user-123');
- * ```
- *
- * @param seed - Optional seed for deterministic ID generation
- * @returns A unique thread ID
- */
-declare function generateThreadId(seed?: string): string;
-/**
- * Create a thread configuration for LangGraph.
- *
- * This creates a RunnableConfig object with the thread configuration
- * that can be passed to graph.invoke() or graph.stream().
- *
- * @example
- * ```typescript
- * import { createThreadConfig } from '@agentforge/core';
- *
- * const config = createThreadConfig({
- *   threadId: 'conversation-1',
- *   metadata: { userId: 'user-123' },
- * });
- *
- * const result = await app.invoke(input, config);
- * ```
- *
- * @param config - Thread configuration
- * @returns A RunnableConfig object
- */
-declare function createThreadConfig(config?: Partial<ThreadConfig>): RunnableConfig;
-/**
- * Create a conversation configuration for LangGraph.
- *
- * This is a convenience function that creates a thread configuration
- * with user and session information, commonly used for chat applications.
- *
- * @example
- * ```typescript
- * import { createConversationConfig } from '@agentforge/core';
- *
- * const config = createConversationConfig({
- *   userId: 'user-123',
- *   sessionId: 'session-456',
- * });
- *
- * const result = await app.invoke(input, config);
- * ```
- *
- * @param config - Conversation configuration
- * @returns A RunnableConfig object
- */
-declare function createConversationConfig(config: ConversationConfig): RunnableConfig;
-
-/**
- * Checkpointer Utility Functions
- *
- * Provides utility functions for working with LangGraph checkpointers.
- *
- * @module langgraph/persistence/utils
- */
-
-/**
- * Options for getting checkpoint history
- */
-interface CheckpointHistoryOptions {
-    /**
-     * Thread ID to get history for
-     */
-    threadId: string;
-    /**
-     * Maximum number of checkpoints to return
-     * @default 10
-     */
-    limit?: number;
-    /**
-     * Get checkpoints before this checkpoint ID
-     */
-    before?: string;
-}
-/**
- * Get the checkpoint history for a thread.
- *
- * Returns a list of checkpoints for the specified thread, ordered from
- * most recent to oldest.
- *
- * @example
- * ```typescript
- * import { getCheckpointHistory } from '@agentforge/core';
- *
- * const history = await getCheckpointHistory(checkpointer, {
- *   threadId: 'conversation-1',
- *   limit: 10,
- * });
- *
- * for (const checkpoint of history) {
- *   console.log(checkpoint.checkpoint.id);
- * }
- * ```
- *
- * @param checkpointer - The checkpointer to query
- * @param options - History query options
- * @returns A promise that resolves to an array of checkpoint tuples
- */
-declare function getCheckpointHistory(checkpointer: BaseCheckpointSaver, options: CheckpointHistoryOptions): Promise<CheckpointTuple[]>;
-/**
- * Get the latest checkpoint for a thread.
- *
- * Returns the most recent checkpoint for the specified thread, or null
- * if no checkpoints exist.
- *
- * @example
- * ```typescript
- * import { getLatestCheckpoint } from '@agentforge/core';
- *
- * const latest = await getLatestCheckpoint(checkpointer, {
- *   threadId: 'conversation-1',
- * });
- *
- * if (latest) {
- *   console.log('Latest checkpoint:', latest.checkpoint.id);
- * }
- * ```
- *
- * @param checkpointer - The checkpointer to query
- * @param options - Query options
- * @returns A promise that resolves to the latest checkpoint tuple or null
- */
-declare function getLatestCheckpoint(checkpointer: BaseCheckpointSaver, options: {
-    threadId: string;
-}): Promise<CheckpointTuple | null>;
-/**
- * Clear all checkpoints for a thread.
- *
- * Note: This functionality depends on the checkpointer implementation.
- * Not all checkpointers support deletion.
- *
- * @example
- * ```typescript
- * import { clearThread } from '@agentforge/core';
- *
- * await clearThread(checkpointer, {
- *   threadId: 'conversation-1',
- * });
- * ```
- *
- * @param checkpointer - The checkpointer to modify
- * @param options - Clear options
- * @returns A promise that resolves when the thread is cleared
- * @throws Error if the checkpointer doesn't support deletion
- */
-declare function clearThread(checkpointer: BaseCheckpointSaver, options: {
-    threadId: string;
-}): Promise<void>;
-
-/**
- * LangSmith Integration Utilities
- *
- * Helpers for configuring and using LangSmith tracing with LangGraph.
- */
-/**
- * LangSmith configuration options
- */
-interface LangSmithConfig {
-    /**
-     * LangSmith API key
-     * Can also be set via LANGSMITH_API_KEY environment variable
-     */
-    apiKey?: string;
-    /**
-     * Project name for organizing traces
-     * Can also be set via LANGSMITH_PROJECT environment variable
-     */
-    projectName?: string;
-    /**
-     * Whether tracing is enabled
-     * Can also be set via LANGSMITH_TRACING environment variable
-     * @default true if apiKey is provided
-     */
-    tracingEnabled?: boolean;
-    /**
-     * LangSmith API endpoint
-     * @default 'https://api.smith.langchain.com'
-     */
-    endpoint?: string;
-    /**
-     * Additional metadata to include in all traces
-     */
-    metadata?: Record<string, any>;
-}
-/**
- * Configure LangSmith for tracing.
- *
- * This sets environment variables that LangChain/LangGraph use for tracing.
- *
- * @example
- * ```typescript
- * import { configureLangSmith } from '@agentforge/core';
- *
- * configureLangSmith({
- *   apiKey: process.env.LANGSMITH_API_KEY,
- *   projectName: 'my-agent',
- *   tracingEnabled: true,
- * });
- * ```
- *
- * @param config - LangSmith configuration
- */
-declare function configureLangSmith(config: LangSmithConfig): void;
-/**
- * Get the current LangSmith configuration.
- *
- * @returns The current configuration or null if not configured
- */
-declare function getLangSmithConfig(): LangSmithConfig | null;
-/**
- * Check if LangSmith tracing is enabled.
- *
- * @returns True if tracing is enabled
- */
-declare function isTracingEnabled(): boolean;
-/**
- * Options for tracing a node
- */
-interface TracingOptions {
-    /**
-     * Name for the traced operation
-     */
-    name: string;
-    /**
-     * Additional metadata to include in the trace
-     */
-    metadata?: Record<string, any>;
-    /**
-     * Tags to categorize the trace
-     */
-    tags?: string[];
-    /**
-     * Run name for the trace
-     */
-    runName?: string;
-}
-/**
- * Wrap a node function with LangSmith tracing.
- *
- * This adds metadata to the execution context that LangSmith can use for tracing.
- *
- * @example
- * ```typescript
- * import { withTracing } from '@agentforge/core';
- *
- * const tracedNode = withTracing(myNode, {
- *   name: 'research-node',
- *   metadata: { category: 'research' },
- *   tags: ['research', 'web'],
- * });
- * ```
- *
- * @param node - The node function to wrap
- * @param options - Tracing options
- * @returns A wrapped node function with tracing
- */
-declare function withTracing<State>(node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>, options: TracingOptions): (state: State) => Promise<State | Partial<State>>;
-
-/**
- * Structured Logging Utilities
- *
- * Provides consistent, structured logging for LangGraph agents.
- */
-/**
- * Log levels
+ * Log levels
  */
 declare enum LogLevel {
     DEBUG = "debug",
@@ -3042,51 +2809,270 @@ interface Logger {
      */
     error(message: string, data?: Record<string, any>): void;
     /**
-     * Check if debug logging is enabled
-     * Useful for avoiding expensive computations when debug is disabled
+     * Check if debug logging is enabled
+     * Useful for avoiding expensive computations when debug is disabled
+     */
+    isDebugEnabled(): boolean;
+    /**
+     * Check if a specific log level is enabled
+     */
+    isLevelEnabled(level: LogLevel): boolean;
+    /**
+     * Create a child logger with additional context
+     */
+    withContext(context: Record<string, any>): Logger;
+}
+/**
+ * Create a structured logger.
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * import { createLogger, LogLevel } from '@agentforge/core';
+ *
+ * const logger = createLogger('my-agent', {
+ *   level: LogLevel.INFO,
+ *   format: 'json',
+ * });
+ *
+ * logger.info('Processing request', { userId: 'user-123' });
+ * logger.error('Request failed', { error: err.message });
+ * ```
+ *
+ * @example
+ * Performance optimization with isDebugEnabled:
+ * ```typescript
+ * // Avoid expensive computations when debug is disabled
+ * if (logger.isDebugEnabled()) {
+ *   const expensiveData = computeExpensiveDebugInfo();
+ *   logger.debug('Debug info', expensiveData);
+ * }
+ * ```
+ *
+ * @param name - Logger name (typically the agent or component name)
+ * @param options - Logger configuration options
+ * @returns A logger instance
+ */
+declare function createLogger(name: string, options?: LoggerOptions): Logger;
+
+/**
+ * Middleware Presets
+ *
+ * Pre-configured middleware combinations for common use cases.
+ *
+ * @module langgraph/middleware/presets
+ */
+
+/**
+ * Options for the production preset.
+ */
+interface ProductionPresetOptions<State> {
+    /**
+     * Name of the node (for logging and metrics)
+     */
+    nodeName: string;
+    /**
+     * Logger instance
+     */
+    logger?: Logger;
+    /**
+     * Enable metrics tracking
+     * @default true
+     */
+    enableMetrics?: boolean;
+    /**
+     * Enable tracing
+     * @default true
+     */
+    enableTracing?: boolean;
+    /**
+     * Enable retry logic
+     * @default true
+     */
+    enableRetry?: boolean;
+    /**
+     * Timeout in milliseconds
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Custom retry options
+     */
+    retryOptions?: Partial<RetryOptions>;
+    /**
+     * Custom error handler options
+     */
+    errorOptions?: Partial<ErrorHandlerOptions<State>>;
+}
+/**
+ * Production preset with comprehensive error handling, metrics, and tracing.
+ *
+ * Includes:
+ * - Error handling with fallback
+ * - Retry logic with exponential backoff
+ * - Timeout protection
+ * - Metrics tracking
+ * - Distributed tracing
+ *
+ * @example
+ * ```typescript
+ * const productionNode = presets.production(myNode, {
+ *   nodeName: 'my-node',
+ *   logger: createLogger({ level: LogLevel.INFO }),
+ * });
+ * ```
+ */
+declare function production<State>(node: NodeFunction<State>, options: ProductionPresetOptions<State>): NodeFunction<State>;
+/**
+ * Options for the development preset.
+ */
+interface DevelopmentPresetOptions {
+    /**
+     * Name of the node
+     */
+    nodeName: string;
+    /**
+     * Enable verbose logging
+     * @default true
+     */
+    verbose?: boolean;
+    /**
+     * Logger instance
+     */
+    logger?: Logger;
+}
+/**
+ * Development preset with verbose logging and debugging.
+ *
+ * Includes:
+ * - Verbose logging
+ * - Error details
+ * - No retry (fail fast)
+ * - Extended timeout
+ *
+ * @example
+ * ```typescript
+ * const devNode = presets.development(myNode, {
+ *   nodeName: 'my-node',
+ *   verbose: true,
+ * });
+ * ```
+ */
+declare function development<State>(node: NodeFunction<State>, options: DevelopmentPresetOptions): NodeFunction<State>;
+/**
+ * Options for the testing preset.
+ */
+interface TestingPresetOptions<State> {
+    /**
+     * Name of the node
+     */
+    nodeName: string;
+    /**
+     * Mock responses for testing
+     */
+    mockResponse?: Partial<State>;
+    /**
+     * Simulate errors for testing
+     */
+    simulateError?: Error;
+    /**
+     * Delay in milliseconds for testing async behavior
+     */
+    delay?: number;
+    /**
+     * Track invocations for assertions
+     */
+    trackInvocations?: boolean;
+}
+/**
+ * Testing preset for unit and integration tests.
+ *
+ * Includes:
+ * - Mock responses
+ * - Error simulation
+ * - Invocation tracking
+ * - Configurable delays
+ *
+ * @example
+ * ```typescript
+ * const testNode = presets.testing(myNode, {
+ *   nodeName: 'my-node',
+ *   mockResponse: { result: 'mocked' },
+ *   trackInvocations: true,
+ * });
+ * ```
+ */
+declare function testing<State>(node: NodeFunction<State>, options: TestingPresetOptions<State>): NodeFunction<State> & {
+    invocations: State[];
+};
+/**
+ * Preset collection for easy access.
+ */
+declare const presets: {
+    production: typeof production;
+    development: typeof development;
+    testing: typeof testing;
+};
+
+/**
+ * Timeout pattern for LangGraph nodes
+ *
+ * Wraps a node function with timeout logic.
+ */
+/**
+ * Options for timeout behavior
+ */
+interface TimeoutOptions<State> {
+    /**
+     * Timeout duration in milliseconds
+     */
+    timeout: number;
+    /**
+     * Callback function to handle timeouts
+     * Should return a state update to apply when a timeout occurs
      */
-    isDebugEnabled(): boolean;
+    onTimeout: (state: State) => State | Partial<State> | Promise<State | Partial<State>>;
     /**
-     * Check if a specific log level is enabled
+     * Optional callback for logging timeouts
      */
-    isLevelEnabled(level: LogLevel): boolean;
+    logTimeout?: (state: State) => void;
     /**
-     * Create a child logger with additional context
+     * Whether to throw an error on timeout
+     * @default false
      */
-    withContext(context: Record<string, any>): Logger;
+    throwOnTimeout?: boolean;
 }
 /**
- * Create a structured logger.
+ * Error thrown when a node times out
+ */
+declare class TimeoutError extends Error {
+    constructor(timeout: number);
+}
+/**
+ * Wraps a node function with timeout logic.
  *
  * @example
- * Basic usage:
  * ```typescript
- * import { createLogger, LogLevel } from '@agentforge/core';
- *
- * const logger = createLogger('my-agent', {
- *   level: LogLevel.INFO,
- *   format: 'json',
+ * const timedNode = withTimeout(myNode, {
+ *   timeout: 5000,
+ *   onTimeout: (state) => ({
+ *     ...state,
+ *     timedOut: true,
+ *     error: 'Operation timed out',
+ *   }),
+ *   logTimeout: () => {
+ *     console.warn('Node timed out');
+ *   },
  * });
  *
- * logger.info('Processing request', { userId: 'user-123' });
- * logger.error('Request failed', { error: err.message });
- * ```
- *
- * @example
- * Performance optimization with isDebugEnabled:
- * ```typescript
- * // Avoid expensive computations when debug is disabled
- * if (logger.isDebugEnabled()) {
- *   const expensiveData = computeExpensiveDebugInfo();
- *   logger.debug('Debug info', expensiveData);
- * }
+ * graph.addNode('timed', timedNode);
  * ```
  *
- * @param name - Logger name (typically the agent or component name)
- * @param options - Logger configuration options
- * @returns A logger instance
+ * @param node - The node function to wrap
+ * @param options - Timeout configuration options
+ * @returns A wrapped node function with timeout logic
  */
-declare function createLogger(name: string, options?: LoggerOptions): Logger;
+declare function withTimeout<State>(node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>, options: TimeoutOptions<State>): (state: State) => Promise<State | Partial<State>>;
 
 /**
  * Metrics Collection Utilities
@@ -3233,515 +3219,529 @@ interface MetricsNodeOptions {
 declare function withMetrics<State>(node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>, options: MetricsNodeOptions): (state: State) => Promise<State | Partial<State>>;
 
 /**
- * Enhanced Error Handling Utilities
+ * LangSmith Integration Utilities
  *
- * Provides enhanced error classes and error reporting for better debugging.
+ * Helpers for configuring and using LangSmith tracing with LangGraph.
  */
 /**
- * Error context information
+ * LangSmith configuration options
  */
-interface ErrorContext {
+interface LangSmithConfig {
     /**
-     * Error code for categorization
+     * LangSmith API key
+     * Can also be set via LANGSMITH_API_KEY environment variable
      */
-    code?: string;
+    apiKey?: string;
     /**
-     * Node name where the error occurred
+     * Project name for organizing traces
+     * Can also be set via LANGSMITH_PROJECT environment variable
      */
-    node?: string;
+    projectName?: string;
     /**
-     * Current state when the error occurred
+     * Whether tracing is enabled
+     * Can also be set via LANGSMITH_TRACING environment variable
+     * @default true if apiKey is provided
      */
-    state?: any;
+    tracingEnabled?: boolean;
     /**
-     * Additional metadata
+     * LangSmith API endpoint
+     * @default 'https://api.smith.langchain.com'
      */
-    metadata?: Record<string, any>;
+    endpoint?: string;
     /**
-     * Original error that caused this error
+     * Additional metadata to include in all traces
      */
-    cause?: Error;
+    metadata?: Record<string, any>;
 }
 /**
- * Enhanced error class for agent errors
+ * Configure LangSmith for tracing.
+ *
+ * This sets environment variables that LangChain/LangGraph use for tracing.
+ *
+ * @example
+ * ```typescript
+ * import { configureLangSmith } from '@agentforge/core';
+ *
+ * configureLangSmith({
+ *   apiKey: process.env.LANGSMITH_API_KEY,
+ *   projectName: 'my-agent',
+ *   tracingEnabled: true,
+ * });
+ * ```
+ *
+ * @param config - LangSmith configuration
  */
-declare class AgentError extends Error {
-    readonly code?: string;
-    readonly node?: string;
-    readonly state?: any;
-    readonly metadata?: Record<string, any>;
-    readonly cause?: Error;
-    readonly timestamp: number;
-    constructor(message: string, context?: ErrorContext);
-    /**
-     * Convert error to JSON for logging/reporting
-     */
-    toJSON(): Record<string, any>;
-    /**
-     * Get a human-readable string representation
-     */
-    toString(): string;
-}
+declare function configureLangSmith(config: LangSmithConfig): void;
 /**
- * Error reporter configuration
+ * Get the current LangSmith configuration.
+ *
+ * @returns The current configuration or null if not configured
  */
-interface ErrorReporterOptions {
-    /**
-     * Callback function to handle errors
-     */
-    onError: (error: AgentError) => void | Promise<void>;
-    /**
-     * Whether to include stack traces
-     * @default true
-     */
-    includeStackTrace?: boolean;
+declare function getLangSmithConfig(): LangSmithConfig | null;
+/**
+ * Check if LangSmith tracing is enabled.
+ *
+ * @returns True if tracing is enabled
+ */
+declare function isTracingEnabled(): boolean;
+/**
+ * Options for tracing a node
+ */
+interface TracingOptions {
     /**
-     * Whether to include state in error context
-     * @default false (for security/privacy)
+     * Name for the traced operation
      */
-    includeState?: boolean;
+    name: string;
     /**
-     * Whether to rethrow errors after reporting
-     * @default true
+     * Additional metadata to include in the trace
      */
-    rethrow?: boolean;
-}
-/**
- * Error reporter for tracking and reporting errors
- */
-interface ErrorReporter {
+    metadata?: Record<string, any>;
     /**
-     * Wrap a node function with error reporting
+     * Tags to categorize the trace
      */
-    wrap<State>(node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>, nodeName?: string): (state: State) => Promise<State | Partial<State>>;
+    tags?: string[];
     /**
-     * Report an error manually
+     * Run name for the trace
      */
-    report(error: Error, context?: ErrorContext): Promise<void>;
+    runName?: string;
 }
 /**
- * Create an error reporter.
+ * Wrap a node function with LangSmith tracing.
+ *
+ * This adds metadata to the execution context that LangSmith can use for tracing.
  *
  * @example
  * ```typescript
- * import { createErrorReporter } from '@agentforge/core';
+ * import { withTracing } from '@agentforge/core';
  *
- * const reporter = createErrorReporter({
- *   onError: (error) => {
- *     console.error('Agent error:', error.toJSON());
- *     // Send to error tracking service
- *   },
- *   includeStackTrace: true,
- *   includeState: false,
+ * const tracedNode = withTracing(myNode, {
+ *   name: 'research-node',
+ *   metadata: { category: 'research' },
+ *   tags: ['research', 'web'],
  * });
- *
- * const safeNode = reporter.wrap(myNode, 'my-node');
  * ```
  *
- * @param options - Error reporter configuration
- * @returns An error reporter instance
+ * @param node - The node function to wrap
+ * @param options - Tracing options
+ * @returns A wrapped node function with tracing
  */
-declare function createErrorReporter(options: ErrorReporterOptions): ErrorReporter;
+declare function withTracing<State>(node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>, options: TracingOptions): (state: State) => Promise<State | Partial<State>>;
 
 /**
- * Middleware System - Type Definitions
+ * Checkpointer Factory Functions
  *
- * Core types and interfaces for the middleware system.
- * All middleware follows a consistent, composable pattern.
+ * Provides factory functions for creating LangGraph checkpointers with sensible defaults.
  *
- * @module langgraph/middleware/types
+ * @module langgraph/persistence/checkpointer
  */
+
 /**
- * A LangGraph node function that processes state.
- *
- * Node functions can return:
- * - Full state (State)
- * - Partial state update (Partial<State>)
- * - Promise of either
- *
- * @template State - The state type for the node
+ * Serializer protocol for checkpoint data
  */
-type NodeFunction<State> = (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>;
+interface SerializerProtocol {
+}
 /**
- * A middleware function that wraps a node function.
- *
- * Middleware takes a node function and options, and returns a new node function
- * with enhanced behavior (logging, metrics, retry, etc.).
+ * Common options for all checkpointers
+ */
+interface CheckpointerOptions {
+    /**
+     * Custom serializer for checkpoint data
+     * @default undefined (uses default serializer)
+     */
+    serializer?: SerializerProtocol;
+}
+/**
+ * Options for SQLite checkpointer
+ */
+interface SqliteCheckpointerOptions extends CheckpointerOptions {
+    /**
+     * Path to the SQLite database file
+     * @default ':memory:' (in-memory database)
+     */
+    path?: string;
+    /**
+     * Whether to automatically run migrations
+     * @default true
+     */
+    autoMigrate?: boolean;
+}
+/**
+ * Create an in-memory checkpointer for development and testing.
  *
- * @template State - The state type for the node
- * @template Options - Configuration options for the middleware
+ * This checkpointer stores all checkpoints in memory and is lost when the process exits.
+ * Ideal for development, testing, and experimentation.
  *
  * @example
  * ```typescript
- * const loggingMiddleware: Middleware<MyState, LoggingOptions> = (node, options) => {
- *   return async (state) => {
- *     console.log('Before:', state);
- *     const result = await node(state);
- *     console.log('After:', result);
- *     return result;
- *   };
- * };
+ * import { createMemoryCheckpointer } from '@agentforge/core';
+ *
+ * const checkpointer = createMemoryCheckpointer();
+ *
+ * const app = workflow.compile({ checkpointer });
  * ```
+ *
+ * @param options - Optional checkpointer configuration
+ * @returns A MemorySaver instance
  */
-type Middleware<State, Options = unknown> = (node: NodeFunction<State>, options: Options) => NodeFunction<State>;
+declare function createMemoryCheckpointer(options?: CheckpointerOptions): MemorySaver;
 /**
- * A middleware factory that creates middleware with bound options.
+ * Create a SQLite-based checkpointer for local persistence.
  *
- * This is useful for creating reusable middleware configurations.
+ * This checkpointer stores checkpoints in a SQLite database file, providing
+ * persistence across process restarts. Ideal for local development and
+ * single-machine deployments.
  *
- * @template State - The state type for the node
- * @template Options - Configuration options for the middleware
+ * Note: Requires `@langchain/langgraph-checkpoint-sqlite` to be installed.
  *
  * @example
  * ```typescript
- * const createLogger: MiddlewareFactory<MyState, LoggingOptions> = (options) => {
- *   return (node) => {
- *     return async (state) => {
- *       // Logging logic using options
- *       return await node(state);
- *     };
- *   };
- * };
+ * import { createSqliteCheckpointer } from '@agentforge/core';
+ *
+ * // Use a file-based database
+ * const checkpointer = await createSqliteCheckpointer({
+ *   path: './checkpoints.db',
+ *   autoMigrate: true,
+ * });
+ *
+ * const app = workflow.compile({ checkpointer });
  * ```
+ *
+ * @param options - SQLite checkpointer configuration
+ * @returns A Promise that resolves to a SqliteSaver instance
+ * @throws Error if @langchain/langgraph-checkpoint-sqlite is not installed
  */
-type MiddlewareFactory<State, Options = unknown> = (options: Options) => (node: NodeFunction<State>) => NodeFunction<State>;
+declare function createSqliteCheckpointer(options?: SqliteCheckpointerOptions): Promise<BaseCheckpointSaver>;
 /**
- * A middleware that doesn't require options.
+ * Type guard to check if a checkpointer is a MemorySaver
  *
- * @template State - The state type for the node
+ * @param checkpointer - The checkpointer to check
+ * @returns True if the checkpointer is a MemorySaver
  */
-type SimpleMiddleware<State> = (node: NodeFunction<State>) => NodeFunction<State>;
+declare function isMemoryCheckpointer(checkpointer: BaseCheckpointSaver): checkpointer is MemorySaver;
+
 /**
- * Configuration for middleware composition.
+ * Thread Management Utilities
+ *
+ * Provides utilities for managing conversation threads and configurations.
+ *
+ * @module langgraph/persistence/thread
  */
-interface ComposeOptions {
-    /**
-     * Whether to execute middleware in reverse order.
-     * @default false
-     */
-    reverse?: boolean;
-    /**
-     * Name for the composed middleware (for debugging).
-     */
-    name?: string;
-    /**
-     * Whether to catch and handle errors in middleware.
-     * @default true
-     */
-    catchErrors?: boolean;
-}
+
 /**
- * Metadata about a middleware function.
+ * Configuration for a thread
  */
-interface MiddlewareMetadata {
-    /**
-     * Name of the middleware
-     */
-    name: string;
-    /**
-     * Description of what the middleware does
-     */
-    description?: string;
+interface ThreadConfig {
     /**
-     * Version of the middleware
+     * Unique identifier for the thread
      */
-    version?: string;
+    threadId: string;
     /**
-     * Tags for categorizing middleware
+     * Optional checkpoint ID to resume from
      */
-    tags?: string[];
-}
-/**
- * A middleware with attached metadata.
- */
-interface MiddlewareWithMetadata<State, Options = unknown> {
+    checkpointId?: string;
     /**
-     * The middleware function
+     * Optional checkpoint namespace
      */
-    middleware: Middleware<State, Options>;
+    checkpointNamespace?: string;
     /**
-     * Metadata about the middleware
+     * Additional metadata for the thread
      */
-    metadata: MiddlewareMetadata;
+    metadata?: Record<string, any>;
 }
 /**
- * Context passed through middleware chain.
- *
- * This allows middleware to share information without modifying state.
+ * Configuration for a conversation
  */
-interface MiddlewareContext {
-    /**
-     * Unique ID for this execution
-     */
-    executionId: string;
+interface ConversationConfig {
     /**
-     * Timestamp when execution started
+     * User ID for the conversation
      */
-    startTime: number;
+    userId: string;
     /**
-     * Custom data that middleware can read/write
+     * Optional session ID
      */
-    data: Record<string, unknown>;
+    sessionId?: string;
     /**
-     * Stack of middleware names that have been applied
+     * Additional metadata
      */
-    middlewareStack: string[];
+    metadata?: Record<string, any>;
 }
 /**
- * Enhanced node function with middleware context.
+ * Generate a unique thread ID.
+ *
+ * If a seed is provided, generates a deterministic UUID v5 based on the seed.
+ * Otherwise, generates a random UUID v4.
+ *
+ * @example
+ * ```typescript
+ * import { generateThreadId } from '@agentforge/core';
+ *
+ * // Random thread ID
+ * const threadId = generateThreadId();
+ *
+ * // Deterministic thread ID from seed
+ * const threadId2 = generateThreadId('user-123');
+ * ```
+ *
+ * @param seed - Optional seed for deterministic ID generation
+ * @returns A unique thread ID
  */
-type NodeFunctionWithContext<State> = (state: State, context: MiddlewareContext) => State | Promise<State> | Partial<State> | Promise<Partial<State>>;
-
+declare function generateThreadId(seed?: string): string;
 /**
- * Middleware Composition Utilities
+ * Create a thread configuration for LangGraph.
  *
- * Functions for composing multiple middleware into a single middleware chain.
+ * This creates a RunnableConfig object with the thread configuration
+ * that can be passed to graph.invoke() or graph.stream().
  *
- * @module langgraph/middleware/compose
+ * @example
+ * ```typescript
+ * import { createThreadConfig } from '@agentforge/core';
+ *
+ * const config = createThreadConfig({
+ *   threadId: 'conversation-1',
+ *   metadata: { userId: 'user-123' },
+ * });
+ *
+ * const result = await app.invoke(input, config);
+ * ```
+ *
+ * @param config - Thread configuration
+ * @returns A RunnableConfig object
  */
-
+declare function createThreadConfig(config?: Partial<ThreadConfig>): RunnableConfig;
 /**
- * Compose multiple middleware functions into a single middleware.
+ * Create a conversation configuration for LangGraph.
  *
- * Middleware are applied from left to right (first middleware wraps the node,
- * second middleware wraps the first, etc.).
+ * This is a convenience function that creates a thread configuration
+ * with user and session information, commonly used for chat applications.
  *
  * @example
  * ```typescript
- * const enhanced = compose(
- *   withLogging({ level: 'info' }),
- *   withMetrics({ name: 'my-node' }),
- *   withRetry({ maxAttempts: 3 })
- * )(myNode);
+ * import { createConversationConfig } from '@agentforge/core';
+ *
+ * const config = createConversationConfig({
+ *   userId: 'user-123',
+ *   sessionId: 'session-456',
+ * });
+ *
+ * const result = await app.invoke(input, config);
  * ```
  *
- * @param middleware - Middleware functions to compose
- * @returns A function that takes a node and returns the enhanced node
+ * @param config - Conversation configuration
+ * @returns A RunnableConfig object
  */
-declare function compose<State>(...middleware: SimpleMiddleware<State>[]): SimpleMiddleware<State>;
+declare function createConversationConfig(config: ConversationConfig): RunnableConfig;
+
 /**
- * Compose middleware with options.
+ * Checkpointer Utility Functions
+ *
+ * Provides utility functions for working with LangGraph checkpointers.
+ *
+ * @module langgraph/persistence/utils
+ */
+
+/**
+ * Options for getting checkpoint history
+ */
+interface CheckpointHistoryOptions {
+    /**
+     * Thread ID to get history for
+     */
+    threadId: string;
+    /**
+     * Maximum number of checkpoints to return
+     * @default 10
+     */
+    limit?: number;
+    /**
+     * Get checkpoints before this checkpoint ID
+     */
+    before?: string;
+}
+/**
+ * Get the checkpoint history for a thread.
+ *
+ * Returns a list of checkpoints for the specified thread, ordered from
+ * most recent to oldest.
  *
  * @example
  * ```typescript
- * const enhanced = composeWithOptions(
- *   { reverse: true, name: 'my-chain' },
- *   withLogging({ level: 'info' }),
- *   withMetrics({ name: 'my-node' })
- * )(myNode);
+ * import { getCheckpointHistory } from '@agentforge/core';
+ *
+ * const history = await getCheckpointHistory(checkpointer, {
+ *   threadId: 'conversation-1',
+ *   limit: 10,
+ * });
+ *
+ * for (const checkpoint of history) {
+ *   console.log(checkpoint.checkpoint.id);
+ * }
  * ```
  *
- * @param options - Composition options
- * @param middleware - Middleware functions to compose
- * @returns A function that takes a node and returns the enhanced node
+ * @param checkpointer - The checkpointer to query
+ * @param options - History query options
+ * @returns A promise that resolves to an array of checkpoint tuples
  */
-declare function composeWithOptions<State>(options: ComposeOptions, ...middleware: SimpleMiddleware<State>[]): SimpleMiddleware<State>;
+declare function getCheckpointHistory(checkpointer: BaseCheckpointSaver, options: CheckpointHistoryOptions): Promise<CheckpointTuple[]>;
 /**
- * Create a middleware chain builder for fluent API.
+ * Get the latest checkpoint for a thread.
+ *
+ * Returns the most recent checkpoint for the specified thread, or null
+ * if no checkpoints exist.
  *
  * @example
  * ```typescript
- * const enhanced = chain<MyState>()
- *   .use(withLogging({ level: 'info' }))
- *   .use(withMetrics({ name: 'my-node' }))
- *   .use(withRetry({ maxAttempts: 3 }))
- *   .build(myNode);
+ * import { getLatestCheckpoint } from '@agentforge/core';
+ *
+ * const latest = await getLatestCheckpoint(checkpointer, {
+ *   threadId: 'conversation-1',
+ * });
+ *
+ * if (latest) {
+ *   console.log('Latest checkpoint:', latest.checkpoint.id);
+ * }
  * ```
+ *
+ * @param checkpointer - The checkpointer to query
+ * @param options - Query options
+ * @returns A promise that resolves to the latest checkpoint tuple or null
  */
-declare class MiddlewareChain<State> {
-    private middleware;
-    private options;
-    /**
-     * Add middleware to the chain.
-     */
-    use(middleware: SimpleMiddleware<State>): this;
-    /**
-     * Set composition options.
-     */
-    withOptions(options: ComposeOptions): this;
-    /**
-     * Build the middleware chain and apply it to a node.
-     */
-    build(node: NodeFunction<State>): NodeFunction<State>;
-    /**
-     * Get the number of middleware in the chain.
-     */
-    get length(): number;
-}
+declare function getLatestCheckpoint(checkpointer: BaseCheckpointSaver, options: {
+    threadId: string;
+}): Promise<CheckpointTuple | null>;
 /**
- * Create a new middleware chain builder.
+ * Clear all checkpoints for a thread.
+ *
+ * Note: This functionality depends on the checkpointer implementation.
+ * Not all checkpointers support deletion.
  *
  * @example
  * ```typescript
- * const enhanced = chain<MyState>()
- *   .use(withLogging({ level: 'info' }))
- *   .build(myNode);
+ * import { clearThread } from '@agentforge/core';
+ *
+ * await clearThread(checkpointer, {
+ *   threadId: 'conversation-1',
+ * });
  * ```
+ *
+ * @param checkpointer - The checkpointer to modify
+ * @param options - Clear options
+ * @returns A promise that resolves when the thread is cleared
+ * @throws Error if the checkpointer doesn't support deletion
  */
-declare function chain<State>(): MiddlewareChain<State>;
-/**
- * Create a middleware context for tracking execution.
- */
-declare function createMiddlewareContext(): MiddlewareContext;
+declare function clearThread(checkpointer: BaseCheckpointSaver, options: {
+    threadId: string;
+}): Promise<void>;
 
 /**
- * Middleware Presets
- *
- * Pre-configured middleware combinations for common use cases.
+ * Enhanced Error Handling Utilities
  *
- * @module langgraph/middleware/presets
+ * Provides enhanced error classes and error reporting for better debugging.
  */
-
 /**
- * Options for the production preset.
+ * Error context information
  */
-interface ProductionPresetOptions<State> {
-    /**
-     * Name of the node (for logging and metrics)
-     */
-    nodeName: string;
+interface ErrorContext {
     /**
-     * Logger instance
+     * Error code for categorization
      */
-    logger?: Logger;
+    code?: string;
     /**
-     * Enable metrics tracking
-     * @default true
+     * Node name where the error occurred
      */
-    enableMetrics?: boolean;
+    node?: string;
     /**
-     * Enable tracing
-     * @default true
+     * Current state when the error occurred
      */
-    enableTracing?: boolean;
+    state?: any;
     /**
-     * Enable retry logic
-     * @default true
+     * Additional metadata
      */
-    enableRetry?: boolean;
+    metadata?: Record<string, any>;
     /**
-     * Timeout in milliseconds
-     * @default 30000 (30 seconds)
+     * Original error that caused this error
      */
-    timeout?: number;
+    cause?: Error;
+}
+/**
+ * Enhanced error class for agent errors
+ */
+declare class AgentError extends Error {
+    readonly code?: string;
+    readonly node?: string;
+    readonly state?: any;
+    readonly metadata?: Record<string, any>;
+    readonly cause?: Error;
+    readonly timestamp: number;
+    constructor(message: string, context?: ErrorContext);
     /**
-     * Custom retry options
+     * Convert error to JSON for logging/reporting
      */
-    retryOptions?: Partial<RetryOptions>;
+    toJSON(): Record<string, any>;
     /**
-     * Custom error handler options
+     * Get a human-readable string representation
      */
-    errorOptions?: Partial<ErrorHandlerOptions<State>>;
+    toString(): string;
 }
 /**
- * Production preset with comprehensive error handling, metrics, and tracing.
- *
- * Includes:
- * - Error handling with fallback
- * - Retry logic with exponential backoff
- * - Timeout protection
- * - Metrics tracking
- * - Distributed tracing
- *
- * @example
- * ```typescript
- * const productionNode = presets.production(myNode, {
- *   nodeName: 'my-node',
- *   logger: createLogger({ level: LogLevel.INFO }),
- * });
- * ```
- */
-declare function production<State>(node: NodeFunction<State>, options: ProductionPresetOptions<State>): NodeFunction<State>;
-/**
- * Options for the development preset.
+ * Error reporter configuration
  */
-interface DevelopmentPresetOptions {
+interface ErrorReporterOptions {
     /**
-     * Name of the node
+     * Callback function to handle errors
      */
-    nodeName: string;
+    onError: (error: AgentError) => void | Promise<void>;
     /**
-     * Enable verbose logging
+     * Whether to include stack traces
      * @default true
      */
-    verbose?: boolean;
+    includeStackTrace?: boolean;
     /**
-     * Logger instance
+     * Whether to include state in error context
+     * @default false (for security/privacy)
      */
-    logger?: Logger;
+    includeState?: boolean;
+    /**
+     * Whether to rethrow errors after reporting
+     * @default true
+     */
+    rethrow?: boolean;
 }
 /**
- * Development preset with verbose logging and debugging.
- *
- * Includes:
- * - Verbose logging
- * - Error details
- * - No retry (fail fast)
- * - Extended timeout
- *
- * @example
- * ```typescript
- * const devNode = presets.development(myNode, {
- *   nodeName: 'my-node',
- *   verbose: true,
- * });
- * ```
- */
-declare function development<State>(node: NodeFunction<State>, options: DevelopmentPresetOptions): NodeFunction<State>;
-/**
- * Options for the testing preset.
+ * Error reporter for tracking and reporting errors
  */
-interface TestingPresetOptions<State> {
-    /**
-     * Name of the node
-     */
-    nodeName: string;
-    /**
-     * Mock responses for testing
-     */
-    mockResponse?: Partial<State>;
-    /**
-     * Simulate errors for testing
-     */
-    simulateError?: Error;
+interface ErrorReporter {
     /**
-     * Delay in milliseconds for testing async behavior
+     * Wrap a node function with error reporting
      */
-    delay?: number;
+    wrap<State>(node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>, nodeName?: string): (state: State) => Promise<State | Partial<State>>;
     /**
-     * Track invocations for assertions
+     * Report an error manually
      */
-    trackInvocations?: boolean;
+    report(error: Error, context?: ErrorContext): Promise<void>;
 }
 /**
- * Testing preset for unit and integration tests.
- *
- * Includes:
- * - Mock responses
- * - Error simulation
- * - Invocation tracking
- * - Configurable delays
+ * Create an error reporter.
  *
  * @example
  * ```typescript
- * const testNode = presets.testing(myNode, {
- *   nodeName: 'my-node',
- *   mockResponse: { result: 'mocked' },
- *   trackInvocations: true,
+ * import { createErrorReporter } from '@agentforge/core';
+ *
+ * const reporter = createErrorReporter({
+ *   onError: (error) => {
+ *     console.error('Agent error:', error.toJSON());
+ *     // Send to error tracking service
+ *   },
+ *   includeStackTrace: true,
+ *   includeState: false,
  * });
+ *
+ * const safeNode = reporter.wrap(myNode, 'my-node');
  * ```
+ *
+ * @param options - Error reporter configuration
+ * @returns An error reporter instance
  */
-declare function testing<State>(node: NodeFunction<State>, options: TestingPresetOptions<State>): NodeFunction<State> & {
-    invocations: State[];
-};
-/**
- * Preset collection for easy access.
- */
-declare const presets: {
-    production: typeof production;
-    development: typeof development;
-    testing: typeof testing;
-};
+declare function createErrorReporter(options: ErrorReporterOptions): ErrorReporter;
 
 /**
  * Types for LangGraph interrupt handling