@assistant-ui/core 0.2.5 → 0.2.6

package/src/react/utils/groupParts.ts

@@ -1,3 +1,6 @@
+import { isMcpAppUri } from "../../types/message";
+import type { PartState } from "../../store/scopes/part";
+
 /**
  * Hierarchical adjacent-coalescing grouping for message parts.
  *
@@ -11,16 +14,71 @@
  */
 
 /**
- * Public group key type. Group keys must be prefixed with `group-` so
- * that a unified `switch (part.type)` in the renderer can distinguish
- * a group key (e.g. `"group-thought"`) from a real part type
- * (`"text"`, `"tool-call"`).
+ * Symbol attached to memoizable `groupBy` functions (e.g. those returned
+ * by {@link groupPartByType}). Carries a string fingerprint of the config
+ * so `MessagePrimitive.GroupedParts` can memo the tree on
+ * `[parts, memoKey]` across renders — even when the helper call site
+ * reconstructs the function each render.
+ */
+export const GROUPBY_MEMO_KEY: unique symbol = Symbol.for(
+  "@assistant-ui/groupBy.memoKey",
+);
+
+/**
+ * Synthetic part-type key recognized by {@link groupPartByType}: a
+ * tool-call whose `mcp.app.resourceUri` points at an assistant-ui MCP
+ * app. Map this key to control how MCP-app tool calls are grouped —
+ * separately from regular `"tool-call"` parts.
+ */
+type GroupPartType = PartState["type"] | "mcp-app";
+
+/**
+ * Build a `groupBy` from a `part.type → group-key path` lookup.
+ * Parts whose type isn't in the map are left ungrouped. The returned
+ * function carries a stable {@link GROUPBY_MEMO_KEY} fingerprint so
+ * `<MessagePrimitive.GroupedParts>` can memoize its tree across renders.
+ *
+ * Special key `"mcp-app"` matches tool-call parts that point at an
+ * assistant-ui MCP app resource (`ui://...`) and takes precedence over
+ * the `"tool-call"` entry for those parts.
+ *
+ * @example
+ * ```tsx
+ * <MessagePrimitive.GroupedParts
+ *   groupBy={groupPartByType({
+ *     reasoning: ["group-thought", "group-reasoning"],
+ *     "tool-call": ["group-thought", "group-tool"],
+ *     "mcp-app": [],
+ *   })}
+ * >
+ *   {({ part, children }) => { ... }}
+ * </MessagePrimitive.GroupedParts>
+ * ```
  */
-export type GroupKey<TKey extends `group-${string}` = `group-${string}`> =
-  | TKey
-  | readonly TKey[]
-  | null
-  | undefined;
+export const groupPartByType = <TKey extends `group-${string}`>(
+  map: Partial<Readonly<Record<GroupPartType, readonly TKey[]>>>,
+): ((part: PartState) => readonly TKey[]) => {
+  const lookup = map as Readonly<Record<string, readonly TKey[] | undefined>>;
+  const fn = ((part) => {
+    if (
+      part.type === "tool-call" &&
+      lookup["mcp-app"] !== undefined &&
+      isMcpAppUri(part.mcp?.app?.resourceUri)
+    ) {
+      return lookup["mcp-app"]!;
+    }
+    return lookup[part.type] ?? [];
+  }) as ((part: PartState) => readonly TKey[]) & {
+    [GROUPBY_MEMO_KEY]?: string;
+  };
+  // Sort keys so the fingerprint is insensitive to map insertion order —
+  // two maps with the same key/value pairs but different declaration order
+  // would otherwise hash differently and invalidate the memo unnecessarily.
+  const sortedKeys = Object.keys(map).sort();
+  const sortedEntries = sortedKeys.map((k) => [k, map[k as keyof typeof map]]);
+  fn[GROUPBY_MEMO_KEY] = `groupPartByType:${JSON.stringify(sortedEntries)}`;
+  return fn;
+};
 
 export type GroupNode = GroupNodeGroup | GroupNodePart;
 
@@ -43,19 +101,6 @@ export interface GroupNodePart {
   readonly nodeKey: string;
 }
 
