sygnal 6.0.0 → 6.1.1

package/src/extra/ai/decide.ts

@@ -0,0 +1,104 @@
+/*
+ * PLAN-6 M-1: decisions (TypeSafe Jev, Ollama `nimble`/`clef`, OpenRouter, AI Gateway, OpenAI
+ * Decisions) are plain HTTP requests, so there is no driver here: `decide()` builds a
+ * `makeFetchDriver` request that works as a reply-action request (`ok` / `error`) and as a
+ * `resources` entry. Types and docs: src/ai.d.ts.
+ *
+ * Dictionary form (TypeSafe `/v1/systemone`, Ollama ≥ 0.35 `/v1/systemone`; verified against
+ * Ollama 0.40.2 + nimble):
+ *   request  { model, state, questions: { name: { type, instructions, criteria? } }, images? }
+ *            choice: criteria { option: description | null }; noul: criteria { true, false }
+ *            (optional); score: criteria [level descriptions, lowest first]
+ *   response { model, answers: { name: { type: 'choice', choice, probabilities, confidence }
+ *            | { type: 'noul', noul } | { type: 'score', score, legend, probabilities, confidence } },
+ *            usage: { input_tokens, output_tokens } }
+ *
+ * OpenAI Decisions (`POST /v1/decisions`, the array form): `decide.openai()` sends
+ *   { model, input, questions: [{ type: 'predicate' | 'choice' | 'score', name, instructions,
+ *     choices?: [{ value, description }], levels?: [{ label, description }] }] }
+ * and its `parse` maps `{ answers: [{ type, name, … }] }` back to the dictionary form, so the
+ * reply action / resource data has the same shape whichever form was sent (a refusal becomes
+ * `{ type: 'refusal' }` under the question's name).
+ *
+ * Side-effect free (0 B for apps that don't import it).
+ */
+
+/** a `choice` question: pick one option (criteria: option → description, or an array of option names) */
+export const choice = (instructions: any, criteria: any) => ({
+  type: 'choice',
+  instructions,
+  criteria: Array.isArray(criteria) ? Object.fromEntries(criteria.map(c => [c, null])) : criteria,
+});
+
+/** a `noul` question: the probability of yes (criteria: `{ true, false }` descriptions) */
+export const noul = (instructions: any, criteria?: any) =>
+  criteria ? {type: 'noul', instructions, criteria} : {type: 'noul', instructions};
+
+/** a `score` question: an ordered scale, lowest first (the answer is the weighted level index) */
+export const score = (instructions: any, levels: any) => ({type: 'score', instructions, criteria: levels});
+
+/** the dictionary-form request (TypeSafe, Ollama, OpenRouter, AI Gateway) */
+function dictionary({url = '/api/decide', model, state, questions, images, ...rest}: any = {}) {
+  const json: any = {model, state, questions};
+  if (images) json.images = images;
+  return {url, method: 'POST', json, ...rest};
+}
+
+const text = (x: any) => typeof x == 'string' ? x : JSON.stringify(x);
+// the dictionary form takes base64 files; OpenAI takes data URLs (the type from the magic bytes)
+const dataUrl = (b64: string) => b64.startsWith('data:') ? b64
+  : `data:image/${b64.startsWith('/9j/') ? 'jpeg' : b64.startsWith('UklGR') ? 'webp' : 'png'};base64,${b64}`;
+
+/** the questions in OpenAI's array form */
+export const toOpenAI = (questions: any) => Object.keys(questions || {}).map(name => {
+  const q = questions[name];
+  const c = q.criteria;
+  const instructions = text(q.instructions);
+  if (q.type == 'choice') {
+    return {type: 'choice', name, instructions,
+      choices: Object.keys(c).map(value => c[value] == null ? {value} : {value, description: c[value]})};
+  }
+  if (q.type == 'score') return {type: 'score', name, instructions, levels: c.map((d: string) => ({label: d, description: d}))};
+  // a predicate has no criteria: they go into the instructions
+  return {type: 'predicate', name,
+    instructions: c ? `${instructions}\nTrue: ${c.true}\nFalse: ${c.false}` : instructions};
+});
+
+// a refusal (or a type this mapping doesn't know) keeps its fields but `name`
+const withoutName = ({name, ...a}: any) => a;
+
+const toMap = (list: any[], k: string) => {
+  const out: any = {};
+  (list || []).forEach(p => { out[String(p[k])] = p.probability; });
+  return out;
+};
+
+/** an OpenAI Decisions reply in the dictionary form */
+export const fromOpenAI = (reply: any) => {
+  if (!reply || !Array.isArray(reply.answers)) return reply;
+  const answers: any = {};
+  reply.answers.forEach((a: any) => {
+    const {type, name} = a;
+    answers[name] = type == 'predicate' ? {type: 'noul', noul: a.probability}
+      : type == 'choice' ? {type, choice: a.choice, probabilities: toMap(a.probabilities, 'value'), confidence: a.confidence}
+      : type == 'score' ? {type, score: a.score,
+        legend: Object.fromEntries((a.probabilities || []).map((p: any) => [String(p.value), p.label])),
+        probabilities: toMap(a.probabilities, 'value'), confidence: a.confidence}
+      : withoutName(a);
+  });
+  return {...reply, answers};
+};
+
+const parseOpenAI = async (res: any) => fromOpenAI(await res.json());
+
+/** the same questions as an OpenAI Decisions request; the reply arrives in the dictionary form */
+function openai({url = '/api/decide', model, state, questions, images, ...rest}: any = {}) {
+  const input = images && images.length
+    ? [{role: 'user', content: [{type: 'input_text', text: text(state)},
+      ...images.map((b: string) => ({type: 'input_image', image_url: dataUrl(b)}))]}]
+    : text(state);
+  return {url, method: 'POST', json: {model, input, questions: toOpenAI(questions)}, parse: parseOpenAI, ...rest};
+}
+
+/** the dictionary-form request (TypeSafe, Ollama, OpenRouter, AI Gateway); `decide.openai()`: the same as an OpenAI Decisions request */
+export const decide = /*#__PURE__*/ Object.assign(dictionary, {openai})

