@useago/sdk 0.3.4 → 0.4.2

package/dist/devtools.d.ts

@@ -31,6 +31,12 @@ declare class AgoClient {
      * Get a specific conversation with messages
      */
     getConversation(conversationId: string): Promise<Conversation>;
+    /**
+     * Map the backend's snake_case `tool_call_data` entries onto the camelCase
+     * {@link ToolCallData} shape used everywhere else in the SDK. Mirrors
+     * `SSEHandler.parseToolCall` so persisted and streamed tool calls match.
+     */
+    private static mapPersistedToolCalls;
     /**
      * Get messages for a conversation
      */
@@ -141,6 +147,13 @@ declare class AgoClient {
      * Remove a dynamic context provider.
      */
     removeDynamicContext(key: string): boolean;
+    /**
+     * Broadcast that the client-side context changed by emitting `context:changed`
+     * with the fresh snapshot. The context-mutating methods call this automatically;
+     * stateful helpers whose context lives in a store (e.g. `createFormCollector`)
+     * call it when their store updates so observers like the dev panel stay live.
+     */
+    notifyContextChanged(): void;
     /**
      * Enable automatic capture of the current browser page (URL + title).
      * Injected as a dynamic context entry named `browser-page`.
@@ -186,6 +199,14 @@ declare class AgoClient {
  * SDK Events
  */
 declare interface AgoClientEvents {
+    /**
+     * The client-side context changed: a context entry or dynamic provider was
+     * added/removed, or a stateful helper (e.g. `createFormCollector`) updated its
+     * store. Carries the fresh snapshot so observers — notably the dev panel — can
+     * repaint without waiting for the next message. Fires for the form collector's
+     * initial install too, so its missing fields show from the start of a conversation.
+     */
+    "context:changed": ContextSnapshot | null;
     "message:start": {
         conversationId: string;
         messageId: string;
@@ -201,6 +222,12 @@ declare interface AgoClientEvents {
         conversationId?: string;
         messageId?: string;
     };
+    /**
+     * A full conversation was loaded from the server (e.g. after a page reload).
+     * Carries the messages and their persisted tool calls so stateful helpers —
+     * notably `createFormCollector` — can replay them to restore their state.
+     */
+    "conversation:loaded": Conversation;
     "toolCall:received": ToolCallData;
     "toolCall:form": ToolCallData;
     "function:invoke": ClientFunctionInvocation;
@@ -350,13 +377,12 @@ declare interface Conversation {
 
 /** Options for {@link initDevPanel}. */
 export declare interface DevPanelOptions {
-    /** The store whose state the panel renders live. */
-    store: Store<unknown>;
     /**
-     * Client to read registered functions from and listen to function events on.
-     * Typed structurally so a mock client works too.
+     * The AGO client to debug. The panel lists its registered functions, logs its
+     * function events, and renders its live context snapshot
+     * (`client.getContextSnapshot()`)
      */
-    client: Pick<AgoClient, "on" | "getRegisteredFunctions">;
+    client: Pick<AgoClient, "on" | "getRegisteredFunctions" | "getContextSnapshot">;
     /** Where to mount: a CSS selector, an Element, or `document.body` (default). */
     target?: string | Element;
 }
@@ -401,27 +427,6 @@ declare interface SendMessageOptions {
     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;
-}
-
 /**
  * Tool call data from SSE stream
  */

package/dist/devtools.js

@@ -1,62 +1,65 @@
-var r, d, x = () => ({});
-function p() {
-  r && (r.textContent = JSON.stringify(x(), null, 2));
+var c, d, v = () => ({});
+function i() {
+  c && (c.textContent = JSON.stringify(v(), null, 2));
 }
-function g(t, a) {
+function s(l, e) {
   if (!d) return;
-  const e = document.createElement("div");
-  e.className = `dev-log-line dev-log-${a}`, e.textContent = `${(/* @__PURE__ */ new Date()).toLocaleTimeString()}  ${t}`, d.appendChild(e), d.scrollTop = d.scrollHeight;
+  const o = document.createElement("div");
+  o.className = `dev-log-line dev-log-${e}`, o.textContent = `${(/* @__PURE__ */ new Date()).toLocaleTimeString()}  ${l}`, d.appendChild(o), d.scrollTop = d.scrollHeight;
 }
-var u = "ago_dev_panel_collapsed";
-function s(t, a) {
-  t.classList.toggle("collapsed", a);
-  const e = t.querySelector(".dev-toggle");
-  e && (e.textContent = a ? "▢" : "—", e.title = a ? "Expand dev tools" : "Collapse dev tools", e.setAttribute("aria-expanded", String(!a)));
+var x = "ago_dev_panel_collapsed";
+function r(l, e) {
+  l.classList.toggle("collapsed", e);
+  const o = l.querySelector(".dev-toggle");
+  o && (o.textContent = e ? "▢" : "—", o.title = e ? "Expand dev tools" : "Collapse dev tools", o.setAttribute("aria-expanded", String(!e)));
   try {
-    localStorage.setItem(u, a ? "1" : "0");
+    localStorage.setItem(x, e ? "1" : "0");
   } catch {
   }
 }
-function m(t) {
-  const { store: a, client: e, target: i } = t;
-  x = a.get, b();
-  const f = typeof i == "string" ? document.querySelector(i) : i instanceof Element ? i : document.body, o = document.createElement("aside");
-  o.id = "ago-dev-panel", (f ?? document.body).appendChild(o), o.innerHTML = `
+function m(l) {
+  const { client: e, target: o } = l;
+  v = () => e.getContextSnapshot()?.entries ?? {}, h();
+  const f = typeof o == "string" ? document.querySelector(o) : o instanceof Element ? o : document.body, t = document.createElement("aside");
+  t.id = "ago-dev-panel", (f ?? document.body).appendChild(t), t.innerHTML = `
     <div class="dev-head">
       <span class="dev-badge">DEV</span>
       <span class="dev-title">DEV TOOLS · client-side function state — not for production</span>
       <button type="button" class="dev-toggle" aria-label="Toggle dev tools">—</button>
     </div>
     <div class="dev-body">
-      <div class="dev-fns">Registered functions: <code>${(e.getRegisteredFunctions?.() ?? []).map((n) => n.name).join(", ") || "—"}</code></div>
+      <div class="dev-fns">Registered functions: <code>${(e.getRegisteredFunctions?.() ?? []).map((a) => a.name).join(", ") || "—"}</code></div>
       <div class="dev-section-label">JSON object (built by the agent)</div>
       <pre class="dev-state" id="ago-dev-state"></pre>
       <div class="dev-section-label">Function calls</div>
       <div class="dev-log" id="ago-dev-log"></div>
     </div>
-  `, r = o.querySelector("#ago-dev-state"), d = o.querySelector("#ago-dev-log"), o.querySelector(".dev-toggle")?.addEventListener("click", (n) => {
-    n.stopPropagation(), s(o, !o.classList.contains("collapsed"));
-  }), o.addEventListener("click", () => {
-    o.classList.contains("collapsed") && s(o, !1);
+  `, c = t.querySelector("#ago-dev-state"), d = t.querySelector("#ago-dev-log"), t.querySelector(".dev-toggle")?.addEventListener("click", (a) => {
+    a.stopPropagation(), r(t, !t.classList.contains("collapsed"));
+  }), t.addEventListener("click", () => {
+    t.classList.contains("collapsed") && r(t, !1);
   });
-  let c = !1;
+  let p = !1;
   try {
-    c = localStorage.getItem(u) === "1";
+    p = localStorage.getItem(x) === "1";
   } catch {
   }
-  s(o, c), e.on("function:invoke", ({ functionName: n, arguments: l }) => {
-    g(`→ ${n}(${JSON.stringify(l ?? {})})`, "invoke");
-  }), e.on("function:result", ({ result: n, error: l }) => {
-    g(l ? `✗ error: ${l}` : `← ${JSON.stringify(n)}`, l ? "error" : "result");
-  }), a.subscribe(p), p();
+  r(t, p), e.on("function:invoke", ({ functionName: a, arguments: n }) => {
+    s(`→ ${a}(${JSON.stringify(n ?? {})})`, "invoke");
+  }), e.on("function:result", ({ result: a, error: n }) => {
+    s(n ? `✗ error: ${n}` : `← ${JSON.stringify(a)}`, n ? "error" : "result"), i();
+  }), e.on("context:changed", i), e.on("conversation:loaded", (a) => {
+    const n = (a.messages ?? []).flatMap((u) => u.toolCalls ?? []);
+    s(`⟳ hydrated "${a.title || a.id}" — replayed ${n.length} tool call${n.length === 1 ? "" : "s"}`, "hydrate"), i();
+  }), i();
 }
-var v = "ago-dev-panel-styles";
-function b() {
-  if (document.getElementById(v)) return;
-  const t = document.createElement("style");
-  t.id = v, t.textContent = h, document.head.appendChild(t);
+var g = "ago-dev-panel-styles";
+function h() {
+  if (document.getElementById(g)) return;
+  const l = document.createElement("style");
+  l.id = g, l.textContent = b, document.head.appendChild(l);
 }
-var h = `
+var b = `
 #ago-dev-panel {
   position: fixed;
   top: 16px;
@@ -150,6 +153,7 @@ var h = `
 #ago-dev-panel .dev-log-invoke { color: #9ecbff; }
 #ago-dev-panel .dev-log-result { color: #86efac; }
 #ago-dev-panel .dev-log-error { color: #fca5a5; }
+#ago-dev-panel .dev-log-hydrate { color: #d8b4fe; }
 `;
 export {
   m as initDevPanel

package/dist/helpers.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("./functions-BH1X5kas.cjs");exports.copyToClipboard=o.copyToClipboard;exports.getLocalStorage=o.getLocalStorage;exports.getUserLocation=o.getUserLocation;exports.highlightElement=o.highlightElement;exports.openUrl=o.openUrl;exports.scrollToElement=o.scrollToElement;exports.setLocalStorage=o.setLocalStorage;exports.setTheme=o.setTheme;exports.showConfirmDialog=o.showConfirmDialog;exports.showNotification=o.showNotification;exports.showToast=o.showToast;exports.submitForm=o.submitForm;exports.trackEvent=o.trackEvent;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("./functions-DsmzgHjC.cjs");exports.copyToClipboard=o.copyToClipboard;exports.getLocalStorage=o.getLocalStorage;exports.getUserLocation=o.getUserLocation;exports.highlightElement=o.highlightElement;exports.openUrl=o.openUrl;exports.scrollToElement=o.scrollToElement;exports.setLocalStorage=o.setLocalStorage;exports.setTheme=o.setTheme;exports.showConfirmDialog=o.showConfirmDialog;exports.showNotification=o.showNotification;exports.showToast=o.showToast;exports.submitForm=o.submitForm;exports.trackEvent=o.trackEvent;

package/dist/helpers.js

@@ -1,4 +1,4 @@
-import { a, c as s, d as t, f as e, i as r, l as i, m as l, o as m, p as c, r as g, s as h, t as n, u as p } from "./functions-CWSRi3xv.js";
+import { a, c as s, d as t, f as e, i as r, l as i, m as l, o as m, p as c, r as g, s as h, t as n, u as p } from "./functions-C1-5vadY.js";
 export {
   n as copyToClipboard,
   g as getLocalStorage,

package/dist/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("./AgoClient-bjN-z2ZQ.cjs"),p=require("./createFormCollector-H4Me_2uj.cjs"),A=require("./createMockClient-DQvFFWnc.cjs"),g=require("./functions-BH1X5kas.cjs");function h(e){return e}function C(e,o){return e.on("message:complete",o),()=>e.off("message:complete",o)}function E(e,o){return e.on("message:chunk",o),()=>e.off("message:chunk",o)}function y(e,o){return e.on("message:start",o),()=>e.off("message:start",o)}function S(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("function:invoke",o),()=>e.off("function:invoke",o)}async function*k(e,o,l){const n=[];let r=null,a=!1;const c=s=>{n.push(s),r?.()},f=s=>c({type:"start",data:s}),t=s=>c({type:"chunk",data:s}),u=s=>{c({type:"complete",data:s}),a=!0,r?.()},m=s=>{c({type:"error",data:s}),a=!0,r?.()},d=s=>c({type:"toolCall",data:s});e.on("message:start",f),e.on("message:chunk",t),e.on("message:complete",u),e.on("message:error",m),e.on("toolCall:received",d),e.sendMessage(o,l).catch(()=>{a=!0,r?.()});try{for(;!a||n.length>0;)n.length>0?yield n.shift():(await new Promise(s=>{r=s}),r=null)}finally{e.off("message:start",f),e.off("message:chunk",t),e.off("message:complete",u),e.off("message:error",m),e.off("toolCall:received",d)}}function w(e){let o,l,n,r,a,c;if(typeof window<"u"&&window.AGO){const t=window.AGO;o=t.basepath,l=t.widgetId,n=t.agent||t.defaultAgent,r=t.permission,a=t.email,c=t.jwt}if(typeof document<"u"){const t=u=>document.querySelector(`meta[name="${u}"]`)?.getAttribute("content")||void 0;o=o||t("ago-base-url"),l=l||t("ago-widget-id"),n=n||t("ago-agent")||t("ago-agent-id"),r=r||t("ago-permission"),a=a||t("ago-user-email")}if(typeof document<"u"){const t=[document.body,...Array.from(document.querySelectorAll("script[data-ago-base-url]"))].filter(Boolean);for(const u of t)u&&(o=o||u.getAttribute("data-ago-base-url")||void 0,l=l||u.getAttribute("data-ago-widget-id")||void 0,n=n||u.getAttribute("data-ago-agent")||u.getAttribute("data-ago-agent-id")||void 0,r=r||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,n=e?.agent||e?.defaultAgentId||n,r=e?.permission||r,a=e?.userEmail||a,c=e?.userJwt||c;const f=e?.debug;return o?{baseUrl:o,widgetId:l,agent:n,permission:r,userEmail:a,userJwt:c,debug:f}:null}function v(e){const o=w(e);if(!o)throw new Error('createAgo(): could not detect AGO configuration. Set window.AGO, add <meta name="ago-base-url">, or pass { baseUrl } explicitly.');return new i.AgoClient(o)}function F(e,o){return{...e,handler:o}}exports.AgoApiError=i.AgoApiError;exports.AgoClient=i.AgoClient;exports.AgoError=i.AgoError;exports.AgoFunctionError=i.AgoFunctionError;exports.AgoNetworkError=i.AgoNetworkError;exports.AgoStreamError=i.AgoStreamError;exports.ClientContextRegistry=i.ClientContextRegistry;exports.EventEmitter=i.EventEmitter;exports.FunctionRegistry=i.FunctionRegistry;exports.SSEHandler=i.SSEHandler;exports.autoDetectConfig=w;exports.copyToClipboard=g.copyToClipboard;exports.createAgo=v;exports.createFormCollector=p.createFormCollector;exports.createMessageStream=k;exports.createMockClient=A.createMockClient;exports.createStore=p.createStore;exports.defineFunction=h;exports.getLocalStorage=g.getLocalStorage;exports.getUserLocation=g.getUserLocation;exports.highlightElement=g.highlightElement;exports.isStreamNetworkError=i.isStreamNetworkError;exports.logger=i.logger;exports.onFunctionInvoke=M;exports.onMessage=C;exports.onMessageChunk=E;exports.onMessageError=S;exports.onMessageStart=y;exports.onToolCall=b;exports.openUrl=g.openUrl;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.withHandler=F;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("./AgoClient-D4EL6nva.cjs"),p=require("./createFormCollector-Wb8Rr-U2.cjs"),A=require("./createConversationSession-DtaeA418.cjs"),C=require("./createMockClient-zHQ0cjUH.cjs"),g=require("./functions-DsmzgHjC.cjs");function h(e){return e}function E(e,o){return e.on("message:complete",o),()=>e.off("message:complete",o)}function S(e,o){return e.on("message:chunk",o),()=>e.off("message:chunk",o)}function y(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 v(e,o){return e.on("toolCall:received",o),()=>e.off("toolCall:received",o)}function M(e,o){return e.on("function:invoke",o),()=>e.off("function:invoke",o)}async function*k(e,o,l){const n=[];let r=null,a=!1;const c=s=>{n.push(s),r?.()},f=s=>c({type:"start",data:s}),t=s=>c({type:"chunk",data:s}),u=s=>{c({type:"complete",data:s}),a=!0,r?.()},m=s=>{c({type:"error",data:s}),a=!0,r?.()},d=s=>c({type:"toolCall",data:s});e.on("message:start",f),e.on("message:chunk",t),e.on("message:complete",u),e.on("message:error",m),e.on("toolCall:received",d),e.sendMessage(o,l).catch(()=>{a=!0,r?.()});try{for(;!a||n.length>0;)n.length>0?yield n.shift():(await new Promise(s=>{r=s}),r=null)}finally{e.off("message:start",f),e.off("message:chunk",t),e.off("message:complete",u),e.off("message:error",m),e.off("toolCall:received",d)}}function w(e){let o,l,n,r,a,c;if(typeof window<"u"&&window.AGO){const t=window.AGO;o=t.basepath,l=t.widgetId,n=t.agent||t.defaultAgent,r=t.permission,a=t.email,c=t.jwt}if(typeof document<"u"){const t=u=>document.querySelector(`meta[name="${u}"]`)?.getAttribute("content")||void 0;o=o||t("ago-base-url"),l=l||t("ago-widget-id"),n=n||t("ago-agent")||t("ago-agent-id"),r=r||t("ago-permission"),a=a||t("ago-user-email")}if(typeof document<"u"){const t=[document.body,...Array.from(document.querySelectorAll("script[data-ago-base-url]"))].filter(Boolean);for(const u of t)u&&(o=o||u.getAttribute("data-ago-base-url")||void 0,l=l||u.getAttribute("data-ago-widget-id")||void 0,n=n||u.getAttribute("data-ago-agent")||u.getAttribute("data-ago-agent-id")||void 0,r=r||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,n=e?.agent||e?.defaultAgentId||n,r=e?.permission||r,a=e?.userEmail||a,c=e?.userJwt||c;const f=e?.debug;return o?{baseUrl:o,widgetId:l,agent:n,permission:r,userEmail:a,userJwt:c,debug:f}:null}function q(e){const o=w(e);if(!o)throw new Error('createAgo(): could not detect AGO configuration. Set window.AGO, add <meta name="ago-base-url">, or pass { baseUrl } explicitly.');return new i.AgoClient(o)}function F(e,o){return{...e,handler:o}}exports.AgoApiError=i.AgoApiError;exports.AgoClient=i.AgoClient;exports.AgoError=i.AgoError;exports.AgoFunctionError=i.AgoFunctionError;exports.AgoNetworkError=i.AgoNetworkError;exports.AgoStreamError=i.AgoStreamError;exports.ClientContextRegistry=i.ClientContextRegistry;exports.EventEmitter=i.EventEmitter;exports.FunctionRegistry=i.FunctionRegistry;exports.SSEHandler=i.SSEHandler;exports.autoDetectConfig=w;exports.copyToClipboard=g.copyToClipboard;exports.createAgo=q;exports.createConversationSession=A.createConversationSession;exports.createFormCollector=p.createFormCollector;exports.createMessageStream=k;exports.createMockClient=C.createMockClient;exports.createStore=p.createStore;exports.defineFunction=h;exports.getLocalStorage=g.getLocalStorage;exports.getUserLocation=g.getUserLocation;exports.highlightElement=g.highlightElement;exports.isStreamNetworkError=i.isStreamNetworkError;exports.logger=i.logger;exports.onFunctionInvoke=M;exports.onMessage=E;exports.onMessageChunk=S;exports.onMessageError=b;exports.onMessageStart=y;exports.onToolCall=v;exports.openUrl=g.openUrl;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.withHandler=F;

package/dist/index.d.cts

@@ -42,6 +42,12 @@ export declare class AgoClient {
      * Get a specific conversation with messages
      */
     getConversation(conversationId: string): Promise<Conversation>;
+    /**
+     * Map the backend's snake_case `tool_call_data` entries onto the camelCase
+     * {@link ToolCallData} shape used everywhere else in the SDK. Mirrors
+     * `SSEHandler.parseToolCall` so persisted and streamed tool calls match.
+     */
+    private static mapPersistedToolCalls;
     /**
      * Get messages for a conversation
      */
@@ -152,6 +158,13 @@ export declare class AgoClient {
      * Remove a dynamic context provider.
      */
     removeDynamicContext(key: string): boolean;
+    /**
+     * Broadcast that the client-side context changed by emitting `context:changed`
+     * with the fresh snapshot. The context-mutating methods call this automatically;
+     * stateful helpers whose context lives in a store (e.g. `createFormCollector`)
+     * call it when their store updates so observers like the dev panel stay live.
+     */
+    notifyContextChanged(): void;
     /**
      * Enable automatic capture of the current browser page (URL + title).
      * Injected as a dynamic context entry named `browser-page`.
@@ -197,6 +210,14 @@ export declare class AgoClient {
  * SDK Events
  */
 export declare interface AgoClientEvents {
+    /**
+     * The client-side context changed: a context entry or dynamic provider was
+     * added/removed, or a stateful helper (e.g. `createFormCollector`) updated its
+     * store. Carries the fresh snapshot so observers — notably the dev panel — can
+     * repaint without waiting for the next message. Fires for the form collector's
+     * initial install too, so its missing fields show from the start of a conversation.
+     */
+    "context:changed": ContextSnapshot | null;
     "message:start": {
         conversationId: string;
         messageId: string;
@@ -212,6 +233,12 @@ export declare interface AgoClientEvents {
         conversationId?: string;
         messageId?: string;
     };
+    /**
+     * A full conversation was loaded from the server (e.g. after a page reload).
+     * Carries the messages and their persisted tool calls so stateful helpers —
+     * notably `createFormCollector` — can replay them to restore their state.
+     */
+    "conversation:loaded": Conversation;
     "toolCall:received": ToolCallData;
     "toolCall:form": ToolCallData;
     "function:invoke": ClientFunctionInvocation;
@@ -498,6 +525,60 @@ export declare interface Conversation {
     messages?: AgoMessage[];
 }
 
+export declare interface ConversationSession {
+    /**
+     * The stable widget id identifying this visitor. Generated once and persisted
+     * forever, so a returning visitor keeps the same id (and therefore the same
+     * server-side conversation history) across reloads.
+     */
+    readonly widgetId: string;
+    /**
+     * The last active thread id, decided **entirely on the front** so a reload costs
+     * no backend round-trip. Returns `null` when there is no cached thread, when its
+     * last message time is unknown, or when it has been idle longer than `ttlMs`.
+     */
+    getLastActiveThread(): string | null;
+    /**
+     * Record (and refresh) the active thread together with the time of its last
+     * message — call it once per turn. The `lastMessageAt` drives the sliding TTL;
+     * omit it and the thread won't be resumed (no time → not displayed).
+     */
+    setActiveThread(conversationId: string, lastMessageAt?: Date | number): void;
+    /** Forget the cached thread — e.g. on "new chat". */
+    clear(): void;
+    /** The resolved storage key holding the widget id — handy for debugging. */
+    readonly key: string;
+}
+
+export declare interface ConversationSessionOptions {
+    /**
+     * Storage backend. Defaults to `localStorage`, degrading to an in-memory store
+     * when storage is unavailable (SSR / disabled). Pass `sessionStorage` for a
+     * tab-scoped session, or any `{ getItem, setItem }` for a custom backend.
+     */
+    storage?: StorageLike;
+    /**
+     * Storage key for the widget id. Default `"ago_widget_id"` — the same key the
+     * HTTP client reads, so the visitor's id is shared across the SDK.
+     */
+    key?: string;
+    /**
+     * Explicit widget id to adopt (and persist) instead of reading or generating
+     * one — e.g. when the host app already has a stable visitor identifier.
+     */
+    widgetId?: string;
+    /** Storage key for the cached last active thread. Default `"ago_last_thread"`. */
+    threadKey?: string;
+    /**
+     * Maximum idle age of a thread to still resume it, in milliseconds, compared
+     * against the recorded time of its last message. Checked entirely on the front
+     * (no backend call): a thread idle longer than this — or one with no recorded
+     * last-message time — is not resumed (`getLastActiveThread` returns `null`).
+     * Default 2h. Pass `Infinity` to never expire.
+     */
+    ttlMs?: number;
+}
+
 /**
  * Copy text to clipboard.
  */
@@ -529,6 +610,33 @@ export declare const copyToClipboard: ClientFunctionDefinition;
  */
 export declare function createAgo(overrides?: Partial<AgoConfig>): AgoClient;
 
+/**
+ * Identify a returning visitor with a single, stable widget id — the same model as
+ * the frontend's `getOrGenerateWidgetId` — and resume their last active thread.
+ *
+ * There is no per-agent conversation id: the widget id is the identity, and the last
+ * active thread (its id + the time of its last message) is cached locally so resuming
+ * is a pure front-side decision — **no backend call** just to know whether the thread
+ * is still fresh. A thread idle longer than `ttlMs` (default 2h, sliding — refreshed
+ * by `setActiveThread`), or one with no recorded last-message time, is not resumed.
+ *
+ * ```ts
+ * const session = createConversationSession();
+ *
+ * // resume on load (front-only — no request):
+ * const conversationId = session.getLastActiveThread() ?? undefined;
+ *
+ * // record the thread once a turn completes:
+ * session.setActiveThread(reply.conversationId, reply.createdAt);
+ *
+ * session.clear(); // forget it — e.g. a "new chat" button
+ * ```
+ *
+ * Persistence is opt-in by storage backend: it defaults to `localStorage`, but pass
+ * `sessionStorage` for a tab-scoped session or omit storage in environments without it.
+ */
+export declare function createConversationSession(options?: ConversationSessionOptions): ConversationSession;
+
 /**
  * Wire one schema into a conversational form: an observable store, an
  * `update_<name>` client function the agent calls to fill fields, a dynamic-context
@@ -675,6 +783,14 @@ export declare interface FormCollector<V = Record<string, unknown>> {
     contextProvider: () => ContextEntry;
     /** Register the functions + dynamic context on a client. Returns an uninstall fn. */
     install: (client: AgoClient) => () => void;
+    /**
+     * Rebuild the state by replaying the persisted `update_<name>` / `submit_<name>`
+     * tool-call arguments of a loaded conversation — restoring what the agent had
+     * collected after a page reload. Replays from the initial values, so it is
+     * idempotent. `install` wires this to the client's `conversation:loaded` event,
+     * so a custom front rarely needs to call it directly.
+     */
+    hydrate: (toolCalls: readonly ToolCallData[]) => void;
     /** Submit the form now (e.g. from a UI button). Blocks until required fields are filled. */
     submit: () => Promise<FormSubmitResult>;
     getValues: () => Partial<V>;
@@ -1054,7 +1170,7 @@ declare interface SSEHandlerCallbacks {
 }
 
 /** The slice of the Web Storage API that {@link createStore} relies on. */
-declare type StorageLike = Pick<Storage, "getItem" | "setItem">;
+export declare type StorageLike = Pick<Storage, "getItem" | "setItem">;
 
 /**
  * A minimal observable store: one value, synchronous subscriptions, and

package/dist/index.d.ts

@@ -42,6 +42,12 @@ export declare class AgoClient {
      * Get a specific conversation with messages
      */
     getConversation(conversationId: string): Promise<Conversation>;
+    /**
+     * Map the backend's snake_case `tool_call_data` entries onto the camelCase
+     * {@link ToolCallData} shape used everywhere else in the SDK. Mirrors
+     * `SSEHandler.parseToolCall` so persisted and streamed tool calls match.
+     */
+    private static mapPersistedToolCalls;
     /**
      * Get messages for a conversation
      */
@@ -152,6 +158,13 @@ export declare class AgoClient {
      * Remove a dynamic context provider.
      */
     removeDynamicContext(key: string): boolean;
+    /**
+     * Broadcast that the client-side context changed by emitting `context:changed`
+     * with the fresh snapshot. The context-mutating methods call this automatically;
+     * stateful helpers whose context lives in a store (e.g. `createFormCollector`)
+     * call it when their store updates so observers like the dev panel stay live.
+     */
+    notifyContextChanged(): void;
     /**
      * Enable automatic capture of the current browser page (URL + title).
      * Injected as a dynamic context entry named `browser-page`.
@@ -197,6 +210,14 @@ export declare class AgoClient {
  * SDK Events
  */
 export declare interface AgoClientEvents {
+    /**
+     * The client-side context changed: a context entry or dynamic provider was
+     * added/removed, or a stateful helper (e.g. `createFormCollector`) updated its
+     * store. Carries the fresh snapshot so observers — notably the dev panel — can
+     * repaint without waiting for the next message. Fires for the form collector's
+     * initial install too, so its missing fields show from the start of a conversation.
+     */
+    "context:changed": ContextSnapshot | null;
     "message:start": {
         conversationId: string;
         messageId: string;
@@ -212,6 +233,12 @@ export declare interface AgoClientEvents {
         conversationId?: string;
         messageId?: string;
     };
+    /**
+     * A full conversation was loaded from the server (e.g. after a page reload).
+     * Carries the messages and their persisted tool calls so stateful helpers —
+     * notably `createFormCollector` — can replay them to restore their state.
+     */
+    "conversation:loaded": Conversation;
     "toolCall:received": ToolCallData;
     "toolCall:form": ToolCallData;
     "function:invoke": ClientFunctionInvocation;
@@ -498,6 +525,60 @@ export declare interface Conversation {
     messages?: AgoMessage[];
 }
 
+export declare interface ConversationSession {
+    /**
+     * The stable widget id identifying this visitor. Generated once and persisted
+     * forever, so a returning visitor keeps the same id (and therefore the same
+     * server-side conversation history) across reloads.
+     */
+    readonly widgetId: string;
+    /**
+     * The last active thread id, decided **entirely on the front** so a reload costs
+     * no backend round-trip. Returns `null` when there is no cached thread, when its
+     * last message time is unknown, or when it has been idle longer than `ttlMs`.
+     */
+    getLastActiveThread(): string | null;
+    /**
+     * Record (and refresh) the active thread together with the time of its last
+     * message — call it once per turn. The `lastMessageAt` drives the sliding TTL;
+     * omit it and the thread won't be resumed (no time → not displayed).
+     */
+    setActiveThread(conversationId: string, lastMessageAt?: Date | number): void;
+    /** Forget the cached thread — e.g. on "new chat". */
+    clear(): void;
+    /** The resolved storage key holding the widget id — handy for debugging. */
+    readonly key: string;
+}
+
+export declare interface ConversationSessionOptions {
+    /**
+     * Storage backend. Defaults to `localStorage`, degrading to an in-memory store
+     * when storage is unavailable (SSR / disabled). Pass `sessionStorage` for a
+     * tab-scoped session, or any `{ getItem, setItem }` for a custom backend.
+     */
+    storage?: StorageLike;
+    /**
+     * Storage key for the widget id. Default `"ago_widget_id"` — the same key the
+     * HTTP client reads, so the visitor's id is shared across the SDK.
+     */
+    key?: string;
+    /**
+     * Explicit widget id to adopt (and persist) instead of reading or generating
+     * one — e.g. when the host app already has a stable visitor identifier.
+     */
+    widgetId?: string;
+    /** Storage key for the cached last active thread. Default `"ago_last_thread"`. */
+    threadKey?: string;
+    /**
+     * Maximum idle age of a thread to still resume it, in milliseconds, compared
+     * against the recorded time of its last message. Checked entirely on the front
+     * (no backend call): a thread idle longer than this — or one with no recorded
+     * last-message time — is not resumed (`getLastActiveThread` returns `null`).
+     * Default 2h. Pass `Infinity` to never expire.
+     */
+    ttlMs?: number;
+}
+
 /**
  * Copy text to clipboard.
  */
@@ -529,6 +610,33 @@ export declare const copyToClipboard: ClientFunctionDefinition;
  */
 export declare function createAgo(overrides?: Partial<AgoConfig>): AgoClient;
 
+/**
+ * Identify a returning visitor with a single, stable widget id — the same model as
+ * the frontend's `getOrGenerateWidgetId` — and resume their last active thread.
+ *
+ * There is no per-agent conversation id: the widget id is the identity, and the last
+ * active thread (its id + the time of its last message) is cached locally so resuming
+ * is a pure front-side decision — **no backend call** just to know whether the thread
+ * is still fresh. A thread idle longer than `ttlMs` (default 2h, sliding — refreshed
+ * by `setActiveThread`), or one with no recorded last-message time, is not resumed.
+ *
+ * ```ts
+ * const session = createConversationSession();
+ *
+ * // resume on load (front-only — no request):
+ * const conversationId = session.getLastActiveThread() ?? undefined;
+ *
+ * // record the thread once a turn completes:
+ * session.setActiveThread(reply.conversationId, reply.createdAt);
+ *
+ * session.clear(); // forget it — e.g. a "new chat" button
+ * ```
+ *
+ * Persistence is opt-in by storage backend: it defaults to `localStorage`, but pass
+ * `sessionStorage` for a tab-scoped session or omit storage in environments without it.
+ */
+export declare function createConversationSession(options?: ConversationSessionOptions): ConversationSession;
+
 /**
  * Wire one schema into a conversational form: an observable store, an
  * `update_<name>` client function the agent calls to fill fields, a dynamic-context
@@ -675,6 +783,14 @@ export declare interface FormCollector<V = Record<string, unknown>> {
     contextProvider: () => ContextEntry;
     /** Register the functions + dynamic context on a client. Returns an uninstall fn. */
     install: (client: AgoClient) => () => void;
+    /**
+     * Rebuild the state by replaying the persisted `update_<name>` / `submit_<name>`
+     * tool-call arguments of a loaded conversation — restoring what the agent had
+     * collected after a page reload. Replays from the initial values, so it is
+     * idempotent. `install` wires this to the client's `conversation:loaded` event,
+     * so a custom front rarely needs to call it directly.
+     */
+    hydrate: (toolCalls: readonly ToolCallData[]) => void;
     /** Submit the form now (e.g. from a UI button). Blocks until required fields are filled. */
     submit: () => Promise<FormSubmitResult>;
     getValues: () => Partial<V>;
@@ -1054,7 +1170,7 @@ declare interface SSEHandlerCallbacks {
 }
 
 /** The slice of the Web Storage API that {@link createStore} relies on. */
-declare type StorageLike = Pick<Storage, "getItem" | "setItem">;
+export declare type StorageLike = Pick<Storage, "getItem" | "setItem">;
 
 /**
  * A minimal observable store: one value, synchronous subscriptions, and