@artooi/ag-ui-web-component 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -7,6 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] — 2026-07-14
+
+### Added
+
+- **Server-side tool approval — the browser half of the human-in-the-loop gate.**
+  When a gated server-side tool defers instead of executing, the run finishes on
+  an AG-UI *interrupt*; the client now renders an inline **approval card**
+  (`requestApproval`, next to the pending tool-call card) and, on the user's
+  decision, resumes the run with the answer via the protocol's `resume[]`.
+  Approve runs the tool (its result streams back into the same card); deny sends
+  a `cancelled` answer so the model learns it was declined and the card settles
+  as declined. No `@ag-ui/*` dependency bump — the interrupt/resume types already
+  ship in the pinned `0.0.x`. `AgUiClient` gains a `resolveInterrupts` config hook
+  and exports `InterruptResponse` / `ResolveInterrupts`. The card is fully
+  customizable: `strings` (`approveAction` / `approvalPrompt` / `approve` /
+  `deny`), a `::part()` surface (`approval`, `-body`, `-actions`, `-button`,
+  `-approve`, `-deny`), and an `approvalRenderer` hook that fully replaces the UI
+  (given the request + a Stop `AbortSignal`, resolves approve/deny). Exports
+  `ApprovalRenderer`.
+- **`ask_user` — a built-in typed-question frontend tool (opt-in).** Set
+  `askUser = true` on `<ag-ui-chat>` to offer the agent an `ask_user(question,
+  options?, allow_custom?)` tool: calling it renders an inline **question card**
+  (`requestQuestion` — radio choices and/or a free-text field) and returns the
+  chosen or typed answer as the tool result, reusing the existing frontend-tool
+  path (no new protocol). Off by default, like the other built-in tool groups, so
+  the advertised catalog is unchanged until a host opts in. The card is **fully
+  customizable**: localized `strings` (`askUserAction` / `otherOption` /
+  `answerPlaceholder` / `submit`), a full `::part()` surface (`question`,
+  `question-body`, `-options`, `-choice`, `-radio`, `-input`, `-actions`,
+  `-button`), and a `askUserRenderer` hook that fully replaces the UI with a
+  host-supplied renderer (given the request + a Stop `AbortSignal`, resolves the
+  answer). Exports `QuestionRenderer`.
+- **Complete `::part()` coverage sweep.** Every rendered UI element now exposes a
+  `part` for `::part()` styling — closing gaps in the attachment chips
+  (`attachment-chips` and the shared `attachment-chip*` parts, now on both the
+  composer tray and the read-only chips on sent bubbles), the skills UI
+  (`skill-chips` / `skill-chip` / `skill-palette` / `skill-item*` / `skill-hint`),
+  the history-drawer row internals (`drawer-row-title` / `-time` / `-preview` /
+  `-actions` / `-rename` / `-delete`, the inline `drawer-rename-input`, and the
+  `drawer-confirm*` delete prompt), plus `thoughts-label`, `question-choice-text`,
+  and the `stopped` note. All are documented in the README "Available parts" list.
+
 ## [0.10.0] — 2026-07-02
 
 ### Added
@@ -453,7 +495,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Notes
 - First release — exercising the automated npm OIDC publish pipeline end-to-end.
 
