@softr/sdk 0.0.89-alpha.4 → 0.0.90-ai.0

package/dist/action.d.ts

@@ -234,5 +234,38 @@ type IntegrationDefinition<TId extends string> = {
  * const res = await listEvents({ query: { timeMin: now, singleEvents: "true" } })
  */
 declare function defineIntegration<const TId extends string>(definition: IntegrationDefinition<TId>): IntegrationAction<TId>;
+type AiResource = {
+  type: "SOFTR_AI";
+  model: string;
+};
+type AiAction<TId extends string = string> = Action<AiResource> & {
+  id: TId;
+};
+type AiDefinition<TId extends string> = {
+  id: TId;
+  model: string;
+  permissions: ActionPermissions;
+};
+/**
+ * Declares an AI action: a model call run by Softr on its own provider keys and billed to the
+ * workspace's AI credits, so nothing has to be connected. `model` is the id of a model from
+ * Softr's AI catalog, chosen when the app is built: read the catalog with the `ai_list_models`
+ * tool and copy the id exactly. An id outside the catalog is refused when the action is saved.
+ *
+ * Every call spends the workspace's credits, so keep the audience to signed-in users unless a
+ * public page really needs the call.
+ *
+ * Pass the returned object to `ai.generate()` or `ai.stream()` at runtime.
+ *
+ * @example
+ * const summarizeDeal = defineAiAction({
+ *   id: "summarizeDeal",
+ *   model: "anthropic-claude-sonnet-5-5",
+ *   permissions: { userGroupTypes: ["LOGGED_IN_USERS"] },
+ * })
+ *
+ * const answer = await ai.generate(summarizeDeal, { system: "...", prompt: facts })
+ */
+declare function defineAiAction<const TId extends string>(definition: AiDefinition<TId>): AiAction<TId>;
 //#endregion
-export { ActionData, ActionPermissions, ActionRecord, ActionShape, DatasourceAction, FieldTypeOf, IntegrationAction, ReadOf, ReadShape, SoftrDatasources, WorkflowAction, defineIntegration, defineMutation, defineQuery, defineWorkflow };
+export { ActionData, ActionPermissions, ActionRecord, ActionShape, AiAction, DatasourceAction, FieldTypeOf, IntegrationAction, ReadOf, ReadShape, SoftrDatasources, WorkflowAction, defineAiAction, defineIntegration, defineMutation, defineQuery, defineWorkflow };

package/dist/action.js

@@ -56,6 +56,17 @@ function isDatasourceAction(value) {
 	const resource = candidate.resource;
 	return typeof candidate.id === "string" && typeof resource === "object" && resource !== null && resource.type === "DATASOURCE";
 }
+function defineAiAction(definition) {
+	const { id, model, permissions } = definition;
+	return {
+		id,
+		resource: {
+			type: "SOFTR_AI",
+			model
+		},
+		permissions
+	};
+}
 
 //#endregion
-export { defineIntegration, defineMutation, defineQuery, defineWorkflow, isDatasourceAction };
+export { defineAiAction, defineIntegration, defineMutation, defineQuery, defineWorkflow, isDatasourceAction };

package/dist/auth/platform.js

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

package/dist/core/ai.d.ts

@@ -0,0 +1,79 @@
+import { AiAction } from "../action.js";
+
+//#region src/core/ai.d.ts
+/** A document or image the model reads, by the URL the app holds it under: one of its own uploads, as a rule. */
+interface AiFile {
+  /** An https URL Softr may fetch. */
+  url: string;
+  /** The file's type when the URL does not say, such as `application/pdf`. */
+  mimeType?: string;
+}
+/** One earlier turn of a conversation. */
+interface AiMessage {
+  role: 'user' | 'assistant';
+  content: string;
+}
+interface AiGenerateInit {
+  /** What the model is and the rules it answers under. */
+  system?: string;
+  /** The earlier turns of a conversation, oldest first, before the prompt. Leave out for a one-shot call. */
+  messages?: ReadonlyArray<AiMessage>;
+  /** What it is asked, with the facts it is given. */
+  prompt: string;
+  /**
+   * A JSON schema the answer has to match. With it, the model is asked for JSON only and the
+   * answer comes back parsed in `json` as well as written in `text`.
+   */
+  schema?: Record<string, unknown>;
+  /** Documents and images the model reads alongside the prompt. */
+  files?: ReadonlyArray<AiFile>;
+  /** A cap on the answer's length, in tokens; Softr caps it further. */
+  maxOutputTokens?: number;
+  /**
+   * How hard a reasoning model thinks before it answers. A model that does not reason ignores it;
+   * the catalog says which do. Left out, the provider's default applies.
+   */
+  reasoning?: 'low' | 'medium' | 'high';
+  /**
+   * How varied the answer is, 0 to 1: 0 for an extraction, higher for a draft. Left out, the provider's default
+   * applies. A model whose provider no longer takes one ignores it.
+   */
+  temperature?: number;
+  signal?: AbortSignal;
+}
+interface AiUsage {
+  inputTokens: number;
+  outputTokens: number;
+}
+interface AiAnswer {
+  /** The answer as the model wrote it. */
+  text: string;
+  /** The answer parsed as JSON when `schema` was given and the model kept to it; `null` otherwise. */
+  json: unknown;
+  usage: AiUsage;
+  /** The model that answered. */
+  model: string;
+}
+/**
+ * Thrown when the model call was refused or failed. `status` is the HTTP status Softr answered
+ * with; 402 means the workspace has no AI credits left.
+ */
+declare class AiError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string);
+}
+/** Runs the action once and answers when the model is done. */
+declare function aiGenerate(action: AiAction, init: AiGenerateInit): Promise<AiAnswer>;
+/**
+ * Runs the action and answers while the model writes. The returned `Response` body is a stream of
+ * Server-Sent Events, one JSON object per `data:` line: `{ "text": "..." }` for each piece of the
+ * answer, then `{ "done": true, "usage": {...}, "model": "..." }`, or `{ "error": "..." }` in its
+ * place. Hand it to the browser as a `Response` with `Content-Type: text/event-stream`.
+ */
+declare function aiStream(action: AiAction, init: AiGenerateInit): Promise<Response>;
+declare const ai: {
+  generate: typeof aiGenerate;
+  stream: typeof aiStream;
+};
+//#endregion
+export { AiAnswer, AiError, AiFile, AiGenerateInit, AiMessage, AiUsage, ai };

