@assistant-ui/core 0.2.11 → 0.2.14

package/src/runtimes/local/local-thread-runtime-core.test.ts

@@ -0,0 +1,311 @@
+import { describe, expect, it } from "vitest";
+import { LocalRuntimeCore } from "./local-runtime-core";
+import type {
+  ChatModelAdapter,
+  ChatModelRunOptions,
+  ChatModelRunResult,
+} from "../../runtime/utils/chat-model-adapter";
+import type { AppendMessage } from "../../types/message";
+
+const flush = () => new Promise((resolve) => setTimeout(resolve, 10));
+
+const createThread = (adapter: ChatModelAdapter) => {
+  const core = new LocalRuntimeCore(
+    {
+      adapters: { chatModel: adapter },
+      unstable_humanToolNames: ["send_email"],
+    },
+    undefined,
+  );
+  return core.threads.getMainThreadRuntimeCore();
+};
+
+const userMessage = (text: string): AppendMessage => ({
+  parentId: null,
+  sourceId: null,
+  runConfig: {},
+  role: "user",
+  content: [{ type: "text", text }],
+  attachments: [],
+  metadata: { custom: {} },
+  createdAt: new Date(),
+});
+
+const toolCallPart = (toolName: string, approval?: { id: string }) => ({
+  type: "tool-call" as const,
+  toolCallId: `call-${toolName}`,
+  toolName,
+  args: {},
+  argsText: "{}",
+  ...(approval !== undefined ? { approval } : {}),
+});
+
+const toolCallResult = (
+  toolName: string,
+  approval?: { id: string },
+): ChatModelRunResult => ({
+  content: [toolCallPart(toolName, approval)],
+  status: { type: "requires-action", reason: "tool-calls" },
+});
+
+const createApprovalThread = (firstResult: ChatModelRunResult) => {
+  const runs: ChatModelRunOptions[] = [];
+  const thread = createThread({
+    async run(options) {
+      runs.push(options);
+      if (runs.length === 1) return firstResult;
+      return { content: [{ type: "text", text: "done" }] };
+    },
+  });
+  return { thread, runs };
+};
+
+describe("LocalThreadRuntimeCore human-in-the-loop tools", () => {
+  it("pauses on requires-action while a listed tool call has no result", async () => {
+    const { thread, runs } = createApprovalThread(toolCallResult("send_email"));
+
+    await thread.append(userMessage("send an email"));
+    await flush();
+
+    expect(runs).toHaveLength(1);
+    expect(thread.messages.at(-1)?.status?.type).toBe("requires-action");
+  });
+
+  it("does not hold the run for unlisted tool calls", async () => {
+    const { thread, runs } = createApprovalThread(
+      toolCallResult("lookup_weather"),
+    );
+
+    await thread.append(userMessage("what is the weather"));
+    await flush();
+
+    expect(runs).toHaveLength(2);
+    expect(thread.messages.at(-1)?.status?.type).toBe("complete");
+  });
+
+  it("resumes via addToolResult and exposes the result to the adapter", async () => {
+    const { thread, runs } = createApprovalThread(toolCallResult("send_email"));
+
+    await thread.append(userMessage("send an email"));
+    await flush();
+
+    const assistantMessage = thread.messages.at(-1)!;
+    thread.addToolResult({
+      messageId: assistantMessage.id,
+      toolCallId: "call-send_email",
+      toolName: "send_email",
+      result: { approved: true },
+      isError: false,
+    });
+    await flush();
+
+    expect(runs).toHaveLength(2);
+    const resumed = runs[1]!;
+    expect(resumed.messages.at(-1)?.role).toBe("user");
+    const toolCall = resumed
+      .unstable_getMessage()
+      .content.find((part) => part.type === "tool-call");
+    expect(toolCall?.result).toEqual({ approved: true });
+
+    const finalMessage = thread.messages.at(-1)!;
+    expect(finalMessage.status?.type).toBe("complete");
+    expect(finalMessage.content.map((part) => part.type)).toEqual([
+      "tool-call",
+      "text",
+    ]);
+  });
+});
+
+describe("LocalThreadRuntimeCore tool approvals", () => {
+  it("pauses the run while an approval is pending, even for unlisted tools", async () => {
+    const { thread, runs } = createApprovalThread(
+      toolCallResult("deploy", { id: "a1" }),
+    );
+
+    await thread.append(userMessage("deploy the app"));
+    await flush();
+
+    expect(runs).toHaveLength(1);
+    expect(thread.messages.at(-1)?.status?.type).toBe("requires-action");
+  });
+
+  it("records an approval and resumes, exempting the gated tool from the human tool result requirement", async () => {
+    const { thread, runs } = createApprovalThread(
+      toolCallResult("send_email", { id: "a1" }),
+    );
+
+    await thread.append(userMessage("send an email"));
+    await flush();
+
+    thread.respondToToolApproval({ approvalId: "a1", approved: true });
+    await flush();
+
+    expect(runs).toHaveLength(2);
+    const toolCall = runs[1]!
+      .unstable_getMessage()
+      .content.find((part) => part.type === "tool-call");
+    expect(toolCall?.approval).toEqual({ id: "a1", approved: true });
+    expect(toolCall?.result).toBeUndefined();
+    expect(thread.messages.at(-1)?.status?.type).toBe("complete");
+  });
+
+  it("continues multi-step turns after an approval resume", async () => {
+    const runs: ChatModelRunOptions[] = [];
+    const thread = createThread({
+      async run(options) {
+        runs.push(options);
+        if (runs.length === 1) return toolCallResult("deploy", { id: "a1" });
+        if (runs.length === 2) return toolCallResult("lookup_weather");
+        return { content: [{ type: "text", text: "done" }] };
+      },
+    });
+
+    await thread.append(userMessage("deploy the app"));
+    await flush();
+
+    thread.respondToToolApproval({ approvalId: "a1", approved: true });
+    await flush();
+
+    expect(runs).toHaveLength(3);
+    expect(thread.messages.at(-1)?.status?.type).toBe("complete");
+  });
+
+  it("resumes when a result is added to an approval-gated tool call", async () => {
+    const { thread, runs } = createApprovalThread(
+      toolCallResult("deploy", { id: "a1" }),
+    );
+
+    await thread.append(userMessage("deploy the app"));
+    await flush();
+
+    thread.addToolResult({
+      messageId: thread.messages.at(-1)!.id,
+      toolCallId: "call-deploy",
+      toolName: "deploy",
+      result: "done manually",
+      isError: false,
+    });
+    await flush();
+
+    expect(runs).toHaveLength(2);
+    expect(thread.messages.at(-1)?.status?.type).toBe("complete");
+  });
+
+  it("records a denial and synthesizes an error result", async () => {
+    const { thread, runs } = createApprovalThread(
+      toolCallResult("deploy", { id: "a1" }),
+    );
+
+    await thread.append(userMessage("deploy the app"));
+    await flush();
+
+    thread.respondToToolApproval({
+      approvalId: "a1",
+      approved: false,
+      reason: "not today",
+    });
+    await flush();
+
+    expect(runs).toHaveLength(2);
+    const toolCall = thread.messages
+      .at(-1)!
+      .content.find((part) => part.type === "tool-call");
+    expect(toolCall?.approval).toEqual({
+      id: "a1",
+      approved: false,
+      reason: "not today",
+    });
+    expect(toolCall?.result).toEqual({ error: "not today" });
+    expect(toolCall?.isError).toBe(true);
+  });
+
+  it("synthesizes a default denial reason", async () => {
+    const { thread } = createApprovalThread(
+      toolCallResult("deploy", { id: "a1" }),
+    );
+
+    await thread.append(userMessage("deploy the app"));
+    await flush();
+
+    thread.respondToToolApproval({ approvalId: "a1", approved: false });
+    await flush();
+
+    const toolCall = thread.messages
+      .at(-1)!
+      .content.find((part) => part.type === "tool-call");
+    expect(toolCall?.result).toEqual({ error: "Tool approval denied" });
+  });
+
+  it("waits until every pending approval is decided before resuming", async () => {
+    const { thread, runs } = createApprovalThread({
+      content: [
+        toolCallPart("deploy", { id: "a1" }),
+        toolCallPart("send_invoice", { id: "a2" }),
+      ],
+      status: { type: "requires-action", reason: "tool-calls" },
+    });
+
+    await thread.append(userMessage("deploy and bill"));
+    await flush();
+
+    thread.respondToToolApproval({ approvalId: "a1", approved: true });
+    await flush();
+    expect(runs).toHaveLength(1);
+
+    expect(() =>
+      thread.respondToToolApproval({ approvalId: "a1", approved: false }),
+    ).toThrowError(/already decided/);
+
+    thread.respondToToolApproval({ approvalId: "a2", approved: false });
+    await flush();
+    expect(runs).toHaveLength(2);
+  });
+
+  it("throws while the run is still in flight, even if the message already reads requires-action", async () => {
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => (release = resolve));
+    const runs: ChatModelRunOptions[] = [];
+    const thread = createThread({
+      async *run(options) {
+        runs.push(options);
+        if (runs.length === 1) {
+          yield toolCallResult("deploy", { id: "a1" });
+          await gate;
+          return;
+        }
+        yield { content: [{ type: "text", text: "done" }] };
+      },
+    });
+
+    const appendPromise = thread.append(userMessage("deploy the app"));
+    await flush();
+
+    expect(thread.messages.at(-1)?.status?.type).toBe("requires-action");
+    expect(() =>
+      thread.respondToToolApproval({ approvalId: "a1", approved: true }),
+    ).toThrowError(/run is in progress/);
+
+    release();
+    await appendPromise;
+
+    thread.respondToToolApproval({ approvalId: "a1", approved: true });
+    await flush();
+
+    expect(runs).toHaveLength(2);
+    expect(thread.messages.at(-1)?.status?.type).toBe("complete");
+  });
+
+  it("throws for unknown approvals and unsupported tool call resumption", async () => {
+    const { thread } = createApprovalThread(toolCallResult("send_email"));
+
+    await thread.append(userMessage("send an email"));
+    await flush();
+
+    expect(() =>
+      thread.respondToToolApproval({ approvalId: "nope", approved: true }),
+    ).toThrowError(/non-existing tool approval/);
+    expect(() =>
+      thread.resumeToolCall({ toolCallId: "call-send_email", payload: {} }),
+    ).toThrowError(/unstable_humanToolNames/);
+  });
+});

