@useago/sdk 1.4.2 → 1.4.4

package/dist/index.d.cts

@@ -50,12 +50,45 @@ export declare class AgoClient {
     private config;
     /** Conversations already warned about an empty reply (one warning each). */
     private warnedEmptyConversations;
+    /** Paused turns awaiting auto-resume, keyed by assistant message id. */
+    private pendingResumes;
+    /** App-provided gate deciding WHEN a paused turn resumes (see {@link registerResumeGate}). */
+    private resumeGate;
     constructor(config: AgoConfig);
     /**
      * Send a message and receive a streaming response
      */
     sendMessage(content: string, options?: SendMessageOptions): Promise<AgoMessage>;
     private processSSEResponse;
+    private resolveClientFunctionsMode;
+    /**
+     * Register a gate deciding WHEN a paused turn resumes. The SDK still decides
+     * *whether* (it resumes once every waiting result is submitted); the gate only
+     * delays the continue call — e.g. `useAgoAutoContinueAfterNavigation` waits for
+     * the destination page to register its page state. One gate at a time (last
+     * registration wins). Returns an unregister function.
+     */
+    registerResumeGate(gate: ResumeGate): () => void;
+    /**
+     * Resume a turn paused on client function results (`WAITING_CLIENT`).
+     *
+     * Sends the CURRENT page's registered functions and context — the page may
+     * have changed since the pause (that's the point of pausing on a navigation) —
+     * and streams the continuation through the same event pipeline as
+     * `sendMessage`, so `message:chunk` / `message:complete` (or another
+     * `message:waiting-client` for chained pauses) fire as usual.
+     *
+     * The SDK calls this automatically after submitting the waiting results; call
+     * it manually only for custom flows (e.g. after restoring a reloaded page via
+     * {@link resumePendingClientFunctions}).
+     */
+    continueMessage(messageId: string): Promise<AgoMessage>;
+    /**
+     * Record one of the two auto-resume preconditions for a paused turn and fire
+     * the resume when both are in (see {@link PendingResume}).
+     */
+    private markResumeSignal;
+    private runAutoResume;
     /**
      * Detect a reply that completed as DONE with no content and no activity —
      * today's backend answers an unknown `agent` slug with an empty 200, which
@@ -88,9 +121,25 @@ export declare class AgoClient {
      */
     getMessages(conversationId: string): Promise<AgoMessage[]>;
     /**
-     * Submit form data for a tool call
+     * Resume a turn left paused on client function results by a page reload.
+     *
+     * A paused turn (pause mode) survives a full reload: the backend keeps the
+     * assistant message in `WAITING_CLIENT` with its waiting tool calls. After
+     * restoring the conversation (`getConversation`) and re-registering the page's
+     * functions, call this: it re-executes each waiting client function through the
+     * registry, submits the results, and continues the turn.
+     *
+     * 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.
+     */
+    resumePendingClientFunctions(conversation: Conversation): Promise<AgoMessage | null>;
+    /**
+     * Submit form data for a tool call. The response's `resume` field (pause mode
+     * only) tells whether the paused turn is ready to be resumed.
      */
-    submitToolCallForm(toolCallId: string, formData: Record<string, unknown>): Promise<void>;
+    submitToolCallForm(toolCallId: string, formData: Record<string, unknown>): Promise<SubmitToolCallResult>;
     /**
      * Confirm a tool call
      */
@@ -137,7 +186,7 @@ export declare class AgoClient {
      * ```
      */
     registerFunction(definition: ClientFunctionDefinition): void;
-    registerFunction(name: string, handler: ClientFunctionHandler, schema: Omit<ClientFunctionSchema, "name">): void;
+    registerFunction(name: string, handler: ClientFunctionHandler, schema: ClientFunctionRegisterOptions): void;
     /**
      * Short alias for `registerFunction`. Also accepts an array of definitions.
      *
@@ -163,6 +212,12 @@ export declare class AgoClient {
      * the agent know *where* it is after it navigates (e.g. so auto-continuation
      * can apply page state on the destination), not just how to navigate away.
      *
+     * Routes may contain `:param` placeholders (`/users/:id`). Each distinct
+     * placeholder becomes a top-level string argument of `navigateToPage`
+     * (`{ page: "userDetail", id: "42" }`), so one route covers every detail
+     * page of an entity. Flat arguments only: nested object parameters are not
+     * reliably rendered to the model, so placeholders must not be named `page`.
+     *
      * @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
      */
@@ -330,6 +385,19 @@ export declare interface AgoClientEvents {
      */
     "message:answer-complete": AgoMessage;
     "message:complete": AgoMessage;
+    /**
+     * The turn paused on client function call(s) (pause mode): the stream closed
+     * with status `WAITING_CLIENT` instead of `DONE`. `message:complete` does NOT
+     * fire for this stream — it fires when the resumed turn concludes, so one
+     * logical turn still emits exactly one `message:complete`. The SDK submits the
+     * function results and resumes automatically; listen to this to know the agent
+     * is waiting on the page (e.g. to keep a "working…" indicator up).
+     */
+    "message:waiting-client": {
+        conversationId: string;
+        messageId: string;
+        waitingToolCallIds: string[];
+    };
     /**
      * A reply finished as `DONE` with empty content and no tool calls, client
      * functions, or follow-up replies — usually an unknown `agent` slug (the
@@ -417,6 +485,24 @@ export declare interface AgoConfig {
      * event fires regardless of this setting.
      */
     warnOnEmptyReply?: boolean;
+    /**
+     * How the agent loop treats client function calls (requires backend support):
+     * - `"placeholder"` (default): the turn continues immediately on a placeholder
+     *   result; the real result is only visible to the agent on later turns.
+     * - `"pause"`: the turn stops on client function call(s) with status
+     *   `WAITING_CLIENT`; once every result is submitted, the SDK resumes the SAME
+     *   turn via `POST /messages/{id}/continue`, so the agent sees the real results.
+     * Older backends ignore the flag, so `"pause"` degrades to legacy behavior.
+     */
+    clientFunctionsMode?: ClientFunctionsMode;
+    /**
+     * Max serialized size (bytes) of a client function result before the SDK
+     * replaces it with a flagged, truncated preview. Everything a handler
+     * returns is sent into the LLM context, so this caps runaway payloads
+     * (raw API responses, full tables). Default `50000`. Override per function
+     * with `maxResultBytes` on its definition; `Infinity` disables the guard.
+     */
+    maxFunctionResultBytes?: number;
 }
 
 /**
@@ -655,6 +741,12 @@ export declare interface ClientFunctionDefinition {
     description: string;
     parameters: ClientFunctionSchema["parameters"];
     handler: ClientFunctionHandler;
+    /**
+     * Max serialized result size in bytes before the SDK truncates it to a
+     * flagged preview (default: `AgoConfig.maxFunctionResultBytes`, 50 000).
+     * `Infinity` disables the guard for this function.
+     */
+    maxResultBytes?: number;
 }
 
 /**
@@ -669,6 +761,20 @@ export declare interface ClientFunctionInvocation {
     conversationId: string;
 }
 
+/**
+ * Schema-plus-settings object accepted when registering a function: the schema
+ * (minus `name`) and SDK-side options that are NOT sent to the backend.
+ */
+export declare type ClientFunctionRegisterOptions = Omit<ClientFunctionSchema, "name"> & {
+    /**
+     * Max serialized result size in bytes before the SDK truncates it to a
+     * flagged preview. Overrides the client-level default
+     * (`AgoConfig.maxFunctionResultBytes`, 50 000 by default). `Infinity`
+     * disables the guard for this function.
+     */
+    maxResultBytes?: number;
+};
+
 /**
  * Schema for a client-side function that AGO can call
  */
@@ -694,6 +800,9 @@ export declare interface ClientFunctionSchema {
     };
 }
 
+/** See {@link AgoConfig.clientFunctionsMode}. */
+export declare type ClientFunctionsMode = "placeholder" | "pause";
+
 /**
  * A single piece of context the client wants the LLM to know about.
  */
@@ -1163,12 +1272,16 @@ export declare interface FunctionDefinition {
  */
 export declare class FunctionRegistry {
     private functions;
+    private defaultMaxResultBytes;
+    constructor(options?: FunctionRegistryOptions);
+    /** Update the client-level result-size ceiling at runtime. */
+    setDefaultMaxResultBytes(bytes: number): void;
     /**
      * Register a function that AGO can call.
      * Accepts either a single definition object or (name, handler, schema) args.
      */
     register(definition: ClientFunctionDefinition): void;
-    register(name: string, handler: ClientFunctionHandler, schema: Omit<ClientFunctionSchema, "name">): void;
+    register(name: string, handler: ClientFunctionHandler, schema: ClientFunctionRegisterOptions): void;
     /**
      * Unregister a function
      */
@@ -1189,6 +1302,14 @@ export declare class FunctionRegistry {
      * Execute a registered function
      */
     execute(name: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Cap the size of a function result before it goes back to the backend.
+     * Everything a handler returns lands in the LLM context, so an unbounded
+     * payload (a raw API response, a full table) inflates cost and can overflow
+     * the model. Oversized results are replaced with a flagged preview so the
+     * agent knows to request less instead of receiving hundreds of KB verbatim.
+     */
+    private guardResultSize;
     /**
      * Clear all registered functions
      */
@@ -1199,6 +1320,11 @@ export declare class FunctionRegistry {
     get size(): number;
 }
 
+declare interface FunctionRegistryOptions {
+    /** Client-level default for the result-size ceiling, in bytes. */
+    maxResultBytes?: number;
+}
+
 /**
  * Client-side function types
  */
@@ -1276,7 +1402,13 @@ declare class Logger {
 
 export declare const logger: Logger;
 
-export declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCELED";
+export declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCELED"
+/**
+* The turn paused on client function call(s) (pause mode): the agent waits for
+* every waiting call to be submitted, then the turn resumes via
+* `continueMessage`. Not a final state.
+*/
+| "WAITING_CLIENT";
 
 export declare interface MockAgoClient extends AgoClient {
     /**
@@ -1384,8 +1516,21 @@ export declare interface PersistOptions {
 export declare interface RegisteredFunction {
     schema: ClientFunctionSchema;
     handler: ClientFunctionHandler;
+    /** Per-function result-size ceiling; falls back to the registry default. */
+    maxResultBytes?: number;
 }
 
+/**
+ * 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
+ * navigation). It must resolve — throwing or hanging blocks the resume; on
+ * timeout-style situations resolve anyway and let the agent conclude.
+ */
+export declare type ResumeGate = (info: {
+    conversationId: string;
+    messageId: string;
+}) => Promise<void> | void;
+
 /**
  * Allow only URL schemes that are safe to put in an `<img src>` / `<a href>`.
  * Presigned attachment URLs are `https:` and optimistic previews are `blob:`;
@@ -1417,6 +1562,8 @@ export declare interface SendMessageOptions {
      * Requires backend support for the `hidden` flag; older backends ignore it.
      */
     hidden?: boolean;
+    /** Per-message override of {@link AgoConfig.clientFunctionsMode}. */
+    clientFunctionsMode?: ClientFunctionsMode;
 }
 
 /**
@@ -1491,6 +1638,8 @@ export declare interface SSEChunkData {
     follow_up_replies?: string[];
     satisfaction_feedback?: unknown;
     ask_to_talk_to_human?: boolean;
+    /** Tool call ids still awaiting a client result, sent with the final `WAITING_CLIENT` event. */
+    waiting_tool_call_ids?: string[];
 }
 
 /**
@@ -1505,6 +1654,7 @@ export declare class SSEHandler {
     private followUpReplies;
     private isFirstChunk;
     private answerCompleteEmitted;
+    private waitingClientEmitted;
     private firedClientFunctions;
     constructor(callbacks: SSEHandlerCallbacks);
     /**
@@ -1547,6 +1697,17 @@ declare interface SSEHandlerCallbacks {
      * with the message as it stands at that moment (no `followUpReplies` yet).
      */
     onAnswerComplete?: (message: AgoMessage) => void;
+    /**
+     * The turn paused on client function call(s) (pause mode): the backend closed
+     * the stream with `status: "WAITING_CLIENT"` and the tool call ids awaiting a
+     * result. {@link onComplete} does NOT fire for this stream — the turn is not
+     * over; it resumes in a separate request once every result is submitted.
+     */
+    onWaitingClient?: (data: {
+        conversationId: string;
+        messageId: string;
+        waitingToolCallIds: string[];
+    }) => void;
     onComplete?: (message: AgoMessage) => void;
     onError?: (error: Error) => void;
 }
@@ -1602,6 +1763,21 @@ export declare type SubmitConfig<V = Record<string, unknown>> = string | {
  */
 export declare const submitForm: ClientFunctionDefinition;
 
+/**
+ * Response of `POST /tool-calls/{id}/submit`. `resume` is only present when the
+ * tool call belongs to a turn paused on client functions (pause mode): `ready`
+ * flips to `true` once ALL waiting calls of that message are submitted, meaning
+ * the turn can be resumed via `continueMessage(resume.message_id)`.
+ */
+export declare interface SubmitToolCallResult {
+    status: string;
+    result?: unknown;
+    resume?: {
+        message_id: string;
+        ready: boolean;
+    };
+}
+
 /**
  * Tool call data from SSE stream
  */

package/dist/index.d.ts

@@ -50,12 +50,45 @@ export declare class AgoClient {
     private config;
     /** Conversations already warned about an empty reply (one warning each). */
     private warnedEmptyConversations;
+    /** Paused turns awaiting auto-resume, keyed by assistant message id. */
+    private pendingResumes;
+    /** App-provided gate deciding WHEN a paused turn resumes (see {@link registerResumeGate}). */
+    private resumeGate;
     constructor(config: AgoConfig);
     /**
      * Send a message and receive a streaming response
      */
     sendMessage(content: string, options?: SendMessageOptions): Promise<AgoMessage>;
     private processSSEResponse;
+    private resolveClientFunctionsMode;
+    /**
+     * Register a gate deciding WHEN a paused turn resumes. The SDK still decides
+     * *whether* (it resumes once every waiting result is submitted); the gate only
+     * delays the continue call — e.g. `useAgoAutoContinueAfterNavigation` waits for
+     * the destination page to register its page state. One gate at a time (last
+     * registration wins). Returns an unregister function.
+     */
+    registerResumeGate(gate: ResumeGate): () => void;
+    /**
+     * Resume a turn paused on client function results (`WAITING_CLIENT`).
+     *
+     * Sends the CURRENT page's registered functions and context — the page may
+     * have changed since the pause (that's the point of pausing on a navigation) —
+     * and streams the continuation through the same event pipeline as
+     * `sendMessage`, so `message:chunk` / `message:complete` (or another
+     * `message:waiting-client` for chained pauses) fire as usual.
+     *
+     * The SDK calls this automatically after submitting the waiting results; call
+     * it manually only for custom flows (e.g. after restoring a reloaded page via
+     * {@link resumePendingClientFunctions}).
+     */
+    continueMessage(messageId: string): Promise<AgoMessage>;
+    /**
+     * Record one of the two auto-resume preconditions for a paused turn and fire
+     * the resume when both are in (see {@link PendingResume}).
+     */
+    private markResumeSignal;
+    private runAutoResume;
     /**
      * Detect a reply that completed as DONE with no content and no activity —
      * today's backend answers an unknown `agent` slug with an empty 200, which
@@ -88,9 +121,25 @@ export declare class AgoClient {
      */
     getMessages(conversationId: string): Promise<AgoMessage[]>;
     /**
-     * Submit form data for a tool call
+     * Resume a turn left paused on client function results by a page reload.
+     *
+     * A paused turn (pause mode) survives a full reload: the backend keeps the
+     * assistant message in `WAITING_CLIENT` with its waiting tool calls. After
+     * restoring the conversation (`getConversation`) and re-registering the page's
+     * functions, call this: it re-executes each waiting client function through the
+     * registry, submits the results, and continues the turn.
+     *
+     * 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.
+     */
+    resumePendingClientFunctions(conversation: Conversation): Promise<AgoMessage | null>;
+    /**
+     * Submit form data for a tool call. The response's `resume` field (pause mode
+     * only) tells whether the paused turn is ready to be resumed.
      */
-    submitToolCallForm(toolCallId: string, formData: Record<string, unknown>): Promise<void>;
+    submitToolCallForm(toolCallId: string, formData: Record<string, unknown>): Promise<SubmitToolCallResult>;
     /**
      * Confirm a tool call
      */
@@ -137,7 +186,7 @@ export declare class AgoClient {
      * ```
      */
     registerFunction(definition: ClientFunctionDefinition): void;
-    registerFunction(name: string, handler: ClientFunctionHandler, schema: Omit<ClientFunctionSchema, "name">): void;
+    registerFunction(name: string, handler: ClientFunctionHandler, schema: ClientFunctionRegisterOptions): void;
     /**
      * Short alias for `registerFunction`. Also accepts an array of definitions.
      *
@@ -163,6 +212,12 @@ export declare class AgoClient {
      * the agent know *where* it is after it navigates (e.g. so auto-continuation
      * can apply page state on the destination), not just how to navigate away.
      *
+     * Routes may contain `:param` placeholders (`/users/:id`). Each distinct
+     * placeholder becomes a top-level string argument of `navigateToPage`
+     * (`{ page: "userDetail", id: "42" }`), so one route covers every detail
+     * page of an entity. Flat arguments only: nested object parameters are not
+     * reliably rendered to the model, so placeholders must not be named `page`.
+     *
      * @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
      */
@@ -330,6 +385,19 @@ export declare interface AgoClientEvents {
      */
     "message:answer-complete": AgoMessage;
     "message:complete": AgoMessage;
+    /**
+     * The turn paused on client function call(s) (pause mode): the stream closed
+     * with status `WAITING_CLIENT` instead of `DONE`. `message:complete` does NOT
+     * fire for this stream — it fires when the resumed turn concludes, so one
+     * logical turn still emits exactly one `message:complete`. The SDK submits the
+     * function results and resumes automatically; listen to this to know the agent
+     * is waiting on the page (e.g. to keep a "working…" indicator up).
+     */
+    "message:waiting-client": {
+        conversationId: string;
+        messageId: string;
+        waitingToolCallIds: string[];
+    };
     /**
      * A reply finished as `DONE` with empty content and no tool calls, client
      * functions, or follow-up replies — usually an unknown `agent` slug (the
@@ -417,6 +485,24 @@ export declare interface AgoConfig {
      * event fires regardless of this setting.
      */
     warnOnEmptyReply?: boolean;
+    /**
+     * How the agent loop treats client function calls (requires backend support):
+     * - `"placeholder"` (default): the turn continues immediately on a placeholder
+     *   result; the real result is only visible to the agent on later turns.
+     * - `"pause"`: the turn stops on client function call(s) with status
+     *   `WAITING_CLIENT`; once every result is submitted, the SDK resumes the SAME
+     *   turn via `POST /messages/{id}/continue`, so the agent sees the real results.
+     * Older backends ignore the flag, so `"pause"` degrades to legacy behavior.
+     */
+    clientFunctionsMode?: ClientFunctionsMode;
+    /**
+     * Max serialized size (bytes) of a client function result before the SDK
+     * replaces it with a flagged, truncated preview. Everything a handler
+     * returns is sent into the LLM context, so this caps runaway payloads
+     * (raw API responses, full tables). Default `50000`. Override per function
+     * with `maxResultBytes` on its definition; `Infinity` disables the guard.
+     */
+    maxFunctionResultBytes?: number;
 }
 
 /**
@@ -655,6 +741,12 @@ export declare interface ClientFunctionDefinition {
     description: string;
     parameters: ClientFunctionSchema["parameters"];
     handler: ClientFunctionHandler;
+    /**
+     * Max serialized result size in bytes before the SDK truncates it to a
+     * flagged preview (default: `AgoConfig.maxFunctionResultBytes`, 50 000).
+     * `Infinity` disables the guard for this function.
+     */
+    maxResultBytes?: number;
 }
 
 /**
@@ -669,6 +761,20 @@ export declare interface ClientFunctionInvocation {
     conversationId: string;
 }
 
+/**
+ * Schema-plus-settings object accepted when registering a function: the schema
+ * (minus `name`) and SDK-side options that are NOT sent to the backend.
+ */
+export declare type ClientFunctionRegisterOptions = Omit<ClientFunctionSchema, "name"> & {
+    /**
+     * Max serialized result size in bytes before the SDK truncates it to a
+     * flagged preview. Overrides the client-level default
+     * (`AgoConfig.maxFunctionResultBytes`, 50 000 by default). `Infinity`
+     * disables the guard for this function.
+     */
+    maxResultBytes?: number;
+};
+
 /**
  * Schema for a client-side function that AGO can call
  */
@@ -694,6 +800,9 @@ export declare interface ClientFunctionSchema {
     };
 }
 
