@copilotkit/vue 1.57.1

package/src/v2/hooks/__tests__/use-agent.e2e.test.ts

@@ -0,0 +1,187 @@
+import { defineComponent } from "vue";
+import { screen, fireEvent, waitFor, cleanup } from "@testing-library/vue";
+import { afterEach, describe, expect, it } from "vitest";
+import { EventType } from "@ag-ui/client";
+import type { BaseEvent, RunAgentInput } from "@ag-ui/client";
+import type { Observable } from "rxjs";
+import {
+  MockStepwiseAgent,
+  renderWithCopilotKit,
+  runStartedEvent,
+  runFinishedEvent,
+  textChunkEvent,
+  testId,
+} from "../../__tests__/utils/test-helpers";
+import { useAgent } from "../use-agent";
+import { useCopilotKit } from "../../providers/useCopilotKit";
+import CopilotChat from "../../components/chat/CopilotChat.vue";
+
+class StateCapturingMockAgent extends MockStepwiseAgent {
+  public lastRunInput?: RunAgentInput;
+
+  run(input: RunAgentInput): Observable<BaseEvent> {
+    this.lastRunInput = input;
+    return super.run(input);
+  }
+}
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("useAgent e2e", () => {
+  describe("setState passes state to agent run", () => {
+    it("agent receives state set via setState when runAgent is called", async () => {
+      const agent = new StateCapturingMockAgent();
+
+      const StateTestComponent = defineComponent({
+        setup() {
+          const { agent: hookAgent } = useAgent();
+          const { copilotkit } = useCopilotKit();
+
+          const handleSetStateAndRun = async () => {
+            hookAgent.value.setState({ testKey: "testValue", counter: 42 });
+            await copilotkit.value.runAgent({ agent: hookAgent.value });
+          };
+
+          return { handleSetStateAndRun };
+        },
+        template: `
+          <button data-testid="trigger-btn" @click="handleSetStateAndRun">
+            Set State and Run
+          </button>
+        `,
+      });
+
+      renderWithCopilotKit({
+        agent,
+        children: StateTestComponent,
+      });
+
+      const triggerBtn = await screen.findByTestId("trigger-btn");
+      await fireEvent.click(triggerBtn);
+
+      await waitFor(() => {
+        expect(agent.lastRunInput).toBeDefined();
+      });
+
+      await agent.emit(runStartedEvent());
+      await agent.emit(runFinishedEvent());
+      await agent.complete();
+
+      expect(agent.lastRunInput?.state).toEqual({
+        testKey: "testValue",
+        counter: 42,
+      });
+    });
+  });
+
+  describe("addMessage + runAgent displays in CopilotChat", () => {
+    it("messages added via useAgent show up in CopilotChat", async () => {
+      const agent = new MockStepwiseAgent();
+
+      const MessageTestComponent = defineComponent({
+        components: { CopilotChat },
+        setup() {
+          const { agent: hookAgent } = useAgent();
+          const { copilotkit } = useCopilotKit();
+
+          const handleAddMessageAndRun = async () => {
+            hookAgent.value.addMessage({
+              id: testId("user-msg"),
+              role: "user",
+              content: "Hello from useAgent!",
+            } as any);
+            await copilotkit.value.runAgent({ agent: hookAgent.value });
+          };
+
+          return { handleAddMessageAndRun };
+        },
+        template: `
+          <div>
+            <button data-testid="send-btn" @click="handleAddMessageAndRun">
+              Send Message
+            </button>
+            <div style="height: 400px;">
+              <CopilotChat :welcome-screen="false" />
+            </div>
+          </div>
+        `,
+      });
+
+      renderWithCopilotKit({
+        agent,
+        children: MessageTestComponent,
+      });
+
+      const sendBtn = await screen.findByTestId("send-btn");
+      await fireEvent.click(sendBtn);
+
+      await waitFor(() => {
+        expect(screen.getByText("Hello from useAgent!")).toBeDefined();
+      });
+
+      const responseId = testId("assistant-msg");
+      await agent.emit(runStartedEvent());
+      await agent.emit(
+        textChunkEvent(responseId, "Hello! I received your message."),
+      );
+      await agent.emit(runFinishedEvent());
+      await agent.complete();
+
+      await waitFor(() => {
+        expect(
+          screen.getByText("Hello! I received your message."),
+        ).toBeDefined();
+      });
+    });
+  });
+
+  describe("run error lifecycle", () => {
+    it("updates useAgent subscribers when run ends with RUN_ERROR", async () => {
+      const agent = new MockStepwiseAgent();
+
+      const RunErrorStatusComponent = defineComponent({
+        setup() {
+          const { agent: hookAgent } = useAgent();
+          const { copilotkit } = useCopilotKit();
+
+          const handleRun = async () => {
+            await copilotkit.value.runAgent({ agent: hookAgent.value });
+          };
+
+          return { hookAgent, handleRun };
+        },
+        template: `
+          <div>
+            <button data-testid="run-btn" @click="handleRun">Run</button>
+            <span data-testid="status">{{ hookAgent?.isRunning ? "running" : "idle" }}</span>
+          </div>
+        `,
+      });
+
+      renderWithCopilotKit({
+        agent,
+        children: RunErrorStatusComponent,
+      });
+
+      expect(screen.getByTestId("status").textContent).toBe("idle");
+
+      await fireEvent.click(screen.getByTestId("run-btn"));
+      await agent.emit(runStartedEvent());
+
+      await waitFor(() => {
+        expect(screen.getByTestId("status").textContent).toBe("running");
+      });
+
+      await agent.emit({
+        type: EventType.RUN_ERROR,
+      } as BaseEvent);
+      await agent.complete();
+
+      await waitFor(() => {
+        expect(screen.getByTestId("status").textContent).toBe("idle");
+      });
+    });
+  });
+});

