@artooi/ag-ui-web-component 0.35.2 → 0.37.0

package/CHANGELOG.md

@@ -7,6 +7,115 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.37.0] — 2026-09-06
+
+### Fixed
+
+- **The README attribute gate only checked one direction, so it could not see its
+  own weakening.** It asked whether every attribute the element *reads* is
+  documented; an attribute falling out of the scanned set shrinks the set being
+  filtered, so the answer stays empty and nothing goes red. Adding a
+  variable-named read and raising the declared count -- without teaching the
+  matcher the new helper -- dropped two attributes out of the scan and the whole
+  suite still passed. Verified by doing exactly that: 1651 tests green.
+
+  There is now a reverse check. It refuses a documented row that nothing
+  consumes, and "consumes" had to be defined carefully: four documented
+  attributes (`density`, `data-side`, `data-small-viewport`, `data-answer-well`)
+  are host-set and read by the stylesheet alone through `:host([...])`, never by
+  any `getAttribute` call. A first version that looked only at JavaScript called
+  all four stale, which would have deleted four working rows.
+
+- **A message sent with no `endpoint` disappeared without a word.** The send path
+  returned early when the attribute was unset, and by then the two visible halves
+  of a successful send had already happened: the user's bubble was in the
+  transcript and `ag-ui-submit` had been dispatched. So the composer cleared, the
+  message appeared to go, Send never became Stop, no request was made, and
+  nothing at all reached the console. What that looks like is an agent ignoring
+  you, and what it gets reported as is a server that never answers.
+
+  The refusal stays -- there is nowhere to send to, and an agent built on an
+  empty endpoint would post to the current page -- but both audiences are now
+  told, because they need different things. A `console.error` names the missing
+  attribute and what to set it to, since a missing attribute is the page's
+  mistake and the page's author is not reading the transcript. A `not-connected`
+  run notice tells the reader their message went nowhere, because the honest
+  alternative to one muted line is an indefinite wait in front of their own
+  question. Both fire on every attempt rather than once: a one-shot report is the
+  same silence again for the second try, which is the try a puzzled user makes.
+
+- **Picking a run to continue with an empty composer closed the panel over
+  nothing.** A continuation sends only the new turn -- the server supplies
+  everything before it from the snapshot -- so with nothing typed there was
+  nothing to send, and the handler returned. The row's button had already
+  dismissed the panel by then, so the widget visibly reacted and then did
+  nothing, which reads as a resume that was attempted and lost rather than one
+  that never started. It now says what the composer still needs, above the input
+  and cleared by the next keystroke, and puts the caret there.
+
+- **A `data-strings` or `data-skills` value that would not parse was discarded
+  without a word.** Quoting JSON inside an HTML attribute is fiddly, and the
+  result of getting it wrong was indistinguishable from never having set the
+  attribute: the strings stayed English, or the palette came up empty, with
+  nothing anywhere naming the attribute. Both now warn on the console, naming
+  which one and what to check -- the answer `data-paste-attach` already gave for
+  a value it could not read. Console only: a page author's typo is not the
+  reader's business, nothing the reader did was refused, and the widget is still
+  perfectly usable without the override.
+
+### Changed
+
+- The composer hint above the input is no longer only a skills affordance: it
+  also carries the message above. Its `skill-hint` `part` is unchanged, since
+  renaming a part is breaking and a second hint in the same slot would be worse
+  than one whose name is older than its job. Two new `UiStrings` keys,
+  `notConnected` and `continueNeedsTurn`, are overridable like every other.
+
+## [0.36.0] — 2026-09-05
+
+### Added
+
+- **A tool call that failed can now say so.** `TOOL_CALL_RESULT` may carry an
+  optional `outcome` field -- `success`, `failed` or `denied`, read off the new
+  `TOOL_OUTCOME` constant -- and the card settles to *done*, *error* or
+  *declined* accordingly. **Absent is a success**, so every server written before
+  the field existed renders exactly as it did, and so does any value this release
+  does not recognise: a card is a claim about what happened, and not knowing a
+  word is not grounds for claiming failure.
+
+  Nothing in `@ag-ui/core` declares the field. AG-UI's event schemas extend a
+  `passthrough` base, so an unknown key survives parsing and reaches the
+  subscriber -- asserted in `tests/ag_ui_event_contract.test.ts`, because if that
+  ever stops being true every card silently goes back to claiming success.
+
+  `AgUiClientHandlers.onToolResult` gains a third parameter for it, typed
+  `unknown` because the protocol does not validate it; `toolStatusFromOutcome`
+  does the narrowing. A handler written against the two-parameter form still
+  satisfies the interface and still behaves as before. A **frontend** tool states
+  its own outcome on the `ToolExecution` it returns, since no server ran it.
+
+### Fixed
+
+- **A refused tool call rendered as a successful one.** Every `TOOL_CALL_RESULT`
+  settled its card as *done*, whatever the server said, so a refusal arrived
+  green with the reason folded into its result body -- in a sibling demo, a
+  booking the server had declined read at a glance as a booking that was made.
+  `ERROR` and `DECLINED` existed and the card rendered all three distinctly; they
+  were simply unreachable from the server's side.
+
+- **A reload turned every tool card green**, which was the same bug reached by a
+  second path and needed no server involvement at all: restoring a conversation
+  settled *every* historical `tool` message as *done*, so a confirmation the user
+  had cancelled came back as an action that went through. The outcome is now
+  persisted beside the tool message and read back through the same mapping the
+  live path uses.
+
+  It is written onto the copy handed to the store, never onto `agent.messages` --
+  so it does not travel back to the server on the next run -- and a store that
+  drops fields it does not know loses only the distinction, falling back to
+  *done*. `Message` does not declare the field, exactly as it does not declare
+  the `attachments` an upload rides on a user message.
+
 ## [0.35.2] — 2026-09-05
 
 ### Fixed
