@softr/sdk 0.0.87-alpha.4 → 0.0.87

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

@@ -1,105 +0,0 @@
----
-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, 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.87-alpha.4
----
-
-**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.
-
-## Setup
-
-```ts
-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.
-
-## Core pattern
-
-```tsx
-// agentId comes from listAgents() in the route's loader.
-function AgentPanel({ agentId, ticket }: { agentId: string; ticket: Ticket | null }) {
-  const chat = useAgentChat(agentId, {
-    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 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`.
-
-**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