@assistant-ui/core 0.1.16 → 0.1.17

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

@@ -21,6 +21,8 @@ import type {
   SpeechState,
   VoiceSessionState,
   RuntimeCapabilities,
+  ThreadRuntimeEventCallback,
+  ThreadRuntimeEventPayload,
   ThreadRuntimeEventType,
   StartRunConfig,
   ResumeRunConfig,
@@ -168,11 +170,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 +437,7 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
   protected ensureInitialized() {
     if (!this._isInitialized) {
       this._isInitialized = true;
-      this._notifyEventSubscribers("initialize");
+      this._notifyEventSubscribers("initialize", {});
     }
   }
 
@@ -453,24 +458,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-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,7 +185,15 @@ export type ThreadRuntimeCore = Readonly<{
 
   reset(initialMessages?: readonly ThreadMessageLike[]): void;
 
-  unstable_on(event: ThreadRuntimeEventType, callback: () => void): Unsubscribe;
+  /**
+   * @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 ThreadRuntimeEventType>(
+    event: E,
+    callback: ThreadRuntimeEventCallback<E>,
+  ): Unsubscribe;
 
   /**
    * @deprecated Use importExternalState instead. This method will be removed in 0.12.0.

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", {});
       }
     }
 

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

@@ -253,7 +253,7 @@ export class LocalThreadRuntimeCore
       createdAt: new Date(),
     };
 
-    this._notifyEventSubscribers("runStart");
+    this._notifyEventSubscribers("runStart", {});
 
     try {
       this._suggestions = [];
@@ -271,7 +271,7 @@ export class LocalThreadRuntimeCore
         runCallback = undefined;
       } while (shouldContinue(message, this._options.unstable_humanToolNames));
     } finally {
-      this._notifyEventSubscribers("runEnd");
+      this._notifyEventSubscribers("runEnd", {});
     }
 
     this._suggestionsController = new AbortController();

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

@@ -63,19 +63,15 @@ export const ComposerClient = resource(
         unsubscribers.push(unsubscribe);
       }
 
-      // attachmentAddError carries the failed attachment ID
       unsubscribers.push(
-        runtime.unstable_on("attachmentAddError", () => {
-          const errorAttachment = runtime
-            .getState()
-            .attachments.findLast(
-              (a) =>
-                a.status.type === "incomplete" && a.status.reason === "error",
-            );
+        runtime.unstable_on("attachmentAddError", (payload) => {
+          // payload.error omitted: raw Error is not store-serializable; use runtime.unstable_on for it.
           emit("composer.attachmentAddError", {
             threadId: threadIdRef.current,
             ...(messageIdRef && { messageId: messageIdRef.current }),
-            ...(errorAttachment && { attachmentId: errorAttachment.id }),
+            ...(payload.attachmentId && { attachmentId: payload.attachmentId }),
+            reason: payload.reason,
+            message: payload.message,
           });
         }),
       );

package/src/store/scopes/composer.ts

@@ -4,6 +4,7 @@ import type { QuoteInfo } from "../../types/quote";
 import type { RunConfig } from "../../types/message";
 import type { ComposerRuntime } from "../../runtime/api/composer-runtime";
 import type {
+  AttachmentAddErrorReason,
   DictationState,
   SendOptions,
 } from "../../runtime/interfaces/composer-runtime-core";
@@ -91,12 +92,22 @@ export type ComposerMeta = {
 };
 
 export type ComposerEvents = {
+  /**
+   * @deprecated State-derivable. Observe composer `text` clearing via
+   * `useAuiState` instead. Kept for backward compatibility.
+   */
   "composer.send": { threadId: string; messageId?: string };
+  /**
+   * @deprecated State-derivable. Observe composer `attachments` via
+   * `useAuiState` instead. Kept for backward compatibility.
+   */
   "composer.attachmentAdd": { threadId: string; messageId?: string };
   "composer.attachmentAddError": {
     threadId: string;
     messageId?: string;
     attachmentId?: string;
+    reason: AttachmentAddErrorReason;
+    message: string;
   };
 };
 

package/src/store/scopes/thread-list-item.ts

@@ -32,7 +32,17 @@ export type ThreadListItemMeta = {
 };
 
 export type ThreadListItemEvents = {
+  /**
+   * @deprecated State-derivable. Compare `s.threads.mainThreadId` against the
+   * item's `s.threadListItem.id` via `useAuiState` instead. Kept for backward
+   * compatibility.
+   */
   "threadListItem.switchedTo": { threadId: string };
+  /**
+   * @deprecated State-derivable. Compare `s.threads.mainThreadId` against the
+   * item's `s.threadListItem.id` via `useAuiState` instead. Kept for backward
+   * compatibility.
+   */
   "threadListItem.switchedAway": { threadId: string };
 };
 

package/src/store/scopes/thread.ts

@@ -130,9 +130,26 @@ export type ThreadMeta = {
 };
 
 export type ThreadEvents = {
+  /**
+   * @deprecated State-derivable. Observe `isRunning` flipping to `true` via
+   * `useAuiState` instead. Kept for backward compatibility.
+   */
   "thread.runStart": { threadId: string };
+  /**
+   * @deprecated State-derivable. Observe `isRunning` flipping to `false` via
+   * `useAuiState` instead. Kept for backward compatibility.
+   */
   "thread.runEnd": { threadId: string };
+  /**
+   * @deprecated State-derivable. This event fires before the first message is
+   * added; observe `messages` becoming non-empty via `useAuiState` instead of
+   * reading state inside this event handler. Kept for backward compatibility.
+   */
   "thread.initialize": { threadId: string };
+  /**
+   * Truly transient. Model context lives in a provider, not in thread state,
+   * so this event has no state-derivable equivalent.
+   */
   "thread.modelContextUpdate": { threadId: string };
 };
 

package/src/subscribable/subscribable.ts

@@ -21,7 +21,10 @@ export type EventSubscribable<TEvent extends string> = {
   event: TEvent;
   binding: SubscribableWithState<
     | {
-        unstable_on: (event: TEvent, callback: () => void) => Unsubscribe;
+        unstable_on: (
+          event: TEvent,
+          callback: (payload?: unknown) => void,
+        ) => Unsubscribe;
       }
     | undefined,
     unknown
@@ -87,7 +90,7 @@ export class BaseSubscribable {
 
 // lazy connect/disconnect: only opens upstream subscription while it has subscribers
 export abstract class BaseSubject {
-  private _subscriptions = new Set<() => void>();
+  private _subscriptions = new Set<(payload?: unknown) => void>();
   private _connection: Unsubscribe | undefined;
 
   protected get isConnected() {
@@ -96,8 +99,8 @@ export abstract class BaseSubject {
 
   protected abstract _connect(): Unsubscribe;
 
-  protected notifySubscribers() {
-    for (const callback of this._subscriptions) callback();
+  protected notifySubscribers(payload?: unknown) {
+    for (const callback of this._subscriptions) callback(payload);
   }
 
   private _updateConnection() {
@@ -110,7 +113,7 @@ export abstract class BaseSubject {
     }
   }
 
-  public subscribe(callback: () => void) {
+  public subscribe(callback: (payload?: unknown) => void) {
     this._subscriptions.add(callback);
     this._updateConnection();
 
@@ -270,8 +273,8 @@ export class EventSubscriptionSubject<
   }
 
   protected _connect(): Unsubscribe {
-    const callback = () => {
-      this.notifySubscribers();
+    const callback = (payload?: unknown) => {
+      this.notifySubscribers(payload);
     };
 
     let lastState = this.config.binding.getState();

package/src/tests/base-composer-runtime-core-addAttachment.test.ts

@@ -48,6 +48,13 @@ describe("BaseComposerRuntimeCore.addAttachment error events", () => {
     ).rejects.toThrow("Attachments are not supported");
 
     expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        reason: "no-adapter",
+        message: "Attachments are not supported",
+        error: expect.any(Error),
+      }),
+    );
     expect(onAdd).not.toHaveBeenCalled();
   });
 
@@ -63,6 +70,15 @@ describe("BaseComposerRuntimeCore.addAttachment error events", () => {
     ).rejects.toThrow(/File type text\/plain is not accepted/);
 
     expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        reason: "not-accepted",
+        message: expect.stringContaining(
+          "File type text/plain is not accepted",
+        ),
+        error: expect.any(Error),
+      }),
+    );
     expect(onAdd).not.toHaveBeenCalled();
   });
 
@@ -84,6 +100,13 @@ describe("BaseComposerRuntimeCore.addAttachment error events", () => {
     ).rejects.toThrow("upload failed");
 
     expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        reason: "adapter-error",
+        message: "upload failed",
+        error: expect.any(Error),
+      }),
+    );
     expect(onAdd).not.toHaveBeenCalled();
   });
 
