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

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/index.ts

@@ -0,0 +1,52 @@
+export * from "../service-adapters/openai/openai-adapter";
+export * from "../service-adapters/langchain/langchain-adapter";
+export * from "../service-adapters/google/google-genai-adapter";
+export * from "../service-adapters/openai/openai-assistant-adapter";
+export * from "../service-adapters/unify/unify-adapter";
+export * from "../service-adapters/groq/groq-adapter";
+export * from "./integrations";
+export * from "./logger";
+export * from "./runtime/copilot-runtime";
+export * from "./runtime/mcp-tools-utils";
+export * from "./runtime/telemetry-agent-runner";
+
+// The below re-exports "dummy" classes and types, to get a deprecation warning redirecting the users to import these from the correct, new route
+
+/**
+ * @deprecated LangGraphAgent import from `@copilotkit/runtime` is deprecated. Please import it from `@copilotkit/runtime/langgraph` instead
+ */
+export class LangGraphAgent {
+  constructor() {
+    throw new Error(
+      "LangGraphAgent import from @copilotkit/runtime is deprecated. Please import it from @copilotkit/runtime/langgraph instead",
+    );
+  }
+}
+
+/**
+ * @deprecated LangGraphHttpAgent import from `@copilotkit/runtime` is deprecated. Please import it from `@copilotkit/runtime/langgraph` instead
+ */
+export class LangGraphHttpAgent {
+  constructor() {
+    throw new Error(
+      "LangGraphHttpAgent import from @copilotkit/runtime is deprecated. Please import it from @copilotkit/runtime/langgraph instead",
+    );
+  }
+}
+
+/**
+ * @deprecated TextMessageEvents import from `@copilotkit/runtime` is deprecated. Please import it from `@copilotkit/runtime/langgraph` instead
+ */
+export type TextMessageEvents = any;
+/**
+ * @deprecated ToolCallEvents import from `@copilotkit/runtime` is deprecated. Please import it from `@copilotkit/runtime/langgraph` instead
+ */
+export type ToolCallEvents = any;
+/**
+ * @deprecated CustomEventNames import from `@copilotkit/runtime` is deprecated. Please import it from `@copilotkit/runtime/langgraph` instead
+ */
+export type CustomEventNames = any;
+/**
+ * @deprecated PredictStateTool import from `@copilotkit/runtime` is deprecated. Please import it from `@copilotkit/runtime/langgraph` instead
+ */
+export type PredictStateTool = any;

package/src/lib/integrations/index.ts

@@ -0,0 +1,6 @@
+export * from "./shared";
+export * from "./nextjs/app-router";
+export * from "./nextjs/pages-router";
+export * from "./node-http";
+export * from "./node-express";
+export * from "./nest";

package/src/lib/integrations/nest/index.ts

@@ -0,0 +1,14 @@
+import { CreateCopilotRuntimeServerOptions } from "../shared";
+import { copilotRuntimeNodeHttpEndpoint } from "../node-http";
+import telemetry, { getRuntimeInstanceTelemetryInfo } from "../../telemetry-client";
+
+export function copilotRuntimeNestEndpoint(options: CreateCopilotRuntimeServerOptions) {
+  telemetry.setGlobalProperties({
+    runtime: {
+      framework: "nest",
+    },
+  });
+
+  telemetry.capture("oss.runtime.instance_created", getRuntimeInstanceTelemetryInfo(options));
+  return copilotRuntimeNodeHttpEndpoint(options);
+}

package/src/lib/integrations/nextjs/app-router.ts

