@assistant-ui/core 0.3.19 → 0.3.21

package/src/runtime/api/message-part-runtime.test.ts

@@ -0,0 +1,215 @@
+import { describe, expect, it, vi } from "vitest";
+import type { ThreadRuntimeCore } from "../interfaces/thread-runtime-core";
+import type { MessageStateBinding } from "./bindings";
+import type { MessagePartState } from "./message-part-runtime";
+import { MessagePartRuntimeImpl } from "./message-part-runtime";
+import type { ThreadRuntimeCoreBinding } from "./thread-runtime";
+
+const threadPath = {
+  ref: "threads.main",
+  threadSelector: { type: "main" as const },
+};
+
+const messagePath = {
+  ...threadPath,
+  ref: "threads.main.messages[0]",
+  messageSelector: { type: "index" as const, index: 0 },
+};
+
+const partPath = {
+  ...messagePath,
+  ref: "threads.main.messages[0].content[0]",
+  messagePartSelector: { type: "index" as const, index: 0 },
+};
+
+const toolPart: MessagePartState = {
+  type: "tool-call",
+  toolCallId: "call-1",
+  toolName: "weather",
+  args: {},
+  argsText: "{}",
+  status: { type: "requires-action", reason: "tool-calls" },
+};
+
+const textPart: MessagePartState = {
+  type: "text",
+  text: "hello",
+  status: { type: "complete" },
+};
+
+const message = {
+  id: "message-1",
+  role: "assistant" as const,
+  createdAt: new Date(0),
+  content: [toolPart],
+  status: { type: "requires-action" as const, reason: "tool-calls" as const },
+  metadata: {
+    unstable_state: null,
+    unstable_annotations: [],
+    unstable_data: [],
+    steps: [],
+    custom: {},
+  },
+  parentId: null,
+  index: 0,
+  isLast: true,
+  branchNumber: 1,
+  branchCount: 1,
+  speech: undefined,
+};
+
+const createRuntime = ({
+  part = toolPart,
+  core,
+}: {
+  part?: MessagePartState;
+  core: ThreadRuntimeCore;
+}) => {
+  const contentBinding = {
+    path: partPath,
+    getState: () => part,
+    subscribe: () => () => {},
+  };
+  const messageBinding: MessageStateBinding = {
+    path: messagePath,
+    getState: () => message,
+    subscribe: () => () => {},
+  };
+  const threadBinding: ThreadRuntimeCoreBinding = {
+    path: threadPath,
+    getState: () => core,
+    subscribe: () => () => {},
+    outerSubscribe: () => () => {},
+  };
+  return new MessagePartRuntimeImpl(
+    contentBinding,
+    messageBinding,
+    threadBinding,
+  );
+};
+
+describe("MessagePartRuntime interaction recording", () => {
+  it("rejects invalid inputs without throwing synchronously", async () => {
+    const core = {
+      unstable_recordToolInteraction: vi.fn(),
+    } as unknown as ThreadRuntimeCore;
+    const runtime = createRuntime({ core });
+
+    const recording = runtime.unstable_recordInteraction({
+      type: "action",
+      payload: "not an object",
+    });
+
+    await expect(recording).rejects.toThrow(
+      "An action interaction payload must be a JSON object.",
+    );
+    expect(core.unstable_recordToolInteraction).not.toHaveBeenCalled();
+  });
+
+  it("rejects recording on non-tool parts", async () => {
+    const core = {
+      unstable_recordToolInteraction: vi.fn(),
+    } as unknown as ThreadRuntimeCore;
+    const runtime = createRuntime({ core, part: textPart });
+
+    await expect(
+      runtime.unstable_recordInteraction({ type: "action", payload: {} }),
+    ).rejects.toThrow("Tried to record interaction on non-tool message part");
+  });
+
+  it("rejects when the core cannot record tool interactions", async () => {
+    const runtime = createRuntime({ core: {} as ThreadRuntimeCore });
+
+    await expect(
+      runtime.unstable_recordInteraction({ type: "action", payload: {} }),
+    ).rejects.toThrow("Runtime does not support recording tool interactions.");
+  });
+
+  it("delegates stamped interactions with the message and tool call ids", async () => {
+    const recordInteraction = vi.fn(async () => {});
+    const core = {
+      unstable_recordToolInteraction: recordInteraction,
+    } as unknown as ThreadRuntimeCore;
+    const runtime = createRuntime({ core });
+
+    await runtime.unstable_recordInteraction({
+      type: "action",
+      payload: { action: "toggle" },
+    });
+
+    expect(recordInteraction).toHaveBeenCalledExactlyOnceWith({
+      messageId: "message-1",
+      toolCallId: "call-1",
+      interaction: {
+        type: "action",
+        payload: { action: "toggle" },
+        occurredAt: expect.any(Number),
+      },
+    });
+  });
+});
+
+describe("MessagePartRuntime resumeToolCall", () => {
+  it("records the accepted human response", () => {
+    const resumeToolCall = vi.fn();
+    const recordInteraction = vi.fn(async () => {});
+    const runtime = createRuntime({
+      core: {
+        resumeToolCall,
+        unstable_recordToolInteraction: recordInteraction,
+      } as unknown as ThreadRuntimeCore,
+    });
+    const payload = { answer: "yes" };
+
+    runtime.resumeToolCall(payload);
+
+    expect(resumeToolCall).toHaveBeenCalledExactlyOnceWith({
+      toolCallId: "call-1",
+      payload,
+    });
+    expect(recordInteraction).toHaveBeenCalledExactlyOnceWith({
+      messageId: "message-1",
+      toolCallId: "call-1",
+      interaction: {
+        type: "human-response",
+        payload,
+        occurredAt: expect.any(Number),
+      },
+    });
+    expect(resumeToolCall.mock.invocationCallOrder[0]).toBeLessThan(
+      recordInteraction.mock.invocationCallOrder[0]!,
+    );
+  });
+
+  it("does not record a human response when resuming throws", () => {
+    const error = new Error("resume failed");
+    const recordInteraction = vi.fn(async () => {});
+    const runtime = createRuntime({
+      core: {
+        resumeToolCall: () => {
+          throw error;
+        },
+        unstable_recordToolInteraction: recordInteraction,
+      } as unknown as ThreadRuntimeCore,
+    });
+
+    expect(() => runtime.resumeToolCall({ answer: "yes" })).toThrow(error);
+    expect(recordInteraction).not.toHaveBeenCalled();
+  });
+
+  it("keeps an accepted resume successful when recording fails", async () => {
+    const resumeToolCall = vi.fn();
+    const runtime = createRuntime({
+      core: {
+        resumeToolCall,
+        unstable_recordToolInteraction: vi.fn(async () => {
+          throw new Error("recording failed");
+        }),
+      } as unknown as ThreadRuntimeCore,
+    });
+
+    expect(() => runtime.resumeToolCall({ answer: "yes" })).not.toThrow();
+    await Promise.resolve();
+    expect(resumeToolCall).toHaveBeenCalledOnce();
+  });
+});

