@softr/sdk 0.0.85 → 0.0.87-alpha.0

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

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import "@tanstack/react-start";
+
+//#region src/agent/agent-fns.d.ts
+
+/** One past chat with an agent. */
+type AgentChatSummary = {
+  id: string;
+  title: string;
+};
+//#endregion
+export { AgentChatSummary };

package/dist/agent/agent-fns.js

@@ -0,0 +1,148 @@
+import { assert } from "../assertions.js";
+import { fetch } from "../fetch.js";
+import { sessionConfig } from "../auth/config.js";
+import { readSessionToken } from "../auth/session.js";
+import { softrApiUrl } from "../softr-api.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";
+/**
+* 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 `platform-api`.
+*/
+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.hostname.startsWith("platform-api"), () => `can't tell the agents API from ${platform.origin}, set SOFTR_AGENTS_API_URL`);
+	platform.hostname = platform.hostname.replace(/^platform-api/, "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(),
+	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,
+				...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 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()
+	})).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()
+		})
+	}))
+});
+/** 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 (!res.ok) throw new Error(`Loading the chat failed: ${await describeFailure(res)}`);
+	return historySchema.parse(await res.json());
+});
+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 (!res.ok) throw new Error(`Saving the answer failed: ${await describeFailure(res)}`);
+});
+
+//#endregion
+export { agentChatFn, decideAgentToolFn, listAgentChatsFn, loadAgentChatFn };

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

@@ -0,0 +1,94 @@
+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`
+   * needs the visitor to connect `integration` first, which code apps can't do yet.
+   */
+  status: "running" | "done" | "failed" | "awaiting-approval" | "approved" | "rejected" | "awaiting-connection";
+  error?: string;
+  integration?: string;
+};
+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. */
+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";
+  /** 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 this chat, or always for this visitor. */
+  approve: (toolCallId: string, scope?: "ONCE" | "SESSION" | "USER") => void;
+  reject: (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,367 @@
+import { assert } from "../assertions.js";
+import { agentChatFn, decideAgentToolFn, listAgentChatsFn, loadAgentChatFn } 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 [error, setError] = useState(null);
+	const [chatId, setChatId] = useState(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,
+				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);
+				}
+				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, 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);
+		setMessages([]);
+		setLive(null);
+		setStatus("idle");
+		setError(null);
+	}, []);
+	const newChat = useCallback(() => reset(null), [reset]);
+	const openChat = useCallback((id) => {
+		reset(id);
+		loadAgentChatFn({ data: {
+			agentId,
+			sessionId: id
+		} }).then((history) => {
+			if (chatIdRef.current !== id) return;
+			if (history === null) {
+				reset(null);
+				setError(/* @__PURE__ */ new Error("This chat is no longer available. Start a new one."));
+				return;
+			}
+			setMessages(fromHistory(history));
+		}).catch((err) => {
+			if (chatIdRef.current === id) setError(err instanceof Error ? err : new Error(String(err)));
+		});
+	}, [agentId, reset]);
+	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(() => {
+			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
+	]);
+	const approve = useCallback((toolCallId, scope = "ONCE") => decide(toolCallId, "APPROVE", scope), [decide]);
+	const reject = useCallback((toolCallId) => decide(toolCallId, "REJECT", "ONCE"), [decide]);
+	return {
+		messages: live === null ? messages : [...messages, {
+			id: "live",
+			role: "assistant",
+			blocks: live
+		}],
+		status,
+		error,
+		chatId,
+		send,
+		stop,
+		newChat,
+		openChat,
+		listChats,
+		approve,
+		reject
+	};
+}
+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
+			} : b);
+			return [...blocks, {
+				type: "tool",
+				id: event.toolCallId,
+				name: event.toolName,
+				input: event.input,
+				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
+		} : 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,
+				status: call.metadata.failed ? "failed" : "done"
+			});
+		}
+		if (m.content) blocks.push({
+			type: "text",
+			text: m.content
+		});
+		return {
+			id: m.id,
+			role: "assistant",
+			blocks
+		};
+	});
+}
+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/core/options.js

@@ -53,9 +53,13 @@ async function listOptions(query, { label, term = "", offset = null, limit = 20
 		nextOffset: page.nextOffset
 	};
 }
