@fgv/ts-extras 5.1.0-45 → 5.1.0-46

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

@@ -10,7 +10,7 @@ export { callProviderEmbedding, callProxiedEmbedding } from './embeddingClient';
 export { callProviderCompletionStream, callProxiedCompletionStream, executeClientToolTurn } from './streamingClient';
 export { aiProviderId, aiServerToolType, aiWebSearchToolConfig, aiServerToolConfig, aiToolAnnotations, aiClientToolConfig, aiToolEnablement, aiAssistProviderConfig, aiAssistSettings, modelSpecKey, modelSpec } from './converters';
 export { resolveEffectiveTools } from './toolFormats';
-export { extractJsonText, fencedStringifiedJson } from './jsonResponse';
+export { classifyJsonParseFailure, extractJsonText, fencedStringifiedJson } from './jsonResponse';
 export { generateJsonCompletion, SMART_JSON_PROMPT_HINT } from './jsonCompletion';
 export { anthropicEffortToBudgetTokens } from './thinkingOptionsResolver';
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,QAAQ,EAER,oBAAoB,EAcpB,4BAA4B,EAe5B,iBAAiB,EAEjB,wBAAwB,EAoCxB,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EAEZ,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,4BAA4B,EAC5B,SAAS,EAiBV,MAAM,SAAS,CAAC;AAEjB,OAAO,EAEL,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,iBAAiB,EACjB,+BAA+B,EAChC,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,2BAA2B,EAC3B,0BAA0B,EAC1B,sBAAsB,EACtB,qBAAqB,EAItB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EAErB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,4BAA4B,EAC5B,2BAA2B,EAE3B,qBAAqB,EAItB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACV,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,EACL,eAAe,EACf,qBAAqB,EAItB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EAIvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,6BAA6B,EAAgC,MAAM,2BAA2B,CAAC","sourcesContent":["/**\n * AI assist packlet - provider registry, prompt class, settings, and API client.\n * @packageDocumentation\n */\n\nexport {\n  AiPrompt,\n  type AiModelCapability,\n  allModelCapabilities,\n  type AiProviderId,\n  type AiServerToolType,\n  type AiServerToolConfig,\n  type AiToolConfig,\n  type IAiWebSearchToolConfig,\n  type IAiClientToolConfig,\n  type IAiToolAnnotations,\n  type IAiClientTool,\n  type IAiClientToolCallSummary,\n  type IAiClientToolContinuation,\n  type IAiClientToolTurnResult,\n  type IAiToolEnablement,\n  type IAiCompletionResponse,\n  DEFAULT_ANTHROPIC_MAX_TOKENS,\n  type IChatMessage,\n  type IChatRequest,\n  type AiApiFormat,\n  type AiImageApiFormat,\n  type AiEmbeddingApiFormat,\n  type AiEmbeddingTaskType,\n  type IAiEmbeddingModelCapability,\n  type IAiEmbeddingParams,\n  type IAiEmbeddingUsage,\n  type IAiEmbeddingResult,\n  type IAiImageModelCapability,\n  type IAiProviderDescriptor,\n  type IAiAssistProviderConfig,\n  type IAiAssistSettings,\n  DEFAULT_AI_ASSIST,\n  type IAiAssistKeyStore,\n  providerApiKeySecretName,\n  type IAiImageAttachment,\n  type IAiImageData,\n  type AiImageSize,\n  type AiImageQuality,\n  type GptImageSize,\n  type GptImageQuality,\n  type GptImageModelNames,\n  type GrokImagineModelNames,\n  type GeminiFlashImageModelNames,\n  type IGptImageGenerationConfig,\n  type IGrokImagineImageGenerationConfig,\n  type IGeminiFlashImageGenerationConfig,\n  type IGptImageModelOptions,\n  type IGrokImagineModelOptions,\n  type IGeminiFlashImageModelOptions,\n  type IOtherModelOptions,\n  type IModelFamilyConfig,\n  type IAiImageGenerationOptions,\n  type IAiImageGenerationParams,\n  type IAiGeneratedImage,\n  type IAiImageGenerationResponse,\n  type IAiModelCapabilityRule,\n  type IAiModelCapabilityConfig,\n  type IAiModelInfo,\n  type IAiStreamEvent,\n  type IAiStreamTextDelta,\n  type IAiStreamToolEvent,\n  type IAiStreamToolUseStart,\n  type IAiStreamToolUseDelta,\n  type IAiStreamToolUseComplete,\n  type IAiStreamDone,\n  type IAiStreamError,\n  type ModelSpec,\n  type ModelSpecKey,\n  type IModelSpecMap,\n  allModelSpecKeys,\n  MODEL_SPEC_BASE_KEY,\n  resolveModel,\n  type IModelAliasMap,\n  MODEL_ALIAS_SIGIL,\n  resolveModelAlias,\n  resolveProviderModel,\n  isResponsesOnlyModel,\n  isAdaptiveThinkingModel,\n  usesMaxCompletionTokensField,\n  toDataUrl,\n  type AiThinkingMode,\n  type IThinkingConfig,\n  type IThinkingProviderConfig,\n  type IAnthropicThinkingOptions,\n  type IOpenAiThinkingOptions,\n  type IGeminiThinkingOptions,\n  type IXAiThinkingOptions,\n  type IOtherThinkingOptions,\n  type IAnthropicThinkingConfig,\n  type IOpenAiThinkingConfig,\n  type IGeminiThinkingConfig,\n  type IXAiThinkingConfig,\n  type AnthropicThinkingModelNames,\n  type OpenAiThinkingModelNames,\n  type GeminiThinkingModelNames,\n  type XAiThinkingModelNames\n} from './model';\n\nexport {\n  type IResolvedImageOptions,\n  resolveImageOptions,\n  validateResolvedOptions\n} from './imageOptionsResolver';\n\nexport {\n  allProviderIds,\n  getProviderDescriptors,\n  getProviderDescriptor,\n  resolveImageCapability,\n  supportsImageGeneration,\n  resolveEmbeddingCapability,\n  supportsEmbedding,\n  DEFAULT_MODEL_CAPABILITY_CONFIG\n} from './registry';\n\nexport {\n  callProviderCompletion,\n  callProxiedCompletion,\n  callProviderImageGeneration,\n  callProxiedImageGeneration,\n  callProviderListModels,\n  callProxiedListModels,\n  type IProviderCompletionParams,\n  type IProviderImageGenerationParams,\n  type IProviderListModelsParams\n} from './apiClient';\n\nexport {\n  callProviderEmbedding,\n  callProxiedEmbedding,\n  type IProviderEmbeddingParams\n} from './embeddingClient';\n\nexport {\n  callProviderCompletionStream,\n  callProxiedCompletionStream,\n  type IProviderCompletionStreamParams,\n  executeClientToolTurn,\n  type IExecuteClientToolTurnParams,\n  type IExecuteClientToolTurnResult,\n  type IToolExecutionDecision\n} from './streamingClient';\n\nexport {\n  aiProviderId,\n  aiServerToolType,\n  aiWebSearchToolConfig,\n  aiServerToolConfig,\n  aiToolAnnotations,\n  aiClientToolConfig,\n  aiToolEnablement,\n  aiAssistProviderConfig,\n  aiAssistSettings,\n  modelSpecKey,\n  modelSpec\n} from './converters';\n\nexport { resolveEffectiveTools } from './toolFormats';\n\nexport {\n  extractJsonText,\n  fencedStringifiedJson,\n  type IFencedStringifiedJsonExtractorOptions,\n  type IFencedStringifiedJsonOptions,\n  type JsonTextExtractor\n} from './jsonResponse';\n\nexport {\n  generateJsonCompletion,\n  SMART_JSON_PROMPT_HINT,\n  type IGenerateJsonCompletionParams,\n  type IGenerateJsonCompletionResult,\n  type JsonPromptHint\n} from './jsonCompletion';\n\nexport { anthropicEffortToBudgetTokens, type IResolvedThinkingConfig } from './thinkingOptionsResolver';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,QAAQ,EAER,oBAAoB,EAcpB,4BAA4B,EAe5B,iBAAiB,EAEjB,wBAAwB,EAoCxB,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EAEZ,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,4BAA4B,EAC5B,SAAS,EAiBV,MAAM,SAAS,CAAC;AAEjB,OAAO,EAEL,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,iBAAiB,EACjB,+BAA+B,EAChC,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,2BAA2B,EAC3B,0BAA0B,EAC1B,sBAAsB,EACtB,qBAAqB,EAItB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EAErB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,4BAA4B,EAC5B,2BAA2B,EAE3B,qBAAqB,EAItB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACV,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,qBAAqB,EAKtB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EAIvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,6BAA6B,EAAgC,MAAM,2BAA2B,CAAC","sourcesContent":["/**\n * AI assist packlet - provider registry, prompt class, settings, and API client.\n * @packageDocumentation\n */\n\nexport {\n  AiPrompt,\n  type AiModelCapability,\n  allModelCapabilities,\n  type AiProviderId,\n  type AiServerToolType,\n  type AiServerToolConfig,\n  type AiToolConfig,\n  type IAiWebSearchToolConfig,\n  type IAiClientToolConfig,\n  type IAiToolAnnotations,\n  type IAiClientTool,\n  type IAiClientToolCallSummary,\n  type IAiClientToolContinuation,\n  type IAiClientToolTurnResult,\n  type IAiToolEnablement,\n  type IAiCompletionResponse,\n  DEFAULT_ANTHROPIC_MAX_TOKENS,\n  type IChatMessage,\n  type IChatRequest,\n  type AiApiFormat,\n  type AiImageApiFormat,\n  type AiEmbeddingApiFormat,\n  type AiEmbeddingTaskType,\n  type IAiEmbeddingModelCapability,\n  type IAiEmbeddingParams,\n  type IAiEmbeddingUsage,\n  type IAiEmbeddingResult,\n  type IAiImageModelCapability,\n  type IAiProviderDescriptor,\n  type IAiAssistProviderConfig,\n  type IAiAssistSettings,\n  DEFAULT_AI_ASSIST,\n  type IAiAssistKeyStore,\n  providerApiKeySecretName,\n  type IAiImageAttachment,\n  type IAiImageData,\n  type AiImageSize,\n  type AiImageQuality,\n  type GptImageSize,\n  type GptImageQuality,\n  type GptImageModelNames,\n  type GrokImagineModelNames,\n  type GeminiFlashImageModelNames,\n  type IGptImageGenerationConfig,\n  type IGrokImagineImageGenerationConfig,\n  type IGeminiFlashImageGenerationConfig,\n  type IGptImageModelOptions,\n  type IGrokImagineModelOptions,\n  type IGeminiFlashImageModelOptions,\n  type IOtherModelOptions,\n  type IModelFamilyConfig,\n  type IAiImageGenerationOptions,\n  type IAiImageGenerationParams,\n  type IAiGeneratedImage,\n  type IAiImageGenerationResponse,\n  type IAiModelCapabilityRule,\n  type IAiModelCapabilityConfig,\n  type IAiModelInfo,\n  type IAiStreamEvent,\n  type IAiStreamTextDelta,\n  type IAiStreamToolEvent,\n  type IAiStreamToolUseStart,\n  type IAiStreamToolUseDelta,\n  type IAiStreamToolUseComplete,\n  type IAiStreamDone,\n  type IAiStreamError,\n  type ModelSpec,\n  type ModelSpecKey,\n  type IModelSpecMap,\n  allModelSpecKeys,\n  MODEL_SPEC_BASE_KEY,\n  resolveModel,\n  type IModelAliasMap,\n  MODEL_ALIAS_SIGIL,\n  resolveModelAlias,\n  resolveProviderModel,\n  isResponsesOnlyModel,\n  isAdaptiveThinkingModel,\n  usesMaxCompletionTokensField,\n  toDataUrl,\n  type AiThinkingMode,\n  type IThinkingConfig,\n  type IThinkingProviderConfig,\n  type IAnthropicThinkingOptions,\n  type IOpenAiThinkingOptions,\n  type IGeminiThinkingOptions,\n  type IXAiThinkingOptions,\n  type IOtherThinkingOptions,\n  type IAnthropicThinkingConfig,\n  type IOpenAiThinkingConfig,\n  type IGeminiThinkingConfig,\n  type IXAiThinkingConfig,\n  type AnthropicThinkingModelNames,\n  type OpenAiThinkingModelNames,\n  type GeminiThinkingModelNames,\n  type XAiThinkingModelNames\n} from './model';\n\nexport {\n  type IResolvedImageOptions,\n  resolveImageOptions,\n  validateResolvedOptions\n} from './imageOptionsResolver';\n\nexport {\n  allProviderIds,\n  getProviderDescriptors,\n  getProviderDescriptor,\n  resolveImageCapability,\n  supportsImageGeneration,\n  resolveEmbeddingCapability,\n  supportsEmbedding,\n  DEFAULT_MODEL_CAPABILITY_CONFIG\n} from './registry';\n\nexport {\n  callProviderCompletion,\n  callProxiedCompletion,\n  callProviderImageGeneration,\n  callProxiedImageGeneration,\n  callProviderListModels,\n  callProxiedListModels,\n  type IProviderCompletionParams,\n  type IProviderImageGenerationParams,\n  type IProviderListModelsParams\n} from './apiClient';\n\nexport {\n  callProviderEmbedding,\n  callProxiedEmbedding,\n  type IProviderEmbeddingParams\n} from './embeddingClient';\n\nexport {\n  callProviderCompletionStream,\n  callProxiedCompletionStream,\n  type IProviderCompletionStreamParams,\n  executeClientToolTurn,\n  type IExecuteClientToolTurnParams,\n  type IExecuteClientToolTurnResult,\n  type IToolExecutionDecision\n} from './streamingClient';\n\nexport {\n  aiProviderId,\n  aiServerToolType,\n  aiWebSearchToolConfig,\n  aiServerToolConfig,\n  aiToolAnnotations,\n  aiClientToolConfig,\n  aiToolEnablement,\n  aiAssistProviderConfig,\n  aiAssistSettings,\n  modelSpecKey,\n  modelSpec\n} from './converters';\n\nexport { resolveEffectiveTools } from './toolFormats';\n\nexport {\n  classifyJsonParseFailure,\n  extractJsonText,\n  fencedStringifiedJson,\n  type IFencedStringifiedJsonExtractorOptions,\n  type IFencedStringifiedJsonOptions,\n  type JsonParseFailureReason,\n  type JsonTextExtractor\n} from './jsonResponse';\n\nexport {\n  generateJsonCompletion,\n  SMART_JSON_PROMPT_HINT,\n  type IGenerateJsonCompletionParams,\n  type IGenerateJsonCompletionResult,\n  type JsonPromptHint\n} from './jsonCompletion';\n\nexport { anthropicEffortToBudgetTokens, type IResolvedThinkingConfig } from './thinkingOptionsResolver';\n"]}

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

