@assistant-ui/react 0.14.16 → 0.14.19

package/src/tests/toolCallTiming.test.tsx

@@ -0,0 +1,221 @@
+// @vitest-environment jsdom
+
+import { act, render, screen } from "@testing-library/react";
+import type { FC, PropsWithChildren } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AssistantRuntimeProvider } from "../context";
+import * as MessagePrimitive from "../primitives/message";
+import * as ThreadPrimitive from "../primitives/thread";
+import { useLocalRuntime } from "../legacy-runtime/runtime-cores/local/useLocalRuntime";
+import type { ChatModelAdapter, ThreadMessageLike } from "../index";
+import {
+  useToolCallElapsed,
+  unstable_useMessageStallDetection,
+} from "../index";
+
+const noOpAdapter: ChatModelAdapter = {
+  async *run() {},
+};
+
+const toolMessage = (timing?: {
+  startedAt: number;
+  completedAt?: number;
+}): ThreadMessageLike => ({
+  role: "assistant",
+  content: [
+    {
+      type: "tool-call",
+      toolCallId: "tc-1",
+      toolName: "search",
+      args: {},
+      argsText: "{}",
+      ...(timing !== undefined && { timing }),
+    },
+  ],
+  status: { type: "running" },
+});
+
+const ElapsedProbe: FC = () => {
+  const elapsedMs = useToolCallElapsed();
+  return (
+    <span data-testid="elapsed">
+      {elapsedMs === undefined ? "none" : String(elapsedMs)}
+    </span>
+  );
+};
+
+const StallProbe: FC = () => {
+  const { stalled } = unstable_useMessageStallDetection({ thresholdMs: 2000 });
+  return <span data-testid="stalled">{String(stalled)}</span>;
+};
+
+const RuntimeProvider: FC<
+  PropsWithChildren<{ messages: ThreadMessageLike[] }>
+> = ({ messages, children }) => {
+  const runtime = useLocalRuntime(noOpAdapter, { initialMessages: messages });
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+};
+
+const renderHarness = async (messages: ThreadMessageLike[], probe: FC) => {
+  render(<Harness messages={messages} probe={probe} />);
+  // Flush the runtime's deferred initialization, which fake timers hold back.
+  await act(async () => {
+    await vi.advanceTimersByTimeAsync(0);
+  });
+};
+
+const Harness: FC<{ messages: ThreadMessageLike[]; probe: FC }> = ({
+  messages,
+  probe: Probe,
+}) => (
+  <RuntimeProvider messages={messages}>
+    <ThreadPrimitive.Messages
+      components={{
+        Message: () => (
+          <MessagePrimitive.Parts components={{ tools: { Fallback: Probe } }} />
+        ),
+      }}
+    />
+  </RuntimeProvider>
+);
+
+describe("useToolCallElapsed", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:00:10.000Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("returns undefined when the part carries no timing", async () => {
+    await renderHarness([toolMessage()], ElapsedProbe);
+    expect(screen.getByTestId("elapsed").textContent).toBe("none");
+  });
+
+  it("returns the settled duration for completed calls", async () => {
+    const startedAt = Date.now() - 5000;
+    await renderHarness(
+      [toolMessage({ startedAt, completedAt: startedAt + 1500 })],
+      ElapsedProbe,
+    );
+    expect(screen.getByTestId("elapsed").textContent).toBe("1500");
+  });
+
+  it("ticks while the call is running", async () => {
+    const startedAt = Date.now() - 1000;
+    await renderHarness([toolMessage({ startedAt })], ElapsedProbe);
+
+    expect(screen.getByTestId("elapsed").textContent).toBe("1000");
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(3000);
+    });
+
+    expect(screen.getByTestId("elapsed").textContent).toBe("4000");
+  });
+});
+
+describe("useToolCallElapsed on terminated calls", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:00:10.000Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("claims no duration when the call ends without a result (cancelled run)", async () => {
+    const startedAt = Date.now() - 1000;
+    const cancelled: ThreadMessageLike = {
+      role: "assistant",
+      content: [
+        {
+          type: "tool-call",
+          toolCallId: "tc-1",
+          toolName: "search",
+          args: {},
+          argsText: "{}",
+          timing: { startedAt },
+        },
+      ],
+      status: { type: "incomplete", reason: "cancelled" },
+    };
+    await renderHarness([cancelled], ElapsedProbe);
+
+    expect(screen.getByTestId("elapsed").textContent).toBe("none");
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(3000);
+    });
+
+    expect(screen.getByTestId("elapsed").textContent).toBe("none");
+  });
+});
+
+describe("useToolCallElapsed outside any scope", () => {
+  it("returns undefined without a provider instead of throwing", () => {
+    const Standalone: FC = () => {
+      const elapsedMs = useToolCallElapsed();
+      return (
+        <span data-testid="standalone">
+          {elapsedMs === undefined ? "none" : String(elapsedMs)}
+        </span>
+      );
+    };
+    render(<Standalone />);
+    expect(screen.getByTestId("standalone").textContent).toBe("none");
+  });
+});
+
+describe("unstable_useMessageStallDetection", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("reports a stall after the threshold with no content changes", async () => {
+    await renderHarness([toolMessage({ startedAt: 0 })], StallProbe);
+
+    expect(screen.getByTestId("stalled").textContent).toBe("false");
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(2500);
+    });
+
+    expect(screen.getByTestId("stalled").textContent).toBe("true");
+  });
+
+  it("never stalls on settled messages", async () => {
+    const settled: ThreadMessageLike = {
+      role: "assistant",
+      content: [
+        {
+          type: "tool-call",
+          toolCallId: "tc-1",
+          toolName: "search",
+          args: {},
+          argsText: "{}",
+          result: "done",
+        },
+      ],
+      status: { type: "complete", reason: "stop" },
+    };
+    await renderHarness([settled], StallProbe);
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(5000);
+    });
+
+    expect(screen.getByTestId("stalled").textContent).toBe("false");
+  });
+});

