@copilotkit/runtime 1.57.3 → 1.58.0-canary.thread-id-propagation

package/src/v2/runtime/core/fetch-router.ts

@@ -1,203 +0,0 @@
-/**
- * Lightweight URL router for framework-agnostic CopilotKit runtime handler.
- *
- * Two strategies:
- * - With `basePath`: strict prefix strip → match remainder
- * - Without `basePath`: suffix matching on known patterns
- *
- * Single-route mode: delegates to `parseMethodCall` for JSON envelope dispatch.
- */
-
-import type { RouteInfo } from "./hooks";
-
-/**
- * Match a request URL against known CopilotKit route patterns.
- *
- * @param pathname - The URL pathname to match
- * @param basePath - Optional base path prefix to strip first
- * @returns RouteInfo if matched, null otherwise
- */
-export function matchRoute(
-  pathname: string,
-  basePath?: string,
-): RouteInfo | null {
-  let remainder: string;
-
-  if (basePath) {
-    // Normalize: ensure basePath doesn't end with /
-    const normalizedBase =
-      basePath.length > 1 && basePath.endsWith("/")
-        ? basePath.slice(0, -1)
-        : basePath;
-
-    // Special case: basePath === "/" matches everything
-    if (normalizedBase === "/") {
-      remainder = pathname;
-    } else {
-      if (!pathname.startsWith(normalizedBase)) return null;
-
-      // The character after basePath must be "/" or end of string
-      const afterBase = pathname.slice(normalizedBase.length);
-      if (afterBase.length > 0 && !afterBase.startsWith("/")) return null;
-
-      remainder = afterBase || "/";
-    }
-  } else {
-    // Suffix matching: find known patterns at the end of the pathname
-    remainder = pathname;
-  }
-
-  return matchSegments(remainder);
-}
-
-function safeDecodeURIComponent(value: string): string | null {
-  try {
-    return decodeURIComponent(value);
-  } catch {
-    return null;
-  }
-}
-
-function matchSegments(path: string): RouteInfo | null {
-  const segments = path.split("/").filter(Boolean);
-  const len = segments.length;
-
-  // Try suffix matching — scan from the end for known patterns
-
-  // /info (1 segment)
-  if (len >= 1 && segments[len - 1] === "info") {
-    return { method: "info" };
-  }
-
-  // /transcribe (1 segment)
-  if (len >= 1 && segments[len - 1] === "transcribe") {
-    return { method: "transcribe" };
-  }
-
-  // /cpk-debug-events (1 segment)
-  // Reserved route name: the `cpk-` prefix makes collision with a
-  // user-named agent essentially impossible (the router only treats
-  // `agent/:agentId/...` patterns as agent lookups, so a bare
-  // `cpk-debug-events` segment would never fall through to one —
-  // the prefix is the real guard, not this branch's position).
-  // Handler returns 404 in production.
-  if (len >= 1 && segments[len - 1] === "cpk-debug-events") {
-    return { method: "cpk-debug-events" };
-  }
-
-  // /agent/:agentId/run (3 segments)
-  if (
-    len >= 3 &&
-    segments[len - 3] === "agent" &&
-    segments[len - 1] === "run"
-  ) {
-    const agentId = safeDecodeURIComponent(segments[len - 2]!);
-    if (!agentId) return null;
-    return { method: "agent/run", agentId };
-  }
-
-  // /agent/:agentId/connect (3 segments)
-  if (
-    len >= 3 &&
-    segments[len - 3] === "agent" &&
-    segments[len - 1] === "connect"
-  ) {
-    const agentId = safeDecodeURIComponent(segments[len - 2]!);
-    if (!agentId) return null;
-    return { method: "agent/connect", agentId };
-  }
-
-  // /agent/:agentId/stop/:threadId (4 segments)
-  if (
-    len >= 4 &&
-    segments[len - 4] === "agent" &&
-    segments[len - 2] === "stop"
-  ) {
-    const agentId = safeDecodeURIComponent(segments[len - 3]!);
-    const threadId = safeDecodeURIComponent(segments[len - 1]!);
-    if (!agentId || !threadId) return null;
-    return { method: "agent/stop", agentId, threadId };
-  }
-
-  // /threads/subscribe (2 segments)
-  if (
-    len >= 2 &&
-    segments[len - 2] === "threads" &&
-    segments[len - 1] === "subscribe"
-  ) {
-    return { method: "threads/subscribe" };
-  }
-
-  // /threads/:threadId/messages (3 segments)
-  if (
-    len >= 3 &&
-    segments[len - 3] === "threads" &&
-    segments[len - 1] === "messages"
-  ) {
-    const threadId = safeDecodeURIComponent(segments[len - 2]!);
-    if (!threadId) return null;
-    return { method: "threads/messages", threadId };
-  }
-
-  // /threads/:threadId/events (3 segments)
-  if (
-    len >= 3 &&
-    segments[len - 3] === "threads" &&
-    segments[len - 1] === "events"
-  ) {
-    const threadId = safeDecodeURIComponent(segments[len - 2]!);
-    if (!threadId) return null;
-    return { method: "threads/events", threadId };
-  }
-
-  // /threads/:threadId/state (3 segments)
-  if (
-    len >= 3 &&
-    segments[len - 3] === "threads" &&
-    segments[len - 1] === "state"
-  ) {
-    const threadId = safeDecodeURIComponent(segments[len - 2]!);
-    if (!threadId) return null;
-    return { method: "threads/state", threadId };
-  }
-
-  // /threads/:threadId/archive (3 segments)
-  if (
-    len >= 3 &&
-    segments[len - 3] === "threads" &&
-    segments[len - 1] === "archive"
-  ) {
-    const threadId = safeDecodeURIComponent(segments[len - 2]!);
-    if (!threadId) return null;
-    return { method: "threads/archive", threadId };
-  }
-
-  // /threads/clear (2 segments) — wipe in-memory thread history
-  if (
-    len >= 2 &&
-    segments[len - 2] === "threads" &&
-    segments[len - 1] === "clear"
-  ) {
-    return { method: "threads/clear" };
-  }
-
-  // /threads/:threadId (2 segments) — update or delete
-  if (
-    len >= 2 &&
-    segments[len - 2] === "threads" &&
-    segments[len - 1] !== "subscribe" &&
-    segments[len - 1] !== "clear"
-  ) {
-    const threadId = safeDecodeURIComponent(segments[len - 1]!);
-    if (!threadId) return null;
-    // Disambiguated by HTTP method in the handler
-    return { method: "threads/update", threadId };
-  }
-
-  // /threads (1 segment) — list
-  if (len >= 1 && segments[len - 1] === "threads") {
-    return { method: "threads/list" };
-  }
-
-  return null;
-}

