Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Modo de laço e tarefas agendadas

Status: Ativo Escopo: estado atual Última revisão: 2026-08-27 Responsável: ax-code runtime

O AX Code tem três primitivas de automação que se combinam:

/loop — prompts recorrentes

/loop <interval> <prompt>   start (interval like 30s, 5m, 1h)
/loop status                show runs, busy-skips, and the prompt
/loop stop                  stop the loop

Exemplos:

/loop 5m check CI for new failures and fix any you find
/loop 30m drain the review queue

Regras:

• Limites do intervalo: 30 segundos a 24 horas. Um laço por sessão — iniciar um novo substitui o antigo.
• Um tique que dispara enquanto a sessão está ocupada é pulado e contado, nunca enfileirado — os laços não podem acumular turnos.
• Cada tique é um turno comum de prompt: permissões, perguntas, tetos autônomos e barreiras de conclusão valem todos. Com o modo autônomo desligado, um tique simplesmente para no primeiro prompt de permissão.
• Teto rígido de 500 execuções por laço; depois disso o laço para sozinho, com um aviso.
• Os laços vivem só no processo de backend: não sobrevivem a uma reinicialização. Para agendas duráveis, use as tarefas agendadas abaixo.

Combinar /goal com /loop

/goal é dono do objetivo (“todos os testes verdes, sem achados abertos de revisão”); /loop fornece o batimento que continua conferindo. Criar uma meta primeiro executa um escritor de plano dedicado, que guarda um contrato revisável em .ax-code/goals/ (ou no diretório de dados do AX quando o projeto não é uma worktree git). Se o planejamento falhar, a meta permanece pausada — /goal resume tenta de novo. Checagens de intervalo git que medem o diff desta meta usam o HEAD do momento do plano ({BASELINE}), não origin/main, a menos que o objetivo nomeie esse remoto. A conclusão da meta continua condicionada à verificação: o agente não pode marcar uma meta como concluída depois de edições sem uma execução de verificação que passe e, quando existe um plano, também precisa fornecer evidência para cada critério de aceitação.

/goal keep main green: fix any CI failure the loop finds
/loop 10m check CI status and act on failures

A garantia da meta é opcional

/goal <objective> começa na hora: não anexa um contrato congelado de aceitação, então a conclusão é julgada pelo plano de trabalho que o agente mantém (tarefas pendentes) mais uma verificação que passa depois da última alteração dele. /goal view (e “Ver detalhes da meta” no diálogo da meta) diz isso de forma explícita — “Sem contrato de garantia” — para que o estado nunca seja algo que você precise inferir.

/goal --assure <objective> executa primeiro o escritor de plano, que congela os critérios de aceitação, as referências de origem e as checagens executáveis; a conclusão então também exige um recibo atual e bem-sucedido de cada checagem exigida (verify_project com o id goalCheck). Use isso quando o “pronto” da meta precisar ser demonstrável, e não apenas descrito.

--assure se combina com as marcas de orçamento em qualquer ordem (/goal --assure --budget 500000 <objective>). /goal replace <objective> conserva a garantia quando a meta substituída tem um contrato válido, então substituir nunca pode enfraquecer em silêncio uma meta que já estava garantida.

Orçamentos e tetos da meta

Uma meta ativa eleva o teto de autocontinuação por execução (session.max_continuations) — a execução continua até a meta estar concluída, bloqueada, pausada ou limitada por orçamento. O que a limita, em vez disso:

• Orçamento de tokens (/goal --budget N …): quando se esgota, o agente ganha um turno de encerramento e depois a meta fica budget_limited.
• Orçamento de tempo (/goal --time-budget 30m …): um limite de relógio de parede em segundos, minutos (m) ou horas (h), combinável com o orçamento de tokens em qualquer ordem. Ele limita o trabalho decorrido que o orçamento de tokens não vê — tarefas remotas de treinamento, chamadas longas de ferramenta, paralisações do provedor. O mesmo turno de encerramento e a transição budget_limited valem quando ele dispara.
• Teto cumulativo de passos: execuções com meta ativa compartilham o limite de apoio Super-Long de max_steps × 40 passos no total (20,000 por padrão), em vez do teto autônomo comum de max_steps × (max_continuations + 1). Substitua com session.max_total_steps.
• A detecção de laço fatal, os tetos de raio de impacto e o disjuntor de turno só de ferramenta continuam valendo o tempo todo.

CLI de meta (headless)

O mesmo controle de meta está disponível fora da TUI, em ax-code goal:

• ax-code goal status [--json] — mostra a meta atual (-s/--session para escolher uma sessão; o padrão é a única meta retomável do projeto, e há erro quando a escolha seria ambígua).
• ax-code goal pause / ax-code goal clear — pausa ou limpa.
• ax-code goal resume — retoma a meta e a conduz em modo headless até ela assentar. Sem --attach, prepara o projeto no próprio processo; com --attach http://localhost:4111, conduz um servidor em execução. Os códigos de saída seguem o contrato headless da meta: 0 concluída, 3 bloqueada, 4 limitada por orçamento, 6 pausada ou não terminal, 1 erro de sessão, 124 tempo esgotado ocioso (--idle-timeout-ms, padrão de 10 minutos). Os eventos fluem para a stdout como JSONL (--event-log PATH também os registra), e uma linha final Goal <status>: <objective> vai para a stderr.

Quando uma execução de meta se aproxima do teto de passos, o agente recebe um aviso único de convergência, pedindo que verifique e conclua a meta ou deixe uma passagem limpa. Se o teto for atingido mesmo assim, a meta é pausada — não falha — e pode ser retomada com /goal resume (eleve session.max_total_steps antes, se precisar de mais folga).

Tarefas agendadas — duráveis e em conversa

Peça direto ao agente; ele usa as ferramentas schedule_task, list_scheduled_tasks e manage_scheduled_task:

• “Lembre-me às 14:30 de conferir a implantação.”
• “Todo dia útil às 9h, resuma as falhas novas de CI.”
• “Liste as minhas tarefas agendadas.” / “Pause a tarefa de resumo de CI.”

Mudanças de agenda criadas e administradas pelo agente pedem a permissão schedule. Uma execução somente leitura não pode alterar nem disparar uma agenda. Para criação headless sem supervisão, use o comando explícito ax-code schedule ou configure uma concessão explícita de permissão schedule para o agente; concessões curinga amplas não autorizam mudanças de agenda.

As mesmas tarefas podem ser administradas pelo shell, sem abrir a TUI:

ax-code schedule list                 # status, next run, schedule, id, title
ax-code schedule show <id>            # details plus the five most recent runs
ax-code schedule runs <id>            # run history: fired, failed, skipped and why
ax-code schedule pause|resume <id>
ax-code schedule delete <id>
ax-code schedule run <id>             # trigger now; requires a live runtime

pause/resume/delete passam pelo runtime gerenciado do projeto quando um está em execução (efeito imediato, atualizações ao vivo da TUI) e, caso contrário, gravam direto no banco do projeto. run precisa de um backend ao vivo — inicie um com ax-code runtime start — porque um processo de CLI de uma vez só não deve assumir trabalho que não consegue terminar. Todos os subcomandos de leitura aceitam --json.

As agendas aceitam execuções únicas, horários diários e semanais, e expressões cron de 5 campos, cada uma com um fuso IANA opcional. As tarefas persistem no banco do projeto e disparam enquanto um backend do AX Code para o projeto estiver em execução (varredura do agendador a cada 60s, reivindicação atômica — uma tarefa dispara uma vez mesmo com vários backends abertos). O avanço da agenda e a inserção na fila durável compartilham uma transação de banco, então uma falha não pode avançar uma ocorrência sem deixar trabalho para recuperar. Comandos de uma vez, como ax-code run e ax-code stats, não reivindicam tarefas vencidas. Inicie um backend persistente com ax-code runtime start para despachá-las.

Ocorrências perdidas usam catchUpPolicy: "run_once" por padrão: depois de uma parada, o AX Code junta qualquer acúmulo numa só execução. Use "skip" quando trabalho velho deva ser avançado sem executar. Uma tarefa também pode definir maxRunDurationMs de um segundo até 72 horas; uma execução que estoura o tempo é cancelada e registrada como falha.

Para operação entre reinícios de processo e de host, execute o backend sob um supervisor. Veja Operações de longa duração para exemplos de systemd, launchd e PM2, além da semântica exata de recuperação.

Execuções longas sem supervisão

Para sessões autônomas de várias horas, o modo Super-Long acrescenta prazos de execução (até 72h), ritmo de solicitações e ajuste de compactação. Ele se liga sozinho para modelos cujas capacidades declaradas aceitam trabalho longo de agente (modelos de raciocínio com contexto de 1M, como Qwen 3.7+ Max/Plus nas rotas da Alibaba e GLM 5.x nas rotas da z.ai) e pode ser forçado por sessão, por projeto ou por AX_CODE_SUPER_LONG. O engajamento da execução é registrado (super-long run engaged), e o ritmo do provedor só começa depois de uma janela de cortesia a partir do início da execução (padrão de 2 horas, super_long.pacing_grace_minutes), para que a fase produtiva inicial de uma execução agêntica conserve a vazão completa de chamadas de ferramenta; a cauda de maratona é ritmada conforme o nível declarado de limite de taxa do modelo.