@useago/sdk 1.4.4 → 1.5.2

package/dist/{createFormCollector-F3YJfsbg.js → createFormCollector-DYh90kiG.js}

@@ -1,72 +1,72 @@
-import { f as $ } from "./AgoClient-Ozz2b1dQ.js";
-function A(s, e) {
+import { f as w } from "./AgoClient-DXrH2AMi.js";
+function J(n, e) {
   const a = e ? e.storage ?? (typeof localStorage < "u" ? localStorage : void 0) : void 0;
-  let n = s;
+  let s = n;
   if (e && a) try {
     const m = a.getItem(e.key);
-    m != null && (n = JSON.parse(m));
+    m != null && (s = JSON.parse(m));
   } catch {
   }
-  const o = /* @__PURE__ */ new Set(), c = () => o.forEach((m) => m(n));
+  const o = /* @__PURE__ */ new Set(), c = () => o.forEach((m) => m(s));
   function b() {
     if (e && a) try {
-      a.setItem(e.key, JSON.stringify(n));
+      a.setItem(e.key, JSON.stringify(s));
     } catch {
     }
   }
   return {
-    get: () => n,
+    get: () => s,
     set: (m) => {
-      n = m, b(), c();
+      s = m, b(), c();
     },
     subscribe: (m) => (o.add(m), () => {
       o.delete(m);
     })
   };
 }
-var P = /^[a-zA-Z0-9_-]{1,40}$/, W = (s) => s == null || s === "";
-function v(s, e) {
-  if ("anyOf" in s) return s.anyOf.some((c) => v(c, e));
-  if ("allOf" in s) return s.allOf.every((c) => v(c, e));
-  const a = e[s.property];
-  if (W(a)) return !1;
-  if (Array.isArray(s.value)) return s.value.some((c) => String(a) === String(c));
-  if (!s.op) return String(a) === String(s.value);
-  const n = Number(a), o = Number(s.value);
-  if (Number.isNaN(n) || Number.isNaN(o)) return !1;
-  switch (s.op) {
+var j = /^[a-zA-Z0-9_-]{1,40}$/, I = (n) => n == null || n === "";
+function N(n, e) {
+  if ("anyOf" in n) return n.anyOf.some((c) => N(c, e));
+  if ("allOf" in n) return n.allOf.every((c) => N(c, e));
+  const a = e[n.property];
+  if (I(a)) return !1;
+  if (Array.isArray(n.value)) return n.value.some((c) => String(a) === String(c));
+  if (!n.op) return String(a) === String(n.value);
+  const s = Number(a), o = Number(n.value);
+  if (Number.isNaN(s) || Number.isNaN(o)) return !1;
+  switch (n.op) {
     case ">=":
-      return n >= o;
+      return s >= o;
     case "<=":
-      return n <= o;
+      return s <= o;
     case ">":
-      return n > o;
+      return s > o;
     case "<":
-      return n < o;
+      return s < o;
     default:
-      return $.warn(`Unknown requiredWhen op "${s.op}"; treating as not required.`), !1;
+      return w.warn(`Unknown requiredWhen op "${n.op}"; treating as not required.`), !1;
   }
 }
-function y(s, e) {
-  const a = s.properties ?? {}, n = /* @__PURE__ */ new Set();
-  for (const c of s.required ?? []) {
+function p(n, e) {
+  const a = n.properties ?? {}, s = /* @__PURE__ */ new Set();
+  for (const c of n.required ?? []) {
     const b = a[c]?.requiredWhen;
-    (!b || v(b, e)) && n.add(c);
+    (!b || N(b, e)) && s.add(c);
   }
-  for (const [c, b] of Object.entries(a)) b.requiredWhen && v(b.requiredWhen, e) && n.add(c);
-  const o = [...n].filter((c) => W(e[c]));
+  for (const [c, b] of Object.entries(a)) b.requiredWhen && N(b.requiredWhen, e) && s.add(c);
+  const o = [...s].filter((c) => I(e[c]));
   return {
     missing: o,
     complete: o.length === 0
   };
 }
-function J(s) {
+function R(n) {
   const e = {};
-  for (const [a, n] of Object.entries(s.properties ?? {})) e[a] = {
-    type: n.type,
-    ...n.description != null && { description: n.description },
-    ...n.enum && { enum: n.enum },
-    ...n.default !== void 0 && { default: n.default }
+  for (const [a, s] of Object.entries(n.properties ?? {})) e[a] = {
+    type: s.type,
+    ...s.description != null && { description: s.description },
+    ...s.enum && { enum: s.enum },
+    ...s.default !== void 0 && { default: s.default }
   };
   return {
     type: "object",
@@ -74,15 +74,15 @@ function J(s) {
     required: []
   };
 }
-function R(s) {
-  const { name: e, description: a, schema: n } = s;
-  if (!P.test(e)) throw new Error(`Invalid form collector name "${e}": must match ${P} (it becomes the update_/submit_ function names).`);
-  const o = typeof s.submit == "string" ? s.submit ? {
+function B(n) {
+  const { name: e, description: a, schema: s } = n;
+  if (!j.test(e)) throw new Error(`Invalid form collector name "${e}": must match ${j} (it becomes the update_/submit_ function names).`);
+  const o = typeof n.submit == "string" ? n.submit ? {
     via: "client",
-    url: s.submit
-  } : !1 : s.submit ?? !1;
-  s.autoSubmit === !0 && !o && $.warn(`FormCollector "${e}": autoSubmit is ignored because no submit target is configured.`);
-  const c = (s.autoSubmit ?? !0) && !!o, b = n.properties ?? {}, m = (t) => {
+    url: n.submit
+  } : !1 : n.submit ?? !1;
+  n.autoSubmit === !0 && !o && w.warn(`FormCollector "${e}": autoSubmit is ignored because no submit target is configured.`);
+  const c = (n.autoSubmit ?? !0) && !!o, b = s.properties ?? {}, m = (t) => {
     const r = {};
     for (const [u, i] of Object.entries(t)) {
       const l = b[u];
@@ -94,10 +94,10 @@ function R(s) {
         } else l.type === "boolean" ? r[u] = typeof i == "boolean" ? i : i === "true" ? !0 : i === "false" ? !1 : !!i : r[u] = i;
     }
     return r;
-  }, S = s.initialValues ?? {}, f = A({
-    values: S,
+  }, $ = n.initialValues ?? {}, f = J({
+    values: $,
     submitted: !1
-  }), C = (t) => {
+  }), k = (t) => {
     const r = f.get(), u = {
       ...r,
       values: {
@@ -108,16 +108,16 @@ function R(s) {
     return f.set(u), u;
   };
   let h = null;
-  const k = (t, r) => {
+  const F = (t, r) => {
     h?.emitFormEvent("form:error", {
       name: e,
       values: t,
       error: r
     });
   };
-  let p = null;
-  const j = async () => {
-    const { values: t } = f.get(), { complete: r, missing: u } = y(n, t);
+  let y = null;
+  const V = async () => {
+    const { values: t } = f.get(), { complete: r, missing: u } = p(s, t);
     if (!r) return {
       ok: !1,
       missing: u
@@ -138,10 +138,10 @@ function R(s) {
           body: JSON.stringify(i)
         });
         if (!d.ok) {
-          const x = `Submit failed: HTTP ${d.status}`;
-          return k(i, x), {
+          const W = `Submit failed: HTTP ${d.status}`;
+          return F(i, W), {
             ok: !1,
-            error: x
+            error: W
           };
         }
         l = await d.json().catch(() => {
@@ -168,27 +168,27 @@ function R(s) {
       };
     } catch (l) {
       const d = l instanceof Error ? l.message : "Submit failed";
-      return $.error(`FormCollector "${e}" submit failed:`, l), k(i, d), {
+      return w.error(`FormCollector "${e}" submit failed:`, l), F(i, d), {
         ok: !1,
         error: d
       };
     }
-  }, N = () => p || (p = (async () => {
+  }, C = () => y || (y = (async () => {
     try {
-      return await j();
+      return await V();
     } finally {
-      p = null;
+      y = null;
     }
-  })(), p), F = async () => {
+  })(), y), q = async () => {
     if (!c || !o) return null;
     const { values: t, submitted: r } = f.get();
-    return r || !y(n, t).complete ? null : N();
-  }, q = {
+    return r || !p(s, t).complete ? null : C();
+  }, O = {
     name: `update_${e}`,
     description: `Fill or update fields of the "${e}" form. ${a} Pass any subset of fields; call it repeatedly to fill the form as the user provides information. Returns the current values and which required fields are still missing.`,
-    parameters: J(n),
+    parameters: R(s),
     handler: async (t) => {
-      const r = C(m(t)), { missing: u } = y(n, r.values), i = await F();
+      const r = k(m(t)), { missing: u } = p(s, r.values), i = await q();
       return i ? i.ok ? {
         ok: !0,
         values: r.values,
@@ -206,7 +206,7 @@ function R(s) {
         missing: u
       };
     }
-  }, g = [q];
+  }, g = [O];
   o && !c && g.push({
     name: `submit_${e}`,
     description: `Submit the completed "${e}" form. Only call this once every required field is collected and the user has confirmed. If fields are missing it returns them instead of submitting.`,
@@ -214,30 +214,34 @@ function R(s) {
       type: "object",
       properties: {}
     },
-    handler: () => N()
+    handler: () => C()
   });
-  const I = "client__", O = o ? `submit_${e}` : null, V = (t) => {
+  const A = "client__", x = o ? `submit_${e}` : null, D = (t) => {
     const r = t.functionName ?? t.toolName;
     if (r)
-      return r.startsWith(I) ? r.slice(8) : r;
+      return r.startsWith(A) ? r.slice(8) : r;
   }, _ = (t) => {
-    let r = { ...S }, u = !1;
+    let r = { ...$ }, u = !1;
     for (const i of t) {
-      const l = V(i);
-      l === q.name ? i.arguments && (r = {
+      const l = D(i);
+      l === O.name ? i.arguments && (r = {
         ...r,
         ...m(i.arguments)
-      }) : O && l === O && i.status?.toLowerCase() === "done" && (u = !0);
+      }) : x && l === x && i.status?.toLowerCase() === "done" && (u = !0);
     }
     f.set({
       values: r,
       submitted: u
     });
-  }, w = `form:${e}`, E = () => {
-    const { values: t, submitted: r } = f.get(), { missing: u, complete: i } = y(n, t), l = o ? c ? " The form is submitted automatically as soon as every required field is filled, so there is no submit function to call." : ` When nothing is missing and the user confirms, call submit_${e}.` : "", d = r ? `The "${e}" form has been submitted.` : `You are currently collecting information from the user to fill the "${e}" form.`;
+  }, v = `form:${e}`, S = `${v}:definition`, E = () => ({
+    name: `Form definition: ${e}`,
+    description: `${a} Some fields are conditionally required; the requiredWhen field in the schema tells you when each becomes required. The form schema is the following: ${JSON.stringify(s)}.`,
+    stable: !0
+  }), T = () => {
+    const { values: t, submitted: r } = f.get(), { missing: u, complete: i } = p(s, t), l = o ? c ? " The form is submitted automatically as soon as every required field is filled, so there is no submit function to call." : ` When nothing is missing and the user confirms, call submit_${e}.` : "", d = r ? `The "${e}" form has been submitted.` : `You are currently collecting information from the user to fill the "${e}" form.`;
     return {
       name: `Form: ${e}`,
-      description: `${d} ${a} Some fields are conditionally required; the requiredWhen field in the schema tells you when each becomes required. The form schema is the following: ${JSON.stringify(n)}. Data collected so far: ${JSON.stringify(t)}. Call update_${e} with any fields the user provides; ask only for what is still missing.${l}`,
+      description: `${d} The form's schema and field requirements are in the "${S}" client context. Call update_${e} with any fields the user provides; ask only for what is still missing.${l}`,
       data: {
         values: t,
         missing: u,
@@ -245,44 +249,46 @@ function R(s) {
         submitted: r
       }
     };
-  }, T = (t) => {
+  }, P = (t) => {
     _((t.messages ?? []).flatMap((r) => r.toolCalls ?? []));
   };
   return {
     name: e,
     store: f,
     functions: g,
-    contextKey: w,
-    contextProvider: E,
+    contextKey: v,
+    contextProvider: T,
+    definitionContextKey: S,
+    definitionContextProvider: E,
     install: (t) => {
       h = t;
       for (const u of g) t.register(u);
-      t.addDynamicContext(w, E);
+      t.addDynamicContext(S, E), t.addDynamicContext(v, T);
       const r = f.subscribe(() => t.notifyContextChanged());
-      return t.on("conversation:loaded", T), () => {
+      return t.on("conversation:loaded", P), () => {
         r();
         for (const u of g) t.unregisterFunction(u.name);
-        t.removeDynamicContext(w), t.off("conversation:loaded", T), h === t && (h = null);
+        t.removeDynamicContext(v), t.removeDynamicContext(S), t.off("conversation:loaded", P), h === t && (h = null);
       };
     },
     hydrate: _,
-    submit: N,
+    submit: C,
     getValues: () => f.get().values,
     setValues: (t) => {
-      C(m(t)), F();
+      k(m(t)), q();
     },
     reset: () => {
       f.set({
-        values: S,
+        values: $,
         submitted: !1
       });
     },
-    getStatus: () => y(n, f.get().values)
+    getStatus: () => p(s, f.get().values)
   };
 }
-async function L(s, e) {
-  const a = await s.getFormCollector(e.name);
-  return R({
+async function K(n, e) {
+  const a = await n.getFormCollector(e.name);
+  return B({
     name: a.name,
     description: e.description ?? a.description,
     schema: e.schema ?? a.schema,
@@ -292,8 +298,8 @@ async function L(s, e) {
   });
 }
 export {
-  A as i,
-  y as n,
-  L as r,
-  R as t
+  J as i,
+  p as n,
+  K as r,
+  B as t
 };

package/dist/devtools.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/devtools.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/functions-CPs7omgM.cjs

@@ -0,0 +1 @@
+const v=require("./react.cjs");var w=v.__exportAll({copyToClipboard:()=>c,getLocalStorage:()=>f,getUserLocation:()=>p,highlightElement:()=>h,openUrl:()=>a,scrollToElement:()=>d,setLocalStorage:()=>m,setTheme:()=>l,showConfirmDialog:()=>u,showNotification:()=>s,showToast:()=>i,submitForm:()=>y,trackEvent:()=>g}),i={name:"showToast",description:"Show a toast notification to the user. Use this to confirm actions or display brief messages.",parameters:{type:"object",properties:{message:{type:"string",description:"The message to display"},type:{type:"string",description:"Toast type",enum:["success","error","warning","info"]},duration:{type:"number",description:"Duration in milliseconds (default 3000)"}},required:["message"]},handler:async()=>({shown:!1,error:"No toast handler configured"})},s={name:"showNotification",description:"Show a browser notification to the user. Useful for important alerts even when the tab is not focused.",parameters:{type:"object",properties:{title:{type:"string",description:"Notification title"},body:{type:"string",description:"Notification body text"}},required:["title"]},handler:async e=>typeof Notification>"u"?{shown:!1,error:"Notifications not supported"}:Notification.permission==="denied"?{shown:!1,error:"Notification permission denied"}:(Notification.permission!=="granted"&&await Notification.requestPermission(),Notification.permission==="granted"?(new Notification(e.title,{body:e.body}),{shown:!0}):{shown:!1,error:"Permission not granted"})},a={name:"openUrl",description:"Open a URL in a new browser tab.",parameters:{type:"object",properties:{url:{type:"string",description:"The URL to open"}},required:["url"]},handler:async e=>(window.open(e.url,"_blank","noopener,noreferrer"),{opened:!0})},c={name:"copyToClipboard",description:"Copy text to the user's clipboard.",parameters:{type:"object",properties:{text:{type:"string",description:"The text to copy"}},required:["text"]},handler:async e=>(await navigator.clipboard.writeText(e.text),{copied:!0})},l={name:"setTheme",description:"Change the application's color theme. Sets a data-theme attribute on the document element.",parameters:{type:"object",properties:{theme:{type:"string",description:"Theme to apply",enum:["light","dark","system"]}},required:["theme"]},handler:async e=>{const t=e.theme;return document.documentElement.setAttribute("data-theme",t),t==="dark"?document.documentElement.classList.add("dark"):document.documentElement.classList.remove("dark"),{theme:t,applied:!0}}},u={name:"showConfirmDialog",description:"Show a confirmation dialog to the user and return their choice (true/false).",parameters:{type:"object",properties:{message:{type:"string",description:"The confirmation message to display"}},required:["message"]},handler:async e=>({confirmed:window.confirm(e.message)})},p={name:"getUserLocation",description:"Get the user's current geographic location (requires permission).",parameters:{type:"object",properties:{}},handler:async()=>navigator.geolocation?new Promise(e=>{navigator.geolocation.getCurrentPosition(t=>e({latitude:t.coords.latitude,longitude:t.coords.longitude,accuracy:t.coords.accuracy}),t=>e({error:t.message}))}):{error:"Geolocation not supported"}},d={name:"scrollToElement",description:"Scroll the page to a specific element identified by CSS selector.",parameters:{type:"object",properties:{selector:{type:"string",description:"CSS selector of the element to scroll to (e.g. '#section-pricing')"},behavior:{type:"string",description:"Scroll behavior",enum:["smooth","instant"]}},required:["selector"]},handler:async e=>{const t=document.querySelector(e.selector);return t?(t.scrollIntoView({behavior:e.behavior||"smooth"}),{scrolled:!0}):{scrolled:!1,error:`Element not found: ${e.selector}`}}},m={name:"setLocalStorage",description:"Store a value in the browser's localStorage.",parameters:{type:"object",properties:{key:{type:"string",description:"Storage key"},value:{type:"string",description:"Value to store"}},required:["key","value"]},handler:async e=>(localStorage.setItem(e.key,e.value),{stored:!0})},f={name:"getLocalStorage",description:"Retrieve a value from the browser's localStorage.",parameters:{type:"object",properties:{key:{type:"string",description:"Storage key"}},required:["key"]},handler:async e=>{const t=localStorage.getItem(e.key);return{key:e.key,value:t,found:t!==null}}},h={name:"highlightElement",description:"Highlight a DOM element to draw the user's attention (e.g. for onboarding).",parameters:{type:"object",properties:{selector:{type:"string",description:"CSS selector of the element to highlight"},color:{type:"string",description:"Highlight border color (default: #3b82f6)"}},required:["selector"]},handler:async e=>{const t=document.querySelector(e.selector);if(!t)return{highlighted:!1,error:`Element not found: ${e.selector}`};const r=t.style.outline,o=e.color||"#3b82f6";return t.style.outline=`3px solid ${o}`,t.style.outlineOffset="2px",t.scrollIntoView({behavior:"smooth",block:"center"}),setTimeout(()=>{t.style.outline=r,t.style.outlineOffset=""},3e3),{highlighted:!0}}},y={name:"submitForm",description:"Fill and submit an HTML form on the page. Pass field values as key-value pairs.",parameters:{type:"object",properties:{selector:{type:"string",description:"CSS selector of the form element"},values:{type:"string",description:"JSON string of field name → value pairs"}},required:["selector"]},handler:async e=>{const t=document.querySelector(e.selector);if(!t)return{submitted:!1,error:`Form not found: ${e.selector}`};if(e.values){const r=JSON.parse(e.values);for(const[o,b]of Object.entries(r)){const n=t.elements.namedItem(o);n&&(n.value=b)}}return t.requestSubmit(),{submitted:!0}}},g={name:"trackEvent",description:"Track a custom analytics event. Override the handler to wire up your analytics provider.",parameters:{type:"object",properties:{event:{type:"string",description:"Event name"},properties:{type:"string",description:"JSON string of event properties"}},required:["event"]},handler:async e=>{const t=e.properties?JSON.parse(e.properties):{};return console.log(`[AGO Analytics] ${e.event}`,t),{tracked:!0,event:e.event}}};Object.defineProperty(exports,"copyToClipboard",{enumerable:!0,get:function(){return c}});Object.defineProperty(exports,"functions_exports",{enumerable:!0,get:function(){return w}});Object.defineProperty(exports,"getLocalStorage",{enumerable:!0,get:function(){return f}});Object.defineProperty(exports,"getUserLocation",{enumerable:!0,get:function(){return p}});Object.defineProperty(exports,"highlightElement",{enumerable:!0,get:function(){return h}});Object.defineProperty(exports,"openUrl",{enumerable:!0,get:function(){return a}});Object.defineProperty(exports,"scrollToElement",{enumerable:!0,get:function(){return d}});Object.defineProperty(exports,"setLocalStorage",{enumerable:!0,get:function(){return m}});Object.defineProperty(exports,"setTheme",{enumerable:!0,get:function(){return l}});Object.defineProperty(exports,"showConfirmDialog",{enumerable:!0,get:function(){return u}});Object.defineProperty(exports,"showNotification",{enumerable:!0,get:function(){return s}});Object.defineProperty(exports,"showToast",{enumerable:!0,get:function(){return i}});Object.defineProperty(exports,"submitForm",{enumerable:!0,get:function(){return y}});Object.defineProperty(exports,"trackEvent",{enumerable:!0,get:function(){return g}});