zacmoltbot/openclaw-skill-long-task-control

장기 작업 제어 (Long Task Control)

이 버전의 핵심은 또 다른 모니터를 추가하는 것이 아니라, 아키텍처를 깔끔하게 분리하는 것입니다:

1. 관찰된 진실 (Observed Truth): 소유자 / 실행자 / 외부 관찰이 진실을 되채움
2. 파생된 상태 (Derived State): 스크립트가 진실로부터 결정론적 투영을 수행
3. 제어 동작 (Control Actions): 모니터 / 소유자 / 사용자 대상 전달이 파생된 상태에 따라 동작 수행

기본 규칙 (Root rule)

• 관찰된 진실이 없으면 OK를 판정하지 않음
• STEP_PROGRESS는 STEP_COMPLETED와 같지 않음
• TASK_COMPLETED는 완료 진실에 의해서만 구동됨
• 모니터는 모순된 필드로 '에이전트가 아직 작업 중 / 외부 대기 중'을 추측하지 않음

이벤트 모델 (Event model)

다음 이벤트를 사용하며, 더 이상 CHECKPOINT를 혼용하지 않음:

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

아키텍처 요약 (Architecture summary)

관찰된 진실 (Observed truth)

소유자 / 실행자 / 외부 관찰이 되채움:

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

파생된 상태 (Derived state)

task_ledger.py project_task() / monitor_nudge.py가 유도:

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

제어 동작 (Control actions)

• TRUTH_INCONSISTENT
• OWNER_RECONCILE
• NUDGE_MAIN_AGENT
• BLOCKED_ESCALATE
• STOP_AND_DELETE

모니터 우선순위 (Monitor precedence)

1. 터미널 → STOP_AND_DELETE
2. 진실 불일치 / 의심스러운 외부 주장 → TRUTH_INCONSISTENT 또는 OWNER_RECONCILE
3. 차단 확인됨 → 재시도 우선 확인 → BLOCKED_ESCALATE
4. 물질적 진행 델타 없음 / 하트비트 → NUDGE_MAIN_AGENT / STALE_PROGRESS / HEARTBEAT_DUE
5. 그 다음에만 OK

진행 기반 감독 계약 (Progress-based supervision contract)

• LTC는 벽시계 작업 TTL이 아닙니다. '20분이 지나면 작업을 중단'하는 것이 아닙니다.
• 모니터는 장시간 물질적 진행 델타가 없을 때만 개입합니다.
• 진행 델타는 다음에서 올 수 있습니다:
  • 새로운 STEP_PROGRESS / STEP_COMPLETED / TASK_COMPLETED
  • 새로운 아티팩트 / 다운로드 관찰
  • 외부/프로바이더 작업 상태 변경
  • 실행자 상태의 성공적인 하트비트 (예: executor_health.last_success_at)
• 장기 작업이 이러한 진행 신호를 계속 생성하는 한, 몇 시간이 걸리더라도 손절매 대상이 되어서는 안 됩니다.
• timeout_sec / nudge_after_sec는 이 버전에서 진행 유휴 임계값을 의미하며, 하드 킬 데드라인이 아닙니다.

소유자 재개 계약 (Owner-resume contract)

모니터가 sessions_send를 통해 소유자에게 요청하는 사항:

• 먼저 관찰
• 실제 데이터 보충
• 그런 다음 재개 / 완료 / 차단

반쯤 완성된 상태를 직접 작성하여 결정론적 투영과 충돌하지 않도록 합니다.

재시도 우선 계약 (Retry-first contract)

DOWNLOAD_TIMEOUT / DOWNLOAD_INCOMPLETE / TRANSIENT_NETWORK / EXECUTION_ERROR / EXTERNAL_WAIT 반드시 먼저 관찰된 진실에서 비롯되어야 하며, 그 후에야 모니터가 재시도 카운터를 사용하여 재시도 또는 에스컬레이션을 결정할 수 있습니다.

주요 명령어 (Primary commands)

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

참고 자료 (References)

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

이 버전이 존재하는 이유 (Why this version exists)

이전 버전은 결정론적 스크립트와 에이전트 판단을 혼합하여 다음과 같은 문제가 있었습니다:

• CHECKPOINT가 진행 / 완료를 동시에 나타냄
• 모니터가 불완전한 진실로 OK를 판정
• 외부 대기 주장이 증거 없이 받아들여짐
• 소유자 재개 후 작성된 상태가 스크립트 투영과 충돌

이 버전은 근본 원인을 분리하여 재작업했으며, 더 이상 이전의 혼합 모델을 패치하지 않습니다.