@assistant-ui/react 0.11.35 → 0.11.36

package/src/client/types/ModelContext.ts

@@ -0,0 +1,15 @@
+import type { Unsubscribe } from "@assistant-ui/tap";
+import type { ModelContextProvider } from "../../model-context/ModelContextTypes";
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export type ModelContextState = {};
+
+export type ModelContextApi = ModelContextProvider & {
+  getState(): ModelContextState;
+  register: (provider: ModelContextProvider) => Unsubscribe;
+};
+
+export type ModelContextMeta = {
+  source: "root";
+  query: Record<string, never>;
+};

package/src/client/types/ThreadList.ts

@@ -3,6 +3,7 @@ import {
   ThreadListItemClientApi,
 } from "./ThreadListItem";
 import { ThreadClientApi, ThreadClientState } from "./Thread";
+import type { AssistantRuntime } from "../../legacy-runtime/runtime/AssistantRuntime";
 
 export type ThreadListClientState = {
   readonly mainThreadId: string;
@@ -29,4 +30,7 @@ export type ThreadListClientApi = {
   ): ThreadListItemClientApi;
 
   thread(selector: "main"): ThreadClientApi;
+
+  /** @internal */
+  __internal_getAssistantRuntime?(): AssistantRuntime;
 };

package/src/client/types/ToolUI.ts

@@ -1,7 +1,12 @@
 import { Unsubscribe } from "@assistant-ui/tap";
+import type { ComponentType, ReactNode } from "react";
 import { ToolCallMessagePartComponent } from "../../types";
 
-export type ToolUIState = Record<string, ToolCallMessagePartComponent[]>;
+export type ToolUIState = {
+  tools: Record<string, ToolCallMessagePartComponent[]>;
+  fallback: ToolCallMessagePartComponent[];
+  layout: ComponentType<{ children: ReactNode }>[];
+};
 
 export type ToolUIApi = {
   getState(): ToolUIState;
@@ -10,6 +15,10 @@ export type ToolUIApi = {
     toolName: string,
     render: ToolCallMessagePartComponent,
   ): Unsubscribe;
+
+  setFallbackToolUI(render: ToolCallMessagePartComponent): Unsubscribe;
+
+  setToolUILayout(render: ComponentType<{ children: ReactNode }>): Unsubscribe;
 };
 
 export type ToolUIMeta = {

package/src/client/types/Tools.ts

@@ -0,0 +1,11 @@
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export type ToolsState = {};
+
+export type ToolsApi = {
+  getState(): ToolsState;
+};
+
+export type ToolsMeta = {
+  source: "root";
+  query: Record<string, never>;
+};

package/src/context/providers/AttachmentByIndexProvider.tsx

@@ -1,31 +1,29 @@
 "use client";
 
-import { useMemo, type FC, type PropsWithChildren } from "react";
+import { type FC, type PropsWithChildren } from "react";
 
 import {
-  AssistantApi,
   AssistantProvider,
   useAssistantApi,
-  createAssistantApiField,
+  useExtendedAssistantApi,
 } from "../react/AssistantApiContext";
+import { DerivedScope } from "../../utils/tap-store/derived-scopes";
 
 export const MessageAttachmentByIndexProvider: FC<
   PropsWithChildren<{
     index: number;
   }>
 > = ({ index, children }) => {
-  const api = useAssistantApi();
-  const api2 = useMemo(() => {
-    return {
-      attachment: createAssistantApiField({
-        source: "message",
-        query: { type: "index", index },
-        get: () => api.message().attachment({ index }),
-      }),
-    } satisfies Partial<AssistantApi>;
-  }, [api, index]);
+  const baseApi = useAssistantApi();
+  const api = useExtendedAssistantApi({
+    attachment: DerivedScope({
+      source: "message",
+      query: { type: "index", index },
+      get: () => baseApi.message().attachment({ index }),
+    }),
+  });
 
-  return <AssistantProvider api={api2}>{children}</AssistantProvider>;
+  return <AssistantProvider api={api}>{children}</AssistantProvider>;
 };
 
 export const ComposerAttachmentByIndexProvider: FC<
@@ -33,16 +31,14 @@ export const ComposerAttachmentByIndexProvider: FC<
     index: number;
   }>
 > = ({ index, children }) => {
-  const api = useAssistantApi();
-  const api2 = useMemo(() => {
-    return {
-      attachment: createAssistantApiField({
-        source: "composer",
-        query: { type: "index", index },
-        get: () => api.composer().attachment({ index }),
-      }),
-    } satisfies Partial<AssistantApi>;
-  }, [api, index]);
+  const baseApi = useAssistantApi();
+  const api = useExtendedAssistantApi({
+    attachment: DerivedScope({
+      source: "composer",
+      query: { type: "index", index },
+      get: () => baseApi.composer().attachment({ index }),
+    }),
+  });
 
-  return <AssistantProvider api={api2}>{children}</AssistantProvider>;
+  return <AssistantProvider api={api}>{children}</AssistantProvider>;
 };

