Files
CenaForge/doc/ia.md
T
MateuusandClaude Opus 5.5 76b722c499 Doc: Equipe de IA (doc/clipador/EQUIPE-IA.md) e contrato por papel em doc/ia.md
- EQUIPE-IA.md: papéis e configuração (judge.roles, migração), juiz de contexto e as regras
  de decisão pelo código, linha do tempo JSON + mosaico, medição (ai_calls, owner_label,
  GET /v1/judge/report) e o medido no corte 291 (analista −45%, varredura −38%, editor −20%;
  ≈ −29% por hora já com o juiz; 1 chamada real do juiz no Codex: 9.624 tokens de entrada).
- doc/ia.md: reserva por papel, codex exec --json e leitura de uso por CLI.
- README do Clipador: rotas /v1/judge e /v1/judge/report.
- judge.describe: uma checagem por provedor para todas as cadeias (o painel lê o status a
  cada poucos segundos); sem analista, o editor recebe as imagens no modo escolhido.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 04:44:56 -03:00

12 KiB
Raw Blame History

IA do CenaForge — provedores, login e reserva

18/11/2026 — Gemini CLI removido do painel. O login pela conta pessoal acabou (ver abaixo) e o Antigravity CLI (agy) o substitui com a mesma conta Google. Os provedores do painel são claude, codex e antigravity. Um settings.json antigo com "gemini" é ignorado. O juiz do Clipador não oferece mais o Gemini na tela; o código Python do Gemini (judge.py) ficou inativo, porque o painel não liga mais essa IA. As seções sobre o Gemini CLI abaixo ficam como histórico do estudo.

Três IAs, sempre pela CLI oficial instalada no PC (nunca SDK/HTTP direto):

Provedor CLI Instalação (Windows) Login com a conta (OAuth) Chave de API (variável)
claude Claude Code (claude) irm https://claude.ai/install.ps1 | iex claude auth login ANTHROPIC_API_KEY
codex Codex (codex) npm install -g @openai/codex@latest codex login (ChatGPT) CODEX_API_KEY (só no codex exec)
gemini Gemini CLI (gemini) npm install -g @google/gemini-cli@latest gemini interativo → "Login with Google" GEMINI_API_KEY

Gemini + OAuth (verificado em 18/11/2026, gemini-cli 0.68.0): o login gratuito "Gemini Code Assist for individuals" foi encerrado (IneligibleTierError: UNSUPPORTED_CLIENT, o Google manda migrar para o Antigravity). OAuth só funciona com plano elegível (Code Assist Standard/Enterprise, Workspace). Para conta pessoal, use a chave de API do Google AI Studio.

Quem usa: os agentes do painel (panel/src/lib/agents.ts) e a Equipe de IA do Clipador (clipper/app/judge.py: varredura, analista, editor e juiz, cada papel com o seu provedor/modelo — clipador/EQUIPE-IA.md). A configuração das IAs (login, chave, reserva) fica no painel em Configurações → IA (/settings/ai); qual IA cada papel usa, em Clipador → Ajustes → Juiz.

Arquivos compartilhados (contrato painel ↔ Clipador)

Ambos em data/ai/. Quem escreve é só o painel; o Clipador apenas lê (relê se o mtime mudar).

data/ai/settings.json (sem segredo)

{
  "version": 1,
  "providers": {
    "claude": { "enabled": true, "authMode": "oauth" },
    "codex":  { "enabled": true, "authMode": "oauth" },
    "gemini": { "enabled": false, "authMode": "apiKey" }
  },
  "order": ["claude", "codex", "gemini"],
  "fallback": { "enabled": true, "cooldownMin": 15 }
}
  • enabled: a IA pode ser usada (como principal ou reserva). Desligada, nunca é chamada.
  • authMode: "oauth" = a sessão já logada da CLI; "apiKey" = a chave guardada no cofre.
  • order: prioridade da reserva. A tarefa usa a IA escolhida (ou a preferida dela); se falhar por indisponibilidade, tenta a próxima da lista que estiver ligada e pronta.
  • fallback.enabled: liga a troca automática. cooldownMin: depois de uma falha de indisponibilidade, a IA fica "em pausa" esse tempo e é pulada (cada processo guarda a sua pausa em memória).
  • Arquivo ausente ou inválido = padrão acima, com claude e codex ligados em oauth e gemini desligado.

data/ai/vault.bin (chaves de API)

Um JSON {"claude": "sk-ant-…", "codex": "sk-…", "gemini": "AIza…"} (só as que existirem) cifrado com a DPAPI do Windows, escopo do usuário (CurrentUser), entropia b"CenaForge.AI.vault.v1". O arquivo é o blob cru da DPAPI. Só a mesma conta do Windows nesta máquina abre. A chave nunca volta para a tela: a API do painel só diz se existe e os 4 últimos caracteres.

