@useago/sdk 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -5,6 +5,72 @@ 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
@@ -59,7 +125,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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
+  _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.
@@ -69,7 +135,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   its `initial_message`; one with neither is dropped. New types
   `SdkHomePageConfig`, `SdkHomeStarter`, `SdkWidgetStarter`.
 
-
 ## [1.10.0] - 2026-09-03
 
 ### Added
@@ -232,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
@@ -245,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 }`.
@@ -319,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,60 @@ 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

package/dist/angular.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("./types-mcW8vB1U.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;

package/dist/angular.d.cts

@@ -109,7 +109,10 @@ declare class AgoClient {
      * `null` otherwise.
      */
     proactive: ProactiveController | null;
+    /** Removes the mirrored WebMCP tools; `null` when the bridge is off. */
+    private detachWebMCP;
     constructor(config: AgoConfig);
+    private attachWebMCPBridge;
     /**
      * Send a message and receive a streaming response
      */
@@ -221,6 +224,7 @@ declare class AgoClient {
      * (the agent decides what to do next). No-op if the invocation is unknown.
      */
     rejectFunction(invocationId: string): Promise<void>;
+    /* Excluded from this release type: runExternalFunction */
     /**
      * Get a page of conversations, newest-first. `pageSize` is capped at 100 by
      * the backend (default 50). Returns the `{ data, has_more, total }` envelope
@@ -240,11 +244,20 @@ declare class AgoClient {
      * `SSEHandler.parseToolCall` so persisted and streamed tool calls match.
      */
     private static mapPersistedToolCalls;
+    /**
+     * Transcribe an audio file into editable text (`POST /api/sdk/v1/audio/transcriptions`).
+     * Requires speech to text to be enabled for the tenant. Supports FLAC, MP3,
+     * MP4, MPEG, MPGA, M4A, OGG, WAV and WebM files up to 25 MB.
+     * The filename must include the matching extension. For a MediaRecorder blob,
+     * wrap it in a File with the recording's extension and MIME type.
+     * Show the returned text as a draft; call `sendMessage` when the user sends it.
+     */
+    transcribeAudio(file: File, options?: TranscribeAudioOptions): Promise<AudioTranscription>;
     /**
      * The tenant's SDK configuration (`GET /api/sdk/v1/config`): per-permission
      * agents, the ticket form the agent's `ago_ticketing` tool opens, and the
-     * file-attachment flag. The vanilla widget fetches it once, when a ticket
-     * form first appears in a conversation.
+     * file-attachment and speech-to-text flags. The vanilla widget fetches it
+     * once, when a ticket form first appears in a conversation.
      */
     getConfig(): Promise<SdkConfig>;
     /**
@@ -381,6 +394,9 @@ declare class AgoClient {
      * Get all registered function schemas
      */
     getRegisteredFunctions(): ClientFunctionSchema[];
+    /** The callback form of `functions:changed`. Returns an unsubscribe. */
+    onFunctionsChanged(listener: () => void): () => void;
+    /* Excluded from this release type: getFunctionRegistrations */
     /**
      * Execute a registered client function locally, through the same
      * FunctionRegistry path (result-size guard, error wrapping) as agent-invoked
@@ -713,6 +729,8 @@ export declare interface AgoClientEvents {
      * call running immediately.
      */
     "function:awaiting-approval": ClientFunctionInvocation;
+    /** A function was registered or unregistered, or the registry cleared. */
+    "functions:changed": ClientFunctionSchema[];
     "function:result": {
         invocationId: string;
         result: unknown;
@@ -785,6 +803,8 @@ export declare interface AgoConfig {
     defaultAgentId?: string;
     /** Permission name to apply to all requests (sent as `X-Widget-Permission`). Mirrors the widget's `window.AGO.permission`. */
     permission?: string;
+    /** Interface locale selected by the host app, sent as Accept-Language. Null clears the override. */
+    language?: string | null;
     /** User email for identification */
     userEmail?: string;
     /** JWT token for authenticated users */
@@ -862,6 +882,15 @@ export declare interface AgoConfig {
      * mode's `jsErrors` signal. See `client.reportError()` for caught errors.
      */
     errorWatcher?: boolean | ErrorWatcherOptions;
+    /** Mirror every registered client function into the browser's WebMCP registry
+     * (`document.modelContext`), so an external agent can call the same functions
+     * the in-app agent calls. Off by default; no-ops without WebMCP.
+     *
+     * A mirrored function runs immediately: the approval gate
+     * ({@link approvalPolicy}, `requiresApproval`) covers the agent loop only.
+     * Use `webmcp: false` on a definition to keep it out.
+     */
+    webmcp?: boolean;
 }
 
 declare type AgoEventHandler<K extends AgoEventName> = (data: AgoClientEvents[K]) => void;
@@ -1048,6 +1077,8 @@ export declare class AgoService {
     private fromEvent;
     /** Send a message and get a streaming response */
     sendMessage(content: string, options?: SendMessageOptions): Promise<AgoMessage>;
+    /** Transcribe an audio file into an editable draft. */
+    transcribeAudio(file: File, options?: TranscribeAudioOptions): Promise<AudioTranscription>;
     /**
      * Stop the turn that is generating: closes the stream and tells the backend to
      * stop generating. The partial answer is kept and the message ends as
@@ -1180,6 +1211,11 @@ declare type AgoStateSetResult = {
     result: "unchanged";
 };
 
+/** Editable text returned by `AgoClient.transcribeAudio`. */
+export declare interface AudioTranscription {
+    text: string;
+}
+
 /** One JavaScript error captured on the page (deduplicated, see `count`). */
 declare interface CapturedError {
     type: CapturedErrorType;
@@ -1219,22 +1255,11 @@ declare type CapturedErrorType = "error" | "unhandledrejection" | "console" | "m
  * client.registerFunction(fn);
  * ```
  */
