@assistant-ui/core 0.2.6 → 0.2.8

package/dist/types/message.js.map

@@ -1 +1 @@
-{"version":3,"file":"message.js","names":[],"sources":["../../src/types/message.ts"],"sourcesContent":["import type {\n  ReadonlyJSONObject,\n  ReadonlyJSONValue,\n} from \"assistant-stream/utils\";\nimport type { ToolModelContentPart } from \"assistant-stream\";\nimport type { CompleteAttachment } from \"./attachment\";\n\nexport type { ToolModelContentPart };\n\nexport type TextMessagePart = {\n  readonly type: \"text\";\n  readonly text: string;\n  readonly parentId?: string;\n};\n\nexport type ReasoningMessagePart = {\n  readonly type: \"reasoning\";\n  readonly text: string;\n  readonly parentId?: string;\n};\n\nexport type SourceProviderMetadata = {\n  readonly [providerName: string]: ReadonlyJSONObject;\n};\n\nexport type SourceMessagePart =\n  | {\n      readonly type: \"source\";\n      readonly sourceType: \"url\";\n      readonly id: string;\n      readonly url: string;\n      readonly title?: string;\n      readonly providerMetadata?: SourceProviderMetadata;\n      readonly parentId?: string;\n    }\n  | {\n      readonly type: \"source\";\n      readonly sourceType: \"document\";\n      readonly id: string;\n      readonly url?: undefined;\n      readonly title: string;\n      readonly mediaType: string;\n      readonly filename?: string;\n      readonly providerMetadata?: SourceProviderMetadata;\n      readonly parentId?: string;\n    };\n\nexport type ImageMessagePart = {\n  readonly type: \"image\";\n  readonly image: string;\n  readonly filename?: string;\n};\n\nexport type FileMessagePart = {\n  readonly type: \"file\";\n  readonly filename?: string;\n  readonly data: string;\n  readonly mimeType: string;\n  readonly parentId?: string;\n};\n\nexport type Unstable_AudioMessagePart = {\n  readonly type: \"audio\";\n  readonly audio: {\n    readonly data: string;\n    readonly format: \"mp3\" | \"wav\";\n  };\n};\n\nexport type DataMessagePart<T = any> = {\n  readonly type: \"data\";\n  readonly name: string;\n  readonly data: T;\n};\n\n/**\n * A JSON spec describing a tree of UI components to render.\n *\n * The agent emits a {@link GenerativeUIMessagePart} containing this spec, and\n * the consumer-provided component allowlist is used to resolve `component`\n * names. Any component referenced that is not present in the allowlist is\n * rejected with a typed error — the allowlist is the security boundary in the\n * default same-realm rendering path.\n */\nexport type GenerativeUINode =\n  | string\n  | {\n      /** Allowlisted component name (resolved against the consumer registry). */\n      readonly component: string;\n      /** Props passed to the resolved component (must be JSON-serializable). */\n      readonly props?: Record<string, unknown>;\n      /** Optional children — strings render as text, objects recurse. */\n      readonly children?: readonly GenerativeUINode[];\n      /** Optional stable key for React reconciliation. */\n      readonly key?: string;\n    };\n\n/**\n * The root spec for a generative UI tree.\n */\nexport type GenerativeUISpec = {\n  /** Root node(s) to render. */\n  readonly root: GenerativeUINode | readonly GenerativeUINode[];\n};\n\n/**\n * A message part that carries a JSON spec describing UI to render.\n *\n * Render with `<MessagePrimitive.GenerativeUI components={...} />`. The\n * primitive resolves component names against the consumer-provided allowlist\n * — any unknown name throws a typed error rather than rendering. Stream-\n * friendly: a partially-streamed spec renders progressively.\n */\nexport type GenerativeUIMessagePart = {\n  readonly type: \"generative-ui\";\n  /** The JSON spec describing the UI tree. */\n  readonly spec: GenerativeUISpec;\n  /** Optional id (useful for replays / stable keys). */\n  readonly id?: string;\n  readonly parentId?: string;\n};\n\nexport type McpAppMetadata = {\n  readonly resourceUri: string;\n  readonly mimeType?: string;\n  readonly visibility?: readonly (\"model\" | \"app\")[];\n};\n\nexport const MCP_APP_URI_SCHEME = \"ui://\";\n\nexport const isMcpAppUri = (uri: string | undefined): boolean =>\n  !!uri?.startsWith(MCP_APP_URI_SCHEME);\n\nexport type ToolCallMessagePartMcpMetadata = {\n  readonly app?: McpAppMetadata;\n};\n\nexport type ToolCallMessagePart<\n  TArgs = ReadonlyJSONObject,\n  TResult = unknown,\n> = {\n  /** Identifies this part as a tool call. */\n  readonly type: \"tool-call\";\n  /** Stable identifier for this invocation of the tool. */\n  readonly toolCallId: string;\n  /** Name of the tool requested by the model. */\n  readonly toolName: string;\n  /**\n   * Arguments supplied by the model. During streaming this is a partial parse:\n   * fields may be missing or incomplete. From a tool-call renderer, use\n   * `useToolArgsStatus` to detect which fields are still arriving.\n   */\n  readonly args: TArgs;\n  /** Result returned by the tool, if it has completed. */\n  readonly result?: TResult | undefined;\n  /** Whether the result represents a tool execution error. */\n  readonly isError?: boolean | undefined;\n  /** Raw JSON argument text streamed by the model. */\n  readonly argsText: string;\n  /** UI-only artifact associated with the tool result. */\n  readonly artifact?: unknown;\n  /** MCP app metadata associated with this tool call, when present. */\n  readonly mcp?: ToolCallMessagePartMcpMetadata;\n  /** Content returned to the model for this tool result. */\n  readonly modelContent?: readonly ToolModelContentPart[] | undefined;\n  /** Human-input request that must be resolved before the run can continue. */\n  readonly interrupt?: { type: \"human\"; payload: unknown };\n  /** Server-side approval gate. `approved === undefined` is the only state in which `respondToApproval` may be called. */\n  readonly approval?: {\n    readonly id: string;\n    readonly approved?: boolean;\n    readonly reason?: string;\n    readonly isAutomatic?: boolean;\n  };\n  /** Parent message-part ID when this part belongs to a nested structure. */\n  readonly parentId?: string;\n  /**\n   * Nested thread messages produced by this tool call, for example a sub-agent\n   * conversation.\n   */\n  readonly messages?: readonly ThreadMessage[];\n};\n\nexport type ThreadUserMessagePart =\n  | TextMessagePart\n  | ImageMessagePart\n  | FileMessagePart\n  | DataMessagePart\n  | Unstable_AudioMessagePart;\n\nexport type ThreadAssistantMessagePart =\n  | TextMessagePart\n  | ReasoningMessagePart\n  | ToolCallMessagePart\n  | SourceMessagePart\n  | FileMessagePart\n  | ImageMessagePart\n  | DataMessagePart\n  | GenerativeUIMessagePart;\n\nexport type MessagePartStatus =\n  | {\n      readonly type: \"running\";\n    }\n  | {\n      readonly type: \"complete\";\n    }\n  | {\n      readonly type: \"incomplete\";\n      readonly reason:\n        | \"cancelled\"\n        | \"length\"\n        | \"content-filter\"\n        | \"other\"\n        | \"error\";\n      readonly error?: unknown;\n    };\n\nexport type ToolCallMessagePartStatus =\n  | {\n      /** The tool call is waiting for UI or human input before continuing. */\n      readonly type: \"requires-action\";\n      /** Reason the tool call requires action. */\n      readonly reason: \"interrupt\";\n    }\n  | MessagePartStatus;\n\nexport type MessageStatus =\n  | {\n      readonly type: \"running\";\n    }\n  | {\n      readonly type: \"requires-action\";\n      readonly reason: \"tool-calls\" | \"interrupt\";\n    }\n  | {\n      readonly type: \"complete\";\n      readonly reason: \"stop\" | \"unknown\";\n    }\n  | {\n      readonly type: \"incomplete\";\n      readonly reason:\n        | \"cancelled\"\n        | \"tool-calls\"\n        | \"length\"\n        | \"content-filter\"\n        | \"other\"\n        | \"error\";\n      readonly error?: ReadonlyJSONValue;\n    };\n\nexport type MessageTiming = {\n  readonly streamStartTime: number;\n  readonly firstTokenTime?: number;\n  readonly totalStreamTime?: number;\n  readonly tokenCount?: number;\n  readonly tokensPerSecond?: number;\n  readonly totalChunks: number;\n  readonly toolCallCount: number;\n};\n\nexport type ThreadStep = {\n  readonly messageId?: string;\n  readonly usage?:\n    | {\n        readonly inputTokens: number;\n        readonly outputTokens: number;\n      }\n    | undefined;\n};\n\ntype MessageCommonProps = {\n  readonly id: string;\n  readonly createdAt: Date;\n};\n\nexport type ThreadSystemMessage = MessageCommonProps & {\n  readonly role: \"system\";\n  readonly content: readonly [TextMessagePart];\n  readonly metadata: {\n    readonly unstable_state?: undefined;\n    readonly unstable_annotations?: undefined;\n    readonly unstable_data?: undefined;\n    readonly steps?: undefined;\n    readonly submittedFeedback?: undefined;\n    readonly timing?: undefined;\n    readonly custom: Record<string, unknown>;\n  };\n};\n\nexport type ThreadUserMessage = MessageCommonProps & {\n  readonly role: \"user\";\n  readonly content: readonly ThreadUserMessagePart[];\n  readonly attachments: readonly CompleteAttachment[];\n  readonly metadata: {\n    readonly unstable_state?: undefined;\n    readonly unstable_annotations?: undefined;\n    readonly unstable_data?: undefined;\n    readonly steps?: undefined;\n    readonly submittedFeedback?: undefined;\n    readonly timing?: undefined;\n    readonly custom: Record<string, unknown>;\n  };\n};\n\nexport type ThreadAssistantMessage = MessageCommonProps & {\n  readonly role: \"assistant\";\n  readonly content: readonly ThreadAssistantMessagePart[];\n  readonly status: MessageStatus;\n  readonly metadata: {\n    readonly unstable_state: ReadonlyJSONValue;\n    readonly unstable_annotations: readonly ReadonlyJSONValue[];\n    readonly unstable_data: readonly ReadonlyJSONValue[];\n    readonly steps: readonly ThreadStep[];\n    readonly submittedFeedback?: { readonly type: \"positive\" | \"negative\" };\n    readonly timing?: MessageTiming;\n    readonly custom: Record<string, unknown>;\n  };\n};\n\ntype BaseThreadMessage = {\n  readonly status?: ThreadAssistantMessage[\"status\"];\n  readonly metadata: {\n    readonly unstable_state?: ReadonlyJSONValue;\n    readonly unstable_annotations?: readonly ReadonlyJSONValue[];\n    readonly unstable_data?: readonly ReadonlyJSONValue[];\n    readonly steps?: readonly ThreadStep[];\n    readonly submittedFeedback?: { readonly type: \"positive\" | \"negative\" };\n    readonly timing?: MessageTiming;\n    readonly custom: Record<string, unknown>;\n  };\n  readonly attachments?: ThreadUserMessage[\"attachments\"];\n};\n\nexport type ThreadMessage = BaseThreadMessage &\n  (ThreadSystemMessage | ThreadUserMessage | ThreadAssistantMessage);\n\nexport type MessageRole = ThreadMessage[\"role\"];\n\nexport type RunConfig = {\n  readonly custom?: Record<string, unknown>;\n};\n\nexport type AppendMessage = Omit<ThreadMessage, \"id\"> & {\n  parentId: string | null;\n\n  /** The ID of the message that was edited or undefined. */\n  sourceId: string | null;\n  runConfig: RunConfig | undefined;\n  startRun?: boolean | undefined;\n};\n"],"mappings":";AAgIA,MAAa,qBAAqB;AAElC,MAAa,eAAe,QAC1B,CAAC,CAAC,KAAK,WAAW,kBAAkB"}
+{"version":3,"file":"message.js","names":[],"sources":["../../src/types/message.ts"],"sourcesContent":["import type {\n  ReadonlyJSONObject,\n  ReadonlyJSONValue,\n} from \"assistant-stream/utils\";\nimport type { ToolModelContentPart } from \"assistant-stream\";\nimport type { CompleteAttachment } from \"./attachment\";\n\nexport type { ToolModelContentPart };\n\nexport type TextMessagePart = {\n  readonly type: \"text\";\n  readonly text: string;\n  readonly parentId?: string;\n};\n\nexport type ReasoningMessagePart = {\n  readonly type: \"reasoning\";\n  readonly text: string;\n  readonly parentId?: string;\n};\n\nexport type SourceProviderMetadata = {\n  readonly [providerName: string]: ReadonlyJSONObject;\n};\n\nexport type SourceMessagePart =\n  | {\n      readonly type: \"source\";\n      readonly sourceType: \"url\";\n      readonly id: string;\n      readonly url: string;\n      readonly title?: string;\n      readonly providerMetadata?: SourceProviderMetadata;\n      readonly parentId?: string;\n    }\n  | {\n      readonly type: \"source\";\n      readonly sourceType: \"document\";\n      readonly id: string;\n      readonly url?: undefined;\n      readonly title: string;\n      readonly mediaType: string;\n      readonly filename?: string;\n      readonly providerMetadata?: SourceProviderMetadata;\n      readonly parentId?: string;\n    };\n\nexport type ImageMessagePart = {\n  readonly type: \"image\";\n  readonly image: string;\n  readonly filename?: string;\n};\n\nexport type FileMessagePart = {\n  readonly type: \"file\";\n  readonly filename?: string;\n  readonly data: string;\n  readonly mimeType: string;\n  readonly parentId?: string;\n};\n\nexport type Unstable_AudioMessagePart = {\n  readonly type: \"audio\";\n  readonly audio: {\n    readonly data: string;\n    readonly format: \"mp3\" | \"wav\";\n  };\n};\n\nexport type DataMessagePart<T = any> = {\n  readonly type: \"data\";\n  readonly name: string;\n  readonly data: T;\n};\n\n/**\n * A JSON spec describing a tree of UI components to render.\n *\n * The agent emits a {@link GenerativeUIMessagePart} containing this spec, and\n * the consumer-provided component allowlist is used to resolve `component`\n * names. Any component referenced that is not present in the allowlist is\n * rejected with a typed error — the allowlist is the security boundary in the\n * default same-realm rendering path.\n */\nexport type GenerativeUINode =\n  | string\n  | {\n      /** Allowlisted component name (resolved against the consumer registry). */\n      readonly component: string;\n      /** Props passed to the resolved component (must be JSON-serializable). */\n      readonly props?: Record<string, unknown>;\n      /** Optional children — strings render as text, objects recurse. */\n      readonly children?: readonly GenerativeUINode[];\n      /** Optional stable key for React reconciliation. */\n      readonly key?: string;\n    };\n\n/**\n * The root spec for a generative UI tree.\n */\nexport type GenerativeUISpec = {\n  /** Root node(s) to render. */\n  readonly root: GenerativeUINode | readonly GenerativeUINode[];\n};\n\n/**\n * A message part that carries a JSON spec describing UI to render.\n *\n * Render with `<MessagePrimitive.GenerativeUI components={...} />`. The\n * primitive resolves component names against the consumer-provided allowlist\n * — any unknown name throws a typed error rather than rendering. Stream-\n * friendly: a partially-streamed spec renders progressively.\n */\nexport type GenerativeUIMessagePart = {\n  readonly type: \"generative-ui\";\n  /** The JSON spec describing the UI tree. */\n  readonly spec: GenerativeUISpec;\n  /** Optional id (useful for replays / stable keys). */\n  readonly id?: string;\n  readonly parentId?: string;\n};\n\nexport type McpAppMetadata = {\n  readonly resourceUri: string;\n  readonly mimeType?: string;\n  readonly visibility?: readonly (\"model\" | \"app\")[];\n};\n\nexport const MCP_APP_URI_SCHEME = \"ui://\";\n\nexport const isMcpAppUri = (uri: string | undefined): boolean =>\n  !!uri?.startsWith(MCP_APP_URI_SCHEME);\n\nexport type ToolCallMessagePartMcpMetadata = {\n  readonly app?: McpAppMetadata;\n};\n\nexport type ToolCallMessagePart<\n  TArgs = ReadonlyJSONObject,\n  TResult = unknown,\n> = {\n  /** Identifies this part as a tool call. */\n  readonly type: \"tool-call\";\n  /** Stable identifier for this invocation of the tool. */\n  readonly toolCallId: string;\n  /** Name of the tool requested by the model. */\n  readonly toolName: string;\n  /**\n   * Arguments supplied by the model. During streaming this is a partial parse:\n   * fields may be missing or incomplete. From a tool-call renderer, use\n   * `useToolArgsStatus` to detect which fields are still arriving.\n   */\n  readonly args: TArgs;\n  /** Result returned by the tool, if it has completed. */\n  readonly result?: TResult | undefined;\n  /** Whether the result represents a tool execution error. */\n  readonly isError?: boolean | undefined;\n  /** Raw JSON argument text streamed by the model. */\n  readonly argsText: string;\n  /** UI-only artifact associated with the tool result. */\n  readonly artifact?: unknown;\n  /** MCP app metadata associated with this tool call, when present. */\n  readonly mcp?: ToolCallMessagePartMcpMetadata;\n  /** Content returned to the model for this tool result. */\n  readonly modelContent?: readonly ToolModelContentPart[] | undefined;\n  /** Human-input request that must be resolved before the run can continue. */\n  readonly interrupt?: { type: \"human\"; payload: unknown };\n  /** Server-side approval gate. `approved === undefined` is the only state in which `respondToApproval` may be called. */\n  readonly approval?: {\n    readonly id: string;\n    readonly approved?: boolean;\n    readonly reason?: string;\n    readonly isAutomatic?: boolean;\n  };\n  /** Parent message-part ID when this part belongs to a nested structure. */\n  readonly parentId?: string;\n  /**\n   * Nested thread messages produced by this tool call, for example a sub-agent\n   * conversation.\n   */\n  readonly messages?: readonly ThreadMessage[];\n};\n\nexport type ThreadUserMessagePart =\n  | TextMessagePart\n  | ImageMessagePart\n  | FileMessagePart\n  | DataMessagePart\n  | Unstable_AudioMessagePart;\n\nexport type ThreadAssistantMessagePart =\n  | TextMessagePart\n  | ReasoningMessagePart\n  | ToolCallMessagePart\n  | SourceMessagePart\n  | FileMessagePart\n  | ImageMessagePart\n  | DataMessagePart\n  | GenerativeUIMessagePart;\n\nexport type MessagePartStatus =\n  | {\n      readonly type: \"running\";\n    }\n  | {\n      readonly type: \"complete\";\n    }\n  | {\n      readonly type: \"incomplete\";\n      readonly reason:\n        | \"cancelled\"\n        | \"length\"\n        | \"content-filter\"\n        | \"other\"\n        | \"error\";\n      readonly error?: unknown;\n    };\n\nexport type ToolCallMessagePartStatus =\n  | {\n      /** The tool call is waiting for UI or human input before continuing. */\n      readonly type: \"requires-action\";\n      /** Reason the tool call requires action. */\n      readonly reason: \"interrupt\";\n    }\n  | MessagePartStatus;\n\nexport type MessageStatus =\n  | {\n      readonly type: \"running\";\n    }\n  | {\n      readonly type: \"requires-action\";\n      readonly reason: \"tool-calls\" | \"interrupt\";\n    }\n  | {\n      readonly type: \"complete\";\n      readonly reason: \"stop\" | \"unknown\";\n    }\n  | {\n      readonly type: \"incomplete\";\n      readonly reason:\n        | \"cancelled\"\n        | \"tool-calls\"\n        | \"length\"\n        | \"content-filter\"\n        | \"other\"\n        | \"error\";\n      readonly error?: ReadonlyJSONValue;\n    };\n\nexport type MessageTiming = {\n  readonly streamStartTime: number;\n  readonly firstTokenTime?: number;\n  readonly totalStreamTime?: number;\n  readonly tokenCount?: number;\n  readonly tokensPerSecond?: number;\n  readonly totalChunks: number;\n  readonly toolCallCount: number;\n};\n\nexport type ThreadStep = {\n  readonly messageId?: string;\n  readonly usage?:\n    | {\n        readonly inputTokens: number;\n        readonly outputTokens: number;\n      }\n    | undefined;\n};\n\ntype MessageCommonProps = {\n  readonly id: string;\n  readonly createdAt: Date;\n};\n\nexport type ThreadSystemMessage = MessageCommonProps & {\n  readonly role: \"system\";\n  readonly content: readonly [TextMessagePart];\n  readonly metadata: {\n    readonly unstable_state?: undefined;\n    readonly unstable_annotations?: undefined;\n    readonly unstable_data?: undefined;\n    readonly steps?: undefined;\n    readonly submittedFeedback?: undefined;\n    readonly timing?: undefined;\n    readonly custom: Record<string, unknown>;\n  };\n};\n\nexport type ThreadUserMessage = MessageCommonProps & {\n  readonly role: \"user\";\n  readonly content: readonly ThreadUserMessagePart[];\n  readonly attachments: readonly CompleteAttachment[];\n  readonly metadata: {\n    readonly unstable_state?: undefined;\n    readonly unstable_annotations?: undefined;\n    readonly unstable_data?: undefined;\n    readonly steps?: undefined;\n    readonly submittedFeedback?: undefined;\n    readonly timing?: undefined;\n    readonly custom: Record<string, unknown>;\n  };\n};\n\nexport type ThreadAssistantMessage = MessageCommonProps & {\n  readonly role: \"assistant\";\n  readonly content: readonly ThreadAssistantMessagePart[];\n  readonly status: MessageStatus;\n  readonly metadata: {\n    readonly unstable_state: ReadonlyJSONValue;\n    readonly unstable_annotations: readonly ReadonlyJSONValue[];\n    readonly unstable_data: readonly ReadonlyJSONValue[];\n    readonly steps: readonly ThreadStep[];\n    readonly submittedFeedback?: { readonly type: \"positive\" | \"negative\" };\n    readonly timing?: MessageTiming;\n    /**\n     * Marks a client-side optimistic placeholder. Such messages are evicted\n     * once off the head branch and are never persisted.\n     */\n    readonly isOptimistic?: boolean;\n    readonly custom: Record<string, unknown>;\n  };\n};\n\ntype BaseThreadMessage = {\n  readonly status?: ThreadAssistantMessage[\"status\"];\n  readonly metadata: {\n    readonly unstable_state?: ReadonlyJSONValue;\n    readonly unstable_annotations?: readonly ReadonlyJSONValue[];\n    readonly unstable_data?: readonly ReadonlyJSONValue[];\n    readonly steps?: readonly ThreadStep[];\n    readonly submittedFeedback?: { readonly type: \"positive\" | \"negative\" };\n    readonly timing?: MessageTiming;\n    readonly isOptimistic?: boolean;\n    readonly custom: Record<string, unknown>;\n  };\n  readonly attachments?: ThreadUserMessage[\"attachments\"];\n};\n\nexport type ThreadMessage = BaseThreadMessage &\n  (ThreadSystemMessage | ThreadUserMessage | ThreadAssistantMessage);\n\nexport type MessageRole = ThreadMessage[\"role\"];\n\nexport type RunConfig = {\n  readonly custom?: Record<string, unknown>;\n};\n\nexport type AppendMessage = Omit<ThreadMessage, \"id\"> & {\n  parentId: string | null;\n\n  /** The ID of the message that was edited or undefined. */\n  sourceId: string | null;\n  runConfig: RunConfig | undefined;\n  startRun?: boolean | undefined;\n};\n"],"mappings":";AAgIA,MAAa,qBAAqB;AAElC,MAAa,eAAe,QAC1B,CAAC,CAAC,KAAK,WAAW,kBAAkB"}