@@ -33,7 +33,11 @@
  */
 import { Conversion, fail, succeed } from '@fgv/ts-utils';
 import { Converters as JsonBaseConverters } from '@fgv/ts-json-base';
-const FENCED_BLOCK = /```[A-Za-z0-9_-]*\s*\r?\n([\s\S]*?)\r?\n?```/;
+// 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).
@@ -88,11 +92,36 @@ function findBalancedJsonSubstring(text) {
         else if (ch === close) {
             depth--;
             if (depth === 0) {
-                return { kind: 'found', value: text.slice(start, i + 1) };
+                return { kind: 'found', value: text.slice(start, i + 1), start };
             }
         }
     }
-    return start >= 0 ? { kind: 'unclosed', depth } : { kind: 'none' };
+    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:
@@ -120,12 +149,11 @@ export const extractJsonText = (text) => {
     if (typeof text !== 'string') {
         return fail('extractJsonText: input must be a string.');
     }
-    const stripped = stripBom(text).trim();
-    if (stripped.length === 0) {
+    const located = locateJsonCandidate(text);
+    if (located.stripped.length === 0) {
         return fail('extractJsonText: input is empty.');
     }
-    const fenced = FENCED_BLOCK.exec(stripped);
-    const candidate = fenced ? fenced[1].trim() : stripped;
+    const candidate = located.text;
     if (candidate.length === 0) {
         return fail('extractJsonText: no JSON content found.');
     }
@@ -145,6 +173,241 @@ export const extractJsonText = (text) => {
     }
     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;

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

@@ -1 +1 @@
-{"version":3,"file":"jsonResponse.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/jsonResponse.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY;AAEZ;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAkB,IAAI,EAAU,OAAO,EAAkB,MAAM,eAAe,CAAC;AAClG,OAAO,EAAE,UAAU,IAAI,kBAAkB,EAAkB,MAAM,mBAAmB,CAAC;AAUrF,MAAM,YAAY,GAAW,8CAA8C,CAAC;AAC5E,MAAM,GAAG,GAAW,SAAS,CAAC;AAC9B,uEAAuE;AACvE,4EAA4E;AAC5E,MAAM,WAAW,GAAW,+CAA+C,CAAC;AAC5E,4CAA4C;AAC5C,MAAM,WAAW,GAAW,gEAAgE,CAAC;AAC7F,MAAM,YAAY,GAAW,uBAAuB,CAAC;AAErD,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC/B,CAAC;AAmBD,SAAS,yBAAyB,CAAC,IAAY;IAC7C,yEAAyE;IACzE,sEAAsE;IACtE,yEAAyE;IACzE,WAAW;IACX,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC;IACf,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,KAAK,GAAG,EAAE,CAAC;IACf,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAC1B,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,GAAG,KAAK,CAAC;YACjB,CAAC;iBAAM,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;gBACvB,MAAM,GAAG,IAAI,CAAC;YAChB,CAAC;iBAAM,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;gBACtB,QAAQ,GAAG,KAAK,CAAC;YACnB,CAAC;YACD,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACf,QAAQ,GAAG,IAAI,CAAC;YAChB,SAAS;QACX,CAAC;QACD,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;gBAC7B,KAAK,GAAG,CAAC,CAAC;gBACV,IAAI,GAAG,EAAE,CAAC;gBACV,KAAK,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;gBAC/B,KAAK,GAAG,CAAC,CAAC;YACZ,CAAC;YACD,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YAChB,KAAK,EAAE,CAAC;QACV,CAAC;aAAM,IAAI,EAAE,KAAK,KAAK,EAAE,CAAC;YACxB,KAAK,EAAE,CAAC;YACR,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;gBAChB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YAC5D,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAsB,CAAC,IAAY,EAAkB,EAAE;IACjF,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC,0CAA0C,CAAC,CAAC;IAC1D,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACvC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC,kCAAkC,CAAC,CAAC;IAClD,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;IAEvD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC,yCAAyC,CAAC,CAAC;IACzD,CAAC;IAED,uEAAuE;IACvE,2EAA2E;IAC3E,uEAAuE;IACvE,IAAI,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QAC/F,OAAO,OAAO,CAAC,SAAS,CAAC,CAAC;IAC5B,CAAC;IAED,MAAM,IAAI,GAAG,yBAAyB,CAAC,SAAS,CAAC,CAAC;IAClD,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC1B,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC7B,OAAO,IAAI,CACT,kEAAkE,IAAI,CAAC,KAAK,sBAAsB;YAChG,6FAA6F,CAChG,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC,kDAAkD,CAAC,CAAC;AAClE,CAAC,CAAC;AAuDF,MAAM,UAAU,qBAAqB,CACnC,OAAmF;;IAEnF,MAAM,SAAS,GAAsB,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,SAAS,mCAAI,eAAe,CAAC;IAC3E,MAAM,KAAK,GAAI,OAAwD,aAAxD,OAAO,uBAAP,OAAO,CAAmD,KAAK,CAAC;IAC/E,MAAM,MAAM,GACV,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,eAAe,CAAI,KAAK,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,eAAe,EAAE,CAAC;IAE5G,OAAO,IAAI,UAAU,CAAC,aAAa,CAAgB,CAAC,IAAa,EAAyB,EAAE;QAC1F,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC,gDAAgD,CAAC,CAAC;QAChE,CAAC;QACD,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;AACL,CAAC","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\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 * @internal\n */\ntype BalancedJsonScanResult =\n  | { readonly kind: 'found'; readonly value: string }\n  | { readonly kind: 'unclosed'; readonly depth: 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) };\n      }\n    }\n  }\n  return start >= 0 ? { kind: 'unclosed', depth } : { kind: 'none' };\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 stripped = stripBom(text).trim();\n  if (stripped.length === 0) {\n    return fail('extractJsonText: input is empty.');\n  }\n\n  const fenced = FENCED_BLOCK.exec(stripped);\n  const candidate = fenced ? fenced[1].trim() : stripped;\n\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 * 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"]}
+{"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"]}

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

