@copilotkit/runtime 1.9.2-next.3 → 1.9.2-next.4

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

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

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

@@ -1,7 +1,7 @@
 import * as graphql from 'graphql';
 import * as pino from 'pino';
 import { YogaInitialContext, createYoga } from 'graphql-yoga';
-import { Parameter, Action } from '@copilotkit/shared';
+import { Parameter, Action, CopilotTraceHandler } from '@copilotkit/shared';
 import { b as CopilotServiceAdapter, A as ActionInput, d as AgentSessionInput, e as AgentStateInput, F as ForwardedParametersInput, E as ExtensionsInput, R as RemoteChainParameters, f as RuntimeEventSource, g as ExtensionsResponse } from './langserve-4a5c9217.js';
 import { M as MessageInput, a as Message } from './index-d4614f9b.js';
 import { CopilotCloudOptions } from './lib/cloud/index.js';
@@ -338,6 +338,24 @@ interface CopilotRuntimeConstructorParams<T extends Parameter[] | [] = []> {
      * ```
      */
     createMCPClient?: CreateMCPClientFunction;
+    /**
+     * Optional trace handler for comprehensive debugging and observability.
+     *
+     * **Requires publicApiKey**: Tracing only works when requests include a valid publicApiKey.
+     * This is a premium CopilotKit Cloud feature.
+     *
+     * @param traceEvent - Structured trace event with rich debugging context
+     *
+     * @example
+     * ```typescript
+     * const runtime = new CopilotRuntime({
+     *   onTrace: (traceEvent) => {
+     *     debugDashboard.capture(traceEvent);
+     *   }
+     * });
+     * ```
+     */
+    onTrace?: CopilotTraceHandler;
 }
 declare class CopilotRuntime<const T extends Parameter[] | [] = []> {
     actions: ActionsConfiguration<T>;
@@ -349,6 +367,8 @@ declare class CopilotRuntime<const T extends Parameter[] | [] = []> {
     private delegateAgentProcessingToServiceAdapter;
     private observability?;
     private availableAgents;
+    private onTrace?;
+    private hasWarnedAboutTracing;
     private readonly mcpServersConfig?;
     private mcpActionCache;
     private readonly createMCPClientImpl?;
@@ -361,6 +381,20 @@ declare class CopilotRuntime<const T extends Parameter[] | [] = []> {
     private getServerSideActions;
     private detectProvider;
     private convertStreamingErrorToStructured;
+    private trace;
+    /**
+     * Public method to trace GraphQL validation errors
+     * This allows the GraphQL resolver to send validation errors through the trace system
+     */
+    traceGraphQLError(error: {
+        message: string;
+        code: string;
+        type: string;
+    }, context: {
+        operation: string;
+        cloudConfigPresent: boolean;
+        guardrailsEnabled: boolean;
+    }): Promise<void>;
 }
 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.2-next.3",
+  "version": "1.9.2-next.4",
   "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.2-next.3"
+    "@copilotkit/shared": "1.9.2-next.4"
   },
   "peerDependencies": {
     "@ag-ui/client": ">=0.0.28",

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

@@ -174,15 +174,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");
       }
 

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);
+    });
+  });
+});

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

@@ -25,6 +25,9 @@ import {
   CopilotKitMisuseError,
   CopilotKitErrorCode,
   CopilotKitLowLevelError,
+  CopilotTraceHandler,
+  CopilotTraceEvent,
+  CopilotRequestContext,
 } from "@copilotkit/shared";
 import {
   CopilotServiceAdapter,
@@ -274,6 +277,25 @@ export interface CopilotRuntimeConstructorParams<T extends Parameter[] | [] = []
    * ```
    */
   createMCPClient?: CreateMCPClientFunction;
+
+  /**
+   * Optional trace handler for comprehensive debugging and observability.
+   *
+   * **Requires publicApiKey**: Tracing only works when requests include a valid publicApiKey.
+   * This is a premium CopilotKit Cloud feature.
+   *
+   * @param traceEvent - Structured trace event with rich debugging context
+   *
+   * @example
+   * ```typescript
+   * const runtime = new CopilotRuntime({
+   *   onTrace: (traceEvent) => {
+   *     debugDashboard.capture(traceEvent);
+   *   }
+   * });
+   * ```
+   */
+  onTrace?: CopilotTraceHandler;
 }
 
 export class CopilotRuntime<const T extends Parameter[] | [] = []> {
@@ -286,6 +308,8 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
   private delegateAgentProcessingToServiceAdapter: boolean;
   private observability?: CopilotObservabilityConfig;
   private availableAgents: Pick<AgentWithEndpoint, "name" | "id">[];
+  private onTrace?: CopilotTraceHandler;
+  private hasWarnedAboutTracing = false;
 
   // +++ MCP Properties +++
   private readonly mcpServersConfig?: MCPEndpointConfig[];
@@ -320,6 +344,7 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
       params?.delegateAgentProcessingToServiceAdapter || false;
     this.observability = params?.observability_c;
     this.agents = params?.agents ?? {};
+    this.onTrace = params?.onTrace;
     // +++ MCP Initialization +++
     this.mcpServersConfig = params?.mcpServers;
     this.createMCPClientImpl = params?.createMCPClient;
@@ -452,6 +477,32 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
     // For storing streamed chunks if progressive logging is enabled
     const streamedChunks: any[] = [];
 
+    // Trace request start
+    await this.trace(
+      "request",
+      {
+        threadId,
+        runId,
+        source: "runtime",
+        request: {
+          operation: "processRuntimeRequest",
+          method: "POST",
+          url: url,
+          startTime: requestStartTime,
+        },
+        agent: agentSession ? { name: agentSession.agentName } : undefined,
+        messages: {
+          input: rawMessages,
+          messageCount: rawMessages.length,
+        },
+        technical: {
+          environment: process.env.NODE_ENV,
+        },
+      },
+      undefined,
+      publicApiKey,
+    );
+
     try {
       if (
         Object.keys(this.agents).length &&
@@ -675,13 +726,43 @@ please use an LLM adapter instead.`,
         }
       }
 
+      let structuredError: CopilotKitError;
+
       if (error instanceof CopilotKitError) {
-        throw error;
+        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
-      console.error("Error getting response:", error);
-      const structuredError = this.convertStreamingErrorToStructured(error);
+      // Trace the error
+      await this.trace(
+        "error",
+        {
+          threadId,
+          runId,
+          source: "runtime",
+          request: {
+            operation: "processRuntimeRequest",
+            method: "POST",
+            url: url,
+            startTime: requestStartTime,
+          },
+          response: {
+            endTime: Date.now(),
+            latency: Date.now() - requestStartTime,
+          },
+          agent: agentSession ? { name: agentSession.agentName } : undefined,
+          technical: {
+            environment: process.env.NODE_ENV,
+            stackTrace: error instanceof Error ? error.stack : undefined,
+          },
+        },
+        structuredError,
+        publicApiKey,
+      );
+
       throw structuredError;
     }
   }
@@ -884,6 +965,33 @@ please use an LLM adapter instead.`,
     // for backwards compatibility, deal with the case when no threadId is provided
     const threadId = threadIdFromRequest ?? agentSession.threadId;
 
+    // Trace agent request start
+    await this.trace(
+      "agent_state",
+      {
+        threadId,
+        source: "agent",
+        request: {
+          operation: "processAgentRequest",
+          method: "POST",
+          startTime: requestStartTime,
+        },
+        agent: {
+          name: agentName,
+          nodeName: nodeName,
+        },
+        messages: {
+          input: rawMessages,
+          messageCount: rawMessages.length,
+        },
+        technical: {
+          environment: process.env.NODE_ENV,
+        },
+      },
+      undefined,
+      publicApiKey,
+    );
+
     const serverSideActions = await this.getServerSideActions(request);
 
     const messages = convertGqlInputToMessages(rawMessages);
@@ -1011,7 +1119,7 @@ please use an LLM adapter instead.`,
       eventSource.stream(async (eventStream$) => {
         from(stream).subscribe({
           next: (event) => eventStream$.next(event),
-          error: (err) => {
+          error: async (err) => {
             console.error("Error in stream", err);
 
             // Log error with observability if enabled
@@ -1037,6 +1145,35 @@ please use an LLM adapter instead.`,
 
             // Convert network termination errors to structured errors
             const structuredError = this.convertStreamingErrorToStructured(err);
+
+            // Trace streaming errors
+            await this.trace(
+              "error",
+              {
+                threadId,
+                source: "agent",
+                request: {
+                  operation: "processAgentRequest",
+                  method: "POST",
+                  startTime: requestStartTime,
+                },
+                response: {
+                  endTime: Date.now(),
+                  latency: Date.now() - requestStartTime,
+                },
+                agent: {
+                  name: agentName,
+                  nodeName: nodeName,
+                },
+                technical: {
+                  environment: process.env.NODE_ENV,
+                  stackTrace: err instanceof Error ? err.stack : undefined,
+                },
+              },
+              structuredError,
+              publicApiKey,
+            );
+
             eventStream$.error(structuredError);
             eventStream$.complete();
           },
@@ -1114,8 +1251,44 @@ please use an LLM adapter instead.`,
         }
       }
 
+      // Ensure error is structured
+      let structuredError: CopilotKitError;
+      if (error instanceof CopilotKitError) {
+        structuredError = error;
+      } else {
+        structuredError = this.convertStreamingErrorToStructured(error);
+      }
+
+      // Trace the agent error
+      await this.trace(
+        "error",
+        {
+          threadId,
+          source: "agent",
+          request: {
+            operation: "processAgentRequest",
+            method: "POST",
+            startTime: requestStartTime,
+          },
+          response: {
+            endTime: Date.now(),
+            latency: Date.now() - requestStartTime,
+          },
+          agent: {
+            name: agentName,
+            nodeName: nodeName,
+          },
+          technical: {
+            environment: process.env.NODE_ENV,
+            stackTrace: error instanceof Error ? error.stack : undefined,
+          },
+        },
+        structuredError,
+        publicApiKey,
+      );
+
       console.error("Error getting response:", error);
-      throw error;
+      throw structuredError;
     }
   }
 
@@ -1278,6 +1451,81 @@ please use an LLM adapter instead.`,
       code: CopilotKitErrorCode.UNKNOWN,
     });
   }
