@useago/sdk 1.5.0 → 1.5.2

package/llms-full.txt

@@ -1304,6 +1304,17 @@ Per framework:
 | Vue | `useAgoFunction(name, options)` (auto-cleanup) |
 | Angular | `agoService.registerFunction(def)` |
 
+### Keep the number of functions low
+
+You can send up to **30** client functions with a message. Above that, the
+request is rejected.
+
+Stay well under the limit whenever you can. The more functions the agent has to
+choose from, the harder it becomes to pick the right one: past **10** functions
+in a single message, expect the agent to call the wrong function or miss the
+right one more often. Register only the functions relevant to the current page
+or state, and unregister the ones that no longer apply.
+
 ### Navigation shortcut
 
 A common case (letting the agent move the user around) has a dedicated helper
@@ -1426,8 +1437,11 @@ How the gap is bridged depends on the client-functions mode:
 
 A paused turn also survives a full page reload: after `getConversation(...)`,
 call `client.resumePendingClientFunctions(conversation)` to re-run the waiting
-functions, submit their results, and resume the turn (opt-in — re-running a
-navigation on reload navigates again).
+functions, submit their results, and resume the turn (opt-in, re-running a
+navigation on reload navigates again). A call gated by the approval policy (see
+below) is not re-run on reload either: `resumePendingClientFunctions` holds it
+for `approveFunction` / `rejectFunction` and keeps the turn paused, exactly as on
+the live stream.
 
 ### Observe invocations
 
@@ -1440,6 +1454,37 @@ client.on("function:result", ({ result, error }) =>
 );
 ```
 
+### Approval gate (ask before running)
+
+In pause mode you can hold a client function call until the user approves it.
+Set `approvalPolicy` on the config to gate calls by name (or anything on the
+invocation), or mark a single function with `requiresApproval: true`. The two OR
+together.
+
+```ts
+const client = new AgoClient({
+  baseUrl: "https://playground.api.useago.com",
+  agent: "your-agent",
+  // Return true for calls the user must approve first.
+  approvalPolicy: (inv) => inv.functionName === "deleteAccount",
+});
+
+client.on("function:awaiting-approval", ({ invocationId, functionName }) => {
+  // Show your UI, then decide:
+  if (userSaidYes) client.approveFunction(invocationId); // runs it, resumes the turn
+  else client.rejectFunction(invocationId); // submits a rejection, agent sees the decline
+});
+```
+
+A gated call stays at `WAITING_CLIENT`: the handler does not run and nothing is
+submitted until `approveFunction(invocationId)`. `rejectFunction(invocationId)`
+submits `{ approved: false, reason: "user_rejected" }` so the agent knows the
+user declined, then lets the turn resume. This is a no-op in placeholder mode
+(there is no paused turn to hold onto), so the call runs normally.
+
+In React, `useAgoActivity` surfaces awaiting items with ready-made `approve` /
+`reject` controls (see the [React guide](../frameworks/react.md)).
+
 ---
 
 ## Pre-built helpers
@@ -1518,9 +1563,35 @@ interface ContextEntry {
   name?: string;        // human label, e.g. "Order detail"
   description?: string; // what this context represents
   data?: Record<string, unknown>; // structured data for the AI
+  stable?: boolean;     // constant for the whole conversation (see below)
 }
 ```
 
+### Stable context (prompt caching)
+
+By default an entry is re-sent next to every new user message, which is right
+for data that changes as the user acts (a cart, the current page). If an
+entry's content never changes during a conversation (a schema, a capability
+list, static instructions), mark it `stable: true`: the backend pins it right
+after the system prompt, where LLM providers cache it across turns instead of
+re-processing it on every message.
+
+```ts
+client.setContext("catalog", {
+  name: "Product catalog",
+  description: "The products the agent can talk about",
+  data: { products: PRODUCTS },
+  stable: true, // content is identical on every message
+});
+```
+
+Only mark an entry stable when its content is byte-identical on every message.
+A "stable" entry that changes between messages invalidates the provider's
+cache for the whole conversation history, which costs more than leaving the
+flag off. Form collectors do this automatically: the form's schema is
+registered as a stable entry and only the live values/missing state is sent
+per message.
+
 ### Dynamic context
 
 A function evaluated on every send, perfect for data outside your render state
@@ -1608,6 +1679,7 @@ const final = await client.waitFor("message:complete", { timeout: 10_000 });
 | `toolCall:received` | `ToolCallData` |
 | `toolCall:form` | `ToolCallData` (only when the tool call is a form) |
 | `function:invoke` | `{ invocationId, functionName, arguments, conversationId }` |
+| `function:awaiting-approval` | `{ invocationId, functionName, arguments, conversationId }`: a client function call is held pending user approval (pause mode + an `approvalPolicy`/`requiresApproval` match). The turn stays at `WAITING_CLIENT`; call `approveFunction(invocationId)` to run it and resume, or `rejectFunction(invocationId)` to decline. See [Approval gate](functions-and-context.md#approval-gate-ask-before-running) |
 | `function:result` | `{ invocationId, result, error? }` |
 | `form:submitted` | `{ name, values, result }`: a form collector submitted successfully; `result` is the submit response (the third-party API's answer) |
 | `form:error` | `{ name, values, error }`: a form collector submit failed at the network/server level (HTTP non-2xx or a thrown handler/fetch). Validation pre-checks (missing fields, no submit target) do not fire this |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useago/sdk",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Create In-APP AI agents that answers question and performs actions. Works with React, Vue, Angular and vanilla JS/TS.",
   "type": "module",
   "sideEffects": false,