@assistant-ui/core 0.1.9 → 0.1.11

package/src/runtime/interfaces/thread-runtime-core.ts

@@ -4,6 +4,7 @@ import type { Unsubscribe } from "../../types/unsubscribe";
 import type { AppendMessage, ThreadMessage } from "../../types/message";
 import type { RunConfig } from "../../types/message";
 import type { SpeechSynthesisAdapter } from "../../adapters/speech";
+import type { RealtimeVoiceAdapter } from "../../adapters/voice";
 import type {
   ChatModelRunOptions,
   ChatModelRunResult,
@@ -24,6 +25,7 @@ export type RuntimeCapabilities = {
   readonly unstable_copy: boolean;
   readonly speech: boolean;
   readonly dictation: boolean;
+  readonly voice: boolean;
   readonly attachments: boolean;
   readonly feedback: boolean;
   readonly queue: boolean;
@@ -57,6 +59,12 @@ export type SpeechState = {
   readonly status: SpeechSynthesisAdapter.Status;
 };
 
+export type VoiceSessionState = {
+  readonly status: RealtimeVoiceAdapter.Status;
+  readonly isMuted: boolean;
+  readonly mode: RealtimeVoiceAdapter.Mode;
+};
+
 export type SubmittedFeedback = {
   readonly type: "negative" | "positive";
 };
@@ -102,6 +110,11 @@ export type ThreadRuntimeCore = Readonly<{
   speak: (messageId: string) => void;
   stopSpeaking: () => void;
 
+  connectVoice: () => void;
+  disconnectVoice: () => void;
+  muteVoice: () => void;
+  unmuteVoice: () => void;
+
   submitFeedback: (feedback: SubmitFeedbackOptions) => void;
 
   getModelContext: () => ModelContext;
@@ -111,6 +124,7 @@ export type ThreadRuntimeCore = Readonly<{
   beginEdit: (messageId: string) => void;
 
   speech: SpeechState | undefined;
+  voice: VoiceSessionState | undefined;
 
   capabilities: Readonly<RuntimeCapabilities>;
   isDisabled: boolean;
@@ -123,6 +137,9 @@ export type ThreadRuntimeCore = Readonly<{
 
   subscribe: (callback: () => void) => Unsubscribe;
 
+  getVoiceVolume: () => number;
+  subscribeVoiceVolume: (callback: () => void) => Unsubscribe;
+
   import(repository: ExportedMessageRepository): void;
   export(): ExportedMessageRepository;
 

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

@@ -5,6 +5,7 @@ import type {
   SpeechSynthesisAdapter,
   DictationAdapter,
 } from "../../adapters/speech";
+import type { RealtimeVoiceAdapter } from "../../adapters/voice";
 import type { FeedbackAdapter } from "../../adapters/feedback";
 import type {
   AddToolResultOptions,
@@ -90,6 +91,7 @@ type ExternalStoreAdapterBase<T> = {
         attachments?: AttachmentAdapter | undefined;
         speech?: SpeechSynthesisAdapter | undefined;
         dictation?: DictationAdapter | undefined;
+        voice?: RealtimeVoiceAdapter | undefined;
         feedback?: FeedbackAdapter | undefined;
         /**
          * @deprecated This API is still under active development and might change without notice.

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

@@ -63,6 +63,7 @@ export class ExternalStoreThreadRuntimeCore
     unstable_copy: false,
     speech: false,
     dictation: false,
+    voice: false,
     attachments: false,
     feedback: false,
     queue: false,
@@ -78,7 +79,7 @@ export class ExternalStoreThreadRuntimeCore
     return this._store.isLoading ?? false;
   }
 
-  public override get messages() {
+  protected override _getBaseMessages(): readonly ThreadMessage[] {
     return this._messages;
   }
 
@@ -137,6 +138,7 @@ export class ExternalStoreThreadRuntimeCore
       cancel: this._store.onCancel !== undefined,
       speech: this._store.adapters?.speech !== undefined,
       dictation: this._store.adapters?.dictation !== undefined,
+      voice: this._store.adapters?.voice !== undefined,
       unstable_copy: this._store.unstable_capabilities?.copy !== false,
       attachments: !!this._store.adapters?.attachments,
       feedback: !!this._store.adapters?.feedback,

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

@@ -5,6 +5,7 @@ import type {
   SpeechSynthesisAdapter,
   DictationAdapter,
 } from "../../adapters/speech";
+import type { RealtimeVoiceAdapter } from "../../adapters/voice";
 import type { SuggestionAdapter } from "../../adapters/suggestion";
 import type { ChatModelAdapter } from "../../runtime/utils/chat-model-adapter";
 
@@ -16,6 +17,7 @@ export type LocalRuntimeOptionsBase = {
     attachments?: AttachmentAdapter | undefined;
     speech?: SpeechSynthesisAdapter | undefined;
     dictation?: DictationAdapter | undefined;
+    voice?: RealtimeVoiceAdapter | undefined;
     feedback?: FeedbackAdapter | undefined;
     suggestion?: SuggestionAdapter | undefined;
   };

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

@@ -45,6 +45,7 @@ export class LocalThreadRuntimeCore
     unstable_copy: true,
     speech: false,
     dictation: false,
+    voice: false,
     attachments: false,
     feedback: false,
     queue: false,
@@ -118,6 +119,12 @@ export class LocalThreadRuntimeCore
       hasUpdates = true;
     }
 
+    const canVoice = options.adapters?.voice !== undefined;
+    if (this.capabilities.voice !== canVoice) {
+      this.capabilities.voice = canVoice;
+      hasUpdates = true;
+    }
+
     const canAttach = options.adapters?.attachments !== undefined;
     if (this.capabilities.attachments !== canAttach) {
       this.capabilities.attachments = canAttach;

package/src/runtimes/readonly/ReadonlyThreadRuntimeCore.ts

@@ -34,7 +34,6 @@ export class ReadonlyThreadRuntimeCore
   }
 
   getBranches(messageId: string) {
-    // no branching in readonly threads
     const idx = this._messages.findIndex((m) => m.id === messageId);
     if (idx === -1) return [];
     return [messageId];
@@ -56,9 +55,7 @@ export class ReadonlyThreadRuntimeCore
     throw READONLY_THREAD_ERROR;
   }
 
-  cancelRun(): void {
-    // noop - nothing to cancel
-  }
+  cancelRun(): void {}
 
   addToolResult(): void {
     throw READONLY_THREAD_ERROR;
@@ -72,8 +69,23 @@ export class ReadonlyThreadRuntimeCore
     throw READONLY_THREAD_ERROR;
   }
 
-  stopSpeaking(): void {
-    // noop
+  stopSpeaking(): void {}
+
+  connectVoice(): void {
+    throw READONLY_THREAD_ERROR;
+  }
+
+  disconnectVoice(): void {}
+
+  getVoiceVolume = () => 0;
+  subscribeVoiceVolume = (): Unsubscribe => () => {};
+
+  muteVoice(): void {
+    throw READONLY_THREAD_ERROR;
+  }
+
+  unmuteVoice(): void {
+    throw READONLY_THREAD_ERROR;
   }
 
   submitFeedback(): void {
@@ -179,6 +191,7 @@ export class ReadonlyThreadRuntimeCore
   }
 
   speech = undefined;
+  voice = undefined;
 
   capabilities = {
     switchToBranch: false,
@@ -189,6 +202,7 @@ export class ReadonlyThreadRuntimeCore
     unstable_copy: false,
     speech: false,
     dictation: false,
+    voice: false,
     attachments: false,
     feedback: false,
     queue: false,

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

@@ -48,6 +48,25 @@ export const EMPTY_THREAD_CORE: ThreadRuntimeCore = {
     throw EMPTY_THREAD_ERROR;
   },
 
+  connectVoice() {
+    throw EMPTY_THREAD_ERROR;
+  },
+
+  disconnectVoice() {
+    throw EMPTY_THREAD_ERROR;
+  },
+
+  getVoiceVolume: () => 0,
+  subscribeVoiceVolume: () => () => {},
+
+  muteVoice() {
+    throw EMPTY_THREAD_ERROR;
+  },
+
+  unmuteVoice() {
+    throw EMPTY_THREAD_ERROR;
+  },
+
   submitFeedback() {
     throw EMPTY_THREAD_ERROR;
   },
@@ -72,7 +91,7 @@ export const EMPTY_THREAD_CORE: ThreadRuntimeCore = {
     attachments: [],
     attachmentAccept: "*",
 
-    async addAttachment(_fileOrAttachment) {
+    async addAttachment() {
       throw EMPTY_THREAD_ERROR;
     },
 
@@ -153,6 +172,7 @@ export const EMPTY_THREAD_CORE: ThreadRuntimeCore = {
   },
 
   speech: undefined,
+  voice: undefined,
 
   capabilities: {
     switchToBranch: false,
@@ -163,13 +183,14 @@ export const EMPTY_THREAD_CORE: ThreadRuntimeCore = {
     unstable_copy: false,
     speech: false,
     dictation: false,
+    voice: false,
     attachments: false,
     feedback: false,
     queue: false,
   },
 
   isDisabled: false,
-  isLoading: false,
+  isLoading: true,
 
   messages: [],
 

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

@@ -39,6 +39,22 @@ export type RemoteThreadListOptions = {
   runtimeHook: () => AssistantRuntime;
   adapter: RemoteThreadListAdapter;
 
+  /**
+   * When provided, the runtime starts on this thread instead of creating a
+   * new empty thread. Useful for URL-based routing (e.g. `/chat/[threadId]`)
+   * where the initial thread is known at mount time.
+   *
+   * @deprecated Use `threadId` instead, which also reacts to subsequent changes.
+   */
+  initialThreadId?: string | undefined;
+
+  /**
+   * The current thread ID to display. When this value changes, the runtime
+   * automatically switches to the specified thread. Set to `undefined` to
+   * switch to a new thread.
+   */
+  threadId?: string | undefined;
+
   /**
    * When true, if this runtime is used inside another RemoteThreadListRuntime,
    * it becomes a no-op and simply calls the runtimeHook directly.

package/src/store/runtime-clients/thread-list-runtime-client.ts

@@ -85,6 +85,7 @@ export const ThreadListClient = resource(
       switchToNewThread: async () => {
         await runtime.switchToNewThread();
       },
+      getLoadThreadsPromise: () => runtime.getLoadThreadsPromise(),
       __internal_getAssistantRuntime: () => __internal_assistantRuntime,
     };
   },

package/src/store/runtime-clients/thread-runtime-client.ts

@@ -44,11 +44,9 @@ export const ThreadClient = resource(
     const runtimeState = tapSubscribable(runtime);
     const emit = tapAssistantEmit();
 
-    // Bind thread events to event manager
     tapEffect(() => {
       const unsubscribers: Unsubscribe[] = [];
 
-      // Subscribe to thread events
       const threadEvents: ThreadRuntimeEventType[] = [
         "runStart",
         "runEnd",
@@ -105,6 +103,7 @@ export const ThreadClient = resource(
         suggestions: runtimeState.suggestions,
         extras: runtimeState.extras,
         speech: runtimeState.speech,
+        voice: runtimeState.voice,
 
         composer: composer.state,
         messages: messages.state,
@@ -124,12 +123,12 @@ export const ThreadClient = resource(
       import: runtime.import,
       reset: runtime.reset,
       stopSpeaking: runtime.stopSpeaking,
-      startVoice: async () => {
-        throw new Error("startVoice is not supported in this runtime");
-      },
-      stopVoice: async () => {
-        throw new Error("stopVoice is not supported in this runtime");
-      },
+      connectVoice: runtime.connectVoice,
+      disconnectVoice: runtime.disconnectVoice,
+      getVoiceVolume: runtime.getVoiceVolume,
+      subscribeVoiceVolume: runtime.subscribeVoiceVolume,
+      muteVoice: runtime.muteVoice,
+      unmuteVoice: runtime.unmuteVoice,
       message: (selector) => {
         if ("id" in selector) {
           return messages.get({ key: selector.id });

package/src/store/scopes/thread.ts

@@ -2,9 +2,11 @@ import type { ReadonlyJSONValue } from "assistant-stream/utils";
 import type {
   RuntimeCapabilities,
   SpeechState,
+  VoiceSessionState,
   ThreadSuggestion,
 } from "../../runtime/interfaces/thread-runtime-core";
 import type { ExportedMessageRepository } from "../../runtime/utils/message-repository";
+import type { Unsubscribe } from "../../types/unsubscribe";
 import type { ThreadMessageLike } from "../../runtime/utils/thread-message-like";
 import type {
   CreateAppendMessage,
@@ -56,6 +58,7 @@ export type ThreadState = {
   readonly extras: unknown;
   /** @deprecated This API is still under active development and might change without notice. */
   readonly speech: SpeechState | undefined;
+  readonly voice: VoiceSessionState | undefined;
   readonly composer: ComposerState;
 };
 
@@ -112,14 +115,12 @@ export type ThreadMethods = {
   message(selector: { id: string } | { index: number }): MessageMethods;
   /** @deprecated This API is still under active development and might change without notice. */
   stopSpeaking(): void;
-  /**
-   * Start the voice session for the thread. Establishes any necessary media connections.
-   */
-  startVoice(): Promise<void>;
-  /**
-   * Stop the currently active voice session.
-   */
-  stopVoice(): Promise<void>;
+  connectVoice(): void;
+  disconnectVoice(): void;
+  getVoiceVolume(): number;
+  subscribeVoiceVolume(callback: () => void): Unsubscribe;
+  muteVoice(): void;
+  unmuteVoice(): void;
   __internal_getRuntime?(): ThreadRuntime;
 };
 

package/src/store/scopes/threads.ts

@@ -26,6 +26,7 @@ export type ThreadsMethods = {
       | { index: number; archived?: boolean },
   ): ThreadListItemMethods;
   thread(selector: "main"): ThreadMethods;
+  getLoadThreadsPromise(): Promise<void>;
   __internal_getAssistantRuntime?(): AssistantRuntime;
 };
 

package/src/tests/empty-thread-core.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest";
+import { EMPTY_THREAD_CORE } from "../runtimes/remote-thread-list/empty-thread-core";
+
+describe("EMPTY_THREAD_CORE", () => {
+  it("has isLoading=true so it is not mistaken for an empty conversation", () => {
+    expect(EMPTY_THREAD_CORE.isLoading).toBe(true);
+  });
+
+  it("has empty messages", () => {
+    expect(EMPTY_THREAD_CORE.messages).toEqual([]);
+  });
+
+  it("does not trigger isEmpty (messages.length === 0 && !isLoading)", () => {
+    const isEmpty =
+      EMPTY_THREAD_CORE.messages.length === 0 && !EMPTY_THREAD_CORE.isLoading;
+    expect(isEmpty).toBe(false);
+  });
+
+  it("all capabilities are disabled", () => {
+    const caps = EMPTY_THREAD_CORE.capabilities;
+    expect(caps.edit).toBe(false);
+    expect(caps.reload).toBe(false);
+    expect(caps.cancel).toBe(false);
+    expect(caps.speech).toBe(false);
+    expect(caps.attachments).toBe(false);
+  });
+
+  it("mutating methods throw", () => {
+    expect(() => EMPTY_THREAD_CORE.append({} as any)).toThrow();
+    expect(() => EMPTY_THREAD_CORE.startRun({} as any)).toThrow();
+    expect(() => EMPTY_THREAD_CORE.cancelRun()).toThrow();
+  });
+});

package/src/tests/remote-thread-list-isLoading.test.ts

@@ -0,0 +1,192 @@
+import { describe, it, expect } from "vitest";
+import { OptimisticState } from "../runtimes/remote-thread-list/optimistic-state";
+import {
+  type RemoteThreadState,
+  type RemoteThreadData,
+  type THREAD_MAPPING_ID,
+  createThreadMappingId,
+} from "../runtimes/remote-thread-list/remote-thread-state";
+
+/**
+ * Tests for the isLoading lifecycle of RemoteThreadListThreadListRuntimeCore.
+ *
+ * The initial isLoading must be `true` so consumers can distinguish
+ * "not yet loaded" from "loaded with zero threads".
+ */
+
+type ListResult = {
+  threads: {
+    remoteId: string;
+    status: "regular" | "archived";
+    title?: string;
+    externalId?: string | undefined;
+  }[];
+};
+
+const INITIAL_STATE: RemoteThreadState = {
+  isLoading: true,
+  newThreadId: undefined,
+  threadIds: [],
+  archivedThreadIds: [],
+  threadIdMap: {},
+  threadData: {},
+};
+
+const applyListResult = (
+  state: RemoteThreadState,
+  l: ListResult,
+): RemoteThreadState => {
+  const newThreadIds: string[] = [];
+  const newArchivedThreadIds: string[] = [];
+  const newThreadIdMap = {} as Record<string, THREAD_MAPPING_ID>;
+  const newThreadData = {} as Record<THREAD_MAPPING_ID, RemoteThreadData>;
+
+  for (const thread of l.threads) {
+    if (thread.status === "regular") newThreadIds.push(thread.remoteId);
+    else newArchivedThreadIds.push(thread.remoteId);
+
+    const mappingId = createThreadMappingId(thread.remoteId);
+    newThreadIdMap[thread.remoteId] = mappingId;
+    newThreadData[mappingId] = {
+      id: thread.remoteId,
+      remoteId: thread.remoteId,
+      externalId: thread.externalId,
+      status: thread.status,
+      title: thread.title,
+      initializeTask: Promise.resolve({
+        remoteId: thread.remoteId,
+        externalId: thread.externalId,
+      }),
+    };
+  }
+
+  return {
+    ...state,
+    isLoading: false,
+    threadIds: newThreadIds,
+    archivedThreadIds: newArchivedThreadIds,
+    threadIdMap: { ...state.threadIdMap, ...newThreadIdMap },
+    threadData: { ...state.threadData, ...newThreadData },
+  };
+};
+
+function deferred<T>() {
+  let resolve!: (v: T) => void;
+  let reject!: (e: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+describe("RemoteThreadList isLoading lifecycle", () => {
+  it("starts as true before any loading begins", () => {
+    const state = new OptimisticState<RemoteThreadState>(INITIAL_STATE);
+    expect(state.value.isLoading).toBe(true);
+  });
+
+  it("remains true while loading is in progress", () => {
+    const state = new OptimisticState<RemoteThreadState>(INITIAL_STATE);
+    const d = deferred<ListResult>();
+
+    state.optimisticUpdate({
+      execute: () => d.promise,
+      loading: (s) => ({ ...s, isLoading: true }),
+      then: applyListResult,
+    });
+
+    expect(state.value.isLoading).toBe(true);
+  });
+
+  it("becomes false after loading completes with empty list", async () => {
+    const state = new OptimisticState<RemoteThreadState>(INITIAL_STATE);
+    const d = deferred<ListResult>();
+
+    const promise = state.optimisticUpdate({
+      execute: () => d.promise,
+      loading: (s) => ({ ...s, isLoading: true }),
+      then: applyListResult,
+    });
+
+    d.resolve({ threads: [] });
+    await promise;
+
+    expect(state.value.isLoading).toBe(false);
+  });
+
+  it("becomes false after loading completes with threads", async () => {
+    const state = new OptimisticState<RemoteThreadState>(INITIAL_STATE);
+    const d = deferred<ListResult>();
+
+    const promise = state.optimisticUpdate({
+      execute: () => d.promise,
+      loading: (s) => ({ ...s, isLoading: true }),
+      then: applyListResult,
+    });
+
+    d.resolve({
+      threads: [
+        { remoteId: "t-1", status: "regular", title: "Thread 1" },
+        { remoteId: "t-2", status: "archived", title: "Thread 2" },
+      ],
+    });
+    await promise;
+
+    expect(state.value.isLoading).toBe(false);
+    expect(state.value.threadIds).toEqual(["t-1"]);
+    expect(state.value.archivedThreadIds).toEqual(["t-2"]);
+  });
+
+  it("initial true and final false are distinguishable", async () => {
+    const state = new OptimisticState<RemoteThreadState>(INITIAL_STATE);
+    const before = state.value.isLoading;
+
+    const d = deferred<ListResult>();
+    const promise = state.optimisticUpdate({
+      execute: () => d.promise,
+      loading: (s) => ({ ...s, isLoading: true }),
+      then: applyListResult,
+    });
+
+    d.resolve({ threads: [] });
+    await promise;
+
+    const after = state.value.isLoading;
+    expect(before).toBe(true);
+    expect(after).toBe(false);
+  });
+});
+
+describe("RemoteThreadList isLoading error path", () => {
+  it("isLoading resets to false after adapter.list() rejects", async () => {
+    const state = new OptimisticState<RemoteThreadState>(INITIAL_STATE);
+    const d = deferred<ListResult>();
+
+    // Simulate the getLoadThreadsPromise pattern with .catch() fix
+    let loadPromise: Promise<void> | undefined;
+    loadPromise = state
+      .optimisticUpdate({
+        execute: () => d.promise,
+        loading: (s) => ({ ...s, isLoading: true }),
+        then: applyListResult,
+      })
+      .catch(() => {
+        loadPromise = undefined;
+        state.update({ ...state.baseValue, isLoading: false });
+      })
+      .then(() => {});
+
+    // While loading, isLoading is true
+    expect(state.value.isLoading).toBe(true);
+
+    d.reject(new Error("network error"));
+    await loadPromise;
+
+    // After failure, isLoading resets to false
+    expect(state.value.isLoading).toBe(false);
+
+    // Cache is cleared, allowing retry
+    expect(loadPromise).toBeUndefined();
+  });
+});