MaxHu-xuan/task-state-guard

何を解決するか

TaskStateGuard は、サービス再起動後に「スタックした」タスク状態を再同期する方法を提供します。AIエージェントランタイムやバックグラウンドワーカーでは、システムがクラッシュまたは再起動した際に、タスクが running や pending のまま残ることが多く、作業が実際に完了したかどうか、または結果がユーザーに届けられたかどうかが不明確になります。このツールは、明示的なデッドラインとグレース期間に基づき、古くなった状態を timed_out のような終端状態に収束させ、作業が成功したかどうかを推測することなく、状態を正しく管理します。

動作方法

埋め込み型SQLiteデータベースを使用して、タスクおよび配信状態の台帳を維持します。2つの独立した状態機械を採用しています：

• タスク状態：作業が queued、running、succeeded、failed、timed_out、または cancelled であるかを追跡します。
• 配信状態：結果が pending、delivered、failed、または not_applicable（内部タスク用）であるかを追跡します。

これらを分離することで、作業は成功したが結果の配信がまだ行われていないタスクを明確に区別できます。reconcile コマンドは、グレース期間を超えたタスクを終端状態に更新し、doctor コマンドはデータベーススキーマとイベントチェーンの健全性をチェックして、台帳の信頼性を確保します。

対象ユーザー

• 再起動後に状態を回復する必要があるAIエージェントやバックグラウンドワーカーサービスの開発者。
• ワークフローの可視性が必要で、診断台帳に機密なプロンプトやタスク本文を保存せずにタスクの結果を監査できる必要があるオペレーター。
• Linux、macOS、Windows 上でローカルワークフローを実行し、一貫した状態契約とローカルファイル保護を必要とするユーザー。

特徴

• 状態機械の分離：作業完了と結果配信を明確に区別。
• ドライランプレビュー：再同期を適用する前に変更の集計数を確認可能。
• プライバシー重視：プロンプト、メッセージ、タスク本文は保存せず、メタデータとオプションのフィンガープリントのみ保存。
• クロスプラットフォーム：Unix系システムではPOSIXファイル権限をサポートし、WindowsではDACL境界を認識。
• メモリ内スナップショット：小さなデータベースの場合、一貫性のある読み取りをメモリ内で行い、プレビュー中のロック問題を回避。