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

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @copilotkit/runtime
 
+## 1.9.2-next.4
+
+### Patch Changes
+
+- 9169ad7: - feat: add onTrace handler for runtime and UI error/event tracking
+- 9169ad7: - feat: add onTrace handler for comprehensive debugging and observability - Add CopilotTraceEvent interfaces with rich debugging context, implement runtime-side tracing with publicApiKey gating, add UI-side error tracing, include comprehensive test coverage, and fix tsup build config to exclude test files
+  - fix: extract publicApiKey for all requests + trace GraphQL errors
+- Updated dependencies [9169ad7]
+- Updated dependencies [9169ad7]
+  - @copilotkit/shared@1.9.2-next.4
+
 ## 1.9.2-next.3
 
 ### Patch Changes

package/dist/{chunk-XDBXF3Q6.mjs → chunk-5FNEYAWH.mjs}

@@ -1,6 +1,6 @@
 import {
   LangGraphEventTypes
-} from "./chunk-GSYE3DGY.mjs";
+} from "./chunk-ZUF3A5TW.mjs";
 import {
   __name
 } from "./chunk-FHD4JECV.mjs";
@@ -138,4 +138,4 @@ export {
   CustomEventNames,
   LangGraphAgent
 };
-//# sourceMappingURL=chunk-XDBXF3Q6.mjs.map
+//# sourceMappingURL=chunk-5FNEYAWH.mjs.map

package/dist/{chunk-N24X5I3C.mjs → chunk-6W7TKZNY.mjs}

@@ -2,7 +2,7 @@ import {
   copilotRuntimeNodeHttpEndpoint,
   getRuntimeInstanceTelemetryInfo,
   telemetry_client_default
-} from "./chunk-GSYE3DGY.mjs";
+} from "./chunk-ZUF3A5TW.mjs";
 import {
   __name
 } from "./chunk-FHD4JECV.mjs";
@@ -22,4 +22,4 @@ __name(copilotRuntimeNodeExpressEndpoint, "copilotRuntimeNodeExpressEndpoint");
 export {
   copilotRuntimeNodeExpressEndpoint
 };
-//# sourceMappingURL=chunk-N24X5I3C.mjs.map
+//# sourceMappingURL=chunk-6W7TKZNY.mjs.map

package/dist/{chunk-MIPAKFI5.mjs → chunk-CJ44W4R2.mjs}

@@ -2,7 +2,7 @@ import {
   copilotRuntimeNodeHttpEndpoint,
   getRuntimeInstanceTelemetryInfo,
   telemetry_client_default
-} from "./chunk-GSYE3DGY.mjs";
+} from "./chunk-ZUF3A5TW.mjs";
 import {
   __name
 } from "./chunk-FHD4JECV.mjs";
@@ -22,4 +22,4 @@ __name(copilotRuntimeNestEndpoint, "copilotRuntimeNestEndpoint");
 export {
   copilotRuntimeNestEndpoint
 };
-//# sourceMappingURL=chunk-MIPAKFI5.mjs.map
+//# sourceMappingURL=chunk-CJ44W4R2.mjs.map

package/dist/{chunk-WFYPJXWX.mjs → chunk-NK2XARWT.mjs}

@@ -2,7 +2,7 @@ import {
   getCommonConfig,
   getRuntimeInstanceTelemetryInfo,
   telemetry_client_default
-} from "./chunk-GSYE3DGY.mjs";
+} from "./chunk-ZUF3A5TW.mjs";
 import {
   __name
 } from "./chunk-FHD4JECV.mjs";
@@ -77,4 +77,4 @@ export {
   config,
   copilotRuntimeNextJSPagesRouterEndpoint
 };
-//# sourceMappingURL=chunk-WFYPJXWX.mjs.map
+//# sourceMappingURL=chunk-NK2XARWT.mjs.map

package/dist/{chunk-GSYE3DGY.mjs → chunk-ZUF3A5TW.mjs}

