RaycarlLei/tool-journal

What it solves

It addresses the "lost response" problem in tool execution, where a tool successfully completes an external action (like an API call) but the system crashes before the response is recorded. This prevents the system from accidentally repeating the action (duplicate effects) or remaining in an uncertain state during recovery.

How it works

The library implements a durable execution journal using SQLite to record the intent to execute a tool before the action happens. It coordinates execution through leases and a retry admission window. If a crash occurs, the journal allows the system to either replay a previously recorded receipt or, if the downstream service is idempotent, safely retry the request using a stable idempotency key. It explicitly marks operations as indeterminate when they cannot be safely recovered automatically.

Who it’s for

Developers building AI agents or automated workflows that rely on external tools and require high reliability and crash-recovery guarantees to ensure actions are not duplicated.

Highlights

• Durable Execution: Uses SQLite for local persistence with no runtime dependencies.
• Crash Recovery: Specifically handles the gap between an external effect and the recording of its completion.
• Idempotency Coordination: Manages idempotency keys and retry windows to ensure safe retries.
• Framework Integration: Includes a reference integration with LangGraph to demonstrate recovery within a state graph.