@fgv/ts-extras 5.1.0-4 → 5.1.0-40

package/lib/packlets/ai-assist/http.js

@@ -0,0 +1,78 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchJson = fetchJson;
+/**
+ * Shared low-level HTTP helpers for the AI-assist provider clients (completion,
+ * image generation, embedding). Internal to the packlet.
+ * @packageDocumentation
+ */
+const ts_json_base_1 = require("@fgv/ts-json-base");
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * Makes a JSON POST request and returns the parsed object body, or a failure.
+ * Non-2xx responses, network errors, invalid JSON, and non-object JSON bodies
+ * are all surfaced as `Result.fail`.
+ * @internal
+ */
+async function fetchJson(url, headers, body, logger, signal) {
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.detail(`AI API request: POST ${url}`);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: Object.assign({ 'Content-Type': 'application/json' }, headers),
+            body: JSON.stringify(body),
+            signal
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error(`AI API request failed: ${detail}`);
+        return (0, ts_utils_1.fail)(`AI API request failed: ${detail}`);
+    }
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => 'unknown error');
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error(`AI API returned ${response.status}: ${errorText}`);
+        return (0, ts_utils_1.fail)(`AI API returned ${response.status}: ${errorText}`);
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.detail(`AI API response: ${response.status}`);
+    let json;
+    try {
+        json = await response.json();
+    }
+    catch (_a) {
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error('AI API returned invalid JSON response');
+        return (0, ts_utils_1.fail)('AI API returned invalid JSON response');
+    }
+    if (!(0, ts_json_base_1.isJsonObject)(json)) {
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error('AI API returned non-object JSON response');
+        return (0, ts_utils_1.fail)('AI API returned non-object JSON response');
+    }
+    return (0, ts_utils_1.succeed)(json);
+}
+//# sourceMappingURL=http.js.map

package/lib/packlets/ai-assist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/http.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;;AA2BZ,8BAqDC;AA9ED;;;;GAIG;AAEH,oDAAkE;AAClE,4CAAoE;AAYpE;;;;;GAKG;AACI,KAAK,UAAU,SAAS,CAC7B,GAAW,EACX,OAA+B,EAC/B,IAAa,EACb,MAAwB,EACxB,MAAoB;IAEpB,wCAAwC;IACxC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,MAAM,CAAC,wBAAwB,GAAG,EAAE,CAAC,CAAC;IAE9C,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC1B,MAAM,EAAE,MAAM;YACd,OAAO,kBACL,cAAc,EAAE,kBAAkB,IAC/B,OAAO,CACX;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;YAC1B,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChE,wCAAwC;QACxC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,KAAK,CAAC,0BAA0B,MAAM,EAAE,CAAC,CAAC;QAClD,OAAO,IAAA,eAAI,EAAC,0BAA0B,MAAM,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,CAAC;QACrE,wCAAwC;QACxC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,KAAK,CAAC,mBAAmB,QAAQ,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC,CAAC;QAClE,OAAO,IAAA,eAAI,EAAC,mBAAmB,QAAQ,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC,CAAC;IAClE,CAAC;IAED,wCAAwC;IACxC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,MAAM,CAAC,oBAAoB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IAEtD,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,WAAM,CAAC;QACP,wCAAwC;QACxC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,KAAK,CAAC,uCAAuC,CAAC,CAAC;QACvD,OAAO,IAAA,eAAI,EAAC,uCAAuC,CAAC,CAAC;IACvD,CAAC;IAED,IAAI,CAAC,IAAA,2BAAY,EAAC,IAAI,CAAC,EAAE,CAAC;QACxB,wCAAwC;QACxC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC1D,OAAO,IAAA,eAAI,EAAC,0CAA0C,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,IAAA,kBAAO,EAAC,IAAI,CAAC,CAAC;AACvB,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 * Shared low-level HTTP helpers for the AI-assist provider clients (completion,\n * image generation, embedding). Internal to the packlet.\n * @packageDocumentation\n */\n\nimport { isJsonObject, type JsonObject } from '@fgv/ts-json-base';\nimport { fail, type Logging, Result, succeed } from '@fgv/ts-utils';\n\n/**\n * Internal API configuration built from a provider descriptor.\n * @internal\n */\nexport interface IAiApiConfig {\n  readonly baseUrl: string;\n  readonly apiKey: string;\n  readonly model: string;\n}\n\n/**\n * Makes a JSON POST request and returns the parsed object body, or a failure.\n * Non-2xx responses, network errors, invalid JSON, and non-object JSON bodies\n * are all surfaced as `Result.fail`.\n * @internal\n */\nexport async function fetchJson(\n  url: string,\n  headers: Record<string, string>,\n  body: unknown,\n  logger?: Logging.ILogger,\n  signal?: AbortSignal\n): Promise<Result<JsonObject>> {\n  /* c8 ignore next 1 - optional logger */\n  logger?.detail(`AI API request: POST ${url}`);\n\n  let response: Response;\n  try {\n    response = await fetch(url, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        ...headers\n      },\n      body: JSON.stringify(body),\n      signal\n    });\n  } catch (err: unknown) {\n    const detail = err instanceof Error ? err.message : String(err);\n    /* c8 ignore next 1 - optional logger */\n    logger?.error(`AI API request failed: ${detail}`);\n    return fail(`AI API request failed: ${detail}`);\n  }\n\n  if (!response.ok) {\n    const errorText = await response.text().catch(() => 'unknown error');\n    /* c8 ignore next 1 - optional logger */\n    logger?.error(`AI API returned ${response.status}: ${errorText}`);\n    return fail(`AI API returned ${response.status}: ${errorText}`);\n  }\n\n  /* c8 ignore next 1 - optional logger */\n  logger?.detail(`AI API response: ${response.status}`);\n\n  let json: unknown;\n  try {\n    json = await response.json();\n  } catch {\n    /* c8 ignore next 1 - optional logger */\n    logger?.error('AI API returned invalid JSON response');\n    return fail('AI API returned invalid JSON response');\n  }\n\n  if (!isJsonObject(json)) {\n    /* c8 ignore next 1 - optional logger */\n    logger?.error('AI API returned non-object JSON response');\n    return fail('AI API returned non-object JSON response');\n  }\n  return succeed(json);\n}\n"]}

