Metadata-Version: 2.4
Name: ai-execution-protocol
Version: 0.11.1
Summary: Framework instalavel para agentes de IA com risco, contexto, validacao, traces e runtime enforcement via runners, MCP, gateway, profiles, sandbox e skills governadas.
Author: AI Execution Protocol
License-Expression: MIT
Project-URL: Homepage, https://github.com/rodneigk2/ai-execution-protocol
Project-URL: Repository, https://github.com/rodneigk2/ai-execution-protocol.git
Project-URL: Issues, https://github.com/rodneigk2/ai-execution-protocol/issues
Keywords: ai,agent,codex,agent-safety,context-management,protocol,risk,validation,prompt,guardrails,observability
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Dynamic: license-file

# AI Execution Protocol

Framework instalavel para agentes de IA com risco, contexto, validacao, traces
e runtime enforcement via runners, MCP, gateway, profiles, sandbox e skills
governadas.

AI Execution Protocol, ou AEP, e um framework para governar a execucao de
agentes dentro de projetos reais. Ele combina protocolo, ponte MCP local,
gateway, traces e checks para orientar como um agente le contexto, escolhe
ferramentas, altera arquivos, valida entregas e declara limites. Quando o fluxo
passa por runner, proxy, hook, CI ou host integrado, esses checks podem bloquear
acoes fora do plano.

O AEP mira a fronteira operacional do trabalho tecnico no repositorio:
classificacao de risco, contexto minimo, politicas de ferramenta, gates
executaveis e evidencias antes da finalizacao.

Ele transforma um pedido em um contrato de execucao delimitado:

- classificar risco antes de agir;
- carregar apenas o contexto necessario para a rota;
- selecionar o menor conjunto de capacidades e ferramentas;
- bloquear chamadas planejadas quando runner, proxy, hook, CI ou integracao de
  host configurada chama o gateway;
- validar o resultado antes da entrega;
- relatar evidencias, limites e risco residual.

O alvo padrao e trabalho local com agentes de codigo, especialmente tarefas em
repositorios no estilo Codex. Garantias fortes exigem uma fronteira executavel.
Sem runner, proxy, hook, CI ou integracao de host, o AEP e disciplina de
execucao `best_effort`, nao um sandbox fisico.

O AEP nao depende de controle exclusivo da IDE para ser util. O modo normal em
hosts comuns e `wrapped_enforced`: o protocolo governa os caminhos que passam
por `ai-protocol run`, hooks, CI, proxy, MCP ou adapter, e declara ferramentas
diretas restantes como `governed_bypass`. `host_enforced` e uma prova adicional
para hosts que conseguem esconder ou rotear todas as ferramentas, nao um
pre-requisito para usar o AEP.

A base de runtime agora tambem inclui provider OpenAI-compatible, profiles
genericos, RBAC de gateway, sandbox local/Docker e instalacao de skills com
manifest e quarentena. Esses recursos fortalecem os caminhos governados sem
prometer controle fisico sobre ferramentas diretas que o host ainda exponha.

O Prompt Compiler adiciona `ai-protocol prompt compile` e `aep prompt compile`
como dry-run para estruturar pedidos vagos sem executar tools, shell ou providers.

## O Que O AEP Resolve

Agentes de IA que trabalham em codigo falham de formas previsiveis:

- agem antes de entender impacto;
- carregam contexto demais e perdem a tarefa real;
- tratam trabalho arriscado como edicao simples;
- usam ferramentas que nunca foram selecionadas;
- pulam validacao ou alegam testes que nao rodaram;
- entregam sem declarar o que ainda esta incerto.

O AEP mantem tarefas simples rapidas e aumenta o processo apenas quando o risco
justifica.

## AEP Como Camada De Controle

O AEP adiciona uma camada de controle instalada no projeto para tornar a
execucao verificavel. Ele nao substitui revisao de engenharia, mas organiza o
caminho minimo para agir com contexto, permissao, validacao e rastreabilidade.

## Fluxo Principal

```text
entender -> classificar risco -> mapear impacto -> executar -> validar -> relatar
```

O protocolo combina:

