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

package/CHANGELOG.md

@@ -7,6 +7,81 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] — 2026-07-27
+
+### Added
+
+- **Resume or fork a run — the checkpoint UI.** With `data-runs-url` pointed at
+  django-ag-ui's run index (`RunsView`, 0.23+), a ⭯ button appears in the header
+  opening a *Continue a run* panel. Type the next turn, pick a row, and the run
+  continues from its last server-side checkpoint — **Resume** to carry on,
+  **Fork** to branch without touching the original. The client half of durable
+  step persistence, whose server half shipped in django-ag-ui 0.20.0.
+  - **Only continuable runs are offered.** The server reports whether a run has
+    a snapshot to seed from; one that never reached a provider-valid boundary
+    has none, so resuming it would start from nothing. Rows show when the run
+    started (id on hover, for correlating with server logs) and mark a branched
+    run so a fork doesn't read as a duplicate of its parent.
+  - **One URL configures three endpoints.** `resume/<id>/` and `fork/<id>/` are
+    siblings of the index — the server mounts all three together — so they are
+    derived rather than configured, and a half-configured set isn't expressible.
+  - **The client contract is structural, not a rule to remember.** Those
+    endpoints require a *fresh run id* and *only the new turn*, because the
+    server supplies prior turns from the snapshot and re-sending them would
+    duplicate the conversation. A continuation therefore runs on its own
+    short-lived agent, pointed at the resume endpoint and seeded with **no**
+    history — so the new turn is the only thing it *can* send, the fresh run id
+    comes free, and the main agent's history is never touched.
+  - A resumed run is otherwise a normal run: frontend tools execute, approval
+    interrupts render, and `headers` are re-read per request so a rotated
+    token still reaches the endpoint. An unreachable index shows the panel's
+    empty state rather than an error.
+  - New exports: `RunIndex` / `RunRow`, `CheckpointMenu` / `CheckpointVerb`, and
+    five UI strings (`checkpoints`, `noCheckpoints`, `resumeRun`, `forkRun`,
+    `forkedRun`) for localization.
+
+## [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 +528,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.10.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.11.0...v0.12.0
+[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

@@ -155,6 +155,7 @@ That's the whole integration: an `endpoint` attribute pointing at your AG-UI ser
 | `data-skills-url` | — | URL of a JSON skill catalog (fetched with `headers`). |
 | `data-tools-url` | — | URL of a server tool-label catalog (`[{ name, summary, description? }]`), fetched with `headers`; labels tool-call cards for server-side tools. |
 | `data-threads-url` | — | URL of a server thread index (django-ag-ui's `ThreadsView`); enables durable, cross-device chat history. |
+| `data-runs-url` | — | URL of a server run index (django-ag-ui's `RunsView`); reveals the header's ⭯ *Continue a run* panel. See [Resuming a run](#resuming-a-run). |
 | `data-attachments-url` | — | URL of the file-upload endpoint (django-ag-ui's `AttachmentsView`); reveals the composer's 📎 picker + drag-and-drop. |
 | `data-attachment-accept` | — | `<input accept>` list for client-side type filtering (e.g. `image/*,.pdf`). The server stays authoritative. |
 | `data-attachment-max-bytes` | — | Client-side upload size cap in bytes (default 10 MiB; `0` disables). The server stays authoritative. |
@@ -171,7 +172,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 +235,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 +310,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
@@ -578,6 +647,56 @@ chat.navigate = (path) => router.push(path); // SPA: in-page, no reload
 
 Route map + `navigate()` and the reload model are the same feature seen from two ends.
 
+## Resuming a run
+
+When the server persists run checkpoints (django-ag-ui's `step_store`), a run
+that stopped part-way can be **continued** rather than restarted. Point the
+component at the run index and a ⭯ button appears in the header:
+
+```html
+<ag-ui-chat endpoint="/agent/" data-runs-url="/agent/runs/"></ag-ui-chat>
+```
+
+The panel lists runs the server marked **continuable** — those with a saved
+snapshot to seed from. A run that never reached a provider-valid boundary has
+none, so it isn't offered: resuming it would start from nothing. Each row shows
+when the run started (the id is on hover, for correlating with server logs) and
+marks a run that branched from another, so a fork doesn't read as a duplicate
+of its parent.
+
+Type the next turn in the composer, then pick a row:
+
+- **Resume** — continue that run.
+- **Fork** — branch it, leaving the original untouched.
+
+Both send to the matching server endpoint and stream into the same transcript.
+
+### One URL, three endpoints
+
+`data-runs-url` is the only thing to configure. `resume/<id>/` and `fork/<id>/`
+are siblings of the index — django-ag-ui mounts all three under one prefix
+whenever a step store is set — so they're derived, and there's no way to end up
+with a half-configured set.
+
+### The client contract, handled for you
+
+Those endpoints expect a request carrying a **fresh run id** and **only the new
+turn**: the server supplies the prior turns from the snapshot, so re-sending
+them would duplicate the conversation.
+
+The component satisfies that structurally rather than by remembering a rule. A
+continuation runs on its own short-lived agent, built pointing at the resume
+endpoint and seeded with **no** history — so "only the new turn" is the only
+thing it *can* send, and the fresh run id comes free because a new agent mints
+one. Your main agent's history is never touched.
+
+A resumed run is a normal run in every other respect: frontend tools execute,
+approval interrupts render their card, and `headers` are re-read per request so
+a rotated CSRF token or JWT still reaches the endpoint.
+
+If the index can't be reached, the panel shows its empty state rather than an
+error — a history affordance that fails is empty, not broken.
+
 ## File uploads
 
 Set **`data-attachments-url`** (django-ag-ui's `AttachmentsView`) to let the user attach files
@@ -692,6 +811,10 @@ re-export point. Internal modules import from leaf paths.
 | `ClientConversationStore` | type | The persistence seam. |
 | `ThreadMeta` | type | A thread-drawer row (`{ threadId, title, updatedAt, preview }`). |
 | `NavigationCheckpoint` | type | The pre-reload checkpoint marker. |
+| `RunIndex` | class | Reads a `data-runs-url` run index and derives its resume / fork endpoints. |
+| `RunRow` | type | One run index row (`{ run_id, thread_id, parent_run_id, started_at, continuable }`). |
+| `CheckpointMenu` | class | The *Continue a run* panel. |
+| `CheckpointVerb` | type | `"resume" | "fork"`. |
 
 ### Attachments
 
@@ -792,14 +915,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=`):