package/lib/packlets/ai-assist/imageOptionsResolver.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Merge logic and runtime validation for image generation options.
+ * @packageDocumentation
+ */
+import { type JsonObject } from '@fgv/ts-json-base';
+import { Result } from '@fgv/ts-utils';
+import type { IAiImageModelCapability, IAiImageGenerationOptions } from './model';
+/**
+ * The resolved, merged wire parameters for an image generation request.
+ * Built from the layered options and ready for provider-specific encoding.
+ * @public
+ */
+export interface IResolvedImageOptions {
+    /** Number of images to generate. */
+    readonly n: number;
+    /** Image size (OpenAI-style pixel strings). */
+    readonly size?: string;
+    /** Quality tier. */
+    readonly quality?: string;
+    /** Seed for reproducibility. */
+    readonly seed?: number;
+    readonly outputFormat?: string;
+    readonly outputCompression?: number;
+    readonly background?: string;
+    readonly moderation?: string;
+    readonly aspectRatio?: string;
+    readonly resolution?: string;
+    readonly geminiAspectRatio?: string;
+    readonly otherParams?: JsonObject;
+}
+/**
+ * Resolves the merged image options for a given model and capability.
+ *
+ * @remarks
+ * **Merge precedence (later wins):**
+ * 1. Generic top-level options (size, count, quality, seed)
+ * 2. Family-generic blocks (models field omitted, provider matches)
+ * 3. Model-specific blocks (models array includes the resolved model name)
+ * 4. Other blocks (provider: 'other', models array includes model name)
+ *
+ * Provider-mismatch blocks are silently skipped.
+ *
+ * Within each tier, declaration order — later declaration wins.
+ *
+ * @param modelId - The resolved model string
+ * @param capability - The resolved IAiImageModelCapability for this model
+ * @param options - Caller-supplied options
+ * @returns The merged wire parameters
+ * @public
+ */
+export declare function resolveImageOptions(modelId: string, capability: IAiImageModelCapability, options: IAiImageGenerationOptions | undefined): IResolvedImageOptions;
+/**
+ * Validates the resolved options against per-model registry constraints.
+ *
+ * @remarks
+ * Fails fast on the first violation. Error format:
+ * `model "${model}": ${field} "${value}" is not accepted; accepted values: ${JSON.stringify(accepted)}`
+ *
+ * @param modelId - The resolved model string
+ * @param capability - The resolved capability entry from the registry
+ * @param resolved - The merged options from resolveImageOptions
+ * @returns The same resolved options on success, or a failure with a contextual message
+ * @public
+ */
+export declare function validateResolvedOptions(modelId: string, capability: IAiImageModelCapability, resolved: IResolvedImageOptions): Result<IResolvedImageOptions>;
+//# sourceMappingURL=imageOptionsResolver.d.ts.map

package/lib/packlets/ai-assist/imageOptionsResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageOptionsResolver.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/imageOptionsResolver.ts"],"names":[],"mappings":"AAoBA;;;GAGG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAQ,MAAM,EAAW,MAAM,eAAe,CAAC;AAEtD,OAAO,KAAK,EACV,uBAAuB,EACvB,yBAAyB,EAO1B,MAAM,SAAS,CAAC;AA6CjB;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,oCAAoC;IACpC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB;IACpB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,gCAAgC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAEpC,QAAQ,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC;CACnC;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,uBAAuB,EACnC,OAAO,EAAE,yBAAyB,GAAG,SAAS,GAC7C,qBAAqB,CAwCvB;AAiED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,uBAAuB,EACnC,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,CAAC,qBAAqB,CAAC,CAiC/B"}

package/lib/packlets/ai-assist/imageOptionsResolver.js

