@useago/sdk 1.13.1 → 1.13.3

package/dist/index.d.ts

@@ -768,6 +768,11 @@ export declare interface AgoClientEvents {
         result: unknown;
         error?: string;
     };
+    /** A validated form collector submission is about to call its submit target. */
+    "form:submitting": {
+        name: string;
+        values: Record<string, unknown>;
+    };
     /**
      * A form collector submitted successfully. `result` is the raw submit response
      * (POST body / handler return value / backend relay result) — the third-party
@@ -2390,6 +2395,9 @@ export declare function onFormError(client: AgoClient, callback: (data: AgoClien
  */
 export declare function onFormSubmitted(client: AgoClient, callback: (data: AgoClientEvents["form:submitted"]) => void): () => void;
 
+/** Observe a validated form submission before its submit target runs. */
+export declare function onFormSubmitting(client: AgoClient, callback: (data: AgoClientEvents["form:submitting"]) => void): () => void;
+
 /**
  * Subscribe to client function invocations.
  */
@@ -3353,16 +3361,21 @@ export declare interface TranscribeAudioOptions {
  */
 export declare function validateConfig(config: unknown, context?: string): asserts config is AgoConfig;
 
-/** The MCP behavior hints AGO has no equivalent for. */
+/** Metadata for tools exposed through the WebMCP bridge. */
 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.
+     * Optional WebMCP metadata; all fields default to `false` in WebMCP.
+     * These annotations do not affect AGO's in-app agent or approval behavior.
      */
     annotations?: {
+        /** The tool only reads data and does not change state. */
         readOnlyHint?: boolean;
+        /** The output contains content untrusted by the tool author. */
         untrustedContentHint?: boolean;
+        /** Significant, real-world, or irreversible effects; independent of requiresApproval. */
+        consequentialHint?: boolean;
+        /** Intended for debugging and developer tooling. */
+        debugging?: boolean;
     };
     /**
      * This function navigates. The WebMCP call is held open until the function

package/dist/index.js

@@ -1,9 +1,9 @@
-import { a as w, c as E, d as C, f as S, i as y, l as b, m as F, o as v, p as _, r as M, s as T, t as R, u as I } from "./functions-tzyOZNp6.js";
-import { C as D, S as L, _ as O, b as k, c as N, d as G, f as x, g as q, h as P, i as X, l as B, m as H, n as c, o as J, p as W, r as j, s as z, t as K, u as V, v as Y, w as $, x as Q, y as Z } from "./types-fX-VoHfa.js";
+import { a as w, c as E, d as S, f as C, i as y, l as b, m as F, o as v, p as _, r as M, s as T, t as R, u as I } from "./functions-tzyOZNp6.js";
+import { C as D, S as L, _ as O, b as N, c as k, d as G, f as x, g as q, h as P, i as X, l as B, m as H, n as c, o as J, p as W, r as j, s as z, t as K, u as V, v as Y, w as $, x as Q, y as Z } from "./types-D1ZrqVhr.js";
 import { a as te, i as oe, n as p, r as ae, t as re } from "./errors-BLfjXnLB.js";
 import { t as se } from "./autoContinue-Cb4_iEbO.js";
-import { t as ge } from "./createConversationSession-D0vks-8C.js";
-import { n as me, r as fe, t as le } from "./createFormCollector-BMN-blXs.js";
+import { t as ue } from "./createConversationSession-DrmOaZdO.js";
+import { n as me, r as fe, t as de } from "./createFormCollector-D6_N8wYq.js";
 import { t as ce } from "./createMockClient-YoYr3pQr.js";
 import "./testing.js";
 function Ae(e) {
@@ -18,10 +18,10 @@ function we(e, t) {
 function Ee(e, t) {
   return e.on("message:start", t), () => e.off("message:start", t);
 }
-function Ce(e, t) {
+function Se(e, t) {
   return e.on("message:error", t), () => e.off("message:error", t);
 }
-function Se(e, t) {
+function Ce(e, t) {
   return e.on("toolCall:received", t), () => e.off("toolCall:received", t);
 }
 function ye(e, t) {
@@ -33,34 +33,34 @@ function be(e, t) {
 function Fe(e, t) {
   return e.on("function:invoke", t), () => e.off("function:invoke", t);
 }
-async function* ve(e, t, g) {
+async function* ve(e, t, u) {
   const n = [];
   let a = null, r = !1;
-  const u = (s) => {
+  const g = (s) => {
     n.push(s), a?.();
-  }, m = (s) => u({
+  }, m = (s) => g({
     type: "start",
     data: s
-  }), f = (s) => u({
+  }), f = (s) => g({
     type: "chunk",
     data: s
   }), o = (s) => {
-    u({
+    g({
       type: "complete",
       data: s
     }), r = !0, a?.();
   }, i = (s) => {
-    u({
+    g({
       type: "error",
       data: s
     }), r = !0, a?.();
-  }, l = (s) => u({
+  }, d = (s) => g({
     type: "toolCall",
     data: s
-  }), d = () => {
+  }), l = () => {
     r = !0, a?.();
   };
-  e.on("message:start", m), e.on("message:chunk", f), e.on("message:complete", o), e.on("message:error", i), e.on("message:stopped", d), e.on("toolCall:received", l), e.sendMessage(t, g).catch(() => {
+  e.on("message:start", m), e.on("message:chunk", f), e.on("message:complete", o), e.on("message:error", i), e.on("message:stopped", l), e.on("toolCall:received", d), e.sendMessage(t, u).catch(() => {
     r = !0, a?.();
   });
   try {
@@ -68,44 +68,47 @@ async function* ve(e, t, g) {
       a = s;
     }), a = null);
   } finally {
-    e.off("message:start", m), e.off("message:chunk", f), e.off("message:complete", o), e.off("message:error", i), e.off("message:stopped", d), e.off("toolCall:received", l);
+    e.off("message:start", m), e.off("message:chunk", f), e.off("message:complete", o), e.off("message:error", i), e.off("message:stopped", l), e.off("toolCall:received", d);
   }
 }
+function _e(e, t) {
+  return e.on("form:submitting", t), () => e.off("form:submitting", t);
+}
 function A(e) {
-  let t, g, n, a, r, u, m;
+  let t, u, n, a, r, g, m;
   if (typeof window < "u" && window.AGO) {
     const o = window.AGO;
-    t = o.basepath, g = o.widgetId, n = o.agent || o.defaultAgent, a = o.permission, r = o.email, u = o.jwt, m = o.metadata;
+    t = o.basepath, u = o.widgetId, n = o.agent || o.defaultAgent, a = o.permission, r = o.email, g = o.jwt, m = o.metadata;
   }
   if (typeof document < "u") {
     const o = (i) => document.querySelector(`meta[name="${i}"]`)?.getAttribute("content") || void 0;
-    t = t || o("ago-base-url"), g = g || o("ago-widget-id"), n = n || o("ago-agent") || o("ago-agent-id"), a = a || o("ago-permission"), r = r || o("ago-user-email");
+    t = t || o("ago-base-url"), u = u || o("ago-widget-id"), n = n || o("ago-agent") || o("ago-agent-id"), a = a || o("ago-permission"), r = r || o("ago-user-email");
   }
   if (typeof document < "u") {
     const o = [document.body, ...Array.from(document.querySelectorAll("script[data-ago-base-url]"))].filter(Boolean);
     for (const i of o)
-      i && (t = t || i.getAttribute("data-ago-base-url") || void 0, g = g || i.getAttribute("data-ago-widget-id") || void 0, n = n || i.getAttribute("data-ago-agent") || i.getAttribute("data-ago-agent-id") || void 0, a = a || i.getAttribute("data-ago-permission") || void 0, r = r || i.getAttribute("data-ago-user-email") || void 0);
+      i && (t = t || i.getAttribute("data-ago-base-url") || void 0, u = u || i.getAttribute("data-ago-widget-id") || void 0, n = n || i.getAttribute("data-ago-agent") || i.getAttribute("data-ago-agent-id") || void 0, a = a || i.getAttribute("data-ago-permission") || void 0, r = r || i.getAttribute("data-ago-user-email") || void 0);
   }
-  t = e?.baseUrl || t, g = e?.widgetId || g, n = e?.agent || e?.defaultAgentId || n, a = e?.permission || a, r = e?.userEmail || r, u = e?.userJwt || u, e?.metadata !== void 0 && (m = e.metadata);
+  t = e?.baseUrl || t, u = e?.widgetId || u, n = e?.agent || e?.defaultAgentId || n, a = e?.permission || a, r = e?.userEmail || r, g = e?.userJwt || g, e?.metadata !== void 0 && (m = e.metadata);
   const f = e?.debug;
   return t ? {
     baseUrl: t,
-    widgetId: g,
+    widgetId: u,
     agent: n,
     permission: a,
     language: e?.language,
     userEmail: r,
-    userJwt: u,
+    userJwt: g,
     metadata: m,
     debug: f
   } : null;
 }
-function _e(e) {
+function Me(e) {
   const t = A(e);
   if (!t) throw new p('createAgo(): could not detect AGO configuration. Set window.AGO, add <meta name="ago-base-url">, or pass { baseUrl } explicitly.', "config_missing_base_url");
   return new c(t);
 }
-function Me(e, t) {
+function Te(e, t) {
   return {
     ...e,
     handler: t
@@ -122,7 +125,7 @@ export {
   G as ClientContextRegistry,
   $ as DEFAULT_MAX_ACTIVITY_ENTRIES,
   Z as DEFAULT_MAX_ERRORS,
-  k as DEFAULT_MAX_ERROR_AGE_MS,
+  N as DEFAULT_MAX_ERROR_AGE_MS,
   Q as ErrorWatcher,
   X as EventEmitter,
   K as FEEDBACK_REASONS,
@@ -133,10 +136,10 @@ export {
   A as autoDetectConfig,
   J as canInlineImage,
   R as copyToClipboard,
-  _e as createAgo,
+  Me as createAgo,
   x as createAgoProactive,
-  ge as createConversationSession,
-  le as createFormCollector,
+  ue as createConversationSession,
+  de as createFormCollector,
   ve as createMessageStream,
   ce as createMockClient,
   q as createStore,
@@ -153,23 +156,24 @@ export {
   H as matchesWhen,
   be as onFormError,
   ye as onFormSubmitted,
+  _e as onFormSubmitting,
   Fe as onFunctionInvoke,
   he as onMessage,
   we as onMessageChunk,
-  Ce as onMessageError,
+  Se as onMessageError,
   Ee as onMessageStart,
-  Se as onToolCall,
+  Ce as onToolCall,
   v as openUrl,
   P as partialDeepMatch,
-  N as safeAttachmentUrl,
+  k as safeAttachmentUrl,
   T as scrollToElement,
   E as setLocalStorage,
   b as setTheme,
   I as showConfirmDialog,
-  C as showNotification,
-  S as showToast,
+  S as showNotification,
+  C as showToast,
   _ as submitForm,
   F as trackEvent,
   j as validateConfig,
-  Me as withHandler
+  Te as withHandler
 };

package/dist/react.cjs

@@ -1,4 +1,4 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});var $e=Object.create,Y=Object.defineProperty,Ke=Object.getOwnPropertyDescriptor,Ue=Object.getOwnPropertyNames,Ge=Object.getPrototypeOf,Je=Object.prototype.hasOwnProperty,Ve=(e,r)=>{let t={};for(var s in e)Y(t,s,{get:e[s],enumerable:!0});return r||Y(t,Symbol.toStringTag,{value:"Module"}),t},Xe=(e,r,t,s)=>{if(r&&typeof r=="object"||typeof r=="function")for(var o=Ue(r),l=0,c=o.length,i;l<c;l++)i=o[l],!Je.call(e,i)&&i!==t&&Y(e,i,{get:(x=>r[x]).bind(null,i),enumerable:!(s=Ke(r,i))||s.enumerable});return e},oe=(e,r,t)=>(t=e!=null?$e(Ge(e)):{},Xe(r||!e||!e.__esModule?Y(t,"default",{value:e,enumerable:!0}):t,e));const L=require("./types-Ck3iZG0K.cjs"),Z=require("./errors-o1IB5fEu.cjs"),Ye=require("./autoContinue-C3UsCvT5.cjs"),z=require("./createFormCollector-BNCMIUw2.cjs"),Ze=require("./createMockClient-BPt1gSve.cjs"),G=require("./speechToText-ZciRyyJE.cjs");let n=require("react");n=oe(n,1);let a=require("react/jsx-runtime"),te=require("react-markdown");te=oe(te,1);let ne=require("remark-gfm");ne=oe(ne,1);function ye(e){const[r,t]=(0,n.useState)(!1),s=(0,n.useRef)(null),o=(0,n.useMemo)(()=>{if(s.current&&(s.current.destroy(),s.current=null),!e)return null;const l=new L.AgoClient(e);return s.current=l,l},[e?.baseUrl,e?.widgetId]);return(0,n.useEffect)(()=>(o&&s.current===null&&(s.current=o,o.reviveAfterDestroy()),t(!0),()=>{s.current?.destroy(),s.current=null}),[o]),(0,n.useEffect)(()=>{s.current&&e&&s.current.updateConfig({agent:e.agent,defaultAgentId:e.defaultAgentId,permission:e.permission,language:e.language??null,userEmail:e.userEmail,userJwt:e.userJwt,metadata:e.metadata??null,debug:e.debug,warnOnEmptyReply:e.warnOnEmptyReply})},[e?.agent,e?.defaultAgentId,e?.permission,e?.language,e?.userEmail,e?.userJwt,e?.metadata,e?.debug,e?.warnOnEmptyReply]),{client:o,isReady:r}}var se=(0,n.createContext)(null),Qe=({children:e,client:r,tools:t,helpers:s,pageContext:o,...l})=>{const{client:c}=ye(r?null:l),i=r||c;return(0,n.useEffect)(()=>{if(!(!t||t.length===0)){for(const x of t)i.register(x);return()=>{for(const x of t)i.unregisterFunction(x.name)}}},[i,t]),(0,n.useEffect)(()=>{if(!s)return;const x=[];return Promise.resolve().then(()=>require("./functions-CPs7omgM.cjs")).then(d=>d.functions_exports).then(d=>{for(const[g,w]of Object.entries(s)){const m=d[g];if(!m){console.warn(`[AGO] Unknown helper: "${g}"`);continue}const f=w===!0?m:{...m,handler:w};i.register(f),x.push(f.name)}}),()=>{for(const d of x)i.unregisterFunction(d)}},[i,s]),(0,n.useEffect)(()=>{o==="auto"&&i.enableAutoPageContext()},[i,o]),(0,a.jsx)(se.Provider,{value:i,children:e})};function B(){const e=(0,n.useContext)(se);if(!e)throw new Error('useAgoClient must be used within an <AgoProvider>. Wrap your component tree with <AgoProvider baseUrl="...">.');return e}function D(){return(0,n.useContext)(se)}var et=new Set(["awaiting-approval"]);function ve(e){switch(e){case"progress_indicator":return"progress";case"reasoning":return"reasoning";case"confirmation_input":return"confirmation";case"form":return"form";default:return"status"}}function tt(e){return e.type==="client_function"?e.functionName==="navigateToPage"?"navigation":"action":ve(e.type)}function ge(e,r){const t=(e??"").toLowerCase();return t.includes("reject")?"rejected":t.includes("error")||t.includes("fail")?"error":t.includes("done")||t.includes("complet")?"done":(t.includes("waiting")||t.includes("pending"))&&(r==="confirmation"||r==="form")?"awaiting-approval":"running"}function xe(e){return typeof e!="string"||!e?"page":e.replace(/[-_]+/g," ").replace(/([a-z0-9])([A-Z])/g,"$1 $2").replace(/\b\w/g,r=>r.toUpperCase()).trim()}function nt(e){switch(e.kind){case"navigation":return`Navigating to ${xe(e.arguments?.page)}`;case"action":return e.functionName==="setPageState"?"Updating the page":e.functionName==="openFilteredConversations"?"Opening conversations":e.toolDisplayName||e.message||xe(e.functionName)||"Working";case"progress":return e.message||"Working";case"reasoning":return e.message||"Thinking";case"confirmation":return e.message||"Waiting for your confirmation";case"form":return e.message||e.toolDisplayName||"Please fill in the form";default:return e.message||e.toolDisplayName||e.toolName||"Working"}}function Ce(e={}){const{includeReasoning:r=!1,labelFor:t}=e,s=D(),o=e.client||s;if(!o)throw new Z.AgoError("useAgoActivity requires an AgoClient. Either pass it as options.client or wrap your app in <AgoProvider>.","provider_missing_client");const[l,c]=(0,n.useState)([]),i=(0,n.useRef)(new Set),x=(0,n.useRef)(void 0),d=(0,n.useRef)(t);d.current=t;const g=(0,n.useCallback)((p,S)=>{c(b=>{const N=b.findIndex(y=>y.id===p),_={...N>=0?b[N]:{id:p,kind:"status",label:"",status:"running",requiresApproval:!1,createdAt:new Date},...S};return _.label=d.current?.(_)??nt(_),N>=0?[...b.slice(0,N),_,...b.slice(N+1)]:[...b,_]})},[]);(0,n.useEffect)(()=>{const p=h=>{x.current=h.messageId},S=h=>{const I=ve(h.type);I==="reasoning"&&!r||g(h.id,{kind:I,status:ge(h.status,I),messageId:x.current,toolName:h.toolName,toolDisplayName:h.toolDisplayName,message:h.message,data:h.data,formSchema:h.formSchema,requiresApproval:I==="confirmation"||I==="form"})},b=h=>{h.invocationId&&g(h.invocationId,{kind:h.functionName==="navigateToPage"?"navigation":"action",status:"running",messageId:x.current,functionName:h.functionName,arguments:h.arguments})},N=h=>{h.invocationId&&g(h.invocationId,{kind:h.functionName==="navigateToPage"?"navigation":"action",status:"awaiting-approval",messageId:x.current,functionName:h.functionName,arguments:h.arguments,requiresApproval:!0})},_=h=>{if(!h.invocationId)return;const I=h.result,u=typeof h.result=="object"&&I!==null&&I.approved===!1&&I.reason==="user_rejected";g(h.invocationId,{status:h.error?"error":u?"rejected":"done",requiresApproval:!1})},y=h=>{for(const I of h.messages??[])if(I.role==="assistant")for(const u of I.toolCalls??[]){const A=tt(u);A==="reasoning"&&!r||/waiting/i.test(u.status??"")||g(u.id,{kind:A,status:ge(u.status,A),messageId:I.id,toolName:u.toolName,toolDisplayName:u.toolDisplayName,functionName:u.functionName,arguments:u.arguments,message:u.message,data:u.data,formSchema:u.formSchema,requiresApproval:A==="confirmation"||A==="form"})}},k=h=>{c(I=>I.map(u=>u.status==="running"||u.status==="awaiting-approval"?{...u,status:h}:u))},j=()=>k("done"),E=()=>k("error");return o.on("message:start",p),o.on("toolCall:received",S),o.on("function:invoke",b),o.on("function:awaiting-approval",N),o.on("function:result",_),o.on("conversation:loaded",y),o.on("message:complete",j),o.on("message:error",E),()=>{o.off("message:start",p),o.off("toolCall:received",S),o.off("function:invoke",b),o.off("function:awaiting-approval",N),o.off("function:result",_),o.off("conversation:loaded",y),o.off("message:complete",j),o.off("message:error",E)}},[o,r,g]);const w=(0,n.useCallback)(async p=>{const S=l.find(b=>b.id===p);!S||S.status!=="awaiting-approval"||i.current.has(p)||S.kind!=="form"&&(i.current.add(p),g(p,{status:"running",requiresApproval:!1}),S.functionName?await o.approveFunction(p):await o.confirmToolCall(p))},[o,l,g]),m=(0,n.useCallback)(async p=>{const S=l.find(b=>b.id===p);!S||S.status!=="awaiting-approval"||i.current.has(p)||(i.current.add(p),g(p,{status:"rejected",requiresApproval:!1}),S.functionName?await o.rejectFunction(p):await o.rejectToolCall(p))},[o,l,g]),f=(0,n.useCallback)(async(p,S)=>{g(p,{status:"running",requiresApproval:!1}),await o.submitToolCallForm(p,S),g(p,{status:"done"})},[o,g]),v=(0,n.useCallback)(()=>{i.current.clear(),c([])},[]);return{items:l,latest:l.length>0?l[l.length-1]:void 0,isAwaitingApproval:l.some(p=>et.has(p.status)),approve:w,reject:m,submitForm:f,clear:v}}function ae({client:e,conversationId:r}={}){const t=D(),s=e||t;if(!s)throw new Error("useMessages requires an AgoClient. Either pass it as options.client or wrap your app in <AgoProvider>.");const[o,l]=(0,n.useState)([]),[c,i]=(0,n.useState)(r),[x,d]=(0,n.useState)(!1),[g,w]=(0,n.useState)(null);(0,n.useEffect)(()=>{r&&r!==c&&(i(r),m(r))},[r]);const m=async f=>{try{l((await s.getMessages(f)).filter(v=>!v.hidden))}catch(v){w(v instanceof Error?v:new Error("Failed to load messages"))}};return(0,n.useEffect)(()=>{const f=y=>y==="IN_PROGRESS"||y==="WAITING_CLIENT",v=y=>{c||i(y.conversationId),d(!0),l(k=>{const j=k.findIndex(E=>E.id===y.messageId);return j>=0?k.map((E,h)=>h===j?{...E,status:"IN_PROGRESS"}:E):k.some(E=>E.role==="assistant"&&f(E.status))?k:[...k,{id:y.messageId,conversationId:y.conversationId,content:"",role:"assistant",status:"IN_PROGRESS",createdAt:new Date}]})},p=y=>{l(k=>{const j=k.findIndex(E=>E.id===y.messageId);return j<0?k:k.map((E,h)=>h===j?{...E,content:E.content+y.content}:E)})},S=y=>{l(k=>{let j=-1;for(let E=k.length-1;E>=0;E--)if(k[E].role==="assistant"&&f(k[E].status)){j=E;break}return j<0?k:[...k.slice(0,j),{...k[j],...y},...k.slice(j+1)]})},b=y=>{l(k=>{const j=k.findIndex(E=>E.id===y.id);return j>=0?[...k.slice(0,j),y,...k.slice(j+1)]:[...k,y]}),d(!1)},N=y=>{w(new Error(y.error)),d(!1)},_=()=>{l(y=>{let k=-1;for(let j=y.length-1;j>=0;j--)if(y[j].role==="assistant"&&f(y[j].status)){k=j;break}return k<0?y:y[k].content?y.map((j,E)=>E===k?{...j,status:"CANCELED"}:j):y.filter((j,E)=>E!==k)}),d(!1)};return s.on("message:start",v),s.on("message:chunk",p),s.on("message:answer-complete",S),s.on("message:complete",b),s.on("message:error",N),s.on("message:stopped",_),()=>{s.off("message:start",v),s.off("message:chunk",p),s.off("message:answer-complete",S),s.off("message:complete",b),s.off("message:error",N),s.off("message:stopped",_)}},[s,c]),{messages:o,isLoading:x,error:g,sendMessage:(0,n.useCallback)(async(f,v)=>{d(!0),w(null);const p={id:`temp-${Date.now()}`,conversationId:c||"",content:f,role:"user",status:"DONE",attachments:v&&v.length>0?L.attachmentsFromFiles(v):void 0,createdAt:new Date},S={id:`temp-assistant-${Date.now()}`,conversationId:c||"",content:"",role:"assistant",status:"IN_PROGRESS",createdAt:new Date};l(b=>[...b,p,S]);try{const b=await s.sendMessage(f,{conversationId:c,files:v});return b.conversationId&&!c&&i(b.conversationId),l(N=>{const _=N.filter(k=>!k.id.startsWith("temp-")),y={...p,id:p.id.replace("temp-","user-"),conversationId:b.conversationId};return _.some(k=>k.id===b.id)?[..._,y].sort((k,j)=>new Date(k.createdAt).getTime()-new Date(j.createdAt).getTime()):[..._,y,b]}),b}catch(b){return w(b instanceof Error?b:new Error("Failed to send message")),d(!1),l(N=>N.filter(_=>!_.id.startsWith("temp-"))),null}},[s,c]),stop:(0,n.useCallback)(async()=>{await s.stop()},[s]),clearMessages:(0,n.useCallback)(()=>{l([]),i(void 0),w(null)},[]),conversationId:c}}var me={compact:!1,state:"peek",isModal:!1,surface:{style:{},attrs:{}}},rt={tabindex:"tabIndex"};function ot(e){const r={};for(const[t,s]of Object.entries(e))r[rt[t]??t]=s;return r}function we(e){const r=e!==!1,t=r?e??{}:void 0,s=(0,n.useRef)(t?.onStateChange);s.current=t?.onStateChange;const o=(0,n.useMemo)(()=>{if(r)return G.createSheetController({breakpoint:t?.breakpoint,initialState:t?.initialState,bottomOffset:t?.bottomOffset,peekHeight:t?.peekHeight,onStateChange:(c,i)=>s.current?.(c,i)})},[r,t?.breakpoint,t?.initialState,t?.bottomOffset,t?.peekHeight]),l=(0,n.useSyncExternalStore)((0,n.useCallback)(c=>o?.subscribe(c)??(()=>{}),[o]),(0,n.useCallback)(()=>o?.getSnapshot()??me,[o]),(0,n.useCallback)(()=>o?.getServerSnapshot()??me,[o]));return{sheet:(0,n.useMemo)(()=>({...l,surface:{...l.surface,attrs:ot(l.surface.attrs)}}),[l]),expand:(0,n.useCallback)(c=>o?.expand(c),[o]),collapse:(0,n.useCallback)(c=>o?.collapse(c),[o]),toggle:(0,n.useCallback)(c=>o?.toggle(c),[o])}}var st=/(`[^`\n]+`|\*\*[^*\n]+\*\*|\*[^*\n]+\*|_[^_\n]+_)/g;function Se(e){const r=e.split(st);return r.length===1?e:r.map((t,s)=>s%2===0||!t?t:t.startsWith("`")?(0,a.jsx)("code",{style:{fontFamily:"ui-monospace, SFMono-Regular, Menlo, Consolas, monospace",fontSize:"0.92em",padding:"0 3px",borderRadius:"3px",backgroundColor:"rgba(0, 0, 0, 0.06)"},children:t.slice(1,-1)},s):t.startsWith("**")?(0,a.jsx)("strong",{style:{fontWeight:600},children:t.slice(2,-2)},s):(0,a.jsx)("em",{children:t.slice(1,-1)},s))}var at=`
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});var $e=Object.create,Y=Object.defineProperty,Ke=Object.getOwnPropertyDescriptor,Ue=Object.getOwnPropertyNames,Ge=Object.getPrototypeOf,Je=Object.prototype.hasOwnProperty,Ve=(e,r)=>{let t={};for(var s in e)Y(t,s,{get:e[s],enumerable:!0});return r||Y(t,Symbol.toStringTag,{value:"Module"}),t},Xe=(e,r,t,s)=>{if(r&&typeof r=="object"||typeof r=="function")for(var o=Ue(r),l=0,c=o.length,i;l<c;l++)i=o[l],!Je.call(e,i)&&i!==t&&Y(e,i,{get:(x=>r[x]).bind(null,i),enumerable:!(s=Ke(r,i))||s.enumerable});return e},oe=(e,r,t)=>(t=e!=null?$e(Ge(e)):{},Xe(r||!e||!e.__esModule?Y(t,"default",{value:e,enumerable:!0}):t,e));const L=require("./types-DNr6XEwI.cjs"),Z=require("./errors-o1IB5fEu.cjs"),Ye=require("./autoContinue-C3UsCvT5.cjs"),z=require("./createFormCollector-D_5SDuk9.cjs"),Ze=require("./createMockClient-BPt1gSve.cjs"),G=require("./speechToText-ZciRyyJE.cjs");let n=require("react");n=oe(n,1);let a=require("react/jsx-runtime"),te=require("react-markdown");te=oe(te,1);let ne=require("remark-gfm");ne=oe(ne,1);function ye(e){const[r,t]=(0,n.useState)(!1),s=(0,n.useRef)(null),o=(0,n.useMemo)(()=>{if(s.current&&(s.current.destroy(),s.current=null),!e)return null;const l=new L.AgoClient(e);return s.current=l,l},[e?.baseUrl,e?.widgetId]);return(0,n.useEffect)(()=>(o&&s.current===null&&(s.current=o,o.reviveAfterDestroy()),t(!0),()=>{s.current?.destroy(),s.current=null}),[o]),(0,n.useEffect)(()=>{s.current&&e&&s.current.updateConfig({agent:e.agent,defaultAgentId:e.defaultAgentId,permission:e.permission,language:e.language??null,userEmail:e.userEmail,userJwt:e.userJwt,metadata:e.metadata??null,debug:e.debug,warnOnEmptyReply:e.warnOnEmptyReply})},[e?.agent,e?.defaultAgentId,e?.permission,e?.language,e?.userEmail,e?.userJwt,e?.metadata,e?.debug,e?.warnOnEmptyReply]),{client:o,isReady:r}}var se=(0,n.createContext)(null),Qe=({children:e,client:r,tools:t,helpers:s,pageContext:o,...l})=>{const{client:c}=ye(r?null:l),i=r||c;return(0,n.useEffect)(()=>{if(!(!t||t.length===0)){for(const x of t)i.register(x);return()=>{for(const x of t)i.unregisterFunction(x.name)}}},[i,t]),(0,n.useEffect)(()=>{if(!s)return;const x=[];return Promise.resolve().then(()=>require("./functions-CPs7omgM.cjs")).then(d=>d.functions_exports).then(d=>{for(const[g,w]of Object.entries(s)){const m=d[g];if(!m){console.warn(`[AGO] Unknown helper: "${g}"`);continue}const f=w===!0?m:{...m,handler:w};i.register(f),x.push(f.name)}}),()=>{for(const d of x)i.unregisterFunction(d)}},[i,s]),(0,n.useEffect)(()=>{o==="auto"&&i.enableAutoPageContext()},[i,o]),(0,a.jsx)(se.Provider,{value:i,children:e})};function B(){const e=(0,n.useContext)(se);if(!e)throw new Error('useAgoClient must be used within an <AgoProvider>. Wrap your component tree with <AgoProvider baseUrl="...">.');return e}function D(){return(0,n.useContext)(se)}var et=new Set(["awaiting-approval"]);function ve(e){switch(e){case"progress_indicator":return"progress";case"reasoning":return"reasoning";case"confirmation_input":return"confirmation";case"form":return"form";default:return"status"}}function tt(e){return e.type==="client_function"?e.functionName==="navigateToPage"?"navigation":"action":ve(e.type)}function ge(e,r){const t=(e??"").toLowerCase();return t.includes("reject")?"rejected":t.includes("error")||t.includes("fail")?"error":t.includes("done")||t.includes("complet")?"done":(t.includes("waiting")||t.includes("pending"))&&(r==="confirmation"||r==="form")?"awaiting-approval":"running"}function xe(e){return typeof e!="string"||!e?"page":e.replace(/[-_]+/g," ").replace(/([a-z0-9])([A-Z])/g,"$1 $2").replace(/\b\w/g,r=>r.toUpperCase()).trim()}function nt(e){switch(e.kind){case"navigation":return`Navigating to ${xe(e.arguments?.page)}`;case"action":return e.functionName==="setPageState"?"Updating the page":e.functionName==="openFilteredConversations"?"Opening conversations":e.toolDisplayName||e.message||xe(e.functionName)||"Working";case"progress":return e.message||"Working";case"reasoning":return e.message||"Thinking";case"confirmation":return e.message||"Waiting for your confirmation";case"form":return e.message||e.toolDisplayName||"Please fill in the form";default:return e.message||e.toolDisplayName||e.toolName||"Working"}}function Ce(e={}){const{includeReasoning:r=!1,labelFor:t}=e,s=D(),o=e.client||s;if(!o)throw new Z.AgoError("useAgoActivity requires an AgoClient. Either pass it as options.client or wrap your app in <AgoProvider>.","provider_missing_client");const[l,c]=(0,n.useState)([]),i=(0,n.useRef)(new Set),x=(0,n.useRef)(void 0),d=(0,n.useRef)(t);d.current=t;const g=(0,n.useCallback)((p,S)=>{c(b=>{const N=b.findIndex(y=>y.id===p),_={...N>=0?b[N]:{id:p,kind:"status",label:"",status:"running",requiresApproval:!1,createdAt:new Date},...S};return _.label=d.current?.(_)??nt(_),N>=0?[...b.slice(0,N),_,...b.slice(N+1)]:[...b,_]})},[]);(0,n.useEffect)(()=>{const p=h=>{x.current=h.messageId},S=h=>{const I=ve(h.type);I==="reasoning"&&!r||g(h.id,{kind:I,status:ge(h.status,I),messageId:x.current,toolName:h.toolName,toolDisplayName:h.toolDisplayName,message:h.message,data:h.data,formSchema:h.formSchema,requiresApproval:I==="confirmation"||I==="form"})},b=h=>{h.invocationId&&g(h.invocationId,{kind:h.functionName==="navigateToPage"?"navigation":"action",status:"running",messageId:x.current,functionName:h.functionName,arguments:h.arguments})},N=h=>{h.invocationId&&g(h.invocationId,{kind:h.functionName==="navigateToPage"?"navigation":"action",status:"awaiting-approval",messageId:x.current,functionName:h.functionName,arguments:h.arguments,requiresApproval:!0})},_=h=>{if(!h.invocationId)return;const I=h.result,u=typeof h.result=="object"&&I!==null&&I.approved===!1&&I.reason==="user_rejected";g(h.invocationId,{status:h.error?"error":u?"rejected":"done",requiresApproval:!1})},y=h=>{for(const I of h.messages??[])if(I.role==="assistant")for(const u of I.toolCalls??[]){const A=tt(u);A==="reasoning"&&!r||/waiting/i.test(u.status??"")||g(u.id,{kind:A,status:ge(u.status,A),messageId:I.id,toolName:u.toolName,toolDisplayName:u.toolDisplayName,functionName:u.functionName,arguments:u.arguments,message:u.message,data:u.data,formSchema:u.formSchema,requiresApproval:A==="confirmation"||A==="form"})}},k=h=>{c(I=>I.map(u=>u.status==="running"||u.status==="awaiting-approval"?{...u,status:h}:u))},j=()=>k("done"),E=()=>k("error");return o.on("message:start",p),o.on("toolCall:received",S),o.on("function:invoke",b),o.on("function:awaiting-approval",N),o.on("function:result",_),o.on("conversation:loaded",y),o.on("message:complete",j),o.on("message:error",E),()=>{o.off("message:start",p),o.off("toolCall:received",S),o.off("function:invoke",b),o.off("function:awaiting-approval",N),o.off("function:result",_),o.off("conversation:loaded",y),o.off("message:complete",j),o.off("message:error",E)}},[o,r,g]);const w=(0,n.useCallback)(async p=>{const S=l.find(b=>b.id===p);!S||S.status!=="awaiting-approval"||i.current.has(p)||S.kind!=="form"&&(i.current.add(p),g(p,{status:"running",requiresApproval:!1}),S.functionName?await o.approveFunction(p):await o.confirmToolCall(p))},[o,l,g]),m=(0,n.useCallback)(async p=>{const S=l.find(b=>b.id===p);!S||S.status!=="awaiting-approval"||i.current.has(p)||(i.current.add(p),g(p,{status:"rejected",requiresApproval:!1}),S.functionName?await o.rejectFunction(p):await o.rejectToolCall(p))},[o,l,g]),f=(0,n.useCallback)(async(p,S)=>{g(p,{status:"running",requiresApproval:!1}),await o.submitToolCallForm(p,S),g(p,{status:"done"})},[o,g]),v=(0,n.useCallback)(()=>{i.current.clear(),c([])},[]);return{items:l,latest:l.length>0?l[l.length-1]:void 0,isAwaitingApproval:l.some(p=>et.has(p.status)),approve:w,reject:m,submitForm:f,clear:v}}function ae({client:e,conversationId:r}={}){const t=D(),s=e||t;if(!s)throw new Error("useMessages requires an AgoClient. Either pass it as options.client or wrap your app in <AgoProvider>.");const[o,l]=(0,n.useState)([]),[c,i]=(0,n.useState)(r),[x,d]=(0,n.useState)(!1),[g,w]=(0,n.useState)(null);(0,n.useEffect)(()=>{r&&r!==c&&(i(r),m(r))},[r]);const m=async f=>{try{l((await s.getMessages(f)).filter(v=>!v.hidden))}catch(v){w(v instanceof Error?v:new Error("Failed to load messages"))}};return(0,n.useEffect)(()=>{const f=y=>y==="IN_PROGRESS"||y==="WAITING_CLIENT",v=y=>{c||i(y.conversationId),d(!0),l(k=>{const j=k.findIndex(E=>E.id===y.messageId);return j>=0?k.map((E,h)=>h===j?{...E,status:"IN_PROGRESS"}:E):k.some(E=>E.role==="assistant"&&f(E.status))?k:[...k,{id:y.messageId,conversationId:y.conversationId,content:"",role:"assistant",status:"IN_PROGRESS",createdAt:new Date}]})},p=y=>{l(k=>{const j=k.findIndex(E=>E.id===y.messageId);return j<0?k:k.map((E,h)=>h===j?{...E,content:E.content+y.content}:E)})},S=y=>{l(k=>{let j=-1;for(let E=k.length-1;E>=0;E--)if(k[E].role==="assistant"&&f(k[E].status)){j=E;break}return j<0?k:[...k.slice(0,j),{...k[j],...y},...k.slice(j+1)]})},b=y=>{l(k=>{const j=k.findIndex(E=>E.id===y.id);return j>=0?[...k.slice(0,j),y,...k.slice(j+1)]:[...k,y]}),d(!1)},N=y=>{w(new Error(y.error)),d(!1)},_=()=>{l(y=>{let k=-1;for(let j=y.length-1;j>=0;j--)if(y[j].role==="assistant"&&f(y[j].status)){k=j;break}return k<0?y:y[k].content?y.map((j,E)=>E===k?{...j,status:"CANCELED"}:j):y.filter((j,E)=>E!==k)}),d(!1)};return s.on("message:start",v),s.on("message:chunk",p),s.on("message:answer-complete",S),s.on("message:complete",b),s.on("message:error",N),s.on("message:stopped",_),()=>{s.off("message:start",v),s.off("message:chunk",p),s.off("message:answer-complete",S),s.off("message:complete",b),s.off("message:error",N),s.off("message:stopped",_)}},[s,c]),{messages:o,isLoading:x,error:g,sendMessage:(0,n.useCallback)(async(f,v)=>{d(!0),w(null);const p={id:`temp-${Date.now()}`,conversationId:c||"",content:f,role:"user",status:"DONE",attachments:v&&v.length>0?L.attachmentsFromFiles(v):void 0,createdAt:new Date},S={id:`temp-assistant-${Date.now()}`,conversationId:c||"",content:"",role:"assistant",status:"IN_PROGRESS",createdAt:new Date};l(b=>[...b,p,S]);try{const b=await s.sendMessage(f,{conversationId:c,files:v});return b.conversationId&&!c&&i(b.conversationId),l(N=>{const _=N.filter(k=>!k.id.startsWith("temp-")),y={...p,id:p.id.replace("temp-","user-"),conversationId:b.conversationId};return _.some(k=>k.id===b.id)?[..._,y].sort((k,j)=>new Date(k.createdAt).getTime()-new Date(j.createdAt).getTime()):[..._,y,b]}),b}catch(b){return w(b instanceof Error?b:new Error("Failed to send message")),d(!1),l(N=>N.filter(_=>!_.id.startsWith("temp-"))),null}},[s,c]),stop:(0,n.useCallback)(async()=>{await s.stop()},[s]),clearMessages:(0,n.useCallback)(()=>{l([]),i(void 0),w(null)},[]),conversationId:c}}var me={compact:!1,state:"peek",isModal:!1,surface:{style:{},attrs:{}}},rt={tabindex:"tabIndex"};function ot(e){const r={};for(const[t,s]of Object.entries(e))r[rt[t]??t]=s;return r}function we(e){const r=e!==!1,t=r?e??{}:void 0,s=(0,n.useRef)(t?.onStateChange);s.current=t?.onStateChange;const o=(0,n.useMemo)(()=>{if(r)return G.createSheetController({breakpoint:t?.breakpoint,initialState:t?.initialState,bottomOffset:t?.bottomOffset,peekHeight:t?.peekHeight,onStateChange:(c,i)=>s.current?.(c,i)})},[r,t?.breakpoint,t?.initialState,t?.bottomOffset,t?.peekHeight]),l=(0,n.useSyncExternalStore)((0,n.useCallback)(c=>o?.subscribe(c)??(()=>{}),[o]),(0,n.useCallback)(()=>o?.getSnapshot()??me,[o]),(0,n.useCallback)(()=>o?.getServerSnapshot()??me,[o]));return{sheet:(0,n.useMemo)(()=>({...l,surface:{...l.surface,attrs:ot(l.surface.attrs)}}),[l]),expand:(0,n.useCallback)(c=>o?.expand(c),[o]),collapse:(0,n.useCallback)(c=>o?.collapse(c),[o]),toggle:(0,n.useCallback)(c=>o?.toggle(c),[o])}}var st=/(`[^`\n]+`|\*\*[^*\n]+\*\*|\*[^*\n]+\*|_[^_\n]+_)/g;function Se(e){const r=e.split(st);return r.length===1?e:r.map((t,s)=>s%2===0||!t?t:t.startsWith("`")?(0,a.jsx)("code",{style:{fontFamily:"ui-monospace, SFMono-Regular, Menlo, Consolas, monospace",fontSize:"0.92em",padding:"0 3px",borderRadius:"3px",backgroundColor:"rgba(0, 0, 0, 0.06)"},children:t.slice(1,-1)},s):t.startsWith("**")?(0,a.jsx)("strong",{style:{fontWeight:600},children:t.slice(2,-2)},s):(0,a.jsx)("em",{children:t.slice(1,-1)},s))}var at=`
 @keyframes ago-activity-enter {
   from { opacity: 0; transform: translateY(4px); }
   to { opacity: 1; transform: none; }

package/dist/react.d.cts

@@ -787,6 +787,11 @@ declare interface AgoClientEvents {
         result: unknown;
         error?: string;
     };
+    /** A validated form collector submission is about to call its submit target. */
+    "form:submitting": {
+        name: string;
+        values: Record<string, unknown>;
+    };
     /**
      * A form collector submitted successfully. `result` is the raw submit response
      * (POST body / handler return value / backend relay result) — the third-party
@@ -3325,16 +3330,21 @@ export declare interface UseSheetResult {
     toggle: (cause?: SheetChangeCause) => void;
 }
 
-/** The MCP behavior hints AGO has no equivalent for. */
+/** Metadata for tools exposed through the WebMCP bridge. */
 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.
+     * Optional WebMCP metadata; all fields default to `false` in WebMCP.
+     * These annotations do not affect AGO's in-app agent or approval behavior.
      */
     annotations?: {
+        /** The tool only reads data and does not change state. */
         readOnlyHint?: boolean;
+        /** The output contains content untrusted by the tool author. */
         untrustedContentHint?: boolean;
+        /** Significant, real-world, or irreversible effects; independent of requiresApproval. */
+        consequentialHint?: boolean;
+        /** Intended for debugging and developer tooling. */
+        debugging?: boolean;
     };
     /**
      * This function navigates. The WebMCP call is held open until the function

package/dist/react.d.ts

@@ -787,6 +787,11 @@ declare interface AgoClientEvents {
         result: unknown;
         error?: string;
     };
+    /** A validated form collector submission is about to call its submit target. */
+    "form:submitting": {
+        name: string;
+        values: Record<string, unknown>;
+    };
     /**
      * A form collector submitted successfully. `result` is the raw submit response
      * (POST body / handler return value / backend relay result) — the third-party
@@ -3325,16 +3330,21 @@ export declare interface UseSheetResult {
     toggle: (cause?: SheetChangeCause) => void;
 }
 
-/** The MCP behavior hints AGO has no equivalent for. */
+/** Metadata for tools exposed through the WebMCP bridge. */
 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.
+     * Optional WebMCP metadata; all fields default to `false` in WebMCP.
+     * These annotations do not affect AGO's in-app agent or approval behavior.
      */
     annotations?: {
+        /** The tool only reads data and does not change state. */
         readOnlyHint?: boolean;
+        /** The output contains content untrusted by the tool author. */
         untrustedContentHint?: boolean;
+        /** Significant, real-world, or irreversible effects; independent of requiresApproval. */
+        consequentialHint?: boolean;
+        /** Intended for debugging and developer tooling. */
+        debugging?: boolean;
     };
     /**
      * This function navigates. The WebMCP call is held open until the function

package/dist/react.js

@@ -1,7 +1,7 @@
-import { a as De, c as ze, g as Le, n as Pe, o as Be, s as He, t as Oe } from "./types-fX-VoHfa.js";
+import { a as De, c as ze, g as Le, n as Pe, o as Be, s as He, t as Oe } from "./types-D1ZrqVhr.js";
 import { n as Q } from "./errors-BLfjXnLB.js";
 import { t as $e } from "./autoContinue-Cb4_iEbO.js";
-import { n as jt, r as he, t as xe } from "./createFormCollector-BMN-blXs.js";
+import { n as jt, r as he, t as xe } from "./createFormCollector-D6_N8wYq.js";
 import { t as Kt } from "./createMockClient-YoYr3pQr.js";
 import { C as je, dt as qe, n as Ke, t as Jt, ut as Ue } from "./speechToText-BV7qxqPF.js";
 import Ge, { createContext as Je, forwardRef as Ve, useCallback as T, useContext as be, useEffect as E, useId as Xe, useImperativeHandle as Ye, useLayoutEffect as Ze, useMemo as $, useRef as W, useState as M, useSyncExternalStore as ye } from "react";

package/dist/testing.d.cts

@@ -729,6 +729,11 @@ declare interface AgoClientEvents {
         result: unknown;
         error?: string;
     };
+    /** A validated form collector submission is about to call its submit target. */
+    "form:submitting": {
+        name: string;
+        values: Record<string, unknown>;
+    };
     /**
      * A form collector submitted successfully. `result` is the raw submit response
      * (POST body / handler return value / backend relay result) — the third-party
@@ -2096,16 +2101,21 @@ declare interface TranscribeAudioOptions {
     signal?: AbortSignal;
 }
 
-/** The MCP behavior hints AGO has no equivalent for. */
+/** Metadata for tools exposed through the WebMCP bridge. */
 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.
+     * Optional WebMCP metadata; all fields default to `false` in WebMCP.
+     * These annotations do not affect AGO's in-app agent or approval behavior.
      */
     annotations?: {
+        /** The tool only reads data and does not change state. */
         readOnlyHint?: boolean;
+        /** The output contains content untrusted by the tool author. */
         untrustedContentHint?: boolean;
+        /** Significant, real-world, or irreversible effects; independent of requiresApproval. */
+        consequentialHint?: boolean;
+        /** Intended for debugging and developer tooling. */
+        debugging?: boolean;
     };
     /**
      * This function navigates. The WebMCP call is held open until the function

package/dist/testing.d.ts

@@ -729,6 +729,11 @@ declare interface AgoClientEvents {
         result: unknown;
         error?: string;
     };
+    /** A validated form collector submission is about to call its submit target. */
+    "form:submitting": {
+        name: string;
+        values: Record<string, unknown>;
+    };
     /**
      * A form collector submitted successfully. `result` is the raw submit response
      * (POST body / handler return value / backend relay result) — the third-party
@@ -2096,16 +2101,21 @@ declare interface TranscribeAudioOptions {
     signal?: AbortSignal;
 }
 
-/** The MCP behavior hints AGO has no equivalent for. */
+/** Metadata for tools exposed through the WebMCP bridge. */
 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.
+     * Optional WebMCP metadata; all fields default to `false` in WebMCP.
+     * These annotations do not affect AGO's in-app agent or approval behavior.
      */
     annotations?: {
+        /** The tool only reads data and does not change state. */
         readOnlyHint?: boolean;
+        /** The output contains content untrusted by the tool author. */
         untrustedContentHint?: boolean;
+        /** Significant, real-world, or irreversible effects; independent of requiresApproval. */
+        consequentialHint?: boolean;
+        /** Intended for debugging and developer tooling. */
+        debugging?: boolean;
     };
     /**
      * This function navigates. The WebMCP call is held open until the function