@useago/sdk 1.12.0 → 1.13.0

package/dist/vue.d.ts

@@ -100,7 +100,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
      */
@@ -212,6 +215,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
@@ -231,11 +235,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>;
     /**
@@ -372,6 +385,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
@@ -704,6 +720,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;
@@ -776,6 +794,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 */
@@ -853,6 +873,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;
@@ -1058,6 +1087,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;
@@ -1097,22 +1131,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;
 }
 
 /**
@@ -1131,20 +1154,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
@@ -1171,6 +1181,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";
 
@@ -1656,6 +1688,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
@@ -1712,6 +1752,8 @@ declare interface SdkPermissionConfig {
     homePage?: SdkHomePageConfig;
     fileAttachmentsEnabled: boolean;
     voiceEnabled: boolean;
+    /** Whether audio uploads can be transcribed. Defaults to false on older backends. */
+    speechToTextEnabled: boolean;
 }
 
 /**
@@ -2047,6 +2089,12 @@ declare type ToolCallType = "form" | "confirmation_input" | "status_message" | "
 
 declare type ToolCallType_2 = "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;
+}
+
 /**
  * Get or create an AgoClient.
  *
@@ -2095,6 +2143,16 @@ export declare function useAgoFunction(name: string, options: {
      * `Infinity` disables the guard for this function.
      */
     maxResultBytes?: number;
