MaxHu-xuan/task-state-guard

해결하는 문제

TaskStateGuard는 서비스 재시작 후 '정지된' 작업 상태를 재동기화할 수 있는 방법을 제공합니다. AI 에이전트 런타임이나 백그라운드 워커에서 시스템이 충돌하거나 재시작되면 작업이 여전히 running 또는 pending 상태로 남아 있어, 작업이 실제로 완료되었는지, 결과가 사용자에게 전달되었는지 여부를 운영자가 알 수 없습니다. 이 도구는 명시적인 마감일과 그레이스 기간을 기반으로 오래된 상태를 timed_out과 같은 종단 상태로 수렴시켜, 작업이 성공했는지 추측하지 않고 상태를 안정화합니다.

작동 방식

임베디드 SQLite 데이터베이스를 사용하여 작업 및 전달 상태의 장부를 유지합니다. 두 개의 별도 상태 기계를 사용합니다:

• 작업 상태: 작업이 queued, running, succeeded, failed, timed_out, 또는 cancelled인지 추적합니다.
• 전달 상태: 결과가 pending, delivered, failed, 또는 not_applicable (내부 작업용)인지 추적합니다.

이들을 분리함으로써, 작업은 성공했지만 결과가 아직 전달되지 않은 경우를 명확히 구분할 수 있습니다. reconcile 명령은 그레이스 기간을 초과한 작업을 종단 상태로 업데이트하고, doctor 명령은 데이터베이스 스키마와 이벤트 체인의 건강 상태를 점검하여 장부의 신뢰성을 보장합니다.

대상 사용자

• 재시작 후 상태를 복구해야 하는 AI 에이전트 및 백그라운드 워커 서비스 개발자.
• 작업 결과를 감사할 수 있고, 진단 장부에 민감한 프롬프트나 작업 본문을 저장하지 않아도 되는 워크플로우 가시성 필요 운영자.
• Linux, macOS, Windows에서 로컬 워크플로우를 실행하며 일관된 상태 계약과 로컬 파일 보호를 필요로 하는 사용자.

주요 특징

• 상태 기계 분리: 작업 완료와 결과 전달을 명확히 구분.
• 드라이런 미리보기: 재동기화를 적용하기 전에 변경 사항의 집계 수를 미리 확인 가능.
• 개인정보 중심: 프롬프트, 메시지, 작업 본문을 저장하지 않으며, 메타데이터와 선택적 지문만 저장.
• 크로스플랫폼: 유닉스 계열 시스템에서는 POSIX 파일 권한을 지원하고, Windows에서는 DACL 경계를 인식.
• 메모리 내 스냅샷: 작은 데이터베이스의 경우 일관된 읽기 작업을 메모리에 수행하여 미리보기 중 락 문제를 방지.