package/src/runtime/api/message-part-runtime.ts

@@ -3,8 +3,10 @@ import type {
   ThreadUserMessagePart,
   ToolApprovalResponse,
   ToolCallMessagePartStatus,
+  Unstable_ToolInteractionInput,
 } from "../../types/message";
 import { resolveToolApprovalResponse } from "../utils/resolveToolApprovalResponse";
+import { createToolInteraction } from "../utils/tool-interactions";
 import type { Unsubscribe } from "../../types/unsubscribe";
 import type { MessagePartStatus } from "../../types/message";
 import type { SubscribableWithState } from "../../subscribable/subscribable";
@@ -29,6 +31,9 @@ export type MessagePartRuntime = {
   addToolResult(result: any | ToolResponse<any>): void;
   resumeToolCall(payload: unknown): void;
   respondToToolApproval(response: ToolApprovalResponse): Promise<void>;
+  unstable_recordInteraction?: (
+    input: Unstable_ToolInteractionInput,
+  ) => Promise<void>;
 
   readonly path: MessagePartRuntimePath;
   getState(): MessagePartState;
@@ -59,6 +64,8 @@ export class MessagePartRuntimeImpl implements MessagePartRuntime {
     this.addToolResult = this.addToolResult.bind(this);
     this.resumeToolCall = this.resumeToolCall.bind(this);
     this.respondToToolApproval = this.respondToToolApproval.bind(this);
+    this.unstable_recordInteraction =
+      this.unstable_recordInteraction.bind(this);
     this.getState = this.getState.bind(this);
     this.subscribe = this.subscribe.bind(this);
   }
@@ -92,8 +99,11 @@ export class MessagePartRuntimeImpl implements MessagePartRuntime {
       toolName,
       toolCallId,
       result: response.result,
-      artifact: response.artifact,
       isError: response.isError,
+      ...(response.artifact !== undefined && { artifact: response.artifact }),
+      ...(response.modelContent !== undefined && {
+        modelContent: response.modelContent,
+      }),
     });
   }
 
@@ -111,6 +121,10 @@ export class MessagePartRuntimeImpl implements MessagePartRuntime {
       toolCallId,
       payload,
     });
