@assistant-ui/core 0.1.12 → 0.1.14

package/src/index.ts

@@ -50,6 +50,15 @@ export type {
   Unstable_DirectiveFormatter,
 } from "./types/mention";
 
+export type {
+  Unstable_TriggerItem,
+  Unstable_TriggerCategory,
+} from "./types/trigger";
+
+// === trigger adapter ===
+
+export type { Unstable_TriggerAdapter } from "./adapters/trigger";
+
 // === model-context ===
 
 export type {
@@ -123,6 +132,12 @@ export type { SuggestionAdapter } from "./adapters/suggestion";
 export type { Unstable_MentionAdapter } from "./adapters/mention";
 export { unstable_defaultDirectiveFormatter } from "./adapters/mention";
 
+// Slash command adapter
+export type {
+  Unstable_SlashCommandAdapter,
+  Unstable_SlashCommandItem,
+} from "./adapters/trigger";
+
 // Thread history adapters
 export type {
   ThreadHistoryAdapter,
@@ -150,6 +165,8 @@ export type {
   ComposerRuntimeCore,
   ComposerRuntimeEventType,
   DictationState,
+  EditComposerRuntimeCore,
+  SendOptions,
   ThreadComposerRuntimeCore,
 } from "./runtime/interfaces/composer-runtime-core";
 

package/src/runtime/api/bindings.ts

@@ -2,6 +2,7 @@ import type { ThreadMessage } from "../../types/message";
 import type { SubscribableWithState } from "../../subscribable/subscribable";
 import type {
   ComposerRuntimeCore,
+  EditComposerRuntimeCore,
   ThreadComposerRuntimeCore,
 } from "../interfaces/composer-runtime-core";
 import type {
@@ -21,7 +22,7 @@ export type ThreadComposerRuntimeCoreBinding = SubscribableWithState<
 >;
 
 export type EditComposerRuntimeCoreBinding = SubscribableWithState<
-  ComposerRuntimeCore | undefined,
+  EditComposerRuntimeCore | undefined,
   ComposerRuntimePath & { composerSource: "edit" }
 >;
 

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

@@ -12,9 +12,10 @@ import {
   SKIP_UPDATE,
 } from "../../subscribable/subscribable";
 import type {
-  ComposerRuntimeCore,
   ComposerRuntimeEventType,
   DictationState,
+  EditComposerRuntimeCore,
+  SendOptions,
   ThreadComposerRuntimeCore,
 } from "../interfaces/composer-runtime-core";
 import type {
@@ -68,6 +69,8 @@ export type ThreadComposerState = BaseComposerState & {
 
 export type EditComposerState = BaseComposerState & {
   readonly type: "edit";
+  readonly parentId: string | null;
+  readonly sourceId: string | null;
 };
 
 export type ComposerState = ThreadComposerState | EditComposerState;
@@ -97,7 +100,7 @@ const getThreadComposerState = (
 };
 
 const getEditComposerState = (
-  runtime: ComposerRuntimeCore | undefined,
+  runtime: EditComposerRuntimeCore | undefined,
 ): EditComposerState => {
   return Object.freeze({
     type: "edit",
@@ -114,6 +117,9 @@ const getEditComposerState = (
     dictation: runtime?.dictation,
     quote: runtime?.quote,
 
+    parentId: runtime?.parentId ?? null,
+    sourceId: runtime?.sourceId ?? null,
+
     value: runtime?.text ?? "",
   });
 };
@@ -173,8 +179,9 @@ export type ComposerRuntime = {
 
   /**
    * Send a message. This will send whatever text or attachments are in the composer.
+   * @param options Optional send options. Use `{ startRun: true }` to force starting a new run.
    */
-  send(): void;
+  send(options?: SendOptions): void;
 
   /**
    * Cancel the current run. In edit mode, this will exit edit mode.
@@ -278,10 +285,10 @@ export abstract class ComposerRuntimeImpl implements ComposerRuntime {
     return core.clearAttachments();
   }
 
-  public send() {
+  public send(options?: SendOptions) {
     const core = this._core.getState();
     if (!core) throw new Error("Composer is not available");
-    core.send();
+    core.send(options);
   }
 
   public cancel() {

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

@@ -17,6 +17,7 @@ import type {
   ComposerRuntimeCore,
   ComposerRuntimeEventType,
   DictationState,
+  SendOptions,
 } from "../interfaces/composer-runtime-core";
 import type { DictationAdapter } from "../../adapters/speech";
 import { generateId } from "../../utils/id";
@@ -152,7 +153,7 @@ export abstract class BaseComposerRuntimeCore
     await task;
   }
 
-  public async send() {
+  public async send(options?: SendOptions) {
     if (this.isEmpty) return;
 
     if (this._dictationSession) {
@@ -187,7 +188,7 @@ export abstract class BaseComposerRuntimeCore
       metadata: { custom: { ...(quote ? { quote } : {}) } },
     };
 
-    this.handleSend(message);
+    this.handleSend(message, options);
     this._notifyEventSubscribers("send");
   }
 
@@ -197,6 +198,7 @@ export abstract class BaseComposerRuntimeCore
 
   protected abstract handleSend(
     message: Omit<AppendMessage, "parentId" | "sourceId">,
+    options?: SendOptions,
   ): void;
   protected abstract handleCancel(): void;
 

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

@@ -2,6 +2,7 @@ import type { AppendMessage, ThreadMessage } from "../../types/message";
 import { getThreadMessageText } from "../../utils/text";
 import type { AttachmentAdapter } from "../../adapters/attachment";
 import type { DictationAdapter } from "../../adapters/speech";
+import type { SendOptions } from "../interfaces/composer-runtime-core";
 import type { ThreadRuntimeCore } from "../interfaces/thread-runtime-core";
 import { BaseComposerRuntimeCore } from "./base-composer-runtime-core";
 
@@ -20,8 +21,8 @@ export class DefaultEditComposerRuntimeCore extends BaseComposerRuntimeCore {
 
   private _nonTextParts;
   private _previousText;
-  private _parentId;
-  private _sourceId;
+  private _parentId: string | null;
+  private _sourceId: string | null;
   constructor(
     private runtime: ThreadRuntimeCore & {
       adapters?:
@@ -48,16 +49,26 @@ export class DefaultEditComposerRuntimeCore extends BaseComposerRuntimeCore {
     this.setRunConfig({ ...runtime.composer.runConfig });
   }
 
+  public get parentId() {
+    return this._parentId;
+  }
+
+  public get sourceId() {
+    return this._sourceId;
+  }
+
   public async handleSend(
     message: Omit<AppendMessage, "parentId" | "sourceId">,
+    options?: SendOptions,
   ) {
     const text = getThreadMessageText(message as AppendMessage);
-    if (text !== this._previousText) {
+    if (text !== this._previousText || options?.startRun) {
       this.runtime.append({
         ...message,
         content: [...message.content, ...this._nonTextParts] as any,
         parentId: this._parentId,
         sourceId: this._sourceId,
+        startRun: options?.startRun,
       });
     }
 

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

@@ -1,7 +1,10 @@
 import type { AppendMessage } from "../../types/message";
 import type { AttachmentAdapter } from "../../adapters/attachment";
 import type { DictationAdapter } from "../../adapters/speech";
-import type { ThreadComposerRuntimeCore } from "../interfaces/composer-runtime-core";
+import type {
+  SendOptions,
+  ThreadComposerRuntimeCore,
+} from "../interfaces/composer-runtime-core";
 import type { ThreadRuntimeCore } from "../interfaces/thread-runtime-core";
 import { BaseComposerRuntimeCore } from "./base-composer-runtime-core";
 
@@ -47,11 +50,13 @@ export class DefaultThreadComposerRuntimeCore
 
   public async handleSend(
     message: Omit<AppendMessage, "parentId" | "sourceId">,
+    options?: SendOptions,
   ) {
     this.runtime.append({
       ...(message as AppendMessage),
       parentId: this.runtime.messages.at(-1)?.id ?? null,
       sourceId: null,
+      startRun: options?.startRun,
     });
   }
 

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

@@ -16,6 +16,10 @@ export type DictationState = {
   readonly inputDisabled?: boolean;
 };
 
+export type SendOptions = {
+  startRun?: boolean;
+};
+
 export type ComposerRuntimeCore = Readonly<{
   isEditing: boolean;
 
@@ -43,7 +47,7 @@ export type ComposerRuntimeCore = Readonly<{
   reset: () => Promise<void>;
   clearAttachments: () => Promise<void>;
 
-  send: () => void;
+  send: (options?: SendOptions) => void;
   cancel: () => void;
 
   dictation: DictationState | undefined;
@@ -59,3 +63,9 @@ export type ComposerRuntimeCore = Readonly<{
 }>;
 
 export type ThreadComposerRuntimeCore = ComposerRuntimeCore;
+
+export type EditComposerRuntimeCore = ComposerRuntimeCore &
+  Readonly<{
+    parentId: string | null;
+    sourceId: string | null;
+  }>;

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

@@ -12,7 +12,7 @@ import type {
 import type { ExportedMessageRepository } from "../utils/message-repository";
 import type { ThreadMessageLike } from "../utils/thread-message-like";
 import type {
-  ComposerRuntimeCore,
+  EditComposerRuntimeCore,
   ThreadComposerRuntimeCore,
 } from "./composer-runtime-core";
 
@@ -120,7 +120,7 @@ export type ThreadRuntimeCore = Readonly<{
   getModelContext: () => ModelContext;
 
   composer: ThreadComposerRuntimeCore;
-  getEditComposer: (messageId: string) => ComposerRuntimeCore | undefined;
+  getEditComposer: (messageId: string) => EditComposerRuntimeCore | undefined;
   beginEdit: (messageId: string) => void;
 
   speech: SpeechState | undefined;

package/src/runtime/utils/message-repository.ts

@@ -39,6 +39,32 @@ export const ExportedMessageRepository = {
       })),
     };
   },
+
+  fromBranchableArray: (
+    items: readonly {
+      message: ThreadMessageLike;
+      parentId: string | null;
+    }[],
+    options?: { headId?: string | null },
+  ): ExportedMessageRepository => {
+    const fallbackStatus = getAutoStatus(false, false, false, false, undefined);
+    return {
+      ...(options?.headId !== undefined
+        ? { headId: options.headId }
+        : undefined),
+      messages: items.map(({ message, parentId }) => {
+        if (!message.id) {
+          throw new Error(
+            "ExportedMessageRepository.fromBranchableArray: Each message must have an 'id' field set.",
+          );
+        }
+        return {
+          parentId,
+          message: fromThreadMessageLike(message, message.id, fallbackStatus),
+        };
+      }),
+    };
+  },
 };
 
 type RepositoryParent = {

package/src/store/scopes/composer.ts

@@ -3,11 +3,14 @@ import type { MessageRole } from "../../types/message";
 import type { QuoteInfo } from "../../types/quote";
 import type { RunConfig } from "../../types/message";
 import type { ComposerRuntime } from "../../runtime/api/composer-runtime";
-import type { DictationState } from "../../runtime/interfaces/composer-runtime-core";
+import type {
+  DictationState,
+  SendOptions,
+} from "../../runtime/interfaces/composer-runtime-core";
 import type { AttachmentMethods } from "./attachment";
 import type { QueueItemState, QueueItemMethods } from "./queue-item";
 
-export type ComposerSendOptions = {
+export type ComposerSendOptions = SendOptions & {
   /**
    * Whether to steer (interrupt the current run and process this message immediately).
    * When false (default), the message is queued and processed in order.

package/src/tests/MessageRepository.test.ts

@@ -457,6 +457,147 @@ describe("MessageRepository", () => {
     });
   });
 
+  describe("ExportedMessageRepository.fromBranchableArray", () => {
+    it("should create a branching tree structure", () => {
+      const items = [
+        {
+          message: {
+            id: "user-1",
+            role: "user" as const,
+            content: [{ type: "text" as const, text: "Hello" }],
+          },
+          parentId: null,
+        },
+        {
+          message: {
+            id: "assistant-1",
+            role: "assistant" as const,
+            content: [{ type: "text" as const, text: "Hi there" }],
+          },
+          parentId: "user-1",
+        },
+        {
+          message: {
+            id: "assistant-2",
+            role: "assistant" as const,
+            content: [{ type: "text" as const, text: "Hey!" }],
+          },
+          parentId: "user-1",
+        },
+      ];
+
+      const result = ExportedMessageRepository.fromBranchableArray(items);
+
+      expect(result.messages).toHaveLength(3);
+      expect(result.messages[0]!.parentId).toBeNull();
+      expect(result.messages[0]!.message.id).toBe("user-1");
+      expect(result.messages[1]!.parentId).toBe("user-1");
+      expect(result.messages[1]!.message.id).toBe("assistant-1");
+      expect(result.messages[2]!.parentId).toBe("user-1");
+      expect(result.messages[2]!.message.id).toBe("assistant-2");
+    });
+
+    it("should support headId option", () => {
+      const items = [
+        {
+          message: {
+            id: "msg-1",
+            role: "user" as const,
+            content: [{ type: "text" as const, text: "Hello" }],
+          },
+          parentId: null,
+        },
+        {
+          message: {
+            id: "msg-2a",
+            role: "assistant" as const,
+            content: [{ type: "text" as const, text: "Branch A" }],
+          },
+          parentId: "msg-1",
+        },
+        {
+          message: {
+            id: "msg-2b",
+            role: "assistant" as const,
+            content: [{ type: "text" as const, text: "Branch B" }],
+          },
+          parentId: "msg-1",
+        },
+      ];
+
+      const result = ExportedMessageRepository.fromBranchableArray(items, {
+        headId: "msg-2b",
+      });
+
+      expect(result.headId).toBe("msg-2b");
+    });
+
+    it("should throw if a message has no id", () => {
+      const items = [
+        {
+          message: {
+            role: "user" as const,
+            content: [{ type: "text" as const, text: "Hello" }],
+          },
+          parentId: null,
+        },
+      ];
+
+      expect(() =>
+        ExportedMessageRepository.fromBranchableArray(items),
+      ).toThrow(/Each message must have an 'id' field set/);
+    });
+
+    it("should handle empty arrays", () => {
+      const result = ExportedMessageRepository.fromBranchableArray([]);
+      expect(result.messages).toHaveLength(0);
+    });
+
+    it("should work with MessageRepository.import for branch switching", () => {
+      const items = [
+        {
+          message: {
+            id: "user-1",
+            role: "user" as const,
+            content: [{ type: "text" as const, text: "Hello" }],
+          },
+          parentId: null,
+        },
+        {
+          message: {
+            id: "assistant-a",
+            role: "assistant" as const,
+            content: [{ type: "text" as const, text: "Response A" }],
+          },
+          parentId: "user-1",
+        },
+        {
+          message: {
+            id: "assistant-b",
+            role: "assistant" as const,
+            content: [{ type: "text" as const, text: "Response B" }],
+          },
+          parentId: "user-1",
+        },
+      ];
+
+      const repo = ExportedMessageRepository.fromBranchableArray(items, {
+        headId: "assistant-a",
+      });
+
+      repository.import(repo);
+
+      // Should show branch A
+      let messages = repository.getMessages();
+      expect(messages.map((m) => m.id)).toEqual(["user-1", "assistant-a"]);
+
+      // Switch to branch B
+      repository.switchToBranch("assistant-b");
+      messages = repository.getMessages();
+      expect(messages.map((m) => m.id)).toEqual(["user-1", "assistant-b"]);
+    });
+  });
+
   describe("Complex scenarios", () => {
     it("should maintain tree structure after deletions", () => {
       const root = createTestMessage({ id: "root-id" });

package/src/types/index.ts

@@ -45,3 +45,8 @@ export type {
   Unstable_DirectiveSegment,
   Unstable_DirectiveFormatter,
 } from "./mention";
+
+export type {
+  Unstable_TriggerItem,
+  Unstable_TriggerCategory,
+} from "./trigger";

package/src/types/mention.ts

@@ -1,27 +1,16 @@
-import type { ReadonlyJSONObject } from "assistant-stream/utils";
+import type { Unstable_TriggerItem, Unstable_TriggerCategory } from "./trigger";
 
 // =============================================================================
-// Mention Item (user-facing definition for items that can be @-mentioned)
+// Mention Item — alias of the generic TriggerItem for backward compatibility
 // =============================================================================
 
-export type Unstable_MentionItem = {
-  readonly id: string;
-  readonly type: string;
-  readonly label: string;
-  readonly icon?: string | undefined;
-  readonly description?: string | undefined;
-  readonly metadata?: ReadonlyJSONObject | undefined;
-};
+export type Unstable_MentionItem = Unstable_TriggerItem;
 
 // =============================================================================
-// Mention Category (for hierarchical navigation)
+// Mention Category — alias of the generic TriggerCategory
 // =============================================================================
 
-export type Unstable_MentionCategory = {
-  readonly id: string;
-  readonly label: string;
-  readonly icon?: string | undefined;
-};
+export type Unstable_MentionCategory = Unstable_TriggerCategory;
 
 // =============================================================================
 // Directive Segment (parsed representation of mention directives in text)

package/src/types/trigger.ts

@@ -0,0 +1,24 @@
+import type { ReadonlyJSONObject } from "assistant-stream/utils";
+
+// =============================================================================
+// Trigger Item (generic item for any trigger-based popover: @mention, /command)
+// =============================================================================
+
+export type Unstable_TriggerItem = {
+  readonly id: string;
+  readonly type: string;
+  readonly label: string;
+  readonly icon?: string | undefined;
+  readonly description?: string | undefined;
+  readonly metadata?: ReadonlyJSONObject | undefined;
+};
+
+// =============================================================================
+// Trigger Category (for hierarchical navigation in trigger popovers)
+// =============================================================================
+
+export type Unstable_TriggerCategory = {
+  readonly id: string;
+  readonly label: string;
+  readonly icon?: string | undefined;
+};