package/src/v2/hooks/__tests__/use-agent.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { defineComponent, h, nextTick, toRaw } from "vue";
+import type { AbstractAgent, Message } from "@ag-ui/client";
+import { randomUUID } from "@copilotkit/shared";
+import { useAgent } from "../use-agent";
+import { useCopilotKit } from "../../providers/useCopilotKit";
+import { mountWithProvider } from "../../__tests__/utils/mount";
+import { StateCapturingAgent } from "../../__tests__/utils/agents";
+
+describe("useAgent", () => {
+  beforeEach(() => {
+    console.warn = vi.fn();
+    console.error = vi.fn();
+  });
+
+  it("returns local agent from agents__unsafe_dev_only", () => {
+    const mockAgent = new StateCapturingAgent([], "test-agent");
+
+    const Child = defineComponent({
+      setup() {
+        const { agent } = useAgent({ agentId: "test-agent" });
+        return () =>
+          h(
+            "span",
+            { "data-testid": "agent-id" },
+            agent.value?.agentId ?? "none",
+          );
+      },
+    });
+
+    const { wrapper } = mountWithProvider(() => h(Child), {
+      agents__unsafe_dev_only: {
+        "test-agent": mockAgent as unknown as AbstractAgent,
+      },
+    });
+
+    expect(wrapper.find("[data-testid=agent-id]").text()).toBe("test-agent");
+  });
+
+  it("passes state set through useAgent into run input", async () => {
+    const mockAgent = new StateCapturingAgent(
+      [{ newMessages: [] }],
+      "test-agent",
+    );
+
+    const Child = defineComponent({
+      setup() {
+        const { agent } = useAgent({ agentId: "test-agent" });
+        const { copilotkit } = useCopilotKit();
+
+        const runWithState = async () => {
+          toRaw(agent.value).setState({ testKey: "testValue", counter: 42 });
+          await copilotkit.value.runAgent({
+            agent: toRaw(agent.value) as AbstractAgent,
+          });
+        };
+
+        return () =>
+          h(
+            "button",
+            { "data-testid": "run-state", onClick: runWithState },
+            "run",
+          );
+      },
+    });
+
+    const { wrapper } = mountWithProvider(() => h(Child), {
+      agents__unsafe_dev_only: {
+        "test-agent": mockAgent as unknown as AbstractAgent,
+      },
+    });
+
+    await wrapper.find("[data-testid=run-state]").trigger("click");
+    await nextTick();
+
+    expect(mockAgent.state).toEqual({
+      testKey: "testValue",
+      counter: 42,
+    });
+  });
+
+  it("passes messages added through useAgent into run input", async () => {
+    const mockAgent = new StateCapturingAgent(
+      [{ newMessages: [] }],
+      "test-agent",
+    );
+
+    const Child = defineComponent({
+      setup() {
+        const { agent } = useAgent({ agentId: "test-agent" });
+        const { copilotkit } = useCopilotKit();
+
+        const runWithMessage = async () => {
+          const userMessage: Message = {
+            id: randomUUID(),
+            role: "user",
+            content: "Hello from useAgent",
+          } as Message;
+          toRaw(agent.value).addMessage(userMessage);
+          await copilotkit.value.runAgent({
+            agent: toRaw(agent.value) as AbstractAgent,
+          });
+        };
+
+        return () =>
+          h(
+            "button",
+            { "data-testid": "run-message", onClick: runWithMessage },
+            "run",
+          );
+      },
+    });
+
+    const { wrapper } = mountWithProvider(() => h(Child), {
+      agents__unsafe_dev_only: {
+        "test-agent": mockAgent as unknown as AbstractAgent,
+      },
+    });
+
+    await wrapper.find("[data-testid=run-message]").trigger("click");
+    await nextTick();
+
+    const lastMessage = mockAgent.messages.find((m) => m.role === "user");
+    expect(lastMessage?.content).toBe("Hello from useAgent");
+  });
+});

