@useago/sdk 1.5.6 → 1.7.0

package/dist/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("./AgoClient-DLB9icvv.cjs"),C=require("./autoContinue-CP9pJR-V.cjs"),p=require("./createConversationSession-Dqh7NXK4.cjs"),f=require("./createFormCollector-BjO3oB63.cjs"),E=require("./createMockClient-Dw-cyISN.cjs");require("./testing.cjs");const g=require("./functions-CPs7omgM.cjs");function S(e){return e}function w(e,o){return e.on("message:complete",o),()=>e.off("message:complete",o)}function y(e,o){return e.on("message:chunk",o),()=>e.off("message:chunk",o)}function v(e,o){return e.on("message:start",o),()=>e.off("message:start",o)}function F(e,o){return e.on("message:error",o),()=>e.off("message:error",o)}function b(e,o){return e.on("toolCall:received",o),()=>e.off("toolCall:received",o)}function M(e,o){return e.on("form:submitted",o),()=>e.off("form:submitted",o)}function T(e,o){return e.on("form:error",o),()=>e.off("form:error",o)}function q(e,o){return e.on("function:invoke",o),()=>e.off("function:invoke",o)}async function*I(e,o,l){const a=[];let n=null,i=!1;const c=s=>{a.push(s),n?.()},m=s=>c({type:"start",data:s}),r=s=>c({type:"chunk",data:s}),u=s=>{c({type:"complete",data:s}),i=!0,n?.()},d=s=>{c({type:"error",data:s}),i=!0,n?.()},A=s=>c({type:"toolCall",data:s});e.on("message:start",m),e.on("message:chunk",r),e.on("message:complete",u),e.on("message:error",d),e.on("toolCall:received",A),e.sendMessage(o,l).catch(()=>{i=!0,n?.()});try{for(;!i||a.length>0;)a.length>0?yield a.shift():(await new Promise(s=>{n=s}),n=null)}finally{e.off("message:start",m),e.off("message:chunk",r),e.off("message:complete",u),e.off("message:error",d),e.off("toolCall:received",A)}}function h(e){let o,l,a,n,i,c;if(typeof window<"u"&&window.AGO){const r=window.AGO;o=r.basepath,l=r.widgetId,a=r.agent||r.defaultAgent,n=r.permission,i=r.email,c=r.jwt}if(typeof document<"u"){const r=u=>document.querySelector(`meta[name="${u}"]`)?.getAttribute("content")||void 0;o=o||r("ago-base-url"),l=l||r("ago-widget-id"),a=a||r("ago-agent")||r("ago-agent-id"),n=n||r("ago-permission"),i=i||r("ago-user-email")}if(typeof document<"u"){const r=[document.body,...Array.from(document.querySelectorAll("script[data-ago-base-url]"))].filter(Boolean);for(const u of r)u&&(o=o||u.getAttribute("data-ago-base-url")||void 0,l=l||u.getAttribute("data-ago-widget-id")||void 0,a=a||u.getAttribute("data-ago-agent")||u.getAttribute("data-ago-agent-id")||void 0,n=n||u.getAttribute("data-ago-permission")||void 0,i=i||u.getAttribute("data-ago-user-email")||void 0)}o=e?.baseUrl||o,l=e?.widgetId||l,a=e?.agent||e?.defaultAgentId||a,n=e?.permission||n,i=e?.userEmail||i,c=e?.userJwt||c;const m=e?.debug;return o?{baseUrl:o,widgetId:l,agent:a,permission:n,userEmail:i,userJwt:c,debug:m}:null}function _(e){const o=h(e);if(!o)throw new t.AgoError('createAgo(): could not detect AGO configuration. Set window.AGO, add <meta name="ago-base-url">, or pass { baseUrl } explicitly.',"config_missing_base_url");return new t.AgoClient(o)}function k(e,o){return{...e,handler:o}}exports.ActivityLedger=t.ActivityLedger;exports.AgoApiError=t.AgoApiError;exports.AgoClient=t.AgoClient;exports.AgoError=t.AgoError;exports.AgoFunctionError=t.AgoFunctionError;exports.AgoNetworkError=t.AgoNetworkError;exports.AgoStreamError=t.AgoStreamError;exports.ClientContextRegistry=t.ClientContextRegistry;exports.DEFAULT_MAX_ACTIVITY_ENTRIES=t.DEFAULT_MAX_ACTIVITY_ENTRIES;exports.EventEmitter=t.EventEmitter;exports.FunctionRegistry=t.FunctionRegistry;exports.SSEHandler=t.SSEHandler;exports.SignalCollector=t.SignalCollector;exports.attachAutoContinueAfterNavigation=C.attachAutoContinueAfterNavigation;exports.autoDetectConfig=h;exports.canInlineImage=t.canInlineImage;exports.copyToClipboard=g.copyToClipboard;exports.createAgo=_;exports.createAgoProactive=t.createAgoProactive;exports.createConversationSession=p.createConversationSession;exports.createFormCollector=f.createFormCollector;exports.createMessageStream=I;exports.createMockClient=E.createMockClient;exports.createStore=t.createStore;exports.defineFunction=S;exports.deriveFormStatus=f.deriveFormStatus;exports.formatFileSize=t.formatFileSize;exports.getLocalStorage=g.getLocalStorage;exports.getUserLocation=g.getUserLocation;exports.highlightElement=g.highlightElement;exports.isStreamNetworkError=t.isStreamNetworkError;exports.loadFormCollector=f.loadFormCollector;exports.logger=t.logger;exports.matchesRoutePattern=t.matchesRoutePattern;exports.matchesWhen=t.matchesWhen;exports.onFormError=T;exports.onFormSubmitted=M;exports.onFunctionInvoke=q;exports.onMessage=w;exports.onMessageChunk=y;exports.onMessageError=F;exports.onMessageStart=v;exports.onToolCall=b;exports.openUrl=g.openUrl;exports.partialDeepMatch=t.partialDeepMatch;exports.safeAttachmentUrl=t.safeAttachmentUrl;exports.scrollToElement=g.scrollToElement;exports.setLocalStorage=g.setLocalStorage;exports.setTheme=g.setTheme;exports.showConfirmDialog=g.showConfirmDialog;exports.showNotification=g.showNotification;exports.showToast=g.showToast;exports.submitForm=g.submitForm;exports.trackEvent=g.trackEvent;exports.validateConfig=t.validateConfig;exports.withHandler=k;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("./AgoClient-BHegN73y.cjs"),p=require("./autoContinue-CP9pJR-V.cjs"),E=require("./createConversationSession-BbUUukV0.cjs"),f=require("./createFormCollector-C1ixsjV0.cjs"),S=require("./createMockClient-BSNuN3ys.cjs");require("./testing.cjs");const g=require("./functions-CPs7omgM.cjs");function w(e){return e}function y(e,o){return e.on("message:complete",o),()=>e.off("message:complete",o)}function v(e,o){return e.on("message:chunk",o),()=>e.off("message:chunk",o)}function F(e,o){return e.on("message:start",o),()=>e.off("message:start",o)}function b(e,o){return e.on("message:error",o),()=>e.off("message:error",o)}function M(e,o){return e.on("toolCall:received",o),()=>e.off("toolCall:received",o)}function T(e,o){return e.on("form:submitted",o),()=>e.off("form:submitted",o)}function q(e,o){return e.on("form:error",o),()=>e.off("form:error",o)}function I(e,o){return e.on("function:invoke",o),()=>e.off("function:invoke",o)}async function*_(e,o,l){const i=[];let n=null,a=!1;const c=s=>{i.push(s),n?.()},m=s=>c({type:"start",data:s}),r=s=>c({type:"chunk",data:s}),u=s=>{c({type:"complete",data:s}),a=!0,n?.()},d=s=>{c({type:"error",data:s}),a=!0,n?.()},A=s=>c({type:"toolCall",data:s}),h=()=>{a=!0,n?.()};e.on("message:start",m),e.on("message:chunk",r),e.on("message:complete",u),e.on("message:error",d),e.on("message:stopped",h),e.on("toolCall:received",A),e.sendMessage(o,l).catch(()=>{a=!0,n?.()});try{for(;!a||i.length>0;)i.length>0?yield i.shift():(await new Promise(s=>{n=s}),n=null)}finally{e.off("message:start",m),e.off("message:chunk",r),e.off("message:complete",u),e.off("message:error",d),e.off("message:stopped",h),e.off("toolCall:received",A)}}function C(e){let o,l,i,n,a,c;if(typeof window<"u"&&window.AGO){const r=window.AGO;o=r.basepath,l=r.widgetId,i=r.agent||r.defaultAgent,n=r.permission,a=r.email,c=r.jwt}if(typeof document<"u"){const r=u=>document.querySelector(`meta[name="${u}"]`)?.getAttribute("content")||void 0;o=o||r("ago-base-url"),l=l||r("ago-widget-id"),i=i||r("ago-agent")||r("ago-agent-id"),n=n||r("ago-permission"),a=a||r("ago-user-email")}if(typeof document<"u"){const r=[document.body,...Array.from(document.querySelectorAll("script[data-ago-base-url]"))].filter(Boolean);for(const u of r)u&&(o=o||u.getAttribute("data-ago-base-url")||void 0,l=l||u.getAttribute("data-ago-widget-id")||void 0,i=i||u.getAttribute("data-ago-agent")||u.getAttribute("data-ago-agent-id")||void 0,n=n||u.getAttribute("data-ago-permission")||void 0,a=a||u.getAttribute("data-ago-user-email")||void 0)}o=e?.baseUrl||o,l=e?.widgetId||l,i=e?.agent||e?.defaultAgentId||i,n=e?.permission||n,a=e?.userEmail||a,c=e?.userJwt||c;const m=e?.debug;return o?{baseUrl:o,widgetId:l,agent:i,permission:n,userEmail:a,userJwt:c,debug:m}:null}function k(e){const o=C(e);if(!o)throw new t.AgoError('createAgo(): could not detect AGO configuration. Set window.AGO, add <meta name="ago-base-url">, or pass { baseUrl } explicitly.',"config_missing_base_url");return new t.AgoClient(o)}function U(e,o){return{...e,handler:o}}exports.ActivityLedger=t.ActivityLedger;exports.AgoApiError=t.AgoApiError;exports.AgoClient=t.AgoClient;exports.AgoError=t.AgoError;exports.AgoFunctionError=t.AgoFunctionError;exports.AgoNetworkError=t.AgoNetworkError;exports.AgoStreamError=t.AgoStreamError;exports.ClientContextRegistry=t.ClientContextRegistry;exports.DEFAULT_MAX_ACTIVITY_ENTRIES=t.DEFAULT_MAX_ACTIVITY_ENTRIES;exports.EventEmitter=t.EventEmitter;exports.FunctionRegistry=t.FunctionRegistry;exports.SSEHandler=t.SSEHandler;exports.SignalCollector=t.SignalCollector;exports.attachAutoContinueAfterNavigation=p.attachAutoContinueAfterNavigation;exports.autoDetectConfig=C;exports.canInlineImage=t.canInlineImage;exports.copyToClipboard=g.copyToClipboard;exports.createAgo=k;exports.createAgoProactive=t.createAgoProactive;exports.createConversationSession=E.createConversationSession;exports.createFormCollector=f.createFormCollector;exports.createMessageStream=_;exports.createMockClient=S.createMockClient;exports.createStore=t.createStore;exports.defineFunction=w;exports.deriveFormStatus=f.deriveFormStatus;exports.formatFileSize=t.formatFileSize;exports.getLocalStorage=g.getLocalStorage;exports.getUserLocation=g.getUserLocation;exports.highlightElement=g.highlightElement;exports.isStreamNetworkError=t.isStreamNetworkError;exports.loadFormCollector=f.loadFormCollector;exports.logger=t.logger;exports.matchesRoutePattern=t.matchesRoutePattern;exports.matchesWhen=t.matchesWhen;exports.onFormError=q;exports.onFormSubmitted=T;exports.onFunctionInvoke=I;exports.onMessage=y;exports.onMessageChunk=v;exports.onMessageError=b;exports.onMessageStart=F;exports.onToolCall=M;exports.openUrl=g.openUrl;exports.partialDeepMatch=t.partialDeepMatch;exports.safeAttachmentUrl=t.safeAttachmentUrl;exports.scrollToElement=g.scrollToElement;exports.setLocalStorage=g.setLocalStorage;exports.setTheme=g.setTheme;exports.showConfirmDialog=g.showConfirmDialog;exports.showNotification=g.showNotification;exports.showToast=g.showToast;exports.submitForm=g.submitForm;exports.trackEvent=g.trackEvent;exports.validateConfig=t.validateConfig;exports.withHandler=U;

