@copilotkit/vue 1.73.0 → 1.73.1

package/src/v2/providers/__tests__/CopilotKitProvider.hitl.e2e.test.ts

@@ -0,0 +1,192 @@
+/**
+ * End-to-end coverage for the `humanInTheLoop` **prop** path (OSS-803).
+ *
+ * The unit tests in CopilotKitProvider.test.ts drive the registered renderer
+ * directly. This file mounts the real pipeline instead — CopilotChat →
+ * CopilotChatToolCallsView → the provider's wrapper — so the wrapper is
+ * exercised as a Vue functional component and the pending-interaction key comes
+ * from core's real tool call id rather than a synthesized handler context.
+ */
+import { defineComponent } from "vue";
+import type { PropType } from "vue";
+import { screen, fireEvent, waitFor, cleanup } from "@testing-library/vue";
+import { afterEach, describe, expect, it } from "vitest";
+import { z } from "zod";
+import { ToolCallStatus } from "@copilotkit/core";
+import CopilotChat from "../../components/chat/CopilotChat.vue";
+import {
+  MockStepwiseAgent,
+  renderWithCopilotKit,
+  runStartedEvent,
+  runFinishedEvent,
+  toolCallChunkEvent,
+  testId,
+} from "../../__tests__/utils/test-helpers";
+
+afterEach(() => {
+  cleanup();
+});
+
+const HITLRenderer = defineComponent({
+  props: {
+    name: { type: String, required: true },
+    description: { type: String, required: true },
+    status: { type: String as PropType<ToolCallStatus>, required: true },
+    args: {
+      type: Object as PropType<{ action?: string }>,
+      required: true,
+    },
+    result: { type: String, required: false },
+    respond: {
+      type: Function as PropType<
+        ((result: unknown) => Promise<void>) | undefined
+      >,
+      required: false,
+    },
+  },
+  template: `
+    <div data-testid="hitl-tool">
+      <div data-testid="hitl-name">{{ name }}</div>
+      <div data-testid="hitl-description">{{ description }}</div>
+      <div data-testid="hitl-status">{{ status }}</div>
+      <div data-testid="hitl-action">{{ args.action ?? "" }}</div>
+      <button
+        v-if="respond"
+        data-testid="hitl-approve"
+        @click="respond(JSON.stringify({ approved: true }))"
+      >
+        Approve
+      </button>
+      <div v-if="result" data-testid="hitl-result">{{ result }}</div>
+    </div>
+  `,
+});
+
+const ChatHost = defineComponent({
+  components: { CopilotChat },
+  template: `
+    <div style="height: 400px;">
+      <CopilotChat :welcome-screen="false" />
+    </div>
+  `,
+});
+
+async function submitMessage(value: string) {
+  const input = await screen.findByRole("textbox");
+  await fireEvent.update(input, value);
+  await fireEvent.keyDown(input, { key: "Enter", code: "Enter" });
+  await waitFor(() => {
+    expect(screen.getByText(value)).toBeDefined();
+  });
+}
+
+describe("CopilotKitProvider humanInTheLoop prop E2E", () => {
+  it("waits for the user and completes with the response", async () => {
+    const agent = new MockStepwiseAgent();
+
+    renderWithCopilotKit({
+      agent,
+      humanInTheLoop: [
+        {
+          name: "approvalTool",
+          description: "Requires human approval",
+          parameters: z.object({ action: z.string() }),
+          render: HITLRenderer,
+        },
+      ],
+      children: ChatHost,
+    });
+
+    await submitMessage("Request approval");
+
+    await agent.emit(runStartedEvent());
+    await agent.emit(
+      toolCallChunkEvent({
+        toolCallId: testId("tc"),
+        toolCallName: "approvalTool",
+        parentMessageId: testId("msg"),
+        delta: JSON.stringify({ action: "delete" }),
+      }),
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("hitl-status").textContent).toBe(
+        ToolCallStatus.InProgress,
+      );
+    });
+    expect(screen.getByTestId("hitl-name").textContent).toBe("approvalTool");
+    expect(screen.getByTestId("hitl-description").textContent).toBe(
+      "Requires human approval",
+    );
+    expect(screen.getByTestId("hitl-action").textContent).toBe("delete");
+
+    await agent.emit(runFinishedEvent());
+    await agent.complete();
+
+    // The run has finished, so the tool handler is now executing. Before the
+    // fix the handler had already resolved undefined, so the card never reached
+    // Executing and no approve button was ever rendered.
+    const approveButton = await screen.findByTestId("hitl-approve");
+    expect(screen.getByTestId("hitl-status").textContent).toBe(
+      ToolCallStatus.Executing,
+    );
+
+    await fireEvent.click(approveButton);
+
+    await waitFor(() => {
+      expect(screen.getByTestId("hitl-status").textContent).toBe(
+        ToolCallStatus.Complete,
+      );
+      expect(screen.getByTestId("hitl-result").textContent).toContain(
+        "approved",
+      );
+    });
+  });
+
+  it("passes the invoked tool name to a wildcard registration", async () => {
+    const agent = new MockStepwiseAgent();
+
+    renderWithCopilotKit({
+      agent,
+      humanInTheLoop: [
+        {
+          name: "*",
+          description: "Approve any tool",
+          parameters: z.object({ action: z.string() }),
+          render: HITLRenderer,
+        },
+      ],
+      children: ChatHost,
+    });
+
+    await submitMessage("Delete the file");
+
+    await agent.emit(runStartedEvent());
+    await agent.emit(
+      toolCallChunkEvent({
+        toolCallId: testId("tc"),
+        toolCallName: "deleteFile",
+        parentMessageId: testId("msg"),
+        delta: JSON.stringify({ action: "delete" }),
+      }),
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("hitl-name").textContent).toBe("deleteFile");
+    });
+
+    await agent.emit(runFinishedEvent());
+    await agent.complete();
+
+    const approveButton = await screen.findByTestId("hitl-approve");
+    expect(screen.getByTestId("hitl-name").textContent).toBe("deleteFile");
+
+    await fireEvent.click(approveButton);
+
+    await waitFor(() => {
+      expect(screen.getByTestId("hitl-status").textContent).toBe(
+        ToolCallStatus.Complete,
+      );
+    });
+  });
+});