@@ -0,0 +1,38 @@
+import { createCopilotEndpointSingleRoute } from "@copilotkitnext/runtime";
+import { CreateCopilotRuntimeServerOptions, getCommonConfig } from "../shared";
+import telemetry, { getRuntimeInstanceTelemetryInfo } from "../../telemetry-client";
+import { handle } from "hono/vercel";
+
+export function copilotRuntimeNextJSAppRouterEndpoint(options: CreateCopilotRuntimeServerOptions) {
+  const commonConfig = getCommonConfig(options);
+
+  telemetry.setGlobalProperties({
+    runtime: {
+      framework: "nextjs-app-router",
+    },
+  });
+
+  if (options.properties?._copilotkit) {
+    telemetry.setGlobalProperties({
+      _copilotkit: options.properties._copilotkit,
+    });
+  }
+
+  telemetry.capture("oss.runtime.instance_created", getRuntimeInstanceTelemetryInfo(options));
+
+  const logger = commonConfig.logging;
+  logger.debug("Creating NextJS App Router endpoint");
+
+  const serviceAdapter = options.serviceAdapter;
+  if (serviceAdapter) {
+    options.runtime.handleServiceAdapter(serviceAdapter);
+  }
+
+  const copilotRoute = createCopilotEndpointSingleRoute({
+    runtime: options.runtime.instance,
+    basePath: options.baseUrl ?? options.endpoint,
+  });
+
+  const handleRequest = handle(copilotRoute as any);
+  return { handleRequest };
+}

package/src/lib/integrations/nextjs/pages-router.ts

@@ -0,0 +1,39 @@
+import { CreateCopilotRuntimeServerOptions, getCommonConfig } from "../shared";
+import telemetry, { getRuntimeInstanceTelemetryInfo } from "../../telemetry-client";
+import { copilotRuntimeNodeHttpEndpoint } from "../node-http";
+
+export const config = {
+  api: {
+    bodyParser: false,
+  },
+};
+
+// This import is needed to fix the type error
+// Fix is currently in TypeScript 5.5 beta, waiting for stable version
+// https://github.com/microsoft/TypeScript/issues/42873#issuecomment-2066874644
+export type {} from "@whatwg-node/server";
+
+export function copilotRuntimeNextJSPagesRouterEndpoint(
+  options: CreateCopilotRuntimeServerOptions,
+) {
+  const commonConfig = getCommonConfig(options);
+
+  telemetry.setGlobalProperties({
+    runtime: {
+      framework: "nextjs-pages-router",
+    },
+  });
+
+  if (options.properties?._copilotkit) {
+    telemetry.setGlobalProperties({
+      _copilotkit: options.properties._copilotkit,
+    });
+  }
+
+  telemetry.capture("oss.runtime.instance_created", getRuntimeInstanceTelemetryInfo(options));
+
+  const logger = commonConfig.logging;
+  logger.debug("Creating NextJS Pages Router endpoint");
+
+  return copilotRuntimeNodeHttpEndpoint(options);
+}

package/src/lib/integrations/node-express/index.ts

@@ -0,0 +1,14 @@
+import { CreateCopilotRuntimeServerOptions } from "../shared";
+import { copilotRuntimeNodeHttpEndpoint } from "../node-http";
+import telemetry, { getRuntimeInstanceTelemetryInfo } from "../../telemetry-client";
+
+export function copilotRuntimeNodeExpressEndpoint(options: CreateCopilotRuntimeServerOptions) {
+  telemetry.setGlobalProperties({
+    runtime: {
+      framework: "node-express",
+    },
+  });
+
+  telemetry.capture("oss.runtime.instance_created", getRuntimeInstanceTelemetryInfo(options));
+  return copilotRuntimeNodeHttpEndpoint(options);
+}

package/src/lib/integrations/node-http/index.ts