package/dist/index.d.cts

@@ -96,6 +96,10 @@ export 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;
     /**
@@ -106,6 +110,20 @@ export 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.
@@ -117,7 +135,53 @@ export 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
@@ -345,13 +409,38 @@ export 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.
@@ -519,6 +608,18 @@ export 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. */
@@ -744,6 +845,80 @@ export declare class AgoNetworkError extends AgoError {
     constructor(message: string, originalError?: Error | undefined);
 }
 
+/**
+ * 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}.
  */
@@ -755,6 +930,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;
 }
 
 /**
@@ -1558,6 +1750,12 @@ export declare class FunctionRegistry {
     constructor(options?: FunctionRegistryOptions);
     /** Update the client-level result-size ceiling at runtime. */
     setDefaultMaxResultBytes(bytes: number): void;
+    /**
+     * The client-level result-size ceiling in force right now. Callers that size
+     * a payload before returning it must budget against this exact number, or
+     * their careful truncation gets replaced by {@link guardResultSize}'s preview.
+     */
+    getDefaultMaxResultBytes(): number;
     /**
      * Register a function that AGO can call.
      * Accepts either a single definition object or (name, handler, schema) args.
@@ -1665,13 +1863,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;
 }
@@ -2377,6 +2583,7 @@ export declare interface SSEChunkData {
  */
 export declare class SSEHandler {
     private callbacks;
+    private options;
     private buffer;
     private message;
     private toolCalls;
@@ -2386,7 +2593,7 @@ export declare class SSEHandler {
     private answerCompleteEmitted;
     private waitingClientEmitted;
     private firedClientFunctions;
-    constructor(callbacks: SSEHandlerCallbacks);
+    constructor(callbacks: SSEHandlerCallbacks, options?: SSEHandlerOptions);
     /**
      * Process a streaming response
      */
@@ -2450,6 +2657,31 @@ declare interface SSEHandlerCallbacks {
     onError?: (error: Error) => void;
 }
 
+declare interface SSEHandlerOptions {
+    /**
+     * Signal of the fetch feeding this stream. When it fires the read rejects,
+     * and that is a deliberate stop rather than a failure: the handler keeps the
+     * text produced so far, ends the message as `CANCELED`, and does NOT call
+     * `onError`.
+     */
+    signal?: AbortSignal;
+}
+
+/**
+ * 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.
+ */
+export 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. */
 export declare type StorageLike = Pick<Storage, "getItem" | "setItem">;