@fgv/ts-extras 5.1.0-52 → 5.1.0-53

package/dist/ts-extras.d.ts

@@ -181,6 +181,8 @@ declare namespace AiAssist {
         supportsImageGeneration,
         resolveEmbeddingCapability,
         supportsEmbedding,
+        resolveStructuredOutputCapability,
+        supportsStructuredOutput,
         DEFAULT_MODEL_CAPABILITY_CONFIG,
         callProviderCompletion,
         callProxiedCompletion,
@@ -213,6 +215,14 @@ declare namespace AiAssist {
         modelSpecKey,
         modelSpec,
         resolveEffectiveTools,
+        ANTHROPIC_STRUCTURED_OUTPUT_TOOL_NAME,
+        AiStructuredOutputFormat,
+        IAiStructuredOutputCapability,
+        IJsonObjectStructuredOutputRequest,
+        ISchemaStructuredOutputRequest,
+        StructuredOutputEnforcement,
+        StructuredOutputFallback,
+        StructuredOutputRequest,
         classifyJsonParseFailure,
         extractJsonText,
         fencedStringifiedJson,
@@ -393,6 +403,20 @@ declare type AiServerToolType = 'web_search';
  */
 declare const aiServerToolType: Converter<AiServerToolType>;
 
+/**
+ * Wire format a provider uses to express a structured-output constraint.
+ *
+ * @remarks
+ * Four shapes, not one, and they differ in more than field names: the OpenAI
+ * pair carry the schema in the request body, Gemini carries it inside
+ * `generationConfig`, and Anthropic has no response-format field at all —
+ * its mechanism is forced tool use, which is why `'tool-forced'` is a distinct
+ * {@link AiAssist.StructuredOutputEnforcement} value rather than a spelling of
+ * `'schema'`.
+ * @public
+ */
+declare type AiStructuredOutputFormat = 'openai-json-schema' | 'openai-responses-format' | 'gemini-response-schema' | 'anthropic-tool-forced';
+
 /**
  * Thinking/reasoning mode support for a provider.
  * @public
@@ -550,6 +574,19 @@ declare const allProviderIds: ReadonlyArray<AiProviderId>;
  */
 declare const ALWAYS_STRIPPED_HEADERS: ReadonlyArray<string>;
 
+/**
+ * The name the Anthropic forced-tool path gives its synthetic tool.
+ *
+ * @remarks
+ * Anthropic has no `response_format`; its structured-output mechanism is forced
+ * tool use, so a tool must exist to be forced. The name is fgv-owned and never
+ * reaches the caller — the structured-output resolver re-serializes the tool's
+ * `input` back into `IAiCompletionResponse.content`, so a caller's converter sees
+ * a JSON string exactly as it does on every other provider.
+ * @public
+ */
+declare const ANTHROPIC_STRUCTURED_OUTPUT_TOOL_NAME: string;
+
 /**
  * Maps Anthropic effort level to the `thinking.budget_tokens` integer that the
  * Anthropic API requires when `thinking.type === 'enabled'`.
@@ -2596,11 +2633,29 @@ declare interface IAiCompletionResponse {
     readonly content: string;
     /** Whether the response was truncated due to token limits */
     readonly truncated: boolean;
+    /**
+     * Which structured-output constraint the provider was **asked** to apply.
+     *
+     * @remarks
+     * **Required, not optional, and that is the point.** An optional field would
+     * make absence three-ways ambiguous — no capability / not requested / a build
+     * predating the feature — and disambiguating exactly that is what this field
+     * exists for. `'none'` already expresses *"no constraint sent"*, so
+     * always-present costs nothing and removes the ambiguity by construction. The
+     * same remedy as `MemoryEmbedOutcome` in `@fgv/ts-agent-memory`, applied to the
+     * same defect.
+     *
+     * It reports what was *sent*, never whether **this** response conforms — that
+     * is the caller's converter's answer and re-deriving it here would be a second
+     * source of truth. See `StructuredOutputEnforcement` for the three-question
+     * split.
+     */
+    readonly structuredOutput: StructuredOutputEnforcement;
 }
 
 /**
  * Embedding capability for a model family within a provider. Used as an entry
- * in {@link IAiProviderDescriptor.embedding}.
+ * in `embedding`.
  *
  * @public
  */
@@ -2823,7 +2878,7 @@ declare interface IAiImageGenerationResponse {
 
 /**
  * Image-generation capability for a model family within a provider. Used as
- * an entry in {@link IAiProviderDescriptor.imageGeneration}.
+ * an entry in `imageGeneration`.
  *
  * @public
  */
@@ -3006,6 +3061,23 @@ declare interface IAiProviderDescriptor {
      * caller supplies the embedding model via `modelOverride`.
      */
     readonly embedding?: ReadonlyArray<IAiEmbeddingModelCapability>;
+    /**
+     * Per-model-family structured-output capability, longest-prefix matched against
+     * the **resolved** completion model id. Absent (or no matching entry) means the
+     * model can enforce nothing, and a request against it reports `'none'`.
+     *
+     * @remarks
+     * Same declaration idiom as `imageGeneration` and
+     * `embedding`, resolved through the same
+     * alias-first helper — a capability lookup on an unresolved alias is the defect
+     * `resolveImageCapability` once had, where a catch-all `modelPrefix: ''` turned
+     * an unknown alias into a confidently wrong answer.
+     *
+     * Note this declares which wire format a model *family* supports, not which
+     * OpenAI endpoint a given call will take — that also depends on whether the
+     * call carries server tools, so the dispatcher supplies it.
+     */
+    readonly structuredOutput?: ReadonlyArray<IAiStructuredOutputCapability>;
     /**
      * Concrete model ids (prefix-matched) that must be invoked via the OpenAI
      * Responses API rather than chat completions — e.g. `gpt-5.5-pro`. Non-OpenAI
@@ -3180,6 +3252,28 @@ declare interface IAiStreamToolUseStart {
     readonly callId?: string;
 }
 
+/**
+ * Structured-output capability for a model family within a provider. Used as an
+ * entry in `IAiProviderDescriptor.structuredOutput`.
+ *
+ * @remarks
+ * Deliberately thinner than its `imageGeneration` / `embedding` siblings: it
+ * carries no `supportsX` flags, because what each format can enforce is a
+ * property of the provider's **API surface** rather than of any one model, and a
+ * per-entry declaration of it could only ever disagree with the one in code.
+ * @public
+ */
+declare interface IAiStructuredOutputCapability {
+    /**
+     * Prefix matched against the resolved completion model id. The empty string is
+     * the catch-all and matches every model. When multiple rules' prefixes match a
+     * model id, the longest prefix wins; ties are broken by first-encountered.
+     */
+    readonly modelPrefix: string;
+    /** Wire format used to express the constraint for matching models. */
+    readonly format: AiStructuredOutputFormat;
+}
+
 /**
  * Behavior annotations for a client-defined tool.
  *
@@ -4543,6 +4637,22 @@ declare interface IImportSecretOptions extends IAddSecretOptions {
     readonly replace?: boolean;
 }
 
+/**
+ * Ask the provider for syntactically valid JSON of arbitrary shape.
+ *
+ * @remarks
+ * The weaker floor, and worth having on its own: the failure that motivated this
+ * surface (`Expected ',' or '}' after property value` — an unescaped quote closing
+ * a string early) is **syntactic**, so a JSON-mode guarantee removes it. Schema
+ * constraint is what additionally buys shape. It is also the only mode some
+ * model/provider pairs support.
+ * @public
+ */
+declare interface IJsonObjectStructuredOutputRequest {
+    readonly mode: 'json-object';
+    readonly onUnsupported?: StructuredOutputFallback;
+}
+
 /**
  * Key derivation parameters stored in encrypted files.
  * Discriminated union on `kdf` field: `'pbkdf2'` or `'argon2id'`.
@@ -5239,6 +5349,18 @@ declare interface IProviderCompletionParams extends IChatRequest {
      * Messages API requires the field, so it falls back to `DEFAULT_ANTHROPIC_MAX_TOKENS`.
      */
     readonly maxTokens?: number;
+    /**
+     * Ask the provider to constrain its output — to a schema, or to syntactically
+     * valid JSON of arbitrary shape.
+     *
+     * @remarks
+     * **The caller supplies intent; the response reports outcome.** A caller cannot
+     * know up front which concrete model will serve the request (a `tier` request
+     * cascades, and aliases resolve at call time), so it never has to: whatever was
+     * actually enforced comes back on
+     * `IAiCompletionResponse.structuredOutput`.
+     */
+    readonly structuredOutput?: StructuredOutputRequest;
 }
 
 /**
@@ -5820,6 +5942,25 @@ declare interface ISaferFetchResponseHead {
     readonly contentLength?: number;
 }
 
+/**
+ * Ask the provider for JSON constrained to a schema.
+ * @public
+ */
+declare interface ISchemaStructuredOutputRequest {
+    readonly mode: 'schema';
+    /**
+     * The schema to constrain generation to — **the same object you validate the
+     * reply with**, so the wire schema and the check cannot drift.
+     *
+     * @remarks
+     * Author it with `JsonSchema.object({...})` from `@fgv/ts-json-base`. This is
+     * the property `@fgv/ts-extras-ollama`'s `chatStructured` already has; this
+     * surface is its cloud sibling.
+     */
+    readonly schema: JsonSchema.ISchemaValidator<unknown>;
+    readonly onUnsupported?: StructuredOutputFallback;
+}
+
 /**
  * Checks if a JSON object appears to be an encrypted file.
  * Uses the format field as a discriminator.
@@ -7897,6 +8038,21 @@ declare function resolveModelAlias(descriptor: IAiProviderDescriptor, model: str
  */
 declare function resolveProviderModel(descriptor: IAiProviderDescriptor, modelOverride: ModelSpec | undefined, context?: ModelSpecKey): Result<string>;
 
+/**
+ * The structured-output capability for `modelId` under `descriptor`, or
+ * `undefined` when the model can enforce nothing.
+ *
+ * @remarks
+ * Alias-first, exactly like its `imageGeneration` / `embedding` siblings — an
+ * unresolved alias returns `undefined` rather than prefix-matching a catch-all
+ * `modelPrefix: ''`, which is the defect this helper was written to prevent.
+ *
+ * @param descriptor - The provider descriptor.
+ * @param modelId - A concrete model id or an `@provider:role` alias.
+ * @public
+ */
+declare function resolveStructuredOutputCapability(descriptor: IAiProviderDescriptor, modelId: string): IAiStructuredOutputCapability | undefined;
+
 /**
  * Statuses whose `Retry-After` header is honored.
  *
@@ -8163,6 +8319,71 @@ declare const SMART_JSON_PROMPT_HINT: string;
  */
 declare function spkiToRawX25519(spki: Uint8Array): Result<Uint8Array>;
 
+/**
+ * Which constraint the provider was **asked** to apply to this response.
+ *
+ * @remarks
+ * Three questions hide inside *"did it honour my schema"*, and they have different
+ * owners:
+ *
+ * | question | answerable by |
+ * |---|---|
+ * | did we send a constraint? | this client, at request-build time |
+ * | which constraint did the provider apply? | this client, from the resolved model's capability |
+ * | does *this response* conform to my shape? | the caller's converter, and nothing else |
+ *
+ * This type answers the first two and deliberately not the third. Reporting
+ * conformance would mean re-validating against the caller's own schema to
+ * re-derive an answer the caller already holds.
+ *
+ * - `'none'` — nothing was sent; the resolved model declares no capability.
+ * - `'json-mode'` — syntactically valid JSON is guaranteed; the shape is not.
+ * - `'schema'` — generation was constrained to the supplied schema.
+ * - `'tool-forced'` — Anthropic-style forced tool use; the shape comes from the
+ *   forced tool's input schema, and `content` is the re-serialized tool input.
+ * @public
+ */
+declare type StructuredOutputEnforcement = 'none' | 'json-mode' | 'schema' | 'tool-forced';
+
+/**
+ * What to do when the resolved model cannot apply the requested constraint.
+ *
+ * @remarks
+ * `'degrade'` is the default, and it is only safe **because
+ * `IAiCompletionResponse.structuredOutput` is required** rather than
+ * optional. Degrade-and-tell-me is safe; degrade-silently is the failure this
+ * whole surface exists to remove — so the two decisions are one decision, not
+ * two independent ones.
+ *
+ * Reach for `'fail'` when the output is persisted or put on a wire, where an
+ * unconstrained generation that happens to parse is worse than an error because
+ * it is wrong quietly. Leave it at `'degrade'` on paths that are *designed* to
+ * degrade — an extractor that may return nothing, a segmenter that floors to a
+ * mechanical chunker — where a hard failure would make this library less safe
+ * than the code it replaces.
+ * @public
+ */
+declare type StructuredOutputFallback = 'degrade' | 'fail';
+
+/**
+ * A caller's structured-output intent.
+ *
+ * @remarks
+ * A discriminated union rather than an optional `schema` whose absence means
+ * *"json-object please"* — an absence that means something is the shape this repo
+ * has been burned by (see `MemoryEmbedOutcome` in `@fgv/ts-agent-memory`, which
+ * exists because a three-ways-ambiguous absence could not be read).
+ *
+ * **The caller supplies intent; the response reports outcome.** A request never
+ * needs to know whether the constraint will be honoured, because
+ * `resolveProviderModel` resolves aliases and tiers at *call* time — a `tier`
+ * request can cascade — so the concrete model that will serve a request is not
+ * knowable to the caller up front. Requiring it to know would be unsound, which
+ * is why the report rides on the response rather than being a lookup.
+ * @public
+ */
+declare type StructuredOutputRequest = ISchemaStructuredOutputRequest | IJsonObjectStructuredOutputRequest;
+
 /**
  * URL schemes this primitive will ever request.
  *
@@ -8195,6 +8416,12 @@ declare function supportsEmbedding(descriptor: IAiProviderDescriptor): boolean;
  */
 declare function supportsImageGeneration(descriptor: IAiProviderDescriptor): boolean;
 
+/**
+ * Whether `descriptor` declares any structured-output capability at all.
+ * @public
+ */
+declare function supportsStructuredOutput(descriptor: IAiProviderDescriptor): boolean;
+
 /**
  * Helper function to create a `StringConverter` which converts
  * `unknown` to `string`, applying template conversions supplied at construction time or at

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

@@ -1,5 +1,6 @@
 import { type Logging, Result } from '@fgv/ts-utils';
 import { type AiServerToolConfig, type IAiCompletionResponse, type IAiProviderDescriptor, type IChatRequest, type IThinkingConfig, type ModelSpec } from './model';
+import type { StructuredOutputRequest } from './structuredOutputTypes';
 /**
  * Parameters for a provider completion request. Carries the unified
  * {@link AiAssist.IChatRequest} shape (`system?` + ordered `messages`, last =
@@ -52,6 +53,18 @@ export interface IProviderCompletionParams extends IChatRequest {
      * Messages API requires the field, so it falls back to `DEFAULT_ANTHROPIC_MAX_TOKENS`.
      */
     readonly maxTokens?: number;
+    /**
+     * Ask the provider to constrain its output — to a schema, or to syntactically
+     * valid JSON of arbitrary shape.
+     *
+     * @remarks
+     * **The caller supplies intent; the response reports outcome.** A caller cannot
+     * know up front which concrete model will serve the request (a `tier` request
+     * cascades, and aliases resolve at call time), so it never has to: whatever was
+     * actually enforced comes back on
+     * `IAiCompletionResponse.structuredOutput`.
+     */
+    readonly structuredOutput?: StructuredOutputRequest;
 }
 /**
  * Calls the appropriate chat completion API for a given provider. Routes by

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

@@ -1 +1 @@
-{"version":3,"file":"completionClient.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/completionClient.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAQ,KAAK,OAAO,EAAE,MAAM,EAAuC,MAAM,eAAe,CAAC;AAEhG,OAAO,EAEL,KAAK,kBAAkB,EAEvB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAE1B,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,SAAS,EAMf,MAAM,SAAS,CAAC;AA8BjB;;;;;GAKG;AACH,MAAM,WAAW,yBAA0B,SAAQ,YAAY;IAC7D,8BAA8B;IAC9B,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;IAC3C,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,qGAAqG;IACrG,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACxC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC;IAClC,uGAAuG;IACvG,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IACnD,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;IACpC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AA0aD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC,CAqIxC;AAMD;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC,CAwExC"}
+{"version":3,"file":"completionClient.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/completionClient.ts"],"names":[],"mappings":"AA8BA,OAAO,EAGL,KAAK,OAAO,EACZ,MAAM,EAIP,MAAM,eAAe,CAAC;AAEvB,OAAO,EAEL,KAAK,kBAAkB,EAEvB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAE1B,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,SAAS,EAMf,MAAM,SAAS,CAAC;AAiCjB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAMvE;;;;;GAKG;AACH,MAAM,WAAW,yBAA0B,SAAQ,YAAY;IAC7D,8BAA8B;IAC9B,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;IAC3C,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,qGAAqG;IACrG,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACxC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC;IAClC,uGAAuG;IACvG,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IACnD,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;IACpC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;CACrD;AAigBD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC,CAiLxC;AAMD;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC,CAiHxC"}

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

@@ -28,6 +28,8 @@ const chatRequestBuilders_1 = require("./chatRequestBuilders");
 const endpoint_1 = require("./endpoint");
 const http_1 = require("./http");
 const toolFormats_1 = require("./toolFormats");
+const structuredOutput_1 = require("./structuredOutput");
+const registry_1 = require("./registry");
 const openAiMessage = ts_utils_1.Validators.object({
     content: ts_utils_1.Validators.string
 });
@@ -73,7 +75,7 @@ const geminiResponse = ts_utils_1.Validators.object({
  * Works for xAI Grok, OpenAI, Groq, and Mistral.
  * @internal
  */
-async function callOpenAiCompletion(config, prompt, head, temperature, logger, signal, resolvedThinking, maxTokens, useMaxCompletionTokensField = false) {
+async function callOpenAiCompletion(config, prompt, head, temperature, logger, signal, resolvedThinking, maxTokens, useMaxCompletionTokensField = false, structured = structuredOutput_1.NO_STRUCTURED_OUTPUT) {
     var _a;
     const url = `${config.baseUrl}/chat/completions`;
     const messages = (0, chatRequestBuilders_1.buildMessages)(prompt.system, (0, chatRequestBuilders_1.buildOpenAiChatUserContent)(prompt), {
@@ -85,6 +87,7 @@ async function callOpenAiCompletion(config, prompt, head, temperature, logger, s
     if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.otherParams) !== undefined) {
         Object.assign(body, resolvedThinking.otherParams);
     }
+    Object.assign(body, structured.wire);
     const headers = (0, endpoint_1.bearerAuthHeader)(config.apiKey);
     /* c8 ignore next 1 - optional logger */
     logger === null || logger === void 0 ? void 0 : logger.info(`OpenAI completion: model=${config.model}`);
@@ -99,7 +102,8 @@ async function callOpenAiCompletion(config, prompt, head, temperature, logger, s
         const choice = response.choices[0];
         return (0, ts_utils_1.succeed)({
             content: choice.message.content,
-            truncated: choice.finish_reason === 'length'
+            truncated: choice.finish_reason === 'length',
+            structuredOutput: structured.enforcement
         });
     });
 }
@@ -127,7 +131,7 @@ function extractResponsesApiText(output) {
  * Used when tools are configured for an openai-format provider.
  * @internal
  */
-async function callOpenAiResponsesCompletion(config, prompt, tools = [], head, temperature, logger, signal, resolvedThinking, maxTokens) {
+async function callOpenAiResponsesCompletion(config, prompt, tools = [], head, temperature, logger, signal, resolvedThinking, maxTokens, structured = structuredOutput_1.NO_STRUCTURED_OUTPUT) {
     var _a;
     const url = `${config.baseUrl}/responses`;
     const input = (0, chatRequestBuilders_1.buildMessages)(prompt.system, (0, chatRequestBuilders_1.buildOpenAiResponsesUserContent)(prompt), {
@@ -142,6 +146,7 @@ async function callOpenAiResponsesCompletion(config, prompt, tools = [], head, t
     if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.otherParams) !== undefined) {
         Object.assign(body, resolvedThinking.otherParams);
     }
+    Object.assign(body, structured.wire);
     const headers = (0, endpoint_1.bearerAuthHeader)(config.apiKey);
     /* c8 ignore next 1 - optional logger */
     logger === null || logger === void 0 ? void 0 : logger.info(`OpenAI Responses API: model=${config.model}, tools=${tools.map((t) => t.type).join(',')}`);
@@ -155,7 +160,8 @@ async function callOpenAiResponsesCompletion(config, prompt, tools = [], head, t
         .onSuccess((response) => {
         return extractResponsesApiText(response.output).onSuccess((text) => (0, ts_utils_1.succeed)({
             content: text,
-            truncated: response.status === 'incomplete'
+            truncated: response.status === 'incomplete',
+            structuredOutput: structured.enforcement
         }));
     });
 }
@@ -184,8 +190,45 @@ function extractAnthropicText(content) {
     }
     return (0, ts_utils_1.succeed)(textParts.join(''));
 }
+/**
+ * Extracts the forced structured-output tool's input from Anthropic response
+ * content blocks and re-serializes it.
+ *
+ * @remarks
+ * Under `'tool-forced'` enforcement the model's answer arrives as a `tool_use`
+ * block's `input` — a parsed object — rather than as text. Re-serializing it here
+ * keeps `IAiCompletionResponse.content` a JSON **string** on every provider, so a
+ * caller's converter is written once and does not branch on which enforcement it
+ * got. A useful side effect: the string is produced by `JSON.stringify` rather
+ * than by the model, so under this enforcement it is syntactically valid by
+ * construction.
+ * @internal
+ */
+function extractAnthropicStructuredOutput(content) {
+    for (const block of content) {
+        if (typeof block === 'object' && block !== null && 'type' in block) {
+            const typed = block;
+            if (typed.type === 'tool_use' && typed.name === structuredOutput_1.ANTHROPIC_STRUCTURED_OUTPUT_TOOL_NAME) {
+                // `JSON.stringify` returns `undefined` — not a string, and not a throw —
+                // for `undefined` and for a function or symbol. `captureResult` would wrap
+                // that as a Success, putting `undefined` behind a `content: string`
+                // contract with nothing to catch it downstream. A `tool_use` block with no
+                // `input` is exactly that case.
+                return (0, ts_utils_1.captureResult)(() => JSON.stringify(typed.input))
+                    .withErrorFormat((msg) => `Anthropic API response: structured output could not be serialized: ${msg}`)
+                    .onSuccess((json) => typeof json === 'string'
+                    ? (0, ts_utils_1.succeed)(json)
+                    : (0, ts_utils_1.fail)(`Anthropic API response: forced tool '${structuredOutput_1.ANTHROPIC_STRUCTURED_OUTPUT_TOOL_NAME}' returned no serializable input`));
+            }
+        }
+    }
+    // Loud rather than a silent fall back to text: we forced the tool, so its
+    // absence means the request did not do what the response is about to claim it
+    // did — and `structuredOutput: 'tool-forced'` would then be a lie.
+    return (0, ts_utils_1.fail)(`Anthropic API response: structured output was forced but no '${structuredOutput_1.ANTHROPIC_STRUCTURED_OUTPUT_TOOL_NAME}' tool_use block was returned`);
+}
 /** Calls the Anthropic Messages API with optional tool support. @internal */
-async function callAnthropicCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking, useAdaptiveThinking = false, maxTokens) {
+async function callAnthropicCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking, useAdaptiveThinking = false, maxTokens, structured = structuredOutput_1.NO_STRUCTURED_OUTPUT) {
     const url = `${config.baseUrl}/messages`;
     const messages = (0, chatRequestBuilders_1.buildAnthropicMessages)(prompt, { head });
     const body = Object.assign({ model: config.model, system: prompt.system, messages, 
@@ -207,6 +250,22 @@ async function callAnthropicCompletion(config, prompt, head, temperature, logger
     if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.otherParams) !== undefined) {
         Object.assign(body, resolvedThinking.otherParams);
     }
+    // The structured-output wire carries `tools` + `tool_choice` of its own, so the
+    // server-tool assignment below would clobber it. `resolveStructuredOutput`
+    // refuses that combination up front, which is what makes the two mutually
+    // exclusive — but that is an invariant held in a DIFFERENT FILE, and a future
+    // second Anthropic capability entry (or a relaxed conflict guard) would
+    // reintroduce silent clobbering with nothing failing at this line. So assert it
+    // here rather than trusting a comment across a file boundary.
+    // Unreachable through the public API — resolveStructuredOutput refuses this
+    // combination before dispatch — and unreachable BY DESIGN: it cannot be
+    // exercised without first breaking the very thing it guards against.
+    /* c8 ignore next 6 - defensive: internal consistency check, see above */
+    if (structured.enforcement === 'tool-forced' && tools !== undefined && tools.length > 0) {
+        return (0, ts_utils_1.fail)(`Anthropic completion: structured output and server-side tools both claim the tools channel; ` +
+            `this combination must be refused before reaching the adapter`);
+    }
+    Object.assign(body, structured.wire);
     if (tools && tools.length > 0) {
         body.tools = (0, toolFormats_1.toAnthropicTools)(tools);
         /* c8 ignore next 3 - optional logger diagnostic output */
@@ -229,9 +288,13 @@ async function callAnthropicCompletion(config, prompt, head, temperature, logger
     if (typeof stopReason !== 'string') {
         return (0, ts_utils_1.fail)('Anthropic API response: stop_reason is missing or not a string');
     }
-    return extractAnthropicText(rawContent).onSuccess((text) => (0, ts_utils_1.succeed)({
+    const extracted = structured.enforcement === 'tool-forced'
+        ? extractAnthropicStructuredOutput(rawContent)
+        : extractAnthropicText(rawContent);
+    return extracted.onSuccess((text) => (0, ts_utils_1.succeed)({
         content: text,
-        truncated: stopReason === 'max_tokens'
+        truncated: stopReason === 'max_tokens',
+        structuredOutput: structured.enforcement
     }));
 }
 // ============================================================================
@@ -242,7 +305,7 @@ async function callAnthropicCompletion(config, prompt, head, temperature, logger
  * When tools are configured, includes Google Search grounding.
  * @internal
  */
-async function callGeminiCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking, maxTokens) {
+async function callGeminiCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking, maxTokens, structured = structuredOutput_1.NO_STRUCTURED_OUTPUT) {
     const url = `${config.baseUrl}/models/${config.model}:generateContent`;
     const contents = (0, chatRequestBuilders_1.buildGeminiContents)(prompt, { head });
     // Temperature is sent only when explicitly provided; otherwise Gemini's default applies.
@@ -259,6 +322,8 @@ async function callGeminiCompletion(config, prompt, head, temperature, logger, t
     if ((resolvedThinking === null || resolvedThinking === void 0 ? void 0 : resolvedThinking.otherParams) !== undefined) {
         Object.assign(generationConfig, resolvedThinking.otherParams);
     }
+    // Gemini nests the constraint INSIDE generationConfig, not on the body.
+    Object.assign(generationConfig, structured.wire);
     const body = {
         systemInstruction: { parts: [{ text: prompt.system }] },
         contents,
@@ -284,8 +349,15 @@ async function callGeminiCompletion(config, prompt, head, temperature, logger, t
         .onSuccess((response) => {
         const candidate = response.candidates[0];
         return (0, ts_utils_1.succeed)({
-            content: candidate.content.parts[0].text,
-            truncated: candidate.finishReason === 'MAX_TOKENS'
+            // ALL parts, not `parts[0]`. Gemini may split one reply across several
+            // text parts, and reading only the first silently discards the rest —
+            // yielding a truncated document that often still parses, which is the
+            // worst way to be wrong. The streaming adapter has always concatenated
+            // (`fullText += part.text`); this path did not, so the same response gave
+            // different text depending on which one you called.
+            content: candidate.content.parts.map((part) => part.text).join(''),
+            truncated: candidate.finishReason === 'MAX_TOKENS',
+            structuredOutput: structured.enforcement
         });
     });
 }
@@ -299,7 +371,7 @@ async function callGeminiCompletion(config, prompt, head, temperature, logger, t
  * @public
  */
 async function callProviderCompletion(params) {
-    const { descriptor, apiKey, system, messages, temperature, modelOverride, tier, logger, tools, signal, endpoint, thinking, maxTokens } = params;
+    const { descriptor, apiKey, system, messages, temperature, modelOverride, tier, logger, tools, signal, endpoint, thinking, maxTokens, structuredOutput } = params;
     const splitResult = (0, chatRequestBuilders_1.splitChatRequest)(system, messages);
     if (splitResult.isFailure()) {
         return (0, ts_utils_1.fail)(splitResult.message);
@@ -337,6 +409,32 @@ async function callProviderCompletion(params) {
             }
         }
     }
+    // Resolved against the CONCRETE model, after resolveProviderModel — passing an
+    // alias here is the defect resolveImageCapability once had.
+    // The OpenAI route depends on tools AND the model, so it is computed here (once,
+    // beside the switch that uses it) and handed to the resolver — a capability keyed
+    // on the model alone cannot know which of the two OpenAI wire shapes applies.
+    const usesResponsesApi = descriptor.apiFormat === 'openai' && (hasTools || (0, model_1.isResponsesOnlyModel)(descriptor, model));
+    const structuredResult = (0, structuredOutput_1.resolveStructuredOutput)(descriptor, model, structuredOutput, tools, usesResponsesApi, registry_1.resolveStructuredOutputCapability);
+    if (structuredResult.isFailure()) {
+        return (0, ts_utils_1.fail)(structuredResult.message);
+    }
+    const resolvedStructured = structuredResult.value;
+    // OpenAI rejects `response_format: { type: 'json_object' }` with a 400 unless the
+    // conversation mentions JSON somewhere — a documented API rule, and one a caller
+    // has no way to discover from a schema-mode request that worked. Pre-empted with a
+    // named failure before the wire call, the same treatment the Gemini
+    // grounding-plus-function-calling conflict already gets. `generateJsonCompletion`
+    // satisfies it for free via its prompt hint; a direct caller may not.
+    if (resolvedStructured.enforcement === 'json-mode' && descriptor.apiFormat === 'openai') {
+        const mentionsJson = (system !== null && system !== void 0 ? system : '').toLowerCase().includes('json') ||
+            messages.some((m) => m.content.toLowerCase().includes('json'));
+        if (!mentionsJson) {
+            return (0, ts_utils_1.fail)(`provider '${descriptor.id}': json-object structured output requires the word 'json' to ` +
+                `appear in the system prompt or a message — OpenAI rejects the request otherwise. Mention ` +
+                `it, or use structuredOutput: { mode: 'schema', schema } which carries no such rule`);
+        }
+    }
     const config = {
         baseUrl: baseUrlResult.value,
         apiKey,
@@ -353,14 +451,14 @@ async function callProviderCompletion(params) {
         case 'openai':
             // Responses-API-only models (e.g. gpt-5.5-pro) 400 on /chat/completions, so they route
             // to the Responses path even with no tools requested — same path the tools case uses.
-            if (hasTools || (0, model_1.isResponsesOnlyModel)(descriptor, config.model)) {
-                return callOpenAiResponsesCompletion(config, prompt, tools, head, temperature, logger, signal, resolvedThinking, maxTokens);
+            if (usesResponsesApi) {
+                return callOpenAiResponsesCompletion(config, prompt, tools, head, temperature, logger, signal, resolvedThinking, maxTokens, resolvedStructured);
             }
-            return callOpenAiCompletion(config, prompt, head, temperature, logger, signal, resolvedThinking, maxTokens, (0, model_1.usesMaxCompletionTokensField)(descriptor));
+            return callOpenAiCompletion(config, prompt, head, temperature, logger, signal, resolvedThinking, maxTokens, (0, model_1.usesMaxCompletionTokensField)(descriptor), resolvedStructured);
         case 'anthropic':
-            return callAnthropicCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking, (0, model_1.isAdaptiveThinkingModel)(descriptor, config.model), maxTokens);
+            return callAnthropicCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking, (0, model_1.isAdaptiveThinkingModel)(descriptor, config.model), maxTokens, resolvedStructured);
         case 'gemini':
-            return callGeminiCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking, maxTokens);
+            return callGeminiCompletion(config, prompt, head, temperature, logger, tools, signal, resolvedThinking, maxTokens, resolvedStructured);
         /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
         default: {
             const _exhaustive = descriptor.apiFormat;
@@ -382,7 +480,7 @@ async function callProviderCompletion(params) {
  * @public
  */
 async function callProxiedCompletion(proxyUrl, params) {
-    const { descriptor, apiKey, system, messages, temperature, modelOverride, logger, tools, signal, thinking, maxTokens } = params;
+    const { descriptor, apiKey, system, messages, temperature, modelOverride, logger, tools, signal, thinking, maxTokens, structuredOutput } = params;
     const splitResult = (0, chatRequestBuilders_1.splitChatRequest)(system, messages);
     if (splitResult.isFailure()) {
         return (0, ts_utils_1.fail)(splitResult.message);
@@ -417,6 +515,18 @@ async function callProxiedCompletion(proxyUrl, params) {
     if (maxTokens !== undefined) {
         body.maxTokens = maxTokens;
     }
+    if (structuredOutput !== undefined) {
+        // The schema travels as its draft-07 wire form, not as the validator object —
+        // an `ISchemaValidator` is not JSON-serializable. A proxy reconstitutes it with
+        // `JsonSchema.fromJson(raw)` before calling `callProviderCompletion`.
+        body.structuredOutput =
+            structuredOutput.mode === 'schema'
+                ? Object.assign({ mode: 'schema', schema: structuredOutput.schema.toJson() }, (structuredOutput.onUnsupported !== undefined
+                    ? { onUnsupported: structuredOutput.onUnsupported }
+                    : {})) : Object.assign({ mode: 'json-object' }, (structuredOutput.onUnsupported !== undefined
+                ? { onUnsupported: structuredOutput.onUnsupported }
+                : {}));
+    }
     /* c8 ignore next 1 - optional logger */
     logger === null || logger === void 0 ? void 0 : logger.info(`AI proxy request: provider=${descriptor.id}, proxy=${proxyUrl}`);
     const url = `${proxyUrl}/api/ai/completion`;
@@ -431,9 +541,27 @@ async function callProxiedCompletion(proxyUrl, params) {
     if (typeof response.content !== 'string') {
         return (0, ts_utils_1.fail)('proxy returned invalid response: missing content');
     }
+    // A caller who asked for nothing gets `'none'` without the proxy having to say
+    // so. A caller who DID ask gets a loud failure when the proxy cannot report,
+    // rather than a response claiming an enforcement nobody verified — a proxy
+    // predating this feature drops the constraint silently, which is the exact
+    // failure this surface exists to remove.
+    if (structuredOutput === undefined) {
+        return (0, ts_utils_1.succeed)({
+            content: response.content,
+            truncated: response.truncated === true,
+            structuredOutput: 'none'
+        });
+    }
+    if (!(0, structuredOutput_1.isStructuredOutputEnforcement)(response.structuredOutput)) {
+        return (0, ts_utils_1.fail)(`proxy did not report which structured-output constraint it applied ` +
+            `(got ${JSON.stringify(response.structuredOutput)}); it may predate the feature and have ` +
+            `dropped the request silently`);
+    }
     return (0, ts_utils_1.succeed)({
         content: response.content,
-        truncated: response.truncated === true
+        truncated: response.truncated === true,
+        structuredOutput: response.structuredOutput
     });
 }
 //# sourceMappingURL=completionClient.js.map