Communitygithub.com

TokonoMix/agents-never-sleep

Governança autônoma de execução para agentes de codificação: execute um backlog de tickets até a conclusão sem supervisão. Contrato de autonomia ASK/PARK/HALT, máquina de estado durável por ticket, portões de teste determinísticos, reversibilidade via Git, watchdog de batimento cardíaco, relatório matinal. Apenas stdlib do Python.

O que é agents-never-sleep?

O TokonoMix/agents-never-sleep (ANS) é uma skill para agentes de codificação (como Claude Code, Codex, Cursor, Gemini, GitHub Copilot) que permite executar um backlog completo de tickets de forma autônoma, sem intervenção humana, eliminando o problema de paradas no meio da execução devido a perguntas não respondidas. Seu núcleo é um contrato de autonomia com três estados distintos: ASK (perguntar ao humano, proibido em modo não supervisionado), PARK (adiar uma decisão/ticket e continuar com o próximo) e HALT (parar toda a execução apenas em perigo irreversível). A skill fornece uma máquina de estado durável por ticket, com snapshots, reversão via Git, portões de teste determinísticos (nunca deletar um teste falho para ficar verde) e um watchdog de batimento cardíaco que bloqueia paradas prematuras. O agente atua como o trabalhador, executando um loop de 'próximo ticket' e 'completar ticket' fornecidos por um harness Python (stdlib puro), que gerencia agendamento, park, reversão, limites de tentativas e detecção de loops. Um launcher externo (`bin/ans-run`) executa verificações de pré-voo (confiança de configuração, identidade do usuário, saúde do repositório) antes de iniciar o agente, garantindo que tokens não sejam desperdiçados em execuções condenadas. A skill suporta modos de consenso tokonomix (conselho e especialistas) para revisão de alta qualidade, e integração com ferramentas como Git, Vault e Paperclip, tudo com foco em durabilidade de estado, semântica concreta de park-continuar e prevenção de inanição.

Funciona com✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI✓Windsurf
npx skills add TokonoMix/agents-never-sleep

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Agents Never Sleep (ANS)

Execute um backlog até a conclusão sem supervisão, sem que a execução pare em uma pergunta. A parte difícil não é fazer o trabalho — é durabilidade de estado + semântica concreta de park-vs-continuar + prevenção de inanição, então é nisso que esta skill é construída. A espinha dorsal de confiabilidade foi enviada primeiro (veja BUILD-PLAN.md); o funil de revisão multi-modelo mais pesado foi sequenciado sobre ela e agora está construído (status em "A maquinaria de qualidade em camadas sobre a espinha" abaixo).

Racional completo: agents-never-sleep-design.md (13 threads de design + 3 revisões do conselho). A espinha dorsal MVP é implementada como um pacote Python pequeno sob agents_never_sleep/ (o nome de importação antigo harness ainda funciona via um shim de compatibilidade retroativa em toda a versão 1.x) e comprovada por acceptance/run_acceptance.py (o único teste que mapeia para a dor de "parar no meio da execução").

O contrato de autonomia — três estados distintos, nunca colapsados

Uma execução tem exatamente três respostas para incerteza. Mantenha-as separadas; colapsá-las é como uma execução se inverte na própria paralisia que existe para evitar.

  • ASK — pergunte ao humano. Proibido enquanto não supervisionado. Não emita AskUserQuestion; não há ninguém para responder às 2 da manhã, e uma única pergunta desperdiça toda a execução. Isso é aplicado estruturalmente, não por disciplina: o hook PreToolUse deny_ask.sh (matcher AskUserQuestion, protegido por env CLAUDE_UNATTENDED=1) NEGA a ferramenta e o redireciona de volta para PARK/PROCEED — o espelho da garantia de nunca parar.
  • PARK — adie esta decisão ou ticket e mantenha a execução em movimento para o próximo ticket independente. Park é normal e saudável, não uma parada.
  • HALT — pare a execução inteira. Apenas em perigo genuinamente irreversível que a camada de hook bloquearia de qualquer forma, ou quando não há rede de segurança de reversibilidade (fs somente leitura, sem VCS e nenhum criável).

Quando não supervisionado, você só escolhe PROCEED, PARK ou HALT. Nunca ASK.

Decida PROCEED vs PARK pelo raio de explosão (então "incerto" é raro)

Torne a hierarquia concreta — chutar em um item de alto raio de explosão e estar confiantemente errado para toda a execução é o pior resultado, pior do que park.

