# IA: provedores, login/chave, IA reserva e monitor de uso Fonte do contrato: **`doc/ia.md`** (arquivos, ambiente de cada chamada, o que conta como indisponível, Gemini headless). Não duplique aqui; este arquivo diz onde mexer e o que não quebrar. Sempre pela **CLI oficial** (`claude`, `codex`, `gemini`, `agy`), nunca SDK/HTTP direto. `antigravity` é o 4º provedor (começa **desligado**). ## Onde mexer | Mudança | Arquivo(s) | Também atualizar | |---|---|---| | Configurações, cofre, detecção, instalação, login, teste, `providerEnv`, `isAvailabilityError`, pausa, `readyChain`/`nextFallback` | `panel/src/lib/ai.ts` | `panel/src/lib/ai.test.ts`, `doc/ia.md` | | Agente do painel por provedor (`geminiArgs`, `normalizeGemini`, `antigravityArgs`, `normalizeAntigravity`, `--resume`/`--conversation`, shell liberado), troca de IA ao cair | `panel/src/lib/agents.ts` (`prompts.ts`, `types.ts` para `AgentProvider`) | `ai.test.ts` (argumentos e eventos do Gemini) | | Execução que continua outra que caiu | coluna `agent_runs.fallback_of` (migração v10 em `panel/src/lib/db.ts`), `followUpRunOf` (segue `resume_of` **e** `fallback_of`) | `publishing-db.test.ts` (conta de migrações) | | Monitor de uso (leitura sem gastar token, `overLimit`, `usage.json`) | `panel/src/lib/ai-usage.ts` (`refreshUsage`, `ensureUsageMonitor`, `normalizeClaude`), `overLimit` em `lib/ai.ts`; `refreshUsage({maxAgeMs: 60_000})` nos 4 pontos que chamam `startRun` (`actions.ts`, `api/agent/runs`, `api/stories`, `api/characters/[id]/agent`); juiz: `AiConfig.over_limit` em `clipper/app/ai_settings.py` | `ai.test.ts`, `test_ai_fallback.py`, `doc/ia.md` | | API | `panel/src/app/api/ai/route.ts` (`GET/PUT /api/ai`), `.../ai/[provider]/route.ts` (`POST {action: install\|login\|verify\|test\|resume\|usage}`, `PUT/DELETE` = chave) | guarda `Origin`/JSON (gotchas, item 125) | | Tela | `panel/src/components/ai-settings.tsx` em `panel/src/app/settings/ai/page.tsx`; seletor de provedor em `agent-console.tsx` e `story-composer.tsx` | — | | Subpáginas de Configurações | `panel/src/app/settings/{ai,publishing,apps,browser,modes}/page.tsx` + `layout.tsx`; seções em `SETTINGS_SECTIONS` de `components/settings-shell.tsx` (o menu lateral `sidebar-nav.tsx` as lê como `children`); `/settings` redireciona para `/settings/ai` | seção nova = entrada em `SETTINGS_SECTIONS` + pasta | | Juiz do Clipador (3 provedores, reserva por chamada) | `clipper/app/judge.py` (`_gemini`, `find_gemini`, `parse_gemini_output`), leitura de settings e cofre `clipper/app/ai_settings.py` (DPAPI por `ctypes`), `main.py`, `config.py`, `intel.py` | `clipper/tests/test_ai_fallback.py`, `conftest.py`, `clipper/README.md` | ## Regras - **Só o painel escreve** `data/ai/settings.json` e `data/ai/vault.bin`; o Clipador só lê (relê por `mtime`). Cofre = DPAPI `CurrentUser`, entropia `CenaForge.AI.vault.v1`; a chave nunca volta à tela (só "existe" + 4 últimos caracteres). Nunca copie chave para skill, log ou prompt. - Chave de API entra **só no ambiente da chamada** (`providerEnv`); não troque o login global da CLI. - **Reserva:** erro de indisponibilidade (cota, 429, login, chave, rede, CLI fora, tempo) → a IA entra em pausa (`cooldownMin`, em memória por processo) e a **mesma tarefa recomeça** na próxima IA pronta de `order`. Erro de conteúdo (JSON/schema inválido) **não** troca. O juiz faz o mesmo por chamada. - Gemini no agente: `-o stream-json --approval-mode auto_edit --skip-trust`, `--resume `, shell só os comandos de `GEMINI_ALLOWED_SHELL` via `--allowed-tools run_shell_command(...)`. No juiz: `-o json --approval-mode plan`, prompt pelo stdin, frames copiados para pasta temporária **fora do repo** (`@arquivo` respeita o `.gitignore`). - Status de login: `claude auth status --json` (`loggedIn`, `authMethod`, `subscriptionType`); `codex login status` (texto, "Logged in using ChatGPT"). - Instalação: Claude pelo instalador nativo (`irm https://claude.ai/install.ps1 | iex`); Codex e Gemini por `npm install -g`. O painel procura também em `~/.local/bin` e `%APPDATA%\npm`. ## Monitor de uso e limite - **Leituras sem gastar token** (`ai-usage.ts`): Claude `claude -p "/usage"` (texto, US$ 0, modelo ``) e `rate_limit_event` de cada execução (`normalizeClaude`); Codex `codex app-server` (`account/rateLimits/read`); Antigravity `agy -p "/usage" --output-format stream-json`. **Gemini CLI: sem leitura**, só reativo (429). - Renova a cada 5 min (`ensureUsageMonitor`, ligado pelo `GET /api/ai`) e antes de cada tarefa (`maxAgeMs: 60_000`). - `overLimit` (`lib/ai.ts`): a IA bateu o limite, ou janela ainda valendo >= `fallback.usageLimitPercent` (padrão 90, faixa 50-100). Leitura com mais de 30 min não decide. `startRun` troca para a próxima IA livre; **em retomada (`resume`) não troca**. - O painel escreve `data/ai/usage.json`; o Clipador lê por `AiConfig.over_limit` e põe a IA acima do limite depois das livres em `fallback_chain`. UI: bloco "Uso do limite" por cartão, campo do limite no cartão da reserva, `POST /api/ai/[provider] {action:"usage"}`. - **Pronta:** IA cujo último teste falhou por indisponibilidade (login/cota) **não** é "pronta"; Gemini em modo conta só conta como pronto depois de um teste que passou. "Testar" continua habilitado. ## Antigravity (`agy`) - `agy.exe` em `~/.gemini/bin` (fora do PATH; `AGY_BIN` sobrescreve). Sem instalador por linha de comando (`install.command` null; a UI mostra o site). Login conferido por `agy models`; atualizar = `agy update`. - Agente: `agy -p --output-format stream-json --mode accept-edits [--conversation ]`; shell **só** por regra exata `command()` via `--settings` (gotchas 177). Eventos e formatos: `doc/ia.md`, "Antigravity no painel". - Começa desligado. **Aviso de termos:** a FAQ do Google diz que embrulhar o `agy` em programa de terceiro "não é suportado" nos planos pessoais; a decisão de ligar é do usuário. O juiz do Clipador **não** usa antigravity. ## Estado verificado (18/11/2026) - Nesta máquina: `claude` 2.1.314, `codex` 0.169.0, `agy` 1.5.10 (`--version` reconferido); `gemini` **não instalado**. - `pnpm --filter cenaforge-panel run test:panel`: 117/117 (reexecutado pela skill). `ai.test.ts` 30 testes (informado). Clipador: 346 passed (informado; reexecutado na 1.52.0). - Leituras reais informadas: Claude 4% / 67%; Codex janela de 5 h em 100% (`rate_limit_reached`), semanal 29%; Antigravity 12% / 5%. "Testar" do Antigravity respondeu "ok" em 15 s. - **Não verificado:** Gemini com chave real, `@arquivo` de imagem no juiz, envelope de erro do `-o json`, a UI `/settings/ai` no navegador, troca de IA no meio de um agente real, troca antecipada por `overLimit` em tarefa real. Armadilhas: gotchas, itens 168-172 e 175-179.