@softr/sdk 0.0.92-emailotc.0 → 0.0.93-alpha.0

package/dist/datasource/record.js

@@ -30,6 +30,15 @@ function refererHeader() {
 	const referer = getRequestHeader("referer");
 	return { Referer: referer !== void 0 && URL.parse(referer)?.origin === page.origin ? referer : page.href };
 }
+/** A datasource call the service refused. `status` is its HTTP status. */
+var DatasourceError = class extends Error {
+	status;
+	constructor(message, status) {
+		super(message);
+		this.name = "DatasourceError";
+		this.status = status;
+	}
+};
 async function describeFailure(res) {
 	const body = await res.json().catch(() => null);
 	const message = typeof body === "object" && body !== null && "message" in body ? body.message : null;
@@ -235,7 +244,7 @@ async function updateRecord(action, options) {
 		},
 		body: JSON.stringify({ fields: rawFields })
 	});
-	if (!res.ok) throw new Error(`datasource update failed for action "${actionId}": ${await describeFailure(res)}`);
+	if (!res.ok) throw new DatasourceError(`datasource update failed for action "${actionId}": ${await describeFailure(res)}`, res.status);
 	const record = await res.json();
 	return {
 		id: record.id,
@@ -257,7 +266,7 @@ async function deleteRecord(action, options) {
 			...refererHeader()
 		}
 	});
-	if (!res.ok) throw new Error(`datasource delete failed for action "${actionId}": ${await describeFailure(res)}`);
+	if (!res.ok) throw new DatasourceError(`datasource delete failed for action "${actionId}": ${await describeFailure(res)}`, res.status);
 }
 function resolveTarget(subject, operation) {
 	const declaredBy = operation === "read" ? "defineQuery" : "defineMutation";
@@ -281,4 +290,4 @@ function dealiasData(data, select) {
 }
 
 //#endregion
-export { createRecord, deleteRecord, describeFailure, dsUrl, getRecord, listRecords, refererHeader, resolveTarget, updateRecord };
+export { DatasourceError, createRecord, deleteRecord, describeFailure, dsUrl, getRecord, listRecords, refererHeader, resolveTarget, updateRecord };

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

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

package/dist/formatting.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import * as react3 from "react";
+import * as react0 from "react";
 import { ReactNode } from "react";
 
 //#region src/formatting.d.ts
@@ -94,7 +94,7 @@ declare function FormattingScope({
   /** A BCP 47 locale, such as `de-DE`. It drops the app's fixed date format inside the scope. */
   locale?: string;
   children?: ReactNode;
-}): react3.FunctionComponentElement<react3.ProviderProps<Scope>>;
+}): react0.FunctionComponentElement<react0.ProviderProps<Scope>>;
 /**
  * A date in the app's format, safe to render on the server. A timestamp whose
  * zone is not known yet renders `fallback` until the browser supplies it, so
@@ -115,6 +115,6 @@ declare function FormattedDate({
   time?: boolean;
   /** What renders while the visitor's zone is unknown. */
   fallback?: ReactNode;
-}): react3.FunctionComponentElement<react3.FragmentProps>;
+}): react0.FunctionComponentElement<react0.FragmentProps>;
 //#endregion
 export { DateOptions, DateParts, DateSeparator, DateValue, FixedDateFormat, FormattedDate, Formatting, FormattingScope, WeekDay, formatDate, formatDateTime, formatNumber, useFormatting };

package/dist/index.d.ts

@@ -17,5 +17,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, type AiAnswer, type AiFile, type AiGenerateInit, type AiMessage, type AiUsage, 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, defineAiAction, 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, type AiAnswer, type AiFile, type AiGenerateInit, type AiMessage, type AiUsage, 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, defineAiAction, 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, defineAiAction, 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, defineAiAction, 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,9 +1,9 @@
-import { DatasourceAction } from "./action.js";
-import * as _tanstack_react_start6 from "@tanstack/react-start";
+import { DatasourceAction, ReadShape } from "./action.js";
+import * as _tanstack_react_start7 from "@tanstack/react-start";
 
 //#region src/mcp.d.ts
 
