pi-tool-wal

Write-ahead log (WAL) for Pi tool calls.

Before a tool runs, the extension records the intent (tool name, input, timestamps). After execution, it reconciles the result and stores the final status in a local SQLite database for audit and crash recovery.

This is not a transactional undo log. It does not roll back filesystem side effects. Pair it with something like git checkpoints if you need restore.

Install

Requires Node.js ≥ 22.5 (uses built-in node:sqlite).

pi install npm:pi-tool-wal

Or from git:

pi install git:github.com/boyuruan/pi-tool-wal

Local checkout:

pi install /absolute/path/to/pi-tool-wal

Then restart pi or run /reload.

How it works

Hooks into Pi’s tool lifecycle — the model cannot skip them:

| Phase | Events | Action | |-------|--------|--------| | Before | tool_execution_start, tool_call | Insert/update pending intent | | After | tool_result, tool_execution_end | Complete as success / failed / partial / blocked | | Session | session_start / session_shutdown | Open DB, orphan stale pending ops |

LLM tool call
    → tool_execution_start   write pending
    → tool_call              refresh final input (write-ahead intent)
    → execute tool
    → tool_result            reconcile (primary)
    → tool_execution_end     complete if still pending (blocked / immediate errors)

Storage

Single SQLite file:

~/.pi/agent/tool-wal/wal.db

Logical scopes (narrow → wide):

| Scope | Key | Meaning | |-------|-----|---------| | session | session_id | One Pi conversation | | project | project_key | Stable project identity | | global | — | Entire database |

cwd is stored for display only; scoping uses project_key.

Stable project identity

Absolute paths differ across machines. Resolution order:

1. Explicit
   • env TOOL_WAL_PROJECT_ID
   • .pi/wal-project-id (cwd or git toplevel)
   • .pi/tool-wal.json → { "projectId": "..." }
2. Git — normalized origin remote + path relative to toplevel
   Examples: git:github.com/org/repo, git:github.com/org/repo#packages/api
3. cwd fallback — Pi-style path encoding (machine-local)

HTTPS/SSH remotes and credentialed URLs normalize to the same host/path.

Commands

| Command | Description | |---------|-------------| | /wal | This project summary + recent ops | | /wal status | Session + project + global counts | | /wal pending [scope] | Pending ops (session | project | global) | | /wal recent [n] [scope] | Recent ops (default: project) | | /wal session | Current session only | | /wal project | All sessions in this project | | /wal projects | List projects in the DB | | /wal global [n] | Cross-project recent | | /wal show <id\|callId> | Full record | | /wal orphaned [scope] | Orphaned ops | | /wal prune [days] [global] | Delete old completed rows (default: 30 days, this project) | | /wal path | DB path + current project identity | | /wal help | Command list |

Footer shows wal:N pending while the current session has in-flight ops.

Status values

| Status | Meaning | |--------|---------| | pending | Intent recorded, no completion yet | | success | Completed without error | | partial | Completed with truncated/partial output | | failed | Error or non-zero bash exit | | blocked | Blocked before execution (e.g. permission extension) | | orphaned | Left pending across crash/shutdown |

expected_ok flags whether completion matched the write-ahead intent (input hash, error state, etc.).

What is covered

• Pi tool calls (built-in and extension-registered tools)

Not covered by default:

• Interactive user bash (! / !!) — uses a different event path
• Side effects outside tools

Development

git clone https://github.com/boyuruan/pi-tool-wal.git
cd pi-tool-wal
npm test
pi install "$PWD"    # or: pi -e ./extensions/tool-wal

Package layout follows the Pi package conventions (pi key in package.json).

License

MIT