@copilotkit/vue 1.57.1

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

@@ -0,0 +1,282 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { defineComponent, h, nextTick, ref } from "vue";
+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";
+
+describe("useHumanInTheLoop", () => {
+  beforeEach(() => {
+    console.warn = vi.fn();
+    console.error = vi.fn();
+  });
+
+  it("resolves handler promise only via respond", async () => {
+    const RenderComp = defineComponent({
+      props: ["status", "respond"],
+      setup() {
+        return () => h("div");
+      },
+    });
+
+    const tool = {
+      name: "approveTool",
+      description: "Approve",
+      parameters: z.object({ question: z.string() }),
+      render: RenderComp,
+    };
+
+    const Child = defineComponent({
+      setup() {
+        useHumanInTheLoop(tool);
+        return () => null;
+      },
+    });
+
+    const { getCore } = mountWithProvider(() => h(Child), {
+      agents__unsafe_dev_only: {
+        "test-agent": new StateCapturingAgent(
+          [],
+          "test-agent",
+        ) as unknown as AbstractAgent,
+      },
+    });
+
+    const registeredTool = getCore().getTool({ toolName: "approveTool" });
+    const renderer = getCore().renderToolCalls.find(
+      (rc) => rc.name === "approveTool",
+    );
+
+    expect(registeredTool?.handler).toBeDefined();
+    expect(renderer).toBeDefined();
+
+    const pending = registeredTool!.handler!(
+      { question: "Proceed?" },
+      {} as never,
+    );
+
+    const executingVNode = renderer!.render({
+      name: "approveTool",
+      args: { question: "Proceed?" },
+      status: "executing",
+      result: undefined,
+    });
+
+    const respond = (
+      executingVNode as { props?: { respond?: (result: unknown) => void } }
+    )?.props?.respond;
+    expect(typeof respond).toBe("function");
+
+    respond?.({ approved: true });
+
+    await expect(pending).resolves.toEqual({ approved: true });
+  });
+
+  it("keeps HITL registrations isolated", async () => {
+    const RenderComp = defineComponent({
+      props: ["respond"],
+      setup() {
+        return () => h("div");
+      },
+    });
+
+    const ToolA = {
+      name: "toolA",
+      parameters: z.object({}),
+      render: RenderComp,
+    };
+    const ToolB = {
+      name: "toolB",
+      parameters: z.object({}),
+      render: RenderComp,
+    };
+
+    const Child = defineComponent({
+      setup() {
+        useHumanInTheLoop(ToolA);
+        useHumanInTheLoop(ToolB);
+        return () => null;
+      },
+    });
+
+    const { getCore } = mountWithProvider(() => h(Child));
+    const toolA = getCore().getTool({ toolName: "toolA" });
+    const toolB = getCore().getTool({ toolName: "toolB" });
+    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 respondA = (
+      renderA!.render({
+        name: "toolA",
+        args: {},
+        status: "executing",
+        result: undefined,
+      }) as {
+        props?: { respond?: (result: unknown) => void };
+      }
+    ).props?.respond;
+    const respondB = (
+      renderB!.render({
+        name: "toolB",
+        args: {},
+        status: "executing",
+        result: undefined,
+      }) as {
+        props?: { respond?: (result: unknown) => void };
+      }
+    ).props?.respond;
+
+    respondA?.("A");
+    respondB?.("B");
+
+    await expect(pA).resolves.toBe("A");
+    await expect(pB).resolves.toBe("B");
+  });
+
+  it("only exposes respond during executing status", () => {
+    const RenderComp = defineComponent({
+      props: ["respond"],
+      setup() {
+        return () => h("div");
+      },
+    });
+
+    const Child = defineComponent({
+      setup() {
+        useHumanInTheLoop({
+          name: "approveTool",
+          parameters: z.object({}),
+          render: RenderComp,
+        });
+        return () => null;
+      },
+    });
+
+    const { getCore } = mountWithProvider(() => h(Child));
+    const renderer = getCore().renderToolCalls.find(
+      (rc) => rc.name === "approveTool",
+    );
+
+    const inProgress = renderer!.render({
+      name: "approveTool",
+      args: {},
+      status: "inProgress",
+      result: undefined,
+    }) as {
+      props?: { respond?: unknown };
+    };
+    const executing = renderer!.render({
+      name: "approveTool",
+      args: {},
+      status: "executing",
+      result: undefined,
+    }) as {
+      props?: { respond?: unknown };
+    };
+    const complete = renderer!.render({
+      name: "approveTool",
+      args: {},
+      status: "complete",
+      result: "ok",
+    }) as {
+      props?: { respond?: unknown };
+    };
+
+    expect(inProgress.props?.respond).toBeUndefined();
+    expect(typeof executing.props?.respond).toBe("function");
+    expect(complete.props?.respond).toBeUndefined();
+  });
+
+  it("cleans up tool and renderer on unmount", async () => {
+    const RenderComp = defineComponent({
+      setup() {
+        return () => h("div");
+      },
+    });
+
+    const Parent = defineComponent({
+      setup() {
+        const shown = ref(true);
+        return () =>
+          h("div", [
+            h(
+              "button",
+              {
+                "data-testid": "toggle",
+                onClick: () => (shown.value = !shown.value),
+              },
+              "toggle",
+            ),
+            shown.value
+              ? h(
+                  defineComponent({
+                    setup() {
+                      useHumanInTheLoop({
+                        name: "cleanupTool",
+                        parameters: z.object({}),
+                        render: RenderComp,
+                      });
+                      return () => null;
+                    },
+                  }),
+                )
+              : null,
+          ]);
+      },
+    });
+
+    const { wrapper, getCore } = mountWithProvider(() => h(Parent));
+    await nextTick();
+
+    expect(getCore().getTool({ toolName: "cleanupTool" })).toBeDefined();
+    expect(
+      getCore().renderToolCalls.find((rc) => rc.name === "cleanupTool"),
+    ).toBeDefined();
+
+    await wrapper.find("[data-testid=toggle]").trigger("click");
+    await nextTick();
+
+    expect(getCore().getTool({ toolName: "cleanupTool" })).toBeUndefined();
+    expect(
+      getCore().renderToolCalls.find((rc) => rc.name === "cleanupTool"),
+    ).toBeUndefined();
+  });
+
+  it("re-registers when deps change", async () => {
+    const RenderComp = defineComponent({
+      setup() {
+        return () => h("div");
+      },
+    });
+
+    const version = ref(0);
+    const Child = defineComponent({
+      setup() {
+        useHumanInTheLoop(
+          { name: "depHitl", parameters: z.object({}), render: RenderComp },
+          [version],
+        );
+        return () =>
+          h(
+            "button",
+            { "data-testid": "bump", onClick: () => (version.value += 1) },
+            "bump",
+          );
+      },
+    });
+
+    const { wrapper, getCore } = mountWithProvider(() => h(Child));
+    const addToolSpy = vi.spyOn(getCore(), "addTool");
+
+    await wrapper.find("[data-testid=bump]").trigger("click");
+    await nextTick();
+
+    expect(addToolSpy).toHaveBeenCalled();
+    expect(getCore().getTool({ toolName: "depHitl" })).toBeDefined();
+    addToolSpy.mockRestore();
+  });
+});

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

