@useago/sdk 1.13.1 → 1.13.3

package/llms-full.txt

@@ -1465,6 +1465,11 @@ This registers a `navigateToPage` function whose `page` parameter is an enum of
 your route names. React/Vue offer `useAgoNavigation(navigate, routes)` with
 lifecycle cleanup.
 
+Functions and page state can change with the route. The navigation tool
+instructs the agent to use the destination's functions for remaining actions.
+Use the [auto-continue helper](#navigate-then-change-the-page-in-one-go) to wait
+for destination page-state registration before continuing.
+
 Paths can contain `:param` placeholders. Each placeholder becomes an explicit
 top-level argument of `navigateToPage` (`{ page: "orderDetail", id: "42" }`
 navigates to `/orders/42`), so one route covers every detail page of an entity.
@@ -1473,8 +1478,11 @@ and returns an error telling the agent what to retry with. Placeholders cannot
 be named `page` (that argument selects the route).
 
 It also registers a dynamic context entry ("Current page") that reports the page
-the user is on (by route name, plus URL and title) on every message, so the agent
-knows where it is after it navigates, not just how to navigate away. Call
+the user is on (by route name when matched, plus URL) on every message, so the
+agent knows where it is after it navigates, not just how to navigate away. It
+does not include `document.title`, which may describe a conversation instead of
+the application route. The separate opt-in `enableAutoPageContext()` feature
+still includes the URL and document title. Call
 `client.unregisterNavigationFunction()` to remove both the function and that
 context.
 
@@ -1496,7 +1504,8 @@ client.registerNavigationFunction(
 ```
 
 `navigateToPage` keeps the page names as its `page` enum, so a recognisable name
-can still navigate in one call.
+can still navigate in one call. Both catalogue modes instruct the agent to use
+the destination page's functions and state to finish remaining requested actions.
 
 Give routes a `section` and `listPages` takes it as a required argument, so the
 agent asks for one group at a time and no single answer has to carry the whole
@@ -1564,6 +1573,12 @@ control names are rejected with the list of available controls. A value that
 matches the current `get()` value is skipped without calling `set()` and
 reported as `unchanged`.
 
+Empty enums are omitted from the advertised tool schema because providers
+reject them. Execution still rejects selections when no values are available.
+An empty array remains valid when only its item enum is empty, and a clearable
+string can still be cleared with `""`. Independent fields in the same request
+can still be applied.
+
 React/Vue offer `useAgoPageState(controls, opts?)` with lifecycle cleanup;
 Angular exposes `agoService.registerPageStateFunction(...)`.
 
@@ -1704,7 +1719,8 @@ of reporting a diff, so a page switch never shows up as a spurious change.
 A request like "open the invoices page and show only the overdue ones" needs two
 steps: the agent navigates, then changes the new page's state. But the
 destination page only registers its `setPageState` (and current state) once it
-mounts, so the agent can't do both in a single turn.
+mounts. Continuation must wait for that registration to use the new page's
+capabilities.
 
 `useAgoAutoContinueAfterNavigation()` closes the gap. Mount it once inside
 `AgoProvider`:
@@ -1814,11 +1830,28 @@ client.registerFunction({
   description: "The flights currently on screen, after filtering.",
   parameters: { type: "object", properties: {} },
   handler: () => visibleFlights(),
-  // Optional, WebMCP only: MCP behavior hints.
+  // Optional, WebMCP only: tool annotations.
   webmcp: { annotations: { readOnlyHint: true } },
 });
 ```
 
+The optional `webmcp.annotations` fields describe the tool to browser agents:
+
+| Annotation | Meaning when `true` |
+| --- | --- |
+| `readOnlyHint` | Only reads data and does not change state. |
+| `untrustedContentHint` | Returns content untrusted by the tool author, such as customer reviews. |
+| `consequentialHint` | Has significant, real-world, or irreversible effects, such as purchasing a flight. |
+| `debugging` | Is intended for debugging and developer tooling. |
+
+All four default to `false` in WebMCP. For example, a purchase tool can set
+`webmcp: { annotations: { consequentialHint: true } }`, and a diagnostic tool
+can set `webmcp: { annotations: { debugging: true } }`.
+
+The SDK forwards these annotations to the browser without changing AGO's
+in-app agent behavior. `consequentialHint` and `requiresApproval` are independent:
+neither sets the other, and annotations do not enforce confirmation dialogs.
+
 In React it is a prop:
 
 ```tsx
@@ -2176,6 +2209,7 @@ const final = await client.waitFor("message:complete", { timeout: 10_000 });
 | `function:result` | `{ invocationId, result, error? }` |
 | `activity:recorded` | `ActivityEntry`: a user- or agent-action was recorded into the activity ledger (via `recordActivity`, or auto-recorded when the agent calls a client function). See [Activity ledger](functions-and-context.md#activity-ledger) |
 | `error:captured` | `CapturedError`: the error watcher captured a JavaScript error (uncaught exception, unhandled rejection, `console.error`, or `reportError`). Fires on repeats too, with the updated `count`. Needs `errorWatcher` in the config. See [JavaScript errors](functions-and-context.md#javascript-errors) |
+| `form:submitting` | `{ name, values }`: validated submission is about to start |
 | `form:submitted` | `{ name, values, result }`: a form collector submitted successfully; `result` is the submit response (the third-party API's answer) |
 | `form:error` | `{ name, values, error }`: a form collector submit failed at the network/server level (HTTP non-2xx or a thrown handler/fetch). Validation pre-checks (missing fields, no submit target) do not fire this |
 | `connection:status` | `{ connected }` |
@@ -2216,6 +2250,7 @@ onMessage(client, (msg) => console.log("complete:", msg.content));
 | `onMessageError(client, cb)` | `message:error` |
 | `onToolCall(client, cb)` | `toolCall:received` |
 | `onFunctionInvoke(client, cb)` | `function:invoke` |
+| `onFormSubmitting(client, cb)` | `form:submitting` |
 | `onFormSubmitted(client, cb)` | `form:submitted` |
 | `onFormError(client, cb)` | `form:error` |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useago/sdk",
-  "version": "1.13.1",
+  "version": "1.13.3",
   "description": "Create In-APP AI agents that answers question and performs actions. Works with React, Vue, Angular and vanilla JS/TS.",
   "type": "module",
   "sideEffects": false,

package/dist/createFormCollector-BNCMIUw2.cjs

@@ -1 +0,0 @@
-const C=require("./types-Ck3iZG0K.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 d=l[c]?.requiredWhen;(!d||S(d,e))&&i.add(c)}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]));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,d=i.properties??{},$=t=>{const r={};for(const[o,s]of Object.entries(t)){const u=d[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},N=n.initialValues??{},m=C.createStore({values:N,submitted:!1}),w=t=>{const r=m.get(),o={...r,values:{...r.values,...t}};return m.set(o),o};let b=null;const k=(t,r)=>{b?.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."};const s=t;try{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{if(!b)return{ok:!1,error:"Backend submit requires install(client) (or useFormCollector) first."};u=await b.submitFormCollector(e,s)}return m.set({...m.get(),submitted:!0,submitResult:u}),b?.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}}},F=()=>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:F()},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:()=>F()});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={...N},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`,P=()=>({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}),T=()=>{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}}},E=t=>{x((t.messages??[]).flatMap(r=>r.toolCalls??[]))};return{name:e,store:m,functions:y,contextKey:g,contextProvider:T,definitionContextKey:v,definitionContextProvider:P,install:t=>{b=t;for(const o of y)t.register(o);t.addDynamicContext(v,P),t.addDynamicContext(g,T);const r=m.subscribe(()=>t.notifyContextChanged());return t.on("conversation:loaded",E),()=>{r();for(const o of y)t.unregisterFunction(o.name);t.removeDynamicContext(g),t.removeDynamicContext(v),t.off("conversation:loaded",E),b===t&&(b=null)}},hydrate:x,submit:F,getValues:()=>m.get().values,setValues:t=>{w($(t)),q()},reset:()=>{m.set({values:N,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}});