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

package/CHANGELOG.md

@@ -7,6 +7,51 @@ 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
@@ -3432,7 +3477,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.35.2...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

package/README.md

@@ -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
@@ -2397,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. |
@@ -2551,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. |