@assistant-ui/react 0.11.0 → 0.11.1

package/src/legacy-runtime/cloud/auiV0.ts

@@ -0,0 +1,158 @@
+import { ThreadMessage } from "../../types";
+import { MessageStatus } from "../../types/AssistantTypes";
+import { fromThreadMessageLike } from "../runtime-cores/external-store/ThreadMessageLike";
+import { CloudMessage } from "assistant-cloud";
+import { isJSONValue } from "../../utils/json/is-json";
+import { ReadonlyJSONObject, ReadonlyJSONValue } from "assistant-stream/utils";
+import { ExportedMessageRepositoryItem } from "../runtime-cores/utils/MessageRepository";
+
+type AuiV0MessageMessagePart =
+  | {
+      readonly type: "text";
+      readonly text: string;
+    }
+  | {
+      readonly type: "reasoning";
+      readonly text: string;
+    }
+  | {
+      readonly type: "source";
+      readonly sourceType: "url";
+      readonly id: string;
+      readonly url: string;
+      readonly title?: string;
+    }
+  | {
+      readonly type: "tool-call";
+      readonly toolCallId: string;
+      readonly toolName: string;
+      readonly args: ReadonlyJSONObject;
+      readonly result?: ReadonlyJSONValue;
+      readonly isError?: true;
+    }
+  | {
+      readonly type: "tool-call";
+      readonly toolCallId: string;
+      readonly toolName: string;
+      readonly argsText: string;
+      readonly result?: ReadonlyJSONValue;
+      readonly isError?: true;
+    };
+
+type AuiV0Message = {
+  readonly role: "assistant" | "user" | "system";
+  readonly status?: MessageStatus;
+  readonly content: readonly AuiV0MessageMessagePart[];
+  readonly metadata: {
+    readonly unstable_state?: ReadonlyJSONValue;
+    readonly unstable_annotations: readonly ReadonlyJSONValue[];
+    readonly unstable_data: readonly ReadonlyJSONValue[];
+    readonly steps: readonly {
+      readonly usage?: {
+        readonly promptTokens: number;
+        readonly completionTokens: number;
+      };
+    }[];
+    readonly custom: ReadonlyJSONObject;
+  };
+};
+
+export const auiV0Encode = (message: ThreadMessage): AuiV0Message => {
+  // TODO attachments are currently intentionally ignored
+  // info: ID and createdAt are ignored (we use the server value instead)
+  return {
+    role: message.role,
+    content: message.content.map((part) => {
+      const type = part.type;
+      switch (type) {
+        case "text": {
+          return {
+            type: "text",
+            text: part.text,
+          };
+        }
+
+        case "reasoning": {
+          return {
+            type: "reasoning",
+            text: part.text,
+          };
+        }
+
+        case "source": {
+          return {
+            type: "source",
+            sourceType: part.sourceType,
+            id: part.id,
+            url: part.url,
+            ...(part.title ? { title: part.title } : undefined),
+          };
+        }
+
+        case "tool-call": {
+          if (!isJSONValue(part.result)) {
+            console.warn(
+              "tool-call result is not JSON! " + JSON.stringify(part),
+            );
+          }
+          return {
+            type: "tool-call",
+            toolCallId: part.toolCallId,
+            toolName: part.toolName,
+            ...(JSON.stringify(part.args) === part.argsText
+              ? {
+                  args: part.args,
+                }
+              : { argsText: part.argsText }),
+            ...(part.result
+              ? { result: part.result as ReadonlyJSONValue }
+              : {}),
+            ...(part.isError ? { isError: true } : {}),
+          };
+        }
+
+        default: {
+          const unhandledType: "image" | "file" | "audio" = type;
+          throw new Error(
+            `Message part type not supported by aui/v0: ${unhandledType}`,
+          );
+        }
+      }
+    }),
+    metadata: message.metadata as AuiV0Message["metadata"],
+    ...(message.status
+      ? {
+          status:
+            message.status?.type === "running"
+              ? {
+                  type: "incomplete",
+                  reason: "cancelled",
+                }
+              : message.status,
+        }
+      : undefined),
+  };
+};
+
+export const auiV0Decode = (
+  cloudMessage: CloudMessage & { format: "aui/v0" },
+): ExportedMessageRepositoryItem => {
+  const payload = cloudMessage.content as unknown as AuiV0Message;
+  const message = fromThreadMessageLike(
+    {
+      id: cloudMessage.id,
+      createdAt: cloudMessage.created_at,
+      ...payload,
+    },
+    cloudMessage.id,
+    {
+      type: "complete",
+      reason: "unknown",
+    },
+  );
+
+  return {
+    parentId: cloudMessage.parent_id,
+    message,
+  };
+};

