@assistant-ui/core 0.2.14 → 0.2.15

package/src/runtimes/local/local-thread-runtime-core.ts

@@ -648,6 +648,7 @@ export class LocalThreadRuntimeCore
   public respondToToolApproval({
     approvalId,
     approved,
+    optionId,
     reason,
   }: RespondToToolApprovalOptions) {
     let message = this.repository
@@ -673,14 +674,25 @@ export class LocalThreadRuntimeCore
         "Tried to respond to a tool approval on a message whose status is not requires-action",
       );
 
-    let recorded = false;
+    const target = message.content.find(
+      (c) => c.type === "tool-call" && c.approval?.id === approvalId,
+    );
+    if (target?.type !== "tool-call" || !target.approval)
+      throw new Error("Tried to respond to a non-existing tool approval");
+    if (target.approval.resolution !== undefined)
+      throw new Error(
+        "Tried to respond to a tool approval that was cancelled or expired",
+      );
+    if (target.approval.approved !== undefined)
+      throw new Error("Tried to respond to an already decided tool approval");
+
+    const targetApproval = target.approval;
     const newContent = message.content.map((c) => {
-      if (c.type !== "tool-call" || c.approval?.id !== approvalId) return c;
-      if (c.approval.approved !== undefined) return c;
-      recorded = true;
+      if (c !== target) return c;
       const approval = {
-        ...c.approval,
+        ...targetApproval,
         approved,
+        ...(optionId != null && { optionId }),
         ...(reason != null && { reason }),
       };
       if (approved) return { ...c, approval };
@@ -692,9 +704,6 @@ export class LocalThreadRuntimeCore
       };
     });
 
-    if (!recorded)
-      throw new Error("Tried to respond to an already decided tool approval");
-
     message = { ...message, content: newContent };
     const { parentId } = this.repository.getMessage(message.id);
     this.repository.addOrUpdateMessage(parentId, message);

package/src/runtimes/local/should-continue.ts

@@ -15,7 +15,8 @@ export const shouldContinue = (
       c.type === "tool-call" &&
       c.result === undefined &&
       c.approval !== undefined &&
-      c.approval.approved === undefined,
+      c.approval.approved === undefined &&
+      c.approval.resolution === undefined,
   );
   if (hasPendingApproval) return false;
 

package/src/store/clients/suggestions.ts

