sygnal 5.4.0 → 6.1.0

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

@@ -0,0 +1,61 @@
+/*
+ * PLAN-6 L-1 / L-4: an in-memory chat transport whose streams are driven by hand. renderComponent's
+ * LLM fake runs the real chat driver over it (as the HTTP fake runs makeFetchDriver over an
+ * in-memory fetch), and the driver's own tests use it. Internal: not exported from 'sygnal/ai'.
+ *
+ * memoryTransport({ onStream?, onIdle? }).stream(request, signal) returns an async iterable and
+ * registers a handle synchronously (so a test sees it right after the sink emitted):
+ *   handle.request, handle.signal, handle.live (not ended, failed or aborted), handle.aborted
+ *   handle.push(...events)   ChatEvents, or strings (text deltas)
+ *   handle.end(finish?)      a finish event ({ reason?, usage? }), then done
+ *   handle.fail(error)       the iterator throws it
+ * `onIdle(handle)` runs when the driver has consumed every queued event and waits for more (the
+ * fake's "end of a frame").
+ */
+
+const toEvent = (c: any) => typeof c == 'string' ? {type: 'text', delta: c} : c;
+const abortError = () => Object.assign(new Error('The operation was aborted.'), {name: 'AbortError'});
+
+export function memoryTransport(opts: {onStream?: (h: any) => void; onIdle?: (h: any) => void} = {}) {
+  const streams: any[] = [];
+  const stream = (request: any, signal: AbortSignal) => {
+    const queue: any[] = [];
+    let ended = false, failed: any, waiting: any = null;
+    const wake = () => {
+      if (!waiting) return;
+      const w = waiting;
+      waiting = null;
+      pull(w[0], w[1]);
+    };
+    const h: any = {
+      request, signal, live: true, aborted: false,
+      push: (...evs: any[]) => { if (h.live) { queue.push(...evs.map(toEvent)); wake(); } return h; },
+      end: (finish?: any) => {
+        if (h.live) { queue.push({type: 'finish', ...finish}); ended = true; h.live = false; wake(); }
+        return h;
+      },
+      fail: (e: any) => {
+        if (h.live) { failed = e ?? new Error('stream failed'); h.live = false; wake(); }
+        return h;
+      },
+    };
+    const pull = (resolve: any, reject: any) => {
+      if (signal.aborted) return reject(abortError());
+      if (queue.length) return resolve({value: queue.shift(), done: false});
+      if (failed) return reject(failed);
+      if (ended) return resolve({value: undefined, done: true});
+      waiting = [resolve, reject];
+      opts.onIdle?.(h);
+    };
+    signal.addEventListener('abort', () => { h.live = false; h.aborted = true; wake(); });
+    streams.push(h);
+    opts.onStream?.(h);
+    return {
+      [Symbol.asyncIterator]: () => ({
+        next: () => new Promise((resolve, reject) => pull(resolve, reject)),
+        return: () => { h.live = false; return Promise.resolve({value: undefined, done: true}); },
+      }),
+    };
+  };
+  return {stream, streams};
+}

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

