@assistant-ui/core 0.1.0 → 0.1.1

package/src/react/types/MessagePartComponentTypes.ts

@@ -0,0 +1,66 @@
+import type { ComponentType, PropsWithChildren } from "react";
+import type {
+  MessagePartStatus,
+  DataMessagePart,
+  FileMessagePart,
+  ImageMessagePart,
+  ReasoningMessagePart,
+  SourceMessagePart,
+  TextMessagePart,
+  ToolCallMessagePart,
+  Unstable_AudioMessagePart,
+} from "../..";
+import type { MessagePartState } from "../..";
+import { ToolResponse } from "assistant-stream";
+
+export type EmptyMessagePartProps = {
+  status: MessagePartStatus;
+};
+export type EmptyMessagePartComponent = ComponentType<EmptyMessagePartProps>;
+
+export type TextMessagePartProps = MessagePartState & TextMessagePart;
+export type TextMessagePartComponent = ComponentType<TextMessagePartProps>;
+
+export type ReasoningMessagePartProps = MessagePartState & ReasoningMessagePart;
+export type ReasoningMessagePartComponent =
+  ComponentType<ReasoningMessagePartProps>;
+
+export type ReasoningGroupProps = PropsWithChildren<{
+  startIndex: number;
+  endIndex: number;
+}>;
+export type ReasoningGroupComponent = ComponentType<ReasoningGroupProps>;
+
+export type SourceMessagePartProps = MessagePartState & SourceMessagePart;
+export type SourceMessagePartComponent = ComponentType<SourceMessagePartProps>;
+
+export type ImageMessagePartProps = MessagePartState & ImageMessagePart;
+export type ImageMessagePartComponent = ComponentType<ImageMessagePartProps>;
+
+export type FileMessagePartProps = MessagePartState & FileMessagePart;
+export type FileMessagePartComponent = ComponentType<FileMessagePartProps>;
+
+export type Unstable_AudioMessagePartProps = MessagePartState &
+  Unstable_AudioMessagePart;
+export type Unstable_AudioMessagePartComponent =
+  ComponentType<Unstable_AudioMessagePartProps>;
+
+export type DataMessagePartProps<T = any> = MessagePartState &
+  DataMessagePart<T>;
+export type DataMessagePartComponent<T = any> = ComponentType<
+  DataMessagePartProps<T>
+>;
+
+export type ToolCallMessagePartProps<
+  TArgs = any,
+  TResult = unknown,
+> = MessagePartState &
+  ToolCallMessagePart<TArgs, TResult> & {
+    addResult: (result: TResult | ToolResponse<TResult>) => void;
+    resume: (payload: unknown) => void;
+  };
+
+export type ToolCallMessagePartComponent<
+  TArgs = any,
+  TResult = any,
+> = ComponentType<ToolCallMessagePartProps<TArgs, TResult>>;

package/src/react/types/index.ts

@@ -0,0 +1,31 @@
+export type {
+  EmptyMessagePartComponent,
+  EmptyMessagePartProps,
+  TextMessagePartComponent,
+  TextMessagePartProps,
+  ReasoningMessagePartComponent,
+  ReasoningMessagePartProps,
+  SourceMessagePartComponent,
+  SourceMessagePartProps,
+  ImageMessagePartComponent,
+  ImageMessagePartProps,
+  FileMessagePartComponent,
+  FileMessagePartProps,
+  Unstable_AudioMessagePartComponent,
+  Unstable_AudioMessagePartProps,
+  DataMessagePartComponent,
+  DataMessagePartProps,
+  ToolCallMessagePartComponent,
+  ToolCallMessagePartProps,
+  ReasoningGroupProps,
+  ReasoningGroupComponent,
+} from "./MessagePartComponentTypes";
+
+export type {
+  ToolsState,
+  ToolsMethods,
+  ToolsClientSchema,
+  DataRenderersState,
+  DataRenderersMethods,
+  DataRenderersClientSchema,
+} from "./scopes";

package/src/react/types/scopes/dataRenderers.ts

