External Store Runtime

The runtime writes its messages to the thread list's history adapter itself, so `useExternalStoreRuntime` does not copy them.

Whether the entire thread is disabled. When `true`, the composer input cannot be typed into, attachments cannot be added, sends (including direct `composer.send()` calls) are blocked, and messages cannot be edited. For a narrower gate that keeps the input usable but blocks only sending, use `isSendDisabled`.

Whether sending new messages is currently disabled. When `true`, the thread composer's input remains usable but `send()` becomes a no-op and the thread composer's `canSend` is `false`. Use this to gate sending on external React state (e.g. while tool config is loading) without disabling the input itself the way `isDisabled` does. Edit composers (saving message edits) intentionally ignore this flag.

Whether the thread is running. When provided, this value flows directly to `thread.isRunning`, letting the application keep the thread in a running state even after the last assistant message has completed (for example while non-message stream chunks like suggestions or metadata updates are still arriving). When omitted, `thread.isRunning` falls back to the last-message-status heuristic.

Opt in only while an interrupted run has a resumable checkpoint. Requires onResume; do not set this for cancellation that permanently ends a run. Resuming must preserve the existing message and tool execution state.

The current run's id, kept through `cancelRun` so its late calls can be discarded.

Whether messages exist before the first one in `messages`, for a host that opens a long thread on its latest page. Only takes effect together with `onLoadEarlier`.

Loads the page before the first message; the host prepends it to `messages` (stable message ids keep rendered rows and scroll position in place). The runtime runs one call at a time, reports `thread.isLoadingEarlier` until the returned promise settles, and logs a rejection instead of passing it to the caller.

An externally owned message repository instance. When provided, the thread runtime adopts it as its branch store and swaps to it atomically whenever a different instance is passed, so hosts that route multiple conversations through one runtime keep each conversation's history and branches isolated in its own instance. Omit it to keep the runtime's own repository. When `unstable_enableToolInvocations` is true, frontend tool executions belong to the instance as well: a runtime mounted with an instance whose tools are still executing takes them over, so it reports them as running, stops them on cancel, and resumes their human input requests.

Applies a message list the runtime rewrote, and is what tells the runtime a removal it makes will survive the next snapshot. Without it, cancelling a run leaves a trailing user message in the thread and the composer untouched; an adapter that removes that message itself owns handing it back, because the runtime cannot see a removal it did not make.

Called with each message a voice session adds to the thread: every finalized transcript, and every text message typed into a session that takes typed text (it carries no `metadata.modality`). The host appends it to its own messages under the same id, which is how the runtime knows the host carries it. A message that finalizes while `isLoading` is true is delivered once loading ends, to the callback on the adapter current at that moment, and is not delivered at all when the conversation changed while it waited. A host that routes conversations through one runtime is recognized by its `unstable_messageRepositoryInstance`; one that swaps only its `messages` cannot be told apart from a load finishing. A host that does not implement this callback keeps these messages for the session only.

Fires when the user explicitly switches branches via the runtime's `switchToBranch` action (e.g. a BranchPicker click). It does not fire on adapter resync, `append`, edit/regenerate, content-only updates, or while the thread is running. Consecutive switches that resolve to the same canonical head are de-duped. `headId` is the canonical (persisted) head of the now-visible branch — optimistic/transient ids are never surfaced. `visibleMessageIds` lists the visible path in order. This complements `setMessages` rather than replacing it: switching still requires `setMessages`, and this callback does not on its own enable branch switching.

Opt in to message queuing. Typically produced by `createMessageQueue`.

Removes a message from the host's store. The runtime drops the message from its branches when `messages` stops carrying the id, and reads a `messages` update that still carries it after every call for it has settled as a declined delete. A host that accepts the delete therefore publishes the removal before the returned promise settles. While a branch switch, `messages` can omit ids on another branch. A reload or edit can omit messages after an earlier reply. For deletes pending across those changes, the runtime waits for the promise: a rejection keeps the message and a resolution drops it.

Re-fetches the thread's state from the backing store, in place; a rejection reaches the `threads.reloadMainThread()` caller. Unrelated to `onReload`, which re-generates an assistant message. The caller does not stop a run in progress first, so an adapter that can stream owns whatever coordination one needs.

Stores a user interaction on a tool call part of a message this store owns and exposes it on that part's `unstable_interactions`. Without it, recording an interaction rejects and nothing is kept.

Opt in to the built-in client-side tool-invocations pipeline (`streamCall` / `execute` / tool-status tracking) for this thread. Defaults to `false` — the runtime does *not* drive client-side tool callbacks on its own. Set to `true` to have the runtime construct a `ToolInvocationTracker` and feed every snapshot through it, so tool callbacks fire automatically for tool-call parts in `messages`. Opt-in by default because most external-store runtimes either run tools entirely server-side, or already wire their own client-side dispatch path. Enabling the embedded tracker on top of an existing dispatch path would cause tool callbacks to run twice. When enabled, client-side tool results (from `execute()` returning, or from `streamCall` resolving) flow back through `adapter.onAddToolResult` like any other tool result, with `modelContent` populated when present.

Decides whether a tool call's result is produced on the client. Only consulted when `unstable_enableToolInvocations` is `true`. A provider that runs tools itself answers its own calls, and its result arrives one or more snapshots after the call's arguments complete. In that window the call is complete and result-less, so a registered tool of the same name would otherwise execute locally and produce a result the provider never asked for. An adapter that can tell the two apart supplies this predicate; it is read once per tool call, when the call is first observed live. The predicate is also what licenses running a frontend tool while the provider's run is still open. Without it, ownership is unknown until the run ends, so a registered tool executes only once the run's outcome is known and cannot fire on a call the provider was about to answer or gate.

Receives the current per-tool-call execution status map whenever it changes. Only invoked when `unstable_enableToolInvocations` is `true` — the runtime maintains the map via the embedded tracker. Wire this into local React state and feed it into the converter's `metadata.toolStatuses` so the UI can render `executing` spinners and human-input prompts.

Whether messages exist before the first one in `messages`; takes effect with `onLoadEarlier`.

Loads the page before the first message, which the host prepends to `messages`; one call runs at a time.

Whether sending new messages is currently disabled. When `true`, the thread composer's input remains usable but `send()` is a no-op and `composer.canSend` is `false`. Edit composers (saving message edits) intentionally ignore this flag.

Callback for new messages (non-queue runtimes).

Resume the existing run from its checkpoint without appending a user message.

True only while a checkpoint is available; requires onResume.

Handler for re-fetching this thread's state in place, driving `threads.reloadMainThread()`. Unrelated to `onReload`, which re-generates an assistant message. Presence enables the `refetchThread` capability; rejections propagate to the caller.

Callback for resuming a tool call that is waiting for human input.

Queue adapter for runtimes that support message queuing and steering.

Branch adapter for runtimes that track sibling variants of messages.

Callback for tool approval decisions. Absent: responding to an approval throws a capability error.

Send a message into the queue lane, processed in order.

Send a message into the steer lane, processed next.

Move a queued message between lanes or within a lane. An unanchored move into the steer lane mid-run interrupts — cancels the live run and dispatches the item — when the runtime supports cancellation; a move with `insertAfter`/`insertBefore` only places the item and never interrupts.