@mindees/ai 0.1.0

package/dist/json.js

@@ -0,0 +1,256 @@
+import { AiError } from "./errors.js";
+//#region src/json.ts
+/**
+* Pure, no-`eval` JSON helpers shared by structured output (`object.ts`) and the
+* tool-calling loop (`tools.ts`): extracting a JSON value from decorated model text,
+* sanitizing untrusted parsed data against prototype-pollution + DoS, validating through a
+* Standard Schema, and formatting validation issues. Model output is untrusted — every
+* function here is fail-closed. See `docs/adr/0019-synapse-structured-output.md`.
+*
+* @module
+*/
+/** Keys that must never appear in untrusted parsed objects (prototype-pollution vectors). */
+const FORBIDDEN_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+/**
+* Max characters of untrusted model text handed to `JSON.parse`. A size gate enforced BEFORE
+* parsing (mirrors the SSE backend's `MAX_SSE_BUFFER`) so a hostile payload can't be fully
+* allocated before the post-parse limits in {@link sanitizeJson} would reject it. ~8M chars.
+*/
+const DEFAULT_MAX_INPUT_CHARS = 8 * 1024 * 1024;
+/** Generous-but-bounded defaults (structured output can be larger than an SDUI tree). */
+const DEFAULT_SANITIZE_LIMITS = {
+	maxDepth: 64,
+	maxNodes: 1e5,
+	maxStringLength: 1e6,
+	maxProps: 1e3
+};
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function tryParse(text) {
+	try {
+		return {
+			ok: true,
+			value: JSON.parse(text)
+		};
+	} catch {
+		return {
+			ok: false,
+			reason: "not valid JSON"
+		};
+	}
+}
+/**
+* Find the content of the first fenced code block (```` ```json ```` or bare ```` ``` ````),
+* or `undefined` if there is no closed fence. Locates the fence with `indexOf` only — the
+* inner content is handed to `JSON.parse`, never to a regex or `eval`.
+*/
+function fencedBlock(text) {
+	const open = text.indexOf("```");
+	if (open === -1) return void 0;
+	const afterFence = open + 3;
+	const newline = text.indexOf("\n", afterFence);
+	if (newline === -1) return void 0;
+	const close = text.indexOf("```", newline + 1);
+	if (close === -1) return void 0;
+	return text.slice(newline + 1, close);
+}
+/**
+* Scan for the first balanced `{…}` or `[…]` span, tracking string + escape state so braces
+* inside string literals don't miscount. Returns the substring or `undefined`. Linear, no
+* regex, no `eval`.
+*/
+function firstBalancedSpan(text) {
+	let start = -1;
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i];
+		if (ch === "{" || ch === "[") {
+			start = i;
+			break;
+		}
+	}
+	if (start === -1) return void 0;
+	const stack = [];
+	let inStr = false;
+	let escaped = false;
+	for (let i = start; i < text.length; i++) {
+		const ch = text[i];
+		if (inStr) {
+			if (escaped) escaped = false;
+			else if (ch === "\\") escaped = true;
+			else if (ch === "\"") inStr = false;
+			continue;
+		}
+		if (ch === "\"") inStr = true;
+		else if (ch === "{") stack.push("}");
+		else if (ch === "[") stack.push("]");
+		else if (ch === "}" || ch === "]") {
+			stack.pop();
+			if (stack.length === 0) return text.slice(start, i + 1);
+		}
+	}
+}
+/**
+* Extract a JSON value from model text, trying in a fixed, testable order:
+* 1. parse the whole (trimmed) text; 2. parse the first fenced code block; 3. parse the
+* first balanced brace/bracket span. Never uses a capturing regex or `eval`.
+*/
+function extractJson(text, maxChars = DEFAULT_MAX_INPUT_CHARS) {
+	if (text.length > maxChars) return {
+		ok: false,
+		reason: `input exceeds ${maxChars} characters`
+	};
+	const direct = tryParse(text.trim());
+	if (direct.ok) return direct;
+	const fenced = fencedBlock(text);
+	if (fenced !== void 0) {
+		const parsed = tryParse(fenced.trim());
+		if (parsed.ok) return parsed;
+	}
+	const span = firstBalancedSpan(text);
+	if (span !== void 0) {
+		const parsed = tryParse(span);
+		if (parsed.ok) return parsed;
+	}
+	return {
+		ok: false,
+		reason: "no valid JSON value found in model output"
+	};
+}
+/**
+* Best-effort parse of *incomplete* JSON for streaming previews: closes any open string and
+* unbalanced brackets, drops a dangling `,`/`:`, and parses. Returns `undefined` whenever it
+* can't safely produce a value (never throws, never guesses a value token). The result is
+* **unvalidated and unsanitized** — callers must treat it as an untyped preview only.
+*/
+function lenientParseJson(text, maxChars = DEFAULT_MAX_INPUT_CHARS) {
+	if (text.length > maxChars) return void 0;
+	let start = -1;
+	for (let i = 0; i < text.length; i++) if (text[i] === "{" || text[i] === "[") {
+		start = i;
+		break;
+	}
+	if (start === -1) return void 0;
+	const stack = [];
+	let inStr = false;
+	let escaped = false;
+	for (let i = start; i < text.length; i++) {
+		const ch = text[i];
+		if (inStr) {
+			if (escaped) escaped = false;
+			else if (ch === "\\") escaped = true;
+			else if (ch === "\"") inStr = false;
+			continue;
+		}
+		if (ch === "\"") inStr = true;
+		else if (ch === "{") stack.push("}");
+		else if (ch === "[") stack.push("]");
+		else if (ch === "}" || ch === "]") stack.pop();
+	}
+	let candidate = text.slice(start);
+	if (inStr) candidate += "\"";
+	let end = candidate.length;
+	while (end > 0) {
+		const c = candidate[end - 1];
+		if (c === " " || c === "\n" || c === "\r" || c === "	") end--;
+		else break;
+	}
+	if (end > 0 && (candidate[end - 1] === "," || candidate[end - 1] === ":")) end--;
+	candidate = candidate.slice(0, end);
+	for (let i = stack.length - 1; i >= 0; i--) candidate += stack[i];
+	try {
+		return JSON.parse(candidate);
+	} catch {
+		return;
+	}
+}
+/**
+* Deep-clone untrusted parsed JSON into a fresh value, throwing `AiError('INVALID_OBJECT')`
+* on any prototype-pollution key (`__proto__`/`constructor`/`prototype`) at any depth or on
+* any limit breach. Run this BEFORE handing a value to a Standard Schema validator — a
+* validator can itself pollute the prototype by touching a poisoned object.
+*/
+function sanitizeJson(value, limits = DEFAULT_SANITIZE_LIMITS) {
+	let nodes = 0;
+	const walk = (v, depth) => {
+		if (depth > limits.maxDepth) throw new AiError("INVALID_OBJECT", `value exceeds max depth ${limits.maxDepth}`);
+		if (++nodes > limits.maxNodes) throw new AiError("INVALID_OBJECT", `value exceeds max nodes ${limits.maxNodes}`);
+		if (v === null) return null;
+		const t = typeof v;
+		if (t === "string") {
+			if (v.length > limits.maxStringLength) throw new AiError("INVALID_OBJECT", `string exceeds max length ${limits.maxStringLength}`);
+			return v;
+		}
+		if (t === "number") {
+			if (!Number.isFinite(v)) throw new AiError("INVALID_OBJECT", "numbers must be finite");
+			return v;
+		}
+		if (t === "boolean") return v;
+		if (Array.isArray(v)) return v.map((x) => walk(x, depth + 1));
+		if (isPlainObject(v)) {
+			const keys = Object.keys(v);
+			if (keys.length > limits.maxProps) throw new AiError("INVALID_OBJECT", `object exceeds max keys ${limits.maxProps}`);
+			const out = {};
+			for (const k of keys) {
+				if (FORBIDDEN_KEYS.has(k)) throw new AiError("INVALID_OBJECT", `forbidden key "${k}"`);
+				out[k] = walk(v[k], depth + 1);
+			}
+			return out;
+		}
+		throw new AiError("INVALID_OBJECT", `unsupported value of type ${t}`);
+	};
+	return walk(value, 0);
+}
+/**
+* Cheap recursive check for any prototype-pollution own key, WITHOUT cloning. Used to skip
+* emitting an unsanitized streaming preview that carries a poison key (so a consumer who
+* naively deep-merges the preview can't be tricked into polluting the prototype). Depth-capped
+* and fail-closed: a value nested past `maxDepth` is treated as forbidden (skip the preview)
+* rather than risking a stack overflow on a deeply-nested untrusted payload.
+*/
+function containsForbiddenKey(value, maxDepth = DEFAULT_SANITIZE_LIMITS.maxDepth, depth = 0) {
+	if (depth > maxDepth) return true;
+	if (Array.isArray(value)) return value.some((v) => containsForbiddenKey(v, maxDepth, depth + 1));
+	if (isPlainObject(value)) for (const k of Object.keys(value)) {
+		if (FORBIDDEN_KEYS.has(k)) return true;
+		if (containsForbiddenKey(value[k], maxDepth, depth + 1)) return true;
+	}
+	return false;
+}
+/** Render Standard Schema issues into one readable line: `path: message; path2: message2`. */
+function formatIssues(issues) {
+	return (Array.isArray(issues) ? issues : []).map((issue) => {
+		const path = Array.isArray(issue.path) ? issue.path.map((seg) => String(typeof seg === "object" && seg !== null ? seg.key : seg)).join(".") : void 0;
+		return path ? `${path}: ${issue.message}` : issue.message;
+	}).join("; ");
+}
+/**
+* Validate a (already-sanitized) value through a Standard Schema, awaiting an async validator.
+* Defensively narrows a malformed validator result (non-array `issues`) into a failure rather
+* than crashing. Discriminates on `issues` truthiness — a valid output may legitimately be
+* `undefined`, so `value` is not a reliable discriminant.
+*/
+async function validateStandard(schema, value) {
+	const raw = schema["~standard"].validate(value);
+	const result = raw instanceof Promise ? await raw : raw;
+	if (typeof result !== "object" || result === null) return {
+		ok: false,
+		issues: []
+	};
+	if (result.issues) return {
+		ok: false,
+		issues: Array.isArray(result.issues) ? result.issues : []
+	};
+	return {
+		ok: true,
+		value: result.value
+	};
+}
+//#endregion
+export { DEFAULT_MAX_INPUT_CHARS, DEFAULT_SANITIZE_LIMITS, containsForbiddenKey, extractJson, formatIssues, lenientParseJson, sanitizeJson, validateStandard };
+
+//# sourceMappingURL=json.js.map