@@ -143,6 +166,14 @@ describe("BaseComposerRuntimeCore.addAttachment error events", () => {
     ).rejects.toThrow("network error");
 
     expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        reason: "adapter-error",
+        message: "network error",
+        attachmentId: "att-1",
+        error: expect.any(Error),
+      }),
+    );
     expect(onAdd).not.toHaveBeenCalled();
     expect(composer.attachments).toHaveLength(1);
     const att = composer.attachments[0]!;
@@ -151,4 +182,36 @@ describe("BaseComposerRuntimeCore.addAttachment error events", () => {
       expect(att.status.reason).toBe("error");
     }
   });
+
+  it("emits attachmentAddError with attachment id when adapter yields an errored attachment", async () => {
+    const composer = makeComposer(
+      makeAdapter({
+        add: async ({ file }) => ({
+          id: "att-2",
+          type: "image",
+          name: file.name,
+          contentType: file.type,
+          file,
+          status: { type: "incomplete", reason: "error" },
+        }),
+      }),
+    );
+    const onError = vi.fn();
+    const onAdd = vi.fn();
+    composer.unstable_on("attachmentAddError", onError);
+    composer.unstable_on("attachmentAdd", onAdd);
+
+    await composer.addAttachment(
+      new File(["x"], "f.png", { type: "image/png" }),
+    );
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        reason: "adapter-error",
+        attachmentId: "att-2",
+      }),
+    );
+    expect(onAdd).not.toHaveBeenCalled();
+  });
 });

