@useago/sdk 1.5.2 → 1.5.3

package/dist/createFormCollector-t_fGyuTD.cjs

@@ -0,0 +1 @@
+const C=require("./AgoClient-BGkFSNZF.cjs");var W=/^[a-zA-Z0-9_-]{1,40}$/,A=n=>n==null||n==="";function S(n,e){if("anyOf"in n)return n.anyOf.some(c=>S(c,e));if("allOf"in n)return n.allOf.every(c=>S(c,e));const l=e[n.property];if(A(l))return!1;if(Array.isArray(n.value))return n.value.some(c=>String(l)===String(c));if(!n.op)return String(l)===String(n.value);const i=Number(l),a=Number(n.value);if(Number.isNaN(i)||Number.isNaN(a))return!1;switch(n.op){case">=":return i>=a;case"<=":return i<=a;case">":return i>a;case"<":return i<a;default:return C.logger.warn(`Unknown requiredWhen op "${n.op}"; treating as not required.`),!1}}function h(n,e){const l=n.properties??{},i=new Set;for(const c of n.required??[]){const d=l[c]?.requiredWhen;(!d||S(d,e))&&i.add(c)}for(const[c,d]of Object.entries(l))d.requiredWhen&&S(d.requiredWhen,e)&&i.add(c);const a=[...i].filter(c=>A(e[c]));return{missing:a,complete:a.length===0}}function B(n){const e={};for(const[l,i]of Object.entries(n.properties??{}))e[l]={type:i.type,...i.description!=null&&{description:i.description},...i.enum&&{enum:i.enum},...i.default!==void 0&&{default:i.default}};return{type:"object",properties:e,required:[]}}function V(n){const{name:e,description:l,schema:i}=n;if(!W.test(e))throw new Error(`Invalid form collector name "${e}": must match ${W} (it becomes the update_/submit_ function names).`);const a=typeof n.submit=="string"?n.submit?{via:"client",url:n.submit}:!1:n.submit??!1;n.autoSubmit===!0&&!a&&C.logger.warn(`FormCollector "${e}": autoSubmit is ignored because no submit target is configured.`);const c=(n.autoSubmit??!0)&&!!a,d=i.properties??{},$=t=>{const r={};for(const[o,s]of Object.entries(t)){const u=d[o];if(u)if(s==null)r[o]=s;else if(u.type==="number"||u.type==="integer"){const f=typeof s=="number"?s:Number(s);r[o]=Number.isNaN(f)?s:f}else u.type==="boolean"?r[o]=typeof s=="boolean"?s:s==="true"?!0:s==="false"?!1:!!s:r[o]=s}return r},N=n.initialValues??{},m=C.createStore({values:N,submitted:!1}),w=t=>{const r=m.get(),o={...r,values:{...r.values,...t}};return m.set(o),o};let b=null;const k=(t,r)=>{b?.emitFormEvent("form:error",{name:e,values:t,error:r})};let p=null;const I=async()=>{const{values:t}=m.get(),{complete:r,missing:o}=h(i,t);if(!r)return{ok:!1,missing:o};if(!a)return{ok:!1,error:"No submit target configured for this form collector."};const s=t;try{let u;if(a.via==="client")if("handler"in a)u=await a.handler(s);else{const f=await fetch(a.url,{method:"POST",headers:{"Content-Type":"application/json"},credentials:"include",body:JSON.stringify(s)});if(!f.ok){const j=`Submit failed: HTTP ${f.status}`;return k(s,j),{ok:!1,error:j}}u=await f.json().catch(()=>{})}else{if(!b)return{ok:!1,error:"Backend submit requires install(client) (or useFormCollector) first."};u=await b.submitFormCollector(e,s)}return m.set({...m.get(),submitted:!0,submitResult:u}),b?.emitFormEvent("form:submitted",{name:e,values:s,result:u}),{ok:!0,result:u}}catch(u){const f=u instanceof Error?u.message:"Submit failed";return C.logger.error(`FormCollector "${e}" submit failed:`,u),k(s,f),{ok:!1,error:f}}},F=()=>p||(p=(async()=>{try{return await I()}finally{p=null}})(),p),q=async()=>{if(!c||!a)return null;const{values:t,submitted:r}=m.get();return r||!h(i,t).complete?null:F()},O={name:`update_${e}`,description:`Fill or update fields of the "${e}" form. ${l} Pass any subset of fields; call it repeatedly to fill the form as the user provides information. Returns the current values and which required fields are still missing.`,parameters:B(i),handler:async t=>{const r=w($(t)),{missing:o}=h(i,r.values),s=await q();return s?s.ok?{ok:!0,values:r.values,missing:o,submitted:!0}:{ok:!0,values:r.values,missing:o,submitted:!1,submitError:s.error}:{ok:!0,values:r.values,missing:o}}},y=[O];a&&!c&&y.push({name:`submit_${e}`,description:`Submit the completed "${e}" form. Only call this once every required field is collected and the user has confirmed. If fields are missing it returns them instead of submitting.`,parameters:{type:"object",properties:{}},handler:()=>F()});const D="client__",_=a?`submit_${e}`:null,R=t=>{const r=t.functionName??t.toolName;if(r)return r.startsWith(D)?r.slice(8):r},x=t=>{let r={...N},o=!1;for(const s of t){const u=R(s);u===O.name?s.arguments&&(r={...r,...$(s.arguments)}):_&&u===_&&s.status?.toLowerCase()==="done"&&(o=!0)}m.set({values:r,submitted:o})},g=`form:${e}`,v=`${g}:definition`,P=()=>({name:`Form definition: ${e}`,description:`${l} Some fields are conditionally required; the requiredWhen field in the schema tells you when each becomes required. The form schema is the following: ${JSON.stringify(i)}.`,stable:!0}),T=()=>{const{values:t,submitted:r}=m.get(),{missing:o,complete:s}=h(i,t),u=a?c?" The form is submitted automatically as soon as every required field is filled, so there is no submit function to call.":` When nothing is missing and the user confirms, call submit_${e}.`:"",f=r?`The "${e}" form has been submitted.`:`You are currently collecting information from the user to fill the "${e}" form.`;return{name:`Form: ${e}`,description:`${f} The form's schema and field requirements are in the "${v}" client context. Call update_${e} with any fields the user provides; ask only for what is still missing.${u}`,data:{values:t,missing:o,complete:s,submitted:r}}},E=t=>{x((t.messages??[]).flatMap(r=>r.toolCalls??[]))};return{name:e,store:m,functions:y,contextKey:g,contextProvider:T,definitionContextKey:v,definitionContextProvider:P,install:t=>{b=t;for(const o of y)t.register(o);t.addDynamicContext(v,P),t.addDynamicContext(g,T);const r=m.subscribe(()=>t.notifyContextChanged());return t.on("conversation:loaded",E),()=>{r();for(const o of y)t.unregisterFunction(o.name);t.removeDynamicContext(g),t.removeDynamicContext(v),t.off("conversation:loaded",E),b===t&&(b=null)}},hydrate:x,submit:F,getValues:()=>m.get().values,setValues:t=>{w($(t)),q()},reset:()=>{m.set({values:N,submitted:!1})},getStatus:()=>h(i,m.get().values)}}async function L(n,e){const l=await n.getFormCollector(e.name);return V({name:l.name,description:e.description??l.description,schema:e.schema??l.schema,submit:e.submit??l.submit,initialValues:e.initialValues,autoSubmit:e.autoSubmit??l.autoSubmit})}Object.defineProperty(exports,"createFormCollector",{enumerable:!0,get:function(){return V}});Object.defineProperty(exports,"deriveFormStatus",{enumerable:!0,get:function(){return h}});Object.defineProperty(exports,"loadFormCollector",{enumerable:!0,get:function(){return L}});

