@copilotkit/vue 1.57.1

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

@@ -0,0 +1,257 @@
+import { computed, onScopeDispose, shallowRef, watch } from "vue";
+import type { ComputedRef, Ref } from "vue";
+import { useCopilotKit } from "../providers/useCopilotKit";
+import { useAgent } from "./use-agent";
+import type {
+  InterruptEvent,
+  InterruptHandlerProps,
+  InterruptRenderProps,
+} from "../types/interrupt";
+
+export type { InterruptEvent, InterruptHandlerProps, InterruptRenderProps };
+
+const INTERRUPT_EVENT_NAME = "on_interrupt";
+
+type InterruptHandlerFn<TValue, TResult> = (
+  props: InterruptHandlerProps<TValue>,
+) => TResult | PromiseLike<TResult>;
+
+type InterruptResultFromHandler<THandler> = THandler extends (
+  ...args: never[]
+) => infer TResult
+  ? TResult extends PromiseLike<infer TResolved>
+    ? TResolved | null
+    : TResult | null
+  : null;
+
+type InterruptResult<TValue, TResult> = InterruptResultFromHandler<
+  InterruptHandlerFn<TValue, TResult>
+>;
+
+export interface UseInterruptConfig<TValue = unknown, TResult = never> {
+  handler?: InterruptHandlerFn<TValue, TResult>;
+  enabled?: (event: InterruptEvent<TValue>) => boolean;
+  agentId?: string;
+  renderInChat?: boolean;
+}
+
+export interface UseInterruptResult<TValue = unknown, TResult = never> {
+  interrupt: Ref<InterruptEvent<TValue> | null>;
+  result: Ref<InterruptResult<TValue, TResult>>;
+  hasInterrupt: ComputedRef<boolean>;
+  resolveInterrupt: (response: unknown) => void;
+  slotProps: ComputedRef<InterruptRenderProps<
+    TValue,
+    InterruptResult<TValue, TResult>
+  > | null>;
+}
+
+export function isPromiseLike<TValue>(
+  value: TValue | PromiseLike<TValue>,
+): value is PromiseLike<TValue> {
+  return (
+    (typeof value === "object" || typeof value === "function") &&
+    value !== null &&
+    typeof Reflect.get(value, "then") === "function"
+  );
+}
+
+function normalizeAsyncResult<TValue>(
+  value: PromiseLike<TValue>,
+): Promise<TValue> {
+  if (value instanceof Promise) {
+    return value;
+  }
+
+  return new Promise<TValue>((resolve, reject) => {
+    try {
+      value.then(resolve, reject);
+    } catch (error) {
+      reject(error);
+    }
+  });
+}
+
+/**
+ * Vue composable for handling `on_interrupt` custom events from an agent.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const { interrupt, hasInterrupt, resolveInterrupt } = useInterrupt({
+ *   handler: ({ event }) => ({ label: String(event.value) }),
+ * });
+ * ```
+ */
+export function useInterrupt<TValue = unknown, TResult = never>(
+  config: UseInterruptConfig<TValue, TResult> = {},
+): UseInterruptResult<TValue, TResult> {
+  const { copilotkit } = useCopilotKit();
+  const { agent } = useAgent({ agentId: config.agentId });
+  const interrupt = shallowRef<InterruptEvent<TValue> | null>(null);
+  const result = shallowRef<InterruptResult<TValue, TResult>>(null);
+
+  watch(
+    agent,
+    (resolvedAgent, _previousAgent, onCleanup) => {
+      if (!resolvedAgent) {
+        interrupt.value = null;
+        result.value = null;
+        return;
+      }
+
+      let localInterrupt: InterruptEvent<TValue> | null = null;
+      const subscription = resolvedAgent.subscribe({
+        onCustomEvent: ({ event }) => {
+          if (event.name === INTERRUPT_EVENT_NAME) {
+            localInterrupt = {
+              name: event.name,
+              value: event.value as TValue,
+            };
+          }
+        },
+        onRunStartedEvent: () => {
+          localInterrupt = null;
+          interrupt.value = null;
+        },
+        onRunFinalized: () => {
+          if (localInterrupt) {
+            interrupt.value = localInterrupt;
+            localInterrupt = null;
+          }
+        },
+        onRunFailed: () => {
+          localInterrupt = null;
+        },
+      });
+
+      onCleanup(() => subscription.unsubscribe());
+    },
+    { immediate: true },
+  );
+
+  const resolveInterrupt = (response: unknown) => {
+    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,
+        },
+      },
+    }).catch((error) => {
+      console.error("[CopilotKit] useInterrupt: failed to resume agent:", error);
+    });
+  };
+
+  watch(
+    interrupt,
+    (pendingEvent, _previous, onCleanup) => {
+      if (!pendingEvent) {
+        result.value = null;
+        return;
+      }
+      if (config.enabled && !config.enabled(pendingEvent)) {
+        result.value = null;
+        return;
+      }
+      const handler = config.handler;
+      if (!handler) {
+        result.value = null;
+        return;
+      }
+
+      let cancelled = false;
+      const maybePromise = handler({
+        event: pendingEvent,
+        resolve: resolveInterrupt,
+      });
+
+      if (isPromiseLike(maybePromise)) {
+        normalizeAsyncResult(maybePromise)
+          .then((resolved) => {
+            if (!cancelled) {
+              result.value = resolved;
+            }
+          })
+          .catch((err) => {
+            if (!cancelled) {
+              console.error("[CopilotKit] useInterrupt handler failed:", err);
+              result.value = null;
+            }
+          });
+      } else {
+        result.value = maybePromise;
+      }
+
+      onCleanup(() => {
+        cancelled = true;
+      });
+    },
+    { immediate: true },
+  );
+
+  const slotProps = computed<InterruptRenderProps<
+    TValue,
+    InterruptResult<TValue, TResult>
+  > | null>(() => {
+    if (!interrupt.value) return null;
+    if (config.enabled && !config.enabled(interrupt.value)) return null;
+
+    return {
+      event: interrupt.value,
+      result: result.value,
+      resolve: resolveInterrupt,
+    };
+  });
+
+  watch(
+    [() => copilotkit.value, slotProps, () => config.renderInChat !== false],
+    ([core, nextSlotProps, shouldRenderInChat], _previous, onCleanup) => {
+      if (!shouldRenderInChat) {
+        return;
+      }
+
+      core.setInterruptState(
+        nextSlotProps as InterruptRenderProps<any, any> | null,
+      );
+      const publishedState = nextSlotProps;
+
+      onCleanup(() => {
+        if (core.interruptState === publishedState) {
+          core.setInterruptState(null);
+        }
+      });
+    },
+    { immediate: true },
+  );
+
+  onScopeDispose(() => {
+    const core = copilotkit.value;
+    if (
+      config.renderInChat !== false &&
+      core.interruptState === slotProps.value
+    ) {
+      core.setInterruptState(null);
+    }
+  });
+
+  return {
+    interrupt: interrupt as Ref<InterruptEvent<TValue> | null>,
+    result: result as Ref<InterruptResult<TValue, TResult>>,
+    hasInterrupt: computed(() => slotProps.value !== null),
+    resolveInterrupt,
+    slotProps: slotProps as ComputedRef<InterruptRenderProps<
+      TValue,
+      InterruptResult<TValue, TResult>
+    > | null>,
+  };
+}

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