Ambiente de cada chamada

Montado a partir do ambiente do processo, por provedor:

Provedor authMode = "oauth" authMode = "apiKey"
claude remove ANTHROPIC_API_KEY ANTHROPIC_API_KEY=<chave>
codex remove CODEX_API_KEY CODEX_API_KEY=<chave>
gemini GOOGLE_GENAI_USE_GCA=true, remove GEMINI_API_KEY GEMINI_API_KEY=<chave>, remove GOOGLE_GENAI_USE_GCA

Assim o login global de cada CLI não é tocado: o modo chave só vale para a chamada.

Clipador: uma IA por papel (18/11/2026)

  • Cada papel do Clipador (scan, analyst, editor, judge) tem provider + model (+ effort no Codex) em judge.roles (banco do Clipador). A reserva vale por papel: a cadeia começa na IA do papel e segue a order deste arquivo, com as mesmas regras (ligada, CLI, chave, pausa, perto do limite). Serviços gerais (tradução da fala, pesquisa de jogo, câmera) usam a IA do editor.
  • codex exec do Clipador roda com --json (eventos JSONL na saída padrão; a resposta continua em -o) e model_reasoning_effort do papel (padrão low; o juiz começa em medium).
  • Uso de tokens por chamada vai para ai_calls (Clipador): Codex = turn.completed.usage do --json; Claude = usage do envelope --output-format json (entrada = nova + criação + leitura de cache); Gemini = stats.models.*.tokens. Medido 18/11/2026: o Codex cobra ≈ 8 mil tokens fixos por chamada pela CLI (juiz com ≈ 1.450 de conteúdo → 9.624 de entrada).

O que conta como "indisponível" (dispara a reserva)

Falha que não é culpa do pedido: limite de uso ou cota (rate limit, 429, quota, usage limit, credit balance), sobrecarga (overloaded, 529, 503, unavailable), login ou chave (401, 403, unauthorized, not logged in, invalid api key, IneligibleTier), rede (ECONN, ETIMEDOUT, ENOTFOUND, network), CLI que não iniciou ou não foi encontrada, e tempo esgotado. Erro de conteúdo (JSON inválido, schema) não troca de IA.

Gemini CLI em modo headless (0.68.0)

  • Agente: gemini -p <prompt> -o stream-json --approval-mode auto_edit --skip-trust [-m <modelo>] [--resume <sessão>].
  • Eventos JSONL: init {session_id, model}, message {role, content, delta} (texto do assistente chega em pedaços), tool_use {tool_name, tool_id, parameters}, tool_result {tool_id, status, output, error}, error {severity: warning|error, message}, result {status, error?, stats}.
  • Respostas estruturadas (juiz): -o json devolve {"response": "<texto>", "stats": …}; não há --output-schema, então o schema vai no prompt e o JSON é extraído do texto. Leitura somente: --approval-mode plan --skip-trust, rodando numa pasta temporária fora do repositório (o @arquivo respeita o .gitignore).
  • Modelos: gemini models -o json (não exige login).
  • No Windows o npm instala gemini.cmd; rode node <prefixo npm>/node_modules/@google/gemini-cli/bundle/gemini.js.

Estudo: uso e limites de cada IA pela CLI (18/11/2026)

Objetivo: mostrar quanto de cada IA já foi usado, trocar de IA ANTES de bater o limite e, se bater, mostrar o uso e quando volta. Medido nesta máquina (claude 2.1.314, codex-cli 0.169.0, gemini-cli 0.68.0).

IA Como ler o uso Custo da leitura O que vem
Claude (assinatura) claude -p "/usage" --output-format stream-json --verbose zero (modelo <synthetic>, 0 tokens, US$ 0) texto: "Current session: 2% used · resets …", "Current week (all models): 67%", "Current week (Fable): 24%"
Claude (em toda execução) evento rate_limit_event do stream-json (vem logo após o init) zero (já vem junto) unifiedWindows.five_hour/seven_day.utilization (0–1), resetsAt (epoch), status (allowed…), overageStatus, isUsingOverage
Codex (ChatGPT) codex app-server (JSON-RPC por stdin): initialize → initialized → account/rateLimits/read zero (não roda modelo) primary (janela 300 min) e secondary (10080 min): usedPercent, resetsAt; ordinaryUsageAllowed, rateLimitReachedType, planType, créditos de reset grátis
Codex (histórico) ~/.codex/sessions/AAAA/MM/DD/rollout-*.jsonl, evento token_count.rate_limits (limit_id: "codex") zero mesmo conteúdo, com a hora em que foi gravado
Gemini (chave) não há consulta de cota restante pela CLI nem pela API do AI Studio — só reativo: erro 429 RESOURCE_EXHAUSTED; o CLI distingue RetryableQuotaError (por minuto, traz retryDelay) de TerminalQuotaError (cota do dia acabou)