package/src/context/providers/MessageByIndexProvider.tsx

@@ -1,52 +1,50 @@
 "use client";
 
-import { useMemo, type FC, type PropsWithChildren } from "react";
+import { type FC, type PropsWithChildren } from "react";
 import {
-  AssistantApi,
   AssistantProvider,
   useAssistantApi,
-  createAssistantApiField,
+  useExtendedAssistantApi,
 } from "../react/AssistantApiContext";
 import {
   checkEventScope,
   normalizeEventSelector,
 } from "../../types/EventTypes";
+import { DerivedScope } from "../../utils/tap-store/derived-scopes";
 
 export const MessageByIndexProvider: FC<
   PropsWithChildren<{
     index: number;
   }>
 > = ({ index, children }) => {
-  const api = useAssistantApi();
-  const api2 = useMemo(() => {
-    const getMessage = () => api.thread().message({ index });
-    return {
-      message: createAssistantApiField({
-        source: "thread",
-        query: { type: "index", index },
-        get: () => getMessage(),
-      }),
-      composer: createAssistantApiField({
-        source: "message",
-        query: {},
-        get: () => getMessage().composer,
-      }),
-      on(selector, callback) {
-        const { event, scope } = normalizeEventSelector(selector);
-        if (
-          !checkEventScope("composer", scope, event) &&
-          !checkEventScope("message", scope, event)
-        )
-          return api.on(selector, callback);
+  const baseApi = useAssistantApi();
+  const api = useExtendedAssistantApi({
+    message: DerivedScope({
+      source: "thread",
+      query: { type: "index", index },
+      get: () => baseApi.thread().message({ index }),
+    }),
+    composer: DerivedScope({
+      source: "message",
+      query: {},
+      get: () => baseApi.thread().message({ index }).composer,
+    }),
+    on(selector, callback) {
+      const getMessage = () => baseApi.thread().message({ index });
+      const { event, scope } = normalizeEventSelector(selector);
+      if (
+        !checkEventScope("composer", scope, event) &&
+        !checkEventScope("message", scope, event)
+      )
+        return baseApi.on(selector, callback);
 
-        return api.on({ scope: "thread", event }, (e) => {
-          if (e.messageId === getMessage().getState().id) {
-            callback(e);
-          }
-        });
-      },
-    } satisfies Partial<AssistantApi>;
-  }, [api, index]);
+      return baseApi.on({ scope: "thread", event }, (e) => {
+        if (e.messageId === getMessage().getState().id) {
+          callback(e);
+        }
+      });
+    },
+  });
 
-  return <AssistantProvider api={api2}>{children}</AssistantProvider>;
+  return <AssistantProvider api={api}>{children}</AssistantProvider>;
 };

package/src/context/providers/MessageProvider.tsx

@@ -1,10 +1,9 @@
 "use client";
 