@@ -0,0 +1,197 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveImageOptions = resolveImageOptions;
+exports.validateResolvedOptions = validateResolvedOptions;
+const ts_utils_1 = require("@fgv/ts-utils");
+// ============================================================================
+// Provider lineage helpers
+// ============================================================================
+/** Maps AiImageApiFormat values to the corresponding IModelFamilyConfig provider discriminator. */
+function providerLineageForFormat(format) {
+    switch (format) {
+        case 'openai-images':
+            return 'openai';
+        case 'xai-images':
+        case 'xai-images-edits':
+            return 'xai';
+        case 'gemini-image-out':
+            return 'google';
+        default:
+            return undefined;
+    }
+}
+// ============================================================================
+// Type guards
+// ============================================================================
+function isGptImageModelOptions(block) {
+    return block.provider === 'openai' && block.family === 'gpt-image';
+}
+function isGrokImagineModelOptions(block) {
+    return block.provider === 'xai' && block.family === 'grok-imagine';
+}
+function isGeminiFlashImageModelOptions(block) {
+    return block.provider === 'google' && block.family === 'gemini-flash-image';
+}
+function isOtherModelOptions(block) {
+    return block.provider === 'other';
+}
+// ============================================================================
+// Merge logic
+// ============================================================================
+/**
+ * Resolves the merged image options for a given model and capability.
+ *
+ * @remarks
+ * **Merge precedence (later wins):**
+ * 1. Generic top-level options (size, count, quality, seed)
+ * 2. Family-generic blocks (models field omitted, provider matches)
+ * 3. Model-specific blocks (models array includes the resolved model name)
+ * 4. Other blocks (provider: 'other', models array includes model name)
+ *
+ * Provider-mismatch blocks are silently skipped.
+ *
+ * Within each tier, declaration order — later declaration wins.
+ *
+ * @param modelId - The resolved model string
+ * @param capability - The resolved IAiImageModelCapability for this model
+ * @param options - Caller-supplied options
+ * @returns The merged wire parameters
+ * @public
+ */
+function resolveImageOptions(modelId, capability, options) {
+    var _a, _b;
+    const opts = options !== null && options !== void 0 ? options : {};
+    const lineage = providerLineageForFormat(capability.format);
+    // Start from generic top-level
+    let resolved = Object.assign(Object.assign(Object.assign({ n: (_a = opts.count) !== null && _a !== void 0 ? _a : 1 }, (opts.size !== undefined ? { size: opts.size } : {})), (opts.quality !== undefined ? { quality: opts.quality } : {})), (opts.seed !== undefined ? { seed: opts.seed } : {}));
+    const modelBlocks = (_b = opts.models) !== null && _b !== void 0 ? _b : [];
+    // Tier 2: family-generic blocks (models field omitted, provider matches lineage)
+    for (const block of modelBlocks) {
+        if (block.provider !== lineage && block.provider !== 'other')
+            continue;
+        if (block.provider === 'other')
+            continue; // other blocks handled in tier 4
+        if (!isApplicableBlock(block, modelId))
+            continue;
+        if (!isFamilyGenericBlock(block))
+            continue;
+        resolved = applyBlock(resolved, block);
+    }
+    // Tier 3: model-specific blocks (models array includes this model)
+    for (const block of modelBlocks) {
+        if (block.provider !== lineage && block.provider !== 'other')
+            continue;
+        if (block.provider === 'other')
+            continue;
+        if (!isApplicableBlock(block, modelId))
+            continue;
+        if (isFamilyGenericBlock(block))
+            continue;
+        resolved = applyBlock(resolved, block);
+    }
+    // Tier 4: Other blocks (same precedence as model-specific)
+    for (const block of modelBlocks) {
+        if (!isOtherModelOptions(block))
+            continue;
+        if (!block.models.includes(modelId))
+            continue;
+        resolved = applyOtherBlock(resolved, block);
+    }
+    return resolved;
+}
+function isApplicableBlock(block, modelId) {
+    /* c8 ignore next 3 - defensive coding: other blocks are filtered before isApplicableBlock is called */
+    if (isOtherModelOptions(block)) {
+        return block.models.includes(modelId);
+    }
+    // Has models array? Must include this modelId.
+    const named = block;
+    if (named.models !== undefined && named.models.length > 0) {
+        return named.models.includes(modelId);
+    }
+    // No models array = family-generic = applies to all in this family
+    return true;
+}
+function isFamilyGenericBlock(block) {
+    /* c8 ignore next 1 - defensive coding: other blocks are filtered before isFamilyGenericBlock is called */
+    if (isOtherModelOptions(block))
+        return false;
+    const named = block;
+    return named.models === undefined || named.models.length === 0;
+}
+function applyBlock(resolved, block) {
+    if (isGptImageModelOptions(block)) {
+        return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, resolved), (block.config.size !== undefined ? { size: block.config.size } : {})), (block.config.quality !== undefined ? { quality: block.config.quality } : {})), (block.config.outputFormat !== undefined ? { outputFormat: block.config.outputFormat } : {})), (block.config.outputCompression !== undefined
+            ? { outputCompression: block.config.outputCompression }
+            : {})), (block.config.background !== undefined ? { background: block.config.background } : {})), (block.config.moderation !== undefined ? { moderation: block.config.moderation } : {}));
+    }
+    if (isGrokImagineModelOptions(block)) {
+        return Object.assign(Object.assign(Object.assign({}, resolved), (block.config.aspectRatio !== undefined ? { aspectRatio: block.config.aspectRatio } : {})), (block.config.resolution !== undefined ? { resolution: block.config.resolution } : {}));
+    }
+    if (isGeminiFlashImageModelOptions(block)) {
+        return Object.assign(Object.assign({}, resolved), (block.config.aspectRatio !== undefined ? { geminiAspectRatio: block.config.aspectRatio } : {}));
+    }
+    /* c8 ignore next 2 - defensive coding: exhaustive union, all family types handled above */
+    return resolved;
+}
+function applyOtherBlock(resolved, block) {
+    var _a;
+    return Object.assign(Object.assign({}, resolved), { otherParams: Object.assign(Object.assign({}, ((_a = resolved.otherParams) !== null && _a !== void 0 ? _a : {})), block.config) });
+}
+// ============================================================================
+// Runtime validation
+// ============================================================================
+/**
+ * Validates the resolved options against per-model registry constraints.
+ *
+ * @remarks
+ * Fails fast on the first violation. Error format:
+ * `model "${model}": ${field} "${value}" is not accepted; accepted values: ${JSON.stringify(accepted)}`
+ *
+ * @param modelId - The resolved model string
+ * @param capability - The resolved capability entry from the registry
+ * @param resolved - The merged options from resolveImageOptions
+ * @returns The same resolved options on success, or a failure with a contextual message
+ * @public
+ */
+function validateResolvedOptions(modelId, capability, resolved) {
+    // Validate count
+    if (capability.maxCount !== undefined && resolved.n > capability.maxCount) {
+        return (0, ts_utils_1.fail)(`model "${modelId}": count ${resolved.n} exceeds maximum of ${capability.maxCount}`);
+    }
+    // Validate size
+    if (capability.acceptedSizes !== undefined && resolved.size !== undefined) {
+        if (!capability.acceptedSizes.includes(resolved.size)) {
+            return (0, ts_utils_1.fail)(`model "${modelId}": size "${resolved.size}" is not accepted; accepted values: ${JSON.stringify(capability.acceptedSizes)}`);
+        }
+    }
+    // Validate quality
+    if (capability.supportsQualityParam &&
+        capability.acceptedQualities !== undefined &&
+        resolved.quality !== undefined) {
+        if (!capability.acceptedQualities.includes(resolved.quality)) {
+            return (0, ts_utils_1.fail)(`model "${modelId}": quality "${resolved.quality}" is not accepted; accepted values: ${JSON.stringify(capability.acceptedQualities)}`);
+        }
+    }
+    return (0, ts_utils_1.succeed)(resolved);
+}
+//# sourceMappingURL=imageOptionsResolver.js.map

