@assistant-ui/core 0.3.18 → 0.3.20

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

@@ -475,6 +475,17 @@ export class ExternalStoreThreadRuntimeCore
       this._messages = messagesSnapshot;
     }
 
+    if (this._voiceMessages.length > 0) {
+      const hostIds = new Set(this._messages.map((message) => message.id));
+      const remaining = this._voiceMessages.filter(
+        (message) => !hostIds.has(message.id),
+      );
+      if (remaining.length !== this._voiceMessages.length) {
+        this._voiceMessages = remaining;
+        this._markVoiceMessagesDirty();
+      }
+    }
+
     if (repositoryChanged) {
       this._runTrackerUpdate(() => this._toolInvocations?.reset());
     }
@@ -637,21 +648,31 @@ export class ExternalStoreThreadRuntimeCore
   }
 
   public async append(rawMessage: AppendMessage): Promise<void> {
+    let message = {
+      ...rawMessage,
+      parentId: this._resolveAppendParent(rawMessage.parentId),
+    };
+    if (this.voice)
+      throw new Error(
+        "Cannot send a text message while a voice session is connected",
+      );
+    if (this._isVoiceMessage(message.sourceId))
+      throw new Error("Voice transcript messages cannot be edited");
     // sourceId marks an edit send; the parent may coincide with the head
     // after a resync (e.g. cancelRun dropped the edited message).
     const isEdit =
-      rawMessage.sourceId != null ||
-      rawMessage.parentId !== (this.messages.at(-1)?.id ?? null);
+      message.sourceId != null ||
+      message.parentId !== (this._getBaseMessages().at(-1)?.id ?? null);
 
     // A transformed-queue send is stamped at flush; any other queue's
     // transform would gate against its own thread's messages, so those stamp
     // at send.
-    const message =
+    message =
       !isEdit &&
       this._store.queue &&
       this._store.queue === this._transformedQueue
-        ? rawMessage
-        : this.enrichAppendMetadata(rawMessage);
+        ? message
+        : this.enrichAppendMetadata(message);
 
     const generation = captureThreadRuntimeGeneration(this);
     this.ensureInitialized();
@@ -705,6 +726,10 @@ export class ExternalStoreThreadRuntimeCore
     }
   }
 
+  protected override _commitVoiceMessage(message: ThreadMessage): void {
+    this._store.onVoiceTranscript?.(message);
+  }
+
   public async deleteMessage(messageId: string): Promise<void> {
     if (this._store.onDelete) {
       // The host owns deletion here, and it may decline (fail a server call,
@@ -761,7 +786,14 @@ export class ExternalStoreThreadRuntimeCore
     }
 
     this.repository.deleteMessage(messageId);
-    this._messages = this.repository.getMessages();
+    this._publishRepositoryMessages();
+  }
+
+  // Notifies even when the visible messages are unchanged: deleting an
+  // off-branch message still changes the branch counts subscribers read.
+  private _publishRepositoryMessages() {
+    const messages = this.repository.getMessages();
+    if (!shallowArrayEqual(this._messages, messages)) this._messages = messages;
     this._notifySubscribers();
   }
 
@@ -786,6 +818,10 @@ export class ExternalStoreThreadRuntimeCore
   public async startRun(config: StartRunConfig): Promise<void> {
     if (!this._store.onReload)
       throw new Error("Runtime does not support reloading messages.");
+    if (this.voice)
+      throw new Error("Cannot start a run while a voice session is connected");
+    if (this._isVoiceMessage(config.sourceId))
+      throw new Error("Voice transcript messages cannot be reloaded");
 
     this._pendingDeleteEvictions.clear();
 
@@ -800,6 +836,10 @@ export class ExternalStoreThreadRuntimeCore
   public async resumeRun(config: ResumeRunConfig): Promise<void> {
     if (!this._store.onResume)
       throw new Error("Runtime does not support resuming runs.");
+    if (this.voice)
+      throw new Error("Cannot start a run while a voice session is connected");
+    if (this._isVoiceMessage(config.sourceId))
+      throw new Error("Voice transcript messages cannot be reloaded");
 
     await this._store.onResume(config);
   }
@@ -892,7 +932,7 @@ export class ExternalStoreThreadRuntimeCore
         movedLeaf = { id: trailingUserLeaf.id, draft };
       }
     }
-    if (!movedLeaf) this._notifySubscribers();
+    this._publishRepositoryMessages();
 
     // The resync commits what the cancel left (a kept optimistic message, the
     // restored branch) back to the store a macrotask later. The store may move