@@ -44,11 +44,9 @@ const useSuggestionsResource = (
   });
 
   const suggestionClients = useClientLookup(
-    () =>
-      state.suggestions.map((suggestion, index) =>
-        withKey(index, SuggestionClient(suggestion)),
-      ),
-    [state.suggestions],
+    state.suggestions.map((suggestion, index) =>
+      withKey(index, SuggestionClient(suggestion), [suggestion]),
+    ),
   );
 
   return {

package/src/store/clients/thread-message-client.ts

@@ -76,24 +76,23 @@ const useThreadMessageClient = ({
   const [isHoveringState, setIsHovering] = useState(false);
 
   const parts = useClientLookup(
-    () =>
-      message.content.map((part, idx) =>
-        withKey(
-          "toolCallId" in part && part.toolCallId != null
-            ? `toolCallId-${part.toolCallId}`
-            : `index-${idx}`,
-          ThreadMessagePartClient({ part }),
-        ),
+    message.content.map((part, idx) =>
+      withKey(
+        "toolCallId" in part && part.toolCallId != null
+          ? `toolCallId-${part.toolCallId}`
+          : `index-${idx}`,
+        ThreadMessagePartClient({ part }),
+        [part],
       ),
-    [message.content],
+    ),
   );
 
   const attachments = useClientLookup(
-    () =>
-      (message.attachments ?? []).map((attachment) =>
-        withKey(attachment.id, ThreadMessageAttachmentClient({ attachment })),
-      ),
-    [message.attachments],
+    (message.attachments ?? []).map((attachment) =>
+      withKey(attachment.id, ThreadMessageAttachmentClient({ attachment }), [
+        attachment,
+      ]),
+    ),
   );
 
   const composer = useResource(NoOpComposerClient({ type: "edit" }));

package/src/store/runtime-clients/composer-runtime-client.ts

@@ -102,33 +102,30 @@ const useComposerClient = ({
   }, [runtime, emit, threadIdRef, messageIdRef]);
 
   const attachments = useClientLookup(
-    () =>
-      runtimeState.attachments.map((attachment, idx) =>
-        withKey(
-          attachment.id,
-          ComposerAttachmentClientByIndex({
-            runtime,
-            index: idx,
-          }),
-        ),
+    runtimeState.attachments.map((attachment, idx) =>
+      withKey(
+        attachment.id,
+        ComposerAttachmentClientByIndex({
+          runtime,
+          index: idx,
+        }),
+        [runtime, idx],
       ),
-    [runtimeState.attachments, runtime],
+    ),
   );
 
   const queue = runtimeState.queue;
   const queueItems = useClientLookup(
-    () =>
-      queue.map((item) =>
-        withKey(
-          item.id,
-          QueueItemClient({
-            item,
-            onSteer: () => runtime.steerQueueItem(item.id),
-            onRemove: () => runtime.removeQueueItem(item.id),
-          }),
-        ),
+    queue.map((item) =>
+      withKey(
+        item.id,
+        QueueItemClient({
+          item,
+          onSteer: () => runtime.steerQueueItem(item.id),
+          onRemove: () => runtime.removeQueueItem(item.id),
+        }),
       ),
-    [queue, runtime],
+    ),
   );
 
   const state = useMemo<ComposerState>(() => {

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

@@ -0,0 +1,5 @@
+export const liveRef = <T>(get: () => T): { readonly current: T } => ({
+  get current() {
+    return get();
+  },
+});

package/src/store/runtime-clients/message-runtime-client.ts

@@ -7,6 +7,7 @@ import {
 } from "@assistant-ui/store";
 import type { MessageRuntime } from "../../runtime/api/message-runtime";
 import { useSubscribable } from "./useSubscribable";
+import { liveRef } from "./liveRef";
 import { ComposerClient } from "./composer-runtime-client";
 import { MessagePartClient } from "./message-part-runtime-client";
 import type { MessageState } from "../scopes/message";
@@ -59,11 +60,7 @@ const useMessageClient = ({
   const [isHoveringState, setIsHovering] = useState(false);
 
   const messageIdRef = useMemo(
-    () => ({
-      get current() {
-        return runtime.getState().id;
-      },
-    }),
+    () => liveRef(() => runtime.getState().id),
     [runtime],
   );
 
@@ -75,27 +72,25 @@ const useMessageClient = ({
     }),
   );
   const parts = useClientLookup(
-    () =>
-      runtimeState.content.map((part, idx) =>
-        withKey(
-          "toolCallId" in part && part.toolCallId != null
-            ? `toolCallId-${part.toolCallId}`
-            : `index-${idx}`,
-          MessagePartByIndex({ runtime, index: idx }),
-        ),
+    runtimeState.content.map((part, idx) =>
+      withKey(
+        "toolCallId" in part && part.toolCallId != null
+          ? `toolCallId-${part.toolCallId}`
+          : `index-${idx}`,
+        MessagePartByIndex({ runtime, index: idx }),
+        [runtime, idx],
       ),
-    [runtimeState.content, runtime],
+    ),
   );
 
   const attachments = useClientLookup(
-    () =>
-      (runtimeState.attachments ?? []).map((attachment, idx) =>
-        withKey(
-          attachment.id,
-          MessageAttachmentClientByIndex({ runtime, index: idx }),
-        ),
+    (runtimeState.attachments ?? []).map((attachment, idx) =>
+      withKey(
+        attachment.id,
+        MessageAttachmentClientByIndex({ runtime, index: idx }),
+        [runtime, idx],
       ),
-    [runtimeState.attachments, runtime],
+    ),
   );
 
   const state = useMemo<MessageState>(() => {

package/src/store/runtime-clients/thread-list-runtime-client.ts

@@ -47,11 +47,9 @@ const useThreadListClient = ({
     }),
   );
   const threadItems = useClientLookup(
-    () =>
-      Object.keys(runtimeState.threadItems).map((id) =>
-        withKey(id, ThreadListItemClientById({ runtime, id })),
-      ),
-    [runtimeState.threadItems, runtime],
+    Object.keys(runtimeState.threadItems).map((id) =>
+      withKey(id, ThreadListItemClientById({ runtime, id }), [runtime, id]),
+    ),
   );
 
   const state = useMemo<ThreadsState>(() => {

package/src/store/runtime-clients/thread-runtime-client.ts

@@ -3,6 +3,7 @@ import type { ThreadRuntimeEventType } from "../../runtime/interfaces/thread-run
 import type { ThreadRuntime } from "../../runtime/api/thread-runtime";
 import { useMemo, useEffect, RefObject } from "react";
 import { useResource, resource, withKey } from "@assistant-ui/tap";
+import { liveRef } from "./liveRef";
 import {
   type ClientOutput,
   useAssistantEmit,
@@ -67,11 +68,7 @@ const useThreadClient = ({
   }, [runtime, emit]);
 
   const threadIdRef = useMemo(
-    () => ({
-      get current() {
-        return runtime.getState()!.threadId;
-      },
-    }),
+    () => liveRef(() => runtime.getState()!.threadId),
     [runtime],
   );
 
@@ -82,11 +79,13 @@ const useThreadClient = ({
     }),
   );
   const messages = useClientLookup(
-    () =>
-      runtimeState.messages.map((m) =>
-        withKey(m.id, MessageClientById({ runtime, id: m.id, threadIdRef })),
-      ),
-    [runtimeState.messages, runtime, threadIdRef],
+    runtimeState.messages.map((m) =>
+      withKey(m.id, MessageClientById({ runtime, id: m.id, threadIdRef }), [
+        runtime,
+        m.id,
+        threadIdRef,
+      ]),
+    ),
   );
 
   const state = useMemo<ThreadState>(() => {

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

@@ -1,16 +1,8 @@
-import { useState, useEffect } from "react";
+import { useSyncExternalStore } from "react";
 import type { SubscribableWithState } from "../../subscribable/subscribable";
 
 export const useSubscribable = <T>(
   subscribable: Omit<SubscribableWithState<T, any>, "path">,
 ) => {
-  const [, setState] = useState(subscribable.getState);
-  useEffect(() => {
-    setState(subscribable.getState());
-    return subscribable.subscribe(() => {
-      setState(subscribable.getState());
-    });
-  }, [subscribable]);
-
-  return subscribable.getState();
+  return useSyncExternalStore(subscribable.subscribe, subscribable.getState);
 };

package/src/store/scopes/part.ts

@@ -2,6 +2,7 @@ import type { ToolResponse } from "assistant-stream";
 import type {
   ThreadUserMessagePart,
   ThreadAssistantMessagePart,
+  ToolApprovalResponse,
   ToolCallMessagePartStatus,
 } from "../../types/message";
 import type { MessagePartStatus } from "../../types/message";
@@ -27,9 +28,11 @@ export type PartMethods = {
    */
   resumeToolCall(payload: unknown): void;
   /**
-   * Respond to a server-side tool approval gate. The approval id is read from the part.
+   * Respond to a server-side tool approval gate. The approval id is read from
+   * the part. Accepts a boolean decision or the id of one of the approval's
+   * options.
    */
-  respondToToolApproval(response: { approved: boolean; reason?: string }): void;
+  respondToToolApproval(response: ToolApprovalResponse): void;
   __internal_getRuntime?(): MessagePartRuntime;
 };
 

package/src/types/message.ts

@@ -2,10 +2,10 @@ import type {
   ReadonlyJSONObject,
   ReadonlyJSONValue,
 } from "assistant-stream/utils";
-import type { ToolModelContentPart } from "assistant-stream";
+import type { ToolCallTiming, ToolModelContentPart } from "assistant-stream";
 import type { CompleteAttachment } from "./attachment";
 
-export type { ToolModelContentPart };
+export type { ToolCallTiming, ToolModelContentPart };
 
 export type TextMessagePart = {
   readonly type: "text";
@@ -135,6 +135,40 @@ export type ToolCallMessagePartMcpMetadata = {
   readonly app?: McpAppMetadata;
 };
 
+export type ToolApprovalOptionKind =
+  | "allow-once"
+  | "allow-always"
+  | "reject-once"
+  | "reject-always";
+
+export type ToolApprovalOption = {
+  /** Opaque, host-defined identifier. Scope semantics (session vs project vs global) belong to the option supplier. */
+  readonly id: string;
+  /**
+   * Decision class. Drives approved-resolution and default rendering.
+   * Open union: `_`-prefixed custom kinds are never auto-resolved and the
+   * default kit skips them; they must be answered with an explicit
+   * `approved` value (optionally alongside the `optionId`).
+   */
+  readonly kind: ToolApprovalOptionKind | (string & {});
+  /** Human label. Renderers supply defaults per kind when omitted. */
+  readonly label?: string;
+  readonly description?: string;
+  /** Patterns or rules this option would persist, shown before the user commits. Supplied by the host; never derived by the library. */
+  readonly grants?: readonly string[];
+  /** Opt-in confirmation step before this option resolves. */
+  readonly confirm?: boolean | { title?: string; description?: string };
+};
+
+export type ToolApprovalResponse =
+  | { readonly approved: boolean; readonly reason?: string }
+  | { readonly optionId: string; readonly reason?: string }
+  | {
+      readonly approved: boolean;
+      readonly optionId: string;
+      readonly reason?: string;
+    };
+
 export type ToolCallMessagePart<
   TArgs = ReadonlyJSONObject,
   TResult = unknown,
@@ -159,18 +193,26 @@ export type ToolCallMessagePart<
   readonly argsText: string;
   /** UI-only artifact associated with the tool result. */
   readonly artifact?: unknown;
+  /** Wall-clock timing for this call, when the runtime or host tracks it. */
+  readonly timing?: ToolCallTiming;
   /** MCP app metadata associated with this tool call, when present. */
   readonly mcp?: ToolCallMessagePartMcpMetadata;
   /** Content returned to the model for this tool result. */
   readonly modelContent?: readonly ToolModelContentPart[] | undefined;
   /** Human-input request that must be resolved before the run can continue. */
   readonly interrupt?: { type: "human"; payload: unknown };
-  /** Server-side approval gate. `approved === undefined` is the only state in which `respondToApproval` may be called. */
+  /** Server-side approval gate. `respondToApproval` may only be called while `approved` is undefined and no `resolution` is recorded. */
   readonly approval?: {
     readonly id: string;
     readonly approved?: boolean;
     readonly reason?: string;
     readonly isAutomatic?: boolean;
+    /** Available decisions for this call. Absent: a plain allow / deny pair. */
+    readonly options?: readonly ToolApprovalOption[];
+    /** The option chosen at resolution, when options were present. */
+    readonly optionId?: string;
+    /** Terminal non-decision state: the request was cancelled or expired without a user decision. Set by the host. */
+    readonly resolution?: "cancelled" | "expired";
   };
   /** Parent message-part ID when this part belongs to a nested structure. */
   readonly parentId?: string;