package/lib/packlets/ai-assist/imageOptionsResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageOptionsResolver.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/imageOptionsResolver.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 * Merge logic and runtime validation for image generation options.\n * @packageDocumentation\n */\n\nimport { type JsonObject } from '@fgv/ts-json-base';\nimport { fail, Result, succeed } from '@fgv/ts-utils';\n\nimport type {\n  IAiImageModelCapability,\n  IAiImageGenerationOptions,\n  IModelFamilyConfig,\n  INamedModelFamilyConfig,\n  IGptImageModelOptions,\n  IGrokImagineModelOptions,\n  IGeminiFlashImageModelOptions,\n  IOtherModelOptions\n} from './model';\n\n// ============================================================================\n// Provider lineage helpers\n// ============================================================================\n\n/** Maps AiImageApiFormat values to the corresponding IModelFamilyConfig provider discriminator. */\nfunction providerLineageForFormat(format: string): 'openai' | 'xai' | 'google' | 'other' | undefined {\n  switch (format) {\n    case 'openai-images':\n      return 'openai';\n    case 'xai-images':\n    case 'xai-images-edits':\n      return 'xai';\n    case 'gemini-image-out':\n      return 'google';\n    default:\n      return undefined;\n  }\n}\n\n// ============================================================================\n// Type guards\n// ============================================================================\n\nfunction isGptImageModelOptions(block: IModelFamilyConfig): block is IGptImageModelOptions {\n  return block.provider === 'openai' && block.family === 'gpt-image';\n}\n\nfunction isGrokImagineModelOptions(block: IModelFamilyConfig): block is IGrokImagineModelOptions {\n  return block.provider === 'xai' && block.family === 'grok-imagine';\n}\n\nfunction isGeminiFlashImageModelOptions(block: IModelFamilyConfig): block is IGeminiFlashImageModelOptions {\n  return block.provider === 'google' && block.family === 'gemini-flash-image';\n}\n\nfunction isOtherModelOptions(block: IModelFamilyConfig): block is IOtherModelOptions {\n  return block.provider === 'other';\n}\n\n// ============================================================================\n// Resolved wire shape\n// ============================================================================\n\n/**\n * The resolved, merged wire parameters for an image generation request.\n * Built from the layered options and ready for provider-specific encoding.\n * @public\n */\nexport interface IResolvedImageOptions {\n  /** Number of images to generate. */\n  readonly n: number;\n  /** Image size (OpenAI-style pixel strings). */\n  readonly size?: string;\n  /** Quality tier. */\n  readonly quality?: string;\n  /** Seed for reproducibility. */\n  readonly seed?: number;\n  // GptImage-specific\n  readonly outputFormat?: string;\n  readonly outputCompression?: number;\n  readonly background?: string;\n  readonly moderation?: string;\n  // xAI-specific\n  readonly aspectRatio?: string;\n  readonly resolution?: string;\n  // Gemini Flash-specific\n  readonly geminiAspectRatio?: string;\n  // Other-block passthroughs (merged at model-specific tier)\n  readonly otherParams?: JsonObject;\n}\n\n// ============================================================================\n// Merge logic\n// ============================================================================\n\n/**\n * Resolves the merged image options for a given model and capability.\n *\n * @remarks\n * **Merge precedence (later wins):**\n * 1. Generic top-level options (size, count, quality, seed)\n * 2. Family-generic blocks (models field omitted, provider matches)\n * 3. Model-specific blocks (models array includes the resolved model name)\n * 4. Other blocks (provider: 'other', models array includes model name)\n *\n * Provider-mismatch blocks are silently skipped.\n *\n * Within each tier, declaration order — later declaration wins.\n *\n * @param modelId - The resolved model string\n * @param capability - The resolved IAiImageModelCapability for this model\n * @param options - Caller-supplied options\n * @returns The merged wire parameters\n * @public\n */\nexport function resolveImageOptions(\n  modelId: string,\n  capability: IAiImageModelCapability,\n  options: IAiImageGenerationOptions | undefined\n): IResolvedImageOptions {\n  const opts = options ?? {};\n  const lineage = providerLineageForFormat(capability.format);\n\n  // Start from generic top-level\n  let resolved: IResolvedImageOptions = {\n    n: opts.count ?? 1,\n    ...(opts.size !== undefined ? { size: opts.size } : {}),\n    ...(opts.quality !== undefined ? { quality: opts.quality } : {}),\n    ...(opts.seed !== undefined ? { seed: opts.seed } : {})\n  };\n\n  const modelBlocks = opts.models ?? [];\n\n  // Tier 2: family-generic blocks (models field omitted, provider matches lineage)\n  for (const block of modelBlocks) {\n    if (block.provider !== lineage && block.provider !== 'other') continue;\n    if (block.provider === 'other') continue; // other blocks handled in tier 4\n    if (!isApplicableBlock(block, modelId)) continue;\n    if (!isFamilyGenericBlock(block)) continue;\n    resolved = applyBlock(resolved, block);\n  }\n\n  // Tier 3: model-specific blocks (models array includes this model)\n  for (const block of modelBlocks) {\n    if (block.provider !== lineage && block.provider !== 'other') continue;\n    if (block.provider === 'other') continue;\n    if (!isApplicableBlock(block, modelId)) continue;\n    if (isFamilyGenericBlock(block)) continue;\n    resolved = applyBlock(resolved, block);\n  }\n\n  // Tier 4: Other blocks (same precedence as model-specific)\n  for (const block of modelBlocks) {\n    if (!isOtherModelOptions(block)) continue;\n    if (!block.models.includes(modelId)) continue;\n    resolved = applyOtherBlock(resolved, block);\n  }\n\n  return resolved;\n}\n\nfunction isApplicableBlock(block: IModelFamilyConfig, modelId: string): boolean {\n  /* c8 ignore next 3 - defensive coding: other blocks are filtered before isApplicableBlock is called */\n  if (isOtherModelOptions(block)) {\n    return block.models.includes(modelId);\n  }\n  // Has models array? Must include this modelId.\n  const named = block as INamedModelFamilyConfig;\n  if (named.models !== undefined && named.models.length > 0) {\n    return named.models.includes(modelId);\n  }\n  // No models array = family-generic = applies to all in this family\n  return true;\n}\n\nfunction isFamilyGenericBlock(block: IModelFamilyConfig): boolean {\n  /* c8 ignore next 1 - defensive coding: other blocks are filtered before isFamilyGenericBlock is called */\n  if (isOtherModelOptions(block)) return false;\n  const named = block as INamedModelFamilyConfig;\n  return named.models === undefined || named.models.length === 0;\n}\n\nfunction applyBlock(resolved: IResolvedImageOptions, block: IModelFamilyConfig): IResolvedImageOptions {\n  if (isGptImageModelOptions(block)) {\n    return {\n      ...resolved,\n      ...(block.config.size !== undefined ? { size: block.config.size } : {}),\n      ...(block.config.quality !== undefined ? { quality: block.config.quality } : {}),\n      ...(block.config.outputFormat !== undefined ? { outputFormat: block.config.outputFormat } : {}),\n      ...(block.config.outputCompression !== undefined\n        ? { outputCompression: block.config.outputCompression }\n        : {}),\n      ...(block.config.background !== undefined ? { background: block.config.background } : {}),\n      ...(block.config.moderation !== undefined ? { moderation: block.config.moderation } : {})\n    };\n  }\n  if (isGrokImagineModelOptions(block)) {\n    return {\n      ...resolved,\n      ...(block.config.aspectRatio !== undefined ? { aspectRatio: block.config.aspectRatio } : {}),\n      ...(block.config.resolution !== undefined ? { resolution: block.config.resolution } : {})\n    };\n  }\n  if (isGeminiFlashImageModelOptions(block)) {\n    return {\n      ...resolved,\n      ...(block.config.aspectRatio !== undefined ? { geminiAspectRatio: block.config.aspectRatio } : {})\n    };\n  }\n  /* c8 ignore next 2 - defensive coding: exhaustive union, all family types handled above */\n  return resolved;\n}\n\nfunction applyOtherBlock(resolved: IResolvedImageOptions, block: IOtherModelOptions): IResolvedImageOptions {\n  return {\n    ...resolved,\n    otherParams: { ...(resolved.otherParams ?? {}), ...block.config }\n  };\n}\n\n// ============================================================================\n// Runtime validation\n// ============================================================================\n\n/**\n * Validates the resolved options against per-model registry constraints.\n *\n * @remarks\n * Fails fast on the first violation. Error format:\n * `model \"${model}\": ${field} \"${value}\" is not accepted; accepted values: ${JSON.stringify(accepted)}`\n *\n * @param modelId - The resolved model string\n * @param capability - The resolved capability entry from the registry\n * @param resolved - The merged options from resolveImageOptions\n * @returns The same resolved options on success, or a failure with a contextual message\n * @public\n */\nexport function validateResolvedOptions(\n  modelId: string,\n  capability: IAiImageModelCapability,\n  resolved: IResolvedImageOptions\n): Result<IResolvedImageOptions> {\n  // Validate count\n  if (capability.maxCount !== undefined && resolved.n > capability.maxCount) {\n    return fail(`model \"${modelId}\": count ${resolved.n} exceeds maximum of ${capability.maxCount}`);\n  }\n\n  // Validate size\n  if (capability.acceptedSizes !== undefined && resolved.size !== undefined) {\n    if (!capability.acceptedSizes.includes(resolved.size)) {\n      return fail(\n        `model \"${modelId}\": size \"${resolved.size}\" is not accepted; accepted values: ${JSON.stringify(\n          capability.acceptedSizes\n        )}`\n      );\n    }\n  }\n\n  // Validate quality\n  if (\n    capability.supportsQualityParam &&\n    capability.acceptedQualities !== undefined &&\n    resolved.quality !== undefined\n  ) {\n    if (!capability.acceptedQualities.includes(resolved.quality)) {\n      return fail(\n        `model \"${modelId}\": quality \"${resolved.quality}\" is not accepted; accepted values: ${JSON.stringify(\n          capability.acceptedQualities\n        )}`\n      );\n    }\n  }\n\n  return succeed(resolved);\n}\n"]}

