@ulearning/ai-sdk 0.0.0-stage → 1.0.0-next.0

package/src/unstable/useMentionAdapter.ts

@@ -0,0 +1,276 @@
+"use client";
+
+import {
+  computed,
+  toValue,
+  type Component,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+} from "vue";
+import { useAui } from "@ulearning/ai-store";
+import type {
+  Unstable_DirectiveFormatter,
+  Unstable_TriggerAdapter,
+  Unstable_TriggerCategory,
+  Unstable_TriggerItem,
+} from "@ulearning/ai-core";
+import { unstable_defaultDirectiveFormatter } from "@ulearning/ai-core";
+import type { ReadonlyJSONObject } from "@ulearning/ai-stream/utils";
+import { matchesTriggerItemQuery } from "../primitives/composer/trigger/matchesTriggerItemQuery";
+import {
+  shallowEqualRecords,
+  useModelContextSnapshot,
+  type ModelContextSnapshotSource,
+} from "./useModelContextSnapshot";
+
+/**
+ * Icon component shape consumed by `ComposerTriggerPopover`'s `iconMap`.
+ *
+ * @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release.
+ */
+export type Unstable_IconComponent = Component<{ className?: string }>;
+
+/** @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release. */
+export type Unstable_Mention = {
+  readonly id: string;
+  readonly type: string;
+  readonly label: string;
+  readonly description?: string | undefined;
+  /** Shortcut for `metadata.icon`; merged with `metadata` if both are given. */
+  readonly icon?: string | undefined;
+  readonly metadata?: ReadonlyJSONObject | undefined;
+};
+
+/** @deprecated Experimental since 2026-03-16. Not scheduled for removal; the API may change in any release. */
+export type Unstable_MentionCategory = {
+  readonly id: string;
+  readonly label: string;
+  readonly items: readonly Unstable_Mention[];
+};
+
+/** @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release. */
+export type Unstable_ModelContextToolsOptions = {
+  /**
+   * Wrap tools in a dedicated category. Selects drill-down mode on its own
+   * when `categories` is unset and `items` is omitted.
+   */
+  readonly category?: { readonly id: string; readonly label: string };
+  /** Format tool name for display. */
+  readonly formatLabel?: (toolName: string) => string;
+  /** Default icon key for each tool. */
+  readonly icon?: string;
+};
+
+/** @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release. */
+export type Unstable_UseMentionAdapterOptions = {
+  /**
+   * Flat mention list. Ignored when `categories` is set, and keeps the
+   * adapter flat when a tool `category` is configured.
+   */
+  readonly items?: readonly Unstable_Mention[];
+  /** Categorized mentions for drill-down navigation. */
+  readonly categories?: readonly Unstable_MentionCategory[];
+  /**
+   * How tools registered in model context integrate.
+   * - `false`: exclude.
+   * - `true`: include (default when no `items`/`categories`; as a category
+   *   if `categories` is set, flat otherwise).
+   * - object: explicit config; `category` also selects drill-down mode.
+   *
+   * Omitted → defaults to `true` iff neither `items` nor `categories`.
+   */
+  readonly includeModelContextTools?:
+    | boolean
+    | Unstable_ModelContextToolsOptions;
+  /** Directive formatter. @default unstable_defaultDirectiveFormatter */
+  readonly formatter?: Unstable_DirectiveFormatter;
+  /** Fires after an item is inserted into the composer. */
+  readonly onInserted?: (item: Unstable_TriggerItem) => void;
+  /** Maps `metadata.icon` / `category.id` string keys to Vue components. */
+  readonly iconMap?: Record<string, Unstable_IconComponent>;
+  /** Fallback icon when no entry in `iconMap` matches. */
+  readonly fallbackIcon?: Unstable_IconComponent;
+};
+
+/** @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release. */
+export type Unstable_MentionDirective = {
+  readonly formatter: Unstable_DirectiveFormatter;
+  readonly onInserted?: ((item: Unstable_TriggerItem) => void) | undefined;
+};
+
+const EMPTY_TOOL_MENTIONS: Readonly<Record<string, string | undefined>> =
+  Object.freeze({});
+
+// The description is copied out rather than reached through the tool, so a
+// provider that returns a stable tool object and edits it in place is observed.
+const toolMentionSource: ModelContextSnapshotSource<
+  Readonly<Record<string, string | undefined>>
+> = {
+  empty: EMPTY_TOOL_MENTIONS,
+  read: (aui) => {
+    const tools = aui.thread.getModelContext().tools;
+    if (!tools) return EMPTY_TOOL_MENTIONS;
+    const mentions = Object.create(null) as Record<string, string | undefined>;
+    for (const [name, tool] of Object.entries(tools)) {
+      mentions[name] = tool.description;
+    }
+    return mentions;
+  },
+  subscribe: (aui, onChange) => {
+    const unsubscribeContext = aui.on("thread.modelContextUpdate", onChange);
+    // Rebinding the thread event subject to a new thread does not replay it,
+    // so a switch between threads carrying different providers is its own
+    // refresh trigger. Subscribed globally because a composer can render
+    // without a thread list scope.
+    const unsubscribeSelection = aui.on(
+      { scope: "*", event: "threads.selectionChanged" },
+      onChange,
+    );
+    return () => {
+      unsubscribeContext();
+      unsubscribeSelection();
+    };
+  },
+  isEqual: shallowEqualRecords,
+};
+
+/**
+ * Creates a spreadable `{ adapter, directive }` bundle for `@` mentions.
+ * Supports tools registered in model context, explicit items, or both —
+ * flat or categorized.
+ *
+ * @deprecated Experimental since 2026-04-15. Not scheduled for removal; the API may change in any release.
+ *
+ * @example
+ * ```tsx
+ * const mention = unstable_useMentionAdapter();
+ * <ComposerTriggerPopover char="@" {...mention} />
+ * ```
+ */
+export function unstable_useMentionAdapter(
+  options: MaybeRefOrGetter<
+    Unstable_UseMentionAdapterOptions | undefined
+  > = undefined,
+): ComputedRef<{
+  adapter: Unstable_TriggerAdapter;
+  directive: Unstable_MentionDirective;
+  iconMap?: Record<string, Unstable_IconComponent>;
+  fallbackIcon?: Unstable_IconComponent;
+}> {
+  const aui = useAui();
+  const items = computed(() => toValue(options)?.items);
+  const categories = computed(() => toValue(options)?.categories);
+  const includeTools = computed(
+    () =>
+      toValue(options)?.includeModelContextTools ??
+      (!items.value && !categories.value),
+  );
+  const toolsConfig = computed(() =>
+    typeof includeTools.value === "object" ? includeTools.value : undefined,
+  );
+  const wantsTools = computed(() => includeTools.value !== false);
+  const formatter = computed(() => toValue(options)?.formatter);
+  const onInserted = computed(() => toValue(options)?.onInserted);
+  const isCategorized = computed(
+    () =>
+      categories.value !== undefined ||
+      (toolsConfig.value?.category !== undefined && items.value === undefined),
+  );
+  const toolMentions = useModelContextSnapshot(
+    aui,
+    wantsTools,
+    toolMentionSource,
+  );
+
+  const adapter = computed<Unstable_TriggerAdapter>(() => {
+    const formatLabel = toolsConfig.value?.formatLabel;
+    const defaultIcon = toolsConfig.value?.icon;
+    const toolItems = wantsTools.value
+      ? Object.entries(toolMentions.value).map(([name, description]) =>
+          toTriggerItem({
+            id: name,
+            type: "tool",
+            label: formatLabel ? formatLabel(name) : name,
+            description,
+            icon: defaultIcon,
+          }),
+        )
+      : [];
+
+    // Categorized: drill-down mode
+    if (isCategorized.value) {
+      const groups = (categories.value ?? []).map((cat) => ({
+        id: cat.id,
+        label: cat.label,
+        items: cat.items.map(toTriggerItem),
+      }));
+      const allGroups =
+        toolItems.length > 0
+          ? [
+              ...groups,
+              {
+                id: toolsConfig.value?.category?.id ?? "tools",
+                label: toolsConfig.value?.category?.label ?? "Tools",
+                items: toolItems,
+              },
+            ]
+          : groups;
+
+      return {
+        categories: () => allGroups.map(({ id, label }) => ({ id, label })),
+        categoryItems: (id) => allGroups.find((g) => g.id === id)?.items ?? [],
+        search: (query) => {
+          const lower = query.toLowerCase();
+          return allGroups
+            .flatMap((g) => g.items)
+            .filter((item) => matchesTriggerItemQuery(item, lower));
+        },
+      };
+    }
+
+    // Flat: items + (optionally) tools, all in one search pool
+    const flatItems = (items.value ?? []).map(toTriggerItem);
+    // Dedupe by id — explicit items win.
+    const seen = new Set(flatItems.map((i) => i.id));
+    const flatPool = [
+      ...flatItems,
+      ...toolItems.filter((t) => !seen.has(t.id)),
+    ];
+
+    return {
+      categories: (): readonly Unstable_TriggerCategory[] => [],
+      categoryItems: () => [],
+      search: (query) => {
+        const lower = query.toLowerCase();
+        return flatPool.filter((item) => matchesTriggerItemQuery(item, lower));
+      },
+    };
+  });
+
+  const directive = computed<Unstable_MentionDirective>(() => ({
+    formatter: formatter.value ?? unstable_defaultDirectiveFormatter,
+    ...(onInserted.value ? { onInserted: onInserted.value } : {}),
+  }));
+
+  return computed(() => {
+    const current = toValue(options);
+    return {
+      adapter: adapter.value,
+      directive: directive.value,
+      ...(current?.iconMap ? { iconMap: current.iconMap } : {}),
+      ...(current?.fallbackIcon ? { fallbackIcon: current.fallbackIcon } : {}),
+    };
+  });
+}
+
+function toTriggerItem(m: Unstable_Mention): Unstable_TriggerItem {
+  const metadata =
+    m.icon !== undefined ? { ...(m.metadata ?? {}), icon: m.icon } : m.metadata;
+  return {
+    id: m.id,
+    type: m.type,
+    label: m.label,
+    ...(m.description !== undefined ? { description: m.description } : {}),
+    ...(metadata !== undefined ? { metadata } : {}),
+  };
+}

