@copilotkit/vue 2.0.0-rc.3 → 2.0.0-rc.31

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

@@ -31,10 +31,10 @@ describe("useAgent error state", () => {
 
     const TestComponent = defineComponent({
       setup() {
-        const { agent } = useAgent({ agentId: "nonexistent" });
-        return { agent };
+        const { agent, isReady } = useAgent({ agentId: "nonexistent" });
+        return { agent, isReady };
       },
-      template: `<div data-testid="agent-id">{{ agent.agentId }}</div>`,
+      template: `<div data-testid="agent-id">{{ agent.agentId }}</div><div data-testid="ready">{{ isReady }}</div>`,
     });
 
     const Host = defineComponent({
@@ -59,6 +59,8 @@ describe("useAgent error state", () => {
     // Should render without crashing — agent is provisional
     const el = await screen.findByTestId("agent-id");
     expect(el.textContent).toBe("nonexistent");
+    // A provisional stand-in is not the real agent.
+    expect(screen.getByTestId("ready").textContent).toBe("false");
     expect(capturedErrors).toEqual([]);
   });
 });

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

@@ -6,7 +6,23 @@ import type { AbstractAgent } from "@ag-ui/client";
 import { useCopilotKit } from "../../providers/useCopilotKit";
 import { MockStepwiseAgent } from "../../__tests__/utils/test-helpers";
 import { useAgent } from "../use-agent";
-import { CopilotKitCoreRuntimeConnectionStatus } from "@copilotkit/core";
+import {
+  CopilotKitCoreRuntimeConnectionStatus,
+  ProxiedCopilotRuntimeAgent,
+} from "@copilotkit/core";
+
+/** Core's `ɵruntimeInfo` snapshot, built from a fake core's runtime fields. */
+function runtimeInfoOf(core: {
+  runtimeConnectionStatus: CopilotKitCoreRuntimeConnectionStatus;
+  threadEndpoints?: unknown;
+  intelligence?: unknown;
+}) {
+  return {
+    status: core.runtimeConnectionStatus,
+    threadEndpoints: core.threadEndpoints,
+    intelligence: core.intelligence,
+  };
+}
 
 // Mock the CopilotKitProvider to control copilotkit state directly
 vi.mock("../../providers/useCopilotKit", () => ({
@@ -26,6 +42,7 @@ describe("useAgent stability during runtime connection", () => {
   type MockCopilotkit = {
     getAgent: ReturnType<typeof vi.fn>;
     runtimeUrl: string | undefined;
+    readonly ɵruntimeInfo: unknown;
     runtimeConnectionStatus: CopilotKitCoreRuntimeConnectionStatus;
     runtimeTransport: string;
     headers: Record<string, string>;
@@ -45,6 +62,9 @@ describe("useAgent stability during runtime connection", () => {
     copilotkitRef = ref({
       getAgent: vi.fn(() => undefined),
       runtimeUrl: "http://localhost:3000/api/copilotkit",
+      get ɵruntimeInfo() {
+        return runtimeInfoOf(this);
+      },
       runtimeConnectionStatus:
         CopilotKitCoreRuntimeConnectionStatus.Disconnected,
       runtimeTransport: "rest",
@@ -198,7 +218,6 @@ describe("useAgent stability during runtime connection", () => {
     // Phase 1: Disconnected — provisional created
     const { rerender } = render(AgentTracker, { props: { tick: 0 } });
     await nextTick();
-    const provisionalThreadId = agentInstances[0]!.threadId;
 
     // Phase 2: Connecting
     mockCopilotkit.runtimeConnectionStatus =
@@ -232,8 +251,10 @@ describe("useAgent stability during runtime connection", () => {
     // CopilotChat's connect guard ensures connect fires only once (when Connected),
     // so the agent reference change doesn't cause a duplicate connect.
     expect(agentInstances.length).toBe(2);
-    // First instance was the provisional
-    expect(agentInstances[0]!.threadId).toBe(provisionalThreadId);
+    // First instance was the provisional. The hand-off then syncs it with
+    // the registered agent, so its threadId follows the registered one.
+    expect(agentInstances[0]).toBeInstanceOf(ProxiedCopilotRuntimeAgent);
+    expect(agentInstances[0]!.threadId).toBe(registeredAgent.threadId);
     // Second instance is the registered agent
     expect(agentInstances[1]).toBe(registeredAgent);
   });

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

@@ -541,6 +541,8 @@ describe("useAgent throttleMs", () => {
   it("single notification within window does not trigger a trailing re-render", async () => {
     const renderCount = { current: 0 };
     mountHookComponent({ agent, throttleMs: 100, renderCount });
+    // The provider connects on mount, and the status change re-renders once.
+    await flushVue();
     const afterMount = renderCount.current;
     agent.setMessages([userMsg("1", "a")]);
     agent.notifyMessagesChanged();
@@ -692,8 +694,10 @@ describe("useAgent defaultThrottleMs from provider", () => {
         agent,
         defaultThrottleMs: value,
       });
+      // Core validates the value (the provider no longer logs its own copy).
       expect(errorSpy).toHaveBeenCalledWith(
-        expect.stringContaining("CopilotKitProvider: defaultThrottleMs"),
+        expect.stringContaining("CopilotKitCore.setDefaultThrottleMs"),
+        expect.any(Error),
       );
       agent.setMessages([userMsg("1", "a")]);
       agent.notifyMessagesChanged();

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

@@ -21,13 +21,15 @@ describe("useAgent", () => {
 
     const Child = defineComponent({
       setup() {
-        const { agent } = useAgent({ agentId: "test-agent" });
-        return () =>
+        const { agent, isReady } = useAgent({ agentId: "test-agent" });
+        return () => [
           h(
             "span",
             { "data-testid": "agent-id" },
             agent.value?.agentId ?? "none",
-          );
+          ),
+          h("span", { "data-testid": "ready" }, String(isReady.value)),
+        ];
       },
     });
 
@@ -38,6 +40,7 @@ describe("useAgent", () => {
     });
 
     expect(wrapper.find("[data-testid=agent-id]").text()).toBe("test-agent");
+    expect(wrapper.find("[data-testid=ready]").text()).toBe("true");
   });
 
   it("uses agentId from chat configuration when no agentId prop is provided", () => {

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

@@ -106,6 +106,27 @@ describe("useComponent", () => {
     expect(forwardedDeps).toBe(deps);
   });
 
+  it("forwards followUp, as React and Angular do", () => {
+    const Harness = defineComponent({
+      setup() {
+        useComponent({
+          name: "showWeatherCard",
+          render: defineComponent({ template: `<div />` }),
+          followUp: false,
+        });
+        return {};
+      },
+      template: `<div />`,
+    });
+
+    render(Harness);
+
+    const [toolConfig] = mockUseFrontendTool.mock.calls[0] as [
+      { followUp?: boolean },
+    ];
+    expect(toolConfig.followUp).toBe(false);
+  });
+
   it("creates a render function that passes args into the component", () => {
     const DemoComponent = defineComponent({
       props: {

package/src/v2/hooks/__tests__/use-configure-suggestions.test.ts

@@ -12,7 +12,10 @@ import type { Observable } from "rxjs";
 import { useConfigureSuggestions } from "../use-configure-suggestions";
 import { useSuggestions } from "../use-suggestions";
 import { useCopilotKit } from "../../providers/useCopilotKit";
-import { mountWithProvider } from "../../__tests__/utils/mount";
+import {
+  mountWithProvider,
+  renderWithCopilotKit,
+} from "../../__tests__/utils/mount";
 import {
   StateCapturingAgent,
   SuggestionsProviderAgent,
@@ -396,4 +399,30 @@ describe("useConfigureSuggestions", () => {
 
     expect(wrapper.find("[data-testid=json]").text()).toContain("Deferred");
   });
+
+  it("loads a global static config for the chat's agent before any agent registers", async () => {
+    const Harness = defineComponent({
+      setup() {
+        useConfigureSuggestions({
+          suggestions: [{ title: "Welcome", message: "Say hi" }],
+          available: "always",
+        });
+        const { suggestions } = useSuggestions({ agentId: "support" });
+        return () =>
+          h(
+            "span",
+            { "data-testid": "titles" },
+            suggestions.value.map((suggestion) => suggestion.title).join(","),
+          );
+      },
+    });
+
+    const { wrapper } = renderWithCopilotKit(() => h(Harness), {
+      agentId: "support",
+      agents: {},
+    });
+    await nextTick();
+
+    expect(wrapper.find("[data-testid=titles]").text()).toBe("Welcome");
+  });
 });

package/src/v2/hooks/__tests__/use-default-render-tool.test.ts

@@ -530,10 +530,8 @@ describe("useDefaultRenderTool", () => {
     expect(forwarded.result).toBe("ok");
   });
 
-  // Fix #5: circular-ref parameters must not crash the vue render; log.
-  it("default renderer survives circular-ref parameters and logs", async () => {
-    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-
+  // Fix #5: circular-ref parameters must not crash the vue render.
+  it("default renderer survives circular-ref parameters", async () => {
     const Harness = defineComponent({
       setup() {
         useDefaultRenderTool();
@@ -567,14 +565,16 @@ describe("useDefaultRenderTool", () => {
       }),
     ).not.toThrow();
 
+    const wrapper = screen.getByTestId("copilot-tool-render");
+    expect(wrapper.getAttribute("data-args")).toBe(
+      '{"a":1,"self":"[Circular]"}',
+    );
+
     const headerButton = screen
       .getByTestId("copilot-tool-render-name")
       .closest("button");
-    if (headerButton) {
-      await expect(fireEvent.click(headerButton)).resolves.not.toThrow();
-    }
-
-    expect(warnSpy).toHaveBeenCalled();
-    warnSpy.mockRestore();
+    expect(headerButton).not.toBeNull();
+    await fireEvent.click(headerButton!);
+    expect(wrapper.textContent).toContain('"self": "[Circular]"');
   });
 });

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

@@ -1,4 +1,12 @@
-import { computed, defineComponent, onMounted, ref, watch } from "vue";
+import {
+  computed,
+  defineComponent,
+  h,
+  nextTick,
+  onMounted,
+  ref,
+  watch,
+} from "vue";
 import type { PropType } from "vue";
 import { screen, fireEvent, waitFor, cleanup } from "@testing-library/vue";
 import { afterEach, describe, expect, it } from "vitest";
@@ -27,6 +35,11 @@ import {
   textChunkEvent,
   testId,
 } from "../../__tests__/utils/test-helpers";
+import { mountWithProvider } from "../../__tests__/utils/mount";
+import {
+  StateCapturingAgent,
+  toolCallMessage,
+} from "../../__tests__/utils/agents";
 
 afterEach(() => {
   cleanup();
@@ -874,6 +887,10 @@ describe("useFrontendTool E2E - Dynamic Registration", () => {
         expect(firstVersion.textContent).toContain("before override");
       });
 
+      await agent.emit(runFinishedEvent());
+      // The tool call starts a follow-up run. A send waits for the run in
+      // flight (#5195), so finish the follow-up before the next message.
+      await agent.emit(runStartedEvent());
       await agent.emit(runFinishedEvent());
 
       const overrideButton = screen.getByTestId("activate-override");
@@ -912,6 +929,54 @@ describe("useFrontendTool E2E - Dynamic Registration", () => {
     });
   });
 
+  describe("Overriding a provider tool", () => {
+    it("brings the provider tool back after the overriding component unmounts", async () => {
+      const calls: string[] = [];
+      const lookupTool = (owner: string): VueFrontendTool => ({
+        name: "lookup",
+        parameters: z.object({}),
+        followUp: false,
+        handler: async () => {
+          calls.push(owner);
+          return owner;
+        },
+      });
+
+      const OverridingTool = defineComponent({
+        setup() {
+          useFrontendTool(lookupTool("component"));
+          return () => null;
+        },
+      });
+
+      const showOverride = ref(true);
+      const agent = new StateCapturingAgent(
+        [
+          { newMessages: [toolCallMessage("lookup")] },
+          { newMessages: [toolCallMessage("lookup")] },
+        ],
+        "test-agent",
+      );
+      const { getCore, wrapper } = mountWithProvider(
+        () => (showOverride.value ? h(OverridingTool) : h("div")),
+        {
+          frontendTools: [lookupTool("provider")],
+          agents__unsafe_dev_only: { "test-agent": agent },
+        },
+      );
+
+      await nextTick();
+      await getCore().runAgent({ agent });
+
+      showOverride.value = false;
+      await nextTick();
+      await getCore().runAgent({ agent });
+
+      expect(calls).toEqual(["component", "provider"]);
+      wrapper.unmount();
+    });
+  });
+
   describe("Integration with Chat UI", () => {
     it("should render tool output correctly in chat interface", async () => {
       const agent = new MockStepwiseAgent();

package/src/v2/hooks/__tests__/use-human-in-the-loop.e2e.test.ts

@@ -720,7 +720,12 @@ describe("useHumanInTheLoop E2E - HITL Tool Rendering", () => {
         expect(screen.queryByTestId("hitl-enabled")).toBeNull();
       });
 
-      await submitMessage("Test after disable");
+      // The first run still waits for the unanswered HITL prompt, and a send
+      // waits for the run in flight (#5195), so this message stays queued.
+      // What this test pins is that the unregistered tool no longer renders.
+      const input = await screen.findByRole("textbox");
+      await fireEvent.update(input, "Test after disable");
+      await fireEvent.keyDown(input, { key: "Enter", code: "Enter" });
 
       const messageId2 = testId("msg2");
       const toolCallId2 = testId("tc2");

package/src/v2/hooks/__tests__/use-human-in-the-loop.test.ts

@@ -4,7 +4,22 @@ import { z } from "zod";
 import type { AbstractAgent } from "@ag-ui/client";
 import { useHumanInTheLoop } from "../use-human-in-the-loop";
 import { mountWithProvider } from "../../__tests__/utils/mount";
-import { StateCapturingAgent } from "../../__tests__/utils/agents";
+import {
+  SequencedRunAgent,
+  StateCapturingAgent,
+  toolCallMessage,
+} from "../../__tests__/utils/agents";
+
+/** Handler context for one tool call; core always passes the call. */
+function callContext(id: string, name = "tool") {
+  return {
+    toolCall: {
+      id,
+      type: "function" as const,
+      function: { name, arguments: "{}" },
+    },
+  };
+}
 
 describe("useHumanInTheLoop", () => {
   beforeEach(() => {
@@ -53,7 +68,7 @@ describe("useHumanInTheLoop", () => {
 
     const pending = registeredTool!.handler!(
       { question: "Proceed?" },
-      {} as never,
+      callContext("tc-approve"),
     );
 
     const executingVNode = renderer!.render({
@@ -107,8 +122,8 @@ describe("useHumanInTheLoop", () => {
     const renderA = getCore().renderToolCalls.find((rc) => rc.name === "toolA");
     const renderB = getCore().renderToolCalls.find((rc) => rc.name === "toolB");
 
-    const pA = toolA!.handler!({}, {} as never);
-    const pB = toolB!.handler!({}, {} as never);
+    const pA = toolA!.handler!({}, callContext("tc-a"));
+    const pB = toolB!.handler!({}, callContext("tc-b"));
 
     const respondA = (
       renderA!.render({
@@ -140,6 +155,72 @@ describe("useHumanInTheLoop", () => {
     await expect(pB).resolves.toBe("B");
   });
 
+  it("gives parallel calls of one tool their own respond", async () => {
+    const RenderComp = defineComponent({
+      props: ["respond"],
+      setup() {
+        return () => h("div");
+      },
+    });
+    const Child = defineComponent({
+      setup() {
+        useHumanInTheLoop({
+          name: "parallelTool",
+          parameters: z.object({}),
+          render: RenderComp,
+        });
+        return () => null;
+      },
+    });
+    const { getCore } = mountWithProvider(() => h(Child));
+    const handler = getCore().getTool({ toolName: "parallelTool" })!.handler!;
+    const renderer = getCore().renderToolCalls.find(
+      (rc) => rc.name === "parallelTool",
+    )!;
+    const respondFor = (toolCallId: string) =>
+      (
+        renderer.render({
+          name: "parallelTool",
+          toolCallId,
+          args: {},
+          status: "executing",
+          result: undefined,
+        }) as { props?: { respond?: (result: unknown) => Promise<void> } }
+      ).props!.respond!;
+
+    const first = handler({}, callContext("call-1"));
+    const second = handler({}, callContext("call-2"));
+    await respondFor("call-2")("second");
+    await respondFor("call-1")("first");
+
+    await expect(first).resolves.toBe("first");
+    await expect(second).resolves.toBe("second");
+  });
+
+  it("passes the called tool's name to a catch-all render", () => {
+    const RenderComp = defineComponent({
+      setup() {
+        return () => h("div");
+      },
+    });
+    const Child = defineComponent({
+      setup() {
+        useHumanInTheLoop({ name: "*", render: RenderComp });
+        return () => null;
+      },
+    });
+    const { getCore } = mountWithProvider(() => h(Child));
+    const renderer = getCore().renderToolCalls.find((rc) => rc.name === "*")!;
+    const vnode = renderer.render({
+      name: "deleteFile",
+      toolCallId: "tc-any",
+      args: {},
+      status: "inProgress",
+      result: undefined,
+    }) as { props?: Record<string, unknown> };
+    expect(vnode.props?.name).toBe("deleteFile");
+  });
+
   it("only exposes respond during executing status", () => {
     const RenderComp = defineComponent({
       props: ["respond"],
@@ -323,9 +404,9 @@ describe("useHumanInTheLoop", () => {
       const controller = new AbortController();
       controller.abort();
 
-      await expect(handler!({}, { signal: controller.signal })).rejects.toEqual(
-        new Error("Human-in-the-loop interaction aborted"),
-      );
+      await expect(
+        handler!({}, { ...callContext("tc-x"), signal: controller.signal }),
+      ).rejects.toEqual(new Error("Human-in-the-loop interaction aborted"));
     });
 
     it("rejects once on abort, clears pending refs, and installs a one-shot listener", async () => {
@@ -344,7 +425,7 @@ describe("useHumanInTheLoop", () => {
         }),
       } as unknown as AbortSignal;
 
-      const pending = handler!({}, { signal });
+      const pending = handler!({}, { ...callContext("tc-aborted"), signal });
       expect(listeners.size).toBe(1);
       const onAbort = [...listeners][0];
       onAbort();
@@ -379,7 +460,13 @@ describe("useHumanInTheLoop", () => {
         }),
       } as unknown as AbortSignal;
 
-      const pending = handler!({}, { signal }).then((result) => {
+      const pending = handler!(
+        {},
+        {
+          ...callContext("tc-respond"),
+          signal,
+        },
+      ).then((result) => {
         events.push(`resolved:${String(result)}`);
         return result;
       });
@@ -511,10 +598,98 @@ describe("useHumanInTheLoop", () => {
       expect(vnode.props?.agentId).toBeUndefined();
     });
 
+    it("lets a message queued behind an unanswered prompt send after the prompt unmounts", async () => {
+      const prompt = toolCallMessage("unmountApproval");
+      const toolCallId = (prompt as { toolCalls: { id: string }[] })
+        .toolCalls[0]!.id;
+      const agent = new SequencedRunAgent(
+        [
+          () => ({ result: undefined, newMessages: [prompt] }),
+          () => ({
+            result: undefined,
+            newMessages: [{ id: "reply", role: "assistant", content: "ok" }],
+          }),
+        ],
+        "default",
+      );
+      const RenderComp = defineComponent({
+        setup() {
+          return () => h("div");
+        },
+      });
+      const shown = ref(true);
+      const Child = defineComponent({
+        setup() {
+          useHumanInTheLoop({
+            name: "unmountApproval",
+            parameters: z.object({}),
+            render: RenderComp,
+          });
+          return () => null;
+        },
+      });
+      const { getCore } = mountWithProvider(
+        () => (shown.value ? h(Child) : null),
+        {
+          agents__unsafe_dev_only: {
+            default: agent as unknown as AbstractAgent,
+          },
+        },
+      );
+      const core = getCore();
+      const sendMessage = async (content: string) => {
+        agent.addMessage({ id: content, role: "user", content });
+        await core.runAgent({ agent: agent as unknown as AbstractAgent });
+      };
+
+      const first = sendMessage("approve this");
+      const queued = first.then(() => sendMessage("next question"));
+      await vi.waitFor(() =>
+        expect(core.ɵhumanInTheLoop.isPending(toolCallId)).toBe(true),
+      );
+
+      shown.value = false;
+      await nextTick();
+
+      await expect(queued).resolves.toBeUndefined();
+      expect(agent.messages).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            role: "tool",
+            toolCallId,
+            error: "Human-in-the-loop interaction aborted",
+          }),
+          expect.objectContaining({ id: "reply", content: "ok" }),
+        ]),
+      );
+    });
+
     it("does not settle a pending HITL promise when its renderer unmounts", async () => {
-      const mounted = mountHitlTool();
-      const pending = mounted.handler({}, {});
-      mounted.wrapper.unmount();
+      const RenderComp = defineComponent({
+        setup() {
+          return () => h("div");
+        },
+      });
+      const shown = ref(true);
+      const Child = defineComponent({
+        setup() {
+          useHumanInTheLoop({
+            name: "unmountTool",
+            parameters: z.object({}),
+            render: RenderComp,
+          });
+          return () => null;
+        },
+      });
+      const { getCore } = mountWithProvider(() =>
+        shown.value ? h(Child) : null,
+      );
+      const pending = getCore().getTool({ toolName: "unmountTool" })!.handler!(
+        {},
+        callContext("tc-unmount"),
+      );
+      shown.value = false;
+      await nextTick();
 
       const outcome = await Promise.race([
         pending.then(