@@ -0,0 +1,37 @@
+import {isStandardSchema, validateWith} from '../../standardSchema';
+import {toJsonSchema} from '../schema/index';
+import {unstrict} from '../schema/strict';
+
+/*
+ * PLAN-6 L-1 structured output (0-S4, G-604): a request's `output` is a Standard Schema with
+ * Standard JSON Schema (or 1-A's jsonSchema()). The transport sends `outputJsonSchema(output)`;
+ * the driver reads the reply text with `readOutput()` and puts the validated value on `ok`
+ * (a failure is the `error` reply with `issues`).
+ *
+ * The JSON Schema comes from A-1's schema module (toJsonSchema: the portable normalization,
+ * cached per schema object, `{ value }` wrapping; jsonSchema() for plain JSON Schema).
+ */
+
+/** the JSON Schema a transport sends for `output`: `{ schema, wrapped }` (a non-object root wrapped as `{ value }`), or undefined */
+export function outputJsonSchema(output: any): {schema: Record<string, any>; wrapped: boolean} | undefined {
+  const c = toJsonSchema(output);
+  return c.schema ? {schema: c.schema, wrapped: !!c.wrapped} : undefined;
+}
+
+const invalid = (message: string) => Object.assign(new Error(message), {name: 'ValidationError', issues: [{message}]});
+
+/**
+ * the structured output in a reply's text: JSON (a ```json fence allowed), unwrapped from
+ * `{ value }` when the schema was wrapped (a bare value accepted too), then validated. Nulls for
+ * keys the schema leaves optional and doesn't allow null for are dropped first (L-2: a transport's
+ * strict mode makes the model send them; small models send them too), as `undefined` would be
+ */
+export async function readOutput(output: any, text: string): Promise<any> {
+  let v: any;
+  const body = text.trim().replace(/^```(?:json)?\s*([\s\S]*?)\s*```$/, '$1');
+  try { v = JSON.parse(body); } catch (_) { throw invalid(`The structured output is not JSON: ${body.length > 80 ? body.slice(0, 80) + '…' : body}`); }
+  const js = outputJsonSchema(output);
+  if (js) v = unstrict(v, js.schema);
+  if (js?.wrapped && v && typeof v == 'object' && !Array.isArray(v) && Object.keys(v).length == 1 && 'value' in v) v = v.value;
+  return isStandardSchema(output) ? validateWith(output, v) : v;
+}

package/src/extra/ai/commandBar.ts