Hard-PARK (nunca chute): esquema de banco de dados / direção de migração, contrato de API pública ou compartilhada, fronteira de segurança / auth / isolamento de inquilino, dinheiro / cobrança / preço, uma interface entre tickets sobre a qual outros constroem, e significado do requisito (você não sabe realmente o que construir) a menos que seja localmente reversível e isolado — então construa-o reversivelmente atrás de uma flag / mudança de rascunho E adie a decisão (híbrido).

Prosseguir (assuma + registre + continue): nomenclatura, estrutura interna, redação de log / comentário / erro, fixtures de teste, escolha entre duas implementações locais equivalentes, padrões trivialmente alternáveis.

Quando genuinamente não classificável → PARK. Um item pequeno erroneamente parkado custa uma decisão de 5 segundos depois; um grande erroneamente assumido custa uma execução de trabalho errado.

Comprometa cada suposição de PROCEED para que possa ser revertida; se o commit de snapshot não puder ser feito (git lock / timeout / object store somente leitura), trate o ticket como BLOCKED_ENV em vez de editar irreversivelmente. Cada PARK deve registrar: por que, as interpretações candidatas, a próxima ação exata do humano e seu escopo de contaminação.

O loop por ticket (o que o harness impõe)

  1. Pré-voo mede capacidades (agents_never_sleep/preflight.py) — VCS/reversibilidade, plataforma, portões, modo de execução, tokonomix/Vault/Paperclip. Capacidade ausente nunca para a execução; diminui o rendimento esperado e aumenta o conservadorismo. Sem VCS → estabeleça uma rede de segurança (git init / backup com timestamp) antes de qualquer edição arriscada; se impossível → apenas não destrutivo.
  2. Decida ASK/PARK/HALT para o ticket (acima). Não supervisionado: ASK→PARK.
  3. Implemente o ticket PROCEED — você, o agente, é o trabalhador: leia o ticket que o harness lhe entrega e edite arquivos. Você conduz este ticket um de cada vez através dos dois subcomandos abaixo; o harness é dono do agendamento, park, snapshot/reversão e do sentinela de nunca parar.
  4. Gateie deterministicamente (agents_never_sleep/gates.py) — a ESPINHA DORSAL. Classifique falhas: introduzidas-pela-diff → bloqueio duro (reverta para o último verde + park/falha); pré-existentes / instáveis / env → reduza confiança, continue ou park (nunca relate como "o ticket falhou"); timeout/env → BLOCKED_ENV. Cada gate executa com um timeout por etapa e um ambiente não interativo para que nunca possa travar em um prompt TTY. Nunca delete ou pule um teste falho para ficar verde — isso é um ponto cego bloqueante.
  5. Registre exatamente um resultado durável (agents_never_sleep/state.py): DONE, DONE_LOW_CONFIDENCE, PARKED_DECISION, PARKED_FOUNDATIONAL, BLOCKED_ENV, FAILED_RETRYABLE, FAILED_BUG_IN_AGENT — com os campos obrigatórios. Escritas atômicas; seguro para retomada.
  6. Próximo ticket. Tentativa + limite de loop (agents_never_sleep/ledger.py) força-park um ticket que excede seu limite de tentativas entre retomadas ou é comprovadamente em loop, para que a execução nunca seja queimada em um item amaldiçoado. Um disjuntor de baixo rendimento para e alerta se a maior parte do trabalho está parkado/bloqueado.

Executando — o agente É o trabalhador (conduza este loop)

Antes de começar de uma sessão interativa, pergunte ao usuário UMA VEZ, no chat: executar o backlog aqui nesta sessão (em primeiro plano — para se o terminal for fechado), ou lançar uma execução destacada via bin/ans-run que sobrevive ao logout? Esta é uma decisão de configuração/roteamento, não uma pergunta no meio da execução — não viola o contrato de nunca-ASK, e é a única pergunta que você faz.

