@assistant-ui/core 0.1.0

package/src/store/scopes/thread.ts

@@ -0,0 +1,135 @@
+import type { ReadonlyJSONValue } from "assistant-stream/utils";
+import type {
+  RuntimeCapabilities,
+  SpeechState,
+  ThreadSuggestion,
+  ExportedMessageRepository,
+  ThreadMessageLike,
+  CreateAppendMessage,
+  CreateStartRunConfig,
+  CreateResumeRunConfig,
+  ThreadRuntime,
+} from "../../runtime";
+import type { ModelContext } from "../../model-context";
+import type { MessageMethods, MessageState } from "./message";
+import type { ComposerMethods, ComposerState } from "./composer";
+
+export type ThreadState = {
+  /**
+   * Whether the thread is empty. A thread is considered empty when it has no messages and is not loading.
+   */
+  readonly isEmpty: boolean;
+  /**
+   * Whether the thread is disabled. Disabled threads cannot receive new messages.
+   */
+  readonly isDisabled: boolean;
+  /**
+   * Whether the thread is loading its history.
+   */
+  readonly isLoading: boolean;
+  /**
+   * Whether the thread is running. A thread is considered running when there is an active stream connection to the backend.
+   */
+  readonly isRunning: boolean;
+  /**
+   * The capabilities of the thread, such as whether the thread supports editing, branch switching, etc.
+   */
+  readonly capabilities: RuntimeCapabilities;
+  /**
+   * The messages in the currently selected branch of the thread.
+   */
+  readonly messages: readonly MessageState[];
+  /**
+   * The thread state.
+   * @deprecated This feature is experimental
+   */
+  readonly state: ReadonlyJSONValue;
+  /**
+   * Follow up message suggestions to show the user.
+   */
+  readonly suggestions: readonly ThreadSuggestion[];
+  /**
+   * Custom extra information provided by the runtime.
+   */
+  readonly extras: unknown;
+  /** @deprecated This API is still under active development and might change without notice. */
+  readonly speech: SpeechState | undefined;
+  readonly composer: ComposerState;
+};
+
+export type ThreadMethods = {
+  /**
+   * Get the current state of the thread.
+   */
+  getState(): ThreadState;
+  /**
+   * The thread composer runtime.
+   */
+  composer(): ComposerMethods;
+  /**
+   * Append a new message to the thread.
+   *
+   * @example ```ts
+   * // append a new user message with the text "Hello, world!"
+   * threadRuntime.append("Hello, world!");
+   * ```
+   *
+   * @example ```ts
+   * // append a new assistant message with the text "Hello, world!"
+   * threadRuntime.append({
+   *   role: "assistant",
+   *   content: [{ type: "text", text: "Hello, world!" }],
+   * });
+   * ```
+   */
+  append(message: CreateAppendMessage): void;
+  /**
+   * Start a new run with the given configuration.
+   * @param config The configuration for starting the run
+   */
+  startRun(config: CreateStartRunConfig): void;
+  /**
+   * Resume a run with the given configuration.
+   * @param config The configuration for resuming the run
+   */
+  unstable_resumeRun(config: CreateResumeRunConfig): void;
+  cancelRun(): void;
+  getModelContext(): ModelContext;
+  export(): ExportedMessageRepository;
+  import(repository: ExportedMessageRepository): void;
+  /**
+   * Reset the thread with optional initial messages.
+   * @param initialMessages - Optional array of initial messages to populate the thread
+   */
+  reset(initialMessages?: readonly ThreadMessageLike[]): void;
+  message(selector: { id: string } | { index: number }): MessageMethods;
+  /** @deprecated This API is still under active development and might change without notice. */
+  stopSpeaking(): void;
+  /**
+   * Start the voice session for the thread. Establishes any necessary media connections.
+   */
+  startVoice(): Promise<void>;
+  /**
+   * Stop the currently active voice session.
+   */
+  stopVoice(): Promise<void>;
+  __internal_getRuntime?(): ThreadRuntime;
+};
+
+export type ThreadMeta = {
+  source: "threads";
+  query: { type: "main" };
+};
+
+export type ThreadEvents = {
+  "thread.runStart": { threadId: string };
+  "thread.runEnd": { threadId: string };
+  "thread.initialize": { threadId: string };
+  "thread.modelContextUpdate": { threadId: string };
+};
+
+export type ThreadClientSchema = {
+  methods: ThreadMethods;
+  meta: ThreadMeta;
+  events: ThreadEvents;
+};

