Antigravity MCP Bridge
by Zythenth
README.md
# Antigravity MCP Bridge
Servidor MCP local para delegar tarefas de programação ao Google Antigravity por meio do CLI oficial `agy`. O Codex pode iniciar tarefas, acompanhar eventos, consultar resultados e cancelar processos. O projeto é independente e não é afiliado ao Google ou à OpenAI.
```text
Codex -- MCP stdio --> bridge -- subprocesso --> agy oficial --> Antigravity
Codex <-- eventos e resultado estruturados <-- bridge <-- stdout/stderr
```
O bridge não acessa endpoints privados, cookies ou os armazenamentos de autenticação do CLI. Para candidatos a arquivos do projeto, o bridge realiza apenas inspeção local durante o preflight preventivo antes da cópia. A comunicação com o serviço é feita pelo próprio `agy`.
## Requisitos
- Node.js 24 ou mais recente e npm. Esse requisito inicia o servidor; no Windows LPAC, ele não garante a compatibilidade de todos os subprocessos Node.
- Git 2.32 ou mais recente, disponível em uma entrada absoluta do `PATH`. Versões anteriores falham na admissão porque não oferecem o isolamento de configuração global exigido pelo bridge.
- [Antigravity CLI oficial](https://www.antigravity.google/docs/cli/install/) instalado e disponível no `PATH` (fonte primária de instalação). Você também pode definir `AGY_PATH` com o caminho absoluto do executável.
- Autenticação oficial concluída no `agy`. O CLI gerencia credenciais por meio dos mecanismos nativos do sistema operacional: Windows Credential Manager, macOS Keychain ou Linux Secret Service (via D-Bus). O bridge preserva diretórios de perfil e configuração, sessão de segurança, D-Bus, proxy, certificados, `GEMINI_API_KEY` e `GOOGLE_GEMINI_BASE_URL`. Variáveis de Google Application Default Credentials (ADC) e de ambientes corporativos (`GOOGLE_APPLICATION_CREDENTIALS`, `GOOGLE_CLOUD_PROJECT`, `GCLOUD_PROJECT`, `GOOGLE_CLOUD_UNIVERSE_DOMAIN`) são preservadas no ambiente por compatibilidade; o fluxo Enterprise não foi validado ponta a ponta. Consulte a [documentação oficial do modo headless](https://www.antigravity.google/docs/cli/headless/).
A descoberta (`discover`) do CLI executa `--version` e `--help`, exigindo exit code 0 em ambas as chamadas, saída não vazia e anúncio obrigatório das capacidades `stream-json` e `--sandbox`. Se o executável não for encontrado, a permissão for negada, a sondagem falhar ou o CLI não for compatível, o bridge emite os diagnósticos `AGY_NOT_FOUND`, `AGY_PERMISSION_DENIED`, `AGY_PROBE_FAILED` ou `AGY_INCOMPATIBLE`.
O bridge foi validado com `agy` 1.3.2 e `@modelcontextprotocol/sdk` 1.30.1. As tarefas delegadas exigem que o CLI anuncie `--sandbox` e `stream-json`; versões futuras podem exigir adaptação. No Windows, `antigravity_test` usa por padrão o executor local do bridge em AppContainer/LPAC; nos demais sistemas, usa o sandbox oficial do `agy`.
O Git local usa um ambiente próprio, com `PATH` restrito a diretórios fora do projeto e da cópia. Hooks, fsmonitor e configurações globais de execução ficam desativados; as regras de ignore são consultadas separadamente. Isso preserva a política de autenticação do `agy`. Quando o encerramento de um processo Git não pode ser comprovado após solicitação de término e janela delimitada de tolerância (pipes retidos), a operação falha com `GIT_CLEANUP_UNVERIFIED`, destruindo stdio e bloqueando a cópia com marcador no baseline privado para impedir reutilização, prévia, integração ou exclusão insegura de recursos potencialmente retidos, sem alegar falsamente limpeza comprovada.
Alterações textuais com bytes não-UTF-8 falham com `UNSUPPORTED_PATCH_ENCODING`, evitando corrupção na aplicação. Declare esses arquivos como `binary` no `.gitattributes` para obter patches binários do Git que preservem os bytes originais.
## Versões disponíveis
Os exemplos de instalação selecionam a **0.9.0**. Consulte a [página do pacote no npm](https://www.npmjs.com/package/antigravity-mcp-bridge) para conferir a versão distribuída.
A 0.9.0 inclui o Anti-AI Craft com as skills de código e segurança sempre carregadas e as demais sob demanda, redação de erros, frames, deltas, mensagens e estado antes da persistência, recusa de credenciais em entradas operacionais, confirmação do encerramento dos processos de cada execução, regras de delegação com restauração do fim de linha original nas prévias, sanitização única do estado salvo por versões anteriores e cancelamento efetivo de testes Windows recém-enfileirados.
A 0.8.0 acrescenta workflows no servidor, checkpoints, hooks de validação, memória privada, perfis completos, seleção de MCPs e ferramentas por tarefa, responsáveis e dependências, mensagens entre nós, espera conjunta, resultados JSON, artefatos com hashes e orçamento por consumo observado.
A 0.7.1 preserva entrega compacta, mensagens por sessão, skills selecionadas, execução simultânea e autorização prévia de integração, além das correções do Windows.
A 0.6.1 inclui executor Windows do bridge, permissões de sandbox controladas por ferramentas MCP e um runtime Node portátil opcional para LPAC. O runtime está publicado em um Release imutável; prepare-o explicitamente antes de usar o modo portátil.
A 0.5.1 inclui perfis, espera com progresso, transferência entre papéis, comparação de modelos e papéis personalizados. Ela amplia a margem de observação dos testes para suportar a preparação de cópias em runners mais lentos, preservando as verificações dos timeouts de execução.
## Instalação
### Servidor MCP via npm/npx
Para iniciar o servidor pelo pacote npm 0.9.0, configure seu cliente MCP com:
```json
{
"mcpServers": {
"antigravity": {
"command": "npx",
"args": ["--yes", "antigravity-mcp-bridge@0.9.0"]
}
}
}
```
No Windows, clientes que exigem o nome completo do comando podem usar `npx.cmd`. O executável inicia o servidor em stdio; não é um comando interativo. O pacote contém o servidor compilado e os avisos das dependências incluídas. Node.js 24, Git e o `agy` autenticado continuam necessários. Para validar uma versão ainda não publicada, use `npm run build:plugin`, `npm pack` e o tarball local com `npx --yes --package <caminho-do-tarball> antigravity-mcp-bridge`.
### Instalação pelo código-fonte
Os exemplos PowerShell usam `npm.cmd`, o lançador do npm para Windows, que funciona mesmo quando a política de execução bloqueia `npm.ps1`. Em outros shells, use `npm`.
```powershell
git clone https://github.com/Zythenth/antigravity-mcp-bridge.git
cd antigravity-mcp-bridge
npm.cmd ci
npm.cmd run build:plugin
npm.cmd test
```
`npm run build:plugin` compila o servidor e gera `plugin/server.mjs`. Esse arquivo também acompanha o repositório para que o plugin possa ser instalado sem executar o build. `npm start` inicia o servidor MCP em stdio; a saída padrão fica reservada para JSON-RPC.
### Runtime Node portátil no Windows LPAC
O servidor iniciado diretamente por npm usa o Node do sistema por padrão. O descritor distribuído com o plugin pede o modo `portable`, para que os testes Windows LPAC usem o runtime preparado no cache. Os modos são escolhidos somente na inicialização confiável do servidor com `BRIDGE_WINDOWS_NODE_RUNTIME=system` ou `portable`; entradas de ferramentas MCP não aceitam URL, hash nem caminho de cache.
No Windows, a inspeção do cache usa um helper nativo incluído no pacote, compilado com o .NET Framework já existente no sistema. O compilador também é necessário para consultar o estado do runtime portátil. Essa verificação lê os atributos e as marcas dos caminhos diretamente, sem iniciar PowerShell. O inspetor e a validação de caminhos de permissões aceitam as marcas `IO_REPARSE_TAG_CLOUD` a `IO_REPARSE_TAG_CLOUD_F`, usadas pelo OneDrive, e rejeitam junctions, links simbólicos e marcas desconhecidas em qualquer ancestral. Arquivos somente na nuvem precisam estar disponíveis para leitura. O cache continua separado do projeto. Compilação e inspeção compartilham um prazo de 15 segundos; os arquivos temporários do helper são removidos ao final.
Consulte o estado sem iniciar MCP, descobrir `agy` ou baixar arquivos:
```powershell
node plugin/server.mjs --windows-runtime-status
```
No Windows x64, prepare explicitamente o runtime antes de usar o modo portátil:
```powershell
node plugin/server.mjs --prepare-windows-runtime
```
Para preparar o runtime pelo pacote npm 0.9.0:
```powershell
npx --yes antigravity-mcp-bridge@0.9.0 --prepare-windows-runtime
```
O status retorna JSON com `requestedMode`, `supported`, `ready`, `buildId`, `nodeVersion`, `libuvVersion`, `sha256` e, quando necessário, `error`. Uma consulta sem suporte, sem cache ou com cache inválido continua sendo uma consulta bem-sucedida; uma falha de preparação retorna exit code 1. Preparação baixa somente os arquivos declarados do GitHub Release, confere tamanho e SHA-256 e instala o cache privado de forma atômica. Em caches situados em pastas sincronizadas (como OneDrive), toleram-se contagens extras ou transitórias de links (`nlink`) exclusivamente na **leitura de assets** com descritor confiável, tamanho e SHA-256 fixados, no **staging da fonte do Node portátil** com `expectedSha256`, e no **lock de preparação** do Node portátil (desde que `device`, `inode` e `size` permaneçam idênticos e o nonce/payload exato seja conferido, liberando com `unlink` apenas a entrada do próprio processo para preservar aliases). Hash, tamanho, identidade de arquivo, marcas reparse e layout de diretório permanecem estritamente obrigatórios; qualquer conteúdo alterado é recusado e aliases não são modificados. Destinos de runtime, executáveis genéricos e concessões de ACL continuam exigindo link único. O `StateStore` não oferece suporte genérico a armazenamento em nuvem. Inicialização, saúde e testes não baixam arquivos. Cache ausente no modo portátil exige `--prepare-windows-runtime`, sem voltar silenciosamente ao Node do sistema. Cache corrompido, alterado ou inseguro é recusado também pela preparação, que não o repara nem remove automaticamente. Antes de preparar novamente, uma pessoa deve inspecionar o caminho e remover manualmente somente o cache do build afetado; depois, executar `--prepare-windows-runtime`.
Mantenha o cache fora dos projetos. O bridge resolve os caminhos reais e recusa sobreposição em ambas as direções entre o projeto e `BRIDGE_WINDOWS_NODE_CACHE_DIRECTORY`, antes de consultar modelos, enfileirar a tarefa ou copiar arquivos. Essa regra também vale com `includePaths` e no modo `system`.
O runtime [Node 24.21.0 LPAC1 para Windows x64](https://github.com/Zythenth/antigravity-mcp-bridge/releases/tag/runtime-node-v24.21.0-lpac1-win-x64) está publicado em um Release imutável, com ABI 137, libuv base 1.52.1 e apenas o PR 5181 aplicado. Ele não declara suporte geral a outras versões, arquiteturas ou plataformas. O cache instala somente `node.exe`, a `LICENSE` upstream e `build.json`; este último registra a fonte fixada, o patch, a ferramenta de compilação e a proveniência da execução. A seleção substitui somente o `process.execPath` conhecido desse runtime e o `npm` adjacente validado; executáveis Node ou npm personalizados permanecem selecionados como foram informados. A substituição portátil inicial de `process.execPath` e do `npm` adjacente exige Node 24 no host do servidor. O requisito geral Node >=24 permite iniciar o servidor, mas hosts Node 25/26 falham em testes elegíveis com `PORTABLE_NODE_HOST_UNSUPPORTED`. O cache persiste entre reinicializações normais do processo e do servidor, mas a persistência através de uma reinicialização física ainda não foi verificada.
### Instalar como plugin do Codex
O repositório contém um catálogo em `.agents/plugins/marketplace.json` e o plugin em `plugin/`. Instale o catálogo e o plugin:
```powershell
codex plugin marketplace add Zythenth/antigravity-mcp-bridge
codex plugin add antigravity@antigravity-mcp-bridge
```
Para atualizar, execute `codex plugin marketplace upgrade antigravity-mcp-bridge` e `codex plugin add antigravity@antigravity-mcp-bridge`. Abra uma **nova conversa** depois da instalação ou atualização. Peça, por exemplo: “Use `$antigravity` para implementar esta mudança e revisar o resultado.” A skill orienta a escolha de modelos, o acompanhamento da tarefa e a revisão final. Sessões já abertas não recarregam as ferramentas do plugin. Se o aplicativo não encontrar `agy`, configure `AGY_PATH` no ambiente em que o Codex é iniciado.
O [guia oficial de plugins](https://developers.openai.com/plugins/build/plugins) explica o formato do catálogo e outras opções de instalação.
### Registrar somente o servidor MCP
Para usar o bridge sem a skill do plugin, compile o projeto e registre o servidor:
```powershell
$server = (Resolve-Path .\dist\src\index.js).Path
codex mcp add antigravity -- node $server
```
Há também um [exemplo de configuração TOML](codex-mcp-example.toml). Use **uma** forma de registro por vez para evitar ferramentas duplicadas.
## Perfis de ferramentas
Defina `BRIDGE_TOOL_PROFILE` no ambiente do servidor e reinicie a conexão MCP:
| Valor | Ferramentas | Catálogo e execução |
| --- | --- | --- |
| `full` (padrão) | 50 | Todas as ferramentas; preserva a configuração existente |
| `query` | 36 | Consulta, modelos, sessões, handoff, comparação e consulta da política de sandbox; tarefas somente em leitura |
| `review` | 39 | Consulta mais prévia, leitura de patches e verificação; tarefas somente em leitura |
| `implementation` | 50 | Fluxo completo, incluindo testes, integração confirmada e descarte |
O perfil é informado em `antigravity_health.toolProfile`. Ferramentas fora do perfil não são registradas e chamadas diretas são recusadas. `query` e `review` também recusam `mode: "write"`; omitir o modo seleciona leitura. Perfis reduzem o catálogo e restringem essas tarefas; o sandbox e a política de autorização da integração continuam necessários. Valores desconhecidos impedem a inicialização.
## Espera com progresso
Prefira `antigravity_wait` com `taskId`, `after` e `timeoutSeconds` (1–60, padrão 30). Clientes que enviam `_meta.progressToken` recebem notificações `notifications/progress` com a sequência e o tipo de eventos reais, incluindo ferramentas, recibos de testes e conclusão. O número é um cursor de eventos, sem total ou porcentagem. Nenhum texto de arquivo, prompt ou saída do terminal é enviado nessas notificações.
A resposta inclui `ready`, `timedOut`, estado, uso de tokens e até 1.000 eventos. Continue com `nextCursor`; `truncated` informa eventos antigos perdidos. Timeout da espera e cancelamento da chamada MCP preservam a execução. Para parar a tarefa, use `antigravity_cancel`. Sem suporte a progresso, a resposta final continua disponível. A espera consulta também o estado persistido para observar tarefas de outro processo do bridge.
## Transferência entre papéis
Use `antigravity_context` após uma tarefa concluída para inspecionar critérios, relatórios e `treeSha256`. Em seguida, chame `antigravity_handoff` com `sourceTaskId`, esse hash, `role`, `prompt` e, opcionalmente, `model` e `decisions`.
A nova tarefa recebe uma cópia independente dos arquivos atuais, incluindo alterações ainda não integradas. Mantém o baseline do projeto original, critérios, até oito relatórios de planejamento/revisão e a origem dos testes. Decisões são marcadas como relatos do cliente; relatórios e recibos mantêm sua origem e não autorizam integração. O pacote de contexto inteiro deve caber no limite do prompt; não há corte silencioso.
Planejamento → implementação → revisão pode mudar de papel e modelo sem reusar a conversa do papel anterior. O contexto é dado a conferir, não uma instrução de prioridade superior. Hashes são conferidos ao aceitar a tarefa e ao copiar, também quando ela aguardou na fila. A revisão verifica que sua cópia permaneceu intacta, incluindo arquivos ignorados. A cópia da implementação permanece disponível para testes, verificação e integração confirmada. Uma implementação iniciada a partir da revisão preserva o patch acumulado contra o original.
A cópia continua respeitando os ignores do projeto e limites de arquivos/bytes. Se a seleção mudar por novas regras de ignore, o handoff falha; inspecione o contexto novamente. Não inclua segredos em decisões. `antigravity_resume` conserva papel e cópia; `antigravity_handoff` cria outro papel em outra cópia e sessão.
## Comparação entre modelos
Após `antigravity_context`, chame `antigravity_compare` com `sourceTaskId`, `expectedContextSha256`, `prompt` e `models` contendo 2 a 4 IDs distintos devolvidos por `agy models`. Cada modelo recebe uma cópia independente da mesma versão e executa uma revisão em leitura. A comparação consome a quota de cada tarefa; respeita `MAX_CONCURRENT_TASKS`, fila, retenção e limites de cópia. As cópias são preparadas antes de iniciar o grupo, evitando que revisores disputem a cópia de origem.
Guarde `comparisonId` e acompanhe cada `taskId` com `antigravity_wait`. `antigravity_comparison` reúne pareceres, erros, uso de tokens, modelos ausentes e os achados por arquivo/linha/citação. `identical` significa achados literalmente iguais; `different`, interpretações diferentes no mesmo trecho; `not-reported-by-all`, um trecho não relatado por todos. Ausência de achados não prova concordância nem correção.
`complete` exige todos os pareceres concluídos e suas cópias ainda correspondentes ao conteúdo comparado. `contextStale` sinaliza que a origem ou alguma cópia mudou, ficou indisponível ou não pôde ser conferida; confira `contextMatches` por parecer. Erros de início ficam em `startErrors`; falhas ou tarefas removidas não são ocultadas. O Codex deve conferir as fontes e sintetizar recomendações, divergências e limites de cada parecer. O agrupamento não faz votação semântica e não autoriza integração. As tarefas de comparação podem ser canceladas e descartadas individualmente.
## Limites de interação e contagem prévia
`antigravity_health.bridgeLimitations` informa duas capacidades indisponíveis:
- `interactiveReplies.available: false`: o [protocolo headless verificado](https://www.antigravity.google/docs/cli/headless/#unsupported-messages) recusa `control_request` e `control_response`. Mensagens de texto em novos turnos não respondem a solicitações pendentes de permissão. O bridge encerra o stdin após seu prompt; para continuar a conversa concluída, use `antigravity_resume`. Examine pedidos negados nos eventos e erros, sem contornar o sandbox. A confirmação MCP da integração continua sendo uma operação separada do bridge.
- `preflightTokenCount.available: false`, `exactTokens: null`: não há comando do agy verificado para contar tokens antes do envio. O uso informado pelo CLI é observado após execução. Tamanho em caracteres não é uma contagem exata de tokens nem um orçamento de quota. O bridge permanece no CLI oficial, sem API adicional, novas credenciais ou estimador apresentado como contagem exata.
Essas limitações não são resolvidas por manter o processo aberto ou inventar mensagens do protocolo. Um suporte futuro exige verificar a versão e o contrato oferecido pelo CLI antes de adicionar a operação.
## Entrega ao agente principal
Use `deliveryMode: "messages"` em `antigravity_run` para receber perguntas públicas estruturadas, bloqueios e um trecho do resultado final. `antigravity_wait` devolve `messages` e cursores de mensagens, sem os eventos e notificações de progresso detalhados. Uma pergunta observada pode encerrar a espera antes do fim da tarefa. O principal lê resultados e diffs completos somente quando necessários, pelas ferramentas de leitura em partes.
Cada mensagem inclui origem, modelo informado, ID, sequência e data; cada texto tem no máximo 2.000 caracteres. Até 100 mensagens são retidas por tarefa e as páginas indicam perdas de mensagens antigas. O resultado final aponta para `antigravity_read_result`, com o hash correspondente. As mensagens do modelo continuam sendo relatos, sem comprovar testes nem autorizar integração.
Omitir a opção conserva `events`, com o histórico de eventos existente. `antigravity_events` continua disponível para uma consulta detalhada explícita. `antigravity_set_delivery_mode` muda a entrega de uma tarefa; reinicie o cursor em `after: 0` após trocar de modo. Passe também `cursorMode` com o modo do cursor anterior: se o modo de entrega mudar, a espera reinicia em zero e informa `cursorReset: true`. A retomada herda a escolha, que não altera permissões ou papéis.
## Execução simultânea
A instalação do plugin configura duas tarefas simultâneas; o servidor independente mantém uma por padrão. `MAX_CONCURRENT_TASKS` aceita 1 a 16. Retomadas da mesma cópia continuam sequenciais.
## Mensagens para a sessão
Use `antigravity_send_message({taskId, messageId, text})` para enviar até 2.000 caracteres; `messageId` é um UUID escolhido pelo cliente. Repetir o mesmo ID e texto retorna o recibo existente. Outro texto com o mesmo ID é recusado. Até 20 inputs ficam retidos por tarefa.
Se o turno estiver ativo, o recibo fica `queued`. Após sua conclusão, o bridge retoma a sessão oficial na mesma cópia e processa os inputs em sequência. `sent` indica aceitação do novo turno pelo bridge, sem provar que o modelo leu a mensagem. Falhas e cancelamento ficam explícitos; um envio interrompido sem evidência de aceitação não é repetido automaticamente.
Acompanhe `continuationTaskId` com um novo cursor em zero. `continuationPending: true` em `antigravity_wait` indica inputs aguardando despacho; o término do turno anterior não encerra toda a conversa. Retomadas preservam seleção, skills, papel, modo e critérios. Mensagens não concedem permissões nem aprovam integração; solicitações de controle do agy continuam indisponíveis.
## Modos de aprovação e integração
O servidor MCP suporta modos de aprovação controlados pela variável `BRIDGE_APPROVAL_MODE` no ambiente do servidor. Quando a variável não estiver definida (unset), o modo padrão é `auto`. Os valores aceitos são estritamente `auto` ou `ask`; valores inválidos causam erro na inicialização.
- **Modo automático (`auto`, padrão)**: `antigravity_integrate` autoriza automaticamente a integração de alterações quando o patch estiver verificado contra o hash atual, dispensando formulários interativos MCP de confirmação humana. Atualizações validadas da política de sandbox (`antigravity_set_sandbox_policy`) também são aplicadas automaticamente. Nenhuma confirmação manual extra é exigida do chamador em `auto`. O chamador pode propor concessões estreitas e verificadas necessárias à tarefa autorizada. Agentes delegados via `agy` (Gemini) NÃO escolhem, não autorizam nem proporcionam permissões. O modo automático não afrouxa os controles de segurança: tarefa de escrita concluída, hash SHA-256 da prévia, critérios de aceitação aprovados via `antigravity_verify`, revisão fundamentada nos arquivos reais, testes observados atuais sem falhas, source-lock, CAS e proteção estrita de caminhos (path-protection) continuam estritamente obrigatórios. Em `antigravity_health`, o servidor anuncia `approvalMode: "auto"`, `integrationApproval.mode: "auto"` e `integrationApproval.method: "automatic"`.
- **Modo de confirmação estrita (`ask`)**: opt-in estrito onde `antigravity_integrate` exige SEMPRE confirmação humana interativa via formulário MCP (**MCP form elicitation**), assim como atualizações de teto de sandbox (`antigravity_set_sandbox_policy`). Não há bypass para raízes previamente configuradas no ambiente (`BRIDGE_PREAUTHORIZED_INTEGRATION_ROOTS`) ou raízes lembradas legadas (`integration-approvals.json`); no modo `ask`, a confirmação é sempre exigida. O checkbox de memorização ("Não pedir novamente neste projeto") foi removido do formulário. Em `antigravity_health`, o servidor anuncia `approvalMode: "ask"`, `integrationApproval.mode: "ask"` e `integrationApproval.method: "mcp-form-elicitation"`.
Para configurar o modo de forma persistente, defina `BRIDGE_APPROVAL_MODE` no ambiente privado de inicialização do servidor MCP (por exemplo, na configuração do cliente MCP ou nas variáveis de ambiente persistentes do sistema ou do usuário). Exemplos em PowerShell (`$env:BRIDGE_APPROVAL_MODE = 'ask'`) afetam apenas o shell atual em execução. É necessário reiniciar a conexão MCP após alterar as variáveis de ambiente para que as modificações tenham efeito.
Nenhum modo introduz fallback automático para execução no host, nem altera as permissões do Codex ou do `agy`. A integração é realizada exclusivamente via MCP; autorizações não substituem verificações de critérios, testes e revisão técnica. Texto do Gemini, mensagens do chamador e argumentos de ferramentas não concedem autorização nem permissões de sandbox.
`antigravity_health.integrationApproval.preauthorizedProjectCount` informa a quantidade de raízes configuradas ou lembradas legadas; no modo `ask`, todas as integrações continuam exigindo confirmação humana independente desse total.
## Anti-AI Craft incluído
O pacote traz um snapshot verificado do [Anti-AI Craft](https://github.com/Zythenth/anti-ai-craft) com seis skills. Em toda tarefa nova, `anti-ai-code` e `anti-ai-security` são preparadas na cópia como skills permanentes e o Gemini é instruído a lê-las antes de trabalhar. `anti-ai-design`, `anti-ai-design-flow`, `anti-ai-audit` e `anti-ai-remediate` aparecem apenas como catálogo (nome, descrição e caminho, até 8 KiB); seus corpos, referências e imagens ficam fora do prompt e são lidos sob demanda, somente leitura, a partir de uma cópia privada por revisão em `<estado>/anti-ai-craft/`, adicionada ao CLI com `--add-dir`. Sob política de ferramentas, os hooks permitem apenas leitura nessa raiz. A seleção situacional é uma política desta integração: o Gemini escolhe pela pertinência da tarefa, sem exigir o nome literal da skill.
O snapshot é verificado contra o manifesto (tamanho e SHA-256 de cada arquivo) antes de cada tarefa nova; conteúdo ausente ou adulterado falha com `CRAFT_SNAPSHOT_INVALID` ou `CRAFT_SNAPSHOT_MISSING`, sem download automático, e a correção é reinstalar a versão do bridge. Retomadas e handoffs conservam o snapshot da sessão original. As permanentes contam no limite de oito pacotes e de 1 MiB das skills fornecidas; uma skill fornecida com o mesmo nome e conteúdo idêntico é deduplicada, e conteúdo diferente falha com `SKILL_CONFLICT`. Arquivos das skills não entram no patch.
`BRIDGE_ANTI_AI_CRAFT=off` desativa a política para todas as tarefas. `BRIDGE_ANTI_AI_CRAFT_DIRECTORY` aponta para outro snapshot com o mesmo formato, que também é verificado contra o próprio manifesto. Disponibilizar as skills não instala o MCP do Anti-AI Craft, Graphify, Python ou outras ferramentas que elas mencionem. As imagens da biblioteca visual mantêm as licenças de suas fontes; consulte [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
## Skills fornecidas pelo cliente
O Codex ou outro cliente pode enviar skills selecionadas em `antigravity_run.skills`. No modo compacto, `providedSkillSummaries` contém apenas nome, hash e quantidade de arquivos. Cada pacote contém o texto de `SKILL.md` e, opcionalmente, recursos de texto com caminhos relativos à skill:
```json
{
"workingDirectory": "/caminho/absoluto/do/projeto",
"prompt": "Use a skill review-style para revisar o projeto.",
"mode": "read-only",
"skills": [{
"name": "review-style",
"content": "---\nname: review-style\ndescription: Regras de revisão\n---\nLeia references/check.md antes de revisar.",
"resources": [{ "path": "references/check.md", "content": "Confira os requisitos contra os arquivos reais." }]
}]
}
```
O bridge prepara apenas os pacotes enviados em `.agents/skills/<nome-em-minúsculas>/` dentro da cópia. Preserva o nome declarado e os bytes UTF-8, incluindo nomes como `Presentations`. Os metadados retornados contêm nomes, caminhos relativos e hashes; não repetem os textos das skills. Skills globais não são descobertas nem importadas automaticamente. O cliente deve selecionar e fornecer também os recursos necessários, mantendo arquivos privados e credenciais fora do envio.
Limites: 8 skills, 100 recursos por skill e 1 MiB de texto no total. Esses arquivos também contam nos limites de arquivos e bytes da cópia. Caminhos absolutos, travessia, nomes de dispositivos, aliases de caixa, links e colisões com pastas existentes na cópia são recusados. O preparo não executa os scripts fornecidos. Dependências de ferramentas precisam existir no agy; uma skill não concede novas permissões.
A retomada e o handoff conservam os pacotes originais e seus hashes. Não é possível fornecer `skills` novamente numa retomada, mesmo como lista vazia; use uma nova tarefa para outra seleção. Alterar, remover ou acrescentar recursos numa skill fornecida invalida a verificação. Os arquivos auxiliares não entram no patch do projeto original. Omitir `skills` preserva o uso de skills que já pertençam aos arquivos elegíveis do projeto.
## Papéis personalizados
Defina `BRIDGE_CUSTOM_ROLES` como um array JSON no ambiente do servidor e reinicie a conexão. Exemplo PowerShell:
```powershell
$env:BRIDGE_CUSTOM_ROLES = '[{"name":"security-review","baseRole":"reviewer","description":"Revisão de controles de acesso","instruction":"Examine os controles de acesso do escopo solicitado e cite evidências reais."}]'
```
`antigravity_roles` lista os nomes disponíveis, descrições, base e tamanho das instruções. Selecione o nome em `role` de `antigravity_run` ou `antigravity_handoff`; os schemas MCP anunciam os nomes configurados. Cada papel tem nome de até 32 caracteres em letras minúsculas, números e hífens, `baseRole` e instruções de até 8.000 caracteres. A descrição é opcional, até 500 caracteres. Há até 20 papéis; nomes duplicados, substituição dos três nomes nativos, bases desconhecidas ou instruções vazias impedem a inicialização.
As bases `planner` e `reviewer` conservam modo de leitura, contratos JSON e conferência de citações. `implementer` conserva o fluxo de escrita na cópia e as mesmas exigências de verificação e confirmação para integração. Instruções personalizadas não dão permissões extras e entram no limite total do prompt. A definição usada é salva com a tarefa; a retomada mantém instruções e base originais, mesmo após mudar a configuração. Para trocar de papel, crie uma nova tarefa ou faça handoff.
## Grupos de tarefas e espera conjunta
O cliente cria um grupo com UUID estável, raiz Git, título e até 32 tarefas. Cada tarefa tem uma chave única, `owner` com um papel configurado, `dependsOn` e as opções de execução em `task`. Dependências desconhecidas, duplicadas, ciclos e definições maiores que 4 MiB são recusados. Há até 100 grupos retidos.
| Ferramenta | Uso |
| --- | --- |
| `antigravity_group_create` | Persiste a definição; não inicia modelos |
| `antigravity_group_start` | Inicia ou retoma com `expectedDefinitionSha256` |
| `antigravity_group_status` / `antigravity_groups` | Metadados, responsáveis, dependências e referências |
| `antigravity_group_wait` | Espera mensagens públicas ou término do grupo |
| `antigravity_group_cancel` | Impede novos nós e cancela tarefas no servidor responsável |
| `antigravity_wait_many` | Espera de 1 a 32 tarefas avulsas com cursores independentes |
| `antigravity_peer_receipts` | Recibos compactos das mensagens entre nós |
| `antigravity_workflow_result` | Síntese final e referência após revalidar checkpoints |
Exemplo de `definition` para `antigravity_group_create`:
```json
{
"workingDirectory": "<raiz-git-absoluta>",
"title": "Inspeção sequencial",
"jobs": [
{ "key": "inspect", "owner": "implementer", "dependsOn": [],
"task": { "prompt": "Inspecione os arquivos selecionados.", "mode": "read-only",
"acceptanceCriteria": [{ "id": "inspection", "description": "Inspeção fundamentada nos arquivos selecionados" }] } },
{ "key": "check", "owner": "implementer", "dependsOn": ["inspect"],
"task": { "prompt": "Confira os requisitos da tarefa.", "mode": "read-only",
"acceptanceCriteria": [{ "id": "requirements", "description": "Conferência fundamentada dos requisitos" }] } }
]
}
```
Repita o mesmo UUID e a mesma definição para consultar uma criação com resposta perdida; outra definição com esse UUID retorna `GROUP_CONFLICT`. O início exige o hash devolvido. O servidor admite um nó somente após todos os seus pré-requisitos terminarem com sucesso. Falha ou cancelamento bloqueiam os dependentes. Cada nó tem sua própria cópia; dependências controlam a ordem e não integram automaticamente alterações entre cópias.
Os grupos usam entrega `messages`. Cada nó aplica hooks da política nativa dentro da cópia, com as ferramentas de arquivo permitidas pelo teto humano e `finish`. MCPs entram por seleção da tarefa ou por um padrão explícito do perfil. A raiz do projeto precisa permanecer canônica e separada do estado privado do bridge. As esperas devolvem no máximo quatro mensagens no total, uma por tarefa, com `nextCursor`, `oldestAvailable` e `truncated`. Passe os cursores anteriores na próxima espera. `hasMoreMessages` e `hasMore` sinalizam mensagens ainda não lidas, inclusive quando `ready` já for verdadeiro. As respostas não incluem prompts, histórico de ferramentas ou resultados intermediários completos; use os leitores por partes quando precisar deles. Cancelar a espera preserva a execução.
Após reiniciar o servidor, `resumeRequired` informa a necessidade de retomada explícita. O coordenador recupera IDs já aceitos e não repete nós concluídos. Se uma admissão interrompida não tiver identidade verificável, retorna `GROUP_ADMISSION_UNVERIFIED`; não inicia outra execução silenciosamente. Alterar o perfil de um responsável pausa novas admissões com `GROUP_PROFILE_CHANGED`. Tarefas removidas pela retenção retornam erro, sem repetição.
O estado `completed` informa o término das execuções. Integração continua exigindo revisão, testes, verificação atual e hash por tarefa. Os registros de grupo ficam no estado privado até remoção local; descarte as cópias antes de apagar registros, conforme [Privacidade](PRIVACY.md).
### Workflows e checkpoints
Acrescente `workflow` à definição do grupo:
```json
{
"finalNode": "check",
"hooks": {
"inspect": { "requireReview": true }
},
"fileSources": { "check": "inspect" }
}
```
O nó final precisa depender, direta ou indiretamente, de todos os outros nós. Cada etapa exige `acceptanceCriteria`. O servidor verifica as condições de arquivo antes de liberar dependentes. Critérios sem uma verificação automática exigem revisão com citações conferidas nos arquivos reais. `requireReview` exige essa revisão mesmo com verificações automáticas; `requireTests` exige evidência observada de execução, vinculada ao patch e à árvore atuais. Registros `client-reported` não satisfazem esse hook. Testes diretos exigem uma etapa de escrita baseada em `implementer` e um executor compatível; a falta dessa capacidade não autoriza execução no host.
Os resultados JSON e artefatos permanecem no estado privado. Etapas de implementação sem formato explícito usam `{"summary":"..."}`; formatos dos perfis e contratos de outros papéis são preservados. Os predecessores fornecem JSON validado e hashes ao próximo nó; a síntese final recebe os intermediários concluídos. O contexto tem até 64 KiB UTF-8. Excesso retorna `WORKFLOW_CONTEXT_TOO_LARGE`, sem truncamento silencioso ou estimativa de tokens.
`fileSources` escolhe uma dependência direta como base dos arquivos de uma etapa. O servidor confere seu checkpoint e cria outra cópia. Outros predecessores fornecem dados; não há mescla automática de arquivos. A seleção de arquivos e skills da base é preservada: omita `includePaths` e `skills` no destino. As regras existentes de transferência de memória continuam válidas; `memory: []` permite não herdar snapshots.
Checkpoints guardam hashes da árvore, patch, resultado, artefatos e validação. Saídas com revisão ou testes pendentes são retidas e pausam o grupo. Depois da verificação, retome com `antigravity_group_start` e o mesmo hash de definição. O servidor revalida os dados e não repete a chamada já concluída. Alterações em arquivos ou resultados retornam `WORKFLOW_CHECKPOINT_CHANGED`; identidades perdidas não autorizam repetição. Novas mensagens não podem alterar uma etapa já checkpointada.
`antigravity_group_wait` mantém os intermediários fora da resposta, preservando perguntas, bloqueios e erros públicos. `antigravity_workflow_result` revalida os checkpoints e entrega somente a síntese pública final e uma referência com hash. Uma execução posterior com falha impede disponibilizar uma síntese como atualmente validada. Essas verificações cobrem as condições declaradas; a integração mantém seus próprios testes, revisão e confirmação ou autorização prévia.
### Orçamento observado por grupo
Use `"budget": {"maxTotalTokens": 100000}` na definição. Sem esse campo, o comportamento existente é preservado. Com teto configurado, o grupo aguarda os contadores do turno atual antes de admitir outro. O controle inclui continuações, mensagens entre nós e reparos com modelo; retomadas contam a diferença da sessão e execuções locais sem modelo têm consumo conhecido zero.
O status informa `observedTotalTokens`, subtotal conhecido, tarefas sem medição, margem e estado do orçamento. Contadores ausentes ou identidades retidas perdidas bloqueiam novas chamadas com `GROUP_USAGE_UNAVAILABLE`; atingir o teto pausa com `GROUP_BUDGET_EXCEEDED`. O teto faz parte da definição imutável do grupo.
Esse controle impede novas admissões conforme consumo observado. Um turno já aceito pode ultrapassar o teto; o CLI não oferece previsão exata de tokens ou preço antecipado. Não há substituição de dados ausentes por estimativas.
### Mensagens entre nós
O chamador seleciona rotas direcionadas em `definition.peerRoutes`, por exemplo `[{"from":"inspect","to":"check"}]`. Omissão ou `[]` nega envios. Não há direção inversa ou broadcast implícitos. Limites: 128 rotas, 20 mensagens por nó de origem durante o grupo e 100 por grupo.
O delegado recebe os destinos permitidos e emite uma resposta pública `<antigravity-peer-message>{"messageId":"<uuid-estável>","toNode":"check","text":"descoberta"}</antigravity-peer-message>`. O texto tem até 2.000 caracteres. O servidor verifica responsável, raiz de conversa, projeto e definição; a entrada chega ao destinatário como dados sem autorizar ferramentas ou integração.
A entrega aguarda a admissão do destinatário e o fim do turno ativo, usando a continuação oficial do CLI. Cada novo turno pode consumir quota. `queued` informa espera; `sent` informa aceitação da continuação, sem comprovar leitura pelo modelo. Dependências aguardam os turnos adicionais, e a espera conjunta acompanha o turno mais recente.
`antigravity_peer_receipts` recebe `groupId`, `after` e `limit` de 1 a 20. Os recibos trazem origem `agy-reported`, destinos, estado e SHA-256; corpos e IDs internos de transporte ficam fora da página. O cursor pagina um retrato: releia a página para conferir estados alterados. Resultados públicos do destinatário podem reproduzir dados recebidos e permanecem disponíveis pelos leitores normais.
Mesmo ID e conteúdo preservam a identidade. Conteúdo conflitante pausa com `PEER_MESSAGE_CONFLICT`; limites e truncamento pausam com `PEER_LIMIT_EXCEEDED`. Confirmação ambígua exige inspeção e retomada explícita, reutilizando o ID persistido. Rota negada ou destinatário encerrado produz falha sem outra sessão. O cancelamento alcança continuações ativas; grupos encerrados recusam novos turnos.
Em tarefas de implementação com política nativa e sem schema de saída explícito, o bridge oferece o formato JSON `{"summary":"..."}` para disponibilizar a chamada guardada `finish`. Schemas explícitos e contratos de outros papéis são preservados. Envelopes no campo público `summary` também são reconhecidos; isso não expõe raciocínio privado.
## Memória privada por projeto e especialista
A memória fica no estado privado do servidor, separada pela raiz Git canônica e pelo identificador do especialista. Nenhum arquivo do projeto é importado automaticamente.
| Ferramenta | Uso |
| --- | --- |
| `antigravity_memory_list` | Metadados, hashes, bytes e limites; não devolve o texto |
| `antigravity_memory_read` | Texto em partes, vinculado a `expectedSha256`; siga `nextOffset` |
| `antigravity_memory_write` | Grava texto revisado pelo chamador; `expectedSha256: null` cria, hash atual substitui |
| `antigravity_memory_remove` | Remove somente a versão correspondente ao hash informado |
Exemplo de seleção em `antigravity_run`, depois de ler e conferir a memória:
```json
{ "memory": [{ "specialist": "reviewer", "sha256": "<hash-atual-de-64-caracteres>" }] }
```
O chamador escolhe até oito entradas. O texto selecionado é enviado ao CLI como dados revisáveis, dentro do limite total do prompt; ele não concede permissões nem substitui as instruções da tarefa. Os retornos de tarefas incluem somente os metadados da memória, inclusive na entrega compacta. O conteúdo não é preparado como arquivo auxiliar nem integrado ao projeto.
`memory` também pode ser um padrão explícito de especialista. Uma lista vazia substitui esse padrão. A retomada conserva os snapshots originais, mesmo após substituir ou remover a memória armazenada; fornecer `memory` outra vez numa retomada é recusado. Handoffs herdam o snapshot por padrão e permitem uma seleção explícita diferente ou `memory: []`.
Os padrões globais são 100 entradas, 1 MiB de texto e 64 KiB por entrada, medidos em UTF-8. Escritas usam comparação de hash e lock entre processos; versões divergentes retornam `MEMORY_CHANGED`. Links, junções de armazenamento, arquivos corrompidos e hashes inconsistentes são recusados. Perfis `query` e `review` permitem somente listar e ler.
Textos com formatos de credencial de alta confiança são recusados com `INPUT_SECRET_DETECTED`, assim como prompts e mensagens. Entradas antigas com esses valores são lidas redigidas e não podem ser selecionadas.
Remover uma entrada não apaga os snapshots já guardados nas tarefas retidas. O descarte da cópia também preserva esses registros. Consulte [Privacidade](PRIVACY.md) para apagar o estado local; o bridge não oferece criptografia própria.
## Controles por especialista e tarefa
Papéis personalizados aceitam `defaults` com `model`, `effort`, `skills`, `includePaths`, `outputSchema`, `artifactPaths`, `deliveryMode`, `timeoutSeconds`, `allowedTools`, `mcpServers` e `memory`. Argumentos explícitos substituem cada campo completo, sem mesclar listas; `model: null` mantém Auto. A retomada conserva o snapshot original. Schemas de resultado personalizados exigem base `implementer`; os outros papéis mantêm seus contratos próprios.
A pessoa usuária configura no ambiente do servidor:
- `BRIDGE_ALLOWED_AGY_TOOLS`: array JSON que limita as ferramentas nativas. Valores aceitos: `view_file`, `write_to_file`, `replace_file_content`, `multi_replace_file_content` e `finish`. A finalização permanece implícita. Um teto configurado é aplicado mesmo quando o chamador omite seletores.
- `BRIDGE_MCP_CATALOG`: até 20 servidores confiáveis, cada um com `id`, transporte e `tools: [{name, readOnly}]`. O transporte é `command` absoluto com `args/env/cwd` opcionais, ou `serverUrl` HTTPS/HTTP de loopback com `headers` opcionais. `nativeServerName` permite um alias nativo estável definido pela pessoa usuária.
No CLI com os nomes atuais, `read_file` corresponde à capacidade `view_file`, `write_file` a `write_to_file` e `edit_file` exige `replace_file_content` ou `multi_replace_file_content`. Esses nomes usam `Path`; os seletores acima permanecem compatíveis. O hook rejeita alvos ambíguos e aplica as mesmas verificações de caminho e modo somente leitura. O recibo registra o nome efetivamente chamado.
Consulte `antigravity_get_agent_policy` antes de escolher `allowedTools` e `mcpServers: [{serverId, tools}]` em `antigravity_run` ou `antigravity_handoff`. O catálogo público mostra apenas IDs, aliases, descrições e ferramentas; transportes e credenciais não entram no prompt nem na política devolvida. Listas vazias selecionam somente a finalização e nenhum MCP. Sem configuração global nem seletores, tarefas antigas conservam o comportamento anterior. Uma sessão antiga sem controles exige nova tarefa depois de configurar um teto global.
Os hooks nativos restringem arquivos à cópia, bloqueiam ferramentas não escolhidas e impedem alterações da configuração auxiliar. Leituras em `.agents` são limitadas aos arquivos de skills explicitamente fornecidos. Helpers são conferidos por hash e ficam fora dos patches. A finalização precisa de recibo novo vinculado à política e à conversa; uma finalização anterior não valida a retomada. O handoff cria seus próprios controles e recibos, conservando a seleção e reduzindo ferramentas incompatíveis com leitura.
O agy também exige uma autorização nativa `mcp(alias/ferramenta)` em suas configurações. O bridge não concede essa autorização nem altera configurações globais; a ausência aparece como `AGY_MCP_PERMISSION_REQUIRED`. Servidores stdio são programas confiáveis executados no host: os hooks controlam chamadas do modelo, sem isolar a implementação interna desses serviços.
No Windows, testes pelo executor LPAC continuam disponíveis. A configuração MCP auxiliar mantém uma DACL protegida e não recebe acesso do processo de teste. A seleção de ferramentas não concede terminal: o executor legado `BRIDGE_TEST_EXECUTOR=agy` recusa testes diretos de tarefas com essa política usando `POLICY_TEST_EXECUTOR_UNAVAILABLE`.
## Ferramentas
Todas as ferramentas publicam `outputSchema` com campos e tipos de suas respostas estruturadas. O contrato contempla sucesso e `error: { code, message }`. O SDK confere os campos obrigatórios antes de entregar respostas de sucesso; clientes também podem validar o JSON recebido. Dados brutos do CLI continuam com tipo aberto porque seu formato pertence ao provedor. O contrato não transforma uma alegação do modelo em prova de execução.
| Ferramenta | Função |
| --- | --- |
| `antigravity_health` | Verifica executável, versão, autenticação aparente e capacidades |
| `antigravity_list_models` | Lista os IDs devolvidos por `agy models` |
| `antigravity_get_model` / `antigravity_set_model` | Consulta ou persiste o modelo padrão; `null` seleciona Auto |
| `antigravity_context` / `antigravity_handoff` | Inspeciona e transfere plano, decisões, critérios e evidências para outro papel em cópia independente |
| `antigravity_compare` / `antigravity_comparison` | Solicita pareceres de 2 a 4 modelos e reúne achados, divergências, falhas e uso observado |
| `antigravity_get_agent_policy` | Lista limites nativos e IDs/ferramentas MCP configurados, sem transportes ou credenciais |
| `antigravity_roles` | Lista os papéis nativos e personalizados configurados |
| `antigravity_get_sandbox_policy` | Lê a política global normalizada, seus limites e o hash atual |
| `antigravity_set_sandbox_policy` | Solicita ao cliente MCP a confirmação humana para substituir a política global com comparação do hash anterior |
| `antigravity_send_message` | Enfileira texto do chamador com recibo idempotente e continuação oficial da sessão |
| `antigravity_run` | Inicia uma tarefa e retorna o `taskId` |
| `antigravity_list_project_files` | Lista os arquivos elegíveis para a cópia |
| `antigravity_preview` | Mostra A/M/D, totais de linhas, estatísticas por arquivo, patch, hash e testes relatados |
| `antigravity_record_test` | Registra comando, saída e exit code relatados pelo cliente, vinculados ao hash |
| `antigravity_test` | Executa o comando exato com a seleção de sandbox do chamador e captura evidência do executor escolhido |
| `antigravity_verify` | Confere critérios da tarefa e evidências de revisão contra arquivos reais |
| `antigravity_read_patch` | Lê o patch por arquivo ou em trechos vinculados ao hash completo |
| `antigravity_read_result` | Lê o JSON final do CLI em trechos com hash de conteúdo |
| `antigravity_usage` | Consolida tokens observados por tarefa, sessão e modelo |
| `antigravity_integrate` | Aplica o patch verificado ao original; dispensa novo formulário somente em projetos previamente autorizados |
| `antigravity_tasks` | Recupera IDs e metadados de tarefas persistidas localmente |
| `antigravity_status` | Consulta estado, processo, sessão, uso e snapshots Git |
| `antigravity_wait` | Espera até 60 segundos com notificações MCP dos eventos observados; timeout não cancela a tarefa |
| `antigravity_events` | Lê eventos após um cursor `after` |
| `antigravity_result` | Consulta o resultado ou informa `ready: false` |
| `antigravity_discard` | Remove a cópia e o baseline de uma tarefa finalizada |
| `antigravity_cleanup` | Remove cópias finalizadas cujo prazo de retenção expirou |
| `antigravity_cancel` | Cancela tarefa na fila ou encerra o processo local |
| `antigravity_sessions` | Lista sessões conhecidas no estado local |
| `antigravity_resume` | Retoma uma conversa conhecida pelo `sessionId` |
`antigravity_run` recebe `prompt`, `workingDirectory` absoluto na raiz de um repositório Git e, opcionalmente, `model`, `timeoutSeconds`, `mode` e `includePaths` (arquivos ou pastas relativos à raiz). Sem `includePaths`, copia todos os arquivos rastreados e não rastreados que **não** correspondam a `.gitignore`, `.git/info/exclude` ou às outras regras de ignore do Git. O filtro também exclui arquivos rastreados que passaram a ser ignorados. `includePaths` apenas reduz essa seleção; não permite incluir arquivos ignorados. Links simbólicos e caminhos fora da raiz são recusados. Consulte `antigravity_list_models` antes de selecionar um modelo.
### Política de sandbox dos testes
`antigravity_get_sandbox_policy` devolve a política global normalizada e seu `sha256` para os testes Windows LPAC. Ela é o limite máximo para `readRoots`, `writeRoots`, `network`, `childProcesses` e `maxOutputChars`. A configuração inicial não concede raízes externas, desativa rede, permite processos filhos e limita a saída a 4.000 caracteres.
O agente que chama o MCP, seja o Codex ou outro cliente, escolhe em cada `antigravity_test` Windows `sandbox: { readPaths, writePaths, network, childProcesses, maxOutputChars }` dentro desse limite. O bridge recusa caminhos que ultrapassem as raízes aprovadas ou que coincidam com a origem, credenciais, armazenamento do bridge, temporários controlados, links, aliases ou outros caminhos protegidos. A seleção fica vinculada à evidência do teste e ao hash da política usado. No caminho legado `agy`, uma seleção explícita não é aceita; sem seleção, ele conserva o comportamento anterior.
Para ampliar ou reduzir o limite global, leia antes a política e chame `antigravity_set_sandbox_policy` com seu hash atual e a proposta. Em modo `auto`, propostas validadas de teto global de sandbox são aplicadas automaticamente sem exibir formulário; em modo `ask`, o cliente MCP deve apresentar o formulário interativo com comparação do hash anterior. A comparação e gravação evitam substituir uma política que mudou enquanto a proposta era avaliada. O agente que chama o MCP escolhe concessões estreitas e verificadas necessárias por teste dentro desses limites; o Gemini delegado via `agy` não pode escolher, autorizar nem alterar concessões. Alterações afetam testes novos e os que ainda estiverem na fila; elas não revogam promessas de permissões de trabalhos ativos nem realizam fallback ao host.
Por exemplo, um pedido de leitura e escrita deve usar raízes específicas verificadas, como `"<raiz-de-leitura-aprovada>"` e `"<raiz-de-escrita-aprovada>"`; não use um disco inteiro nem presuma caminhos do computador de outra pessoa. Em modo `ask`, confirme antes os limites no formulário; em `auto`, submeta a proposta validada e selecione subconjuntos estreitos dela para o teste.
Para revisão, diagnóstico ou segunda opinião, passe `mode: "read-only"`. O bridge exige suporte a `agy --mode plan`, confere ao final que nenhum arquivo foi criado, modificado ou removido (inclusive arquivos novos ignorados pelo Git) e recusa integração dessas tarefas. Esse modo é uma restrição do CLI com verificação posterior, sem garantia de bloqueio físico de escrita. O padrão `mode: "write"` preserva o fluxo de implementação na cópia. Uma sessão retomada mantém seu modo original.
Fluxo típico:
1. Consulte `antigravity_health` para conferir CLI, perfil e modo de aprovação (`approvalMode` e `integrationApproval`). Use `antigravity_list_models` e `antigravity_roles` para selecionar IDs e papéis anunciados pelo servidor.
2. Liste os arquivos elegíveis com `antigravity_list_project_files`, selecione `includePaths` quando necessário e defina `acceptanceCriteria` cobrindo os requisitos antes de iniciar a implementação com `antigravity_run`. Guarde o `taskId`.
3. Acompanhe com `antigravity_wait`, preservando `nextCursor` e repetindo a espera quando `ready` for falso. `timedOut` encerra apenas a espera. Use `antigravity_events` para consultar os eventos detalhados.
4. Após o término, confira o status e os erros em `antigravity_result` com `includeResult: false`. Leia o resultado com `antigravity_read_result` e o patch com `antigravity_preview` (`includePatch: false`) e `antigravity_read_patch`. Se houver falha, confira a causa antes de retomar; `completed` não comprova os requisitos.
5. No Windows com o executor LPAC, consulte a política de sandbox e execute os testes pertinentes com `antigravity_test`, usando o hash da prévia e somente uma seleção já aprovada. Nos demais sistemas, ou com `BRIDGE_TEST_EXECUTOR=agy`, execute o teste sem seletor `sandbox`, pois a seleção explícita é recusada no caminho legado. A ferramenta devolve outro `taskId`: acompanhe e revise esse ID, confira a origem da evidência, exit codes e evidências desatualizadas e obtenha a prévia atual novamente. `antigravity_record_test` registra testes executados pelo cliente, como relatos; não substitui a evidência observada do executor.
6. Confira os arquivos reais contra cada critério e envie evidências de revisão a `antigravity_verify` com o hash atual. Com verificação aprovada e atual, confira também se os testes observados continuam válidos e chame `antigravity_integrate` na tarefa de implementação mais recente dessa cópia para aplicar segundo a política de autorização configurada. Alterações no patch, nas evidências ou nos arquivos afetados do original exigem nova conferência.
7. Informe o uso observado com `antigravity_usage` e, quando o trabalho puder ser removido, descarte a cópia com `antigravity_discard`.
Esse fluxo de implementação requer `full` ou `implementation`. Para planejamento, revisão ou comparação, use os papéis de leitura e os fluxos específicos acima. Uma revisão por handoff recebe outra cópia; ela não altera qual é a tarefa mais recente da cópia de implementação.
A aplicação final respeita o modo ativo configurado: em `auto`, `antigravity_integrate` aplica o patch verificado sem formulários; em `ask`, exige confirmação humana via formulário MCP (**MCP form elicitation**), mesmo para raízes lembradas ou configuradas legadas (o checkbox de memorização foi removido). `antigravity_health` informa `approvalMode`, `integrationApproval.available` e `integrationApproval.mode`. No modo `ask`, o formulário mostra origem, tarefa, hash, arquivos e contagens de linhas; só `accept` com `confirm: true` permite aplicar. Recusa, cancelamento, timeout ou falta de suporte preservam o original. O hash identifica o patch e a confirmação vem de uma resposta separada do cliente; nenhum argumento `approved` é aceito como autorização. Após a resposta, o bridge confere novamente hash e origem. A confirmação depende de um cliente confiável que apresente a decisão ao usuário.
## Verificação dos resultados
### Consumo de tokens
`antigravity_status` e `antigravity_result` incluem `task.tokenUsage`. `antigravity_usage` consolida as tarefas retidas e aceita filtros por `taskId`, `sessionId` e `model`. A resposta contém `byTask`, `bySession`, `byModel` e os contadores `inputTokens`, `outputTokens`, `totalTokens`, `thinkingTokens` e `cacheReadTokens`.
O [resultado final do agy informa uso cumulativo da sessão](https://www.antigravity.google/docs/cli/headless/#read-the-results). O bridge salva os contadores anteriores ao retomar e usa a diferença para a tarefa seguinte, inclusive quando o modelo muda. Assim, duas respostas cumulativas de 120 e 170 tokens representam 170 tokens na sessão e 50 na segunda tarefa. `observedCumulative` preserva o último total de sessão informado pelo CLI, separado do consumo das tarefas retidas.
Contadores ausentes, inválidos, reiniciados ou sem baseline conhecido ficam `null`; `available`, `partial`, `source` e `warnings` indicam a qualidade dos dados. Não há estimativa de tokens nem substituição silenciosa por zero. O consumo de tarefas falhas também é incluído quando o CLI devolve os contadores finais. Antes desse resultado, o total da tarefa pode estar indisponível. Tarefas antigas removidas pela retenção deixam de compor o consolidado local. Modelo `null` significa que não foi informado um ID; não se presume um modelo padrão.
Esses números são relatos do CLI, sem cálculo de cobrança ou acesso à quota global da conta. Cache e raciocínio são dimensões separadas e não devem ser somados novamente a `totalTokens`. A skill orienta o Codex a informar o consumo disponível ao concluir ou relatar falhas.
### Papéis de trabalho
`antigravity_run` aceita os papéis nativos `"implementer"` (padrão), `"planner"` e `"reviewer"`, além dos nomes personalizados anunciados por `antigravity_roles`. As bases de planejamento e revisão usam obrigatoriamente `mode: "read-only"` e `agy --mode plan`; selecionar escrita nesses papéis é recusado. A retomada mantém o papel e a definição originais.
Os papéis de consulta exigem suporte a `agy --json-schema`. O planejamento devolve `summary`, `steps` com arquivos e verificações observáveis, e `unverified`. A revisão devolve `summary`, `reviewedFiles`, `findings` e `unverified`; cada achado contém gravidade P0–P3, caminho, linha, citação literal, mensagem, impacto e sugestão.
O relatório validado aparece em `task.report` na resposta completa. Com resposta compacta, use `antigravity_read_result` para ler o `structured_output` original do CLI. Relatórios são identificados como `agy-reported`; na revisão, `citationsChecked: true` significa que arquivos e citações foram conferidos, sem atestar a interpretação ou provar ausência de defeitos. Formato inválido, arquivos inexistentes ou citações inventadas impedem a conclusão normal da tarefa. Uma resposta de planejamento não significa que suas etapas foram executadas.
### Ler respostas grandes em partes
Use `antigravity_preview` com `includePatch: false` para obter arquivos, estatísticas, hash e `patchLength` sem enviar o diff inteiro. Depois chame `antigravity_read_patch` com `expectedSha256` e, opcionalmente, um `path` devolvido na prévia. A seleção é feita pelo Git, incluindo arquivos binários e caminhos com espaços; não depende de interpretar cabeçalhos do patch. Qualquer alteração do patch completo invalida a leitura, mesmo quando você seleciona apenas um arquivo.
`antigravity_result` aceita `includeResult: false` para omitir o resultado bruto, o prompt, relatórios transferidos, instruções do papel e a lista completa de arquivos da cópia. Quando `ready: true`, consulte `antigravity_read_result` para ler o resultado serializado como JSON. Guarde `contentSha256` e envie-o como `expectedContentSha256` nas páginas seguintes para detectar mudanças.
Os leitores recebem `offset` (padrão 0) e `limit` (padrão 10.000, entre 2 e 50.000). Retornam `text`, `nextOffset`, `hasMore`, `totalLength` e `contentSha256`. Concatene `text` até `hasMore: false`; use sempre o `nextOffset` devolvido. Os offsets usam unidades UTF-16 e o leitor preserva caracteres representados por pares substitutos, como emojis. As opções antigas continuam devolvendo o conteúdo inteiro quando os campos de omissão não são usados.
Defina `acceptanceCriteria` antes de iniciar uma tarefa. Cada critério tem `id`, `description` e, opcionalmente, `check` com `kind`, `path` e `text`. As verificações disponíveis são `file-exists`, `file-absent`, `file-contains` e `file-not-contains`; as duas últimas exigem `text`. Critérios são preservados em retomadas e não podem ser substituídos depois da execução.
Após revisar o patch, chame `antigravity_verify` com o hash atual e `reviews`. Para cada critério, informe `criterionId`, `verdict` (`passed`, `failed` ou `unverified`), `path`, `line`, `quote` e `explanation`. O bridge lê os arquivos da cópia, executa as verificações e confere se a citação corresponde exatamente à linha indicada. Uma alegação do Gemini, um resultado `SUCCESS` ou um registro de teste do cliente não substitui essas evidências.
A integração exige todos os critérios aprovados e uma revisão atual. Critérios ausentes ou pendentes geram `VERIFICATION_REQUIRED`. Alterações no patch ou nos arquivos usados como evidência invalidam a verificação, inclusive alterações em arquivos ignorados que não aparecem no diff. O servidor verifica novamente após a confirmação humana. A prévia inclui `verification` e `stale`.
As verificações automáticas demonstram apenas as condições declaradas; a correção funcional mais ampla depende dos testes pertinentes e da revisão do Codex. O parecer permanece identificado como `client-reported`: conferir uma citação não demonstra que sua interpretação está correta. Esse fluxo aplica a distinção entre alegação e estado final e combina verificações determinísticas com revisão, conforme a [orientação sobre avaliações de agentes](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents).
## Eventos, sessões e cancelamento
O bridge exige suporte aos formatos `stream-json` e a `--sandbox`, conferidos na descoberta do CLI. A versão verificada neste projeto é `agy` 1.3.2. Eventos estruturados chegam como NDJSON; diagnósticos de `stderr` permanecem separados. Linhas inválidas são expostas como `stream.unparsed`. O `EventStore` mantém um buffer limitado: `truncated: true` indica perda de eventos antigos. Registros de tarefas, sessões, eventos disponíveis, preferência de modelo e referências às cópias são persistidos por escrita atômica em `~/.antigravity-mcp-bridge` (ou `BRIDGE_STATE_DIRECTORY`). O estado contém prompts e resultados: mantenha esse diretório privado, fora dos projetos versionados e de pastas compartilhadas.
Locks do estado privado conferem a identidade do arquivo e um token de posse antes da liberação. A recuperação de um proprietário confirmado como encerrado é serializada entre processos. Locks incompletos, arquivos substituídos e uma recuperação interrompida permanecem protegidos para inspeção local, com `STATE_BUSY`; a liberação repetida de um lock já encerrado é idempotente. O `StateStore` não possui suporte genérico a armazenamento em nuvem. Em ambientes sincronizados como OneDrive, a tolerância a variações na contagem de links (`nlink`) aplica-se exclusivamente à leitura de assets com descritor confiável, tamanho e SHA-256 fixados, ao staging da fonte do Node portátil com `expectedSha256`, e ao lock de preparação do Node portátil (preservando device, inode, tamanho e nonce/payload exato, com unlink apenas da entrada do próprio processo para preservar aliases). Hash, tamanho, identidade, marcas de reparse e layout continuam estritamente obrigatórios; conteúdo alterado é recusado e aliases não são modificados. Destinos de runtime, executáveis genéricos e concessões de ACL continuam exigindo link único.
### Modelo padrão
Defina `BRIDGE_DEFAULT_MODEL` com um ID devolvido por `agy models` para o padrão inicial. `antigravity_set_model` grava a preferência no estado privado, compartilhada por servidores que usam o mesmo diretório. A prioridade é: `model` da tarefa, preferência salva, variável de ambiente e padrão do agy. A seleção é conferida contra a lista atual antes de executar; IDs indisponíveis causam `MODEL_NOT_AVAILABLE`.
Passe `model: null` para Auto: por tarefa, ignora os padrões do bridge; em `antigravity_set_model`, persiste o padrão do agy mesmo quando a variável está configurada. Omitir `model` preserva a preferência vigente. Para voltar ao padrão inicial do ambiente, pare o servidor e remova somente `model-selection.json` do diretório privado de estado.
`antigravity_resume` usa o `conversation_id` de uma tarefa concluída, inclusive após reinício, e reutiliza sua cópia isolada. Use `antigravity_tasks` para recuperar IDs e `antigravity_sessions` para consultar sessões persistidas. Execuções interrompidas não são repetidas automaticamente: recebem `SERVER_RESTARTED` quando o processo anterior já terminou. Se o PID registrado ainda estiver vivo, a cópia fica bloqueada com `ORPHAN_PROCESS_RUNNING`; o bridge não encerra processos recuperados apenas por PID. Tarefas de outro servidor ativo podem ser acompanhadas, mas devem ser canceladas no servidor que as iniciou. Locks locais impedem uso simultâneo da mesma cópia. O cancelamento encerra o subprocesso local; alterações parciais na cópia podem permanecer e devem ser revisadas.
Em cancelamentos e timeouts, a primeira intenção registrada prevalece (`TASK_CANCELLED` ou `TASK_TIMEOUT`), acionando o encerramento do processo e descendentes, sem garantia perfeita para processos que escapem do grupo de processos ou de permissões do sistema operacional. Diagnósticos estruturados diferenciam falhas de execução e ciclo de vida: `AGY_NOT_FOUND` (executável ausente), `AGY_PERMISSION_DENIED` (acesso negado ao binário), `AGY_PROBE_FAILED` (falha na sondagem inicial), `AGY_INCOMPATIBLE` (falta de suporte a `stream-json` ou `--sandbox`), `CLI_INPUT_FAILED` (falhas de stdin, EPIPE ou EOF prematuro), `AGY_IO_FAILED` (erros de I/O em streams) e `AGY_PROCESS_FAILED` (saída anômala do processo). Mensagens de erro de ferramentas externas podem conter segredos desconhecidos; o bridge aplica redaction a formas e padrões conhecidos de erro e suas operações não adicionam valores de credenciais aos logs nem passam tokens como argumentos, sem prometer ausência absoluta.
Ao fim de cada execução do CLI, inclusive com sucesso, o bridge observa novamente os processos pertencentes à execução e registra `processCleanup`. No Windows, a árvore é reconstruída por PID pai e horário de criação a partir do instante do spawn, o que exclui PIDs reutilizados; cada processo é encerrado e sua ausência é confirmada em até 3 s. Em POSIX, o grupo de processos próprio é encerrado e sua ausência é confirmada. Quando a confirmação falha, `processCleanup.verified` fica `false` e retomadas, testes, integrações e mensagens dessa cópia são recusados com `PROCESS_CLEANUP_UNVERIFIED` até uma nova observação confirmar o encerramento. Limite: no Windows, descendentes cujo processo intermediário já terminou não podem ser associados pelo PID pai e não entram na verificação.
## Cópia, revisão e integração
Antes de chamar `agy`, o bridge cria uma cópia temporária dos arquivos elegíveis e mantém um baseline Git separado da cópia. O CLI recebe a cópia como diretório de trabalho e a opção `--sandbox`. O projeto original só muda por `antigravity_integrate`, depois da revisão do patch. O bridge não faz commit, merge nem push.
Antes de copiar, o bridge executa um preflight preventivo de segredos APÓS as exclusões do Git e a seleção por `includePaths`, e ANTES da cópia dos arquivos. O preflight bloqueia `.env`, `.env.local` e outras variantes `.env.*` (exceto `.env.example`, `.env.sample`, `.env.template` e `.env.dist`, que ainda passam por inspeção de conteúdo), `.envrc`, chaves privadas, keystores, autenticação conhecida e padrões de credenciais com alta confiança por conteúdo. Certificados, chaves públicas e fixtures sintéticas para testes permanecem permitidos. O evento `copy.ready` informa `blockedFiles` contendo apenas `path` e `reason` (`SECRET_FILE`, `SECRET_CONTENT`, `SECRET_EXCLUSION`, `UNSAFE_PATH`), nunca expondo o conteúdo do arquivo. O preflight não garante detectar segredos arbitrários em código, formatos desconhecidos ou dados criptografados.
Quando o CLI anuncia `--add-dir` e `--new-project`, o bridge declara a cópia como workspace e cria um projeto CLI separado na primeira execução. A retomada preserva o projeto da conversa. Essas opções não equivalem a uma comprovação de todas as fronteiras do sandbox; permissões negadas continuam sendo respeitadas.
O resultado informa `copyDirectory` e `includedFiles`. Cópias temporárias permanecem para revisão por 7 dias após a última tarefa finalizada. O servidor limpa cópias expiradas na inicialização e a cada minuto; `antigravity_cleanup` permite antecipar a verificação. Use `antigravity_discard` para remover imediatamente uma cópia pelo MCP. Tarefas retomadas compartilham a mesma cópia; todas perdem acesso após descarte. Cópias em uso são preservadas. A expulsão do último registro pelo limite de retenção também remove sua cópia. `isolateWorktree: true` é aceito apenas por compatibilidade e usa o mesmo fluxo de cópia; `false` é recusado.
`antigravity_preview` preserva `files`, `patch` e `sha256` e acrescenta `summary` (totais A/M/D, linhas e arquivos binários), `fileSummaries` (inserções/remoções por caminho) e `tests`. Binários usam `null` nas contagens de linhas. Registros de `antigravity_record_test` têm `source: "client-reported"`: são relatos cujo comando o bridge não executou. Registros capturados por `antigravity_test` indicam o executor que os observou. Cada registro leva hash, data, exit code e saída limitada pela seleção do teste; o padrão é 4.000 caracteres. Resultados antigos recebem `stale: true` quando a evidência já não corresponde aos arquivos atuais. Falhas são preservadas e devem ser apresentadas na revisão.
O baseline privado, o patch e a integração tratam os arquivos como bytes: atributos do projeto como `* text=auto` ou `eol=crlf` não convertem finais de linha. Antes de escrever no original, `antigravity_integrate` aplica o patch a cópias dos arquivos afetados num diretório privado e confere cada um contra o original: um arquivo LF ou CRLF continua no mesmo formato, um arquivo misto mantém o final de cada linha não editada e o BOM UTF-8 é preservado. Um BOM que o patch removeu volta automaticamente enquanto o resto do arquivo for UTF-8; os caminhos aparecem em `restoredByteOrderMarks`, no resultado e no evento `copy.integrated`. Qualquer outra mudança de final de linha ou de BOM recusa a integração com `LINE_ENDINGS_CHANGED`, sem tocar no original. Só então cada arquivo é gravado de forma atômica (temporário na mesma pasta, depois renomeado), mantendo as permissões do original; um arquivo excluído é antes movido para um nome temporário na mesma pasta. Se uma gravação falhar, os arquivos já gravados recebem de volta os bytes anteriores, os excluídos voltam ao lugar e a operação falha com `INTEGRATION_FAILED`. Com tudo gravado, a integração está concluída e os excluídos são apagados; um que não possa ser apagado fica no nome temporário e é listado em `leftoverFiles`. Uma queda do processo do servidor no meio das gravações ainda não é recuperada automaticamente.
A cópia aceita até 10.000 arquivos e 256 MiB por padrão (`MAX_COPY_FILES` e `MAX_COPY_BYTES`), limites estritamente respeitados durante o scan preliminar e durante a cópia. A seleção é medida antes da criação e os bytes efetivamente copiados são conferidos novamente para detectar crescimento da origem. Qualquer mudança de identidade, tamanho ou hash falha a operação com `SOURCE_CHANGED` ou `CONTEXT_CHANGED`, e a criação da cópia (fork) não omite silenciosamente arquivos de baseline que venham a virar credencial. `includePaths` pode reduzir a seleção. Mais de 100 arquivos alterados gera `CHANGE_LIMIT_EXCEEDED` ao finalizar, revisar ou integrar. O original permanece intacto; reduza a tarefa ou ajuste os limites explicitamente no ambiente do servidor.
### Executar testes sem Docker
Chame `antigravity_test` com `taskId`, `expectedSha256` e `command: { executable, args }`. A ferramenta inicia uma continuação na mesma cópia e devolve outro `taskId`. Acompanhe esse ID pelos eventos e pelo resultado; revise e integre a tarefa mais recente. `retries` vale 0 por padrão e aceita até 3 tentativas de correção adicionais, solicitadas explicitamente. `timeoutSeconds` vale 600 por padrão.
Se uma tentativa local do Windows falhar na infraestrutura, uma chamada explícita de `antigravity_test` pode criar outra tentativa após a recuperação nativa das leases. O registro anterior permanece falho. Essa repetição exige a prévia e o hash atuais e é recusada enquanto houver execução ativa ou recuperação inconclusiva. Ela não habilita testes de sessões do CLI canceladas, expiradas ou com falhas de modelo.
A limpeza confere o caminho e a identidade dos temporários próprios. Um temporário comprovadamente ausente não invalida os demais resultados de limpeza; substituições ou links detectados impedem sua remoção. As verificações de Job, perfil, aliases e permissões continuam obrigatórias.
No Windows, o bridge cria um processo AppContainer/LPAC por execução e executa o comando diretamente nessa fronteira. O perfil, o SID e as ACLs de acesso são exclusivos da execução; as concessões exatas são removidas ao final. A limpeza e a recuperação de uma execução interrompida são verificadas em processos novos. Uma queda de energia não remove essas ACLs instantaneamente: a recuperação seguinte precisa concluí-la, e uma falha de limpeza impede que o teste seja considerado verificado e bloqueia novo uso daquela concessão.
O executor Windows não instala Docker nem pede elevação UAC. Ele exige o compilador .NET Framework já existente no Windows para criar o controlador. Cada execução é isolada em um perfil novo; a cobertura atual inclui recuperação de processo e nova execução, mas não afirma uma reinicialização física do computador.
Para expor os diretórios próprios da execução, o controlador cria aliases temporários em dois níveis para a cópia, o runtime preparado e o scratch: um nome DOS e uma letra entre `D:` e `Z:` para cada diretório. São necessárias três letras livres. O controlador confere a identidade e o destino de cada mapeamento antes, durante e depois do comando e os remove na limpeza, inclusive ao recuperar uma execução interrompida. Esses nomes DOS ficam visíveis apenas no contexto de logon atual; a reserva por letra é coordenada por logon e letra. Eles não concedem acesso à raiz do volume, não criam um mount persistente e não pedem UAC.
Fora do Windows, ou com `BRIDGE_TEST_EXECUTOR=agy`, o bridge mantém o caminho legado: `agy --sandbox` e `run_command`, com recibo vinculado à chamada exata. Não há fallback para executar diretamente no host. Em todos os casos, um comando não zero produz `TEST_FAILED`, mudanças nos arquivos durante/depois do comando produzem `TEST_CHANGED_PATCH`, e a evidência precisa continuar atual para integração.
No Windows, a evidência tem `source: "windows-executor"` e `sandbox: "windows-lpac"`; fora dele, tem `source: "agy-tool"` e `sandbox: "agy-native-requested"`. A evidência inclui seleção de sandbox, hash da política, saída limitada e fingerprints antes/depois. A execução local conhecida registra zero tokens de modelo. Se uma correção pelo `agy` for solicitada após uma falha, seus contadores continuam sendo somente os devolvidos pelo CLI; campos ausentes permanecem `null`.
Saída ou texto do modelo, inclusive uma afirmação de que o comando passou, não é recibo de teste. Use somente a evidência observada pelo executor escolhido, com seu exit code e os campos de sandbox correspondentes.
No Windows, o bridge preenche `PATHEXT` ausente no subprocesso com `.COM;.EXE;.BAT;.CMD`, para que o PowerShell encontre os executáveis instalados. Valores definidos pelo cliente, inclusive um valor vazio, são preservados. O SDK pode omitir essa variável no ambiente herdado, fazendo `node` parecer ausente mesmo quando o arquivo está instalado. A correção vale para as sondagens e para todas as tarefas, sem configuração por projeto.
No Windows, use um `.exe` nativo ou `npm`/`npm.cmd`. Para npm, o bridge valida o launcher instalado, seu pacote e `npm-cli.js`, e chama o `node.exe` preparado com os argumentos literais. Lotes `.cmd`/`.bat` arbitrários e outros interpretadores não são suportados pelo executor. O staging rejeita caminhos remotos, dispositivos, streams alternativos e NUL; só o runtime validado é copiado sob limites de tamanho. Destinos de runtime, executáveis genéricos e concessões de ACL (grants) continuam exigindo link único; arquivos preparados pelo usuário não podem usar links; o `cmd.exe` interno deriva de um caminho fixo do Windows.
Para testes Node/npm e comandos git diretos no Windows, o executor prepara automaticamente o Git for Windows descoberto no `PATH` quando instalado, resolvendo launchers de `cmd` e `bin` para o binário nativo em `ucrt64/bin` ou `mingw64/bin` quando há um layout conhecido. Executáveis nativos e instalações standalone são preservados; layouts conhecidos sem binário válido ou com links inseguros são recusados. Copiam-se somente binários PE, DLLs e helpers públicos para um runtime isolado em modo somente leitura com links únicos no destino; arquivos de origem podem conter hardlinks na instalação original, mas ela não recebe ACLs nem concessões. O `PATH` preserva exclusivamente os diretórios do runtime preparado e o `System32` exato; `GIT_EXEC_PATH` aponta para o diretório no alias do runtime, a configuração global aponta para arquivo ausente no scratch e definem-se `GIT_CONFIG_NOSYSTEM=1` e `GIT_TERMINAL_PROMPT=0`. Entradas injetadas de `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_*`, `GIT_CONFIG_VALUE_*` e `GIT_CONFIG_PARAMETERS` são removidas, e o ambiente do comando estabelece a confiança protegida de `safe.directory` restrita exclusivamente à lista exata dos depósitos verificados presentes na cópia no início da execução: reset vazio (`VALUE_0=''`), raiz do alias da cópia verificada (`VALUE_1`) e raízes dos depósitos descendentes com diretório `.git` verificado dentro da cópia (`VALUE_2..N`), sem wildcard `*` e sem confiar fora da cópia. Novos depósitos criados após a admissão continuam sujeitos às checagens normais do Git. Não há herança de `.gitconfig`, credenciais ou chaves, nem download de Git. A ausência de Git é opcional e não impede testes Node/npm sem Git, enquanto comandos que necessitam de Git falham se ele estiver ausente. Os limites de cópia permanecem obrigatórios (arquivos do Git contam para o teto), sem concessões extras para a pasta de instalação e sem fallback ao host ou ampliação de rede.
Novos repositórios temporários criados no sandbox usam o formato `reftable` via `GIT_DEFAULT_REF_FORMAT=reftable` definido somente no ambiente isolado quando o Git está preparado. O Git instalado deve suportar esse formato; a configuração não converte repositórios existentes nem altera o Git no host. O backend tradicional `files` e versões do Git sem suporte a reftable possuem limitação no LPAC ao consultar diretórios pais privados (sem alegação de suporte universal). A configuração não afrouxa as proteções de sistema de arquivos: diretórios pais privados continuam com acesso negado, sem novas concessões, sem UAC e sem fallback ao host.
Quando o Git está preparado, o controlador consulta a permissão do dispositivo Null do Windows. Se a regra padrão de LPAC já permite leitura e escrita, essa consulta não altera a ACL nem solicita `WRITE_DAC`. Caso o acesso esteja ausente e o token atual permita `WRITE_DAC`, o controlador registra uma concessão temporária somente para o SID exclusivo da execução. A limpeza verifica que o Job está vazio antes de remover acessos; uma recuperação inconclusiva mantém o lease e bloqueia a execução. A falta de permissão produz um diagnóstico sem solicitar elevação.
#### Compatibilidade de subprocessos Node no Windows LPAC
No Node 24.14.1 com libuv 1.51, `child_process.spawnSync` com pipes padrão de stdin/stdout/stderr cria endpoints globais `\\?\pipe\uv\...`. O LPAC recusa o `CreateNamedPipe` global com erro 5, enquanto endpoints equivalentes `LOCAL\...` abrem. A captura de stdout/stderr do processo pai está corrigida; no Node 24.14.1 do sistema, esse caso com pipes padrão ainda expira com exit code 124.
Testes de filhos com `stdio: "inherit"` e do ciclo real do npm passaram, mas não demonstram compatibilidade geral de subprocessos porque não exercitam os pipes capturados por padrão. Não substitua os pipes por stdio herdado para apresentar essa falha como resolvida.
O [PR 5181 do libuv](https://github.com/libuv/libuv/pull/5181/files) corrige os nomes de pipe para AppContainer e a correção entrou no [libuv 1.53](https://github.com/libuv/libuv/releases/tag/v1.53.0). O runtime portátil Node 24.21.0 LPAC1 para Windows x64, com libuv base 1.52.1 e somente esse PR aplicado, já está publicado em Release imutável e disponível para preparação explícita. Esse build passou pela regressão LPAC de `spawnSync` com pipes padrão capturados (1 teste) e pelos testes de isolamento e ciclo de vida (22 testes, sem falhas nem skips). A validação se aplica a esse build fixado.
`network: true` concede somente as capacidades Windows `internetClient` e `privateNetworkClientServer`, que permitem tráfego de Internet e LAN privada bidirecional. Não há capacidades arbitrárias, exceção para localhost, alteração de firewall nem acesso de rede quando a seleção não o permite. `childProcesses` e `maxOutputChars` também ficam limitados pela política aprovada.
Para testar com a conta real em um projeto descartável, execute `npm run build` e `node tests/native-integration.mjs`. Esse teste usa a conta do agy e verifica a captura de uma execução real; a suíte padrão usa o CLI simulado e não consome quota.
## Configuração e segurança
| Variável | Padrão | Uso |
| --- | --- | --- |
| `BRIDGE_APPROVAL_MODE` | `auto` | Modo de aprovação: `auto` (padrão se unset; dispensa formulários para integração e política de sandbox validadas) ou `ask` (estrito; exige sempre confirmação humana via formulário MCP, mesmo para raízes lembradas ou configuradas) |
| `BRIDGE_CUSTOM_ROLES` | `[]` | Até 20 papéis em JSON com nome, base e instruções |
| `BRIDGE_TOOL_PROFILE` | `full` | Catálogo: `full`, `query`, `review` ou `implementation` |
| `BRIDGE_TEST_EXECUTOR` | `windows-lpac` no Windows; `agy` nos demais sistemas | Executor de `antigravity_test`; `agy` força o caminho legado no Windows |
| `BRIDGE_WINDOWS_NODE_RUNTIME` | `system` | No Windows, usa `system` ou o runtime portátil previamente preparado; o plugin distribuído define `portable` |
| `BRIDGE_WINDOWS_NODE_CACHE_DIRECTORY` | `~/.antigravity-mcp-bridge/windows-runtimes` | Diretório confiável opcional, fora dos projetos, para compartilhar o cache portátil entre diretórios de estado; não é entrada MCP |
| `AGY_PATH` | `agy` | Caminho do CLI oficial |
| `MAX_CONCURRENT_TASKS` | `1` | Processos simultâneos |
| `MAX_QUEUED_TASKS` | `20` | Tarefas aguardando |
| `MAX_RETAINED_TASKS` | `100` | Tarefas persistidas retidas |
| `DEFAULT_TIMEOUT_SECONDS` | `1800` | Prazo máximo por execução |
| `EVENT_BUFFER_SIZE` | `2000` | Eventos mantidos em memória |
| `BRIDGE_MEMORY_MAX_ENTRIES` | `100` | Entradas privadas globais; até 10.000 |
| `BRIDGE_MEMORY_MAX_BYTES` | `1048576` | Texto privado global em UTF-8; até 64 MiB |
| `BRIDGE_MEMORY_MAX_ENTRY_BYTES` | `65536` | Texto por entrada; até 1 MiB, sem exceder o limite global |
| `BRIDGE_STATE_DIRECTORY` | `~/.antigravity-mcp-bridge` | Diretório privado de tarefas e sessões |
| `BRIDGE_DEFAULT_MODEL` | vazio | Modelo inicial, usado quando não há preferência salva |
| `BRIDGE_SECRET_EXCLUSIONS` | `[]` | Array JSON de padrões relativos de arquivos que devem ficar fora das cópias |
| `BRIDGE_SECRET_EXCEPTIONS` | `{"version":2,"namePatterns":[]}` | Objeto JSON estrito na versão 2 contendo padrões glob de nomes relativos que pulam exclusivamente a verificação de nomes de credenciais conhecidas (`SECRET_FILE`), sem nunca pular a detecção incremental de conteúdo (`SECRET_CONTENT`); arrays legados não vazios falham com orientação de migração |
| `BRIDGE_ALLOWED_ENV_VARS` | `[]` | Array JSON de nomes exatos adicionais de variáveis permitidas nos subprocessos do CLI |
| `MAX_COPY_FILES` | `10000` | Máximo de arquivos selecionados para a cópia |
| `MAX_COPY_BYTES` | `268435456` | Máximo de bytes copiados (256 MiB) |
| `MAX_CHANGED_FILES` | `100` | Máximo de arquivos alterados para revisão e integração |
| `COPY_RETENTION_HOURS` | `168` | Prazo de retenção das cópias finalizadas |
| `MAX_PROMPT_CHARS` | `50000` | Tamanho máximo do prompt enviado, incluindo critérios, contexto transferido e instruções do bridge e do papel |
| `FORBIDDEN_DIRECTORIES` | vazio | Diretórios bloqueados, separados por `;` no Windows |
Entradas e diretórios são validados. Configurações de ambiente devem ser registradas de modo persistente no ambiente privado de inicialização do servidor (atribuições de exemplo no PowerShell como `$env:VAR = ...` afetam somente o shell atual); reinicie a conexão MCP após qualquer alteração. Tarefas delegadas usam `spawn` sem shell e exigem `--sandbox`; não passam `--dangerously-skip-permissions`. Testes Windows usam o executor LPAC do bridge por padrão. Não inclua credenciais ou documentos privados nos prompts. Mantenha arquivos sensíveis fora da cópia por regras de ignore e selecione apenas os caminhos necessários com `includePaths`. Consulte a [documentação do sandbox](https://antigravity.google/docs/sandbox/) e [do modo headless](https://www.antigravity.google/docs/cli/headless/).
### Padrões de exclusão e exceção de segredos
Os padrões em `BRIDGE_SECRET_EXCLUSIONS` são definidos como um array JSON de strings com caminhos relativos à raiz do projeto. Já `BRIDGE_SECRET_EXCEPTIONS` adota formato de objeto JSON versionado estrito: `{"version": 2, "namePatterns": ["fixtures/.env.local"]}`. Ambos suportam curingas glob: `*` (segmento individual), `?` (um caractere) e `**` (múltiplos diretórios), sem permitir travessia de diretório (`..`), caracteres NUL ou caminhos absolutos. Nomes sem barra correspondem ao nome base (basename) em qualquer diretório; `**/` e `/**/` correspondem a zero ou mais diretórios intermediários. A comparação é insensível a maiúsculas e minúsculas (case-insensitive). Arrays legados não vazios são rejeitados com diagnóstico de migração (sem expor valores sensíveis); a omissão ou um array vazio `[]` normaliza para política vazia `{"version": 2, "namePatterns": []}`.
Prefira exceções restritas a arquivos revisados e sem credenciais reais (como o exemplo sintético `BRIDGE_SECRET_EXCEPTIONS='{"version": 2, "namePatterns": ["fixtures/.env.local"]}'`), evitando padrões glob amplos. Na versão 2, a exceção pula apenas a checagem de nome de arquivo de credencial conhecida (`isKnownCredentialFile` / `SECRET_FILE`); todo o conteúdo permitido continua sendo inspecionado pelo scanner de segredos (`detectSecretContent` / `SECRET_CONTENT`) e nunca é ignorado por exceções de nome.
A ordem de precedência e segurança é estrita:
1. Regras de ignore do Git e verificações de caminhos inseguros (`UNSAFE_PATH`) SEMPRE vencem e têm prioridade máxima sobre qualquer exceção.
2. Deny explícito (`BRIDGE_SECRET_EXCLUSIONS` gerando `SECRET_EXCLUSION`) sempre vence qualquer exceção (`BRIDGE_SECRET_EXCEPTIONS`).
3. Exceção explícita v2 (`BRIDGE_SECRET_EXCEPTIONS`) pula unicamente o bloqueio padrão de nome de credencial (`SECRET_FILE`), mantendo integralmente a varredura e bloqueio por conteúdo (`SECRET_CONTENT`).
O preflight preventivo não garante a detecção de segredos arbitrários embutidos em código-fonte, formatos proprietários ou desconhecidos, dados criptografados ou arquivos ofuscados.
### Barreiras de segurança em prévias, contexto e artefatos
A prévia inspeciona nomes e padrões de credenciais conhecidos antes de formar uma cópia dos bytes verificados para staging no Git privado, restaurando o índice privado com `read-tree HEAD` ao final. A leitura de patches por arquivo (`readProjectPatch`) extrai a fatia correspondente diretamente do patch revisado e verificado (`preview.patch`), vinculando-se estritamente ao mesmo hash SHA-256 e dispensando novas leituras inseguras do índice compartilhado ou da árvore de trabalho. Arquivos gerados ou modificados que violem a política falham com `BLOCKED_FILE_DETECTED`; alterações detectadas durante a preparação invalidam a operação. Restaurar o índice não remove objetos que já existiam no banco do Git.
Snapshots, fingerprints e bifurcações aplicam os ignores da origem e da cópia e a política de segredos. Arquivos gerados bloqueados são omitidos; um arquivo do baseline que se torne bloqueado causa `CONTEXT_CHANGED`. Skills fornecidas e políticas de execução conservam verificações próprias de integridade.
A coleta e a leitura de artefatos reaplicam a política de nomes, conteúdo e exclusões. Violações de segredo falham com `BLOCKED_ARTIFACT_PATH`. A leitura verifica os bytes contra o SHA-256 da inspeção e da referência, mantendo somente a janela solicitada em memória. Referências anteriores não dispensam os controles de caminho e política. Essas verificações cobrem os formatos reconhecidos pelo scanner e não garantem detectar segredos arbitrários nem eliminar toda corrida possível do filesystem.
### Ambiente do subprocesso do CLI (`cliEnvironment`)
O subprocesso do CLI utiliza um ambiente estritamente filtrado por `cliEnvironment` em vez de herdar o ambiente do host indiscriminadamente. O bridge não registra valores de variáveis de ambiente nem passa tokens como argumentos. A variável `BRIDGE_ALLOWED_ENV_VARS` aceita um array JSON de nomes exatos adicionais para inclusão (opt-in), por exemplo `BRIDGE_ALLOWED_ENV_VARS='["MY_TOOL_SETTING"]'`. Por padrão, nenhuma injeção ou variável arbitrária é permitida; a inclusão de variáveis é estritamente opt-in e não é o comportamento padrão. A correspondência respeita as regras de plataforma (case-insensitive no Windows e exata/case-sensitive no Unix/Linux/macOS), preservando a deduplicação e `PATHEXT`.
Por motivos de segurança, variáveis de injeção de runtime e preload de bibliotecas (`NODE_OPTIONS`, `NODE_PATH` e os namespaces `LD_*` e `DYLD_*`) são estritamente proibidas para opt-in em `BRIDGE_ALLOWED_ENV_VARS` e chamadas diretas a `cliEnvironment`, inclusive com variações de maiúsculas/minúsculas ou espaços em branco em qualquer plataforma. Tentativas de opt-in dessas variáveis falham com erro estruturado nomeando a variável rejeitada, sem jamais ecoar seu valor. Opt-ins de variáveis legítimas não injetáveis, certificados como `NODE_EXTRA_CA_CERTS` e todos os defaults de sistema, perfil, keyring nativo, proxies, certificados corporativos e autenticação oficial Google / ADC continuam preservados. Demais credenciais de provedores e APIs de terceiros (como AWS, GitHub/GH, OpenAI e Stripe) e agentes locais (`SSH_AUTH_SOCK`, `GPG_AGENT_INFO`) continuam omitidos por padrão.
As variáveis padrão permitidas são agrupadas exatamente conforme definido no `cliEnvironment`:
- **Resolução de sistema e executáveis**: `PATH`, `PATHEXT`, `SystemRoot`, `SystemDrive`, `ComSpec`, `WINDIR`, `SHELL`, `TERM`, `COLORTERM`.
- **Diretórios de usuário e perfil**: `HOME`, `USERPROFILE`, `APPDATA`, `LOCALAPPDATA`, `HOMEDRIVE`, `HOMEPATH`, `USER`, `LOGNAME`, `USERNAME`.
- **Diretórios temporários**: `TEMP`, `TMP`, `TMPDIR`.
- **Localidade, idioma e fuso horário**: `LANG`, `LC_ALL`, `LC_CTYPE`, `LC_MESSAGES`, `TZ`.
- **Diretórios base XDG e autenticação de sessão / keyring nativo**: `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_CACHE_HOME`, `XDG_RUNTIME_DIR`, `XDG_DATA_DIRS`, `XDG_CONFIG_DIRS`, `DBUS_SESSION_BUS_ADDRESS`, `GNOME_KEYRING_CONTROL`, `GNOME_KEYRING_PID`, `SECURITYSESSIONID`.
- **Contexto de sessão remota SSH (sem credenciais)**: `SSH_CONNECTION`, `SSH_CLIENT`, `SSH_TTY`.
- **Configurações de rede e proxy**: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`, `http_proxy`, `https_proxy`, `all_proxy`, `no_proxy`.
- **Certificados SSL/TLS (corporativos e raízes customizadas)**: `SSL_CERT_FILE`, `SSL_CERT_DIR`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, `NODE_EXTRA_CA_CERTS`.
- **Autenticação oficial Google / Gemini e endpoints customizados**: `GEMINI_API_KEY`, `GOOGLE_GEMINI_BASE_URL`, `GOOGLE_APPLICATION_CREDENTIALS`, `GOOGLE_CLOUD_PROJECT`, `GCLOUD_PROJECT`, `GOOGLE_CLOUD_UNIVERSE_DOMAIN`.
- **Ambiente Windows, arquitetura e contexto de domínio**: `OS`, `PROCESSOR_ARCHITECTURE`, `PROCESSOR_ARCHITEW6432`, `NUMBER_OF_PROCESSORS`, `ProgramData`, `ProgramFiles`, `ProgramFiles(x86)`, `CommonProgramFiles`, `CommonProgramFiles(x86)`, `USERDOMAIN`, `USERDNSDOMAIN`, `COMPUTERNAME`.
Erros comuns e diagnósticos estruturados incluem `AGY_NOT_FOUND`, `AGY_PERMISSION_DENIED`, `AGY_PROBE_FAILED`, `AGY_INCOMPATIBLE`, `CLI_INPUT_FAILED`, `AGY_IO_FAILED`, `AGY_PROCESS_FAILED`, `TASK_CANCELLED`, `TASK_TIMEOUT`, `AGY_AUTH_REQUIRED`, `MODEL_NOT_AVAILABLE`, `INVALID_WORKING_DIRECTORY` e `QUEUE_FULL`. Se houver `AGY_AUTH_REQUIRED`, faça login no `agy` interativo. Se as ferramentas não aparecerem no Codex, confirme a instalação com `codex plugin list --json` e abra uma conversa nova.
## Testes
```powershell
npm.cmd run typecheck
npm.cmd run lint
npm.cmd test
npm.cmd run build:plugin
npm.cmd run test:package
```
`npm test` usa um mock do `agy` e não consome quota. `npm run test:package` também consulta o status do runtime pelo pacote empacotado; em plataformas fora do Windows ele deve informar `supported: false` sem preparar nada. A integração real é opcional: `npm run test:integration` cria um repositório descartável, executa uma tarefa pelo cliente MCP, confere que o original permanece intacto até a integração e remove o repositório. Esse teste simula a resposta de confirmação somente para seu projeto descartável; a confirmação humana da interface deve ser usada nos projetos reais. Execute-a apenas com `agy` autenticado e quando quiser usar a conta real.
## Licença e políticas
O projeto usa a [licença MIT](LICENSE). Consulte a [política de segurança](SECURITY.md), a [política de privacidade](PRIVACY.md), o [histórico de versões](CHANGELOG.md) e os [avisos das dependências distribuídas](THIRD_PARTY_NOTICES.md). `npm run build:plugin` atualiza o bundle e os avisos a partir das dependências efetivamente incluídas.
TDQS
B3.4/5.0
Scored across 23 tools
Disambiguation4/5
Tools generally target distinct lifecycle stages (run/resume/cancel, preview/read_patch/read_result, test/verify/integrate), but several reading/status tools have adjacent purposes. The descriptions help separate result vs read_result and preview vs read_patch, though an agent could still confuse them.
Naming Consistency4/5
All tools consistently use the antigravity_ prefix with snake_case, which makes the set predictable. Most names are verb_noun or verb_noun-phrase, but some are noun-only query tools (usage, status, tasks, events, result, sessions), a minor deviation from a strict pattern.
Tool Count3/5
23 tools is heavy for a single MCP server and sits in the borderline 16-25 range. The domain is complex, but several output-reading and status tools could be consolidated, making the surface feel somewhat over-scoped.
Completeness4/5
The surface covers model selection, task lifecycle, file listing, patch/result reading, testing, verification, integration, and cleanup. Minor gaps exist, such as no explicit authentication/login tool or direct source-file read outside task artifacts, but core workflows are covered.
Maintenance
ActivityMaintained
ResponsivenessNo issues