@assistant-ui/core 0.1.7 → 0.1.9

package/src/react/client/Interactables.ts

@@ -0,0 +1,233 @@
+import {
+  resource,
+  tapState,
+  tapEffect,
+  tapCallback,
+  tapRef,
+  tapMemo,
+} from "@assistant-ui/tap";
+import {
+  tapAssistantClientRef,
+  type ClientOutput,
+  attachTransformScopes,
+} from "@assistant-ui/store";
+import type {
+  InteractablesState,
+  InteractableDefinition,
+  InteractableRegistration,
+  InteractableStateSchema,
+} from "../types/scopes/interactables";
+import { toJSONSchema, toPartialJSONSchema } from "assistant-stream";
+import type { Tool } from "assistant-stream";
+import { ModelContext } from "../../store";
+
+function shallowMerge(prev: unknown, partial: unknown): unknown {
+  if (
+    typeof prev !== "object" ||
+    prev === null ||
+    typeof partial !== "object" ||
+    partial === null ||
+    Array.isArray(prev) ||
+    Array.isArray(partial)
+  ) {
+    return partial;
+  }
+  return {
+    ...(prev as Record<string, unknown>),
+    ...(partial as Record<string, unknown>),
+  };
+}
+
+export const Interactables = resource((): ClientOutput<"interactables"> => {
+  const [state, setState] = tapState<InteractablesState>(() => ({
+    definitions: {},
+  }));
+
+  const clientRef = tapAssistantClientRef();
+
+  const stateRef = tapRef(state);
+  tapEffect(() => {
+    stateRef.current = state;
+  }, [state]);
+
+  const subscribersRef = tapRef(new Set<() => void>());
+
+  const partialSchemaCacheRef = tapRef(
+    new Map<string, InteractableStateSchema>(),
+  );
+  const detachedStateRef = tapRef(new Map<string, unknown>());
+
+  const setDefState = tapCallback(
+    (id: string, updater: (prev: unknown) => unknown) => {
+      setState((prev) => {
+        const existing = prev.definitions[id];
+        if (!existing) return prev;
+        return {
+          ...prev,
+          definitions: {
+            ...prev.definitions,
+            [id]: { ...existing, state: updater(existing.state) },
+          },
+        };
+      });
+    },
+    [],
+  );
+
+  const setDefSelected = tapCallback((id: string, selected: boolean) => {
+    setState((prev) => {
+      const existing = prev.definitions[id];
+      if (!existing) return prev;
+      return {
+        ...prev,
+        definitions: {
+          ...prev.definitions,
+          [id]: { ...existing, selected },
+        },
+      };
+    });
+  }, []);
+
+  const provider = tapMemo(
+    () => ({
+      getModelContext: () => {
+        const defs = stateRef.current.definitions;
+        const entries = Object.values(defs);
+        if (entries.length === 0) return {};
+
+        const byName = new Map<string, InteractableDefinition[]>();
+        for (const def of entries) {
+          const list = byName.get(def.name) ?? [];
+          list.push(def);
+          byName.set(def.name, list);
+        }
+
+        const systemParts: string[] = [];
+        const tools: Record<string, Tool<any, any>> = {};
+
+        for (const [name, instances] of byName) {
+          const isMulti = instances.length > 1;
+
+          for (const def of instances) {
+            const selectedTag = def.selected ? " (SELECTED)" : "";
+            const idTag = isMulti ? ` [id="${def.id}"]` : "";
+
+            systemParts.push(
+              `Interactable component "${name}"${idTag}${selectedTag} (${def.description}). Current state: ${JSON.stringify(def.state)}`,
+            );
+
+            const safeName = name.replace(/[^a-zA-Z0-9_-]/g, "_");
+            const safeId = def.id.replace(/[^a-zA-Z0-9_-]/g, "_");
+            const toolName = isMulti
+              ? `update_${safeName}_${safeId}`
+              : `update_${safeName}`;
+
+            const partialSchema =
+              partialSchemaCacheRef.current.get(def.id) ?? def.stateSchema;
+
+            tools[toolName] = {
+              type: "frontend" as const,
+              description: `Update the state of interactable component "${name}"${isMulti ? ` (id: ${def.id})` : ""}. Only include the fields you want to change; omitted fields keep their current values. ${def.description}`,
+              parameters: partialSchema,
+              streamCall: async (reader) => {
+                try {
+                  for await (const partialArgs of reader.args.streamValues()) {
+                    setDefState(def.id, (prev) =>
+                      shallowMerge(prev, partialArgs),
+                    );
+                  }
+                } catch {
+                  // Non-fatal: execute handles the final state
+                }
+              },
+              execute: async (partialState: unknown) => {
+                setDefState(def.id, (prev) => shallowMerge(prev, partialState));
+                return { success: true };
+              },
+            };
+          }
+        }
+
+        return { system: systemParts.join("\n"), tools };
+      },
+      subscribe: (callback: () => void) => {
+        subscribersRef.current.add(callback);
+        return () => {
+          subscribersRef.current.delete(callback);
+        };
+      },
+    }),
+    [setDefState],
+  );
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: state dep triggers notification
+  tapEffect(() => {
+    for (const cb of subscribersRef.current) {
+      cb();
+    }
+  }, [state]);
+
+  tapEffect(() => {
+    return clientRef.current!.modelContext().register(provider);
+  }, [clientRef, provider]);
+
+  const register = tapCallback((def: InteractableRegistration) => {
+    try {
+      const jsonSchema = toJSONSchema(def.stateSchema);
+      partialSchemaCacheRef.current.set(
+        def.id,
+        toPartialJSONSchema(jsonSchema),
+      );
+    } catch (e) {
+      // Fall back to the raw schema; partial updates may not work correctly
+      console.warn(
+        `[Interactables] Failed to create partial schema for "${def.name}". The update tool will require all fields.`,
+        e,
+      );
+    }
+
+    const detached = detachedStateRef.current.get(def.id);
+    detachedStateRef.current.delete(def.id);
+
+    setState((prev) => ({
+      ...prev,
+      definitions: {
+        ...prev.definitions,
+        [def.id]: {
+          id: def.id,
+          name: def.name,
+          description: def.description,
+          stateSchema: def.stateSchema,
+          state:
+            prev.definitions[def.id]?.state ?? detached ?? def.initialState,
+          selected: def.selected,
+        },
+      },
+    }));
+
+    return () => {
+      setState((prev) => {
+        const existing = prev.definitions[def.id];
+        if (existing) {
+          detachedStateRef.current.set(def.id, existing.state);
+        }
+        partialSchemaCacheRef.current.delete(def.id);
+        const { [def.id]: _, ...rest } = prev.definitions;
+        return { ...prev, definitions: rest };
+      });
+    };
+  }, []);
+
+  return {
+    getState: () => state,
+    register,
+    setState: setDefState,
+    setSelected: setDefSelected,
+  };
+});
+
+attachTransformScopes(Interactables, (scopes, parent) => {
+  if (!scopes.modelContext && parent.modelContext.source === null) {
+    scopes.modelContext = ModelContext();
+  }
+});

