@agentforge/core 0.16.50 → 0.16.52

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { z, ZodTypeAny, output, ZodType, ZodTypeDef } from 'zod';
 import * as _langchain_core_tools from '@langchain/core/tools';
 import { DynamicStructuredTool } from '@langchain/core/tools';
 import * as _langchain_langgraph from '@langchain/langgraph';
-import { AnnotationRoot, BaseChannel, StateDefinition, UpdateType, StateGraph, END, MemorySaver, BaseCheckpointSaver, CheckpointTuple } from '@langchain/langgraph';
+import { BaseChannel, AnnotationRoot, StateDefinition, UpdateType, StateGraph, END, MemorySaver, BaseCheckpointSaver, CheckpointTuple } from '@langchain/langgraph';
 import { RunnableConfig } from '@langchain/core/runnables';
 
 /**
@@ -1093,15 +1093,6 @@ declare function getToolJsonSchema<TInput, TOutput>(tool: Tool<TInput, TOutput>)
  */
 declare function getToolDescription<TInput, TOutput>(tool: Tool<TInput, TOutput>): string;
 
-/**
- * LangGraph State Utilities
- *
- * Type-safe helpers for working with LangGraph state management.
- * These utilities wrap LangGraph's Annotation API to provide better TypeScript ergonomics.
- *
- * @module langgraph/state
- */
-
 /**
  * State channel configuration with optional Zod schema validation
  */
@@ -1150,6 +1141,16 @@ type ReducerUpdate<TChannel extends StateChannelConfigLike> = TChannel extends {
 } ? TUpdate : never;
 type ChannelValue<TChannel extends StateChannelConfigLike> = HasReducer<TChannel> extends true ? ReducerValue<TChannel> : [SchemaValue<TChannel>] extends [never] ? [DefaultValue<TChannel>] extends [never] ? unknown : DefaultValue<TChannel> : SchemaValue<TChannel>;
 type ChannelUpdate<TChannel extends StateChannelConfigLike> = HasReducer<TChannel> extends true ? ReducerUpdate<TChannel> : ChannelValue<TChannel>;
+type SchemaMatchesValue<TChannel extends StateChannelConfigLike> = [
+    SchemaValue<TChannel>
+] extends [never] ? true : [ChannelValue<TChannel>] extends [SchemaValue<TChannel>] ? true : false;
+type DefaultMatchesValue<TChannel extends StateChannelConfigLike> = [
+    DefaultValue<TChannel>
+] extends [never] ? true : [DefaultValue<TChannel>] extends [ChannelValue<TChannel>] ? true : false;
+type ValidStateChannel<TChannel extends StateChannelConfigLike> = HasReducer<TChannel> extends true ? [ChannelValue<TChannel>] extends [never] ? never : SchemaMatchesValue<TChannel> extends true ? DefaultMatchesValue<TChannel> extends true ? TChannel : never : never : TChannel;
+type ValidStateConfig<TConfig extends StateConfigMap> = {
+    [K in keyof TConfig]: ValidStateChannel<TConfig[K]>;
+};
 type StateShape<TConfig extends StateConfigMap> = {
     [K in keyof TConfig]: ChannelValue<TConfig[K]>;
 };
@@ -1169,6 +1170,7 @@ type InputStateKeys<TConfig extends StateConfigMap, TState> = Extract<keyof TCon
 type ValidatedState<TConfig extends StateConfigMap, TState extends Partial<Record<keyof TConfig, unknown>>> = {
     [K in InputStateKeys<TConfig, TState> | DefaultedKeys<TConfig>]: ChannelValue<TConfig[K]>;
 };