- niveis de risco, de respostas diretas a operacoes sensiveis;
- route packs para evitar carregar o protocolo inteiro em toda tarefa;
- memoria adaptativa que orienta o trabalho sem substituir o pedido atual;
- orcamentos de contexto para evitar arquivos e tokens desnecessarios;
- roteamento de capacidades para skills, MCPs, ferramentas e acoes externas;
- roteamento custo-qualidade para economizar sem reduzir correcao ou validacao;
- validacao seletiva baseada no raio de impacto;
- contratos comportamentais para aderencia observavel do agente;
- gates executaveis para runners, hooks, proxies, CI e integracoes de host;
- traces locais sem coletar logs completos ou arquivos-fonte;
- feedback consentido de execucoes reais para avaliacao local.

## Modos De Garantia

O AEP declara de forma explicita o que pode e o que nao pode impor.

| Modo | Caminho controlado | O que pode impor | Limite principal |
| --- | --- | --- | --- |
| `best_effort` | `AGENTS.md` e blocos de instrucao da IDE | Melhor planejamento, disciplina de contexto e relato | Ferramentas diretas do host ainda podem desviar do AEP |
| `wrapped_enforced` | `ai-protocol run`, `run-auto`, hooks, CI ou runners locais | Plano valido, comando permitido e evidencia de validacao para o caminho encapsulado | Comandos fora do wrapper entram como `governed_bypass` |
| `proxy_enforced` | Chamadas de ferramenta pelo proxy ou gateway do AEP | Bloqueia chamadas nao planejadas ou sem suporte antes da execucao | Bypass direto deve ser declarado se o host ainda expuser a ferramenta |
| `host_enforced` | Uma integracao de host chama o gateway antes de cada ferramenta | Checks obrigatorios naquele caminho de ferramenta | Ainda exige validacao do raciocinio do modelo |

`wrapped_enforced` e o alvo operacional principal para hosts que nao oferecem
controle exclusivo. Nessa condicao, o AEP trabalha sobre a impossibilidade de
mandar em todas as ferramentas: ele reduz a superficie governando os caminhos
controlados, exige relato de acoes fora do wrapper e mantem
`host_direct_tool_bypass` como risco residual explicito.

A fronteira mais forte vem de controle executavel, nao de um prompt maior:

```text
instrucoes -> runner/hooks -> gateway local -> integracao propria
```

## Instalacao

Instale com npm:

```powershell
npm install -g ai-execution-protocol
ai-protocol init C:\path\to\project
ai-protocol verify C:\path\to\project
```

Use sem npm/PyPI a partir de clone ou ZIP com `.\install.ps1 -Portable` no Windows
ou `./install.sh --portable` no Linux/macOS/WSL. Nao exige admin nem altera PATH.

Prepare dependencias basicas do ambiente:

```powershell
ai-protocol bootstrap check
ai-protocol bootstrap plan --include-optional
ai-protocol bootstrap install --yes
```

O `bootstrap` segue o padrao de CLIs modernas: detecta Python, Node.js, npm,
Git e ripgrep, reaproveita o que ja existe e so instala pacotes do sistema com
confirmacao explicita. Dependencias opcionais como GitHub CLI e Docker entram
apenas com `--include-optional`.

Ou com Python:

```powershell
python -m pip install --upgrade ai-execution-protocol
ai-protocol install C:\path\to\project
ai-protocol verify C:\path\to\project
```

Previsualize a instalacao sem escrever arquivos:

```powershell
ai-protocol install C:\path\to\project --dry-run
```

Ative automacao local estrita depois de consentimento explicito:

```powershell
ai-protocol setup-local C:\path\to\project --yes --real-tests accept
```

Isso instala o protocolo, conclui o onboarding, adiciona hooks/scripts
encapsulados quando disponiveis, cria `.aep-host/` com uma ponte MCP local do
projeto e inicia o host runtime com scheduler de agentes quando possivel. Com
`--yes`, tambem cria as configuracoes MCP locais conhecidas: `.vscode/mcp.json`,
`.cursor/mcp.json` e `.mcp.json`. O resultado esperado da verificacao e `PASS`.

O consentimento cobre criacao e atualizacao de arquivos locais dentro do
projeto. A IDE ainda pode pedir trust, reload ou aceite do MCP; esse clique
continua sendo uma confirmacao do usuario no host.

Inspecione a ponte de host:

```powershell
ai-protocol host doctor C:\path\to\project
ai-protocol host diagnose C:\path\to\project
ai-protocol host mcp-config C:\path\to\project
```

