@hed-hog/core 0.0.398 → 0.0.400

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hed-hog/core",
-  "version": "0.0.398",
+  "version": "0.0.400",
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,6 +27,8 @@
     "@simplewebauthn/server": "^13.2.2",
     "argon2": "^0.44.0",
     "axios": "^1.9.0",
+    "class-transformer": "*",
+    "class-validator": "*",
     "cookie-parser": "^1.4.7",
     "geoip-lite": "^2.0.2",
     "handlebars": "^4.7.8",
@@ -45,13 +47,13 @@
     "speakeasy": "^2.0.0",
     "ua-parser-js": "^2.0.10",
     "uuid": "^11.1.0",
-    "@hed-hog/vault-crypto": "0.0.1",
-    "@hed-hog/api-pagination": "0.0.8",
     "@hed-hog/api-prisma": "0.0.7",
-    "@hed-hog/api": "0.0.9",
-    "@hed-hog/api-types": "0.0.2",
     "@hed-hog/api-locale": "0.0.15",
-    "@hed-hog/api-mail": "0.0.11"
+    "@hed-hog/api-mail": "0.0.11",
+    "@hed-hog/vault-crypto": "0.0.1",
+    "@hed-hog/api": "0.0.9",
+    "@hed-hog/api-pagination": "0.0.8",
+    "@hed-hog/api-types": "0.0.2"
   },
   "exports": {
     ".": {

package/src/ai/ai-agent.sort.ts

@@ -0,0 +1,21 @@
+import { defineSortable } from '@hed-hog/api-pagination';
+
+/**
+ * Campos ordenáveis de `ai_agent` (`AiService.listAgents`). Todas as colunas
+ * exibidas na tela são planas — sem relação envolvida.
+ */
+export const AI_AGENT_SORT = defineSortable(
+  {
+    slug: true,
+    provider: true,
+    model: true,
+    external_agent_id: true,
+    created_at: { initialOrder: 'desc' },
+    id: { initialOrder: 'desc' },
+  },
+  {
+    // Mesma ordem que estava fixa no `$queryRaw` (`ORDER BY id DESC`).
+    default: 'id',
+    defaultOrder: 'desc',
+  },
+);

package/src/ai/ai.service.spec.ts

@@ -14,6 +14,7 @@ const mockedAxios = axios as jest.Mocked<typeof axios>;
 describe('AiService — parâmetros de modelo', () => {
   let service: AiService;
   let promptResolver: { resolveMany: jest.Mock };
+  let aiExecution: any;
 
   const aiProfile = {
     apiKey: 'sk-test',
@@ -25,7 +26,7 @@ describe('AiService — parâmetros de modelo', () => {
     const prisma = {} as any;
     const settingService = { getSettingValues: jest.fn().mockResolvedValue({}) } as any;
     const fileService = {} as any;
-    const aiExecution = {
+    aiExecution = {
       start: jest.fn().mockResolvedValue(1),
       recordStep: jest.fn().mockResolvedValue(undefined),
       finish: jest.fn().mockResolvedValue(undefined),
@@ -276,5 +277,176 @@ describe('AiService — parâmetros de modelo', () => {
         response_format: { type: 'json_object' },
       });
     });
+
+    /** Prompt sem nenhum parâmetro gravado: o registro não opina no modelo. */
+    const promptSemParametros = () =>
+      promptResolver.resolveMany.mockResolvedValue({
+        'task.lms.quiz.generate.user': {
+          slug: 'task.lms.quiz.generate.user',
+          content: 'Gere 5 questões.',
+          source: 'fallback',
+          model: null,
+          temperature: null,
+          maxTokens: null,
+        },
+      });
+
+    it('o modelo pedido pelo chamador vence o do perfil', async () => {
+      // O SAC lê `sac.ai.model` do operador e não tinha por onde entregá-la:
+      // a setting era lida e descartada.
+      promptSemParametros();
+      (service as any).getAiProfile.mockResolvedValueOnce({
+        ...aiProfile,
+        model: 'gpt-4o-mini',
+      });
+
+      const result = await service.chatWithPrompt({
+        userPromptSlug: 'task.lms.quiz.generate.user',
+        provider: 'openai',
+        model: 'gpt-4o',
+      });
+
+      expect(result.model).toBe('gpt-4o');
+      expect(lastBody()).toMatchObject({ model: 'gpt-4o' });
+    });
+
+    it('e vence também o modelo gravado no registro do prompt', async () => {
+      // Precedência documentada em `mergeModelParams`: argumento explícito
+      // primeiro, depois a linha de `ai_instruction`, depois o perfil. Note que
+      // `temperature` e `maxTokens` seguem a ordem inversa nesta mesma função —
+      // ali o registro vence o chamador.
+      promptResolver.resolveMany.mockResolvedValue({
+        'task.lms.quiz.generate.user': {
+          slug: 'task.lms.quiz.generate.user',
+          content: 'Gere 5 questões.',
+          source: 'db',
+          model: 'gpt-4o',
+          temperature: null,
+          maxTokens: null,
+        },
+      });
+
+      const result = await service.chatWithPrompt({
+        userPromptSlug: 'task.lms.quiz.generate.user',
+        provider: 'openai',
+        model: 'gpt-3.5-turbo',
+      });
+
+      expect(result.model).toBe('gpt-3.5-turbo');
+    });
+
+    it('devolve a execução de IA, onde o custo da chamada é registrado', async () => {
+      promptSemParametros();
+
+      const result = await service.chatWithPrompt({
+        userPromptSlug: 'task.lms.quiz.generate.user',
+        provider: 'openai',
+      });
+
+      expect(result.executionId).toBe(1);
+    });
+
+    it('devolve null quando a execução não pôde ser aberta', async () => {
+      // `start` engole a falha e devolve 0; repassar esse 0 faria quem o grava
+      // apontar para uma execução que não existe.
+      promptSemParametros();
+      aiExecution.start.mockResolvedValueOnce(0);
+
+      const result = await service.chatWithPrompt({
+        userPromptSlug: 'task.lms.quiz.generate.user',
+        provider: 'openai',
+      });
+
+      expect(result.executionId).toBeNull();
+    });
+  });
+});
+
+/**
+ * A Assistants API (beta) da OpenAI foi desligada em 26/08/2026: `/v1/assistants`
+ * e `/v1/threads` passaram a responder 404, e o `createOpenAiAssistant` que o
+ * agente do financeiro disparava a cada extração derrubava a requisição com 500
+ * antes de qualquer leitura do arquivo. Estes testes guardam a ausência desse
+ * caminho — agente é linha no banco, e a conversa é sempre `chat/completions`.
+ */
+describe('AiService — agentes sem a Assistants API', () => {
+  let service: AiService;
+  let executeRaw: jest.Mock;
+
+  beforeEach(() => {
+    executeRaw = jest.fn().mockResolvedValue(1);
+    const prisma = { $executeRaw: executeRaw } as any;
+    const settingService = { getSettingValues: jest.fn().mockResolvedValue({}) } as any;
+    const aiExecution = {
+      start: jest.fn().mockResolvedValue(1),
+      recordStep: jest.fn().mockResolvedValue(undefined),
+      finish: jest.fn().mockResolvedValue(undefined),
+    } as any;
+    const promptResolver = {
+      resolve: jest
+        .fn()
+        .mockResolvedValue({ content: 'instrucao padrao do agente', source: 'db' }),
+    };
+
+    service = new AiService(prisma, settingService, {} as any, aiExecution, promptResolver as any);
+
+    jest.spyOn(service as any, 'getAiProfile').mockResolvedValue({ apiKey: 'sk-test' });
+    jest.spyOn(service as any, 'resolveAttachment').mockResolvedValue(null);
+
+    mockedAxios.post.mockResolvedValue({
+      data: { choices: [{ message: { content: 'ok' } }] },
+    } as any);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    mockedAxios.post.mockReset();
+  });
+
+  it('cria o agente sem assistant remoto, guardando a instrução padrão na linha', async () => {
+    const created = { id: 1, slug: 'finance-payable-extractor' };
+    jest
+      .spyOn(service as any, 'findAgentBySlug')
+      .mockResolvedValueOnce(null)
+      .mockResolvedValueOnce(created);
+
+    const agent = await service.createAgent({
+      slug: 'finance-payable-extractor',
+      provider: 'openai',
+    } as any);
+
+    expect(mockedAxios.post).not.toHaveBeenCalled();
+    expect(agent).toBe(created);
+
+    const [sql, ...values] = executeRaw.mock.calls[0];
+    // A instrução padrão precisa ficar na linha: sem assistant remoto para
+    // guardá-la, ela é o único system prompt que o agente terá.
+    expect(values).toContain('instrucao padrao do agente');
+    expect(sql.join('?')).toContain('NULL');
+  });
+
+  it('conversa por chat/completions mesmo com external_agent_id legado e sem anexo', async () => {
+    jest.spyOn(service as any, 'findAgentBySlug').mockResolvedValue({
+      id: 1,
+      slug: 'finance-payable-extractor',
+      provider: 'openai',
+      model: 'gpt-4o',
+      instructions: 'extraia os dados do título',
+      external_agent_id: 'asst_legado',
+    });
+
+    const result = await service.chatWithAgent('finance-payable-extractor', {
+      message: 'oi',
+    } as any);
+
+    expect(mockedAxios.post).toHaveBeenCalledTimes(1);
+    expect(mockedAxios.post.mock.calls[0][0]).toBe(
+      'https://api.openai.com/v1/chat/completions',
+    );
+    expect((mockedAxios.post.mock.calls[0][1] as any).messages[0]).toEqual({
+      role: 'system',
+      content: 'extraia os dados do título',
+    });
+    expect(result.content).toBe('ok');
   });
 });

package/src/ai/ai.service.ts

@@ -29,6 +29,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,
@@ -200,6 +201,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 +217,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 +251,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 +298,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 +345,7 @@ export class AiService implements OnModuleInit {
         CAST(${provider} AS ai_agent_provider_7cb93b1143_enum),
         ${model},
         ${instructions},
-        ${externalAgentId}
+        NULL
       )
     `;
 
@@ -358,29 +391,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 where: Prisma.ai_agentWhereInput = search
+      ? { slug: { contains: search, mode: 'insensitive' } }
+      : {};
 
-    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 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 +446,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,20 +495,11 @@ 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 { content } = await this.chatWithProvider(agent.provider, {
@@ -887,138 +894,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,
@@ -1100,10 +975,6 @@ export class AiService implements OnModuleInit {
     };
   }
 
-  private async sleep(ms: number) {
-    await new Promise((resolve) => setTimeout(resolve, ms));
-  }
-
   private async resolveAttachment(
     uploadFile?: MulterFile,
     fileId?: number,