@useago/sdk 1.4.4 → 1.5.2

package/dist/helpers.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("./functions-Djnq-JAo.cjs");exports.copyToClipboard=o.copyToClipboard;exports.getLocalStorage=o.getLocalStorage;exports.getUserLocation=o.getUserLocation;exports.highlightElement=o.highlightElement;exports.openUrl=o.openUrl;exports.scrollToElement=o.scrollToElement;exports.setLocalStorage=o.setLocalStorage;exports.setTheme=o.setTheme;exports.showConfirmDialog=o.showConfirmDialog;exports.showNotification=o.showNotification;exports.showToast=o.showToast;exports.submitForm=o.submitForm;exports.trackEvent=o.trackEvent;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("./functions-CPs7omgM.cjs");exports.copyToClipboard=o.copyToClipboard;exports.getLocalStorage=o.getLocalStorage;exports.getUserLocation=o.getUserLocation;exports.highlightElement=o.highlightElement;exports.openUrl=o.openUrl;exports.scrollToElement=o.scrollToElement;exports.setLocalStorage=o.setLocalStorage;exports.setTheme=o.setTheme;exports.showConfirmDialog=o.showConfirmDialog;exports.showNotification=o.showNotification;exports.showToast=o.showToast;exports.submitForm=o.submitForm;exports.trackEvent=o.trackEvent;

package/dist/helpers.d.cts

@@ -22,6 +22,11 @@ declare interface ClientFunctionDefinition {
      * `Infinity` disables the guard for this function.
      */
     maxResultBytes?: number;
+    /**
+     * Require explicit user approval before this function runs. See
+     * {@link AgoConfig.approvalPolicy} — pause mode only. ORs with the policy.
+     */
+    requiresApproval?: boolean;
 }
 
 /**

package/dist/helpers.d.ts

@@ -22,6 +22,11 @@ declare interface ClientFunctionDefinition {
      * `Infinity` disables the guard for this function.
      */
     maxResultBytes?: number;