package/lib/packlets/ai-assist/index.d.ts

@@ -2,9 +2,15 @@
  * AI assist packlet - provider registry, prompt class, settings, and API client.
  * @packageDocumentation
  */
-export { AiPrompt, type AiProviderId, type AiServerToolType, type AiServerToolConfig, type IAiWebSearchToolConfig, type IAiToolEnablement, type IAiCompletionResponse, type IChatMessage, type AiApiFormat, type IAiProviderDescriptor, type IAiAssistProviderConfig, type IAiAssistSettings, DEFAULT_AI_ASSIST, type IAiAssistKeyStore, type ModelSpec, type ModelSpecKey, type IModelSpecMap, allModelSpecKeys, MODEL_SPEC_BASE_KEY, resolveModel } from './model';
-export { allProviderIds, getProviderDescriptors, getProviderDescriptor } from './registry';
-export { callProviderCompletion, callProxiedCompletion, type IProviderCompletionParams } from './apiClient';
-export { aiProviderId, aiServerToolType, aiWebSearchToolConfig, aiServerToolConfig, aiToolEnablement, aiAssistProviderConfig, aiAssistSettings, modelSpecKey, modelSpec } from './converters';
+export { AiPrompt, type AiModelCapability, allModelCapabilities, type AiProviderId, type AiServerToolType, type AiServerToolConfig, type AiToolConfig, type IAiWebSearchToolConfig, type IAiClientToolConfig, type IAiToolAnnotations, type IAiClientTool, type IAiClientToolCallSummary, type IAiClientToolContinuation, type IAiClientToolTurnResult, type IAiToolEnablement, type IAiCompletionResponse, type IChatMessage, type IChatRequest, type AiApiFormat, type AiImageApiFormat, type AiEmbeddingApiFormat, type AiEmbeddingTaskType, type IAiEmbeddingModelCapability, type IAiEmbeddingParams, type IAiEmbeddingUsage, type IAiEmbeddingResult, type IAiImageModelCapability, type IAiProviderDescriptor, type IAiAssistProviderConfig, type IAiAssistSettings, DEFAULT_AI_ASSIST, type IAiAssistKeyStore, type IAiImageAttachment, type IAiImageData, type AiImageSize, type AiImageQuality, type GptImageSize, type GptImageQuality, type GptImageModelNames, type GrokImagineModelNames, type GeminiFlashImageModelNames, type IGptImageGenerationConfig, type IGrokImagineImageGenerationConfig, type IGeminiFlashImageGenerationConfig, type IGptImageModelOptions, type IGrokImagineModelOptions, type IGeminiFlashImageModelOptions, type IOtherModelOptions, type IModelFamilyConfig, type IAiImageGenerationOptions, type IAiImageGenerationParams, type IAiGeneratedImage, type IAiImageGenerationResponse, type IAiModelCapabilityRule, type IAiModelCapabilityConfig, type IAiModelInfo, type IAiStreamEvent, type IAiStreamTextDelta, type IAiStreamToolEvent, type IAiStreamToolUseStart, type IAiStreamToolUseDelta, type IAiStreamToolUseComplete, type IAiStreamDone, type IAiStreamError, type ModelSpec, type ModelSpecKey, type IModelSpecMap, allModelSpecKeys, MODEL_SPEC_BASE_KEY, resolveModel, type IModelAliasMap, MODEL_ALIAS_SIGIL, resolveModelAlias, resolveProviderModel, isResponsesOnlyModel, toDataUrl, type AiThinkingMode, type IThinkingConfig, type IThinkingProviderConfig, type IAnthropicThinkingOptions, type IOpenAiThinkingOptions, type IGeminiThinkingOptions, type IXAiThinkingOptions, type IOtherThinkingOptions, type IAnthropicThinkingConfig, type IOpenAiThinkingConfig, type IGeminiThinkingConfig, type IXAiThinkingConfig, type AnthropicThinkingModelNames, type OpenAiThinkingModelNames, type GeminiThinkingModelNames, type XAiThinkingModelNames } from './model';
+export { type IResolvedImageOptions, resolveImageOptions, validateResolvedOptions } from './imageOptionsResolver';
+export { allProviderIds, getProviderDescriptors, getProviderDescriptor, resolveImageCapability, supportsImageGeneration, resolveEmbeddingCapability, supportsEmbedding, DEFAULT_MODEL_CAPABILITY_CONFIG } from './registry';
+export { callProviderCompletion, callProxiedCompletion, callProviderImageGeneration, callProxiedImageGeneration, callProviderListModels, callProxiedListModels, type IProviderCompletionParams, type IProviderImageGenerationParams, type IProviderListModelsParams } from './apiClient';
+export { callProviderEmbedding, callProxiedEmbedding, type IProviderEmbeddingParams } from './embeddingClient';
+export { callProviderCompletionStream, callProxiedCompletionStream, type IProviderCompletionStreamParams, executeClientToolTurn, type IExecuteClientToolTurnParams, type IExecuteClientToolTurnResult, type IToolExecutionDecision } from './streamingClient';
+export { aiProviderId, aiServerToolType, aiWebSearchToolConfig, aiServerToolConfig, aiToolAnnotations, aiClientToolConfig, aiToolEnablement, aiAssistProviderConfig, aiAssistSettings, modelSpecKey, modelSpec } from './converters';
 export { resolveEffectiveTools } from './toolFormats';