@@ -914,7 +954,8 @@ export class ExternalStoreThreadRuntimeCore
           this.composer.retractDraft(movedLeaf.draft);
         }
       }
-      this.updateMessages(this.repository.getMessages());
+      this._publishRepositoryMessages();
+      this.updateMessages(this._messages);
     }, 0);
   }
 
@@ -961,8 +1002,32 @@ export class ExternalStoreThreadRuntimeCore
   ): Promise<void> {
     if (!this._store.onRespondToToolApproval)
       throw new Error("Runtime does not support tool approvals.");
+    const message = this.messages.findLast(
+      (candidate) =>
+        candidate.role === "assistant" &&
+        candidate.content.some(
+          (part) =>
+            part.type === "tool-call" &&
+            part.approval?.id === options.approvalId,
+        ),
+    );
+    const toolCall = message?.content.find(
+      (part) =>
+        part.type === "tool-call" && part.approval?.id === options.approvalId,
+    );
     try {
-      return Promise.resolve(this._store.onRespondToToolApproval(options));
+      return Promise.resolve(this._store.onRespondToToolApproval(options)).then(
+        () => {
+          if (message && toolCall?.type === "tool-call") {
+            this._notifyToolApprovalAnswered(
+              message.id,
+              toolCall.toolCallId,
+              toolCall.toolName,
+              options.approved,
+            );
+          }
+        },
+      );
     } catch (error) {
       return Promise.reject(error);
     }

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

@@ -6,6 +6,7 @@ import type {
   ChatModelRunResult,
 } from "../../runtime/utils/chat-model-adapter";
 import type { AppendMessage, ToolCallMessagePart } from "../../types/message";
+import type { ThreadHistoryAdapter } from "../../adapters/thread-history";
 import type { LocalRuntimeOptionsBase } from "./local-runtime-options";
 import {
   ExportedMessageRepository,
@@ -407,6 +408,76 @@ describe("LocalThreadRuntimeCore human-in-the-loop tools", () => {
   });
 });
 
