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

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

@@ -0,0 +1,168 @@
+---
+name: ai
+description: >-
+  Run an AI model from the app on Softr's own keys, billed to the workspace's
+  AI credits, with nothing to connect: defineAiAction from @softr/sdk declares
+  the action with the catalog model it runs on and its permissions;
+  ai.generate from @softr/sdk/server runs it with a system text, a prompt, an
+  optional JSON schema for an answer that is data, and optional files;
+  ai.stream runs it for an answer the user watches being written. Load this
+  for a summary, an extraction, a classification, a draft, or a chat the app
+  asks a model for, before you decide whether a feature runs on Softr AI
+  or on the user's own account, and before you change the model it runs on.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.79-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.
+
+# AI
+
+An app asks a model through an AI action. Softr runs the call on its own provider keys and bills the workspace's AI credits, so there is no key to ask the user for and nothing to connect. This is the default for every AI feature of the app's own — a summary of a record, fields extracted from a document, a classification, a draft, a chat. The other path is the user's own provider account, through a connected integration: the `integrations` sub-skill. An app can hold both: each feature carries its own choice in its code.
+
+## Decide who runs it first
+
+Never choose silently between Softr AI and the user's own account. Decide for each AI feature, before you write its code, in this order:
+
+1. The user said who runs it: follow it. "My OpenAI key" or "our Anthropic account", with exactly one integration of that type in `integration_list`: use that one, without asking. A new key of a provider they named — they asked for a new one, or the workspace holds none of that type — is one `requestinput` of type `integration` for that type: its card connects one. A connected key runs the feature; a skipped request means Softr AI, and you say so. Several keys of that type, or "my own key" with no provider: ask (step 4). A provider or a model named without "my" or "our" ("use Claude", "summarise with GPT") is a model preference on Softr AI, not a reason to ask.
+2. The app already has AI features: follow the choice they made, and say so in one line.
+3. `integration_list` shows no `OPEN_AI`, `ANTHROPIC_AI` or `GEMINI_AI` integration: use Softr AI, and say so in one line. Call the tool; do not assume the answer.
+4. Otherwise ask with one `requestinput` of type `aiProvider`. Its card lists every key the workspace holds and every provider to connect, unfiltered. The answer is Softr AI, or the integration with its id and type: follow it, even when it is another provider than the one the user named. A declined request means Softr AI: use it, and say so in one line.
+
+Never ask who runs a feature, or which key, with the `question` tool: its free-text answer invites the user to type a key into the chat.
+
+Ask at most once per turn. A turn that builds several AI features sends one request, and its `feature` names every one of them in the user's words: "Deal summary and lead tagging". It holds the names only, never the provider, the key or how the feature runs, because the card asks exactly that: "Product chat", not "Product chat, using an OpenAI key".
+
+An own-account answer leaves this skill: the call goes through `defineIntegration`, as the `integrations` sub-skill describes.
+
+## Choose the model
+
+The model is chosen when the app is built and frozen in its code. Before you declare an action, read Softr's catalog with the `ai_list_models` tool: the most recent models of each provider. Each entry carries the `id` the action names, the `provider`, `bestFor`, what to pick it for, `reads`, what it reads beside text, and `reasoning`, whether it thinks before it answers. (`providerModelId` is for the own-account path of the `integrations` sub-skill, never for `defineAiAction`.)
+
+- by default — a chat, an assistant, a summary, a briefing, a draft: a mid-tier model, `anthropic`'s newest one between its cheapest and strongest. When the user named another provider, that provider's mid-tier model;
+- an extraction or a classification: the cheapest model whose `reads` covers what it is given — an image or a PDF needs `IMAGE`;
+- the strongest model listed only when the user asks for more quality.
+
+Copy the `id` exactly from the tool's answer. An id outside the catalog is refused when the action is saved, and a model spelled from memory, or taken from an example, never is in it.
+
+## Changing it later
+
+A model change asked in chat ("use a cheaper model", "try Gemini") edits the `model` of the feature's action, or, on the user's own account, the `providerModelId` its call sends. Read `ai_list_models` again and copy the new id. It never sends an `aiProvider` request. On the user's own account the new model is one of that account's provider: a model of another provider, or a switch to the user's own key, changes who runs it, so follow step 1 of the order above.
+
+## Say it
+
+The plan and the closing message give one line per AI feature built or changed: who runs it, its model, what it bills — Softr AI uses the workspace's AI credits, the user's own key is billed by its provider — and that the user can ask to switch the model or to use their own OpenAI, Anthropic or Gemini key. For example: "Deal summary runs on Softr AI with <the model> and uses your workspace's AI credits. Ask me to switch the model or to use your own OpenAI, Anthropic or Gemini key."
+
+## Declare the action
+
+```ts
+const summarizeDeal = defineAiAction({
+  id: 'summarizeDeal',
+  model: '<an id from ai_list_models>',
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
+})
+```
+
+Write the object inline in `defineAiAction`. Passing it through a variable widens the types.
+
+**Every call spends the workspace's credits.** Keep the audience to `['LOGGED_IN_USERS']`, narrowed with `customGroups` where the feature is for some users only. Open an AI action to visitors only when a public page really needs it, and say so to the user: anyone on the internet can then bill the workspace.
+
+Declare one action per feature — the summary and the extraction are two actions, each with its own `id`, its own model and its own audience.
+
+## Core pattern: an answer the server reads
+
+`ai.generate(action, init)` runs the action and answers when the model is done. `init` takes:
+
+- `prompt` — what the model is asked, with the facts it is given. Required.
+- `system` — what the model is and the rules it answers under.
+- `schema` — 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`.
+- `files` — documents and images the model reads, each as `{ url, mimeType? }`: an `https` URL Softr may fetch, one of the app's own uploads as a rule.
+- `maxOutputTokens` — a cap on the answer's length. Softr caps it further.
+- `messages` — the earlier turns of a conversation, oldest first, each `{ role: 'user' | 'assistant', content }`. The prompt is the newest turn. Leave out for a one-shot call.
+- `reasoning` — `'low'`, `'medium'` or `'high'`: how hard a reasoning model thinks before it answers. The catalog says which models reason; the others ignore it. Leave out for the provider's default.
+- `temperature` — 0 to 1: how varied the answer is. `0` for an extraction or a classification, around `0.7` for a draft. Left out, the provider's default applies. A model whose provider no longer takes one, such as the Claude 5 models, ignores it.
+
+The answer is `{ text, json, usage, model }`: `text` as the model wrote it, `json` parsed when a schema was given and the model kept to it, `null` otherwise.
+
+```ts
+const summarize = createServerFn({ method: 'POST' })
+  .validator(z.object({ recordId: z.string() }))
+  .handler(async ({ data }) => {
+    const deal = await ds.get(dealQuery, { id: data.recordId })
+    if (deal === null) throw new Error('This deal no longer exists')
+    const facts = [`Name: ${fieldText(deal.fields.name)}`, `Stage: ${fieldText(deal.fields.stage)}`].join('\n')
+    const answer = await ai.generate(summarizeDeal, {
+      system: 'You brief a sales team. Use only the facts given; say what is missing rather than invent it.',
+      prompt: facts,
+      maxOutputTokens: 800,
+    })
+    return answer.text
+  })
+```
+
+## Extraction: an answer that is data
+
+A document dropped on the app, fields pulled out of it, a record created — the model reads the file and answers in the shape the record needs. Give it the schema and the file; validate the parsed answer before writing it, since a model may stray from the shape.
+
+```ts
+const InvoiceFields = z.object({ vendor: z.string(), total: z.number(), issuedOn: z.string() })
+
+const extractInvoice = createServerFn({ method: 'POST' })
+  .validator(z.object({ fileUrl: z.string().url() }))
+  .handler(async ({ data }) => {
+    const answer = await ai.generate(readInvoice, {
+      system: 'Read the invoice and answer with its fields. Dates as YYYY-MM-DD, amounts as numbers.',
+      prompt: 'Extract the vendor, the total and the issue date.',
+      schema: {
+        type: 'object',
+        properties: { vendor: { type: 'string' }, total: { type: 'number' }, issuedOn: { type: 'string' } },
+        required: ['vendor', 'total', 'issuedOn'],
+      },
+      files: [{ url: data.fileUrl, mimeType: 'application/pdf' }],
+    })
+    const parsed = InvoiceFields.safeParse(answer.json)
+    if (!parsed.success) throw new Error('The invoice could not be read. Try a clearer scan.')
+    return ds.create(createInvoice, { data: parsed.data })
+  })
+```
+
+The file's URL comes from the app's own upload: load the Softr SDK `file-uploads` guidance for that half. `readInvoice` names a model whose `bestFor` reads PDF documents.
+
+## Streaming: an answer the user watches being written
+
+A chat, an assistant, a long draft shown as it is typed — never buffer these: the user would watch a blank panel until the last token. A chat box the user types into is always this case, never `ai.generate`. `ai.stream(action, init)` takes the same `init` and answers with a `Response` whose body is a stream of Server-Sent Events. Hand it to the browser from the server function, unchanged:
+
+```ts
+const draftReply = createServerFn({ method: 'POST' })
+  .validator(z.object({ prompt: z.string() }))
+  .handler(async ({ data }) => {
+    const res = await ai.stream(draftAction, { system: 'You write replies for a support team.', prompt: data.prompt })
+    return new Response(res.body, { headers: { 'Content-Type': 'text/event-stream' } })
+  })
+```
+
+Each event is one JSON object on a `data:` line:
+
+- `{ "text": "..." }` — the next piece of the answer; append it.
+- `{ "done": true, "usage": { "inputTokens", "outputTokens" }, "model": "..." }` — the answer is complete.
+- `{ "error": "..." }` — in place of `done`, when the call ended before its answer: show the message.
+
+On the client, call the server function's URL with `fetch`, read `response.body` with a stream reader, split on blank lines, and parse the JSON after `data:`. A conversation sends its earlier turns in `messages`; the app keeps them, the model holds nothing between calls.
+
+## Failure modes
+
+**Calling from client code.** `ai` is server-only. Importing it into a component or calling it outside a `createServerFn` handler fails the build or has no request context to act on.
+
+**Spelling a model id.** `model` is copied from `ai_list_models`, never written from memory. An id outside the catalog fails the save of the action, so the app cannot be published with it.
+
+**No credits left.** `ai.generate` and `ai.stream` throw an `AiError` whose `status` is `402` when the workspace has no AI credits. Show its message to the user; the workspace owner tops the credits up in Softr. Any other refusal carries its status and reason the same way.
+
+**Trusting `json` without checking it.** A model may stray from the schema; `json` is then `null`, or a shape close to the one asked. Validate it with `zod` before writing it to a record, and keep `text` as the fallback the user can read.
+
+**Buffering a chat.** A chat built on `ai.generate` shows nothing until the whole reply is done, and the user reads "replies appear all at once" in your closing message. A chat streams.
+
+**Reading a streamed body with `res.json()`.** The body of `ai.stream` is an event stream, not one JSON document. Return `res.body` in a `Response` or read it with a stream reader.
+
+**Asking for the user's API key.** An AI feature of the app's own needs none. Only when the user chose their own provider account for the feature does the call go through a connected integration — load the `integrations` sub-skill then.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.89-alpha.4
+  library_version: 0.0.89
 ---
 
 **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.89-alpha.4
+  library_version: 0.0.89
 ---
 
 **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.89-alpha.4
+  library_version: 0.0.89
 ---
 
 # 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.89-alpha.4
+  library_version: 0.0.89
 ---
 
 **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.89-alpha.4
+  library_version: 0.0.89
 ---
 
 # 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.89-alpha.4
+  library_version: 0.0.89
 ---
 
 **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.
@@ -126,7 +126,11 @@ Do not add an `Authorization` key to `headers` — Softr injects the integration
 
 ## Calling an AI model
 
-A button on one record that hands its fields to the model and shows the answer is the `ai-action` pattern: it carries this call and the model id, so write the call by hand only for another shape — a batch, a chat, a field the model fills on create. An AI integration is called like any other. For `ANTHROPIC_AI`, the action is `POST` on `https://api.anthropic.com/v1/messages`, the request carries the `anthropic-version` header and a body of `model`, `max_tokens`, `system` and `messages`, and the answer's text is in `content[].text`:
+**This is the path for the user's own provider account only.** An AI feature of the app's own — a summary, an extraction, a chat — runs on Softr's keys through an AI action, with nothing to connect and no key to ask for: load the `ai` sub-skill for it. Call a model through an integration only when the user chose their own OpenAI, Anthropic or Gemini account for the feature, in the prompt or when asked, and had it connected.
+
+**The model id comes from `ai_list_models`, never from memory.** Each entry of that list carries `providerModelId`, the id the provider's own API accepts, and `provider`: `anthropic` for an `ANTHROPIC_AI` integration, `openai` for `OPEN_AI`, `google_ai` for `GEMINI_AI`. Pick an entry of the integration's provider as the `ai` sub-skill's "Choose the model" says, and send its `providerModelId`. An id spelled from memory (`claude-3-5-…`, `gpt-4o`) names a model that no longer answers, and the error only shows up when the button is pressed.
+
+An AI integration is called like any other. For `ANTHROPIC_AI`, the action is `POST` on `https://api.anthropic.com/v1/messages`, the request carries the `anthropic-version` header and a body of `model`, `max_tokens`, `system` and `messages`, and the answer's text is in `content[].text`:
 
 ```ts
 const askClaude = defineIntegration({
@@ -141,7 +145,7 @@ const claude = integration.createFetcher(askClaude)
 const res = await claude({
   headers: { 'Content-Type': 'application/json', 'anthropic-version': '2023-06-01' },
   body: JSON.stringify({
-    model: 'claude-opus-5-5',
+    model: '<providerModelId of an anthropic entry of ai_list_models>',
     max_tokens: 1024,
     system: 'You write a short briefing for a sales team. Use only the facts given.',
     messages: [{ role: 'user', content: facts }],
@@ -152,7 +156,7 @@ const body = (await res.json()) as { content: Array<{ type: string; text?: strin
 const text = body.content.flatMap((block) => (block.type === 'text' && block.text ? [block.text] : [])).join('')
 ```
 
