@softr/sdk 0.0.87-alpha.4 → 0.0.87-alpha.5

package/dist/agent/agent-fns.d.ts

@@ -21,10 +21,10 @@ declare const listAgents: _tanstack_react_start7.OptionalFetcher<undefined, unde
   avatar?: string | null | undefined;
   thumbnail?: string | null | undefined;
 }[]>>;
-/** One past chat with an agent. */
+/** One past chat with an agent. `title` is null until the agent names the chat. */
 type AgentChatSummary = {
   id: string;
-  title: string;
+  title: string | null;
 };
 //#endregion
 export { Agent, AgentChatSummary, listAgents };

package/dist/agent/agent-fns.js

@@ -47,6 +47,7 @@ const chatSchema = z.object({
 	sessionId: z.string().nullable(),
 	timezone: z.string(),
 	pageName: z.string(),
+	pageUrl: z.string(),
 	record: z.object({
 		id: z.string(),
 		fields: z.record(z.string(), z.unknown())
@@ -75,6 +76,7 @@ const agentChatFn = createServerFn({ method: "POST" }).validator((data) => {
 			...data.sessionId ? { sessionId: data.sessionId } : {},
 			context: {
 				pageName: data.pageName,
+				pageUrl: data.pageUrl,
 				...data.record ? { currentRecord: { data: data.record } } : {}
 			}
 		}
@@ -105,7 +107,7 @@ const listAgentChatsFn = createServerFn({ method: "POST" }).validator(z.object({
 	if (!res.ok) throw new Error(`Loading chats failed: ${await describeFailure(res)}`);
 	return z.array(z.object({
 		id: z.string(),
-		title: z.string()
+		title: z.string().nullable()
 	})).parse(await res.json());
 });
 const historySchema = z.object({
@@ -128,21 +130,23 @@ const historySchema = z.object({
 		})
 	}))
 });
+const CHAT_GONE = [
+	401,
+	403,
+	404,
+	410
+];
 /** What a past chat holds, or `null` when it's gone or belongs to someone else. */
 const loadAgentChatFn = createServerFn({ method: "POST" }).validator(z.object({
 	agentId: z.string().min(1),
 	sessionId: z.string().min(1)
 })).handler(async ({ data }) => {
 	const res = await agentsFetch(`${encodeURIComponent(data.agentId)}/sessions/${encodeURIComponent(data.sessionId)}`);
-	if ([
-		401,
-		403,
-		404,
-		410
-	].includes(res.status)) return null;
+	if (CHAT_GONE.includes(res.status)) return null;
 	if (!res.ok) throw new Error(`Loading the chat failed: ${await describeFailure(res)}`);
 	return historySchema.parse(await res.json());
 });
+/** Saves the visitor's answer. `false` when the chat is gone, see `loadAgentChatFn`. */
 const decideAgentToolFn = createServerFn({ method: "POST" }).validator(z.object({
 	agentId: z.string().min(1),
 	sessionId: z.string().min(1),
@@ -159,7 +163,9 @@ const decideAgentToolFn = createServerFn({ method: "POST" }).validator(z.object(
 		method: "POST",
 		body: decision
 	});
+	if (CHAT_GONE.includes(res.status)) return false;
 	if (!res.ok) throw new Error(`Saving the answer failed: ${await describeFailure(res)}`);
+	return true;
 });
 
 //#endregion

package/dist/agent/use-agent-chat.d.ts

@@ -15,6 +15,10 @@ type AgentToolCall = {
   status: "running" | "done" | "failed" | "awaiting-approval" | "approved" | "rejected" | "awaiting-connection";
   error?: string;
   integration?: string;
+  /** Why the agent calls it, in its own words. */
+  thought?: string;
+  /** How long a finished call took. */
+  durationMs?: number;
 };
 type AgentTodo = {
   content: string;
@@ -55,6 +59,8 @@ type AgentChat = {
   messages: AgentMessage[];
   /** `thinking` until the first part of the reply arrives, `replying` until it ends. */
   status: "idle" | "thinking" | "replying";
+  /** True while a past chat loads, including the one reopened on mount. */
+  loading: boolean;
   /** Why the last request failed. Cleared by the next one. */
   error: Error | null;
   /** The chat the next message goes to, `null` for a new one. */

package/dist/agent/use-agent-chat.js

@@ -1,4 +1,5 @@
 import { assert } from "../assertions.js";
+import { useCurrentUser } from "../auth/isomorphic.js";
 import { agentChatFn, decideAgentToolFn, listAgentChatsFn, loadAgentChatFn } from "./agent-fns.js";
 import { useCallback, useEffect, useRef, useState } from "react";
 
@@ -15,8 +16,10 @@ function useAgentChat(agentId, options = {}) {
 	const [messages, setMessages] = useState([]);
 	const [live, setLive] = useState(null);
 	const [status, setStatus] = useState("idle");
+	const [loading, setLoading] = useState(false);
 	const [error, setError] = useState(null);
 	const [chatId, setChatId] = useState(null);
+	const storeKey = chatKey(agentId, useCurrentUser()?.id ?? null);
 	const chatIdRef = useRef(chatId);
 	chatIdRef.current = chatId;
 	const recordRef = useRef(options.record ?? null);
@@ -48,6 +51,7 @@ function useAgentChat(agentId, options = {}) {
 				sessionId: chatIdRef.current,
 				timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
 				pageName: document.title,
+				pageUrl: location.href,
 				record: recordRef.current
 			};
 			const form = new FormData();
@@ -67,6 +71,7 @@ function useAgentChat(agentId, options = {}) {
 				if (event.sessionId && event.sessionId !== chatIdRef.current) {
 					chatIdRef.current = event.sessionId;
 					setChatId(event.sessionId);
+					saveChatId(storeKey, event.sessionId);
 				}
 				blocks = reduceEvent(blocks, event);
 				setLive(blocks);
@@ -89,7 +94,11 @@ function useAgentChat(agentId, options = {}) {
 		abortRef.current = null;
 		commitLive(blocks);
 		setStatus("idle");
-	}, [agentId, commitLive]);
+	}, [
+		agentId,
+		storeKey,
+		commitLive
+	]);
 	const send = useCallback((text) => {
 		const trimmed = text.trim();
 		if (!trimmed) return;
@@ -117,14 +126,17 @@ function useAgentChat(agentId, options = {}) {
 		abortRef.current = null;
 		chatIdRef.current = id;
 		setChatId(id);
+		saveChatId(storeKey, id);
 		setMessages([]);
 		setLive(null);
 		setStatus("idle");
+		setLoading(false);
 		setError(null);
-	}, []);
+	}, [storeKey]);
 	const newChat = useCallback(() => reset(null), [reset]);
-	const openChat = useCallback((id) => {
+	const load = useCallback((id, restoring) => {
 		reset(id);
+		setLoading(true);
 		loadAgentChatFn({ data: {
 			agentId,
 			sessionId: id
@@ -132,14 +144,27 @@ function useAgentChat(agentId, options = {}) {
 			if (chatIdRef.current !== id) return;
 			if (history === null) {
 				reset(null);
-				setError(/* @__PURE__ */ new Error("This chat is no longer available. Start a new one."));
+				if (!restoring) setError(new Error(CHAT_GONE_MESSAGE));
 				return;
 			}
+			setLoading(false);
 			setMessages(fromHistory(history));
 		}).catch((err) => {
-			if (chatIdRef.current === id) setError(err instanceof Error ? err : new Error(String(err)));
+			if (chatIdRef.current !== id) return;
+			setLoading(false);
+			setError(err instanceof Error ? err : new Error(String(err)));
 		});
 	}, [agentId, reset]);
+	const openChat = useCallback((id) => load(id, false), [load]);
+	useEffect(() => {
+		const saved = savedChatId(storeKey);
+		if (saved) load(saved, true);
+		else newChat();
+	}, [
+		storeKey,
+		load,
+		newChat
+	]);
 	const listChats = useCallback(() => listAgentChatsFn({ data: { agentId } }), [agentId]);
 	const setToolStatus = useCallback((toolCallId, next) => {
 		const update = (blocks) => blocks.map((b) => b.type === "tool" && b.id === toolCallId ? {
@@ -164,7 +189,12 @@ function useAgentChat(agentId, options = {}) {
 			toolName: tool.name,
 			decision,
 			scope
-		} }).then(() => {
+		} }).then((saved) => {
+			if (!saved) {
+				reset(null);
+				setError(new Error(CHAT_GONE_MESSAGE));
+				return;
+			}
 			if (decision !== "APPROVE") return;
 			abortRef.current?.abort();
 			commitLive(liveRef.current);
@@ -178,7 +208,8 @@ function useAgentChat(agentId, options = {}) {
 		messages,
 		setToolStatus,
 		commitLive,
-		stream
+		stream,
+		reset
 	]);
 	const approve = useCallback((toolCallId, scope = "ONCE") => decide(toolCallId, "APPROVE", scope), [decide]);
 	const reject = useCallback((toolCallId) => decide(toolCallId, "REJECT", "ONCE"), [decide]);
@@ -189,6 +220,7 @@ function useAgentChat(agentId, options = {}) {
 			blocks: live
 		}],
 		status,
+		loading,
 		error,
 		chatId,
 		send,
@@ -231,20 +263,23 @@ function reduceEvent(blocks, event) {
 			if (event.toolName === QUESTION_TOOL) return blocks;
 			if (blocks.some((b) => b.type === "tool" && b.id === event.toolCallId)) return updateTool(blocks, event.toolCallId, (b) => b.status === "running" ? {
 				...b,
-				input: event.input ?? b.input
+				input: event.input ?? b.input,
+				thought: event.innerThought ?? b.thought
 			} : b);
 			return [...blocks, {
 				type: "tool",
 				id: event.toolCallId,
 				name: event.toolName,
 				input: event.input,
+				thought: event.innerThought,
 				integration: event.integrationType,
 				status: "running"
 			}];
 		case "TOOL_CALL_END": return updateTool(blocks, event.toolCallId, (b) => b.status === "running" || b.status === "approved" ? {
 			...b,
 			status: event.failed ? "failed" : "done",
-			error: event.errorMessage
+			error: event.errorMessage,
+			durationMs: event.durationMs
 		} : b);
 		case "TOOL_PERMISSION_REQUEST":
 		case "INTEGRATION_AUTH_REQUEST": {
@@ -343,6 +378,8 @@ function fromHistory(history) {
 				id: call.id,
 				name: call.toolName,
 				input: call.input,
+				thought: call.metadata.innerThought ?? void 0,
+				durationMs: call.metadata.durationMs ?? void 0,
 				status: call.metadata.failed ? "failed" : "done"
 			});
 		}
@@ -357,6 +394,21 @@ function fromHistory(history) {
 		};
 	});
 }
+const CHAT_GONE_MESSAGE = "This chat is no longer available. Start a new one.";
+const chatKey = (agentId, userId) => `softr-agent-chat:${agentId}:${userId ?? "visitor"}`;
+function savedChatId(key) {
+	try {
+		return localStorage.getItem(key);
+	} catch {
+		return null;
+	}
+}
+function saveChatId(key, chatId) {
+	try {
+		if (chatId) localStorage.setItem(key, chatId);
+		else localStorage.removeItem(key);
+	} catch {}
+}
 async function failureMessage(res) {
 	const body = await res.json().catch(() => null);
 	if (typeof body === "object" && body !== null && "message" in body && typeof body.message === "string") return body.message;

package/dist/default-error-overlay.d.ts

@@ -1,4 +1,4 @@
-import * as react6 from "react";
+import * as react4 from "react";
 
 //#region src/default-error-overlay.d.ts
 type Props = {
@@ -8,6 +8,6 @@ type Props = {
 declare function DefaultErrorOverlay({
   error,
   reset
-}: Props): react6.JSX.Element;
+}: Props): react4.JSX.Element;
 //#endregion
 export { DefaultErrorOverlay };

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.87-alpha.4";
+var version = "0.0.87-alpha.5";
 
 //#endregion
 export { version };

package/dist/pwa.d.ts

@@ -1,4 +1,4 @@
-import * as react4 from "react";
+import * as react5 from "react";
 import "@tanstack/react-start";
 
 //#region src/pwa.d.ts
@@ -23,7 +23,7 @@ import "@tanstack/react-start";
  *   )
  * }
  */
-declare function SoftrPwaHead(): react4.FunctionComponentElement<react4.FragmentProps>;
+declare function SoftrPwaHead(): react5.FunctionComponentElement<react5.FragmentProps>;
 type PwaPlatform = "ios" | "android" | "desktop";
 type PwaInstall = {
   available: false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.87-alpha.4",
+  "version": "0.0.87-alpha.5",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },

package/skills/softr-sdk/SKILL.md

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.87-alpha.4
+  library_version: 0.0.87-alpha.5
 ---
 
 # Softr SDK core

package/skills/softr-sdk/agent-chat/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87-alpha.4
+  library_version: 0.0.87-alpha.5
 ---
 
 **Boundary.** `listAgents` and `useAgentChat` live on `@softr/sdk`. `listAgents` runs in a route loader, `useAgentChat` in a component. Neither needs a route, server function or registration of its own. It chats as the signed-in visitor, or anonymously when no one is signed in.
@@ -58,9 +58,10 @@ function AgentPanel({ agentId, ticket }: { agentId: string; ticket: Ticket | nul
 
 - `messages`: the whole chat, oldest first. While the agent answers, its reply is the last message and grows as it streams.
 - `status`: `thinking` until the first part of the reply arrives, `replying` until it ends, then `idle`. Show a typing hint while it's `thinking`.
+- `loading`: `true` while a past chat loads. Show a spinner, not the empty-chat greeting.
 - `error`: why the last request failed, or `null`.
 - `send(text)`, `stop()`, `newChat()`.
-- `listChats()` resolves to the visitor's past chats, `{ id, title }[]`. `openChat(id)` loads one. `chatId` is the open one, `null` for a new chat.
+- `listChats()` resolves to the visitor's past chats, `{ id, title }[]`, with `title` `null` until the agent names the chat. `openChat(id)` loads one. `chatId` is the open one, `null` for a new chat. The open chat is kept in the browser for each visitor, so the hook reopens it after a remount or a reload.
 - `approve(toolCallId, scope?)` and `reject(toolCallId)` answer a tool waiting for approval. `scope` is `ONCE` (default), `SESSION` for the rest of this chat, or `USER` for always.
 
 ## Rendering a message
@@ -70,7 +71,7 @@ Each message has `role` (`user` or `assistant`) and `blocks`, in the order the a
 | Block | Show it as |
 | --- | --- |
 | `text` | Markdown text |
-| `tool` | One line: the tool `name` and its `status`. Collapse finished ones. |
+| `tool` | One line: the tool `name` and its `status`. Collapse finished ones. Expanded, show `thought`, `input`, `error` and `durationMs`. |
 | `todo` | A checklist of the agent's plan. It updates in place. |
 | `question` | The questions with their options. A click on an option sends its label with `send`. |
 | `error` | An error line inside the reply |
@@ -79,11 +80,25 @@ A `tool` with status `awaiting-approval` blocks the agent until the visitor answ
 
 A `tool` with status `awaiting-connection` needs the visitor to connect the `integration` first. Code apps can't do that yet. Say which integration the agent needs, and that the builder has to connect it for this agent in Studio.
 
+## The chat panel
+
+Classic Softr apps ship a chat panel. Visitors expect the same from yours:
+
+- A round button in a corner opens it. A right-side panel on desktop, full screen on mobile.
+- The header shows the agent's avatar and name, a picker when there are several agents, new chat, past chats and close.
+- An empty chat greets the visitor with the agent's avatar.
+- The list scrolls to the newest message as the reply streams, until the visitor scrolls up. Then a button takes them back down.
+- Text renders as Markdown, tables included.
+- The input says "Ask {agent title}…". Enter sends. Shift+Enter adds a line.
+- A line under the input: "AI can make mistakes. Please double-check responses."
+- A question with one choice sends on click. One with `multiSelect` or several questions sends once all are answered. An answered question stays locked.
+- Approve offers the three scopes: once, for this chat, always for this agent.
+
 ## Context
 
 `record` is the one record the visitor is looking at, so they can say "close this one". Pass it where a page shows one record, and `null` elsewhere. Use readable field names as keys. The agent reads them as they are.
 
-The page title goes along on its own. Nothing else about the page does, so don't try to send whole lists.
+The page title and URL go along on their own. Nothing else about the page does, so don't try to send whole lists.
 
 ## Letting the agent act on the app
 
@@ -95,6 +110,8 @@ The agent reads and changes data through the app's own MCP, as the visitor who i
 
 **Rendering only `text` blocks.** A tool waiting for approval never shows, and the agent waits forever. Render every block type.
 
+**The hook inside a panel that unmounts when it closes.** Closing it stops a reply that is still coming. Call `useAgentChat` in the component that owns the open state, such as the layout, and pass `chat` into the panel. Keep the selected agent there too, or closing the panel resets it.
+
 **An agent id written by hand.** The chat fails on the first message, and an agent hidden from the visitor still shows. Take the id from `listAgents`.
 
 **Expecting the agent to change data with no MCP wired.** It answers but can't act. List the actions it needs in `softrMcpMiddleware`.

package/skills/softr-sdk/auth/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87-alpha.4
+  library_version: 0.0.87-alpha.5
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.

package/skills/softr-sdk/charts-and-metrics/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87-alpha.4
+  library_version: 0.0.87-alpha.5
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/current-user/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87-alpha.4
+  library_version: 0.0.87-alpha.5
 ---
 
 # The current user

package/skills/softr-sdk/file-uploads/SKILL.md

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87-alpha.4
+  library_version: 0.0.87-alpha.5
 ---
 
 **Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk` and run in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/formatting/SKILL.md

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87-alpha.4
+  library_version: 0.0.87-alpha.5
 ---
 
 # Dates, times and numbers

package/skills/softr-sdk/integrations/SKILL.md

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87-alpha.4
+  library_version: 0.0.87-alpha.5
 ---
 
 **Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineIntegration` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/mcp/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87-alpha.4
+  library_version: 0.0.87-alpha.5
 ---
 
 **Boundary.** `softrMcpMiddleware` lives on `@softr/sdk` and is registered once, in `src/start.ts`. The actions you hand it are the same `defineQuery` / `defineMutation` values the app's own pages use — declared wherever they already live, not duplicated for MCP.

package/skills/softr-sdk/pwa/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87-alpha.4
+  library_version: 0.0.87-alpha.5
 ---
 
 # Installing the app

package/skills/softr-sdk/record-mutations/SKILL.md

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87-alpha.4
+  library_version: 0.0.87-alpha.5
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineMutation` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/record-queries/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87-alpha.4
+  library_version: 0.0.87-alpha.5
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. The same holds for any helper that calls `ds`: declare it inside the handler. A function at module level that calls `ds` keeps the server-only import in the browser bundle, and every page stops loading until it moves. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/region-visibility/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87-alpha.4
+  library_version: 0.0.87-alpha.5
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

package/skills/softr-sdk/routes-and-visibility/SKILL.md

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87-alpha.4
+  library_version: 0.0.87-alpha.5
 ---
 
 **Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.

package/skills/softr-sdk/workflows/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87-alpha.4
+  library_version: 0.0.87-alpha.5
 ---
 
 **Boundary.** `workflow` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineWorkflow` and every type come from `@softr/sdk` and can be imported anywhere.