@@ -0,0 +1,44 @@
+import { onMounted } from "vue";
+
+// Module-level singleton flag so the stylesheet is only injected once per
+// module graph (matches the React singleton injection intent).
+let injected = false;
+
+/**
+ * Dynamically loads KaTeX CSS at runtime to avoid Next.js-style
+ * "Global CSS cannot be imported from within node_modules" build errors and
+ * to keep the CSS out of the static import graph.
+ *
+ * Uses a module-level singleton flag so the stylesheet is only loaded once,
+ * regardless of how many components call this composable.
+ *
+ * Mirrors the React `useKatexStyles` hook: returns `void`, never throws, and
+ * logs a warning with equivalent intent if the dynamic import fails.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useKatexStyles } from "@copilotkit/vue";
+ *
+ * useKatexStyles();
+ * </script>
+ * ```
+ */
+export function useKatexStyles(): void {
+  onMounted(() => {
+    if (injected || typeof document === "undefined") return;
+    injected = true;
+
+    // Dynamic import defers CSS loading to runtime, bypassing build-time
+    // static analysis that rejects global CSS from node_modules.
+    // The `@vite-ignore` + indirect specifier keeps TypeScript from trying
+    // to resolve a type declaration for the CSS module while still letting
+    // the bundler handle the actual side-effect import at runtime.
+    const katexStylesSpecifier = "katex/dist/katex.min.css";
+    void import(/* @vite-ignore */ katexStylesSpecifier).catch(() => {
+      console.warn(
+        "[CopilotKit] Failed to load katex styles — math content may render without formatting",
+      );
+    });
+  });
+}