package/src/store/scopes/threads.ts

@@ -0,0 +1,34 @@
+import type { AssistantRuntime } from "../../runtime";
+import type {
+  ThreadListItemMethods,
+  ThreadListItemState,
+} from "./thread-list-item";
+import type { ThreadMethods, ThreadState } from "./thread";
+
+export type ThreadsState = {
+  readonly mainThreadId: string;
+  readonly newThreadId: string | null;
+  readonly isLoading: boolean;
+  readonly threadIds: readonly string[];
+  readonly archivedThreadIds: readonly string[];
+  readonly threadItems: readonly ThreadListItemState[];
+  readonly main: ThreadState;
+};
+
+export type ThreadsMethods = {
+  getState(): ThreadsState;
+  switchToThread(threadId: string): void;
+  switchToNewThread(): void;
+  item(
+    threadIdOrOptions:
+      | "main"
+      | { id: string }
+      | { index: number; archived?: boolean },
+  ): ThreadListItemMethods;
+  thread(selector: "main"): ThreadMethods;
+  __internal_getAssistantRuntime?(): AssistantRuntime;
+};
+
+export type ThreadsClientSchema = {
+  methods: ThreadsMethods;
+};

package/src/store/types/client.ts

@@ -0,0 +1,203 @@
+import type { ResourceElement } from "@assistant-ui/tap";
+import type {
+  AssistantEventName,
+  AssistantEventCallback,
+  AssistantEventSelector,
+} from "./events";
+import type { ThreadsClientSchema } from "../scopes/threads";
+import type { ThreadListItemClientSchema } from "../scopes/thread-list-item";
+import type { ThreadClientSchema } from "../scopes/thread";
+import type { MessageClientSchema } from "../scopes/message";
+import type { PartClientSchema } from "../scopes/part";
+import type { ComposerClientSchema } from "../scopes/composer";
+import type { AttachmentClientSchema } from "../scopes/attachment";
+import type { ModelContextClientSchema } from "../scopes/model-context";
+import type { SuggestionsClientSchema } from "../scopes/suggestions";
+import type { SuggestionClientSchema } from "../scopes/suggestion";
+import type { ChainOfThoughtClientSchema } from "../scopes/chain-of-thought";
+
+/**
+ * Base type for methods that can be called on a client.
+ */
+export interface ClientMethods {
+  [key: string | symbol]: (...args: any[]) => any;
+}
+
+type ClientMetaType = { source: ClientNames; query: Record<string, unknown> };
+
+/**
+ * Schema of a client in the assistant system (internal type).
+ * @template TState - The state type for this client
+ * @template TMethods - The methods available on this client
+ * @template TMeta - Source/query metadata (optional)
+ * @template TEvents - Events that this client can emit (optional)
+ * @internal
+ */
+export type ClientSchema<
+  TMethods extends ClientMethods = ClientMethods,
+  TMeta extends ClientMetaType = never,
+  TEvents extends Record<string, unknown> = never,
+> = {
+  methods: TMethods;
+  meta?: TMeta;
+  events?: TEvents;
+};
+
+/**
+ * Module augmentation interface for assistant-ui store type extensions.
+ *
+ * @example
+ * ```typescript
+ * declare module "@assistant-ui/core/store" {
+ *   interface ScopeRegistry {
+ *     // Simple client (meta and events are optional)
+ *     foo: {
+ *       methods: {
+ *         getState: () => { bar: string };
+ *         updateBar: (bar: string) => void;
+ *       };
+ *     };
+ *     // Full client with meta and events
+ *     bar: {
+ *       methods: {
+ *         getState: () => { id: string };
+ *         update: () => void;
+ *       };
+ *       meta: { source: "fooList"; query: { index: number } };
+ *       events: {
+ *         "bar.updated": { id: string };
+ *       };
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export interface ScopeRegistry {
+  threads: ThreadsClientSchema;
+  threadListItem: ThreadListItemClientSchema;
+  thread: ThreadClientSchema;
+  message: MessageClientSchema;
+  part: PartClientSchema;
+  composer: ComposerClientSchema;
+  attachment: AttachmentClientSchema;
+  modelContext: ModelContextClientSchema;
+  suggestions: SuggestionsClientSchema;
+  suggestion: SuggestionClientSchema;
+  chainOfThought: ChainOfThoughtClientSchema;
+}
+
+type ClientEventsType<K extends ClientNames> = Record<
+  `${K}.${string}`,
+  unknown
+>;
+
+type ClientError<E extends string> = {
+  methods: Record<E, () => E>;
+  meta: { source: ClientNames; query: Record<E, E> };
+  events: Record<`${E}.`, E>;
+};
+
+type ValidateClient<K extends keyof ScopeRegistry> = ScopeRegistry[K] extends {
+  methods: ClientMethods;
+}
+  ? "meta" extends keyof ScopeRegistry[K]
+    ? ScopeRegistry[K]["meta"] extends ClientMetaType
+      ? "events" extends keyof ScopeRegistry[K]
+        ? ScopeRegistry[K]["events"] extends ClientEventsType<K>
+          ? ScopeRegistry[K]
+          : ClientError<`ERROR: ${K & string} has invalid events type`>
+        : ScopeRegistry[K]
+      : ClientError<`ERROR: ${K & string} has invalid meta type`>
+    : "events" extends keyof ScopeRegistry[K]
+      ? ScopeRegistry[K]["events"] extends ClientEventsType<K>
+        ? ScopeRegistry[K]
+        : ClientError<`ERROR: ${K & string} has invalid events type`>
+      : ScopeRegistry[K]
+  : ClientError<`ERROR: ${K & string} has invalid methods type`>;
+
+type ClientSchemas = keyof ScopeRegistry extends never
+  ? {
+      "ERROR: No clients were defined": ClientError<"ERROR: No clients were defined">;
+    }
+  : { [K in keyof ScopeRegistry]: ValidateClient<K> };
+
+/**
+ * Output type that client resources return (just methods).
+ *
+ * @example
+ * ```typescript
+ * const FooResource = resource((): ClientResourceOutput<"foo"> => {
+ *   const [state, setState] = tapState({ bar: "hello" });
+ *   return {
+ *     getState: () => state,
+ *     updateBar: (b) => setState({ bar: b }),
+ *   };
+ * });
+ * ```
+ */
+export type ClientOutput<K extends ClientNames> = ClientSchemas[K]["methods"] &
+  ClientMethods;
+
+export type ClientNames = keyof ClientSchemas extends infer U ? U : never;
+
+export type ClientEvents<K extends ClientNames> =
+  "events" extends keyof ClientSchemas[K]
+    ? ClientSchemas[K]["events"] extends ClientEventsType<K>
+      ? ClientSchemas[K]["events"]
+      : never
+    : never;
+
+export type ClientMeta<K extends ClientNames> =
+  "meta" extends keyof ClientSchemas[K]
+    ? Pick<
+        ClientSchemas[K]["meta"] extends ClientMetaType
+          ? ClientSchemas[K]["meta"]
+          : never,
+        "source" | "query"
+      >
+    : never;
+
+export type ClientElement<K extends ClientNames> = ResourceElement<
+  ClientOutput<K>
+>;
+
+/**
+ * Unsubscribe function type.
+ */
+export type Unsubscribe = () => void;
+
+/**
+ * State type extracted from all clients via their getState() methods.
+ */
+export type AssistantState = {
+  [K in ClientNames]: ClientSchemas[K]["methods"] extends {
+    getState: () => infer S;
+  }
+    ? S
+    : never;
+};
+
+/**
+ * Type for a client accessor - a function that returns the methods,
+ * with source/query metadata attached (derived from meta).
+ */
+export type AssistantClientAccessor<K extends ClientNames> =
+  (() => ClientSchemas[K]["methods"]) &
+    (
+      | ClientMeta<K>
+      | { source: "root"; query: Record<string, never> }
+      | { source: null; query: null }
+    ) & { name: K };
+
+/**
+ * The assistant client type with all registered clients.
+ */
+export type AssistantClient = {
+  [K in ClientNames]: AssistantClientAccessor<K>;
+} & {
+  subscribe(listener: () => void): Unsubscribe;
+  on<TEvent extends AssistantEventName>(
+    selector: AssistantEventSelector<TEvent>,
+    callback: AssistantEventCallback<TEvent>,
+  ): Unsubscribe;
+};

