sygnal 6.0.0 → 6.1.0

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

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

@@ -0,0 +1,152 @@
+import {resolve, walk, isObj} from './index';
+
+/*
+ * PLAN-6 L-2 (0-S4 layer 2, D266, D285): the opt-in strict schema layer of the OpenAI- and
+ * Anthropic-backed transports. Apps opt in with an import (`openResponses({ strict:
+ * strictSchemas })`), so the transports don't carry it otherwise (≈ 1.1 KB, D285); unstrict is
+ * also used by the chat driver's structured output (./chat/output.ts), where it is always safe.
+ *
+ * strictSchemas(schema, dialect) turns a portable tool / output schema (./index.ts normalize)
+ * into a provider's strict subset; both walk with A-1's map-aware `walk` (G-629):
+ * - 'openai' (developers.openai.com structured outputs, "Supported schemas", 2026-10):
+ *   `additionalProperties: false` on every object, every property required, the optional ones
+ *   made nullable (a type array + null in the enum, or `anyOf [..., { type: 'null' }]`);
+ *   unsupported keywords and formats moved into the description as JSON (the model still reads
+ *   them; validation still enforces them), a tuple's `prefixItems` turned into `items: { anyOf }`.
+ * - 'anthropic' (platform.claude.com structured outputs; the subset @anthropic-ai/sdk's
+ *   transformJSONSchema keeps): `additionalProperties: false` on every object, `required` as is
+ *   (optional keys stay optional), and only type, anyOf (oneOf), allOf, $ref/$defs, enum, const,
+ *   description, title, properties, required, items, the supported formats and `minItems` 0/1
+ *   kept; the rest (numeric and string bounds, pattern, other array constraints) moved into the
+ *   description. A recursive schema or an untyped (any) value has no strict form.
+ * Both return `errors` when the schema has no strict form (a record: `additionalProperties` with a
+ * schema; a non-object root): the transport then sends that tool non-strict (SYG675, dev info),
+ * and `optional` / `unions` (the counts Anthropic limits per request, G-609).
+ *
+ * unstrict(value, schema) drops the nulls a strict schema forced the model to send for keys the
+ * original schema leaves optional and doesn't allow null for, so validation sees the original
+ * shape. The transports run it on every tool call they sent strict.
+ */
+
+export type StrictDialect = 'openai' | 'anthropic';
+export interface Strictified {schema: any; errors: string[]; optional: number; unions: number}
+/** what a request has left of a provider's per-request strict limits (Anthropic, G-609) */
+export interface StrictLimits {tools: number; optional: number; unions: number}
+
+const DROP = ['allOf', 'not', 'if', 'then', 'else', 'dependentRequired', 'dependentSchemas', 'patternProperties',
+  'unevaluatedProperties', 'propertyNames', 'minProperties', 'maxProperties', 'unevaluatedItems', 'contains',
+  'minContains', 'maxContains', 'uniqueItems', 'default', 'examples', 'title'];
+const FORMATS = ['date-time', 'time', 'date', 'duration', 'email', 'hostname', 'ipv4', 'ipv6', 'uuid'];
+// Anthropic's subset (the keywords @anthropic-ai/sdk's transformJSONSchema keeps)
+const KEEP = /^(type|anyOf|allOf|\$ref|\$defs|enum|const|description|title|properties|required|additionalProperties|items)$/;
+const ANT_FORMATS = /^(date-time|time|date|duration|email|hostname|uri|ipv4|ipv6|uuid)$/;
+
+/** one schema object into Anthropic's subset, in place (oneOf -> anyOf): the keywords it moved out */
+export function anthropicKeywords(o: any): any {
+  const moved: any = {};
+  if (o.oneOf && !o.anyOf) { o.anyOf = o.oneOf; delete o.oneOf; }
+  for (const k in o) if (k == 'format' ? !ANT_FORMATS.test(o[k]) : k == 'minItems' ? o[k] > 1 : !KEEP.test(k)) { moved[k] = o[k]; delete o[k]; }
+  return moved;
+}
+
+// the moved keywords as JSON at the end of the description: the model still reads them, validation still enforces them
+const describe = (o: any, moved: any) => {
+  if (Object.keys(moved).length) {
+    const hint = JSON.stringify(moved);
+    o.description = o.description ? o.description + ' ' + hint : hint;
+  }
+  return o;
+};
+
+/**
+ * G-635: the light, always-on pass anthropicMessages() runs on a non-strict `output` schema
+ * (`output_config.format` is always constrained decoding, and a keyword outside Anthropic's subset
+ * is a 400): Anthropic's keywords only (the rest moved into the description), and
+ * `additionalProperties: false` on every object that isn't a record. No limits, no errors.
+ */
+export const anthropicCompatible = (schema: any): any => walk(schema, o => {
+  const moved = anthropicKeywords(o);
+  if ((o.type == 'object' || o.properties) && !isObj(o.additionalProperties)) o.additionalProperties = false;
+  return describe(o, moved);
+});
+
+const nullable = (p: any): any => {
+  const t = p.type, withEnum = (o: any) => p.enum ? {...o, enum: [...p.enum, null]} : o;
+  if (Array.isArray(t)) return t.includes('null') ? p : withEnum({...p, type: [...t, 'null']});
+  if (typeof t == 'string' && !p.$ref) return withEnum({...p, type: [t, 'null']});
+  if (p.anyOf) return p.anyOf.some((b: any) => b.type == 'null') ? p : {...p, anyOf: [...p.anyOf, {type: 'null'}]};
+  const {description, ...rest} = p;
+  return {anyOf: [rest, {type: 'null'}], ...(description && {description})};
+};
+
+// a `$defs` entry that reaches itself through `$ref`s (or a `#` root reference)
+const recursive = (s: any): boolean => {
+  const defs = s.$defs || {}, refs = (x: any): string[] => [...JSON.stringify(x ?? null).matchAll(/"\$ref":"#(?:\/\$defs\/([^"]*))?"/g)].map(m => m[1] ?? '#');
+  const to = (a: string, b: string, seen: Set<string>): boolean => !seen.has(a) && (seen.add(a), refs(defs[a]).some(n => n == b || (n in defs && to(n, b, seen))));
+  return refs(s).includes('#') || Object.keys(defs).some(k => to(k, k, new Set()));
+};
+
+/**
+ * `{ schema, errors, optional, unions }`: a provider's strict form of a portable schema, or why
+ * there is none. `left` (the transports'): what the request has left of the provider's
+ * per-request limits; a schema that fits is counted against it (`tool`: it is a tool), one that
+ * doesn't gets an error
+ */
+export function strictSchemas(schema: any, dialect: StrictDialect = 'openai', left?: StrictLimits, tool?: boolean): Strictified {
+  const errors: string[] = [], ant = dialect == 'anthropic';
+  let optional = 0, unions = 0;
+  if (schema?.type != 'object') errors.push('the root is not an object');
+  if (ant && schema && recursive(schema)) errors.push('a recursive schema has no strict form');
+  const out = walk(schema, o => {
+    let moved: any = {};
+    if (ant) {
+      moved = anthropicKeywords(o);
+      if (!o.type && !o.anyOf && !o.allOf && !o.$ref && !o.enum && !('const' in o) && !o.properties) errors.push('a value of any type has no strict form');
+    } else {
+      for (const k of DROP) if (k in o) { moved[k] = o[k]; delete o[k]; }
+      if (o.format && !FORMATS.includes(o.format)) { moved.format = o.format; delete o.format; }
+      if (o.prefixItems) { moved.prefixItems = 'tuple'; o.items = {anyOf: o.prefixItems}; delete o.prefixItems; }
+    }
+    if (o.items === false) delete o.items;
+    if (o.type == 'object' || o.properties) {
+      if (o.additionalProperties && o.additionalProperties !== false) errors.push('a record (additionalProperties with a schema) has no strict form');
+      const props = o.properties ||= {}, req = new Set(o.required || []);
+      for (const k in props) {
+        const p = props[k];
+        if (p?.anyOf || Array.isArray(p?.type)) unions++;
+        if (!req.has(k)) { optional++; if (!ant) props[k] = nullable(p); }
+      }
+      if (!ant) o.required = Object.keys(props);
+      o.additionalProperties = false;
+    }
+    return describe(o, moved);
+  });
+  if (left && !errors.length) {
+    if ((tool && left.tools < 1) || left.optional < optional || left.unions < unions) errors.push('over the per-request strict limits (20 tools, 24 optional and 16 union-typed parameters)');
+    else { if (tool) left.tools--; left.optional -= optional; left.unions -= unions; }
+  }
+  return {schema: out, errors, optional, unions};
+}
+
+const acceptsNull = (p: any, root: any): boolean => {
+  p = p?.$ref ? resolve(p, root) : p;
+  return !!p && (p.type == 'null' || (Array.isArray(p.type) && p.type.includes('null')) || (p.enum || []).includes(null) ||
+    p.const === null || (p.anyOf || p.oneOf || []).some((b: any) => acceptsNull(b, root)));
+};
+
+/** strict-mode JSON -> what the original schema accepts: nulls for optional, non-nullable keys dropped */
+export function unstrict(value: any, schema: any, root: any = schema): any {
+  if (schema?.$ref) schema = resolve(schema, root);
+  if (!schema || value == null || typeof value != 'object') return value;
+  if (Array.isArray(value)) return schema.items ? value.map(x => unstrict(x, schema.items, root)) : value;
+  const out = {...value};
+  for (const b0 of schema.anyOf || schema.oneOf || [schema]) {
+    const b = b0?.$ref ? resolve(b0, root) : b0, req = new Set(b?.required || []);
+    for (const k in b?.properties) {
+      if (!(k in out)) continue;
+      if (out[k] === null && !req.has(k) && !acceptsNull(b.properties[k], root)) delete out[k];
+      else out[k] = unstrict(out[k], b.properties[k], root);
+    }
+  }
+  return out;
+}