-[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.10.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.11.0...HEAD
+[0.11.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.8.1...v0.9.0
 [0.8.1]: https://github.com/Artui/ag-ui-web-component/compare/v0.8.0...v0.8.1

package/README.md

@@ -171,7 +171,7 @@ That's the whole integration: an `endpoint` attribute pointing at your AG-UI ser
 | `placement` | — | CSS-only: `floating` (default) / `bottom-left` / `side` / `sidebar` / `full` / `page` / `embedded`. |
 
 **Properties** (JS only, not attributes): `headers`, `allowImages`, `autoConfirm`,
-`confirmPredicate`, `agentFactory`, `getTools`, `getContext`, `routeMap`, `navigate`,
+`confirmPredicate`, `askUser`, `agentFactory`, `getTools`, `getContext`, `routeMap`, `navigate`,
 `getPageMap`, `autoInjectPageMap`, `conversationStore`, `uploadHandler`, `transcribeHandler`,
 `navigationResult`, `skillContext`, `toolSummaries`, `strings`, `resolvePageTarget`, plus the
 mirrors `endpoint` / `toolDisplay` / `collapsed`.
@@ -234,7 +234,8 @@ AG-UI has no server-side cancel route: cancelling **aborts the streaming request
   round starts. A frontend tool handler already running completes, but its result doesn't trigger
   a re-run.
 - An **open confirmation card is declined** (`data-resolved="declined"`) — cancelling the run
-  answers the pending question.
+  answers the pending question. Likewise an open **approval card** is denied and an open
+  **question card** (`ask_user`) resolves with an empty answer.
 - The new `onCancelled()` handler fires instead of `onError()`; `onSettled()` still follows
   (the terminal-rest guarantee), returning the button to **Send**.
 
@@ -308,6 +309,73 @@ chat.registerTool({
 });
 ```
 
+The confirmation card gates **client-registered** tools *before* they run. A **server-side**
+tool runs on the server, so the browser can't intercept it the same way — that is what the
+approval card below is for.
+
+### Server-side tool approval (interrupts)
+
+When the server gates a destructive tool (e.g. django-ag-ui's `ToolGuard`), the tool **defers**
+instead of executing and the run finishes on an AG-UI *interrupt*. The element then appends an
+**inline approval card** (a `<div class="approval">`) via
+[`requestApproval`](src/ui/approval_card.ts), next to the pending tool-call card:
+
+- **Approve** → the run resumes and the server runs the tool; its result streams back into the
+  same card.
+- **Deny** → the run resumes carrying a `cancelled` answer, so the model learns the tool was
+  declined; the pending card settles as declined.
+
+This uses the AG-UI protocol's own interrupt/resume mechanism (`RunAgentInput.resume[]`) — the
+wire stays vanilla AG-UI. A **Stop** while an approval card is open denies every open card and
+cancels the run. No configuration is needed on the client; the gate is enabled server-side.
+
+Like the question card, the approval card is customizable at three levels: **text** (`strings`:
+`approveAction` / `approvalPrompt` / `approve` / `deny`), **CSS** (`::part()`: `approval`,
+`approval-body`, `approval-actions`, `approval-button`, `approval-approve`, `approval-deny`), and
+**full replacement** via `chat.approvalRenderer` — given the request (`message` + `toolName`) and
+a Stop `AbortSignal`, render your own UI and resolve `true`/`false`:
+
+```js
+chat.approvalRenderer = (request, { signal }) =>
+  myConfirmDialog(request.message ?? `Run ${request.toolName}?`, { signal });
+```
+
+### Asking the user a question (`ask_user`)
+
+Set `chat.askUser = true` to offer the agent a built-in `ask_user` frontend tool. When the agent
+calls it, the element renders an **inline question card** (a `<div class="question">`) via
+[`requestQuestion`](src/ui/question_card.ts) and returns the user's answer as the tool result:
+
+```js
+chat.askUser = true; // opt in; off by default so the tool catalog is unchanged otherwise
+```
+
+`ask_user(question, options?, allow_custom?)` renders `options` as radio buttons, adds a free-text
+field when `allow_custom` is set (or when no options are given), and feeds the chosen or typed
+answer back through the normal frontend-tool path — no new protocol. A **Stop** dismisses an open
+question with an empty answer.
+
+The question card is **fully customizable** at three levels:
+
+- **Text** — every label is a `strings` key: `askUserAction` (the card's `aria-label`),
+  `otherOption`, `answerPlaceholder`, `submit`.
+- **CSS** — every element exposes a `::part()`: `question`, `question-body`, `question-options`,
+  `question-choice`, `question-radio`, `question-input`, `question-actions`, `question-button`
+  (plus the `--ag-ui-*` theme variables). No shadow piercing.
+- **Full replacement** — set `chat.askUserRenderer` to own the entire UI. Given the parsed request
+  and an `AbortSignal` (fired on Stop), render anything — a native modal, a framework component —
+  and resolve with the answer (empty string = no answer). The built-in card is bypassed entirely.
+
+```js
+// Level 1+2: restyle the built-in card.
+chat.strings = { submit: "Answer", answerPlaceholder: "Type here…" };
+// ag-ui-chat::part(question) { border-radius: 0; }
+
+// Level 3: replace the card with your own UI.
+chat.askUserRenderer = (request, { signal }) =>
+  myModal.ask(request.question, request.options, { allowCustom: request.allowCustom, signal });
+```
+
 ### DOM-driver and animation primitives
 
 So the agent can visibly drive the host page, the package ships generic, framework-free
@@ -792,14 +860,28 @@ ag-ui-chat::part(tool-card) { font-family: var(--my-mono); }
 
 Available parts: `panel`, `header`, `title`, `icon`, `header-controls`, `header-button`
 (plus `history-button` / `new-button` / `collapse-button` / `theme-toggle`), `messages`,
-`answer` (the per-turn group), `thoughts` (plus `thoughts-toggle` / `thoughts-body`), `message`
-(plus `message-user` / `message-assistant`), `empty`, `pending`, `tool-card`
+`answer` (the per-turn group), `thoughts` (plus `thoughts-toggle` / `thoughts-body` /
+`thoughts-label`), `message`
+(plus `message-user` / `message-assistant`), `empty`, `pending`, `stopped` (the "⏹ Stopped" note),
+`tool-card`
 (plus `tool-card-head` / `-icon` / `-name` / `-status` / `-args` / `-toggle` / `-result`),
 `confirm` (plus `confirm-body` /
-`-args` / `-actions` / `-button` / `-cancel` / `-confirm`), `composer`, `input`, `send`,
-`attach-button`, `voice-button`, `attachment-tray`, `launcher`, `launcher-icon`, and the drawer parts
+`-args` / `-actions` / `-button` / `-cancel` / `-confirm`),
+`approval` (plus `approval-body` / `-actions` / `-button` / `-approve` / `-deny`),
+`question` (plus `question-body` / `-options` / `-choice` / `-choice-text` / `-radio` / `-input` /
+`-actions` / `-button`), `composer`, `input`, `send`,
+`attach-button`, `voice-button`,
+the attachment chips — `attachment-tray` and `attachment-chips` (the read-only chips on sent
+bubbles) with the shared chip parts `attachment-chip` (plus `-icon` / `-name` / `-size` / `-bar` /
+`-bar-fill` / `-retry` / `-remove`),
+the skills UI (`skill-chips`, `skill-chip`, `skill-palette`, `skill-item`, `skill-item-title`,
+`skill-item-desc`, and the missing-placeholder `skill-hint`),
+`launcher`, `launcher-icon`, and the drawer parts
 (`drawer`, `drawer-backdrop`, `drawer-panel`, `drawer-header`, `drawer-title`, `drawer-new`,
-`drawer-list`, `drawer-empty`, `drawer-row`, `drawer-row-select`).
+`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`).
 
 Coarse **slots** let you replace whole regions with your own markup (project light-DOM children
 with a matching `slot=`):