+    void this.unstable_recordInteraction({
+      type: "human-response",
+      payload,
+    }).catch(() => {});
   }
 
   public respondToToolApproval(response: ToolApprovalResponse): Promise<void> {
@@ -138,6 +152,35 @@ export class MessagePartRuntimeImpl implements MessagePartRuntime {
       );
   }
 
+  public async unstable_recordInteraction(
+    input: Unstable_ToolInteractionInput,
+  ): Promise<void> {
+    const state = this.contentBinding.getState();
+    if (!state) throw new Error("Message part is not available");
+
+    if (state.type !== "tool-call")
+      throw new Error("Tried to record interaction on non-tool message part");
+
+    if (!this.messageApi)
+      throw new Error(
+        "Message API is not available. This is likely a bug in assistant-ui.",
+      );
+    if (!this.threadApi) throw new Error("Thread API is not available");
+
+    const message = this.messageApi.getState();
+    if (!message) throw new Error("Message is not available");
+
+    const core = this.threadApi.getState();
+    if (!core.unstable_recordToolInteraction)
+      throw new Error("Runtime does not support recording tool interactions.");
+
+    await core.unstable_recordToolInteraction({
+      messageId: message.id,
+      toolCallId: state.toolCallId,
+      interaction: createToolInteraction(input),
+    });
+  }
+
   public subscribe(callback: () => void) {
     return this.contentBinding.subscribe(callback);
   }

package/src/runtime/api/message-runtime.test.ts

