@terreno/mcp 57.19.2 → 57.21.0

package/src/docs/versioned/57.20.0/explanation/agent-ui-asks.md

@@ -0,0 +1,300 @@
+# Agent UI Asks
+
+An ask lets an agent stop in the middle of a turn, ask the user a typed question inside the chat,
+and continue with the answer as a tool result. This page explains why asks are client-side tool
+calls on the existing chat stream, how one round trip works, how a watch or another small client
+answers them, and how asks and Agent UI Blocks divide the work. Fields, limits, events, and error
+codes are in the [reference](../reference/agent-ui-asks.md).
+
+Asks ship today as five kinds: `choice`, to pick one option or several with an optional answer
+of the user's own (Other), `confirm`, to approve or deny one action, `markdown`, to edit a draft
+the agent wrote and send it back, `form`, to fill in a few typed fields at once, and `files`, to
+send images or documents the agent reads in the same turn. The chat asks
+on `POST /gpt/prompt` and shows asks in `GPTChat`. Watches and other small clients answer
+select-one choices and confirms on two JSON endpoints with the compact surface, and can approve a
+markdown draft or submit a form's defaults as is. A host tool can also require an approval that
+the server enforces, shown as a `confirm`. The sandboxed HTML block and the `callout`, `image`,
+and `details` display blocks follow the
+[implementation plan](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/agent-ui-asks.md).
+
+## The problem
+
+Agents often need one decision before they can go on: which plan, which record, whether to
+proceed. In plain chat the agent asks in prose and the user types a reply. The agent then parses
+free text that may not match any option, nothing ties the reply to the question, and nothing stops
+the user from answering with something that was never offered.
+
+## Why client-side tool calls
+
+Each ask kind is an AI SDK tool, such as `ask_choice`, with a Zod input schema, an output schema,
+and no `execute` function. Most of the design follows from that choice:
+
+- **The model is held to the schema.** Provider function calling makes the model write a JSON
+  object for the tool, and the AI SDK checks it against the Zod schema. An invalid ask goes back
+  to the model as a tool error it can fix in its next step. It never reaches the user.
+- **The turn pauses by itself.** A tool without `execute` ends the AI SDK step loop, so the
+  server needs no waiting state inside the model call. It saves the paused turn and ends the
+  stream.
+- **The answer is tied to the question.** The tool call id is the key. The answer names it, and
+  the server accepts an answer only for the ask the conversation waits on.
+- **The model already knows how to read the answer.** It comes back as the tool's result, which
+  every provider represents natively, so no prompt wording has to explain what the user chose.
+
+This is the same pattern as AI SDK client-side tools, AG-UI interrupts, and CopilotKit
+human-in-the-loop. The answer envelope (`accept`, `decline`, `cancel`) is the MCP elicitation
+shape.
+
+Other approaches were rejected:
+
+| Approach | Why not |
+| --- | --- |
+| Move the chat to the AI SDK `useChat` UI message stream | Rewrites the SSE contract every host parses, and the history storage |
+| Form blocks inside the reply document, like Slack Block Kit inputs | Values come back as user text with nothing tying them to a question, and they need blocks turned on |
+| Interactive HTML mini-apps, like MCP Apps | No React Native host exists, and they open the widest phishing and data-leak surface |
+
+## One round trip
+
+1. **Ask.** The model calls `ask_choice` with a prompt and options. The AI SDK checks the input;
+   an invalid ask goes back to the model as a tool error.
+2. **Pause.** The step loop ends. The server derives the ask's simple card and saves the paused
+   turn on the history as `pendingAsk`, including the AI SDK messages the turn produced. It adds a
+   row for the ask with status `pending`, then sends `{ask}` with the conversation's `historyId`
+   and `{done}` with `pendingAsk`. Because `{ask}` names the conversation, a client can answer a
+   new chat's ask before `{done}` arrives.
+3. **Answer.** The client shows the ask and posts the answer with the ask's tool call id to
+   `POST /gpt/prompt`.
+4. **Check.** The server confirms the history belongs to the caller (403), that this is the ask
+   it waits on (409), and that the answer fits the ask (400, and the model is not called).
+5. **Resume.** One atomic update stores the answer row, marks the ask answered, and clears
+   `pendingAsk`. The server replays the saved messages with the answer as the tool result and
+   streams the rest of the turn, starting with `{askResolved}`.
+
+The server replays the saved messages instead of rebuilding them from history rows because the AI
+SDK messages carry provider metadata, such as Gemini thought signatures, that the rows do not
+keep. Replaying them resumes the exact turn the provider started. In later turns, the history goes
+through `buildMessages`, which keeps each ask and its answer so the model remembers what it asked
+and what the user chose. Host tool rows stay out of the model's messages, as before.
+
+The update is atomic because two answers to one ask, from a double tap or two devices, must resume
+the turn once. It matches on the pending ask's tool call id, so the second answer finds nothing to
+update and gets 409.
+
+The answer stays stored even when the model call that continues the turn fails. The user did
+answer, so the next message continues from the ask and its answer instead of asking again. Any
+turn that fails after its stream starts still ends with `{error}` then `{done}` and saves what the
+user saw, so a client always learns the turn ended and which conversation holds it.
+
+## One ask at a time
+
+A conversation waits on at most one ask. When the model asks twice in one step, the first ask
+pauses the turn and the others are answered with `cancel` and the reason `one_ask_at_a_time`,
+which the model sees when the turn resumes. Two turns on one conversation, say from two open tabs,
+follow the same rule. Setting the pending ask is a conditional update, so the ask saved first
+keeps waiting and the other turn's ask gets the same `cancel` instead of overwriting it.
+
+The user is never stuck behind a question. Typing a message instead of answering records `cancel`
+with the reason `user_sent_message`, then adds the message. The model sees both and can respond to
+what the user actually said. A message is never refused because its ask is gone: when another tab
+answered the ask first, the message goes ahead on the conversation as that answer left it. Only an
+answer can be stale, so only an answer gets 409.
+
+Turns never write back a whole copy of the conversation. Each turn appends its rows with one
+atomic update when it ends, and ratings set one field, so two turns or a rating racing a turn
+cannot drop each other's rows. A paused turn remembers how many rows come before and include its
+own user message, and its resume replays exactly those.
+
+## Approvals the server enforces
+
+`ask_confirm` works only when the model remembers to call it. A prompt injection, or a model that
+skips the step, can still call a destructive tool directly. So a host tool can set the AI SDK's
+`needsApproval: true`, and the server, not the model, makes the confirm.
+
+When the model calls such a tool, the AI SDK stops before `execute` and emits a
+`tool-approval-request`. The server turns it into a `confirm` ask with `origin: "approval"` and
+pauses the turn exactly as for a model ask: same pending slot, same simple card, same answers
+through `/gpt/prompt` and `turn`. The answer becomes the SDK's `tool-approval-response`. On
+resume the SDK runs the tool once when approved, or gives the model a denial when not, so the
+tool's own code never has to check.
+
+The approval uses the one pending slot rather than a second one. A client then has one question
+to show and one way to answer, and a watch needs no new card type. When a step holds a model ask
+and an approval, or two approvals, the first pauses the turn and each other approval is denied
+with `one_ask_at_a_time`. The model sees the denial and can ask again in its next turn.
+
+The host words the card with `asks.approvals`, because only the host knows what a call changes.
+The default, "Allow <toolName>?" with the tool's description, is safe but vague, so a
+destructive tool should name the effect and set `destructive: true`.
+
+Approval rows are for display. Later turns do not replay them, just as they do not replay host
+tool rows: the model's memory of the call is what it wrote in its reply.
+
+## Strict by design
+
+Every ask kind is a strict schema with hard limits. The limits live in one constant,
+`ASK_LIMITS`, which the schemas, the system prompt section, the tests, and a doc-parity test all
+read. The model can only ask for controls a client can render, and the user can only send answers
+the ask allows. The same pure validators run on the server and in clients, so a client can enable
+Submit exactly when the server will accept the answer.
+
+## Simple cards
+
+Every ask comes with a simple card: short text and at most three buttons, each holding the exact
+answer it sends. A client that knows nothing about ask kinds, such as a watch, a notification, or
+a chat bot, can render the card and answer with one tap by sending back the tapped button's answer.
+When the buttons cannot show every option the ask offers, the card sets `handoff` so the client
+can send the user to the full app. A card with a button for every option does not set it, even
+when Skip is left out to make room.
+
+The server derives the card once, when the ask is made, and stores it with the pending ask. A card
+already on a screen never changes, even if the derivation rules change later.
+
+Each button carries its exact answer, not a label for the client to turn into one. A client that
+knows no ask kinds cannot build a valid answer: it would need each kind's answer shape and rules.
+With the answer on the button, those rules stay on the server, and a test checks that every
+button's answer passes `validateAskResponse` for its ask. A client can also send only the pressed
+button's `id`. The server looks the id up on the card it stored and answers with that button's
+answer, so a client that sends only ids cannot send an answer the card did not offer.
+
+## In the chat
+
+`GPTChat` shows an ask where the model asked it: the ask's tool call row becomes an `AskCard` in
+the transcript, and the continuation streams in below it. The host still owns the network.
+`GPTChat` calls `onAskSubmit`, and the host posts the answer and reads the continuation with the
+same stream reader it uses for prompts. An answer the server rejects comes back to the card as
+`askErrors`, next to the control that caused it.
+
+A `choice` whose options all fit its simple card renders as that card's buttons, and a tap answers.
+A phone then shows the same buttons a watch would, and the most common ask, two or three short
+options, takes one tap. Longer lists get radio buttons or a searchable select with Submit.
+
+A `select: "many"` choice renders as checkboxes with Submit, because one tap cannot pick several.
+Its Other field lets the user answer with something the agent did not list, without leaving the
+ask for free text: the answer still names the offered ids in `selected`, and only the typed part
+is in `other`. Other counts as one choice against `maxSelected`, so "pick up to three" means three
+things in total, however the user picks them. Other is offered only with `"many"`; an agent that
+wants "one option or your own" asks `"many"` with `maxSelected: 1`, so every ask with free text
+goes through the same control and the same count rule. On a small screen a many-select card can
+offer only its suggested set and Skip, so it always hands off, and the compact surface does not
+offer `"many"` at all.
+
+A `confirm` guards one action the agent is about to take, such as deleting data or sending a
+message for the user. Its answer is `{confirmed: true}` or `{confirmed: false}`, so "no" is a real
+answer the agent must respect, not a skip: deny is the second button, and Skip appears only when
+the ask sets `allowDecline`. The card shows the simple card's two buttons in the same order on a
+phone and a watch, approve first and deny last. A `destructive` ask draws the approve button in
+the destructive style, and a watch never makes it the Double Tap button, so a gesture cannot
+approve an action that cannot be undone. The confirm is a pause in the turn, not a lock: the host's
+tool should still check that the action is allowed.
+
+A `markdown` ask hands the user a draft, such as an announcement or an email, in a markdown editor
+with a preview. It is one round trip, not a shared document: the user edits and sends the text
+back, and the agent continues with it. The answer carries `changed`, and the server checks it
+against the text, so `changed: false` reliably means "approved as is" and the agent need not diff
+the text itself. Editing needs a keyboard and room, so the compact surface never offers `markdown`.
+A watch still sees a markdown ask the phone's chat made: its card offers Approve draft, when the
+draft already meets the length rules, and Cancel, and it always hands off to the phone. A long
+answer collapses to a preview in the transcript, so one draft does not push the conversation out
+of view.
+
+A `form` asks for several values in one step, such as the details for an invoice, instead of a
+string of questions. Its fields are flat and typed, and the same rules check a default when the
+ask is made and a value when the answer arrives, so the agent never receives a value its own form
+would reject and never offers a default the user could not send back. Blank means unanswered.
+Dates travel as ISO strings in fixed shapes (`YYYY-MM-DD`, 24-hour `HH:mm`, and datetimes with an
+offset) so the agent never has to guess a time zone. Each error names its field
+(`content.values.<id>`), so the card shows it where the user can fix it. A small screen cannot
+fill in fields, so the compact surface never offers `form`; a watch can still send the defaults
+when every required field has one, and otherwise hands off to the phone.
+
+A `files` ask gets the user's files to the model as the model's own input types: images as image
+parts, PDFs as file parts, and text, CSV, and JSON as text cut at 100 KB. The declared type is not
+trusted. The server reads the bytes and rejects a file whose bytes are another type, so a renamed
+file cannot reach the model as something it is not. Files travel as uploads when the host has
+file storage and as data URLs when it does not, so an app without a bucket still works. Either
+way the history keeps only each file's name, type, and size: the bytes reach the model once, on
+the answering turn, and a long conversation does not grow by the size of its files. Picking files
+needs a phone or a computer, so the compact surface never offers `files`.
+
+After an ask ends, the card collapses to one line, such as "You chose: Team" or "You declined:
+Keep them". A long conversation
+then reads as a record of what the agent asked and what the user decided. The answer's
+`tool-result` row stays in the message list but is hidden. Ratings address messages by their index
+in the stored rows, so the client keeps one message per row, and after a reload the summary reads
+the answer from that row.
+
+A pending ask takes focus when it appears, so keyboard and screen reader users land on the question
+instead of hunting for it.
+
+## Small screens and the watch
+
+A watch shows about three short buttons. A full `choice` can offer 50 options, and on a watch its
+card can only hand off to the phone. So a small client says where the user is with
+`surface: "compact"`, and the server narrows what the agent may ask on that turn: a `choice`
+with `select: "one"` and 2–3 options whose labels fit a button uncut and differ from each other,
+or a `confirm`, whose two labels already fit. Every card made on a
+compact turn can be answered from the watch, and the system prompt asks for replies of at most two
+short sentences. The narrowing is in the tool's input schema, not only in the prompt, so the model
+cannot ask what the watch cannot show. A compact ask that breaks the rules goes back to the model
+as a tool error, like any invalid ask.
+
+The surface belongs to a turn, not to the conversation. One conversation can start in the phone's
+chat and continue on the watch, and each turn gets the rules of the screen it was sent from.
+
+A watch app, a notification action, or a chat bot wants to send one request and read one
+response, not a server-sent event stream. The `turn` action runs the same turn as `/gpt/prompt`,
+through the same turn runner, and collects its events into one JSON result. Both save the same
+rows, so the phone's chat shows what was answered on the watch. The turn keeps running when the
+client disconnects, which matters on a watch, where the system can suspend the app mid-request.
+The turn is saved, and the client reads the reply or the next ask later. `pendingAsks` lists what
+waits on the user across every conversation, so a watch can show it without opening each one.
+
+How an Apple Watch can plug in:
+
+| Path | What it needs | Status |
+| --- | --- | --- |
+| SwiftUI watch app | A native watchOS target, because React Native does not run on watchOS. `@bacons/apple-targets` adds one to an Expo app. The phone hands the session token over WatchConnectivity, and the app calls the two endpoints with `URLSession`, always with `surface: "compact"`. The [how-to](../how-to/agent-ui-asks.md#answer-asks-from-an-apple-watch-or-another-small-client) sketches one. | Protocol ready; a sample app is Future Work |
+| Actionable push, no watch app | iOS forwards iPhone notifications with up to 4 action buttons to the watch. It needs `categoryId` on comms push, `data` on `notify()`, templated categories (iOS fixes action labels when the app registers a category), actions that do not open the app, a small native iOS handler (expo-notifications completes before a JavaScript `fetch` finishes), and a one-time action token per ask. | Future Work |
+
+Other follow-ups: finishing long turns in a `@terreno/jobs` background job, so a headless answer
+returns at once instead of waiting for the agent, and Wear OS.
+
+## Asks and blocks
+
+Asks and [UI blocks](agent-ui-blocks.md) split the work by where the
+result goes. Body components are Phase 5 of the asks plan; the design record remains
+[agent-ui-blocks](../implementationPlans/agent-ui-blocks.md).
+
+| Need | Mechanism |
+| --- | --- |
+| Show data, such as a chart, table, or metric | A block in the reply |
+| Suggest a follow-up message | A block button that sends a reply |
+| Run host code, such as an export | A block button with a host callback |
+| Get an answer the agent needs to continue | An ask: tool call, pause, answer, resume |
+| Answer from a watch or another small client | The ask's simple card, through `pendingAsks` and `turn` |
+
+Blocks display, and their buttons start something new: a message or host code. Asks collect, and
+their answer goes back to the agent as the result of the call that asked. An ask's `prompt` is
+plain text, so an ask cannot show a chart or table above its control yet. Both live in
+`@terreno/blocks`, which holds the schemas for what the agent can show and ask.
+
+## Trust boundaries
+
+- **Only the server writes the paused turn.** The saved messages are replayed to the model
+  verbatim, so a client must not be able to plant or edit them. The history REST API drops
+  `pendingAsk` from create and update bodies, and the answer a client sends is only the envelope,
+  checked against the stored ask.
+- **A button id answers only with the stored card.** The server resolves `buttonId` on the card
+  it saved when the ask was made. An id that is not on the card gets 400 `UNKNOWN_BUTTON`, and the
+  ask stays pending.
+- **A client can only answer an approval, never make one.** The approval request and the
+  `tool-approval-response` live only in the server's stored messages. A client sends the answer
+  envelope for the pending ask's `toolCallId`, and the server builds the response for the
+  `approvalId` it stored. A crafted approval response in the body gets 400, and another tool
+  call's id gets 409.
+- **A turn speaks as the conversation's owner.** Only the owner can send a `turn`. An admin gets
+  403, because the model would read the admin's message or answer as the owner's.
+- **Asks do not collect secrets.** The system prompt tells the model never to ask for passwords,
+  payment card numbers, API keys, or other secrets.
+- **HTML is display-only and opt-in.** An `html` block can be used for XSS, phishing, exfiltration, or clickjacking if it runs as part of the host page. The server allows it only when `uiBlocks.html` is on, strips scripts, event handlers, forms, frames, `meta`/`base`/`link`, anchor `href`s, and every URL except `data:image`, then stores that cleaned document. The client draws it in a sandboxed frame with no JavaScript and no navigation, labeled as an agent-generated preview, and only after the reply has finished.
+- **Image hosts are an allowlist.** An `image` block can leak conversation data by requesting a URL the model chooses. `data:image` URLs and `file:` refs are always allowed. An `https` URL loads only when its hostname is in `uiBlocks.imageHosts`. The default list is empty, so a hostile prompt cannot point the image at a server the app did not name.
+- **The image allowlist does not cover Markdown.** `imageHosts` applies to `image` blocks, `gallery` tiles, and `list` item images only. A Markdown image (`![alt](https://…)`) inside a `text` block, or in a plain assistant reply when `uiBlocks` is off, renders through `MarkdownView` and loads from any URL the model writes (decision D27 kept the existing Markdown behavior). So a prompt-injected reply can still make the client request an attacker's URL through Markdown, and that request can carry conversation data in its path or query. Apps that need the allowlist guarantee for every image should also restrict Markdown images. One approach, not built today, is an `imageHosts`-aware image handler on `MarkdownView` that drops or placeholders images whose host is not on the list, wired to the same hosts the server passes to `uiBlocks.imageHosts`.

package/src/docs/versioned/57.20.0/explanation/agent-ui-blocks.md

@@ -0,0 +1,127 @@
+# Agent UI blocks
+
+When a chat turns UI blocks on, the assistant reply is one YAML document of Terreno
+components, not free HTML or JSX. This page explains why the catalog is closed and why the
+whole reply is the document. Field tables and error codes are in the
+[reference](../reference/blocks.md). Asks, which return a typed answer to the agent, stay
+in [Agent UI Asks](agent-ui-asks.md).
+
+The design record is
+[agent-ui-blocks.md](../implementationPlans/agent-ui-blocks.md). Pick executes that work as
+Phase 5 of [Agent UI Asks](../implementationPlans/agent-ui-asks.md).
+The stepper, checklist, gallery, list, card eyebrow, and copy additions are recorded in
+`docs/implementationPlans/agent-ui-rich-replies.md`.
+
+## Why a closed catalog
+
+An agent that can emit arbitrary components can also emit styles, scripts, and layout the
+app theme does not own. The catalog is the list of `@terreno/ui` components the chat can
+paint. Unknown keys and unknown block types fail validation, so a reply cannot smuggle a
+`style` object or a hex color.
+
+| Group | Blocks | Notes |
+| --- | --- | --- |
+| Text | `heading`, `text`, `context`, `callout`, `details` | `text` is markdown, including GFM tables |
+| Values | `metric`, `badge`, `divider` | |
+| Data | `chart`, `table` | Read an inline or `ref` dataset |
+| Media | `image`, `gallery`, `list` | Sources are `data:image`, `file:`, or an allowed `https` host |
+| Interactive | `actions` (`button`, `segmented`), `stepper`, `checklist` | Button actions: `reply`, `open`, `select`, `callback`, `copy` |
+| Layout | `columns`, `card` (optional `title` and `eyebrow`) | Leaf blocks only inside |
+| Escape hatch | `html` | Only with `uiBlocks.html`; sanitized before storage |
+
+Field rules for each block are in the [reference](../reference/blocks.md).
+
+The same pure functions run wherever a document is checked. `parseBlocks` and
+`validateBlocks` live in `@terreno/blocks`, which has no React and no Express. The renderer,
+the chat route, and the `terreno-blocks` CLI all call them; none grows a second grammar.
+
+## Why interactive blocks call the server
+
+A stepper that rescales a shopping list, or a checklist that remembers ticks, needs logic.
+Terreno does not give the document a shared `state` with `{{formula}}` bindings, and it does
+not run scripted html. Both need an expression language the theme and the validator cannot
+see into. Instead, an interactive block names a host callback, as a callback button does:
+
+| Interaction | Who runs it | Result |
+| --- | --- | --- |
+| Stepper − / + | Host action with `handles: "stepper"`, through `POST /gpt/actions` | The replacement stepper, swapped in by block id |
+| Checklist tick | Host action with `handles: "checklist"`, or the device when the checklist has no callback | The replacement checklist, or a local tick |
+| `copy` button | The device | Text on the clipboard; nothing reaches the server |
+
+The cost is one round trip per tap. The view disables the block while the call is pending, so
+fast taps are dropped, not queued, and a checklist tick cannot send ticks that miss the one
+before it. The gain is that the agent writes plain data, and the app's code decides what a
+tap means. `scaleStepperHostAction` and `toggleChecklistHostAction` in `@terreno/ai` cover the
+common case. They read the block the agent wrote from the stored history and never trust the
+tap request's copy of it. The history owner can still edit stored prompts, so an app whose
+numbers matter (prices, stock) registers its own action over its own data.
+
+Overrides live in client memory. A reload shows the agent's original block again.
+
+## Why photos come from a stored library
+
+A model cannot make a photo while it writes a reply, and an `https` image needs an
+`imageHosts` allowlist the model cannot know. The example app generates a photo library once
+per environment with the Vertex image model, stores it through `FileStorageService`, and gives
+the agent a `findPhotos` tool that returns `file:` ids. The reply cites ids; the client
+resolves each id to a signed URL. Generation cost and latency stay out of the chat turn, and
+every photo the user sees was made and stored ahead of time. See
+[Give the agent photos](../how-to/agent-ui-blocks.md#give-the-agent-photos).
+
+## Rollout: rich blocks are on by default
+
+`uiBlocks.richBlocks` defaults to `true`. The prompt then offers `checklist`, `gallery`,
+`list`, `card.eyebrow`, and `copy`, and offers `stepper` when a host action has
+`handles: "stepper"`. A stepper without such an action would have dead buttons, so the
+prompt does not mention it.
+
+The server and the web client upgrade together. A native build already in the app stores
+does not know the new blocks: a reply that uses them fails its validation and shows the
+error banner with the raw YAML. A host with such builds sets `uiBlocks.richBlocks: false`
+until they update. The prompt is then the same as before rich blocks. Validation still
+accepts the new blocks, so a stored reply that uses them still renders on new clients.
+A client-declared catalog version, so the server picks blocks per client, would remove that
+manual step; it is not built yet.
+
+## Why the whole reply is YAML
+
+The document is the reply. There is no prose before it and no fenced block inside
+markdown. A leading or trailing fence is stripped so a model that adds one still parses.
+JSON is accepted because it is a YAML 1.2 subset and is what a structured-output call
+emits.
+
+Key order is `v`, then `datasets`, then `blocks`. Datasets come first so a streaming
+renderer can know the data before the first block. `parseBlocksPartial` returns the
+top-level blocks that have already finished and marks the cut tail pending. The finished
+document is still checked with `validateBlocks`.
+
+Text in the same step as a tool call is not the reply, except when that text is a block document and no later step has text. An actions block that left off `id` receives one before storage, and the chat is sent the corrected document.
+
+A reply that is not a mapping with `v` is not a document. The chat can still show it:
+`wrapAsTextDocument` turns the raw text into one `text` block. The error
+`NOT_A_DOCUMENT` is how the caller tells that case apart from a document that failed a
+field check.
+
+YAML anchors, aliases, and explicit tags are rejected. They let one node stand in for
+another, which makes a small document able to expand in ways the limits cannot see.
+
+## Ownership
+
+| Layer | Owns |
+| --- | --- |
+| `@terreno/blocks` | Schema, parse, partial parse, validate, JSON Schema, prompt section, `blockPlainText`, CLI, limits, error codes |
+| `@terreno/ui` | `BlocksView` renders every block in the catalog. A select action changes the target chart or table dataset in that view. A segmented control starts on the option that matches that dataset. A callback button or stepper stays disabled when `hostActions` is set and does not include its name; a checklist with such a callback ticks locally instead. A `copy` button writes the clipboard on the device. `GPTChat` `uiBlocks` renders assistant messages through `BlocksView`, including a spinner while the reply is still streaming, and swaps a block when a callback returns `{replace: "block"}`. A `file:` image stays as alt text until `resolveImage` returns a URL. |
+| `@terreno/ai` | When `uiBlocks` is on: the chat system prompt, the post-stream `{blocks}` check, `AIDataset` storage, and `POST /gpt/actions`. The opt-in `scaleStepperHostAction` and `toggleChecklistHostAction`. `AIService.generateBlocks` returns one validated document outside a chat turn. |
+
+Asks use the same package under `src/asks/`. A block shows something. An ask collects an
+answer and returns it to the agent.
+
+A callback button is the Block Kit `block_actions` path. The document names the callback.
+The host owns the code.
+
+| | Block Kit | Terreno |
+| --- | --- | --- |
+| Who runs the click | Slack posts `block_actions` to the app | The client posts `POST /gpt/actions` |
+| Payload check | The app trusts the platform body | The host Zod schema runs before the handler |
+| What comes back | `chat.update` replaces the message | `{replace, blocks}` replaces the block, or `{text}` appends a message |
+| Time limit | The platform's request window | 10 seconds, then 504 |

package/src/docs/versioned/57.20.0/explanation/ai-development-loop.md

@@ -0,0 +1,196 @@
+# AI development loop
+
+A coding agent working on a Terreno app runs the same five-stage loop on every change:
+it asks how something should be done, generates the code, runs the app, observes what the
+app did, and fixes what it finds. Terreno's two MCP servers supply a tool for each stage.
+
+- **`terreno-mcp`** is the hosted server. It holds the docs, the code generators, and the
+  convention validators. It knows Terreno but not your app.
+- **`terreno-mcp-local`** runs in your project over stdio. It reads your app's logs,
+  client state, and database, and drives the running app. It knows your app but not the
+  docs.
+
+```mermaid
+flowchart LR
+  ASK["1. Ask<br/>terreno_search_docs<br/>terreno_get_component_docs<br/>application_info"]
+  GEN["2. Generate<br/>terreno_generate_*<br/>terreno_validate_model_schema"]
+  RUN["3. Run<br/>backend dev server<br/>Metro (Expo)"]
+  OBS["4. Observe<br/>read_logs (backend / browser / metro / app)<br/>last_error<br/>get_client_state"]
+  FIX["5. Fix<br/>edit, then navigate<br/>browser snapshot + screenshot"]
+  ASK --> GEN --> RUN --> OBS --> FIX
+  FIX -->|"iterate"| ASK
+```
+
+This page covers what the agent can see and do at each stage, and where that stops. How
+Terreno's conventions reach the agent in the first place is in
+[Agent guidelines](agent-guidelines.md).
+
+## The five stages
+
+### 1. Ask
+
+The agent looks up the current way to do something before it writes code.
+
+| Tool | Server | Contributes |
+| --- | --- | --- |
+| `application_info` | local | The app's `@terreno/*`, Expo, React Native, and Mongoose versions, so later answers match the installed release |
+| `terreno_search_docs` | hosted | BM25 search over the bundled docs, several queries per call, filtered by package and lockstep `version` |
+| `terreno_get_component_docs` | hosted | The full props table for one `@terreno/ui` component |
+| `terreno_get_upgrade_guide`, `terreno_search_update_notes`, `terreno_get_update_note`, `terreno_ask_update_help` | hosted | Upgrade notes for a version range, and questions against them |
+| `terreno://docs/*` resources | hosted | Fixed entry pages a client can read without a tool call |
+
+Version matters here. An agent that passes the app's version to `terreno_search_docs` gets
+the guidance for the release the app is on, not for the newest one.
+
+### 2. Generate
+
+The agent produces code in Terreno's shape instead of inventing it.
+
+| Tool | Server | Contributes |
+| --- | --- | --- |
+| `terreno_generate_model`, `terreno_generate_route`, `terreno_generate_screen`, `terreno_generate_form_fields` | hosted | A Mongoose model with the standard plugins and types, a `modelRouter` with permissions, an Expo screen, form fields |
+| `terreno_validate_model_schema` | hosted | Checks a schema against the conventions, such as a `description` on every field |
+| `terreno_validate_ui_blocks` | hosted | Checks an agent reply document against the blocks catalog |
+| `terreno_install_admin` | hosted | Admin panel integration snippets |
+| `terreno_bootstrap_ai_rules` | hosted | Rule files for the app's editors |
+
+The generators return file contents and instructions. They do not write files, so the agent
+stays in control of where code lands. A new app is scaffolded by `create-terreno-app`, not by
+an MCP tool.
+
+### 3. Run
+
+The app runs the way a developer runs it: the backend dev server, and Expo's Metro dev
+server for the web, simulator, or device build. There is no special agent runtime. The
+local server attaches to what is already running.
+
+Two pieces of development-only instrumentation make the running app observable:
+
+- The backend's logger writes JSONL to `.terreno/logs/app.log`. By default this is on
+  whenever `NODE_ENV` is not `production`.
+- On web, `installTerrenoDevConsoleLogger` (from `@terreno/syncdb`) forwards `console.error`,
+  `console.warn`, and uncaught errors and rejections to the backend's `POST /__terreno/browser-logs` route, which writes
+  `.terreno/logs/browser.log`. The route exists only in development and is never registered
+  in production. See [Development browser-log ingestion](../reference/api.md#development-browser-log-ingestion).
+
+### 4. Observe
+
+The agent reads what the app did.
+
+| Tool | Contributes |
+| --- | --- |
+| `read_logs` | One merged, time-ordered tail from four sources: `backend` (server JSONL), `browser` (web errors and warnings JSONL), `metro` (bundler events), and `app` (the Hermes console over the Chrome DevTools Protocol). Its `connection` field says which live sources are attached. |
+| `last_error` | The newest error-level entry across the same sources, as the raw line. It includes a stack when the entry carries one. |
+| `get_client_state` | The client data layer in the running app. It reports which `layer` it found (`rtk`, `syncdb`, both, or `none`) and returns the RTK Query cache and auth state, the SyncDB state, or both. `get_rtk_state` is a deprecated alias. |
+| `get_syncdb_state`, `syncdb_snapshot` | SyncDB entities, outbox, conflicts, cursors, and debug events, plus snapshots to compare before and after a change |
+| `database_schema`, `database_query` | The app's MongoDB collections and documents, through a read-only allowlist |
+
+All of these are reads. None of them needs an opt-in.
+
+### 5. Fix
+
+The agent edits code in its own editor, then reproduces the path that failed and checks the
+result.
+
+| Tool | Contributes |
+| --- | --- |
+| `navigate` | Moves a native app to an expo-router path over the same CDP connection the logs use |
+| `browser` | Drives the web app in a headless WebView: open, click, type, scroll, then `snapshot` the rendered page and save a `screenshot` as proof |
+| `evaluate` | Runs a JavaScript expression in the app's Hermes runtime |
+| `syncdb_action` | Changes a live SyncDB client: mutate, flush, resync, resolve conflicts, go offline |
+
+`evaluate`, `navigate`, `syncdb_action`, and the `browser` tool's `evaluate` action run code
+or change state inside the app, so they refuse unless the local server was started with
+`TERRENO_MCP_EVAL=1`. Generated editor configuration never sets it. The other `browser`
+actions do not need it.
+
+After the fix, the loop goes back to Observe. A change is done when the logs and state show
+the new behavior, not when the edit compiles.
+
+## Tool layer versus process layer
+
+The loop is half of how Terreno works with agents. This page covers the tool layer. The
+`/terreno-*` lifecycle skills are the process layer, described in
+[Planning plugins](planning-plugins.md).
+
+| Layer | Answers | Delivered by |
+| --- | --- | --- |
+| **Tool** | What can the agent see and do? | MCP servers: docs search, codegen, merged logs, client state, navigation |
+| **Process** | In what order should the agent work, and who checks it? | `/terreno-*`: question-first planning, TDD, fresh-context independent review, evidence gates, reactive review loop |
+
+The two compose. The lifecycle's build and prove stages use the loop's tools to gather their
+evidence, and the tools are most useful when the lifecycle decides when to call them.
+
+## What makes this different
+
+The agent observes what the app actually did, not a description of it.
+
+Without these tools, an agent learns about a failure from a person's summary, a pasted stack
+trace, or its own guess about what the code should do. With them, it reads the 500 from the
+server log, the uncaught error from the browser console, and the cache entry the screen
+rendered from. It reads them from the same run it just changed.
+
+The rest is table stakes. Docs search, generators, and rule files exist for other frameworks
+too, and Terreno does not claim otherwise.
+
+## What the agent cannot see
+
+The loop ends at the edge of the local development session, and some sources have gaps
+inside it.
+
+- **Production.** The backend log file is off in production by default, the browser-log
+  route is never registered there, and no tool reads a hosted log service. Production errors
+  reach the agent only if a person brings them in.
+- **Native crash reports.** A native crash outside the dev loop, such as an iOS crash report
+  or an Android tombstone, never reaches the JavaScript console, so no log source carries it.
+- **Devices not attached to a dev server.** The `app` source, `navigate`, and `evaluate` reach
+  a runtime only through Metro's inspector. A phone running a release build, or one not
+  connected to Metro, is invisible.
+- **The `app` source on web.** The web build has no Hermes target, so `app` returns nothing
+  there. On web, errors, warnings, and uncaught exceptions arrive through the `browser` source
+  instead; `console.log` and `console.info` reach no source. `app` needs a native
+  development build or Expo Go attached to Metro.
+- **Metro events under Expo CLI.** The `metro` source reads Metro's `/events` socket. In Expo
+  CLI 57 that socket accepts connections but never sends events, so `metro` stays empty even
+  when its status reads connected.
+- **The Hermes debugger connection.** The local server holds one CDP session to the app. On a
+  default `expo start` with current React Native, that session and React Native DevTools
+  coexist. On a target that allows a single debugger, or when Expo runs headless, opening
+  DevTools disconnects the local server. The next call that reads the app reconnects and
+  disconnects DevTools in turn, and console entries logged in between are lost. The
+  `connection` field reports the close reason.
+- **Missing stacks.** `last_error` returns the line as it was logged. If the code logged a
+  message without a stack, there is no stack to return.
+
+## How this composes
+
+Terreno does not build its own simulator or browser automation. It composes with three tools
+that already do it well, and keeps to the part they lack: reading the app's logs, client
+state, and data.
+
+| Tool | Use it for | Lives |
+| --- | --- | --- |
+| `expo-mcp` | Interacting with the iOS simulator or Android emulator: screenshots and taps on the native app | Agent session |
+| Playwright MCP | Interacting with the web app in a full browser while working | Agent session |
+| Maestro | Flows worth keeping, such as login, signup, and creating a todo, committed and run in CI | Repository |
+
+The division of labor:
+
+- **Interaction is the composed servers' job.** `expo-mcp` and Playwright MCP move the app
+  and show what is on screen. Terreno's `browser` tool covers the same ground on web when a
+  lightweight headless session is enough.
+- **Observation is Terreno's job.** After a tap or a click, `read_logs`, `last_error`, and
+  `get_client_state` show what the app did behind the screen.
+- **Durability is Maestro's job.** An agent session ends. A flow that proved a fix and should
+  keep proving it becomes a Maestro flow, so CI repeats the check on every change.
+
+`create-terreno-app` writes `expo` and `playwright` entries next to the two Terreno servers
+in the app's `.cursor/mcp.json` and `.mcp.json`, so a new app starts with all four.
+
+## Related
+
+- [Set up Terreno MCP](../how-to/set-up-terreno-mcp.md): connect the servers to your editor
+- [Debug a Terreno app with MCP](../how-to/debug-with-mcp.md): the loop on a real failure
+- [MCP server reference](../reference/mcp-server.md): every tool, prompt, resource, and variable
+- [Agent guidelines](agent-guidelines.md): how Terreno's conventions reach the agent
+- [Planning plugins](planning-plugins.md): the process layer