sygnal 5.4.0 → 6.1.0

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();
+    },
+  };
+}

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

@@ -0,0 +1,175 @@
+import {post, sse, json, partsOf, toolName, toolOutput} from './shared';
+import type {HttpOptions} from './shared';
+import {prepare} from './tools';
+import type {StrictOption} from './tools';
+import {anthropicCompatible} from '../schema/strict';
+
+/*
+ * PLAN-6 L-2 (wave 2): anthropicMessages({ baseURL?, model, maxTokens?, headers?, fetch?, body?,
+ * strict?, serverTools?, dangerouslyAllowBrowser? }), a chat transport for Anthropic's Messages
+ * API SSE (checked against @anthropic-ai/sdk 0.131.0's types): Claude through the app's proxy,
+ * or Ollama's Anthropic-compatible endpoint. POST `${baseURL}/messages` (baseURL default '/v1')
+ * with `stream: true`, `anthropic-version: 2023-06-01` (and
+ * `anthropic-dangerous-direct-browser-access` with dangerouslyAllowBrowser).
+ *
+ * Request: `instructions` and `system` messages as `system`; user / assistant messages as content
+ * blocks (text; images and PDFs as image / document blocks from a URL or a data URL; signed
+ * reasoning parts as thinking / redacted_thinking; a tool part with a result as a tool_use block
+ * in the assistant message and a tool_result block in a user message after it, one assistant
+ * message per step; a server tool part as server_tool_use + its result block as received;
+ * consecutive messages of one role merged); `tools` as custom tools (`input_schema`), plus
+ * `serverTools` (Anthropic server tools, e.g. `{ type: 'web_search_20260209', name: 'web_search' }`)
+ * as is; `output` as `output_config.format` json_schema; `max_tokens` from the request's
+ * `maxTokens`, the option, or 16000; `body` merged in.
+ *
+ * Strict (D266, D285): `strict: strictSchemas` sends tools `strict: true` with schemas in
+ * Anthropic's subset and the `output` schema in it; a schema without a strict form, or one over
+ * Anthropic's per-request limits (20 strict tools, 24 optional and 16 union-typed parameters
+ * across the strict schemas, G-609), is sent non-strict on its own (SYG675).
+ *
+ * Compatibility (G-635, always on): `output_config.format` is always constrained decoding, so a
+ * non-strict `output` schema goes through anthropicCompatible() (../schema/strict.ts): keywords
+ * outside Anthropic's subset (numeric / string bounds, pattern, uniqueItems, not, if/then, ...)
+ * move into the description, oneOf becomes anyOf, objects get `additionalProperties: false`. The
+ * driver validates the reply against the original schema. Non-strict tools' `input_schema` is sent
+ * as is: the API takes any JSON Schema (draft 2020-12) there, and the keywords guide the model
+ * (A-1's normalization already makes the root an object, which the API requires).
+ *
+ * Events: message_start -> start (the message id, input usage); text_delta -> text;
+ * thinking_delta -> reasoning, and its signature (signature_delta) closes the part with
+ * `providerMetadata: { anthropic: { signature } }` (a redacted_thinking block: `{ redactedData }`)
+ * so the next request can send it back (Claude requires it in a tool loop); tool_use with its
+ * input_json_delta -> a tool call at content_block_stop; server_tool_use -> an `executed` tool
+ * call, its `*_tool_result` block -> that call's result (the block itself); message_delta ->
+ * the stop reason and output usage; message_stop (or the end of the stream) -> finish; an
+ * `error` event -> a thrown Error. Citations and unknown events are ignored.
+ */
+
+export interface AnthropicMessagesOptions extends HttpOptions {
+  baseURL?: string;
+  model?: string;
+  maxTokens?: number;
+  strict?: StrictOption;
+  serverTools?: any[];
+}
+
+const REASONS: Record<string, string> = {end_turn: 'stop', stop_sequence: 'stop', pause_turn: 'stop', tool_use: 'tool-calls', max_tokens: 'length', model_context_window_exceeded: 'length', refusal: 'content-filter'};
+// G-609: platform.claude.com structured outputs, "Schema complexity limits"
+const LIMITS = {tools: 20, optional: 24, unions: 16};
+const DATA = /^data:([^;,]+)(;base64)?,(.*)$/;
+
+const source = (url: string) => {
+  const m = DATA.exec(url);
+  return m && m[2] ? {type: 'base64', media_type: m[1], data: m[3]} : {type: 'url', url};
+};
+
+/** a message as Anthropic messages (an assistant message with tool results: one per step, results in user messages) */
+export function toAnthropic(m: any): any[] {
+  const out: any[] = [];
+  let content: any[] = [], results: any[] = [];
+  const flush = () => {
+    if (content.length) out.push({role: m.role, content});
+    if (results.length) out.push({role: 'user', content: results});
+    content = []; results = [];
+  };
+  for (const p of partsOf(m)) {
+    const name = toolName(p), meta = p.providerMetadata?.anthropic;
+    if (results.length && !(name && p.input !== undefined)) flush();
+    if (p.type == 'text') content.push({type: 'text', text: p.text});
+    else if (p.type == 'file' && m.role == 'user') {
+      const image = p.mediaType?.startsWith('image/');
+      if (image || p.mediaType == 'application/pdf') content.push({type: image ? 'image' : 'document', source: source(p.url)});
+    } else if (p.type == 'reasoning' && m.role == 'assistant' && meta) {
+      if (meta.signature) content.push({type: 'thinking', thinking: p.text, signature: meta.signature});
+      else if (meta.redactedData) content.push({type: 'redacted_thinking', data: meta.redactedData});
+    } else if (name && p.input !== undefined && m.role == 'assistant') {
+      if (p.providerExecuted) {
+        content.push({type: 'server_tool_use', id: p.toolCallId, name, input: p.input});
+        if (/_tool_result$/.test(p.output?.type)) content.push(p.output);
+        continue;
+      }
+      const o = toolOutput(p);
+      // a call with no result yet can't be sent: Anthropic needs its tool_result next
+      if (o === undefined) continue;
+      content.push({type: 'tool_use', id: p.toolCallId, name, input: p.input ?? {}});
+      results.push({type: 'tool_result', tool_use_id: p.toolCallId, content: o, ...(p.state != 'output-available' && {is_error: true})});
+    }
+  }
+  flush();
+  return out;
+}
+
+export function anthropicMessages(options: AnthropicMessagesOptions = {}) {
+  const seen = new Set<string>();
+  const headers = async (req: any) => ({
+    'anthropic-version': '2023-06-01',
+    ...(options.dangerouslyAllowBrowser && {'anthropic-dangerous-direct-browser-access': 'true'}),
+    ...(typeof options.headers == 'function' ? await options.headers(req) : options.headers),
+  });
+  return {
+    async *stream(req: any, signal: AbortSignal): AsyncGenerator<any, void, any> {
+      const p = prepare(req, options.strict, seen, 'anthropicMessages', 'anthropic', LIMITS);
+      const system = [req.instructions, ...req.messages.filter((m: any) => m.role == 'system').map((m: any) => partsOf(m).filter(x => x.type == 'text').map(x => x.text).join(''))].filter(Boolean).join('\n\n');
+      const messages: any[] = [];
+      for (const m of req.messages.filter((m: any) => m.role != 'system').flatMap(toAnthropic)) {
+        const last = messages[messages.length - 1];
+        if (last?.role == m.role) last.content = [...last.content, ...m.content];
+        else messages.push(m);
+      }
+      const tools = [...p.tools.map(({name, description, parameters, strict}) => ({name, ...(description && {description}), input_schema: parameters, ...(strict && {strict})})), ...(options.serverTools || [])];
+      const res = await post((options.baseURL ?? '/v1').replace(/\/$/, '') + '/messages', {
+        model: req.model ?? options.model,
+        max_tokens: req.maxTokens ?? options.maxTokens ?? 16000,
+        stream: true,
+        ...(system && {system}),
+        messages,
+        ...(tools.length && {tools}),
+        ...(p.output && {output_config: {format: {type: 'json_schema', schema: p.output.strict ? p.output.schema : anthropicCompatible(p.output.schema)}}}),
+      }, req, signal, {...options, headers}, 'anthropicMessages');
+      // content blocks by index: tool_use / server_tool_use input JSON, thinking signatures
+      const blocks: any[] = [];
+      // usage: message_start's, updated by message_delta's (cumulative counts)
+      let reason: any, u: any, finished = false;
+      const usage = () => {
+        if (!u) return;
+        const i = (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0), o = u.output_tokens ?? 0;
+        return {inputTokens: i, outputTokens: o, totalTokens: i + o, ...(u.output_tokens_details?.thinking_tokens != null && {reasoningTokens: u.output_tokens_details.thinking_tokens})};
+      };
+      for await (const {data} of sse(res)) {
+        const e = json(data), t = e?.type;
+        if (typeof t != 'string') continue;
+        if (t == 'message_start') {
+          u = e.message?.usage;
+          if (e.message?.id) yield {type: 'start', id: e.message.id};
+        } else if (t == 'content_block_start') {
+          const b = e.content_block || {};
+          blocks[e.index] = {...b, json: ''};
+          if (b.type == 'text' && b.text) yield {type: 'text', delta: b.text};
+          else if (b.type == 'thinking' && b.thinking) yield {type: 'reasoning', delta: b.thinking};
+          else if (b.type == 'redacted_thinking') yield {type: 'reasoning', delta: '', providerMetadata: {anthropic: {redactedData: b.data}}};
+          else if (/_tool_result$/.test(b.type) && b.tool_use_id) yield {type: 'tool-result', id: b.tool_use_id, output: b};
+        } else if (t == 'content_block_delta') {
+          const d = e.delta || {}, b = blocks[e.index];
+          if (d.type == 'text_delta') yield {type: 'text', delta: d.text};
+          else if (d.type == 'thinking_delta') yield {type: 'reasoning', delta: d.thinking};
+          else if (b && d.type == 'signature_delta') b.signature = d.signature;
+          else if (b && d.type == 'input_json_delta') b.json += d.partial_json;
+        } else if (t == 'content_block_stop') {
+          const b = blocks[e.index];
+          if (b?.type == 'thinking' && b.signature) yield {type: 'reasoning', delta: '', providerMetadata: {anthropic: {signature: b.signature}}};
+          else if (b?.type == 'tool_use') yield {type: 'tool-call', id: b.id, name: b.name, input: p.input(b.name, b.json ? json(b.json) : b.input ?? {})};
+          else if (b?.type == 'server_tool_use') yield {type: 'tool-call', id: b.id, name: b.name, input: b.json ? json(b.json) : b.input ?? {}, executed: true, providerExecuted: true};
+        } else if (t == 'message_delta') {
+          if (e.delta?.stop_reason) reason = REASONS[e.delta.stop_reason] ?? 'other';
+          if (e.usage) u = {...u, ...e.usage};
+        } else if (t == 'message_stop') {
+          finished = true;
+          yield {type: 'finish', reason, usage: usage()};
+        } else if (t == 'error') {
+          throw Object.assign(new Error('anthropicMessages: ' + (e.error?.message ?? 'the request failed')), {code: e.error?.type});
+        }
+      }
+      if (!finished) yield {type: 'finish', reason, usage: usage()};
+    },
+  };
+}

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

