@omnizap-system/omnizap 2.6.0 → 2.6.2

package/app/modules/playModule/playConfigRuntime.js

@@ -1,3 +1,4 @@
+import { now as __timeNow, nowIso as __timeNowIso, toUnixMs as __timeNowMs } from '#time';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -6,9 +7,82 @@ import { createModuleCommandConfigRuntime } from '../../services/ai/moduleComman
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const CONFIG_PATH = path.join(__dirname, 'commandConfig.json');
+const CONFIG_SNAPSHOT_TTL_MS = Math.max(1000, Number.parseInt(process.env.PLAY_CONFIG_SNAPSHOT_TTL_MS || '15000', 10) || 15000);
 
 const DEFAULT_TEXTS = {
   usage_header: '',
+  error_prefix: '❌ Erro: ',
+  generic_error: 'Erro inesperado ao processar sua solicitação.',
+  user_error_timeout: 'A operação demorou mais que o esperado. Tente novamente.',
+  user_error_technical_generic: 'Não foi possível processar sua solicitação agora. Tente novamente em instantes.',
+  admin_error_title: 'Erro no módulo play (diagnóstico).',
+  wait_audio: '⏳ Processando sua mídia...',
+  wait_video: '⏳ Processando sua mídia...',
+  ready_title_audio: '🎵 Áudio pronto!',
+  ready_title_video: '🎬 Vídeo pronto!',
+  video_fallback_to_audio: '⚠️ Este link retornou somente áudio. Enviando no formato de áudio.',
+  anti_bot_with_cookies: 'YouTube solicitou verificação anti-bot. Atualize o arquivo .secrets/cookies.txt e tente novamente.',
+  anti_bot_with_browser_profile: 'YouTube solicitou verificação anti-bot no provedor de mídia. Verifique suas credenciais e tente novamente.',
+  anti_bot_without_cookies: 'YouTube solicitou verificação anti-bot no provedor de mídia. Tente novamente em alguns minutos.',
+  usage_fallback_audio: '🎵 Uso: <prefix>play <link do YouTube ou termo de busca>',
+  usage_fallback_video: '🎬 Uso: <prefix>playvid <link do YouTube ou termo de busca>',
+  invalid_media_type: 'Tipo de mídia inválido.',
+  binary_exec_failed: 'Falha ao executar <command>.',
+  provider_error_generic: 'Falha ao processar mídia no provedor.',
+  provider_timeout_generic: 'Timeout ao processar mídia no provedor.',
+  search_invalid_input: 'Você precisa informar um link do YouTube ou termo de busca.',
+  search_not_found: 'Nenhum resultado encontrado para a busca.',
+  search_timeout: 'Timeout ao buscar metadados do vídeo.',
+  search_failed: 'Não foi possível buscar o vídeo agora.',
+  video_unavailable: 'Não foi possível acessar este vídeo agora. Tente outro link.',
+  ffmpeg_not_found: 'ffmpeg não encontrado no servidor para processar esta mídia.',
+  download_timeout: 'Timeout ao baixar o arquivo.',
+  download_failed: 'Falha ao baixar o arquivo localmente.',
+  download_file_not_found: 'Não foi possível localizar o arquivo baixado.',
+  download_invalid_media: 'Falha ao baixar mídia válida.',
+  media_too_big: 'O arquivo excede o limite permitido de <max_mb> MB.',
+  probe_timeout: 'Timeout ao analisar o vídeo recebido.',
+  probe_failed: 'Falha ao validar o vídeo recebido.',
+  transcode_timeout: 'Timeout ao normalizar o vídeo para envio.',
+  transcode_failed: 'Falha ao converter o vídeo para um formato compatível.',
+  transcode_output_invalid: 'Falha ao gerar vídeo compatível para envio.',
+  video_without_streams: 'Não foi possível enviar como vídeo: a mídia não possui faixa de vídeo nem áudio.',
+  thumbnail_timeout: 'Timeout ao baixar a thumbnail.',
+  thumbnail_failed: 'Falha ao baixar a thumbnail.',
+  thumbnail_too_big: 'Thumbnail excede o limite permitido.',
+  http_timeout: 'Timeout na requisição HTTP.',
+  http_failed: 'Falha na requisição HTTP.',
+  content_too_big: 'Conteúdo excede o limite permitido.',
+};
+
+const DEFAULT_OPERATIONAL_LIMITS = {
+  max_search_results: 5,
+  search_cache_ttl_ms: 60000,
+  max_search_cache_entries: 500,
+  max_redirects: 2,
+  max_concurrent_jobs: 2,
+  max_error_body_bytes: 65536,
+  max_meta_body_chars: 512,
+  retry_backoff_base_ms: 200,
+  search_retry_count: 1,
+  thumbnail_retry_count: 1,
+  thumbnail_timeout_ms: 15000,
+  max_thumb_bytes: 5 * 1024 * 1024,
+  admin_alert_dedupe_window_ms: 120000,
+  ytmp3_poll_interval_ms: 2000,
+};
+
+const DEFAULT_EXECUTION_OPTIONS = {
+  estrategias_formato: {
+    audio: ['bestaudio/best', 'best'],
+    video: ['bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4]/best', 'bestvideo*+bestaudio/best', 'best'],
+    audio_extract: {
+      enabled: true,
+      format: 'mp3',
+      quality: '0',
+    },
+    video_merge_output_format: 'mp4',
+  },
 };
 
 const runtime = createModuleCommandConfigRuntime({
@@ -17,10 +91,106 @@ const runtime = createModuleCommandConfigRuntime({
     module: 'playModule',
     commands: [],
     textos: DEFAULT_TEXTS,
+    limites_operacionais: DEFAULT_OPERATIONAL_LIMITS,
+    opcoes_execucao: DEFAULT_EXECUTION_OPTIONS,
   },
 });
 
+let cachedModuleConfig = null;
+let cachedSnapshotExpiresAt = 0;
+let cachedCommandRegistry = null;
+
 const renderUsageMethod = (method, commandPrefix) => String(method || '').replaceAll('<prefix>', String(commandPrefix || '/'));
+const renderTemplate = (value, variables = {}) => {
+  let text = String(value || '');
+  for (const [key, variableValue] of Object.entries(variables || {})) {
+    text = text.replaceAll(`<${key}>`, String(variableValue ?? ''));
+  }
+  return text;
+};
+
+const normalizeCommandToken = (value) =>
+  String(value || '')
+    .trim()
+    .toLowerCase();
+
+const toInt = (value, fallback, { min = Number.NEGATIVE_INFINITY, max = Number.POSITIVE_INFINITY } = {}) => {
+  const number = Number.parseInt(String(value ?? ''), 10);
+  if (!Number.isFinite(number)) return fallback;
+  if (number < min) return fallback;
+  if (number > max) return fallback;
+  return number;
+};
+
+const normalizeStringArray = (value, fallback = []) => {
+  if (!Array.isArray(value)) return [...fallback];
+  const normalized = value.map((item) => String(item || '').trim()).filter(Boolean);
+  return normalized.length ? normalized : [...fallback];
+};
+
+const normalizeExecutionOptions = (raw) => {
+  const source = raw && typeof raw === 'object' ? raw : {};
+  const defaultFormat = DEFAULT_EXECUTION_OPTIONS.estrategias_formato;
+  const rawFormat = source.estrategias_formato && typeof source.estrategias_formato === 'object' ? source.estrategias_formato : {};
+  const rawAudioExtract = rawFormat.audio_extract && typeof rawFormat.audio_extract === 'object' ? rawFormat.audio_extract : {};
+
+  return {
+    estrategias_formato: {
+      audio: normalizeStringArray(rawFormat.audio, defaultFormat.audio),
+      video: normalizeStringArray(rawFormat.video, defaultFormat.video),
+      audio_extract: {
+        enabled: rawAudioExtract.enabled === undefined ? Boolean(defaultFormat.audio_extract.enabled) : Boolean(rawAudioExtract.enabled),
+        format: String(rawAudioExtract.format || defaultFormat.audio_extract.format || '').trim() || defaultFormat.audio_extract.format,
+        quality: String(rawAudioExtract.quality || defaultFormat.audio_extract.quality || '').trim() || defaultFormat.audio_extract.quality,
+      },
+      video_merge_output_format: String(rawFormat.video_merge_output_format || defaultFormat.video_merge_output_format || '').trim() || defaultFormat.video_merge_output_format,
+    },
+  };
+};
+
+const getPlayModuleConfigSnapshot = () => {
+  const now = __timeNowMs();
+  if (cachedModuleConfig && now < cachedSnapshotExpiresAt) {
+    return cachedModuleConfig;
+  }
+
+  cachedModuleConfig = runtime.getModuleConfig();
+  cachedSnapshotExpiresAt = now + CONFIG_SNAPSHOT_TTL_MS;
+  cachedCommandRegistry = null;
+  return cachedModuleConfig;
+};
+
+const buildCommandRegistry = () => {
+  if (cachedCommandRegistry) return cachedCommandRegistry;
+
+  const config = getPlayModuleConfigSnapshot();
+  const entries = Array.isArray(config?.commands) ? config.commands : [];
+  const aliasToCanonical = new Map();
+  const commandEntryByCanonical = new Map();
+
+  for (const entry of entries) {
+    if (!entry || entry.enabled === false) continue;
+
+    const canonical = normalizeCommandToken(entry.name);
+    if (!canonical) continue;
+
+    commandEntryByCanonical.set(canonical, entry);
+    aliasToCanonical.set(canonical, canonical);
+
+    const aliases = Array.isArray(entry.aliases) ? entry.aliases : [];
+    for (const alias of aliases) {
+      const normalizedAlias = normalizeCommandToken(alias);
+      if (!normalizedAlias) continue;
+      aliasToCanonical.set(normalizedAlias, canonical);
+    }
+  }
+
+  cachedCommandRegistry = {
+    aliasToCanonical,
+    commandEntryByCanonical,
+  };
+  return cachedCommandRegistry;
+};
 
 const resolveUsageLines = (entry, variant) => {
   if (!entry || typeof entry !== 'object') return [];
@@ -42,11 +212,26 @@ const resolveUsageLines = (entry, variant) => {
   return methods.filter(Boolean).map((value) => String(value));
 };
 
-export const getPlayModuleConfig = () => runtime.getModuleConfig();
+export const getPlayModuleConfig = () => getPlayModuleConfigSnapshot();
+
+export const resolvePlayCommandName = (command) => {
+  const normalized = normalizeCommandToken(command);
+  if (!normalized) return null;
+  const { aliasToCanonical } = buildCommandRegistry();
+  return aliasToCanonical.get(normalized) || null;
+};
+
+export const getPlayCommandEntry = (command) => {
+  const canonical = resolvePlayCommandName(command);
+  if (!canonical) return null;
+  const { commandEntryByCanonical } = buildCommandRegistry();
+  return commandEntryByCanonical.get(canonical) || null;
+};
 
-export const resolvePlayCommandName = (command) => runtime.resolveCommandName(command);
-export const getPlayCommandEntry = (command) => runtime.getCommandEntry(command);
-export const listEnabledPlayCommands = () => runtime.listEnabledCommands();
+export const listEnabledPlayCommands = () => {
+  const { commandEntryByCanonical } = buildCommandRegistry();
+  return [...commandEntryByCanonical.values()];
+};
 
 export const getPlayTextConfig = () => {
   const config = getPlayModuleConfig();
@@ -57,6 +242,62 @@ export const getPlayTextConfig = () => {
   };
 };
 
+export const getPlayOperationalLimits = () => {
+  const config = getPlayModuleConfig();
+  const raw = config?.limites_operacionais && typeof config.limites_operacionais === 'object' ? config.limites_operacionais : {};
+  return {
+    max_search_results: toInt(raw.max_search_results, DEFAULT_OPERATIONAL_LIMITS.max_search_results, { min: 1, max: 10 }),
+    search_cache_ttl_ms: toInt(raw.search_cache_ttl_ms, DEFAULT_OPERATIONAL_LIMITS.search_cache_ttl_ms, { min: 1 }),
+    max_search_cache_entries: toInt(raw.max_search_cache_entries, DEFAULT_OPERATIONAL_LIMITS.max_search_cache_entries, { min: 1 }),
+    max_redirects: toInt(raw.max_redirects, DEFAULT_OPERATIONAL_LIMITS.max_redirects, { min: 0, max: 10 }),
+    max_concurrent_jobs: toInt(raw.max_concurrent_jobs, DEFAULT_OPERATIONAL_LIMITS.max_concurrent_jobs, { min: 1, max: 32 }),
+    max_error_body_bytes: toInt(raw.max_error_body_bytes, DEFAULT_OPERATIONAL_LIMITS.max_error_body_bytes, { min: 1024 }),
+    max_meta_body_chars: toInt(raw.max_meta_body_chars, DEFAULT_OPERATIONAL_LIMITS.max_meta_body_chars, { min: 64 }),
+    retry_backoff_base_ms: toInt(raw.retry_backoff_base_ms, DEFAULT_OPERATIONAL_LIMITS.retry_backoff_base_ms, { min: 1 }),
+    search_retry_count: toInt(raw.search_retry_count, DEFAULT_OPERATIONAL_LIMITS.search_retry_count, { min: 0, max: 5 }),
+    thumbnail_retry_count: toInt(raw.thumbnail_retry_count, DEFAULT_OPERATIONAL_LIMITS.thumbnail_retry_count, { min: 0, max: 5 }),
+    thumbnail_timeout_ms: toInt(raw.thumbnail_timeout_ms, DEFAULT_OPERATIONAL_LIMITS.thumbnail_timeout_ms, { min: 1000 }),
+    max_thumb_bytes: toInt(raw.max_thumb_bytes, DEFAULT_OPERATIONAL_LIMITS.max_thumb_bytes, { min: 1024 }),
+    admin_alert_dedupe_window_ms: toInt(raw.admin_alert_dedupe_window_ms, DEFAULT_OPERATIONAL_LIMITS.admin_alert_dedupe_window_ms, { min: 0 }),
+  };
+};
+
+export const getPlayExecutionOptions = () => {
+  const config = getPlayModuleConfig();
+  const raw = config?.opcoes_execucao && typeof config.opcoes_execucao === 'object' ? config.opcoes_execucao : {};
+  return normalizeExecutionOptions(raw);
+};
+
+export const getPlayText = (key, fallback = '') => {
+  const textConfig = getPlayTextConfig();
+  if (typeof key !== 'string' || !key.trim()) return fallback;
+  const value = textConfig[key];
+  if (typeof value !== 'string' || !value.trim()) return fallback;
+  return value;
+};
+
+export const getPlayWaitText = (type) => {
+  const normalizedType = String(type || '').toLowerCase();
+  const key = normalizedType === 'video' ? 'wait_video' : 'wait_audio';
+  const fallback = normalizedType === 'video' ? DEFAULT_TEXTS.wait_video : DEFAULT_TEXTS.wait_audio;
+  return getPlayText(key, fallback);
+};
+
+export const getPlayReadyTitle = (type) => {
+  const normalizedType = String(type || '').toLowerCase();
+  const key = normalizedType === 'video' ? 'ready_title_video' : 'ready_title_audio';
+  const fallback = normalizedType === 'video' ? DEFAULT_TEXTS.ready_title_video : DEFAULT_TEXTS.ready_title_audio;
+  return getPlayText(key, fallback);
+};
+
+export const getPlayUsageFallbackText = (type, commandPrefix = '/') => {
+  const normalizedType = String(type || '').toLowerCase();
+  const key = normalizedType === 'video' ? 'usage_fallback_video' : 'usage_fallback_audio';
+  const fallback = normalizedType === 'video' ? DEFAULT_TEXTS.usage_fallback_video : DEFAULT_TEXTS.usage_fallback_audio;
+  const template = getPlayText(key, fallback);
+  return renderTemplate(template, { prefix: commandPrefix });
+};
+
 export const getPlayUsageText = (command, { commandPrefix = '/', header, variant } = {}) => {
   const entry = getPlayCommandEntry(command);
   const methods = resolveUsageLines(entry, variant);

package/app/modules/playModule/playModuleCriticalFlows.test.js

@@ -0,0 +1,152 @@
+import { now as __timeNow, nowIso as __timeNowIso, toUnixMs as __timeNowMs } from '#time';
+import assert from 'node:assert/strict';
+import { after, test } from 'node:test';
+
+import { __playMediaClientTestUtils } from './playCommandMediaClient.js';
+
+const withEnv = async (overrides, fn) => {
+  const previous = new Map();
+  for (const [key, value] of Object.entries(overrides || {})) {
+    previous.set(key, Object.prototype.hasOwnProperty.call(process.env, key) ? process.env[key] : null);
+    if (value === null || value === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = String(value);
+    }
+  }
+
+  try {
+    return await fn();
+  } finally {
+    for (const [key, value] of previous.entries()) {
+      if (value === null) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  }
+};
+
+let closeDatabasePoolForTests = null;
+
+after(async () => {
+  if (typeof closeDatabasePoolForTests !== 'function') {
+    return;
+  }
+  await closeDatabasePoolForTests();
+  closeDatabasePoolForTests = null;
+});
+
+test('resolve candidates deduplica URLs e ignora inválidas', () => {
+  const urls = __playMediaClientTestUtils.extractCandidateUrlsFromSearchResult({
+    resultado: { url: 'https://www.youtube.com/watch?v=abc123' },
+    resultados: [{ url: 'https://www.youtube.com/watch?v=abc123' }, { url: 'https://youtu.be/xyz987' }, { url: 'not-an-url' }, { url: 'https://www.youtube.com/watch?v=zzz000' }],
+  });
+
+  assert.deepEqual(urls, ['https://www.youtube.com/watch?v=abc123', 'https://youtu.be/xyz987', 'https://www.youtube.com/watch?v=zzz000']);
+});
+
+test('ytmp3 principal é elegível para áudio e vídeo com URL do YouTube', () => {
+  assert.equal(
+    __playMediaClientTestUtils.isYtmp3PrimaryEligible({
+      type: 'audio',
+      link: 'https://www.youtube.com/watch?v=test1234567A',
+    }),
+    true,
+  );
+
+  assert.equal(
+    __playMediaClientTestUtils.isYtmp3PrimaryEligible({
+      type: 'video',
+      link: 'https://www.youtube.com/watch?v=test1234567A',
+    }),
+    true,
+  );
+
+  assert.equal(
+    __playMediaClientTestUtils.isYtmp3PrimaryEligible({
+      type: 'audio',
+      link: 'https://vimeo.com/1234',
+    }),
+    false,
+  );
+});
+
+test('anti-bot: detecta causa e retorna mensagem genérica do provedor', { concurrency: false }, async () => {
+  assert.equal(
+    __playMediaClientTestUtils.isYouTubeBotCheckCause({
+      meta: { cause: 'ERROR: [youtube] Sign in to confirm you’re not a bot.' },
+    }),
+    true,
+  );
+
+  const message = __playMediaClientTestUtils.buildYouTubeBotCheckUserMessage();
+  assert.match(message, /anti-bot/i);
+  assert.ok(!message.includes('PLAY_'));
+  assert.ok(!message.toLowerCase().includes('cookies_path'));
+});
+
+test('notifyFailure: envia admin só para erro técnico e deduplica alertas', { concurrency: false }, async () => {
+  await withEnv(
+    {
+      USER_ADMIN: '5511999999999',
+    },
+    async () => {
+      const mod = await import(`./playCommandCore.js?test=${__timeNowMs()}-${Math.random().toString(16).slice(2)}`);
+      const { closePool } = await import('../../../database/index.js');
+      closeDatabasePoolForTests = closePool;
+      const utils = mod.__playCommandCoreTestUtils;
+      utils.resetAdminAlertDedupCacheForTests();
+
+      const sent = [];
+      const sock = {
+        sendMessage: async (jid, content, options) => {
+          sent.push({ jid, content, options });
+          return {
+            key: { remoteJid: jid },
+            message: content,
+            messageTimestamp: Math.floor(__timeNowMs() / 1000),
+          };
+        },
+      };
+
+      const technicalError = Object.assign(new Error('spawn failed'), {
+        code: 'EAPI',
+        meta: {
+          technical: true,
+          endpoint: 'local:download',
+          cause: 'spawn failed',
+          rawCode: 'EPROCESS',
+        },
+      });
+
+      await utils.notifyFailure(sock, '120363111111111111@g.us', { key: {}, message: {} }, 0, technicalError, {
+        type: 'audio',
+        requestId: 'req-1',
+      });
+      assert.equal(sent.length, 2);
+      assert.match(sent[1].content.text, /diagnóstico/i);
+
+      await utils.notifyFailure(sock, '120363111111111111@g.us', { key: {}, message: {} }, 0, technicalError, {
+        type: 'audio',
+        requestId: 'req-1',
+      });
+      assert.equal(sent.length, 3);
+
+      const businessError = Object.assign(new Error('not found'), {
+        code: 'ENOTFOUND',
+        meta: {
+          technical: false,
+          endpoint: 'local:search',
+        },
+      });
+
+      await utils.notifyFailure(sock, '120363111111111111@g.us', { key: {}, message: {} }, 0, businessError, {
+        type: 'audio',
+        requestId: 'req-2',
+      });
+      assert.equal(sent.length, 4);
+    },
+  );
+});

package/app/modules/quoteModule/AGENT.md

@@ -7,7 +7,7 @@ Este arquivo e destinado a agentes de IA para gerar respostas no contexto dos co
 - arquivo_base: `app/modules/quoteModule/commandConfig.json`
 - schema_version: `2.0.0`
 - module_enabled: `true`
-- generated_at: `2026-03-11T02:35:17.177Z`
+- generated_at: `2026-03-17T04:04:14.195Z`
 
 ## Escopo do Modulo
 

package/app/modules/quoteModule/commandConfig.json

@@ -357,6 +357,35 @@
         "schema": "legacy_v1_and_v2",
         "legacy_name": "citar",
         "legacy_fields_present": ["descricao", "metodos_de_uso", "permissao_necessaria", "local_de_uso", "informacoes_coletadas", "argumentos", "pre_condicoes", "dependencias_externas", "efeitos_colaterais", "observabilidade", "privacidade", "acesso", "limite_uso_por_plano"]
+      },
+      "user_experience": {
+        "resumo_usuario": "Converta texto em uma figurinha no estilo quote para compartilhar citações.",
+        "quando_usar": ["Quando quiser transformar um texto ou mensagem citada em uma figurinha com o estilo 'quote' para compartilhar na conversa.", "Para criar citações rápidas sem digitar outros detalhes, basta digitar o comando com o texto desejado."],
+        "exemplos_reais": [
+          {
+            "situacao": "Criar uma quote simples a partir de um texto próprio.",
+            "comando": "<prefix>citar seu texto",
+            "resposta_esperada": "Figura citada criada com sucesso.",
+            "variacao": "Aparece a figurinha com o seu texto formatado como quote."
+          },
+          {
+            "situacao": "Citar uma frase de outro usuário mencionando-o.",
+            "comando": "<prefix>qc @usuário a frase citada",
+            "resposta_esperada": "Figura citada criada com sucesso.",
+            "variacao": "A citação é gerada a partir da mensagem citada."
+          },
+          {
+            "situacao": "Erro de formato ao não informar o texto.",
+            "comando": "<prefix>citar",
+            "resposta_esperada": "Formato de uso inválido. Consulte metodos_de_uso.",
+            "variacao": "O sistema pede para incluir o texto após o comando."
+          }
+        ],
+        "resposta_esperada": ["Figura citada criada com sucesso.", "Formato de uso inválido. Consulte metodos_de_uso.", "Permissão insuficiente para executar este comando."],
+        "erros_comuns_usuario": ["Esquecer de informar o texto após o comando <prefix>citar.", "Usar o comando <prefix>qc sem a estrutura correta (falta @usuario ou texto).", "Texto muito longo ou com caracteres não suportados pela figurinha.", "Não estar logado quando o sistema exigir login Google."],
+        "passos_se_der_erro": ["Verifique se você incluiu o texto após o comando.", "Se usar <prefix>qc, confirme a menção @usuário e o conteúdo a citar.", "Garanta que você está conectado com o Google (login requerido) e tente novamente.", "Se o problema persistir, tente novamente após atualizar a página ou contate o suporte."],
+        "resumo_usuario_origem": "auto_ia_assistida",
+        "resumo_usuario_revisao_pendente": true
       }
     }
   ],

package/app/modules/quoteModule/quoteCommand.js

@@ -1,3 +1,4 @@
+import { now as __timeNow, nowIso as __timeNowIso, toUnixMs as __timeNowMs } from '#time';
 import { createCanvas, loadImage } from 'canvas';
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -259,7 +260,7 @@ const getCachedEmojiImage = (cacheKey) => {
   if (!entry) return undefined;
 
   const ttl = entry.image ? EMOJI_CACHE_TTL_MS : EMOJI_FAIL_TTL_MS;
-  if (Date.now() - entry.createdAt > ttl) {
+  if (__timeNowMs() - entry.createdAt > ttl) {
     EMOJI_IMAGE_CACHE.delete(cacheKey);
     return undefined;
   }
@@ -275,7 +276,7 @@ const getCachedEmojiImage = (cacheKey) => {
  * @returns {void}
  */
 const setCachedEmojiImage = (cacheKey, image) => {
-  EMOJI_IMAGE_CACHE.set(cacheKey, { image, createdAt: Date.now() });
+  EMOJI_IMAGE_CACHE.set(cacheKey, { image, createdAt: __timeNowMs() });
 };
 
 /**

package/app/modules/rpgPokemonModule/AGENT.md

@@ -7,7 +7,7 @@ Este arquivo e destinado a agentes de IA para gerar respostas no contexto dos co
 - arquivo_base: `app/modules/rpgPokemonModule/commandConfig.json`
 - schema_version: `2.0.0`
 - module_enabled: `true`
-- generated_at: `2026-03-11T02:35:17.177Z`
+- generated_at: `2026-03-17T04:04:14.195Z`
 
 ## Escopo do Modulo
 

package/app/modules/rpgPokemonModule/commandConfig.json

@@ -377,6 +377,35 @@
         "schema": "legacy_v1_and_v2",
         "legacy_name": "pokemon",
         "legacy_fields_present": ["descricao", "metodos_de_uso", "permissao_necessaria", "local_de_uso", "informacoes_coletadas", "argumentos", "pre_condicoes", "dependencias_externas", "efeitos_colaterais", "observabilidade", "privacidade", "acesso", "limite_uso_por_plano"]
+      },
+      "user_experience": {
+        "resumo_usuario": "Comando principal do RPG Pokemon, usado para explorar, batalhar, comprar itens e socializar dentro do jogo pelo chat.",
+        "quando_usar": ["Iniciar a aventura: <prefix>pokemon start.", "Explorar o mapa: <prefix>pokemon explorar.", "Batalhar contra inimigos: <prefix>pokemon atacar <id>.", "Obter ajuda ou ver os métodos de uso: <prefix>pokemon help."],
+        "exemplos_reais": [
+          {
+            "situacao": "Novo jogador quer começar a aventura.",
+            "comando": "<prefix>pokemon start",
+            "resposta_esperada": "Comando executado com sucesso.",
+            "variacao": "Prefixo pode variar (ex.: ! ou /)."
+          },
+          {
+            "situacao": "Explorar o mapa atual.",
+            "comando": "<prefix>pokemon explorar",
+            "resposta_esperada": "Comando executado com sucesso.",
+            "variacao": "Se houver área bloqueada, o jogo mostrará informações da área atual."
+          },
+          {
+            "situacao": "Iniciar batalha contra o oponente 1.",
+            "comando": "<prefix>pokemon atacar 1",
+            "resposta_esperada": "Comando executado com sucesso.",
+            "variacao": "O número pode variar conforme os oponentes disponíveis."
+          }
+        ],
+        "resposta_esperada": ["Comando executado com sucesso.", "Formato de uso inválido. Consulte metodos_de_uso.", "Permissão insuficiente para executar este comando."],
+        "erros_comuns_usuario": ["Esquecer de informar o subcomando obrigatório (ação).", "Usar um subcomando que não existe ou está incorreto.", "Não estar logado com Google antes de usar o comando.", "Formato incorreto ao enviar parâmetros (ex.: <prefix>pokemon atacar sem o id).", "Tentar usar comandos antes de iniciar o jogo com <prefix>pokemon start."],
+        "passos_se_der_erro": ["Leia a mensagem de erro e verifique se o uso está correto consultando <prefix>pokemon help.", "Confira se o subcomando digitado é válido e se o <prefix> está correto.", "Tente novamente com o formato correto, por exemplo <prefix>pokemon start.", "Certifique-se de estar logado com Google, já que é exigido.", "Se o problema continuar, reporte o contexto do erro para o suporte."],
+        "resumo_usuario_origem": "auto_ia_assistida",
+        "resumo_usuario_revisao_pendente": true
       }
     }
   ],

package/app/modules/rpgPokemonModule/rpgBattleCanvasRenderer.js

@@ -1,3 +1,4 @@
+import { now as __timeNow, nowIso as __timeNowIso, toUnixMs as __timeNowMs } from '#time';
 import axios from 'axios';
 import { createCanvas, loadImage } from 'canvas';
 import logger from '#logger';
@@ -183,7 +184,7 @@ const drawRoundRect = (ctx, x, y, width, height, radius, fillStyle) => {
 };
 
 const cleanupCache = () => {
-  const now = Date.now();
+  const now = __timeNowMs();
   for (const [key, entry] of imageCache.entries()) {
     if (!entry || entry.expiresAt <= now) {
       imageCache.delete(key);
@@ -202,7 +203,7 @@ const resolveImage = async (imageUrl) => {
 
   cleanupCache();
   const cached = imageCache.get(url);
-  if (cached && cached.expiresAt > Date.now()) return cached.image;
+  if (cached && cached.expiresAt > __timeNowMs()) return cached.image;
 
   try {
     const response = await axios.get(url, {
@@ -211,10 +212,10 @@ const resolveImage = async (imageUrl) => {
       headers: { Accept: 'image/*' },
     });
     const image = await loadImage(Buffer.from(response.data));
-    imageCache.set(url, { image, expiresAt: Date.now() + IMAGE_CACHE_TTL_MS });
+    imageCache.set(url, { image, expiresAt: __timeNowMs() + IMAGE_CACHE_TTL_MS });
     return image;
   } catch (error) {
-    imageCache.set(url, { image: null, expiresAt: Date.now() + 90_000 });
+    imageCache.set(url, { image: null, expiresAt: __timeNowMs() + 90_000 });
     logger.debug('Falha ao carregar sprite para frame de batalha.', {
       imageUrl: url,
       error: error.message,

package/app/modules/rpgPokemonModule/rpgBattleService.test.js

@@ -1,3 +1,4 @@
+import { now as __timeNow, nowIso as __timeNowIso, toUnixMs as __timeNowMs } from '#time';
 import test from 'node:test';
 import assert from 'node:assert/strict';
 
@@ -15,7 +16,7 @@ const ensurePokeApiCache = () => {
 const setCache = (cache, key, data) => {
   cache.set(key, {
     data,
-    expiresAt: Date.now() + 60 * 60 * 1000,
+    expiresAt: __timeNowMs() + 60 * 60 * 1000,
   });
 };
 

package/app/modules/rpgPokemonModule/rpgPokemonDomain.js

@@ -1,3 +1,4 @@
+import { now as __timeNow, nowIso as __timeNowIso, toUnixMs as __timeNowMs } from '#time';
 export const BIOME_KEYS = ['floresta', 'cidade', 'caverna'];
 
 export const BIOME_DEFINITIONS = {
@@ -87,7 +88,7 @@ export const resolveDefaultBiomeForGroup = (groupJid) => {
   return BIOME_DEFINITIONS[biomeKey];
 };
 
-export const resolveMissionRefs = (date = new Date()) => {
+export const resolveMissionRefs = (date = __timeNow()) => {
   const year = date.getUTCFullYear();
   const month = date.getUTCMonth();
   const day = date.getUTCDate();