@useago/sdk 1.12.0 → 1.13.1

package/dist/react.d.ts

@@ -1,5 +1,6 @@
 import { default as default_2 } from 'react';
 import { ForwardRefExoticComponent } from 'react';
+import { JSX as JSX_2 } from 'react/jsx-runtime';
 import { RefAttributes } from 'react';
 
 export declare interface ActivityEntry {
@@ -115,6 +116,8 @@ declare class AgoClient {
     private config;
     /** Conversations already warned about an empty reply (one warning each). */
     private warnedEmptyConversations;
+    /** Client functions the backend has accepted from a WebMCP call report. */
+    private declaredExternally;
     /** Whether the placeholder-mode page-data warning has already been logged. */
     private warnedPageDataPlaceholder;
     /** `readPageData` companions this SDK registered, so cleanup only removes its own. */
@@ -149,7 +152,12 @@ declare class AgoClient {
      * `null` otherwise.
      */
     proactive: ProactiveController | null;
+    /** Removes the mirrored WebMCP tools; `null` when the bridge is off. */
+    private detachWebMCP;
+    /** The `listPages` companion is live. */
+    private listPagesRegistered;
     constructor(config: AgoConfig);
+    private attachWebMCPBridge;
     /**
      * Send a message and receive a streaming response
      */
@@ -261,6 +269,12 @@ 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 */
+    /**
+     * Best-effort analytics for one WebMCP call. No agent: the caller is someone
+     * else's agent and cannot be known from `execute`.
+     */
+    private reportExternalCall;
     /**
      * Get a page of conversations, newest-first. `pageSize` is capped at 100 by
      * the backend (default 50). Returns the `{ data, has_more, total }` envelope
@@ -280,11 +294,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>;
     /**
@@ -421,6 +444,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
@@ -443,14 +469,15 @@ declare class AgoClient {
      * page of an entity. Flat arguments only: nested object parameters are not
      * reliably rendered to the model, so placeholders must not be named `page`.
      *
+     * For a large table, `{ catalogue: "onDemand" }` moves the route descriptions
+     * into a read-only `listPages` companion, leaving only the page names in the
+     * per-message schema. Routes may carry a `section` to group that companion.
+     *
      * @param navigate - A callback that performs the navigation (e.g. react-router's navigate)
      * @param routes - Map of route names to paths, with descriptions for the LLM
+     * @param opts - Where the catalogue lives; `"inline"` by default
      */
-    registerNavigationFunction(navigate: (path: string) => void, routes: Array<{
-        name: string;
-        path: string;
-        description: string;
-    }>): void;
+    registerNavigationFunction(navigate: (path: string) => void, routes: NavRoute[], opts?: AgoNavigationOptions): void;
     /**
      * Unregister the navigation function and its `current-page` context provider.
      */
@@ -753,6 +780,8 @@ 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;
@@ -825,6 +854,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 */
@@ -902,6 +933,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;
 }
 
 /**
@@ -945,6 +985,16 @@ export declare interface AgoMessage {
     createdAt: Date;
 }
 
+/**
+ * Where the route catalogue lives: `"inline"` (default) in `navigateToPage`'s
+ * description, or `"onDemand"` in a `listPages` companion's result.
+ */
+export declare type AgoNavigationOptions = {
+    catalogue?: "inline";
+} | {
+    catalogue: "onDemand";
+};
+
 /**
  * Prebuilt proactive-nudge toast: a small, always-dismissable bubble anchored
  * near the chat launcher. Never modal — it never blocks the page. Renders the
@@ -1118,6 +1168,8 @@ export declare interface AgoRoute {
     name: string;
     path: string;
     description: string;
+    /** Groups this route for `catalogue: "onDemand"`. Unused otherwise. */
+    section?: string;
 }
 
 /**
@@ -1170,6 +1222,11 @@ declare type AgoStateSetResult = {
     result: "unchanged";
 };
 
+/** Editable text returned by `AgoClient.transcribeAudio`. */
+declare interface AudioTranscription {
+    text: string;
+}
+
 /** One JavaScript error captured on the page (deduplicated, see `count`). */
 declare interface CapturedError {
     type: CapturedErrorType;
@@ -1217,6 +1274,12 @@ export declare interface ChatInputProps {
     disabled?: boolean;
     placeholder?: string;
     allowFiles?: boolean;
+    /** Microphone, live waveform and draft transcription. Uses the tenant flag. */
+    speechToText?: boolean | SpeechToTextOptions;
+    /** For dictation; otherwise uses AgoProvider's client. */
+    client?: AgoClient;
+    /** Cancels dictation when the conversation or page changes. */
+    scopeKey?: string;
     className?: string;
 }
 
@@ -1255,6 +1318,8 @@ export declare interface ChatWidgetProps {
     placeholder?: string;
     /** Enable file attachments */
     allowFiles?: boolean;
+    /** Microphone, live waveform and draft transcription. Checks the tenant flag. */
+    speechToText?: boolean | SpeechToTextOptions;
     /**
      * While the agent is answering, turn the send button into a Stop button that
      * interrupts the turn. Defaults to `true`.
@@ -1352,22 +1417,11 @@ export declare interface ChatWidgetProps {
  * 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;
 }
 
 /**
@@ -1386,20 +1440,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
@@ -1426,6 +1467,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";
 
@@ -1556,6 +1619,8 @@ declare interface CreateTicketResult {
 
 export declare const DEFAULT_MESSAGE_FEEDBACK_LABELS: MessageFeedbackLabels;
 
+export declare const DEFAULT_SPEECH_TO_TEXT_LABELS: SpeechToTextLabels;
+
 /**
  * Compute which required fields are still empty and whether the form is complete.
  * Pure — the single home for the "required + non-empty" rule, shared by the update
@@ -2007,6 +2072,15 @@ declare interface MockAgoClientOptions {
 
 declare type MockFn = (...args: any[]) => any;
 
+/** A navigable page. `path` may carry `:param` placeholders. */
+declare interface NavRoute {
+    name: string;
+    path: string;
+    description: string;
+    /** Only read under `catalogue: "onDemand"`. */
+    section?: string;
+}
+
 /**
  * Optional action attached to a nudge. Accepting a `functionName` action
  * executes the registered client function (same `FunctionRegistry` path as
@@ -2199,6 +2273,14 @@ declare interface ProactiveTriggerWhen {
     fieldErrors?: Record<string, number>;
 }
 
+/**
+ * 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
@@ -2255,6 +2337,8 @@ declare interface SdkPermissionConfig {
     homePage?: SdkHomePageConfig;
     fileAttachmentsEnabled: boolean;
     voiceEnabled: boolean;
+    /** Whether audio uploads can be transcribed. Defaults to false on older backends. */
+    speechToTextEnabled: boolean;
 }
 
 /**
@@ -2411,6 +2495,42 @@ declare interface SignalsSnapshot {
     pageState: Record<string, unknown> | null;
 }
 
+/** Ready-made microphone, live waveform, cancel/confirm controls and transcription. */
+export declare function SpeechToTextButton(props: SpeechToTextButtonProps): JSX_2.Element;
+
+export declare interface SpeechToTextButtonProps {
+    /** Uses AgoProvider's client when omitted. */
+    client?: AgoClient;
+    onTranscript: (text: string) => void;
+    /** Use this to hide or disable your editor while dictation is active. */
+    onBusyChange?: (busy: boolean) => void;
+    disabled?: boolean;
+    /** Cancels dictation when the conversation or page changes. */
+    scopeKey?: string;
+    labels?: Partial<SpeechToTextLabels>;
+    className?: string;
+}
+
+/** Strings used by the microphone control in every widget. */
+export declare interface SpeechToTextLabels {
+    start: string;
+    finish: string;
+    cancel: string;
+    requesting: string;
+    recording: string;
+    transcribing: string;
+    limitApproaching: string;
+    permissionDenied: string;
+    recordingFailed: string;
+    tooLarge: string;
+    noSpeech: string;
+    transcriptionFailed: string;
+}
+
+export declare interface SpeechToTextOptions {
+    labels?: Partial<SpeechToTextLabels>;
+}
+
 /**
  * SSE stream chunk data
  */
@@ -2655,6 +2775,12 @@ declare interface ToolCallTicketPrefill {
 
 declare type ToolCallType = "form" | "confirmation_input" | "status_message" | "progress_indicator" | "client_function" | "reasoning" | "mcp_ui_resource";
 
+/** Options for `AgoClient.transcribeAudio`. */
+declare interface TranscribeAudioOptions {
+    /** Cancel the upload or stop waiting for its transcription. */
+    signal?: AbortSignal;
+}
+
 /**
  * Hook to create and manage an AgoClient instance
  *
@@ -2854,6 +2980,11 @@ export declare interface UseAgoFunctionOptions {
      * See `AgoConfig.approvalPolicy`.
      */
     requiresApproval?: boolean;
+    /**
+     * WebMCP metadata, read only when the bridge is on (`AgoConfig.webmcp`).
+     * `false` keeps this function out of WebMCP.
+     */
+    webmcp?: WebMCPToolMeta | false;
 }
 
 /**
@@ -2867,8 +2998,11 @@ export declare interface UseAgoFunctionOptions {
  *   { name: "settings", path: "/settings", description: "User settings" },
  * ]);
  * ```
+ *
+ * For a large route table, `{ catalogue: "onDemand" }` keeps the descriptions
+ * out of every message.
  */
-export declare function useAgoNavigation(navigate: (path: string) => void, routes: AgoRoute[]): void;
+export declare function useAgoNavigation(navigate: (path: string) => void, routes: AgoRoute[], opts?: AgoNavigationOptions): void;
 
 export declare type UseAgoOptions = AgoConfig;
 
@@ -3191,4 +3325,23 @@ export declare interface UseSheetResult {
     toggle: (cause?: SheetChangeCause) => void;
 }
 
+/** 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 { }