@hed-hog/core 0.0.399 → 0.0.401

package/src/ai/ai.service.ts

@@ -17,6 +17,7 @@ import {
   AiPromptResolverService,
   applyGeminiModelParams,
   applyOpenAiModelParams,
+  applyOpenAiResponsesParams,
   mergeModelParams,
   type PromptSource,
 } from '../ai-instruction/ai-prompt-resolver.service';
@@ -29,6 +30,7 @@ import {
   DEEPSEEK_DEFAULT_MODEL,
 } from '../integration-profile/integration-profile.utils';
 import { SettingService } from '../setting/setting.service';
+import { AI_AGENT_SORT } from './ai-agent.sort';
 import {
   attachedFileBlock,
   binaryAttachmentMarker,
@@ -96,6 +98,56 @@ type AiAttachment = {
   buffer: Buffer;
 };
 
+/**
+ * Como o anexo efetivamente chegou ao modelo na última chamada.
+ *
+ * Sem isso quem chama só consegue adivinhar — foi exatamente o que o extrator
+ * de notas fiscais fazia, deduzindo pelo tamanho do texto do PDF, e por isso
+ * insistia em reperguntar ao modelo sobre um anexo que ele nunca recebeu.
+ * `unreadable-pdf` e `binary` são os dois casos em que o modelo recebeu um
+ * marcador no lugar do documento.
+ */
+export type AiAttachmentDelivery =
+  | 'none'
+  | 'image'
+  | 'pdf-document'
+  | 'pdf-text'
+  | 'text'
+  | 'unreadable-pdf'
+  | 'binary';
+
+/** Anexo que o modelo realmente leu, em vez de um marcador dizendo que não deu. */
+const DELIVERED_TO_MODEL: ReadonlySet<AiAttachmentDelivery> = new Set([
+  'image',
+  'pdf-document',
+  'pdf-text',
+  'text',
+]);
+
+/** Entregas em que o modelo enxergou os pixels da página, não só texto. */
+const DELIVERED_AS_PIXELS: ReadonlySet<AiAttachmentDelivery> = new Set([
+  'image',
+  'pdf-document',
+]);
+
+export function isAttachmentDeliveredToModel(
+  delivery?: AiAttachmentDelivery | null,
+): boolean {
+  return !!delivery && DELIVERED_TO_MODEL.has(delivery);
+}
+
+export function isAttachmentDeliveredAsPixels(
+  delivery?: AiAttachmentDelivery | null,
+): boolean {
+  return !!delivery && DELIVERED_AS_PIXELS.has(delivery);
+}
+
+type AiChatResult = {
+  content: string;
+  usage?: { input: number; output: number; total: number; cached?: number };
+  delivery?: AiAttachmentDelivery;
+};
+
 type AiProfileCredentials = {
   apiKey: string;
   organization?: string;
@@ -104,6 +156,29 @@ type AiProfileCredentials = {
   baseUrl?: string;
 };
 
+/**
+ * O setting de um provider aponta para o perfil de outro provider.
+ *
+ * Classe própria, e não um `BadRequestException` solto, para uma escada de
+ * fallback conseguir parar antes de disparar chamadas que vão dar 4xx com
+ * certeza — era o que o extrator de notas fiscais fazia oito vezes por upload,
+ * engolindo cada uma delas.
+ */
+export class AiProfileProviderMismatchError extends BadRequestException {
+  constructor(
+    readonly requestedProvider: string,
+    readonly profileSlug: string,
+    readonly profileProviderSlug: string,
+    readonly settingSlug: string,
+  ) {
+    super(
+      `AI profile "${profileSlug}" (setting "${settingSlug}") belongs to provider ` +
+        `"${profileProviderSlug}", not "${requestedProvider}". ` +
+        `Point Settings → AI → "${settingSlug}" at a ${requestedProvider} profile, or leave it empty.`,
+    );
+  }
+}
+
 @Injectable()
 export class AiService implements OnModuleInit {
   private readonly logger = new Logger(AiService.name);
@@ -147,7 +222,7 @@ export class AiService implements OnModuleInit {
     const stepStart = Date.now();
 
     try {
-      const { content, usage } = await this.withTimeout(
+      const { content, usage, delivery } = await this.withTimeout(
         this.chatWithProvider(provider, {
           message: data.message,
           model,
@@ -156,6 +231,7 @@ export class AiService implements OnModuleInit {
           apiKey: aiProfile.apiKey,
           baseUrl: aiProfile.baseUrl,
           params,
+          timeoutMs,
         }),
         timeoutMs,
       );
@@ -172,7 +248,12 @@ export class AiService implements OnModuleInit {
       });
       await this.aiExecution.finish(executionId, 'completed');
 
-      return { provider, model, content };
+      return {
+        provider,
+        model,
+        content,
+        attachmentDelivery: delivery ?? 'none',
+      };
     } catch (err) {
       await this.aiExecution.finish(executionId, 'failed', String(err));
       throw err;
@@ -200,6 +281,15 @@ export class AiService implements OnModuleInit {
      * sistema. Mesmo padrão que `sendTemplatedMail` já usa para e-mail.
      */
     profileSlug?: string;
+    /**
+     * Modelo a usar, no lugar do que o perfil define.
+     *
+     * Existe para o chamador que tem a própria configuração de modelo — o SAC
+     * lê `sac.ai.model` do operador e não tinha por onde entregá-la. Vence a
+     * linha de `ai_instruction` e o perfil, na precedência que
+     * `mergeModelParams` documenta: argumento explícito primeiro.
+     */
+    model?: string;
     params?: AiChatModelParams;
     contextSlug?: string;
   }): Promise<{
@@ -207,6 +297,14 @@ export class AiService implements OnModuleInit {
     model: string;
     content: string;
     promptSources: Record<string, PromptSource>;
+    /**
+     * Linha de `ai_execution` desta chamada, onde o custo estimado é registrado.
+     *
+     * `null` quando o registro não pôde ser aberto: `AiExecutionService.start`
+     * devolve `0` nesse caso, e quem grava esse id numa coluna própria estaria
+     * apontando para uma execução que não existe.
+     */
+    executionId: number | null;
   }> {
     const slugs = input.systemPromptSlug
       ? [input.systemPromptSlug, input.userPromptSlug]
@@ -233,7 +331,10 @@ export class AiService implements OnModuleInit {
     const provider = target.provider;
     const aiProfile = target.profile;
     const model =
-      stored.model || aiProfile.model || this.getDefaultModel(provider);
+      input.model?.trim() ||
+      stored.model ||
+      aiProfile.model ||
+      this.getDefaultModel(provider);
     const timeoutMs = aiProfile.timeoutMs ?? DEFAULT_AI_CALL_TIMEOUT_MS;
 
     const params: AiChatModelParams = {
@@ -277,32 +378,44 @@ export class AiService implements OnModuleInit {
         Object.entries(resolved).map(([slug, prompt]) => [slug, prompt.source]),
       );
 
-      return { provider, model, content, promptSources };
+      // `executionId || null`: `start` devolve 0 quando não conseguiu abrir a
+      // linha, e quem guarda esse id (o SAC, em `ai_execution_id`) ficaria
+      // apontando para uma execução inexistente — a coluna não tem FK para
+      // barrar isso.
+      return { provider, model, content, promptSources, executionId: executionId || null };
     } catch (err) {
       await this.aiExecution.finish(executionId, 'failed', String(err));
       throw err;
     }
   }
 
+  /**
+   * `external_agent_id` nasce nulo: a Assistants API da OpenAI, que devolvia o
+   * `asst_...` guardado nessa coluna, foi desligada em 26/08/2026 e todo
+   * `POST /v1/assistants` passou a responder 404. As instruções do agente viram
+   * system prompt do `chat/completions` em `chatWithAgent`, então elas precisam
+   * estar na linha — daí resolver aqui a instrução padrão que antes ia embutida
+   * no assistant remoto, em vez de deixar o agente sem prompt nenhum.
+   */
   async createAgent(data: CreateAgentDTO) {
     const slug = data.slug.trim();
     const provider = data.provider || 'openai';
     const model = data.model || this.getDefaultModel(provider);
-    const instructions = data.instructions?.trim() || null;
 
     const existing = await this.findAgentBySlug(slug);
     if (existing) {
       return existing;
     }
 
-    let externalAgentId: string | null = null;
+    let instructions = data.instructions?.trim() || null;
 
-    if (provider === 'openai') {
-      externalAgentId = await this.createOpenAiAssistant({
-        slug,
-        model,
-        instructions,
+    if (!instructions) {
+      const defaultInstructions = await this.promptResolver.resolve({
+        slug: CORE_AI_PROMPT_SLUGS.agentDefaultInstructions,
+        variables: { slug },
       });
+
+      instructions = defaultInstructions.content;
     }
 
     await this.prismaService.$executeRaw`
@@ -312,7 +425,7 @@ export class AiService implements OnModuleInit {
         CAST(${provider} AS ai_agent_provider_7cb93b1143_enum),
         ${model},
         ${instructions},
-        ${externalAgentId}
+        NULL
       )
     `;
 
@@ -358,29 +471,22 @@ export class AiService implements OnModuleInit {
       Math.max(Number(paginationParams?.pageSize || 10), 1),
       100,
     );
-    const offset = (page - 1) * pageSize;
+    const skip = (page - 1) * pageSize;
     const search = String(paginationParams?.search || '').trim();
 
-    const whereClause = search
-      ? Prisma.sql`WHERE LOWER(slug) LIKE LOWER(${`%${search}%`})`
-      : Prisma.empty;
-
-    const data = await this.prismaService.$queryRaw<AiAgentRecord[]>(Prisma.sql`
-      SELECT id, slug, provider, model, instructions, external_agent_id, created_at, updated_at
-      FROM ai_agent
-      ${whereClause}
-      ORDER BY id DESC
-      LIMIT ${pageSize}
-      OFFSET ${offset}
-    `);
-
-    const totalResult = await this.prismaService.$queryRaw<Array<{ total: bigint | number | string }>>(Prisma.sql`
-      SELECT COUNT(*) AS total
-      FROM ai_agent
-      ${whereClause}
-    `);
+    const where: Prisma.ai_agentWhereInput = search
+      ? { slug: { contains: search, mode: 'insensitive' } }
+      : {};
 
-    const total = Number(totalResult?.[0]?.total || 0);
+    const [data, total] = await Promise.all([
+      this.prismaService.ai_agent.findMany({
+        where,
+        orderBy: AI_AGENT_SORT.toPrismaOrderBy(paginationParams),
+        skip,
+        take: pageSize,
+      }),
+      this.prismaService.ai_agent.count({ where }),
+    ]);
 
     return {
       data,
@@ -420,25 +526,15 @@ export class AiService implements OnModuleInit {
       }
     }
 
-    let externalAgentId = currentAgent.external_agent_id;
-
-    if (provider !== 'openai') {
-      externalAgentId = null;
-    } else if (!externalAgentId) {
-      externalAgentId = await this.createOpenAiAssistant({
-        slug,
-        model,
-        instructions,
-      });
-    }
-
+    // Zera o `asst_...` legado: a coluna deixou de ser alimentada quando a
+    // Assistants API foi desligada, e valor antigo aqui não tem mais para onde ir.
     await this.prismaService.$executeRaw`
       UPDATE ai_agent
       SET slug = ${slug},
           provider = CAST(${provider} AS ai_agent_provider_7cb93b1143_enum),
           model = ${model},
           instructions = ${instructions},
-          external_agent_id = ${externalAgentId},
+          external_agent_id = NULL,
           updated_at = NOW()
       WHERE id = ${agentId}
     `;
@@ -479,36 +575,36 @@ export class AiService implements OnModuleInit {
       throw new NotFoundException(`AI agent with slug "${slug}" was not found.`);
     }
 
-    if (agent.provider === 'openai' && agent.external_agent_id && !attachment) {
-      const content = await this.chatWithOpenAiAssistant(
-        agent.external_agent_id,
-        data.message,
-      );
-
-      return {
-        slug: agent.slug,
-        provider: agent.provider,
-        model: agent.model,
-        content,
-      };
-    }
-
+    // Um único caminho para todo agente, com ou sem anexo: as instruções da
+    // linha viram system prompt do provider. Até 26/08/2026 o agente da OpenAI
+    // com `external_agent_id` e sem anexo era atendido por thread + run da
+    // Assistants API — que a OpenAI desligou, e que já ignorava model e
+    // instructions do banco porque só mandava o `assistant_id`.
     const aiProfile = await this.getAiProfile(agent.provider);
+    const timeoutMs = aiProfile.timeoutMs ?? DEFAULT_AI_CALL_TIMEOUT_MS;
 
-    const { content } = await this.chatWithProvider(agent.provider, {
-      message: data.message,
-      model: agent.model || this.getDefaultModel(agent.provider),
-      systemPrompt: agent.instructions || undefined,
-      attachment,
-      apiKey: aiProfile.apiKey,
-      baseUrl: aiProfile.baseUrl,
-    });
+    // Sem o `withTimeout` este era o único ponto público sem prazo nenhum: uma
+    // chamada travada no provider segurava a requisição HTTP de quem chamou
+    // indefinidamente.
+    const { content, delivery } = await this.withTimeout(
+      this.chatWithProvider(agent.provider, {
+        message: data.message,
+        model: agent.model || this.getDefaultModel(agent.provider),
+        systemPrompt: agent.instructions || undefined,
+        attachment,
+        apiKey: aiProfile.apiKey,
+        baseUrl: aiProfile.baseUrl,
+        timeoutMs,
+      }),
+      timeoutMs,
+    );
 
     return {
       slug: agent.slug,
       provider: agent.provider,
       model: agent.model,
       content,
+      attachmentDelivery: delivery ?? 'none',
     };
   }
 
@@ -580,7 +676,7 @@ export class AiService implements OnModuleInit {
       sha256: createHash('sha256').update(attachment.buffer).digest('hex'),
     };
 
-    this.logger.warn(
+    this.logger.debug(
       `[AI-ATTACHMENT-DEBUG] fileId=${fileId || 'upload'} filename="${result.filename}" mime=${result.mimeType} mode=${result.mode} bytes=${result.bytes} textLength=${result.textLength}`,
     );
 
@@ -649,8 +745,9 @@ export class AiService implements OnModuleInit {
       apiKey?: string;
       baseUrl?: string;
       params?: AiChatModelParams;
+      timeoutMs?: number;
     },
-  ) {
+  ): Promise<AiChatResult> {
     if (provider === 'gemini') {
       return this.chatWithGemini(input);
     }
@@ -721,7 +818,49 @@ export class AiService implements OnModuleInit {
       );
     }
 
-    return (await this.loadAiProfileBySlug(profileSlug)).config;
+    const loaded = await this.loadAiProfileBySlug(profileSlug);
+    const mapped = PROVIDER_BY_INTEGRATION_SLUG[loaded.providerSlug];
+
+    // `resolveProviderAndProfile` já protegia o caminho do perfil explícito
+    // ("pedir openai e apontar um perfil Claude bateria na API errada com a
+    // chave errada"); o caminho do setting global ficara de fora. Sem isso, um
+    // perfil OpenAI no campo do Gemini fazia o serviço postar a chave da OpenAI
+    // no endpoint do Google e engolir o 4xx de cada modelo tentado.
+    if (mapped !== provider) {
+      this.logger.error(
+        `[AI-PROFILE] "${slug}" = "${profileSlug}" é um perfil ${loaded.providerSlug}, ` +
+          `mas ${provider} foi pedido.`,
+      );
+      throw new AiProfileProviderMismatchError(
+        provider,
+        profileSlug,
+        loaded.providerSlug,
+        slug,
+      );
+    }
+
+    return loaded.config;
+  }
+
+  /**
+   * "Este provider dá para usar?", sem lançar.
+   *
+   * Existe para uma escada de fallback perguntar antes de tentar, em vez de
+   * gastar uma requisição HTTP por modelo só para descobrir que a credencial
+   * nem é daquele provider.
+   */
+  async isProviderConfigured(
+    provider: AiProvider,
+  ): Promise<{ ok: boolean; reason?: string }> {
+    try {
+      await this.getAiProfile(provider);
+      return { ok: true };
+    } catch (error) {
+      return {
+        ok: false,
+        reason: error instanceof Error ? error.message : String(error),
+      };
+    }
   }
 
   private async loadAiProfileBySlug(profileSlug: string): Promise<{
@@ -776,6 +915,7 @@ export class AiService implements OnModuleInit {
     provider = 'openai',
     baseUrl = 'https://api.openai.com/v1',
     supportsImages = true,
+    timeoutMs,
   }: {
     message: string;
     model: string;
@@ -787,16 +927,44 @@ export class AiService implements OnModuleInit {
     provider?: AiProvider;
     baseUrl?: string;
     supportsImages?: boolean;
-  }): Promise<{ content: string; usage?: { input: number; output: number; total: number } }> {
+    timeoutMs?: number;
+  }): Promise<AiChatResult> {
     const openai = apiKey ?? (await this.getAiApiKey(provider));
 
+    if (this.shouldUseOpenAiResponses({ provider, baseUrl, model, attachment })) {
+      try {
+        return await this.chatWithOpenAiResponses({
+          message,
+          model,
+          systemPrompt,
+          attachment: attachment!,
+          apiKey: openai,
+          baseUrl,
+          params,
+          timeoutMs,
+        });
+      } catch (error) {
+        const status = Number((error as any)?.response?.status);
+        // 400/404/422 = este modelo ou esta conta não aceita `input_file`;
+        // cair para o chat/completions é melhor que falhar. Qualquer outra
+        // coisa (401, 429, 5xx, timeout) é falha de verdade e não pode ser
+        // mascarada por uma segunda chamada mais fraca, que só reproduziria o
+        // marcador de PDF ilegível e devolveria "não achei nada".
+        if (![400, 404, 422].includes(status)) throw error;
+        this.logger.warn(
+          `[AI-RESPONSES] /v1/responses recusou (status=${status}); usando chat/completions. ` +
+            `apiError=${(error as any)?.response?.data?.error?.message ?? 'n/a'}`,
+        );
+      }
+    }
+
     const messages: Array<any> = [];
 
     if (systemPrompt) {
       messages.push({ role: 'system', content: systemPrompt });
     }
 
-    const userContent = await this.buildOpenAiUserContent(
+    const { content: userContent, delivery } = await this.buildOpenAiUserContent(
       message,
       attachment,
       supportsImages,
@@ -823,10 +991,200 @@ export class AiService implements OnModuleInit {
     const u = response.data?.usage;
     return {
       content: response.data?.choices?.[0]?.message?.content || '',
+      delivery,
       usage: u ? { input: u.prompt_tokens ?? 0, output: u.completion_tokens ?? 0, total: u.total_tokens ?? 0 } : undefined,
     };
   }
 
+  /**
+   * Bytes crus de PDF acima disto não vão inline: base64 infla ~1,37x e a
+   * OpenAI limita a requisição a 50 MB.
+   */
+  private static readonly OPENAI_RESPONSES_MAX_PDF_BYTES = 20 * 1024 * 1024;
+
+  /** Acima disto a conta de tokens das páginas renderizadas deixa de compensar. */
+  private static readonly OPENAI_RESPONSES_MAX_PDF_PAGES = 20;
+
+  /**
+   * Modelos que renderizam as páginas do PDF como imagem na Responses API.
+   *
+   * Um modelo sem visão recebendo `input_file` só recebe a camada de texto de
+   * volta — o mesmo nada do chat/completions, num endpoint diferente. Deixá-lo
+   * no caminho antigo mantém a falha conhecida em vez de criar uma nova.
+   */
+  private static readonly OPENAI_DOCUMENT_MODEL_RE =
+    /^(gpt-4o|gpt-4\.1|gpt-4-turbo|gpt-5|o3|o4)/i;
+
+  private shouldUseOpenAiResponses(input: {
+    provider: AiProvider;
+    baseUrl: string;
+    model: string;
+    attachment?: AiAttachment | null;
+  }): boolean {
+    // O DeepSeek reusa o formato da OpenAI, mas não tem /v1/responses; e um
+    // gateway apontado por `base_url` pode simplesmente não repassar a rota.
+    if (input.provider !== 'openai') return false;
+    if (!input.baseUrl.startsWith('https://api.openai.com')) return false;
+    if (!input.attachment) return false;
+    // Imagem já funciona pelo bloco de visão do chat/completions.
+    if (!this.isPdfMime(input.attachment.mimeType)) return false;
+    if (
+      input.attachment.buffer.length > AiService.OPENAI_RESPONSES_MAX_PDF_BYTES
+    ) {
+      return false;
+    }
+    return AiService.OPENAI_DOCUMENT_MODEL_RE.test(input.model);
+  }
+
+  private buildOpenAiResponsesBody(input: {
+    message: string;
+    model: string;
+    systemPrompt?: string;
+    attachment: AiAttachment;
+    params?: AiChatModelParams;
+  }): Record<string, unknown> {
+    const base64 = input.attachment.buffer.toString('base64');
+
+    // Arquivo antes da instrução, como no exemplo da própria OpenAI: o modelo
+    // lê o documento antes de saber o que tirar dele.
+    const body: Record<string, unknown> = {
+      input: [
+        {
+          role: 'user',
+          content: [
+            {
+              type: 'input_file',
+              filename: input.attachment.filename,
+              file_data: `data:${input.attachment.mimeType};base64,${base64}`,
+            },
+            { type: 'input_text', text: input.message },
+          ],
+        },
+      ],
+    };
+
+    // `instructions` é o equivalente do `messages[0].role === 'system'`.
+    if (input.systemPrompt) body.instructions = input.systemPrompt;
+
+    return applyOpenAiResponsesParams(
+      body,
+      {
+        model: null,
+        temperature: input.params?.temperature ?? null,
+        maxTokens: input.params?.maxTokens ?? null,
+      },
+      {
+        model: input.model,
+        jsonObject: input.params?.responseFormat === 'json_object',
+      },
+    );
+  }
+
+  /**
+   * Texto da resposta da Responses API.
+   *
+   * `output_text` é conveniência do SDK — o JSON HTTP cru normalmente não traz.
+   * O texto mora no array `output`, ao lado de itens `reasoning` que não têm
+   * `content` nenhum. Percorrer o array é o caminho real; o atalho pelo
+   * `output_text` só vale para quando o campo por acaso estiver lá.
+   */
+  private readOpenAiResponsesText(data: any): string {
+    if (typeof data?.output_text === 'string' && data.output_text.trim()) {
+      return data.output_text;
+    }
+
+    const output: any[] = Array.isArray(data?.output) ? data.output : [];
+    const chunks: string[] = [];
+
+    for (const item of output) {
+      if (item?.type && item.type !== 'message') continue;
+      for (const part of item?.content ?? []) {
+        if (part?.type === 'output_text' && typeof part.text === 'string') {
+          chunks.push(part.text);
+        } else if (part?.type === 'refusal' && typeof part.refusal === 'string') {
+          this.logger.warn(
+            `[AI-RESPONSES] modelo recusou: ${part.refusal.slice(0, 200)}`,
+          );
+        }
+      }
+    }
+
+    return chunks.join('');
+  }
+
+  /**
+   * PDF como documento, via `POST /v1/responses`.
+   *
+   * É o único caminho em que um PDF escaneado chega ao modelo: para modelos com
+   * visão a API extrai o texto e renderiza cada página como imagem. O
+   * chat/completions, mesmo aceitando um content part de PDF, só extrai texto —
+   * não serviria para um scan.
+   */
+  private async chatWithOpenAiResponses(input: {
+    message: string;
+    model: string;
+    systemPrompt?: string;
+    attachment: AiAttachment;
+    apiKey: string;
+    baseUrl: string;
+    params?: AiChatModelParams;
+    timeoutMs?: number;
+  }): Promise<AiChatResult> {
+    const pages = await this.countPdfPages(input.attachment.buffer);
+
+    if (pages > AiService.OPENAI_RESPONSES_MAX_PDF_PAGES) {
+      this.logger.warn(
+        `[AI-RESPONSES] "${input.attachment.filename}" tem ${pages} páginas ` +
+          `(máx. ${AiService.OPENAI_RESPONSES_MAX_PDF_PAGES}); usando chat/completions.`,
+      );
+      // 422 é o status que o chamador trata como "degrade", e não como falha.
+      throw Object.assign(new Error('PDF acima do limite de páginas'), {
+        response: { status: 422, data: { error: { message: 'too many pages' } } },
+      });
+    }
+
+    const response = await axios.post(
+      `${input.baseUrl.replace(/\/+$/, '')}/responses`,
+      this.buildOpenAiResponsesBody(input),
+      {
+        headers: {
+          Authorization: `Bearer ${input.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        // O corpo é o PDF em base64, na casa dos megabytes, e a renderização
+        // das páginas é lenta: com os padrões do axios isso trunca ou trava.
+        timeout: input.timeoutMs ?? DEFAULT_AI_CALL_TIMEOUT_MS,
+        maxBodyLength: Infinity,
+        maxContentLength: Infinity,
+      },
+    );
+
+    if (response.data?.status && response.data.status !== 'completed') {
+      this.logger.warn(
+        `[AI-RESPONSES] status=${response.data.status} ` +
+          `reason=${response.data?.incomplete_details?.reason ?? 'n/a'} ` +
+          `model=${input.model} file="${input.attachment.filename}"`,
+      );
+    }
+
+    const u = response.data?.usage;
+    return {
+      content: this.readOpenAiResponsesText(response.data),
+      delivery: 'pdf-document',
+      usage: u
+        ? {
+            input: u.input_tokens ?? 0,
+            output: u.output_tokens ?? 0,
+            total:
+              u.total_tokens ?? (u.input_tokens ?? 0) + (u.output_tokens ?? 0),
+            ...(u.input_tokens_details?.cached_tokens
+              ? { cached: u.input_tokens_details.cached_tokens }
+              : {}),
+          }
+        : undefined,
+    };
+  }
+
   /**
    * Anthropic (Claude).
    *
@@ -851,7 +1209,7 @@ export class AiService implements OnModuleInit {
     systemPrompt?: string;
     apiKey?: string;
     params?: AiChatModelParams;
-  }): Promise<{ content: string; usage?: { input: number; output: number; total: number } }> {
+  }): Promise<AiChatResult> {
     const key = apiKey ?? (await this.getAiApiKey('claude'));
 
     const body: Record<string, unknown> = {
@@ -887,138 +1245,6 @@ export class AiService implements OnModuleInit {
     };
   }
 
-  private async createOpenAiAssistant({
-    slug,
-    model,
-    instructions,
-  }: {
-    slug: string;
-    model: string;
-    instructions: string | null;
-  }): Promise<string> {
-    const openai = await this.getAiApiKey('openai');
-
-    const defaultInstructions = await this.promptResolver.resolve({
-      slug: CORE_AI_PROMPT_SLUGS.agentDefaultInstructions,
-      variables: { slug },
-    });
-
-    const response = await axios.post(
-      'https://api.openai.com/v1/assistants',
-      {
-        name: slug,
-        model,
-        instructions: instructions || defaultInstructions.content,
-      },
-      {
-        headers: {
-          Authorization: `Bearer ${openai}`,
-          'Content-Type': 'application/json',
-          'OpenAI-Beta': 'assistants=v2',
-        },
-      },
-    );
-
-    const assistantId = response.data?.id;
-
-    if (!assistantId) {
-      throw new BadRequestException('OpenAI assistant creation failed.');
-    }
-
-    return assistantId;
-  }
-
-  private async chatWithOpenAiAssistant(
-    assistantId: string,
-    message: string,
-  ): Promise<string> {
-    const openai = await this.getAiApiKey('openai');
-
-    const threadResponse = await axios.post(
-      'https://api.openai.com/v1/threads',
-      {
-        messages: [{ role: 'user', content: message }],
-      },
-      {
-        headers: {
-          Authorization: `Bearer ${openai}`,
-          'Content-Type': 'application/json',
-          'OpenAI-Beta': 'assistants=v2',
-        },
-      },
-    );
-
-    const threadId = threadResponse.data?.id;
-
-    if (!threadId) {
-      throw new BadRequestException('OpenAI thread creation failed.');
-    }
-
-    const runResponse = await axios.post(
-      `https://api.openai.com/v1/threads/${threadId}/runs`,
-      {
-        assistant_id: assistantId,
-      },
-      {
-        headers: {
-          Authorization: `Bearer ${openai}`,
-          'Content-Type': 'application/json',
-          'OpenAI-Beta': 'assistants=v2',
-        },
-      },
-    );
-
-    const runId = runResponse.data?.id;
-
-    if (!runId) {
-      throw new BadRequestException('OpenAI assistant run failed to start.');
-    }
-
-    for (let i = 0; i < 30; i++) {
-      const runStatusResponse = await axios.get(
-        `https://api.openai.com/v1/threads/${threadId}/runs/${runId}`,
-        {
-          headers: {
-            Authorization: `Bearer ${openai}`,
-            'OpenAI-Beta': 'assistants=v2',
-          },
-        },
-      );
-
-      const status = runStatusResponse.data?.status;
-
-      if (status === 'completed') {
-        break;
-      }
-
-      if (['cancelled', 'failed', 'expired'].includes(status)) {
-        throw new BadRequestException(
-          `OpenAI assistant run did not complete successfully (status: ${status}).`,
-        );
-      }
-
-      await this.sleep(1000);
-    }
-
-    const messagesResponse = await axios.get(
-      `https://api.openai.com/v1/threads/${threadId}/messages`,
-      {
-        headers: {
-          Authorization: `Bearer ${openai}`,
-          'OpenAI-Beta': 'assistants=v2',
-        },
-      },
-    );
-
-    const assistantMessage = messagesResponse.data?.data?.find(
-      (item: any) => item.role === 'assistant',
-    );
-
-    const output = assistantMessage?.content?.[0]?.text?.value;
-
-    return output || '';
-  }
-
   private async chatWithGemini({
     message,
     model,
@@ -1033,24 +1259,27 @@ export class AiService implements OnModuleInit {
     attachment?: AiAttachment | null;
     apiKey?: string;
     params?: AiChatModelParams;
-  }): Promise<{ content: string; usage?: { input: number; output: number; total: number } }> {
+  }): Promise<AiChatResult> {
     const gemini = apiKey ?? (await this.getAiApiKey('gemini'));
 
     const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${gemini}`;
 
     const userParts: any[] = [{ text: message }];
+    let delivery: AiAttachmentDelivery = 'none';
 
     if (attachment) {
       if (this.isTextMime(attachment.mimeType)) {
         userParts.push({
           text: attachedFileBlock(attachment.filename, this.toUtf8Text(attachment.buffer)),
         });
+        delivery = 'text';
       } else if (this.isPdfMime(attachment.mimeType)) {
         const pdfText = await this.extractPdfText(attachment.buffer);
         if (pdfText) {
           userParts.push({
             text: attachedFileBlock(attachment.filename, pdfText),
           });
+          delivery = 'pdf-text';
         } else {
           userParts.push({
             inline_data: {
@@ -1058,6 +1287,7 @@ export class AiService implements OnModuleInit {
               data: attachment.buffer.toString('base64'),
             },
           });
+          delivery = 'pdf-document';
         }
       } else {
         userParts.push({
@@ -1066,6 +1296,7 @@ export class AiService implements OnModuleInit {
             data: attachment.buffer.toString('base64'),
           },
         });
+        delivery = this.isImageMime(attachment.mimeType) ? 'image' : 'binary';
       }
     }
 
@@ -1096,14 +1327,11 @@ export class AiService implements OnModuleInit {
     const u = response.data?.usageMetadata;
     return {
       content,
+      delivery,
       usage: u ? { input: u.promptTokenCount ?? 0, output: u.candidatesTokenCount ?? 0, total: u.totalTokenCount ?? 0 } : undefined,
     };
   }
 
-  private async sleep(ms: number) {
-    await new Promise((resolve) => setTimeout(resolve, ms));
-  }
-
   private async resolveAttachment(
     uploadFile?: MulterFile,
     fileId?: number,
@@ -1136,40 +1364,56 @@ export class AiService implements OnModuleInit {
     return null;
   }
 
+  /**
+   * Conteúdo da mensagem do usuário no chat/completions, mais como o anexo foi
+   * parar lá dentro.
+   *
+   * O `delivery` sai daqui porque é aqui que a decisão acontece: um PDF sem
+   * camada de texto vira o marcador de ilegível, e só este método sabe disso.
+   */
   private async buildOpenAiUserContent(
     message: string,
     attachment?: AiAttachment | null,
     supportsImages = true,
-  ) {
+  ): Promise<{ content: unknown; delivery: AiAttachmentDelivery }> {
     if (!attachment) {
-      return message;
+      return { content: message, delivery: 'none' };
     }
 
     if (supportsImages && this.isImageMime(attachment.mimeType)) {
       const dataUri = `data:${attachment.mimeType};base64,${attachment.buffer.toString('base64')}`;
-      return [
-        { type: 'text', text: message },
-        { type: 'image_url', image_url: { url: dataUri } },
-      ];
+      return {
+        content: [
+          { type: 'text', text: message },
+          { type: 'image_url', image_url: { url: dataUri } },
+        ],
+        delivery: 'image',
+      };
     }
 
     let text: string;
+    let delivery: AiAttachmentDelivery;
 
     if (this.isTextMime(attachment.mimeType)) {
       text = this.toUtf8Text(attachment.buffer);
+      delivery = 'text';
     } else if (this.isPdfMime(attachment.mimeType)) {
-      text =
-        (await this.extractPdfText(attachment.buffer)) ||
-        unreadablePdfMarker(attachment.filename);
+      const pdfText = await this.extractPdfText(attachment.buffer);
+      text = pdfText || unreadablePdfMarker(attachment.filename);
+      delivery = pdfText ? 'pdf-text' : 'unreadable-pdf';
     } else {
       text = binaryAttachmentMarker(
         attachment.filename,
         attachment.mimeType,
         attachment.buffer.length,
       );
+      delivery = 'binary';
     }
 
-    return `${message}${attachedFileBlock(attachment.filename, text)}`;
+    return {
+      content: `${message}${attachedFileBlock(attachment.filename, text)}`,
+      delivery,
+    };
   }
 
   private isImageMime(mimeType: string) {
@@ -1229,6 +1473,15 @@ export class AiService implements OnModuleInit {
     }
   }
 
+  /** Páginas do PDF, ou 0 quando ele não abre — nesse caso o teto não barra. */
+  private async countPdfPages(buffer: Buffer): Promise<number> {
+    try {
+      return (await pdfParse(buffer))?.numpages ?? 0;
+    } catch {
+      return 0;
+    }
+  }
+
   private toUtf8Text(buffer: Buffer) {
     return buffer.toString('utf8');
   }