package/src/legacy-runtime/cloud/useCloudThreadListRuntime.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+import { AssistantCloud } from "assistant-cloud";
+import { AssistantRuntime } from "../runtime";
+import { useRemoteThreadListRuntime } from "../runtime-cores/remote-thread-list/useRemoteThreadListRuntime";
+import { useCloudThreadListAdapter } from "../runtime-cores/remote-thread-list/adapter/cloud";
+
+type ThreadData = {
+  externalId: string;
+};
+
+type CloudThreadListAdapter = {
+  cloud: AssistantCloud;
+
+  runtimeHook: () => AssistantRuntime;
+
+  create?(): Promise<ThreadData>;
+  delete?(threadId: string): Promise<void>;
+};
+
+export const useCloudThreadListRuntime = ({
+  runtimeHook,
+  ...adapterOptions
+}: CloudThreadListAdapter) => {
+  const adapter = useCloudThreadListAdapter(adapterOptions);
+  const runtime = useRemoteThreadListRuntime({
+    runtimeHook: runtimeHook,
+    adapter,
+  });
+
+  return runtime;
+};

package/src/legacy-runtime/hooks/AssistantContext.ts

@@ -0,0 +1,53 @@
+"use client";
+
+import { useAssistantApi } from "../../context/react/AssistantApiContext";
+import { AssistantRuntime } from "../runtime/AssistantRuntime";
+import type { ThreadListRuntime } from "../runtime/ThreadListRuntime";
+import { createStateHookForRuntime } from "../../context/react/utils/createStateHookForRuntime";
+
+/**
+ * Hook to access the AssistantRuntime from the current context.
+ *
+ * The AssistantRuntime provides access to the top-level assistant state and actions,
+ * including thread management, tool registration, and configuration.
+ *
+ * @param options Configuration options
+ * @param options.optional Whether the hook should return null if no context is found
+ * @returns The AssistantRuntime instance, or null if optional is true and no context exists
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const runtime = useAssistantRuntime();
+ *
+ *   const handleNewThread = () => {
+ *     runtime.switchToNewThread();
+ *   };
+ *
+ *   return <button onClick={handleNewThread}>New Thread</button>;
+ * }
+ * ```
+ */
+export function useAssistantRuntime(options?: {
+  optional?: false | undefined;
+}): AssistantRuntime;
+export function useAssistantRuntime(options?: {
+  optional?: boolean | undefined;
+}): AssistantRuntime | null;
+export function useAssistantRuntime(options?: {
+  optional?: boolean | undefined;
+}) {
+  const api = useAssistantApi();
+  const runtime = api.__internal_getRuntime();
+
+  if (!runtime && !options?.optional) {
+    throw new Error("AssistantRuntime is not available");
+  }
+
+  return runtime;
+}
+
+const useThreadListRuntime = (opt: {
+  optional: boolean | undefined;
+}): ThreadListRuntime | null => useAssistantRuntime(opt)?.threads ?? null;
+export const useThreadList = createStateHookForRuntime(useThreadListRuntime);

package/src/legacy-runtime/hooks/AttachmentContext.ts

