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

package/CHANGELOG.md

@@ -7,6 +7,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] — 2026-07-27
+
+### Added
+
+- **AG-UI shared state.** `<ag-ui-chat>` now speaks the protocol's own state
+  channel: assign `chat.sharedState = {...}` to seed it, listen for the
+  `ag-ui-state` event (`detail.state`) to react when the agent changes it.
+  State rides `RunAgentInput.state` on every run and is replaced in place when
+  the server streams `STATE_SNAPSHOT` / `STATE_DELTA`.
+  - **Adoption, not implementation.** `@ag-ui/client` already applies both
+    events to `agent.state` and exposes an `onStateChanged` subscriber hook;
+    what was missing was seeding it (`initialState`) and surfacing it to the
+    host. Deriving state from the raw event stream ourselves would have
+    duplicated — and eventually contradicted — the client's own handling,
+    including its JSON-Patch delta application.
+  - Assigning **after** the conversation has started pushes through to the live
+    agent rather than waiting for a new one, so a host that seeds state late
+    isn't silently stranded.
+  - The event is `composed: true`, so a host listening on `document` receives it
+    through the shadow boundary.
+  - **Distinct from `registerPageState`**, which exposes host state to the agent
+    as ordinary *tools*. Use shared state when agent and page edit the same
+    object; use page-state tools when the agent should *ask* — a tool call is
+    visible in the transcript and can be gated by a confirmation card, which
+    state events cannot.
+
+### Changed
+
+- **`registerStateHook` is now `registerPageState`** (and `createStateHookTools` /
+  `StateHook` are `createPageStateTools` / `PageState`). **The old names implied a
+  feature that does not exist**: they read as AG-UI shared-state sync —
+  `STATE_SNAPSHOT` / `STATE_DELTA`, the protocol events that carry a state object
+  between agent and client — which neither this component nor `django-ag-ui`
+  implements. What the method actually does is generate two ordinary client tools
+  (`read_<name>` / `set_<name>`) over host page state, which the agent calls like
+  any other tool. `page` matches the vocabulary already used throughout the
+  component (`page_map`, `page_action_tools`, `route_map`, the DOM driver).
+  - **Not a hard break.** The old spellings are kept as deprecated aliases and
+    behave identically; they will be removed in a future major. A rename is only
+    ever cheaper the earlier it happens, which is why this ships now rather than
+    waiting for state support to exist.
+
+### Documentation
+
+- **The README now distinguishes the two state mechanisms**, which the old
+  method name conflated. `sharedState` is the protocol's state channel;
+  `registerPageState` generates ordinary client tools. The rename and the
+  feature landed together, so the docs answer "which one" rather than leaving
+  two similar names side by side.
+
+## [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
@@ -495,7 +578,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.11.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.13.0...HEAD
+[0.13.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.12.0...v0.13.0
+[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

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. |
@@ -190,7 +191,9 @@ the django-ag-ui `@tool` registry), whose schema never reaches the browser — e
 labels are fetched automatically — per card, `x-summary` → an explicit
 `toolSummaries` entry → the fetched catalog → the raw name.
 
-**Methods**: `registerTool`, `registerStateHook`, `setSkills`, `appendMessage`, `newChat`,
+**Properties** (selected): `sharedState` — AG-UI shared state (documented under Tools & state).
+
+**Methods**: `registerTool`, `registerPageState`, `setSkills`, `appendMessage`, `newChat`,
 `setCollapsed`, `toggleCollapsed`.
 
 A self-contained live playground lives in [`demo/`](demo/) — run `make demo` to serve it against a
@@ -620,12 +623,12 @@ so it reflects the page the agent is currently looking at:
 chat.getPageMap = () => ({ fields: introspectForm(), buttons: visibleButtons() });
 ```
 
-**`registerStateHook({ name, read, write?, schema? })`** — ergonomic sugar over `registerTool` for
+**`registerPageState({ name, read, write?, schema? })`** — ergonomic sugar over `registerTool` for
 SPA app state (Redux/Zustand/signals). It auto-generates a `read_<name>` (read-only) tool and, when
 `write` is supplied, a `set_<name>` tool stamped `x-destructive`:
 
 ```js
-chat.registerStateHook({
+chat.registerPageState({
   name: "cart",
   read: () => store.getState().cart,
   write: ({ items }) => store.dispatch(setCart(items)),
@@ -633,6 +636,42 @@ chat.registerStateHook({
 });
 ```
 
+**This is not AG-UI shared state** — that is `sharedState`, below. `registerPageState` generates two
+ordinary client tools; the agent reads or writes your store by *calling a tool*. The method was
+called `registerStateHook` through 0.12, a name that read as protocol state sync; the old spelling
+still works and is deprecated.
+
+**`sharedState`** *(property)* — AG-UI **shared state**: the protocol's own state channel, sent as
+`RunAgentInput.state` on every run and replaced in place when the server streams `STATE_SNAPSHOT` /
+`STATE_DELTA`. Assign to seed it, listen for `ag-ui-state` to react:
+
+```js
+chat.sharedState = { document: "" };
+
+chat.addEventListener("ag-ui-state", (e) => {
+  editor.value = e.detail.state.document;   // the agent rewrote it
+});
+```
+
+Server-side, a tool mutates `ctx.deps.state` and returns the snapshot as `ToolReturn` metadata —
+pydantic-ai does not emit deltas for you:
+
+```python
+@tool(registry)
+async def write_document(ctx: RunContext[AgentDeps], body: str) -> ToolReturn:
+    """Replace the shared document."""
+    ctx.deps.state = {**(ctx.deps.state or {}), "document": body}
+    return ToolReturn(
+        return_value="written",
+        metadata=[StateSnapshotEvent(type=EventType.STATE_SNAPSHOT, snapshot=ctx.deps.state)],
+    )
+```
+
+Use this when the agent and the page are editing **the same object** (a document, a form, a
+canvas). Use `registerPageState` when the agent should *ask* for a value or *request* a change —
+the tool call is visible in the transcript and can be gated by a confirmation card, which state
+events cannot.
+
 **`navigate(path): void`** *(optional)* — a host routing callback. **This single seam is what
 distinguishes an SPA from an MPA.** When set, `navigate_to_route` routes client-side (no reload) and
 the in-memory run loop simply continues — the whole resumable-loop / checkpoint machinery is
@@ -646,6 +685,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
@@ -747,8 +836,8 @@ re-export point. Internal modules import from leaf paths.
 | `RouteWithParams` | type | A route resolved with `:param` path segments + leftover query params. |
 | `createPageMapContext(...)` | function | Build the per-run `page_map` context entry. |
 | `PageMap` | type | The compact page-surface shape. |
-| `createStateHookTools(hook)` | function | Build `read_<name>` / `set_<name>` tools. |
-| `StateHook` | type | A state-binding declaration. |
+| `createPageStateTools(binding)` | function | Build `read_<name>` / `set_<name>` tools. |
+| `PageState` | type | A page-state binding declaration. |
 | `Skill` | type | A launchable prompt (chip / `/`-command). |
 
 ### Durability
@@ -760,6 +849,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