package/dist/core/ai.js

@@ -0,0 +1,64 @@
+import { fetch } from "../fetch.js";
+import { readSessionToken } from "../auth/session.js";
+import { describeFailure, dsUrl, refererHeader } from "../datasource/record.js";
+
+//#region src/core/ai.ts
+/**
+* Thrown when the model call was refused or failed. `status` is the HTTP status Softr answered
+* with; 402 means the workspace has no AI credits left.
+*/
+var AiError = class extends Error {
+	status;
+	constructor(status, message) {
+		super(message);
+		this.name = "AiError";
+		this.status = status;
+	}
+};
+function body(init) {
+	return JSON.stringify({
+		system: init.system,
+		messages: init.messages,
+		prompt: init.prompt,
+		schema: init.schema,
+		files: init.files,
+		maxOutputTokens: init.maxOutputTokens,
+		reasoning: init.reasoning,
+		temperature: init.temperature
+	});
+}
+async function post(action, path, init) {
+	if (init.signal?.aborted) throw init.signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+	const res = await fetch(`${dsUrl(action.id)}/${path}`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"Authorization": `Bearer ${readSessionToken()}`,
+			...refererHeader()
+		},
+		body: body(init),
+		signal: init.signal
+	});
+	if (!res.ok) throw new AiError(res.status, `AI call "${action.id}" failed: ${await describeFailure(res)}`);
+	return res;
+}
+/** Runs the action once and answers when the model is done. */
+async function aiGenerate(action, init) {
+	return await (await post(action, "softr-ai/generate", init)).json();
+}
+/**
+* Runs the action and answers while the model writes. The returned `Response` body is a stream of
+* Server-Sent Events, one JSON object per `data:` line: `{ "text": "..." }` for each piece of the
+* answer, then `{ "done": true, "usage": {...}, "model": "..." }`, or `{ "error": "..." }` in its
+* place. Hand it to the browser as a `Response` with `Content-Type: text/event-stream`.
+*/
+async function aiStream(action, init) {
+	return post(action, "softr-ai/generate/stream", init);
+}
+const ai = {
+	generate: aiGenerate,
+	stream: aiStream
+};
+
+//#endregion
+export { AiError, ai };

package/dist/core/file-upload.js

@@ -1,7 +1,8 @@
+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 { describeFailure } from "../datasource/record.js";
 import { randomUUID } from "node:crypto";
 
 //#region src/core/file-upload.ts
@@ -18,7 +19,7 @@ async function upload(action, file) {
 		headers: token ? { Authorization: `Bearer ${token}` } : {},
 		body: formData
 	});