@@ -0,0 +1,91 @@
+"use client";
+
+import { AttachmentRuntime } from "../runtime/AttachmentRuntime";
+import { createStateHookForRuntime } from "../../context/react/utils/createStateHookForRuntime";
+import { useAssistantApi } from "../../context/react";
+
+export function useAttachmentRuntime(options?: {
+  optional?: false | undefined;
+}): AttachmentRuntime;
+export function useAttachmentRuntime(options?: {
+  optional?: boolean | undefined;
+}): AttachmentRuntime | null;
+export function useAttachmentRuntime(options?: {
+  optional?: boolean | undefined;
+}): AttachmentRuntime | null {
+  const api = useAssistantApi();
+  const runtime = api.attachment.source
+    ? api.attachment().__internal_getRuntime()
+    : null;
+  if (!runtime && !options?.optional) {
+    throw new Error("AttachmentRuntime is not available");
+  }
+  return runtime;
+}
+
+export function useThreadComposerAttachmentRuntime(options?: {
+  optional?: false | undefined;
+}): AttachmentRuntime<"thread-composer">;
+export function useThreadComposerAttachmentRuntime(options?: {
+  optional?: boolean | undefined;
+}): AttachmentRuntime<"thread-composer"> | null;
+export function useThreadComposerAttachmentRuntime(options?: {
+  optional?: boolean | undefined;
+}): AttachmentRuntime<"thread-composer"> | null {
+  const attachmentRuntime = useAttachmentRuntime(options);
+  if (!attachmentRuntime) return null;
+  if (attachmentRuntime.source !== "thread-composer")
+    throw new Error(
+      "This component must be used within a thread's ComposerPrimitive.Attachments component.",
+    );
+  return attachmentRuntime as AttachmentRuntime<"thread-composer">;
+}
+
+export function useEditComposerAttachmentRuntime(options?: {
+  optional?: false | undefined;
+}): AttachmentRuntime<"edit-composer">;
+export function useEditComposerAttachmentRuntime(options?: {
+  optional?: boolean | undefined;
+}): AttachmentRuntime<"edit-composer"> | null;
+export function useEditComposerAttachmentRuntime(options?: {
+  optional?: boolean | undefined;
+}): AttachmentRuntime<"edit-composer"> | null {
+  const attachmentRuntime = useAttachmentRuntime(options);
+  if (!attachmentRuntime) return null;
+  if (attachmentRuntime.source !== "edit-composer")
+    throw new Error(
+      "This component must be used within a message's ComposerPrimitive.Attachments component.",
+    );
+
+  return attachmentRuntime as AttachmentRuntime<"edit-composer">;
+}
+
+export function useMessageAttachmentRuntime(options?: {
+  optional?: false | undefined;
+}): AttachmentRuntime<"message">;
+export function useMessageAttachmentRuntime(options?: {
+  optional?: boolean | undefined;
+}): AttachmentRuntime<"message"> | null;
+export function useMessageAttachmentRuntime(options?: {
+  optional?: boolean | undefined;
+}): AttachmentRuntime<"message"> | null {
+  const attachmentRuntime = useAttachmentRuntime(options);
+  if (!attachmentRuntime) return null;
+  if (attachmentRuntime.source !== "message")
+    throw new Error(
+      "This component must be used within a MessagePrimitive.Attachments component.",
+    );
+  return attachmentRuntime as AttachmentRuntime<"message">;
+}
+
+export const useAttachment = createStateHookForRuntime(useAttachmentRuntime);
+
+export const useThreadComposerAttachment = createStateHookForRuntime(
+  useThreadComposerAttachmentRuntime,
+);
+export const useEditComposerAttachment = createStateHookForRuntime(
+  useEditComposerAttachmentRuntime,
+);
+export const useMessageAttachment = createStateHookForRuntime(
+  useMessageAttachmentRuntime,
+);

package/src/legacy-runtime/hooks/ComposerContext.ts

