@useago/sdk 1.5.6 → 1.7.1

package/CHANGELOG.md

@@ -5,6 +5,239 @@ All notable changes to `@useago/sdk` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.1] - 2026-08-10
+
+### Fixed
+
+- The `setPageState` function synthesized by `registerPageStateFunction` /
+  `useAgoPageState` now sends an explicit `required: []` in its parameter
+  schema. Backends that treat a missing `required` array as "every property is
+  required" forced the agent to set all controls on every call; controls are
+  optional, and the agent sets only the ones the user asked for.
+
+## [1.7.0] - 2026-08-07
+
+### Added
+
+- `registerPageStateFunction` / `useAgoPageState` accept a `data` source, so the
+  agent gets back **what the page displays** as the result of its own
+  `setPageState` call instead of only as context on the next message. An agent
+  that filters a list can now say what it found.
+
+  ```ts
+  useAgoPageState(controls, {
+    data: {
+      description: "The users matching the current filters.",
+      get: () => users ?? [],
+      isLoading: () => isFetching, // isFetching, not isLoading
+    },
+  });
+  ```
+
+  `setPageState` then returns `{ success, applied, data }`. Declaring `data`
+  also registers a read-only `readPageData` companion (no parameters, changes
+  nothing, returns `{ data }`) for "what's on screen?" questions; it is removed
+  by `unregisterPageStateFunction`.
+- The SDK waits for the work a control change triggered before reading the
+  snapshot. Two ways to tell it when that work is done:
+  - **`get()` returns a promise** (preferred): awaiting it *is* the completion
+    signal, so the SDK is exact. `get: () => queryClient.ensureQueryData({...})`
+    shares the single in-flight request with the UI.
+  - **`isLoading` is declared**: the SDK polls it every 50 ms and treats two
+    consecutive idle readings as settled. A heuristic, and a flag raised more
+    than ~100 ms after the change (a debounced fetch) is missed, so the agent
+    reads the previous rows.
+
+  Both are capped by `settleTimeoutMs` (10 s by default); a promise that never
+  settles no longer holds the turn open, and a rejected `get()` is reported to
+  the agent as a failed read instead of an empty page.
+- Oversized snapshots are truncated **by item**: the first whole items that fit
+  the budget (`data.maxResultBytes`, defaulting to `maxFunctionResultBytes`) plus
+  a `truncation` field carrying `{ truncated, returnedItems, totalItems, hint }`.
+  The counts are nested so they cannot overwrite a same-named field of your own
+  snapshot. `success` and `applied` are never dropped, so a filter that worked is
+  never reported as an unusable blob. When the snapshot's other fields overflow
+  on their own, it falls back to a size-bounded preview rather than returning
+  something over the ceiling.
+- A `readPageData` companion is only removed by the SDK if the SDK registered it,
+  so a host app that already has a function by that name keeps it, and
+  re-registering a page-state function without `data` drops the stale companion
+  instead of letting it answer with the previous page's rows.
+- `AgoPageDataSource` is exported from the root, `/react`, `/vue` and `/angular`
+  entries.
+- `<ChatWidget>` now says **what the agent is doing** while it works, instead of
+  three dots. While a client function is running it shows a status row naming it
+  ("Updating the page", "Looking up prices"), which matters most during a
+  pause/resume loop: the per-message dots disappear as soon as the first token
+  lands, so a tool pause after some text had been written showed nothing at all.
+
+  ```tsx
+  <ChatWidget functionLabels={{ lookupFlavorPrices: "Je regarde les prix" }} />
+  ```
+
+  The row shows the latest step of the current turn and **keeps it until
+  something replaces it** (another call, a reasoning step) or the turn ends.
+  Clearing it when the call returned made a fast function flash for a few frames
+  and read as nothing at all. The agent's `reasoning` steps are included by
+  default (`showReasoning={false}` to leave them out), so the row does not go
+  blank between two calls.
+
+  `functionLabels` takes a map, or a function `(name, args) => string` for full
+  control. Unmapped names fall back to a prettified function name, so the row
+  works with no configuration. Pass `false` to keep the plain indicator. The row
+  is a `role="status"` live region and is driven by the existing
+  `useAgoActivity` hook, so it covers server-side tool calls and approval holds
+  too. It is scoped to the assistant message being written, so a new turn never
+  opens showing the previous one's last step.
+
+  The label itself is animated: a slow sheen keeps travelling across the text,
+  so a step that sits for several seconds (a fetch, a settle wait) reads as
+  still working rather than stuck, and each new step fades in as its own node so
+  one visibly gives way to the next instead of the characters swapping in place.
+  Colours go through `--ago-activity-color` / `--ago-activity-sheen` /
+  `--ago-activity-bg`; the sheen is behind `@supports (background-clip: text)`
+  and stops under `prefers-reduced-motion`.
+
+  The label carries no animated dots, and the answer bubble above it drops its
+  own while the row is up: the text already reads as progress, and the two
+  together were just noise. `<Message>` takes a `showStreamingDots` prop for
+  the same reason in a custom UI (`false` removes the empty bubble entirely
+  rather than leaving a blank box). It renders simple inline Markdown
+  (`**bold**`, `*italic*`, `` `code` ``) so a backend reasoning step keeps its
+  emphasis; block Markdown is deliberately not supported there, since a
+  paragraph or a table would break a one-line row.
+
+Omit `data` and the result stays exactly `{ success, applied }`, byte for byte.
+The snapshot stays out of the `page-state:` context entry, so it travels only
+when the agent asks for it. The intra-turn round trip requires
+`clientFunctionsMode: "pause"` (the default); the SDK warns once if `data` is
+declared in `"placeholder"` mode.
+
+### Fixed
+
+- Client functions executed on the resume path (after a reload, via
+  `resumePendingClientFunctions`) now emit `function:invoke` and
+  `function:result` like the live stream does. A UI driven by those events used
+  to sit on a spinner for those calls.
+- An agent calling the same client function twice in one turn no longer strands
+  the turn. The per-stream dedupe (which exists because the backend emits one
+  call under two SSE shapes) keyed on function name + arguments alone, so a
+  second call with identical arguments was swallowed: its result was never
+  submitted, the backend never saw every result, and the paused turn stayed in
+  `WAITING_CLIENT` forever. It now uses the invocation id to tell a repeat call
+  apart from a repeat *emission* of the same call. Zero-argument functions (such
+  as the new `readPageData`) hit this every time.
+- Vue's `useAgoPageState` no longer drops `requiresApproval` (and now forwards
+  every option, matching React and Angular).
+
+## [1.6.2] - 2026-08-06
+
+### Fixed
+
+- Side-placement panels (`placement: "left" | "right"`) now get the mobile
+  treatment the inline card already had. On a small viewport the open panel
+  tracks the visible viewport, so the on-screen keyboard no longer covers the
+  composer, and it is exposed as a real dialog (`role="dialog"`, `aria-modal`,
+  Tab trap, Escape to close). Opening it moves focus into the panel rather than
+  the text field, so the keyboard no longer opens unprompted.
+- A desktop side panel is explicitly **not** modal: it no longer traps Tab or
+  locks the page behind it, so the host page stays usable beside it.
+- The background scroll lock now restores the host page's own inline `<body>` /
+  `<html>` styles instead of deleting them. A host that had already pinned its
+  own body (for its own modal) is left exactly as it was found.
+- The scroll lock is tracked per owner instead of by a counter, so overlapping
+  open / close / destroy paths can no longer release a lock they don't hold,
+  and `destroy()` is idempotent.
+- `destroy()` during an opening animation no longer re-pins the page after
+  teardown, which could leave `<body>` fixed with no owner left to release it.
+- `destroy()` now drops its keydown and `visualViewport` listeners for every
+  placement; side-placement widgets previously leaked them.
+- A phone in landscape (short viewport, e.g. 844x390) now counts as mobile, so
+  it keeps the full-screen sheet and the keyboard handling instead of falling
+  back to the desktop layout mid-conversation.
+- A streamed answer no longer rebuilds the whole thread on every token. Screen
+  readers announced the entire conversation per chunk, and the rebuild collapsed
+  the pane's scroll height, which is what made a "follow the bottom" check latch
+  off after the first token.
+- The message pane now follows new content only while you are already at the
+  bottom. Scroll up to re-read something and the stream stops yanking you back;
+  a "jump to latest" button returns you. Sending always re-attaches.
+- On a compact viewport the composer is no longer re-focused after every answer,
+  which was re-opening the on-screen keyboard over the reply you were reading.
+- A failed send no longer destroys the message: the text (and any attachments)
+  go back into the composer instead of being lost.
+- Touch targets are at least 44px across both the vanilla widget and the React
+  components: send, stop, attach, remove-attachment, suggested replies, and both
+  close buttons.
+
+### Added
+
+- Bottom-sheet presentation for compact viewports, opt-in via the new `sheet`
+  option on the React `<ChatWidget>`. It rests as a `peek` bar pinned to the
+  bottom edge (named header, two-line preview of the last reply, composer) and
+  expands to a `full` screen with `role="dialog"`, a background scroll lock and
+  Escape to collapse. `peek` is deliberately never modal: the page behind it
+  stays scrollable and keyboard-reachable.
+- `createSheetController` (`@useago/sdk/widget`): the framework-agnostic state
+  machine behind it. It returns a **props bag** rather than touching the DOM, so
+  the React binding, the vanilla widget and any Vue or Angular binding drive the
+  same implementation.
+- `useSheet` (`@useago/sdk/react`), which reads that controller through
+  `useSyncExternalStore` with a non-compact server snapshot, so `matchMedia`
+  never runs during render and hydration matches.
+- `<ChatWidget>` now forwards a ref exposing `expand()`, `collapse()`,
+  `toggle()` and the current `state`.
+- `sheet.bottomOffset` leaves room for a host page that already owns the bottom
+  edge (a bottom nav, a sticky checkout bar). `sheet: false` (the default) keeps
+  the widget out of the host's fixed layers entirely.
+- `thinkingLabel` on `<ChatWidget>`: what the collapsed sheet says next to the
+  animated dots while the agent is working and has produced no text yet.
+- `--ago-sheet-height`: the collapsed sheet measures itself and publishes its
+  footprint as a custom property on the host document. A fixed bar covers the end
+  of the page, so hosts need to reserve that space, and a constant in their CSS
+  would drift from the real height (which depends on their own composer styling).
+  Use it as `padding-bottom: var(--ago-sheet-height, 0px)`.
+
+### Changed
+
+- The streaming dots now paint in `currentColor` instead of a fixed grey, so
+  they stay legible on a dark surface as well as a light one.
+- React `<ChatInput>`'s `onSend` may now return a boolean (or a promise of one).
+  Returning `false` tells the composer the send failed so it can restore the
+  draft. Existing handlers that return nothing keep working unchanged.
+
+## [1.6.1] - 2026-08-05
+
+### Added
+
+- The React `<ChatInput>` textarea now exposes an
+  `ago-chat-input__field` class for stable custom styling.
+
+### Fixed
+
+- React `<ChatWidget>` auto-scroll now stays inside the message pane instead of
+  moving ancestor containers or the whole page, and preserves the reader's
+  position while they review earlier messages.
+
+## [1.6.0] - 2026-08-04
+
+### Added
+
+- Stop generation. `client.stop()` interrupts the turn being generated: it
+  closes the stream and calls the new `POST /api/sdk/v1/messages/{id}/stop`, so
+  the agent really stops instead of finishing in the background. The text
+  produced so far is kept and the message ends as `CANCELED`; the in-flight
+  `sendMessage` resolves with it rather than rejecting.
+- `message:stopped` event, fired once the stopped turn has unwound.
+- `client.stopMessage(messageId)` to stop a turn by id (e.g. one still running
+  after a page reload), and `client.isGenerating()` to know whether there is
+  anything to stop.
+- `stop()` on the React `useMessages` / `useChat` hooks, the Vue `useMessages` /
+  `useChat` composables, the Angular `AgoService`, and the vanilla widget handle.
+- The React `<ChatWidget>` and the vanilla widget now show a Stop button in
+  place of the send button while the agent answers. Opt out with
+  `allowStop: false`.
+
 ## [1.5.6] - 2026-07-29
 
 ### Fixed

