@useago/sdk 1.9.0 → 1.13.0

package/CHANGELOG.md

@@ -5,6 +5,175 @@ 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.13.0] - 2026-09-10
+
+### Added
+
+- **Knowledge language from your application.** Set `language: "fr"` on the
+  client or `<AgoProvider language={locale}>` to send `Accept-Language` with
+  SDK requests. Change it with `client.updateConfig({ language: "de" })`
+  without recreating the client. AGO selects available knowledge translations
+  and source titles. `null` clears the override; invalid locales are rejected
+  before changing the configuration. `createAgo` accepts the same option.
+- **Audio transcription.** Call `client.transcribeAudio(file, { signal })` to
+  turn an audio file into editable text. The method uses the SDK's existing
+  authentication and supports cancellation. It is also available through the
+  Angular service and mock client. `getConfig()` exposes `speechToTextEnabled`
+  for each permission, defaulting to `false` on older backends.
+- **Dictation in the chat composer.** Set `speechToText: true` on
+  `mountChatWidget`, or use `<ChatWidget speechToText />` in React. When the
+  tenant enables transcription, the microphone opens a volume waveform with
+  a timer and cancel/confirm controls. Confirming appends the transcript to
+  the draft for editing before sending. Recordings stop after two minutes;
+  closing the widget or changing conversations releases the microphone and
+  cancels pending transcription.
+- **Reusable React dictation controls.** Use `<ChatInput speechToText />` or
+  `<SpeechToTextButton onTranscript={setDraft} />` in a custom composer.
+  Translate the controls with `SpeechToTextLabels` and
+  `DEFAULT_SPEECH_TO_TEXT_LABELS`. The waveform respects reduced motion.
+- **WebMCP bridge (`webmcp` config).** Set `webmcp: true` and every registered
+  client function is also registered as a
+  [WebMCP](https://github.com/webmachinelearning/webmcp) tool on
+  `document.modelContext`, so the tools written for AGO's agent are offered to
+  whatever agent the user brings. A tool a page registers on mount is withdrawn
+  when that page unmounts. In React it is a prop on `AgoProvider`. Off by
+  default, and a no-op in browsers without WebMCP. Calls emit `function:invoke`
+  and `function:result` like any other. There is no approval gate on them, and
+  cancelling a call does not stop the handler.
+- **`webmcp` on a function definition.** WebMCP-only metadata the AGO schema has
+  no room for: `annotations` (`readOnlyHint`, `untrustedContentHint`) and
+  `navigates`. `webmcp: false` keeps one function private to your own agent
+  while the bridge is on.
+- **`webmcp: { navigates: true }`.** A navigating function's WebMCP call is held
+  open until the function registry has been quiet for 150ms (600ms when the
+  destination registers nothing, 4s ceiling), so the caller reads the
+  destination page's tools instead of the departing page's.
+  Already set on the built-in `navigateToPage`, so `registerNavigationFunction`
+  and `useAgoNavigation` need no change. Set it yourself on a custom function
+  whose handler navigates.
+- **`autoScroll: false` on the chat widget.** `mountChatWidget` follows new
+  messages and streamed replies while the reader is at the bottom. Pass
+  `autoScroll: false` and the reader keeps their position during a reply:
+  sending a message or clicking the jump-to-latest button still moves to the end
+  once, and nothing follows after that. Automatic following stays the default.
+
+### Fixed
+
+- `getConversation()` and `getMessages()` now preserve knowledge sources,
+  including translated titles, when loading conversation history.
+- **`webmcp` and `requiresApproval` are no longer dropped by the framework
+  wrappers.** React's `useAgoFunction` dropped `webmcp`, and Vue's dropped both
+  `webmcp` and `requiresApproval`, so `webmcp: false` was silently ignored and
+  the function was mirrored anyway. An inline `webmcp` object is compared by
+  value, so it does not re-register the function on every render.
+- **`functions:changed` event** and `client.onFunctionsChanged(listener)`, fired
+  when a function is registered, unregistered, or the registry is cleared. The
+  dev panel now repaints its function list from it instead of waiting for a
+  manual refresh.
+
+## [1.12.0] - 2026-09-07
+
+### Added
+
+- **User metadata on messages.** Set `metadata` on the client config (or in
+  `window.AGO.metadata`) and the JSON-serializable object rides along with every
+  new message, both JSON and multipart uploads. `sendMessage(text, { metadata })`
+  replaces the defaults for that message, `null` omits the field, and
+  `updateConfig({ metadata })` changes it at runtime. In React, `useAgo`
+  re-applies the `metadata` prop without recreating the client. The API stores
+  it as widget metadata on the user, where field mappings can pull selected
+  values into tickets. It is untrusted browser-supplied context, not a
+  credential.
+- **JavaScript errors as agent context.** Set `errorWatcher: true` (or options)
+  on the client config and the page's recent JS errors ride along with every
+  message as the `errors:recent` context entry: uncaught exceptions with file,
+  line and stack, unhandled promise rejections, `console.error` calls (the
+  method is wrapped, calls through, and is restored on `destroy()`), and
+  errors the app hands over with `client.reportError(error, context?)`.
+  Deduplicated with a `count`, capped at 10, pruned after 10 minutes, messages
+  and stacks truncated. Options `maxErrors`, `maxAgeMs`, `maxStackChars`,
+  `filter`. New client methods `enableErrorWatcher`, `disableErrorWatcher`,
+  `reportError`, `getRecentErrors`, `clearErrors`; new event `error:captured`;
+  new exports `ErrorWatcher`, `CapturedError`, `ErrorWatcherOptions`. Off by
+  default: error messages can carry PII.
+- **`jsErrors` proactive matcher.** Captured errors count as friction on the
+  current route (`SignalsSnapshot.jsErrors`, reset on navigation), so a
+  trigger can nudge right after a crash with `when: { jsErrors: 1 }`. Needs
+  `errorWatcher` on; counts only, the messages stay in `client_context`.
+
+### Fixed
+
+- Ticket attachments become available when the dashboard form configuration
+  finishes loading.
+- Ticket forms now support multiple condition values, nested questions and
+  conditional choices across ticketing providers. Changing a branch clears
+  answers that no longer apply. Required questions are checked before sending,
+  including those not yet revealed.
+- Ticket forms respect option groups and order, fields marked always visible,
+  format validation, priority by request type and dashboard success messages
+  when the API supplies these settings.
+
+## [1.11.0] - 2026-09-04
+
+### Added
+
+- **`loadHomeConfig` on the bubble widget: the home screen from the AGO
+  dashboard.** `mountChatWidget(el, { placement: "bubble", loadHomeConfig: true })`
+  takes the home title, the markdown subtitle and the starter cards from
+  `GET /config` instead of the options, the way the hosted widget does. One
+  request on mount, off the critical path: the panel renders with whatever the
+  options set and re-renders when the config lands, and a failed request leaves
+  the options in place. Each part is replaced only when the dashboard has a
+  value for it, and the header keeps the `title` option. The dashboard's
+  _widget starter_ (an opening message the agent sends by itself) fires when the
+  panel is first opened, on a fresh visit only, never over a resumed thread.
+- **`agentId` on `ConversationStarter`.** A starter card can name the agent
+  that answers it. Dashboard starters carry their own.
+- **`SdkPermissionConfig.homePage`.** `AgoClient.getConfig()` now maps the
+  `home_page` block (`title`, `subtitle`, `home_starters`, `widget_starter`)
+  when the backend sends one. A starter card shows its `description` and sends
+  its `initial_message`; one with neither is dropped. New types
+  `SdkHomePageConfig`, `SdkHomeStarter`, `SdkWidgetStarter`.
+
+## [1.10.0] - 2026-09-03
+
+### Added
+
+- **`placement: "bubble"` on `mountChatWidget`.** The hosted embed widget
+  without the iframe: a 54px launcher bottom right, a teaser bubble one second
+  after mount, and a 550px panel with a home screen (title, markdown
+  `subtitle`, `conversationStarters` cards), a conversation screen, and a chat
+  history screen with relative times and a "New conversation" pill. Reopens
+  the visitor's most recent thread when its last message is under two hours
+  old (`autoResume`), goes full screen under 450px, closes on Escape, and
+  takes the embed snippet's `colors` (`button`, `header` with gradients,
+  `agentMessage`, `background`, `font`, `userMessage`) with the header text
+  derived for contrast. New options `prompt`, `icon`, `colors`, `hideFooter`,
+  `subtitle`, `conversationStarters`, `autoResume`, `labels`; new handle
+  members `screen`, `showScreen`, `openConversation`, `newConversation`. New
+  theme tokens `--ago-launcher-background`, `--ago-launcher-text-color`,
+  `--ago-send-button-background`, `--ago-user-bubble-background`,
+  `--ago-user-bubble-text-color`, `--ago-agent-bubble-text-color`,
+  `--ago-panel-width`.
+- **The ticket form renders in the vanilla widget.** The `form` tool call the
+  agent's `ago_ticketing` tool opens now shows the tenant's contact form in the
+  conversation, on every placement: inline fields from `GET /config`, the
+  embedded (HubSpot) variant, the "not allowed" notice, a green success block,
+  and the composer replaced by a "complete the form" card, then "ticket
+  created" with a New conversation button. New `toolCallForm` option (labels,
+  success text, `userEmail`, callbacks).
+- **`AgoClient.getConfig()`, `AgoClient.createTicket()`, and
+  `AgoClient.getUserIdentity()`.** `ToolCallData` carries the ticketing fields
+  (`displayMode`, `askToTalkToHuman`, `allowedToCreateTicket`, `ticket`,
+  `mode`, `ticketFormId`, `embedHtml`, `embedDescription`), streamed and
+  persisted alike. New exported types `TicketForm`, `TicketField`,
+  `SdkConfig`, `CreateTicketInput`, `CreateTicketResult`.
+
+### Changed
+
+- Nothing for the existing `inline`, `left`, and `right` placements. The
+  `newConversation()` handle method is new on all of them.
+
 ## [1.9.0] - 2026-08-28
 
 ### Changed