@@ -7,7 +7,7 @@ import type {
 import type { ThreadRuntimeCoreBinding } from "./thread-runtime";
 import {
   MessageRuntimeImpl,
-  type MessageState,
+  type MessageRuntimeState,
   type MessageStateBinding,
 } from "./message-runtime";
 import { toMessagePartStatus } from "../../utils/normalizePartStatus";
@@ -28,7 +28,7 @@ const attachment: CompleteAttachment = {
   status: { type: "complete" },
 };
 
-const message: MessageState = {
+const message: MessageRuntimeState = {
   id: "message-1",
   role: "assistant",
   createdAt: new Date(0),
@@ -226,6 +226,116 @@ describe("toMessagePartStatus", () => {
     });
   });
 
+  it.each([
+    ["approval", { approval: { id: "approval-1" } }],
+    [
+      "interrupt",
+      { interrupt: { type: "human" as const, payload: { question: "?" } } },
+    ],
+  ] as const)(
+    "keeps a tool call with a pending %s actionable beside its result",
+    (_label, action) => {
+      const message = createAssistantMessage(
+        [
+          {
+            type: "tool-call",
+            toolCallId: "call-1",
+            toolName: "weather",
+            args: {},
+            argsText: "{}",
+            result: "partial output",
+            ...action,
+          },
+        ],
+        { type: "requires-action", reason: "interrupt" },
+      );
+
+      expect(toMessagePartStatus(message, 0, message.content[0]!)).toEqual({
+        type: "requires-action",
+        reason: "interrupt",
+      });
+    },
+  );
+
+  it.each([
+    ["a decision", { approved: true }],
+    ["a rejection", { approved: false }],
+    ["a resolution", { resolution: "cancelled" as const }],
+  ])(
+    "treats a tool call whose approval carries %s as complete",
+    (_label, settled) => {
+      const message = createAssistantMessage(
+        [
+          {
+            type: "tool-call",
+            toolCallId: "call-1",
+            toolName: "weather",
+            args: {},
+            argsText: "{}",
+            result: "sunny",
+            approval: { id: "approval-1", ...settled },
+          },
+        ],
+        { type: "requires-action", reason: "interrupt" },
+      );
+
+      expect(toMessagePartStatus(message, 0, message.content[0]!)).toEqual({
+        type: "complete",
+      });
+    },
+  );
+
+  it.each([
+    ["running", { type: "running" as const }],
+    [
+      "cancelled",
+      { type: "incomplete" as const, reason: "cancelled" as const },
+    ],
+  ])(
+    "keeps a tool call with a preliminary result on the %s message status",
+    (_label, status) => {
+      const message = createAssistantMessage(
+        [
+          {
+            type: "tool-call",
+            toolCallId: "call-1",
+            toolName: "bash",
+            args: {},
+            argsText: "{}",
+            result: "partial output",
+            isPreliminary: true,
+          },
+        ],
+        status,
+      );
+
+      expect(toMessagePartStatus(message, 0, message.content[0]!)).toEqual(
+        status,
+      );
+    },
+  );
+
+  it("settles a tool call whose result is no longer preliminary", () => {
+    const message = createAssistantMessage(
+      [
+        {
+          type: "tool-call",
+          toolCallId: "call-1",
+          toolName: "bash",
+          args: {},
+          argsText: "{}",
+          result: "final output",
+          isPreliminary: false,
+        },
+      ],
+      { type: "running" },
+    );
+
+    expect(toMessagePartStatus(message, 0, message.content[0]!)).toEqual({
+      type: "complete",
+    });
+  });
+
   it("normalizes supplied upstream statuses", () => {
     const upstreamComplete = {
       type: "text",

package/src/runtime/api/message-runtime.ts

@@ -12,7 +12,7 @@ import {
 } from "../../subscribable/subscribable";
 import {
   type AttachmentRuntime,
-  type AttachmentState,
+  type AttachmentRuntimeState,
   MessageAttachmentRuntimeImpl,
 } from "./attachment-runtime";
 import {
@@ -29,7 +29,7 @@ import type { ThreadRuntimeCoreBinding } from "./thread-runtime";
 import type { MessageStateBinding } from "./bindings";
 
 const getMessagePartState = (
-  message: MessageState,
+  message: MessageRuntimeState,
   partIndex: number,
 ): MessagePartState | SKIP_UPDATE => {
   const part = message.content[partIndex];
@@ -46,7 +46,7 @@ const getMessagePartState = (
   });
 };
 
-export type MessageState = ThreadMessage & {
+export type MessageRuntimeState = ThreadMessage & {
   readonly parentId: string | null;
   /** The position of this message in the thread (0 for first message) */
   readonly index: number;
@@ -61,6 +61,11 @@ export type MessageState = ThreadMessage & {
   readonly speech: SpeechState | undefined;
 };
 
+/**
+ * @deprecated Use `MessageRuntimeState`. From `@assistant-ui/react` 0.16, `MessageState` names the message state read through `useAuiState`.
+ */
+export type MessageState = MessageRuntimeState;
+
 export type { MessageStateBinding } from "./bindings";
 
 type ReloadConfig = {
@@ -72,7 +77,7 @@ export type MessageRuntime = {
 
   readonly composer: EditComposerRuntime;
 
-  getState(): MessageState;
+  getState(): MessageRuntimeState;
   delete(): void | Promise<void>;
   reload(config?: ReloadConfig): void;
   /**
@@ -83,7 +88,13 @@ export type MessageRuntime = {
    * @deprecated This API is still under active development and might change without notice.
    */
   stopSpeaking(): void;
-  submitFeedback({ type }: { type: "positive" | "negative" }): void;
+  submitFeedback({
+    type,
+    comment,
+  }: {
+    type: "positive" | "negative";
+    comment?: string;
+  }): void;
   switchToBranch({
     position,
     branchId,
@@ -197,11 +208,18 @@ export class MessageRuntimeImpl implements MessageRuntime {
     }
   }
 
-  public submitFeedback({ type }: { type: "positive" | "negative" }) {
+  public submitFeedback({
+    type,
+    comment,
+  }: {
+    type: "positive" | "negative";
+    comment?: string;
+  }) {
     const state = this._core.getState();
     this._threadBinding.getState().submitFeedback({
       messageId: state.id,
       type,
+      ...(comment !== undefined ? { comment } : undefined),
     });
   }
 
@@ -300,7 +318,7 @@ export class MessageRuntimeImpl implements MessageRuntime {
           return {
             ...attachment,
             source: "message",
-          } satisfies AttachmentState & { source: "message" };
+          } satisfies AttachmentRuntimeState & { source: "message" };
         },
         subscribe: (callback) => this._core.subscribe(callback),
       }),

package/src/runtime/api/thread-list-item-runtime.ts

@@ -25,10 +25,10 @@ export type ThreadListItemEventCallback<E extends ThreadListItemEventType> = (
   payload: ThreadListItemEventPayload[E],
 ) => void;
 
-import type { ThreadListItemState } from "./bindings";
+import type { ThreadListItemRuntimeState } from "./bindings";
 import type { ThreadListItemStatus } from "../interfaces/thread-list-runtime-core";
 
-export type { ThreadListItemState, ThreadListItemStatus };
+export type { ThreadListItemRuntimeState, ThreadListItemStatus };
 
 export type ThreadListItemGenerateTitleOptions = {
   /** Marks a generation started by the automatic title trigger. */
@@ -37,7 +37,7 @@ export type ThreadListItemGenerateTitleOptions = {
 
 export type ThreadListItemRuntime = {
   readonly path: ThreadListItemRuntimePath;
-  getState(): ThreadListItemState;
+  getState(): ThreadListItemRuntimeState;
 
   initialize(): Promise<{ remoteId: string; externalId: string | undefined }>;
   generateTitle(options?: ThreadListItemGenerateTitleOptions): Promise<void>;
@@ -62,7 +62,7 @@ export type ThreadListItemRuntime = {
 };
 
 export type ThreadListItemStateBinding = SubscribableWithState<
-  ThreadListItemState,
+  ThreadListItemRuntimeState,
   ThreadListItemRuntimePath
 >;
 
@@ -98,7 +98,7 @@ export class ThreadListItemRuntimeImpl implements ThreadListItemRuntime {
     this.detach = this.detach.bind(this);
   }
 
-  public getState(): ThreadListItemState {
+  public getState(): ThreadListItemRuntimeState {
     return this._core.getState();
   }
 

package/src/runtime/api/thread-list-runtime.ts

@@ -14,7 +14,7 @@ import type {
 import {
   type ThreadListItemRuntime,
   ThreadListItemRuntimeImpl,
-  type ThreadListItemState,
+  type ThreadListItemRuntimeState,
   type ThreadListItemStateBinding,
 } from "./thread-list-item-runtime";
 import {
@@ -40,7 +40,7 @@ export type ThreadListState = {
   readonly threadItems: Readonly<
     Record<
       string,
-      Omit<ThreadListItemState, "isMain" | "threadId" | "isRunning">
+      Omit<ThreadListItemRuntimeState, "isMain" | "threadId" | "isRunning">
     >
   >;
 };
@@ -110,7 +110,7 @@ const getThreadListState = (
 const getThreadListItemState = (
   threadList: ThreadListRuntimeCore,
   threadId: string | undefined,
-): ThreadListItemState | SKIP_UPDATE => {
+): ThreadListItemRuntimeState | SKIP_UPDATE => {
   if (threadId === undefined) return SKIP_UPDATE;
 
   const threadData = threadList.getItemById(threadId);

package/src/runtime/api/thread-runtime.test.ts

@@ -1,7 +1,10 @@
 import { describe, expect, it, vi } from "vitest";
+import { z } from "zod";
 import { LocalRuntimeCore } from "../../runtimes/local/local-runtime-core";
 import { ExternalStoreRuntimeCore } from "../../runtimes/external-store/external-store-runtime-core";
 import { ReadonlyThreadRuntimeCore } from "../../runtimes/readonly/ReadonlyThreadRuntimeCore";
+import { EMPTY_THREAD_CORE } from "../../runtimes/remote-thread-list/empty-thread-core";
+import type { ThreadRuntimeCore } from "../interfaces/thread-runtime-core";
 import { AssistantRuntimeImpl } from "./assistant-runtime";
 import {
   ThreadRuntimeImpl,
@@ -134,3 +137,59 @@ describe("ThreadRuntime state subscriptions", () => {
     expect(itemSubscriptions).toBe(2);
   });
 });
+
+describe("ThreadRuntime model context", () => {
+  it("notifies modelContextUpdate subscribers when the bound core is replaced", () => {
+    const attached = new ExternalStoreRuntimeCore({
+      messages: [],
+      onNew: async () => {},
+    });
+    attached.registerModelContextProvider({
+      getModelContext: () => ({
+        tools: { search_docs: { parameters: z.object({}) } },
+      }),
+    });
+
+    let core: ThreadRuntimeCore = EMPTY_THREAD_CORE;
+    let notifyBinding!: () => void;
+    const path = {
+      ref: "test.thread",
+      threadSelector: { type: "main" as const },
+    };
+    const runtime = new ThreadRuntimeImpl(
+      {
+        path,
+        getState: () => core,
+        subscribe: (callback) => {
+          notifyBinding = callback;
+          return () => {};
+        },
+        outerSubscribe: () => () => {},
+      } satisfies ThreadRuntimeCoreBinding,
+      {
+        path,
+        getState: () => ({
+          id: "test",
+          remoteId: undefined,
+          externalId: undefined,
+          isMain: true,
+          isRunning: false,
+          status: "regular",
+          title: undefined,
+        }),
+        subscribe: () => () => {},
+      } satisfies ThreadListItemRuntimeBinding,
+    );
+
+    const reads: string[][] = [];
+    runtime.unstable_on("modelContextUpdate", () => {
+      reads.push(Object.keys(runtime.getModelContext().tools ?? {}));
+    });
+    expect(runtime.getModelContext().tools).toBeUndefined();
+
+    core = attached.threads.getMainThreadRuntimeCore();
+    notifyBinding();
+
+    expect(reads).toEqual([["search_docs"]]);
+  });
+});