@helpai/elements 1.9.0 → 1.11.0

package/llms.txt

@@ -1,36 +1,40 @@
 # Help AI Elements
 
-> Help AI's AI chat widget for any website: an AI agent that answers visitors from the customer's own help content, can hand the chat to a person, and shows Help articles and News. Install it with one script tag, the `<web-ai-chat>` element, the npm API or the React kit. These docs match @helpai/elements@1.9.0.
+> Help AI's AI chat widget for any website: an AI agent that answers visitors from the customer's own help content, can hand the chat to a person, and shows Help articles and News. Install it with one script tag, the `<web-ai-chat>` element, the npm API or the React kit. These docs match @helpai/elements@1.11.0.
 
 What a coding agent needs to install it right the first time:
 
 - Two values come from the deployment's Install page in the Help AI dashboard: the public key (`agent_pk_…`) and the AI agent deployment id (a UUID). Both belong in browser code. The deployment's secret key never does.
-- Plain HTML, WordPress or any CMS: `<script src="https://cdn.help.ai/sdk/js/elements/1.9.0/elements.js" data-public-key="agent_pk_…" data-ai-agent-deployment-id="…" defer></script>`.
+- Plain HTML, WordPress or any CMS: `<script src="https://cdn.help.ai/sdk/js/elements/1.11.0/elements.js" data-public-key="agent_pk_…" data-ai-agent-deployment-id="…" defer></script>`.
 - React, Next.js, Remix: install `@helpai/elements` and render `<HelpAI publicKey="…" aiAgentDeploymentId="…" />` from `@helpai/elements/react` once, in the root layout. `useHelpAI()` in any component returns `{ state, ask, open, close, reset }`. It is server-render safe; import everything from `@helpai/elements/react`.
 - Vue, Svelte, Angular and other bundlers: `import '@helpai/elements/web-component'`, then `<web-ai-chat public-key="…" ai-agent-deployment-id="…"></web-ai-chat>`. JSX typings: `@helpai/elements/jsx/react`, `/jsx/vue`, `/jsx/svelte`.
 - Site buttons need no JavaScript: `data-helpai-ask="Which plan fits a team of 10?"` puts the question in the chat, `data-helpai-open="help"` opens a tab (`home`, `chats`, `help`, `news`). In code, `ask(text)` fills the composer and sends only with `{ send: true }`.
+- Logged-in users: your server signs a JWT with the deployment's secret key (HS256; `sub` = your user id, `exp`; optional `name`, `email`), and the widget gets a function that fetches it: `userToken` at init, `login(fn)` after sign-in, `reset()` at sign-out. Their chats then follow them to any device. Never sign tokens in the browser.
+- Your page's own events: `chat.track('plan_viewed', { plan: 'pro' })` sends an analytics hit and lets the agent see the visitor's last 10 events with their next message.
+- Page tools: `chat.registerTool({ name, description, inputSchema?, annotations?: { consequentialHint }, execute })` (WebMCP shape; `HelpAI('registerTool', tool)` from the script tag, `useHelpAITool(tool)` in React, or a `<form toolname tooldescription>`) lets the agent act on the page (open a form, read the cart). `execute(input, { signal })` runs once in the browser and returns JSON for the agent; abort the registration's `signal` when a route leaves.
 - `theme: 'host'` (`theme="host"`) follows the site's own light/dark switch.
 - Pin the exact version in production, as above; `latest` changes under you.
 - It works when the launcher shows in the bottom corner and `HelpAI.ready()` (or `chat.ready`) resolves.
 
 ## Docs
 
