sygnal 6.2.0 → 6.3.0

package/src/extra/ai/chat/behavior.ts

@@ -57,10 +57,47 @@
  * the host's dispose stops it. A host in an app made before the first chat() call is reported as
  * SYG442 and runs without tools. The engine dispatches RESULTS / ASK (cause 'reply') and DONE
  * ('next') to the host through the runtime API.
+ *
+ * PLAN-9 H-1, client tools (design: dev-plans/research/ai-compose/chat-client-tools.md, D454,
+ * D469): `clientTools: { name: { description, inputSchema } }` go in every request with the agent
+ * tools (a name in both: the client tool wins, SYG684; they need no link, so they work under
+ * SYG442 too). The app answers their calls:
+ * - a reply's client calls stay `input-available` (a Standard Schema input that fails validation
+ *   is closed at once as output-error with the issues, so the model can repair it), and each fires
+ *   the host entry 'assistant.TOOL_CALL' (ChatCall) once, when it opens;
+ * - 'assistant.TOOL_OUTPUT' `{ toolCallId, output }` / `{ toolCallId, errorText }` (the AI SDK's
+ *   addToolOutput) answers one: only an input-available client part of the last message (checked
+ *   on state, so it works after a reload); anything else does nothing (SYG685, dev);
+ * - the next request goes once the last message has no input-available and no approval-requested
+ *   part: RESULTS, APPROVE / DENY, TOOL_OUTPUT, ANSWER and the cards share that one test, so
+ *   whichever finishes last sends (`continue: true`; it counts as a step);
+ * - status: 'ready' while only the user's answers are outstanding (DONE waits for the end of the
+ *   turn), 'streaming' while agent calls run or a card composes;
+ * - STOP (also when only client calls are open) closes them as "not answered: stopped by the
+ *   user", SEND as "not answered: the user sent a new message"; REGENERATE drops them with their
+ *   message; past maxSteps they are closed as not run.
+ * `openToolCalls(state)`: the input-available tool parts of the last assistant message.
+ *
+ * PLAN-9 H-2 / H-3: `ask: { catalog, backend?, instructions?, direct? }` adds the client tool
+ * `ask_user` (../compose/ask.ts, reached through `catalog._ask`): a card per call on `part.ui`,
+ * composed one at a time on the backend's sink (default compose.llm() on this sink; CARD /
+ * CARD_FAILED are its reply actions, the request key `<use>.ask:<toolCallId>`), answered by the
+ * catalog's result parts (ANSWER `{ scope, node, value }`: CHILD.select of their components, since
+ * cards render in the host's view) with the output `{ part, answer }`; CONTROL for the cards'
+ * container controls. STOP aborts a card being composed (the driver's `abort: [keys]`).
+ *
+ * Reload (design rule 12): `persist()` restores the whole slice, so a slice saved mid-request came
+ * back busy and SEND stayed locked. RESUME, once at start when the restored slice is busy (or has a
+ * card composing): status 'ready' (the partial reply kept, as on STOP), agent calls still open
+ * closed as not run, an app confirm dropped (a server approval stays answerable), and a card that
+ * was composing composed again; open client calls stay answerable.
  */
 import {defineBehavior} from '../../behaviors'
 import {ABORT} from '../../../shared'
+import {report} from '../../diagnostics/index'
+import xs from '../../xstreamCompat'
 import {agentTools, hasUserText, labelsUntrusted, unlabel} from '../agent/index'
+import {toJsonSchema, repair, isObj} from '../schema/index'
 import {linked, engineOf, checkLinked} from '../link'
 import {messageId} from '../messages'
 
@@ -84,6 +121,9 @@ const toolsOf = (e: Engine) => e.o.agent === false ? null : e.tools ||= agentToo
   }),
 })
 
+// dev diagnostics (SYG684, SYG685): no-ops with diagnostics off
+const dev = (code: string, message: string, fix: string) => { try { report(code, {component: 'chat', message, fix, severity: 'warn'}) } catch (e) { queueMicrotask(() => { throw e }) } }
+
 // ------------------------------------------------------------------ messages
 const isTool = (p: any) => typeof p?.type == 'string' && p.type.startsWith('tool-')
 const openCalls = (m: any): any[] => (m?.parts || []).filter((p: any) => isTool(p) && p.state == 'input-available')
@@ -102,16 +142,23 @@ const withResult = (p: any, r: any) => {
   const {output: _o, errorText: _e, ...rest} = p
   return 'error' in r ? {...rest, state: 'output-error', errorText: r.error} : {...rest, state: 'output-available', output: r.output}
 }
+/** H-1: the tool parts the app answers (clientTools, ask_user) */
+type Cfg = {client: Record<string, any>; ask?: any; kit?: any}
+const isClient = (c: Cfg, p: any) => Object.prototype.hasOwnProperty.call(c.client, p.type.slice(5))
+/** an ask_user card that is still composing / open → cancelled */
+const cancel = (p: any) => p.ui && (p.ui.status == 'composing' || p.ui.status == 'open') ? {...p.ui, status: 'cancelled', pending: null} : p.ui
 /**
  * The last message with its open tool parts closed (a turn stopped, failed or capped): a call
- * that already ran gets its result (`ran`, G-626), the others `why`; a server approval still
- * waiting is denied
+ * that already ran gets its result (`ran`, G-626), the others `why` (client calls `cwhy`, their
+ * cards cancelled); a server approval still waiting is denied
  */
