sygnal 7.0.0 → 7.2.0-preview.0

package/src/agent-ui/mcp.ts

@@ -0,0 +1,152 @@
+/**
+ * sygnal/agent-ui: a minimal Model Context Protocol server (tools only), as sygnal-check's
+ * (sygnal-check/src/mcp.js) and sygnal/vite's dev endpoint (src/vite/mcp.ts): hand-rolled, no
+ * dependency, both protocol eras answered per request.
+ *
+ * - legacy, the `initialize` revisions (2024-11-05 … 2025-11-25): initialize, ping, tools/list,
+ *   tools/call; JSON-RPC batches answered. tools.listChanged is true: the tool set can change
+ *   when extra tools (sygnal/ai agentTools) do, and notifications/tools/list_changed is sent.
+ * - modern, the stateless 2026-07-28 revision (`_meta['io.modelcontextprotocol/protocolVersion']`
+ *   with client capabilities): server/discover, tools/list, tools/call; results carry
+ *   `resultType: 'complete'` and the server info in `_meta`.
+ * Transport: newline-delimited JSON over any stream pair with `on('data')` and `write()` (Node's
+ * stdin / stdout); messages are handled one at a time, in order.
+ */
+export const MODERN_VERSIONS = ['2026-07-28']
+export const LEGACY_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05']
+const SUPPORTED = [...MODERN_VERSIONS, ...LEGACY_VERSIONS]
+const META = 'io.modelcontextprotocol/'
+
+export interface McpTool {
+  name: string
+  description: string
+  inputSchema: Record<string, any>
+  annotations?: Record<string, any>
+}
+export interface McpToolResult {
+  /** the text the model reads */
+  text: string
+  /** structured content (an object) */
+  value?: Record<string, any>
+  isError?: boolean
+}
+export interface McpServerSpec {
+  name: string
+  version: string
+  instructions?: string
+  tools(): McpTool[]
+  call(name: string, args: Record<string, any>): Promise<McpToolResult>
+}
+
+const isObj = (v: any): v is Record<string, any> => !!v && typeof v == 'object' && !Array.isArray(v)
+
+export function createMcpHandler(spec: McpServerSpec) {
+  const serverInfo = {name: spec.name, version: spec.version}
+  const result = (id: any, value: any) => ({jsonrpc: '2.0', id, result: value})
+  const error = (id: any, code: number, message: string, data?: any) => ({jsonrpc: '2.0', id, error: {code, message, ...(data !== undefined ? {data} : {})}})
+
+  async function route(id: any, method: string, params: Record<string, any>, modern: boolean): Promise<any> {
+    if (modern && (method == 'initialize' || method == 'ping')) return error(id, -32601, `Method not found: ${method} is not in 2026-07-28`)
+    switch (method) {
+      case 'initialize':
+        return result(id, {
+          protocolVersion: LEGACY_VERSIONS.includes(params.protocolVersion) ? params.protocolVersion : LEGACY_VERSIONS[0],
+          capabilities: {tools: {listChanged: true}},
+          serverInfo,
+          ...(spec.instructions ? {instructions: spec.instructions} : {}),
+        })
+      case 'server/discover':
+        if (!modern) return error(id, -32602, 'Invalid params: server/discover is a 2026-07-28 request')
+        return result(id, {supportedVersions: SUPPORTED, capabilities: {tools: {}}, ...(spec.instructions ? {instructions: spec.instructions} : {})})
+      case 'ping':
+        return result(id, {})
+      case 'tools/list':
+        return result(id, {tools: spec.tools()})
+      case 'tools/call': {
+        const name = params.name
+        if (!spec.tools().some(t => t.name == name)) return error(id, -32602, `Unknown tool: ${name}`)
+        try {
+          const r = await spec.call(name, isObj(params.arguments) ? params.arguments : {})
+          return result(id, {content: [{type: 'text', text: r.text}], ...(r.value ? {structuredContent: r.value} : {}), isError: !!r.isError})
+        } catch (e: any) {
+          return result(id, {content: [{type: 'text', text: `${name} failed: ${e?.message || e}`}], isError: true})
+        }
+      }
+      default:
+        return error(id, -32601, `Method not found: ${method}`)
+    }
+  }
+
+  /** one message → its response (null for a notification); never throws */
+  async function handle(msg: any, inBatch = false): Promise<any> {
+    try {
+      if (!isObj(msg) || msg.jsonrpc !== '2.0' || typeof msg.method != 'string') {
+        return isObj(msg) && 'id' in msg && !('result' in msg || 'error' in msg) ? error(msg.id ?? null, -32600, 'Invalid Request') : null
+      }
+      if (!('id' in msg) || msg.id === null) return null
+      const {id, method} = msg
+      const params = isObj(msg.params) ? msg.params : {}
+      const meta = isObj(params._meta) ? params._meta : {}
+      let modern = false
+      if (META + 'protocolVersion' in meta) {
+        const v = meta[META + 'protocolVersion']
+        if (!SUPPORTED.includes(v)) return error(id, -32022, 'Unsupported protocol version', {supported: SUPPORTED, requested: v})
+        if (MODERN_VERSIONS.includes(v)) {
+          if (!isObj(meta[META + 'clientCapabilities'])) return error(id, -32602, `Invalid params: _meta["${META}clientCapabilities"] is required`)
+          if (inBatch) return error(id, -32600, 'Invalid Request: 2026-07-28 messages are sent one per line, not in a batch')
+          modern = true
+        }
+      }
+      const out = await route(id, method, params, modern)
+      if (modern && isObj(out.result)) out.result = {resultType: 'complete', ...out.result, _meta: {...(out.result._meta || {}), [META + 'serverInfo']: serverInfo}}
+      return out
+    } catch (e: any) {
+      return error(isObj(msg) ? msg.id ?? null : null, -32603, `Internal error: ${e?.message || e}`)
+    }
+  }
+  return {handle}
+}
+
+export interface McpStdio {
+  /** notifications/tools/list_changed to the client */
+  listChanged(): void
+  /** stop reading */
+  stop(): void
+  /** resolves when the input ends */
+  done: Promise<void>
+}
+
+/** serve over a newline-delimited JSON stream pair (default: process.stdin / process.stdout) */
+export function serveMcpStream(spec: McpServerSpec, input?: any, output?: any): McpStdio {
+  const proc: any = (globalThis as any).process
+  input ||= proc?.stdin
+  output ||= proc?.stdout
+  const {handle} = createMcpHandler(spec)
+  const send = (m: any) => { if (m && !(Array.isArray(m) && !m.length)) output.write(JSON.stringify(m) + '\n') }
+  let buf = '', queue = Promise.resolve(), end!: () => void
+  const done = new Promise<void>(r => end = r)
+  const line = (l: string) => {
+    if (!l.trim()) return
+    queue = queue.then(async () => {
+      let msg: any
+      try { msg = JSON.parse(l) } catch { return send({jsonrpc: '2.0', id: null, error: {code: -32700, message: 'Parse error'}}) }
+      if (Array.isArray(msg)) send((await Promise.all(msg.map(m => handle(m, true)))).filter(Boolean))
+      else send(await handle(msg))
+    })
+  }
+  const onData = (chunk: any) => {
+    buf += String(chunk)
+    let i
+    while ((i = buf.indexOf('\n')) >= 0) { line(buf.slice(0, i)); buf = buf.slice(i + 1) }
+  }
+  const onEnd = () => { if (buf) line(buf); buf = ''; queue.then(end) }
+  input.setEncoding?.('utf8')
+  input.on('data', onData)
+  input.on('end', onEnd)
+  input.resume?.()
+  return {
+    listChanged: () => send({jsonrpc: '2.0', method: 'notifications/tools/list_changed'}),
+    stop: () => { input.off?.('data', onData); input.off?.('end', onEnd); end() },
+    done,
+  }
+}

