@useago/sdk 1.5.0 → 1.5.3

package/dist/react.d.ts

@@ -1,5 +1,41 @@
 import { default as default_2 } from 'react';
 
+/**
+ * One normalized entry in the agent's activity feed. Merges a tool call
+ * (`toolCall:received`) or a client-function invocation (`function:invoke` /
+ * `function:awaiting-approval` / `function:result`) into a single shape.
+ */
+export declare interface AgoActivityItem {
+    /** Stable id — the tool-call id or the function invocationId. */
+    id: string;
+    kind: AgoActivityKind;
+    /** Human label, e.g. "Navigating to Products". Override via `labelFor`. */
+    label: string;
+    status: AgoActivityStatus;
+    /** The assistant message this activity belongs to (when known). */
+    messageId?: string;
+    toolName?: string;
+    toolDisplayName?: string;
+    functionName?: string;
+    arguments?: Record<string, unknown>;
+    message?: string;
+    data?: Record<string, unknown>;
+    formSchema?: FormSchema;
+    /** True when this item waits on the user before it runs. */
+    requiresApproval: boolean;
+    createdAt: Date;
+}
+
+/**
+ * The kind of thing the agent is doing, normalized across the two wire sources
+ * (tool calls and client-function invocations) into one vocabulary the UI can
+ * switch on.
+ */
+export declare type AgoActivityKind = "navigation" | "action" | "status" | "progress" | "reasoning" | "confirmation" | "form";
+
+/** Where the item is in its lifecycle. */
+export declare type AgoActivityStatus = "running" | "done" | "error" | "awaiting-approval" | "rejected";
+
 /**
  * Agent information
  */
@@ -60,8 +96,20 @@ 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;
+    /**
+     * Proactive-mode controller, set when the client was created with
+     * `proactive` options or when `createAgoProactive(client, opts)` was called.
+     * `null` otherwise.
+     */
+    proactive: ProactiveController | null;
     constructor(config: AgoConfig);
     /**
      * Send a message and receive a streaming response
@@ -110,6 +158,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
      */
@@ -139,8 +205,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>;
     /**
@@ -212,6 +280,14 @@ declare class AgoClient {
      * Get all registered function schemas
      */
     getRegisteredFunctions(): ClientFunctionSchema[];
+    /**
+     * Execute a registered client function locally, through the same
+     * FunctionRegistry path (result-size guard, error wrapping) as agent-invoked
+     * calls. Used by proactive nudge actions, where the user's explicit click on
+     * the action button constitutes the approval — nothing is submitted to the
+     * backend (there is no tool call to answer).
+     */
+    executeClientFunction(name: string, args: Record<string, unknown>): Promise<unknown>;
     /**
      * Register a navigation function that lets AGO navigate users to different pages.
      *
@@ -313,6 +389,9 @@ declare class AgoClient {
      */
     notifyContextChanged(): void;
     /* Excluded from this release type: emitFormEvent */
+    /* Excluded from this release type: emitProactiveEvent */
+    /* Excluded from this release type: getHttp */
+    /* Excluded from this release type: getConfiguredAgent */
     /**
      * Enable automatic capture of the current browser page (URL + title).
      * Injected as a dynamic context entry named `browser-page`.
@@ -357,6 +436,7 @@ declare class AgoClient {
      * Clean up resources
      */
     destroy(): void;
+    /* Excluded from this release type: reviveAfterDestroy */
 }
 
 /**
@@ -435,6 +515,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;
@@ -464,6 +553,25 @@ declare interface AgoClientEvents {
     "connection:status": {
         connected: boolean;
     };
+    /**
+     * A proactive nudge passed every governor gate and is ready to display.
+     * `useProactiveNudge` / `<AgoNudge>` consume this; custom UIs should call
+     * `client.proactive.shown(nudge)` when they render it (impression tracking
+     * + frequency caps), then `accept(nudge)` / `dismiss(nudge)`.
+     */
+    "nudge:ready": ProactiveNudgeInstance;
+    /** A nudge was displayed to the user (fires once per nudge). */
+    "nudge:shown": {
+        nudge: ProactiveNudgeInstance;
+    };
+    /** The user dismissed the nudge (its trigger is suppressed, see governor). */
+    "nudge:dismissed": {
+        nudge: ProactiveNudgeInstance;
+    };
+    /** The user accepted the nudge (its action ran / the chat is being seeded). */
+    "nudge:accepted": {
+        nudge: ProactiveNudgeInstance;
+    };
 }
 
 /**
@@ -503,6 +611,20 @@ export declare interface AgoConfig {
      * 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
@@ -511,6 +633,16 @@ export declare interface AgoConfig {
      * with `maxResultBytes` on its definition; `Infinity` disables the guard.
      */
     maxFunctionResultBytes?: number;