+
 /**
  * Create a type-safe state annotation with optional Zod validation
  *
@@ -1176,75 +1178,16 @@ type ValidatedState<TConfig extends StateConfigMap, TState extends Partial<Recor
  * - Zod schema validation support
  * - Better TypeScript inference
  * - Documentation/description support
- *
- * @example
- * ```typescript
- * import { createStateAnnotation } from '@agentforge/core';
- * import { z } from 'zod';
- *
- * const AgentState = createStateAnnotation({
- *   messages: {
- *     schema: z.array(z.string()),
- *     reducer: (left, right) => [...left, ...right],
- *     default: () => [],
- *     description: 'Chat messages'
- *   },
- *   context: {
- *     schema: z.record(z.any()),
- *     default: () => ({}),
- *     description: 'Agent context'
- *   }
- * });
- *
- * type State = typeof AgentState.State;
- * ```
  */
-declare function createStateAnnotation<TConfig extends StateConfigMap>(config: TConfig): AnnotationRoot<StateAnnotationDefinition<TConfig>>;
+declare function createStateAnnotation<TConfig extends StateConfigMap>(config: ValidStateConfig<TConfig>): AnnotationRoot<StateAnnotationDefinition<TConfig>>;
+
 /**
  * Validate state against Zod schemas
- *
- * @param state - The state object to validate
- * @param config - The state channel configuration with schemas
- * @returns Validated state
- * @throws {z.ZodError} If validation fails
- *
- * @example
- * ```typescript
- * const config = {
- *   messages: { schema: z.array(z.string()) },
- *   count: { schema: z.number() }
- * };
- *
- * const validatedState = validateState(
- *   { messages: ['hello'], count: 42 },
- *   config
- * );
- * ```
  */
 declare function validateState<TConfig extends StateConfigMap, TState extends Partial<Record<keyof TConfig, unknown>>>(state: TState, config: TConfig): ValidatedState<TConfig, TState>;
+
 /**
  * Merge state updates using configured reducers
- *
- * @param currentState - Current state
- * @param update - State update
- * @param config - State channel configuration
- * @returns Merged state
- *
- * @example
- * ```typescript
- * const config = {
- *   messages: {
- *     reducer: (left, right) => [...left, ...right]
- *   }
- * };
- *
- * const merged = mergeState(
- *   { messages: ['a', 'b'] },
- *   { messages: ['c'] },
- *   config
- * );
- * // Result: { messages: ['a', 'b', 'c'] }
- * ```
  */
 declare function mergeState<TConfig extends StateConfigMap>(currentState: Partial<StateShape<TConfig>>, update: StateUpdateShape<TConfig>, config: TConfig): Partial<StateShape<TConfig>>;
 
@@ -1906,119 +1849,6 @@ declare function chain<State>(): MiddlewareChain<State>;
  */
 declare function createMiddlewareContext(): MiddlewareContext;
 
