@copilotkit/runtime 1.9.1-next.0 → 1.9.2-next.0

package/dist/lib/integrations/node-http/index.mjs

@@ -1,6 +1,6 @@
 import {
   copilotRuntimeNodeHttpEndpoint
-} from "../../../chunk-YVZCIKZM.mjs";
+} from "../../../chunk-YMIOUUPV.mjs";
 import "../../../chunk-IIXJVVTV.mjs";
 import "../../../chunk-5BIEM2UU.mjs";
 import "../../../chunk-SHBDMA63.mjs";

package/dist/{shared-0c31d7c5.d.ts → shared-e272b15a.d.ts}

@@ -360,6 +360,7 @@ declare class CopilotRuntime<const T extends Parameter[] | [] = []> {
     private processAgentRequest;
     private getServerSideActions;
     private detectProvider;
+    private convertStreamingErrorToStructured;
 }
 declare function flattenToolCallsNoDuplicates(toolsByPriority: ActionInput[]): ActionInput[];
 declare function copilotKitEndpoint(config: Omit<CopilotKitEndpoint, "type">): CopilotKitEndpoint;

package/package.json

@@ -9,7 +9,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.9.1-next.0",
+  "version": "1.9.2-next.0",
   "sideEffects": false,
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -66,7 +66,7 @@
     "rxjs": "^7.8.1",
     "type-graphql": "2.0.0-rc.1",
     "zod": "^3.23.3",
