@copilotkit/runtime 1.9.2-next.8 → 1.9.2-next.9

package/src/lib/error-messages.ts

@@ -0,0 +1,200 @@
+/**
+ * Error message configuration - Single source of truth for all error messages
+ *
+ * This centralized configuration system provides:
+ *
+ * 🎯 **Benefits:**
+ * - Single source of truth for all error messages
+ * - Easy content management without touching code
+ * - Consistent error messaging across the application
+ * - Ready for internationalization (i18n)
+ * - Type-safe configuration with TypeScript
+ * - Categorized errors for better handling
+ *
+ * 📝 **How to use:**
+ * 1. Add new error patterns to `errorPatterns` object
+ * 2. Use {context} placeholder for dynamic context injection
+ * 3. Specify category, severity, and actionable flags
+ * 4. Add fallback messages for error categories
+ *
+ * 🔧 **How to maintain:**
+ * - Content teams can update messages here without touching logic
+ * - Developers add new error patterns as needed
+ * - Use categories to group similar errors
+ * - Mark errors as actionable if users can fix them
+ *
+ * 🌍 **Future i18n support:**
+ * - Replace `message` string with `messages: { en: "...", es: "..." }`
+ * - Add locale parameter to helper functions
+ *
+ * @example
+ * ```typescript
+ * // Adding a new error pattern:
+ * "CUSTOM_ERROR": {
+ *   message: "Custom error occurred in {context}. Please try again.",
+ *   category: "unknown",
+ *   severity: "error",
+ *   actionable: true
+ * }
+ * ```
+ */
+
+export interface ErrorPatternConfig {
+  message: string;
+  category: "network" | "connection" | "authentication" | "validation" | "unknown";
+  severity: "error" | "warning" | "info";
+  actionable: boolean;
+}
+
+export interface ErrorConfig {
+  errorPatterns: Record<string, ErrorPatternConfig>;
+  fallbacks: Record<string, string>;
+  contextTemplates: Record<string, string>;
+}
+
+export const errorConfig: ErrorConfig = {
+  errorPatterns: {
+    ECONNREFUSED: {
+      message:
+        "Connection refused - the agent service is not running or not accessible at the specified address. Please check that your agent is started and listening on the correct port.",
+      category: "network",
+      severity: "error",
+      actionable: true,
+    },
+    ENOTFOUND: {
+      message:
+        "Host not found - the agent service URL appears to be incorrect or the service is not accessible. Please verify the agent endpoint URL.",
+      category: "network",
+      severity: "error",
+      actionable: true,
+    },
+    ETIMEDOUT: {
+      message:
+        "Connection timeout - the agent service is taking too long to respond. This could indicate network issues or an overloaded agent service.",
+      category: "network",
+      severity: "warning",
+      actionable: true,
+    },
+    terminated: {
+      message:
+        "Agent {context} was unexpectedly terminated. This often indicates an error in the agent service (e.g., authentication failures, missing environment variables, or agent crashes). Check the agent logs for the root cause.",
+      category: "connection",
+      severity: "error",
+      actionable: true,
+    },
+    UND_ERR_SOCKET: {
+      message:
+        "Socket connection was closed unexpectedly. This typically indicates the agent service encountered an error and shut down the connection. Check the agent logs for the underlying cause.",
+      category: "connection",
+      severity: "error",
+      actionable: true,
+    },
+    other_side_closed: {
+      message:
+        "The agent service closed the connection unexpectedly. This usually indicates an error in the agent service. Check the agent logs for more details.",
+      category: "connection",
+      severity: "error",
+      actionable: true,
+    },
+    fetch_failed: {
+      message:
+        "Failed to connect to the agent service. Please verify the agent is running and the endpoint URL is correct.",
+      category: "network",
+      severity: "error",
+      actionable: true,
+    },
+    // Authentication patterns
+    "401": {
+      message:
+        "Authentication failed. Please check your API keys and ensure they are correctly configured.",
+      category: "authentication",
+      severity: "error",
+      actionable: true,
+    },
+    "api key": {
+      message:
+        "API key error detected. Please verify your API key is correct and has the necessary permissions.",
+      category: "authentication",
+      severity: "error",
+      actionable: true,
+    },
+    unauthorized: {
+      message: "Unauthorized access. Please check your authentication credentials.",
+      category: "authentication",
+      severity: "error",
+      actionable: true,
+    },
+    // Python-specific error patterns
+    AuthenticationError: {
+      message:
+        "OpenAI authentication failed. Please check your OPENAI_API_KEY environment variable or API key configuration.",
+      category: "authentication",
+      severity: "error",
+      actionable: true,
+    },
+    "Incorrect API key provided": {
+      message:
+        "OpenAI API key is invalid. Please verify your OPENAI_API_KEY is correct and active.",
+      category: "authentication",
+      severity: "error",
+      actionable: true,
+    },
+    RateLimitError: {
+      message:
+        "OpenAI rate limit exceeded. Please wait a moment and try again, or check your OpenAI usage limits.",
+      category: "network",
+      severity: "warning",
+      actionable: true,
+    },
+    InvalidRequestError: {
+      message:
+        "Invalid request to OpenAI API. Please check your request parameters and model configuration.",
+      category: "validation",
+      severity: "error",
+      actionable: true,
+    },
+    PermissionDeniedError: {
+      message:
+        "Permission denied for OpenAI API. Please check your API key permissions and billing status.",
+      category: "authentication",
+      severity: "error",
+      actionable: true,
+    },
+    NotFoundError: {
+      message: "OpenAI resource not found. Please check your model name and availability.",
+      category: "validation",
+      severity: "error",
+      actionable: true,
+    },
+  },
+  fallbacks: {
+    network:
+      "A network error occurred while connecting to the agent service. Please check your connection and ensure the agent service is running.",
+    connection:
+      "The connection to the agent service was lost unexpectedly. This may indicate an issue with the agent service.",
+    authentication: "Authentication failed. Please check your API keys and credentials.",
+    validation: "Invalid input or configuration. Please check your parameters and try again.",
+    unknown: "An unexpected error occurred. Please check the logs for more details.",
+    default: "An unexpected error occurred. Please check the logs for more details.",
+  },
+  contextTemplates: {
+    connection: "connection",
+    event_streaming_connection: "event streaming connection",
+    agent_streaming_connection: "agent streaming connection",
+    langgraph_agent_connection: "LangGraph agent connection",
+  },
+};
+
+/**
+ * Helper function to get error pattern configuration by key
+ */
+export function getErrorPattern(key: string): ErrorPatternConfig | undefined {
+  return errorConfig.errorPatterns[key];
+}
+
+/**
+ * Helper function to get fallback message by category
+ */
+export function getFallbackMessage(category: string): string {
+  return errorConfig.fallbacks[category] || errorConfig.fallbacks.default;
+}