@@ -0,0 +1,15 @@
+import type { DataMessagePartComponent } from "../MessagePartComponentTypes";
+import type { Unsubscribe } from "../../..";
+
+export type DataRenderersState = {
+  renderers: Record<string, DataMessagePartComponent[]>;
+};
+
+export type DataRenderersMethods = {
+  getState(): DataRenderersState;
+  setDataUI(name: string, render: DataMessagePartComponent): Unsubscribe;
+};
+
+export type DataRenderersClientSchema = {
+  methods: DataRenderersMethods;
+};

package/src/react/types/scopes/index.ts

@@ -0,0 +1,6 @@
+export type { ToolsState, ToolsMethods, ToolsClientSchema } from "./tools";
+export type {
+  DataRenderersState,
+  DataRenderersMethods,
+  DataRenderersClientSchema,
+} from "./dataRenderers";

package/src/react/types/scopes/tools.ts

@@ -0,0 +1,18 @@
+import type { ToolCallMessagePartComponent } from "../MessagePartComponentTypes";
+import type { Unsubscribe } from "../../..";
+
+export type ToolsState = {
+  tools: Record<string, ToolCallMessagePartComponent[]>;
+};
+
+export type ToolsMethods = {
+  getState(): ToolsState;
+  setToolUI(
+    toolName: string,
+    render: ToolCallMessagePartComponent,
+  ): Unsubscribe;
+};
+
+export type ToolsClientSchema = {
+  methods: ToolsMethods;
+};

package/src/react/types/store-augmentation.ts

@@ -0,0 +1,11 @@
+import "@assistant-ui/store";
+
+import type { ToolsClientSchema } from "./scopes/tools";
+import type { DataRenderersClientSchema } from "./scopes/dataRenderers";
+
+declare module "@assistant-ui/store" {
+  interface ScopeRegistry {
+    tools: ToolsClientSchema;
+    dataRenderers: DataRenderersClientSchema;
+  }
+}

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

@@ -1,9 +1,4 @@
-import type {
-  Attachment,
-  CompleteAttachment,
-  PendingAttachment,
-  Unsubscribe,
-} from "../../types";
+import type { Attachment, CompleteAttachment, Unsubscribe } from "../../types";
 import type { SubscribableWithState } from "../../subscribable/subscribable";
 
 import type { ComposerRuntimeCoreBinding } from "./bindings";
@@ -13,7 +8,7 @@ type MessageAttachmentState = CompleteAttachment & {
   readonly source: "message";
 };
 
