@softr/sdk 0.0.79-alpha.0 → 0.0.79-alpha.1

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { DatasourceAction } from "./action.js";
-import * as _tanstack_react_start5 from "@tanstack/react-start";
+import * as _tanstack_react_start0 from "@tanstack/react-start";
 
 //#region src/mcp.d.ts
 
@@ -31,6 +31,6 @@ type SoftrMcpOptions = {
  *   ],
  * }))
  */
-declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start5.RequestMiddlewareAfterServer<{}, undefined, undefined>;
+declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>;
 //#endregion
 export { softrMcpMiddleware };

package/dist/package.js

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

package/package.json

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

package/skills/softr-sdk/SKILL.md

@@ -84,7 +84,7 @@ Asking an AI model for anything: a summary, fields out of a document, a classifi
 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 asked for that?
+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?

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

@@ -8,7 +8,8 @@ description: >-
   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.
+  asks a model for, and before you decide whether a feature runs on Softr AI
+  or on the user's own account.
 metadata:
   type: sub-skill
   library: softr-sdk
@@ -19,23 +20,34 @@ metadata:
 
 # 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 path 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 — unless the user explicitly asked to use their own provider account, which is the `integrations` sub-skill's path.
+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.
 
-## Choose the model first
+## Decide who runs it first
+
+Never choose silently between Softr AI and the user's own account. Decide per feature, before you write it, in this order:
+
+1. The user named Softr AI or their own account in the prompt: follow it.
+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`, naming the feature. The answer is Softr AI, or the integration with its id and type; a declined request means Softr AI.
+
+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. Each entry carries the `id` the action names, the `provider`, and `bestFor`, what to pick it for:
 
-- a summary, a briefing, a draft, reasoning over many facts: the strongest model listed;
+- a chat, an assistant, a summary, a briefing, a draft, reasoning over many facts: the strongest model listed;
 - an extraction or a classification over one document: the cheapest model that reads that document's kind — a PDF needs a model whose `bestFor` says so.
 
-Copy the `id` exactly. An id outside the catalog is refused when the action is saved, and a model spelled from memory never is in it.
+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.
 
 ## Declare the action
 
 ```ts
 const summarizeDeal = defineAiAction({
   id: 'summarizeDeal',
-  model: 'anthropic-claude-sonnet-4-6',
+  model: '<an id from ai_list_models>',
   permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
 })
 ```
@@ -105,29 +117,9 @@ const extractInvoice = createServerFn({ method: 'POST' })
 
 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.
 
-## A conversation
-
-A chat sends its earlier turns in `messages` and the new one as `prompt`. The app keeps the turns; the model holds nothing between calls.
-
-```ts
-const reply = createServerFn({ method: 'POST' })
-  .validator(z.object({ turns: z.array(z.object({ role: z.enum(['user', 'assistant']), content: z.string() })), prompt: z.string() }))
-  .handler(async ({ data }) => {
-    const answer = await ai.generate(supportChat, {
-      system: 'You answer questions about the order the user is looking at.',
-      messages: data.turns,
-      prompt: data.prompt,
-      temperature: 0.5,
-    })
-    return answer.text
-  })
-```
-
-A chat the user watches being written streams instead, with the same `messages`: see the next section.
-
 ## 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. `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:
+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' })
@@ -144,7 +136,7 @@ Each event is one JSON object on a `data:` line:
 - `{ "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:`.
+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
 
@@ -156,6 +148,8 @@ On the client, call the server function's URL with `fetch`, read `response.body`
 
 **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 asks to run the app on their own provider account does the call go through a connected integration — load the `integrations` sub-skill then.
+**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/integrations/SKILL.md

@@ -126,7 +126,7 @@ Do not add an `Authorization` key to `headers` — Softr injects the integration
 
 ## Calling an AI model
 
-**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 asked to use their own OpenAI, Anthropic or Gemini account, and had it connected.
+**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.
 
 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