package/src/unstable/useComposerInputHistory.test.tsx

@@ -0,0 +1,201 @@
+/** @vitest-environment jsdom */
+import { createEvent, fireEvent, render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const fixture = {
+  messages: [] as { role: string; content: { type: string; text: string }[] }[],
+  composerType: "thread",
+  activeAria: null as object | null,
+  switchedToHandlers: [] as (() => void)[],
+};
+const setText = vi.fn();
+
+vi.mock("@assistant-ui/store", () => ({
+  useAui: () => ({
+    composer: () => ({
+      getState: () => ({ type: fixture.composerType }),
+      setText,
+    }),
+    thread: () => ({ getState: () => ({ messages: fixture.messages }) }),
+    on: (_event: string, cb: () => void) => {
+      fixture.switchedToHandlers.push(cb);
+      return () => {};
+    },
+  }),
+}));
+vi.mock("@assistant-ui/tap", () => ({
+  flushTapSync: (fn: () => void) => fn(),
+}));
+vi.mock("../primitives/composer/trigger/TriggerPopoverRootContext", () => ({
+  useTriggerPopoverRootContextOptional: () => ({
+    getActiveAria: () => fixture.activeAria,
+  }),
+}));
+
+vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => {
+  cb(0);
+  return 0;
+});
+
+import { unstable_useComposerInputHistory } from "./useComposerInputHistory";
+
+const user = (text: string) => ({
+  role: "user",
+  content: [{ type: "text", text }],
+});
+const assistant = (text: string) => ({
+  role: "assistant",
+  content: [{ type: "text", text }],
+});
+
+function Harness() {
+  const history = unstable_useComposerInputHistory();
+  return <textarea data-testid="input" {...history} />;
+}
+
+const setup = (value = "") => {
+  const utils = render(<Harness />);
+  const textarea = screen.getByTestId("input") as HTMLTextAreaElement;
+  textarea.value = value;
+  textarea.setSelectionRange(value.length, value.length);
+  return { ...utils, textarea };
+};
+
+const arrow = (
+  textarea: HTMLTextAreaElement,
+  key: "ArrowUp" | "ArrowDown",
+  init: Record<string, unknown> = {},
+) => fireEvent.keyDown(textarea, { key, ...init });
+
+beforeEach(() => {
+  fixture.messages = [user("first"), assistant("reply"), user("second")];
+  fixture.composerType = "thread";
+  fixture.activeAria = null;
+  fixture.switchedToHandlers = [];
+  setText.mockClear();
+});
+
+describe("unstable_useComposerInputHistory", () => {
+  it("recalls the newest user message on ArrowUp in an empty composer", () => {
+    const { textarea } = setup("");
+    const notPrevented = arrow(textarea, "ArrowUp");
+    expect(notPrevented).toBe(false);
+    expect(setText).toHaveBeenCalledWith("second");
+  });
+
+  it("steps to older entries and consumes the key at the oldest", () => {
+    const { textarea } = setup("");
+    arrow(textarea, "ArrowUp");
+    textarea.value = "second";
+    arrow(textarea, "ArrowUp");
+    expect(setText).toHaveBeenLastCalledWith("first");
+
+    textarea.value = "first";
+    const notPrevented = arrow(textarea, "ArrowUp");
+    expect(notPrevented).toBe(false);
+    expect(setText).toHaveBeenCalledTimes(2);
+  });
+
+  it("restores the draft snapshot on ArrowDown past the newest", () => {
+    const { textarea } = setup("  ");
+    arrow(textarea, "ArrowUp");
+    textarea.value = "second";
+    arrow(textarea, "ArrowDown");
+    expect(setText).toHaveBeenLastCalledWith("  ");
+
+    textarea.value = "  ";
+    const notPrevented = arrow(textarea, "ArrowDown");
+    expect(notPrevented).toBe(true);
+    expect(setText).toHaveBeenCalledTimes(2);
+  });
+
+  it("ignores ArrowUp when the composer holds a typed draft", () => {
+    const { textarea } = setup("draft in progress");
+    const notPrevented = arrow(textarea, "ArrowUp");
+    expect(notPrevented).toBe(true);
+    expect(setText).not.toHaveBeenCalled();
+  });
+
+  it("keeps native arrows when the caret is not on the first line", () => {
+    fixture.messages = [user("other"), user("line1\nline2")];
+    const { textarea } = setup("");
+    arrow(textarea, "ArrowUp");
+    expect(setText).toHaveBeenLastCalledWith("line1\nline2");
+    textarea.value = "line1\nline2";
+    textarea.setSelectionRange(8, 8);
+    const notPrevented = arrow(textarea, "ArrowUp");
+    expect(notPrevented).toBe(true);
+    expect(setText).toHaveBeenCalledTimes(1);
+  });
+
+  it("yields to an open trigger popover", () => {
+    fixture.activeAria = {};
+    const { textarea } = setup("");
+    const notPrevented = arrow(textarea, "ArrowUp");
+    expect(notPrevented).toBe(true);
+    expect(setText).not.toHaveBeenCalled();
+  });
+
+  it("ignores IME composition, modifiers, selections, and prevented events", () => {
+    const { textarea } = setup("");
+    fireEvent.keyDown(textarea, { key: "ArrowUp", isComposing: true });
+    arrow(textarea, "ArrowUp", { shiftKey: true });
+    arrow(textarea, "ArrowUp", { metaKey: true });
+    textarea.value = "ab";
+    textarea.setSelectionRange(0, 2);
+    arrow(textarea, "ArrowUp");
+
+    textarea.value = "";
+    textarea.setSelectionRange(0, 0);
+    const prevented = createEvent.keyDown(textarea, { key: "ArrowUp" });
+    prevented.preventDefault();
+    fireEvent(textarea, prevented);
+    expect(setText).not.toHaveBeenCalled();
+  });
+
+  it("derives the ring from trimmed user texts, newest first, deduped", () => {
+    fixture.messages = [
+      user("first"),
+      user("first"),
+      assistant("noise"),
+      user("   "),
+      user("second"),
+    ];
+    const { textarea } = setup("");
+    arrow(textarea, "ArrowUp");
+    expect(setText).toHaveBeenLastCalledWith("second");
+    textarea.value = "second";
+    arrow(textarea, "ArrowUp");
+    expect(setText).toHaveBeenLastCalledWith("first");
+    textarea.value = "first";
+    arrow(textarea, "ArrowUp");
+    expect(setText).toHaveBeenCalledTimes(2);
+  });
+
+  it("starts a fresh browse after the composer was cleared externally", () => {
+    const { textarea } = setup("");
+    arrow(textarea, "ArrowUp");
+    fixture.messages = [...fixture.messages, user("third")];
+    textarea.value = "";
+    arrow(textarea, "ArrowUp");
+    expect(setText).toHaveBeenLastCalledWith("third");
+  });
+
+  it("is inert on edit composers", () => {
+    fixture.composerType = "edit";
+    const { textarea } = setup("");
+    const notPrevented = arrow(textarea, "ArrowUp");
+    expect(notPrevented).toBe(true);
+    expect(setText).not.toHaveBeenCalled();
+  });
+
+  it("resets browsing when the thread switches", () => {
+    const { textarea } = setup("");
+    arrow(textarea, "ArrowUp");
+    fixture.switchedToHandlers.forEach((cb) => cb());
+    textarea.value = "second";
+    const notPrevented = arrow(textarea, "ArrowDown");
+    expect(notPrevented).toBe(true);
+    expect(setText).toHaveBeenCalledTimes(1);
+  });
+});