@@ -0,0 +1,90 @@
+"use client";
+
+import { useAssistantApi } from "../../context/react";
+import { ComposerRuntime } from "../runtime/ComposerRuntime";
+import { createStateHookForRuntime } from "../../context/react/utils/createStateHookForRuntime";
+
+/**
+ * Hook to access the ComposerRuntime from the current context.
+ *
+ * The ComposerRuntime provides access to composer state and actions for message
+ * composition, including text input, attachments, and sending functionality.
+ * This hook automatically resolves to either the message's edit composer or
+ * the thread's main composer depending on the context.
+ *
+ * @param options Configuration options
+ * @param options.optional Whether the hook should return null if no context is found
+ * @returns The ComposerRuntime instance, or null if optional is true and no context exists
+ *
+ * @example
+ * ```tsx
+ * function ComposerActions() {
+ *   const runtime = useComposerRuntime();
+ *
+ *   const handleSend = () => {
+ *     if (runtime.getState().canSend) {
+ *       runtime.send();
+ *     }
+ *   };
+ *
+ *   const handleCancel = () => {
+ *     if (runtime.getState().canCancel) {
+ *       runtime.cancel();
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleSend}>Send</button>
+ *       <button onClick={handleCancel}>Cancel</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useComposerRuntime(options?: {
+  optional?: false | undefined;
+}): ComposerRuntime;
+export function useComposerRuntime(options?: {
+  optional?: boolean | undefined;
+}): ComposerRuntime | null;
+export function useComposerRuntime(options?: {
+  optional?: boolean | undefined;
+}): ComposerRuntime | null {
+  const api = useAssistantApi();
+  const runtime = api.composer.source
+    ? api.composer().__internal_getRuntime()
+    : null;
+  if (!runtime && !options?.optional) {
+    throw new Error("ComposerRuntime is not available");
+  }
+  return runtime;
+}
+
+/**
+ * Hook to access the current composer state.
+ *
+ * This hook provides reactive access to the composer's state, including text content,
+ * attachments, editing status, and send/cancel capabilities.
+ *
+ * @param selector Optional selector function to pick specific state properties
+ * @returns The selected composer state or the entire composer state if no selector provided
+ *
+ * @example
+ * ```tsx
+ * function ComposerStatus() {
+ *   const text = useComposer((state) => state.text);
+ *   const canSend = useComposer((state) => state.canSend);
+ *   const attachmentCount = useComposer((state) => state.attachments.length);
+ *
+ *   return (
+ *     <div>
+ *       Text: {text.length} chars,
+ *       Attachments: {attachmentCount},
+ *       Can send: {canSend}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export const useComposer = createStateHookForRuntime(useComposerRuntime);

package/src/legacy-runtime/hooks/MessageContext.ts

@@ -0,0 +1,90 @@
+"use client";
+
+import { MessageRuntime } from "../runtime/MessageRuntime";
+import { useAssistantApi } from "../../context/react";
+import { createStateHookForRuntime } from "../../context/react/utils/createStateHookForRuntime";
+import { EditComposerRuntime } from "../runtime";
+
+/**
+ * Hook to access the MessageRuntime from the current context.
+ *
+ * The MessageRuntime provides access to message-level state and actions,
+ * including message content, status, editing capabilities, and branching.
+ *
+ * @param options Configuration options
+ * @param options.optional Whether the hook should return null if no context is found
+ * @returns The MessageRuntime instance, or null if optional is true and no context exists
+ *
+ * @example
+ * ```tsx
+ * function MessageActions() {
+ *   const runtime = useMessageRuntime();
+ *
+ *   const handleReload = () => {
+ *     runtime.reload();
+ *   };
+ *
+ *   const handleEdit = () => {
+ *     runtime.startEdit();
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleReload}>Reload</button>
+ *       <button onClick={handleEdit}>Edit</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useMessageRuntime(options?: {
+  optional?: false | undefined;
+}): MessageRuntime;
+export function useMessageRuntime(options?: {
+  optional?: boolean | undefined;
+}): MessageRuntime | null;
+export function useMessageRuntime(options?: {
+  optional?: boolean | undefined;
+}) {
+  const api = useAssistantApi();
+  const runtime = api.message.source
+    ? api.message().__internal_getRuntime()
+    : null;
+  if (!runtime && !options?.optional) {
+    throw new Error("MessageRuntime is not available");
+  }
+  return runtime;
+}
+
+/**
+ * Hook to access the current message state.
+ *
+ * This hook provides reactive access to the message's state, including content,
+ * role, status, and other message-level properties.
+ *
+ * @param selector Optional selector function to pick specific state properties
+ * @returns The selected message state or the entire message state if no selector provided
+ *
+ * @example
+ * ```tsx
+ * function MessageContent() {
+ *   const role = useMessage((state) => state.role);
+ *   const content = useMessage((state) => state.content);
+ *   const isLoading = useMessage((state) => state.status.type === "running");
+ *
+ *   return (
+ *     <div className={`message-${role}`}>
+ *       {isLoading ? "Loading..." : content.map(part => part.text).join("")}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export const useMessage = createStateHookForRuntime(useMessageRuntime);
+
+const useEditComposerRuntime = (opt: {
+  optional: boolean | undefined;
+}): EditComposerRuntime | null => useMessageRuntime(opt)?.composer ?? null;
+export const useEditComposer = createStateHookForRuntime(
+  useEditComposerRuntime,
+);

package/src/legacy-runtime/hooks/MessagePartContext.ts

@@ -0,0 +1,24 @@
+"use client";
+
+import { MessagePartRuntime } from "../runtime/MessagePartRuntime";
+import { createStateHookForRuntime } from "../../context/react/utils/createStateHookForRuntime";
+import { useAssistantApi } from "../../context/react";
+
+export function useMessagePartRuntime(options?: {
+  optional?: false | undefined;
+}): MessagePartRuntime;
+export function useMessagePartRuntime(options?: {
+  optional?: boolean | undefined;
+}): MessagePartRuntime | null;
+export function useMessagePartRuntime(options?: {
+  optional?: boolean | undefined;
+}) {
+  const api = useAssistantApi();
+  const runtime = api.part.source ? api.part().__internal_getRuntime() : null;
+  if (!runtime && !options?.optional) {
+    throw new Error("MessagePartRuntime is not available");
+  }
+  return runtime;
+}
+
+export const useMessagePart = createStateHookForRuntime(useMessagePartRuntime);

package/src/legacy-runtime/hooks/ThreadContext.ts

@@ -0,0 +1,94 @@
+"use client";
+
+import { useState } from "react";
+import { ThreadRuntime } from "../runtime/ThreadRuntime";
+import { ModelContext } from "../../model-context";
+import { createStateHookForRuntime } from "../../context/react/utils/createStateHookForRuntime";
+import { ThreadComposerRuntime } from "../runtime";
+import { useAssistantApi, useAssistantEvent } from "../../context/react";
+
+/**
+ * Hook to access the ThreadRuntime from the current context.
+ *
+ * The ThreadRuntime provides access to thread-level state and actions,
+ * including message management, thread state, and composer functionality.
+ *
+ * @param options Configuration options
+ * @param options.optional Whether the hook should return null if no context is found
+ * @returns The ThreadRuntime instance, or null if optional is true and no context exists
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const runtime = useThreadRuntime();
+ *
+ *   const handleSendMessage = (text: string) => {
+ *     runtime.append({ role: "user", content: [{ type: "text", text }] });
+ *   };
+ *
+ *   return <button onClick={() => handleSendMessage("Hello!")}>Send</button>;
+ * }
+ * ```
+ */
+export function useThreadRuntime(options?: {
+  optional?: false | undefined;
+}): ThreadRuntime;
+export function useThreadRuntime(options?: {
+  optional?: boolean | undefined;
+}): ThreadRuntime | null;
+export function useThreadRuntime(options?: { optional?: boolean | undefined }) {
+  const api = useAssistantApi();
+  const runtime = api.thread.source
+    ? api.thread().__internal_getRuntime()
+    : null;
+  if (!runtime && !options?.optional) {
+    throw new Error("ThreadRuntime is not available");
+  }
+  return runtime;
+}
+
+/**
+ * Hook to access the current thread state.
+ *
+ * This hook provides reactive access to the thread's state, including messages,
+ * running status, capabilities, and other thread-level properties.
+ *
+ * @param selector Optional selector function to pick specific state properties
+ * @returns The selected thread state or the entire thread state if no selector provided
+ *
+ * @example
+ * ```tsx
+ * function ThreadStatus() {
+ *   const isRunning = useThread((state) => state.isRunning);
+ *   const messageCount = useThread((state) => state.messages.length);
+ *
+ *   return <div>Running: {isRunning}, Messages: {messageCount}</div>;
+ * }
+ * ```
+ */
+export const useThread = createStateHookForRuntime(useThreadRuntime);
+
+const useThreadComposerRuntime = (opt: {
+  optional: boolean | undefined;
+}): ThreadComposerRuntime | null => useThreadRuntime(opt)?.composer ?? null;
+export const useThreadComposer = createStateHookForRuntime(
+  useThreadComposerRuntime,
+);
+
+export function useThreadModelContext(options?: {
+  optional?: false | undefined;
+}): ModelContext;
+export function useThreadModelContext(options?: {
+  optional?: boolean | undefined;
+}): ModelContext | null;
+export function useThreadModelContext(options?: {
+  optional?: boolean | undefined;
+}): ModelContext | null {
+  const [, rerender] = useState({});
+
+  const runtime = useThreadRuntime(options);
+  useAssistantEvent("thread.model-context-update", () => rerender({}));
+
+  if (!runtime) return null;
+  return runtime?.getModelContext();
+}

package/src/legacy-runtime/hooks/ThreadListItemContext.ts

@@ -0,0 +1,28 @@
+"use client";
+
+import { ThreadListItemRuntime } from "../runtime/ThreadListItemRuntime";
+import { createStateHookForRuntime } from "../../context/react/utils/createStateHookForRuntime";
+import { useAssistantApi } from "../../context/react";
+
+export function useThreadListItemRuntime(options?: {
+  optional?: false | undefined;
+}): ThreadListItemRuntime;
+export function useThreadListItemRuntime(options?: {
+  optional?: boolean | undefined;
+}): ThreadListItemRuntime | null;
+export function useThreadListItemRuntime(options?: {
+  optional?: boolean | undefined;
+}) {
+  const api = useAssistantApi();
+  const runtime = api.threadListItem.source
+    ? api.threadListItem().__internal_getRuntime()
+    : null;
+  if (!runtime && !options?.optional) {
+    throw new Error("ThreadListItemRuntime is not available");
+  }
+  return runtime;
+}
+
+export const useThreadListItem = createStateHookForRuntime(
+  useThreadListItemRuntime,
+);