@artooi/ag-ui-web-component 0.42.0 → 0.44.0

package/CHANGELOG.md

@@ -7,6 +7,164 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.44.0] — 2026-10-20
+
+### Fixed
+
+- **`ag-ui-feedback` now says which message was rated.** Its detail carried only
+  the message's text and the rating, so a host could not tell two answers that
+  read the same apart, and could not find a rated message again after a reload.
+  The detail now also carries `messageId`, the AG-UI id of the rated assistant
+  message (the id it streamed under, or the stored message's `id` when it was
+  restored from history, including the turns a Retry keeps); `threadId`, the
+  conversation it belongs to; and `runId`, the run whose `RUN_STARTED` streamed
+  it. `runId` is present only on a message that arrived live: a stored AG-UI
+  message carries no run id, so the key is absent on a restored one rather than
+  guessed; text a sub-agent streams through the parent run carries the
+  parent's `runId`. A restored answer whose store returned no id keeps its Copy
+  but offers no rating pair, since a rating has to name a message. A restored
+  message is named by the id its store returns: the
+  built-in browser store keeps the streamed ids, and with `data-threads-url` or
+  a host's own store a rating made after a reload names the same message as one
+  made live only where the server persists the ids it streamed. Additive: `content` and
+  `rating` are unchanged. **A host has to opt in to use it**: the rating pair is
+  still off unless `data-message-actions` lists `feedback`, and a host already
+  listening reads the new fields from the same event. `AgUiClientHandlers.onTextEnd`
+  gains a second argument, `AgUiMessageIds`, naming the completed message; a
+  handler that ignores it is unaffected, and code that calls a handler table's
+  `onTextEnd` itself has to pass it.
+- **The `data-message-actions` row of the README's attribute table said all
+  three actions are on by default.** Absent means copy and retry; the rating
+  pair has been opt-in since it was found latching with no listener. The row now
+  says so.
+
+## [0.43.0] — 2026-10-10
+
+### Fixed
+
+- **A second click on the mic while its permission prompt is open no longer
+  leaves a recording nothing can stop.** The mic button reads idle for as long
+  as the browser's prompt is up, which is seconds the first time an origin asks
+  and a few milliseconds after that, so a double click or an impatient second
+  click started twice. Both starts recorded and held a live track, but the
+  control kept only the second: one stop click ended that one, the first kept
+  recording with the browser's recording indicator on for a button reading
+  idle, and `dispose()` could not reach it either. The first start's two-minute
+  cap timer was orphaned too, and when it fired it stopped whatever recording
+  was current, so a later, unrelated one was cut short with "Stopped at the
+  2-minute limit". If the second start's recorder then failed, the failure
+  released the second stream and hid the first. The latest click now wins: a
+  start that settles after a newer one began, or after the control was disposed,
+  releases the microphone it was granted and touches nothing the newer start
+  owns, and a refusal on such a start no longer draws an error over the newer
+  one. The button is not blocked while a prompt is open, so a prompt the user
+  dismissed without answering, which a browser may leave pending forever, does
+  not stop the next click from asking again. Nothing for a host to opt into.
+
+- **A send made while a stored conversation loads no longer goes out without
+  it.** Every restore asks the conversation store for the conversation first:
+  on connect, on `reload()`, when a thread is picked from the drawer, and when
+  `user-key` changes from one principal to another. With `data-threads-url`
+  that is a request to the server,
+  and nothing held the composer while it was out unless the restore was about
+  to resume a run. So a send in that time went out carrying only its own turn,
+  and the agent answered without the conversation. Its save replaced the
+  stored conversation with the new exchange, and the replay then drew the
+  stored conversation under the new turn. The client the send built stayed
+  cached without the history, so every later turn on that page went out
+  without it too. A Retry in the window was refused, but it left the same
+  empty client cached, so the first send after the load lost the history the
+  same way. With the built-in store the window is one microtask, so it was
+  reached only by a send in the same task as the insertion: a script right
+  after `append`, a framework ref callback, or a layout effect.
+  Now every restore holds the composer until the conversation is drawn:
+  - A host's `sendMessage()` waits for the restore, then sends with the
+    conversation. Its bubble, its `ag-ui-submit` event and its request all move
+    to after the replay, so they arrive later than the call by the length of
+    the load. A host that listens on `ag-ui-submit` hears it that much later.
+  - If New chat, a thread switch, a change from one `user-key` to another or
+    `reload()` comes while the send waits, the send is dropped and resolves
+    `false` at once, because the conversation it was addressed to is no longer
+    on screen. If the element leaves the page, the send is dropped too, but it
+    resolves `false` only once the load answers or the element is inserted
+    again. A first `user-key` on an anonymous conversation adopts it rather than
+    replacing it, so a send waiting then still goes out. A second
+    `sendMessage()` while one waits is refused.
+  - The built-in Send queues what is typed during the load, showing it as
+    "Waiting to send", and sends it after the conversation is drawn, behind a
+    `sendMessage()` that was waiting.
+  - `retryLastTurn()` resolves `false` during the load, before it builds a
+    client.
+  - A checkpoint pick is refused during the load with a new composer hint,
+    `continueWhileLoading` ("Wait for the conversation to finish loading, then
+    pick a run to continue."). Hosts that translate the UI strings can override
+    it in `data-strings`; until they do, it shows in English. `UiStrings` gains
+    the key. The `strings` property and `data-strings` take a partial table, so
+    only code that builds a complete `UiStrings` object of its own has to add
+    it.
+  - A restore that will resume a run a navigating tool interrupted keeps
+    refusing a host's `sendMessage()`, as in 0.42.0, because that restore ends
+    by starting the run.
+
+  No host opt-in is needed: this applies to every element as soon as it is
+  upgraded. A host that sends on mount gets the conversation without changing
+  anything. The cost is that the composer queues for as long as each load
+  takes, and the load has no timeout of its own, so a request that hangs keeps
+  it queueing until the request fails. A store whose load rejects ends the wait
+  too, and what waited then goes out into the empty conversation the page is left
+  showing, so a custom store that rejects loses its stored copy to that send, as
+  a turn typed after the failure always has. The built-in remote store falls back
+  to its local cache on a failed fetch instead of rejecting.
+
+- **Clearing the conversation while a frontend tool waits no longer leaves a
+  "thinking" indicator in the next one.** A handler cannot be aborted, and a
+  confirmation card that is open when the run stops is declined, so the call
+  resumes after the conversation has been cleared. It then showed the run
+  waiting on its next round in whatever conversation had replaced it: the
+  indicator's answer group hid the greeting and the starter chips, and nothing
+  took it down until the next run there ended. This happened after New chat,
+  picking another thread from the drawer, deleting the active thread,
+  `reload()` and re-inserting the element, each with a handler still running
+  or a confirmation card open. A `user-key` handover already drew nothing there, as of 0.42.0.
+  Now the call draws nothing once the conversation it was dispatched in has
+  been cleared. Everything else it did is unchanged:
+  - Its card still settles as done, failed or declined.
+  - A failed navigating tool still clears its checkpoint from the thread it
+    was written to.
+  - Its result still goes to the run it belonged to, as after a Stop.
+
+  No host opt-in is needed: this applies to every element as soon as it is
+  upgraded, and nothing about the tool registry or its handlers changes.
+
+- **A microphone the browser grants but cannot record no longer fails silently.**
+  With `data-transcribe-url` set, the mic button asks for the microphone and
+  then builds a `MediaRecorder` on the stream. If the browser refuses that, as
+  Chromium does with `NotSupportedError` for a stream whose tracks have already
+  ended, the click ended in an unhandled promise rejection and the button stayed
+  idle with no message. Any track of the stream that was still live kept
+  running, so the browser's recording indicator stayed lit, and starting again
+  replaced the stream without stopping it. Now a recorder that cannot start is
+  treated as a refused microphone: the tracks are released, the button shows
+  "Transcription failed" as it does for a denied permission, and it stays idle,
+  ready to try again. The message reuses that existing string, so `UiStrings` is
+  unchanged.
+
+  No host opt-in is needed: this applies to every element as soon as it is
+  upgraded.
+
+### Changed
+
+- **`sendMessage()` resolves to whether it sent.** It returns
+  `Promise<boolean>` where it returned `Promise<void>`. It resolves `true` once
+  the turn was handed to the agent and the interaction settled, and `false`
+  when nothing was sent: an empty message, a run or a send already in flight, a
+  reload's resume, no `endpoint`, or a send dropped while it waited for a
+  restore. Code that ignores the result behaves as before, but type-checking
+  breaks wherever `sendMessage` is annotated, implemented, overridden or
+  replaced as returning `Promise<void>`: a wrapper's ref type declaring it, a
+  subclass override, and a test double that replaces it on the element all have
+  to return a boolean to type-check.
+
 ## [0.42.0] — 2026-10-07
 
 ### Fixed
@@ -4424,7 +4582,9 @@ hosts that both arrange the page the way it expects.
 ### Notes
 - First release — exercising the automated npm OIDC publish pipeline end-to-end.
 
-[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.42.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.44.0...HEAD
+[0.44.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.43.0...v0.44.0
+[0.43.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.42.0...v0.43.0
 [0.42.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.41.3...v0.42.0
 [0.41.3]: https://github.com/Artui/ag-ui-web-component/compare/v0.41.2...v0.41.3
 [0.41.2]: https://github.com/Artui/ag-ui-web-component/compare/v0.41.1...v0.41.2

package/README.md

@@ -199,7 +199,7 @@ another origin, add `credentials="include"` too; see
 | `data-unread-badge` | — | **On by default.** `="false"` hides the launcher's unread badge; the count and the `ag-ui-unread` event keep running. See [Collapsing to the launcher](#collapsing-to-the-launcher). |
 | `data-launcher-drag` | — | **On by default.** `="false"` leaves the widget wherever your CSS puts it. Otherwise the collapsed launcher can be dragged anywhere on screen (the panel opens into the clearest space) and the open panel can be dragged by its header. See [Moving the launcher](#moving-the-launcher) and [Moving the panel](#moving-the-panel). |
 | `data-quote-selection` | — | **On by default.** `="false"` stops the transcript offering to quote a selection. `quote()` keeps working either way. See [Quoting a selection](#quoting-a-selection). |
-| `data-message-actions` | — | **All on by default.** A comma list of the actions a finished answer keeps: `copy` / `retry` / `feedback` (e.g. `"copy,retry"`). `="false"` removes the row entirely. See [Message actions](#message-actions-copy-retry-feedback). |
+| `data-message-actions` | — | **Copy and retry by default; feedback is opt-in.** A comma list of the actions a finished answer keeps: `copy` / `retry` / `feedback` (e.g. `"copy,retry,feedback"` to add the rating pair, which needs an `ag-ui-feedback` listener). `="false"` removes the row entirely. See [Message actions](#message-actions-copy-retry-feedback). |
 | `data-max-tool-rounds` | — | Upper bound on frontend tool-call → re-run rounds within one send (default 10; a value below 1 is ignored). Raise it for a page-driving agent whose turn takes many small steps. See [The run loop](#the-run-loop-and-the-ag-ui-client). |
 | `data-page-actions` | — | Opt-in built-in page-action tools: a comma list of `scroll` / `drag` / `chat` (e.g. `"scroll,drag"`). See [Page-action tools](#page-action-tools). |
 | `data-side` | — | CSS-only, for `placement="sidebar"`: which edge it docks to — `right` (default) / `left`. |
@@ -305,23 +305,49 @@ the `copyCode` / `copied` / `copyFailed` strings.
 
 `sendMessage(content, attachments?)` sends as if the user had typed it — user bubble,
 `ag-ui-submit` event, run started. Use it for an "Ask about this order" button, a command
-palette, or a composer of your own replacing the built-in one. It no-ops for an entirely
-empty message, and while a run — or a checkpoint continuation picked from the panel — is in
-flight. A continuation counts from the pick, and a send from the call rather than from when its
-run starts, so a `sendMessage` from an `ag-ui-submit` listener, or a second call in the same
-task, is refused rather than starting a second run. So is one made while a reload resumes a run
-a navigating tool interrupted: the resume counts from the moment the element asks its
-conversation store for the conversation, so a `sendMessage` while a remote store is still
-answering is refused, and the built-in Send queues behind the resumed answer. Your own code
-that runs on the way to the request — the conversation store's save, `getContext`, `getTools` —
-can stop a send by starting a new chat or changing `user-key`, and then nothing is sent. Unlike
-the built-in Send it does **not** queue, so your composer keeps what it tried to send, and it
-does **not** consult the attachment tray: what you pass is what is sent, so your composer stays
+palette, a prompt fired when your page mounts the chat, or a composer of your own replacing the
+built-in one.
+
+It returns a `Promise<boolean>`. It resolves `true` once the turn has been handed to the agent
+and its run has settled, frontend-tool rounds included, and `false` when nothing was sent:
+
+- for an entirely empty message;
+- while a run, or a checkpoint continuation picked from the panel, is in flight. A continuation
+  counts from the pick, and a send from the call rather than from when its run starts, so a
+  `sendMessage` from an `ag-ui-submit` listener, or a second call in the same task, is refused
+  rather than starting a second run;
+- with no `endpoint` set, which the transcript also says;
+- while a reload resumes a run a navigating tool interrupted. The resume counts from the moment
+  the element asks its conversation store for the conversation, and it ends by starting that
+  run, so a send then is refused, and the built-in Send queues behind the resumed answer;
+- when your own code that runs on the way to the request — an `ag-ui-submit` listener, the
+  conversation store's save — stops it by starting a new chat or changing `user-key`. A
+  `getContext` or `getTools` that does the same stops it too, but after the turn was handed
+  over, so the call resolves `true`.
+
+**While the element restores a stored conversation, a send waits for it.** Every restore —
+when the element connects, on `reload()`, when a thread is picked from the drawer, and when
+`user-key` changes from one principal to another — first asks the conversation store for the conversation, and with
+`data-threads-url` that is a request to your server. A `sendMessage` made in that time waits
+until the conversation is drawn, then sends with it: the bubble, the `ag-ui-submit` event and the
+request all come after the replay, later than the call by the length of the load. So a prompt
+fired on mount needs no timing of its own. If New chat, a thread switch, a change from one
+`user-key` to another or a `reload()` comes while it waits, the conversation it was addressed
+to is gone, so it is dropped and resolves `false` at once. The element leaving the page drops it
+too, but it resolves `false` only once the load answers or the element is inserted again. A
+first `user-key` on an anonymous conversation adopts that conversation rather than replacing
+it, so a send waiting then still goes out. A second `sendMessage` while one waits is refused. The built-in Send queues what is typed during the load ("Waiting to send"),
+and sends it after the conversation is drawn, behind a `sendMessage` that was waiting.
+
+Unlike the built-in Send it does **not** queue, so your composer keeps what it tried to send, and
+it does **not** consult the attachment tray: what you pass is what is sent, so your composer stays
 in charge of its own state.
 
 `retryLastTurn()` keeps the same rules, because it starts a run on the same conversation. It
-returns `false` while a run, a send, another Retry, a continuation or a reload's resume is in
-flight, and it counts from the call as a send does: until its run starts, a `sendMessage` or a
+returns `false` while a run, a send, another Retry or a continuation is in flight, and while
+any restore of the stored conversation is still loading. It does not wait for the load as a send
+does: until the conversation is drawn there is nothing on screen to retry, and afterwards it
+would ask the previous visit's last question again. It counts from the call as a send does: until its run starts, a `sendMessage` or a
 second Retry is refused, the built-in Send queues, and a checkpoint pick is refused. It also
 returns `false` when your own code stops it before its run starts: a conversation store, or an
 activity or tool renderer it redraws through, that starts a new chat or changes `user-key`. A
@@ -499,9 +525,10 @@ function Assistant() {
 
 Writing it as `<ag-ui-chat ref={...} />` in JSX and configuring in the ref callback mostly works —
 the catalog requests are held back one microtask precisely so a ref assigned in the same commit is
-honoured — but the thread-history request is **not** deferred (a deferred replay could land after a
-`sendMessage()` and duplicate the transcript), so that one goes out with whatever was configured at
-insertion.
+honoured — but the thread-history request is **not** deferred, so that one goes out with whatever
+was configured at insertion. It starts at insertion because the restore is what a `sendMessage()`
+from the same commit waits on: a restore that had not started yet would have nothing to hold it,
+and the send would go out without the conversation.
 
 If your credentials can only arrive later still — an awaited token, a passive effect — call
 **`reload()`** once they land:
@@ -1885,13 +1912,46 @@ still takes its margin and still announces itself as a group of actions.
 `retryLastTurn()` is public, for a host driving its own message UI.
 
 ```js
+await chat.retryLastTurn(); // false when there is nothing to ask again, a run is in flight, or a restore is loading
+```
+
+### Storing a rating
+
+`ag-ui-feedback` names the message that was rated, so a host can file the
+rating against it rather than against its text — two answers can read the same,
+and nothing about the text survives a reload:
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `messageId` | `string` | The AG-UI id of the rated assistant message: the id it streamed under (`TEXT_MESSAGE_START` / `TEXT_MESSAGE_END`), or the stored message's `id` when it was restored from history. A restored answer whose store returned no id offers no rating pair, since a rating has to name a message. |
+| `threadId` | `string` | The conversation it belongs to: the element's thread when the message was drawn. |
+| `runId` | `string`, optional | The run that streamed it, as that run's `RUN_STARTED` named it. Text a sub-agent streams through the parent run carries the parent's `runId`. **Absent on a restored message** — an AG-UI message carries no run id, so there is none to give and the key is left out rather than guessed. |
+| `content` | `string` | The message's text, as rendered. |
+| `rating` | `"up"` \| `"down"` | Which button. |
+
+```js
+chat.setAttribute("data-message-actions", "copy,retry,feedback");
 chat.addEventListener("ag-ui-feedback", (e) => {
-  analytics.track("assistant_rating", e.detail); // { content, rating }
+  const { messageId, threadId, runId, rating } = e.detail;
+  // Keyed by message: rating the same answer again replaces the earlier rating.
+  fetch(`/api/threads/${threadId}/ratings/${messageId}/`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ rating, ...(runId === undefined ? {} : { runId }) }),
+  });
 });
-
-await chat.retryLastTurn(); // false when there is nothing to ask again, or a run is in flight
 ```
 
+> [!NOTE]
+> **A restored message is named by whatever `id` the conversation store returns
+> for it.** The built-in browser store saves the conversation as it streamed, so
+> there a message keeps its id across a reload. With `data-threads-url` or a
+> `conversationStore` of your own, the conversation comes back from your server,
+> and a message keeps its id only if the server persists the ids it streamed:
+> one that stores the conversation under fresh ids makes a rating made live and a
+> rating made after a reload name the same answer by two different ids. Live,
+> the id is always the one on the wire.
+
 ## Quoting a selection
 
 Select any text in the transcript and a small **Quote** offer floats beside it.
@@ -2481,6 +2541,11 @@ stop it, and what you typed stays in the composer for the pick after. The run in
 flight is not cancelled for you, since a continuation starting over it would
 leave two answers streaming into one transcript with Stop reaching only one.
 
+Picking a row while a stored conversation is still loading is refused the same
+way, with a hint asking you to wait for the load: a continuation sends only the
+new turn, so it must not start before the history it continues is on screen. The
+wording is the `continueWhileLoading` string.
+
 ### One URL, three endpoints
 
 `data-runs-url` is the only thing to configure. `resume/<id>/` and `fork/<id>/`
@@ -2623,6 +2688,7 @@ re-export point. Internal modules import from leaf paths.
 | `AgUiClient` | class | Orchestration layer over an AG-UI `AbstractAgent`. |
 | `AgUiClientConfig` / `AgUiClientHandlers` / `AgUiRunInputs` | type | Client config, lifecycle handlers, per-run input providers. |
 | `AgUiToolCall` / `ToolExecution` / `ExecuteTool` | type | Tool-call shape, execution result, executor signature. |
+| `AgUiMessageIds` | type | Which message `AgUiClientHandlers.onTextEnd` completed: its `messageId`, and the `runId` its `RUN_STARTED` named. |
 | `ToolOutcome` | type | The `TOOL_OUTCOME` values as a union. |
 | `toolStatusFromOutcome` | function | Map a wire outcome to the card status it settles into; anything absent or unrecognised is a success. |
 | `ConnectionLostError` | class | Raised (→ `onError`) when a run's stream closes with no terminal AG-UI event. |
@@ -2668,7 +2734,7 @@ re-export point. Internal modules import from leaf paths.
 | `RunFinishedDetail` / `ToolRun` | type | `ag-ui-run-finished` detail: the tools an interaction ran, and which side ran them. |
 | `CustomAgentDetail` | type | `ag-ui-custom` detail: an AG-UI `CUSTOM` event's `name` and `value`, verbatim. |
 | `InvalidateDetail` | type | `ag-ui-invalidate` detail: the resource `keys` that moved, and the `reason`. |
-| `FeedbackDetail` | type | `ag-ui-feedback` detail: the rated message's `content` and the `rating`. |
+| `FeedbackDetail` | type | `ag-ui-feedback` detail: the rated message's `messageId`, its `threadId`, the `runId` that streamed it (live only), its `content` and the `rating`. See [Storing a rating](#storing-a-rating). |
 | `relativeTime` | function | The built-in locale-neutral timestamp formatter (`"5m ago"`), for a host building on it. |
 | `RelativeTimeFormatter` | type | What `formatRelativeTime` takes: an epoch-ms timestamp in, row text out. |
 | `renderSuggestionChips` | function | Draw a `suggestions` activity as chips that send themselves; `null` when nothing survives. |