package/src/store/types/events.ts

@@ -0,0 +1,77 @@
+import type {
+  AssistantClientAccessor,
+  ClientEvents,
+  ClientNames,
+} from "./client";
+
+// --- Event Map Construction ---
+type UnionToIntersection<U> = (
+  U extends unknown
+    ? (x: U) => void
+    : never
+) extends (x: infer I) => void
+  ? I
+  : never;
+
+type ClientEventMap = UnionToIntersection<
+  { [K in ClientNames]: ClientEvents<K> }[ClientNames]
+>;
+
+// --- Core Types ---
+
+type WildcardPayload = {
+  [K in keyof ClientEventMap]: { event: K; payload: ClientEventMap[K] };
+}[keyof ClientEventMap];
+
+export type AssistantEventPayload = ClientEventMap & { "*": WildcardPayload };
+
+export type AssistantEventName = keyof AssistantEventPayload;
+
+type EventSource<T extends AssistantEventName> =
+  T extends `${infer Source}.${string}` ? Source : never;
+
+// --- Scoping ---
+
+type ParentOf<K extends ClientNames> =
+  AssistantClientAccessor<K> extends { source: infer S }
+    ? S extends ClientNames
+      ? S
+      : never
+    : never;
+
+type AncestorsOf<
+  K extends ClientNames,
+  Seen extends ClientNames = never,
+> = K extends Seen
+  ? never
+  : ParentOf<K> extends never
+    ? never
+    : ParentOf<K> | AncestorsOf<ParentOf<K>, Seen | K>;
+
+/** Valid scopes: `"*"` | event source | ancestors of event source */
+export type AssistantEventScope<TEvent extends AssistantEventName> =
+  | "*"
+  | EventSource<TEvent>
+  | (EventSource<TEvent> extends ClientNames
+      ? AncestorsOf<EventSource<TEvent>>
+      : never);
+
+// --- Selection & Callbacks ---
+
+export type AssistantEventSelector<TEvent extends AssistantEventName> =
+  | TEvent
+  | { scope: AssistantEventScope<TEvent>; event: TEvent };
+
+export const normalizeEventSelector = <TEvent extends AssistantEventName>(
+  selector: AssistantEventSelector<TEvent>,
+) => {
+  if (typeof selector === "string") {
+    const source = selector.split(".")[0] as AssistantEventScope<TEvent>;
+    return { scope: source, event: selector };
+  }
+  return { scope: selector.scope, event: selector.event };
+};
+
+export type AssistantEventCallback<TEvent extends AssistantEventName> = (
+  payload: AssistantEventPayload[TEvent],
+) => void;

