fix: preserve embedded json fences in structured output (#13948)

Co-authored-by: Mastra Code (openai/gpt-5.4) <noreply@mastra.ai>

Author: roaminro

.changeset/big-rats-smoke.md

@@ -0,0 +1,5 @@
+---
+'@mastra/core': patch
+---
+
+Fixed structured output parsing when JSON string fields include fenced JSON examples.

packages/core/src/stream/base/output-format-handlers.test.ts

@@ -851,6 +851,50 @@ describe('output-format-handlers', () => {
       expect(objectResultChunk).toBeDefined();
       expect(objectResultChunk?.object).toEqual({ title: 'Test', count: 5 });
     });
+
+    it('should preserve ```json fences inside valid JSON string values', async () => {
+      const schema = z.object({
+        response: z.string(),
+        status: z.string(),
+      });
+
+      const transformer = createObjectStreamTransformer({
+        structuredOutput: { schema },
+      });
+
+      const response = 'API example:\n```json\nPOST /v1/payments\n{\n  "customerId": "cust_123"\n}\n```';
+
+      const streamParts: ChunkType<typeof schema>[] = [
+        {
+          type: 'text-delta',
+          runId: 'test-run',
+          from: ChunkFrom.AGENT,
+          payload: {
+            id: '1',
+            text: JSON.stringify({ response, status: 'ok' }),
+          },
+        },
+        {
+          type: 'finish',
+          runId: 'test-run',
+          from: ChunkFrom.AGENT,
+          payload: {
+            stepResult: { reason: 'stop' },
+            output: { usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 } },
+            metadata: {},
+            messages: { all: [], user: [], nonUser: [] },
+          },
+        },
+      ];
+
+      // @ts-expect-error - web/stream readable stream type error
+      const stream = convertArrayToReadableStream(streamParts).pipeThrough(transformer);
+      const chunks = await convertAsyncIterableToArray(stream);
+
+      const objectResultChunk = chunks.find(c => c?.type === 'object-result');
+      expect(objectResultChunk).toBeDefined();
+      expect(objectResultChunk?.object).toEqual({ response, status: 'ok' });
+    });
   });
 
   describe('unescaped newlines in JSON strings', () => {

packages/core/src/stream/base/output-format-handlers.ts

@@ -258,16 +258,18 @@ abstract class BaseFormatHandler<OUTPUT = undefined> {
       }
     }
 
-    // Some LLMs wrap the JSON response in code blocks.
-    // In that case, first try to extract content from complete code blocks
-    if (processedText.includes('```json')) {
-      const match = processedText.match(/```json\s*\n?([\s\S]*?)\n?\s*```/);
+    // Some LLMs wrap the entire JSON response in a ```json code block.
+    // Only unwrap when the accumulated text itself starts with that fence so
+    // embedded examples inside valid JSON string values are preserved.
+    const trimmedStart = processedText.trimStart();
+    if (/^```json\b/.test(trimmedStart)) {
+      const match = trimmedStart.match(/^```json\s*\n?([\s\S]*?)\n?\s*```\s*$/);
       if (match && match[1]) {
         // Complete code block found - use content between tags
         processedText = match[1].trim();
       } else {
-        // No complete code block - just remove the opening ```json
-        processedText = processedText.replace(/^```json\s*\n?/, '');
+        // No complete code block yet - just remove the opening ```json prefix
+        processedText = trimmedStart.replace(/^```json\s*\n?/, '');
       }
     }