package/dist/createMockClient-Br0TWgLO.js

@@ -0,0 +1,97 @@
+function v(g = {}) {
+  const { overrides: u = {} } = g, a = {
+    id: "mock-msg-1",
+    conversationId: "mock-conv-1",
+    content: "Mock response",
+    role: "assistant",
+    status: "DONE",
+    createdAt: /* @__PURE__ */ new Date()
+  }, l = {
+    id: "mock-conv-1",
+    title: "Mock Conversation",
+    lastMessageDate: /* @__PURE__ */ new Date()
+  }, o = /* @__PURE__ */ new Map(), c = [], m = {
+    sendMessage: async () => a,
+    continueMessage: async () => a,
+    resumePendingClientFunctions: async () => null,
+    registerResumeGate: () => () => {
+    },
+    getConversations: async () => [l],
+    getConversation: async () => l,
+    getMessages: async () => [a],
+    submitToolCallForm: async () => ({ status: "completed" }),
+    confirmToolCall: async () => {
+    },
+    rejectToolCall: async () => {
+    },
+    submitFeedback: async () => {
+    },
+    registerFunction: () => {
+    },
+    unregisterFunction: () => !0,
+    getRegisteredFunctions: () => [],
+    executeClientFunction: async () => {
+    },
+    getContextSnapshot: () => null,
+    notifyContextChanged: () => {
+    },
+    setContext: () => {
+    },
+    removeContext: () => !0,
+    addDynamicContext: () => {
+    },
+    removeDynamicContext: () => !0,
+    registerNavigationFunction: () => {
+    },
+    unregisterNavigationFunction: () => {
+    },
+    getConfiguredAgent: () => {
+    },
+    getHttp: () => ({
+      get: async () => ({}),
+      post: async () => ({})
+    }),
+    emitProactiveEvent: (e, t) => {
+      const n = o.get(e);
+      n && [...n].forEach((s) => s(t));
+    },
+    on: (e, t) => {
+      o.has(e) || o.set(e, /* @__PURE__ */ new Set()), o.get(e).add(t);
+    },
+    off: (e, t) => {
+      o.get(e)?.delete(t);
+    },
+    once: (e, t) => {
+      const n = (...s) => {
+        o.get(e)?.delete(n), t(...s);
+      };
+      o.has(e) || o.set(e, /* @__PURE__ */ new Set()), o.get(e).add(n);
+    },
+    waitFor: (e, t) => new Promise((n, s) => {
+      let r;
+      const d = (f) => {
+        r && clearTimeout(r), o.get(e)?.delete(d), n(f);
+      };
+      o.has(e) || o.set(e, /* @__PURE__ */ new Set()), o.get(e).add(d), t?.timeout && (r = setTimeout(() => {
+        o.get(e)?.delete(d), s(/* @__PURE__ */ new Error(`waitFor("${e}") timed out after ${t.timeout}ms`));
+      }, t.timeout));
+    }),
+    updateConfig: () => {
+    },
+    destroy: () => {
+      o.clear();
+    },
+    ...u
+  }, i = {};
+  for (const [e, t] of Object.entries(m)) i[e] = (...n) => (c.push({
+    method: e,
+    args: n
+  }), t(...n));
+  return i.proactive = null, i.__calls = c, i.__callsFor = (e) => c.filter((t) => t.method === e), i.__emitEvent = (e, t) => {
+    const n = o.get(e);
+    n && [...n].forEach((s) => s(t));
+  }, i;
+}
+export {
+  v as t
+};

