@fgv/ts-extras 5.1.0-5 → 5.1.0-50

package/dist/packlets/ai-assist/jsonResponse.js

@@ -0,0 +1,423 @@
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+/**
+ * JSON-tolerant extraction and converters for LLM responses.
+ *
+ * Models commonly wrap JSON output in Markdown code fences, add a
+ * "Sure, here's the JSON:" preamble, or trail off with prose after the
+ * closing brace. These helpers normalize that quirk on the read side so every
+ * AiAssist consumer can reach a validated `T` from raw model text without
+ * reimplementing the same fence-stripping logic.
+ *
+ * Scope: strip wrappers (fences, prose, BOM, whitespace). Out of scope: repair
+ * malformed JSON (missing commas, unquoted keys, smart quotes, etc.).
+ *
+ * @packageDocumentation
+ */
+import { Conversion, fail, succeed } from '@fgv/ts-utils';
+import { Converters as JsonBaseConverters } from '@fgv/ts-json-base';
+// Group 1 is the opening fence (marker, optional language tag, newline) and
+// group 2 is the fenced body. Group 1 is captured only so a caller that needs
+// to map a position inside the body back onto an offset in the original text
+// can add its length instead of re-deriving the fence header.
+const FENCED_BLOCK = /(```[A-Za-z0-9_-]*\s*\r?\n)([\s\S]*?)\r?\n?```/;
+const BOM = /^\uFEFF/;
+// Full RFC 8259 grammar so the extractor only succeeds when the entire
+// candidate parses as a JSON primitive (instead of just starting like one).
+const JSON_NUMBER = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
+// eslint-disable-next-line no-control-regex
+const JSON_STRING = /^"(?:[^"\\\u0000-\u001F]|\\(?:["\\/bfnrt]|u[0-9a-fA-F]{4}))*"$/;
+const JSON_KEYWORD = /^(?:true|false|null)$/;
+function stripBom(text) {
+    return text.replace(BOM, '');
+}
+function findBalancedJsonSubstring(text) {
+    // Walk the text once tracking string state. The first '{' or '[' that is
+    // *outside* a quoted string is the candidate start; from there, count
+    // matching close characters while ignoring delimiters that appear inside
+    // strings.
+    let inString = false;
+    let escape = false;
+    let start = -1;
+    let open = '';
+    let close = '';
+    let depth = 0;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text.charAt(i);
+        if (inString) {
+            if (escape) {
+                escape = false;
+            }
+            else if (ch === '\\') {
+                escape = true;
+            }
+            else if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (start < 0) {
+            if (ch === '{' || ch === '[') {
+                start = i;
+                open = ch;
+                close = ch === '{' ? '}' : ']';
+                depth = 1;
+            }
+            continue;
+        }
+        if (ch === open) {
+            depth++;
+        }
+        else if (ch === close) {
+            depth--;
+            if (depth === 0) {
+                return { kind: 'found', value: text.slice(start, i + 1), start };
+            }
+        }
+    }
+    return start >= 0 ? { kind: 'unclosed', depth, start } : { kind: 'none' };
+}
+/**
+ * Strips the wrappers a model adds around JSON — byte-order mark, surrounding
+ * whitespace, Markdown code fence — and reports where what is left starts in
+ * the original text.
+ *
+ * Single source of truth for that step: {@link extractJsonText} and
+ * {@link classifyJsonParseFailure} must agree on what the candidate is, or a
+ * classified `offset` would point into text the extractor never parsed.
+ * @internal
+ */
+function locateJsonCandidate(text) {
+    const noBom = stripBom(text);
+    const stripped = noBom.trim();
+    const strippedBase = text.length - noBom.length + (noBom.length - noBom.trimStart().length);
+    const fenced = FENCED_BLOCK.exec(stripped);
+    if (fenced === null) {
+        return { stripped, text: stripped, base: strippedBase };
+    }
+    const body = fenced[2];
+    return {
+        stripped,
+        text: body.trim(),
+        base: strippedBase + fenced.index + fenced[1].length + (body.length - body.trimStart().length)
+    };
+}
+/**
+ * Default {@link AiAssist.JsonTextExtractor | extractor} for LLM responses. Tolerates:
+ *
+ * - Leading/trailing whitespace and a leading byte-order mark.
+ * - Markdown code fences (with or without a language tag).
+ * - Conversational preamble before the first `{` or `[`.
+ * - Trailing prose after the matched closing `}` or `]`.
+ *
+ * Out of scope: repairing malformed JSON, handling smart quotes, etc.
+ *
+ * When an object or array opens but never closes before the end of input —
+ * the shape a response truncated by a token cap leaves behind — the failure
+ * names that specifically (distinct from the generic "no JSON-shaped
+ * substring found" for input that never looked like JSON at all) and points
+ * at `IAiCompletionResponse.truncated` and the `maxTokens` request option as
+ * the likely cause and fix.
+ *
+ * @param text - Raw model output.
+ * @returns A `Result<string>` containing the JSON-shaped substring, or a
+ * `Failure` if no JSON-shaped substring was found.
+ * @public
+ */
+export const extractJsonText = (text) => {
+    if (typeof text !== 'string') {
+        return fail('extractJsonText: input must be a string.');
+    }
+    const located = locateJsonCandidate(text);
+    if (located.stripped.length === 0) {
+        return fail('extractJsonText: input is empty.');
+    }
+    const candidate = located.text;
+    if (candidate.length === 0) {
+        return fail('extractJsonText: no JSON content found.');
+    }
+    // Whole-candidate primitive check runs before the brace scan so that a
+    // valid JSON string containing braces (e.g. `"text with { }"`) is returned
+    // intact instead of being mangled into the first balanced `{ }` match.
+    if (JSON_KEYWORD.test(candidate) || JSON_NUMBER.test(candidate) || JSON_STRING.test(candidate)) {
+        return succeed(candidate);
+    }
+    const scan = findBalancedJsonSubstring(candidate);
+    if (scan.kind === 'found') {
+        return succeed(scan.value);
+    }
+    if (scan.kind === 'unclosed') {
+        return fail(`extractJsonText: JSON structure opened but never closed (depth ${scan.depth} at end of input) — ` +
+            'response may have been truncated (check IAiCompletionResponse.truncated / raise maxTokens).');
+    }
+    return fail('extractJsonText: no JSON-shaped substring found.');
+};
+const UNKNOWN_PARSE_FAILURE = { kind: 'unknown' };
+const JSON_WHITESPACE = /[ \t\n\r]/;
+const IDENTIFIER_START = /[A-Za-z0-9_$]/;
+const IDENTIFIER_PART = /[A-Za-z0-9_$.-]/;
+// Characters that end an unquoted value run (`true`, `null`, a number, or
+// garbage). Includes ':' so a stray colon at a value position produces an
+// empty run — reported as 'unknown' — instead of being swallowed by a literal.
+const VALUE_RUN_TERMINATOR = /[\s,}\]:"'{[]/;
+function scanQuotedRun(text, start, quote) {
+    let escape = false;
+    for (let i = start + 1; i < text.length; i++) {
+        const ch = text.charAt(i);
+        if (escape) {
+            escape = false;
+        }
+        else if (ch === '\\') {
+            escape = true;
+        }
+        else if (ch === quote) {
+            return { terminated: true, end: i + 1, body: text.slice(start + 1, i) };
+        }
+    }
+    return { terminated: false, end: text.length, body: text.slice(start + 1) };
+}
+function skipJsonWhitespace(text, from) {
+    let i = from;
+    while (i < text.length && JSON_WHITESPACE.test(text.charAt(i))) {
+        i++;
+    }
+    return i;
+}
+function scanRun(text, from, isPart) {
+    let i = from;
+    while (i < text.length && isPart(text.charAt(i))) {
+        i++;
+    }
+    return text.slice(from, i);
+}
+function classifyAtPropertyName(text, i, base) {
+    const ch = text.charAt(i);
+    if (ch === '"') {
+        const scan = scanQuotedRun(text, i, '"');
+        if (scan.terminated) {
+            return { next: scan.end };
+        }
+        // An unterminated name is only distinguishable from a mid-name truncation
+        // when the swallowed body contains structural text — a ':' the author
+        // plainly meant as the name/value separator. Without that, stay honest.
+        return scan.body.includes(':')
+            ? { reason: { kind: 'unterminated-property-name', token: text.slice(i), offset: base + i } }
+            : { reason: UNKNOWN_PARSE_FAILURE };
+    }
+    if (ch === "'") {
+        const scan = scanQuotedRun(text, i, "'");
+        return {
+            reason: {
+                kind: 'single-quoted-property-name',
+                token: scan.terminated ? text.slice(i, scan.end) : "'",
+                offset: base + i
+            }
+        };
+    }
+    if (ch === ',') {
+        return { reason: { kind: 'elided-member', token: ',', offset: base + i } };
+    }
+    if (IDENTIFIER_START.test(ch)) {
+        return {
+            reason: {
+                kind: 'unquoted-property-name',
+                token: scanRun(text, i, (c) => IDENTIFIER_PART.test(c)),
+                offset: base + i
+            }
+        };
+    }
+    return { reason: UNKNOWN_PARSE_FAILURE };
+}
+/**
+ * Walks `text` from `from` (the opening `{` or `[`) as a permissive JSON
+ * scanner, reporting the first fault it can name with confidence. Anything it
+ * cannot name — including a document that scans clean — yields `'unknown'`.
+ *
+ * The scan is structural: it never reads the engine's `JSON.parse` message, so
+ * its verdicts do not drift with the Node version.
+ * @internal
+ */
+function scanForParseFailure(text, from, base) {
+    const stack = [];
+    let expect = 'value';
+    let i = from;
+    for (;;) {
+        i = skipJsonWhitespace(text, i);
+        if (i >= text.length) {
+            return UNKNOWN_PARSE_FAILURE;
+        }
+        const ch = text.charAt(i);
+        const top = stack[stack.length - 1];
+        if (expect === 'name') {
+            if (ch === '}') {
+                stack.pop();
+                i++;
+                expect = 'comma';
+                continue;
+            }
+            const outcome = classifyAtPropertyName(text, i, base);
+            if ('reason' in outcome) {
+                return outcome.reason;
+            }
+            i = outcome.next;
+            expect = 'colon';
+            continue;
+        }
+        if (expect === 'colon') {
+            if (ch !== ':') {
+                return UNKNOWN_PARSE_FAILURE;
+            }
+            i++;
+            expect = 'value';
+            continue;
+        }
+        if (expect === 'value') {
+            if (ch === '{' || ch === '[') {
+                stack.push(ch === '{' ? 'object' : 'array');
+                i++;
+                expect = ch === '{' ? 'name' : 'value';
+                continue;
+            }
+            if (ch === ']' && top === 'array') {
+                stack.pop();
+                i++;
+                expect = 'comma';
+                continue;
+            }
+            if (ch === ',') {
+                return top === 'array'
+                    ? { kind: 'elided-member', token: ',', offset: base + i }
+                    : UNKNOWN_PARSE_FAILURE;
+            }
+            if (ch === '"') {
+                const scan = scanQuotedRun(text, i, '"');
+                if (!scan.terminated) {
+                    // Could equally be a truncated value; the extractor already names
+                    // truncation, so do not compete with it here.
+                    return UNKNOWN_PARSE_FAILURE;
+                }
+                i = scan.end;
+                expect = 'comma';
+                continue;
+            }
+            const literal = scanRun(text, i, (c) => !VALUE_RUN_TERMINATOR.test(c));
+            if (literal.length === 0) {
+                return UNKNOWN_PARSE_FAILURE;
+            }
+            i += literal.length;
+            expect = 'comma';
+            continue;
+        }
+        // expect === 'comma': a complete value just closed.
+        if (top === undefined) {
+            return UNKNOWN_PARSE_FAILURE;
+        }
+        if (ch === ',') {
+            i++;
+            expect = top === 'object' ? 'name' : 'value';
+            continue;
+        }
+        if ((ch === '}' && top === 'object') || (ch === ']' && top === 'array')) {
+            stack.pop();
+            i++;
+            continue;
+        }
+        return UNKNOWN_PARSE_FAILURE;
+    }
+}
+/**
+ * Classifies why a JSON-shaped LLM response would not parse, returning a
+ * {@link AiAssist.JsonParseFailureReason} a caller can branch on — repair the
+ * cheap cases, re-prompt the expensive ones, fail outright on the rest —
+ * instead of regex-matching an engine-specific `JSON.parse` message.
+ *
+ * Pass the same raw model text you handed
+ * {@link AiAssist.fencedStringifiedJson} or {@link AiAssist.extractJsonText};
+ * this applies the same BOM / whitespace / fence / preamble handling before
+ * scanning, and reports `offset` against that original text.
+ *
+ * Classification is **structural and deliberately conservative**. The scan
+ * walks the JSON grammar itself rather than reading the engine's error string,
+ * so its verdicts are stable across Node versions — and any fault it cannot
+ * name with confidence comes back as `'unknown'` rather than a guess. In
+ * particular an input that opened a structure and never closed it (the
+ * truncated-response shape {@link AiAssist.extractJsonText} already diagnoses)
+ * classifies as `'unknown'` here; the two diagnostics are complementary, not
+ * competing.
+ *
+ * This never fails and never repairs — it only names the fault. It is a
+ * diagnostic on the failure path, so calling it on text that parses fine is
+ * harmless but pointless: it returns `'unknown'`.
+ *
+ * @example
+ * ```ts
+ * const parsed = fencedStringifiedJson({ inner }).convert(raw);
+ * if (parsed.isFailure()) {
+ *   const reason = classifyJsonParseFailure(raw);
+ *   switch (reason.kind) {
+ *     case 'unquoted-property-name': // cheap to repair
+ *     case 'single-quoted-property-name':
+ *       break;
+ *     case 'elided-member':
+ *     case 'unterminated-property-name': // worth a re-prompt
+ *       break;
+ *     default: // 'unknown' — fail outright
+ *   }
+ * }
+ * ```
+ *
+ * @param text - Raw model output (the same string handed to the extractor).
+ * @returns A {@link AiAssist.JsonParseFailureReason}.
+ * @public
+ */
+export function classifyJsonParseFailure(text) {
+    // Defensive, and load-bearing for the documented totality: the signature says
+    // `string`, but a JS consumer — or a TS caller coming through an `unknown` /
+    // `any` escape hatch — can still hand us a non-string, and `locateJsonCandidate`
+    // would throw on it. `extractJsonText` already guards the same way; this keeps
+    // the pair consistent and keeps "never fails" true in practice rather than only
+    // under a well-typed caller.
+    if (typeof text !== 'string') {
+        return UNKNOWN_PARSE_FAILURE;
+    }
+    const candidate = locateJsonCandidate(text);
+    const scan = findBalancedJsonSubstring(candidate.text);
+    if (scan.kind === 'none') {
+        return UNKNOWN_PARSE_FAILURE;
+    }
+    return scanForParseFailure(candidate.text, scan.start, candidate.base);
+}
+export function fencedStringifiedJson(options) {
+    var _a;
+    const extractor = (_a = options === null || options === void 0 ? void 0 : options.extractor) !== null && _a !== void 0 ? _a : extractJsonText;
+    const inner = options === null || options === void 0 ? void 0 : options.inner;
+    const parser = inner !== undefined ? JsonBaseConverters.stringifiedJson(inner) : JsonBaseConverters.stringifiedJson();
+    return new Conversion.BaseConverter((from) => {
+        if (typeof from !== 'string') {
+            return fail('fencedStringifiedJson: input must be a string.');
+        }
+        return extractor(from).onSuccess((extracted) => parser.convert(extracted));
+    });
+}
+//# sourceMappingURL=jsonResponse.js.map

package/dist/packlets/ai-assist/jsonResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonResponse.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/jsonResponse.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\n/**\n * JSON-tolerant extraction and converters for LLM responses.\n *\n * Models commonly wrap JSON output in Markdown code fences, add a\n * \"Sure, here's the JSON:\" preamble, or trail off with prose after the\n * closing brace. These helpers normalize that quirk on the read side so every\n * AiAssist consumer can reach a validated `T` from raw model text without\n * reimplementing the same fence-stripping logic.\n *\n * Scope: strip wrappers (fences, prose, BOM, whitespace). Out of scope: repair\n * malformed JSON (missing commas, unquoted keys, smart quotes, etc.).\n *\n * @packageDocumentation\n */\n\nimport { Conversion, type Converter, fail, Result, succeed, type Validator } from '@fgv/ts-utils';\nimport { Converters as JsonBaseConverters, type JsonValue } from '@fgv/ts-json-base';\n\n/**\n * A function that pulls a JSON-shaped substring out of arbitrary model text.\n * Implementations strip whatever wrappers the model added (fences, preamble,\n * trailing prose) and return the JSON-shaped substring ready for `JSON.parse`.\n * @public\n */\nexport type JsonTextExtractor = (text: string) => Result<string>;\n\n// Group 1 is the opening fence (marker, optional language tag, newline) and\n// group 2 is the fenced body. Group 1 is captured only so a caller that needs\n// to map a position inside the body back onto an offset in the original text\n// can add its length instead of re-deriving the fence header.\nconst FENCED_BLOCK: RegExp = /(```[A-Za-z0-9_-]*\\s*\\r?\\n)([\\s\\S]*?)\\r?\\n?```/;\nconst BOM: RegExp = /^\\uFEFF/;\n// Full RFC 8259 grammar so the extractor only succeeds when the entire\n// candidate parses as a JSON primitive (instead of just starting like one).\nconst JSON_NUMBER: RegExp = /^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$/;\n// eslint-disable-next-line no-control-regex\nconst JSON_STRING: RegExp = /^\"(?:[^\"\\\\\\u0000-\\u001F]|\\\\(?:[\"\\\\/bfnrt]|u[0-9a-fA-F]{4}))*\"$/;\nconst JSON_KEYWORD: RegExp = /^(?:true|false|null)$/;\n\nfunction stripBom(text: string): string {\n  return text.replace(BOM, '');\n}\n\n/**\n * Outcome of a {@link findBalancedJsonSubstring} scan.\n *\n * - `'found'`: a balanced JSON-shaped substring was located; `value` is it.\n * - `'unclosed'`: an object or array opened but the matching close never\n *   arrived before the end of input — the classic truncated-response shape;\n *   `depth` is the unresolved depth at end of input, counting only the\n *   opening delimiter's type (the scan tracks the candidate's own `{`/`}`\n *   or `[`/`]` pair, not total mixed-delimiter nesting).\n * - `'none'`: no `{` or `[` was ever seen outside a quoted string.\n *\n * `start` (present on `'found'` and `'unclosed'`) is the index of the opening\n * `{` or `[` within the scanned text.\n * @internal\n */\ntype BalancedJsonScanResult =\n  | { readonly kind: 'found'; readonly value: string; readonly start: number }\n  | { readonly kind: 'unclosed'; readonly depth: number; readonly start: number }\n  | { readonly kind: 'none' };\n\nfunction findBalancedJsonSubstring(text: string): BalancedJsonScanResult {\n  // Walk the text once tracking string state. The first '{' or '[' that is\n  // *outside* a quoted string is the candidate start; from there, count\n  // matching close characters while ignoring delimiters that appear inside\n  // strings.\n  let inString = false;\n  let escape = false;\n  let start = -1;\n  let open = '';\n  let close = '';\n  let depth = 0;\n  for (let i = 0; i < text.length; i++) {\n    const ch = text.charAt(i);\n    if (inString) {\n      if (escape) {\n        escape = false;\n      } else if (ch === '\\\\') {\n        escape = true;\n      } else if (ch === '\"') {\n        inString = false;\n      }\n      continue;\n    }\n    if (ch === '\"') {\n      inString = true;\n      continue;\n    }\n    if (start < 0) {\n      if (ch === '{' || ch === '[') {\n        start = i;\n        open = ch;\n        close = ch === '{' ? '}' : ']';\n        depth = 1;\n      }\n      continue;\n    }\n    if (ch === open) {\n      depth++;\n    } else if (ch === close) {\n      depth--;\n      if (depth === 0) {\n        return { kind: 'found', value: text.slice(start, i + 1), start };\n      }\n    }\n  }\n  return start >= 0 ? { kind: 'unclosed', depth, start } : { kind: 'none' };\n}\n\n/**\n * The JSON-shaped candidate located within raw model text, plus where it\n * starts in that text.\n * @internal\n */\ninterface IJsonCandidate {\n  /** The whole input after BOM strip and trim, before any fence unwrap. */\n  readonly stripped: string;\n  /** The candidate itself: the trimmed fenced body when fenced, else `stripped`. */\n  readonly text: string;\n  /** Index of `text`'s first character within the original input. */\n  readonly base: number;\n}\n\n/**\n * Strips the wrappers a model adds around JSON — byte-order mark, surrounding\n * whitespace, Markdown code fence — and reports where what is left starts in\n * the original text.\n *\n * Single source of truth for that step: {@link extractJsonText} and\n * {@link classifyJsonParseFailure} must agree on what the candidate is, or a\n * classified `offset` would point into text the extractor never parsed.\n * @internal\n */\nfunction locateJsonCandidate(text: string): IJsonCandidate {\n  const noBom = stripBom(text);\n  const stripped = noBom.trim();\n  const strippedBase = text.length - noBom.length + (noBom.length - noBom.trimStart().length);\n\n  const fenced = FENCED_BLOCK.exec(stripped);\n  if (fenced === null) {\n    return { stripped, text: stripped, base: strippedBase };\n  }\n  const body = fenced[2];\n  return {\n    stripped,\n    text: body.trim(),\n    base: strippedBase + fenced.index + fenced[1].length + (body.length - body.trimStart().length)\n  };\n}\n\n/**\n * Default {@link AiAssist.JsonTextExtractor | extractor} for LLM responses. Tolerates:\n *\n * - Leading/trailing whitespace and a leading byte-order mark.\n * - Markdown code fences (with or without a language tag).\n * - Conversational preamble before the first `{` or `[`.\n * - Trailing prose after the matched closing `}` or `]`.\n *\n * Out of scope: repairing malformed JSON, handling smart quotes, etc.\n *\n * When an object or array opens but never closes before the end of input —\n * the shape a response truncated by a token cap leaves behind — the failure\n * names that specifically (distinct from the generic \"no JSON-shaped\n * substring found\" for input that never looked like JSON at all) and points\n * at `IAiCompletionResponse.truncated` and the `maxTokens` request option as\n * the likely cause and fix.\n *\n * @param text - Raw model output.\n * @returns A `Result<string>` containing the JSON-shaped substring, or a\n * `Failure` if no JSON-shaped substring was found.\n * @public\n */\nexport const extractJsonText: JsonTextExtractor = (text: string): Result<string> => {\n  if (typeof text !== 'string') {\n    return fail('extractJsonText: input must be a string.');\n  }\n  const located = locateJsonCandidate(text);\n  if (located.stripped.length === 0) {\n    return fail('extractJsonText: input is empty.');\n  }\n\n  const candidate = located.text;\n  if (candidate.length === 0) {\n    return fail('extractJsonText: no JSON content found.');\n  }\n\n  // Whole-candidate primitive check runs before the brace scan so that a\n  // valid JSON string containing braces (e.g. `\"text with { }\"`) is returned\n  // intact instead of being mangled into the first balanced `{ }` match.\n  if (JSON_KEYWORD.test(candidate) || JSON_NUMBER.test(candidate) || JSON_STRING.test(candidate)) {\n    return succeed(candidate);\n  }\n\n  const scan = findBalancedJsonSubstring(candidate);\n  if (scan.kind === 'found') {\n    return succeed(scan.value);\n  }\n  if (scan.kind === 'unclosed') {\n    return fail(\n      `extractJsonText: JSON structure opened but never closed (depth ${scan.depth} at end of input) — ` +\n        'response may have been truncated (check IAiCompletionResponse.truncated / raise maxTokens).'\n    );\n  }\n\n  return fail('extractJsonText: no JSON-shaped substring found.');\n};\n\n/**\n * Typed reason a JSON-shaped LLM response failed to parse, so a caller can\n * branch on the failure class instead of regex-matching the engine's\n * `JSON.parse` message (whose wording varies across V8 / Node versions).\n *\n * Every classified arm describes a fault at an **object property-name\n * position** — the position an LLM most often gets wrong, and the one whose\n * repair strategy differs most by case:\n *\n * - `'unquoted-property-name'`: a bare identifier where a quoted name belongs\n *   (`{ key: 1 }`). `token` is the identifier run, `offset` its first\n *   character. Identifier recognition is ASCII-only, so a non-ASCII bare name\n *   (`{ ключ: 1 }`) reports `'unknown'` rather than being named.\n * - `'single-quoted-property-name'`: a single-quoted name (`{ 'key': 1 }`).\n *   `token` is the quoted literal (or just `'` if it never closes), `offset`\n *   the opening quote.\n * - `'unterminated-property-name'`: a name whose closing `\"` is missing, and\n *   whose body swallowed structural text (`{ \"key: 1 }`). `token` is the\n *   unterminated fragment, `offset` the opening quote.\n * - `'elided-member'`: a `,` where a member is expected — a leading or doubled\n *   comma in an object (`{ , \"a\": 1 }`, `{ \"a\":1, , \"b\":2 }`) or an array\n *   (`[1, , 2]`). `token` is `','`, `offset` its position.\n * - `'unknown'`: the catch-all. The scan reached the end of the text, or hit a\n *   fault it cannot name with confidence, and reports nothing rather than\n *   guessing. Truncated responses, missing colons, trailing commas, bad number\n *   literals, and anything else not listed above land here.\n *\n * `offset` is a 0-based index into the `text` passed to\n * {@link AiAssist.classifyJsonParseFailure}, not into the extracted substring.\n * @public\n */\nexport type JsonParseFailureReason =\n  | { readonly kind: 'unquoted-property-name'; readonly token: string; readonly offset: number }\n  | { readonly kind: 'single-quoted-property-name'; readonly token: string; readonly offset: number }\n  | { readonly kind: 'unterminated-property-name'; readonly token: string; readonly offset: number }\n  | { readonly kind: 'elided-member'; readonly token: string; readonly offset: number }\n  | { readonly kind: 'unknown' };\n\nconst UNKNOWN_PARSE_FAILURE: JsonParseFailureReason = { kind: 'unknown' };\n\nconst JSON_WHITESPACE: RegExp = /[ \\t\\n\\r]/;\nconst IDENTIFIER_START: RegExp = /[A-Za-z0-9_$]/;\nconst IDENTIFIER_PART: RegExp = /[A-Za-z0-9_$.-]/;\n// Characters that end an unquoted value run (`true`, `null`, a number, or\n// garbage). Includes ':' so a stray colon at a value position produces an\n// empty run — reported as 'unknown' — instead of being swallowed by a literal.\nconst VALUE_RUN_TERMINATOR: RegExp = /[\\s,}\\]:\"'{[]/;\n\n/** Where the parse scan currently is within the JSON grammar. @internal */\ntype JsonScanExpectation = 'value' | 'name' | 'colon' | 'comma';\n\n/** Result of scanning a quoted run starting at a given opening quote. @internal */\ninterface IQuotedRunScan {\n  readonly terminated: boolean;\n  /** Index just past the closing quote, or end of text when unterminated. */\n  readonly end: number;\n  /** Content between the quotes, exclusive. */\n  readonly body: string;\n}\n\nfunction scanQuotedRun(text: string, start: number, quote: string): IQuotedRunScan {\n  let escape = false;\n  for (let i = start + 1; i < text.length; i++) {\n    const ch = text.charAt(i);\n    if (escape) {\n      escape = false;\n    } else if (ch === '\\\\') {\n      escape = true;\n    } else if (ch === quote) {\n      return { terminated: true, end: i + 1, body: text.slice(start + 1, i) };\n    }\n  }\n  return { terminated: false, end: text.length, body: text.slice(start + 1) };\n}\n\nfunction skipJsonWhitespace(text: string, from: number): number {\n  let i = from;\n  while (i < text.length && JSON_WHITESPACE.test(text.charAt(i))) {\n    i++;\n  }\n  return i;\n}\n\nfunction scanRun(text: string, from: number, isPart: (ch: string) => boolean): string {\n  let i = from;\n  while (i < text.length && isPart(text.charAt(i))) {\n    i++;\n  }\n  return text.slice(from, i);\n}\n\nfunction classifyAtPropertyName(\n  text: string,\n  i: number,\n  base: number\n): { readonly reason: JsonParseFailureReason } | { readonly next: number } {\n  const ch = text.charAt(i);\n  if (ch === '\"') {\n    const scan = scanQuotedRun(text, i, '\"');\n    if (scan.terminated) {\n      return { next: scan.end };\n    }\n    // An unterminated name is only distinguishable from a mid-name truncation\n    // when the swallowed body contains structural text — a ':' the author\n    // plainly meant as the name/value separator. Without that, stay honest.\n    return scan.body.includes(':')\n      ? { reason: { kind: 'unterminated-property-name', token: text.slice(i), offset: base + i } }\n      : { reason: UNKNOWN_PARSE_FAILURE };\n  }\n  if (ch === \"'\") {\n    const scan = scanQuotedRun(text, i, \"'\");\n    return {\n      reason: {\n        kind: 'single-quoted-property-name',\n        token: scan.terminated ? text.slice(i, scan.end) : \"'\",\n        offset: base + i\n      }\n    };\n  }\n  if (ch === ',') {\n    return { reason: { kind: 'elided-member', token: ',', offset: base + i } };\n  }\n  if (IDENTIFIER_START.test(ch)) {\n    return {\n      reason: {\n        kind: 'unquoted-property-name',\n        token: scanRun(text, i, (c) => IDENTIFIER_PART.test(c)),\n        offset: base + i\n      }\n    };\n  }\n  return { reason: UNKNOWN_PARSE_FAILURE };\n}\n\n/**\n * Walks `text` from `from` (the opening `{` or `[`) as a permissive JSON\n * scanner, reporting the first fault it can name with confidence. Anything it\n * cannot name — including a document that scans clean — yields `'unknown'`.\n *\n * The scan is structural: it never reads the engine's `JSON.parse` message, so\n * its verdicts do not drift with the Node version.\n * @internal\n */\nfunction scanForParseFailure(text: string, from: number, base: number): JsonParseFailureReason {\n  const stack: Array<'object' | 'array'> = [];\n  let expect: JsonScanExpectation = 'value';\n  let i = from;\n\n  for (;;) {\n    i = skipJsonWhitespace(text, i);\n    if (i >= text.length) {\n      return UNKNOWN_PARSE_FAILURE;\n    }\n    const ch = text.charAt(i);\n    const top = stack[stack.length - 1];\n\n    if (expect === 'name') {\n      if (ch === '}') {\n        stack.pop();\n        i++;\n        expect = 'comma';\n        continue;\n      }\n      const outcome = classifyAtPropertyName(text, i, base);\n      if ('reason' in outcome) {\n        return outcome.reason;\n      }\n      i = outcome.next;\n      expect = 'colon';\n      continue;\n    }\n\n    if (expect === 'colon') {\n      if (ch !== ':') {\n        return UNKNOWN_PARSE_FAILURE;\n      }\n      i++;\n      expect = 'value';\n      continue;\n    }\n\n    if (expect === 'value') {\n      if (ch === '{' || ch === '[') {\n        stack.push(ch === '{' ? 'object' : 'array');\n        i++;\n        expect = ch === '{' ? 'name' : 'value';\n        continue;\n      }\n      if (ch === ']' && top === 'array') {\n        stack.pop();\n        i++;\n        expect = 'comma';\n        continue;\n      }\n      if (ch === ',') {\n        return top === 'array'\n          ? { kind: 'elided-member', token: ',', offset: base + i }\n          : UNKNOWN_PARSE_FAILURE;\n      }\n      if (ch === '\"') {\n        const scan = scanQuotedRun(text, i, '\"');\n        if (!scan.terminated) {\n          // Could equally be a truncated value; the extractor already names\n          // truncation, so do not compete with it here.\n          return UNKNOWN_PARSE_FAILURE;\n        }\n        i = scan.end;\n        expect = 'comma';\n        continue;\n      }\n      const literal = scanRun(text, i, (c) => !VALUE_RUN_TERMINATOR.test(c));\n      if (literal.length === 0) {\n        return UNKNOWN_PARSE_FAILURE;\n      }\n      i += literal.length;\n      expect = 'comma';\n      continue;\n    }\n\n    // expect === 'comma': a complete value just closed.\n    if (top === undefined) {\n      return UNKNOWN_PARSE_FAILURE;\n    }\n    if (ch === ',') {\n      i++;\n      expect = top === 'object' ? 'name' : 'value';\n      continue;\n    }\n    if ((ch === '}' && top === 'object') || (ch === ']' && top === 'array')) {\n      stack.pop();\n      i++;\n      continue;\n    }\n    return UNKNOWN_PARSE_FAILURE;\n  }\n}\n\n/**\n * Classifies why a JSON-shaped LLM response would not parse, returning a\n * {@link AiAssist.JsonParseFailureReason} a caller can branch on — repair the\n * cheap cases, re-prompt the expensive ones, fail outright on the rest —\n * instead of regex-matching an engine-specific `JSON.parse` message.\n *\n * Pass the same raw model text you handed\n * {@link AiAssist.fencedStringifiedJson} or {@link AiAssist.extractJsonText};\n * this applies the same BOM / whitespace / fence / preamble handling before\n * scanning, and reports `offset` against that original text.\n *\n * Classification is **structural and deliberately conservative**. The scan\n * walks the JSON grammar itself rather than reading the engine's error string,\n * so its verdicts are stable across Node versions — and any fault it cannot\n * name with confidence comes back as `'unknown'` rather than a guess. In\n * particular an input that opened a structure and never closed it (the\n * truncated-response shape {@link AiAssist.extractJsonText} already diagnoses)\n * classifies as `'unknown'` here; the two diagnostics are complementary, not\n * competing.\n *\n * This never fails and never repairs — it only names the fault. It is a\n * diagnostic on the failure path, so calling it on text that parses fine is\n * harmless but pointless: it returns `'unknown'`.\n *\n * @example\n * ```ts\n * const parsed = fencedStringifiedJson({ inner }).convert(raw);\n * if (parsed.isFailure()) {\n *   const reason = classifyJsonParseFailure(raw);\n *   switch (reason.kind) {\n *     case 'unquoted-property-name': // cheap to repair\n *     case 'single-quoted-property-name':\n *       break;\n *     case 'elided-member':\n *     case 'unterminated-property-name': // worth a re-prompt\n *       break;\n *     default: // 'unknown' — fail outright\n *   }\n * }\n * ```\n *\n * @param text - Raw model output (the same string handed to the extractor).\n * @returns A {@link AiAssist.JsonParseFailureReason}.\n * @public\n */\nexport function classifyJsonParseFailure(text: string): JsonParseFailureReason {\n  // Defensive, and load-bearing for the documented totality: the signature says\n  // `string`, but a JS consumer — or a TS caller coming through an `unknown` /\n  // `any` escape hatch — can still hand us a non-string, and `locateJsonCandidate`\n  // would throw on it. `extractJsonText` already guards the same way; this keeps\n  // the pair consistent and keeps \"never fails\" true in practice rather than only\n  // under a well-typed caller.\n  if (typeof text !== 'string') {\n    return UNKNOWN_PARSE_FAILURE;\n  }\n  const candidate = locateJsonCandidate(text);\n  const scan = findBalancedJsonSubstring(candidate.text);\n  if (scan.kind === 'none') {\n    return UNKNOWN_PARSE_FAILURE;\n  }\n  return scanForParseFailure(candidate.text, scan.start, candidate.base);\n}\n\n/**\n * Options shared by every {@link AiAssist.fencedStringifiedJson} call.\n * @public\n */\nexport interface IFencedStringifiedJsonExtractorOptions {\n  /**\n   * Optional pre-parse extractor. Defaults to {@link AiAssist.extractJsonText}.\n   * Provide a custom extractor to handle response shapes the default does not\n   * understand.\n   */\n  readonly extractor?: JsonTextExtractor;\n}\n\n/**\n * Options for the validating overload of {@link AiAssist.fencedStringifiedJson}.\n * `inner` is required so the typed `Converter<T>` return value can never lie\n * about the runtime shape.\n * @public\n */\nexport interface IFencedStringifiedJsonOptions<T> extends IFencedStringifiedJsonExtractorOptions {\n  /** Inner converter or validator applied to the parsed JSON value. */\n  readonly inner: Converter<T> | Validator<T>;\n}\n\n/**\n * Creates a `Converter` that accepts raw LLM response text, runs it through a\n * tolerant extractor (default: {@link AiAssist.extractJsonText}), parses the\n * extracted substring as JSON, and applies an optional inner converter or\n * validator.\n *\n * @example\n * ```ts\n * const converter = fencedStringifiedJson({ inner: myShapeConverter });\n * const result = converter.convert(llmText); // Result<MyShape>\n * ```\n *\n * @param options - Optional extractor; omit to keep the default. Without an\n * `inner` step, the converter resolves to the parsed `JsonValue`.\n * @returns A `Converter<JsonValue>`.\n * @public\n */\nexport function fencedStringifiedJson(options?: IFencedStringifiedJsonExtractorOptions): Converter<JsonValue>;\n/**\n * Creates a `Converter` that accepts raw LLM response text, runs it through a\n * tolerant extractor (default: {@link AiAssist.extractJsonText}), parses the\n * extracted substring as JSON, and applies the supplied inner converter or\n * validator.\n *\n * @param options - Required `inner` converter/validator and optional extractor.\n * @returns A `Converter<T>`.\n * @public\n */\nexport function fencedStringifiedJson<T>(options: IFencedStringifiedJsonOptions<T>): Converter<T>;\nexport function fencedStringifiedJson<T>(\n  options?: IFencedStringifiedJsonExtractorOptions | IFencedStringifiedJsonOptions<T>\n): Converter<T | JsonValue> {\n  const extractor: JsonTextExtractor = options?.extractor ?? extractJsonText;\n  const inner = (options as IFencedStringifiedJsonOptions<T> | undefined)?.inner;\n  const parser: Converter<T | JsonValue> =\n    inner !== undefined ? JsonBaseConverters.stringifiedJson<T>(inner) : JsonBaseConverters.stringifiedJson();\n\n  return new Conversion.BaseConverter<T | JsonValue>((from: unknown): Result<T | JsonValue> => {\n    if (typeof from !== 'string') {\n      return fail('fencedStringifiedJson: input must be a string.');\n    }\n    return extractor(from).onSuccess((extracted) => parser.convert(extracted));\n  });\n}\n"]}