package/src/extra/ai/index.ts

@@ -0,0 +1,42 @@
+/*
+ * PLAN-6 (D240, D253): the implementation behind 'sygnal/ai'. It lives in the main package so
+ * there is one copy of the reply helpers and the diagnostics module (G-581) and renderComponent's
+ * fakes can use it; src/index.ts exports these names and src/ai.ts re-exports them from the
+ * external 'sygnal', which is the documented import. Every module here must be side-effect free
+ * so apps that don't use it pay 0 B (the size gate).
+ *
+ * Layout (Phase 1): messages.ts (L-1 message helpers), chat/ (L-1 driver, L-2 transports),
+ * agent/ (A-1 layer), schema/ (A-1 input contract), decide.ts (M-1).
+ */
+export {messageText, withToolResults} from './messages'
+export {decide, choice, noul, score} from './decide'
+// A-1 (1-A): the agent layer and the schema input contract
+export {agentTools} from './agent/index'
+export {toJsonSchema, parseInput} from './schema/index'
+export {jsonSchema} from './schema/jsonSchema'
+// L-1 (1-L): the chat driver; outputJsonSchema is the structured-output seam transports use (1-A fills it)
+export {makeChatDriver} from './chat/driver'
+export {outputJsonSchema} from './chat/output'
+// A-2 (2-W): WebMCP (experimental, D241)
+export {experimentalExposeWebMcp} from './webmcp'
+// L-3 (2-C): the chat behavior
+export {chat} from './chat/behavior'
+// L-2 (2-T): transports, wave 1 (D248), each its own module (tree-shaken), and the Open Responses
+// event encoder (D273)
+export {openResponses} from './transports/openResponses'
+export {chatCompletions} from './transports/chatCompletions'
+export {uiMessageStream} from './transports/uiMessageStream'
+export {chromePrompt} from './transports/chromePrompt'
+export {encodeOpenResponses} from './transports/encodeOpenResponses'
+// M-2 / M-3 (3-M): decision reply fixtures and the command bar
+export {answers} from './answers'
+// PLAN-6 A-3 (experimental, D241, D291): form(schema, { tool: formTool({ … }) })
+export {formTool} from '../formTool'
+export {commandBar} from './commandBar'
+// L-2 (3-W2): transports, wave 2 (D248), and the opt-in strict layer (D285)
+export {anthropicMessages} from './transports/anthropicMessages'
+export {agui} from './transports/agui'
+export {fromAISDK} from './transports/fromAISDK'
+export {strictSchemas} from './schema/strict'
+// X-1 (3-X): MCP Apps, the view side
+export {makeMcpAppDriver} from './mcpApp'

