@copilotkit/runtime 1.9.2-next.16 → 1.9.2-next.18

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

@@ -1,6 +1,6 @@
 import {
   copilotRuntimeNodeHttpEndpoint
-} from "../../../chunk-7F4BIRQF.mjs";
+} from "../../../chunk-FW5UOGQ2.mjs";
 import "../../../chunk-SHBDMA63.mjs";
 import "../../../chunk-JTFQ5GIL.mjs";
 import "../../../chunk-XWBDEXDA.mjs";

package/dist/{shared-4164c674.d.ts → shared-41d4988d.d.ts}

@@ -2,7 +2,7 @@ import * as graphql from 'graphql';
 import * as createPinoLogger from 'pino';
 import createPinoLogger__default from 'pino';
 import { YogaInitialContext, createYoga } from 'graphql-yoga';
-import { Parameter, Action, CopilotTraceHandler } from '@copilotkit/shared';
+import { Parameter, Action, CopilotErrorHandler } 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-fc5cac89.js';
 import { M as MessageInput, a as Message } from './index-d4614f9b.js';
 import { CopilotCloudOptions } from './lib/cloud/index.js';
@@ -340,23 +340,23 @@ interface CopilotRuntimeConstructorParams<T extends Parameter[] | [] = []> {
      */
     createMCPClient?: CreateMCPClientFunction;
     /**
-     * Optional trace handler for comprehensive debugging and observability.
+     * Optional error handler for comprehensive debugging and observability.
      *
-     * **Requires publicApiKey**: Tracing only works when requests include a valid publicApiKey.
+     * **Requires publicApiKey**: Error handling only works when requests include a valid publicApiKey.
      * This is a premium CopilotKit Cloud feature.
      *
-     * @param traceEvent - Structured trace event with rich debugging context
+     * @param errorEvent - Structured error event with rich debugging context
      *
      * @example
      * ```typescript
      * const runtime = new CopilotRuntime({
-     *   onTrace: (traceEvent) => {
-     *     debugDashboard.capture(traceEvent);
+     *   onError: (errorEvent) => {
+     *     debugDashboard.capture(errorEvent);
      *   }
      * });
      * ```
      */
-    onTrace?: CopilotTraceHandler;
+    onError?: CopilotErrorHandler;
 }
 declare class CopilotRuntime<const T extends Parameter[] | [] = []> {
     actions: ActionsConfiguration<T>;
@@ -368,8 +368,8 @@ declare class CopilotRuntime<const T extends Parameter[] | [] = []> {
     private delegateAgentProcessingToServiceAdapter;
     private observability?;
     private availableAgents;
-    private onTrace?;
-    private hasWarnedAboutTracing;
+    private onError?;
+    private hasWarnedAboutError;
     private readonly mcpServersConfig?;
     private mcpActionCache;
     private readonly createMCPClientImpl?;
@@ -384,12 +384,12 @@ declare class CopilotRuntime<const T extends Parameter[] | [] = []> {
     private getServerSideActions;
     private detectProvider;
     private convertStreamingErrorToStructured;
-    private trace;
+    private error;
     /**
-     * Public method to trace GraphQL validation errors
-     * This allows the GraphQL resolver to send validation errors through the trace system
+     * Public method to handle GraphQL validation errors
+     * This allows the GraphQL resolver to send validation errors through the error system
      */
-    traceGraphQLError(error: {
+    errorGraphQLError(error: {
         message: string;
         code: string;
         type: string;

package/package.json

@@ -9,7 +9,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.9.2-next.16",
+  "version": "1.9.2-next.18",
   "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.16"
+    "@copilotkit/shared": "1.9.2-next.18"
   },
   "peerDependencies": {
     "@ag-ui/client": ">=0.0.28",

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

@@ -192,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",

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

package/src/lib/runtime/agui-action.ts

@@ -23,6 +23,7 @@ export function constructAGUIRemoteAction({
   agent,
   metaEvents,
   threadMetadata,
+  nodeName,
 }: {
   logger: Logger;
   messages: Message[];
@@ -30,6 +31,7 @@ export function constructAGUIRemoteAction({
   agent: AbstractAgent;
   metaEvents?: MetaEventInput[];
   threadMetadata?: Record<string, any>;
+  nodeName?: string;
 }) {
   const action = {
     name: agent.agentId,
@@ -72,6 +74,7 @@ export function constructAGUIRemoteAction({
       const forwardedProps = {
         ...(metaEvents?.length ? { command: { resume: metaEvents[0]?.response } } : {}),
         ...(threadMetadata ? { threadMetadata } : {}),
+        ...(nodeName ? { nodeName } : {}),
       };
 
       return agent.legacy_to_be_removed_runAgentBridged({

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

@@ -20,13 +20,12 @@ import {
   CopilotKitApiDiscoveryError,
   randomId,
   CopilotKitError,
-  CopilotKitRemoteEndpointDiscoveryError,
   CopilotKitAgentDiscoveryError,
   CopilotKitMisuseError,
   CopilotKitErrorCode,
   CopilotKitLowLevelError,
-  CopilotTraceHandler,
-  CopilotTraceEvent,
+  CopilotErrorHandler,
+  CopilotErrorEvent,
   CopilotRequestContext,
   ensureStructuredError,
 } from "@copilotkit/shared";
@@ -66,7 +65,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, isUserConfigurationError } from "./remote-lg-action";
+import { langchainMessagesToCopilotKit } from "./remote-lg-action";
 import { MetaEventInput } from "../../graphql/inputs/meta-event.input";
 import {
   CopilotObservabilityConfig,
@@ -283,23 +282,23 @@ export interface CopilotRuntimeConstructorParams<T extends Parameter[] | [] = []
   createMCPClient?: CreateMCPClientFunction;
 
   /**
-   * Optional trace handler for comprehensive debugging and observability.
+   * Optional error handler for comprehensive debugging and observability.
    *
-   * **Requires publicApiKey**: Tracing only works when requests include a valid publicApiKey.
+   * **Requires publicApiKey**: Error handling only works when requests include a valid publicApiKey.
    * This is a premium CopilotKit Cloud feature.
    *
-   * @param traceEvent - Structured trace event with rich debugging context
+   * @param errorEvent - Structured error event with rich debugging context
    *
    * @example
    * ```typescript
    * const runtime = new CopilotRuntime({
-   *   onTrace: (traceEvent) => {
-   *     debugDashboard.capture(traceEvent);
+   *   onError: (errorEvent) => {
+   *     debugDashboard.capture(errorEvent);
    *   }
    * });
    * ```
    */
-  onTrace?: CopilotTraceHandler;
+  onError?: CopilotErrorHandler;
 }
 
 export class CopilotRuntime<const T extends Parameter[] | [] = []> {
@@ -312,8 +311,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;
+  private onError?: CopilotErrorHandler;
+  private hasWarnedAboutError = false;
 
   // +++ MCP Properties +++
   private readonly mcpServersConfig?: MCPEndpointConfig[];
@@ -362,7 +361,7 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
       params?.delegateAgentProcessingToServiceAdapter || false;
     this.observability = params?.observability_c;
     this.agents = params?.agents ?? {};
-    this.onTrace = params?.onTrace;
+    this.onError = params?.onError;
     // +++ MCP Initialization +++
     this.mcpServersConfig = params?.mcpServers;
     this.createMCPClientImpl = params?.createMCPClient;
@@ -495,8 +494,8 @@ 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(
+    // Track request start
+    await this.error(
       "request",
       {
         threadId,
@@ -755,8 +754,8 @@ please use an LLM adapter instead.`,
         );
       }
 
-      // Trace the error
-      await this.trace(
+      // Track the error
+      await this.error(
         "error",
         {
           threadId,
@@ -1041,8 +1040,8 @@ 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(
+    // Track agent request start
+    await this.error(
       "agent_state",
       {
         threadId,
@@ -1222,8 +1221,8 @@ please use an LLM adapter instead.`,
               this.convertStreamingErrorToStructured(error),
             );
 
-            // Trace streaming errors
-            await this.trace(
+            // Track streaming errors
+            await this.error(
               "error",
               {
                 threadId,
@@ -1332,8 +1331,8 @@ please use an LLM adapter instead.`,
         this.convertStreamingErrorToStructured(err),
       );
 
-      // Trace the agent error
-      await this.trace(
+      // Track the agent error
+      await this.error(
         "error",
         {
           threadId,
@@ -1392,6 +1391,7 @@ please use an LLM adapter instead.`,
       frontendUrl: url,
       agents: this.agents,
       metaEvents: request.metaEvents,
+      nodeName: request.agentSession?.nodeName,
     });
 
     const configuredActions =
@@ -1505,45 +1505,45 @@ please use an LLM adapter instead.`,
     });
   }
 
-  private async trace(
-    type: CopilotTraceEvent["type"],
+  private async error(
+    type: CopilotErrorEvent["type"],
     context: CopilotRequestContext,
     error?: any,
     publicApiKey?: string,
   ): Promise<void> {
-    if (!this.onTrace) return;
+    if (!this.onError) return;
 
     // Just check if publicApiKey is defined (regardless of validity)
     if (!publicApiKey) {
-      if (!this.hasWarnedAboutTracing) {
+      if (!this.hasWarnedAboutError) {
         console.warn(
-          "CopilotKit: onTrace handler provided but requires publicApiKey to be defined for tracing to work.",
+          "CopilotKit: onError handler provided but requires publicApiKey to be defined for error handling to work.",
         );
-        this.hasWarnedAboutTracing = true;
+        this.hasWarnedAboutError = true;
       }
       return;
     }
 
     try {
-      const traceEvent: CopilotTraceEvent = {
+      const errorEvent: CopilotErrorEvent = {
         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);
+      await this.onError(errorEvent);
+    } catch (errorHandlerError) {
+      // Don't let error handler errors break the main flow
+      console.error("Error in onError handler:", errorHandlerError);
     }
   }
 
   /**
-   * Public method to trace GraphQL validation errors
-   * This allows the GraphQL resolver to send validation errors through the trace system
+   * Public method to handle GraphQL validation errors
+   * This allows the GraphQL resolver to send validation errors through the error system
    */
-  public async traceGraphQLError(
+  public async errorGraphQLError(
     error: { message: string; code: string; type: string },
     context: {
       operation: string;
@@ -1551,10 +1551,10 @@ please use an LLM adapter instead.`,
       guardrailsEnabled: boolean;
     },
   ): Promise<void> {
-    if (!this.onTrace) return;
+    if (!this.onError) return;
 
     try {
-      await this.onTrace({
+      await this.onError({
         type: "error",
         timestamp: Date.now(),
         context: {
@@ -1574,9 +1574,9 @@ please use an LLM adapter instead.`,
         },
         error,
       });
-    } catch (traceError) {
-      // Don't let trace errors break the main flow
-      console.error("Error in onTrace handler:", traceError);
+    } catch (errorHandlerError) {
+      // Don't let error handler errors break the main flow
+      console.error("Error in onError handler:", errorHandlerError);
     }
   }
 }

package/src/lib/runtime/remote-actions.ts

@@ -131,6 +131,7 @@ export async function setupRemoteActions({
   frontendUrl,
   agents,
   metaEvents,
+  nodeName,
 }: {
   remoteEndpointDefinitions: EndpointDefinition[];
   graphqlContext: GraphQLContext;
@@ -139,6 +140,7 @@ export async function setupRemoteActions({
   frontendUrl?: string;
   agents: Record<string, AbstractAgent>;
   metaEvents?: MetaEventInput[];
+  nodeName?: string;
 }): Promise<Action[]> {
   const logger = graphqlContext.logger.child({ component: "remote-actions.fetchRemoteActions" });
   logger.debug({ remoteEndpointDefinitions }, "Fetching from remote endpoints");
@@ -207,6 +209,7 @@ export async function setupRemoteActions({
         agent: agent,
         metaEvents,
         threadMetadata,
+        nodeName,
       }),
     );
   }