@useago/sdk 1.12.0 → 1.13.0

package/dist/index.d.cts

@@ -131,7 +131,10 @@ export 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
      */
@@ -243,6 +246,7 @@ export 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
@@ -262,11 +266,20 @@ export 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>;
     /**
@@ -403,6 +416,9 @@ export 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
@@ -735,6 +751,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;
@@ -807,6 +825,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 */
@@ -884,6 +904,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;
 }
 
 /**
@@ -1200,6 +1229,11 @@ declare interface ApiErrorResponse {
  */
 export declare function attachAutoContinueAfterNavigation(client: AgoClient, options?: AgoAutoContinueOptions | (() => AgoAutoContinueOptions | undefined)): () => void;
 
+/** Editable text returned by `AgoClient.transcribeAudio`. */
+export declare interface AudioTranscription {
+    text: string;
+}
+
 /**
  * Auto-detect AGO configuration from the DOM environment.
  *
@@ -1303,22 +1337,11 @@ export declare type ClientFunction = (args: Record<string, unknown>) => Promise<
  * client.registerFunction(fn);
  * ```
  */
-export declare interface ClientFunctionDefinition {
+export 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;
 }
 
 /**
@@ -1337,20 +1360,7 @@ export 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.
  */
-export 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;
-};
+export declare type ClientFunctionRegisterOptions = Omit<ClientFunctionSchema, "name"> & ClientFunctionSettings;
 
 /**
  * Schema for a client-side function that AGO can call
@@ -1377,6 +1387,28 @@ export 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}. */
 export declare type ClientFunctionsMode = "placeholder" | "pause";
 