package/src/lib/integrations/shared.ts

@@ -10,6 +10,7 @@ import { createYoga } from "graphql-yoga";
 import telemetry from "../telemetry-client";
 import { StateResolver } from "../../graphql/resolvers/state.resolver";
 import * as packageJson from "../../../package.json";
+import { CopilotKitError, CopilotKitErrorCode } from "@copilotkit/shared";
 
 const logger = createLogger();
 
@@ -79,6 +80,9 @@ export type CommonConfig = {
   schema: ReturnType<typeof buildSchema>;
   plugins: Parameters<typeof createYoga>[0]["plugins"];
   context: (ctx: YogaInitialContext) => Promise<Partial<GraphQLContext>>;
+  maskedErrors: {
+    maskError: (error: any, message: string, isDev?: boolean) => any;
+  };
 };
 
 export function getCommonConfig(options: CreateCopilotRuntimeServerOptions): CommonConfig {
@@ -108,11 +112,50 @@ export function getCommonConfig(options: CreateCopilotRuntimeServerOptions): Com
     },
   });
 
+  // User error codes that should not be logged as server errors
+  const userErrorCodes = [
+    CopilotKitErrorCode.AGENT_NOT_FOUND,
+    CopilotKitErrorCode.API_NOT_FOUND,
+    CopilotKitErrorCode.REMOTE_ENDPOINT_NOT_FOUND,
+    CopilotKitErrorCode.CONFIGURATION_ERROR,
+    CopilotKitErrorCode.MISSING_PUBLIC_API_KEY_ERROR,
+  ];
+
   return {
     logging: createLogger({ component: "Yoga GraphQL", level: logLevel }),
     schema: buildSchema(),
     plugins: [useDeferStream(), addCustomHeaderPlugin],
     context: (ctx: YogaInitialContext): Promise<Partial<GraphQLContext>> =>
       createContext(ctx, options, contextLogger, options.properties),
+    // Suppress logging for user configuration errors
+    maskedErrors: {
+      maskError: (error: any, message: string, isDev?: boolean) => {
+        // Check if this is a user configuration error (could be wrapped in GraphQLError)
+        const originalError = error.originalError || error;
+        const extensions = error.extensions;
+        const errorCode = extensions?.code;
+
+        // Suppress logging for user errors based on error code
+        if (errorCode && userErrorCodes.includes(errorCode)) {
+          // Log user configuration errors at debug level instead
+          console.debug("User configuration error:", error.message);
+          return error;
+        }
+
+        // Check if the original error is a user error
+        if (
+          originalError instanceof CopilotKitError &&
+          userErrorCodes.includes(originalError.code)
+        ) {
+          // Log user configuration errors at debug level instead
+          console.debug("User configuration error:", error.message);
+          return error;
+        }
+
+        // For application errors, log normally and mask if needed
+        console.error("Application error:", error);
+        return error;
+      },
+    },
   };
 }

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