@@ -0,0 +1,143 @@
+import { CreateCopilotRuntimeServerOptions, getCommonConfig } from "../shared";
+import telemetry, { getRuntimeInstanceTelemetryInfo } from "../../telemetry-client";
+import { createCopilotEndpointSingleRoute } from "@copilotkitnext/runtime";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import {
+  getFullUrl,
+  IncomingWithBody,
+  isDisturbedOrLockedError,
+  isStreamConsumed,
+  nodeStreamToReadableStream,
+  readableStreamToNodeStream,
+  synthesizeBodyFromParsedBody,
+  toHeaders,
+} from "./request-handler";
+
+export function copilotRuntimeNodeHttpEndpoint(options: CreateCopilotRuntimeServerOptions) {
+  const commonConfig = getCommonConfig(options);
+
+  telemetry.setGlobalProperties({
+    runtime: {
+      framework: "node-http",
+    },
+  });
+
+  if (options.properties?._copilotkit) {
+    telemetry.setGlobalProperties({
+      _copilotkit: options.properties._copilotkit,
+    });
+  }
+
+  telemetry.capture("oss.runtime.instance_created", getRuntimeInstanceTelemetryInfo(options));
+
+  const logger = commonConfig.logging;
+  logger.debug("Creating Node HTTP endpoint");
+
+  const serviceAdapter = options.serviceAdapter;
+  if (serviceAdapter) {
+    options.runtime.handleServiceAdapter(serviceAdapter);
+  }
+
+  const honoApp = createCopilotEndpointSingleRoute({
+    runtime: options.runtime.instance,
+    basePath: options.baseUrl ?? options.endpoint,
+  });
+
+  const handle = async function handler(req: IncomingWithBody, res: ServerResponse) {
+    const url = getFullUrl(req);
+    const hasBody = req.method !== "GET" && req.method !== "HEAD";
+
+    const baseHeaders = toHeaders(req.headers);
+    const parsedBody = req.body;
+
+    const streamConsumed = isStreamConsumed(req) || parsedBody !== undefined;
+    const canStream = hasBody && !streamConsumed;
+
+    let requestBody: BodyInit | null | undefined = undefined;
+    let useDuplex = false;
+
+    if (hasBody && canStream) {
+      requestBody = nodeStreamToReadableStream(req);
+      useDuplex = true;
+    }
+
+    if (hasBody && streamConsumed) {
+      if (parsedBody !== undefined) {
+        const synthesized = synthesizeBodyFromParsedBody(parsedBody, baseHeaders);
+        requestBody = synthesized.body ?? undefined;
+        baseHeaders.delete("content-length");
+
+        if (synthesized.contentType) {
+          baseHeaders.set("content-type", synthesized.contentType);
+        }
+
+        logger.debug("Request stream already consumed; using parsed req.body to rebuild request.");
+      } else {
+        logger.warn("Request stream consumed with no available body; sending empty payload.");
+        requestBody = undefined;
+      }
+    }
+
+    const buildRequest = (body: BodyInit | null | undefined, headers: Headers, duplex: boolean) =>
+      new Request(url, {
+        method: req.method,
+        headers,
+        body,
+        duplex: duplex ? "half" : undefined,
+      } as RequestInit);
+
+    let response: Response;
+    try {
+      response = await honoApp.fetch(buildRequest(requestBody, baseHeaders, useDuplex));
+    } catch (error) {
+      if (isDisturbedOrLockedError(error) && hasBody) {
+        logger.warn(
+          "Encountered disturbed/locked request body; rebuilding request using parsed body or empty payload.",
+        );
+
+        const fallbackHeaders = new Headers(baseHeaders);
+        let fallbackBody: BodyInit | null | undefined;
+
+        if (parsedBody !== undefined) {
+          const synthesized = synthesizeBodyFromParsedBody(parsedBody, fallbackHeaders);
+          fallbackBody = synthesized.body ?? undefined;
+          fallbackHeaders.delete("content-length");
+
+          if (synthesized.contentType) {
+            fallbackHeaders.set("content-type", synthesized.contentType);
+          }
+        } else {
+          fallbackBody = undefined;
+        }
+
+        response = await honoApp.fetch(buildRequest(fallbackBody, fallbackHeaders, false));
+      } else {
+        throw error;
+      }
+    }
+
+    res.statusCode = response.status;
+    response.headers.forEach((value, key) => {
+      res.setHeader(key, value);
+    });
+
+    if (response.body) {
+      readableStreamToNodeStream(response.body).pipe(res);
+    } else {
+      res.end();
+    }
+  };
+
+  return function (
+    reqOrRequest: IncomingMessage | Request,
+    res?: ServerResponse,
+  ): Promise<void> | Promise<Response> | Response {
+    if (reqOrRequest instanceof Request) {
+      return honoApp.fetch(reqOrRequest as Request);
+    }
+    if (!res) {
+      throw new TypeError("ServerResponse is required for Node HTTP requests");
+    }
+    return handle(reqOrRequest as IncomingMessage, res);
+  };
+}

