@copilotkit/runtime 1.54.1 → 1.55.0-next.8

package/src/v2/runtime/handlers/intelligence/thread-names.ts

@@ -0,0 +1,246 @@
+import { AbstractAgent, Message, RunAgentInput } from "@ag-ui/client";
+import { logger } from "@copilotkit/shared";
+import { randomUUID } from "node:crypto";
+import { CopilotIntelligenceRuntimeLike } from "../../runtime";
+import {
+  cloneAgentForRequest,
+  configureAgentForRequest,
+} from "../shared/agent-utils";
+import { ThreadSummary } from "../../intelligence-platform";
+import { isHandlerResponse } from "../shared/json-response";
+
+const THREAD_NAME_SYSTEM_PROMPT = [
+  "You generate short, specific conversation titles.",
+  'Return JSON only in this exact shape: {"title":"..."}',
+  "The title must be 2 to 5 words.",
+  "Use sentence case.",
+  "No quotes.",
+  "No emoji.",
+  "No markdown characters or formatting.",
+  "Do not use *, _, #, `, [, ], (, ), !, ~, >, or |.",
+  "No trailing punctuation.",
+  "No explanations.",
+  "Do not call tools.",
+].join("\n");
+
+const MAX_TITLE_LENGTH = 80;
+const MAX_TITLE_WORDS = 8;
+const MAX_TRANSCRIPT_MESSAGES = 8;
+const MAX_TITLE_GENERATION_ATTEMPTS = 3;
+const FALLBACK_THREAD_TITLE = "Untitled";
+
+interface GenerateThreadNameParams {
+  runtime: CopilotIntelligenceRuntimeLike;
+  request: Request;
+  agentId: string;
+  sourceInput: RunAgentInput;
+  thread: ThreadSummary;
+  userId: string;
+}
+
+export async function generateThreadNameForNewThread({
+  runtime,
+  request,
+  agentId,
+  sourceInput,
+  thread,
+  userId,
+}: GenerateThreadNameParams): Promise<void> {
+  if (!runtime.generateThreadNames || hasThreadName(thread.name)) {
+    return;
+  }
+
+  const prompt = buildThreadTitlePrompt(sourceInput.messages);
+  if (!prompt) {
+    return;
+  }
+
+  let generatedTitle: string | null = null;
+
+  for (let attempt = 1; attempt <= MAX_TITLE_GENERATION_ATTEMPTS; attempt++) {
+    try {
+      generatedTitle = await runTitleGenerationAttempt({
+        runtime,
+        request,
+        agentId,
+        threadId: thread.id,
+        prompt,
+      });
+
+      if (generatedTitle) {
+        break;
+      }
+
+      logger.warn(
+        { agentId, attempt, threadId: thread.id },
+        "Thread name generation returned an empty or invalid title",
+      );
+    } catch (error) {
+      logger.warn(
+        { err: error, agentId, attempt, threadId: thread.id },
+        "Thread name generation attempt failed",
+      );
+    }
+  }
+
+  await runtime.intelligence.updateThread({
+    threadId: thread.id,
+    userId,
+    agentId,
+    updates: { name: generatedTitle ?? FALLBACK_THREAD_TITLE },
+  });
+}
+
+async function runTitleGenerationAttempt(params: {
+  runtime: CopilotIntelligenceRuntimeLike;
+  request: Request;
+  agentId: string;
+  threadId: string;
+  prompt: string;
+}): Promise<string | null> {
+  const { runtime, request, agentId, threadId, prompt } = params;
+  const agent = await cloneAgentForRequest(runtime, agentId);
+  if (isHandlerResponse(agent)) {
+    logger.warn(
+      { agentId, threadId },
+      "Skipping thread naming because the agent could not be cloned",
+    );
+    return null;
+  }
+
+  configureAgentForRequest({
+    runtime,
+    request,
+    agentId,
+    agent,
+  });
+
+  const messages: Message[] = [
+    {
+      id: randomUUID(),
+      role: "system",
+      content: THREAD_NAME_SYSTEM_PROMPT,
+    },
+    {
+      id: randomUUID(),
+      role: "user",
+      content: prompt,
+    },
+  ];
+
+  agent.setMessages(messages);
+  agent.setState({});
+  agent.threadId = `thread-name:${threadId}:${randomUUID()}`;
+  const { newMessages } = await agent.runAgent({
+    messages,
+    state: {},
+    tools: [],
+    context: [],
+    forwardedProps: {},
+  });
+
+  const lastMessage = newMessages.at(-1);
+  const titleContent = lastMessage
+    ? stringifyMessageContent(lastMessage.content)
+    : "";
+
+  return normalizeGeneratedTitle(titleContent);
+}
+
+function buildThreadTitlePrompt(
+  messages: Message[] | undefined,
+): string | null {
+  const transcript = (messages ?? [])
+    .filter((message) =>
+      ["user", "assistant", "system", "developer"].includes(message.role),
+    )
+    .map((message) => {
+      const content = stringifyMessageContent(message.content);
+      if (!content) {
+        return null;
+      }
+
+      return `${message.role}: ${content}`;
+    })
+    .filter((message): message is string => !!message)
+    .slice(-MAX_TRANSCRIPT_MESSAGES);
+
+  if (transcript.length === 0) {
+    return null;
+  }
+
+  return [
+    "Generate a short title for this conversation.",
+    "Conversation:",
+    transcript.join("\n"),
+  ].join("\n\n");
+}
+
+function stringifyMessageContent(content: Message["content"]): string {
+  if (typeof content === "string") {
+    return content.trim();
+  }
+
+  if (content == null) {
+    return "";
+  }
+
+  try {
+    return JSON.stringify(content).trim();
+  } catch {
+    return "";
+  }
+}
+
+function normalizeGeneratedTitle(rawTitle: string): string | null {
+  let candidate = rawTitle.trim();
+  if (!candidate) {
+    return null;
+  }
+
+  candidate = candidate
+    .replace(/^```(?:json)?\s*/i, "")
+    .replace(/\s*```$/, "")
+    .trim();
+
+  try {
+    const parsed = JSON.parse(candidate) as { title?: unknown };
+    if (typeof parsed.title === "string") {
+      candidate = parsed.title;
+    }
+  } catch {
+    // Fall back to using the raw text.
+  }
+
+  candidate = candidate
+    .replace(/^["'`]+|["'`]+$/g, "")
+    .replace(/[*_#[\]()!~>|]+/g, "")
+    .replace(/[.!?,;:]+$/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+
+  if (!candidate) {
+    return null;
+  }
+
+  if (candidate.length > MAX_TITLE_LENGTH) {
+    candidate = candidate.slice(0, MAX_TITLE_LENGTH).trim();
+  }
+
+  if (candidate.split(/\s+/).length > MAX_TITLE_WORDS) {
+    return null;
+  }
+
+  return candidate;
+}
+
+function hasThreadName(name: string | null | undefined): boolean {
+  return typeof name === "string" && name.trim().length > 0;
+}
+
+/** @internal Exported for testing only. */
+export const ɵnormalizeGeneratedTitle = normalizeGeneratedTitle;
+/** @internal Exported for testing only. */
+export const ɵbuildThreadTitlePrompt = buildThreadTitlePrompt;
+/** @internal Exported for testing only. */
+export const ɵhasThreadName = hasThreadName;

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

@@ -0,0 +1,233 @@
+import {
+  CopilotIntelligenceRuntimeLike,
+  CopilotRuntimeLike,
+  isIntelligenceRuntime,
+} from "../../runtime";
+import { logger } from "@copilotkit/shared";
+import { errorResponse, isHandlerResponse } from "../shared/json-response";
+import { isValidIdentifier } from "../shared/intelligence-utils";
+import { resolveIntelligenceUser } from "../shared/resolve-intelligence-user";
+
+interface ThreadsHandlerParams {
+  runtime: CopilotRuntimeLike;
+  request: Request;
+}
+
+interface ThreadMutationParams extends ThreadsHandlerParams {
+  threadId: string;
+}
+
+interface ThreadMutationContext {
+  userId: string;
+  agentId: string;
+  body: Record<string, unknown>;
+}
+
+async function parseJsonBody(
+  request: Request,
+): Promise<Record<string, unknown> | Response> {
+  try {
+    return (await request.json()) as Record<string, unknown>;
+  } catch (error) {
+    logger.error({ err: error }, "Malformed JSON in request body");
+    return errorResponse("Invalid request body", 400);
+  }
+}
+
+function requireIntelligenceRuntime(
+  runtime: CopilotRuntimeLike,
+): CopilotIntelligenceRuntimeLike | Response {
+  if (!isIntelligenceRuntime(runtime)) {
+    return errorResponse(
+      "Missing CopilotKitIntelligence configuration. Thread operations require a CopilotKitIntelligence instance to be provided in CopilotRuntime options.",
+      422,
+    );
+  }
+
+  return runtime;
+}
+
+async function resolveThreadMutationContext(
+  runtime: CopilotIntelligenceRuntimeLike,
+  request: Request,
+): Promise<ThreadMutationContext | Response> {
+  const body = await parseJsonBody(request);
+  if (isHandlerResponse(body)) return body;
+
+  const user = await resolveIntelligenceUser({ runtime, request });
+  if (isHandlerResponse(user)) return user;
+
+  const agentId = body.agentId;
+  if (!isValidIdentifier(agentId)) {
+    return errorResponse("Valid agentId is required", 400);
+  }
+
+  return {
+    body,
+    userId: user.id,
+    agentId,
+  };
+}
+
+export async function handleListThreads({
+  runtime,
+  request,
+}: ThreadsHandlerParams): Promise<Response> {
+  const intelligenceRuntime = requireIntelligenceRuntime(runtime);
+  if (isHandlerResponse(intelligenceRuntime)) {
+    return intelligenceRuntime;
+  }
+
+  try {
+    const url = new URL(request.url);
+    const agentId = url.searchParams.get("agentId");
+    const includeArchived = url.searchParams.get("includeArchived") === "true";
+    const limitParam = url.searchParams.get("limit");
+    const cursor = url.searchParams.get("cursor");
+    const user = await resolveIntelligenceUser({
+      runtime: intelligenceRuntime,
+      request,
+    });
+    if (isHandlerResponse(user)) return user;
+
+    if (!isValidIdentifier(agentId)) {
+      return errorResponse("Valid agentId query param is required", 400);
+    }
+
+    const data = await intelligenceRuntime.intelligence.listThreads({
+      userId: user.id,
+      agentId,
+      ...(includeArchived ? { includeArchived: true } : {}),
+      ...(limitParam ? { limit: Number(limitParam) } : {}),
+      ...(cursor ? { cursor } : {}),
+    });
+
+    return Response.json(data);
+  } catch (error) {
+    logger.error({ err: error }, "Error listing threads");
+    return errorResponse("Failed to list threads", 500);
+  }
+}
+
+export async function handleUpdateThread({
+  runtime,
+  request,
+  threadId,
+}: ThreadMutationParams): Promise<Response> {
+  const intelligenceRuntime = requireIntelligenceRuntime(runtime);
+  if (isHandlerResponse(intelligenceRuntime)) {
+    return intelligenceRuntime;
+  }
+
+  try {
+    const mutation = await resolveThreadMutationContext(
+      intelligenceRuntime,
+      request,
+    );
+    if (isHandlerResponse(mutation)) return mutation;
+
+    const updates = { ...mutation.body };
+    delete updates.agentId;
+    delete updates.userId;
+
+    const thread = await intelligenceRuntime.intelligence.updateThread({
+      threadId,
+      userId: mutation.userId,
+      agentId: mutation.agentId,
+      updates,
+    });
+
+    return Response.json(thread);
+  } catch (error) {
+    logger.error({ err: error, threadId }, "Error updating thread");
+    return errorResponse("Failed to update thread", 500);
+  }
+}
+
+export async function handleSubscribeToThreads({
+  runtime,
+  request,
+}: ThreadsHandlerParams): Promise<Response> {
+  const intelligenceRuntime = requireIntelligenceRuntime(runtime);
+  if (isHandlerResponse(intelligenceRuntime)) {
+    return intelligenceRuntime;
+  }
+
+  try {
+    const user = await resolveIntelligenceUser({
+      runtime: intelligenceRuntime,
+      request,
+    });
+    if (isHandlerResponse(user)) return user;
+
+    const credentials =
+      await intelligenceRuntime.intelligence.ɵsubscribeToThreads({
+        userId: user.id,
+      });
+
+    return Response.json({ joinToken: credentials.joinToken });
+  } catch (error) {
+    logger.error({ err: error }, "Error subscribing to threads");
+    return errorResponse("Failed to subscribe to threads", 500);
+  }
+}
+
+export async function handleArchiveThread({
+  runtime,
+  request,
+  threadId,
+}: ThreadMutationParams): Promise<Response> {
+  const intelligenceRuntime = requireIntelligenceRuntime(runtime);
+  if (isHandlerResponse(intelligenceRuntime)) {
+    return intelligenceRuntime;
+  }
+
+  try {
+    const mutation = await resolveThreadMutationContext(
+      intelligenceRuntime,
+      request,
+    );
+    if (isHandlerResponse(mutation)) return mutation;
+
+    await intelligenceRuntime.intelligence.archiveThread({
+      threadId,
+      userId: mutation.userId,
+      agentId: mutation.agentId,
+    });
+
+    return Response.json({ threadId, archived: true });
+  } catch (error) {
+    logger.error({ err: error, threadId }, "Error archiving thread");
+    return errorResponse("Failed to archive thread", 500);
+  }
+}
+
+export async function handleDeleteThread({
+  runtime,
+  request,
+  threadId,
+}: ThreadMutationParams): Promise<Response> {
+  const intelligenceRuntime = requireIntelligenceRuntime(runtime);
+  if (isHandlerResponse(intelligenceRuntime)) {
+    return intelligenceRuntime;
+  }
+
+  try {
+    const mutation = await resolveThreadMutationContext(
+      intelligenceRuntime,
+      request,
+    );
+    if (isHandlerResponse(mutation)) return mutation;
+
+    await intelligenceRuntime.intelligence.deleteThread({
+      threadId,
+      userId: mutation.userId,
+      agentId: mutation.agentId,
+    });
+
+    return Response.json({ threadId, deleted: true });
+  } catch (error) {
+    logger.error({ err: error, threadId }, "Error deleting thread");
+    return errorResponse("Failed to delete thread", 500);
+  }
+}

package/src/v2/runtime/handlers/shared/agent-utils.ts

@@ -0,0 +1,136 @@
+import {
+  AbstractAgent,
+  RunAgentInput,
+  RunAgentInputSchema,
+} from "@ag-ui/client";
+import { A2UIMiddleware } from "@ag-ui/a2ui-middleware";
+import { MCPAppsMiddleware } from "@ag-ui/mcp-apps-middleware";
+import { CopilotRuntimeLike } from "../../runtime";
+import { extractForwardableHeaders } from "../header-utils";
+import { logger } from "@copilotkit/shared";
+
+type MiddlewareCapableAgent = AbstractAgent & {
+  use?: (middleware: unknown) => void;
+  headers?: Record<string, string>;
+};
+
+export interface RunAgentParameters {
+  request: Request;
+  runtime: CopilotRuntimeLike;
+  agentId: string;
+}
+
+export interface ConnectRequestBody extends RunAgentInput {
+  lastSeenEventId?: string | null;
+}
+
+export async function cloneAgentForRequest(
+  runtime: CopilotRuntimeLike,
+  agentId: string,
+): Promise<AbstractAgent | Response> {
+  const agents = await runtime.agents;
+
+  if (!agents[agentId]) {
+    return Response.json(
+      {
+        error: "Agent not found",
+        message: `Agent '${agentId}' does not exist`,
+      },
+      { status: 404 },
+    );
+  }
+
+  return (agents[agentId] as AbstractAgent).clone() as AbstractAgent;
+}
+
+export function configureAgentForRequest(params: {
+  runtime: CopilotRuntimeLike;
+  request: Request;
+  agentId: string;
+  agent: AbstractAgent;
+}): void {
+  const { runtime, request, agentId } = params;
+  const agent = params.agent as MiddlewareCapableAgent;
+
+  if (runtime.a2ui) {
+    const { agents: targetAgents, ...a2uiOptions } = runtime.a2ui;
+    const shouldApply = !targetAgents || targetAgents.includes(agentId);
+    if (shouldApply && typeof agent.use === "function") {
+      agent.use(new A2UIMiddleware(a2uiOptions));
+    }
+  }
+
+  if (runtime.mcpApps?.servers?.length) {
+    const mcpServers = runtime.mcpApps.servers
+      .filter((server) => !server.agentId || server.agentId === agentId)
+      .map((server) => {
+        const mcpServer = { ...server };
+        delete mcpServer.agentId;
+        return mcpServer;
+      });
+
+    if (mcpServers.length > 0 && typeof agent.use === "function") {
+      agent.use(new MCPAppsMiddleware({ mcpServers }));
+    }
+  }
+
+  if (agent.headers) {
+    agent.headers = {
+      ...agent.headers,
+      ...extractForwardableHeaders(request),
+    };
+  }
+}
+
+export async function parseRunRequest(
+  request: Request,
+): Promise<RunAgentInput | Response> {
+  try {
+    const requestBody = await request.json();
+    return RunAgentInputSchema.parse(requestBody);
+  } catch (error) {
+    logger.error("Invalid run request body:", error);
+    return Response.json(
+      {
+        error: "Invalid request body",
+        details: error instanceof Error ? error.message : String(error),
+      },
+      { status: 400 },
+    );
+  }
+}
+
+export async function parseConnectRequest(request: Request): Promise<
+  | Response
+  | {
+      input: RunAgentInput;
+      lastSeenEventId: string | null;
+    }
+> {
+  try {
+    const requestBody = await request.json();
+    const input = RunAgentInputSchema.parse(requestBody);
+    let lastSeenEventId: string | null = null;
+
+    if (
+      "lastSeenEventId" in (requestBody as Record<string, unknown>) &&
+      (typeof (requestBody as Record<string, unknown>).lastSeenEventId ===
+        "string" ||
+        (requestBody as Record<string, unknown>).lastSeenEventId === null)
+    ) {
+      lastSeenEventId =
+        (requestBody as ConnectRequestBody).lastSeenEventId ?? null;
+    }
+
+    return { input, lastSeenEventId };
+  } catch (error) {
+    logger.error("Invalid connect request body:", error);
+    return Response.json(
+      {
+        error: "Invalid request body",
+        details: error instanceof Error ? error.message : String(error),
+      },
+      { status: 400 },
+    );
+  }
+}

package/src/v2/runtime/handlers/shared/intelligence-utils.ts

@@ -0,0 +1,21 @@
+import { PlatformRequestError } from "../../intelligence-platform/client";
+
+export function isPlatformNotFoundError(error: unknown): boolean {
+  return error instanceof PlatformRequestError && error.status === 404;
+}
+
+const MAX_ID_LENGTH = 128;
+const SAFE_ID_PATTERN = /^[\w.@:=-]+$/;
+
+/**
+ * Validates that a string identifier (userId, agentId) is safe to pass through.
+ * Returns `true` if valid, `false` otherwise.
+ */
+export function isValidIdentifier(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= MAX_ID_LENGTH &&
+    SAFE_ID_PATTERN.test(value)
+  );
+}

package/src/v2/runtime/handlers/shared/json-response.ts

@@ -0,0 +1,6 @@
+export const errorResponse = (message: string, status: number) =>
+  Response.json({ error: message }, { status });
+
+export function isHandlerResponse(value: unknown): value is Response {
+  return value instanceof Response;
+}

package/src/v2/runtime/handlers/shared/resolve-intelligence-user.ts

@@ -0,0 +1,25 @@
+import {
+  CopilotIntelligenceRuntimeLike,
+  CopilotRuntimeUser,
+} from "../../runtime";
+import { errorResponse } from "./json-response";
+import { isValidIdentifier } from "./intelligence-utils";
+
+export async function resolveIntelligenceUser(params: {
+  runtime: CopilotIntelligenceRuntimeLike;
+  request: Request;
+}): Promise<CopilotRuntimeUser | Response> {
+  const { runtime, request } = params;
+
+  try {
+    const user = await runtime.identifyUser(request);
+    if (!isValidIdentifier(user?.id)) {
+      return errorResponse("identifyUser must return a valid user id", 400);
+    }
+
+    return { id: user.id };
+  } catch (error) {
+    console.error("Error identifying intelligence user:", error);
+    return errorResponse("Failed to identify user", 500);
+  }
+}