@copilotkit/runtime 1.56.5 → 1.57.0

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/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/intelligence-platform/client.ts

@@ -198,6 +198,40 @@ export interface ThreadMessagesResponse {
   messages: ThreadMessage[];
 }
 
+/**
+ * Persisted AG-UI event for the inspector's debugging views. The platform
+ * stores raw events keyed by run; the `_inspect` route returns them in
+ * replay order (oldest first) across every run that targeted the thread.
+ */
+export interface ThreadInspectEvent {
+  type: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Response from {@link CopilotKitIntelligence.getThreadEvents}. Mirrors the
+ * `ThreadEventsResult` shape returned by the platform's
+ * `GET /api/_inspect/threads/:id/events` endpoint.
+ */
+export interface ThreadEventsResponse {
+  events: ThreadInspectEvent[];
+  /** Row IDs the platform failed to decode (raw column corrupted). */
+  decodeErrorRowIds: string[];
+  /** True when the platform hit its per-thread event cap. */
+  truncated: boolean;
+}
+
+/**
+ * Response from {@link CopilotKitIntelligence.getThreadState}. Mirrors the
+ * discriminated `ThreadStateResult` returned by the platform's
+ * `GET /api/_inspect/threads/:id/state` endpoint, which folds RFC 6902
+ * STATE_DELTA events on top of the latest STATE_SNAPSHOT.
+ */
+export type ThreadStateResponse =
+  | { kind: "no-snapshot" }
+  | { kind: "snapshot-decode-error" }
+  | { kind: "snapshot"; state: unknown; skippedDeltas: number };
+
 export interface AcquireThreadLockRequest {
   threadId: string;
   runId: string;
@@ -556,6 +590,48 @@ export class CopilotKitIntelligence {
     );
   }
 
+  /**
+   * Fetch the persisted AG-UI event stream for a thread.
+   *
+   * Backed by the platform's `GET /api/_inspect/threads/:id/events`
+   * introspection endpoint (see Intelligence PR #144). Events are returned
+   * in replay order across every run that targeted the thread. The
+   * `_inspect/` prefix flags this as debug-only — production code paths
+   * must not depend on it.
+   *
+   * @throws {@link PlatformRequestError} on non-2xx responses.
+   */
+  async getThreadEvents(params: {
+    threadId: string;
+  }): Promise<ThreadEventsResponse> {
+    return this.#request<ThreadEventsResponse>(
+      "GET",
+      `/api/_inspect/threads/${encodeURIComponent(params.threadId)}/events`,
+    );
+  }
+
+  /**
+   * Fetch the current agent state for a thread.
+   *
+   * Backed by the platform's `GET /api/_inspect/threads/:id/state`
+   * introspection endpoint (see Intelligence PR #144). The platform folds
+   * RFC 6902 STATE_DELTA events on top of the latest STATE_SNAPSHOT, so
+   * the returned state reflects the thread's current state — not just the
+   * last snapshot. The discriminated response distinguishes "no snapshot
+   * persisted yet" from "snapshot present" so consumers can render the
+   * correct empty state.
+   *
+   * @throws {@link PlatformRequestError} on non-2xx responses.
+   */
+  async getThreadState(params: {
+    threadId: string;
+  }): Promise<ThreadStateResponse> {
+    return this.#request<ThreadStateResponse>(
+      "GET",
+      `/api/_inspect/threads/${encodeURIComponent(params.threadId)}/state`,
+    );
+  }
+
   /**
    * Mark a thread as archived.
    *