package/dist/createMockClient-BwNLPjeT.cjs

@@ -0,0 +1 @@
+function C(u={}){const{overrides:g={}}=u,a={id:"mock-msg-1",conversationId:"mock-conv-1",content:"Mock response",role:"assistant",status:"DONE",createdAt:new Date},l={id:"mock-conv-1",title:"Mock Conversation",lastMessageDate:new Date},o=new Map,r=[],m={sendMessage:async()=>a,continueMessage:async()=>a,resumePendingClientFunctions:async()=>null,registerResumeGate:()=>()=>{},getConversations:async()=>[l],getConversation:async()=>l,getMessages:async()=>[a],submitToolCallForm:async()=>({status:"completed"}),confirmToolCall:async()=>{},rejectToolCall:async()=>{},submitFeedback:async()=>{},registerFunction:()=>{},unregisterFunction:()=>!0,getRegisteredFunctions:()=>[],executeClientFunction:async()=>{},getContextSnapshot:()=>null,notifyContextChanged:()=>{},setContext:()=>{},removeContext:()=>!0,addDynamicContext:()=>{},removeDynamicContext:()=>!0,registerNavigationFunction:()=>{},unregisterNavigationFunction:()=>{},getConfiguredAgent:()=>{},getHttp:()=>({get:async()=>({}),post:async()=>({})}),emitProactiveEvent:(e,t)=>{const n=o.get(e);n&&[...n].forEach(s=>s(t))},on:(e,t)=>{o.has(e)||o.set(e,new Set),o.get(e).add(t)},off:(e,t)=>{o.get(e)?.delete(t)},once:(e,t)=>{const n=(...s)=>{o.get(e)?.delete(n),t(...s)};o.has(e)||o.set(e,new Set),o.get(e).add(n)},waitFor:(e,t)=>new Promise((n,s)=>{let c;const d=f=>{c&&clearTimeout(c),o.get(e)?.delete(d),n(f)};o.has(e)||o.set(e,new Set),o.get(e).add(d),t?.timeout&&(c=setTimeout(()=>{o.get(e)?.delete(d),s(new Error(`waitFor("${e}") timed out after ${t.timeout}ms`))},t.timeout))}),updateConfig:()=>{},destroy:()=>{o.clear()},...g},i={};for(const[e,t]of Object.entries(m))i[e]=(...n)=>(r.push({method:e,args:n}),t(...n));return i.proactive=null,i.__calls=r,i.__callsFor=e=>r.filter(t=>t.method===e),i.__emitEvent=(e,t)=>{const n=o.get(e);n&&[...n].forEach(s=>s(t))},i}Object.defineProperty(exports,"createMockClient",{enumerable:!0,get:function(){return C}});

