ai-execution-protocol 0.11.1

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

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

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:

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

Instalacao

Instale com npm:

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:

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:

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:

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

Ative automacao local estrita depois de consentimento explicito:

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:

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:

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

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:

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:

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
• Prontidao de implementacao de host
• Configuracao MCP em IDEs
• Exemplo de smoke do adapter

Observabilidade

Execucoes controladas podem gravar um trace local em:

.ai-protocol-run/trace.jsonl

Resuma o trace:

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

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:

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:

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.