package/src/lib/integrations/node-http/request-handler.ts

@@ -0,0 +1,111 @@
+import type { IncomingMessage } from "http";
+import { Readable } from "node:stream";
+
+export type IncomingWithBody = IncomingMessage & { body?: unknown; complete?: boolean };
+
+export function readableStreamToNodeStream(webStream: ReadableStream): Readable {
+  const reader = webStream.getReader();
+
+  return new Readable({
+    async read() {
+      try {
+        const { done, value } = await reader.read();
+        if (done) {
+          this.push(null);
+        } else {
+          this.push(Buffer.from(value));
+        }
+      } catch (err) {
+        this.destroy(err as Error);
+      }
+    },
+  });
+}
+
+export function nodeStreamToReadableStream(nodeStream: Readable): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller) {
+      nodeStream.on("data", (chunk) => {
+        controller.enqueue(chunk instanceof Buffer ? new Uint8Array(chunk) : chunk);
+      });
+      nodeStream.on("end", () => {
+        controller.close();
+      });
+      nodeStream.on("error", (err) => {
+        controller.error(err);
+      });
+    },
+    cancel() {
+      nodeStream.destroy();
+    },
+  });
+}
+
+export function getFullUrl(req: IncomingMessage): string {
+  // Use req.url (path relative to mount point) for Hono routing to work correctly.
+  // Express sets req.url to the path after the mount point (e.g., "/" when mounted at "/copilotkit").
+  // Pure Node HTTP sets req.url to the full path.
+  const path = req.url || "/";
+  const host =
+    (req.headers["x-forwarded-host"] as string) || (req.headers.host as string) || "localhost";
+  const proto =
+    (req.headers["x-forwarded-proto"] as string) ||
+    ((req.socket as any).encrypted ? "https" : "http");
+
+  return `${proto}://${host}${path}`;
+}
+
+export function toHeaders(rawHeaders: IncomingMessage["headers"]): Headers {
+  const headers = new Headers();
+
+  for (const [key, value] of Object.entries(rawHeaders)) {
+    if (value === undefined) continue;
+
+    if (Array.isArray(value)) {
+      value.forEach((entry) => headers.append(key, entry));
+      continue;
+    }
+
+    headers.append(key, value);
+  }
+
+  return headers;
+}
+
+export function isStreamConsumed(req: IncomingWithBody): boolean {
+  const readableState = (req as any)._readableState;
+
+  return Boolean(
+    req.readableEnded || req.complete || readableState?.ended || readableState?.endEmitted,
+  );
+}
+
+export function synthesizeBodyFromParsedBody(
+  parsedBody: unknown,
+  headers: Headers,
+): { body: BodyInit | null; contentType?: string } {
+  if (parsedBody === null || parsedBody === undefined) {
+    return { body: null };
+  }
+
+  if (parsedBody instanceof Buffer || parsedBody instanceof Uint8Array) {
+    return { body: parsedBody };
+  }
+
+  if (typeof parsedBody === "string") {
+    return { body: parsedBody, contentType: headers.get("content-type") ?? "text/plain" };
+  }
+
+  return {
+    body: JSON.stringify(parsedBody),
+    contentType: "application/json",
+  };
+}
+
+export function isDisturbedOrLockedError(error: unknown): boolean {
+  return (
+    error instanceof TypeError &&
+    typeof error.message === "string" &&
+    (error.message.includes("disturbed") || error.message.includes("locked"))
+  );
+}