@copilotkit/vue 1.57.1

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

@@ -0,0 +1,268 @@
+import { defineComponent, ref, watchEffect, nextTick } from "vue";
+import type { Ref } from "vue";
+import { render, cleanup } from "@testing-library/vue";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+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";
+
+// Mock the CopilotKitProvider to control copilotkit state directly
+vi.mock("../../providers/useCopilotKit", () => ({
+  useCopilotKit: vi.fn(),
+}));
+
+const mockUseCopilotKit = useCopilotKit as ReturnType<typeof vi.fn>;
+
+/**
+ * Tests for useAgent referential stability during runtime connection lifecycle.
+ *
+ * Bug: useAgent creates multiple ProxiedCopilotRuntimeAgent instances during
+ * Disconnected→Connecting→Connected transitions because the useMemo recalculates
+ * on every dependency change and creates a new agent each time.
+ */
+describe("useAgent stability during runtime connection", () => {
+  type MockCopilotkit = {
+    getAgent: ReturnType<typeof vi.fn>;
+    runtimeUrl: string | undefined;
+    runtimeConnectionStatus: CopilotKitCoreRuntimeConnectionStatus;
+    runtimeTransport: string;
+    headers: Record<string, string>;
+    agents: Record<string, AbstractAgent>;
+    // Added after the hook moved to consume the shared core API. Mocks only
+    // need a no-op subscription object here; stability/ref-identity behavior
+    // is orthogonal to subscribe internals.
+    subscribeToAgentWithOptions: ReturnType<typeof vi.fn>;
+  };
+
+  let mockCopilotkit: MockCopilotkit;
+  let copilotkitRef: Ref<MockCopilotkit>;
+
+  beforeEach(() => {
+    copilotkitRef = ref({
+      getAgent: vi.fn(() => undefined),
+      runtimeUrl: "http://localhost:3000/api/copilotkit",
+      runtimeConnectionStatus:
+        CopilotKitCoreRuntimeConnectionStatus.Disconnected,
+      runtimeTransport: "rest",
+      headers: {},
+      agents: {},
+      subscribeToAgentWithOptions: vi.fn(() => ({ unsubscribe: vi.fn() })),
+    });
+    mockCopilotkit = copilotkitRef.value;
+
+    mockUseCopilotKit.mockReturnValue({
+      copilotkit: copilotkitRef,
+      executingToolCallIds: ref(new Set()),
+    });
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.restoreAllMocks();
+  });
+
+  it("should reuse the same provisional agent across re-renders during Disconnected→Connecting", async () => {
+    const agentInstances: AbstractAgent[] = [];
+
+    const AgentTracker = defineComponent({
+      props: {
+        tick: { type: Number, required: true },
+      },
+      setup() {
+        const { agent } = useAgent({ agentId: "test-agent" });
+
+        watchEffect(() => {
+          if (
+            agentInstances.length === 0 ||
+            agentInstances[agentInstances.length - 1] !== agent.value
+          ) {
+            agentInstances.push(agent.value);
+          }
+        });
+
+        return { agent };
+      },
+      template: `<div>{{ agent.threadId }}</div>`,
+    });
+
+    // Render 1: Disconnected — creates provisional agent
+    const { rerender } = render(AgentTracker, { props: { tick: 0 } });
+    await nextTick();
+    expect(agentInstances.length).toBe(1);
+    const provisionalThreadId = agentInstances[0]!.threadId;
+
+    // Render 2: Connecting — should reuse same provisional agent
+    mockCopilotkit.runtimeConnectionStatus =
+      CopilotKitCoreRuntimeConnectionStatus.Connecting;
+    await rerender({ tick: 1 });
+    await nextTick();
+
+    // BUG: Current code creates a new agent instance here (agentInstances.length === 2)
+    // FIX: Should still be 1 (same provisional reused)
+    expect(agentInstances.length).toBe(1);
+    expect(agentInstances[0]!.threadId).toBe(provisionalThreadId);
+  });
+
+  it("should reuse provisional agent when headers change during connecting", async () => {
+    const agentInstances: AbstractAgent[] = [];
+
+    const AgentTracker = defineComponent({
+      props: {
+        tick: { type: Number, required: true },
+      },
+      setup() {
+        const { agent } = useAgent({ agentId: "test-agent" });
+
+        watchEffect(() => {
+          if (
+            agentInstances.length === 0 ||
+            agentInstances[agentInstances.length - 1] !== agent.value
+          ) {
+            agentInstances.push(agent.value);
+          }
+        });
+
+        return { agent };
+      },
+      template: `<div>{{ agent.threadId }}</div>`,
+    });
+
+    // Render 1: Disconnected
+    const { rerender } = render(AgentTracker, { props: { tick: 0 } });
+    await nextTick();
+    expect(agentInstances.length).toBe(1);
+
+    // Render 2: Connecting
+    mockCopilotkit.runtimeConnectionStatus =
+      CopilotKitCoreRuntimeConnectionStatus.Connecting;
+    await rerender({ tick: 1 });
+    await nextTick();
+
+    // Render 3: Headers change (e.g., auth token set)
+    mockCopilotkit.headers = { "X-CopilotCloud-Public-Api-Key": "test-key" };
+    await rerender({ tick: 2 });
+    await nextTick();
+
+    // Render 4: Another minor change
+    mockCopilotkit.headers = {
+      "X-CopilotCloud-Public-Api-Key": "test-key",
+      "X-Custom": "value",
+    };
+    await rerender({ tick: 3 });
+    await nextTick();
+
+    // BUG: Current code creates a new agent on each re-render (agentInstances.length >= 3)
+    // FIX: Should still be 1 (same provisional reused throughout connecting phase)
+    expect(agentInstances.length).toBe(1);
+  });
+
+  it("should keep the same agent instance across the full Disconnected→Connected lifecycle", async () => {
+    const agentInstances: AbstractAgent[] = [];
+
+    const AgentTracker = defineComponent({
+      props: {
+        tick: { type: Number, required: true },
+      },
+      setup() {
+        const { agent } = useAgent({ agentId: "test-agent" });
+
+        watchEffect(() => {
+          if (
+            agentInstances.length === 0 ||
+            agentInstances[agentInstances.length - 1] !== agent.value
+          ) {
+            agentInstances.push(agent.value);
+          }
+        });
+
+        return { agent };
+      },
+      template: `<div>{{ agent.threadId }}</div>`,
+    });
+
+    // Phase 1: Disconnected — provisional created
+    const { rerender } = render(AgentTracker, { props: { tick: 0 } });
+    await nextTick();
+    const provisionalThreadId = agentInstances[0]!.threadId;
+
+    // Phase 2: Connecting
+    mockCopilotkit.runtimeConnectionStatus =
+      CopilotKitCoreRuntimeConnectionStatus.Connecting;
+    await rerender({ tick: 1 });
+    await nextTick();
+
+    // Phase 3: Headers change during connecting
+    mockCopilotkit.headers = { "X-Auth": "token" };
+    await rerender({ tick: 2 });
+    await nextTick();
+
+    // Phase 4: Connected — registered agent now available
+    const registeredAgent = new MockStepwiseAgent();
+    registeredAgent.agentId = "test-agent";
+    registeredAgent.description = "Agent from /info";
+
+    mockCopilotkit.getAgent.mockReturnValue(registeredAgent);
+    mockCopilotkit.runtimeConnectionStatus =
+      CopilotKitCoreRuntimeConnectionStatus.Connected;
+    mockCopilotkit.agents = { "test-agent": registeredAgent };
+    await rerender({ tick: 3 });
+    await nextTick();
+
+    // Phase 5: agents notification (separate re-render in real app)
+    await rerender({ tick: 4 });
+    await nextTick();
+
+    // 2 instances: 1 provisional (Disconnected/Connecting) + 1 registered (Connected).
+    // The provisional is stable across all pre-connection renders.
+    // 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);
+    // Second instance is the registered agent
+    expect(agentInstances[1]).toBe(registeredAgent);
+  });
+
+  it("should return local dev agents directly without a provisional", async () => {
+    const localAgent = new MockStepwiseAgent();
+    localAgent.agentId = "local-agent";
+
+    // Simulate agents__unsafe_dev_only: no runtimeUrl, agent found immediately
+    mockCopilotkit.runtimeUrl = undefined;
+    mockCopilotkit.getAgent.mockReturnValue(localAgent);
+    mockCopilotkit.agents = { "local-agent": localAgent };
+
+    const agentInstances: AbstractAgent[] = [];
+
+    const AgentTracker = defineComponent({
+      props: {
+        tick: { type: Number, required: true },
+      },
+      setup() {
+        const { agent } = useAgent({ agentId: "local-agent" });
+
+        watchEffect(() => {
+          if (
+            agentInstances.length === 0 ||
+            agentInstances[agentInstances.length - 1] !== agent.value
+          ) {
+            agentInstances.push(agent.value);
+          }
+        });
+
+        return { agent };
+      },
+      template: `<div>{{ agent.threadId }}</div>`,
+    });
+
+    const { rerender } = render(AgentTracker, { props: { tick: 0 } });
+    await rerender({ tick: 1 });
+    await nextTick();
+
+    // Local agent is returned directly — exactly 1 instance, the original
+    expect(agentInstances.length).toBe(1);
+    expect(agentInstances[0]).toBe(localAgent);
+  });
+});

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

