@copilotkit/runtime 0.0.0-0.0.0-max-changeset-10101010101010-20260109191632

package/src/agents/langgraph/event-source.ts

@@ -0,0 +1,329 @@
+import { CopilotKitLowLevelError, isStructuredCopilotKitError } from "@copilotkit/shared";
+import { catchError, mergeMap, ReplaySubject, scan } from "rxjs";
+import { generateHelpfulErrorMessage } from "../../lib/streaming";
+import {
+  RuntimeEvent,
+  RuntimeEventTypes,
+  RuntimeMetaEventName,
+} from "../../service-adapters/events";
+import { CustomEventNames, LangGraphEvent, LangGraphEventTypes } from "./events";
+
+interface LangGraphEventWithState {
+  event: LangGraphEvent | null;
+
+  isMessageStart: boolean;
+  isMessageEnd: boolean;
+  isToolCallStart: boolean;
+  isToolCallEnd: boolean;
+  isToolCall: boolean;
+
+  lastMessageId: string | null;
+  lastToolCallId: string | null;
+  lastToolCallName: string | null;
+  currentContent: string | null;
+  processedToolCallIds: Set<string>;
+}
+
+export class RemoteLangGraphEventSource {
+  public eventStream$ = new ReplaySubject<LangGraphEvent>();
+
+  private shouldEmitToolCall(
+    shouldEmitToolCalls: string | string[] | boolean,
+    toolCallName: string,
+  ) {
+    if (typeof shouldEmitToolCalls === "boolean") {
+      return shouldEmitToolCalls;
+    }
+    if (Array.isArray(shouldEmitToolCalls)) {
+      return shouldEmitToolCalls.includes(toolCallName);
+    }
+    return shouldEmitToolCalls === toolCallName;
+  }
+
+  private getCurrentContent(event: LangGraphEvent) {
+    // @ts-expect-error -- LangGraph Platform implementation stores data outside of kwargs
+    const content = event.data?.chunk?.kwargs?.content ?? event.data?.chunk?.content;
+
+    if (!content) {
+      const toolCallChunks = this.getCurrentToolCallChunks(event) ?? [];
+      for (const chunk of toolCallChunks) {
+        if (chunk.args) {
+          return chunk.args;
+        }
+      }
+    }
+
+    if (typeof content === "string") {
+      return content;
+    } else if (Array.isArray(content) && content.length > 0) {
+      return content[0].text;
+    }
+
+    return null;
+  }
+
+  private getCurrentMessageId(event: LangGraphEvent) {
+    // @ts-expect-error -- LangGraph Platform implementation stores data outside of kwargs
+    return event.data?.chunk?.kwargs?.id ?? event.data?.chunk?.id;
+  }
+
+  private getCurrentToolCallChunks(event: LangGraphEvent) {
+    // @ts-expect-error -- LangGraph Platform implementation stores data outside of kwargs
+    return event.data?.chunk?.kwargs?.tool_call_chunks ?? event.data?.chunk?.tool_call_chunks;
+  }
+
+  private getResponseMetadata(event: LangGraphEvent) {
+    // @ts-expect-error -- LangGraph Platform implementation stores data outside of kwargs
+    return event.data?.chunk?.kwargs?.response_metadata ?? event.data?.chunk?.response_metadata;
+  }
+
+  processLangGraphEvents() {
+    let lastEventWithState: LangGraphEventWithState | null = null;
+
+    return this.eventStream$.pipe(
+      scan(
+        (acc, event) => {
+          if (event.event === LangGraphEventTypes.OnChatModelStream) {
+            const prevMessageId = acc.lastMessageId;
+            acc.currentContent = this.getCurrentContent(event);
+            acc.lastMessageId = this.getCurrentMessageId(event) ?? acc.lastMessageId;
+            const toolCallChunks = this.getCurrentToolCallChunks(event) ?? [];
+            const responseMetadata = this.getResponseMetadata(event);
+            // Check if a given event is a tool call
+            const toolCallCheck = toolCallChunks && toolCallChunks.length > 0;
+            let isToolCallEnd = responseMetadata?.finish_reason === "tool_calls";
+
+            acc.isToolCallStart = toolCallChunks.some((chunk: any) => chunk.name && chunk.id);
+            acc.isMessageStart = prevMessageId !== acc.lastMessageId && !acc.isToolCallStart;
+
+            let previousRoundHadToolCall = acc.isToolCall;
+            acc.isToolCall = toolCallCheck;
+            // Previous "acc.isToolCall" was set but now it won't pass the check, it means the tool call just ended.
+            if (previousRoundHadToolCall && !toolCallCheck) {
+              isToolCallEnd = true;
+            }
+            acc.isToolCallEnd = isToolCallEnd;
+            acc.isMessageEnd = responseMetadata?.finish_reason === "stop";
+            ({ name: acc.lastToolCallName, id: acc.lastToolCallId } = toolCallChunks.find(
+              (chunk: any) => chunk.name && chunk.id,
+            ) ?? { name: acc.lastToolCallName, id: acc.lastToolCallId });
+          }
+          acc.event = event;
+          lastEventWithState = acc; // Capture the state
+          return acc;
+        },
+        {
+          event: null,
+          isMessageStart: false,
+          isMessageEnd: false,
+          isToolCallStart: false,
+          isToolCallEnd: false,
+          isToolCall: false,
+          lastMessageId: null,
+          lastToolCallId: null,
+          lastToolCallName: null,
+          currentContent: null,
+          processedToolCallIds: new Set<string>(),
+        } as LangGraphEventWithState,
+      ),
+      mergeMap((acc): RuntimeEvent[] => {
+        const events: RuntimeEvent[] = [];
+
+        let shouldEmitMessages = true;
+        let shouldEmitToolCalls: string | string[] | boolean = true;
+
+        if (acc.event.event == LangGraphEventTypes.OnChatModelStream) {
+          if ("copilotkit:emit-tool-calls" in (acc.event.metadata || {})) {
+            shouldEmitToolCalls = acc.event.metadata["copilotkit:emit-tool-calls"];
+          }
+          if ("copilotkit:emit-messages" in (acc.event.metadata || {})) {
+            shouldEmitMessages = acc.event.metadata["copilotkit:emit-messages"];
+          }
+        }
+
+        if (acc.event.event === LangGraphEventTypes.OnInterrupt) {
+          events.push({
+            type: RuntimeEventTypes.MetaEvent,
+            name: RuntimeMetaEventName.LangGraphInterruptEvent,
+            value: acc.event.value,
+          });
+        }
+        if (acc.event.event === LangGraphEventTypes.OnCopilotKitInterrupt) {
+          events.push({
+            type: RuntimeEventTypes.MetaEvent,
+            name: RuntimeMetaEventName.CopilotKitLangGraphInterruptEvent,
+            data: acc.event.data,
+          });
+        }
+
+        // Handle CopilotKit error events with preserved semantic information
+        if (acc.event.event === LangGraphEventTypes.OnCopilotKitError) {
+          const errorData = acc.event.data.error;
+
+          // Create a structured error with the original semantic information
+          const preservedError = new CopilotKitLowLevelError({
+            error: new Error(errorData.message),
+            url: "langgraph agent",
+            message: `${errorData.type}: ${errorData.message}`,
+          });
+
+          // Add additional error context to the error object
+          if (errorData.status_code) {
+            (preservedError as any).statusCode = errorData.status_code;
+          }
+          if (errorData.response_data) {
+            (preservedError as any).responseData = errorData.response_data;
+          }
+          (preservedError as any).agentName = errorData.agent_name;
+          (preservedError as any).originalErrorType = errorData.type;
+
+          // Throw the structured error to be handled by the catchError operator
+          throw preservedError;
+        }
+
+        const responseMetadata = this.getResponseMetadata(acc.event);
+
+        // Tool call ended: emit ActionExecutionEnd
+        if (
+          acc.isToolCallEnd &&
+          this.shouldEmitToolCall(shouldEmitToolCalls, acc.lastToolCallName) &&
+          acc.lastToolCallId &&
+          !acc.processedToolCallIds.has(acc.lastToolCallId)
+        ) {
+          acc.processedToolCallIds.add(acc.lastToolCallId);
+
+          events.push({
+            type: RuntimeEventTypes.ActionExecutionEnd,
+            actionExecutionId: acc.lastToolCallId,
+          });
+        }
+
+        // Message ended: emit TextMessageEnd
+        else if (responseMetadata?.finish_reason === "stop" && shouldEmitMessages) {
+          events.push({
+            type: RuntimeEventTypes.TextMessageEnd,
+            messageId: acc.lastMessageId,
+          });
+        }
+
+        switch (acc.event!.event) {
+          //
+          // Custom events
+          //
+          case LangGraphEventTypes.OnCustomEvent:
+            //
+            // Manually emit a message
+            //
+            if (acc.event.name === CustomEventNames.CopilotKitManuallyEmitMessage) {
+              events.push({
+                type: RuntimeEventTypes.TextMessageStart,
+                messageId: acc.event.data.message_id,
+              });
+              events.push({
+                type: RuntimeEventTypes.TextMessageContent,
+                messageId: acc.event.data.message_id,
+                content: acc.event.data.message,
+              });
+              events.push({
+                type: RuntimeEventTypes.TextMessageEnd,
+                messageId: acc.event.data.message_id,
+              });
+            }
+            //
+            // Manually emit a tool call
+            //
+            else if (acc.event.name === CustomEventNames.CopilotKitManuallyEmitToolCall) {
+              events.push({
+                type: RuntimeEventTypes.ActionExecutionStart,
+                actionExecutionId: acc.event.data.id,
+                actionName: acc.event.data.name,
+                parentMessageId: acc.event.data.id,
+              });
+              events.push({
+                type: RuntimeEventTypes.ActionExecutionArgs,
+                actionExecutionId: acc.event.data.id,
+                args: JSON.stringify(acc.event.data.args),
+              });
+              events.push({
+                type: RuntimeEventTypes.ActionExecutionEnd,
+                actionExecutionId: acc.event.data.id,
+              });
+            }
+            break;
+          case LangGraphEventTypes.OnCopilotKitStateSync:
+            events.push({
+              type: RuntimeEventTypes.AgentStateMessage,
+              threadId: acc.event.thread_id,
+              role: acc.event.role,
+              agentName: acc.event.agent_name,
+              nodeName: acc.event.node_name,
+              runId: acc.event.run_id,
+              active: acc.event.active,
+              state: JSON.stringify(acc.event.state),
+              running: acc.event.running,
+            });
+            break;
+          case LangGraphEventTypes.OnChatModelStream:
+            if (
+              acc.isToolCallStart &&
+              this.shouldEmitToolCall(shouldEmitToolCalls, acc.lastToolCallName)
+            ) {
+              events.push({
+                type: RuntimeEventTypes.ActionExecutionStart,
+                actionExecutionId: acc.lastToolCallId,
+                actionName: acc.lastToolCallName,
+                parentMessageId: acc.lastMessageId,
+              });
+            }
+            // Message started: emit TextMessageStart
+            else if (acc.isMessageStart && shouldEmitMessages) {
+              acc.processedToolCallIds.clear();
+              events.push({
+                type: RuntimeEventTypes.TextMessageStart,
+                messageId: acc.lastMessageId,
+              });
+            }
+
+            // Tool call args: emit ActionExecutionArgs
+            if (
+              acc.isToolCall &&
+              acc.currentContent &&
+              this.shouldEmitToolCall(shouldEmitToolCalls, acc.lastToolCallName)
+            ) {
+              events.push({
+                type: RuntimeEventTypes.ActionExecutionArgs,
+                actionExecutionId: acc.lastToolCallId,
+                args: acc.currentContent,
+              });
+            }
+            // Message content: emit TextMessageContent
+            else if (!acc.isToolCall && acc.currentContent && shouldEmitMessages) {
+              events.push({
+                type: RuntimeEventTypes.TextMessageContent,
+                messageId: acc.lastMessageId,
+                content: acc.currentContent,
+              });
+            }
+            break;
+        }
+        return events;
+      }),
+      catchError((error) => {
+        // If it's a structured CopilotKitError, re-throw it to be handled by the frontend error system
+        if (isStructuredCopilotKitError(error)) {
+          throw error;
+        }
+
+        // Determine a more helpful error message based on context
+        let helpfulMessage = generateHelpfulErrorMessage(error, "LangGraph agent connection");
+
+        // For all other errors, preserve the raw error information in a structured format
+        throw new CopilotKitLowLevelError({
+          error: error instanceof Error ? error : new Error(String(error)),
+          url: "langgraph event stream",
+          message: helpfulMessage,
+        });
+      }),
+    );
+  }
+}

