# 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 arquivos de autenticação. A comunicação com o serviço é feita pelo próprio `agy`.

## Requisitos

- Node.js 24 ou mais recente e npm.
- Git instalado e disponível no `PATH`.
- [Antigravity CLI oficial](https://www.antigravity.google/docs/cli/overview/) instalado e disponível no `PATH`. Você também pode definir `AGY_PATH` com o caminho absoluto do executável.
- Autenticação concluída no `agy` interativo. Consulte a [documentação oficial do modo headless](https://www.antigravity.google/docs/cli/headless/).

O bridge foi testado com `agy` 1.2.16 e `@modelcontextprotocol/sdk` 1.30.1. Ele exige que o CLI anuncie `--sandbox` e `stream-json`; versões futuras podem exigir adaptação. Consulte abaixo a limitação observada na execução de testes no Windows.

## Versões disponíveis

A **0.5.1** está publicada no npm e inclui perfis, espera com progresso, transferência entre papéis, comparação de modelos e papéis personalizados. Os exemplos npx abaixo usam essa versão.

O código-fonte e o plugin deste repositório preparam a **0.5.2**, com correção do ambiente de execução Windows, diagnósticos específicos do sandbox e recusa de recibos com bypass. A publicação dessa versão no npm está pendente.

A 0.5.1 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.5.1, configure seu cliente MCP com:

```json
{
  "mcpServers": {
    "antigravity": {
      "command": "npx",
      "args": ["--yes", "antigravity-mcp-bridge@0.5.1"]
    }
  }
}
```

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.

### 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 na 0.5.1 | Catálogo e execução |
| --- | --- | --- |
| `full` (padrão) | 29 | Todas as ferramentas; preserva a configuração existente |
| `query` | 20 | Consulta, modelos, sessões, handoff e comparação; tarefas somente em leitura |
| `review` | 23 | Consulta mais prévia, leitura de patches e verificação; tarefas somente em leitura |
| `implementation` | 29 | 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 confirmação de 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.

## 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.

## 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_roles` | Lista os papéis nativos e personalizados configurados |
| `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 testes pelo terminal do agy com sandbox nativo e captura recibos reais |
| `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` | Solicita confirmação via MCP e aplica o patch revisado ao original |
| `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.

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 confirmação disponível. 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. Execute os testes pertinentes com `antigravity_test`, usando o hash da prévia. A ferramenta devolve outro `taskId`: acompanhe e revise esse ID, confira recibos, 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 os recibos observados 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 solicitar a confirmação humana. 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 integração exige suporte do cliente a **MCP form elicitation**. `antigravity_health` informa `integrationApproval.available`. 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.2.16. 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.

### 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.

## 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.

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` têm `source: "agy-tool"` e incluem o recibo observado do terminal. Cada registro leva hash, data, exit code e até 4.000 caracteres de saída. 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.

A cópia aceita até 10.000 arquivos e 256 MiB por padrão. A seleção é medida antes da criação e os bytes efetivamente copiados são conferidos novamente para detectar crescimento da origem. `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.

O executor usa `agy --sandbox` e a ferramenta nativa `run_command`. Não exige Docker nem executa o comando diretamente no host como alternativa. Um runner temporário, conferido por SHA-256 antes da execução, captura saída, exit code e fingerprints dos arquivos elegíveis antes/depois do teste. O bridge aceita o recibo apenas no evento da chamada exata do terminal; uma mensagem do Gemini dizendo que o teste passou não conta. Os registros têm `source: "agy-tool"` e `sandbox: "agy-native-requested"`. A saída é limitada a 4.000 caracteres, com indicação de truncamento.

Quando não há recibo válido e a causa não foi identificada, o resultado é `TEST_EXECUTION_UNVERIFIED`. Os diagnósticos específicos abaixo preservam falhas conhecidas do runtime. Um comando não zero produz `TEST_FAILED`; mudanças nos arquivos durante/depois do comando produzem `TEST_CHANGED_PATCH`. Testes observados precisam continuar atuais para a integração; um relato manual não substitui um teste observado falho. Após `TEST_FAILED`, é possível retomar a conversa para corrigir ou executar os testes novamente. A orientação de correção mantém o comando original e proíbe enfraquecer os testes; tentativas observadas além do limite encerram a tarefa.

| Código | Evidência e ação |
| --- | --- |
| `AGY_SANDBOX_ACCESS_DENIED` | O runtime relatou falha ao conceder acesso ao alvo. Confira o caminho e as ACLs; esse erro sozinho não demonstra que o setup inicial está ausente. |
| `AGY_SANDBOX_SETUP_REQUIRED` | A solicitação administrativa de setup não foi concluída, inclusive quando `denied_actions` informa `escalate_admin`. Confira a disponibilidade do broker do runtime atual. |
| `AGY_SANDBOX_BYPASS_DENIED` | O runtime relatou uma recusa de execução fora do sandbox. Preserve essa recusa. |
| `AGY_SANDBOX_BYPASS_REQUESTED` | A chamada declarou bypass ou um valor incompatível para essa opção. Seu recibo não verifica execução isolada. |

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 executáveis nativos como `node.exe` e `python.exe`; para npm, use `npm.cmd`. Arquivos `.cmd`/`.bat` aceitam argumentos comuns, mas metacaracteres de shell são recusados. A execução depende das permissões do sandbox nativo do CLI. Uma restrição de terminal não demonstra isolamento de todas as ferramentas do agente nem permite afirmar proteção completa do sistema de arquivos. Consulte a [configuração oficial do sandbox](https://www.antigravity.google/docs/sandbox/) e os [eventos de ferramentas no modo headless](https://www.antigravity.google/docs/cli/headless/#tool-calls-in-the-stream).

Na configuração inicial do sandbox Windows, o CLI pode pedir uma elevação UAC. Quando o runtime indicar setup administrativo pendente, abra `agy --sandbox` em uma pasta descartável e, no prompt do próprio Antigravity, peça `Execute node.exe --version`. O cartão de configuração apresenta `Yes, elevate`; confira o aplicativo solicitante e confirme o diálogo do Windows. Uma tela de sandbox bypass é uma solicitação distinta. Depois, verifique o executor pelo recibo de `antigravity_test`. Um comando executado no PowerShell após sair do agy e `antigravity_health.capabilities.sandbox: true` não comprovam a preparação do sandbox. Falhas de ACL precisam de diagnóstico do alvo; repetir o setup para cada projeto não é uma correção demonstrada.

A versão 0.4.1 foi validada com execução real no Windows após essa configuração: o recibo capturou exit code 0, a origem permaneceu intacta e um marcador artificial fora da cópia teve leitura e escrita negadas. O snapshot Git do runner fica temporariamente dentro da cópia montada no sandbox, excluído do fingerprint e removido ao terminar. Esse teste comprova os cenários observados; não atesta todas as ferramentas do agente nem todas as fronteiras do sistema de arquivos. A suíte padrão continua usando um CLI simulado.

No `agy` 1.2.16, os testes reais passaram enquanto o broker administrativo da sessão de configuração estava ativo. Depois de encerrar essa sessão e seu filho, uma nova execução headless pediu `escalate_admin` e terminou sem recibo. Portanto, a confirmação anterior de setup não comprova disponibilidade após o encerramento do processo que mantinha o broker. O bridge ainda não gerencia esse ciclo de vida; esse limite precisa ser resolvido antes de afirmar funcionamento independente no Windows.

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_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` |
| `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_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 |
| `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. O processo é iniciado com `spawn` sem shell e exige `--sandbox`; não passa `--dangerously-skip-permissions`. Não inclua credenciais ou documentos privados nos prompts. O sandbox do CLI restringe comandos de terminal, mas não constitui garantia de isolamento completo do sistema de arquivos no Windows. 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/).

Erros comuns incluem `AGY_NOT_FOUND`, `AGY_AUTH_REQUIRED`, `MODEL_NOT_AVAILABLE`, `INVALID_WORKING_DIRECTORY`, `QUEUE_FULL` e `AGY_PROCESS_FAILED`. 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. 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.