@assistant-ui/core 0.1.16 → 0.2.0

package/src/runtime/api/thread-runtime.ts

@@ -4,6 +4,7 @@ import type {
   ThreadRuntimeCore,
   SpeechState,
   VoiceSessionState,
+  ThreadRuntimeEventCallback,
   ThreadRuntimeEventType,
   StartRunConfig,
   ResumeRunConfig,
@@ -251,10 +252,6 @@ export type ThreadRuntime = {
    */
   append(message: CreateAppendMessage): void;
 
-  /**
-   * @deprecated pass an object with `parentId` instead. This will be removed in 0.12.0.
-   */
-  startRun(parentId: string | null): void;
   /**
    * Start a new run with the given configuration.
    * @param config The configuration for starting the run
@@ -267,11 +264,6 @@ export type ThreadRuntime = {
    **/
   resumeRun(config: CreateResumeRunConfig): void;
 
-  /**
-   * @deprecated Use `resumeRun` instead.
-   */
-  unstable_resumeRun(config: CreateResumeRunConfig): void;
-
   /**
    * Export the thread state in the external store format.
    * For AI SDK runtimes, this returns the AI SDK message format.
@@ -288,22 +280,10 @@ export type ThreadRuntime = {
    */
   importExternalState(state: any): void;
 
-  /**
-   * Load external state into the thread.
-   * @deprecated Use importExternalState instead. This method will be removed in 0.12.0.
-   * @param state The state to load into the thread
-   */
-  unstable_loadExternalState(state: any): void;
-
   subscribe(callback: () => void): Unsubscribe;
   cancelRun(): void;
   getModelContext(): ModelContext;
 
-  /**
-   * @deprecated This method was renamed to `getModelContext`.
-   */
-  getModelConfig(): ModelContext;
-
   export(): ExportedMessageRepository;
   import(repository: ExportedMessageRepository): void;
 
@@ -329,7 +309,10 @@ export type ThreadRuntime = {
   muteVoice(): void;
   unmuteVoice(): void;
 
-  unstable_on(event: ThreadRuntimeEventType, callback: () => void): Unsubscribe;
+  unstable_on<E extends ThreadRuntimeEventType>(
+    event: E,
+    callback: ThreadRuntimeEventCallback<E>,
+  ): Unsubscribe;
 };
 
 export class ThreadRuntimeImpl implements ThreadRuntime {
@@ -392,9 +375,6 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
   protected __internal_bindMethods() {
     this.append = this.append.bind(this);
     this.resumeRun = this.resumeRun.bind(this);
-    this.unstable_resumeRun = this.unstable_resumeRun.bind(this);
-    this.unstable_loadExternalState =
-      this.unstable_loadExternalState.bind(this);
     this.importExternalState = this.importExternalState.bind(this);
     this.exportExternalState = this.exportExternalState.bind(this);
     this.startRun = this.startRun.bind(this);
@@ -414,7 +394,6 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
     this.subscribe = this.subscribe.bind(this);
     this.unstable_on = this.unstable_on.bind(this);
     this.getModelContext = this.getModelContext.bind(this);
-    this.getModelConfig = this.getModelConfig.bind(this);
     this.getState = this.getState.bind(this);
   }
 
@@ -440,15 +419,7 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
     return this._threadBinding.getState().getModelContext();
   }
 
-  public getModelConfig() {
-    return this.getModelContext();
-  }
-
-  public startRun(configOrParentId: string | null | CreateStartRunConfig) {
-    const config =
-      configOrParentId === null || typeof configOrParentId === "string"
-        ? { parentId: configOrParentId }
-        : configOrParentId;
+  public startRun(config: CreateStartRunConfig) {
     return this._threadBinding.getState().startRun(toStartRunConfig(config));
   }
 
@@ -456,11 +427,6 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
     return this._threadBinding.getState().resumeRun(toResumeRunConfig(config));
   }
 
-  /** @deprecated Use `resumeRun` instead. */
-  public unstable_resumeRun(config: CreateResumeRunConfig) {
-    return this.resumeRun(config);
-  }
-
   public exportExternalState() {
     return this._threadBinding.getState().exportExternalState();
   }
@@ -469,10 +435,6 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
     this._threadBinding.getState().importExternalState(state);
   }
 
-  public unstable_loadExternalState(state: any) {
-    this._threadBinding.getState().unstable_loadExternalState(state);
-  }
-
   public cancelRun() {
     this._threadBinding.getState().cancelRun();
   }
@@ -571,7 +533,6 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
           const thread = this._threadBinding.getState();
 
           const branches = thread.getBranches(message.id);
-          const submittedFeedback = message.metadata.submittedFeedback;
 
           return {
             ...message,
@@ -586,8 +547,6 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
 
             speech:
               speechState?.messageId === message.id ? speechState : undefined,
-
-            submittedFeedback,
           } satisfies MessageState;
         },
         subscribe: (callback) => this._threadBinding.subscribe(callback),
