@artooi/ag-ui-web-component 0.35.1 → 0.36.0

package/CHANGELOG.md

@@ -7,6 +7,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **The README's two callouts rendered as code blocks.** This file is the
+  documentation -- there is no docs site, so it is what GitHub shows and what npm
+  puts on the package page -- and `!!! note` is MkDocs syntax that neither
+  understands. The line rendered literally and its indented body became a *code
+  block*, so a warning was displayed as something to copy. Both are now GitHub
+  callouts.
+
+  One of the two was 0.35.1's own note about forgetting `defineAgUiChat()`,
+  written because that failure is silent. A reader hit the same failure after it
+  shipped, which is how the rendering was found: the note was there, was
+  correct, and reached nobody. `tests/readme_renders.test.ts` now fails on any
+  admonition, and on the registration callout going missing.
+
 ## [0.35.1] — 2026-09-05
 
 ### Documentation
@@ -3415,7 +3477,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.1...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.36.0...HEAD
+[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
 [0.34.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.33.1...v0.34.0

package/README.md

@@ -149,16 +149,18 @@ Drop the element into your page and register the tools the agent may call:
 <ag-ui-chat endpoint="/agent/" title-text="Assistant"></ag-ui-chat>
 ```
 
-!!! note "If nothing appears, check `defineAgUiChat()` ran"
-    Forgetting it looks like nothing. `<ag-ui-chat>` is then an *unknown
-    element*, which every browser renders as an inline 0x0 box, in flow, with no
-    console warning and no error — so the page looks finished and the chat is
-    simply absent. A bare `import "@artooi/ag-ui-web-component"` does not
-    register anything, deliberately: registration is an explicit call so the
-    package stays tree-shakeable.
-
-    `customElements.get("ag-ui-chat")` in a console answers it in one line —
-    `undefined` means the call did not run.
+> [!IMPORTANT]
+> **If nothing appears, check that `defineAgUiChat()` ran.** Forgetting it looks
+> like nothing at all. `<ag-ui-chat>` is then an *unknown element*, which every
+> browser renders as an inline 0x0 box, in flow, with no console warning and no
+> error — so the page looks finished and the chat is simply absent. There is
+> nothing to search for.
+>
+> A bare `import "@artooi/ag-ui-web-component"` registers nothing, deliberately:
+> registration is an explicit call so the package stays tree-shakeable.
+>
+> `customElements.get("ag-ui-chat")` in a console answers it in one line.
+> `undefined` means the call did not run.
 
 That's the whole integration: an `endpoint` attribute pointing at your AG-UI server, optional
 `headers`, and the tools you want the agent to be able to invoke in the browser. If your API is on
@@ -553,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
@@ -1668,11 +1702,11 @@ Retry sits on the **last** answer only. Re-running an older turn is branching,
 and for a page-driving agent editing a past turn is not neutral — those turns
 clicked buttons, and re-running turn 3 does not un-save what turn 5 saved.
 
-!!! note
-    A retried turn **re-runs its tools.** The previous attempt already did what
-    it did, and this does not undo it. Confirmation still applies, so a
-    destructive tool asks again — unless the user waived it for this session
-    with *Always allow*.
+> [!NOTE]
+> A retried turn **re-runs its tools.** The previous attempt already did what it
+> did, and this does not undo it. Confirmation still applies, so a destructive
+> tool asks again — unless the user waived it for this session with
+> *Always allow*.
 
 A failed run gets the same row, with Retry and Copy and no rating: error text is
 what people paste into a bug report, but "the connection dropped" is not a
@@ -1921,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
@@ -2395,6 +2438,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. |
@@ -2549,6 +2594,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. |