sygnal 6.1.1 → 6.3.0

package/dist/guide/adapters.md

@@ -24,7 +24,8 @@ npm install react react-dom
 The React component here is a small one of our own, written with React's `createElement` (the JSX on these pages is Sygnal's); a component from npm is wrapped the same way:
 
 ```js live-file=./Rating.js
-// Rating.js: a React component
+// Rating.js
+// a React component
 import { createElement as h } from 'react'
 
 export function Rating({ value, max, onChange }) {

package/dist/guide/agent.md

@@ -69,6 +69,7 @@ TodoApp.agent = {
 | `label(state)` | A [Collection item](#collection-items)'s label for the model |
 | `untrusted` | `read` returns text users typed (see [Security](#security)). Unset, Sygnal infers it from the strings in the projection |
 | `actions` | The only actions agents may run, by action name |
+| `queries` | Read-only tools that take an input: data too large for `read`, or answers computed from the state ([Queries](#queries)) |
 
 Each entry of `actions`:
 
@@ -79,6 +80,8 @@ Each entry of `actions`:
 | `consequential` | Ask the user before running it |
 | `when(state)` | The tool is offered only while this is true |
 | `idempotent` | A call that changes nothing is a success (`{ ok: true, unchanged: true }`), not an error |
+| `until` | The call answers once the action's result is in state: a resource name, or a function of the state ([Waiting for a result](#waiting-for-a-result-until)) |
+| `timeout` | With `until`: how long to wait, in ms (default 10,000) |
 
 ### Input schemas
 
@@ -109,7 +112,7 @@ In TypeScript, on a component typed with its actions ([TypeScript](https://sygna
 
 ## What agents see
 
-**Tools.** One per listed action, plus `<name>_read` when the declaration has a `read`. The todo app above offers:
+**Tools.** One per listed action and [query](#queries), plus `<name>_read` when the declaration has a `read`. The todo app above offers:
 
 | Tool | Input | Hints |
 |---|---|---|
@@ -131,7 +134,7 @@ Every call, from any kind of agent, goes through the same steps:
 2. **Availability.** A tool whose `when` is false now gets `{ ok: false, error: 'todos_clear_done is not available now' }`.
 3. **Confirmation.** A `consequential` action waits for the user (each consumer asks in its own way). A declined call is `{ ok: false, error: 'the user declined' }`. The target and `when` are checked again after the answer.
 4. **Dispatch.** The action runs with `cause: 'agent'`, through the same queue, reducers and render as a click. It shows in `t.actions`, the DevTools action log and the dev MCP endpoint's `recent_actions` with that cause.
-5. **The result**, after the render: `{ ok: true, state }`, where `state` is the nearest `read` projection (the component's, or for an item, its own or its list's).
+5. **The result**, after the render: `{ ok: true, state }`, where `state` is the nearest `read` projection (the component's, or for an item, its own or its list's). An action with [`until`](#waiting-for-a-result-until) answers later, once its result is in state.
 
 **No-op detection.** A call succeeds when one of the action's handlers had an effect: a reducer changed the state, a driver sink got a value, or an `EFFECT` ran. A call that changed nothing is reported as a failure, not a false success. Here, `SET_FILTER` to the filter already set, on an action without `idempotent`:
 
@@ -158,6 +161,107 @@ A refusal is reported even on an `idempotent` action.
 
 **One at a time.** Calls run serially, in the order the model made them, so each one sees the previous one's result. A model that sends three calls at once gets three results computed in sequence.
 
+## Waiting for a result: `until`
+
+Some actions only start something: a search sets the query, and a [`resources`](./resources.md) entry fetches the results. Right after the action, the results aren't there yet, so the call would answer with `status: 'loading'`, and the model would have to guess or ask again. With `until`, the call answers once the result is in state:
+
+```jsx
+// Shop.jsx
+import { z } from 'zod'
+
+export default function Shop({ state }) {
+  const { status, data } = state.search
+  return (
+    <section>
+      {status === 'loading' && <p>Searching…</p>}
+      <ul className="results">{(data ?? []).map((p) => <li key={p.id}>{p.name}</li>)}</ul>
+    </section>
+  )
+}
+
+Shop.initialState = { query: '' }
+
+Shop.resources = { search: (state) => state.query && { url: '/api/search', query: { q: state.query } } }
+
+Shop.model = { SEARCH: (state, query) => ({ ...state, query }) }
+
+Shop.agent = {
+  name: 'shop',
+  description: 'The product search the user sees',
+  read: (state) => ({ query: state.query, status: state.search.status, results: (state.search.data ?? []).map(({ id, name }) => ({ id, name })) }),
+  actions: {
+    SEARCH: { description: 'Search the catalog; the results show on the page', input: z.string().min(1), until: 'search' },
+  },
+}
+```
+
+`shop_search({ value: 'red shoes' })` now answers with the results the user sees, `{ ok: true, state: { query: 'red shoes', status: 'success', results: [...] } }`, or with `status: 'error'` when the request failed.
+
+- **`until: 'search'`** names one of the component's resources. The call answers once that resource is neither loading nor refreshing, so a [`keepPrevious`](./resources.md) request or a refetch, which keep the status and set `refreshing`, are waited for too. A name the component's `resources` doesn't have is [SYG248](https://sygnal.js.org/reference/errors/#syg248): the call answers at once.
+- **`until: (state) => boolean`** is for a result a reply action writes (a driver request with an `ok` action). The action's own reducer must mark it pending, `status: 'loading'`, so the test is false right after the action: `until: (state) => state.status !== 'loading'`. A throwing `until` ends the wait ([SYG241](https://sygnal.js.org/reference/errors/#syg241)).
+- **The test runs after the action's render and after every render that changed something.** A result already in state answers at once.
+- **No result within `timeout`** (default 10 s): `{ ok: true, pending: true, note, state }`. The note tells the model the result will be in the app state later, where the `chat` behavior's next request shows it.
+- **Calls run one at a time**, so a waiting call delays the model's next one. The [`chat` behavior](#an-in-app-assistant-chat) ends the wait when the user presses Stop or sends a new message (the call answers `pending`), and `agentTools()` has `cancel()` for other consumers.
+- An item that removes itself while its call waits answers `{ ok: true, removed: true, state }`.
+
+The side effect stays where it was: the request goes through `resources` or a driver, and a test answers it with the fetch fake, `await t.respond('HTTP', [...])`. `t.callTool()` waits for it like any agent.
+
+## Queries
+
+`read` goes to the model whole, with every request. That suits a summary, not a table of 5,000 invoices: sending them all costs tokens on every turn, and a model reads a long list badly anyway. A query is a read-only tool that takes an input and answers from the state: the model asks for the overdue invoices of one customer and gets those.
+
+```jsx
+// Invoices.jsx
+import { z } from 'zod'
+
+export default function Invoices({ state }) {
+  return <p className="count">{state.invoices.length} invoices</p>
+}
+
+Invoices.initialState = { invoices: [] }
+
+const Filter = z.object({
+  customer: z.string().optional().describe('The customer name'),
+  overdue: z.boolean().optional(),
+})
+
+Invoices.agent = {
+  name: 'invoices',
+  description: 'The invoices',
+  untrusted: true,
+  read: (state) => ({ count: state.invoices.length }),   // the summary, on every request
+  queries: {
+    // invoices_find({ customer?, overdue? })
+    find: {
+      description: 'The invoices matching a filter, at most 50',
+      input: Filter,
+      run: (state, { customer, overdue }) => state.invoices
+        .filter((i) => (customer === undefined || i.customer === customer) && (overdue === undefined || i.overdue === overdue))
+        .slice(0, 50),
+    },
+    // invoices_total()
+    total: { description: 'The sum of all invoices', run: (state) => state.invoices.reduce((sum, i) => sum + i.total, 0) },
+  },
+}
+```
+
+| Key | What it does |
+|---|---|
+| `description` | What the query returns, for the model |
+| `input` | The schema of its input, as for an action ([Input schemas](#input-schemas)). Without one the query takes no arguments |
+| `when(state)` | The tool is offered only while this is true |
+| `run(state, input)` | The result: a pure, synchronous function of the component's state now and the validated input |
+
+- **A query is a tool named `<name>_<query>`**, marked read-only. It is offered next to the actions, to every kind of agent (the command bar, which picks one action, leaves read-only tools out).
+- **A call validates the input and checks `when`**, as for an action, then returns `{ ok: true, result }` with what `run` returned. Nothing is dispatched, nothing is confirmed, and nothing renders: a query can't change the app.
+- **It must be synchronous.** A `run` that returns a promise (an `async` function, a `fetch`) fails the call and is [SYG246](https://sygnal.js.org/reference/errors/#syg246), as is a query without `run`. Data that has to be loaded belongs to an action: its model entry asks for it (a [`resources`](./resources.md) entry or a driver request), and [`until`](#waiting-for-a-result-until) makes the call answer with the result.
+- **A throw** fails the call with its message and is [SYG241](https://sygnal.js.org/reference/errors/#syg241).
+- **Actions and queries share the tool names.** A query whose snake-case name is an action's (`find` next to `FIND`) is [SYG247](https://sygnal.js.org/reference/errors/#syg247), and only the action is offered.
+- **On a Collection item component**, a query gets the same key parameter as the item's actions (`contact_notes({ id, word })`), and answers from that item's state.
+- **Results are data.** When they hold text users typed, set `untrusted: true` on the declaration: WebMCP then marks the queries with `untrustedContentHint` too ([Security](#security)). Keep results small (filter, then cut): WebMCP cuts a result over 1,500 characters of JSON ([SYG242](https://sygnal.js.org/reference/errors/#syg242)).
+
+In TypeScript, `run`'s `state` is typed from the component; type the input yourself, `run: (state, input: z.infer<typeof Filter>) => …`, since it isn't inferred from `input`.
+
 ## Collection items
 
 An item component's actions don't become one tool per item. They become one tool per action, with a parameter that names the item: an enum of the live keys (the items' `id`s), routed to the item with that key.
@@ -259,7 +363,7 @@ export default {
 }
 ```
 
