@helpai/elements 1.9.0 → 1.11.0

package/docs/README.md

@@ -41,6 +41,7 @@ Get the public key and deployment ID from [help.ai](https://help.ai) →
 | Wire GA4 / Mixpanel / Segment / multi-provider              | [Analytics integration](./analytics.md)       |
 | Integrate with Next.js / Vue / Svelte / WordPress / Shopify | [Framework integrations](./frameworks.md)     |
 | Copy a working example                                      | [Recipes](./recipes.md)                       |
+| Let the AI agent act on my page                             | [Page tools](./page-tools.md)                 |
 | Diagnose "why isn't this working"                           | [Troubleshooting](./troubleshooting.md)       |
 | Quick answer to a common question                           | [FAQ](./faq.md)                               |
 | Compact API reference for lookup                            | [API reference](./api-reference.md)           |

package/docs/analytics.md

@@ -78,6 +78,7 @@ via `chat.on(name, fn)` (instance) or `HelpAI.hook(widgetId, name, fn)`
 |                  | `soundToggle`         | `{ muted }`                                        |
 |                  | `sidebarToggle`       | `{ collapsed }` (page mode)                        |
 |                  | `calloutDismiss`      | `void`                                             |
+| **Your page**    | `hostEvent`           | `{ name, data? }` (from `chat.track()`)            |
 | **Lifecycle**    | `error`               | `unknown` (any unhandled error)                    |
 |                  | `handshake`           | `HandshakeResponse` (full handshake payload)       |
 |                  | `conversationRebound` | `{ previous, current }`                            |
@@ -392,6 +393,32 @@ chat.on('close', () => {
 
 ## Common patterns
 
+### Your own events (`chat.track`)
+
+Report what the visitor does on your site, outside the chat, with `chat.track(name, data)`:
+
+```ts
+chat.track('plan_viewed', { plan: 'pro' });
+chat.track('cart_updated', { items: 2, total: 48.5 });
+```
+
+Each call does two things:
+
+- **Analytics.** It sends one hit to help.ai's Elements analytics as a `hostEvent`, with your event name and data,
+  like the widget's own events. A deployment with tracking off (or a browser sending Global Privacy Control or Do
+  Not Track) sends nothing.
+- **The agent.** The widget keeps your last 10 events and sends them with the visitor's next message, as
+  `recentEvents` in the page context (`{ name, data?, secondsAgo }`, oldest first), so an answer can take into
+  account what the visitor just did: "I see you were looking at the Pro plan." Like the rest of the page context, the
+  agent treats them as information from your site, never as instructions. They live only in this page view.
+
+The name is 1–64 characters. The data is flat: strings, numbers and booleans (other values are left out), up to 256
+characters as JSON (longer data is not sent; the name still is). Nothing personal should go in either: use ids and
+plan names, not emails. `track()` also fires the `hostEvent` event, so your own listeners see it.
+
+Also `HelpAI('track', name, data)` with the script tag, `element.track(name, data)` on `<web-ai-chat>`, and
+`useHelpAI().track` in React.
+
 ### Identify the visitor
 
 The widget mints a stable anonymous `visitorId` on first load and

package/docs/api-reference.md

@@ -46,7 +46,8 @@ React kit (React 18+; everything above plus the component and the hook, so impor
 ```ts
 import {
   HelpAI, // <HelpAI {...options} /> mounts the widget, re-configures it on prop changes, removes it on unmount
-  useHelpAI, // useHelpAI(widgetId?) → { state, ask, open, close, reset }, re-rendering on state changes
+  useHelpAI, // useHelpAI(widgetId?) → { state, ask, open, close, reset, track }, re-rendering on state changes
+  useHelpAITool, // useHelpAITool(tool) gives the agent a page tool while the component is mounted
   type HelpAIProps,
   type HelpAIControls,
 } from '@helpai/elements/react';
@@ -139,13 +140,16 @@ interface ChatWidgetInstance {
 
   // Lifecycle
   reset(): void; // start over as a new anonymous visitor (on logout)
+  login(userToken: UserTokenSource): void; // sign the visitor in as your logged-in user (a signed token, or a function returning one)
+  track(name: string, data?: Record<string, string | number | boolean>): void; // report your page's own event: analytics + the agent's next message
+  registerTool(tool: ModelContextTool, options?: { signal?: AbortSignal }): void; // a tool the agent can use on this page, for every widget on it
   destroy(): void;
 
   // Events
   on<E extends EventName>(name: E, fn: (payload: EventMap[E]) => void): () => void; // returns unsubscribe fn
 
   // Re-config
-  update(patch: Partial<ChatWidgetOptions>): void;
+  update(patch: Partial<ChatWidgetOptions>): void; // e.g. update({ tools }) on a route change
 
   // Host-asserted context (informational, not auth; re-handshakes, same visitor/conversation)
   setUserContext(ctx: Partial<NonNullable<ChatWidgetOptions['userContext']>>): void; // merges into the current user context
@@ -207,6 +211,29 @@ init({
 The complete type also exposes `features`, `forms`, `modules`, and `tracking`.
 See [Configuration](./configuration.md) for behavior and examples.
 
+### `ModelContextTool`
+
+A tool the agent can use on your page, in the WebMCP tool shape ([Page tools](./page-tools.md)). On `<web-ai-chat>`
+it's the `tools` property or `registerTool()`, since functions can't be attributes.
+
+```ts
+interface ModelContextTool<TInput = unknown> {
+  name: string; // letters, digits, `_` and `-` (58 at most; others become `_`); the agent sees `site__<name>`
+  title?: string;
+  description: string; // when to use it (1024 characters at most)
+  inputSchema?: Record<string, unknown>; // JSON Schema of an object; none = no input
+  annotations?: ToolAnnotations; // `consequentialHint: true` = the visitor approves each call first
+  execute(input: TInput, options: { signal: AbortSignal }): unknown; // a JSON result, or throw; `signal` aborts when the visitor moves on
+}
+
+interface ToolAnnotations {
+  readOnlyHint?: boolean;
+  untrustedContentHint?: boolean;
+  consequentialHint?: boolean;
+  debugging?: boolean;
+}
+```
+
 ### `ActionName`
 
 ```ts
@@ -332,6 +359,46 @@ visitor, their current conversation (draft and queued messages included), prefer
 `setUserContext`, then reconnects as a first visit. Listeners added with `on()` stay, and the handle keeps working.
 On `<web-ai-chat>`, also remove a `user-context` attribute you set.
 
+### `login(userToken)`
+
+Signs the visitor in as your logged-in user. `userToken` is a JWT your server signs with the deployment's secret key,
+or a function returning a fresh one (called again when the server rejects the current token as expired). The widget
+reconnects as that user: their conversations on this browser move to them, and they reach their conversations on any
+device where they're signed in. Call `reset()` when they sign out; switching to another user's token starts over the
+same way. Also `HelpAI('login', userToken)`, `element.login(userToken)` on `<web-ai-chat>` (not an attribute, so the
+token stays out of the DOM), the `userToken` option at `init()`, and `<HelpAI userToken={…} />`. Signing and the
+guarantees: [Security → Verified users](./security-privacy.md#verified-users-usertoken).
+
+```ts
+chat.login(() => fetch('/api/help-ai-token').then((res) => res.text()));
+```
+
+---
+
+### `registerTool(tool, options?)`
+
+Gives the agent a tool on this page, for every widget on it: the latest registration of a name wins, and aborting
+`options.signal` removes it. Also `HelpAI('registerTool', tool)` (queued before the script loads),
+`element.registerTool(tool)` and the React kit's `useHelpAITool(tool)`. Details: [Page tools](./page-tools.md).
+
+```ts
+chat.registerTool({ name: 'open_booking', description: 'Open the booking form. Use it whenever the visitor wants to book a call.', execute: () => bookingForm.open() });
+```
+
+---
+
+### `track(name, data?)`
+
+Reports something the visitor did on your site, outside the chat. It sends a `hostEvent` hit to Elements analytics
+(not when tracking is off), and the widget keeps the last 10 for the agent, which reads them with the visitor's next
+message. The name is 1–64 characters; the data is flat (strings, numbers, booleans; 256 characters of JSON at most).
+Also `HelpAI('track', name, data)`, `element.track(name, data)` and `useHelpAI().track`. Details:
+[Analytics → Your own events](./analytics.md#your-own-events-chattrack).
+
+```ts
+chat.track('plan_viewed', { plan: 'pro' });
+```
+
 ---
 
 ## Events

package/docs/configuration.md

@@ -102,6 +102,37 @@ Override if you use:
 - A custom domain (`your-company.com`).
 - A local dev backend.
 
+### `userToken`
+
+`string | () => string | Promise<string>` · default: none (anonymous)
+
+Signs the visitor in as your logged-in user: a JWT your server signs with the deployment's secret key, or a function
+returning a fresh one. Their conversations then follow them to any device, and the AI gets their name and email as
+verified facts. Runtime-only: not an attribute or `data-*` option, so the token stays out of the page's markup. See
+[Security → Verified users](./security-privacy.md#verified-users-usertoken) for signing it.
+
+```ts
+init({ publicKey: 'agent_pk_...', aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000', userToken: () => fetch('/api/help-ai-token').then((res) => res.text()) });
+```
+
+### `tools`
+
+`ModelContextTool[]` · default: none
+
+Tools the AI agent can use on your page, in the WebMCP tool shape: a name, a description, a JSON Schema of its input
+and an `execute` function the widget runs in the visitor's browser when the agent calls it
+(`annotations: { consequentialHint: true }` asks the visitor first). Runtime-only, like `userToken`;
+`chat.update({ tools })` replaces them. `chat.registerTool(tool)` adds one for every widget on the page instead. Full
+guide: [Page tools](./page-tools.md).
+
+```ts
+init({
+  publicKey: 'agent_pk_...',
+  aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000',
+  tools: [{ name: 'open_booking', description: 'Open the booking form. Use it whenever the visitor wants to book a call.', execute: () => (bookingForm.open(), { opened: true }) }],
+});
+```
+
 ### `userContext`
 
 `object | undefined`

package/docs/events-and-hooks.md

@@ -18,17 +18,19 @@ Both deliver the same event stream. Both are safe to mix.
 
 ## Available events
 
-| Event             | Fires on                                          | Payload                                                |
-| ----------------- | ------------------------------------------------- | ------------------------------------------------------ |
-| `open`            | Panel opens (floating mode)                       | `void`                                                 |
-| `close`           | Panel closes                                      | `void`                                                 |
-| `message`         | User sends a message + assistant finishes a reply | `{ role: "user" \| "assistant"; text: string }`        |
-| `error`           | Transport error or mid-stream error               | `unknown` (error object or message)                    |
-| `expand`          | Expanded tier toggled (⤢)                         | `boolean` (new state)                                  |
-| `fullscreen`      | Fullscreen tier toggled (⛶)                       | `boolean` (new state)                                  |
-| `handshake`       | Widget finishes booting (once per mount)          | `HandshakeResponse` (dashboard config)                 |
-| `localeChange`    | User picks a different language                   | `string` (new BCP-47 tag)                              |
-| `messageFeedback` | User rates a reply 👍/👎 (or clears it)           | `{ messageId: string; value: "up" \| "down" \| null }` |
+| Event             | Fires on                                                                            | Payload                                                                                                                                    |
+| ----------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `open`            | Panel opens (floating mode)                                                         | `void`                                                                                                                                     |
+| `close`           | Panel closes                                                                        | `void`                                                                                                                                     |
+| `message`         | User sends a message + assistant finishes a reply                                   | `{ role: "user" \| "assistant"; text: string }`                                                                                            |
+| `error`           | Transport error or mid-stream error                                                 | `unknown` (error object or message)                                                                                                        |
+| `expand`          | Expanded tier toggled (⤢)                                                           | `boolean` (new state)                                                                                                                      |
+| `fullscreen`      | Fullscreen tier toggled (⛶)                                                         | `boolean` (new state)                                                                                                                      |
+| `handshake`       | Widget finishes booting (once per mount)                                            | `HandshakeResponse` (dashboard config)                                                                                                     |
+| `localeChange`    | User picks a different language                                                     | `string` (new BCP-47 tag)                                                                                                                  |
+| `messageFeedback` | User rates a reply 👍/👎 (or clears it)                                             | `{ messageId: string; value: "up" \| "down" \| null }`                                                                                     |
+| `hostEvent`       | Your page calls `chat.track(name, data)`                                            | `{ name: string; data?: Record<string, scalar> }`                                                                                          |
+| `toolResult`      | A [page tool](./page-tools.md) call settles, or the visitor answers a question card | `{ toolCallId: string; name?: string; status?: "completed" \| "failed" \| "declined" \| "stopped" \| "interrupted"; durationMs?: number }` |
 
 ---
 

package/docs/frameworks.md

@@ -89,7 +89,7 @@ function PricingHelp() {
   required. It renders nothing itself: the widget mounts once the page is in the browser, a prop change re-configures
   the live widget without a remount, and unmounting removes it. Callback props (`onOpen`, `onMessage`, …) can be new
   functions on every render; the widget always calls the latest one.
-- **`useHelpAI(widgetId?)`** returns `{ state, ask, open, close, reset }`. `state` is
+- **`useHelpAI(widgetId?)`** returns `{ state, ask, open, close, reset, track }`. `state` is
   [`{ open, ready, unread, conversationId? }`](./api-reference.md#state-and-ready) and re-renders the component when it changes;
   the server render sees the initial state. The commands are stable across renders and do nothing until the widget
   has mounted (`state.ready`). `ask(text)` fills the composer; `ask(text, { send: true })` sends it. Call `reset()`
@@ -97,6 +97,12 @@ function PricingHelp() {
 - **One import path.** The kit carries the whole widget API (`getInstance`, `hook`, the types), so import everything
   from `@helpai/elements/react`; the package's other entries are separate copies with their own widgets.
 - **Two widgets** on one page: give each `<HelpAI widgetId='support' … />` and read it with `useHelpAI('support')`.
+- **Page tools:** `useHelpAITool(tool)` gives the agent a tool while the component is mounted, or pass
+  `<HelpAI tools={[...]} />` ([Page tools](./page-tools.md)). `execute` can be a new function on every render; the
+  agent's call runs the latest one, and only a changed definition registers or configures anything again.
+- **Signed-in users:** pass `userToken`, a function that fetches the token your server signs
+  ([Verified users](./security-privacy.md#verified-users-usertoken)). Keep it stable for one user (a module function, or
+  `useCallback` keyed on your user id): a different function signs in afresh, and dropping it signs out.
 
 The kit bundles the widget and imports only React from your app, so you don't need Preact installed.
 

package/docs/page-tools.md

@@ -0,0 +1,194 @@
+# Page tools
+
+Give the AI agent tools that act on your own page: open your booking form, read the visitor's cart, jump to a
+section, fill in a form. You describe each tool and write its function; the agent decides when to call it, the
+widget runs the function in the visitor's browser, and the agent continues the conversation with what it returned.
+Every page can offer different tools, so the agent can do on each page what that page is for.
+
+A tool has the [WebMCP](https://webmachinelearning.github.io/webmcp/) shape (the W3C draft for tools a web page
+offers to AI agents), so a tool you write for the widget also works with a browser's own WebMCP support, and the
+other way round.
+
+```ts
+chat.registerTool({
+  name: 'open_booking',
+  description: 'Open the booking form on this page for a meeting type. Use it whenever the visitor wants to book a call.',
+  inputSchema: {
+    type: 'object',
+    properties: { meetingType: { type: 'string', enum: ['sales', 'support'] } },
+    required: ['meetingType'],
+  },
+  execute({ meetingType }) {
+    bookingForm.open(meetingType);
+    return { opened: true };
+  },
+});
+```
+
+A visitor writes "I'd like to talk to sales"; the agent calls `open_booking` with `{ meetingType: 'sales' }`, your
+booking form opens, and the agent answers "The booking form is open, pick a time that suits you."
+
+## Adding tools
+
+| Where you are    | How                                                                                                                          |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Script tag       | `HelpAI('registerTool', tool)`. Works before the widget has loaded: the loader queues it.                                    |
+| npm              | `chat.registerTool(tool, { signal })`, or `init({ tools: [...] })`.                                                          |
+| React            | `useHelpAITool(tool)` in the component that owns the feature, or `<HelpAI tools={[...]} />`.                                 |
+| `<web-ai-chat>`  | `element.registerTool(tool)`, or the `tools` property (functions can't be attributes).                                       |
+| Plain HTML       | A form with `toolname` and `tooldescription` attributes ([Forms as tools](#forms-as-tools)); no script needed.               |
+| A WebMCP browser | Tools registered with the browser's own `document.modelContext.registerTool()` are offered too ([WebMCP](#webmcp-browsers)). |
+
+`registerTool` adds the tool for every widget on the page. Pass an `AbortSignal` to remove it again, for example when
+a single-page app leaves the route that owns it:
+
+```ts
+const route = new AbortController();
+chat.registerTool(addToCart, { signal: route.signal });
+// …when the visitor leaves the product page:
+route.abort();
+```
+
+`useHelpAITool` does this for you: the tool is registered while the component is mounted, `execute` always runs the
+latest render's function, and React's StrictMode double mount still leaves one registration.
+
+## A tool
+
+| Field                           | What it is                                                                                                                                                                                 |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`                          | Letters, digits, `_` and `-`, 58 characters at most; other characters become `_`. The agent sees `site__<name>`. A name registered again replaces the earlier tool.                        |
+| `description`                   | When the agent should use it and what it does, 1024 characters at most. The agent picks tools by their descriptions: say when, not only what. Without one, `title` (then `name`) is used.  |
+| `title`                         | Optional. A short human name.                                                                                                                                                              |
+| `inputSchema`                   | Optional. [JSON Schema](https://json-schema.org/) of the input, an object. The agent fills it in; use `enum` and `required` to keep the input exact. Without one, the tool takes no input. |
+| `annotations.consequentialHint` | Optional. `true` for a tool with real consequences (an order, a booking, a message to someone): the visitor approves each call in the chat first, and the function runs only on Approve.   |
+| `execute`                       | `(input, { signal }) => result`. Return a value or a promise of one; throw to report a failure. `signal` aborts when the visitor moves on before the call finishes.                        |
+
+The `ModelContextTool` and `ToolAnnotations` types are exported for TypeScript; `ModelContextTool<{ sku: string }>`
+types `execute`'s input. WebMCP's other annotations (`readOnlyHint`, `untrustedContentHint`) are accepted and not used
+yet.
+
+Nothing about a tool can break the chat: a tool without a `name` or an `execute` function is left out with a warning
+in the browser console, and every message still goes through.
+
+## Forms as tools
+
+A form becomes a tool with two attributes, in every browser:
+
+```html
+<form toolname="request_demo" tooldescription="Request a product demo for the visitor." toolautosubmit>
+  <label for="email">Work email</label>
+  <input id="email" name="email" type="email" required />
+  <input name="company" toolparamdescription="The visitor's company name" />
+  <select name="plan">
+    <option value="starter">Starter</option>
+    <option value="pro">Pro</option>
+  </select>
+  <button>Request demo</button>
+</form>
+```
+
+- Each named field is an input the agent can fill: a `select` or radio group takes one of its values, a checkbox
+  `true` or `false`, a number field a number, anything else text. Hidden, disabled and file fields are left out, and
+  so are passwords: the visitor types those, never the chat.
+- A field's description is its `toolparamdescription`, else its label, else its `aria-description`; `required`
+  fields are required.
+- The agent fills the fields the way a visitor would (your framework's change handlers run). With `toolautosubmit`
+  the form is then submitted; without it the visitor checks the form and presses its button. When a field still
+  blocks the submit (a password, or a value the browser rejects), the form isn't submitted and the agent is told which
+  field needs the visitor.
+
+## WebMCP browsers
+
+In a browser with WebMCP (`document.modelContext`: in Chrome, turn on `chrome://flags/#enable-experimental-web-platform-features`
+or join the origin trial), the tools the page registered with the browser are offered to the agent too, and the widget
+runs them through the browser. A `<form toolname>` is the exception: such a browser lists it too, but the widget fills
+it itself, as in every other browser, so your form's own submit handler keeps working and passwords stay the
+visitor's. Elsewhere, nothing changes.
+
+## Which tools a message offers
+
+The widget reads the page's tools when the visitor sends each message: the browser's WebMCP tools, then forms, then
+the `tools` option, then `registerTool`. For a name in more than one place, the later one wins. When the agent calls a
+tool, the widget reads them again and runs the current function of that name, so a single-page app's route change
+applies straight away, with nothing to keep in sync. A call to a tool the page no longer has tells the agent the page
+doesn't offer it right now. So does a call to a tool the message didn't offer at all (the agent repeating an earlier
+call after a route change): the server answers it with "This page doesn't offer that action right now.", tells the agent
+not to call it again this turn, and the agent carries on from what it knows or asks the visitor.
+
+## What the agent gets back
+
+- **A return value** becomes the tool's result, as JSON: dates become strings, `undefined` becomes `null`, functions
+  are dropped, a page element is named (`"[dialog]"`), a repeated object reads `"[circular]"`, and a result over
+  30,000 characters is sent as `{ truncated: true, preview }`. Return what the agent needs to answer well, such as
+  `{ opened: true }` or `{ items: 2, total: '$48' }`.
+- **A thrown error** (or a rejected promise) reaches the agent as the tool's error, with its message, so it can tell
+  the visitor or try another way. For an expected miss ("that product is out of stock") a normal result such as
+  `{ ok: false, reason: 'out of stock' }` gives the agent more to work with.
+
+With several calls in one step, the agent waits for all of them, and for any approvals, then continues once.
+
+## Each call runs once
+
+- **Tabs.** Only the tab where the visitor sent the message runs the calls in its reply; another tab of the same
+  conversation shows them running, then the agent's answer.
+- **Reloads and navigation.** A call that hadn't started when the page reloaded runs once after the reload. A call
+  that was running is never run again: the agent is told the page reloaded, so it may or may not have taken effect,
+  and checks with the visitor; its card reads "Not completed". A result that was ready but not yet sent is sent after the reload. The widget keeps
+  this note per tab in `sessionStorage`, so it also covers a navigation to another page of your site.
+- **Leaving the page.** Results go out with `keepalive`, so they arrive even when the page navigates straight after.
+  A tool that navigates should return first and leave after:
+
+  ```ts
+  execute({ path }) {
+    setTimeout(() => location.assign(path), 0); // navigate after the result is sent
+    return { navigating: path };
+  },
+  ```
+
+- **The script loaded twice, or two widgets.** The call still runs once.
+- **No time limit.** The agent waits for the result. While a tool runs, the chat shows Stop. If the visitor presses it,
+  or sends another message first, the call's `signal` aborts, its result is never sent, and its card reads
+  "Not completed". A stopped call never runs again, not even after a reload.
+
+When `sessionStorage` is blocked (some private modes), the note lives in memory, so a reload can't tell a call that
+ran from one that didn't; everything else works the same.
+
+## What the visitor sees
+
+A tool that runs on its own appears in the transcript only when the deployment shows tool calls
+(`behavior.showToolCalls`), with its input and result: "Running", then "Completed" or "Error" (the tool failed), or
+"Not completed" when the visitor stopped it or moved on, or a reload cut it short. A tool with `consequentialHint` always shows an approval card with the input; Reject tells
+the agent the visitor declined, and the function never runs.
+
+## Events
+
+Each call this page settles fires `toolResult` with `{ toolCallId, name, status, durationMs }`: `status` is
+`completed`, `failed`, `declined` (the visitor rejected it), `stopped` (the visitor pressed Stop) or `interrupted` (a
+reload cut it short). It never carries the input or the result.
+
+```ts
+chat.on('toolResult', ({ name, status, durationMs }) => analytics.track('help_ai_tool', { name, status, durationMs }));
+```
+
+## Security
+
+- Tools run with your page's full privileges, as code you wrote. Anyone can also call your functions from the
+  browser's developer tools, so a tool may do only what the visitor could do on the page themselves.
+- The agent chooses the input. Check it in `execute` as you would a form submission, and mark tools with real
+  consequences (payments, deletions, messages to other people) `consequentialHint: true`, or confirm in your own UI.
+- The definitions are sent with each message and the results are stored in the conversation, like any tool's result,
+  so never put secrets in a description or a result.
+
+## Testing
+
+`testing/page-tools-manual.md` walks through every case above in a real browser
+on the `dev/page-tools.html` playground, with a real model or the mock backend.
+
+## Troubleshooting
+
+- **The agent never uses the tool:** write the description as an instruction ("Use it whenever the visitor wants to
+  book a call"), and check the console for a "skipped a tool" warning.
+- **The chat waits after a tool:** the function never settled (a promise that doesn't resolve). Return, or throw.
+- **"This page doesn't offer … right now":** the call came after the tool was removed (a route change aborted its
+  signal), or the agent tried a tool this page doesn't register. Keep a tool registered while the agent may still use
+  it.

package/docs/security-privacy.md

@@ -340,7 +340,8 @@ the pinned version URL (`/v1.2.0/`) supports SRI — the floating URL
 ## Authentication
 
 Browser access is scoped by `aiAgentDeploymentId`; a `publicKey` adds
-workspace authorization. There is **no per-end-user token.**
+workspace authorization. Visitors are anonymous unless your server signs a
+[user token](#verified-users-usertoken) for your logged-in user.
 
 ### public key (default)
 
@@ -365,6 +366,64 @@ What your public key does NOT grant:
 Omit `publicKey` but keep `aiAgentDeploymentId`; the widget connects to
 that public deployment as a guest without an auth header.
 
+### Verified users (`userToken`)
+
+To show a logged-in user their own conversations on any device, and to let the AI rely on who they are, your
+server signs a short-lived JWT for them with the deployment's **secret key** (on the deployment's Install page;
+never put it in the browser):
+
+| Claim   | Required | What it is                                                 |
+| ------- | -------- | ---------------------------------------------------------- |
+| `sub`   | yes      | Your own id for the user (a string, up to 255 characters)  |
+| `exp`   | yes      | Expiry, in seconds since the epoch; keep it short (1 hour) |
+| `name`  | no       | Their name, given to the AI as a verified fact             |
+| `email` | no       | Their email, given to the AI as a verified fact            |
+
+Sign it with HS256:
+
+```js
+// Node (jose)
+import { SignJWT } from 'jose';
+
+const secret = new TextEncoder().encode(process.env.HELPAI_SECRET_KEY);
+const userToken = await new SignJWT({ name: user.name, email: user.email }).setProtectedHeader({ alg: 'HS256' }).setSubject(String(user.id)).setExpirationTime('1h').sign(secret);
+```
+
+```python
+# Python (PyJWT)
+import os, time, jwt
+
+user_token = jwt.encode({"sub": str(user.id), "exp": int(time.time()) + 3600, "name": user.name, "email": user.email}, os.environ["HELPAI_SECRET_KEY"], algorithm="HS256")
+```
+
+```php
+// PHP (firebase/php-jwt)
+use Firebase\JWT\JWT;
+
+$userToken = JWT::encode(['sub' => (string) $user->id, 'exp' => time() + 3600, 'name' => $user->name, 'email' => $user->email], getenv('HELPAI_SECRET_KEY'), 'HS256');
+```
+
+Serve it from an endpoint only your signed-in user can reach, and hand the widget a function that fetches it:
+
+```ts
+const userToken = () => fetch('/api/help-ai-token').then((res) => res.text());
+
+init({ publicKey: 'agent_pk_...', aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000', userToken }); // signed in at load
+chat.login(userToken); // or after your sign-in (`HelpAI('login', userToken)`, `<HelpAI userToken={userToken} />`)
+chat.reset(); // on sign-out (`HelpAI('reset')`)
+```
+
+- The widget sends the token only to the agent API, as the `x-user-token` header. The function is called when a token
+  is first needed and again when the server answers `401 USER_TOKEN_INVALID` (expired or rejected); the request is
+  then sent once more. A fixed string can't be refreshed, so an expired one fails until you call `login()` again.
+- A token the server can't verify is refused; it never falls back to an anonymous visitor.
+- Signing in moves the visitor's conversations on that browser to the user. From then on they reach them on any device
+  where they're signed in, and nobody else does, the signed-out browser included.
+- Signing out (`reset()`, or dropping the token) or switching to another user starts over as a new visitor: nothing of
+  the previous user stays in the browser.
+- Keep the function's identity stable for one user (a module function, or `useCallback` keyed on your user id): a
+  different function counts as a different user.
+
 ### user / page context is NOT auth
 
 ```ts
@@ -406,13 +465,13 @@ flowchart TB
     direction TB
     B1["Authenticates the HOST's agent deployment<br/>(NOT the end user)"]
     B2["Treats userContext / pageContext as<br/>informational + untrusted"]
-    B3["Never registers / authenticates end users"]
+    B3["Never registers end users; verifies a signed userToken when the host sends one"]
   end
 
   Host -->|"context (untrusted)"| Widget
   Widget -->|"HTTPS/TLS + headers + context field"| Backend
 
-  note["publicKey + aiAgentDeploymentId auth the host's agent, NOT the end user — no end-user token anywhere."]
+  note["publicKey + aiAgentDeploymentId auth the host's agent; only a userToken signed by the host's server identifies the end user."]
   Backend -.-> note
 ```
 
@@ -430,6 +489,8 @@ and anyone can base64url-decode it. Never put a secret in context.
 
 - **public keys** — rotate from the dashboard. Old keys are deactivated
   instantly; update your embeds.
+- **secret key** — user tokens signed with a replaced secret key stop verifying, so every verified user is signed out
+  until your server signs new ones with the new key.
 
 ---