+export { extractJsonText, fencedStringifiedJson, type IFencedStringifiedJsonExtractorOptions, type IFencedStringifiedJsonOptions, type JsonTextExtractor } from './jsonResponse';
+export { generateJsonCompletion, SMART_JSON_PROMPT_HINT, type IGenerateJsonCompletionParams, type IGenerateJsonCompletionResult, type JsonPromptHint } from './jsonCompletion';
+export { anthropicEffortToBudgetTokens, type IResolvedThinkingConfig } from './thinkingOptionsResolver';
 //# sourceMappingURL=index.d.ts.map

package/lib/packlets/ai-assist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,QAAQ,EACR,KAAK,iBAAiB,EACtB,oBAAoB,EACpB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EAChC,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,iCAAiC,EACtC,KAAK,iCAAiC,EACtC,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,6BAA6B,EAClC,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,KAAK,cAAc,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,SAAS,EACT,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC3B,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,KAAK,qBAAqB,EAC1B,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,EACrB,KAAK,yBAAyB,EAC9B,KAAK,8BAA8B,EACnC,KAAK,yBAAyB,EAC/B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,KAAK,wBAAwB,EAC9B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,4BAA4B,EAC5B,2BAA2B,EAC3B,KAAK,+BAA+B,EACpC,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,EACjC,KAAK,sBAAsB,EAC5B,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,EACrB,KAAK,sCAAsC,EAC3C,KAAK,6BAA6B,EAClC,KAAK,iBAAiB,EACvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,EAClC,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,6BAA6B,EAAE,KAAK,uBAAuB,EAAE,MAAM,2BAA2B,CAAC"}

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

@@ -4,25 +4,52 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveEffectiveTools = exports.modelSpec = exports.modelSpecKey = exports.aiAssistSettings = exports.aiAssistProviderConfig = exports.aiToolEnablement = exports.aiServerToolConfig = exports.aiWebSearchToolConfig = exports.aiServerToolType = exports.aiProviderId = exports.callProxiedCompletion = exports.callProviderCompletion = exports.getProviderDescriptor = exports.getProviderDescriptors = exports.allProviderIds = exports.resolveModel = exports.MODEL_SPEC_BASE_KEY = exports.allModelSpecKeys = exports.DEFAULT_AI_ASSIST = exports.AiPrompt = void 0;
+exports.anthropicEffortToBudgetTokens = exports.SMART_JSON_PROMPT_HINT = exports.generateJsonCompletion = exports.fencedStringifiedJson = exports.extractJsonText = exports.resolveEffectiveTools = exports.modelSpec = exports.modelSpecKey = exports.aiAssistSettings = exports.aiAssistProviderConfig = exports.aiToolEnablement = exports.aiClientToolConfig = exports.aiToolAnnotations = exports.aiServerToolConfig = exports.aiWebSearchToolConfig = exports.aiServerToolType = exports.aiProviderId = exports.executeClientToolTurn = exports.callProxiedCompletionStream = exports.callProviderCompletionStream = exports.callProxiedEmbedding = exports.callProviderEmbedding = exports.callProxiedListModels = exports.callProviderListModels = exports.callProxiedImageGeneration = exports.callProviderImageGeneration = exports.callProxiedCompletion = exports.callProviderCompletion = exports.DEFAULT_MODEL_CAPABILITY_CONFIG = exports.supportsEmbedding = exports.resolveEmbeddingCapability = exports.supportsImageGeneration = exports.resolveImageCapability = exports.getProviderDescriptor = exports.getProviderDescriptors = exports.allProviderIds = exports.validateResolvedOptions = exports.resolveImageOptions = exports.toDataUrl = exports.isResponsesOnlyModel = exports.resolveProviderModel = exports.resolveModelAlias = exports.MODEL_ALIAS_SIGIL = exports.resolveModel = exports.MODEL_SPEC_BASE_KEY = exports.allModelSpecKeys = exports.DEFAULT_AI_ASSIST = exports.allModelCapabilities = exports.AiPrompt = void 0;
 var model_1 = require("./model");
 Object.defineProperty(exports, "AiPrompt", { enumerable: true, get: function () { return model_1.AiPrompt; } });
+Object.defineProperty(exports, "allModelCapabilities", { enumerable: true, get: function () { return model_1.allModelCapabilities; } });
 Object.defineProperty(exports, "DEFAULT_AI_ASSIST", { enumerable: true, get: function () { return model_1.DEFAULT_AI_ASSIST; } });
 Object.defineProperty(exports, "allModelSpecKeys", { enumerable: true, get: function () { return model_1.allModelSpecKeys; } });
 Object.defineProperty(exports, "MODEL_SPEC_BASE_KEY", { enumerable: true, get: function () { return model_1.MODEL_SPEC_BASE_KEY; } });
 Object.defineProperty(exports, "resolveModel", { enumerable: true, get: function () { return model_1.resolveModel; } });
+Object.defineProperty(exports, "MODEL_ALIAS_SIGIL", { enumerable: true, get: function () { return model_1.MODEL_ALIAS_SIGIL; } });
+Object.defineProperty(exports, "resolveModelAlias", { enumerable: true, get: function () { return model_1.resolveModelAlias; } });
+Object.defineProperty(exports, "resolveProviderModel", { enumerable: true, get: function () { return model_1.resolveProviderModel; } });
+Object.defineProperty(exports, "isResponsesOnlyModel", { enumerable: true, get: function () { return model_1.isResponsesOnlyModel; } });
+Object.defineProperty(exports, "toDataUrl", { enumerable: true, get: function () { return model_1.toDataUrl; } });
+var imageOptionsResolver_1 = require("./imageOptionsResolver");
+Object.defineProperty(exports, "resolveImageOptions", { enumerable: true, get: function () { return imageOptionsResolver_1.resolveImageOptions; } });
+Object.defineProperty(exports, "validateResolvedOptions", { enumerable: true, get: function () { return imageOptionsResolver_1.validateResolvedOptions; } });
 var registry_1 = require("./registry");
 Object.defineProperty(exports, "allProviderIds", { enumerable: true, get: function () { return registry_1.allProviderIds; } });
 Object.defineProperty(exports, "getProviderDescriptors", { enumerable: true, get: function () { return registry_1.getProviderDescriptors; } });
 Object.defineProperty(exports, "getProviderDescriptor", { enumerable: true, get: function () { return registry_1.getProviderDescriptor; } });