package/src/agent-ui/snapshot.ts

@@ -0,0 +1,212 @@
+/**
+ * sygnal/agent-ui: the accessibility snapshot. The host tree as an LLM agent reads a page: roles,
+ * accessible names, states and values, with a ref on each element it can act on. The format is
+ * the YAML-like aria snapshot browser agents already know (Playwright's, Claude in Chrome's
+ * read_page):
+ *
+ *   - heading "todos" [level=1]
+ *   - textbox "What needs to be done?" [ref=e4]
+ *   - list:
+ *     - listitem:
+ *       - checkbox "Toggle" [checked] [ref=e9]
+ *       - generic "Write the spike" [ref=e10] [on=dblclick]
+ *       - button "Delete" [ref=e11]
+ *   - text: 1 item left
+ *
+ * What a browser can't give an agent: `on=…` lists the events the app's intents listen for on an
+ * element that isn't a native control (Sygnal's intents are selectors, so the renderer knows
+ * exactly which elements are interactive).
+ */
+import type {HostDocument, HostElement, HostNode, HostStyleRule} from '../host'
+import {computeStyle, isInteractive, isTextField, isCheckable, labelTarget, nodeId, optionValue} from '../host'
+
+export interface AgentNode {
+  role: string
+  name?: string
+  /** `e<id>`: the element tools act on */
+  ref?: string
+  value?: string
+  /** checked, disabled, expanded, pressed, selected, focused, required, level=n */
+  states?: string[]
+  /** events the app listens for on a non-native element */
+  on?: string[]
+  /** a text node's text */
+  text?: string
+  children?: AgentNode[]
+}
+
+const BLOCK = /^(root|div|section|header|footer|main|nav|article|aside|ul|ol|li|form|fieldset|h[1-6]|p|pre|table|tr|td|th|details|summary|dialog|blockquote|figure|figcaption|dl|dt|dd|hr|br|menu|search|label)$/
+const NATIVE = /^(input|textarea|select|button|a|summary|option)$/
+const LANDMARKS: Record<string, string> = {nav: 'navigation', main: 'main', aside: 'complementary', search: 'search', dialog: 'dialog'}
+
+export function roleOf(el: HostElement): string | null {
+  const r = el.getAttribute('role')
+  if (r) return r.split(/\s+/)[0]
+  const t = el.localName
+  // a target's own field tags (registerFieldTags)
+  if (t != 'input' && t != 'textarea' && isCheckable(el)) return 'checkbox'
+  if (t != 'input' && t != 'textarea' && isTextField(el)) return 'textbox'
+  if (t == 'a') return el.hasAttribute('href') ? 'link' : null
+  if (t == 'button' || t == 'summary') return 'button'
+  if (t == 'input') {
+    const ty = el.type || 'text'
+    if (/^(button|submit|reset|image)$/.test(ty)) return 'button'
+    if (ty == 'checkbox' || ty == 'radio') return ty
+    if (ty == 'range') return 'slider'
+    if (ty == 'number') return 'spinbutton'
+    if (ty == 'search') return 'searchbox'
+    if (ty == 'hidden' || ty == 'file') return null
+    return 'textbox'
+  }
+  if (t == 'textarea') return 'textbox'
+  if (t == 'select') return el.multiple ? 'listbox' : 'combobox'
+  if (t == 'option') return 'option'
+  if (/^h[1-6]$/.test(t)) return 'heading'
+  if (t == 'ul' || t == 'ol' || t == 'menu') return 'list'
+  if (t == 'li') return 'listitem'
+  if (t == 'img') return el.getAttribute('alt') === '' ? null : 'img'
+  if (t == 'table') return 'table'
+  if (t == 'tr') return 'row'
+  if (t == 'td') return 'cell'
+  if (t == 'th') return 'columnheader'
+  if (t == 'progress') return 'progressbar'
+  if (t == 'fieldset' || t == 'details') return 'group'
+  if (t == 'form') return el.getAttribute('aria-label') || el.getAttribute('name') ? 'form' : null
+  if (t == 'section') return el.getAttribute('aria-label') ? 'region' : null
+  return LANDMARKS[t] || null
+}
+
+const squash = (s: string) => s.replace(/\s+/g, ' ').trim()
+/** visible text, without hidden subtrees */
+function textOf(n: HostNode, rules: readonly HostStyleRule[], skip?: HostElement): string {
+  if (n.nodeType === 3) return (n as any).data
+  const el = n as HostElement
+  if (el === skip || computeStyle(el, rules).display == 'none' || el.getAttribute('aria-hidden') == 'true') return ''
+  if (el.localName == 'input' || el.localName == 'select' || el.localName == 'textarea') return ''
+  return el.childNodes.map(c => textOf(c, rules, skip)).join(BLOCK.test(el.localName) ? ' ' : '')
+}
+
+/** the accessible name: aria-label, aria-labelledby, a label, contents, alt / value / placeholder / title */
+export function nameOf(el: HostElement, rules: readonly HostStyleRule[] = []): string {
+  const a = el.getAttribute('aria-label')
+  if (a) return squash(a)
+  const by = el.getAttribute('aria-labelledby')
+  if (by) return squash(by.split(/\s+/).map(id => { const t = el.ownerDocument.getElementById(id); return t ? textOf(t, rules) : '' }).join(' '))
+  const t = el.localName
+  if (t == 'input' || t == 'textarea' || t == 'select') {
+    const id = el.id
+    const lab = (id && el.ownerDocument.querySelector(`label[for="${id}"]`)) || el.closest('label')
+    // (a label names its control even when it's visually hidden, as the browser's accessible name)
+    const l = lab ? squash(textOf(lab, [], el)) : ''
+    if (l) return l
+    if (t == 'input' && /^(button|submit|reset)$/.test(el.type)) return el.getAttribute('value') || (el.type == 'reset' ? 'Reset' : 'Submit')
+    return squash(el.placeholder || el.title || '')
+  }
+  if (t == 'img') return squash(el.getAttribute('alt') || el.title || '')
+  return squash(textOf(el, rules)) || squash(el.title || '')
+}
+
+const CONTENT_NAMED = /^(button|link|heading|checkbox|radio|switch|textbox|searchbox|combobox|listbox|slider|spinbutton|option|img|columnheader|cell|tab|menuitem|treeitem|tooltip|progressbar)$/
+const labelOnly = (el: HostElement, rules: readonly HostStyleRule[]) => {
+  const a = el.getAttribute('aria-label')
+  if (a) return squash(a)
+  const by = el.getAttribute('aria-labelledby')
+  if (by) return squash(by.split(/\s+/).map(id => { const t = el.ownerDocument.getElementById(id); return t ? textOf(t, rules) : '' }).join(' '))
+  return squash(el.title || '')
+}
+
+export interface SnapshotOptions {
+  rules?: readonly HostStyleRule[]
+}
+
+/** the host tree as agent nodes (generic containers flattened, their text merged into text nodes) */
+export function snapshotTree(doc: HostDocument, options: SnapshotOptions = {}): AgentNode[] {
+  const rules = options.rules || []
+  // labels that name a control are read as that control's name, not again as text
+  const naming = new Set<HostElement>()
+  for (const l of doc.body.querySelectorAll('label')) {
+    const t = labelTarget(l)
+    if (t && t.localName != 'button') naming.add(l)
+  }
+  const kids = (el: HostElement): AgentNode[] => {
+    const out: AgentNode[] = []
+    let text = ''
+    const flushText = () => { const t = squash(text); if (t) out.push({role: 'text', text: t}); text = '' }
+    // a flex container's children are separate items (a column's lines, a row's gap): their text doesn't run together
+    const visit = (n: HostNode, inFlex = false) => {
+      if (n.nodeType === 3) { text += (n as any).data; return }
+      const c = n as HostElement
+      const st = computeStyle(c, rules)
+      if (st.display == 'none' || c.getAttribute('aria-hidden') == 'true') return
+      const node = nodeFor(c)
+      if (node) { flushText(); out.push(node); return }
+      if (naming.has(c)) {
+        // the label's own text names its control; any other content stays
+        for (const x of c.childNodes) if (x.nodeType === 1) visit(x)
+        return
+      }
+      const block = inFlex || BLOCK.test(c.localName)
+      const flex = /flex$/.test(st.display || '')
+      if (block) flushText()
+      for (const x of c.childNodes) visit(x, flex)
+      if (block) flushText()
+    }
+    for (const c of el.childNodes) visit(c, /flex$/.test(computeStyle(el, rules).display || ''))
+    flushText()
+    return out
+  }
+  const nodeFor = (el: HostElement): AgentNode | null => {
+    const role = roleOf(el)
+    const interactive = isInteractive(el, rules)
+    const listened = NATIVE.test(el.localName) ? [] : el.ownerDocument.listenedTypes(el).filter(t => !/^(focus|blur|focusin|focusout)$/.test(t))
+    if (!role && !(interactive && listened.length)) return null
+    const node: AgentNode = {role: role || 'generic'}
+    // a role-less element the app listens to is one control (its contents its name), unless
+    // interactive elements are inside it: a scene-graph group with a click intent (canvas-three F1)
+    // keeps its children
+    const leaf = /^(textbox|searchbox|checkbox|radio|switch|slider|spinbutton|combobox|listbox|button|link|img|heading|option|progressbar)$/.test(node.role) || !role && !el.querySelectorAll('*').some(d => isInteractive(d, rules))
+    // a name from contents only for the roles that take one (ARIA "name from content"); a
+    // landmark, list or group (or such a container) is named by aria-label / aria-labelledby / title only
+    const name = !role && leaf || CONTENT_NAMED.test(node.role) ? nameOf(el, rules) : labelOnly(el, rules)
+    if (name) node.name = name
+    if (interactive) node.ref = 'e' + nodeId(el)
+    if (listened.length) node.on = listened
+    const states: string[] = []
+    if (/^(checkbox|radio|switch)$/.test(node.role)) { if (isCheckable(el) ? el.checked : el.getAttribute('aria-checked') == 'true') states.push('checked') }
+    if (el.disabled || el.getAttribute('aria-disabled') == 'true') states.push('disabled')
+    for (const s of ['expanded', 'pressed', 'selected']) { const v = el.getAttribute('aria-' + s); if (v) states.push(v == 'true' ? s : `${s}=${v}`) }
+    if (node.role == 'option' && el.selected) states.push('selected')
+    if (el.required) states.push('required')
+    if (node.role == 'heading') states.push('level=' + (+(el.getAttribute('aria-level') || el.localName.slice(1)) || 2))
+    if (el.ownerDocument.activeElement === el) states.push('focused')
+    if (states.length) node.states = states
+    if (isTextField(el)) node.value = el.type == 'password' ? '•'.repeat([...el.value].length) : el.value
+    if (el.localName == 'select') {
+      const o = el.options.find(x => optionValue(x) == el.value)
+      if (o) node.value = squash(o.textContent)
+      node.children = el.options.map(x => ({role: 'option', name: squash(x.textContent), ...(x === o ? {states: ['selected']} : {})}))
+      return node
+    }
+    if (!leaf) { const c = kids(el); if (c.length) node.children = c }
+    return node
+  }
+  return kids(doc.body)
+}
+
+const q = (s: string) => JSON.stringify(s)
+/** agent nodes as the YAML-like text */
+export function formatSnapshot(nodes: AgentNode[], indent = ''): string {
+  const lines: string[] = []
+  for (const n of nodes) {
+    if (n.role == 'text') { lines.push(`${indent}- text: ${n.text}`); continue }
+    let line = `${indent}- ${n.role}`
+    if (n.name) line += ' ' + q(n.name)
+    for (const s of n.states || []) line += ` [${s}]`
+    if (n.ref) line += ` [ref=${n.ref}]`
+    if (n.on?.length) line += ` [on=${n.on.join(',')}]`
+    if (n.value !== undefined && n.value !== '') line += ': ' + q(n.value)
+    if (n.children?.length) lines.push(line + ':', formatSnapshot(n.children, indent + '  '))
+    else lines.push(line)
+  }
+  return lines.join('\n')
+}