package/src/unstable/useComposerInputHistory.ts

@@ -0,0 +1,160 @@
+"use client";
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  type KeyboardEvent,
+  type KeyboardEventHandler,
+} from "react";
+import { useAui } from "@assistant-ui/store";
+import { flushTapSync } from "@assistant-ui/tap";
+import type { ThreadMessage } from "@assistant-ui/core";
+import { getThreadMessageText } from "@assistant-ui/core/internal";
+import { useTriggerPopoverRootContextOptional } from "../primitives/composer/trigger/TriggerPopoverRootContext";
+
+export type Unstable_ComposerInputHistory = {
+  /** Keydown handler to spread onto `ComposerPrimitive.Input`. */
+  onKeyDown: KeyboardEventHandler<HTMLTextAreaElement>;
+};
+
+type BrowseState = {
+  cursor: number;
+  draftSnapshot: string;
+  lastRecalledText: string;
+};
+
+const deriveHistory = (messages: readonly ThreadMessage[]): string[] => {
+  const entries: string[] = [];
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i]!;
+    if (message.role !== "user") continue;
+    const text = getThreadMessageText(message).trim();
+    if (!text) continue;
+    if (entries[entries.length - 1] === text) continue;
+    entries.push(text);
+  }
+  return entries;
+};
+
+const isOnFirstLine = (value: string, caret: number): boolean =>
+  !value.slice(0, caret).includes("\n");
+
+const isOnLastLine = (value: string, caret: number): boolean =>
+  !value.slice(caret).includes("\n");
+
+/**
+ * @deprecated Under active development and might change without notice.
+ *
+ * Terminal-style input history for the thread composer: ArrowUp on an
+ * empty draft recalls previously sent user messages (newest first),
+ * ArrowDown steps back toward the newest and finally restores the draft
+ * that was being typed when browsing started.
+ *
+ * Recall only triggers when the caret is on the first/last line with no
+ * selection, so multi-line editing keeps native arrow behavior. The
+ * handler yields to an open mention/slash popover, to IME composition,
+ * to modifier keys, and to consumer handlers that already called
+ * `preventDefault`. It is inert on edit composers.
+ *
+ * @example
+ * ```tsx
+ * const history = unstable_useComposerInputHistory();
+ * <ComposerPrimitive.Input {...history} />
+ * ```
+ */
+export function unstable_useComposerInputHistory(): Unstable_ComposerInputHistory {
+  const aui = useAui();
+  const popoverCtx = useTriggerPopoverRootContextOptional();
+  const browseRef = useRef<BrowseState | null>(null);
+
+  useEffect(() => {
+    if (aui.composer().getState().type !== "thread") return undefined;
+
+    return aui.on("threadListItem.switchedTo", () => {
+      browseRef.current = null;
+    });
+  }, [aui]);
+
+  const onKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLTextAreaElement>) => {
+      if (e.defaultPrevented) return;
+      if (e.key !== "ArrowUp" && e.key !== "ArrowDown") return;
+      if (e.nativeEvent.isComposing) return;
+      if (e.shiftKey || e.ctrlKey || e.metaKey || e.altKey) return;
+      if (popoverCtx && popoverCtx.getActiveAria() !== null) return;
+      if (aui.composer().getState().type !== "thread") return;
+
+      const textarea = e.currentTarget;
+      const { selectionStart, selectionEnd, value } = textarea;
+      if (selectionStart !== selectionEnd) return;
+
+      if (browseRef.current && value !== browseRef.current.lastRecalledText) {
+        browseRef.current = null;
+      }
+      const browse = browseRef.current;
+
+      const commitText = (text: string): void => {
+        flushTapSync(() => aui.composer().setText(text));
+        // React's controlled-value commit restores the pre-recall caret;
+        // reposition after the commit, before paint.
+        requestAnimationFrame(() => {
+          textarea.setSelectionRange(text.length, text.length);
+        });
+        e.preventDefault();
+      };
+
+      const recall = (
+        history: readonly string[],
+        cursor: number,
+        draftSnapshot: string,
+      ): void => {
+        const entry = history[cursor];
+        if (entry === undefined) {
+          e.preventDefault();
+          return;
+        }
+        browseRef.current = { cursor, draftSnapshot, lastRecalledText: entry };
+        commitText(entry);
+      };
+
+      if (e.key === "ArrowUp") {
+        if (!isOnFirstLine(value, selectionStart)) return;
+
+        if (!browse) {
+          if (value.trim() !== "") return;
+          const history = deriveHistory(aui.thread().getState().messages);
+          if (history.length === 0) return;
+          recall(history, 0, value);
+          return;
+        }
+
+        const history = deriveHistory(aui.thread().getState().messages);
+        const next = browse.cursor + 1;
+        if (next >= history.length) {
+          e.preventDefault();
+          return;
+        }
+        recall(history, next, browse.draftSnapshot);
+        return;
+      }
+
+      if (!browse) return;
+      if (!isOnLastLine(value, selectionEnd)) return;
+
+      const next = browse.cursor - 1;
+      if (next < 0) {
+        browseRef.current = null;
+        commitText(browse.draftSnapshot);
+        return;
+      }
+
+      const history = deriveHistory(aui.thread().getState().messages);
+      recall(history, next, browse.draftSnapshot);
+    },
+    [aui, popoverCtx],
+  );
+
+  return useMemo(() => ({ onKeyDown }), [onKeyDown]);
+}

