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

package/src/context/vue/utils/createContextStoreHook.ts

@@ -0,0 +1,93 @@
+import {
+  computed,
+  shallowReadonly,
+  shallowRef,
+  watchEffect,
+  type ShallowRef,
+} from "vue";
+import { useIsomorphicLayoutEffect } from "@ulearning/ai-store/internal";
+import type { ReadonlyStore } from "../../ReadonlyStore";
+
+/** Vue selectors retain external snapshot identity and subscribe only while active. */
+export function createContextStoreHook<T, K extends keyof T & string>(
+  contextHook: (options?: { optional?: boolean }) => T | null,
+  contextKey: K,
+) {
+  type StateType = T[K] extends ReadonlyStore<infer S> ? S : never;
+  function useStoreStoreHook(): ReadonlyStore<StateType>;
+  function useStoreStoreHook(options: {
+    optional: true;
+  }): ReadonlyStore<StateType> | null;
+  function useStoreStoreHook(options?: {
+    optional?: boolean;
+  }): ReadonlyStore<StateType> | null {
+    const context = contextHook(options);
+    return context ? (context[contextKey] as ReadonlyStore<StateType>) : null;
+  }
+
+  function useStoreHook(): Readonly<ShallowRef<StateType>>;
+  function useStoreHook<S>(
+    selector: (state: StateType) => S,
+  ): Readonly<ShallowRef<S>>;
+  function useStoreHook(options: {
+    optional: true;
+  }): Readonly<ShallowRef<StateType | null>>;
+  function useStoreHook<S>(options: {
+    optional: true;
+    selector: (state: StateType) => S;
+  }): Readonly<ShallowRef<S | null>>;
+  function useStoreHook<S>(
+    param?:
+      | ((state: StateType) => S)
+      | { optional?: boolean; selector?: (state: StateType) => S },
+  ): Readonly<ShallowRef<S | StateType | null>> {
+    const optional = typeof param === "object" && !!param.optional;
+    const selector = typeof param === "function" ? param : param?.selector;
+    const context = contextHook({ optional });
+    const store = context
+      ? (context[contextKey] as ReadonlyStore<StateType>)
+      : null;
+    const snapshot = shallowRef(store?.getState() ?? null);
+    const failure = shallowRef<{ error: unknown }>();
+    watchEffect(
+      () => {
+        if (failure.value) throw failure.value.error;
+      },
+      { flush: "sync" },
+    );
+    useIsomorphicLayoutEffect(() => {
+      if (!store) return;
+      let active = true;
+      const refresh = () => {
+        if (!active) return;
+        try {
+          snapshot.value = store.getState();
+          failure.value = undefined;
+        } catch (error) {
+          failure.value = { error };
+        }
+      };
+      const release = store.subscribe(refresh);
+      refresh();
+      return () => {
+        active = false;
+        release();
+      };
+    }, []);
+    return shallowReadonly(
+      computed(() =>
+        snapshot.value === null
+          ? null
+          : selector
+            ? selector(snapshot.value)
+            : snapshot.value,
+      ),
+    );
+  }
+  return {
+    [contextKey]: useStoreHook,
+    [`${contextKey}Store`]: useStoreStoreHook,
+  } as { [P in K]: typeof useStoreHook } & {
+    [P in `${K}Store`]: typeof useStoreStoreHook;
+  };
+}

package/src/devtools/DevToolsHooks.test.ts

@@ -0,0 +1,40 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { DevToolsHooks, DevToolsProviderApi } from "./DevToolsHooks";
+
+describe("DevToolsHooks", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("notifies every listener when one throws", () => {
+    const error = new Error("listener failed");
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const laterListener = vi.fn();
+    const unsubscribeThrowing = DevToolsHooks.subscribe(() => {
+      throw error;
+    });
+    const unsubscribeLater = DevToolsHooks.subscribe(laterListener);
+    let unregister = () => {};
+
+    try {
+      unregister = DevToolsProviderApi.register({});
+      const apiId = [...DevToolsHooks.getApis().keys()].at(-1);
+      expect(apiId).toBeDefined();
+
+      DevToolsHooks.clearEventLogs(apiId!);
+
+      expect(laterListener).toHaveBeenCalledTimes(2);
+      expect(consoleError).toHaveBeenCalledTimes(2);
+      expect(consoleError).toHaveBeenCalledWith(
+        "[assistant-ui] DevTools listener threw an error",
+        error,
+      );
+    } finally {
+      unsubscribeThrowing();
+      unsubscribeLater();
+      unregister();
+    }
+  });
+});

package/src/devtools/DevToolsHooks.ts

