@omnizap-system/omnizap 2.6.0 → 2.6.2

package/app/services/ai/commandConfigEnrichmentService.js

@@ -4,9 +4,13 @@ import path from 'node:path';
 import OpenAI from 'openai';
 import { z } from 'zod';
 
+import { toUnixMs as __timeNowMs } from '#time';
 import logger from '#logger';
+import { createGeminiTextService, DEFAULT_GEMINI_MODEL, isGeminiAuthReady } from './geminiService.js';
 
-const DEFAULT_MODEL = 'gpt-4o-mini';
+const DEFAULT_MODEL = DEFAULT_GEMINI_MODEL;
+const DEFAULT_PROVIDER = 'gemini';
+const DEFAULT_GEMINI_AUTH_MODE = 'cli';
 const DEFAULT_TIMEOUT_MS = 25_000;
 const DEFAULT_CONTEXT_MAX_CHARS = 5_200;
 const DEFAULT_AGENT_MAX_CHARS = 2_400;
@@ -28,13 +32,52 @@ const parseEnvFloat = (value, fallback, min, max) => {
   return Math.max(min, Math.min(max, parsed));
 };
 
+const normalizeProvider = (value, fallback = DEFAULT_PROVIDER) => {
+  const normalized = String(value || '')
+    .trim()
+    .toLowerCase();
+  if (normalized === 'gemini') return 'gemini';
+  if (normalized === 'openai') return 'openai';
+  return fallback;
+};
+
+const normalizeGeminiAuthMode = (value, fallback = DEFAULT_GEMINI_AUTH_MODE) => {
+  const normalized = String(value || '')
+    .trim()
+    .toLowerCase();
+  if (normalized === 'api_key') return 'api_key';
+  if (normalized === 'cli') return 'cli';
+  if (normalized === 'auto') return 'auto';
+  return fallback;
+};
+
+const looksLikeGeminiModel = (value) =>
+  String(value || '')
+    .trim()
+    .toLowerCase()
+    .includes('gemini');
+
+const looksLikeOpenAiModel = (value) => {
+  const normalized = String(value || '')
+    .trim()
+    .toLowerCase();
+  if (!normalized) return false;
+  return normalized.startsWith('gpt-') || normalized.startsWith('o1') || normalized.startsWith('o3') || normalized.startsWith('o4') || normalized.startsWith('text-');
+};
+
+const COMMAND_CONFIG_ENRICHMENT_PROVIDER = normalizeProvider(process.env.COMMAND_CONFIG_ENRICHMENT_WORKER_PROVIDER || process.env.AI_HELP_LLM_PROVIDER || DEFAULT_PROVIDER, DEFAULT_PROVIDER);
 const COMMAND_CONFIG_ENRICHMENT_MODEL = String(process.env.COMMAND_CONFIG_ENRICHMENT_WORKER_MODEL || DEFAULT_MODEL).trim() || DEFAULT_MODEL;
+const COMMAND_CONFIG_ENRICHMENT_GEMINI_MODEL = looksLikeGeminiModel(COMMAND_CONFIG_ENRICHMENT_MODEL) ? COMMAND_CONFIG_ENRICHMENT_MODEL : String(process.env.GEMINI_MODEL || DEFAULT_GEMINI_MODEL).trim() || DEFAULT_GEMINI_MODEL;
+const COMMAND_CONFIG_ENRICHMENT_OPENAI_MODEL = looksLikeOpenAiModel(COMMAND_CONFIG_ENRICHMENT_MODEL) ? COMMAND_CONFIG_ENRICHMENT_MODEL : String(process.env.OPENAI_MODEL || 'gpt-5-nano').trim() || 'gpt-5-nano';
 const COMMAND_CONFIG_ENRICHMENT_TIMEOUT_MS = parseEnvInt(process.env.COMMAND_CONFIG_ENRICHMENT_WORKER_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, 5_000, 90_000);
 const COMMAND_CONFIG_ENRICHMENT_CONTEXT_MAX_CHARS = parseEnvInt(process.env.COMMAND_CONFIG_ENRICHMENT_CONTEXT_MAX_CHARS, DEFAULT_CONTEXT_MAX_CHARS, 1_500, 16_000);
 const COMMAND_CONFIG_ENRICHMENT_AGENT_MAX_CHARS = parseEnvInt(process.env.COMMAND_CONFIG_ENRICHMENT_AGENT_MAX_CHARS, DEFAULT_AGENT_MAX_CHARS, 600, 8_000);
 const COMMAND_CONFIG_ENRICHMENT_SOURCE_FILE_MAX_CHARS = parseEnvInt(process.env.COMMAND_CONFIG_ENRICHMENT_SOURCE_FILE_MAX_CHARS, DEFAULT_SOURCE_FILE_MAX_CHARS, 400, 5_000);
 const COMMAND_CONFIG_ENRICHMENT_MAX_SOURCE_FILES = parseEnvInt(process.env.COMMAND_CONFIG_ENRICHMENT_MAX_SOURCE_FILES, DEFAULT_MAX_SOURCE_FILES, 1, 8);
 const COMMAND_CONFIG_ENRICHMENT_BASE_CONFIDENCE = parseEnvFloat(process.env.COMMAND_CONFIG_ENRICHMENT_BASE_CONFIDENCE, 0.55, 0.1, 1);