-**Use the model id above as it is written here.** Model ids are not derivable: one spelled from memory (`claude-3-5-…`, `claude-sonnet-4-…`) names a model that no longer answers, and the error only shows up when the button is pressed. `claude-opus-5-5` is the current default; `claude-sonnet-5-5` is the cheaper one for a short summary.
+For `OPEN_AI`, the action is `POST` on `https://api.openai.com/v1/chat/completions` with a body of `model` and `messages` (the system text as the first message, role `system`); the answer's text is in `choices[0].message.content`. For `GEMINI_AI`, the action is `POST` on `https://generativelanguage.googleapis.com/v1beta/models/<providerModelId>:generateContent` with a body of `contents` (`[{ role: 'user', parts: [{ text }] }]`) and an optional `systemInstruction`; the answer's text is in `candidates[0].content.parts[].text`. Read the answer defensively: a refusal or an empty answer leaves the text out.
 
 ## Base URLs by integration type
 

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.89-alpha.4
+  library_version: 0.0.89
 ---
 
 **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.89-alpha.4
+  library_version: 0.0.89
 ---
 
 # 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.89-alpha.4
+  library_version: 0.0.89
 ---
 
 **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.89-alpha.4
+  library_version: 0.0.89
 ---
 
 **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.89-alpha.4