package/src/v2/runtime/core/hooks.ts

@@ -1,160 +0,0 @@
-/**
- * Lifecycle hooks for CopilotKit runtime request processing.
- *
- * Hooks let you intercept requests at various stages of the pipeline:
- * - `onRequest`: Before routing — auth, correlation IDs, header injection
- * - `onBeforeHandler`: After routing — route-specific authorization
- * - `onResponse`: After handler — add headers, log, set cookies
- * - `onError`: On error — custom error responses
- *
- * @example
- * ```typescript
- * const handler = createCopilotRuntimeHandler({
- *   runtime,
- *   hooks: {
- *     onRequest: async ({ request }) => {
- *       const token = request.headers.get("authorization");
- *       if (!token) throw new Response("Unauthorized", { status: 401 });
- *     },
- *     onResponse: async ({ response }) => {
- *       const headers = new Headers(response.headers);
- *       headers.set("x-copilot-version", "2.0");
- *       return new Response(response.body, { ...response, headers });
- *     },
- *   },
- * });
- * ```
- */
-
-import type { MaybePromise } from "@copilotkit/shared";
-import type { CopilotRuntimeLike } from "./runtime";
-
-/* ------------------------------------------------------------------------------------------------
- * Route info
- * --------------------------------------------------------------------------------------------- */
-
-export type RouteInfo =
-  | { method: "agent/run"; agentId: string }
-  | { method: "agent/connect"; agentId: string }
-  | { method: "agent/stop"; agentId: string; threadId: string }
-  | { method: "info" }
-  | { method: "transcribe" }
-  | { method: "threads/list" }
-  | { method: "threads/subscribe" }
-  | { method: "threads/update"; threadId: string }
-  | { method: "threads/archive"; threadId: string }
-  | { method: "threads/messages"; threadId: string }
-  | { method: "threads/events"; threadId: string }
-  | { method: "threads/state"; threadId: string }
-  | { method: "threads/clear" }
-  | { method: "cpk-debug-events" };
-
-/* ------------------------------------------------------------------------------------------------
- * Hook contexts
- * --------------------------------------------------------------------------------------------- */
-
-export interface HookContext {
-  /** The incoming Fetch Request (possibly modified by prior hooks). */
-  request: Request;
-  /** The resolved URL pathname. */
-  path: string;
-  /** The CopilotRuntimeLike instance. */
-  runtime: CopilotRuntimeLike;
-}
-
-export interface HandlerHookContext extends HookContext {
-  /** The resolved route information. */
-  route: RouteInfo;
-}
-
-export interface ResponseHookContext extends HookContext {
-  /** The Response produced by the handler. */
-  response: Response;
-  /** The resolved route information. */
-  route: RouteInfo;
-}
-
-export interface ErrorHookContext extends HookContext {
-  /** The error that occurred. */
-  error: unknown;
-  /** The route info, if routing had already succeeded. */
-  route?: RouteInfo;
-}
-
-/* ------------------------------------------------------------------------------------------------
- * Hooks interface
- * --------------------------------------------------------------------------------------------- */
-
-export interface CopilotRuntimeHooks {
-  /**
-   * Called at the start of every request, before routing.
-   * Use to validate auth, attach headers, initialize correlation IDs, etc.
-   *
-   * Return a modified Request to replace the original, or void to continue.
-   * Throw a Response to short-circuit with an early response.
-   */
-  onRequest?: (ctx: HookContext) => MaybePromise<Request | void>;
-
-  /**
-   * Called after routing is resolved but before the handler executes.
-   * Receives the resolved route info (method, agentId, threadId).
-   *
-   * Use to do route-specific authorization, attach headers for agent calls, etc.
-   * Return a modified Request or void.
-   * Throw a Response to short-circuit.
-   */
-  onBeforeHandler?: (ctx: HandlerHookContext) => MaybePromise<Request | void>;
-
-  /**
-   * Called after the handler produces a Response, before it's sent to the client.
-   * Use to set cookies, add debugging headers, log, etc.
-   *
-   * Return a modified Response to replace the original, or void.
-   */
-  onResponse?: (ctx: ResponseHookContext) => MaybePromise<Response | void>;
-
-  /**
-   * Called when an error occurs during request processing.
-   * Return a Response to override the default error response, or void to use the default.
-   */
-  onError?: (ctx: ErrorHookContext) => MaybePromise<Response | void>;
-}
-
-/* ------------------------------------------------------------------------------------------------
- * Internal hook runners
- * --------------------------------------------------------------------------------------------- */
-
-export async function runOnRequest(
-  hooks: CopilotRuntimeHooks | undefined,
-  ctx: HookContext,
-): Promise<Request> {
-  if (!hooks?.onRequest) return ctx.request;
-  const result = await hooks.onRequest(ctx);
-  return result instanceof Request ? result : ctx.request;
-}
-
-export async function runOnBeforeHandler(
-  hooks: CopilotRuntimeHooks | undefined,
-  ctx: HandlerHookContext,
-): Promise<Request> {
-  if (!hooks?.onBeforeHandler) return ctx.request;
-  const result = await hooks.onBeforeHandler(ctx);
-  return result instanceof Request ? result : ctx.request;
-}
-
-export async function runOnResponse(
-  hooks: CopilotRuntimeHooks | undefined,
-  ctx: ResponseHookContext,
-): Promise<Response> {
-  if (!hooks?.onResponse) return ctx.response;
-  const result = await hooks.onResponse(ctx);
-  return result instanceof Response ? result : ctx.response;
-}
-
-export async function runOnError(
-  hooks: CopilotRuntimeHooks | undefined,
-  ctx: ErrorHookContext,
-): Promise<Response | void> {
-  if (!hooks?.onError) return;
-  return hooks.onError(ctx);
-}