@@ -216,6 +216,20 @@ export function resolveModelAlias(descriptor, model) {
  * `ModelSpec` branch is selected first; the resulting string — which may itself
  * be an fgv alias — is then resolved to a concrete id.
  *
+ * **This is the whole model-selection surface — do not hand-roll the walk.**
+ * Callers should pass the `ModelSpecKey` they want and use the concrete id
+ * this returns; a manual `resolveModel` + `resolveModelAlias` sequence is
+ * both redundant and easy to get wrong (it is how alias-form ids leak into
+ * capability lookups such as `resolveImageCapability`).
+ *
+ * **`context` carries the quality tier and the modality — never tools or
+ * thinking.** `ModelSpecKey` has no `tools` / `thinking` key: server-side
+ * tools and reasoning effort are orthogonal request params that ride on top of
+ * whatever model the tier selected, and never select a model. A tool-path caller
+ * passes a tier like any other caller — omit `context` for `base`, or pass
+ * `'advanced'` / `'frontier'` — and sets the tools / thinking request params
+ * separately.
+ *
  * @param descriptor - The provider descriptor (supplies `defaultModel` and `aliases`).
  * @param modelOverride - An optional caller-supplied `ModelSpec` that takes precedence
  * over `descriptor.defaultModel`. May itself contain or be an alias.