@copilotkit/vue 1.61.1 → 1.62.0

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

@@ -1,17 +1,39 @@
 import { computed, onScopeDispose, shallowRef, watch } from "vue";
 import type { ComputedRef, Ref } from "vue";
+import { buildResumeArray, isInterruptExpired } from "@ag-ui/client";
+import type { Interrupt, RunAgentResult } from "@ag-ui/client";
 import { useCopilotKit } from "../providers/useCopilotKit";
 import { useAgent } from "./use-agent";
 import type {
   InterruptEvent,
   InterruptHandlerProps,
   InterruptRenderProps,
+  InterruptResolveFn,
+  InterruptCancelFn,
 } from "../types/interrupt";
 
-export type { InterruptEvent, InterruptHandlerProps, InterruptRenderProps };
+export type {
+  InterruptEvent,
+  InterruptHandlerProps,
+  InterruptRenderProps,
+  Interrupt,
+};
 
 const INTERRUPT_EVENT_NAME = "on_interrupt";
 
+/** Internal accumulator response shape consumed by buildResumeArray. */
+type ResumeResponse =
+  | { status: "resolved"; payload?: unknown }
+  | { status: "cancelled" };
+
+/**
+ * Normalized pending interrupt. `legacy` carries the custom-event payload;
+ * `standard` carries the AG-UI `outcome:"interrupt"` interrupts array.
+ */
+type PendingInterrupt =
+  | { kind: "legacy"; event: InterruptEvent }
+  | { kind: "standard"; interrupts: Interrupt[] };
+
 type InterruptHandlerFn<TValue, TResult> = (
   props: InterruptHandlerProps<TValue>,
 ) => TResult | PromiseLike<TResult>;
@@ -39,7 +61,14 @@ export interface UseInterruptResult<TValue = unknown, TResult = never> {
   interrupt: Ref<InterruptEvent<TValue> | null>;
   result: Ref<InterruptResult<TValue, TResult>>;
   hasInterrupt: ComputedRef<boolean>;
-  resolveInterrupt: (response: unknown) => void;
+  /** Resolve the pending interrupt. Standard: records resolved response and submits when all addressed. Legacy: resumes via forwardedProps.command. */
+  resolve: InterruptResolveFn;
+  /** Alias of resolve for back-compat. */
+  resolveInterrupt: InterruptResolveFn;
+  /** Cancel the pending interrupt. Standard: records cancelled response and submits when all addressed. */
+  cancel: InterruptCancelFn;
+  /** Alias of cancel for back-compat. */
+  cancelInterrupt: InterruptCancelFn;
   slotProps: ComputedRef<InterruptRenderProps<
     TValue,
     InterruptResult<TValue, TResult>
@@ -72,16 +101,27 @@ function normalizeAsyncResult<TValue>(
   });
 }
 
+/** Derive the legacy-compatible `event` for any pending interrupt. */
+function toLegacyEvent(pending: PendingInterrupt): InterruptEvent {
+  if (pending.kind === "legacy") return pending.event;
+  return { name: INTERRUPT_EVENT_NAME, value: pending.interrupts[0] };
+}
+
 /**
- * Vue composable for handling `on_interrupt` custom events from an agent.
+ * Vue composable for handling agent interrupts with optional filtering,
+ * preprocessing, and resume behavior.
  *
- * It tracks the latest pending interrupt, optionally derives UI data via
- * `handler`, and can publish slot state into `CopilotChat` so consumers render
- * interrupts through the `#interrupt` slot instead of render functions/TSX.
+ * Supports both the AG-UI standard interrupt flow (`RUN_FINISHED` with
+ * `outcome:"interrupt"`) and the legacy custom-event flow (`on_interrupt`).
+ * For standard interrupts, `slotProps` receives `interrupt` (the primary one)
+ * and `interrupts` (the full open set); call `resolve(payload)` to resume or
+ * `cancel()` to cancel. Resuming addresses the targeted interrupt and, once
+ * every open interrupt is addressed, submits a single spec `resume` array via
+ * `copilotkit.runAgent`.
  *
  * @example
  * ```ts
- * const { interrupt, hasInterrupt, resolveInterrupt } = useInterrupt({
+ * const { interrupt, hasInterrupt, resolve, cancel } = useInterrupt({
  *   handler: ({ event }) => ({ label: String(event.value) }),
  * });
  * ```
@@ -91,40 +131,64 @@ export function useInterrupt<TValue = unknown, TResult = never>(
 ): UseInterruptResult<TValue, TResult> {
   const { copilotkit } = useCopilotKit();
   const { agent } = useAgent({ agentId: config.agentId });
-  const interrupt = shallowRef<InterruptEvent<TValue> | null>(null);
+  const pending = shallowRef<PendingInterrupt | null>(null);
   const result = shallowRef<InterruptResult<TValue, TResult>>(null);
 
+  // Accumulated per-interrupt responses for the current standard interrupt set.
+  const responses: Record<string, ResumeResponse> = {};
+
   watch(
     agent,
     (resolvedAgent, _previousAgent, onCleanup) => {
       if (!resolvedAgent) {
-        interrupt.value = null;
+        pending.value = null;
         result.value = null;
         return;
       }
 
-      let localInterrupt: InterruptEvent<TValue> | null = null;
+      let localLegacy: InterruptEvent<TValue> | null = null;
+      let localStandard: Interrupt[] | null = null;
+
       const subscription = resolvedAgent.subscribe({
         onCustomEvent: ({ event }) => {
           if (event.name === INTERRUPT_EVENT_NAME) {
-            localInterrupt = {
+            localLegacy = {
               name: event.name,
               value: event.value as TValue,
             };
           }
         },
+        onRunFinishedEvent: (params) => {
+          if (params.outcome === "interrupt") {
+            localStandard = params.interrupts;
+          }
+        },
         onRunStartedEvent: () => {
-          localInterrupt = null;
-          interrupt.value = null;
+          localLegacy = null;
+          localStandard = null;
+          // Reset accumulated responses for the new run.
+          for (const k of Object.keys(responses)) {
+            delete responses[k];
+          }
+          pending.value = null;
         },
         onRunFinalized: () => {
-          if (localInterrupt) {
-            interrupt.value = localInterrupt;
-            localInterrupt = null;
+          // Standard wins if both somehow appear for one run.
+          if (localStandard && localStandard.length > 0) {
+            pending.value = { kind: "standard", interrupts: localStandard };
+          } else if (localLegacy) {
+            pending.value = { kind: "legacy", event: localLegacy };
           }
+          localLegacy = null;
+          localStandard = null;
         },
         onRunFailed: () => {
-          localInterrupt = null;
+          localLegacy = null;
+          localStandard = null;
+          for (const k of Object.keys(responses)) {
+            delete responses[k];
+          }
+          pending.value = null;
         },
       });
 
@@ -133,38 +197,122 @@ export function useInterrupt<TValue = unknown, TResult = never>(
     { immediate: true },
   );
 
-  const resolveInterrupt = (response: unknown) => {
+  /** Submit the accumulated standard responses once all open interrupts are addressed. */
+  const submitStandardIfComplete = async (
+    interrupts: Interrupt[],
+  ): Promise<RunAgentResult | void> => {
+    const allAddressed = interrupts.every((i) => responses[i.id]);
+    if (!allAddressed) return;
+
+    const expired = interrupts.find((i) => isInterruptExpired(i));
+    if (expired) {
+      console.error(
+        `[CopilotKit] useInterrupt: interrupt ${expired.id} expired at ${expired.expiresAt}; not resuming.`,
+      );
+      for (const k of Object.keys(responses)) {
+        delete responses[k];
+      }
+      pending.value = null;
+      return;
+    }
+
+    const resume = buildResumeArray(interrupts, responses);
+    for (const k of Object.keys(responses)) {
+      delete responses[k];
+    }
+    const resolvedAgent = agent.value;
+    if (!resolvedAgent) return;
+    try {
+      return await copilotkit.value.runAgent({ agent: resolvedAgent, resume });
+    } catch (err) {
+      console.error(
+        "[CopilotKit] useInterrupt resolve: runAgent rejected; clearing pending + rethrowing",
+        err,
+      );
+      pending.value = null;
+      throw err;
+    }
+  };
+
+  const resolve: InterruptResolveFn = async (payload?, interruptId?) => {
+    const current = pending.value;
+    if (!current) return;
+
     const resolvedAgent = agent.value;
     if (!resolvedAgent) return;
 
-    const interruptEventValue = interrupt.value?.value;
-    interrupt.value = null;
-    void copilotkit.value
-      .runAgent({
-        agent: resolvedAgent,
-        forwardedProps: {
-          command: {
-            resume: response,
-            interruptEvent: interruptEventValue,
+    if (current.kind === "legacy") {
+      const interruptEventValue = current.event.value;
+      try {
+        return await copilotkit.value.runAgent({
+          agent: resolvedAgent,
+          forwardedProps: {
+            command: {
+              resume: payload,
+              interruptEvent: interruptEventValue,
+            },
           },
-        },
-      })
-      .catch((error) => {
+        });
+      } catch (err) {
         console.error(
-          "[CopilotKit] useInterrupt: failed to resume agent:",
-          error,
+          "[CopilotKit] useInterrupt resolve: runAgent rejected; clearing pending + rethrowing",
+          err,
         );
-      });
+        pending.value = null;
+        throw err;
+      }
+    }
+
+    if (current.interrupts.length > 1 && interruptId === undefined) {
+      console.warn(
+        `[CopilotKit] useInterrupt: resolve()/cancel() called without an interruptId while ${current.interrupts.length} interrupts are open; defaulting to the first. Pass an interruptId to address a specific interrupt.`,
+      );
+    }
+    const id = interruptId ?? current.interrupts[0]?.id;
+    if (!id) return;
+    responses[id] = { status: "resolved", payload };
+    return submitStandardIfComplete(current.interrupts);
   };
 
+  const cancel: InterruptCancelFn = async (interruptId?) => {
+    const current = pending.value;
+    if (!current) return;
+
+    if (current.kind === "legacy") {
+      // Legacy interrupts have no cancel semantics; dismiss without resuming.
+      console.warn(
+        "[CopilotKit] useInterrupt: cancel() is not supported for legacy on_interrupt interrupts; dismissing.",
+      );
+      pending.value = null;
+      return;
+    }
+
+    if (current.interrupts.length > 1 && interruptId === undefined) {
+      console.warn(
+        `[CopilotKit] useInterrupt: resolve()/cancel() called without an interruptId while ${current.interrupts.length} interrupts are open; defaulting to the first. Pass an interruptId to address a specific interrupt.`,
+      );
+    }
+    const id = interruptId ?? current.interrupts[0]?.id;
+    if (!id) return;
+    responses[id] = { status: "cancelled" };
+    return submitStandardIfComplete(current.interrupts);
+  };
+
+  // Keep resolveInterrupt and cancelInterrupt as aliases for back-compat.
+  const resolveInterrupt: InterruptResolveFn = resolve;
+  const cancelInterrupt: InterruptCancelFn = cancel;
+
   watch(
-    interrupt,
-    (pendingEvent, _previous, onCleanup) => {
-      if (!pendingEvent) {
+    pending,
+    (currentPending, _previous, onCleanup) => {
+      if (!currentPending) {
         result.value = null;
         return;
       }
-      if (config.enabled && !config.enabled(pendingEvent)) {
+      const legacyEvent = toLegacyEvent(
+        currentPending,
+      ) as InterruptEvent<TValue>;
+      if (config.enabled && !config.enabled(legacyEvent)) {
         result.value = null;
         return;
       }
@@ -176,8 +324,15 @@ export function useInterrupt<TValue = unknown, TResult = never>(
 
       let cancelled = false;
       const maybePromise = handler({
-        event: pendingEvent,
-        resolve: resolveInterrupt,
+        event: legacyEvent,
+        interrupt:
+          currentPending.kind === "standard"
+            ? (currentPending.interrupts[0] ?? null)
+            : null,
+        interrupts:
+          currentPending.kind === "standard" ? currentPending.interrupts : [],
+        resolve,
+        cancel,
       });
 
       if (isPromiseLike(maybePromise)) {
@@ -204,17 +359,32 @@ export function useInterrupt<TValue = unknown, TResult = never>(
     { immediate: true },
   );
 
+  // Compute the legacy-compat "interrupt" ref for existing consumers (InterruptEvent shape).
+  const interrupt = computed<InterruptEvent<TValue> | null>(() => {
+    if (!pending.value) return null;
+    return toLegacyEvent(pending.value) as InterruptEvent<TValue>;
+  });
+
   const slotProps = computed<InterruptRenderProps<
     TValue,
     InterruptResult<TValue, TResult>
   > | null>(() => {
-    if (!interrupt.value) return null;
-    if (config.enabled && !config.enabled(interrupt.value)) return null;
+    const currentPending = pending.value;
+    if (!currentPending) return null;
+    const legacyEvent = toLegacyEvent(currentPending) as InterruptEvent<TValue>;
+    if (config.enabled && !config.enabled(legacyEvent)) return null;
 
     return {
-      event: interrupt.value,
+      event: legacyEvent,
+      interrupt:
+        currentPending.kind === "standard"
+          ? (currentPending.interrupts[0] ?? null)
+          : null,
+      interrupts:
+        currentPending.kind === "standard" ? currentPending.interrupts : [],
       result: result.value,
-      resolve: resolveInterrupt,
+      resolve,
+      cancel,
     };
   });
 
@@ -226,6 +396,7 @@ export function useInterrupt<TValue = unknown, TResult = never>(
       }
 
       core.setInterruptState(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         nextSlotProps as InterruptRenderProps<any, any> | null,
       );
       const publishedState = nextSlotProps;
@@ -250,10 +421,13 @@ export function useInterrupt<TValue = unknown, TResult = never>(
   });
 
   return {
-    interrupt: interrupt as Ref<InterruptEvent<TValue> | null>,
+    interrupt: interrupt as unknown as Ref<InterruptEvent<TValue> | null>,
     result: result as Ref<InterruptResult<TValue, TResult>>,
     hasInterrupt: computed(() => slotProps.value !== null),
+    resolve,
     resolveInterrupt,
+    cancel,
+    cancelInterrupt,
     slotProps: slotProps as ComputedRef<InterruptRenderProps<
       TValue,
       InterruptResult<TValue, TResult>

package/src/v2/index.ts

@@ -4,6 +4,11 @@ export * from "@ag-ui/client";
 
 // Local V2 vue code
 export * from "./components";
+// Explicit re-export so the default A2UI catalog is reachable as a public
+// named export. Vue users need a catalog to pass to `a2ui.catalog` for the
+// catalog-on-provider path; the nested `export *` barrel above gets
+// tree-shaken by the library build, so surface it directly here.
+export { vueBasicCatalog } from "./components/a2ui/catalog";
 export * from "./hooks";
 export * from "./providers";
 export * from "./types";

package/src/v2/providers/CopilotKitProvider.vue

@@ -16,6 +16,7 @@ import type {
   FrontendTool,
 } from "@copilotkit/core";
 import { schemaToJsonSchema } from "@copilotkit/shared";
+import type { RuntimeLicenseStatus } from "@copilotkit/shared";
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { CopilotKitCoreVue } from "../lib/vue-core";
 import { createA2UIMessageRenderer } from "../components/A2UIMessageRenderer";
@@ -37,8 +38,8 @@ import { CopilotKitKey, SandboxFunctionsKey } from "./keys";
 import {
   LicenseContextKey,
   createLicenseContextValue,
-  type LicenseContextValue,
 } from "./license-context";
+import type { LicenseContextValue } from "./license-context";
 import CopilotKitInspector from "../components/CopilotKitInspector.vue";
 import LicenseWarningBanner from "../components/LicenseWarningBanner.vue";
 import type { CopilotKitProviderProps } from "./CopilotKitProvider.types";
@@ -290,10 +291,25 @@ const allRenderCustomMessages = computed(
 );
 const runtimeA2UIEnabled = ref(false);
 const runtimeOpenGenerativeUIEnabled = ref(false);
-const runtimeLicenseStatus = ref<string | undefined>(undefined);
+const runtimeLicenseStatus = ref<RuntimeLicenseStatus | undefined>(undefined);
 const openGenerativeUIActive = computed(
   () => runtimeOpenGenerativeUIEnabled.value || !!props.openGenerativeUI,
 );
+// A catalog passed to the provider is enough to turn A2UI on: render the
+// surfaces locally and forward the catalog signal so the runtime injects the
+// render tool — no runtime-side `a2ui` config required.
+const a2uiCatalogProvided = computed(() => !!props.a2ui?.catalog);
+const a2uiActive = computed(
+  () => runtimeA2UIEnabled.value || a2uiCatalogProvided.value,
+);
+// Forward a per-run signal when the provider has an A2UI catalog so the
+// runtime can turn A2UI on (and inject the render tool) without a separate
+// `a2ui.injectA2UITool` flag on the runtime.
+const resolvedProperties = computed(() =>
+  a2uiCatalogProvided.value
+    ? { ...props.properties, a2uiCatalogAvailable: true }
+    : props.properties,
+);
 const sandboxFunctions = computed<readonly SandboxFunction[]>(
   () => props.openGenerativeUI?.sandboxFunctions ?? [],
 );
@@ -342,7 +358,7 @@ const builtInActivityRenderers = computed<
     });
   }
 
-  if (runtimeA2UIEnabled.value) {
+  if (a2uiActive.value) {
     renderers.unshift(
       createA2UIMessageRenderer({
         theme: props.a2ui?.theme ?? viewerTheme,
@@ -383,7 +399,7 @@ const createCopilotKit = () => {
           : "auto",
     headers: mergedHeaders.value,
     credentials: props.credentials,
-    properties: props.properties,
+    properties: resolvedProperties.value,
     agents__unsafe_dev_only: mergedAgents.value,
     tools: allTools.value,
     renderToolCalls: allRenderToolCalls.value,
@@ -502,7 +518,7 @@ function syncRuntimeConfig() {
   );
   copilotkit.value.setHeaders(mergedHeaders.value);
   copilotkit.value.setCredentials(props.credentials);
-  copilotkit.value.setProperties(props.properties);
+  copilotkit.value.setProperties(resolvedProperties.value);
   copilotkit.value.setAgents__unsafe_dev_only(mergedAgents.value);
   copilotkit.value.setDebug(props.debug);
   applyDefaultThrottleMs(copilotkit.value);
@@ -513,7 +529,7 @@ watch(
     () => chatApiEndpoint.value,
     () => mergedHeaders.value,
     () => props.credentials,
-    () => props.properties,
+    () => resolvedProperties.value,
     () => mergedAgents.value,
     () => props.useSingleEndpoint,
     () => props.debug,
@@ -548,11 +564,11 @@ const a2uiLoadingComponent = computed(() => props.a2ui?.loadingComponent);
 const a2uiIncludeSchema = computed(() => props.a2ui?.includeSchema ?? true);
 
 // A2UI tool call renderer (progress indicator) — auto-registered when A2UI enabled
-registerA2UIBuiltInToolCallRenderer(copilotkit, () => runtimeA2UIEnabled.value);
+registerA2UIBuiltInToolCallRenderer(copilotkit, () => a2uiActive.value);
 
 // A2UI catalog context, schema, and generation/design guidelines
 registerA2UICatalogContext(copilotkit, {
-  enabled: () => runtimeA2UIEnabled.value,
+  enabled: () => a2uiActive.value,
   catalog: () => props.a2ui?.catalog,
   includeSchema: () => props.a2ui?.includeSchema ?? true,
 });
@@ -616,11 +632,8 @@ provide(CopilotKitKey, {
 provide(SandboxFunctionsKey, sandboxFunctions);
 
 // License context — driven by server-reported `/info` license status.
-// Stays at the permissive default (`createLicenseContextValue(null)`)
-// to mirror React's current provider behavior; banner rendering below
-// is the sole consumer of `runtimeLicenseStatus`.
 const licenseContextValue = computed<LicenseContextValue>(() =>
-  createLicenseContextValue(null),
+  createLicenseContextValue(runtimeLicenseStatus.value),
 );
 provide(LicenseContextKey, licenseContextValue);
 

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

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+import { defineComponent, h, ref } from "vue";
+import { mount } from "@vue/test-utils";
+import CopilotKitProvider from "../CopilotKitProvider.vue";
+import { useCopilotKit } from "../useCopilotKit";
+
+function mountProvider(props: Record<string, unknown>) {
+  const observedCore =
+    ref<ReturnType<typeof useCopilotKit>["copilotkit"]["value"]>();
+
+  const Child = defineComponent({
+    setup() {
+      const { copilotkit } = useCopilotKit();
+      observedCore.value = copilotkit.value;
+      return () => h("div");
+    },
+  });
+
+  const wrapper = mount(CopilotKitProvider, {
+    props: {
+      runtimeUrl: "/api/copilotkit",
+      ...props,
+    },
+    slots: {
+      default: () => h(Child),
+    },
+  });
+
+  return { wrapper, observedCore };
+}
+
+describe("CopilotKitProvider a2ui catalog auto-enable", () => {
+  it("forwards a2uiCatalogAvailable when a catalog is passed to the provider", () => {
+    const { observedCore } = mountProvider({
+      a2ui: { catalog: { id: "test", components: new Map() } },
+    });
+
+    expect(observedCore.value?.properties.a2uiCatalogAvailable).toBe(true);
+  });
+
+  it("does not forward a2uiCatalogAvailable when no catalog is passed", () => {
+    const { observedCore } = mountProvider({ a2ui: {} });
+
+    expect(observedCore.value?.properties.a2uiCatalogAvailable).toBeUndefined();
+  });
+
+  it("preserves user-provided properties alongside the catalog signal", () => {
+    const { observedCore } = mountProvider({
+      a2ui: { catalog: { id: "test", components: new Map() } },
+      properties: { tenant: "acme" },
+    });
+
+    expect(observedCore.value?.properties).toMatchObject({
+      tenant: "acme",
+      a2uiCatalogAvailable: true,
+    });
+  });
+
+  it("registers an a2ui-surface renderer when a catalog is provided, without a runtime signal", () => {
+    const { observedCore } = mountProvider({
+      a2ui: { catalog: { id: "test", components: new Map() } },
+    });
+
+    const a2uiRenderer = observedCore.value?.renderActivityMessages.find(
+      (r) => r.activityType === "a2ui-surface",
+    );
+    expect(a2uiRenderer).toBeDefined();
+  });
+
+  it("does not register an a2ui-surface renderer when no catalog is provided and runtime has not signaled a2uiEnabled", () => {
+    const { observedCore } = mountProvider({ a2ui: { theme: {} } });
+
+    const a2uiRenderer = observedCore.value?.renderActivityMessages.find(
+      (r) => r.activityType === "a2ui-surface",
+    );
+    expect(a2uiRenderer).toBeUndefined();
+  });
+});

package/src/v2/types/interrupt.ts

@@ -1,15 +1,31 @@
+import type { Interrupt, RunAgentResult } from "@ag-ui/client";
+
 export interface InterruptEvent<TValue = unknown> {
   name: string;
   value: TValue;
 }
 
+export type InterruptResolveFn = (
+  payload?: unknown,
+  interruptId?: string,
+) => Promise<RunAgentResult | void>;
+export type InterruptCancelFn = (
+  interruptId?: string,
+) => Promise<RunAgentResult | void>;
+
 export interface InterruptHandlerProps<TValue = unknown> {
   event: InterruptEvent<TValue>;
-  resolve: (response: unknown) => void;
+  interrupt: Interrupt | null;
+  interrupts: Interrupt[];
+  resolve: InterruptResolveFn;
+  cancel: InterruptCancelFn;
 }
 
 export interface InterruptRenderProps<TValue = unknown, TResult = unknown> {
   event: InterruptEvent<TValue>;
+  interrupt: Interrupt | null;
+  interrupts: Interrupt[];
   result: TResult;
-  resolve: (response: unknown) => void;
+  resolve: InterruptResolveFn;
+  cancel: InterruptCancelFn;
 }