package/src/v2/hooks/use-keyboard-height.ts

@@ -0,0 +1,87 @@
+import { onBeforeUnmount, onMounted, readonly, ref, type Ref } from "vue";
+
+/**
+ * Vue-idiomatic result of {@link useKeyboardHeight}. Fields mirror the React
+ * `KeyboardState` shape (`isKeyboardOpen`, `keyboardHeight`, `availableHeight`,
+ * `viewportHeight`) and are exposed as readonly refs so consumers can bind them
+ * reactively inside templates or computed values.
+ */
+export interface KeyboardState {
+  isKeyboardOpen: Readonly<Ref<boolean>>;
+  keyboardHeight: Readonly<Ref<number>>;
+  availableHeight: Readonly<Ref<number>>;
+  viewportHeight: Readonly<Ref<number>>;
+}
+
+/**
+ * Composable to detect mobile keyboard appearance and calculate available
+ * viewport height. Uses the Visual Viewport API to track keyboard state on
+ * mobile devices.
+ *
+ * Mirrors the React `useKeyboardHeight` hook: returns `keyboardHeight` as the
+ * difference between `window.innerHeight` and `visualViewport.height`, clamped
+ * to `0`, and reports the keyboard as open when the diff exceeds `150` px.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useKeyboardHeight } from "@copilotkit/vue";
+ *
+ * const { isKeyboardOpen, keyboardHeight } = useKeyboardHeight();
+ * </script>
+ * ```
+ */
+export function useKeyboardHeight(): KeyboardState {
+  const initialHeight = typeof window !== "undefined" ? window.innerHeight : 0;
+  const isKeyboardOpen = ref(false);
+  const keyboardHeight = ref(0);
+  const availableHeight = ref(initialHeight);
+  const viewportHeight = ref(initialHeight);
+
+  const updateKeyboardState = () => {
+    if (typeof window === "undefined") return;
+    const visualViewport = window.visualViewport;
+    if (!visualViewport) return;
+
+    const layoutHeight = window.innerHeight;
+    const visualHeight = visualViewport.height;
+
+    // Keyboard height = layout viewport minus visual viewport, clamped to 0.
+    const nextKeyboardHeight = Math.max(0, layoutHeight - visualHeight);
+    // Only treat the keyboard as open past the 150px threshold, matching
+    // the React implementation's mobile heuristic.
+    const nextIsOpen = nextKeyboardHeight > 150;
+
+    keyboardHeight.value = nextKeyboardHeight;
+    isKeyboardOpen.value = nextIsOpen;
+    availableHeight.value = visualHeight;
+    viewportHeight.value = layoutHeight;
+  };
+
+  let visualViewport: VisualViewport | null = null;
+
+  onMounted(() => {
+    if (typeof window === "undefined") return;
+    visualViewport = window.visualViewport ?? null;
+    if (!visualViewport) return;
+
+    updateKeyboardState();
+
+    visualViewport.addEventListener("resize", updateKeyboardState);
+    visualViewport.addEventListener("scroll", updateKeyboardState);
+  });
+
+  onBeforeUnmount(() => {
+    if (!visualViewport) return;
+    visualViewport.removeEventListener("resize", updateKeyboardState);
+    visualViewport.removeEventListener("scroll", updateKeyboardState);
+    visualViewport = null;
+  });
+
+  return {
+    isKeyboardOpen: readonly(isKeyboardOpen),
+    keyboardHeight: readonly(keyboardHeight),
+    availableHeight: readonly(availableHeight),
+    viewportHeight: readonly(viewportHeight),
+  };
+}

package/src/v2/hooks/use-pin-to-send.ts

