@copilotkit/vue 1.57.1

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

@@ -0,0 +1,144 @@
+/**
+ * Integration test for the context timing race condition (CPK-7060).
+ *
+ * When a useFrontendTool handler calls setState(), the corresponding
+ * useAgentContext value is updated asynchronously (React defers useEffect to a
+ * later scheduler task). Without yielding before the follow-up agent run,
+ * runAgent reads stale context from the store.
+ *
+ * CopilotKitCoreReact.waitForPendingFrameworkUpdates() fixes this by awaiting a
+ * zero-delay timeout, which yields to React's scheduler before reading context.
+ *
+ * This test uses real React rendering in jsdom so that actual useState +
+ * useAgentContext + useFrontendTool lifecycle interactions are exercised.
+ */
+import { defineComponent, ref } from "vue";
+import { screen, fireEvent, waitFor, cleanup } from "@testing-library/vue";
+import { describe, it, expect, afterEach } from "vitest";
+import { z } from "zod";
+import type {
+  AgentSubscriber,
+  Context,
+  RunAgentParameters,
+} from "@ag-ui/client";
+import { useFrontendTool } from "../use-frontend-tool";
+import { useAgentContext } from "../use-agent-context";
+import CopilotChat from "../../components/chat/CopilotChat.vue";
+import {
+  MockStepwiseAgent,
+  renderWithCopilotKit,
+  runStartedEvent,
+  runFinishedEvent,
+  toolCallChunkEvent,
+  testId,
+} from "../../__tests__/utils/test-helpers";
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("useAgentContext timing - follow-up run sees updated context", () => {
+  it("follow-up agent run receives context updated by useFrontendTool handler", async () => {
+    /**
+     * Agent subclass that records the context parameter on every runAgent call.
+     * After complete() is called on the subject the Observable completes
+     * immediately for subsequent subscriptions, so the follow-up run resolves
+     * with no new messages — which is fine; we only need to capture context.
+     */
+    class ContextCapturingAgent extends MockStepwiseAgent {
+      public contextPerRun: Context[][] = [];
+
+      override async runAgent(
+        parameters: RunAgentParameters = {},
+        subscriber?: AgentSubscriber,
+      ) {
+        this.contextPerRun.push(parameters.context ?? []);
+        return super.runAgent(parameters, subscriber);
+      }
+    }
+
+    const agent = new ContextCapturingAgent();
+
+    /**
+     * Component that wires React state into useAgentContext and exposes a
+     * frontend tool that updates that state.
+     */
+    const TestComponent = defineComponent({
+      setup() {
+        const prefs = ref<{ spicy: boolean }>({ spicy: true });
+
+        useAgentContext({
+          description: "user preferences",
+          value: prefs,
+        });
+
+        useFrontendTool({
+          name: "updatePrefs",
+          parameters: z.object({}),
+          followUp: true,
+          handler: async () => {
+            prefs.value = { spicy: false };
+          },
+        });
+
+        return {};
+      },
+      template: `<div />`,
+    });
+
+    const Host = defineComponent({
+      components: { TestComponent, CopilotChat },
+      template: `
+        <div>
+          <TestComponent />
+          <div style="height: 400px;">
+            <CopilotChat :welcome-screen="false" />
+          </div>
+        </div>
+      `,
+    });
+
+    renderWithCopilotKit({
+      agent,
+      children: Host,
+    });
+
+    // Submit a user message to start the first agent run
+    const input = await screen.findByRole("textbox");
+    await fireEvent.update(input, "Update my preferences");
+    await fireEvent.keyDown(input, { key: "Enter", code: "Enter" });
+
+    // Wait for the first runAgent call to arrive
+    await waitFor(() => {
+      expect(agent.contextPerRun.length).toBeGreaterThanOrEqual(1);
+    });
+
+    // First run: the agent calls the updatePrefs tool
+    const messageId = testId("msg");
+    const toolCallId = testId("tc");
+
+    await agent.emit(runStartedEvent());
+    await agent.emit(
+      toolCallChunkEvent({
+        toolCallId,
+        toolCallName: "updatePrefs",
+        parentMessageId: messageId,
+        delta: "{}",
+      }),
+    );
+    await agent.emit(runFinishedEvent());
+    await agent.complete();
+
+    // Wait for the follow-up run to be triggered by processAgentResult
+    await waitFor(() => {
+      expect(agent.contextPerRun.length).toBeGreaterThanOrEqual(2);
+    });
+
+    // The follow-up run should see the context updated by the tool handler
+    // (spicy: false), not the stale value from before the handler ran (spicy: true).
+    const followUpContext = agent.contextPerRun[1];
+    expect(followUpContext).toContainEqual(
+      expect.objectContaining({ value: '{"spicy":false}' }),
+    );
+  });
+});

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