-const EMPTY_PATH: readonly string[] = Object.freeze([]);
-
-/**
- * Normalize a `groupBy` return value to a path array.
- * `null`/`undefined`/`[]` → `[]` (ungrouped).
- * `"foo"` → `["foo"]`. Arrays pass through.
- */
-export const normalizeGroupKey = (key: GroupKey): readonly string[] => {
-  if (key == null) return EMPTY_PATH;
-  if (typeof key === "string") return [key];
-  return key;
-};
-
 interface BuildFrame {
   key: string;
   nodeKey: string;

package/src/runtime/api/message-part-runtime.ts

@@ -26,6 +26,7 @@ type MessagePartSnapshotBinding = SubscribableWithState<
 export type MessagePartRuntime = {
   addToolResult(result: any | ToolResponse<any>): void;
   resumeToolCall(payload: unknown): void;
+  respondToToolApproval(response: { approved: boolean; reason?: string }): void;
 
   readonly path: MessagePartRuntimePath;
   getState(): MessagePartState;
@@ -48,6 +49,7 @@ export class MessagePartRuntimeImpl implements MessagePartRuntime {
   protected __internal_bindMethods() {
     this.addToolResult = this.addToolResult.bind(this);
     this.resumeToolCall = this.resumeToolCall.bind(this);
+    this.respondToToolApproval = this.respondToToolApproval.bind(this);
     this.getState = this.getState.bind(this);
     this.subscribe = this.subscribe.bind(this);
   }
@@ -102,6 +104,30 @@ export class MessagePartRuntimeImpl implements MessagePartRuntime {
     });
   }
 
+  public respondToToolApproval(response: {
+    approved: boolean;
+    reason?: string;
+  }) {
+    const state = this.contentBinding.getState();
+    if (!state) throw new Error("Message part is not available");
+
+    if (state.type !== "tool-call")
+      throw new Error(
+        "Tried to respond to tool approval on non-tool message part",
+      );
+
+    if (!state.approval || state.approval.approved !== undefined)
+      throw new Error("Tool call has no pending approval");
+
+    if (!this.threadApi) throw new Error("Thread API is not available");
+
+    this.threadApi.getState().respondToToolApproval({
+      approvalId: state.approval.id,
+      approved: response.approved,
+      ...(response.reason != null && { reason: response.reason }),
+    });
+  }
+
   public subscribe(callback: () => void) {
     return this.contentBinding.subscribe(callback);
   }

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

@@ -15,6 +15,7 @@ import { DefaultThreadComposerRuntimeCore } from "./default-thread-composer-runt
 import type {
   AddToolResultOptions,
   ResumeToolCallOptions,
+  RespondToToolApprovalOptions,
   ThreadSuggestion,
   SubmitFeedbackOptions,
   ThreadRuntimeCore,
@@ -59,6 +60,9 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
   public abstract resumeRun(config: ResumeRunConfig): void;
   public abstract addToolResult(options: AddToolResultOptions): void;
   public abstract resumeToolCall(options: ResumeToolCallOptions): void;
+  public abstract respondToToolApproval(
+    options: RespondToToolApprovalOptions,
+  ): void;
   public abstract cancelRun(): void;
   public abstract exportExternalState(): any;
   public abstract importExternalState(state: any): void;

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

@@ -45,6 +45,12 @@ export type ResumeToolCallOptions = {
   payload: unknown;
 };
 
+export type RespondToToolApprovalOptions = {
+  approvalId: string;
+  approved: boolean;
+  reason?: string;
+};
+
 export type SubmitFeedbackOptions = {
   messageId: string;
   type: "negative" | "positive";
@@ -137,6 +143,7 @@ export type ThreadRuntimeCore = Readonly<{
 
   addToolResult: (options: AddToolResultOptions) => void;
   resumeToolCall: (options: ResumeToolCallOptions) => void;
+  respondToToolApproval: (options: RespondToToolApprovalOptions) => void;
 
   speak: (messageId: string) => void;
   stopSpeaking: () => void;

package/src/runtime/utils/thread-message-like.ts

@@ -54,6 +54,13 @@ export type ThreadMessageLike = {
             readonly isError?: boolean | undefined;
             readonly parentId?: string | undefined;
             readonly messages?: readonly ThreadMessage[] | undefined;
+            readonly interrupt?: { type: "human"; payload: unknown };
+            readonly approval?: {
+              readonly id: string;
+              readonly approved?: boolean;
+              readonly reason?: string;
+              readonly isAutomatic?: boolean;
+            };
           }
       )[];
   readonly id?: string | undefined;

package/src/runtimes/external-store/external-store-adapter.ts

@@ -9,6 +9,7 @@ import type { RealtimeVoiceAdapter } from "../../adapters/voice";
 import type { FeedbackAdapter } from "../../adapters/feedback";
 import type {
   AddToolResultOptions,
+  RespondToToolApprovalOptions,
   StartRunConfig,
   ResumeRunConfig,
   ThreadSuggestion,
@@ -108,6 +109,9 @@ type ExternalStoreAdapterBase<T> = {
   onResumeToolCall?:
     | ((options: { toolCallId: string; payload: unknown }) => void)
     | undefined;
+  onRespondToToolApproval?:
+    | ((options: RespondToToolApprovalOptions) => Promise<void> | void)
+    | undefined;
   convertMessage?: ExternalStoreMessageConverter<T> | undefined;
   adapters?:
     | {

package/src/runtimes/external-store/external-store-thread-runtime-core.ts

@@ -3,6 +3,7 @@ import type {
   AddToolResultOptions,
   ResumeRunConfig,
   ResumeToolCallOptions,
+  RespondToToolApprovalOptions,
   StartRunConfig,
   ThreadSuggestion,
 } from "../../runtime/interfaces/thread-runtime-core";
@@ -372,6 +373,12 @@ export class ExternalStoreThreadRuntimeCore
     this._store.onResumeToolCall(options);
   }
 
+  public respondToToolApproval(options: RespondToToolApprovalOptions) {
+    if (!this._store.onRespondToToolApproval)
+      throw new Error("Runtime does not support tool approvals.");
+    this._store.onRespondToToolApproval(options);
+  }
+
   public override reset(initialMessages?: readonly ThreadMessageLike[]) {
     this._lastSyncedMessageIds = new Set();
     const repo = new MessageRepository();

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

@@ -9,6 +9,7 @@ import type { LocalRuntimeOptionsBase } from "./local-runtime-options";
 import type {
   AddToolResultOptions,
   ResumeToolCallOptions,
+  RespondToToolApprovalOptions,
   ThreadSuggestion,
   ThreadRuntimeCore,
   StartRunConfig,
@@ -535,4 +536,8 @@ export class LocalThreadRuntimeCore
   public resumeToolCall(_options: ResumeToolCallOptions) {
     throw new Error("Local runtime does not support resuming tool calls.");
   }
+
+  public respondToToolApproval(_options: RespondToToolApprovalOptions) {
+    throw new Error("Local runtime does not support tool approvals.");
+  }
 }

package/src/runtimes/readonly/ReadonlyThreadRuntimeCore.ts

@@ -65,6 +65,10 @@ export class ReadonlyThreadRuntimeCore
     throw READONLY_THREAD_ERROR;
   }
 
+  respondToToolApproval(): void {
+    throw READONLY_THREAD_ERROR;
+  }
+
   speak(): void {
     throw READONLY_THREAD_ERROR;
   }

package/src/runtimes/remote-thread-list/empty-thread-core.ts

@@ -40,6 +40,10 @@ export const EMPTY_THREAD_CORE: ThreadRuntimeCore = {
     throw EMPTY_THREAD_ERROR;
   },
 
+  respondToToolApproval() {
+    throw EMPTY_THREAD_ERROR;
+  },
+
   speak() {
     throw EMPTY_THREAD_ERROR;
   },

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

@@ -38,6 +38,9 @@ const ThreadMessagePartClient = resource(
       resumeToolCall: () => {
         throw new Error("Not supported");
       },
+      respondToToolApproval: () => {
+        throw new Error("Not supported");
+      },
     };
   },
 );

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

@@ -11,6 +11,8 @@ export const MessagePartClient = resource(
       getState: () => state,
       addToolResult: (result) => runtime.addToolResult(result),
       resumeToolCall: (payload) => runtime.resumeToolCall(payload),
+      respondToToolApproval: (response) =>
+        runtime.respondToToolApproval(response),
       __internal_getRuntime: () => runtime,
     };
   },

package/src/store/scopes/part.ts

@@ -26,6 +26,10 @@ export type PartMethods = {
    * This is useful when a tool has requested human input and is waiting for a response.
    */
   resumeToolCall(payload: unknown): void;
+  /**
+   * Respond to a server-side tool approval gate. The approval id is read from the part.
+   */
+  respondToToolApproval(response: { approved: boolean; reason?: string }): void;
   __internal_getRuntime?(): MessagePartRuntime;
 };
 

package/src/tests/groupParts.test.ts

@@ -1,12 +1,13 @@
 import { describe, expect, it } from "vitest";
+import type { PartState } from "../store/scopes/part";
 import {
   buildGroupTree,
-  normalizeGroupKey,
+  GROUPBY_MEMO_KEY,
+  groupPartByType,
   type GroupNode,
 } from "../react/utils/groupParts";
 
-const asPaths = (keys: readonly (string | readonly string[] | null)[]) =>
-  keys.map((k) => normalizeGroupKey(k));
+const asPaths = (keys: readonly (readonly string[])[]) => keys;
 
 // Compact tree dump: "G:key#nodeKey[i,j]{...}" | "P:#nodeKey(i)"
 const dump = (nodes: readonly GroupNode[]): string =>
@@ -20,39 +21,23 @@ const dump = (nodes: readonly GroupNode[]): string =>
     })
     .join(",");
 