+Object.defineProperty(exports, "resolveImageCapability", { enumerable: true, get: function () { return registry_1.resolveImageCapability; } });
+Object.defineProperty(exports, "supportsImageGeneration", { enumerable: true, get: function () { return registry_1.supportsImageGeneration; } });
+Object.defineProperty(exports, "resolveEmbeddingCapability", { enumerable: true, get: function () { return registry_1.resolveEmbeddingCapability; } });
+Object.defineProperty(exports, "supportsEmbedding", { enumerable: true, get: function () { return registry_1.supportsEmbedding; } });
+Object.defineProperty(exports, "DEFAULT_MODEL_CAPABILITY_CONFIG", { enumerable: true, get: function () { return registry_1.DEFAULT_MODEL_CAPABILITY_CONFIG; } });
 var apiClient_1 = require("./apiClient");
 Object.defineProperty(exports, "callProviderCompletion", { enumerable: true, get: function () { return apiClient_1.callProviderCompletion; } });
 Object.defineProperty(exports, "callProxiedCompletion", { enumerable: true, get: function () { return apiClient_1.callProxiedCompletion; } });
+Object.defineProperty(exports, "callProviderImageGeneration", { enumerable: true, get: function () { return apiClient_1.callProviderImageGeneration; } });
+Object.defineProperty(exports, "callProxiedImageGeneration", { enumerable: true, get: function () { return apiClient_1.callProxiedImageGeneration; } });
+Object.defineProperty(exports, "callProviderListModels", { enumerable: true, get: function () { return apiClient_1.callProviderListModels; } });
+Object.defineProperty(exports, "callProxiedListModels", { enumerable: true, get: function () { return apiClient_1.callProxiedListModels; } });
+var embeddingClient_1 = require("./embeddingClient");
+Object.defineProperty(exports, "callProviderEmbedding", { enumerable: true, get: function () { return embeddingClient_1.callProviderEmbedding; } });
+Object.defineProperty(exports, "callProxiedEmbedding", { enumerable: true, get: function () { return embeddingClient_1.callProxiedEmbedding; } });
+var streamingClient_1 = require("./streamingClient");
+Object.defineProperty(exports, "callProviderCompletionStream", { enumerable: true, get: function () { return streamingClient_1.callProviderCompletionStream; } });
+Object.defineProperty(exports, "callProxiedCompletionStream", { enumerable: true, get: function () { return streamingClient_1.callProxiedCompletionStream; } });
+Object.defineProperty(exports, "executeClientToolTurn", { enumerable: true, get: function () { return streamingClient_1.executeClientToolTurn; } });
 var converters_1 = require("./converters");
 Object.defineProperty(exports, "aiProviderId", { enumerable: true, get: function () { return converters_1.aiProviderId; } });
 Object.defineProperty(exports, "aiServerToolType", { enumerable: true, get: function () { return converters_1.aiServerToolType; } });
 Object.defineProperty(exports, "aiWebSearchToolConfig", { enumerable: true, get: function () { return converters_1.aiWebSearchToolConfig; } });
 Object.defineProperty(exports, "aiServerToolConfig", { enumerable: true, get: function () { return converters_1.aiServerToolConfig; } });
+Object.defineProperty(exports, "aiToolAnnotations", { enumerable: true, get: function () { return converters_1.aiToolAnnotations; } });
+Object.defineProperty(exports, "aiClientToolConfig", { enumerable: true, get: function () { return converters_1.aiClientToolConfig; } });
 Object.defineProperty(exports, "aiToolEnablement", { enumerable: true, get: function () { return converters_1.aiToolEnablement; } });
 Object.defineProperty(exports, "aiAssistProviderConfig", { enumerable: true, get: function () { return converters_1.aiAssistProviderConfig; } });
 Object.defineProperty(exports, "aiAssistSettings", { enumerable: true, get: function () { return converters_1.aiAssistSettings; } });
