@useago/sdk 1.4.4 → 1.5.2

package/dist/testing.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./createMockClient-BSr-UV8R.cjs");exports.createMockClient=e.createMockClient;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./createMockClient-C-wrjb2C.cjs");exports.createMockClient=e.createMockClient;

package/dist/testing.d.cts

@@ -41,6 +41,12 @@ 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);
@@ -91,6 +97,24 @@ 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
      */
@@ -120,8 +144,10 @@ 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>;
     /**
@@ -416,6 +442,15 @@ 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;
@@ -476,14 +511,28 @@ 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
@@ -528,6 +577,11 @@ declare interface AgoMessage {
 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;
 }
 
 /**
@@ -589,6 +643,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;
 }
 
 /**
@@ -615,6 +674,11 @@ declare type ClientFunctionRegisterOptions = Omit<ClientFunctionSchema, "name">
      * 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;
 };
 
 /**
@@ -655,6 +719,19 @@ 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;
 }
 
 /**

package/dist/testing.d.ts

@@ -41,6 +41,12 @@ 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);
@@ -91,6 +97,24 @@ 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
      */
@@ -120,8 +144,10 @@ 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>;
     /**
@@ -416,6 +442,15 @@ 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;
@@ -476,14 +511,28 @@ 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
@@ -528,6 +577,11 @@ declare interface AgoMessage {
 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;
 }
 
 /**
@@ -589,6 +643,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;
 }
 
 /**
@@ -615,6 +674,11 @@ declare type ClientFunctionRegisterOptions = Omit<ClientFunctionSchema, "name">
      * 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;
 };
 
 /**
@@ -655,6 +719,19 @@ 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;
 }
 
 /**

package/dist/testing.js

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

package/dist/vue.cjs

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

package/dist/vue.d.cts

@@ -49,6 +49,12 @@ 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);
@@ -99,6 +105,24 @@ 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
      */
@@ -128,8 +152,10 @@ 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>;
     /**
@@ -424,6 +450,15 @@ 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;
@@ -484,14 +519,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
@@ -536,6 +585,11 @@ export declare interface AgoMessage {
 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;
 }
 
 /**
@@ -618,6 +672,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;
 }
 
 /**
@@ -644,6 +703,11 @@ declare type ClientFunctionRegisterOptions = Omit<ClientFunctionSchema, "name">
      * 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;
 };
 
 /**
@@ -684,6 +748,19 @@ 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;
 }
 
 /**

package/dist/vue.d.ts

@@ -49,6 +49,12 @@ 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);
@@ -99,6 +105,24 @@ 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
      */
@@ -128,8 +152,10 @@ 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>;
     /**
@@ -424,6 +450,15 @@ 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;
@@ -484,14 +519,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
@@ -536,6 +585,11 @@ export declare interface AgoMessage {
 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;
 }
 
 /**
@@ -618,6 +672,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;
 }
 
 /**
@@ -644,6 +703,11 @@ declare type ClientFunctionRegisterOptions = Omit<ClientFunctionSchema, "name">
      * 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;
 };
 
 /**
@@ -684,6 +748,19 @@ 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;
 }
 
 /**

package/dist/vue.js

@@ -1,4 +1,4 @@
-import { t as A } from "./AgoClient-Ozz2b1dQ.js";
+import { t as A } from "./AgoClient-DXrH2AMi.js";
 import { computed as L, inject as M, onMounted as f, onScopeDispose as F, onUnmounted as h, ref as c, shallowRef as S } from "vue";
 var N = /* @__PURE__ */ Symbol("ago-client"), b = { install(t, n) {
   const e = new A(n);