package/src/v2/hooks/__tests__/use-attachments.test.ts

@@ -0,0 +1,181 @@
+import { nextTick, defineComponent, h, onUpdated, ref } from "vue";
+import { render } from "@testing-library/vue";
+import { describe, expect, it, vi } from "vitest";
+import type {
+  AttachmentUploadError,
+  AttachmentsConfig,
+} from "@copilotkit/shared";
+import { useAttachments } from "../use-attachments";
+
+function createFile(name: string, size: number, type: string): File {
+  const content = new Uint8Array(size);
+  return new File([content], name, { type });
+}
+
+function mountHook(initialConfig: AttachmentsConfig | undefined) {
+  const config = ref<AttachmentsConfig | undefined>(initialConfig);
+  const trigger = ref(0);
+  let updateCount = 0;
+  let api: ReturnType<typeof useAttachments> | null = null;
+
+  render(
+    defineComponent({
+      setup() {
+        api = useAttachments({ config });
+        onUpdated(() => {
+          updateCount += 1;
+        });
+        return { trigger };
+      },
+      render() {
+        return h("div", String(this.trigger));
+      },
+    }),
+  );
+
+  const rerender = async () => {
+    trigger.value += 1;
+    await nextTick();
+  };
+
+  return {
+    config,
+    get api() {
+      if (!api) {
+        throw new Error("Hook harness was not initialized.");
+      }
+      return api;
+    },
+    get updateCount() {
+      return updateCount;
+    },
+    rerender,
+  };
+}
+
+describe("useAttachments", () => {
+  describe("referential stability", () => {
+    it("all actions are stable across rerenders with same config", async () => {
+      const harness = mountHook({ enabled: true, accept: "image/*" });
+      const first = harness.api;
+
+      await harness.rerender();
+      const second = harness.api;
+
+      expect(second.processFiles).toBe(first.processFiles);
+      expect(second.handleFileUpload).toBe(first.handleFileUpload);
+      expect(second.handleDragOver).toBe(first.handleDragOver);
+      expect(second.handleDragLeave).toBe(first.handleDragLeave);
+      expect(second.handleDrop).toBe(first.handleDrop);
+      expect(second.removeAttachment).toBe(first.removeAttachment);
+      expect(second.consumeAttachments).toBe(first.consumeAttachments);
+    });
+
+    it("actions remain stable when config object identity changes", async () => {
+      const harness = mountHook({ enabled: true, accept: "image/*" });
+      const first = harness.api;
+
+      harness.config.value = { enabled: true, accept: "image/*" };
+      await harness.rerender();
+      const second = harness.api;
+
+      expect(second.processFiles).toBe(first.processFiles);
+      expect(second.handleFileUpload).toBe(first.handleFileUpload);
+      expect(second.handleDragOver).toBe(first.handleDragOver);
+      expect(second.handleDragLeave).toBe(first.handleDragLeave);
+      expect(second.handleDrop).toBe(first.handleDrop);
+      expect(second.removeAttachment).toBe(first.removeAttachment);
+      expect(second.consumeAttachments).toBe(first.consumeAttachments);
+    });
+
+    it("refs are stable across rerenders", async () => {
+      const harness = mountHook(undefined);
+      const first = harness.api;
+
+      await harness.rerender();
+      const second = harness.api;
+
+      expect(second.fileInputRef).toBe(first.fileInputRef);
+      expect(second.containerRef).toBe(first.containerRef);
+    });
+  });
+
+  describe("re-render counting", () => {
+    it("does not re-render when consumeAttachments is called on empty queue", async () => {
+      const harness = mountHook(undefined);
+      const initialUpdateCount = harness.updateCount;
+
+      harness.api.consumeAttachments();
+      await nextTick();
+
+      expect(harness.updateCount).toBe(initialUpdateCount);
+    });
+
+    it("does not re-render on repeated consumeAttachments for empty queue", async () => {
+      const harness = mountHook(undefined);
+      const initialUpdateCount = harness.updateCount;
+
+      harness.api.consumeAttachments();
+      harness.api.consumeAttachments();
+      harness.api.consumeAttachments();
+      await nextTick();
+
+      expect(harness.updateCount).toBe(initialUpdateCount);
+    });
+  });
+
+  describe("initial state", () => {
+    it("returns empty attachments and disabled by default", () => {
+      const harness = mountHook(undefined);
+      expect(harness.api.attachments.value).toEqual([]);
+      expect(harness.api.enabled.value).toBe(false);
+      expect(harness.api.dragOver.value).toBe(false);
+    });
+
+    it("returns enabled when config.enabled is true", () => {
+      const harness = mountHook({ enabled: true });
+      expect(harness.api.enabled.value).toBe(true);
+    });
+  });
+
+  describe("consumeAttachments", () => {
+    it("returns an empty array when there are no attachments", () => {
+      const harness = mountHook(undefined);
+      expect(harness.api.consumeAttachments()).toEqual([]);
+    });
+  });
+
+  describe("removeAttachment", () => {
+    it("is a no-op when the id does not exist", () => {
+      const harness = mountHook(undefined);
+      harness.api.removeAttachment("nonexistent");
+      expect(harness.api.attachments.value).toEqual([]);
+    });
+  });
+
+  describe("latest config reads", () => {
+    it("stable actions still observe latest config", async () => {
+      const onUploadFailed = vi.fn<(error: AttachmentUploadError) => void>();
+      const harness = mountHook({
+        enabled: true,
+        accept: "image/*",
+        onUploadFailed,
+      });
+
+      const stableProcessFiles = harness.api.processFiles;
+      harness.config.value = {
+        enabled: true,
+        accept: "audio/*",
+        onUploadFailed,
+      };
+      await harness.rerender();
+
+      const imageFile = createFile("photo.png", 128, "image/png");
+      await stableProcessFiles([imageFile]);
+
+      expect(onUploadFailed).toHaveBeenCalledTimes(1);
+      expect(onUploadFailed.mock.calls[0][0].reason).toBe("invalid-type");
+      expect(onUploadFailed.mock.calls[0][0].message).toContain("audio/*");
+    });
+  });
+});

