sygnal 6.2.0 → 6.3.0

package/src/ai.d.ts

@@ -1,12 +1,12 @@
 // Types for 'sygnal/ai' (PLAN-6). The implementation lives in src/extra/ai/ (D253).
-import type { FetchRequest, Behavior, BehaviorTarget, FieldErrors } from 'sygnal'
+import type { FetchRequest, Behavior, BehaviorTarget, FieldErrors, RenderResult } from 'sygnal'
 import type { Stream } from 'xstream'
 
 /** A part of a chat message (AI SDK UIMessage-shaped, D252) */
 export type MessagePart =
   | { type: 'text'; text: string }
   | { type: 'reasoning'; text: string; /** provider data to send back with it (an Anthropic thinking signature) */ providerMetadata?: Record<string, Record<string, unknown>> }
-  | { type: `tool-${string}`; toolCallId: string; state: string; input?: unknown; output?: unknown; errorText?: string; approval?: { id: string; approved?: boolean; reason?: string; [key: string]: unknown }; providerExecuted?: boolean }
+  | { type: `tool-${string}`; toolCallId: string; state: string; input?: unknown; output?: unknown; errorText?: string; approval?: { id: string; approved?: boolean; reason?: string; [key: string]: unknown }; providerExecuted?: boolean; /** PLAN-9 H-2: an `ask_user` call's card */ ui?: ChatCard }
   | { type: 'file'; mediaType: string; url: string; filename?: string }
   | { type: `source-${string}`; [key: string]: unknown }
   | { type: `data-${string}`; id?: string; data: unknown }