package/src/store/types/index.ts

@@ -0,0 +1,23 @@
+export type {
+  ClientMethods,
+  ClientSchema,
+  ScopeRegistry,
+  ClientOutput,
+  ClientNames,
+  ClientEvents,
+  ClientMeta,
+  ClientElement,
+  Unsubscribe,
+  AssistantState,
+  AssistantClientAccessor,
+  AssistantClient,
+} from "./client";
+
+export {
+  normalizeEventSelector,
+  type AssistantEventPayload,
+  type AssistantEventName,
+  type AssistantEventScope,
+  type AssistantEventSelector,
+  type AssistantEventCallback,
+} from "./events";

package/src/store/utils/attach-transform-scopes.ts

@@ -0,0 +1,38 @@
+import type { ResourceElement } from "@assistant-ui/tap";
+import type {
+  AssistantClient,
+  ClientElement,
+  ClientNames,
+} from "../types/client";
+import type { DerivedElement } from "./derived";
+
+const TRANSFORM_SCOPES = Symbol("assistant-ui.transform-scopes");
+
+export type ScopesConfig = {
+  [K in ClientNames]?: ClientElement<K> | DerivedElement<K>;
+};
+
+type TransformScopesFn = (
+  scopes: ScopesConfig,
+  parent: AssistantClient,
+) => ScopesConfig;
+
+type ResourceWithTransformScopes = {
+  [TRANSFORM_SCOPES]?: TransformScopesFn;
+};
+
+export function attachTransformScopes<
+  T extends (...args: any[]) => ResourceElement<any>,
+>(resource: T, transform: TransformScopesFn): void {
+  const r = resource as T & ResourceWithTransformScopes;
+  if (r[TRANSFORM_SCOPES]) {
+    throw new Error("transformScopes is already attached to this resource");
+  }
+  r[TRANSFORM_SCOPES] = transform;
+}
+
+export function getTransformScopes<
+  T extends (...args: any[]) => ResourceElement<any>,
+>(resource: T): TransformScopesFn | undefined {
+  return (resource as T & ResourceWithTransformScopes)[TRANSFORM_SCOPES];
+}