package/src/runtimes/local/local-thread-runtime-core.ts

@@ -49,6 +49,7 @@ export class LocalThreadRuntimeCore
     switchToBranch: true,
     switchBranchDuringRun: true,
     edit: true,
+    delete: false,
     reload: true,
     cancel: true,
     unstable_copy: true,
@@ -150,6 +151,12 @@ export class LocalThreadRuntimeCore
       hasUpdates = true;
     }
 
+    const canDelete = options.adapters?.history?.delete !== undefined;
+    if (this.capabilities.delete !== canDelete) {
+      this.capabilities.delete = canDelete;
+      hasUpdates = true;
+    }
+
     const canQueue = options.unstable_enableMessageQueue === true;
     if (canQueue && !this._queue) {
       this._queue = createMessageQueue({
@@ -275,6 +282,25 @@ export class LocalThreadRuntimeCore
     }
   }
 
+  public async deleteMessage(messageId: string): Promise<void> {
+    const adapter = this._options.adapters.history;
+    if (!adapter?.delete)
+      throw new Error("Runtime does not support deleting messages.");
+
+    const messages = this.repository.getMessages();
+    const messageIndex = messages.findIndex((m) => m.id === messageId);
+    if (messageIndex === -1) throw new Error("Message not found.");
+
+    const message = messages[messageIndex]!;
+    const parentId = messages[messageIndex - 1]?.id ?? null;
+    const items = [{ parentId, message }];
+
+    await adapter.delete(items);
+
+    this.repository.deleteMessage(messageId);
+    this._notifySubscribers();
+  }
+
   public resumeRun({ stream, ...startConfig }: ResumeRunConfig): Promise<void> {
     if (!stream)
       throw new Error("You must pass a stream parameter to resume runs.");
@@ -297,7 +323,7 @@ export class LocalThreadRuntimeCore
 
     // add assistant message
     const id = generateId();
-    let message: ThreadAssistantMessage = {
+    const message: ThreadAssistantMessage = {
       id,
       role: "assistant",
       status: { type: "running" },
@@ -312,6 +338,15 @@ export class LocalThreadRuntimeCore
       createdAt: new Date(),
     };
 
+    return this._runLoop(parentId, message, runConfig, runCallback);
+  }
+
+  private async _runLoop(
+    parentId: string | null,
+    message: ThreadAssistantMessage,
+    runConfig: RunConfig | undefined,
+    runCallback?: ChatModelAdapter["run"],
+  ): Promise<void> {
     this._notifyEventSubscribers("runStart", {});
 
     try {
@@ -592,22 +627,84 @@ export class LocalThreadRuntimeCore
       content: newContent,
     };
     this.repository.addOrUpdateMessage(parentId, message);
+    this._notifySubscribers();
 
+    // a result may arrive mid-run or on a non-head message; the resume
+    // intentionally aborts any in-flight run, unlike respondToToolApproval
     if (
       added &&
       shouldContinue(message, this._options.unstable_humanToolNames)
     ) {
-      this.performRoundtrip(parentId, message, this._lastRunConfig).catch(
-        () => {},
-      );
+      this._runLoop(parentId, message, this._lastRunConfig).catch(() => {});
     }
   }
 
   public resumeToolCall(_options: ResumeToolCallOptions) {
-    throw new Error("Local runtime does not support resuming tool calls.");
+    throw new Error(
+      "Local runtime does not support resuming tool calls. For human-in-the-loop tools, list the tool in unstable_humanToolNames and complete the call with addToolResult.",
+    );
   }
 
-  public respondToToolApproval(_options: RespondToToolApprovalOptions) {
-    throw new Error("Local runtime does not support tool approvals.");
+  public respondToToolApproval({
+    approvalId,
+    approved,
+    reason,
+  }: RespondToToolApprovalOptions) {
+    let message = this.repository
+      .getMessages()
+      .findLast(
+        (m): m is ThreadAssistantMessage =>
+          m.role === "assistant" &&
+          m.content.some(
+            (c) => c.type === "tool-call" && c.approval?.id === approvalId,
+          ),
+      );
+
+    if (!message)
+      throw new Error("Tried to respond to a non-existing tool approval");
+
+    if (this.abortController !== null)
+      throw new Error(
+        "Tried to respond to a tool approval while a run is in progress",
+      );
+
+    if (message.status?.type !== "requires-action")
+      throw new Error(
+        "Tried to respond to a tool approval on a message whose status is not requires-action",
+      );
+
+    let recorded = false;
+    const newContent = message.content.map((c) => {
+      if (c.type !== "tool-call" || c.approval?.id !== approvalId) return c;
+      if (c.approval.approved !== undefined) return c;
+      recorded = true;
+      const approval = {
+        ...c.approval,
+        approved,
+        ...(reason != null && { reason }),
+      };
+      if (approved) return { ...c, approval };
+      return {
+        ...c,
+        approval,
+        result: { error: reason || "Tool approval denied" },
+        isError: true,
+      };
+    });
+
+    if (!recorded)
+      throw new Error("Tried to respond to an already decided tool approval");
+
+    message = { ...message, content: newContent };
+    const { parentId } = this.repository.getMessage(message.id);
+    this.repository.addOrUpdateMessage(parentId, message);
+    this._notifySubscribers();
+
+    if (
+      this.repository.headId === message.id &&
+      shouldContinue(message, this._options.unstable_humanToolNames)
+    ) {
+      this._runLoop(parentId, message, this._lastRunConfig).catch(() => {});
+    }
   }
 }

package/src/runtimes/local/should-continue.ts

@@ -4,23 +4,33 @@ export const shouldContinue = (
   result: ThreadAssistantMessage,
   humanToolNames: string[] | undefined,
 ) => {
+  if (
+    result.status?.type !== "requires-action" ||
+    result.status.reason !== "tool-calls"
+  )
+    return false;
+
+  const hasPendingApproval = result.content.some(
+    (c) =>
+      c.type === "tool-call" &&
+      c.result === undefined &&
+      c.approval !== undefined &&
+      c.approval.approved === undefined,
+  );
+  if (hasPendingApproval) return false;
+
   // TODO legacy behavior -- make specifying human tool names required
   if (humanToolNames === undefined) {
-    return (
-      result.status?.type === "requires-action" &&
-      result.status.reason === "tool-calls" &&
-      result.content.every((c) => c.type !== "tool-call" || !!c.result)
+    return result.content.every(
+      (c) => c.type !== "tool-call" || !!c.result || c.approval !== undefined,
     );
   }
 
-  return (
-    result.status?.type === "requires-action" &&
-    result.status.reason === "tool-calls" &&
-    result.content.every(
-      (c) =>
-        c.type !== "tool-call" ||
-        !!c.result ||
-        !humanToolNames.includes(c.toolName),
-    )
+  return result.content.every(
+    (c) =>
+      c.type !== "tool-call" ||
+      !!c.result ||
+      c.approval !== undefined ||
+      !humanToolNames.includes(c.toolName),
   );
 };

package/src/runtimes/readonly/ReadonlyThreadRuntimeCore.ts

@@ -47,6 +47,10 @@ export class ReadonlyThreadRuntimeCore
     throw READONLY_THREAD_ERROR;
   }
 
+  deleteMessage(): void {
+    throw READONLY_THREAD_ERROR;
+  }
+
   startRun(): void {
     throw READONLY_THREAD_ERROR;
   }
@@ -202,6 +206,7 @@ export class ReadonlyThreadRuntimeCore
     switchToBranch: false,
     switchBranchDuringRun: false,
     edit: false,
+    delete: false,
     reload: false,
     cancel: false,
     unstable_copy: false,

package/src/runtimes/remote-thread-list/empty-thread-core.ts

@@ -20,6 +20,10 @@ export const EMPTY_THREAD_CORE: ThreadRuntimeCore = {
     throw EMPTY_THREAD_ERROR;
   },
 
+  deleteMessage() {
+    throw EMPTY_THREAD_ERROR;
+  },
+
   startRun() {
     throw EMPTY_THREAD_ERROR;
   },
@@ -183,6 +187,7 @@ export const EMPTY_THREAD_CORE: ThreadRuntimeCore = {
     switchToBranch: false,
     switchBranchDuringRun: false,
     edit: false,
+    delete: false,
     reload: false,
     cancel: false,
     unstable_copy: false,

package/src/runtimes/remote-thread-list/remote-thread-state.ts

@@ -28,6 +28,7 @@ export type RemoteThreadData =
       readonly externalId: string | undefined;
       readonly status: "regular" | "archived";
       readonly title?: string | undefined;
+      readonly lastMessageAt?: Date | undefined;
       readonly custom?: Record<string, unknown> | undefined;
     };
 
@@ -75,6 +76,7 @@ export const classifyThreads = (
       externalId: thread.externalId,
       status: thread.status,
       title: thread.title,
+      lastMessageAt: thread.lastMessageAt,
       custom: thread.custom,
       initializeTask: Promise.resolve({
         remoteId: thread.remoteId,

package/src/runtimes/remote-thread-list/types.ts

@@ -13,6 +13,7 @@ export type RemoteThreadMetadata = {
   readonly remoteId: string;
   readonly externalId?: string | undefined;
   readonly title?: string | undefined;
+  readonly lastMessageAt?: Date | undefined;
   readonly custom?: Record<string, unknown> | undefined;
 };
 

package/src/store/clients/chain-of-thought-client.ts

@@ -12,13 +12,13 @@ const COMPLETE_STATUS: MessagePartStatus = Object.freeze({
   type: "complete",
 });
 
-export const ChainOfThoughtClient = resource(function ChainOfThoughtClient({
+const useChainOfThoughtClient = ({
   parts,
   getMessagePart,
 }: {
   parts: readonly ChainOfThoughtPart[];
   getMessagePart: (selector: { index: number }) => PartMethods;
-}): ClientOutput<"chainOfThought"> {
+}): ClientOutput<"chainOfThought"> => {
   const [collapsed, setCollapsed] = useState(true);
 
   const status = useMemo(() => {
@@ -36,4 +36,6 @@ export const ChainOfThoughtClient = resource(function ChainOfThoughtClient({
     setCollapsed,
     part: getMessagePart,
   };
-});
+};
+
+export const ChainOfThoughtClient = resource(useChainOfThoughtClient);

package/src/store/clients/model-context-client.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { createResourceRoot } from "@assistant-ui/tap";
+import { createTapRoot, useResource } from "@assistant-ui/tap";
 import type { Tool } from "assistant-stream";
 import { ModelContext } from "./model-context-client";
 import type {
@@ -18,9 +18,10 @@ const toolFixture = (): Tool<any, any> =>
   ({ description: "", parameters: {} as any }) as unknown as Tool<any, any>;
 
 const render = () => {
-  const root = createResourceRoot();
-  const sub = root.render(ModelContext());
-  return { sub, unmount: () => root.unmount() };
+  const root = createTapRoot(function Root() {
+    return useResource(ModelContext());
+  });
+  return { sub: root, unmount: () => root.unmount() };
 };
 
 describe("ModelContext", () => {

package/src/store/clients/model-context-client.ts

@@ -29,25 +29,25 @@ const deriveState = (
   return { modelName, toolNames };
 };
 
-export const ModelContext = resource(
-  function ModelContext(): ClientOutput<"modelContext"> {
-    const composite = useMemo(() => new CompositeContextProvider(), []);
-    const [state, setState] = useState<ModelContextState>(() =>
-      deriveState(composite, INITIAL_STATE),
-    );
-
-    useEffect(() => {
+const useModelContext = (): ClientOutput<"modelContext"> => {
+  const composite = useMemo(() => new CompositeContextProvider(), []);
+  const [state, setState] = useState<ModelContextState>(() =>
+    deriveState(composite, INITIAL_STATE),
+  );
+
+  useEffect(() => {
+    setState((prev) => deriveState(composite, prev));
+    return composite.subscribe(() => {
       setState((prev) => deriveState(composite, prev));
-      return composite.subscribe(() => {
-        setState((prev) => deriveState(composite, prev));
-      });
-    }, [composite]);
-
-    return {
-      getState: () => deriveState(composite, state),
-      getModelContext: () => composite.getModelContext(),
-      subscribe: (callback) => composite.subscribe(callback),
-      register: (provider) => composite.registerModelContextProvider(provider),
-    };
-  },
-);
+    });
+  }, [composite]);
+
+  return {
+    getState: () => deriveState(composite, state),
+    getModelContext: () => composite.getModelContext(),
+    subscribe: (callback) => composite.subscribe(callback),
+    register: (provider) => composite.registerModelContextProvider(provider),
+  };
+};
+
+export const ModelContext = resource(useModelContext);