@useago/sdk 1.5.6 → 1.7.0

package/dist/{createFormCollector-BjO3oB63.cjs → createFormCollector-C1ixsjV0.cjs}

@@ -1 +1 @@
-const C=require("./AgoClient-DLB9icvv.cjs");var W=/^[a-zA-Z0-9_-]{1,40}$/,A=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(A(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=>A(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 V(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 V({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 V}});Object.defineProperty(exports,"deriveFormStatus",{enumerable:!0,get:function(){return h}});Object.defineProperty(exports,"loadFormCollector",{enumerable:!0,get:function(){return L}});
+const C=require("./AgoClient-BHegN73y.cjs");var W=/^[a-zA-Z0-9_-]{1,40}$/,A=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(A(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=>A(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 V(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 V({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 V}});Object.defineProperty(exports,"deriveFormStatus",{enumerable:!0,get:function(){return h}});Object.defineProperty(exports,"loadFormCollector",{enumerable:!0,get:function(){return L}});

package/dist/{createFormCollector-YwaZ78wU.js → createFormCollector-CvVFNkp6.js}

@@ -1,4 +1,4 @@
-import { h as R, v as w } from "./AgoClient-B_R_qi2s.js";
+import { h as R, v as w } from "./AgoClient-PWPaekcg.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));

package/dist/{createMockClient-DcuNlufr.js → createMockClient-BDLW6tVc.js}

@@ -1,4 +1,4 @@
-function v(g = {}) {
+function y(g = {}) {
   const { overrides: u = {} } = g, a = {
     id: "mock-msg-1",
     conversationId: "mock-conv-1",
@@ -13,6 +13,9 @@ function v(g = {}) {
   }, o = /* @__PURE__ */ new Map(), c = [], m = {
     sendMessage: async () => a,
     continueMessage: async () => a,
+    stop: async () => null,
+    stopMessage: async () => ({ status: "not_running" }),
+    isGenerating: () => !1,
     resumePendingClientFunctions: async () => null,
     registerResumeGate: () => () => {
     },
@@ -93,5 +96,5 @@ function v(g = {}) {
   }, i;
 }
 export {
-  v as t
+  y as t
 };

package/dist/createMockClient-BSNuN3ys.cjs

@@ -0,0 +1 @@
+function y(u={}){const{overrides:g={}}=u,a={id:"mock-msg-1",conversationId:"mock-conv-1",content:"Mock response",role:"assistant",status:"DONE",createdAt:new Date},l={id:"mock-conv-1",title:"Mock Conversation",lastMessageDate:new Date},n=new Map,r=[],m={sendMessage:async()=>a,continueMessage:async()=>a,stop:async()=>null,stopMessage:async()=>({status:"not_running"}),isGenerating:()=>!1,resumePendingClientFunctions:async()=>null,registerResumeGate:()=>()=>{},getConversations:async()=>[l],getConversation:async()=>l,getMessages:async()=>[a],submitToolCallForm:async()=>({status:"completed"}),confirmToolCall:async()=>{},rejectToolCall:async()=>{},submitFeedback:async()=>{},registerFunction:()=>{},unregisterFunction:()=>!0,getRegisteredFunctions:()=>[],executeClientFunction:async()=>{},getContextSnapshot:()=>null,notifyContextChanged:()=>{},setContext:()=>{},removeContext:()=>!0,addDynamicContext:()=>{},removeDynamicContext:()=>!0,registerNavigationFunction:()=>{},unregisterNavigationFunction:()=>{},getConfiguredAgent:()=>{},getHttp:()=>({get:async()=>({}),post:async()=>({})}),emitProactiveEvent:(e,t)=>{const o=n.get(e);o&&[...o].forEach(s=>s(t))},on:(e,t)=>{n.has(e)||n.set(e,new Set),n.get(e).add(t)},off:(e,t)=>{n.get(e)?.delete(t)},once:(e,t)=>{const o=(...s)=>{n.get(e)?.delete(o),t(...s)};n.has(e)||n.set(e,new Set),n.get(e).add(o)},waitFor:(e,t)=>new Promise((o,s)=>{let c;const d=f=>{c&&clearTimeout(c),n.get(e)?.delete(d),o(f)};n.has(e)||n.set(e,new Set),n.get(e).add(d),t?.timeout&&(c=setTimeout(()=>{n.get(e)?.delete(d),s(new Error(`waitFor("${e}") timed out after ${t.timeout}ms`))},t.timeout))}),updateConfig:()=>{},destroy:()=>{n.clear()},...g},i={};for(const[e,t]of Object.entries(m))i[e]=(...o)=>(r.push({method:e,args:o}),t(...o));return i.proactive=null,i.__calls=r,i.__callsFor=e=>r.filter(t=>t.method===e),i.__emitEvent=(e,t)=>{const o=n.get(e);o&&[...o].forEach(s=>s(t))},i}Object.defineProperty(exports,"createMockClient",{enumerable:!0,get:function(){return y}});

package/dist/devtools.d.cts

@@ -57,6 +57,10 @@ declare class AgoClient {
     private config;
     /** Conversations already warned about an empty reply (one warning each). */
     private warnedEmptyConversations;
+    /** Whether the placeholder-mode page-data warning has already been logged. */
+    private warnedPageDataPlaceholder;
+    /** `readPageData` companions this SDK registered, so cleanup only removes its own. */
+    private pageDataCompanions;
     /** Paused turns awaiting auto-resume, keyed by assistant message id. */
     private pendingResumes;
     /**
@@ -67,6 +71,20 @@ declare class AgoClient {
     private pendingApprovals;
     /** App-provided gate deciding WHEN a paused turn resumes (see {@link registerResumeGate}). */
     private resumeGate;
+    /** The turn currently streaming, or `null` when the client is idle. */
+    private activeTurn;
+    /**
+     * A turn that closed as `WAITING_CLIENT` and has not resumed yet. There is no
+     * open stream in that window, but the turn is still live for the user, so it
+     * stays stoppable (see {@link stop}).
+     */
+    private pausedTurn;
+    /**
+     * Turns stopped while they were paused on client functions. A resume may
+     * already be queued (or waiting on the resume gate) at that point; this drops
+     * it, so a stopped turn is never restarted.
+     */
+    private stoppedTurnIds;
     /**
      * Proactive-mode controller, set when the client was created with
      * `proactive` options or when `createAgoProactive(client, opts)` was called.
@@ -78,7 +96,53 @@ declare class AgoClient {
      * Send a message and receive a streaming response
      */
     sendMessage(content: string, options?: SendMessageOptions): Promise<AgoMessage>;
+    /**
+     * Fire the streaming request, returning `null` when the user stopped before
+     * the response came back. Any other failure ends the turn and propagates, so
+     * a real error still reaches the caller.
+     */
+    private sendRequest;
     private processSSEResponse;
+    /**
+     * Stop the turn that is generating right now: closes the stream so the UI
+     * stops immediately, and tells the backend to stop generating.
+     *
+     * Both halves matter. Closing the stream alone does NOT stop the agent — it
+     * keeps running and the full answer reappears the next time the conversation
+     * is loaded. The backend unwinds at its next safe point (any tool already
+     * running finishes, no further tool or reasoning round starts), keeps the text
+     * produced so far and finalizes the message as `CANCELED`.
+     *
+     * The in-flight `sendMessage` / `continueMessage` promise resolves normally
+     * with that partial message (it does not reject), `message:complete` fires
+     * with status `CANCELED`, then `message:stopped`.
+     *
+     * ```ts
+     * // "Stop" button
+     * stopButton.onclick = () => void client.stop();
+     * ```
+     *
+     * Returns the backend's verdict, or `null` when nothing was generating or the
+     * stop landed before the message had an id (the stream is still closed).
+     */
+    stop(): Promise<StopMessageResult | null>;
+    /**
+     * Ask the backend to stop a specific in-flight turn, without touching any
+     * local stream. Idempotent — stopping a finished turn answers
+     * `{ status: "not_running" }` rather than failing. Most apps want
+     * {@link stop} instead; use this to stop a turn started elsewhere (e.g. one
+     * still running after a page reload, found via `getConversation`).
+     */
+    stopMessage(messageId: string): Promise<StopMessageResult>;
+    /** Whether a turn is generating right now (i.e. {@link stop} has something to stop). */
+    isGenerating(): boolean;
+    /** Open a new turn, replacing any bookkeeping left by the previous one. */
+    private beginTurn;
+    private endTurn;
+    /** POST the stop for a turn, once, never letting the failure escape. */
+    private postStopForTurn;
+    /** The message a caller gets back when the stop beat the response. */
+    private buildStoppedMessage;
     private resolveClientFunctionsMode;
     /**
      * Register a gate deciding WHEN a paused turn resumes. The SDK still decides
@@ -306,13 +370,38 @@ declare class AgoClient {
      *   },
      * ]);
      * ```
+     *
+     * Pass `opts.data` and the agent also gets back **what the page now shows**,
+     * as the result of its own call, instead of having to wait for the next
+     * message's context. That also registers a read-only `readPageData`
+     * companion. See {@link AgoPageDataSource}.
      */
     registerPageStateFunction(controls: AgoStateControl[], opts?: AgoPageStateOptions): void;
     /**
-     * Unregister a page state function and its dynamic context provider.
-     * Mirror of unregistering `navigateToPage`.
+     * Unregister a page state function, its `readPageData` companion, and its
+     * dynamic context provider. Mirror of unregistering `navigateToPage`.
      */
     unregisterPageStateFunction(functionName?: string): void;
+    /**
+     * Size ceiling for a page snapshot, before the envelope is accounted for.
+     * Read at call time, not at registration, so `updateConfig` moves it.
+     */
+    private pageDataBudget;
+    /** Bytes the non-`data` part of the result costs, `data` included as `null`. */
+    private envelopeBytes;
+    /**
+     * Wait for the page to stop reloading, then read the snapshot. `get` and
+     * `isLoading` are re-read from `source` on every tick so a re-render that
+     * swaps the closures (without re-registering) is picked up mid-wait.
+     */
+    private readPageData;
+    /**
+     * The snapshot only reaches the agent inside the same turn in pause mode,
+     * where the SDK submits the tool result and resumes. In placeholder mode the
+     * turn is already over, so a `data` source looks broken from the outside:
+     * say so once rather than let the integrator hunt for an SDK bug.
+     */
+    private warnIfPlaceholderMode;
     /**
      * Register or update a piece of client-side context.
      * This context is sent with every message so the AI understands the user's situation.
@@ -480,6 +569,18 @@ declare interface AgoClientEvents {
         conversationId: string;
         messageId: string;
     };
+    /**
+     * The user stopped the turn (`client.stop()`): the stream was closed and the
+     * backend was told to stop generating. Always fires, so this is the event to
+     * finalize a UI on. When there was an answer to keep, a `message:complete`
+     * carrying it with status `CANCELED` fires first; there is none when the stop
+     * landed before the backend named the message (`messageId` is then an empty
+     * string) or when the stopped turn was paused on client functions.
+     */
+    "message:stopped": {
+        conversationId: string;
+        messageId: string;
+    };
     "message:error": {
         error: string;
         /** Stable error code (see configuration.md#error-codes) when the failure was an AgoError. */
@@ -673,6 +774,80 @@ declare interface AgoMessage {
     createdAt: Date;
 }
 
+/**
+ * What the page currently displays, returned to the agent as the *result* of
+ * `setPageState` instead of only as context on the next message.
+ *
+ * Declare it when the agent should be able to act on what its own change
+ * produced ("search for dupont" → it can say who was found).
+ *
+ * A control change usually kicks off work (a refetch, a recomputation). The SDK
+ * has to wait for that work before reading, and there are two ways to tell it
+ * when the work is done. **Prefer the first.**
+ *
+ * **1. Return a promise from `get()`** — you own the await, so the SDK is
+ * exact: it resolves when your work resolves, with no polling and no timing
+ * assumption. With TanStack Query, `ensureQueryData` gives you that promise and
+ * shares the single in-flight request with the UI:
+ *
+ * ```ts
+ * useAgoPageState(controls, {
+ *   data: {
+ *     description: "The users matching the current filters.",
+ *     get: () => queryClient.ensureQueryData({
+ *       queryKey: ["users", filters],
+ *       queryFn: fetchUsers,
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * **2. Declare `isLoading`** — for data you cannot get a promise for. The SDK
+ * polls it instead, which is a heuristic: the flag has to be up within ~100 ms
+ * of the change or the SDK concludes the page settled and reads the previous
+ * rows. Fine for a query library that flips `isFetching` on render, wrong for a
+ * debounced fetch.
+ *
+ * ```ts
+ * const { data: users, isFetching } = useQuery({ queryKey: ["users", filters], queryFn: fetchUsers });
+ *
+ * useAgoPageState(controls, {
+ *   data: {
+ *     description: "The users matching the current filters.",
+ *     get: () => users ?? [],
+ *     // isFetching, NOT isLoading: a background refetch must count as loading,
+ *     // otherwise the agent reads the rows from the previous search.
+ *     isLoading: () => isFetching,
+ *   },
+ * });
+ * ```
+ */
+declare interface AgoPageDataSource<T = unknown> {
+    /** What this data is, for the LLM: "The users matching the current filters." */
+    description: string;
+    /**
+     * The snapshot handed back to the agent.
+     *
+     * Return a promise and the SDK awaits it: that promise resolving *is* the
+     * signal that the work the change triggered has finished, so nothing is
+     * guessed. It is bounded by `settleTimeoutMs`.
+     */
+    get: () => T | Promise<T>;
+    /**
+     * True while the page is (re)loading this data. Only needed when `get()`
+     * cannot return a promise. The SDK polls it every 50 ms and treats two
+     * consecutive `false` readings as settled, so a flag raised more than ~100 ms
+     * after the change is missed and the agent reads stale rows.
+     */
+    isLoading?: () => boolean;
+    /**
+     * Size ceiling for the returned snapshot, in bytes. Defaults to the client's
+     * `maxFunctionResultBytes`. Over the ceiling the snapshot keeps the first
+     * whole items that fit; `success` and `applied` are never dropped.
+     */
+    maxResultBytes?: number;
+}
+
 /**
  * Options for {@link AgoClient.registerPageStateFunction}.
  */
@@ -684,6 +859,23 @@ declare interface AgoPageStateOptions {
      * {@link AgoConfig.approvalPolicy} — pause mode only. Defaults to `false`.
      */
     requiresApproval?: boolean;
+    /**
+     * Declare what the page displays so `setPageState` returns it. Omit it and
+     * the result stays exactly `{ success, applied }`.
+     *
+     * Also registers a read-only companion function (`readPageData`, derived from
+     * `functionName`) that returns the same snapshot without touching the page.
+     *
+     * The snapshot travels only when the agent calls one of those functions: it
+     * is deliberately kept out of the `page-state:` dynamic context, which would
+     * put it in every message.
+     */
+    data?: AgoPageDataSource;
+    /**
+     * How long to wait for the page to finish reloading before reading the
+     * snapshot. Defaults to 10 000 ms; on timeout whatever is there is returned.
+     */
+    settleTimeoutMs?: number;
 }
 
 /**
@@ -1006,13 +1198,21 @@ declare class HttpClient {
         keepalive?: boolean;
     }): Promise<T>;
     /**
-     * Make a POST request and return the raw Response (for streaming)
+     * Make a POST request and return the raw Response (for streaming).
+     *
+     * `signal` lets the caller close the stream mid-flight (see
+     * `AgoClient.stop`); an abort is rethrown as-is rather than wrapped in an
+     * `AgoNetworkError`, so a deliberate stop is not mistaken for a network drop.
      */
-    postStream(path: string, body?: unknown): Promise<Response>;
+    postStream(path: string, body?: unknown, options?: {
+        signal?: AbortSignal;
+    }): Promise<Response>;
     /**
      * Make a POST request with FormData (for file uploads)
      */
-    postFormData(path: string, formData: FormData): Promise<Response>;
+    postFormData(path: string, formData: FormData, options?: {
+        signal?: AbortSignal;
+    }): Promise<Response>;
     private request;
     private handleErrorResponse;
 }
@@ -1338,6 +1538,21 @@ declare interface SSEChunkData {
     waiting_tool_call_ids?: string[];
 }
 
+/**
+ * Response of `POST /messages/{id}/stop` (see `AgoClient.stopMessage`).
+ *
+ * - `"stopping"` — the request was accepted; the turn unwinds at its next safe
+ *   point and finalizes as `CANCELED`, keeping the text produced so far.
+ * - `"not_running"` — the turn had already finished. Harmless.
+ * - `"not_supported"` — a background agent run, which cannot be stopped once
+ *   started.
+ */
+declare interface StopMessageResult {
+    status: "stopping" | "not_running" | "not_supported";
+    /** The message's status when the stop was requested. */
+    messageStatus?: MessageStatus;
+}
+
 /** The slice of the Web Storage API that {@link createStore} relies on. */
 declare type StorageLike = Pick<Storage, "getItem" | "setItem">;
 

package/dist/devtools.d.ts

@@ -57,6 +57,10 @@ declare class AgoClient {
     private config;
     /** Conversations already warned about an empty reply (one warning each). */
     private warnedEmptyConversations;
+    /** Whether the placeholder-mode page-data warning has already been logged. */
+    private warnedPageDataPlaceholder;
+    /** `readPageData` companions this SDK registered, so cleanup only removes its own. */
+    private pageDataCompanions;
     /** Paused turns awaiting auto-resume, keyed by assistant message id. */
     private pendingResumes;
     /**
@@ -67,6 +71,20 @@ declare class AgoClient {
     private pendingApprovals;
     /** App-provided gate deciding WHEN a paused turn resumes (see {@link registerResumeGate}). */
     private resumeGate;
+    /** The turn currently streaming, or `null` when the client is idle. */
+    private activeTurn;
+    /**
+     * A turn that closed as `WAITING_CLIENT` and has not resumed yet. There is no
+     * open stream in that window, but the turn is still live for the user, so it
+     * stays stoppable (see {@link stop}).
+     */
+    private pausedTurn;
+    /**
+     * Turns stopped while they were paused on client functions. A resume may
+     * already be queued (or waiting on the resume gate) at that point; this drops
+     * it, so a stopped turn is never restarted.
+     */
+    private stoppedTurnIds;
     /**
      * Proactive-mode controller, set when the client was created with
      * `proactive` options or when `createAgoProactive(client, opts)` was called.
@@ -78,7 +96,53 @@ declare class AgoClient {
      * Send a message and receive a streaming response
      */
     sendMessage(content: string, options?: SendMessageOptions): Promise<AgoMessage>;
+    /**
+     * Fire the streaming request, returning `null` when the user stopped before
+     * the response came back. Any other failure ends the turn and propagates, so
+     * a real error still reaches the caller.
+     */
+    private sendRequest;
     private processSSEResponse;
+    /**
+     * Stop the turn that is generating right now: closes the stream so the UI
+     * stops immediately, and tells the backend to stop generating.
+     *
+     * Both halves matter. Closing the stream alone does NOT stop the agent — it
+     * keeps running and the full answer reappears the next time the conversation
+     * is loaded. The backend unwinds at its next safe point (any tool already
+     * running finishes, no further tool or reasoning round starts), keeps the text
+     * produced so far and finalizes the message as `CANCELED`.
+     *
+     * The in-flight `sendMessage` / `continueMessage` promise resolves normally
+     * with that partial message (it does not reject), `message:complete` fires
+     * with status `CANCELED`, then `message:stopped`.
+     *
+     * ```ts
+     * // "Stop" button
+     * stopButton.onclick = () => void client.stop();
+     * ```
+     *
+     * Returns the backend's verdict, or `null` when nothing was generating or the
+     * stop landed before the message had an id (the stream is still closed).
+     */
+    stop(): Promise<StopMessageResult | null>;
+    /**
+     * Ask the backend to stop a specific in-flight turn, without touching any
+     * local stream. Idempotent — stopping a finished turn answers
+     * `{ status: "not_running" }` rather than failing. Most apps want
+     * {@link stop} instead; use this to stop a turn started elsewhere (e.g. one
+     * still running after a page reload, found via `getConversation`).
+     */
+    stopMessage(messageId: string): Promise<StopMessageResult>;
+    /** Whether a turn is generating right now (i.e. {@link stop} has something to stop). */
+    isGenerating(): boolean;
+    /** Open a new turn, replacing any bookkeeping left by the previous one. */
+    private beginTurn;
+    private endTurn;
+    /** POST the stop for a turn, once, never letting the failure escape. */
+    private postStopForTurn;
+    /** The message a caller gets back when the stop beat the response. */
+    private buildStoppedMessage;
     private resolveClientFunctionsMode;
     /**
      * Register a gate deciding WHEN a paused turn resumes. The SDK still decides
@@ -306,13 +370,38 @@ declare class AgoClient {
      *   },
      * ]);
      * ```
+     *
+     * Pass `opts.data` and the agent also gets back **what the page now shows**,
+     * as the result of its own call, instead of having to wait for the next
+     * message's context. That also registers a read-only `readPageData`
+     * companion. See {@link AgoPageDataSource}.
      */
     registerPageStateFunction(controls: AgoStateControl[], opts?: AgoPageStateOptions): void;
     /**
-     * Unregister a page state function and its dynamic context provider.
-     * Mirror of unregistering `navigateToPage`.
+     * Unregister a page state function, its `readPageData` companion, and its
+     * dynamic context provider. Mirror of unregistering `navigateToPage`.
      */
     unregisterPageStateFunction(functionName?: string): void;
+    /**
+     * Size ceiling for a page snapshot, before the envelope is accounted for.
+     * Read at call time, not at registration, so `updateConfig` moves it.
+     */
+    private pageDataBudget;
+    /** Bytes the non-`data` part of the result costs, `data` included as `null`. */
+    private envelopeBytes;
+    /**
+     * Wait for the page to stop reloading, then read the snapshot. `get` and
+     * `isLoading` are re-read from `source` on every tick so a re-render that
+     * swaps the closures (without re-registering) is picked up mid-wait.
+     */
+    private readPageData;
+    /**
+     * The snapshot only reaches the agent inside the same turn in pause mode,
+     * where the SDK submits the tool result and resumes. In placeholder mode the
+     * turn is already over, so a `data` source looks broken from the outside:
+     * say so once rather than let the integrator hunt for an SDK bug.
+     */
+    private warnIfPlaceholderMode;
     /**
      * Register or update a piece of client-side context.
      * This context is sent with every message so the AI understands the user's situation.
@@ -480,6 +569,18 @@ declare interface AgoClientEvents {
         conversationId: string;
         messageId: string;
     };
+    /**
+     * The user stopped the turn (`client.stop()`): the stream was closed and the
+     * backend was told to stop generating. Always fires, so this is the event to
+     * finalize a UI on. When there was an answer to keep, a `message:complete`
+     * carrying it with status `CANCELED` fires first; there is none when the stop
+     * landed before the backend named the message (`messageId` is then an empty
+     * string) or when the stopped turn was paused on client functions.
+     */
+    "message:stopped": {
+        conversationId: string;
+        messageId: string;
+    };
     "message:error": {
         error: string;
         /** Stable error code (see configuration.md#error-codes) when the failure was an AgoError. */
@@ -673,6 +774,80 @@ declare interface AgoMessage {
     createdAt: Date;
 }
 
+/**
+ * What the page currently displays, returned to the agent as the *result* of
+ * `setPageState` instead of only as context on the next message.
+ *
+ * Declare it when the agent should be able to act on what its own change
+ * produced ("search for dupont" → it can say who was found).
+ *
+ * A control change usually kicks off work (a refetch, a recomputation). The SDK
+ * has to wait for that work before reading, and there are two ways to tell it
+ * when the work is done. **Prefer the first.**
+ *
+ * **1. Return a promise from `get()`** — you own the await, so the SDK is
+ * exact: it resolves when your work resolves, with no polling and no timing
+ * assumption. With TanStack Query, `ensureQueryData` gives you that promise and
+ * shares the single in-flight request with the UI:
+ *
+ * ```ts
+ * useAgoPageState(controls, {
+ *   data: {
+ *     description: "The users matching the current filters.",
+ *     get: () => queryClient.ensureQueryData({
+ *       queryKey: ["users", filters],
+ *       queryFn: fetchUsers,
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * **2. Declare `isLoading`** — for data you cannot get a promise for. The SDK
+ * polls it instead, which is a heuristic: the flag has to be up within ~100 ms
+ * of the change or the SDK concludes the page settled and reads the previous
+ * rows. Fine for a query library that flips `isFetching` on render, wrong for a
+ * debounced fetch.
+ *
+ * ```ts
+ * const { data: users, isFetching } = useQuery({ queryKey: ["users", filters], queryFn: fetchUsers });
+ *
+ * useAgoPageState(controls, {
+ *   data: {
+ *     description: "The users matching the current filters.",
+ *     get: () => users ?? [],
+ *     // isFetching, NOT isLoading: a background refetch must count as loading,
+ *     // otherwise the agent reads the rows from the previous search.
+ *     isLoading: () => isFetching,
+ *   },
+ * });
+ * ```
+ */
+declare interface AgoPageDataSource<T = unknown> {
+    /** What this data is, for the LLM: "The users matching the current filters." */
+    description: string;
+    /**
+     * The snapshot handed back to the agent.
+     *
+     * Return a promise and the SDK awaits it: that promise resolving *is* the
+     * signal that the work the change triggered has finished, so nothing is
+     * guessed. It is bounded by `settleTimeoutMs`.
+     */
+    get: () => T | Promise<T>;
+    /**
+     * True while the page is (re)loading this data. Only needed when `get()`
+     * cannot return a promise. The SDK polls it every 50 ms and treats two
+     * consecutive `false` readings as settled, so a flag raised more than ~100 ms
+     * after the change is missed and the agent reads stale rows.
+     */
+    isLoading?: () => boolean;
+    /**
+     * Size ceiling for the returned snapshot, in bytes. Defaults to the client's
+     * `maxFunctionResultBytes`. Over the ceiling the snapshot keeps the first
+     * whole items that fit; `success` and `applied` are never dropped.
+     */
+    maxResultBytes?: number;
+}
+
 /**
  * Options for {@link AgoClient.registerPageStateFunction}.
  */
@@ -684,6 +859,23 @@ declare interface AgoPageStateOptions {
      * {@link AgoConfig.approvalPolicy} — pause mode only. Defaults to `false`.
      */
     requiresApproval?: boolean;
+    /**
+     * Declare what the page displays so `setPageState` returns it. Omit it and
+     * the result stays exactly `{ success, applied }`.
+     *
+     * Also registers a read-only companion function (`readPageData`, derived from
+     * `functionName`) that returns the same snapshot without touching the page.
+     *
+     * The snapshot travels only when the agent calls one of those functions: it
+     * is deliberately kept out of the `page-state:` dynamic context, which would
+     * put it in every message.
+     */
+    data?: AgoPageDataSource;
+    /**
+     * How long to wait for the page to finish reloading before reading the
+     * snapshot. Defaults to 10 000 ms; on timeout whatever is there is returned.
+     */
+    settleTimeoutMs?: number;
 }
 
 /**
@@ -1006,13 +1198,21 @@ declare class HttpClient {
         keepalive?: boolean;
     }): Promise<T>;
     /**
-     * Make a POST request and return the raw Response (for streaming)
+     * Make a POST request and return the raw Response (for streaming).
+     *
+     * `signal` lets the caller close the stream mid-flight (see
+     * `AgoClient.stop`); an abort is rethrown as-is rather than wrapped in an
+     * `AgoNetworkError`, so a deliberate stop is not mistaken for a network drop.
      */
-    postStream(path: string, body?: unknown): Promise<Response>;
+    postStream(path: string, body?: unknown, options?: {
+        signal?: AbortSignal;
+    }): Promise<Response>;
     /**
      * Make a POST request with FormData (for file uploads)
      */
-    postFormData(path: string, formData: FormData): Promise<Response>;
+    postFormData(path: string, formData: FormData, options?: {
+        signal?: AbortSignal;
+    }): Promise<Response>;
     private request;
     private handleErrorResponse;
 }
@@ -1338,6 +1538,21 @@ declare interface SSEChunkData {
     waiting_tool_call_ids?: string[];
 }
 
+/**
+ * Response of `POST /messages/{id}/stop` (see `AgoClient.stopMessage`).
+ *
+ * - `"stopping"` — the request was accepted; the turn unwinds at its next safe
+ *   point and finalizes as `CANCELED`, keeping the text produced so far.
+ * - `"not_running"` — the turn had already finished. Harmless.
+ * - `"not_supported"` — a background agent run, which cannot be stopped once
+ *   started.
+ */
+declare interface StopMessageResult {
+    status: "stopping" | "not_running" | "not_supported";
+    /** The message's status when the stop was requested. */
+    messageStatus?: MessageStatus;
+}
+
 /** The slice of the Web Storage API that {@link createStore} relies on. */
 declare type StorageLike = Pick<Storage, "getItem" | "setItem">;