+  library_version: 0.0.89
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.89-alpha.4
+  library_version: 0.0.89
 ---
 
 **Boundary.** `definePage`, `pageHead`, 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.89-alpha.4
+  library_version: 0.0.89
 ---
 
 **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/agent/agent-fns.d.ts

@@ -1,30 +0,0 @@
-import { z } from "zod";
-import * as _tanstack_react_start8 from "@tanstack/react-start";
-
-//#region src/agent/agent-fns.d.ts
-
-declare const agentSchema: z.ZodObject<{
-  id: z.ZodString;
-  title: z.ZodString;
-  avatar: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-  thumbnail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-}, z.core.$strip>;
-/** An agent the visitor may chat with. */
-type Agent = z.infer<typeof agentSchema>;
-/**
- * The agents the visitor may chat with in this app. The builder attaches them
- * in Studio, and each one's visibility settings decide who sees it.
- */
-declare const listAgents: _tanstack_react_start8.OptionalFetcher<undefined, undefined, Promise<{
-  id: string;
-  title: string;
-  avatar?: string | null | undefined;
-  thumbnail?: string | null | undefined;
-}[]>>;
-/** One past chat with an agent. `title` is null until the agent names the chat. */
-type AgentChatSummary = {
-  id: string;
-  title: string | null;
-};
-//#endregion
-export { Agent, AgentChatSummary, listAgents };