@@ -0,0 +1,281 @@
+/*
+ * PLAN-6 M-3: the `commandBar` behavior, "do one thing in this app" from one line of text, on a
+ * decision model instead of a chat model (Experiment 5: 8/8 with local `nimble`, ~570 ms).
+ *
+ *   TodoApp.uses = { cmd: commandBar({ input: '.command', decide: { url: '/api/decide', model: 'jev-latest' },
+ *     below: 0.6, escalate: 'assistant', approve: '.cmd-approve', deny: '.cmd-deny' }) }
+ *
+ * Slice (state.cmd): { text, status, command, pending, unsure, result, error }
+ * - text: the input's value (cleared when a command ran);
+ * - status: 'ready' | 'deciding' (the decision request is out) | 'running' (the action runs, or
+ *   waits for APPROVE / DENY) | 'error' (the decision request failed: `error`);
+ * - command: the command being handled (null when ready);
+ * - pending: the confirm info (AgentConfirmInfo) of a consequential action, else null;
+ * - unsure: why the last command wasn't run, for the view: `{ command, reason, tool, description,
+ *   target, label, confidence }` with reason 'confidence' (below `below`), 'no-action' (the model
+ *   picked "none of these"), 'target' (an item action without a clear item) or 'input' (the
+ *   action needs an argument the bar can't fill); null otherwise. With `escalate` the command
+ *   goes to the chat behavior instead (`result.escalated`);
+ * - result: the last outcome, `{ command, tool, input, ...AgentResult }` (ok, error, state, ...),
+ *   or `{ command, escalated: '<chat key>', reason, confidence }`; error: the last failure, else null.
+ *
+ * Actions ('cmd.X'): RUN (the input's Enter, or the form's submit, and a click of the optional
+ * `run` selector, D288; a string as data runs that command), APPROVE, DENY, DONE (a command ran: the result; a host entry 'cmd.DONE' runs after it).
+ * Internal: INPUT (typing), DECIDED / FAILED (the fetch driver's reply actions), ASK.
+ *
+ * One decision request per command (through the app's fetch driver, `decide()`), two questions:
+ * - action: a `choice` over the host's and its shown descendants' `agent` actions (D249; `agent:
+ *   [Comp, …]` narrows), keyed by tool name, described by the action's description, plus
+ *   `none` ("none of these"). An action whose input is one enum (or boolean) field becomes one
+ *   option per value (`todos_set_filter=done`), so the model picks the argument too;
+ * - target (only when an item action exists): a `choice` over the live Collection item keys,
+ *   described by `agent.label` (D258), plus `none`. User-entered labels (A-1's labelsUntrusted,
+ *   G-644) stay out of the criteria, which a model reads like instructions: the option is described
+ *   by kind and id, and its label goes into the decision's `state.labels` (option -> label).
+ * The decision `state` is `{ command, app, labels? }`, `app` being the `read` projections (A-1's context).
+ * Then the call runs through A-1's `call()` (validation, repair, no-op detection, cause 'agent',
+ * `confirm` → `pending` for a consequential action).
+ *
+ * Free text arguments (ADD's text): a decision model only picks among options, so the text is
+ * taken from the command by a heuristic, documented as one (G-634, freeText below): a quoted part
+ * ("…", '…', “…”) if there is one, else the command without its lead-in ("remind me to call mom" →
+ * "call mom", "put milk on my list" → "milk"); a question gives undefined. It is validated like any
+ * agent input. `freeText: (command, tool) => string | undefined` replaces it;
+ * undefined means "can't tell": the command is escalated (or `unsure`, reason 'input'). Actions with
+ * other inputs (numbers, several fields) are offered too, and escalated / unsure when picked: a
+ * chat model fills arguments, a decision model doesn't.
+ *
+ * It reaches the runtime through the shared link (./link.ts, D283), as `chat` does.
+ */
+import xs from 'xstream'
+import {defineBehavior} from '../behaviors'
+import {ABORT} from '../../shared'
+import {agentTools, labelsUntrusted} from './agent/index'
+import {decide as decideRequest} from './decide'
+import {linked, engineOf, checkLinked} from './link'
+
+interface Opt {tool: string; args?: any; free?: string; needs?: 1; description: string}
+interface Asked {command: string; opts: Map<string, Opt>; targets: Map<string, {name: string; id: any; label?: string}>; items: Map<string, {key: string; name: string}>}
+interface Engine {api: any; iv: any; k: string; o: any; tools?: any; asked?: Asked; turn: number; answer?: (ok: boolean) => void; stop(): void}
+
+const engineFor = (props: any, k: string, o: any): Engine | undefined => engineOf<Engine>(props, k, (api, iv) => {
+  const en: Engine = {api, iv, k, o, turn: 0, stop() { en.turn++; en.answer?.(false); en.tools?.stop() }}
+  return en
+})
+const dispatch = (e: Engine, type: string, data: any, cause: string) => e.api.dispatch(e.iv.id, e.k + '.' + type, data, cause)
+
+const toolsOf = (e: Engine) => e.tools ||= agentTools(e.api, {
+  from: e.iv.id,
+  ...(Array.isArray(e.o.agent) && {components: e.o.agent}),
+  confirm: (info: any) => new Promise<boolean>(resolve => {
+    const turn = e.turn
+    e.answer = ok => { e.answer = undefined; resolve(ok) }
+    turn === e.turn ? dispatch(e, 'ASK', info, 'reply') : e.answer(false)
+  }),
+})
+
+// G-634: the free-text heuristic's words. Fillers before the request, the verbs that ask to add
+// something, the nouns that name an entry, and a destination at the end ("… to my list")
+const FILLER = "please|pls|hey|ok(?:ay)?|so|just|(?:can|could|would|will) you|i(?: want| need| have|'d like| would like) to|let'?s|go ahead and|(?:do not|don'?t) forget to|remember to|make sure to"
+const VERBS = 'add|create|make|put|insert|append|include|new|remind|remember|note|track|jot(?: down)?|write(?: down)?|note down'
+const NOUNS = 'todo|to-do|task|item|entry|note|reminder'
+const words = (x: string) => x.toLowerCase().replace(/[^a-z' -]/g, '').trim()
+
+/**
+ * The documented heuristic (G-634): a quoted part if there is one; else the command without its
+ * lead-in, which is: fillers ("please", "can you", "I need to", "don't forget to"), then a verb
+ * asking to add (add, create, put, remind, jot down, …, or the first word of the action's
+ * `description`) with what follows it ("me to", "about", an article, "a new todo:", "a task to",
+ * "to my list:"; the last word of the description counts as a noun), and a destination at the end
+ * ("to the list", "on my shopping list"). A command with no verb keeps its words ("buy eggs").
+ * undefined ("can't tell": the command escalates) for a question or nothing left.
+ */
+export const freeText = (command: string, description = ''): string | undefined => {
+  const q = /"([^"]+)"|“([^”]+)”|'([^']+)'/.exec(command)
+  if (q) return (q[1] ?? q[2] ?? q[3]).trim() || undefined
+  const c = command.trim()
+  if (c.endsWith('?')) return
+  const d = words(description).split(/\s+/), v = d.length > 1 ? `|${d[0]}` : '', n = d.length > 1 ? `|${d[d.length - 1]}s?` : ''
+  const noun = `(?:(?:a|an|the|another|one|my)\\s+)?(?:new\\s+)?(?:${NOUNS}${n})\\b\\s*(?:(?::|-|to|that|saying|called|named)\\s+)?`
+  const list = `(?:to|on|onto|in|into)\\s+(?:the|my|our)\\s+(?:[\\w-]+\\s+)?(?:list|${NOUNS}${n})s?`
+  const t = c.replace(/[.!]+$/, '')
+    .replace(new RegExp(`^(?:(?:${FILLER})\\s+)*(?:(?:${VERBS}${v})\\b\\s*:?\\s*(?:(?:me|us)\\s+)?(?:${list}\\s*:\\s*|(?:to|that|about)\\s+)?(?:${noun}|(?:a|an|the)\\s+)?)?(?:${noun})?`, 'i'), '')
+    .replace(new RegExp(`\\s+(?:${list}|please|for me)$`, 'i'), '')
+  return t.trim() || undefined
+}
+
+/** the questions for `command` over the live tools; `e.asked` maps the answers back */
+function ask(e: Engine, command: string) {
+  const t = toolsOf(e), opts = new Map<string, Opt>(), items = new Map<string, {key: string; name: string}>()
+  const groups = new Map<string, string>(), bare = new Set<string>()
+  for (const g of t.groups()) {
+    for (const n of g.tools) groups.set(n, g.name)
+    if (labelsUntrusted(g)) bare.add(g.name)
+  }
+  const targets = t.targets()
+  const itemNames = new Set(targets.map((x: any) => x.name))
+  for (const tool of t.list()) {
+    if (tool.annotations.readOnlyHint) continue
+    const s = tool.inputSchema || {}, name = groups.get(tool.name) || ''
+    const props = {...s.properties}, req = new Set<string>(s.required || [])
+    if (itemNames.has(name) && s.required?.[0] && props[s.required[0]]?.enum) {
+      const key = s.required[0]
+      items.set(tool.name, {key, name})
+      delete props[key]
+      req.delete(key)
+    }
+    const fields = Object.keys(props), base = {tool: tool.name, description: tool.description}
+    const f = fields.length == 1 ? fields[0] : '', p = f && props[f]
+    // one option per value: an enum, a boolean, or `anyOf` consts (described literals: their own descriptions)
+    const values: any[] | null = !p ? null : Array.isArray(p.enum) ? p.enum.map((v: any) => [v]) : p.type == 'boolean' ? [[true], [false]]
+      : Array.isArray(p.anyOf) && p.anyOf.every((x: any) => x && 'const' in x) ? p.anyOf.map((x: any) => [x.const, x.description]) : null
+    if (!fields.length || (!req.size && !values)) opts.set(tool.name, {...base, args: {}})
+    else if (values) for (const [v, d] of values) opts.set(`${tool.name}=${v}`, {...base, args: {[f]: v}, description: d || `${tool.description}: ${v}`})
+    else if (p && p.type == 'string') opts.set(tool.name, {...base, free: f})
+    else opts.set(tool.name, {...base, needs: 1})
+  }
+  const many = new Set(targets.map((x: any) => x.name)).size > 1, tmap = new Map<string, any>()
+  for (const x of targets) tmap.set(many ? `${x.name} ${x.id}` : String(x.id), x)
+  const kinds = [...new Set(targets.map((x: any) => x.name))]
+  const questions: any = {
+    action: {type: 'choice', instructions: 'Which app action does the command ask for?',
+      criteria: {...Object.fromEntries([...opts].map(([k, v]) => [k, v.description])), none: 'None of these actions'}},
+  }
+  // G-644: user-entered labels are data: they go into the decision's `state` (`labels`: option ->
+  // label), and the criteria (read like instructions) name the option by kind and id only
+  const labels: Record<string, string> = {}
+  if (items.size && tmap.size) {
+    const what = kinds.length == 1 ? kinds[0] : 'item'
+    const desc = (k: string, x: any) => {
+      if (x.label == null) return `${x.name} ${x.id}`
+      if (!bare.has(x.name)) return x.label
+      labels[k] = x.label
+      return `The ${x.name} with id ${x.id} (its label: state.labels["${k}"])`
+    }
+    questions.target = {type: 'choice', instructions: `Which existing ${what} does the command refer to (none if it names no existing ${what})?`
+      + (bare.size ? " Each option's label is in state.labels." : ''),
+      criteria: {none: `No existing ${what}`, ...Object.fromEntries([...tmap].map(([k, x]) => [k, desc(k, x)]))}}
+  }
+  e.asked = {command, opts, targets: tmap, items}
+  const ctx = t.context()
+  return {questions, state: {command, ...(Object.keys(ctx).length && {app: ctx}), ...(Object.keys(labels).length && {labels})}}
+}
+
+/** one step's outcome per (slice, data): STATE and the sink / EFFECT of an action read the same one */
+const memo = (f: (s: any, d: any, e?: Engine) => 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]
+}
+const busy = (s: any) => s.status == 'deciding' || s.status == 'running'
+const commandOf = (s: any, d: any) => (typeof d == 'string' ? d : s.text).trim()
+
+const runStep = /*#__PURE__*/ memo((s, d, e) => {
+  const command = commandOf(s, d)
+  if (busy(s) || !command) return
+  const next = {...s, status: 'deciding', command, unsure: null, error: null, pending: null}
+  if (!e) return {s: {...next, status: 'error', command: null, error: 'the command bar is not connected to its app (SYG442)'}}
+  e.turn++
+  return {s: next, ...ask(e, command)}
+})
+
+/** what a decision means: run a tool, or why not */
+const planStep = /*#__PURE__*/ memo((s, d, e) => {
+  const asked = e?.asked
+  if (s.status != 'deciding' || !asked || asked.command !== s.command) return
+  const o = e!.o, below = o.below ?? 0.6, command = asked.command
+  const a = d?.answers?.action, tg = d?.answers?.target
+  const opt = a && asked.opts.get(a.choice)
+  const item = opt && asked.items.get(opt.tool)
+  const target = item && tg && asked.targets.get(tg.choice)
+  let reason: string | undefined, args: any
+  if (!opt) reason = 'no-action'
+  else if (!(a.confidence >= below)) reason = 'confidence'
+  else if (item && (!target || target.name !== item.name || !(tg.confidence >= below))) reason = 'target'
+  else if (opt.needs) reason = 'input'
+  else if (opt.free) {
+    const x = o.freeText ? o.freeText(command, opt.tool) : freeText(command, opt.description)
+    if (typeof x != 'string' || !x) reason = 'input'
+    else args = {[opt.free]: x}
+  } else args = opt.args
+  const why = {tool: opt?.tool ?? null, description: opt?.description ?? null, target: target?.id ?? null, label: target?.label ?? null,
+    confidence: reason == 'target' ? tg?.confidence ?? 0 : a?.confidence ?? 0}
+  if (reason) {
+    return o.escalate
+      ? {s: {...s, status: 'ready', command: null, result: {command, escalated: o.escalate, reason, ...why}}, escalate: command}
+      : {s: {...s, status: 'ready', command: null, unsure: {command, reason, ...why}}}
+  }
+  if (item) args = {...args, [item.key]: target!.id}
+  return {s: {...s, status: 'running'}, call: {tool: opt.tool, input: args}}
+})
+
+async function runCall(e: Engine, command: string, c: {tool: string; input: any}) {
+  const turn = e.turn
+  let r: any
+  try { r = await toolsOf(e).call(c.tool, c.input) } catch (err: any) { r = {ok: false, error: String(err?.message ?? err)} }
+  if (turn === e.turn) dispatch(e, 'DONE', {command, ...c, ...r}, 'reply')
+}
+
+/**
+ * The command bar behavior (PLAN-6 M-3): `uses = { cmd: commandBar({ input, form, run, decide, below,
+ * escalate, agent, sink, approve, deny, freeText }) }`. Types: src/ai.d.ts.
+ */
+export const commandBar = (options: any = {}): any => {
+  const {sink = 'HTTP', input, form, run, approve, deny} = options
+  const on = (DOM: any, sel: any, ev = 'click', o?: any) => DOM.select(sel).events(ev, o)
+  const E = engineFor
+  const b = defineBehavior({
+    initialState: {text: '', status: 'ready', command: null, pending: null, unsure: null, result: null, error: null},
+    intent: (so: any) => {
+      const {DOM} = so
+      checkLinked(so, 'commandBar', 'it runs no commands')
+      // Enter in the field runs it (a form's submit instead when `form` is given); D288: and a
+      // click of `run` (a Go button: the field's text)
+      const runs = [
+        form ? on(DOM, form, 'submit', {preventDefault: true})
+          : input && on(DOM, input, 'keydown').filter((ev: any) => ev.key === 'Enter' && !ev.isComposing).map((ev: any) => { ev.preventDefault?.(); return typeof ev.target?.value == 'string' ? ev.target.value : undefined }),
+        run && on(DOM, run).mapTo(undefined),
+      ].filter(Boolean)
+      return {
+        ...(input && {INPUT: on(DOM, input, 'input').map((ev: any) => ev.target.value)}),
+        ...(runs.length && {RUN: runs.length == 1 ? runs[0] : xs.merge(...runs)}),
+        ...(approve && {APPROVE: on(DOM, approve)}),
+        ...(deny && {DENY: on(DOM, deny)}),
+      }
+    },
+    model: {
+      INPUT: (s: any, v: any) => typeof v == 'string' && v !== s.text ? {...s, text: v} : ABORT,
+      RUN: {
+        STATE: (s: any, d: any, _n: any, p: any, o: any, k: string) => runStep(s, d, E(p, k, o))?.s || ABORT,
+        [sink]: (s: any, d: any, _n: any, p: any, o: any, k: string) => {
+          const r = runStep(s, d, E(p, k, o))
+          if (!r?.questions) return ABORT
+          const keys = {ok: k + '.DECIDED', error: k + '.FAILED'}
+          return typeof o.decide == 'function' ? {...o.decide({state: r.state, questions: r.questions}), ...keys}
+            : decideRequest({...o.decide, state: r.state, questions: r.questions, ...keys})
+        },
+      },
+      DECIDED: {
+        STATE: (s: any, d: any, _n: any, p: any, o: any, k: string) => planStep(s, d, E(p, k, o))?.s || ABORT,
+        EFFECT: (s: any, d: any, next: any, p: any, o: any, k: string) => {
+          const e = E(p, k, o), r = planStep(s, d, e)
+          if (r?.call) void runCall(e!, s.command, r.call)
+          else if (r?.escalate) next(o.escalate + '.SEND', r.escalate)
+        },
+      },
+      FAILED: (s: any, d: any) => s.status == 'deciding' ? {...s, status: 'error', command: null, error: d?.error?.message ?? String(d?.error ?? 'error')} : ABORT,
+      ASK: (s: any, info: any) => ({...s, pending: info}),
+      APPROVE: {
+        STATE: (s: any) => s.pending ? {...s, pending: null} : ABORT,
+        EFFECT: (_s: any, _d: any, _n: any, p: any, o: any, k: string) => { E(p, k, o)?.answer?.(true) },
+      },
+      DENY: {
+        STATE: (s: any) => s.pending ? {...s, pending: null} : ABORT,
+        EFFECT: (_s: any, _d: any, _n: any, p: any, o: any, k: string) => { E(p, k, o)?.answer?.(false) },
+      },
+      // a command ran (or was refused): the result; the input is cleared when it was this command
+      DONE: (s: any, d: any) => s.status != 'running' ? ABORT
+        : {...s, status: 'ready', command: null, pending: null, result: d, text: d?.ok && s.text.trim() === d.command ? '' : s.text},
+    },
+  })(options)
+  return linked(b)
+}

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