stop-guard 0.3.0

O stop-guard avalia a primeira tentativa de encerrar uma tarefa, sem exigir que o agente preencha uma ferramenta de parada.

O que muda nesta versão

A ferramenta stop_guard foi removida. O modelo não precisa acertar enums, fornecer evidências em campos obrigatórios, consultar um schema nem escrever outro resumo só para conseguir parar.

Ao terminar uma resposta:

1. Um supervisor separado avalia o pedido e o histórico disponível imediatamente, na primeira tentativa de encerrar.
2. Se o pedido já foi atendido, a sessão termina preservando a resposta existente. Não há outra chamada ao agente principal nem mensagem adicional de conclusão.
3. Se o agente já fez uma pergunta necessária, a sessão aguarda o usuário, sem repetir a pergunta.
4. Só uma pendência concreta do pedido original pode gerar outra chamada ao agente principal, acompanhada de uma orientação curta. Ofertas de trabalho opcional (“se quiser, posso atualizar…”) não são obrigações pendentes.
5. Falha/timeout/JSON inválido do supervisor encerra com diagnóstico. O agente principal nunca recebe uma tarefa de corrigir o schema interno.

O supervisor continua sendo um modelo: a qualidade da classificação depende dele. O código garante que o veredito finished não provoca outra resposta do agente; não garante que todo modelo sempre escolherá o veredito correto. Uma avaliação separada acrescenta uma chamada ao provider na primeira parada, mas não regenera o texto do agente.

Instalação e atualização

pi install npm:@lincolness/stop-guard
# Para instalações já existentes:
pi update --extensions

Depois execute /reload. Ao migrar de uma versão antiga, o novo prompt informa que a ferramenta de parada foi removida. Em sessões muito longas, referências antigas podem continuar no histórico. O guard não apaga as mensagens do usuário nem resultados de ferramentas. Se ainda usa o pacote sem scope, remova a instalação antiga com pi remove npm:stop-guard para não carregar as duas versões.

Requer Node >=22.15 e Pi @earendil-works/pi-coding-agent >=1.0.4 <2. O namespace antigo @mariozechner não é suportado. O pacote pi-fabric testado requer Node 24+.

Comandos

/stop-guard status
/stop-guard off
/stop-guard on
/stop-guard reset
/stop-guard limit 1
/stop-guard limit 0
/stop-guard owner auto

O limite numérico padrão é 12 retomadas, mas há um teto independente de duas avaliações do supervisor por entrada. limit 0 não remove esse teto. reset limpa os contadores e a orientação, sem iniciar uma tarefa sozinho. As opções são locais à sessão e reiniciam ao recarregar/navegar na árvore. Escape, erros do provider e mensagens pendentes são respeitados.

Supervisor, contexto e custo

O supervisor usa o mesmo modelo e as credenciais do Pi, via modelRegistry.streamSimple, em uma chamada isolada sem ferramentas. Não é um subprocesso de pi-subagents e não pode executar tarefas ou autorizar ações. Retorna somente um veredito estruturado interno: finished, needs_user, continue ou stuck.

Cada avaliação tem timeout de 20 segundos e até 1.024 tokens de saída. O snapshot inclui objetivo (até 5.000 caracteres), restrições (6.000), até seis observações recentes (2.400 cada) e a última orientação (600). Blocos de raciocínio e imagens não entram no snapshot. Truncamento pode perder informação: o supervisor é instruído a não inferir conclusão somente pela ausência de evidência.

O contexto do agente principal contém no máximo uma orientação ativa. A seguinte substitui a anterior; entradas antigas recebem context_edit e os filtros removem somente mensagens de controle do próprio guard. Decisões ficam em metadados stop-guard-review / stop-guard-supervisor. Diagnósticos de bloqueio são visíveis para o usuário e filtrados das chamadas seguintes. Conclusões e perguntas já feitas não geram mensagens visíveis adicionais.

Repetição da mesma chamada/resultados três vezes entre os últimos seis turnos também aciona o supervisor durante loops de ferramentas. IDs, tempo e raciocínio interno não contam como mudanças. Essa detecção é uma heurística, não uma prova de ausência de progresso.

As avaliações consomem tokens do provider e podem não aparecer no mesmo contador de uso da sessão principal. Com req-limit carregado, o supervisor compartilha o orçamento do provider; a espera pela vaga ocorre antes do timeout de avaliação.

Paralelismo e coexistência

O prompt continua orientando avaliar dependências e delegar tarefas independentes usando os schemas reais de subagent/Fabric. Não há mais formulário de avaliação de paralelismo para encerrar. Tarefas triviais ou dependentes podem continuar sequenciais.

Versões carregadas simultaneamente nos testes:

Com objetivo ativo no pi-goal-x, o guard cede o loop ao controlador existente. A detecção usa as ferramentas ativas get_goal e update_goal; a posse é mantida até a próxima entrada. /stop-guard owner guard força o controle pelo guard; use somente com o outro controlador desativado.

O guard preserva os prompts encadeados e não substitui runtimes, configurações ou ferramentas das outras extensões. Plugins que reescrevem o contexto depois dele e configurações de compactação diferentes exigem validação adicional.

Testes e limites da validação

npm ci
npm run check
npm test

23 testes no Pi 1.0.4 / Node 24.19. Incluem a regressão relatada: uma resposta já concluída com uma oferta opcional termina na primeira avaliação, sem repetir texto e sem ferramenta/schema de parada. O cenário é executado com as sete extensões, nas duas ordens de carregamento. Outro teste executa de fato fabric_exec antes da resposta, usando o runtime instalado do Fabric. Há testes de trabalho pendente, escrita real de arquivo via Pi, cancelamento, falha do supervisor, orçamento, timeout, perguntas e contexto.

A integração do req-limit tem um teste adicional com o loop real do Pi: uma resposta principal em 0s e uma avaliação do supervisor em 60s compartilham um limite de 1/min, com relógio controlado.

Os providers dos testes têm respostas programadas. Não houve sessão interativa com LLM real no provider do usuário. Esses testes verificam controle de fluxo e regressões, não a qualidade de decisão do supervisor em uso real. A interface do terminal também não foi validada visualmente.