@@ -30,4 +57,12 @@ Object.defineProperty(exports, "modelSpecKey", { enumerable: true, get: function
 Object.defineProperty(exports, "modelSpec", { enumerable: true, get: function () { return converters_1.modelSpec; } });
 var toolFormats_1 = require("./toolFormats");
 Object.defineProperty(exports, "resolveEffectiveTools", { enumerable: true, get: function () { return toolFormats_1.resolveEffectiveTools; } });
+var jsonResponse_1 = require("./jsonResponse");
+Object.defineProperty(exports, "extractJsonText", { enumerable: true, get: function () { return jsonResponse_1.extractJsonText; } });
+Object.defineProperty(exports, "fencedStringifiedJson", { enumerable: true, get: function () { return jsonResponse_1.fencedStringifiedJson; } });
+var jsonCompletion_1 = require("./jsonCompletion");
+Object.defineProperty(exports, "generateJsonCompletion", { enumerable: true, get: function () { return jsonCompletion_1.generateJsonCompletion; } });
+Object.defineProperty(exports, "SMART_JSON_PROMPT_HINT", { enumerable: true, get: function () { return jsonCompletion_1.SMART_JSON_PROMPT_HINT; } });
+var thinkingOptionsResolver_1 = require("./thinkingOptionsResolver");
+Object.defineProperty(exports, "anthropicEffortToBudgetTokens", { enumerable: true, get: function () { return thinkingOptionsResolver_1.anthropicEffortToBudgetTokens; } });
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,iCA6FiB;AA5Ff,iGAAA,QAAQ,OAAA;AAER,6GAAA,oBAAoB,OAAA;AA4BpB,0GAAA,iBAAiB,OAAA;AAqCjB,yGAAA,gBAAgB,OAAA;AAChB,4GAAA,mBAAmB,OAAA;AACnB,qGAAA,YAAY,OAAA;AAEZ,0GAAA,iBAAiB,OAAA;AACjB,0GAAA,iBAAiB,OAAA;AACjB,6GAAA,oBAAoB,OAAA;AACpB,6GAAA,oBAAoB,OAAA;AACpB,kGAAA,SAAS,OAAA;AAmBX,+DAIgC;AAF9B,2HAAA,mBAAmB,OAAA;AACnB,+HAAA,uBAAuB,OAAA;AAGzB,uCASoB;AARlB,0GAAA,cAAc,OAAA;AACd,kHAAA,sBAAsB,OAAA;AACtB,iHAAA,qBAAqB,OAAA;AACrB,kHAAA,sBAAsB,OAAA;AACtB,mHAAA,uBAAuB,OAAA;AACvB,sHAAA,0BAA0B,OAAA;AAC1B,6GAAA,iBAAiB,OAAA;AACjB,2HAAA,+BAA+B,OAAA;AAGjC,yCAUqB;AATnB,mHAAA,sBAAsB,OAAA;AACtB,kHAAA,qBAAqB,OAAA;AACrB,wHAAA,2BAA2B,OAAA;AAC3B,uHAAA,0BAA0B,OAAA;AAC1B,mHAAA,sBAAsB,OAAA;AACtB,kHAAA,qBAAqB,OAAA;AAMvB,qDAI2B;AAHzB,wHAAA,qBAAqB,OAAA;AACrB,uHAAA,oBAAoB,OAAA;AAItB,qDAQ2B;AAPzB,+HAAA,4BAA4B,OAAA;AAC5B,8HAAA,2BAA2B,OAAA;AAE3B,wHAAA,qBAAqB,OAAA;AAMvB,2CAYsB;AAXpB,0GAAA,YAAY,OAAA;AACZ,8GAAA,gBAAgB,OAAA;AAChB,mHAAA,qBAAqB,OAAA;AACrB,gHAAA,kBAAkB,OAAA;AAClB,+GAAA,iBAAiB,OAAA;AACjB,gHAAA,kBAAkB,OAAA;AAClB,8GAAA,gBAAgB,OAAA;AAChB,oHAAA,sBAAsB,OAAA;AACtB,8GAAA,gBAAgB,OAAA;AAChB,0GAAA,YAAY,OAAA;AACZ,uGAAA,SAAS,OAAA;AAGX,6CAAsD;AAA7C,oHAAA,qBAAqB,OAAA;AAE9B,+CAMwB;AALtB,+GAAA,eAAe,OAAA;AACf,qHAAA,qBAAqB,OAAA;AAMvB,mDAM0B;AALxB,wHAAA,sBAAsB,OAAA;AACtB,wHAAA,sBAAsB,OAAA;AAMxB,qEAAwG;AAA/F,wIAAA,6BAA6B,OAAA","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  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  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  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"]}

package/lib/packlets/ai-assist/jsonCompletion.d.ts

@@ -0,0 +1,93 @@
+/**
+ * `generateJsonCompletion<T>` — request a JSON-shaped completion from any
+ * provider supported by AiAssist and validate it against a caller-supplied
+ * `Converter<T>` or `Validator<T>`. Wraps fence/preamble tolerance + parsing +
+ * validation into a single call so consumers don't reinvent the pipeline.
+ *
+ * @packageDocumentation
+ */
+import { type Converter, Result, type Validator } from '@fgv/ts-utils';
+import { type IProviderCompletionParams } from './apiClient';
+import { type IAiCompletionResponse } from './model';
+/**
+ * Default system-prompt suffix appended when {@link AiAssist.IGenerateJsonCompletionParams.promptHint}
+ * is `'smart'` (the default). Designed to discourage code fences and prose in
+ * the model's response while still tolerating them via the read-side extractor.
+ * @public
+ */
+export declare const SMART_JSON_PROMPT_HINT: string;
+/**
+ * Controls the optional system-prompt augmentation applied by
+ * {@link AiAssist.generateJsonCompletion}.
+ *
+ * - `'smart'` (default): append {@link AiAssist.SMART_JSON_PROMPT_HINT}.
+ * - `'none'`: do not modify the prompt.
+ * - A string: append the supplied text verbatim.
+ *
+ * @remarks
+ * The `string & {}` branch is the standard TypeScript trick that prevents
+ * the literal members from being widened away — callers still get
+ * autocomplete for `'smart'` and `'none'` while accepting any string.
+ *
+ * @public
+ */
+export type JsonPromptHint = 'smart' | 'none' | (string & {});
+/**
+ * Parameters for {@link AiAssist.generateJsonCompletion}. Extends
+ * {@link AiAssist.IProviderCompletionParams} with JSON-validation knobs.
+ * @public
+ */
+export interface IGenerateJsonCompletionParams<T> extends IProviderCompletionParams {
+    /**
+     * Caller-supplied `Converter<T>` or `Validator<T>` applied to the parsed
+     * JSON value. Wrapped internally in {@link AiAssist.fencedStringifiedJson}
+     * unless {@link AiAssist.IGenerateJsonCompletionParams.jsonConverter} is
+     * provided.
+     */
+    readonly converter?: Converter<T> | Validator<T>;
+    /**
+     * Full string-to-`T` pipeline override. When supplied, takes precedence over
+     * {@link AiAssist.IGenerateJsonCompletionParams.converter} and lets the
+     * caller plug in a custom extractor or skip the default fence tolerance
+     * entirely.
+     */
+    readonly jsonConverter?: Converter<T>;
+    /**
+     * Controls the optional system-prompt augmentation. Defaults to `'smart'`.
+     * Pass `'none'` to disable, or a string to append custom guidance.
+     */
+    readonly promptHint?: JsonPromptHint;
+}
+/**
+ * Successful result of {@link AiAssist.generateJsonCompletion}.
+ * @public
+ */
+export interface IGenerateJsonCompletionResult<T> {
+    /** The validated JSON value. */
+    readonly value: T;
+    /** The raw response text returned by the provider. */
+    readonly raw: string;
+    /** The full underlying completion response. */
+    readonly response: IAiCompletionResponse;
+}
+/**
+ * Calls {@link AiAssist.callProviderCompletion}, then runs the response text
+ * through a tolerant JSON converter (default:
+ * {@link AiAssist.fencedStringifiedJson}) and the caller's
+ * `converter`/`validator`. Returns the validated value plus the raw text and
+ * underlying completion response for diagnostics.
+ *
+ * @remarks
+ * The default smart prompt hint asks the model to emit raw JSON. The read-side
+ * extractor still tolerates fences and prose, so models that ignore the hint
+ * are still handled.
+ *
+ * Either `converter` or `jsonConverter` must be provided; passing both lets
+ * `jsonConverter` win.
+ *
+ * @param params - Provider parameters plus JSON validation options.
+ * @returns The validated value, the raw text, and the underlying response.
+ * @public
+ */
+export declare function generateJsonCompletion<T>(params: IGenerateJsonCompletionParams<T>): Promise<Result<IGenerateJsonCompletionResult<T>>>;
+//# sourceMappingURL=jsonCompletion.d.ts.map

package/lib/packlets/ai-assist/jsonCompletion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonCompletion.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/jsonCompletion.ts"],"names":[],"mappings":"AAoBA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAQ,MAAM,EAAW,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAEtF,OAAO,EAA0B,KAAK,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAErF,OAAO,EAAE,KAAK,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAE2C,CAAC;AAEjF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,6BAA6B,CAAC,CAAC,CAAE,SAAQ,yBAAyB;IACjF;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAEjD;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IAEtC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,WAAW,6BAA6B,CAAC,CAAC;IAC9C,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,sDAAsD;IACtD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;CAC1C;AAUD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,MAAM,EAAE,6BAA6B,CAAC,CAAC,CAAC,GACvC,OAAO,CAAC,MAAM,CAAC,6BAA6B,CAAC,CAAC,CAAC,CAAC,CAAC,CAoBnD"}