@useago/sdk 1.5.5 → 1.7.0

package/dist/testing.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;
 }
 
 /**
@@ -996,13 +1188,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;
 }
@@ -1356,6 +1556,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/testing.js

@@ -1,4 +1,4 @@
-import { t as e } from "./createMockClient-DcuNlufr.js";
+import { t as e } from "./createMockClient-BDLW6tVc.js";
 export {
   e as createMockClient
 };

package/dist/vue.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const I=require("./AgoClient-CQh8YovA.cjs");let o=require("vue");var w=Symbol("ago-client"),N={install(t,e){const n=new I.AgoClient(e);t.provide(w,n)}};function v(t){if(t)return new I.AgoClient(t);const e=(0,o.inject)(w);if(!e)throw new Error("useAgo(): no AgoClient found. Either pass config or install AgoPlugin.");return e}function M(t={}){const e=t.client??v(),n=(0,o.ref)([]),s=(0,o.ref)(t.conversationId),a=(0,o.ref)(!1),u=(0,o.ref)(null),c=r=>{s.value||(s.value=r.conversationId)},f=r=>{const i=n.value.findIndex(d=>d.id===r.messageId);i>=0&&(n.value[i]={...n.value[i],content:n.value[i].content+r.content})},m=r=>{const i=n.value.findIndex(d=>d.id===r.id);i>=0?n.value[i]=r:n.value.push(r),a.value=!1},C=r=>{u.value=new Error(r.error),a.value=!1};(0,o.onMounted)(()=>{e.on("message:start",c),e.on("message:chunk",f),e.on("message:complete",m),e.on("message:error",C)}),(0,o.onUnmounted)(()=>{e.off("message:start",c),e.off("message:chunk",f),e.off("message:complete",m),e.off("message:error",C)});async function g(r,i){a.value=!0,u.value=null;const d={id:`temp-${Date.now()}`,conversationId:s.value||"",content:r,role:"user",status:"DONE",createdAt:new Date},y={id:`temp-assistant-${Date.now()}`,conversationId:s.value||"",content:"",role:"assistant",status:"IN_PROGRESS",createdAt:new Date};n.value.push(d,y);try{const l=await e.sendMessage(r,{conversationId:s.value,files:i});l.conversationId&&!s.value&&(s.value=l.conversationId),n.value=n.value.filter(A=>!A.id.startsWith("temp-"));const p={...d,id:d.id.replace("temp-","user-"),conversationId:l.conversationId};return n.value.some(A=>A.id===l.id)?n.value.push(p):n.value.push(p,l),l}catch(l){return u.value=l instanceof Error?l:new Error("Failed to send"),a.value=!1,n.value=n.value.filter(p=>!p.id.startsWith("temp-")),null}}function h(){n.value=[],s.value=void 0,u.value=null}return{messages:n,isLoading:a,error:u,conversationId:s,sendMessage:g,clearMessages:h}}function E(t={}){const e=t.client??v(),n=t.autoLoad??!0,s=(0,o.ref)([]),a=(0,o.ref)(null),u=(0,o.ref)(!1),c=(0,o.ref)(null);async function f(){u.value=!0,c.value=null;try{s.value=(await e.getConversations()).data}catch(g){c.value=g instanceof Error?g:new Error("Failed to load conversations")}finally{u.value=!1}}async function m(g){u.value=!0,c.value=null;try{a.value=await e.getConversation(g)}catch(h){c.value=h instanceof Error?h:new Error("Failed to load conversation")}finally{u.value=!1}}function C(){a.value=null}return(0,o.onMounted)(()=>{n&&f()}),{conversations:s,currentConversation:a,isLoading:u,error:c,selectConversation:m,startNewConversation:C,refreshConversations:f}}function S(t={}){const e=M({client:t.client,conversationId:t.conversationId}),n=E({client:t.client,autoLoad:t.autoLoad}),s=(0,o.computed)(()=>e.error.value||n.error.value);return{messages:e.messages,isLoading:e.isLoading,error:s,sendMessage:e.sendMessage,clearMessages:e.clearMessages,conversationId:e.conversationId,conversations:n.conversations,currentConversation:n.currentConversation,isConversationsLoading:n.isLoading,selectConversation:n.selectConversation,startNewConversation:n.startNewConversation,refreshConversations:n.refreshConversations}}function L(t,e){const n=v();(0,o.onMounted)(()=>{n.registerFunction(t,e.handler,{description:e.description,parameters:e.parameters,maxResultBytes:e.maxResultBytes})}),(0,o.onUnmounted)(()=>{n.unregisterFunction(t)})}function P(t,e){const n=v();(0,o.onMounted)(()=>{n.registerNavigationFunction(t,e)}),(0,o.onUnmounted)(()=>{n.unregisterNavigationFunction()})}function F(t,e){const n=v(),s=e?.functionName??"setPageState";(0,o.onMounted)(()=>{n.registerPageStateFunction(t,{functionName:s})}),(0,o.onUnmounted)(()=>{n.unregisterPageStateFunction(s)})}function R(t,e){const n=v();(0,o.onMounted)(()=>{n.on(t,e)}),(0,o.onUnmounted)(()=>{n.off(t,e)})}function U(t){const e=(0,o.shallowRef)(t.get());return(0,o.onScopeDispose)(t.subscribe(n=>{e.value=n})),e}function D(){const t=v(),e=(0,o.shallowRef)(null),n=a=>{e.value=a,t.proactive?.shown(a)},s=({nudge:a})=>{e.value?.id===a.id&&(e.value=null)};return(0,o.onMounted)(()=>{t.on("nudge:ready",n),t.on("nudge:accepted",s),t.on("nudge:dismissed",s)}),(0,o.onUnmounted)(()=>{t.off("nudge:ready",n),t.off("nudge:accepted",s),t.off("nudge:dismissed",s)}),{nudge:e,accept:async()=>{const a=e.value;a&&(e.value=null,await t.proactive?.accept(a))},dismiss:()=>{const a=e.value;a&&(e.value=null,t.proactive?.dismiss(a))}}}exports.AGO_CLIENT_KEY=w;exports.AgoPlugin=N;exports.useAgo=v;exports.useAgoEvents=R;exports.useAgoFunction=L;exports.useAgoNavigation=P;exports.useAgoPageState=F;exports.useAgoStore=U;exports.useChat=S;exports.useConversation=E;exports.useMessages=M;exports.useProactiveNudge=D;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const w=require("./AgoClient-BHegN73y.cjs");let o=require("vue");var I=Symbol("ago-client"),L={install(t,e){const n=new w.AgoClient(e);t.provide(I,n)}};function d(t){if(t)return new w.AgoClient(t);const e=(0,o.inject)(I);if(!e)throw new Error("useAgo(): no AgoClient found. Either pass config or install AgoPlugin.");return e}function E(t={}){const e=t.client??d(),n=(0,o.ref)([]),s=(0,o.ref)(t.conversationId),a=(0,o.ref)(!1),i=(0,o.ref)(null),v=r=>{s.value||(s.value=r.conversationId)},f=r=>{const u=n.value.findIndex(l=>l.id===r.messageId);u>=0&&(n.value[u]={...n.value[u],content:n.value[u].content+r.content})},m=r=>{const u=n.value.findIndex(l=>l.id===r.id);u>=0?n.value[u]=r:n.value.push(r),a.value=!1},p=r=>{i.value=new Error(r.error),a.value=!1},g=()=>{let r=-1;for(let u=n.value.length-1;u>=0;u--){const l=n.value[u];if(l.role==="assistant"&&(l.status==="IN_PROGRESS"||l.status==="WAITING_CLIENT")){r=u;break}}r>=0&&(n.value[r].content?n.value[r]={...n.value[r],status:"CANCELED"}:n.value.splice(r,1)),a.value=!1};(0,o.onMounted)(()=>{e.on("message:start",v),e.on("message:chunk",f),e.on("message:complete",m),e.on("message:error",p),e.on("message:stopped",g)}),(0,o.onUnmounted)(()=>{e.off("message:start",v),e.off("message:chunk",f),e.off("message:complete",m),e.off("message:error",p),e.off("message:stopped",g)});async function C(r,u){a.value=!0,i.value=null;const l={id:`temp-${Date.now()}`,conversationId:s.value||"",content:r,role:"user",status:"DONE",createdAt:new Date},S={id:`temp-assistant-${Date.now()}`,conversationId:s.value||"",content:"",role:"assistant",status:"IN_PROGRESS",createdAt:new Date};n.value.push(l,S);try{const c=await e.sendMessage(r,{conversationId:s.value,files:u});c.conversationId&&!s.value&&(s.value=c.conversationId),n.value=n.value.filter(A=>!A.id.startsWith("temp-"));const h={...l,id:l.id.replace("temp-","user-"),conversationId:c.conversationId};return n.value.some(A=>A.id===c.id)?n.value.push(h):n.value.push(h,c),c}catch(c){return i.value=c instanceof Error?c:new Error("Failed to send"),a.value=!1,n.value=n.value.filter(h=>!h.id.startsWith("temp-")),null}}async function M(){await e.stop()}function y(){n.value=[],s.value=void 0,i.value=null}return{messages:n,isLoading:a,error:i,conversationId:s,sendMessage:C,stop:M,clearMessages:y}}function N(t={}){const e=t.client??d(),n=t.autoLoad??!0,s=(0,o.ref)([]),a=(0,o.ref)(null),i=(0,o.ref)(!1),v=(0,o.ref)(null);async function f(){i.value=!0,v.value=null;try{s.value=(await e.getConversations()).data}catch(g){v.value=g instanceof Error?g:new Error("Failed to load conversations")}finally{i.value=!1}}async function m(g){i.value=!0,v.value=null;try{a.value=await e.getConversation(g)}catch(C){v.value=C instanceof Error?C:new Error("Failed to load conversation")}finally{i.value=!1}}function p(){a.value=null}return(0,o.onMounted)(()=>{n&&f()}),{conversations:s,currentConversation:a,isLoading:i,error:v,selectConversation:m,startNewConversation:p,refreshConversations:f}}function P(t={}){const e=E({client:t.client,conversationId:t.conversationId}),n=N({client:t.client,autoLoad:t.autoLoad}),s=(0,o.computed)(()=>e.error.value||n.error.value);return{messages:e.messages,isLoading:e.isLoading,error:s,sendMessage:e.sendMessage,stop:e.stop,clearMessages:e.clearMessages,conversationId:e.conversationId,conversations:n.conversations,currentConversation:n.currentConversation,isConversationsLoading:n.isLoading,selectConversation:n.selectConversation,startNewConversation:n.startNewConversation,refreshConversations:n.refreshConversations}}function R(t,e){const n=d();(0,o.onMounted)(()=>{n.registerFunction(t,e.handler,{description:e.description,parameters:e.parameters,maxResultBytes:e.maxResultBytes})}),(0,o.onUnmounted)(()=>{n.unregisterFunction(t)})}function F(t,e){const n=d();(0,o.onMounted)(()=>{n.registerNavigationFunction(t,e)}),(0,o.onUnmounted)(()=>{n.unregisterNavigationFunction()})}function _(t,e){const n=d(),s=e?.functionName??"setPageState";(0,o.onMounted)(()=>{n.registerPageStateFunction(t,{...e,functionName:s})}),(0,o.onUnmounted)(()=>{n.unregisterPageStateFunction(s)})}function D(t,e){const n=d();(0,o.onMounted)(()=>{n.on(t,e)}),(0,o.onUnmounted)(()=>{n.off(t,e)})}function U(t){const e=(0,o.shallowRef)(t.get());return(0,o.onScopeDispose)(t.subscribe(n=>{e.value=n})),e}function b(){const t=d(),e=(0,o.shallowRef)(null),n=a=>{e.value=a,t.proactive?.shown(a)},s=({nudge:a})=>{e.value?.id===a.id&&(e.value=null)};return(0,o.onMounted)(()=>{t.on("nudge:ready",n),t.on("nudge:accepted",s),t.on("nudge:dismissed",s)}),(0,o.onUnmounted)(()=>{t.off("nudge:ready",n),t.off("nudge:accepted",s),t.off("nudge:dismissed",s)}),{nudge:e,accept:async()=>{const a=e.value;a&&(e.value=null,await t.proactive?.accept(a))},dismiss:()=>{const a=e.value;a&&(e.value=null,t.proactive?.dismiss(a))}}}exports.AGO_CLIENT_KEY=I;exports.AgoPlugin=L;exports.useAgo=d;exports.useAgoEvents=D;exports.useAgoFunction=R;exports.useAgoNavigation=F;exports.useAgoPageState=_;exports.useAgoStore=U;exports.useChat=P;exports.useConversation=N;exports.useMessages=E;exports.useProactiveNudge=b;

package/dist/vue.d.cts

@@ -65,6 +65,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;
     /**
@@ -75,6 +79,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.
@@ -86,7 +104,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
@@ -314,13 +378,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.
@@ -488,6 +577,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. */
@@ -681,6 +782,80 @@ export 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,
+ *   },
+ * });
+ * ```
+ */
+export 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}.
  */
@@ -692,6 +867,23 @@ export 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;
 }
 
 /**
@@ -1020,13 +1212,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;
 }
@@ -1358,6 +1558,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">;
 
@@ -1519,6 +1734,19 @@ export declare function useAgoNavigation(navigate: (path: string) => void, route
  *   },
  * ]);
  * ```