@@ -601,18 +560,18 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
     EventSubscriptionSubject<ThreadRuntimeEventType>
   >();
 
-  public unstable_on(
-    event: ThreadRuntimeEventType,
-    callback: () => void,
+  public unstable_on<E extends ThreadRuntimeEventType>(
+    event: E,
+    callback: ThreadRuntimeEventCallback<E>,
   ): Unsubscribe {
     let subject = this._eventSubscriptionSubjects.get(event);
     if (!subject) {
-      subject = new EventSubscriptionSubject({
-        event: event,
+      subject = new EventSubscriptionSubject<ThreadRuntimeEventType>({
+        event,
         binding: this._threadBinding,
       });
       this._eventSubscriptionSubjects.set(event, subject);
     }
-    return subject.subscribe(callback);
+    return subject.subscribe(callback as (payload?: unknown) => void);
   }
 }

package/src/runtime/base/base-composer-runtime-core.ts

@@ -14,7 +14,10 @@ import {
   fileMatchesAccept,
 } from "../../adapters/attachment";
 import type {
+  AttachmentAddErrorReason,
   ComposerRuntimeCore,
+  ComposerRuntimeEventCallback,
+  ComposerRuntimeEventPayload,
   ComposerRuntimeEventType,
   DictationState,
   SendOptions,
@@ -189,7 +192,7 @@ export abstract class BaseComposerRuntimeCore
     };
 
     this.handleSend(message, options);
-    this._notifyEventSubscribers("send");
+    this._notifyEventSubscribers("send", {});
   }
 
   public cancel() {
@@ -215,14 +218,15 @@ export abstract class BaseComposerRuntimeCore
           adapter.accept,
         )
       ) {
-        try {
-          this._notifyEventSubscribers("attachmentAddError");
-        } catch {
-          // prevent subscriber errors from masking the original error
-        }
-        throw new Error(
-          `File type ${fileOrAttachment.contentType || "unknown"} is not accepted. Accepted types: ${adapter.accept}`,
+        const message = `File type ${fileOrAttachment.contentType || "unknown"} is not accepted. Accepted types: ${adapter.accept}`;
+        const err = new Error(message);
+        this._safeEmitAttachmentAddError(
+          "not-accepted",
+          message,
+          undefined,
+          err,
         );
+        throw err;
       }
 
       const a: CompleteAttachment = {
@@ -235,7 +239,7 @@ export abstract class BaseComposerRuntimeCore
       };
       this._attachments = [...this._attachments, a];
       this._notifySubscribers();
-      this._notifyEventSubscribers("attachmentAdd");
+      this._notifyEventSubscribers("attachmentAdd", {});
       return;
     }
 
@@ -256,22 +260,28 @@ export abstract class BaseComposerRuntimeCore
       this._notifySubscribers();
     };
 