package/src/v2/runtime/core/middleware-sse-parser.ts

@@ -1,210 +0,0 @@
-import { logger } from "@copilotkit/shared";
-
-export interface ParsedSSEResult {
-  messages: Message[];
-  threadId?: string;
-  runId?: string;
-}
-
-/** Minimal message shape reconstructed from AG-UI events. */
-export interface Message {
-  id: string;
-  role: string;
-  content?: string;
-  toolCalls?: ToolCall[];
-  toolCallId?: string;
-}
-
-interface ToolCall {
-  id: string;
-  name: string;
-  args: string;
-}
-
-/**
- * Parse a cloned SSE Response body into structured messages.
- * Returns empty results for non-SSE responses.
- */
-export async function parseSSEResponse(
-  response: Response,
-): Promise<ParsedSSEResult> {
-  const contentType = response.headers.get("content-type") ?? "";
-  if (!contentType.includes("text/event-stream")) {
-    return { messages: [] };
-  }
-
-  let text: string;
-  try {
-    text = await response.text();
-  } catch {
-    logger.warn("Failed to read SSE response body in afterRequestMiddleware");
-    return { messages: [] };
-  }
-
-  if (!text.trim()) {
-    return { messages: [] };
-  }
-
-  let threadId: string | undefined;
-  let runId: string | undefined;
-  const messagesById = new Map<string, Message>();
-  const toolCallsById = new Map<string, ToolCall>();
-  const toolCallParent = new Map<string, string>(); // toolCallId → messageId
-  let snapshotMessages: Message[] | undefined;
-
-  for (const line of text.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed.startsWith("data:")) continue;
-
-    let event: Record<string, any>;
-    try {
-      event = JSON.parse(trimmed.slice(5).trim());
-    } catch {
-      continue;
-    }
-
-    switch (event.type) {
-      case "RUN_STARTED":
-        threadId = event.threadId;
-        runId = event.runId;
-        break;
-
-      case "MESSAGES_SNAPSHOT":
-        if (Array.isArray(event.messages)) {
-          snapshotMessages = event.messages;
-        }
-        break;
-
-      case "TEXT_MESSAGE_START":
-        messagesById.set(event.messageId, {
-          id: event.messageId,
-          role: event.role ?? "assistant",
-          content: "",
-        });
-        break;
-
-      case "TEXT_MESSAGE_CONTENT": {
-        const msg = messagesById.get(event.messageId);
-        if (msg) {
-          msg.content = (msg.content ?? "") + (event.delta ?? "");
-        }
-        break;
-      }
-
-      case "TEXT_MESSAGE_CHUNK": {
-        // Chunk format: combined start+content. First chunk creates the
-        // message, subsequent chunks append delta to content.
-        if (event.messageId) {
-          const existing = messagesById.get(event.messageId);
-          if (existing) {
-            existing.content = (existing.content ?? "") + (event.delta ?? "");
-          } else {
-            messagesById.set(event.messageId, {
-              id: event.messageId,
-              role: event.role ?? "assistant",
-              content: event.delta ?? "",
-            });
-          }
-        }
-        break;
-      }
-
-      case "TOOL_CALL_START": {
-        const tc: ToolCall = {
-          id: event.toolCallId,
-          name: event.toolCallName,
-          args: "",
-        };
-        toolCallsById.set(event.toolCallId, tc);
-        if (event.parentMessageId) {
-          toolCallParent.set(event.toolCallId, event.parentMessageId);
-        }
-        break;
-      }
-
-      case "TOOL_CALL_ARGS": {
-        const tc = toolCallsById.get(event.toolCallId);
-        if (tc) {
-          tc.args += event.delta ?? "";
-        }
-        break;
-      }
-
-      case "TOOL_CALL_CHUNK": {
-        // Chunk format: combined start+args. First chunk for a given
-        // toolCallId creates the tool call, subsequent chunks append delta.
-        if (event.toolCallId) {
-          let tc = toolCallsById.get(event.toolCallId);
-          if (!tc) {
-            tc = {
-              id: event.toolCallId,
-              name: event.toolCallName ?? "",
-              args: "",
-            };
-            toolCallsById.set(event.toolCallId, tc);
-            if (event.parentMessageId) {
-              toolCallParent.set(event.toolCallId, event.parentMessageId);
-            }
-          }
-          if (event.toolCallName) {
-            tc.name = event.toolCallName;
-          }
-          tc.args += event.delta ?? "";
-        }
-        break;
-      }
-
-      case "TOOL_CALL_END": {
-        const tc = toolCallsById.get(event.toolCallId);
-        const parentId = toolCallParent.get(event.toolCallId);
-        if (tc && parentId) {
-          const parent = messagesById.get(parentId);
-          if (parent) {
-            parent.toolCalls = parent.toolCalls ?? [];
-            parent.toolCalls.push(tc);
-          }
-        }
-        break;
-      }
-
-      case "TOOL_CALL_RESULT": {
-        // langchain-mcp-adapters may send content as an array of
-        // {type:"text", text:string} objects instead of a plain string.
-        let resultContent = event.content;
-        if (Array.isArray(resultContent)) {
-          resultContent = resultContent
-            .filter((part: any) => part && typeof part.text === "string")
-            .map((part: any) => part.text)
-            .join("");
-        }
-        messagesById.set(event.messageId, {
-          id: event.messageId,
-          role: "tool",
-          content: resultContent,
-          toolCallId: event.toolCallId,
-        });
-        break;
-      }
-    }
-  }
-
-  // Attach any tool calls not yet linked to their parent message.
-  // This handles TOOL_CALL_CHUNK flows which don't emit TOOL_CALL_END.
-  for (const [toolCallId, tc] of toolCallsById) {
-    const parentId = toolCallParent.get(toolCallId);
-    if (!parentId) continue;
-    const parent = messagesById.get(parentId);
-    if (!parent) continue;
-    const alreadyAttached = parent.toolCalls?.some((t) => t.id === tc.id);
-    if (!alreadyAttached) {
-      parent.toolCalls = parent.toolCalls ?? [];
-      parent.toolCalls.push(tc);
-    }
-  }
-
-  // Prefer MESSAGES_SNAPSHOT if present (contains full history).
-  // Otherwise reconstruct from individual events.
-  const messages = snapshotMessages ?? [...messagesById.values()];
-
-  return { messages, threadId, runId };
-}

