@softr/sdk 0.0.90-alpha.4 → 0.0.90-alpha.6

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

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import * as _tanstack_react_start8 from "@tanstack/react-start";
+
+//#region src/agent/agent-fns.d.ts
+
+declare const agentSchema: z.ZodObject<{
+  id: z.ZodString;
+  title: z.ZodString;
+  avatar: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  thumbnail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/** An agent the visitor may chat with. */
+type Agent = z.infer<typeof agentSchema>;
+/**
+ * The agents the visitor may chat with in this app. The builder attaches them
+ * in Studio, and each one's visibility settings decide who sees it.
+ */
+declare const listAgents: _tanstack_react_start8.OptionalFetcher<undefined, undefined, Promise<{
+  id: string;
+  title: string;
+  avatar?: string | null | undefined;
+  thumbnail?: string | null | undefined;
+}[]>>;
+/** One past chat with an agent. `title` is null until the agent names the chat. */
+type AgentChatSummary = {
+  id: string;
+  title: string | null;
+};
+//#endregion
+export { Agent, AgentChatSummary, listAgents };

package/dist/agent/agent-fns.js

@@ -0,0 +1,215 @@
+import { assert } from "../assertions.js";
+import { softrApiUrl } from "../softr-api.js";
+import { fetch } from "../fetch.js";
+import { sessionConfig } from "../auth/config.js";
+import { readSessionToken } from "../auth/session.js";
+import { describeFailure, refererHeader } from "../datasource/record.js";
+import { z } from "zod";
+import { createServerFn } from "@tanstack/react-start";
+import { getRequest } from "@tanstack/react-start/server";
+
+//#region src/agent/agent-fns.ts
+const AGENTS_PRODUCTION = "https://agents-api.softr.io";
+const PLATFORM_HOST = /^(platform-api|platform-preview-api|preview-api)(?=[.-])/;
+/**
+* Where the agents service is. It sits next to the platform API, so unless
+* `SOFTR_AGENTS_API_URL` says otherwise, it's the platform's host with
+* `agents-api` in place of the platform's name. Live and preview share one
+* agents service.
+*/
+function agentsApiUrl() {
+	const explicit = process.env.SOFTR_AGENTS_API_URL;
+	if (explicit) return explicit.replace(/\/+$/, "");
+	if (!process.env.SOFTR_PLATFORM_API_URL) return AGENTS_PRODUCTION;
+	const platform = new URL(softrApiUrl("SOFTR_PLATFORM_API_URL"));
+	assert(PLATFORM_HOST.test(platform.hostname), () => `can't tell the agents API from ${platform.origin}, set SOFTR_AGENTS_API_URL`);
+	platform.hostname = platform.hostname.replace(PLATFORM_HOST, "agents-api");
+	return platform.origin;
+}
+function agentsFetch(path, init = {}) {
+	const token = readSessionToken();
+	return fetch(`${agentsApiUrl()}/v1/agents/${path}`, {
+		method: init.method ?? "GET",
+		signal: init.signal,
+		headers: {
+			"Content-Type": "application/json",
+			...token ? { Authorization: `Bearer ${token}` } : {},
+			"Softr-Application-ID": sessionConfig().applicationId,
+			...refererHeader(),
+			...init.headers
+		},
+		body: init.body === void 0 ? void 0 : JSON.stringify(init.body)
+	});
+}
+const chatSchema = z.object({
+	agentId: z.string().min(1),
+	message: z.string(),
+	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())
+	}).nullable()
+});
+/**
+* Sends one message and streams the reply back as it comes, one JSON event per line.
+*
+* Takes FormData so the browser can call it with plain `fetch` and read the
+* stream itself. A failed call passes the agents service's status and message on.
+*/
+const agentChatFn = createServerFn({ method: "POST" }).validator((data) => {
+	const payload = data.get("payload");
+	assert(typeof payload === "string", "agent chat: payload is required");
+	return chatSchema.parse(JSON.parse(payload));
+}).handler(async ({ data }) => {
+	const upstream = await agentsFetch(`${encodeURIComponent(data.agentId)}/chat`, {
+		method: "POST",
+		signal: getRequest().signal,
+		headers: {
+			Accept: "application/x-ndjson",
+			"X-User-Timezone": data.timezone
+		},
+		body: {
+			message: data.message,
+			...data.sessionId ? { sessionId: data.sessionId } : {},
+			context: {
+				pageName: data.pageName,
+				pageUrl: data.pageUrl,
+				...data.record ? { currentRecord: { data: data.record } } : {}
+			}
+		}
+	});
+	return new Response(upstream.body, {
+		status: upstream.status,
+		headers: { "Content-Type": upstream.headers.get("Content-Type") ?? "application/x-ndjson" }
+	});
+});
+const agentSchema = z.object({
+	id: z.string(),
+	title: z.string(),
+	avatar: z.string().nullish(),
+	thumbnail: z.string().nullish()
+});
+/**
+* The agents the visitor may chat with in this app. The builder attaches them
+* in Studio, and each one's visibility settings decide who sees it.
+*/
+const listAgents = createServerFn({ method: "GET" }).handler(async () => {
+	const token = readSessionToken();
+	const res = await fetch(`${softrApiUrl("SOFTR_PLATFORM_API_URL")}/v1/vibe/applications/${sessionConfig().applicationId}/agents`, { headers: token ? { Authorization: `Bearer ${token}` } : {} });
+	if (!res.ok) throw new Error(`Loading agents failed: ${await describeFailure(res)}`);
+	return z.array(agentSchema).parse(await res.json());
+});
+const listAgentChatsFn = createServerFn({ method: "POST" }).validator(z.object({ agentId: z.string().min(1) })).handler(async ({ data }) => {
+	const res = await agentsFetch(`${encodeURIComponent(data.agentId)}/sessions`);
+	if (!res.ok) throw new Error(`Loading chats failed: ${await describeFailure(res)}`);
+	return z.array(z.object({
+		id: z.string(),
+		title: z.string().nullable()
+	})).parse(await res.json());
+});
+const historySchema = z.object({
+	messages: z.array(z.object({
+		id: z.string(),
+		role: z.enum(["USER", "ASSISTANT"]),
+		content: z.string(),
+		createdAt: z.number()
+	})),
+	toolCalls: z.array(z.object({
+		id: z.string(),
+		messageId: z.string(),
+		toolName: z.string(),
+		input: z.string(),
+		createdAt: z.number(),
+		metadata: z.object({
+			innerThought: z.string().nullish(),
+			durationMs: z.number().nullish(),
+			failed: z.boolean().nullish()
+		})
+	}))
+});
+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 (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),
+	toolCallId: z.string().min(1),
+	toolName: z.string().min(1),
+	decision: z.enum(["APPROVE", "REJECT"]),
+	scope: z.enum([
+		"ONCE",
+		"SESSION",
+		"USER"
+	])
+})).handler(async ({ data: { agentId,...decision } }) => {
+	const res = await agentsFetch(`${encodeURIComponent(agentId)}/tool-permission-decisions`, {
+		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;
+});
+const connectionSchema = z.object({
+	integration: z.string().min(1),
+	requestId: z.string().min(1)
+});
+function connectionUrl({ integration, requestId }, step) {
+	const { applicationId } = sessionConfig();
+	const provider = encodeURIComponent(integration.toLowerCase());
+	return `${`${softrApiUrl("SOFTR_DATASOURCE_API_URL")}/v1/datasource/applications/${applicationId}`}/integrations/${provider}/oauth/${step}?${new URLSearchParams({ requestId })}`;
+}
+/** The sign-in page to open in the popup. */
+const startAgentConnectionFn = createServerFn({ method: "POST" }).validator(connectionSchema).handler(async ({ data }) => {
+	const token = readSessionToken();
+	const res = await fetch(connectionUrl(data, "register"), {
+		method: "POST",
+		headers: {
+			...token ? { Authorization: `Bearer ${token}` } : {},
+			...refererHeader()
+		}
+	});
+	if (!res.ok) throw new Error(`Starting the connection failed: ${await describeFailure(res)}`);
+	return z.object({ url: z.string() }).parse(await res.json()).url;
+});
+/** Waits a while for the visitor to finish signing in. `false` when they haven't yet. */
+const awaitAgentConnectionFn = createServerFn({ method: "POST" }).validator(connectionSchema).handler(async ({ data }) => {
+	const res = await fetch(connectionUrl(data, "register-result"), { signal: getRequest().signal });
+	if (res.status === 503) return false;
+	if (!res.ok) throw new Error(`Connecting failed: ${await describeFailure(res)}`);
+	return true;
+});
+/** Tells the agent the account is connected. `false` when the chat is gone, see `loadAgentChatFn`. */
+const finishAgentConnectionFn = createServerFn({ method: "POST" }).validator(z.object({
+	agentId: z.string().min(1),
+	sessionId: z.string().min(1),
+	toolCallId: z.string().min(1)
+})).handler(async ({ data: { agentId,...completion } }) => {
+	const res = await agentsFetch(`${encodeURIComponent(agentId)}/integration-auth-completions`, {
+		method: "POST",
+		body: completion
+	});
+	if (CHAT_GONE.includes(res.status)) return false;
+	if (!res.ok) throw new Error(`Finishing the connection failed: ${await describeFailure(res)}`);
+	return true;
+});
+
+//#endregion
+export { agentChatFn, awaitAgentConnectionFn, decideAgentToolFn, finishAgentConnectionFn, listAgentChatsFn, listAgents, loadAgentChatFn, startAgentConnectionFn };

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

@@ -0,0 +1,106 @@
+import { AgentChatSummary } from "./agent-fns.js";
+
+//#region src/agent/use-agent-chat.d.ts
+/** A step of the agent's work: a tool it calls, and where that call stands. */
+type AgentToolCall = {
+  type: "tool";
+  id: string;
+  name: string;
+  /** The tool's input as the agent sent it, usually JSON. */
+  input?: string;
+  /**
+   * `awaiting-approval` waits for `approve` or `reject`. `awaiting-connection`
+   * waits for the visitor to `connect` their own `integration` account, and is
+   * `connecting` while they sign in.
+   */
+  status: "running" | "done" | "failed" | "awaiting-approval" | "approved" | "rejected" | "awaiting-connection" | "connecting";
+  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;
+  status: "pending" | "in_progress" | "completed";
+};
+type AgentQuestion = {
+  question: string;
+  header: string;
+  options: Array<{
+    label: string;
+    description: string;
+  }>;
+  multiSelect: boolean;
+};
+/**
+ * One piece of a message, in the order the agent produced it. A tool waiting for
+ * the visitor comes last, below the text that asks for it, until they answer.
+ */
+type AgentBlock = {
+  type: "text";
+  text: string;
+} | AgentToolCall
+/** The agent's plan. It replaces itself as the agent works through it. */ | {
+  type: "todo";
+  todos: AgentTodo[];
+}
+/** The agent asks the visitor to pick. They answer by sending a message. */ | {
+  type: "question";
+  questions: AgentQuestion[];
+} | {
+  type: "error";
+  message: string;
+};
+type AgentMessage = {
+  id: string;
+  role: "user" | "assistant";
+  blocks: AgentBlock[];
+};
+type AgentChat = {
+  /** The whole chat, oldest first. While the agent replies, its reply is the last one and grows. */
+  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. */
+  chatId: string | null;
+  send: (text: string) => void;
+  /** Stops the reply. What arrived so far stays. */
+  stop: () => void;
+  newChat: () => void;
+  /** Opens a past chat from `listChats`. */
+  openChat: (chatId: string) => void;
+  /** The visitor's past chats with this agent. */
+  listChats: () => Promise<AgentChatSummary[]>;
+  /** Lets a tool waiting for approval run: once, for the rest of this chat, or for this agent from now on. */
+  approve: (toolCallId: string, scope?: "ONCE" | "SESSION" | "USER") => void;
+  reject: (toolCallId: string) => void;
+  /** Opens the sign-in for a tool's `integration` in a popup. Call it from a click, or the browser blocks the popup. */
+  connect: (toolCallId: string) => void;
+};
+type AgentChatOptions = {
+  /**
+   * The record the visitor is looking at, so they can say "this one". Sent
+   * with each message. Keys are what the agent reads, so use field names.
+   */
+  record?: {
+    id: string;
+    fields: Record<string, unknown>;
+  } | null;
+};
+/**
+ * A chat with one of the app's Softr agents, as the signed-in visitor. No UI:
+ * render `messages` with the app's own components.
+ *
+ * @example
+ * const chat = useAgentChat(AGENT_ID, { record: ticket && { id: ticket.id, fields: ticket.fields } })
+ * <form onSubmit={(e) => { e.preventDefault(); chat.send(draft) }}>
+ */
+declare function useAgentChat(agentId: string, options?: AgentChatOptions): AgentChat;
+//#endregion
+export { AgentBlock, AgentChat, AgentChatOptions, AgentMessage, AgentQuestion, AgentTodo, AgentToolCall, useAgentChat };

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

@@ -0,0 +1,486 @@
+import { assert } from "../assertions.js";
+import { useCurrentUser } from "../auth/isomorphic.js";
+import { agentChatFn, awaitAgentConnectionFn, decideAgentToolFn, finishAgentConnectionFn, listAgentChatsFn, loadAgentChatFn, startAgentConnectionFn } from "./agent-fns.js";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+//#region src/agent/use-agent-chat.ts
+/**
+* A chat with one of the app's Softr agents, as the signed-in visitor. No UI:
+* render `messages` with the app's own components.
+*
+* @example
+* const chat = useAgentChat(AGENT_ID, { record: ticket && { id: ticket.id, fields: ticket.fields } })
+* <form onSubmit={(e) => { e.preventDefault(); chat.send(draft) }}>
+*/
+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);
+	recordRef.current = options.record ?? null;
+	const liveRef = useRef(live);
+	liveRef.current = live;
+	const abortRef = useRef(null);
+	useEffect(() => () => abortRef.current?.abort(), []);
+	const commitLive = useCallback((blocks) => {
+		setLive(null);
+		if (!blocks?.some((b) => b.type !== "text" || b.text.trim())) return;
+		setMessages((prev) => [...prev, {
+			id: crypto.randomUUID(),
+			role: "assistant",
+			blocks: endRunningTools(blocks)
+		}]);
+	}, []);
+	const stream = useCallback(async (message) => {
+		abortRef.current?.abort();
+		const controller = new AbortController();
+		abortRef.current = controller;
+		setError(null);
+		setStatus("thinking");
+		let blocks = [];
+		try {
+			const request = {
+				agentId,
+				message,
+				sessionId: chatIdRef.current,
+				timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+				pageName: document.title,
+				pageUrl: location.href,
+				record: recordRef.current
+			};
+			const form = new FormData();
+			form.append("payload", JSON.stringify(request));
+			const res = await fetch(agentChatFn.url, {
+				method: "POST",
+				body: form,
+				signal: controller.signal
+			});
+			if (!res.ok) throw new Error(await failureMessage(res));
+			assert(res.body, "agent chat: the reply has no body");
+			const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
+			let buffer = "";
+			const onLine = (line) => {
+				const event = parseEvent(line);
+				if (event === null) return;
+				if (event.sessionId && event.sessionId !== chatIdRef.current) {
+					chatIdRef.current = event.sessionId;
+					setChatId(event.sessionId);
+					saveChatId(storeKey, event.sessionId);
+				}
+				blocks = reduceEvent(blocks, event);
+				setLive(blocks);
+				setStatus("replying");
+			};
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				buffer += value;
+				const lines = buffer.split("\n");
+				buffer = lines.pop() ?? "";
+				lines.forEach(onLine);
+			}
+			onLine(buffer);
+		} catch (err) {
+			if (controller.signal.aborted) return;
+			setError(err instanceof Error ? err : new Error(String(err)));
+		}
+		if (abortRef.current !== controller) return;
+		abortRef.current = null;
+		commitLive(blocks);
+		setStatus("idle");
+	}, [
+		agentId,
+		storeKey,
+		commitLive
+	]);
+	const send = useCallback((text) => {
+		const trimmed = text.trim();
+		if (!trimmed) return;
+		abortRef.current?.abort();
+		commitLive(liveRef.current);
+		setMessages((prev) => [...prev, {
+			id: crypto.randomUUID(),
+			role: "user",
+			blocks: [{
+				type: "text",
+				text: trimmed
+			}]
+		}]);
+		stream(trimmed);
+	}, [stream, commitLive]);
+	const stop = useCallback(() => {
+		if (abortRef.current === null) return;
+		abortRef.current.abort();
+		abortRef.current = null;
+		commitLive(liveRef.current);
+		setStatus("idle");
+	}, [commitLive]);
+	const reset = useCallback((id) => {
+		abortRef.current?.abort();
+		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 load = useCallback((id, restoring) => {
+		reset(id);
+		setLoading(true);
+		loadAgentChatFn({ data: {
+			agentId,
+			sessionId: id
+		} }).then((history) => {
+			if (chatIdRef.current !== id) return;
+			if (history === null) {
+				reset(null);
+				if (!restoring) setError(new Error(CHAT_GONE_MESSAGE));
+				return;
+			}
+			setLoading(false);
+			setMessages(fromHistory(history));
+		}).catch((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 ? {
+			...b,
+			status: next
+		} : b);
+		setLive((prev) => prev && update(prev));
+		setMessages((prev) => prev.map((m) => ({
+			...m,
+			blocks: update(m.blocks)
+		})));
+	}, []);
+	const decide = useCallback((toolCallId, decision, scope) => {
+		const sessionId = chatIdRef.current;
+		const tool = [...messages.flatMap((m) => m.blocks), ...liveRef.current ?? []].find((b) => b.type === "tool" && b.id === toolCallId);
+		if (sessionId === null || tool?.status !== "awaiting-approval") return;
+		setToolStatus(toolCallId, decision === "APPROVE" ? "approved" : "rejected");
+		decideAgentToolFn({ data: {
+			agentId,
+			sessionId,
+			toolCallId,
+			toolName: tool.name,
+			decision,
+			scope
+		} }).then((saved) => {
+			if (!saved) {
+				reset(null);
+				setError(new Error(CHAT_GONE_MESSAGE));
+				return;
+			}
+			if (decision !== "APPROVE") return;
+			abortRef.current?.abort();
+			commitLive(liveRef.current);
+			stream("");
+		}).catch((err) => {
+			setToolStatus(toolCallId, "awaiting-approval");
+			setError(err instanceof Error ? err : new Error(String(err)));
+		});
+	}, [
+		agentId,
+		messages,
+		setToolStatus,
+		commitLive,
+		stream,
+		reset
+	]);
+	const approve = useCallback((toolCallId, scope = "ONCE") => decide(toolCallId, "APPROVE", scope), [decide]);
+	const reject = useCallback((toolCallId) => decide(toolCallId, "REJECT", "ONCE"), [decide]);
+	const connect = useCallback((toolCallId) => {
+		const sessionId = chatIdRef.current;
+		const tool = [...messages.flatMap((m) => m.blocks), ...liveRef.current ?? []].find((b) => b.type === "tool" && b.id === toolCallId);
+		if (sessionId === null || tool?.status !== "awaiting-connection" || !tool.integration) return;
+		const popup = window.open("", "softr-agent-connect", popupFeatures(500, 600));
+		if (!popup) {
+			setError(/* @__PURE__ */ new Error("Allow pop-ups for this site to connect your account."));
+			return;
+		}
+		setToolStatus(toolCallId, "connecting");
+		const connection = {
+			integration: tool.integration,
+			requestId: crypto.randomUUID()
+		};
+		const deadline = Date.now() + CONNECT_TIMEOUT_MS;
+		(async () => {
+			popup.location.href = await startAgentConnectionFn({ data: connection });
+			while (!await awaitAgentConnectionFn({ data: connection })) {
+				if (Date.now() > deadline) throw new Error("Connecting took too long. Try again.");
+				await new Promise((resolve) => setTimeout(resolve, CONNECT_RETRY_MS));
+			}
+			popup.close();
+			if (!await finishAgentConnectionFn({ data: {
+				agentId,
+				sessionId,
+				toolCallId
+			} })) {
+				reset(null);
+				setError(new Error(CHAT_GONE_MESSAGE));
+				return;
+			}
+			setToolStatus(toolCallId, "approved");
+			abortRef.current?.abort();
+			commitLive(liveRef.current);
+			stream("");
+		})().catch((err) => {
+			popup.close();
+			setToolStatus(toolCallId, "awaiting-connection");
+			setError(err instanceof Error ? err : new Error(String(err)));
+		});
+	}, [
+		agentId,
+		messages,
+		setToolStatus,
+		commitLive,
+		stream,
+		reset
+	]);
+	return {
+		messages: (live === null ? messages : [...messages, {
+			id: "live",
+			role: "assistant",
+			blocks: live
+		}]).map(waitingLast),
+		status,
+		loading,
+		error,
+		chatId,
+		send,
+		stop,
+		newChat,
+		openChat,
+		listChats,
+		approve,
+		reject,
+		connect
+	};
+}
+const waitsForVisitor = (b) => b.type === "tool" && (b.status === "awaiting-approval" || b.status === "awaiting-connection" || b.status === "connecting");
+function waitingLast(message) {
+	if (!message.blocks.some(waitsForVisitor)) return message;
+	const blocks = [...message.blocks.filter((b) => !waitsForVisitor(b)), ...message.blocks.filter(waitsForVisitor)];
+	return {
+		...message,
+		blocks
+	};
+}
+const CONNECT_TIMEOUT_MS = 5 * 6e4;
+const CONNECT_RETRY_MS = 3e3;
+function popupFeatures(width, height) {
+	return `width=${width},height=${height},left=${window.screenX + (window.innerWidth - width) / 2},top=${window.screenY + (window.innerHeight - height) / 2}`;
+}
+const TODO_TOOL = "TodoWrite";
+/** Its question shows as a question block, so the call itself is noise. */
+const QUESTION_TOOL = "AskUserQuestion";
+function parseEvent(line) {
+	if (!line.trim()) return null;
+	try {
+		return JSON.parse(line);
+	} catch {
+		return null;
+	}
+}
+function reduceEvent(blocks, event) {
+	switch (event.type) {
+		case "TEXT": {
+			const last = blocks.at(-1);
+			return last?.type === "text" ? [...blocks.slice(0, -1), {
+				type: "text",
+				text: last.text + event.response
+			}] : [...blocks, {
+				type: "text",
+				text: event.response
+			}];
+		}
+		case "TOOL_CALL_START":
+			if (event.toolName === TODO_TOOL) {
+				const todos = parseTodos(event.input);
+				if (todos) return upsertTodos(blocks, todos);
+			}
+			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,
+				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,
+			durationMs: event.durationMs
+		} : b);
+		case "TOOL_PERMISSION_REQUEST":
+		case "INTEGRATION_AUTH_REQUEST": {
+			const status = event.type === "TOOL_PERMISSION_REQUEST" ? "awaiting-approval" : "awaiting-connection";
+			const integration = event.type === "INTEGRATION_AUTH_REQUEST" ? event.integrationType : void 0;
+			if (blocks.some((b) => b.type === "tool" && b.id === event.toolCallId)) return updateTool(blocks, event.toolCallId, (b) => ({
+				...b,
+				status,
+				integration: integration ?? b.integration,
+				input: ("input" in event ? event.input : void 0) ?? b.input
+			}));
+			return [...blocks, {
+				type: "tool",
+				id: event.toolCallId,
+				name: event.toolName,
+				input: "input" in event ? event.input : void 0,
+				integration,
+				status
+			}];
+		}
+		case "QUESTION": return [...blocks, {
+			type: "question",
+			questions: event.questions
+		}];
+		case "ERROR": return [...blocks, {
+			type: "error",
+			message: event.message
+		}];
+		default: return blocks;
+	}
+}
+function updateTool(blocks, id, update) {
+	return blocks.map((b) => b.type === "tool" && b.id === id ? update(b) : b);
+}
+/** A reply that ended without finishing a tool call, stopped or cut off, never will. */
+function endRunningTools(blocks) {
+	return blocks.map((b) => b.type === "tool" && b.status === "running" ? {
+		...b,
+		status: "failed",
+		error: "The agent stopped before this step finished."
+	} : b);
+}
+/** Each plan update re-sends the whole list, so only the latest one is kept, where the first one was. */
+function upsertTodos(blocks, todos) {
+	const index = blocks.findIndex((b) => b.type === "todo");
+	if (index === -1) return [...blocks, {
+		type: "todo",
+		todos
+	}];
+	return blocks.map((b, i) => i === index ? {
+		type: "todo",
+		todos
+	} : b);
+}
+function parseTodos(input) {
+	if (!input) return null;
+	try {
+		const parsed = JSON.parse(input);
+		if (typeof parsed !== "object" || parsed === null || !("todos" in parsed)) return null;
+		const outer = parsed.todos;
+		const raw = typeof outer === "object" && outer !== null && "todos" in outer ? outer.todos : outer;
+		if (!Array.isArray(raw)) return null;
+		const todos = raw.flatMap((item) => {
+			if (typeof item !== "object" || item === null) return [];
+			const { content, status } = item;
+			if (typeof content !== "string" || !content.trim()) return [];
+			if (status !== "pending" && status !== "in_progress" && status !== "completed") return [];
+			return [{
+				content,
+				status
+			}];
+		});
+		return todos.length > 0 ? todos : null;
+	} catch {
+		return null;
+	}
+}
+function fromHistory(history) {
+	const toolsByMessage = Map.groupBy(history.toolCalls, (call) => call.messageId);
+	return history.messages.filter((m) => m.role !== "USER" || m.content.trim()).map((m) => {
+		if (m.role === "USER") return {
+			id: m.id,
+			role: "user",
+			blocks: [{
+				type: "text",
+				text: m.content
+			}]
+		};
+		let blocks = [];
+		const calls = (toolsByMessage.get(m.id) ?? []).toSorted((a, b) => a.createdAt - b.createdAt);
+		for (const call of calls) {
+			const todos = call.toolName === TODO_TOOL ? parseTodos(call.input) : null;
+			if (todos) blocks = upsertTodos(blocks, todos);
+			else if (call.toolName !== QUESTION_TOOL) blocks.push({
+				type: "tool",
+				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"
+			});
+		}
+		if (m.content) blocks.push({
+			type: "text",
+			text: m.content
+		});
+		return {
+			id: m.id,
+			role: "assistant",
+			blocks
+		};
+	});
+}
+const CHAT_GONE_MESSAGE = "This chat is no longer available. Start a new one.";
+const VISITOR = "visitor";
+const chatKey = (agentId, userId) => `softr-code-app:agent-chat:${agentId}:${userId ?? VISITOR}`;
+function chatStore(key) {
+	return key.endsWith(`:${VISITOR}`) ? sessionStorage : localStorage;
+}
+function savedChatId(key) {
+	try {
+		return chatStore(key).getItem(key);
+	} catch {
+		return null;
+	}
+}
+function saveChatId(key, chatId) {
+	try {
+		if (chatId) chatStore(key).setItem(key, chatId);
+		else chatStore(key).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;
+	return `The agent could not answer (${res.status}).`;
+}
+
+//#endregion
+export { useAgentChat };

package/dist/auth/isomorphic.d.ts

@@ -22,7 +22,7 @@ import * as _tanstack_react_start0 from "@tanstack/react-start";
  *   requestMiddleware: [softrAuthMiddleware()],
  * }))
  */