package/src/react/client/Tools.ts

@@ -89,9 +89,8 @@ export const Tools = resource(
   },
 );
 
-attachTransformScopes(Tools, (scopes, parent) => ({
-  ...scopes,
-  ...(scopes.modelContext || parent.modelContext.source !== null
-    ? {}
-    : { modelContext: ModelContext() }),
-}));
+attachTransformScopes(Tools, (scopes, parent) => {
+  if (!scopes.modelContext && parent.modelContext.source === null) {
+    scopes.modelContext = ModelContext();
+  }
+});

package/src/react/index.ts

@@ -28,10 +28,21 @@ export {
 } from "./model-context/useAssistantDataUI";
 export { useInlineRender } from "./model-context/useInlineRender";
 export type { Toolkit, ToolDefinition } from "./model-context/toolbox";
+export {
+  useInteractable,
+  type UseInteractableConfig,
+  type UseInteractableMetadata,
+} from "./model-context/useInteractable";
+export {
+  makeInteractable,
+  type InteractableConfig,
+  type AssistantInteractable,
+} from "./model-context/makeInteractable";
 
 // client
 export { Tools } from "./client/Tools";
 export { DataRenderers } from "./client/DataRenderers";
+export { Interactables } from "./client/Interactables";
 
 // types
 export type {
@@ -68,6 +79,14 @@ export type {
   DataRenderersMethods,
   DataRenderersClientSchema,
 } from "./types/scopes/dataRenderers";
+export type {
+  InteractableStateSchema,
+  InteractablesState,
+  InteractableDefinition,
+  InteractableRegistration,
+  InteractablesMethods,
+  InteractablesClientSchema,
+} from "./types/scopes/interactables";
 
 // providers
 export {
@@ -85,6 +104,10 @@ export {
   SuggestionByIndexProvider,
   type SuggestionByIndexProviderProps,
 } from "./providers/SuggestionByIndexProvider";
+export {
+  QueueItemByIndexProvider,
+  type QueueItemByIndexProviderProps,
+} from "./providers/QueueItemByIndexProvider";
 export { ReadonlyThreadProvider } from "./providers/ReadonlyThreadProvider";
 
 // RuntimeAdapter
@@ -144,6 +167,7 @@ export {
   ComposerPrimitiveAttachments,
   ComposerPrimitiveAttachmentByIndex,
 } from "./primitives/composer/ComposerAttachments";
+export { ComposerPrimitiveQueue } from "./primitives/composer/ComposerQueue";
 export {
   ThreadListPrimitiveItems,
   ThreadListPrimitiveItemByIndex,

package/src/react/model-context/makeInteractable.ts

@@ -0,0 +1,21 @@
+import { FC } from "react";
+import { useInteractable, type UseInteractableConfig } from "./useInteractable";
+
+export type InteractableConfig<TState> = UseInteractableConfig<TState> & {
+  name: string;
+};
+
+export type AssistantInteractable = FC & {
+  unstable_interactable: InteractableConfig<any>;
+};
+
+export const makeInteractable = <TState>(
+  config: InteractableConfig<TState>,
+) => {
+  const Interactable: AssistantInteractable = () => {
+    useInteractable(config.name, config);
+    return null;
+  };
+  Interactable.unstable_interactable = config;
+  return Interactable;
+};

package/src/react/model-context/useInteractable.ts

@@ -0,0 +1,73 @@
+import { useEffect, useCallback, useId, useRef } from "react";
+import { useAui, useAuiState } from "@assistant-ui/store";
+import type { InteractableStateSchema } from "../types/scopes/interactables";
+
+export type UseInteractableConfig<TState> = {
+  description: string;
+  stateSchema: InteractableStateSchema;
+  initialState: TState;
+  id?: string;
+  selected?: boolean;
+};
+
+type StateUpdater<TState> = TState | ((prev: TState) => TState);
+
+export type UseInteractableMetadata = {
+  id: string;
+  setSelected: (selected: boolean) => void;
+};
+
+export const useInteractable = <TState>(
+  name: string,
+  config: UseInteractableConfig<TState>,
+): [
+  TState,
+  (updater: StateUpdater<TState>) => void,
+  UseInteractableMetadata,
+] => {
+  const aui = useAui();
+
+  const autoId = useId().replace(/[^a-zA-Z0-9]/g, "");
+  const id = config.id ?? autoId;
+
+  const stateSchemaRef = useRef(config.stateSchema);
+  stateSchemaRef.current = config.stateSchema;
+  const initialStateRef = useRef(config.initialState);
+  initialStateRef.current = config.initialState;
+
+  useEffect(() => {
+    return aui.interactables().register({
+      id,
+      name,
+      description: config.description,
+      stateSchema: stateSchemaRef.current,
+      initialState: initialStateRef.current,
+      selected: config.selected,
+    });
+  }, [aui, id, name, config.description, config.selected]);
+
+  const state =
+    (useAuiState((s) => s.interactables.definitions[id]?.state) as TState) ??
+    config.initialState;
+
+  const setState = useCallback(
+    (updater: StateUpdater<TState>) => {
+      aui.interactables().setState(id, (prev) => {
+        if (typeof updater === "function") {
+          return (updater as (prev: TState) => TState)(prev as TState);
+        }
+        return updater;
+      });
+    },
+    [aui, id],
+  );
+
+  const setSelected = useCallback(
+    (selected: boolean) => {
+      aui.interactables().setSelected(id, selected);
+    },
+    [aui, id],
+  );
+
+  return [state, setState, { id, setSelected }];
+};

package/src/react/primitive-hooks/useComposerSend.ts

@@ -1,15 +1,22 @@
 import { useCallback } from "react";
 import { useAui, useAuiState } from "@assistant-ui/store";
+import type { ComposerSendOptions } from "../../store/scopes/composer";
 
 export const useComposerSend = () => {
   const aui = useAui();
   const disabled = useAuiState(
-    (s) => s.thread.isRunning || !s.composer.isEditing || s.composer.isEmpty,
+    (s) =>
+      (s.thread.isRunning && !s.thread.capabilities.queue) ||
+      !s.composer.isEditing ||
+      s.composer.isEmpty,
   );
 
-  const send = useCallback(() => {
-    aui.composer().send();
-  }, [aui]);
+  const send = useCallback(
+    (opts?: ComposerSendOptions) => {
+      aui.composer().send(opts);
+    },
+    [aui],
+  );
 
   return { send, disabled };
 };

package/src/react/primitives/composer/ComposerQueue.tsx

@@ -0,0 +1,58 @@
+import { type FC, type ReactNode, memo, useMemo } from "react";
+import { RenderChildrenWithAccessor, useAuiState } from "@assistant-ui/store";
+import type { QueueItemState } from "../../../store/scopes/queue-item";
+import { QueueItemByIndexProvider } from "../../providers/QueueItemByIndexProvider";
+
+export namespace ComposerPrimitiveQueue {
+  export type Props = {
+    /** Render function called for each queue item. Receives the queue item state. */
+    children: (value: { queueItem: QueueItemState }) => ReactNode;
+  };
+}
+
+const ComposerPrimitiveQueueInner: FC<{
+  children: (value: { queueItem: QueueItemState }) => ReactNode;
+}> = ({ children }) => {
+  const queue = useAuiState((s) => s.composer.queue.length);
+
+  return useMemo(
+    () =>
+      Array.from({ length: queue }, (_, index) => (
+        <QueueItemByIndexProvider key={index} index={index}>
+          <RenderChildrenWithAccessor
+            getItemState={(aui) =>
+              aui.composer().queueItem({ index }).getState()
+            }
+          >
+            {(getItem) =>
+              children({
+                get queueItem() {
+                  return getItem();
+                },
+              })
+            }
+          </RenderChildrenWithAccessor>
+        </QueueItemByIndexProvider>
+      )),
+    [queue, children],
+  );
+};
+
+/**
+ * Renders all queue items in the composer.
+ *
+ * @example
+ * ```tsx
+ * <ComposerPrimitive.Queue>
+ *   {({ queueItem }) => (
+ *     <div>
+ *       <QueueItemPrimitive.Text />
+ *       <QueueItemPrimitive.Steer>Run Now</QueueItemPrimitive.Steer>
+ *     </div>
+ *   )}
+ * </ComposerPrimitive.Queue>
+ * ```
+ */
+export const ComposerPrimitiveQueue = memo(ComposerPrimitiveQueueInner);
+
+ComposerPrimitiveQueue.displayName = "ComposerPrimitive.Queue";

package/src/react/primitives/message/MessageParts.tsx

@@ -440,6 +440,8 @@ const EmptyPartsImpl: FC<MessagePartComponentProps> = ({ components }) => {
 
   if (components?.Empty) return <components.Empty status={status} />;
 
+  if (status.type !== "running") return null;
+
   return (
     <EmptyPartFallback
       status={status}

package/src/react/providers/QueueItemByIndexProvider.tsx

@@ -0,0 +1,21 @@
+import { type FC, type PropsWithChildren } from "react";
+import { AuiProvider, Derived, useAui } from "@assistant-ui/store";
+
+export type QueueItemByIndexProviderProps = PropsWithChildren<{
+  index: number;
+}>;
+
+export const QueueItemByIndexProvider: FC<QueueItemByIndexProviderProps> = ({
+  index,
+  children,
+}) => {
+  const aui = useAui({
+    queueItem: Derived({
+      source: "composer",
+      query: { index },
+      get: (aui) => aui.composer().queueItem({ index }),
+    }),
+  });
+
+  return <AuiProvider value={aui}>{children}</AuiProvider>;
+};

package/src/react/runtimes/RemoteThreadListThreadListRuntimeCore.tsx

@@ -480,6 +480,7 @@ export class RemoteThreadListThreadListRuntimeCore
       throw new Error("Thread is not yet initialized");
 
     await this._ensureThreadIsNotMain(data.id);
+    this._hookManager.stopThreadRuntime(data.id);
 
     return this._state.optimisticUpdate({
       execute: async () => {

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

@@ -0,0 +1,44 @@
+import type { Tool } from "assistant-stream";
+import type { Unsubscribe } from "../../..";
+
+/**
+ * Schema type matching Tool["parameters"] from assistant-stream.
+ * Accepts both StandardSchemaV1 and JSONSchema7.
+ */
+export type InteractableStateSchema = NonNullable<
+  Extract<Tool, { parameters: unknown }>["parameters"]
+>;
+
+export type InteractableDefinition = {
+  id: string;
+  name: string;
+  description: string;
+  stateSchema: InteractableStateSchema;
+  state: unknown;
+  selected?: boolean | undefined;
+};
+
+export type InteractableRegistration = {
+  id: string;
+  name: string;
+  description: string;
+  stateSchema: InteractableStateSchema;
+  initialState: unknown;
+  selected?: boolean | undefined;
+};
+
+export type InteractablesState = {
+  /** Keyed by instance id */
+  definitions: Record<string, InteractableDefinition>;
+};
+
+export type InteractablesMethods = {
+  getState(): InteractablesState;
+  register(def: InteractableRegistration): Unsubscribe;
+  setState(id: string, updater: (prev: unknown) => unknown): void;
+  setSelected(id: string, selected: boolean): void;
+};
+
+export type InteractablesClientSchema = {
+  methods: InteractablesMethods;
+};

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

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

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

@@ -9,7 +9,10 @@ import type { QuoteInfo } from "../../types/quote";
 import type { Unsubscribe } from "../../types/unsubscribe";
 import type { RunConfig } from "../../types/message";
 import { BaseSubscribable } from "../../subscribable/subscribable";
-import type { AttachmentAdapter } from "../../adapters/attachment";
+import {
+  type AttachmentAdapter,
+  fileMatchesAccept,
+} from "../../adapters/attachment";
 import type {
   ComposerRuntimeCore,
   ComposerRuntimeEventType,
@@ -216,6 +219,17 @@ export abstract class BaseComposerRuntimeCore
     const adapter = this.getAttachmentAdapter();
     if (!adapter) throw new Error("Attachments are not supported");
 
+    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}`,
+      );
+    }
+
     const upsertAttachment = (a: PendingAttachment) => {
       const idx = this._attachments.findIndex(
         (attachment) => attachment.id === a.id,
@@ -233,17 +247,39 @@ export abstract class BaseComposerRuntimeCore
       this._notifySubscribers();
     };
 
-    const promiseOrGenerator = adapter.add({ file: fileOrAttachment });
-    if (Symbol.asyncIterator in promiseOrGenerator) {
-      for await (const r of promiseOrGenerator) {
-        upsertAttachment(r);
+    let lastAttachment: PendingAttachment | undefined;
+    try {
+      const promiseOrGenerator = adapter.add({ file: fileOrAttachment });
+      if (Symbol.asyncIterator in promiseOrGenerator) {
+        for await (const r of promiseOrGenerator) {
+          lastAttachment = r;
+          upsertAttachment(r);
+        }
+      } else {
+        lastAttachment = await promiseOrGenerator;
+        upsertAttachment(lastAttachment);
       }
-    } else {
-      upsertAttachment(await promiseOrGenerator);
+    } catch (e) {
+      if (lastAttachment) {
+        upsertAttachment({
+          ...lastAttachment,
+          status: { type: "incomplete", reason: "error" },
+        });
+      }
+      try {
+        this._notifyEventSubscribers("attachmentAddError");
+      } catch {
+        // prevent subscriber errors from masking the adapter error
+      }
+      throw e;
     }
 
-    this._notifyEventSubscribers("attachmentAdd");
-    this._notifySubscribers();
+    const hasError =
+      lastAttachment?.status.type === "incomplete" &&
+      lastAttachment.status.reason === "error";
+    this._notifyEventSubscribers(
+      hasError ? "attachmentAddError" : "attachmentAdd",
+    );
   }
 
   async removeAttachment(attachmentId: string) {

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

@@ -5,7 +5,10 @@ import type { Unsubscribe } from "../../types/unsubscribe";
 import type { RunConfig } from "../../types/message";
 import type { DictationAdapter } from "../../adapters/speech";
 
-export type ComposerRuntimeEventType = "send" | "attachmentAdd";
+export type ComposerRuntimeEventType =
+  | "send"
+  | "attachmentAdd"
+  | "attachmentAddError";
 
 export type DictationState = {
   readonly status: DictationAdapter.Status;

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

@@ -26,6 +26,7 @@ export type RuntimeCapabilities = {
   readonly dictation: boolean;
   readonly attachments: boolean;
   readonly feedback: boolean;
+  readonly queue: boolean;
 };
 
 export type AddToolResultOptions = {