+
+  private async trace(
+    type: CopilotTraceEvent["type"],
+    context: CopilotRequestContext,
+    error?: any,
+    publicApiKey?: string,
+  ): Promise<void> {
+    if (!this.onTrace) return;
+
+    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",
+        );
+        this.hasWarnedAboutTracing = true;
+      }
+      return;
+    }
+
+    try {
+      const traceEvent: CopilotTraceEvent = {
+        type,
+        timestamp: Date.now(),
+        context,
+        ...(error && { error }),
+      };
+
+      await this.onTrace(traceEvent);
+    } catch (traceError) {
+      // Don't let trace errors break the main flow
+      console.error("Error in onTrace handler:", traceError);
+    }
+  }
+
+  /**
+   * Public method to trace GraphQL validation errors
+   * This allows the GraphQL resolver to send validation errors through the trace system
+   */
+  public async traceGraphQLError(
+    error: { message: string; code: string; type: string },
+    context: {
+      operation: string;
+      cloudConfigPresent: boolean;
+      guardrailsEnabled: boolean;
+    },
+  ): Promise<void> {
+    if (!this.onTrace) return;
+
+    try {
+      await this.onTrace({
+        type: "error",
+        timestamp: Date.now(),
+        context: {
+          source: "runtime",
+          request: {
+            operation: context.operation,
+            startTime: Date.now(),
+          },
+          technical: {
+            environment: process.env.NODE_ENV,
+          },
+          metadata: {
+            errorType: "GraphQLValidationError",
+            cloudConfigPresent: context.cloudConfigPresent,
+            guardrailsEnabled: context.guardrailsEnabled,
+          },
+        },
+        error,
+      });
+    } catch (traceError) {
+      // Don't let trace errors break the main flow
+      console.error("Error in onTrace handler:", traceError);
+    }
+  }
 }
 
 export function flattenToolCallsNoDuplicates(toolsByPriority: ActionInput[]): ActionInput[] {