feat(agent): validate structured outputs after generation with one retry

The agent block never checked structured output after generation:
processStructuredResponse was a bare JSON.parse whose failure path logged,
attached an unread _responseFormatWarning, and returned success via the
standard-format fallback. Downstream blocks read the structured fields as
undefined, indistinguishable from a legitimate empty answer. Models with
native structured outputs are additionally constrained only by a weakened
grammar (the SDK transform strips enum, minLength, numeric bounds, and
similar keywords into advisory prose), and prompt-based models had no
enforcement at all.

Validation now runs in the provider-request seam whenever the response
format's existing strict flag is not false (the default the block schema
has always documented): truncation at the output token limit (read from
the final model trace segment every provider already populates),
unparseable JSON (with a Markdown code-fence rescue), and ajv validation
against the authored schema are one failure condition. A failed attempt
on a tool-free request is resampled once, with the failed attempt's
tokens, cost, and trace segments folded into the final result; requests
carrying tools are not resampled because their tools would execute again.
A response that still fails validation fails the block explicitly.
Setting "strict": false keeps the previous lenient fallback, and
streaming responses are unchanged.

Claude-Session: https://claude.ai/code/session_018L7CosQfKB9SGCF8E9fLfY

Author: mzxchandra

apps/docs/content/docs/workflows/blocks/agent.mdx