+const COMMAND_CONFIG_ENRICHMENT_PROVIDER_FAILURE_COOLDOWN_MS = parseEnvInt(process.env.COMMAND_CONFIG_ENRICHMENT_PROVIDER_FAILURE_COOLDOWN_MS, 15 * 60 * 1000, 30_000, 24 * 60 * 60 * 1000);
+const COMMAND_CONFIG_ENRICHMENT_GEMINI_AUTH_MODE = normalizeGeminiAuthMode(process.env.COMMAND_CONFIG_ENRICHMENT_WORKER_GEMINI_AUTH_MODE || process.env.GEMINI_AUTH_MODE || DEFAULT_GEMINI_AUTH_MODE, DEFAULT_GEMINI_AUTH_MODE);
+const COMMAND_CONFIG_ENRICHMENT_GEMINI_CLI_COMMAND = String(process.env.COMMAND_CONFIG_ENRICHMENT_WORKER_GEMINI_CLI_COMMAND || process.env.GEMINI_CLI_COMMAND || 'gemini').trim() || 'gemini';
 
 const AI_ENRICHMENT_OUTPUT_SCHEMA = z
   .object({
@@ -48,6 +91,12 @@ const AI_ENRICHMENT_OUTPUT_SCHEMA = z
   .strict();
 
 let cachedClient = null;
+let cachedGeminiService = null;
+let cachedGeminiServiceKey = '';
+const providerCooldownUntil = {
+  gemini: 0,
+  openai: 0,
+};
 
 const moduleConfigCache = new Map();
 const fileTextCache = new Map();
@@ -105,6 +154,51 @@ const parseJsonSafe = (value) => {
   }
 };
 
+const parseJsonFromModelOutput = (rawOutput) => {
+  const direct = parseJsonSafe(rawOutput);
+  if (direct && typeof direct === 'object') return direct;
+
+  const text = String(rawOutput || '').trim();
+  if (!text) return null;
+
+  const fenceMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fenceMatch?.[1]) {
+    const fenced = parseJsonSafe(fenceMatch[1]);
+    if (fenced && typeof fenced === 'object') return fenced;
+  }
+
+  const start = text.indexOf('{');
+  const end = text.lastIndexOf('}');
+  if (start >= 0 && end > start) {
+    const sliced = parseJsonSafe(text.slice(start, end + 1));
+    if (sliced && typeof sliced === 'object') return sliced;
+  }
+
+  return null;
+};
+
+const isProviderInCooldown = (provider) => {
+  const now = __timeNowMs();
+  const safeProvider = provider === 'openai' ? 'openai' : 'gemini';
+  return Number(providerCooldownUntil[safeProvider] || 0) > now;
+};
+
+const shouldApplyProviderCooldown = (provider, error) => {
+  const message = normalizeText(error?.message || error);
+  if (!message) return false;
+
+  const hardErrorPatterns = ['modelnotfound', 'does not exist', 'requested entity was not found', 'permission denied', 'unauthorized', 'invalid api key', 'quota', '429'];
+  if (hardErrorPatterns.some((token) => message.includes(token))) return true;
+  return false;
+};
+
+const markProviderCooldown = (provider, error) => {
+  if (!shouldApplyProviderCooldown(provider, error)) return false;
+  const safeProvider = provider === 'openai' ? 'openai' : 'gemini';
+  providerCooldownUntil[safeProvider] = __timeNowMs() + COMMAND_CONFIG_ENRICHMENT_PROVIDER_FAILURE_COOLDOWN_MS;
+  return true;
+};
+
 const uniqueList = (values = [], { maxItems = DEFAULT_MAX_LIST_ITEMS, maxLength = 200, normalizeMode = 'display' } = {}) => {
   const source = Array.isArray(values) ? values : [];
   const output = [];
@@ -175,6 +269,86 @@ const getOpenAIClient = () => {
   return cachedClient;
 };
 
+const isGeminiReady = () =>
+  isGeminiAuthReady({
+    authMode: COMMAND_CONFIG_ENRICHMENT_GEMINI_AUTH_MODE,
+    apiKey: process.env.GEMINI_API_KEY,
+    cliCommand: COMMAND_CONFIG_ENRICHMENT_GEMINI_CLI_COMMAND,
+  });
+
+const isOpenAiReady = () => Boolean(String(process.env.OPENAI_API_KEY || '').trim());
+
+const getGeminiService = () => {
+  if (!isGeminiReady()) return null;
+
+  const serviceKey = `${COMMAND_CONFIG_ENRICHMENT_MODEL}|${COMMAND_CONFIG_ENRICHMENT_TIMEOUT_MS}|${COMMAND_CONFIG_ENRICHMENT_GEMINI_AUTH_MODE}|${COMMAND_CONFIG_ENRICHMENT_GEMINI_CLI_COMMAND}|${Boolean(String(process.env.GEMINI_API_KEY || '').trim())}`;
+  if (!cachedGeminiService || cachedGeminiServiceKey !== serviceKey) {
+    cachedGeminiService = createGeminiTextService({
+      apiKey: process.env.GEMINI_API_KEY,
+      defaultModel: COMMAND_CONFIG_ENRICHMENT_GEMINI_MODEL,
+      timeoutMs: COMMAND_CONFIG_ENRICHMENT_TIMEOUT_MS,
+      authMode: COMMAND_CONFIG_ENRICHMENT_GEMINI_AUTH_MODE,
+      cliCommand: COMMAND_CONFIG_ENRICHMENT_GEMINI_CLI_COMMAND,
+    });
+    cachedGeminiServiceKey = serviceKey;
+  }
+  return cachedGeminiService;
+};
+
+const callGeminiEnrichment = async ({ systemPrompt, contextPayload }) => {
+  const service = getGeminiService();
+  if (!service) return null;
+
+  const response = await service.generateText({
+    instructions: systemPrompt,
+    userPrompt: contextPayload,
+    model: COMMAND_CONFIG_ENRICHMENT_GEMINI_MODEL,
+  });
+
+  const text = String(response?.text || '').trim();
+  if (!text) return null;
+  return {
+    provider: 'gemini',
+    model: String(response?.model || COMMAND_CONFIG_ENRICHMENT_GEMINI_MODEL).trim() || COMMAND_CONFIG_ENRICHMENT_GEMINI_MODEL,
+    outputText: text,
+  };
+};
+
+const callOpenAiEnrichment = async ({ systemPrompt, contextPayload }) => {
+  if (!isOpenAiReady()) return null;
+
+  const client = getOpenAIClient();
+  const completion = await client.chat.completions.create({
+    model: COMMAND_CONFIG_ENRICHMENT_OPENAI_MODEL,
+    response_format: { type: 'json_object' },
+    messages: [
+      {
+        role: 'system',
+        content: systemPrompt,
+      },
+      {
+        role: 'user',
+        content: contextPayload,
+      },
+    ],
+  });
+
+  const message = completion?.choices?.[0]?.message || {};
+  const outputText = extractTextFromAssistantMessage(message);
+  if (!outputText) return null;
+  return {
+    provider: 'openai',
+    model: COMMAND_CONFIG_ENRICHMENT_OPENAI_MODEL,
+    outputText,
+  };
+};
+
+const resolveLlmCallOrder = () => {
+  const primary = normalizeProvider(COMMAND_CONFIG_ENRICHMENT_PROVIDER, DEFAULT_PROVIDER);
+  const fallback = primary === 'gemini' ? 'openai' : 'gemini';
+  return [primary, fallback];
+};
+
 const isFilePathInside = (baseDir, candidatePath) => {
   const normalizedBase = path.resolve(baseDir);
   const normalizedCandidate = path.resolve(candidatePath);
@@ -333,7 +507,7 @@ const buildCommandContextPayload = async ({ learningEvent, toolRecord }) => {
 };
 
 const parseAndSanitizeOutput = (rawJson) => {
-  const parsed = parseJsonSafe(rawJson);
+  const parsed = parseJsonFromModelOutput(rawJson);
   if (!parsed || typeof parsed !== 'object') return null;
 
   const validated = AI_ENRICHMENT_OUTPUT_SCHEMA.safeParse(parsed);
@@ -379,7 +553,7 @@ const buildHeuristicSuggestion = ({ learningEvent, toolRecord }) => {
   };
 };
 
-const isLlmReady = () => Boolean(process.env.OPENAI_API_KEY);
+const isLlmReady = () => isGeminiReady() || isOpenAiReady();
 
 export const generateCommandConfigEnrichmentSuggestion = async ({ learningEvent, toolRecord } = {}) => {
   if (!learningEvent || !toolRecord) return null;
@@ -390,63 +564,71 @@ export const generateCommandConfigEnrichmentSuggestion = async ({ learningEvent,
   }
 
   const contextPayload = await buildCommandContextPayload({ learningEvent, toolRecord });
-  const client = getOpenAIClient();
+  const systemPrompt = buildSystemPrompt();
 
-  let completion = null;
-  try {
-    completion = await client.chat.completions.create({
-      model: COMMAND_CONFIG_ENRICHMENT_MODEL,
-      temperature: 0.15,
-      response_format: { type: 'json_object' },
-      messages: [
-        {
-          role: 'system',
-          content: buildSystemPrompt(),
-        },
-        {
-          role: 'user',
-          content: contextPayload,
-        },
-      ],
-    });
-  } catch (error) {
-    logger.warn('Falha ao gerar enriquecimento de commandConfig com LLM.', {
-      action: 'command_config_enrichment_llm_failed',
-      module: toolRecord?.moduleKey || null,
-      command: toolRecord?.commandName || null,
-      event_id: learningEvent?.id || null,
-      error: error?.message,
-    });
-    return fallbackSuggestion;
-  }
-
-  const message = completion?.choices?.[0]?.message || {};
-  const rawJson = extractTextFromAssistantMessage(message);
-  const parsed = parseAndSanitizeOutput(rawJson);
+  const providerOrder = resolveLlmCallOrder();
+  for (const provider of providerOrder) {
+    if (isProviderInCooldown(provider)) {
+      continue;
+    }
 
-  if (!parsed || !isSuggestionMeaningful(parsed.suggestion)) {
-    return fallbackSuggestion;
+    try {
+      const llmOutput =
+        provider === 'gemini'
+          ? await callGeminiEnrichment({
+              systemPrompt,
+              contextPayload,
+            })
+          : await callOpenAiEnrichment({
+              systemPrompt,
+              contextPayload,
+            });
+
+      if (!llmOutput?.outputText) continue;
+
+      const parsed = parseAndSanitizeOutput(llmOutput.outputText);
+      if (!parsed || !isSuggestionMeaningful(parsed.suggestion)) continue;
+
+      const eventConfidence = clamp01(learningEvent?.confidence);
+      const successSignal = learningEvent?.success ? 0.12 : 0.03;
+      const finalConfidence = clamp01(parsed.modelConfidence * 0.72 + eventConfidence * 0.18 + successSignal);
+
+      return {
+        suggestion: parsed.suggestion,
+        confidence: finalConfidence,
+        source: `llm_${provider}`,
+        modelName: llmOutput.model || COMMAND_CONFIG_ENRICHMENT_MODEL,
+      };
+    } catch (error) {
+      logger.warn('Falha ao gerar enriquecimento de commandConfig com LLM.', {
+        action: 'command_config_enrichment_llm_failed',
+        module: toolRecord?.moduleKey || null,
+        command: toolRecord?.commandName || null,
+        event_id: learningEvent?.id || null,
+        provider,
+        provider_cooldown_applied: markProviderCooldown(provider, error),
+        error: error?.message,
+      });
+    }
   }
 
-  const eventConfidence = clamp01(learningEvent?.confidence);
-  const successSignal = learningEvent?.success ? 0.12 : 0.03;
-  const finalConfidence = clamp01(parsed.modelConfidence * 0.72 + eventConfidence * 0.18 + successSignal);
-
-  return {
-    suggestion: parsed.suggestion,
-    confidence: finalConfidence,
-    source: 'llm',
-    modelName: COMMAND_CONFIG_ENRICHMENT_MODEL,
-  };
+  return fallbackSuggestion;
 };
 
 export const getCommandConfigEnrichmentServiceConfig = () => ({
+  provider: COMMAND_CONFIG_ENRICHMENT_PROVIDER,
   model: COMMAND_CONFIG_ENRICHMENT_MODEL,
+  geminiModel: COMMAND_CONFIG_ENRICHMENT_GEMINI_MODEL,
+  openaiModel: COMMAND_CONFIG_ENRICHMENT_OPENAI_MODEL,
   timeoutMs: COMMAND_CONFIG_ENRICHMENT_TIMEOUT_MS,
   contextMaxChars: COMMAND_CONFIG_ENRICHMENT_CONTEXT_MAX_CHARS,
   agentMaxChars: COMMAND_CONFIG_ENRICHMENT_AGENT_MAX_CHARS,
   sourceFileMaxChars: COMMAND_CONFIG_ENRICHMENT_SOURCE_FILE_MAX_CHARS,
   maxSourceFiles: COMMAND_CONFIG_ENRICHMENT_MAX_SOURCE_FILES,
   baseConfidence: COMMAND_CONFIG_ENRICHMENT_BASE_CONFIDENCE,
+  geminiAuthMode: COMMAND_CONFIG_ENRICHMENT_GEMINI_AUTH_MODE,
+  hasGeminiAuth: isGeminiReady(),
+  hasOpenAiApiKey: isOpenAiReady(),
   hasApiKey: isLlmReady(),
+  providerFailureCooldownMs: COMMAND_CONFIG_ENRICHMENT_PROVIDER_FAILURE_COOLDOWN_MS,
 });

package/app/services/ai/conversationRouterService.js

@@ -1,3 +1,4 @@
+import { now as __timeNow, nowIso as __timeNowIso, toUnixMs as __timeNowMs } from '#time';
 import logger from '#logger';
 import { isSameJidUser } from '../../config/index.js';
 import { responderPerguntaGlobal } from './globalModuleAiHelpService.js';
@@ -119,7 +120,7 @@ const hasBotKeywordTrigger = (text) => {
   return tokens.length <= 3;
 };
 
-const pruneGroupCooldown = (nowMs = Date.now()) => {
+const pruneGroupCooldown = (nowMs = __timeNowMs()) => {
   for (const [key, expiresAt] of groupCooldownCache.entries()) {
     if (!Number.isFinite(expiresAt) || expiresAt <= nowMs) {
       groupCooldownCache.delete(key);
@@ -207,7 +208,7 @@ const shouldSkipForGroupCooldown = ({ chatId, senderJid }) => {
   if (!key) return false;
 
   pruneGroupCooldown();
-  const nowMs = Date.now();
+  const nowMs = __timeNowMs();
   const expiresAt = groupCooldownCache.get(key) || 0;
   if (expiresAt > nowMs) return true;
   return false;
@@ -217,7 +218,7 @@ const markGroupCooldown = ({ chatId, senderJid }) => {
   const key = buildGroupCooldownKey({ chatId, senderJid });
   if (!key) return;
   pruneGroupCooldown();
-  groupCooldownCache.set(key, Date.now() + GROUP_COOLDOWN_MS);
+  groupCooldownCache.set(key, __timeNowMs() + GROUP_COOLDOWN_MS);
 };
 
 const buildIntentFromAnswer = (answer) => ({

package/app/services/ai/geminiService.js

@@ -1,5 +1,13 @@
+import { execFile, spawnSync } from 'node:child_process';
+import { promisify } from 'node:util';
+
 const DEFAULT_GEMINI_API_BASE_URL = 'https://generativelanguage.googleapis.com/v1beta';
-export const DEFAULT_GEMINI_MODEL = 'gemini-1.5-flash';
+export const DEFAULT_GEMINI_MODEL = 'gemini-2.5-flash';
+const DEFAULT_GEMINI_AUTH_MODE = 'auto';
+const DEFAULT_GEMINI_CLI_COMMAND = 'gemini';
+
+const execFileAsync = promisify(execFile);
+const cliAvailabilityCache = new Map();
 
 const normalizeModelName = (value, fallback = DEFAULT_GEMINI_MODEL) => {
   const raw = String(value || '').trim();
@@ -13,6 +21,64 @@ const toPositiveInt = (value, fallback, min = 1) => {
   return parsed;
 };
 
+const normalizeAuthMode = (value, fallback = DEFAULT_GEMINI_AUTH_MODE) => {
+  const normalized = String(value || '')
+    .trim()
+    .toLowerCase();
+  if (normalized === 'api_key') return 'api_key';
+  if (normalized === 'cli') return 'cli';
+  if (normalized === 'auto') return 'auto';
+  return fallback;
+};
+
+const normalizeCliCommand = (value) => {
+  const command = String(value || DEFAULT_GEMINI_CLI_COMMAND).trim();
+  return command || DEFAULT_GEMINI_CLI_COMMAND;
+};
+
+const parseBooleanEnv = (value, fallback = false) => {
+  if (value === undefined || value === null || value === '') return fallback;
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'sim', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'nao', 'não', 'off'].includes(normalized)) return false;
+  return fallback;
+};
+
+const isGeminiCliAvailable = (cliCommand = DEFAULT_GEMINI_CLI_COMMAND) => {
+  const safeCliCommand = normalizeCliCommand(cliCommand);
+  if (cliAvailabilityCache.has(safeCliCommand)) {
+    return cliAvailabilityCache.get(safeCliCommand);
+  }
+
+  let available = false;
+  try {
+    const result = spawnSync(safeCliCommand, ['--version'], {
+      stdio: 'ignore',
+      shell: false,
+    });
+    available = result?.status === 0;
+  } catch {
+    available = false;
+  }
+
+  cliAvailabilityCache.set(safeCliCommand, available);
+  return available;
+};
+
+const sanitizeCliOutput = (value) =>
+  String(value || '')
+    .replaceAll('\0', '')
+    .replace(/\r\n/g, '\n')
+    .trim();
+
+const buildCliPrompt = ({ instructions = '', userPrompt = '' } = {}) => {
+  const safePrompt = normalizeOutboundText(userPrompt);
+  const safeInstructions = normalizeOutboundText(instructions);
+  if (!safeInstructions) return safePrompt;
+  if (!safePrompt) return safeInstructions;
+  return `${safeInstructions}\n\n---\n\n${safePrompt}`;
+};
+
 const parseErrorMessage = (payload, status) => {
   const explicit = String(payload?.error?.message || '').trim();
   if (explicit) return explicit;
@@ -35,14 +101,25 @@ const normalizeOutboundText = (value) =>
     .join('')
     .trim();
 
-export const createGeminiTextService = ({ apiKey = process.env.GEMINI_API_KEY, defaultModel = process.env.GEMINI_MODEL || DEFAULT_GEMINI_MODEL, timeoutMs = 25_000, apiBaseUrl = process.env.GEMINI_API_BASE_URL || DEFAULT_GEMINI_API_BASE_URL } = {}) => {
+export const isGeminiAuthReady = ({ authMode = process.env.GEMINI_AUTH_MODE || DEFAULT_GEMINI_AUTH_MODE, apiKey = process.env.GEMINI_API_KEY, cliCommand = process.env.GEMINI_CLI_COMMAND || DEFAULT_GEMINI_CLI_COMMAND } = {}) => {
+  const mode = normalizeAuthMode(authMode, DEFAULT_GEMINI_AUTH_MODE);
   const safeApiKey = String(apiKey || '').trim();
-  if (!safeApiKey) return null;
+  const useCliByEnv = parseBooleanEnv(process.env.GEMINI_USE_CLI_AUTH, false);
+  const modeWithLegacy = mode === 'auto' && useCliByEnv ? 'cli' : mode;
 
-  if (typeof globalThis.fetch !== 'function') {
-    throw new Error('createGeminiTextService: global fetch indisponivel no runtime atual.');
-  }
+  if (modeWithLegacy === 'api_key') return Boolean(safeApiKey);
+  if (modeWithLegacy === 'cli') return isGeminiCliAvailable(cliCommand);
+  if (safeApiKey) return true;
+  return isGeminiCliAvailable(cliCommand);
+};
 
+export const createGeminiTextService = ({ apiKey = process.env.GEMINI_API_KEY, defaultModel = process.env.GEMINI_MODEL || DEFAULT_GEMINI_MODEL, timeoutMs = 25_000, apiBaseUrl = process.env.GEMINI_API_BASE_URL || DEFAULT_GEMINI_API_BASE_URL, authMode = process.env.GEMINI_AUTH_MODE || DEFAULT_GEMINI_AUTH_MODE, cliCommand = process.env.GEMINI_CLI_COMMAND || DEFAULT_GEMINI_CLI_COMMAND, execFileAsyncImpl = execFileAsync, isCliAvailableImpl = isGeminiCliAvailable } = {}) => {
+  const safeApiKey = String(apiKey || '').trim();
+  const safeAuthMode = normalizeAuthMode(authMode, DEFAULT_GEMINI_AUTH_MODE);
+  const useCliByEnv = parseBooleanEnv(process.env.GEMINI_USE_CLI_AUTH, false);
+  const normalizedAuthMode = safeAuthMode === 'auto' && useCliByEnv ? 'cli' : safeAuthMode;
+  const selectedTransport = normalizedAuthMode === 'api_key' ? 'api_key' : normalizedAuthMode === 'cli' ? 'cli' : safeApiKey ? 'api_key' : 'cli';
+  const safeCliCommand = normalizeCliCommand(cliCommand);
   const safeBaseUrl =
     String(apiBaseUrl || DEFAULT_GEMINI_API_BASE_URL)
       .trim()
@@ -50,7 +127,16 @@ export const createGeminiTextService = ({ apiKey = process.env.GEMINI_API_KEY, d
   const safeTimeoutMs = Math.max(1_000, toPositiveInt(timeoutMs, 25_000, 1_000));
   const resolvedDefaultModel = normalizeModelName(defaultModel, DEFAULT_GEMINI_MODEL);
 
-  const generateText = async ({ instructions = '', userPrompt = '', model = resolvedDefaultModel } = {}) => {
+  if (selectedTransport === 'api_key') {
+    if (!safeApiKey) return null;
+    if (typeof globalThis.fetch !== 'function') {
+      throw new Error('createGeminiTextService: global fetch indisponivel no runtime atual.');
+    }
+  } else if (!isCliAvailableImpl(safeCliCommand)) {
+    return null;
+  }
+
+  const generateTextViaApiKey = async ({ instructions = '', userPrompt = '', model = resolvedDefaultModel } = {}) => {
     const safePrompt = normalizeOutboundText(userPrompt);
     if (!safePrompt) return { text: '', model: normalizeModelName(model, resolvedDefaultModel) };
 
@@ -82,6 +168,7 @@ export const createGeminiTextService = ({ apiKey = process.env.GEMINI_API_KEY, d
       : null;
 
     try {
+      // lgtm[js/file-access-to-http]
       const response = await globalThis.fetch(endpoint, {
         method: 'POST',
         headers: {
@@ -108,8 +195,46 @@ export const createGeminiTextService = ({ apiKey = process.env.GEMINI_API_KEY, d
     }
   };
 
+  const generateTextViaCli = async ({ instructions = '', userPrompt = '', model = resolvedDefaultModel } = {}) => {
+    const prompt = buildCliPrompt({ instructions, userPrompt });
+    const modelName = normalizeModelName(model, resolvedDefaultModel);
+    if (!prompt) return { text: '', model: modelName };
+
+    const args = ['-m', modelName, '-p', prompt, '--output-format', 'text'];
+    try {
+      const result = await execFileAsyncImpl(safeCliCommand, args, {
+        timeout: safeTimeoutMs,
+        maxBuffer: 2 * 1024 * 1024,
+        env: process.env,
+      });
+      const text = sanitizeCliOutput(result?.stdout);
+      if (!text) {
+        const stderrText = sanitizeCliOutput(result?.stderr);
+        throw new Error(stderrText || 'Gemini CLI retornou resposta vazia.');
+      }
+      return {
+        text,
+        model: modelName,
+      };
+    } catch (error) {
+      const stderrText = sanitizeCliOutput(error?.stderr);
+      const stdoutText = sanitizeCliOutput(error?.stdout);
+      const baseMessage = String(error?.message || '').trim();
+      const finalMessage = stderrText || stdoutText || baseMessage || 'Falha ao executar Gemini CLI.';
+      throw new Error(finalMessage);
+    }
+  };
+
+  const generateText = async ({ instructions = '', userPrompt = '', model = resolvedDefaultModel } = {}) => {
+    if (selectedTransport === 'api_key') {
+      return generateTextViaApiKey({ instructions, userPrompt, model });
+    }
+    return generateTextViaCli({ instructions, userPrompt, model });
+  };
+
   return {
     defaultModel: resolvedDefaultModel,
+    transport: selectedTransport,
     generateText,
   };
 };

package/app/services/ai/geminiService.test.js

@@ -2,8 +2,8 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { createGeminiTextService } from './geminiService.js';
 
-test('createGeminiTextService retorna null quando GEMINI_API_KEY nao existe', () => {
-  const service = createGeminiTextService({ apiKey: '' });
+test('createGeminiTextService retorna null no modo api_key quando GEMINI_API_KEY nao existe', () => {
+  const service = createGeminiTextService({ authMode: 'api_key', apiKey: '' });
   assert.equal(service, null);
 });
 
@@ -85,3 +85,60 @@ test('createGeminiTextService propaga erro detalhado da API', async (t) => {
     /Modelo invalido/,
   );
 });
+
+test('createGeminiTextService usa Gemini CLI quando authMode=cli', async () => {
+  const calls = [];
+  const service = createGeminiTextService({
+    authMode: 'cli',
+    cliCommand: 'gemini',
+    defaultModel: 'gemini-2.5-flash',
+    isCliAvailableImpl: () => true,
+    execFileAsyncImpl: async (file, args, options) => {
+      calls.push({ file, args, options });
+      return {
+        stdout: 'OK_GEMINI_CLI\n',
+        stderr: 'Loaded cached credentials.',
+      };
+    },
+  });
+
+  assert.ok(service);
+  assert.equal(service.transport, 'cli');
+
+  const response = await service.generateText({
+    instructions: 'Responda curto.',
+    userPrompt: 'Diga OK.',
+    model: 'gemini-2.5-flash',
+  });
+
+  assert.equal(response.model, 'gemini-2.5-flash');
+  assert.equal(response.text, 'OK_GEMINI_CLI');
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].file, 'gemini');
+  assert.ok(calls[0].args.includes('-m'));
+  assert.ok(calls[0].args.includes('gemini-2.5-flash'));
+  assert.ok(calls[0].args.includes('-p'));
+  assert.ok(calls[0].args.includes('--output-format'));
+});
+
+test('createGeminiTextService propaga erro do Gemini CLI', async () => {
+  const service = createGeminiTextService({
+    authMode: 'cli',
+    cliCommand: 'gemini',
+    defaultModel: 'gemini-2.5-flash',
+    isCliAvailableImpl: () => true,
+    execFileAsyncImpl: async () => {
+      const error = new Error('Command failed');
+      error.stderr = 'ModelNotFoundError: Requested entity was not found.';
+      throw error;
+    },
+  });
+
+  await assert.rejects(
+    () =>
+      service.generateText({
+        userPrompt: 'teste',
+      }),
+    /ModelNotFoundError/,
+  );
+});

package/app/services/ai/globalModuleAiHelpService.js

@@ -1,3 +1,4 @@
+import { now as __timeNow, nowIso as __timeNowIso, toUnixMs as __timeNowMs } from '#time';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
@@ -283,7 +284,7 @@ const ensureFeedbackStoreLoaded = async () => {
 
 const persistFeedbackStore = async () => {
   const store = await ensureFeedbackStoreLoaded();
-  store.updatedAt = new Date().toISOString();
+  store.updatedAt = __timeNowIso();
   await withFeedbackWrite(async () => {
     await fs.writeFile(GLOBAL_HELP_FEEDBACK_FILE_PATH, `${JSON.stringify(store, null, 2)}\n`, 'utf8');
   });
@@ -1340,7 +1341,7 @@ export const registerGlobalHelpCommandExecution = async ({ chatId, userId, isGro
   } else {
     entry.miss_count = Number(entry.miss_count || 0) + 1;
   }
-  entry.last_updated_at = new Date().toISOString();
+  entry.last_updated_at = __timeNowIso();
   await persistFeedbackStore();
 
   setConversationSessionIntent({

package/app/services/ai/messageCommandExecutionService.js

@@ -329,6 +329,7 @@ export const executeMessageCommandRoute = async ({ command, args = [], text = ''
           messageInfo,
           expirationMessage,
           senderJid,
+          senderIdentity,
           args: safeArgs,
           isGroupMessage,
           commandPrefix,
@@ -377,7 +378,7 @@ export const executeMessageCommandRoute = async ({ command, args = [], text = ''
       });
       commandResult = await runCommand('unknown', () =>
         sendReply(sock, remoteJid, messageInfo, expirationMessage, {
-          text: globalSuggestion ? `❌ *Comando não reconhecido*\n\nO comando *${normalizedCommand}* não está configurado ou ainda não existe.\n\n${globalSuggestion}\n\nℹ️ *Dica:*  \nDigite *${commandPrefix}menu* para ver a lista geral de comandos.\n\n🚧 *Fase Beta*  \nO omnizap-system ainda está em desenvolvimento e novos comandos estão sendo adicionados constantemente.` : `❌ *Comando não reconhecido*\n\nO comando *${normalizedCommand}* não está configurado ou ainda não existe.\n\nℹ️ *Dica:*  \nDigite *${commandPrefix}menu* para ver a lista de comandos disponíveis.\n\n🚧 *Fase Beta*  \nO omnizap-system ainda está em desenvolvimento e novos comandos estão sendo adicionados constantemente.`,
+          text: globalSuggestion ? `❌ *Comando não reconhecido*\n\nO comando *${normalizedCommand}* não está configurado ou ainda não existe.\n\n${globalSuggestion}\n\nℹ️ *Dica:*  \nDigite *${commandPrefix}menu* para ver a lista geral de comandos.\n\n🚧 *Fase Beta*  \nO omnizap ainda está em desenvolvimento e novos comandos estão sendo adicionados constantemente.` : `❌ *Comando não reconhecido*\n\nO comando *${normalizedCommand}* não está configurado ou ainda não existe.\n\nℹ️ *Dica:*  \nDigite *${commandPrefix}menu* para ver a lista de comandos disponíveis.\n\n🚧 *Fase Beta*  \nO omnizap ainda está em desenvolvimento e novos comandos estão sendo adicionados constantemente.`,
         }),
       );
       break;