@assistant-ui/core 0.2.12 → 0.2.15

package/src/runtime/utils/resolveToolApprovalResponse.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import { resolveToolApprovalResponse } from "./resolveToolApprovalResponse";
+
+const approval = {
+  id: "a1",
+  options: [
+    { id: "once", kind: "allow-once" as const },
+    { id: "always", kind: "allow-always" as const, grants: ["git *"] },
+    { id: "deny", kind: "reject-once" as const },
+    { id: "never", kind: "reject-always" as const },
+    { id: "edit", kind: "_modify" },
+  ],
+};
+
+describe("resolveToolApprovalResponse", () => {
+  it("passes through boolean responses", () => {
+    expect(resolveToolApprovalResponse(approval, { approved: true })).toEqual({
+      approvalId: "a1",
+      approved: true,
+    });
+    expect(
+      resolveToolApprovalResponse(approval, {
+        approved: false,
+        reason: "nope",
+      }),
+    ).toEqual({ approvalId: "a1", approved: false, reason: "nope" });
+  });
+
+  it("resolves allow kinds to approved: true", () => {
+    expect(resolveToolApprovalResponse(approval, { optionId: "once" })).toEqual(
+      { approvalId: "a1", approved: true, optionId: "once" },
+    );
+    expect(
+      resolveToolApprovalResponse(approval, { optionId: "always" }),
+    ).toEqual({ approvalId: "a1", approved: true, optionId: "always" });
+  });
+
+  it("resolves reject kinds to approved: false and keeps the reason", () => {
+    expect(
+      resolveToolApprovalResponse(approval, {
+        optionId: "deny",
+        reason: "not now",
+      }),
+    ).toEqual({
+      approvalId: "a1",
+      approved: false,
+      optionId: "deny",
+      reason: "not now",
+    });
+    expect(
+      resolveToolApprovalResponse(approval, { optionId: "never" }),
+    ).toEqual({ approvalId: "a1", approved: false, optionId: "never" });
+  });
+
+  it("throws for an unknown option id", () => {
+    expect(() =>
+      resolveToolApprovalResponse(approval, { optionId: "missing" }),
+    ).toThrow('no option with id "missing"');
+  });
+
+  it("throws for custom kinds instead of guessing a boolean", () => {
+    expect(() =>
+      resolveToolApprovalResponse(approval, { optionId: "edit" }),
+    ).toThrow('custom kind "_modify"');
+  });
+
+  it("accepts an explicit approved alongside the optionId for custom kinds", () => {
+    expect(
+      resolveToolApprovalResponse(approval, {
+        optionId: "edit",
+        approved: true,
+      }),
+    ).toEqual({ approvalId: "a1", approved: true, optionId: "edit" });
+  });
+
+  it("does not resolve kinds named after Object.prototype members", () => {
+    const trap = {
+      id: "a3",
+      options: [{ id: "x", kind: "constructor" }],
+    };
+    expect(() => resolveToolApprovalResponse(trap, { optionId: "x" })).toThrow(
+      'custom kind "constructor"',
+    );
+  });
+
+  it("throws for option responses when the approval has no options", () => {
+    expect(() =>
+      resolveToolApprovalResponse({ id: "a2" }, { optionId: "once" }),
+    ).toThrow('no option with id "once"');
+  });
+});

package/src/runtime/utils/resolveToolApprovalResponse.ts

@@ -0,0 +1,55 @@
+import type {
+  ToolApprovalOption,
+  ToolApprovalResponse,
+} from "../../types/message";
+import type { RespondToToolApprovalOptions } from "../interfaces/thread-runtime-core";
+
+const APPROVED_BY_KIND: Record<string, boolean> = {
+  "allow-once": true,
+  "allow-always": true,
+  "reject-once": false,
+  "reject-always": false,
+};
+
+/**
+ * Resolves a renderer-facing approval response (boolean or optionId form)
+ * against the approval's option list into the runtime-facing decision shape.
+ */
+export const resolveToolApprovalResponse = (
+  approval: {
+    readonly id: string;
+    readonly options?: readonly ToolApprovalOption[];
+  },
+  response: ToolApprovalResponse,
+): RespondToToolApprovalOptions => {
+  let approved: boolean;
+  let optionId: string | undefined;
+
+  if ("optionId" in response) {
+    const option = approval.options?.find((o) => o.id === response.optionId);
+    if (!option)
+      throw new Error(
+        `Tool approval has no option with id "${response.optionId}"`,
+      );
+
+    if ("approved" in response) {
+      approved = response.approved;
+    } else {
+      if (!Object.hasOwn(APPROVED_BY_KIND, option.kind))
+        throw new Error(
+          `Tool approval option "${option.id}" has a custom kind "${option.kind}"; respond with an explicit approved value instead`,
+        );
+      approved = APPROVED_BY_KIND[option.kind]!;
+    }
+    optionId = option.id;
+  } else {
+    approved = response.approved;
+  }
+
+  return {
+    approvalId: approval.id,
+    approved,
+    ...(optionId !== undefined && { optionId }),
+    ...(response.reason != null && { reason: response.reason }),
+  };
+};

package/src/runtime/utils/thread-message-like.ts

@@ -18,7 +18,12 @@ import type {
   Unstable_AudioMessagePart,
 } from "../../types/message";
 import type { CompleteAttachment } from "../../types/attachment";
