@useago/sdk 0.3.2 → 0.3.4

package/dist/react.d.cts

@@ -0,0 +1,999 @@
+import { default as default_2 } from 'react';
+
+/**
+ * Agent information
+ */
+export declare interface AgoAgent {
+    id: string;
+    name: string;
+    displayName?: string;
+}
+
+/**
+ * Main SDK client for AGO Chat integration
+ */
+declare class AgoClient {
+    private httpClient;
+    private functionRegistry;
+    private contextRegistry;
+    private eventEmitter;
+    private config;
+    constructor(config: AgoConfig);
+    /**
+     * Send a message and receive a streaming response
+     */
+    sendMessage(content: string, options?: SendMessageOptions): Promise<AgoMessage>;
+    private processSSEResponse;
+    private handleClientFunctionInvocation;
+    /**
+     * Get list of conversations
+     */
+    getConversations(): Promise<Conversation[]>;
+    /**
+     * Get a specific conversation with messages
+     */
+    getConversation(conversationId: string): Promise<Conversation>;
+    /**
+     * Get messages for a conversation
+     */
+    getMessages(conversationId: string): Promise<AgoMessage[]>;
+    /**
+     * Submit form data for a tool call
+     */
+    submitToolCallForm(toolCallId: string, formData: Record<string, unknown>): Promise<void>;
+    /**
+     * Confirm a tool call
+     */
+    confirmToolCall(toolCallId: string): Promise<void>;
+    /**
+     * Reject a tool call
+     */
+    rejectToolCall(toolCallId: string): Promise<void>;
+    /**
+     * Relay a completed form collector's values to a server-configured destination.
+     *
+     * Used by `createFormCollector` / `useFormCollector` in `{ via: "backend" }` mode:
+     * the browser never holds the destination URL or its secret — the backend resolves
+     * `destination` (a named, opted-in tool) and forwards the values from the server.
+     */
+    submitFormCollector(destination: string, values: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Submit feedback for a message
+     */
+    submitFeedback(messageId: string, rating: "positive" | "negative"): Promise<void>;
+    /**
+     * Register a client-side function that AGO can call.
+     * Accepts either a definition object or (name, handler, schema) args.
+     *
+     * ```ts
+     * // Single-object (preferred)
+     * client.registerFunction({
+     *   name: "lookupOrder",
+     *   description: "Look up an order",
+     *   parameters: { type: "object", properties: { id: { type: "string" } } },
+     *   handler: async (args) => fetchOrder(args.id),
+     * });
+     *
+     * // Classic 3-arg form
+     * client.registerFunction("lookupOrder", handler, schema);
+     * ```
+     */
+    registerFunction(definition: ClientFunctionDefinition): void;
+    registerFunction(name: string, handler: ClientFunctionHandler, schema: Omit<ClientFunctionSchema, "name">): void;
+    /**
+     * Short alias for `registerFunction`. Also accepts an array of definitions.
+     *
+     * ```ts
+     * client.register(lookupOrder);
+     * client.register([lookupOrder, cancelOrder]);
+     * ```
+     */
+    register(definition: ClientFunctionDefinition | ClientFunctionDefinition[]): void;
+    /**
+     * Unregister a client-side function
+     */
+    unregisterFunction(name: string): boolean;
+    /**
+     * Get all registered function schemas
+     */
+    getRegisteredFunctions(): ClientFunctionSchema[];
+    /**
+     * Register a navigation function that lets AGO navigate users to different pages.
+     * @param navigate - A callback that performs the navigation (e.g. react-router's navigate)
+     * @param routes - Map of route names to paths, with descriptions for the LLM
+     */
+    registerNavigationFunction(navigate: (path: string) => void, routes: Array<{
+        name: string;
+        path: string;
+        description: 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.
+     *
+     * ```ts
+     * client.setContext("order-page", {
+     *   name: "Order detail",
+     *   description: "User is viewing order #123",
+     *   data: { orderId: "123", status: "shipped" },
+     * });
+     * ```
+     */
+    setContext(key: string, entry: ContextEntry): void;
+    /**
+     * Remove a previously registered context entry.
+     */
+    removeContext(key: string): boolean;
+    /**
+     * Register a dynamic context provider. The callback is invoked every time
+     * a message is sent, so the AI always gets the freshest data.
+     *
+     * Use this for context that lives outside React state — global stores,
+     * refs, or computed values.
+     *
+     * ```ts
+     * client.addDynamicContext("cart", () => ({
+     *   name: "Checkout",
+     *   data: { itemCount: cart.items.length, total: cart.total },
+     * }));
+     * ```
+     */
+    addDynamicContext(key: string, provider: DynamicContextProvider): void;
+    /**
+     * Remove a dynamic context provider.
+     */
+    removeDynamicContext(key: string): boolean;
+    /**
+     * Enable automatic capture of the current browser page (URL + title).
+     * Injected as a dynamic context entry named `browser-page`.
+     */
+    enableAutoPageContext(): void;
+    /**
+     * Get the current context snapshot.
+     */
+    getContextSnapshot(): ContextSnapshot | null;
+    /**
+     * Subscribe to an event
+     */
+    on<K extends AgoEventName>(event: K, handler: AgoEventHandler<K>): void;
+    /**
+     * Unsubscribe from an event
+     */
+    off<K extends AgoEventName>(event: K, handler: AgoEventHandler<K>): void;
+    /**
+     * Subscribe to an event once — auto-unsubscribes after the first call.
+     */
+    once<K extends AgoEventName>(event: K, handler: AgoEventHandler<K>): void;
+    /**
+     * Returns a Promise that resolves the next time `event` fires.
+     *
+     * ```ts
+     * const msg = await client.waitFor("message:complete", { timeout: 10000 });
+     * ```
+     */
+    waitFor<K extends AgoEventName>(event: K, options?: {
+        timeout?: number;
+    }): Promise<AgoClientEvents[K]>;
+    /**
+     * Update client configuration
+     */
+    updateConfig(config: Partial<AgoConfig>): void;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}
+
+/**
+ * SDK Events
+ */
+declare interface AgoClientEvents {
+    "message:start": {
+        conversationId: string;
+        messageId: string;
+    };
+    "message:chunk": {
+        content: string;
+        conversationId: string;
+        messageId: string;
+    };
+    "message:complete": AgoMessage;
+    "message:error": {
+        error: string;
+        conversationId?: string;
+        messageId?: string;
+    };
+    "toolCall:received": ToolCallData;
+    "toolCall:form": ToolCallData;
+    "function:invoke": ClientFunctionInvocation;
+    "function:result": {
+        invocationId: string;
+        result: unknown;
+        error?: string;
+    };
+    "connection:status": {
+        connected: boolean;
+    };
+}
+
+/**
+ * SDK Configuration
+ */
+export declare interface AgoConfig {
+    /** API base URL (e.g., https://YOUR-DOMAIN.useago.com) */
+    baseUrl: string;
+    /** Widget ID (X-Widget-Id header). Auto-generated if not provided. */
+    widgetId?: string;
+    /** Default agent (id or slug) for new conversations. Shorthand for `defaultAgentId`. */
+    agent?: string;
+    /** Default agent ID for new conversations. Prefer `agent`. */
+    defaultAgentId?: string;
+    /** Permission name to apply to all requests (sent as `X-Widget-Permission`). Mirrors the widget's `window.AGO.permission`. */
+    permission?: string;
+    /** User email for identification */
+    userEmail?: string;
+    /** JWT token for authenticated users */
+    userJwt?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+
+/**
+ * Top-level declarative configuration for the `AgoProvider`.
+ *
+ * - `tools` — full function definitions to expose to the AI app-wide
+ * - `helpers` — map of pre-built helper name → handler override (or `true` for default)
+ * - `pageContext` — `"auto"` enables automatic URL/title capture
+ */
+export declare interface AgoDeclarativeConfig {
+    tools?: ClientFunctionDefinition[];
+    helpers?: Record<string, ClientFunctionHandler | true>;
+    pageContext?: "auto" | "manual";
+}
+
+declare type AgoEventHandler<K extends AgoEventName> = (data: AgoClientEvents[K]) => void;
+
+declare type AgoEventName = keyof AgoClientEvents;
+
+/**
+ * Message from AGO
+ */
+export declare interface AgoMessage {
+    id: string;
+    conversationId: string;
+    content: string;
+    role: "user" | "assistant";
+    status: MessageStatus;
+    agent?: AgoAgent;
+    sources?: AgoSource[];
+    toolCalls?: ToolCallData[];
+    followUpReplies?: string[];
+    createdAt: Date;
+}
+
+/**
+ * Provides an AgoClient to all descendant components via React context.
+ *
+ * ```tsx
+ * // Minimal setup
+ * <AgoProvider baseUrl="https://YOUR-DOMAIN.useago.com">
+ *   <App />
+ * </AgoProvider>
+ *
+ * // Declarative config — tools, helpers, page context
+ * <AgoProvider
+ *   baseUrl="https://YOUR-DOMAIN.useago.com"
+ *   tools={[lookupOrder, cancelOrder]}
+ *   helpers={{
+ *     showToast: (args) => toast(args.message as string),
+ *     copyToClipboard: true, // use default handler
+ *   }}
+ *   pageContext="auto"
+ * >
+ *   <App />
+ * </AgoProvider>
+ *
+ * // With a pre-built client (useful for testing)
+ * <AgoProvider client={myClient}>
+ *   <App />
+ * </AgoProvider>
+ * ```
+ */
+export declare const AgoProvider: default_2.FC<AgoProviderProps>;
+
+export declare type AgoProviderProps = {
+    children: default_2.ReactNode;
+} & AgoDeclarativeConfig & (({
+    client: AgoClient;
+} & Partial<Record<keyof AgoConfig, never>>) | ({
+    client?: never;
+} & AgoConfig));
+
+export declare interface AgoRoute {
+    name: string;
+    path: string;
+    description: string;
+}
+
+/**
+ * Knowledge source citation
+ */
+export declare interface AgoSource {
+    id: string;
+    title: string;
+    url?: string;
+}
+
+/**
+ * Chat input component with send button
+ */
+export declare const ChatInput: default_2.FC<ChatInputProps>;
+
+export declare interface ChatInputProps {
+    onSend: (message: string, files?: File[]) => void;
+    disabled?: boolean;
+    placeholder?: string;
+    allowFiles?: boolean;
+    className?: string;
+}
+
+/**
+ * Pre-built chat widget component
+ */
+export declare const ChatWidget: default_2.FC<ChatWidgetProps>;
+
+export declare interface ChatWidgetProps {
+    /** The AGO client instance. If omitted, reads from AgoProvider context. */
+    client?: AgoClient;
+    /** Initial conversation ID */
+    conversationId?: string;
+    /** Widget title */
+    title?: string;
+    /** Welcome message shown when no messages */
+    welcomeMessage?: string;
+    /** Input placeholder */
+    placeholder?: string;
+    /** Enable file attachments */
+    allowFiles?: boolean;
+    /** Widget height */
+    height?: string | number;
+    /** URL of a logo to display in the header */
+    logoUrl?: string;
+    /** Show the agent name above assistant messages. Defaults to `false`. */
+    showAgentName?: boolean;
+    /**
+     * Conversational forms the agent can fill and submit during the chat. Each
+     * config is installed as a {@link createFormCollector} (its `update_<name>` /
+     * `submit_<name>` functions + dynamic context) for the lifetime of the widget.
+     */
+    forms?: CreateFormCollectorOptions[];
+    /**
+     * How clicking a suggested follow-up reply behaves. Defaults to sending the
+     * reply as a new user message. Pass a handler to override, or `false` to
+     * render the suggestions as non-interactive.
+     */
+    onFollowUpClick?: ((reply: string) => void) | false;
+    /** Additional CSS class */
+    className?: string;
+    /** Callback when a message is sent */
+    onMessageSent?: (content: string) => void;
+    /** Callback when a message is received */
+    onMessageReceived?: (message: {
+        id: string;
+        content: string;
+    }) => void;
+}
+
+/**
+ * Single-object function definition — combines name, schema, and handler.
+ *
+ * ```ts
+ * const fn = defineFunction({
+ *   name: "lookupOrder",
+ *   description: "Look up an order by ID",
+ *   parameters: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+ *   handler: async (args) => fetchOrder(args.id as string),
+ * });
+ * client.registerFunction(fn);
+ * ```
+ */
+declare interface ClientFunctionDefinition {
+    name: string;
+    description: string;
+    parameters: ClientFunctionSchema["parameters"];
+    handler: ClientFunctionHandler;
+}
+
+/**
+ * Function handler type
+ */
+declare type ClientFunctionHandler = (args: Record<string, unknown>) => Promise<unknown> | unknown;
+
+declare interface ClientFunctionInvocation {
+    invocationId: string;
+    functionName: string;
+    arguments: Record<string, unknown>;
+    conversationId: string;
+}
+
+/**
+ * Schema for a client-side function that AGO can call
+ */
+declare interface ClientFunctionSchema {
+    /** Function name (must be unique) */
+    name: string;
+    /** Description for the LLM to understand when to call this function */
+    description: string;
+    /** JSON Schema for function parameters */
+    parameters: {
+        type: "object";
+        properties: Record<string, {
+            type: string;
+            description?: string;
+            enum?: string[];
+            default?: unknown;
+        }>;
+        required?: string[];
+    };
+}
+
+/**
+ * A single piece of context the client wants the LLM to know about.
+ */
+declare interface ContextEntry {
+    /** Human-readable label (e.g. "Order detail", "Current user") */
+    name?: string;
+    /** Short description of what this context represents */
+    description?: string;
+    /** Arbitrary structured data the AI should know about */
+    data?: Record<string, unknown>;
+}
+
+/**
+ * Serialised client context sent with each message.
+ */
+declare interface ContextSnapshot {
+    /** All active context entries keyed by their registration key */
+    entries: Record<string, ContextEntry>;
+}
+
+/**
+ * Conversation/Thread
+ */
+export declare interface Conversation {
+    id: string;
+    title: string;
+    lastMessageDate: Date;
+    messages?: AgoMessage[];
+}
+
+/**
+ * Wire one schema into a conversational form: an observable store, an
+ * `update_<name>` client function the agent calls to fill fields, a dynamic-context
+ * provider that tells the agent what's still missing, and an optional submit.
+ *
+ * ```ts
+ * const order = createFormCollector({
+ *   name: "order",
+ *   description: "The order the user wants to place",
+ *   schema: {
+ *     type: "object",
+ *     properties: { product: { type: "string" }, quantity: { type: "number" } },
+ *     required: ["product", "quantity"],
+ *   },
+ *   submit: { via: "client", url: "/api/orders" },
+ * });
+ * order.install(client);
+ * order.store.subscribe((s) => render(s));
+ * ```
+ */
+export declare function createFormCollector<V = Record<string, unknown>>(options: CreateFormCollectorOptions<V>): FormCollector<V>;
+
+export declare interface CreateFormCollectorOptions<V = Record<string, unknown>> {
+    /** Short identifier; becomes the `update_<name>` / `submit_<name>` function names. */
+    name: string;
+    /** What the form is, for the LLM. */
+    description: string;
+    /** The single source of truth for the form's fields. */
+    schema: FormCollectorSchema;
+    /** How the completed form is submitted. Default: `false` (collect only). */
+    submit?: SubmitConfig<V>;
+    /** Pre-filled values. */
+    initialValues?: Partial<V>;
+}
+
+/**
+ * Create a mock AgoClient for testing. Works with any framework.
+ *
+ * ```ts
+ * import { createMockClient } from "@useago/sdk/testing";
+ *
+ * const mock = createMockClient();
+ * mock.__emitEvent("message:complete", someMessage);
+ * expect(mock.__callsFor("sendMessage")).toHaveLength(1);
+ * ```
+ */
+export declare function createMockClient(options?: MockAgoClientOptions): MockAgoClient;
+
+/**
+ * A function that returns a fresh context entry on demand.
+ * Evaluated every time a message is sent — use it to pull data from stores,
+ * refs, or any source that isn't captured by React state.
+ */
+declare type DynamicContextProvider = () => ContextEntry | null | undefined;
+
+export declare interface FormCollector<V = Record<string, unknown>> {
+    name: string;
+    /** Observable store driving the form UI (read via `useAgoStore`). */
+    store: Store<FormCollectorState<V>>;
+    /** Client functions to register: `[update]` or `[update, submit]`. */
+    functions: ClientFunctionDefinition[];
+    /** Dynamic-context key under which the form state is exposed. */
+    contextKey: string;
+    /** Dynamic-context provider — re-read on every message. */
+    contextProvider: () => ContextEntry;
+    /** Register the functions + dynamic context on a client. Returns an uninstall fn. */
+    install: (client: AgoClient) => () => void;
+    /** Submit the form now (e.g. from a UI button). Blocks until required fields are filled. */
+    submit: () => Promise<FormSubmitResult>;
+    getValues: () => Partial<V>;
+    setValues: (patch: Partial<V>) => void;
+    reset: () => void;
+}
+
+/**
+ * JSON-schema shape of a form's fields — identical to a client function's
+ * `parameters`, so one schema feeds the store, the update function, and the
+ * dynamic context with no second type.
+ */
+export declare type FormCollectorSchema = ClientFunctionSchema["parameters"];
+
+/** Live state held in the collector's store. */
+export declare interface FormCollectorState<V = Record<string, unknown>> {
+    /** Field values collected so far. */
+    values: Partial<V>;
+    /** Required field names still empty. */
+    missing: string[];
+    /** True when no required field is missing. */
+    complete: boolean;
+    /** True once a submit succeeded. */
+    submitted: boolean;
+}
+
+declare interface FormField {
+    type: "string" | "number" | "boolean" | "array";
+    title?: string;
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+}
+
+/**
+ * Form schema for tool calls requiring user input
+ */
+declare interface FormSchema {
+    type: "object";
+    properties: Record<string, FormField>;
+    required?: string[];
+}
+
+/** Result returned by `submit()` / the generated `submit_<name>` function. */
+export declare interface FormSubmitResult {
+    ok: boolean;
+    missing?: string[];
+    result?: unknown;
+    error?: string;
+}
+
+/**
+ * Renders markdown content with GitHub-flavored markdown support
+ * (tables, task lists, strikethrough, autolinks) and inline-styled
+ * element renderers. Used by {@link Message} but exported so consumers
+ * building a custom chat UI can render assistant content the same way.
+ */
+export declare const Markdown: default_2.FC<MarkdownProps>;
+
+export declare interface MarkdownProps {
+    /** Raw markdown string to render. */
+    content: string;
+}
+
+export declare const Message: default_2.FC<MessageProps>;
+
+export declare interface MessageProps {
+    message: AgoMessage;
+    className?: string;
+    /** Show the agent name above assistant messages. Defaults to `false`. */
+    showAgentName?: boolean;
+    /**
+     * Called when the user clicks a suggested follow-up reply. When omitted the
+     * follow-up buttons render but are not interactive (backwards-compatible).
+     */
+    onFollowUpClick?: (reply: string) => void;
+}
+
+declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCELED";
+
+declare interface MockAgoClient extends AgoClient {
+    /**
+     * Simulate a server-pushed event.
+     * ```ts
+     * mock.__emitEvent("message:complete", { id: "1", content: "hi", ... });
+     * ```
+     */
+    __emitEvent<K extends AgoEventName>(event: K, data: AgoClientEvents[K]): void;
+    /**
+     * All recorded method calls: `[methodName, ...args][]`
+     */
+    __calls: Array<{
+        method: string;
+        args: unknown[];
+    }>;
+    /**
+     * Get calls for a specific method.
+     */
+    __callsFor(method: string): Array<{
+        method: string;
+        args: unknown[];
+    }>;
+}
+
+declare interface MockAgoClientOptions {
+    overrides?: Partial<Record<string, MockFn>>;
+}
+
+declare type MockFn = (...args: any[]) => any;
+
+/**
+ * Options for sending a message
+ */
+declare interface SendMessageOptions {
+    /** Existing conversation ID */
+    conversationId?: string;
+    /** Override default agent */
+    agentId?: string;
+    /** File attachments */
+    files?: File[];
+}
+
+/**
+ * A minimal observable store: one value, synchronous subscriptions, and
+ * optional persistence via {@link PersistOptions} (localStorage by default).
+ *
+ * ```ts
+ * const store = createStore({ count: 0 });
+ * store.subscribe((state) => save(state));
+ * store.set({ count: 1 }); // listeners fire synchronously
+ *
+ * const cart = createStore({ items: [] }, { key: "cart" }); // persisted
+ * ```
+ */
+declare interface Store<T> {
+    /** Current state. */
+    get(): T;
+    /** Replace the state and notify subscribers synchronously. */
+    set(next: T): void;
+    /** Register a listener; returns a function that removes it. */
+    subscribe(listener: (state: T) => void): () => void;
+}
+
+/**
+ * Where a completed form is sent.
+ * - `"https://..."` (a bare string) — shorthand for `{ via: "client", url }`: the browser
+ *   POSTs the values to that URL.
+ * - `{ via: "client", url }` — same, written out.
+ * - `{ via: "client", handler }` — the browser runs your own submit logic.
+ * - `{ via: "backend", destination }` — the browser relays the values to the backend,
+ *   which forwards them to the server-configured destination (URL + secret stay server-side).
+ * - `false` — collect only, no submit function.
+ */
+export declare type SubmitConfig<V = Record<string, unknown>> = string | {
+    via: "client";
+    url: string;
+} | {
+    via: "client";
+    handler: (values: V) => Promise<unknown> | unknown;
+} | {
+    via: "backend";
+    destination: string;
+} | false;
+
+/**
+ * Tool call data from SSE stream
+ */
+export declare interface ToolCallData {
+    id: string;
+    type: ToolCallType;
+    status: string;
+    toolName: string;
+    toolDisplayName?: string;
+    message?: string;
+    formSchema?: FormSchema;
+    data?: Record<string, unknown>;
+    functionName?: string;
+    arguments?: Record<string, unknown>;
+}
+
+declare type ToolCallType = "form" | "confirmation_input" | "status_message" | "progress_indicator" | "client_function" | "reasoning" | "mcp_ui_resource";
+
+/**
+ * Hook to create and manage an AgoClient instance
+ */
+export declare function useAgo(config: UseAgoOptions): UseAgoResult;
+
+/**
+ * Returns the AgoClient from the nearest AgoProvider.
+ * Throws if used outside of an AgoProvider.
+ */
+export declare function useAgoClient(): AgoClient;
+
+/**
+ * Declaratively expose a piece of context to the AI agent with every message.
+ *
+ * Accepts either:
+ * - An **object** — sent as-is on every message (re-registered when it changes).
+ *   Use for data that already lives in React state.
+ * - A **function** — called lazily at each message send, so the AI always gets
+ *   the freshest value. Use for data outside React state (global stores, refs,
+ *   computed values).
+ *
+ * A unique key is auto-generated per component instance via `useId()`. Pass an
+ * explicit key as second argument to share context across components or
+ * reference it from elsewhere.
+ *
+ * ```tsx
+ * // Static object — captured at render time
+ * function OrderPage({ order }) {
+ *   useAgoContext({
+ *     name: "Order detail",
+ *     description: "The user is viewing a specific order",
+ *     data: { orderId: order.id, status: order.status },
+ *   });
+ * }
+ *
+ * // Dynamic function — evaluated at each sendMessage
+ * function App() {
+ *   const storeRef = useRef(reduxStore);
+ *   useAgoContext(() => {
+ *     const state = storeRef.current.getState();
+ *     return { name: "App shell", data: { userId: state.auth.userId } };
+ *   });
+ * }
+ *
+ * // With an explicit key
+ * useAgoContext({ name: "Sidebar filter", data: { filter } }, "sidebar-filter");
+ * ```
+ */
+export declare function useAgoContext(entry: ContextEntry, key?: string): void;
+
+export declare function useAgoContext(provider: DynamicContextProvider, key?: string): void;
+
+/**
+ * Declaratively register a client-side function with the AGO agent.
+ * Automatically unregisters on unmount and re-registers when deps change.
+ *
+ * Accepts either a full definition object (preferred) or classic (name, options) args.
+ *
+ * ```tsx
+ * // Preferred — pass the whole definition
+ * useAgoFunction({
+ *   name: "showToast",
+ *   description: "Show a notification to the user",
+ *   parameters: { type: "object", properties: { message: { type: "string" } } },
+ *   handler: async (args) => { toast(args.message); return { shown: true }; },
+ * });
+ *
+ * // Or reuse a pre-defined function
+ * const lookupOrder = defineFunction({ name: "lookupOrder", ... });
+ * useAgoFunction(lookupOrder);
+ *
+ * // Classic form
+ * useAgoFunction("showToast", { description: "...", parameters: {...}, handler: async (args) => ... });
+ * ```
+ */
+export declare function useAgoFunction(definition: ClientFunctionDefinition): void;
+
+export declare function useAgoFunction(name: string, options: UseAgoFunctionOptions): void;
+
+export declare interface UseAgoFunctionOptions {
+    description: string;
+    parameters: {
+        type: "object";
+        properties: Record<string, {
+            type: string;
+            description?: string;
+            enum?: string[];
+            default?: unknown;
+        }>;
+        required?: string[];
+    };
+    handler: ClientFunctionHandler;
+}
+
+/**
+ * Declaratively register navigation routes with the AGO agent.
+ * Wraps `registerNavigationFunction` with React lifecycle management.
+ *
+ * ```tsx
+ * const navigate = useNavigate();
+ * useAgoNavigation(navigate, [
+ *   { name: "dashboard", path: "/dashboard", description: "Main dashboard" },
+ *   { name: "settings", path: "/settings", description: "User settings" },
+ * ]);
+ * ```
+ */
+export declare function useAgoNavigation(navigate: (path: string) => void, routes: AgoRoute[]): void;
+
+export declare interface UseAgoOptions extends AgoConfig {
+}
+
+export declare interface UseAgoResult {
+    /** The AGO client instance */
+    client: AgoClient;
+    /** Whether the client is ready */
+    isReady: boolean;
+}
+
+/**
+ * Read a framework-agnostic AGO store (`createStore`) reactively in React.
+ *
+ * Re-renders the component whenever the store's value changes. Mutate the store
+ * via `store.set(...)`, not the value returned here.
+ *
+ * ```tsx
+ * const cart = createStore({ items: [] as string[] });
+ *
+ * function CartBadge() {
+ *   const { items } = useAgoStore(cart);
+ *   return <span>{items.length}</span>;
+ * }
+ * ```
+ */
+export declare function useAgoStore<T>(store: Store<T>): T;
+
+/**
+ * All-in-one hook for building a custom chat UI.
+ * Composes useMessages + useConversation.
+ *
+ * ```tsx
+ * const { messages, sendMessage, conversations, selectConversation } = useChat();
+ * ```
+ */
+export declare function useChat(options?: UseChatOptions): UseChatResult;
+
+export declare interface UseChatOptions {
+    /** AgoClient instance. If omitted, reads from AgoProvider context. */
+    client?: AgoClient;
+    /** Initial conversation ID to load */
+    conversationId?: string;
+    /** Auto-load conversation list on mount (default: true) */
+    autoLoad?: boolean;
+}
+
+export declare interface UseChatResult {
+    /** Messages in the current conversation */
+    messages: AgoMessage[];
+    /** Whether a message is being sent/streamed */
+    isLoading: boolean;
+    /** Current error */
+    error: Error | null;
+    /** Send a message */
+    sendMessage: (content: string, files?: File[]) => Promise<AgoMessage | null>;
+    /** Clear current messages */
+    clearMessages: () => void;
+    /** Current conversation ID */
+    conversationId: string | undefined;
+    /** All conversations */
+    conversations: Conversation[];
+    /** Currently selected conversation */
+    currentConversation: Conversation | null;
+    /** Whether conversations are loading */
+    isConversationsLoading: boolean;
+    /** Select a conversation by ID */
+    selectConversation: (conversationId: string) => Promise<void>;
+    /** Start a new conversation */
+    startNewConversation: () => void;
+    /** Refresh conversations list */
+    refreshConversations: () => Promise<void>;
+}
+
+/**
+ * Hook to manage conversations
+ */
+export declare function useConversation({ client: clientProp, autoLoad, }?: UseConversationOptions): UseConversationResult;
+
+export declare interface UseConversationOptions {
+    /** The AGO client instance. If omitted, reads from AgoProvider context. */
+    client?: AgoClient;
+    /** Auto-load conversations on mount */
+    autoLoad?: boolean;
+}
+
+export declare interface UseConversationResult {
+    /** List of conversations */
+    conversations: Conversation[];
+    /** Currently selected conversation */
+    currentConversation: Conversation | null;
+    /** Whether conversations are loading */
+    isLoading: boolean;
+    /** Current error, if any */
+    error: Error | null;
+    /** Select a conversation */
+    selectConversation: (conversationId: string) => Promise<void>;
+    /** Clear current conversation (start new) */
+    startNewConversation: () => void;
+    /** Refresh conversations list */
+    refreshConversations: () => Promise<void>;
+}
+
+/**
+ * React wiring for {@link createFormCollector}: registers the collector's client
+ * functions + dynamic context on mount, removes them on unmount, and returns the
+ * live store state.
+ *
+ * The collector is recreated only when `name`, the schema, or the submit target
+ * changes. Keep the schema and submit object stable (declare them outside render
+ * or memoize them) so an inline `handler` isn't captured stale.
+ *
+ * ```tsx
+ * const order = useFormCollector({
+ *   name: "order",
+ *   description: "The order the user wants to place",
+ *   schema: {
+ *     type: "object",
+ *     properties: { product: { type: "string" }, quantity: { type: "number" } },
+ *     required: ["product", "quantity"],
+ *   },
+ *   submit: { via: "backend", destination: "order_webhook" },
+ * });
+ *
+ * return (
+ *   <div>
+ *     {order.state.missing.length > 0
+ *       ? `Still need: ${order.state.missing.join(", ")}`
+ *       : "Ready to submit"}
+ *   </div>
+ * );
+ * ```
+ */
+export declare function useFormCollector<V = Record<string, unknown>>(options: CreateFormCollectorOptions<V>): UseFormCollectorResult<V>;
+
+export declare interface UseFormCollectorResult<V = Record<string, unknown>> extends FormCollector<V> {
+    /** Live form state from the collector's store — re-renders on every change. */
+    state: FormCollectorState<V>;
+}
+
+/**
+ * Hook to manage messages in a conversation
+ */
+export declare function useMessages({ client: clientProp, conversationId: initialConversationId, }?: UseMessagesOptions): UseMessagesResult;
+
+export declare interface UseMessagesOptions {
+    /** The AGO client instance. If omitted, reads from AgoProvider context. */
+    client?: AgoClient;
+    /** Conversation ID to load messages for */
+    conversationId?: string;
+}
+
+export declare interface UseMessagesResult {
+    /** List of messages */
+    messages: AgoMessage[];
+    /** Whether a message is being sent */
+    isLoading: boolean;
+    /** Current error, if any */
+    error: Error | null;
+    /** Send a new message */
+    sendMessage: (content: string, files?: File[]) => Promise<AgoMessage | null>;
+    /** Clear messages */
+    clearMessages: () => void;
+    /** Current conversation ID */
+    conversationId: string | undefined;
+}
+
+/**
+ * Returns the AgoClient from context, or null if no provider exists.
+ * Use this when client access is optional.
+ */
+export declare function useOptionalAgoClient(): AgoClient | null;
+
+export { }