@@ -0,0 +1,142 @@
+import type { Unsubscribe } from "@ulearning/ai-core";
+import { notifyEventListeners } from "@ulearning/ai-core/internal";
+import type { AssistantClient } from "@ulearning/ai-store";
+
+export interface EventLog {
+  time: Date;
+  event: string;
+  data: unknown;
+}
+
+interface DevToolsApiEntry {
+  api: Partial<AssistantClient>;
+  logs: EventLog[];
+}
+
+interface DevToolsHook {
+  apis: Map<number, DevToolsApiEntry>;
+  nextId: number;
+  listeners: Set<(apiId: number) => void>;
+}
+
+declare global {
+  interface Window {
+    __ASSISTANT_UI_DEVTOOLS_HOOK__?: DevToolsHook;
+  }
+}
+
+let cachedHook: DevToolsHook | undefined;
+
+const getHook = (): DevToolsHook => {
+  if (cachedHook) {
+    return cachedHook;
+  }
+
+  const createHook = (): DevToolsHook => ({
+    apis: new Map(),
+    nextId: 0,
+    listeners: new Set(),
+  });
+
+  if (typeof window === "undefined") {
+    cachedHook = createHook();
+    return cachedHook;
+  }
+
+  const existingHook = window.__ASSISTANT_UI_DEVTOOLS_HOOK__;
+  if (existingHook) {
+    cachedHook = existingHook;
+    return existingHook;
+  }
+
+  const newHook = createHook();
+  window.__ASSISTANT_UI_DEVTOOLS_HOOK__ = newHook;
+  cachedHook = newHook;
+  return newHook;
+};
+
+const notifyListeners = (apiId: number): void => {
+  notifyEventListeners(getHook().listeners, apiId, "DevTools");
+};
+
+export class DevToolsHooks {
+  static subscribe(listener: () => void): Unsubscribe {
+    const hook = getHook();
+    hook.listeners.add(listener);
+    return () => {
+      hook.listeners.delete(listener);
+    };
+  }
+
+  static clearEventLogs(apiId: number): void {
+    const hook = getHook();
+    const entry = hook.apis.get(apiId);
+    if (!entry) return;
+
+    entry.logs = [];
+    notifyListeners(apiId);
+  }
+
+  static getApis(): Map<number, DevToolsApiEntry> {
+    return getHook().apis;
+  }
+}
+
+export class DevToolsProviderApi {
+  private static readonly MAX_EVENT_LOGS_PER_API = 200;
+
+  static register(aui: Partial<AssistantClient>): Unsubscribe {
+    const hook = getHook();
+
+    for (const entry of hook.apis.values()) {
+      if (entry.api === aui) {
+        return () => {};
+      }
+    }
+
+    const apiId = hook.nextId++;
+    const entry: DevToolsApiEntry = {
+      api: aui,
+      logs: [],
+    };
+
+    const eventUnsubscribe = aui.on?.("*", (e) => {
+      const entry = hook.apis.get(apiId);
+      if (!entry) return;
+
+      entry.logs.push({
+        time: new Date(),
+        event: e.event,
+        data: e.payload,
+      });
+
+      if (entry.logs.length > DevToolsProviderApi.MAX_EVENT_LOGS_PER_API) {
+        entry.logs = entry.logs.slice(
+          -DevToolsProviderApi.MAX_EVENT_LOGS_PER_API,
+        );
+      }
+
+      notifyListeners(apiId);
+    });
+
+    const stateUnsubscribe = aui.subscribe?.(() => {
+      notifyListeners(apiId);
+    });
+
+    hook.apis.set(apiId, entry);
+    notifyListeners(apiId);
+
+    return () => {
+      const hook = getHook();
+      const entry = hook.apis.get(apiId);
+      if (!entry) return;
+
+      eventUnsubscribe?.();
+      stateUnsubscribe?.();
+
+      hook.apis.delete(apiId);
+
+      notifyListeners(apiId);
+    };
+  }
+}

package/src/hooks/message-readers.test.ts

