zacmoltbot/openclaw-skill-long-task-control

Long Task Control

このバージョンのポイントは、モニターを追加することではなく、アーキテクチャをきれいに分離することです。

1. 観測事実 (Observed Truth)：owner / executor / 外部観測が真実を書き戻す
2. 導出状態 (Derived State)：スクリプトが観測事実から決定論的に射影する
3. 制御アクション (Control Actions)：モニター / owner / ユーザー向け配信が導出状態に基づいてアクションを実行する

ルートルール

• 観測事実がなければ、OK と判定しない
• STEP_PROGRESS は STEP_COMPLETED と等価ではない
• TASK_COMPLETED は完了の観測事実によってのみ駆動される
• モニターは矛盾するフィールドから「エージェントはまだ動作中 / 外部は保留中」と勝手に推測してはいけない

イベントモデル

以下のイベントを使用します。CHECKPOINT は混在させません。

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

アーキテクチャ概要

観測事実 (Observed Truth)

owner / executor / 外部観測によって書き戻されるもの：

• 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

モニター優先順位

1. 終端状態 → STOP_AND_DELETE
2. 観測事実の矛盾 / 疑わしい外部主張 → TRUTH_INCONSISTENT または OWNER_RECONCILE
3. ブロック確認 → リトライ優先チェック → BLOCKED_ESCALATE
4. 実質的な進捗デルタなし / ハートビートなし → NUDGE_MAIN_AGENT / STALE_PROGRESS / HEARTBEAT_DUE
5. その場合のみ OK

進捗ベースのスーパービジョン契約

• LTC は 壁時計ベースのタスクTTLではありません。「20分経ったらタスクを停止する」というものではありません。
• モニターは、長期間にわたって実質的な進捗デルタがない場合にのみ介入します。
• 進捗デルタは以下のソースから得られます：
  • 新しい STEP_PROGRESS / STEP_COMPLETED / TASK_COMPLETED
  • 新しいアーティファクト / ダウンロード観測
  • external/provider ジョブステータスの変化
  • executor の健全性を示す成功したハートビート（例：executor_health.last_success_at）
• 長時間タスクがこれらの進捗シグナルを継続的に生成している限り、たとえ数時間実行されていてもストップロスの対象とすべきではありません。
• timeout_sec / nudge_after_sec は、このバージョンでは 進捗アイドルしきい値 を意味し、ハードキル期限ではありません。

Owner 再開契約

モニターが sessions_send を使用して owner に依頼すること：

• まず観察する
• 真のデータを補完する
• その後に再開 / 完了 / ブロック処理を行う

半完成の状態を直接書き込んで、決定論的な射影と競合させてはいけません。

リトライファースト契約

DOWNLOAD_TIMEOUT / DOWNLOAD_INCOMPLETE / TRANSIENT_NETWORK / EXECUTION_ERROR / EXTERNAL_WAIT は、まず観測事実から得られる必要があります。その後、モニターはリトライカウンタを使用して、リトライするかエスカレーションするかを判断します。

主要コマンド

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/task-ledger-spec.md
• references/monitor-action-spec.md
• scripts/task_ledger.py
• scripts/monitor_nudge.py
• scripts/openclaw_ops.py

このバージョンが存在する理由

旧バージョンでは、決定論的スクリプトとエージェントの判断が混在していたため、以下の問題が発生していました：

• CHECKPOINT が進捗と完了の両方を同時に意味していた
• モニターが不完全な観測事実に基づいて OK と判定していた
• 外部保留主張に証拠がないにもかかわらず真に受けていた
• owner 再開後に書き込まれた状態とスクリプトの射影が競合していた

このバージョンでは、根本原因を分離して再構築しており、旧来の混線モデルにパッチを当てるのではなく、完全に作り直しています。