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

package/src/model-context/makeAssistantVisible.test.tsx

@@ -0,0 +1,460 @@
+// @vitest-environment jsdom
+
+import { within } from "@testing-library/dom";
+import { defineComponent, h, nextTick, shallowRef } from "vue";
+import { useForwardExpose } from "reka-ui";
+import { cleanup, render as mount } from "../tests/vue";
+const render = (node: Parameters<typeof mount>[0]) => {
+  const view = mount(node);
+  return { ...view, ...within(view.container) };
+};
+const act = async (action: () => unknown) => {
+  await action();
+  await nextTick();
+};
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  mergeModelContexts,
+  type ModelContextProvider,
+} from "@ulearning/ai-core";
+import type { Tool } from "@ulearning/ai-stream";
+
+const { registerMock, auiMock } = vi.hoisted(() => {
+  const register = vi.fn((_provider: unknown) => () => {});
+  return {
+    registerMock: register,
+    auiMock: {
+      modelContext: { register },
+    },
+  };
+});
+
+vi.mock("@ulearning/ai-store", async (importOriginal) => ({
+  ...(await importOriginal()),
+  useAui: () => auiMock,
+}));
+
+import { makeAssistantVisible } from "./makeAssistantVisible";
+
+type EditTool = {
+  execute: (args: { editId: string; value: string }) => Promise<unknown>;
+};
+
+type ClickTool = {
+  execute: (args: { clickId: string }) => Promise<unknown>;
+};
+
+type VisibleToolsProvider = {
+  getModelContext: () => {
+    tools: {
+      edit?: EditTool;
+      click?: ClickTool;
+    };
+  };
+};
+
+const ControlledInput = defineComponent({
+  props: ["onChange"],
+  inheritAttrs: false,
+  setup(props, { attrs }) {
+    const value = shallowRef("initial");
+    const { forwardRef } = useForwardExpose();
+    return () =>
+      h("input", {
+        ...attrs,
+        ref: forwardRef,
+        value: value.value,
+        "data-vue-value": value.value,
+        onChange: (event: Event) => {
+          if (event.target instanceof HTMLInputElement)
+            value.value = event.target.value;
+          props.onChange?.(event);
+        },
+      });
+  },
+});
+
+const ControlledTextarea = defineComponent({
+  props: ["onChange"],
+  inheritAttrs: false,
+  setup(props, { attrs }) {
+    const value = shallowRef("initial");
+    const { forwardRef } = useForwardExpose();
+    return () =>
+      h("textarea", {
+        ...attrs,
+        ref: forwardRef,
+        value: value.value,
+        "data-vue-value": value.value,
+        onChange: (event: Event) => {
+          if (event.target instanceof HTMLTextAreaElement)
+            value.value = event.target.value;
+          props.onChange?.(event);
+        },
+      });
+  },
+});
+
+const Button = defineComponent({
+  props: ["onClick"],
+  inheritAttrs: false,
+  setup(props, { attrs, slots }) {
+    const { forwardRef } = useForwardExpose();
+    return () =>
+      h("button", { ...attrs, onClick: props.onClick, ref: forwardRef }, slots);
+  },
+});
+
+const SplitRefButton = defineComponent({
+  props: ["onClick"],
+  inheritAttrs: false,
+  setup(props, { attrs, slots }) {
+    const { forwardRef } = useForwardExpose();
+    return () =>
+      h("div", { ...attrs, onClick: props.onClick }, [
+        h("button", { ref: forwardRef }, slots.default?.()),
+      ]);
+  },
+});
+
+const getRegisteredTools = () => {
+  const provider = registerMock.mock.calls[0]![0] as VisibleToolsProvider;
+  return provider.getModelContext().tools;
+};
+
+const executeTool = (tool: Tool | undefined, args: Record<string, unknown>) => {
+  if (!tool?.execute) throw new Error("Missing executable tool");
+  return Promise.resolve(
+    tool.execute(args, {
+      toolCallId: "test-call",
+      abortSignal: new AbortController().signal,
+      human: async () => {
+        throw new Error("Unexpected human input request");
+      },
+    }),
+  );
+};
+
+const runEditTool = async (
+  element: HTMLInputElement | HTMLTextAreaElement,
+  value: string,
+) => {
+  const editId = element.dataset.editId;
+  if (editId === undefined) throw new Error("Missing edit id");
+
+  const edit = getRegisteredTools().edit;
+  if (!edit) throw new Error("Missing edit tool");
+  const task = edit.execute({
+    editId,
+    value,
+  });
+  await vi.runAllTimersAsync();
+  await task;
+};
+
+const expectDefaultSettleDelay = async (start: () => Promise<unknown>) => {
+  await act(async () => {
+    const settled = vi.fn();
+    const task = start();
+    void task.then(settled);
+
+    await vi.advanceTimersByTimeAsync(1999);
+    expect(settled).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(1);
+    expect(settled).toHaveBeenCalledOnce();
+    await task;
+  });
+};
+
+describe("makeAssistantVisible", () => {
+  beforeEach(() => {
+    registerMock.mockClear();
+    vi.stubGlobal("CSS", { escape: (value: string) => value });
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  it("updates controlled input state through the edit tool", async () => {
+    const EditableInput = makeAssistantVisible(ControlledInput, {
+      editable: true,
+    });
+    const onChange = vi.fn();
+    const input = render(<EditableInput onChange={onChange} />).getByRole(
+      "textbox",
+    );
+
+    await act(async () => {
+      await runEditTool(input as HTMLInputElement, "updated");
+    });
+
+    expect(input).toHaveProperty("value", "updated");
+    expect(input.getAttribute("data-vue-value")).toBe("updated");
+    expect(onChange).toHaveBeenCalledOnce();
+  });
+
+  it("updates controlled textarea state through the edit tool", async () => {
+    const EditableTextarea = makeAssistantVisible(ControlledTextarea, {
+      editable: true,
+    });
+    const onChange = vi.fn();
+    const textarea = render(<EditableTextarea onChange={onChange} />).getByRole(
+      "textbox",
+    );
+
+    await act(async () => {
+      await runEditTool(textarea as HTMLTextAreaElement, "updated");
+    });
+
+    expect(textarea).toHaveProperty("value", "updated");
+    expect(textarea.getAttribute("data-vue-value")).toBe("updated");
+    expect(onChange).toHaveBeenCalledOnce();
+  });
+
+  it("preserves the default action settle delay", async () => {
+    const EditableInput = makeAssistantVisible(ControlledInput, {
+      editable: true,
+    });
+    const input = render(<EditableInput />).getByRole("textbox");
+    const editId = (input as HTMLInputElement).dataset.editId!;
+
+    expect(
+      (input as HTMLInputElement).dataset.actionSettleDelay,
+    ).toBeUndefined();
+
+    await expectDefaultSettleDelay(() =>
+      getRegisteredTools().edit!.execute({ editId, value: "updated" }),
+    );
+  });
+
+  it("uses the default when the rendered settle delay is invalid", async () => {
+    const ClickableButton = makeAssistantVisible(Button, {
+      clickable: true,
+      settleDelayMs: 25,
+    });
+    const button = render(<ClickableButton>Run</ClickableButton>).getByRole(
+      "button",
+    );
+    const clickId = (button as HTMLButtonElement).dataset.clickId!;
+    (button as HTMLButtonElement).dataset.actionSettleDelay = "invalid";
+    await expectDefaultSettleDelay(() =>
+      getRegisteredTools().click!.execute({ clickId }),
+    );
+  });
+
+  it.each(["", "   "])(
+    "uses the default for a blank rendered settle delay of %j",
+    async (renderedDelay) => {
+      const VisibleInput = makeAssistantVisible(ControlledInput, {
+        clickable: true,
+        editable: true,
+        settleDelayMs: 25,
+      });
+      const input = render(<VisibleInput />).getByRole("textbox");
+      const clickId = (input as HTMLInputElement).dataset.clickId!;
+      const editId = (input as HTMLInputElement).dataset.editId!;
+      input.dataset.actionSettleDelay = renderedDelay;
+
+      await expectDefaultSettleDelay(() =>
+        getRegisteredTools().click!.execute({ clickId }),
+      );
+      await expectDefaultSettleDelay(() =>
+        getRegisteredTools().edit!.execute({ editId, value: "updated" }),
+      );
+    },
+  );
+
+  it("uses the configured settle delay for click actions", async () => {
+    const ClickableButton = makeAssistantVisible(Button, {
+      clickable: true,
+      settleDelayMs: 25,
+    });
+    const onClick = vi.fn();
+    const button = render(
+      <ClickableButton onClick={onClick}>Run</ClickableButton>,
+    ).getByRole("button");
+    const clickId = (button as HTMLButtonElement).dataset.clickId!;
+    const settled = vi.fn();
+
+    const task = getRegisteredTools().click!.execute({ clickId });
+    void task.then(settled);
+
+    expect(onClick).toHaveBeenCalledOnce();
+    await vi.advanceTimersByTimeAsync(24);
+    expect(settled).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(1);
+    await task;
+    expect(settled).toHaveBeenCalledOnce();
+  });
+
+  it("uses the action id when the forwarded ref targets a child", async () => {
+    const ClickableButton = makeAssistantVisible(SplitRefButton, {
+      clickable: true,
+      settleDelayMs: 25,
+    });
+    const onClick = vi.fn();
+    const view = render(
+      <ClickableButton data-testid="action" onClick={onClick}>
+        Run
+      </ClickableButton>,
+    );
+    const action = view.getByTestId("action");
+    const clickId = action.dataset.clickId!;
+    const settled = vi.fn();
+
+    const task = getRegisteredTools().click!.execute({ clickId });
+    void task.then(settled);
+
+    expect(onClick).toHaveBeenCalledOnce();
+    await vi.advanceTimersByTimeAsync(24);
+    expect(settled).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(1);
+    await task;
+    expect(settled).toHaveBeenCalledOnce();
+  });
+
+  it("shares tools across wrappers while keeping per-element delays", async () => {
+    const SlowButton = makeAssistantVisible(Button, {
+      clickable: true,
+      editable: true,
+      settleDelayMs: 25,
+    });
+    const ImmediateButton = makeAssistantVisible(Button, {
+      clickable: true,
+      editable: true,
+      settleDelayMs: 0,
+    });
+    const view = render(
+      <>
+        <SlowButton>Slow</SlowButton>
+        <ImmediateButton>Immediate</ImmediateButton>
+      </>,
+    );
+    const providers = registerMock.mock.calls.map(
+      ([provider]) => provider as ModelContextProvider,
+    );
+    const mergedContext = mergeModelContexts(new Set(providers));
+
+    expect(mergedContext.tools?.click).toBe(
+      providers[0]!.getModelContext().tools?.click,
+    );
+    expect(mergedContext.tools?.click).toBe(
+      providers[1]!.getModelContext().tools?.click,
+    );
+    expect(mergedContext.tools?.edit).toBe(
+      providers[0]!.getModelContext().tools?.edit,
+    );
+    expect(mergedContext.tools?.edit).toBe(
+      providers[1]!.getModelContext().tools?.edit,
+    );
+
+    const [slowButton, immediateButton] = view.getAllByRole("button");
+    const click = mergedContext.tools!.click!;
+    const slowTask = executeTool(click, {
+      clickId: (slowButton as HTMLButtonElement).dataset.clickId!,
+    });
+    const immediateTask = executeTool(click, {
+      clickId: (immediateButton as HTMLButtonElement).dataset.clickId!,
+    });
+
+    await immediateTask;
+    let slowSettled = false;
+    void slowTask.then(() => {
+      slowSettled = true;
+    });
+    await vi.advanceTimersByTimeAsync(24);
+    expect(slowSettled).toBe(false);
+    await vi.advanceTimersByTimeAsync(1);
+    await slowTask;
+  });
+
+  it("shares the edit tool across wrappers while keeping per-element delays", async () => {
+    const SlowInput = makeAssistantVisible(ControlledInput, {
+      editable: true,
+      settleDelayMs: 25,
+    });
+    const ImmediateInput = makeAssistantVisible(ControlledInput, {
+      editable: true,
+      settleDelayMs: 0,
+    });
+    const view = render(
+      <>
+        <SlowInput aria-label="Slow" />
+        <ImmediateInput aria-label="Immediate" />
+      </>,
+    );
+    const providers = registerMock.mock.calls.map(
+      ([provider]) => provider as ModelContextProvider,
+    );
+    const mergedContext = mergeModelContexts(new Set(providers));
+
+    expect(mergedContext.tools?.edit).toBe(
+      providers[0]!.getModelContext().tools?.edit,
+    );
+    expect(mergedContext.tools?.edit).toBe(
+      providers[1]!.getModelContext().tools?.edit,
+    );
+
+    const slowInput = view.getByRole("textbox", { name: "Slow" });
+    const immediateInput = view.getByRole("textbox", { name: "Immediate" });
+    const edit = mergedContext.tools!.edit!;
+    const slowTask = executeTool(edit, {
+      editId: (slowInput as HTMLInputElement).dataset.editId!,
+      value: "slow update",
+    });
+    const immediateTask = executeTool(edit, {
+      editId: (immediateInput as HTMLInputElement).dataset.editId!,
+      value: "immediate update",
+    });
+
+    await immediateTask;
+    expect(immediateInput).toHaveProperty("value", "immediate update");
+    let slowSettled = false;
+    void slowTask.then(() => {
+      slowSettled = true;
+    });
+    await vi.advanceTimersByTimeAsync(24);
+    expect(slowSettled).toBe(false);
+
+    await vi.advanceTimersByTimeAsync(1);
+    await slowTask;
+    expect(slowInput).toHaveProperty("value", "slow update");
+  });
+
+  it("allows the action settle delay to be disabled", async () => {
+    const EditableInput = makeAssistantVisible(ControlledInput, {
+      editable: true,
+      settleDelayMs: 0,
+    });
+    const input = render(<EditableInput />).getByRole("textbox");
+    const editId = (input as HTMLInputElement).dataset.editId!;
+    const timersBefore = vi.getTimerCount();
+
+    const task = getRegisteredTools().edit!.execute({
+      editId,
+      value: "updated",
+    });
+
+    expect(vi.getTimerCount()).toBe(timersBefore);
+    await task;
+    expect(input).toHaveProperty("value", "updated");
+  });
+
+  it.each([-1, Number.NaN, Number.POSITIVE_INFINITY, 2_147_483_648])(
+    "rejects an invalid action settle delay of %s",
+    (settleDelayMs) => {
+      expect(() =>
+        makeAssistantVisible(Button, { clickable: true, settleDelayMs }),
+      ).toThrow(
+        new RangeError("settleDelayMs must be between 0 and 2147483647"),
+      );
+    },
+  );
+});

package/src/model-context/makeAssistantVisible.tsx

@@ -0,0 +1,184 @@
+"use client";
+
+import {
+  defineComponent,
+  h,
+  inject,
+  provide,
+  useId,
+  type Component,
+  type FunctionalComponent,
+  type InjectionKey,
+} from "vue";
+import { useAui } from "@ulearning/ai-store";
+import { useIsomorphicLayoutEffect } from "@ulearning/ai-store/internal";
+import { useForwardExpose } from "reka-ui";
+import { tool } from "@ulearning/ai-core";
+
+const DEFAULT_ACTION_SETTLE_DELAY_MS = 2000;
+const MAX_ACTION_SETTLE_DELAY_MS = 2_147_483_647;
+
+const waitForSettle = async (settleDelayMs: number) => {
+  const delay =
+    Number.isFinite(settleDelayMs) &&
+    settleDelayMs >= 0 &&
+    settleDelayMs <= MAX_ACTION_SETTLE_DELAY_MS
+      ? settleDelayMs
+      : DEFAULT_ACTION_SETTLE_DELAY_MS;
+  if (delay === 0) return;
+  await new Promise<void>((resolve) => setTimeout(resolve, delay));
+};
+
+const readActionSettleDelay = (element: HTMLElement) => {
+  const value = element.dataset.actionSettleDelay;
+  return value === undefined || value.trim() === ""
+    ? DEFAULT_ACTION_SETTLE_DELAY_MS
+    : Number(value);
+};
+
+const click = tool({
+  parameters: {
+    type: "object",
+    properties: {
+      clickId: {
+        type: "string",
+      },
+    },
+    required: ["clickId"],
+  },
+  execute: async ({ clickId }: { clickId: string }) => {
+    const escapedClickId = CSS.escape(clickId);
+    const el = document.querySelector(`[data-click-id='${escapedClickId}']`);
+    if (el instanceof HTMLElement) {
+      el.click();
+      await waitForSettle(readActionSettleDelay(el));
+      return {};
+    } else {
+      return "Element not found";
+    }
+  },
+});
+
+const setNativeValue = (
+  element: HTMLInputElement | HTMLTextAreaElement,
+  value: string,
+) => {
+  const prototype =
+    element instanceof HTMLInputElement
+      ? HTMLInputElement.prototype
+      : HTMLTextAreaElement.prototype;
+  const setter = Object.getOwnPropertyDescriptor(prototype, "value")?.set;
+
+  if (setter) {
+    setter.call(element, value);
+  } else {
+    element.value = value;
+  }
+};
+
+const edit = tool({
+  parameters: {
+    type: "object",
+    properties: {
+      editId: {
+        type: "string",
+      },
+      value: {
+        type: "string",
+      },
+    },
+    required: ["editId", "value"],
+  },
+  execute: async ({ editId, value }: { editId: string; value: string }) => {
+    const escapedEditId = CSS.escape(editId);
+    const el = document.querySelector(`[data-edit-id='${escapedEditId}']`);
+    if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+      setNativeValue(el, value);
+      el.dispatchEvent(new Event("input", { bubbles: true }));
+      el.dispatchEvent(new Event("change", { bubbles: true }));
+      await waitForSettle(readActionSettleDelay(el));
+      return {};
+    } else {
+      return "Element not found";
+    }
+  },
+});
+
+const ReadableContext: InjectionKey<boolean> = Symbol("AssistantVisible");
+type ComponentProps<T extends Component> = T extends new (...args: never[]) => {
+  $props: infer P extends object;
+}
+  ? P
+  : T extends FunctionalComponent<infer P extends object>
+    ? P
+    : Record<string, unknown>;
+
+export const makeAssistantVisible = <T extends Component>(
+  Component: T,
+  config?: {
+    clickable?: boolean | undefined;
+    editable?: boolean | undefined;
+    settleDelayMs?: number | undefined;
+  },
+) => {
+  const settleDelayMs = config?.settleDelayMs ?? DEFAULT_ACTION_SETTLE_DELAY_MS;
+  if (
+    !Number.isFinite(settleDelayMs) ||
+    settleDelayMs < 0 ||
+    settleDelayMs > MAX_ACTION_SETTLE_DELAY_MS
+  ) {
+    throw new RangeError(
+      `settleDelayMs must be between 0 and ${MAX_ACTION_SETTLE_DELAY_MS}`,
+    );
+  }
+
+  const WrappedComponent: Component = Component;
+  return defineComponent(
+    function AssistantVisible(props: ComponentProps<T>, { attrs, slots }) {
+      const isNestedReadable = inject(ReadableContext, false);
+      provide(ReadableContext, true);
+      const clickId = useId();
+      const { forwardRef, currentElement } = useForwardExpose();
+      const aui = useAui();
+      const { clickable, editable } = config ?? {};
+      useIsomorphicLayoutEffect(
+        () =>
+          aui.modelContext.register({
+            getModelContext: () => ({
+              tools: {
+                ...(clickable ? { click } : {}),
+                ...(editable ? { edit } : {}),
+              },
+              system:
+                !isNestedReadable && currentElement.value instanceof HTMLElement
+                  ? currentElement.value.outerHTML
+                  : undefined,
+            }),
+          }),
+        () => [isNestedReadable, aui, clickable, editable],
+      );
+      return () =>
+        h(
+          WrappedComponent,
+          {
+            ...attrs,
+            ...props,
+            ...(clickable ? { "data-click-id": clickId } : {}),
+            ...(editable ? { "data-edit-id": clickId } : {}),
+            ...(config?.settleDelayMs !== undefined && (clickable || editable)
+              ? { "data-action-settle-delay": settleDelayMs }
+              : {}),
+            ref: forwardRef,
+          },
+          slots,
+        );
+    },
+    {
+      name: Component.name ?? "AssistantVisible",
+      inheritAttrs: false,
+      props: [],
+    },
+  );
+};
+
+export default makeAssistantVisible;

package/src/model-context/registry/SPEC_ModelContextRegistry.md

@@ -0,0 +1,40 @@
+# ModelContextRegistry
+
+An imperative API for registering tools and instructions to a model context provider.
+
+```typescript
+const registry = new ModelContextRegistry();
+
+const handle = registry.addTool({
+  toolName: "search",
+  description: "Search the web",
+  parameters: z.object({ query: z.string() }),
+  execute: async (args) => {
+    return { results: ["..."] };
+  },
+});
+```
+
+## API
+
+- addTool(tool: Tool & { toolName: string }): ModelContextRegistryToolHandle
+- addInstruction(instruction: string): ModelContextRegistryInstructionHandle
+- addProvider(provider: ModelContextProvider): ModelContextRegistryProviderHandle
+
+## ModelContextRegistryToolHandle
+
+- update(tool: Tool & { toolName: string }): void;
+- remove(): void;
+
+## ModelContextRegistryInstructionHandle
+
+- update(instruction: string): void;
+- remove(): void;
+
+## ModelContextRegistryProviderHandle
+
+- remove(): void;
+
+## ModelContextProvider
+
+The registry is a ModelContextProvider.

package/src/primitives/actionBar/ActionBarCopy.test.tsx

@@ -0,0 +1,28 @@
+// @vitest-environment jsdom
+
+import { h } from "vue";
+import { afterEach, expect, it, vi } from "vitest";
+import { cleanup } from "../../tests/vue";
+import { mountMessageAction } from "../../tests/messageAction";
+import { ActionBarPrimitiveCopy } from "./ActionBarCopy";
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+
+it("copies the scoped message through the browser clipboard", async () => {
+  const writeText = vi.fn().mockResolvedValue(undefined);
+  vi.stubGlobal("navigator", { ...navigator, clipboard: { writeText } });
+  const view = mountMessageAction(
+    () => h(ActionBarPrimitiveCopy, null, { default: () => "Copy message" }),
+    { content: [{ type: "text", text: "Message to copy." }] },
+  );
+  const button = view.container.querySelector("button")!;
+  button.click();
+
+  expect(writeText).toHaveBeenCalledExactlyOnceWith("Message to copy.");
+  await vi.waitFor(() =>
+    expect(button.getAttribute("data-copied")).toBe("true"),
+  );
+});