package/src/agent-ui.d.ts

@@ -0,0 +1,106 @@
+// 'sygnal/agent-ui': a Sygnal app rendered for an LLM agent, on 'sygnal/host'. Guide: https://sygnal.js.org/renderers/agent-ui
+import type { HostDocument, HostElement, HostSource, HostStyleRule } from 'sygnal/host'
+
+/** A snapshot node */
+export interface AgentNode {
+  role: string
+  name?: string
+  /** `e<id>`: what tools act on */
+  ref?: string
+  value?: string
+  /** checked, disabled, expanded, pressed, selected, focused, required, level=n */
+  states?: string[]
+  /** events the app's intents listen for on a non-native element */
+  on?: string[]
+  text?: string
+  children?: AgentNode[]
+}
+export function snapshotTree(doc: HostDocument, options?: { rules?: readonly HostStyleRule[] }): AgentNode[]
+export function formatSnapshot(nodes: AgentNode[], indent?: string): string
+export function roleOf(el: HostElement): string | null
+export function nameOf(el: HostElement, rules?: readonly HostStyleRule[]): string
+
+export interface AgentUIOptions {
+  /** what is shown: `['.todo .edit', { display: 'none' }]` */
+  styles?: readonly HostStyleRule[]
+  /** a link's default action (a router driver's go) */
+  onNavigate?: (href: string, el: HostElement) => void
+  /** quiet time before a tool call answers (ms, default 20) */
+  quietMs?: number
+  /** longest wait for the app to settle (ms, default 2000) */
+  maxWaitMs?: number
+  document?: HostDocument
+}
+
+export interface McpTool {
+  name: string
+  description: string
+  inputSchema: Record<string, any>
+  annotations?: Record<string, any>
+}
+export interface AgentUITool extends McpTool {
+  annotations: { readOnlyHint?: boolean, destructiveHint?: boolean }
+}
+export type AgentUIResult =
+  | { ok: true, snapshot: string }
+  | { ok: false, error: string, snapshot?: string }
+
+export interface AgentUI {
+  readonly doc: HostDocument
+  /** run(App, { DOM: ui.driver }) */
+  readonly driver: (vnode$: any, name?: string) => HostSource
+  snapshot(): string
+  tree(): AgentNode[]
+  element(ref: string): HostElement | null
+  /** ui_snapshot, ui_click, ui_type, ui_press, ui_select, ui_check */
+  tools(): AgentUITool[]
+  /** the tools as ChatRequest.tools (sygnal/ai) */
+  chatTools(): Record<string, { description: string, inputSchema: Record<string, any> }>
+  /** run a tool; answers after the app settles, with the new snapshot */
+  call(name: string, args?: Record<string, any>): Promise<AgentUIResult>
+  /** run()'s result, to wait on its flushes (runAgentUI does this) */
+  attach(app: any): void
+  settle(): Promise<void>
+  subscribe(listener: () => void): () => void
+}
+export function createAgentUI(options?: AgentUIOptions): AgentUI
+
+export interface RunAgentUIOptions extends AgentUIOptions {
+  drivers?: Record<string, any>
+  runOptions?: Record<string, any>
+}
+export function runAgentUI(App: any, options?: RunAgentUIOptions): { app: any, ui: AgentUI }
+
+/** a tool set served alongside: sygnal/ai's agentTools(app), or your own */
+export interface ExtraTools {
+  list(): { name: string, description: string, inputSchema: Record<string, any>, annotations?: Record<string, any> }[]
+  call(name: string, args?: unknown): Promise<unknown>
+  subscribe?(listener: (change: any) => void): () => void
+}
+export interface ServeMcpOptions {
+  name?: string
+  version?: string
+  instructions?: string
+  tools?: ExtraTools
+  /** default process.stdin / process.stdout */
+  input?: any
+  output?: any
+}
+export interface McpStdio {
+  listChanged(): void
+  stop(): void
+  done: Promise<void>
+}
+/** the UI tools (and extra tools) as an MCP server over newline-delimited JSON (default stdio) */
+export function serveMcp(ui: AgentUI, options?: ServeMcpOptions): McpStdio
+
+export interface McpToolResult { text: string, value?: Record<string, any>, isError?: boolean }
+export interface McpServerSpec {
+  name: string
+  version: string
+  instructions?: string
+  tools(): McpTool[]
+  call(name: string, args: Record<string, any>): Promise<McpToolResult>
+}
+export function createMcpHandler(spec: McpServerSpec): { handle(message: unknown, inBatch?: boolean): Promise<unknown> }
+export function serveMcpStream(spec: McpServerSpec, input?: any, output?: any): McpStdio