@@ -28,6 +28,7 @@ import {
   CopilotTraceHandler,
   CopilotTraceEvent,
   CopilotRequestContext,
+  ensureStructuredError,
 } from "@copilotkit/shared";
 import {
   CopilotServiceAdapter,
@@ -65,7 +66,7 @@ import { ExtensionsInput } from "../../graphql/inputs/extensions.input";
 import { ExtensionsResponse } from "../../graphql/types/extensions-response.type";
 import { LoadAgentStateResponse } from "../../graphql/types/load-agent-state-response.type";
 import { Client as LangGraphClient } from "@langchain/langgraph-sdk";
-import { langchainMessagesToCopilotKit } from "./remote-lg-action";
+import { langchainMessagesToCopilotKit, isUserConfigurationError } from "./remote-lg-action";
 import { MetaEventInput } from "../../graphql/inputs/meta-event.input";
 import {
   CopilotObservabilityConfig,
@@ -89,6 +90,8 @@ import { LangGraphAgent } from "./langgraph/langgraph-agent";
 type CreateMCPClientFunction = (config: MCPEndpointConfig) => Promise<MCPClient>;
 // --- MCP Imports ---
 
+import { generateHelpfulErrorMessage } from "../streaming";
+
 export interface CopilotRuntimeRequest {
   serviceAdapter: CopilotServiceAdapter;
   messages: MessageInput[];
@@ -746,9 +749,10 @@ please use an LLM adapter instead.`,
       if (error instanceof CopilotKitError) {
         structuredError = error;
       } else {
-        // Convert non-CopilotKitErrors to structured errors
-        console.error("Error getting response:", error);
-        structuredError = this.convertStreamingErrorToStructured(error);
+        // Convert non-CopilotKitErrors to structured errors, but preserve already structured ones
+        structuredError = ensureStructuredError(error, (err) =>
+          this.convertStreamingErrorToStructured(err),
+        );
       }
 
       // Trace the error
@@ -948,10 +952,24 @@ please use an LLM adapter instead.`,
           if (response.status === 404) {
             throw new CopilotKitApiDiscoveryError({ url: fetchUrl });
           }
+
+          // Extract semantic error information from response body
+          let errorMessage = `HTTP ${response.status} error`;
+          try {
+            const errorBody = await response.text();
+            const parsedError = JSON.parse(errorBody);
+            if (parsedError.error && typeof parsedError.error === "string") {
+              errorMessage = parsedError.error;
+            }
+          } catch {
+            // If parsing fails, fall back to generic message
+          }
+
           throw new ResolvedCopilotKitError({
             status: response.status,
             url: fetchUrl,
             isRemoteEndpoint: true,
+            message: errorMessage,
           });
         }
 
@@ -992,7 +1010,20 @@ please use an LLM adapter instead.`,
     let state: any = {};
     try {
       state = (await client.threads.getState(threadId)).values as any;
-    } catch (error) {}
+    } catch (error) {
+      // All errors from agent state loading are user configuration issues
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
+      // Log user configuration errors at debug level to reduce noise
+      console.debug(`Agent '${agentName}' configuration issue: ${errorMessage}`);
+
+      // Throw a configuration error - all agent state loading failures are user setup issues
+      throw new ResolvedCopilotKitError({
+        status: 400,
+        message: `Agent '${agentName}' failed to execute: ${errorMessage}`,
+        code: CopilotKitErrorCode.CONFIGURATION_ERROR,
+      });
+    }
 
     if (Object.keys(state).length === 0) {
       return {
@@ -1193,8 +1224,6 @@ please use an LLM adapter instead.`,
         from(stream).subscribe({
           next: (event) => eventStream$.next(event),
           error: async (err) => {
-            console.error("Error in stream", err);
-
             // Log error with observability if enabled
             if (this.observability?.enabled && publicApiKey) {
               try {
@@ -1216,8 +1245,10 @@ please use an LLM adapter instead.`,
               }
             }
 
-            // Convert network termination errors to structured errors
-            const structuredError = this.convertStreamingErrorToStructured(err);
+            // Preserve structured CopilotKit errors, only convert unstructured errors
+            const structuredError = ensureStructuredError(err, (error) =>
+              this.convertStreamingErrorToStructured(error),
+            );
 
             // Trace streaming errors
             await this.trace(
@@ -1325,12 +1356,9 @@ please use an LLM adapter instead.`,
       }
 
       // Ensure error is structured
-      let structuredError: CopilotKitError;
-      if (error instanceof CopilotKitError) {
-        structuredError = error;
-      } else {
-        structuredError = this.convertStreamingErrorToStructured(error);
-      }
+      const structuredError = ensureStructuredError(error, (err) =>
+        this.convertStreamingErrorToStructured(err),
+      );
 
       // Trace the agent error
       await this.trace(
@@ -1477,50 +1505,30 @@ please use an LLM adapter instead.`,
   }
 
   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,
-      });
-    }
+    // Determine a more helpful error message based on context
+    let helpfulMessage = generateHelpfulErrorMessage(error, "agent streaming connection");
 
-    // Handle other network-related errors
+    // For network-related errors, use CopilotKitLowLevelError to preserve the original error
     if (
       error?.message?.includes("fetch failed") ||
       error?.message?.includes("ECONNREFUSED") ||
       error?.message?.includes("ENOTFOUND") ||
-      error?.message?.includes("ETIMEDOUT")
+      error?.message?.includes("ETIMEDOUT") ||
+      error?.message?.includes("terminated") ||
+      error?.cause?.code === "UND_ERR_SOCKET" ||
+      error?.message?.includes("other side closed") ||
+      error?.code === "UND_ERR_SOCKET"
     ) {
       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,
+        message: helpfulMessage,
       });
     }
 
-    // Default: convert unknown streaming errors
+    // For all other errors, preserve the raw error in a basic CopilotKitError
     return new CopilotKitError({
-      message: `Agent streaming error: ${error?.message || String(error)}`,
+      message: helpfulMessage,
       code: CopilotKitErrorCode.UNKNOWN,
     });
   }
@@ -1533,11 +1541,11 @@ please use an LLM adapter instead.`,
   ): Promise<void> {
     if (!this.onTrace) return;
 
+    // Just check if publicApiKey is defined (regardless of validity)
     if (!publicApiKey) {
       if (!this.hasWarnedAboutTracing) {
         console.warn(
-          "CopilotKit: onTrace handler provided but requires publicApiKey for tracing to work. " +
-            "This is a CopilotKit Cloud feature. See: https://docs.copilotkit.ai/cloud",
+          "CopilotKit: onTrace handler provided but requires publicApiKey to be defined for tracing to work.",
         );
         this.hasWarnedAboutTracing = true;
       }

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

@@ -22,6 +22,9 @@ import { parseJson, tryMap } from "@copilotkit/shared";
 import { ActionInput } from "../../graphql/inputs/action.input";
 import { fetchWithRetry } from "./retry-utils";
 
+// Import the utility function from remote-lg-action
+import { isUserConfigurationError } from "./remote-lg-action";
+
 export function constructLGCRemoteAction({
   endpoint,
   graphqlContext,
@@ -93,11 +96,33 @@ export function constructLGCRemoteAction({
         writeJsonLineResponseToEventStream(response, eventSource.eventStream$);
         return eventSource.processLangGraphEvents();
       } catch (error) {
+        // Preserve structured CopilotKit errors with semantic information
+        if (error instanceof CopilotKitError || error instanceof CopilotKitLowLevelError) {
+          // Distinguish between user errors and system errors for logging
+          if (isUserConfigurationError(error)) {
+            logger.debug(
+              { url: endpoint.deploymentUrl, error: error.message, code: error.code },
+              "User configuration error in LangGraph Platform agent",
+            );
+          } else {
+            logger.error(
+              { url: endpoint.deploymentUrl, error: error.message, type: error.constructor.name },
+              "LangGraph Platform agent error",
+            );
+          }
+          throw error; // Re-throw the structured error to preserve semantic information
+        }
+
+        // For other errors, log and wrap them
         logger.error(
           { url: endpoint.deploymentUrl, status: 500, body: error.message },
           "Failed to execute LangGraph Platform agent",
         );
-        throw new Error("Failed to execute LangGraph Platform agent");
+        throw new CopilotKitLowLevelError({
+          error: error instanceof Error ? error : new Error(String(error)),
+          url: endpoint.deploymentUrl,
+          message: "Failed to execute LangGraph Platform agent",
+        });
       }
     },
   }));
@@ -180,7 +205,7 @@ export function constructRemoteActions({
         logger.debug({ actionName: action.name, result }, "Executed remote action");
         return result;
       } catch (error) {
-        if (error instanceof CopilotKitError) {
+        if (error instanceof CopilotKitError || error instanceof CopilotKitLowLevelError) {
           throw error;
         }
         throw new CopilotKitLowLevelError({ error, url: fetchUrl });
@@ -275,7 +300,7 @@ export function constructRemoteActions({
               throw new Error("Unsupported agent type");
             }
           } catch (error) {
-            if (error instanceof CopilotKitError) {
+            if (error instanceof CopilotKitError || error instanceof CopilotKitLowLevelError) {
               throw error;
             }
             throw new CopilotKitLowLevelError({ error, url: fetchUrl });

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

@@ -19,9 +19,28 @@ import { CustomEventNames, LangGraphEventTypes } from "../../agents/langgraph/ev
 import telemetry from "../telemetry-client";
 import { MetaEventInput } from "../../graphql/inputs/meta-event.input";
 import { MetaEventName } from "../../graphql/types/meta-events.type";
-import { parseJson, CopilotKitMisuseError } from "@copilotkit/shared";
+import {
+  parseJson,
+  CopilotKitMisuseError,
+  CopilotKitLowLevelError,
+  CopilotKitError,
+} from "@copilotkit/shared";
 import { RemoveMessage } from "@langchain/core/messages";
 import { RETRY_CONFIG, isRetryableError, sleep, calculateDelay } from "./retry-utils";
+import { generateHelpfulErrorMessage } from "../streaming";
+
+// Utility to determine if an error is a user configuration issue vs system error
+export function isUserConfigurationError(error: any): boolean {
+  return (
+    (error instanceof CopilotKitError || error instanceof CopilotKitLowLevelError) &&
+    (error.code === "NETWORK_ERROR" ||
+      error.code === "AUTHENTICATION_ERROR" ||
+      error.statusCode === 401 ||
+      error.statusCode === 403 ||
+      error.message?.toLowerCase().includes("authentication") ||
+      error.message?.toLowerCase().includes("api key"))
+  );
+}
 
 type State = Record<string, any>;
 
@@ -128,6 +147,15 @@ export async function execute(args: ExecutionArgs): Promise<ReadableStream<Uint8
             See more: https://docs.copilotkit.ai/troubleshooting/common-issues`,
         });
       } else {
+        // Preserve already structured CopilotKit errors with semantic information
+        if (
+          lastError instanceof CopilotKitError ||
+          lastError instanceof CopilotKitLowLevelError ||
+          (lastError instanceof Error && lastError.name && lastError.name.includes("CopilotKit"))
+        ) {
+          throw lastError; // Re-throw to preserve semantic information and visibility settings
+        }
+
         throw new CopilotKitMisuseError({
           message: `
             The LangGraph client threw unhandled error ${lastError}.
@@ -341,7 +369,43 @@ async function streamEvents(controller: ReadableStreamDefaultController, args: E
       if (!["events", "values", "error", "updates"].includes(streamResponseChunk.event)) continue;
 
       if (streamResponseChunk.event === "error") {
-        throw new Error(`Error event thrown: ${streamResponseChunk.data.message}`);
+        const errorData = streamResponseChunk.data;
+
+        // Check if this is a structured error from our Python agent
+        if (errorData && typeof errorData === "object" && "error_details" in errorData) {
+          const errorDetails = (errorData as any).error_details;
+
+          // Create a structured error with preserved semantic information
+          const preservedError = new CopilotKitLowLevelError({
+            error: new Error(errorDetails.message),
+            url: "langgraph platform agent",
+            message: `${errorDetails.type}: ${errorDetails.message}`,
+          });
+
+          // Add additional error context
+          if (errorDetails.status_code) {
+            (preservedError as any).statusCode = errorDetails.status_code;
+          }
+          if (errorDetails.response_data) {
+            (preservedError as any).responseData = errorDetails.response_data;
+          }
+          (preservedError as any).agentName = errorDetails.agent_name;
+          (preservedError as any).originalErrorType = errorDetails.type;
+
+          throw preservedError;
+        }
+
+        // Fallback for generic error messages
+        const helpfulMessage = generateHelpfulErrorMessage(
+          new Error(errorData.message),
+          "LangGraph Platform agent",
+        );
+
+        throw new CopilotKitLowLevelError({
+          error: new Error(errorData.message),
+          url: "langgraph platform agent",
+          message: helpfulMessage,
+        });
       }
 
       // Force event type, as data is not properly defined on the LG side.
@@ -507,11 +571,29 @@ async function streamEvents(controller: ReadableStreamDefaultController, args: E
 
     return Promise.resolve();
   } catch (e) {
-    logger.error(e);
+    // Distinguish between user errors and system errors for logging
+    if (isUserConfigurationError(e)) {
+      // Log user errors at debug level to reduce noise
+      logger.debug({ error: e.message, code: e.code }, "User configuration error");
+    } else {
+      // Log actual system errors at error level
+      logger.error(e);
+    }
+
     telemetry.capture("oss.runtime.agent_execution_stream_errored", {
       ...streamInfo,
       error: e.message,
     });
+
+    // Re-throw CopilotKit errors so they can be handled properly at higher levels
+    if (
+      e instanceof CopilotKitError ||
+      e instanceof CopilotKitLowLevelError ||
+      (e instanceof Error && e.name && e.name.includes("CopilotKit"))
+    ) {
+      throw e;
+    }
+
     return Promise.resolve();
   }
 }