-    let lastAttachment: PendingAttachment | undefined;
-    try {
-      const adapter = this.getAttachmentAdapter();
-      if (!adapter) throw new Error("Attachments are not supported");
+    const adapter = this.getAttachmentAdapter();
+    if (!adapter) {
+      const message = "Attachments are not supported";
+      const err = new Error(message);
+      this._safeEmitAttachmentAddError("no-adapter", message, undefined, err);
+      throw err;
+    }
 
-      if (
-        !fileMatchesAccept(
-          { name: fileOrAttachment.name, type: fileOrAttachment.type },
-          adapter.accept,
-        )
-      ) {
-        throw new Error(
-          `File type ${fileOrAttachment.type || "unknown"} is not accepted. Accepted types: ${adapter.accept}`,
-        );
-      }
+    if (
+      !fileMatchesAccept(
+        { name: fileOrAttachment.name, type: fileOrAttachment.type },
+        adapter.accept,
+      )
+    ) {
+      const message = `File type ${fileOrAttachment.type || "unknown"} is not accepted. Accepted types: ${adapter.accept}`;
+      const err = new Error(message);
+      this._safeEmitAttachmentAddError("not-accepted", message, undefined, err);
+      throw err;
+    }
 
+    let lastAttachment: PendingAttachment | undefined;
+    try {
       const promiseOrGenerator = adapter.add({ file: fileOrAttachment });
       if (Symbol.asyncIterator in promiseOrGenerator) {
         for await (const r of promiseOrGenerator) {
@@ -289,20 +299,48 @@ export abstract class BaseComposerRuntimeCore
           status: { type: "incomplete", reason: "error" },
         });
       }
-      try {
-        this._notifyEventSubscribers("attachmentAddError");
-      } catch {
-        // prevent subscriber errors from masking the original error
-      }
+      this._safeEmitAttachmentAddError(
+        "adapter-error",
+        e instanceof Error ? e.message : String(e),
+        lastAttachment?.id,
+        e instanceof Error ? e : undefined,
+      );
       throw e;
     }
 
     const hasError =
       lastAttachment?.status.type === "incomplete" &&
       lastAttachment.status.reason === "error";