-import { useMemo, type FC, type PropsWithChildren } from "react";
+import { type FC, type PropsWithChildren } from "react";
 import {
   AssistantProvider,
-  AssistantApi,
-  createAssistantApiField,
+  useExtendedAssistantApi,
 } from "../react/AssistantApiContext";
 import { useResource } from "@assistant-ui/tap/react";
 import { asStore } from "../../utils/tap-store";
@@ -12,22 +11,21 @@ import {
   ThreadMessageClientProps,
   ThreadMessageClient,
 } from "../../client/ThreadMessageClient";
+import { DerivedScope } from "../../utils/tap-store/derived-scopes";
 
 export const MessageProvider: FC<
   PropsWithChildren<ThreadMessageClientProps>
 > = ({ children, ...props }) => {
   const store = useResource(asStore(ThreadMessageClient(props)));
-  const api = useMemo(() => {
-    return {
-      message: createAssistantApiField({
-        source: "root",
-        query: {},
-        get: () => store.getState().api,
-      }),
-      subscribe: store.subscribe,
-      flushSync: store.flushSync,
-    } satisfies Partial<AssistantApi>;
-  }, [store]);
+  const api = useExtendedAssistantApi({
+    message: DerivedScope({
+      source: "root",
+      query: {},
+      get: () => store.getState().api,
+    }),
+    subscribe: store.subscribe,
+    flushSync: store.flushSync,
+  });
 
   return <AssistantProvider api={api}>{children}</AssistantProvider>;
 };

package/src/context/providers/PartByIndexProvider.tsx

@@ -1,28 +1,26 @@
 "use client";
 
-import { useMemo, type FC, type PropsWithChildren } from "react";
+import { type FC, type PropsWithChildren } from "react";
 import {
-  AssistantApi,
   AssistantProvider,
   useAssistantApi,
-  createAssistantApiField,
+  useExtendedAssistantApi,
 } from "../react/AssistantApiContext";
+import { DerivedScope } from "../../utils/tap-store/derived-scopes";
 
 export const PartByIndexProvider: FC<
   PropsWithChildren<{
     index: number;
   }>
 > = ({ index, children }) => {
-  const api = useAssistantApi();
-  const api2 = useMemo(() => {
-    return {
-      part: createAssistantApiField({
-        source: "message",
-        query: { type: "index", index },
-        get: () => api.message().part({ index }),
-      }),
-    } satisfies Partial<AssistantApi>;
-  }, [api, index]);
+  const baseApi = useAssistantApi();
+  const api = useExtendedAssistantApi({
+    part: DerivedScope({
+      source: "message",
+      query: { type: "index", index },
+      get: () => baseApi.message().part({ index }),
+    }),
+  });
 
-  return <AssistantProvider api={api2}>{children}</AssistantProvider>;
+  return <AssistantProvider api={api}>{children}</AssistantProvider>;
 };

package/src/context/providers/TextMessagePartProvider.tsx

@@ -1,10 +1,9 @@
 "use client";
 
