A request with hosted tools can take several seconds. While it runs, ModelRiver sends progress to the same WebSocket channel the final response arrives on, so your frontend can show "Reading this week's sales…" instead of a spinner.
Progress events carry a tool's name, its progress label and how the call ended. They never carry results. The only arguments they carry are, for a call waiting for the end user's approval, the ones the developer chose to show.
With the Client SDK
Client SDK 1.9.0 and later keep the list for you:
1import { useModelRiver } from '@modelriver/client/react';2 3function Assistant() {4 const { toolCalls, toolRound, response, error, hasPendingRequest, cancel } = useModelRiver();5 6 return (7 <div>8 {toolCalls.map((call) => (9 <p key={call.id} className={call.status}>10 {call.label ?? call.name}11 {call.status === 'error' && call.user_message ? `: ${call.user_message}` : null}12 </p>13 ))}14 15 {hasPendingRequest && <button onClick={() => cancel()}>Stop</button>}16 {response?.status === 'success' && <pre>{JSON.stringify(response.data, null, 2)}</pre>}17 {error && <p className="error">{error}</p>}18 </div>19 );20}| Where | Tool calls | Current round | Stop |
|---|---|---|---|
ModelRiverClient | getState().toolCalls, the tool_calls event | getState().toolRound | cancel() |
React useModelRiver | toolCalls | toolRound | cancel() |
Vue useModelRiver | toolCalls (ref) | toolRound (ref) | cancel() |
Angular ModelRiverService | toolCalls$ | toolRound$ | cancel() |
Svelte createModelRiver | toolCalls (store) | toolRound (store) | cancel() |
From 1.10.0, pendingApprovals (pendingApprovals$ in Angular, getState().pendingApprovals and the tool_approvals event on ModelRiverClient) lists the calls waiting for the end user's approval. See Approvals.
Each entry of toolCalls:
| Field | Description |
|---|---|
id | The call's id. Stable across retries and reconnects |
name | The tool's name |
label | The tool's Progress label from the console, or null |
round | The model round the call belongs to, starting at 1 |
status | running, then ok, error or timeout. ended when the request finished before the client saw the call finish. A call to a tool that changes something (1.10.0+) starts as awaiting_approval, then becomes approved (until it starts), rejected or expired, and can end as unknown |
duration_ms | Set once the call has finished |
user_message | A message your endpoint marked as safe to show, if it sent one |
Calls are listed in the order they started. Calls of one round can run at the same time and finish in any order.
Earlier SDK versions ignore these events and still receive the final response.
The events
If you use Phoenix Channels directly, these arrive on ai_response:{project_id}:{channel_id}:
tool_round_started
A model round is starting.
1{ "round": 1, "max_rounds": 5 }tool_call_started
ModelRiver is calling one of your tools.
1{ "id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b", "name": "get_sales_summary", "label": "Reading this week's sales…", "round": 1 }tool_call_completed
The call finished, whatever the outcome.
1{ "id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b", "name": "get_sales_summary", "round": 1, "status": "ok", "duration_ms": 182, "user_message": null }status is ok, error or timeout, or unknown for a call to a tool that changes something whose outcome is not known (it was sent, and is never sent again). A call to a tool that changes something that your endpoint answered with 2xx is ok even when its result could not be read. A call that failed does not fail the request: the model is told, and usually still answers.
tool_approval_required
A call to a tool that changes something waits for the end user's approval. The request pauses once the round's other calls have finished. One event per waiting call:
1{2 "id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b",3 "name": "cancel_order",4 "label": "Cancelling the order…",5 "round": 1,6 "prompt": "Cancel this order? This can't be undone.",7 "arguments": { "order_id": "1041" },8 "expires_at": "2026-11-14T10:20:00Z"9}arguments holds only the arguments ticked under Show to the user ({} when none). Show the prompt and the values as plain text, in full. See Approvals.
tool_approval_resolved
The call was decided, or its wait ran out:
1{ "id": "tc_3f2a9c1d5b7e4a6f8c0d1e2b", "name": "cancel_order", "round": 1, "decision": "approved" }decision is approved, rejected or expired. A call stopped while it waited is rejected. Once every waiting call of the round is decided, approved calls run: tool_call_started and tool_call_completed follow for each one that is sent. A call that is approved but not sent (the request was stopped, or no time was left) gets neither event.
tool_state
Sent once when a client joins a request that is already under way, for example after a page reload: where things stand.
1{2 "round": 2,3 "max_rounds": 5,4 "calls": [5 { "id": "tc_3f2a…", "name": "get_sales_summary", "label": "Reading this week's sales…", "round": 1, "status": "ok", "duration_ms": 182, "user_message": null },6 { "id": "tc_9c1d…", "name": "get_top_products", "label": null, "round": 2, "status": "running" }7 ]8}Take it as where the calls it lists stand now, and drop any call you still show as running or waiting that it doesn't list. Keep calls you already saw finish: each call's progress is kept for ten minutes, so an earlier one can be missing from a later snapshot. The Client SDK (1.10.0+) does this for you. tool_state is sent before any buffered final response, so the screen never goes from "done" back to "working". If no snapshot is available, the client simply gets the events from then on.
While a request waits for approval, calls from earlier rounds are listed from the request's log. Those have label: null and user_message: null, so show the tool's name when a call has no label. A call to a tool the workflow doesn't have is left out, as it is from the live events.
While a request waits for approval, tool_state is sent for the whole wait, from any server and after a restart. A waiting call has status: "awaiting_approval" and also prompt, arguments and expires_at, as in tool_approval_required. A decided call has approved (not started yet), rejected or expired:
1{2 "round": 1,3 "max_rounds": 5,4 "calls": [5 { "id": "tc_3f2a…", "name": "get_order", "label": null, "round": 1, "status": "ok", "duration_ms": 140, "user_message": null },6 { "id": "tc_9c1d…", "name": "cancel_order", "label": "Cancelling the order…", "round": 1, "status": "awaiting_approval", "prompt": "Cancel this order? This can't be undone.", "arguments": { "order_id": "1041" }, "expires_at": "2026-11-14T10:20:00Z" }7 ]8}A model's request for a tool the workflow doesn't have produces no events, because its name is whatever the model wrote.
Stopping a request
To let the user stop a request, push cancel on the channel (the SDK's cancel() does this):
1const stopped = await client.cancel(); // true when ModelRiver took the request to stopWhat happens:
- ModelRiver starts no further model round. A tool call already under way is left to finish.
- The final
responsestill arrives, withstatus: "error"anderror.type: "cancelled". Keep the connection open until it does. A request stopped while it waited for approval sends that response once: if a ModelRiver server fails at that moment it may not arrive, and the request's log still shows the end. - Rounds that already ran are counted. A request stopped before its first round counts nothing.
- A stop sent while the request is still waiting to start is remembered, and the request ends as soon as it starts.
- A stop sent while calls wait for approval ends the request straight away. The waiting calls are declined (
tool_approval_resolvedwithrejected) and never run.
cancel() resolves false when the client isn't joined to a request.
How a request ends
The final response event is the same as for any async request. On success it carries the answer and what the request used:
1{2 "status": "success",3 "data": { "...": "the model's answer, as for any request to this workflow" },4 "meta": { "workflow": "sales_chat", "duration_ms": 2140, "tool_loop": { "rounds": 2, "tool_calls": 2 } }5}When hosted tools end a request early, status is error and error.type says why:
error.type | What happened | error.message, written for the end user |
|---|---|---|
tool_loop_limit | The model was still asking for tools at the round or tool-call limit | "This took too many steps to finish. Try asking a narrower question." |
tool_loop_timeout | The request ran out of its total time | "This took too long to finish. Please try again." |
cancelled | The user stopped it | "The request was cancelled." |
request_limit_exceeded | Your plan's request limit or the project's quota was reached part-way | "This request could not be completed." |
tool_pause_failed | The request couldn't be saved to wait for approval | "This request could not be completed." |
tool_unavailable | Hosted tools were turned off, or the workflow was deleted (or couldn't be loaded) or its tools switched off, while the request waited for approval. Nothing approved was sent | "This request could not be completed." |
tool_resume_failed | The request could not carry on after waiting for approval | "This request could not be completed." |
tool_model_unsupported | None of the workflow's models that the request may use can call tools (see Which models can run tools). It ended before any model was called and counts nothing. A request resuming after approval ends the same way, and nothing approved is sent | "This request could not be completed." |
1{2 "status": "error",3 "message": "This took too many steps to finish. Try asking a narrower question.",4 "error": {5 "type": "tool_loop_limit",6 "message": "This took too many steps to finish. Try asking a narrower question.",7 "details": "The request reached its round limit before the model answered."8 },9 "meta": { "status": "error", "tool_loop": { "rounds": 5, "tool_calls": 9 } }10}error.message is safe to show as it is. error.details is for your logs, and isn't always there: a request that failed unexpectedly has only type and message.
If a provider fails in a later round and no backup model can take over, the request ends with the usual provider error. If a spending limit is reached part-way, the next round is not started and the request ends with the usual budget error. In every case, the rounds that ran are counted.
Next steps
- Client SDK: connect, reconnect and read the response
- Approvals: show the approval and send the decision
- Testing: watch a request round by round in the Timeline