@spec-wave/cli 0.13.0 → 0.15.0

package/src/lib/claude.mjs

@@ -1,9 +1,12 @@
 import Anthropic from '@anthropic-ai/sdk';
-import { readFileSync, existsSync } from 'node:fs';
-import path from 'node:path';
-import { CONFIG_FILE, getProvider, DEFAULT_PROVIDER } from '../config.mjs';
+import { readFileSync } from 'node:fs';
+import {
+  getProvider, DEFAULT_PROVIDER, MODEL_LABEL_PREFIX,
+  DEFAULT_MAX_CRITIQUE_ATTEMPTS, labelNames,
+} from '../config.mjs';
 import { lintLanguage } from './output-lint.mjs';
 import { computeCost } from './usage-report.mjs';
+import { findConfigPath } from './project-root.mjs';
 
 // Teto de saída padrão. O valor anterior (8192) truncava specs reais: um
 // documento de ~20 KB em pt-BR já custa ~6k tokens, e modelos com raciocínio
@@ -12,44 +15,99 @@ import { computeCost } from './usage-report.mjs';
 // branco. Ajustável por `ai.maxTokens` / `ai.maxTokensByAction`.
 export const DEFAULT_MAX_TOKENS = 32768;
 
+// Teto padrão POR AÇÃO, aplicado abaixo de `ai.maxTokens` na precedência. A
+// crítica devolve uma lista JSON de findings, muito menor que um spec/plan —
+// 8192 é folgado para ela. Antes esse valor era passado hard-coded pelo
+// critique.mjs, o que sobrepunha `ai.maxTokensByAction.critique` e tornava o
+// knob morto; aqui ele é só um DEFAULT, então a configuração volta a valer.
+export const MAX_TOKENS_BY_ACTION = { critique: 8192 };
+
+/**
+ * Resolve o alias de modelo vindo de label (função PURA).
+ *
+ * A label `spec-wave:model:<apelido>` existe para reprocessar um caso difícil num
+ * modelo mais forte sem editar o .spec-wave.json e commitar — a decisão vale só
+ * para aquela issue. Duas labels na mesma issue é ambiguidade: nenhuma vale, não
+ * se sorteia.
+ *
+ * @param {Array<string|{name:string}>} [labels] labels da issue
+ * @param {object} [modelAliases] bloco `ai.modelAliases` do .spec-wave.json
+ * @returns {null|{ alias: string, model: string|null, error: null|'desconhecido'|'ambíguo' }}
+ */
+export function resolveModelLabel(labels = [], modelAliases = {}) {
+  const found = labelNames(labels).filter(n => n.startsWith(MODEL_LABEL_PREFIX));
+  if (found.length === 0) return null;
+  const aliases = found.map(n => n.slice(MODEL_LABEL_PREFIX.length));
+  if (found.length > 1) return { alias: aliases.join(', '), model: null, error: 'ambíguo' };
+  const model = modelAliases?.[aliases[0]];
+  return typeof model === 'string' && model.trim()
+    ? { alias: aliases[0], model: model.trim(), error: null }
+    : { alias: aliases[0], model: null, error: 'desconhecido' };
+}
+
 /**
  * Resolve provider/modelo/teto de tokens de IA (função PURA — testável sem
  * process.env nem fs).
  *
- * Precedência do modelo: env.SPEC_WAVE_MODEL → fileAi.models[action] →
- * fileAi.model → default do provider. Provider: env.SPEC_WAVE_PROVIDER →
- * fileAi.provider → default. Assim uma ação específica (ex.: critique) pode
- * usar modelo próprio via bloco `ai.models` do .spec-wave.json.
+ * Precedência do modelo:
+ *   env.SPEC_WAVE_MODEL → label `spec-wave:model:<alias>` → modelOverride
+ *   (escalada automática da crítica) → fileAi.models[action] → fileAi.model
+ *   → default do provider.
  *
- * maxTokens segue a mesma forma: env.SPEC_WAVE_MAX_TOKENS →
- * fileAi.maxTokensByAction[action] → fileAi.maxTokens → DEFAULT_MAX_TOKENS.
+ * A label vem ANTES da escalada de propósito: ela é decisão manual explícita do
+ * humano para aquela execução, e deve vencer a troca automática de modelo.
+ *
+ * Provider: env.SPEC_WAVE_PROVIDER → fileAi.provider → default.
+ *
+ * maxTokens: env.SPEC_WAVE_MAX_TOKENS → fileAi.maxTokensByAction[action] →
+ * fileAi.maxTokens → MAX_TOKENS_BY_ACTION[action] → DEFAULT_MAX_TOKENS.
  *
  * @param {object} params
  * @param {object} [params.env] objeto tipo process.env
  * @param {object} [params.fileAi] bloco `ai` do .spec-wave.json
  * @param {string} [params.action] ação de IA (ver AI_ACTIONS em config.mjs)
- * @returns {{ provider: string, model: string, secret: string, pricing: object|null, maxTokens: number }}
+ * @param {Array<string|{name:string}>} [params.labels] labels da issue em curso
+ * @param {string} [params.modelOverride] modelo imposto pelo chamador (escalada)
+ * @returns {{ provider, model, modelSource, labelAlias, secret, pricing,
+ *             maxTokens, escalationModel, maxCritiqueAttempts }}
  */
