sygnal 6.2.0 → 6.4.0

package/dist/guide/ai-decisions.md

@@ -248,6 +248,21 @@ Ticket.resources = {
 
 A `noul` question becomes a `predicate` whose instructions include the criteria. OpenAI may refuse a question: its answer is then `{ type: 'refusal', … }`, so check `answer.type` before reading `choice`. The type `Decision<Q, RefusalAnswer>` includes it.
 
+## Large question sets
+
+Servers limit what one request may ask: Ollama's `/v1/systemone` takes at most 64 questions, and each question's prompt (the `state` plus every question of the request) must fit the model's context, 8,192 tokens for `nimble`. `decide()` handles it, and your component still gets one reply:
+
+- More than `maxQuestions` questions (default 64): the request goes as several requests of about even size, sent in parallel. Their replies arrive as one: `answers` merged by name, `usage` summed, `model` from the first.
+- `maxPromptTokens`: the same split when the estimated prompt of one question passes it. The estimate runs high (on `nimble`, 1.13 to 1.30 times the count Ollama reports), and there is no default.
+- A request the server rejects as too large is halved and sent again, at most 3 times deep. "Too large" means HTTP 400 or 413 whose body mentions tokens, fields, context, a limit, or "too long", "too many" or "too large". Other errors arrive as before. A rejection costs one fast round trip (Ollama answers it in about 10 ms), so Jev's requests, which fit, go out exactly as before.
+- `split: false` sends every request whole and never halves it.
+
+```js
+decide({ model: 'nimble', url: 'http://localhost:11434/v1/systemone', state, questions, maxQuestions: 32 })
+```
+
+The request keeps the whole decision in `json`, and its parts in `batch`, with `combine` and `split`. The [fetch driver](./http.md) reads those three keys, and any request can use them. Under `renderComponent` the fake answers a split request as one: `t.requests('HTTP')` lists it once, and `t.respond('HTTP', answers(questions, picks))` answers all its questions together.
+
 ## Keys stay on the server
 
 The browser never holds a provider key ([SYG670](https://sygnal.js.org/reference/errors/#syg670) refuses to send one to another origin). `decide()` posts to `/api/decide` on your own server by default, and that route adds the key. Keep it narrow, as for [chat](./ai-chat.md#shipping-it): fix the model, require a session, and limit the size of `state`, so the route can't be used as a free decision API.
@@ -326,5 +341,6 @@ It reads the actions from the components' [`agent` declarations](./agent.md#the-
 
 - [Agents](./agent.md): the `agent` static, the command bar and the in-app assistant
 - [AI Chat](./ai-chat.md): the chat driver, transports, and shipping an AI SDK route
+- [Composing UI with a Model](./ai-compose.md): a decision model builds a page from your catalog of parts with `compose.decisions()`
 - [Resources and Caching](./resources.md): the rules a decision resource follows
 - [Support inbox](./recipes/ai-support-inbox.md): triage, sorting and escalation in a whole inbox

package/dist/guide/http.md

@@ -137,6 +137,7 @@ A request is an object (or a URL string, for a plain GET with no reply actions):
 | `updates` | — | After a 2xx reply, write it into this component's resources (and their cache entries): `updates: 'item'`, or `{ items: (list, reply) => newList }` ([Writing a reply into the cache](./resources.md#writing-a-reply-into-the-cache)) |
 | `retry` | driver's `retry` for GET/HEAD (0) | Retry network errors, 408, 429 and 5xx: a count or `{ count, delayMs, maxDelayMs, jitter }` ([Retries](./resources.md#retries)) |
 | `validate` | — | A Standard Schema the body must pass ([Validation](./resources.md#validation)) |
+| `batch`, `combine`, `split` | — | One reply from several fetches: `batch` sends these requests in parallel instead (each inherits this request's fields; its own `json`, `body`, `parse` win), `combine(bodies, requests)` merges their parsed bodies into the reply, and `split(request, error)` returns the requests to try instead when one fails (at most 3 deep). `decide()` sets them for [large question sets](./ai-decisions.md#large-question-sets); the test fake answers such a request as one |
 
 Any other field is yours (an id, the query text): it isn't sent, and it comes back on the failure's `request`. A sink that returns `ABORT`, `null` or `undefined` sends nothing.
 

package/dist/guide/mcp-apps.md

@@ -48,10 +48,19 @@ App.model = {
     STATE: (state) => ({ ...state, status: 'loading' }),
     MCP: (state) => ({ callTool: 'get_forecast', args: { city: state.city }, ok: 'RESULT' }),
   },
-  // tell the model what the user picked: it reads it on its next turn
+  // tell the model what the user picked: store it on the server, where the model reads it with a
+  // tool, then send it as model context too (see Model context below)
   PICK: {
     STATE: (state, date) => ({ ...state, selected: date }),
-    MCP: (state, date) => ({ updateModelContext: { city: state.city, selectedDay: state.days.find((d) => d.date === date) } }),
+    MCP: (state, date) => ({ callTool: 'select_day', args: { city: state.city, day: state.days.find((d) => d.date === date) }, ok: 'PICKED' }),
+  },
+  PICKED: {
+    MCP: (state) => ({
+      updateModelContext: {
+        content: `The user selected ${state.selected} in the ${state.city} forecast card.`,
+        structuredContent: { city: state.city, selectedDay: state.days.find((d) => d.date === state.selected) },
+      },
+    }),
   },
   // post a message to the conversation, as the user
   ASK: { MCP: (state) => ({ message: `What should I pack for ${state.city} on ${state.selected}?` }) },
@@ -92,7 +101,7 @@ The latest tool input, tool result, host context and `host` are replayed to a co
 | Value | Does |
 |---|---|
 | `{ callTool: 'name', args, ok, error }` | Calls a tool on the MCP server through the host. `ok` gets the `CallToolResult`; `error` gets `{ error, code?, result?, request }` (a JSON-RPC error, or a result with `isError: true`) |
-| `{ updateModelContext: value }` | Tells the model something, for its next turn: a string (one text block), content blocks, or an object (`structuredContent`) |
+| `{ updateModelContext: value }` | Tells the model something, for its next turn: a string (one text block), content blocks, an object (`structuredContent`), or `{ content, structuredContent }`. The host decides whether the model sees it: see [Model context](#model-context) |
 | `{ message: 'text' }` | Posts a message to the conversation as the user (a string or content blocks) |
 | `{ openLink: 'https://…' }` | Asks the host to open a link |
 | `{ displayMode: 'fullscreen' }` | Asks for `'inline'`, `'fullscreen'` or `'pip'`; `ok` gets `{ mode }`, the mode the host chose |
@@ -155,6 +164,45 @@ Export.model = {
 
 **Theme and size.** Follow `host-context-changed` for the host's `theme` (and its `styles.variables`, CSS custom properties the host suggests), so the view matches the conversation around it. Keep the view compact for `inline` mode; offer full screen with `{ displayMode: 'fullscreen' }` when `availableDisplayModes` includes it.
 
+### Model context
+
+A view has three ways to tell the model something, and hosts handle them differently:
+
+- `{ message }` posts a message to the conversation as the user. The model sees it and answers it, in every host that supports `message`. Use it when the user's click is a question (the starter's **Ask about this day**).
+- `{ updateModelContext }` gives the host context for the model's **next** turn, and the host decides what to do with it. The spec says a host *should* pass it on, not how. Cursor adds it to the next user message; claude.ai keeps it and lets the model fetch it with a built-in tool ("Reading widget context"), and so does Claude Desktop's Code tab (`read_widget_context`, which the host points the model to); Claude Desktop's chat (tested October 2026) accepts it, but its model has no way to read it.
+- **A tool on your server.** The view saves what the user did with a tool only the view may call, and the model reads it with an ordinary tool. This reaches the model in every host, because every host offers the server's tools.
+
+The starter does the last two. When the user picks a day, the view calls `select_day`, then sends the same selection as model context:
+
+```js
+// server/server.js
+let selection = null   // one per process: the stdio server runs one per host connection
+
+// only the view can call it: visibility ['app'] keeps it out of the model's tool list
+server.registerTool('select_day', {
+  description: 'Records the day the user selected in the forecast card.',
+  inputSchema: { city: z.string(), day: z.object({ date: z.string(), sky: z.string(), high: z.number(), low: z.number() }) },
+  _meta: { ui: { resourceUri: VIEW_URI, visibility: ['app'] } },
+}, async ({ city, day }) => {
+  selection = { city, day }
+  return { content: [{ type: 'text', text: `Selected ${day.date} in ${city}` }], structuredContent: selection }
+})
+
+// the model's way to read it; get_forecast's description says to call it
+server.registerTool('get_selected_day', {
+  description: 'The day the user selected in the forecast card shown by get_forecast, if any.',
+  inputSchema: {},
+}, async () => ({
+  content: [{ type: 'text', text: selection ? `The user selected ${selection.day.date} in ${selection.city}.` : 'The user has not selected a day.' }],
+}))
+```
+
+The stdio server runs once per host connection, so one variable holds one user's selection. A server many users share (Streamable HTTP behind a public URL) has to keep it per user or session.
+
+Send `updateModelContext` with a text `content`: hosts list the content types they take (`MCP.select('host')` gives `hostCapabilities.updateModelContext`, Claude's is `{ text: {}, image: {} }`), and one that doesn't list `structuredContent` may drop an update that only has it.
+
+A host may also keep a tool's view (the `ui://` resource) and the tool list for as long as the server stays connected: Claude Desktop fetches them once per connection. After rebuilding the view or changing a tool, reconnect the server (restart the host, or turn the server off and on) before trying it again.
+
 ## The view's own tools
 
 The model sees the server's tools. With `tools: agentTools`, the view also offers its components' [`agent` declarations](./agent.md) to the host as tools of its own, so the model can operate the view while it is shown: select a day, change units, open a detail. Calls go through the same [call rules](./agent.md#the-call-rules) as any agent's.
@@ -263,7 +311,14 @@ it('shows the result, refreshes, and tells the model what the user picked', asyn
 
   t.simulateEvent('.day', 'click', { data: { date: 'Tue' } })
   await t.waitForState((s) => s.selected === 'Tue')
-  expect(t.requests('MCP').at(-1)).toEqual({ updateModelContext: { city: 'Oslo', selectedDay: days[1] } })
+  expect(t.requests('MCP').at(-1)).toEqual({ callTool: 'select_day', args: { city: 'Oslo', day: days[1] }, ok: 'PICKED' })
+  await t.respond('MCP', { content: [], structuredContent: { city: 'Oslo', day: days[1] } }, 'PICKED')
+  expect(t.requests('MCP').at(-1)).toEqual({
+    updateModelContext: {
+      content: 'The user selected Tue in the Oslo forecast card.',
+      structuredContent: { city: 'Oslo', selectedDay: days[1] },
+    },
+  })
 })
 ```