package/dist/utils/composite-context-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite-context-provider.d.ts","names":[],"sources":["../../src/utils/composite-context-provider.ts"],"mappings":";;cAKa,wBAAA,YAAoC,oBAAA;EAAA,QACvC,UAAA;EAER,eAAA,CAAA,GAHoC,YAAA;EAOpC,4BAAA,CAA6B,QAAA,EAAU,oBAAA;EAAA,QAa/B,YAAA;EAER,iBAAA,CAAA;EAIA,SAAA,CAAU,QAAA;AAAA"}
+{"version":3,"file":"composite-context-provider.d.ts","names":[],"sources":["../../src/utils/composite-context-provider.ts"],"mappings":";;cAKa,wBAAA,YAAoC,oBAAA;EAAA,QACvC,UAAA;EAER,eAAA,IAHoC,YAAA;EAOpC,4BAAA,CAA6B,QAAA,EAAU,oBAAA;EAAA,QAa/B,YAAA;EAER,iBAAA;EAIA,SAAA,CAAU,QAAA;AAAA"}

package/dist/utils/id.d.ts

@@ -1,9 +1,7 @@
 //#region src/utils/id.d.ts
 declare const generateId: (size?: number) => string;
-declare const generateOptimisticId: () => string;
-declare const isOptimisticId: (id: string) => boolean;
 declare const generateErrorMessageId: () => string;
 declare const isErrorMessageId: (id: string) => boolean;
 //#endregion