Quando o mesmo host MCP atende mais de um projeto, ative o alvo atual sem
editar a configuracao global:

```powershell
ai-protocol host activate C:\path\to\project
```

O MCP gerado tambem aceita `project_root`/`target` nas tools e valida que o
alvo contem `AGENTS.md` e `protocol/fast-path.yaml`. Se nao conseguir resolver
um projeto AEP valido, ele falha fechado em vez de executar no repositorio
errado.

## Quickstart De 60 Segundos

```powershell
ai-protocol init-example C:\tmp\aep-example
cd C:\tmp\aep-example
ai-protocol install .
ai-protocol workflow run workflow.yaml
ai-protocol workflow report
ai-protocol trace-report . --html
```

Para um script local de pacote, use o caminho estrito gerado:

```powershell
ai-protocol run-auto --target C:\path\to\project --risk 1 --npm-script test
```

Para transformar um pedido em prompt operacional sem chamar IA extra:

```powershell
ai-protocol improve-prompt "corrige o bug do chat" --json
```

O modo padrao `lite` usa heuristicas locais, preserva prompts bons e so expande
quando faltar escopo, restricao, validacao ou controle pelo AEP Host/MCP.

## Baseline Operacional

O AEP v0.10.0 consolidou um baseline operacional proprio. Tudo entra com gate,
auditoria e limite explicito.

- `bootstrap`: detecta e prepara dependencias basicas do ambiente.
- `memory`: registra memoria candidate-first antes de aprovar conhecimento.
- `skill`: audita skills sem conceder ferramentas automaticamente.
- `tools`: lista, ativa, desativa e audita ferramentas por politica local.
- `board`: cria um Kanban local para tarefas persistentes de agentes.
- `mcp`: lista e audita catalogo de servidores MCP por risco.
- `model`: escolhe tier de modelo por risco e tarefa.
- `sandbox`: planeja backend local, Docker, WSL ou SSH sem substituir gates.
- `monitor`: registra checks recorrentes locais.
- `lsp`: roda diagnosticos semanticos minimos por arquivo.
- `guard`: verifica segredos e politica de rede para tarefas sensiveis.

Esses comandos sao o baseline integrado. Eles nao prometem autonomia irrestrita
nem isolamento fisico quando o host nao fornece essa fronteira.

## Runtime Adapter

O AEP pode encapsular caminhos de execucao com um runtime adapter pequeno e
auditavel:

- [Templates de stack](./docs/34-stack-templates.md)
- [Prontidao de implementacao de host](./docs/35-host-implementation-readiness.md)
- [Configuracao MCP em IDEs](./docs/36-configuracao-mcp-ides.md)
- [Exemplo de smoke do adapter](./examples/adapter_quickstart_smoke.py)

## Observabilidade

Execucoes controladas podem gravar um trace local em:

```text
.ai-protocol-run/trace.jsonl
```

Resuma o trace:

```powershell
ai-protocol trace-report C:\path\to\project
ai-protocol trace-report C:\path\to\project --html
ai-protocol trace-report C:\path\to\project --summary
```

O relatorio HTML mostra timeline de eventos, status, nivel de risco,
capacidades selecionadas, resultado de tool calls, eventos de validacao e
campos de risco residual quando existirem.

## Comandos Principais

```powershell
ai-protocol verify C:\path\to\project
ai-protocol --version
ai-protocol bootstrap check
ai-protocol memory status C:\path\to\project
ai-protocol board list C:\path\to\project
ai-protocol skill list C:\path\to\project
ai-protocol tools list C:\path\to\project
ai-protocol tools disable local_files C:\path\to\project
ai-protocol mcp catalog C:\path\to\project
ai-protocol model route --task "publicar pacote" --risk 3
ai-protocol sandbox plan --backend docker --risk 3
ai-protocol monitor list C:\path\to\project
ai-protocol lsp check C:\path\to\project --file package.json
ai-protocol guard network --task "publish pacote" --risk 3
ai-protocol doctor C:\path\to\project
ai-protocol strict-status C:\path\to\project
ai-protocol host setup C:\path\to\project --yes
ai-protocol host doctor C:\path\to\project
ai-protocol host diagnose C:\path\to\project --json
ai-protocol host activate C:\path\to\project
ai-protocol agent status C:\path\to\project --request "corrigir bug de auth" --risk 2
ai-protocol codex profile plan --target C:\path\to\project --preset coding
ai-protocol codex profile auto --target C:\path\to\project --task "corrigir testes" --yes
ai-protocol codex profile apply --target C:\path\to\project --preset coding --yes
ai-protocol improve-prompt "corrige o bug do chat" --json
ai-protocol preflight C:\path\to\project --plan plan.json
ai-protocol check-call C:\path\to\project --input call.json
ai-protocol proxy-call C:\path\to\project --input proxy-call.json
ai-protocol run-checks C:\path\to\project --plan plan.json --report report.json
ai-protocol run --target C:\path\to\project --plan plan.json --call call.json --report report.json --npm-script test
ai-protocol run-auto --target C:\path\to\project --risk 1 --npm-script test
ai-protocol trace-report C:\path\to\project --html
ai-protocol feedback-status C:\path\to\project
```

