@assistant-ui/core 0.1.0

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

@@ -0,0 +1,65 @@
+import type { AppendMessage, PendingAttachment } from "../../types";
+import type { AttachmentAdapter } from "../../adapters/attachment";
+import type { DictationAdapter } from "../../adapters/speech";
+import type { ThreadComposerRuntimeCore } from "../interfaces/composer-runtime-core";
+import type { ThreadRuntimeCore } from "../interfaces/thread-runtime-core";
+import { BaseComposerRuntimeCore } from "./base-composer-runtime-core";
+
+export class DefaultThreadComposerRuntimeCore
+  extends BaseComposerRuntimeCore
+  implements ThreadComposerRuntimeCore
+{
+  private _canCancel = false;
+  public get canCancel() {
+    return this._canCancel;
+  }
+
+  public override get attachments(): readonly PendingAttachment[] {
+    return super.attachments as readonly PendingAttachment[];
+  }
+
+  protected getAttachmentAdapter() {
+    return this.runtime.adapters?.attachments;
+  }
+
+  protected getDictationAdapter() {
+    return this.runtime.adapters?.dictation;
+  }
+
+  constructor(
+    private runtime: Omit<ThreadRuntimeCore, "composer"> & {
+      adapters?:
+        | {
+            attachments?: AttachmentAdapter | undefined;
+            dictation?: DictationAdapter | undefined;
+          }
+        | undefined;
+    },
+  ) {
+    super();
+    this.connect();
+  }
+
+  public connect() {
+    return this.runtime.subscribe(() => {
+      if (this.canCancel !== this.runtime.capabilities.cancel) {
+        this._canCancel = this.runtime.capabilities.cancel;
+        this._notifySubscribers();
+      }
+    });
+  }
+
+  public async handleSend(
+    message: Omit<AppendMessage, "parentId" | "sourceId">,
+  ) {
+    this.runtime.append({
+      ...(message as AppendMessage),
+      parentId: this.runtime.messages.at(-1)?.id ?? null,
+      sourceId: null,
+    });
+  }
+
+  public async handleCancel() {
+    this.runtime.cancelRun();
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,108 @@
+// =============================================================================
+// Public API — types and values that end users may import
+// =============================================================================
+
+// Path Types
+export type {
+  ThreadListItemRuntimePath,
+  ThreadRuntimePath,
+  MessageRuntimePath,
+  MessagePartRuntimePath,
+  AttachmentRuntimePath,
+  ComposerRuntimePath,
+} from "./api/paths";
+
+// Runtime Core Interface Types
+export type {
+  ComposerRuntimeCore,
+  ComposerRuntimeEventType,
+  DictationState,
+  ThreadComposerRuntimeCore,
+} from "./interfaces/composer-runtime-core";
+
+export type {
+  RuntimeCapabilities,
+  AddToolResultOptions,
+  ResumeToolCallOptions,
+  SubmitFeedbackOptions,
+  ThreadSuggestion,
+  SpeechState,
+  SubmittedFeedback,
+  ThreadRuntimeEventType,
+  StartRunConfig,
+  ResumeRunConfig,
+  ThreadRuntimeCore,
+} from "./interfaces/thread-runtime-core";
+
+export type {
+  ThreadListItemStatus,
+  ThreadListItemCoreState,
+  ThreadListRuntimeCore,
+} from "./interfaces/thread-list-runtime-core";
+
+export type { AssistantRuntimeCore } from "./interfaces/assistant-runtime-core";
+
+// Public Runtime Types
+export type { AssistantRuntime } from "./api/assistant-runtime";
+
+export type {
+  CreateStartRunConfig,
+  CreateResumeRunConfig,
+  CreateAppendMessage,
+  ThreadState,
+  ThreadRuntime,
+} from "./api/thread-runtime";
+
+export type {
+  ThreadListState,
+  ThreadListRuntime,
+} from "./api/thread-list-runtime";
+
+export type {
+  ThreadListItemEventType,
+  ThreadListItemRuntime,
+} from "./api/thread-list-item-runtime";
+
+export type { ThreadListItemState } from "./api/bindings";
+
+export type { MessageState, MessageRuntime } from "./api/message-runtime";
+export type {
+  MessagePartState,
+  MessagePartRuntime,
+} from "./api/message-part-runtime";
+
+export type {
+  ThreadComposerState,
+  EditComposerState,
+  ComposerState,
+  ComposerRuntime,
+  ThreadComposerRuntime,
+  EditComposerRuntime,
+} from "./api/composer-runtime";
+
+export type {
+  AttachmentState,
+  AttachmentRuntime,
+} from "./api/attachment-runtime";
+
+// ChatModel Types
+export type {
+  ChatModelRunUpdate,
+  ChatModelRunResult,
+  CoreChatModelRunResult,
+  ChatModelRunOptions,
+  ChatModelAdapter,
+} from "./utils/chat-model-adapter";
+
+// ThreadMessageLike
+export type { ThreadMessageLike } from "./utils/thread-message-like";
+
+// External Store Message Utilities
+export {
+  getExternalStoreMessage,
+  getExternalStoreMessages,
+} from "./utils/external-store-message";
+
+// ExportedMessageRepository
+export type { ExportedMessageRepositoryItem } from "./utils/message-repository";
+export { ExportedMessageRepository } from "./utils/message-repository";

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

@@ -0,0 +1,12 @@
+import type { Unsubscribe } from "../../types";
+import type { ModelContextProvider } from "../../model-context";
+import type { ThreadListRuntimeCore } from "./thread-list-runtime-core";
+
+export type AssistantRuntimeCore = {
+  readonly threads: ThreadListRuntimeCore;
+
+  registerModelContextProvider: (provider: ModelContextProvider) => Unsubscribe;
+  getModelContextProvider: () => ModelContextProvider;
+
+  readonly RenderComponent?: ((...args: any[]) => unknown) | undefined;
+};

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

@@ -0,0 +1,64 @@
+import type {
+  MessageRole,
+  RunConfig,
+  QuoteInfo,
+  Attachment,
+  PendingAttachment,
+  Unsubscribe,
+} from "../../types";
+import type { DictationAdapter } from "../../adapters/speech";
+
+export type ComposerRuntimeEventType = "send" | "attachmentAdd";
+
+export type DictationState = {
+  readonly status: DictationAdapter.Status;
+  readonly transcript?: string;
+  readonly inputDisabled?: boolean;
+};
+
+export type ComposerRuntimeCore = Readonly<{
+  isEditing: boolean;
+
+  canCancel: boolean;
+  isEmpty: boolean;
+
+  attachments: readonly Attachment[];
+  attachmentAccept: string;
+
+  addAttachment: (file: File) => Promise<void>;
+  removeAttachment: (attachmentId: string) => Promise<void>;
+
+  text: string;
+  setText: (value: string) => void;
+
+  role: MessageRole;
+  setRole: (role: MessageRole) => void;
+
+  runConfig: RunConfig;
+  setRunConfig: (runConfig: RunConfig) => void;
+
+  quote: QuoteInfo | undefined;
+  setQuote: (quote: QuoteInfo | undefined) => void;
+
+  reset: () => Promise<void>;
+  clearAttachments: () => Promise<void>;
+
+  send: () => void;
+  cancel: () => void;
+
+  dictation: DictationState | undefined;
+  startDictation: () => void;
+  stopDictation: () => void;
+
+  subscribe: (callback: () => void) => Unsubscribe;
+
+  unstable_on: (
+    event: ComposerRuntimeEventType,
+    callback: () => void,
+  ) => Unsubscribe;
+}>;
+
+export type ThreadComposerRuntimeCore = ComposerRuntimeCore &
+  Readonly<{
+    attachments: readonly PendingAttachment[];
+  }>;

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

@@ -0,0 +1,49 @@
+import type { Unsubscribe } from "../../types";
+import type { ThreadRuntimeCore } from "./thread-runtime-core";
+
+export type ThreadListItemStatus = "archived" | "regular" | "new" | "deleted";
+
+export type ThreadListItemCoreState = {
+  readonly id: string;
+  readonly remoteId: string | undefined;
+  readonly externalId: string | undefined;
+
+  readonly status: ThreadListItemStatus;
+  readonly title?: string | undefined;
+
+  readonly runtime?: ThreadRuntimeCore | undefined;
+};
+
+export type ThreadListRuntimeCore = {
+  readonly isLoading: boolean;
+  mainThreadId: string;
+  newThreadId: string | undefined;
+
+  threadIds: readonly string[];
+  archivedThreadIds: readonly string[];
+
+  readonly threadItems: Readonly<Record<string, ThreadListItemCoreState>>;
+
+  getMainThreadRuntimeCore(): ThreadRuntimeCore;
+  getThreadRuntimeCore(threadId: string): ThreadRuntimeCore;
+
+  getItemById(threadId: string): ThreadListItemCoreState | undefined;
+
+  switchToThread(threadId: string): Promise<void>;
+  switchToNewThread(): Promise<void>;
+
+  getLoadThreadsPromise(): Promise<void>;
+
+  detach(threadId: string): Promise<void>;
+  rename(threadId: string, newTitle: string): Promise<void>;
+  archive(threadId: string): Promise<void>;
+  unarchive(threadId: string): Promise<void>;
+  delete(threadId: string): Promise<void>;
+
+  initialize(
+    threadId: string,
+  ): Promise<{ remoteId: string; externalId: string | undefined }>;
+  generateTitle(threadId: string): Promise<void>;
+
+  subscribe(callback: () => void): Unsubscribe;
+};

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

@@ -0,0 +1,142 @@
+import type { ReadonlyJSONValue } from "assistant-stream/utils";
+import type { ModelContext } from "../../model-context";
+import type {
+  RunConfig,
+  Unsubscribe,
+  AppendMessage,
+  ThreadMessage,
+} from "../../types";
+import type { SpeechSynthesisAdapter } from "../../adapters/speech";
+import type {
+  ChatModelRunOptions,
+  ChatModelRunResult,
+} from "../utils/chat-model-adapter";
+import type { ExportedMessageRepository } from "../utils/message-repository";
+import type { ThreadMessageLike } from "../utils/thread-message-like";
+import type {
+  ComposerRuntimeCore,
+  ThreadComposerRuntimeCore,
+} from "./composer-runtime-core";
+
+export type RuntimeCapabilities = {
+  readonly switchToBranch: boolean;
+  readonly switchBranchDuringRun: boolean;
+  readonly edit: boolean;
+  readonly reload: boolean;
+  readonly cancel: boolean;
+  readonly unstable_copy: boolean;
+  readonly speech: boolean;
+  readonly dictation: boolean;
+  readonly attachments: boolean;
+  readonly feedback: boolean;
+};
+
+export type AddToolResultOptions = {
+  messageId: string;
+  toolName: string;
+  toolCallId: string;
+  result: ReadonlyJSONValue;
+  isError: boolean;
+  artifact?: ReadonlyJSONValue | undefined;
+};
+
+export type ResumeToolCallOptions = {
+  toolCallId: string;
+  payload: unknown;
+};
+
+export type SubmitFeedbackOptions = {
+  messageId: string;
+  type: "negative" | "positive";
+};
+
+export type ThreadSuggestion = {
+  prompt: string;
+};
+
+export type SpeechState = {
+  readonly messageId: string;
+  readonly status: SpeechSynthesisAdapter.Status;
+};
+
+export type SubmittedFeedback = {
+  readonly type: "negative" | "positive";
+};
+
+export type ThreadRuntimeEventType =
+  | "runStart"
+  | "runEnd"
+  | "initialize"
+  | "modelContextUpdate";
+
+export type StartRunConfig = {
+  parentId: string | null;
+  sourceId: string | null;
+  runConfig: RunConfig;
+};
+
+export type ResumeRunConfig = StartRunConfig & {
+  stream?: (
+    options: ChatModelRunOptions,
+  ) => AsyncGenerator<ChatModelRunResult, void, unknown>;
+};
+
+export type ThreadRuntimeCore = Readonly<{
+  getMessageById: (messageId: string) =>
+    | {
+        parentId: string | null;
+        message: ThreadMessage;
+        index: number;
+      }
+    | undefined;
+
+  getBranches: (messageId: string) => readonly string[];
+  switchToBranch: (branchId: string) => void;
+
+  append: (message: AppendMessage) => void;
+  startRun: (config: StartRunConfig) => void;
+  resumeRun: (config: ResumeRunConfig) => void;
+  cancelRun: () => void;
+
+  addToolResult: (options: AddToolResultOptions) => void;
+  resumeToolCall: (options: ResumeToolCallOptions) => void;
+
+  speak: (messageId: string) => void;
+  stopSpeaking: () => void;
+
+  submitFeedback: (feedback: SubmitFeedbackOptions) => void;
+
+  getModelContext: () => ModelContext;
+
+  composer: ThreadComposerRuntimeCore;
+  getEditComposer: (messageId: string) => ComposerRuntimeCore | undefined;
+  beginEdit: (messageId: string) => void;
+
+  speech: SpeechState | undefined;
+
+  capabilities: Readonly<RuntimeCapabilities>;
+  isDisabled: boolean;
+  isLoading: boolean;
+  messages: readonly ThreadMessage[];
+  state: ReadonlyJSONValue;
+  suggestions: readonly ThreadSuggestion[];
+
+  extras: unknown;
+
+  subscribe: (callback: () => void) => Unsubscribe;
+
+  import(repository: ExportedMessageRepository): void;
+  export(): ExportedMessageRepository;
+
+  exportExternalState(): any;
+  importExternalState(state: any): void;
+
+  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.
+   */
+  unstable_loadExternalState: (state: any) => void;
+}>;

package/src/runtime/internal.ts

@@ -0,0 +1,64 @@
+// =============================================================================
+// Internal API — implementation details used by framework bindings
+// Not part of the public API surface.
+// =============================================================================
+
+// Binding Types
+export type {
+  ComposerRuntimeCoreBinding,
+  ThreadComposerRuntimeCoreBinding,
+  EditComposerRuntimeCoreBinding,
+  MessageStateBinding,
+} from "./api/bindings";
+
+// Base Runtime Core Implementations
+export { BaseAssistantRuntimeCore } from "./base/base-assistant-runtime-core";
+export { BaseThreadRuntimeCore } from "./base/base-thread-runtime-core";
+export { BaseComposerRuntimeCore } from "./base/base-composer-runtime-core";
+export { DefaultThreadComposerRuntimeCore } from "./base/default-thread-composer-runtime-core";
+export { DefaultEditComposerRuntimeCore } from "./base/default-edit-composer-runtime-core";
+
+// Runtime Impl Classes
+export { AssistantRuntimeImpl } from "./api/assistant-runtime";
+
+export {
+  getThreadState,
+  ThreadRuntimeImpl,
+} from "./api/thread-runtime";
+export type {
+  ThreadRuntimeCoreBinding,
+  ThreadListItemRuntimeBinding,
+} from "./api/thread-runtime";
+
+export { ThreadListRuntimeImpl } from "./api/thread-list-runtime";
+export type { ThreadListRuntimeCoreBinding } from "./api/thread-list-runtime";
+
+export { ThreadListItemRuntimeImpl } from "./api/thread-list-item-runtime";
+export type { ThreadListItemStateBinding } from "./api/thread-list-item-runtime";
+
+export { MessageRuntimeImpl } from "./api/message-runtime";
+export { MessagePartRuntimeImpl } from "./api/message-part-runtime";
+
+export {
+  ComposerRuntimeImpl,
+  ThreadComposerRuntimeImpl,
+  EditComposerRuntimeImpl,
+} from "./api/composer-runtime";
+
+export {
+  AttachmentRuntimeImpl,
+  ThreadComposerAttachmentRuntimeImpl,
+  EditComposerAttachmentRuntimeImpl,
+  MessageAttachmentRuntimeImpl,
+} from "./api/attachment-runtime";
+
+// Supporting Utilities
+export { fromThreadMessageLike } from "./utils/thread-message-like";
+export { symbolInnerMessage } from "./utils/external-store-message";
+export { isAutoStatus, getAutoStatus } from "./utils/auto-status";
+
+export {
+  ExportedMessageRepository,
+  MessageRepository,
+} from "./utils/message-repository";
+export type { ExportedMessageRepositoryItem } from "./utils/message-repository";

package/src/runtime/utils/auto-status.ts

@@ -0,0 +1,67 @@
+import type { MessageStatus } from "../../types";
+import { ReadonlyJSONValue } from "assistant-stream/utils";
+
+const symbolAutoStatus = Symbol("autoStatus");
+
+const AUTO_STATUS_RUNNING = Object.freeze(
+  Object.assign({ type: "running" as const }, { [symbolAutoStatus]: true }),
+);
+const AUTO_STATUS_COMPLETE = Object.freeze(
+  Object.assign(
+    {
+      type: "complete" as const,
+      reason: "unknown" as const,
+    },
+    { [symbolAutoStatus]: true },
+  ),
+);
+
+const AUTO_STATUS_PENDING = Object.freeze(
+  Object.assign(
+    {
+      type: "requires-action" as const,
+      reason: "tool-calls" as const,
+    },
+    { [symbolAutoStatus]: true },
+  ),
+);
+
+const AUTO_STATUS_INTERRUPT = Object.freeze(
+  Object.assign(
+    {
+      type: "requires-action" as const,
+      reason: "interrupt" as const,
+    },
+    { [symbolAutoStatus]: true },
+  ),
+);
+
+export const isAutoStatus = (status: MessageStatus) =>
+  (status as any)[symbolAutoStatus] === true;
+
+export const getAutoStatus = (
+  isLast: boolean,
+  isRunning: boolean,
+  hasInterruptedToolCalls: boolean,
+  hasPendingToolCalls: boolean,
+  error?: ReadonlyJSONValue,
+): MessageStatus => {
+  if (isLast && error) {
+    return Object.assign(
+      {
+        type: "incomplete" as const,
+        reason: "error" as const,
+        error: error,
+      },
+      { [symbolAutoStatus]: true },
+    );
+  }
+
+  return isLast && isRunning
+    ? AUTO_STATUS_RUNNING
+    : hasInterruptedToolCalls
+      ? AUTO_STATUS_INTERRUPT
+      : hasPendingToolCalls
+        ? AUTO_STATUS_PENDING
+        : AUTO_STATUS_COMPLETE;
+};

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

@@ -0,0 +1,66 @@
+import type {
+  FileMessagePart,
+  MessageStatus,
+  MessageTiming,
+  ReasoningMessagePart,
+  RunConfig,
+  SourceMessagePart,
+  TextMessagePart,
+  ThreadAssistantMessagePart,
+  ThreadMessage,
+  ThreadStep,
+  ToolCallMessagePart,
+} from "../../types";
+import type { ModelContext } from "../../model-context";
+import { ReadonlyJSONValue } from "assistant-stream/utils";
+
+export type ChatModelRunUpdate = {
+  readonly content: readonly ThreadAssistantMessagePart[];
+  readonly metadata?: Record<string, unknown>;
+};
+
+export type ChatModelRunResult = {
+  readonly content?: readonly ThreadAssistantMessagePart[] | undefined;
+  readonly status?: MessageStatus | undefined;
+  readonly metadata?: {
+    readonly unstable_state?: ReadonlyJSONValue;
+    readonly unstable_annotations?: readonly ReadonlyJSONValue[] | undefined;
+    readonly unstable_data?: readonly ReadonlyJSONValue[] | undefined;
+    readonly steps?: readonly ThreadStep[] | undefined;
+    readonly timing?: MessageTiming | undefined;
+    readonly custom?: Record<string, unknown> | undefined;
+  };
+};
+
+export type CoreChatModelRunResult = Omit<ChatModelRunResult, "content"> & {
+  readonly content: readonly (
+    | TextMessagePart
+    | ReasoningMessagePart
+    | ToolCallMessagePart
+    | SourceMessagePart
+    | FileMessagePart
+  )[];
+};
+
+export type ChatModelRunOptions = {
+  readonly messages: readonly ThreadMessage[];
+  readonly runConfig: RunConfig;
+  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;
+  unstable_getMessage(): ThreadMessage;
+};
+
+export type ChatModelAdapter = {
+  run(
+    options: ChatModelRunOptions,
+  ): Promise<ChatModelRunResult> | AsyncGenerator<ChatModelRunResult, void>;
+};

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

@@ -0,0 +1,37 @@
+import type { ThreadMessage } from "../../types";
+
+export const symbolInnerMessage = Symbol("innerMessage");
+const symbolInnerMessages = Symbol("innerMessages");
+
+type WithInnerMessages<T> = {
+  [symbolInnerMessage]?: T | 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[] = [];
+
+export const getExternalStoreMessages = <T>(
+  input:
+    | { messages: readonly ThreadMessage[] }
+    | ThreadMessage
+    | ThreadMessage["content"][number],
+) => {
+  const container = (
+    "messages" in input ? input.messages : input
+  ) as WithInnerMessages<T>;
+  const value = container[symbolInnerMessages] || container[symbolInnerMessage];
+  if (!value) return EMPTY_ARRAY;
+  if (Array.isArray(value)) {
+    return value;
+  }
+  container[symbolInnerMessages] = [value];
+  return container[symbolInnerMessages];
+};