-	if (!res.ok) throw new Error(`File upload failed: ${res.status}`);
+	if (!res.ok) throw new Error(`File upload failed: ${await describeFailure(res)}`);
 	const resultJSON = await res.json();
 	return {
 		url: resultJSON.url,

package/dist/core/workflow.js

@@ -1,7 +1,8 @@
+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 { describeFailure } from "../datasource/record.js";
 
 //#region src/core/workflow.ts
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -14,7 +15,7 @@ async function triggerWorkflow(action, payload) {
 		},
 		body: JSON.stringify({ input: payload ?? {} })
 	});
-	if (!triggerRes.ok) throw new Error(`Workflow trigger failed: ${triggerRes.status}`);
+	if (!triggerRes.ok) throw new Error(`Workflow trigger failed: ${await describeFailure(triggerRes)}`);
 	let details = await triggerRes.json();
 	while (details.status !== "FINISHED") {
 		if (details.status === "PENDING_INTERACTION") for (const interaction of details.nextInteractions) {
@@ -23,11 +24,11 @@ async function triggerWorkflow(action, payload) {
 				headers: { "Content-Type": "application/json" },
 				body: "{}"
 			});
-			if (!interactionRes.ok) throw new Error(`Workflow interaction failed: ${interactionRes.status}`);
+			if (!interactionRes.ok) throw new Error(`Workflow interaction failed: ${await describeFailure(interactionRes)}`);
 		}
 		await sleep(1e3);
 		const detailsRes = await fetch(`${softrApiUrl("SOFTR_WORKFLOWS_API_URL")}/v1/workflows/${action.resource.workflowId}/executions/${details.id}/details`);
-		if (!detailsRes.ok) throw new Error(`Workflow status check failed: ${detailsRes.status}`);
+		if (!detailsRes.ok) throw new Error(`Workflow status check failed: ${await describeFailure(detailsRes)}`);
 		details = await detailsRes.json();
 	}
 }

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/fetch.js

@@ -1,9 +1,29 @@
+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) => {
-	if (process.env.NODE_ENV === "production") return globalThis.fetch(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 method = init?.method ?? (input instanceof Request ? input.method : "GET");
 	const started = Date.now();
 	try {
@@ -16,6 +36,48 @@ const fetch = async (input, init) => {
 		throw error;
 	}
 };
+/**
+* RFC 9421 signature over the request, with the key Studio handed the app at publish or session start. The SDK
+* never derives, rotates or inspects the key: Softr derives it from a master key and the app's nonce, and the key
+* id (`<environment>/<applicationId>/<master number>`) is copied into the signature as is so the verifier can
+* derive the same key.
+*
+* The signature covers the method, authority, path, query and, when sent, the Authorization header. The body is
+* not covered: TLS protects it in transit, and signing is there to tell the app's own server from anyone holding a
+* user token, which needs no body coverage. So nothing is buffered here and the body streams through as given.
+*/
+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);
+	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 });
+}
+function base64(bytes) {
+	return btoa(String.fromCharCode(...new Uint8Array(bytes)));
+}
 
 //#endregion
 export { fetch };

package/dist/formatting.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import * as react2 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;
-}): react2.FunctionComponentElement<react2.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;
-}): react2.FunctionComponentElement<react2.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

@@ -1,7 +1,8 @@
 import { SoftrUserGroupId, SoftrUserGroups, SoftrUserProperties, User } from "./auth/user.js";
-import { ActionPermissions, SoftrDatasources, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
+import { ActionPermissions, SoftrDatasources, defineAiAction, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 import { FileAttachment } from "./core/file-upload.js";
 import { FileItem, useFileUpload } from "./core/use-file-upload.js";
+import { AiAnswer, AiFile, AiGenerateInit, AiMessage, AiUsage } from "./core/ai.js";
 import { DateOptions, DateParts, DateSeparator, DateValue, FixedDateFormat, FormattedDate, Formatting, FormattingScope, WeekDay, formatDate, formatDateTime, formatNumber, useFormatting } from "./formatting.js";
 import { SoftrContext } from "./auth/context.js";
 import { AuthSettings } from "./auth/platform.js";
@@ -16,7 +17,5 @@ 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 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 };
+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 };

package/dist/index.js

