zacmoltbot/openclaw-skill-long-task-control

Controle de Tarefas Longas (Long Task Control)

Esta versão não se trata apenas de adicionar um monitor, mas de reestruturar a arquitetura de forma limpa:

1. Verdade Observada (Observed Truth): proprietário / executor / observação externa preenchem a verdade de volta
2. Estado Derivado (Derived State): o script projeta deterministicamente a partir da verdade
3. Ações de Controle (Control Actions): monitor / proprietário / entrega voltada ao usuário agem com base no estado derivado

Regra raiz

• Sem verdade observada, não declare OK
• STEP_PROGRESS não é igual a STEP_COMPLETED
• TASK_COMPLETED só pode ser acionado pela verdade de conclusão
• O monitor não pode usar campos contraditórios para supor "agente ainda está fazendo / pendente externo"

Modelo de eventos

Use estes eventos, sem misturar com CHECKPOINT:

• STARTED
• STEP_PROGRESS
• STEP_COMPLETED
• TASK_COMPLETED
• BLOCKED_CONFIRMED
• OWNER_RESUMED
• OWNER_REPLY_RECORDED
• EXTERNAL_OBSERVED
• DOWNLOAD_OBSERVED
• HEARTBEAT

Resumo da arquitetura

Verdade Observada (Observed Truth)

Preenchida pelo proprietário / executor / observação externa:

• observations[]
• observed.steps.*
• observed.task_completion
• observed.block
• observed.owner
• observed.external_jobs
• observed.downloads

Estado Derivado (Derived State)

Derivado por task_ledger.py project_task() / monitor_nudge.py:

• derived.workflow
• derived.current_step
• derived.step_states
• derived.pending_external
• derived.truth_state
• derived.inconsistencies

Ações de Controle (Control Actions)

• TRUTH_INCONSISTENT
• OWNER_RECONCILE
• NUDGE_MAIN_AGENT
• BLOCKED_ESCALATE
• STOP_AND_DELETE

Precedência do monitor

1. terminal → STOP_AND_DELETE
2. verdade inconsistente / alegação externa suspeita → TRUTH_INCONSISTENT ou OWNER_RECONCILE
3. bloqueio confirmado → verificação de nova tentativa primeiro → BLOCKED_ESCALATE
4. sem delta de progresso material / heartbeat → NUDGE_MAIN_AGENT / STALE_PROGRESS / HEARTBEAT_DUE
5. somente então OK

Contrato de supervisão baseado em progresso

• LTC não é um TTL de tarefa baseado em tempo de parede; não é "parar a tarefa após 20 minutos"
• O monitor só intervém quando não há delta de progresso substancial por um longo período
• O delta de progresso pode vir de:
  • Novo STEP_PROGRESS / STEP_COMPLETED / TASK_COMPLETED
  • Nova observação de artefato / download
  • Mudança no status do job externo/provedor
  • Heartbeat bem-sucedido da saúde do executor (ex.: executor_health.last_success_at)
• Enquanto a tarefa longa continuar gerando esses sinais de progresso, mesmo que por horas, não deve ser alvo de stop-loss
• timeout_sec / nudge_after_sec nesta versão têm o significado semântico de limiar de inatividade de progresso, não um prazo final de eliminação

Contrato de retomada pelo proprietário (Owner-resume)

O que o monitor pede ao proprietário via sessions_send:

• Primeiro observe
• Preencha os dados reais
• Depois retome / conclua / bloqueie

Não escreva estado semi-pronto diretamente para conflitar com a projeção determinística.

Contrato de nova tentativa (Retry-first)

DOWNLOAD_TIMEOUT / DOWNLOAD_INCOMPLETE / TRANSIENT_NETWORK / EXECUTION_ERROR / EXTERNAL_WAIT Devem vir primeiro da verdade observada; só então o monitor pode usar o contador de tentativas para decidir entre nova tentativa ou escalação.

Comandos principais

python3 scripts/task_ledger.py --ledger state/long-task-ledger.json init <task_id> ...
python3 scripts/task_ledger.py --ledger state/long-task-ledger.json checkpoint <task_id> --event-type STEP_PROGRESS ...
python3 scripts/task_ledger.py --ledger state/long-task-ledger.json checkpoint <task_id> --event-type STEP_COMPLETED ...
python3 scripts/task_ledger.py --ledger state/long-task-ledger.json checkpoint <task_id> --event-type TASK_COMPLETED ...
python3 scripts/task_ledger.py --ledger state/long-task-ledger.json block <task_id> ...
python3 scripts/task_ledger.py --ledger state/long-task-ledger.json external-job <task_id> ...
python3 scripts/task_ledger.py --ledger state/long-task-ledger.json download-observed <task_id> ...
python3 scripts/task_ledger.py --ledger state/long-task-ledger.json owner-reply <task_id> --reply <A|B|C|D|E> ...
python3 scripts/monitor_nudge.py --ledger state/long-task-ledger.json --apply-supervision

Referências

• references/task-ledger-spec.md
• references/monitor-action-spec.md
• scripts/task_ledger.py
• scripts/monitor_nudge.py
• scripts/openclaw_ops.py

Por que esta versão existe

Porque a versão antiga misturava script determinístico com julgamento do agente, resultando em:

• CHECKPOINT significando tanto progresso quanto conclusão
• O monitor usando meia verdade para declarar OK
• Alegações de pendência externa sem evidência sendo levadas a sério
• O estado escrito após retomada do proprietário conflitando com a projeção do script

Esta versão separa a causa raiz e refaz tudo, sem corrigir o modelo antigo e confuso.