How saravanx41/undolog works
undolog protects agent tool side effects: wrapped calls are classified and recorded in a per-thread append-only ledger, then a freeze and previewable rollback can restore or compensate undoable actions and report what remains. Core is framework-independent; LangGraph is an optional integration. The repository also includes a web UI and a torture/chaos suite that exercises the safety behavior. Edges reflect README statements and indexed source references; unsampled web wiring and some implementation details are left unconnected rather than inferred.
Main entry points: ledger.py Thread ledger · __init__.py Mock services · demo.py Corruption demo · chaos.py Chaos runner
Components 28
Ledger engine
- Thread ledger
packages/core/src/undolog_core/ledger.py - Ledger models
packages/core/src/undolog_core/models.py - Freeze errors
packages/core/src/undolog_core/exceptions.py - Safety registry
packages/core/src/undolog_core/registry/__init__.py
Integrations
- Postgres adapter
packages/adapters/src/undolog_adapters/postgres_adapter.py - Stripe adapter
packages/adapters/src/undolog_adapters/stripe_adapter.py - LangGraph plugin
packages/langgraph/src/undolog_langgraph/adapter.py
Torture scenarios
- Corruption demo
packages/torture/src/undolog_torture/demo.py - Runaway agent
packages/torture/src/undolog_torture/agent.py - Chaos runner
packages/torture/src/undolog_torture/chaos.py - Invariant verifier
packages/torture/src/undolog_torture/verify.py - Fault injection
packages/torture/src/undolog_torture/faults.py - Rollback executors
packages/torture/src/undolog_torture/executors.py - World snapshots
packages/torture/src/undolog_torture/snapshot.py - Mock services
packages/torture/src/undolog_torture/world/__init__.py - CRM mock
packages/torture/src/undolog_torture/world/crm.py - Stripe mock
packages/torture/src/undolog_torture/world/stripe.py
Web interface
- Thread API
packages/web/src/app/api/threads/route.ts - Entries API
packages/web/src/app/api/threads/[threadId]/entries/route.ts - Preview API
packages/web/src/app/api/threads/[threadId]/preview/route.ts - Rollback API
packages/web/src/app/api/threads/[threadId]/rollback/route.ts - Thread view
packages/web/src/app/threads/[threadId]/page.tsx - Rollback panel
packages/web/src/components/RollbackPanel.tsx - Timeline row
packages/web/src/components/TimelineRow.tsx - Web data layer
packages/web/src/lib/db.ts
Other components
- Operator
- CLI
undolog/cli.py - PostgreSQL
Connections 29
- Operator → CLI: runs
undolog/cli.py - CLI → Corruption demo: starts demo
undolog/cli.py - CLI → Chaos runner: starts chaos
undolog/cli.py - Corruption demo → Thread ledger: wraps calls
packages/torture/src/undolog_torture/demo.py - Corruption demo → Mock services: uses services
packages/torture/src/undolog_torture/demo.py - Corruption demo → Rollback executors: executes rollback
packages/torture/src/undolog_torture/demo.py - Thread ledger → Ledger models: persists entries
packages/core/src/undolog_core/ledger.py - Thread ledger → Safety registry: classifies tools
packages/core/src/undolog_core/ledger.py - Thread ledger → Freeze errors: raises frozen error
packages/core/src/undolog_core/ledger.py - Thread ledger → PostgreSQL: reads and writes
README.md - Runaway agent → Thread ledger: wraps actions
packages/torture/src/undolog_torture/agent.py - Runaway agent → Mock services: acts on
packages/torture/src/undolog_torture/agent.py - Mock services → CRM mock: contains service
packages/torture/src/undolog_torture/world/__init__.py - Mock services → Stripe mock: contains service
packages/torture/src/undolog_torture/world/__init__.py - Chaos runner → Runaway agent: runs scenario
packages/torture/src/undolog_torture/chaos.py - Chaos runner → Fault injection: injects faults
packages/torture/src/undolog_torture/chaos.py - Chaos runner → Invariant verifier: checks results
packages/torture/src/undolog_torture/chaos.py - Invariant verifier → Thread ledger: checks ledger
packages/torture/src/undolog_torture/verify.py - Invariant verifier → World snapshots: compares state
packages/torture/src/undolog_torture/verify.py - World snapshots → Mock services: captures state
packages/torture/src/undolog_torture/snapshot.py - Rollback executors → Mock services: uses services
packages/torture/src/undolog_torture/executors.py - LangGraph plugin → Thread ledger: wraps tools
packages/langgraph/src/undolog_langgraph/adapter.py - Postgres adapter → Ledger models: captures proofs
packages/adapters/src/undolog_adapters/postgres_adapter.py - Stripe adapter → Ledger models: captures proofs
packages/adapters/src/undolog_adapters/stripe_adapter.py - Operator → Thread view: views thread
README.md - Operator → Thread API: uses web UI
README.md - Operator → Entries API: requests entries
- Operator → Preview API: requests preview
- Operator → Rollback API: requests rollback