package/src/unstable/useMessageStallDetection.ts

@@ -0,0 +1,91 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { useAuiState } from "@assistant-ui/store";
+
+export type Unstable_MessageStallDetectionOptions = {
+  /**
+   * Milliseconds of unchanged message content before the message counts as
+   * stalled.
+   * @default 2000
+   */
+  thresholdMs?: number | undefined;
+};
+
+export type Unstable_MessageStallDetection = {
+  /** True while the message is running and its content has not changed for at least `thresholdMs`. */
+  stalled: boolean;
+  /** Milliseconds since the last observed content change. `0` while not stalled. */
+  stalledForMs: number;
+};
+
+/**
+ * @deprecated Under active development and might change without notice.
+ *
+ * Detects mid-run output stalls on the current message: while the message is
+ * running, watches a fingerprint of its content (part count plus text,
+ * argument, and result sizes) and reports a stall once the fingerprint stops
+ * changing for `thresholdMs`. Useful for re-surfacing a "still working"
+ * indicator during tool think-time or provider stalls, after the first
+ * tokens have already streamed.
+ *
+ * Must be used inside a message scope.
+ */
+export function unstable_useMessageStallDetection(
+  options?: Unstable_MessageStallDetectionOptions,
+): Unstable_MessageStallDetection {
+  const thresholdMs = options?.thresholdMs ?? 2000;
+
+  const fingerprint = useAuiState((s) => {
+    if (s.message.status?.type !== "running") return undefined;
+    let size = 0;
+    for (const part of s.message.content) {
+      if (part.type === "text" || part.type === "reasoning") {
+        size += part.text.length;
+      } else if (part.type === "tool-call") {
+        size += part.argsText.length + (part.result !== undefined ? 1 : 0);
+      }
+    }
+    return `${s.message.content.length}:${size}`;
+  });
+
+  const running = fingerprint !== undefined;
+  const lastActivityRef = useRef(Date.now());
+  const [stalled, setStalled] = useState(false);
+  const [, setTick] = useState(0);
+
+  useEffect(() => {
+    if (!running) return undefined;
+    lastActivityRef.current = Date.now();
+    return undefined;
+  }, [running, fingerprint]);
+
+  useEffect(() => {
+    if (!running) {
+      setStalled(false);
+      return undefined;
+    }
+
+    const sinceActivity = Date.now() - lastActivityRef.current;
+    if (sinceActivity >= thresholdMs) {
+      setStalled(true);
+      return undefined;
+    }
+
+    setStalled(false);
+    const id = setTimeout(() => setStalled(true), thresholdMs - sinceActivity);
+    return () => clearTimeout(id);
+  }, [running, fingerprint, thresholdMs]);
+
+  useEffect(() => {
+    if (!stalled) return undefined;
+    const id = setInterval(() => setTick((t) => t + 1), 1000);
+    return () => clearInterval(id);
+  }, [stalled]);
+
+  if (!stalled) return { stalled: false, stalledForMs: 0 };
+  return {
+    stalled: true,
+    stalledForMs: Math.max(0, Date.now() - lastActivityRef.current),
+  };
+}