[P0][Integration] Tornar Runtime + Agent obrigatórios no Code e entregar painel proativo do Agent

[wesleysimplicio]

Emenda canônica — Code exige Agent + Runtime

Precedência: esta seção substitui qualquer redação conflitante abaixo, inclusive “Agent opcional”, coordinator=builtin|external produtivo, fallback de coordenador e aceite que permita operar produtivamente sem o Simplicio Agent.

Decisão vigente solicitada pelo mantenedor:

• Simplicio Runtime é totalmente independente do Simplicio Code.
• Simplicio Agent é totalmente independente do Simplicio Code.
• Simplicio Code depende obrigatoriamente de Simplicio Runtime e Simplicio Agent no modo produtivo.
• Dentro do Code, o Simplicio Agent é o coordenador cognitivo único do turno; o Runtime executa/prova efeitos; o Loop Hub agenda recursos/waves; o Mapper fornece contexto canônico.
• Ausência, incompatibilidade ou estado inseguro do Agent ou Runtime bloqueia turno/efeito produtivo. Só diagnóstico explícito, sem tool/effect, pode continuar degradado.
• Não há fallback produtivo para agente embutido ou coordenador externo dentro do produto Simplicio Code.
• Isso não torna Agent ou Code donos do Runtime: fora do Code, o Runtime continua utilizável por outros coordenadores através de seus contratos públicos.
• O Code deve incorporar todos os comandos/capabilities do ecossistema por adapters versionados, sem copiar engines nem criar outro scheduler.
• A lateral do Agent deve ser visível, não roubar foco, observar o desenvolvimento com consentimento e emitir finding/risk/suggestion; qualquer efeito continua sujeito a approval e Runtime.
• A issue só fecha após as quatro superfícies, turn adapter, painel proativo, Runtime-only tools, reconnect/cancel/replay e E2E instalado estarem comprovados.

Critérios conflitantes abaixo são históricos e não autorizam fechamento.

---

Contexto

Relaciona-se a #42 e #43 e consome, sem duplicar:

• simplicio-agent#230: AgentHost quente de sessões/turns;
• simplicio-agent#222: SimplicioBridge tipado para o Runtime;
• simplicio-agent#162: lifecycle e readiness Agent–Runtime;
• simplicio-runtime#3042: execução governada sob coordenadores externos;
• simplicio-runtime#3281: infraestrutura de inferência local;
• simplicio-loop#496: Hub compartilhado e coordenação global de recursos.

O Simplicio Code já possui uma superfície agentic própria. Adicionar o Simplicio Agent sem boundary explícito criaria dois loops cognitivos, duas sessões, tool calls concorrentes e possibilidade de efeitos duplicados.

A decisão obrigatória é: o Simplicio Agent aparece dentro da experiência do Code, mas continua sendo um coordenador independente e opcional. O Runtime executa e prova; o Loop coordena convergência quando escolhido; o Code apresenta UX, sessão, approvals, progresso, diffs e evidências.

Objetivo

Implementar um CoordinatorAdapter para que TUI, headless, ACP e workspace possam abrir, retomar e cancelar sessões/turnos no AgentHost do Simplicio Agent, com streaming tipado e sem incorporar o interpretador Python, copiar o Agent ou tornar o Agent gateway exclusivo do Runtime.

Arquitetura e ownership

Componente	Responsabilidade
Simplicio Code	UX, escolha do modo/coordenador, thread view, approvals, diff e evidência
Simplicio Agent / AgentHost	conversa, planejamento semântico, tool selection e coordenação do turno
Simplicio Runtime	capabilities, sandbox, leases, efeitos, validação, rollback e receipts
Simplicio Loop/Hub	DAG de convergência, filas globais, fairness, backpressure e completion
Simplicio Mapper	contexto canônico e overlays

Modos mínimos:

• coordinator=builtin;
• coordinator=simplicio-agent;
• coordinator=external via ACP/MCP compatível.

Exatamente um coordenador é ativo por turno. Stage agents criados pelo Loop não contam como um segundo coordenador da conversa.

Plano passo a passo