-import type { MessageTiming, TextMessagePart } from "../../types/message";
+import type {
+  MessageTiming,
+  TextMessagePart,
+  ToolApprovalOption,
+  ToolCallTiming,
+} from "../../types/message";
 import type {
   ReadonlyJSONObject,
   ReadonlyJSONValue,
@@ -55,11 +60,15 @@ export type ThreadMessageLike = {
             readonly parentId?: string | undefined;
             readonly messages?: readonly ThreadMessage[] | undefined;
             readonly interrupt?: { type: "human"; payload: unknown };
+            readonly timing?: ToolCallTiming;
             readonly approval?: {
               readonly id: string;
               readonly approved?: boolean;
               readonly reason?: string;
               readonly isAutomatic?: boolean;
+              readonly options?: readonly ToolApprovalOption[];
+              readonly optionId?: string;
+              readonly resolution?: "cancelled" | "expired";
             };
           }
       )[];

package/src/runtimes/external-store/external-store-adapter.ts

@@ -109,6 +109,7 @@ type ExternalStoreAdapterBase<T> = {
   /** Opt in to message queuing. Typically produced by `createMessageQueue`. */
   queue?: ExternalThreadQueueAdapter | undefined;
   onEdit?: ((message: AppendMessage) => Promise<void>) | undefined;
+  onDelete?: ((messageId: string) => Promise<void> | void) | undefined;
   onReload?: // TODO: remove parentId in 0.12.0
     | ((parentId: string | null, config: StartRunConfig) => Promise<void>)
     | undefined;

package/src/runtimes/external-store/external-store-thread-runtime-core.ts

@@ -60,6 +60,7 @@ export class ExternalStoreThreadRuntimeCore
     switchToBranch: false,
     switchBranchDuringRun: false,
     edit: false,
+    delete: false,
     reload: false,
     cancel: false,
     unstable_copy: false,
@@ -148,6 +149,9 @@ export class ExternalStoreThreadRuntimeCore
       switchToBranch: this._store.setMessages !== undefined,
       switchBranchDuringRun: false,
       edit: this._store.onEdit !== undefined,
+      delete:
+        this._store.onDelete !== undefined ||
+        this._store.setMessages !== undefined,
       reload: this._store.onReload !== undefined,
       cancel: this._store.onCancel !== undefined,
       speech: this._store.adapters?.speech !== undefined,
@@ -419,6 +423,26 @@ export class ExternalStoreThreadRuntimeCore
     }
   }
 
+  public async deleteMessage(messageId: string): Promise<void> {
+    if (this._store.onDelete) {
+      await this._store.onDelete(messageId);
+      return;
+    }
+
+    if (!this._store.setMessages)
+      throw new Error("Runtime does not support deleting messages.");
+
+    if (this._store.isRunning) {
+      await this._toolInvocations?.abort();
+    }
+
+    const messages = this.repository.getMessages();
+    const messageIndex = messages.findIndex((m) => m.id === messageId);
+    if (messageIndex === -1) throw new Error("Message not found.");
+
+    this.updateMessages(messages.filter((message) => message.id !== messageId));
+  }
+
   public getQueueItems() {
     // The composer reads this during base-thread construction, before the
     // constructor assigns `_store`, so guard against the unset field.

package/src/runtimes/local/local-runtime-options.ts

@@ -23,7 +23,7 @@ export type LocalRuntimeOptionsBase = {
   };
 
   /**
-   * Names of tools that are allowed to interrupt the run in order to wait for human/external approval.
+   * Names of tools that pause the run until a result is supplied via `addToolResult`.
    */
   unstable_humanToolNames?: string[] | undefined;
 

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

@@ -0,0 +1,370 @@
+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; resolution?: "cancelled" | "expired" },
+) => ({
+  type: "tool-call" as const,
+  toolCallId: `call-${toolName}`,
+  toolName,
+  args: {},
+  argsText: "{}",
+  ...(approval !== undefined ? { approval } : {}),
+});
+
+const toolCallResult = (
+  toolName: string,
+  approval?: { id: string; resolution?: "cancelled" | "expired" },
+): 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("records the chosen optionId alongside the decision", 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,
+      optionId: "always",
+    });
+    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,
+      optionId: "always",
+    });
+  });
+
+  it("treats a terminal resolution as non-pending and continues the run", async () => {
+    const { thread, runs } = createApprovalThread(
+      toolCallResult("deploy", { id: "a1", resolution: "expired" }),
+    );
+
+    await thread.append(userMessage("deploy the app"));
+    await flush();
+
+    expect(runs).toHaveLength(2);
+    expect(thread.messages.at(-1)?.status?.type).toBe("complete");
+  });
+
+  it("rejects responses to approvals with a terminal resolution", async () => {
+    const { thread } = createApprovalThread({
+      content: [
+        toolCallPart("deploy", { id: "a1", resolution: "expired" }),
+        toolCallPart("send_email"),
+      ],
+      status: { type: "requires-action", reason: "tool-calls" },
+    });
+
+    await thread.append(userMessage("deploy and email"));
+    await flush();
+
+    expect(thread.messages.at(-1)?.status?.type).toBe("requires-action");
+    expect(() =>
+      thread.respondToToolApproval({ approvalId: "a1", approved: true }),
+    ).toThrow("cancelled or expired");
+  });
+
+  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/);
+  });
+});