package/src/v2/providers/__tests__/CopilotKitProvider.messageFilter.test.ts

@@ -0,0 +1,159 @@
+import { cleanup, render } from "@testing-library/vue";
+import { defineComponent, nextTick } from "vue";
+import type { Component, PropType } from "vue";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { CopilotKitMessageFilter } from "@copilotkit/core";
+import CopilotKitProvider from "../CopilotKitProvider.vue";
+import { useCopilotKit } from "../useCopilotKit";
+import type * as VueCoreModule from "../../lib/vue-core";
+import type { CopilotKitCoreVue } from "../../lib/vue-core";
+
+/** Keeps the final turn only — the shape #1482 asks for. */
+const keepLastTurn: CopilotKitMessageFilter = (messages) => messages.slice(-1);
+/** A second, distinguishable filter, for asserting a swap took effect. */
+const keepLastTwo: CopilotKitMessageFilter = (messages) => messages.slice(-2);
+
+/**
+ * Every config the provider constructed a core with, in order. The real class
+ * still does the work — only the constructor argument is recorded — so these
+ * tests read the same core the app would get.
+ */
+const ctorConfigs: { messageFilter?: CopilotKitMessageFilter }[] = [];
+
+vi.mock("../../lib/vue-core", async (importOriginal) => {
+  const actual = await importOriginal<typeof VueCoreModule>();
+  class RecordingCore extends actual.CopilotKitCoreVue {
+    constructor(
+      config: ConstructorParameters<typeof actual.CopilotKitCoreVue>[0],
+    ) {
+      ctorConfigs.push(config as { messageFilter?: CopilotKitMessageFilter });
+      super(config);
+    }
+  }
+  return { ...actual, CopilotKitCoreVue: RecordingCore };
+});
+
+/**
+ * Parity with React's `messageFilter` prop (#1482). The filter itself is
+ * covered by `packages/core/src/__tests__/message-filter.test.ts`; what is
+ * framework-specific, and what these assert, is that the prop reaches the core
+ * both on mount and on a later change — including a change back to
+ * `undefined`, which is how an app turns trimming off.
+ */
+function renderProvider(args: {
+  child: Component;
+  messageFilter?: CopilotKitMessageFilter;
+}) {
+  const Host = defineComponent({
+    components: {
+      CopilotKitProvider,
+      ChildComponent: args.child,
+    },
+    props: {
+      messageFilter: {
+        type: Function as PropType<CopilotKitMessageFilter | undefined>,
+        required: false,
+        default: undefined,
+      },
+    },
+    template: `
+      <CopilotKitProvider
+        runtime-url="/api/copilotkit"
+        :message-filter="messageFilter"
+      >
+        <ChildComponent />
+      </CopilotKitProvider>
+    `,
+  });
+
+  return render(Host, {
+    props: { messageFilter: args.messageFilter },
+  });
+}
+
+function createCoreCollector(): {
+  child: Component;
+  getCore: () => CopilotKitCoreVue;
+} {
+  const instances: CopilotKitCoreVue[] = [];
+  const Collector = defineComponent({
+    setup() {
+      const { copilotkit } = useCopilotKit();
+      instances.push(copilotkit.value);
+      return () => null;
+    },
+  });
+  return {
+    child: Collector,
+    getCore: () => {
+      if (instances.length === 0) {
+        throw new Error("CopilotKit core not captured yet");
+      }
+      return instances[instances.length - 1]!;
+    },
+  };
+}
+
+describe("CopilotKitProvider messageFilter", () => {
+  beforeEach(() => {
+    ctorConfigs.length = 0;
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("hands the filter to the core at construction, not only on mount", async () => {
+    const { child } = createCoreCollector();
+    renderProvider({ child, messageFilter: keepLastTurn });
+    await nextTick();
+
+    // The core opens its `/info` request from the constructor, and an agent
+    // that response advertises is built with whatever filter the core holds
+    // at that moment. A filter applied only from the mount effect would let
+    // that first agent make its first run with the whole thread.
+    expect(ctorConfigs.length).toBeGreaterThanOrEqual(1);
+    expect(ctorConfigs[0]?.messageFilter).toBe(keepLastTurn);
+  });
+
+  it("threads the filter to the core on mount", async () => {
+    const { child, getCore } = createCoreCollector();
+    renderProvider({ child, messageFilter: keepLastTurn });
+    await nextTick();
+
+    expect(getCore().messageFilter).toBe(keepLastTurn);
+  });
+
+  it("leaves the core unfiltered when the prop is absent", async () => {
+    const { child, getCore } = createCoreCollector();
+
+    renderProvider({ child });
+    await nextTick();
+
+    expect(getCore().messageFilter).toBeUndefined();
+  });
+
+  it("adopts a filter the app swaps in after mount", async () => {
+    const { child, getCore } = createCoreCollector();
+    const view = renderProvider({ child, messageFilter: keepLastTurn });
+    await nextTick();
+    expect(getCore().messageFilter).toBe(keepLastTurn);
+
+    await view.rerender({ messageFilter: keepLastTwo });
+    await nextTick();
+
+    expect(getCore().messageFilter).toBe(keepLastTwo);
+  });
+
+  it("clears the filter when the prop goes back to undefined", async () => {
+    const { child, getCore } = createCoreCollector();
+    const view = renderProvider({ child, messageFilter: keepLastTurn });
+    await nextTick();
+    expect(getCore().messageFilter).toBe(keepLastTurn);
+
+    await view.rerender({ messageFilter: undefined });
+    await nextTick();
+
+    expect(getCore().messageFilter).toBeUndefined();
+  });
+});

package/src/v2/providers/__tests__/CopilotKitProvider.test.ts

@@ -9,12 +9,16 @@ import {
   ref,
   watchEffect,
 } from "vue";
+import type { VNode } from "vue";
 import { renderToString } from "vue/server-renderer";
 import type {
   CopilotKitCoreSubscriber,
   FrontendToolHandlerContext,
 } from "@copilotkit/core";
-import { CopilotKitCoreRuntimeConnectionStatus } from "@copilotkit/core";
+import {
+  CopilotKitCoreRuntimeConnectionStatus,
+  ToolCallStatus,
+} from "@copilotkit/core";
 import { defineWebInspector } from "@copilotkit/web-inspector";
 import { z } from "zod";
 import CopilotKitProvider from "../CopilotKitProvider.vue";
@@ -338,12 +342,45 @@ describe("CopilotKitProvider", () => {
   });
 
   describe("humanInTheLoop prop", () => {
+    const HitlComponent = defineComponent({
+      setup() {
+        return () => h("div", "Test");
+      },
+    });
+
+    /** A handler context shaped like the one core passes to frontend tools. */
+    const hitlContext = (toolCallId: string, signal?: AbortSignal) =>
+      ({
+        toolCall: { id: toolCallId },
+        signal,
+      }) as unknown as FrontendToolHandlerContext;
+
+    /**
+     * Invokes the provider's registered renderer the way `useRenderToolCall`
+     * does and returns the props it forwarded to the user's component. The
+     * wrapper builds its VNode with `h()`, so the injected props are readable
+     * without mounting.
+     */
+    const renderHitl = (
+      getCore: () => CopilotKitCoreContextValue,
+      registeredName: string,
+      props: Record<string, unknown>,
+    ) => {
+      const render = getCore().renderToolCalls.find(
+        (rc) => rc.name === registeredName,
+      )?.render as (p: Record<string, unknown>) => VNode;
+      return render(props).props as {
+        name?: string;
+        description?: string;
+        agentId?: string;
+        respond?: (result: unknown) => Promise<void>;
+      };
+    };
+
+    const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
+
     it("processes humanInTheLoop tools and creates handlers", () => {
-      const TestComponent = defineComponent({
-        setup() {
-          return () => h("div", "Test");
-        },
-      });
+      const TestComponent = HitlComponent;
       const humanInTheLoop: VueHumanInTheLoop[] = [
         {
           name: "approvalTool",
@@ -358,25 +395,101 @@ describe("CopilotKitProvider", () => {
       expect(tool).toBeDefined();
       expect(tool?.handler).toBeDefined();
 
+      // The registered renderer wraps the user's component so `respond` and the
+      // tool's description can be injected per status.
       const renderTool = getCore().renderToolCalls.find(
         (rc) => rc.name === "approvalTool",
       );
       expect(renderTool).toBeDefined();
-      expect(renderTool?.render).toStrictEqual(TestComponent);
+      expect(typeof renderTool?.render).toBe("function");
     });
 
-    it("creates placeholder handlers for humanInTheLoop tools", async () => {
-      const TestComponent = defineComponent({
-        setup() {
-          return () => h("div", "Test");
+    it("keeps the tool call pending until respond is called", async () => {
+      // Reproduces OSS-803: the handler used to warn and resolve undefined
+      // immediately, so the HITL UI flashed and disappeared instead of waiting
+      // for the user.
+      const humanInTheLoop: VueHumanInTheLoop[] = [
+        {
+          name: "interactiveTool",
+          description: "Interactive tool",
+          parameters: z.object({ data: z.string() }),
+          render: HitlComponent,
+        },
+      ];
+
+      const { getCore } = mountWithProvider(() => h("div"), { humanInTheLoop });
+      const handler = getCore().getTool({
+        toolName: "interactiveTool",
+      })?.handler;
+      expect(handler).toBeDefined();
+
+      let settled = false;
+      const pending = handler!({ data: "test" }, hitlContext("tc-1")).then(
+        (result) => {
+          settled = true;
+          return result;
         },
+      );
+
+      await flush();
+      expect(settled).toBe(false);
+      expect(consoleWarnSpy).not.toHaveBeenCalledWith(
+        expect.stringContaining("no interactive handler is set up"),
+      );
+
+      const props = renderHitl(getCore, "interactiveTool", {
+        name: "interactiveTool",
+        toolCallId: "tc-1",
+        args: { data: "test" },
+        status: ToolCallStatus.Executing,
+        result: undefined,
       });
+
+      expect(props.respond).toBeDefined();
+      await props.respond!("approved");
+
+      await expect(pending).resolves.toBe("approved");
+    });
+
+    it("exposes respond only while the tool is executing", () => {
       const humanInTheLoop: VueHumanInTheLoop[] = [
         {
           name: "interactiveTool",
           description: "Interactive tool",
           parameters: z.object({ data: z.string() }),
-          render: TestComponent,
+          render: HitlComponent,
+        },
+      ];
+
+      const { getCore } = mountWithProvider(() => h("div"), { humanInTheLoop });
+
+      const inProgress = renderHitl(getCore, "interactiveTool", {
+        name: "interactiveTool",
+        toolCallId: "tc-1",
+        args: { data: "test" },
+        status: ToolCallStatus.InProgress,
+        result: undefined,
+      });
+      expect(inProgress.respond).toBeUndefined();
+      expect(inProgress.description).toBe("Interactive tool");
+
+      const complete = renderHitl(getCore, "interactiveTool", {
+        name: "interactiveTool",
+        toolCallId: "tc-1",
+        args: { data: "test" },
+        status: ToolCallStatus.Complete,
+        result: "approved",
+      });
+      expect(complete.respond).toBeUndefined();
+    });
+
+    it("rejects the pending tool call when the run is aborted", async () => {
+      const humanInTheLoop: VueHumanInTheLoop[] = [
+        {
+          name: "interactiveTool",
+          description: "Interactive tool",
+          parameters: z.object({ data: z.string() }),
+          render: HitlComponent,
         },
       ];
 
@@ -384,19 +497,147 @@ describe("CopilotKitProvider", () => {
       const handler = getCore().getTool({
         toolName: "interactiveTool",
       })?.handler;
-      expect(handler).toBeDefined();
 
-      const result = await handler!(
+      const controller = new AbortController();
+      const pending = handler!(
         { data: "test" },
-        {} as unknown as FrontendToolHandlerContext,
+        hitlContext("tc-1", controller.signal),
       );
-      expect(result).toBeUndefined();
-      expect(consoleWarnSpy).toHaveBeenCalledWith(
-        expect.stringContaining(
-          "Human-in-the-loop tool 'interactiveTool' called",
-        ),
+
+      controller.abort();
+
+      // An explicit rejection makes core record an error tool result rather
+      // than silently resolving empty (#5554).
+      await expect(pending).rejects.toThrow(
+        "Human-in-the-loop interaction aborted",
       );
     });
+
+    it("rejects immediately when the run was already aborted", async () => {
+      const humanInTheLoop: VueHumanInTheLoop[] = [
+        {
+          name: "interactiveTool",
+          description: "Interactive tool",
+          parameters: z.object({ data: z.string() }),
+          render: HitlComponent,
+        },
+      ];
+
+      const { getCore } = mountWithProvider(() => h("div"), { humanInTheLoop });
+      const handler = getCore().getTool({
+        toolName: "interactiveTool",
+      })?.handler;
+
+      const controller = new AbortController();
+      controller.abort();
+
+      await expect(
+        handler!({ data: "test" }, hitlContext("tc-1", controller.signal)),
+      ).rejects.toThrow("Human-in-the-loop interaction aborted");
+    });
+
+    it("keeps parallel interrupts on the same tool independent", async () => {
+      const humanInTheLoop: VueHumanInTheLoop[] = [
+        {
+          name: "interactiveTool",
+          description: "Interactive tool",
+          parameters: z.object({ data: z.string() }),
+          render: HitlComponent,
+        },
+      ];
+
+      const { getCore } = mountWithProvider(() => h("div"), { humanInTheLoop });
+      const handler = getCore().getTool({
+        toolName: "interactiveTool",
+      })?.handler;
+
+      const first = handler!({ data: "one" }, hitlContext("tc-1"));
+      const second = handler!({ data: "two" }, hitlContext("tc-2"));
+
+      let firstSettled = false;
+      void first.then(() => {
+        firstSettled = true;
+      });
+      let secondSettled = false;
+      void second.then(() => {
+        secondSettled = true;
+      });
+
+      // Respond to the second tool call only.
+      const secondProps = renderHitl(getCore, "interactiveTool", {
+        name: "interactiveTool",
+        toolCallId: "tc-2",
+        args: { data: "two" },
+        status: ToolCallStatus.Executing,
+        result: undefined,
+      });
+      await secondProps.respond!("two-approved");
+      await expect(second).resolves.toBe("two-approved");
+
+      // The first is still waiting on its own user response.
+      await flush();
+      expect(firstSettled).toBe(false);
+      expect(secondSettled).toBe(true);
+
+      const firstProps = renderHitl(getCore, "interactiveTool", {
+        name: "interactiveTool",
+        toolCallId: "tc-1",
+        args: { data: "one" },
+        status: ToolCallStatus.Executing,
+        result: undefined,
+      });
+      await firstProps.respond!("one-approved");
+      await expect(first).resolves.toBe("one-approved");
+    });
+
+    it("passes the actual invoked tool name to a wildcard HITL renderer", () => {
+      const humanInTheLoop: VueHumanInTheLoop[] = [
+        {
+          name: "*",
+          description: "Approve any tool",
+          parameters: z.object({ data: z.string() }),
+          render: HitlComponent,
+        },
+      ];
+
+      const { getCore } = mountWithProvider(() => h("div"), { humanInTheLoop });
+
+      const props = renderHitl(getCore, "*", {
+        name: "deleteFile",
+        toolCallId: "tc-1",
+        args: { data: "test" },
+        status: ToolCallStatus.Executing,
+        result: undefined,
+      });
+
+      expect(props.name).toBe("deleteFile");
+    });
+
+    it("passes agentId through to the HITL renderer", () => {
+      const humanInTheLoop: VueHumanInTheLoop[] = [
+        {
+          name: "scopedTool",
+          description: "Scoped to one agent",
+          parameters: z.object({ data: z.string() }),
+          agentId: "specific-agent",
+          render: HitlComponent,
+        },
+      ];
+
+      const { getCore } = mountWithProvider(() => h("div"), { humanInTheLoop });
+
+      // `VueHumanInTheLoopRenderProps` declares `agentId`, and the
+      // `useHumanInTheLoop` composable supplies it. The prop path must too.
+      const props = renderHitl(getCore, "scopedTool", {
+        name: "scopedTool",
+        toolCallId: "tc-1",
+        args: { data: "test" },
+        status: ToolCallStatus.Executing,
+        result: undefined,
+      });
+
+      expect(props.agentId).toBe("specific-agent");
+    });
   });
 
   describe("Combined tools functionality", () => {
@@ -497,7 +738,20 @@ describe("CopilotKitProvider", () => {
       expect(frontendRenderTool).toBeDefined();
       expect(humanRenderTool).toBeDefined();
       expect(frontendRenderTool?.render).toStrictEqual(TestComponent1);
-      expect(humanRenderTool?.render).toStrictEqual(TestComponent2);
+      // A humanInTheLoop render is wrapped so `respond` can be injected, so it
+      // is not the component itself — assert it delegates to it.
+      const humanRender = humanRenderTool?.render as (
+        p: Record<string, unknown>,
+      ) => VNode;
+      expect(
+        humanRender({
+          name: "humanRenderTool",
+          toolCallId: "tc-1",
+          args: { b: "value" },
+          status: ToolCallStatus.Executing,
+          result: undefined,
+        }).type,
+      ).toStrictEqual(TestComponent2);
     });
   });