package/src/unstable/useMessageStallDetection.lifecycle.test.ts

@@ -0,0 +1,120 @@
+// @vitest-environment jsdom
+import { defineComponent, h, KeepAlive, nextTick, shallowRef } from "vue";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import {
+  AssistantRuntimeProvider,
+  ThreadPrimitiveMessages,
+  useExternalStoreRuntime,
+} from "@ulearning/ai-core/vue";
+import type { ThreadMessageLike } from "@ulearning/ai-core";
+import { cleanup, render } from "../tests/vue";
+import { mountMessageAction } from "../tests/messageAction";
+import { unstable_useMessageStallDetection } from "./useMessageStallDetection";
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(10000);
+});
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+});
+
+it("reacts to threshold getters and resets for equal-length content and settled messages", async () => {
+  const threshold = shallowRef(2000);
+  const Probe = defineComponent({
+    setup() {
+      const result = unstable_useMessageStallDetection(() => ({
+        thresholdMs: threshold.value,
+      }));
+      return () =>
+        h("output", `${result.value.stalled}:${result.value.stalledForMs}`);
+    },
+  });
+  const view = mountMessageAction(() => h(Probe), {
+    content: [{ type: "text", text: "first" }],
+    status: { type: "running" },
+  });
+  await nextTick();
+  await vi.advanceTimersByTimeAsync(1500);
+  threshold.value = 1000;
+  await nextTick();
+  expect(view.container.textContent).toBe("true:1500");
+  await view.update({
+    ...view.message.value,
+    content: [{ type: "text", text: "other" }],
+  });
+  expect(view.container.textContent).toBe("false:0");
+  await vi.advanceTimersByTimeAsync(999);
+  expect(view.container.textContent).toBe("false:0");
+  await vi.advanceTimersByTimeAsync(1);
+  expect(view.container.textContent).toBe("true:1000");
+  await view.update({
+    ...view.message.value,
+    status: { type: "complete", reason: "stop" },
+  });
+  expect(view.container.textContent).toBe("false:0");
+  await vi.advanceTimersByTimeAsync(5000);
+  expect(view.container.textContent).toBe("false:0");
+});
+
+it("pauses timers while retained and stops ticking after permanent release", async () => {
+  const shown = shallowRef(true);
+  let detection!: ReturnType<typeof unstable_useMessageStallDetection>;
+  const Probe = defineComponent({
+    setup() {
+      detection = unstable_useMessageStallDetection();
+      return () => h("output", String(detection.value.stalled));
+    },
+  });
+  const Owner = defineComponent({
+    setup() {
+      const runtime = useExternalStoreRuntime({
+        messages: [
+          {
+            id: "message",
+            role: "assistant",
+            content: [{ type: "text", text: "streaming" }],
+            status: { type: "running" },
+          },
+        ],
+        convertMessage: (message: ThreadMessageLike) => message,
+        onNew: async () => {},
+      });
+      return () =>
+        h(
+          AssistantRuntimeProvider,
+          { runtime },
+          {
+            default: () =>
+              h(ThreadPrimitiveMessages, { components: { Message: Probe } }),
+          },
+        );
+    },
+  });
+  const view = render(
+    h(
+      defineComponent({
+        setup: () => () =>
+          h(KeepAlive, null, {
+            default: () => (shown.value ? h(Owner) : null),
+          }),
+      }),
+    ),
+  );
+  await nextTick();
+  shown.value = false;
+  await nextTick();
+  await vi.advanceTimersByTimeAsync(5000);
+  expect(detection.value.stalled).toBe(false);
+  shown.value = true;
+  await nextTick();
+  await vi.advanceTimersByTimeAsync(1999);
+  expect(detection.value.stalled).toBe(false);
+  await vi.advanceTimersByTimeAsync(1);
+  expect(detection.value.stalled).toBe(true);
+  view.unmount();
+  const stopped = detection.value.stalledForMs;
+  await vi.advanceTimersByTimeAsync(5000);
+  expect(detection.value.stalledForMs).toBe(stopped);
+});