-declare interface ClientFunctionDefinition {
+declare interface ClientFunctionDefinition extends ClientFunctionSettings {
     name: string;
     description: string;
     parameters: ClientFunctionSchema["parameters"];
     handler: ClientFunctionHandler;
-    /**
-     * Max serialized result size in bytes before the SDK truncates it to a
-     * flagged preview (default: `AgoConfig.maxFunctionResultBytes`, 50 000).
-     * `Infinity` disables the guard for this function.
-     */
-    maxResultBytes?: number;
-    /**
-     * Require explicit user approval before this function runs. See
-     * {@link AgoConfig.approvalPolicy} — pause mode only. ORs with the policy.
-     */
-    requiresApproval?: boolean;
 }
 
 /**
@@ -1253,20 +1278,7 @@ declare interface ClientFunctionInvocation {
  * Schema-plus-settings object accepted when registering a function: the schema
  * (minus `name`) and SDK-side options that are NOT sent to the backend.
  */
-declare type ClientFunctionRegisterOptions = Omit<ClientFunctionSchema, "name"> & {
-    /**
-     * Max serialized result size in bytes before the SDK truncates it to a
-     * flagged preview. Overrides the client-level default
-     * (`AgoConfig.maxFunctionResultBytes`, 50 000 by default). `Infinity`
-     * disables the guard for this function.
-     */
-    maxResultBytes?: number;
-    /**
-     * Require explicit user approval before this function runs. See
-     * {@link AgoConfig.approvalPolicy} — pause mode only. ORs with the policy.
-     */
-    requiresApproval?: boolean;
-};
+declare type ClientFunctionRegisterOptions = Omit<ClientFunctionSchema, "name"> & ClientFunctionSettings;
 
 /**
  * Schema for a client-side function that AGO can call
@@ -1293,6 +1305,28 @@ declare interface ClientFunctionSchema {
     };
 }
 
+/** SDK-side function settings that are never sent to the backend. */
+declare interface ClientFunctionSettings {
+    /**
+     * Max serialized result size in bytes before the SDK truncates it to a
+     * flagged preview. Overrides the client-level default
+     * (`AgoConfig.maxFunctionResultBytes`, 50 000 by default). `Infinity`
+     * disables the guard for this function.
+     */
+    maxResultBytes?: number;
+    /**
+     * Require explicit user approval before this function runs. See
+     * {@link AgoConfig.approvalPolicy} — pause mode only. ORs with the policy.
+     */
+    requiresApproval?: boolean;
+    /**
+     * WebMCP metadata, read only when the bridge is on (`AgoConfig.webmcp`).
+     * `false` keeps this function out of WebMCP while leaving it available to the
+     * in-app agent.
+     */
+    webmcp?: WebMCPToolMeta | false;
+}
+
 /** See {@link AgoConfig.clientFunctionsMode}. */
 declare type ClientFunctionsMode = "placeholder" | "pause";
 
@@ -1795,6 +1829,14 @@ export declare function provideAgo(options: AgoProvideOptions): {
     useValue: AgoService;
 };
 
+/**
+ * Registered function with handler
+ */
+declare interface RegisteredFunction extends ClientFunctionSettings {
+    schema: ClientFunctionSchema;
+    handler: ClientFunctionHandler;
+}
+
 /**
  * Hook run before a paused turn is resumed, so the app controls WHEN the
  * continuation fires (e.g. wait for the destination page to mount after a
@@ -1851,6 +1893,8 @@ declare interface SdkPermissionConfig {
     homePage?: SdkHomePageConfig;
     fileAttachmentsEnabled: boolean;
     voiceEnabled: boolean;
+    /** Whether audio uploads can be transcribed. Defaults to false on older backends. */
+    speechToTextEnabled: boolean;
 }
 
 /**
@@ -2163,4 +2207,29 @@ declare interface ToolCallTicketPrefill {
 
 declare type ToolCallType = "form" | "confirmation_input" | "status_message" | "progress_indicator" | "client_function" | "reasoning" | "mcp_ui_resource";
 
+/** Options for `AgoClient.transcribeAudio`. */
+export declare interface TranscribeAudioOptions {
+    /** Cancel the upload or stop waiting for its transcription. */
+    signal?: AbortSignal;
+}
+
+/** The MCP behavior hints AGO has no equivalent for. */
+declare interface WebMCPToolMeta {
+    /**
+     * Both default to `false`, so only set what is true: `readOnlyHint` marks a
+     * function that changes nothing, `untrustedContentHint` one whose result may
+     * carry third-party text.
+     */
+    annotations?: {
+        readOnlyHint?: boolean;
+        untrustedContentHint?: boolean;
+    };
+    /**
+     * This function navigates. The WebMCP call is held open until the function
+     * registry goes quiet, so the caller sees the destination page's tools rather
+     * than the departing page's. Already set on the built-in `navigateToPage`.
+     */
+    navigates?: boolean;
+}
+
 export { }