+    /**
+     * Require explicit user approval before this function runs. See
+     * {@link AgoConfig.approvalPolicy} — pause mode only. ORs with the policy.
+     */
+    requiresApproval?: boolean;
 }
 
 /**

package/dist/helpers.js

@@ -1,4 +1,4 @@
-import { a, c as s, d as t, f as e, i as r, l as i, m as l, o as m, p as c, r as g, s as h, t as n, u as p } from "./functions-CApuQZ2b.js";
+import { a, c as s, d as t, f as e, i as r, l as i, m as l, o as m, p as c, r as g, s as h, t as n, u as p } from "./functions-tzyOZNp6.js";
 export {
   n as copyToClipboard,
   g as getLocalStorage,

package/dist/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("./AgoClient-CLmtYTJx.cjs"),f=require("./createFormCollector-DHT1ObOb.cjs"),h=require("./createConversationSession-CUkNp6mZ.cjs"),p=require("./createMockClient-BSr-UV8R.cjs");require("./testing.cjs");const g=require("./functions-Djnq-JAo.cjs");function w(e){return e}function S(e,o){return e.on("message:complete",o),()=>e.off("message:complete",o)}function E(e,o){return e.on("message:chunk",o),()=>e.off("message:chunk",o)}function y(e,o){return e.on("message:start",o),()=>e.off("message:start",o)}function F(e,o){return e.on("message:error",o),()=>e.off("message:error",o)}function b(e,o){return e.on("toolCall:received",o),()=>e.off("toolCall:received",o)}function v(e,o){return e.on("form:submitted",o),()=>e.off("form:submitted",o)}function M(e,o){return e.on("form:error",o),()=>e.off("form:error",o)}function q(e,o){return e.on("function:invoke",o),()=>e.off("function:invoke",o)}async function*k(e,o,l){const a=[];let n=null,i=!1;const m=s=>{a.push(s),n?.()},c=s=>m({type:"start",data:s}),t=s=>m({type:"chunk",data:s}),u=s=>{m({type:"complete",data:s}),i=!0,n?.()},d=s=>{m({type:"error",data:s}),i=!0,n?.()},C=s=>m({type:"toolCall",data:s});e.on("message:start",c),e.on("message:chunk",t),e.on("message:complete",u),e.on("message:error",d),e.on("toolCall:received",C),e.sendMessage(o,l).catch(()=>{i=!0,n?.()});try{for(;!i||a.length>0;)a.length>0?yield a.shift():(await new Promise(s=>{n=s}),n=null)}finally{e.off("message:start",c),e.off("message:chunk",t),e.off("message:complete",u),e.off("message:error",d),e.off("toolCall:received",C)}}function A(e){let o,l,a,n,i,m;if(typeof window<"u"&&window.AGO){const t=window.AGO;o=t.basepath,l=t.widgetId,a=t.agent||t.defaultAgent,n=t.permission,i=t.email,m=t.jwt}if(typeof document<"u"){const t=u=>document.querySelector(`meta[name="${u}"]`)?.getAttribute("content")||void 0;o=o||t("ago-base-url"),l=l||t("ago-widget-id"),a=a||t("ago-agent")||t("ago-agent-id"),n=n||t("ago-permission"),i=i||t("ago-user-email")}if(typeof document<"u"){const t=[document.body,...Array.from(document.querySelectorAll("script[data-ago-base-url]"))].filter(Boolean);for(const u of t)u&&(o=o||u.getAttribute("data-ago-base-url")||void 0,l=l||u.getAttribute("data-ago-widget-id")||void 0,a=a||u.getAttribute("data-ago-agent")||u.getAttribute("data-ago-agent-id")||void 0,n=n||u.getAttribute("data-ago-permission")||void 0,i=i||u.getAttribute("data-ago-user-email")||void 0)}o=e?.baseUrl||o,l=e?.widgetId||l,a=e?.agent||e?.defaultAgentId||a,n=e?.permission||n,i=e?.userEmail||i,m=e?.userJwt||m;const c=e?.debug;return o?{baseUrl:o,widgetId:l,agent:a,permission:n,userEmail:i,userJwt:m,debug:c}:null}function T(e){const o=A(e);if(!o)throw new r.AgoError('createAgo(): could not detect AGO configuration. Set window.AGO, add <meta name="ago-base-url">, or pass { baseUrl } explicitly.',"config_missing_base_url");return new r.AgoClient(o)}function I(e,o){return{...e,handler:o}}exports.AgoApiError=r.AgoApiError;exports.AgoClient=r.AgoClient;exports.AgoError=r.AgoError;exports.AgoFunctionError=r.AgoFunctionError;exports.AgoNetworkError=r.AgoNetworkError;exports.AgoStreamError=r.AgoStreamError;exports.ClientContextRegistry=r.ClientContextRegistry;exports.EventEmitter=r.EventEmitter;exports.FunctionRegistry=r.FunctionRegistry;exports.SSEHandler=r.SSEHandler;exports.autoDetectConfig=A;exports.canInlineImage=r.canInlineImage;exports.copyToClipboard=g.copyToClipboard;exports.createAgo=T;exports.createConversationSession=h.createConversationSession;exports.createFormCollector=f.createFormCollector;exports.createMessageStream=k;exports.createMockClient=p.createMockClient;exports.createStore=f.createStore;exports.defineFunction=w;exports.deriveFormStatus=f.deriveFormStatus;exports.formatFileSize=r.formatFileSize;exports.getLocalStorage=g.getLocalStorage;exports.getUserLocation=g.getUserLocation;exports.highlightElement=g.highlightElement;exports.isStreamNetworkError=r.isStreamNetworkError;exports.loadFormCollector=f.loadFormCollector;exports.logger=r.logger;exports.onFormError=M;exports.onFormSubmitted=v;exports.onFunctionInvoke=q;exports.onMessage=S;exports.onMessageChunk=E;exports.onMessageError=F;exports.onMessageStart=y;exports.onToolCall=b;exports.openUrl=g.openUrl;exports.safeAttachmentUrl=r.safeAttachmentUrl;exports.scrollToElement=g.scrollToElement;exports.setLocalStorage=g.setLocalStorage;exports.setTheme=g.setTheme;exports.showConfirmDialog=g.showConfirmDialog;exports.showNotification=g.showNotification;exports.showToast=g.showToast;exports.submitForm=g.submitForm;exports.trackEvent=g.trackEvent;exports.validateConfig=r.validateConfig;exports.withHandler=I;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("./AgoClient-5VGybmvz.cjs"),h=require("./autoContinue-CP9pJR-V.cjs"),f=require("./createFormCollector-1GKKwQV_.cjs"),p=require("./createConversationSession-0WTqcCLK.cjs"),w=require("./createMockClient-C-wrjb2C.cjs");require("./testing.cjs");const g=require("./functions-CPs7omgM.cjs");function S(e){return e}function E(e,o){return e.on("message:complete",o),()=>e.off("message:complete",o)}function y(e,o){return e.on("message:chunk",o),()=>e.off("message:chunk",o)}function F(e,o){return e.on("message:start",o),()=>e.off("message:start",o)}function v(e,o){return e.on("message:error",o),()=>e.off("message:error",o)}function b(e,o){return e.on("toolCall:received",o),()=>e.off("toolCall:received",o)}function q(e,o){return e.on("form:submitted",o),()=>e.off("form:submitted",o)}function M(e,o){return e.on("form:error",o),()=>e.off("form:error",o)}function k(e,o){return e.on("function:invoke",o),()=>e.off("function:invoke",o)}async function*T(e,o,l){const a=[];let n=null,i=!1;const c=s=>{a.push(s),n?.()},m=s=>c({type:"start",data:s}),t=s=>c({type:"chunk",data:s}),u=s=>{c({type:"complete",data:s}),i=!0,n?.()},d=s=>{c({type:"error",data:s}),i=!0,n?.()},A=s=>c({type:"toolCall",data:s});e.on("message:start",m),e.on("message:chunk",t),e.on("message:complete",u),e.on("message:error",d),e.on("toolCall:received",A),e.sendMessage(o,l).catch(()=>{i=!0,n?.()});try{for(;!i||a.length>0;)a.length>0?yield a.shift():(await new Promise(s=>{n=s}),n=null)}finally{e.off("message:start",m),e.off("message:chunk",t),e.off("message:complete",u),e.off("message:error",d),e.off("toolCall:received",A)}}function C(e){let o,l,a,n,i,c;if(typeof window<"u"&&window.AGO){const t=window.AGO;o=t.basepath,l=t.widgetId,a=t.agent||t.defaultAgent,n=t.permission,i=t.email,c=t.jwt}if(typeof document<"u"){const t=u=>document.querySelector(`meta[name="${u}"]`)?.getAttribute("content")||void 0;o=o||t("ago-base-url"),l=l||t("ago-widget-id"),a=a||t("ago-agent")||t("ago-agent-id"),n=n||t("ago-permission"),i=i||t("ago-user-email")}if(typeof document<"u"){const t=[document.body,...Array.from(document.querySelectorAll("script[data-ago-base-url]"))].filter(Boolean);for(const u of t)u&&(o=o||u.getAttribute("data-ago-base-url")||void 0,l=l||u.getAttribute("data-ago-widget-id")||void 0,a=a||u.getAttribute("data-ago-agent")||u.getAttribute("data-ago-agent-id")||void 0,n=n||u.getAttribute("data-ago-permission")||void 0,i=i||u.getAttribute("data-ago-user-email")||void 0)}o=e?.baseUrl||o,l=e?.widgetId||l,a=e?.agent||e?.defaultAgentId||a,n=e?.permission||n,i=e?.userEmail||i,c=e?.userJwt||c;const m=e?.debug;return o?{baseUrl:o,widgetId:l,agent:a,permission:n,userEmail:i,userJwt:c,debug:m}:null}function I(e){const o=C(e);if(!o)throw new r.AgoError('createAgo(): could not detect AGO configuration. Set window.AGO, add <meta name="ago-base-url">, or pass { baseUrl } explicitly.',"config_missing_base_url");return new r.AgoClient(o)}function U(e,o){return{...e,handler:o}}exports.AgoApiError=r.AgoApiError;exports.AgoClient=r.AgoClient;exports.AgoError=r.AgoError;exports.AgoFunctionError=r.AgoFunctionError;exports.AgoNetworkError=r.AgoNetworkError;exports.AgoStreamError=r.AgoStreamError;exports.ClientContextRegistry=r.ClientContextRegistry;exports.EventEmitter=r.EventEmitter;exports.FunctionRegistry=r.FunctionRegistry;exports.SSEHandler=r.SSEHandler;exports.attachAutoContinueAfterNavigation=h.attachAutoContinueAfterNavigation;exports.autoDetectConfig=C;exports.canInlineImage=r.canInlineImage;exports.copyToClipboard=g.copyToClipboard;exports.createAgo=I;exports.createConversationSession=p.createConversationSession;exports.createFormCollector=f.createFormCollector;exports.createMessageStream=T;exports.createMockClient=w.createMockClient;exports.createStore=f.createStore;exports.defineFunction=S;exports.deriveFormStatus=f.deriveFormStatus;exports.formatFileSize=r.formatFileSize;exports.getLocalStorage=g.getLocalStorage;exports.getUserLocation=g.getUserLocation;exports.highlightElement=g.highlightElement;exports.isStreamNetworkError=r.isStreamNetworkError;exports.loadFormCollector=f.loadFormCollector;exports.logger=r.logger;exports.onFormError=M;exports.onFormSubmitted=q;exports.onFunctionInvoke=k;exports.onMessage=E;exports.onMessageChunk=y;exports.onMessageError=v;exports.onMessageStart=F;exports.onToolCall=b;exports.openUrl=g.openUrl;exports.safeAttachmentUrl=r.safeAttachmentUrl;exports.scrollToElement=g.scrollToElement;exports.setLocalStorage=g.setLocalStorage;exports.setTheme=g.setTheme;exports.showConfirmDialog=g.showConfirmDialog;exports.showNotification=g.showNotification;exports.showToast=g.showToast;exports.submitForm=g.submitForm;exports.trackEvent=g.trackEvent;exports.validateConfig=r.validateConfig;exports.withHandler=U;

package/dist/index.d.cts

@@ -39,6 +39,23 @@ export declare interface AgoAttachment {
     isSafeImage: boolean;
 }
 
+export declare interface AgoAutoContinueOptions {
+    /** Function names whose invocation counts as "navigated". Default `["navigateToPage"]`. */
+    navigationFunctions?: string[];
+    /** Registered function that signals the destination has editable state. Default `"setPageState"`. */
+    pageStateFunctionName?: string;
+    /** The hidden continuation prompt. Override for i18n / tone. */
+    continuationPrompt?: string;
+    /** Max continuations per user gesture (guards navigate→continue→navigate loops). Default `1`. */
+    maxDepth?: number;
+    /** How long to wait for the destination page to register page-state before giving up. Default `4000`ms. */
+    readinessTimeoutMs?: number;
+    /** Extra settle delay after page-state appears, to let sibling state mount. Default `150`ms. */
+    settleMs?: number;
+    /** Opt-out escape hatch. Default `true`. */
+    enabled?: boolean;
+}
+
 /**
  * Main SDK client for AGO Chat integration
  */
