@agentforge/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,4076 @@
+import { z, ZodType, ZodTypeDef } from 'zod';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { AnnotationRoot, StateDefinition, StateGraph, END, MemorySaver, BaseCheckpointSaver, CheckpointTuple } from '@langchain/langgraph';
+import { RunnableConfig } from '@langchain/core/runnables';
+
+/**
+ * Tool System Types
+ *
+ * Core type definitions for the AgentForge tool system.
+ * These types define the structure and metadata for tools.
+ */
+
+/**
+ * ToolCategory - Categories for organizing tools
+ *
+ * Why use an enum?
+ * - Type safety: Can't use invalid categories
+ * - Autocomplete: IDE suggests valid options
+ * - Consistency: Everyone uses the same category names
+ *
+ * Example:
+ * ```ts
+ * const tool = { category: ToolCategory.FILE_SYSTEM };
+ * ```
+ */
+declare enum ToolCategory {
+    /**
+     * Tools for file system operations
+     * Examples: read-file, write-file, list-directory
+     */
+    FILE_SYSTEM = "file-system",
+    /**
+     * Tools for web/HTTP operations
+     * Examples: http-request, web-scrape, download-file
+     */
+    WEB = "web",
+    /**
+     * Tools for code operations
+     * Examples: execute-code, analyze-syntax, format-code
+     */
+    CODE = "code",
+    /**
+     * Tools for database operations
+     * Examples: query-database, insert-record, update-record
+     */
+    DATABASE = "database",
+    /**
+     * Tools for API integrations
+     * Examples: github-api, slack-api, stripe-api
+     */
+    API = "api",
+    /**
+     * General utility tools
+     * Examples: calculate, format-date, generate-uuid
+     */
+    UTILITY = "utility",
+    /**
+     * Custom/user-defined tools
+     * Use this for tools that don't fit other categories
+     */
+    CUSTOM = "custom"
+}
+/**
+ * ToolExample - Example usage of a tool
+ *
+ * Why examples?
+ * - Help LLMs understand how to use the tool
+ * - Provide documentation for developers
+ * - Enable few-shot learning in prompts
+ *
+ * Example:
+ * ```ts
+ * const example: ToolExample = {
+ *   description: 'Read a text file',
+ *   input: { path: './README.md' },
+ *   output: '# My Project\n\nWelcome...',
+ *   explanation: 'Reads the file and returns its contents as a string'
+ * };
+ * ```
+ */
+interface ToolExample {
+    /**
+     * What this example demonstrates
+     * Should be concise and clear
+     */
+    description: string;
+    /**
+     * Example input parameters
+     * Must match the tool's schema
+     */
+    input: Record<string, unknown>;
+    /**
+     * Expected output (optional)
+     * Helps users understand what to expect
+     */
+    output?: unknown;
+    /**
+     * Additional explanation (optional)
+     * Why this example works, edge cases, etc.
+     */
+    explanation?: string;
+}
+/**
+ * ToolMetadata - Rich metadata for a tool
+ *
+ * Why so much metadata?
+ * - Better LLM understanding: More context = better tool selection
+ * - Better developer experience: Clear documentation
+ * - Better discoverability: Search by tags, categories
+ * - Better maintenance: Version tracking, deprecation warnings
+ *
+ * Example:
+ * ```ts
+ * const metadata: ToolMetadata = {
+ *   name: 'read-file',
+ *   displayName: 'Read File',
+ *   description: 'Read contents of a file from the file system',
+ *   category: ToolCategory.FILE_SYSTEM,
+ *   tags: ['file', 'read', 'io'],
+ *   examples: [{ description: 'Read README', input: { path: './README.md' } }],
+ *   usageNotes: 'Paths are relative to current working directory',
+ *   limitations: ['Cannot read files larger than 10MB'],
+ *   version: '1.0.0',
+ *   author: 'AgentForge'
+ * };
+ * ```
+ */
+interface ToolMetadata {
+    /**
+     * Unique identifier for the tool
+     * Must be kebab-case (lowercase with hyphens)
+     * Examples: 'read-file', 'http-request', 'query-database'
+     */
+    name: string;
+    /**
+     * Clear description of what the tool does
+     * Should be 1-2 sentences, written for LLMs to understand
+     * Example: 'Read the contents of a file from the file system'
+     */
+    description: string;
+    /**
+     * Primary category for this tool
+     * Used for grouping and filtering
+     */
+    category: ToolCategory;
+    /**
+     * Human-readable display name (optional)
+     * Example: 'Read File' instead of 'read-file'
+     */
+    displayName?: string;
+    /**
+     * Tags for search and filtering (optional)
+     * Example: ['file', 'read', 'io', 'filesystem']
+     */
+    tags?: string[];
+    /**
+     * Usage examples (optional but highly recommended)
+     * Helps LLMs understand how to use the tool
+     */
+    examples?: ToolExample[];
+    /**
+     * Additional usage notes (optional)
+     * Important details about how to use the tool
+     * Example: 'Paths are relative to the current working directory'
+     */
+    usageNotes?: string;
+    /**
+     * Known limitations (optional)
+     * What the tool cannot do
+     * Example: ['Cannot read files larger than 10MB', 'Requires read permissions']
+     */
+    limitations?: string[];
+    /**
+     * Tool version (optional)
+     * Semantic versioning recommended
+     * Example: '1.0.0'
+     */
+    version?: string;
+    /**
+     * Tool author (optional)
+     * Who created/maintains this tool
+     * Example: 'AgentForge Team'
+     */
+    author?: string;
+    /**
+     * Deprecation flag (optional)
+     * Set to true if this tool should no longer be used
+     */
+    deprecated?: boolean;
+    /**
+     * Replacement tool name (optional)
+     * If deprecated, what tool should be used instead?
+     * Example: 'read-file-v2'
+     */
+    replacedBy?: string;
+}
+/**
+ * Tool - Complete tool definition
+ *
+ * This is the main interface that combines:
+ * - Metadata: What the tool is and how to use it
+ * - Schema: What inputs it accepts (validated with Zod)
+ * - Execute: The actual implementation
+ *
+ * Why generic types?
+ * - TInput: Type of the input parameters (inferred from schema)
+ * - TOutput: Type of the return value
+ * - This gives us full type safety!
+ *
+ * Example:
+ * ```ts
+ * const readFileTool: Tool<{ path: string }, string> = {
+ *   metadata: { name: 'read-file', ... },
+ *   schema: z.object({ path: z.string() }),
+ *   execute: async ({ path }) => {
+ *     // Implementation here
+ *     return fileContents;
+ *   }
+ * };
+ * ```
+ */
+interface Tool<TInput = unknown, TOutput = unknown> {
+    /**
+     * Rich metadata about the tool
+     */
+    metadata: ToolMetadata;
+    /**
+     * Zod schema for input validation
+     *
+     * Why Zod?
+     * - Runtime validation: Catch errors before execution
+     * - Type inference: TypeScript types from schema
+     * - Great error messages: Clear validation errors
+     * - JSON Schema conversion: For LangChain integration
+     */
+    schema: z.ZodSchema<TInput>;
+    /**
+     * Tool implementation
+     *
+     * Why async?
+     * - Most tools do I/O (files, network, database)
+     * - Async is more flexible (can handle both sync and async)
+     *
+     * The input is automatically validated against the schema
+     * before this function is called.
+     */
+    execute: (input: TInput) => Promise<TOutput>;
+}
+
+/**
+ * Tool System Schemas
+ *
+ * Zod schemas for runtime validation of tool metadata and configuration.
+ *
+ * Why Zod schemas?
+ * - Runtime validation: Catch errors when tools are created
+ * - Type inference: TypeScript types are automatically inferred
+ * - Great errors: Clear messages when validation fails
+ * - JSON Schema: Can convert to JSON Schema for LangChain
+ */
+
+/**
+ * Schema for ToolCategory
+ *
+ * This validates that a value is one of the valid ToolCategory enum values.
+ *
+ * Example:
+ * ```ts
+ * ToolCategorySchema.parse('file-system');  // ✅ Valid
+ * ToolCategorySchema.parse('invalid');      // ❌ Throws ZodError
+ * ```
+ */
+declare const ToolCategorySchema: z.ZodNativeEnum<typeof ToolCategory>;
+/**
+ * Schema for ToolExample
+ *
+ * Validates the structure of tool usage examples.
+ *
+ * Example:
+ * ```ts
+ * ToolExampleSchema.parse({
+ *   description: 'Read a file',
+ *   input: { path: './file.txt' },
+ *   output: 'file contents',
+ *   explanation: 'Reads and returns file contents'
+ * });
+ * ```
+ */
+declare const ToolExampleSchema: z.ZodObject<{
+    /**
+     * Description must be a non-empty string
+     */
+    description: z.ZodString;
+    /**
+     * Input must be an object (can have any properties)
+     */
+    input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    /**
+     * Output is optional and can be anything
+     */
+    output: z.ZodOptional<z.ZodUnknown>;
+    /**
+     * Explanation is optional but must be non-empty if provided
+     */
+    explanation: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    input: Record<string, unknown>;
+    output?: unknown;
+    explanation?: string | undefined;
+}, {
+    description: string;
+    input: Record<string, unknown>;
+    output?: unknown;
+    explanation?: string | undefined;
+}>;
+/**
+ * Schema for tool names
+ *
+ * Tool names must be:
+ * - Lowercase letters, numbers, and hyphens only
+ * - Start with a letter
+ * - Not start or end with a hyphen
+ * - Between 2 and 50 characters
+ *
+ * Valid: 'read-file', 'http-request', 'query-db'
+ * Invalid: 'ReadFile', 'read_file', '-read-file', 'r'
+ */
+declare const ToolNameSchema: z.ZodString;
+/**
+ * Schema for ToolMetadata
+ *
+ * Validates all tool metadata fields with appropriate constraints.
+ *
+ * Example:
+ * ```ts
+ * ToolMetadataSchema.parse({
+ *   name: 'read-file',
+ *   description: 'Read a file from the file system',
+ *   category: ToolCategory.FILE_SYSTEM,
+ *   tags: ['file', 'read'],
+ *   examples: [{ description: 'Read README', input: { path: './README.md' } }]
+ * });
+ * ```
+ */
+declare const ToolMetadataSchema: z.ZodObject<{
+    /**
+     * Tool name - must be valid kebab-case
+     */
+    name: z.ZodString;
+    /**
+     * Description - must be meaningful (at least 10 characters)
+     */
+    description: z.ZodString;
+    /**
+     * Category - must be a valid ToolCategory
+     */
+    category: z.ZodNativeEnum<typeof ToolCategory>;
+    /**
+     * Display name - if provided, must be non-empty
+     */
+    displayName: z.ZodOptional<z.ZodString>;
+    /**
+     * Tags - array of non-empty strings
+     */
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Examples - array of valid ToolExample objects
+     */
+    examples: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /**
+         * Description must be a non-empty string
+         */
+        description: z.ZodString;
+        /**
+         * Input must be an object (can have any properties)
+         */
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        /**
+         * Output is optional and can be anything
+         */
+        output: z.ZodOptional<z.ZodUnknown>;
+        /**
+         * Explanation is optional but must be non-empty if provided
+         */
+        explanation: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        input: Record<string, unknown>;
+        output?: unknown;
+        explanation?: string | undefined;
+    }, {
+        description: string;
+        input: Record<string, unknown>;
+        output?: unknown;
+        explanation?: string | undefined;
+    }>, "many">>;
+    /**
+     * Usage notes - if provided, must be meaningful
+     */
+    usageNotes: z.ZodOptional<z.ZodString>;
+    /**
+     * Limitations - array of non-empty strings
+     */
+    limitations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Version - if provided, should follow semver format
+     * Examples: '1.0.0', '2.1.3', '0.1.0-beta', '1.0.0-alpha.1'
+     */
+    version: z.ZodOptional<z.ZodString>;
+    /**
+     * Author - if provided, must be non-empty
+     */
+    author: z.ZodOptional<z.ZodString>;
+    /**
+     * Deprecated flag
+     */
+    deprecated: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Replacement tool name - if provided, must be valid tool name
+     */
+    replacedBy: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    name: string;
+    category: ToolCategory;
+    displayName?: string | undefined;
+    tags?: string[] | undefined;
+    examples?: {
+        description: string;
+        input: Record<string, unknown>;
+        output?: unknown;
+        explanation?: string | undefined;
+    }[] | undefined;
+    usageNotes?: string | undefined;
+    limitations?: string[] | undefined;
+    version?: string | undefined;
+    author?: string | undefined;
+    deprecated?: boolean | undefined;
+    replacedBy?: string | undefined;
+}, {
+    description: string;
+    name: string;
+    category: ToolCategory;
+    displayName?: string | undefined;
+    tags?: string[] | undefined;
+    examples?: {
+        description: string;
+        input: Record<string, unknown>;
+        output?: unknown;
+        explanation?: string | undefined;
+    }[] | undefined;
+    usageNotes?: string | undefined;
+    limitations?: string[] | undefined;
+    version?: string | undefined;
+    author?: string | undefined;
+    deprecated?: boolean | undefined;
+    replacedBy?: string | undefined;
+}>;
+/**
+ * Helper function to validate tool metadata
+ *
+ * This is a convenience function that validates metadata and returns
+ * a typed result with helpful error messages.
+ *
+ * Example:
+ * ```ts
+ * const result = validateToolMetadata({
+ *   name: 'read-file',
+ *   description: 'Read a file',
+ *   category: ToolCategory.FILE_SYSTEM
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Valid metadata:', result.data);
+ * } else {
+ *   console.error('Validation errors:', result.error.errors);
+ * }
+ * ```
+ */
+declare function validateToolMetadata(metadata: unknown): z.SafeParseReturnType<{
+    description: string;
+    name: string;
+    category: ToolCategory;
+    displayName?: string | undefined;
+    tags?: string[] | undefined;
+    examples?: {
+        description: string;
+        input: Record<string, unknown>;
+        output?: unknown;
+        explanation?: string | undefined;
+    }[] | undefined;
+    usageNotes?: string | undefined;
+    limitations?: string[] | undefined;
+    version?: string | undefined;
+    author?: string | undefined;
+    deprecated?: boolean | undefined;
+    replacedBy?: string | undefined;
+}, {
+    description: string;
+    name: string;
+    category: ToolCategory;
+    displayName?: string | undefined;
+    tags?: string[] | undefined;
+    examples?: {
+        description: string;
+        input: Record<string, unknown>;
+        output?: unknown;
+        explanation?: string | undefined;
+    }[] | undefined;
+    usageNotes?: string | undefined;
+    limitations?: string[] | undefined;
+    version?: string | undefined;
+    author?: string | undefined;
+    deprecated?: boolean | undefined;
+    replacedBy?: string | undefined;
+}>;
+/**
+ * Helper function to validate tool name
+ *
+ * Quick validation for just the tool name.
+ *
+ * Example:
+ * ```ts
+ * validateToolName('read-file');     // ✅ Returns true
+ * validateToolName('ReadFile');      // ❌ Returns false
+ * ```
+ */
+declare function validateToolName(name: string): boolean;
+
+/**
+ * Schema Validation Utilities
+ *
+ * Helpers to ensure schemas are properly configured for LLM usage,
+ * including enforcing descriptions on all fields.
+ */
+
+/**
+ * Error thrown when a schema field is missing a description
+ */
+declare class MissingDescriptionError extends Error {
+    readonly fieldPath: string[];
+    readonly fieldType: string;
+    constructor(fieldPath: string[], fieldType: string);
+}
+/**
+ * Validates that all fields in a Zod schema have descriptions
+ *
+ * Why enforce descriptions?
+ * - LLMs need context to understand what each parameter does
+ * - Descriptions are converted to JSON Schema for tool calling
+ * - Better descriptions = Better tool selection and usage
+ *
+ * @param schema - The Zod schema to validate
+ * @param fieldPath - Internal: current field path for nested objects
+ * @throws {MissingDescriptionError} If any field lacks a description
+ *
+ * @example
+ * ```ts
+ * // ❌ This will throw - no descriptions
+ * const badSchema = z.object({
+ *   name: z.string(),
+ *   age: z.number()
+ * });
+ * validateSchemaDescriptions(badSchema); // Throws!
+ *
+ * // ✅ This is valid - all fields have descriptions
+ * const goodSchema = z.object({
+ *   name: z.string().describe('User name'),
+ *   age: z.number().describe('User age in years')
+ * });
+ * validateSchemaDescriptions(goodSchema); // OK!
+ * ```
+ */
+declare function validateSchemaDescriptions(schema: z.ZodTypeAny, fieldPath?: string[]): void;
+/**
+ * Safe version of validateSchemaDescriptions that returns a result
+ * instead of throwing
+ *
+ * @param schema - The Zod schema to validate
+ * @returns Object with success flag and optional error
+ *
+ * @example
+ * ```ts
+ * const result = safeValidateSchemaDescriptions(schema);
+ * if (!result.success) {
+ *   console.error('Missing descriptions:', result.error.message);
+ * }
+ * ```
+ */
+declare function safeValidateSchemaDescriptions(schema: z.ZodTypeAny): {
+    success: boolean;
+    error?: MissingDescriptionError;
+};
+/**
+ * Helper to get all missing descriptions from a schema
+ *
+ * @param schema - The Zod schema to check
+ * @returns Array of field paths that are missing descriptions
+ *
+ * @example
+ * ```ts
+ * const missing = getMissingDescriptions(schema);
+ * if (missing.length > 0) {
+ *   console.log('Fields missing descriptions:', missing);
+ * }
+ * ```
+ */
+declare function getMissingDescriptions(schema: z.ZodTypeAny): string[];
+
+/**
+ * Tool Creation Helpers
+ *
+ * Utility functions to create tools with automatic validation.
+ */
+
+/**
+ * Create a tool with automatic validation
+ *
+ * This function validates:
+ * 1. Metadata is valid (name, description, category, etc.)
+ * 2. Schema has descriptions on ALL fields (enforced!)
+ *
+ * Why enforce descriptions?
+ * - LLMs need context to understand parameters
+ * - Better descriptions = Better tool usage
+ * - Prevents common mistakes
+ *
+ * @param metadata - Tool metadata
+ * @param schema - Zod schema for input validation (must have descriptions!)
+ * @param execute - Tool implementation
+ * @returns Validated tool
+ * @throws {Error} If metadata is invalid or schema is missing descriptions
+ *
+ * @example
+ * ```ts
+ * // ✅ This works - all fields have descriptions
+ * const tool = createTool(
+ *   {
+ *     name: 'read-file',
+ *     description: 'Read a file from the file system',
+ *     category: ToolCategory.FILE_SYSTEM,
+ *   },
+ *   z.object({
+ *     path: z.string().describe('Path to the file to read'),
+ *   }),
+ *   async ({ path }) => {
+ *     // Implementation
+ *   }
+ * );
+ *
+ * // ❌ This throws - missing description on 'path'
+ * const badTool = createTool(
+ *   { name: 'bad', description: 'Bad tool', category: ToolCategory.UTILITY },
+ *   z.object({
+ *     path: z.string(), // No .describe()!
+ *   }),
+ *   async ({ path }) => {}
+ * );
+ * ```
+ */
+declare function createTool<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, execute: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
+/**
+ * Create a tool without enforcing schema descriptions
+ *
+ * ⚠️ WARNING: Only use this if you have a good reason to skip description validation.
+ * In most cases, you should use `createTool()` instead.
+ *
+ * This is useful for:
+ * - Migration from existing code
+ * - Tools with dynamic schemas
+ * - Testing
+ *
+ * @param metadata - Tool metadata
+ * @param schema - Zod schema for input validation
+ * @param execute - Tool implementation
+ * @returns Tool (without schema validation)
+ */
+declare function createToolUnsafe<TInput = unknown, TOutput = unknown>(metadata: ToolMetadata, schema: z.ZodSchema<TInput>, execute: (input: TInput) => Promise<TOutput>): Tool<TInput, TOutput>;
+/**
+ * Validate an existing tool
+ *
+ * Checks both metadata and schema descriptions.
+ *
+ * @param tool - The tool to validate
+ * @returns Validation result with success flag and errors
+ *
+ * @example
+ * ```ts
+ * const result = validateTool(myTool);
+ * if (!result.success) {
+ *   console.error('Tool validation failed:', result.errors);
+ * }
+ * ```
+ */
+declare function validateTool(tool: Tool): {
+    success: boolean;
+    errors: string[];
+};
+
+/**
+ * Tool Builder API
+ *
+ * Fluent interface for creating tools with automatic validation.
+ *
+ * @example
+ * ```ts
+ * const tool = createToolBuilder()
+ *   .name('read-file')
+ *   .description('Read a file from the file system')
+ *   .category(ToolCategory.FILE_SYSTEM)
+ *   .tags(['file', 'read', 'io'])
+ *   .schema(z.object({
+ *     path: z.string().describe('Path to the file')
+ *   }))
+ *   .implement(async ({ path }) => {
+ *     // Implementation
+ *   })
+ *   .build();
+ * ```
+ */
+
+/**
+ * Builder for creating tools with a fluent API
+ *
+ * This provides a more ergonomic way to create tools compared to
+ * manually constructing the metadata object.
+ */
+declare class ToolBuilder<TInput = unknown, TOutput = unknown> {
+    private metadata;
+    private _schema?;
+    private _execute?;
+    /**
+     * Set the tool name (required)
+     *
+     * @param name - Tool name in kebab-case (e.g., 'read-file')
+     */
+    name(name: string): this;
+    /**
+     * Set the tool description (required)
+     *
+     * @param description - Clear description of what the tool does
+     */
+    description(description: string): this;
+    /**
+     * Set the tool category (required)
+     *
+     * @param category - Tool category for organization
+     */
+    category(category: ToolCategory): this;
+    /**
+     * Set the display name (optional)
+     *
+     * @param displayName - Human-friendly name for UI display
+     */
+    displayName(displayName: string): this;
+    /**
+     * Set tags for searchability (optional)
+     *
+     * @param tags - Array of tags for categorization and search
+     */
+    tags(tags: string[]): this;
+    /**
+     * Add a single tag (optional)
+     *
+     * @param tag - Tag to add
+     */
+    tag(tag: string): this;
+    /**
+     * Add an example (optional)
+     *
+     * @param example - Usage example for the tool
+     */
+    example(example: ToolExample): this;
+    /**
+     * Set usage notes (optional)
+     *
+     * @param notes - Important usage information
+     */
+    usageNotes(notes: string): this;
+    /**
+     * Set limitations (optional)
+     *
+     * @param limitations - Array of known limitations
+     */
+    limitations(limitations: string[]): this;
+    /**
+     * Add a single limitation (optional)
+     *
+     * @param limitation - Limitation to add
+     */
+    limitation(limitation: string): this;
+    /**
+     * Set version (optional)
+     *
+     * @param version - Semantic version string
+     */
+    version(version: string): this;
+    /**
+     * Set author (optional)
+     *
+     * @param author - Tool author name
+     */
+    author(author: string): this;
+    /**
+     * Set the input schema (required)
+     *
+     * All fields MUST have .describe() for LLM understanding!
+     *
+     * @param schema - Zod schema for input validation
+     */
+    schema<T>(schema: z.ZodSchema<T>): ToolBuilder<T, TOutput>;
+    /**
+     * Set the implementation function (required)
+     *
+     * @param execute - Async function that implements the tool
+     */
+    implement<T>(execute: (input: TInput) => Promise<T>): ToolBuilder<TInput, T>;
+    /**
+     * Build the tool with validation
+     *
+     * Validates:
+     * - All required fields are present
+     * - Metadata is valid
+     * - Schema has descriptions on all fields
+     *
+     * @returns The validated tool
+     * @throws {Error} If validation fails
+     */
+    build(): Tool<TInput, TOutput>;
+}
+/**
+ * Create a new tool builder
+ *
+ * @example
+ * ```ts
+ * const tool = toolBuilder()
+ *   .name('my-tool')
+ *   .description('Does something useful')
+ *   .category(ToolCategory.UTILITY)
+ *   .schema(z.object({ input: z.string().describe('Input') }))
+ *   .implement(async ({ input }) => input)
+ *   .build();
+ * ```
+ */
+declare function toolBuilder(): ToolBuilder;
+
+/**
+ * Tool Registry
+ *
+ * Central registry for managing and querying tools.
+ * Provides CRUD operations, querying, and event notifications.
+ *
+ * @example
+ * ```ts
+ * const registry = new ToolRegistry();
+ *
+ * registry.register(readFileTool);
+ * registry.register(writeFileTool);
+ *
+ * const fileTool = registry.get('read-file');
+ * const fileTools = registry.getByCategory(ToolCategory.FILE_SYSTEM);
+ * ```
+ */
+
+/**
+ * Registry events
+ */
+declare enum RegistryEvent {
+    TOOL_REGISTERED = "tool:registered",
+    TOOL_REMOVED = "tool:removed",
+    TOOL_UPDATED = "tool:updated",
+    REGISTRY_CLEARED = "registry:cleared"
+}
+/**
+ * Event handler type
+ */
+type EventHandler = (data: any) => void;
+/**
+ * Options for generating tool prompts
+ */
+interface PromptOptions {
+    /** Include usage examples in the prompt */
+    includeExamples?: boolean;
+    /** Include usage notes in the prompt */
+    includeNotes?: boolean;
+    /** Include limitations in the prompt */
+    includeLimitations?: boolean;
+    /** Group tools by category */
+    groupByCategory?: boolean;
+    /** Filter by specific categories */
+    categories?: ToolCategory[];
+    /** Maximum number of examples to include per tool */
+    maxExamplesPerTool?: number;
+}
+/**
+ * Tool Registry - Central registry for managing tools
+ *
+ * Features:
+ * - CRUD operations (register, get, remove, update)
+ * - Query operations (by category, tag, search)
+ * - Bulk operations (registerMany, clear)
+ * - Event system for observability
+ *
+ * @example
+ * ```ts
+ * const registry = new ToolRegistry();
+ *
+ * // Register tools
+ * registry.register(myTool);
+ * registry.registerMany([tool1, tool2, tool3]);
+ *
+ * // Query tools
+ * const tool = registry.get('my-tool');
+ * const fileTools = registry.getByCategory(ToolCategory.FILE_SYSTEM);
+ * const searchResults = registry.search('file');
+ *
+ * // Listen to events
+ * registry.on(RegistryEvent.TOOL_REGISTERED, (tool) => {
+ *   console.log('Tool registered:', tool.metadata.name);
+ * });
+ * ```
+ */
+declare class ToolRegistry {
+    private tools;
+    private eventHandlers;
+    /**
+     * Register a tool in the registry
+     *
+     * @param tool - The tool to register
+     * @throws Error if a tool with the same name already exists
+     *
+     * @example
+     * ```ts
+     * registry.register(readFileTool);
+     * ```
+     */
+    register(tool: Tool<any, any>): void;
+    /**
+     * Get a tool by name
+     *
+     * @param name - The tool name
+     * @returns The tool, or undefined if not found
+     *
+     * @example
+     * ```ts
+     * const tool = registry.get('read-file');
+     * if (tool) {
+     *   const result = await tool.execute({ path: './file.txt' });
+     * }
+     * ```
+     */
+    get(name: string): Tool<any, any> | undefined;
+    /**
+     * Check if a tool exists in the registry
+     *
+     * @param name - The tool name
+     * @returns True if the tool exists
+     *
+     * @example
+     * ```ts
+     * if (registry.has('read-file')) {
+     *   console.log('Tool exists!');
+     * }
+     * ```
+     */
+    has(name: string): boolean;
+    /**
+     * Remove a tool from the registry
+     *
+     * @param name - The tool name
+     * @returns True if the tool was removed, false if it didn't exist
+     *
+     * @example
+     * ```ts
+     * const removed = registry.remove('read-file');
+     * console.log(removed ? 'Removed' : 'Not found');
+     * ```
+     */
+    remove(name: string): boolean;
+    /**
+     * Update an existing tool
+     *
+     * @param name - The tool name
+     * @param tool - The new tool definition
+     * @returns True if updated, false if the tool didn't exist
+     *
+     * @example
+     * ```ts
+     * const updated = registry.update('read-file', newReadFileTool);
+     * ```
+     */
+    update(name: string, tool: Tool<any, any>): boolean;
+    /**
+     * Get all registered tools
+     *
+     * @returns Array of all tools
+     *
+     * @example
+     * ```ts
+     * const allTools = registry.getAll();
+     * console.log(`Total tools: ${allTools.length}`);
+     * ```
+     */
+    getAll(): Tool<any, any>[];
+    /**
+     * Get tools by category
+     *
+     * @param category - The tool category
+     * @returns Array of tools in the category
+     *
+     * @example
+     * ```ts
+     * const fileTools = registry.getByCategory(ToolCategory.FILE_SYSTEM);
+     * ```
+     */
+    getByCategory(category: ToolCategory): Tool<any, any>[];
+    /**
+     * Get tools by tag
+     *
+     * @param tag - The tag to search for
+     * @returns Array of tools with the tag
+     *
+     * @example
+     * ```ts
+     * const fileTools = registry.getByTag('file');
+     * ```
+     */
+    getByTag(tag: string): Tool<any, any>[];
+    /**
+     * Search tools by name or description
+     *
+     * Case-insensitive search across tool names, display names, and descriptions.
+     *
+     * @param query - The search query
+     * @returns Array of matching tools
+     *
+     * @example
+     * ```ts
+     * const results = registry.search('file');
+     * // Returns tools with 'file' in name or description
+     * ```
+     */
+    search(query: string): Tool<any, any>[];
+    /**
+     * Register multiple tools at once
+     *
+     * @param tools - Array of tools to register
+     * @throws Error if any tool name conflicts with existing tools
+     *
+     * @example
+     * ```ts
+     * registry.registerMany([tool1, tool2, tool3]);
+     * ```
+     */
+    registerMany(tools: Tool<any, any>[]): void;
+    /**
+     * Clear all tools from the registry
+     *
+     * @example
+     * ```ts
+     * registry.clear();
+     * console.log(registry.size()); // 0
+     * ```
+     */
+    clear(): void;
+    /**
+     * Get the number of registered tools
+     *
+     * @returns Number of tools in the registry
+     *
+     * @example
+     * ```ts
+     * console.log(`Registry has ${registry.size()} tools`);
+     * ```
+     */
+    size(): number;
+    /**
+     * Get all tool names
+     *
+     * @returns Array of tool names
+     *
+     * @example
+     * ```ts
+     * const names = registry.getNames();
+     * console.log('Available tools:', names.join(', '));
+     * ```
+     */
+    getNames(): string[];
+    /**
+     * Register an event handler
+     *
+     * @param event - The event to listen for
+     * @param handler - The handler function
+     *
+     * @example
+     * ```ts
+     * registry.on(RegistryEvent.TOOL_REGISTERED, (tool) => {
+     *   console.log('New tool:', tool.metadata.name);
+     * });
+     * ```
+     */
+    on(event: RegistryEvent, handler: EventHandler): void;
+    /**
+     * Unregister an event handler
+     *
+     * @param event - The event to stop listening for
+     * @param handler - The handler function to remove
+     *
+     * @example
+     * ```ts
+     * const handler = (tool) => console.log(tool);
+     * registry.on(RegistryEvent.TOOL_REGISTERED, handler);
+     * registry.off(RegistryEvent.TOOL_REGISTERED, handler);
+     * ```
+     */
+    off(event: RegistryEvent, handler: EventHandler): void;
+    /**
+     * Emit an event to all registered handlers
+     *
+     * @param event - The event to emit
+     * @param data - The event data
+     * @private
+     */
+    private emit;
+    /**
+     * Convert all registered tools to LangChain format
+     *
+     * This allows the entire registry to be used with LangChain agents.
+     *
+     * @returns Array of LangChain DynamicStructuredTools
+     *
+     * @example
+     * ```ts
+     * const registry = new ToolRegistry();
+     * registry.registerMany([tool1, tool2, tool3]);
+     *
+     * const langchainTools = registry.toLangChainTools();
+     *
+     * const agent = createAgent({
+     *   model: new ChatOpenAI(),
+     *   tools: langchainTools,
+     * });
+     * ```
+     */
+    toLangChainTools(): DynamicStructuredTool[];
+    /**
+     * Generate a formatted prompt describing all tools
+     *
+     * Creates a human-readable description of all tools in the registry,
+     * suitable for inclusion in LLM prompts.
+     *
+     * @param options - Options for customizing the prompt
+     * @returns Formatted prompt string
+     *
+     * @example
+     * ```ts
+     * const prompt = registry.generatePrompt({
+     *   includeExamples: true,
+     *   groupByCategory: true,
+     *   maxExamplesPerTool: 2,
+     * });
+     *
+     * console.log(prompt);
+     * // Available Tools:
+     * //
+     * // FILE SYSTEM TOOLS:
+     * // - read-file: Read a file from the file system
+     * //   Parameters: path (string)
+     * //   Example: Read a text file
+     * //     Input: { "path": "./README.md" }
+     * // ...
+     * ```
+     */
+    generatePrompt(options?: PromptOptions): string;
+    /**
+     * Format a single tool for inclusion in a prompt
+     *
+     * @param tool - The tool to format
+     * @param options - Formatting options
+     * @returns Array of formatted lines
+     * @private
+     */
+    private formatToolForPrompt;
+}
+
+/**
+ * Tool Executor - Async tool execution with resource management
+ * @module tools/executor
+ */
+type Priority = 'low' | 'normal' | 'high' | 'critical';
+type BackoffStrategy$1 = 'linear' | 'exponential' | 'fixed';
+interface RetryPolicy {
+    maxAttempts: number;
+    backoff: BackoffStrategy$1;
+    initialDelay?: number;
+    maxDelay?: number;
+    retryableErrors?: string[];
+}
+interface ToolExecutorConfig {
+    maxConcurrent?: number;
+    timeout?: number;
+    retryPolicy?: RetryPolicy;
+    priorityFn?: (tool: any) => Priority;
+    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;
+}
+interface ToolExecution {
+    tool: any;
+    input: any;
+    priority?: Priority;
+}
+interface ExecutionMetrics {
+    totalExecutions: number;
+    successfulExecutions: number;
+    failedExecutions: number;
+    totalDuration: number;
+    averageDuration: number;
+    byPriority: Record<Priority, number>;
+}
+/**
+ * Create a tool executor with resource management
+ */
+declare function createToolExecutor(config?: ToolExecutorConfig): {
+    execute: (tool: any, input: any, options?: {
+        priority?: Priority;
+    }) => Promise<any>;
+    executeParallel: (executions: ToolExecution[]) => Promise<any[]>;
+    getMetrics: () => ExecutionMetrics;
+    resetMetrics: () => void;
+    getQueueStatus: () => {
+        queueLength: number;
+        activeExecutions: number;
+        maxConcurrent: number;
+    };
+};
+
+/**
+ * Tool Lifecycle Management - Manage tool initialization, cleanup, and resources
+ * @module tools/lifecycle
+ */
+interface HealthCheckResult {
+    healthy: boolean;
+    error?: string;
+    metadata?: Record<string, any>;
+}
+interface ManagedToolConfig<TContext = any, TInput = any, TOutput = any> {
+    name: string;
+    description: string;
+    initialize?: (this: ManagedTool<TContext, TInput, TOutput>) => Promise<void>;
+    execute: (this: ManagedTool<TContext, TInput, TOutput>, input: TInput) => Promise<TOutput>;
+    cleanup?: (this: ManagedTool<TContext, TInput, TOutput>) => Promise<void>;
+    healthCheck?: (this: ManagedTool<TContext, TInput, TOutput>) => Promise<HealthCheckResult>;
+    context?: TContext;
+    autoCleanup?: boolean;
+    healthCheckInterval?: number;
+}
+interface ManagedToolStats {
+    initialized: boolean;
+    totalExecutions: number;
+    successfulExecutions: number;
+    failedExecutions: number;
+    lastExecutionTime?: number;
+    lastHealthCheck?: HealthCheckResult;
+    lastHealthCheckTime?: number;
+}
+/**
+ * Managed tool with lifecycle hooks
+ */
+declare class ManagedTool<TContext = any, TInput = any, TOutput = any> {
+    readonly name: string;
+    readonly description: string;
+    private readonly initializeFn?;
+    private readonly executeFn;
+    private readonly cleanupFn?;
+    private readonly healthCheckFn?;
+    private readonly autoCleanup;
+    private readonly healthCheckInterval?;
+    private _initialized;
+    private _context;
+    private _stats;
+    private _healthCheckTimer?;
+    constructor(config: ManagedToolConfig<TContext, TInput, TOutput>);
+    /**
+     * Get the tool context (e.g., connection pool, API client)
+     */
+    get context(): TContext;
+    /**
+     * Set the tool context
+     */
+    set context(value: TContext);
+    /**
+     * Check if tool is initialized
+     */
+    get initialized(): boolean;
+    /**
+     * Initialize the tool
+     */
+    initialize(): Promise<void>;
+    /**
+     * Execute the tool
+     */
+    execute(input: TInput): Promise<TOutput>;
+    /**
+     * Cleanup the tool
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Run health check
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Get tool statistics
+     */
+    getStats(): ManagedToolStats;
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+    /**
+     * Convert to LangChain tool format
+     */
+    toLangChainTool(): {
+        name: string;
+        description: string;
+        invoke: (input: TInput) => Promise<TOutput>;
+    };
+}
+/**
+ * Create a managed tool
+ */
+declare function createManagedTool<TContext = any, TInput = any, TOutput = any>(config: ManagedToolConfig<TContext, TInput, TOutput>): ManagedTool<TContext, TInput, TOutput>;
+
+/**
+ * Tool Composition - Compose tools into higher-level operations
+ * @module tools/composition
+ */
+interface ComposedTool {
+    name: string;
+    description: string;
+    invoke: (input: any) => Promise<any>;
+}
+interface ConditionalConfig {
+    condition: (input: any) => boolean | Promise<boolean>;
+    onTrue: ComposedTool;
+    onFalse: ComposedTool;
+}
+interface ComposeToolConfig {
+    name: string;
+    description?: string;
+    steps: Array<ComposedTool | ComposedTool[] | ConditionalConfig>;
+    transformResult?: (result: any) => any;
+}
+/**
+ * Execute tools sequentially
+ */
+declare function sequential(tools: ComposedTool[]): ComposedTool;
+/**
+ * Execute tools in parallel
+ */
+declare function parallel(tools: ComposedTool[]): ComposedTool;
+/**
+ * Execute tool conditionally
+ */
+declare function conditional(config: ConditionalConfig): ComposedTool;
+/**
+ * Compose tools into a complex workflow
+ */
+declare function composeTool(config: ComposeToolConfig): ComposedTool;
+/**
+ * Create a tool that retries on failure
+ */
+declare function retry(tool: ComposedTool, options?: {
+    maxAttempts?: number;
+    delay?: number;
+    backoff?: 'linear' | 'exponential';
+}): ComposedTool;
+/**
+ * Create a tool that times out
+ */
+declare function timeout(tool: ComposedTool, ms: number): ComposedTool;
+/**
+ * Create a tool that caches results
+ */
+declare function cache(tool: ComposedTool, ttl?: number): ComposedTool;
+
+/**
+ * Tool Mocking & Testing - Mock tools for testing
+ * @module tools/testing
+ */
+interface MockToolResponse {
+    input: any;
+    output?: any;
+    error?: Error;
+}
+interface MockToolConfig {
+    name: string;
+    description?: string;
+    responses?: MockToolResponse[];
+    defaultResponse?: any;
+    latency?: {
+        min: number;
+        max: number;
+    } | number;
+    errorRate?: number;
+}
+interface ToolInvocation {
+    input: any;
+    output?: any;
+    error?: Error;
+    timestamp: number;
+    duration: number;
+}
+interface ToolSimulatorConfig {
+    tools: Array<{
+        name: string;
+        invoke: (input: any) => Promise<any>;
+    }>;
+    errorRate?: number;
+    latency?: {
+        mean: number;
+        stddev: number;
+    };
+    recordInvocations?: boolean;
+}
+/**
+ * Create a mock tool for testing
+ */
+declare function createMockTool(config: MockToolConfig): {
+    name: string;
+    description: string;
+    invoke: (input: any) => Promise<any>;
+    getInvocations: () => ToolInvocation[];
+    clearInvocations: () => void;
+};
+/**
+ * Create a tool simulator for testing
+ */
+declare function createToolSimulator(config: ToolSimulatorConfig): {
+    execute: (toolName: string, input: any) => Promise<any>;
+    getInvocations: (toolName: string) => ToolInvocation[];
+    getAllInvocations: () => Record<string, ToolInvocation[]>;
+    clearInvocations: (toolName?: string) => void;
+};
+
+/**
+ * LangChain Integration - Tool Converter
+ *
+ * Converts AgentForge tools to LangChain StructuredTool format.
+ *
+ * @example
+ * ```ts
+ * import { toLangChainTool } from '@agentforge/core';
+ *
+ * const langchainTool = toLangChainTool(agentforgeTool);
+ * ```
+ */
+
+/**
+ * Convert an AgentForge tool to a LangChain DynamicStructuredTool
+ *
+ * This allows AgentForge tools to be used with LangChain agents and chains.
+ *
+ * @param tool - The AgentForge tool to convert
+ * @returns A LangChain DynamicStructuredTool
+ *
+ * @example
+ * ```ts
+ * const readFileTool = toolBuilder()
+ *   .name('read-file')
+ *   .description('Read a file from the file system')
+ *   .category(ToolCategory.FILE_SYSTEM)
+ *   .schema(z.object({
+ *     path: z.string().describe('Path to the file'),
+ *   }))
+ *   .implement(async ({ path }) => {
+ *     return fs.readFileSync(path, 'utf-8');
+ *   })
+ *   .build();
+ *
+ * // Convert to LangChain tool
+ * const langchainTool = toLangChainTool(readFileTool);
+ *
+ * // Use with LangChain agent
+ * const agent = createAgent({
+ *   model: new ChatOpenAI(),
+ *   tools: [langchainTool],
+ * });
+ * ```
+ */
+declare function toLangChainTool(tool: Tool<any, any>): DynamicStructuredTool<any>;
+/**
+ * Convert multiple AgentForge tools to LangChain tools
+ *
+ * @param tools - Array of AgentForge tools
+ * @returns Array of LangChain DynamicStructuredTools
+ *
+ * @example
+ * ```ts
+ * const tools = [readFileTool, writeFileTool, searchTool];
+ * const langchainTools = toLangChainTools(tools);
+ *
+ * const agent = createAgent({
+ *   model: new ChatOpenAI(),
+ *   tools: langchainTools,
+ * });
+ * ```
+ */
+declare function toLangChainTools(tools: Tool<any, any>[]): DynamicStructuredTool<any>[];
+/**
+ * Get the JSON Schema representation of a tool's input schema
+ *
+ * This is useful for debugging or for integrations that need the raw JSON Schema.
+ *
+ * @param tool - The AgentForge tool
+ * @returns JSON Schema object
+ *
+ * @example
+ * ```ts
+ * const schema = getToolJsonSchema(readFileTool);
+ * console.log(JSON.stringify(schema, null, 2));
+ * ```
+ */
+declare function getToolJsonSchema(tool: Tool<any, any>): Record<string, any>;
+/**
+ * Get tool metadata in a format suitable for LLM prompts
+ *
+ * This creates a human-readable description of the tool including
+ * its metadata, usage notes, limitations, and examples.
+ *
+ * @param tool - The AgentForge tool
+ * @returns Formatted tool description
+ *
+ * @example
+ * ```ts
+ * const description = getToolDescription(readFileTool);
+ * console.log(description);
+ * // Output:
+ * // read-file: Read a file from the file system
+ * // Category: file-system
+ * // Tags: file, read, io
+ * // ...
+ * ```
+ */
+declare function getToolDescription(tool: Tool<any, any>): 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
+ */
+interface StateChannelConfig<T = any, U = T> {
+    /**
+     * Optional Zod schema for runtime validation
+     */
+    schema?: ZodType<T, ZodTypeDef, any>;
+    /**
+     * Optional reducer function for aggregating updates
+     */
+    reducer?: (left: T, right: U) => T;
+    /**
+     * Optional default value factory
+     */
+    default?: () => T;
+    /**
+     * Description of this state channel (for documentation)
+     */
+    description?: string;
+}
+/**
+ * Create a type-safe state annotation with optional Zod validation
+ *
+ * This is a thin wrapper around LangGraph's Annotation.Root that adds:
+ * - 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<T extends Record<string, StateChannelConfig>>(config: T): AnnotationRoot<StateDefinition>;
+/**
+ * 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<T extends Record<string, StateChannelConfig>>(state: Record<string, any>, config: T): Record<string, any>;
+/**
+ * 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<T extends Record<string, StateChannelConfig>>(currentState: Record<string, any>, update: Record<string, any>, config: T): Record<string, any>;
+
+/**
+ * Sequential Workflow Builder
+ *
+ * Provides utilities for building linear workflows where nodes execute in sequence.
+ * This is a thin wrapper around LangGraph's StateGraph that simplifies the common
+ * pattern of chaining nodes together.
+ *
+ * @module langgraph/builders/sequential
+ */
+
+/**
+ * Configuration for a node in a sequential workflow
+ */
+interface SequentialNode<State> {
+    /**
+     * Unique name for the node
+     */
+    name: string;
+    /**
+     * The node function that processes the state
+     */
+    node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>;
+    /**
+     * Optional description of what this node does
+     */
+    description?: string;
+}
+/**
+ * Options for creating a sequential workflow
+ */
+interface SequentialWorkflowOptions {
+    /**
+     * Whether to automatically add START and END nodes
+     * @default true
+     */
+    autoStartEnd?: boolean;
+    /**
+     * Custom name for the workflow (for debugging)
+     */
+    name?: string;
+}
+/**
+ * Creates a sequential workflow where nodes execute in order.
+ *
+ * This is a convenience function that creates a StateGraph and chains
+ * the provided nodes together with edges.
+ *
+ * @example
+ * ```typescript
+ * const workflow = createSequentialWorkflow(AgentState, [
+ *   { name: 'fetch', node: fetchNode },
+ *   { name: 'process', node: processNode },
+ *   { name: 'save', node: saveNode },
+ * ]);
+ *
+ * const app = workflow.compile();
+ * const result = await app.invoke({ input: 'data' });
+ * ```
+ *
+ * @param stateSchema - The state annotation for the graph
+ * @param nodes - Array of nodes to execute in sequence
+ * @param options - Optional configuration
+ * @returns A configured StateGraph ready to compile
+ */
+declare function createSequentialWorkflow<State>(stateSchema: any, nodes: SequentialNode<State>[], options?: SequentialWorkflowOptions): StateGraph<State>;
+/**
+ * Creates a sequential workflow builder with a fluent API.
+ *
+ * This provides a more flexible way to build sequential workflows
+ * by allowing you to add nodes one at a time.
+ *
+ * @example
+ * ```typescript
+ * const workflow = sequentialBuilder(AgentState)
+ *   .addNode('fetch', fetchNode)
+ *   .addNode('process', processNode)
+ *   .addNode('save', saveNode)
+ *   .build();
+ *
+ * const app = workflow.compile();
+ * ```
+ *
+ * @param stateSchema - The state annotation for the graph
+ * @returns A fluent builder for sequential workflows
+ */
+declare function sequentialBuilder<State>(stateSchema: any): {
+    /**
+     * Add a node to the sequential workflow
+     */
+    addNode(name: string, node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>, description?: string): /*elided*/ any;
+    /**
+     * Set options for the workflow
+     */
+    options(opts: SequentialWorkflowOptions): /*elided*/ any;
+    /**
+     * Build the StateGraph
+     */
+    build(): StateGraph<State>;
+};
+
+/**
+ * Parallel Execution Builder
+ *
+ * Provides utilities for building workflows where multiple nodes execute in parallel.
+ * This implements the fan-out/fan-in pattern using LangGraph's native parallel execution.
+ *
+ * @module langgraph/builders/parallel
+ */
+
+/**
+ * Configuration for a parallel node
+ */
+interface ParallelNode<State> {
+    /**
+     * Unique name for the node
+     */
+    name: string;
+    /**
+     * The node function that processes the state
+     */
+    node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>;
+    /**
+     * Optional description of what this node does
+     */
+    description?: string;
+}
+/**
+ * Configuration for an aggregation node that combines parallel results
+ */
+interface AggregateNode<State> {
+    /**
+     * Name for the aggregation node
+     */
+    name: string;
+    /**
+     * The aggregation function that combines results from parallel nodes
+     */
+    node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>;
+    /**
+     * Optional description
+     */
+    description?: string;
+}
+/**
+ * Options for creating a parallel workflow
+ */
+interface ParallelWorkflowOptions {
+    /**
+     * Whether to automatically add START and END nodes
+     * @default true
+     */
+    autoStartEnd?: boolean;
+    /**
+     * Custom name for the workflow (for debugging)
+     */
+    name?: string;
+}
+/**
+ * Configuration for a parallel workflow
+ */
+interface ParallelWorkflowConfig<State> {
+    /**
+     * Nodes that execute in parallel
+     */
+    parallel: ParallelNode<State>[];
+    /**
+     * Optional aggregation node that runs after all parallel nodes complete
+     */
+    aggregate?: AggregateNode<State>;
+}
+/**
+ * Creates a parallel workflow where multiple nodes execute concurrently.
+ *
+ * This implements the fan-out/fan-in pattern:
+ * - Fan-out: Multiple nodes execute in parallel
+ * - Fan-in: Optional aggregation node combines results
+ *
+ * @example
+ * ```typescript
+ * const workflow = createParallelWorkflow(AgentState, {
+ *   parallel: [
+ *     { name: 'fetch_news', node: fetchNewsNode },
+ *     { name: 'fetch_weather', node: fetchWeatherNode },
+ *     { name: 'fetch_stocks', node: fetchStocksNode },
+ *   ],
+ *   aggregate: { name: 'combine', node: combineNode },
+ * });
+ *
+ * const app = workflow.compile();
+ * const result = await app.invoke({ input: 'data' });
+ * ```
+ *
+ * @param stateSchema - The state annotation for the graph
+ * @param config - Configuration for parallel nodes and optional aggregation
+ * @param options - Optional configuration
+ * @returns A configured StateGraph ready to compile
+ */
+declare function createParallelWorkflow<State>(stateSchema: any, config: ParallelWorkflowConfig<State>, options?: ParallelWorkflowOptions): StateGraph<State>;
+
+/**
+ * Conditional Routing Utilities
+ *
+ * Provides type-safe utilities for adding conditional edges to LangGraph workflows.
+ * This simplifies the common pattern of routing based on state conditions.
+ *
+ * @module langgraph/builders/conditional
+ */
+
+/**
+ * A route name that can be either a node name or END
+ */
+type RouteName = string | typeof END;
+/**
+ * A mapping of route keys to node names
+ */
+type RouteMap = Record<string, RouteName>;
+/**
+ * A condition function that determines which route to take
+ */
+type RouteCondition<State> = (state: State) => string;
+/**
+ * Configuration for a conditional router
+ */
+interface ConditionalRouterConfig<State, Routes extends RouteMap> {
+    /**
+     * Map of route keys to node names
+     */
+    routes: Routes;
+    /**
+     * Condition function that returns a route key
+     */
+    condition: RouteCondition<State>;
+    /**
+     * Optional description of the routing logic
+     */
+    description?: string;
+}
+/**
+ * A conditional router that can be used with StateGraph.addConditionalEdges
+ */
+interface ConditionalRouter<State, Routes extends RouteMap> {
+    /**
+     * The route map
+     */
+    routes: Routes;
+    /**
+     * The condition function
+     */
+    condition: RouteCondition<State>;
+    /**
+     * Optional description
+     */
+    description?: string;
+}
+/**
+ * Creates a type-safe conditional router for LangGraph workflows.
+ *
+ * This provides a cleaner API for conditional routing with better type safety
+ * and validation.
+ *
+ * @example
+ * ```typescript
+ * const router = createConditionalRouter<AgentState>({
+ *   routes: {
+ *     'continue': 'agent',
+ *     'end': END,
+ *     'tools': 'tools',
+ *   },
+ *   condition: (state) => {
+ *     if (state.shouldEnd) return 'end';
+ *     if (state.needsTools) return 'tools';
+ *     return 'continue';
+ *   },
+ * });
+ *
+ * // Use with StateGraph
+ * graph.addConditionalEdges('agent', router.condition, router.routes);
+ * ```
+ *
+ * @param config - Configuration for the conditional router
+ * @returns A conditional router object
+ */
+declare function createConditionalRouter<State, Routes extends RouteMap = RouteMap>(config: ConditionalRouterConfig<State, Routes>): ConditionalRouter<State, Routes>;
+/**
+ * Creates a simple binary router (true/false condition).
+ *
+ * This is a convenience function for the common case of routing based on
+ * a boolean condition.
+ *
+ * @example
+ * ```typescript
+ * const router = createBinaryRouter<AgentState>({
+ *   condition: (state) => state.isComplete,
+ *   ifTrue: END,
+ *   ifFalse: 'continue',
+ * });
+ *
+ * graph.addConditionalEdges('check', router.condition, router.routes);
+ * ```
+ *
+ * @param config - Configuration for the binary router
+ * @returns A conditional router object
+ */
+declare function createBinaryRouter<State>(config: {
+    condition: (state: State) => boolean;
+    ifTrue: RouteName;
+    ifFalse: RouteName;
+    description?: string;
+}): ConditionalRouter<State, {
+    true: RouteName;
+    false: RouteName;
+}>;
+/**
+ * Creates a multi-way router based on a discriminator function.
+ *
+ * This is useful when you have multiple possible routes based on a
+ * state property or computed value.
+ *
+ * @example
+ * ```typescript
+ * const router = createMultiRouter<AgentState>({
+ *   discriminator: (state) => state.status,
+ *   routes: {
+ *     'pending': 'process',
+ *     'complete': END,
+ *     'error': 'error_handler',
+ *   },
+ *   default: 'unknown',
+ * });
+ *
+ * graph.addConditionalEdges('check', router.condition, router.routes);
+ * ```
+ *
+ * @param config - Configuration for the multi-way router
+ * @returns A conditional router object
+ */
+declare function createMultiRouter<State, Routes extends RouteMap = RouteMap>(config: {
+    discriminator: (state: State) => string;
+    routes: Routes;
+    default?: keyof Routes;
+    description?: string;
+}): ConditionalRouter<State, Routes>;
+
+/**
+ * Subgraph composition utilities for LangGraph
+ *
+ * Helpers for creating and composing subgraphs.
+ */
+
+/**
+ * Configuration function for building a subgraph
+ */
+type SubgraphBuilder<State> = (graph: StateGraph<State>) => StateGraph<State>;
+/**
+ * Creates a reusable subgraph that can be added as a node to other graphs.
+ *
+ * This is a helper function that creates a StateGraph, applies the builder function,
+ * and returns the compiled graph which can be added as a node to another graph.
+ *
+ * @example
+ * ```typescript
+ * // Create a reusable research subgraph
+ * const researchSubgraph = createSubgraph(ResearchState, (graph) => {
+ *   graph.addNode('search', searchNode);
+ *   graph.addNode('analyze', analyzeNode);
+ *   graph.addEdge('__start__', 'search');
+ *   graph.addEdge('search', 'analyze');
+ *   graph.addEdge('analyze', '__end__');
+ *   return graph;
+ * });
+ *
+ * // Use in main graph
+ * const mainGraph = new StateGraph(MainState);
+ * mainGraph.addNode('research', researchSubgraph);
+ * ```
+ *
+ * @param stateSchema - The state annotation for the subgraph
+ * @param builder - Function that configures the subgraph
+ * @returns A compiled graph that can be used as a node
+ */
+declare function createSubgraph<State>(stateSchema: any, builder: SubgraphBuilder<State>): ReturnType<StateGraph<State>['compile']>;
+/**
+ * Options for composing graphs
+ */
+interface ComposeGraphsOptions {
+    /**
+     * Name for the subgraph node
+     */
+    name: string;
+    /**
+     * Optional description for documentation
+     */
+    description?: string;
+}
+/**
+ * Adds a compiled subgraph as a node to a parent graph.
+ *
+ * This is a convenience function that wraps the common pattern of
+ * adding a compiled graph as a node.
+ *
+ * @example
+ * ```typescript
+ * const subgraph = createSubgraph(SubState, (graph) => {
+ *   // Configure subgraph
+ *   return graph;
+ * });
+ *
+ * const mainGraph = new StateGraph(MainState);
+ * composeGraphs(mainGraph, subgraph, { name: 'sub_workflow' });
+ * ```
+ *
+ * @param parentGraph - The parent graph to add the subgraph to
+ * @param subgraph - The compiled subgraph to add as a node
+ * @param options - Configuration options
+ * @returns The parent graph for chaining
+ */
+declare function composeGraphs<ParentState, SubState>(parentGraph: StateGraph<ParentState>, subgraph: ReturnType<StateGraph<SubState>['compile']>, options: ComposeGraphsOptions): StateGraph<ParentState>;
+
+/**
+ * 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>>;
+
+/**
+ * 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
+     */
+    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
+ */
+declare enum LogLevel {
+    DEBUG = "debug",
+    INFO = "info",
+    WARN = "warn",
+    ERROR = "error"
+}
+/**
+ * Logger configuration options
+ */
+interface LoggerOptions {
+    /**
+     * Minimum log level to output
+     * @default LogLevel.INFO
+     */
+    level?: LogLevel;
+    /**
+     * Output format
+     * @default 'pretty'
+     */
+    format?: 'json' | 'pretty';
+    /**
+     * Output destination
+     * @default process.stdout
+     */
+    destination?: NodeJS.WritableStream;
+    /**
+     * Whether to include timestamps
+     * @default true
+     */
+    includeTimestamp?: boolean;
+    /**
+     * Whether to include context in logs
+     * @default true
+     */
+    includeContext?: boolean;
+}
+/**
+ * Log entry structure
+ */
+interface LogEntry {
+    level: LogLevel;
+    name: string;
+    message: string;
+    timestamp?: string;
+    context?: Record<string, any>;
+    data?: Record<string, any>;
+}
+/**
+ * Logger interface
+ */
+interface Logger {
+    /**
+     * Log a debug message
+     */
+    debug(message: string, data?: Record<string, any>): void;
+    /**
+     * Log an info message
+     */
+    info(message: string, data?: Record<string, any>): void;
+    /**
+     * Log a warning message
+     */
+    warn(message: string, data?: Record<string, any>): void;
+    /**
+     * Log an error message
+     */
+    error(message: string, data?: Record<string, any>): void;
+    /**
+     * Create a child logger with additional context
+     */
+    withContext(context: Record<string, any>): Logger;
+}
+/**
+ * Create a structured logger.
+ *
+ * @example
+ * ```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 });
+ * ```
+ *
+ * @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;
+
+/**
+ * Metrics Collection Utilities
+ *
+ * Provides utilities for collecting performance and usage metrics.
+ */
+/**
+ * Metric types
+ */
+declare enum MetricType {
+    COUNTER = "counter",
+    GAUGE = "gauge",
+    HISTOGRAM = "histogram"
+}
+/**
+ * Metric entry
+ */
+interface MetricEntry {
+    type: MetricType;
+    name: string;
+    value: number;
+    timestamp: number;
+    labels?: Record<string, string>;
+}
+/**
+ * Timer interface for measuring durations
+ */
+interface Timer {
+    /**
+     * End the timer and record the duration
+     */
+    end(): number;
+}
+/**
+ * Metrics collector interface
+ */
+interface Metrics {
+    /**
+     * Increment a counter metric
+     */
+    increment(name: string, value?: number, labels?: Record<string, string>): void;
+    /**
+     * Decrement a counter metric
+     */
+    decrement(name: string, value?: number, labels?: Record<string, string>): void;
+    /**
+     * Set a gauge metric
+     */
+    gauge(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Record a histogram value
+     */
+    histogram(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Start a timer for measuring duration
+     */
+    startTimer(name: string, labels?: Record<string, string>): Timer;
+    /**
+     * Get all recorded metrics
+     */
+    getMetrics(): MetricEntry[];
+    /**
+     * Clear all metrics
+     */
+    clear(): void;
+}
+/**
+ * Create a metrics collector.
+ *
+ * @example
+ * ```typescript
+ * import { createMetrics } from '@agentforge/core';
+ *
+ * const metrics = createMetrics('my-agent');
+ *
+ * // Track counters
+ * metrics.increment('requests.total');
+ * metrics.increment('requests.success');
+ *
+ * // Track gauges
+ * metrics.gauge('active.connections', 5);
+ *
+ * // Track histograms
+ * metrics.histogram('request.duration', 150);
+ *
+ * // Track timers
+ * const timer = metrics.startTimer('operation.duration');
+ * // ... do work ...
+ * timer.end();
+ * ```
+ *
+ * @param name - Metrics namespace (typically the agent or component name)
+ * @returns A metrics collector instance
+ */
+declare function createMetrics(name: string): Metrics;
+/**
+ * Options for metrics tracking on nodes
+ */
+interface MetricsNodeOptions {
+    /**
+     * Name for the metrics
+     */
+    name: string;
+    /**
+     * Whether to track execution duration
+     * @default true
+     */
+    trackDuration?: boolean;
+    /**
+     * Whether to track errors
+     * @default true
+     */
+    trackErrors?: boolean;
+    /**
+     * Whether to track invocation count
+     * @default true
+     */
+    trackInvocations?: boolean;
+    /**
+     * Metrics collector to use
+     * If not provided, a new one will be created
+     */
+    metrics?: Metrics;
+}
+/**
+ * Wrap a node function with automatic metrics tracking.
+ *
+ * @example
+ * ```typescript
+ * import { withMetrics, createMetrics } from '@agentforge/core';
+ *
+ * const metrics = createMetrics('my-agent');
+ *
+ * const metricNode = withMetrics(myNode, {
+ *   name: 'research-node',
+ *   metrics,
+ * });
+ * ```
+ *
+ * @param node - The node function to wrap
+ * @param options - Metrics tracking options
+ * @returns A wrapped node function with metrics tracking
+ */
+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
+ *
+ * Provides enhanced error classes and error reporting for better debugging.
+ */
+/**
+ * Error context information
+ */
+interface ErrorContext {
+    /**
+     * Error code for categorization
+     */
+    code?: string;
+    /**
+     * Node name where the error occurred
+     */
+    node?: string;
+    /**
+     * Current state when the error occurred
+     */
+    state?: any;
+    /**
+     * Additional metadata
+     */
+    metadata?: Record<string, any>;
+    /**
+     * Original error that caused this error
+     */
+    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);
+    /**
+     * Convert error to JSON for logging/reporting
+     */
+    toJSON(): Record<string, any>;
+    /**
+     * Get a human-readable string representation
+     */
+    toString(): string;
+}
+/**
+ * Error reporter configuration
+ */
+interface ErrorReporterOptions {
+    /**
+     * Callback function to handle errors
+     */
+    onError: (error: AgentError) => void | Promise<void>;
+    /**
+     * Whether to include stack traces
+     * @default true
+     */
+    includeStackTrace?: boolean;
+    /**
+     * Whether to include state in error context
+     * @default false (for security/privacy)
+     */
+    includeState?: boolean;
+    /**
+     * Whether to rethrow errors after reporting
+     * @default true
+     */
+    rethrow?: boolean;
+}
+/**
+ * Error reporter for tracking and reporting errors
+ */
+interface ErrorReporter {
+    /**
+     * Wrap a node function with error reporting
+     */
+    wrap<State>(node: (state: State) => State | Promise<State> | Partial<State> | Promise<Partial<State>>, nodeName?: string): (state: State) => Promise<State | Partial<State>>;
+    /**
+     * Report an error manually
+     */
+    report(error: Error, context?: ErrorContext): Promise<void>;
+}
+/**
+ * Create an error reporter.
+ *
+ * @example
+ * ```typescript
+ * 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 createErrorReporter(options: ErrorReporterOptions): ErrorReporter;
+
+/**
+ * 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;
+
+/**
+ * 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;
+};
+
+/**
+ * Streaming utilities for LangGraph applications
+ * @module streaming
+ */
+/**
+ * Options for chunk transformer
+ */
+interface ChunkOptions {
+    /** Number of items per chunk */
+    size: number;
+}
+/**
+ * Options for batch transformer
+ */
+interface BatchOptions {
+    /** Maximum number of items per batch */
+    maxSize: number;
+    /** Maximum time to wait before emitting a batch (ms) */
+    maxWait: number;
+}
+/**
+ * Options for throttle transformer
+ */
+interface ThrottleOptions {
+    /** Maximum number of items to emit */
+    rate: number;
+    /** Time period for rate limit (ms) */
+    per: number;
+}
+/**
+ * Reducer function for stream aggregation
+ */
+type ReducerFunction<T, R> = (accumulator: R, current: T) => R;
+/**
+ * Progress information
+ */
+interface Progress {
+    /** Current progress value */
+    current: number;
+    /** Total expected value */
+    total: number;
+    /** Percentage complete (0-100) */
+    percentage: number;
+    /** Estimated time to completion (seconds) */
+    eta: number;
+    /** Start time */
+    startTime: number;
+    /** Elapsed time (ms) */
+    elapsed: number;
+}
+/**
+ * Progress tracker options
+ */
+interface ProgressTrackerOptions {
+    /** Total expected items/steps */
+    total: number;
+    /** Callback for progress updates */
+    onProgress?: (progress: Progress) => void;
+    /** Callback for completion */
+    onComplete?: (progress: Progress) => void;
+    /** Callback for cancellation */
+    onCancel?: () => void;
+}
+/**
+ * Progress tracker interface
+ */
+interface ProgressTracker {
+    /** Start tracking */
+    start(): void;
+    /** Update progress */
+    update(current: number): void;
+    /** Mark as complete */
+    complete(): void;
+    /** Cancel tracking */
+    cancel(): void;
+    /** Get current progress */
+    getProgress(): Progress;
+    /** Check if cancelled */
+    isCancelled(): boolean;
+}
+/**
+ * SSE event
+ */
+interface SSEEvent {
+    /** Event type */
+    event?: string;
+    /** Event data */
+    data: string;
+    /** Event ID */
+    id?: string;
+    /** Retry interval (ms) */
+    retry?: number;
+}
+/**
+ * SSE formatter options
+ */
+interface SSEFormatterOptions<T = any> {
+    /** Event type mappers */
+    eventTypes?: Record<string, (data: T) => SSEEvent>;
+    /** Heartbeat interval (ms) */
+    heartbeat?: number;
+    /** Default retry interval (ms) */
+    retry?: number;
+}
+/**
+ * SSE formatter interface
+ */
+interface SSEFormatter<T = any> {
+    /** Format stream as SSE events */
+    format(stream: AsyncIterable<T>): AsyncIterable<string>;
+}
+/**
+ * WebSocket message
+ */
+interface WebSocketMessage {
+    /** Message type */
+    type: string;
+    /** Message data */
+    data?: any;
+    /** Error information */
+    error?: string;
+}
+/**
+ * WebSocket handler options
+ */
+interface WebSocketHandlerOptions {
+    /** Connection handler */
+    onConnect?: (ws: any, req?: any) => void;
+    /** Message handler */
+    onMessage?: (ws: any, message: any) => Promise<void>;
+    /** Error handler */
+    onError?: (ws: any, error: Error) => void;
+    /** Close handler */
+    onClose?: (ws: any, code?: number, reason?: string) => void;
+    /** Heartbeat interval (ms) */
+    heartbeat?: number;
+}
+
+/**
+ * Stream transformers for LangGraph applications
+ * @module streaming/transformers
+ */
+
+/**
+ * Transform a stream into chunks of a specified size
+ *
+ * @example
+ * ```typescript
+ * const chunked = chunk(stream, { size: 10 });
+ * for await (const chunk of chunked) {
+ *   console.log(chunk); // Array of 10 items (or fewer for last chunk)
+ * }
+ * ```
+ */
+declare function chunk<T>(stream: AsyncIterable<T>, options: ChunkOptions): AsyncIterable<T[]>;
+/**
+ * Batch stream items with size and time constraints
+ *
+ * @example
+ * ```typescript
+ * const batched = batch(stream, { maxSize: 5, maxWait: 100 });
+ * for await (const batch of batched) {
+ *   console.log(batch); // Array of up to 5 items or items collected within 100ms
+ * }
+ * ```
+ */
+declare function batch<T>(stream: AsyncIterable<T>, options: BatchOptions): AsyncIterable<T[]>;
+/**
+ * Throttle stream to limit rate of items
+ *
+ * @example
+ * ```typescript
+ * const throttled = throttle(stream, { rate: 10, per: 1000 });
+ * for await (const item of throttled) {
+ *   console.log(item); // Max 10 items per second
+ * }
+ * ```
+ */
+declare function throttle<T>(stream: AsyncIterable<T>, options: ThrottleOptions): AsyncIterable<T>;
+
+/**
+ * Stream aggregators for LangGraph applications
+ * @module streaming/aggregators
+ */
+
+/**
+ * Collect all items from a stream into an array
+ *
+ * @example
+ * ```typescript
+ * const items = await collect(stream);
+ * console.log(items); // Array of all items
+ * ```
+ */
+declare function collect<T>(stream: AsyncIterable<T>): Promise<T[]>;
+/**
+ * Reduce a stream to a single value
+ *
+ * @example
+ * ```typescript
+ * const sum = await reduce(stream, (acc, val) => acc + val, 0);
+ * console.log(sum); // Sum of all values
+ * ```
+ */
+declare function reduce<T, R>(stream: AsyncIterable<T>, reducer: ReducerFunction<T, R>, initialValue: R): Promise<R>;
+/**
+ * Merge multiple streams into a single stream
+ *
+ * Items are emitted as they arrive from any stream.
+ *
+ * @example
+ * ```typescript
+ * const merged = merge([stream1, stream2, stream3]);
+ * for await (const item of merged) {
+ *   console.log(item); // Items from any stream
+ * }
+ * ```
+ */
+declare function merge<T>(streams: AsyncIterable<T>[]): AsyncIterable<T>;
+/**
+ * Filter stream items based on a predicate
+ *
+ * @example
+ * ```typescript
+ * const filtered = filter(stream, (item) => item.value > 10);
+ * for await (const item of filtered) {
+ *   console.log(item); // Only items with value > 10
+ * }
+ * ```
+ */
+declare function filter<T>(stream: AsyncIterable<T>, predicate: (item: T) => boolean | Promise<boolean>): AsyncIterable<T>;
+/**
+ * Map stream items to new values
+ *
+ * @example
+ * ```typescript
+ * const mapped = map(stream, (item) => item.value * 2);
+ * for await (const item of mapped) {
+ *   console.log(item); // Transformed items
+ * }
+ * ```
+ */
+declare function map<T, R>(stream: AsyncIterable<T>, mapper: (item: T) => R | Promise<R>): AsyncIterable<R>;
+/**
+ * Take only the first N items from a stream
+ *
+ * @example
+ * ```typescript
+ * const first10 = take(stream, 10);
+ * for await (const item of first10) {
+ *   console.log(item); // Only first 10 items
+ * }
+ * ```
+ */
+declare function take<T>(stream: AsyncIterable<T>, count: number): AsyncIterable<T>;
+
+/**
+ * Progress tracking for long-running operations
+ * @module streaming/progress
+ */
+
+/**
+ * Create a progress tracker for long-running operations
+ *
+ * @example
+ * ```typescript
+ * const tracker = createProgressTracker({
+ *   total: 100,
+ *   onProgress: (progress) => {
+ *     console.log(`${progress.percentage}% complete (ETA: ${progress.eta}s)`);
+ *   },
+ * });
+ *
+ * tracker.start();
+ * for (let i = 0; i < 100; i++) {
+ *   await processItem(i);
+ *   tracker.update(i + 1);
+ * }
+ * tracker.complete();
+ * ```
+ */
+declare function createProgressTracker(options: ProgressTrackerOptions): ProgressTracker;
+
+/**
+ * Server-Sent Events (SSE) support for streaming
+ * @module streaming/sse
+ */
+
+/**
+ * Create an SSE formatter for streaming data
+ *
+ * @example
+ * ```typescript
+ * const formatter = createSSEFormatter({
+ *   eventTypes: {
+ *     token: (data) => ({ event: 'token', data: data.content }),
+ *     error: (data) => ({ event: 'error', data: data.message }),
+ *   },
+ *   heartbeat: 30000,
+ *   retry: 3000,
+ * });
+ *
+ * // In Express/Fastify handler
+ * res.setHeader('Content-Type', 'text/event-stream');
+ * res.setHeader('Cache-Control', 'no-cache');
+ * res.setHeader('Connection', 'keep-alive');
+ *
+ * for await (const event of formatter.format(stream)) {
+ *   res.write(event);
+ * }
+ * res.end();
+ * ```
+ */
+declare function createSSEFormatter<T = any>(options?: SSEFormatterOptions<T>): SSEFormatter<T>;
+/**
+ * Create a heartbeat comment for SSE
+ */
+declare function createHeartbeat(): string;
+/**
+ * Parse SSE event from string
+ *
+ * Useful for testing or client-side parsing
+ */
+declare function parseSSEEvent(eventString: string): SSEEvent | null;
+
+/**
+ * WebSocket support for bidirectional streaming
+ * @module streaming/websocket
+ */
+
+/**
+ * Create a WebSocket handler for bidirectional streaming
+ *
+ * @example
+ * ```typescript
+ * import WebSocket from 'ws';
+ *
+ * const handler = createWebSocketHandler({
+ *   onConnect: (ws) => {
+ *     console.log('Client connected');
+ *   },
+ *   onMessage: async (ws, message) => {
+ *     const stream = await agent.stream(message);
+ *     for await (const event of stream) {
+ *       ws.send(JSON.stringify(event));
+ *     }
+ *   },
+ *   onError: (ws, error) => {
+ *     ws.send(JSON.stringify({ type: 'error', error: error.message }));
+ *   },
+ *   heartbeat: 30000,
+ * });
+ *
+ * wss.on('connection', handler);
+ * ```
+ */
+declare function createWebSocketHandler(options: WebSocketHandlerOptions): (ws: any, req?: any) => void;
+/**
+ * Send a message through WebSocket
+ *
+ * Automatically serializes objects to JSON
+ */
+declare function sendMessage(ws: any, message: WebSocketMessage): void;
+/**
+ * Broadcast a message to multiple WebSocket clients
+ */
+declare function broadcast(clients: Set<any>, message: WebSocketMessage): void;
+/**
+ * Create a WebSocket message
+ */
+declare function createMessage(type: string, data?: any, error?: string): WebSocketMessage;
+
+/**
+ * Connection pooling for database and HTTP clients
+ */
+interface PoolConfig {
+    min?: number;
+    max?: number;
+    acquireTimeout?: number;
+    idleTimeout?: number;
+    evictionInterval?: number;
+}
+interface HealthCheckConfig {
+    enabled?: boolean;
+    interval?: number;
+    timeout?: number;
+    retries?: number;
+}
+interface ConnectionPoolOptions<T> {
+    factory: () => Promise<T>;
+    destroyer?: (connection: T) => Promise<void>;
+    validator?: (connection: T) => Promise<boolean>;
+    pool?: PoolConfig;
+    healthCheck?: HealthCheckConfig;
+    onAcquire?: (connection: T) => void;
+    onRelease?: (connection: T) => void;
+    onDestroy?: (connection: T) => void;
+    onHealthCheckFail?: (error: Error) => void;
+}
+interface PoolStats {
+    size: number;
+    available: number;
+    pending: number;
+    acquired: number;
+    created: number;
+    destroyed: number;
+    healthChecksPassed: number;
+    healthChecksFailed: number;
+}
+declare class ConnectionPool<T> {
+    private options;
+    private connections;
+    private pending;
+    private stats;
+    private evictionTimer?;
+    private healthCheckTimer?;
+    private draining;
+    constructor(options: ConnectionPoolOptions<T>);
+    private initialize;
+    private createConnection;
+    private destroyConnection;
+    acquire(): Promise<T>;
+    release(connection: T): Promise<void>;
+    private evictIdleConnections;
+    private performHealthChecks;
+    drain(): Promise<void>;
+    clear(): Promise<void>;
+    getStats(): PoolStats;
+}
+declare function createConnectionPool<T>(options: ConnectionPoolOptions<T>): ConnectionPool<T>;
+
+interface DatabaseConfig {
+    host: string;
+    port?: number;
+    database: string;
+    user: string;
+    password: string;
+    ssl?: boolean;
+    connectionTimeout?: number;
+}
+interface DatabaseConnection {
+    query<T = any>(sql: string, params?: any[]): Promise<T>;
+    execute(sql: string, params?: any[]): Promise<void>;
+    close(): Promise<void>;
+}
+interface DatabasePoolOptions {
+    config: DatabaseConfig;
+    pool?: PoolConfig;
+    healthCheck?: HealthCheckConfig & {
+        query?: string;
+    };
+    onConnect?: (connection: DatabaseConnection) => void;
+    onDisconnect?: (connection: DatabaseConnection) => void;
+}
+declare class DatabasePool {
+    private options;
+    private pool;
+    constructor(options: DatabasePoolOptions);
+    acquire(): Promise<DatabaseConnection>;
+    release(connection: DatabaseConnection): Promise<void>;
+    query<T = any>(sql: string, params?: any[]): Promise<T>;
+    execute(sql: string, params?: any[]): Promise<void>;
+    drain(): Promise<void>;
+    clear(): Promise<void>;
+    getStats(): PoolStats;
+}
+declare function createDatabasePool(options: DatabasePoolOptions): DatabasePool;
+
+interface HttpConfig {
+    baseURL: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+    maxRedirects?: number;
+    validateStatus?: (status: number) => boolean;
+}
+interface HttpPoolConfig extends PoolConfig {
+    maxSockets?: number;
+    keepAlive?: boolean;
+    keepAliveMsecs?: number;
+}
+interface HttpClient {
+    get<T = any>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>;
+    post<T = any>(url: string, data?: any, config?: RequestConfig): Promise<HttpResponse<T>>;
+    put<T = any>(url: string, data?: any, config?: RequestConfig): Promise<HttpResponse<T>>;
+    delete<T = any>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>;
+    request<T = any>(config: RequestConfig): Promise<HttpResponse<T>>;
+    close(): Promise<void>;
+}
+interface RequestConfig {
+    url?: string;
+    method?: string;
+    headers?: Record<string, string>;
+    params?: Record<string, any>;
+    data?: any;
+    timeout?: number;
+}
+interface HttpResponse<T = any> {
+    data: T;
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+}
+interface HttpPoolOptions {
+    config: HttpConfig;
+    pool?: HttpPoolConfig;
+    healthCheck?: HealthCheckConfig & {
+        endpoint?: string;
+        method?: string;
+    };
+    onConnect?: (client: HttpClient) => void;
+    onDisconnect?: (client: HttpClient) => void;
+}
+declare class HttpPool {
+    private options;
+    private pool;
+    constructor(options: HttpPoolOptions);
+    acquire(): Promise<HttpClient>;
+    release(client: HttpClient): Promise<void>;
+    request<T = any>(config: RequestConfig): Promise<HttpResponse<T>>;
+    drain(): Promise<void>;
+    clear(): Promise<void>;
+    getStats(): PoolStats;
+}
+declare function createHttpPool(options: HttpPoolOptions): HttpPool;
+
+/**
+ * Memory management and tracking
+ */
+interface MemoryStats {
+    used: number;
+    total: number;
+    percentage: number;
+    heapUsed: number;
+    heapTotal: number;
+    external: number;
+    arrayBuffers: number;
+}
+interface MemoryManagerOptions {
+    maxMemory?: number;
+    checkInterval?: number;
+    thresholdPercentage?: number;
+    onThreshold?: (stats: MemoryStats) => void;
+    onLimit?: (stats: MemoryStats) => Promise<void>;
+    onLeak?: (stats: MemoryStats) => void;
+    leakDetection?: {
+        enabled?: boolean;
+        sampleInterval?: number;
+        growthThreshold?: number;
+    };
+}
+type CleanupHandler = () => Promise<void>;
+declare class MemoryManager {
+    private options;
+    private cleanupHandlers;
+    private checkTimer?;
+    private leakDetectionTimer?;
+    private previousMemory?;
+    private running;
+    constructor(options: MemoryManagerOptions);
+    start(): void;
+    stop(): void;
+    registerCleanup(name: string, handler: CleanupHandler): void;
+    unregisterCleanup(name: string): void;
+    cleanup(name?: string): Promise<void>;
+    getStats(): MemoryStats;
+    forceGC(): void;
+    private checkMemory;
+    private detectLeaks;
+}
+declare function createMemoryManager(options: MemoryManagerOptions): MemoryManager;
+
+/**
+ * Batch processing for efficient request handling
+ */
+interface BatchProcessorOptions<TInput, TOutput> {
+    maxBatchSize: number;
+    maxWaitTime: number;
+    processor: (batch: TInput[]) => Promise<TOutput[]>;
+    onBatchStart?: (batch: TInput[]) => void;
+    onBatchComplete?: (batch: TInput[], results: TOutput[]) => void;
+    onBatchError?: (batch: TInput[], error: Error) => void;
+    onItemError?: (item: TInput, error: Error) => TOutput | undefined;
+}
+interface BatchStats {
+    totalBatches: number;
+    totalItems: number;
+    averageBatchSize: number;
+    averageWaitTime: number;
+    successfulBatches: number;
+    failedBatches: number;
+}
+declare class BatchProcessor<TInput, TOutput> {
+    private options;
+    private pending;
+    private timer?;
+    private processing;
+    private stats;
+    constructor(options: BatchProcessorOptions<TInput, TOutput>);
+    add(input: TInput): Promise<TOutput>;
+    flush(): Promise<void>;
+    private processBatch;
+    getStats(): BatchStats;
+    getPendingCount(): number;
+}
+declare function createBatchProcessor<TInput, TOutput>(options: BatchProcessorOptions<TInput, TOutput>): BatchProcessor<TInput, TOutput>;
+
+/**
+ * Circuit breaker pattern for fault tolerance
+ */
+type CircuitState = 'closed' | 'open' | 'half-open';
+interface CircuitBreakerOptions {
+    failureThreshold: number;
+    resetTimeout: number;
+    monitoringPeriod?: number;
+    halfOpenRequests?: number;
+    onStateChange?: (state: CircuitState, previousState: CircuitState) => void;
+    onFailure?: (error: Error) => void;
+    onSuccess?: () => void;
+    shouldTrip?: (error: Error) => boolean;
+}
+interface CircuitBreakerStats {
+    state: CircuitState;
+    failures: number;
+    successes: number;
+    totalCalls: number;
+    failureRate: number;
+    lastFailureTime?: number;
+    lastSuccessTime?: number;
+    stateChanges: number;
+}
+declare class CircuitBreaker {
+    private options;
+    private state;
+    private failures;
+    private successes;
+    private totalCalls;
+    private stateChanges;
+    private lastFailureTime?;
+    private lastSuccessTime?;
+    private resetTimer?;
+    private callHistory;
+    private halfOpenAttempts;
+    constructor(options: CircuitBreakerOptions);
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    wrap<TArgs extends any[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>): (...args: TArgs) => Promise<TReturn>;
+    private onSuccess;
+    private onFailure;
+    private recordCall;
+    private getRecentFailures;
+    private scheduleReset;
+    private transitionTo;
+    getState(): CircuitState;
+    getStats(): CircuitBreakerStats;
+    reset(): void;
+}
+declare function createCircuitBreaker(options: CircuitBreakerOptions): CircuitBreaker;
+
+export { AgentError, type AggregateNode, type BackoffStrategy, type BatchOptions, BatchProcessor, type BatchProcessorOptions, type BatchStats, 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 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 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 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 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 ToolSimulatorConfig, type TracingOptions, type WebSocketHandlerOptions, type WebSocketMessage, batch, broadcast, cache, chain, chunk, clearThread, collect, compose, composeGraphs, composeTool, composeWithOptions, conditional, configureLangSmith, createBatchProcessor, createBinaryRouter, createCircuitBreaker, createConditionalRouter, createConnectionPool, createConversationConfig, createDatabasePool, createErrorReporter, createHeartbeat, createHttpPool, createLogger, createManagedTool, createMemoryCheckpointer, createMemoryManager, createMessage, createMetrics, createMiddlewareContext, createMockTool, createMultiRouter, createParallelWorkflow, createProgressTracker, createSSEFormatter, createSequentialWorkflow, createSqliteCheckpointer, createStateAnnotation, createSubgraph, createThreadConfig, createTool, createToolExecutor, createToolSimulator, createToolUnsafe, createWebSocketHandler, development, filter, generateThreadId, getCheckpointHistory, getLangSmithConfig, getLatestCheckpoint, getMissingDescriptions, getToolDescription, getToolJsonSchema, 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 };