package/src/agents/langgraph/events.ts

@@ -0,0 +1,377 @@
+import { ActionExecutionMessage, ResultMessage, TextMessage } from "../../graphql/types/converted";
+
+export enum LangGraphEventTypes {
+  OnChainStart = "on_chain_start",
+  OnChainStream = "on_chain_stream",
+  OnChainEnd = "on_chain_end",
+  OnChatModelStart = "on_chat_model_start",
+  OnChatModelStream = "on_chat_model_stream",
+  OnChatModelEnd = "on_chat_model_end",
+  OnToolStart = "on_tool_start",
+  OnToolEnd = "on_tool_end",
+  OnCopilotKitStateSync = "on_copilotkit_state_sync",
+  OnCopilotKitEmitMessage = "on_copilotkit_emit_message",
+  OnCopilotKitEmitToolCall = "on_copilotkit_emit_tool_call",
+  OnCustomEvent = "on_custom_event",
+  OnInterrupt = "on_interrupt",
+  OnCopilotKitInterrupt = "on_copilotkit_interrupt",
+  OnCopilotKitError = "on_copilotkit_error",
+}
+
+export enum MetaEventNames {
+  LangGraphInterruptEvent = "LangGraphInterruptEvent",
+  CopilotKitLangGraphInterruptEvent = "CopilotKitLangGraphInterruptEvent",
+}
+
+export enum CustomEventNames {
+  CopilotKitManuallyEmitMessage = "copilotkit_manually_emit_message",
+  CopilotKitManuallyEmitToolCall = "copilotkit_manually_emit_tool_call",
+  CopilotKitManuallyEmitIntermediateState = "copilotkit_manually_emit_intermediate_state",
+  CopilotKitExit = "copilotkit_exit",
+}
+
+type LangGraphOnCopilotKitStateSyncEvent = {
+  event: LangGraphEventTypes.OnCopilotKitStateSync;
+  thread_id: string;
+  agent_name: string;
+  node_name: string;
+  run_id: string;
+  active: boolean;
+  role: string;
+  state: any;
+  running: boolean;
+};
+
+type LangGraphOnChainStartEvent = {
+  event: LangGraphEventTypes.OnChainStart;
+  run_id: string;
+  name: string;
+  tags: string[];
+  metadata: { thread_id: string };
+  data: {
+    input: any;
+  };
+  parent_ids: string[];
+};
+
+type LangGraphOnChainEndEvent = {
+  event: LangGraphEventTypes.OnChainEnd;
+  name: string;
+  run_id: string;
+  tags: string[];
+  metadata: {
+    thread_id: string;
+    langgraph_step: number;
+    langgraph_node: string;
+    langgraph_triggers: string[];
+    langgraph_task_idx: number;
+    thread_ts: string;
+  };
+  data: {
+    input: any;
+    output: any;
+  };
+  parent_ids: string[];
+};
+
+type LangGraphOnChatModelStartEvent = {
+  event: LangGraphEventTypes.OnChatModelStart;
+  name: string;
+  run_id: string;
+  tags: string[];
+  metadata: {
+    thread_id: string;
+    langgraph_step: number;
+    langgraph_node: string;
+    langgraph_triggers: string[];
+    langgraph_task_idx: number;
+    thread_ts: string;
+    ls_provider: string;
+    ls_model_name: string;
+    ls_model_type: string;
+    ls_temperature: number;
+  };
+  data: {
+    input: {
+      messages: {
+        lc: number;
+        type: string;
+        id: string[];
+        kwargs: {
+          content: string;
+          type: string;
+          id: string;
+        };
+      }[][];
+    };
+  };
+  parent_ids: string[];
+};
+
+type LangGraphOnChatModelStreamEvent = {
+  event: LangGraphEventTypes.OnChatModelStream;
+  name: string;
+  run_id: string;
+  tags: string[];
+  metadata: {
+    thread_id: string;
+    langgraph_step: number;
+    langgraph_node: string;
+    langgraph_triggers: string[];
+    langgraph_task_idx: number;
+    thread_ts: string;
+    ls_provider: string;
+    ls_model_name: string;
+    ls_model_type: string;
+    ls_temperature: number;
+  };
+  data: {
+    chunk: {
+      lc: number;
+      type: string;
+      id: string;
+      kwargs: {
+        content: string | { text: string; type: string; index: number }[];
+        additional_kwargs: {
+          tool_calls: {
+            index: number;
+            id: string;
+            function: { arguments: string; name: string };
+            type: string;
+          }[];
+        };
+        type: string;
+        id: string;
+        tool_calls: { name: string; args: {}; id: string; type: string }[];
+        tool_call_chunks: {
+          name: string;
+          args: string;
+          id: string;
+          index: number;
+          type: string;
+        }[];
+        invalid_tool_calls: any[];
+      };
+    };
+  };
+  parent_ids: string[];
+};
+
+type LangGraphOnChatModelEndEvent = {
+  event: LangGraphEventTypes.OnChatModelEnd;
+  name: string;
+  run_id: string;
+  tags: string[];
+  metadata: {
+    thread_id: string;
+    langgraph_step: number;
+    langgraph_node: string;
+    langgraph_triggers: string[];
+    langgraph_task_idx: number;
+    thread_ts: string;
+    ls_provider: string;
+    ls_model_name: string;
+    ls_model_type: string;
+    ls_temperature: number;
+  };
+  data: {
+    input: any;
+    output: {
+      generations: {
+        text: string;
+        generation_info: {
+          finish_reason: string;
+          model_name: string;
+          system_fingerprint: string;
+        };
+        type: string;
+        message: {
+          lc: number;
+          type: string;
+          id: string[];
+          kwargs: {
+            content: string;
+            additional_kwargs: {
+              tool_calls: {
+                index: number;
+                id: string;
+                function: { arguments: string; name: string };
+                type: string;
+              }[];
+            };
+            response_metadata: {
+              finish_reason: string;
+              model_name: string;
+              system_fingerprint: string;
+            };
+            type: string;
+            id: string;
+            tool_calls: { name: string; args: { query: string }; id: string; type: string }[];
+            invalid_tool_calls: any[];
+          };
+        };
+      }[][];
+      llm_output: any;
+      run: any;
+    };
+  };
+  parent_ids: string[];
+};
+
+type LangGraphOnChainStreamEvent = {
+  event: LangGraphEventTypes.OnChainStream;
+  name: string;
+  run_id: string;
+  tags: string[];
+  metadata: {
+    thread_id: string;
+    langgraph_step?: number;
+    langgraph_node?: string;
+    langgraph_triggers?: string[];
+    langgraph_task_idx?: number;
+    thread_ts?: string;
+  };
+  data: {
+    chunk: {
+      messages: {
+        lc: number;
+        type: string;
+        id: string[];
+        kwargs: {
+          content: string;
+          additional_kwargs?: {
+            tool_calls?: {
+              index: number;
+              id: string;
+              function: { arguments: string; name: string };
+              type: string;
+            }[];
+          };
+          response_metadata?: {
+            finish_reason: string;
+            model_name: string;
+            system_fingerprint: string;
+          };
+          type: string;
+          id: string;
+          tool_calls?: { name: string; args: { query: string }; id: string; type: string }[];
+          invalid_tool_calls?: any[];
+        };
+      }[];
+    };
+  };
+  parent_ids: string[];
+};
+
+type LangGraphOnToolStartEvent = {
+  event: LangGraphEventTypes.OnToolStart;
+  name: string;
+  run_id: string;
+  tags: string[];
+  metadata: {
+    thread_id: string;
+    langgraph_step: number;
+    langgraph_node: string;
+    langgraph_triggers: string[];
+    langgraph_task_idx: number;
+    thread_ts: string;
+  };
+  data: {
+    input: {
+      query: string;
+    };
+  };
+  parent_ids: string[];
+};
+
+type LangGraphOnToolEndEvent = {
+  event: LangGraphEventTypes.OnToolEnd;
+  name: string;
+  run_id: string;
+  tags: string[];
+  metadata: {
+    thread_id: string;
+    langgraph_step: number;
+    langgraph_node: string;
+    langgraph_triggers: string[];
+    langgraph_task_idx: number;
+    thread_ts: string;
+  };
+  data: {
+    input: {
+      query: string;
+    };
+    output: {
+      lc: number;
+      type: string;
+      id: string[];
+      kwargs: {
+        content: string[];
+        type: string;
+        name: string;
+        tool_call_id: string;
+        status: string;
+      };
+    };
+  };
+  parent_ids: string[];
+};
+
+type LangGraphOnCustomEvent = {
+  event: LangGraphEventTypes.OnCustomEvent;
+  run_id: string;
+  name: string;
+  tags: string[];
+  metadata: {
+    thread_id: string;
+    langgraph_step: number;
+    langgraph_node: string;
+    langgraph_triggers: string[];
+    langgraph_path: [string, string];
+    langgraph_checkpoint_ns: string;
+    checkpoint_ns: string;
+  };
+  data: any;
+  parent_ids: string[];
+};
+
+interface LangGraphInterruptEvent {
+  event: LangGraphEventTypes.OnInterrupt;
+  value: string;
+}
+
+interface CopilotKitLangGraphInterruptEvent {
+  event: LangGraphEventTypes.OnCopilotKitInterrupt;
+  data: { value: string; messages: (TextMessage | ActionExecutionMessage | ResultMessage)[] };
+}
+
+interface CopilotKitLangGraphErrorEvent {
+  event: LangGraphEventTypes.OnCopilotKitError;
+  data: {
+    error: {
+      message: string;
+      type: string;
+      agent_name: string;
+      status_code?: number;
+      response_data?: any;
+    };
+    thread_id: string;
+    agent_name: string;
+    node_name: string;
+  };
+}
+
+export type LangGraphEvent =
+  | LangGraphOnChainStartEvent
+  | LangGraphOnChainStreamEvent
+  | LangGraphOnChainEndEvent
+  | LangGraphOnChatModelStartEvent
+  | LangGraphOnChatModelStreamEvent
+  | LangGraphOnChatModelEndEvent
+  | LangGraphOnToolStartEvent
+  | LangGraphOnToolEndEvent
+  | LangGraphOnCopilotKitStateSyncEvent
+  | LangGraphOnCustomEvent
+  | LangGraphInterruptEvent
+  | CopilotKitLangGraphInterruptEvent
+  | CopilotKitLangGraphErrorEvent;