@useago/sdk 1.4.3 → 1.5.0

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
  */
@@ -186,7 +203,7 @@ export declare class AgoClient {
      * ```
      */
     registerFunction(definition: ClientFunctionDefinition): void;
-    registerFunction(name: string, handler: ClientFunctionHandler, schema: Omit<ClientFunctionSchema, "name">): void;
+    registerFunction(name: string, handler: ClientFunctionHandler, schema: ClientFunctionRegisterOptions): void;
     /**
      * Short alias for `registerFunction`. Also accepts an array of definitions.
      *
@@ -487,14 +504,22 @@ 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;
+    /**
+     * Max serialized size (bytes) of a client function result before the SDK
+     * replaces it with a flagged, truncated preview. Everything a handler
+     * returns is sent into the LLM context, so this caps runaway payloads
+     * (raw API responses, full tables). Default `50000`. Override per function
+     * with `maxResultBytes` on its definition; `Infinity` disables the guard.
+     */
+    maxFunctionResultBytes?: number;
 }
 
 /**
@@ -651,6 +676,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.
  *
@@ -733,6 +790,12 @@ export declare interface ClientFunctionDefinition {
     description: string;
     parameters: ClientFunctionSchema["parameters"];
     handler: ClientFunctionHandler;
+    /**
+     * Max serialized result size in bytes before the SDK truncates it to a
+     * flagged preview (default: `AgoConfig.maxFunctionResultBytes`, 50 000).
+     * `Infinity` disables the guard for this function.
+     */
+    maxResultBytes?: number;
 }
 
 /**
@@ -747,6 +810,20 @@ export declare interface ClientFunctionInvocation {
     conversationId: string;
 }
 
+/**
+ * Schema-plus-settings object accepted when registering a function: the schema
+ * (minus `name`) and SDK-side options that are NOT sent to the backend.
+ */
+export declare type ClientFunctionRegisterOptions = Omit<ClientFunctionSchema, "name"> & {
+    /**
+     * Max serialized result size in bytes before the SDK truncates it to a
+     * flagged preview. Overrides the client-level default
+     * (`AgoConfig.maxFunctionResultBytes`, 50 000 by default). `Infinity`
+     * disables the guard for this function.
+     */
+    maxResultBytes?: number;
+};
+
 /**
  * Schema for a client-side function that AGO can call
  */
@@ -1244,12 +1321,16 @@ export declare interface FunctionDefinition {
  */
 export declare class FunctionRegistry {
     private functions;
+    private defaultMaxResultBytes;
+    constructor(options?: FunctionRegistryOptions);
+    /** Update the client-level result-size ceiling at runtime. */
+    setDefaultMaxResultBytes(bytes: number): void;
     /**
      * Register a function that AGO can call.
      * Accepts either a single definition object or (name, handler, schema) args.
      */
     register(definition: ClientFunctionDefinition): void;
-    register(name: string, handler: ClientFunctionHandler, schema: Omit<ClientFunctionSchema, "name">): void;
+    register(name: string, handler: ClientFunctionHandler, schema: ClientFunctionRegisterOptions): void;
     /**
      * Unregister a function
      */
@@ -1270,6 +1351,14 @@ export declare class FunctionRegistry {
      * Execute a registered function
      */
     execute(name: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Cap the size of a function result before it goes back to the backend.
+     * Everything a handler returns lands in the LLM context, so an unbounded
+     * payload (a raw API response, a full table) inflates cost and can overflow
+     * the model. Oversized results are replaced with a flagged preview so the
+     * agent knows to request less instead of receiving hundreds of KB verbatim.
+     */
+    private guardResultSize;
     /**
      * Clear all registered functions
      */
@@ -1280,6 +1369,11 @@ export declare class FunctionRegistry {
     get size(): number;
 }
 
+declare interface FunctionRegistryOptions {
+    /** Client-level default for the result-size ceiling, in bytes. */
+    maxResultBytes?: number;
+}
+
 /**
  * Client-side function types
  */
@@ -1471,6 +1565,8 @@ export declare interface PersistOptions {
 export declare interface RegisteredFunction {
     schema: ClientFunctionSchema;
     handler: ClientFunctionHandler;
+    /** Per-function result-size ceiling; falls back to the registry default. */
+    maxResultBytes?: number;
 }
 
 /**

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
  */
@@ -186,7 +203,7 @@ export declare class AgoClient {
      * ```
      */
     registerFunction(definition: ClientFunctionDefinition): void;
-    registerFunction(name: string, handler: ClientFunctionHandler, schema: Omit<ClientFunctionSchema, "name">): void;
+    registerFunction(name: string, handler: ClientFunctionHandler, schema: ClientFunctionRegisterOptions): void;
     /**
      * Short alias for `registerFunction`. Also accepts an array of definitions.
      *
@@ -487,14 +504,22 @@ 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;
+    /**
+     * Max serialized size (bytes) of a client function result before the SDK
+     * replaces it with a flagged, truncated preview. Everything a handler
+     * returns is sent into the LLM context, so this caps runaway payloads
+     * (raw API responses, full tables). Default `50000`. Override per function
+     * with `maxResultBytes` on its definition; `Infinity` disables the guard.
+     */
+    maxFunctionResultBytes?: number;
 }
 
 /**
@@ -651,6 +676,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.
  *
@@ -733,6 +790,12 @@ export declare interface ClientFunctionDefinition {
     description: string;
     parameters: ClientFunctionSchema["parameters"];
     handler: ClientFunctionHandler;
+    /**
+     * Max serialized result size in bytes before the SDK truncates it to a
+     * flagged preview (default: `AgoConfig.maxFunctionResultBytes`, 50 000).
+     * `Infinity` disables the guard for this function.
+     */
+    maxResultBytes?: number;
 }
 
 /**
@@ -747,6 +810,20 @@ export declare interface ClientFunctionInvocation {
     conversationId: string;
 }
 
+/**
+ * Schema-plus-settings object accepted when registering a function: the schema
+ * (minus `name`) and SDK-side options that are NOT sent to the backend.
+ */
+export declare type ClientFunctionRegisterOptions = Omit<ClientFunctionSchema, "name"> & {
+    /**
+     * Max serialized result size in bytes before the SDK truncates it to a
+     * flagged preview. Overrides the client-level default
+     * (`AgoConfig.maxFunctionResultBytes`, 50 000 by default). `Infinity`
+     * disables the guard for this function.
+     */
+    maxResultBytes?: number;
+};
+
 /**
  * Schema for a client-side function that AGO can call
  */
