wehub-resource-sync
147 lines
6.5 KiB
Markdown
147 lines
6.5 KiB
Markdown
# Design: Checkpoints & Rewind
|
|
|
|
Status: **Phase 1 + 2 implemented** — snapshot store, capture seam, the Esc-Esc /
|
|
`/rewind` CLI picker, and the desktop hover-rewind, with the full Claude Code menu:
|
|
restore code / conversation / both, fork-from-here, and summarize from / up to
|
|
here. Snapshot-based and aligned with Claude Code. An optional git-backed mode is
|
|
the remaining (lower-priority) follow-up. Tracks the most requested missing
|
|
capability from v1 — an edit safety net / undo.
|
|
|
|
This document describes rewind snapshots. For the autonomous-run rule about when
|
|
the agent should pause and ask the user, see
|
|
[`TASK_CONTRACT.md`](TASK_CONTRACT.md).
|
|
|
|
## Goal
|
|
|
|
Let a user rewind a session to a previous point and restore **code**,
|
|
**conversation**, or **both** — without touching their git history. Aligned with
|
|
Claude Code's rewind (Esc-Esc / `/rewind`), driven identically from the CLI and
|
|
the desktop.
|
|
|
|
## Mechanism: file snapshots, not git
|
|
|
|
Like Claude Code (and v1's `checkpoints.ts`), checkpoints are **file snapshots**,
|
|
independent of git:
|
|
|
|
- **Zero git pollution** — never commits, stages, or touches `.git/`. Works in a
|
|
non-git directory.
|
|
- **Tracks only previewable edit-tool changes** — `write_file` / `edit_file` / `multi_edit`.
|
|
File moves via `move_file` follow the same workspace permission boundary, but
|
|
are not yet represented in checkpoint previews.
|
|
`bash` side effects are **not** tracked (no way to know what a shell command
|
|
touched), exactly as Claude Code. Risky bash is already permission-gated.
|
|
- Full pre-edit content snapshots (simple; storage bounded by retention, below).
|
|
|
|
An optional **git-backed mode** (v1's `auto-git-rollback`) is a possible Phase 2
|
|
for users who want git-level safety; it is explicitly out of scope here.
|
|
|
|
## Anchors & capture
|
|
|
|
- **One checkpoint per user turn.** A checkpoint opens when a turn starts
|
|
(`Controller.Send` / `runTurn`), labelled with the user prompt.
|
|
- **Pre-edit snapshot.** In `agent.(*Agent).executeOne`, before running a tool
|
|
whose `ReadOnly()` is false and which implements `tool.Previewer`, call
|
|
`Preview(args)` → `diff.Change{Path, Kind, OldText}` and record a snapshot of
|
|
that file into the active checkpoint. `tool.Previewer` already exists and the
|
|
file-writers implement it, so this is one centralized seam — no per-tool code.
|
|
- Dedup per path per turn: only the **first** touch is snapshotted (that is the
|
|
file's turn-start content).
|
|
- `Kind == create` (file did not exist) → store `Content = nil` so a restore
|
|
*deletes* it. `modify`/`delete` → store `OldText`.
|
|
- `bash` has no `Previewer`, so it is naturally excluded — matching the
|
|
"edit-tools only" contract.
|
|
|
|
## Data model
|
|
|
|
```go
|
|
type FileSnap struct {
|
|
Path string // workspace-relative
|
|
Content *string // nil → file did not exist at the anchor (restore deletes it)
|
|
}
|
|
|
|
type Checkpoint struct {
|
|
Turn int // user-message index this anchors (0-based)
|
|
Time time.Time
|
|
Prompt string // user message text — the picker label
|
|
Files []FileSnap // distinct files touched during this turn, turn-start state
|
|
}
|
|
```
|
|
|
|
## Storage
|
|
|
|
- **Sidecar to the session**, under `config.SessionDir()`: `<session-id>.ckpt/`
|
|
with one JSON per checkpoint plus a small index (v1's layout — cheap delete, a
|
|
corrupt snapshot only loses itself). Kept separate from the message JSONL
|
|
(`agent.Session.Save`) so the session format is unchanged.
|
|
- **Persists across sessions** — resuming a session re-loads its checkpoints, so
|
|
rewind works after a restart (Claude Code parity).
|
|
- **Retention**: prune with the session (default ~30 days, configurable), to bound
|
|
disk from full-content snapshots.
|
|
|
|
## Controller API (the one seam both frontends drive)
|
|
|
|
Checkpoints live on `control.Controller`, beside `SetPlanMode` / `Compact` /
|
|
`NewSession`, so the terminal TUI, the desktop webview, and the HTTP/SSE server
|
|
drive rewind identically and none re-implement it.
|
|
|
|
```go
|
|
type RewindScope int // Code | Conversation | Both
|
|
|
|
func (c *Controller) Checkpoints() []CheckpointMeta // for the picker
|
|
func (c *Controller) Rewind(turn int, scope RewindScope) error
|
|
```
|
|
|
|
- **Code**: for every checkpoint from `turn` to the latest, take the earliest
|
|
`FileSnap` per path and restore each file to that content (delete if `nil`) —
|
|
i.e. undo all edits made at or after `turn`. Path-escape re-checked against the
|
|
live workspace root.
|
|
- **Conversation**: truncate `Session.Messages` to just before turn `turn`'s user
|
|
message, re-`Save`, and emit the truncated history as events so the frontend
|
|
re-renders. The turn's prompt is restored into the composer for re-send/edit
|
|
(Claude Code behavior).
|
|
- **Both**: code + conversation.
|
|
|
|
A `Rewound` event (or reuse of a history-replace event) lets every frontend
|
|
re-render uniformly.
|
|
|
|
## CLI UX (aligned with Claude Code)
|
|
|
|
- **`Esc Esc`** with an empty composer, or **`/rewind`**, opens a picker listing
|
|
each user turn (time + which files it changed). `chat_tui` already tracks the
|
|
double-Esc timing.
|
|
- Select a turn → sub-menu: **`[code+conversation] [conversation] [code] [cancel]`**.
|
|
- On a conversation/both restore, the selected prompt is prefilled into the
|
|
composer.
|
|
|
|
## Desktop UX (aligned with the VS Code extension)
|
|
|
|
- Each user message in the transcript gets a hover **rewind** control → menu:
|
|
**rewind code / rewind conversation / both / fork-from-here**.
|
|
- It calls the same `controller.Rewind` over the Wails binding; the controller's
|
|
event stream pushes the restored state and React re-renders. No rewind logic in
|
|
the frontend.
|
|
|
|
## Non-goals & edge cases
|
|
|
|
- **bash / external side effects** (`rm`, `mv`, DB writes, deploys) are not
|
|
tracked — rewind cannot undo them (Claude Code parity).
|
|
- **External edits between turns**: a snapshot holds the file's turn-start
|
|
content, so restoring overwrites edits made outside reasonix in the meantime.
|
|
- **Deletions**: an edit-tool deletion is restorable (snapshot has the content); a
|
|
`bash rm` is not.
|
|
- **Large files**: full snapshots — retention cleanup bounds disk; revisit dedup
|
|
(content-addressed snapshots) if it becomes a problem.
|
|
|
|
## Phasing
|
|
|
|
1. **Phase 1**: snapshot store + `executeOne` capture seam + `Controller.Rewind`
|
|
(code/conversation/both) + CLI picker (Esc-Esc + `/rewind`).
|
|
2. **Phase 2**: desktop hover-rewind UI; "fork from here"; "summarize from/up to
|
|
here"; optional git-backed mode.
|
|
|
|
## Open questions
|
|
|
|
- Snapshot on `/compact` and on `NewSession` boundaries?
|
|
- Default retention window and whether to expose it in `[checkpoints]` config.
|
|
- Content-addressed dedup vs one-file-per-snapshot from the start.
|