-- [Quickstart](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/quickstart.md): credentials, the install paths and a first check, in five minutes
-- [Installation](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/installation.md): every install path in depth: script tag, async loader, npm, web component, CDN URLs and version pinning
-- [Frameworks](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/frameworks.md): the React kit (`<HelpAI />`, `useHelpAI()`), Next.js, Remix, Vue, Nuxt, Svelte, Astro, Angular, WordPress, Shopify, Webflow
-- [Configuration](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/configuration.md): every option by group, with examples
-- [Option reference](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/options.md): the table of every option, generated from the schemas; authoritative
-- [API reference](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/api-reference.md): exports, instance methods (`ask`, `open`, `state`, `ready`, `reset`, …), the global API, no-script triggers, deep links, JSX typings
-- [Events and hooks](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/events-and-hooks.md): every event and its payload, `on()` and `hook()`
-- [Theming](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/theming.md): colors, shapes, fonts, launcher styles, `theme: "host"` and `::part()` styling
-- [Recipes](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/recipes.md): copy-paste solutions for common integrations
-- [Analytics](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/analytics.md): sending widget activity to Google Analytics, Segment, PostHog and other trackers
-- [Security and privacy](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/security-privacy.md): isolation, CSP, what the widget stores and sends
-- [Browser support](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/browser-support.md): supported browsers and fallbacks
-- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/troubleshooting.md): an install that does not show, connect or answer
-- [FAQ](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/faq.md): short answers to common questions
-- [Overview](https://cdn.help.ai/sdk/js/elements/1.9.0/docs/README.md): the whole SDK on one page
+- [Quickstart](https://cdn.help.ai/sdk/js/elements/1.11.0/docs/quickstart.md): credentials, the install paths and a first check, in five minutes
+- [Installation](https://cdn.help.ai/sdk/js/elements/1.11.0/docs/installation.md): every install path in depth: script tag, async loader, npm, web component, CDN URLs and version pinning
+- [Frameworks](https://cdn.help.ai/sdk/js/elements/1.11.0/docs/frameworks.md): the React kit (`<HelpAI />`, `useHelpAI()`), Next.js, Remix, Vue, Nuxt, Svelte, Astro, Angular, WordPress, Shopify, Webflow
+- [Configuration](https://cdn.help.ai/sdk/js/elements/1.11.0/docs/configuration.md): every option by group, with examples
+- [Option reference](https://cdn.help.ai/sdk/js/elements/1.11.0/docs/options.md): the table of every option, generated from the schemas; authoritative
+- [API reference](https://cdn.help.ai/sdk/js/elements/1.11.0/docs/api-reference.md): exports, instance methods (`ask`, `open`, `state`, `ready`, `reset`, …), the global API, no-script triggers, deep links, JSX typings
+- [Events and hooks](https://cdn.help.ai/sdk/js/elements/1.11.0/docs/events-and-hooks.md): every event and its payload, `on()` and `hook()`
+- [Page tools](https://cdn.help.ai/sdk/js/elements/1.11.0/docs/page-tools.md): WebMCP-shaped tools the AI agent calls on your page (`registerTool`, `tools`, `useHelpAITool`, `<form toolname>`), run once in the browser
+- [Theming](https://cdn.help.ai/sdk/js/elements/1.11.0/docs/theming.md): colors, shapes, fonts, launcher styles, `theme: "host"` and `::part()` styling
+- [Recipes](https://cdn.help.ai/sdk/js/elements/1.11.0/docs/recipes.md): copy-paste solutions for common integrations
+- [Analytics](https://cdn.help.ai/sdk/js/elements/1.11.0/docs/analytics.md): sending widget activity to Google Analytics, Segment, PostHog and other trackers
+- [Security and privacy](https://cdn.help.ai/sdk/js/elements/1.11.0/docs/security-privacy.md): isolation, CSP, what the widget stores and sends
+- [Browser support](https://cdn.help.ai/sdk/js/elements/1.11.0/docs/browser-support.md): supported browsers and fallbacks
+- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.11.0/docs/troubleshooting.md): an install that does not show, connect or answer
+- [FAQ](https://cdn.help.ai/sdk/js/elements/1.11.0/docs/faq.md): short answers to common questions
+- [Overview](https://cdn.help.ai/sdk/js/elements/1.11.0/docs/README.md): the whole SDK on one page
 
 ## Optional
 
-- [Every doc in one file](https://cdn.help.ai/sdk/js/elements/1.9.0/llms-full.txt): the docs above, concatenated
+- [Every doc in one file](https://cdn.help.ai/sdk/js/elements/1.11.0/llms-full.txt): the docs above, concatenated

package/package.json

@@ -117,5 +117,5 @@
   ],
   "type": "module",
   "types": "./index.d.ts",
-  "version": "1.9.0"
+  "version": "1.11.0"
 }

package/react.d.ts

@@ -39,7 +39,7 @@ interface ClientStorage {
  * populated {@link Strings} map. UI components then read `strings.send` as a
  * normal property access — no per-render lookup, no per-render allocation.
  */
-type StringKey = 'launcherOpen' | 'launcherLabel' | 'panelTitle' | 'composerPlaceholder' | 'send' | 'stop' | 'queueMessage' | 'removeQueuedMessage' | 'compactingContext' | 'attach' | 'micStart' | 'micStop' | 'micUnsupported' | 'expand' | 'collapse' | 'fullscreen' | 'exitFullscreen' | 'popOut' | 'resizeHandle' | 'scrollToBottom' | 'close' | 'moreActions' | 'soundOn' | 'soundOff' | 'language' | 'theme' | 'themeAuto' | 'themeLight' | 'themeDark' | 'textSize' | 'textSizeSmall' | 'textSizeNormal' | 'textSizeLarge' | 'history' | 'historyTitle' | 'historyEmpty' | 'historyLoading' | 'historyBack' | 'historyContinue' | 'loadMoreConversations' | 'conversationLoading' | 'loadPreviousMessages' | 'conversationClosed' | 'startNewConversation' | 'talkToOperator' | 'connectingOperator' | 'noOperatorAvailable' | 'chattingWithOperator' | 'cancelOperatorRequest' | 'dateToday' | 'dateYesterday' | 'dateLastWeek' | 'dateOlder' | 'newConversation' | 'dropZone' | 'attachmentTooLarge' | 'attachmentTooMany' | 'attachmentMimeRejected' | 'errorRetry' | 'errorGeneric' | 'errorRateLimited' | 'loading' | 'visualPreparing' | 'visualError' | 'visualPartial' | 'thinking' | 'thoughts' | 'toolResult' | 'sources' | 'feedbackUp' | 'feedbackDown' | 'feedbackThanks' | 'copy' | 'copied' | 'collapseSidebar' | 'expandSidebar' | 'formSubmit' | 'formSkip' | 'formSubmitted' | 'formSkipped' | 'formFillOut' | 'formRequired' | 'formInvalidEmail' | 'formInvalidTel' | 'formInvalidUrl' | 'formInvalidNumber' | 'formTooShort' | 'formTooLong' | 'formNumberTooSmall' | 'formNumberTooLarge' | 'formPatternMismatch' | 'formChooseAtLeast' | 'formChooseAtMost' | 'formOther' | 'formOtherPlaceholder' | 'inputRequired' | 'inputBadge' | 'inputAnswered' | 'inputSkipped' | 'inputSubmit' | 'inputSubmitHint' | 'inputSkip' | 'showOptions' | 'hideOptions' | 'qtypeText' | 'qtypeEmail' | 'qtypePhone' | 'qtypeNumber' | 'qtypeDate' | 'qtypeChooseOne' | 'qtypeChooseAny' | 'qtypeBoolean' | 'confirmYes' | 'confirmNo' | 'approve' | 'reject' | 'approvalPrompt' | 'approvalBody' | 'approvalYourResponse' | 'approvalEditHint' | 'approvalSubmitting' | 'edit' | 'toolParameters' | 'statusAwaiting' | 'statusResponded' | 'statusCompleted' | 'statusDenied' | 'statusError' | 'statusRunning' | 'statusSuperseded' | 'tabHome' | 'tabConversations' | 'tabHelp' | 'tabNews' | 'modulesEmpty' | 'moduleBack' | 'contentLoading' | 'contentHelpful' | 'homeGreeting' | 'homeGreetingNamed' | 'homeGreetingLead' | 'homeSearchPlaceholder' | 'homeAskPlaceholder' | 'homeWhatsNew' | 'homeContentTitle' | 'homeStatus' | 'helpTitle' | 'helpSearchPlaceholder' | 'helpEmpty' | 'helpLoading' | 'helpSearchEmpty' | 'helpShowMore' | 'newsTitle' | 'newsEmpty' | 'newsLoading' | 'newsBack' | 'newsPublishedAt' | 'newsShowMore' | 'newsUnseen';
+type StringKey = 'launcherOpen' | 'launcherLabel' | 'panelTitle' | 'composerPlaceholder' | 'send' | 'stop' | 'queueMessage' | 'removeQueuedMessage' | 'compactingContext' | 'attach' | 'micStart' | 'micStop' | 'micUnsupported' | 'expand' | 'collapse' | 'fullscreen' | 'exitFullscreen' | 'popOut' | 'resizeHandle' | 'scrollToBottom' | 'close' | 'moreActions' | 'soundOn' | 'soundOff' | 'language' | 'theme' | 'themeAuto' | 'themeLight' | 'themeDark' | 'textSize' | 'textSizeSmall' | 'textSizeNormal' | 'textSizeLarge' | 'history' | 'historyTitle' | 'historyEmpty' | 'historyLoading' | 'historyBack' | 'historyContinue' | 'loadMoreConversations' | 'conversationLoading' | 'loadPreviousMessages' | 'conversationClosed' | 'startNewConversation' | 'talkToOperator' | 'connectingOperator' | 'noOperatorAvailable' | 'chattingWithOperator' | 'cancelOperatorRequest' | 'dateToday' | 'dateYesterday' | 'dateLastWeek' | 'dateOlder' | 'newConversation' | 'dropZone' | 'attachmentTooLarge' | 'attachmentTooMany' | 'attachmentMimeRejected' | 'errorRetry' | 'errorGeneric' | 'errorRateLimited' | 'loading' | 'visualPreparing' | 'visualError' | 'visualPartial' | 'thinking' | 'thoughts' | 'toolResult' | 'sources' | 'feedbackUp' | 'feedbackDown' | 'feedbackThanks' | 'copy' | 'copied' | 'collapseSidebar' | 'expandSidebar' | 'formSubmit' | 'formSkip' | 'formSubmitted' | 'formSkipped' | 'formFillOut' | 'formRequired' | 'formInvalidEmail' | 'formInvalidTel' | 'formInvalidUrl' | 'formInvalidNumber' | 'formTooShort' | 'formTooLong' | 'formNumberTooSmall' | 'formNumberTooLarge' | 'formPatternMismatch' | 'formChooseAtLeast' | 'formChooseAtMost' | 'formOther' | 'formOtherPlaceholder' | 'inputRequired' | 'inputBadge' | 'inputAnswered' | 'inputSkipped' | 'inputSubmit' | 'inputSubmitHint' | 'inputSkip' | 'showOptions' | 'hideOptions' | 'qtypeText' | 'qtypeEmail' | 'qtypePhone' | 'qtypeNumber' | 'qtypeDate' | 'qtypeChooseOne' | 'qtypeChooseAny' | 'qtypeBoolean' | 'confirmYes' | 'confirmNo' | 'approve' | 'reject' | 'approvalPrompt' | 'approvalBody' | 'approvalYourResponse' | 'approvalEditHint' | 'approvalSubmitting' | 'edit' | 'toolParameters' | 'statusAwaiting' | 'statusResponded' | 'statusCompleted' | 'statusDenied' | 'statusError' | 'statusRunning' | 'statusSuperseded' | 'statusIncomplete' | 'tabHome' | 'tabConversations' | 'tabHelp' | 'tabNews' | 'modulesEmpty' | 'moduleBack' | 'contentLoading' | 'contentHelpful' | 'homeGreeting' | 'homeGreetingNamed' | 'homeGreetingLead' | 'homeSearchPlaceholder' | 'homeAskPlaceholder' | 'homeWhatsNew' | 'homeContentTitle' | 'homeStatus' | 'helpTitle' | 'helpSearchPlaceholder' | 'helpEmpty' | 'helpLoading' | 'helpSearchEmpty' | 'helpShowMore' | 'newsTitle' | 'newsEmpty' | 'newsLoading' | 'newsBack' | 'newsPublishedAt' | 'newsShowMore' | 'newsUnseen';
 /** A partial map for one locale — what overrides look like on the wire. */
 type LocaleStrings = Partial<Record<StringKey, string>>;
 /**
@@ -899,6 +899,38 @@ interface ResolvedTracking {
  * alongside at the top level — they're function / DOM types that can't be
  * serialised on the wire.
  */
+/** A signed user token, or a function that returns a fresh one (see {@link ChatWidgetOptions.userToken}). */
+type UserTokenSource = string | (() => string | Promise<string>);
+/** WebMCP `ToolAnnotations`: hints about what a tool does. */
+interface ToolAnnotations {
+  /** It only reads; it changes nothing. */
+  readOnlyHint?: boolean;
+  /** Its result holds content the site doesn't vouch for, such as reviews. */
+  untrustedContentHint?: boolean;
+  /** A significant or irreversible action (booking, paying, deleting): the visitor approves each call first. */
+  consequentialHint?: boolean;
+  /** Built for developers, not visitors. */
+  debugging?: boolean;
+}
+/**
+ * A tool the AI agent can use on your page, in the WebMCP `ModelContextTool` shape: the same object works with
+ * `document.modelContext.registerTool()`. The agent sees `name`, `description` and `inputSchema`; `execute` runs here,
+ * in the visitor's browser, and what it returns goes back to the agent.
+ */
+interface ModelContextTool<TInput = unknown> {
+  /** Letters, digits, `_` and `-` (58 at most; others become `_`). A name registered again replaces the earlier tool. */
+  name: string;
+  title?: string;
+  /** When the agent should use it and what it does (1024 characters at most). */
+  description: string;
+  /** JSON Schema of the input (`type: "object"`); none means the tool takes no input. */
+  inputSchema?: Record<string, unknown>;
+  annotations?: ToolAnnotations;
+  /** Runs the tool: return a JSON value (or a promise of one) for the agent; throw to report a failure. `signal` aborts when the visitor moves on first. */
+  execute(input: TInput, options: {
+    signal: AbortSignal;
+  }): unknown;
+}
 interface ChatWidgetOptions {
   /**
    * Stable identifier for this widget instance. Use when mounting more
@@ -974,6 +1006,20 @@ interface ChatWidgetOptions {
    * interface (`get` / `set` / `remove` / `clear`).
    */
   storage?: ClientStorage;
+  /**
+   * Proves who the logged-in visitor is: a JWT your server signs (HS256) with the deployment's secret key, carrying
+   * `sub` (your user id) and `exp`, optionally `name` and `email`. A function is called when a token is first
+   * needed and again when the server rejects the current one as expired, so return a fresh token from it. Their
+   * conversations then follow them to any device; `chat.login(token)` sets it after sign-in, `chat.reset()` on
+   * sign-out. Sent only to the agent API, as `x-user-token`.
+   */
+  userToken?: UserTokenSource;
+  /**
+   * Tools the AI agent can use on your page (open a booking form, read the cart, jump to a section), WebMCP
+   * `ModelContextTool`s. Sent with each message as definitions only; the agent's call runs `execute` here, in the
+   * visitor's browser. `registerTool()` adds one from anywhere, for example a single-page app's route.
+   */
+  tools?: readonly ModelContextTool[];
   onMessage?: (msg: {
     role: string;
     text: string;
@@ -1084,11 +1130,15 @@ interface ResolvedOptions {
   tracking: ResolvedTracking;
   /** Resolved storage adapter — defaults to `LocalStorageAdapter`. */
   storage: ClientStorage;
+  userToken?: UserTokenSource;
+  tools?: readonly ModelContextTool[];
   onMessage?: ChatWidgetOptions['onMessage'];
   onOpen?: ChatWidgetOptions['onOpen'];
   onClose?: ChatWidgetOptions['onClose'];
   onError?: ChatWidgetOptions['onError'];
 }
+/** How a call this page ran (or found cut short) ended, for the `toolResult` event. */
+type PageToolCallStatus = 'completed' | 'failed' | 'interrupted';
 /** A single image asset (logo, hero, icon). */
 declare const assetSchema: z.ZodObject<{
   url: z.ZodString;
@@ -3134,15 +3184,27 @@ interface EventMap {
     values: Record<string, string>;
     skipped: boolean;
   };
-  /** User answered an ask-questions tool request (re-POST follows). */
+  /**
+   * A tool call settled on the page: the visitor answered an ask-questions request (`toolCallId` only), or a page
+   * tool's call ended — `completed`, `failed`, `declined` or `stopped` by the visitor, or `interrupted` by a reload —
+   * after `durationMs`. Never its input or result.
+   */
   toolResult: {
     toolCallId: string;
+    name?: string;
+    status?: PageToolCallStatus | 'declined' | 'stopped';
+    durationMs?: number;
   };
   /** User approved / rejected a gated tool call (re-POST follows). */
   toolDecision: {
     toolCallId: string;
     approved: boolean;
   };
+  /** Your page reported its own event with `track(name, data)`: sent to analytics, and to the agent with the next message. */
+  hostEvent: {
+    name: string;
+    data?: Record<string, string | number | boolean>;
+  };
   /**
    * User gave feedback on a rateable reply (AI or operator). `value` is `"up"` / `"down"`, or
    * `null` when they cleared a prior choice. `messageId` is the backend message
@@ -3290,6 +3352,8 @@ interface AskOptions {
   /** Send the text as the visitor's message instead of filling the composer with it. Default `false`. */
   send?: boolean;
 }
+/** Flat data about a host event: strings, numbers and booleans only. */
+type HostEventData = Record<string, string | number | boolean>;
 /**
  * Comprehensive logger for the widget runtime.
  *
@@ -3384,6 +3448,47 @@ export interface ChatWidgetInstance {
    * Listeners added with `on()` stay.
    */
   reset: () => void;
+  /**
+   * Sign the visitor in as your logged-in user, after they log in to your site: `userToken` is a JWT your server
+   * signs with the deployment's secret key (`sub`, `exp`; optional `name`, `email`), or a function that returns a
+   * fresh one. The widget reconnects as that user: their earlier chats on this browser move to them, and their
+   * conversations follow them to any device. Call `reset()` when they log out.
+   *
+   * @example
+   * ```ts
+   * chat.login(async () => (await fetch('/api/help-ai-token')).text());
+   * ```
+   */
+  login: (userToken: UserTokenSource) => void;
+  /**
+   * Report something the visitor did on your site, outside the chat. Sends a `hostEvent` hit to analytics (not when
+   * tracking is off), and the agent reads your last 10 events with the visitor's next message. `name` is 1–64
+   * characters; `data` is flat (strings, numbers, booleans), 256 characters of JSON at most.
+   *
+   * @example
+   * ```ts
+   * chat.track('plan_viewed', { plan: 'pro' });
+   * ```
+   */
+  track: (name: string, data?: HostEventData) => void;
+  /**
+   * Add a tool the agent can use on this page, in the WebMCP tool shape — for every widget on the page, not only this
+   * one. The latest registration of a name wins; aborting `options.signal` removes it. `annotations.consequentialHint`
+   * asks the visitor before each call. See `docs/sdk/page-tools.md`.
+   *
+   * @example
+   * ```ts
+   * chat.registerTool({
+   *   name: 'open_booking',
+   *   description: 'Open the booking form for a meeting type.',
+   *   inputSchema: { type: 'object', properties: { meetingType: { type: 'string', enum: ['sales', 'support'] } }, required: ['meetingType'] },
+   *   execute: ({ meetingType }) => booking.open(meetingType),
+   * });
+   * ```
+   */
+  registerTool: (tool: ModelContextTool, options?: {
+    signal?: AbortSignal;
+  }) => void;
   /**
    * Subscribe to a lifecycle event. Returns an `off` function. See
    * {@link EventMap} for the full set + payload shapes — currently
@@ -3543,10 +3648,26 @@ export interface HelpAIControls {
   open: ChatWidgetInstance['open'];
   close: ChatWidgetInstance['close'];
   reset: ChatWidgetInstance['reset'];
+  track: ChatWidgetInstance['track'];
 }
 /**
  * The widget's state and commands, for any component in the app, wherever `<HelpAI />` sits. A command sent before
  * the widget has mounted does nothing; `state.ready` turns true once it takes them.
  */
 export declare function useHelpAI(widgetId?: string): HelpAIControls;
-export type { AskOptions, Asset, BlocksConfig, ChatWidgetOptions, ConnectionConfig, ConnectionConfigPartial, EventMap, EventName, HandshakeResponse, HookListener, Link, LogEntry, LogLevel, OpenTarget, ResolvedOptions, ServerConfig, SiteConfig, WidgetConfig, WidgetConfigPartial, WidgetSettings, WidgetSettingsPartial, WidgetState };
+/**
+ * Give the agent a tool on this page while the component is mounted (WebMCP `registerTool`): every widget on the
+ * page can use it. A change to its definition registers it again; `execute` always runs the latest render's function.
+ *
+ * @example
+ * ```tsx
+ * useHelpAITool({
+ *   name: 'add_to_cart',
+ *   description: 'Add a product to the visitor\'s cart.',
+ *   inputSchema: { type: 'object', properties: { sku: { type: 'string' } }, required: ['sku'] },
+ *   execute: ({ sku }) => cart.add(sku),
+ * });
+ * ```
+ */
+export declare function useHelpAITool<TInput>(tool: ModelContextTool<TInput>): void;
+export type { AskOptions, Asset, BlocksConfig, ChatWidgetOptions, ConnectionConfig, ConnectionConfigPartial, EventMap, EventName, HandshakeResponse, HookListener, HostEventData, Link, LogEntry, LogLevel, ModelContextTool, OpenTarget, ResolvedOptions, ServerConfig, SiteConfig, ToolAnnotations, UserTokenSource, WidgetConfig, WidgetConfigPartial, WidgetSettings, WidgetSettingsPartial, WidgetState };