-import { useMemo, type FC, type PropsWithChildren } from "react";
+import { type FC, type PropsWithChildren } from "react";
 import {
   AssistantProvider,
-  AssistantApi,
-  createAssistantApiField,
+  useExtendedAssistantApi,
 } from "../react/AssistantApiContext";
 import {
   MessagePartClientApi,
@@ -13,6 +12,7 @@ import {
 import { resource, tapMemo } from "@assistant-ui/tap";
 import { useResource } from "@assistant-ui/tap/react";
 import { asStore, tapApi } from "../../utils/tap-store";
+import { DerivedScope } from "../../utils/tap-store/derived-scopes";
 
 const TextMessagePartClient = resource(
   ({ text, isRunning }: { text: string; isRunning: boolean }) => {
@@ -46,17 +46,15 @@ export const TextMessagePartProvider: FC<
   const store = useResource(
     asStore(TextMessagePartClient({ text, isRunning })),
   );
-  const api = useMemo(() => {
-    return {
-      part: createAssistantApiField({
-        source: "root",
-        query: {},
-        get: () => store.getState().api,
-      }),
-      subscribe: store.subscribe,
-      flushSync: store.flushSync,
-    } satisfies Partial<AssistantApi>;
-  }, [store]);
+  const api = useExtendedAssistantApi({
+    part: DerivedScope({
+      source: "root",
+      query: {},
+      get: () => store.getState().api,
+    }),
+    subscribe: store.subscribe,
+    flushSync: store.flushSync,
+  });
 
   return <AssistantProvider api={api}>{children}</AssistantProvider>;
 };

package/src/context/providers/ThreadListItemProvider.tsx

@@ -1,16 +1,16 @@
 "use client";
 
-import { useMemo, type FC, type PropsWithChildren } from "react";
+import { type FC, type PropsWithChildren } from "react";
 import {
-  AssistantApi,
   AssistantProvider,
   useAssistantApi,
-  createAssistantApiField,
+  useExtendedAssistantApi,
 } from "../react/AssistantApiContext";
 import {
   checkEventScope,
   normalizeEventSelector,
 } from "../../types/EventTypes";
+import { DerivedScope } from "../../utils/tap-store/derived-scopes";
 
 export const ThreadListItemByIndexProvider: FC<
   PropsWithChildren<{
@@ -18,31 +18,29 @@ export const ThreadListItemByIndexProvider: FC<
     archived: boolean;
   }>
 > = ({ index, archived, children }) => {
-  const api = useAssistantApi();
+  const baseApi = useAssistantApi();
 
-  const api2 = useMemo(() => {
-    const getItem = () => api.threads().item({ index, archived });
-    return {
-      threadListItem: createAssistantApiField({
-        source: "threads",
-        query: { type: "index", index, archived },
-        get: () => getItem(),
-      }),
-      on(selector, callback) {
-        const { event, scope } = normalizeEventSelector(selector);
-        if (!checkEventScope("thread-list-item", scope, event))
-          return api.on(selector, callback);
+  const api = useExtendedAssistantApi({
+    threadListItem: DerivedScope({
+      source: "threads",
+      query: { type: "index", index, archived },
+      get: () => baseApi.threads().item({ index, archived }),
+    }),
+    on(selector, callback) {
+      const getItem = () => baseApi.threads().item({ index, archived });
+      const { event, scope } = normalizeEventSelector(selector);
+      if (!checkEventScope("thread-list-item", scope, event))
+        return baseApi.on(selector, callback);
 
-        return api.on({ scope: "*", event }, (e) => {
-          if (e.threadId === getItem().getState().id) {
-            callback(e);
-          }
-        });
-      },
-    } satisfies Partial<AssistantApi>;
-  }, [api, index, archived]);
+      return baseApi.on({ scope: "*", event }, (e) => {
+        if (e.threadId === getItem().getState().id) {
+          callback(e);
+        }
+      });
+    },
+  });
 
-  return <AssistantProvider api={api2}>{children}</AssistantProvider>;
+  return <AssistantProvider api={api}>{children}</AssistantProvider>;
 };
 
 export const ThreadListItemByIdProvider: FC<
@@ -50,28 +48,26 @@ export const ThreadListItemByIdProvider: FC<
     id: string;
   }>
 > = ({ id, children }) => {
-  const api = useAssistantApi();
+  const baseApi = useAssistantApi();
 
-  const api2 = useMemo(() => {
-    const getItem = () => api.threads().item({ id });
-    return {
-      threadListItem: createAssistantApiField({
-        source: "threads",
-        query: { type: "id", id },
-        get: () => getItem(),
-      }),
-      on(selector, callback) {
-        const { event, scope } = normalizeEventSelector(selector);
-        if (!checkEventScope("thread-list-item", scope, event))
-          return api.on(selector, callback);
+  const api = useExtendedAssistantApi({
+    threadListItem: DerivedScope({
+      source: "threads",
+      query: { type: "id", id },
+      get: () => baseApi.threads().item({ id }),
+    }),
+    on(selector, callback) {
+      const getItem = () => baseApi.threads().item({ id });
+      const { event, scope } = normalizeEventSelector(selector);
+      if (!checkEventScope("thread-list-item", scope, event))
+        return baseApi.on(selector, callback);
 
-        return api.on({ scope: "*", event }, (e) => {
-          if (e.threadId !== getItem().getState().id) return;
-          callback(e);
-        });
-      },
-    } satisfies Partial<AssistantApi>;
-  }, [api, id]);
+      return baseApi.on({ scope: "*", event }, (e) => {
+        if (e.threadId !== getItem().getState().id) return;
+        callback(e);
+      });
+    },
+  });
 
-  return <AssistantProvider api={api2}>{children}</AssistantProvider>;
+  return <AssistantProvider api={api}>{children}</AssistantProvider>;
 };

package/src/context/react/AssistantApiContext.tsx

@@ -8,6 +8,7 @@ import {
   useMemo,
   useEffect,
 } from "react";
+import { useResource } from "@assistant-ui/tap/react";
 
 import { ToolUIApi, ToolUIState, ToolUIMeta } from "../../client/types/ToolUI";
 import {
@@ -32,8 +33,6 @@ import {
   AttachmentClientState,
 } from "../../client/types/Attachment";
 import { Unsubscribe } from "@assistant-ui/tap";
-import { ModelContextProvider } from "../../model-context";
-import { AssistantRuntime } from "../../legacy-runtime/runtime/AssistantRuntime";
 import {
   AssistantEvent,
   AssistantEventCallback,
@@ -50,6 +49,15 @@ import {
   AssistantClientProps,
   useAssistantClient,
 } from "../../client/AssistantClient";
+import { ToolsApi, ToolsMeta } from "../../client/types/Tools";
+import {
+  ModelContextApi,
+  ModelContextMeta,
+} from "../../client/types/ModelContext";
+import {
+  DerivedScopes,
+  DerivedScopesInput,
+} from "../../utils/tap-store/derived-scopes";
 
 export type AssistantState = {
   readonly threads: ThreadListClientState;
@@ -63,7 +71,7 @@ export type AssistantState = {
   readonly attachment: AttachmentClientState;
 };
 
-type AssistantApiField<
+export type AssistantApiField<
   TApi,
   TMeta extends { source: string | null; query: any },
 > = (() => TApi) & (TMeta | { source: null; query: Record<string, never> });
@@ -115,6 +123,8 @@ type AttachmentMeta = {
 export type AssistantApi = {
   threads: AssistantApiField<ThreadListClientApi, ThreadsMeta>;
   toolUIs: AssistantApiField<ToolUIApi, ToolUIMeta>;
+  tools: AssistantApiField<ToolsApi, ToolsMeta>;
+  modelContext: AssistantApiField<ModelContextApi, ModelContextMeta>;
   threadListItem: AssistantApiField<
     ThreadListItemClientApi,
     ThreadListItemMeta
@@ -132,11 +142,6 @@ export type AssistantApi = {
     event: AssistantEventSelector<TEvent>,
     callback: AssistantEventCallback<TEvent>,
   ): Unsubscribe;
-
-  // temp
-  registerModelContextProvider(provider: ModelContextProvider): void;
-  /** @internal */
-  __internal_getRuntime?(): AssistantRuntime;
 };
 
 export const createAssistantApiField = <
@@ -170,6 +175,22 @@ const AssistantApiContext = createContext<AssistantApi>({
       throw new Error("ToolUIs is only available inside <AssistantProvider />");
     },
   }),
+  tools: createAssistantApiField({
+    source: null,
+    query: {},
+    get: (): never => {
+      throw new Error("Tools is only available inside <AssistantProvider />");
+    },
+  }),
+  modelContext: createAssistantApiField({
+    source: null,
+    query: {},
+    get: (): never => {
+      throw new Error(
+        "ModelContext is only available inside <AssistantProvider />",
+      );
+    },
+  }),
   threadListItem: createAssistantApiField({
     source: null,
     query: {},
@@ -229,25 +250,47 @@ const AssistantApiContext = createContext<AssistantApi>({
     const { scope } = normalizeEventSelector(selector);
     throw new Error(`Event scope is not available in this component: ${scope}`);
   },
-
-  registerModelContextProvider: () => {
-    throw new Error(
-      "Registering model context providers is only available inside <AssistantProvider />",
-    );
-  },
 });
 
-const useAssistantApiImpl = (): AssistantApi => {
+export const useAssistantApiImpl = (): AssistantApi => {
   return useContext(AssistantApiContext);
 };
 
+/**
+ * Hook to extend the current AssistantApi with additional derived scope fields and special callbacks.
+ * This merges the derived fields with the existing API from context.
+ * Fields are automatically memoized based on source and query changes.
+ * Special callbacks (on, subscribe, flushSync) use the useEffectEvent pattern to always access latest values.
+ *
+ * @param scopes - Record of field names to DerivedScope resource elements, plus optional special callbacks
+ * @returns The merged AssistantApi
+ *
+ * @example
+ * ```tsx
+ * const api = useExtendedAssistantApi({
+ *   message: DerivedScope({
+ *     source: "root",
+ *     query: {},
+ *     get: () => messageApi,
+ *   }),
+ *   on: (selector, callback) => {
+ *     // Custom event filtering logic
+ *   },
+ * });
+ * ```
+ */
+export const useExtendedAssistantApi = (
+  scopes: DerivedScopesInput,
+): AssistantApi => {
+  const baseApi = useAssistantApiImpl();
+  const partialApi = useResource(DerivedScopes(scopes));
+  return useMemo(() => extendApi(baseApi, partialApi), [baseApi, partialApi]);
+};
+
 const useExtendedAssistantApiImpl = (
   config: AssistantClientProps,
 ): AssistantApi => {
-  const api = useAssistantApiImpl();
-  const api2 = useAssistantClient(config);
-  const extendedApi = useMemo(() => extendApi(api, api2), [api, api2]);
-  return extendedApi;
+  return useAssistantClient(config);
 };
 
 export function useAssistantApi(): AssistantApi;
@@ -293,7 +336,7 @@ const mergeFnsWithUnsubscribe = <TArgs extends Array<unknown>>(
   };
 };
 
-const extendApi = (
+export const extendApi = (
   api: AssistantApi,
   api2: Partial<AssistantApi>,
 ): AssistantApi => {
@@ -311,18 +354,15 @@ const extendApi = (
 };
 
 export const AssistantProvider: FC<
-  PropsWithChildren<{ api: Partial<AssistantApi>; devToolsVisible?: boolean }>
-> = ({ api: api2, children, devToolsVisible = true }) => {
-  const api = useAssistantApi();
-  const extendedApi = useMemo(() => extendApi(api, api2), [api, api2]);
-
+  PropsWithChildren<{ api: AssistantApi; devToolsVisible?: boolean }>
+> = ({ api, children, devToolsVisible = true }) => {
   useEffect(() => {
-    if (!devToolsVisible || !api2.subscribe) return undefined;
-    return DevToolsProviderApi.register(api2);
-  }, [api2, devToolsVisible]);
+    if (!devToolsVisible || !api.subscribe) return undefined;
+    return DevToolsProviderApi.register(api);
+  }, [api, devToolsVisible]);
 
   return (
-    <AssistantApiContext.Provider value={extendedApi}>
+    <AssistantApiContext.Provider value={api}>
       {/* TODO temporarily allow accessing viewport state from outside the viewport */}
       {/* TODO figure out if this behavior should be deprecated, since it is quite hacky */}
       <ThreadViewportProvider>{children}</ThreadViewportProvider>