-    this._notifyEventSubscribers(
-      hasError ? "attachmentAddError" : "attachmentAdd",
-    );
+    if (hasError) {
+      this._safeEmitAttachmentAddError(
+        "adapter-error",
+        "Attachment upload did not complete successfully.",
+        lastAttachment?.id,
+      );
+    } else {
+      this._notifyEventSubscribers("attachmentAdd", {});
+    }
+  }
+
+  private _safeEmitAttachmentAddError(
+    reason: AttachmentAddErrorReason,
+    message: string,
+    attachmentId?: string,
+    error?: Error,
+  ) {
+    try {
+      this._notifyEventSubscribers("attachmentAddError", {
+        reason,
+        message,
+        ...(attachmentId !== undefined && { attachmentId }),
+        ...(error !== undefined && { error }),
+      });
+    } catch (subscriberError) {
+      console.error(
+        "[assistant-ui] attachmentAddError subscriber threw:",
+        subscriberError,
+      );
+    }
   }
 
   async removeAttachment(attachmentId: string) {
@@ -471,28 +509,33 @@ export abstract class BaseComposerRuntimeCore
 
   private _eventSubscribers = new Map<
     ComposerRuntimeEventType,
-    Set<() => void>
+    Set<(payload?: unknown) => void>
   >();
 
-  protected _notifyEventSubscribers(event: ComposerRuntimeEventType) {
+  protected _notifyEventSubscribers<E extends ComposerRuntimeEventType>(
+    event: E,
+    payload: ComposerRuntimeEventPayload[E],
+  ) {
     const subscribers = this._eventSubscribers.get(event);
     if (!subscribers) return;
 
-    for (const callback of subscribers) callback();
+    for (const callback of subscribers) callback(payload);
   }
 
-  public unstable_on(event: ComposerRuntimeEventType, callback: () => void) {
-    const subscribers = this._eventSubscribers.get(event);
+  public unstable_on<E extends ComposerRuntimeEventType>(
+    event: E,
+    callback: ComposerRuntimeEventCallback<E>,
+  ) {
+    const wrapped = callback as (payload?: unknown) => void;
+    let subscribers = this._eventSubscribers.get(event);
     if (!subscribers) {
-      this._eventSubscribers.set(event, new Set([callback]));
-    } else {
-      subscribers.add(callback);
+      subscribers = new Set();
+      this._eventSubscribers.set(event, subscribers);
     }
+    subscribers.add(wrapped);
 
     return () => {
-      const subscribers = this._eventSubscribers.get(event);
-      if (!subscribers) return;
-      subscribers.delete(callback);
+      this._eventSubscribers.get(event)?.delete(wrapped);
     };
   }
 }

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

@@ -21,6 +21,8 @@ import type {
   SpeechState,
   VoiceSessionState,
   RuntimeCapabilities,
+  ThreadRuntimeEventCallback,
+  ThreadRuntimeEventPayload,
   ThreadRuntimeEventType,
   StartRunConfig,
   ResumeRunConfig,
@@ -59,7 +61,6 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
   public abstract cancelRun(): void;
   public abstract exportExternalState(): any;
   public abstract importExternalState(state: any): void;
-  public abstract unstable_loadExternalState(state: any): void;
 
   protected _voiceMessages: ThreadMessage[] = [];
   protected _voiceGeneration = 0;
@@ -168,11 +169,14 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
     for (const callback of this._subscriptions) callback();
   }
 
-  public _notifyEventSubscribers(event: ThreadRuntimeEventType) {
+  public _notifyEventSubscribers<E extends ThreadRuntimeEventType>(
+    event: E,
+    payload: ThreadRuntimeEventPayload[E],
+  ) {
     const subscribers = this._eventSubscribers.get(event);
     if (!subscribers) return;
 
-    for (const callback of subscribers) callback();
+    for (const callback of subscribers) callback(payload);
   }
 
   public subscribe(callback: () => void): Unsubscribe {
@@ -432,7 +436,7 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
   protected ensureInitialized() {
     if (!this._isInitialized) {
       this._isInitialized = true;
-      this._notifyEventSubscribers("initialize");
+      this._notifyEventSubscribers("initialize", {});
     }
   }
 
@@ -453,24 +457,28 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
 
   private _eventSubscribers = new Map<
     ThreadRuntimeEventType,
-    Set<() => void>
+    Set<(payload?: unknown) => void>
   >();
 
-  public unstable_on(event: ThreadRuntimeEventType, callback: () => void) {
+  public unstable_on<E extends ThreadRuntimeEventType>(
+    event: E,
+    callback: ThreadRuntimeEventCallback<E>,
+  ) {
+    const wrapped = callback as (payload?: unknown) => void;
     if (event === "modelContextUpdate") {
-      return this._contextProvider.subscribe?.(callback) ?? (() => {});
+      // provider.subscribe is `() => void`; pump the typed empty payload to the user callback.
+      return this._contextProvider.subscribe?.(() => wrapped({})) ?? (() => {});
     }
 
-    const subscribers = this._eventSubscribers.get(event);
+    let subscribers = this._eventSubscribers.get(event);
     if (!subscribers) {
-      this._eventSubscribers.set(event, new Set([callback]));
-    } else {
-      subscribers.add(callback);
+      subscribers = new Set();
+      this._eventSubscribers.set(event, subscribers);
     }
+    subscribers.add(wrapped);
 
     return () => {
-      const subscribers = this._eventSubscribers.get(event)!;
-      subscribers.delete(callback);
+      this._eventSubscribers.get(event)?.delete(wrapped);
     };
   }
 }

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

@@ -5,10 +5,37 @@ import type { Unsubscribe } from "../../types/unsubscribe";
 import type { RunConfig } from "../../types/message";
 import type { DictationAdapter } from "../../adapters/speech";
 
-export type ComposerRuntimeEventType =
-  | "send"
-  | "attachmentAdd"
-  | "attachmentAddError";
+export type AttachmentAddErrorReason =
+  | "no-adapter"
+  | "not-accepted"
+  | "adapter-error";
+
+export type AttachmentAddErrorEvent = {
+  readonly reason: AttachmentAddErrorReason;
+  readonly message: string;
+  readonly attachmentId?: string;
+  readonly error?: Error;
+};
+
+export type ComposerRuntimeEventPayload = {
+  /**
+   * @deprecated State-derivable. Observe `state.text` clearing via
+   * `subscribe` + `getState` instead. Kept for backward compatibility.
+   */
+  send: Record<string, never>;
+  /**
+   * @deprecated State-derivable. Observe `state.attachments` via `subscribe` +
+   * `getState` instead. Kept for backward compatibility.
+   */
+  attachmentAdd: Record<string, never>;
+  attachmentAddError: AttachmentAddErrorEvent;
+};
+
+export type ComposerRuntimeEventType = keyof ComposerRuntimeEventPayload;
+
+export type ComposerRuntimeEventCallback<E extends ComposerRuntimeEventType> = (
+  payload: ComposerRuntimeEventPayload[E],
+) => void;
 
 export type DictationState = {
   readonly status: DictationAdapter.Status;
@@ -56,9 +83,14 @@ export type ComposerRuntimeCore = Readonly<{
 
   subscribe: (callback: () => void) => Unsubscribe;
 
-  unstable_on: (
-    event: ComposerRuntimeEventType,
-    callback: () => void,
+  /**
+   * @deprecated This API is still under active development and might change without notice.
+   * For state-derivable transitions, prefer `subscribe` + `getState`. This channel is the
+   * escape hatch for transient occurrences not represented in state.
+   */
+  unstable_on: <E extends ComposerRuntimeEventType>(
+    event: E,
+    callback: ComposerRuntimeEventCallback<E>,
   ) => Unsubscribe;
 }>;
 

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

@@ -17,6 +17,8 @@ export type ThreadListItemCoreState = {
 
 export type ThreadListRuntimeCore = {
   readonly isLoading: boolean;
+  readonly isLoadingMore?: boolean;
+  readonly hasMore?: boolean;
   mainThreadId: string;
   newThreadId: string | undefined;
 
@@ -35,6 +37,7 @@ export type ThreadListRuntimeCore = {
 
   getLoadThreadsPromise(): Promise<void>;
   reload?(): Promise<void>;
+  loadMore?(): Promise<void>;
 
   detach(threadId: string): Promise<void>;
   rename(threadId: string, newTitle: string): Promise<void>;

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

@@ -69,11 +69,41 @@ export type SubmittedFeedback = {
   readonly type: "negative" | "positive";
 };
 
-export type ThreadRuntimeEventType =
-  | "runStart"
-  | "runEnd"
-  | "initialize"
-  | "modelContextUpdate";
+export type ThreadRuntimeEventPayload = {
+  /**
+   * @deprecated State-derivable. Observe `state.isRunning` flipping to `true`
+   * via `subscribe` + `getState` instead. Note: this event fires at the
+   * transition point and may run before the next subscriber notification.
+   * Kept for backward compatibility.
+   */
+  runStart: Record<string, never>;
+  /**
+   * @deprecated State-derivable. Observe `state.isRunning` flipping to `false`
+   * via `subscribe` + `getState` instead. Note: this event fires at the
+   * transition point and may run before the next subscriber notification.
+   * Kept for backward compatibility.
+   */
+  runEnd: Record<string, never>;
+  /**
+   * @deprecated State-derivable. This event fires at the initialization
+   * transition immediately BEFORE the first message is added, so reading state
+   * inside the handler still sees an empty thread; observe `state.messages`
+   * becoming non-empty via a regular `subscribe` callback instead. Kept for
+   * backward compatibility.
+   */
+  initialize: Record<string, never>;
+  /**
+   * Truly transient. The model context lives in a provider, not in thread
+   * state, so this event has no state-derivable equivalent.
+   */
+  modelContextUpdate: Record<string, never>;
+};
+
+export type ThreadRuntimeEventType = keyof ThreadRuntimeEventPayload;
+
+export type ThreadRuntimeEventCallback<E extends ThreadRuntimeEventType> = (
+  payload: ThreadRuntimeEventPayload[E],
+) => void;
 
 export type StartRunConfig = {
   parentId: string | null;
@@ -155,10 +185,13 @@ export type ThreadRuntimeCore = Readonly<{
 
   reset(initialMessages?: readonly ThreadMessageLike[]): void;
 
-  unstable_on(event: ThreadRuntimeEventType, callback: () => void): Unsubscribe;
-
   /**
-   * @deprecated Use importExternalState instead. This method will be removed in 0.12.0.
+   * @deprecated This API is still under active development and might change without notice.
+   * For state-derivable transitions, prefer `subscribe` + `getState`. This channel is the
+   * escape hatch for transient occurrences not represented in state.
    */
-  unstable_loadExternalState: (state: any) => void;
+  unstable_on<E extends ThreadRuntimeEventType>(
+    event: E,
+    callback: ThreadRuntimeEventCallback<E>,
+  ): Unsubscribe;
 }>;

package/src/runtime/utils/chat-model-adapter.ts

@@ -50,11 +50,6 @@ export type ChatModelRunOptions = {
   readonly abortSignal: AbortSignal;
   readonly context: ModelContext;
 
-  /**
-   * @deprecated This field was renamed to `context`.
-   */
-  readonly config: ModelContext;
-
   readonly unstable_assistantMessageId?: string | undefined;
   readonly unstable_threadId?: string | undefined;
   readonly unstable_parentId?: string | null | undefined;

package/src/runtime/utils/external-store-message.ts

@@ -8,14 +8,6 @@ type WithInnerMessages<T> = {
   [symbolInnerMessages]?: T[];
 };
 
-/**
- * @deprecated Use `getExternalStoreMessages` (plural) instead. This function will be removed in 0.12.0.
- */
-export const getExternalStoreMessage = <T>(input: ThreadMessage) => {
-  const withInnerMessages = input as WithInnerMessages<T>;
-  return withInnerMessages[symbolInnerMessage];
-};
-
 const EMPTY_ARRAY: never[] = [];
 
 /**

package/src/runtimes/assistant-transport/utils.ts

@@ -1,31 +1,3 @@
-import {
-  type Tool,
-  toToolsJSONSchema,
-  type ToolJSONSchema,
-} from "assistant-stream";
-
-/**
- * @deprecated Use `toToolsJSONSchema` from `assistant-stream` instead.
- */
-export function toAISDKTools(
-  tools: Record<string, Tool>,
-): Record<string, ToolJSONSchema> {
-  return toToolsJSONSchema(tools, { filter: () => true });
-}
-
-/**
- * @deprecated Use `toToolsJSONSchema` from `assistant-stream` instead, which includes filtering by default.
- */
-export function getEnabledTools(
-  tools: Record<string, Tool>,
-): Record<string, Tool> {
-  return Object.fromEntries(
-    Object.entries(tools).filter(
-      ([, tool]) => !tool.disabled && tool.type !== "backend",
-    ),
-  );
-}
-
 export async function createRequestHeaders(
   headersValue:
     | Record<string, string>

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

@@ -236,9 +236,9 @@ export class ExternalStoreThreadRuntimeCore
 
     if ((oldStore?.isRunning ?? false) !== (store.isRunning ?? false)) {
       if (store.isRunning) {
-        this._notifyEventSubscribers("runStart");
+        this._notifyEventSubscribers("runStart", {});
       } else {
-        this._notifyEventSubscribers("runEnd");
+        this._notifyEventSubscribers("runEnd", {});
       }
     }
 
@@ -316,10 +316,6 @@ export class ExternalStoreThreadRuntimeCore
     this._store.onLoadExternalState(state);
   }
 
-  public unstable_loadExternalState(state: any): void {
-    this.importExternalState(state);
-  }
-
   public cancelRun(): void {
     if (!this._store.onCancel)
       throw new Error("Runtime does not support cancelling runs.");