feat(tools): checkpoint files before mutating write and edit
The built-in workspace write and edit tools replaced file content with
no recoverable pre-state. Each now snapshots its target immediately
before the write and refuses the mutation when the snapshot cannot be
taken, so a checkpoint is never silently skipped.
Checkpoints land in .git/archie-checkpoints inside the workspace, the
same per-task state directory that already holds the task brief and the
prepared sentinel: nothing under .git can be swept onto the task branch
by go-git's Add{All:true}. A checkpoint records either the file's bytes
or its absence, so creating a file restores by removing it;
RestoreLatest returns the most recent pre-state for a path.
Shell, Go-script, MCP and plugin tools are deliberately not covered:
the set of files they can touch is not enumerable from the call.
This commit is contained in:
1 parent
721968eeff
commit
e10d862f6a
4 files changed
+429
-6
No files matched your search
@@ -0,0 +1,199 @@
|
||||
// Not lifted from tau: archie-original. It gives the lifted write and edit
|
||||
// tools something tau never had -- a pre-mutation checkpoint -- and stores it
|
||||
// in the per-workspace state directory those tools already run against.
|
||||
package builtin
|
||||
|
||||
import (
|
||||
"crypto/sha256"
|
||||
"encoding/hex"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"sort"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// checkpointDir is the workspace-relative directory a task's pre-mutation
|
||||
// file checkpoints live under. It sits inside .git for the same reason the
|
||||
// task brief (container.WriteTaskJSON) and the prepared sentinel
|
||||
// (worktree.preparedSentinel) do: the workspace is a git worktree the agent
|
||||
// commits from, and go-git's Add{All:true} honours neither .gitignore nor
|
||||
// .git/info/exclude, so anything outside .git can be swept onto the task
|
||||
// branch. Nothing under .git can ever be tracked.
|
||||
const checkpointDir = ".git/archie-checkpoints"
|
||||
|
||||
// Checkpoint is a file's pre-mutation state: its bytes, or the fact that it
|
||||
// did not exist.
|
||||
type Checkpoint struct {
|
||||
// ID identifies this checkpoint and names its file on disk.
|
||||
ID string `json:"id"`
|
||||
// Path is the absolute path the snapshot was taken from.
|
||||
Path string `json:"path"`
|
||||
// Existed reports whether the file was present. False means restore
|
||||
// removes Path.
|
||||
Existed bool `json:"existed"`
|
||||
// Mode is the file's permission bits when it existed.
|
||||
Mode os.FileMode `json:"mode"`
|
||||
// Content is the file's bytes when it existed.
|
||||
Content []byte `json:"content,omitempty"`
|
||||
// CreatedAt orders checkpoints for RestoreLatest.
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
}
|
||||
|
||||
// CheckpointStore keeps pre-mutation file checkpoints for one workspace. It
|
||||
// is written by the mutating built-in tools (write, edit) and read by a
|
||||
// rollback caller; it is not itself a tool.
|
||||
type CheckpointStore struct {
|
||||
root string
|
||||
now func() time.Time
|
||||
}
|
||||
|
||||
// NewCheckpointStore returns the store rooted at workspace's per-workspace
|
||||
// state directory. workspace is the same directory the file tools are rooted
|
||||
// at, so the store travels with the workspace it protects.
|
||||
func NewCheckpointStore(workspace string) *CheckpointStore {
|
||||
return &CheckpointStore{
|
||||
root: filepath.Join(workspace, filepath.FromSlash(checkpointDir)),
|
||||
now: time.Now,
|
||||
}
|
||||
}
|
||||
|
||||
// Snapshot records path's current state and returns the checkpoint. It must
|
||||
// be called before the mutation it guards: an error means the mutation must
|
||||
// not proceed, because the pre-mutation state could not be preserved.
|
||||
//
|
||||
// A missing file is a valid snapshot (Existed=false) so that creating a file
|
||||
// is restorable too. Non-regular files are refused: a checkpoint can restore
|
||||
// bytes, not a socket, device or directory.
|
||||
func (s *CheckpointStore) Snapshot(path string) (Checkpoint, error) {
|
||||
abs, err := filepath.Abs(path)
|
||||
if err != nil {
|
||||
return Checkpoint{}, fmt.Errorf("checkpoint %s: resolve path: %w", path, err)
|
||||
}
|
||||
|
||||
cp := Checkpoint{Path: abs, CreatedAt: s.now()}
|
||||
|
||||
info, err := os.Stat(abs)
|
||||
switch {
|
||||
case errors.Is(err, os.ErrNotExist):
|
||||
// New file: the checkpoint records absence so restore removes it.
|
||||
case err != nil:
|
||||
return Checkpoint{}, fmt.Errorf("checkpoint %s: stat: %w", abs, err)
|
||||
case info.IsDir() || !info.Mode().IsRegular():
|
||||
return Checkpoint{}, fmt.Errorf("checkpoint %s: refusing to checkpoint non-regular file (%s)", abs, info.Mode())
|
||||
default:
|
||||
content, readErr := os.ReadFile(abs)
|
||||
if readErr != nil {
|
||||
return Checkpoint{}, fmt.Errorf("checkpoint %s: read: %w", abs, readErr)
|
||||
}
|
||||
cp.Existed = true
|
||||
cp.Mode = info.Mode().Perm()
|
||||
cp.Content = content
|
||||
}
|
||||
|
||||
sum := sha256.Sum256(append([]byte(abs+"\x00"), cp.Content...))
|
||||
cp.ID = fmt.Sprintf("%019d-%s", cp.CreatedAt.UnixNano(), hex.EncodeToString(sum[:6]))
|
||||
|
||||
if err := s.write(cp); err != nil {
|
||||
return Checkpoint{}, err
|
||||
}
|
||||
return cp, nil
|
||||
}
|
||||
|
||||
// write persists one checkpoint atomically.
|
||||
func (s *CheckpointStore) write(cp Checkpoint) error {
|
||||
if err := os.MkdirAll(s.root, 0o700); err != nil {
|
||||
return fmt.Errorf("checkpoint %s: create store %s: %w", cp.Path, s.root, err)
|
||||
}
|
||||
data, err := json.Marshal(cp)
|
||||
if err != nil {
|
||||
return fmt.Errorf("checkpoint %s: encode: %w", cp.Path, err)
|
||||
}
|
||||
if err := writeFileAtomic(filepath.Join(s.root, cp.ID+".json"), data, 0o600); err != nil {
|
||||
return fmt.Errorf("checkpoint %s: persist: %w", cp.Path, err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// RestoreLatest puts path back to its most recently taken checkpoint and
|
||||
// returns that checkpoint. A path with no checkpoint is an error, never a
|
||||
// silent no-op: a rollback that quietly does nothing is worse than one that
|
||||
// says it could not.
|
||||
func (s *CheckpointStore) RestoreLatest(path string) (Checkpoint, error) {
|
||||
abs, err := filepath.Abs(path)
|
||||
if err != nil {
|
||||
return Checkpoint{}, fmt.Errorf("restore %s: resolve path: %w", path, err)
|
||||
}
|
||||
cp, ok, err := s.latest(abs)
|
||||
if err != nil {
|
||||
return Checkpoint{}, err
|
||||
}
|
||||
if !ok {
|
||||
return Checkpoint{}, fmt.Errorf("restore %s: no checkpoint recorded", abs)
|
||||
}
|
||||
if err := s.restore(cp); err != nil {
|
||||
return Checkpoint{}, err
|
||||
}
|
||||
return cp, nil
|
||||
}
|
||||
|
||||
// latest returns the newest checkpoint recorded for abs.
|
||||
func (s *CheckpointStore) latest(abs string) (Checkpoint, bool, error) {
|
||||
entries, err := os.ReadDir(s.root)
|
||||
if errors.Is(err, os.ErrNotExist) {
|
||||
return Checkpoint{}, false, nil
|
||||
}
|
||||
if err != nil {
|
||||
return Checkpoint{}, false, fmt.Errorf("restore %s: read store: %w", abs, err)
|
||||
}
|
||||
|
||||
var matches []Checkpoint
|
||||
for _, entry := range entries {
|
||||
if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".json") {
|
||||
continue
|
||||
}
|
||||
data, readErr := os.ReadFile(filepath.Join(s.root, entry.Name()))
|
||||
if readErr != nil {
|
||||
return Checkpoint{}, false, fmt.Errorf("restore %s: read checkpoint %s: %w", abs, entry.Name(), readErr)
|
||||
}
|
||||
var cp Checkpoint
|
||||
if jsonErr := json.Unmarshal(data, &cp); jsonErr != nil {
|
||||
return Checkpoint{}, false, fmt.Errorf("restore %s: decode checkpoint %s: %w", abs, entry.Name(), jsonErr)
|
||||
}
|
||||
if cp.Path == abs {
|
||||
matches = append(matches, cp)
|
||||
}
|
||||
}
|
||||
if len(matches) == 0 {
|
||||
return Checkpoint{}, false, nil
|
||||
}
|
||||
|
||||
sort.Slice(matches, func(i, j int) bool {
|
||||
if matches[i].CreatedAt.Equal(matches[j].CreatedAt) {
|
||||
return matches[i].ID > matches[j].ID
|
||||
}
|
||||
return matches[i].CreatedAt.After(matches[j].CreatedAt)
|
||||
})
|
||||
return matches[0], true, nil
|
||||
}
|
||||
|
||||
// restore writes a checkpoint's state back to its path.
|
||||
func (s *CheckpointStore) restore(cp Checkpoint) error {
|
||||
if !cp.Existed {
|
||||
if err := os.Remove(cp.Path); err != nil && !errors.Is(err, os.ErrNotExist) {
|
||||
return fmt.Errorf("restore %s: remove: %w", cp.Path, err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
mode := cp.Mode
|
||||
if mode == 0 {
|
||||
mode = 0o644
|
||||
}
|
||||
if err := writeFileAtomic(cp.Path, cp.Content, mode); err != nil {
|
||||
return fmt.Errorf("restore %s: write: %w", cp.Path, err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
@@ -0,0 +1,209 @@
|
||||
package builtin
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// A write takes a checkpoint of the file it is about to replace, and that
|
||||
// checkpoint puts the original bytes back.
|
||||
func TestWriteTool_CheckpointRestoresOriginal(t *testing.T) {
|
||||
tmp := t.TempDir()
|
||||
path := filepath.Join(tmp, "f.txt")
|
||||
original := "original\n"
|
||||
if err := os.WriteFile(path, []byte(original), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
tool := NewWriteTool(tmp, NewMutationQueue(), nil)
|
||||
res, err := tool.Execute(context.Background(), json.RawMessage(
|
||||
`{"path":"f.txt","content":"changed\n","overwrite":true}`,
|
||||
), nil)
|
||||
if err != nil {
|
||||
t.Fatalf("execute: %v", err)
|
||||
}
|
||||
if res.IsError {
|
||||
t.Fatalf("write failed: %s", res.Content)
|
||||
}
|
||||
|
||||
store := NewCheckpointStore(tmp)
|
||||
if _, err := store.RestoreLatest(path); err != nil {
|
||||
t.Fatalf("RestoreLatest: %v", err)
|
||||
}
|
||||
got, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if string(got) != original {
|
||||
t.Fatalf("restored content = %q, want %q", got, original)
|
||||
}
|
||||
}
|
||||
|
||||
// A checkpoint taken before creating a file restores by removing it: the
|
||||
// recorded pre-state is "did not exist".
|
||||
func TestWriteTool_CheckpointOfNewFileRestoresAbsence(t *testing.T) {
|
||||
tmp := t.TempDir()
|
||||
path := filepath.Join(tmp, "created.txt")
|
||||
|
||||
tool := NewWriteTool(tmp, NewMutationQueue(), nil)
|
||||
res, err := tool.Execute(context.Background(), json.RawMessage(
|
||||
`{"path":"created.txt","content":"new\n"}`,
|
||||
), nil)
|
||||
if err != nil {
|
||||
t.Fatalf("execute: %v", err)
|
||||
}
|
||||
if res.IsError {
|
||||
t.Fatalf("write failed: %s", res.Content)
|
||||
}
|
||||
|
||||
store := NewCheckpointStore(tmp)
|
||||
if _, err := store.RestoreLatest(path); err != nil {
|
||||
t.Fatalf("RestoreLatest: %v", err)
|
||||
}
|
||||
if _, statErr := os.Stat(path); !os.IsNotExist(statErr) {
|
||||
t.Fatalf("expected restore to remove the created file, stat err = %v", statErr)
|
||||
}
|
||||
}
|
||||
|
||||
// Edit is a mutating tool too, and its checkpoint restores the original.
|
||||
func TestEditTool_CheckpointRestoresOriginal(t *testing.T) {
|
||||
tmp := t.TempDir()
|
||||
path := filepath.Join(tmp, "f.txt")
|
||||
original := "one\ntwo\nthree\n"
|
||||
if err := os.WriteFile(path, []byte(original), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
tool := NewEditTool(tmp, NewMutationQueue(), nil)
|
||||
res, err := tool.Execute(context.Background(), json.RawMessage(
|
||||
`{"path":"f.txt","edits":[{"old_text":"two","new_text":"TWO"}]}`,
|
||||
), nil)
|
||||
if err != nil {
|
||||
t.Fatalf("execute: %v", err)
|
||||
}
|
||||
if res.IsError {
|
||||
t.Fatalf("edit failed: %s", res.Content)
|
||||
}
|
||||
|
||||
store := NewCheckpointStore(tmp)
|
||||
if _, err := store.RestoreLatest(path); err != nil {
|
||||
t.Fatalf("RestoreLatest: %v", err)
|
||||
}
|
||||
got, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if string(got) != original {
|
||||
t.Fatalf("restored content = %q, want %q", got, original)
|
||||
}
|
||||
}
|
||||
|
||||
// Two mutations in a row leave two checkpoints; restore returns the most
|
||||
// recent pre-state, not the oldest.
|
||||
func TestWriteTool_CheckpointRestoresMostRecentState(t *testing.T) {
|
||||
tmp := t.TempDir()
|
||||
path := filepath.Join(tmp, "f.txt")
|
||||
if err := os.WriteFile(path, []byte("v1\n"), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
tool := NewWriteTool(tmp, NewMutationQueue(), nil)
|
||||
for _, content := range []string{"v2", "v3"} {
|
||||
res, err := tool.Execute(context.Background(), json.RawMessage(
|
||||
`{"path":"f.txt","content":"`+content+`\n","overwrite":true}`,
|
||||
), nil)
|
||||
if err != nil {
|
||||
t.Fatalf("execute: %v", err)
|
||||
}
|
||||
if res.IsError {
|
||||
t.Fatalf("write failed: %s", res.Content)
|
||||
}
|
||||
}
|
||||
|
||||
store := NewCheckpointStore(tmp)
|
||||
if _, err := store.RestoreLatest(path); err != nil {
|
||||
t.Fatalf("RestoreLatest: %v", err)
|
||||
}
|
||||
got, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if string(got) != "v2\n" {
|
||||
t.Fatalf("restored content = %q, want %q", got, "v2\n")
|
||||
}
|
||||
}
|
||||
|
||||
// A mutation whose checkpoint cannot be taken must not happen. Blocking the
|
||||
// store (.git/archie-checkpoints is a regular file) must leave the file
|
||||
// untouched and the tool reporting an error, never a silent write.
|
||||
func TestWriteTool_RefusesMutationWhenCheckpointFails(t *testing.T) {
|
||||
tmp := t.TempDir()
|
||||
path := filepath.Join(tmp, "f.txt")
|
||||
original := "original\n"
|
||||
if err := os.WriteFile(path, []byte(original), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
blockCheckpointStore(t, tmp)
|
||||
|
||||
tool := NewWriteTool(tmp, NewMutationQueue(), nil)
|
||||
res, err := tool.Execute(context.Background(), json.RawMessage(
|
||||
`{"path":"f.txt","content":"changed\n","overwrite":true}`,
|
||||
), nil)
|
||||
if err != nil {
|
||||
t.Fatalf("execute: %v", err)
|
||||
}
|
||||
if !res.IsError {
|
||||
t.Fatalf("expected the write to be refused without a checkpoint, got: %#v", res)
|
||||
}
|
||||
got, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if string(got) != original {
|
||||
t.Fatalf("file was mutated without a checkpoint: %q", got)
|
||||
}
|
||||
}
|
||||
|
||||
// Same fail-closed rule for edit.
|
||||
func TestEditTool_RefusesMutationWhenCheckpointFails(t *testing.T) {
|
||||
tmp := t.TempDir()
|
||||
path := filepath.Join(tmp, "f.txt")
|
||||
original := "one\ntwo\n"
|
||||
if err := os.WriteFile(path, []byte(original), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
blockCheckpointStore(t, tmp)
|
||||
|
||||
tool := NewEditTool(tmp, NewMutationQueue(), nil)
|
||||
res, err := tool.Execute(context.Background(), json.RawMessage(
|
||||
`{"path":"f.txt","edits":[{"old_text":"two","new_text":"TWO"}]}`,
|
||||
), nil)
|
||||
if err != nil {
|
||||
t.Fatalf("execute: %v", err)
|
||||
}
|
||||
if !res.IsError {
|
||||
t.Fatalf("expected the edit to be refused without a checkpoint, got: %#v", res)
|
||||
}
|
||||
got, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if string(got) != original {
|
||||
t.Fatalf("file was mutated without a checkpoint: %q", got)
|
||||
}
|
||||
}
|
||||
|
||||
// blockCheckpointStore makes the checkpoint store's parent a regular file so
|
||||
// MkdirAll of the store directory cannot succeed.
|
||||
func blockCheckpointStore(t *testing.T, workspace string) {
|
||||
t.Helper()
|
||||
if err := os.MkdirAll(filepath.Join(workspace, ".git"), 0o700); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := os.WriteFile(filepath.Join(workspace, ".git", "archie-checkpoints"), []byte("blocked"), 0o600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
@@ -75,7 +75,7 @@ func NewEditTool(cwd string, mq *MutationQueue, rt *ReadTracker) Tool {
|
||||
Schema: editSchema,
|
||||
Source: "builtin",
|
||||
Emoji: "✏️",
|
||||
Execute: makeEditExecutor(cwd, mq, rt),
|
||||
Execute: makeEditExecutor(cwd, mq, rt, NewCheckpointStore(cwd)),
|
||||
}
|
||||
}
|
||||
|
||||
@@ -121,7 +121,7 @@ func parseEditParams(params json.RawMessage) (EditParams, error) {
|
||||
return p, nil
|
||||
}
|
||||
|
||||
func makeEditExecutor(cwd string, mq *MutationQueue, rt *ReadTracker) Executor {
|
||||
func makeEditExecutor(cwd string, mq *MutationQueue, rt *ReadTracker, cp *CheckpointStore) Executor {
|
||||
return func(ctx context.Context, params json.RawMessage, _ UIBridge) (Result, error) {
|
||||
p, err := parseEditParams(params)
|
||||
if err != nil {
|
||||
@@ -150,7 +150,7 @@ func makeEditExecutor(cwd string, mq *MutationQueue, rt *ReadTracker) Executor {
|
||||
|
||||
var result Result
|
||||
err = runWithContext(editCtx, func() error {
|
||||
result = performEdit(path, p, mq)
|
||||
result = performEdit(path, p, mq, cp)
|
||||
return nil
|
||||
})
|
||||
if err != nil {
|
||||
@@ -167,7 +167,7 @@ func makeEditExecutor(cwd string, mq *MutationQueue, rt *ReadTracker) Executor {
|
||||
// performEdit loads, mutates, and writes path according to the edits in p.
|
||||
// Every failure is returned as a Result with IsError set, never a non-nil
|
||||
// error, so the executor keeps a single error envelope.
|
||||
func performEdit(path string, p EditParams, mq *MutationQueue) Result {
|
||||
func performEdit(path string, p EditParams, mq *MutationQueue, cp *CheckpointStore) Result {
|
||||
// Check file size before reading to avoid OOM on large files.
|
||||
info, err := os.Stat(path)
|
||||
if err != nil {
|
||||
@@ -217,6 +217,13 @@ func performEdit(path string, p EditParams, mq *MutationQueue) Result {
|
||||
newContent = strings.ReplaceAll(newContent, "\n", "\r\n")
|
||||
}
|
||||
|
||||
// Snapshot immediately before the write. applyEdits has already run, so
|
||||
// a rejected edit leaves no checkpoint behind, and the mutation lock is
|
||||
// held, so nothing can change the file between here and the write.
|
||||
if _, err := cp.Snapshot(path); err != nil {
|
||||
return Result{Content: fmt.Sprintf("refusing to edit %s: %v", path, err), IsError: true, ErrorKind: "checkpoint_failed"}
|
||||
}
|
||||
|
||||
if err := writeFileAtomic(path, []byte(bom+newContent), 0o644); err != nil {
|
||||
return Result{Content: fmt.Sprintf("error writing file: %v", err), IsError: true}
|
||||
}
|
||||
|
||||
@@ -54,11 +54,11 @@ func NewWriteTool(cwd string, mq *MutationQueue, rt *ReadTracker) Tool {
|
||||
Schema: writeSchema,
|
||||
Source: "builtin",
|
||||
Emoji: "📝",
|
||||
Execute: makeWriteExecutor(cwd, mq, rt),
|
||||
Execute: makeWriteExecutor(cwd, mq, rt, NewCheckpointStore(cwd)),
|
||||
}
|
||||
}
|
||||
|
||||
func makeWriteExecutor(cwd string, mq *MutationQueue, rt *ReadTracker) Executor {
|
||||
func makeWriteExecutor(cwd string, mq *MutationQueue, rt *ReadTracker, cp *CheckpointStore) Executor {
|
||||
return func(ctx context.Context, params json.RawMessage, _ UIBridge) (Result, error) {
|
||||
var p WriteParams
|
||||
if err := json.Unmarshal(params, &p); err != nil {
|
||||
@@ -92,6 +92,14 @@ func makeWriteExecutor(cwd string, mq *MutationQueue, rt *ReadTracker) Executor
|
||||
release := mq.Acquire(path)
|
||||
defer release()
|
||||
|
||||
// Snapshot before the first byte changes. If the checkpoint cannot
|
||||
// be taken the write is refused: proceeding would produce a
|
||||
// mutation with nothing to restore from.
|
||||
if _, err := cp.Snapshot(path); err != nil {
|
||||
result = Result{Content: fmt.Sprintf("refusing to write %s: %v", path, err), IsError: true, ErrorKind: "checkpoint_failed"}
|
||||
return nil
|
||||
}
|
||||
|
||||
dir := filepath.Dir(path)
|
||||
if err := os.MkdirAll(dir, 0o755); err != nil {
|
||||
result = Result{Content: fmt.Sprintf("error creating directory: %v", err), IsError: true}
|
||||
|
||||
Reference in new issue
Block a user