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

package/CHANGELOG.md

@@ -7,6 +7,37 @@ 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
@@ -4551,7 +4582,8 @@ 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.43.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

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`. |
@@ -1912,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, a run is in flight, or a restore is loading
 ```
 
+> [!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.
@@ -2655,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. |
@@ -2700,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. |