@copilotkit/runtime 0.0.0-0.0.0-max-changeset-10101010101010-20260109191632

package/src/lib/integrations/shared.ts

@@ -0,0 +1,161 @@
+import { YogaInitialContext } from "graphql-yoga";
+import { buildSchemaSync } from "type-graphql";
+import { CopilotResolver } from "../../graphql/resolvers/copilot.resolver";
+import { useDeferStream } from "@graphql-yoga/plugin-defer-stream";
+import { CopilotRuntime } from "../runtime/copilot-runtime";
+import { CopilotServiceAdapter } from "../../service-adapters";
+import { CopilotCloudOptions } from "../cloud";
+import { LogLevel, createLogger } from "../../lib/logger";
+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();
+
+export const addCustomHeaderPlugin = {
+  onResponse({ response }) {
+    // Set your custom header; adjust the header name and value as needed
+    response.headers.set("X-CopilotKit-Runtime-Version", packageJson.version);
+  },
+};
+
+type AnyPrimitive = string | boolean | number | null;
+export type CopilotRequestContextProperties = Record<
+  string,
+  AnyPrimitive | Record<string, AnyPrimitive>
+>;
+
+export type GraphQLContext = YogaInitialContext & {
+  _copilotkit: CreateCopilotRuntimeServerOptions;
+  properties: CopilotRequestContextProperties;
+  logger: typeof logger;
+};
+
+export interface CreateCopilotRuntimeServerOptions {
+  runtime: CopilotRuntime<any>;
+  serviceAdapter?: CopilotServiceAdapter;
+  endpoint: string;
+  baseUrl?: string;
+  cloud?: CopilotCloudOptions;
+  properties?: CopilotRequestContextProperties;
+  logLevel?: LogLevel;
+}
+
+export async function createContext(
+  initialContext: YogaInitialContext,
+  copilotKitContext: CreateCopilotRuntimeServerOptions,
+  contextLogger: typeof logger,
+  properties: CopilotRequestContextProperties = {},
+): Promise<Partial<GraphQLContext>> {
+  logger.debug({ copilotKitContext }, "Creating GraphQL context");
+  const ctx: GraphQLContext = {
+    ...initialContext,
+    _copilotkit: {
+      ...copilotKitContext,
+    },
+    properties: { ...properties },
+    logger: contextLogger,
+  };
+  return ctx;
+}
+
+export function buildSchema(
+  options: {
+    emitSchemaFile?: string;
+  } = {},
+) {
+  logger.debug("Building GraphQL schema...");
+  const schema = buildSchemaSync({
+    resolvers: [CopilotResolver, StateResolver],
+    emitSchemaFile: options.emitSchemaFile,
+  });
+  logger.debug("GraphQL schema built successfully");
+  return schema;
+}
+
+export type CommonConfig = {
+  logging: typeof logger;
+  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 {
+  const logLevel = (process.env.LOG_LEVEL as LogLevel) || (options.logLevel as LogLevel) || "error";
+  const logger = createLogger({ level: logLevel, component: "getCommonConfig" });
+
+  const contextLogger = createLogger({ level: logLevel });
+
+  if (options.cloud) {
+    telemetry.setCloudConfiguration({
+      publicApiKey: options.cloud.publicApiKey,
+      baseUrl: options.cloud.baseUrl,
+    });
+  }
+
+  if (options.properties?._copilotkit) {
+    telemetry.setGlobalProperties({
+      _copilotkit: {
+        ...(options.properties._copilotkit as Record<string, any>),
+      },
+    });
+  }
+
+  telemetry.setGlobalProperties({
+    runtime: {
+      serviceAdapter: options.serviceAdapter.constructor.name,
+    },
+  });
+
+  // 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/logger.ts

@@ -0,0 +1,28 @@
+import createPinoLogger from "pino";
+import pretty from "pino-pretty";
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export type CopilotRuntimeLogger = ReturnType<typeof createLogger>;
+
+export function createLogger(options?: { level?: LogLevel; component?: string }) {
+  const { level, component } = options || {};
+  const stream = pretty({ colorize: true });
+
+  const logger = createPinoLogger(
+    {
+      level: process.env.LOG_LEVEL || level || "error",
+      redact: {
+        paths: ["pid", "hostname"],
+        remove: true,
+      },
+    },
+    stream,
+  );
+
+  if (component) {
+    return logger.child({ component });
+  } else {
+    return logger;
+  }
+}

package/src/lib/observability.ts

@@ -0,0 +1,160 @@
+import { RuntimeEventSource, RuntimeEventTypes } from "../service-adapters/events";
+
+export interface LLMRequestData {
+  threadId?: string;
+  runId?: string;
+  model?: string;
+  messages: any[];
+  actions?: any[];
+  forwardedParameters?: any;
+  timestamp: number;
+  provider?: string;
+  [key: string]: any;
+}
+
+export interface LLMResponseData {
+  threadId: string;
+  runId?: string;
+  model?: string;
+  output: any;
+  latency: number;
+  timestamp: number;
+  provider?: string;
+  isProgressiveChunk?: boolean;
+  isFinalResponse?: boolean;
+  [key: string]: any;
+}
+
+export interface LLMErrorData {
+  threadId?: string;
+  runId?: string;
+  model?: string;
+  error: Error | string;
+  timestamp: number;
+  provider?: string;
+  [key: string]: any;
+}
+
+export interface CopilotObservabilityHooks {
+  handleRequest: (data: LLMRequestData) => void | Promise<void>;
+  handleResponse: (data: LLMResponseData) => void | Promise<void>;
+  handleError: (data: LLMErrorData) => void | Promise<void>;
+}
+
+/**
+ * Configuration for CopilotKit logging functionality.
+ *
+ * @remarks
+ * Custom logging handlers require a valid CopilotKit public API key.
+ * Sign up at https://docs.copilotkit.ai/quickstart#get-a-copilot-cloud-public-api-key to get your key.
+ */
+export interface CopilotObservabilityConfig {
+  /**
+   * Enable or disable logging functionality.
+   *
+   * @default false
+   */
+  enabled: boolean;
+
+  /**
+   * Controls whether logs are streamed progressively or buffered.
+   * - When true: Each token and update is logged as it's generated (real-time)
+   * - When false: Complete responses are logged after completion (batched)
+   *
+   * @default true
+   */
+  progressive: boolean;
+
+  /**
+   * Custom observability hooks for request, response, and error events.
+   *
+   * @remarks
+   * Using custom observability hooks requires a valid CopilotKit public API key.
+   */
+  hooks: CopilotObservabilityHooks;
+}
+
+/**
+ * Setup progressive logging by wrapping the event stream
+ */
+function setupProgressiveLogging(
+  eventSource: RuntimeEventSource,
+  streamedChunks: any[],
+  requestStartTime: number,
+  context: {
+    threadId?: string;
+    runId?: string;
+    model?: string;
+    provider?: string;
+    agentName?: string;
+    nodeName?: string;
+  },
+  publicApiKey?: string,
+): void {
+  if (this.observability?.enabled && this.observability.progressive && publicApiKey) {
+    // Keep reference to original stream function
+    const originalStream = eventSource.stream.bind(eventSource);
+
+    // Wrap the stream function to intercept events
+    eventSource.stream = async (callback) => {
+      await originalStream(async (eventStream$) => {
+        // Create subscription to capture streaming events
+        eventStream$.subscribe({
+          next: (event) => {
+            // Only log content chunks
+            if (event.type === RuntimeEventTypes.TextMessageContent) {
+              // Store the chunk
+              streamedChunks.push(event.content);
+
+              // Log each chunk separately for progressive mode
+              try {
+                const progressiveData: LLMResponseData = {
+                  threadId: context.threadId || "",
+                  runId: context.runId,
+                  model: context.model,
+                  output: event.content,
+                  latency: Date.now() - requestStartTime,
+                  timestamp: Date.now(),
+                  provider: context.provider,
+                  isProgressiveChunk: true,
+                  agentName: context.agentName,
+                  nodeName: context.nodeName,
+                };
+
+                // Use Promise to handle async logger without awaiting
+                Promise.resolve()
+                  .then(() => {
+                    this.observability.hooks.handleResponse(progressiveData);
+                  })
+                  .catch((error) => {
+                    console.error("Error in progressive logging:", error);
+                  });
+              } catch (error) {
+                console.error("Error preparing progressive log data:", error);
+              }
+            }
+          },
+        });
+
+        // Call the original callback with the event stream
+        await callback(eventStream$);
+      });
+    };
+  }
+}
+
+/**
+ * Log error if observability is enabled
+ */
+async function logObservabilityError(
+  errorData: LLMErrorData,
+  publicApiKey?: string,
+): Promise<void> {
+  if (this.observability?.enabled && publicApiKey) {
+    try {
+      await this.observability.hooks.handleError(errorData);
+    } catch (logError) {
+      console.error("Error logging LLM error:", logError);
+    }
+  }
+}

package/src/lib/runtime/__tests__/copilot-runtime-error.test.ts

@@ -0,0 +1,169 @@
+import { CopilotErrorEvent, CopilotRequestContext, CopilotErrorHandler } from "@copilotkit/shared";
+
+describe("CopilotRuntime onError types", () => {
+  it("should have correct CopilotTraceEvent type structure", () => {
+    const errorEvent: CopilotErrorEvent = {
+      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(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", () => {
+    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 error event types", () => {
+    const eventTypes: CopilotErrorEvent["type"][] = [
+      "error",
+      "request",
+      "response",
+      "agent_state",
+      "action",
+      "message",
+      "performance",
+    ];
+
+    eventTypes.forEach((type) => {
+      const event: CopilotErrorEvent = {
+        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 ShouldHandleError = (onError?: CopilotErrorHandler, publicApiKey?: string) => boolean;
+
+    const shouldHandleError: ShouldHandleError = (onError, publicApiKey) => {
+      return Boolean(onError && publicApiKey);
+    };
+
+    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 onError is missing", () => {
+      const result = shouldHandleError(undefined, "valid-api-key");
+      expect(result).toBe(false);
+    });
+
+    it("should return false when publicApiKey is missing", () => {
+      const onError = jest.fn();
+      const result = shouldHandleError(onError, undefined);
+      expect(result).toBe(false);
+    });
+
+    it("should return false when publicApiKey is empty string", () => {
+      const onError = jest.fn();
+      const result = shouldHandleError(onError, "");
+      expect(result).toBe(false);
+    });
+
+    it("should return false when both are missing", () => {
+      const result = shouldHandleError(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 error handling when onError is present
+      const onError = jest.fn();
+      expect(shouldHandleError(onError, cloudKey)).toBe(true);
+      expect(shouldHandleError(onError, nonCloudKey)).toBe(true);
+    });
+  });
+});