@@ -72,6 +72,12 @@ Give the agent a JSON Schema to force structured output. The response is constra
 }
 ```
 
+The schema is checked after generation.
+A response that fails to parse as JSON, violates the schema (including constraints like `enum`, `minLength`, and number bounds), or was cut off at the output token limit counts as a failed generation.
+A block without tools retries once automatically; a block with tools is not retried, because its tools would run again.
+When no valid response remains, the block fails with the validation error instead of silently returning unstructured text.
+Set `"strict": false` in the response format to skip enforcement and accept whatever the model returns.
+
 ### Advanced
 
 Some settings live under advanced, or appear only for models that support them:

apps/sim/executor/handlers/agent/agent-handler.test.ts

@@ -148,6 +148,21 @@ vi.mock('@/lib/internal/custom-tools/read-available-by-id-or-title', () => ({
     mockReadAvailableCustomToolByIdOrTitleAsExecutor(...args),
 }))
 
+/**
+ * Provider response whose content satisfies a strict structured response
+ * format, for tests that exercise other behavior alongside a responseFormat.
+ */
+function structuredMockResponse(content: string) {
+  return {
+    content,
+    model: 'mock-model',
+    tokens: { input: 10, output: 20, total: 30 },
+    timing: { total: 100 },
+    toolCalls: [],
+    cost: undefined,
+  }
+}
+
 const mockGetAllBlocks = getAllBlocks as Mock
 const mockExecuteTool = executeTool as Mock
 const mockGetProviderFromModel = getProviderFromModel as Mock
@@ -1988,6 +2003,7 @@ describe('AgentBlockHandler', () => {
       mockContext.resolvedSecretTraceRegistry = new ResolvedSecretTraceRegistry([
         { name: 'UNUSED', plaintext: 'x', encryptedValue: 'encrypted-unused' },
       ])
+      mockExecuteProviderRequest.mockResolvedValueOnce(structuredMockResponse('{"answer":"ok"}'))
 
       await handler.execute(mockContext, mockBlock, {
         model: 'gpt-4o',
@@ -2014,6 +2030,7 @@ describe('AgentBlockHandler', () => {
       registry.recordResolvedAtInputPath('DESCRIPTION', 'classified', inputPath)
       registry.recordResolvedInputProjection(inputPath, 'classified', '{{DESCRIPTION}}')
       mockContext.resolvedSecretTraceRegistry = registry
+      mockExecuteProviderRequest.mockResolvedValueOnce(structuredMockResponse('{"answer":"ok"}'))
 
       await handler.execute(mockContext, mockBlock, {
         model: 'gpt-4o',
@@ -2051,6 +2068,7 @@ describe('AgentBlockHandler', () => {
         projectedResponseFormat
       )
       mockContext.resolvedSecretTraceRegistry = registry
+      mockExecuteProviderRequest.mockResolvedValueOnce(structuredMockResponse('{"answer":"ok"}'))
 
       await handler.execute(mockContext, mockBlock, {
         model: 'gpt-4o',
@@ -2177,6 +2195,7 @@ describe('AgentBlockHandler', () => {
       registry.recordResolvedAtInputPath('FORMAT_NAME', 'private-schema', inputPath)
       registry.recordResolvedInputProjection(inputPath, 'private-schema', '{{FORMAT_NAME}}')
       mockContext.resolvedSecretTraceRegistry = registry
+      mockExecuteProviderRequest.mockResolvedValueOnce(structuredMockResponse('{}'))
 
       await handler.execute(mockContext, mockBlock, {
         model: 'gpt-4o',
@@ -2298,6 +2317,7 @@ describe('AgentBlockHandler', () => {
         projectedResponseFormat
       )
       mockContext.resolvedSecretTraceRegistry = registry
+      mockExecuteProviderRequest.mockResolvedValueOnce(structuredMockResponse('{}'))
 
       await handler.execute(mockContext, mockBlock, {
         model: 'gpt-4o',
@@ -2352,6 +2372,7 @@ describe('AgentBlockHandler', () => {
         projectedResponseFormat
       )
       mockContext.resolvedSecretTraceRegistry = registry
+      mockExecuteProviderRequest.mockResolvedValueOnce(structuredMockResponse('{"answer":"ok"}'))
       const handlerInputs = {
         model: 'gpt-4o',
         userPrompt: 'Return an answer.',
@@ -2408,6 +2429,140 @@ describe('AgentBlockHandler', () => {
       })
     })
 
+    it('retries once when a strict structured response fails to parse, then succeeds', async () => {
+      mockExecuteProviderRequest
+        .mockResolvedValueOnce(structuredMockResponse('{"result": "truncated mid'))
+        .mockResolvedValueOnce(structuredMockResponse('{"result": "ok"}'))
+
+      const result = await handler.execute(mockContext, mockBlock, {
+        model: 'gpt-4o',
+        userPrompt: 'Test context',
+        apiKey: 'test-api-key',
+        responseFormat: '{"type":"object","properties":{"result":{"type":"string"}}}',
+      })
+
+      expect(mockExecuteProviderRequest).toHaveBeenCalledTimes(2)
+      expect(result).toMatchObject({ result: 'ok' })
+      expect((result as Record<string, unknown>).tokens).toEqual({
+        input: 20,
+        output: 40,
+        total: 60,
+      })
+      expect(mockExecuteProviderRequest.mock.calls[0][1]).toEqual(
+        mockExecuteProviderRequest.mock.calls[1][1]
+      )
+    })
+
+    it('fails the block when the structured response fails validation twice', async () => {
+      mockExecuteProviderRequest
+        .mockResolvedValueOnce(structuredMockResponse('not json at all'))
+        .mockResolvedValueOnce(structuredMockResponse('still not json'))
+
+      await expect(
+        handler.execute(mockContext, mockBlock, {
+          model: 'gpt-4o',
+          userPrompt: 'Test context',
+          apiKey: 'test-api-key',
+          responseFormat: '{"type":"object","properties":{"result":{"type":"string"}}}',
+        })
+      ).rejects.toThrow('Agent structured output failed validation after a retry')
+      expect(mockExecuteProviderRequest).toHaveBeenCalledTimes(2)
+    })
+
+    it('rejects schema-violating output that parses as JSON', async () => {
+      mockExecuteProviderRequest
+        .mockResolvedValueOnce(structuredMockResponse('{"status":""}'))
+        .mockResolvedValueOnce(structuredMockResponse('{"status":"open"}'))
+
+      const result = await handler.execute(mockContext, mockBlock, {
+        model: 'gpt-4o',
+        userPrompt: 'Test context',
+        apiKey: 'test-api-key',
+        responseFormat:
+          '{"type":"object","properties":{"status":{"type":"string","enum":["open","closed"]}},"required":["status"]}',
+      })
+
+      expect(mockExecuteProviderRequest).toHaveBeenCalledTimes(2)
+      expect(result).toMatchObject({ status: 'open' })
+    })
+
+    it('keeps the lenient fallback when the response format sets strict false', async () => {
+      mockExecuteProviderRequest.mockResolvedValueOnce(structuredMockResponse('not json at all'))
+
+      const result = await handler.execute(mockContext, mockBlock, {
+        model: 'gpt-4o',
+        userPrompt: 'Test context',
+        apiKey: 'test-api-key',
+        responseFormat:
+          '{"name":"response_schema","schema":{"type":"object","properties":{"result":{"type":"string"}}},"strict":false}',
+      })
+
+      expect(mockExecuteProviderRequest).toHaveBeenCalledTimes(1)
+      expect(result).toMatchObject({
+        content: 'not json at all',
+        _responseFormatWarning: expect.stringContaining('did not adhere'),
+      })
+    })
+
+    it('fails without resampling when the request carries tools', async () => {
+      mockTransformBlockTool.mockReturnValue({
+        id: 'test_tool',
+        name: 'Test Tool',
+        description: 'A test tool',
+        parameters: { type: 'object', properties: {} },
+      })
+      mockExecuteProviderRequest.mockResolvedValueOnce(structuredMockResponse('not json at all'))
+
+      await expect(
+        handler.execute(mockContext, mockBlock, {
+          model: 'gpt-4o',
+          userPrompt: 'Test context',
+          apiKey: 'test-api-key',
+          responseFormat: '{"type":"object","properties":{"result":{"type":"string"}}}',
+          tools: [{ type: 'test_tool', title: 'Test Tool', params: {}, usageControl: 'auto' }],
+        })
+      ).rejects.toThrow('Agent structured output failed validation:')
+      expect(mockExecuteProviderRequest).toHaveBeenCalledTimes(1)
+    })
+
+    it('fails a structured response whose final model segment stopped at max_tokens', async () => {
+      const truncatedResponse = () => ({
+        content: '{"result": "parses but was cut short by the cap"}',
+        model: 'mock-model',
+        tokens: { input: 10, output: 20, total: 30 },
+        timing: {
+          startTime: 't0',
+          endTime: 't1',
+          duration: 10,
+          timeSegments: [
+            {
+              type: 'model',
+              name: 'final',
+              startTime: 0,
+              endTime: 1,
+              duration: 1,
+              finishReason: 'max_tokens',
+            },
+          ],
+        },
+        toolCalls: [],
+        cost: undefined,
+      })
+      mockExecuteProviderRequest
+        .mockResolvedValueOnce(truncatedResponse())
+        .mockResolvedValueOnce(truncatedResponse())
+
+      await expect(
+        handler.execute(mockContext, mockBlock, {
+          model: 'gpt-4o',
+          userPrompt: 'Test context',
+          apiKey: 'test-api-key',
+          responseFormat: '{"type":"object","properties":{"result":{"type":"string"}}}',
+        })
+      ).rejects.toThrow('output token limit')
+      expect(mockExecuteProviderRequest).toHaveBeenCalledTimes(2)
+    })
+
     it('should handle invalid JSON in responseFormat gracefully', async () => {
       mockExecuteProviderRequest.mockResolvedValueOnce({
         content: 'Regular text response',