-describe("normalizeGroupKey", () => {
-  it("maps null/undefined/[] to []", () => {
-    expect(normalizeGroupKey(null)).toEqual([]);
-    expect(normalizeGroupKey(undefined)).toEqual([]);
-    expect(normalizeGroupKey([])).toEqual([]);
-  });
-
-  it("wraps a string into a single-element array", () => {
-    expect(normalizeGroupKey("foo")).toEqual(["foo"]);
-  });
-
-  it("passes arrays through", () => {
-    expect(normalizeGroupKey(["a", "b"])).toEqual(["a", "b"]);
-  });
-});
-
 describe("buildGroupTree", () => {
   it("returns an empty list for no parts", () => {
     expect(buildGroupTree([])).toEqual([]);
   });
 
   it("emits one part leaf per ungrouped part (no coalescing)", () => {
-    const tree = buildGroupTree(asPaths([null, null, null]));
+    const tree = buildGroupTree(asPaths([[], [], []]));
     expect(dump(tree)).toBe("P:#0(0),P:#1(1),P:#2(2)");
   });
 
   it("wraps adjacent same-key parts in one group with one part child each", () => {
-    const tree = buildGroupTree(asPaths(["a", "a", "a"]));
+    const tree = buildGroupTree(asPaths([["a"], ["a"], ["a"]]));
     expect(dump(tree)).toBe("G:a#0[0,1,2]{P:#0.0(0),P:#0.1(1),P:#0.2(2)}");
   });
 
   it("splits non-adjacent runs of the same key into separate groups", () => {
-    const tree = buildGroupTree(asPaths(["a", null, "a"]));
+    const tree = buildGroupTree(asPaths([["a"], [], ["a"]]));
     expect(dump(tree)).toBe("G:a#0[0]{P:#0.0(0)},P:#1(1),G:a#2[2]{P:#2.0(2)}");
   });
 
@@ -95,20 +80,121 @@ describe("buildGroupTree", () => {
     );
   });
 
-  it("accepts strings and arrays interchangeably via normalizeGroupKey", () => {
-    const tree = buildGroupTree([
-      normalizeGroupKey("A"),
-      normalizeGroupKey(["A"]),
-    ]);
-    expect(dump(tree)).toBe("G:A#0[0,1]{P:#0.0(0),P:#0.1(1)}");
-  });
-
   it("assigns stable nodeKeys under append (existing keys do not shift)", () => {
-    const before = buildGroupTree(asPaths([["A"], null]));
-    const after = buildGroupTree(asPaths([["A"], null, ["B"]]));
+    const before = buildGroupTree(asPaths([["A"], []]));
+    const after = buildGroupTree(asPaths([["A"], [], ["B"]]));
 
     expect(before[0]!.nodeKey).toBe(after[0]!.nodeKey);
     expect(before[1]!.nodeKey).toBe(after[1]!.nodeKey);
     expect(after[2]!.nodeKey).toBe("2");
   });
 });
