Documentation
¶
Overview ¶
Package checkpoint provides file-level undo for agent turns.
Before each write/edit tool modifies a file, Capture snapshots its current content. When the user runs /undo, the most recent checkpoint is popped and all files are restored to their pre-modification state.
Checkpoints are in-memory only (lost on process exit) and scoped to a session. A circular buffer keeps the most recent N checkpoints.
v1 limitation: only covers write/edit builtins. Changes via bash, MCP, extensions, or subagents are not tracked.
Index ¶
- type Checkpoint
- type Snapshot
- type Store
- func (s *Store) Begin(label string)
- func (s *Store) Capture(path string) error
- func (s *Store) Commit()
- func (s *Store) Discard()
- func (s *Store) List() []Summary
- func (s *Store) Repush(cp *Checkpoint)
- func (s *Store) Restore(cp *Checkpoint) error
- func (s *Store) Undo() (*Checkpoint, error)
- func (s *Store) UndoAndRestore() error
- type Summary
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Checkpoint ¶
type Checkpoint struct {
ID int
CreatedAt time.Time
Label string // e.g. first 60 chars of user message
Files []Snapshot // files modified in this turn
}
Checkpoint groups all snapshots from one agent turn.
type Snapshot ¶
type Snapshot struct {
Path string // absolute resolved path
Content []byte // original content; nil means file didn't exist (created by agent)
Perm fs.FileMode // original permissions
// contains filtered or unexported fields
}
Snapshot holds the pre-modification state of one file.
func (Snapshot) ModifiedSinceCapture ¶
ModifiedSinceCapture reports whether the file diverged from the state the agent left it in (recorded at Commit). A true result means an external edit happened after the agent's turn, so Undo must not overwrite it.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is an in-memory, thread-safe checkpoint store with a circular buffer.
func (*Store) Begin ¶
Begin opens a checkpoint for the current turn. Thread-safe. If a previous active checkpoint exists (stale from aborted run), it's discarded.
func (*Store) Capture ¶
Capture snapshots a file before modification. Thread-safe. No-op if already captured in this turn or if no active checkpoint. Returns error on I/O failure reading the file to snapshot.
func (*Store) Commit ¶
func (s *Store) Commit()
Commit closes the active checkpoint and adds it to the ring. No-op if no active checkpoint or if no files were captured.
func (*Store) Discard ¶
func (s *Store) Discard()
Discard closes the active checkpoint without saving.
func (*Store) Repush ¶
func (s *Store) Repush(cp *Checkpoint)
Repush puts a checkpoint back on the ring buffer after a failed undo. This allows the caller to retry /undo after fixing the restore failure.
func (*Store) Restore ¶
func (s *Store) Restore(cp *Checkpoint) error
Restore applies a checkpoint as one transaction. It first verifies that no file has changed since the agent's turn, then saves every current state. If any restore operation fails, every file already touched is rolled back. The checkpoint remains owned by the caller, which can Repush it for retry.
func (*Store) Undo ¶
func (s *Store) Undo() (*Checkpoint, error)
Undo pops the most recent checkpoint and returns it for the caller to restore. If restoration fails, call Repush to put it back for retry. Returns error if no checkpoints exist or if a turn is in progress.
func (*Store) UndoAndRestore ¶
UndoAndRestore performs the entire undo transaction under one operation lock. A new run cannot open/capture/commit a checkpoint between popping this checkpoint and either committing its restoration or putting it back.
Source Files