@@ -52,6 +69,12 @@ export declare class AgoClient {
     private warnedEmptyConversations;
     /** Paused turns awaiting auto-resume, keyed by assistant message id. */
     private pendingResumes;
+    /**
+     * Client function invocations held pending user approval, keyed by
+     * invocationId (the tool-call id). Populated when {@link requiresApproval}
+     * matches; drained by {@link approveFunction} / {@link rejectFunction}.
+     */
+    private pendingApprovals;
     /** App-provided gate deciding WHEN a paused turn resumes (see {@link registerResumeGate}). */
     private resumeGate;
     constructor(config: AgoConfig);
@@ -102,6 +125,24 @@ export declare class AgoClient {
      */
     private maybeFlagEmptyReply;
     private handleClientFunctionInvocation;
+    /**
+     * Whether a client function invocation must wait for explicit user approval.
+     * True when the {@link AgoConfig.approvalPolicy} returns true OR the function
+     * was registered with `requiresApproval: true` — the two OR together.
+     */
+    private requiresApproval;
+    /**
+     * Approve a client function call held by the approval gate: run it, submit its
+     * result, and let the paused turn resume. No-op if the invocation is unknown
+     * (already handled, or never gated).
+     */
+    approveFunction(invocationId: string): Promise<void>;
+    /**
+     * Reject a client function call held by the approval gate: submit a rejection
+     * result so the agent sees the user declined, and let the paused turn resume
+     * (the agent decides what to do next). No-op if the invocation is unknown.
+     */
+    rejectFunction(invocationId: string): Promise<void>;
     /**
      * Get list of conversations
      */
@@ -131,8 +172,10 @@ export declare class AgoClient {
      *
      * Opt-in on purpose — re-running functions on reload can be surprising (e.g. a
      * navigation function would navigate again), so the app decides. Returns the
-     * resumed turn's final message, or `null` when there was nothing to resume or
-     * some waiting function is not registered on this page.
+     * resumed turn's final message, or `null` when there was nothing to resume,
+     * some waiting function is not registered on this page, or a waiting call is
+     * gated by the approval policy (it is held for `approveFunction` /
+     * `rejectFunction` and the turn stays paused, exactly as on the live stream).
      */
     resumePendingClientFunctions(conversation: Conversation): Promise<AgoMessage | null>;
     /**
@@ -427,6 +470,15 @@ export declare interface AgoClientEvents {
     "toolCall:received": ToolCallData;
     "toolCall:form": ToolCallData;
     "function:invoke": ClientFunctionInvocation;
+    /**
+     * A client function call is held pending the user's approval (pause mode +
+     * an {@link AgoConfig.approvalPolicy}/`requiresApproval` match). The turn stays
+     * at `WAITING_CLIENT`; call `approveFunction(invocationId)` to run it and
+     * resume, or `rejectFunction(invocationId)` to decline. Fires after
+     * `function:invoke` (which still fires for every call) and instead of the
+     * call running immediately.
+     */
+    "function:awaiting-approval": ClientFunctionInvocation;
     "function:result": {
         invocationId: string;
         result: unknown;
@@ -487,14 +539,28 @@ export declare interface AgoConfig {
     warnOnEmptyReply?: boolean;
     /**
      * How the agent loop treats client function calls (requires backend support):
-     * - `"placeholder"` (default): the turn continues immediately on a placeholder
-     *   result; the real result is only visible to the agent on later turns.
-     * - `"pause"`: the turn stops on client function call(s) with status
+     * - `"pause"` (default): the turn stops on client function call(s) with status
      *   `WAITING_CLIENT`; once every result is submitted, the SDK resumes the SAME
      *   turn via `POST /messages/{id}/continue`, so the agent sees the real results.
+     * - `"placeholder"` (legacy): the turn continues immediately on a placeholder
+     *   result; the real result is only visible to the agent on later turns.
      * Older backends ignore the flag, so `"pause"` degrades to legacy behavior.
      */
     clientFunctionsMode?: ClientFunctionsMode;
+    /**
+     * Gate client function calls behind explicit user approval. Return `true` for
+     * an invocation the user must approve/reject before it runs; return `false`
+     * (or omit the policy) to let it run immediately as before.
+     *
+     * Only effective in pause mode (`clientFunctionsMode: "pause"`) — a gated call
+     * holds at `WAITING_CLIENT`, the SDK emits `function:awaiting-approval`, and it
+     * runs (and the turn resumes) only after `approveFunction(invocationId)`; a
+     * `rejectFunction(invocationId)` submits a rejection so the agent sees the
+     * decline. In placeholder mode there is no pause to hold, so the policy is a
+     * no-op and the call runs normally. A per-function `requiresApproval: true`
+     * also gates a call; the policy and the flag OR together.
+     */
+    approvalPolicy?: (invocation: ClientFunctionInvocation) => boolean;
     /**
      * Max serialized size (bytes) of a client function result before the SDK
      * replaces it with a flagged, truncated preview. Everything a handler
@@ -571,6 +637,11 @@ export declare class AgoNetworkError extends AgoError {
 export declare interface AgoPageStateOptions {
     /** Name of the synthesized client function. Defaults to "setPageState". */
     functionName?: string;
+    /**
+     * Require explicit user approval before this state change runs. See
+     * {@link AgoConfig.approvalPolicy} — pause mode only. Defaults to `false`.
+     */
+    requiresApproval?: boolean;
 }
 
 /**
@@ -659,6 +730,38 @@ declare interface ApiErrorResponse {
     };
 }
 
+/**
+ * Auto-continue the agent after it navigates, so a "go to page B and change X"
+ * request completes in one user gesture. Attach once per client; returns a
+ * detach function that removes every listener.
+ *
+ * Two mechanisms, picked by the turn's client-functions mode:
+ *
+ * - **Pause mode** (`clientFunctionsMode: "pause"`, the default): the backend pauses the turn
+ *   on the navigation call (`message:waiting-client`) and the SDK resumes it once
+ *   the result is submitted. This helper only registers a *resume gate* that delays
+ *   the resume until the destination page's page-state registered (plus a settle
+ *   delay), so the continued turn ships the new page's `setPageState` and current
+ *   state. Same turn, no extra prompt, backend budget as the guardrail —
+ *   `continuationPrompt` and `maxDepth` are unused here.
+ *
+ * - **Placeholder mode** (legacy, `clientFunctionsMode: "placeholder"`): when the agent calls the navigation
+ *   function and that turn ends, this waits for the destination page's state to
+ *   register, then sends a hidden continuation message; the agent applies the
+ *   state in a second turn (requires backend support for the `hidden` flag).
+ *
+ * ```ts
+ * const detach = attachAutoContinueAfterNavigation(client);
+ * // later, on teardown:
+ * detach();
+ * ```
+ *
+ * Options can be a plain object, or a getter for live options: the getter is
+ * re-read on every event, so changing what it returns never re-subscribes the
+ * listeners (this is how the React hook keeps options reactive).
+ */
+export declare function attachAutoContinueAfterNavigation(client: AgoClient, options?: AgoAutoContinueOptions | (() => AgoAutoContinueOptions | undefined)): () => void;
+
 /**
  * Auto-detect AGO configuration from the DOM environment.
  *
@@ -747,6 +850,11 @@ export declare interface ClientFunctionDefinition {
      * `Infinity` disables the guard for this function.
      */
     maxResultBytes?: number;
+    /**
+     * Require explicit user approval before this function runs. See
+     * {@link AgoConfig.approvalPolicy} — pause mode only. ORs with the policy.
+     */
+    requiresApproval?: boolean;
 }
 
 /**
@@ -773,6 +881,11 @@ export declare type ClientFunctionRegisterOptions = Omit<ClientFunctionSchema, "
      * disables the guard for this function.
      */
     maxResultBytes?: number;
+    /**
+     * Require explicit user approval before this function runs. See
+     * {@link AgoConfig.approvalPolicy} — pause mode only. ORs with the policy.
+     */
+    requiresApproval?: boolean;
 };
 
 /**
@@ -813,6 +926,19 @@ export declare interface ContextEntry {
     description?: string;
     /** Arbitrary structured data the AI should know about */
     data?: Record<string, unknown>;
+    /**
+     * Marks the entry as constant for the whole conversation. The backend then
+     * pins it right after the system prompt, where LLM providers cache it across
+     * turns, instead of re-processing it next to every new user message.
+     *
+     * Only set this when the entry's content is byte-identical on every message
+     * of a conversation (a schema, a capability list, static instructions). A
+     * stable entry that changes between messages invalidates the provider's
+     * cache for the entire conversation history, which costs more than leaving
+     * the flag off. Default: `false` (re-sent near the newest user message).
+     * Backends that don't know the flag ignore it.
+     */
+    stable?: boolean;
 }
 
 /**
@@ -1111,10 +1237,22 @@ export declare interface FormCollector<V = Record<string, unknown>> {
     store: Store<FormCollectorState<V>>;
     /** Client functions to register: `[update]` or `[update, submit]`. */
     functions: ClientFunctionDefinition[];
-    /** Dynamic-context key under which the form state is exposed. */
+    /** Dynamic-context key under which the live form state is exposed. */
     contextKey: string;
-    /** Dynamic-context provider — re-read on every message. */
+    /**
+     * Dynamic-context provider for the live form state (phase, values, missing)
+     * — re-read on every message. The schema itself rides in the companion
+     * {@link definitionContextProvider} entry.
+     */
     contextProvider: () => ContextEntry;
+    /** Context key of the stable form definition (`<contextKey>:definition`). */
+    definitionContextKey: string;
+    /**
+     * Provider for the form's definition (description + schema): identical on
+     * every message and marked `stable: true`, so the backend can pin it in the
+     * cacheable part of the prompt. Registered/removed by `install` alongside `contextProvider`.
+     */
+    definitionContextProvider: () => ContextEntry;
     /** Register the functions + dynamic context on a client. Returns an uninstall fn. */
     install: (client: AgoClient) => () => void;
     /**
@@ -1518,6 +1656,8 @@ export declare interface RegisteredFunction {
     handler: ClientFunctionHandler;
     /** Per-function result-size ceiling; falls back to the registry default. */
     maxResultBytes?: number;
+    /** Require explicit user approval before running (pause mode only). */
+    requiresApproval?: boolean;
 }
 
 /**

package/dist/index.d.ts

@@ -39,6 +39,23 @@ export declare interface AgoAttachment {
     isSafeImage: boolean;
 }
 
+export declare interface AgoAutoContinueOptions {
+    /** Function names whose invocation counts as "navigated". Default `["navigateToPage"]`. */
+    navigationFunctions?: string[];
+    /** Registered function that signals the destination has editable state. Default `"setPageState"`. */
+    pageStateFunctionName?: string;
+    /** The hidden continuation prompt. Override for i18n / tone. */
+    continuationPrompt?: string;
+    /** Max continuations per user gesture (guards navigate→continue→navigate loops). Default `1`. */
+    maxDepth?: number;
+    /** How long to wait for the destination page to register page-state before giving up. Default `4000`ms. */
+    readinessTimeoutMs?: number;
+    /** Extra settle delay after page-state appears, to let sibling state mount. Default `150`ms. */
+    settleMs?: number;
+    /** Opt-out escape hatch. Default `true`. */
+    enabled?: boolean;
+}
+
 /**
  * Main SDK client for AGO Chat integration
  */