@@ -1244,12 +1321,16 @@ export declare interface FunctionDefinition {
  */
 export declare class FunctionRegistry {
     private functions;
+    private defaultMaxResultBytes;
+    constructor(options?: FunctionRegistryOptions);
+    /** Update the client-level result-size ceiling at runtime. */
+    setDefaultMaxResultBytes(bytes: number): void;
     /**
      * Register a function that AGO can call.
      * Accepts either a single definition object or (name, handler, schema) args.
      */
     register(definition: ClientFunctionDefinition): void;
-    register(name: string, handler: ClientFunctionHandler, schema: Omit<ClientFunctionSchema, "name">): void;
+    register(name: string, handler: ClientFunctionHandler, schema: ClientFunctionRegisterOptions): void;
     /**
      * Unregister a function
      */
@@ -1270,6 +1351,14 @@ export declare class FunctionRegistry {
      * Execute a registered function
      */
     execute(name: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Cap the size of a function result before it goes back to the backend.
+     * Everything a handler returns lands in the LLM context, so an unbounded
+     * payload (a raw API response, a full table) inflates cost and can overflow
+     * the model. Oversized results are replaced with a flagged preview so the
+     * agent knows to request less instead of receiving hundreds of KB verbatim.
+     */
+    private guardResultSize;
     /**
      * Clear all registered functions
      */
@@ -1280,6 +1369,11 @@ export declare class FunctionRegistry {
     get size(): number;
 }
 
+declare interface FunctionRegistryOptions {
+    /** Client-level default for the result-size ceiling, in bytes. */
+    maxResultBytes?: number;
+}
+
 /**
  * Client-side function types
  */
@@ -1471,6 +1565,8 @@ export declare interface PersistOptions {
 export declare interface RegisteredFunction {
     schema: ClientFunctionSchema;
     handler: ClientFunctionHandler;
+    /** Per-function result-size ceiling; falls back to the registry default. */
+    maxResultBytes?: number;
 }
 
 /**

package/dist/index.js

@@ -1,37 +1,38 @@
-import { a as h, c as A, d as y, f as C, i as E, l as S, m as b, o as v, p as F, r as M, s as I, t as k, u as T } from "./functions-CApuQZ2b.js";
-import { _ as G, a as O, c as _, d as q, f as x, g as L, h as N, l as D, m as d, n as H, o as J, p as R, r as j, s as z, t as c, u as B } from "./AgoClient-S8oeNnAE.js";
-import { i as $, n as K, r as Q, t as V } from "./createFormCollector-vy-QvFja.js";
-import { t as X } from "./createConversationSession-DoUHdVNR.js";
-import { t as Z } from "./createMockClient-bAZ9KBHC.js";
+import { a as h, c as A, d as C, f as y, i as E, l as S, m as b, o as v, p as F, r as M, s as I, t as k, u as T } from "./functions-CApuQZ2b.js";
+import { _ as G, a as N, c as O, d as _, f as q, g as x, h as L, l as D, m as d, n as H, o as J, p as R, r as j, s as z, t as c, u as B } from "./AgoClient-q39FIjSC.js";
+import { t as $ } from "./autoContinue-D3Mmaaca.js";
+import { i as Q, n as V, r as W, t as X } from "./createFormCollector-sB6rMccD.js";
+import { t as Z } from "./createConversationSession-DCSWShaW.js";
+import { t as oe } from "./createMockClient-BUc9PSbo.js";
 import "./testing.js";
-function oe(e) {
+function re(e) {
   return e;
 }
-function te(e, o) {
+function ne(e, o) {
   return e.on("message:complete", o), () => e.off("message:complete", o);
 }
-function re(e, o) {
+function ae(e, o) {
   return e.on("message:chunk", o), () => e.off("message:chunk", o);
 }
-function ne(e, o) {
+function se(e, o) {
   return e.on("message:start", o), () => e.off("message:start", o);
 }
-function ae(e, o) {
+function ie(e, o) {
   return e.on("message:error", o), () => e.off("message:error", o);
 }
-function se(e, o) {
+function ue(e, o) {
   return e.on("toolCall:received", o), () => e.off("toolCall:received", o);
 }
-function ie(e, o) {
+function ge(e, o) {
   return e.on("form:submitted", o), () => e.off("form:submitted", o);
 }
-function ue(e, o) {
+function fe(e, o) {
   return e.on("form:error", o), () => e.off("form:error", o);
 }
-function ge(e, o) {
+function me(e, o) {
   return e.on("function:invoke", o), () => e.off("function:invoke", o);
 }
-async function* fe(e, o, u) {
+async function* le(e, o, u) {
   const n = [];
   let r = null, a = !1;
   const g = (s) => {
@@ -94,12 +95,12 @@ function p(e) {
     debug: f
   } : null;
 }
-function me(e) {
+function de(e) {
   const o = p(e);
   if (!o) throw new d('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 c(o);
 }
-function le(e, o) {
+function ce(e, o) {
   return {
     ...e,
     handler: o
@@ -109,49 +110,50 @@ export {
   R as AgoApiError,
   c as AgoClient,
   d as AgoError,
-  N as AgoFunctionError,
-  L as AgoNetworkError,
+  L as AgoFunctionError,
+  x as AgoNetworkError,
   G as AgoStreamError,
   B as ClientContextRegistry,
   j as EventEmitter,
-  q as FunctionRegistry,
-  _ as SSEHandler,
+  _ as FunctionRegistry,
+  O as SSEHandler,
+  $ as attachAutoContinueAfterNavigation,
   p as autoDetectConfig,
-  O as canInlineImage,
+  N as canInlineImage,
   k as copyToClipboard,
-  me as createAgo,
-  X as createConversationSession,
-  V as createFormCollector,
-  fe as createMessageStream,
-  Z as createMockClient,
-  $ as createStore,
-  oe as defineFunction,
-  K as deriveFormStatus,
+  de as createAgo,
+  Z as createConversationSession,
+  X as createFormCollector,
+  le as createMessageStream,
+  oe as createMockClient,
+  Q as createStore,
+  re as defineFunction,
+  V as deriveFormStatus,
   J as formatFileSize,
   M as getLocalStorage,
   E as getUserLocation,
   h as highlightElement,
   D as isStreamNetworkError,
-  Q as loadFormCollector,
-  x as logger,
-  ue as onFormError,
-  ie as onFormSubmitted,
-  ge as onFunctionInvoke,
-  te as onMessage,
-  re as onMessageChunk,
-  ae as onMessageError,
-  ne as onMessageStart,
-  se as onToolCall,
+  W as loadFormCollector,
+  q as logger,
+  fe as onFormError,
+  ge as onFormSubmitted,
+  me as onFunctionInvoke,
+  ne as onMessage,
+  ae as onMessageChunk,
+  ie as onMessageError,
+  se as onMessageStart,
+  ue as onToolCall,
   v as openUrl,
   z as safeAttachmentUrl,
   I as scrollToElement,
   A as setLocalStorage,
   S as setTheme,
   T as showConfirmDialog,
-  y as showNotification,
-  C as showToast,
+  C as showNotification,
+  y as showToast,
   F as submitForm,
   b as trackEvent,
   H as validateConfig,
-  le as withHandler
+  ce as withHandler
 };