package/README.md

@@ -145,6 +145,30 @@ so the agent changes only what the user asked for. The current value from each
 `get()` is sent with every message, so the agent knows the state before it
 changes it. Vue and Angular have the same helper.
 
+Add a `data` source and the agent also gets back **what the page now shows**, as
+the result of its own call, so it can answer "did you find dupont?" in the same
+turn:
+
+```tsx
+const { data: invoices, isFetching } = useQuery({
+  queryKey: ["invoices", status, sort],
+  queryFn: fetchInvoices,
+});
+
+useAgoPageState(controls, {
+  data: {
+    description: "The invoices matching the current filters.",
+    get: () => invoices ?? [],
+    isLoading: () => isFetching,   // isFetching, not isLoading
+  },
+});
+```
+
+The SDK waits for `isLoading` to go false before reading, so the agent never
+receives the previous search's rows, and it truncates a long list by whole rows
+rather than sending a huge payload. Details in
+[functions and context](docs/general/functions-and-context.md#return-what-the-page-displays).
+
 ## Turn a JavaScript function into an agent tool
 
 Keep your application logic as a regular JavaScript function, then describe its
@@ -198,6 +222,41 @@ Whenever the agent calls the tool, the SDK runs your handler in the browser
 with the generated arguments and sends its return value back to the agent. Keep
 the return value small and structured so the agent can use it reliably.
 
+## Let the user stop a long answer
+
+`<ChatWidget>` already does this: while the agent answers, its send button turns
+into a **Stop** button (pass `allowStop={false}` to opt out). In a custom UI, wire
+the `stop` returned by `useChat` / `useMessages`:
+
+```tsx
+import { useChat } from "@useago/sdk/react";
+
+function Chat() {
+  const { messages, sendMessage, stop, isLoading } = useChat();
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <p key={m.id}><b>{m.role}:</b> {m.content}</p>
+      ))}
+      {isLoading ? (
+        <button onClick={() => void stop()}>Stop</button>
+      ) : (
+        <button onClick={() => sendMessage("Write me a long report")}>Send</button>
+      )}
+    </div>
+  );
+}
+```
+
+Stopping closes the stream **and** tells the backend to stop generating. Closing
+the stream alone would not stop the agent: it would keep running and the full
+answer would reappear on the next load. The text already produced stays on
+screen, the message ends as `CANCELED`, and the pending `sendMessage` resolves
+with that partial message instead of rejecting. Vue and Angular have the same
+`stop`, and the vanilla `mountChatWidget` handle gained `stop()`. Details in
+[Stop the answer](docs/general/core.md#stop-the-answer).
+
 ## Show the source docs the agent retrieved
 
 Each assistant message carries the knowledge sources it used in `m.sources`