@copilotkit/runtime 1.54.1 → 1.55.0-next.8

package/src/v2/runtime/handlers/handle-stop.ts

@@ -0,0 +1,76 @@
+import { CopilotRuntimeLike } from "../runtime";
+import { EventType } from "@ag-ui/client";
+
+interface StopAgentParameters {
+  request: Request;
+  runtime: CopilotRuntimeLike;
+  agentId: string;
+  threadId: string;
+}
+
+export async function handleStopAgent({
+  runtime,
+  request,
+  agentId,
+  threadId,
+}: StopAgentParameters) {
+  try {
+    const agents = await runtime.agents;
+
+    if (!agents[agentId]) {
+      return new Response(
+        JSON.stringify({
+          error: "Agent not found",
+          message: `Agent '${agentId}' does not exist`,
+        }),
+        {
+          status: 404,
+          headers: { "Content-Type": "application/json" },
+        },
+      );
+    }
+
+    const stopped = await runtime.runner.stop({ threadId });
+
+    if (!stopped) {
+      return new Response(
+        JSON.stringify({
+          stopped: false,
+          message: `No active run for thread '${threadId}'.`,
+        }),
+        {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        },
+      );
+    }
+
+    return new Response(
+      JSON.stringify({
+        stopped: true,
+        interrupt: {
+          type: EventType.RUN_ERROR,
+          message: "Run stopped by user",
+          code: "STOPPED",
+        },
+      }),
+      {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+  } catch (error) {
+    console.error("Error stopping agent run:", error);
+
+    return new Response(
+      JSON.stringify({
+        error: "Failed to stop agent",
+        message: error instanceof Error ? error.message : "Unknown error",
+      }),
+      {
+        status: 500,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+  }
+}

package/src/v2/runtime/handlers/handle-threads.ts

@@ -0,0 +1,7 @@
+export {
+  handleArchiveThread,
+  handleDeleteThread,
+  handleListThreads,
+  handleSubscribeToThreads,
+  handleUpdateThread,
+} from "./intelligence/threads";

package/src/v2/runtime/handlers/handle-transcribe.ts

@@ -0,0 +1,256 @@
+import { CopilotRuntimeLike } from "../runtime";
+import {
+  TranscriptionErrorCode,
+  TranscriptionErrors,
+  type TranscriptionErrorResponse,
+} from "@copilotkit/shared";
+
+/**
+ * HTTP status codes for transcription error codes
+ */
+const ERROR_STATUS_CODES: Record<TranscriptionErrorCode, number> = {
+  [TranscriptionErrorCode.SERVICE_NOT_CONFIGURED]: 503,
+  [TranscriptionErrorCode.INVALID_AUDIO_FORMAT]: 400,
+  [TranscriptionErrorCode.AUDIO_TOO_LONG]: 400,
+  [TranscriptionErrorCode.AUDIO_TOO_SHORT]: 400,
+  [TranscriptionErrorCode.RATE_LIMITED]: 429,
+  [TranscriptionErrorCode.AUTH_FAILED]: 401,
+  [TranscriptionErrorCode.PROVIDER_ERROR]: 500,
+  [TranscriptionErrorCode.NETWORK_ERROR]: 502,
+  [TranscriptionErrorCode.INVALID_REQUEST]: 400,
+};
+
+interface HandleTranscribeParameters {
+  runtime: CopilotRuntimeLike;
+  request: Request;
+}
+
+interface Base64AudioInput {
+  audio: string; // base64-encoded audio data
+  mimeType: string;
+  filename?: string;
+}
+
+const VALID_AUDIO_TYPES = [
+  "audio/mpeg",
+  "audio/mp3",
+  "audio/mp4",
+  "audio/wav",
+  "audio/webm",
+  "audio/ogg",
+  "audio/flac",
+  "audio/aac",
+];
+
+function isValidAudioType(type: string): boolean {
+  // Extract base MIME type (before semicolon) to handle types like "audio/webm; codecs=opus"
+  const baseType = type.split(";")[0]?.trim() ?? "";
+  return (
+    VALID_AUDIO_TYPES.includes(baseType) ||
+    baseType === "" ||
+    baseType === "application/octet-stream"
+  );
+}
+
+function createErrorResponse(
+  errorResponse: TranscriptionErrorResponse,
+): Response {
+  const status = ERROR_STATUS_CODES[errorResponse.error] ?? 500;
+  return new Response(JSON.stringify(errorResponse), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function base64ToFile(
+  base64: string,
+  mimeType: string,
+  filename: string,
+): File {
+  // Remove data URL prefix if present (e.g., "data:audio/webm;base64,")
+  const base64Data = base64.includes(",")
+    ? (base64.split(",")[1] ?? base64)
+    : base64;
+
+  // Decode base64 to binary
+  const binaryString = atob(base64Data);
+  const bytes = new Uint8Array(binaryString.length);
+  for (let i = 0; i < binaryString.length; i++) {
+    bytes[i] = binaryString.charCodeAt(i);
+  }
+
+  // Create File object
+  return new File([bytes], filename, { type: mimeType });
+}
+
+async function extractAudioFromFormData(
+  request: Request,
+): Promise<{ file: File } | { error: Response }> {
+  const formData = await request.formData();
+  const audioFile = formData.get("audio") as File | null;
+
+  if (!audioFile || !(audioFile instanceof File)) {
+    const err = TranscriptionErrors.invalidRequest(
+      "No audio file found in form data. Please include an 'audio' field.",
+    );
+    return { error: createErrorResponse(err) };
+  }
+
+  if (!isValidAudioType(audioFile.type)) {
+    const err = TranscriptionErrors.invalidAudioFormat(
+      audioFile.type,
+      VALID_AUDIO_TYPES,
+    );
+    return { error: createErrorResponse(err) };
+  }
+
+  return { file: audioFile };
+}
+
+async function extractAudioFromJson(
+  request: Request,
+): Promise<{ file: File } | { error: Response }> {
+  let body: Base64AudioInput;
+
+  try {
+    body = await request.json();
+  } catch {
+    const err = TranscriptionErrors.invalidRequest(
+      "Request body must be valid JSON",
+    );
+    return { error: createErrorResponse(err) };
+  }
+
+  if (!body.audio || typeof body.audio !== "string") {
+    const err = TranscriptionErrors.invalidRequest(
+      "Request must include 'audio' field with base64-encoded audio data",
+    );
+    return { error: createErrorResponse(err) };
+  }
+
+  if (!body.mimeType || typeof body.mimeType !== "string") {
+    const err = TranscriptionErrors.invalidRequest(
+      "Request must include 'mimeType' field (e.g., 'audio/webm')",
+    );
+    return { error: createErrorResponse(err) };
+  }
+
+  if (!isValidAudioType(body.mimeType)) {
+    const err = TranscriptionErrors.invalidAudioFormat(
+      body.mimeType,
+      VALID_AUDIO_TYPES,
+    );
+    return { error: createErrorResponse(err) };
+  }
+
+  try {
+    const filename = body.filename || "recording.webm";
+    const file = base64ToFile(body.audio, body.mimeType, filename);
+    return { file };
+  } catch {
+    const err = TranscriptionErrors.invalidRequest(
+      "Failed to decode base64 audio data",
+    );
+    return { error: createErrorResponse(err) };
+  }
+}
+
+/**
+ * Categorize provider errors into appropriate transcription error responses.
+ */
+function categorizeProviderError(error: unknown): TranscriptionErrorResponse {
+  const message =
+    error instanceof Error ? error.message : "Unknown error occurred";
+  const errorStr = String(error).toLowerCase();
+
+  // Check for rate limiting
+  if (
+    errorStr.includes("rate") ||
+    errorStr.includes("429") ||
+    errorStr.includes("too many")
+  ) {
+    return TranscriptionErrors.rateLimited();
+  }
+
+  // Check for auth errors
+  if (
+    errorStr.includes("auth") ||
+    errorStr.includes("401") ||
+    errorStr.includes("api key") ||
+    errorStr.includes("unauthorized")
+  ) {
+    return TranscriptionErrors.authFailed();
+  }
+
+  // Check for audio too long
+  if (
+    errorStr.includes("too long") ||
+    errorStr.includes("duration") ||
+    errorStr.includes("length")
+  ) {
+    return TranscriptionErrors.audioTooLong();
+  }
+
+  // Default to provider error
+  return TranscriptionErrors.providerError(message);
+}
+
+export async function handleTranscribe({
+  runtime,
+  request,
+}: HandleTranscribeParameters) {
+  try {
+    // Check if transcription service is configured
+    if (!runtime.transcriptionService) {
+      const err = TranscriptionErrors.serviceNotConfigured();
+      return createErrorResponse(err);
+    }
+
+    // Determine input type based on content-type header
+    const contentType = request.headers.get("content-type") || "";
+
+    let extractResult: { file: File } | { error: Response };
+
+    if (contentType.includes("multipart/form-data")) {
+      // Handle multipart/form-data (REST mode)
+      extractResult = await extractAudioFromFormData(request);
+    } else if (contentType.includes("application/json")) {
+      // Handle JSON with base64 audio (single-endpoint mode)
+      extractResult = await extractAudioFromJson(request);
+    } else {
+      const err = TranscriptionErrors.invalidRequest(
+        "Request must be multipart/form-data or application/json with base64 audio",
+      );
+      return createErrorResponse(err);
+    }
+
+    // Check for extraction errors
+    if ("error" in extractResult) {
+      return extractResult.error;
+    }
+
+    const audioFile = extractResult.file;
+
+    // Transcribe the audio file
+    const transcription = await runtime.transcriptionService.transcribeFile({
+      audioFile,
+      mimeType: audioFile.type,
+      size: audioFile.size,
+    });
+
+    return new Response(
+      JSON.stringify({
+        text: transcription,
+        size: audioFile.size,
+        type: audioFile.type,
+      }),
+      {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+  } catch (error) {
+    // Categorize the error for better client-side handling
+    return createErrorResponse(categorizeProviderError(error));
+  }
+}

package/src/v2/runtime/handlers/header-utils.ts

@@ -0,0 +1,24 @@
+/**
+ * Determines if a header should be forwarded based on the allowlist.
+ * Forwards: authorization header and all x-* custom headers.
+ */
+export function shouldForwardHeader(headerName: string): boolean {
+  const lower = headerName.toLowerCase();
+  return lower === "authorization" || lower.startsWith("x-");
+}
+
+/**
+ * Extracts headers that should be forwarded from a Request object.
+ * Forwards only authorization and x-* headers.
+ */
+export function extractForwardableHeaders(
+  request: Request,
+): Record<string, string> {
+  const forwardableHeaders: Record<string, string> = {};
+  request.headers.forEach((value, key) => {
+    if (shouldForwardHeader(key)) {
+      forwardableHeaders[key] = value;
+    }
+  });
+  return forwardableHeaders;
+}

package/src/v2/runtime/handlers/intelligence/connect.ts

@@ -0,0 +1,65 @@
+import { CopilotIntelligenceRuntimeLike } from "../../runtime";
+import { isPlatformNotFoundError } from "../shared/intelligence-utils";
+import { resolveIntelligenceUser } from "../shared/resolve-intelligence-user";
+import { isHandlerResponse } from "../shared/json-response";
+
+interface HandleIntelligenceConnectParams {
+  runtime: CopilotIntelligenceRuntimeLike;
+  request: Request;
+  threadId: string;
+  lastSeenEventId: string | null;
+}
+
+export async function handleIntelligenceConnect({
+  runtime,
+  request,
+  threadId,
+  lastSeenEventId,
+}: HandleIntelligenceConnectParams): Promise<Response> {
+  if (!runtime.intelligence) {
+    return Response.json(
+      {
+        error: "Intelligence not configured",
+        message: "Intelligence mode requires a CopilotKitIntelligence",
+      },
+      { status: 500 },
+    );
+  }
+
+  try {
+    const user = await resolveIntelligenceUser({ runtime, request });
+    if (isHandlerResponse(user)) {
+      return user;
+    }
+
+    const result = await runtime.intelligence.ɵconnectThread({
+      threadId,
+      userId: user.id,
+      lastSeenEventId,
+    });
+
+    if (result === null) {
+      return new Response(null, {
+        status: 204,
+      });
+    }
+
+    return Response.json(result, {
+      headers: { "Cache-Control": "no-cache", Connection: "keep-alive" },
+    });
+  } catch (error) {
+    if (isPlatformNotFoundError(error)) {
+      return new Response(null, {
+        status: 204,
+      });
+    }
+
+    console.error("Connect plan not available:", error);
+    return Response.json(
+      {
+        error: "Connect plan not available",
+      },
+      { status: 404 },
+    );
+  }
+}

package/src/v2/runtime/handlers/intelligence/run.ts

@@ -0,0 +1,152 @@
+import { AbstractAgent, Message, RunAgentInput } from "@ag-ui/client";
+import { CopilotIntelligenceRuntimeLike } from "../../runtime";
+import { generateThreadNameForNewThread } from "./thread-names";
+import { logger } from "@copilotkit/shared";
+import { telemetry } from "../../telemetry";
+import { resolveIntelligenceUser } from "../shared/resolve-intelligence-user";
+import { isHandlerResponse } from "../shared/json-response";
+
+interface HandleIntelligenceRunParams {
+  runtime: CopilotIntelligenceRuntimeLike;
+  request: Request;
+  agentId: string;
+  agent: AbstractAgent;
+  input: RunAgentInput;
+}
+
+export async function handleIntelligenceRun({
+  runtime,
+  request,
+  agentId,
+  agent,
+  input,
+}: HandleIntelligenceRunParams): Promise<Response> {
+  if (!runtime.intelligence) {
+    return Response.json(
+      {
+        error: "Intelligence not configured",
+        message: "Intelligence mode requires a CopilotKitIntelligence",
+      },
+      { status: 500 },
+    );
+  }
+
+  const user = await resolveIntelligenceUser({ runtime, request });
+  if (isHandlerResponse(user)) {
+    return user;
+  }
+  const userId = user.id;
+
+  try {
+    const { thread, created } = await runtime.intelligence.getOrCreateThread({
+      threadId: input.threadId,
+      userId,
+      agentId,
+    });
+
+    if (created && runtime.generateThreadNames && !thread.name?.trim()) {
+      void generateThreadNameForNewThread({
+        runtime,
+        request,
+        agentId,
+        sourceInput: input,
+        thread,
+        userId,
+      }).catch((nameError) => {
+        logger.error("Failed to generate thread name:", nameError);
+      });
+    }
+  } catch (error) {
+    logger.error("Failed to get or create thread:", error);
+    return Response.json(
+      {
+        error: "Failed to initialize thread",
+      },
+      { status: 502 },
+    );
+  }
+
+  let joinCode: string | undefined;
+  let joinToken: string | undefined;
+  try {
+    const lockResult = await runtime.intelligence.ɵacquireThreadLock({
+      threadId: input.threadId,
+      runId: input.runId,
+      userId,
+    });
+    joinToken = lockResult.joinToken;
+    joinCode = lockResult.joinCode;
+  } catch (error) {
+    logger.error("Thread lock denied:", error);
+    return Response.json(
+      {
+        error: "Thread lock denied",
+      },
+      { status: 409 },
+    );
+  }
+
+  if (!joinToken) {
+    return Response.json(
+      {
+        error: "Join token not available",
+        message: "Intelligence platform did not return a join token",
+      },
+      { status: 502 },
+    );
+  }
+
+  let persistedInputMessages: Message[] | undefined;
+  if (Array.isArray(input.messages)) {
+    try {
+      const history = await runtime.intelligence.getThreadMessages({
+        threadId: input.threadId,
+      });
+      const historicMessageIds = new Set(
+        history.messages.map((message) => message.id),
+      );
+      persistedInputMessages = input.messages.filter(
+        (message) => !historicMessageIds.has(message.id),
+      );
+    } catch (error) {
+      logger.error("Thread history lookup failed:", error);
+      return Response.json(
+        {
+          error: "Thread history lookup failed",
+        },
+        { status: 502 },
+      );
+    }
+  }
+
+  telemetry.capture("oss.runtime.agent_execution_stream_started", {});
+
+  runtime.runner
+    .run({
+      threadId: input.threadId,
+      agent,
+      input,
+      ...(persistedInputMessages !== undefined
+        ? { persistedInputMessages }
+        : {}),
+      ...(joinCode ? { joinCode } : {}),
+    })
+    .subscribe({
+      error: (error) => {
+        telemetry.capture("oss.runtime.agent_execution_stream_errored", {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        logger.error("Error running agent:", error);
+      },
+      complete: () => {
+        telemetry.capture("oss.runtime.agent_execution_stream_ended", {});
+      },
+    });
+
+  return Response.json(
+    { joinToken },
+    {
+      headers: { "Cache-Control": "no-cache" },
+    },
+  );
+}