# IA: três provedores, login/chave e IA reserva 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`), nunca SDK/HTTP direto. ## 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`, `--resume`, 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) | | API | `panel/src/app/api/ai/route.ts` (`GET/PUT /api/ai`), `.../ai/[provider]/route.ts` (`POST {action: install\|login\|verify\|test\|resume}`, `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`. ## Estado verificado (18/11/2026) - Nesta máquina: `claude` 2.1.314 e `codex` 0.169.0 (`--version` reconferido pela skill); `gemini` **não instalado** (`command not found`). - `pnpm --filter cenaforge-panel test:panel` inclui `ai.test.ts`: 21 testes, 21 passaram (reexecutado pela skill; um usa a DPAPI real). Clipador: `pnpm test:clipper` → 335 passed (reexecutado). Suíte do painel 104/104: informada. Ida e volta real do cofre painel → Clipador: informada, não repetida. - **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. Armadilhas: gotchas, itens 168–172.