Use `doctor` e `strict-status` para ver se um projeto alvo esta em
`best_effort`, `wrapped_enforced`, `proxy_enforced` ou `host_enforced`.

Use `codex profile` para preparar `.codex/config.toml` por projeto com skills
ligadas ou desligadas por preset. O comando escreve apenas um bloco gerenciado,
faz backup antes de alterar e exige reiniciar o Codex para a sessao carregar a
nova configuracao. Isso reduz contexto; permissoes reais continuam dependendo
de host, gateway, sandbox e politicas de ferramenta.
Use `codex profile auto --task "<pedido>" --yes` para escolher automaticamente
entre `coding`, `docs`, `data` e `design` antes de iniciar ou reiniciar a
sessao do Codex.

Gere artefatos estritos em vez de escrever JSON manualmente:

```powershell
ai-protocol plan new --target . --risk 1 --cap shell --scope "run tests" --out .ai-protocol-run/plan.json
ai-protocol call new --target . --plan .ai-protocol-run/plan.json --capability shell --operation write --tool-target "npm run test" --confirmed --out .ai-protocol-run/call.json
ai-protocol report new --target . --plan .ai-protocol-run/plan.json --status unchanged --evidence "tests passed" --residual-risk "semantic review still required" --out .ai-protocol-run/report.json
```

## Estrutura Do Projeto

- `AGENTS.md`: arquivo principal de instrucao para agentes de IA neste repo.
- `INDEX.yaml`: mapa estruturado de navegacao.
- `config.yaml`: alvo atual, versao do protocolo e modo padrao.
- `protocol/`: regras operacionais compactas em YAML.
- `behavior/`: contrato comportamental observavel e checklist de auditoria.
- `capabilities/`: registro de capacidades e politica de exposicao.
- `ai-protocol-enforcement/`: gateway executavel local e politica.
- `ai-protocol-onboarding/`: configuracao local consentida do host.
- `ai-protocol-feedback/`: consentimento visivel de feedback e runs locais.
- `docs/`: documentacao conceitual.
- `examples/`: adapters, quickstarts e templates de stack.
- `schema/`: schemas de validacao.
- `scripts/`: instalacao, validacao, benchmark e checks de pacote.
- `apps/aep-host/`: scaffold de host local com API Node, SQLite local por
  padrao, ponte MCP, agentes e worker Python controlado.
- `real-runs/`: lotes locais importados de feedback.
- `dist/minimal/`: distribuicao minima instalavel gerada.

## Status E Limites

Status: alpha operacional.

Para uso local com agentes persistentes, o caminho padrao usa SQLite local:

```powershell
ai-protocol host install --yes
ai-protocol host status
ai-protocol host enable-autostart
```

O Host usa SQLite local por padrao e `host install --yes` inicia host e scheduler
de agentes. Use `--without-agents` apenas para instalar/migrar sem ligar os
agentes. O runtime tambem pode ser operado com `host start`, `host stop`, `host
logs`, `host backup`, `host restore` e `host reset`.

O AEP inclui CLIs npm/Python, instalacao em projeto, onboarding, roteamento de
risco, orcamento de contexto, memoria adaptativa, gates de
capacidades, politica custo-qualidade, validacao seletiva, gateway local de
enforcement, runtime adapter, templates de stack, relatorios de trace e feedback consentido
de execucoes reais.

Trabalho critico ainda exige revisao de engenharia, testes reais, sandboxing,
confirmacao explicita e julgamento de engenharia.

## Licenca

MIT. Veja [LICENSE](./LICENSE).