-type ThreadComposerAttachmentState = PendingAttachment & {
+type ThreadComposerAttachmentState = Attachment & {
   readonly source: "thread-composer";
 };
 

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

@@ -1,6 +1,6 @@
 import type {
   Attachment,
-  PendingAttachment,
+  CreateAttachment,
   MessageRole,
   RunConfig,
   QuoteInfo,
@@ -65,8 +65,6 @@ type BaseComposerState = {
 
 export type ThreadComposerState = BaseComposerState & {
   readonly type: "thread";
-
-  readonly attachments: readonly PendingAttachment[];
 };
 
 export type EditComposerState = BaseComposerState & {
@@ -131,10 +129,13 @@ export type ComposerRuntime = {
   getState(): ComposerState;
 
   /**
-   * Given a standard js File object, add it to the composer. A composer can have multiple attachments.
-   * @param file The file to add to the composer.
+   * Add an attachment to the composer. Accepts either a standard File object
+   * (processed through the AttachmentAdapter) or a CreateAttachment descriptor
+   * for external-source attachments (URLs, API data, CMS references) that
+   * bypasses the adapter entirely.
+   * @param fileOrAttachment The file or attachment descriptor to add.
    */
-  addAttachment(file: File): Promise<void>;
+  addAttachment(fileOrAttachment: File | CreateAttachment): Promise<void>;
 
   /**
    * Set the text of the composer.
@@ -260,10 +261,10 @@ export abstract class ComposerRuntimeImpl implements ComposerRuntime {
     core.setRunConfig(runConfig);
   }
 
-  public addAttachment(file: File) {
+  public addAttachment(fileOrAttachment: File | CreateAttachment) {
     const core = this._core.getState();
     if (!core) throw new Error("Composer is not available");
-    return core.addAttachment(file);
+    return core.addAttachment(fileOrAttachment);
   }
 
   public reset() {

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

@@ -1,6 +1,7 @@
 import type {
   Attachment,
   CompleteAttachment,
+  CreateAttachment,
   PendingAttachment,
   MessageRole,
   RunConfig,
@@ -16,6 +17,7 @@ import type {
   DictationState,
 } from "../interfaces/composer-runtime-core";
 import type { DictationAdapter } from "../../adapters/speech";
+import { generateId } from "../../utils/id";
 
 const isAttachmentComplete = (a: Attachment): a is CompleteAttachment =>
   a.status.type === "complete";
@@ -116,7 +118,8 @@ export abstract class BaseComposerRuntimeCore
   private async _onClearAttachments() {
     const adapter = this.getAttachmentAdapter();
     if (adapter) {
-      await Promise.all(this._attachments.map((a) => adapter.remove(a)));
+      const pending = this._attachments.filter((a) => !isAttachmentComplete(a));
+      await Promise.all(pending.map((a) => adapter.remove(a)));
     }
   }
 
@@ -155,10 +158,11 @@ export abstract class BaseComposerRuntimeCore
 
     const adapter = this.getAttachmentAdapter();
     const attachments =
-      adapter && this.attachments.length > 0
+      this.attachments.length > 0
         ? Promise.all(
             this.attachments.map(async (a) => {
               if (isAttachmentComplete(a)) return a;
+              if (!adapter) throw new Error("Attachments are not supported");
               const result = await adapter.send(a);
               return result as CompleteAttachment;
             }),
@@ -192,7 +196,22 @@ export abstract class BaseComposerRuntimeCore
   ): void;
   protected abstract handleCancel(): void;
 
-  async addAttachment(file: File) {
+  async addAttachment(fileOrAttachment: File | CreateAttachment) {
+    if (!(fileOrAttachment instanceof File)) {
+      const a: CompleteAttachment = {
+        id: fileOrAttachment.id ?? generateId(),
+        type: fileOrAttachment.type ?? "document",
+        name: fileOrAttachment.name,
+        contentType: fileOrAttachment.contentType,
+        content: fileOrAttachment.content,
+        status: { type: "complete" },
+      };
+      this._attachments = [...this._attachments, a];
+      this._notifyEventSubscribers("attachmentAdd");
+      this._notifySubscribers();
+      return;
+    }
+
     const adapter = this.getAttachmentAdapter();
     if (!adapter) throw new Error("Attachments are not supported");
 
@@ -213,7 +232,7 @@ export abstract class BaseComposerRuntimeCore
       this._notifySubscribers();
     };
 
-    const promiseOrGenerator = adapter.add({ file });
+    const promiseOrGenerator = adapter.add({ file: fileOrAttachment });
     if (Symbol.asyncIterator in promiseOrGenerator) {
       for await (const r of promiseOrGenerator) {
         upsertAttachment(r);
@@ -227,14 +246,15 @@ export abstract class BaseComposerRuntimeCore
   }
 
   async removeAttachment(attachmentId: string) {
-    const adapter = this.getAttachmentAdapter();
-    if (!adapter) throw new Error("Attachments are not supported");
-
     const index = this._attachments.findIndex((a) => a.id === attachmentId);
     if (index === -1) throw new Error("Attachment not found");
     const attachment = this._attachments[index]!;
 
-    await adapter.remove(attachment);
+    if (!isAttachmentComplete(attachment)) {
+      const adapter = this.getAttachmentAdapter();
+      if (!adapter) throw new Error("Attachments are not supported");
+      await adapter.remove(attachment);
+    }
 
     this._attachments = this._attachments.filter((a) => a.id !== attachmentId);
     this._notifySubscribers();

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

@@ -1,4 +1,4 @@
-import type { AppendMessage, PendingAttachment } from "../../types";
+import type { AppendMessage } from "../../types";
 import type { AttachmentAdapter } from "../../adapters/attachment";
 import type { DictationAdapter } from "../../adapters/speech";
 import type { ThreadComposerRuntimeCore } from "../interfaces/composer-runtime-core";
@@ -14,10 +14,6 @@ export class DefaultThreadComposerRuntimeCore
     return this._canCancel;
   }
 
-  public override get attachments(): readonly PendingAttachment[] {
-    return super.attachments as readonly PendingAttachment[];
-  }
-
   protected getAttachmentAdapter() {
     return this.runtime.adapters?.attachments;
   }

package/src/runtime/index.ts

@@ -101,6 +101,7 @@ export type { ThreadMessageLike } from "./utils/thread-message-like";
 export {
   getExternalStoreMessage,
   getExternalStoreMessages,
+  bindExternalStoreMessage,
 } from "./utils/external-store-message";
 
 // ExportedMessageRepository

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

@@ -3,7 +3,7 @@ import type {
   RunConfig,
   QuoteInfo,
   Attachment,
-  PendingAttachment,
+  CreateAttachment,
   Unsubscribe,
 } from "../../types";
 import type { DictationAdapter } from "../../adapters/speech";
@@ -25,7 +25,7 @@ export type ComposerRuntimeCore = Readonly<{
   attachments: readonly Attachment[];
   attachmentAccept: string;
 
-  addAttachment: (file: File) => Promise<void>;
+  addAttachment: (fileOrAttachment: File | CreateAttachment) => Promise<void>;
   removeAttachment: (attachmentId: string) => Promise<void>;
 
   text: string;
@@ -58,7 +58,4 @@ export type ComposerRuntimeCore = Readonly<{
   ) => Unsubscribe;
 }>;
 
-export type ThreadComposerRuntimeCore = ComposerRuntimeCore &
-  Readonly<{
-    attachments: readonly PendingAttachment[];
-  }>;
+export type ThreadComposerRuntimeCore = ComposerRuntimeCore;

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

@@ -18,6 +18,21 @@ export const getExternalStoreMessage = <T>(input: ThreadMessage) => {
 
 const EMPTY_ARRAY: never[] = [];
 
+/**
+ * Attach the original external store message(s) to a ThreadMessage or message part.
+ * This is a no-op if the target already has a bound message.
+ * Use `getExternalStoreMessages` to retrieve the bound messages later.
+ *
+ * @deprecated This API is experimental and may change without notice.
+ */
+export const bindExternalStoreMessage = <T>(
+  target: object,
+  message: T | T[],
+): void => {
+  if (symbolInnerMessage in target) return;
+  (target as WithInnerMessages<T>)[symbolInnerMessage] = message;
+};
+
 export const getExternalStoreMessages = <T>(
   input:
     | { messages: readonly ThreadMessage[] }

package/src/runtime/utils/thread-message-like.ts

@@ -21,6 +21,11 @@ import type {
 } from "../../types";
 import { ReadonlyJSONObject, ReadonlyJSONValue } from "assistant-stream/utils";
 
+type DataPrefixedPart = {
+  readonly type: `data-${string}`;
+  readonly data: any;
+};
+
 export type ThreadMessageLike = {
   readonly role: "assistant" | "user" | "system";
   readonly content:
@@ -33,6 +38,7 @@ export type ThreadMessageLike = {
         | FileMessagePart
         | DataMessagePart
         | Unstable_AudioMessagePart
+        | DataPrefixedPart
         | {
             readonly type: "tool-call";
             readonly toolCallId?: string;
@@ -49,7 +55,11 @@ export type ThreadMessageLike = {
   readonly id?: string | undefined;
   readonly createdAt?: Date | undefined;
   readonly status?: MessageStatus | undefined;
-  readonly attachments?: readonly CompleteAttachment[] | undefined;
+  readonly attachments?:
+    | readonly (Omit<CompleteAttachment, "content"> & {
+        readonly content: readonly (ThreadUserMessagePart | DataPrefixedPart)[];
+      })[]
+    | undefined;
   readonly metadata?:
     | {
         readonly unstable_state?: ReadonlyJSONValue;
@@ -65,6 +75,14 @@ export type ThreadMessageLike = {
     | undefined;
 };
 
+const convertDataPrefixedPart = (
+  type: string,
+  data: unknown,
+): DataMessagePart | undefined => {
+  if (!type.startsWith("data-")) return undefined;
+  return { type: "data", name: type.substring(5), data };
+};
+
 export const fromThreadMessageLike = (
   like: ThreadMessageLike,
   fallbackId: string,
@@ -152,9 +170,13 @@ export const fromThreadMessageLike = (
               }
 
               default: {
-                const unhandledType: "audio" = type;
+                const converted = convertDataPrefixedPart(
+                  type,
+                  (part as DataPrefixedPart).data,
+                );
+                if (converted) return converted;
                 throw new Error(
-                  `Unsupported assistant message part type: ${unhandledType}`,
+                  `Unsupported assistant message part type: ${type}`,
                 );
               }
             }
@@ -189,14 +211,25 @@ export const fromThreadMessageLike = (
               return part;
 
             default: {
-              const unhandledType: "tool-call" | "reasoning" | "source" = type;
-              throw new Error(
-                `Unsupported user message part type: ${unhandledType}`,
+              const converted = convertDataPrefixedPart(
+                type,
+                (part as DataPrefixedPart).data,
               );
+              if (converted) return converted;
+              throw new Error(`Unsupported user message part type: ${type}`);
             }
           }
         }),
-        attachments: attachments ?? [],
+        attachments: (attachments ?? []).map((att) => ({
+          ...att,
+          content: att.content.map((part): ThreadUserMessagePart => {
+            const converted = convertDataPrefixedPart(
+              part.type,
+              (part as DataPrefixedPart).data,
+            );
+            return converted ?? (part as ThreadUserMessagePart);
+          }),
+        })),
         metadata: {
           custom: metadata?.custom ?? {},
         },

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

@@ -9,8 +9,8 @@ import type {
 
 import type { ExternalStoreAdapter } from "./external-store-adapter";
 import {
-  getExternalStoreMessage,
-  symbolInnerMessage,
+  getExternalStoreMessages,
+  bindExternalStoreMessage,
 } from "../../runtime/utils/external-store-message";
 import { ThreadMessageConverter } from "./thread-message-converter";
 import { getAutoStatus, isAutoStatus } from "../../runtime/utils/auto-status";
@@ -30,7 +30,16 @@ import {
   MessageRepository,
 } from "../../runtime/utils/message-repository";
 
-const EMPTY_ARRAY = Object.freeze([]);
+const EMPTY_ARRAY: readonly ThreadSuggestion[] = Object.freeze([]);
+
+const shallowEqual = (a: object, b: object): boolean => {
+  const aKeys = Object.keys(a);
+  if (aKeys.length !== Object.keys(b).length) return false;
+  for (const key of aKeys) {
+    if ((a as any)[key] !== (b as any)[key]) return false;
+  }
+  return true;
+};
 
 export const hasUpcomingMessage = (
   isRunning: boolean,
@@ -110,20 +119,30 @@ export class ExternalStoreThreadRuntimeCore
 
     const oldStore = this._store as ExternalStoreAdapter<any> | undefined;
     this._store = store;
-    this.extras = store.extras;
-    this.suggestions = store.suggestions ?? EMPTY_ARRAY;
-    this._capabilities = {
+    if (this.extras !== store.extras) {
+      this.extras = store.extras;
+    }
+
+    const newSuggestions = store.suggestions ?? EMPTY_ARRAY;
+    if (!shallowEqual(this.suggestions, newSuggestions)) {
+      this.suggestions = newSuggestions;
+    }
+
+    const newCapabilities: RuntimeCapabilities = {
       switchToBranch: this._store.setMessages !== undefined,
-      switchBranchDuringRun: false, // External store never supports branch switching during run
+      switchBranchDuringRun: false,
       edit: this._store.onEdit !== undefined,
       reload: this._store.onReload !== undefined,
       cancel: this._store.onCancel !== undefined,
       speech: this._store.adapters?.speech !== undefined,
       dictation: this._store.adapters?.dictation !== undefined,
-      unstable_copy: this._store.unstable_capabilities?.copy !== false, // default true
+      unstable_copy: this._store.unstable_capabilities?.copy !== false,
       attachments: !!this._store.adapters?.attachments,
       feedback: !!this._store.adapters?.feedback,
     };
+    if (!shallowEqual(this._capabilities, newCapabilities)) {
+      this._capabilities = newCapabilities;
+    }
 
     let messages: readonly ThreadMessage[];
 
@@ -189,7 +208,7 @@ export class ExternalStoreThreadRuntimeCore
               idx.toString(),
               autoStatus,
             );
-            (newMessage as any)[symbolInnerMessage] = m;
+            bindExternalStoreMessage(newMessage, m);
             return newMessage;
           });
 
@@ -357,9 +376,7 @@ export class ExternalStoreThreadRuntimeCore
   private updateMessages = (messages: readonly ThreadMessage[]) => {
     const hasConverter = this._store.convertMessage !== undefined;
     if (hasConverter) {
-      this._store.setMessages?.(
-        messages.flatMap(getExternalStoreMessage).filter((m) => m != null),
-      );
+      this._store.setMessages?.(messages.flatMap(getExternalStoreMessages));
     } else {
       // TODO mark this as readonly in v0.12.0
       this._store.setMessages?.(messages as ThreadMessage[]);

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

@@ -72,7 +72,7 @@ export const EMPTY_THREAD_CORE: ThreadRuntimeCore = {
     attachments: [],
     attachmentAccept: "*",
 
-    async addAttachment() {
+    async addAttachment(_fileOrAttachment) {
       throw EMPTY_THREAD_ERROR;
     },
 

package/src/store/clients/chain-of-thought-client.ts

@@ -1,5 +1,5 @@
 import { resource, tapMemo, tapState } from "@assistant-ui/tap";
-import type { ClientOutput } from "../types/client";
+import type { ClientOutput } from "@assistant-ui/store";
 import type {
   ChainOfThoughtState,
   ChainOfThoughtPart,

package/src/store/clients/model-context-client.ts

@@ -1,5 +1,5 @@
 import { resource, tapMemo, tapState } from "@assistant-ui/tap";
-import type { ClientOutput } from "../types/client";
+import type { ClientOutput } from "@assistant-ui/store";
 import { CompositeContextProvider } from "../../utils";
 import type { ModelContextState } from "../scopes";
 

package/src/store/clients/no-op-composer-client.ts

@@ -1,5 +1,5 @@
 import { resource, tapMemo } from "@assistant-ui/tap";
-import type { ClientOutput } from "../types/client";
+import type { ClientOutput } from "@assistant-ui/store";
 import type { ComposerState } from "../scopes";
 
 export const NoOpComposerClient = resource(

package/src/store/clients/runtime-adapter.ts

@@ -0,0 +1,67 @@
+import { resource, tapEffect, tapResource } from "@assistant-ui/tap";
+import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
+import { ThreadListClient } from "../runtime-clients";
+import {
+  tapAssistantClientRef,
+  Derived,
+  type ScopesConfig,
+  type AssistantClient,
+} from "@assistant-ui/store";
+import { ModelContext } from "./model-context-client";
+import { Suggestions } from "./suggestions";
+
+export const RuntimeAdapterResource = resource((runtime: AssistantRuntime) => {
+  const clientRef = tapAssistantClientRef();
+
+  tapEffect(() => {
+    return runtime.registerModelContextProvider(
+      clientRef.current!.modelContext(),
+    );
+  }, [runtime, clientRef]);
+
+  return tapResource(
+    ThreadListClient({
+      runtime: runtime.threads,
+      __internal_assistantRuntime: runtime,
+    }),
+  );
+});
+
+export const baseRuntimeAdapterTransformScopes = (
+  scopes: ScopesConfig,
+  parent: AssistantClient,
+): ScopesConfig => {
+  const result = {
+    ...scopes,
+    thread:
+      scopes.thread ??
+      Derived({
+        source: "threads",
+        query: { type: "main" },
+        get: (aui) => aui.threads().thread("main"),
+      }),
+    threadListItem:
+      scopes.threadListItem ??
+      Derived({
+        source: "threads",
+        query: { type: "main" },
+        get: (aui) => aui.threads().item("main"),
+      }),
+    composer:
+      scopes.composer ??
+      Derived({
+        source: "thread",
+        query: {},
+        get: (aui) => aui.threads().thread("main").composer(),
+      }),
+  };
+
+  if (!result.modelContext && parent.modelContext.source === null) {
+    result.modelContext = ModelContext();
+  }
+  if (!result.suggestions && parent.suggestions.source === null) {
+    result.suggestions = Suggestions();
+  }
+
+  return result;
+};