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

package/CHANGELOG.md

@@ -7,25 +7,120 @@ 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
+
+- **Upload cancellation.** `UploadHandler` gains an optional third argument,
+  `signal: AbortSignal`. Removing a pending chip, clearing the tray, or removing
+  the element now aborts the in-flight upload, so a cancelled transfer no longer
+  orphans a server-side file. Non-breaking: existing two-argument handlers keep
+  working; a custom handler that honours the signal should abort its own
+  transport when it fires.
+- **Teardown on disconnect.** `<ag-ui-chat>` now cleans up when it leaves the
+  DOM (a removed node or a client-side route swap): it cancels the in-flight
+  run so the SSE stream closes, aborts in-flight uploads, and releases the
+  microphone so the browser's recording indicator clears.
+- **Accessible history drawer.** The chat-history drawer is now a proper modal
+  dialog — Escape closes it, focus moves into the panel on open and is restored
+  to the opener on close, Tab is trapped within the panel, and an inline rename
+  commits on blur.
+- **Per-instance storage scoping.** The collapsed / theme / active-thread state
+  and the default thread store are now namespaced by the element's `id` (else
+  its `endpoint`), so two `<ag-ui-chat>` instances — or two apps — on the same
+  origin no longer share state. Pre-existing per-tab state migrates into the
+  namespace automatically on first load.
+
+### Fixed
+
+- **Submit while running.** Pressing Enter during a live run no longer starts a
+  second, concurrent SSE run (which orphaned the first and could corrupt its
+  pending tool cards). Enter now matches the Send/Stop button and is ignored
+  while a run is in flight.
+- **Thread-switch race.** Rapidly switching threads against a slow remote store
+  can no longer interleave two replays into one transcript — a stale replay is
+  dropped once a newer switch begins.
+- **Malformed thread responses.** A `200` from the threads endpoint whose body
+  isn't valid JSON (a proxy's HTML error page, a truncated stream) now falls
+  back to the local cache instead of silently failing to load the drawer or
+  history.
+- **Relative timestamps.** An unparseable or missing `updated_at` now renders a
+  neutral "just now" rather than `"NaNw ago"` or `"~2950w ago"`.
+- **Corrupt attachment refs.** Malformed entries in a message's persisted
+  attachments are dropped instead of throwing and aborting the whole history
+  replay.
+- **Retry of a rejected upload.** Retrying a chip that was rejected client-side
+  (oversize / disallowed type) now re-applies the guard instead of uploading the
+  file in full.
+- **Duplicate tool result.** A repeated `TOOL_CALL_RESULT` (or a replayed tool
+  message for an already-settled card) no longer appends a second result
+  section.
+- **Run-error continuation.** A run that ends in an error is now terminal: the
+  loop no longer proceeds into frontend-tool execution or another round, so a
+  failed run can't surface a confusing second error. Pending tool cards still
+  settle.
+
 ## [0.9.0] — 2026-06-30
 
 ### Added
 
-- **Model thoughts (THINK-1).** When the server forwards a reasoning model's
+- **Model thoughts.** When the server forwards a reasoning model's
   chain-of-thought, the element now renders a muted, collapsible **thoughts
   region** (part `thoughts`) at the top of the current answer group — it streams
   while the model reasons and folds away on the answer's first token (the reader
   can reopen it). `AgUiClientHandlers` gains `onReasoningStart` / `onReasoningDelta`
   / `onReasoningEnd`, wired from `@ag-ui/client`'s `REASONING_*` subscriber
   callbacks (which also cover the deprecated `THINKING_*` family).
-- **Voice input (VOICE-1).** Set `data-transcribe-url` (django-ag-ui's
+- **Voice input.** Set `data-transcribe-url` (django-ag-ui's
   `TranscribeView`) to reveal a 🎤 mic button in the composer (part
   `voice-button`): it records via `MediaRecorder`, POSTs the clip, and drops the
   returned transcript into the textarea. A pluggable `transcribeHandler` —
   `(audio: Blob) => Promise<string>` — swaps the transport (a different STT
   endpoint, a Web Speech adapter) and reveals the mic even without the attribute.
   New exports: `transcribeAudio`, `TranscribeOptions`, `TranscribeHandler`.
-- **Built-in theme toggle (THEME-1).** The boolean `data-theme-toggle` attribute
+- **Built-in theme toggle.** The boolean `data-theme-toggle` attribute
   adds an optional light⇄dark toggle to the header (part `theme-toggle`,
   `toggleTheme()`) that flips `theme` and persists per tab. Off by default, so a
   host-supplied switch in `slot="header-actions"` stays unaffected.
@@ -44,7 +139,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Per-turn answer group + opt-in well (WELL-1).** Each assistant turn now
+- **Per-turn answer group + opt-in well.** Each assistant turn now
   renders inside one `.answer` group (part `answer`) that holds its streamed
   text, tool cards, and pending indicator — so a turn that calls tools reads as
   a single answer instead of loose siblings. The group spans the whole
@@ -54,12 +149,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `data-answer-well` attribute to box that group in a bordered, padded "well"
   (themeable via `--ag-ui-well-bg` / `--ag-ui-well-border`); without it the
   layout is the flat stack as before. Pure CSS, turn-scoped, no JS API.
-- **Full-screen page placement (PAGE-1).** New `placement="page"`: a full-bleed
+- **Full-screen page placement.** New `placement="page"`: a full-bleed
   background with the conversation in a centred reading column (default ~820px,
   set via `--ag-ui-content-max-width`). The assistant turn spans the column
   while the user message stays a right-aligned pill — the layout for a dedicated
   chat page (distinct from `full`'s edge-to-edge, left-aligned messages).
-- **Inline tool-display mode + themeable status icons (CARD-1).** New
+- **Inline tool-display mode + themeable status icons.** New
   `data-tool-display="inline"`: the lightest card — a one-line status row (icon
   + summary, no box chrome) with the result behind its own toggle. Every
   tool-call card now leads with a CSS-drawn **status icon** (part
@@ -400,7 +495,9 @@ 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.9.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
 [0.8.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.7.0...v0.8.0

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=`):