@copilotkit/runtime 1.9.2-next.1 → 1.9.2-next.11

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,
@@ -174,15 +178,34 @@ export class CopilotResolver {
     let copilotCloudPublicApiKey: string | null = null;
     let copilotCloudBaseUrl: string;
 
+    // Extract publicApiKey from headers for both cloud and non-cloud requests
+    // This enables onTrace functionality regardless of cloud configuration
+    const publicApiKeyFromHeaders = ctx.request.headers.get("x-copilotcloud-public-api-key");
+    if (publicApiKeyFromHeaders) {
+      copilotCloudPublicApiKey = publicApiKeyFromHeaders;
+    }
+
     if (data.cloud) {
       logger = logger.child({ cloud: true });
       logger.debug("Cloud configuration provided, checking for public API key in headers");
-      const key = ctx.request.headers.get("x-copilotcloud-public-api-key");
-      if (key) {
-        logger.debug("Public API key found in headers");
-        copilotCloudPublicApiKey = key;
-      } else {
+
+      if (!copilotCloudPublicApiKey) {
         logger.error("Public API key not found in headers");
+
+        // Trace the validation error for debugging visibility
+        await copilotRuntime.traceGraphQLError(
+          {
+            message: "X-CopilotCloud-Public-API-Key header is required",
+            code: "MISSING_PUBLIC_API_KEY",
+            type: "GraphQLError",
+          },
+          {
+            operation: "generateCopilotResponse",
+            cloudConfigPresent: Boolean(data.cloud),
+            guardrailsEnabled: Boolean(data.cloud?.guardrails),
+          },
+        );
+
         throw new GraphQLError("X-CopilotCloud-Public-API-Key header is required");
       }
 
@@ -216,6 +239,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(),
@@ -223,24 +280,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
@@ -338,12 +378,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();
           },
@@ -425,20 +474,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,
                   ),
                 );
 
@@ -520,20 +569,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>();
@@ -646,16 +695,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/graphql/resolvers/state.resolver.ts

@@ -10,9 +10,9 @@ import { CopilotKitAgentDiscoveryError } from "@copilotkit/shared";
 export class StateResolver {
   @Query(() => LoadAgentStateResponse)
   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) {
+    const agents = await ctx._copilotkit.runtime.getAllAgents(ctx);
+    const hasAgent = agents.some((agent) => agent.name === data.agentName);
+    if (!hasAgent) {
       throw new CopilotKitAgentDiscoveryError({
         agentName: data.agentName,
         availableAgents: agents.map((a) => ({ name: a.name, id: a.name })),

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

@@ -0,0 +1,169 @@
+import { CopilotTraceEvent, CopilotRequestContext, CopilotTraceHandler } from "@copilotkit/shared";
+
+describe("CopilotRuntime onTrace types", () => {
+  it("should have correct CopilotTraceEvent type structure", () => {
+    const traceEvent: CopilotTraceEvent = {
+      type: "error",
+      timestamp: Date.now(),
+      context: {
+        threadId: "test-123",
+        source: "runtime",
+        request: {
+          operation: "test-operation",
+          startTime: Date.now(),
+        },
+        technical: {},
+        metadata: {},
+      },
+      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);
+  });
+
+  it("should have correct CopilotRequestContext type structure", () => {
+    const context: CopilotRequestContext = {
+      threadId: "test-thread-456",
+      runId: "test-run-789",
+      source: "runtime",
+      request: {
+        operation: "processRuntimeRequest",
+        method: "POST",
+        url: "http://localhost:3000/api/copilotkit",
+        startTime: Date.now(),
+      },
+      response: {
+        status: 200,
+        endTime: Date.now(),
+        latency: 1200,
+      },
+      agent: {
+        name: "test-agent",
+        nodeName: "test-node",
+        state: { step: 1 },
+      },
+      messages: {
+        input: [],
+        output: [],
+        messageCount: 2,
+      },
+      technical: {
+        userAgent: "Mozilla/5.0...",
+        host: "localhost:3000",
+        environment: "test",
+        version: "1.0.0",
+        stackTrace: "Error: Test\n  at test.js:1:1",
+      },
+      performance: {
+        requestDuration: 1200,
+        streamingDuration: 800,
+        actionExecutionTime: 400,
+        memoryUsage: 45.2,
+      },
+      metadata: {
+        testFlag: true,
+        version: "1.0.0",
+      },
+    };
+
+    expect(context.threadId).toBe("test-thread-456");
+    expect(context.agent?.name).toBe("test-agent");
+    expect(context.messages?.messageCount).toBe(2);
+    expect(context.technical?.stackTrace).toContain("Error: Test");
+    expect(context.metadata?.testFlag).toBe(true);
+  });
+
+  it("should support all trace event types", () => {
+    const eventTypes: CopilotTraceEvent["type"][] = [
+      "error",
+      "request",
+      "response",
+      "agent_state",
+      "action",
+      "message",
+      "performance",
+    ];
+
+    eventTypes.forEach((type) => {
+      const event: CopilotTraceEvent = {
+        type,
+        timestamp: Date.now(),
+        context: {
+          threadId: `test-${type}`,
+          source: "runtime",
+          request: {
+            operation: "test",
+            startTime: Date.now(),
+          },
+          technical: {},
+          metadata: {},
+        },
+      };
+
+      expect(event.type).toBe(type);
+    });
+  });
+
+  describe("publicApiKey gating logic", () => {
+    type ShouldTrace = (onTrace?: CopilotTraceHandler, publicApiKey?: string) => boolean;
+
+    const shouldTrace: ShouldTrace = (onTrace, publicApiKey) => {
+      return Boolean(onTrace && publicApiKey);
+    };
+
+    it("should return true when both onTrace and publicApiKey are provided", () => {
+      const onTrace = jest.fn();
+      const result = shouldTrace(onTrace, "valid-api-key");
+      expect(result).toBe(true);
+    });
+
+    it("should return false when onTrace is missing", () => {
+      const result = shouldTrace(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);
+      expect(result).toBe(false);
+    });
+
+    it("should return false when publicApiKey is empty string", () => {
+      const onTrace = jest.fn();
+      const result = shouldTrace(onTrace, "");
+      expect(result).toBe(false);
+    });
+
+    it("should return false when both are missing", () => {
+      const result = shouldTrace(undefined, undefined);
+      expect(result).toBe(false);
+    });
+
+    it("should extract publicApiKey from headers for both cloud and non-cloud requests", () => {
+      // Test the logic we just fixed in the GraphQL resolver
+      const mockHeaders = new Map([["x-copilotcloud-public-api-key", "test-key-123"]]);
+
+      // Simulate header extraction logic
+      const extractPublicApiKey = (headers: Map<string, string>, hasCloudConfig: boolean) => {
+        const publicApiKeyFromHeaders = headers.get("x-copilotcloud-public-api-key");
+        return publicApiKeyFromHeaders || null;
+      };
+
+      // Should work for cloud requests
+      const cloudKey = extractPublicApiKey(mockHeaders, true);
+      expect(cloudKey).toBe("test-key-123");
+
+      // Should also work for non-cloud requests (this was the bug)
+      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);
+    });
+  });
+});