@@ -52,6 +69,12 @@ export declare class AgoClient {
     private warnedEmptyConversations;
     /** Paused turns awaiting auto-resume, keyed by assistant message id. */
     private pendingResumes;
+    /**
+     * Client function invocations held pending user approval, keyed by
+     * invocationId (the tool-call id). Populated when {@link requiresApproval}
+     * matches; drained by {@link approveFunction} / {@link rejectFunction}.
+     */
+    private pendingApprovals;
     /** App-provided gate deciding WHEN a paused turn resumes (see {@link registerResumeGate}). */
     private resumeGate;
     constructor(config: AgoConfig);
@@ -102,6 +125,24 @@ export declare class AgoClient {
      */
     private maybeFlagEmptyReply;
     private handleClientFunctionInvocation;
+    /**
+     * Whether a client function invocation must wait for explicit user approval.
+     * True when the {@link AgoConfig.approvalPolicy} returns true OR the function
+     * was registered with `requiresApproval: true` — the two OR together.
+     */
+    private requiresApproval;
+    /**
+     * Approve a client function call held by the approval gate: run it, submit its
+     * result, and let the paused turn resume. No-op if the invocation is unknown
+     * (already handled, or never gated).
+     */
+    approveFunction(invocationId: string): Promise<void>;
+    /**
+     * Reject a client function call held by the approval gate: submit a rejection
+     * result so the agent sees the user declined, and let the paused turn resume
+     * (the agent decides what to do next). No-op if the invocation is unknown.
+     */
+    rejectFunction(invocationId: string): Promise<void>;
     /**
      * Get list of conversations
      */
@@ -131,8 +172,10 @@ export declare class AgoClient {
      *
      * Opt-in on purpose — re-running functions on reload can be surprising (e.g. a
      * navigation function would navigate again), so the app decides. Returns the
-     * resumed turn's final message, or `null` when there was nothing to resume or
-     * some waiting function is not registered on this page.
+     * resumed turn's final message, or `null` when there was nothing to resume,
+     * some waiting function is not registered on this page, or a waiting call is
+     * gated by the approval policy (it is held for `approveFunction` /
+     * `rejectFunction` and the turn stays paused, exactly as on the live stream).
      */
     resumePendingClientFunctions(conversation: Conversation): Promise<AgoMessage | null>;
     /**
@@ -427,6 +470,15 @@ export declare interface AgoClientEvents {
     "toolCall:received": ToolCallData;
     "toolCall:form": ToolCallData;
     "function:invoke": ClientFunctionInvocation;
+    /**
+     * A client function call is held pending the user's approval (pause mode +
+     * an {@link AgoConfig.approvalPolicy}/`requiresApproval` match). The turn stays
+     * at `WAITING_CLIENT`; call `approveFunction(invocationId)` to run it and
+     * resume, or `rejectFunction(invocationId)` to decline. Fires after
+     * `function:invoke` (which still fires for every call) and instead of the
+     * call running immediately.
+     */
+    "function:awaiting-approval": ClientFunctionInvocation;
     "function:result": {
         invocationId: string;
         result: unknown;
@@ -487,14 +539,28 @@ export declare interface AgoConfig {
     warnOnEmptyReply?: boolean;
     /**
      * How the agent loop treats client function calls (requires backend support):
-     * - `"placeholder"` (default): the turn continues immediately on a placeholder
-     *   result; the real result is only visible to the agent on later turns.
-     * - `"pause"`: the turn stops on client function call(s) with status
+     * - `"pause"` (default): the turn stops on client function call(s) with status
      *   `WAITING_CLIENT`; once every result is submitted, the SDK resumes the SAME
      *   turn via `POST /messages/{id}/continue`, so the agent sees the real results.
+     * - `"placeholder"` (legacy): the turn continues immediately on a placeholder
+     *   result; the real result is only visible to the agent on later turns.
      * Older backends ignore the flag, so `"pause"` degrades to legacy behavior.
      */
     clientFunctionsMode?: ClientFunctionsMode;
+    /**
+     * Gate client function calls behind explicit user approval. Return `true` for
+     * an invocation the user must approve/reject before it runs; return `false`
+     * (or omit the policy) to let it run immediately as before.
+     *
+     * Only effective in pause mode (`clientFunctionsMode: "pause"`) — a gated call
+     * holds at `WAITING_CLIENT`, the SDK emits `function:awaiting-approval`, and it
+     * runs (and the turn resumes) only after `approveFunction(invocationId)`; a
+     * `rejectFunction(invocationId)` submits a rejection so the agent sees the
+     * decline. In placeholder mode there is no pause to hold, so the policy is a
+     * no-op and the call runs normally. A per-function `requiresApproval: true`
+     * also gates a call; the policy and the flag OR together.
+     */
+    approvalPolicy?: (invocation: ClientFunctionInvocation) => boolean;
     /**
      * Max serialized size (bytes) of a client function result before the SDK
      * replaces it with a flagged, truncated preview. Everything a handler
@@ -571,6 +637,11 @@ export declare class AgoNetworkError extends AgoError {
 export declare interface AgoPageStateOptions {
     /** Name of the synthesized client function. Defaults to "setPageState". */
     functionName?: string;
+    /**
+     * Require explicit user approval before this state change runs. See
+     * {@link AgoConfig.approvalPolicy} — pause mode only. Defaults to `false`.
+     */
+    requiresApproval?: boolean;
 }
 
 /**
@@ -659,6 +730,38 @@ declare interface ApiErrorResponse {
     };
 }
 
+/**
+ * Auto-continue the agent after it navigates, so a "go to page B and change X"
+ * request completes in one user gesture. Attach once per client; returns a
+ * detach function that removes every listener.
+ *
+ * Two mechanisms, picked by the turn's client-functions mode:
+ *
+ * - **Pause mode** (`clientFunctionsMode: "pause"`, the default): the backend pauses the turn
+ *   on the navigation call (`message:waiting-client`) and the SDK resumes it once
+ *   the result is submitted. This helper only registers a *resume gate* that delays
+ *   the resume until the destination page's page-state registered (plus a settle
+ *   delay), so the continued turn ships the new page's `setPageState` and current
+ *   state. Same turn, no extra prompt, backend budget as the guardrail —
+ *   `continuationPrompt` and `maxDepth` are unused here.
+ *
+ * - **Placeholder mode** (legacy, `clientFunctionsMode: "placeholder"`): when the agent calls the navigation
+ *   function and that turn ends, this waits for the destination page's state to
+ *   register, then sends a hidden continuation message; the agent applies the
+ *   state in a second turn (requires backend support for the `hidden` flag).
+ *
+ * ```ts
+ * const detach = attachAutoContinueAfterNavigation(client);
+ * // later, on teardown:
+ * detach();
+ * ```
+ *
+ * Options can be a plain object, or a getter for live options: the getter is
+ * re-read on every event, so changing what it returns never re-subscribes the
+ * listeners (this is how the React hook keeps options reactive).
+ */
+export declare function attachAutoContinueAfterNavigation(client: AgoClient, options?: AgoAutoContinueOptions | (() => AgoAutoContinueOptions | undefined)): () => void;
+
 /**
  * Auto-detect AGO configuration from the DOM environment.
  *
@@ -747,6 +850,11 @@ export declare interface ClientFunctionDefinition {
      * `Infinity` disables the guard for this function.
      */
     maxResultBytes?: number;
+    /**
+     * Require explicit user approval before this function runs. See
+     * {@link AgoConfig.approvalPolicy} — pause mode only. ORs with the policy.
+     */
+    requiresApproval?: boolean;
 }
 
 /**
@@ -773,6 +881,11 @@ export declare type ClientFunctionRegisterOptions = Omit<ClientFunctionSchema, "
      * disables the guard for this function.
      */
     maxResultBytes?: number;
+    /**
+     * Require explicit user approval before this function runs. See
+     * {@link AgoConfig.approvalPolicy} — pause mode only. ORs with the policy.
+     */
+    requiresApproval?: boolean;
 };
 
 /**
@@ -813,6 +926,19 @@ export declare interface ContextEntry {
     description?: string;
     /** Arbitrary structured data the AI should know about */
     data?: Record<string, unknown>;
+    /**
+     * Marks the entry as constant for the whole conversation. The backend then
+     * pins it right after the system prompt, where LLM providers cache it across
+     * turns, instead of re-processing it next to every new user message.
+     *
+     * Only set this when the entry's content is byte-identical on every message
+     * of a conversation (a schema, a capability list, static instructions). A
+     * stable entry that changes between messages invalidates the provider's
+     * cache for the entire conversation history, which costs more than leaving
+     * the flag off. Default: `false` (re-sent near the newest user message).
+     * Backends that don't know the flag ignore it.
+     */
+    stable?: boolean;
 }
 
 /**
@@ -1111,10 +1237,22 @@ export declare interface FormCollector<V = Record<string, unknown>> {
     store: Store<FormCollectorState<V>>;
     /** Client functions to register: `[update]` or `[update, submit]`. */
     functions: ClientFunctionDefinition[];
-    /** Dynamic-context key under which the form state is exposed. */
+    /** Dynamic-context key under which the live form state is exposed. */
     contextKey: string;
-    /** Dynamic-context provider — re-read on every message. */
+    /**
+     * Dynamic-context provider for the live form state (phase, values, missing)
+     * — re-read on every message. The schema itself rides in the companion
+     * {@link definitionContextProvider} entry.
+     */
     contextProvider: () => ContextEntry;
+    /** Context key of the stable form definition (`<contextKey>:definition`). */
+    definitionContextKey: string;
+    /**
+     * Provider for the form's definition (description + schema): identical on
+     * every message and marked `stable: true`, so the backend can pin it in the
+     * cacheable part of the prompt. Registered/removed by `install` alongside `contextProvider`.
+     */
+    definitionContextProvider: () => ContextEntry;
     /** Register the functions + dynamic context on a client. Returns an uninstall fn. */
     install: (client: AgoClient) => () => void;
     /**
@@ -1518,6 +1656,8 @@ export declare interface RegisteredFunction {
     handler: ClientFunctionHandler;
     /** Per-function result-size ceiling; falls back to the registry default. */
     maxResultBytes?: number;
+    /** Require explicit user approval before running (pause mode only). */
+    requiresApproval?: boolean;
 }
 
 /**