@softr/sdk 0.0.87-alpha.0 → 0.0.87-alpha.2

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

@@ -1,103 +0,0 @@
----
-name: agent-chat
-description: >-
-  Let visitors chat with one of the app's Softr agents: useAgentChat(agentId,
-  { record }) from @softr/sdk returns the messages, the reply as it streams,
-  and send, stop, approve and reject, with no UI. 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.
-metadata:
-  type: sub-skill
-  library: softr-sdk
-  library_version: 0.0.86
----
-
-**Boundary.** `useAgentChat` lives on `@softr/sdk` and runs in a component. It needs no 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.
-
-## Setup
-
-```ts
-import { useAgentChat } from '@softr/sdk'
-```
-
-The agent id is a string from Studio. Ask the builder for it if you don't have it, and write it as a literal. Never guess or invent one.
-
-## Core pattern
-
-```tsx
-function AgentPanel({ ticket }: { ticket: Ticket | null }) {
-  const chat = useAgentChat('a1b2c3d4-...', {
-    record: ticket && { id: ticket.id, fields: { Title: ticket.title, Status: ticket.status } },
-  })
-  const [draft, setDraft] = useState('')
-
-  return (
-    <>
-      {chat.messages.map((message) => (
-        <Message key={message.id} message={message} onApprove={chat.approve} onReject={chat.reject} />
-      ))}
-      {chat.error && <p role="alert">{chat.error.message}</p>}
-      <form onSubmit={(e) => { e.preventDefault(); chat.send(draft); setDraft('') }}>
-        <Textarea value={draft} onChange={(e) => setDraft(e.target.value)} />
-        {chat.status === 'idle'
-          ? <Button type="submit">Send</Button>
-          : <Button type="button" onClick={chat.stop}>Stop</Button>}
-      </form>
-    </>
-  )
-}
-```
-
-## What the hook returns
-
-- `messages`: the whole chat, oldest first. While the agent answers, its reply is the last message and grows as it streams.
-- `status`: `thinking` until the first part of the reply arrives, `replying` until it ends, then `idle`. Show a typing hint while it's `thinking`.
-- `error`: why the last request failed, or `null`.
-- `send(text)`, `stop()`, `newChat()`.
-- `listChats()` resolves to the visitor's past chats, `{ id, title }[]`. `openChat(id)` loads one. `chatId` is the open one, `null` for a new chat.
-- `approve(toolCallId, scope?)` and `reject(toolCallId)` answer a tool waiting for approval. `scope` is `ONCE` (default), `SESSION` for the rest of this chat, or `USER` for always.
-
-## Rendering a message
-
-Each message has `role` (`user` or `assistant`) and `blocks`, in the order the agent produced them. Render every block type:
-
-| Block | Show it as |
-| --- | --- |
-| `text` | Markdown text |
-| `tool` | One line: the tool `name` and its `status`. Collapse finished ones. |
-| `todo` | A checklist of the agent's plan. It updates in place. |
-| `question` | The questions with their options. A click on an option sends its label with `send`. |
-| `error` | An error line inside the reply |
-
-A `tool` with status `awaiting-approval` blocks the agent until the visitor answers. Show Approve and Reject buttons on it. The agent continues on its own after an approval.
-
-A `tool` with status `awaiting-connection` needs the visitor to connect the `integration` first. Code apps can't do that yet. Say which integration the agent needs, and that the builder has to connect it for this agent in Studio.
-
-## Context
-
-`record` is the one record the visitor is looking at, so they can say "close this one". Pass it where a page shows one record, and `null` elsewhere. Use readable field names as keys. The agent reads them as they are.
-
-The page title goes along on its own. Nothing else about the page does, so don't try to send whole lists.
-
-## Letting the agent act on the app
-
-The agent reads and changes data through the app's own MCP, as the visitor who is chatting. 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.
-
-## 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.
-
-**An invented agent id.** The chat fails on the first message. Use the id from Studio.
-
-**Expecting the agent to change data with no MCP wired.** It answers but can't act. List the actions it needs in `softrMcpMiddleware`.
-
-## References
-
-- [mcp/SKILL.md](../mcp/SKILL.md): the actions the agent may call
-- [current-user/SKILL.md](../current-user/SKILL.md): showing the chat to signed-in visitors only