@@ -0,0 +1,105 @@
+import {post, sse, json, usageOf, partsOf, toolName, toolOutput} from './shared';
+import type {HttpOptions} from './shared';
+import {prepare} from './tools';
+import type {StrictOption} from './tools';
+
+/*
+ * PLAN-6 L-2: chatCompletions({ baseURL?, model, headers?, fetch?, body?, strict?,
+ * dangerouslyAllowBrowser? }), a chat transport for OpenAI's Chat Completions SSE, the lowest
+ * common denominator of local servers (Ollama, llama.cpp, LM Studio, vLLM). POST
+ * `${baseURL}/chat/completions` (baseURL default '/v1') with `stream: true` and
+ * `stream_options.include_usage`.
+ *
+ * Request: `instructions` as the first system message; each message as Chat Completions
+ * messages (an assistant message's text and tool calls as one message per step, followed by a
+ * `tool` message per result); `tools` as function tools; `output` as `response_format`
+ * json_schema; `body` merged in.
+ *
+ * Events: `delta.content` -> text; `delta.reasoning_content` / `delta.reasoning` (vLLM,
+ * DeepSeek, Ollama) -> reasoning; `delta.tool_calls` accumulated by `index`, yielded in index
+ * order when the choice finishes (or the stream ends); the usage chunk (empty `choices`) and
+ * `finish_reason` -> finish; an `error` chunk -> a thrown Error; `[DONE]` ends the stream.
+ */
+
+export interface ChatCompletionsOptions extends HttpOptions {
+  baseURL?: string;
+  model?: string;
+  strict?: StrictOption;
+}
+
+const REASONS: Record<string, string> = {stop: 'stop', length: 'length', tool_calls: 'tool-calls', function_call: 'tool-calls', content_filter: 'content-filter'};
+
+/** a message as Chat Completions messages */
+export function toMessages(m: any): any[] {
+  const out: any[] = [];
+  let text = '', calls: any[] = [], results: any[] = [], content: any[] = [];
+  const flush = () => {
+    if (m.role == 'assistant') {
+      if (text || calls.length) out.push({role: 'assistant', content: text || null, ...(calls.length && {tool_calls: calls})});
+    } else if (text || content.length) {
+      out.push({role: m.role, content: content.length ? [...(text ? [{type: 'text', text}] : []), ...content] : text});
+    }
+    out.push(...results);
+    text = ''; calls = []; results = []; content = [];
+  };
+  for (const p of partsOf(m)) {
+    const name = toolName(p);
+    if (p.type == 'text') {
+      if (calls.length) flush();
+      text += p.text;
+    } else if (p.type == 'file' && m.role == 'user') {
+      content.push(p.mediaType?.startsWith('image/') ? {type: 'image_url', image_url: {url: p.url}} : {type: 'file', file: {file_data: p.url, ...(p.filename && {filename: p.filename})}});
+    } else if (name && p.input !== undefined && m.role == 'assistant') {
+      calls.push({id: p.toolCallId, type: 'function', function: {name, arguments: JSON.stringify(p.input ?? {})}});
+      const o = toolOutput(p);
+      if (o !== undefined) results.push({role: 'tool', tool_call_id: p.toolCallId, content: o});
+    }
+  }
+  flush();
+  return out;
+}
+
+export function chatCompletions(options: ChatCompletionsOptions = {}) {
+  const seen = new Set<string>();
+  return {
+    async *stream(req: any, signal: AbortSignal): AsyncGenerator<any, void, any> {
+      const p = prepare(req, options.strict, seen, 'chatCompletions');
+      const res = await post((options.baseURL ?? '/v1').replace(/\/$/, '') + '/chat/completions', {
+        model: req.model ?? options.model,
+        stream: true,
+        stream_options: {include_usage: true},
+        messages: [...(req.instructions ? [{role: 'system', content: req.instructions}] : []), ...req.messages.flatMap(toMessages)],
+        ...(p.tools.length && {tools: p.tools.map(({name, description, parameters, strict}) => ({type: 'function', function: {name, ...(description && {description}), parameters, ...(strict && {strict})}}))}),
+        ...(p.output && {response_format: {type: 'json_schema', json_schema: {name: 'output', schema: p.output.schema, ...(p.output.strict && {strict: true})}}}),
+      }, req, signal, options, 'chatCompletions');
+      // tool calls by index, as their deltas arrive
+      let calls: any[] = [], reason: any, usage: any, started = false;
+      const done = function* () {
+        for (const c of calls) if (c) yield {type: 'tool-call', id: c.id, name: c.name, input: p.input(c.name, json(c.args))};
+        calls = [];
+      };
+      for await (const {data} of sse(res)) {
+        if (data == '[DONE]') break;
+        const e = json(data);
+        if (!e || typeof e != 'object') continue;
+        if (e.error) throw Object.assign(new Error('chatCompletions: ' + (e.error.message ?? e.error)), {code: e.error.code});
+        if (!started && e.id) { started = true; yield {type: 'start', id: e.id}; }
+        if (e.usage) usage = usageOf(e.usage);
+        const ch = e.choices?.[0];
+        if (!ch) continue;
+        const d = ch.delta || {}, r = d.reasoning_content ?? d.reasoning;
+        if (typeof r == 'string' && r) yield {type: 'reasoning', delta: r};
+        if (typeof d.content == 'string' && d.content) yield {type: 'text', delta: d.content};
+        for (const t of d.tool_calls || []) {
+          const c = calls[t.index ?? 0] ||= {id: t.id, name: '', args: ''};
+          if (t.id) c.id = t.id;
+          if (t.function?.name) c.name = t.function.name;
+          if (t.function?.arguments) c.args += t.function.arguments;
+        }
+        if (ch.finish_reason) { reason = REASONS[ch.finish_reason] ?? 'other'; yield* done(); }
+      }
+      yield* done();
+      yield {type: 'finish', reason, usage};
+    },
+  };
+}