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

package/CHANGELOG.md

@@ -7,6 +7,91 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] — 2026-07-28
+
+### Added
+
+- **Run notices — a muted inline annotation for things the *run* did**, as
+  opposed to work the user asked for. Styleable via the `run-notice`,
+  `run-notice-icon` and `run-notice-text` parts; announced with `role="status"`
+  so a screen reader hears it politely rather than mid-sentence.
+  - **Compaction.** A standard AG-UI `ACTIVITY_SNAPSHOT` with
+    `activityType: "compaction"` (emitted by django-ag-ui 0.26+ when a
+    compaction capability trimmed the history) renders as "earlier turns
+    condensed", with the count. Activity events of any other type pass through
+    untouched, so another producer on that channel isn't mistaken for one.
+  - **Agent skills.** There is no dedicated event: loading a deferred capability
+    *is* an ordinary `load_capability` tool call, which is what reaches the
+    client. It now renders as `Using skill <id>` **instead of** the raw tool
+    card it would otherwise produce.
+
+    ⚠ Not to be confused with the existing `Skill` catalog — that is a *human*
+    affordance (a prompt the user launches from the chip row or `/`-palette).
+    An agent skill is chosen by the model mid-run. Only the latter emits a
+    notice.
+  - **Suppression covers all three paths a card can come from** — the live
+    stream, the client's tool-execution loop, and **restored history** — so a
+    reload shows the same transcript rather than resurrecting the raw
+    `load_capability` card.
+  - A `load_capability` call with **no usable id** falls back to a normal tool
+    card rather than being dropped: a malformed call is still real activity, and
+    hiding it would be worse than showing it plainly.
+- **`onActivity(activityType, content)`** on `AgUiClientHandlers`, forwarding
+  AG-UI activity events to the host element. `COMPACTION_ACTIVITY_TYPE` and
+  `LOAD_CAPABILITY_TOOL` are exported from `constants`.
+- **Two new overridable strings**: `historyCompacted` (token `{count}`) and
+  `usingSkill` (token `{name}`).
+
+## [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
@@ -528,7 +613,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.12.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.14.0...HEAD
+[0.14.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.13.0...v0.14.0
+[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

package/README.md

@@ -48,6 +48,7 @@ No framework, no Django, no admin specifics live here. Downstream consumers (e.g
 - [New chat and collapse](#new-chat-and-collapse)
 - [Tool-call display modes](#tool-call-display-modes)
 - [Markdown rendering](#markdown-rendering)
+- [Run notices: compaction and agent skills](#run-notices-compaction-and-agent-skills)
 - [Skills: prompt chips and slash palette](#skills-prompt-chips-and-slash-palette)
 - [MPA durability: surviving full page reloads](#mpa-durability-surviving-full-page-reloads)
 - [Host seams: the SPA story](#host-seams-the-spa-story)
@@ -191,7 +192,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
@@ -515,6 +518,37 @@ reveal). It honours `prefers-reduced-motion` (collapsing to instant).
 
 ---
 
+## Run notices: compaction and agent skills
+
+Some things a run does are neither text nor a tool the user asked for — the server condensed
+earlier turns to fit the context window, or the model pulled in an agent skill. Those render as
+**run notices**: a muted one-line annotation inline in the transcript, styleable via the
+`run-notice`, `run-notice-icon` and `run-notice-text` `part`s.
+
+> **Two different things are called "skills".**
+> The [prompt chips and slash palette](#skills-prompt-chips-and-slash-palette) below are a
+> **human** affordance — prompts *the user* launches. An **agent skill** is a folder of
+> instructions *the model* chooses to load mid-run. Only the second produces a run notice.
+
+Neither notice needs configuration here — both appear when the server is set up to produce them.
+
+**Compaction.** `django-ag-ui` emits a standard AG-UI `ACTIVITY_SNAPSHOT` with
+`activityType: "compaction"` when a compaction capability trimmed the history; the notice reports
+how many messages went. Server side, that means wrapping the capability in `CompactionObserver` —
+see [django-ag-ui's compaction guide](https://artui.github.io/django-ag-ui/compaction/). Activity
+events of any other type pass through untouched, so another producer on that channel is not
+mistaken for a compaction.
+
+**Agent skills.** There is no dedicated event for these: loading a deferred capability *is* an
+ordinary `load_capability` tool call, which is what reaches the client. The component recognises
+it, renders `Using skill <id>`, and suppresses the raw tool card that would otherwise appear
+beside it — on the live stream and on restored history alike, so a reload shows the same
+transcript. A `load_capability` call with no usable id falls back to a normal tool card rather
+than being dropped, since it is still real activity.
+
+Both strings are overridable like every other — `historyCompacted` (token `{count}`) and
+`usingSkill` (token `{name}`).
+
 ## Skills: prompt chips and slash palette
 
 Skills are pre-defined prompts the user can launch from a chip or the `/`-command palette. They are
@@ -621,12 +655,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)),
@@ -634,6 +668,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
@@ -798,8 +868,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