package/src/extra/ai/link.ts

@@ -0,0 +1,90 @@
+/*
+ * PLAN-6 (D283): how the sygnal/ai behaviors (`chat`, L-3; `commandBar`, M-3) reach their app's
+ * runtime, with 0 core bytes. The agent layer (A-1) needs the app's runtime API and the host
+ * instance, which a behavior's handlers don't get. The first factory call (`chat()`,
+ * `commandBar()`) adds one hook-layer factory to the core bridge's `layers`
+ * (`globalThis.__SYGNAL_DIAGNOSTICS__.layers`, which every App reads when it is constructed, as
+ * the dev entries do), so each app made after it hands the layer its runtime API. The layer's
+ * onAction (called synchronously right before an action's handlers) records the instance and its
+ * pre-action state; a handler takes them when its `props.state` is that state.
+ *
+ * G-625: an app made before the first factory call (a host loaded lazily into a running app)
+ * didn't read the layer at construction, so the first factory call also adds it to the apps that
+ * are already running and can be found without core changes: the one `run()` registers as
+ * `window.__SYGNAL_DEVTOOLS_APP__` (the first live app; its `__runtime.addHooks`). Another app
+ * started before it (a second `run()`, a `sygnal/element` custom element) can't be found: its
+ * hosts are reported as SYG442 and run without the link.
+ *
+ * Per (host instance, uses key) a behavior keeps one engine (`engineOf`); the layer's onDispose
+ * stops the host's engines.
+ */
+import {error as logError} from '../diagnostics/legacy'
+
+const G: any = globalThis
+/** marks a `uses` value whose host needs the link (`linked()`) */
+const AI = Symbol.for('sygnal.aiBehavior')
+
+interface Ctx {api: any; iv: any; pre: any}
+export interface Engine {api: any; iv: any; k: string; stop(): void}
+
+/** the instance whose action is being handled (set by the layer's onAction; one object per app) */
+let cur: Ctx | undefined
+const engines = new WeakMap<any, Map<string, Engine>>()
+/** the dispose$ of each linked host an app with the layer created (SYG442 otherwise) */
+const known = new WeakSet<any>()
+const isHost = (iv: any) => {
+  const u = iv.def.view.uses
+  for (const k in u) if (u[k]?.[AI]) return true
+  return false
+}
+
+const layer = (api: any) => {
+  const c: Ctx = {api, iv: null, pre: null}
+  return {
+    onCreate: (iv: any) => { if (isHost(iv)) known.add(iv.sources.dispose$) },
+    onAction: (iv: any) => { c.iv = iv; c.pre = iv.state; cur = c },
+    onDispose: (iv: any) => { engines.get(iv)?.forEach(e => e.stop()) },
+  }
+}
+
+/** the runtimes the layer was added to after they started (G-625) */
+const late = new WeakSet<any>()
+
+/** install the layer (apps made from now on read it) and mark the behavior value `b` as needing it */
+export function linked<B>(b: B): B {
+  const D = G.__SYGNAL_DIAGNOSTICS__ ||= {}, L = D.layers ||= new Set()
+  if (!(L.has ? L.has(layer) : L.includes(layer))) {
+    L.add ? L.add(layer) : L.push(layer)
+    // G-625: the app already running (registered by run())
+    const rt = (typeof window != 'undefined' ? window as any : G).__SYGNAL_DEVTOOLS_APP__?.__runtime
+    if (rt && typeof rt.addHooks == 'function' && !late.has(rt)) {
+      late.add(rt)
+      rt.addHooks(layer(rt))
+    }
+  }
+  ;(b as any)[AI] = true
+  return b
+}
+
+/**
+ * The engine of the host whose action runs now, made by `make(api, iv)` on first use (undefined
+ * when the app has no layer, or `props` isn't the acting instance's)
+ */
+export function engineOf<E extends Engine>(props: any, k: string, make: (api: any, iv: any) => E): E | undefined {
+  const c = cur
+  if (!c || !props || props.state !== c.pre || c.iv.disposed) return
+  const iv = c.iv
+  let m = engines.get(iv)
+  if (!m) engines.set(iv, m = new Map())
+  let e = m.get(k) as E | undefined
+  if (!e) m.set(k, e = make(c.api, iv))
+  return e
+}
+
+const warned = new Set<string>()
+/** SYG442, once per behavior: an intent's host has no link (its app was made before the factory call) */
+export function checkLinked(sources: any, name: string, without: string) {
+  if (known.has(sources.dispose$) || warned.has(name)) return
+  warned.add(name)
+  logError('SYG442', name, `the ${name} behavior has no connection to its app (the app was started before the first ${name}() call, and isn't the page's first app): ${without}`, `Call ${name}() in a module imported before run(), not only in a component loaded later`)
+}