@@ -0,0 +1,345 @@
+import { mount } from "@vue/test-utils";
+import { computed, defineComponent, h, nextTick } from "vue";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { useCopilotKit } from "../../providers/useCopilotKit";
+import { useAgent } from "../use-agent";
+import { useInterrupt } from "../use-interrupt";
+
+vi.mock("../../providers/useCopilotKit", () => ({
+  useCopilotKit: vi.fn(),
+}));
+
+vi.mock("../use-agent", () => ({
+  useAgent: vi.fn(),
+}));
+
+const mockUseCopilotKit = useCopilotKit as ReturnType<typeof vi.fn>;
+const mockUseAgent = useAgent as ReturnType<typeof vi.fn>;
+
+type SubscriptionHandlers = {
+  onCustomEvent?: (payload: {
+    event: { name: string; value: unknown };
+  }) => void;
+  onRunStartedEvent?: () => void;
+  onRunFinalized?: () => void;
+  onRunFailed?: () => void;
+};
+
+describe("useInterrupt", () => {
+  let runAgentMock: ReturnType<typeof vi.fn>;
+  let setInterruptStateMock: ReturnType<typeof vi.fn>;
+  let unsubscribeMock: ReturnType<typeof vi.fn>;
+  let subscribeMock: ReturnType<typeof vi.fn>;
+  let handlers: SubscriptionHandlers;
+  let mockAgent: Record<string, unknown>;
+  let coreState: {
+    runAgent: ReturnType<typeof vi.fn>;
+    setInterruptState: ReturnType<typeof vi.fn>;
+    interruptState: unknown;
+  };
+
+  beforeEach(() => {
+    runAgentMock = vi.fn().mockResolvedValue(undefined);
+    unsubscribeMock = vi.fn();
+    handlers = {};
+
+    subscribeMock = vi.fn((nextHandlers: SubscriptionHandlers) => {
+      handlers = nextHandlers;
+      return { unsubscribe: unsubscribeMock };
+    });
+
+    mockAgent = {
+      subscribe: subscribeMock,
+      id: "test-agent",
+    };
+
+    coreState = {
+      runAgent: runAgentMock,
+      setInterruptState: vi.fn((value: unknown) => {
+        coreState.interruptState = value;
+      }),
+      interruptState: null,
+    };
+    setInterruptStateMock = coreState.setInterruptState;
+
+    mockUseCopilotKit.mockReturnValue({
+      copilotkit: {
+        value: coreState,
+      },
+    });
+
+    mockUseAgent.mockReturnValue({
+      agent: computed(() => mockAgent),
+    });
+  });
+
+  function mountHarness(
+    options: {
+      enabled?: (event: { name: string; value: unknown }) => boolean;
+      handler?: (props: {
+        event: { name: string; value: unknown };
+        resolve: (response: unknown) => void;
+      }) => unknown;
+      renderInChat?: boolean;
+    } = {},
+  ) {
+    const Harness = defineComponent({
+      setup() {
+        const interrupt = useInterrupt({
+          enabled: options.enabled,
+          handler: options.handler,
+          renderInChat: options.renderInChat,
+        });
+
+        return () => {
+          const payload = interrupt.slotProps.value;
+          if (!payload) {
+            return h("div", { "data-testid": "interrupt-state" }, "idle");
+          }
+
+          return h(
+            "button",
+            {
+              "data-testid": "interrupt-state",
+              onClick: () =>
+                payload.resolve({
+                  approved: true,
+                  value: payload.event.value,
+                }),
+            },
+            `${String(payload.result ?? "no-result")}:${String(payload.event.value)}`,
+          );
+        };
+      },
+    });
+
+    return mount(Harness);
+  }
+
+  function emitInterrupt(value: unknown) {
+    handlers.onCustomEvent?.({
+      event: { name: "on_interrupt", value },
+    });
+    handlers.onRunFinalized?.();
+  }
+
+  it("subscribes on mount and unsubscribes on unmount", () => {
+    const wrapper = mountHarness({ renderInChat: false });
+
+    expect(subscribeMock).toHaveBeenCalledTimes(1);
+    expect(handlers.onCustomEvent).toBeTypeOf("function");
+    expect(handlers.onRunStartedEvent).toBeTypeOf("function");
+    expect(handlers.onRunFinalized).toBeTypeOf("function");
+    expect(handlers.onRunFailed).toBeTypeOf("function");
+
+    wrapper.unmount();
+    expect(unsubscribeMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("ignores non-interrupt custom events", () => {
+    const wrapper = mountHarness({ renderInChat: false });
+
+    handlers.onCustomEvent?.({
+      event: { name: "not_interrupt", value: "x" },
+    });
+    handlers.onRunFinalized?.();
+
+    expect(wrapper.get("[data-testid=interrupt-state]").text()).toBe("idle");
+  });
+
+  it("renders interrupt only after run finalized", async () => {
+    const wrapper = mountHarness({ renderInChat: false });
+
+    handlers.onCustomEvent?.({
+      event: { name: "on_interrupt", value: "pending" },
+    });
+    await nextTick();
+    expect(wrapper.get("[data-testid=interrupt-state]").text()).toBe("idle");
+
+    handlers.onRunFinalized?.();
+    await nextTick();
+    expect(wrapper.get("[data-testid=interrupt-state]").text()).toContain(
+      "pending",
+    );
+  });
+
+  it("clears pending interrupt on run start", async () => {
+    const wrapper = mountHarness({ renderInChat: false });
+
+    emitInterrupt("first");
+    await nextTick();
+    expect(wrapper.get("[data-testid=interrupt-state]").text()).toContain(
+      "first",
+    );
+
+    handlers.onRunStartedEvent?.();
+    await nextTick();
+    expect(wrapper.get("[data-testid=interrupt-state]").text()).toBe("idle");
+  });
+
+  it("resolve clears UI and resumes agent with response payload", async () => {
+    const wrapper = mountHarness({ renderInChat: false });
+
+    emitInterrupt("approve-me");
+    await nextTick();
+    await wrapper.get("[data-testid=interrupt-state]").trigger("click");
+    await nextTick();
+
+    expect(wrapper.get("[data-testid=interrupt-state]").text()).toBe("idle");
+    expect(runAgentMock).toHaveBeenCalledWith({
+      agent: mockAgent,
+      forwardedProps: {
+        command: {
+          resume: { approved: true, value: "approve-me" },
+          interruptEvent: "approve-me",
+        },
+      },
+    });
+  });
+
+  it("does not render and does not run handler when enabled returns false", async () => {
+    const handler = vi.fn(() => "should-not-run");
+    const wrapper = mountHarness({
+      renderInChat: false,
+      enabled: () => false,
+      handler,
+    });
+
+    emitInterrupt("blocked");
+    await nextTick();
+
+    expect(wrapper.get("[data-testid=interrupt-state]").text()).toBe("idle");
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("renders with null result when no handler is provided", async () => {
+    const wrapper = mountHarness({ renderInChat: false });
+
+    emitInterrupt("no-handler");
+    await nextTick();
+
+    expect(wrapper.get("[data-testid=interrupt-state]").text()).toContain(
+      "no-result:no-handler",
+    );
+  });
+
+  it("uses sync handler result in render", async () => {
+    const wrapper = mountHarness({
+      renderInChat: false,
+      handler: ({ event }) => `handled:${String(event.value)}`,
+    });
+
+    emitInterrupt("sync");
+    await nextTick();
+
+    expect(wrapper.get("[data-testid=interrupt-state]").text()).toContain(
+      "handled:sync",
+    );
+  });
+
+  it("uses async handler resolved value in render", async () => {
+    const wrapper = mountHarness({
+      renderInChat: false,
+      handler: ({ event }) => Promise.resolve(`async:${String(event.value)}`),
+    });
+
+    emitInterrupt("value");
+    await Promise.resolve();
+    await Promise.resolve();
+    await nextTick();
+
+    expect(wrapper.get("[data-testid=interrupt-state]").text()).toContain(
+      "async:value",
+    );
+  });
+
+  it("falls back to null result when async handler rejects", async () => {
+    const wrapper = mountHarness({
+      renderInChat: false,
+      handler: () => Promise.reject(new Error("boom")),
+    });
+
+    emitInterrupt("reject");
+    await Promise.resolve();
+    await Promise.resolve();
+    await nextTick();
+
+    expect(wrapper.get("[data-testid=interrupt-state]").text()).toContain(
+      "no-result:reject",
+    );
+  });
+
+  it("accepts thenable handler results (non-native Promise)", async () => {
+    const wrapper = mountHarness({
+      renderInChat: false,
+      handler: () => Promise.resolve("thenable-ok"),
+    });
+
+    emitInterrupt("thenable");
+    await Promise.resolve();
+    await Promise.resolve();
+    await nextTick();
+
+    expect(wrapper.get("[data-testid=interrupt-state]").text()).toContain(
+      "thenable-ok:thenable",
+    );
+  });
+
+  it("publishes interrupt element to chat by default and clears on unmount", async () => {
+    const wrapper = mountHarness();
+
+    emitInterrupt("chat");
+    await nextTick();
+
+    expect(setInterruptStateMock).toHaveBeenCalled();
+    expect(setInterruptStateMock.mock.calls.at(-1)?.[0]).toMatchObject({
+      event: { name: "on_interrupt", value: "chat" },
+      result: null,
+    });
+
+    wrapper.unmount();
+    expect(setInterruptStateMock.mock.calls.at(-1)?.[0]).toBeNull();
+  });
+
+  it("does not publish to chat and returns manual element when renderInChat is false", async () => {
+    const wrapper = mountHarness({ renderInChat: false });
+
+    emitInterrupt("manual");
+    await nextTick();
+
+    expect(wrapper.get("[data-testid=interrupt-state]").text()).toContain(
+      "manual",
+    );
+    expect(setInterruptStateMock).not.toHaveBeenCalled();
+  });
+
+  it("discards local interrupt when run fails before finalize", async () => {
+    const wrapper = mountHarness({ renderInChat: false });
+
+    handlers.onCustomEvent?.({
+      event: { name: "on_interrupt", value: "lost" },
+    });
+    handlers.onRunFailed?.();
+    handlers.onRunFinalized?.();
+    await nextTick();
+
+    expect(wrapper.get("[data-testid=interrupt-state]").text()).toBe("idle");
+  });
+
+  it("keeps the latest interrupt when multiple interrupts arrive within one run", async () => {
+    const wrapper = mountHarness({ renderInChat: false });
+
+    handlers.onCustomEvent?.({
+      event: { name: "on_interrupt", value: "first" },
+    });
+    handlers.onCustomEvent?.({
+      event: { name: "on_interrupt", value: "second" },
+    });
+    handlers.onRunFinalized?.();
+    await nextTick();
+
+    expect(wrapper.get("[data-testid=interrupt-state]").text()).toContain(
+      "second",
+    );
+  });
+});

package/src/v2/hooks/__tests__/use-katex-styles.test.ts

@@ -0,0 +1,69 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { defineComponent, h, nextTick } from "vue";
+import { render } from "@testing-library/vue";
+
+// Mock the katex CSS import globally so the dynamic import resolves cleanly
+// in the test environment.
+vi.mock("katex/dist/katex.min.css", () => ({}));
+
+describe("useKatexStyles", () => {
+  beforeEach(() => {
+    // Reset module state (the singleton `injected` flag) between tests so
+    // each case can exercise the dynamic-import branch.
+    vi.resetModules();
+  });
+
+  async function loadHook() {
+    const mod = await import("../use-katex-styles");
+    return mod.useKatexStyles;
+  }
+
+  function mountWith(hook: () => void) {
+    return render(
+      defineComponent({
+        setup() {
+          hook();
+          return () => h("div");
+        },
+      }),
+    );
+  }
+
+  it("renders without error (dynamic import succeeds)", async () => {
+    const useKatexStyles = await loadHook();
+
+    expect(() => {
+      mountWith(useKatexStyles);
+    }).not.toThrow();
+    await nextTick();
+  });
+
+  it("does not throw when katex CSS import fails", async () => {
+    vi.doMock("katex/dist/katex.min.css", () => {
+      throw new Error("CSS not found");
+    });
+
+    const useKatexStyles = await loadHook();
+
+    expect(() => {
+      mountWith(useKatexStyles);
+    }).not.toThrow();
+    await nextTick();
+  });
+
+  it("does not use a static katex CSS import in the component", async () => {
+    // Regression guard: ensure the static import doesn't creep back.
+    const fs = await import("fs");
+    const path = await import("path");
+    const componentPath = path.resolve(
+      __dirname,
+      "../../components/chat/CopilotChatAssistantMessage.vue",
+    );
+    const source = fs.readFileSync(componentPath, "utf-8");
+
+    // Should NOT have a static import of katex CSS anywhere in the SFC.
+    expect(source).not.toMatch(/import\s+['"]katex\/dist\/katex\.min\.css['"]/);
+    // Should use the composable instead.
+    expect(source).toMatch(/useKatexStyles/);
+  });
+});