+    /**
+     * Require explicit user approval before this function runs (pause mode
+     * only). 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;
 }): void;
 
 /**
@@ -3029,4 +3087,23 @@ export declare interface UseProactiveNudgeResult {
     dismiss: () => 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 { }

package/dist/vue.js

@@ -1,47 +1,47 @@
-import { n as A, t as D } from "./types-Ct1hlKwg.js";
+import { n as I, t as D } from "./types-Q7t1peH-.js";
 import { computed as L, inject as M, onMounted as p, onScopeDispose as R, onUnmounted as C, ref as d, shallowRef as F } from "vue";
-var N = /* @__PURE__ */ Symbol("ago-client"), q = { install(t, n) {
-  const e = new A(n);
-  t.provide(N, e);
+var N = /* @__PURE__ */ Symbol("ago-client"), _ = { install(t, e) {
+  const n = new I(e);
+  t.provide(N, n);
 } };
 function m(t) {
-  if (t) return new A(t);
-  const n = M(N);
-  if (!n) throw new Error("useAgo(): no AgoClient found. Either pass config or install AgoPlugin.");
-  return n;
+  if (t) return new I(t);
+  const e = M(N);
+  if (!e) throw new Error("useAgo(): no AgoClient found. Either pass config or install AgoPlugin.");
+  return e;
 }
 function k(t = {}) {
-  const n = t.client ?? m(), e = d([]), a = d(t.conversationId), o = d(!1), i = d(null), c = (s) => {
+  const e = t.client ?? m(), n = d([]), a = d(t.conversationId), o = d(!1), i = d(null), c = (s) => {
     a.value || (a.value = s.conversationId);
   }, g = (s) => {
-    const u = e.value.findIndex((v) => v.id === s.messageId);
-    u >= 0 && (e.value[u] = {
-      ...e.value[u],
-      content: e.value[u].content + s.content
+    const u = n.value.findIndex((v) => v.id === s.messageId);
+    u >= 0 && (n.value[u] = {
+      ...n.value[u],
+      content: n.value[u].content + s.content
     });
-  }, h = (s) => {
-    const u = e.value.findIndex((v) => v.id === s.id);
-    u >= 0 ? e.value[u] = s : e.value.push(s), o.value = !1;
   }, w = (s) => {
+    const u = n.value.findIndex((v) => v.id === s.id);
+    u >= 0 ? n.value[u] = s : n.value.push(s), o.value = !1;
+  }, h = (s) => {
     i.value = new Error(s.error), o.value = !1;
   }, r = () => {
     let s = -1;
-    for (let u = e.value.length - 1; u >= 0; u--) {
-      const v = e.value[u];
+    for (let u = n.value.length - 1; u >= 0; u--) {
+      const v = n.value[u];
       if (v.role === "assistant" && (v.status === "IN_PROGRESS" || v.status === "WAITING_CLIENT")) {
         s = u;
         break;
       }
     }
-    s >= 0 && (e.value[s].content ? e.value[s] = {
-      ...e.value[s],
+    s >= 0 && (n.value[s].content ? n.value[s] = {
+      ...n.value[s],
       status: "CANCELED"
-    } : e.value.splice(s, 1)), o.value = !1;
+    } : n.value.splice(s, 1)), o.value = !1;
   };
   p(() => {
-    n.on("message:start", c), n.on("message:chunk", g), n.on("message:complete", h), n.on("message:error", w), n.on("message:stopped", r);
+    e.on("message:start", c), e.on("message:chunk", g), e.on("message:complete", w), e.on("message:error", h), e.on("message:stopped", r);
   }), C(() => {
-    n.off("message:start", c), n.off("message:chunk", g), n.off("message:complete", h), n.off("message:error", w), n.off("message:stopped", r);
+    e.off("message:start", c), e.off("message:chunk", g), e.off("message:complete", w), e.off("message:error", h), e.off("message:stopped", r);
   });
   async function l(s, u) {
     o.value = !0, i.value = null;
@@ -60,31 +60,31 @@ function k(t = {}) {
       status: "IN_PROGRESS",
       createdAt: /* @__PURE__ */ new Date()
     };
-    e.value.push(v, S);
+    n.value.push(v, S);
     try {
-      const f = await n.sendMessage(s, {
+      const f = await e.sendMessage(s, {
         conversationId: a.value,
         files: u
       });
-      f.conversationId && !a.value && (a.value = f.conversationId), e.value = e.value.filter((b) => !b.id.startsWith("temp-"));
-      const I = {
+      f.conversationId && !a.value && (a.value = f.conversationId), n.value = n.value.filter((A) => !A.id.startsWith("temp-"));
+      const b = {
         ...v,
         id: v.id.replace("temp-", "user-"),
         conversationId: f.conversationId
       };
-      return e.value.some((b) => b.id === f.id) ? e.value.push(I) : e.value.push(I, f), f;
+      return n.value.some((A) => A.id === f.id) ? n.value.push(b) : n.value.push(b, f), f;
     } catch (f) {
-      return i.value = f instanceof Error ? f : /* @__PURE__ */ new Error("Failed to send"), o.value = !1, e.value = e.value.filter((I) => !I.id.startsWith("temp-")), null;
+      return i.value = f instanceof Error ? f : /* @__PURE__ */ new Error("Failed to send"), o.value = !1, n.value = n.value.filter((b) => !b.id.startsWith("temp-")), null;
     }
   }
   async function E() {
-    await n.stop();
+    await e.stop();
   }
   function y() {
-    e.value = [], a.value = void 0, i.value = null;
+    n.value = [], a.value = void 0, i.value = null;
   }
   return {
-    messages: e,
+    messages: n,
     isLoading: o,
     error: i,
     conversationId: a,
@@ -94,79 +94,79 @@ function k(t = {}) {
   };
 }
 function P(t = {}) {
-  const n = t.client ?? m(), e = t.autoLoad ?? !0, a = d([]), o = d(null), i = d(!1), c = d(null);
+  const e = t.client ?? m(), n = t.autoLoad ?? !0, a = d([]), o = d(null), i = d(!1), c = d(null);
   async function g() {
     i.value = !0, c.value = null;
     try {
-      a.value = (await n.getConversations()).data;
+      a.value = (await e.getConversations()).data;
     } catch (r) {
       c.value = r instanceof Error ? r : /* @__PURE__ */ new Error("Failed to load conversations");
     } finally {
       i.value = !1;
     }
   }
-  async function h(r) {
+  async function w(r) {
     i.value = !0, c.value = null;
     try {
-      o.value = await n.getConversation(r);
+      o.value = await e.getConversation(r);
     } catch (l) {
       c.value = l instanceof Error ? l : /* @__PURE__ */ new Error("Failed to load conversation");
     } finally {
       i.value = !1;
     }
   }
-  function w() {
+  function h() {
     o.value = null;
   }
   return p(() => {
-    e && g();
+    n && g();
   }), {
     conversations: a,
     currentConversation: o,
     isLoading: i,
     error: c,
-    selectConversation: h,
-    startNewConversation: w,
+    selectConversation: w,
+    startNewConversation: h,
     refreshConversations: g
   };
 }
 function O(t = {}) {
-  const n = k({
+  const e = k({
     client: t.client,
     conversationId: t.conversationId
-  }), e = P({
+  }), n = P({
     client: t.client,
     autoLoad: t.autoLoad
-  }), a = L(() => n.error.value || e.error.value);
+  }), a = L(() => e.error.value || n.error.value);
   return {
-    messages: n.messages,
-    isLoading: n.isLoading,
+    messages: e.messages,
+    isLoading: e.isLoading,
     error: a,
-    sendMessage: n.sendMessage,
-    stop: n.stop,
-    clearMessages: n.clearMessages,
-    conversationId: n.conversationId,
-    conversations: e.conversations,
-    currentConversation: e.currentConversation,
-    isConversationsLoading: e.isLoading,
-    selectConversation: e.selectConversation,
-    startNewConversation: e.startNewConversation,
-    refreshConversations: e.refreshConversations
+    sendMessage: e.sendMessage,
+    stop: e.stop,
+    clearMessages: e.clearMessages,
+    conversationId: e.conversationId,
+    conversations: n.conversations,
+    currentConversation: n.currentConversation,
+    isConversationsLoading: n.isLoading,
+    selectConversation: n.selectConversation,
+    startNewConversation: n.startNewConversation,
+    refreshConversations: n.refreshConversations
   };
 }
 function G(t = {}) {
-  const n = t.client ?? m(), e = d({}), a = d(!1), o = d(null), i = /* @__PURE__ */ new Map();
+  const e = t.client ?? m(), n = d({}), a = d(!1), o = d(null), i = /* @__PURE__ */ new Map();
   function c(r) {
     const l = (i.get(r) ?? 0) + 1;
     return i.set(r, l), l;
   }
   const g = (r, l) => i.get(r) === l;
-  async function h(r, l, E) {
+  async function w(r, l, E) {
     const y = c(r);
     a.value = !0, o.value = null;
     try {
-      await n.submitFeedback(r, l, E), g(r, y) && (e.value = {
-        ...e.value,
+      await e.submitFeedback(r, l, E), g(r, y) && (n.value = {
+        ...n.value,
         [r]: l
       });
     } catch (s) {
@@ -176,13 +176,13 @@ function G(t = {}) {
       a.value = !1;
     }
   }
-  async function w(r, l, E) {
+  async function h(r, l, E) {
     const y = c(r);
     a.value = !0, o.value = null;
     try {
-      const s = await n.submitConversationFeedback(r, l, E);
-      return g(r, y) && (e.value = {
-        ...e.value,
+      const s = await e.submitConversationFeedback(r, l, E);
+      return g(r, y) && (n.value = {
+        ...n.value,
         [s]: l
       }), s;
     } catch (s) {
@@ -193,83 +193,85 @@ function G(t = {}) {
     }
   }
   return {
-    ratings: e,
+    ratings: n,
     isSubmitting: a,
     error: o,
-    submitFeedback: h,
-    submitConversationFeedback: w
+    submitFeedback: w,
+    submitConversationFeedback: h
   };
 }
-function B(t, n) {
-  const e = m();
+function B(t, e) {
+  const n = m();
   p(() => {
-    e.registerFunction(t, n.handler, {
-      description: n.description,
-      parameters: n.parameters,
-      maxResultBytes: n.maxResultBytes
+    n.registerFunction(t, e.handler, {
+      description: e.description,
+      parameters: e.parameters,
+      maxResultBytes: e.maxResultBytes,
+      requiresApproval: e.requiresApproval,
+      webmcp: e.webmcp
     });
   }), C(() => {
-    e.unregisterFunction(t);
+    n.unregisterFunction(t);
   });
 }
-function T(t, n) {
-  const e = m();
+function T(t, e) {
+  const n = m();
   p(() => {
-    e.registerNavigationFunction(t, n);
+    n.registerNavigationFunction(t, e);
   }), C(() => {
-    e.unregisterNavigationFunction();
+    n.unregisterNavigationFunction();
   });
 }
-function W(t, n) {
-  const e = m(), a = n?.functionName ?? "setPageState";
+function W(t, e) {
+  const n = m(), a = e?.functionName ?? "setPageState";
   p(() => {
-    e.registerPageStateFunction(t, {
-      ...n,
+    n.registerPageStateFunction(t, {
+      ...e,
       functionName: a
     });
   }), C(() => {
-    e.unregisterPageStateFunction(a);
+    n.unregisterPageStateFunction(a);
   });
 }
-function K(t, n) {
-  const e = m();
+function K(t, e) {
+  const n = m();
   p(() => {
-    e.on(t, n);
+    n.on(t, e);
   }), C(() => {
-    e.off(t, n);
+    n.off(t, e);
   });
 }
 function U(t) {
-  const n = F(t.get());
-  return R(t.subscribe((e) => {
-    n.value = e;
-  })), n;
+  const e = F(t.get());
+  return R(t.subscribe((n) => {
+    e.value = n;
+  })), e;
 }
 function $() {
-  const t = m(), n = F(null), e = (o) => {
-    n.value = o, t.proactive?.shown(o);
+  const t = m(), e = F(null), n = (o) => {
+    e.value = o, t.proactive?.shown(o);
   }, a = ({ nudge: o }) => {
-    n.value?.id === o.id && (n.value = null);
+    e.value?.id === o.id && (e.value = null);
   };
   return p(() => {
-    t.on("nudge:ready", e), t.on("nudge:accepted", a), t.on("nudge:dismissed", a);
+    t.on("nudge:ready", n), t.on("nudge:accepted", a), t.on("nudge:dismissed", a);
   }), C(() => {
-    t.off("nudge:ready", e), t.off("nudge:accepted", a), t.off("nudge:dismissed", a);
+    t.off("nudge:ready", n), t.off("nudge:accepted", a), t.off("nudge:dismissed", a);
   }), {
-    nudge: n,
+    nudge: e,
     accept: async () => {
-      const o = n.value;
-      o && (n.value = null, await t.proactive?.accept(o));
+      const o = e.value;
+      o && (e.value = null, await t.proactive?.accept(o));
     },
     dismiss: () => {
-      const o = n.value;
-      o && (n.value = null, t.proactive?.dismiss(o));
+      const o = e.value;
+      o && (e.value = null, t.proactive?.dismiss(o));
     }
   };
 }
 export {
   N as AGO_CLIENT_KEY,
-  q as AgoPlugin,
+  _ as AgoPlugin,
   D as FEEDBACK_REASONS,
   m as useAgo,
   K as useAgoEvents,