-/** The text a label field holds: its own text, or the label of the choice or record it names. */
+/**
+* The text a label field holds: its own text, or the label of the choice or record it names.
+* A multi-value field, such as a lookup, joins the labels of its values.
+*/
 function labelOf(value) {
 	if (value === null || value === void 0) return "";
+	if (Array.isArray(value)) return value.map(labelOf).filter((text) => text !== "").join(", ");
 	if (typeof value === "object") {
 		const label = value.label;
 		return typeof label === "string" ? label : "";

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 { AgentChatSummary } 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 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, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAgentChat, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };

package/dist/index.js

@@ -12,6 +12,7 @@ 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 { 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, 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_start5 from "@tanstack/react-start";
+import * as _tanstack_react_start0 from "@tanstack/react-start";
 
 //#region src/mcp.d.ts
 
@@ -31,6 +31,6 @@ type SoftrMcpOptions = {
  *   ],
  * }))
  */
-declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start5.RequestMiddlewareAfterServer<{}, undefined, undefined>;
+declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>;
 //#endregion
 export { softrMcpMiddleware };

package/dist/mcp.js

@@ -385,8 +385,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.85";
+var version = "0.0.87-alpha.0";
 
 //#endregion
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.85",
+  "version": "0.0.87-alpha.0",
   "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.85
+  library_version: 0.0.86
 ---
 
 # Softr SDK core
@@ -48,6 +48,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) |
 
@@ -84,6 +85,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?
+  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,103 @@
+---
+name: agent-chat
+description: >-
+  Let visitors chat with one of the app's Softr agents: useAgentChat(agentId,
+  { record }) from @softr/sdk returns the messages, the reply as it streams,
+  and send, stop, approve and reject, with no UI. Build the chat from the app's
+  own components. The agent acts on the app's data through the app's MCP, so
+  softrMcpMiddleware must list the actions it may use.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.86
+---
+
+**Boundary.** `useAgentChat` lives on `@softr/sdk` and runs in a component. It needs no 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. The app gives it a chat. There is no ready-made chat widget: the hook gives the state, and the app draws it with its own components.
+
+## Setup
+
+```ts
+import { useAgentChat } from '@softr/sdk'
+```
+
+The agent id is a string from Studio. Ask the builder for it if you don't have it, and write it as a literal. Never guess or invent one.
+
+## Core pattern
+
+```tsx
+function AgentPanel({ ticket }: { ticket: Ticket | null }) {
+  const chat = useAgentChat('a1b2c3d4-...', {
+    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`.
+- `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.
+- `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
+
+Each message has `role` (`user` or `assistant`) and `blocks`, in the order the agent produced them. Render every block type:
+
+| Block | Show it as |
+| --- | --- |
+| `text` | Markdown text |
+| `tool` | One line: the tool `name` and its `status`. Collapse finished ones. |
+| `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 |
+
+A `tool` with status `awaiting-approval` blocks the agent until the visitor answers. Show Approve and Reject buttons on it. The agent continues on its own after an approval.
+
+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.
+
+## 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.
+
+## 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. Their groups and each action's `permissions` apply. The actions it may use are the ones listed in `softrMcpMiddleware`. With no MCP wired, the agent can only talk. Load [mcp/SKILL.md](../mcp/SKILL.md) to wire it.
+
+## 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`.
+
+**Rendering only `text` blocks.** A tool waiting for approval never shows, and the agent waits forever. Render every block type.
+
+**An invented agent id.** The chat fails on the first message. Use the id from Studio.
+
+**Expecting the agent to change data with no MCP wired.** It answers but can't act. List the actions it needs in `softrMcpMiddleware`.
+
+## 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.85
+  library_version: 0.0.86
 ---
 
 **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.85
+  library_version: 0.0.86
 ---
 
 **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.85
+  library_version: 0.0.86
 ---
 
 # 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.85
+  library_version: 0.0.86
 ---
 
 **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.85
+  library_version: 0.0.86
 ---
 
 # 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.85
+  library_version: 0.0.86
 ---
 
 **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.85
+  library_version: 0.0.86
 ---
 
 **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.85
+  library_version: 0.0.86
 ---
 
 # 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.85
+  library_version: 0.0.86
 ---
 
 **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.85
+  library_version: 0.0.86
 ---
 
 **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.85
+  library_version: 0.0.86
 ---
 
 **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.85
+  library_version: 0.0.86
 ---
 
 **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.85
+  library_version: 0.0.86
 ---
 
 **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.