+ *
+ * Pass `opts.data` to also hand the agent what the page ends up displaying, as
+ * the result of its own `setPageState` call:
+ *
+ * ```ts
+ * useAgoPageState(controls, {
+ *   data: {
+ *     description: "The rows matching the current filters.",
+ *     get: () => rows.value,
+ *     isLoading: () => isFetching.value,
+ *   },
+ * });
+ * ```
  */
 export declare function useAgoPageState(controls: AgoStateControl[], opts?: AgoPageStateOptions): void;
 
@@ -1637,6 +1865,7 @@ export declare function useChat(options?: UseChatOptions): {
     isLoading: Ref<boolean, boolean>;
     error: ComputedRef<Error | null>;
     sendMessage: (content: string, files?: File[]) => Promise<AgoMessage | null>;
+    stop: () => Promise<void>;
     clearMessages: () => void;
     conversationId: Ref<string | undefined, string | undefined>;
     conversations: Ref<    {
@@ -2158,6 +2387,7 @@ export declare function useMessages(options?: UseMessagesOptions): {
     error: Ref<Error | null, Error | null>;
     conversationId: Ref<string | undefined, string | undefined>;
     sendMessage: (content: string, files?: File[]) => Promise<AgoMessage | null>;
+    stop: () => Promise<void>;
     clearMessages: () => void;
 };