1. Inventariar o lifecycle atual de sessão/turno em TUI, headless, ACP e workspace.
2. Definir CoordinatorProtocol/v1 no Code como interface interna neutra.
3. Implementar adapter do AgentProtocol/v1 fornecido por simplicio-agent#230.
4. Negociar versão, capabilities, profile, coordinator identity e event schemas.
5. Implementar discovery/attach/auto-start autorizado do AgentHost por socket local seguro.
6. Garantir single-flight de startup: várias janelas do Code conectam ao mesmo host/profile compatível.
7. Mapear session.open/close, turn.start/cancel/resume, approval.resolve, reconnect cursor e shutdown/drain.
8. Normalizar eventos: delta, plan, tool intent, approval, effect receipt, validation, finding, delivery e terminal.
9. Propagar IDs causais: workspace/session/turn/attempt/tool/idempotency/run/stage/fence.
10. Congelar toolset e policy por incarnation; mudança exige nova revision.
11. Fazer toda tool execution do Agent atravessar SimplicioBridge/Runtime, nunca um executor local do Code.
12. Integrar leases/capacity do Loop Hub quando disponível; standalone permanece explícito e bounded.
13. Persistir apenas IDs/cursors/estado necessário no Code; SessionDB do Agent permanece canônico.
14. Implementar reconnect e replay de eventos sem repetir efeitos.
15. Distinguir not_started, effect_unknown, completed e terminal.
16. Implementar fallback para outro coordenador somente antes de efeito ou após reconciliação independente.
17. Adicionar seletor/status no Code com coordinator efetivo, AgentHost health e motivo de degradação.
18. Fazer rollout por shadow de eventos, canário, feature flag e kill switch.
19. Atualizar instalador/bundle para resolver versões compatíveis sem copiar estado entre produtos.
20. Conectar o cenário ao Product E2E [P0][#16][Product E2E] Certificar jornada completa do usuário até delivery confirmado #43.

Testes obrigatórios

Contrato

• golden fixtures Code↔AgentHost;
• versão mínima/atual/futura incompatível;
• evento desconhecido e capability ausente;
• ordenação por sequence e replay por cursor;
• paridade semântica entre coordinator builtin e Simplicio Agent para os receipts Runtime.

Integração

• duas janelas do Code compartilhando um AgentHost;
• sessões/profiles distintos sem vazamento;
• streaming, approval, cancel e resume;
• Code/Agent/Runtime reiniciados em cada boundary;
• Runtime indisponível e AgentHost degradado;
• Loop Hub presente/ausente/incompatível.

Sistema/E2E

Tarefa fixture completa:

abrir workspace → mapear → planejar → aprovar → editar via Runtime → testar → revisar → receber receipt → retomar após restart.

Executar em TUI, headless, ACP e workspace.

Segurança

• permissões do socket/named pipe;
• client spoofing e replay;
• isolamento de credentials/profile;
• prompt, código e secrets ausentes de logs/handshake;
• Agent tentando acessar filesystem/processo fora do Runtime deve falhar.

Performance/reliability

• cold e warm até readiness/provider request/primeiro delta;
• overhead IPC p95;
• churn de sessões e soak de 24h;
• backpressure sem OOM;
• memória estabilizada por LRU/TTL;
• zero duplicação de efeitos sob reconnect/retry.

Critérios de aceite

• Simplicio Agent pode ser selecionado e usado dentro das quatro superfícies do Code.
• A integração reutiliza AgentHost; não copia o Agent nem incorpora Python ao binário Rust.
• Existe exatamente um coordenador ativo por turno.
• Runtime continua independente e acessível por outros coordenadores.
• Ausência do Simplicio Agent não bloqueia coordinator builtin/external compatível.
• Tool calls do Agent não bypassam o Runtime.
• Reconnect/cancel/restart não perde eventos nem duplica efeitos.
• AgentHost é compartilhado com isolamento correto por profile.
• Code, Agent, Runtime e Loop exibem identidades/receipts causais consistentes.
• E2E [P0][#16][Product E2E] Certificar jornada completa do usuário até delivery confirmado #43 passa com coordinator=simplicio-agent e com ao menos outro coordenador.
• Métricas provam ganho warm e overhead dentro do SLO publicado.
• Feature flag, kill switch e rollback são testados.

Não objetivos

• declarar o Simplicio Agent coordenador obrigatório;
• mover o diálogo para o Runtime;
• duplicar AgentHost ou SimplicioBridge no Code;
• permitir dois loops cognitivos executarem o mesmo turno;
• considerar UI conectada como prova de execução E2E.

Revisão complementar do projeto: simplicio-code

Responsabilidade avaliada: IDE/orquestração. Esta issue deve ser entendida no contexto da auditoria-mãe do repositório.

Objetivo específico

validar usuário → plano → Agent/Runtime → alteração → testes → PR

Fluxo de testes obrigatório

comando → plano → execução → diff → testes → cancelamento → retomada

1. Registrar SHA/branch, ambiente, dependências e configuração.
2. Executar o caminho feliz completo e capturar logs/receipts.
3. Injetar entrada inválida, timeout, falha externa ou permissão ausente aplicável.
4. Verificar retry, cancelamento, idempotência e rollback quando o fluxo suportar.
5. Executar testes unitários, integração, sistema/E2E, regressão, segurança e desempenho aplicáveis.
6. Reexecutar com os mesmos dados e comparar resultado/hashes.
7. Confirmar que falha nunca vira sucesso e que recursos são liberados.

Critérios de aceite adicionais

• O comportamento principal está demonstrado por teste executável.
• Pelo menos um caminho de falha está coberto e documentado.
• Contratos entre projetos são validados nas versões/SHAs declarados.
• Logs e receipts permitem reconstruir a decisão.
• Métricas não observáveis são null com motivo, nunca estimadas.
• Segredos, PII e dados privados não aparecem nos artefatos.
• O procedimento é reproduzível localmente ou em container sem GitHub Actions pago.
• PR/commit, logs, hashes e riscos residuais estão anexados antes de fechar.

Evidências obrigatórias

• PR/commit vinculado;
• comandos e versões;
• logs do caminho feliz e da falha;
• testes/coverage/benchmark aplicáveis;
• receipts, hashes e relatório de rollback;
• limitações e próximos passos.

Regra de encerramento

Não fechar sem todos os critérios desta issue e da auditoria-mãe atendidos. Se faltar implementação, marcar como NEEDS-IMPLEMENTATION ou BLOCKED, nunca como concluída.

[wesleysimplicio]

Atualização de auditoria (2026-07-17)

A auditoria local confirmou que o Code ainda não tem uma implementação completa de AgentHost/coordinator first-class compatível com todos os critérios desta issue. O Simplicio Agent expõe simplicio-agent mcp serve, simplicio_act e capabilities, mas ainda é necessário definir e implementar no Code o contrato estável de coordinator selection, exactly-one authority, causal envelopes, Runtime bridge, Loop hub, reconnection, persistence, cancellation, UI/flags e E2E da #43.

A execução do simplicio-loop plan foi iniciada com contrato .orchestrator/tasks/issue-50.md, mas o volume atingiu 100% e o Runtime não conseguiu gravar spill (No space left on device), rastreado em #52.

Issue permanece aberta; nenhum critério de aceite foi declarado concluído.

[wesleysimplicio]

O AgentHost opcional deve operar dentro do boundary de #55: Code é UX/cliente interativo, Loop é workflow, Runtime executa/gateia, Agent raciocina. Isso evita dois loops cognitivos, Runtime/map/processos duplicados. Parent: wesleysimplicio/simplicio-loop#555.

[wesleysimplicio]

Implementação parcial first-class entregue localmente:

• Novo módulo crates/codegen/xai-grok-agent/src/agent_host.rs.
• CoordinatorMode: builtin, simplicio_agent, external.
• AgentHostConfig com protocolo agent/v1, endpoint obrigatório nos modos externos, max_in_flight e reconnect.
• Handshake com capabilities, correlação de turnos, limite de capacidade, finish/cancel via status, reconnect por epoch e CoordinatorSnapshot serializável.
• AgentDefinition aceita agentHost no frontmatter JSON/YAML.
• Testes do crate: 555 passed, 0 failed.

Ainda pendente para fechar a issue:

• transport adapter MCP real para simplicio-agent;
• persistência/reconexão de sessão no gateway;
• selector/UI e E2E com capabilities/act;
• cancelamento remoto efetivo e evidência via Runtime/Loop.

[wesleysimplicio]

Evidência local após pull

Sequência executada antes da verificação:

git pull --ff-only
cargo fmt --all -- --check
cargo check -p xai-grok-shell --offline

Resultado: Already up to date, formatação válida e Finished dev profile com CHECK_EXIT:0.

#49

O caminho produtivo de filesystem e terminal agora usa o cliente Runtime, com rejeição explícita de fallback local. O manifest estrito também passa. O fechamento continua bloqueado porque background terminal, list/poll/log/kill, cancelamento e receipts ainda precisam de contrato Runtime ponta a ponta e testes de integração/E2E.

#50

O contrato first-class local foi implementado e o pacote xai-grok-agent passou 556 testes, incluindo validação de AgentHostConfig, capacidade concorrente e reconnect epoch. O shell também compila. O fechamento continua bloqueado porque ainda faltam transporte MCP/gateway real, persistência de sessão, streaming, cancel remoto e E2E Code ↔ Simplicio Agent.

Nenhuma issue foi fechada: estes resultados são evidência parcial local, não promoção remota nem prova de todos os critérios de aceite.

[wesleysimplicio]

Decisão arquitetural supersedente — Runtime + Agent obrigatórios e painel proativo

A decisão do owner em 2026-07-19 substitui, para o modo produtivo do Simplicio Code, as menções anteriores a “coordenador opcional”, coordinator=builtin independente e ao aceite “ausência do Agent não bloqueia”.

Grafo de dependências obrigatório

• simplicio-runtime é produto independente e nunca depende/importa simplicio-code;
• simplicio-agent é produto independente e nunca depende/importa simplicio-code;
• simplicio-code depende de versões/capabilities compatíveis de Runtime e Agent;
• diagnóstico/instalação pode abrir sem eles apenas para explicar e reparar; edição, tools e turnos produtivos falham fechados;
• Code integra Mapper, Dev CLI e Loop por adapters/contratos versionados; não copia componentes nem cria scheduler/efeitos paralelos.

Painel lateral do Agent

O Code deve exibir, ao lado do desenvolvimento, um painel anexado ao AgentHost neutro, com stream proativo versionado de attention|finding|risk|suggestion|plan|progress|receipt. Ele observa somente contexto autorizado do workspace/editor/diff/teste/terminal, com redaction, budgets, backpressure e cancelamento; mostra evidência/confiança/ação sugerida; não toma foco nem executa efeito silencioso. Toda leitura/execução/mutação produtiva atravessa o Runtime; DAG/fila/recursos pertencem ao Loop Hub; mapa/overlay pertencem ao Mapper.

O contrato do Agent deve permanecer genérico (workspace.observe/subscribe + advisory events), sem imports, tipos de UI ou dependência de build do Code, e consumível por outros clientes.

Aceite adicional/supersedente

• Runtime e Agent ausentes/incompatíveis deixam Code em modo diagnóstico, nunca em operação degradada silenciosa.
• Handshake obrigatório prova runtime/* e agent/v1 antes de turno produtivo.
• Agent é o único coordenador cognitivo produtivo; Code é UX/cliente.
• Runtime é o único boundary de efeitos.
• Agent e Runtime constroem/testam/publicam sem dependência do Code.
• Code consome ambos por clients/adapters com política N/N-1.
• Painel proativo renderiza finding→evidence→suggestion→receipt.
• Observação é consentida, redigida, bounded e cancelável.
• Advisory não executa efeito sem policy/approval/idempotency key.
• Product E2E prova Code→Agent→Runtime→Loop/Mapper→receipt e falhas negativas por componente ausente.

Esta decisão é vinculante para os próximos slices/PRs desta issue.