@useago/sdk 1.3.2 → 1.4.0

package/dist/react.d.ts

@@ -30,6 +30,23 @@ 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
  */
@@ -156,6 +173,37 @@ declare class AgoClient {
         path: string;
         description: string;
     }>): void;
+    /**
+     * Register a "page state" function that lets AGO change the current page's
+     * state (filters, sort, view mode, selection…) and reads the current state
+     * back as dynamic context. This is the state-mutation mirror of
+     * {@link registerNavigationFunction}.
+     *
+     * It does two things:
+     * - Synthesizes ONE client function (default name `setPageState`) whose
+     *   properties are the controls — all optional, so the agent sets only the
+     *   ones the user asked for.
+     * - Registers a dynamic context provider (keyed `page-state:<fnName>`) that
+     *   reports each control's current `get()` value on every message.
+     *
+     * ```ts
+     * client.registerPageStateFunction([
+     *   {
+     *     name: "statusFilter",
+     *     description: "Filter the list by review status",
+     *     schema: { type: "string", enum: ["all", "pending", "approved"] },
+     *     get: () => filters.status,
+     *     set: (v) => setFilters({ ...filters, status: v }),
+     *   },
+     * ]);
+     * ```
+     */
+    registerPageStateFunction(controls: AgoStateControl[], opts?: AgoPageStateOptions): void;
+    /**
+     * Unregister a page state function and its dynamic context provider.
+     * Mirror of unregistering `navigateToPage`.
+     */
+    unregisterPageStateFunction(functionName?: string): void;
     /**
      * Register or update a piece of client-side context.
      * This context is sent with every message so the AI understands the user's situation.
@@ -401,9 +449,23 @@ export declare interface AgoMessage {
     followUpReplies?: string[];
     /** Uploaded files on this message (usually the user's). */
     attachments?: AgoAttachment[];
+    /**
+     * True when the backend flagged this message as hidden (e.g. an
+     * auto-continuation nudge). Kept in the model's context but not displayed;
+     * UI helpers like `useMessages`/`ChatWidget` filter these out.
+     */
+    hidden?: boolean;
     createdAt: Date;
 }
 
+/**
+ * Options for {@link AgoClient.registerPageStateFunction}.
+ */
+export declare interface AgoPageStateOptions {
+    /** Name of the synthesized client function. Defaults to "setPageState". */
+    functionName?: string;
+}
+
 /**
  * Provides an AgoClient to all descendant components via React context.
  *
@@ -457,6 +519,32 @@ export declare interface AgoSource {
     url?: string;
 }
 
+/**
+ * A single editable control on the current page (a filter, a sort, a view mode,
+ * a selection…). It becomes one optional property of the synthesized
+ * `setPageState` function, and its current value is surfaced back to the agent
+ * as dynamic context. This is the state-mutation mirror of a navigation route.
+ */
+export declare interface AgoStateControl<T = unknown> {
+    /** Machine name of the control, e.g. "statusFilter". Becomes a property of the tool. */
+    name: string;
+    /** Description for the LLM, e.g. "Filter the list by review status". */
+    description: string;
+    /** JSON schema for a SINGLE field (like one property of navigateToPage). */
+    schema: {
+        type: "string" | "number" | "boolean" | "array";
+        enum?: (string | number)[];
+        items?: {
+            type: string;
+            enum?: (string | number)[];
+        };
+    };
+    /** Current value → pushed as dynamic context so the agent knows what to change. */
+    get?: () => T;
+    /** Apply the state change on the page. May be async. */
+    set: (value: T) => void | Promise<void>;
+}
+
 /**
  * Chat input component with send button
  */
@@ -566,7 +654,11 @@ declare interface ClientFunctionSchema {
         properties: Record<string, {
             type: string;
             description?: string;
-            enum?: string[];
+            enum?: (string | number)[];
+            items?: {
+                type: string;
+                enum?: (string | number)[];
+            };
             default?: unknown;
         }>;
         required?: string[];
@@ -935,6 +1027,13 @@ declare interface SendMessageOptions {
     agentId?: string;
     /** File attachments */
     files?: File[];
+    /**
+     * Mark this message as hidden. The backend keeps it in the model's context but
+     * flags it so the UI never displays it. Used by auto-continuation to nudge the
+     * agent after a navigation without polluting the visible transcript.
+     * Requires backend support for the `hidden` flag; older backends ignore it.
+     */
+    hidden?: boolean;
 }
 
 /**
@@ -1053,6 +1152,27 @@ export declare function useAgo(config: UseAgoOptions | null): {
     isReady: boolean;
 };
 
+/**
+ * Auto-continue the agent after it navigates, so a "go to page B and change X"
+ * request completes in one user gesture. Mount this once inside `AgoProvider`.
+ *
+ * How it works: when the agent calls the navigation function and that turn ends,
+ * this waits for the destination page's `useAgoPageState` to register (so the
+ * SDK will ship its `setPageState` + current state on the next send), then sends
+ * a hidden continuation message. The agent then applies the state in a second
+ * turn. The continuation is `hidden`, so it never shows in the transcript
+ * (requires backend support for the `hidden` flag).
+ *
+ * ```tsx
+ * function AppShell() {
+ *   useAgoNavigation(navigate, routes);
+ *   useAgoAutoContinueAfterNavigation();
+ *   return <Outlet />;
+ * }
+ * ```
+ */
+export declare function useAgoAutoContinueAfterNavigation(options?: AgoAutoContinueOptions): void;
+
 /**
  * Returns the AgoClient from the nearest AgoProvider.
  * Throws if used outside of an AgoProvider.
@@ -1134,7 +1254,11 @@ export declare interface UseAgoFunctionOptions {
         properties: Record<string, {
             type: string;
             description?: string;
-            enum?: string[];
+            enum?: (string | number)[];
+            items?: {
+                type: string;
+                enum?: (string | number)[];
+            };
             default?: unknown;
         }>;
         required?: string[];
@@ -1158,6 +1282,28 @@ export declare function useAgoNavigation(navigate: (path: string) => void, route
 
 export declare type UseAgoOptions = AgoConfig;
 
+/**
+ * Declaratively register editable page-state controls with the AGO agent.
+ * The state-mutation mirror of `useAgoNavigation`: it wraps
+ * `registerPageStateFunction` with React lifecycle management, so the agent can
+ * change the current page's state (filters, sort, view mode…) and read the
+ * current state back.
+ *
+ * ```tsx
+ * const [status, setStatus] = useState("all");
+ * useAgoPageState([
+ *   {
+ *     name: "statusFilter",
+ *     description: "Filter the list by review status",
+ *     schema: { type: "string", enum: ["all", "pending", "approved"] },
+ *     get: () => status,
+ *     set: setStatus,
+ *   },
+ * ]);
+ * ```
+ */
+export declare function useAgoPageState(controls: AgoStateControl[], opts?: AgoPageStateOptions): void;
+
 export declare interface UseAgoResult {
     /** The AGO client instance */
     client: AgoClient;