@softr/sdk 0.0.88-signing.0 → 0.0.89-alpha.0

package/dist/core/file-upload.js

@@ -1,7 +1,7 @@
-import { softrApiUrl } from "../softr-api.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 { randomUUID } from "node:crypto";
 
 //#region src/core/file-upload.ts

package/dist/core/workflow.js

@@ -1,7 +1,7 @@
-import { softrApiUrl } from "../softr-api.js";
 import { fetch } from "../fetch.js";
 import { sessionConfig } from "../auth/config.js";
 import { readSessionToken } from "../auth/session.js";
+import { softrApiUrl } from "../softr-api.js";
 
 //#region src/core/workflow.ts
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/dist/datasource/record.js

@@ -1,8 +1,8 @@
 import { assert, panic } from "../assertions.js";
-import { softrApiUrl } from "../softr-api.js";
 import { fetch } from "../fetch.js";
 import { readUserTimezone } from "../cookies.js";
 import { readSessionToken } from "../auth/session.js";
+import { softrApiUrl } from "../softr-api.js";
 import { isDatasourceAction } from "../action.js";
 import { buildFilterCriteria, buildOrderBy, dealiasFilterCriteria, dealiasOrderBy } from "./filter.js";
 import { andAll, makeFieldSet, makeSortSet } from "./fields.js";

package/dist/embedding.js

@@ -0,0 +1,33 @@
+import { softrConfig } from "./softr-config.js";
+import { createMiddleware } from "@tanstack/react-start";
+
+//#region src/embedding.ts
+/**
+* Stops other sites from showing the published app in an iframe. The origins
+* softr.json lists in `allowEmbedding` still can.
+*
+* Production only. The dev server runs in the preview pod, and Studio shows
+* that preview in an iframe on another site.
+*/
+function embeddingMiddleware() {
+	return createMiddleware({ type: "request" }).server(async ({ next }) => {
+		const result = await next();
+		if (process.env.NODE_ENV !== "production") return result;
+		const policy = [
+			"frame-ancestors",
+			"'self'",
+			...softrConfig().allowEmbedding ?? []
+		].join(" ");
+		try {
+			result.response.headers.append("content-security-policy", policy);
+			return result;
+		} catch {
+			const response = new Response(result.response.body, result.response);
+			response.headers.append("content-security-policy", policy);
+			return response;
+		}
+	});
+}
+
+//#endregion
+export { embeddingMiddleware };

package/dist/fetch.js

@@ -1,29 +1,9 @@
-import { version } from "./package.js";
-import { assert, requireDefined } from "./assertions.js";
 import { logger } from "./logger.js";
-import { softrApiUrl } from "./softr-api.js";
 
 //#region src/fetch.ts
 const fetch = async (input, init) => {
-	const url = input instanceof Request ? input.url : String(input);
-	if ([
-		softrApiUrl("SOFTR_PLATFORM_API_URL"),
-		softrApiUrl("SOFTR_DATASOURCE_API_URL"),
-		softrApiUrl("SOFTR_WORKFLOWS_API_URL")
-	].some((base) => url.startsWith(`${base}/`))) {
-		const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : void 0));
-		headers.set("user-agent", `softr-sdk/${version}`);
-		init = {
-			...init,
-			headers
-		};
-		const signed = await sign(input, init);
-		if (signed) {
-			input = signed;
-			init = void 0;
-		}
-	}
 	if (process.env.NODE_ENV === "production") return globalThis.fetch(input, init);
+	const url = input instanceof Request ? input.url : String(input);
 	const method = init?.method ?? (input instanceof Request ? input.method : "GET");
 	const started = Date.now();
 	try {
@@ -36,46 +16,6 @@ const fetch = async (input, init) => {
 		throw error;
 	}
 };