-export function resolveAiConfig({ env = {}, fileAi = {}, action } = {}) {
+export function resolveAiConfig({ env = {}, fileAi = {}, action, labels = [], modelOverride } = {}) {
   const provider = (env.SPEC_WAVE_PROVIDER || fileAi.provider || DEFAULT_PROVIDER).toLowerCase();
   const meta = getProvider(provider) || getProvider(DEFAULT_PROVIDER);
-  const model = env.SPEC_WAVE_MODEL
-    || (action && fileAi.models?.[action])
-    || fileAi.model
-    || meta.defaultModel;
+
+  const labelAlias = resolveModelLabel(labels, fileAi.modelAliases);
+  // Tabela em vez de cadeia de `||` para poder devolver a ORIGEM do modelo — sem
+  // isso, o log da Action não diz por que aquele modelo foi usado.
+  const [modelSource, rawModel] = [
+    ['env',        env.SPEC_WAVE_MODEL],
+    ['label',      labelAlias?.model],
+    ['escalation', modelOverride],
+    ['action',     action ? fileAi.models?.[action] : undefined],
+    ['file',       fileAi.model],
+    ['default',    meta.defaultModel],
+  ].find(([, value]) => typeof value === 'string' && value.trim());
+
   // pricing: tabela `ai.pricing` do .spec-wave.json ({ [model]: { input,
   // output } } em USD/1M tokens) — usada para estimar custo quando o provider
   // não devolve o valor (Anthropic).
   const maxTokens = positiveInt(env.SPEC_WAVE_MAX_TOKENS)
     ?? (action ? positiveInt(fileAi.maxTokensByAction?.[action]) : undefined)
     ?? positiveInt(fileAi.maxTokens)
+    ?? (action ? MAX_TOKENS_BY_ACTION[action] : undefined)
     ?? DEFAULT_MAX_TOKENS;
+
   return {
     provider: meta.value,
-    model,
+    model: rawModel.trim(),
+    modelSource,
+    labelAlias,
     secret: meta.secret,
     pricing: fileAi.pricing || null,
     maxTokens,
+    escalationModel: typeof fileAi.escalationModel === 'string'
+      ? (fileAi.escalationModel.trim() || null)
+      : null,
+    maxCritiqueAttempts: positiveInt(fileAi.maxCritiqueAttempts) ?? DEFAULT_MAX_CRITIQUE_ATTEMPTS,
   };
 }
 
@@ -60,21 +118,27 @@ function positiveInt(value) {
   return Number.isInteger(n) && n > 0 ? n : undefined;
 }
 
-// Resolve o provider/modelo de IA a partir do .spec-wave.json (gravado pelo init
-// e versionado no repo) com precedência para variáveis de ambiente — assim os
-// workflows usam exatamente o que foi escolhido no init, sem depender de flags.
-// Wrapper fino: lê o arquivo e delega a decisão à resolveAiConfig (pura).
-function resolveAi(action) {
-  let fileAi = {};
+/**
+ * Bloco `ai` do .spec-wave.json (ou {} se ausente/corrompido).
+ * Procura o config subindo na árvore — comandos rodados de um subdiretório
+ * precisam achar a mesma configuração que a raiz.
+ */
+export function readFileAi(cwd = process.cwd()) {
   try {
-    const configPath = path.join(process.cwd(), CONFIG_FILE);
-    if (existsSync(configPath)) {
-      fileAi = JSON.parse(readFileSync(configPath, 'utf-8')).ai || {};
-    }
+    const configPath = findConfigPath(cwd);
+    if (configPath) return JSON.parse(readFileSync(configPath, 'utf-8')).ai || {};
   } catch {
     // config ausente/corrompido → cai nos defaults/env
   }
-  return resolveAiConfig({ env: process.env, fileAi, action });
+  return {};
+}
+
+// Resolve o provider/modelo de IA a partir do .spec-wave.json (gravado pelo init
+// e versionado no repo) com precedência para variáveis de ambiente — assim os
+// workflows usam exatamente o que foi escolhido no init, sem depender de flags.
+// Wrapper fino: lê o arquivo e delega a decisão à resolveAiConfig (pura).
+function resolveAi(action, { labels = [], modelOverride } = {}) {
+  return resolveAiConfig({ env: process.env, fileAi: readFileAi(), action, labels, modelOverride });
 }
 
 // Retry de falha transitória do provedor. Sem isto, um corpo cortado numa
@@ -158,6 +222,80 @@ export function supportsTemperature(model) {
   return !MODELS_WITHOUT_SAMPLING_PARAMS.test(model || '');
 }
 
+// Modelos que aceitam `strict: true` na definição de tool (structured outputs).
+// O default do repo (claude-sonnet-4-6) NÃO está na lista — enviar strict lá
+// devolve 400. Sem strict, o tool_choice forçado ainda garante um bloco tool_use
+// com input JSON; quem fecha o contrato é o validador do schema.
+const MODELS_WITH_STRICT_SCHEMA =
+  /claude-(?:fable-5|mythos-5|opus-5|opus-4[.-](?:1|5|8)|sonnet-5|haiku-4[.-]5)/i;
+
+/** O modelo aceita `strict: true` na definição de tool? (função PURA) */
+export function supportsStrictSchema(model) {
+  return MODELS_WITH_STRICT_SCHEMA.test(model || '');
+}
+
+/**
+ * Corpo EXATO de `client.messages.create` (função PURA — testável sem HTTP).
+ *
+ * Com `schema`, força a ferramenta via tool_choice: o modelo não tem como
+ * responder em texto livre, que é o que produzia JSON sujo na crítica.
+ * `disable_parallel_tool_use` garante no máximo um bloco tool_use.
+ */
+export function buildAnthropicRequest({
+  ai, systemPrompt, userContent, temperature, maxTokens, schema, strict,
+}) {
+  return {
+    model: ai.model,
+    max_tokens: maxTokens,
+    // Omitida nos modelos que removeram sampling (Opus 4.7+, Sonnet 5, Fable 5):
+    // enviá-la devolve 400.
+    ...(temperature === undefined ? {} : { temperature }),
+    messages: [{ role: 'user', content: userContent }],
+    system: systemPrompt,
+    ...(schema ? {
+      tools: [{
+        name: schema.name,
+        description: schema.description,
+        input_schema: schema.jsonSchema,
+        ...(strict ? { strict: true } : {}),
+      }],
+      tool_choice: { type: 'tool', name: schema.name, disable_parallel_tool_use: true },
+    } : {}),
+  };
+}
+
+/**
+ * Corpo EXATO do POST da OpenRouter (função PURA — testável sem HTTP).
+ *
+ * `provider.require_parameters` é obrigatório junto do response_format: sem ele o
+ * roteador escolhe endpoints que IGNORAM o schema e devolvem prosa, e o erro só
+ * apareceria no JSON.parse, três retries depois. Com ele, a recusa é imediata e
+ * a mensagem diz o que trocar.
+ */
+export function buildOpenRouterBody({
+  ai, systemPrompt, userContent, temperature, maxTokens, schema,
+}) {
+  return {
+    model: ai.model,
+    max_tokens: maxTokens,
+    // Omitida nos modelos que removeram sampling (Opus 4.7+, Sonnet 5, Fable 5).
+    ...(temperature === undefined ? {} : { temperature }),
+    messages: [
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: userContent },
+    ],
+    // Pede o bloco `usage` completo na resposta (inclui `cost` em USD).
+    usage: { include: true },
+    ...(schema ? {
+      response_format: {
+        type: 'json_schema',
+        json_schema: { name: schema.name, strict: true, schema: schema.jsonSchema },
+      },
+      provider: { require_parameters: true },
+    } : {}),
+  };
+}
+
 // temperature padrão 0.2 (RFC-002 §5): "Determinism over Creativity". Pode ser
 // sobrescrita por chamada via opts, mas o default cobre spec/plan/decompose.
 //
@@ -173,7 +311,7 @@ export function supportsTemperature(model) {
 //    model, inputTokens, outputTokens, cost } por invocação (o retry de lint
 //    soma tokens/custo na MESMA entrada).
 export async function generateDocument(systemPrompt, userContent, opts = {}) {
-  const ai = resolveAi(opts.action);
+  const ai = resolveAi(opts.action, { labels: opts.labels });
   const temperature = opts.temperature ?? 0.2;
   // Modelos de reasoning (ex.: deepseek-r1, Opus 4.7+) consomem tokens
   // "pensando" antes da resposta, então o teto precisa cobrir raciocínio +
@@ -181,7 +319,7 @@ export async function generateDocument(systemPrompt, userContent, opts = {}) {
   const maxTokens = opts.maxTokens ?? ai.maxTokens;
   const sendTemperature = supportsTemperature(ai.model);
   console.log(
-    `Provider de IA: ${ai.provider} · modelo: ${ai.model} · ` +
+    `Provider de IA: ${ai.provider} · modelo: ${ai.model} (origem: ${ai.modelSource}) · ` +
     `temperature: ${sendTemperature ? temperature : 'n/a (removida neste modelo)'} · ` +
     `max_tokens: ${maxTokens}`
   );
@@ -232,26 +370,95 @@ export async function generateDocument(systemPrompt, userContent, opts = {}) {
     }
   }
 
-  // Telemetria: uma entrada por invocação no coletor passado pelo chamador.
-  // A Anthropic não devolve custo — estima via tabela ai.pricing, se houver.
-  if (Array.isArray(opts.usage)) {
-    if (cost === null && ai.provider === 'anthropic') {
-      cost = computeCost({ model: ai.model, inputTokens, outputTokens, pricing: ai.pricing });
-    }
-    opts.usage.push({
-      at: new Date().toISOString(),
-      action: opts.action || 'unknown',
-      provider: ai.provider,
-      model: ai.model,
-      inputTokens,
-      outputTokens,
-      cost,
-    });
-  }
+  recordUsageEntry(opts, ai, { inputTokens, outputTokens, cost });
 
   return opts.withReport ? { content, lintFindings, retried } : content;
 }
 
+// Telemetria: uma entrada por invocação no coletor passado pelo chamador.
+// A Anthropic não devolve custo — estima via tabela ai.pricing, se houver.
+// Extraída do generateDocument para o generateStructured usar a mesma contagem.
+function recordUsageEntry(opts, ai, { inputTokens, outputTokens, cost }) {
+  if (!Array.isArray(opts.usage)) return;
+  const finalCost = cost === null && ai.provider === 'anthropic'
+    ? computeCost({ model: ai.model, inputTokens, outputTokens, pricing: ai.pricing })
+    : cost;
+  opts.usage.push({
+    at: new Date().toISOString(),
+    action: opts.action || 'unknown',
+    provider: ai.provider,
+    model: ai.model,
+    inputTokens,
+    outputTokens,
+    cost: finalCost,
+  });
+}
+
+/**
+ * Geração com saída ESTRUTURADA e validada (JSON), não texto livre.
+ *
+ * Existe como função irmã de `generateDocument` — e não como um `opts.schema`
+ * nela — porque aquele caminho é string de ponta a ponta: remove cerca externa,
+ * roda lint de idioma e RE-GERA quando o lint reprova. Um payload JSON não deve
+ * passar por nada disso; só o lint já dobraria o custo de cada crítica.
+ *
+ * Anthropic: tool call forçado. OpenRouter: response_format json_schema +
+ * provider.require_parameters. A validação do schema roda DENTRO do retry —
+ * pedir de novo é exatamente o que pode resolver (ao contrário de truncamento).
+ * Esgotadas as tentativas o erro SOBE: nunca se devolve texto bruto disfarçado
+ * de resultado, que era a origem do vazamento de JSON nos comentários da issue.
+ *
+ * @param {string} systemPrompt
+ * @param {string} userContent
+ * @param {object} opts
+ * @param {{name,description,jsonSchema,validate?}} opts.schema `validate` é pura,
+ *        lança em payload inválido e devolve o valor normalizado
+ * @param {string} [opts.action] ação de IA (modelo/teto por ação)
+ * @param {Array} [opts.labels] labels da issue (override por label)
+ * @param {string} [opts.model] modelo imposto (escalada da crítica)
+ * @param {boolean} [opts.withReport] devolve { value, model, provider, modelSource }
+ * @returns {Promise<any>} valor validado (ou o relatório, com withReport)
+ */
+export async function generateStructured(systemPrompt, userContent, opts = {}) {
+  const schema = opts.schema;
+  if (!schema?.name || !schema?.jsonSchema) {
+    throw new Error('generateStructured exige opts.schema { name, jsonSchema }.');
+  }
+
+  const ai = resolveAi(opts.action, { labels: opts.labels, modelOverride: opts.model });
+  const temperature = opts.temperature ?? 0.2;
+  const maxTokens = opts.maxTokens ?? ai.maxTokens;
+  const sendTemperature = supportsTemperature(ai.model);
+  const strict = opts.strict ?? supportsStrictSchema(ai.model);
+
+  console.log(
+    `Provider de IA: ${ai.provider} · modelo: ${ai.model} (origem: ${ai.modelSource}) · ` +
+    `saída estruturada: ${schema.name}${strict ? ' (strict)' : ''} · max_tokens: ${maxTokens}`
+  );
+
+  const callOpts = {
+    temperature: sendTemperature ? temperature : undefined,
+    maxTokens,
+    schema,
+    strict,
+  };
+
+  // A validação roda DENTRO do retry de propósito: um payload fora do schema é
+  // marcado como transitório, e repetir a mesma requisição costuma resolver.
+  const { value, usage } = await withRetry(`Geração estruturada via ${ai.provider}`, async () => {
+    const res = ai.provider === 'openrouter'
+      ? await generateWithOpenRouter(systemPrompt, userContent, ai, callOpts)
+      : await generateWithAnthropic(systemPrompt, userContent, ai, callOpts);
+    return { value: schema.validate ? schema.validate(res.json) : res.json, usage: res.usage };
+  }, opts.retry);
+
+  recordUsageEntry(opts, ai, usage);
+
+  return opts.withReport
+    ? { value, model: ai.model, provider: ai.provider, modelSource: ai.modelSource }
+    : value;
+}
+
 // Remove blocos de raciocínio que alguns modelos (ex.: deepseek-r1) embutem no
 // content. A OpenRouter normalmente separa em `reasoning`, mas isto é uma rede
 // de segurança caso o <think> venha junto do conteúdo final.
@@ -299,7 +506,9 @@ export function extractOpenRouterUsage(usage) {
   };
 }
 
-async function generateWithAnthropic(systemPrompt, userContent, ai, { temperature, maxTokens }) {
+async function generateWithAnthropic(
+  systemPrompt, userContent, ai, { temperature, maxTokens, schema, strict }
+) {
   const apiKey = process.env.ANTHROPIC_API_KEY;
   if (!apiKey) {
     throw new Error(
@@ -309,15 +518,9 @@ async function generateWithAnthropic(systemPrompt, userContent, ai, { temperatur
   }
 
   const client = new Anthropic({ apiKey });
-  const message = await client.messages.create({
-    model: ai.model,
-    max_tokens: maxTokens,
-    // Omitida nos modelos que removeram sampling (Opus 4.7+, Sonnet 5, Fable 5):
-    // enviá-la devolve 400.
-    ...(temperature === undefined ? {} : { temperature }),
-    messages: [{ role: 'user', content: userContent }],
-    system: systemPrompt,
-  });
+  const message = await client.messages.create(buildAnthropicRequest({
+    ai, systemPrompt, userContent, temperature, maxTokens, schema, strict,
+  }));
 
   // A resposta nem sempre começa com um bloco de texto (recusa, resposta vazia):
   // `content[0].text` cru virava TypeError com mensagem inútil.
@@ -325,6 +528,10 @@ async function generateWithAnthropic(systemPrompt, userContent, ai, { temperatur
     .filter((block) => block.type === 'text')
     .map((block) => block.text)
     .join('');
+  // Com tool_choice forçado a resposta traz um bloco tool_use e NENHUM bloco de
+  // texto — daí a necessidade do branch dedicado antes da checagem de texto vazio.
+  const tool = (message.content || [])
+    .find((block) => block.type === 'tool_use' && block.name === schema?.name);
 
   if (message.stop_reason === 'refusal') {
     throw new Error(
@@ -347,9 +554,31 @@ async function generateWithAnthropic(systemPrompt, userContent, ai, { temperatur
       model: ai.model,
       maxTokens,
       reason: message.stop_reason,
-      chars: text.length,
+      // Sob tool call forçado não há bloco de texto: medir `text.length` diria
+      // sempre "~0 caracteres antes do corte".
+      chars: schema ? JSON.stringify(tool?.input ?? '').length : text.length,
     });
   }
+
+  // ATENÇÃO: este branch precisa vir ANTES da checagem de `!text` — uma resposta
+  // com tool call forçado não tem bloco de texto, e cair no `!text` faria toda
+  // crítica queimar os 3 retries com a mensagem errada.
+  if (schema) {
+    if (!tool || typeof tool.input !== 'object' || tool.input === null) {
+      const err = new Error(
+        `A Anthropic não devolveu a ferramenta \`${schema.name}\` ` +
+        `(stop_reason=${message.stop_reason}). Conteúdo: ${text.slice(0, 200) || '(vazio)'}`
+      );
+      err.transient = true; // ferramenta forçada: repetir a requisição costuma resolver
+      throw err;
+    }
+    return {
+      text: JSON.stringify(tool.input),
+      json: tool.input,
+      usage: extractAnthropicUsage(message.usage),
+    };
+  }
+
   if (!text) {
     const err = new Error(
       `A Anthropic retornou resposta sem texto (stop_reason=${message.stop_reason}).`
@@ -361,7 +590,9 @@ async function generateWithAnthropic(systemPrompt, userContent, ai, { temperatur
   return { text, usage: extractAnthropicUsage(message.usage) };
 }
 
-async function generateWithOpenRouter(systemPrompt, userContent, ai, { temperature, maxTokens }) {
+async function generateWithOpenRouter(
+  systemPrompt, userContent, ai, { temperature, maxTokens, schema }
+) {
   const apiKey = process.env.OPENROUTER_API_KEY;
   if (!apiKey) {
     throw new Error(
@@ -378,23 +609,22 @@ async function generateWithOpenRouter(systemPrompt, userContent, ai, { temperatu
       'HTTP-Referer': 'https://github.com/moacsjr/spec-wave',
       'X-Title': 'spec-wave',
     },
-    body: JSON.stringify({
-      model: ai.model,
-      max_tokens: maxTokens,
-      // Omitida nos modelos que removeram sampling (Opus 4.7+, Sonnet 5, Fable 5).
-      ...(temperature === undefined ? {} : { temperature }),
-      messages: [
-        { role: 'system', content: systemPrompt },
-        { role: 'user', content: userContent },
-      ],
-      // Pede o bloco `usage` completo na resposta (inclui `cost` em USD).
-      usage: { include: true },
-    }),
+    body: JSON.stringify(buildOpenRouterBody({
+      ai, systemPrompt, userContent, temperature, maxTokens, schema,
+    })),
   });
 
   if (!res.ok) {
     const body = await res.text();
-    const err = new Error(`OpenRouter API ${res.status}: ${body}`);
+    const err = new Error(
+      `OpenRouter API ${res.status}: ${body}` +
+      // require_parameters faz o roteador recusar quando nenhum provedor do modelo
+      // implementa response_format — erro de CONFIGURAÇÃO, não de rede.
+      (schema && (res.status === 404 || res.status === 400)
+        ? `\nNenhum provedor de ${ai.model} suporta response_format/json_schema. ` +
+          'Aponte `ai.models.critique` no .spec-wave.json para um modelo com saída estruturada.'
+        : '')
+    );
     err.status = res.status;
     throw err;
   }
@@ -437,5 +667,20 @@ async function generateWithOpenRouter(systemPrompt, userContent, ai, { temperatu
     err.transient = true;
     throw err;
   }
+
+  if (schema) {
+    const raw = stripOuterFence(content);
+    try {
+      return { text: raw, json: JSON.parse(raw), usage: extractOpenRouterUsage(data.usage) };
+    } catch {
+      const err = new Error(
+        `O modelo ${ai.model} ignorou response_format e devolveu texto não-JSON ` +
+        `(${raw.length} bytes): ${raw.slice(0, 200)}`
+      );
+      err.transient = true; // ≠ truncamento: repetir pode dar certo
+      throw err;
+    }
+  }
+
   return { text: content, usage: extractOpenRouterUsage(data.usage) };
 }