+    /**
+     * Enable the proactive mode: declarative triggers evaluated client-side
+     * against friction signals (dwell/idle time, rage clicks, route bounces…)
+     * that can surface a nudge before the user opens the chat. Equivalent to
+     * calling `createAgoProactive(client, proactive)` — the resulting controller
+     * is available as `client.proactive`. Requires the tenant-level kill-switch
+     * (`GET /api/sdk/v1/config` → `proactive.enabled`) to be on; disabled by
+     * default otherwise.
+     */
+    proactive?: ProactiveOptions;
 }
 
 /**
@@ -554,12 +686,44 @@ export declare interface AgoMessage {
     createdAt: Date;
 }
 
+/**
+ * Prebuilt proactive-nudge toast: a small, always-dismissable bubble anchored
+ * near the chat launcher. Never modal — it never blocks the page. Renders the
+ * nudge message, its optional action button, and an "open chat" affordance
+ * for nudges that expand into a conversation.
+ */
+export declare const AgoNudge: default_2.FC<AgoNudgeProps>;
+
+export declare interface AgoNudgeProps {
+    /** The AGO client instance. If omitted, reads from AgoProvider context. */
+    client?: AgoClient;
+    /**
+     * Called after accepting a nudge that expands into the chat (agent-sourced
+     * or with a `goal`) — open your chat UI here. The conversation is already
+     * pre-seeded with a hidden kickoff message.
+     */
+    onExpand?: UseProactiveNudgeOptions["onExpand"];
+    /** Auto-dismiss after this many ms. Off by default (nudges stay until acted on). */
+    autoHideMs?: number;
+    /** Corner to anchor to (near the chat launcher). Default `"bottom-right"`. */
+    position?: "bottom-right" | "bottom-left";
+    /** Label of the open-chat affordance. Default `"Open chat"`. */
+    openChatLabel?: string;
+    /** Additional CSS class (consumer hook only; the SDK ships no CSS for it). */
+    className?: string;
+}
+
 /**
  * Options for {@link AgoClient.registerPageStateFunction}.
  */
 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;
 }
 
 /**
@@ -728,6 +892,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;
 }
 
 /**
@@ -754,6 +923,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;
 };
 
 /**
@@ -794,6 +968,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;
 }
 
 /**
@@ -898,10 +1085,22 @@ export declare interface FormCollector<V = Record<string, unknown>> {
     store: Store<FormCollectorState<V>>;
     /** Client functions to register: `[update]` or `[update, submit]`. */
     functions: ClientFunctionDefinition[];
-    /** Dynamic-context key under which the form state is exposed. */
+    /** Dynamic-context key under which the live form state is exposed. */
     contextKey: string;
-    /** Dynamic-context provider — re-read on every message. */
+    /**
+     * Dynamic-context provider for the live form state (phase, values, missing)
+     * — re-read on every message. The schema itself rides in the companion
+     * {@link definitionContextProvider} entry.
+     */
     contextProvider: () => ContextEntry;