package/src/extra/ai/mcpApp.ts

@@ -0,0 +1,314 @@
+/*
+ * PLAN-6 X-1 (D247): `makeMcpAppDriver(options?)`, the view side of MCP Apps (SEP-1865, protocol
+ * 2026-01-26): a Sygnal app as the HTML resource a host (Claude, ChatGPT, VS Code, MCPJam, the
+ * ext-apps basic-host) shows in a sandboxed iframe, talking JSON-RPC 2.0 over postMessage with
+ * the host window. Hand-written (D209: the `@modelcontextprotocol/ext-apps` SDK is a test-only
+ * devDependency; its `App` pulls in the MCP client and zod).
+ *
+ * - Handshake on start: `ui/initialize` { appInfo, appCapabilities, protocolVersion } →
+ *   { hostInfo, hostCapabilities, hostContext }, then `ui/notifications/initialized`. Requests
+ *   made before it completes are queued. With no host (not in an iframe, SSR) nothing is sent and
+ *   every request gets its `error` action.
+ * - Source `MCP.select(type)`: 'tool-input' ({ arguments } → the arguments object),
+ *   'tool-input-partial' (the same, streamed while the model writes them), 'tool-result' (the
+ *   CallToolResult: { content, structuredContent?, isError? }), 'tool-cancelled' ({ reason? }),
+ *   'host-context-changed' (the whole host context, merged: first the one from the handshake,
+ *   then after each change) and 'teardown' (the host is about to remove the view; it is answered
+ *   after the actions it caused have run). The latest tool-input, tool-result and host context
+ *   are replayed to a stream that starts later (a component shown after they arrived).
+ * - Sink values (reply actions `ok` / `error` to the sending instance, like makeFetchDriver):
+ *   - `{ callTool: name, args?, ok?, error? }`: `tools/call` on the MCP server through the host;
+ *     ok gets the CallToolResult, error `{ error, result?, request }` (a JSON-RPC error, or a
+ *     result with isError: true);
+ *   - `{ updateModelContext }`: `ui/update-model-context`; a string → one text block, an array →
+ *     content blocks, an object → structuredContent (or `{ content, structuredContent }` as is);
+ *   - `{ message }`: `ui/message` as the user; a string or content blocks;
+ *   - `{ openLink: url }`: `ui/open-link`;
+ *   - `{ displayMode: 'inline' | 'fullscreen' | 'pip' }`: `ui/request-display-mode` (ok gets
+ *     `{ mode }`, the mode the host chose);
+ *   - G-641: `{ downloadFile }`: `ui/download-file` { contents } (EmbeddedResource / ResourceLink
+ *     blocks; a bare `{ uri, mimeType, text | blob }` is embedded); `{ readResource: uri }`:
+ *     `resources/read`; `{ listResources: true | { cursor } }`: `resources/list`;
+ *     `{ createMessage }`: `sampling/createMessage` (a string is one user message; maxTokens
+ *     defaults to 1024); notifications (ok runs once sent): `{ log, level?, logger? }`:
+ *     `notifications/message`, `{ requestTeardown: true }`: `ui/notifications/request-teardown`.
+ * - Source `MCP.select('host')`: { hostInfo, hostCapabilities, protocolVersion } of the
+ *   handshake (replayed), to check e.g. `hostCapabilities.sampling` / `downloadFile`.
+ * - Host → view requests: `ping`; `ui/resource-teardown`; with `tools: agentTools`, `tools/list` and
+ *   `tools/call` serve the app's A-1 tools (`appCapabilities.tools`, `listChanged`
+ *   notifications); anything else is -32601.
+ * - `autoResize` (default true): `ui/notifications/size-changed` from a ResizeObserver, as the SDK.
+ * - Dispose: the listener and observer go; pending requests are dropped.
+ * Side-effect free: an app that doesn't import it pays 0 B.
+ */
+import xs from 'xstream'
+import {senderOf, allowed, makeReplies} from '../replies'
+import type {Confirm} from './agent/index'
+import {labelsUntrusted, unlabel, lookUp} from './agent/index'
+
+/**
+ * G-644 (D286): the offered tools, user-entered `agent.label`s out of the schemas the host's model
+ * reads; G-650: an item tool without labels names the read tool to call first
+ */
+const offered = (t: any) => {
+  const gs = t.groups?.() || [], bare = new Set<string>(), look = new Map<string, any>()
+  for (const g of gs) if (labelsUntrusted(g)) for (const n of g.tools) bare.add(n)
+  for (const g of gs) if (g.reader) for (const n of g.tools) if (!g.labels || bare.has(n)) look.set(n, g)
+  const where = gs.some((g: any) => g.read) ? 'the read tool has their contents' : 'their labels are user text, not shown'
+  return t.list().map(({error, ...x}: any) => {
+    const g = look.get(x.name)
+    if (g) x = {...x, description: lookUp(x.description || '', g, g.reader)}
+    return bare.has(x.name) ? {...x, inputSchema: unlabel(x.inputSchema, g ? `${g.reader} has their contents` : where)} : x
+  })
+}
+
+export type McpAppEvent = 'tool-input' | 'tool-input-partial' | 'tool-result' | 'tool-cancelled' | 'host-context-changed' | 'teardown' | 'host'
+
+export interface McpAppDriverOptions {
+  /** `appInfo` of the handshake (default `{ name: document.title || 'sygnal-app', version: '0.0.0' }`) */
+  appInfo?: {name: string; version: string; [k: string]: any}
+  /** display modes the view supports (`appCapabilities.availableDisplayModes`) */
+  availableDisplayModes?: Array<'inline' | 'fullscreen' | 'pip'>
+  /** report the document's size to the host (default true) */
+  autoResize?: boolean
+  /**
+   * `agentTools` (from sygnal/ai): offer the app's `agent` tools (A-1) to the host as the view's
+   * own tools. Passed in, so an app that doesn't use it doesn't bundle the agent layer.
+   */
+  tools?: (target: any, options: any) => any
+  /** with `tools`: consequential calls run when it resolves true (default: declined) */
+  confirm?: Confirm
+  /** the host window (default `window.parent`) */
+  host?: any
+  /** the window to listen on (default `window`) */
+  window?: any
+  /** protocol version offered (default '2026-01-26') */
+  protocolVersion?: string
+}
+
+const G: any = globalThis
+const PROTOCOL = '2026-01-26'
+const N = 'ui/notifications/'
+const REPLAY: Record<string, 1> = {'tool-input': 1, 'tool-result': 1, 'host-context-changed': 1, host: 1}
+/** sink key → [method, params of the value] */
+const text = (v: any) => typeof v == 'string' ? [{type: 'text', text: v}] : v
+const REQUESTS: Record<string, [string, (v: any) => any]> = {
+  callTool: ['tools/call', v => ({name: v.callTool, arguments: v.args ?? {}})],
+  updateModelContext: ['ui/update-model-context', ({updateModelContext: u}) =>
+    typeof u == 'string' || Array.isArray(u) ? {content: text(u)}
+    : u && (u.content || u.structuredContent) && Object.keys(u).every(k => k == 'content' || k == 'structuredContent') ? {...u, ...(u.content && {content: text(u.content)})}
+    : {structuredContent: u}],
+  message: ['ui/message', v => ({role: 'user', content: text(v.message)})],
+  openLink: ['ui/open-link', v => ({url: v.openLink})],
+  displayMode: ['ui/request-display-mode', v => ({mode: v.displayMode})],
+  // G-641: an item without `type` is a resource's contents ({ uri, mimeType, text | blob }), embedded
+  downloadFile: ['ui/download-file', ({downloadFile: d}) => ({contents: (Array.isArray(d) ? d : [d]).map((c: any) => c && !c.type ? {type: 'resource', resource: c} : c)})],
+  readResource: ['resources/read', ({readResource: r}) => typeof r == 'string' ? {uri: r} : r],
+  listResources: ['resources/list', ({listResources: l}) => l && typeof l == 'object' ? l : {}],
+  createMessage: ['sampling/createMessage', ({createMessage: c}) => {
+    const p = typeof c == 'string' ? {messages: c} : {...c}
+    if (typeof p.messages == 'string') p.messages = [{role: 'user', content: {type: 'text', text: p.messages}}]
+    return {maxTokens: 1024, ...p}
+  }],
+}
+/** G-641: sink key → [notification method, params] (no answer: `ok` is called once it is sent) */
+const NOTIFY: Record<string, [string, (v: any) => any]> = {
+  log: ['notifications/message', v => ({level: v.level || 'info', ...(v.logger && {logger: v.logger}), data: v.log})],
+  requestTeardown: ['ui/notifications/request-teardown', () => ({})],
+}
+
+/** agent: the runtime API of the app being constructed (its layer runs right before its drivers start) */
+let building: any
+const layer = (api: any) => {
+  building = api
+  queueMicrotask(() => { building = undefined })
+  return {}
+}
+
+export function makeMcpAppDriver(options: McpAppDriverOptions = {}) {
+  if (options.tools) {
+    const D = G.__SYGNAL_DIAGNOSTICS__ ||= {}, L = D.layers ||= new Set()
+    if (L.add) L.add(layer)
+    else if (!L.includes(layer)) L.push(layer)
+  }
+  return (sink$: any) => {
+    const api = building
+    building = undefined
+    const win = options.window ?? G.window
+    const host = options.host ?? (win && win.parent !== win ? win.parent : undefined)
+    const subs = new Map<string, Set<any>>()
+    const last = new Map<string, any>()
+    const pending = new Map<number, (m: any) => void>()
+    let queue: any[] | null = [], id = 0, disposed = false, context: any = {}, stopResize: any, tools: any, offTools: any
+
+    const post = (m: any) => { try { host.postMessage({jsonrpc: '2.0', ...m}, '*') } catch (e) { console.error('[Sygnal] makeMcpAppDriver', e) } }
+    const send = (m: any) => queue ? queue.push(m) : post(m)
+    const request = (method: string, params: any, done: (m: any) => void, early?: boolean) => {
+      const m = {id: ++id, method, params}
+      pending.set(m.id, done)
+      early ? post(m) : send(m)
+    }
+    const emit = (type: string, data: any) => {
+      if (REPLAY[type]) last.set(type, data)
+      subs.get(type)?.forEach(l => { try { l.next(data) } catch (e) { console.error(e) } })
+    }
+    const {replies, reply} = makeReplies()
+
+    const serve = async (m: any) => {
+      const p = m.params || {}
+      if (m.method == 'ping') return {}
+      if (m.method == 'ui/resource-teardown') {
+        emit('teardown', p)
+        // answered after the actions it caused (their flush and the requests they sent)
+        for (let i = 0; i < 3; i++) await Promise.resolve()
+        return {}
+      }
+      if (tools && m.method == 'tools/list') return {tools: offered(tools)}
+      if (tools && m.method == 'tools/call') {
+        let r: any
+        try { r = await tools.call(p.name, p.arguments ?? {}) } catch (e: any) { r = {ok: false, error: String(e?.message ?? e)} }
+        return {content: [{type: 'text', text: JSON.stringify(r)}], structuredContent: r, ...(!r?.ok && {isError: true})}
+      }
+      throw {code: -32601, message: 'Method not found: ' + m.method}
+    }
+
+    const onMessage = (ev: any) => {
+      const m = ev.data
+      if (disposed || ev.source !== host || !m || m.jsonrpc !== '2.0') return
+      if (m.method === undefined) {
+        const done = pending.get(m.id)
+        if (done) { pending.delete(m.id); done(m) }
+      } else if (m.id !== undefined) {
+        serve(m).then(result => post({id: m.id, result}), (e: any) => post({id: m.id, error: {code: e?.code ?? -32603, message: String(e?.message ?? e)}}))
+      } else if (typeof m.method == 'string' && m.method.startsWith(N)) {
+        const type = m.method.slice(N.length), p = m.params || {}
+        if (type == 'host-context-changed') emit(type, context = {...context, ...p})
+        else if (type == 'tool-input' || type == 'tool-input-partial') emit(type, p.arguments ?? {})
+        else if (type == 'tool-result' || type == 'tool-cancelled') emit(type, p)
+      }
+    }
+
+    const resize = () => {
+      const RO = G.ResizeObserver, doc = G.document
+      if (options.autoResize === false || typeof RO != 'function' || !doc) return
+      let w = 0, h = 0, busy = false
+      const measure = () => {
+        if (busy) return
+        busy = true
+        // a frame, raced with a 100 ms timer: rAF is throttled in an off-screen or hidden iframe
+        // (WebKit, a view scrolled out of the host's chat), and the size must still be reported
+        let ran = false
+        const once = (f: () => void) => () => { if (!ran) { ran = true; f() } }
+        const go = once(() => {
+          busy = false
+          const el = doc.documentElement, old = el.style.height
+          el.style.height = 'max-content'
+          const H = Math.ceil(el.getBoundingClientRect().height)
+          el.style.height = old
+          const W = Math.ceil(G.innerWidth || 0)
+          if (W !== w || H !== h) { w = W; h = H; send({method: N + 'size-changed', params: {width: W, height: H}}) }
+        })
+        G.requestAnimationFrame?.(go)
+        setTimeout(go, 100)
+      }
+      measure()
+      const ro = new RO(measure)
+      ro.observe(doc.documentElement)
+      if (doc.body) ro.observe(doc.body)
+      stopResize = () => ro.disconnect()
+    }
+
+    if (host && win) {
+      win.addEventListener('message', onMessage)
+      if (options.tools && api) {
+        tools = options.tools(api, {confirm: options.confirm})
+        // list_changed only when the tools changed (not on every context change); the first is the list at start
+        let was: string | undefined
+        offTools = tools.subscribe(({tools: t}: any) => {
+          const now = JSON.stringify(t)
+          if (was !== undefined && now !== was) send({method: 'notifications/tools/list_changed'})
+          was = now
+        })
+      }
+      const doc = G.document
+      request('ui/initialize', {
+        appInfo: options.appInfo ?? {name: doc?.title || 'sygnal-app', version: '0.0.0'},
+        appCapabilities: {
+          ...(tools && {tools: {listChanged: true}}),
+          ...(options.availableDisplayModes && {availableDisplayModes: options.availableDisplayModes}),
+        },
+        protocolVersion: options.protocolVersion ?? PROTOCOL,
+      }, m => {
+        if (m.error) return console.error('[Sygnal] makeMcpAppDriver: ui/initialize failed', m.error)
+        const r = m.result || {}
+        emit('host', {hostInfo: r.hostInfo, hostCapabilities: r.hostCapabilities || {}, protocolVersion: r.protocolVersion})
+        if (r.hostContext) emit('host-context-changed', context = {...r.hostContext})
+        post({method: N + 'initialized'})
+        const q = queue || []
+        queue = null
+        q.forEach(post)
+        resize()
+      }, true)
+    }
+
+    sink$.addListener({
+      next: (v: any) => {
+        if (!v || typeof v != 'object' || disposed || !allowed(v, 'makeMcpAppDriver')) return
+        const k = Object.keys(REQUESTS).find(k => v[k] !== undefined)
+        const n = k ? undefined : Object.keys(NOTIFY).find(k => v[k] !== undefined && v[k] !== false)
+        const sender = senderOf(v)
+        const answer = (ok: boolean, data: any) => {
+          const action = ok ? v.ok : v.error
+          if (sender !== undefined && typeof action == 'string') reply(sender, action, data)
+          else if (!ok) console.error('[Sygnal] makeMcpAppDriver', data.error, v)
+        }
+        if (!k && !n) return console.error('[Sygnal] makeMcpAppDriver: expected { callTool }, { updateModelContext }, { message }, { openLink }, { displayMode }, { downloadFile }, { readResource }, { listResources }, { createMessage }, { log } or { requestTeardown }', v)
+        if (!host) return answer(false, {error: 'not running in an MCP Apps host', request: v})
+        if (n) {
+          const [method, params] = NOTIFY[n]
+          send({method, params: params(v)})
+          return answer(true, {})
+        }
+        const [method, params] = REQUESTS[k!]
+        request(method, params(v), m => {
+          if (m.error) answer(false, {error: m.error.message, code: m.error.code, request: v})
+          else if (m.result?.isError) answer(false, {error: (m.result.content || []).map((c: any) => c.text).filter(Boolean).join('\n') || method + ' failed', result: m.result, request: v})
+          else answer(true, m.result)
+        })
+      },
+      error: (e: any) => console.error('[Sygnal] makeMcpAppDriver', e),
+      complete: () => {},
+    })
+
+    const source = {
+      select: (type: McpAppEvent) => {
+        let mine: any
+        return xs.create<any>({
+          start: l => {
+            let s = subs.get(type)
+            if (!s) subs.set(type, s = new Set())
+            s.add(mine = l)
+            if (last.has(type)) l.next(last.get(type))
+          },
+          stop: () => { subs.get(type)?.delete(mine) },
+        })
+      },
+      isolateSource: (s: any) => s,
+      isolateSink: (s: any) => s,
+      isolateValue: (v: any) => v,
+      ...replies,
+    }
+    return {
+      ...source,
+      dispose: () => {
+        disposed = true
+        win?.removeEventListener?.('message', onMessage)
+        stopResize?.()
+        offTools?.()
+        tools?.stop()
+        pending.clear()
+        subs.clear()
+      },
+    }
+  }
+}