@@ -3432,7 +3541,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.35.2...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.37.0...HEAD
+[0.37.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.36.0...v0.37.0
+[0.36.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.35.2...v0.36.0
 [0.35.2]: https://github.com/Artui/ag-ui-web-component/compare/v0.35.1...v0.35.2
 [0.35.1]: https://github.com/Artui/ag-ui-web-component/compare/v0.35.0...v0.35.1
 [0.35.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.34.0...v0.35.0

package/README.md

@@ -173,14 +173,14 @@ another origin, add `credentials="include"` too; see
 
 | Attribute | Property | Notes |
 | --- | --- | --- |
-| `endpoint` | `endpoint` | The AG-UI endpoint URL. Required to send. Reflecting getter + setter. |
+| `endpoint` | `endpoint` | The AG-UI endpoint URL. Required to send: without it a send is refused with a `console.error` naming the missing attribute and a `not-connected` run notice in the transcript. Reflecting getter + setter. |
 | `credentials` | `credentials` | Cookie policy for every request the element makes: `omit` / `same-origin` / `include`. Unset means the browser default (`same-origin`), which sends no cookies cross-origin. See [Authenticating requests](#authenticating-requests). |
 | `title-text` | — | Header label; defaults to `"Assistant"`. Live: writing it after the element connects re-labels the header. See [When each attribute is read](#when-each-attribute-is-read). |
 | `data-tool-display` | `toolDisplay` | Tool-call card detail: `inline` / `minimal` / `compact` / `full` (default `full`). |
 | `data-text-animation` | — | Incoming-text reveal: `none` (default) / `fade` / `word`. |
 | `data-prompt-chips` | — | Present (bare, or any value but `"false"`) to surface skills as chips. |
 | `data-slash-commands` | — | Present (bare, or any value but `"false"`) to enable the `/`-command palette. |
-| `data-skills` | — | Inline JSON skill catalog. |
+| `data-skills` | — | Inline JSON skill catalog. A value that will not parse is ignored and reported on the console, rather than reading as an empty catalog. |
 | `data-skills-url` | — | URL of a JSON skill catalog (fetched with the element's headers and cookie policy). |
 | `data-tools-url` | — | URL of a server tool-label catalog (`[{ name, summary, description? }]`), fetched with the element's headers and cookie policy; labels tool-call cards for server-side tools. |
 | `user-key` | `userKey` | Who the stored conversation belongs to — any string identifying the signed-in principal. Joins the storage namespace, and **changing it purges what the previous principal left behind**. Live (not connect-time): a logout is the host's to announce. See [Who the stored conversation belongs to](#who-the-stored-conversation-belongs-to-user-key). |
@@ -192,7 +192,7 @@ another origin, add `credentials="include"` too; see
 | `data-attachment-max-bytes` | — | Client-side upload size cap in bytes (default 10 MiB; `0` disables). The server stays authoritative. |
 | `data-transcribe-url` | — | URL of the voice-transcription endpoint (django-ag-ui's `TranscribeView`); reveals the composer's mic button. See [Voice input](#voice-input). |
 | `data-theme-toggle` | — | Boolean: show a built-in header light⇄dark toggle (persists per tab). Off by default. See [Theme toggle](#theme-toggle). |
-| `data-strings` | `strings` | Partial JSON override of the UI string table (localization). The property wins key-by-key over the attribute; see [Internationalization](#internationalization-i18n). |
+| `data-strings` | `strings` | Partial JSON override of the UI string table (localization). The property wins key-by-key over the attribute; a value that will not parse is ignored and reported on the console. See [Internationalization](#internationalization-i18n). |
 | `data-icon-url` | — | Header (and launcher) icon image URL. A slotted `slot="icon"` wins; see [Header & launcher icon](#header-and-launcher-icon). |
 | `data-launcher-icon-url` | — | Icon image URL for the collapsed launcher only, when it should differ from the header's. Falls back to `data-icon-url`; a slotted `slot="launcher"` wins over both. |
 | `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). |
@@ -555,6 +555,38 @@ card (honouring `data-tool-display`), so server-side output is visible too. The
 and context are read **fresh on every run** (`getTools()` / `getContext()`), so they always reflect
 the current page state.
 
+#### A tool call that failed
+
+A `TOOL_CALL_RESULT` may carry an optional **`outcome`** field saying how the call ended. It takes
+pydantic-ai's own `ToolReturnPart` vocabulary — read the values off `TOOL_OUTCOME`:
+
+| `outcome` | Card | Means |
+| --- | --- | --- |
+| *(absent)* | done | A result, said the way every server has always said it. |
+| `success` | done | The same thing, stated. |
+| `failed` | error | The call ran and failed. |
+| `denied` | declined | A person or a guard refused it, so it never ran. |
+
+**Absent is a success, and anything unrecognised is too** — including a value from a later protocol
+version, and pydantic-ai's own `interrupted`. A card is a claim about what happened, and refusing to
+recognise a word is not grounds for claiming failure. So no server has to change to keep the
+rendering it has today, and a server that adds the field gets the truth on screen instead of a
+green card with a refusal folded inside it.
+
+Nothing in `@ag-ui/core` needs to declare the field: AG-UI's event schemas are zod `passthrough`, so
+an unknown key survives parsing and reaches the subscriber. It arrives on
+`AgUiClientHandlers.onToolResult` as an optional third argument, typed `unknown` because the
+protocol does not validate it; `toolStatusFromOutcome` does the narrowing.
+
+A **frontend** tool never streams this event — the client posts its own result — so its outcome is
+recorded on the `ToolExecution` the executor returns (`{ content, outcome: "denied" }`). That covers
+the two refusals the component makes itself: a confirmation card the user declined, and a call
+blocked because the page moved under the round.
+
+Either way the outcome is **persisted beside the tool message**, so a reload replays the card as it
+settled rather than as a plain result. See
+[MPA durability](#mpa-durability-surviving-full-page-reloads).
+
 The catalog a run advertises is also the set that run can execute. Override `getTools` to scope
 what a page offers — say, exposing `delete_record` only where deleting makes sense — and a call
 naming a tool you withheld is treated exactly as a call naming a tool you never registered: no
@@ -1923,6 +1955,15 @@ On mount the element rehydrates the transcript from the store, so the chat looks
 including tool-call cards and their results (reconstructed from the persisted `toolCalls` and `tool`
 messages), not just the text turns.
 
+A tool message is saved with an extra **`outcome`** field when the call did not simply succeed, in
+the same vocabulary the wire uses (see [A tool call that failed](#a-tool-call-that-failed)), so a
+failed or declined card replays as failed or declined instead of turning green on reload. `Message`
+does not declare the field, exactly as it does not declare the `attachments` an upload rides on a
+user message; the default store round-trips both through `JSON.stringify`. **A store that drops
+unknown fields loses only the distinction** — the card falls back to *done*, which is what it did
+before. It is written onto the copy handed to the store and never onto `agent.messages`, so it is
+not sent back to the server on the next run.
+
 **3. Resumable loop (`x-navigates` + `navigationResult`).** A tool whose schema carries
 `x-navigates: true` (use `X_NAVIGATES_KEY`; read back by [`isNavigates`](src/tools/is_navigates.ts))
 triggers a full reload. Before the handler navigates, the element writes a checkpoint
@@ -2271,6 +2312,10 @@ Type the next turn in the composer, then pick a row:
 
 Both send to the matching server endpoint and stream into the same transcript.
 
+Picking a row with an empty composer says so above the input and puts the caret
+there, rather than closing the panel over nothing: a continuation sends **only**
+the new turn, so with nothing typed there is nothing to send.
+
 ### One URL, three endpoints
 
 `data-runs-url` is the only thing to configure. `resume/<id>/` and `fork/<id>/`
@@ -2397,6 +2442,8 @@ 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. |
+| `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. |
 | `createHttpAgent(options)` | function | Default agent factory (wraps `HttpAgent`). |
 | `AgentFactory` / `HttpAgentOptions` | type | Factory signature and its options. |
@@ -2551,6 +2598,7 @@ re-export point. Internal modules import from leaf paths.
 | `MESSAGE_ACTIONS` | The message-action tokens `data-message-actions` selects by (`copy` / `retry` / `feedback`). |
 | `TOOL_CALL_STATUS` | Tool-call card status constants. |
 | `TOOL_DISPLAY` | Tool-call display-mode constants (`inline` / `minimal` / `compact` / `full`). |
+| `TOOL_OUTCOME` | How a tool call ended, as a server states it on `TOOL_CALL_RESULT` (`success` / `failed` / `denied`). |
 | `X_CONFIRM_KEY` | Confirmation-prompt key: on a tool's JSON Schema for a client-side confirmation, and in an AG-UI interrupt's `metadata` for a server-side approval. |
 | `X_SUMMARY_KEY` | JSON-Schema key carrying a short tool-card label. |
 | `MAX_TOOL_ROUNDS` | Upper bound on tool-call → re-run rounds per send. |
@@ -2829,7 +2877,7 @@ component sets, so a new one cannot ship undocumented.
 | Follow-up suggestions | `suggestions`, `suggestion-chip` |
 | Message actions | `message-actions`, `message-action` (plus `message-action-retry`, `message-action-copy`, `message-action-up`, `message-action-down`), and the icon holder inside each: `message-action-icon` (plus `message-action-icon-retry`, `message-action-icon-copy`, `message-action-icon-up`, `message-action-icon-down`) |
 | Queued messages | `queued`, `queued-chip` |
-| Run notices | `run-notice` (plus `run-notice-interrupted`, `run-notice-attachment-pending`, `run-notice-compaction`, `run-notice-skill`, `run-notice-history-replaced`, `run-notice-chart-undrawable`, `run-notice-surface`), `run-notice-icon`, `run-notice-text`, `run-notice-undo` |
+| Run notices | `run-notice` (plus `run-notice-interrupted`, `run-notice-attachment-pending`, `run-notice-compaction`, `run-notice-skill`, `run-notice-history-replaced`, `run-notice-chart-undrawable`, `run-notice-surface`, `run-notice-not-connected`), `run-notice-icon`, `run-notice-text`, `run-notice-undo` |
 | Tool cards | `tool-card`, `tool-card-head`, `tool-card-icon`, `tool-card-name`, `tool-card-status`, `tool-card-decision`, `tool-card-toggle`, `tool-card-body`, `tool-card-section` (plus `tool-card-args-section`, `tool-card-result-section`), `tool-card-section-label` (plus `tool-card-args-label`, `tool-card-result-label`), `tool-card-args`, `tool-card-result`, `tool-card-approval`, `tool-card-subagent` |
 | Delegated sub-agents | `subagent`, `subagent-row`, `subagent-icon`, `subagent-status`, `subagent-steps`, `subagent-step`, `subagent-step-icon`, `subagent-step-name` |
 | Client-side confirmation | `confirm`, `confirm-body`, `confirm-args`, `confirm-actions`, `confirm-button` (plus `confirm-confirm`, `confirm-cancel`, `confirm-always`) |
@@ -2837,7 +2885,7 @@ component sets, so a new one cannot ship undocumented.
 | Typed question | `question`, `question-body`, `question-options`, `question-choice`, `question-choice-text`, `question-radio`, `question-input`, `question-actions`, `question-button` |
 | Composer | `composer`, `composer-surface`, `composer-tools`, `input`, `send`, `attach-button`, `voice-button` |
 | Attachments | `attachment-tray`, `attachment-chips` (the read-only chips on sent bubbles), and the shared chip parts `attachment-chip`, `attachment-chip-icon`, `attachment-chip-name`, `attachment-chip-size`, `attachment-chip-bar`, `attachment-chip-bar-fill`, `attachment-chip-retry`, `attachment-chip-remove` |
-| Skills | `skill-chips`, `skill-chip`, `skill-palette`, `skill-item`, `skill-item-title`, `skill-item-desc`, `skill-item-token`, `skill-hint` (the missing-placeholder hint) |
+| Skills | `skill-chips`, `skill-chip`, `skill-palette`, `skill-item`, `skill-item-title`, `skill-item-desc`, `skill-item-token`, `skill-hint` (the composer hint: a skill’s missing placeholders, and a run continuation with nothing typed) |
 | Thread drawer | `drawer`, `drawer-backdrop`, `drawer-panel`, `drawer-header`, `drawer-title`, `drawer-new`, `drawer-close`, `drawer-filter`, `drawer-list`, `drawer-empty`, `drawer-row`, `drawer-row-select`, `drawer-row-title`, `drawer-row-time`, `drawer-row-preview`, `drawer-row-actions`, `drawer-row-rename`, `drawer-row-delete`, `drawer-rename-input`, `drawer-confirm`, `drawer-confirm-label`, `drawer-confirm-yes`, `drawer-confirm-no` |
 | Charts | `chart-block`, `chart-title`, `chart-legend` |
 | Checkpoints panel | `checkpoints`, `checkpoints-header`, `checkpoints-title`, `checkpoints-list`, `checkpoints-empty`, `checkpoint-row`, `checkpoint-label`, `checkpoint-time`, `checkpoint-id`, `checkpoint-branch`, `checkpoint-action` (plus `checkpoint-resume`, `checkpoint-fork`) |