@@ -0,0 +1,271 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { defineComponent, h, nextTick, ref } from "vue";
+import { useCopilotKit } from "../../providers/useCopilotKit";
+import { useAgentContext } from "../use-agent-context";
+import { mountWithProvider } from "../../__tests__/utils/mount";
+
+function getContextEntries(
+  core: ReturnType<typeof useCopilotKit>["copilotkit"]["value"],
+) {
+  return Object.values(core.context ?? {});
+}
+
+describe("useAgentContext", () => {
+  beforeEach(() => {
+    console.warn = vi.fn();
+    console.error = vi.fn();
+  });
+
+  it("adds context on mount and removes on unmount", () => {
+    let core:
+      | ReturnType<typeof useCopilotKit>["copilotkit"]["value"]
+      | undefined;
+
+    const Child = defineComponent({
+      setup() {
+        useAgentContext({
+          description: "Test context",
+          value: { key: "value" },
+        });
+        return () => h("div", "child");
+      },
+    });
+
+    const Probe = defineComponent({
+      setup() {
+        const { copilotkit } = useCopilotKit();
+        core = copilotkit.value;
+        return () => null;
+      },
+    });
+
+    const { wrapper } = mountWithProvider(() => h("div", [h(Child), h(Probe)]));
+    expect(getContextEntries(core!)).toHaveLength(1);
+
+    wrapper.unmount();
+    expect(getContextEntries(core!)).toHaveLength(0);
+  });
+
+  it("removes context when conditionally unmounted", async () => {
+    let core:
+      | ReturnType<typeof useCopilotKit>["copilotkit"]["value"]
+      | undefined;
+
+    const ContextUser = defineComponent({
+      setup() {
+        useAgentContext({ description: "conditional", value: "value" });
+        return () => h("div", "context-user");
+      },
+    });
+
+    const Parent = defineComponent({
+      setup() {
+        const shown = ref(true);
+        const { copilotkit } = useCopilotKit();
+        core = copilotkit.value;
+        return () =>
+          h("div", [
+            h(
+              "button",
+              {
+                "data-testid": "toggle",
+                onClick: () => (shown.value = !shown.value),
+              },
+              "toggle",
+            ),
+            shown.value ? h(ContextUser) : null,
+          ]);
+      },
+    });
+
+    const { wrapper } = mountWithProvider(() => h(Parent));
+    expect(getContextEntries(core!)).toHaveLength(1);
+
+    await wrapper.find("[data-testid=toggle]").trigger("click");
+    await nextTick();
+
+    expect(getContextEntries(core!)).toHaveLength(0);
+  });
+
+  it("does not duplicate context on parent re-render with stable inputs", async () => {
+    let core:
+      | ReturnType<typeof useCopilotKit>["copilotkit"]["value"]
+      | undefined;
+
+    const Child = defineComponent({
+      setup() {
+        useAgentContext({
+          description: "Stable context",
+          value: "stable value",
+        });
+        return () => h("div", "child");
+      },
+    });
+
+    const Parent = defineComponent({
+      setup() {
+        const counter = ref(0);
+        const { copilotkit } = useCopilotKit();
+        core = copilotkit.value;
+        return () =>
+          h("div", [
+            h(
+              "button",
+              {
+                "data-testid": "increment",
+                onClick: () => (counter.value += 1),
+              },
+              String(counter.value),
+            ),
+            h(Child),
+          ]);
+      },
+    });
+
+    const { wrapper } = mountWithProvider(() => h(Parent));
+    expect(getContextEntries(core!)).toHaveLength(1);
+
+    await wrapper.find("[data-testid=increment]").trigger("click");
+    await wrapper.find("[data-testid=increment]").trigger("click");
+    await nextTick();
+
+    expect(getContextEntries(core!)).toHaveLength(1);
+  });
+
+  it("re-adds context when description changes", async () => {
+    let core:
+      | ReturnType<typeof useCopilotKit>["copilotkit"]["value"]
+      | undefined;
+    const description = ref("first");
+
+    const Child = defineComponent({
+      setup() {
+        useAgentContext({ description, value: "same" });
+        return () => h("div", "child");
+      },
+    });
+
+    const Parent = defineComponent({
+      setup() {
+        const { copilotkit } = useCopilotKit();
+        core = copilotkit.value;
+        return () =>
+          h(
+            "button",
+            {
+              "data-testid": "update",
+              onClick: () => (description.value = "second"),
+            },
+            "update",
+          );
+      },
+    });
+
+    const { wrapper } = mountWithProvider(() =>
+      h("div", [h(Parent), h(Child)]),
+    );
+    expect(getContextEntries(core!)[0]?.description).toBe("first");
+
+    await wrapper.find("[data-testid=update]").trigger("click");
+    await nextTick();
+
+    const entries = getContextEntries(core!);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.description).toBe("second");
+    expect(entries[0]?.value).toBe("same");
+  });
+
+  it("re-adds context when value changes", async () => {
+    let core:
+      | ReturnType<typeof useCopilotKit>["copilotkit"]["value"]
+      | undefined;
+    const value = ref("first");
+
+    const Child = defineComponent({
+      setup() {
+        useAgentContext({ description: "fixed", value });
+        return () => h("div", "child");
+      },
+    });
+
+    const Parent = defineComponent({
+      setup() {
+        const { copilotkit } = useCopilotKit();
+        core = copilotkit.value;
+        return () =>
+          h(
+            "button",
+            {
+              "data-testid": "update",
+              onClick: () => (value.value = "second"),
+            },
+            "update",
+          );
+      },
+    });
+
+    const { wrapper } = mountWithProvider(() =>
+      h("div", [h(Parent), h(Child)]),
+    );
+    expect(getContextEntries(core!)[0]?.value).toBe("first");
+
+    await wrapper.find("[data-testid=update]").trigger("click");
+    await nextTick();
+
+    const entries = getContextEntries(core!);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.description).toBe("fixed");
+    expect(entries[0]?.value).toBe("second");
+  });
+
+  it("serializes string values unchanged", () => {
+    let core:
+      | ReturnType<typeof useCopilotKit>["copilotkit"]["value"]
+      | undefined;
+    const Child = defineComponent({
+      setup() {
+        const { copilotkit } = useCopilotKit();
+        core = copilotkit.value;
+        useAgentContext({ description: "string", value: "plain" });
+        return () => null;
+      },
+    });
+
+    mountWithProvider(() => h(Child));
+    expect(getContextEntries(core!)[0]?.value).toBe("plain");
+  });
+
+  it.each([
+    ["object", { name: "John", age: 30 }, '{"name":"John","age":30}'],
+    ["array", [1, 2, 3, "four"], '[1,2,3,"four"]'],
+    ["number", 42, "42"],
+    ["boolean", true, "true"],
+    ["null", null, "null"],
+    [
+      "nested",
+      {
+        user: {
+          name: "Alice",
+          settings: { theme: "dark", notifications: true },
+        },
+        items: [1, 2, { nested: "value" }],
+      },
+      '{"user":{"name":"Alice","settings":{"theme":"dark","notifications":true}},"items":[1,2,{"nested":"value"}]}',
+    ],
+  ])("serializes %s values", (_name, value, expected) => {
+    let core:
+      | ReturnType<typeof useCopilotKit>["copilotkit"]["value"]
+      | undefined;
+    const Child = defineComponent({
+      setup() {
+        const { copilotkit } = useCopilotKit();
+        core = copilotkit.value;
+        useAgentContext({ description: "serialized", value: value as never });
+        return () => null;
+      },
+    });
+
+    mountWithProvider(() => h(Child));
+    expect(getContextEntries(core!)[0]?.value).toBe(expected);
+  });
+});

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

