@copilotkit/vue 2.0.0-rc.1 → 2.0.0-rc.2

package/src/v2/components/chat/tool-call-layout.ts

@@ -0,0 +1,304 @@
+import type { Message, ToolCall, ToolMessage } from "@ag-ui/core";
+
+/**
+ * How the chat shows tool calls.
+ *
+ * - `"grouped"` (default): calls made in a row share one card, collapsed to a
+ *   summary ("Used 3 tools") that opens to a row per call.
+ * - `"line"`: the same grouping as a quiet line of text, like the reasoning
+ *   message's "Thought for 4 seconds".
+ * - `"stacked"`: the latest call on top of a stack of the earlier ones; click
+ *   to fan the stack out into its cards.
+ * - `"turn"`: the agent works in the open (narration, then a row per call),
+ *   and when the reply is done everything before it folds into "Worked for 9s".
+ * - `"separate"`: every call gets its own card, as before grouping existed.
+ *
+ * Only calls drawn by a renderer that opts into grouping (`group: true`) are
+ * grouped; CopilotKit's built-in card from `useDefaultRenderTool()` does. Any
+ * other call always shows on its own and splits the group around it.
+ */
+export type CopilotChatToolCallDisplay =
+  | "grouped"
+  | "line"
+  | "stacked"
+  | "turn"
+  | "separate";
+
+/** One tool call and, once it has finished, the message carrying its result. */
+export interface ToolCallEntry {
+  toolCall: ToolCall;
+  toolMessage?: ToolMessage;
+}
+
+export type ToolCallSegment =
+  /** Consecutive calls drawn by renderers that opted into grouping. */
+  | {
+      kind: "group";
+      id: string;
+      calls: ToolCallEntry[];
+      /** Nothing renders after this group yet, so a running agent may add to it. */
+      trailing: boolean;
+    }
+  /**
+   * A call drawn by a renderer that didn't opt into grouping, or with no
+   * renderer at all. The latter renders nothing (and warns in development)
+   * without breaking a group.
+   */
+  | { kind: "call"; id: string; call: ToolCallEntry; rendered: boolean };
+
+/** What one assistant message's tool-call area renders. */
+export interface ToolCallLayout {
+  segments: ToolCallSegment[];
+  /** Changes whenever anything this layout renders changes; for memoization. */
+  signature: string;
+}
+
+/** Which tool-call renderers are registered. */
+export interface ToolCallRendererNames {
+  /** Tool names with a renderer of their own. */
+  named: ReadonlySet<string>;
+  /** Of those, the ones whose renderer opted into grouping. */
+  groupedNames: ReadonlySet<string>;
+  /** A wildcard (`"*"`) renderer is registered. */
+  wildcard: boolean;
+  /** The wildcard renderer opted into grouping (the built-in card does). */
+  wildcardGroups: boolean;
+}
+
+function contentLength(content: ToolMessage["content"]): number {
+  return typeof content === "string"
+    ? content.length
+    : JSON.stringify(content ?? "").length;
+}
+
+const entrySignature = ({ toolCall, toolMessage }: ToolCallEntry) =>
+  [
+    toolCall.id,
+    toolCall.function.name,
+    toolCall.function.arguments.length,
+    toolMessage
+      ? `${contentLength(toolMessage.content)}${toolMessage.error ? "!" : ""}`
+      : "-",
+  ].join(":");
+
+function signatureOf(segments: ToolCallSegment[]): string {
+  return segments
+    .map((segment) =>
+      segment.kind === "call"
+        ? `c(${entrySignature(segment.call)})`
+        : `g${segment.trailing ? "*" : ""}(${segment.calls.map(entrySignature).join(",")})`,
+    )
+    .join("|");
+}
+
+/** Index of tool results by the call they answer. */
+export function getToolResults(messages: Message[]): Map<string, ToolMessage> {
+  const results = new Map<string, ToolMessage>();
+  for (const message of messages) {
+    if (message.role === "tool") results.set(message.toolCallId, message);
+  }
+  return results;
+}
+
+/**
+ * Lays out the tool calls of every assistant message in `rendered`.
+ *
+ * Calls drawn by a renderer that opted into grouping join the group that's
+ * open; anything else that shows between them closes it: assistant text, a
+ * user, reasoning or activity message, or a call drawn by any other renderer. A group belongs to
+ * the message where it starts, so later messages whose calls joined it render
+ * no tool calls themselves.
+ *
+ * @param rendered - The messages as the chat renders them, in order.
+ * @param all - Every message, for finding tool results (a transform may hide them).
+ * @param renderers - The registered renderers.
+ */
+export function getToolCallLayouts(
+  rendered: Message[],
+  all: Message[],
+  renderers: ToolCallRendererNames,
+): Map<string, ToolCallLayout> {
+  const results = getToolResults(all);
+  const layouts = new Map<string, ToolCallSegment[]>();
+  let open: Extract<ToolCallSegment, { kind: "group" }> | undefined;
+
+  for (const message of rendered) {
+    if (message.role === "tool") continue;
+    if (message.role !== "assistant") {
+      open = undefined;
+      continue;
+    }
+    if (typeof message.content === "string" && message.content.trim()) {
+      open = undefined;
+    }
+
+    const segments: ToolCallSegment[] = [];
+    layouts.set(message.id, segments);
+    // Streaming can repeat a call: keep its first position, last content.
+    const toolCalls = new Map<string, ToolCall>();
+    for (const toolCall of message.toolCalls ?? []) {
+      toolCalls.set(toolCall.id, toolCall);
+    }
+    for (const toolCall of toolCalls.values()) {
+      const entry = { toolCall, toolMessage: results.get(toolCall.id) };
+
+      const name = toolCall.function.name;
+      const named = renderers.named.has(name);
+      const rendered = named || renderers.wildcard;
+      const groups = named
+        ? renderers.groupedNames.has(name)
+        : renderers.wildcardGroups;
+
+      if (!rendered || !groups) {
+        if (rendered) open = undefined;
+        segments.push({ kind: "call", id: toolCall.id, call: entry, rendered });
+      } else if (open) {
+        open.calls.push(entry);
+      } else {
+        open = {
+          kind: "group",
+          id: toolCall.id,
+          calls: [entry],
+          trailing: false,
+        };
+        segments.push(open);
+      }
+    }
+  }
+  if (open) open.trailing = true;
+
+  const layout = new Map<string, ToolCallLayout>();
+  for (const [id, segments] of layouts) {
+    layout.set(id, { segments, signature: signatureOf(segments) });
+  }
+  return layout;
+}
+
+const TOOL_CALL_SLOT_PREFIX = "tool-call-";
+
+/**
+ * Which renderers draw tool calls, from the registered renderers and the
+ * view's tool-call slots. A slot wins over a registered renderer and never
+ * groups, since the chat can't tell what it draws: `#tool-call-<name>` takes
+ * that tool, and `#tool-call` takes every tool.
+ *
+ * @param renderers - The registered renderers (`copilotkit.renderToolCalls`).
+ * @param slotNames - The names of the slots the view was given.
+ */
+export function getToolCallRendererNames(
+  renderers: readonly { name: string; group?: boolean }[],
+  slotNames: readonly string[] = [],
+): ToolCallRendererNames {
+  const wildcardSlot = slotNames.includes("tool-call");
+  const slotTools = slotNames
+    .filter((name) => name.startsWith(TOOL_CALL_SLOT_PREFIX))
+    .map((name) => name.slice(TOOL_CALL_SLOT_PREFIX.length));
+  const named = renderers.filter((renderer) => renderer.name !== "*");
+  const wildcards = renderers.filter((renderer) => renderer.name === "*");
+  return {
+    named: new Set([...named.map((renderer) => renderer.name), ...slotTools]),
+    groupedNames: new Set(
+      wildcardSlot
+        ? []
+        : named
+            .filter(
+              (renderer) =>
+                renderer.group && !slotTools.includes(renderer.name),
+            )
+            .map((renderer) => renderer.name),
+    ),
+    wildcard: wildcards.length > 0 || wildcardSlot,
+    wildcardGroups:
+      !wildcardSlot && wildcards.some((renderer) => renderer.group),
+  };
+}
+
+/** A reply's working phase, for the `"turn"` display. */
+export interface TurnWork {
+  /** Stable across the turn's life: the id of the user message it answers. */
+  key: string;
+  /** The first assistant-side message, where the "Worked for" line goes. */
+  firstMessageId: string;
+  /** Everything up to and including the last message with a tool call. */
+  workMessageIds: ReadonlySet<string>;
+  /**
+   * The reply's last assistant message, when it has text and is part of the
+   * work (it also calls a tool). Its text is the answer, so it stays out.
+   */
+  replyTextMessageId?: string;
+  calls: ToolCallEntry[];
+  /** No user message follows, so the agent may still be working on it. */
+  isLatest: boolean;
+}
+
+/**
+ * Finds the working phase of every reply in `rendered`: its messages up to the
+ * last one that calls a tool. Text in there was narration; what follows is the
+ * reply itself. Replies that called no tools are omitted, except the latest,
+ * which may be about to.
+ */
+export function getTurnWork(
+  rendered: Message[],
+  layouts: ReadonlyMap<string, ToolCallLayout>,
+): Map<string, TurnWork> {
+  const turns = new Map<string, TurnWork>();
+  let start = 0;
+  while (start < rendered.length) {
+    let end = start;
+    while (end < rendered.length && rendered[end]!.role !== "user") end++;
+    const key = start > 0 ? rendered[start - 1]!.id : "start";
+    const visible = rendered
+      .slice(start, end)
+      .filter((message) => message.role !== "tool");
+    const isLatest = end === rendered.length;
+
+    // A message's calls may sit in a group an earlier message owns, so
+    // collect every shown call first, then find the last message making one.
+    const calls: ToolCallEntry[] = [];
+    for (const message of visible) {
+      for (const segment of layouts.get(message.id)?.segments ?? []) {
+        if (segment.kind === "group") calls.push(...segment.calls);
+        else if (segment.rendered) calls.push(segment.call);
+      }
+    }
+    const shown = new Set(calls.map((entry) => entry.toolCall.id));
+    let lastWork = -1;
+    visible.forEach((message, index) => {
+      if (
+        message.role === "assistant" &&
+        message.toolCalls?.some((call) => shown.has(call.id))
+      ) {
+        lastWork = index;
+      }
+    });
+
+    const first = visible[0];
+    if (first && (calls.length > 0 || isLatest)) {
+      let lastAssistant = -1;
+      visible.forEach((message, index) => {
+        if (message.role === "assistant") lastAssistant = index;
+      });
+      const replyText = visible[lastAssistant]?.content;
+      const endsWithWork =
+        lastAssistant >= 0 &&
+        lastAssistant <= lastWork &&
+        typeof replyText === "string" &&
+        replyText.trim().length > 0;
+
+      turns.set(key, {
+        key,
+        firstMessageId: first.id,
+        workMessageIds: new Set(
+          visible.slice(0, lastWork + 1).map((message) => message.id),
+        ),
+        replyTextMessageId: endsWithWork
+          ? visible[lastAssistant]!.id
+          : undefined,
+        calls,
+        isLatest,
+      });
+    }
+    start = end + 1;
+  }
+  return turns;
+}

