@hed-hog/core 0.0.387 → 0.0.393

package/src/mcp-chat/mcp-chat.service.ts

@@ -12,13 +12,27 @@ import {
 } from '@nestjs/common';
 import axios from 'axios';
 import { AiExecutionService } from '../ai-instruction/ai-execution.service';
+import { FALLBACK_SYSTEM_PROMPT } from '../ai-instruction/ai-instruction.service';
 import { AiPromptBuilderService } from '../ai-instruction/ai-prompt-builder.service';
-import { buildAiConfigFromIntegration } from '../integration-profile/integration-profile.utils';
+import {
+  buildAiConfigFromIntegration,
+  DEEPSEEK_API_BASE_URL,
+  DEEPSEEK_DEFAULT_MODEL,
+} from '../integration-profile/integration-profile.utils';
 import { McpRegistryService, McpToolEntry } from '../mcp/mcp-registry.service';
 import { McpContext } from '../mcp/types/mcp-context.type';
 import { SettingService } from '../setting/setting.service';
 import { CreateConversationDTO } from './dto/create-conversation.dto';
 
+const OPENAI_API_BASE_URL = 'https://api.openai.com/v1';
+/**
+ * Modelos usados quando o perfil de integração não declara `config.model`.
+ * São o comportamento histórico do chat MCP, de quando o modelo era literal:
+ * mudar aqui muda o padrão de toda instalação que ainda não preencheu o campo.
+ */
+const OPENAI_CHAT_MODEL = 'gpt-4o-mini';
+const GEMINI_CHAT_MODEL = 'gemini-2.0-flash';
+
 type OpenAiMessage =
   | { role: 'system'; content: string }
   | { role: 'user'; content: string }
@@ -90,13 +104,6 @@ const FORCE_FINISH_THRESHOLD = 2;
 const MIN_DOMAIN_CONFIDENCE = 2;
 const AMBIGUOUS_DOMAIN_DELTA = 1;
 
-// SYSTEM_PROMPT is now managed via AiInstructionService (slug: system.global).
-// This fallback is used only if the DB is unreachable during startup.
-const SYSTEM_PROMPT_FALLBACK =
-  'You are a helpful assistant with access to tools from the HedHog system. ' +
-  "Use the available tools to answer the user's questions accurately. " +
-  'Always respond in the same language the user writes in.';
-
 const sanitize = (n: string) => n.replace(/\./g, '__');
 const restore = (n: string) => n.replace(/__/g, '.');
 