-declare function softrAuthMiddleware(): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, readonly [_tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>], {
+declare function softrAuthMiddleware(): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, readonly [_tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>], {
   user: User | null;
   permissions: Permissions;
   formatting: Formatting;

package/dist/auth/isomorphic.js

@@ -10,7 +10,6 @@ import { bootErrorMiddleware } from "../boot-error.js";
 import { pwaMiddleware } from "../pwa.js";
 import { faviconMiddleware } from "../favicon.js";
 import { embeddingMiddleware } from "../embedding.js";
-import { appIdentityMiddleware } from "../app-identity.js";
 import { createContext, useContext } from "react";
 import { createMiddleware, createServerFn, getGlobalStartContext } from "@tanstack/react-start";
 import { getRequestHeader } from "@tanstack/react-start/server";
@@ -35,7 +34,6 @@ import { jsx } from "react/jsx-runtime";
 function softrAuthMiddleware() {
 	return createMiddleware({ type: "request" }).middleware([
 		embeddingMiddleware(),
-		appIdentityMiddleware(),
 		bootErrorMiddleware(),
 		pwaMiddleware(),
 		faviconMiddleware()

package/dist/index.d.ts

@@ -16,5 +16,7 @@ import { useOverrides } from "./core/use-overrides.js";
 import { useUserTimezone } from "./timezone.js";
 import { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall } from "./pwa.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
+import { Agent, AgentChatSummary, listAgents } from "./agent/agent-fns.js";
+import { AgentBlock, AgentChat, AgentChatOptions, AgentMessage, AgentQuestion, AgentTodo, AgentToolCall, useAgentChat } from "./agent/use-agent-chat.js";
 import { Audience } from "./route/audience.js";
-export { type ActionPermissions, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FieldShape, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type Page, type PageSettings, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type SoftrUserProperties, type User, type WeekDay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };
+export { type ActionPermissions, type Agent, type AgentBlock, type AgentChat, type AgentChatOptions, type AgentChatSummary, type AgentMessage, type AgentQuestion, type AgentTodo, type AgentToolCall, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FieldShape, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type Page, type PageSettings, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type SoftrUserProperties, type User, type WeekDay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, listAgents, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAgentChat, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };

package/dist/index.js

@@ -12,6 +12,8 @@ import { fieldShape, formatDuration, formatField, formatValue, registerSoftrFiel
 import { useOverrides } from "./core/use-overrides.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
+import { listAgents } from "./agent/agent-fns.js";
+import { useAgentChat } from "./agent/use-agent-chat.js";
 import { Audience } from "./route/audience.js";
 
-export { Audience, AuthSettingsProvider, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };
+export { Audience, AuthSettingsProvider, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, listAgents, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAgentChat, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { DatasourceAction } from "./action.js";
-import * as _tanstack_react_start0 from "@tanstack/react-start";
+import * as _tanstack_react_start6 from "@tanstack/react-start";
 
 //#region src/mcp.d.ts
 
@@ -31,6 +31,6 @@ type SoftrMcpOptions = {
  *   ],
  * }))
  */
-declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>;
+declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start6.RequestMiddlewareAfterServer<{}, undefined, undefined>;
 //#endregion
 export { softrMcpMiddleware };

package/dist/mcp.js

@@ -244,7 +244,8 @@ const WHOAMI = {
 		type: "object",
 		properties: {},
 		additionalProperties: false
-	}
+	},
+	annotations: { readOnlyHint: true }
 };
 /** How many records a read returns when the caller does not say. */
 const DEFAULT_LIMIT = 20;
@@ -265,6 +266,7 @@ function describeTool(action) {
 		case "read": return {
 			name: action.id,
 			description: `Read records from "${action.id}". Returns the fields ${names.join(", ")}. Only records the signed-in user may see come back.`,
+			annotations: { readOnlyHint: true },
 			inputSchema: {
 				type: "object",
 				properties: {
@@ -385,8 +387,10 @@ async function rpc(request, origin, actions) {
 	const token = bearerToken(request);
 	if (token === null) return unauthorized(origin);
 	const session = await platformSession(token);
-	if (!session.ok) return session.refused ? unauthorized(origin) : unavailable();
-	const { sessionToken } = session;
+	let sessionToken;
+	if (session.ok) sessionToken = session.sessionToken;
+	else if (session.refused && await resolveUser(token) !== null) sessionToken = token;
+	else return session.refused ? unauthorized(origin) : unavailable();
 	const body = await readJson(request);
 	const message = z.object({
 		id: z.union([z.string(), z.number()]).optional(),

package/dist/package.js

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

package/package.json

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

package/skills/softr-sdk/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.90-alpha.4
+  library_version: 0.0.90-alpha.6
 ---
 
 # Softr SDK core
@@ -49,6 +49,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Sign a visitor in, out, or up | [auth/SKILL.md](./auth/SKILL.md) |
 | Call a connected third-party API (Slack, Stripe, Gmail, …) | [integrations/SKILL.md](./integrations/SKILL.md) |
 | Open the app to AI assistants over MCP | [mcp/SKILL.md](./mcp/SKILL.md) |
+| Let visitors chat with a Softr agent | [agent-chat/SKILL.md](./agent-chat/SKILL.md) |
 | Let visitors install the app on their home screen | [pwa/SKILL.md](./pwa/SKILL.md) |
 | Show a date, a time or a number | [formatting/SKILL.md](./formatting/SKILL.md) |
 
@@ -85,6 +86,9 @@ Calling a connected third-party API (Slack, Stripe, Gmail, Google Calendar, …)
 Opening the app to an AI assistant over MCP?
   load softr-sdk/mcp
 
+Adding a chat with one of the app's Softr agents, or a Connect button for the visitor's account it needs?
+  load softr-sdk/agent-chat
+
 Adding an install button, or making the app installable?
   load softr-sdk/pwa
 

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

@@ -0,0 +1,109 @@
+---
+name: agent-chat
+description: >-
+  Chat with one of the app's Softr agents: listAgents() and useAgentChat(agentId,
+  { record }) from @softr/sdk give the chat state with no UI — messages, the
+  streaming reply, past chats, approve, reject, connect. Load it for an agent
+  chat, approving its actions, which records the agent may change for each
+  visitor, or connecting the visitor's account a tool needs.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.90-alpha.6
+---
+
+**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.
+
+# Agent chat
+
+A Softr agent is set up in Studio's Agents tab and attached to the app there. There is no chat widget: the hook gives the state, and the app draws it with its own components.
+
+## Setup
+
+```ts
+import { listAgents, useAgentChat } from '@softr/sdk'
+```
+
+`listAgents()` resolves to the agents this visitor may chat with, `{ id, title, avatar, thumbnail }[]`. Call it in the route's `loader`. An agent hidden from this visitor isn't in the list, so show no chat when it's empty. When there are several, let the visitor pick one, or pick the one the builder named by its `title`. Take the id from the list. A hand-written id fails on the first message, and shows an agent the visitor may not see.
+
+## Core pattern
+
+```tsx
+// agentId comes from listAgents() in the route's loader.
+function AgentPanel({ agentId, ticket }: { agentId: string; ticket: Ticket | null }) {
+  const chat = useAgentChat(agentId, {
+    record: ticket && { id: ticket.id, fields: { Title: ticket.title, Status: ticket.status } },
+  })
+  const [draft, setDraft] = useState('')
+
+  return (
+    <>
+      {chat.messages.map((message) => (
+        <Message key={message.id} message={message} onApprove={chat.approve} onReject={chat.reject} />
+      ))}
+      {chat.error && <p role="alert">{chat.error.message}</p>}
+      <form onSubmit={(e) => { e.preventDefault(); chat.send(draft); setDraft('') }}>
+        <Textarea value={draft} onChange={(e) => setDraft(e.target.value)} />
+        {chat.status === 'idle'
+          ? <Button type="submit">Send</Button>
+          : <Button type="button" onClick={chat.stop}>Stop</Button>}
+      </form>
+    </>
+  )
+}
+```
+
+## What the hook returns
+
+- `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 }[]`, 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 signed-in user, so the hook reopens it after a remount or a reload. A signed-out visitor keeps it only until the tab closes.
+- `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 this agent from now on.
+- `connect(toolCallId)` signs the visitor in to a tool's `integration` in a popup. Call it straight from the click, or the browser blocks the popup.
+
+## Rendering a message
+
+Each message has `role` (`user` or `assistant`) and `blocks`. Render every block type, in the order given. Show only `text` and a tool waiting for approval never appears, so the agent waits forever. A tool waiting for Approve or Connect comes last in its message, below the text asking for it.
+
+| Block | Show it as |
+| --- | --- |
+| `text` | Markdown, tables included |
+| `tool` | One line: the tool `name` and its `status`. Collapse finished ones. Expanded, show `thought`, `input` as `Label: value` lines (never raw JSON), `error` and `durationMs`, leaving out empty ones. |
+| `todo` | A checklist of the agent's plan. It updates in place. |
+| `question` | The questions with their options. One question with a single choice sends its label with `send` on click. Several questions, or `multiSelect`, collect the picks and show a Send button, enabled once each question has one. It sends one line per question, picked labels joined by ", ". An answered question stays locked. |
+| `error` | An error line inside the reply |
+
+A `tool` with status `awaiting-approval` blocks the agent until the visitor answers. Give it a split Approve button and a Reject button. The button says "Approve once" (`approve(id)`), and its menu offers "Approve for this session" (`approve(id, 'SESSION')`) and "Approve for this agent" (`approve(id, 'USER')`). With only one Approve, the visitor approves the same action again on every call. The agent continues on its own after an approval.
+
+A `tool` with status `awaiting-connection` needs the visitor's own `integration` account, such as their Gmail. Say "You need to connect to {integration} for this request. You'll only need to connect once.", with the name in readable case, and show a Connect button that calls `connect`. While it's `connecting`, show "Connecting…" and disable the button. The agent continues on its own once they're signed in. Every integration works the same way, so build one button, not one per integration.
+
+## 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 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
+
+The agent reads and changes data through the app's own MCP, as the visitor who is chatting, using the actions `softrMcpMiddleware` lists. With no MCP wired, the agent can only talk. Load [mcp/SKILL.md](../mcp/SKILL.md) to wire it and choose the actions.
+
+**The agent calls a listed action directly, with any input.** It skips pages and server functions. Two things guard it: the action's `permissions` say who may run it, and the app's data restrictions say which rows each user group reaches. A read returns every row the visitor may see, and an update or delete takes any id that passes both.
+
+- **By default, each visitor changes only their own records.** On a table whose rows belong to a person, such as requests or bookings, open its create, update and delete to every signed-in visitor, and let the table's data restriction narrow edit and delete to the visitor's own rows. The groups that manage everyone's records get no restriction.
+- Split an action by role only for fields one role sets. A request's status goes on its own update with `customGroups` for the managers, and the visitor's update doesn't list it. One update open to every signed-in visitor that writes the status lets an employee have the agent approve their own vacation request.
+- Don't list an update or delete on a table whose rows belong to people until its restriction is in place. Without it, the agent edits anyone's row.
+- Where the app's pages show people only their own rows, the restriction needs a view rule too. The pages' filter lives in server functions, and without the rule the agent reads everyone's rows.
+
+## Failure modes
+
+**Building a chat without the hook.** Calling the agents service from the browser fails: only the app's server can sign the request in as the visitor. Use `useAgentChat`.
+
+**The hook inside a component that unmounts when the panel closes.** Closing it stops a reply that is still coming. Call `useAgentChat` in the component that owns the panel's open state and pass `chat` down. Keep the selected agent there too, or closing the panel resets it.
+
+## References
+
+- [mcp/SKILL.md](../mcp/SKILL.md): the actions the agent may call
+- [current-user/SKILL.md](../current-user/SKILL.md): showing the chat to signed-in visitors only

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.90-alpha.4
+  library_version: 0.0.90-alpha.6
 ---
 
 **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.90-alpha.4
+  library_version: 0.0.90-alpha.6
 ---
 
 **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.90-alpha.4
+  library_version: 0.0.90-alpha.6
 ---
 
 # 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.90-alpha.4
+  library_version: 0.0.90-alpha.6
 ---
 
 **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.90-alpha.4
+  library_version: 0.0.90-alpha.6
 ---
 
 # 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.90-alpha.4
+  library_version: 0.0.90-alpha.6
 ---
 
 **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.90-alpha.4
+  library_version: 0.0.90-alpha.6
 ---
 
 **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.
@@ -53,6 +53,7 @@ The list is the whole tool surface. Write it out:
 
 - An action you leave out is invisible to the assistant, even where the app's pages use it freely.
 - An action you list still obeys its own `permissions`. Listing it does not widen who may run it — the assistant runs as whoever signed in, with that user's groups.
+- The assistant calls the action directly and skips server functions, so a row filter written in one does not apply. A listed read returns every row the user's data restrictions allow, and a listed update or delete takes any id that passes them. On a table whose rows belong to people, list an action only once a data restriction scopes the table to the user's own rows.
 - Two actions with the same `id` throw at startup. So does anything that is not a `defineQuery` or `defineMutation` value.
 
 Reads first. Add a write only when the user asked for one, and name it back to them.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.90-alpha.4
+  library_version: 0.0.90-alpha.6
 ---
 
 # 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.90-alpha.4
+  library_version: 0.0.90-alpha.6
 ---
 
 **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.90-alpha.4
+  library_version: 0.0.90-alpha.6
 ---
 
 **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.90-alpha.4
+  library_version: 0.0.90-alpha.6
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.90-alpha.4
+  library_version: 0.0.90-alpha.6
 ---
 
 **Boundary.** `definePage`, `pageHead`, 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.90-alpha.4
+  library_version: 0.0.90-alpha.6
 ---
 
 **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.

package/dist/app-identity.js

@@ -1,76 +0,0 @@
-import { version } from "./package.js";
-import { assert } from "./assertions.js";
-import { createMiddleware } from "@tanstack/react-start";
-
-//#region src/app-identity.ts
-const HTML_TAG = new TextEncoder().encode("<html");
-const HTML_TAG_SEARCH_LIMIT = 1024;
-/**
-* Marks every HTML page with the Softr app it belongs to and the SDK version it
-* runs on, so support can read both from the page source.
-*
-* They go on `<html>` as `data-appid` and `data-sdk-version`, and
-* in a comment just before it. React keeps the attributes when it hydrates, but
-* drops them if it ever renders the document again on the client. The comment
-* sits outside what React owns, so it always stays.
-*/
-function appIdentityMiddleware() {
-	return createMiddleware({ type: "request" }).server(async ({ next }) => {
-		const result = await next();
-		const { response } = result;
-		if (!response.body || !response.headers.get("content-type")?.startsWith("text/html")) return result;
-		const applicationId = process.env.SOFTR_APPLICATION_ID;
-		if (!applicationId) return result;
-		assert(/^[\w-]+$/.test(applicationId), `SOFTR_APPLICATION_ID is not an id: "${applicationId}"`);
-		const encoder = new TextEncoder();
-		const comment = encoder.encode(`<!-- Softr app ${applicationId}, @softr/sdk ${version} -->`);
-		const attributes = encoder.encode(` data-appid="${applicationId}" data-sdk-version="${version}"`);
-		let held = new Uint8Array(0);
-		let done = false;
-		const body = response.body.pipeThrough(new TransformStream({
-			transform(chunk, controller) {
-				if (done) {
-					controller.enqueue(chunk);
-					return;
-				}
-				const bytes = new Uint8Array(held.length + chunk.length);
-				bytes.set(held);
-				bytes.set(chunk, held.length);
-				let at = -1;
-				search: for (let i = 0; i + HTML_TAG.length < bytes.length; i++) {
-					for (let j = 0; j < HTML_TAG.length; j++) if (bytes[i + j] !== HTML_TAG[j]) continue search;
-					const after = bytes[i + HTML_TAG.length];
-					if (after === 32 || after === 62) {
-						at = i;
-						break;
-					}
-				}
-				if (at === -1) {
-					if (bytes.length > HTML_TAG_SEARCH_LIMIT) {
-						done = true;
-						controller.enqueue(bytes);
-						return;
-					}
-					held = bytes;
-					return;
-				}
-				done = true;
-				const end = at + HTML_TAG.length;
-				controller.enqueue(bytes.subarray(0, at));
-				controller.enqueue(comment);
-				controller.enqueue(bytes.subarray(at, end));
-				controller.enqueue(attributes);
-				controller.enqueue(bytes.subarray(end));
-			},
-			flush(controller) {
-				if (!done) controller.enqueue(held);
-			}
-		}));
-		const marked = new Response(body, response);
-		marked.headers.delete("content-length");
-		return marked;
-	});
-}
-
-//#endregion
-export { appIdentityMiddleware };