-export { generateErrorMessageId, generateId, generateOptimisticId, isErrorMessageId, isOptimisticId };
+export { generateErrorMessageId, generateId, isErrorMessageId };
 //# sourceMappingURL=id.d.ts.map

package/dist/utils/id.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"id.d.ts","names":[],"sources":["../../src/utils/id.ts"],"mappings":";cAEa,UAAA,GAAU,IAAA;AAAA,cAMV,oBAAA;AAAA,cACA,cAAA,GAAkB,EAAU;AAAA,cAG5B,sBAAA;AAAA,cACA,gBAAA,GAAoB,EAAU"}
+{"version":3,"file":"id.d.ts","names":[],"sources":["../../src/utils/id.ts"],"mappings":";cAEa,UAAA,GAAU,IAAA;AAAA,cAMV,sBAAA;AAAA,cACA,gBAAA,GAAoB,EAAU"}

package/dist/utils/id.js

@@ -1,13 +1,10 @@
 import { customAlphabet } from "nanoid/non-secure";
 //#region src/utils/id.ts
 const generateId = customAlphabet("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz", 7);
-const optimisticPrefix = "__optimistic__";
-const generateOptimisticId = () => `${optimisticPrefix}${generateId()}`;
-const isOptimisticId = (id) => id.startsWith(optimisticPrefix);
 const errorPrefix = "__error__";
 const generateErrorMessageId = () => `${errorPrefix}${generateId()}`;
 const isErrorMessageId = (id) => id.startsWith(errorPrefix);
 //#endregion