-const closeOpen = (msgs: any[], why: string, ran?: Map<string, any>) => {
+const closeOpen = (msgs: any[], why: string, ran?: Map<string, any>, c?: Cfg, cwhy = why) => {
   const m = msgs[msgs.length - 1]
   if (!openCalls(m).length && !firstAsk(m)) return msgs
   return [...msgs.slice(0, -1), {...m, parts: m.parts.map((p: any) => !isTool(p) ? p
-    : p.state == 'input-available' ? (ran?.has(p.toolCallId) ? withResult(p, ran.get(p.toolCallId)) : {...p, state: 'output-error', errorText: why})
+    : p.state == 'input-available' ? (ran?.has(p.toolCallId) ? withResult(p, ran.get(p.toolCallId))
+      : c && isClient(c, p) ? {...p, state: 'output-error', errorText: cwhy, ...(p.ui && {ui: cancel(p)})}
+      : {...p, state: 'output-error', errorText: why})
     : p.state == 'approval-requested' ? {...p, state: 'output-denied', approval: {...p.approval, approved: false, reason: why}}
     : p)}]
 }
@@ -120,61 +167,213 @@ const user = (text: string) => ({id: messageId(), role: 'user', parts: [{type: '
 const busy = (s: any) => s.status == 'submitted' || s.status == 'streaming'
 const lastUser = (msgs: any[]) => { for (let i = msgs.length - 1; i >= 0; i--) if (msgs[i].role == 'user') return i; return -1 }
 const lastOf = (msgs: any[]) => msgs[msgs.length - 1]
+/** the last message's parts through `f` (an assistant message; otherwise unchanged) */
+const mapLast = (msgs: any[], f: (p: any) => any) => {
+  const m = lastOf(msgs)
+  return m?.role != 'assistant' ? msgs : [...msgs.slice(0, -1), {...m, parts: m.parts.map(f)}]
+}
+/** the input-available tool parts of the last assistant message (H-1: the calls the app answers, and agent calls while they run) */
+export const openToolCalls = (s: any): any[] => { const m = s && Array.isArray(s.messages) ? lastOf(s.messages) : null; return m?.role == 'assistant' ? openCalls(m) : [] }
+const composing = (p: any) => p.state == 'input-available' && p.ui?.status == 'composing'
+
+/**
+ * H-1 rule 3 and 4: what the slice does after a call closed or a card changed: the next request
+ * (`send`) once nothing is open, else the status: 'streaming' while agent calls run or a card
+ * composes (or a server approval waits), 'ready' while only the user's answers are outstanding
+ */
+const settle = (s: any, messages: any[], c: Cfg) => {
+  const last = lastOf(messages), ask = firstAsk(last), open = openCalls(last)
+  if (!ask && !open.length) return {s: {...s, messages, status: 'submitted', pending: null}, send: true}
+  const agent = open.some(p => !isClient(c, p))
+  const working = ask || agent || open.some(composing)
+  return {s: {...s, messages, status: working ? 'streaming' : 'ready', pending: ask ? askInfo(ask) : agent && s.pending?.approvalId === undefined ? s.pending : null}}
+}
 
-/** one step's outcome per (slice, data): STATE and the LLM sink of an action read the same one */
-const memo = (f: (s: any, d: any, e?: Engine) => any) => {
+/** H-2: start the first queued card (cards compose one at a time); a card that can't start fails and the next one goes */
+const nextCard = (c: Cfg, msgs: any[], st: any, k: string): {msgs: any[]; request?: any} => {
+  if (!c.ask || !c.ask.backend) return {msgs}
+  for (;;) {
+    const m = lastOf(msgs), parts = m?.role == 'assistant' ? m.parts : []
+    if (parts.some((p: any) => composing(p) && p.ui.pending)) return {msgs}
+    const p = parts.find(composing)
+    if (!p) return {msgs}
+    const r = c.kit.startCard(c.ask, p, st, k), np = r.part ?? r
+    msgs = mapLast(msgs, (x: any) => x === p ? np : x)
+    if (r.request !== undefined) return {msgs, request: r.request}
+  }
+}
+
+/**
+ * one step's outcome per (slice, data, engine, host): STATE, the sinks and EFFECT of an action
+ * read the same one (`x`: the host's state and the use's key, compared by value)
+ */
+const memo = (f: (s: any, d: any, e?: any, x?: any) => any) => {
   let l: any[] = []
-  return (s: any, d: any, e?: Engine) => l[0] === s && l[1] === d && l[2] === e ? l[3] : (l = [s, d, e, f(s, d, e)])[3]
+  return (s: any, d: any, e?: any, x?: any) => l[0] === s && l[1] === d && l[2] === e && l[3] === x?.state && l[4] === x?.k ? l[5] : (l = [s, d, e, x?.state, x?.k, f(s, d, e, x)])[5]
+}
+
+/**
+ * H-1: a client call's Standard Schema input, checked synchronously (the lenient `{ value }`
+ * unwrap and repair, as A-1's parseInput): `{ input }` or `{ issues }`; an async schema or a plain
+ * JSON Schema is not checked here
+ */
+function checkInput(tool: any, input: any): {input?: any; issues?: string} {
+  const sc = tool?.inputSchema
+  if (!sc || typeof sc['~standard']?.validate != 'function') return {input}
+  const c = toJsonSchema(sc)
+  let v = c.wrapped && isObj(input) && 'value' in input ? input.value : input
+  if (c.schema) v = repair(v, c.wrapped ? c.schema.properties.value : c.schema, c.schema)
+  const r = sc['~standard'].validate(v)
+  if (!r || typeof r.then == 'function') return {input}
+  return r.issues ? {issues: r.issues.map((i: any) => (i.path?.length ? i.path.map((x: any) => isObj(x) ? x.key : x).join('.') + ': ' : '') + i.message).join('; ')} : {input: r.value}
+}
+/** the JSON Schema a request sends for a client tool */
+const schemaOf = (tool: any) => {
+  const sc = tool?.inputSchema
+  if (sc && typeof sc['~standard']?.validate == 'function') return toJsonSchema(sc).schema ?? {type: 'object'}
+  return sc ?? {type: 'object'}
 }
 
 const textOf = (d: any) => typeof d == 'string' ? d : d && typeof d == 'object' && typeof d.text == 'string' && !('target' in d) ? d.text : undefined
-const sendStep = /*#__PURE__*/ memo((s, d) => {
-  const given = textOf(d), text = given ?? s.prompt
-  if (busy(s) || typeof text != 'string' || !text.trim()) return
-  return {...s, messages: [...closeOpen(s.messages, 'not run: a new message was sent'), user(text)], prompt: given === undefined ? '' : s.prompt, draft: '', draftReasoning: '', status: 'submitted', error: null, pending: null}
-})
-const regenStep = /*#__PURE__*/ memo(s => {
-  const i = lastUser(s.messages)
-  if (busy(s) || i < 0) return
-  return {...s, messages: s.messages.slice(0, i + 1), draft: '', draftReasoning: '', status: 'submitted', error: null, pending: null}
-})
-// a reply: run its open tool calls (status stays streaming), wait for a server approval
-// (`pending`), or the turn is over (DONE). Past maxSteps the open calls are closed as not run. A
-// reply to a request that continued the last (assistant) message replaces it (G-628: the driver
-// grew that message, as the AI SDK does)
-const replyStep = /*#__PURE__*/ memo((s, d, e) => {
-  const m = d?.message
-  if (!m) return
-  const max = e?.o.maxSteps ?? 8, calls = openCalls(m), run = calls.length > 0 && !!e && e.steps < max
-  const msg = calls.length && !run ? closeOpen([m], `not run: the step limit (maxSteps ${max}) was reached`)[0] : m
-  const ask = !run && firstAsk(msg)
-  const prev = lastOf(s.messages), messages = prev?.role == 'assistant' ? [...s.messages.slice(0, -1), msg] : [...s.messages, msg]
-  return {s: {...s, messages, draft: '', draftReasoning: '', status: run || ask ? 'streaming' : 'ready', pending: ask ? askInfo(ask) : null}, calls: run ? calls : null, ask: !!ask, msg}
-})
-// a reply's tool results: the next request (or the next server approval first). `late`: a call
-// that was running when STOP came changed the app: its "not run" part gets the result (G-626)
-const resultsStep = /*#__PURE__*/ memo((s, d, e) => {
-  if (!e || !Array.isArray(d?.results) || (d.turn !== e.turn && !d.late)) return
-  const out = new Map(d.results.map((r: any) => [r.id, r]))
-  const fix = (p: any) => {
-    const r: any = isTool(p) && out.get(p.toolCallId)
-    return !r ? p : d.late ? (p.state == 'output-error' && /^not run/.test(p.errorText) ? withResult(p, r) : p) : p.state == 'input-available' ? withResult(p, r) : p
+/** steps that read the use's client config; made per chat() call */
+function steps(c: Cfg, o: any) {
+  const sendStep = memo((s, d) => {
+    const given = textOf(d), text = given ?? s.prompt
+    if (busy(s) || typeof text != 'string' || !text.trim()) return
+    return {...s, messages: [...closeOpen(s.messages, 'not run: a new message was sent', undefined, c, 'not answered: the user sent a new message'), user(text)], prompt: given === undefined ? '' : s.prompt, draft: '', draftReasoning: '', status: 'submitted', error: null, pending: null}
+  })
+  const regenStep = memo(s => {
+    const i = lastUser(s.messages)
+    if (busy(s) || i < 0) return
+    return {...s, messages: s.messages.slice(0, i + 1), draft: '', draftReasoning: '', status: 'submitted', error: null, pending: null}
+  })
+  // a reply: run its agent calls (status stays streaming), open its client calls (TOOL_CALL; cards
+  // start composing), wait for a server approval (`pending`), or the turn is over (DONE). Past
+  // maxSteps the open calls are closed as not run. A reply to a request that continued the last
+  // (assistant) message replaces it (G-628: the driver grew that message, as the AI SDK does)
+  const replyStep = memo((s, d, e, p) => {
+    const m = d?.message
+    if (!m) return
+    const max = e?.o.maxSteps ?? 8, calls = openCalls(m), over = !!e && e.steps >= max
+    const agent = calls.filter(x => !isClient(c, x)), run = agent.length > 0 && !!e && !over
+    // past maxSteps every call is closed; with no engine (SYG442) the agent calls are
+    let msg = calls.length && (over || (!e && agent.length)) ? closeOpen([m], `not run: the step limit (maxSteps ${max}) was reached`, undefined, over ? undefined : c)[0] : m
+    const opened: any[] = []
+    let closed = false
+    if (!over && calls.length > agent.length) {
+      msg = {...msg, parts: msg.parts.map((x: any) => {
+        if (!isTool(x) || x.state != 'input-available' || !isClient(c, x)) return x
+        const name = x.type.slice(5), call = {id: x.toolCallId, name, input: x.input}
+        let y = x
+        if (c.ask && name == 'ask_user') y = c.kit.openCard(c.ask, x, p?.state)
+        else {
+          const r = checkInput(c.client[name], x.input)
+          if (r.issues) y = {...x, state: 'output-error', errorText: `Invalid input: ${r.issues}`}
+          else call.input = r.input
+        }
+        if (y.state == 'input-available') opened.push(call)
+        else closed = true
+        return y
+      })}
+    }
+    const ask = !run && firstAsk(msg)
+    const prev = lastOf(s.messages)
+    let messages = prev?.role == 'assistant' ? [...s.messages.slice(0, -1), msg] : [...s.messages, msg]
+    const card = nextCard(c, messages, p?.state, p?.k)
+    messages = card.msgs
+    const last = lastOf(messages), wait = openCalls(last).filter(x => isClient(c, x))
+    const send = !run && !ask && !wait.length && closed
+    const status = send ? 'submitted' : run || ask || wait.some(composing) ? 'streaming' : 'ready'
+    return {s: {...s, messages, draft: '', draftReasoning: '', status, pending: ask ? askInfo(ask) : null}, calls: run ? agent : null, ask: !!ask, msg: last, wait: wait.length > 0, send, opened, compose: card.request}
+  })
+  // a reply's tool results: the next request (or the next server approval first). `late`: a call
+  // that was running when STOP came changed the app: its "not run" part gets the result (G-626)
+  const resultsStep = memo((s, d, e) => {
+    if (!e || !Array.isArray(d?.results) || (d.turn !== e.turn && !d.late)) return
+    const out = new Map(d.results.map((r: any) => [r.id, r]))
+    const fix = (p: any) => {
+      const r: any = isTool(p) && out.get(p.toolCallId)
+      return !r ? p : d.late ? (p.state == 'output-error' && /^not run/.test(p.errorText) ? withResult(p, r) : p) : p.state == 'input-available' ? withResult(p, r) : p
+    }
+    const msgs = s.messages.map((m: any) => m.role == 'assistant' && m.parts?.some((p: any) => out.has(p.toolCallId)) ? {...m, parts: m.parts.map(fix)} : m)
+    if (d.late) return {s: {...s, messages: msgs}}
+    return settle(s, msgs, c)
+  })
+  // APPROVE / DENY of a server approval (G-628): the part goes to approval-responded, as the AI
+  // SDK's addToolApprovalResponse does; once none waits, the conversation is sent again and the
+  // server runs (or skips) the call, continuing the same message
+  const answerStep = memo((s, ok) => {
+    const id = s.pending?.approvalId, last = lastOf(s.messages)
+    if (id === undefined || last?.role != 'assistant') return
+    return settle(s, mapLast(s.messages, (p: any) => isTool(p) && p.state == 'approval-requested' && p.approval?.id === id ? {...p, state: 'approval-responded', approval: {...p.approval, approved: ok}} : p), c)
+  })
+  /** the input-available client part `id` of the last assistant message, or undefined (SYG685) */
+  const openPart = (s: any, id: any, what: string, guard = (_p: any) => true) => {
+    const p = openToolCalls(s).find(x => x.toolCallId === id && isClient(c, x) && guard(x))
+    if (!p) dev('SYG685', `${what} for the tool call '${id}', which is not waiting for an answer (answered, closed, or not a client tool call of the last message); it is ignored`, 'Answer only the calls in openToolCalls(state); a late answer after STOP, SEND or REGENERATE is dropped on purpose')
+    return p
   }
-  const msgs = s.messages.map((m: any) => m.role == 'assistant' && m.parts?.some((p: any) => out.has(p.toolCallId)) ? {...m, parts: m.parts.map(fix)} : m)
-  if (d.late) return {s: {...s, messages: msgs}}
-  const ask = firstAsk(lastOf(msgs))
-  return {s: {...s, messages: msgs, status: ask ? 'streaming' : 'submitted', pending: ask ? askInfo(ask) : null}, send: !ask}
-})
-// APPROVE / DENY of a server approval (G-628): the part goes to approval-responded, as the AI
-// SDK's addToolApprovalResponse does; once none waits, the conversation is sent again and the
-// server runs (or skips) the call, continuing the same message
-const answerStep = /*#__PURE__*/ memo((s, ok) => {
-  const id = s.pending?.approvalId, last = lastOf(s.messages)
-  if (id === undefined || last?.role != 'assistant') return
-  const parts = last.parts.map((p: any) => isTool(p) && p.state == 'approval-requested' && p.approval?.id === id ? {...p, state: 'approval-responded', approval: {...p.approval, approved: ok}} : p)
-  const msgs = [...s.messages.slice(0, -1), {...last, parts}], ask = firstAsk(lastOf(msgs))
-  return {s: {...s, messages: msgs, pending: ask ? askInfo(ask) : null, status: ask ? 'streaming' : 'submitted'}, send: !ask}
-})
+  /** after a call closed or a card changed: the next queued card, then rule 3 */
+  const after = (s: any, msgs: any[], x: any) => { const n = nextCard(c, msgs, x?.state, x?.k); return {...settle(s, n.msgs, c), compose: n.request} }
+  // H-1 rule 5: TOOL_OUTPUT answers an open client call
+  const outputStep = memo((s, d, _e, x) => {
+    const p = d && typeof d == 'object' && openPart(s, d.toolCallId, 'TOOL_OUTPUT')
+    if (!p) return
+    const err = 'errorText' in d
+    const {output: _o, errorText: _x, ...rest} = p
+    const np = {...rest, ...(err ? {state: 'output-error', errorText: String(d.errorText)} : {state: 'output-available', output: d.output}),
+      ...(p.ui && {ui: {...p.ui, status: err ? 'failed' : 'answered', pending: null}})}
+    return after(s, mapLast(s.messages, (y: any) => y === p ? np : y), x)
+  })
+  // H-2: a result part answered an open card: the call's output is `{ part, answer }`
+  const answerCard = memo((s, d, _e, x) => {
+    const p = d && typeof d == 'object' && openPart(s, d.scope, 'ANSWER', y => y.ui?.status == 'open')
+    if (!p) return
+    const part = p.ui.layout?.nodes?.[d.node]?.part ?? null
+    const np = {...p, state: 'output-available', output: {part, answer: d.value}, ui: {...p.ui, status: 'answered', answer: {node: d.node, part, value: d.value}}}
+    return after(s, mapLast(s.messages, (y: any) => y === p ? np : y), x)
+  })
+  // H-2: the backend's reply for the card in flight (another step, the card, or a failure), then the next card
+  const cardStep = (ok: boolean) => memo((s, d, _e, x) => {
+    const st = x?.state, k = x?.k
+    const card = openToolCalls(s).find((y: any) => composing(y) && y.ui.pending)
+    // the reply's request key: the chat driver's `key`, an HTTP reply's `askKey` tag (G-756, ask.ts), a failure's request
+    const key = d?.askKey ?? d?.key ?? d?.request?.key
+    // a late reply (the card was cancelled or answered, or the turn replaced) is dropped
+    if (!card || (typeof key == 'string' && key != `${k}.ask:${card.toolCallId}`)) return
+    const r = ok ? c.kit.cardReply(c.ask, card, d, st, k) : c.kit.failed(card, String(d?.error?.message ?? d?.error ?? 'the request failed'))
+    const msgs = mapLast(s.messages, (y: any) => y === card ? r.part ?? r : y)
+    return r.request !== undefined ? {...settle(s, msgs, c), compose: r.request} : after(s, msgs, x)
+  })
+  const cardOk = cardStep(true), cardFailed = cardStep(false)
+  // H-2: a container control in a card: ui[node][name] = value, on the card's part
+  const controlStep = (s: any, d: any) => {
+    if (!d || typeof d.scope != 'string') return
+    let hit = false
+    const messages = s.messages.map((m: any) => m.role != 'assistant' || !m.parts.some((x: any) => x.toolCallId === d.scope && x.ui) ? m
+      : {...m, parts: m.parts.map((x: any) => x.toolCallId !== d.scope || !x.ui ? x : (hit = true, {...x, ui: {...x.ui, ui: {...x.ui.ui, [d.key]: {...x.ui.ui?.[d.key], [d.name]: d.value}}}}))})
+    return hit ? {...s, messages} : undefined
+  }
+  // rule 12: a restored busy slice (its request is gone) is made usable again; a composing card is composed again
+  const resumeStep = memo((s, _d, _e, p) => {
+    const msgs0 = s.messages.length ? mapLast(s.messages, (x: any) => composing(x) ? {...x, ui: {...x.ui, pending: null}} : x) : s.messages
+    // agent calls still open never get their results now
+    const m = lastOf(msgs0)
+    let msgs = m?.role == 'assistant' && openCalls(m).some(x => !isClient(c, x))
+      ? mapLast(msgs0, (x: any) => isTool(x) && x.state == 'input-available' && !isClient(c, x) ? {...x, state: 'output-error', errorText: 'not run: the page was reloaded'} : x) : msgs0
+    msgs = withPartial(s, msgs)
+    const card = nextCard(c, msgs, p?.state, p?.k)
+    const ask = firstAsk(lastOf(card.msgs))
+    return {s: {...s, messages: card.msgs, draft: '', draftReasoning: '', status: ask || card.request !== undefined ? 'streaming' : 'ready', pending: ask ? askInfo(ask) : null}, compose: card.request}
+  })
+  /** the partial reply (STOP, RESUME) appended to the last assistant message, or as a new one */
+  const withPartial = (s: any, msgs: any[]) => {
+    const partial = [...(s.draftReasoning ? [{type: 'reasoning', text: s.draftReasoning}] : []), ...(s.draft ? [{type: 'text', text: s.draft}] : [])]
+    const last = lastOf(msgs)
+    return !partial.length ? msgs : last?.role == 'assistant' ? [...msgs.slice(0, -1), {...last, parts: [...last.parts, {type: 'step-start'}, ...partial]}] : [...msgs, {id: messageId(), role: 'assistant', parts: partial}]
+  }
+  return {sendStep, regenStep, replyStep, resultsStep, answerStep, outputStep, answerCard, cardOk, cardFailed, controlStep, resumeStep, withPartial}
+}
 
 // ------------------------------------------------------------------ the request
 /** the app-state message's id and metadata marker (G-631) */
@@ -200,12 +399,15 @@ function appState(t: any, groups: any[], labels: Map<string, any>): any {
   return {id: APP_STATE, role: 'user', metadata: {sygnal: APP_STATE, untrusted}, parts: [{type: 'text', text}]}
 }
 
+const shadowed = new Set<string>()
 /**
  * The request for the conversation `messages`: tools and app state of now, the state right before
  * the last user message; `fresh`: a new turn. When the last message is the assistant's (tool
- * results, an approval answered) the reply continues it (`continue: true`, G-628)
+ * results, an approval answered) the reply continues it (`continue: true`, G-628). H-1: the client
+ * tools join the agent tools (a name in both: the client tool, SYG684); `host`: the host's state
+ * (ask's direct layout schema reads it)
  */
-function request(e: Engine | undefined, o: any, k: string, messages: any[], fresh: boolean) {
+function request(e: Engine | undefined, o: any, k: string, messages: any[], fresh: boolean, c?: Cfg, host?: any) {
   const t = e && toolsOf(e)
   if (e) {
     // a new turn: a call still waiting on `until` answers now, as pending
@@ -219,17 +421,26 @@ function request(e: Engine | undefined, o: any, k: string, messages: any[], fres
   }
   const state = t && appState(t, groups, labels), i = lastUser(messages)
   const schema = (x: any) => bare.has(x.name) ? unlabel(x.inputSchema, `their labels are in ${bare.get(x.name)}_labels in the app state`) : x.inputSchema
+  const tools: any = Object.fromEntries(list.map((x: any) => [x.name, {description: x.description, inputSchema: schema(x)}]))
+  if (c) for (const n in c.client) {
+    if (n in tools && !shadowed.has(n)) { shadowed.add(n); dev('SYG684', `the client tool '${n}' has the name of an agent tool; the client tool is sent and its calls are the app's to answer`, 'Rename the client tool, or the agent declaration or action') }
+    const x = c.client[n]
+    tools[n] = c.ask && n == 'ask_user' ? c.kit.askTool(c.ask, host) : {description: x.description, inputSchema: schemaOf(x)}
+  }
   return {
     ...o.transportOptions,
     messages: !state ? messages : i < 0 ? [state, ...messages] : [...messages.slice(0, i), state, ...messages.slice(i)],
     ...(o.instructions && {instructions: o.instructions}),
-    ...(list.length && {tools: Object.fromEntries(list.map((x: any) => [x.name, {description: x.description, inputSchema: schema(x)}]))}),
-    ...(o.model && {model: o.model}),
+    ...(Object.keys(tools).length && {tools}),
+    ...modelOf(o.model, host),
     ...(lastOf(messages)?.role == 'assistant' && {continue: true}),
     key: k, delta: k + '.DELTA', ok: k + '.REPLY', error: k + '.FAILED',
   }
 }
 
+/** `model`: a model id, or a function of the host's state returning one (resolved per request) */
+const modelOf = (m: any, host: any) => { const v = typeof m == 'function' ? m(host) : m; return v ? {model: v} : {} }
+
 /**
  * run a reply's tool calls one at a time; RESULTS when all are done (dropped if the turn moved on).
  * The results so far are kept on the engine (`ran`): STOP gives the calls that ran their results
@@ -251,20 +462,60 @@ async function runTools(e: Engine, calls: any[]) {
   dispatch(e, 'RESULTS', {turn, results}, 'reply')
 }
 
+/** a click on a card's container control (catalog.render's `control()` data attributes) */
+const controlOf = (ev: any) => {
+  const el = ev?.ownerTarget || ev?.target?.closest?.('[data-compose-control]') || ev?.target
+  const ds = el?.dataset || {}
+  if (!ds.composeControl || !ds.composeKey || ds.composeScope === undefined) return null
+  let value: any = ds.composeValue
+  try { value = JSON.parse(value) } catch (_) { /* a plain string */ }
+  return {scope: ds.composeScope, key: ds.composeKey, name: ds.composeControl, value}
+}
+
 /**
  * The chat behavior (PLAN-6 L-3): `uses = { assistant: chat({ sink, form, prompt, stop, approve,
- * deny, instructions, model, agent, maxSteps, transportOptions }) }`. Types: src/ai.d.ts.
+ * deny, instructions, model, agent, maxSteps, transportOptions, clientTools, ask }) }`. Types:
+ * src/ai.d.ts.
  */
 export const chat = (options: any = {}): any => {
-  const {sink = 'LLM', form, prompt, stop, approve, deny, regenerate} = options
+  const {sink = 'LLM', form, prompt, stop, approve, deny, regenerate, clientTools, ask} = options
   const on = (DOM: any, sel: any, ev = 'click', o?: any) => DOM.select(sel).events(ev, o)
   const E = engineFor
+  // H-1 / H-2: the calls the app answers; ask_user's card machinery comes with the catalog
+  const kit = ask?.catalog?._ask
+  if (ask && !kit) throw new Error('[Sygnal] chat({ ask }): `ask.catalog` must be a catalog made by defineCatalog()')
+  const c: Cfg = {client: {...clientTools}, ...(ask && {kit, ask: kit.askConfig(ask, options, sink)})}
+  if (ask) c.client.ask_user = {}
+  const B: string | undefined = c.ask?.backend?.sink
+  const S = steps(c, options)
+  const {sendStep, regenStep, replyStep, resultsStep, answerStep} = S
+  // the sink handlers' view of the host: its state (props.state) and the use's key
+  const P = (p: any, k: string) => p && {state: p.state, k}
+  // a step's request on the chat sink (`send`), and the card request on the backend's sink
+  const out = (n: any, e: any, o: any, k: string, p: any, which: 'chat' | 'card') => {
+    if (!n) return ABORT
+    if (which == 'card') return n.compose ?? ABORT
+    return n.send ? request(e, o, k, n.s.messages, false, c, p?.state) : B === sink && n.compose !== undefined ? n.compose : ABORT
+  }
+  /** model entries for a step's chat request and its card request (one entry when they share a sink) */
+  const sinks = (step: (s: any, d: any, e: any, p: any) => any) => ({
+    [sink]: (s: any, d: any, _n: any, p: any, o: any, k: string) => { const e = E(p, k, o); return out(step(s, d, e, P(p, k)), e, o, k, p, 'chat') },
+    ...(B && B !== sink && {[B]: (s: any, d: any, _n: any, p: any, o: any, k: string) => out(step(s, d, E(p, k, o), P(p, k)), undefined, o, k, p, 'card')}),
+  })
+  const stateOf = (step: (s: any, d: any, e: any, p: any) => any) => (s: any, d: any, _n: any, p: any, o: any, k: string) => step(s, d, E(p, k, o), P(p, k))?.s || ABORT
+  /** the card request in flight's key (STOP aborts it) */
+  const inflight = (s: any, k: string) => { const x = openToolCalls(s).find((p: any) => composing(p) && p.ui.pending); return x && `${k}.ask:${x.toolCallId}` }
   const b = defineBehavior({
     initialState: {messages: [], prompt: '', draft: '', draftReasoning: '', status: 'ready', pending: null, error: null},
     intent: (so: any) => {
-      const {DOM} = so
+      const {DOM, CHILD} = so
       // SYG442: an app made before the first chat() call has no layer: no tools, no loop
       checkLinked(so, 'chat', 'it sends no tools and runs no tool calls')
+      // rule 12: a slice restored busy (persist) or with a card composing; a microtask later, so
+      // the requests it sends reach drivers that are wired after the instance is made
+      const restored = so.STATE?.stream?.take?.(1).filter((s: any) => s && (busy(s) || openToolCalls(s).some(composing)))
+        .map((s: any) => xs.fromPromise(Promise.resolve(s))).flatten()
+      const results = c.ask?.results || []
       return {
         ...(prompt && {PROMPT: on(DOM, prompt, 'input').map((ev: any) => ev.target.value)}),
         ...(form && {SEND: on(DOM, form, 'submit', {preventDefault: true})}),
@@ -272,70 +523,92 @@ export const chat = (options: any = {}): any => {
         ...(approve && {APPROVE: on(DOM, approve)}),
         ...(deny && {DENY: on(DOM, deny)}),
         ...(regenerate && {REGENERATE: on(DOM, regenerate)}),
+        ...(restored && {RESUME: restored}),
+        // H-2: a result part's PARENT value (compose.answer): cards render in the host's view
+        ...(results.length && CHILD && {ANSWER: xs.merge(...results.map((C: any) => CHILD.select(C))).filter((v: any) => v && typeof v == 'object' && v.scope !== undefined)}),
+        ...(c.ask?.controls && DOM && {CONTROL: DOM.select('[data-compose-control]').events('click').map(controlOf).filter((x: any) => !!x)}),
       }
     },
     model: {
       PROMPT: (s: any, p: any) => typeof p == 'string' && p !== s.prompt ? {...s, prompt: p} : ABORT,
       SEND: {
         STATE: (s: any, d: any) => sendStep(s, d) || ABORT,
-        [sink]: (s: any, d: any, _n: any, p: any, o: any, k: string) => { const n = sendStep(s, d); return n ? request(E(p, k, o), o, k, n.messages, true) : ABORT },
+        [sink]: (s: any, d: any, _n: any, p: any, o: any, k: string) => { const n = sendStep(s, d); return n ? request(E(p, k, o), o, k, n.messages, true, c, p?.state) : ABORT },
       },
       REGENERATE: {
         STATE: (s: any) => regenStep(s, 0) || ABORT,
-        [sink]: (s: any, _d: any, _n: any, p: any, o: any, k: string) => { const n = regenStep(s, 0); return n ? request(E(p, k, o), o, k, n.messages, true) : ABORT },
+        [sink]: (s: any, _d: any, _n: any, p: any, o: any, k: string) => { const n = regenStep(s, 0); return n ? request(E(p, k, o), o, k, n.messages, true, c, p?.state) : ABORT },
       },
       // G-627: the reply's text and reasoning so far
       DELTA: (s: any, d: any) => ({...s, draft: d?.text ?? s.draft, draftReasoning: d?.reasoning ?? s.draftReasoning, status: 'streaming'}),
       REPLY: {
-        STATE: (s: any, d: any, _n: any, p: any, o: any, k: string) => replyStep(s, d, E(p, k, o))?.s || ABORT,
-        // the turn is over: DONE in the same flush (a host entry 'assistant.DONE' runs after it)
+        STATE: stateOf(replyStep),
+        ...sinks(replyStep),
+        // the turn is over: DONE in the same flush (a host entry 'assistant.DONE' runs after it).
+        // H-1: each client call that opened fires TOOL_CALL; the turn waits for their answers
         EFFECT: (s: any, d: any, next: any, p: any, o: any, k: string) => {
-          const e = E(p, k, o), r = replyStep(s, d, e)
-          if (!r || r.ask) return
+          const e = E(p, k, o), r = replyStep(s, d, e, P(p, k))
+          if (!r) return
+          for (const call of r.opened) e ? dispatch(e, 'TOOL_CALL', call, 'next') : next('TOOL_CALL', call, 0)
+          if (r.ask) return
           const done = {message: r.msg, text: d.text, finishReason: d.finishReason, usage: d.usage, steps: e?.steps ?? 1}
           if (r.calls) void runTools(e!, r.calls)
+          else if (r.wait || r.send) return
           else if (e) dispatch(e, 'DONE', done, 'next')
           else next('DONE', done, 0)
         },
       },
       RESULTS: {
-        STATE: (s: any, d: any, _n: any, p: any, o: any, k: string) => resultsStep(s, d, E(p, k, o))?.s || ABORT,
-        [sink]: (s: any, d: any, _n: any, p: any, o: any, k: string) => { const e = E(p, k, o), n = resultsStep(s, d, e); return n?.send ? request(e, o, k, n.s.messages, false) : ABORT },
+        STATE: stateOf(resultsStep),
+        [sink]: (s: any, d: any, _n: any, p: any, o: any, k: string) => { const e = E(p, k, o), n = resultsStep(s, d, e); return n?.send ? request(e, o, k, n.s.messages, false, c, p?.state) : ABORT },
       },
       ASK: (s: any, info: any) => ({...s, pending: info}),
       // a consequential app call (A-1's confirm) or a server approval (G-628: answerStep)
       APPROVE: {
         STATE: (s: any) => answerStep(s, true)?.s || (s.pending ? {...s, pending: null} : ABORT),
-        [sink]: (s: any, _d: any, _n: any, p: any, o: any, k: string) => { const n = answerStep(s, true); return n?.send ? request(E(p, k, o), o, k, n.s.messages, false) : ABORT },
+        [sink]: (s: any, _d: any, _n: any, p: any, o: any, k: string) => { const n = answerStep(s, true); return n?.send ? request(E(p, k, o), o, k, n.s.messages, false, c, p?.state) : ABORT },
         EFFECT: (s: any, _d: any, _n: any, p: any, o: any, k: string) => { if (s.pending?.approvalId === undefined) E(p, k, o)?.answer?.(true) },
       },
       DENY: {
         STATE: (s: any) => answerStep(s, false)?.s || (s.pending ? {...s, pending: null} : ABORT),
-        [sink]: (s: any, _d: any, _n: any, p: any, o: any, k: string) => { const n = answerStep(s, false); return n?.send ? request(E(p, k, o), o, k, n.s.messages, false) : ABORT },
+        [sink]: (s: any, _d: any, _n: any, p: any, o: any, k: string) => { const n = answerStep(s, false); return n?.send ? request(E(p, k, o), o, k, n.s.messages, false, c, p?.state) : ABORT },
         EFFECT: (s: any, _d: any, _n: any, p: any, o: any, k: string) => { if (s.pending?.approvalId === undefined) E(p, k, o)?.answer?.(false) },
       },
+      // H-1: the app answers a client call (rule 5)
+      TOOL_OUTPUT: {STATE: stateOf(S.outputStep), ...sinks(S.outputStep)},
+      // H-1: a client call opened (a host entry 'assistant.TOOL_CALL' runs after it)
+      TOOL_CALL: () => ABORT,
       STOP: {
-        // the calls that ran keep their results (G-626); the partial reply is kept (its reasoning too)
+        // the calls that ran keep their results (G-626); the partial reply is kept (its reasoning
+        // too); H-1: open client calls are closed, a card being composed is cancelled
         STATE: (s: any, _d: any, _n: any, p: any, o: any, k: string) => {
-          if (!busy(s)) return ABORT
-          const e = E(p, k, o), msgs = closeOpen(s.messages, 'not run: stopped by the user', e?.ran?.turn === e?.turn ? e?.ran?.out : undefined)
-          const partial = [...(s.draftReasoning ? [{type: 'reasoning', text: s.draftReasoning}] : []), ...(s.draft ? [{type: 'text', text: s.draft}] : [])]
-          const last = lastOf(msgs)
-          return {
-            ...s, draft: '', draftReasoning: '', status: 'ready', pending: null,
-            messages: !partial.length ? msgs : last?.role == 'assistant' ? [...msgs.slice(0, -1), {...last, parts: [...last.parts, {type: 'step-start'}, ...partial]}] : [...msgs, {id: messageId(), role: 'assistant', parts: partial}],
-          }
+          if (!busy(s) && !openToolCalls(s).length) return ABORT
+          const e = E(p, k, o), msgs = closeOpen(s.messages, 'not run: stopped by the user', e?.ran?.turn === e?.turn ? e?.ran?.out : undefined, c, 'not answered: stopped by the user')
+          return {...s, draft: '', draftReasoning: '', status: 'ready', pending: null, messages: S.withPartial(s, msgs)}
+        },
+        [sink]: (s: any, _d: any, _n: any, _p: any, _o: any, k: string) => {
+          const keys = [...(busy(s) ? [k] : []), ...(B === sink && inflight(s, k) ? [inflight(s, k)] : [])]
+          return !keys.length ? ABORT : {abort: keys.length == 1 ? keys[0] : keys}
         },
-        [sink]: (s: any, _d: any, _n: any, _p: any, _o: any, k: string) => busy(s) ? {abort: k} : ABORT,
+        ...(B && B !== sink && {[B]: (s: any, _d: any, _n: any, _p: any, _o: any, k: string) => inflight(s, k) ? {abort: inflight(s, k)} : ABORT}),
         // the turn moves on: a waiting confirm is declined, tool results still to come are dropped
         EFFECT: (s: any, _d: any, _n: any, p: any, o: any, k: string) => { const e = busy(s) && E(p, k, o); if (e) { e.turn++; e.answer?.(false); e.tools?.cancel() } },
       },
       FAILED: {
-        STATE: (s: any, d: any) => ({...s, messages: closeOpen(s.messages, 'not run: the request failed'), draft: '', draftReasoning: '', status: 'error', pending: null, error: d?.error?.message ?? String(d?.error ?? 'error')}),
+        STATE: (s: any, d: any) => ({...s, messages: closeOpen(s.messages, 'not run: the request failed', undefined, c), draft: '', draftReasoning: '', status: 'error', pending: null, error: d?.error?.message ?? String(d?.error ?? 'error')}),
         EFFECT: (_s: any, _d: any, _n: any, p: any, o: any, k: string) => { const e = E(p, k, o); if (e) { e.turn++; e.answer?.(false); e.tools?.cancel() } },
       },
       // (REPLY already set ready: a host entry gets the finished state)
       DONE: (s: any) => s.status == 'ready' ? ABORT : {...s, status: 'ready'},
+      // rule 12: once at start, for a slice restored busy
+      RESUME: {STATE: stateOf(S.resumeStep), ...sinks(S.resumeStep)},
+      ...(c.ask && {
+        // H-2: the card backend's replies, a result part's answer, a card's container control
+        CARD: {STATE: stateOf(S.cardOk), ...sinks(S.cardOk)},
+        CARD_FAILED: {STATE: stateOf(S.cardFailed), ...sinks(S.cardFailed)},
+        ANSWER: {STATE: stateOf(S.answerCard), ...sinks(S.answerCard)},
+        CONTROL: (s: any, d: any) => S.controlStep(s, d) || ABORT,
+      }),
     },
   })(options)
   // the `prompt` option is a selector, not the slice's start value (defineBehavior's option override)