package/src/extra/ai/messages.ts

@@ -0,0 +1,51 @@
+/*
+ * PLAN-6 L-1 (D252): chat messages are AI SDK UIMessage-shaped: `{ id?, role, parts }`, where a
+ * part is `{ type: 'text', text }`, `{ type: 'reasoning', text }`, `{ type: 'tool-<name>', toolCallId,
+ * state, input?, output? }`, `{ type: 'file', … }`, `{ type: 'source-…', … }` or `{ type: 'data-…', … }`.
+ * A message written by hand may carry `content: string` instead of parts.
+ */
+
+/** the text of a message: its text parts joined (or its `content` string) */
+export function messageText(message: any): string {
+  if (!message) return ''
+  if (typeof message.content == 'string' && !message.parts) return message.content
+  return (message.parts || []).filter((p: any) => p && p.type === 'text').map((p: any) => p.text).join('')
+}
+
+/**
+ * G-640: a new message id, 16 random [0-9a-z] characters (the AI SDK's generateId is 16
+ * alphanumerics too). Ids name messages, they are no secret: Math.random is enough
+ */
+export const messageId = (): string => {
+  let s = ''
+  while (s.length < 16) s += Math.random().toString(36).slice(2)
+  return s.slice(0, 16)
+}
+
+const own = (o: any, k: any) => Object.prototype.hasOwnProperty.call(o, k)
+
+/**
+ * PLAN-6 4-F: the message with its open tool calls answered, for apps that run the raw chat
+ * driver's tool loop themselves: each `tool-<name>` part in `input-available` gets the result for
+ * its call. `results`: a function `(call: { id, name, input }) => output` (a throw is that call's
+ * error), or an object keyed by the call's id, else by the tool's name. An `Error` value (returned
+ * or thrown) gives `state: 'output-error'` with its `errorText`; any other value
+ * `state: 'output-available'` with it as `output`; `undefined` (no result) leaves the part open.
+ * Returns a new message (the same one when nothing changed).
+ */
+export function withToolResults(message: any, results: any): any {
+  if (!message || !Array.isArray(message.parts) || results == null) return message
+  let changed = false
+  const parts = message.parts.map((p: any) => {
+    if (!p || typeof p.type != 'string' || !p.type.startsWith('tool-') || p.state != 'input-available') return p
+    const call = {id: p.toolCallId, name: p.type.slice(5), input: p.input}
+    let r: any
+    try {
+      r = typeof results == 'function' ? results(call) : own(results, call.id) ? results[call.id] : own(results, call.name) ? results[call.name] : undefined
+    } catch (e: any) { r = e instanceof Error ? e : new Error(String(e)) }
+    if (r === undefined) return p
+    changed = true
+    return r instanceof Error ? {...p, state: 'output-error', errorText: r.message} : {...p, state: 'output-available', output: r}
+  })
+  return changed ? {...message, parts} : message
+}