-```jsx live live-height=380
+```jsx live live-height=380 title="TodoApp.jsx"
 import { z } from 'zod'
 import { Collection } from 'sygnal'
 import { chat, messageText } from 'sygnal/ai'
@@ -361,10 +465,12 @@ In production the provider key belongs on your server: `makeChatDriver({ transpo
 | `prompt` | | The prompt field (its input sets `prompt`) |
 | `stop`, `approve`, `deny`, `regenerate` | | Buttons: their clicks dispatch `STOP`, `APPROVE`, `DENY`, `REGENERATE` |
 | `instructions` | | System instructions: your app's own text |
-| `agent` | the host's and its shown descendants' | Whose declarations become tools: `false` for none, `[Comp, ...]` for only these (inside the host) |
+| `agent` | the host's and its shown descendants' | Whose declarations become tools: `false` for none (a plain chat, [AI Chat](./ai-chat.md#the-same-chat-with-the-chat-behavior)), `[Comp, ...]` for only these (inside the host) |
 | `maxSteps` | `8` | The most requests per turn; tool calls in a reply past it are not run |
 | `sink` | `'LLM'` | The chat driver's name |
-| `model`, `transportOptions` | | A model id, and extra request keys for the transport |
+| `model`, `transportOptions` | | A model id, or a function of the host's state that returns one, read per request (`(state) => state.chatModel`, for a model picker); extra request keys for the transport |
+| `clientTools` | | Tools the app answers itself with `TOOL_OUTPUT` ([client tools](./ai-cards.md#client-tools)) |
+| `ask` | | `{ catalog, backend?, instructions?, direct? }`: the `ask_user` tool, which asks the user with a composed card ([Cards in a Chat](./ai-cards.md)) |
 
 The slice, `state.assistant` for `uses = { assistant: chat(...) }`:
 
@@ -377,7 +483,7 @@ The slice, `state.assistant` for `uses = { assistant: chat(...) }`:
 | `pending` | A consequential call waiting for `APPROVE` / `DENY`: `{ tool, component, action, description, input, key?, label? }`, else `null` |
 | `error` | The last failure's message, else `null` |
 
-Actions, as `'assistant.X'`: `SEND` (the form's submit; or dispatch it with the text as data), `STOP` (aborts the reply, keeps the text so far, declines a waiting call), `REGENERATE` (sends the last user message again), `APPROVE`, `DENY`, and `DONE` (the turn is over: `{ message, text, finishReason, usage, steps }`; a host entry `'assistant.DONE'` runs after the behavior's).
+Actions, as `'assistant.X'`: `SEND` (the form's submit; or dispatch it with the text as data), `STOP` (aborts the reply, keeps the text so far, declines a waiting call, and answers a call waiting on [`until`](#waiting-for-a-result-until) as pending), `REGENERATE` (sends the last user message again), `APPROVE`, `DENY`, and `DONE` (the turn is over: `{ message, text, finishReason, usage, steps }`; a host entry `'assistant.DONE'` runs after the behavior's).
 
 **The markup belongs to the host's view.** A behavior listens to selectors in its host's own view, like every intent ([SYG104](https://sygnal.js.org/reference/errors/#syg104)): elements rendered inside a child component are out of its reach. So the panel is a plain function the host's view calls, `{assistantPanel(state.assistant)}`, not a `<AssistantPanel />` component. A function can still live in its own file and be shared.
 
@@ -385,6 +491,8 @@ Actions, as `'assistant.X'`: `SEND` (the form's submit; or dispatch it with the
 
 **Approvals.** A consequential call sets `pending` and waits. Render `pending.description` and `pending.label` with the approve and deny buttons. `APPROVE` runs it; `DENY` tells the model the user declined, and the model continues from there. `STOP` and removing the component decline too.
 
+**Composing the page.** An assistant can arrange a [composed page](./ai-compose.md) as an action: `actions: { ...compose.action('page') }` gives it the tool `<name>_page_compose({ prompt, fresh? })`, whose result waits for the composition, and `read: (state) => ({ page: compose.summary(state.page) })` shows it the page ([Compose from an agent](./ai-compose.md#compose-from-an-agent)).
+
 ## A command bar: `commandBar`
 
 For "do one thing in this app" from one line of text, a chat model's conversation loop is more than you need. `commandBar` asks a **decision model** one question per command: which of the `agent` actions it means, and which Collection item. The answer comes with a confidence, and the action runs through the [call rules](#the-call-rules) only when the model is sure enough. In the research behind this feature, a local decision model picked the right action and target for 8 of 8 commands, in about 570 ms each. Decision models, `decide()` and confidence are in [AI Decisions](./ai-decisions.md).
@@ -414,7 +522,7 @@ export default {
 }
 ```
 
