@useago/sdk 1.5.6 → 1.7.0

package/dist/react.d.cts

@@ -1,4 +1,6 @@
 import { default as default_2 } from 'react';
+import { ForwardRefExoticComponent } from 'react';
+import { RefAttributes } from 'react';
 
 export declare interface ActivityEntry {
     ts: number;
@@ -112,6 +114,10 @@ declare class AgoClient {
     private config;
     /** Conversations already warned about an empty reply (one warning each). */
     private warnedEmptyConversations;
+    /** Whether the placeholder-mode page-data warning has already been logged. */
+    private warnedPageDataPlaceholder;
+    /** `readPageData` companions this SDK registered, so cleanup only removes its own. */
+    private pageDataCompanions;
     /** Paused turns awaiting auto-resume, keyed by assistant message id. */
     private pendingResumes;
     /**
@@ -122,6 +128,20 @@ declare class AgoClient {
     private pendingApprovals;
     /** App-provided gate deciding WHEN a paused turn resumes (see {@link registerResumeGate}). */
     private resumeGate;
+    /** The turn currently streaming, or `null` when the client is idle. */
+    private activeTurn;
+    /**
+     * A turn that closed as `WAITING_CLIENT` and has not resumed yet. There is no
+     * open stream in that window, but the turn is still live for the user, so it
+     * stays stoppable (see {@link stop}).
+     */
+    private pausedTurn;
+    /**
+     * Turns stopped while they were paused on client functions. A resume may
+     * already be queued (or waiting on the resume gate) at that point; this drops
+     * it, so a stopped turn is never restarted.
+     */
+    private stoppedTurnIds;
     /**
      * Proactive-mode controller, set when the client was created with
      * `proactive` options or when `createAgoProactive(client, opts)` was called.
@@ -133,7 +153,53 @@ declare class AgoClient {
      * Send a message and receive a streaming response
      */
     sendMessage(content: string, options?: SendMessageOptions): Promise<AgoMessage>;
+    /**
+     * Fire the streaming request, returning `null` when the user stopped before
+     * the response came back. Any other failure ends the turn and propagates, so
+     * a real error still reaches the caller.
+     */
+    private sendRequest;
     private processSSEResponse;
+    /**
+     * Stop the turn that is generating right now: closes the stream so the UI
+     * stops immediately, and tells the backend to stop generating.
+     *
+     * Both halves matter. Closing the stream alone does NOT stop the agent — it
+     * keeps running and the full answer reappears the next time the conversation
+     * is loaded. The backend unwinds at its next safe point (any tool already
+     * running finishes, no further tool or reasoning round starts), keeps the text
+     * produced so far and finalizes the message as `CANCELED`.
+     *
+     * The in-flight `sendMessage` / `continueMessage` promise resolves normally
+     * with that partial message (it does not reject), `message:complete` fires
+     * with status `CANCELED`, then `message:stopped`.
+     *
+     * ```ts
+     * // "Stop" button
+     * stopButton.onclick = () => void client.stop();
+     * ```
+     *
+     * Returns the backend's verdict, or `null` when nothing was generating or the
+     * stop landed before the message had an id (the stream is still closed).
+     */
+    stop(): Promise<StopMessageResult | null>;
+    /**
+     * Ask the backend to stop a specific in-flight turn, without touching any
+     * local stream. Idempotent — stopping a finished turn answers
+     * `{ status: "not_running" }` rather than failing. Most apps want
+     * {@link stop} instead; use this to stop a turn started elsewhere (e.g. one
+     * still running after a page reload, found via `getConversation`).
+     */
+    stopMessage(messageId: string): Promise<StopMessageResult>;
+    /** Whether a turn is generating right now (i.e. {@link stop} has something to stop). */
+    isGenerating(): boolean;
+    /** Open a new turn, replacing any bookkeeping left by the previous one. */
+    private beginTurn;
+    private endTurn;
+    /** POST the stop for a turn, once, never letting the failure escape. */
+    private postStopForTurn;
+    /** The message a caller gets back when the stop beat the response. */
+    private buildStoppedMessage;
     private resolveClientFunctionsMode;
     /**
      * Register a gate deciding WHEN a paused turn resumes. The SDK still decides
@@ -361,13 +427,38 @@ declare class AgoClient {
      *   },
      * ]);
      * ```
+     *
+     * Pass `opts.data` and the agent also gets back **what the page now shows**,
+     * as the result of its own call, instead of having to wait for the next
+     * message's context. That also registers a read-only `readPageData`
+     * companion. See {@link AgoPageDataSource}.
      */
     registerPageStateFunction(controls: AgoStateControl[], opts?: AgoPageStateOptions): void;
     /**
-     * Unregister a page state function and its dynamic context provider.
-     * Mirror of unregistering `navigateToPage`.
+     * Unregister a page state function, its `readPageData` companion, and its
+     * dynamic context provider. Mirror of unregistering `navigateToPage`.
      */
     unregisterPageStateFunction(functionName?: string): void;
+    /**
+     * Size ceiling for a page snapshot, before the envelope is accounted for.
+     * Read at call time, not at registration, so `updateConfig` moves it.
+     */
+    private pageDataBudget;
+    /** Bytes the non-`data` part of the result costs, `data` included as `null`. */
+    private envelopeBytes;
+    /**
+     * Wait for the page to stop reloading, then read the snapshot. `get` and
+     * `isLoading` are re-read from `source` on every tick so a re-render that
+     * swaps the closures (without re-registering) is picked up mid-wait.
+     */
+    private readPageData;
+    /**
+     * The snapshot only reaches the agent inside the same turn in pause mode,
+     * where the SDK submits the tool result and resumes. In placeholder mode the
+     * turn is already over, so a `data` source looks broken from the outside:
+     * say so once rather than let the integrator hunt for an SDK bug.
+     */
+    private warnIfPlaceholderMode;
     /**
      * Register or update a piece of client-side context.
      * This context is sent with every message so the AI understands the user's situation.
@@ -535,6 +626,18 @@ declare interface AgoClientEvents {
         conversationId: string;
         messageId: string;
     };
+    /**
+     * The user stopped the turn (`client.stop()`): the stream was closed and the
+     * backend was told to stop generating. Always fires, so this is the event to
+     * finalize a UI on. When there was an answer to keep, a `message:complete`
+     * carrying it with status `CANCELED` fires first; there is none when the stop
+     * landed before the backend named the message (`messageId` is then an empty
+     * string) or when the stopped turn was paused on client functions.
+     */
+    "message:stopped": {
+        conversationId: string;
+        messageId: string;
+    };
     "message:error": {
         error: string;
         /** Stable error code (see configuration.md#error-codes) when the failure was an AgoError. */
@@ -768,6 +871,80 @@ export declare interface AgoNudgeProps {
     className?: string;
 }
 
+/**
+ * What the page currently displays, returned to the agent as the *result* of
+ * `setPageState` instead of only as context on the next message.
+ *
+ * Declare it when the agent should be able to act on what its own change
+ * produced ("search for dupont" → it can say who was found).
+ *
+ * A control change usually kicks off work (a refetch, a recomputation). The SDK
+ * has to wait for that work before reading, and there are two ways to tell it
+ * when the work is done. **Prefer the first.**
+ *
+ * **1. Return a promise from `get()`** — you own the await, so the SDK is
+ * exact: it resolves when your work resolves, with no polling and no timing
+ * assumption. With TanStack Query, `ensureQueryData` gives you that promise and
+ * shares the single in-flight request with the UI:
+ *
+ * ```ts
+ * useAgoPageState(controls, {
+ *   data: {
+ *     description: "The users matching the current filters.",
+ *     get: () => queryClient.ensureQueryData({
+ *       queryKey: ["users", filters],
+ *       queryFn: fetchUsers,
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * **2. Declare `isLoading`** — for data you cannot get a promise for. The SDK
+ * polls it instead, which is a heuristic: the flag has to be up within ~100 ms
+ * of the change or the SDK concludes the page settled and reads the previous
+ * rows. Fine for a query library that flips `isFetching` on render, wrong for a
+ * debounced fetch.
+ *
+ * ```ts
+ * const { data: users, isFetching } = useQuery({ queryKey: ["users", filters], queryFn: fetchUsers });
+ *
+ * useAgoPageState(controls, {
+ *   data: {
+ *     description: "The users matching the current filters.",
+ *     get: () => users ?? [],
+ *     // isFetching, NOT isLoading: a background refetch must count as loading,
+ *     // otherwise the agent reads the rows from the previous search.
+ *     isLoading: () => isFetching,
+ *   },
+ * });
+ * ```
+ */
+export declare interface AgoPageDataSource<T = unknown> {
+    /** What this data is, for the LLM: "The users matching the current filters." */
+    description: string;
+    /**
+     * The snapshot handed back to the agent.
+     *
+     * Return a promise and the SDK awaits it: that promise resolving *is* the
+     * signal that the work the change triggered has finished, so nothing is
+     * guessed. It is bounded by `settleTimeoutMs`.
+     */
+    get: () => T | Promise<T>;
+    /**
+     * True while the page is (re)loading this data. Only needed when `get()`
+     * cannot return a promise. The SDK polls it every 50 ms and treats two
+     * consecutive `false` readings as settled, so a flag raised more than ~100 ms
+     * after the change is missed and the agent reads stale rows.
+     */
+    isLoading?: () => boolean;
+    /**
+     * Size ceiling for the returned snapshot, in bytes. Defaults to the client's
+     * `maxFunctionResultBytes`. Over the ceiling the snapshot keeps the first
+     * whole items that fit; `success` and `applied` are never dropped.
+     */
+    maxResultBytes?: number;
+}
+
 /**
  * Options for {@link AgoClient.registerPageStateFunction}.
  */
@@ -779,6 +956,23 @@ export declare interface AgoPageStateOptions {
      * {@link AgoConfig.approvalPolicy} — pause mode only. Defaults to `false`.
      */
     requiresApproval?: boolean;
+    /**
+     * Declare what the page displays so `setPageState` returns it. Omit it and
+     * the result stays exactly `{ success, applied }`.
+     *
+     * Also registers a read-only companion function (`readPageData`, derived from
+     * `functionName`) that returns the same snapshot without touching the page.
+     *
+     * The snapshot travels only when the agent calls one of those functions: it
+     * is deliberately kept out of the `page-state:` dynamic context, which would
+     * put it in every message.
+     */
+    data?: AgoPageDataSource;
+    /**
+     * How long to wait for the page to finish reloading before reading the
+     * snapshot. Defaults to 10 000 ms; on timeout whatever is there is returned.
+     */
+    settleTimeoutMs?: number;
 }
 
 /**
@@ -866,7 +1060,18 @@ export declare interface AgoStateControl<T = unknown> {
 export declare const ChatInput: default_2.FC<ChatInputProps>;
 
 export declare interface ChatInputProps {
-    onSend: (message: string, files?: File[]) => void;
+    /**
+     * Send the message. The composer clears immediately so the UI feels instant,
+     * so resolving to `false` means "that send failed" and puts the text (and any
+     * attachments) back rather than losing what the user typed.
+     */
+    onSend: (message: string, files?: File[]) => void | boolean | Promise<void | boolean>;
+    /**
+     * Stop the turn being generated. When provided, the send button becomes an
+     * enabled Stop button for as long as `disabled` is true (i.e. while the agent
+     * is answering).
+     */
+    onStop?: () => void;
     disabled?: boolean;
     placeholder?: string;
     allowFiles?: boolean;
@@ -876,7 +1081,24 @@ export declare interface ChatInputProps {
 /**
  * Pre-built chat widget component
  */
-export declare const ChatWidget: default_2.FC<ChatWidgetProps>;
+export declare const ChatWidget: ForwardRefExoticComponent<ChatWidgetProps & RefAttributes<ChatWidgetHandle>>;
+
+/** Imperative handle exposed via `ref`. */
+export declare interface ChatWidgetHandle {
+    /**
+     * Expand the sheet to full screen.
+     *
+     * Only the presentation is gated on a compact viewport: off-compact (or with
+     * the sheet disabled) nothing moves on screen, but the state still changes and
+     * `onStateChange` still fires. Guard on `state` if that matters to you.
+     */
+    expand: () => void;
+    /** Collapse back to `peek`. The draft and the conversation are kept. */
+    collapse: () => void;
+    toggle: () => void;
+    /** Current sheet state. `"peek"` when the sheet is off. */
+    state: SheetState;
+}
 
 export declare interface ChatWidgetProps {
     /** The AGO client instance. If omitted, reads from AgoProvider context. */
@@ -891,6 +1113,11 @@ export declare interface ChatWidgetProps {
     placeholder?: string;
     /** Enable file attachments */
     allowFiles?: boolean;
+    /**
+     * While the agent is answering, turn the send button into a Stop button that
+     * interrupts the turn. Defaults to `true`.
+     */
+    allowStop?: boolean;
     /** Widget height */
     height?: string | number;
     /** URL of a logo to display in the header */
@@ -921,6 +1148,42 @@ export declare interface ChatWidgetProps {
         id: string;
         content: string;
     }) => void;
+    /**
+     * Present the widget as a bottom sheet on compact viewports: a slim `peek`
+     * bar pinned to the bottom edge that expands to `full`.
+     *
+     * Off by default, because it turns the widget into a fixed overlay on the
+     * host page. Pass `false` explicitly to be sure it stays off, or an object to
+     * tune the breakpoint, resting state, and the space to leave for a host
+     * bottom nav (`bottomOffset`).
+     */
+    sheet?: SheetOptions | false;
+    /**
+     * Shown next to the animated dots in the collapsed sheet while the agent is
+     * working and has not produced any text yet. Defaults to `"Thinking..."`.
+     */
+    thinkingLabel?: string;
+    /**
+     * What to show while a client function the agent called is still running.
+     * Between the call and the turn resuming the page can be busy for seconds,
+     * and a bare typing indicator says nothing about it.
+     *
+     * Map a function name to a label, or pass a function for full control.
+     * Unmapped names fall back to a prettified version of the name itself
+     * (`lookupFlavorPrices` -> "Lookup Flavor Prices"). Pass `false` to keep the
+     * plain thinking indicator.
+     *
+     * ```tsx
+     * <ChatWidget functionLabels={{ lookupFlavorPrices: "Je regarde les prix" }} />
+     * ```
+     */
+    functionLabels?: Record<string, string> | ((functionName: string, args: Record<string, unknown>) => string) | false;
+    /**
+     * Include the agent's `reasoning` steps in the activity row. On by default:
+     * they are the backend's own progress messages, and without them the row goes
+     * blank between two function calls. Set `false` to show only tool activity.
+     */
+    showReasoning?: boolean;
 }
 
 /**
@@ -1134,6 +1397,13 @@ export declare function deriveFormStatus(schema: FormCollectorSchema, values: Pa
  */
 declare type DynamicContextProvider = () => ContextEntry | null | undefined;
 
+/** Style/attribute bag for one element. Style keys are camelCase: React spreads
+ *  them directly, and the vanilla `css()` helper takes the same shape. */
+declare interface ElementProps {
+    style: Record<string, string>;
+    attrs: Record<string, string | null>;
+}
+
 export declare interface FormCollector<V = Record<string, unknown>> {
     name: string;
     /** Observable store driving the form UI (read via `useAgoStore`). */
@@ -1328,13 +1598,21 @@ declare class HttpClient {
         keepalive?: boolean;
     }): Promise<T>;
     /**
-     * Make a POST request and return the raw Response (for streaming)
+     * Make a POST request and return the raw Response (for streaming).
+     *
+     * `signal` lets the caller close the stream mid-flight (see
+     * `AgoClient.stop`); an abort is rethrown as-is rather than wrapped in an
+     * `AgoNetworkError`, so a deliberate stop is not mistaken for a network drop.
      */
-    postStream(path: string, body?: unknown): Promise<Response>;
+    postStream(path: string, body?: unknown, options?: {
+        signal?: AbortSignal;
+    }): Promise<Response>;
     /**
      * Make a POST request with FormData (for file uploads)
      */
-    postFormData(path: string, formData: FormData): Promise<Response>;
+    postFormData(path: string, formData: FormData, options?: {
+        signal?: AbortSignal;
+    }): Promise<Response>;
     private request;
     private handleErrorResponse;
 }
@@ -1393,6 +1671,13 @@ export declare interface MessageProps {
      * follow-up buttons render but are not interactive (backwards-compatible).
      */
     onFollowUpClick?: (reply: string) => void;
+    /**
+     * Show the animated dots for an answer that has not started writing yet.
+     * Defaults to `true`. Pass `false` when something else on screen already
+     * reports progress (an activity row naming the running function): the empty
+     * bubble is then dropped entirely rather than left as a blank box.
+     */
+    showStreamingDots?: boolean;
 }
 
 declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCELED"
@@ -1651,6 +1936,73 @@ declare interface SendMessageOptions {
     clientFunctionsMode?: ClientFunctionsMode;
 }
 
+/** Why a transition happened, so hosts can tell a tap from a breakpoint change. */
+export declare type SheetChangeCause = "api" | "user" | "breakpoint";
+
+export declare interface SheetOptions {
+    /**
+     * Max viewport width (px) treated as compact. A short landscape viewport
+     * (`max-height: 500px`) counts as compact too, so a phone turned sideways
+     * keeps the sheet instead of dropping to the desktop layout mid-conversation.
+     * Defaults to `768`.
+     */
+    breakpoint?: number;
+    /** State to rest in when the compact layout first applies. Defaults to `"peek"`. */
+    initialState?: SheetState;
+    /**
+     * Space to leave below the sheet, for hosts whose page already owns the bottom
+     * edge (a bottom nav, a sticky checkout bar). A number is treated as px; a
+     * string is used verbatim, so `env(safe-area-inset-bottom)` or a `calc()` both
+     * work. Defaults to `0`.
+     */
+    bottomOffset?: number | string;
+    /**
+     * Minimum height of the collapsed sheet, excluding the bottom safe area.
+     * The bar grows past it if the host's own composer styling is taller.
+     * Defaults to `152`.
+     */
+    peekHeight?: number;
+    /** Called after every state change, with what caused it. */
+    onStateChange?: (state: SheetState, cause: SheetChangeCause) => void;
+}
+
+export declare interface SheetSnapshot {
+    /** Whether the compact (phone-shaped) layout applies at all. */
+    compact: boolean;
+    /** Current resting state. Meaningless while `compact` is false. */
+    state: SheetState;
+    /**
+     * Whether the sheet currently covers the viewport. Drives scroll locking,
+     * dialog semantics, focus trapping and Escape. One predicate, so those can
+     * never drift apart. False on a desktop viewport even when open: the host page
+     * is still usable beside the widget and must stay keyboard-reachable.
+     */
+    isModal: boolean;
+    /** Props for the sheet surface itself. */
+    surface: ElementProps;
+}
+
+/**
+ * Framework-agnostic bottom-sheet controller.
+ *
+ * Owns the `peek <-> full` state machine and turns it into a **props bag**: a
+ * plain object of styles and ARIA attributes that a renderer applies however it
+ * likes. It never touches the DOM itself.
+ *
+ * That shape is deliberate. The React widget re-renders on every streamed token
+ * and re-applies its inline `style` object, so a controller that wrote to the
+ * DOM directly would be clobbered mid-stream. Returning props instead means
+ * React can spread them, the vanilla adapter can hand them to `css()`, and a Vue
+ * or Angular binding can bind them, all from one implementation.
+ *
+ * Modality is expressed, not delegated to `<dialog>`: promoting a dialog from
+ * `show()` to `showModal()` requires closing it and re-parenting into the top
+ * layer, which cancels any running transition. The renderer applies
+ * `role="dialog"` / `aria-modal` / focus trapping from `isModal` instead.
+ */
+/** The two resting states. There is no `half`: it needs a drag engine to be worth having. */
+export declare type SheetState = "peek" | "full";
+
 /** Tuning knobs for the collector's detectors. All optional. */
 declare interface SignalCollectorTuning {
     /** Min gap between heavy activity work (route checks, notifications), ms. Default 250. */
@@ -1744,6 +2096,21 @@ declare interface SSEChunkData {
     waiting_tool_call_ids?: string[];
 }
 
+/**
+ * Response of `POST /messages/{id}/stop` (see `AgoClient.stopMessage`).
+ *
+ * - `"stopping"` — the request was accepted; the turn unwinds at its next safe
+ *   point and finalizes as `CANCELED`, keeping the text produced so far.
+ * - `"not_running"` — the turn had already finished. Harmless.
+ * - `"not_supported"` — a background agent run, which cannot be stopped once
+ *   started.
+ */
+declare interface StopMessageResult {
+    status: "stopping" | "not_running" | "not_supported";
+    /** The message's status when the stop was requested. */
+    messageStatus?: MessageStatus;
+}
+
 /** The slice of the Web Storage API that {@link createStore} relies on. */
 declare type StorageLike = Pick<Storage, "getItem" | "setItem">;
 
@@ -2059,6 +2426,21 @@ export declare type UseAgoOptions = AgoConfig;
  *   },
  * ]);
  * ```
+ *
+ * Pass `opts.data` to also hand the agent what the page ends up displaying, as
+ * the result of its own `setPageState` call:
+ *
+ * ```tsx
+ * const { data: rows, isFetching } = useQuery({ queryKey: ["rows", status], queryFn: fetchRows });
+ *
+ * useAgoPageState(controls, {
+ *   data: {
+ *     description: "The rows matching the current filters.",
+ *     get: () => rows ?? [],
+ *     isLoading: () => isFetching,
+ *   },
+ * });
+ * ```
  */
 export declare function useAgoPageState(controls: AgoStateControl[], opts?: AgoPageStateOptions): void;
 
@@ -2114,6 +2496,8 @@ export declare interface UseChatResult {
     error: Error | null;
     /** Send a message */
     sendMessage: (content: string, files?: File[]) => Promise<AgoMessage | null>;
+    /** Stop the turn that is generating (the "Stop" button). No-op when idle. */
+    stop: () => Promise<void>;
     /** Clear current messages */
     clearMessages: () => void;
     /** Current conversation ID */
@@ -2223,6 +2607,13 @@ export declare interface UseMessagesResult {
     error: Error | null;
     /** Send a new message */
     sendMessage: (content: string, files?: File[]) => Promise<AgoMessage | null>;
+    /**
+     * Stop the turn that is generating: closes the stream and tells the backend
+     * to stop. The partial answer stays in the transcript as `CANCELED`. No-op
+     * when nothing is generating. Wire it to a Stop button shown while
+     * {@link isLoading} is true.
+     */
+    stop: () => Promise<void>;
     /** Clear messages */
     clearMessages: () => void;
     /** Current conversation ID */
@@ -2272,4 +2663,25 @@ export declare interface UseProactiveNudgeResult {
     dismiss: () => void;
 }
 
+/**
+ * React binding for {@link createSheetController}.
+ *
+ * Reads through `useSyncExternalStore` with a **non-compact server snapshot**, so
+ * `matchMedia` (which does not exist in Node) never runs during render. The
+ * server emits the ordinary layout and the client promotes to a sheet after
+ * hydration, instead of throwing on the server or flashing on the client.
+ *
+ * Pass `false` to opt out entirely: no sheet, no scroll lock, no focus trap, no
+ * fixed overlay on the host page.
+ */
+export declare function useSheet(options?: SheetOptions | false): UseSheetResult;
+
+export declare interface UseSheetResult {
+    /** Current state + the props bag to apply to the sheet surface. */
+    sheet: SheetSnapshot;
+    expand: (cause?: SheetChangeCause) => void;
+    collapse: (cause?: SheetChangeCause) => void;
+    toggle: (cause?: SheetChangeCause) => void;
+}
+
 export { }