Se o modo de consenso tokonomix estiver configurado (bloco council em cargas PROCEED, ou uma ferramenta MCP tokonomix_* disponível): no início da execução:

  • Não supervisionado (CLAUDE_UNATTENDED=1): emita UMA linha de log e prossiga imediatamente — nunca bloqueie ou pergunte: ℹ️ Consenso Tokonomix ativo — avaliando automaticamente cada chamada do conselho via tokonomix_rate_consensus.
  • Interativo (sem CLAUDE_UNATTENDED): se a conta ainda não tem preferência de avaliação salva (isto é, review_feedback_opt_in ainda não definido — detectável porque feedback_invite está ausente da primeira resposta de consenso), pergunte ao usuário UMA VEZ no chat:

    "O consenso Tokonomix está ativo. Após cada chamada do conselho, posso enviar automaticamente uma avaliação de utilidade (pontuação + descobertas) para melhorar as pontuações do modelo. Ativar isso? (sim/não)" Armazene a resposta em .unattended/state/consensus_rating_pref.json para que isso seja perguntado apenas uma vez entre sessões. Se sim: prossiga com avaliação automática. Se não: pule chamadas de avaliação inteiramente.

Se consensus_rating_endpoint_enabled retornar 404 na primeira tentativa de avaliação, registre uma vez como um ponto cego e pule todas as chamadas de avaliação subsequentes para esta execução.

O harness não pode chamá-lo de dentro de um loop Python, então você o conduz. Alterne estes dois subcomandos até que o backlog se esgote. Cada um imprime um objeto JSON no stdout.

# 1. Peça ao harness a próxima coisa a fazer. Ele automaticamente parka tickets ambíguos/de alto raio de explosão
#    e só entrega UM ticket pronto para implementar, ou um sinal terminal.
python3 -m agents_never_sleep.run next --repo <projeto> --tickets <diretório-de-.md-tickets>

Leia o JSON status:

  • PROCEED → implemente APENAS ticket.body editando arquivos no repositório (NÃO toque em outros tickets, NÃO pare, NÃO pergunte). Então chame complete:

    python3 -m agents_never_sleep.run complete --repo <projeto> --attempted "resumo de uma linha do que você fez"
    

    Use --cannot-implement (com --attempted explicando por que) se você genuinamente não puder fazer — o harne

    ss reverte suas edições parciais e registra BLOCKED_ENV. Depois de complete, chame next novamente.

    Se a carga PROCEED carregou um bloco council ou specialists, você executou revisões — você DEVE alimentar os resultados de volta em complete, ou o portão de confiança consultivo nunca dispara silenciosamente: ... complete --attempted "…" [--council-verdict pass|concerns|error --council-cost <€>] \ [--specialist-concerns architect,security,… --specialist-cost <€>] [--review-coverage "<quem executou>"]. Omita uma flag apenas quando você não executou tal revisão. (Detalhes: as seções Council e Specialist abaixo.)

  • PARK_CONSENSUS_ELIGIBLE → o ticket de outra forma PARKaria em significado de requisito ambíguo apenas (nunca uma categoria Hard-PARK). Execute o consenso tokonomix fundamentado que o prompt da carga pede (proponentes paralelos + cegos, um juiz disjunto) — nunca pergunte um texto livre "devo prosseguir?", essa é a estrutura perigosa que o prompt explicitamente proíbe. Então relate o veredito estruturado, ecoando de volta o attempt_id da carga de oferta:

    ... resolve-park --ticket-id <id> --attempt-id <attempt_id da carga de oferta> --resolved \
        --chosen-reading "<a leitura>" --evidence "<evidência exata citada>" --dissent-count <N> \
        --synthesis-text "<síntese do juiz>"
    

    ou --not-resolved se o consenso não pôde desambiguar com base na evidência citada. O portão determinístico do harness é o ÚNICO árbitro — um veredito resolvido roteia para o fluxo normal PROCEED (implemente, então complete como de costume); um veredito recusado parka o ticket com uma trilha de auditoria e segue em frente. Um resolve-park duplicado no mesmo ticket é sempre um no-op seguro (ALREADY_RESOLVED). (Detalhes: a seção F5 abaixo.)

  • DRAINED / HALTED / LOW_YIELD → a execução acabou; o relatório de execução foi escrito. Pare.

  • NON_DESTRUCTIVE → não supervisionado sem configuração salva; primeiro faça uma execução interativa de configuração.

Nunca invente seu próprio loop ou pare cedo. next é dono do sentinela .unattended/run-incomplete que o Stop-hook usa para bloquear uma parada prematura; continue chamando next até que retorne um status terminal. O harness gerencia snapshot-antes-de-editar, gate-depois-de-editar, reverter-no-vermelho, o limite de tentativas, detecção de loop e o disjuntor de baixo rendimento — seu único trabalho são as edições.

