@assistant-ui/react-ag-ui 0.0.59 → 0.0.61

package/dist/useAgUiRuntime.js.map

@@ -1 +1 @@
-{"version":3,"file":"useAgUiRuntime.js","names":[],"sources":["../src/useAgUiRuntime.ts"],"sourcesContent":["\"use client\";\n\nimport {\n  useCallback,\n  useEffect,\n  useLayoutEffect,\n  useMemo,\n  useRef,\n  useState,\n  useSyncExternalStore,\n} from \"react\";\nimport {\n  useExternalStoreRuntime,\n  useExternalStoreSharedOptions,\n  useRuntimeAdapters,\n} from \"@assistant-ui/core/react\";\nimport { createMessageQueue } from \"@assistant-ui/core\";\nimport type {\n  MessageQueueController,\n  ToolExecutionStatus,\n} from \"@assistant-ui/core\";\nimport type {\n  AssistantRuntime,\n  AppendMessage,\n  ExternalStoreAdapter,\n  ThreadMessage,\n} from \"@assistant-ui/core\";\nimport type { ReadonlyJSONValue } from \"assistant-stream/utils\";\nimport { makeLogger } from \"./runtime/logger\";\nimport type {\n  AgUiInterrupt,\n  AgUiResumeEntry,\n  UseAgUiRuntimeOptions,\n} from \"./runtime/types\";\nimport { AgUiThreadRuntimeCore } from \"./runtime/AgUiThreadRuntimeCore\";\nimport { agUiExtras } from \"./agUiExtras\";\nimport type { QueueItemState } from \"@assistant-ui/core/store\";\n\nconst EMPTY_INTERRUPTS: readonly AgUiInterrupt[] = [];\nconst EMPTY_QUEUE_ITEMS: readonly QueueItemState[] = Object.freeze([]);\nconst subscribeNoop = () => () => {};\n\nexport type AgUiAssistantRuntime = AssistantRuntime & {\n  /**\n   * @deprecated Use the `useAgUiInterrupts()` hook instead. This method is kept\n   * for backward compatibility and will be removed in a future major release.\n   */\n  unstable_getPendingInterrupts: () => readonly AgUiInterrupt[];\n  /**\n   * @deprecated Use the `useAgUiSubmitInterruptResponses()` hook instead. This\n   * method is kept for backward compatibility and will be removed in a future\n   * major release.\n   */\n  unstable_submitInterruptResponses: (\n    responses: readonly AgUiResumeEntry[],\n  ) => Promise<void>;\n};\n\nexport function useAgUiRuntime(\n  options: UseAgUiRuntimeOptions,\n): AgUiAssistantRuntime {\n  const logger = useMemo(() => makeLogger(options.logger), [options.logger]);\n  const [_version, setVersion] = useState(0);\n  const notifyUpdate = useCallback(() => setVersion((v) => v + 1), []);\n  const coreRef = useRef<AgUiThreadRuntimeCore | null>(null);\n  const threadSwitchGenerationRef = useRef(0);\n  const runtimeAdapters = useRuntimeAdapters();\n\n  const historyAdapter = options.adapters?.history ?? runtimeAdapters?.history;\n  const threadListAdapter = options.adapters?.threadList;\n\n  if (!coreRef.current) {\n    coreRef.current = new AgUiThreadRuntimeCore({\n      agent: options.agent,\n      logger,\n      showThinking: options.showThinking ?? true,\n      resumeTranscript: options.resumeTranscript,\n      autoCancelPendingToolCalls: options.autoCancelPendingToolCalls,\n      ...(options.onError && { onError: options.onError }),\n      ...(options.onCancel && { onCancel: options.onCancel }),\n      ...(historyAdapter && { history: historyAdapter }),\n      notifyUpdate,\n    });\n  }\n\n  const core = coreRef.current;\n  useEffect(() => {\n    core.updateOptions({\n      agent: options.agent,\n      logger,\n      showThinking: options.showThinking ?? true,\n      resumeTranscript: options.resumeTranscript,\n      autoCancelPendingToolCalls: options.autoCancelPendingToolCalls,\n      ...(options.onError && { onError: options.onError }),\n      ...(options.onCancel && { onCancel: options.onCancel }),\n      ...(historyAdapter && { history: historyAdapter }),\n    });\n  });\n\n  const [toolStatuses, setToolStatuses] = useState<\n    Record<string, ToolExecutionStatus>\n  >({});\n\n  const hasExecutingTools = Object.values(toolStatuses).some(\n    (s) => s?.type === \"executing\",\n  );\n  const isRunning = core.isRunning() || hasExecutingTools;\n\n  // The driver sends through the agent core rather than the runtime, because\n  // the runtime's append routes every tail append back into this queue.\n  const queueRef = useRef<MessageQueueController | null>(null);\n  // Counts rendered busy edges, whether a run start or an interrupt arriving.\n  // A dispatch whose count never moves was never observed as busy, so no\n  // falling edge is coming to release the queue.\n  const busyEdgesRef = useRef(0);\n  if (options.unstable_enableMessageQueue && !queueRef.current) {\n    queueRef.current = createMessageQueue({\n      run: (message) => {\n        const controller = queueRef.current;\n        const edgesAtDispatch = busyEdgesRef.current;\n        // The queue drops the item before dispatching and stays busy until an\n        // idle edge. An append observed as busy is released by that falling\n        // edge, and releasing again here would advance the queue twice; one\n        // that never runs (a pre-run rejection, or startRun false) has to be\n        // released here or every later send buffers forever. An interrupt is\n        // rechecked because a run that resolves without yielding to React\n        // reaches here before the effect below has seen either edge.\n        const releaseIfNoRun = () => {\n          if (\n            queueRef.current !== controller ||\n            busyEdgesRef.current !== edgesAtDispatch ||\n            core.getPendingInterrupts() !== null\n          )\n            return;\n          controller?.notifyIdle();\n        };\n        void core.append(message).then(releaseIfNoRun, (e: unknown) => {\n          releaseIfNoRun();\n          logger.error?.(\"[agui] queued message failed to send\", e);\n        });\n      },\n    });\n  }\n  const queueController = options.unstable_enableMessageQueue\n    ? queueRef.current\n    : null;\n  useLayoutEffect(() => {\n    if (options.unstable_enableMessageQueue || !queueRef.current) return;\n    const controller = queueRef.current;\n    queueRef.current = null;\n    controller.clear();\n  }, [options.unstable_enableMessageQueue]);\n\n  // Feeds the store memo below: the runtime core skips an adapter whose\n  // identity is unchanged, so queue items have to move the store reference or\n  // subscribers never see composer.queue change.\n  const queueItems = useSyncExternalStore(\n    queueController?.subscribe ?? subscribeNoop,\n    () => queueController?.adapter.items ?? EMPTY_QUEUE_ITEMS,\n    () => EMPTY_QUEUE_ITEMS,\n  );\n  const steerQueueItems = useSyncExternalStore(\n    queueController?.subscribe ?? subscribeNoop,\n    () => queueController?.adapter.steerItems ?? EMPTY_QUEUE_ITEMS,\n    () => EMPTY_QUEUE_ITEMS,\n  );\n\n  // Holds the queue while client-side tools are still executing, and while an\n  // interrupt is unanswered: `append` refuses a new run until it is resolved,\n  // and the queue drops an item before dispatching it, so draining into that\n  // refusal would lose the message instead of keeping it visible.\n  const queueBusy = isRunning || core.getPendingInterrupts() !== null;\n  useEffect(() => {\n    if (queueBusy) {\n      busyEdgesRef.current++;\n      queueController?.notifyBusy();\n    } else {\n      queueController?.notifyIdle();\n    }\n  }, [queueBusy, queueController]);\n\n  const threadList = useMemo(() => {\n    if (!threadListAdapter) return undefined;\n\n    const { onSwitchToNewThread, onSwitchToThread, ...rest } =\n      threadListAdapter;\n\n    return {\n      ...rest,\n      onSwitchToNewThread: onSwitchToNewThread\n        ? async () => {\n            const generation = ++threadSwitchGenerationRef.current;\n            await onSwitchToNewThread();\n            if (generation !== threadSwitchGenerationRef.current) return;\n            core.applyExternalMessages([]);\n            core.resetState();\n          }\n        : undefined,\n      onSwitchToThread: onSwitchToThread\n        ? async (threadId: string) => {\n            const generation = ++threadSwitchGenerationRef.current;\n            // Clear before the thread id flips, or the old messages leak\n            // into the new thread as a sibling branch.\n            core.applyExternalMessages([]);\n            const result = await onSwitchToThread(threadId);\n            if (generation !== threadSwitchGenerationRef.current) return;\n            core.applyExternalMessages(result.messages);\n            if (result.state !== undefined) {\n              core.loadExternalState(result.state);\n            } else {\n              core.resetState();\n            }\n            if (result.unstable_resume) {\n              void core.resumeInFlightRun(result.messages);\n            }\n          }\n        : undefined,\n    };\n  }, [threadListAdapter, core]);\n\n  const adapters = options.adapters;\n  const adapterAdapters = useMemo(\n    () => ({\n      attachments: adapters?.attachments ?? runtimeAdapters?.attachments,\n      speech: adapters?.speech,\n      dictation: adapters?.dictation,\n      voice: adapters?.voice,\n      feedback: adapters?.feedback,\n      threadList,\n    }),\n    [adapters, runtimeAdapters, threadList],\n  );\n\n  const shared = useExternalStoreSharedOptions(options);\n  const store = useMemo(\n    () => {\n      void _version; // rerender on version change\n\n      return {\n        ...shared,\n        isLoading: core.isLoading,\n        messageRepository: core.getMessageRepository(),\n        state: core.getState(),\n        isRunning: core.isRunning(),\n        extras: agUiExtras.provide({\n          interrupts:\n            core.getPendingInterrupts()?.interrupts ?? EMPTY_INTERRUPTS,\n          sendA2uiAction: (action) => core.sendA2uiAction(action),\n          submitInterruptResponses: (responses) =>\n            core.submitInterruptResponses(responses),\n          steerAway: (message, responses) => core.steerAway(message, responses),\n          state: core.getState(),\n          setState: (next) => core.setState(next),\n        }),\n        unstable_enableToolInvocations: true,\n        setToolStatuses,\n        onNew: (message: AppendMessage) => core.append(message),\n        onEdit: (message: AppendMessage) => {\n          queueController?.clear();\n          return core.edit(message);\n        },\n        onReload: (parentId: string | null, config: { runConfig?: any }) => {\n          queueController?.clear();\n          return core.reload(parentId, config);\n        },\n        onCancel: async () => {\n          queueController?.notifyCancelled();\n          core.cancel();\n        },\n        onAddToolResult: (options) => core.addToolResult(options),\n        onRespondToToolApproval: (options) =>\n          core.respondToToolApproval(options).catch((error: unknown) => {\n            core.reportError(error);\n            throw error;\n          }),\n        onResume: (config) => core.resume(config),\n        setMessages: (messages: readonly ThreadMessage[]) =>\n          core.applyExternalMessages(messages),\n        onImport: (messages: readonly ThreadMessage[]) =>\n          core.applyExternalMessages(messages),\n        onLoadExternalState: (state: ReadonlyJSONValue) =>\n          core.loadExternalState(state),\n        adapters: adapterAdapters,\n        ...(queueController && { queue: queueController.adapter }),\n      } satisfies ExternalStoreAdapter<ThreadMessage>;\n    },\n    // _version is intentionally included to trigger re-computation when core state changes via notifyUpdate\n    // toolInvocations intentionally excluded: abort/resume use refs internally and work with stale captures\n    [\n      adapterAdapters,\n      core,\n      _version,\n      isRunning,\n      queueController,\n      queueItems,\n      steerQueueItems,\n      shared,\n    ],\n  );\n\n  const baseRuntime = useExternalStoreRuntime(store);\n\n  const runtime = useMemo<AgUiAssistantRuntime>(() => {\n    const wrapper = Object.create(baseRuntime) as AgUiAssistantRuntime;\n    wrapper.unstable_getPendingInterrupts = () =>\n      core.getPendingInterrupts()?.interrupts ?? [];\n    wrapper.unstable_submitInterruptResponses = (responses) =>\n      core.submitInterruptResponses(responses);\n    return wrapper;\n  }, [baseRuntime, core]);\n\n  useEffect(() => {\n    core.attachRuntime(runtime);\n    return () => {\n      core.detachRuntime();\n    };\n  }, [core, runtime]);\n\n  useEffect(() => {\n    core.__internal_load();\n  }, [core]);\n\n  return runtime;\n}\n"],"mappings":"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"}
+{"version":3,"file":"useAgUiRuntime.js","names":[],"sources":["../src/useAgUiRuntime.ts"],"sourcesContent":["\"use client\";\n\nimport {\n  useCallback,\n  useEffect,\n  useLayoutEffect,\n  useMemo,\n  useRef,\n  useState,\n  useSyncExternalStore,\n} from \"react\";\nimport {\n  useExternalStoreRuntime,\n  useExternalStoreSharedOptions,\n  useRuntimeAdapters,\n} from \"@assistant-ui/core/react\";\nimport { createMessageQueue } from \"@assistant-ui/core\";\nimport type {\n  MessageQueueController,\n  ToolExecutionStatus,\n} from \"@assistant-ui/core\";\nimport type {\n  AssistantRuntime,\n  AppendMessage,\n  ExternalStoreAdapter,\n  ThreadMessage,\n} from \"@assistant-ui/core\";\nimport type { ReadonlyJSONValue } from \"assistant-stream/utils\";\nimport { makeLogger } from \"./runtime/logger\";\nimport type {\n  AgUiInterrupt,\n  AgUiResumeEntry,\n  UseAgUiRuntimeOptions,\n} from \"./runtime/types\";\nimport { AgUiThreadRuntimeCore } from \"./runtime/AgUiThreadRuntimeCore\";\nimport { agUiExtras } from \"./agUiExtras\";\nimport type { QueueItemState } from \"@assistant-ui/core/store\";\n\nconst EMPTY_INTERRUPTS: readonly AgUiInterrupt[] = [];\nconst EMPTY_QUEUE_ITEMS: readonly QueueItemState[] = Object.freeze([]);\nconst subscribeNoop = () => () => {};\n\nexport type AgUiAssistantRuntime = AssistantRuntime & {\n  /**\n   * @deprecated Use the `useAgUiInterrupts()` hook instead. This method is kept\n   * for backward compatibility and will be removed in a future major release.\n   */\n  unstable_getPendingInterrupts: () => readonly AgUiInterrupt[];\n  /**\n   * @deprecated Use the `useAgUiSubmitInterruptResponses()` hook instead. This\n   * method is kept for backward compatibility and will be removed in a future\n   * major release.\n   */\n  unstable_submitInterruptResponses: (\n    responses: readonly AgUiResumeEntry[],\n  ) => Promise<void>;\n};\n\nexport function useAgUiRuntime(\n  options: UseAgUiRuntimeOptions,\n): AgUiAssistantRuntime {\n  const logger = useMemo(() => makeLogger(options.logger), [options.logger]);\n  const [_version, setVersion] = useState(0);\n  const notifyUpdate = useCallback(() => setVersion((v) => v + 1), []);\n  const coreRef = useRef<AgUiThreadRuntimeCore | null>(null);\n  const threadSwitchGenerationRef = useRef(0);\n  const runtimeAdapters = useRuntimeAdapters();\n\n  const historyAdapter = options.adapters?.history ?? runtimeAdapters?.history;\n  const threadListAdapter = options.adapters?.threadList;\n\n  if (!coreRef.current) {\n    coreRef.current = new AgUiThreadRuntimeCore({\n      agent: options.agent,\n      logger,\n      showThinking: options.showThinking ?? true,\n      resumeTranscript: options.resumeTranscript,\n      autoCancelPendingToolCalls: options.autoCancelPendingToolCalls,\n      ...(options.onError && { onError: options.onError }),\n      ...(options.onCancel && { onCancel: options.onCancel }),\n      ...(historyAdapter && { history: historyAdapter }),\n      notifyUpdate,\n    });\n  }\n\n  const core = coreRef.current;\n  useEffect(() => {\n    core.updateOptions({\n      agent: options.agent,\n      logger,\n      showThinking: options.showThinking ?? true,\n      resumeTranscript: options.resumeTranscript,\n      autoCancelPendingToolCalls: options.autoCancelPendingToolCalls,\n      ...(options.onError && { onError: options.onError }),\n      ...(options.onCancel && { onCancel: options.onCancel }),\n      ...(historyAdapter && { history: historyAdapter }),\n    });\n  });\n\n  const [toolStatuses, setToolStatuses] = useState<\n    Record<string, ToolExecutionStatus>\n  >({});\n\n  const hasExecutingTools = Object.values(toolStatuses).some(\n    (s) => s?.type === \"executing\",\n  );\n  const isRunning = core.isRunning() || hasExecutingTools;\n\n  // The driver sends through the agent core rather than the runtime, because\n  // the runtime's append routes every tail append back into this queue.\n  const queueRef = useRef<MessageQueueController | null>(null);\n  // Counts rendered busy edges, whether a run start or an interrupt arriving.\n  // A dispatch whose count never moves was never observed as busy, so no\n  // falling edge is coming to release the queue.\n  const busyEdgesRef = useRef(0);\n  if (options.unstable_enableMessageQueue && !queueRef.current) {\n    queueRef.current = createMessageQueue({\n      run: (message) => {\n        const controller = queueRef.current;\n        const edgesAtDispatch = busyEdgesRef.current;\n        // The queue drops the item before dispatching and stays busy until an\n        // idle edge. An append observed as busy is released by that falling\n        // edge, and releasing again here would advance the queue twice; one\n        // that never runs (a pre-run rejection, or startRun false) has to be\n        // released here or every later send buffers forever. An interrupt is\n        // rechecked because a run that resolves without yielding to React\n        // reaches here before the effect below has seen either edge.\n        const releaseIfNoRun = () => {\n          if (\n            queueRef.current !== controller ||\n            busyEdgesRef.current !== edgesAtDispatch ||\n            core.getPendingInterrupts() !== null\n          )\n            return;\n          controller?.notifyIdle();\n        };\n        void core.append(message).then(releaseIfNoRun, (e: unknown) => {\n          releaseIfNoRun();\n          logger.error?.(\"[agui] queued message failed to send\", e);\n        });\n      },\n    });\n  }\n  const queueController = options.unstable_enableMessageQueue\n    ? queueRef.current\n    : null;\n  useLayoutEffect(() => {\n    if (options.unstable_enableMessageQueue || !queueRef.current) return;\n    const controller = queueRef.current;\n    queueRef.current = null;\n    controller.clear();\n  }, [options.unstable_enableMessageQueue]);\n\n  // Feeds the store memo below: the runtime core skips an adapter whose\n  // identity is unchanged, so queue items have to move the store reference or\n  // subscribers never see composer.queue change.\n  const queueItems = useSyncExternalStore(\n    queueController?.subscribe ?? subscribeNoop,\n    () => queueController?.adapter.items ?? EMPTY_QUEUE_ITEMS,\n    () => EMPTY_QUEUE_ITEMS,\n  );\n  const steerQueueItems = useSyncExternalStore(\n    queueController?.subscribe ?? subscribeNoop,\n    () => queueController?.adapter.steerItems ?? EMPTY_QUEUE_ITEMS,\n    () => EMPTY_QUEUE_ITEMS,\n  );\n\n  // Holds the queue while client-side tools are still executing, and while an\n  // interrupt is unanswered: `append` refuses a new run until it is resolved,\n  // and the queue drops an item before dispatching it, so draining into that\n  // refusal would lose the message instead of keeping it visible.\n  const queueBusy = isRunning || core.getPendingInterrupts() !== null;\n  useEffect(() => {\n    if (queueBusy) {\n      busyEdgesRef.current++;\n      queueController?.notifyBusy();\n    } else {\n      queueController?.notifyIdle();\n    }\n  }, [queueBusy, queueController]);\n\n  const threadList = useMemo(() => {\n    if (!threadListAdapter) return undefined;\n\n    const { onSwitchToNewThread, onSwitchToThread, ...rest } =\n      threadListAdapter;\n\n    return {\n      ...rest,\n      onSwitchToNewThread: onSwitchToNewThread\n        ? async () => {\n            const generation = ++threadSwitchGenerationRef.current;\n            // Clear before the thread id flips, or the old messages leak\n            // into the new thread as a sibling branch.\n            core.applyExternalMessages([]);\n            core.resetThreadState();\n            await onSwitchToNewThread();\n            if (generation !== threadSwitchGenerationRef.current) return;\n            core.applyExternalMessages([]);\n            core.resetThreadState();\n          }\n        : undefined,\n      onSwitchToThread: onSwitchToThread\n        ? async (threadId: string) => {\n            const generation = ++threadSwitchGenerationRef.current;\n            // Clear before the thread id flips, or the old messages leak\n            // into the new thread as a sibling branch.\n            core.applyExternalMessages([]);\n            core.resetThreadState();\n            const result = await onSwitchToThread(threadId);\n            if (generation !== threadSwitchGenerationRef.current) return;\n            core.applyExternalMessages([]);\n            core.resetThreadState();\n            core.applyExternalMessages(result.messages);\n            if (result.state !== undefined) {\n              core.loadExternalState(result.state);\n            }\n            if (result.unstable_resume) {\n              void core.resumeInFlightRun(result.messages);\n            }\n          }\n        : undefined,\n    };\n  }, [threadListAdapter, core]);\n\n  const adapters = options.adapters;\n  const adapterAdapters = useMemo(\n    () => ({\n      attachments: adapters?.attachments ?? runtimeAdapters?.attachments,\n      speech: adapters?.speech,\n      dictation: adapters?.dictation,\n      voice: adapters?.voice,\n      feedback: adapters?.feedback,\n      threadList,\n    }),\n    [adapters, runtimeAdapters, threadList],\n  );\n\n  const shared = useExternalStoreSharedOptions(options);\n  const store = useMemo(\n    () => {\n      void _version; // rerender on version change\n\n      return {\n        ...shared,\n        isLoading: core.isLoading,\n        messageRepository: core.getMessageRepository(),\n        state: core.getState(),\n        isRunning: core.isRunning(),\n        extras: agUiExtras.provide({\n          interrupts:\n            core.getPendingInterrupts()?.interrupts ?? EMPTY_INTERRUPTS,\n          sendA2uiAction: (action) => core.sendA2uiAction(action),\n          submitInterruptResponses: (responses) =>\n            core.submitInterruptResponses(responses),\n          steerAway: (message, responses) => core.steerAway(message, responses),\n          state: core.getState(),\n          setState: (next) => core.setState(next),\n        }),\n        unstable_enableToolInvocations: true,\n        unstable_persistsHistory: true,\n        setToolStatuses,\n        onNew: (message: AppendMessage) => core.append(message),\n        onVoiceTranscript: (message) => core.appendVoiceTranscript(message),\n        onEdit: (message: AppendMessage) => {\n          queueController?.clear();\n          return core.edit(message);\n        },\n        onReload: (parentId: string | null, config: { runConfig?: any }) => {\n          queueController?.clear();\n          return core.reload(parentId, config);\n        },\n        onCancel: async () => {\n          queueController?.notifyCancelled();\n          core.cancel();\n        },\n        onAddToolResult: (options) => core.addToolResult(options),\n        unstable_onRecordToolInteraction: (options) =>\n          core.recordToolInteraction(options),\n        onRespondToToolApproval: (options) =>\n          core.respondToToolApproval(options).catch((error: unknown) => {\n            core.reportError(error);\n            throw error;\n          }),\n        onResume: (config) => core.resume(config),\n        setMessages: (messages: readonly ThreadMessage[]) =>\n          core.applyExternalMessages(messages),\n        onImport: (messages: readonly ThreadMessage[]) =>\n          core.applyExternalMessages(messages),\n        onLoadExternalState: (state: ReadonlyJSONValue) =>\n          core.loadExternalState(state),\n        adapters: adapterAdapters,\n        ...(queueController && { queue: queueController.adapter }),\n      } satisfies ExternalStoreAdapter<ThreadMessage>;\n    },\n    // _version is intentionally included to trigger re-computation when core state changes via notifyUpdate\n    // toolInvocations intentionally excluded: abort/resume use refs internally and work with stale captures\n    [\n      adapterAdapters,\n      core,\n      _version,\n      isRunning,\n      queueController,\n      queueItems,\n      steerQueueItems,\n      shared,\n    ],\n  );\n\n  const baseRuntime = useExternalStoreRuntime(store);\n\n  const runtime = useMemo<AgUiAssistantRuntime>(() => {\n    const wrapper = Object.create(baseRuntime) as AgUiAssistantRuntime;\n    wrapper.unstable_getPendingInterrupts = () =>\n      core.getPendingInterrupts()?.interrupts ?? [];\n    wrapper.unstable_submitInterruptResponses = (responses) =>\n      core.submitInterruptResponses(responses);\n    return wrapper;\n  }, [baseRuntime, core]);\n\n  useEffect(() => {\n    core.attachRuntime(runtime);\n    return () => {\n      core.detachRuntime();\n    };\n  }, [core, runtime]);\n\n  useEffect(() => {\n    core.__internal_load();\n  }, [core]);\n\n  return runtime;\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/react-ag-ui",
-  "version": "0.0.59",
+  "version": "0.0.61",
   "description": "AG-UI protocol adapter for assistant-ui",
   "keywords": [
     "ag-ui",
@@ -30,10 +30,10 @@
   "sideEffects": false,
   "dependencies": {
     "@ag-ui/client": "^0.0.59",
-    "@assistant-ui/core": "^0.3.18",
-    "@assistant-ui/react-generative-ui": "^0.0.18",
-    "@assistant-ui/store": "^0.3.13",
-    "assistant-stream": "^0.3.42",
+    "@assistant-ui/core": "^0.3.21",
+    "@assistant-ui/react-generative-ui": "^0.0.20",
+    "@assistant-ui/store": "^0.3.15",
+    "assistant-stream": "^0.3.45",
     "fast-json-patch": "^3.1.1"
   },
   "peerDependencies": {
@@ -46,14 +46,14 @@
     }
   },
   "devDependencies": {
-    "@assistant-ui/x-buildutils": "0.0.26",
-    "@testing-library/dom": "^10.4.1",
+    "@assistant-ui/x-buildutils": "0.0.29",
+    "@testing-library/dom": "^10.4.2",
     "@testing-library/react": "^16.3.3",
-    "@types/react": "^19.2.18",
+    "@types/react": "^19.3.0",
     "jsdom": "^30.0.1",
-    "react": "^19.2.8",
-    "vitest": "^4.1.11",
-    "zod": "^4.5.4"
+    "react": "^19.3.0",
+    "vitest": "^5.0.1",
+    "zod": "^4.6.5"
   },
   "publishConfig": {
     "access": "public",
@@ -71,6 +71,7 @@
   "scripts": {
     "build": "aui-build",
     "test": "vitest run",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
     "test:watch": "vitest"
   }
 }

package/src/runtime/AgUiThreadRuntimeCore.ts

@@ -19,8 +19,10 @@ import type {
   ThreadHistoryAdapter,
   ThreadMessage,
   ToolCallMessagePart,
+  Unstable_ToolInteraction,
 } from "@assistant-ui/core";
 import {
+  appendToolInteraction,
   createMessageRepositorySession,
   invokeUserCallback,
   iterateToolCallParts,
@@ -329,6 +331,14 @@ export class AgUiThreadRuntimeCore {
     await this.startRun(threadMessageId, message.runConfig);
   }
 
+  appendVoiceTranscript(message: ThreadMessage): void {
+    const parentId = this.session.headId;
+    this.session.addOrUpdateMessage(parentId, message);
+    this.session.switchToBranch(message.id);
+    this.notifyUpdate();
+    this.recordHistoryEntry(parentId, message);
+  }
+
   private maybeAutoCancelPendingToolCalls(): void {
     if (this.autoCancelPendingToolCalls === false) return;
     const pending = this.getPendingToolCalls();
@@ -871,11 +881,17 @@ export class AgUiThreadRuntimeCore {
       const { content } = mapToolCallPartsDeep(assistant.content, (part) => {
         if (part.toolCallId !== options.toolCallId) return part;
         matchedToolCall = true;
+        // artifact and modelContent are optional; only override when supplied
+        // so a later result that omits them keeps a stored value, and
+        // emitToolResult can forward the model-facing content to the agent.
         return {
           ...part,
           result: options.result,
-          artifact: options.artifact,
           isError: options.isError,
+          ...(options.artifact !== undefined && { artifact: options.artifact }),
+          ...(options.modelContent !== undefined && {
+            modelContent: options.modelContent,
+          }),
         };
       });
       if (!matchedToolCall) return message;
@@ -887,6 +903,67 @@ export class AgUiThreadRuntimeCore {
     this.maybeResumeAfterToolResults(sessionMessageId);
   }
 
+  async recordToolInteraction(options: {
+    messageId: string;
+    toolCallId: string;
+    interaction: Unstable_ToolInteraction;
+  }): Promise<void> {
+    const sessionMessageId = this.session.tryGetMessage(options.messageId)
+      ? options.messageId
+      : this.findMessageIdForToolCall(options.toolCallId);
+    if (sessionMessageId === undefined) {
+      throw new Error(
+        `[agui] recordToolInteraction: message "${options.messageId}" was not found`,
+      );
+    }
+
+    const item = this.session.tryGetMessage(sessionMessageId);
+    if (!item) {
+      throw new Error(
+        `[agui] recordToolInteraction: message "${sessionMessageId}" was not found`,
+      );
+    }
+
+    let recorded = false;
+    const updated = this.session.updateMessage(sessionMessageId, (message) => {
+      if (message.role !== "assistant") return message;
+      const assistant = message as ThreadAssistantMessage;
+      const { content } = mapToolCallPartsDeep(assistant.content, (part) => {
+        if (part.toolCallId !== options.toolCallId) return part;
+        recorded = true;
+        return {
+          ...part,
+          unstable_interactions: appendToolInteraction(
+            part.unstable_interactions,
+            options.interaction,
+          ),
+        };
+      });
+      return recorded ? { ...assistant, content } : assistant;
+    });
+    if (!recorded || !updated) {
+      throw new Error(
+        `[agui] recordToolInteraction: tool call "${options.toolCallId}" was not found on message "${options.messageId}"`,
+      );
+    }
+
+    this.notifyUpdate();
+
+    const message = this.session.tryGetMessage(sessionMessageId)?.message;
+    const history = this.history;
+    if (
+      !message ||
+      !history?.update ||
+      !this.isPersistableStatus(message.status)
+    ) {
+      return;
+    }
+
+    await this.chainHistoryWrite(sessionMessageId, () =>
+      history.update!({ parentId: item.parentId, message }),
+    );
+  }
+
   sendA2uiAction(action: Record<string, unknown>): void {
     this.assertNoPendingInterrupts();
     this.maybeAutoCancelPendingToolCalls();
@@ -973,6 +1050,17 @@ export class AgUiThreadRuntimeCore {
   }
 
   applyExternalMessages(messages: readonly ThreadMessage[]): void {
+    messages = messages.map((message) => {
+      if (message.role === "system" || message.metadata.modality !== undefined)
+        return message;
+      const modality = this.session.tryGetMessage(message.id)?.message.metadata
+        .modality;
+      if (modality === undefined) return message;
+      return {
+        ...message,
+        metadata: { ...message.metadata, modality },
+      } as ThreadMessage;
+    });
     this.pendingA2uiResumeOwner = null;
     this.pendingA2uiAction = undefined;
     this.assistantHistoryParents.clear();
@@ -1053,6 +1141,31 @@ export class AgUiThreadRuntimeCore {
     this.notifyUpdate();
   }
 
+  resetThreadState(): void {
+    const controller = this.abortController;
+    const activeRunAgent = this.activeRunAgent;
+
+    this.stateSnapshot = undefined;
+    this.pendingResume = null;
+    this.pendingA2uiResumeOwner = null;
+    this.pendingA2uiAction = undefined;
+
+    if (controller) {
+      this.abortController = null;
+      this.activeRunAgent = null;
+      this.setRunning(false);
+      try {
+        (activeRunAgent ?? this.agent).abortRun();
+      } catch (error) {
+        this.logger.error?.("[agui] agent abortRun failed", error);
+      } finally {
+        controller.abort();
+      }
+    } else {
+      this.notifyUpdate();
+    }
+  }
+
   private async startRun(
     parentId: string | null,
     runConfig?: RunConfig,
@@ -1171,6 +1284,8 @@ export class AgUiThreadRuntimeCore {
       }
     };
 
+    const abortController = new AbortController();
+    const abortSignal = abortController.signal;
     const aggregator = new RunAggregator({
       showThinking: this.showThinking,
       logger: this.logger,
@@ -1180,11 +1295,18 @@ export class AgUiThreadRuntimeCore {
       },
       onTextMessageStart: (serverId) => adoptServerMessageId(serverId, true),
     });
-    const dispatch = (event: AgUiEvent) =>
-      this.handleEvent(aggregator, event, assistantMessageId);
+    const dispatch = (event: AgUiEvent) => {
+      if (this.abortController !== abortController) return;
+      const nextAssistantMessageId = this.handleEvent(
+        aggregator,
+        event,
+        assistantMessageId,
+      );
+      if (event.type === "MESSAGES_SNAPSHOT") {
+        assistantMessageId = nextAssistantMessageId;
+      }
+    };
 
-    const abortController = new AbortController();
-    const abortSignal = abortController.signal;
     this.abortController = abortController;
     const runAgentInstance = this.agent;
     this.activeRunAgent = runAgentInstance;
@@ -1585,26 +1707,57 @@ export class AgUiThreadRuntimeCore {
     previous: ThreadAssistantMessage["content"],
     next: ThreadAssistantMessage["content"],
   ): ThreadAssistantMessage["content"] {
-    const resolved = new Map<string, ToolCallMessagePart>();
+    const preserved = new Map<string, ToolCallMessagePart>();
     for (const part of iterateToolCallParts(previous)) {
       if (isResolvedToolCall(part)) {
-        resolved.set(part.toolCallId, part);
+        preserved.set(part.toolCallId, part);
       }
     }
-    if (resolved.size === 0) return next;
+    if (preserved.size === 0) {
+      return this.preserveToolInteractions(previous, next);
+    }
 
     const { content: merged, changed } = mapToolCallPartsDeep(next, (part) => {
-      if (isResolvedToolCall(part)) return part;
-      const prior = resolved.get(part.toolCallId);
+      const prior = preserved.get(part.toolCallId);
       if (!prior) return part;
-      return {
-        ...part,
-        result: prior.result,
-        ...(prior.artifact !== undefined ? { artifact: prior.artifact } : {}),
-        ...(prior.isError !== undefined ? { isError: prior.isError } : {}),
-      };
+      if (!isResolvedToolCall(part) && isResolvedToolCall(prior)) {
+        return {
+          ...part,
+          result: prior.result,
+          ...(prior.artifact !== undefined ? { artifact: prior.artifact } : {}),
+          ...(prior.isError !== undefined ? { isError: prior.isError } : {}),
+          ...(prior.modelContent !== undefined
+            ? { modelContent: prior.modelContent }
+            : {}),
+        };
+      }
+      return part;
+    });
+    return this.preserveToolInteractions(previous, changed ? merged : next);
+  }
+
+  private preserveToolInteractions(
+    previous: ThreadAssistantMessage["content"],
+    next: ThreadAssistantMessage["content"],
+  ): ThreadAssistantMessage["content"] {
+    const interactions = new Map<
+      string,
+      NonNullable<ToolCallMessagePart["unstable_interactions"]>
+    >();
+    for (const part of iterateToolCallParts(previous)) {
+      if (part.unstable_interactions !== undefined) {
+        interactions.set(part.toolCallId, part.unstable_interactions);
+      }
+    }
+    if (interactions.size === 0) return next;
+
+    const { content, changed } = mapToolCallPartsDeep(next, (part) => {
+      const interaction = interactions.get(part.toolCallId);
+      if (interaction === undefined || part.unstable_interactions !== undefined)
+        return part;
+      return { ...part, unstable_interactions: interaction };
     });
-    return changed ? merged : next;
+    return changed ? content : next;
   }
 
   private mergeAssistantMetadata(
@@ -1640,15 +1793,15 @@ export class AgUiThreadRuntimeCore {
     aggregator: RunAggregator,
     event: AgUiEvent,
     activeAssistantId: string | undefined,
-  ) {
+  ): string | undefined {
     switch (event.type) {
       case "STATE_SNAPSHOT": {
         this.stateSnapshot = event.snapshot as ReadonlyJSONValue;
-        this.notifyUpdate();
-        return;
+        this.updateActiveAssistantState(activeAssistantId);
+        break;
       }
       case "STATE_DELTA": {
-        if (event.delta.length === 0) return;
+        if (event.delta.length === 0) break;
         try {
           const state = this.stateSnapshot ?? {};
           const result = jsonpatch.applyPatch(
@@ -1658,26 +1811,44 @@ export class AgUiThreadRuntimeCore {
             /* mutateDocument */ false,
           );
           this.stateSnapshot = result.newDocument as ReadonlyJSONValue;
-          this.notifyUpdate();
+          this.updateActiveAssistantState(activeAssistantId);
         } catch (error) {
           this.logger.error?.("[agui] failed to apply state delta", error);
         }
-        return;
+        break;
       }
       case "MESSAGES_SNAPSHOT": {
+        const previousHeadId = this.session.headId;
+        const activeAssistant =
+          activeAssistantId === undefined
+            ? undefined
+            : this.session.tryGetMessage(activeAssistantId)?.message;
+        const hasActiveText =
+          activeAssistant?.role === "assistant" &&
+          activeAssistant.content.some((part) => part.type === "text");
         this.importMessagesSnapshot(event.messages, activeAssistantId);
-        return;
+        const headId = this.session.headId;
+        if (hasActiveText && headId !== previousHeadId) {
+          const head =
+            headId === null
+              ? undefined
+              : this.session.tryGetMessage(headId)?.message;
+          activeAssistantId =
+            head?.role === "assistant" ? (headId ?? undefined) : undefined;
+        }
+        this.updateActiveAssistantState(activeAssistantId);
+        break;
       }
       case "TOOL_CALL_RESULT": {
         if (!aggregator.hasToolCall(event.toolCallId)) {
           const messageId = this.findMessageIdForToolCall(event.toolCallId);
           if (messageId !== undefined) {
             this.applyCrossRunToolResult(messageId, event);
-            return;
+            break;
           }
         }
         aggregator.handle(event);
-        return;
+        break;
       }
       case "ACTIVITY_SNAPSHOT": {
         const toolCallId = event.content["toolCallId"];
@@ -1689,15 +1860,41 @@ export class AgUiThreadRuntimeCore {
           const messageId = this.findMessageIdForToolCall(toolCallId);
           if (messageId !== undefined) {
             this.applyCrossRunActivitySnapshot(messageId, toolCallId, event);
-            return;
+            break;
           }
         }
         aggregator.handle(event);
-        return;
+        break;
       }
       default:
         aggregator.handle(event);
     }
+    return activeAssistantId;
+  }
+
+  private updateActiveAssistantState(messageId: string | undefined): void {
+    const current =
+      messageId === undefined
+        ? undefined
+        : this.session.tryGetMessage(messageId)?.message;
+    const activeAssistantId =
+      current?.role === "assistant" && this.session.headId === messageId
+        ? messageId
+        : this.session.headId;
+    if (activeAssistantId !== null && activeAssistantId !== undefined) {
+      this.session.updateMessage(activeAssistantId, (message) => {
+        if (message.role !== "assistant") return message;
+        const assistant = message as ThreadAssistantMessage;
+        return {
+          ...assistant,
+          metadata: {
+            ...assistant.metadata,
+            unstable_state: this.stateSnapshot ?? null,
+          },
+        };
+      });
+    }
+    this.notifyUpdate();
   }
 
   private applyCrossRunToolResult(
@@ -1851,9 +2048,28 @@ export class AgUiThreadRuntimeCore {
       const converted: ThreadMessage[] = [];
       for (const message of normalized) {
         try {
-          converted.push(
-            fromThreadMessageLike(message, generateId(), FALLBACK_USER_STATUS),
+          const convertedMessage = fromThreadMessageLike(
+            message,
+            generateId(),
+            FALLBACK_USER_STATUS,
           );
+          const existing = this.session.tryGetMessage(
+            convertedMessage.id,
+          )?.message;
+          if (
+            convertedMessage.role === "assistant" &&
+            existing?.role === "assistant"
+          ) {
+            converted.push({
+              ...convertedMessage,
+              content: this.preserveToolInteractions(
+                existing.content,
+                convertedMessage.content,
+              ),
+            });
+          } else {
+            converted.push(convertedMessage);
+          }
         } catch (error) {
           this.logger.error?.(
             "[agui] failed to import message from snapshot",

package/src/runtime/adapter/conversions.content.test.ts

@@ -276,3 +276,59 @@ describe("toAgUiMessages content metadata", () => {
     expect(toAgUiMessages(rebuilt as never)).toEqual(sent);
   });
 });
+
+describe("toAgUiMessages percent-encoded data URLs", () => {
+  it("sends a data URL that is not base64 as a url source", () => {
+    expect(
+      contentOf(
+        userMessage([
+          { type: "image", image: "data:image/svg+xml,%3Csvg%2F%3E" },
+          {
+            type: "file",
+            data: "data:text/plain,hello",
+            mimeType: "text/plain",
+            filename: "f.txt",
+          },
+        ]),
+      ),
+    ).toEqual([
+      {
+        type: "image",
+        source: { type: "url", value: "data:image/svg+xml,%3Csvg%2F%3E" },
+      },
+      {
+        type: "document",
+        source: {
+          type: "url",
+          value: "data:text/plain,hello",
+          mimeType: "text/plain",
+        },
+        metadata: { filename: "f.txt" },
+      },
+    ]);
+  });
+
+  it("keeps a data URL that is not base64 through a snapshot round trip", () => {
+    const sent = toAgUiMessages([
+      userMessage([
+        {
+          type: "file",
+          data: "data:text/plain,hello",
+          mimeType: "text/plain",
+          filename: "f.txt",
+        },
+      ]),
+    ]);
+
+    const rebuilt = fromAgUiMessages(sent as never);
+    const attachment = (rebuilt[0] as unknown as { attachments: unknown[] })
+      .attachments[0] as { content: unknown[] };
+
+    expect(attachment.content[0]).toMatchObject({
+      type: "file",
+      data: "data:text/plain,hello",
+      mimeType: "text/plain",
+    });
+    expect(toAgUiMessages(rebuilt as never)).toEqual(sent);
+  });
+});