@assistant-ui/core 0.3.18 → 0.3.19

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

@@ -427,6 +427,27 @@ describe("LocalThreadRuntimeCore state", () => {
 });
 
 describe("LocalThreadRuntimeCore tool approvals", () => {
+  it("emits a decision with its message and tool call IDs", async () => {
+    const { thread } = createApprovalThread(
+      toolCallResult("send_email", { id: "a1" }),
+    );
+    const answered = vi.fn();
+    thread.unstable_on("toolApprovalAnswered", answered);
+
+    await thread.append(userMessage("send an email"));
+    await flush();
+    const messageId = thread.messages.at(-1)?.id;
+
+    await thread.respondToToolApproval({ approvalId: "a1", approved: false });
+
+    expect(answered).toHaveBeenCalledWith({
+      messageId,
+      toolCallId: "call-send_email",
+      toolName: "send_email",
+      approved: false,
+    });
+  });
+
   it("pauses the run while an approval is pending, even for unlisted tools", async () => {
     const { thread, runs } = createApprovalThread(
       toolCallResult("deploy", { id: "a1" }),

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

@@ -342,6 +342,8 @@ export class LocalThreadRuntimeCore
   }
 
   public async append(message: AppendMessage): Promise<void> {
+    if (this._isVoiceMessage(message.sourceId))
+      throw new Error("Voice transcript messages cannot be edited");
     const isTail = message.parentId === (this.messages.at(-1)?.id ?? null);
     const willRun = message.startRun ?? message.role === "user";
     if (this._queue && willRun && isTail) {
@@ -488,10 +490,12 @@ export class LocalThreadRuntimeCore
   }
 
   public async startRun(
-    { parentId, runConfig }: StartRunConfig,
+    { parentId, sourceId, runConfig }: StartRunConfig,
     runCallback?: ChatModelAdapter["run"],
   ): Promise<void> {
     this.ensureInitialized();
+    if (this._isVoiceMessage(sourceId))
+      throw new Error("Voice transcript messages cannot be reloaded");
 
     // add assistant message
     const id = generateId();
@@ -961,6 +965,12 @@ export class LocalThreadRuntimeCore
     const { parentId } = this.repository.getMessage(message.id);
     this.repository.addOrUpdateMessage(parentId, message);
     this._notifySubscribers();
+    this._notifyToolApprovalAnswered(
+      message.id,
+      target.toolCallId,
+      target.toolName,
+      approved,
+    );
 
     if (
       this.repository.headId === message.id &&

package/src/runtimes/tool-invocations/EDGE_CASES.md

@@ -72,9 +72,7 @@ If the tool also had a frontend `execute`, the executor is short-circuited
 via the entry's per-execution skip marker. Single fire.
 
 ### A.6. Previously-resolved tool's `result` is replaced
-Silently ignored — `entry.hasResult` short-circuits both the
-re-`setResponse` path and the downstream result-chunk handler. The host
-sees only the first result.
+Silently ignored. A restored entry with a result remains historical even when a live snapshot reserializes its `argsText` or replaces its result. For active entries, `entry.hasResult` short-circuits both the re-`setResponse` path and the downstream result-chunk handler. The host sees only the first result.
 
 ### A.7. Previously-resolved tool loses its `result` (back to undefined)
 Silently ignored. The entry stays in the resolved phase internally.
@@ -213,9 +211,7 @@ Silently kept as restored. Recursion into `content.messages` still
 happens so any nested live tool calls are processed.
 
 ### C.3. Restored entry observed in a live snapshot, signature changed
-The restored entry is deleted and a new active entry starts via
-`_startActiveEntry`. This is PR #4057's promotion path. `streamCall`
-fires once — its first and only fire for this `toolCallId`.
+A restored entry with a result remains historical regardless of later `argsText` or result changes. An unresolved restored entry is promoted only when a result lands or its `argsText` changes. Complete `argsText` values that parse to equivalent JSON are unchanged. Promotion deletes the restored entry and starts a new active entry via `_startActiveEntry`. `streamCall` fires once, its first and only fire for this `toolCallId`.
 
 ### C.4. `isLoading` transitions `true → false` while messages are stable
 The next `setState` call sees `isLoading === false` and processes

package/src/runtimes/tool-invocations/ToolInvocationTracker.test.ts

@@ -1465,6 +1465,139 @@ describe("ToolInvocationTracker", () => {
     expect(onResult).not.toHaveBeenCalled();
   });
 
+  it("keeps a resolved restored tool call historical when its snapshot is reserialized", async () => {
+    const execute = vi.fn(async () => ({ forecast: "ok" }));
+    const streamCall = vi.fn();
+    const getTools = () => ({
+      weatherSearch: {
+        parameters: { type: "object", properties: {} },
+        execute,
+        streamCall,
+      } satisfies Tool,
+    });
+    const onResult = vi.fn();
+    const tracker = new ToolInvocationTracker(getTools, {
+      onResult,
+      onStatusesChange: () => {},
+    });
+
+    tracker.setState(
+      createState([
+        createAssistantMessage(
+          '{"query":"London","page":1}',
+          { query: "London", page: 1 },
+          { result: { source: "history", revision: 1 } },
+        ),
+      ]),
+    );
+
+    tracker.setState(
+      createState([
+        createAssistantMessage(
+          '{ "page": 1, "query": "London" }',
+          { query: "London", page: 1 },
+          { result: { source: "history", revision: 2 } },
+        ),
+      ]),
+    );
+
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(streamCall).not.toHaveBeenCalled();
+    expect(execute).not.toHaveBeenCalled();
+    expect(onResult).not.toHaveBeenCalled();
+  });
+
+  it("promotes unresolved restored tool calls only for real args changes or a landed result", async () => {
+    const equivalentStreamCall = vi.fn();
+    const growingStreamCall = vi.fn();
+    const resolvedStreamCall = vi.fn();
+    const getTools = () => ({
+      equivalentTool: {
+        parameters: { type: "object", properties: {} },
+        streamCall: equivalentStreamCall,
+      } satisfies Tool,
+      growingTool: {
+        parameters: { type: "object", properties: {} },
+        streamCall: growingStreamCall,
+      } satisfies Tool,
+      resolvedTool: {
+        parameters: { type: "object", properties: {} },
+        streamCall: resolvedStreamCall,
+      } satisfies Tool,
+    });
+    const tracker = new ToolInvocationTracker(getTools, {
+      onResult: vi.fn(),
+      onStatusesChange: () => {},
+    });
+
+    tracker.setState(
+      createState([
+        createAssistantMessage(
+          '{"a":1,"b":2}',
+          { a: 1, b: 2 },
+          {
+            toolCallId: "equivalent",
+            toolName: "equivalentTool",
+          },
+        ),
+        createAssistantMessage(
+          '{"query":"Lon',
+          { query: "Lon" },
+          {
+            toolCallId: "growing",
+            toolName: "growingTool",
+          },
+        ),
+        createAssistantMessage(
+          '{"city":"London"}',
+          { city: "London" },
+          {
+            toolCallId: "resolved",
+            toolName: "resolvedTool",
+          },
+        ),
+      ]),
+    );
+
+    tracker.setState(
+      createState([
+        createAssistantMessage(
+          '{ "b": 2, "a": 1 }',
+          { a: 1, b: 2 },
+          {
+            toolCallId: "equivalent",
+            toolName: "equivalentTool",
+          },
+        ),
+        createAssistantMessage(
+          '{"query":"London"}',
+          { query: "London" },
+          {
+            toolCallId: "growing",
+            toolName: "growingTool",
+          },
+        ),
+        createAssistantMessage(
+          '{"city":"London"}',
+          { city: "London" },
+          {
+            toolCallId: "resolved",
+            toolName: "resolvedTool",
+            result: { source: "history" },
+          },
+        ),
+      ]),
+    );
+
+    await waitFor(() => {
+      expect(growingStreamCall).toHaveBeenCalledTimes(1);
+      expect(resolvedStreamCall).toHaveBeenCalledTimes(1);
+    });
+
+    expect(equivalentStreamCall).not.toHaveBeenCalled();
+  });
+
   it("promotes an in-progress tool call from the initial snapshot when it changes", async () => {
     const execute = vi.fn(async () => ({ forecast: "ok" }));
     const streamCall = vi.fn();

package/src/runtimes/tool-invocations/ToolInvocationTracker.ts

@@ -825,12 +825,16 @@ export class ToolInvocationTracker {
         this._discardedToolCallIds.delete(content.toolCallId);
 
       if (entry && !entry.controller) {
-        // Restored entry observed in a live snapshot. Promote if its
-        // signature has changed; otherwise treat as still-historical.
-        const signatureChanged =
-          content.argsText !== entry.argsText ||
-          (content.result !== undefined) !== entry.hasResult;
-        if (!signatureChanged) continue;
+        // A restored entry with a result remains historical.
+        if (entry.hasResult) continue;
+        const argsChanged =
+          content.argsText !== entry.argsText &&
+          !(
+            isArgsTextComplete(entry.argsText) &&
+            isArgsTextComplete(content.argsText) &&
+            isEquivalentCompleteArgsText(entry.argsText, content.argsText)
+          );
+        if (!argsChanged && content.result === undefined) continue;
         this._entries.delete(content.toolCallId);
         entry = undefined;
       }

package/src/store/clients/external-thread.ts

@@ -55,6 +55,7 @@ import { toMessagePartStatus } from "../../utils/normalizePartStatus";
 import { generateId } from "../../utils/id";
 import { ModelContext } from "./model-context-client";
 import { ThreadSuggestions } from "./suggestions";
+import { createTaskDeriver, getTaskKey, TaskClient } from "./thread-tasks";
 import { Tools } from "../../react/client/Tools";
 import { DataRenderers } from "../../react/client/DataRenderers";
 import { SingleThreadList } from "./single-thread-list";
@@ -569,7 +570,7 @@ const useComposerClientResource = ({
     await Promise.all(
       removed
         .filter((a) => a.status.type !== "complete")
-        .map((a) => attachmentAdapter.remove(a)),
+        .map(async (a) => attachmentAdapter.remove(a)),
     );
   };
 
@@ -1025,6 +1026,14 @@ const useExternalThread = ({
     }),
   );
 
+  const taskDeriver = useMemo(() => createTaskDeriver(), []);
+  const tasks = useMemo(() => taskDeriver(messages), [taskDeriver, messages]);
+  const taskClients = useClientLookup(
+    tasks.map((task) =>
+      withKey(getTaskKey(task), TaskClient({ task }), [task]),
+    ),
+  );
+
   const handleCancelRun = () => {
     // Nothing is aborted without a handler, so pausing the queue would hold
     // the pending items against a run that keeps going.
@@ -1109,6 +1118,7 @@ const useExternalThread = ({
         queue: hasQueue,
       },
       messages: messageStates,
+      tasks,
       state: threadState ?? {},
       suggestions: EMPTY_SUGGESTIONS,
       extras,
@@ -1134,12 +1144,20 @@ const useExternalThread = ({
     speech,
     messageClients.state,
     composerClient.state,
+    tasks,
   ]);
 
   return {
     getState: () => state,
     composer: () => composerClient.methods,
     suggestions: () => suggestionsClient.methods,
+    task: (selector) => {
+      if ("id" in selector) {
+        const task = tasks.find((candidate) => candidate.id === selector.id);
+        return taskClients.get({ key: task ? getTaskKey(task) : selector.id });
+      }
+      return taskClients.get(selector);
+    },
     append: (message) => {
       const appendMessage: AppendMessage =
         typeof message === "string"

package/src/store/clients/thread-tasks.test.ts

@@ -0,0 +1,274 @@
+import { describe, expect, it } from "vitest";
+import type { ThreadMessage, ToolCallMessagePart } from "../../types/message";
+import { createTaskDeriver, getTaskKey } from "./thread-tasks";
+
+const assistantMessage = (
+  id: string,
+  status:
+    | { type: "running" }
+    | { type: "complete"; reason: "stop" }
+    | { type: "incomplete"; reason: "error"; error: unknown },
+  content:
+    | readonly ToolCallMessagePart[]
+    | readonly { type: "text"; text: string }[],
+) =>
+  ({
+    id,
+    role: "assistant",
+    createdAt: new Date(0),
+    content,
+    status,
+    metadata: {
+      unstable_state: {},
+      unstable_annotations: [],
+      unstable_data: [],
+      steps: [],
+      custom: {},
+    },
+  }) as unknown as ThreadMessage;
+
+const toolCall = (
+  id: string,
+  messages?: readonly ThreadMessage[],
+  result?: unknown,
+) =>
+  ({
+    type: "tool-call",
+    toolCallId: id,
+    toolName: "delegate",
+    args: { id },
+    argsText: JSON.stringify({ id }),
+    ...(messages !== undefined ? { messages } : undefined),
+    ...(result !== undefined ? { result } : undefined),
+  }) as ToolCallMessagePart;
+
+describe("createTaskDeriver", () => {
+  it("derives top-level and nested tasks in document order", () => {
+    const nestedTask = toolCall("nested-1", []);
+    const nestedMessage = assistantMessage(
+      "nested-message",
+      { type: "running" },
+      [nestedTask],
+    );
+    const topLevelTask = toolCall("top-level-1", [nestedMessage]);
+    const tasks = createTaskDeriver()([
+      assistantMessage("outer-message", { type: "running" }, [topLevelTask]),
+    ]);
+
+    expect(tasks.map((task) => task.id)).toEqual(["top-level-1", "nested-1"]);
+    expect(tasks[0]).toMatchObject({
+      depth: 0,
+      parentTaskId: null,
+      messageId: "outer-message",
+    });
+    expect(tasks[1]).toMatchObject({
+      depth: 1,
+      parentTaskId: "top-level-1",
+      messageId: "nested-message",
+    });
+  });
+
+  it("uses normalized tool call statuses", () => {
+    const tasks = createTaskDeriver()([
+      assistantMessage("outer-message", { type: "running" }, [
+        toolCall("pending", []),
+        toolCall("complete", [], "done"),
+      ]),
+    ]);
+
+    expect(tasks.map((task) => task.status)).toEqual([
+      { type: "running" },
+      { type: "complete" },
+    ]);
+  });
+
+  it("excludes tool calls without nested messages", () => {
+    const tasks = createTaskDeriver()([
+      assistantMessage("outer-message", { type: "running" }, [
+        toolCall("not-a-task"),
+        toolCall("task", []),
+      ]),
+    ]);
+
+    expect(tasks.map((task) => task.id)).toEqual(["task"]);
+  });
+
+  it("preserves the array identity when an unrelated sibling changes", () => {
+    const task = toolCall("delegate-1", []);
+    const derive = createTaskDeriver();
+    const initial = derive([
+      assistantMessage("outer-message", { type: "running" }, [
+        { type: "text", text: "one" },
+        task,
+      ] as unknown as readonly ToolCallMessagePart[]),
+    ]);
+    const updated = derive([
+      assistantMessage("outer-message", { type: "running" }, [
+        { type: "text", text: "two" },
+        task,
+      ] as unknown as readonly ToolCallMessagePart[]),
+    ]);
+
+    expect(updated).toBe(initial);
+  });
+
+  it("creates a fresh entry and array when a nested status changes", () => {
+    const nestedTask = toolCall("nested-1", []);
+    const derive = createTaskDeriver();
+    const initial = derive([
+      assistantMessage("outer-message", { type: "running" }, [
+        toolCall("top-level-1", [
+          assistantMessage("nested-message", { type: "running" }, [nestedTask]),
+        ]),
+      ]),
+    ]);
+    const updated = derive([
+      assistantMessage("outer-message", { type: "running" }, [
+        toolCall("top-level-1", [
+          assistantMessage(
+            "nested-message",
+            { type: "complete", reason: "stop" },
+            [nestedTask],
+          ),
+        ]),
+      ]),
+    ]);
+
+    expect(updated).not.toBe(initial);
+    expect(updated[1]).not.toBe(initial[1]);
+    expect(updated[1]?.status).toMatchObject({ type: "complete" });
+  });
+
+  it("creates a fresh entry when an incomplete status changes its error", () => {
+    const task = toolCall("failing", []);
+    const derive = createTaskDeriver();
+    const initial = derive([
+      assistantMessage(
+        "outer-message",
+        { type: "incomplete", reason: "error", error: "first" },
+        [task],
+      ),
+    ]);
+    const updated = derive([
+      assistantMessage(
+        "outer-message",
+        { type: "incomplete", reason: "error", error: "second" },
+        [task],
+      ),
+    ]);
+
+    expect(updated).not.toBe(initial);
+    expect(updated[0]).not.toBe(initial[0]);
+    expect(updated[0]?.status).toMatchObject({
+      type: "incomplete",
+      reason: "error",
+      error: "second",
+    });
+  });
+
+  it("rebuilds an entry when an unchanged part moves to another message", () => {
+    const part = toolCall("moving", []);
+    const derive = createTaskDeriver();
+    const initial = derive([
+      assistantMessage("first-message", { type: "running" }, [part]),
+    ]);
+    const moved = derive([
+      assistantMessage("second-message", { type: "running" }, [part]),
+    ]);
+
+    expect(moved[0]).not.toBe(initial[0]);
+    expect(moved[0]?.messageId).toBe("second-message");
+  });
+
+  it("stops descending past the depth cap", () => {
+    let content: readonly ToolCallMessagePart[] = [toolCall("leaf", [])];
+    for (let level = 40; level > 0; level -= 1) {
+      content = [
+        toolCall(`level-${level}`, [
+          assistantMessage(`message-${level}`, { type: "running" }, content),
+        ]),
+      ];
+    }
+    const tasks = createTaskDeriver()([
+      assistantMessage("root", { type: "running" }, content),
+    ]);
+
+    expect(Math.max(...tasks.map((task) => task.depth))).toBe(32);
+  });
+
+  it("keeps the array identity when nested conversations repeat a toolCallId", () => {
+    const nested = (messageId: string) =>
+      assistantMessage(messageId, { type: "complete", reason: "stop" }, [
+        toolCall("call_1", [], "ok"),
+      ]);
+    const messages = [
+      assistantMessage("outer-message", { type: "complete", reason: "stop" }, [
+        toolCall("delegate-a", [nested("nested-a")], "ok"),
+        toolCall("delegate-b", [nested("nested-b")], "ok"),
+      ]),
+    ];
+    const derive = createTaskDeriver();
+    const first = derive(messages);
+    const second = derive(messages);
+
+    expect(first.map((task) => task.id)).toEqual([
+      "delegate-a",
+      "call_1",
+      "delegate-b",
+      "call_1",
+    ]);
+    expect(second).toBe(first);
+  });
+
+  it("keys tasks by document order when nested payloads repeat every id", () => {
+    const replay = () =>
+      assistantMessage("nested", { type: "complete", reason: "stop" }, [
+        toolCall("call_1", [], "ok"),
+      ]);
+    const messages = [
+      assistantMessage("outer-message", { type: "complete", reason: "stop" }, [
+        toolCall("delegate-a", [replay()], "ok"),
+        toolCall("delegate-b", [replay()], "ok"),
+      ]),
+    ];
+    const derive = createTaskDeriver();
+    const first = derive(messages);
+
+    expect(new Set(first.map(getTaskKey)).size).toBe(4);
+    expect(derive(messages)).toBe(first);
+  });
+
+  it("reads a nested message without a status as complete", () => {
+    const unnormalized = {
+      ...assistantMessage("nested", { type: "running" }, [
+        toolCall("call_1", []),
+      ]),
+      status: undefined,
+    } as unknown as ThreadMessage;
+    const [, nestedTask] = createTaskDeriver()([
+      assistantMessage("outer-message", { type: "running" }, [
+        toolCall("delegate", [unnormalized], "ok"),
+      ]),
+    ]);
+
+    expect(nestedTask?.status).toEqual({ type: "complete" });
+  });
+
+  it("preserves unchanged entries when a task is appended", () => {
+    const first = toolCall("first", []);
+    const derive = createTaskDeriver();
+    const initial = derive([
+      assistantMessage("outer-message", { type: "running" }, [first]),
+    ]);
+    const updated = derive([
+      assistantMessage("outer-message", { type: "running" }, [
+        first,
+        toolCall("second", []),
+      ]),
+    ]);
+
+    expect(updated).not.toBe(initial);
+    expect(updated[0]).toBe(initial[0]);
+    expect(updated.map((task) => task.id)).toEqual(["first", "second"]);
+  });
+});