package/dist/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","names":[],"sources":["../src/json.ts"],"sourcesContent":["/**\n * Pure, no-`eval` JSON helpers shared by structured output (`object.ts`) and the\n * tool-calling loop (`tools.ts`): extracting a JSON value from decorated model text,\n * sanitizing untrusted parsed data against prototype-pollution + DoS, validating through a\n * Standard Schema, and formatting validation issues. Model output is untrusted — every\n * function here is fail-closed. See `docs/adr/0019-synapse-structured-output.md`.\n *\n * @module\n */\n\nimport { AiError } from './errors'\nimport type { StandardSchemaV1 } from './standard-schema'\n\n/** Keys that must never appear in untrusted parsed objects (prototype-pollution vectors). */\nconst FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype'])\n\n/**\n * Max characters of untrusted model text handed to `JSON.parse`. A size gate enforced BEFORE\n * parsing (mirrors the SSE backend's `MAX_SSE_BUFFER`) so a hostile payload can't be fully\n * allocated before the post-parse limits in {@link sanitizeJson} would reject it. ~8M chars.\n */\nexport const DEFAULT_MAX_INPUT_CHARS = 8 * 1024 * 1024\n\n/** Limits that bound a sanitized value so hostile model JSON can't exhaust memory. */\nexport interface SanitizeLimits {\n  /** Max nesting depth. */\n  readonly maxDepth: number\n  /** Max total nodes (objects + arrays + primitives) across the whole value. */\n  readonly maxNodes: number\n  /** Max length of any single string. */\n  readonly maxStringLength: number\n  /** Max own keys on any single object. */\n  readonly maxProps: number\n}\n\n/** Generous-but-bounded defaults (structured output can be larger than an SDUI tree). */\nexport const DEFAULT_SANITIZE_LIMITS: SanitizeLimits = {\n  maxDepth: 64,\n  maxNodes: 100_000,\n  maxStringLength: 1_000_000,\n  maxProps: 1000,\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\n/** The outcome of {@link extractJson}. */\nexport type ExtractResult =\n  | { readonly ok: true; readonly value: unknown }\n  | {\n      readonly ok: false\n      readonly reason: string\n    }\n\nfunction tryParse(text: string): ExtractResult {\n  try {\n    return { ok: true, value: JSON.parse(text) }\n  } catch {\n    return { ok: false, reason: 'not valid JSON' }\n  }\n}\n\n/**\n * Find the content of the first fenced code block (```` ```json ```` or bare ```` ``` ````),\n * or `undefined` if there is no closed fence. Locates the fence with `indexOf` only — the\n * inner content is handed to `JSON.parse`, never to a regex or `eval`.\n */\nfunction fencedBlock(text: string): string | undefined {\n  const open = text.indexOf('```')\n  if (open === -1) return undefined\n  // Skip the opening fence and an optional language tag up to the end of that line.\n  const afterFence = open + 3\n  const newline = text.indexOf('\\n', afterFence)\n  if (newline === -1) return undefined\n  const close = text.indexOf('```', newline + 1)\n  if (close === -1) return undefined\n  return text.slice(newline + 1, close)\n}\n\n/**\n * Scan for the first balanced `{…}` or `[…]` span, tracking string + escape state so braces\n * inside string literals don't miscount. Returns the substring or `undefined`. Linear, no\n * regex, no `eval`.\n */\nfunction firstBalancedSpan(text: string): string | undefined {\n  let start = -1\n  for (let i = 0; i < text.length; i++) {\n    const ch = text[i]\n    if (ch === '{' || ch === '[') {\n      start = i\n      break\n    }\n  }\n  if (start === -1) return undefined\n  const stack: string[] = []\n  let inStr = false\n  let escaped = false\n  for (let i = start; i < text.length; i++) {\n    const ch = text[i]\n    if (inStr) {\n      if (escaped) escaped = false\n      else if (ch === '\\\\') escaped = true\n      else if (ch === '\"') inStr = false\n      continue\n    }\n    if (ch === '\"') inStr = true\n    else if (ch === '{') stack.push('}')\n    else if (ch === '[') stack.push(']')\n    else if (ch === '}' || ch === ']') {\n      stack.pop()\n      if (stack.length === 0) return text.slice(start, i + 1)\n    }\n  }\n  return undefined\n}\n\n/**\n * Extract a JSON value from model text, trying in a fixed, testable order:\n * 1. parse the whole (trimmed) text; 2. parse the first fenced code block; 3. parse the\n * first balanced brace/bracket span. Never uses a capturing regex or `eval`.\n */\nexport function extractJson(\n  text: string,\n  maxChars: number = DEFAULT_MAX_INPUT_CHARS,\n): ExtractResult {\n  // Size gate BEFORE any JSON.parse so a hostile payload isn't fully allocated first.\n  if (text.length > maxChars) {\n    return { ok: false, reason: `input exceeds ${maxChars} characters` }\n  }\n  const direct = tryParse(text.trim())\n  if (direct.ok) return direct\n\n  const fenced = fencedBlock(text)\n  if (fenced !== undefined) {\n    const parsed = tryParse(fenced.trim())\n    if (parsed.ok) return parsed\n  }\n\n  const span = firstBalancedSpan(text)\n  if (span !== undefined) {\n    const parsed = tryParse(span)\n    if (parsed.ok) return parsed\n  }\n\n  return { ok: false, reason: 'no valid JSON value found in model output' }\n}\n\n/**\n * Best-effort parse of *incomplete* JSON for streaming previews: closes any open string and\n * unbalanced brackets, drops a dangling `,`/`:`, and parses. Returns `undefined` whenever it\n * can't safely produce a value (never throws, never guesses a value token). The result is\n * **unvalidated and unsanitized** — callers must treat it as an untyped preview only.\n */\nexport function lenientParseJson(\n  text: string,\n  maxChars: number = DEFAULT_MAX_INPUT_CHARS,\n): unknown {\n  if (text.length > maxChars) return undefined\n  let start = -1\n  for (let i = 0; i < text.length; i++) {\n    if (text[i] === '{' || text[i] === '[') {\n      start = i\n      break\n    }\n  }\n  if (start === -1) return undefined\n\n  const stack: string[] = []\n  let inStr = false\n  let escaped = false\n  for (let i = start; i < text.length; i++) {\n    const ch = text[i]\n    if (inStr) {\n      if (escaped) escaped = false\n      else if (ch === '\\\\') escaped = true\n      else if (ch === '\"') inStr = false\n      continue\n    }\n    if (ch === '\"') inStr = true\n    else if (ch === '{') stack.push('}')\n    else if (ch === '[') stack.push(']')\n    else if (ch === '}' || ch === ']') stack.pop()\n  }\n\n  let candidate = text.slice(start)\n  if (inStr) candidate += '\"'\n  // Drop trailing whitespace then a single dangling structural char (e.g. `{\"a\":` or `[1,`).\n  let end = candidate.length\n  while (end > 0) {\n    const c = candidate[end - 1]\n    if (c === ' ' || c === '\\n' || c === '\\r' || c === '\\t') end--\n    else break\n  }\n  if (end > 0 && (candidate[end - 1] === ',' || candidate[end - 1] === ':')) end--\n  candidate = candidate.slice(0, end)\n  for (let i = stack.length - 1; i >= 0; i--) candidate += stack[i]\n\n  try {\n    return JSON.parse(candidate)\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * Deep-clone untrusted parsed JSON into a fresh value, throwing `AiError('INVALID_OBJECT')`\n * on any prototype-pollution key (`__proto__`/`constructor`/`prototype`) at any depth or on\n * any limit breach. Run this BEFORE handing a value to a Standard Schema validator — a\n * validator can itself pollute the prototype by touching a poisoned object.\n */\nexport function sanitizeJson(\n  value: unknown,\n  limits: SanitizeLimits = DEFAULT_SANITIZE_LIMITS,\n): unknown {\n  let nodes = 0\n  const walk = (v: unknown, depth: number): unknown => {\n    if (depth > limits.maxDepth) {\n      throw new AiError('INVALID_OBJECT', `value exceeds max depth ${limits.maxDepth}`)\n    }\n    if (++nodes > limits.maxNodes) {\n      throw new AiError('INVALID_OBJECT', `value exceeds max nodes ${limits.maxNodes}`)\n    }\n    if (v === null) return null\n    const t = typeof v\n    if (t === 'string') {\n      if ((v as string).length > limits.maxStringLength) {\n        throw new AiError('INVALID_OBJECT', `string exceeds max length ${limits.maxStringLength}`)\n      }\n      return v\n    }\n    if (t === 'number') {\n      if (!Number.isFinite(v)) throw new AiError('INVALID_OBJECT', 'numbers must be finite')\n      return v\n    }\n    if (t === 'boolean') return v\n    if (Array.isArray(v)) return v.map((x) => walk(x, depth + 1))\n    if (isPlainObject(v)) {\n      const keys = Object.keys(v)\n      if (keys.length > limits.maxProps) {\n        throw new AiError('INVALID_OBJECT', `object exceeds max keys ${limits.maxProps}`)\n      }\n      const out: Record<string, unknown> = {}\n      for (const k of keys) {\n        if (FORBIDDEN_KEYS.has(k)) throw new AiError('INVALID_OBJECT', `forbidden key \"${k}\"`)\n        out[k] = walk(v[k], depth + 1)\n      }\n      return out\n    }\n    throw new AiError('INVALID_OBJECT', `unsupported value of type ${t}`)\n  }\n  return walk(value, 0)\n}\n\n/**\n * Cheap recursive check for any prototype-pollution own key, WITHOUT cloning. Used to skip\n * emitting an unsanitized streaming preview that carries a poison key (so a consumer who\n * naively deep-merges the preview can't be tricked into polluting the prototype). Depth-capped\n * and fail-closed: a value nested past `maxDepth` is treated as forbidden (skip the preview)\n * rather than risking a stack overflow on a deeply-nested untrusted payload.\n */\nexport function containsForbiddenKey(\n  value: unknown,\n  maxDepth: number = DEFAULT_SANITIZE_LIMITS.maxDepth,\n  depth = 0,\n): boolean {\n  if (depth > maxDepth) return true // fail-closed: too deep to vet → don't emit\n  if (Array.isArray(value)) return value.some((v) => containsForbiddenKey(v, maxDepth, depth + 1))\n  if (isPlainObject(value)) {\n    for (const k of Object.keys(value)) {\n      if (FORBIDDEN_KEYS.has(k)) return true\n      if (containsForbiddenKey(value[k], maxDepth, depth + 1)) return true\n    }\n  }\n  return false\n}\n\n/** Render Standard Schema issues into one readable line: `path: message; path2: message2`. */\nexport function formatIssues(issues: ReadonlyArray<StandardSchemaV1.Issue>): string {\n  const list: ReadonlyArray<StandardSchemaV1.Issue> = Array.isArray(issues) ? issues : []\n  const lines = list.map((issue) => {\n    // String()-coerce each segment: a path key may be a symbol (PropertyKey), and\n    // `Array.join`'s implicit coercion throws on symbols — that must not escape the pipeline.\n    // Guard the array shape too — a malformed validator may hand back a non-array `path`.\n    const path = Array.isArray(issue.path)\n      ? issue.path\n          .map((seg) => String(typeof seg === 'object' && seg !== null ? seg.key : seg))\n          .join('.')\n      : undefined\n    return path ? `${path}: ${issue.message}` : issue.message\n  })\n  return lines.join('; ')\n}\n\n/** A normalized validation outcome (sync — the Promise has already been awaited). */\nexport type ValidationOutcome<T> =\n  | { readonly ok: true; readonly value: T }\n  | { readonly ok: false; readonly issues: ReadonlyArray<StandardSchemaV1.Issue> }\n\n/**\n * Validate a (already-sanitized) value through a Standard Schema, awaiting an async validator.\n * Defensively narrows a malformed validator result (non-array `issues`) into a failure rather\n * than crashing. Discriminates on `issues` truthiness — a valid output may legitimately be\n * `undefined`, so `value` is not a reliable discriminant.\n */\nexport async function validateStandard<S extends StandardSchemaV1>(\n  schema: S,\n  value: unknown,\n): Promise<ValidationOutcome<StandardSchemaV1.InferOutput<S>>> {\n  const raw = schema['~standard'].validate(value)\n  const result = raw instanceof Promise ? await raw : raw\n  // A buggy/hostile validator may return a non-object — treat that as a (repairable) failure\n  // rather than crashing on a property access.\n  if (typeof result !== 'object' || result === null) {\n    return { ok: false, issues: [] }\n  }\n  if (result.issues) {\n    return { ok: false, issues: Array.isArray(result.issues) ? result.issues : [] }\n  }\n  return { ok: true, value: result.value }\n}\n"],"mappings":"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"}

package/dist/mappers.d.ts

@@ -0,0 +1,52 @@
+import { AiChunk, AiResult, GenerateRequest } from "./contract.js";
+
+//#region src/mappers.d.ts
+/**
+ * Parse one SSE `data` JSON into zero or more {@link AiChunk}s. Returns an array (empty
+ * to skip a non-content event) because a single event can legitimately carry more than
+ * one logical chunk — e.g. an OpenAI-compatible server that puts a content delta AND the
+ * terminal `finish_reason`/`usage` in the same event (a 1-chunk-per-event parser would
+ * drop the finish/usage).
+ */
+type StreamParser = (data: unknown) => readonly AiChunk[];
+/**
+ * A provider wire mapper. A custom mapper whose `buildRequest` cannot express
+ * `request.tools` MUST throw rather than silently drop them (the built-in openai/anthropic
+ * mappers serialize them; the on-device backend throws).
+ */
+interface ProviderMapper {
+  /**
+   * How `apiKey` is sent. `'anthropic'` → `x-api-key` + `anthropic-version`; `'bearer'`
+   * (the default when omitted) → `Authorization: Bearer`. Declared on the mapper so auth
+   * follows the chosen provider whether it is selected by name or by object — and so a
+   * custom Anthropic-compatible mapper can opt into `x-api-key` auth.
+   */
+  readonly auth?: 'bearer' | 'anthropic';
+  /** Build the HTTP path + JSON body for a request. */
+  buildRequest(request: GenerateRequest, model: string, stream: boolean): {
+    path: string;
+    body: unknown;
+  };
+  /** Parse a non-streaming JSON response into an {@link AiResult}. */
+  parseResponse(json: unknown): AiResult;
+  /**
+   * Create a {@link StreamParser} for one stream. Returned fresh per stream so it may hold
+   * per-stream state (e.g. the last `finish_reason`) without leaking across concurrent
+   * streams that share this mapper singleton.
+   */
+  createStreamParser(): StreamParser;
+}
+/** OpenAI-compatible `/chat/completions` mapper (also fits many local/compatible servers). */
+declare const openaiMapper: ProviderMapper;
+/** Anthropic `/v1/messages` mapper. */
+declare const anthropicMapper: ProviderMapper;
+/** The built-in mappers by adapter name. */
+declare const MAPPERS: {
+  readonly openai: ProviderMapper;
+  readonly anthropic: ProviderMapper;
+};
+/** A built-in provider adapter name. */
+type AdapterName = keyof typeof MAPPERS;
+//#endregion
+export { AdapterName, ProviderMapper, StreamParser, anthropicMapper, openaiMapper };
+//# sourceMappingURL=mappers.d.ts.map

package/dist/mappers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mappers.d.ts","names":[],"sources":["../src/mappers.ts"],"mappings":";;;;;;;;;;KA6BY,YAAA,IAAgB,IAAA,uBAA2B,OAAO;;;;;;UAO7C,cAAA;EAaI;;;;;;EAAA,SANV,IAAA;EAcyB;EAZlC,YAAA,CACE,OAAA,EAAS,eAAA,EACT,KAAA,UACA,MAAA;IACG,IAAA;IAAc,IAAA;EAAA;EAgOpB;EA9NC,aAAA,CAAc,IAAA,YAAgB,QAAA;EAuT/B;;;AAAA;AAGD;EApTE,kBAAA,IAAsB,YAAA;AAAA;;cA0IX,YAAA,EAAc,cA8E1B;;cAGY,eAAA,EAAiB,cAsF7B;;cAGY,OAAA;EAAA,iBAAuE,cAAA;EAAA,oBAAA,cAAA;AAAA;;KAGxE,WAAA,gBAA2B,OAAO"}

package/dist/mappers.js

@@ -0,0 +1,312 @@
+import { messageText } from "./contract.js";
+//#region src/mappers.ts
+/**
+* Per-provider wire mappers (OpenAI-compatible + Anthropic), isolating the HTTP shape so
+* the server backend never imports a vendor SDK and a provider change is a contained
+* edit. All response/stream parsing is defensive — model/server JSON is untrusted. Tool
+* mapping is added in 11C (with tools). See `docs/adr/0018-synapse-server-backend.md`.
+*
+* @module
+*/
+function asRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+function asString(value) {
+	return typeof value === "string" ? value : void 0;
+}
+function asNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+/** Build a {@link Usage} omitting undefined fields (exactOptionalPropertyTypes-safe). */
+function usageOf(inputTokens, outputTokens) {
+	const usage = {};
+	if (inputTokens !== void 0) usage.inputTokens = inputTokens;
+	if (outputTokens !== void 0) usage.outputTokens = outputTokens;
+	return usage;
+}
+/** Parse OpenAI's `function.arguments` (a JSON STRING) defensively into a value. */
+function parseJsonArgs(value) {
+	if (typeof value !== "string") return value ?? {};
+	try {
+		return JSON.parse(value);
+	} catch {
+		return {};
+	}
+}
+/** Serialize a tool result to the string the wire APIs expect (never throws, cycle-safe-ish). */
+function toWireString(value) {
+	if (typeof value === "string") return value;
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+/** Split a message's parts (string content has only text). */
+function partsOf(content) {
+	if (typeof content === "string") return {
+		text: content,
+		calls: [],
+		results: []
+	};
+	return {
+		text: content.filter((p) => p.type === "text").map((p) => p.text).join(""),
+		calls: content.filter((p) => p.type === "tool-call"),
+		results: content.filter((p) => p.type === "tool-result")
+	};
+}
+/**
+* Serialize messages to the OpenAI chat shape, round-tripping tool turns: an assistant turn
+* with tool calls emits `tool_calls`; a `tool` message emits one `{ role:'tool', tool_call_id }`
+* per result. Without this the tool loop's 2nd turn would lose its tool context.
+*/
+function openaiMessages(messages) {
+	const out = [];
+	for (const m of messages) {
+		const { text, calls, results } = partsOf(m.content);
+		if (results.length > 0) for (const r of results) out.push({
+			role: "tool",
+			tool_call_id: r.id,
+			content: toWireString(r.result)
+		});
+		else if (calls.length > 0) out.push({
+			role: m.role,
+			content: text || null,
+			tool_calls: calls.map((c) => ({
+				id: c.id,
+				type: "function",
+				function: {
+					name: c.name,
+					arguments: JSON.stringify(c.args ?? {})
+				}
+			}))
+		});
+		else out.push({
+			role: m.role,
+			content: text
+		});
+	}
+	return out;
+}
+/**
+* Serialize non-system messages to the Anthropic shape, round-tripping tool turns: assistant
+* tool calls become `tool_use` blocks; a `tool` message becomes a USER message of `tool_result`
+* blocks (Anthropic carries tool results in the user turn).
+*/
+function anthropicMessages(messages) {
+	const out = [];
+	for (const m of messages) {
+		if (m.role === "system") continue;
+		const { text, calls, results } = partsOf(m.content);
+		if (results.length > 0) out.push({
+			role: "user",
+			content: results.map((r) => ({
+				type: "tool_result",
+				tool_use_id: r.id,
+				content: toWireString(r.result)
+			}))
+		});
+		else if (calls.length > 0) {
+			const content = [];
+			if (text) content.push({
+				type: "text",
+				text
+			});
+			for (const c of calls) content.push({
+				type: "tool_use",
+				id: c.id,
+				name: c.name,
+				input: c.args ?? {}
+			});
+			out.push({
+				role: "assistant",
+				content
+			});
+		} else out.push({
+			role: m.role,
+			content: text
+		});
+	}
+	return out;
+}
+/** Add `toolCalls` to an {@link AiResult} only when present (exactOptionalPropertyTypes-safe). */
+function withToolCalls(result, toolCalls) {
+	return toolCalls.length > 0 ? {
+		...result,
+		toolCalls
+	} : result;
+}
+const OPENAI_FINISH = Object.assign(Object.create(null), {
+	stop: "stop",
+	length: "length",
+	tool_calls: "tool-calls"
+});
+const ANTHROPIC_FINISH = Object.assign(Object.create(null), {
+	end_turn: "stop",
+	max_tokens: "length",
+	tool_use: "tool-calls"
+});
+/** OpenAI-compatible `/chat/completions` mapper (also fits many local/compatible servers). */
+const openaiMapper = {
+	auth: "bearer",
+	buildRequest(request, model, stream) {
+		const body = {
+			model,
+			stream,
+			messages: openaiMessages(request.messages)
+		};
+		if (request.temperature !== void 0) body.temperature = request.temperature;
+		if (request.maxOutputTokens !== void 0) body.max_tokens = request.maxOutputTokens;
+		if (request.tools && request.tools.length > 0) body.tools = request.tools.map((t) => ({
+			type: "function",
+			function: {
+				name: t.name,
+				...t.description !== void 0 ? { description: t.description } : {},
+				parameters: t.parameters ?? {
+					type: "object",
+					properties: {}
+				}
+			}
+		}));
+		if (stream) body.stream_options = { include_usage: true };
+		return {
+			path: "/chat/completions",
+			body
+		};
+	},
+	parseResponse(json) {
+		const root = asRecord(json);
+		const choice = asRecord((root?.choices)?.[0]);
+		const message = asRecord(choice?.message);
+		const usage = asRecord(root?.usage);
+		const toolCalls = [];
+		for (const raw of message?.tool_calls ?? []) {
+			const tc = asRecord(raw);
+			const fn = asRecord(tc?.function);
+			const name = asString(fn?.name);
+			if (!name) continue;
+			toolCalls.push({
+				type: "tool-call",
+				id: asString(tc?.id) ?? name,
+				name,
+				args: parseJsonArgs(fn?.arguments)
+			});
+		}
+		return withToolCalls({
+			text: asString(message?.content) ?? "",
+			finishReason: OPENAI_FINISH[asString(choice?.finish_reason) ?? ""] ?? "stop",
+			usage: usageOf(asNumber(usage?.prompt_tokens), asNumber(usage?.completion_tokens))
+		}, toolCalls);
+	},
+	createStreamParser() {
+		let lastReason = "stop";
+		return (data) => {
+			const root = asRecord(data);
+			const choice = asRecord((root?.choices)?.[0]);
+			const out = [];
+			const delta = asString(asRecord(choice?.delta)?.content);
+			if (delta) out.push({
+				type: "text-delta",
+				delta
+			});
+			const finish = asString(choice?.finish_reason);
+			if (finish) lastReason = OPENAI_FINISH[finish] ?? "stop";
+			const usage = asRecord(root?.usage);
+			if (finish || usage) out.push({
+				type: "finish",
+				finishReason: lastReason,
+				usage: usageOf(asNumber(usage?.prompt_tokens), asNumber(usage?.completion_tokens))
+			});
+			return out;
+		};
+	}
+};
+/** Anthropic `/v1/messages` mapper. */
+const anthropicMapper = {
+	auth: "anthropic",
+	buildRequest(request, model, stream) {
+		const system = request.messages.filter((m) => m.role === "system").map((m) => messageText(m)).join("\n");
+		const body = {
+			model,
+			stream,
+			messages: anthropicMessages(request.messages),
+			max_tokens: request.maxOutputTokens ?? 1024
+		};
+		if (system) body.system = system;
+		if (request.temperature !== void 0) body.temperature = request.temperature;
+		if (request.tools && request.tools.length > 0) body.tools = request.tools.map((t) => ({
+			name: t.name,
+			...t.description !== void 0 ? { description: t.description } : {},
+			input_schema: t.parameters ?? {
+				type: "object",
+				properties: {}
+			}
+		}));
+		return {
+			path: "/v1/messages",
+			body
+		};
+	},
+	parseResponse(json) {
+		const root = asRecord(json);
+		const content = root?.content ?? [];
+		let text = "";
+		const toolCalls = [];
+		for (const part of content) {
+			const block = asRecord(part);
+			if (asString(block?.type) === "tool_use") {
+				const name = asString(block?.name);
+				if (!name) continue;
+				toolCalls.push({
+					type: "tool-call",
+					id: asString(block?.id) ?? name,
+					name,
+					args: block?.input ?? {}
+				});
+			} else text += asString(block?.text) ?? "";
+		}
+		const usage = asRecord(root?.usage);
+		return withToolCalls({
+			text,
+			finishReason: ANTHROPIC_FINISH[asString(root?.stop_reason) ?? ""] ?? "stop",
+			usage: usageOf(asNumber(usage?.input_tokens), asNumber(usage?.output_tokens))
+		}, toolCalls);
+	},
+	createStreamParser() {
+		let inputTokens;
+		return (data) => {
+			const root = asRecord(data);
+			const type = asString(root?.type);
+			if (type === "message_start") {
+				inputTokens = asNumber(asRecord(asRecord(root?.message)?.usage)?.input_tokens);
+				return [];
+			}
+			if (type === "content_block_delta") {
+				const delta = asString(asRecord(root?.delta)?.text);
+				return delta ? [{
+					type: "text-delta",
+					delta
+				}] : [];
+			}
+			if (type === "message_delta") {
+				const stop = asString(asRecord(root?.delta)?.stop_reason);
+				const usage = asRecord(root?.usage);
+				return [{
+					type: "finish",
+					finishReason: ANTHROPIC_FINISH[stop ?? ""] ?? "stop",
+					usage: usageOf(inputTokens, asNumber(usage?.output_tokens))
+				}];
+			}
+			return [];
+		};
+	}
+};
+/** The built-in mappers by adapter name. */
+const MAPPERS = {
+	openai: openaiMapper,
+	anthropic: anthropicMapper
+};
+//#endregion
+export { MAPPERS, anthropicMapper, openaiMapper };
+
+//# sourceMappingURL=mappers.js.map