package/src/extra/ai/transports/agui.ts

@@ -0,0 +1,177 @@
+import {post, sse, json, partsOf, toolName, toolOutput} from './shared';
+import type {HttpOptions} from './shared';
+import {outputJsonSchema} from '../chat/output';
+
+/*
+ * PLAN-6 L-2 (wave 2): agui(url, { threadId?, state?, context?, headers?, fetch?, body?,
+ * dangerouslyAllowBrowser? }), a chat transport for an AG-UI agent endpoint (the Agent-User
+ * Interaction protocol: TanStack AI, CopilotKit runtimes, LangGraph / Mastra / Pydantic AI
+ * servers), checked against @ag-ui/core 1.0.2's types. POST `url` with a RunAgentInput, SSE back
+ * (`data: <event JSON>`).
+ *
+ * Request (RunAgentInput): `threadId` (the request's `chatId`, the option, or one per transport),
+ * a new `runId`, `state` (the request's `state`, else the latest state this transport saw, else
+ * the option, else {}), `messages` (the instructions as a system message; user / assistant / tool
+ * messages: an assistant message per step with its `toolCalls`, a `tool` message per result),
+ * `tools` (`{ name, description, parameters }`: client tools the agent may call), `context` (the
+ * option), `forwardedProps` (`{ model?, output? }`: the requested model and the `output` JSON
+ * Schema, for servers that use them); `body` merged in.
+ *
+ * Events -> ChatEvents:
+ * - TEXT_MESSAGE_START / CONTENT / CHUNK -> start (the first message id) and text (messages with a
+ *   role other than assistant are skipped); REASONING_MESSAGE_CONTENT / CHUNK -> reasoning;
+ * - TOOL_CALL_START / ARGS / END (or CHUNK) -> a tool call, held until the step ends: a call the
+ *   agent answers (TOOL_CALL_RESULT) is yielded `executed` + its result (the app doesn't run it), a
+ *   call still open at STEP_FINISHED / RUN_FINISHED / the end of the stream (or when a new message
+ *   starts) is a client tool call (the `tool` reply);
+ * - STATE_SNAPSHOT / STATE_DELTA (RFC 6902, applied here) -> a `data-agui-state` part (id
+ *   'state', so it replaces the previous one) holding the agent's whole current state;
+ *   MESSAGES_SNAPSHOT -> a `data-agui-messages` part (id 'messages') with the agent's messages as
+ *   sent (the app decides whether to adopt them); ACTIVITY_SNAPSHOT -> a `data-agui-activity` part
+ *   (id: its message id);
+ * - RUN_FINISHED -> finish ('tool-calls' after client calls, 'other' for an interrupt outcome,
+ *   else 'stop'; usage summed); RUN_ERROR -> a thrown Error. Everything else is ignored.
+ */
+
+export interface AguiOptions extends HttpOptions {
+  threadId?: string;
+  state?: unknown;
+  context?: Array<{description: string; value: string}>;
+}
+
+let n = 0;
+const uid = (p: string) => `${p}_${Date.now().toString(36)}_${++n}`;
+const clone = (v: any) => v === undefined ? v : JSON.parse(JSON.stringify(v));
+
+/** RFC 6902 JSON Patch (add, remove, replace, move, copy; test ignored) on a copy of `doc` */
+export function applyPatch(doc: any, ops: any[]): any {
+  let root = clone(doc ?? {});
+  const keys = (p: string) => p.split('/').slice(1).map(s => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+  const get = (k: string[]) => k.reduce((o, x) => o?.[x], root);
+  const set = (k: string[], v: any, insert: boolean) => {
+    if (!k.length) { root = v; return; }
+    const parent = get(k.slice(0, -1)), last = k[k.length - 1];
+    if (Array.isArray(parent)) last == '-' ? parent.push(v) : insert ? parent.splice(+last, 0, v) : (parent[+last] = v);
+    else if (parent && typeof parent == 'object') parent[last] = v;
+  };
+  const del = (k: string[]) => {
+    const parent = get(k.slice(0, -1)), last = k[k.length - 1], v = parent?.[last];
+    if (Array.isArray(parent)) parent.splice(+last, 1); else if (parent) delete parent[last];
+    return v;
+  };
+  for (const op of ops || []) {
+    const to = keys(String(op.path ?? ''));
+    if (op.op == 'add') set(to, clone(op.value), true);
+    else if (op.op == 'replace') set(to, clone(op.value), false);
+    else if (op.op == 'remove') del(to);
+    else if (op.op == 'move') set(to, del(keys(op.from)), true);
+    else if (op.op == 'copy') set(to, clone(get(keys(op.from))), true);
+  }
+  return root;
+}
+
+const textOf = (m: any) => partsOf(m).filter(p => p.type == 'text').map(p => p.text).join('');
+
+/** a message as AG-UI messages (an assistant message per step with its toolCalls, then a tool message per result) */
+export function toAgui(m: any, i: number): any[] {
+  const id = m.id ?? `m${i}`;
+  if (m.role != 'assistant') {
+    const files = partsOf(m).filter(p => p.type == 'file');
+    const text = textOf(m);
+    return [{id, role: m.role, content: files.length && m.role == 'user'
+      ? [...(text ? [{type: 'text', text}] : []), ...files.map(p => ({type: p.mediaType?.startsWith('image/') ? 'image' : 'document', source: {type: 'url', value: p.url, mimeType: p.mediaType}}))]
+      : text}];
+  }
+  const out: any[] = [];
+  let text = '', calls: any[] = [], results: any[] = [], step = 0;
+  const flush = () => {
+    if (text || calls.length) out.push({id: step ? `${id}_${step}` : id, role: 'assistant', ...(text && {content: text}), ...(calls.length && {toolCalls: calls})});
+    out.push(...results);
+    if (text || calls.length) step++;
+    text = ''; calls = []; results = [];
+  };
+  for (const p of partsOf(m)) {
+    const name = toolName(p);
+    if (p.type == 'text') { if (calls.length) flush(); text += p.text; }
+    else if (name && p.input !== undefined) {
+      calls.push({id: p.toolCallId, type: 'function', function: {name, arguments: JSON.stringify(p.input ?? {})}});
+      const o = toolOutput(p);
+      if (o !== undefined) results.push({id: `${p.toolCallId}_result`, role: 'tool', toolCallId: p.toolCallId, content: o, ...(p.state == 'output-error' && {error: p.errorText ?? 'error'})});
+    }
+  }
+  flush();
+  return out;
+}
+
+export function agui(url: string, options: AguiOptions = {}) {
+  const thread = options.threadId ?? uid('thread');
+  let state: any = options.state;
+  const headers = async (req: any) => ({accept: 'text/event-stream', ...(typeof options.headers == 'function' ? await options.headers(req) : options.headers)});
+  return {
+    async *stream(req: any, signal: AbortSignal): AsyncGenerator<any, void, any> {
+      const o = req.output !== undefined ? outputJsonSchema(req.output) : undefined;
+      const res = await post(url, {
+        threadId: req.chatId ?? thread,
+        runId: uid('run'),
+        state: req.state ?? state ?? {},
+        messages: [...(req.instructions ? [{id: 'instructions', role: 'system', content: req.instructions}] : []), ...req.messages.flatMap(toAgui)],
+        tools: Object.entries(req.tools || {}).map(([name, t]: [string, any]) => ({name, description: t?.description ?? '', parameters: t?.inputSchema ?? {type: 'object', properties: {}}})),
+        context: options.context ?? [],
+        forwardedProps: {...(req.model && {model: req.model}), ...(o && {output: o})},
+      }, req, signal, {...options, headers}, 'agui');
+      // tool calls by id as they stream; `open`: ended calls not yet answered, in order
+      const calls: Record<string, any> = {}, roles: Record<string, string> = {};
+      let open: any[] = [], last: any, started = false, called = 0;
+      const start = function* (id: any) { if (!started && id) { started = true; yield {type: 'start', id}; } };
+      const release = function* () { for (const c of open) { called++; yield c; } open = []; };
+      const take = (id: string) => {
+        const i = open.findIndex(c => c.id === id);
+        return i < 0 ? [] : [{...open.splice(i, 1)[0], executed: true}];
+      };
+      const end = (id: string) => {
+        const c = calls[id];
+        if (!c || c.done) return;
+        c.done = 1;
+        open.push({type: 'tool-call', id, name: c.name, input: json(c.args || '{}')});
+      };
+      for await (const {data} of sse(res)) {
+        const e = json(data), t = e?.type;
+        if (typeof t != 'string') continue;
+        if (t == 'TEXT_MESSAGE_START') { roles[e.messageId] = e.role ?? 'assistant'; yield* release(); yield* start(e.messageId); }
+        else if (t == 'TEXT_MESSAGE_CONTENT' || t == 'TEXT_MESSAGE_CHUNK') {
+          if (t == 'TEXT_MESSAGE_CHUNK' && e.role) roles[e.messageId] = e.role;
+          if ((roles[e.messageId] ?? 'assistant') == 'assistant' && e.delta) { yield* release(); yield* start(e.messageId); yield {type: 'text', delta: e.delta}; }
+        } else if (t == 'REASONING_MESSAGE_CONTENT' || t == 'REASONING_MESSAGE_CHUNK') { if (e.delta) yield {type: 'reasoning', delta: e.delta}; }
+        else if (t == 'TOOL_CALL_START') { yield* start(e.parentMessageId); calls[e.toolCallId] = {name: e.toolCallName, args: ''}; last = e.toolCallId; }
+        else if (t == 'TOOL_CALL_ARGS') { if (calls[e.toolCallId]) calls[e.toolCallId].args += e.delta ?? ''; }
+        else if (t == 'TOOL_CALL_CHUNK') {
+          const id = e.toolCallId ?? last;
+          if (e.toolCallId && e.toolCallId != last) { if (last) end(last); yield* start(e.parentMessageId); }
+          const c = calls[id] ||= {name: e.toolCallName, args: ''};
+          if (e.toolCallName) c.name = e.toolCallName;
+          c.args += e.delta ?? '';
+          last = id;
+        } else if (t == 'TOOL_CALL_END') end(e.toolCallId);
+        else if (t == 'TOOL_CALL_RESULT') {
+          end(e.toolCallId);
+          yield* take(e.toolCallId);
+          yield {type: 'tool-result', id: e.toolCallId, output: typeof e.content == 'string' ? json(e.content) : e.content};
+        } else if (t == 'STATE_SNAPSHOT' || t == 'STATE_DELTA') {
+          state = t == 'STATE_SNAPSHOT' ? e.snapshot : applyPatch(state, e.delta);
+          yield {type: 'data-agui-state', id: 'state', data: state};
+        } else if (t == 'MESSAGES_SNAPSHOT') yield {type: 'data-agui-messages', id: 'messages', data: e.messages};
+        else if (t == 'ACTIVITY_SNAPSHOT') yield {type: 'data-agui-activity', id: e.messageId, data: {activityType: e.activityType, content: e.content}};
+        else if (t == 'STEP_FINISHED') { if (last) end(last); yield* release(); }
+        else if (t == 'RUN_FINISHED') {
+          for (const id in calls) end(id);
+          yield* release();
+          const u = (e.usage || []).reduce((a: any, x: any) => ({inputTokens: a.inputTokens + (x.inputTokens ?? 0), outputTokens: a.outputTokens + (x.outputTokens ?? 0), totalTokens: a.totalTokens + (x.totalTokens ?? (x.inputTokens ?? 0) + (x.outputTokens ?? 0))}), {inputTokens: 0, outputTokens: 0, totalTokens: 0});
+          yield {type: 'finish', reason: e.outcome?.type == 'interrupt' ? 'other' : called ? 'tool-calls' : 'stop', ...(e.usage?.length && {usage: u})};
+          return;
+        } else if (t == 'RUN_ERROR') throw Object.assign(new Error('agui: ' + (e.message ?? 'the run failed')), {code: e.code});
+      }
+      for (const id in calls) end(id);
+      yield* release();
+    },
+  };
+}