-type SoftrMcpOptions = {
+type SoftrMcpOptions<TUsers extends ReadShape = ReadShape> = {
   /**
    * The actions to expose as tools, from `defineQuery` and `defineMutation`.
    *
@@ -12,6 +12,19 @@ type SoftrMcpOptions = {
    * decide who may run the ones that are listed.
    */
   actions?: Array<DatasourceAction>;
+  /**
+   * Fills the owner of a person's record from who is calling, the way the app's
+   * pages do with `auth.currentUserRow`. The field is left out of the tool, so
+   * the assistant can't leave it wrong or name someone else.
+   */
+  owner?: SoftrMcpOwner<TUsers>;
+};
+type SoftrMcpOwner<TUsers extends ReadShape = ReadShape> = {
+  /** The people table, and its email field, to find the caller's row in. */
+  users: DatasourceAction<TUsers>;
+  email: keyof TUsers["fields"] & string;
+  /** Listed create or update action id to the field that links to the caller's row. */
+  fields: Record<string, string>;
 };
 /**
  * Serves the MCP endpoint and its OAuth flow from the app's own origin.
@@ -31,6 +44,6 @@ type SoftrMcpOptions = {
  *   ],
  * }))
  */
-declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start6.RequestMiddlewareAfterServer<{}, undefined, undefined>;
+declare function softrMcpMiddleware<TUsers extends ReadShape>(options?: SoftrMcpOptions<TUsers>): _tanstack_react_start7.RequestMiddlewareAfterServer<{}, undefined, undefined>;
 //#endregion
 export { softrMcpMiddleware };

package/dist/mcp.js

@@ -5,8 +5,10 @@ import { softrConfig } from "./softr-config.js";
 import { sessionConfig } from "./auth/config.js";
 import { readSessionToken, withSessionToken } from "./auth/session.js";
 import { isDatasourceAction } from "./action.js";
+import { DatasourceError } from "./datasource/record.js";
 import { makePlatform } from "./auth/platform.js";
 import { ds } from "./datasource/datasource.js";
+import { currentUserRow } from "./auth/current-user-row.js";
 import { z } from "zod";
 import { createMiddleware } from "@tanstack/react-start";
 
@@ -48,6 +50,14 @@ function softrMcpMiddleware(options = {}) {
 		assert(!actions.has(value.id), `two actions share the id "${value.id}"`);
 		actions.set(value.id, value);
 	}
+	const owner = options.owner;
+	for (const [actionId, field] of Object.entries(owner?.fields ?? {})) {
+		const action = actions.get(actionId);
+		assert(action, `owner names "${actionId}", which is not a listed action`);
+		const { operation, fields } = action.resource;
+		assert(operation === "create" || operation === "update", `owner fills "${actionId}", which is a ${operation}`);
+		assert(field in (fields ?? {}), `"${actionId}" has no field "${field}" for the owner`);
+	}
 	return createMiddleware({ type: "request" }).server(async ({ next, request }) => {
 		const url = new URL(request.url);
 		const origin = url.origin;
@@ -71,7 +81,7 @@ function softrMcpMiddleware(options = {}) {
 			});
 			case AUTHORIZE_PATH: return await authorize(request, login);
 			case TOKEN_PATH: return await issueToken(request);
-			case MCP_PATH: return await rpc(request, origin, actions);
+			case MCP_PATH: return await rpc(request, origin, actions, owner);
 			default: return await next();
 		}
 	});
@@ -244,7 +254,8 @@ const WHOAMI = {
 		type: "object",
 		properties: {},
 		additionalProperties: false
-	}
+	},
+	annotations: { readOnlyHint: true }
 };
 /** How many records a read returns when the caller does not say. */
 const DEFAULT_LIMIT = 20;
@@ -257,14 +268,16 @@ const MAX_LIMIT = 100;
 * that only ever reads one datasource exposes one read, even though its
 * credentials would allow more.
 */