+    /** Context key of the stable form definition (`<contextKey>:definition`). */
+    definitionContextKey: string;
+    /**
+     * Provider for the form's definition (description + schema): identical on
+     * every message and marked `stable: true`, so the backend can pin it in the
+     * cacheable part of the prompt. Registered/removed by `install` alongside `contextProvider`.
+     */
+    definitionContextProvider: () => ContextEntry;
     /** Register the functions + dynamic context on a client. Returns an uninstall fn. */
     install: (client: AgoClient) => () => void;
     /**
@@ -1048,6 +1247,43 @@ export declare interface FormSubmitResult {
     error?: string;
 }
 
+/**
+ * HTTP client with authentication headers
+ */
+declare class HttpClient {
+    private baseUrl;
+    private headers;
+    constructor(config: AgoConfig);
+    /**
+     * Update configuration (e.g., JWT token)
+     */
+    updateConfig(config: Partial<AgoConfig>): void;
+    /**
+     * Make a GET request
+     */
+    get<T>(path: string): Promise<T>;
+    /**
+     * Make a POST request with JSON body.
+     *
+     * `keepalive: true` lets the request survive a page unload (used by the
+     * proactive event tracker's flush-on-hide — sendBeacon can't carry the auth
+     * headers, so it's a keepalive fetch instead).
+     */
+    post<T>(path: string, body?: unknown, options?: {
+        keepalive?: boolean;
+    }): Promise<T>;
+    /**
+     * Make a POST request and return the raw Response (for streaming)
+     */
+    postStream(path: string, body?: unknown): Promise<Response>;
+    /**
+     * Make a POST request with FormData (for file uploads)
+     */
+    postFormData(path: string, formData: FormData): Promise<Response>;
+    private request;
+    private handleErrorResponse;
+}
+
 /**
  * Async sibling of {@link createFormCollector} that pulls the form's definition
  * (description + schema + submit target) from the backend by name — the single
@@ -1142,6 +1378,182 @@ declare interface MockAgoClientOptions {
 
 declare type MockFn = (...args: any[]) => any;
 
+/**
+ * Optional action attached to a nudge. Accepting a `functionName` action
+ * executes the registered client function (same `FunctionRegistry` path as
+ * agent-invoked calls); `setPageState` applies values through the registered
+ * page-state controls.
+ */
+export declare type NudgeAction = {
+    label: string;
+    functionName: string;
+    arguments?: Record<string, unknown>;
+} | {
+    label: string;
+    setPageState: Record<string, unknown>;
+};
+
+/**
+ * Controller returned by {@link createAgoProactive} (also available as
+ * `client.proactive`).
+ */
+export declare interface ProactiveController {
+    /** Persistently opt this browser out of proactive nudges. */
+    optOut(): void;
+    /** Undo {@link optOut}. */
+    optIn(): void;
+    isOptedOut(): boolean;
+    /**
+     * Tell the governor the user is already engaged (e.g. the chat widget is
+     * open) — nudges are suppressed while `true`. Call from the UI layer.
+     */
+    setEngaged(engaged: boolean): void;
+    /** App-pushed field error counter (field NAME only — never values). */
+    signalFieldError(fieldName: string): void;
+    /** Current aggregated friction snapshot. */
+    getSignalsSnapshot(): SignalsSnapshot;
+    /** The nudge currently occupying the single-nudge slot, if any. */
+    getActiveNudge(): ProactiveNudgeInstance | null;
+    /**
+     * Mark the nudge as displayed. Idempotent per nudge; counts it against the
+     * frequency caps, tracks the impression, and emits `nudge:shown`.
+     */
+    shown(nudge: ProactiveNudgeInstance): void;
+    /**
+     * Accept the nudge: run its action (if any), emit `nudge:accepted`, track,
+     * and — for agent nudges or nudges with a `goal` — pre-seed the chat with a
+     * hidden kickoff message so the agent starts the turn with full context.
+     */
+    accept(nudge: ProactiveNudgeInstance): Promise<void>;
+    /** Dismiss the nudge: suppress the trigger, track, emit `nudge:dismissed`. */
+    dismiss(nudge: ProactiveNudgeInstance): void;
+    /** Report a downstream conversion attributable to the nudge (analytics only). */
+    markConverted(nudge: ProactiveNudgeInstance): void;
+    /** Detach everything: listeners, timers, context provider, event flush. */
+    destroy(): void;
+}
+
+/** A concrete nudge produced by the engine, carried by every `nudge:*` event. */
+export declare interface ProactiveNudgeInstance {
+    /** Client-generated uuid for this nudge instance (`client_nudge_id`). */
+    id: string;
+    triggerId: string;
+    /** `static` = configured message; `agent` = backend LLM evaluation. */
+    source: "static" | "agent";
+    message: string;
+    action?: NudgeAction;
+    goal?: string;
+    /** See {@link ProactiveTrigger.kickoff}. */
+    kickoff?: string;
+    createdAt: Date;
+    /** Server-side nudge id (agent nudges only). */
+    serverNudgeId?: string;
+}
+
+/** Options for {@link createAgoProactive} / `AgoConfig.proactive`. */
+export declare interface ProactiveOptions {
+    triggers: ProactiveTrigger[];
+    /**
+     * Global caps on nudges actually shown. `perSession` is in-memory (page
+     * lifetime); `perDay` is persisted in localStorage with a date rollover —
+     * best-effort by design (private browsing resets it); the costly LLM path is
+     * additionally capped server-side.
+     */
+    frequencyCap?: {
+        perSession?: number;
+        perDay?: number;
+    };
+    /** Evaluation tick, ms. Default 1000. Zero network per tick. */
+    tickMs?: number;
+    /** Storage backend for persisted governance state. Default `localStorage`. */
+    storage?: StorageLike;
+    /** Storage key for persisted governance state. Default `"ago_proactive"`. */
+    storageKey?: string;
+    /** Tuning of the signal detectors (rage-click window, throttles…). */
+    signals?: SignalCollectorTuning;
+    /**
+     * Local demos and tests ONLY: bypass the remote kill-switch. When set, the
+     * `GET /config` fetch is skipped and the kill-switch takes this value.
+     * Leave unset in production — the tenant admin controls the feature, and
+     * the evaluate endpoint stays gated server-side regardless.
+     */
+    enabledOverride?: boolean;
+}
+
+/** A declarative proactive trigger. */
+export declare interface ProactiveTrigger {
+    /** Stable id, used for cooldowns, dismissal memory, and analytics. */
+    id: string;
+    /** Conjunction of matchers (see {@link ProactiveTriggerWhen}). */
+    when: ProactiveTriggerWhen;
+    /**
+     * Min time between two firings of this trigger (persisted across reloads).
+     * A firing is the moment the trigger passes the gates — including an agent
+     * evaluation that decides NOT to intervene, so a persistent condition can't
+     * hammer the evaluate endpoint. Default 60 000.
+     */
+    cooldownMs?: number;
+    /**
+     * `'agent'` asks the backend's fast-LLM second filter whether (and how) to
+     * intervene; a `static` object shows the given message with no network call.
+     */
+    intervene: "agent" | {
+        type: "static";
+        message: string;
+        action?: NudgeAction;
+    };
+    /**
+     * What the agent should help with. Sent to the evaluate endpoint, and used to
+     * pre-seed the chat turn when the user accepts the nudge.
+     */
+    goal?: string;
+    /**
+     * User-voice line used to OPEN the conversation when the user accepts this
+     * nudge and no conversation exists yet — a hidden kickoff cannot start one
+     * (the backend rejects it). Sent as a visible user message, so write it in
+     * the app's language ("Oui, aidez-moi à choisir !"). When a conversation is
+     * already open, the SDK sends a hidden meta kickoff instead and this field
+     * is unused. Without it, accepting with no open conversation skips the chat
+     * pre-seed (the nudge action still runs).
+     */
+    kickoff?: string;
+    /**
+     * How long a dismissal of this trigger's nudge suppresses it (persisted).
+     * Default 24h.
+     */
+    resurfaceAfterMs?: number;
+}
+
+/**
+ * Conditions of a proactive trigger. Pure conjunction: EVERY specified matcher
+ * must pass against the current {@link SignalsSnapshot}. Numeric fields are
+ * `>=` thresholds.
+ */
+declare interface ProactiveTriggerWhen {
+    /**
+     * Route pattern the current pathname must match. Supports the SDK's route
+     * styles: exact (`/billing`), `:param` segments (`/users/:id`), single-segment
+     * wildcards (`/a/*` / `/b`), and a trailing `/*` that matches one or more
+     * remaining segments (`/dossier/*`).
+     */
+    route?: string;
+    /** Min time since the last user activity, ms. */
+    idleMs?: number;
+    /** Min time spent on the current route, ms. */
+    dwellMs?: number;
+    /**
+     * Partial deep match against the registered page state (funnel step,
+     * filters…). Every key present here must deep-match the live value.
+     */
+    pageState?: Partial<Record<string, unknown>>;
+    /** Min rage-click bursts on the current route. */
+    rageClicks?: number;
+    /** Min A→B→A→B route oscillations this session. */
+    routeBounces?: number;
+    /** Per-field minimum error counts (field NAME → min count). */
+    fieldErrors?: Record<string, number>;
+}
+
 /**
  * Hook run before a paused turn is resumed, so the app controls WHEN the
  * continuation fires (e.g. wait for the destination page to mount after a
@@ -1174,6 +1586,54 @@ declare interface SendMessageOptions {
     clientFunctionsMode?: ClientFunctionsMode;
 }
 
+/** Tuning knobs for the collector's detectors. All optional. */
+declare interface SignalCollectorTuning {
+    /** Min gap between heavy activity work (route checks, notifications), ms. Default 250. */
+    activityThrottleMs?: number;
+    /** Rage click: clicks needed to count a burst. Default 3. */
+    rageClickCount?: number;
+    /** Rage click: max time between first and last click of a burst, ms. Default 1000. */
+    rageClickWindowMs?: number;
+    /** Rage click: max radius between clicks of a burst, px. Default 24. */
+    rageClickRadiusPx?: number;
+    /** Max routes kept in the recent-route sequence. Default 10. */
+    maxRecentRoutes?: number;
+    /** Max typed signals kept in the ring buffer. Default 50. */
+    maxSignals?: number;
+}
+
+/**
+ * Aggregated view of the current friction state. Registered as a dynamic
+ * context provider (key `friction_signals`) so it rides along as
+ * `client_context` on every message, and sent as `signals` to the proactive
+ * evaluate endpoint.
+ */
+declare interface SignalsSnapshot {
+    /** Current pathname. */
+    route: string;
+    /** Time spent on the current route, ms. */
+    dwellMs: number;
+    /** Time since the last user activity (pointer/key/scroll/touch), ms. */
+    idleMs: number;
+    /** Rage-click bursts detected on the current route. */
+    rageClicks: number;
+    /**
+     * A→B→A→B route oscillations detected in the recent route sequence. Rolling
+     * session counter (cross-route by nature); trigger cooldowns and dismissal
+     * memory keep it from re-firing forever.
+     */
+    routeBounces: number;
+    /** App-pushed field error counters (field NAME → count), current route only. */
+    fieldErrors: Record<string, number>;
+    /** Most recent pathnames, oldest first (bounded). */
+    recentRoutes: string[];
+    /**
+     * Merged `AgoStateControl.get()` snapshot of the registered page-state
+     * controls (funnel step, filters…), or `null` when none are registered.
+     */
+    pageState: Record<string, unknown> | null;
+}
+
 /**
  * SSE stream chunk data
  */
@@ -1217,6 +1677,9 @@ declare interface SSEChunkData {
     waiting_tool_call_ids?: string[];
 }
 
+/** The slice of the Web Storage API that {@link createStore} relies on. */
+declare type StorageLike = Pick<Storage, "getItem" | "setItem">;
+
 /**
  * A minimal observable store: one value, synchronous subscriptions, and
  * optional persistence via {@link PersistOptions} (localStorage by default).
@@ -1307,6 +1770,58 @@ export declare function useAgo(config: UseAgoOptions | null): {
     isReady: boolean;
 };
 
+/**
+ * A live, normalized feed of what the agent is doing — navigations, state
+ * changes, forms, confirmations, status, progress — plus the controls to
+ * approve/reject/submit the items that wait on the user.
+ *
+ * Client functions surface via `function:invoke` (they're filtered out of
+ * `toolCall:received`); everything else via `toolCall:received`. Reasoning is
+ * suppressed unless `includeReasoning` is set. Approvals require the client's
+ * approval gate (`AgoConfig.approvalPolicy` / `requiresApproval`, pause mode).
+ *
+ * ```tsx
+ * const { items, latest, approve, reject } = useAgoActivity({
+ *   labelFor: (i) =>
+ *     i.kind === "navigation" ? routeLabels[i.arguments?.page as string] : undefined,
+ * });
+ * ```
+ */
+export declare function useAgoActivity(options?: UseAgoActivityOptions): UseAgoActivityResult;
+
+export declare interface UseAgoActivityOptions {
+    /** The AGO client. If omitted, reads from AgoProvider context. */
+    client?: AgoClient;
+    /**
+     * Include the model's `reasoning` items in the feed. Off by default — the
+     * chain-of-thought is noisy for an activity display.
+     */
+    includeReasoning?: boolean;
+    /**
+     * Override the default label for an item. Return a string to replace it, or
+     * `undefined` to keep the default. Use this to map route names / function
+     * names to friendly copy, e.g. `navigateToPage` → "Navigating to Products".
+     */
+    labelFor?: (item: AgoActivityItem) => string | undefined;
+}
+
+export declare interface UseAgoActivityResult {
+    /** Time-ordered activity for the current/most-recent turn. */
+    items: AgoActivityItem[];
+    /** The most recent item — handy for a collapsed "latest action" line. */
+    latest?: AgoActivityItem;
+    /** True while any item is waiting on the user (approval or form). */
+    isAwaitingApproval: boolean;
+    /** Approve an awaiting item (client function or confirmation). */
+    approve: (id: string) => Promise<void>;
+    /** Reject an awaiting item (client function or confirmation). */
+    reject: (id: string) => Promise<void>;
+    /** Submit form data for a `form` item. */
+    submitForm: (id: string, values: Record<string, unknown>) => Promise<void>;
+    /** Drop all items (e.g. when starting a new conversation). */
+    clear: () => void;
+}
+
 /**
  * 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`.
@@ -1421,6 +1936,11 @@ export declare interface UseAgoFunctionOptions {
      * `Infinity` disables the guard for this function.
      */
     maxResultBytes?: number;