@@ -0,0 +1,128 @@
+// @vitest-environment jsdom
+import { defineComponent, h, nextTick, shallowRef } from "vue";
+import { afterEach, expect, it } from "vitest";
+import { flushTapSync } from "@ulearning/ai-tap";
+import {
+  AssistantRuntimeProvider,
+  ThreadPrimitiveMessages,
+  useExternalStoreRuntime,
+} from "@ulearning/ai-core/vue";
+import type {
+  MessageTiming,
+  QuoteInfo,
+  ThreadMessageLike,
+} from "@ulearning/ai-core";
+import { cleanup, render } from "../tests/vue";
+import { useMessageQuote } from "./useMessageQuote";
+import { useMessageTiming } from "./useMessageTiming";
+
+afterEach(cleanup);
+const timing = (streamStartTime: number): MessageTiming => ({
+  streamStartTime,
+  totalChunks: 1,
+  toolCallCount: 0,
+});
+const mountReaders = (
+  quote: QuoteInfo | undefined,
+  messageTiming: MessageTiming | undefined,
+) => {
+  const message = shallowRef<ThreadMessageLike>({
+    id: "message",
+    role: "assistant",
+    content: [],
+    createdAt: new Date(0),
+    metadata: { custom: { quote }, timing: messageTiming },
+  });
+  let quoteRef!: ReturnType<typeof useMessageQuote>;
+  let timingRef!: ReturnType<typeof useMessageTiming>;
+  let setups = 0;
+  const Message = defineComponent({
+    setup() {
+      setups++;
+      quoteRef = useMessageQuote();
+      timingRef = useMessageTiming();
+      return () =>
+        h(
+          "p",
+          `${quoteRef.value?.text ?? "none"}:${timingRef.value?.streamStartTime ?? "none"}`,
+        );
+    },
+  });
+  const view = render(
+    h(
+      defineComponent({
+        setup() {
+          const runtime = useExternalStoreRuntime(() => ({
+            messages: [message.value],
+            convertMessage: (input: ThreadMessageLike) => input,
+            onNew: async () => {},
+          }));
+          return () =>
+            h(
+              AssistantRuntimeProvider,
+              { runtime },
+              {
+                default: () =>
+                  h(ThreadPrimitiveMessages, { components: { Message } }),
+              },
+            );
+        },
+      }),
+    ),
+  );
+  return {
+    ...view,
+    message,
+    get quote() {
+      return quoteRef;
+    },
+    get timing() {
+      return timingRef;
+    },
+    get setups() {
+      return setups;
+    },
+    async update(next: ThreadMessageLike) {
+      flushTapSync(() => {
+        message.value = next;
+      });
+      await nextTick();
+    },
+  };
+};
+it("keeps shallow quote/timing identities and updates metadata without recreating setup", async () => {
+  const quote = { messageId: "original", text: "selected" };
+  const firstTiming = timing(1000);
+  const view = mountReaders(quote, firstTiming);
+  expect(view.quote.value).toBe(quote);
+  expect(view.timing.value).toBe(firstTiming);
+  expect(view.container.textContent).toBe("selected:1000");
+  const replacement = { messageId: "other", text: "changed" };
+  const nextTiming = timing(2000);
+  await view.update({
+    ...view.message.value,
+    metadata: { custom: { quote: replacement }, timing: nextTiming },
+  });
+  expect(view.quote.value).toBe(replacement);
+  expect(view.timing.value).toBe(nextTiming);
+  expect(view.container.textContent).toBe("changed:2000");
+  expect(view.setups).toBe(1);
+});
+it("clears optional metadata and rejects timing from a user message", async () => {
+  const view = mountReaders({ messageId: "source", text: "quote" }, timing(1));
+  await view.update({ ...view.message.value, role: "user" });
+  expect(view.timing.value).toBeUndefined();
+  expect(view.quote.value?.text).toBe("quote");
+  await view.update({ ...view.message.value, metadata: { custom: {} } });
+  expect(view.quote.value).toBeUndefined();
+  expect(view.container.textContent).toBe("none:none");
+});
+it("isolates separate message owners", async () => {
+  const first = mountReaders({ messageId: "a", text: "one" }, timing(1));
+  const second = mountReaders({ messageId: "b", text: "two" }, timing(2));
+  const stable = second.timing.value;
+  await first.update({ ...first.message.value, metadata: { custom: {} } });
+  expect(second.quote.value?.text).toBe("two");
+  expect(second.timing.value).toBe(stable);
+  expect(second.container.textContent).toBe("two:2");
+});

package/src/hooks/useMessageQuote.ts

@@ -0,0 +1,25 @@
+"use client";
+
+import type { QuoteInfo } from "@ulearning/ai-core";
+import { getMessageQuote } from "@ulearning/ai-core/vue";
+import { useAuiState } from "@ulearning/ai-store";
+import type { ShallowRef } from "vue";
+
+/**
+ * Returns a readonly shallow ref to the current message's quote, if any.
+ *
+ * Reads from `message.metadata.custom.quote`.
+ *
+ * @example
+ * ```tsx
+ * function useQuoteBlock() {
+ *   const quote = useMessageQuote();
+ *   return () => quote.value && <blockquote>{quote.value.text}</blockquote>;
+ * }
+ * ```
+ */
+export const useMessageQuote = (): Readonly<
+  ShallowRef<QuoteInfo | undefined>
+> => {
+  return useAuiState(getMessageQuote);
+};