@@ -0,0 +1,433 @@
+import { defineComponent, nextTick, ref, toRaw, watchEffect } from "vue";
+import { render, cleanup } from "@testing-library/vue";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { AbstractAgent, type BaseEvent } from "@ag-ui/client";
+import { CopilotKitCoreRuntimeConnectionStatus } from "@copilotkit/core";
+import { Observable } from "rxjs";
+import { useCopilotKit } from "../../providers/useCopilotKit";
+import { useAgent } from "../use-agent";
+
+vi.mock("../../providers/useCopilotKit", () => ({
+  useCopilotKit: vi.fn(),
+}));
+
+const mockUseCopilotKit = useCopilotKit as ReturnType<typeof vi.fn>;
+
+class CloneableAgent extends AbstractAgent {
+  clone(): CloneableAgent {
+    const cloned = new CloneableAgent();
+    cloned.agentId = this.agentId;
+    cloned.setMessages([...this.messages]);
+    return cloned;
+  }
+
+  run(): Observable<BaseEvent> {
+    return new Observable();
+  }
+}
+
+describe("useAgent thread isolation", () => {
+  let mockCopilotkit: {
+    getAgent: ReturnType<typeof vi.fn>;
+    runtimeUrl: string | undefined;
+    runtimeConnectionStatus: CopilotKitCoreRuntimeConnectionStatus;
+    runtimeTransport: string;
+    headers: Record<string, string>;
+    agents: Record<string, AbstractAgent>;
+    // Added after the hook moved to consume the shared core API. Mocks only
+    // need a no-op subscription object here; notification behavior is covered
+    // in `use-agent-throttle.test.ts`.
+    subscribeToAgentWithOptions: ReturnType<typeof vi.fn>;
+  };
+  let copilotkitRef: ReturnType<typeof ref<typeof mockCopilotkit>>;
+  let registeredAgent: CloneableAgent;
+
+  beforeEach(() => {
+    registeredAgent = new CloneableAgent();
+    registeredAgent.agentId = "my-agent";
+    mockCopilotkit = {
+      getAgent: vi.fn((id: string) =>
+        id === "my-agent" ? registeredAgent : undefined,
+      ),
+      runtimeUrl: "http://localhost:3000/api/copilotkit",
+      runtimeConnectionStatus: CopilotKitCoreRuntimeConnectionStatus.Connected,
+      runtimeTransport: "rest",
+      headers: {},
+      agents: { "my-agent": registeredAgent },
+      subscribeToAgentWithOptions: vi.fn(() => ({ unsubscribe: vi.fn() })),
+    };
+    copilotkitRef = ref(mockCopilotkit);
+    mockUseCopilotKit.mockReturnValue({
+      copilotkit: copilotkitRef,
+      executingToolCallIds: ref(new Set()),
+    });
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.restoreAllMocks();
+  });
+
+  it("returns different agent instances for different threadIds with the same agentId", async () => {
+    const agents: Record<string, AbstractAgent> = {};
+
+    const TrackerA = defineComponent({
+      setup(props) {
+        const { agent } = useAgent({
+          agentId: "my-agent",
+          threadId: "thread-a",
+        });
+        watchEffect(() => {
+          agents.a = agent.value;
+        });
+        return {};
+      },
+      template: "<div />",
+    });
+
+    const TrackerB = defineComponent({
+      setup(props) {
+        const { agent } = useAgent({
+          agentId: "my-agent",
+          threadId: "thread-b",
+        });
+        watchEffect(() => {
+          agents.b = agent.value;
+        });
+        return {};
+      },
+      template: "<div />",
+    });
+
+    const Host = defineComponent({
+      components: { TrackerA, TrackerB },
+      template: "<div><TrackerA /><TrackerB /></div>",
+    });
+
+    render(Host);
+    await nextTick();
+
+    expect(agents.a).toBeDefined();
+    expect(agents.b).toBeDefined();
+    expect(agents.a).not.toBe(agents.b);
+  });
+
+  it("returns the same cached instance for the same (agentId, threadId) across re-renders", async () => {
+    const instances: AbstractAgent[] = [];
+
+    const Tracker = defineComponent({
+      props: {
+        tick: { type: Number, required: true },
+      },
+      setup(props) {
+        const { agent } = useAgent({
+          agentId: "my-agent",
+          threadId: "thread-x",
+        });
+        watchEffect(() => {
+          const currentTick = props.tick;
+          void currentTick;
+          instances.push(agent.value);
+        });
+        return {};
+      },
+      template: "<div>{{ tick }}</div>",
+    });
+
+    const { rerender } = render(Tracker, {
+      props: { tick: 0 },
+    });
+    await nextTick();
+    await rerender({ tick: 1 });
+    await nextTick();
+
+    expect(instances.length).toBe(2);
+    expect(toRaw(instances[0]!)).toBe(toRaw(instances[1]!));
+  });
+
+  it("returns the shared registry agent when no threadId is provided (backward compat)", async () => {
+    const captured = ref<AbstractAgent | undefined>();
+    const Tracker = defineComponent({
+      setup() {
+        const { agent } = useAgent({ agentId: "my-agent" });
+        watchEffect(() => {
+          captured.value = agent.value;
+        });
+        return {};
+      },
+      template: "<div />",
+    });
+
+    render(Tracker);
+    await nextTick();
+    expect(toRaw(captured.value!)).toBe(registeredAgent);
+  });
+
+  it("isolates messages between thread-specific agents", async () => {
+    registeredAgent.addMessage({
+      id: "source-msg",
+      role: "user",
+      content: "pre-existing on source",
+    });
+
+    const agents: Record<string, AbstractAgent> = {};
+    const TrackerA = defineComponent({
+      setup() {
+        const { agent } = useAgent({
+          agentId: "my-agent",
+          threadId: "thread-a",
+        });
+        watchEffect(() => {
+          agents.a = agent.value;
+        });
+        return {};
+      },
+      template: "<div />",
+    });
+    const TrackerB = defineComponent({
+      setup() {
+        const { agent } = useAgent({
+          agentId: "my-agent",
+          threadId: "thread-b",
+        });
+        watchEffect(() => {
+          agents.b = agent.value;
+        });
+        return {};
+      },
+      template: "<div />",
+    });
+    const Host = defineComponent({
+      components: { TrackerA, TrackerB },
+      template: "<div><TrackerA /><TrackerB /></div>",
+    });
+
+    render(Host);
+    await nextTick();
+
+    expect(agents.a.messages).toHaveLength(0);
+    expect(agents.b.messages).toHaveLength(0);
+
+    agents.a.addMessage({
+      id: "msg-1",
+      role: "user",
+      content: "hello from thread A",
+    });
+
+    expect(agents.a.messages).toHaveLength(1);
+    expect(agents.b.messages).toHaveLength(0);
+  });
+
+  it("sets threadId on cloned agents", async () => {
+    const agents: Record<string, AbstractAgent> = {};
+    const TrackerA = defineComponent({
+      setup() {
+        const { agent } = useAgent({
+          agentId: "my-agent",
+          threadId: "thread-a",
+        });
+        watchEffect(() => {
+          agents.a = agent.value;
+        });
+        return {};
+      },
+      template: "<div />",
+    });
+    const TrackerB = defineComponent({
+      setup() {
+        const { agent } = useAgent({
+          agentId: "my-agent",
+          threadId: "thread-b",
+        });
+        watchEffect(() => {
+          agents.b = agent.value;
+        });
+        return {};
+      },
+      template: "<div />",
+    });
+    const Host = defineComponent({
+      components: { TrackerA, TrackerB },
+      template: "<div><TrackerA /><TrackerB /></div>",
+    });
+
+    render(Host);
+    await nextTick();
+
+    expect(agents.a.threadId).toBe("thread-a");
+    expect(agents.b.threadId).toBe("thread-b");
+  });
+
+  it("invalidates stale clone when the registry agent is replaced", async () => {
+    const capturedAgent = ref<AbstractAgent | undefined>();
+
+    const Tracker = defineComponent({
+      props: {
+        tid: { type: String, required: true },
+        tick: { type: Number, required: true },
+      },
+      setup(props) {
+        const { agent } = useAgent({
+          agentId: "my-agent",
+          threadId: () => props.tid,
+        });
+        watchEffect(() => {
+          capturedAgent.value = agent.value;
+        });
+        return {};
+      },
+      template: "<div>{{ tick }}</div>",
+    });
+
+    const { rerender } = render(Tracker, {
+      props: { tid: "thread-a", tick: 0 },
+    });
+    await nextTick();
+    const firstClone = capturedAgent.value;
+    expect(firstClone).not.toBe(registeredAgent);
+
+    const replacementAgent = new CloneableAgent();
+    replacementAgent.agentId = "my-agent";
+
+    copilotkitRef.value.agents = { "my-agent": replacementAgent };
+    copilotkitRef.value.getAgent = vi.fn((id: string) =>
+      id === "my-agent" ? replacementAgent : undefined,
+    );
+
+    await rerender({ tid: "thread-a", tick: 1 });
+    await nextTick();
+
+    const secondClone = capturedAgent.value;
+    expect(secondClone).not.toBe(firstClone);
+    expect(secondClone).not.toBe(replacementAgent);
+  });
+
+  it("switching threadId returns a fresh clone; switching back returns the cached one", async () => {
+    const capturedAgent = ref<AbstractAgent | undefined>();
+
+    const Tracker = defineComponent({
+      props: {
+        tid: { type: String, required: true },
+      },
+      setup(props) {
+        const { agent } = useAgent({
+          agentId: "my-agent",
+          threadId: () => props.tid,
+        });
+        watchEffect(() => {
+          capturedAgent.value = agent.value;
+        });
+        return {};
+      },
+      template: "<div />",
+    });
+
+    const { rerender } = render(Tracker, {
+      props: { tid: "thread-a" },
+    });
+    await nextTick();
+    const cloneA = capturedAgent.value;
+
+    await rerender({ tid: "thread-b" });
+    await nextTick();
+    const cloneB = capturedAgent.value;
+    expect(cloneB).not.toBe(cloneA);
+
+    await rerender({ tid: "thread-a" });
+    await nextTick();
+    expect(capturedAgent.value).toBe(cloneA);
+  });
+
+  it("uses a fresh clone with correct threadId when provisional transitions to real agent", async () => {
+    copilotkitRef.value.runtimeConnectionStatus =
+      CopilotKitCoreRuntimeConnectionStatus.Disconnected;
+    copilotkitRef.value.getAgent = vi.fn(() => undefined);
+    copilotkitRef.value.agents = {};
+
+    const capturedAgent = ref<AbstractAgent | undefined>();
+    const Tracker = defineComponent({
+      props: {
+        tick: { type: Number, required: true },
+      },
+      setup() {
+        const { agent } = useAgent({
+          agentId: "my-agent",
+          threadId: "thread-a",
+        });
+        watchEffect(() => {
+          capturedAgent.value = agent.value;
+        });
+        return {};
+      },
+      template: "<div>{{ tick }}</div>",
+    });
+
+    const { rerender } = render(Tracker, {
+      props: { tick: 0 },
+    });
+    await nextTick();
+    const provisional = capturedAgent.value!;
+    expect(provisional.threadId).toBe("thread-a");
+
+    copilotkitRef.value.runtimeConnectionStatus =
+      CopilotKitCoreRuntimeConnectionStatus.Connected;
+    copilotkitRef.value.getAgent = vi.fn((id: string) =>
+      id === "my-agent" ? registeredAgent : undefined,
+    );
+    copilotkitRef.value.agents = { "my-agent": registeredAgent };
+
+    await rerender({ tick: 1 });
+    await nextTick();
+
+    const realClone = capturedAgent.value!;
+    expect(realClone).not.toBe(provisional);
+    expect(realClone).not.toBe(registeredAgent);
+    expect(realClone.threadId).toBe("thread-a");
+  });
+
+  it("uses composite key for provisional agents when threadId is provided", async () => {
+    copilotkitRef.value.runtimeConnectionStatus =
+      CopilotKitCoreRuntimeConnectionStatus.Disconnected;
+    copilotkitRef.value.getAgent = vi.fn(() => undefined);
+    copilotkitRef.value.agents = {};
+
+    const agents: Record<string, AbstractAgent> = {};
+    const TrackerA = defineComponent({
+      setup() {
+        const { agent } = useAgent({
+          agentId: "my-agent",
+          threadId: "thread-a",
+        });
+        watchEffect(() => {
+          agents.a = agent.value;
+        });
+        return {};
+      },
+      template: "<div />",
+    });
+    const TrackerB = defineComponent({
+      setup() {
+        const { agent } = useAgent({
+          agentId: "my-agent",
+          threadId: "thread-b",
+        });
+        watchEffect(() => {
+          agents.b = agent.value;
+        });
+        return {};
+      },
+      template: "<div />",
+    });
+    const Host = defineComponent({
+      components: { TrackerA, TrackerB },
+      template: "<div><TrackerA /><TrackerB /></div>",
+    });
+
+    render(Host);
+    await nextTick();
+
+    expect(agents.a).not.toBe(agents.b);
+    expect(agents.a.threadId).toBe("thread-a");
+    expect(agents.b.threadId).toBe("thread-b");
+  });
+});