package/dist/devtools.d.cts

@@ -49,6 +49,12 @@ declare class AgoClient {
     private pendingApprovals;
     /** App-provided gate deciding WHEN a paused turn resumes (see {@link registerResumeGate}). */
     private resumeGate;
+    /**
+     * Proactive-mode controller, set when the client was created with
+     * `proactive` options or when `createAgoProactive(client, opts)` was called.
+     * `null` otherwise.
+     */
+    proactive: ProactiveController | null;
     constructor(config: AgoConfig);
     /**
      * Send a message and receive a streaming response
@@ -219,6 +225,14 @@ declare class AgoClient {
      * Get all registered function schemas
      */
     getRegisteredFunctions(): ClientFunctionSchema[];
+    /**
+     * Execute a registered client function locally, through the same
+     * FunctionRegistry path (result-size guard, error wrapping) as agent-invoked
+     * calls. Used by proactive nudge actions, where the user's explicit click on
+     * the action button constitutes the approval — nothing is submitted to the
+     * backend (there is no tool call to answer).
+     */
+    executeClientFunction(name: string, args: Record<string, unknown>): Promise<unknown>;
     /**
      * Register a navigation function that lets AGO navigate users to different pages.
      *
@@ -320,6 +334,9 @@ declare class AgoClient {
      */
     notifyContextChanged(): void;
     /* Excluded from this release type: emitFormEvent */
+    /* Excluded from this release type: emitProactiveEvent */
+    /* Excluded from this release type: getHttp */
+    /* Excluded from this release type: getConfiguredAgent */
     /**
      * Enable automatic capture of the current browser page (URL + title).
      * Injected as a dynamic context entry named `browser-page`.
@@ -364,6 +381,7 @@ declare class AgoClient {
      * Clean up resources
      */
     destroy(): void;
+    /* Excluded from this release type: reviveAfterDestroy */
 }
 
 /**
@@ -480,6 +498,25 @@ declare interface AgoClientEvents {
     "connection:status": {
         connected: boolean;
     };
+    /**
+     * A proactive nudge passed every governor gate and is ready to display.
+     * `useProactiveNudge` / `<AgoNudge>` consume this; custom UIs should call
+     * `client.proactive.shown(nudge)` when they render it (impression tracking
+     * + frequency caps), then `accept(nudge)` / `dismiss(nudge)`.
+     */
+    "nudge:ready": ProactiveNudgeInstance;
+    /** A nudge was displayed to the user (fires once per nudge). */
+    "nudge:shown": {
+        nudge: ProactiveNudgeInstance;
+    };
+    /** The user dismissed the nudge (its trigger is suppressed, see governor). */
+    "nudge:dismissed": {
+        nudge: ProactiveNudgeInstance;
+    };
+    /** The user accepted the nudge (its action ran / the chat is being seeded). */
+    "nudge:accepted": {
+        nudge: ProactiveNudgeInstance;
+    };
 }
 
 /**
@@ -541,6 +578,16 @@ declare interface AgoConfig {
      * with `maxResultBytes` on its definition; `Infinity` disables the guard.
      */
     maxFunctionResultBytes?: number;