@@ -40,7 +40,7 @@ var require_package = __commonJS({
       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",
@@ -3219,6 +3219,8 @@ var CopilotRuntime = class {
   delegateAgentProcessingToServiceAdapter;
   observability;
   availableAgents;
+  onTrace;
+  hasWarnedAboutTracing = false;
   // +++ MCP Properties +++
   mcpServersConfig;
   mcpActionCache = /* @__PURE__ */ new Map();
@@ -3243,6 +3245,7 @@ var CopilotRuntime = class {
     this.delegateAgentProcessingToServiceAdapter = (params == null ? void 0 : params.delegateAgentProcessingToServiceAdapter) || false;
     this.observability = params == null ? void 0 : params.observability_c;
     this.agents = (params == null ? void 0 : params.agents) ?? {};
+    this.onTrace = params == null ? void 0 : params.onTrace;
     this.mcpServersConfig = params == null ? void 0 : params.mcpServers;
     this.createMCPClientImpl = params == null ? void 0 : params.createMCPClient;
     if (this.mcpServersConfig && this.mcpServersConfig.length > 0 && !this.createMCPClientImpl) {
@@ -3321,6 +3324,27 @@ var CopilotRuntime = class {
     const eventSource = new RuntimeEventSource();
     const requestStartTime = Date.now();
     const streamedChunks = [];
+    await this.trace("request", {
+      threadId,
+      runId,
+      source: "runtime",
+      request: {
+        operation: "processRuntimeRequest",
+        method: "POST",
+        url,
+        startTime: requestStartTime
+      },
+      agent: agentSession ? {
+        name: agentSession.agentName
+      } : void 0,
+      messages: {
+        input: rawMessages,
+        messageCount: rawMessages.length
+      },
+      technical: {
+        environment: process.env.NODE_ENV
+      }
+    }, void 0, publicApiKey);
     try {
       if (Object.keys(this.agents).length && (agentSession == null ? void 0 : agentSession.agentName) && !this.delegateAgentProcessingToServiceAdapter) {
         this.agents = {
@@ -3490,11 +3514,35 @@ please use an LLM adapter instead.`
           console.error("Error logging LLM error:", logError);
         }
       }
+      let structuredError;
       if (error instanceof CopilotKitError5) {
-        throw error;
+        structuredError = error;
+      } else {
+        console.error("Error getting response:", error);
+        structuredError = this.convertStreamingErrorToStructured(error);
       }
-      console.error("Error getting response:", error);
-      const structuredError = this.convertStreamingErrorToStructured(error);
+      await this.trace("error", {
+        threadId,
+        runId,
+        source: "runtime",
+        request: {
+          operation: "processRuntimeRequest",
+          method: "POST",
+          url,
+          startTime: requestStartTime
+        },
+        response: {
+          endTime: Date.now(),
+          latency: Date.now() - requestStartTime
+        },
+        agent: agentSession ? {
+          name: agentSession.agentName
+        } : void 0,
+        technical: {
+          environment: process.env.NODE_ENV,
+          stackTrace: error instanceof Error ? error.stack : void 0
+        }
+      }, structuredError, publicApiKey);
       throw structuredError;
     }
   }
@@ -3679,6 +3727,26 @@ please use an LLM adapter instead.`
     const requestStartTime = Date.now();
     const streamedChunks = [];
     const threadId = threadIdFromRequest ?? agentSession.threadId;
+    await this.trace("agent_state", {
+      threadId,
+      source: "agent",
+      request: {
+        operation: "processAgentRequest",
+        method: "POST",
+        startTime: requestStartTime
+      },
+      agent: {
+        name: agentName,
+        nodeName
+      },
+      messages: {
+        input: rawMessages,
+        messageCount: rawMessages.length
+      },
+      technical: {
+        environment: process.env.NODE_ENV
+      }
+    }, void 0, publicApiKey);
     const serverSideActions = await this.getServerSideActions(request);
     const messages = convertGqlInputToMessages(rawMessages);
     const currentAgent = serverSideActions.find((action) => action.name === agentName && isRemoteAgentAction(action));
@@ -3774,7 +3842,7 @@ please use an LLM adapter instead.`
       eventSource.stream(async (eventStream$) => {
         from(stream).subscribe({
           next: (event) => eventStream$.next(event),
-          error: (err) => {
+          error: async (err) => {
             var _a2;
             console.error("Error in stream", err);
             if (((_a2 = this.observability) == null ? void 0 : _a2.enabled) && publicApiKey) {
@@ -3796,6 +3864,27 @@ please use an LLM adapter instead.`
               }
             }
             const structuredError = this.convertStreamingErrorToStructured(err);
+            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
+              },
+              technical: {
+                environment: process.env.NODE_ENV,
+                stackTrace: err instanceof Error ? err.stack : void 0
+              }
+            }, structuredError, publicApiKey);
             eventStream$.error(structuredError);
             eventStream$.complete();
           },
@@ -3863,8 +3952,35 @@ please use an LLM adapter instead.`
           console.error("Error logging agent error:", logError);
         }
       }
+      let structuredError;
+      if (error instanceof CopilotKitError5) {
+        structuredError = error;
+      } else {
+        structuredError = this.convertStreamingErrorToStructured(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
+        },
+        technical: {
+          environment: process.env.NODE_ENV,
+          stackTrace: error instanceof Error ? error.stack : void 0
+        }
+      }, structuredError, publicApiKey);
       console.error("Error getting response:", error);
-      throw error;
+      throw structuredError;
     }
   }
   async getServerSideActions(request) {
@@ -3984,6 +4100,62 @@ please use an LLM adapter instead.`
       code: CopilotKitErrorCode3.UNKNOWN
     });
   }