+describe("LocalThreadRuntimeCore addToolResult content", () => {
+  it("stores modelContent and forwards it to the resumed adapter", async () => {
+    const { thread, runs } = createApprovalThread(toolCallResult("send_email"));
+
+    await thread.append(userMessage("send an email"));
+    await flush();
+
+    thread.addToolResult({
+      messageId: thread.messages.at(-1)!.id,
+      toolCallId: "call-send_email",
+      toolName: "send_email",
+      result: { approved: true },
+      isError: false,
+      modelContent: [{ type: "text", text: "Email sent." }],
+    });
+    await flush();
+
+    const resumedToolCall = runs[1]!
+      .unstable_getMessage()
+      .content.find((part) => part.type === "tool-call");
+    expect(resumedToolCall?.modelContent).toEqual([
+      { type: "text", text: "Email sent." },
+    ]);
+
+    const storedToolCall = thread.messages
+      .at(-1)!
+      .content.find((part) => part.type === "tool-call");
+    expect(storedToolCall?.modelContent).toEqual([
+      { type: "text", text: "Email sent." },
+    ]);
+  });
+
+  it("keeps a stored artifact when a later result omits it", async () => {
+    const { thread } = createApprovalThread(toolCallResult("send_email"));
+
+    await thread.append(userMessage("send an email"));
+    await flush();
+
+    const messageId = thread.messages.at(-1)!.id;
+    thread.addToolResult({
+      messageId,
+      toolCallId: "call-send_email",
+      toolName: "send_email",
+      result: { approved: true },
+      isError: false,
+      artifact: { draftId: "d-1" },
+    });
+    await flush();
+
+    thread.addToolResult({
+      messageId,
+      toolCallId: "call-send_email",
+      toolName: "send_email",
+      result: { approved: true, sent: true },
+      isError: false,
+    });
+    await flush();
+
+    const storedToolCall = thread.messages
+      .map((message) =>
+        message.content.find(
+          (part): part is ToolCallMessagePart =>
+            part.type === "tool-call" && part.toolCallId === "call-send_email",
+        ),
+      )
+      .find((part): part is ToolCallMessagePart => part !== undefined);
+    expect(storedToolCall?.artifact).toEqual({ draftId: "d-1" });
+  });
+});
+
 describe("LocalThreadRuntimeCore state", () => {
   it.each([
     ["false", false],
@@ -427,6 +498,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" }),
@@ -835,7 +927,7 @@ describe("LocalThreadRuntimeCore cancellation", () => {
     const toolCall = thread.messages
       .find((item) => item.id === messageId)
       ?.content.find(
-        (part) =>
+        (part): part is ToolCallMessagePart =>
           part.type === "tool-call" && part.toolCallId === "call-send_email",
       );
     expect(toolCall?.result).toEqual({ approved: true });
@@ -843,9 +935,10 @@ describe("LocalThreadRuntimeCore cancellation", () => {
 
     resolveSecond({ content: [{ type: "text", text: "replacement" }] });
     await vi.waitFor(() => {
-      expect(
-        thread.messages.find((item) => item.id === messageId)?.status.type,
-      ).toBe("complete");
+      const message = thread.messages.find((item) => item.id === messageId);
+      if (message?.role !== "assistant")
+        throw new Error("expected assistant message");
+      expect(message.status.type).toBe("complete");
     });
   });
 
@@ -894,16 +987,19 @@ describe("LocalThreadRuntimeCore cancellation", () => {
     await appendPromise;
 
     const message = thread.messages.find((item) => item.id === messageId);
-    const sendEmail = message?.content.find(
-      (part) =>
+    if (message?.role !== "assistant")
+      throw new Error("expected assistant message");
+    const sendEmail = message.content.find(
+      (part): part is ToolCallMessagePart =>
         part.type === "tool-call" && part.toolCallId === "call-send_email",
     );
-    const deploy = message?.content.find(
-      (part) => part.type === "tool-call" && part.toolCallId === "call-deploy",
+    const deploy = message.content.find(
+      (part): part is ToolCallMessagePart =>
+        part.type === "tool-call" && part.toolCallId === "call-deploy",
     );
     expect(sendEmail?.result).toEqual({ approved: true });
     expect(deploy?.approval).toEqual({ id: "approval-1" });
-    expect(message?.status.type).toBe("requires-action");
+    expect(message.status.type).toBe("requires-action");
   });
 
   it("ignores a superseded result after its message is removed", async () => {
@@ -1830,7 +1926,7 @@ describe("LocalThreadRuntimeCore runs", () => {
       ],
       status: { type: "requires-action", reason: "tool-calls" },
       metadata: {
-        steps: [{ usage: { promptTokens: 10, completionTokens: 5 } }],
+        steps: [{ usage: { inputTokens: 10, outputTokens: 5 } }],
       },
     }));
     const thread = createPlainThread({ run }, { maxSteps: 1 });
@@ -1892,7 +1988,7 @@ describe("LocalThreadRuntimeCore runs", () => {
       run: async () => ({ content: [] }),
     };
     const thread = createPlainThread(adapter);
-    const load = vi.fn(async () => ({
+    const load = vi.fn<ThreadHistoryAdapter["load"]>(async () => ({
       headId: "restored",
       messages: [
         {
@@ -1901,6 +1997,7 @@ describe("LocalThreadRuntimeCore runs", () => {
             id: "restored",
             role: "user" as const,
             content: [{ type: "text" as const, text: "hello" }],
+            attachments: [],
             createdAt: new Date(0),
             metadata: { custom: {} },
           },
@@ -1929,7 +2026,7 @@ describe("LocalThreadRuntimeCore runs", () => {
       run: async () => ({ content: [] }),
     };
     const thread = createPlainThread(adapter);
-    const load = vi.fn(async () => ({
+    const load = vi.fn<ThreadHistoryAdapter["load"]>(async () => ({
       headId: "restored",
       messages: [
         {
@@ -1938,6 +2035,7 @@ describe("LocalThreadRuntimeCore runs", () => {
             id: "restored",
             role: "user" as const,
             content: [{ type: "text" as const, text: "hello" }],
+            attachments: [],
             createdAt: new Date(0),
             metadata: { custom: {} },
           },
@@ -2199,3 +2297,82 @@ describe("LocalThreadRuntimeCore imported approvals", () => {
     expect(thread.messages.at(-1)?.status?.type).toBe("complete");
   });
 });
+
+describe("LocalThreadRuntimeCore message queue", () => {
+  const createQueuedThread = () => {
+    const dispatched: string[] = [];
+    let release!: () => void;
+    let gate = new Promise<void>((resolve) => (release = resolve));
+
+    const core = new LocalRuntimeCore(
+      {
+        adapters: {
+          chatModel: {
+            async run(options) {
+              const last = options.messages.at(-1);
+              const text = last?.content
+                .filter((part) => part.type === "text")
+                .map((part) => (part as { text: string }).text)
+                .join("");
+              dispatched.push(text ?? "");
+              await gate;
+              return { content: [{ type: "text", text: "ok" }] };
+            },
+          },
+        },
+        unstable_enableMessageQueue: true,
+      },
+      undefined,
+    );
+
+    // the in-flight run already awaits the current gate, so the next gate has
+    // to be installed before releasing it or the run dispatched next resolves
+    // against an already-settled promise
+    const releaseRun = async () => {
+      const releaseCurrent = release;
+      gate = new Promise<void>((resolve) => (release = resolve));
+      releaseCurrent();
+      await flush();
+    };
+
+    return {
+      thread: core.threads.getMainThreadRuntimeCore(),
+      dispatched,
+      releaseRun,
+    };
+  };
+
+  it("keeps the steer lane for implicit sends during back-to-back queued runs", async () => {
+    const { thread, dispatched, releaseRun } = createQueuedThread();
+    // the queue lane is only taken for a message appended onto the tail
+    const appendToTail = (text: string, steer?: boolean) =>
+      void thread.append({
+        ...userMessage(text),
+        parentId: thread.messages.at(-1)?.id ?? null,
+        ...(steer !== undefined && { steer }),
+      });
+
+    appendToTail("first");
+    await flush();
+    expect(dispatched).toEqual(["first"]);
+
+    // buffers behind the running dispatch, so releasing "first" dispatches it
+    appendToTail("second", false);
+    await flush();
+    await releaseRun();
+    expect(dispatched).toEqual(["first", "second"]);
+
+    // "second" is a queue-dispatched run in flight, so an implicit send steers
+    // ahead of a bulk item even though it is appended after it
+    appendToTail("bulk", false);
+    appendToTail("implicit");
+    await flush();
+    await releaseRun();
+
+    expect(dispatched).toEqual(["first", "second", "implicit"]);
+
+    await releaseRun();
+    expect(dispatched).toEqual(["first", "second", "implicit", "bulk"]);
+    await releaseRun();
+  });
+});

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

@@ -114,7 +114,10 @@ export class LocalThreadRuntimeCore
   private abortController: AbortController | null = null;
 
   private _queue: MessageQueueController | null = null;
-  private _queueRunInFlight = false;
+  // Identifies the dispatch in flight, not merely that one is: consecutive
+  // queue runs overlap, and the previous dispatch settles after the next one
+  // has already started.
+  private _queueRunInFlight: object | null = null;
   private _activeRun: { cancelled: boolean } | null = null;
   private _runGeneration = 0;
 
@@ -255,22 +258,29 @@ export class LocalThreadRuntimeCore
         run: (message) => {
           // release the queue when the dispatch settles, even if it rejects
           // before reaching startRun's finally, so a failure can't deadlock it
-          this._queueRunInFlight = true;
+          const dispatch = {};
+          this._queueRunInFlight = dispatch;
           const generation = this._runGeneration;
           // the tail may have moved since the message was enqueued
           void this._runAppend({
             ...message,
-            parentId: this.messages.at(-1)?.id ?? null,
+            parentId: this._resolveAppendParent(
+              this.messages.at(-1)?.id ?? null,
+            ),
           })
             .finally(() => {
-              this._queueRunInFlight = false;
-              // a dispatch that failed before starting a run settles here;
-              // runs that did start release from _runLoop
-              if (this._runGeneration === generation) this._queue?.notifyIdle();
+              if (this._queueRunInFlight === dispatch) {
+                this._queueRunInFlight = null;
+                // A dispatch that failed before starting a run settles here;
+                // runs that did start release from _runLoop.
+                if (this._runGeneration === generation)
+                  this._queue?.notifyIdle();
+              }
             })
             .catch(() => {});
         },
       });
+      if (this.voice) this._queue.hold();
       this._queue.subscribe(() => this._notifySubscribers());
     } else if (!canQueue && this._queue) {
       this._queue = null;
@@ -342,10 +352,20 @@ export class LocalThreadRuntimeCore
   }
 
   public async append(message: AppendMessage): Promise<void> {
+    message = {
+      ...message,
+      parentId: this._resolveAppendParent(message.parentId),
+    };
+    if (this.voice)
+      throw new Error(
+        "Cannot send a text message while a voice session is connected",
+      );
+    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) {
-      if (message.steer ?? this._queueRunInFlight)
+      if (message.steer ?? this._queueRunInFlight !== null)
         this._queue.adapter.steer(message);
       else this._queue.adapter.enqueue(message);
       return;
@@ -359,6 +379,28 @@ export class LocalThreadRuntimeCore
     return this._runAppend(message);
   }
 
+  protected override _commitVoiceMessage(message: ThreadMessage): void {
+    const parentId = this.repository.headId;
+    this.repository.addOrUpdateMessage(parentId, message);
+    this.repository.resetHead(message.id);
+    void this._options.adapters.history
+      ?.append({ parentId, message })
+      .catch(() => {});
+    const index = this._voiceMessages.findIndex(
+      (voiceMessage) => voiceMessage.id === message.id,
+    );
+    if (index !== -1) this._voiceMessages.splice(index, 1);
+    this._markVoiceMessagesDirty();
+  }
+
+  protected override _onVoiceConnected(): void {
+    this._queue?.hold();
+  }
+
+  protected override _onVoiceDisconnected(): void {
+    this._queue?.release();
+  }
+
   public getQueueItems(): readonly QueueItemState[] {
     // Reads can arrive during base-thread construction, before the queue field
     // is assigned, so guard against the unset field.
@@ -386,7 +428,22 @@ export class LocalThreadRuntimeCore
     this._notifySubscribers();
   }
 
+  private _pendingAppends = 0;
+
+  protected override _isRunActive(): boolean {
+    return this._pendingAppends > 0 || super._isRunActive();
+  }
+
   private async _runAppend(rawMessage: AppendMessage): Promise<void> {
+    this._pendingAppends += 1;
+    try {
+      await this._runAppendInner(rawMessage);
+    } finally {
+      this._pendingAppends -= 1;
+    }
+  }
+
+  private async _runAppendInner(rawMessage: AppendMessage): Promise<void> {
     // Stamped here rather than in `append` so a queued message is gated after
     // the flush re-pointed its parentId at the current tail.
     const generation = captureThreadRuntimeGeneration(this);
@@ -488,10 +545,14 @@ export class LocalThreadRuntimeCore
   }
 
   public async startRun(
-    { parentId, runConfig }: StartRunConfig,
+    { parentId, sourceId, runConfig }: StartRunConfig,
     runCallback?: ChatModelAdapter["run"],
   ): Promise<void> {
     this.ensureInitialized();
+    if (this.voice)
+      throw new Error("Cannot start a run while a voice session is connected");
+    if (this._isVoiceMessage(sourceId))
+      throw new Error("Voice transcript messages cannot be reloaded");
 
     // add assistant message
     const id = generateId();
@@ -519,6 +580,8 @@ export class LocalThreadRuntimeCore
     runConfig: RunConfig | undefined,
     runCallback?: ChatModelAdapter["run"],
   ): Promise<void> {
+    if (this.voice)
+      throw new Error("Cannot start a run while a voice session is connected");
     this._notifyEventSubscribers("runStart", {});
 
     // A run entered on a requires-action message resumes a pause an
@@ -845,7 +908,12 @@ export class LocalThreadRuntimeCore
     result,
     isError,
     artifact,
+    modelContent,
   }: AddToolResultOptions) {
+    if (this.voice)
+      throw new Error(
+        "Cannot add a tool result while a voice session is connected",
+      );
     const messageData = this.repository.getMessage(messageId);
     const { parentId } = messageData;
     let { message } = messageData;
@@ -860,11 +928,14 @@ export class LocalThreadRuntimeCore
       if (c.toolCallId !== toolCallId) return c;
       found = true;
       if (c.result === undefined) added = true;
+      // artifact and modelContent are optional; only override when supplied so
+      // a later result that omits them does not clobber a stored value.
       return {
         ...c,
         result,
-        artifact,
         isError,
+        ...(artifact !== undefined && { artifact }),
+        ...(modelContent !== undefined && { modelContent }),
       };
     });
 
@@ -903,6 +974,10 @@ export class LocalThreadRuntimeCore
     text,
     reason,
   }: RespondToToolApprovalOptions): Promise<void> {
+    if (this.voice)
+      throw new Error(
+        "Cannot respond to a tool approval while a voice session is connected",
+      );
     let message = this.repository
       .getMessages()
       .findLast(
@@ -961,6 +1036,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