+    /**
+     * Enable the proactive mode: declarative triggers evaluated client-side
+     * against friction signals (dwell/idle time, rage clicks, route bounces…)
+     * that can surface a nudge before the user opens the chat. Equivalent to
+     * calling `createAgoProactive(client, proactive)` — the resulting controller
+     * is available as `client.proactive`. Requires the tenant-level kill-switch
+     * (`GET /api/sdk/v1/config` → `proactive.enabled`) to be on; disabled by
+     * default otherwise.
+     */
+    proactive?: ProactiveOptions;
 }
 
 declare type AgoEventHandler<K extends AgoEventName> = (data: AgoClientEvents[K]) => void;
@@ -878,6 +925,43 @@ declare interface FormSchema {
     required?: string[];
 }
 
+/**
+ * HTTP client with authentication headers
+ */
+declare class HttpClient {
+    private baseUrl;
+    private headers;
+    constructor(config: AgoConfig);
+    /**
+     * Update configuration (e.g., JWT token)
+     */
+    updateConfig(config: Partial<AgoConfig>): void;
+    /**
+     * Make a GET request
+     */
+    get<T>(path: string): Promise<T>;
+    /**
+     * Make a POST request with JSON body.
+     *
+     * `keepalive: true` lets the request survive a page unload (used by the
+     * proactive event tracker's flush-on-hide — sendBeacon can't carry the auth
+     * headers, so it's a keepalive fetch instead).
+     */
+    post<T>(path: string, body?: unknown, options?: {
+        keepalive?: boolean;
+    }): Promise<T>;
+    /**
+     * Make a POST request and return the raw Response (for streaming)
+     */
+    postStream(path: string, body?: unknown): Promise<Response>;
+    /**
+     * Make a POST request with FormData (for file uploads)
+     */
+    postFormData(path: string, formData: FormData): Promise<Response>;
+    private request;
+    private handleErrorResponse;
+}
+
 export declare function initDevPanel(options: DevPanelOptions): void;
 
 declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCELED"
@@ -888,6 +972,182 @@ declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCEL
 */
 | "WAITING_CLIENT";
 