package/src/v2/hooks/__tests__/use-component.test.ts

@@ -0,0 +1,145 @@
+import { render, screen } from "@testing-library/vue";
+import { defineComponent } from "vue";
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { z } from "zod";
+import { useComponent } from "../use-component";
+import { useFrontendTool } from "../use-frontend-tool";
+
+vi.mock("../use-frontend-tool", () => ({
+  useFrontendTool: vi.fn(),
+}));
+
+const mockUseFrontendTool = useFrontendTool as ReturnType<typeof vi.fn>;
+
+describe("useComponent", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("registers a component tool with generated default description", () => {
+    const DemoComponent = defineComponent({
+      props: {
+        city: { type: String, required: true },
+      },
+      template: `<div>{{ city }}</div>`,
+    });
+
+    const Harness = defineComponent({
+      setup() {
+        useComponent({
+          name: "showWeatherCard",
+          render: DemoComponent,
+        });
+        return {};
+      },
+      template: `<div />`,
+    });
+
+    render(Harness);
+
+    expect(mockUseFrontendTool).toHaveBeenCalledTimes(1);
+    const [toolConfig] = mockUseFrontendTool.mock.calls[0] as [
+      {
+        name: string;
+        description: string;
+      },
+    ];
+
+    expect(toolConfig.name).toBe("showWeatherCard");
+    expect(toolConfig.description).toContain(
+      'Use this tool to display the "showWeatherCard" component in the chat.',
+    );
+  });
+
+  it("appends custom description and forwards parameters, agentId, and deps", () => {
+    const weatherSchema = z.object({
+      city: z.string(),
+      unit: z.enum(["c", "f"]),
+    });
+
+    const DemoComponent = defineComponent({
+      props: {
+        city: { type: String, required: true },
+      },
+      template: `<div>{{ city }}</div>`,
+    });
+
+    const deps = ["v1"] as const;
+
+    const Harness = defineComponent({
+      setup() {
+        useComponent(
+          {
+            name: "showWeatherCard",
+            description: "Render a weather card for the selected city.",
+            parameters: weatherSchema,
+            render: DemoComponent,
+            agentId: "weather-agent",
+          },
+          deps as unknown as any[],
+        );
+        return {};
+      },
+      template: `<div />`,
+    });
+
+    render(Harness);
+
+    expect(mockUseFrontendTool).toHaveBeenCalledTimes(1);
+    const [toolConfig, forwardedDeps] = mockUseFrontendTool.mock.calls[0] as [
+      {
+        description: string;
+        parameters: typeof weatherSchema;
+        agentId?: string;
+      },
+      unknown[],
+    ];
+
+    expect(toolConfig.description).toContain(
+      'Use this tool to display the "showWeatherCard" component in the chat.',
+    );
+    expect(toolConfig.description).toContain(
+      "Render a weather card for the selected city.",
+    );
+    expect(toolConfig.parameters).toBe(weatherSchema);
+    expect(toolConfig.agentId).toBe("weather-agent");
+    expect(forwardedDeps).toBe(deps);
+  });
+
+  it("creates a render function that passes args into the component", () => {
+    const DemoComponent = defineComponent({
+      props: {
+        city: { type: String, required: true },
+      },
+      template: `<div data-testid="city">{{ city }}</div>`,
+    });
+
+    const Harness = defineComponent({
+      setup() {
+        useComponent({
+          name: "showWeatherCard",
+          render: DemoComponent,
+        });
+        return {};
+      },
+      template: `<div />`,
+    });
+
+    render(Harness);
+
+    const [toolConfig] = mockUseFrontendTool.mock.calls[0] as [
+      {
+        render: (props: { args: { city: string } }) => unknown;
+      },
+    ];
+
+    const RenderHost = defineComponent({
+      setup() {
+        return () => toolConfig.render({ args: { city: "Paris" } });
+      },
+    });
+
+    render(RenderHost);
+    expect(screen.getByTestId("city").textContent).toBe("Paris");
+  });
+});