@@ -0,0 +1,160 @@
+import { inject, watch, type Ref } from "vue";
+import {
+  LastUserMessageKey,
+  createDefaultLastUserMessageRef,
+} from "../components/chat/last-user-message-context";
+
+export interface UsePinToSendOptions {
+  scrollRef: Ref<HTMLElement | null>;
+  contentRef: Ref<HTMLElement | null>;
+  spacerRef: Ref<HTMLElement | null>;
+  topOffset?: number;
+}
+
+/**
+ * Vue counterpart of React's `usePinToSend` (`packages/react-core/src/v2/hooks/use-pin-to-send.ts`).
+ *
+ * Anchors the chat scroll container so the most recent user message stays
+ * pinned near the top of the viewport while the assistant streams a
+ * response beneath it.
+ *
+ * Implementation parity with React:
+ * - Reads the latest user message via the `LastUserMessageContext`
+ *   equivalent (`LastUserMessageKey` + `Ref<LastUserMessageState>`).
+ * - On each `sendNonce` increment, sizes the spacer to
+ *   `viewportHeight - bubbleHeight - topOffset` and scrolls so the bubble
+ *   sits `topOffset` from the viewport top (padding above the bubble is
+ *   pushed off-screen).
+ * - Installs a shrink-only `ResizeObserver` on `contentRef` that collapses
+ *   the spacer as the assistant response grows; never grows it back.
+ * - Cancels the scheduled `requestAnimationFrame` and disconnects the
+ *   `ResizeObserver` on subsequent re-runs and on scope dispose.
+ */
+export function usePinToSend({
+  scrollRef,
+  contentRef,
+  spacerRef,
+  topOffset = 16,
+}: UsePinToSendOptions): void {
+  const lastUserMessage = inject(
+    LastUserMessageKey,
+    createDefaultLastUserMessageRef(),
+    true,
+  );
+
+  let lastNonce = -1;
+  let currentSpacerHeight = 0;
+  let raf: number | null = null;
+  let ro: ResizeObserver | null = null;
+
+  function teardown() {
+    if (raf !== null && typeof cancelAnimationFrame === "function") {
+      cancelAnimationFrame(raf);
+    }
+    raf = null;
+    ro?.disconnect();
+    ro = null;
+  }
+
+  watch(
+    [
+      () => lastUserMessage.value.id,
+      () => lastUserMessage.value.sendNonce,
+      scrollRef,
+      contentRef,
+      spacerRef,
+      () => topOffset,
+    ],
+    ([id, sendNonce, scrollEl, contentEl, spacerEl], _old, onCleanup) => {
+      // Always tear down the previous run's RAF / ResizeObserver before
+      // evaluating any of the early-exit guards below. Mirrors React
+      // `useEffect` cleanup semantics: the prior run's cleanup runs before
+      // the next callback executes regardless of why the deps changed.
+      // Without this, a reactive `autoScroll` mode change (e.g. switching
+      // away from `"pin-to-send"`) or a `ref` swap that doesn't bump
+      // `sendNonce` would leak the stale content-element observer because
+      // the nonce guard skips the body. Registering via `onCleanup` also
+      // covers watcher stop on scope dispose, so an explicit
+      // `onScopeDispose(teardown)` is no longer required.
+      onCleanup(teardown);
+
+      if (sendNonce === lastNonce) return;
+      lastNonce = sendNonce;
+
+      if (!id) return;
+      if (!scrollEl || !contentEl || !spacerEl) return;
+
+      const escaped =
+        typeof CSS !== "undefined" && typeof CSS.escape === "function"
+          ? CSS.escape(id)
+          : id.replace(/[!"#$%&'()*+,./:;<=>?@[\\\]^`{|}~]/g, "\\$&");
+      const targetEl = contentEl.querySelector<HTMLElement>(
+        `[data-message-id="${escaped}"]`,
+      );
+      if (!targetEl) return;
+
+      // The target message's element has a top padding (e.g. `pt-10`) that
+      // creates breathing room above the visible bubble. When we "anchor at
+      // the top", we mean anchor the *bubble*, not the element's padded box.
+      // So we scroll past the padding (it goes above the viewport, hiding
+      // whatever was above the element too — including the previous message's
+      // trailing copy button).
+      const viewportHeight = scrollEl.clientHeight;
+      const userMessageHeight = targetEl.getBoundingClientRect().height;
+      const paddingTop = parseFloat(getComputedStyle(targetEl).paddingTop) || 0;
+      const bubbleHeight = Math.max(0, userMessageHeight - paddingTop);
+      const spacerHeight = Math.max(
+        0,
+        viewportHeight - bubbleHeight - topOffset,
+      );
+
+      spacerEl.style.height = `${spacerHeight}px`;
+      currentSpacerHeight = spacerHeight;
+
+      if (typeof requestAnimationFrame === "function") {
+        raf = requestAnimationFrame(() => {
+          // Scroll so the BUBBLE is `topOffset` from the viewport top — the
+          // padding above the bubble ends up scrolled off-screen.
+          const targetTop =
+            computeOffsetTop(targetEl, scrollEl) + paddingTop - topOffset;
+          scrollEl.scrollTo({
+            top: Math.max(0, targetTop),
+            behavior: "smooth",
+          });
+        });
+      }
+
+      // Shrink-only ResizeObserver: as the assistant response grows below the
+      // anchored user message, collapse the spacer by the same amount so total
+      // scrollable space below the bubble stays constant (and the bubble stays
+      // pinned). Never grow the spacer after initial sizing.
+      if (typeof ResizeObserver !== "undefined") {
+        ro = new ResizeObserver(() => {
+          if (!contentEl || !spacerEl || !scrollEl) return;
+          const contentHeight = contentEl.getBoundingClientRect().height;
+          const targetOffsetWithinContent = computeOffsetTop(
+            targetEl,
+            contentEl,
+          );
+          const consumedBelow =
+            contentHeight - targetOffsetWithinContent - userMessageHeight;
+          const remaining = Math.max(0, spacerHeight - consumedBelow);
+          if (remaining < currentSpacerHeight) {
+            spacerEl.style.height = `${remaining}px`;
+            currentSpacerHeight = remaining;
+          }
+        });
+        ro.observe(contentEl);
+      }
+    },
+    { immediate: true, flush: "post" },
+  );
+}
+
+// Compute the offset of el relative to stopAt, accounting for stopAt's current scrollTop.
+// Uses getBoundingClientRect so it works regardless of CSS positioning (including position:static).
+function computeOffsetTop(el: HTMLElement, stopAt: HTMLElement): number {
+  const elRect = el.getBoundingClientRect();
+  const stopRect = stopAt.getBoundingClientRect();
+  return elRect.top - stopRect.top + stopAt.scrollTop;
+}

package/src/v2/hooks/use-render-activity-message.ts

@@ -0,0 +1,92 @@
+import { computed } from "vue";
+import type { Component } from "vue";
+import type { ActivityMessage } from "@ag-ui/core";
+import type { AbstractAgent } from "@ag-ui/client";
+import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
+import { useCopilotKit } from "../providers/useCopilotKit";
+import { useCopilotChatConfiguration } from "../providers/useCopilotChatConfiguration";
+import type {
+  VueActivityMessageRenderer,
+  VueActivityMessageRendererProps,
+} from "../types";
+
+interface ActivityRendererResult {
+  renderer: Component<VueActivityMessageRendererProps<unknown>>;
+  props: VueActivityMessageRendererProps<unknown>;
+}
+
+/**
+ * Returns helpers for rendering activity messages.
+ *
+ * Matches the React `useRenderActivityMessage` API: `findRenderer` locates a
+ * registered renderer by activity type (preferring agent-scoped over global,
+ * with `"*"` as a wildcard fallback), and `renderActivityMessage` resolves the
+ * renderer and validates the content schema.
+ */
+export function useRenderActivityMessage() {
+  const { copilotkit } = useCopilotKit();
+  const config = useCopilotChatConfiguration();
+  const agentId = computed(
+    () => config.value?.agentId ?? DEFAULT_AGENT_ID,
+  );
+
+  const renderers = computed(() => [...copilotkit.value.renderActivityMessages]);
+
+  function findRenderer(
+    activityType: string,
+  ): VueActivityMessageRenderer<unknown> | null {
+    const list = renderers.value;
+    if (!list.length) {
+      return null;
+    }
+
+    const matches = list.filter(
+      (renderer) => renderer.activityType === activityType,
+    );
+
+    return (
+      matches.find((candidate) => candidate.agentId === agentId.value) ??
+      matches.find((candidate) => candidate.agentId === undefined) ??
+      list.find((candidate) => candidate.activityType === "*") ??
+      null
+    );
+  }
+
+  function renderActivityMessage(
+    message: ActivityMessage,
+  ): ActivityRendererResult | null {
+    const renderer = findRenderer(message.activityType);
+
+    if (!renderer) {
+      return null;
+    }
+
+    const parseResult = renderer.content.safeParse(message.content);
+
+    if (!parseResult.success) {
+      console.warn(
+        `Failed to parse content for activity message ` +
+          `'${message.activityType}':`,
+        parseResult.error,
+      );
+      return null;
+    }
+
+    const agent: AbstractAgent | undefined =
+      copilotkit.value.getAgent(agentId.value);
+
+    return {
+      renderer: renderer.render as Component<
+        VueActivityMessageRendererProps<unknown>
+      >,
+      props: {
+        activityType: message.activityType,
+        content: parseResult.data,
+        message,
+        agent,
+      },
+    };
+  }
+
+  return { renderActivityMessage, findRenderer };
+}