+/**
+ * Optional action attached to a nudge. Accepting a `functionName` action
+ * executes the registered client function (same `FunctionRegistry` path as
+ * agent-invoked calls); `setPageState` applies values through the registered
+ * page-state controls.
+ */
+declare type NudgeAction = {
+    label: string;
+    functionName: string;
+    arguments?: Record<string, unknown>;
+} | {
+    label: string;
+    setPageState: Record<string, unknown>;
+};
+
+/**
+ * Controller returned by {@link createAgoProactive} (also available as
+ * `client.proactive`).
+ */
+declare interface ProactiveController {
+    /** Persistently opt this browser out of proactive nudges. */
+    optOut(): void;
+    /** Undo {@link optOut}. */
+    optIn(): void;
+    isOptedOut(): boolean;
+    /**
+     * Tell the governor the user is already engaged (e.g. the chat widget is
+     * open) — nudges are suppressed while `true`. Call from the UI layer.
+     */
+    setEngaged(engaged: boolean): void;
+    /** App-pushed field error counter (field NAME only — never values). */
+    signalFieldError(fieldName: string): void;
+    /** Current aggregated friction snapshot. */
+    getSignalsSnapshot(): SignalsSnapshot;
+    /** The nudge currently occupying the single-nudge slot, if any. */
+    getActiveNudge(): ProactiveNudgeInstance | null;
+    /**
+     * Mark the nudge as displayed. Idempotent per nudge; counts it against the
+     * frequency caps, tracks the impression, and emits `nudge:shown`.
+     */
+    shown(nudge: ProactiveNudgeInstance): void;
+    /**
+     * Accept the nudge: run its action (if any), emit `nudge:accepted`, track,
+     * and — for agent nudges or nudges with a `goal` — pre-seed the chat with a
+     * hidden kickoff message so the agent starts the turn with full context.
+     */
+    accept(nudge: ProactiveNudgeInstance): Promise<void>;
+    /** Dismiss the nudge: suppress the trigger, track, emit `nudge:dismissed`. */
+    dismiss(nudge: ProactiveNudgeInstance): void;
+    /** Report a downstream conversion attributable to the nudge (analytics only). */
+    markConverted(nudge: ProactiveNudgeInstance): void;
+    /** Detach everything: listeners, timers, context provider, event flush. */
+    destroy(): void;
+}
+
+/** A concrete nudge produced by the engine, carried by every `nudge:*` event. */
+declare interface ProactiveNudgeInstance {
+    /** Client-generated uuid for this nudge instance (`client_nudge_id`). */
+    id: string;
+    triggerId: string;
+    /** `static` = configured message; `agent` = backend LLM evaluation. */
+    source: "static" | "agent";
+    message: string;
+    action?: NudgeAction;
+    goal?: string;
+    /** See {@link ProactiveTrigger.kickoff}. */
+    kickoff?: string;
+    createdAt: Date;
+    /** Server-side nudge id (agent nudges only). */
+    serverNudgeId?: string;
+}
+
+/** Options for {@link createAgoProactive} / `AgoConfig.proactive`. */
+declare interface ProactiveOptions {
+    triggers: ProactiveTrigger[];
+    /**
+     * Global caps on nudges actually shown. `perSession` is in-memory (page
+     * lifetime); `perDay` is persisted in localStorage with a date rollover —
+     * best-effort by design (private browsing resets it); the costly LLM path is
+     * additionally capped server-side.
+     */
+    frequencyCap?: {
+        perSession?: number;
+        perDay?: number;
+    };
+    /** Evaluation tick, ms. Default 1000. Zero network per tick. */
+    tickMs?: number;
+    /** Storage backend for persisted governance state. Default `localStorage`. */
+    storage?: StorageLike;
+    /** Storage key for persisted governance state. Default `"ago_proactive"`. */
+    storageKey?: string;
+    /** Tuning of the signal detectors (rage-click window, throttles…). */
+    signals?: SignalCollectorTuning;
+    /**
+     * Local demos and tests ONLY: bypass the remote kill-switch. When set, the
+     * `GET /config` fetch is skipped and the kill-switch takes this value.
+     * Leave unset in production — the tenant admin controls the feature, and
+     * the evaluate endpoint stays gated server-side regardless.
+     */
+    enabledOverride?: boolean;
+}
+
+/** A declarative proactive trigger. */
+declare interface ProactiveTrigger {
+    /** Stable id, used for cooldowns, dismissal memory, and analytics. */
+    id: string;
+    /** Conjunction of matchers (see {@link ProactiveTriggerWhen}). */
+    when: ProactiveTriggerWhen;
+    /**
+     * Min time between two firings of this trigger (persisted across reloads).
+     * A firing is the moment the trigger passes the gates — including an agent
+     * evaluation that decides NOT to intervene, so a persistent condition can't
+     * hammer the evaluate endpoint. Default 60 000.
+     */
+    cooldownMs?: number;
+    /**
+     * `'agent'` asks the backend's fast-LLM second filter whether (and how) to
+     * intervene; a `static` object shows the given message with no network call.
+     */
+    intervene: "agent" | {
+        type: "static";
+        message: string;
+        action?: NudgeAction;
+    };
+    /**
+     * What the agent should help with. Sent to the evaluate endpoint, and used to
+     * pre-seed the chat turn when the user accepts the nudge.
+     */
+    goal?: string;
+    /**
+     * User-voice line used to OPEN the conversation when the user accepts this
+     * nudge and no conversation exists yet — a hidden kickoff cannot start one
+     * (the backend rejects it). Sent as a visible user message, so write it in
+     * the app's language ("Oui, aidez-moi à choisir !"). When a conversation is
+     * already open, the SDK sends a hidden meta kickoff instead and this field
+     * is unused. Without it, accepting with no open conversation skips the chat
+     * pre-seed (the nudge action still runs).
+     */
+    kickoff?: string;
+    /**
+     * How long a dismissal of this trigger's nudge suppresses it (persisted).
+     * Default 24h.
+     */
+    resurfaceAfterMs?: number;
+}
+
+/**
+ * Conditions of a proactive trigger. Pure conjunction: EVERY specified matcher
+ * must pass against the current {@link SignalsSnapshot}. Numeric fields are
+ * `>=` thresholds.
+ */
+declare interface ProactiveTriggerWhen {
+    /**
+     * Route pattern the current pathname must match. Supports the SDK's route
+     * styles: exact (`/billing`), `:param` segments (`/users/:id`), single-segment
+     * wildcards (`/a/*` / `/b`), and a trailing `/*` that matches one or more
+     * remaining segments (`/dossier/*`).
+     */
+    route?: string;
+    /** Min time since the last user activity, ms. */
+    idleMs?: number;
+    /** Min time spent on the current route, ms. */
+    dwellMs?: number;
+    /**
+     * Partial deep match against the registered page state (funnel step,
+     * filters…). Every key present here must deep-match the live value.
+     */
+    pageState?: Partial<Record<string, unknown>>;
+    /** Min rage-click bursts on the current route. */
+    rageClicks?: number;
+    /** Min A→B→A→B route oscillations this session. */
+    routeBounces?: number;
+    /** Per-field minimum error counts (field NAME → min count). */
+    fieldErrors?: Record<string, number>;
+}
+
 /**
  * Hook run before a paused turn is resumed, so the app controls WHEN the
  * continuation fires (e.g. wait for the destination page to mount after a
@@ -920,6 +1180,54 @@ declare interface SendMessageOptions {
     clientFunctionsMode?: ClientFunctionsMode;
 }
 
+/** Tuning knobs for the collector's detectors. All optional. */
+declare interface SignalCollectorTuning {
+    /** Min gap between heavy activity work (route checks, notifications), ms. Default 250. */
+    activityThrottleMs?: number;
+    /** Rage click: clicks needed to count a burst. Default 3. */
+    rageClickCount?: number;
+    /** Rage click: max time between first and last click of a burst, ms. Default 1000. */
+    rageClickWindowMs?: number;
+    /** Rage click: max radius between clicks of a burst, px. Default 24. */
+    rageClickRadiusPx?: number;
+    /** Max routes kept in the recent-route sequence. Default 10. */
+    maxRecentRoutes?: number;
+    /** Max typed signals kept in the ring buffer. Default 50. */
+    maxSignals?: number;
+}
+
+/**
+ * Aggregated view of the current friction state. Registered as a dynamic
+ * context provider (key `friction_signals`) so it rides along as
+ * `client_context` on every message, and sent as `signals` to the proactive
+ * evaluate endpoint.
+ */
+declare interface SignalsSnapshot {
+    /** Current pathname. */
+    route: string;
+    /** Time spent on the current route, ms. */
+    dwellMs: number;
+    /** Time since the last user activity (pointer/key/scroll/touch), ms. */
+    idleMs: number;
+    /** Rage-click bursts detected on the current route. */
+    rageClicks: number;
+    /**
+     * A→B→A→B route oscillations detected in the recent route sequence. Rolling
+     * session counter (cross-route by nature); trigger cooldowns and dismissal
+     * memory keep it from re-firing forever.
+     */
+    routeBounces: number;
+    /** App-pushed field error counters (field NAME → count), current route only. */
+    fieldErrors: Record<string, number>;
+    /** Most recent pathnames, oldest first (bounded). */
+    recentRoutes: string[];
+    /**
+     * Merged `AgoStateControl.get()` snapshot of the registered page-state
+     * controls (funnel step, filters…), or `null` when none are registered.
+     */
+    pageState: Record<string, unknown> | null;
+}
+
 /**
  * SSE stream chunk data
  */
@@ -963,6 +1271,9 @@ declare interface SSEChunkData {
     waiting_tool_call_ids?: string[];
 }
 
+/** The slice of the Web Storage API that {@link createStore} relies on. */
+declare type StorageLike = Pick<Storage, "getItem" | "setItem">;
+
 /**
  * Where a completed form is sent.
  * - `"https://..."` (a bare string) — shorthand for `{ via: "client", url }`: the browser