@@ -300,7 +307,7 @@ export class McpChatService {
 
     await this.assertOwnership(conversationId, userId);
 
-    const { provider, apiKey } = await this.getProviderKey();
+    const { provider, apiKey, baseUrl, model } = await this.getProviderKey();
 
     // Save user message
     await this.prisma.mcp_conversation_message.create({
@@ -331,28 +338,65 @@ export class McpChatService {
 
     try {
       if (provider === 'gemini') {
-        return await this.runGeminiLoop(conversationId, userId, locale, message, apiKey, executionId);
+        return await this.runGeminiLoop(
+          conversationId,
+          userId,
+          locale,
+          message,
+          apiKey,
+          executionId,
+          model,
+        );
       }
-      return await this.runOpenAiLoop(conversationId, userId, locale, message, apiKey, executionId);
+      return await this.runOpenAiLoop(
+        conversationId,
+        userId,
+        locale,
+        message,
+        apiKey,
+        executionId,
+        provider,
+        baseUrl,
+        model,
+      );
     } catch (err) {
       await this.aiExecution.finish(executionId, 'failed', String(err));
       throw err;
     }
   }
 
-  private async getSystemPrompt(locale?: string): Promise<string> {
+  /**
+   * Composes the system prompt from the stored layers.
+   *
+   * `moduleSlug`/`agentSlug` activate the L3/L4 layers; without them the seeded
+   * `module.*` and `agent.*` instructions are never read. `SYSTEM_PROMPT_FALLBACK`
+   * used to be duplicated here — it now comes from `AiInstructionService`, which
+   * already falls back internally, so this only guards against the whole build
+   * throwing.
+   */
+  private async getSystemPrompt(
+    locale?: string,
+    context?: { moduleSlug?: string; agentSlug?: string },
+  ): Promise<string> {
     try {
       const built = await this.promptBuilder.build({
         locale,
+        moduleSlug: context?.moduleSlug,
+        agentSlug: context?.agentSlug,
       });
-      return built.systemPrompt || SYSTEM_PROMPT_FALLBACK;
+      return built.systemPrompt || FALLBACK_SYSTEM_PROMPT;
     } catch {
-      return SYSTEM_PROMPT_FALLBACK;
+      return FALLBACK_SYSTEM_PROMPT;
     }
   }
 
   // ── OpenAI loop ──────────────────────────────────────────────────────────
 
+  /**
+   * Loop de tool calling no formato OpenAI. Serve tanto para a OpenAI quanto
+   * para o DeepSeek, que expõe a mesma API de `/chat/completions` (inclusive
+   * `tools`/`tool_calls`) — muda só a base URL, o modelo e a chave.
+   */
   private async runOpenAiLoop(
     conversationId: number,
     userId: number,
@@ -360,6 +404,9 @@ export class McpChatService {
     message: string,
     apiKey: string,
     executionId: number,
+    provider: 'openai' | 'deepseek' = 'openai',
+    baseUrl = OPENAI_API_BASE_URL,
+    model = OPENAI_CHAT_MODEL,
   ) {
     const systemPrompt = await this.getSystemPrompt(locale);
 
@@ -385,6 +432,9 @@ export class McpChatService {
       history,
     );
     if (toolSelection.clarification) {
+      // Sem o finish a execução fica presa em `running` para sempre — o caminho
+      // Gemini já fechava aqui.
+      await this.aiExecution.finish(executionId, 'completed');
       return this.recordAssistantAndReturnHistory(
         conversationId,
         toolSelection.clarification,
@@ -401,9 +451,9 @@ export class McpChatService {
       const stepStart = Date.now();
       try {
         response = await axios.post(
-          'https://api.openai.com/v1/chat/completions',
+          `${baseUrl}/chat/completions`,
           {
-            model: 'gpt-4o-mini',
+            model,
             messages: openAiMessages,
             tools: !forceFinish && tools.length > 0 ? tools : undefined,
             tool_choice: !forceFinish && tools.length > 0 ? 'auto' : undefined,
@@ -418,17 +468,19 @@ export class McpChatService {
       } catch (err: any) {
         const status = err?.response?.status;
         const errBody = err?.response?.data?.error;
+        const providerName = provider === 'deepseek' ? 'DeepSeek' : 'OpenAI';
         if (status === 429) {
           throw new HttpException(
-            errBody?.message ?? 'OpenAI rate limit exceeded. Please try again later.',
+            errBody?.message ??
+              `${providerName} rate limit exceeded. Please try again later.`,
             HttpStatus.TOO_MANY_REQUESTS,
           );
         }
         if (status === 401) {
-          throw new BadRequestException('Invalid OpenAI API key.');
+          throw new BadRequestException(`Invalid ${providerName} API key.`);
         }
         throw new HttpException(
-          errBody?.message ?? 'OpenAI API error.',
+          errBody?.message ?? `${providerName} API error.`,
           status ?? HttpStatus.BAD_GATEWAY,
         );
       }
@@ -438,8 +490,8 @@ export class McpChatService {
         executionId,
         stepOrder: stepOrder++,
         type: 'prompt',
-        provider: 'openai',
-        model: 'gpt-4o-mini',
+        provider,
+        model,
         durationMs: Date.now() - stepStart,
         usage: usage
           ? { input: usage.prompt_tokens ?? 0, output: usage.completion_tokens ?? 0, total: usage.total_tokens ?? 0 }
@@ -571,7 +623,11 @@ export class McpChatService {
     message: string,
     apiKey: string,
     executionId: number,
+    model = GEMINI_CHAT_MODEL,
   ) {
+    // O perfil pode trazer o nome no formato da API ("models/gemini-2.0-flash");
+    // a URL abaixo já inclui o segmento `/models/`.
+    const modelId = model.replace(/^models\//, '');
     const systemPrompt = await this.getSystemPrompt(locale);
 
     const allHistory = await this.prisma.mcp_conversation_message.findMany({
@@ -608,7 +664,7 @@ export class McpChatService {
       const stepStart = Date.now();
       try {
         response = await axios.post(
-          `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=${apiKey}`,
+          `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(modelId)}:generateContent?key=${apiKey}`,
           {
             systemInstruction: { parts: [{ text: systemPrompt }] },
             contents: geminiContents,
@@ -648,7 +704,7 @@ export class McpChatService {
         stepOrder: stepOrder++,
         type: 'prompt',
         provider: 'gemini',
-        model: 'gemini-2.0-flash',
+        model: modelId,
         durationMs: Date.now() - stepStart,
         usage: geminiUsage
           ? { input: geminiUsage.promptTokenCount ?? 0, output: geminiUsage.candidatesTokenCount ?? 0, total: geminiUsage.totalTokenCount ?? 0 }
@@ -858,7 +914,21 @@ export class McpChatService {
     }
   }
 
-  private async getProviderKey(): Promise<{ provider: 'openai' | 'gemini'; apiKey: string }> {
+  /**
+   * Resolve credenciais e modelo do chat MCP a partir do perfil de integração
+   * apontado pela setting `mcp-ai-profile-id`.
+   *
+   * O `model` segue a mesma precedência do resto do codebase — aqui sem o degrau
+   * de `ai_instruction`, porque este fluxo não tem prompt de task próprio:
+   * `integration_profile.config.model` > constante de default do provider.
+   */
+  private async getProviderKey(): Promise<{
+    provider: 'openai' | 'gemini' | 'deepseek';
+    apiKey: string;
+    /** Base URL só se aplica aos providers no formato OpenAI; o Gemini leva o modelo na URL. */
+    baseUrl: string;
+    model: string;
+  }> {
     const settings = await this.setting.getSettingValues(['mcp-ai-profile-id']);
     const profileSlug = String(settings['mcp-ai-profile-id'] ?? '').trim();
 
@@ -878,13 +948,39 @@ export class McpChatService {
     }
 
     const providerSlug = profile.integration_provider.slug;
-    const { apiKey } = buildAiConfigFromIntegration(providerSlug, profile.config);
+    const { apiKey, model, baseUrl } = buildAiConfigFromIntegration(
+      providerSlug,
+      profile.config,
+    );
 
     if (!apiKey) {
       throw new BadRequestException(`MCP AI profile "${profileSlug}" has no API key configured.`);
     }
 
-    return { provider: providerSlug === 'gemini' ? 'gemini' : 'openai', apiKey };
+    if (providerSlug === 'gemini') {
+      return {
+        provider: 'gemini',
+        apiKey,
+        baseUrl: '',
+        model: model || GEMINI_CHAT_MODEL,
+      };
+    }
+
+    if (providerSlug === 'deepseek') {
+      return {
+        provider: 'deepseek',
+        apiKey,
+        baseUrl: baseUrl || DEEPSEEK_API_BASE_URL,
+        model: model || DEEPSEEK_DEFAULT_MODEL,
+      };
+    }
+
+    return {
+      provider: 'openai',
+      apiKey,
+      baseUrl: OPENAI_API_BASE_URL,
+      model: model || OPENAI_CHAT_MODEL,
+    };
   }
 
   private async buildOpenAiTools(

package/src/meeting/meeting-provider.registry.ts

@@ -0,0 +1,193 @@
+import { Injectable, Logger } from '@nestjs/common';
+
+/**
+ * Pedido de criação de uma reunião online para uma entidade de negócio qualquer.
+ *
+ * A tripla `sourceModule`/`sourceEntity`/`sourceEntityId` é o que amarra a reunião
+ * à origem sem que o provedor precise conhecer o domínio: o LMS envia
+ * `('lms', 'course_class_session', '42')` e recebe de volta, no evento de gravação,
+ * exatamente a mesma tripla.
+ */
+export interface CreateMeetingInput {
+  sourceModule: string;
+  sourceEntity: string;
+  sourceEntityId: string;
+  subject: string;
+  startAt: Date;
+  endAt: Date;
+  /** Liga a gravação automática, quando o provedor suportar. */
+  autoRecord?: boolean;
+  /** Usuário que pediu a criação (usado no modo delegado). */
+  requestedByUserId?: number;
+  /**
+   * Usuários que devem poder controlar a reunião (iniciar/parar gravação, admitir
+   * participantes). Sem isso, num organizador de serviço, o professor entra como
+   * participante comum.
+   */
+  coOrganizerUserIds?: number[];
+  /** Convidados do evento de calendário. */
+  attendeeEmails?: string[];
+  /** Local do evento (aula presencial/híbrida com reunião gerenciada). */
+  location?: string | null;
+  /** Texto da origem que acompanha o link no corpo do evento. */
+  description?: string | null;
+}
+
+export interface CreatedMeeting {
+  /** Link que o aluno abre. É o que vai para `meeting_url` da aula. */
+  joinUrl: string;
+  /** Id da reunião no provedor — necessário para buscar a gravação depois. */
+  providerMeetingId: string;
+  /** Id do evento de calendário, quando o provedor cria um. */
+  providerEventId?: string | null;
+}
+
+export interface MeetingSourceRef {
+  sourceModule: string;
+  sourceEntity: string;
+  sourceEntityIds: string[];
+}
+
+export type CreateMeetingResult =
+  | ({ ok: true } & CreatedMeeting)
+  | { ok: false; sourceEntityId: string; error: string };
+
+/** Pedido de troca de convidados de uma reunião já existente. */
+export interface UpdateMeetingAttendeesInput {
+  sourceModule: string;
+  sourceEntity: string;
+  sourceEntityId: string;
+  attendeeEmails: string[];
+}
+
+/**
+ * Pedido de atualização de assunto/horário/local de uma reunião já existente.
+ *
+ * Separado de `createMeeting` pelo mesmo motivo de `updateAttendees`: recriar
+ * geraria link novo e derrubaria quem já tem o evento antigo na agenda.
+ */
+export interface UpdateMeetingDetailsInput {
+  sourceModule: string;
+  sourceEntity: string;
+  sourceEntityId: string;
+  subject: string;
+  startAt: Date;
+  endAt: Date;
+  location?: string | null;
+  description?: string | null;
+}
+
+/**
+ * Estado de uma reunião, na forma em que o módulo de origem precisa ver.
+ *
+ * Existe para que o dono da origem consulte o provedor em vez de ler a tabela
+ * dele: o LMS não deve saber que existe uma `microsoft_meeting`.
+ */
+export interface MeetingSummary {
+  sourceEntityId: string;
+  joinUrl: string | null;
+  status: 'scheduled' | 'cancelled' | 'failed';
+  autoRecord: boolean;
+  /**
+   * Assunto e janela gravados no provedor, para a origem comparar com o que é
+   * desejado antes de mandar `updateDetails` — evita um PATCH a cada sync
+   * quando nada mudou. `null` em reuniões criadas antes deste campo existir.
+   */
+  subject: string | null;
+  startAt: Date | null;
+  endAt: Date | null;
+  location: string | null;
+  description: string | null;
+  /**
+   * Convidados atualmente no evento de calendário.
+   *
+   * Existe para o módulo de origem comparar antes de mandar atualizar: alterar
+   * a lista faz o provedor reenviar convite/atualização para todos, então um
+   * PATCH incondicional a cada sincronização viraria spam na caixa de quem
+   * acompanha a turma.
+   */
+  attendeeEmails: string[];
+  /** Estado da importação da gravação, quando `autoRecord` está ligado. */
+  recordingStatus:
+    | 'not_requested'
+    | 'pending'
+    | 'imported'
+    | 'unavailable'
+    | 'failed';
+  recordingFileId: number | null;
+  lastError: string | null;
+}
+
+/**
+ * Provedor de reuniões online (Teams hoje; Meet/Zoom cabem no mesmo contrato).
+ *
+ * Existe para que os módulos de negócio não dependam do pacote de um provedor
+ * específico: eles pedem ao registro e, se ninguém tiver se registrado, a
+ * funcionalidade simplesmente não aparece.
+ */
+export interface IMeetingProvider {
+  /** Se a integração está configurada a ponto de aceitar chamadas. */
+  isAvailable(): Promise<boolean>;
+  createMeeting(input: CreateMeetingInput): Promise<CreatedMeeting>;
+  /** Criação em lote; nunca rejeita — devolve o erro por item. */
+  createMeetings(inputs: CreateMeetingInput[]): Promise<CreateMeetingResult[]>;
+  /** Cancela no provedor as reuniões das origens informadas. Tolerante a ausências. */
+  cancelBySource(ref: MeetingSourceRef): Promise<void>;
+  /**
+   * Troca a lista de convidados do evento de uma reunião já criada.
+   *
+   * Separado de `createMeeting` porque o custo é diferente: recriar a reunião
+   * geraria um link novo e derrubaria quem já tinha o antigo na agenda, enquanto
+   * ajustar convidados preserva a reunião. Tolerante a reunião inexistente.
+   */
+  updateAttendees(input: UpdateMeetingAttendeesInput): Promise<void>;
+  /**
+   * Atualiza assunto, horário e local do evento/reunião já criados, sem gerar
+   * link novo. Tolerante a reunião inexistente (mesmo padrão de updateAttendees).
+   */
+  updateDetails(input: UpdateMeetingDetailsInput): Promise<void>;
+  /** Estado das reuniões das origens informadas, para a UI do módulo de origem. */
+  findBySource(ref: MeetingSourceRef): Promise<MeetingSummary[]>;
+}
+
+/**
+ * Registro dos provedores de reunião, no mesmo padrão do WebhookProtocolRegistry:
+ * o módulo dono do provedor se registra no boot.
+ */
+@Injectable()
+export class MeetingProviderRegistry {
+  private readonly logger = new Logger(MeetingProviderRegistry.name);
+  private readonly providers = new Map<string, IMeetingProvider>();
+
+  register(provider: string, implementation: IMeetingProvider): void {
+    const key = normalizeProvider(provider);
+    if (!key) throw new Error('Meeting provider key is required.');
+
+    if (this.providers.has(key)) {
+      this.logger.warn(`Meeting provider "${key}" was overwritten.`);
+    }
+
+    this.providers.set(key, implementation);
+    this.logger.log(`Registered meeting provider "${key}"`);
+  }
+
+  get(provider: string | null | undefined): IMeetingProvider | null {
+    const key = normalizeProvider(provider);
+    return key ? (this.providers.get(key) ?? null) : null;
+  }
+
+  has(provider: string | null | undefined): boolean {
+    return this.get(provider) !== null;
+  }
+
+  /** Provedores registrados (para a UI listar o que existe). */
+  list(): string[] {
+    return [...this.providers.keys()].sort();
+  }
+}
+
+function normalizeProvider(provider: string | null | undefined): string {
+  return String(provider ?? '')
+    .trim()
+    .toLowerCase();
+}

package/src/meeting/meeting.constants.ts

@@ -0,0 +1,53 @@
+/** Chave do provedor Microsoft Teams no {@link MeetingProviderRegistry}. */
+export const TEAMS_MEETING_PROVIDER = 'teams';
+
+/**
+ * Evento de domínio publicado quando a gravação de uma reunião foi baixada e já
+ * existe como registro em `file`. Fica no core porque é o contrato entre quem
+ * publica (provedor da reunião) e quem consome (módulo dono da origem) — assim
+ * nenhum dos dois precisa importar o pacote do outro.
+ */
+export const MEETING_RECORDING_AVAILABLE_EVENT =
+  'microsoft.meeting.recording.available';
+
+export interface MeetingRecordingAvailablePayload {
+  /** `file.id` do vídeo já enviado ao storage. */
+  fileId: number;
+  sourceModule: string;
+  sourceEntity: string;
+  sourceEntityId: string;
+  providerMeetingId?: string | null;
+  providerRecordingId?: string | null;
+  durationSeconds?: number | null;
+  joinUrl?: string | null;
+}
+
+/**
+ * Evento publicado quando o relatório de presença de uma reunião foi importado.
+ *
+ * Mesma razão de existir do evento de gravação: o provedor sabe quem entrou na
+ * reunião, mas não sabe o que é um aluno; o módulo de origem sabe quem está
+ * matriculado, mas não conhece o Graph. O encontro é aqui.
+ */
+export const MEETING_ATTENDANCE_AVAILABLE_EVENT =
+  'microsoft.meeting.attendance.available';
+
+/** Um participante do relatório, na forma em que a origem precisa ver. */
+export interface MeetingAttendanceRecord {
+  /**
+   * Nulo quando o provedor não identificou quem entrou (link aberto por
+   * convidado externo ou anônimo). A origem trata esse caso como "participante
+   * não identificado" em vez de descartar.
+   */
+  email: string | null;
+  displayName: string;
+  totalAttendanceSeconds: number;
+}
+
+export interface MeetingAttendanceAvailablePayload {
+  sourceModule: string;
+  sourceEntity: string;
+  sourceEntityId: string;
+  providerMeetingId?: string | null;
+  records: MeetingAttendanceRecord[];
+}

package/src/meeting/meeting.module.ts

@@ -0,0 +1,13 @@
+import { Global, Module } from '@nestjs/common';
+import { MeetingProviderRegistry } from './meeting-provider.registry';
+
+/**
+ * Porta genérica de reuniões online. Só carrega o registro — a implementação vem
+ * de quem se registrar no boot (hoje a library `microsoft`, com a chave `teams`).
+ */
+@Global()
+@Module({
+  providers: [MeetingProviderRegistry],
+  exports: [MeetingProviderRegistry],
+})
+export class MeetingModule {}

package/src/middlewares/locale-injection.middleware.ts

@@ -1,15 +1,34 @@
+import { localeStorage } from '@hed-hog/api-locale';
 import { Injectable, NestMiddleware } from '@nestjs/common';
 import { NextFunction, Request, Response } from 'express';
-import { localeStorage } from '../utils/locale-context';
 
+/**
+ * Rede de seguranca do contexto de locale.
+ *
+ * Quem resolve o idioma e o `LocaleMiddleware` do `api-locale`, que ja abre o
+ * `AsyncLocalStorage` para o resto da cadeia. Este middleware so entra em acao
+ * quando aquele nao rodou (app que nao registrou o `LocaleModule`, ou uma
+ * ordem de middleware que o coloque depois), para que
+ * `getLocaleFromContext()` nunca leia um store vazio.
+ *
+ * Nao reinterpreta o header: sem a tabela `locale` a mao, validar aqui de novo
+ * era justamente como as duas camadas divergiam.
+ */
 @Injectable()
 export class LocaleInjectionMiddleware implements NestMiddleware {
   use(req: Request, res: Response, next: NextFunction) {
-    const acceptLanguage = req.headers['accept-language'] || 'en';
-    const locale = acceptLanguage.split(',')[0].split('-')[0];
+    if (localeStorage.getStore()) {
+      return next();
+    }
 
-    localeStorage.run({ locale }, () => {
-      next();
-    });
+    localeStorage.run(
+      {
+        locale: req['locale'] || 'en',
+        detected: Boolean(req['localeDetected']),
+      },
+      () => {
+        next();
+      },
+    );
   }
 }