+
+const part = (overrides: Partial<PartState>): PartState =>
+  ({
+    type: "text",
+    text: "",
+    status: { type: "complete" },
+    ...overrides,
+  }) as PartState;
+
+describe("groupPartByType", () => {
+  it("maps part.type to the configured path", () => {
+    const fn = groupPartByType({
+      reasoning: ["group-thought", "group-reasoning"],
+      "tool-call": ["group-thought", "group-tool"],
+    });
+    expect(fn(part({ type: "reasoning" }))).toEqual([
+      "group-thought",
+      "group-reasoning",
+    ]);
+    expect(fn(part({ type: "tool-call" }))).toEqual([
+      "group-thought",
+      "group-tool",
+    ]);
+  });
+
+  it("returns [] for part types not in the map", () => {
+    const fn = groupPartByType({ reasoning: ["group-r"] });
+    expect(fn(part({ type: "text" }))).toEqual([]);
+  });
+
+  it("routes MCP-app tool calls through the 'mcp-app' entry when present", () => {
+    const fn = groupPartByType({
+      "tool-call": ["group-tool"],
+      "mcp-app": [],
+    });
+    const mcpApp = part({
+      type: "tool-call",
+      toolName: "render",
+      mcp: { app: { resourceUri: "ui://my-app" } },
+    } as Partial<PartState>);
+    const regular = part({
+      type: "tool-call",
+      toolName: "search",
+    } as Partial<PartState>);
+    expect(fn(mcpApp)).toEqual([]);
+    expect(fn(regular)).toEqual(["group-tool"]);
+  });
+
+  it("falls back to 'tool-call' for MCP-app parts when 'mcp-app' is absent", () => {
+    const fn = groupPartByType({ "tool-call": ["group-tool"] });
+    const mcpApp = part({
+      type: "tool-call",
+      toolName: "render",
+      mcp: { app: { resourceUri: "ui://x" } },
+    } as Partial<PartState>);
+    expect(fn(mcpApp)).toEqual(["group-tool"]);
+  });
+
+  it("does not route non-`ui://` tool calls through 'mcp-app'", () => {
+    const fn = groupPartByType({
+      "tool-call": ["group-tool"],
+      "mcp-app": ["group-mcp"],
+    });
+    const notMcp = part({
+      type: "tool-call",
+      toolName: "x",
+      mcp: { app: { resourceUri: "http://example.com" } },
+    } as Partial<PartState>);
+    expect(fn(notMcp)).toEqual(["group-tool"]);
+  });
+
+  it("tags the function with a GROUPBY_MEMO_KEY fingerprint", () => {
+    const fn = groupPartByType({ reasoning: ["group-r"] });
+    const memoKey = (fn as unknown as { [GROUPBY_MEMO_KEY]: string })[
+      GROUPBY_MEMO_KEY
+    ];
+    expect(memoKey).toMatch(/^groupPartByType:/);
+  });
+
+  it("produces the same fingerprint regardless of map key order", () => {
+    const a = groupPartByType({
+      reasoning: ["group-r"],
+      "tool-call": ["group-t"],
+    });
+    const b = groupPartByType({
+      "tool-call": ["group-t"],
+      reasoning: ["group-r"],
+    });
+    const keyA = (a as unknown as { [GROUPBY_MEMO_KEY]: string })[
+      GROUPBY_MEMO_KEY
+    ];
+    const keyB = (b as unknown as { [GROUPBY_MEMO_KEY]: string })[
+      GROUPBY_MEMO_KEY
+    ];
+    expect(keyA).toBe(keyB);
+  });
+
+  it("produces different fingerprints for different configs", () => {
+    const a = groupPartByType({ reasoning: ["group-r"] });
+    const b = groupPartByType({ reasoning: ["group-r2"] });
+    const keyA = (a as unknown as { [GROUPBY_MEMO_KEY]: string })[
+      GROUPBY_MEMO_KEY
+    ];
+    const keyB = (b as unknown as { [GROUPBY_MEMO_KEY]: string })[
+      GROUPBY_MEMO_KEY
+    ];
+    expect(keyA).not.toBe(keyB);
+  });
+});

package/src/types/message.ts

@@ -165,6 +165,13 @@ export type ToolCallMessagePart<
   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. */
+  readonly approval?: {
+    readonly id: string;
+    readonly approved?: boolean;
+    readonly reason?: string;
+    readonly isAutomatic?: boolean;
+  };
   /** Parent message-part ID when this part belongs to a nested structure. */
   readonly parentId?: string;
   /**