-    "@copilotkit/shared": "1.9.1-next.0"
+    "@copilotkit/shared": "1.9.2-next.0"
   },
   "peerDependencies": {
     "@ag-ui/client": ">=0.0.28",

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

@@ -5,7 +5,7 @@ import {
   RuntimeEventTypes,
   RuntimeMetaEventName,
 } from "../../service-adapters/events";
-import { randomId } from "@copilotkit/shared";
+import { randomId, CopilotKitError } from "@copilotkit/shared";
 
 interface LangGraphEventWithState {
   event: LangGraphEvent | null;
@@ -284,6 +284,15 @@ export class RemoteLangGraphEventSource {
       }),
       catchError((error) => {
         console.error(error);
+
+        // If it's a structured CopilotKitError, re-throw it to be handled by the frontend error system
+        if (
+          error instanceof CopilotKitError ||
+          (error?.name && error.name.includes("CopilotKit"))
+        ) {
+          throw error;
+        }
+
         const events: RuntimeEvent[] = [];
 
         if (lastEventWithState?.lastMessageId && !lastEventWithState.isToolCall) {

package/src/graphql/resolvers/copilot.resolver.ts

@@ -54,6 +54,7 @@ import telemetry from "../../lib/telemetry-client";
 import { randomId } from "@copilotkit/shared";
 import { AgentsResponse } from "../types/agents-response.type";
 import { LangGraphEventTypes } from "../../agents/langgraph/events";
+import { CopilotKitError } from "@copilotkit/shared";
 
 const invokeGuardrails = async ({
   baseUrl,
@@ -646,6 +647,18 @@ export class CopilotResolver {
           },
           error: (err) => {
             logger.error({ err }, "Error in event stream");
+
+            // If it's a structured CopilotKitError, stop the repeater with the error so frontend can handle it
+            if (
+              err instanceof CopilotKitError ||
+              (err instanceof Error && err.name && err.name.includes("CopilotKit"))
+            ) {
+              eventStreamSubscription?.unsubscribe();
+              rejectOutputMessagesPromise(err);
+              stopStreamingMessages(err); // Pass the error to stop the GraphQL stream with this error
+              return;
+            }
+
             responseStatus$.next(
               new UnknownErrorResponse({
                 description: `An unknown error has occurred in the event stream`,

package/src/graphql/resolvers/state.resolver.ts

@@ -4,6 +4,7 @@ import { Query } from "type-graphql";
 import { LoadAgentStateResponse } from "../types/load-agent-state-response.type";
 import type { GraphQLContext } from "../../lib/integrations";
 import { LoadAgentStateInput } from "../inputs/load-agent-state.input";
+import { CopilotKitAgentDiscoveryError } from "@copilotkit/shared";
 
 @Resolver(() => LoadAgentStateResponse)
 export class StateResolver {
@@ -11,14 +12,11 @@ export class StateResolver {
   async loadAgentState(@Ctx() ctx: GraphQLContext, @Arg("data") data: LoadAgentStateInput) {
     const agents = await ctx._copilotkit.runtime.discoverAgentsFromEndpoints(ctx);
     const agent = agents.find((agent) => agent.name === data.agentName);
-
     if (!agent) {
-      return {
-        threadId: data.threadId || "",
-        threadExists: false,
-        state: JSON.stringify({}),
-        messages: JSON.stringify([]),
-      };
+      throw new CopilotKitAgentDiscoveryError({
+        agentName: data.agentName,
+        availableAgents: agents.map((a) => ({ name: a.name, id: a.name })),
+      });
     }
 
     const state = await ctx._copilotkit.runtime.loadAgentState(ctx, data.threadId, data.agentName);

package/src/lib/runtime/copilot-runtime.ts

@@ -20,9 +20,11 @@ import {
   CopilotKitApiDiscoveryError,
   randomId,
   CopilotKitError,
-  CopilotKitLowLevelError,
+  CopilotKitRemoteEndpointDiscoveryError,
   CopilotKitAgentDiscoveryError,
   CopilotKitMisuseError,
+  CopilotKitErrorCode,
+  CopilotKitLowLevelError,
 } from "@copilotkit/shared";
 import {
   CopilotServiceAdapter,
@@ -54,6 +56,7 @@ import { from } from "rxjs";
 import { AgentStateInput } from "../../graphql/inputs/agent-state.input";
 import { ActionInputAvailability } from "../../graphql/types/enums";
 import { createHeaders } from "./remote-action-constructors";
+import { fetchWithRetry } from "./retry-utils";
 import { Agent } from "../../graphql/types/agents-response.type";
 import { ExtensionsInput } from "../../graphql/inputs/extensions.input";
 import { ExtensionsResponse } from "../../graphql/types/extensions-response.type";
@@ -667,9 +670,11 @@ please use an LLM adapter instead.`,
       if (error instanceof CopilotKitError) {
         throw error;
       }
+
+      // Convert non-CopilotKitErrors to structured errors
       console.error("Error getting response:", error);
-      eventSource.sendErrorMessageToChat();
-      throw error;
+      const structuredError = this.convertStreamingErrorToStructured(error);
+      throw structuredError;
     }
   }
 
@@ -721,7 +726,7 @@ please use an LLM adapter instead.`,
         const cpkEndpoint = endpoint as CopilotKitEndpoint;
         const fetchUrl = `${endpoint.url}/info`;
         try {
-          const response = await fetch(fetchUrl, {
+          const response = await fetchWithRetry(fetchUrl, {
             method: "POST",
             headers: createHeaders(cpkEndpoint.onBeforeRequest, graphqlContext),
             body: JSON.stringify({ properties: graphqlContext.properties }),
@@ -810,7 +815,7 @@ please use an LLM adapter instead.`,
       const cpkEndpoint = agentWithEndpoint.endpoint as CopilotKitEndpoint;
       const fetchUrl = `${cpkEndpoint.url}/agents/state`;
       try {
-        const response = await fetch(fetchUrl, {
+        const response = await fetchWithRetry(fetchUrl, {
           method: "POST",
           headers: createHeaders(cpkEndpoint.onBeforeRequest, graphqlContext),
           body: JSON.stringify({
@@ -1022,7 +1027,9 @@ please use an LLM adapter instead.`,
               }
             }
 
-            eventStream$.error(err);
+            // Convert network termination errors to structured errors
+            const structuredError = this.convertStreamingErrorToStructured(err);
+            eventStream$.error(structuredError);
             eventStream$.complete();
           },
           complete: () => eventStream$.complete(),
@@ -1214,6 +1221,55 @@ please use an LLM adapter instead.`,
     if (adapterName.includes("LangChain")) return "langchain";
     return undefined;
   }
+
+  private convertStreamingErrorToStructured(error: any): CopilotKitError {
+    // Handle network termination errors
+    if (
+      error?.message?.includes("terminated") ||
+      error?.cause?.code === "UND_ERR_SOCKET" ||
+      error?.message?.includes("other side closed") ||
+      error?.code === "UND_ERR_SOCKET"
+    ) {
+      return new CopilotKitError({
+        message:
+          "Connection to agent was unexpectedly terminated. This may be due to the agent service being restarted or network issues. Please try again.",
+        code: CopilotKitErrorCode.NETWORK_ERROR,
+      });
+    }
+
+    // Handle other network-related errors
+    if (
+      error?.message?.includes("fetch failed") ||
+      error?.message?.includes("ECONNREFUSED") ||
+      error?.message?.includes("ENOTFOUND") ||
+      error?.message?.includes("ETIMEDOUT")
+    ) {
+      return new CopilotKitLowLevelError({
+        error: error instanceof Error ? error : new Error(String(error)),
+        url: "agent streaming connection",
+        message:
+          "Network error occurred during agent streaming. Please check your connection and try again.",
+      });
+    }
+
+    // Handle abort/cancellation errors (these are usually normal)
+    if (
+      error?.message?.includes("aborted") ||
+      error?.message?.includes("canceled") ||
+      error?.message?.includes("signal is aborted")
+    ) {
+      return new CopilotKitError({
+        message: "Agent request was cancelled",
+        code: CopilotKitErrorCode.UNKNOWN,
+      });
+    }
+
+    // Default: convert unknown streaming errors
+    return new CopilotKitError({
+      message: `Agent streaming error: ${error?.message || String(error)}`,
+      code: CopilotKitErrorCode.UNKNOWN,
+    });
+  }
 }
 
 export function flattenToolCallsNoDuplicates(toolsByPriority: ActionInput[]): ActionInput[] {

package/src/lib/runtime/remote-action-constructors.ts

@@ -20,6 +20,7 @@ import { writeJsonLineResponseToEventStream } from "../streaming";
 import { CopilotKitApiDiscoveryError, ResolvedCopilotKitError } from "@copilotkit/shared";
 import { parseJson, tryMap } from "@copilotkit/shared";
 import { ActionInput } from "../../graphql/inputs/action.input";
+import { fetchWithRetry } from "./retry-utils";
 
 export function constructLGCRemoteAction({
   endpoint,
@@ -144,15 +145,19 @@ export function constructRemoteActions({
 
       const fetchUrl = `${url}/actions/execute`;
       try {
-        const response = await fetch(fetchUrl, {
-          method: "POST",
-          headers,
-          body: JSON.stringify({
-            name: action.name,
-            arguments: args,
-            properties: graphqlContext.properties,
-          }),
-        });
+        const response = await fetchWithRetry(
+          fetchUrl,
+          {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+              name: action.name,
+              arguments: args,
+              properties: graphqlContext.properties,
+            }),
+          },
+          logger,
+        );
 
         if (!response.ok) {
           logger.error(
@@ -219,25 +224,29 @@ export function constructRemoteActions({
 
           const fetchUrl = `${url}/agents/execute`;
           try {
-            const response = await fetch(fetchUrl, {
-              method: "POST",
-              headers,
-              body: JSON.stringify({
-                name,
-                threadId,
-                nodeName,
-                messages: [...messages, ...additionalMessages],
-                state,
-                config,
-                properties: graphqlContext.properties,
-                actions: tryMap(actionInputsWithoutAgents, (action: ActionInput) => ({
-                  name: action.name,
-                  description: action.description,
-                  parameters: JSON.parse(action.jsonSchema),
-                })),
-                metaEvents,
-              }),
-            });
+            const response = await fetchWithRetry(
+              fetchUrl,
+              {
+                method: "POST",
+                headers,
+                body: JSON.stringify({
+                  name,
+                  threadId,
+                  nodeName,
+                  messages: [...messages, ...additionalMessages],
+                  state,
+                  config,
+                  properties: graphqlContext.properties,
+                  actions: tryMap(actionInputsWithoutAgents, (action: ActionInput) => ({
+                    name: action.name,
+                    description: action.description,
+                    parameters: JSON.parse(action.jsonSchema),
+                  })),
+                  metaEvents,
+                }),
+              },
+              logger,
+            );
 
             if (!response.ok) {
               logger.error(

package/src/lib/runtime/remote-lg-action.ts

@@ -19,6 +19,7 @@ import { MetaEventInput } from "../../graphql/inputs/meta-event.input";
 import { MetaEventName } from "../../graphql/types/meta-events.type";
 import { parseJson, CopilotKitMisuseError } from "@copilotkit/shared";
 import { RemoveMessage } from "@langchain/core/messages";
+import { RETRY_CONFIG, isRetryableError, sleep, calculateDelay } from "./retry-utils";
 
 type State = Record<string, any>;
 
@@ -88,32 +89,52 @@ let activeInterruptEvent = false;
 export async function execute(args: ExecutionArgs): Promise<ReadableStream<Uint8Array>> {
   return new ReadableStream({
     async start(controller) {
-      try {
-        await streamEvents(controller, args);
-        controller.close();
-      } catch (err) {
-        // Unwrap the possible cause
-        const cause = err?.cause;
-
-        // Check code directly if it exists
-        const errorCode = cause?.code || err?.code;
-
-        if (errorCode === "ECONNREFUSED") {
-          throw new CopilotKitMisuseError({
-            message: `
-              The LangGraph client could not connect to the graph. Please further check previous logs, which includes further details.
-              
-              See more: https://docs.copilotkit.ai/troubleshooting/common-issues`,
-          });
-        } else {
-          throw new CopilotKitMisuseError({
-            message: `
-              The LangGraph client threw unhandled error ${err}.
-              
-              See more: https://docs.copilotkit.ai/troubleshooting/common-issues`,
-          });
+      let lastError: any;
+
+      // Retry logic for transient connection errors
+      for (let attempt = 0; attempt <= RETRY_CONFIG.maxRetries; attempt++) {
+        try {
+          await streamEvents(controller, args);
+          controller.close();
+          return; // Success - exit retry loop
+        } catch (err) {
+          lastError = err;
+
+          // Check if this is a retryable error
+          if (isRetryableError(err) && attempt < RETRY_CONFIG.maxRetries) {
+            const delay = calculateDelay(attempt);
+            console.warn(
+              `LangGraph connection attempt ${attempt + 1}/${RETRY_CONFIG.maxRetries + 1} failed. ` +
+                `Retrying in ${delay}ms. Error: ${err?.message || String(err)}`,
+            );
+            await sleep(delay);
+            continue; // Retry
+          }
+
+          // Not retryable or max retries exceeded - handle error
+          break;
         }
       }
+
+      // Handle the final error after retries exhausted
+      const cause = lastError?.cause;
+      const errorCode = cause?.code || lastError?.code;
+
+      if (errorCode === "ECONNREFUSED") {
+        throw new CopilotKitMisuseError({
+          message: `
+            The LangGraph client could not connect to the graph after ${RETRY_CONFIG.maxRetries + 1} attempts. Please further check previous logs, which includes further details.
+            
+            See more: https://docs.copilotkit.ai/troubleshooting/common-issues`,
+        });
+      } else {
+        throw new CopilotKitMisuseError({
+          message: `
+            The LangGraph client threw unhandled error ${lastError}.
+            
+            See more: https://docs.copilotkit.ai/troubleshooting/common-issues`,
+        });
+      }
     },
   });
 }

package/src/lib/runtime/retry-utils.ts

@@ -0,0 +1,96 @@
+import { Logger } from "pino";
+
+// Retry configuration for network requests
+export const RETRY_CONFIG = {
+  maxRetries: 3,
+  baseDelayMs: 1000,
+  maxDelayMs: 5000,
+  // HTTP status codes that should be retried
+  retryableStatusCodes: [502, 503, 504, 408, 429],
+  // Network error patterns that should be retried
+  retryableErrorMessages: [
+    "fetch failed",
+    "network error",
+    "connection timeout",
+    "ECONNREFUSED",
+    "ETIMEDOUT",
+    "ENOTFOUND",
+    "ECONNRESET",
+  ],
+};
+
+// Helper function to check if an error/response is retryable
+export function isRetryableError(error: any, response?: Response): boolean {
+  // Check HTTP response status
+  if (response && RETRY_CONFIG.retryableStatusCodes.includes(response.status)) {
+    return true;
+  }
+
+  // Check error codes (for connection errors like ECONNREFUSED)
+  const errorCode = error?.cause?.code || error?.code;
+  if (errorCode && RETRY_CONFIG.retryableErrorMessages.includes(errorCode)) {
+    return true;
+  }
+
+  // Check error messages
+  const errorMessage = error?.message?.toLowerCase() || "";
+  return RETRY_CONFIG.retryableErrorMessages.some((msg) => errorMessage.includes(msg));
+}
+
+// Helper function to sleep for a given duration
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Calculate exponential backoff delay
+export function calculateDelay(attempt: number): number {
+  const delay = RETRY_CONFIG.baseDelayMs * Math.pow(2, attempt);
+  return Math.min(delay, RETRY_CONFIG.maxDelayMs);
+}
+
+// Retry wrapper for fetch requests
+export async function fetchWithRetry(
+  url: string,
+  options: RequestInit,
+  logger?: Logger,
+): Promise<Response> {
+  let lastError: any;
+
+  for (let attempt = 0; attempt <= RETRY_CONFIG.maxRetries; attempt++) {
+    try {
+      const response = await fetch(url, options);
+
+      // If response is retryable, treat as error and retry
+      if (isRetryableError(null, response) && attempt < RETRY_CONFIG.maxRetries) {
+        const delay = calculateDelay(attempt);
+        logger?.warn(
+          `Request to ${url} failed with status ${response.status}. ` +
+            `Retrying attempt ${attempt + 1}/${RETRY_CONFIG.maxRetries + 1} in ${delay}ms.`,
+        );
+        await sleep(delay);
+        continue;
+      }
+
+      return response; // Success or non-retryable error
+    } catch (error) {
+      lastError = error;
+
+      // Check if this is a retryable network error
+      if (isRetryableError(error) && attempt < RETRY_CONFIG.maxRetries) {
+        const delay = calculateDelay(attempt);
+        logger?.warn(
+          `Request to ${url} failed with network error. ` +
+            `Retrying attempt ${attempt + 1}/${RETRY_CONFIG.maxRetries + 1} in ${delay}ms. Error: ${error?.message || String(error)}`,
+        );
+        await sleep(delay);
+        continue;
+      }
+
+      // Not retryable or max retries exceeded
+      break;
+    }
+  }
+
+  // Re-throw the last error after retries exhausted
+  throw lastError;
+}

package/src/lib/streaming.ts

@@ -1,4 +1,5 @@
 import { ReplaySubject } from "rxjs";
+import { CopilotKitLowLevelError, CopilotKitError, CopilotKitErrorCode } from "@copilotkit/shared";
 
 export async function writeJsonLineResponseToEventStream<T>(
   response: ReadableStream<Uint8Array>,
@@ -52,8 +53,60 @@ export async function writeJsonLineResponseToEventStream<T>(
     }
   } catch (error) {
     console.error("Error in stream", error);
-    eventStream$.error(error);
+
+    // Convert network termination errors to structured errors
+    const structuredError = convertStreamingErrorToStructured(error);
+    eventStream$.error(structuredError);
     return;
   }
   eventStream$.complete();
 }
+
+function convertStreamingErrorToStructured(error: any): CopilotKitError {
+  // Handle network termination errors
+  if (
+    error?.message?.includes("terminated") ||
+    error?.cause?.code === "UND_ERR_SOCKET" ||
+    error?.message?.includes("other side closed") ||
+    error?.code === "UND_ERR_SOCKET"
+  ) {
+    return new CopilotKitError({
+      message:
+        "Connection to agent was unexpectedly terminated. This is likely due to the agent service being down or experiencing issues. Please check your agent logs and try again.",
+      code: CopilotKitErrorCode.NETWORK_ERROR,
+    });
+  }
+
+  // Handle other network-related errors
+  if (
+    error?.message?.includes("fetch failed") ||
+    error?.message?.includes("ECONNREFUSED") ||
+    error?.message?.includes("ENOTFOUND") ||
+    error?.message?.includes("ETIMEDOUT")
+  ) {
+    return new CopilotKitLowLevelError({
+      error: error instanceof Error ? error : new Error(String(error)),
+      url: "streaming connection",
+      message:
+        "Network error occurred during streaming. Please check your connection and try again.",
+    });
+  }
+
+  // Handle abort/cancellation errors (these are usually normal)
+  if (
+    error?.message?.includes("aborted") ||
+    error?.message?.includes("canceled") ||
+    error?.message?.includes("signal is aborted")
+  ) {
+    return new CopilotKitError({
+      message: "Request was cancelled",
+      code: CopilotKitErrorCode.UNKNOWN,
+    });
+  }
+
+  // Default: convert unknown streaming errors
+  return new CopilotKitError({
+    message: `Streaming error: ${error?.message || String(error)}`,
+    code: CopilotKitErrorCode.UNKNOWN,
+  });
+}