@@ -128,9 +297,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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
+  - **`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
@@ -141,6 +311,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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 }`.
@@ -215,7 +386,7 @@ declared in `"placeholder"` mode.
   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
+  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).

package/README.md

@@ -232,6 +232,25 @@ 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.
 
+## Share the same tools with the user's own browser agent
+
+[WebMCP](https://github.com/webmachinelearning/webmcp) lets a page hand tools to
+whatever agent the user brings, such as an agentic browser or an extension. Set
+`webmcp` and every function you register is offered there too:
+
+```tsx
+<AgoProvider baseUrl="https://api.example.com" agent="support-agent" webmcp>
+  <ChatWidget />
+</AgoProvider>
+```
+
+Off by default, and a no-op where the browser has no WebMCP. A mirrored function
+runs as soon as the external agent calls it, with no approval gate, so set
+`webmcp: false` on anything that must not run unattended. Navigation is handled:
+a call that changes page resolves only once the destination has registered its
+own tools. See
+[functions and context](docs/general/functions-and-context.md#webmcp-bridge-share-your-functions-with-browser-agents).
+
 ## Let the user stop a long answer
 
 `<ChatWidget>` already does this: while the agent answers, its send button turns
@@ -304,6 +323,113 @@ React and Vue have a `useFeedback()` hook/composable; React also exports the
 `<MessageFeedback messageId={...} />` row for a custom message list. Details in
 [Feedback](docs/general/widget.md#feedback).
 
+## Choose the knowledge language
+
+```ts
+ago.updateConfig({ language: "fr" });
+const conversation = await ago.getConversation(conversationId);
+const sources = conversation.messages?.flatMap((message) => message.sources ?? []);
+```
+
+Pass your app's locale as `language` when creating the client, or update it when
+the visitor changes languages. The API uses `Accept-Language` to select existing
+knowledge translations. Reloading a conversation refreshes its source titles.
+In React, pass `language={i18n.language}` to `AgoProvider`.
+See [Language](docs/general/configuration.md#language) for regional tags and
+fallback behavior.
+
+## Transcribe audio into a draft
+
+```ts
+const { text } = await ago.transcribeAudio(audioFile);
+messageInput.value = text; // The user can edit it before sending.
+```
+
+Pass an audio `File` (up to 25 MB). Check `speechToTextEnabled` in the
+permissions returned by `ago.getConfig()` before showing a recording control.
+Supports cancellation with `{ signal }` and works through the client in every
+framework, including `AgoService.transcribeAudio` in Angular.
+See [Speech to text](docs/general/core.md#speech-to-text) for recording blobs,
+supported formats and error handling.
+
+For the complete dictation UI in the floating chat widget:
+
+```ts
+mountChatWidget(document.body, {
+  config: { baseUrl: "https://playground.api.useago.com" },
+  placement: "bubble",
+  speechToText: true,
+});
+```
+
+Use your tenant's API domain with speech to text enabled. The microphone appears
+when the tenant allows it and the browser supports recording. While recording,
+the editor becomes a waveform that follows the microphone volume, with a timer
+and cancel/confirm controls. A spinner appears during transcription; the text
+then returns to the editable draft.
+
+The same UI ships in React:
+
+```tsx
+<ChatWidget speechToText />
+```
+
+For a custom React composer, use `SpeechToTextButton` with an `onTranscript`
+callback. See [Dictation](docs/frameworks/react.md#dictation) for examples.
+
+## Let the agent see what broke
+
+"The button does nothing" is easier to answer with the exception in hand. Turn
+on the error watcher and the page's recent JavaScript errors (uncaught
+exceptions with file, line and stack, unhandled rejections, `console.error`
+calls) ride along with every message, deduplicated and capped.
+
+```ts
+const ago = new AgoClient({
+  baseUrl: "https://playground.api.useago.com",
+  agent: "generic-guide",
+  errorWatcher: true, // off by default: error messages can carry PII
+});
+
+// Errors you already catch (error boundaries, framework handlers):
+ago.reportError(error, { component: "OrderTable" });
+```
+
+Same option on `<AgoProvider>`, the Vue plugin, `provideAgo` and
+`mountChatWidget({ config })`. Redact with a `filter`, tune the caps, or use
+`when: { jsErrors: 1 }` in a proactive trigger to nudge right after a crash.
+Details in [JavaScript errors](docs/general/functions-and-context.md#javascript-errors).
+
+## Drop the chat bubble on any page
+
+The hosted embed widget, without the iframe: a launcher in the corner, a teaser
+bubble, and a panel with a home screen, the conversation, and the chat history.
+It reopens the visitor's last thread for two hours and goes full screen on a
+phone.
+
+```ts
+import { mountChatWidget } from "@useago/sdk/widget";
+
+mountChatWidget(document.body, {
+  config: { baseUrl: "https://playground.api.useago.com", agent: "generic-guide" },
+  placement: "bubble",
+  title: "Ask AGO",
+  conversationStarters: [{ label: "What can the SDK do?" }],
+  colors: { button: "#007bff", header: "#03182f" },
+});
+```
+
+Add `loadHomeConfig: true` and the home title, subtitle and starter cards come
+from your AGO dashboard instead of the options above.
+
+When the visitor asks for a human, the agent's ticket form renders inside the
+conversation on every placement, with the fields from your AGO dashboard.
+Conditional questions and choices work across ticketing providers; changing an
+answer clears responses that no longer apply. The API must include the form
+metadata described in the ticket form guide.
+Details in [Floating bubble](docs/general/widget.md#floating-bubble-placement-bubble)
+and [Ticket form](docs/general/widget.md#ticket-form-the-form-tool-call).
+
 ## Show the source docs the agent retrieved
 
 Each assistant message carries the knowledge sources it used in `m.sources`

package/dist/angular.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("./types-D3YQl1jx.cjs"),c=require("./autoContinue-CP9pJR-V.cjs");var n=class{constructor(t){this.client=new r.AgoClient(t),this.messages$=this.fromEvent("message:complete"),this.chunks$=this.fromEvent("message:chunk"),this.errors$=this.fromEvent("message:error"),this.messageStart$=this.fromEvent("message:start")}fromEvent(t){const e=this.client;return{subscribe(i){const s=o=>{i.next?.(o)};return e.on(t,s),{unsubscribe:()=>e.off(t,s)}}}}sendMessage(t,e){return this.client.sendMessage(t,e)}stop(){return this.client.stop()}stopMessage(t){return this.client.stopMessage(t)}isGenerating(){return this.client.isGenerating()}getConversations(){return this.client.getConversations().then(t=>t.data)}getConversation(t){return this.client.getConversation(t)}getMessages(t){return this.client.getMessages(t)}submitToolCallForm(t,e){return this.client.submitToolCallForm(t,e)}confirmToolCall(t){return this.client.confirmToolCall(t)}rejectToolCall(t){return this.client.rejectToolCall(t)}submitFeedback(t,e,i){return this.client.submitFeedback(t,e,i)}submitConversationFeedback(t,e,i){return this.client.submitConversationFeedback(t,e,i)}registerFunction(t,e,i){typeof t=="object"?this.client.registerFunction(t):this.client.registerFunction(t,e,i)}unregisterFunction(t){return this.client.unregisterFunction(t)}registerNavigationFunction(t,e){this.client.registerNavigationFunction(t,e)}unregisterNavigationFunction(){this.client.unregisterNavigationFunction()}enableAutoContinueAfterNavigation(t){return c.attachAutoContinueAfterNavigation(this.client,t)}registerPageStateFunction(t,e){this.client.registerPageStateFunction(t,e)}unregisterPageStateFunction(t){this.client.unregisterPageStateFunction(t)}on(t,e){this.client.on(t,e)}off(t,e){this.client.off(t,e)}updateConfig(t){this.client.updateConfig(t)}getClient(){return this.client}destroy(){this.client.destroy()}};function u(t){return{provide:n,useValue:new n(t)}}exports.AgoService=n;exports.FEEDBACK_REASONS=r.FEEDBACK_REASONS;exports.provideAgo=u;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("./types-a7teDBnC.cjs"),c=require("./autoContinue-CP9pJR-V.cjs");var n=class{constructor(t){this.client=new s.AgoClient(t),this.messages$=this.fromEvent("message:complete"),this.chunks$=this.fromEvent("message:chunk"),this.errors$=this.fromEvent("message:error"),this.messageStart$=this.fromEvent("message:start")}fromEvent(t){const e=this.client;return{subscribe(i){const r=o=>{i.next?.(o)};return e.on(t,r),{unsubscribe:()=>e.off(t,r)}}}}sendMessage(t,e){return this.client.sendMessage(t,e)}transcribeAudio(t,e){return this.client.transcribeAudio(t,e)}stop(){return this.client.stop()}stopMessage(t){return this.client.stopMessage(t)}isGenerating(){return this.client.isGenerating()}getConversations(){return this.client.getConversations().then(t=>t.data)}getConversation(t){return this.client.getConversation(t)}getMessages(t){return this.client.getMessages(t)}submitToolCallForm(t,e){return this.client.submitToolCallForm(t,e)}confirmToolCall(t){return this.client.confirmToolCall(t)}rejectToolCall(t){return this.client.rejectToolCall(t)}submitFeedback(t,e,i){return this.client.submitFeedback(t,e,i)}submitConversationFeedback(t,e,i){return this.client.submitConversationFeedback(t,e,i)}registerFunction(t,e,i){typeof t=="object"?this.client.registerFunction(t):this.client.registerFunction(t,e,i)}unregisterFunction(t){return this.client.unregisterFunction(t)}registerNavigationFunction(t,e){this.client.registerNavigationFunction(t,e)}unregisterNavigationFunction(){this.client.unregisterNavigationFunction()}enableAutoContinueAfterNavigation(t){return c.attachAutoContinueAfterNavigation(this.client,t)}registerPageStateFunction(t,e){this.client.registerPageStateFunction(t,e)}unregisterPageStateFunction(t){this.client.unregisterPageStateFunction(t)}on(t,e){this.client.on(t,e)}off(t,e){this.client.off(t,e)}updateConfig(t){this.client.updateConfig(t)}getClient(){return this.client}destroy(){this.client.destroy()}};function u(t){return{provide:n,useValue:new n(t)}}exports.AgoService=n;exports.FEEDBACK_REASONS=s.FEEDBACK_REASONS;exports.provideAgo=u;