package/src/hooks/useMessageTiming.ts

@@ -0,0 +1,26 @@
+"use client";
+
+import { useAuiState } from "@ulearning/ai-store";
+import type { MessageTiming } from "@ulearning/ai-core";
+import type { ShallowRef } from "vue";
+
+/**
+ * Returns a readonly shallow ref to timing for the current assistant message.
+ *
+ * Reads from `message.metadata.timing`.
+ *
+ * @example
+ * ```tsx
+ * function useMessageStats() {
+ *   const timing = useMessageTiming();
+ *   return () => timing.value && <span>{timing.value.tokensPerSecond?.toFixed(1)} tok/s</span>;
+ * }
+ * ```
+ */
+export const useMessageTiming = (): Readonly<
+  ShallowRef<MessageTiming | undefined>
+> => {
+  return useAuiState((s) =>
+    s.message.role === "assistant" ? s.message.metadata?.timing : undefined,
+  );
+};

package/src/hooks/useToolCallElapsed.test.tsx

@@ -0,0 +1,172 @@
+// @vitest-environment jsdom
+import {
+  createSSRApp,
+  defineComponent,
+  h,
+  KeepAlive,
+  nextTick,
+  shallowRef,
+} from "vue";
+import { renderToString } from "@vue/server-renderer";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resource } from "@ulearning/ai-tap";
+import { AuiConfig, AuiProvider, type ClientOutput } from "@ulearning/ai-store";
+import type { MessagePartState } from "@ulearning/ai-core";
+import { cleanup, render, visibleHTML } from "../tests/vue";
+import { useToolCallElapsed } from "./useToolCallElapsed";
+
+const tool = (
+  startedAt = 9000,
+): Extract<MessagePartState, { type: "tool-call" }> => ({
+  type: "tool-call",
+  toolCallId: "call",
+  toolName: "task",
+  args: {},
+  argsText: "{}",
+  status: { type: "running" },
+  timing: { startedAt },
+});
+const Part = resource(function usePart({
+  state,
+}: {
+  state: MessagePartState;
+}): ClientOutput<"part"> {
+  return {
+    getState: () => state,
+    addToolResult: () => {},
+    resumeToolCall: () => {},
+    respondToToolApproval: async () => {},
+  };
+});
+const fixture = (initial: MessagePartState = tool()) => {
+  const state = shallowRef<MessagePartState>(initial);
+  let elapsed!: ReturnType<typeof useToolCallElapsed>;
+  const Probe = defineComponent({
+    setup() {
+      elapsed = useToolCallElapsed();
+      return () => h("span", String(elapsed.value ?? "none"));
+    },
+  });
+  const Owner = defineComponent({
+    setup: () => () =>
+      h(
+        AuiProvider,
+        { config: AuiConfig({ part: Part({ state: state.value }) }) },
+        { default: () => h(Probe) },
+      ),
+  });
+  return {
+    state,
+    Owner,
+    get elapsed() {
+      return elapsed;
+    },
+  };
+};
+
+describe("useToolCallElapsed", () => {
+  afterEach(() => {
+    cleanup();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("does not read the wall clock during server render", async () => {
+    const { Owner } = fixture();
+    const nowSpy = vi.spyOn(Date, "now");
+    const errors = vi.spyOn(console, "error").mockImplementation(() => {});
+    const container = document.createElement("div");
+    container.innerHTML = await renderToString(createSSRApp(Owner));
+    expect(visibleHTML(container)).toBe("<span>none</span>");
+    expect(nowSpy).not.toHaveBeenCalled();
+    expect(errors).not.toHaveBeenCalled();
+  });
+
+  it("ticks while running and uses the recorded completion without continuing to poll", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(10000);
+    const input = fixture();
+    const view = render(h(input.Owner));
+    await nextTick();
+    expect(view.container.textContent).toBe("1000");
+    expect(vi.getTimerCount()).toBe(1);
+    vi.advanceTimersByTime(1000);
+    await nextTick();
+    expect(view.container.textContent).toBe("2000");
+    input.state.value = {
+      ...tool(),
+      status: { type: "complete" },
+      timing: { startedAt: 9000, completedAt: 11500 },
+    };
+    await nextTick();
+    expect(view.container.textContent).toBe("2500");
+    expect(vi.getTimerCount()).toBe(0);
+    vi.advanceTimersByTime(5000);
+    await nextTick();
+    expect(view.container.textContent).toBe("2500");
+  });
+
+  it("handles absent scopes, non-tool parts, unknown completion and clock skew", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(10000);
+    const missing = render(
+      h(
+        defineComponent({
+          setup() {
+            const elapsed = useToolCallElapsed();
+            return () => h("b", String(elapsed.value ?? "none"));
+          },
+        }),
+      ),
+    );
+    expect(missing.container.textContent).toBe("none");
+    expect(vi.getTimerCount()).toBe(0);
+    const input = fixture(tool(20000));
+    const view = render(h(input.Owner));
+    await nextTick();
+    expect(view.container.textContent).toBe("0");
+    input.state.value = { ...tool(), status: { type: "complete" } };
+    await nextTick();
+    expect(view.container.textContent).toBe("none");
+    expect(vi.getTimerCount()).toBe(0);
+    input.state.value = {
+      type: "text",
+      text: "not a tool",
+      status: { type: "complete" },
+    };
+    await nextTick();
+    expect(view.container.textContent).toBe("none");
+  });
+
+  it("stops on deactivation and disposal and catches the clock up on activation", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(10000);
+    const shown = shallowRef(true);
+    const input = fixture();
+    const view = render(
+      h(
+        defineComponent({
+          setup: () => () =>
+            h(KeepAlive, null, {
+              default: () => (shown.value ? h(input.Owner) : null),
+            }),
+        }),
+      ),
+    );
+    await nextTick();
+    expect(input.elapsed.value).toBe(1000);
+    shown.value = false;
+    await nextTick();
+    expect(vi.getTimerCount()).toBe(0);
+    vi.advanceTimersByTime(5000);
+    expect(input.elapsed.value).toBe(1000);
+    shown.value = true;
+    await nextTick();
+    expect(input.elapsed.value).toBe(6000);
+    expect(vi.getTimerCount()).toBe(1);
+    view.unmount();
+    expect(vi.getTimerCount()).toBe(0);
+    vi.advanceTimersByTime(5000);
+    expect(input.elapsed.value).toBe(6000);
+  });
+});

