@copilotkit/runtime 1.9.2-next.8 → 1.9.2

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

@@ -54,7 +54,11 @@ 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";
+import {
+  CopilotKitError,
+  CopilotKitLowLevelError,
+  isStructuredCopilotKitError,
+} from "@copilotkit/shared";
 
 const invokeGuardrails = async ({
   baseUrl,
@@ -188,8 +192,7 @@ export class CopilotResolver {
       if (!copilotCloudPublicApiKey) {
         logger.error("Public API key not found in headers");
 
-        // Trace the validation error for debugging visibility
-        await copilotRuntime.traceGraphQLError(
+        await copilotRuntime.errorGraphQLError(
           {
             message: "X-CopilotCloud-Public-API-Key header is required",
             code: "MISSING_PUBLIC_API_KEY",
@@ -235,6 +238,40 @@ export class CopilotResolver {
     }
 
     logger.debug("Processing");
+    let runtimeResponse;
+    try {
+      runtimeResponse = await copilotRuntime.processRuntimeRequest({
+        serviceAdapter,
+        messages: data.messages,
+        actions: data.frontend.actions.filter(
+          (action) => action.available !== ActionInputAvailability.disabled,
+        ),
+        threadId: data.threadId,
+        runId: data.runId,
+        publicApiKey: copilotCloudPublicApiKey,
+        outputMessagesPromise,
+        graphqlContext: ctx,
+        forwardedParameters: data.forwardedParameters,
+        agentSession: data.agentSession,
+        agentStates: data.agentStates,
+        url: data.frontend.url,
+        extensions: data.extensions,
+        metaEvents: data.metaEvents,
+      });
+    } catch (error) {
+      // Catch structured CopilotKit errors at the main mutation level and re-throw as GraphQL errors
+      if (isStructuredCopilotKitError(error) || (error as any)?.extensions?.visibility) {
+        throw new GraphQLError(error.message || "Agent error occurred", {
+          extensions: {
+            ...(error as any).extensions,
+            code: (error as any).code || (error as any).extensions?.code || "AGENT_ERROR",
+            originalError: error,
+          },
+        });
+      }
+      throw error; // Re-throw non-CopilotKit errors as-is
+    }
+
     const {
       eventSource,
       threadId = randomId(),
@@ -242,24 +279,7 @@ export class CopilotResolver {
       serverSideActions,
       actionInputsWithoutAgents,
       extensions,
-    } = await copilotRuntime.processRuntimeRequest({
-      serviceAdapter,
-      messages: data.messages,
-      actions: data.frontend.actions.filter(
-        (action) => action.available !== ActionInputAvailability.disabled,
-      ),
-      threadId: data.threadId,
-      runId: data.runId,
-      publicApiKey: copilotCloudPublicApiKey,
-      outputMessagesPromise,
-      graphqlContext: ctx,
-      forwardedParameters: data.forwardedParameters,
-      agentSession: data.agentSession,
-      agentStates: data.agentStates,
-      url: data.frontend.url,
-      extensions: data.extensions,
-      metaEvents: data.metaEvents,
-    });
+    } = runtimeResponse;
 
     logger.debug("Event source created, creating response");
     // run and process the event stream
@@ -357,12 +377,21 @@ export class CopilotResolver {
             }
           },
           error: (err) => {
-            logger.error({ err }, "Error in meta events stream");
-            responseStatus$.next(
-              new UnknownErrorResponse({
-                description: `An unknown error has occurred in the event stream`,
-              }),
-            );
+            // For structured CopilotKit errors, set proper error response status
+            if (err?.name?.includes("CopilotKit") || err?.extensions?.visibility) {
+              responseStatus$.next(
+                new UnknownErrorResponse({
+                  description: err.message || "Agent error occurred",
+                }),
+              );
+            } else {
+              responseStatus$.next(
+                new UnknownErrorResponse({
+                  description: `An unknown error has occurred in the event stream`,
+                }),
+              );
+            }
+
             eventStreamSubscription?.unsubscribe();
             stop();
           },
@@ -444,20 +473,20 @@ export class CopilotResolver {
                 // create a sub stream that contains the message content
                 const textMessageContentStream = eventStream.pipe(
                   // skip until this message start event
-                  skipWhile((e) => e !== event),
+                  skipWhile((e: RuntimeEvent) => e !== event),
                   // take until the message end event
                   takeWhile(
-                    (e) =>
+                    (e: RuntimeEvent) =>
                       !(
                         e.type === RuntimeEventTypes.TextMessageEnd &&
-                        e.messageId == event.messageId
+                        (e as any).messageId == event.messageId
                       ),
                   ),
                   // filter out any other message events or message ids
                   filter(
-                    (e) =>
+                    (e: RuntimeEvent) =>
                       e.type == RuntimeEventTypes.TextMessageContent &&
-                      e.messageId == event.messageId,
+                      (e as any).messageId == event.messageId,
                   ),
                 );
 
@@ -539,20 +568,20 @@ export class CopilotResolver {
               case RuntimeEventTypes.ActionExecutionStart:
                 logger.debug("Action execution start event received");
                 const actionExecutionArgumentStream = eventStream.pipe(
-                  skipWhile((e) => e !== event),
+                  skipWhile((e: RuntimeEvent) => e !== event),
                   // take until the action execution end event
                   takeWhile(
-                    (e) =>
+                    (e: RuntimeEvent) =>
                       !(
                         e.type === RuntimeEventTypes.ActionExecutionEnd &&
-                        e.actionExecutionId == event.actionExecutionId
+                        (e as any).actionExecutionId == event.actionExecutionId
                       ),
                   ),
                   // filter out any other action execution events or action execution ids
                   filter(
-                    (e) =>
+                    (e: RuntimeEvent) =>
                       e.type == RuntimeEventTypes.ActionExecutionArgs &&
-                      e.actionExecutionId == event.actionExecutionId,
+                      (e as any).actionExecutionId == event.actionExecutionId,
                   ),
                 );
                 const streamingArgumentsStatus = new Subject<typeof MessageStatusUnion>();
@@ -665,16 +694,30 @@ 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
+            // For structured CopilotKit errors, set proper error response status
             if (
               err instanceof CopilotKitError ||
-              (err instanceof Error && err.name && err.name.includes("CopilotKit"))
+              err instanceof CopilotKitLowLevelError ||
+              (err instanceof Error && err.name && err.name.includes("CopilotKit")) ||
+              err?.extensions?.visibility
             ) {
+              responseStatus$.next(
+                new UnknownErrorResponse({
+                  description: err.message || "Agent error occurred",
+                  // Include original error information for frontend to extract
+                  originalError: {
+                    code: err.code || err.extensions?.code,
+                    statusCode: err.statusCode || err.extensions?.statusCode,
+                    severity: err.severity || err.extensions?.severity,
+                    visibility: err.visibility || err.extensions?.visibility,
+                    originalErrorType: err.originalErrorType || err.extensions?.originalErrorType,
+                    extensions: err.extensions,
+                  },
+                }),
+              );
               eventStreamSubscription?.unsubscribe();
               rejectOutputMessagesPromise(err);
-              stopStreamingMessages(err); // Pass the error to stop the GraphQL stream with this error
+              stopStreamingMessages();
               return;
             }
 

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/__tests__/{copilot-runtime-trace.test.ts → copilot-runtime-error.test.ts}

@@ -1,8 +1,8 @@
-import { CopilotTraceEvent, CopilotRequestContext, CopilotTraceHandler } from "@copilotkit/shared";
+import { CopilotErrorEvent, CopilotRequestContext, CopilotErrorHandler } from "@copilotkit/shared";
 
-describe("CopilotRuntime onTrace types", () => {
+describe("CopilotRuntime onError types", () => {
   it("should have correct CopilotTraceEvent type structure", () => {
-    const traceEvent: CopilotTraceEvent = {
+    const errorEvent: CopilotErrorEvent = {
       type: "error",
       timestamp: Date.now(),
       context: {
@@ -18,10 +18,10 @@ describe("CopilotRuntime onTrace types", () => {
       error: new Error("Test error"),
     };
 
-    expect(traceEvent.type).toBe("error");
-    expect(traceEvent.timestamp).toBeGreaterThan(0);
-    expect(traceEvent.context.threadId).toBe("test-123");
-    expect(traceEvent.error).toBeInstanceOf(Error);
+    expect(errorEvent.type).toBe("error");
+    expect(errorEvent.timestamp).toBeGreaterThan(0);
+    expect(errorEvent.context.threadId).toBe("test-123");
+    expect(errorEvent.error).toBeInstanceOf(Error);
   });
 
   it("should have correct CopilotRequestContext type structure", () => {
@@ -76,8 +76,8 @@ describe("CopilotRuntime onTrace types", () => {
     expect(context.metadata?.testFlag).toBe(true);
   });
 
-  it("should support all trace event types", () => {
-    const eventTypes: CopilotTraceEvent["type"][] = [
+  it("should support all error event types", () => {
+    const eventTypes: CopilotErrorEvent["type"][] = [
       "error",
       "request",
       "response",
@@ -88,7 +88,7 @@ describe("CopilotRuntime onTrace types", () => {
     ];
 
     eventTypes.forEach((type) => {
-      const event: CopilotTraceEvent = {
+      const event: CopilotErrorEvent = {
         type,
         timestamp: Date.now(),
         context: {
@@ -108,37 +108,37 @@ describe("CopilotRuntime onTrace types", () => {
   });
 
   describe("publicApiKey gating logic", () => {
-    type ShouldTrace = (onTrace?: CopilotTraceHandler, publicApiKey?: string) => boolean;
+    type ShouldHandleError = (onError?: CopilotErrorHandler, publicApiKey?: string) => boolean;
 
-    const shouldTrace: ShouldTrace = (onTrace, publicApiKey) => {
-      return Boolean(onTrace && publicApiKey);
+    const shouldHandleError: ShouldHandleError = (onError, publicApiKey) => {
+      return Boolean(onError && publicApiKey);
     };
 
-    it("should return true when both onTrace and publicApiKey are provided", () => {
-      const onTrace = jest.fn();
-      const result = shouldTrace(onTrace, "valid-api-key");
+    it("should return true when both onError and publicApiKey are provided", () => {
+      const onError = jest.fn();
+      const result = shouldHandleError(onError, "valid-api-key");
       expect(result).toBe(true);
     });
 
-    it("should return false when onTrace is missing", () => {
-      const result = shouldTrace(undefined, "valid-api-key");
+    it("should return false when onError is missing", () => {
+      const result = shouldHandleError(undefined, "valid-api-key");
       expect(result).toBe(false);
     });
 
     it("should return false when publicApiKey is missing", () => {
-      const onTrace = jest.fn();
-      const result = shouldTrace(onTrace, undefined);
+      const onError = jest.fn();
+      const result = shouldHandleError(onError, undefined);
       expect(result).toBe(false);
     });
 
     it("should return false when publicApiKey is empty string", () => {
-      const onTrace = jest.fn();
-      const result = shouldTrace(onTrace, "");
+      const onError = jest.fn();
+      const result = shouldHandleError(onError, "");
       expect(result).toBe(false);
     });
 
     it("should return false when both are missing", () => {
-      const result = shouldTrace(undefined, undefined);
+      const result = shouldHandleError(undefined, undefined);
       expect(result).toBe(false);
     });
 
@@ -160,10 +160,10 @@ describe("CopilotRuntime onTrace types", () => {
       const nonCloudKey = extractPublicApiKey(mockHeaders, false);
       expect(nonCloudKey).toBe("test-key-123");
 
-      // Both should enable tracing when onTrace is present
-      const onTrace = jest.fn();
-      expect(shouldTrace(onTrace, cloudKey)).toBe(true);
-      expect(shouldTrace(onTrace, nonCloudKey)).toBe(true);
+      // Both should enable error handling when onError is present
+      const onError = jest.fn();
+      expect(shouldHandleError(onError, cloudKey)).toBe(true);
+      expect(shouldHandleError(onError, nonCloudKey)).toBe(true);
     });
   });
 });