-function describeTool(action) {
+function describeTool(action, ownerField) {
 	const { operation, fields } = action.resource;
 	const names = Object.keys(fields ?? {});
-	const fieldProps = Object.fromEntries(names.map((name) => [name, { description: `The "${name}" field.` }]));
+	const writable = names.filter((name) => name !== ownerField);
+	const fieldProps = Object.fromEntries(writable.map((name) => [name, { description: `The "${name}" field.` }]));
 	switch (operation) {
 		case "read": return {
 			name: action.id,
 			description: `Read records from "${action.id}". Returns the fields ${names.join(", ")}. Only records the signed-in user may see come back.`,
+			annotations: { readOnlyHint: true },
 			inputSchema: {
 				type: "object",
 				properties: {
@@ -285,7 +298,7 @@ function describeTool(action) {
 		};
 		case "create": return {
 			name: action.id,
-			description: `Create a record with "${action.id}". Writable fields: ${names.join(", ")}.`,
+			description: `Create a record with "${action.id}". Writable fields: ${writable.join(", ")}.`,
 			inputSchema: {
 				type: "object",
 				properties: fieldProps,
@@ -294,7 +307,7 @@ function describeTool(action) {
 		};
 		case "update": return {
 			name: action.id,
-			description: `Update a record with "${action.id}". Writable fields: ${names.join(", ")}.`,
+			description: `Update a record with "${action.id}". Writable fields: ${writable.join(", ")}.`,
 			inputSchema: {
 				type: "object",
 				properties: {
@@ -330,7 +343,7 @@ function describeTool(action) {
 * visitor's user groups exactly as it would a click in the app. Nothing here
 * decides what is allowed.
 */
-async function runTool(action, args) {
+async function runTool(action, args, owner) {
 	const typed = action;
 	switch (action.resource.operation) {
 		case "read": {
@@ -342,13 +355,21 @@ async function runTool(action, args) {
 				nextOffset: result$1.nextOffset
 			};
 		}
-		case "create": return await ds.create(typed, { data: writableFields(action, args) });
+		case "create": {
+			const data = writableFields(action, args, owner?.field);
+			if (owner !== null) {
+				const row = await owner.row();
+				if (row === null) throw new Error("The visitor has no row in the people table, so this record can't be created for them.");
+				data[owner.field] = { id: row.id };
+			}
+			return await ds.create(typed, { data });
+		}
 		case "update": {
 			const { id,...data } = args;
 			assert(typeof id === "string" && id !== "", "update needs a record id");
 			return await ds.update(typed, {
 				id,
-				data: writableFields(action, data)
+				data: writableFields(action, data, owner?.field)
 			});
 		}
 		case "delete": {
@@ -359,8 +380,19 @@ async function runTool(action, args) {
 		}
 	}
 }
+function ownerFieldOf(owner, actionId) {
+	return owner !== void 0 && Object.hasOwn(owner.fields, actionId) ? owner.fields[actionId] : void 0;
+}
+function ownerFill(owner, actionId, sessionToken) {
+	const field = ownerFieldOf(owner, actionId);
+	if (owner === void 0 || field === void 0) return null;
+	return {
+		field,
+		row: async () => currentUserRow(await resolveUser(sessionToken), owner.users, owner.email)
+	};
+}
 /**
-* Only the fields the action declared.
+* Only the fields the action declared, less the owner it fills itself.
 *
 * `additionalProperties: false` in the tool schema is a hint to the model, not
 * a check — a client can send whatever it likes. An unlisted key reaches the
@@ -368,9 +400,18 @@ async function runTool(action, args) {
 * straight through. So the action's field list gets enforced here, or it isn't
 * a boundary at all.
 */
-function writableFields(action, args) {
+function writableFields(action, args, ownerField) {
 	const allowed = action.resource.fields ?? {};
-	return Object.fromEntries(Object.entries(args).filter(([name]) => name in allowed));
+	return Object.fromEntries(Object.entries(args).filter(([name]) => name in allowed && name !== ownerField));
+}
+/**
+* The error as the assistant should read it. A row rule that keeps the caller
+* from changing a record answers 404, the same as a deleted record, so a bare
+* "not found" would leave the assistant guessing.
+*/
+function describeError(error) {
+	if (error instanceof DatasourceError && error.status === 404) return "Refused: this record doesn't exist, or the visitor's user group may not change it. If it still shows in a read, it is a permission. Tell the visitor they don't have access to this action, and that the app's builder can grant it.";
+	return error instanceof Error ? error.message : String(error);
 }
 function clampLimit(raw) {
 	if (typeof raw !== "number" || !Number.isInteger(raw)) return DEFAULT_LIMIT;
@@ -380,13 +421,15 @@ function clampOffset(raw) {
 	if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) return null;
 	return raw;
 }
-async function rpc(request, origin, actions) {
+async function rpc(request, origin, actions, owner) {
 	if (request.method !== "POST") return methodNotAllowed("POST");
 	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(),
@@ -415,7 +458,7 @@ async function rpc(request, origin, actions) {
 				}
 			});
 		}
-		case "tools/list": return result(id, { tools: [WHOAMI, ...[...actions.values()].map(describeTool)] });
+		case "tools/list": return result(id, { tools: [WHOAMI, ...[...actions.values()].map((action) => describeTool(action, ownerFieldOf(owner, action.id)))] });
 		case "tools/call": {
 			const name = params?.name;
 			const args = typeof params?.arguments === "object" && params.arguments !== null ? params.arguments : {};
@@ -427,13 +470,13 @@ async function rpc(request, origin, actions) {
 			const action = typeof name === "string" ? actions.get(name) : void 0;
 			if (action === void 0) return failure(id, -32602, `Unknown tool: ${String(name)}`);
 			try {
-				return result(id, toolResult(await withSessionToken(sessionToken, () => runTool(action, args))));
+				return result(id, toolResult(await withSessionToken(sessionToken, () => runTool(action, args, ownerFill(owner, action.id, sessionToken)))));
 			} catch (error) {
 				return result(id, {
 					isError: true,
 					content: [{
 						type: "text",
-						text: error instanceof Error ? error.message : String(error)
+						text: describeError(error)
 					}]
 				});
 			}

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.92-emailotc.0";
+var version = "0.0.93-alpha.0";
 
 //#endregion
 export { version };

package/dist/pwa.d.ts

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

package/package.json

@@ -1,37 +1,16 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.92-emailotc.0",
+  "version": "0.0.93-alpha.0",
   "type": "module",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./client": {
-      "types": "./dist/client.d.ts",
-      "import": "./dist/client.js"
-    },
-    "./server": {
-      "types": "./dist/server.d.ts",
-      "import": "./dist/server.js"
-    },
-    "./vite": {
-      "types": "./dist/vite.d.ts",
-      "import": "./dist/vite.js"
-    }
-  },
-  "bin": {
-    "softr-sdk": "./dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "schema",
-    "skills",
-    "!skills/_artifacts"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./client": { "types": "./dist/client.d.ts", "import": "./dist/client.js" },
+    "./server": { "types": "./dist/server.d.ts", "import": "./dist/server.js" },
+    "./vite": { "types": "./dist/vite.d.ts", "import": "./dist/vite.js" }
+  },
+  "bin": { "softr-sdk": "./dist/cli.js" },
+  "files": ["dist", "schema", "skills", "!skills/_artifacts"],
+  "publishConfig": { "access": "public" },
   "scripts": {
     "build": "tsdown",
     "test": "node --import ./src/test-utils/setup.ts --test",
@@ -63,9 +42,7 @@
       "optional": true
     }
   },
-  "keywords": [
-    "tanstack-intent"
-  ],
+  "keywords": ["tanstack-intent"],
   "intent": {
     "version": 1,
     "repo": "@softr/sdk",

package/skills/softr-sdk/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.91
+  library_version: 0.0.93-alpha.0
 ---
 
 # Softr SDK core
@@ -52,6 +52,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Ask an AI model: a summary, an extraction from a document, a classification, a draft, a chat | [ai/SKILL.md](./ai/SKILL.md) |
 | Call a connected third-party API (Slack, Stripe, Gmail, …), or an AI model on the user's own provider account | [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) |
 
@@ -94,6 +95,9 @@ Running a model on the user's OWN provider account, because they chose that for
 Opening the app to an AI assistant over MCP?
   load softr-sdk/mcp
 
+Adding a chat with one of the app's Softr agents, or a Connect button for the visitor's account it needs?
+  load softr-sdk/agent-chat
+
 Adding an install button, or making the app installable?
   load softr-sdk/pwa
 

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

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

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

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

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

@@ -3,13 +3,13 @@ name: auth
 description: >-
   Sign a visitor in, out or up from a server function with auth from
   @softr/sdk/server: password, code, Google and magic link, sign-up and its
-  confirmation, the emailed-code and authenticator-app steps, password reset links,
+  confirmation, the authenticator-app steps, password reset links,
   updateProfile, and getAuthSettings and useAuthSettings for the methods the app
   enables. Covers the Result shape, its error codes, and toReturnPath.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.91
+  library_version: 0.0.93-alpha.0
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.
@@ -55,13 +55,6 @@ Signing out:
 | --- | --- |
 | `auth.signOut()` | Ends every session that visitor has in this app, on every device |
 
-Finishing a sign-in that wants a code from the visitor's inbox:
-
-| Call | Does |
-| --- | --- |
-| `auth.verifyEmailCode({ code })` | Answers it with the code that was emailed |
-| `auth.resendEmailCode()` | Emails that code again |
-
 Finishing a sign-in that wants an authenticator app:
 
 | Call | Does |
@@ -204,8 +197,6 @@ Those calls take only what the visitor typed. The sign-in they finish is the one
 
 An app with no authenticator app configured never answers `authenticatorRequired`. The type still has both arms either way, so `result.data.user` does not exist until you have narrowed on `status`.
 
-`signIn` has a third answer, `{ status: 'emailCodeRequired' }`, for an app that asks a password sign-in for a code from the visitor's inbox as well. The code is already on its way. Show a code field as the next step and finish with `auth.verifyEmailCode({ code })`, see [Finishing a sign-in that needs an emailed code](#finishing-a-sign-in-that-needs-an-emailed-code). That call answers like `signIn` does, so an app that also wants an authenticator app goes on to that step after it.
-
 ## Landing after sign-in
 
 A guard that turns a signed-out visitor away sends them to the page `softr.json` names for that, usually the login page. The page they wanted rides along in the search param named for the login page. `toReturnPath` from `@softr/sdk` reads it back:
@@ -264,13 +255,10 @@ if (answer.message !== null) return setMessage(answer.message)
 if (answer.outcome.status === 'authenticatorRequired') {
   return setStep({ name: 'secondFactor', opensOn: answer.outcome.step })
 }
-if (answer.outcome.status === 'emailCodeRequired') {
-  return setStep({ name: 'emailCode' })
-}
 await navigate({ href: target })
 ```
 
-Four exits: a message for the form to render, the emailed-code step, the authenticator step, the return target.
+Three exits: a message for the form to render, the second-factor step, the return target.
 
 A server function that throws `redirect` needs the hook. Call the imported function directly and the throw never reaches the router, so a successful sign-in leaves the visitor on the form.
 
@@ -397,22 +385,6 @@ The UI has to carry email into step two, plus the name if step one collected one
 
 `password` is what the account is created with. Leave it out only for an app that signs people in with an emailed code. An app that expects a password rejects a sign-up without one, and an app that does not expect one rejects a sign-up that sends it.
 
-### Finishing a sign-in that needs an emailed code
-
-After `signIn` answers `emailCodeRequired`, the visitor owes the code that was just emailed to them:
-
-```ts
-// invalidCode for a wrong or expired code, otherwise the same two-armed result as signIn.
-const result = await auth.verifyEmailCode({ code })
-
-// For a "Resend code" link.
-const sent = await auth.resendEmailCode()
-```
-
-Send `authenticatorRequired` on to the authenticator step, never into the app.
-
-Asking for a resend too soon sends nothing and still succeeds. It answers `notAuthenticated` once the sign-in has run out of time, and the visitor then signs in again from the start.
-
 ### Finishing a sign-in that needs an authenticator app
 
 On `step: 'verify'` the visitor already has an app, and owes a code from it: