@softr/sdk 0.0.87-alpha.1 → 0.0.87-alpha.3

package/dist/auth/methods/authenticator.js

@@ -46,7 +46,7 @@ async function confirmAuthenticatorSetup(details) {
 		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows an authenticator app.`);
 	}
 	const { session, backupCodes } = result.data;
-	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);
@@ -75,7 +75,7 @@ async function skipAuthenticatorSetup() {
 	}
 	const { session } = result.data;
 	assert(session, "Expected a session from skipping setup, but got none");
-	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);
@@ -101,7 +101,7 @@ async function verifyAuthenticator(credentials) {
 	}
 	const { session } = result.data;
 	assert(session, "Expected a session from verification, but got none");
-	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);

package/dist/auth/methods/code.js

@@ -56,7 +56,7 @@ async function signInWithCode(credentials) {
 	}
 	const { session } = result.data;
 	assert(session, "Expected a session from sign-in, but got none");
-	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);

package/dist/auth/methods/magicLink.js

@@ -36,7 +36,7 @@ async function signInWithMagicLink(credentials) {
 	}
 	const { session } = result.data;
 	assert(session, "Expected a session from magic-link sign-in, but got none");
-	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);

package/dist/auth/methods/password.js

@@ -35,7 +35,7 @@ async function signIn(credentials) {
 	}
 	const { session } = result.data;
 	assert(session, "Expected a session from sign-in, but got none");
-	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);

package/dist/auth/methods/passwordLink.js

@@ -68,7 +68,7 @@ async function setPasswordWithLink(details) {
 	}
 	const { session } = result.data;
 	assert(session, "Expected a session from setting a password, but got none");
-	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);

package/dist/auth/methods/signup.js

@@ -66,7 +66,7 @@ async function confirmSignUp(details) {
 	}
 	const { session } = result.data;
 	assert(session, "Expected a session from sign-up, but got none");
-	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);

package/dist/auth/methods/social.js

@@ -41,7 +41,7 @@ async function signInWithGoogle(credentials) {
 	}
 	const { session } = result.data;
 	assert(session, "Expected a session from Google sign-in, but got none");
-	writeCookies([...makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
+	writeCookies([makeSessionTokenCookie(session.jwt), makeSessionDataCookie({
 		user: session.user,
 		permissions: session.permissions
 	}, session.jwt)]);

package/dist/auth/platform.js

@@ -1,8 +1,8 @@
 import { assert, panic } from "../assertions.js";
 import { fetch } from "../fetch.js";
-import { softrConfig } from "../softr-config.js";
 import { permissionsSchema } from "./permissions.js";
 import { softrApiUrl } from "../softr-api.js";
+import { softrConfig } from "../softr-config.js";
 import { z } from "zod";
 
 //#region src/auth/platform.ts

package/dist/auth/session.js

@@ -1,4 +1,4 @@
-import { expireCookie, expireOtherCopy, readRequestCookies, serializeCookie, writeCookies } from "../cookies.js";
+import { readRequestCookies, serializeCookie, writeCookies } from "../cookies.js";
 import { permissionsSchema } from "./permissions.js";
 import { sessionConfig } from "./config.js";
 import { userSchema } from "./user.js";
@@ -65,16 +65,12 @@ function readSessionData(sessionToken) {
 		permissions: payload.permissions
 	};
 }
-/**
-* The token cookie, after a deletion of any copy from before `allowEmbedding`
-* changed. Both would be sent, and the old one could be read instead.
-*/
 function makeSessionTokenCookie(token) {
 	const { name, secure } = sessionCookie(SESSION_TOKEN);
-	return [...expireOtherCopy(name, secure), serializeCookie(name, sealEnvelope(token, SESSION_TOKEN), {
+	return serializeCookie(name, sealEnvelope(token, SESSION_TOKEN), {
 		maxAge: sessionConfig().sessionMaxAge,
 		secure
-	})];
+	});
 }
 function makeSessionDataCookie(session, sessionToken) {
 	const { name, secure } = sessionCookie(SESSION_DATA);
@@ -145,7 +141,10 @@ const sessionDataSchema = z.object({
 */
 function clearCookies(bases) {
 	const secure = requestIsSecure();
-	writeCookies(bases.flatMap((base) => secure ? [sessionCookieName(base, secure), base] : [base]).flatMap((name) => expireCookie(name, secure)));
+	writeCookies(bases.flatMap((base) => secure ? [sessionCookieName(base, secure), base] : [base]).map((name) => serializeCookie(name, "", {
+		maxAge: 0,
+		secure
+	})));
 }
 /**
 * Over the plaintext token, never the cookie value: that is resealed with a

package/dist/cookies.js

@@ -1,5 +1,4 @@
 import { softAssert } from "./assertions.js";
-import { softrConfig } from "./softr-config.js";
 import { getRequestHeader, getResponseHeaders, setResponseHeader } from "@tanstack/react-start/server";
 
 //#region src/cookies.ts
@@ -37,33 +36,8 @@ function serializeCookie(name, value, { maxAge, secure }) {
 	return parts.join("; ");
 }
 function sameSiteAttributes(secure) {
-	return partitions(secure) ? ["SameSite=None", "Partitioned"] : ["SameSite=Lax"];
-}
-function partitions(secure) {
-	return secure && (process.env.NODE_ENV !== "production" || (softrConfig().allowEmbedding ?? []).length > 0);
-}
-function expired(name, partitioned) {
-	return partitioned ? `${name}=; Path=/; HttpOnly; Secure; SameSite=None; Partitioned; Max-Age=0` : `${name}=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0`;
-}
-/**
-* The deletions for one cookie. A browser keeps a partitioned and a plain
-* cookie of one name apart, and sends both. Which one the app wrote can change
-* between sign-in and sign-out, when `allowEmbedding` changes. So over https,
-* delete both. The one left behind would keep the visitor signed in.
-*/
-function expireCookie(name, secure) {
-	if (!secure) return [serializeCookie(name, "", {
-		maxAge: 0,
-		secure
-	})];
-	return [expired(name, false), expired(name, true)];
-}
-/**
-* The deletion of the copy the other mode would write. Sent with a new cookie,
-* so a copy from before `allowEmbedding` changed can't be read in its place.
-*/
-function expireOtherCopy(name, secure) {
-	return secure ? [expired(name, !partitions(secure))] : [];
+	if (secure && process.env.NODE_ENV !== "production") return ["SameSite=None", "Partitioned"];
+	return ["SameSite=Lax"];
 }
 const USER_TIMEZONE_COOKIE = "user-timezone";
 function readUserTimezone() {
@@ -82,4 +56,4 @@ function writeCookies(cookies) {
 }
 
 //#endregion
-export { expireCookie, expireOtherCopy, readRequestCookies, readUserTimezone, serializeCookie, writeCookies };
+export { readRequestCookies, readUserTimezone, serializeCookie, writeCookies };

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

package/dist/mcp.js

@@ -1,10 +1,10 @@
 import { assert } from "./assertions.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.87-alpha.1";
+var version = "0.0.87-alpha.3";
 
 //#endregion
 export { version };

package/dist/route/route.js

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

package/dist/softr-config.schema.js

@@ -21,7 +21,6 @@ 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.string().refine((origin) => origin === "*" || URL.canParse(origin) && new URL(origin).origin === origin && origin.startsWith("https://"), { 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({
@@ -48,8 +47,7 @@ const SoftrConfigSchema = z.object({
 			alreadyAuthenticated: AccessBehaviour
 		})
 	}),
-	user: z.strictObject({ properties: z.record(z.string(), z.string()) }).optional(),
-	allowEmbedding: z.array(Origin).optional()
+	user: z.strictObject({ properties: z.record(z.string(), z.string()) }).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.87-alpha.1",
+  "version": "0.0.87-alpha.3",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },

package/schema/softr.schema.json

@@ -67,11 +67,6 @@
       },
       "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://[^/?#]+)$" }
     }
   },
   "required": ["auth"],

package/skills/softr-sdk/SKILL.md

@@ -3,13 +3,12 @@ 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, 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.
+  Softr context, and which sub-skill covers each task. Load it when unsure which
+  sub-skill applies, or when touching the wiring.
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.87
+  library_version: 0.0.87-alpha.3
 ---
 
 # Softr SDK core
@@ -49,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) |
 
@@ -85,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
 
@@ -149,7 +152,3 @@ 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,105 @@
+---
+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.87-alpha.3
+---
+
+**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`.
+- `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 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.87
+  library_version: 0.0.87-alpha.3
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.87
+  library_version: 0.0.87-alpha.3
 ---
 
 **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/embedding.js

@@ -1,28 +0,0 @@
-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 origins = softrConfig().allowEmbedding ?? [];
-		const response = new Response(result.response.body, result.response);
-		response.headers.append("content-security-policy", [
-			"frame-ancestors",
-			"'self'",
-			...origins
-		].join(" "));
-		return response;
-	});
-}
-
-//#endregion
-export { embeddingMiddleware };