package/src/tests/groupParts.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildGroupTree,
+  normalizeGroupKey,
+  type GroupNode,
+} from "../react/utils/groupParts";
+
+const asPaths = (keys: readonly (string | readonly string[] | null)[]) =>
+  keys.map((k) => normalizeGroupKey(k));
+
+// Compact tree dump: "G:key#nodeKey[i,j]{...}" | "P:#nodeKey(i)"
+const dump = (nodes: readonly GroupNode[]): string =>
+  nodes
+    .map((n) => {
+      if (n.type === "part") {
+        return `P:#${n.nodeKey}(${n.index})`;
+      }
+      const inner = dump(n.children);
+      return `G:${n.key}#${n.nodeKey}[${n.indices.join(",")}]{${inner}}`;
+    })
+    .join(",");
+
+describe("normalizeGroupKey", () => {
+  it("maps null/undefined/[] to []", () => {
+    expect(normalizeGroupKey(null)).toEqual([]);
+    expect(normalizeGroupKey(undefined)).toEqual([]);
+    expect(normalizeGroupKey([])).toEqual([]);
+  });
+
+  it("wraps a string into a single-element array", () => {
+    expect(normalizeGroupKey("foo")).toEqual(["foo"]);
+  });
+
+  it("passes arrays through", () => {
+    expect(normalizeGroupKey(["a", "b"])).toEqual(["a", "b"]);
+  });
+});
+
+describe("buildGroupTree", () => {
+  it("returns an empty list for no parts", () => {
+    expect(buildGroupTree([])).toEqual([]);
+  });
+
+  it("emits one part leaf per ungrouped part (no coalescing)", () => {
+    const tree = buildGroupTree(asPaths([null, null, null]));
+    expect(dump(tree)).toBe("P:#0(0),P:#1(1),P:#2(2)");
+  });
+
+  it("wraps adjacent same-key parts in one group with one part child each", () => {
+    const tree = buildGroupTree(asPaths(["a", "a", "a"]));
+    expect(dump(tree)).toBe("G:a#0[0,1,2]{P:#0.0(0),P:#0.1(1),P:#0.2(2)}");
+  });
+
+  it("splits non-adjacent runs of the same key into separate groups", () => {
+    const tree = buildGroupTree(asPaths(["a", null, "a"]));
+    expect(dump(tree)).toBe("G:a#0[0]{P:#0.0(0)},P:#1(1),G:a#2[2]{P:#2.0(2)}");
+  });
+
+  it("nests groups: parts at depth 1 sit alongside depth-2 subgroups", () => {
+    // ["A","B"], ["A","B"], ["A"], ["A"], ["A","C"]:
+    // Outer A spans 0..4. Inside A: a B subgroup (0,1), two depth-1 parts
+    // (2,3), then a C subgroup (4).
+    const tree = buildGroupTree(
+      asPaths([["A", "B"], ["A", "B"], ["A"], ["A"], ["A", "C"]]),
+    );
+    expect(dump(tree)).toBe(
+      "G:A#0[0,1,2,3,4]{G:B#0.0[0,1]{P:#0.0.0(0),P:#0.0.1(1)},P:#0.1(2),P:#0.2(3),G:C#0.3[4]{P:#0.3.0(4)}}",
+    );
+  });
+
+  it("treats longer prefix changes as group close+open", () => {
+    // ["A","B"], ["A","B","C"], ["A","B"]: opens C under B, closes back.
+    const tree = buildGroupTree(
+      asPaths([
+        ["A", "B"],
+        ["A", "B", "C"],
+        ["A", "B"],
+      ]),
+    );
+    expect(dump(tree)).toBe(
+      "G:A#0[0,1,2]{G:B#0.0[0,1,2]{P:#0.0.0(0),G:C#0.0.1[1]{P:#0.0.1.0(1)},P:#0.0.2(2)}}",
+    );
+  });
+
+  it("does not coalesce same-keyed groups separated by a divergent sibling", () => {
+    const tree = buildGroupTree(
+      asPaths([
+        ["A", "B"],
+        ["A", "C"],
+        ["A", "B"],
+      ]),
+    );
+    expect(dump(tree)).toBe(
+      "G:A#0[0,1,2]{G:B#0.0[0]{P:#0.0.0(0)},G:C#0.1[1]{P:#0.1.0(1)},G:B#0.2[2]{P:#0.2.0(2)}}",
+    );
+  });
+
+  it("accepts strings and arrays interchangeably via normalizeGroupKey", () => {
+    const tree = buildGroupTree([
+      normalizeGroupKey("A"),
+      normalizeGroupKey(["A"]),
+    ]);
+    expect(dump(tree)).toBe("G:A#0[0,1]{P:#0.0(0),P:#0.1(1)}");
+  });
+
+  it("assigns stable nodeKeys under append (existing keys do not shift)", () => {
+    const before = buildGroupTree(asPaths([["A"], null]));
+    const after = buildGroupTree(asPaths([["A"], null, ["B"]]));
+
+    expect(before[0]!.nodeKey).toBe(after[0]!.nodeKey);
+    expect(before[1]!.nodeKey).toBe(after[1]!.nodeKey);
+    expect(after[2]!.nodeKey).toBe("2");
+  });
+});