-async function sign(input, init) {
-	const key = process.env.SOFTR_REQUEST_SIGNING_KEY;
-	const keyId = process.env.SOFTR_REQUEST_SIGNING_KEY_ID;
-	if (!key || !keyId) return void 0;
-	assert(/^[0-9a-f]{64}$/i.test(key), "SOFTR_REQUEST_SIGNING_KEY must be 64 hex characters");
-	assert(!/["\\]/.test(keyId), "SOFTR_REQUEST_SIGNING_KEY_ID must not contain quotes or backslashes");
-	const request = new Request(input, init);
-	const headers = new Headers(request.headers);
-	const { host, pathname, search } = new URL(request.url);
-	const derived = {
-		"@method": request.method,
-		"@authority": host,
-		"@path": pathname,
-		"@query": search || "?"
-	};
-	const fields = Object.keys(derived);
-	const body = request.body ? new Uint8Array(await request.arrayBuffer()) : void 0;
-	if (body) {
-		headers.set("content-digest", `sha-256=:${base64(await crypto.subtle.digest("SHA-256", body))}:`);
-		fields.push("content-type", "content-digest");
-	}
-	if (headers.has("authorization")) fields.push("authorization");
-	const created = Math.floor(Date.now() / 1e3);
-	const params = `(${fields.map((field) => `"${field}"`).join(" ")});created=${created};keyid="${keyId}";tag="softr-code-app"`;
-	const base = [...fields.map((field) => `"${field}": ${derived[field] ?? requireDefined(headers.get(field), field)}`), `"@signature-params": ${params}`].join("\n");
-	const hmacKey = await crypto.subtle.importKey("raw", Uint8Array.from(key.match(/../g) ?? [], (byte) => parseInt(byte, 16)), {
-		name: "HMAC",
-		hash: "SHA-256"
-	}, false, ["sign"]);
-	const signature = base64(await crypto.subtle.sign("HMAC", hmacKey, new TextEncoder().encode(base)));
-	headers.set("signature-input", `softr=${params}`);
-	headers.set("signature", `softr=:${signature}:`);
-	return new Request(request, {
-		headers,
-		body
-	});
-}
-function base64(bytes) {
-	return btoa(String.fromCharCode(...new Uint8Array(bytes)));
-}
 
 //#endregion
 export { fetch };

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/locale-settings.js

@@ -1,8 +1,8 @@
 import { logger } from "./logger.js";
-import { softrApiUrl } from "./softr-api.js";
 import { fetch } from "./fetch.js";
 import { readRequestCookies, serializeCookie, writeCookies } from "./cookies.js";
 import { sessionConfig } from "./auth/config.js";
+import { softrApiUrl } from "./softr-api.js";
 import { localeSettingsSchema } from "./formatting.js";
 import { getRequestProtocol } from "@tanstack/react-start/server";
 

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_start6 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_start6.RequestMiddlewareAfterServer<{}, undefined, undefined>;
 //#endregion
 export { softrMcpMiddleware };

package/dist/mcp.js

@@ -1,10 +1,10 @@
 import { assert } from "./assertions.js";
-import { softrApiUrl } from "./softr-api.js";
 import { fetch } from "./fetch.js";
+import { softrConfig } from "./softr-config.js";
 import { sessionConfig } from "./auth/config.js";
 import { readSessionToken, withSessionToken } from "./auth/session.js";
+import { softrApiUrl } from "./softr-api.js";
 import { isDatasourceAction } from "./action.js";
-import { softrConfig } from "./softr-config.js";
 import { makePlatform } from "./auth/platform.js";
 import { ds } from "./datasource/datasource.js";
 import { z } from "zod";
@@ -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.88-signing.0";
+var version = "0.0.89-alpha.0";
 
 //#endregion
 export { version };

package/dist/pwa.js

@@ -1,7 +1,7 @@
 import { logger } from "./logger.js";
-import { softrApiUrl } from "./softr-api.js";
 import { fetch } from "./fetch.js";
 import { sessionConfig } from "./auth/config.js";
+import { softrApiUrl } from "./softr-api.js";
 import { z } from "zod";
 import { Fragment, createElement, useEffect, useState } from "react";
 import { createMiddleware } from "@tanstack/react-start";
@@ -125,7 +125,7 @@ function usePwaInstall() {
 	useEffect(() => {
 		if (window.matchMedia("(display-mode: standalone)").matches || "standalone" in navigator && navigator.standalone === true) return;
 		let cancelled = false;
-		globalThis.fetch(INSTALL_PATH, { headers: { accept: "application/json" } }).then(async (response) => {
+		fetch(INSTALL_PATH, { headers: { accept: "application/json" } }).then(async (response) => {
 			if (!response.ok) return;
 			const parsed = installSchema.safeParse(await response.json());
 			if (!parsed.success || cancelled) return;

package/dist/route/route.js

@@ -1,6 +1,6 @@
 import { panic } from "../assertions.js";
-import { ACCESS_REASONS, checkRule } from "./visibility.js";
 import { softrConfig } from "../softr-config.js";
+import { ACCESS_REASONS, checkRule } from "./visibility.js";
 import { redirect } from "@tanstack/react-router";
 
 //#region src/route/route.ts

package/dist/softr-config.schema.js

@@ -21,6 +21,7 @@ const AccessBehaviour = z.union([
 	z.object({ strategy: z.literal("throw") })
 ], { error: "must be a path like \"/login\", { \"strategy\": \"redirect\", \"to\": \"/login\" } or { \"strategy\": \"throw\" }" });
 const AppPath = z.string().refine((path$1) => path$1.startsWith("/") && !path$1.includes("?") && !path$1.includes("#") && new URL(path$1, "https://app.invalid").origin === "https://app.invalid", { error: "must be a path on this app like \"/login\", with no \"?\" or \"#\"" });
+const Origin = z.union([z.literal("*"), z.string().regex(/^https:\/\/[^/\\?#@\s;,]+$/).refine(URL.canParse).transform((origin) => new URL(origin).origin)], { error: "must be an https origin like \"https://partner.com\", with no path or trailing \"/\", or \"*\" for any site" });
 const SoftrConfigSchema = z.object({
 	auth: z.strictObject({
 		routes: z.strictObject({
@@ -47,7 +48,8 @@ const SoftrConfigSchema = z.object({
 			alreadyAuthenticated: AccessBehaviour
 		})
 	}),
-	user: z.strictObject({ properties: z.record(z.string(), z.string()) }).optional()
+	user: z.strictObject({ properties: z.record(z.string(), z.string()) }).optional(),
+	allowEmbedding: z.array(Origin).optional()
 });
 function loadSoftrConfig(root) {
 	const file = path.join(root, SOFTR_CONFIG_FILE);

package/package.json

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

package/schema/softr.schema.json

@@ -67,6 +67,11 @@
       },
       "required": ["properties"],
       "additionalProperties": false
+    },
+    "allowEmbedding": {
+      "type": "array",
+      "description": "Sites that may show the published app in an iframe, signed-in pages included, as https origins like \"https://partner.com\", or \"*\" for any site. Any other site is still blocked. With at least one, session cookies use SameSite=None, which drops the browser's CSRF protection. Empty by default.",
+      "items": { "type": "string", "pattern": "^(\\*|https://[^/\\\\?#@\\s;,]+)$" }
     }
   },
   "required": ["auth"],

package/skills/softr-sdk/SKILL.md

@@ -3,12 +3,13 @@ name: softr-sdk
 description: >-
   Entry point for @softr/sdk: its four entrypoints (@softr/sdk, /server,
   /client, /vite) and their client-server boundary, softrAuthMiddleware and the
-  Softr context, and which sub-skill covers each task. Load it when unsure which
-  sub-skill applies, or when touching the wiring.
+  Softr context, embedding the app in another site's iframe, and which sub-skill
+  covers each task. Load it when unsure which sub-skill applies, when touching
+  the wiring, or when the user wants the app embedded elsewhere.
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.88-signing.0
+  library_version: 0.0.89-alpha.0
 ---
 
 # Softr SDK core
@@ -17,7 +18,7 @@ metadata:
 
 > **CRITICAL**: The SDK is split across four entrypoints and the split is enforced. `ds` and `auth` exist only on `@softr/sdk/server` and only run inside a `createServerFn` handler. Importing them anywhere else fails the build.
 >
-> **CRITICAL**: Every route file must declare its audience with `defineVisibility` and guard itself with that rule in `beforeLoad`. There is no default and nothing is inherited from a sibling.
+> **CRITICAL**: Every route file must declare its settings with `definePage`, guard itself with them in `beforeLoad` and render them in `head`. There is no default and nothing is inherited from a sibling.
 >
 > **CRITICAL**: The app is already wired. `src/start.ts`, `src/router.tsx` and `src/routes/__root.tsx` register `softrAuthMiddleware` and resolve the session. Do not add a second registration of it. `softrMcpMiddleware` is the one thing an app adds to `src/start.ts` itself — load the `softr-sdk/mcp` sub-skill before doing so.
 >
@@ -29,7 +30,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `FormattedDate`, `FormattingScope`, `useFormatting`, `formatDate`, `formatDateTime`, `formatNumber`, `formatValue`, `formatField`, `fieldShape`, `registerSoftrFields`, `useOverrides`, `SoftrPwaHead`, `usePwaInstall`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `definePage`, `pageHead`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `FormattedDate`, `FormattingScope`, `useFormatting`, `formatDate`, `formatDateTime`, `formatNumber`, `formatValue`, `formatField`, `fieldShape`, `registerSoftrFields`, `useOverrides`, `SoftrPwaHead`, `usePwaInstall`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
 | `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration` |
 | `@softr/sdk/client` | Browser only | `useFileUpload` |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
@@ -48,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) |
 
@@ -84,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?
+  load softr-sdk/agent-chat
+
 Adding an install button, or making the app installable?
   load softr-sdk/pwa
 
@@ -148,3 +153,7 @@ type User = {
   userGroupIds: Array<SoftrUserGroupId>   // the app's own group ids
 }
 ```
+
+## Embedding the app in another site
+
+The published app refuses to load inside another site's iframe. The Studio preview is not affected. When the user asks to embed the app on their site, list that site's origin in `softr.json`: `"allowEmbedding": ["https://partner.com"]`. Ask for the exact origin if you don't have it. Only listed sites can embed the app. Use `["*"]` only when the user wants any site to embed it. Remove the list to block embedding again. Sign-in then works inside the embed. Session cookies switch from SameSite=Lax to None, so the app loses the browser's CSRF protection. Only set it when the user asks. There are two more limits to tell the user: Safari may not keep the visitor signed in, and links from emails (magic link, password reset) open the app in a new tab, not in the embed.

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

@@ -0,0 +1,122 @@
+---
+name: agent-chat
+description: >-
+  Let visitors chat with one of the app's Softr agents: listAgents() from
+  @softr/sdk gives the agents the visitor may use, and useAgentChat(agentId, {
+  record }) 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.89-alpha.0
+---
+
+**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. 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 { 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, never write one by hand.
+
+## 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 visitor, so the hook reopens it after a remount or a reload.
+- `approve(toolCallId, scope?)` and `reject(toolCallId)` answer a tool waiting for approval. `scope` is `ONCE` (default), `SESSION` for the rest of this chat, or `USER` for always.
+
+## Rendering a message
+
+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. Expanded, show `thought`, `input`, `error` and `durationMs`. |
+| `todo` | A checklist of the agent's plan. It updates in place. |
+| `question` | The questions with their options. 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 ", ". |
+| `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.
+
+## The chat panel
+
+Classic Softr apps ship a chat panel. Visitors expect the same from yours:
+
+- A round button in a corner opens it. A right-side panel on desktop, full screen on mobile.
+- The header shows the agent's avatar and name, a picker when there are several agents, new chat, past chats and close.
+- An empty chat greets the visitor with the agent's avatar.
+- The list scrolls to the newest message as the reply streams, until the visitor scrolls up. Then a button takes them back down.
+- Text renders as Markdown, tables included.
+- The input says "Ask {agent title}…". Enter sends. Shift+Enter adds a line.
+- A line under the input: "AI can make mistakes. Please double-check responses."
+- A question with one choice sends on click. One with `multiSelect` or several questions sends once all are answered. An answered question stays locked.
+- Approve offers the three scopes: once, for this chat, always for this agent.
+
+## Context
+
+`record` is the one record the visitor is looking at, so they can say "close this one". Pass it where a page shows one record, and `null` elsewhere. Use readable field names as keys. The agent reads them as they are.
+
+The page title 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. 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.
+
+**The hook inside a panel that unmounts when it closes.** Closing it stops a reply that is still coming. Call `useAgentChat` in the component that owns the open state, such as the layout, and pass `chat` into the panel. Keep the selected agent there too, or closing the panel resets it.
+
+**An agent id written by hand.** The chat fails on the first message, and an agent hidden from the visitor still shows. Take the id from `listAgents`.
+
+**Expecting the agent to change data with no MCP wired.** It answers but can't act. List the actions it needs in `softrMcpMiddleware`.
+
+## 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.88-signing.0
+  library_version: 0.0.89-alpha.0
 ---
 
 **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.88-signing.0
+  library_version: 0.0.89-alpha.0
 ---
 
 **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.88-signing.0
+  library_version: 0.0.89-alpha.0
 ---
 
 # The current user
@@ -55,12 +55,16 @@ It returns `User | null` and never suspends or fetches. It selects off root rout
 
 ```tsx
 export const Route = createFileRoute('/_app/invoices')({
-  beforeLoad: guardRoute(visibility),
-  loader: ({ context }) => fetchInvoicesFor({ data: { userId: context.user!.id } }),
+  beforeLoad: guardRoute(pageSettings),
+  loader: (opts) => {
+    assertRouteAccess(pageSettings, opts)
+    return fetchInvoicesFor({ data: { userId: opts.context.user.id } })
+  },
+  head: pageHead(pageSettings),
 })
 ```
 
-A `guardRoute` in `beforeLoad` guarantees a visitor at runtime, but it does not change what the compiler sees. `context.user` is still `User | null` further down the route. `isAuthorized(visibility, context)` is the check that narrows it, so prefer that over `!`. See [routes-and-visibility](../routes-and-visibility/SKILL.md).
+A `guardRoute` in `beforeLoad` guarantees a visitor at runtime, but it does not change what the compiler sees. `context.user` is still `User | null` in the loader. `assertRouteAccess(pageSettings, opts)` at the top of the loader narrows it there, so prefer that over `!`. Take `opts` whole: a destructured `context` does not narrow. See [routes-and-visibility](../routes-and-visibility/SKILL.md).
 
 ### In a server function: `context`
 
@@ -94,7 +98,7 @@ For every group's name and id, read `docs/user-groups.md`. It lists every group
 
 ## References
 
-- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `isAuthorized` narrows `context.user` while applying the route's rule
+- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `assertRouteAccess` narrows `context.user` while applying the route's rule
 - [region-visibility/SKILL.md](../region-visibility/SKILL.md): rendering a region only to the visitors a rule admits
 - [record-queries/SKILL.md](../record-queries/SKILL.md): filtering a query by the visitor, and who really authorizes the read
 - [auth/SKILL.md](../auth/SKILL.md): what changes the value `useCurrentUser` returns

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

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.88-signing.0
+  library_version: 0.0.89-alpha.0
 ---
 
 **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.88-signing.0
+  library_version: 0.0.89-alpha.0
 ---
 
 # 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.88-signing.0
+  library_version: 0.0.89-alpha.0
 ---
 
 **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.88-signing.0
+  library_version: 0.0.89-alpha.0
 ---
 
 **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.88-signing.0
+  library_version: 0.0.89-alpha.0
 ---
 
 # 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.88-signing.0
+  library_version: 0.0.89-alpha.0
 ---
 
 **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.88-signing.0
+  library_version: 0.0.89-alpha.0
 ---
 
 **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.
@@ -53,7 +53,7 @@ const publishedPosts = defineQuery({
   - `{ userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'] }`: everyone, signed out included. `customGroups` narrows only the signed-in half.
   - `{ userGroupTypes: ['NON_LOGGED_IN_USERS'] }`: signed-out visitors only.
   - `{ userGroupTypes: ['LOGGED_IN_USERS'] }`: any signed-in visitor, narrowed to particular groups with `customGroups: ['00000000-0000-0000-0000-00000000000a']`. `customGroups` is added to `userGroupTypes`, never written in place of it.
-- Write each group id as a literal in `permissions`. An id taken from a `const` is a lint error, as it is in a route's visibility.
+- Write each group id as a literal in `permissions`. An id taken from a `const` is a lint error.
 - Write the object inline in the `defineQuery` call. Passing the declaration or its `fields` through a variable, or spreading one in, widens the field ids to `string` and the types stop checking.
 
 A query fixes the table and the columns, not the rows: filters, sorting and paging stay at the call site, because a list screen changes them as the user types. Declare as many queries over one datasource as the app needs, each carrying the fields its own screen touches.