@copilotkit/runtime 1.56.5 → 1.57.0

package/src/v2/runtime/runner/__tests__/in-memory-runner.test.ts

@@ -1,9 +1,8 @@
 import { describe, it, expect, beforeEach } from "vitest";
 import { InMemoryAgentRunner } from "../in-memory";
-import {
-  AbstractAgent,
+import type { InMemoryThread } from "../in-memory";
+import type {
   BaseEvent,
-  EventType,
   Message,
   RunAgentInput,
   RunErrorEvent,
@@ -13,6 +12,7 @@ import {
   TextMessageStartEvent,
   ToolCallResultEvent,
 } from "@ag-ui/client";
+import { AbstractAgent, EventType } from "@ag-ui/client";
 import { EMPTY, firstValueFrom } from "rxjs";
 import { toArray } from "rxjs/operators";
 
@@ -94,6 +94,7 @@ describe("InMemoryAgentRunner", () => {
 
   beforeEach(() => {
     runner = new InMemoryAgentRunner();
+    runner.clearThreads();
   });
 
   describe("RunStarted payload", () => {
@@ -336,6 +337,12 @@ describe("InMemoryAgentRunner", () => {
 
       expect(errorEvent).toBeDefined();
       expect(errorEvent!.message).toBe("HTTP 401: Unauthorized");
+      // RUN_ERROR must be the terminal event — the runner must not also emit
+      // RUN_FINISHED on the failure path, and nothing should follow the error.
+      expect(events[events.length - 1].type).toBe(EventType.RUN_ERROR);
+      expect(
+        events.filter((e) => e.type === EventType.RUN_FINISHED),
+      ).toHaveLength(0);
     });
 
     it("propagates non-HTTP error messages into the RUN_ERROR event", async () => {
@@ -361,3 +368,410 @@ describe("InMemoryAgentRunner", () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Agent that populates this.messages after a run — needed to test the
+// listThreads / getThreadMessages fallback which reads agent.messages.
+// ---------------------------------------------------------------------------
+class MessagePopulatingTestAgent extends AbstractAgent {
+  constructor(
+    // Accept undefined so `clone()` can forward `this.agentId` losslessly.
+    // `AbstractAgent.agentId` is optional (`AgentConfig.agentId?: string`),
+    // so coercing undefined to "" would silently turn "no agent id" into
+    // "empty agent id" — a different state.
+    agentId: string | undefined,
+    private readonly inputMessages: Message[],
+    private readonly generatedMessages: Message[],
+  ) {
+    super({ agentId });
+  }
+
+  // Override runAgent to simulate what a real agent does: populate this.messages
+  // with the full conversation (input + generated) then call the subscriber callbacks.
+  // Aligns with TestAgent above — `onEvent` is required so the in-memory runner
+  // contract (always supply an event sink) is exercised exactly the same way.
+  // `onNewMessage` is declared optional to match TestAgent and the actual
+  // runner call site, which always passes it. Without the declaration the
+  // mock's options shape silently drifts from production and a regression
+  // that starts depending on `onNewMessage` here would compile cleanly.
+  async runAgent(
+    input: RunAgentInput,
+    options: {
+      onEvent: (params: { event: BaseEvent }) => void;
+      onNewMessage?: (args: { message: Message }) => void;
+      onRunStartedEvent?: () => void;
+    },
+  ): Promise<{ result: unknown; newMessages: Message[] }> {
+    const runStarted: RunStartedEvent = {
+      type: EventType.RUN_STARTED,
+      threadId: input.threadId,
+      runId: input.runId,
+    };
+    options.onEvent({ event: runStarted });
+    options.onRunStartedEvent?.();
+
+    for (const msg of this.generatedMessages) {
+      const start = {
+        type: EventType.TEXT_MESSAGE_START,
+        messageId: msg.id,
+        role: (msg as { role: string }).role,
+      } as TextMessageStartEvent;
+      const content = {
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: msg.id,
+        delta: (msg as { content?: string }).content ?? "",
+      } as TextMessageContentEvent;
+      const end = {
+        type: EventType.TEXT_MESSAGE_END,
+        messageId: msg.id,
+      } as TextMessageEndEvent;
+      options.onEvent({ event: start });
+      options.onEvent({ event: content });
+      options.onEvent({ event: end });
+    }
+
+    // Populate this.messages — this is what real AbstractAgent.runAgent does
+    this.messages = [...this.inputMessages, ...this.generatedMessages];
+    return { result: undefined, newMessages: this.generatedMessages };
+  }
+
+  clone(): AbstractAgent {
+    return new MessagePopulatingTestAgent(
+      this.agentId,
+      this.inputMessages,
+      this.generatedMessages,
+    );
+  }
+
+  protected run(): ReturnType<AbstractAgent["run"]> {
+    return EMPTY;
+  }
+
+  // Mirror `TestAgent` and `ThrowingAgent` — `AbstractAgent.connect()` would
+  // otherwise inherit production behavior that may try to open a transport.
+  // Returning EMPTY keeps clones inert in tests.
+  protected connect(): ReturnType<AbstractAgent["connect"]> {
+    return EMPTY;
+  }
+}
+
+describe("InMemoryAgentRunner — listThreads / getThreadMessages", () => {
+  let runner: InMemoryAgentRunner;
+
+  const userMessage: Message = { id: "u1", role: "user", content: "Hello" };
+  const assistantMessage: Message = {
+    id: "a1",
+    role: "assistant",
+    content: "Hi there!",
+  };
+
+  beforeEach(async () => {
+    runner = new InMemoryAgentRunner();
+    // Reset the module-level GLOBAL_STORE singleton so tests don't leak into each other
+    runner.clearThreads();
+
+    // Run a single turn on a unique thread so each test starts fresh
+    const agent = new MessagePopulatingTestAgent(
+      "test-agent",
+      [userMessage],
+      [assistantMessage],
+    );
+    await firstValueFrom(
+      runner
+        .run({
+          threadId: "list-threads-thread-1",
+          agent,
+          input: {
+            threadId: "list-threads-thread-1",
+            runId: "run-lt-1",
+            messages: [userMessage],
+            state: {},
+            tools: [],
+            context: [],
+          },
+        })
+        .pipe(toArray()),
+    );
+  });
+
+  describe("listThreads", () => {
+    it("returns a summary for each completed thread", () => {
+      const threads = runner.listThreads();
+      const thread = threads.find(
+        (t: InMemoryThread) => t.id === "list-threads-thread-1",
+      );
+      expect(thread).toBeDefined();
+      expect(thread!.agentId).toBe("test-agent");
+      expect(thread!.name).toBeNull();
+      expect(thread!.archived).toBe(false);
+      expect(thread!.createdAt).toBeTruthy();
+      expect(thread!.updatedAt).toBeTruthy();
+    });
+
+    it("returns threads sorted most-recently-updated first", async () => {
+      // Run a second thread after a delay long enough that timer-resolution
+      // jitter on slow CI runners cannot collapse the two timestamps. 20ms
+      // sits comfortably above typical setTimeout granularity (~4ms in Node)
+      // and the file-system timestamp resolution we observed flakes around.
+      await new Promise((r) => setTimeout(r, 20));
+      const agent2 = new MessagePopulatingTestAgent(
+        "test-agent",
+        [userMessage],
+        [assistantMessage],
+      );
+      await firstValueFrom(
+        runner
+          .run({
+            threadId: "list-threads-thread-2",
+            agent: agent2,
+            input: {
+              threadId: "list-threads-thread-2",
+              runId: "run-lt-2",
+              messages: [userMessage],
+              state: {},
+              tools: [],
+              context: [],
+            },
+          })
+          .pipe(toArray()),
+      );
+
+      const threads = runner.listThreads();
+      const ids = threads.map((t: InMemoryThread) => t.id);
+      const idx1 = ids.indexOf("list-threads-thread-1");
+      const idx2 = ids.indexOf("list-threads-thread-2");
+      // thread-2 is more recent, should appear before thread-1
+      expect(idx2).toBeLessThan(idx1);
+    });
+
+    it("returns an empty array when no threads have been run", () => {
+      const freshRunner = new InMemoryAgentRunner();
+      freshRunner.clearThreads();
+      expect(freshRunner.listThreads()).toEqual([]);
+    });
+  });
+
+  describe("getThreadMessages", () => {
+    it("returns all messages for a completed thread", () => {
+      const messages = runner.getThreadMessages("list-threads-thread-1");
+      expect(messages).toHaveLength(2);
+      const roles = messages.map((m) => (m as { role: string }).role);
+      expect(roles).toContain("user");
+      expect(roles).toContain("assistant");
+    });
+
+    it("includes message content", () => {
+      const messages = runner.getThreadMessages("list-threads-thread-1");
+      const user = messages.find(
+        (m) => (m as { role: string }).role === "user",
+      ) as {
+        content?: string;
+      };
+      const assistant = messages.find(
+        (m) => (m as { role: string }).role === "assistant",
+      ) as { content?: string };
+      expect(user?.content).toBe("Hello");
+      expect(assistant?.content).toBe("Hi there!");
+    });
+
+    it("returns an empty array for an unknown threadId", () => {
+      const messages = runner.getThreadMessages("nonexistent-thread-xyz");
+      expect(messages).toEqual([]);
+    });
+
+    it("reflects the most recent run's full message history", async () => {
+      const followUp: Message = {
+        id: "u2",
+        role: "user",
+        content: "Follow up",
+      };
+      const followUpReply: Message = {
+        id: "a2",
+        role: "assistant",
+        content: "Sure!",
+      };
+      const agent2 = new MessagePopulatingTestAgent(
+        "test-agent",
+        [userMessage, assistantMessage, followUp],
+        [followUpReply],
+      );
+      await firstValueFrom(
+        runner
+          .run({
+            threadId: "list-threads-thread-1",
+            agent: agent2,
+            input: {
+              threadId: "list-threads-thread-1",
+              runId: "run-lt-turn-2",
+              messages: [userMessage, assistantMessage, followUp],
+              state: {},
+              tools: [],
+              context: [],
+            },
+          })
+          .pipe(toArray()),
+      );
+
+      const messages = runner.getThreadMessages("list-threads-thread-1");
+      // Should have all 4 messages from the second run's snapshot
+      expect(messages).toHaveLength(4);
+    });
+  });
+
+  describe("getThreadEvents", () => {
+    it("returns stored events for a completed thread", () => {
+      const events = runner.getThreadEvents("list-threads-thread-1");
+      // The beforeEach runs a single turn. The MessagePopulatingTestAgent
+      // emits RUN_STARTED + a TEXT_MESSAGE triple for the assistant reply
+      // and never emits a terminal event itself.
+      expect(events.length).toBeGreaterThan(0);
+      const types = events.map((e) => e.type);
+      expect(types).toContain(EventType.RUN_STARTED);
+      // Content events must be present so the inspector can replay full
+      // thread history — guard against a regression that strips them
+      // during compaction.
+      expect(types).toContain(EventType.TEXT_MESSAGE_START);
+      expect(types).toContain(EventType.TEXT_MESSAGE_CONTENT);
+      expect(types).toContain(EventType.TEXT_MESSAGE_END);
+      // finalizeRunEvents mutates the events array to append a synthetic
+      // terminal event when the agent does not emit one itself: a
+      // RUN_ERROR with code INCOMPLETE_STREAM. Asserting this explicitly
+      // guards against a regression where the synthetic event is dropped
+      // (the inspector would render an in-progress thread forever) or
+      // where the code is silently changed to something inspectors don't
+      // recognise.
+      const terminal = events.find(
+        (e): e is BaseEvent & { code?: string } =>
+          e.type === EventType.RUN_ERROR,
+      );
+      expect(terminal).toBeDefined();
+      expect((terminal as { code?: string }).code).toBe("INCOMPLETE_STREAM");
+    });
+
+    it("returns an empty array for an unknown threadId", () => {
+      expect(runner.getThreadEvents("nonexistent-thread-xyz")).toEqual([]);
+    });
+
+    it("flattens events across multiple historic runs", async () => {
+      const followUp: Message = {
+        id: "u2",
+        role: "user",
+        content: "Follow up",
+      };
+      const agent2 = new MessagePopulatingTestAgent(
+        "test-agent",
+        [userMessage, assistantMessage, followUp],
+        [{ id: "a2", role: "assistant", content: "Sure!" }],
+      );
+      await firstValueFrom(
+        runner
+          .run({
+            threadId: "list-threads-thread-1",
+            agent: agent2,
+            input: {
+              threadId: "list-threads-thread-1",
+              runId: "run-lt-turn-2",
+              messages: [userMessage, assistantMessage, followUp],
+              state: {},
+              tools: [],
+              context: [],
+            },
+          })
+          .pipe(toArray()),
+      );
+
+      const events = runner.getThreadEvents("list-threads-thread-1");
+      const runStartedCount = events.filter(
+        (e) => e.type === EventType.RUN_STARTED,
+      ).length;
+      // Two runs means two RUN_STARTED events survive compaction.
+      expect(runStartedCount).toBe(2);
+    });
+  });
+
+  describe("getThreadState", () => {
+    it("returns null when the thread has never emitted a state snapshot", () => {
+      // The beforeEach agent doesn't emit STATE_SNAPSHOT events.
+      expect(runner.getThreadState("list-threads-thread-1")).toBeNull();
+    });
+
+    it("returns null for an unknown threadId", () => {
+      expect(runner.getThreadState("nonexistent-thread-xyz")).toBeNull();
+    });
+
+    it("returns the last STATE_SNAPSHOT payload after a run", async () => {
+      const snapshot = { counter: 7, name: "alpha" };
+      const stateAgent = new TestAgent(
+        [
+          {
+            type: EventType.STATE_SNAPSHOT,
+            snapshot,
+          } as BaseEvent,
+        ],
+        true,
+      );
+      await firstValueFrom(
+        runner
+          .run({
+            threadId: "thread-with-state",
+            agent: stateAgent,
+            input: {
+              threadId: "thread-with-state",
+              runId: "run-state-1",
+              messages: [],
+              state: {},
+              tools: [],
+              context: [],
+            },
+          })
+          .pipe(toArray()),
+      );
+
+      expect(runner.getThreadState("thread-with-state")).toEqual(snapshot);
+    });
+
+    it("returns the most recent snapshot across multiple runs", async () => {
+      const first = { step: 1 };
+      const second = { step: 2 };
+
+      const run = async (threadId: string, runId: string, snapshot: object) => {
+        const agent = new TestAgent(
+          [{ type: EventType.STATE_SNAPSHOT, snapshot } as BaseEvent],
+          true,
+        );
+        await firstValueFrom(
+          runner
+            .run({
+              threadId,
+              agent,
+              input: {
+                threadId,
+                runId,
+                messages: [],
+                state: {},
+                tools: [],
+                context: [],
+              },
+            })
+            .pipe(toArray()),
+        );
+      };
+
+      await run("thread-multi-state", "run-a", first);
+      await run("thread-multi-state", "run-b", second);
+
+      expect(runner.getThreadState("thread-multi-state")).toEqual(second);
+
+      // Cross-thread isolation: a snapshot on a different thread must not
+      // bleed into the original thread's state. This guards against any
+      // accidental "last-write-wins" leak in the per-thread state store.
+      const otherThreadSnapshot = { step: 999 };
+      await run("thread-other", "run-other", otherThreadSnapshot);
+
+      expect(runner.getThreadState("thread-other")).toEqual(
+        otherThreadSnapshot,
+      );
+      expect(runner.getThreadState("thread-multi-state")).toEqual(second);
+    });
+  });
+});

package/src/v2/runtime/runner/in-memory.ts

@@ -10,8 +10,9 @@ import {
   AbstractAgent,
   BaseEvent,
   EventType,
-  MessagesSnapshotEvent,
+  Message,
   RunStartedEvent,
+  StateSnapshotEvent,
   compactEvents,
 } from "@ag-ui/client";
 import { finalizeRunEvents } from "@copilotkit/shared";
@@ -19,11 +20,34 @@ import { finalizeRunEvents } from "@copilotkit/shared";
 interface HistoricRun {
   threadId: string;
   runId: string;
+  /** ID of the agent that executed this run. */
+  agentId: string;
   parentRunId: string | null;
   events: BaseEvent[];
+  /**
+   * Snapshot of all messages (input + generated) at the end of this run.
+   * Used by the local thread-messages fallback endpoint.
+   */
+  messages: Message[];
   createdAt: number;
 }
 
+/**
+ * Lightweight thread summary returned by {@link InMemoryAgentRunner.listThreads}.
+ * Shape matches the Intelligence platform's ThreadRecord so the same HTTP
+ * response envelope can be used for both backends.
+ */
+export interface InMemoryThread {
+  id: string;
+  name: string | null;
+  agentId: string;
+  organizationId: ""; // always empty in in-memory mode
+  createdById: ""; // always empty in in-memory mode
+  archived: false; // always false in in-memory mode
+  createdAt: string;
+  updatedAt: string;
+}
+
 class InMemoryEventStore {
   constructor(public threadId: string) {}
 
@@ -52,50 +76,7 @@ class InMemoryEventStore {
   currentEvents: BaseEvent[] | null = null;
 }
 
-// Use a symbol key on globalThis to survive hot reloads in development
-const GLOBAL_STORE_KEY = Symbol.for("@copilotkit/runtime/in-memory-store");
-
-interface GlobalStoreData {
-  stores: Map<string, InMemoryEventStore>;
-  historicRunsBackup: Map<string, HistoricRun[]>;
-}
-
-function getGlobalStore(): Map<string, InMemoryEventStore> {
-  const globalAny = globalThis as unknown as Record<symbol, GlobalStoreData>;
-
-  if (!globalAny[GLOBAL_STORE_KEY]) {
-    globalAny[GLOBAL_STORE_KEY] = {
-      stores: new Map<string, InMemoryEventStore>(),
-      historicRunsBackup: new Map<string, HistoricRun[]>(),
-    };
-  }
-
-  const data = globalAny[GLOBAL_STORE_KEY];
-
-  // Restore historic runs from backup after hot reload
-  // (when stores map is empty but backup has data)
-  if (data.stores.size === 0 && data.historicRunsBackup.size > 0) {
-    for (const [threadId, historicRuns] of data.historicRunsBackup) {
-      const store = new InMemoryEventStore(threadId);
-      store.historicRuns = historicRuns;
-      data.stores.set(threadId, store);
-    }
-  }
-
-  return data.stores;
-}
-
-function backupHistoricRuns(
-  threadId: string,
-  historicRuns: HistoricRun[],
-): void {
-  const globalAny = globalThis as unknown as Record<symbol, GlobalStoreData>;
-  if (globalAny[GLOBAL_STORE_KEY]) {
-    globalAny[GLOBAL_STORE_KEY].historicRunsBackup.set(threadId, historicRuns);
-  }
-}
-
-const GLOBAL_STORE = getGlobalStore();
+const GLOBAL_STORE = new Map<string, InMemoryEventStore>();
 
 export class InMemoryAgentRunner extends AgentRunner {
   run(request: AgentRunnerRunRequest): Observable<BaseEvent> {
@@ -215,13 +196,15 @@ export class InMemoryAgentRunner extends AgentRunner {
           store.historicRuns.push({
             threadId: request.threadId,
             runId: store.currentRunId,
+            agentId: request.agent.agentId ?? "default",
             parentRunId,
             events: compactedEvents,
+            // Snapshot all messages (input + generated) for the thread-messages endpoint
+            messages: Array.isArray(request.agent.messages)
+              ? [...request.agent.messages]
+              : [],
             createdAt: Date.now(),
           });
-
-          // Backup for hot reload survival
-          backupHistoricRuns(request.threadId, store.historicRuns);
         }
 
         // Complete the run
@@ -252,13 +235,14 @@ export class InMemoryAgentRunner extends AgentRunner {
           store.historicRuns.push({
             threadId: request.threadId,
             runId: store.currentRunId,
+            agentId: request.agent.agentId ?? "default",
             parentRunId,
             events: compactedEvents,
+            messages: Array.isArray(request.agent.messages)
+              ? [...request.agent.messages]
+              : [],
             createdAt: Date.now(),
           });
-
-          // Backup for hot reload survival
-          backupHistoricRuns(request.threadId, store.historicRuns);
         }
 
         // Complete the run
@@ -378,4 +362,106 @@ export class InMemoryAgentRunner extends AgentRunner {
       return Promise.resolve(false);
     }
   }
+
+  /**
+   * Returns a summary of every thread that has been run through this runner.
+   *
+   * This powers the local-dev fallback for `GET /threads` when the Intelligence
+   * platform is not configured. Each entry mirrors the shape of a platform
+   * `ThreadRecord` so the HTTP handler can use the same response envelope.
+   */
+  listThreads(): InMemoryThread[] {
+    const threads: InMemoryThread[] = [];
+    for (const [threadId, store] of GLOBAL_STORE) {
+      if (store.historicRuns.length === 0) continue;
+      const firstRun = store.historicRuns[0]!;
+      const lastRun = store.historicRuns[store.historicRuns.length - 1]!;
+      threads.push({
+        id: threadId,
+        name: null,
+        agentId: lastRun.agentId,
+        organizationId: "",
+        createdById: "",
+        archived: false,
+        createdAt: new Date(firstRun.createdAt).toISOString(),
+        updatedAt: new Date(lastRun.createdAt).toISOString(),
+      });
+    }
+    // Most recently updated first
+    return threads.sort(
+      (a, b) =>
+        new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime(),
+    );
+  }
+
+  /**
+   * Returns all messages for a thread, using the snapshot captured at the end
+   * of the most recent run.
+   *
+   * This powers the local-dev fallback for `GET /threads/:threadId/messages`
+   * when the Intelligence platform is not configured. The returned `Message[]`
+   * objects come directly from the ag-ui agent, so their shape is compatible
+   * with the Intelligence platform's `ThreadMessage` type.
+   */
+  getThreadMessages(threadId: string): Message[] {
+    const store = GLOBAL_STORE.get(threadId);
+    if (!store || store.historicRuns.length === 0) return [];
+    // The last run's snapshot has the complete conversation history
+    return store.historicRuns[store.historicRuns.length - 1]!.messages;
+  }
+
+  /**
+   * Returns all AG-UI events for a thread, compacted across historic runs.
+   *
+   * Powers the local-dev fallback for `GET /threads/:threadId/events` when the
+   * Intelligence platform is not configured. The compaction logic matches
+   * the connection-replay path in {@link connect}, so the stream a
+   * late-joining inspector sees matches what this method returns.
+   */
+  getThreadEvents(threadId: string): BaseEvent[] {
+    const store = GLOBAL_STORE.get(threadId);
+    if (!store || store.historicRuns.length === 0) return [];
+    const all: BaseEvent[] = [];
+    for (const run of store.historicRuns) all.push(...run.events);
+    return compactEvents(all);
+  }
+
+  /**
+   * Returns the agent state snapshot for a thread.
+   *
+   * Derived from the last `STATE_SNAPSHOT` in the compacted event stream. The
+   * AG-UI `compactEvents` helper consolidates STATE_DELTA events and produces
+   * a single trailing STATE_SNAPSHOT when state changes exist, so this is a
+   * faithful view of state at the end of the most recent run.
+   *
+   * Returns `null` when the thread has never emitted a STATE_SNAPSHOT.
+   */
+  getThreadState(threadId: string): Record<string, unknown> | null {
+    const events = this.getThreadEvents(threadId);
+    // Walk backwards — the last snapshot wins.
+    for (let i = events.length - 1; i >= 0; i--) {
+      const event = events[i]!;
+      if (event.type === EventType.STATE_SNAPSHOT) {
+        const snapshot = (event as StateSnapshotEvent).snapshot;
+        if (snapshot && typeof snapshot === "object") {
+          return snapshot as Record<string, unknown>;
+        }
+        return null;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Clears all in-memory thread history.
+   *
+   * Powers the local-dev fallback for `POST /threads/clear`, letting consumers
+   * (e.g. the demo's Clear button) reset to an empty thread list without
+   * restarting the runtime. Intentionally not exposed on the Intelligence
+   * platform path: there, thread history lives in a real database and must
+   * not be wiped this way.
+   */
+  clearThreads(): void {
+    GLOBAL_STORE.clear();
+  }
 }