@copilotkit/runtime 1.55.1 → 1.55.2-next.1

package/src/agent/__tests__/converter-custom.test.ts

@@ -0,0 +1,319 @@
+import { describe, it, expect } from "vitest";
+import { EventType, type BaseEvent } from "@ag-ui/client";
+import { BuiltInAgent } from "../index";
+import {
+  createAgent,
+  createDefaultInput,
+  collectEvents,
+  expectLifecycleWrapped,
+  expectEventSequence,
+  eventField,
+  mockCustomStream,
+} from "./agent-test-helpers";
+
+describe("Custom Converter (passthrough)", () => {
+  // -----------------------------------------------------------------------
+  // Event Forwarding
+  // -----------------------------------------------------------------------
+  describe("Event Forwarding", () => {
+    it("should forward a single TEXT_MESSAGE_CHUNK as-is between lifecycle events", async () => {
+      const chunk: BaseEvent = {
+        type: EventType.TEXT_MESSAGE_CHUNK,
+        role: "assistant",
+        delta: "Hello world",
+      } as BaseEvent;
+
+      const agent = createAgent("custom", [chunk]);
+      const input = createDefaultInput();
+      const events = await collectEvents(agent.run(input));
+
+      expectLifecycleWrapped(events, "test-thread", "test-run");
+      expectEventSequence(events, [
+        EventType.RUN_STARTED,
+        EventType.TEXT_MESSAGE_CHUNK,
+        EventType.RUN_FINISHED,
+      ]);
+
+      expect(eventField<string>(events[1], "delta")).toBe("Hello world");
+      expect(eventField<string>(events[1], "role")).toBe("assistant");
+    });
+
+    it("should forward multiple event types in order", async () => {
+      const userEvents: BaseEvent[] = [
+        { type: EventType.TEXT_MESSAGE_START, role: "assistant" } as BaseEvent,
+        {
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          role: "assistant",
+          content: "Hi",
+        } as BaseEvent,
+        { type: EventType.TEXT_MESSAGE_END } as BaseEvent,
+      ];
+
+      const agent = createAgent("custom", userEvents);
+      const events = await collectEvents(agent.run(createDefaultInput()));
+
+      expectEventSequence(events, [
+        EventType.RUN_STARTED,
+        EventType.TEXT_MESSAGE_START,
+        EventType.TEXT_MESSAGE_CONTENT,
+        EventType.TEXT_MESSAGE_END,
+        EventType.RUN_FINISHED,
+      ]);
+    });
+
+    it("should forward TOOL_CALL_START + TOOL_CALL_ARGS + TOOL_CALL_END", async () => {
+      const toolEvents: BaseEvent[] = [
+        {
+          type: EventType.TOOL_CALL_START,
+          toolCallId: "tc-1",
+          toolCallName: "myTool",
+        } as BaseEvent,
+        {
+          type: EventType.TOOL_CALL_ARGS,
+          toolCallId: "tc-1",
+          delta: '{"key":"value"}',
+        } as BaseEvent,
+        {
+          type: EventType.TOOL_CALL_END,
+          toolCallId: "tc-1",
+        } as BaseEvent,
+      ];
+
+      const agent = createAgent("custom", toolEvents);
+      const events = await collectEvents(agent.run(createDefaultInput()));
+
+      expectEventSequence(events, [
+        EventType.RUN_STARTED,
+        EventType.TOOL_CALL_START,
+        EventType.TOOL_CALL_ARGS,
+        EventType.TOOL_CALL_END,
+        EventType.RUN_FINISHED,
+      ]);
+
+      expect(eventField<string>(events[1], "toolCallId")).toBe("tc-1");
+      expect(eventField<string>(events[1], "toolCallName")).toBe("myTool");
+
+      expect(eventField<string>(events[2], "toolCallId")).toBe("tc-1");
+      expect(eventField<string>(events[2], "delta")).toBe('{"key":"value"}');
+
+      expect(eventField<string>(events[3], "toolCallId")).toBe("tc-1");
+    });
+
+    it("should forward a STATE_SNAPSHOT event", async () => {
+      const snapshot: BaseEvent = {
+        type: EventType.STATE_SNAPSHOT,
+        snapshot: { counter: 42, items: ["a", "b"] },
+      } as BaseEvent;
+
+      const agent = createAgent("custom", [snapshot]);
+      const events = await collectEvents(agent.run(createDefaultInput()));
+
+      expectEventSequence(events, [
+        EventType.RUN_STARTED,
+        EventType.STATE_SNAPSHOT,
+        EventType.RUN_FINISHED,
+      ]);
+
+      expect(
+        eventField<Record<string, unknown>>(events[1], "snapshot"),
+      ).toEqual({ counter: 42, items: ["a", "b"] });
+    });
+
+    it("should forward a STATE_DELTA event", async () => {
+      const delta: BaseEvent = {
+        type: EventType.STATE_DELTA,
+        delta: [{ op: "replace", path: "/counter", value: 43 }],
+      } as BaseEvent;
+
+      const agent = createAgent("custom", [delta]);
+      const events = await collectEvents(agent.run(createDefaultInput()));
+
+      expectEventSequence(events, [
+        EventType.RUN_STARTED,
+        EventType.STATE_DELTA,
+        EventType.RUN_FINISHED,
+      ]);
+
+      expect(eventField<unknown[]>(events[1], "delta")).toEqual([
+        { op: "replace", path: "/counter", value: 43 },
+      ]);
+    });
+
+    it("should forward reasoning events in order", async () => {
+      const reasoningEvents: BaseEvent[] = [
+        { type: EventType.REASONING_START } as BaseEvent,
+        { type: EventType.REASONING_MESSAGE_START } as BaseEvent,
+        {
+          type: EventType.REASONING_MESSAGE_CONTENT,
+          content: "Thinking step 1",
+        } as BaseEvent,
+        {
+          type: EventType.REASONING_MESSAGE_CONTENT,
+          content: "Thinking step 2",
+        } as BaseEvent,
+        { type: EventType.REASONING_MESSAGE_END } as BaseEvent,
+        { type: EventType.REASONING_END } as BaseEvent,
+      ];
+
+      const agent = createAgent("custom", reasoningEvents);
+      const events = await collectEvents(agent.run(createDefaultInput()));
+
+      expectEventSequence(events, [
+        EventType.RUN_STARTED,
+        EventType.REASONING_START,
+        EventType.REASONING_MESSAGE_START,
+        EventType.REASONING_MESSAGE_CONTENT,
+        EventType.REASONING_MESSAGE_CONTENT,
+        EventType.REASONING_MESSAGE_END,
+        EventType.REASONING_END,
+        EventType.RUN_FINISHED,
+      ]);
+
+      expect(eventField<string>(events[3], "content")).toBe("Thinking step 1");
+      expect(eventField<string>(events[4], "content")).toBe("Thinking step 2");
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Lifecycle Boundary
+  // -----------------------------------------------------------------------
+  describe("Lifecycle Boundary", () => {
+    it("should result in duplicate RUN_STARTED when user emits one in custom stream", async () => {
+      const userEvents: BaseEvent[] = [
+        {
+          type: EventType.RUN_STARTED,
+          threadId: "user-thread",
+          runId: "user-run",
+        } as BaseEvent,
+        {
+          type: EventType.TEXT_MESSAGE_CHUNK,
+          role: "assistant",
+          delta: "Hello",
+        } as BaseEvent,
+      ];
+
+      const agent = createAgent("custom", userEvents);
+      const events = await collectEvents(agent.run(createDefaultInput()));
+
+      // Agent emits its own RUN_STARTED, then the user's RUN_STARTED is forwarded
+      const runStartedEvents = events.filter(
+        (e) => e.type === EventType.RUN_STARTED,
+      );
+      expect(runStartedEvents).toHaveLength(2);
+
+      // First is from the Agent lifecycle
+      expect(runStartedEvents[0]).toMatchObject({
+        type: EventType.RUN_STARTED,
+        threadId: "test-thread",
+        runId: "test-run",
+      });
+
+      // Second is the user-emitted one, forwarded as-is
+      expect(eventField<string>(runStartedEvents[1], "threadId")).toBe(
+        "user-thread",
+      );
+      expect(eventField<string>(runStartedEvents[1], "runId")).toBe("user-run");
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Edge Cases
+  // -----------------------------------------------------------------------
+  describe("Edge Cases", () => {
+    it("should emit only lifecycle events for an empty async iterable", async () => {
+      const agent = createAgent("custom", []);
+      const events = await collectEvents(agent.run(createDefaultInput()));
+
+      expectEventSequence(events, [
+        EventType.RUN_STARTED,
+        EventType.RUN_FINISHED,
+      ]);
+      expectLifecycleWrapped(events, "test-thread", "test-run");
+    });
+
+    it("should work correctly with an async generator factory", async () => {
+      const agent = new BuiltInAgent({
+        type: "custom",
+        factory: async function* () {
+          yield {
+            type: EventType.TEXT_MESSAGE_CHUNK,
+            role: "assistant",
+            delta: "from generator",
+          } as BaseEvent;
+          yield {
+            type: EventType.TEXT_MESSAGE_CHUNK,
+            role: "assistant",
+            delta: " factory",
+          } as BaseEvent;
+        },
+      });
+
+      const events = await collectEvents(agent.run(createDefaultInput()));
+
+      expectEventSequence(events, [
+        EventType.RUN_STARTED,
+        EventType.TEXT_MESSAGE_CHUNK,
+        EventType.TEXT_MESSAGE_CHUNK,
+        EventType.RUN_FINISHED,
+      ]);
+
+      expect(eventField<string>(events[1], "delta")).toBe("from generator");
+      expect(eventField<string>(events[2], "delta")).toBe(" factory");
+    });
+
+    it("should pass through events with extra/unknown fields", async () => {
+      const eventWithExtras: BaseEvent = {
+        type: EventType.CUSTOM,
+        customField: "custom-value",
+        nestedData: { deep: { value: 123 } },
+        arrayField: [1, 2, 3],
+      } as BaseEvent;
+
+      const agent = createAgent("custom", [eventWithExtras]);
+      const events = await collectEvents(agent.run(createDefaultInput()));
+
+      expectEventSequence(events, [
+        EventType.RUN_STARTED,
+        EventType.CUSTOM,
+        EventType.RUN_FINISHED,
+      ]);
+
+      expect(eventField<string>(events[1], "customField")).toBe("custom-value");
+      expect(
+        eventField<{ deep: { value: number } }>(events[1], "nestedData"),
+      ).toEqual({ deep: { value: 123 } });
+      expect(eventField<number[]>(events[1], "arrayField")).toEqual([1, 2, 3]);
+    });
+
+    it("should forward 1000+ events without loss", async () => {
+      const count = 1500;
+      const manyEvents: BaseEvent[] = Array.from({ length: count }, (_, i) => ({
+        type: EventType.TEXT_MESSAGE_CHUNK,
+        role: "assistant",
+        delta: `chunk-${i}`,
+      })) as BaseEvent[];
+
+      const agent = createAgent("custom", manyEvents);
+      const events = await collectEvents(agent.run(createDefaultInput()));
+
+      // Total = RUN_STARTED + 1500 chunks + RUN_FINISHED
+      expect(events).toHaveLength(count + 2);
+
+      // First and last are lifecycle
+      expect(events[0].type).toBe(EventType.RUN_STARTED);
+      expect(events[events.length - 1].type).toBe(EventType.RUN_FINISHED);
+
+      // All content events are TEXT_MESSAGE_CHUNK
+      const contentEvents = events.slice(1, -1);
+      expect(contentEvents).toHaveLength(count);
+
+      // Verify order preservation
+      for (let i = 0; i < count; i++) {
+        expect(contentEvents[i].type).toBe(EventType.TEXT_MESSAGE_CHUNK);
+        expect(eventField<string>(contentEvents[i], "delta")).toBe(
+          `chunk-${i}`,
+        );
+      }
+    });
+  });
+});

package/src/agent/__tests__/converter-tanstack-input.test.ts

@@ -0,0 +1,211 @@
+import { describe, it, expect } from "vitest";
+import { convertInputToTanStackAI } from "../converters/tanstack";
+import { createDefaultInput } from "./agent-test-helpers";
+
+describe("convertInputToTanStackAI", () => {
+  // -------------------------------------------------------------------------
+  // Message filtering
+  // -------------------------------------------------------------------------
+  describe("message filtering", () => {
+    it("filters out system messages from the messages array", () => {
+      const input = createDefaultInput({
+        messages: [
+          { role: "system", content: "You are helpful" },
+          { role: "user", content: "Hello" },
+        ],
+      });
+
+      const { messages } = convertInputToTanStackAI(input);
+
+      expect(messages).toHaveLength(1);
+      expect(messages[0].role).toBe("user");
+      expect(messages[0].content).toBe("Hello");
+    });
+
+    it("filters out developer messages from the messages array", () => {
+      const input = createDefaultInput({
+        messages: [
+          { role: "developer", content: "Internal instruction" },
+          { role: "user", content: "Hi" },
+        ],
+      });
+
+      const { messages } = convertInputToTanStackAI(input);
+
+      expect(messages).toHaveLength(1);
+      expect(messages[0].role).toBe("user");
+    });
+
+    it("extracts system and developer messages into systemPrompts", () => {
+      const input = createDefaultInput({
+        messages: [
+          { role: "system", content: "System prompt" },
+          { role: "developer", content: "Dev instruction" },
+          { role: "user", content: "Hello" },
+        ],
+      });
+
+      const { systemPrompts } = convertInputToTanStackAI(input);
+
+      expect(systemPrompts).toContain("System prompt");
+      expect(systemPrompts).toContain("Dev instruction");
+    });
+
+    it("preserves user and assistant messages in order", () => {
+      const input = createDefaultInput({
+        messages: [
+          { role: "user", content: "Question 1" },
+          { role: "assistant", content: "Answer 1" },
+          { role: "user", content: "Question 2" },
+        ],
+      });
+
+      const { messages } = convertInputToTanStackAI(input);
+
+      expect(messages).toHaveLength(3);
+      expect(messages[0]).toMatchObject({
+        role: "user",
+        content: "Question 1",
+      });
+      expect(messages[1]).toMatchObject({
+        role: "assistant",
+        content: "Answer 1",
+      });
+      expect(messages[2]).toMatchObject({
+        role: "user",
+        content: "Question 2",
+      });
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Tool call mapping
+  // -------------------------------------------------------------------------
+  describe("tool call mapping", () => {
+    it("maps assistant message toolCalls to TanStack format", () => {
+      const input = createDefaultInput({
+        messages: [
+          {
+            role: "assistant",
+            content: null,
+            toolCalls: [
+              {
+                id: "tc-1",
+                type: "function",
+                function: { name: "getWeather", arguments: '{"city":"NYC"}' },
+              },
+            ],
+          },
+        ],
+      });
+
+      const { messages } = convertInputToTanStackAI(input);
+
+      expect(messages).toHaveLength(1);
+      expect(messages[0].toolCalls).toHaveLength(1);
+      expect(messages[0].toolCalls![0]).toEqual({
+        id: "tc-1",
+        type: "function",
+        function: { name: "getWeather", arguments: '{"city":"NYC"}' },
+      });
+    });
+
+    it("maps tool messages with toolCallId", () => {
+      const input = createDefaultInput({
+        messages: [
+          {
+            role: "tool",
+            content: '{"temp": 72}',
+            toolCallId: "tc-1",
+          },
+        ],
+      });
+
+      const { messages } = convertInputToTanStackAI(input);
+
+      expect(messages).toHaveLength(1);
+      expect(messages[0].role).toBe("tool");
+      expect(messages[0].toolCallId).toBe("tc-1");
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Context injection
+  // -------------------------------------------------------------------------
+  describe("context injection", () => {
+    it("appends context entries to systemPrompts", () => {
+      const input = createDefaultInput({
+        context: [
+          { description: "User preferences", value: "Dark mode enabled" },
+          { description: "Current page", value: "/dashboard" },
+        ],
+      });
+
+      const { systemPrompts } = convertInputToTanStackAI(input);
+
+      expect(systemPrompts).toContain("User preferences:\nDark mode enabled");
+      expect(systemPrompts).toContain("Current page:\n/dashboard");
+    });
+
+    it("does not add context when context array is empty", () => {
+      const input = createDefaultInput({ context: [] });
+
+      const { systemPrompts } = convertInputToTanStackAI(input);
+
+      expect(systemPrompts).toHaveLength(0);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // State serialization
+  // -------------------------------------------------------------------------
+  describe("state serialization", () => {
+    it("serializes non-empty state into systemPrompts", () => {
+      const input = createDefaultInput({
+        state: { count: 42, items: ["a", "b"] },
+      });
+
+      const { systemPrompts } = convertInputToTanStackAI(input);
+
+      const statePrompt = systemPrompts.find((p) =>
+        p.startsWith("Application State:"),
+      );
+      expect(statePrompt).toBeDefined();
+      expect(statePrompt).toContain('"count": 42');
+    });
+
+    it("does not add state when state is empty object", () => {
+      const input = createDefaultInput({ state: {} });
+
+      const { systemPrompts } = convertInputToTanStackAI(input);
+
+      expect(
+        systemPrompts.find((p) => p.startsWith("Application State:")),
+      ).toBeUndefined();
+    });
+
+    it("does not add state when state is null", () => {
+      const input = createDefaultInput({ state: null });
+
+      const { systemPrompts } = convertInputToTanStackAI(input);
+
+      expect(
+        systemPrompts.find((p) => p.startsWith("Application State:")),
+      ).toBeUndefined();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Empty input
+  // -------------------------------------------------------------------------
+  describe("empty input", () => {
+    it("returns empty messages and systemPrompts for default input", () => {
+      const input = createDefaultInput();
+
+      const { messages, systemPrompts } = convertInputToTanStackAI(input);
+
+      expect(messages).toHaveLength(0);
+      expect(systemPrompts).toHaveLength(0);
+    });
+  });
+});