MaxHu-xuan/task-state-guard

Reconcile stuck AI-agent tasks after restarts and timeouts. Preview SQLite changes, close stale delivery states, and never guess success.

What it solves

TaskStateGuard provides a way to reconcile "stuck" task states after a service restart. In AI agent runtimes or background workers, tasks often remain marked as running or pending when the system crashes or restarts, leaving the operator unsure if the work actually completed or if the result was delivered to the user. This tool ensures that stale states are converged to a terminal state (like timed_out) based on explicit deadlines and grace periods, without guessing whether the work succeeded.

How it works

It uses an embedded SQLite database to maintain a ledger of task and delivery states. It employs two separate state machines:

  • Task State: Tracks if the work is queued, running, succeeded, failed, timed_out, or cancelled.
  • Delivery State: Tracks if the result was pending, delivered, failed, or not_applicable (for internal tasks).

By separating these, the system can distinguish between a task that finished successfully but whose result hasn't been delivered yet. The reconcile command identifies tasks that have exceeded their grace periods and updates them to terminal states, while the doctor command performs health checks on the database schema and event chains to ensure the ledger is trustworthy.

Who it’s for

  • Developers of AI agents and background worker services that need to recover state after restarts.
  • Operators who need workflow observability and a way to audit task outcomes without storing sensitive prompts or task bodies in the diagnostic ledger.
  • Users running local workflows on Linux, macOS, or Windows who require a consistent state contract and local file protection.

Highlights

  • Separated State Machines: Distinguishes between work completion and result delivery.
  • Dry-run Previews: Allows users to see aggregate counts of changes before applying reconciliation.
  • Privacy-focused: Does not store prompts, messages, or task bodies, only metadata and optional fingerprints.
  • Cross-platform: Supports POSIX file permissions on Unix-like systems and acknowledges DACL boundaries on Windows.
  • In-memory Snapshots: For small databases, it can perform consistent reads into memory to avoid locking issues during previews.

Related

  • Project
    nshiab/simple-data-analysis

    A high-performance TypeScript library for tabular, geospatial, and vector data analysis that integrates DuckDB and LLM capabilities for a complete data pipeline in JS/TS.

  • Project
    dais-polymtl/flock

    A DuckDB extension that integrates LLMs and RAG pipelines into SQL, enabling multimodal semantic analysis and analytics directly within the database.

  • Project
    facebookresearch/recipes

    A library of ready-to-run deep learning training recipes that provide production-ready baselines for common tasks to eliminate repetitive glue code.

  • Project
    lovstudio/Ataru

    A high-performance local memory retrieval system that indexes AI session transcripts from various agents to make historical conversations searchable via GUI, CLI, or API.