@copilotkit/runtime 1.56.5 → 1.57.0-canary.1778078321

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

@@ -48,12 +48,15 @@ import { handleGetRuntimeInfo } from "../handlers/get-runtime-info";
 import { handleTranscribe } from "../handlers/handle-transcribe";
 import { handleDebugEvents } from "../handlers/handle-debug-events";
 import {
+  handleClearThreads,
   handleListThreads,
   handleSubscribeToThreads,
   handleUpdateThread,
   handleArchiveThread,
   handleDeleteThread,
   handleGetThreadMessages,
+  handleGetThreadEvents,
+  handleGetThreadState,
 } from "../handlers/handle-threads";
 import {
   parseMethodCall,
@@ -318,6 +321,8 @@ function dispatchRoute(
       return handleGetRuntimeInfo({ runtime, request });
     case "transcribe":
       return handleTranscribe({ runtime, request });
+    case "threads/clear":
+      return Promise.resolve(handleClearThreads({ runtime, request }));
     case "threads/list":
       return handleListThreads({ runtime, request });
     case "threads/subscribe":
@@ -343,6 +348,18 @@ function dispatchRoute(
         request,
         threadId: route.threadId,
       });
+    case "threads/events":
+      return handleGetThreadEvents({
+        runtime,
+        request,
+        threadId: route.threadId,
+      });
+    case "threads/state":
+      return handleGetThreadState({
+        runtime,
+        request,
+        threadId: route.threadId,
+      });
     case "cpk-debug-events":
       return Promise.resolve(handleDebugEvents({ runtime, request }));
   }