package/dist/agent/agent-fns.js

@@ -1,215 +0,0 @@
-import { assert } from "../assertions.js";
-import { fetch } from "../fetch.js";
-import { sessionConfig } from "../auth/config.js";
-import { readSessionToken } from "../auth/session.js";
-import { softrApiUrl } from "../softr-api.js";
-import { describeFailure, refererHeader } from "../datasource/record.js";
-import { z } from "zod";
-import { createServerFn } from "@tanstack/react-start";
-import { getRequest } from "@tanstack/react-start/server";
-
-//#region src/agent/agent-fns.ts
-const AGENTS_PRODUCTION = "https://agents-api.softr.io";
-const PLATFORM_HOST = /^(platform-api|platform-preview-api|preview-api)(?=[.-])/;
-/**
-* Where the agents service is. It sits next to the platform API, so unless
-* `SOFTR_AGENTS_API_URL` says otherwise, it's the platform's host with
-* `agents-api` in place of the platform's name. Live and preview share one
-* agents service.
-*/
-function agentsApiUrl() {
-	const explicit = process.env.SOFTR_AGENTS_API_URL;
-	if (explicit) return explicit.replace(/\/+$/, "");
-	if (!process.env.SOFTR_PLATFORM_API_URL) return AGENTS_PRODUCTION;
-	const platform = new URL(softrApiUrl("SOFTR_PLATFORM_API_URL"));
-	assert(PLATFORM_HOST.test(platform.hostname), () => `can't tell the agents API from ${platform.origin}, set SOFTR_AGENTS_API_URL`);
-	platform.hostname = platform.hostname.replace(PLATFORM_HOST, "agents-api");
-	return platform.origin;
-}
-function agentsFetch(path, init = {}) {
-	const token = readSessionToken();
-	return fetch(`${agentsApiUrl()}/v1/agents/${path}`, {
-		method: init.method ?? "GET",
-		signal: init.signal,
-		headers: {
-			"Content-Type": "application/json",
-			...token ? { Authorization: `Bearer ${token}` } : {},
-			"Softr-Application-ID": sessionConfig().applicationId,
-			...refererHeader(),
-			...init.headers
-		},
-		body: init.body === void 0 ? void 0 : JSON.stringify(init.body)
-	});
-}
-const chatSchema = z.object({
-	agentId: z.string().min(1),
-	message: z.string(),
-	sessionId: z.string().nullable(),
-	timezone: z.string(),
-	pageName: z.string(),
-	pageUrl: z.string(),
-	record: z.object({
-		id: z.string(),
-		fields: z.record(z.string(), z.unknown())
-	}).nullable()
-});
-/**
-* Sends one message and streams the reply back as it comes, one JSON event per line.
-*
-* Takes FormData so the browser can call it with plain `fetch` and read the
-* stream itself. A failed call passes the agents service's status and message on.
-*/
-const agentChatFn = createServerFn({ method: "POST" }).validator((data) => {
-	const payload = data.get("payload");
-	assert(typeof payload === "string", "agent chat: payload is required");
-	return chatSchema.parse(JSON.parse(payload));
-}).handler(async ({ data }) => {
-	const upstream = await agentsFetch(`${encodeURIComponent(data.agentId)}/chat`, {
-		method: "POST",
-		signal: getRequest().signal,
-		headers: {
-			Accept: "application/x-ndjson",
-			"X-User-Timezone": data.timezone
-		},
-		body: {
-			message: data.message,
-			...data.sessionId ? { sessionId: data.sessionId } : {},
-			context: {
-				pageName: data.pageName,
-				pageUrl: data.pageUrl,
-				...data.record ? { currentRecord: { data: data.record } } : {}
-			}
-		}
-	});
-	return new Response(upstream.body, {
-		status: upstream.status,
-		headers: { "Content-Type": upstream.headers.get("Content-Type") ?? "application/x-ndjson" }
-	});
-});
-const agentSchema = z.object({
-	id: z.string(),
-	title: z.string(),
-	avatar: z.string().nullish(),
-	thumbnail: z.string().nullish()
-});
-/**
-* The agents the visitor may chat with in this app. The builder attaches them
-* in Studio, and each one's visibility settings decide who sees it.
-*/
-const listAgents = createServerFn({ method: "GET" }).handler(async () => {
-	const token = readSessionToken();
-	const res = await fetch(`${softrApiUrl("SOFTR_PLATFORM_API_URL")}/v1/vibe/applications/${sessionConfig().applicationId}/agents`, { headers: token ? { Authorization: `Bearer ${token}` } : {} });
-	if (!res.ok) throw new Error(`Loading agents failed: ${await describeFailure(res)}`);
-	return z.array(agentSchema).parse(await res.json());
-});
-const listAgentChatsFn = createServerFn({ method: "POST" }).validator(z.object({ agentId: z.string().min(1) })).handler(async ({ data }) => {
-	const res = await agentsFetch(`${encodeURIComponent(data.agentId)}/sessions`);
-	if (!res.ok) throw new Error(`Loading chats failed: ${await describeFailure(res)}`);
-	return z.array(z.object({
-		id: z.string(),
-		title: z.string().nullable()
-	})).parse(await res.json());
-});
-const historySchema = z.object({
-	messages: z.array(z.object({
-		id: z.string(),
-		role: z.enum(["USER", "ASSISTANT"]),
-		content: z.string(),
-		createdAt: z.number()
-	})),
-	toolCalls: z.array(z.object({
-		id: z.string(),
-		messageId: z.string(),
-		toolName: z.string(),
-		input: z.string(),
-		createdAt: z.number(),
-		metadata: z.object({
-			innerThought: z.string().nullish(),
-			durationMs: z.number().nullish(),
-			failed: z.boolean().nullish()
-		})
-	}))
-});
-const CHAT_GONE = [
-	401,
-	403,
-	404,
-	410
-];
-/** What a past chat holds, or `null` when it's gone or belongs to someone else. */
-const loadAgentChatFn = createServerFn({ method: "POST" }).validator(z.object({
-	agentId: z.string().min(1),
-	sessionId: z.string().min(1)
-})).handler(async ({ data }) => {
-	const res = await agentsFetch(`${encodeURIComponent(data.agentId)}/sessions/${encodeURIComponent(data.sessionId)}`);
-	if (CHAT_GONE.includes(res.status)) return null;
-	if (!res.ok) throw new Error(`Loading the chat failed: ${await describeFailure(res)}`);
-	return historySchema.parse(await res.json());
-});
-/** Saves the visitor's answer. `false` when the chat is gone, see `loadAgentChatFn`. */
-const decideAgentToolFn = createServerFn({ method: "POST" }).validator(z.object({
-	agentId: z.string().min(1),
-	sessionId: z.string().min(1),
-	toolCallId: z.string().min(1),
-	toolName: z.string().min(1),
-	decision: z.enum(["APPROVE", "REJECT"]),
-	scope: z.enum([
-		"ONCE",
-		"SESSION",
-		"USER"
-	])
-})).handler(async ({ data: { agentId,...decision } }) => {
-	const res = await agentsFetch(`${encodeURIComponent(agentId)}/tool-permission-decisions`, {
-		method: "POST",
-		body: decision
-	});
-	if (CHAT_GONE.includes(res.status)) return false;
-	if (!res.ok) throw new Error(`Saving the answer failed: ${await describeFailure(res)}`);
-	return true;
-});
-const connectionSchema = z.object({
-	integration: z.string().min(1),
-	requestId: z.string().min(1)
-});
-function connectionUrl({ integration, requestId }, step) {
-	const { applicationId } = sessionConfig();
-	const provider = encodeURIComponent(integration.toLowerCase());
-	return `${`${softrApiUrl("SOFTR_DATASOURCE_API_URL")}/v1/datasource/applications/${applicationId}`}/integrations/${provider}/oauth/${step}?${new URLSearchParams({ requestId })}`;
-}
-/** The sign-in page to open in the popup. */
-const startAgentConnectionFn = createServerFn({ method: "POST" }).validator(connectionSchema).handler(async ({ data }) => {
-	const token = readSessionToken();
-	const res = await fetch(connectionUrl(data, "register"), {
-		method: "POST",
-		headers: {
-			...token ? { Authorization: `Bearer ${token}` } : {},
-			...refererHeader()
-		}
-	});
-	if (!res.ok) throw new Error(`Starting the connection failed: ${await describeFailure(res)}`);
-	return z.object({ url: z.string() }).parse(await res.json()).url;
-});
-/** Waits a while for the visitor to finish signing in. `false` when they haven't yet. */
-const awaitAgentConnectionFn = createServerFn({ method: "POST" }).validator(connectionSchema).handler(async ({ data }) => {
-	const res = await fetch(connectionUrl(data, "register-result"), { signal: getRequest().signal });
-	if (res.status === 503) return false;
-	if (!res.ok) throw new Error(`Connecting failed: ${await describeFailure(res)}`);
-	return true;
-});
-/** Tells the agent the account is connected. `false` when the chat is gone, see `loadAgentChatFn`. */
-const finishAgentConnectionFn = createServerFn({ method: "POST" }).validator(z.object({
-	agentId: z.string().min(1),
-	sessionId: z.string().min(1),
-	toolCallId: z.string().min(1)
-})).handler(async ({ data: { agentId,...completion } }) => {
-	const res = await agentsFetch(`${encodeURIComponent(agentId)}/integration-auth-completions`, {
-		method: "POST",
-		body: completion
-	});
-	if (CHAT_GONE.includes(res.status)) return false;
-	if (!res.ok) throw new Error(`Finishing the connection failed: ${await describeFailure(res)}`);
-	return true;
-});
-
-//#endregion
-export { agentChatFn, awaitAgentConnectionFn, decideAgentToolFn, finishAgentConnectionFn, listAgentChatsFn, listAgents, loadAgentChatFn, startAgentConnectionFn };