Observações:

  • No teste, o Codex estava com a janela de 5 h em 100% (rate_limit_reached, ordinaryUsageAllowed: false): com a leitura prévia, o painel o teria pulado em vez de esperar a falha.
  • Cuidado no Git Bash: /usage vira caminho (C:/Program Files/Git/usage) e a CLI cobra uma resposta normal. O painel chama sem shell, então não é afetado; no terminal use MSYS_NO_PATHCONV=1.
  • claude -p "/usage" devolve texto em inglês, com datas no fuso local: o parser precisa ser tolerante e preferir o rate_limit_event (estruturado) quando houver execução recente.
  • Gemini com chave: contar nós mesmos as requisições e tokens do dia (o result do stream-json traz stats) e pausar até o reset diário quando vier TerminalQuotaError.

Implementado (18/11/2026)

  • panel/src/lib/ai-usage.ts: leitura do Claude (/usage + rate_limit_event de cada execução) e do Codex (app-server), monitor de 5 min (liga ao abrir Configurações → IA) e releitura antes de cada tarefa (> 60 s).
  • overLimit (lib/ai.ts): bateu o limite ou janela ainda valendo ≥ fallback.usageLimitPercent (padrão 90) → a tarefa nova começa na próxima IA livre; leitura com mais de 30 min não decide.
  • data/ai/usage.json (escrito pelo painel): {updatedAt, limitPercent, providers: {<ia>: {at, windows[], blocked, …}}}. O juiz do Clipador lê (AiConfig.over_limit) e põe a IA perto do limite depois das livres.

Gemini pela conta: Antigravity CLI (pesquisa de 18/11/2026)

  • O gemini-cli não aceita mais conta pessoal (nem AI Pro/Ultra) desde 18/06/2026; Code Assist Standard/Enterprise não vende assinatura nova desde 09/10/2026. Fonte: developers.google.com/gemini-code-assist/docs/deprecations/code-assist-individuals
  • Substituto oficial: Antigravity CLI (%USERPROFILE%\.gemini\bin\agy.exe, 1.5.10 nesta máquina, fora do PATH). Headless parecido com o Claude: agy -p <prompt> --output-format stream-json --mode accept-edits [--model] [--effort] [--conversation <id>]; agy models funciona com a conta logada (Gemini 4, Gemini 3.8 Flash, Claude, GPT-OSS).
  • Termos: a FAQ (antigravity.google/docs/faq) diz que embrulhar o agy em app de terceiro "is not supported under consumer plans"; recomenda chave do AI Studio ou Gemini Enterprise. Respostas de funcionários no fórum se contradizem. Zona cinza: decisão do usuário.
  • Os três pontos que estavam em aberto (saída sem TTY, edição com accept-edits, formato do stream-json) foram testados e funcionam: ver "Antigravity no painel" abaixo.

Antigravity no painel (implementado em 18/11/2026, agy 1.5.10)

Testado de verdade nesta máquina (prompts mínimos, conta Google logada):

  • Sem terminal funciona: agy -p "…" --output-format stream-json chamado pelo Node respondeu em ~6 s.
  • Eventos: {"event":"init","conversation_id"}, step_update (step_type: user_input | agent_response com text_delta | tool com tool_name, tool_info.parameters e state ACTIVE/DONE/ERROR; usage por passo) e {"event":"result","result":{status:"SUCCESS",response,num_turns,usage}}. Retomada: --conversation <id>.
  • Edição: --mode accept-edits grava arquivos sem pedir.
  • Shell: só com --settings '{"permissions":{"allow":["command(<linha exata>)"]}}' (vale só na sessão). Testado: command(node --version) libera exatamente essa linha; prefixo, command(node), command(node:*) e command(node -e *) NÃO liberam. O que não estiver liberado é recusado (passo ERROR + aviso jetski: no stderr; o processo sai com 0). Não usamos --dangerously-skip-permissions.
  • Uso, sem cota: agy -p "/usage" --output-format stream-json → {"event":"command_result","command":{"name":"usage", "data":{"groups":[{"name":"Gemini Models","buckets":[{"window":"5h"|"weekly","remaining_fraction":0.88,"reset_time"}]}, {"name":"Claude and GPT models",…}]}}}. O painel usa o grupo Gemini (modelos padrão do agente).
  • Login: agy models só lista com a conta logada (sem gastar cota); "Entrar com a conta" abre agy interativo.
  • Modelos: agy models → linhas id<TAB>nome (18 nesta conta), depois de uma linha "Fetching available models...".
  • Começa desligado; o juiz do Clipador ainda não usa o Antigravity (só agentes do painel).