@@ -0,0 +1,64 @@
+import { defineComponent } from "vue";
+import { render, screen, cleanup } from "@testing-library/vue";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import CopilotKitProvider from "../../providers/CopilotKitProvider.vue";
+import { useAgent } from "../use-agent";
+
+describe("useAgent error state", () => {
+  const originalFetch = global.fetch;
+  const originalWindow = (globalThis as { window?: unknown }).window;
+
+  beforeEach(() => {
+    // Simulate browser environment
+    (globalThis as { window?: unknown }).window = {};
+    // Mock fetch to reject (simulates runtime unreachable)
+    global.fetch = vi.fn().mockRejectedValue(new Error("network failure"));
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.restoreAllMocks();
+    global.fetch = originalFetch;
+    if (originalWindow === undefined) {
+      delete (globalThis as { window?: unknown }).window;
+    } else {
+      (globalThis as { window?: unknown }).window = originalWindow;
+    }
+  });
+
+  it("returns a provisional agent instead of throwing when runtime is in error state", async () => {
+    const capturedErrors: unknown[] = [];
+
+    const TestComponent = defineComponent({
+      setup() {
+        const { agent } = useAgent({ agentId: "nonexistent" });
+        return { agent };
+      },
+      template: `<div data-testid="agent-id">{{ agent.agentId }}</div>`,
+    });
+
+    const Host = defineComponent({
+      components: { CopilotKitProvider, TestComponent },
+      template: `
+        <CopilotKitProvider runtime-url="http://localhost:59999/nonexistent">
+          <TestComponent />
+        </CopilotKitProvider>
+      `,
+    });
+
+    render(Host, {
+      global: {
+        config: {
+          errorHandler: (error) => {
+            capturedErrors.push(error);
+          },
+        },
+      },
+    });
+
+    // Should render without crashing — agent is provisional
+    const el = await screen.findByTestId("agent-id");
+    expect(el.textContent).toBe("nonexistent");
+    expect(capturedErrors).toEqual([]);
+  });
+});