-/**
- * Retry pattern for LangGraph nodes
- *
- * Wraps a node function with retry logic.
- */
-/**
- * Backoff strategy for retries
- */
-type BackoffStrategy = 'constant' | 'linear' | 'exponential';
-/**
- * Options for retry behavior
- */
-interface RetryOptions {
-    /**
-     * Maximum number of retry attempts
-     * @default 3
-     */
-    maxAttempts?: number;
-    /**
-     * Backoff strategy between retries
-     * @default 'exponential'
-     */
-    backoff?: BackoffStrategy;
-    /**
-     * Initial delay in milliseconds
-     * @default 1000
-     */
-    initialDelay?: number;
-    /**
-     * Maximum delay in milliseconds
-     * @default 30000
-     */
-    maxDelay?: number;
-    /**
-     * Optional callback when a retry occurs
-     */
-    onRetry?: (error: Error, attempt: number) => void;
-    /**
-     * Optional predicate to determine if error should be retried
-     * @default () => true (retry all errors)
-     */
-    shouldRetry?: (error: Error) => boolean;
-}
-/**
- * Wraps a node function with retry logic.
- *
- * @example
- * ```typescript
- * const robustNode = withRetry(myNode, {
- *   maxAttempts: 3,
- *   backoff: 'exponential',
- *   initialDelay: 1000,
- *   onRetry: (error, attempt) => {
- *     console.log(`Retry attempt ${attempt}: ${error.message}`);
- *   },
- * });
- *
- * graph.addNode('robust', robustNode);
- * ```
- *
- * @param node - The node function to wrap
- * @param options - Retry configuration options
- * @returns A wrapped node function with retry logic
- */
-declare function withRetry<State>(node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>, options?: RetryOptions): (state: State) => Promise<State | Partial<State>>;
-
-/**
- * Error handler pattern for LangGraph nodes
- *
- * Wraps a node function with error handling logic.
- */
-/**
- * Options for error handling behavior
- */
-interface ErrorHandlerOptions<State> {
-    /**
-     * Callback function to handle errors
-     * Should return a state update to apply when an error occurs
-     */
-    onError: (error: Error, state: State) => State | Partial<State> | Promise<State | Partial<State>>;
-    /**
-     * Optional callback for logging errors
-     */
-    logError?: (error: Error, state: State) => void;
-    /**
-     * Whether to rethrow the error after handling
-     * @default false
-     */
-    rethrow?: boolean;
-}
-/**
- * Wraps a node function with error handling logic.
- *
- * @example
- * ```typescript
- * const safeNode = withErrorHandler(myNode, {
- *   onError: (error, state) => {
- *     return { ...state, error: error.message, failed: true };
- *   },
- *   logError: (error) => {
- *     console.error('Node failed:', error);
- *   },
- * });
- *
- * graph.addNode('safe', safeNode);
- * ```
- *
- * @param node - The node function to wrap
- * @param options - Error handling configuration options
- * @returns A wrapped node function with error handling
- */
-declare function withErrorHandler<State>(node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>, options: ErrorHandlerOptions<State>): (state: State) => Promise<State | Partial<State>>;
-
 /**
  * Structured Logging Utilities
  *
@@ -2143,158 +1973,159 @@ interface Logger {
 declare function createLogger(name: string, options?: LoggerOptions): Logger;
 
 /**
- * Middleware Presets
- *
- * Pre-configured middleware combinations for common use cases.
+ * Error handler pattern for LangGraph nodes
  *
- * @module langgraph/middleware/presets
+ * Wraps a node function with error handling logic.
  */
-
 /**
- * Options for the production preset.
+ * Options for error handling behavior
  */
-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;
+interface ErrorHandlerOptions<State> {
     /**
-     * Timeout in milliseconds
-     * @default 30000 (30 seconds)
+     * Callback function to handle errors
+     * Should return a state update to apply when an error occurs
      */
-    timeout?: number;
+    onError: (error: Error, state: State) => State | Partial<State> | Promise<State | Partial<State>>;
     /**
-     * Custom retry options
+     * Optional callback for logging errors
      */
-    retryOptions?: Partial<RetryOptions>;
+    logError?: (error: Error, state: State) => void;
     /**
-     * Custom error handler options
+     * Whether to rethrow the error after handling
+     * @default false
      */
-    errorOptions?: Partial<ErrorHandlerOptions<State>>;
+    rethrow?: boolean;
 }
 /**
- * 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
+ * Wraps a node function with error handling logic.
  *
  * @example
  * ```typescript
- * const productionNode = presets.production(myNode, {
- *   nodeName: 'my-node',
- *   logger: createLogger({ level: LogLevel.INFO }),
+ * const safeNode = withErrorHandler(myNode, {
+ *   onError: (error, state) => {
+ *     return { ...state, error: error.message, failed: true };
+ *   },
+ *   logError: (error) => {
+ *     console.error('Node failed:', error);
+ *   },
  * });
+ *
+ * graph.addNode('safe', safeNode);
  * ```
+ *
+ * @param node - The node function to wrap
+ * @param options - Error handling configuration options
+ * @returns A wrapped node function with error handling
  */
-declare function production<State>(node: NodeFunction<State>, options: ProductionPresetOptions<State>): NodeFunction<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>>;
+
 /**
- * Options for the development preset.
+ * Retry pattern for LangGraph nodes
+ *
+ * Wraps a node function with retry logic.
  */