package/src/unstable/useMessageStallDetection.test.tsx

@@ -0,0 +1,59 @@
+// @vitest-environment jsdom
+
+import { renderToString } from "@vue/server-renderer";
+import { defineComponent, h } from "vue";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  AssistantRuntimeProvider,
+  ThreadPrimitiveMessages,
+  useExternalStoreRuntime,
+} from "@ulearning/ai-core/vue";
+import type { ThreadMessageLike } from "@ulearning/ai-core";
+import { visibleHTML } from "../tests/vue";
+import { unstable_useMessageStallDetection } from "./useMessageStallDetection";
+
+describe("unstable_useMessageStallDetection", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("does not read the wall clock during server render", async () => {
+    const Probe = defineComponent({
+      setup() {
+        const detection = unstable_useMessageStallDetection();
+        return () => h("span", String(detection.value.stalled));
+      },
+    });
+    const Fixture = defineComponent({
+      setup() {
+        const runtime = useExternalStoreRuntime({
+          messages: [
+            {
+              id: "message",
+              role: "assistant",
+              createdAt: new Date(0),
+              content: [{ type: "text", text: "streaming" }],
+              status: { type: "running" },
+            },
+          ],
+          convertMessage: (message: ThreadMessageLike) => message,
+          onNew: async () => {},
+        });
+        return () =>
+          h(
+            AssistantRuntimeProvider,
+            { runtime },
+            {
+              default: () =>
+                h(ThreadPrimitiveMessages, { components: { Message: Probe } }),
+            },
+          );
+      },
+    });
+    const nowSpy = vi.spyOn(Date, "now");
+    const output = document.createElement("div");
+    output.innerHTML = await renderToString(h(Fixture));
+    expect(visibleHTML(output)).toBe("<span>false</span>");
+    expect(nowSpy).not.toHaveBeenCalled();
+  });
+});