package/src/v2/runtime/core/middleware.ts

@@ -1,115 +0,0 @@
-/**
- * Middleware support for CopilotKit Runtime.
- *
- * A middleware hook can be provided as either:
- *   1. A **callback function** executed in-process.
- *   2. A **webhook URL** (http/https).  The runtime will `POST` a JSON payload
- *      to the URL and, for *before* hooks, accept an optional modified
- *      `Request` object in the response body.
- *
- * Two lifecycle hooks are available:
- *   • `BEFORE_REQUEST` – runs *before* the request handler.
- *   • `AFTER_REQUEST`  – runs *after* the handler returns a `Response`.
- */
-
-import type { CopilotRuntimeLike } from "./runtime";
-import type { MaybePromise } from "@copilotkit/shared";
-import { logger } from "@copilotkit/shared";
-import { parseSSEResponse } from "./middleware-sse-parser";
-import type { Message } from "./middleware-sse-parser";
-
-/* ------------------------------------------------------------------------------------------------
- * Public types
- * --------------------------------------------------------------------------------------------- */
-
-export interface BeforeRequestMiddlewareParameters {
-  runtime: CopilotRuntimeLike;
-  request: Request;
-  path: string;
-}
-export interface AfterRequestMiddlewareParameters {
-  runtime: CopilotRuntimeLike;
-  response: Response;
-  path: string;
-  /** Reconstructed messages from the SSE stream (empty for non-SSE responses). */
-  messages?: Message[];
-  /** Thread ID extracted from the RUN_STARTED event. */
-  threadId?: string;
-  /** Run ID extracted from the RUN_STARTED event. */
-  runId?: string;
-}
-
-export type BeforeRequestMiddlewareFn = (
-  params: BeforeRequestMiddlewareParameters,
-) => MaybePromise<Request | void>;
-export type AfterRequestMiddlewareFn = (
-  params: AfterRequestMiddlewareParameters,
-) => MaybePromise<void>;
-
-/**
- * A middleware value can be either a callback function or a webhook URL.
- */
-export type BeforeRequestMiddleware = BeforeRequestMiddlewareFn;
-export type AfterRequestMiddleware = AfterRequestMiddlewareFn;
-
-/** Lifecycle events emitted to webhook middleware. */
-export enum CopilotKitMiddlewareEvent {
-  BeforeRequest = "BEFORE_REQUEST",
-  AfterRequest = "AFTER_REQUEST",
-}
-
-/** Stages used by the Middleware Webhook Protocol */
-/** Stages used by the CopilotKit webhook protocol */
-export enum WebhookStage {
-  BeforeRequest = "before_request",
-  AfterRequest = "after_request",
-}
-
-/* ------------------------------------------------------------------------------------------------
- * Internal helpers – (de)serialisation
- * --------------------------------------------------------------------------------------------- */
-
-export async function callBeforeRequestMiddleware({
-  runtime,
-  request,
-  path,
-}: BeforeRequestMiddlewareParameters): Promise<Request | void> {
-  const mw = runtime.beforeRequestMiddleware;
-  if (!mw) return;
-
-  // Function-based middleware (in-process)
-  if (typeof mw === "function") {
-    return (mw as BeforeRequestMiddlewareFn)({ runtime, request, path });
-  }
-
-  logger.warn({ mw }, "Unsupported beforeRequestMiddleware value – skipped");
-  return;
-}
-
-export async function callAfterRequestMiddleware({
-  runtime,
-  response,
-  path,
-}: {
-  runtime: CopilotRuntimeLike;
-  response: Response;
-  path: string;
-}): Promise<void> {
-  const mw = runtime.afterRequestMiddleware;
-  if (!mw) return;
-
-  const { messages, threadId, runId } = await parseSSEResponse(response);
-
-  if (typeof mw === "function") {
-    return (mw as AfterRequestMiddlewareFn)({
-      runtime,
-      response,
-      path,
-      messages,
-      threadId,
-      runId,
-    });
-  }
-
-  logger.warn({ mw }, "Unsupported afterRequestMiddleware value – skipped");
-}