Contrato de caminho do sentinela (estrutural, aplicado). O Stop-hook verifica ${UE_RUN_INCOMPLETE:-$PWD/.unattended/run-incomplete} e o driver escreve o mesmo caminho. Eles concordam automaticamente apenas quando o agente executa a partir da raiz do repositório (então $PWD == --repo; use --repo .). Para uma execução não supervisionada onde CWD pode diferir de --repo (cron / claude-run), exporte UE_RUN_INCOMPLETE=<repo>/.unattended/run-incomplete no lançamento. Para evitar que nunca-parar quebre silenciosamente, next falha duro (status:"ERROR", exit 2) quando não supervisionado + CWD ≠ --repo + UE_RUN_INCOMPLETE não definido — corrija o lançamento (cd para o repositório, ou defina a env var).

A primeira execução interativa dispara um wizard mínimo por projeto (.claude/agents-never-sleep.json). A skill nunca se agenda — executar não supervisionado (cron / claude-run) é sempre o ato explícito do usuário, então o wizard sempre executa primeiro. Não supervisionado sem configuração → apenas não destrutivo

  • uma nota alta no relatório.

O demo de aceitação hermético (acceptance/run_acceptance.py) conduz o loop em processo com um DemoWorker determinístico apenas para auto-teste — não há subcomando run em processo. As execuções reais sempre usam o fluxo next/complete acima.

Lançando uma execução — bin/ans-run (pré-voo pré-token + trava da árvore de trabalho)

agents_never_sleep/preflight.py mede capacidades DEPOIS que a sessão do agente inicia — nesse ponto os primeiros tokens já foram gastos e uma execução condenada já custou dinheiro. Para lançamentos headless/cron, inicie através do launcher:

bin/ans-run [--repo <projeto>] [--agent <predefinição>] [--fg] [--check] [--trust] "<prompt>"

É um portão determinístico GO/NO-GO que executa ANTES do CLI do agente iniciar:

  • confiança de configuração (TOFU) — .claude/agents-never-sleep.json viaja com o repositório e descreve comandos que o launcher executa (argv do agente, verificações de host). Uma configuração nova ou alterada deve ser confiada uma vez por usuário — interativamente no prompt, ou explicitamente via ans-run --trust após revisão. Headless + não confiado = NO-GO. Confiança é registrada fora do repositório (~/.config/agents-never-sleep/trusted.json, chaveada pelo SHA-256 da configuração) — o repositório não pode garantir por si mesmo. Nunca execute ans-run em um repositório que você confia menos do que seu make install.
  • identidade — launcher.target_user configurável + guarda-raiz: iniciado como root com um usuário alvo configurado → re-executa como esse usuário; como root com nenhum configurado → NO-GO (uma execução não supervisionada nunca deve executar como root),
  • seleção de agente — predefinições nomeadas sob launcher.agents, escolhidas por --agent ou launcher.default_agent. Nenhuma detecção de plataforma acontece no momento do lançamento (marcadores de env de sessão são falsificáveis e desaparecem sob cron); o wizard é onde a detecção — como uma dica de preenchimento — e a decisão humana vivem. Três portões por predefinição: argv[0] deve ser um CLI de agente conhecido (claude/codex/gemini/copilot; substitua apenas via launcher.allow_custom_agent em uma configuração confiável), o binário deve passar uma sonda de capacidade --version de 5s (pega deriva de flag antes que tokens sejam gastos), e autonomy_confirmed deve ser verdadeiro (veja abaixo),
  • credenciais — launcher.credentials_paths é bloqueante quando configurado, apenas aviso quando não (keychain e configurações de chave API não têm arquivo de credenciais),
  • saúde do repositório — git utilizável (pega dubious-ownership), repositório gravável, espaço em disco (launcher.min_disk_mb), árvore suja/estagiada exibida como avisos,
  • verificações de host — sondas de serviços/DB vêm EXCLUSIVAMENTE de launcher.checks ([{"name", "command", "blocking"}]); nada específico do site está codificado no launcher.

Códigos de saída: 0 iniciado/GO · 64 NO-GO · 65 árvore de trabalho ocupada.

Flags de autonomia são uma decisão humana explícita — nunca um padrão

Uma execução destacada com o sistema de permissão do CLI totalmente ligado trava no primeiro prompt de aprovação (stdin está fechado, ninguém está assistindo); a flag que evita isso concede poder real. O mapa enviado (agents_never_sleep/agent_clis.py, fonte única para wizard + launcher) mantém ambas as variantes separadas e mostra o que a flag concede antes de pedir para confirmar — só então a predefinição registra autonomy_confirmed e se torna lançável.

Habilidades Relacionadas