@juspay/neurolink 9.69.3 → 9.70.1

package/dist/core/modules/GenerationHandler.js

@@ -21,6 +21,8 @@ import { calculateCost } from "../../utils/pricing.js";
 import { withProviderRetry } from "../../utils/providerRetry.js";
 import { calculateCacheSavingsPercent, extractCacheCreationTokens, extractCacheReadTokens, extractTokenUsage, } from "../../utils/tokenUtils.js";
 import { DEFAULT_MAX_STEPS } from "../constants.js";
+import { isToolsSchemaConflictError, isToolsSchemaExclusionInForce, } from "./structuredOutputPolicy.js";
+import { coerceJsonToSchema } from "../../utils/json/coerce.js";
 import { NoObjectGeneratedError } from "../../utils/generationErrors.js";
 import { Output, stepCountIs } from "../../utils/tool.js";
 import { generateText } from "../../utils/generation.js";
@@ -76,8 +78,10 @@ export class GenerationHandler {
             (!!options.schema ||
                 options.output?.format === "json" ||
                 options.output?.format === "structured");
+        // The tools↔schema conflict is a Gemini-only API limitation. Vertex+Claude
+        // supports both simultaneously, so only exclude for actual Gemini models.
         const useStructuredOutput = wantsStructuredOutput &&
-            !(isGoogleProvider && shouldUseTools && Object.keys(tools).length > 0);
+            !isToolsSchemaExclusionInForce(this.providerName, this.modelName, shouldUseTools, Object.keys(tools).length);
         // Annotate the last tool with cache_control so the full tool-definition
         // block becomes a cache breakpoint for Anthropic-family providers.
         // Non-Anthropic providers harmlessly ignore unknown providerOptions.
@@ -279,20 +283,30 @@ export class GenerationHandler {
                 return result;
             }
             catch (error) {
-                // If NoObjectGeneratedError is thrown when using schema + tools together,
-                // fall back to generating without experimental_output and extract JSON manually
-                if (error instanceof NoObjectGeneratedError && useStructuredOutput) {
+                // Fall back to text-mode (no experimental_output) when structured
+                // output + tools failed, in two cases:
+                //   1. NoObjectGeneratedError — the SDK couldn't coerce the object.
+                //   2. The provider rejected json-mode-with-tools outright (e.g. Groq:
+                //      "json mode cannot be combined with tool/function calling").
+                // In both cases we retry without structured output and let
+                // formatEnhancedResult coerce the text response into valid JSON.
+                const isStructuredOutputConflict = useStructuredOutput &&
+                    (error instanceof NoObjectGeneratedError ||
+                        isToolsSchemaConflictError(error));
+                if (isStructuredOutputConflict) {
                     span.setAttribute("neurolink.has_fallback", true);
                     // NLK-GAP-007: Record initial failure event before fallback retry
                     span.addEvent("retry.initial_failure", {
-                        "error.message": error.message,
+                        "error.message": error instanceof Error ? error.message : String(error),
                         "retry.attempt": 1,
-                        "retry.reason": "NoObjectGeneratedError_structured_output_fallback",
+                        "retry.reason": error instanceof NoObjectGeneratedError
+                            ? "NoObjectGeneratedError_structured_output_fallback"
+                            : "tools_schema_conflict_structured_output_fallback",
                     });
-                    logger.debug("[GenerationHandler] NoObjectGeneratedError caught - falling back to manual JSON extraction", {
+                    logger.debug("[GenerationHandler] structured-output conflict caught - falling back to manual JSON extraction", {
                         provider: this.providerName,
                         model: this.modelName,
-                        error: error.message,
+                        error: error instanceof Error ? error.message : String(error),
                     });
                     // Retry without experimental_output - the formatEnhancedResult method
                     // will extract JSON from the text response
@@ -460,41 +474,76 @@ export class GenerationHandler {
             options.output?.format === "json" ||
             options.output?.format === "structured";
         let content;
+        let structuredData;
+        let jsonRepaired = false;
+        let jsonTruncated = false;
+        // Strip an outer ```json fence and coerce raw model text into canonical
+        // JSON. Object/array roots are recovered via balanced-scan + jsonrepair;
+        // scalar JSON roots (string/number/bool) via plain JSON.parse. When
+        // nothing JSON-shaped is recoverable, the raw text is returned unchanged,
+        // structuredData stays unset, and a WARN makes the broken case observable.
+        const coerceTextMode = (rawText) => {
+            const strippedText = rawText
+                .replace(/^```(?:json)?\s*\n?/i, "")
+                .replace(/\n?```\s*$/i, "")
+                .trim();
+            const coerced = coerceJsonToSchema(strippedText, options.schema);
+            if (coerced) {
+                structuredData = coerced.structuredData;
+                if (coerced.repaired) {
+                    jsonRepaired = true;
+                }
+                if (coerced.truncated) {
+                    jsonTruncated = true;
+                }
+                return coerced.content;
+            }
+            try {
+                const scalar = JSON.parse(strippedText);
+                if (scalar !== null && scalar !== undefined) {
+                    structuredData = scalar;
+                    return strippedText;
+                }
+            }
+            catch {
+                // not JSON at all — fall through to raw text + WARN
+            }
+            logger.warn("[GenerationHandler] schema requested but no JSON could be recovered from model text; returning raw text", { provider: this.providerName, model: this.modelName });
+            return strippedText;
+        };
         if (useStructuredOutput) {
             try {
                 const experimentalOutput = generateResult.experimental_output;
                 if (experimentalOutput !== undefined) {
+                    // AI-SDK already parsed + schema-validated the object. Expose it
+                    // directly and serialise canonically — no hand-parsing needed.
+                    structuredData = experimentalOutput;
                     content = JSON.stringify(experimentalOutput);
                 }
                 else {
-                    // Fall back to text parsing
-                    const rawText = generateResult.text || "";
-                    const strippedText = rawText
-                        .replace(/^```(?:json)?\s*\n?/i, "")
-                        .replace(/\n?```\s*$/i, "")
-                        .trim();
-                    content = strippedText;
+                    content = coerceTextMode(generateResult.text || "");
                 }
             }
             catch (outputError) {
-                // experimental_output is a getter that can throw NoObjectGeneratedError
-                // Fall back to text parsing when structured output fails
+                // experimental_output is a getter that can throw NoObjectGeneratedError.
                 logger.debug("[GenerationHandler] experimental_output threw, falling back to text parsing", {
                     error: outputError instanceof Error
                         ? outputError.message
                         : String(outputError),
                 });
-                const rawText = generateResult.text || "";
-                const strippedText = rawText
-                    .replace(/^```(?:json)?\s*\n?/i, "")
-                    .replace(/\n?```\s*$/i, "")
-                    .trim();
-                content = strippedText;
+                content = coerceTextMode(generateResult.text || "");
             }
         }
         else {
             content = generateResult.text;
         }
+        // Tie the coercion repair to the provider's truncation signal: if the
+        // response stopped on the token cap, treat the structured output as
+        // truncated regardless of which coerce candidate won, and warn.
+        if (useStructuredOutput && generateResult.finishReason === "length") {
+            jsonTruncated = true;
+            logger.warn("[GenerationHandler] Structured output truncated by token cap (finishReason=length); increase maxTokens", { provider: this.providerName, model: this.modelName });
+        }
         // Extract usage with support for different formats and reasoning tokens
         // Note: The AI SDK bundles thinking tokens into promptTokens for Google models.
         // Separate reasoningTokens tracking will work when/if the AI SDK adds support.
@@ -537,8 +586,11 @@ export class GenerationHandler {
         const reasoningTokens = usage.reasoning ?? undefined;
         return {
             content,
+            structuredData,
             usage,
             finishReason: generateResult.finishReason,
+            jsonRepaired: jsonRepaired || undefined,
+            jsonTruncated: jsonTruncated || undefined,
             provider: this.providerName,
             model: this.modelName,
             reasoning,

package/dist/core/modules/structuredOutputPolicy.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Policy for when AI-SDK structured output (experimental_output) must be
+ * disabled because the provider cannot combine tool calls with JSON-schema
+ * enforcement.
+ *
+ * This is a GEMINI-ONLY API limitation. Anthropic Claude — including when
+ * hosted on Vertex (modelName starts with "claude-") — supports tools and
+ * structured output simultaneously, so it must NOT be excluded. A gate keyed on
+ * "any Vertex model" wrongly disables structured output for Vertex+Claude (the
+ * primary production config) and forces fragile hand-parsed JSON.
+ */
+/** True when the provider+model is a Gemini model (the only family with the tools↔schema conflict). */
+export declare function isGeminiProvider(providerName: string, modelName: string | undefined): boolean;
+/**
+ * True when structured output must be disabled for this call because tools are
+ * active on a Gemini provider. Mirrors the AI-SDK constraint exactly.
+ */
+export declare function isToolsSchemaExclusionInForce(providerName: string, modelName: string | undefined, shouldUseTools: boolean, toolCount: number): boolean;
+/**
+ * True when a provider error indicates the request was rejected because JSON /
+ * structured output and tool-calling cannot be combined for that provider
+ * (e.g. Groq: "json mode cannot be combined with tool/function calling").
+ *
+ * This is the runtime, provider-agnostic complement to the static Gemini gate:
+ * any provider with the same limitation can be detected from its error message
+ * and retried without structured output instead of failing the call.
+ */
+export declare function isToolsSchemaConflictError(error: unknown): boolean;

package/dist/core/modules/structuredOutputPolicy.js

@@ -0,0 +1,50 @@
+/**
+ * Policy for when AI-SDK structured output (experimental_output) must be
+ * disabled because the provider cannot combine tool calls with JSON-schema
+ * enforcement.
+ *
+ * This is a GEMINI-ONLY API limitation. Anthropic Claude — including when
+ * hosted on Vertex (modelName starts with "claude-") — supports tools and
+ * structured output simultaneously, so it must NOT be excluded. A gate keyed on
+ * "any Vertex model" wrongly disables structured output for Vertex+Claude (the
+ * primary production config) and forces fragile hand-parsed JSON.
+ */
+/** True when the provider+model is a Gemini model (the only family with the tools↔schema conflict). */
+export function isGeminiProvider(providerName, modelName) {
+    if (providerName === "google-ai") {
+        return true;
+    }
+    if (providerName === "vertex") {
+        // Vertex hosts both Gemini and Claude. Only non-Claude (Gemini) models
+        // have the tools↔schema conflict.
+        return !(modelName?.startsWith("claude-") ?? false);
+    }
+    return false;
+}
+/**
+ * True when structured output must be disabled for this call because tools are
+ * active on a Gemini provider. Mirrors the AI-SDK constraint exactly.
+ */
+export function isToolsSchemaExclusionInForce(providerName, modelName, shouldUseTools, toolCount) {
+    return (isGeminiProvider(providerName, modelName) && shouldUseTools && toolCount > 0);
+}
+/**
+ * True when a provider error indicates the request was rejected because JSON /
+ * structured output and tool-calling cannot be combined for that provider
+ * (e.g. Groq: "json mode cannot be combined with tool/function calling").
+ *
+ * This is the runtime, provider-agnostic complement to the static Gemini gate:
+ * any provider with the same limitation can be detected from its error message
+ * and retried without structured output instead of failing the call.
+ */
+export function isToolsSchemaConflictError(error) {
+    const message = error instanceof Error
+        ? error.message
+        : typeof error === "string"
+            ? error
+            : "";
+    return (/cannot be combined with (a )?(tool|function)/i.test(message) ||
+        /json[\s_-]?(mode|schema|object|output)[^.]{0,60}(tool|function)/i.test(message) ||
+        /(tool|function)[\s-]?call[^.]{0,60}json[\s_-]?(mode|schema)/i.test(message) ||
+        /response_format[^.]{0,60}(tool|function)/i.test(message));
+}

package/dist/lib/core/modules/GenerationHandler.js

@@ -21,6 +21,8 @@ import { calculateCost } from "../../utils/pricing.js";
 import { withProviderRetry } from "../../utils/providerRetry.js";
 import { calculateCacheSavingsPercent, extractCacheCreationTokens, extractCacheReadTokens, extractTokenUsage, } from "../../utils/tokenUtils.js";
 import { DEFAULT_MAX_STEPS } from "../constants.js";
+import { isToolsSchemaConflictError, isToolsSchemaExclusionInForce, } from "./structuredOutputPolicy.js";
+import { coerceJsonToSchema } from "../../utils/json/coerce.js";
 import { NoObjectGeneratedError } from "../../utils/generationErrors.js";
 import { Output, stepCountIs } from "../../utils/tool.js";
 import { generateText } from "../../utils/generation.js";
@@ -76,8 +78,10 @@ export class GenerationHandler {
             (!!options.schema ||
                 options.output?.format === "json" ||
                 options.output?.format === "structured");
+        // The tools↔schema conflict is a Gemini-only API limitation. Vertex+Claude
+        // supports both simultaneously, so only exclude for actual Gemini models.
         const useStructuredOutput = wantsStructuredOutput &&
-            !(isGoogleProvider && shouldUseTools && Object.keys(tools).length > 0);
+            !isToolsSchemaExclusionInForce(this.providerName, this.modelName, shouldUseTools, Object.keys(tools).length);
         // Annotate the last tool with cache_control so the full tool-definition
         // block becomes a cache breakpoint for Anthropic-family providers.
         // Non-Anthropic providers harmlessly ignore unknown providerOptions.
@@ -279,20 +283,30 @@ export class GenerationHandler {
                 return result;
             }
             catch (error) {
-                // If NoObjectGeneratedError is thrown when using schema + tools together,
-                // fall back to generating without experimental_output and extract JSON manually
-                if (error instanceof NoObjectGeneratedError && useStructuredOutput) {
+                // Fall back to text-mode (no experimental_output) when structured
+                // output + tools failed, in two cases:
+                //   1. NoObjectGeneratedError — the SDK couldn't coerce the object.
+                //   2. The provider rejected json-mode-with-tools outright (e.g. Groq:
+                //      "json mode cannot be combined with tool/function calling").
+                // In both cases we retry without structured output and let
+                // formatEnhancedResult coerce the text response into valid JSON.
+                const isStructuredOutputConflict = useStructuredOutput &&
+                    (error instanceof NoObjectGeneratedError ||
+                        isToolsSchemaConflictError(error));
+                if (isStructuredOutputConflict) {
                     span.setAttribute("neurolink.has_fallback", true);
                     // NLK-GAP-007: Record initial failure event before fallback retry
                     span.addEvent("retry.initial_failure", {
-                        "error.message": error.message,
+                        "error.message": error instanceof Error ? error.message : String(error),
                         "retry.attempt": 1,
-                        "retry.reason": "NoObjectGeneratedError_structured_output_fallback",
+                        "retry.reason": error instanceof NoObjectGeneratedError
+                            ? "NoObjectGeneratedError_structured_output_fallback"
+                            : "tools_schema_conflict_structured_output_fallback",
                     });
-                    logger.debug("[GenerationHandler] NoObjectGeneratedError caught - falling back to manual JSON extraction", {
+                    logger.debug("[GenerationHandler] structured-output conflict caught - falling back to manual JSON extraction", {
                         provider: this.providerName,
                         model: this.modelName,
-                        error: error.message,
+                        error: error instanceof Error ? error.message : String(error),
                     });
                     // Retry without experimental_output - the formatEnhancedResult method
                     // will extract JSON from the text response
@@ -460,41 +474,76 @@ export class GenerationHandler {
             options.output?.format === "json" ||
             options.output?.format === "structured";
         let content;
+        let structuredData;
+        let jsonRepaired = false;
+        let jsonTruncated = false;
+        // Strip an outer ```json fence and coerce raw model text into canonical
+        // JSON. Object/array roots are recovered via balanced-scan + jsonrepair;
+        // scalar JSON roots (string/number/bool) via plain JSON.parse. When
+        // nothing JSON-shaped is recoverable, the raw text is returned unchanged,
+        // structuredData stays unset, and a WARN makes the broken case observable.
+        const coerceTextMode = (rawText) => {
+            const strippedText = rawText
+                .replace(/^```(?:json)?\s*\n?/i, "")
+                .replace(/\n?```\s*$/i, "")
+                .trim();
+            const coerced = coerceJsonToSchema(strippedText, options.schema);
+            if (coerced) {
+                structuredData = coerced.structuredData;
+                if (coerced.repaired) {
+                    jsonRepaired = true;
+                }
+                if (coerced.truncated) {
+                    jsonTruncated = true;
+                }
+                return coerced.content;
+            }
+            try {
+                const scalar = JSON.parse(strippedText);
+                if (scalar !== null && scalar !== undefined) {
+                    structuredData = scalar;
+                    return strippedText;
+                }
+            }
+            catch {
+                // not JSON at all — fall through to raw text + WARN
+            }
+            logger.warn("[GenerationHandler] schema requested but no JSON could be recovered from model text; returning raw text", { provider: this.providerName, model: this.modelName });
+            return strippedText;
+        };
         if (useStructuredOutput) {
             try {
                 const experimentalOutput = generateResult.experimental_output;
                 if (experimentalOutput !== undefined) {
+                    // AI-SDK already parsed + schema-validated the object. Expose it
+                    // directly and serialise canonically — no hand-parsing needed.
+                    structuredData = experimentalOutput;
                     content = JSON.stringify(experimentalOutput);
                 }
                 else {
-                    // Fall back to text parsing
-                    const rawText = generateResult.text || "";
-                    const strippedText = rawText
-                        .replace(/^```(?:json)?\s*\n?/i, "")
-                        .replace(/\n?```\s*$/i, "")
-                        .trim();
-                    content = strippedText;
+                    content = coerceTextMode(generateResult.text || "");
                 }
             }
             catch (outputError) {
-                // experimental_output is a getter that can throw NoObjectGeneratedError
-                // Fall back to text parsing when structured output fails
+                // experimental_output is a getter that can throw NoObjectGeneratedError.
                 logger.debug("[GenerationHandler] experimental_output threw, falling back to text parsing", {
                     error: outputError instanceof Error
                         ? outputError.message
                         : String(outputError),
                 });
-                const rawText = generateResult.text || "";
-                const strippedText = rawText
-                    .replace(/^```(?:json)?\s*\n?/i, "")
-                    .replace(/\n?```\s*$/i, "")
-                    .trim();
-                content = strippedText;
+                content = coerceTextMode(generateResult.text || "");
             }
         }
         else {
             content = generateResult.text;
         }
+        // Tie the coercion repair to the provider's truncation signal: if the
+        // response stopped on the token cap, treat the structured output as
+        // truncated regardless of which coerce candidate won, and warn.
+        if (useStructuredOutput && generateResult.finishReason === "length") {
+            jsonTruncated = true;
+            logger.warn("[GenerationHandler] Structured output truncated by token cap (finishReason=length); increase maxTokens", { provider: this.providerName, model: this.modelName });
+        }
         // Extract usage with support for different formats and reasoning tokens
         // Note: The AI SDK bundles thinking tokens into promptTokens for Google models.
         // Separate reasoningTokens tracking will work when/if the AI SDK adds support.
@@ -537,8 +586,11 @@ export class GenerationHandler {
         const reasoningTokens = usage.reasoning ?? undefined;
         return {
             content,
+            structuredData,
             usage,
             finishReason: generateResult.finishReason,
+            jsonRepaired: jsonRepaired || undefined,
+            jsonTruncated: jsonTruncated || undefined,
             provider: this.providerName,
             model: this.modelName,
             reasoning,

package/dist/lib/core/modules/structuredOutputPolicy.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Policy for when AI-SDK structured output (experimental_output) must be
+ * disabled because the provider cannot combine tool calls with JSON-schema
+ * enforcement.
+ *
+ * This is a GEMINI-ONLY API limitation. Anthropic Claude — including when
+ * hosted on Vertex (modelName starts with "claude-") — supports tools and
+ * structured output simultaneously, so it must NOT be excluded. A gate keyed on
+ * "any Vertex model" wrongly disables structured output for Vertex+Claude (the
+ * primary production config) and forces fragile hand-parsed JSON.
+ */
+/** True when the provider+model is a Gemini model (the only family with the tools↔schema conflict). */
+export declare function isGeminiProvider(providerName: string, modelName: string | undefined): boolean;
+/**
+ * True when structured output must be disabled for this call because tools are
+ * active on a Gemini provider. Mirrors the AI-SDK constraint exactly.
+ */
+export declare function isToolsSchemaExclusionInForce(providerName: string, modelName: string | undefined, shouldUseTools: boolean, toolCount: number): boolean;
+/**
+ * True when a provider error indicates the request was rejected because JSON /
+ * structured output and tool-calling cannot be combined for that provider
+ * (e.g. Groq: "json mode cannot be combined with tool/function calling").
+ *
+ * This is the runtime, provider-agnostic complement to the static Gemini gate:
+ * any provider with the same limitation can be detected from its error message
+ * and retried without structured output instead of failing the call.
+ */
+export declare function isToolsSchemaConflictError(error: unknown): boolean;

package/dist/lib/core/modules/structuredOutputPolicy.js

@@ -0,0 +1,51 @@
+/**
+ * Policy for when AI-SDK structured output (experimental_output) must be
+ * disabled because the provider cannot combine tool calls with JSON-schema
+ * enforcement.
+ *
+ * This is a GEMINI-ONLY API limitation. Anthropic Claude — including when
+ * hosted on Vertex (modelName starts with "claude-") — supports tools and
+ * structured output simultaneously, so it must NOT be excluded. A gate keyed on
+ * "any Vertex model" wrongly disables structured output for Vertex+Claude (the
+ * primary production config) and forces fragile hand-parsed JSON.
+ */
+/** True when the provider+model is a Gemini model (the only family with the tools↔schema conflict). */
+export function isGeminiProvider(providerName, modelName) {
+    if (providerName === "google-ai") {
+        return true;
+    }
+    if (providerName === "vertex") {
+        // Vertex hosts both Gemini and Claude. Only non-Claude (Gemini) models
+        // have the tools↔schema conflict.
+        return !(modelName?.startsWith("claude-") ?? false);
+    }
+    return false;
+}
+/**
+ * True when structured output must be disabled for this call because tools are
+ * active on a Gemini provider. Mirrors the AI-SDK constraint exactly.
+ */
+export function isToolsSchemaExclusionInForce(providerName, modelName, shouldUseTools, toolCount) {
+    return (isGeminiProvider(providerName, modelName) && shouldUseTools && toolCount > 0);
+}
+/**
+ * True when a provider error indicates the request was rejected because JSON /
+ * structured output and tool-calling cannot be combined for that provider
+ * (e.g. Groq: "json mode cannot be combined with tool/function calling").
+ *
+ * This is the runtime, provider-agnostic complement to the static Gemini gate:
+ * any provider with the same limitation can be detected from its error message
+ * and retried without structured output instead of failing the call.
+ */
+export function isToolsSchemaConflictError(error) {
+    const message = error instanceof Error
+        ? error.message
+        : typeof error === "string"
+            ? error
+            : "";
+    return (/cannot be combined with (a )?(tool|function)/i.test(message) ||
+        /json[\s_-]?(mode|schema|object|output)[^.]{0,60}(tool|function)/i.test(message) ||
+        /(tool|function)[\s-]?call[^.]{0,60}json[\s_-]?(mode|schema)/i.test(message) ||
+        /response_format[^.]{0,60}(tool|function)/i.test(message));
+}
+//# sourceMappingURL=structuredOutputPolicy.js.map

package/dist/lib/neurolink.js

@@ -66,6 +66,7 @@ import { CircuitBreaker, ERROR_CODES, ErrorFactory, isAbortError, isRetriableErr
 import { hasLifecycleErrorFired, markLifecycleErrorFired, } from "./utils/lifecycleCallbacks.js";
 import { resolveLifecycleTimeoutMs } from "./utils/lifecycleTimeout.js";
 import { cloneOptionsForCallIsolation } from "./utils/cloneOptions.js";
+import { coerceJsonToSchema } from "./utils/json/coerce.js";
 // Factory processing imports
 import { createCleanStreamOptions, enhanceTextGenerationOptions, processFactoryOptions, processStreamingFactoryOptions, validateFactoryConfig, } from "./utils/factoryProcessing.js";
 import { logger, mcpLogger } from "./utils/logger.js";
@@ -3345,6 +3346,60 @@ Current user's request: ${currentInput}`;
     }
     finalizeGenerateRequestResult(params) {
         const { generateSpan, options, textOptions, textResult, factoryResult, originalPrompt, startTime, } = params;
+        // Provider-agnostic JSON coercion for schema requests. Structured-output
+        // enforcement makes valid JSON the overwhelming case; for every other
+        // provider path — including generate() overrides (Vertex, Anthropic,
+        // Bedrock, Google AI Studio) — object/array roots are recovered here via
+        // balanced-scan + jsonrepair and scalar JSON roots via plain JSON.parse,
+        // with the parsed value exposed as `structuredData`. If nothing
+        // JSON-shaped is recoverable (pure prose), the raw text is returned,
+        // `structuredData` stays undefined, and a WARN makes the case observable.
+        // Runs BEFORE the end-of-generation emits below so event consumers see
+        // the same coerced content/structuredData the caller receives.
+        if (textOptions.schema &&
+            textResult.structuredData === undefined &&
+            typeof textResult.content === "string") {
+            const coerced = coerceJsonToSchema(textResult.content, textOptions.schema);
+            if (coerced) {
+                textResult.content = coerced.content;
+                textResult.structuredData = coerced.structuredData;
+                if (coerced.repaired) {
+                    textResult.jsonRepaired = true;
+                }
+                if (coerced.truncated) {
+                    textResult.jsonTruncated = true;
+                }
+            }
+            else {
+                try {
+                    const scalar = JSON.parse(textResult.content);
+                    if (scalar !== null && scalar !== undefined) {
+                        textResult.structuredData = scalar;
+                    }
+                }
+                catch {
+                    logger.warn("[NeuroLink] schema requested but no JSON could be recovered from model output; returning raw text", { provider: textResult.provider, model: textResult.model });
+                }
+            }
+        }
+        // Surface truncation when a schema was requested: either the provider
+        // reported finishReason="length" or the recovered JSON came from an
+        // unclosed span. Either way `structuredData` may be incomplete — warn at
+        // info level so it is observable in production (not just debug logs).
+        if (textOptions.schema) {
+            if (textResult.finishReason === "length") {
+                textResult.jsonTruncated = true;
+            }
+            if (textResult.jsonTruncated) {
+                logger.warn("[NeuroLink] Structured output may be truncated (finishReason=length or unclosed JSON); " +
+                    "increase maxTokens to fit the full response.", {
+                    provider: textResult.provider,
+                    model: textResult.model,
+                    finishReason: textResult.finishReason,
+                    outputTokens: textResult.usage?.output,
+                });
+            }
+        }
         // Skip the top-level `generation:end` emission when the provider already
         // emitted it from its native generate path (Vertex / Google AI Studio).
         // Without this guard, native-path providers would surface TWO events
@@ -3378,7 +3433,10 @@ Current user's request: ${currentInput}`;
         this.emitter.emit("message", `Generation completed in ${Date.now() - startTime}ms`);
         const generateResult = {
             content: textResult.content,
+            structuredData: textResult.structuredData,
             finishReason: textResult.finishReason,
+            jsonRepaired: textResult.jsonRepaired,
+            jsonTruncated: textResult.jsonTruncated,
             provider: textResult.provider,
             model: textResult.model,
             usage: textResult.usage