@wundr.io/langgraph-orchestrator 1.0.3

package/dist/types.d.ts

@@ -0,0 +1,762 @@
+/**
+ * Type definitions for LangGraph-style workflow orchestration
+ * @module @wundr.io/langgraph-orchestrator
+ */
+import { z } from 'zod';
+/**
+ * Generic agent state that can be extended for specific workflows
+ */
+export interface AgentState {
+    /** Unique identifier for this state instance */
+    readonly id: string;
+    /** Current messages in the conversation/workflow */
+    readonly messages: Message[];
+    /** Arbitrary key-value data store */
+    readonly data: Record<string, unknown>;
+    /** Current step in the workflow */
+    readonly currentStep: string;
+    /** Previous steps for backtracking */
+    readonly history: StateHistoryEntry[];
+    /** Error information if workflow failed */
+    readonly error?: WorkflowError;
+    /** Timestamp of state creation */
+    readonly createdAt: Date;
+    /** Timestamp of last state update */
+    readonly updatedAt: Date;
+    /** Metadata for tracking and debugging */
+    readonly metadata: StateMetadata;
+}
+/**
+ * Message in the agent conversation
+ */
+export interface Message {
+    /** Unique message identifier */
+    readonly id: string;
+    /** Role of the message sender */
+    readonly role: MessageRole;
+    /** Content of the message */
+    readonly content: string;
+    /** Tool calls if any */
+    readonly toolCalls?: ToolCall[];
+    /** Tool response if this is a tool result */
+    readonly toolResult?: ToolResult;
+    /** Timestamp of message creation */
+    readonly timestamp: Date;
+    /** Additional message metadata */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Role of a message sender
+ */
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+/**
+ * Tool call request from LLM
+ */
+export interface ToolCall {
+    /** Unique identifier for this tool call */
+    readonly id: string;
+    /** Name of the tool to call */
+    readonly name: string;
+    /** Arguments to pass to the tool */
+    readonly arguments: Record<string, unknown>;
+}
+/**
+ * Result from a tool execution
+ */
+export interface ToolResult {
+    /** ID of the tool call this is responding to */
+    readonly toolCallId: string;
+    /** Result content */
+    readonly content: string;
+    /** Whether the tool execution was successful */
+    readonly success: boolean;
+    /** Error message if failed */
+    readonly error?: string;
+}
+/**
+ * Entry in state history for time-travel debugging
+ */
+export interface StateHistoryEntry {
+    /** Step name that produced this state */
+    readonly step: string;
+    /** Timestamp when this state was created */
+    readonly timestamp: Date;
+    /** Snapshot of the state at this point */
+    readonly snapshot: Partial<AgentState>;
+    /** Changes made in this step */
+    readonly changes: StateChange[];
+}
+/**
+ * Individual state change record
+ */
+export interface StateChange {
+    /** Path to the changed property */
+    readonly path: string;
+    /** Previous value */
+    readonly previousValue: unknown;
+    /** New value */
+    readonly newValue: unknown;
+}
+/**
+ * Error information for failed workflows
+ */
+export interface WorkflowError {
+    /** Error code */
+    readonly code: string;
+    /** Human-readable error message */
+    readonly message: string;
+    /** Stack trace if available */
+    readonly stack?: string;
+    /** Node where error occurred */
+    readonly node?: string;
+    /** Whether the error is recoverable */
+    readonly recoverable: boolean;
+    /** Suggested recovery actions */
+    readonly recoveryHints?: string[];
+}
+/**
+ * Metadata for state tracking
+ */
+export interface StateMetadata {
+    /** Session ID for cross-session tracking */
+    readonly sessionId: string;
+    /** User ID if applicable */
+    readonly userId?: string;
+    /** Workflow execution ID */
+    readonly executionId: string;
+    /** Total number of steps executed */
+    readonly stepCount: number;
+    /** Total tokens consumed (if LLM involved) */
+    readonly tokensUsed?: number;
+    /** Custom tags for filtering */
+    readonly tags: string[];
+}
+/**
+ * Configuration for a workflow graph
+ */
+export interface GraphConfig {
+    /** Unique identifier for the graph */
+    readonly id: string;
+    /** Human-readable name */
+    readonly name: string;
+    /** Description of what this graph does */
+    readonly description?: string;
+    /** Entry point node name */
+    readonly entryPoint: string;
+    /** Node definitions */
+    readonly nodes: Map<string, NodeDefinition>;
+    /** Edge definitions */
+    readonly edges: Map<string, EdgeDefinition[]>;
+    /** Global graph configuration */
+    readonly config: GraphGlobalConfig;
+}
+/**
+ * Global configuration options for graph execution
+ */
+export interface GraphGlobalConfig {
+    /** Maximum number of iterations (cycle protection) */
+    readonly maxIterations: number;
+    /** Timeout in milliseconds */
+    readonly timeout: number;
+    /** Whether to enable checkpointing */
+    readonly checkpointEnabled: boolean;
+    /** Checkpoint interval (every N steps) */
+    readonly checkpointInterval: number;
+    /** Whether to enable parallel execution where possible */
+    readonly parallelExecution: boolean;
+    /** Retry configuration */
+    readonly retry: RetryConfig;
+    /** Logging level */
+    readonly logLevel: LogLevel;
+}
+/**
+ * Retry configuration for failed nodes
+ */
+export interface RetryConfig {
+    /** Maximum number of retries */
+    readonly maxRetries: number;
+    /** Initial delay in milliseconds */
+    readonly initialDelay: number;
+    /** Backoff multiplier */
+    readonly backoffMultiplier: number;
+    /** Maximum delay in milliseconds */
+    readonly maxDelay: number;
+    /** Error codes that should trigger retry */
+    readonly retryableErrors: string[];
+}
+/**
+ * Logging level for graph execution
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * Definition of a node in the workflow graph
+ */
+export interface NodeDefinition<TState extends AgentState = AgentState> {
+    /** Unique identifier for this node */
+    readonly id: string;
+    /** Human-readable name */
+    readonly name: string;
+    /** Node type */
+    readonly type: NodeType;
+    /** Node-specific configuration */
+    readonly config: NodeConfig;
+    /** The function to execute for this node */
+    readonly execute: NodeExecutor<TState>;
+    /** Pre-execution hooks */
+    readonly preHooks?: NodeHook<TState>[];
+    /** Post-execution hooks */
+    readonly postHooks?: NodeHook<TState>[];
+    /** Validation schema for node output */
+    readonly outputSchema?: z.ZodSchema;
+}
+/**
+ * Types of nodes in the workflow
+ */
+export type NodeType = 'llm' | 'tool' | 'decision' | 'human' | 'aggregate' | 'transform' | 'start' | 'end';
+/**
+ * Node configuration options
+ */
+export interface NodeConfig {
+    /** Whether this node can run in parallel with others */
+    readonly parallel?: boolean;
+    /** Timeout for this specific node */
+    readonly timeout?: number;
+    /** Retry configuration override */
+    readonly retry?: Partial<RetryConfig>;
+    /** Custom metadata */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Function signature for node execution
+ */
+export type NodeExecutor<TState extends AgentState = AgentState> = (state: TState, context: NodeContext) => Promise<NodeResult<TState>>;
+/**
+ * Context provided to node executors
+ */
+export interface NodeContext {
+    /** Node definition */
+    readonly node: NodeDefinition;
+    /** Graph configuration */
+    readonly graph: GraphConfig;
+    /** Execution ID */
+    readonly executionId: string;
+    /** Current iteration count */
+    readonly iterationCount: number;
+    /** Shared services */
+    readonly services: NodeServices;
+    /** Abort signal for cancellation */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Services available to nodes
+ */
+export interface NodeServices {
+    /** Logger instance */
+    readonly logger: Logger;
+    /** Checkpointing service */
+    readonly checkpointer?: GraphCheckpointer;
+    /** Tool registry */
+    readonly toolRegistry?: ToolRegistry;
+    /** LLM provider */
+    readonly llmProvider?: LLMProvider;
+}
+/**
+ * Logger interface
+ */
+export interface Logger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * Tool registry interface
+ */
+export interface ToolRegistry {
+    get(name: string): Tool | undefined;
+    list(): Tool[];
+    register(tool: Tool): void;
+    unregister(name: string): void;
+}
+/**
+ * Tool definition
+ */
+export interface Tool {
+    /** Unique tool name */
+    readonly name: string;
+    /** Tool description for LLM */
+    readonly description: string;
+    /** Input schema */
+    readonly inputSchema: z.ZodSchema;
+    /** Output schema */
+    readonly outputSchema?: z.ZodSchema;
+    /** Tool execution function */
+    execute(input: unknown): Promise<unknown>;
+}
+/**
+ * LLM provider interface
+ */
+export interface LLMProvider {
+    /** Generate a response */
+    generate(request: LLMRequest): Promise<LLMResponse>;
+    /** Stream a response */
+    stream?(request: LLMRequest): AsyncIterable<LLMStreamChunk>;
+}
+/**
+ * LLM request
+ */
+export interface LLMRequest {
+    /** Messages to send */
+    readonly messages: Message[];
+    /** Model to use */
+    readonly model?: string;
+    /** Temperature */
+    readonly temperature?: number;
+    /** Maximum tokens */
+    readonly maxTokens?: number;
+    /** Available tools */
+    readonly tools?: Tool[];
+    /** Stop sequences */
+    readonly stop?: string[];
+}
+/**
+ * LLM response
+ */
+export interface LLMResponse {
+    /** Generated message */
+    readonly message: Message;
+    /** Token usage */
+    readonly usage: TokenUsage;
+    /** Model used */
+    readonly model: string;
+    /** Finish reason */
+    readonly finishReason: FinishReason;
+}
+/**
+ * Token usage information
+ */
+export interface TokenUsage {
+    /** Prompt tokens */
+    readonly promptTokens: number;
+    /** Completion tokens */
+    readonly completionTokens: number;
+    /** Total tokens */
+    readonly totalTokens: number;
+}
+/**
+ * Reason for LLM completion
+ */
+export type FinishReason = 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error';
+/**
+ * Streaming chunk from LLM
+ */
+export interface LLMStreamChunk {
+    /** Delta content */
+    readonly delta: string;
+    /** Whether this is the final chunk */
+    readonly done: boolean;
+    /** Finish reason if done */
+    readonly finishReason?: FinishReason;
+}
+/**
+ * Result from node execution
+ */
+export interface NodeResult<TState extends AgentState = AgentState> {
+    /** Updated state */
+    readonly state: TState;
+    /** Next node(s) to execute */
+    readonly next?: string | string[];
+    /** Whether to terminate the workflow */
+    readonly terminate?: boolean;
+    /** Execution metadata */
+    readonly metadata?: NodeExecutionMetadata;
+}
+/**
+ * Metadata from node execution
+ */
+export interface NodeExecutionMetadata {
+    /** Duration in milliseconds */
+    readonly duration: number;
+    /** Tokens used if LLM node */
+    readonly tokensUsed?: number;
+    /** Tool calls made */
+    readonly toolCalls?: ToolCall[];
+    /** Retry count if retried */
+    readonly retryCount?: number;
+}
+/**
+ * Hook function signature
+ */
+export type NodeHook<TState extends AgentState = AgentState> = (state: TState, context: NodeContext) => Promise<TState>;
+/**
+ * Definition of an edge in the workflow graph
+ */
+export interface EdgeDefinition {
+    /** Source node */
+    readonly from: string;
+    /** Target node */
+    readonly to: string;
+    /** Edge type */
+    readonly type: EdgeType;
+    /** Condition for conditional edges */
+    readonly condition?: EdgeCondition;
+    /** Edge metadata */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Types of edges
+ */
+export type EdgeType = 'direct' | 'conditional' | 'loop' | 'parallel';
+/**
+ * Condition for edge traversal
+ */
+export interface EdgeCondition {
+    /** Condition type */
+    readonly type: ConditionType;
+    /** Field to check in state */
+    readonly field?: string;
+    /** Value to compare against */
+    readonly value?: unknown;
+    /** Custom condition function */
+    readonly evaluate?: EdgeConditionEvaluator;
+}
+/**
+ * Types of conditions
+ */
+export type ConditionType = 'equals' | 'not_equals' | 'contains' | 'greater_than' | 'less_than' | 'exists' | 'not_exists' | 'custom';
+/**
+ * Custom condition evaluator
+ */
+export type EdgeConditionEvaluator<TState extends AgentState = AgentState> = (state: TState, context: EdgeContext) => Promise<boolean>;
+/**
+ * Context provided to edge evaluators
+ */
+export interface EdgeContext {
+    /** Edge definition */
+    readonly edge: EdgeDefinition;
+    /** Source node result */
+    readonly sourceResult: NodeResult;
+    /** Graph configuration */
+    readonly graph: GraphConfig;
+}
+/**
+ * Interface for checkpoint persistence
+ */
+export interface GraphCheckpointer {
+    /** Save a checkpoint */
+    save(checkpoint: Checkpoint): Promise<void>;
+    /** Load a checkpoint by ID */
+    load(checkpointId: string): Promise<Checkpoint | null>;
+    /** List checkpoints for an execution */
+    list(executionId: string): Promise<CheckpointSummary[]>;
+    /** Delete a checkpoint */
+    delete(checkpointId: string): Promise<void>;
+    /** Get the latest checkpoint for an execution */
+    getLatest(executionId: string): Promise<Checkpoint | null>;
+}
+/**
+ * Checkpoint data structure
+ */
+export interface Checkpoint {
+    /** Unique checkpoint identifier */
+    readonly id: string;
+    /** Execution ID this checkpoint belongs to */
+    readonly executionId: string;
+    /** Step number */
+    readonly stepNumber: number;
+    /** Node that created this checkpoint */
+    readonly nodeName: string;
+    /** Full state snapshot */
+    readonly state: AgentState;
+    /** Timestamp of checkpoint creation */
+    readonly timestamp: Date;
+    /** Parent checkpoint ID for branching */
+    readonly parentId?: string;
+    /** Custom metadata */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Summary of a checkpoint for listing
+ */
+export interface CheckpointSummary {
+    /** Checkpoint ID */
+    readonly id: string;
+    /** Execution ID */
+    readonly executionId: string;
+    /** Step number */
+    readonly stepNumber: number;
+    /** Node name */
+    readonly nodeName: string;
+    /** Timestamp */
+    readonly timestamp: Date;
+}
+/**
+ * Options for graph execution
+ */
+export interface ExecutionOptions {
+    /** Initial state */
+    readonly initialState?: Partial<AgentState>;
+    /** Checkpoint ID to resume from */
+    readonly resumeFrom?: string;
+    /** Override graph config */
+    readonly configOverrides?: Partial<GraphGlobalConfig>;
+    /** Abort signal */
+    readonly signal?: AbortSignal;
+    /** Event handlers */
+    readonly handlers?: ExecutionHandlers;
+}
+/**
+ * Event handlers for execution lifecycle
+ */
+export interface ExecutionHandlers {
+    /** Called when execution starts */
+    onStart?: (state: AgentState) => void;
+    /** Called when entering a node */
+    onNodeEnter?: (nodeName: string, state: AgentState) => void;
+    /** Called when exiting a node */
+    onNodeExit?: (nodeName: string, result: NodeResult) => void;
+    /** Called on checkpoint creation */
+    onCheckpoint?: (checkpoint: Checkpoint) => void;
+    /** Called on error */
+    onError?: (error: WorkflowError) => void;
+    /** Called when execution completes */
+    onComplete?: (state: AgentState) => void;
+}
+/**
+ * Result of graph execution
+ */
+export interface ExecutionResult {
+    /** Final state */
+    readonly state: AgentState;
+    /** Whether execution was successful */
+    readonly success: boolean;
+    /** Error if failed */
+    readonly error?: WorkflowError;
+    /** Execution statistics */
+    readonly stats: ExecutionStats;
+    /** Path through the graph */
+    readonly path: string[];
+}
+/**
+ * Statistics from graph execution
+ */
+export interface ExecutionStats {
+    /** Total execution time in milliseconds */
+    readonly duration: number;
+    /** Number of nodes executed */
+    readonly nodesExecuted: number;
+    /** Number of iterations */
+    readonly iterations: number;
+    /** Total tokens used */
+    readonly tokensUsed: number;
+    /** Checkpoints created */
+    readonly checkpointsCreated: number;
+    /** Retries performed */
+    readonly retries: number;
+}
+/**
+ * Schema for validating message structure
+ */
+export declare const MessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodEnum<["system", "user", "assistant", "tool"]>;
+    content: z.ZodString;
+    toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }, {
+        id: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }>, "many">>;
+    toolResult: z.ZodOptional<z.ZodObject<{
+        toolCallId: z.ZodString;
+        content: z.ZodString;
+        success: z.ZodBoolean;
+        error: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        toolCallId: string;
+        success: boolean;
+        error?: string | undefined;
+    }, {
+        content: string;
+        toolCallId: string;
+        success: boolean;
+        error?: string | undefined;
+    }>>;
+    timestamp: z.ZodDate;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    timestamp: Date;
+    toolCalls?: {
+        id: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }[] | undefined;
+    toolResult?: {
+        content: string;
+        toolCallId: string;
+        success: boolean;
+        error?: string | undefined;
+    } | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    id: string;
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    timestamp: Date;
+    toolCalls?: {
+        id: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }[] | undefined;
+    toolResult?: {
+        content: string;
+        toolCallId: string;
+        success: boolean;
+        error?: string | undefined;
+    } | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+/**
+ * Schema for validating graph configuration
+ */
+export declare const GraphConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    entryPoint: z.ZodString;
+    config: z.ZodObject<{
+        maxIterations: z.ZodNumber;
+        timeout: z.ZodNumber;
+        checkpointEnabled: z.ZodBoolean;
+        checkpointInterval: z.ZodNumber;
+        parallelExecution: z.ZodBoolean;
+        retry: z.ZodObject<{
+            maxRetries: z.ZodNumber;
+            initialDelay: z.ZodNumber;
+            backoffMultiplier: z.ZodNumber;
+            maxDelay: z.ZodNumber;
+            retryableErrors: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            maxRetries: number;
+            initialDelay: number;
+            backoffMultiplier: number;
+            maxDelay: number;
+            retryableErrors: string[];
+        }, {
+            maxRetries: number;
+            initialDelay: number;
+            backoffMultiplier: number;
+            maxDelay: number;
+            retryableErrors: string[];
+        }>;
+        logLevel: z.ZodEnum<["debug", "info", "warn", "error", "silent"]>;
+    }, "strip", z.ZodTypeAny, {
+        maxIterations: number;
+        timeout: number;
+        checkpointEnabled: boolean;
+        checkpointInterval: number;
+        parallelExecution: boolean;
+        retry: {
+            maxRetries: number;
+            initialDelay: number;
+            backoffMultiplier: number;
+            maxDelay: number;
+            retryableErrors: string[];
+        };
+        logLevel: "debug" | "info" | "warn" | "error" | "silent";
+    }, {
+        maxIterations: number;
+        timeout: number;
+        checkpointEnabled: boolean;
+        checkpointInterval: number;
+        parallelExecution: boolean;
+        retry: {
+            maxRetries: number;
+            initialDelay: number;
+            backoffMultiplier: number;
+            maxDelay: number;
+            retryableErrors: string[];
+        };
+        logLevel: "debug" | "info" | "warn" | "error" | "silent";
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    entryPoint: string;
+    config: {
+        maxIterations: number;
+        timeout: number;
+        checkpointEnabled: boolean;
+        checkpointInterval: number;
+        parallelExecution: boolean;
+        retry: {
+            maxRetries: number;
+            initialDelay: number;
+            backoffMultiplier: number;
+            maxDelay: number;
+            retryableErrors: string[];
+        };
+        logLevel: "debug" | "info" | "warn" | "error" | "silent";
+    };
+    description?: string | undefined;
+}, {
+    id: string;
+    name: string;
+    entryPoint: string;
+    config: {
+        maxIterations: number;
+        timeout: number;
+        checkpointEnabled: boolean;
+        checkpointInterval: number;
+        parallelExecution: boolean;
+        retry: {
+            maxRetries: number;
+            initialDelay: number;
+            backoffMultiplier: number;
+            maxDelay: number;
+            retryableErrors: string[];
+        };
+        logLevel: "debug" | "info" | "warn" | "error" | "silent";
+    };
+    description?: string | undefined;
+}>;
+/**
+ * Schema for validating checkpoint data
+ */
+export declare const CheckpointSchema: z.ZodObject<{
+    id: z.ZodString;
+    executionId: z.ZodString;
+    stepNumber: z.ZodNumber;
+    nodeName: z.ZodString;
+    timestamp: z.ZodDate;
+    parentId: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    timestamp: Date;
+    executionId: string;
+    stepNumber: number;
+    nodeName: string;
+    metadata?: Record<string, unknown> | undefined;
+    parentId?: string | undefined;
+}, {
+    id: string;
+    timestamp: Date;
+    executionId: string;
+    stepNumber: number;
+    nodeName: string;
+    metadata?: Record<string, unknown> | undefined;
+    parentId?: string | undefined;
+}>;
+//# sourceMappingURL=types.d.ts.map