package/dist/angular.d.ts

@@ -109,7 +109,10 @@ declare class AgoClient {
      * `null` otherwise.
      */
     proactive: ProactiveController | null;
+    /** Removes the mirrored WebMCP tools; `null` when the bridge is off. */
+    private detachWebMCP;
     constructor(config: AgoConfig);
+    private attachWebMCPBridge;
     /**
      * Send a message and receive a streaming response
      */
@@ -221,6 +224,7 @@ declare class AgoClient {
      * (the agent decides what to do next). No-op if the invocation is unknown.
      */
     rejectFunction(invocationId: string): Promise<void>;
+    /* Excluded from this release type: runExternalFunction */
     /**
      * Get a page of conversations, newest-first. `pageSize` is capped at 100 by
      * the backend (default 50). Returns the `{ data, has_more, total }` envelope
@@ -240,11 +244,20 @@ declare class AgoClient {
      * `SSEHandler.parseToolCall` so persisted and streamed tool calls match.
      */
     private static mapPersistedToolCalls;
+    /**
+     * Transcribe an audio file into editable text (`POST /api/sdk/v1/audio/transcriptions`).
+     * Requires speech to text to be enabled for the tenant. Supports FLAC, MP3,
+     * MP4, MPEG, MPGA, M4A, OGG, WAV and WebM files up to 25 MB.
+     * The filename must include the matching extension. For a MediaRecorder blob,
+     * wrap it in a File with the recording's extension and MIME type.
+     * Show the returned text as a draft; call `sendMessage` when the user sends it.
+     */
+    transcribeAudio(file: File, options?: TranscribeAudioOptions): Promise<AudioTranscription>;
     /**
      * The tenant's SDK configuration (`GET /api/sdk/v1/config`): per-permission
      * agents, the ticket form the agent's `ago_ticketing` tool opens, and the
-     * file-attachment flag. The vanilla widget fetches it once, when a ticket
-     * form first appears in a conversation.
+     * file-attachment and speech-to-text flags. The vanilla widget fetches it
+     * once, when a ticket form first appears in a conversation.
      */
     getConfig(): Promise<SdkConfig>;
     /**
@@ -381,6 +394,9 @@ declare class AgoClient {
      * Get all registered function schemas
      */
     getRegisteredFunctions(): ClientFunctionSchema[];
+    /** The callback form of `functions:changed`. Returns an unsubscribe. */
+    onFunctionsChanged(listener: () => void): () => void;
+    /* Excluded from this release type: getFunctionRegistrations */
     /**
      * Execute a registered client function locally, through the same
      * FunctionRegistry path (result-size guard, error wrapping) as agent-invoked
@@ -713,6 +729,8 @@ export declare interface AgoClientEvents {
      * call running immediately.
      */
     "function:awaiting-approval": ClientFunctionInvocation;
+    /** A function was registered or unregistered, or the registry cleared. */
+    "functions:changed": ClientFunctionSchema[];
     "function:result": {
         invocationId: string;
         result: unknown;
@@ -785,6 +803,8 @@ export declare interface AgoConfig {
     defaultAgentId?: string;
     /** Permission name to apply to all requests (sent as `X-Widget-Permission`). Mirrors the widget's `window.AGO.permission`. */
     permission?: string;
+    /** Interface locale selected by the host app, sent as Accept-Language. Null clears the override. */
+    language?: string | null;
     /** User email for identification */
     userEmail?: string;
     /** JWT token for authenticated users */
@@ -862,6 +882,15 @@ export declare interface AgoConfig {
      * mode's `jsErrors` signal. See `client.reportError()` for caught errors.
      */
     errorWatcher?: boolean | ErrorWatcherOptions;
+    /** Mirror every registered client function into the browser's WebMCP registry
+     * (`document.modelContext`), so an external agent can call the same functions
+     * the in-app agent calls. Off by default; no-ops without WebMCP.
+     *
+     * A mirrored function runs immediately: the approval gate
+     * ({@link approvalPolicy}, `requiresApproval`) covers the agent loop only.
+     * Use `webmcp: false` on a definition to keep it out.
+     */
+    webmcp?: boolean;
 }
 
 declare type AgoEventHandler<K extends AgoEventName> = (data: AgoClientEvents[K]) => void;
@@ -1048,6 +1077,8 @@ export declare class AgoService {
     private fromEvent;
     /** Send a message and get a streaming response */
     sendMessage(content: string, options?: SendMessageOptions): Promise<AgoMessage>;
+    /** Transcribe an audio file into an editable draft. */
+    transcribeAudio(file: File, options?: TranscribeAudioOptions): Promise<AudioTranscription>;
     /**
      * Stop the turn that is generating: closes the stream and tells the backend to
      * stop generating. The partial answer is kept and the message ends as
@@ -1180,6 +1211,11 @@ declare type AgoStateSetResult = {
     result: "unchanged";
 };
 
+/** Editable text returned by `AgoClient.transcribeAudio`. */
+export declare interface AudioTranscription {
+    text: string;
+}
+
 /** One JavaScript error captured on the page (deduplicated, see `count`). */
 declare interface CapturedError {
     type: CapturedErrorType;
@@ -1219,22 +1255,11 @@ declare type CapturedErrorType = "error" | "unhandledrejection" | "console" | "m
  * client.registerFunction(fn);
  * ```
  */
-declare interface ClientFunctionDefinition {
+declare interface ClientFunctionDefinition extends ClientFunctionSettings {
     name: string;
     description: string;
     parameters: ClientFunctionSchema["parameters"];
     handler: ClientFunctionHandler;
-    /**
-     * Max serialized result size in bytes before the SDK truncates it to a
-     * flagged preview (default: `AgoConfig.maxFunctionResultBytes`, 50 000).
-     * `Infinity` disables the guard for this function.
-     */
-    maxResultBytes?: number;
-    /**
-     * Require explicit user approval before this function runs. See
-     * {@link AgoConfig.approvalPolicy} — pause mode only. ORs with the policy.
-     */
-    requiresApproval?: boolean;
 }
 
 /**
@@ -1253,20 +1278,7 @@ declare interface ClientFunctionInvocation {
  * Schema-plus-settings object accepted when registering a function: the schema
  * (minus `name`) and SDK-side options that are NOT sent to the backend.
  */
-declare type ClientFunctionRegisterOptions = Omit<ClientFunctionSchema, "name"> & {
-    /**
-     * Max serialized result size in bytes before the SDK truncates it to a
-     * flagged preview. Overrides the client-level default
-     * (`AgoConfig.maxFunctionResultBytes`, 50 000 by default). `Infinity`
-     * disables the guard for this function.
-     */
-    maxResultBytes?: number;
-    /**
-     * Require explicit user approval before this function runs. See
-     * {@link AgoConfig.approvalPolicy} — pause mode only. ORs with the policy.
-     */
-    requiresApproval?: boolean;
-};
+declare type ClientFunctionRegisterOptions = Omit<ClientFunctionSchema, "name"> & ClientFunctionSettings;
 
 /**
  * Schema for a client-side function that AGO can call
@@ -1293,6 +1305,28 @@ declare interface ClientFunctionSchema {
     };
 }
 
+/** SDK-side function settings that are never sent to the backend. */
+declare interface ClientFunctionSettings {
+    /**
+     * Max serialized result size in bytes before the SDK truncates it to a
+     * flagged preview. Overrides the client-level default
+     * (`AgoConfig.maxFunctionResultBytes`, 50 000 by default). `Infinity`
+     * disables the guard for this function.
+     */
+    maxResultBytes?: number;
+    /**
+     * Require explicit user approval before this function runs. See
+     * {@link AgoConfig.approvalPolicy} — pause mode only. ORs with the policy.
+     */
+    requiresApproval?: boolean;
+    /**
+     * WebMCP metadata, read only when the bridge is on (`AgoConfig.webmcp`).
+     * `false` keeps this function out of WebMCP while leaving it available to the
+     * in-app agent.
+     */
+    webmcp?: WebMCPToolMeta | false;
+}
+
 /** See {@link AgoConfig.clientFunctionsMode}. */
 declare type ClientFunctionsMode = "placeholder" | "pause";
 
@@ -1795,6 +1829,14 @@ export declare function provideAgo(options: AgoProvideOptions): {
     useValue: AgoService;
 };
 
+/**
+ * Registered function with handler
+ */
+declare interface RegisteredFunction extends ClientFunctionSettings {
+    schema: ClientFunctionSchema;
+    handler: ClientFunctionHandler;
+}
+
 /**
  * Hook run before a paused turn is resumed, so the app controls WHEN the
  * continuation fires (e.g. wait for the destination page to mount after a
@@ -1851,6 +1893,8 @@ declare interface SdkPermissionConfig {
     homePage?: SdkHomePageConfig;
     fileAttachmentsEnabled: boolean;
     voiceEnabled: boolean;
+    /** Whether audio uploads can be transcribed. Defaults to false on older backends. */
+    speechToTextEnabled: boolean;
 }
 
 /**
@@ -2163,4 +2207,29 @@ declare interface ToolCallTicketPrefill {
 
 declare type ToolCallType = "form" | "confirmation_input" | "status_message" | "progress_indicator" | "client_function" | "reasoning" | "mcp_ui_resource";
 
+/** Options for `AgoClient.transcribeAudio`. */
+export declare interface TranscribeAudioOptions {
+    /** Cancel the upload or stop waiting for its transcription. */
+    signal?: AbortSignal;
+}
+
+/** The MCP behavior hints AGO has no equivalent for. */
+declare interface WebMCPToolMeta {
+    /**
+     * Both default to `false`, so only set what is true: `readOnlyHint` marks a
+     * function that changes nothing, `untrustedContentHint` one whose result may
+     * carry third-party text.
+     */
+    annotations?: {
+        readOnlyHint?: boolean;
+        untrustedContentHint?: boolean;
+    };
+    /**
+     * This function navigates. The WebMCP call is held open until the function
+     * registry goes quiet, so the caller sees the destination page's tools rather
+     * than the departing page's. Already set on the built-in `navigateToPage`.
+     */
+    navigates?: boolean;
+}
+
 export { }