-export { generateErrorMessageId, generateId, generateOptimisticId, isErrorMessageId, isOptimisticId };
+export { generateErrorMessageId, generateId, isErrorMessageId };
 
 //# sourceMappingURL=id.js.map

package/dist/utils/id.js.map

@@ -1 +1 @@
-{"version":3,"file":"id.js","names":[],"sources":["../../src/utils/id.ts"],"sourcesContent":["import { customAlphabet } from \"nanoid/non-secure\";\n\nexport const generateId = customAlphabet(\n  \"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz\",\n  7,\n);\n\nconst optimisticPrefix = \"__optimistic__\";\nexport const generateOptimisticId = () => `${optimisticPrefix}${generateId()}`;\nexport const isOptimisticId = (id: string) => id.startsWith(optimisticPrefix);\n\nconst errorPrefix = \"__error__\";\nexport const generateErrorMessageId = () => `${errorPrefix}${generateId()}`;\nexport const isErrorMessageId = (id: string) => id.startsWith(errorPrefix);\n"],"mappings":";;AAEA,MAAa,aAAa,eACxB,kEACA,CACF;AAEA,MAAM,mBAAmB;AACzB,MAAa,6BAA6B,GAAG,mBAAmB,WAAW;AAC3E,MAAa,kBAAkB,OAAe,GAAG,WAAW,gBAAgB;AAE5E,MAAM,cAAc;AACpB,MAAa,+BAA+B,GAAG,cAAc,WAAW;AACxE,MAAa,oBAAoB,OAAe,GAAG,WAAW,WAAW"}
+{"version":3,"file":"id.js","names":[],"sources":["../../src/utils/id.ts"],"sourcesContent":["import { customAlphabet } from \"nanoid/non-secure\";\n\nexport const generateId = customAlphabet(\n  \"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz\",\n  7,\n);\n\nconst errorPrefix = \"__error__\";\nexport const generateErrorMessageId = () => `${errorPrefix}${generateId()}`;\nexport const isErrorMessageId = (id: string) => id.startsWith(errorPrefix);\n"],"mappings":";;AAEA,MAAa,aAAa,eACxB,kEACA,CACF;AAEA,MAAM,cAAc;AACpB,MAAa,+BAA+B,GAAG,cAAc,WAAW;AACxE,MAAa,oBAAoB,OAAe,GAAG,WAAW,WAAW"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/core",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Framework-agnostic core runtime for assistant-ui",
   "keywords": [
     "assistant",
@@ -59,15 +59,15 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "assistant-stream": "^0.3.17",
+    "assistant-stream": "^0.3.18",
     "nanoid": "^5.1.11"
   },
   "peerDependencies": {
-    "@assistant-ui/store": "^0.2.12",
-    "@assistant-ui/tap": "^0.5.12",
+    "@assistant-ui/store": "^0.2.13",
+    "@assistant-ui/tap": "^0.5.14",
     "@types/react": "*",
     "react": "^18 || ^19",
-    "assistant-cloud": "^0.1.29",
+    "assistant-cloud": "^0.1.30",
     "zustand": "^5.0.11"
   },
   "peerDependenciesMeta": {
@@ -88,11 +88,11 @@
     "@types/react": "^19.2.15",
     "react": "^19.2.6",
     "vitest": "^4.1.7",
-    "zustand": "^5.0.13",
-    "@assistant-ui/store": "0.2.12",
-    "@assistant-ui/tap": "0.5.12",
-    "@assistant-ui/x-buildutils": "0.0.9",
-    "assistant-cloud": "0.1.29"
+    "zustand": "^5.0.14",
+    "@assistant-ui/store": "0.2.13",
+    "@assistant-ui/tap": "0.5.14",
+    "@assistant-ui/x-buildutils": "0.0.10",
+    "assistant-cloud": "0.1.30"
   },
   "publishConfig": {
     "access": "public",

package/src/adapters/index.ts

@@ -8,10 +8,7 @@ export {
 
 // Speech adapters
 export type { SpeechSynthesisAdapter, DictationAdapter } from "./speech";
-export {
-  WebSpeechSynthesisAdapter,
-  WebSpeechDictationAdapter,
-} from "./speech";
+export { WebSpeechSynthesisAdapter, WebSpeechDictationAdapter } from "./speech";
 
 // Voice adapter
 export type { RealtimeVoiceAdapter } from "./voice";

package/src/adapters/speech.ts

@@ -64,7 +64,6 @@ export class WebSpeechSynthesisAdapter implements SpeechSynthesisAdapter {
       if (res.status.type === "ended") return;
 
       res.status = { type: "ended", reason, error };
-      // biome-ignore lint/suspicious/useIterableCallbackReturn: forEach callback intentionally has no return
       subscribers.forEach((handler) => handler());
     };
 

package/src/index.ts

@@ -1,5 +1,13 @@
 // @assistant-ui/core - Framework-agnostic core runtime (public API)
 
+/// <reference path="./store/scope-registration.ts" />
+
+import { checkDuplicateCore } from "./internal/duplicate-detection";
+
+if (process.env.NODE_ENV !== "production") {
+  checkDuplicateCore();
+}
+
 export type {
   // Message parts
   TextMessagePart,
@@ -80,6 +88,8 @@ export { mergeModelContexts } from "./model-context/types";
 
 export { tool } from "./model-context/tool";
 
+export type { ToolExecutionStatus } from "./runtimes/tool-invocations/ToolInvocationTracker";
+
 export { ModelContextRegistry } from "./model-context/registry";
 export type {
   ModelContextRegistryToolHandle,
@@ -272,6 +282,8 @@ export type {
   ExternalStoreThreadListAdapter,
   ExternalStoreThreadData,
 } from "./runtimes/external-store/external-store-adapter";
+export type { ExternalStoreSharedOptions } from "./runtimes/external-store/external-store-shared-options";
+export { pickExternalStoreSharedOptions } from "./runtimes/external-store/external-store-shared-options";
 
 // Remote Thread List (user-facing)
 export type {

package/src/internal/duplicate-detection.ts

@@ -0,0 +1,26 @@
+// Warns once if a second copy of @assistant-ui/core is loaded into the
+// same runtime. Mismatched transitive versions of core silently break
+// runtime behavior — tools registered via `makeAssistantTool` don't reach
+// the active runtime, context lookups resolve to the wrong provider,
+// `instanceof` checks fail (see issue #4101). The actual version diagnosis
+// lives in `npx assistant-ui doctor`.
+//
+// The caller is responsible for gating on `process.env.NODE_ENV` so this
+// module tree-shakes out of production bundles.
+
+const KEY = Symbol.for("@assistant-ui/core.loaded");
+
+export function checkDuplicateCore(): void {
+  const g = globalThis as unknown as Record<symbol, boolean | undefined>;
+  if (g[KEY]) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      "[@assistant-ui/core] Multiple copies of @assistant-ui/core are " +
+        "loaded into the same runtime. This causes subtle bugs (tools not " +
+        "reaching the runtime, context lookups returning the wrong " +
+        "provider, instanceof checks failing). Run " +
+        "`npx assistant-ui doctor` to diagnose.",
+    );
+  }
+  g[KEY] = true;
+}

package/src/internal.ts

@@ -26,8 +26,6 @@ export type {
 // ID generation
 export {
   generateId,
-  generateOptimisticId,
-  isOptimisticId,
   generateErrorMessageId,
   isErrorMessageId,
 } from "./utils/id";

package/src/model-context/frame/host.ts

@@ -175,7 +175,6 @@ export class AssistantFrameHost implements ModelContextProvider {
   }
 
   private notifySubscribers() {
-    // biome-ignore lint/suspicious/useIterableCallbackReturn: forEach callback intentionally has no return
     this._subscribers.forEach((callback) => callback());
   }
 

package/src/model-context/frame/provider.ts

@@ -179,7 +179,6 @@ export class AssistantFrameProvider {
       const instance = AssistantFrameProvider._instance;
       window.removeEventListener("message", instance.handleMessage);
 
-      // biome-ignore lint/suspicious/useIterableCallbackReturn: forEach callback intentionally has no return
       instance._providerUnsubscribes.forEach((unsubscribe) => unsubscribe?.());
       instance._providerUnsubscribes.clear();
       instance._providers.clear();

package/src/react/AssistantProvider.tsx

@@ -10,9 +10,8 @@ import type { AssistantRuntimeCore } from "../runtime/interfaces/assistant-runti
 import { RuntimeAdapter } from "./RuntimeAdapter";
 
 export const getRenderComponent = (runtime: AssistantRuntime) => {
-  return (runtime as { _core?: AssistantRuntimeCore })._core?.RenderComponent as
-    | ComponentType
-    | undefined;
+  return (runtime as { _core?: AssistantRuntimeCore })._core
+    ?.RenderComponent as ComponentType | undefined;
 };
 
 export type AssistantProviderBaseProps = PropsWithChildren<{

package/src/react/client/Interactables.ts

@@ -253,7 +253,6 @@ export const Interactables = resource((): ClientOutput<"interactables"> => {
     [setDefState],
   );
 
-  // biome-ignore lint/correctness/useExhaustiveDependencies: state dep triggers notification
   tapEffect(() => {
     for (const cb of subscribersRef.current) cb();
   }, [state]);

package/src/react/client/Tools.ts

@@ -15,7 +15,10 @@ import {
 } from "@assistant-ui/store";
 import type { McpAppResourceOutput, ToolsState } from "../types/scopes/tools";
 import type { Tool } from "assistant-stream";
-import type { Toolkit } from "../model-context/toolbox";
+import {
+  isStandaloneToolDisplay,
+  type Toolkit,
+} from "../model-context/toolbox";
 import type { ToolCallMessagePartComponent } from "../types/MessagePartComponentTypes";
 import { ModelContext } from "../../store";
 
@@ -45,36 +48,53 @@ export const Tools = resource(
     );
     const mcpAppOutput = mcpAppOutputs[0];
 
-    const [toolsState, setToolsState] = tapState<{
-      tools: ToolsState["tools"];
-    }>(() => ({
-      tools: {},
-    }));
+    const [toolUIs, setToolUIs] = tapState<ToolsState["toolUIs"]>(() => ({}));
 
     const state = tapMemo(
-      (): ToolsState => ({ tools: toolsState.tools, mcpApp: mcpAppOutput }),
-      [toolsState, mcpAppOutput],
+      (): ToolsState => ({
+        toolUIs,
+        mcpApp: mcpAppOutput,
+        // Deprecated component-only view, derived from `toolUIs`. Removed in v0.15.
+        tools: Object.fromEntries(
+          Object.entries(toolUIs).map(([name, regs]) => [
+            name,
+            regs.map((r) => r.render),
+          ]),
+        ),
+      }),
+      [toolUIs, mcpAppOutput],
     );
 
     const clientRef = tapAssistantClientRef();
 
     const setToolUI = tapCallback(
-      (toolName: string, render: ToolCallMessagePartComponent) => {
-        setToolsState((prev) => ({
-          tools: {
-            ...prev.tools,
-            [toolName]: [...(prev.tools[toolName] ?? []), render],
-          },
+      (
+        toolName: string,
+        render: ToolCallMessagePartComponent,
+        options?: { standalone?: boolean },
+      ) => {
+        // One registration object per call; identity is the removal key, so
+        // the per-name list stays correctly ref-counted across re-registers.
+        const registration = {
+          render,
+          standalone: options?.standalone ?? false,
+        };
+
+        setToolUIs((prev) => ({
+          ...prev,
+          [toolName]: [...(prev[toolName] ?? []), registration],
         }));
 
         return () => {
-          setToolsState((prev) => ({
-            tools: {
-              ...prev.tools,
-              [toolName]:
-                prev.tools[toolName]?.filter((r) => r !== render) ?? [],
-            },
-          }));
+          setToolUIs((prev) => {
+            const next =
+              prev[toolName]?.filter((r) => r !== registration) ?? [];
+            if (next.length > 0) return { ...prev, [toolName]: next };
+            // Drop the key entirely so repeatedly mounted/unmounted tools
+            // don't leave empty arrays accumulating across a long session.
+            const { [toolName]: _removed, ...rest } = prev;
+            return rest;
+          });
         };
       },
       [],
@@ -87,14 +107,20 @@ export const Tools = resource(
       // Register tool UIs (exclude symbols)
       for (const [toolName, tool] of Object.entries(toolkit)) {
         if (tool.render) {
-          unsubscribes.push(setToolUI(toolName, tool.render));
+          unsubscribes.push(
+            setToolUI(toolName, tool.render, {
+              standalone: isStandaloneToolDisplay(tool),
+            }),
+          );
         }
       }
 
-      // Register tools with model context (exclude symbols)
+      // Register tools with model context (exclude symbols). `render` and
+      // `display` are client-only presentation concerns and never reach the
+      // model.
       const toolsWithoutRender = Object.entries(toolkit).reduce(
         (acc, [name, tool]) => {
-          const { render, ...rest } = tool;
+          const { render, display, ...rest } = tool;
           acc[name] = rest;
           return acc;
         },
@@ -112,7 +138,6 @@ export const Tools = resource(
       );
 
       return () => {
-        // biome-ignore lint/suspicious/useIterableCallbackReturn: forEach callback intentionally has no return
         unsubscribes.forEach((fn) => fn());
       };
     }, [toolkit, setToolUI, clientRef]);

package/src/react/index.ts

@@ -1,3 +1,4 @@
+/// <reference path="../store/scope-registration.ts" />
 /// <reference path="./types/store-augmentation.ts" />
 
 // model-context
@@ -31,7 +32,12 @@ export {
   type AssistantDataUIProps,
 } from "./model-context/useAssistantDataUI";
 export { useInlineRender } from "./model-context/useInlineRender";
-export type { Toolkit, ToolDefinition } from "./model-context/toolbox";
+export {
+  type Toolkit,
+  type ToolDefinition,
+  type ToolkitDeclaration,
+  type ToolkitDeclarationDefinition,
+} from "./model-context/toolbox";
 export {
   useAssistantInteractable,
   type AssistantInteractableProps,
@@ -129,13 +135,8 @@ export {
   useRuntimeAdapters,
   type RuntimeAdapters,
 } from "./runtimes/RuntimeAdapterProvider";
-export {
-  useToolInvocations,
-  type ToolExecutionStatus,
-  type AssistantTransportState,
-  type AddToolResultCommand,
-} from "./runtimes/useToolInvocations";
 export { useExternalStoreRuntime } from "./runtimes/useExternalStoreRuntime";
+export { useExternalStoreSharedOptions } from "./runtimes/useExternalStoreSharedOptions";
 export {
   useExternalMessageConverter,
   convertExternalMessages,
@@ -178,7 +179,7 @@ export {
   type PartState,
 } from "./primitives/message/MessageParts";
 export { MessagePrimitiveGroupedParts } from "./primitives/message/MessageGroupedParts";
-export { groupPartByType } from "./utils/groupParts";
+export { groupPartByType, type GroupByContext } from "./utils/groupParts";
 export {
   MessagePrimitiveGenerativeUI,
   GenerativeUIRender,

package/src/react/model-context/toolbox.ts

@@ -1,6 +1,22 @@
-import type { Tool } from "assistant-stream";
+import type { Tool, ToolDeclaration } from "assistant-stream";
 import type { ToolCallMessagePartComponent } from "../types/MessagePartComponentTypes";
 
+/**
+ * Resolves whether a tool's UI should be presented standalone (outside the
+ * chain-of-thought grouping), applying the type-based defaults.
+ *
+ * An explicit `display` wins. Otherwise `human` tools default to standalone
+ * (they prompt the user), and every other tool defaults to inline (a trace of
+ * what the model is doing). MCP-app tool calls are detected separately from
+ * the part itself and are not resolved here.
+ */
+export const isStandaloneToolDisplay = (
+  tool: Pick<Tool<any, any>, "type" | "display">,
+): boolean => {
+  if (tool.display !== undefined) return tool.display === "standalone";
+  return tool.type === "human";
+};
+
 type WithRender<T, TArgs extends Record<string, unknown>, TResult> = T extends {
   type: "frontend" | "human";
 }
@@ -43,6 +59,35 @@ export type ToolDefinition<
  */
 export type Toolkit = Record<string, ToolDefinition<any, any>>;
 
+/**
+ * A tool as authored, before the build splits it: like {@link ToolDefinition}
+ * but it may declare `description`, `parameters`, and a server-side `execute`
+ * alongside its `render`. The `type` field is **not** authored — the
+ * `"use generative"` compiler infers it (`execute: hitl()` → human; `execute`
+ * with a `"use client"` directive → frontend; otherwise backend) and writes it
+ * back — so declaring it here is a type error.
+ */
+export type ToolkitDeclarationDefinition<
+  TArgs extends Record<string, unknown>,
+  TResult,
+> = WithRender<
+  Omit<ToolDeclaration<TArgs, TResult>, "type">,
+  TArgs,
+  TResult
+> & {
+  type?: never;
+};
+
+/**
+ * The permissive, authoring-time counterpart to {@link Toolkit} — the input to
+ * {@link defineToolkit}. Backend entries may carry their server `execute` here;
+ * the canonical {@link Toolkit} keeps those fields `undefined`.
+ */
+export type ToolkitDeclaration = Record<
+  string,
+  ToolkitDeclarationDefinition<any, any>
+>;
+
 /** Configuration for the {@link Tools} resource. */
 export type ToolsConfig = {
   /** Tools to register with model context and, when provided, message renderers. */

package/src/react/model-context/useAssistantTool.ts

@@ -2,6 +2,7 @@ import { useEffect } from "react";
 import { useAui } from "@assistant-ui/store";
 import type { ToolCallMessagePartComponent } from "../types/MessagePartComponentTypes";
 import type { AssistantToolProps as CoreAssistantToolProps } from "../..";
+import { isStandaloneToolDisplay } from "./toolbox";
 
 /**
  * Props used to register a tool from React.
@@ -52,13 +53,17 @@ export const useAssistantTool = <
 ) => {
   const aui = useAui();
 
+  const standalone = isStandaloneToolDisplay(tool);
+
   useEffect(() => {
     if (!tool.render) return undefined;
-    return aui.tools().setToolUI(tool.toolName, tool.render);
-  }, [aui, tool.toolName, tool.render]);
+    return aui.tools().setToolUI(tool.toolName, tool.render, { standalone });
+  }, [aui, tool.toolName, tool.render, standalone]);
 
   useEffect(() => {
-    const { toolName, render, ...rest } = tool;
+    // `render` and `display` are client-only presentation concerns and never
+    // reach the model.
+    const { toolName, render, display, ...rest } = tool;
     const context = {
       tools: {
         [toolName]: rest,

package/src/react/model-context/useAssistantToolUI.ts

@@ -8,6 +8,12 @@ export type AssistantToolUIProps<TArgs, TResult> = {
   toolName: string;
   /** Component rendered for matching tool-call message parts. */
   render: ToolCallMessagePartComponent<TArgs, TResult>;
+  /**
+   * How the UI is presented relative to the chain-of-thought trace. Set
+   * `"standalone"` to surface it on its own (e.g. human-in-the-loop or
+   * generative UI for a backend/MCP tool). Defaults to `"inline"`.
+   */
+  display?: "standalone" | "inline";
 };
 
 /**
@@ -23,8 +29,9 @@ export const useAssistantToolUI = (
   tool: AssistantToolUIProps<any, any> | null,
 ) => {
   const aui = useAui();
+  const standalone = tool?.display === "standalone";
   useEffect(() => {
     if (!tool?.toolName || !tool?.render) return undefined;
-    return aui.tools().setToolUI(tool.toolName, tool.render);
-  }, [aui, tool?.toolName, tool?.render]);
+    return aui.tools().setToolUI(tool.toolName, tool.render, { standalone });
+  }, [aui, tool?.toolName, tool?.render, standalone]);
 };

package/src/react/model-context/useInlineRender.ts

@@ -17,7 +17,6 @@ export const useInlineRender = <TArgs, TResult>(
 
   return useCallback(
     function ToolUI(args) {
-      // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
       const store = useToolUIStore();
       return store.toolUI(args);
     },

package/src/react/primitives/chainOfThought/ChainOfThoughtParts.tsx

@@ -86,8 +86,7 @@ export const ChainOfThoughtPrimitiveParts: FC<
     );
   }
 
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
+  // oxlint-disable-next-line react-hooks/rules-of-hooks -- intentional conditional hook below the early return above
   const messageComponents = useMemo(
     () => ({
       Reasoning: components?.Reasoning,

package/src/react/primitives/message/MessageAttachments.test.tsx

@@ -4,7 +4,7 @@ import { MessagePrimitiveAttachments } from "./MessageAttachments";
 
 const mockUseAuiState = vi.fn();
 type UseAuiStateSelector = Parameters<
-  typeof import("@assistant-ui/store")["useAuiState"]
+  (typeof import("@assistant-ui/store"))["useAuiState"]
 >[0];
 type AttachmentsElement = ReactElement<{ children: () => null }>;