package/src/store/utils/base-proxy-handler.ts

@@ -0,0 +1,50 @@
+const INTROSPECTION_PROPS = new Set(["$$typeof", "nodeType", "then"]);
+
+/**
+ * Handles common proxy introspection properties.
+ * Returns the appropriate value for toStringTag, toJSON, and props that should return undefined.
+ * Returns `false` if the prop should be handled by the subclass.
+ */
+export const handleIntrospectionProp = (
+  prop: string | symbol,
+  name: string,
+): unknown | false => {
+  if (prop === Symbol.toStringTag) return name;
+  if (typeof prop === "symbol") return undefined;
+  if (prop === "toJSON") return () => name;
+  if (INTROSPECTION_PROPS.has(prop)) return undefined;
+  return false;
+};
+
+export abstract class BaseProxyHandler implements ProxyHandler<object> {
+  abstract get(_: unknown, prop: string | symbol, receiver?: unknown): unknown;
+  abstract ownKeys(): ArrayLike<string | symbol>;
+  abstract has(_: unknown, prop: string | symbol): boolean;
+
+  getOwnPropertyDescriptor(_: unknown, prop: string | symbol) {
+    const value = this.get(_, prop);
+    if (value === undefined) return undefined;
+    return {
+      value,
+      writable: false,
+      enumerable: true,
+      configurable: false,
+    };
+  }
+
+  set() {
+    return false;
+  }
+  setPrototypeOf() {
+    return false;
+  }
+  defineProperty() {
+    return false;
+  }
+  deleteProperty() {
+    return false;
+  }
+  preventExtensions(): boolean {
+    return false;
+  }
+}

package/src/store/utils/derived.ts

@@ -0,0 +1,46 @@
+import { resource, ResourceElement } from "@assistant-ui/tap";
+import type {
+  AssistantClient,
+  ClientNames,
+  AssistantClientAccessor,
+  ClientMeta,
+} from "../types/client";
+
+/**
+ * Creates a derived client field that references a client from a parent scope.
+ * The get callback always calls the most recent version (useEffectEvent pattern).
+ *
+ * IMPORTANT: The `get` callback must return a client that was created via
+ * `tapClientResource` (or `tapClientLookup`/`tapClientList` which use it internally).
+ * This is required for event scoping to work correctly.
+ *
+ * @example
+ * ```typescript
+ * const aui = useAui({
+ *   message: Derived({
+ *     source: "thread",
+ *     query: { index: 0 },
+ *     get: (aui) => aui.thread().message({ index: 0 }),
+ *   }),
+ * });
+ * ```
+ */
+export const Derived = resource(
+  <K extends ClientNames>(_config: Derived.Props<K>): null => {
+    return null;
+  },
+);
+
+export type DerivedElement<K extends ClientNames> = ResourceElement<
+  null,
+  Derived.Props<K>
+>;
+
+export namespace Derived {
+  /**
+   * Props passed to a derived client resource element.
+   */
+  export type Props<K extends ClientNames> = {
+    get: (client: AssistantClient) => ReturnType<AssistantClientAccessor<K>>;
+  } & (ClientMeta<K> | { getMeta: (client: AssistantClient) => ClientMeta<K> });
+}

package/src/store/utils/index.ts

@@ -0,0 +1,28 @@
+export {
+  BaseProxyHandler,
+  handleIntrospectionProp,
+} from "./base-proxy-handler";
+export {
+  SYMBOL_CLIENT_INDEX,
+  getClientIndex,
+  type ClientStack,
+  tapClientStack,
+  tapWithClientStack,
+} from "./tap-client-stack-context";
+export {
+  type AssistantTapContextValue,
+  withAssistantTapContextProvider,
+  tapAssistantClientRef,
+  tapAssistantEmit,
+} from "./tap-assistant-context";
+export { NotificationManager } from "./notification-manager";
+export {
+  PROXIED_ASSISTANT_STATE_SYMBOL,
+  createProxiedAssistantState,
+  getProxiedAssistantState,
+} from "./proxied-assistant-state";
+export {
+  type RootClients,
+  type DerivedClients,
+  tapSplitClients,
+} from "./split-clients";