@useago/sdk 1.13.2 → 1.13.3

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.13.3] - 2026-10-13
+
+### Added
+
+- **Form submission start notifications.** Use `form:submitting`, the
+  `onFormSubmitting` helper, or the widget callback to show a loading state
+  after validation and before submission starts. Concurrent submits share one
+  start notification; success and failure use the existing outcome events.
+
+- **WebMCP `consequentialHint` and `debugging` annotations.** Both are now
+  supported in `webmcp.annotations` and forwarded to browser agents.
+  `consequentialHint` describes significant, real-world, or irreversible
+  effects; `debugging` marks developer tools. These annotations do not change
+  AGO's in-app agent or approval behavior. `consequentialHint` remains
+  independent of `requiresApproval`.
+
+## [1.13.1] - 2026-09-21
+
 ### Added
 
 - **`catalogue: "onDemand"` for navigation.** Route descriptions ride in the

package/dist/angular.d.cts

@@ -746,6 +746,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
@@ -2246,16 +2251,21 @@ export 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/angular.d.ts

@@ -746,6 +746,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
@@ -2246,16 +2251,21 @@ export 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/{createFormCollector-ki_GTlp9.js → createFormCollector-D6_N8wYq.js}

@@ -1,11 +1,11 @@
 import { S as w, g as R } from "./types-D1ZrqVhr.js";
 var j = /^[a-zA-Z0-9_-]{1,40}$/, V = (s) => s == null || s === "";
 function S(s, e) {
-  if ("anyOf" in s) return s.anyOf.some((c) => S(c, e));
-  if ("allOf" in s) return s.allOf.every((c) => S(c, e));
+  if ("anyOf" in s) return s.anyOf.some((m) => S(m, e));
+  if ("allOf" in s) return s.allOf.every((m) => S(m, e));
   const l = e[s.property];
   if (V(l)) return !1;
-  if (Array.isArray(s.value)) return s.value.some((c) => String(l) === String(c));
+  if (Array.isArray(s.value)) return s.value.some((m) => String(l) === String(m));
   if (!s.op) return String(l) === String(s.value);
   const i = Number(l), a = Number(s.value);
   if (Number.isNaN(i) || Number.isNaN(a)) return !1;
@@ -24,12 +24,12 @@ function S(s, e) {
 }
 function p(s, e) {
   const l = s.properties ?? {}, i = /* @__PURE__ */ new Set();
-  for (const c of s.required ?? []) {
-    const d = l[c]?.requiredWhen;
-    (!d || S(d, e)) && i.add(c);
+  for (const m of s.required ?? []) {
+    const b = l[m]?.requiredWhen;
+    (!b || S(b, e)) && i.add(m);
   }
-  for (const [c, d] of Object.entries(l)) d.requiredWhen && S(d.requiredWhen, e) && i.add(c);
-  const a = [...i].filter((c) => V(e[c]));
+  for (const [m, b] of Object.entries(l)) b.requiredWhen && S(b.requiredWhen, e) && i.add(m);
+  const a = [...i].filter((m) => V(e[m]));
   return {
     missing: a,
     complete: a.length === 0
@@ -57,10 +57,10 @@ function L(s) {
     url: s.submit
   } : !1 : s.submit ?? !1;
   s.autoSubmit === !0 && !a && w.warn(`FormCollector "${e}": autoSubmit is ignored because no submit target is configured.`);
-  const c = (s.autoSubmit ?? !0) && !!a, d = i.properties ?? {}, $ = (t) => {
+  const m = (s.autoSubmit ?? !0) && !!a, b = i.properties ?? {}, $ = (t) => {
     const r = {};
     for (const [o, n] of Object.entries(t)) {
-      const u = d[o];
+      const u = b[o];
       if (u)
         if (n == null) r[o] = n;
         else if (u.type === "number" || u.type === "integer") {
@@ -69,22 +69,22 @@ function L(s) {
         } else u.type === "boolean" ? r[o] = typeof n == "boolean" ? n : n === "true" ? !0 : n === "false" ? !1 : !!n : r[o] = n;
     }
     return r;
-  }, C = s.initialValues ?? {}, m = R({
+  }, C = s.initialValues ?? {}, c = R({
     values: C,
     submitted: !1
   }), F = (t) => {
-    const r = m.get(), o = {
+    const r = c.get(), o = {
       ...r,
       values: {
         ...r.values,
         ...t
       }
     };
-    return m.set(o), o;
+    return c.set(o), o;
   };
-  let b = null;
+  let d = null;
   const k = (t, r) => {
-    b?.emitFormEvent("form:error", {
+    d?.emitFormEvent("form:error", {
       name: e,
       values: t,
       error: r
@@ -92,7 +92,7 @@ function L(s) {
   };
   let h = null;
   const A = async () => {
-    const { values: t } = m.get(), { complete: r, missing: o } = p(i, t);
+    const { values: t } = c.get(), { complete: r, missing: o } = p(i, t);
     if (!r) return {
       ok: !1,
       missing: o
@@ -101,8 +101,16 @@ function L(s) {
       ok: !1,
       error: "No submit target configured for this form collector."
     };
+    if (a.via === "backend" && !d) return {
+      ok: !1,
+      error: "Backend submit requires install(client) (or useFormCollector) first."
+    };
     const n = t;
     try {
+      d?.emitFormEvent("form:submitting", {
+        name: e,
+        values: n
+      });
       let u;
       if (a.via === "client") if ("handler" in a) u = await a.handler(n);
       else {
@@ -122,18 +130,12 @@ function L(s) {
         u = await f.json().catch(() => {
         });
       }
-      else {
-        if (!b) return {
-          ok: !1,
-          error: "Backend submit requires install(client) (or useFormCollector) first."
-        };
-        u = await b.submitFormCollector(e, n);
-      }
-      return m.set({
-        ...m.get(),
+      else u = await d.submitFormCollector(e, n);
+      return c.set({
+        ...c.get(),
         submitted: !0,
         submitResult: u
-      }), b?.emitFormEvent("form:submitted", {
+      }), d?.emitFormEvent("form:submitted", {
         name: e,
         values: n,
         result: u
@@ -155,8 +157,8 @@ function L(s) {
       h = null;
     }
   })(), h), q = async () => {
-    if (!c || !a) return null;
-    const { values: t, submitted: r } = m.get();
+    if (!m || !a) return null;
+    const { values: t, submitted: r } = c.get();
     return r || !p(i, t).complete ? null : N();
   }, x = {
     name: `update_${e}`,
@@ -182,7 +184,7 @@ function L(s) {
       };
     }
   }, y = [x];
-  a && !c && y.push({
+  a && !m && y.push({
     name: `submit_${e}`,
     description: `Submit the completed "${e}" form. Only call this once every required field is collected and the user has confirmed. If fields are missing it returns them instead of submitting.`,
     parameters: {
@@ -195,7 +197,7 @@ function L(s) {
     const r = t.functionName ?? t.toolName;
     if (r)
       return r.startsWith(I) ? r.slice(8) : r;
-  }, O = (t) => {
+  }, E = (t) => {
     let r = { ...C }, o = !1;
     for (const n of t) {
       const u = D(n);
@@ -204,16 +206,16 @@ function L(s) {
         ...$(n.arguments)
       }) : _ && u === _ && n.status?.toLowerCase() === "done" && (o = !0);
     }
-    m.set({
+    c.set({
       values: r,
       submitted: o
     });
-  }, g = `form:${e}`, v = `${g}:definition`, T = () => ({
+  }, g = `form:${e}`, v = `${g}:definition`, O = () => ({
     name: `Form definition: ${e}`,
     description: `${l} Some fields are conditionally required; the requiredWhen field in the schema tells you when each becomes required. The form schema is the following: ${JSON.stringify(i)}.`,
     stable: !0
-  }), E = () => {
-    const { values: t, submitted: r } = m.get(), { missing: o, complete: n } = p(i, t), u = a ? c ? " The form is submitted automatically as soon as every required field is filled, so there is no submit function to call." : ` When nothing is missing and the user confirms, call submit_${e}.` : "", f = r ? `The "${e}" form has been submitted.` : `You are currently collecting information from the user to fill the "${e}" form.`;
+  }), T = () => {
+    const { values: t, submitted: r } = c.get(), { missing: o, complete: n } = p(i, t), u = a ? m ? " The form is submitted automatically as soon as every required field is filled, so there is no submit function to call." : ` When nothing is missing and the user confirms, call submit_${e}.` : "", f = r ? `The "${e}" form has been submitted.` : `You are currently collecting information from the user to fill the "${e}" form.`;
     return {
       name: `Form: ${e}`,
       description: `${f} The form's schema and field requirements are in the "${v}" client context. Call update_${e} with any fields the user provides; ask only for what is still missing.${u}`,
@@ -225,40 +227,40 @@ function L(s) {
       }
     };
   }, P = (t) => {
-    O((t.messages ?? []).flatMap((r) => r.toolCalls ?? []));
+    E((t.messages ?? []).flatMap((r) => r.toolCalls ?? []));
   };
   return {
     name: e,
-    store: m,
+    store: c,
     functions: y,
     contextKey: g,
-    contextProvider: E,
+    contextProvider: T,
     definitionContextKey: v,
-    definitionContextProvider: T,
+    definitionContextProvider: O,
     install: (t) => {
-      b = t;
+      d = t;
       for (const o of y) t.register(o);
-      t.addDynamicContext(v, T), t.addDynamicContext(g, E);
-      const r = m.subscribe(() => t.notifyContextChanged());
+      t.addDynamicContext(v, O), t.addDynamicContext(g, T);
+      const r = c.subscribe(() => t.notifyContextChanged());
       return t.on("conversation:loaded", P), () => {
         r();
         for (const o of y) t.unregisterFunction(o.name);
-        t.removeDynamicContext(g), t.removeDynamicContext(v), t.off("conversation:loaded", P), b === t && (b = null);
+        t.removeDynamicContext(g), t.removeDynamicContext(v), t.off("conversation:loaded", P), d === t && (d = null);
       };
     },
-    hydrate: O,
+    hydrate: E,
     submit: N,
-    getValues: () => m.get().values,
+    getValues: () => c.get().values,
     setValues: (t) => {
       F($(t)), q();
     },
     reset: () => {
-      m.set({
+      c.set({
         values: C,
         submitted: !1
       });
     },
-    getStatus: () => p(i, m.get().values)
+    getStatus: () => p(i, c.get().values)
   };
 }
 async function K(s, e) {

package/dist/createFormCollector-D_5SDuk9.cjs

@@ -0,0 +1 @@
+const C=require("./types-DNr6XEwI.cjs");var W=/^[a-zA-Z0-9_-]{1,40}$/,V=n=>n==null||n==="";function S(n,e){if("anyOf"in n)return n.anyOf.some(c=>S(c,e));if("allOf"in n)return n.allOf.every(c=>S(c,e));const l=e[n.property];if(V(l))return!1;if(Array.isArray(n.value))return n.value.some(c=>String(l)===String(c));if(!n.op)return String(l)===String(n.value);const i=Number(l),a=Number(n.value);if(Number.isNaN(i)||Number.isNaN(a))return!1;switch(n.op){case">=":return i>=a;case"<=":return i<=a;case">":return i>a;case"<":return i<a;default:return C.logger.warn(`Unknown requiredWhen op "${n.op}"; treating as not required.`),!1}}function h(n,e){const l=n.properties??{},i=new Set;for(const c of n.required??[]){const b=l[c]?.requiredWhen;(!b||S(b,e))&&i.add(c)}for(const[c,b]of Object.entries(l))b.requiredWhen&&S(b.requiredWhen,e)&&i.add(c);const a=[...i].filter(c=>V(e[c]));return{missing:a,complete:a.length===0}}function B(n){const e={};for(const[l,i]of Object.entries(n.properties??{}))e[l]={type:i.type,...i.description!=null&&{description:i.description},...i.enum&&{enum:i.enum},...i.default!==void 0&&{default:i.default}};return{type:"object",properties:e,required:[]}}function A(n){const{name:e,description:l,schema:i}=n;if(!W.test(e))throw new Error(`Invalid form collector name "${e}": must match ${W} (it becomes the update_/submit_ function names).`);const a=typeof n.submit=="string"?n.submit?{via:"client",url:n.submit}:!1:n.submit??!1;n.autoSubmit===!0&&!a&&C.logger.warn(`FormCollector "${e}": autoSubmit is ignored because no submit target is configured.`);const c=(n.autoSubmit??!0)&&!!a,b=i.properties??{},$=t=>{const r={};for(const[o,s]of Object.entries(t)){const u=b[o];if(u)if(s==null)r[o]=s;else if(u.type==="number"||u.type==="integer"){const f=typeof s=="number"?s:Number(s);r[o]=Number.isNaN(f)?s:f}else u.type==="boolean"?r[o]=typeof s=="boolean"?s:s==="true"?!0:s==="false"?!1:!!s:r[o]=s}return r},F=n.initialValues??{},m=C.createStore({values:F,submitted:!1}),w=t=>{const r=m.get(),o={...r,values:{...r.values,...t}};return m.set(o),o};let d=null;const k=(t,r)=>{d?.emitFormEvent("form:error",{name:e,values:t,error:r})};let p=null;const I=async()=>{const{values:t}=m.get(),{complete:r,missing:o}=h(i,t);if(!r)return{ok:!1,missing:o};if(!a)return{ok:!1,error:"No submit target configured for this form collector."};if(a.via==="backend"&&!d)return{ok:!1,error:"Backend submit requires install(client) (or useFormCollector) first."};const s=t;try{d?.emitFormEvent("form:submitting",{name:e,values:s});let u;if(a.via==="client")if("handler"in a)u=await a.handler(s);else{const f=await fetch(a.url,{method:"POST",headers:{"Content-Type":"application/json"},credentials:"include",body:JSON.stringify(s)});if(!f.ok){const j=`Submit failed: HTTP ${f.status}`;return k(s,j),{ok:!1,error:j}}u=await f.json().catch(()=>{})}else u=await d.submitFormCollector(e,s);return m.set({...m.get(),submitted:!0,submitResult:u}),d?.emitFormEvent("form:submitted",{name:e,values:s,result:u}),{ok:!0,result:u}}catch(u){const f=u instanceof Error?u.message:"Submit failed";return C.logger.error(`FormCollector "${e}" submit failed:`,u),k(s,f),{ok:!1,error:f}}},N=()=>p||(p=(async()=>{try{return await I()}finally{p=null}})(),p),q=async()=>{if(!c||!a)return null;const{values:t,submitted:r}=m.get();return r||!h(i,t).complete?null:N()},O={name:`update_${e}`,description:`Fill or update fields of the "${e}" form. ${l} Pass any subset of fields; call it repeatedly to fill the form as the user provides information. Returns the current values and which required fields are still missing.`,parameters:B(i),handler:async t=>{const r=w($(t)),{missing:o}=h(i,r.values),s=await q();return s?s.ok?{ok:!0,values:r.values,missing:o,submitted:!0}:{ok:!0,values:r.values,missing:o,submitted:!1,submitError:s.error}:{ok:!0,values:r.values,missing:o}}},y=[O];a&&!c&&y.push({name:`submit_${e}`,description:`Submit the completed "${e}" form. Only call this once every required field is collected and the user has confirmed. If fields are missing it returns them instead of submitting.`,parameters:{type:"object",properties:{}},handler:()=>N()});const D="client__",_=a?`submit_${e}`:null,R=t=>{const r=t.functionName??t.toolName;if(r)return r.startsWith(D)?r.slice(8):r},x=t=>{let r={...F},o=!1;for(const s of t){const u=R(s);u===O.name?s.arguments&&(r={...r,...$(s.arguments)}):_&&u===_&&s.status?.toLowerCase()==="done"&&(o=!0)}m.set({values:r,submitted:o})},g=`form:${e}`,v=`${g}:definition`,E=()=>({name:`Form definition: ${e}`,description:`${l} Some fields are conditionally required; the requiredWhen field in the schema tells you when each becomes required. The form schema is the following: ${JSON.stringify(i)}.`,stable:!0}),P=()=>{const{values:t,submitted:r}=m.get(),{missing:o,complete:s}=h(i,t),u=a?c?" The form is submitted automatically as soon as every required field is filled, so there is no submit function to call.":` When nothing is missing and the user confirms, call submit_${e}.`:"",f=r?`The "${e}" form has been submitted.`:`You are currently collecting information from the user to fill the "${e}" form.`;return{name:`Form: ${e}`,description:`${f} The form's schema and field requirements are in the "${v}" client context. Call update_${e} with any fields the user provides; ask only for what is still missing.${u}`,data:{values:t,missing:o,complete:s,submitted:r}}},T=t=>{x((t.messages??[]).flatMap(r=>r.toolCalls??[]))};return{name:e,store:m,functions:y,contextKey:g,contextProvider:P,definitionContextKey:v,definitionContextProvider:E,install:t=>{d=t;for(const o of y)t.register(o);t.addDynamicContext(v,E),t.addDynamicContext(g,P);const r=m.subscribe(()=>t.notifyContextChanged());return t.on("conversation:loaded",T),()=>{r();for(const o of y)t.unregisterFunction(o.name);t.removeDynamicContext(g),t.removeDynamicContext(v),t.off("conversation:loaded",T),d===t&&(d=null)}},hydrate:x,submit:N,getValues:()=>m.get().values,setValues:t=>{w($(t)),q()},reset:()=>{m.set({values:F,submitted:!1})},getStatus:()=>h(i,m.get().values)}}async function L(n,e){const l=await n.getFormCollector(e.name);return A({name:l.name,description:e.description??l.description,schema:e.schema??l.schema,submit:e.submit??l.submit,initialValues:e.initialValues,autoSubmit:e.autoSubmit??l.autoSubmit})}Object.defineProperty(exports,"createFormCollector",{enumerable:!0,get:function(){return A}});Object.defineProperty(exports,"deriveFormStatus",{enumerable:!0,get:function(){return h}});Object.defineProperty(exports,"loadFormCollector",{enumerable:!0,get:function(){return L}});

package/dist/devtools.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
@@ -2086,16 +2091,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/devtools.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
@@ -2086,16 +2091,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/helpers.d.cts

@@ -144,16 +144,21 @@ export declare const submitForm: ClientFunctionDefinition;
  */
 export declare const trackEvent: ClientFunctionDefinition;
 
-/** 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/helpers.d.ts

@@ -144,16 +144,21 @@ export declare const submitForm: ClientFunctionDefinition;
  */
 export declare const trackEvent: ClientFunctionDefinition;
 
-/** 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/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("./types-DNr6XEwI.cjs"),f=require("./errors-o1IB5fEu.cjs"),S=require("./autoContinue-C3UsCvT5.cjs"),p=require("./createConversationSession-Digvn0GQ.cjs"),A=require("./createFormCollector-Cq7HWjtU.cjs"),w=require("./createMockClient-BPt1gSve.cjs");require("./testing.cjs");const g=require("./functions-CPs7omgM.cjs");function F(e){return e}function _(e,t){return e.on("message:complete",t),()=>e.off("message:complete",t)}function y(e,t){return e.on("message:chunk",t),()=>e.off("message:chunk",t)}function M(e,t){return e.on("message:start",t),()=>e.off("message:start",t)}function v(e,t){return e.on("message:error",t),()=>e.off("message:error",t)}function T(e,t){return e.on("toolCall:received",t),()=>e.off("toolCall:received",t)}function R(e,t){return e.on("form:submitted",t),()=>e.off("form:submitted",t)}function b(e,t){return e.on("form:error",t),()=>e.off("form:error",t)}function q(e,t){return e.on("function:invoke",t),()=>e.off("function:invoke",t)}async function*I(e,t,l){const i=[];let n=null,a=!1;const c=s=>{i.push(s),n?.()},m=s=>c({type:"start",data:s}),d=s=>c({type:"chunk",data:s}),r=s=>{c({type:"complete",data:s}),a=!0,n?.()},u=s=>{c({type:"error",data:s}),a=!0,n?.()},E=s=>c({type:"toolCall",data:s}),h=()=>{a=!0,n?.()};e.on("message:start",m),e.on("message:chunk",d),e.on("message:complete",r),e.on("message:error",u),e.on("message:stopped",h),e.on("toolCall:received",E),e.sendMessage(t,l).catch(()=>{a=!0,n?.()});try{for(;!a||i.length>0;)i.length>0?yield i.shift():(await new Promise(s=>{n=s}),n=null)}finally{e.off("message:start",m),e.off("message:chunk",d),e.off("message:complete",r),e.off("message:error",u),e.off("message:stopped",h),e.off("toolCall:received",E)}}function C(e){let t,l,i,n,a,c,m;if(typeof window<"u"&&window.AGO){const r=window.AGO;t=r.basepath,l=r.widgetId,i=r.agent||r.defaultAgent,n=r.permission,a=r.email,c=r.jwt,m=r.metadata}if(typeof document<"u"){const r=u=>document.querySelector(`meta[name="${u}"]`)?.getAttribute("content")||void 0;t=t||r("ago-base-url"),l=l||r("ago-widget-id"),i=i||r("ago-agent")||r("ago-agent-id"),n=n||r("ago-permission"),a=a||r("ago-user-email")}if(typeof document<"u"){const r=[document.body,...Array.from(document.querySelectorAll("script[data-ago-base-url]"))].filter(Boolean);for(const u of r)u&&(t=t||u.getAttribute("data-ago-base-url")||void 0,l=l||u.getAttribute("data-ago-widget-id")||void 0,i=i||u.getAttribute("data-ago-agent")||u.getAttribute("data-ago-agent-id")||void 0,n=n||u.getAttribute("data-ago-permission")||void 0,a=a||u.getAttribute("data-ago-user-email")||void 0)}t=e?.baseUrl||t,l=e?.widgetId||l,i=e?.agent||e?.defaultAgentId||i,n=e?.permission||n,a=e?.userEmail||a,c=e?.userJwt||c,e?.metadata!==void 0&&(m=e.metadata);const d=e?.debug;return t?{baseUrl:t,widgetId:l,agent:i,permission:n,language:e?.language,userEmail:a,userJwt:c,metadata:m,debug:d}:null}function U(e){const t=C(e);if(!t)throw new f.AgoError('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 o.AgoClient(t)}function D(e,t){return{...e,handler:t}}exports.ActivityLedger=o.ActivityLedger;exports.AgoApiError=f.AgoApiError;exports.AgoClient=o.AgoClient;exports.AgoError=f.AgoError;exports.AgoFunctionError=f.AgoFunctionError;exports.AgoNetworkError=f.AgoNetworkError;exports.AgoStreamError=f.AgoStreamError;exports.ClientContextRegistry=o.ClientContextRegistry;exports.DEFAULT_MAX_ACTIVITY_ENTRIES=o.DEFAULT_MAX_ACTIVITY_ENTRIES;exports.DEFAULT_MAX_ERRORS=o.DEFAULT_MAX_ERRORS;exports.DEFAULT_MAX_ERROR_AGE_MS=o.DEFAULT_MAX_ERROR_AGE_MS;exports.ErrorWatcher=o.ErrorWatcher;exports.EventEmitter=o.EventEmitter;exports.FEEDBACK_REASONS=o.FEEDBACK_REASONS;exports.FunctionRegistry=o.FunctionRegistry;exports.SSEHandler=o.SSEHandler;exports.SignalCollector=o.SignalCollector;exports.attachAutoContinueAfterNavigation=S.attachAutoContinueAfterNavigation;exports.autoDetectConfig=C;exports.canInlineImage=o.canInlineImage;exports.copyToClipboard=g.copyToClipboard;exports.createAgo=U;exports.createAgoProactive=o.createAgoProactive;exports.createConversationSession=p.createConversationSession;exports.createFormCollector=A.createFormCollector;exports.createMessageStream=I;exports.createMockClient=w.createMockClient;exports.createStore=o.createStore;exports.defineFunction=F;exports.deriveFormStatus=A.deriveFormStatus;exports.formatFileSize=o.formatFileSize;exports.getLocalStorage=g.getLocalStorage;exports.getUserLocation=g.getUserLocation;exports.highlightElement=g.highlightElement;exports.isStreamNetworkError=o.isStreamNetworkError;exports.loadFormCollector=A.loadFormCollector;exports.logger=o.logger;exports.matchesRoutePattern=o.matchesRoutePattern;exports.matchesWhen=o.matchesWhen;exports.onFormError=b;exports.onFormSubmitted=R;exports.onFunctionInvoke=q;exports.onMessage=_;exports.onMessageChunk=y;exports.onMessageError=v;exports.onMessageStart=M;exports.onToolCall=T;exports.openUrl=g.openUrl;exports.partialDeepMatch=o.partialDeepMatch;exports.safeAttachmentUrl=o.safeAttachmentUrl;exports.scrollToElement=g.scrollToElement;exports.setLocalStorage=g.setLocalStorage;exports.setTheme=g.setTheme;exports.showConfirmDialog=g.showConfirmDialog;exports.showNotification=g.showNotification;exports.showToast=g.showToast;exports.submitForm=g.submitForm;exports.trackEvent=g.trackEvent;exports.validateConfig=o.validateConfig;exports.withHandler=D;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("./types-DNr6XEwI.cjs"),f=require("./errors-o1IB5fEu.cjs"),C=require("./autoContinue-C3UsCvT5.cjs"),p=require("./createConversationSession-Digvn0GQ.cjs"),A=require("./createFormCollector-D_5SDuk9.cjs"),w=require("./createMockClient-BPt1gSve.cjs");require("./testing.cjs");const g=require("./functions-CPs7omgM.cjs");function F(e){return e}function _(e,t){return e.on("message:complete",t),()=>e.off("message:complete",t)}function y(e,t){return e.on("message:chunk",t),()=>e.off("message:chunk",t)}function M(e,t){return e.on("message:start",t),()=>e.off("message:start",t)}function b(e,t){return e.on("message:error",t),()=>e.off("message:error",t)}function v(e,t){return e.on("toolCall:received",t),()=>e.off("toolCall:received",t)}function T(e,t){return e.on("form:submitted",t),()=>e.off("form:submitted",t)}function R(e,t){return e.on("form:error",t),()=>e.off("form:error",t)}function q(e,t){return e.on("function:invoke",t),()=>e.off("function:invoke",t)}async function*I(e,t,m){const i=[];let n=null,a=!1;const l=s=>{i.push(s),n?.()},c=s=>l({type:"start",data:s}),d=s=>l({type:"chunk",data:s}),r=s=>{l({type:"complete",data:s}),a=!0,n?.()},u=s=>{l({type:"error",data:s}),a=!0,n?.()},E=s=>l({type:"toolCall",data:s}),S=()=>{a=!0,n?.()};e.on("message:start",c),e.on("message:chunk",d),e.on("message:complete",r),e.on("message:error",u),e.on("message:stopped",S),e.on("toolCall:received",E),e.sendMessage(t,m).catch(()=>{a=!0,n?.()});try{for(;!a||i.length>0;)i.length>0?yield i.shift():(await new Promise(s=>{n=s}),n=null)}finally{e.off("message:start",c),e.off("message:chunk",d),e.off("message:complete",r),e.off("message:error",u),e.off("message:stopped",S),e.off("toolCall:received",E)}}function U(e,t){return e.on("form:submitting",t),()=>e.off("form:submitting",t)}function h(e){let t,m,i,n,a,l,c;if(typeof window<"u"&&window.AGO){const r=window.AGO;t=r.basepath,m=r.widgetId,i=r.agent||r.defaultAgent,n=r.permission,a=r.email,l=r.jwt,c=r.metadata}if(typeof document<"u"){const r=u=>document.querySelector(`meta[name="${u}"]`)?.getAttribute("content")||void 0;t=t||r("ago-base-url"),m=m||r("ago-widget-id"),i=i||r("ago-agent")||r("ago-agent-id"),n=n||r("ago-permission"),a=a||r("ago-user-email")}if(typeof document<"u"){const r=[document.body,...Array.from(document.querySelectorAll("script[data-ago-base-url]"))].filter(Boolean);for(const u of r)u&&(t=t||u.getAttribute("data-ago-base-url")||void 0,m=m||u.getAttribute("data-ago-widget-id")||void 0,i=i||u.getAttribute("data-ago-agent")||u.getAttribute("data-ago-agent-id")||void 0,n=n||u.getAttribute("data-ago-permission")||void 0,a=a||u.getAttribute("data-ago-user-email")||void 0)}t=e?.baseUrl||t,m=e?.widgetId||m,i=e?.agent||e?.defaultAgentId||i,n=e?.permission||n,a=e?.userEmail||a,l=e?.userJwt||l,e?.metadata!==void 0&&(c=e.metadata);const d=e?.debug;return t?{baseUrl:t,widgetId:m,agent:i,permission:n,language:e?.language,userEmail:a,userJwt:l,metadata:c,debug:d}:null}function D(e){const t=h(e);if(!t)throw new f.AgoError('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 o.AgoClient(t)}function L(e,t){return{...e,handler:t}}exports.ActivityLedger=o.ActivityLedger;exports.AgoApiError=f.AgoApiError;exports.AgoClient=o.AgoClient;exports.AgoError=f.AgoError;exports.AgoFunctionError=f.AgoFunctionError;exports.AgoNetworkError=f.AgoNetworkError;exports.AgoStreamError=f.AgoStreamError;exports.ClientContextRegistry=o.ClientContextRegistry;exports.DEFAULT_MAX_ACTIVITY_ENTRIES=o.DEFAULT_MAX_ACTIVITY_ENTRIES;exports.DEFAULT_MAX_ERRORS=o.DEFAULT_MAX_ERRORS;exports.DEFAULT_MAX_ERROR_AGE_MS=o.DEFAULT_MAX_ERROR_AGE_MS;exports.ErrorWatcher=o.ErrorWatcher;exports.EventEmitter=o.EventEmitter;exports.FEEDBACK_REASONS=o.FEEDBACK_REASONS;exports.FunctionRegistry=o.FunctionRegistry;exports.SSEHandler=o.SSEHandler;exports.SignalCollector=o.SignalCollector;exports.attachAutoContinueAfterNavigation=C.attachAutoContinueAfterNavigation;exports.autoDetectConfig=h;exports.canInlineImage=o.canInlineImage;exports.copyToClipboard=g.copyToClipboard;exports.createAgo=D;exports.createAgoProactive=o.createAgoProactive;exports.createConversationSession=p.createConversationSession;exports.createFormCollector=A.createFormCollector;exports.createMessageStream=I;exports.createMockClient=w.createMockClient;exports.createStore=o.createStore;exports.defineFunction=F;exports.deriveFormStatus=A.deriveFormStatus;exports.formatFileSize=o.formatFileSize;exports.getLocalStorage=g.getLocalStorage;exports.getUserLocation=g.getUserLocation;exports.highlightElement=g.highlightElement;exports.isStreamNetworkError=o.isStreamNetworkError;exports.loadFormCollector=A.loadFormCollector;exports.logger=o.logger;exports.matchesRoutePattern=o.matchesRoutePattern;exports.matchesWhen=o.matchesWhen;exports.onFormError=R;exports.onFormSubmitted=T;exports.onFormSubmitting=U;exports.onFunctionInvoke=q;exports.onMessage=_;exports.onMessageChunk=y;exports.onMessageError=b;exports.onMessageStart=M;exports.onToolCall=v;exports.openUrl=g.openUrl;exports.partialDeepMatch=o.partialDeepMatch;exports.safeAttachmentUrl=o.safeAttachmentUrl;exports.scrollToElement=g.scrollToElement;exports.setLocalStorage=g.setLocalStorage;exports.setTheme=g.setTheme;exports.showConfirmDialog=g.showConfirmDialog;exports.showNotification=g.showNotification;exports.showToast=g.showToast;exports.submitForm=g.submitForm;exports.trackEvent=g.trackEvent;exports.validateConfig=o.validateConfig;exports.withHandler=L;

package/dist/index.d.cts

@@ -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.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