@assistant-ui/core 0.3.18 → 0.3.20

package/src/runtime/base/base-thread-runtime-core.test.ts

@@ -1,7 +1,10 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
+import type { FeedbackAdapter } from "../../adapters/feedback";
+import type { SpeechSynthesisAdapter } from "../../adapters/speech";
 import type { RealtimeVoiceAdapter } from "../../adapters/voice";
 import type { ModelContextProvider } from "../../model-context/types";
-import type { AppendMessage } from "../../types/message";
+import type { AppendMessage, ThreadMessage } from "../../types/message";
+import type { ChatModelRunResult } from "../../runtime/utils/chat-model-adapter";
 import { CompositeContextProvider } from "../../utils/composite-context-provider";
 import type {
   AddToolResultOptions,
@@ -13,9 +16,13 @@ import type {
   ThreadSuggestion,
 } from "../interfaces/thread-runtime-core";
 import { BaseThreadRuntimeCore } from "./base-thread-runtime-core";
+import { LocalRuntimeCore } from "../../runtimes/local/local-runtime-core";
 
 const createVoiceAdapter = () => {
   let volumeCallback: ((volume: number) => void) | undefined;
+  let statusCallback:
+    | ((status: RealtimeVoiceAdapter.Status) => void)
+    | undefined;
   let transcriptCallback:
     | ((transcript: RealtimeVoiceAdapter.TranscriptItem) => void)
     | undefined;
@@ -25,7 +32,12 @@ const createVoiceAdapter = () => {
     disconnect: vi.fn(),
     mute: vi.fn(),
     unmute: vi.fn(),
-    onStatusChange: () => () => {},
+    onStatusChange: (callback) => {
+      statusCallback = callback;
+      return () => {
+        statusCallback = undefined;
+      };
+    },
     onTranscript: (callback) => {
       transcriptCallback = callback;
       return () => {
@@ -44,12 +56,15 @@ const createVoiceAdapter = () => {
   return {
     adapter: { connect: () => session },
     emitVolume: (volume: number) => volumeCallback?.(volume),
+    emitStatus: (status: RealtimeVoiceAdapter.Status) =>
+      statusCallback?.(status),
     emitTranscript: (transcript: RealtimeVoiceAdapter.TranscriptItem) =>
       transcriptCallback?.(transcript),
     session,
   } satisfies {
     adapter: RealtimeVoiceAdapter;
     emitVolume: (volume: number) => void;
+    emitStatus: (status: RealtimeVoiceAdapter.Status) => void;
     emitTranscript: (transcript: RealtimeVoiceAdapter.TranscriptItem) => void;
     session: RealtimeVoiceAdapter.Session;
   };
@@ -57,17 +72,26 @@ const createVoiceAdapter = () => {
 
 class TestRuntime extends BaseThreadRuntimeCore {
   private readonly voiceAdapter: ReturnType<typeof createVoiceAdapter>;
+  private readonly actionAdapters: {
+    speech?: SpeechSynthesisAdapter;
+    feedback?: FeedbackAdapter;
+  };
 
   constructor(
     voiceAdapter: ReturnType<typeof createVoiceAdapter>,
     contextProvider: ModelContextProvider = { getModelContext: () => ({}) },
+    actionAdapters: {
+      speech?: SpeechSynthesisAdapter;
+      feedback?: FeedbackAdapter;
+    } = {},
   ) {
     super(contextProvider);
     this.voiceAdapter = voiceAdapter;
+    this.actionAdapters = actionAdapters;
   }
 
   get adapters() {
-    return { voice: this.voiceAdapter.adapter };
+    return { voice: this.voiceAdapter.adapter, ...this.actionAdapters };
   }
 
   get isDisabled() {
@@ -128,6 +152,476 @@ afterEach(() => {
   vi.restoreAllMocks();
 });
 
+describe("BaseThreadRuntimeCore speech lifecycle", () => {
+  const createUtterance = () => {
+    let notify = () => {};
+    const unsubscribe = vi.fn();
+    const utterance: SpeechSynthesisAdapter.Utterance = {
+      status: { type: "running" },
+      cancel: vi.fn(),
+      subscribe: (callback) => {
+        notify = callback;
+        return unsubscribe;
+      },
+    };
+    return { utterance, unsubscribe, notify: () => notify() };
+  };
+
+  const createThread = (speech: SpeechSynthesisAdapter) => {
+    const runtime = new LocalRuntimeCore(
+      {
+        adapters: {
+          chatModel: {
+            async run() {
+              return {};
+            },
+          },
+          speech,
+        },
+      },
+      undefined,
+    );
+    const thread = runtime.threads.getMainThreadRuntimeCore();
+    thread.reset([
+      {
+        id: "first",
+        role: "assistant",
+        content: [{ type: "text", text: "Hello" }],
+      },
+      {
+        id: "second",
+        role: "assistant",
+        content: [{ type: "text", text: "Again" }],
+      },
+    ]);
+    return thread;
+  };
+
+  it("releases a session that completes during subscription", () => {
+    const { utterance, unsubscribe } = createUtterance();
+    utterance.subscribe = (callback) => {
+      utterance.status = { type: "ended", reason: "finished" };
+      callback();
+      return unsubscribe;
+    };
+    const thread = createThread({ speak: () => utterance });
+
+    thread.speak("first");
+
+    expect(thread.speech).toBeUndefined();
+    expect(unsubscribe).toHaveBeenCalledOnce();
+    expect(utterance.cancel).not.toHaveBeenCalled();
+    expect(() => thread.stopSpeaking()).toThrow("No message is being spoken");
+  });
+
+  it("does not install an already-ended utterance", () => {
+    const { utterance, unsubscribe } = createUtterance();
+    utterance.status = { type: "ended", reason: "finished" };
+    const thread = createThread({ speak: () => utterance });
+
+    thread.speak("first");
+
+    expect(thread.speech).toBeUndefined();
+    expect(unsubscribe).toHaveBeenCalledOnce();
+  });
+
+  it.each(["finished", "error", "cancelled"] as const)(
+    "releases the listener after %s completion",
+    (reason) => {
+      const { utterance, unsubscribe, notify } = createUtterance();
+      const thread = createThread({ speak: () => utterance });
+      thread.speak("first");
+      const subscriber = vi.fn();
+      thread.subscribe(subscriber);
+
+      utterance.status = { type: "ended", reason };
+      notify();
+      notify();
+
+      expect(thread.speech).toBeUndefined();
+      expect(unsubscribe).toHaveBeenCalledOnce();
+      expect(subscriber).toHaveBeenCalledOnce();
+      expect(utterance.cancel).not.toHaveBeenCalled();
+    },
+  );
+
+  it("ignores old running and ended callbacks after replacement", () => {
+    const first = createUtterance();
+    const second = createUtterance();
+    const speak = vi
+      .fn()
+      .mockReturnValueOnce(first.utterance)
+      .mockReturnValueOnce(second.utterance);
+    const thread = createThread({ speak });
+    thread.speak("first");
+    thread.speak("second");
+    const subscriber = vi.fn();
+    thread.subscribe(subscriber);
+
+    first.notify();
+    first.utterance.status = { type: "ended", reason: "cancelled" };
+    first.notify();
+
+    expect(thread.speech).toEqual({
+      messageId: "second",
+      status: { type: "running" },
+    });
+    expect(subscriber).not.toHaveBeenCalled();
+    expect(first.utterance.cancel).toHaveBeenCalledOnce();
+    expect(first.unsubscribe).toHaveBeenCalledOnce();
+    thread.stopSpeaking();
+    expect(second.utterance.cancel).toHaveBeenCalledOnce();
+    expect(second.unsubscribe).toHaveBeenCalledOnce();
+  });
+
+  it("clears state before synchronous cancellation callbacks", () => {
+    const { utterance, unsubscribe, notify } = createUtterance();
+    utterance.cancel = vi.fn(() => {
+      utterance.status = { type: "ended", reason: "cancelled" };
+      notify();
+    });
+    const thread = createThread({ speak: () => utterance });
+    thread.speak("first");
+    const subscriber = vi.fn();
+    thread.subscribe(subscriber);
+
+    thread.stopSpeaking();
+
+    expect(thread.speech).toBeUndefined();
+    expect(utterance.cancel).toHaveBeenCalledOnce();
+    expect(unsubscribe).toHaveBeenCalledOnce();
+    expect(subscriber).toHaveBeenCalledOnce();
+  });
+
+  it.each(["cancellation", "unsubscribe"] as const)(
+    "notifies stopped state when %s throws",
+    (failure) => {
+      const { utterance, unsubscribe } = createUtterance();
+      const error = new Error("cleanup failed");
+      const thread = createThread({ speak: () => utterance });
+      thread.speak("first");
+      let observedSpeech = thread.speech;
+      const subscriber = vi.fn(() => {
+        observedSpeech = thread.speech;
+      });
+      thread.subscribe(subscriber);
+      if (failure === "cancellation") {
+        utterance.cancel = vi.fn(() => {
+          throw error;
+        });
+      } else {
+        unsubscribe.mockImplementation(() => {
+          throw error;
+        });
+      }
+
+      expect(() => thread.stopSpeaking()).toThrow(error);
+
+      expect(observedSpeech).toBeUndefined();
+      expect(thread.speech).toBeUndefined();
+      expect(subscriber).toHaveBeenCalledOnce();
+      expect(unsubscribe).toHaveBeenCalledOnce();
+      expect(utterance.cancel).toHaveBeenCalledOnce();
+      expect(() => thread.stopSpeaking()).toThrow("No message is being spoken");
+      expect(subscriber).toHaveBeenCalledOnce();
+    },
+  );
+
+  it("reports stop and notification failures after notifying later subscribers", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const { utterance } = createUtterance();
+    const cleanupError = new Error("cleanup failed");
+    const notificationError = new Error("notification failed");
+    utterance.cancel = vi.fn(() => {
+      throw cleanupError;
+    });
+    const thread = createThread({ speak: () => utterance });
+    thread.speak("first");
+    thread.subscribe(() => {
+      throw notificationError;
+    });
+    const laterSubscriber = vi.fn();
+    thread.subscribe(laterSubscriber);
+
+    expect(() => thread.stopSpeaking()).toThrow(
+      expect.objectContaining({
+        errors: [cleanupError, notificationError],
+      }),
+    );
+
+    expect(thread.speech).toBeUndefined();
+    expect(laterSubscriber).toHaveBeenCalledOnce();
+  });
+
+  it("notifies completed state even when terminal unsubscribe throws", () => {
+    const { utterance, unsubscribe, notify } = createUtterance();
+    const error = new Error("unsubscribe failed");
+    unsubscribe.mockImplementation(() => {
+      throw error;
+    });
+    const thread = createThread({ speak: () => utterance });
+    thread.speak("first");
+    let observedSpeech = thread.speech;
+    const subscriber = vi.fn(() => {
+      observedSpeech = thread.speech;
+    });
+    thread.subscribe(subscriber);
+    utterance.status = { type: "ended", reason: "finished" };
+
+    expect(notify).toThrow(error);
+
+    expect(observedSpeech).toBeUndefined();
+    expect(subscriber).toHaveBeenCalledOnce();
+    expect(unsubscribe).toHaveBeenCalledOnce();
+    expect(utterance.cancel).not.toHaveBeenCalled();
+    expect(notify).not.toThrow();
+    expect(subscriber).toHaveBeenCalledOnce();
+  });
+
+  it("cancels playback if a subscriber throws during initial state publication", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const { utterance, unsubscribe } = createUtterance();
+    const error = new Error("subscriber failed");
+    const thread = createThread({ speak: () => utterance });
+    thread.subscribe(() => {
+      throw error;
+    });
+
+    expect(() => thread.speak("first")).toThrow(error);
+
+    expect(thread.speech).toBeUndefined();
+    expect(unsubscribe).toHaveBeenCalledOnce();
+    expect(utterance.cancel).toHaveBeenCalledOnce();
+    expect(() => thread.stopSpeaking()).toThrow("No message is being spoken");
+  });
+
+  it("cancels a session when subscribing throws", () => {
+    const { utterance } = createUtterance();
+    const error = new Error("subscription failed");
+    utterance.subscribe = () => {
+      throw error;
+    };
+    const thread = createThread({ speak: () => utterance });
+
+    expect(() => thread.speak("first")).toThrow(error);
+    expect(thread.speech).toBeUndefined();
+    expect(utterance.cancel).toHaveBeenCalledOnce();
+    expect(() => thread.stopSpeaking()).toThrow("No message is being spoken");
+  });
+
+  it("notifies observers when replacement subscription fails", () => {
+    const first = createUtterance();
+    const second = createUtterance();
+    const error = new Error("subscription failed");
+    second.utterance.subscribe = () => {
+      throw error;
+    };
+    const thread = createThread({
+      speak: vi
+        .fn()
+        .mockReturnValueOnce(first.utterance)
+        .mockReturnValueOnce(second.utterance),
+    });
+    thread.speak("first");
+    let observedSpeech = thread.speech;
+    const subscriber = vi.fn(() => {
+      observedSpeech = thread.speech;
+    });
+    thread.subscribe(subscriber);
+
+    expect(() => thread.speak("second")).toThrow(error);
+
+    expect(observedSpeech).toBeUndefined();
+    expect(subscriber).toHaveBeenCalledOnce();
+    expect(second.utterance.cancel).toHaveBeenCalledOnce();
+  });
+
+  it.each(["creation", "cancellation", "unsubscribe"] as const)(
+    "notifies observers when replacement fails during %s",
+    (failure) => {
+      const first = createUtterance();
+      const error = new Error("replacement failed");
+      const speak = vi
+        .fn()
+        .mockReturnValueOnce(first.utterance)
+        .mockImplementationOnce(() => {
+          throw error;
+        });
+      const thread = createThread({ speak });
+      thread.speak("first");
+      let observedSpeech = thread.speech;
+      const subscriber = vi.fn(() => {
+        observedSpeech = thread.speech;
+      });
+      thread.subscribe(subscriber);
+      if (failure === "cancellation") {
+        first.utterance.cancel = vi.fn(() => {
+          throw error;
+        });
+      } else if (failure === "unsubscribe") {
+        first.unsubscribe.mockImplementation(() => {
+          throw error;
+        });
+      }
+
+      expect(() => thread.speak("second")).toThrow(error);
+
+      expect(observedSpeech).toBeUndefined();
+      expect(thread.speech).toBeUndefined();
+      expect(subscriber).toHaveBeenCalledOnce();
+      expect(first.unsubscribe).toHaveBeenCalledOnce();
+      expect(first.utterance.cancel).toHaveBeenCalledOnce();
+      expect(speak).toHaveBeenCalledTimes(failure === "creation" ? 2 : 1);
+    },
+  );
+
+  it("preserves a creation error when rollback notification throws", () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const first = createUtterance();
+    const creationError = new Error("creation failed");
+    const notificationError = new Error("notification failed");
+    const thread = createThread({
+      speak: vi
+        .fn()
+        .mockReturnValueOnce(first.utterance)
+        .mockImplementationOnce(() => {
+          throw creationError;
+        }),
+    });
+    thread.speak("first");
+    thread.subscribe(() => {
+      throw notificationError;
+    });
+    const laterSubscriber = vi.fn();
+    thread.subscribe(laterSubscriber);
+
+    expect(() => thread.speak("second")).toThrow(creationError);
+
+    expect(thread.speech).toBeUndefined();
+    expect(laterSubscriber).toHaveBeenCalledOnce();
+    expect(consoleError).toHaveBeenCalledWith(
+      "[assistant-ui] Speech rollback notification threw",
+      notificationError,
+    );
+  });
+
+  it("does not notify when initial utterance creation fails", () => {
+    const error = new Error("creation failed");
+    const thread = createThread({
+      speak: () => {
+        throw error;
+      },
+    });
+    const subscriber = vi.fn();
+    thread.subscribe(subscriber);
+
+    expect(() => thread.speak("first")).toThrow(error);
+
+    expect(thread.speech).toBeUndefined();
+    expect(subscriber).not.toHaveBeenCalled();
+  });
+
+  it("preserves reentrant speech when the outer creation throws", () => {
+    const first = createUtterance();
+    const replacement = createUtterance();
+    const error = new Error("outer creation failed");
+    const speak = vi.fn().mockReturnValue(first.utterance);
+    const thread = createThread({ speak });
+    thread.speak("first");
+    speak
+      .mockImplementationOnce(() => {
+        thread.speak("second");
+        throw error;
+      })
+      .mockReturnValueOnce(replacement.utterance);
+    const subscriber = vi.fn();
+    thread.subscribe(subscriber);
+
+    expect(() => thread.speak("second")).toThrow(error);
+
+    expect(thread.speech?.messageId).toBe("second");
+    expect(replacement.utterance.cancel).not.toHaveBeenCalled();
+    expect(subscriber).toHaveBeenCalledOnce();
+    thread.stopSpeaking();
+    expect(replacement.unsubscribe).toHaveBeenCalledOnce();
+  });
+
+  it("preserves the setup error when rollback cancellation throws", () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const { utterance } = createUtterance();
+    const setupError = new Error("subscription failed");
+    const cleanupError = new Error("cancellation failed");
+    utterance.subscribe = () => {
+      throw setupError;
+    };
+    utterance.cancel = vi.fn(() => {
+      throw cleanupError;
+    });
+    const thread = createThread({ speak: () => utterance });
+    const subscriber = vi.fn();
+    thread.subscribe(subscriber);
+
+    expect(() => thread.speak("first")).toThrow(setupError);
+
+    expect(thread.speech).toBeUndefined();
+    expect(subscriber).toHaveBeenCalledOnce();
+    expect(consoleError).toHaveBeenCalledWith(
+      "[assistant-ui] Speech rollback cleanup threw",
+      cleanupError,
+    );
+  });
+
+  it("does not notify twice when subscription completes before throwing", () => {
+    const { utterance } = createUtterance();
+    const error = new Error("subscription failed");
+    utterance.subscribe = (callback) => {
+      utterance.status = { type: "ended", reason: "finished" };
+      callback();
+      throw error;
+    };
+    const thread = createThread({ speak: () => utterance });
+    const subscriber = vi.fn();
+    thread.subscribe(subscriber);
+
+    expect(() => thread.speak("first")).toThrow(error);
+
+    expect(thread.speech).toBeUndefined();
+    expect(subscriber).toHaveBeenCalledOnce();
+    expect(utterance.cancel).not.toHaveBeenCalled();
+  });
+
+  it("leaves a reentrant replacement active when the old subscription throws", () => {
+    const first = createUtterance();
+    const second = createUtterance();
+    const thread = createThread({
+      speak: vi
+        .fn()
+        .mockReturnValueOnce(first.utterance)
+        .mockReturnValueOnce(second.utterance),
+    });
+    const error = new Error("old subscription failed");
+    first.utterance.subscribe = () => {
+      thread.speak("second");
+      throw error;
+    };
+    const subscriber = vi.fn();
+    thread.subscribe(subscriber);
+
+    expect(() => thread.speak("first")).toThrow(error);
+
+    expect(thread.speech?.messageId).toBe("second");
+    expect(subscriber).toHaveBeenCalledOnce();
+    expect(first.utterance.cancel).toHaveBeenCalledOnce();
+    expect(second.utterance.cancel).not.toHaveBeenCalled();
+    thread.stopSpeaking();
+    expect(second.unsubscribe).toHaveBeenCalledOnce();
+  });
+});
+
 describe("BaseThreadRuntimeCore subscriptions", () => {
   it("notifies later subscribers when an earlier subscriber throws", () => {
     const runtime = new TestRuntime(createVoiceAdapter());
@@ -231,84 +725,1340 @@ describe("BaseThreadRuntimeCore subscriptions", () => {
 });
 
 describe("BaseThreadRuntimeCore voice volume subscriptions", () => {
-  it("continues notifying subscribers when one throws", () => {
-    const consoleError = vi
-      .spyOn(console, "error")
-      .mockImplementation(() => {});
+  it("finishes disconnecting when a session cleanup throws", () => {
+    const cleanupError = new Error("cleanup failed");
+    const laterCleanup = vi.fn();
     const voice = createVoiceAdapter();
+    voice.session.onStatusChange = () => () => {
+      throw cleanupError;
+    };
+    voice.session.onModeChange = () => laterCleanup;
     const runtime = new TestRuntime(voice);
     runtime.connectVoice();
 
-    const listenerError = new Error("listener failed");
-    const laterListener = vi.fn();
-    runtime.subscribeVoiceVolume(() => {
-      throw listenerError;
-    });
-    runtime.subscribeVoiceVolume(laterListener);
+    expect(() => runtime.disconnectVoice()).toThrow(cleanupError);
+    expect(laterCleanup).toHaveBeenCalledOnce();
+    expect(voice.session.disconnect).toHaveBeenCalledOnce();
+    expect(runtime.voice).toBeUndefined();
+    expect(runtime.getVoiceVolume()).toBe(0);
 
-    expect(() => voice.emitVolume(0.5)).not.toThrow();
-    expect(laterListener).toHaveBeenCalledOnce();
-    expect(runtime.getVoiceVolume()).toBe(0.5);
-    expect(consoleError).toHaveBeenCalledWith(
-      "[assistant-ui] Voice volume listener threw an error",
-      listenerError,
-    );
+    expect(() => runtime.disconnectVoice()).not.toThrow();
+    expect(laterCleanup).toHaveBeenCalledOnce();
+    expect(voice.session.disconnect).toHaveBeenCalledOnce();
   });
 
-  it("continues disconnect cleanup when a subscriber throws", () => {
+  it("reconnects after cleanup from the previous session throws", () => {
     const consoleError = vi
       .spyOn(console, "error")
       .mockImplementation(() => {});
+    const cleanupError = new Error("cleanup failed");
     const voice = createVoiceAdapter();
+    voice.adapter.connect = vi.fn(voice.adapter.connect);
+    voice.session.onStatusChange = () => () => {
+      throw cleanupError;
+    };
     const runtime = new TestRuntime(voice);
     runtime.connectVoice();
 
-    const listenerError = new Error("disconnect listener failed");
-    const laterListener = vi.fn();
-    runtime.subscribeVoiceVolume(() => {
+    expect(() => runtime.connectVoice()).not.toThrow();
+    expect(voice.adapter.connect).toHaveBeenCalledTimes(2);
+    expect(consoleError).toHaveBeenCalledWith(
+      "[assistant-ui] Voice cleanup threw before reconnect",
+      cleanupError,
+    );
+  });
+
+  it("rolls back a new session when initialization throws", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const voice = createVoiceAdapter();
+    const runtime = new TestRuntime(voice);
+    const listenerError = new Error("subscriber failed");
+    runtime.subscribe(() => {
       throw listenerError;
     });
-    runtime.subscribeVoiceVolume(laterListener);
 
-    expect(() => runtime.disconnectVoice()).not.toThrow();
-    expect(laterListener).toHaveBeenCalledOnce();
+    expect(() => runtime.connectVoice()).toThrow(listenerError);
+    expect(voice.session.disconnect).toHaveBeenCalledOnce();
+    expect(runtime.voice).toBeUndefined();
     expect(runtime.getVoiceVolume()).toBe(0);
+  });
+
+  it("releases handlers registered before voice setup throws", () => {
+    const setupError = new Error("registration failed");
+    const statusCleanup = vi.fn();
+    const voice = createVoiceAdapter();
+    voice.session.onStatusChange = () => statusCleanup;
+    voice.session.onModeChange = () => {
+      throw setupError;
+    };
+    const runtime = new TestRuntime(voice);
+
+    expect(() => runtime.connectVoice()).toThrow(setupError);
+    expect(statusCleanup).toHaveBeenCalledOnce();
+    expect(voice.session.disconnect).toHaveBeenCalledOnce();
     expect(runtime.voice).toBeUndefined();
+  });
+
+  it("stops setup when a subscriber disconnects the new session", () => {
+    const voice = createVoiceAdapter();
+    const statusRegistration = vi.spyOn(voice.session, "onStatusChange");
+    const runtime = new TestRuntime(voice);
+    runtime.subscribe(() => {
+      if (runtime.voice) runtime.disconnectVoice();
+    });
+
+    expect(() => runtime.connectVoice()).not.toThrow();
+
     expect(voice.session.disconnect).toHaveBeenCalledOnce();
-    expect(consoleError).toHaveBeenCalledWith(
-      "[assistant-ui] Voice volume listener threw an error",
-      listenerError,
-    );
+    expect(statusRegistration).not.toHaveBeenCalled();
+    expect(runtime.voice).toBeUndefined();
   });
 
-  it("reports rejected subscriber thenables", async () => {
+  it("releases a handler returned after reentrant disconnect", () => {
+    const statusCleanup = vi.fn();
+    const voice = createVoiceAdapter();
+    let registeringStatus = false;
+    voice.session.onStatusChange = (callback) => {
+      registeringStatus = true;
+      callback({ type: "running" });
+      registeringStatus = false;
+      return statusCleanup;
+    };
+    const modeRegistration = vi.spyOn(voice.session, "onModeChange");
+    const runtime = new TestRuntime(voice);
+    runtime.subscribe(() => {
+      if (registeringStatus) {
+        registeringStatus = false;
+        runtime.disconnectVoice();
+      }
+    });
+
+    expect(() => runtime.connectVoice()).not.toThrow();
+
+    expect(statusCleanup).toHaveBeenCalledOnce();
+    expect(modeRegistration).not.toHaveBeenCalled();
+    expect(voice.session.disconnect).toHaveBeenCalledOnce();
+    expect(runtime.voice).toBeUndefined();
+  });
+
+  it("does not release earlier handlers twice after reentrant disconnect", () => {
+    const statusCleanup = vi.fn();
+    const modeCleanup = vi.fn();
+    const voice = createVoiceAdapter();
+    voice.session.onStatusChange = () => statusCleanup;
+    let registeringMode = false;
+    voice.session.onModeChange = (callback) => {
+      registeringMode = true;
+      callback("speaking");
+      registeringMode = false;
+      return modeCleanup;
+    };
+    const volumeRegistration = vi.spyOn(voice.session, "onVolumeChange");
+    const runtime = new TestRuntime(voice);
+    runtime.subscribe(() => {
+      if (registeringMode) {
+        registeringMode = false;
+        runtime.disconnectVoice();
+      }
+    });
+
+    expect(() => runtime.connectVoice()).not.toThrow();
+
+    expect(statusCleanup).toHaveBeenCalledOnce();
+    expect(modeCleanup).toHaveBeenCalledOnce();
+    expect(volumeRegistration).not.toHaveBeenCalled();
+    expect(voice.session.disconnect).toHaveBeenCalledOnce();
+    expect(runtime.voice).toBeUndefined();
+  });
+
+  it("does not disconnect a replacement session after setup throws", () => {
+    const setupError = new Error("registration failed");
+    const firstVoice = createVoiceAdapter();
+    const replacementVoice = createVoiceAdapter();
+    firstVoice.adapter.connect = vi
+      .fn()
+      .mockReturnValueOnce(firstVoice.session)
+      .mockReturnValueOnce(replacementVoice.session);
+    let replacing = false;
+    firstVoice.session.onModeChange = (callback) => {
+      replacing = true;
+      callback("listening");
+      throw setupError;
+    };
+    const runtime = new TestRuntime(firstVoice);
+    runtime.subscribe(() => {
+      if (replacing) {
+        replacing = false;
+        runtime.disconnectVoice();
+        runtime.connectVoice();
+      }
+    });
+
+    expect(() => runtime.connectVoice()).toThrow(setupError);
+
+    expect(firstVoice.session.disconnect).toHaveBeenCalledOnce();
+    expect(replacementVoice.session.disconnect).not.toHaveBeenCalled();
+    expect(runtime.voice).toMatchObject({
+      status: replacementVoice.session.status,
+      isMuted: replacementVoice.session.isMuted,
+      mode: "listening",
+    });
+  });
+
+  it("releases setup handlers without disconnecting a self-ended session", () => {
+    const voice = createVoiceAdapter();
+    const statusCleanup = vi.fn();
+    voice.session.onStatusChange = (callback) => {
+      voice.session.status = { type: "ended", reason: "finished" };
+      callback(voice.session.status);
+      return statusCleanup;
+    };
+    const modeRegistration = vi.spyOn(voice.session, "onModeChange");
+    const runtime = new TestRuntime(voice);
+
+    runtime.connectVoice();
+
+    expect(statusCleanup).toHaveBeenCalledOnce();
+    expect(voice.session.disconnect).not.toHaveBeenCalled();
+    expect(modeRegistration).not.toHaveBeenCalled();
+    expect(runtime.voice).toBeUndefined();
+
+    runtime.disconnectVoice();
+    expect(statusCleanup).toHaveBeenCalledOnce();
+    expect(voice.session.disconnect).not.toHaveBeenCalled();
+  });
+
+  it("releases ended-session handlers when setup notification throws", () => {
+    const listenerError = new Error("ended notification failed");
+    const cleanupError = new Error("status cleanup failed");
     const consoleError = vi
       .spyOn(console, "error")
       .mockImplementation(() => {});
     const voice = createVoiceAdapter();
+    const statusCleanup = vi.fn(() => {
+      throw cleanupError;
+    });
+    let endSession!: () => void;
+    voice.session.onStatusChange = (callback) => {
+      endSession = () => {
+        voice.session.status = { type: "ended", reason: "finished" };
+        callback(voice.session.status);
+      };
+      return statusCleanup;
+    };
+    voice.session.onModeChange = () => {
+      endSession();
+      return () => {};
+    };
     const runtime = new TestRuntime(voice);
-    runtime.connectVoice();
-
-    const listenerError = new Error("async listener failed");
-    const laterListener = vi.fn();
-    runtime.subscribeVoiceVolume(async () => {
-      throw listenerError;
+    let wasConnected = false;
+    runtime.subscribe(() => {
+      if (runtime.voice) wasConnected = true;
+      else if (wasConnected) throw listenerError;
     });
-    runtime.subscribeVoiceVolume(laterListener);
 
-    voice.emitVolume(0.5);
+    expect(() => runtime.connectVoice()).toThrow(listenerError);
 
-    await vi.waitFor(() => {
-      expect(laterListener).toHaveBeenCalledOnce();
-      expect(consoleError).toHaveBeenCalledWith(
-        "[assistant-ui] Voice volume listener threw an error",
-        listenerError,
-      );
-    });
+    expect(statusCleanup).toHaveBeenCalledOnce();
+    expect(voice.session.disconnect).not.toHaveBeenCalled();
+    expect(runtime.voice).toBeUndefined();
+    expect(consoleError).toHaveBeenCalledWith(
+      "[assistant-ui] Detached voice setup cleanup threw",
+      cleanupError,
+    );
+  });
+
+  it("does not disconnect a session that ends after setup", () => {
+    const voice = createVoiceAdapter();
+    const statusCleanup = vi.fn();
+    let endSession!: () => void;
+    voice.session.onStatusChange = (callback) => {
+      endSession = () => {
+        voice.session.status = { type: "ended", reason: "finished" };
+        callback(voice.session.status);
+      };
+      return statusCleanup;
+    };
+    const runtime = new TestRuntime(voice);
+    runtime.connectVoice();
+    endSession();
+    expect(runtime.voice).toBeUndefined();
+
+    runtime.disconnectVoice();
+
+    expect(statusCleanup).toHaveBeenCalledOnce();
+    expect(voice.session.disconnect).not.toHaveBeenCalled();
+  });
+
+  it("rethrows one subscriber error once while disconnecting", () => {
+    const voice = createVoiceAdapter();
+    const runtime = new TestRuntime(voice);
+    runtime.connectVoice();
+    voice.emitTranscript({ role: "assistant", text: "Partial" });
+    const listenerError = new Error("subscriber failed");
+    runtime.subscribe(() => {
+      throw listenerError;
+    });
+
+    let thrown: unknown;
+    try {
+      runtime.disconnectVoice();
+    } catch (error) {
+      thrown = error;
+    }
+
+    expect(thrown).toBe(listenerError);
+    expect(voice.session.disconnect).toHaveBeenCalledOnce();
+  });
+
+  it("continues notifying subscribers when one throws", () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const voice = createVoiceAdapter();
+    const runtime = new TestRuntime(voice);
+    runtime.connectVoice();
+
+    const listenerError = new Error("listener failed");
+    const laterListener = vi.fn();
+    runtime.subscribeVoiceVolume(() => {
+      throw listenerError;
+    });
+    runtime.subscribeVoiceVolume(laterListener);
+
+    expect(() => voice.emitVolume(0.5)).not.toThrow();
+    expect(laterListener).toHaveBeenCalledOnce();
+    expect(runtime.getVoiceVolume()).toBe(0.5);
+    expect(consoleError).toHaveBeenCalledWith(
+      "[assistant-ui] Voice volume listener threw an error",
+      listenerError,
+    );
+  });
+
+  it("continues disconnect cleanup when a subscriber throws", () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const voice = createVoiceAdapter();
+    const runtime = new TestRuntime(voice);
+    runtime.connectVoice();
+
+    const listenerError = new Error("disconnect listener failed");
+    const laterListener = vi.fn();
+    runtime.subscribeVoiceVolume(() => {
+      throw listenerError;
+    });
+    runtime.subscribeVoiceVolume(laterListener);
+
+    expect(() => runtime.disconnectVoice()).not.toThrow();
+    expect(laterListener).toHaveBeenCalledOnce();
+    expect(runtime.getVoiceVolume()).toBe(0);
+    expect(runtime.voice).toBeUndefined();
+    expect(voice.session.disconnect).toHaveBeenCalledOnce();
+    expect(consoleError).toHaveBeenCalledWith(
+      "[assistant-ui] Voice volume listener threw an error",
+      listenerError,
+    );
+  });
+
+  it("reports rejected subscriber thenables", async () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const voice = createVoiceAdapter();
+    const runtime = new TestRuntime(voice);
+    runtime.connectVoice();
+
+    const listenerError = new Error("async listener failed");
+    const laterListener = vi.fn();
+    runtime.subscribeVoiceVolume(async () => {
+      throw listenerError;
+    });
+    runtime.subscribeVoiceVolume(laterListener);
+
+    voice.emitVolume(0.5);
+
+    await vi.waitFor(() => {
+      expect(laterListener).toHaveBeenCalledOnce();
+      expect(consoleError).toHaveBeenCalledWith(
+        "[assistant-ui] Voice volume listener threw an error",
+        listenerError,
+      );
+    });
+  });
+});
+
+describe("BaseThreadRuntimeCore voice transcripts", () => {
+  const createLocalVoiceThread = async () => {
+    const voiceAdapter = createVoiceAdapter();
+    const history = {
+      load: vi.fn(async () => ({ messages: [] })),
+      append: vi.fn(async () => {}),
+    };
+    const runtime = new LocalRuntimeCore(
+      {
+        adapters: {
+          chatModel: {
+            async run() {
+              return {};
+            },
+          },
+          history,
+          voice: voiceAdapter.adapter,
+        },
+      },
+      undefined,
+    );
+    const thread = runtime.threads.getMainThreadRuntimeCore();
+    await thread.__internal_load();
+    thread.connectVoice();
+    return { history, thread, voiceAdapter };
+  };
+
+  it("holds a queued send that becomes dispatchable while a voice session is connected", async () => {
+    let resolveFirst!: (result: ChatModelRunResult) => void;
+    const firstRun = new Promise<ChatModelRunResult>((resolve) => {
+      resolveFirst = resolve;
+    });
+    let runCount = 0;
+    const run = vi.fn(() =>
+      ++runCount === 1 ? firstRun : Promise.resolve({}),
+    );
+    const voiceAdapter = createVoiceAdapter();
+    const runtime = new LocalRuntimeCore(
+      {
+        unstable_enableMessageQueue: true,
+        adapters: { chatModel: { run }, voice: voiceAdapter.adapter },
+      },
+      undefined,
+    );
+    const thread = runtime.threads.getMainThreadRuntimeCore();
+    const firstMessage: AppendMessage = {
+      parentId: null,
+      sourceId: null,
+      runConfig: {},
+      role: "user",
+      content: [{ type: "text", text: "first" }],
+      attachments: [],
+      metadata: { custom: {} },
+      createdAt: new Date(),
+    };
+
+    await thread.append(firstMessage);
+    expect(run).toHaveBeenCalledOnce();
+    await thread.append({
+      ...firstMessage,
+      parentId: thread.messages.at(-1)?.id ?? null,
+      content: [{ type: "text", text: "second" }],
+      steer: false,
+    });
+
+    const deferred: Array<() => void> = [];
+    const originalQueueMicrotask = globalThis.queueMicrotask;
+    globalThis.queueMicrotask = (callback: () => void) => {
+      deferred.push(callback);
+    };
+    try {
+      resolveFirst({});
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    } finally {
+      globalThis.queueMicrotask = originalQueueMicrotask;
+    }
+    expect(thread.messages.at(-1)?.status?.type).toBe("complete");
+
+    thread.connectVoice();
+    try {
+      for (const callback of deferred) callback();
+      await Promise.resolve();
+      expect(run).toHaveBeenCalledOnce();
+      expect(thread.getQueueItems()).toHaveLength(1);
+    } finally {
+      thread.disconnectVoice();
+    }
+    await Promise.resolve();
+
+    expect(run).toHaveBeenCalledTimes(2);
+    expect(thread.getQueueItems()).toHaveLength(0);
+  });
+
+  it("commits a final user transcript to the repository and history", async () => {
+    const { history, thread, voiceAdapter } = await createLocalVoiceThread();
+
+    try {
+      voiceAdapter.emitTranscript({
+        role: "user",
+        text: "Hello",
+        isFinal: true,
+      });
+      const message = thread.messages[0]!;
+
+      expect(message.metadata.modality).toBe("voice");
+      expect(history.append).toHaveBeenCalledExactlyOnceWith({
+        parentId: null,
+        message,
+      });
+      expect(thread.export().messages).toContainEqual({
+        parentId: null,
+        message,
+      });
+    } finally {
+      thread.disconnectVoice();
+    }
+  });
+
+  it("commits an assistant transcript when it finalizes", async () => {
+    const { history, thread, voiceAdapter } = await createLocalVoiceThread();
+
+    try {
+      voiceAdapter.emitTranscript({ role: "assistant", text: "Partial" });
+
+      expect(thread.messages[0]?.status).toEqual({ type: "running" });
+      expect(history.append).not.toHaveBeenCalled();
+
+      voiceAdapter.emitTranscript({
+        role: "assistant",
+        text: "Complete",
+        isFinal: true,
+      });
+      const message = thread.messages[0]!;
+
+      expect(message.status).toEqual({ type: "complete", reason: "stop" });
+      expect(history.append).toHaveBeenCalledExactlyOnceWith({
+        parentId: null,
+        message,
+      });
+    } finally {
+      thread.disconnectVoice();
+    }
+  });
+
+  it("commits an in-flight assistant transcript when disconnecting", async () => {
+    const { history, thread, voiceAdapter } = await createLocalVoiceThread();
+
+    voiceAdapter.emitTranscript({ role: "assistant", text: "Partial" });
+    thread.disconnectVoice();
+    const message = thread.messages[0]!;
+
+    expect(message.status).toEqual({ type: "complete", reason: "stop" });
+    expect(history.append).toHaveBeenCalledExactlyOnceWith({
+      parentId: null,
+      message,
+    });
+  });
+
+  it("keeps committed transcripts after disconnect", async () => {
+    const { thread, voiceAdapter } = await createLocalVoiceThread();
+
+    voiceAdapter.emitTranscript({
+      role: "user",
+      text: "Hello",
+      isFinal: true,
+    });
+    const message = thread.messages[0]!;
+
+    thread.disconnectVoice();
+
+    expect(thread.messages).toEqual([message]);
+  });
+
+  it("links the second transcript to the first", async () => {
+    const { thread, voiceAdapter } = await createLocalVoiceThread();
+
+    try {
+      voiceAdapter.emitTranscript({
+        role: "user",
+        text: "First",
+        isFinal: true,
+      });
+      const first = thread.messages[0]!;
+      voiceAdapter.emitTranscript({
+        role: "user",
+        text: "Second",
+        isFinal: true,
+      });
+      const second = thread.messages[1]!;
+
+      expect(thread.export().messages).toContainEqual({
+        parentId: first.id,
+        message: second,
+      });
+    } finally {
+      thread.disconnectVoice();
+    }
+  });
+
+  it("rejects a text send while a session is connected", async () => {
+    const { thread, voiceAdapter } = await createLocalVoiceThread();
+
+    voiceAdapter.emitTranscript({
+      role: "user",
+      text: "Voice message",
+      isFinal: true,
+    });
+    const transcript = thread.messages[0]!;
+    const message: AppendMessage = {
+      parentId: transcript.id,
+      sourceId: null,
+      role: "user",
+      content: [{ type: "text", text: "Text message" }],
+      attachments: [],
+      metadata: { custom: {} },
+      createdAt: new Date(),
+      runConfig: {},
+      startRun: false,
+    };
+
+    await expect(thread.append(message)).rejects.toThrow(
+      "Cannot send a text message while a voice session is connected",
+    );
+    expect(thread.export().messages).toHaveLength(1);
+
+    thread.disconnectVoice();
+
+    await expect(thread.append(message)).resolves.toBeUndefined();
+    expect(thread.export().messages).toContainEqual({
+      parentId: transcript.id,
+      message: expect.objectContaining({ role: "user" }),
+    });
+  });
+
+  it("keeps the replacement session's hooks when a subscriber reconnects during disconnect", () => {
+    class HookRuntime extends TestRuntime {
+      connected = 0;
+      disconnected = 0;
+      protected override _onVoiceConnected() {
+        this.connected += 1;
+      }
+      protected override _onVoiceDisconnected() {
+        this.disconnected += 1;
+      }
+    }
+    const runtime = new HookRuntime(createVoiceAdapter());
+    runtime.connectVoice();
+    expect(runtime.connected).toBe(1);
+
+    let reconnected = false;
+    const unsubscribe = runtime.subscribe(() => {
+      if (reconnected || runtime.voice !== undefined) return;
+      reconnected = true;
+      runtime.connectVoice();
+    });
+
+    try {
+      runtime.disconnectVoice();
+      expect(runtime.voice).toBeDefined();
+      expect(runtime.connected).toBe(2);
+      expect(runtime.disconnected).toBe(0);
+    } finally {
+      unsubscribe();
+      runtime.disconnectVoice();
+    }
+    expect(runtime.disconnected).toBe(1);
+  });
+
+  it("keeps voice hooks held while replacing a session", () => {
+    class HookRuntime extends TestRuntime {
+      connected = 0;
+      disconnected = 0;
+      protected override _onVoiceConnected() {
+        this.connected += 1;
+      }
+      protected override _onVoiceDisconnected() {
+        this.disconnected += 1;
+      }
+    }
+    const runtime = new HookRuntime(createVoiceAdapter());
+
+    runtime.connectVoice();
+    runtime.connectVoice();
+
+    expect(runtime.connected).toBe(2);
+    expect(runtime.disconnected).toBe(0);
+
+    runtime.disconnectVoice();
+
+    expect(runtime.disconnected).toBe(1);
+  });
+
+  it("ignores an ended status from a replaced session", () => {
+    class HookRuntime extends TestRuntime {
+      disconnected = 0;
+      protected override _onVoiceDisconnected() {
+        this.disconnected += 1;
+      }
+    }
+    const statusCallbacks: Array<
+      (status: RealtimeVoiceAdapter.Status) => void
+    > = [];
+    const createSession = (): RealtimeVoiceAdapter.Session => ({
+      status: { type: "running" },
+      isMuted: false,
+      disconnect: vi.fn(),
+      mute: vi.fn(),
+      unmute: vi.fn(),
+      onStatusChange: (callback) => {
+        statusCallbacks.push(callback);
+        return () => {};
+      },
+      onTranscript: () => () => {},
+      onModeChange: () => () => {},
+      onVolumeChange: () => () => {},
+    });
+    const runtime = new HookRuntime({
+      adapter: { connect: () => createSession() },
+      emitVolume: () => {},
+      emitStatus: () => {},
+      emitTranscript: () => {},
+      session: createSession(),
+    });
+
+    runtime.connectVoice();
+    runtime.connectVoice();
+    statusCallbacks[0]!({ type: "ended", reason: "finished" });
+
+    try {
+      expect(runtime.voice).toBeDefined();
+      expect(runtime.disconnected).toBe(0);
+    } finally {
+      runtime.disconnectVoice();
+    }
+    expect(runtime.disconnected).toBe(1);
+  });
+
+  it("releases voice hooks when a replacement cannot connect", () => {
+    class HookRuntime extends TestRuntime {
+      connected = 0;
+      disconnected = 0;
+      protected override _onVoiceConnected() {
+        this.connected += 1;
+      }
+      protected override _onVoiceDisconnected() {
+        this.disconnected += 1;
+      }
+    }
+    const voice = createVoiceAdapter();
+    const error = new Error("connection failed");
+    voice.adapter.connect = vi
+      .fn()
+      .mockReturnValueOnce(voice.session)
+      .mockImplementationOnce(() => {
+        throw error;
+      });
+    const runtime = new HookRuntime(voice);
+    runtime.connectVoice();
+
+    expect(() => runtime.connectVoice()).toThrow(error);
+    expect(runtime.connected).toBe(1);
+    expect(runtime.disconnected).toBe(1);
+  });
+
+  it("rejects starting a voice session while a run is in progress", async () => {
+    const voiceAdapter = createVoiceAdapter();
+    let resolveRun!: (result: ChatModelRunResult) => void;
+    const firstRun = new Promise<ChatModelRunResult>((resolve) => {
+      resolveRun = resolve;
+    });
+    const run = vi.fn(() => firstRun);
+    const runtime = new LocalRuntimeCore(
+      { adapters: { chatModel: { run }, voice: voiceAdapter.adapter } },
+      undefined,
+    );
+    const thread = runtime.threads.getMainThreadRuntimeCore();
+    const pending = thread.append({
+      parentId: null,
+      sourceId: null,
+      role: "user",
+      content: [{ type: "text", text: "hello" }],
+      attachments: [],
+      metadata: { custom: {} },
+      createdAt: new Date(),
+      runConfig: {},
+    });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(run).toHaveBeenCalledOnce();
+
+    expect(() => thread.connectVoice()).toThrow(
+      "Cannot start a voice session while a run is in progress or paused on a pending tool action",
+    );
+    expect(thread.voice).toBeUndefined();
+
+    resolveRun({});
+    await pending;
+
+    thread.connectVoice();
+    try {
+      expect(thread.voice).toBeDefined();
+    } finally {
+      thread.disconnectVoice();
+    }
+  });
+
+  it("rejects starting a voice session while a run is paused on a tool action", () => {
+    const voiceAdapter = createVoiceAdapter();
+    const runtime = new LocalRuntimeCore(
+      {
+        adapters: {
+          chatModel: {
+            async run() {
+              return {};
+            },
+          },
+          voice: voiceAdapter.adapter,
+        },
+      },
+      undefined,
+    );
+    const thread = runtime.threads.getMainThreadRuntimeCore();
+    thread.reset([
+      {
+        id: "user",
+        role: "user",
+        content: [{ type: "text", text: "Use the tool" }],
+      },
+      {
+        id: "assistant",
+        role: "assistant",
+        content: [
+          {
+            type: "tool-call",
+            toolCallId: "tool-call",
+            toolName: "tool",
+            args: {},
+            argsText: "{}",
+          },
+        ],
+        status: { type: "requires-action", reason: "tool-calls" },
+      },
+    ]);
+
+    expect(() => thread.connectVoice()).toThrow(
+      "Cannot start a voice session while a run is in progress or paused on a pending tool action",
+    );
+    expect(thread.voice).toBeUndefined();
+  });
+
+  it("reloads committed transcripts from history into a fresh runtime", async () => {
+    const items: Array<{ parentId: string | null; message: ThreadMessage }> =
+      [];
+    const history = {
+      load: async () => ({
+        messages: items,
+        headId: items.at(-1)?.message.id ?? null,
+      }),
+      append: async (item: {
+        parentId: string | null;
+        message: ThreadMessage;
+      }) => {
+        items.push(item);
+      },
+    };
+    const chatModel = {
+      async run() {
+        return {};
+      },
+    };
+    const voiceAdapter = createVoiceAdapter();
+    const first = new LocalRuntimeCore(
+      { adapters: { chatModel, history, voice: voiceAdapter.adapter } },
+      undefined,
+    );
+    const thread = first.threads.getMainThreadRuntimeCore();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    thread.connectVoice();
+    voiceAdapter.emitTranscript({ role: "user", text: "Hi", isFinal: true });
+    voiceAdapter.emitTranscript({
+      role: "assistant",
+      text: "Hello",
+      isFinal: true,
+    });
+    thread.disconnectVoice();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(items).toHaveLength(2);
+
+    const second = new LocalRuntimeCore(
+      { adapters: { chatModel, history } },
+      undefined,
+    );
+    const reloaded = second.threads.getMainThreadRuntimeCore();
+    await reloaded.__internal_load();
+
+    expect(reloaded.messages.map((message) => message.role)).toEqual([
+      "user",
+      "assistant",
+    ]);
+    expect(reloaded.messages[1]?.metadata.modality).toBe("voice");
+  });
+
+  it("rejects starting a voice session while a send awaits initialization", async () => {
+    const voiceAdapter = createVoiceAdapter();
+    const run = vi.fn(async () => ({}));
+    const runtime = new LocalRuntimeCore(
+      { adapters: { chatModel: { run }, voice: voiceAdapter.adapter } },
+      undefined,
+    );
+    const thread = runtime.threads.getMainThreadRuntimeCore();
+    let release!: () => void;
+    const barrier = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    thread.__internal_setGetInitializePromise(() => barrier);
+    const pending = thread.append({
+      parentId: null,
+      sourceId: null,
+      role: "user",
+      content: [{ type: "text", text: "hello" }],
+      attachments: [],
+      metadata: { custom: {} },
+      createdAt: new Date(),
+      runConfig: {},
+    });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(run).not.toHaveBeenCalled();
+
+    expect(() => thread.connectVoice()).toThrow(
+      "Cannot start a voice session while a run is in progress or paused on a pending tool action",
+    );
+
+    release();
+    await pending;
+    expect(run).toHaveBeenCalledOnce();
+
+    thread.connectVoice();
+    try {
+      expect(thread.voice).toBeDefined();
+    } finally {
+      thread.disconnectVoice();
+    }
+  });
+
+  it("rejects opening an edit while connected", async () => {
+    const { thread, voiceAdapter } = await createLocalVoiceThread();
+
+    try {
+      voiceAdapter.emitTranscript({
+        role: "user",
+        text: "Hello",
+        isFinal: true,
+      });
+      const transcript = thread.messages[0]!;
+
+      expect(() => thread.beginEdit(transcript.id)).toThrow(
+        "Cannot edit a message while a voice session is connected",
+      );
+
+      thread.disconnectVoice();
+
+      expect(() => thread.beginEdit(transcript.id)).not.toThrow();
+    } finally {
+      thread.disconnectVoice();
+    }
+  });
+
+  it("speaks an assistant transcript", () => {
+    const voiceAdapter = createVoiceAdapter();
+    const speech = {
+      speak: vi.fn(() => ({
+        status: { type: "running" as const },
+        cancel: vi.fn(),
+        subscribe: () => () => {},
+      })),
+    } satisfies SpeechSynthesisAdapter;
+    const runtime = new TestRuntime(voiceAdapter, undefined, { speech });
+    runtime.connectVoice();
+
+    try {
+      voiceAdapter.emitTranscript({
+        role: "assistant",
+        text: "Hello",
+        isFinal: true,
+      });
+      const message = runtime.messages[0]!;
+
+      expect(() => runtime.speak(message.id)).not.toThrow();
+      expect(speech.speak).toHaveBeenCalledExactlyOnceWith("Hello");
+    } finally {
+      runtime.disconnectVoice();
+    }
+  });
+
+  it("stops speaking a transcript when the session disconnects", () => {
+    const voiceAdapter = createVoiceAdapter();
+    const utterance = {
+      status: { type: "running" as const },
+      cancel: vi.fn(),
+      subscribe: () => () => {},
+    };
+    const speech = {
+      speak: vi.fn(() => utterance),
+    } satisfies SpeechSynthesisAdapter;
+    const runtime = new TestRuntime(voiceAdapter, undefined, { speech });
+    runtime.connectVoice();
+
+    voiceAdapter.emitTranscript({
+      role: "assistant",
+      text: "Hello",
+      isFinal: true,
+    });
+    runtime.speak(runtime.messages[0]!.id);
+    expect(runtime.speech?.messageId).toBe(runtime.messages[0]!.id);
+
+    runtime.disconnectVoice();
+
+    expect(utterance.cancel).toHaveBeenCalledOnce();
+    expect(runtime.speech).toBeUndefined();
+  });
+
+  it("still disconnects the session when stopping a spoken transcript throws", () => {
+    const voiceAdapter = createVoiceAdapter();
+    const utterance = {
+      status: { type: "running" as const },
+      cancel: vi.fn(() => {
+        throw new Error("cancel failed");
+      }),
+      subscribe: () => () => {},
+    };
+    const speech = {
+      speak: vi.fn(() => utterance),
+    } satisfies SpeechSynthesisAdapter;
+    const runtime = new TestRuntime(voiceAdapter, undefined, { speech });
+    runtime.connectVoice();
+
+    voiceAdapter.emitTranscript({
+      role: "assistant",
+      text: "Hello",
+      isFinal: true,
+    });
+    runtime.speak(runtime.messages[0]!.id);
+
+    expect(() => runtime.disconnectVoice()).toThrow("cancel failed");
+    expect(utterance.cancel).toHaveBeenCalledOnce();
+    expect(voiceAdapter.session.disconnect).toHaveBeenCalledOnce();
+    expect(runtime.messages).toHaveLength(0);
+    expect(runtime.speech).toBeUndefined();
+    expect(runtime.voice).toBeUndefined();
+  });
+
+  it("submits feedback for a transcript", () => {
+    const voiceAdapter = createVoiceAdapter();
+    const feedback = { submit: vi.fn() } satisfies FeedbackAdapter;
+    const runtime = new TestRuntime(voiceAdapter, undefined, { feedback });
+    runtime.connectVoice();
+
+    try {
+      voiceAdapter.emitTranscript({
+        role: "assistant",
+        text: "Hello",
+        isFinal: true,
+      });
+      const message = runtime.messages[0]!;
+
+      expect(() =>
+        runtime.submitFeedback({
+          messageId: message.id,
+          type: "positive",
+          comment: "Helpful summary",
+        }),
+      ).not.toThrow();
+      expect(feedback.submit).toHaveBeenCalledExactlyOnceWith({
+        message,
+        type: "positive",
+        comment: "Helpful summary",
+      });
+      expect(runtime.messages[0]?.metadata.submittedFeedback).toEqual({
+        type: "positive",
+        comment: "Helpful summary",
+      });
+
+      const rated = runtime.messages[0]!;
+      runtime.submitFeedback({
+        messageId: message.id,
+        type: "negative",
+        comment: "   ",
+      });
+      expect(feedback.submit).toHaveBeenLastCalledWith({
+        message: rated,
+        type: "negative",
+      });
+      expect(runtime.messages[0]?.metadata.submittedFeedback).toEqual({
+        type: "negative",
+      });
+
+      const rerated = runtime.messages[0]!;
+      runtime.submitFeedback({ messageId: message.id, type: "positive" });
+      expect(feedback.submit).toHaveBeenLastCalledWith({
+        message: rerated,
+        type: "positive",
+      });
+      expect(runtime.messages[0]?.metadata.submittedFeedback).toEqual({
+        type: "positive",
+      });
+    } finally {
+      runtime.disconnectVoice();
+    }
+  });
+
+  it("marks transcript feedback locally without an adapter", () => {
+    const voiceAdapter = createVoiceAdapter();
+    const runtime = new TestRuntime(voiceAdapter);
+    runtime.connectVoice();
+
+    try {
+      voiceAdapter.emitTranscript({
+        role: "assistant",
+        text: "Hello",
+        isFinal: true,
+      });
+      const message = runtime.messages[0]!;
+
+      expect(() =>
+        runtime.submitFeedback({ messageId: message.id, type: "negative" }),
+      ).not.toThrow();
+      expect(runtime.messages[0]?.metadata.submittedFeedback).toEqual({
+        type: "negative",
+      });
+    } finally {
+      runtime.disconnectVoice();
+    }
+  });
+
+  it("blocks an edit while connected and accepts it once the session ends", async () => {
+    const voiceAdapter = createVoiceAdapter();
+    const run = vi.fn(async () => ({}));
+    const runtime = new LocalRuntimeCore(
+      { adapters: { chatModel: { run }, voice: voiceAdapter.adapter } },
+      undefined,
+    );
+    const thread = runtime.threads.getMainThreadRuntimeCore();
+    thread.connectVoice();
+
+    try {
+      voiceAdapter.emitTranscript({
+        role: "assistant",
+        text: "Hello",
+        isFinal: true,
+      });
+      const edit = {
+        parentId: null,
+        sourceId: thread.messages[0]!.id,
+        role: "user" as const,
+        content: [{ type: "text" as const, text: "again" }],
+        attachments: [],
+        metadata: { custom: {} },
+        createdAt: new Date(),
+        runConfig: {},
+      };
+
+      await expect(thread.append(edit)).rejects.toThrow(
+        "Cannot send a text message while a voice session is connected",
+      );
+      await expect(thread.append({ ...edit, startRun: false })).rejects.toThrow(
+        "Cannot send a text message while a voice session is connected",
+      );
+      expect(run).not.toHaveBeenCalled();
+      expect(thread.messages).toHaveLength(1);
+
+      thread.disconnectVoice();
+
+      await thread.append(edit);
+      expect(run).toHaveBeenCalledOnce();
+    } finally {
+      thread.disconnectVoice();
+    }
+  });
+
+  it("blocks a reload while connected and allows it once the session ends", async () => {
+    const voiceAdapter = createVoiceAdapter();
+    const run = vi.fn(async () => ({}));
+    const runtime = new LocalRuntimeCore(
+      { adapters: { chatModel: { run }, voice: voiceAdapter.adapter } },
+      undefined,
+    );
+    const thread = runtime.threads.getMainThreadRuntimeCore();
+    thread.connectVoice();
+
+    try {
+      voiceAdapter.emitTranscript({
+        role: "assistant",
+        text: "Hello",
+        isFinal: true,
+      });
+      const message = thread.messages[0]!;
+
+      await expect(
+        thread.startRun({
+          parentId: null,
+          sourceId: message.id,
+          runConfig: {},
+        }),
+      ).rejects.toThrow(
+        "Cannot start a run while a voice session is connected",
+      );
+      expect(run).not.toHaveBeenCalled();
+
+      thread.disconnectVoice();
+
+      await thread.startRun({
+        parentId: null,
+        sourceId: message.id,
+        runConfig: {},
+      });
+      expect(run).toHaveBeenCalledOnce();
+    } finally {
+      thread.disconnectVoice();
+    }
+  });
+
+  it("blocks an approval response while connected before deciding it", () => {
+    const voiceAdapter = createVoiceAdapter();
+    const run = vi.fn(async () => ({}));
+    const runtime = new LocalRuntimeCore(
+      { adapters: { chatModel: { run }, voice: voiceAdapter.adapter } },
+      undefined,
+    );
+    const thread = runtime.threads.getMainThreadRuntimeCore();
+    thread.connectVoice();
+    thread.reset([
+      {
+        id: "user",
+        role: "user",
+        content: [{ type: "text", text: "Use the tool" }],
+      },
+      {
+        id: "assistant",
+        role: "assistant",
+        content: [
+          {
+            type: "tool-call",
+            toolCallId: "tool-call",
+            toolName: "tool",
+            args: {},
+            argsText: "{}",
+            approval: { id: "approval-1" },
+          },
+        ],
+        status: { type: "requires-action", reason: "interrupt" },
+      },
+    ]);
+
+    try {
+      expect(() =>
+        thread.respondToToolApproval({
+          approvalId: "approval-1",
+          approved: true,
+        }),
+      ).toThrow(
+        "Cannot respond to a tool approval while a voice session is connected",
+      );
+      const part = thread.messages[1]!.content[0]!;
+      expect(
+        part.type === "tool-call" && part.approval?.approved,
+      ).toBeUndefined();
+      expect(run).not.toHaveBeenCalled();
+    } finally {
+      thread.disconnectVoice();
+    }
+  });
+
+  it("blocks a tool result continuation while connected", () => {
+    const voiceAdapter = createVoiceAdapter();
+    const run = vi.fn(async () => ({}));
+    const runtime = new LocalRuntimeCore(
+      { adapters: { chatModel: { run }, voice: voiceAdapter.adapter } },
+      undefined,
+    );
+    const thread = runtime.threads.getMainThreadRuntimeCore();
+    const messageId = "assistant";
+    const toolCallId = "tool-call";
+    thread.connectVoice();
+    thread.reset([
+      {
+        id: "user",
+        role: "user",
+        content: [{ type: "text", text: "Use the tool" }],
+      },
+      {
+        id: messageId,
+        role: "assistant",
+        content: [
+          {
+            type: "tool-call",
+            toolCallId,
+            toolName: "tool",
+            args: {},
+            argsText: "{}",
+          },
+        ],
+        status: { type: "requires-action", reason: "tool-calls" },
+      },
+    ]);
+
+    try {
+      expect(() =>
+        thread.addToolResult({
+          messageId,
+          toolCallId,
+          toolName: "tool",
+          result: "done",
+          isError: false,
+        }),
+      ).toThrow("Cannot add a tool result while a voice session is connected");
+      expect(run).not.toHaveBeenCalled();
+      const part = thread.messages[1]!.content[0]!;
+      expect(part).not.toHaveProperty("result");
+    } finally {
+      thread.disconnectVoice();
+    }
+  });
+
+  it("rejects editing a transcript", () => {
+    const voiceAdapter = createVoiceAdapter();
+    const runtime = new TestRuntime(voiceAdapter);
+    runtime.connectVoice();
+
+    try {
+      voiceAdapter.emitTranscript({
+        role: "assistant",
+        text: "Hello",
+        isFinal: true,
+      });
+      voiceAdapter.emitStatus({ type: "ended", reason: "finished" });
+
+      expect(() => runtime.beginEdit(runtime.messages[0]!.id)).toThrow(
+        "Voice transcript messages cannot be edited",
+      );
+    } finally {
+      runtime.disconnectVoice();
+    }
+  });
+
+  it("marks user and assistant transcripts as voice messages", () => {
+    const voiceAdapter = createVoiceAdapter();
+    const runtime = new TestRuntime(voiceAdapter);
+    runtime.connectVoice();
+
+    try {
+      voiceAdapter.emitTranscript({
+        role: "user",
+        text: "Hello",
+        isFinal: true,
+      });
+      voiceAdapter.emitTranscript({ role: "assistant", text: "Hi" });
+
+      expect(runtime.messages[0]?.metadata.modality).toBe("voice");
+      expect(runtime.messages[1]?.metadata.modality).toBe("voice");
+
+      voiceAdapter.emitTranscript({
+        role: "assistant",
+        text: "Hello there",
+        isFinal: true,
+      });
+
+      expect(runtime.messages[1]?.metadata.modality).toBe("voice");
+    } finally {
+      runtime.disconnectVoice();
+    }
   });
-});
 
-describe("BaseThreadRuntimeCore voice transcripts", () => {
   it("completes a final-only reply before the next streamed reply", () => {
     const voiceAdapter = createVoiceAdapter();
     const runtime = new TestRuntime(voiceAdapter);