diff --git a/internal/tools/builtin/checkpoint.go b/internal/tools/builtin/checkpoint.go new file mode 100644 index 000000000..870b95de5 --- /dev/null +++ b/internal/tools/builtin/checkpoint.go @@ -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 +} diff --git a/internal/tools/builtin/checkpoint_test.go b/internal/tools/builtin/checkpoint_test.go new file mode 100644 index 000000000..c7d61c4d1 --- /dev/null +++ b/internal/tools/builtin/checkpoint_test.go @@ -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) + } +} diff --git a/internal/tools/builtin/edit.go b/internal/tools/builtin/edit.go index f75884a03..c0239d919 100644 --- a/internal/tools/builtin/edit.go +++ b/internal/tools/builtin/edit.go @@ -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} } diff --git a/internal/tools/builtin/write.go b/internal/tools/builtin/write.go index ec7a0f711..cd023a3f7 100644 --- a/internal/tools/builtin/write.go +++ b/internal/tools/builtin/write.go @@ -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}