@@ -2045,7 +2077,11 @@ export declare interface FunctionDefinition {
 export declare class FunctionRegistry {
     private functions;
     private defaultMaxResultBytes;
+    private changeListeners;
     constructor(options?: FunctionRegistryOptions);
+    /** Fires on registrations, unregistrations and clears. */
+    onChange(listener: () => void): () => void;
+    private emitChange;
     /** Update the client-level result-size ceiling at runtime. */
     setDefaultMaxResultBytes(bytes: number): void;
     /**
@@ -2076,6 +2112,13 @@ export declare class FunctionRegistry {
      * Get all registered function schemas (for sending to backend)
      */
     getSchemas(): ClientFunctionSchema[];
+    /**
+     * Every registration, name included, with the SDK-side settings
+     * {@link getSchemas} drops.
+     */
+    getAll(): Array<RegisteredFunction & {
+        name: string;
+    }>;
     /**
      * Execute a registered function
      */
@@ -2587,13 +2630,9 @@ export declare interface ProactiveTriggerWhen {
 /**
  * Registered function with handler
  */
-export declare interface RegisteredFunction {
+export declare interface RegisteredFunction extends ClientFunctionSettings {
     schema: ClientFunctionSchema;
     handler: ClientFunctionHandler;
-    /** Per-function result-size ceiling; falls back to the registry default. */
-    maxResultBytes?: number;
-    /** Require explicit user approval before running (pause mode only). */
-    requiresApproval?: boolean;
 }
 
 /**
@@ -2622,7 +2661,7 @@ export declare function safeAttachmentUrl(url?: string): string | undefined;
 export declare const scrollToElement: ClientFunctionDefinition;
 
 /** Response of `GET /api/sdk/v1/config` (see `AgoClient.getConfig`). */
-declare interface SdkConfig {
+export declare interface SdkConfig {
     permissions: SdkPermissionConfig[];
     proactive: {
         enabled: boolean;
@@ -2653,7 +2692,7 @@ declare interface SdkHomeStarter {
 }
 
 /** One permission's configuration in {@link SdkConfig}. */
-declare interface SdkPermissionConfig {
+export declare interface SdkPermissionConfig {
     id?: string;
     name?: string;
     displayName?: string;
@@ -2666,6 +2705,8 @@ declare interface SdkPermissionConfig {
     homePage?: SdkHomePageConfig;
     fileAttachmentsEnabled: boolean;
     voiceEnabled: boolean;
+    /** Whether audio uploads can be transcribed. Defaults to false on older backends. */
+    speechToTextEnabled: boolean;
 }
 
 /**
@@ -3254,6 +3295,12 @@ export declare type ToolCallType = "form" | "confirmation_input" | "status_messa
  */
 export declare const trackEvent: ClientFunctionDefinition;
 
+/** Options for `AgoClient.transcribeAudio`. */
+export declare interface TranscribeAudioOptions {
+    /** Cancel the upload or stop waiting for its transcription. */
+    signal?: AbortSignal;
+}
+
 /**
  * Validate an AgoConfig at the public API boundary.
  *
@@ -3277,6 +3324,25 @@ export declare const trackEvent: ClientFunctionDefinition;
  */
 export declare function validateConfig(config: unknown, context?: string): asserts config is AgoConfig;
 
+/** The MCP behavior hints AGO has no equivalent for. */
+export 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;
+}
+
 /**
  * Attach a handler to a pre-built function definition.
  *

package/dist/index.d.ts

@@ -131,7 +131,10 @@ export 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
      */
@@ -243,6 +246,7 @@ export 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
@@ -262,11 +266,20 @@ export 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>;
     /**
@@ -403,6 +416,9 @@ export 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
@@ -735,6 +751,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;
@@ -807,6 +825,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 */
@@ -884,6 +904,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;
 }
 
 /**
@@ -1200,6 +1229,11 @@ declare interface ApiErrorResponse {
  */
 export declare function attachAutoContinueAfterNavigation(client: AgoClient, options?: AgoAutoContinueOptions | (() => AgoAutoContinueOptions | undefined)): () => void;
 
+/** Editable text returned by `AgoClient.transcribeAudio`. */
+export declare interface AudioTranscription {
+    text: string;
+}
+
 /**
  * Auto-detect AGO configuration from the DOM environment.
  *
@@ -1303,22 +1337,11 @@ export declare type ClientFunction = (args: Record<string, unknown>) => Promise<
  * client.registerFunction(fn);
  * ```
  */
-export declare interface ClientFunctionDefinition {
+export 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;
 }
 
 /**
@@ -1337,20 +1360,7 @@ export 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.
  */
-export 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;
-};
+export declare type ClientFunctionRegisterOptions = Omit<ClientFunctionSchema, "name"> & ClientFunctionSettings;
 
 /**
  * Schema for a client-side function that AGO can call
@@ -1377,6 +1387,28 @@ export 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}. */
 export declare type ClientFunctionsMode = "placeholder" | "pause";
 
@@ -2045,7 +2077,11 @@ export declare interface FunctionDefinition {
 export declare class FunctionRegistry {
     private functions;
     private defaultMaxResultBytes;
+    private changeListeners;
     constructor(options?: FunctionRegistryOptions);
+    /** Fires on registrations, unregistrations and clears. */
+    onChange(listener: () => void): () => void;
+    private emitChange;
     /** Update the client-level result-size ceiling at runtime. */
     setDefaultMaxResultBytes(bytes: number): void;
     /**
@@ -2076,6 +2112,13 @@ export declare class FunctionRegistry {
      * Get all registered function schemas (for sending to backend)
      */
     getSchemas(): ClientFunctionSchema[];
+    /**
+     * Every registration, name included, with the SDK-side settings
+     * {@link getSchemas} drops.
+     */
+    getAll(): Array<RegisteredFunction & {
+        name: string;
+    }>;
     /**
      * Execute a registered function
      */
@@ -2587,13 +2630,9 @@ export declare interface ProactiveTriggerWhen {
 /**
  * Registered function with handler
  */
-export declare interface RegisteredFunction {
+export declare interface RegisteredFunction extends ClientFunctionSettings {
     schema: ClientFunctionSchema;
     handler: ClientFunctionHandler;
-    /** Per-function result-size ceiling; falls back to the registry default. */
-    maxResultBytes?: number;
-    /** Require explicit user approval before running (pause mode only). */
-    requiresApproval?: boolean;
 }
 
 /**
@@ -2622,7 +2661,7 @@ export declare function safeAttachmentUrl(url?: string): string | undefined;
 export declare const scrollToElement: ClientFunctionDefinition;
 
 /** Response of `GET /api/sdk/v1/config` (see `AgoClient.getConfig`). */
-declare interface SdkConfig {
+export declare interface SdkConfig {
     permissions: SdkPermissionConfig[];
     proactive: {
         enabled: boolean;
@@ -2653,7 +2692,7 @@ declare interface SdkHomeStarter {
 }
 
 /** One permission's configuration in {@link SdkConfig}. */
-declare interface SdkPermissionConfig {
+export declare interface SdkPermissionConfig {
     id?: string;
     name?: string;
     displayName?: string;
@@ -2666,6 +2705,8 @@ declare interface SdkPermissionConfig {
     homePage?: SdkHomePageConfig;
     fileAttachmentsEnabled: boolean;
     voiceEnabled: boolean;
+    /** Whether audio uploads can be transcribed. Defaults to false on older backends. */
+    speechToTextEnabled: boolean;
 }
 
 /**
@@ -3254,6 +3295,12 @@ export declare type ToolCallType = "form" | "confirmation_input" | "status_messa
  */
 export declare const trackEvent: ClientFunctionDefinition;
 
+/** Options for `AgoClient.transcribeAudio`. */
+export declare interface TranscribeAudioOptions {
+    /** Cancel the upload or stop waiting for its transcription. */
+    signal?: AbortSignal;
+}
+
 /**
  * Validate an AgoConfig at the public API boundary.
  *
@@ -3277,6 +3324,25 @@ export declare const trackEvent: ClientFunctionDefinition;
  */
 export declare function validateConfig(config: unknown, context?: string): asserts config is AgoConfig;
 
+/** The MCP behavior hints AGO has no equivalent for. */
+export 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;
+}
+
 /**
  * Attach a handler to a pre-built function definition.
  *