@macrow/copilotkit-langgraph-history 0.1.7

package/dist/index.d.cts

@@ -0,0 +1,647 @@
+import { EventType, BaseEvent } from '@ag-ui/core';
+import { AgentRunnerRunRequest, AgentRunner, AgentRunnerStopRequest, AgentRunnerConnectRequest } from '@copilotkitnext/runtime';
+import { Observable } from 'rxjs';
+import { LangGraphAgent } from '@copilotkit/runtime/langgraph';
+import { RequestHook } from '@langchain/langgraph-sdk/client';
+
+/**
+ * Configuration for the HistoryHydratingAgentRunner.
+ */
+interface HistoryHydratingRunnerConfig {
+    /**
+     * The LangGraphAgent instance to delegate run() calls to.
+     */
+    agent: LangGraphAgent;
+    /**
+     * LangGraph deployment URL (required).
+     * Used to create fresh Client instances for history fetching.
+     */
+    deploymentUrl: string;
+    /**
+     * Graph ID for the agent.
+     */
+    graphId: string;
+    /**
+     * LangSmith API key for authentication (optional).
+     */
+    langsmithApiKey?: string;
+    /**
+     * Maximum number of history checkpoints to fetch.
+     * Default: 100, Maximum: 1000 (LangGraph API limit)
+     */
+    historyLimit?: number;
+    /**
+     * Client timeout in milliseconds.
+     * Default: 1800000 (30 minutes) - supports long-running agents.
+     */
+    clientTimeoutMs?: number;
+    /**
+     * Enable debug logging.
+     * Default: false
+     */
+    debug?: boolean;
+    /**
+     * Optional function to extract additional state from the request.
+     * Called during run() to enrich the state passed to the agent.
+     *
+     * @param input - The run request input
+     * @param forwardedProps - Optional forwarded props from CopilotKit
+     * @returns State object to merge with existing state
+     */
+    stateExtractor?: StateExtractor;
+    /**
+     * Optional request hook for the client.
+     */
+    onRequest?: RequestHook;
+}
+/**
+ * Function type for extracting state from run requests.
+ */
+type StateExtractor = (input: AgentRunnerRunRequest["input"], forwardedProps?: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * LangGraph message format from thread state.
+ */
+interface LangGraphMessage {
+    id: string;
+    type: "human" | "ai" | "tool" | "system";
+    content: string | Array<{
+        type: string;
+        text?: string;
+    }>;
+    tool_calls?: Array<{
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    }>;
+    tool_call_id?: string;
+}
+/**
+ * Thread state from LangGraph checkpoint.
+ */
+interface ThreadState {
+    values: {
+        messages?: LangGraphMessage[];
+        [key: string]: unknown;
+    };
+    next: string[];
+    config?: unknown;
+    created_at?: string;
+    parent_config?: unknown;
+    tasks?: Array<{
+        id: string;
+        name: string;
+        interrupts?: Array<{
+            value?: unknown;
+            [key: string]: unknown;
+        }>;
+        [key: string]: unknown;
+    }>;
+    checkpoint: unknown;
+    metadata: unknown;
+    parent_checkpoint?: unknown;
+}
+/**
+ * Tool used to predict state (for intermediate state emission).
+ */
+interface PredictStateTool {
+    tool: string;
+    state_key: string;
+    tool_argument: string;
+}
+/**
+ * Frozen agent config to prevent shared state contamination.
+ */
+interface FrozenAgentConfig {
+    deploymentUrl: string;
+    graphId: string;
+    langsmithApiKey?: string;
+    clientTimeoutMs: number;
+    onRequest?: RequestHook;
+}
+
+/**
+ * HistoryHydratingAgentRunner
+ *
+ * A custom AgentRunner that extends CopilotKit's base runner to add
+ * message history hydration support for LangGraph threads.
+ *
+ * Fixes the issue where page refreshes don't load historical messages
+ * by fetching thread state and emitting MESSAGES_SNAPSHOT events.
+ */
+
+/**
+ * Custom AgentRunner that extends CopilotKit's base runner to add
+ * message history hydration support for LangGraph threads.
+ *
+ * @example
+ * ```typescript
+ * import { HistoryHydratingAgentRunner, createIsolatedAgent } from 'copilotkit-langgraph-history';
+ *
+ * const agent = createIsolatedAgent({
+ *   deploymentUrl: process.env.LANGGRAPH_DEPLOYMENT_URL!,
+ *   graphId: "my-agent",
+ *   langsmithApiKey: process.env.LANGSMITH_API_KEY,
+ * });
+ *
+ * const runner = new HistoryHydratingAgentRunner({
+ *   agent,
+ *   deploymentUrl: process.env.LANGGRAPH_DEPLOYMENT_URL!,
+ *   graphId: "my-agent",
+ *   langsmithApiKey: process.env.LANGSMITH_API_KEY,
+ *   historyLimit: 100,
+ * });
+ *
+ * const runtime = new CopilotRuntime({
+ *   agents: { "my-agent": agent },
+ *   runner,
+ * });
+ * ```
+ */
+declare class HistoryHydratingAgentRunner extends AgentRunner {
+    private agent;
+    private historyLimit;
+    private debug;
+    private stateExtractor?;
+    private activeRun;
+    /**
+     * Frozen agent config to prevent shared state contamination.
+     * We store the raw config values and create fresh Agent/Client instances per request.
+     * This is critical because Vercel serverless can bundle multiple routes together,
+     * causing module-level state to leak between different agent configurations.
+     */
+    private readonly frozenConfig;
+    constructor(config: HistoryHydratingRunnerConfig);
+    /**
+     * Creates a fresh LangGraphAgent instance using the frozen config.
+     * Uses our isolated agent creator to prevent shared state contamination.
+     */
+    private createFreshAgent;
+    /**
+     * Creates a fresh LangGraph Client instance using the frozen config.
+     * This prevents shared state contamination in serverless environments.
+     */
+    private createFreshClient;
+    /**
+     * Log a message if debug mode is enabled.
+     */
+    private log;
+    /**
+     * Log a warning.
+     */
+    private warn;
+    /**
+     * Log an error.
+     */
+    private error;
+    /**
+     * Run the agent with a FRESH agent instance.
+     * CRITICAL: We cannot trust request.agent (cloned by CopilotKit) because
+     * its internal Client may have been corrupted by shared module state in
+     * Vercel serverless environments. Create a completely fresh agent with
+     * our frozen config to guarantee the correct deployment URL is used.
+     */
+    run(request: AgentRunnerRunRequest): Observable<{
+        type: EventType.TEXT_MESSAGE_START;
+        role: "developer" | "system" | "assistant" | "user";
+        messageId: string;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+    } | {
+        type: EventType.TEXT_MESSAGE_CONTENT;
+        messageId: string;
+        delta: string;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+    } | {
+        type: EventType.TEXT_MESSAGE_END;
+        messageId: string;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+    } | {
+        type: EventType.TOOL_CALL_START;
+        toolCallId: string;
+        toolCallName: string;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+        parentMessageId?: string | undefined;
+    } | {
+        type: EventType.TOOL_CALL_ARGS;
+        toolCallId: string;
+        delta: string;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+    } | {
+        type: EventType.TOOL_CALL_END;
+        toolCallId: string;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+    } | {
+        type: EventType.THINKING_TEXT_MESSAGE_START;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+    } | {
+        type: EventType.THINKING_TEXT_MESSAGE_CONTENT;
+        delta: string;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+    } | {
+        type: EventType.THINKING_TEXT_MESSAGE_END;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+    } | {
+        type: EventType.TOOL_CALL_RESULT;
+        content: string;
+        toolCallId: string;
+        messageId: string;
+        role?: "tool" | undefined;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+    } | {
+        type: EventType.THINKING_START;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+        title?: string | undefined;
+    } | {
+        type: EventType.THINKING_END;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+    } | {
+        type: EventType.STATE_SNAPSHOT;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+        snapshot?: any;
+    } | {
+        type: EventType.STATE_DELTA;
+        delta: any[];
+        timestamp?: number | undefined;
+        rawEvent?: any;
+    } | {
+        type: EventType.MESSAGES_SNAPSHOT;
+        messages: ({
+            id: string;
+            role: "developer";
+            content: string;
+            name?: string | undefined;
+        } | {
+            id: string;
+            role: "system";
+            content: string;
+            name?: string | undefined;
+        } | {
+            id: string;
+            role: "assistant";
+            name?: string | undefined;
+            content?: string | undefined;
+            toolCalls?: {
+                function: {
+                    name: string;
+                    arguments: string;
+                };
+                type: "function";
+                id: string;
+            }[] | undefined;
+        } | {
+            id: string;
+            role: "user";
+            content: string | ({
+                type: "text";
+                text: string;
+            } | {
+                type: "binary";
+                mimeType: string;
+                id?: string | undefined;
+                url?: string | undefined;
+                data?: string | undefined;
+                filename?: string | undefined;
+            })[];
+            name?: string | undefined;
+        } | {
+            id: string;
+            role: "tool";
+            content: string;
+            toolCallId: string;
+            error?: string | undefined;
+        } | {
+            id: string;
+            role: "activity";
+            content: Record<string, any>;
+            activityType: string;
+        })[];
+        timestamp?: number | undefined;
+        rawEvent?: any;
+    } | {
+        type: EventType.RAW;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+        event?: any;
+        source?: string | undefined;
+    } | {
+        name: string;
+        type: EventType.CUSTOM;
+        value?: any;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+    } | {
+        type: EventType.RUN_STARTED;
+        threadId: string;
+        runId: string;
+        parentRunId?: string | undefined;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+        input?: {
+            threadId: string;
+            runId: string;
+            messages: ({
+                id: string;
+                role: "developer";
+                content: string;
+                name?: string | undefined;
+            } | {
+                id: string;
+                role: "system";
+                content: string;
+                name?: string | undefined;
+            } | {
+                id: string;
+                role: "assistant";
+                name?: string | undefined;
+                content?: string | undefined;
+                toolCalls?: {
+                    function: {
+                        name: string;
+                        arguments: string;
+                    };
+                    type: "function";
+                    id: string;
+                }[] | undefined;
+            } | {
+                id: string;
+                role: "user";
+                content: string | ({
+                    type: "text";
+                    text: string;
+                } | {
+                    type: "binary";
+                    mimeType: string;
+                    id?: string | undefined;
+                    url?: string | undefined;
+                    data?: string | undefined;
+                    filename?: string | undefined;
+                })[];
+                name?: string | undefined;
+            } | {
+                id: string;
+                role: "tool";
+                content: string;
+                toolCallId: string;
+                error?: string | undefined;
+            } | {
+                id: string;
+                role: "activity";
+                content: Record<string, any>;
+                activityType: string;
+            })[];
+            tools: {
+                name: string;
+                description: string;
+                parameters?: any;
+            }[];
+            context: {
+                value: string;
+                description: string;
+            }[];
+            parentRunId?: string | undefined;
+            state?: any;
+            forwardedProps?: any;
+        } | undefined;
+    } | {
+        type: EventType.RUN_FINISHED;
+        threadId: string;
+        runId: string;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+        result?: any;
+    } | {
+        message: string;
+        type: EventType.RUN_ERROR;
+        code?: string | undefined;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+    } | {
+        type: EventType.STEP_STARTED;
+        stepName: string;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+    } | {
+        type: EventType.STEP_FINISHED;
+        stepName: string;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+    } | {
+        type: EventType;
+        name: string;
+        value: any;
+    }>;
+    /**
+     * Delegate isRunning to the agent.
+     */
+    isRunning(): Promise<boolean>;
+    /**
+     * Delegate stop to the agent.
+     */
+    stop(_request: AgentRunnerStopRequest): Promise<boolean | undefined>;
+    /**
+     * Override connect to add history hydration support.
+     *
+     * When reconnecting to a thread:
+     * 1. Fetches ALL thread history (checkpoints) from LangGraph
+     * 2. Extracts and deduplicates messages from all checkpoints
+     * 3. Transforms historical messages to CopilotKit format
+     * 4. Emits MESSAGES_SNAPSHOT and STATE_SNAPSHOT events
+     * 5. Completes the observable
+     */
+    connect(request: AgentRunnerConnectRequest): Observable<BaseEvent>;
+    /**
+     * Joins an active stream and processes its events.
+     *
+     * This method connects to an already-running LangGraph execution and
+     * processes all incoming events, transforming them to BaseEvent format.
+     *
+     * Tracks started messages and tool calls to handle mid-stream joins where
+     * we might receive CONTENT/END events without having seen START events.
+     */
+    private joinAndProcessStream;
+}
+
+/**
+ * LangGraph Agent Isolation Utilities
+ *
+ * Fixes shared state contamination in Vercel serverless (Fluid Compute)
+ * where CopilotKit's LangGraphAgent can get wrong deploymentUrl due to
+ * module-level state being shared between bundled routes.
+ *
+ * Root cause: CopilotKit's clone() passes config by reference, not by value.
+ * Our fix: Create completely isolated agents with verified URLs.
+ */
+
+/**
+ * Configuration for creating an isolated LangGraph agent.
+ */
+interface CreateIsolatedAgentConfig {
+    /**
+     * LangGraph deployment URL.
+     */
+    deploymentUrl: string;
+    /**
+     * Graph ID for the agent.
+     */
+    graphId: string;
+    /**
+     * LangSmith API key for authentication (optional).
+     */
+    langsmithApiKey?: string;
+    /**
+     * Client timeout in milliseconds.
+     * Default: 1800000 (30 minutes)
+     */
+    clientTimeoutMs?: number;
+    /**
+     * Enable debug mode on the agent.
+     */
+    debug?: boolean;
+    /**
+     * Optional request hook for the client.
+     */
+    onRequest?: RequestHook;
+}
+/**
+ * Creates a completely isolated LangGraphAgent that cannot be contaminated
+ * by shared module state. This is the "nuclear option" fix for serverless
+ * environments like Vercel Fluid Compute.
+ *
+ * Key features:
+ * 1. Creates agent with fresh, frozen config
+ * 2. Verifies the internal client has correct URL
+ * 3. Force-replaces client if contamination detected
+ *
+ * @example
+ * ```typescript
+ * const agent = createIsolatedAgent({
+ *   deploymentUrl: process.env.LANGGRAPH_DEPLOYMENT_URL!,
+ *   graphId: "my-agent",
+ *   langsmithApiKey: process.env.LANGSMITH_API_KEY,
+ * });
+ * ```
+ */
+declare function createIsolatedAgent(config: CreateIsolatedAgentConfig): LangGraphAgent;
+
+/**
+ * Default timeout for LangGraph Client HTTP requests (30 minutes).
+ * Long timeout supports long-running agent workflows.
+ */
+declare const DEFAULT_TIMEOUT: number;
+/**
+ * Default number of history checkpoints to fetch.
+ */
+declare const DEFAULT_HISTORY_LIMIT = 100;
+/**
+ * Maximum history limit allowed by the LangGraph API.
+ */
+declare const MAX_HISTORY_LIMIT = 1000;
+
+/**
+ * Custom event names that CopilotKit uses for manual emissions.
+ * These match exactly what CopilotKit's LangGraphAgent expects.
+ */
+declare enum CustomEventNames {
+    CopilotKitManuallyEmitMessage = "copilotkit_manually_emit_message",
+    CopilotKitManuallyEmitToolCall = "copilotkit_manually_emit_tool_call",
+    CopilotKitManuallyEmitIntermediateState = "copilotkit_manually_emit_intermediate_state",
+    CopilotKitExit = "copilotkit_exit"
+}
+
+/**
+ * LangGraph event types for stream processing.
+ * These correspond to LangChain/LangGraph lifecycle events.
+ */
+declare enum LangGraphEventTypes {
+    OnChatModelStart = "on_chat_model_start",
+    OnChatModelStream = "on_chat_model_stream",
+    OnChatModelEnd = "on_chat_model_end",
+    OnToolStart = "on_tool_start",
+    OnToolEnd = "on_tool_end",
+    OnChainStart = "on_chain_start",
+    OnChainEnd = "on_chain_end"
+}
+
+/**
+ * Transformed message in CopilotKit format.
+ */
+interface TransformedMessage {
+    id: string;
+    role: "user" | "assistant" | "system" | "tool";
+    content: string;
+    toolCalls?: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+    toolCallId?: string;
+}
+/**
+ * Extracts text content from LangGraph message content.
+ * Handles both string and array formats.
+ */
+declare function extractContent(content: string | Array<{
+    type: string;
+    text?: string;
+}>): string;
+/**
+ * Transforms LangGraph messages to CopilotKit message format.
+ *
+ * Based on the `ut` function from @ag-ui/langgraph but adapted
+ * for standalone use.
+ */
+declare function transformMessages(messages: LangGraphMessage[], options?: {
+    debug?: boolean;
+}): TransformedMessage[];
+
+/**
+ * Context for stream processing.
+ */
+interface StreamProcessorContext {
+    threadId: string;
+    runId: string;
+    subscriber: {
+        next: (event: BaseEvent) => void;
+    };
+    startedMessages?: Set<string>;
+    startedToolCalls?: Set<string>;
+    debug?: boolean;
+    manuallyEmittedState?: Record<string, unknown>;
+}
+/**
+ * Stream chunk from LangGraph.
+ */
+interface StreamChunk {
+    id?: string;
+    event: string;
+    data: unknown;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Processes a single stream chunk and transforms it to BaseEvent format.
+ *
+ * Based on CopilotKit's event processing patterns from the agent's .run method.
+ * Handles all event types including custom events, metadata filtering, and
+ * transformations for TEXT_MESSAGE and TOOL_CALL events.
+ */
+declare function processStreamChunk(chunk: StreamChunk, context: StreamProcessorContext): Promise<{
+    runId: string;
+    manuallyEmittedState?: Record<string, unknown>;
+}>;
+
+export { type CreateIsolatedAgentConfig, CustomEventNames, DEFAULT_HISTORY_LIMIT, DEFAULT_TIMEOUT, type FrozenAgentConfig, HistoryHydratingAgentRunner, type HistoryHydratingRunnerConfig, LangGraphEventTypes, type LangGraphMessage, MAX_HISTORY_LIMIT, type PredictStateTool, type StateExtractor, type StreamChunk, type StreamProcessorContext, type ThreadState, type TransformedMessage, createIsolatedAgent, extractContent, processStreamChunk, transformMessages };