@useago/sdk 0.3.3 → 0.4.1

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
      */
@@ -201,6 +207,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 +362,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 +412,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,63 +1,63 @@
-var r, d, x = () => ({});
-function p() {
-  r && (r.textContent = JSON.stringify(x(), null, 2));
+var s, d, v = () => ({});
+function c() {
+  s && (s.textContent = JSON.stringify(v(), null, 2));
 }
-function v(o, n) {
+function p(a, o) {
   if (!d) return;
   const e = document.createElement("div");
-  e.className = `dev-log-line dev-log-${n}`, e.textContent = `${(/* @__PURE__ */ new Date()).toLocaleTimeString()}  ${o}`, d.appendChild(e), d.scrollTop = d.scrollHeight;
+  e.className = `dev-log-line dev-log-${o}`, e.textContent = `${(/* @__PURE__ */ new Date()).toLocaleTimeString()}  ${a}`, d.appendChild(e), d.scrollTop = d.scrollHeight;
 }
-var u = "devPanelCollapsed";
-function s(o, n) {
-  o.classList.toggle("collapsed", n);
-  const e = o.querySelector(".dev-toggle");
-  e && (e.textContent = n ? "▢" : "—", e.title = n ? "Expand dev tools" : "Collapse dev tools", e.setAttribute("aria-expanded", String(!n)));
+var x = "ago_dev_panel_collapsed";
+function i(a, o) {
+  a.classList.toggle("collapsed", o);
+  const e = a.querySelector(".dev-toggle");
+  e && (e.textContent = o ? "▢" : "—", e.title = o ? "Expand dev tools" : "Collapse dev tools", e.setAttribute("aria-expanded", String(!o)));
   try {
-    localStorage.setItem(u, n ? "1" : "0");
+    localStorage.setItem(x, o ? "1" : "0");
   } catch {
   }
 }
-function m(o) {
-  const { store: n, client: e, target: i } = o;
-  x = n.get, b();
-  const f = typeof i == "string" ? document.querySelector(i) : i instanceof Element ? i : document.body, t = document.createElement("aside");
-  t.id = "dev-panel", (f ?? document.body).appendChild(t), t.innerHTML = `
+function h(a) {
+  const { client: o, target: e } = a;
+  v = () => o.getContextSnapshot()?.entries ?? {}, f();
+  const u = typeof e == "string" ? document.querySelector(e) : e instanceof Element ? e : document.body, t = document.createElement("aside");
+  t.id = "ago-dev-panel", (u ?? 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((l) => l.name).join(", ") || "—"}</code></div>
+      <div class="dev-fns">Registered functions: <code>${(o.getRegisteredFunctions?.() ?? []).map((n) => n.name).join(", ") || "—"}</code></div>
       <div class="dev-section-label">JSON object (built by the agent)</div>
-      <pre class="dev-state" id="dev-state"></pre>
+      <pre class="dev-state" id="ago-dev-state"></pre>
       <div class="dev-section-label">Function calls</div>
-      <div class="dev-log" id="dev-log"></div>
+      <div class="dev-log" id="ago-dev-log"></div>
     </div>
-  `, r = t.querySelector("#dev-state"), d = t.querySelector("#dev-log"), t.querySelector(".dev-toggle")?.addEventListener("click", (l) => {
-    l.stopPropagation(), s(t, !t.classList.contains("collapsed"));
+  `, s = t.querySelector("#ago-dev-state"), d = t.querySelector("#ago-dev-log"), t.querySelector(".dev-toggle")?.addEventListener("click", (n) => {
+    n.stopPropagation(), i(t, !t.classList.contains("collapsed"));
   }), t.addEventListener("click", () => {
-    t.classList.contains("collapsed") && s(t, !1);
+    t.classList.contains("collapsed") && i(t, !1);
   });
-  let c = !1;
+  let r = !1;
   try {
-    c = localStorage.getItem(u) === "1";
+    r = localStorage.getItem(x) === "1";
   } catch {
   }
-  s(t, c), e.on("function:invoke", ({ functionName: l, arguments: a }) => {
-    v(`→ ${l}(${JSON.stringify(a ?? {})})`, "invoke");
-  }), e.on("function:result", ({ result: l, error: a }) => {
-    v(a ? `✗ error: ${a}` : `← ${JSON.stringify(l)}`, a ? "error" : "result");
-  }), n.subscribe(p), p();
+  i(t, r), o.on("function:invoke", ({ functionName: n, arguments: l }) => {
+    p(`→ ${n}(${JSON.stringify(l ?? {})})`, "invoke");
+  }), o.on("function:result", ({ result: n, error: l }) => {
+    p(l ? `✗ error: ${l}` : `← ${JSON.stringify(n)}`, l ? "error" : "result"), c();
+  }), c();
 }
-var g = "dev-panel-styles";
-function b() {
+var g = "ago-dev-panel-styles";
+function f() {
   if (document.getElementById(g)) return;
-  const o = document.createElement("style");
-  o.id = g, o.textContent = h, document.head.appendChild(o);
+  const a = document.createElement("style");
+  a.id = g, a.textContent = b, document.head.appendChild(a);
 }
-var h = `
-#dev-panel {
+var b = `
+#ago-dev-panel {
   position: fixed;
   top: 16px;
   right: 16px;
@@ -78,8 +78,8 @@ var h = `
   font-size: 12px;
   z-index: 1000;
 }
-#dev-panel .dev-head { display: flex; align-items: center; gap: 8px; }
-#dev-panel .dev-toggle {
+#ago-dev-panel .dev-head { display: flex; align-items: center; gap: 8px; }
+#ago-dev-panel .dev-toggle {
   margin-left: auto;
   flex: none;
   width: 22px;
@@ -95,19 +95,19 @@ var h = `
   line-height: 1;
   cursor: pointer;
 }
-#dev-panel .dev-toggle:hover { color: #d7e0e8; border-color: #3a4655; }
-#dev-panel .dev-body { display: flex; flex-direction: column; gap: 8px; }
+#ago-dev-panel .dev-toggle:hover { color: #d7e0e8; border-color: #3a4655; }
+#ago-dev-panel .dev-body { display: flex; flex-direction: column; gap: 8px; }
 
 /* Collapsed: shrink to a small clickable widget showing only the DEV badge. */
-#dev-panel.collapsed {
+#ago-dev-panel.collapsed {
   width: auto;
   cursor: pointer;
   padding: 8px 10px;
 }
-#dev-panel.collapsed .dev-title,
-#dev-panel.collapsed .dev-body { display: none; }
-#dev-panel.collapsed .dev-toggle { margin-left: 6px; }
-#dev-panel .dev-badge {
+#ago-dev-panel.collapsed .dev-title,
+#ago-dev-panel.collapsed .dev-body { display: none; }
+#ago-dev-panel.collapsed .dev-toggle { margin-left: 6px; }
+#ago-dev-panel .dev-badge {
   background: #f59e0b;
   color: #1c1206;
   font-weight: 700;
@@ -116,17 +116,17 @@ var h = `
   padding: 2px 6px;
   border-radius: 5px;
 }
-#dev-panel .dev-title { color: #f59e0b; font-size: 11px; line-height: 1.3; }
-#dev-panel .dev-fns { color: #7c8a99; font-size: 11px; }
-#dev-panel .dev-fns code { color: #9ecbff; }
-#dev-panel .dev-section-label {
+#ago-dev-panel .dev-title { color: #f59e0b; font-size: 11px; line-height: 1.3; }
+#ago-dev-panel .dev-fns { color: #7c8a99; font-size: 11px; }
+#ago-dev-panel .dev-fns code { color: #9ecbff; }
+#ago-dev-panel .dev-section-label {
   color: #7c8a99;
   text-transform: uppercase;
   letter-spacing: .08em;
   font-size: 10px;
   margin-top: 4px;
 }
-#dev-panel .dev-state {
+#ago-dev-panel .dev-state {
   margin: 0;
   padding: 8px;
   background: #060a0e;
@@ -136,7 +136,7 @@ var h = `
   white-space: pre;
   color: #c8e6c9;
 }
-#dev-panel .dev-log {
+#ago-dev-panel .dev-log {
   display: flex;
   flex-direction: column;
   gap: 2px;
@@ -146,11 +146,11 @@ var h = `
   border-radius: 8px;
   padding: 6px 8px;
 }
-#dev-panel .dev-log-line { white-space: pre-wrap; word-break: break-word; line-height: 1.4; }
-#dev-panel .dev-log-invoke { color: #9ecbff; }
-#dev-panel .dev-log-result { color: #86efac; }
-#dev-panel .dev-log-error { color: #fca5a5; }
+#ago-dev-panel .dev-log-line { white-space: pre-wrap; word-break: break-word; line-height: 1.4; }
+#ago-dev-panel .dev-log-invoke { color: #9ecbff; }
+#ago-dev-panel .dev-log-result { color: #86efac; }
+#ago-dev-panel .dev-log-error { color: #fca5a5; }
 `;
 export {
-  m as initDevPanel
+  h as initDevPanel
 };

package/dist/helpers.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("./functions-Bz-1Bs3I.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-DdROP6Ui.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"),m=require("./createMockClient-DecMEUcK.cjs"),g=require("./functions-Bz-1Bs3I.cjs");function A(e){return e}function h(e,o){return e.on("message:complete",o),()=>e.off("message:complete",o)}function C(e,o){return e.on("message:chunk",o),()=>e.off("message:chunk",o)}function E(e,o){return e.on("message:start",o),()=>e.off("message:start",o)}function y(e,o){return e.on("message:error",o),()=>e.off("message:error",o)}function S(e,o){return e.on("toolCall:received",o),()=>e.off("toolCall:received",o)}function b(e,o){return e.on("function:invoke",o),()=>e.off("function:invoke",o)}async function*M(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?.()},d=s=>{c({type:"error",data:s}),a=!0,r?.()},p=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",d),e.on("toolCall:received",p),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",d),e.off("toolCall:received",p)}}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 k(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 v(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=k;exports.createFormCollector=m.createFormCollector;exports.createMessageStream=M;exports.createMockClient=m.createMockClient;exports.createStore=m.createStore;exports.defineFunction=A;exports.getLocalStorage=g.getLocalStorage;exports.getUserLocation=g.getUserLocation;exports.highlightElement=g.highlightElement;exports.isStreamNetworkError=i.isStreamNetworkError;exports.logger=i.logger;exports.onFunctionInvoke=b;exports.onMessage=h;exports.onMessageChunk=C;exports.onMessageError=y;exports.onMessageStart=E;exports.onToolCall=S;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=v;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("./AgoClient-B6PsfMeg.cjs"),p=require("./createFormCollector-D1FfiSgA.cjs"),A=require("./createConversationSession-D3K5Gf1k.cjs"),C=require("./createMockClient-DMFGIOtc.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
      */
@@ -212,6 +218,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 +510,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 +595,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 +768,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 +1155,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
      */
@@ -212,6 +218,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 +510,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 +595,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 +768,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 +1155,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