+    /**
+     * Require explicit user approval before this function runs (pause mode only).
+     * See `AgoConfig.approvalPolicy`.
+     */
+    requiresApproval?: boolean;
 }
 
 /**
@@ -1634,4 +2154,41 @@ export declare interface UseMessagesResult {
  */
 export declare function useOptionalAgoClient(): AgoClient | null;
 
+/**
+ * Consume proactive nudges (see `createAgoProactive` / `AgoConfig.proactive`).
+ * Receiving a nudge marks it as shown (impression tracking + frequency caps),
+ * so only render ONE consumer of this hook per nudge surface — or use the
+ * prebuilt `<AgoNudge />`.
+ *
+ * ```tsx
+ * const { nudge, accept, dismiss } = useProactiveNudge({
+ *   onExpand: () => setChatOpen(true),
+ * });
+ * if (!nudge) return null;
+ * return <MyToast text={nudge.message} onAccept={accept} onClose={dismiss} />;
+ * ```
+ */
+export declare function useProactiveNudge(options?: UseProactiveNudgeOptions): UseProactiveNudgeResult;
+
+export declare interface UseProactiveNudgeOptions {
+    /** The AGO client instance. If omitted, reads from AgoProvider context. */
+    client?: AgoClient;
+    /**
+     * Called after `accept()` when the nudge should expand into the chat (it
+     * came from `intervene: 'agent'` or carries a `goal`). The SDK has already
+     * pre-seeded the conversation with a hidden kickoff message at this point;
+     * use this to open your chat UI (widget, panel…).
+     */
+    onExpand?: (nudge: ProactiveNudgeInstance) => void;
+}
+
+export declare interface UseProactiveNudgeResult {
+    /** The active nudge, or `null` when none is ready. */
+    nudge: ProactiveNudgeInstance | null;
+    /** Accept the nudge: run its action, seed the chat when relevant, clear it. */
+    accept: () => Promise<void>;
+    /** Dismiss the nudge (suppresses its trigger, see the governor). */
+    dismiss: () => void;
+}
+
 export { }