@@ -1,5 +1,5 @@
+import { defineAiAction, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 import { useFileUpload } from "./core/use-file-upload.js";
-import { defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 import { checkAccess, defineVisibility, isAuthorized } from "./route/visibility.js";
 import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./route/route.js";
 import { definePage, pageHead } from "./route/page.js";
@@ -12,8 +12,6 @@ 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, listAgents, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAgentChat, 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, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, 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.js

@@ -1,9 +1,9 @@
 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 { makePlatform } from "./auth/platform.js";
 import { ds } from "./datasource/datasource.js";
@@ -244,8 +244,7 @@ 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;
@@ -266,7 +265,6 @@ function describeTool(action) {
 		case "read": return {
 			name: action.id,
 			description: `Read records from "${action.id}". Returns the fields ${names.join(", ")}. Only records the signed-in user may see come back.`,
-			annotations: { readOnlyHint: true },
 			inputSchema: {
 				type: "object",
 				properties: {
@@ -387,10 +385,8 @@ async function rpc(request, origin, actions) {
 	const token = bearerToken(request);
 	if (token === null) return unauthorized(origin);
 	const session = await platformSession(token);
-	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();
+	if (!session.ok) return session.refused ? unauthorized(origin) : unavailable();
+	const { sessionToken } = session;
 	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.89-alpha.4";
+var version = "0.0.90-ai.0";
 
 //#endregion
 export { version };

package/dist/pwa.d.ts

@@ -1,4 +1,4 @@
-import * as react0 from "react";
+import * as react4 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(): react4.FunctionComponentElement<react4.FragmentProps>;
 type PwaPlatform = "ios" | "android" | "desktop";
 type PwaInstall = {
   available: false;

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;
-		fetch(INSTALL_PATH, { headers: { accept: "application/json" } }).then(async (response) => {
+		globalThis.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/server.d.ts

@@ -1,8 +1,9 @@
 import { upload } from "./core/file-upload.js";
+import { AiError, ai } from "./core/ai.js";
 import { auth } from "./auth/server.js";
 import { FieldChoice, RecordOption, RecordOptions } from "./core/options.js";
 import { ds } from "./datasource/datasource.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import "@tanstack/react-start/server-only";
-export { type FieldChoice, type RecordOption, type RecordOptions, auth, ds, integration, upload, workflow };
+export { AiError, type FieldChoice, type RecordOption, type RecordOptions, ai, auth, ds, integration, upload, workflow };

package/dist/server.js

@@ -3,6 +3,7 @@ import { ds } from "./datasource/datasource.js";
 import { auth } from "./auth/server.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
+import { AiError, ai } from "./core/ai.js";
 import "@tanstack/react-start/server-only";
 
-export { auth, ds, integration, upload, workflow };
+export { AiError, ai, auth, ds, integration, upload, workflow };

package/package.json

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

package/skills/softr-sdk/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.89-alpha.4
+  library_version: 0.0.89
 ---
 
 # Softr SDK core
@@ -22,6 +22,8 @@ metadata:
 >
 > **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.
 >
+> **CRITICAL**: `ai.generate` and `ai.stream` live on `@softr/sdk/server` and only run inside a `createServerFn` handler. Use `defineAiAction` from `@softr/sdk` to declare the action with the model it runs on, an id copied from the `ai_list_models` tool. Softr runs the model on its own keys; never ask the user for an API key for the app's own AI feature. Load the `softr-sdk/ai` sub-skill for the full pattern.
+>
 > **CRITICAL**: `workflow.trigger` lives on `@softr/sdk/server` and only runs inside a `createServerFn` handler. Use `defineWorkflow` from `@softr/sdk` to declare the action, then pass it to `workflow.trigger`. Load the `softr-sdk/workflows` sub-skill for the full pattern.
 
 Each sub-skill stands alone for its task and repeats the boundary above, so most work needs **one** sub-skill and not this file. Load this one when you are unsure which sub-skill applies, or when the wiring below is what you are touching. Add a second sub-skill only when the work genuinely crosses that boundary: a page that lists records behind a group restriction needs `record-queries` plus `routes-and-visibility`.
@@ -30,8 +32,8 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@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` | Both | `defineQuery`, `defineMutation`, `defineAiAction`, `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`, `ai` |
 | `@softr/sdk/client` | Browser only | `useFileUpload` |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
 
@@ -47,9 +49,9 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Create, update or delete a record | [record-mutations/SKILL.md](./record-mutations/SKILL.md) |
 | Trigger a Softr workflow | [workflows/SKILL.md](./workflows/SKILL.md) |
 | 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) |
+| 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) |
 
@@ -80,15 +82,18 @@ Triggering a Softr workflow from a button or form?
 Wiring a login, signup, or sign-out?
   load softr-sdk/auth
 
+Asking an AI model for anything: a summary, fields out of a document, a classification, a draft, a chat?
+  load softr-sdk/ai — Softr runs the model on its own keys, nothing to connect; pick the model from ai_list_models
+
 Calling a connected third-party API (Slack, Stripe, Gmail, Google Calendar, …)?
   load softr-sdk/integrations
 
+Running a model on the user's OWN provider account, because they chose that for the feature?
+  load softr-sdk/integrations: its "Calling an AI model" section
+
 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