@@ -121,7 +121,7 @@ export interface Decision<Q extends Questions = Questions, R = never> {
 type FetchRequestObject = Extract<FetchRequest, { url: string }>
 
 /** What `decide()` / `decide.openai()` take: the decision, plus any `makeFetchDriver` request keys */
-export type DecideOptions<Q extends Questions> = Omit<FetchRequestObject, 'url' | 'json' | 'body'> & {
+export type DecideOptions<Q extends Questions> = Omit<FetchRequestObject, 'url' | 'json' | 'body' | 'batch' | 'combine' | 'split'> & {
   /** Default '/api/decide' (the app's own route, which holds the API key) */
   url?: string
   /** The decision model, e.g. 'jev-latest' (TypeSafe), 'nimble' (Ollama), 'gpt-6-luna' (OpenAI) */
@@ -131,6 +131,23 @@ export type DecideOptions<Q extends Questions> = Omit<FetchRequestObject, 'url'
   questions: Q
   /** Base64 PNG / JPEG / WebP files shared by every question (models that read images only) */
   images?: readonly string[]
+  /**
+   * D472: more questions than this go as parallel sub-requests (a fetch-driver `batch`), their
+   * replies merged into one (`answers` by name, `usage` summed). Default 64 (Ollama's limit)
+   */
+  maxQuestions?: number
+  /**
+   * D472: split the same way when the estimated prompt of one question (the state plus every
+   * question of the request, as Ollama counts it; the estimate runs high) passes this. Default:
+   * none; a request a server rejects as too large is halved anyway (`split`)
+   */
+  maxPromptTokens?: number
+  /**
+   * false: one request whatever its size, and no halving on a "too large" rejection. Default: on
+   * (a request under the limits is sent as is; a 400 / 413 that names tokens, fields, context, a
+   * limit or "too long / many / large" sends it again in halves, at most 3 deep)
+   */
+  split?: boolean
   /** As a resource: keep the previous `data` on a new request */
   keepPrevious?: boolean
   /** As a resource: refetch every this many ms */
@@ -140,10 +157,15 @@ export type DecideOptions<Q extends Questions> = Omit<FetchRequestObject, 'url'
 }
 
 /** A decision as a `makeFetchDriver` request (POST JSON); its reply is a `Decision<Q, R>` */
-export type DecideRequest<Q extends Questions = Questions, R = never> = Omit<DecideOptions<Q>, 'model' | 'state' | 'questions' | 'images' | 'url'> & {
+export type DecideRequest<Q extends Questions = Questions, R = never> = Omit<DecideOptions<Q>, 'model' | 'state' | 'questions' | 'images' | 'url' | 'maxQuestions' | 'maxPromptTokens' | 'split'> & {
   url: string
   method: 'POST'
+  /** the whole decision (what a test fake answers); over the limits, the parts go in `batch` */
   json: Record<string, unknown>
+  /** D472: the parts of a decision over the limits (sent in parallel, merged by `combine`) */
+  batch?: ReadonlyArray<{ url: string; method: 'POST'; json: Record<string, unknown>; parse?: (response: Response) => any }>
+  combine?: (bodies: any[], requests: any[]) => any
+  split?: (request: any, error: Error & { status?: number; body?: any }) => any[] | null
   /** Type only: the reply's shape (`Decision<Q, R>`); never set */
   readonly __decision?: Decision<Q, R>
 }
@@ -490,6 +512,11 @@ export type ChatRequest<OUT = unknown> = {
    * `ok` gets the validated `value`, a failure is the `error` reply with `issues`
    */
   output?: ChatOutputSchema<OUT>;
+  /**
+   * `false`: the transport still sends `output`'s JSON Schema, but the driver doesn't read the reply:
+   * `ok` has the `text` and no `value` (the caller parses it, e.g. leniently; compose.llm() does)
+   */
+  parse?: false;
   /** The request's key for `latest` and `abort` (default: `ok`, else `error`) */
   key?: string;
   /** A new request aborts the sender's request under the same key (default true) */
@@ -522,7 +549,7 @@ export type ChatRequest<OUT = unknown> = {
 }
 
 /** Stops the sender's requests under a key (`{ abort: 'reply' }`, `{ abort: true, key: 'reply' }`), or all of them (`{ abort: true }`) */
-export type ChatAbort = { abort: string | true; key?: string }
+export type ChatAbort = { abort: string | readonly string[] | true; key?: string }
 
 /** `delta` action data: the reply so far */
 export type ChatDelta = {
@@ -733,6 +760,16 @@ export interface ChatActions {
   DENY: any
   /** The turn is over (a host entry `'assistant.DONE'` runs after the behavior's) */
   DONE: ChatDone
+  /**
+   * PLAN-9 H-1: answer an open client tool call (`clientTools`, or `ask_user`): an
+   * `input-available` client part of the last message (else nothing happens, SYG685). The next
+   * request goes once no call is open. The AI SDK's `addToolOutput`
+   */
+  TOOL_OUTPUT: { toolCallId: string; output: unknown } | { toolCallId: string; errorText: string }
+  /** PLAN-9 H-1: a client tool call opened (a host entry `'assistant.TOOL_CALL'` runs after it, once per call; the AI SDK's `onToolCall`) */
+  TOOL_CALL: ChatCall
+  /** PLAN-9 H-2: a result part answered a card (`compose.answer(props, value)`, heard through CHILD.select): the call's output is `{ part, answer }` */
+  ANSWER: ComposeAnswer
   /** Internal: the prompt field's input */
   PROMPT: string
 }
@@ -759,8 +796,13 @@ export interface ChatOptions {
    * user-entered text named; G-631)
    */
   instructions?: string
-  /** A model id for the requests (overrides the transport's) */
-  model?: string
+  /**
+   * A model id for the requests (overrides the transport's), or a function of the host's state
+   * that returns one, resolved per request: `model: (state) => state.chatModel` lets an app's model
+   * picker switch models with one chat behavior. The default card backend (`ask` without
+   * `backend`) uses it too
+   */
+  model?: string | ((state: any) => string | undefined)
   /**
    * Whose `agent` declarations become tools: by default the host's and its shown descendants'
    * (D249); `false`: none; `[Comp, …]`: only these components' (in the host's subtree)
@@ -770,6 +812,13 @@ export interface ChatOptions {
   maxSteps?: number
   /** Extra request keys for the transport */
   transportOptions?: Record<string, unknown>
+  /**
+   * PLAN-9 H-1: tools the app answers itself: sent with the agent tools (a name in both: the
+   * client tool, SYG684); their calls stay `input-available` until `TOOL_OUTPUT` answers them
+   */
+  clientTools?: Record<string, ChatClientTool>
+  /** PLAN-9 H-2: the `ask_user` tool: the model says what it needs, and the app shows a card built from the catalog */
+  ask?: ChatAskOptions
 }
 
 /**
@@ -1220,3 +1269,589 @@ export interface McpAppDriverOptions {
  *   run(WeatherCard, { MCP: makeMcpAppDriver() })
  */
 export function makeMcpAppDriver(options?: McpAppDriverOptions): (sink$: Stream<McpAppRequest>) => McpAppSource
+
+// ---- PLAN-9 compose ------------------------------------------------------------------------------
+// (worker A: catalogs, layouts, render, the compose behavior, composeWith; B and C add their
+// sub-sections below)
+
+/** A record for a record param: `from: (state) => records` (the value becomes the node key `part:value`) */
+export interface CatalogRecord<V extends string | number = string | number> {
+  value: V
+  name?: string
+  aliases?: string[]
+  description?: string
+}
+
+/** A part's (or container's) param declaration */
+export type CatalogParam =
+  /** an enum: the model picks one option (decisions: a choice, `not_stated` = the default; LLM: an enum) */
+  | { options: Record<string, string>; default?: string; label?: string; ask?: string }
+  /** a number (LLM: a number; decisions: a bin, which names the vague words it covers) */
+  | { type: 'number'; min?: number; max?: number; default?: number; bins?: Record<string | number, string>; label?: string }
+  /** free text: LLM only (a decision model keeps the default; `required` with no default makes the part LLM-only) */
+  | { type: 'text'; maxLength?: number; default?: string; required?: boolean; label?: string }
+  /** a list of short texts: LLM only */
+  | { type: 'list'; items?: { maxLength?: number }; min?: number; max?: number; required?: boolean; default?: readonly string[]; label?: string }
+  /** a record: one node per record (at most one per part) */
+  | { from: (state: any) => ReadonlyArray<CatalogRecord>; label?: string }
+
+/** A param's value type */
+export type CatalogParamValue<P> =
+  P extends { from: (state: any) => ReadonlyArray<{ value: infer V }> } ? V
+  : P extends { options: infer O } ? keyof O & string
+  : P extends { type: 'number' } ? number
+  : P extends { type: 'text' } ? string
+  : P extends { type: 'list' } ? string[]
+  : unknown
+
+/** The params of a part or container declaration, as a layout or tree holds them (all optional: defaults are left out) */
+export type CatalogParamsOf<E> = E extends { params: infer PS } ? { [K in keyof PS]?: CatalogParamValue<PS[K]> } : Record<string, never>
+
+/** A node of a layout */
+export interface LayoutNode {
+  part: string
+  /** only the non-default values */
+  params?: Record<string, unknown>
+  /** a container's slots: node keys in order */
+  slots?: Record<string, string[]>
+}
+
+/**
+ * A composition's layout: a node map whose keys are identities (the part id; `part:recordValue`;
+ * repeats `~2`, `~3`; containers by id: `row`, `row~2`). Plain JSON state.
+ */
+export interface Layout {
+  root: 'page'
+  nodes: Record<string, LayoutNode>
+}
+
+/** A nested tree (what a model writes, what tests use), not tied to a catalog */
+export type ComposeTree = Array<{ part: string; params?: Record<string, unknown>; children?: ComposeTree | Record<string, ComposeTree> }>
+
+type CatalogLens = { get(state: any): any; set?(state: any, value: any): any }
+
+/** A part declaration */
+export interface CatalogPartDecl<STATE = any> {
+  /** a Sygnal component (a child of the host: CHILD.select, lenses, EVENTS and context work) */
+  component?: any
+  /** or a view function, called inline with the props (and `state` read through the lens) */
+  render?: (props: any) => any
+  /** fixed props (params go over them), or `(params, state) => props` */
+  props?: Record<string, any> | ((params: Record<string, any>, state: STATE) => Record<string, any>)
+  /** all a model sees of it: "Noun (what it shows)" */
+  description: string
+  /** its state: a key of the host's state, a lens, or `(node, key) => lens` (a record part: `byId(…)`) */
+  state?: string | CatalogLens | ((node: LayoutNode & { params: Record<string, any> }, key: string) => string | CatalogLens)
+  /** state kept in the composition (`slice.local[nodeKey]`), starting as this */
+  local?: unknown
+  params?: Record<string, CatalogParam>
+  /** where it may go: `'page'`, `'container'` (any slot) or `'container:slot'` (default `['page']`) */
+  in?: string | readonly string[]
+  /** alternatives: the first part of a group in a layout wins */
+  group?: string
+  /** how often one identity may appear (default 1) */
+  maxUses?: number
+  /** always on the page (added by the finishing step; not offered to a model) */
+  required?: boolean
+  pin?: 'start' | 'end'
+  /** parts added right after it */
+  companions?: readonly string[]
+  category?: string
+  /** a part that answers a card (`compose.answer(props, value)`) */
+  result?: boolean
+}
+
+/** What a container's view gets */
+export interface ContainerView {
+  key: string
+  node: LayoutNode
+  /** its params, defaults filled */
+  params: Record<string, any>
+  /** each slot's vnodes */
+  slots: Record<string, any[]>
+  /** every child in order */
+  children: Array<{ key: string; node: LayoutNode; part: CatalogPart | CatalogContainer; slot: string; vnode: any }>
+  /** `slice.ui[key]` */
+  ui: Record<string, any>
+  /** data attributes to spread on an element: a click on it sets `ui[key][name] = value` (the behavior's CONTROL) */
+  control(name: string, value?: unknown): Record<string, string>
+  scope?: string
+  frozen: boolean
+}
+
+/** A container declaration: a view function with named slots (the model never chooses one) */
+export interface CatalogContainerDecl {
+  /** slot name → description (default `{ default: null }`) */
+  slots?: Record<string, string | null>
+  /** fewer filled slots: unwrapped */
+  minSlots?: number
+  /** children per slot: fewer than `min` unwraps it, more than `max` overflow after it (a row splits) */
+  min?: number
+  max?: number
+  /** only parts in its slots */
+  accepts?: 'leaves'
+  /** its order is fixed (no rows inside) */
+  arranged?: boolean
+  direction?: 'row' | 'column'
+  description?: string
+  /** where it may go (default `['page']`) */
+  in?: string | readonly string[]
+  params?: Record<string, CatalogParam>
+  /** a view function, never a component (SYG161) */
+  render?: (view: ContainerView) => any
+}
+
+/** defineCatalog's declaration */
+export interface CatalogDecl {
+  parts: Record<string, CatalogPartDecl>
+  /** `page` and `row` are built in (override their render; `row: false` opts out, as `rows: false` does) */
+  containers?: Record<string, CatalogContainerDecl | false>
+  /** the page's label */
+  description?: string
+  /** `{ id: description }`, named by parts' `category` (a prefilter for large catalogs) */
+  categories?: Record<string, string>
+  /** false: no built-in row (canonical; `containers: { row: false }` too) */
+  rows?: boolean
+  /** quoted in order questions and the LLM prompt */
+  guidance?: string
+  /**
+   * maxParts (default 12): parts on the page. maxDepth (default 4): how deep a container may sit,
+   * the page's children at depth 1; a deeper one moves to the page
+   */
+  limits?: { maxParts?: number; maxDepth?: number }
+  /** app-written few-shot cases (LLM) */
+  examples?: readonly unknown[]
+}
+
+/** A normalized part */
+export interface CatalogPart {
+  id: string
+  kind: 'part'
+  description: string
+  params: Record<string, CatalogParam & { kind: 'options' | 'number' | 'text' | 'list' | 'record' }>
+  /** the record param's name */
+  record?: string
+  /** 'container:slot' entries */
+  in: string[]
+  group?: string
+  maxUses: number
+  required: boolean
+  pin?: 'start' | 'end'
+  companions: string[]
+  category?: string
+  result: boolean
+  decl: CatalogPartDecl
+  [key: string]: any
+}
+
+/** A normalized container */
+export interface CatalogContainer {
+  id: string
+  kind: 'container'
+  slots: Record<string, string | null>
+  slotNames: string[]
+  minSlots?: number
+  min?: number
+  max?: number
+  accepts?: 'leaves'
+  arranged: boolean
+  direction?: 'row' | 'column'
+  description?: string
+  in: string[]
+  params: Record<string, CatalogParam>
+  render: (view: ContainerView) => any
+  decl: CatalogContainerDecl
+}
+
+/** One selectable option: a part, or a record part once per record (`part:value`) */
+export interface CatalogOption { option: string; part: string; params?: Record<string, unknown>; description: string }
+
+type CatalogPartIds<D> = D extends { parts: infer P } ? keyof P & string : string
+type CatalogContainerIds<D> = (D extends { containers: infer C } ? { [K in keyof C & string]: C[K] extends false ? never : K }[keyof C & string] : never) | 'row'
+type CatalogContainerOf<D, C> = D extends { containers: infer CS } ? C extends keyof CS ? CS[C] : {} : {}
+type CatalogSlotsOf<D, C> = CatalogContainerOf<D, C> extends { slots: infer S } ? keyof S & string : 'default'
+type CatalogPartOf<D, P> = D extends { parts: infer PS } ? P extends keyof PS ? PS[P] : never : never
+
+/** A tree node for a catalog: a part with its params, or a container with its children */
+export type CatalogTreeNode<D> =
+  | { [P in CatalogPartIds<D>]: { part: P; params?: CatalogParamsOf<CatalogPartOf<D, P>> } }[CatalogPartIds<D>]
+  | { [C in CatalogContainerIds<D>]: { part: C; params?: CatalogParamsOf<CatalogContainerOf<D, C>>; children?: CatalogTreeNode<D>[] | { [S in CatalogSlotsOf<D, C>]?: CatalogTreeNode<D>[] } } }[CatalogContainerIds<D>]
+
+/** A nested tree for a catalog (part ids, params and slots checked); `ComposeTree` for an untyped one */
+export type CatalogTree<D> = 0 extends (1 & D) ? ComposeTree : CatalogTreeNode<D>[]
+
+/** catalog.render's options */
+export interface ComposeRenderOptions {
+  /** several compositions in one host (one per chat card): instance keys become `scope/nodeKey`; parts get `scope` */
+  scope?: string
+  /** an answered card: wrapped in `<fieldset disabled>`; parts get `frozen` */
+  frozen?: boolean
+  /** a result part's answer: `answer.value` goes to the part whose key is `answer.node` */
+  answer?: { node: string; value: unknown } | null
+  /** the slice's path in the host state (for `local` parts; default: the host key whose value is the slice) */
+  at?: string | ReadonlyArray<string | number>
+}
+
+/** What catalog.render renders: a compose slice, or anything with a layout */
+export type ComposeRenderable = { layout: Layout | null; preview?: Layout | null; ui?: Record<string, Record<string, any>>; local?: Record<string, any> }
+
+/** A catalog (defineCatalog's result); D is the declaration, for typed trees */
+export interface Catalog<D = CatalogDecl> {
+  /** (type only) the declaration */
+  readonly __decl?: D
+  parts: Record<string, CatalogPart>
+  containers: Record<string, CatalogContainer>
+  get(id: string): CatalogPart | CatalogContainer | undefined
+  /** every selectable option for this state */
+  options(state: any): CatalogOption[]
+  /** a record part's records (validated: SYG252) */
+  records(part: string | CatalogPart, state: any): CatalogRecord[]
+  /** the deterministic finishing step (idempotent) */
+  finish(layout: Layout | null | undefined, state?: any): Layout
+  /**
+   * The composition as vnodes for the host's own view: `slice.preview ?? slice.layout`, each part a
+   * child of the host (keyed by its node key), containers through their view functions.
+   */
+  render(slice: ComposeRenderable | null | undefined, state: any, options?: ComposeRenderOptions): any
+  description?: string
+  categories: Record<string, string>
+  rows: boolean
+  guidance?: string
+  limits: { maxParts: number; maxDepth: number }
+  examples: unknown[]
+}
+
+/**
+ * PLAN-9 K-1: a catalog of prepared parts a model composes from, one declaration for both
+ * backends. `catalog.render(state.page, state)` renders a composition.
+ */
+export function defineCatalog<const D extends CatalogDecl>(decl: D): Catalog<D>
+
+/** fromTree(catalog, tree, previous?): a tree → a layout, reusing `previous`'s keys (same params, then same identity) */
+export function fromTree<D>(catalog: Catalog<D>, tree: CatalogTree<D>, previous?: Layout | null): Layout
+/** toTree(layout): the nested tree (keys dropped) */
+export function toTree(layout: Layout | null | undefined): ComposeTree
+/** removeNode(layout, key): the layout without that node and its subtree (not finished) */
+export function removeNode(layout: Layout, key: string): Layout
+
+/** The reply action names a backend's requests carry */
+export interface ComposeNames { ok: string; error: string; delta: string; key: string }
+
+/** A composition backend (`compose.decisions()`, `compose.llm()`, or your own) */
+export interface ComposeBackend {
+  /** the sink its requests go to: 'HTTP' (decisions) or the LLM sink */
+  sink: string
+  start(a: { catalog: Catalog<any>; state: any; prompt: string; previous: Layout | null; names: ComposeNames }): { request: unknown; pending: unknown }
+  /**
+   * a layout (done), `layout: null, unavailable: true` (nothing fits), `request` + `pending` (another
+   * step), or `error`. `keyed: true`: the layout and preview already carry the previous layout's
+   * keys (an edit), so the behavior doesn't re-key them by identity
+   */
+  reply(a: { catalog: Catalog<any>; state: any; pending: any; reply: any; names: ComposeNames }):
+    { layout?: Layout | null; unavailable?: true; preview?: Layout; request?: unknown; pending?: unknown; decisions?: unknown; error?: string; keyed?: boolean }
+  /** `keyed` (on reply too): the layout already has the previous layout's keys (an edit applied to it): the behavior doesn't re-key it */
+  delta?(a: { catalog: Catalog<any>; state: any; pending: any; delta: any }): { preview?: Layout; keyed?: boolean }
+  /** the reply body that leads to `target` (composeWith) */
+  fake(a: { catalog: Catalog<any>; state: any; pending: any; target: ComposeTree }): unknown
+}
+
+export type ComposeStatus = 'idle' | 'composing' | 'preview' | 'done' | 'unavailable' | 'error'
+
+/** The compose behavior's slice: `state.page` for `uses = { page: compose(...) }` */
+export interface ComposeState {
+  prompt: string
+  status: ComposeStatus
+  /** the last finished layout (kept on an error and when nothing fits) */
+  layout: Layout | null
+  /** the layout being built (rendered instead while set) */
+  preview: Layout | null
+  /** the backend's step (plain JSON) */
+  pending: unknown
+  /** what the backend explains (decisions: its answers; LLM: its plan) */
+  decisions: unknown
+  error: string | null
+  /** container state per node key (CONTROL) */
+  ui: Record<string, Record<string, any>>
+  /** `local` parts' state per node key */
+  local: Record<string, any>
+}
+
+/** The compose behavior's actions, as `'<key>.<ACTION>'` on the host */
+export interface ComposeActions {
+  /** compose (an edit of the current layout unless `fresh`): a prompt, `{ prompt, fresh }`, or the form's submit (the slice's prompt) */
+  COMPOSE: string | { prompt: string; fresh?: boolean } | Event | undefined
+  /** set the layout (finished first): restore, undo, the app's own edits; null clears */
+  SET_LAYOUT: Layout | null
+  /** remove a node (by key) and its subtree */
+  REMOVE: string
+  /** a container control: `ui[key][name] = value` */
+  CONTROL: { key: string; name: string; value: unknown }
+  /** a composition finished (a host entry `'page.DONE'` runs after the behavior's) */
+  DONE: Layout
+  /** Internal: the prompt field's input */
+  PROMPT: string
+}
+
+export interface ComposeOptions {
+  /** `compose.decisions({ … })`, `compose.llm({ … })`, or your own ComposeBackend */
+  backend: ComposeBackend
+  /** the form whose submit composes */
+  form?: BehaviorTarget
+  /** the prompt field (its input sets `prompt`) */
+  prompt?: BehaviorTarget
+  /** the request lane (default 'compose'): a new prompt aborts the step in flight */
+  key?: string
+}
+
+/** A result part's PARENT value (`compose.answer(props, value)`) */
+export interface ComposeAnswer<V = unknown> { scope: string | undefined; node: string | undefined; value: V }
+
+/**
+ * PLAN-9 C-1: compose a page from a catalog. `uses = { page: compose(catalog, { backend:
+ * compose.decisions({ model }), form: '.ask', prompt: '.prompt' }) }`, rendered with
+ * `catalog.render(state.page, state)`.
+ */
+export const compose: {
+  (catalog: Catalog<any>, options: ComposeOptions): Behavior<ComposeState, ComposeActions, {}, ComposeOptions>
+  /** a decision-model backend (decide() on HTTP) */
+  decisions(options?: ComposeDecisionsOptions): ComposeBackend
+  /** a chat-LLM backend (structured output on the LLM sink) */
+  llm(options?: ComposeLlmOptions): ComposeBackend
+  /** a result part's PARENT value: `{ scope, node, value }` */
+  answer<V>(props: { scope?: string; node?: string }, value: V): ComposeAnswer<V>
+  /**
+   * PLAN-9 C-2: the `agent.actions` entry that lets an agent (a chat assistant) compose the page:
+   * `actions: { ...compose.action('page') }` offers `<agent name>_page_compose({ prompt, fresh? })`;
+   * its result waits (`until`) for the composition to finish, so its `state` (the `read`) shows the
+   * new page (`read: (s) => ({ page: compose.summary(s.page) })`). `timeout` default 60 s
+   */
+  action<K extends string = 'page'>(key?: K, options?: { description?: string; timeout?: number }): Record<`${K}.COMPOSE`, AgentAction<any, { prompt: string; fresh?: boolean }>>
+  /** PLAN-9 C-2: a composition as an agent's `read` shows it: its status, the layout as a tree, the error */
+  summary(slice: ComposeState | null | undefined): { status: ComposeStatus; page: ComposeTree; error?: string } | undefined
+}
+
+/**
+ * PLAN-9 T-1: answer the pending composition of `catalog` so that it becomes `tree`, whatever the
+ * backend (each step through the backend's fake reply). `stream: n` streams an LLM reply in n chunks.
+ */
+export function composeWith<D>(t: RenderResult<any>, catalog: Catalog<D>, tree: CatalogTree<D>, options?: { stream?: number | boolean }): Promise<void>
+
+// PLAN-9 B: compose.decisions
+/** `compose.decisions(options)`: the decision-model backend (`decide()` on the HTTP sink) */
+export interface ComposeDecisionsOptions {
+  /** the decision endpoint (default '/api/decide': the app's own route, which holds the API key) */
+  url?: string
+  /** the decision model ('jev-latest', 'nimble', …); without one: SYG681 (dev) */
+  model?: string
+  /** the request lane (`key` of every `decide()` request; default: the behavior's, 'compose') */
+  key?: string
+  /**
+   * rows: the mean side-by-side probability two groups of parts need to join one row
+   * (average-linkage clustering of the `beside_` answers; default 0.25, measured on Jev; 0.5 suits nimble)
+   */
+  rowMean?: number
+  /**
+   * ask which part `categories` the request is about first, then only about their parts (one more
+   * call, about half the input tokens; measured on Jev's 50-part ops console: the same accuracy).
+   * 'auto' (default): on when the catalog has categories and more than 60 parts to choose from
+   * (30 with `profile: 'small'`); `true`: always (with categories); `false`: never
+   */
+  prefilter?: boolean | 'auto'
+  /**
+   * the most options one choice question may have (default 255; 25 when `url` looks like Ollama;
+   * at least 4): every larger choice is split into chunks that repeat its head options
+   */
+  maxOptions?: number
+  /**
+   * 'small': for a local ~9B decision model such as Ollama's nimble, which favours the first of two
+   * options: pairwise order questions are asked in both orders, and near-ties follow the order in
+   * which the request names the parts (G-755); at most 8 parts per composition (`maxParts`); the
+   * category prefilter from 30 parts
+   */
+  profile?: 'small'
+  /**
+   * the most parts one composition selects (the most probable kept; required parts and companions
+   * come on top). Default: the catalog's `limits.maxParts` (12); 8 with `profile: 'small'`. The
+   * catalog's limit still caps the page
+   */
+  maxParts?: number
+  /** passed to every `decide()` request (D472): see `DecideOptions`. Default 64 */
+  maxQuestions?: number
+  /** passed to every `decide()` request (D472): see `DecideOptions`. Default: none */
+  maxPromptTokens?: number
+  /** passed to every `decide()` request (D472): false sends each step as one request, never halved */
+  split?: boolean
+}
+/**
+ * the decisions backend: plain-JSON `pending` steps (`'categories'`, `'select'`, `'layout'`; for an
+ * edit of a previous layout, B-4: `'edit'`, then `'where'` when something moves or is added)
+ */
+export interface ComposeDecisionsBackend {
+  sink: 'HTTP'
+  kind: 'decisions'
+  start(a: { catalog: any; state: any; prompt: string; previous: any; names: { ok: string; error: string; delta?: string; key?: string } }): { request: DecideRequest<any>; pending: any }
+  reply(a: { catalog: any; state: any; pending: any; reply: any; names: { ok: string; error: string; delta?: string; key?: string } }): {
+    layout?: any; unavailable?: true; preview?: any; request?: DecideRequest<any>; pending?: any
+    /** a reply that can't be read (no `answers`, or every answer outside its options: SYG682); the behavior's status 'error' */
+    error?: string
+    /**
+     * the raw answers per step (`{ select, layout }`, plus `categories` with `prefilter`; an edit:
+     * `{ edit, where }`), for an explain panel: question name → `{ choice, probabilities }`. Names
+     * an explain panel can rely on (`<p>` a part id, `<k>` an element of the layout step):
+     * select: `use_<p>` (omit / use), `count_<p>`, `pick_<group>`, `rec_<p>__<n>` (the n-th record
+     * slot, n = 1..4: none or a record), `param_<p>__<param>` (not_stated = the default), `row`;
+     * layout: `parent_<k>`, `beside_<k>`, `first_<a>_vs_<b>`, `left_<a>_vs_<b>`, `same_<a>_vs_<b>`,
+     * `gap_<x>_in_<p>`; categories: `cat_<category>`; edit: `remove_<node>`, `set_<node>__<param>`,
+     * `add_<p>`, `moved_<n>`; where: `where_<node>`. A choice split by `maxOptions` shows as its
+     * chunks, `<name>__c<k>` (each repeats the head options: not_stated, keep, none, omit)
+     */
+    decisions?: Record<string, Record<string, any>>
+    /** an edit's layout and preview keep the previous layout's keys (the behavior uses them as they are) */
+    keyed?: boolean
+  }
+  /** the decision reply that makes the pending step read as `target` (composeWith); throws when the encoding can't reach it */
+  fake(a: { catalog: any; state: any; pending: any; target: any[] }): Decision<any>
+}
+
+// PLAN-9 C: compose.llm ------------------------------------------------------------------------
+
+/**
+ * `compose.llm(options?)`: the GenAI LLM backend of `compose` (one structured-output request on
+ * a makeChatDriver() sink; a streamed preview). The request carries the catalog's JSON Schema
+ * (`asked_for`, then the layout tree), the system prompt (the catalog as text, its `guidance`,
+ * `examples` as few-shot turns) and `delta` when streaming. Other keys go on the request as is
+ * (transport options such as `body: { temperature: 0 }`). Requests carry `parse: false`: the reply
+ * text is read leniently here (prose or a code fence around the JSON), and text with no layout in
+ * it is the behavior's status 'error' (SYG683), not the driver's FAILED.
+ *
+ * B-4: with a current layout, COMPOSE is an edit. The request sends the page (`n1: part params`,
+ * one node per line) and the change; the model returns operations positioned by named places
+ * (`add` / `remove` / `move` / `replace` / `setParams`; `top`, `bottom`, `above n2`, `left of n3`,
+ * …), applied to the current layout itself: every node they don't replace or remove keeps its key
+ * (a param change too; another record is another node), a replacement takes the old node's place,
+ * and the node a place names never moves. No operation: `unavailable`, the layout stays.
+ *
+ *   compose(catalog, { backend: compose.llm({ model: 'gpt-5-mini' }) })
+ */
+export interface ComposeLlmOptions {
+  /** The model id (default: the transport's), or a function of the host's state that returns one, resolved per request */
+  model?: string | ((state: any) => string | undefined)
+  /** The chat driver's sink (default 'LLM') */
+  sink?: string
+  /** The request key (default: the behavior's key) */
+  key?: string
+  /** Stream a preview of the complete parts so far (default true) */
+  stream?: boolean
+  /** Ask for the `asked_for` plan before the tree (default true; false when there are examples) */
+  plan?: boolean
+  /** More instructions after the rules, or a function of the system prompt returning the one to send */
+  instructions?: string | ((prompt: string) => string)
+  /** Few-shot examples (default: the catalog's): `[prompt, tree, asked_for?]` or `{ prompt, tree, asked_for? }` */
+  examples?: ReadonlyArray<readonly [string, ReadonlyArray<ComposeLlmTreeNode>, ReadonlyArray<string>?] | { prompt: string; tree: ReadonlyArray<ComposeLlmTreeNode>; asked_for?: ReadonlyArray<string> }>
+  /** Transport options, sent on the request as is */
+  [option: string]: unknown
+}
+
+/** A node of a layout tree as `examples` take it (the contract's Tree) */
+export type ComposeLlmTreeNode = { part: string; params?: Record<string, unknown>; children?: ReadonlyArray<ComposeLlmTreeNode> | Record<string, ReadonlyArray<ComposeLlmTreeNode>> }
+
+/** What `compose.llm()` puts in the slice's `decisions`: the model's plan and what the repair fixed */
+export interface ComposeLlmDecisions {
+  /** Each thing the request asks for, in the model's words (with `plan`) */
+  asked_for?: string[]
+  /** What the repair changed: `alias`, `duplicate`, `param`, `structure`, `unknownPart`, `required`, `invalid`; `op` for an edit's operations */
+  repairs?: Array<{ kind: string; detail: string }>
+  /** An edit: the operations as applied, with layout keys (an add's `node` is the new key) */
+  ops?: Array<{ op: 'add' | 'remove' | 'move' | 'replace' | 'setParams'; node: string; part?: string; params?: Record<string, unknown>; where?: string; moved?: string }>
+}
+
+// ---- PLAN-9 H: chat client tools and ask ---------------------------------------------------------
+
+/** PLAN-9 H-1: a tool the app answers (`chat({ clientTools: { name: tool } })`) */
+export interface ChatClientTool {
+  description: string
+  /** The input's JSON Schema, or a Standard Schema with a JSON Schema form (its input is validated: a failure closes the call with the issues, so the model can repair it) */
+  inputSchema: JsonSchemaObject | AgentSchema<any>
+}
+
+/** PLAN-9 H-2: `chat({ ask })` */
+export interface ChatAskOptions {
+  /** The parts a card is built from; parts with `result: true` answer it (none: SYG686) */
+  catalog: Catalog<any>
+  /** What composes the card from the call's `need` and the app state: `compose.llm()` (default, on the chat's sink) or `compose.decisions()` */
+  backend?: ComposeBackend
+  /** More guidance on when and how to ask, added to the `ask_user` tool's description */
+  instructions?: string
+  /** PLAN-9 H-3: the tool's input is the card (the layout schema; LLM only, for providers that enforce tool schemas): no compose round trip */
+  direct?: boolean
+}
+
+/** 'composing' (queued, or its backend step is out) | 'open' (answerable) | 'answered' | 'failed' (the call closed with "could not show a card: …") | 'cancelled' (STOP, a new message) */
+export type ChatCardStatus = 'composing' | 'open' | 'answered' | 'failed' | 'cancelled'
+
+/** PLAN-9 H-2: an `ask_user` call's card, on its tool part (`part.ui`); render it with `askCard()` */
+export interface ChatCard {
+  status: ChatCardStatus
+  /** The card (a decision backend's preview while it composes) */
+  layout: Layout | null
+  /** State of the card's `local` parts, per node key */
+  local: Record<string, any>
+  /** Container state per node key (CONTROL) */
+  ui: Record<string, Record<string, any>>
+  /** The answer: the result part's node, its part id, the value */
+  answer: { node: string; part: string | null; value: unknown } | null
+  /** The backend's step while its request is out */
+  pending?: unknown
+  /**
+   * What the backend explains, as a compose slice's `decisions`: its last reply's (`compose.llm()`:
+   * ComposeLlmDecisions; `compose.decisions()`: the answers per step, see ComposeDecisionsBackend).
+   * Absent until a reply carries some; kept (and persisted) with the card, for an explain panel
+   */
+  decisions?: unknown
+}
+
+/** A tool part of a chat message */
+export type ChatToolPart = Extract<MessagePart, { toolCallId: string }>
+
+/**
+ * PLAN-9 H-1: the `input-available` tool parts of the last assistant message: the calls waiting for
+ * the app's answer (and agent calls while they run: status 'streaming')
+ */
+export function openToolCalls(state: ChatState): ChatToolPart[]
+
+/**
+ * PLAN-9 H-2: the card of an `ask_user` tool part, for the host's view: `catalog.render(part.ui,
+ * state, { scope: part.toolCallId, frozen, answer })`, frozen unless the card is open, `local`
+ * written through a lens to the part. `key`: the chat's key in `uses` (default 'assistant'). Null
+ * while the card has no layout.
+ */
+export function askCard(catalog: Catalog<any>, state: any, part: ChatToolPart, options?: { key?: string }): any
+
+/** PLAN-9 M-1: `<Composed>`'s props */
+export interface ComposedProps {
+  /** the catalog (defineCatalog's result); missing: SYG451, nothing rendered */
+  catalog: Catalog<any>
+  /**
+   * Where the composition is in the host's state: a key (default 'page') or a path
+   * (['boards', 0, 'page']); with `card`, the chat's key (default 'assistant'). Not a composition
+   * (an object with `layout`): SYG451, nothing rendered
+   */
+  from?: string | ReadonlyArray<string | number>
+  /** an `ask_user` tool part: its card, as askCard() renders it (scope, frozen and answer from the part) */
+  card?: ChatToolPart
+  /** as catalog.render's options (they override the card's) */
+  scope?: string
+  frozen?: boolean
+  answer?: { node: string; value: unknown } | null
+  key?: string | number
+}
+
+/**
+ * PLAN-9 M-1 (D466): `<Composed catalog={catalog} from="page" />` renders the composition at `from`
+ * in the host's state, as `{catalog.render(state.page, state)}` in the view does: the parts are the
+ * host's children (same keys, CHILD.select, lenses). Differences: it reads the host's own state (a
+ * composition computed in the view needs render()), and a container view or part `props()` that
+ * throws replaces only the composition with the host's `onError` (SYG408), where render() shows an
+ * empty `.compose-error` element (SYG406).
+ */
+export function Composed(props: ComposedProps): JSX.Element