package/src/hooks/useToolCallElapsed.ts

@@ -0,0 +1,65 @@
+"use client";
+
+import { computed, shallowRef, type ComputedRef } from "vue";
+import { useAuiState } from "@ulearning/ai-store";
+import { useIsomorphicLayoutEffect } from "@ulearning/ai-store/internal";
+
+/**
+ * Returns a computed ref to elapsed wall-clock milliseconds for the current
+ * tool call, ticking once per second while the call runs.
+ *
+ * Reads `part.timing`. Returns `undefined` when the part is not a tool call,
+ * carries no timing, ended without a recorded completion (the duration is
+ * unknown), or when no message part scope is available (so kit components
+ * stay renderable standalone, e.g. in docs previews). A running call also
+ * returns `undefined` until the component mounts, so a server render never
+ * reads the clock.
+ *
+ * @example
+ * ```tsx
+ * function useToolDuration() {
+ *   const elapsedMs = useToolCallElapsed();
+ *   return () => elapsedMs.value === undefined ? null : <span>{(elapsedMs.value / 1000).toFixed(1)}s</span>;
+ * }
+ * ```
+ */
+export const useToolCallElapsed = (): ComputedRef<number | undefined> => {
+  const timing = useAuiState((s) => {
+    const part = s.optional.part;
+    return part?.type === "tool-call" ? part.timing : undefined;
+  });
+  const partRunning = useAuiState((s) => {
+    const part = s.optional.part;
+    return part?.type === "tool-call" && part.status.type === "running";
+  });
+  const running = computed(
+    () =>
+      timing.value !== undefined &&
+      timing.value.completedAt === undefined &&
+      partRunning.value,
+  );
+  const now = shallowRef<number>();
+
+  useIsomorphicLayoutEffect(
+    () => {
+      if (!running.value) return undefined;
+      // The clock is read only after mount so a prerender never reads it; the
+      // layout effect still catches the elapsed value up before the first paint.
+      now.value = Date.now();
+      const id = setInterval(() => {
+        now.value = Date.now();
+      }, 1000);
+      return () => clearInterval(id);
+    },
+    () => [running.value],
+  );
+
+  return computed(() => {
+    const value = timing.value;
+    if (value === undefined) return undefined;
+    if (value.completedAt !== undefined)
+      return Math.max(0, value.completedAt - value.startedAt);
+    if (!running.value || now.value === undefined) return undefined;
+    return Math.max(0, now.value - value.startedAt);
+  });
+};