+/** See {@link AgoConfig.clientFunctionsMode}. */
+export declare type ClientFunctionsMode = "placeholder" | "pause";
+
 /**
  * A single piece of context the client wants the LLM to know about.
  */
@@ -1163,12 +1272,16 @@ export declare interface FunctionDefinition {
  */
 export declare class FunctionRegistry {
     private functions;
+    private defaultMaxResultBytes;
+    constructor(options?: FunctionRegistryOptions);
+    /** Update the client-level result-size ceiling at runtime. */
+    setDefaultMaxResultBytes(bytes: number): void;
     /**
      * Register a function that AGO can call.
      * Accepts either a single definition object or (name, handler, schema) args.
      */
     register(definition: ClientFunctionDefinition): void;
-    register(name: string, handler: ClientFunctionHandler, schema: Omit<ClientFunctionSchema, "name">): void;
+    register(name: string, handler: ClientFunctionHandler, schema: ClientFunctionRegisterOptions): void;
     /**
      * Unregister a function
      */
@@ -1189,6 +1302,14 @@ export declare class FunctionRegistry {
      * Execute a registered function
      */
     execute(name: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Cap the size of a function result before it goes back to the backend.
+     * Everything a handler returns lands in the LLM context, so an unbounded
+     * payload (a raw API response, a full table) inflates cost and can overflow
+     * the model. Oversized results are replaced with a flagged preview so the
+     * agent knows to request less instead of receiving hundreds of KB verbatim.
+     */
+    private guardResultSize;
     /**
      * Clear all registered functions
      */
@@ -1199,6 +1320,11 @@ export declare class FunctionRegistry {
     get size(): number;
 }
 
+declare interface FunctionRegistryOptions {
+    /** Client-level default for the result-size ceiling, in bytes. */
+    maxResultBytes?: number;
+}
+
 /**
  * Client-side function types
  */
@@ -1276,7 +1402,13 @@ declare class Logger {
 
 export declare const logger: Logger;
 
-export declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCELED";
+export declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCELED"
+/**
+* The turn paused on client function call(s) (pause mode): the agent waits for
+* every waiting call to be submitted, then the turn resumes via
+* `continueMessage`. Not a final state.
+*/
+| "WAITING_CLIENT";
 
 export declare interface MockAgoClient extends AgoClient {
     /**
@@ -1384,8 +1516,21 @@ export declare interface PersistOptions {
 export declare interface RegisteredFunction {
     schema: ClientFunctionSchema;
     handler: ClientFunctionHandler;
+    /** Per-function result-size ceiling; falls back to the registry default. */
+    maxResultBytes?: number;
 }
 
+/**
+ * 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
+ * navigation). It must resolve — throwing or hanging blocks the resume; on
+ * timeout-style situations resolve anyway and let the agent conclude.
+ */
+export declare type ResumeGate = (info: {
+    conversationId: string;
+    messageId: string;
+}) => Promise<void> | void;
+
 /**
  * Allow only URL schemes that are safe to put in an `<img src>` / `<a href>`.
  * Presigned attachment URLs are `https:` and optimistic previews are `blob:`;
@@ -1417,6 +1562,8 @@ export declare interface SendMessageOptions {
      * Requires backend support for the `hidden` flag; older backends ignore it.
      */
     hidden?: boolean;
+    /** Per-message override of {@link AgoConfig.clientFunctionsMode}. */
+    clientFunctionsMode?: ClientFunctionsMode;
 }
 
 /**
@@ -1491,6 +1638,8 @@ export declare interface SSEChunkData {
     follow_up_replies?: string[];
     satisfaction_feedback?: unknown;
     ask_to_talk_to_human?: boolean;
+    /** Tool call ids still awaiting a client result, sent with the final `WAITING_CLIENT` event. */
+    waiting_tool_call_ids?: string[];
 }
 
 /**
@@ -1505,6 +1654,7 @@ export declare class SSEHandler {
     private followUpReplies;
     private isFirstChunk;
     private answerCompleteEmitted;
+    private waitingClientEmitted;
     private firedClientFunctions;
     constructor(callbacks: SSEHandlerCallbacks);
     /**
@@ -1547,6 +1697,17 @@ declare interface SSEHandlerCallbacks {
      * with the message as it stands at that moment (no `followUpReplies` yet).
      */
     onAnswerComplete?: (message: AgoMessage) => void;
+    /**
+     * The turn paused on client function call(s) (pause mode): the backend closed
+     * the stream with `status: "WAITING_CLIENT"` and the tool call ids awaiting a
+     * result. {@link onComplete} does NOT fire for this stream — the turn is not
+     * over; it resumes in a separate request once every result is submitted.
+     */
+    onWaitingClient?: (data: {
+        conversationId: string;
+        messageId: string;
+        waitingToolCallIds: string[];
+    }) => void;
     onComplete?: (message: AgoMessage) => void;
     onError?: (error: Error) => void;
 }
@@ -1602,6 +1763,21 @@ export declare type SubmitConfig<V = Record<string, unknown>> = string | {
  */
 export declare const submitForm: ClientFunctionDefinition;
 
+/**
+ * Response of `POST /tool-calls/{id}/submit`. `resume` is only present when the
+ * tool call belongs to a turn paused on client functions (pause mode): `ready`
+ * flips to `true` once ALL waiting calls of that message are submitted, meaning
+ * the turn can be resumed via `continueMessage(resume.message_id)`.
+ */
+export declare interface SubmitToolCallResult {
+    status: string;
+    result?: unknown;
+    resume?: {
+        message_id: string;
+        ready: boolean;
+    };
+}
+
 /**
  * Tool call data from SSE stream
  */

package/dist/index.js

@@ -1,8 +1,8 @@
 import { a as h, c as A, d as y, f as C, i as E, l as S, m as b, o as v, p as F, r as M, s as I, t as k, u as T } from "./functions-CApuQZ2b.js";
-import { _ as G, a as O, c as _, d as q, f as x, g as L, h as N, l as D, m as d, n as H, o as J, p as R, r as j, s as z, t as c, u as B } from "./AgoClient-BdtuHX7k.js";
-import { i as $, n as K, r as Q, t as V } from "./createFormCollector-B4n0_diV.js";
-import { t as X } from "./createConversationSession-CWpf4u6I.js";
-import { t as Z } from "./createMockClient-d-arlmCq.js";
+import { _ as G, a as O, c as _, d as q, f as x, g as L, h as N, l as D, m as d, n as H, o as J, p as R, r as j, s as z, t as c, u as B } from "./AgoClient-Ozz2b1dQ.js";
+import { i as $, n as K, r as Q, t as V } from "./createFormCollector-F3YJfsbg.js";
+import { t as X } from "./createConversationSession-QIBN0gLx.js";
+import { t as Z } from "./createMockClient-bAZ9KBHC.js";
 import "./testing.js";
 function oe(e) {
   return e;