package/src/unstable/useMessageStallDetection.ts

@@ -0,0 +1,147 @@
+"use client";
+
+import {
+  computed,
+  shallowRef,
+  toValue,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+} from "vue";
+import { useAuiState } from "@ulearning/ai-store";
+import {
+  useIsomorphicLayoutEffect,
+  useShallowSelector,
+} from "@ulearning/ai-store/internal";
+
+/** @deprecated Experimental since 2026-06-13. Not scheduled for removal; the API may change in any release. */
+export type Unstable_MessageStallDetectionOptions = {
+  /**
+   * Milliseconds of unchanged message content before the message counts as
+   * stalled.
+   * @default 2000
+   */
+  thresholdMs?: number | undefined;
+};
+
+/** @deprecated Experimental since 2026-06-13. Not scheduled for removal; the API may change in any release. */
+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;
+};
+
+/**
+ * Detects mid-run output stalls on the current message: while the message is
+ * running, watches its text, reasoning, and tool-argument values plus tool-result
+ * availability and reports a stall once they stop 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.
+ *
+ * @deprecated Experimental since 2026-06-13. Not scheduled for removal; the API may change in any release.
+ */
+export function unstable_useMessageStallDetection(
+  options: MaybeRefOrGetter<
+    Unstable_MessageStallDetectionOptions | undefined
+  > = undefined,
+): ComputedRef<Unstable_MessageStallDetection> {
+  const thresholdMs = computed(() => toValue(options)?.thresholdMs ?? 2000);
+
+  const activity = useAuiState(
+    useShallowSelector((s) => {
+      const running = s.message.status?.type === "running";
+      if (!running) return [false];
+
+      const values: unknown[] = [true, s.message.content.length];
+
+      for (const part of s.message.content) {
+        if (part.type === "text" || part.type === "reasoning") {
+          values.push(part.type, part.text);
+        } else if (part.type === "tool-call") {
+          values.push(part.type, part.argsText, part.result !== undefined);
+        } else {
+          values.push(part.type);
+        }
+      }
+      return values;
+    }),
+  );
+
+  const running = computed(() => activity.value[0] === true);
+  let lastActivity = 0;
+  let lastObservedActivity: readonly unknown[] | undefined;
+  let observing = false;
+  const stalled = shallowRef(false);
+  const now = shallowRef(0);
+
+  useIsomorphicLayoutEffect(() => {
+    return () => {
+      observing = false;
+    };
+  }, []);
+
+  useIsomorphicLayoutEffect(
+    () => {
+      if (!running.value) {
+        observing = false;
+        stalled.value = false;
+        return undefined;
+      }
+
+      // KeepAlive may reconnect descendant activation hooks in reverse order.
+      // Observe activity and arm its timer together, so activation cannot compare
+      // the threshold with a timestamp from before the scope was paused.
+      if (!observing || lastObservedActivity !== activity.value) {
+        lastActivity = Date.now();
+        lastObservedActivity = activity.value;
+        observing = true;
+      }
+
+      let active = true;
+      const stall = () => {
+        if (!active) return;
+        now.value = Date.now();
+        stalled.value = true;
+      };
+      const sinceActivity = Date.now() - lastActivity;
+      if (sinceActivity >= thresholdMs.value) {
+        stall();
+        return undefined;
+      }
+
+      stalled.value = false;
+      const id = setTimeout(stall, thresholdMs.value - sinceActivity);
+      return () => {
+        active = false;
+        clearTimeout(id);
+      };
+    },
+    () => [running.value, activity.value, thresholdMs.value],
+  );
+
+  useIsomorphicLayoutEffect(
+    () => {
+      if (!stalled.value) return undefined;
+      let active = true;
+      const id = setInterval(() => {
+        if (active) now.value = Date.now();
+      }, 1000);
+      return () => {
+        active = false;
+        clearInterval(id);
+      };
+    },
+    () => [stalled.value],
+  );
+
+  return computed(() =>
+    !stalled.value
+      ? { stalled: false, stalledForMs: 0 }
+      : {
+          stalled: true,
+          stalledForMs: Math.max(0, now.value - lastActivity),
+        },
+  );
+}