package/src/v2/components/chat/turn-work.ts

@@ -0,0 +1,61 @@
+import { defineComponent, h, inject } from "vue";
+import type { FunctionalComponent } from "vue";
+import { CopilotChatCollapsible } from "./tool-call-group-parts";
+import { ToolCallDisplayContextKey } from "./tool-call-display-context";
+
+/** "45s", "1m 5s", "2m". Used for the live timer and the final duration. */
+export function formatDuration(ms: number): string {
+  const seconds = Math.max(0, Math.floor(ms / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const rest = seconds % 60;
+  return rest ? `${minutes}m ${rest}s` : `${minutes}m`;
+}
+
+/**
+ * Folds its content away with a reply's work in the `"turn"` display. Without
+ * `open` (any other display) it renders the content as is.
+ * @internal
+ */
+export const TurnWorkFold: FunctionalComponent<{ open?: boolean }> = (
+  props,
+  { slots },
+) =>
+  props.open === undefined
+    ? slots.default?.()
+    : h(CopilotChatCollapsible, { open: props.open }, slots);
+TurnWorkFold.props = ["open"];
+
+/**
+ * In the `"turn"` tool-call display, text in a reply's working phase was
+ * narration: it fades to muted once a call follows it, and folds away with the
+ * rest of the work when the reply is done. The wrapper is there for every
+ * message in that display, so text that turns into narration keeps its node
+ * (and its place) rather than remounting.
+ * @internal
+ */
+export const CopilotChatWorkText = defineComponent({
+  name: "CopilotChatWorkText",
+  props: { messageId: { type: String, required: true } },
+  setup(props, { slots }) {
+    const context = inject(ToolCallDisplayContextKey, null);
+    return () => {
+      if (context?.value.display !== "turn") return slots.default?.();
+      const open = context.value.workTextOpen.get(props.messageId);
+      return h(
+        CopilotChatCollapsible,
+        { open: open ?? true, class: "cpk-assistant-message-work-text" },
+        () => [
+          h(
+            "div",
+            {
+              class: "cpk-assistant-message-work-text-content",
+              "data-work-text": open === undefined ? "reply" : "narration",
+            },
+            slots.default?.(),
+          ),
+        ],
+      );
+    };
+  },
+});

package/src/v2/components/chat/types.ts

@@ -6,24 +6,73 @@ import type {
   ToolMessage,
   UserMessage,
 } from "@ag-ui/core";
+import type { VNode } from "vue";
 import type { CopilotKitCoreErrorCode, ToolCallStatus } from "@copilotkit/core";
 import type { Suggestion } from "@copilotkit/core";
 import type {
   Attachment,
   AttachmentsConfig,
   AttachmentModality,
+  InputContentSource,
 } from "@copilotkit/shared";
 import type { CopilotChatLabels } from "../../providers/types";
 import type { InterruptEvent } from "../../types";
 import type { AutoScrollMode } from "./normalize-auto-scroll";
+import type {
+  CopilotChatToolCallDisplay,
+  ToolCallEntry,
+} from "./tool-call-layout";
 
 export type CopilotChatInputMode = "input" | "transcribe" | "processing";
 export type { Attachment, AttachmentsConfig, AttachmentModality };
 export type { AutoScrollMode };
+export type { CopilotChatToolCallDisplay, ToolCallEntry };
+
+/** How a `CopilotChatToolCallGroup` draws its calls. */
+export type CopilotChatToolCallGroupAppearance = "card" | "line" | "stack";
+
+/** Props of the `#tool-calls-group` slot, which replaces a group of calls. */
+export interface CopilotChatToolCallsGroupSlotProps {
+  /** The calls in the group, in order. */
+  calls: ToolCallEntry[];
+  /** The appearance the view's `toolCallDisplay` asks for. */
+  appearance: CopilotChatToolCallGroupAppearance;
+  /** The agent is running and nothing follows the group, so more calls may join it. */
+  isActive: boolean;
+  /**
+   * Draws one call through the registered renderers and tool-call slots.
+   * Render the VNode with `<component :is="renderCall(call)" />`.
+   */
+  renderCall: (call: ToolCallEntry) => VNode;
+}
+
+/**
+ * Props of `CopilotChatWorkSummary` and of the `#work-summary` slot, which
+ * replaces the "Working… / Worked for 9s" line of the `"turn"` display.
+ */
+export interface CopilotChatWorkSummarySlotProps {
+  /** The agent is still working on this reply. */
+  isWorking: boolean;
+  /** Whether the work (narration and tool calls) is showing. */
+  isOpen: boolean;
+  /** The tool calls the reply made. */
+  calls: ToolCallEntry[];
+  /**
+   * How long the agent has worked on the reply, in ms, summed over its runs
+   * so time spent waiting between them doesn't count. Only known for replies
+   * this client watched start; without it the summary shows the tool count.
+   */
+  elapsedMs?: number;
+  /** When the current run started (epoch ms), while the agent is working. */
+  workingSince?: number;
+  /** Opens or closes the reply's work. */
+  onClick: () => void;
+}
 
 export interface CopilotChatAttachmentRendererProps {
   type: AttachmentModality;
-  source: Attachment["source"];
+  /** Any AG-UI content source, as in React; a `file` handle shows no preview. */
+  source: InputContentSource;
   filename?: string;
   className?: string;
 }
@@ -94,6 +143,20 @@ export interface CopilotChatViewProps {
   onDragLeave?: (event: DragEvent) => void;
   onDrop?: (event: DragEvent) => void;
   onFinishTranscribeWithAudio?: (audioBlob: Blob) => void | Promise<void>;
+  /**
+   * How tool calls show. Defaults to `"grouped"`: calls made in a row share
+   * one card that opens to a row per call. `"line"` and `"stacked"` group
+   * them too; `"separate"` gives every call its own card. Calls drawn by a
+   * renderer that does not set `group: true`, or by a tool-call slot, always
+   * show on their own.
+   */
+  toolCallDisplay?: CopilotChatToolCallDisplay;
+  /**
+   * Whether reply thumbs record ratings for Automatic Learning once a
+   * Trajectory has started. Defaults to `true`; set `false` to keep the
+   * thumbs to your own `thumbs-up` / `thumbs-down` handlers and slots.
+   */
+  messageFeedback?: boolean;
 }
 
 export interface CopilotChatProps extends Omit<
@@ -319,13 +382,56 @@ export interface CopilotChatAssistantMessageCopyButtonSlotProps {
   label: string;
 }
 
+/**
+ * Attributes and listeners that let a thumb record a Learning rating and open
+ * its comment popover. Bind them on the thumb's `<button>` with `v-bind`;
+ * they are empty while the chat records no ratings.
+ */
+export type CopilotChatAssistantMessageThumbProps = Record<string, unknown>;
+
 export interface CopilotChatAssistantMessageThumbsUpButtonSlotProps {
-  onThumbsUp: () => void;
+  /**
+   * Rates the reply. Pass the click event, so the comment points at the
+   * clicked thumb and a keyboard click moves focus into it.
+   */
+  onThumbsUp: (event?: MouseEvent) => void;
   label: string;
+  /** This rating is the chosen one (Learning only). */
+  pressed: boolean;
+  thumbProps: CopilotChatAssistantMessageThumbProps;
 }
 
 export interface CopilotChatAssistantMessageThumbsDownButtonSlotProps {
-  onThumbsDown: () => void;
+  /** See {@link CopilotChatAssistantMessageThumbsUpButtonSlotProps.onThumbsUp}. */
+  onThumbsDown: (event?: MouseEvent) => void;
+  label: string;
+  /** This rating is the chosen one (Learning only). */
+  pressed: boolean;
+  thumbProps: CopilotChatAssistantMessageThumbProps;
+}
+
+/** Props of the `feedback-comment` slot: the comment field of a rating. */
+export interface CopilotChatAssistantMessageFeedbackCommentSlotProps {
+  value: string;
+  /** The comment already saved. */
+  savedComment: string;
+  /** Bind as `:ref` on the text field, so a keyboard rating can focus it. */
+  inputRef: (element: unknown) => void;
+  onChange: (value: string) => void;
+  /** Saves the comment, closes the popover and returns focus to the thumb. */
+  onSubmit: () => void;
+  onEditingChange: (editing: boolean) => void;
+  /**
+   * Focus left the form for `next`, or for no focusable element when null.
+   * Not called when the window loses focus.
+   */
+  onLeave: (next: Element | null) => void;
+}
+
+/** Props of the `inspector-button` slot. */
+export interface CopilotChatAssistantMessageInspectorButtonSlotProps {
+  /** Opens this message in the Inspector. */
+  onInspect: () => void;
   label: string;
 }
 
@@ -498,6 +604,8 @@ export interface CopilotSidebarViewToggleButtonSlotProps {
 export interface CopilotSidebarViewProps extends CopilotChatViewProps {
   width?: number | string;
   defaultOpen?: boolean;
+  /** The edge the sidebar docks to. Defaults to `"right"`. */
+  position?: "left" | "right";
 }
 
 export type CopilotPopupViewHeaderSlotProps = CopilotSidebarViewHeaderSlotProps;
@@ -533,4 +641,6 @@ export interface CopilotPopupProps extends CopilotChatProps {
 export interface CopilotSidebarProps extends CopilotChatProps {
   width?: number | string;
   defaultOpen?: boolean;
+  /** The edge the sidebar docks to. Defaults to `"right"`. */
+  position?: CopilotSidebarViewProps["position"];
 }

package/src/v2/components/chat/use-lightbox.ts

@@ -0,0 +1,64 @@
+import { nextTick, ref } from "vue";
+import { useCopilotId } from "../ui/use-id";
+
+type DocWithVT = Document & {
+  startViewTransition?: (cb: () => void | Promise<void>) => {
+    finished: Promise<void>;
+  };
+};
+
+/**
+ * Opens and closes a lightbox, using the View Transition API to morph the
+ * thumbnail into the full-screen content, as React's `useLightbox`.
+ *
+ * `view-transition-name` must be on exactly one element at a time: on the
+ * thumbnail in the old state, and on the lightbox content (bind `vtName` to
+ * it) in the new one. The transition callback waits for Vue to render the
+ * change, so the API can snapshot old and new correctly.
+ * @internal
+ */
+export function useLightbox() {
+  const thumbnailRef = ref<HTMLElement | null>(null);
+  const open = ref(false);
+  // A custom ident: Vue's ids can hold characters CSS does not allow there.
+  const vtName = useCopilotId("cpk-lightbox").replace(/[^\w-]/g, "-");
+
+  const openLightbox = () => {
+    const thumb = thumbnailRef.value;
+    const doc =
+      typeof document === "undefined" ? undefined : (document as DocWithVT);
+
+    if (doc?.startViewTransition && thumb) {
+      thumb.style.viewTransitionName = vtName;
+      doc.startViewTransition(async () => {
+        thumb.style.viewTransitionName = "";
+        open.value = true;
+        await nextTick();
+      });
+    } else {
+      open.value = true;
+    }
+  };
+
+  const closeLightbox = () => {
+    const thumb = thumbnailRef.value;
+    const doc =
+      typeof document === "undefined" ? undefined : (document as DocWithVT);
+
+    if (doc?.startViewTransition && thumb) {
+      const transition = doc.startViewTransition(async () => {
+        open.value = false;
+        await nextTick();
+        thumb.style.viewTransitionName = vtName;
+      });
+      const clear = () => {
+        thumb.style.viewTransitionName = "";
+      };
+      transition.finished.then(clear, clear);
+    } else {
+      open.value = false;
+    }
+  };
+
+  return { thumbnailRef, vtName, open, openLightbox, closeLightbox };
+}

package/src/v2/components/icons/index.ts

@@ -20,4 +20,8 @@ export {
   CheckCircle as IconCheckCircle,
   Circle as IconCircle,
   PanelLeftOpen as IconPanelLeftOpen,
+  Play as IconPlay,
+  Upload as IconUpload,
+  Wrench as IconWrench,
+  EyeOff as IconEyeOff,
 } from "lucide-vue-next";