sygnal 5.4.0 → 6.1.0

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
+}

package/src/extra/ai/schema/index.ts

@@ -0,0 +1,166 @@
+/*
+ * PLAN-6 A-1 (0-S4): the input contract of agent tools and of structured chat output.
+ *
+ * An `input` (or a chat request's `output`) is a Standard Schema that also implements Standard
+ * JSON Schema (Zod 4.2+, ArkType 2.1.28+, Valibot through `toStandardJsonSchema()`), or a plain
+ * JSON Schema wrapped by `jsonSchema()` (./jsonSchema.ts, D262). The model always gets the
+ * INPUT-side JSON Schema (it produces what `validate` receives), after the portable
+ * normalization below, which every consumer (the agent layer, WebMCP, the chat behavior, the
+ * chat driver's `output`, t.tools()) shares:
+ * - `$schema` / `$id` dropped, `oneOf` -> `anyOf`, Zod's safe-integer bounds dropped, a closed
+ *   tuple's `items: false` -> `maxItems` (Ollama rejects boolean subschemas);
+ * - a root self-reference (`"$ref": "#"`, Zod's recursion) moved into `$defs.__root` (Ollama
+ *   rejects `#`, and wrapping changes what it means); ArkType's `$ref`-only root inlined;
+ * - a non-object root wrapped as `{ value }` (`required`, `additionalProperties: false`); the
+ *   unwrap is lenient: arguments without a `value` key are taken as the value itself (0-S4: both
+ *   local models sent a wrapped object union bare).
+ * A schema part with no JSON Schema form (refinements, a Date) is retried with the library's
+ * lossy option (`lossy`: SYG243, a dev warning; validation still enforces it); no form at all is
+ * `error` (SYG240). Conversions are cached by schema object (ArkType rebuilds `~standard` on
+ * every read, G-608). The strict layer for OpenAI / Anthropic is the transports' (Phase 2), opt-in
+through `strictSchemas` (./strict.ts, D285); both walk schemas with `walk` below.
+ */
+
+/** The result of converting a schema: the tool schema, or why there is none (SYG240) */
+export interface Converted {
+  /** the normalized, input-side JSON Schema; always an object root */
+  schema?: any
+  /** the root was wrapped as `{ value }` */
+  wrapped?: boolean
+  /** a lossy conversion (SYG243): what the library couldn't express */
+  lossy?: string
+  /** no JSON Schema form (SYG240) */
+  error?: string
+}
+
+// each library's "give me what you can" switch (Standard JSON Schema's libraryOptions)
+const LOSSY: Record<string, any> = {zod: {unrepresentable: 'any'}, valibot: {errorMode: 'ignore'}, arktype: {fallback: (c: any) => c.base}}
+const SAFE = 9007199254740991
+const cache = new WeakMap<object, Converted>()
+
+const msg = (e: any) => String(e?.message || e).split('\n')[0].slice(0, 200)
+export const isObj = (x: any): boolean => !!x && typeof x == 'object' && !Array.isArray(x)
+
+/**
+ * The JSON Schema a model gets for `schema` (a Standard Schema with Standard JSON Schema, or
+ * `jsonSchema()`): `{ schema, wrapped, lossy? }`, or `{ error }` when it has no JSON Schema form.
+ * Cached by schema object.
+ */
+export function toJsonSchema(input: any): Converted {
+  if (!input || (typeof input != 'object' && typeof input != 'function')) return {error: 'not a Standard Schema'}
+  let c = cache.get(input)
+  if (!c) cache.set(input, c = convert(input))
+  return c
+}
+
+function convert(input: any): Converted {
+  const st = input['~standard']
+  if (typeof st?.validate != 'function') return {error: input.type || input.properties || input.anyOf || input.enum ? 'a plain JSON Schema: wrap it with jsonSchema()' : 'not a Standard Schema'}
+  const conv = st.jsonSchema?.input, v = st.vendor
+  if (typeof conv != 'function') return {error: `the ${v} schema has no JSON Schema form` + (v == 'valibot' ? ': wrap it with toStandardJsonSchema() from @valibot/to-json-schema' : v == 'zod' ? ' (Zod Mini): use jsonSchema(z.toJSONSchema(s), { validate: s })' : '')}
+  let js: any, lossy: string | undefined
+  try { js = conv({target: 'draft-2020-12'}) } catch (e) {
+    try { if (!LOSSY[v]) throw 0; js = conv({target: 'draft-2020-12', libraryOptions: LOSSY[v]}) } catch (_) { return {error: 'no JSON Schema form: ' + msg(e)} }
+    lossy = msg(e)
+  }
+  return {...normalize(js), ...(lossy && {lossy})}
+}
+
+// G-629: every subschema, bottom-up (shared with the strict layer, ./strict.ts). The values of
+// `properties` / `$defs` / ... maps are schemas, the maps themselves aren't (a property named
+// `oneOf` or `items` is a name, not a keyword), and `const` / `enum` / `default` / `examples` are
+// data (a default of `{ oneOf: 1 }` stays as it is)
+const MAPS = /^(properties|\$defs|definitions|patternProperties|dependentSchemas)$/
+const DATA = /^(const|enum|default|examples)$/
+export const walk = (s: any, f: (o: any) => any): any => {
+  if (Array.isArray(s)) return s.map(x => walk(x, f))
+  if (!s || typeof s != 'object') return s
+  const o: any = {}
+  for (const k in s) {
+    const v = s[k]
+    o[k] = DATA.test(k) ? v : MAPS.test(k) && isObj(v) ? Object.fromEntries(Object.entries(v).map(([n, x]) => [n, walk(x, f)])) : walk(v, f)
+  }
+  return f(o)
+}
+const rewriteRefs = (s: any, to: string) => walk(s, o => {
+  const r = o.$ref
+  if (typeof r == 'string' && (r == '#' || r[1] == '/') && !/^#\/(\$defs|definitions)\//.test(r)) o.$ref = to + r.slice(1)
+  return o
+})
+
+/** the portable normalization (see the header): `{ schema, wrapped }` */
+export function normalize(schema: any): {schema: any; wrapped: boolean} {
+  let {$schema, $id, ...s} = walk(schema, o => {
+    if ('oneOf' in o && !('anyOf' in o)) { o.anyOf = o.oneOf; delete o.oneOf }
+    if (o.type == 'integer' && o.minimum == -SAFE && o.maximum == SAFE) { delete o.minimum; delete o.maximum }
+    if (o.prefixItems && o.items === false) { delete o.items; o.maxItems ??= o.prefixItems.length }
+    return o
+  })
+  const m = typeof s.$ref == 'string' && /^#\/\$defs\/(.+)$/.exec(s.$ref)
+  if (m && s.$defs?.[m[1]]?.type == 'object' && Object.keys(s).length == 2) s = {...s.$defs[m[1]], $defs: s.$defs}
+  const {$defs, description, ...rest} = s
+  const defs: any = {...$defs}
+  const selfRef = /"\$ref":"#(?!\/\$defs\/|\/definitions\/)/.test(JSON.stringify(s))
+  if (selfRef) {
+    for (const k in defs) defs[k] = rewriteRefs(defs[k], '#/$defs/__root')
+    defs.__root = rewriteRefs(rest, '#/$defs/__root')
+  }
+  if (s.type == 'object') return {schema: selfRef ? {...defs.__root, ...(description && {description}), $defs: defs} : s, wrapped: false}
+  let value = selfRef ? {$ref: '#/$defs/__root'} : rest
+  if (description) value = {...value, description}
+  const out: any = {type: 'object', properties: {value}, required: ['value'], additionalProperties: false}
+  if (Object.keys(defs).length) out.$defs = defs
+  return {schema: out, wrapped: true}
+}
+
+export const resolve = (s: any, root: any) => {
+  const m = /^#\/\$defs\/(.+)$/.exec(s.$ref)
+  return m ? root.$defs?.[m[1]] : s.$ref == '#' ? root : s
+}
+
+/**
+ * D264: small local models send "3" for an integer and "true" for a boolean. Where the JSON
+ * Schema says number / integer / boolean (and not string), a string that parses as one becomes
+ * one. Nothing else changes; validation still decides.
+ */
+export function repair(value: any, schema: any, root: any = schema): any {
+  if (schema?.$ref) schema = resolve(schema, root)
+  if (!schema) return value
+  const types = [].concat(schema.type ?? []) as string[]
+  if (typeof value == 'string' && !types.includes('string')) {
+    const t = value.trim()
+    if ((types.includes('integer') || types.includes('number')) && /^-?\d+(\.\d+)?$/.test(t)) {
+      const n = Number(t)
+      if (types.includes('number') || Number.isInteger(n)) return n
+    }
+    if (types.includes('boolean') && (t == 'true' || t == 'false')) return t == 'true'
+  }
+  if (Array.isArray(value)) return value.map((x, i) => repair(x, schema.prefixItems?.[i] ?? schema.items, root))
+  if (isObj(value)) {
+    const o = {...value}
+    for (const b of schema.anyOf || [schema]) {
+      const bb = b?.$ref ? resolve(b, root) : b
+      for (const k in bb?.properties) if (k in o) o[k] = repair(o[k], bb.properties[k], root)
+    }
+    return o
+  }
+  if (typeof value == 'string' && schema.anyOf) for (const b of schema.anyOf) { const r = repair(value, b, root); if (r !== value) return r }
+  return value
+}
+
+/** One validation failure: the schema's message and the path as keys */
+export interface Issue {message: string; path?: PropertyKey[]}
+
+/**
+ * A model's arguments for `schema` -> the validated value: the lenient `{ value }` unwrap,
+ * `repair` (unless `repair: false`), then the schema's own validation. Resolves with
+ * `{ value }` (the schema's output), `{ issues }`, or `{ error }` (no JSON Schema form)
+ */
+export async function parseInput(schema: any, args: any, options: {repair?: boolean} = {}): Promise<{value?: any; issues?: Issue[]; error?: string}> {
+  const c = toJsonSchema(schema)
+  if (c.error) return {error: c.error}
+  let v = c.wrapped && isObj(args) && 'value' in args ? args.value : args
+  if (options.repair !== false) v = repair(v, c.wrapped ? c.schema.properties.value : c.schema, c.schema)
+  const r = await schema['~standard'].validate(v)
+  return r.issues ? {issues: r.issues.map((i: any) => ({message: i.message, ...(i.path && {path: i.path.map((p: any) => isObj(p) ? p.key : p)})}))} : {value: r.value}
+}

package/src/extra/ai/schema/jsonSchema.ts

@@ -0,0 +1,72 @@
+/*
+ * PLAN-6 A-1 (D262, 0-S4 §4): plain JSON Schema as a tool `input` (or a chat `output`), only
+ * through `jsonSchema(json[, { validate }])`. It returns a Standard Schema that is also a
+ * Standard JSON Schema, so it takes the same path as Zod / Valibot / ArkType. Without
+ * `validate`, a subset validator checks the value: type (integer and type arrays too), enum,
+ * const, required, properties, additionalProperties (false or a schema), items, prefixItems,
+ * anyOf / oneOf, minLength / maxLength, pattern, minimum / maximum, minItems / maxItems and local
+ * `$ref`s (`#`, `#/$defs/…`, `#/definitions/…`). format, allOf, not, if/then/else, multipleOf,
+ * uniqueItems, exclusive* and the rest are accepted unchecked. `{ validate: s }` keeps a
+ * library's own validation (Zod Mini: `jsonSchema(z.toJSONSchema(s), { validate: s })`).
+ * A separate module: tree-shaken unless imported.
+ */
+import type {Issue} from './index'
+
+const T = (v: any) => v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v
+const is = (t: string, v: any) => t == 'integer' ? Number.isInteger(v) : t == 'number' ? typeof v == 'number' && isFinite(v) : T(v) == t
+const S = JSON.stringify
+
+/** the subset check: the issues of `v` against `s` (empty when valid) */
+export function check(s: any, v: any, root: any = s, path: PropertyKey[] = [], out: Issue[] = []): Issue[] {
+  const bad = (message: string) => (out.push({message, path}), out)
+  if (s === false) return bad('no value allowed')
+  if (!s || s === true) return out
+  if (s.$ref) return check(s.$ref == '#' ? root : root.$defs?.[s.$ref.slice(8)] ?? root.definitions?.[s.$ref.slice(14)], v, root, path, out)
+  const types = [].concat(s.type ?? []) as string[]
+  if (types.length && !types.some(t => is(t, v))) return bad(`expected ${types.join(' or ')}, got ${T(v)}`)
+  if (s.enum && !s.enum.some((e: any) => S(e) == S(v))) return bad(`expected one of ${S(s.enum)}`)
+  if ('const' in s && S(s.const) != S(v)) return bad(`expected ${S(s.const)}`)
+  const any = s.anyOf ?? s.oneOf
+  if (any && !any.some((b: any) => !check(b, v, root, path).length)) return bad('matches no alternative')
+  if (typeof v == 'string') {
+    if (v.length < (s.minLength ?? 0)) bad(`at least ${s.minLength} characters`)
+    if (v.length > (s.maxLength ?? Infinity)) bad(`at most ${s.maxLength} characters`)
+    if (s.pattern && !new RegExp(s.pattern, 'u').test(v)) bad(`must match ${s.pattern}`)
+  }
+  if (typeof v == 'number') {
+    if (v < (s.minimum ?? -Infinity)) bad(`at least ${s.minimum}`)
+    if (v > (s.maximum ?? Infinity)) bad(`at most ${s.maximum}`)
+  }
+  if (Array.isArray(v)) {
+    if (v.length < (s.minItems ?? 0)) bad(`at least ${s.minItems} items`)
+    if (v.length > (s.maxItems ?? Infinity)) bad(`at most ${s.maxItems} items`)
+    const pre = s.prefixItems ?? []
+    v.forEach((x, i) => check(i < pre.length ? pre[i] : s.items, x, root, [...path, i], out))
+  } else if (T(v) == 'object') {
+    for (const k of s.required ?? []) if (!(k in v)) bad(`${k} is required`)
+    const p = s.properties ?? {}
+    for (const k in v) check(k in p ? p[k] : s.additionalProperties, v[k], root, [...path, k], out)
+  }
+  return out
+}
+
+/**
+ * A plain JSON Schema as a Standard Schema with Standard JSON Schema: the schema goes to the
+ * model as is (normalized), and the subset validator (or `options.validate`, a Standard Schema)
+ * checks the value
+ */
+export function jsonSchema(schema: any, options: {validate?: any} = {}): any {
+  const own = options.validate?.['~standard']
+  const out = () => schema
+  return {
+    '~standard': {
+      version: 1,
+      vendor: 'sygnal',
+      validate: own ? (v: any) => own.validate(v) : (value: any) => {
+        const issues = check(schema, value)
+        return issues.length ? {issues} : {value}
+      },
+      jsonSchema: {input: out, output: out},
+    },
+  }
+}