-```jsx live live-height=300
+```jsx live live-height=300 title="Commands.jsx"
 import { z } from 'zod'
 import { Collection } from 'sygnal'
 import { commandBar } from 'sygnal/ai'
@@ -581,6 +689,8 @@ it('is operable by agents', async () => {
 ```
 
 - `t.tools()` lists the offered tools, plus any declared tool that can't be offered (SYG240) with its `error`.
+- A [query](#queries) is called the same way: `await t.callTool('invoices_find', { customer: 'Acme' })` resolves with `{ ok: true, result }`.
+- A call to an action with [`until`](#waiting-for-a-result-until) resolves once its result is in state: start it, answer the request (`await t.respond('HTTP', data)`), then await it. Under `vi.useFakeTimers()`, advancing past `timeout` gives `{ ok: true, pending: true }`.
 - `t.callTool(name, args, { confirm })` resolves with the [call result](#the-call-rules) after the render. A consequential tool without `confirm` throws, so a test can't approve one by accident.
 - `t.agentContext()` returns what the model sees: one entry per declaration with a `read`, keyed by the declaration's `name`, holding what its `read` returned. That is why the example above reads `todos.todos`: the declaration is named `todos`, and its `read` returns `{ todos, filter }`. An item declaration's entry is an array with one projection per live item, each with its `id` (`{ todo: [{ id: 1, done: false }] }` for `read: (s) => ({ done: s.done })`).
 
@@ -589,6 +699,8 @@ To test the assistant itself, drive the `LLM` fake: `t.stream('LLM', [{ toolCall
 ## Related
 
 - [AI Chat](./ai-chat.md): the chat driver under the `chat` behavior, transports, and the raw tool loop
+- [Cards in a Chat](./ai-cards.md): client tools (`clientTools`, `TOOL_OUTPUT`) and `chat({ ask })`
+- [Composing UI with a Model](./ai-compose.md#compose-from-an-agent): `compose.action()`, the page as an agent action
 - [AI Decisions](./ai-decisions.md): decision models, `decide()` and confidence, which the command bar uses
 - [WebMCP](./webmcp.md): the same tools for the browser's agent (experimental)
 - [MCP Apps](./mcp-apps.md): your app inside Claude, ChatGPT or VS Code, with its tools

package/dist/guide/ai-cards.md

@@ -0,0 +1,319 @@
+<!-- Generated from docs/src/content/docs/guide by scripts/copy-guides.mjs; online: https://sygnal.js.org/guide/ -->
+# Cards in a Chat
+
+Some answers are easier to click than to type: one of a few options, a plan from the app's list, a short form, "does this look right?". With `chat({ ask })` the assistant asks for them with a **card**. The model calls the `ask_user` tool and says in one sentence what it needs, the app composes a card from **parts it prepared** (the same [catalog](./ai-compose.md#the-catalog) as a composed page), and the user's answer goes back to the model as the tool's result.
+
+As with a composed page, the model only chooses: every button and label on the card is the app's own component, and the answer is a value your component sends.
+
+## A plan assistant
+
+The demo server below stands in for the model. It matches words and replies in the Open Responses format a real model streams, through the page's `LLM` driver:
+
+- the chat's first request: "Let me ask.", then an `ask_user` call;
+- a card's request (a structured-output request: it has `text.format`): the layout JSON a chat model writes, from the call's `need`;
+- a request after a card's answer (the last input is the tool's output, `{ part, answer }`): the next question, or the end.
+
+```js live-server
+import { encodeOpenResponses } from 'sygnal/ai'
+
+const words = (text) => text.match(/\S+\s*/g)
+const say = (chunks) => ({ sse: encodeOpenResponses(chunks), delayMs: 300, chunkMs: 40 })
+const ask = (need) => ({ toolCall: { name: 'ask_user', input: { need } } })
+
+// the card for a need: the layout JSON compose.llm() asks for (a real model reads the catalog)
+function card(need) {
+  const children = /plan/i.test(need)
+    ? [{ part: 'plans' }]
+    : [{ part: 'choice', params: { question: need, options: ['Just me', '2 to 10', 'More than 10'] } }]
+  return JSON.stringify({ asked_for: children.map((c) => c.part), children }).match(/[\s\S]{1,16}/g)
+}
+
+export default {
+  'POST /v1/responses': ({ json }) => {
+    const last = json.input.at(-1)
+    // compose.llm() building a card: its message is the call's `need`
+    if (json.text?.format) return say(card(String(last.content)))
+    // a card was answered (or closed): its output is { part, answer } (or { error })
+    if (last.type === 'function_call_output') {
+      const out = JSON.parse(last.output)
+      if (out.part === 'choice' && out.answer === 'Just me') return say([...words('Then Free is enough. '), ask('Pick the plan you want')])
+      if (out.part === 'choice') return say([...words(`For ${out.answer.toLowerCase()} people, Team or Business. `), ask('Pick the plan you want')])
+      if (out.part === 'plans') return say(words(`Done: you are on the ${out.answer} plan.`))
+      return say(words('No card then. Tell me how many people will use it.'))
+    }
+    return say(['Let me ask. ', ask('How many people will use it?')])
+  },
+}
+```
+
+The catalog: parts with `result: true` answer a card. `choice` has free-text params (the model writes the question and the options); `plans` is the app's own list.
+
+```jsx live-file=./cards.jsx title="cards.jsx"
+import { defineCatalog, compose } from 'sygnal/ai'
+
+export const PLANS = [
+  { id: 'free', name: 'Free', price: '$0' },
+  { id: 'team', name: 'Team', price: '$12' },
+  { id: 'business', name: 'Business', price: '$30' },
+]
+
+export function Choice({ question, options = [], answer, frozen }) {
+  return (
+    <div className="choice">
+      <p>{question}</p>
+      {options.map((o) => <button type="button" className={o === answer ? 'option picked' : 'option'} data={{ value: o }} disabled={frozen}>{o}</button>)}
+    </div>
+  )
+}
+Choice.intent = ({ DOM }) => ({ PICK: DOM.click('.option').data('value') })
+Choice.model = { PICK: { PARENT: (state, value, next, props) => compose.answer(props, value) } }
+
+// no `state` in the catalog entry: the part sees the host's state, as any child does
+export function PlanPicker({ state, answer, frozen }) {
+  return (
+    <ul className="plans">
+      {state.plans.map((p) => (
+        <li><button type="button" className={p.id === answer ? 'plan picked' : 'plan'} data={{ id: p.id }} disabled={frozen}>{p.name} ({p.price})</button></li>
+      ))}
+    </ul>
+  )
+}
+PlanPicker.intent = ({ DOM }) => ({ PICK: DOM.click('.plan').data('id') })
+PlanPicker.model = { PICK: { PARENT: (state, id, next, props) => compose.answer(props, id) } }
+
+export const catalog = defineCatalog({
+  parts: {
+    choice: {
+      component: Choice, result: true,
+      description: 'A question with 2 to 5 short options; the user picks one',
+      params: {
+        question: { type: 'text', maxLength: 120, required: true },
+        options: { type: 'list', items: { maxLength: 40 }, min: 2, max: 5, required: true },
+      },
+    },
+    plans: { component: PlanPicker, result: true, description: 'The pricing plans to pick from (Free, Team, Business)' },
+  },
+})
+```
+
+```css live
+.plan-chat { display: grid; gap: 0.5rem; }
+.plan-chat ol { list-style: none; margin: 0; padding: 0; display: grid; gap: 0.4rem; }
+.plan-chat .ask-card { border: 1px solid #8884; border-radius: 6px; padding: 0.4rem 0.6rem; }
+.plan-chat .ask-card p { margin: 0 0 0.3rem; }
+.plan-chat .ask-card ul { list-style: none; margin: 0; padding: 0; display: flex; gap: 0.4rem; }
+.plan-chat .ask-card fieldset { border: 0; margin: 0; padding: 0; }
+.plan-chat .option, .plan-chat .plan { margin-right: 0.3rem; }
+.plan-chat .picked { font-weight: bold; }
+.plan-chat .card-status { font-size: 0.8rem; opacity: 0.7; }
+.plan-chat .ask { display: flex; gap: 0.5rem; }
+.plan-chat .ask input { flex: 1; }
+```
+
+The demo asks on load. Answer the card: the answer goes back to the model, which asks again with a second card, built from the app's plans.
+
+```jsx live live-height=380 title="PlanChat.jsx"
+import { chat, askCard } from 'sygnal/ai'
+import { catalog, PLANS } from './cards.jsx'
+
+// a message part: text, or an ask_user call with its card
+function part(p, state) {
+  if (p.type === 'text') return <p>{p.text}</p>
+  if (p.type !== 'tool-ask_user') return null
+  return (
+    <section className="ask-card">
+      {askCard(catalog, state, p) ?? <p>Composing a card…</p>}
+      <span className="card-status">{p.ui?.status}</span>
+    </section>
+  )
+}
+
+function PlanChat({ state }) {
+  const a = state.assistant
+  const busy = a.status === 'submitted' || a.status === 'streaming'
+  return (
+    <div className="plan-chat">
+      <ol aria-live="polite">
+        {a.messages.map((m) => <li className={m.role}><b>{m.role}:</b> {m.parts.map((p) => part(p, state))}</li>)}
+        {a.draft && <li className="assistant"><b>assistant:</b> {a.draft}</li>}
+      </ol>
+      <form className="ask">
+        <input className="prompt" aria-label="Message" value={a.prompt} />
+        <button type="submit" disabled={busy}>Send</button>
+        <button type="button" className="stop" hidden={!busy}>Stop</button>
+      </form>
+    </div>
+  )
+}
+
+PlanChat.initialState = { plans: PLANS }
+
+PlanChat.uses = {
+  assistant: chat({
+    form: '.ask', prompt: '.prompt', stop: '.stop',
+    instructions: 'Help the user choose a plan. Ask with ask_user when they need to choose something.',
+    ask: { catalog },
+  }),
+}
+
+PlanChat.model = {
+  // the demo asks on load only to have something to show
+  BOOTSTRAP: { EFFECT: (state, data, next) => next('assistant.SEND', 'Which plan should I take?') },
+}
+
+export default PlanChat
+```
+
+## How a card works
+
+`chat({ ask: { catalog, backend?, instructions?, direct? } })` adds the tool `ask_user({ need })` to the chat's requests. Its description tells the model to say in one sentence what it needs, and to prefer a card to a question in text when the answer is one of a few options or structured. `instructions` adds your own guidance on when and how to ask.
+
+1. **The model calls `ask_user`** with its `need`. The call stays open (`input-available`), and its card starts composing.
+2. **The backend composes the card** from the `need` and the app state, never the conversation: `compose.llm()` by default, on the chat's own sink, or `compose.decisions()` ([below](#two-backends)). Cards compose one at a time, each under its own request key (`assistant.ask:<call id>`), so a card's request never aborts the chat's.
+3. **The host renders it** with `askCard(catalog, state, part)` wherever it renders the message's `tool-ask_user` part. It is null while there is no card yet.
+4. **The user answers** in a result part, which sends `compose.answer(props, value)` to `PARENT`. The call closes with the output `{ part, answer }` (the part's id, the value), and once no call is open the chat sends the next request, so the model continues from the answer.
+
+The card lives on the tool part, as `part.ui`:
+
+| Field | |
+|---|---|
+| `status` | `composing` (queued, or its request is out), `open` (answerable), `answered`, `failed`, `cancelled` |
+| `layout` | The card: a layout, as on a composed page |
+| `answer` | `{ node, part, value }` once answered, else `null` |
+| `local`, `ui` | The card's `local` parts' state and container state, per node key |
+
+- **Statuses of the chat.** While a card composes, the chat's `status` is `'streaming'`. Once every open card is composed and only the user's answers are outstanding, it is `'ready'`, and the turn is not over (no `DONE`). Several `ask_user` calls in one reply give several cards; the next request goes when all are answered.
+- **A failed card** (its request fails, or the reply is not a valid card) closes the call with the error "could not show a card: …; ask in text instead", and the turn goes on: the model can ask in text.
+- **STOP** aborts a card that is composing and cancels the open ones: their calls close as "not answered: stopped by the user", and nothing is sent. **SEND** of a new message cancels them too ("not answered: the user sent a new message"), so the model sees its question went unanswered. A cancelled or answered card renders frozen.
+
+### Result parts
+
+A part with `result: true` answers the card. It sends its answer to `PARENT` with `compose.answer(props, value)`: `props` carries the card's `scope` and the part's `node`, so the answer reaches the right call. Any value works: a string, an id, a form's values.
+
+- `askCard` renders each card in its own scope, so two cards with the same part are two instances, with their own `local` state (a small form keeps what the user typed, per card).
+- The answered part gets the prop `answer` (its value, to mark the pick), and every part of a card that isn't open gets `frozen`. The card is wrapped in a disabled `<fieldset>` too.
+- The host hears result parts as well: `CHILD.select(PlanPicker)` in the host's intent gets `{ scope, node, value }`, to keep the pick in app state.
+- A catalog for `ask` needs at least one result part ([SYG686](https://sygnal.js.org/reference/errors/#syg686)), and a result part rendered outside a card can't answer anything ([SYG160](https://sygnal.js.org/reference/errors/#syg160)).
+
+## Two backends
+
+| | `compose.llm()` (the default) | `compose.decisions({ model })` |
+|---|---|---|
+| Who composes the card | The chat model, in a second, structured-output request | A decision model, from the parts' descriptions |
+| Sink | The chat's (`LLM`) | `HTTP` (`/api/decide` by default) |
+| Parts it can use | All, free-text params too (a question and its options written for this need) | Prepared parts only: a part with required free text is LLM-only |
+
+```js
+chat({ ask: { catalog, backend: compose.decisions({ model: 'jev-latest' }) } })
+```
+
+**Why two steps.** The chat model only says what it needs (`need`), and a separate request builds the card. Writing the card as the tool's arguments in one step needs a provider that enforces tool schemas: on Ollama, none of the measured calls with the layout as tool arguments was a valid card as emitted, against 5 of 5 with the two-step form.
+
+**`direct: true`** is that one-step form, for providers that do enforce tool schemas: the `ask_user` input schema is the catalog's layout schema, and the card opens as soon as the call arrives, with no compose round trip. An input that is not a card closes the call with the error, so the model can try again. It is LLM-only.
+
+**What the backend explains** stays with the card as `part.ui.decisions`, as a [composed page](./ai-compose.md) keeps it in its slice: `compose.llm()`'s plan (`asked_for`) and repairs, or `compose.decisions()`'s answers per step by question name (`use_<part>`, `rec_<part>__<n>`, `first_<a>_vs_<b>`, ...). It is persisted with the card, for an explain panel.
+
+**Switching models.** `model` may be a function of the host's state, read per request: `chat({ model: (state) => state.chatModel, ask: { catalog } })` follows the app's model picker with one chat behavior, and the default card backend follows it too (`compose.llm({ model: (state) => state.chatModel })` for an explicit one). The card backend itself is fixed when `chat()` is called, since it decides the sink the cards go to: an app that lets the user pick it makes one host component per backend.
+
+**Call `chat()` before `run()`.** The first `chat()` call links the sygnal/ai behaviors to the apps started after it (and to the page's first running app). A host component defined in a module the entry imports is in time; one created only later, in a second app, runs without tools ([SYG442](https://sygnal.js.org/reference/errors/#syg442)). An app that makes host components on demand calls `chat()` once at load.
+
+## Client tools
+
+`ask_user` is one case of a **client tool**: a tool the app answers itself, often with the user's help, instead of an `agent` action that runs on its own. `clientTools` declares your own:
+
+```jsx
+import { z } from 'zod'
+import { chat, openToolCalls } from 'sygnal/ai'
+
+function confirmations(a) {
+  return openToolCalls(a).filter((p) => p.type === 'tool-confirm').map((p) => (
+    <p className="confirm">
+      {p.input.question}
+      <button type="button" className="yes" data={{ id: p.toolCallId }}>Yes</button>
+      <button type="button" className="no" data={{ id: p.toolCallId }}>No</button>
+    </p>
+  ))
+}
+
+function Booking({ state }) {
+  const a = state.assistant
+  return (
+    <main>
+      {confirmations(a)}
+      <form className="ask"><input className="prompt" aria-label="Message" value={a.prompt} /></form>
+    </main>
+  )
+}
+
+Booking.uses = {
+  assistant: chat({
+    form: '.ask', prompt: '.prompt',
+    clientTools: {
+      confirm: { description: 'Ask the user a yes / no question', inputSchema: z.object({ question: z.string().min(1) }) },
+    },
+  }),
+}
+
+Booking.intent = ({ DOM }) => ({ YES: DOM.click('.yes').data('id'), NO: DOM.click('.no').data('id') })
+
+Booking.model = {
+  YES: { EFFECT: (state, id, next) => next('assistant.TOOL_OUTPUT', { toolCallId: id, output: { confirmed: true } }) },
+  NO: { EFFECT: (state, id, next) => next('assistant.TOOL_OUTPUT', { toolCallId: id, output: { confirmed: false } }) },
+}
+```
+
+- A client tool is `{ description, inputSchema }`: a JSON Schema, or a Standard Schema (zod, valibot) with a JSON Schema form. A Standard Schema input is validated first; an invalid one closes the call with the issues, so the model can repair it.
+- Its calls stay open until `'assistant.TOOL_OUTPUT'` answers them: `{ toolCallId, output }`, or `{ toolCallId, errorText }` for an error. A TOOL_OUTPUT for a call that isn't open does nothing ([SYG685](https://sygnal.js.org/reference/errors/#syg685)).
+- `openToolCalls(state.assistant)` lists the calls of the last message that wait for an answer (each a `tool-<name>` part with its `input`).
+- A host entry `'assistant.TOOL_CALL'` runs once when each call opens, with `{ id, name, input }` (the input after validation).
+- STOP and SEND close open calls as they close cards. A client tool with the name of an `agent` tool replaces it ([SYG684](https://sygnal.js.org/reference/errors/#syg684)).
+
+These are the AI SDK's `addToolOutput` and `onToolCall`, on the `chat` behavior.
+
+## Persistence
+
+Cards live on the messages (`part.ui`), so [`persist()`](./persistence.md) of the chat slice keeps them: an answered card comes back frozen with its pick, an open card stays answerable, and a card that was composing composes again. A chat saved while a reply streamed comes back `'ready'`, so Send works after a reload.
+
+```js
+import { persist } from 'sygnal'
+
+PlanChat.persist = persist({ key: 'plan-chat', pick: ['assistant'] })
+```
+
+On the wire, the `openResponses()` and `chatCompletions()` transports send only a call's input and output, never `ui`. `uiMessageStream()` sends the parts as they are: a server route that stores conversations must store `body.messages` as received to keep the cards ([Storing conversations](./ai-chat.md#storing-conversations)).
+
+## Testing
+
+`composeWith(t, catalog, tree)` answers a card's pending composition too, whichever backend it uses. Here `makePlanChat()` returns the demo's component without its `BOOTSTRAP` entry:
+
+```js
+import { it, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { composeWith } from 'sygnal/ai'
+import { catalog } from './cards.jsx'
+import { makePlanChat } from './PlanChat.jsx'
+
+it('asks with a card, and the pick goes back to the model', async () => {
+  const t = renderComponent(makePlanChat())
+  t.simulateAction('assistant.SEND', 'Which plan should I take?')
+  await t.stream('LLM', [{ toolCall: { id: 'c1', name: 'ask_user', input: { need: 'Pick the plan you want' } } }])
+  await composeWith(t, catalog, [{ part: 'plans' }])
+  expect(t.state.assistant.status).toBe('ready')
+
+  t.simulateEvent('.plan[data-id="team"]', 'click')
+  await t.waitForState((s) => s.assistant.status === 'submitted')
+  const call = t.requests('LLM').at(-1).messages.at(-1).parts.find((p) => p.type === 'tool-ask_user')
+  expect(call.output).toEqual({ part: 'plans', answer: 'team' })
+  t.dispose()
+})
+```
+
+- `t.stream('LLM', chunks)` answers the chat's request; a `{ toolCall }` chunk is a call.
+- To test a failed card, fail its request: `t.fail('LLM', new Error('overloaded'), 'assistant.CARD_FAILED')`.
+- A client tool: `t.simulateAction('assistant.TOOL_OUTPUT', { toolCallId: 'c1', output: { confirmed: true } })`.
+
+## Related
+
+- [Composing UI with a Model](./ai-compose.md): catalogs, parts and the two backends
+- [AI Chat](./ai-chat.md): the chat driver, transports and tools
+- [Agents](./agent.md): the `chat` behavior and its call rules