@@ -420,6 +437,8 @@ function validateHttpMethod(
     case "info":
     case "threads/list":
     case "threads/messages":
+    case "threads/events":
+    case "threads/state":
     case "cpk-debug-events":
       if (method === "GET") return null;
       return jsonResponse({ error: "Method not allowed" }, 405, {

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

@@ -139,6 +139,28 @@ function matchSegments(path: string): RouteInfo | 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 &&
@@ -150,11 +172,21 @@ function matchSegments(path: string): RouteInfo | 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] !== "subscribe" &&
+    segments[len - 1] !== "clear"
   ) {
     const threadId = safeDecodeURIComponent(segments[len - 1]!);
     if (!threadId) return null;

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

@@ -44,6 +44,9 @@ export type RouteInfo =
   | { 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" };
 
 /* ------------------------------------------------------------------------------------------------

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

@@ -35,6 +35,10 @@ export async function handleRunAgent({
       return agent;
     }
 
+    // Ensure the clone carries the registry key so InMemoryAgentRunner can
+    // tag historic runs with the correct agentId for filtering.
+    agent.agentId = agentId;
+
     configureAgentForRequest({ runtime, request, agentId, agent });
 
     if (

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

@@ -1,7 +1,10 @@
 export {
   handleArchiveThread,
+  handleClearThreads,
   handleDeleteThread,
+  handleGetThreadEvents,
   handleGetThreadMessages,
+  handleGetThreadState,
   handleListThreads,
   handleSubscribeToThreads,
   handleUpdateThread,

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

@@ -1,18 +1,18 @@
-import {
+import type {
   AbstractAgent,
   BaseEvent,
-  EventType,
   Message,
   RunAgentInput,
 } from "@ag-ui/client";
-import { CopilotIntelligenceRuntimeLike } from "../../core/runtime";
+import { EventType } from "@ag-ui/client";
+import type { CopilotIntelligenceRuntimeLike } from "../../core/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";
-import { AgentRunnerRunRequest } from "../../runner/agent-runner";
-import { Observable } from "rxjs";
+import type { AgentRunnerRunRequest } from "../../runner/agent-runner";
+import type { Observable } from "rxjs";
 
 /**
  * Builds browser-facing realtime connection metadata owned by the runtime.
@@ -161,10 +161,32 @@ export async function handleIntelligenceRun({
     );
   }
 
+  // When Intelligence has `mcpServer: true`, hand the agent the per-request
+  // bits it needs to attach the platform's MCP server: the resolved user-id,
+  // the project Bearer (`apiKey`), and the MCP URL. These ride through
+  // `forwardedProps.copilotkitIntelligence` so the agent doesn't need a
+  // typed reference to the Intelligence client. `BuiltInAgent` reads the
+  // bag and builds a per-request MCP config with a closure-baked fetch;
+  // non-BuiltInAgent agents naturally ignore the key.
+  const copilotkitIntelligenceProps =
+    runtime.intelligence.ɵisMcpServerEnabled?.()
+      ? {
+          copilotkitIntelligence: {
+            userId,
+            apiKey: runtime.intelligence.ɵgetApiKey(),
+            mcpUrl: `${runtime.intelligence.ɵgetApiUrl()}/mcp`,
+          },
+        }
+      : {};
+
   const canonicalInput: RunAgentInput = {
     ...input,
     threadId: canonicalThreadId,
     runId: canonicalRunId,
+    forwardedProps: {
+      ...input.forwardedProps,
+      ...copilotkitIntelligenceProps,
+    },
   };
 
   let persistedInputMessages: Message[] | undefined;

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

@@ -7,6 +7,7 @@ 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";
+import { InMemoryAgentRunner } from "../../runner/in-memory";
 
 interface ThreadsHandlerParams {
   runtime: CopilotRuntimeLike;
@@ -73,40 +74,70 @@ export async function handleListThreads({
   runtime,
   request,
 }: ThreadsHandlerParams): Promise<Response> {
-  const intelligenceRuntime = requireIntelligenceRuntime(runtime);
-  if (isHandlerResponse(intelligenceRuntime)) {
-    return intelligenceRuntime;
+  // Intelligence platform path
+  if (isIntelligenceRuntime(runtime)) {
+    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, request });
+      if (isHandlerResponse(user)) return user;
+
+      if (!isValidIdentifier(agentId)) {
+        return errorResponse("Valid agentId query param is required", 400);
+      }
+
+      const data = await runtime.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);
+    }
   }
 
-  try {
+  // Local in-memory fallback — useful for local development without Intelligence
+  if (runtime.runner instanceof InMemoryAgentRunner) {
     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);
+    let threads = runtime.runner.listThreads();
+    if (agentId) {
+      threads = threads.filter((t) => t.agentId === agentId);
     }
+    return Response.json({ threads, nextCursor: null });
+  }
 
-    const data = await intelligenceRuntime.intelligence.listThreads({
-      userId: user.id,
-      agentId,
-      ...(includeArchived ? { includeArchived: true } : {}),
-      ...(limitParam ? { limit: Number(limitParam) } : {}),
-      ...(cursor ? { cursor } : {}),
-    });
+  return errorResponse(
+    "Missing CopilotKitIntelligence configuration. Thread operations require a CopilotKitIntelligence instance to be provided in CopilotRuntime options.",
+    422,
+  );
+}
 
-    return Response.json(data);
-  } catch (error) {
-    logger.error({ err: error }, "Error listing threads");
-    return errorResponse("Failed to list threads", 500);
+/**
+ * Clears all in-memory thread history for the local-dev InMemory fallback.
+ *
+ * The local-dev fallback exposes this so consumers (e.g. the demo's Clear
+ * button) can wipe in-memory thread history without restarting the runtime.
+ * Intentionally a no-op when the Intelligence platform is configured: real
+ * thread history lives in the database and must not be wiped by a
+ * client-side page load.
+ */
+export function handleClearThreads({
+  runtime,
+}: ThreadsHandlerParams): Response {
+  if (runtime.runner instanceof InMemoryAgentRunner) {
+    runtime.runner.clearThreads();
   }
+  return new Response(null, { status: 204 });
 }
 
 export async function handleUpdateThread({
@@ -237,25 +268,153 @@ export async function handleGetThreadMessages({
   request,
   threadId,
 }: ThreadMutationParams): Promise<Response> {
-  const intelligenceRuntime = requireIntelligenceRuntime(runtime);
-  if (isHandlerResponse(intelligenceRuntime)) {
-    return intelligenceRuntime;
+  // Intelligence platform path
+  if (isIntelligenceRuntime(runtime)) {
+    try {
+      const user = await resolveIntelligenceUser({ runtime, request });
+      if (isHandlerResponse(user)) return user;
+
+      const data = await runtime.intelligence.getThreadMessages({ threadId });
+      return Response.json(data);
+    } catch (error) {
+      logger.error({ err: error, threadId }, "Error fetching thread messages");
+      return errorResponse("Failed to fetch thread messages", 500);
+    }
   }
 
-  try {
-    const user = await resolveIntelligenceUser({
-      runtime: intelligenceRuntime,
-      request,
+  // Local in-memory fallback — useful for local development without Intelligence
+  if (runtime.runner instanceof InMemoryAgentRunner) {
+    const messages = runtime.runner.getThreadMessages(threadId);
+    // Map ag-ui Message objects to the same shape the Intelligence platform
+    // returns. Switching on the discriminant `role` lets each branch read
+    // the narrowed message arm directly, instead of laundering through
+    // `Record<string, unknown>` and chained `as` casts.
+    const mapped = messages.map((msg) => {
+      switch (msg.role) {
+        case "assistant": {
+          const toolCalls = msg.toolCalls ?? [];
+          return {
+            id: msg.id,
+            role: msg.role,
+            ...(msg.content !== undefined ? { content: msg.content } : {}),
+            ...(toolCalls.length > 0
+              ? {
+                  toolCalls: toolCalls.map((tc) => ({
+                    id: tc.id,
+                    name: tc.function.name,
+                    args: tc.function.arguments,
+                  })),
+                }
+              : {}),
+          };
+        }
+        case "tool":
+          return {
+            id: msg.id,
+            role: msg.role,
+            content: msg.content,
+            toolCallId: msg.toolCallId,
+          };
+        default:
+          return {
+            id: msg.id,
+            role: msg.role,
+            ...("content" in msg && msg.content !== undefined
+              ? { content: msg.content }
+              : {}),
+          };
+      }
     });
-    if (isHandlerResponse(user)) return user;
+    return Response.json({ messages: mapped });
+  }
 
-    const data = await intelligenceRuntime.intelligence.getThreadMessages({
-      threadId,
-    });
+  return errorResponse(
+    "Missing CopilotKitIntelligence configuration. Thread operations require a CopilotKitIntelligence instance to be provided in CopilotRuntime options.",
+    422,
+  );
+}
 
-    return Response.json(data);
-  } catch (error) {
-    logger.error({ err: error, threadId }, "Error getting thread messages");
-    return errorResponse("Failed to get thread messages", 500);
+export async function handleGetThreadEvents({
+  runtime,
+  request,
+  threadId,
+}: ThreadMutationParams): Promise<Response> {
+  // Intelligence platform path. Delegates to the platform's `_inspect`
+  // endpoint (Intelligence PR #144). Auth still flows through the standard
+  // identifyUser → API key path; threadId scoping happens server-side.
+  if (isIntelligenceRuntime(runtime)) {
+    try {
+      const user = await resolveIntelligenceUser({ runtime, request });
+      if (isHandlerResponse(user)) return user;
+
+      const data = await runtime.intelligence.getThreadEvents({ threadId });
+      // Strip platform-internal fields (`decodeErrorRowIds`, `truncated`)
+      // before returning to the inspector — those describe persistence-side
+      // concerns the inspector currently has no UI for. The shape becomes
+      // `{ events }`, matching the in-memory branch below.
+      return Response.json({ events: data.events });
+    } catch (error) {
+      logger.error({ err: error, threadId }, "Error fetching thread events");
+      return errorResponse("Failed to fetch thread events", 500);
+    }
+  }
+
+  // Local in-memory fallback
+  if (runtime.runner instanceof InMemoryAgentRunner) {
+    try {
+      const events = runtime.runner.getThreadEvents(threadId);
+      return Response.json({ events });
+    } catch (error) {
+      logger.error({ err: error, threadId }, "Error fetching thread events");
+      return errorResponse("Failed to fetch thread events", 500);
+    }
   }
+
+  return errorResponse(
+    "Missing CopilotKitIntelligence configuration. Thread operations require a CopilotKitIntelligence instance to be provided in CopilotRuntime options.",
+    422,
+  );
+}
+
+export async function handleGetThreadState({
+  runtime,
+  request,
+  threadId,
+}: ThreadMutationParams): Promise<Response> {
+  // Intelligence platform path. Delegates to the platform's `_inspect`
+  // state endpoint, which folds STATE_DELTA events onto the latest
+  // STATE_SNAPSHOT to return the thread's current state.
+  if (isIntelligenceRuntime(runtime)) {
+    try {
+      const user = await resolveIntelligenceUser({ runtime, request });
+      if (isHandlerResponse(user)) return user;
+
+      const data = await runtime.intelligence.getThreadState({ threadId });
+      // Flatten the discriminated `ThreadStateResult` to the wire shape the
+      // inspector consumes (`{ state: <value> | null }`). Missing snapshot
+      // and decode-error both surface as `null`; the inspector renders an
+      // empty state branch for null and the platform's decode-error case is
+      // already logged platform-side.
+      const state = data.kind === "snapshot" ? data.state : null;
+      return Response.json({ state });
+    } catch (error) {
+      logger.error({ err: error, threadId }, "Error fetching thread state");
+      return errorResponse("Failed to fetch thread state", 500);
+    }
+  }
+
+  if (runtime.runner instanceof InMemoryAgentRunner) {
+    try {
+      const state = runtime.runner.getThreadState(threadId);
+      return Response.json({ state });
+    } catch (error) {
+      logger.error({ err: error, threadId }, "Error fetching thread state");
+      return errorResponse("Failed to fetch thread state", 500);
+    }
+  }
+
+  return errorResponse(
+    "Missing CopilotKitIntelligence configuration. Thread operations require a CopilotKitIntelligence instance to be provided in CopilotRuntime options.",
+    422,
+  );
 }

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

@@ -1,11 +1,9 @@
-import {
-  AbstractAgent,
-  RunAgentInput,
-  RunAgentInputSchema,
-} from "@ag-ui/client";
+import type { AbstractAgent, RunAgentInput } from "@ag-ui/client";
+import { RunAgentInputSchema } from "@ag-ui/client";
 import { A2UIMiddleware } from "@ag-ui/a2ui-middleware";
 import { MCPAppsMiddleware } from "@ag-ui/mcp-apps-middleware";
-import { CopilotRuntimeLike, resolveAgents } from "../../core/runtime";
+import type { CopilotRuntimeLike } from "../../core/runtime";
+import { resolveAgents } from "../../core/runtime";
 import { OpenGenerativeUIMiddleware } from "../../open-generative-ui-middleware";
 import { extractForwardableHeaders } from "../header-utils";
 import { logger } from "@copilotkit/shared";

package/src/v2/runtime/index.ts

@@ -19,6 +19,11 @@ export {
   type UpdateThreadRequest,
 } from "./intelligence-platform";
 
+// Re-export `@ai-sdk/mcp` stable types so consumers don't need to depend on
+// it directly to type their MCP wiring. `MCPClient` is the value users pass
+// into `mcpClients`; `MCPTransport` is the contract for custom transports.
+export type { MCPClient, MCPTransport } from "@ai-sdk/mcp";
+
 // Export framework-agnostic fetch handler
 export { createCopilotRuntimeHandler } from "./core/fetch-handler";
 export type {