+  async trace(type, context, error, publicApiKey) {
+    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 = {
+        type,
+        timestamp: Date.now(),
+        context,
+        ...error && {
+          error
+        }
+      };
+      await this.onTrace(traceEvent);
+    } catch (traceError) {
+      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
+  */
+  async traceGraphQLError(error, context) {
+    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) {
+      console.error("Error in onTrace handler:", traceError);
+    }
+  }
 };
 __name(CopilotRuntime, "CopilotRuntime");
 function flattenToolCallsNoDuplicates(toolsByPriority) {
@@ -4539,7 +4711,7 @@ var CopilotResolver = class {
     };
   }
   async generateCopilotResponse(ctx, data, properties) {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e;
     telemetry_client_default.capture("oss.runtime.copilot_request_created", {
       "cloud.guardrails.enabled": ((_a = data.cloud) == null ? void 0 : _a.guardrails) !== void 0,
       requestType: data.metadata.requestType,
@@ -4570,23 +4742,32 @@ var CopilotResolver = class {
     const serviceAdapter = ctx._copilotkit.serviceAdapter;
     let copilotCloudPublicApiKey = null;
     let copilotCloudBaseUrl;
+    const publicApiKeyFromHeaders = ctx.request.headers.get("x-copilotcloud-public-api-key");
+    if (publicApiKeyFromHeaders) {
+      copilotCloudPublicApiKey = publicApiKeyFromHeaders;
+    }
     if (data.cloud) {
       logger2 = logger2.child({
         cloud: true
       });
       logger2.debug("Cloud configuration provided, checking for public API key in headers");
-      const key = ctx.request.headers.get("x-copilotcloud-public-api-key");
-      if (key) {
-        logger2.debug("Public API key found in headers");
-        copilotCloudPublicApiKey = key;
-      } else {
+      if (!copilotCloudPublicApiKey) {
         logger2.error("Public API key not found in headers");
+        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((_b = data.cloud) == null ? void 0 : _b.guardrails)
+        });
         throw new GraphQLError("X-CopilotCloud-Public-API-Key header is required");
       }
       if (process.env.COPILOT_CLOUD_BASE_URL) {
         copilotCloudBaseUrl = process.env.COPILOT_CLOUD_BASE_URL;
-      } else if ((_b = ctx._copilotkit.cloud) == null ? void 0 : _b.baseUrl) {
-        copilotCloudBaseUrl = (_c = ctx._copilotkit.cloud) == null ? void 0 : _c.baseUrl;
+      } else if ((_c = ctx._copilotkit.cloud) == null ? void 0 : _c.baseUrl) {
+        copilotCloudBaseUrl = (_d = ctx._copilotkit.cloud) == null ? void 0 : _d.baseUrl;
       } else {
         copilotCloudBaseUrl = "https://api.cloud.copilotkit.ai";
       }
@@ -4628,7 +4809,7 @@ var CopilotResolver = class {
     logger2.debug("Event source created, creating response");
     const eventStream = eventSource.processRuntimeEvents({
       serverSideActions,
-      guardrailsResult$: ((_d = data.cloud) == null ? void 0 : _d.guardrails) ? guardrailsResult$ : null,
+      guardrailsResult$: ((_e = data.cloud) == null ? void 0 : _e.guardrails) ? guardrailsResult$ : null,
       actionInputsWithoutAgents: actionInputsWithoutAgents.filter(
         // TODO-AGENTS: do not exclude ALL server side actions
         (action) => !serverSideActions.find((serverSideAction) => serverSideAction.name == action.name)
@@ -5325,4 +5506,4 @@ export {
   getCommonConfig,
   copilotRuntimeNodeHttpEndpoint
 };
-//# sourceMappingURL=chunk-GSYE3DGY.mjs.map
+//# sourceMappingURL=chunk-ZUF3A5TW.mjs.map