-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,
- * });
- * ```
+ * Backoff strategy for retries
  */
-declare function development<State>(node: NodeFunction<State>, options: DevelopmentPresetOptions): NodeFunction<State>;
+type BackoffStrategy = 'constant' | 'linear' | 'exponential';
 /**
- * Options for the testing preset.
+ * Options for retry behavior
  */
-interface TestingPresetOptions<State> {
+interface RetryOptions {
     /**
-     * Name of the node
+     * Maximum number of retry attempts
+     * @default 3
      */
-    nodeName: string;
+    maxAttempts?: number;
     /**
-     * Mock responses for testing
+     * Backoff strategy between retries
+     * @default 'exponential'
      */
-    mockResponse?: Partial<State>;
+    backoff?: BackoffStrategy;
     /**
-     * Simulate errors for testing
+     * Initial delay in milliseconds
+     * @default 1000
      */
-    simulateError?: Error;
+    initialDelay?: number;
     /**
-     * Delay in milliseconds for testing async behavior
+     * Maximum delay in milliseconds
+     * @default 30000
      */
-    delay?: number;
+    maxDelay?: number;
     /**
-     * Track invocations for assertions
+     * Optional callback when a retry occurs
      */
-    trackInvocations?: boolean;
+    onRetry?: (error: Error, attempt: number) => void;
+    /**
+     * Optional predicate to determine if error should be retried
+     * @default () => true (retry all errors)
+     */
+    shouldRetry?: (error: Error) => boolean;
 }
 /**
- * Testing preset for unit and integration tests.
- *
- * Includes:
- * - Mock responses
- * - Error simulation
- * - Invocation tracking
- * - Configurable delays
+ * Wraps a node function with retry logic.
  *
  * @example
  * ```typescript
- * const testNode = presets.testing(myNode, {
- *   nodeName: 'my-node',
- *   mockResponse: { result: 'mocked' },
- *   trackInvocations: true,
+ * const robustNode = withRetry(myNode, {
+ *   maxAttempts: 3,
+ *   backoff: 'exponential',
+ *   initialDelay: 1000,
+ *   onRetry: (error, attempt) => {
+ *     console.log(`Retry attempt ${attempt}: ${error.message}`);
+ *   },
  * });
+ *
+ * graph.addNode('robust', robustNode);
  * ```
+ *
+ * @param node - The node function to wrap
+ * @param options - Retry configuration options
+ * @returns A wrapped node function with retry logic
  */
-declare function testing<State>(node: NodeFunction<State>, options: TestingPresetOptions<State>): NodeFunction<State> & {
+declare function withRetry<State>(node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>, options?: RetryOptions): (state: State) => Promise<State | Partial<State>>;
+
+interface ProductionPresetOptions<State> {
+    nodeName: string;
+    logger?: Logger;
+    enableMetrics?: boolean;
+    enableTracing?: boolean;
+    enableRetry?: boolean;
+    timeout?: number;
+    retryOptions?: Partial<RetryOptions>;
+    errorOptions?: Partial<ErrorHandlerOptions<State>>;
+}
+interface DevelopmentPresetOptions {
+    nodeName: string;
+    verbose?: boolean;
+    logger?: Logger;
+}
+interface TestingPresetOptions<State> {
+    nodeName: string;
+    mockResponse?: Partial<State>;
+    simulateError?: Error;
+    delay?: number;
+    trackInvocations?: boolean;
+}
+type TestingPresetNode<State> = NodeFunction<State> & {
     invocations: State[];
 };
+
 /**
- * Preset collection for easy access.
+ * Production preset with comprehensive error handling, metrics, and tracing.
  */
+declare function production<State>(node: NodeFunction<State>, options: ProductionPresetOptions<State>): NodeFunction<State>;
+
+/**
+ * Development preset with verbose logging and debugging.
+ */
+declare function development<State>(node: NodeFunction<State>, options: DevelopmentPresetOptions): NodeFunction<State>;
+
+/**
+ * Testing preset for unit and integration tests.
+ */
+declare function testing<State>(node: NodeFunction<State>, options: TestingPresetOptions<State>): TestingPresetNode<State>;
+
 declare const presets: {
     production: typeof production;
     development: typeof development;