@softr/sdk 0.0.90-alpha.2 → 0.0.90-alpha.3

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

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

package/dist/package.js

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

package/dist/pwa.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.90-alpha.2",
+  "version": "0.0.90-alpha.3",
   "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.90-alpha.2
+  library_version: 0.0.90-alpha.3
 ---
 
 # Softr SDK core

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

@@ -1,25 +1,21 @@
 ---
 name: agent-chat
 description: >-
-  Let visitors chat with one of the app's Softr agents: listAgents() from
-  @softr/sdk gives the agents the visitor may use, and useAgentChat(agentId, {
-  record }) returns the messages, the reply as it streams, past chats, and
-  send, stop, approve, reject and connect, with no UI. Load it for an agent
-  chat panel, approving the agent's actions, or connecting the visitor's own
-  account (Gmail, Slack…) that a tool needs. Build the chat from the app's own
-  components. The agent acts on the app's data through the app's MCP, so
-  softrMcpMiddleware must list the actions it may use.
+  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, or connecting the visitor's account a tool needs.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.90-alpha.2
+  library_version: 0.0.90-alpha.3
 ---
 
 **Boundary.** `listAgents` and `useAgentChat` live on `@softr/sdk`. `listAgents` runs in a route loader, `useAgentChat` in a component. Neither needs a route, server function or registration of its own. It chats as the signed-in visitor, or anonymously when no one is signed in.
 
 # Agent chat
 
-A Softr agent is set up in Studio's Agents tab and attached to the app there. The app gives it a chat. There is no ready-made chat widget: the hook gives the state, and the app draws it with its own components.
+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
 
@@ -27,7 +23,7 @@ A Softr agent is set up in Studio's Agents tab and attached to the app there. Th
 import { listAgents, useAgentChat } from '@softr/sdk'
 ```
 
-`listAgents()` resolves to the agents this visitor may chat with, `{ id, title, avatar, thumbnail }[]`. Call it in the route's `loader`. An agent hidden from this visitor isn't in the list, so show no chat when it's empty. When there are several, let the visitor pick one, or pick the one the builder named by its `title`. Take the id from the list, never write one by hand.
+`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
 
@@ -58,7 +54,7 @@ function AgentPanel({ agentId, ticket }: { agentId: string; ticket: Ticket | nul
 
 ## 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. A tool waiting for Approve or Connect comes last in its message, so render blocks in the order given.
+- `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`.
@@ -69,46 +65,19 @@ function AgentPanel({ agentId, ticket }: { agentId: string; ticket: Ticket | nul
 
 ## Rendering a message
 
-Each message has `role` (`user` or `assistant`) and `blocks`, in the order the agent produced them. Render every block type:
+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 text |
-| `tool` | One line: the tool `name` and its `status`. Collapse finished ones. Expanded, show `thought`, `input`, `error` and `durationMs`. |
+| `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 ", ". |
+| `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, as classic apps do. 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 has to approve the same action again on every call. The agent continues on its own after an approval.
+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. Any integration works the same way, so don't build one per integration.
-
-## The chat panel
-
-Visitors expect the panel classic Softr apps ship:
-
-- A round `primary` button in a corner opens it, with the agent's avatar or a chat icon. It hides while the panel is open.
-- A right-side panel, about 420px, full screen on mobile.
-- Header: avatar, name, agent picker when there are several, new chat, past chats, close.
-- The list follows the streaming reply until the visitor scrolls up, then offers a jump back down.
-- Text renders as Markdown, tables included.
-- The input says "Ask {agent title}…". Enter sends, Shift+Enter adds a line. Under it: "AI can make mistakes. Please double-check responses."
-- An answered question stays locked.
-- A tool's `input` shows as `Label: value` lines, never raw JSON. Empty `thought`, `input`, `error` or duration are left out.
-
-## How it looks
-
-Defaults for the first build. The builder's prompt overrides them.
-
-- Reuse the app's own components and styles: its Markdown renderer, cards, buttons, avatars. Add no copies and no new colours.
-- One loud thing at a time. Tool lines stay quiet; only a block waiting for the visitor stands out.
-- Visitor messages are right-aligned `primary` bubbles. Agent replies have no bubble and run full width, so tables read like a page.
-- A tool is one muted `text-xs` line with a status icon, expandable.
-- Approve, connect and questions sit in a `card`: a title, a short line, the main action `primary`.
-- While `thinking`, a muted pulsing "Thinking…" where the reply will appear.
-- An empty chat shows a large avatar and "Hi, I'm {agent title}". Add suggestion chips only when the builder said what the agent does.
-- The composer is one rounded box holding the textarea and send button. It grows to about six lines.
-- Short slide and fade motion that respects reduced motion.
+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
 
@@ -118,26 +87,18 @@ The page title and URL go along on their own. Nothing else about the page does,
 
 ## Letting the agent act on the app
 
-The agent reads and changes data through the app's own MCP, as the visitor who is chatting. Their groups and each action's `permissions` apply. The actions it may use are the ones listed in `softrMcpMiddleware`. With no MCP wired, the agent can only talk. Load [mcp/SKILL.md](../mcp/SKILL.md) to wire it.
+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.** Pages and server functions are skipped, so the action's `permissions` are its only guard: a read returns every row those groups may see, an update or delete takes any id.
+**The agent calls a listed action directly, with any input.** It skips pages and server functions, so the action's `permissions` are its only guard: a read returns every row those groups may see, an update or delete takes any id.
 
-- List the app's existing actions. Don't define copies for the agent.
-- Narrow `permissions` to who may really run it. When roles differ, split the action: each writes only that role's fields, with `customGroups` for that role.
+- Narrow `permissions` to who may really run it. When roles differ, split the action: each writes only that role's fields, with `customGroups` for that role. 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 action that is only safe for a visitor's own records. Nothing scopes it to them.
-- Tell the builder which actions the agent can use and who may run each one.
 
 ## Failure modes
 
 **Building a chat without the hook.** Calling the agents service from the browser fails: only the app's server can sign the request in as the visitor. Use `useAgentChat`.
 
-**Rendering only `text` blocks.** A tool waiting for approval never shows, and the agent waits forever. Render every block type.
-
-**The hook inside a panel that unmounts when it closes.** Closing it stops a reply that is still coming. Call `useAgentChat` in the component that owns the open state, such as `AppLayout` in `src/routes/_app.tsx`, and pass `chat` into the panel. Keep the selected agent there too, or closing the panel resets it.
-
-**One action for every role.** An update any signed-in visitor may run, writing the status, lets an employee have the agent approve their own vacation request. Give approve its own action, limited to managers.
-
-**An agent id written by hand.** The chat fails on the first message, and an agent hidden from the visitor still shows. Take the id from `listAgents`.
+**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
 

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.90-alpha.2
+  library_version: 0.0.90-alpha.3
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.90-alpha.2
+  library_version: 0.0.90-alpha.3
 ---
 
 **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.90-alpha.2
+  library_version: 0.0.90-alpha.3
 ---
 
 **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.90-alpha.2
+  library_version: 0.0.90-alpha.3
 ---
 
 **Boundary.** `workflow` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineWorkflow` and every type come from `@softr/sdk` and can be imported anywhere.