pi-rewind-hook 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.3.0] - 2026-01-05
+
+### Breaking Changes
+- Requires pi v0.35.0+ (unified extensions system)
+- Install location changed from `hooks/rewind` to `extensions/rewind`
+
+### Changed
+- Migrated from hooks to unified extensions system
+- Settings key changed from `hooks` to `extensions`
+- Install script now migrates old hooks config and cleans up old directory
+- Renamed "Hook" to "Extension" throughout codebase and docs
+
+## [1.2.0] - 2025-01-03
+
+### Added
+- Tree navigation support (`session_before_tree`) - restore files when navigating session tree
+- Entry-based checkpoint mapping (uses entry IDs instead of turn indices)
+
+### Changed
+- Migrated to granular session events API (pi-coding-agent v0.31+)
+- Use `pi.exec` instead of `ctx.exec` per updated hooks API
+
+### Fixed
+- Removed `agent_end` handler that was clearing checkpoints after each turn
+- "Undo last file rewind" now cancels branch instead of creating unwanted branch
+
 ## [1.1.1] - 2024-12-27
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
-# Rewind Hook
+# Rewind Extension
 
-A Pi agent hook that enables rewinding file changes during coding sessions. Creates automatic checkpoints using git refs, allowing you to restore files to previous states while optionally preserving conversation history.
+A Pi agent extension that enables rewinding file changes during coding sessions. Creates automatic checkpoints using git refs, allowing you to restore files to previous states while optionally preserving conversation history.
 
 ## Screenshots
 
@@ -10,7 +10,7 @@ A Pi agent hook that enables rewinding file changes during coding sessions. Crea
 
 ## Requirements
 
-- Pi agent v0.18.0+
+- Pi agent v0.35.0+ (unified extensions system)
 - Node.js (for installation)
 - Git repository (checkpoints are stored as git refs)
 
@@ -21,9 +21,11 @@ npx pi-rewind-hook
 ```
 
 This will:
-1. Create `~/.pi/agent/hooks/rewind/`
-2. Download the hook files
-3. Add the hook to your `~/.pi/agent/settings.json`
+1. Create `~/.pi/agent/extensions/rewind/`
+2. Download the extension files
+3. Add the extension to your `~/.pi/agent/settings.json`
+4. Migrate any existing hooks config to extensions (if upgrading from v1.2.0)
+5. Clean up old `hooks/rewind` directory (if present)
 
 ### Alternative Installation
 
@@ -36,14 +38,14 @@ curl -fsSL https://raw.githubusercontent.com/nicobailon/pi-rewind-hook/main/inst
 Or clone the repo and configure manually:
 
 ```bash
-git clone https://github.com/nicobailon/pi-rewind-hook ~/.pi/agent/hooks/rewind
+git clone https://github.com/nicobailon/pi-rewind-hook ~/.pi/agent/extensions/rewind
 ```
 
 Then add to `~/.pi/agent/settings.json`:
 
 ```json
 {
-  "hooks": ["~/.pi/agent/hooks/rewind/index.ts"]
+  "extensions": ["~/.pi/agent/extensions/rewind/index.ts"]
 }
 ```
 
@@ -55,11 +57,20 @@ Then add to `~/.pi/agent/settings.json`:
 Invoke-WebRequest -Uri "https://raw.githubusercontent.com/nicobailon/pi-rewind-hook/main/install.js" -OutFile install.js; node install.js; Remove-Item install.js
 ```
 
+### Upgrading from v1.2.0
+
+If you're upgrading from pi-rewind-hook v1.2.0 (which used the hooks system), simply run `npx pi-rewind-hook` again. The installer will:
+- Move the extension from `hooks/rewind` to `extensions/rewind`
+- Migrate your settings.json from `hooks` to `extensions`
+- Clean up the old hooks directory
+
+**Note:** v1.3.0+ requires pi v0.35.0 or later. If you're on an older version of pi, stay on pi-rewind-hook v1.2.0.
+
 ## How It Works
 
 ### Checkpoints
 
-The hook creates git refs at two points:
+The extension creates git refs at two points:
 
 1. **Session start** - When pi starts, creates a "resume checkpoint" of the current file state
 2. **Each turn** - Before the agent processes each message, creates a checkpoint
@@ -68,11 +79,17 @@ Checkpoints are stored as git refs under `refs/pi-checkpoints/` and are pruned t
 
 ### Rewinding
 
-To rewind:
+To rewind via `/branch`:
 
 1. Type `/branch` in pi
 2. Select a message to branch from
-3. Choose a restore option:
+3. Choose a restore option
+
+To rewind via tree navigation:
+
+1. Press `Tab` to open the session tree
+2. Navigate to a different node
+3. Choose a restore option
 
 **For messages from the current session:**
 
@@ -81,6 +98,7 @@ To rewind:
 | **Restore all (files + conversation)** | Restored | Reset to that point |
 | **Conversation only (keep current files)** | Unchanged | Reset to that point |
 | **Code only (restore files, keep conversation)** | Restored | Unchanged |
+| **Undo last file rewind** | Restored to before last rewind | Unchanged |
 
 **For messages from before the current session (uses resume checkpoint):**
 
@@ -89,10 +107,11 @@ To rewind:
 | **Restore to session start (files + conversation)** | Restored to session start | Reset to that point |
 | **Conversation only (keep current files)** | Unchanged | Reset to that point |
 | **Restore to session start (files only, keep conversation)** | Restored to session start | Unchanged |
+| **Undo last file rewind** | Restored to before last rewind | Unchanged |
 
 ### Resumed Sessions
 
-When you resume a session (`pi --resume`), the hook creates a resume checkpoint. If you branch to a message from before the current session, you can restore files to the state when you resumed (not per-message granularity, but a safety net).
+When you resume a session (`pi --resume`), the extension creates a resume checkpoint. If you branch to a message from before the current session, you can restore files to the state when you resumed (not per-message granularity, but a safety net).
 
 ## Examples
 
@@ -157,15 +176,15 @@ git for-each-ref --format='%(refname)' refs/pi-checkpoints/ | xargs -n1 git upda
 
 ## Uninstalling
 
-1. Remove the hook directory:
+1. Remove the extension directory:
    ```bash
-   rm -rf ~/.pi/agent/hooks/rewind
+   rm -rf ~/.pi/agent/extensions/rewind
    ```
-   On Windows (PowerShell): `Remove-Item -Recurse -Force ~/.pi/agent/hooks/rewind`
+   On Windows (PowerShell): `Remove-Item -Recurse -Force ~/.pi/agent/extensions/rewind`
 
-2. Remove the hook from `~/.pi/agent/settings.json` (delete the line with `rewind/index.ts` from the `hooks` array)
+2. Remove the extension from `~/.pi/agent/settings.json` (delete the line with `rewind/index.ts` from the `extensions` array)
 
-3. Optionally, clean up git refs in each repo where you used the hook:
+3. Optionally, clean up git refs in each repo where you used the extension:
    ```bash
    git for-each-ref --format='%(refname)' refs/pi-checkpoints/ | xargs -n1 git update-ref -d
    ```

package/index.ts

@@ -1,4 +1,13 @@
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+/**
+ * Rewind Extension - Git-based file restoration for pi branching
+ *
+ * Creates worktree snapshots at each turn so /branch can restore code state.
+ * Supports: restore files + conversation, files only, conversation only, undo last restore.
+ *
+ * Updated for pi-coding-agent v0.35.0+ (unified extensions system)
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { exec as execCb } from "child_process";
 import { mkdtemp, rm } from "fs/promises";
 import { tmpdir } from "os";
@@ -13,13 +22,14 @@ const MAX_CHECKPOINTS = 100;
 
 type ExecFn = (cmd: string, args: string[]) => Promise<{ stdout: string; stderr: string; code: number }>;
 
-export default function (pi: HookAPI) {
-  const checkpoints = new Map<number, string>();
+export default function (pi: ExtensionAPI) {
+  const checkpoints = new Map<string, string>();
+  let currentEntryId: string | undefined;
   let resumeCheckpoint: string | null = null;
   let repoRoot: string | null = null;
   let isGitRepo = false;
 
-  console.error(`[rewind] Hook loaded`);
+  console.error(`[rewind] Extension loaded`);
 
   async function findBeforeRestoreRef(exec: ExecFn): Promise<{ refName: string; commitSha: string } | null> {
     try {
@@ -71,7 +81,7 @@ export default function (pi: HookAPI) {
   async function restoreWithBackup(
     exec: ExecFn,
     targetRef: string,
-    notify: (msg: string, level: "success" | "error" | "info") => void
+    notify: (msg: string, level: "info" | "warning" | "error") => void
   ): Promise<boolean> {
     try {
       const existingBackup = await findBeforeRestoreRef(exec);
@@ -113,12 +123,38 @@ export default function (pi: HookAPI) {
     }
   }
 
-  pi.on("session", async (event, ctx) => {
-    if (event.reason !== "start") return;
+  async function pruneCheckpoints(exec: ExecFn) {
+    try {
+      const result = await exec("git", [
+        "for-each-ref",
+        "--sort=creatordate",
+        "--format=%(refname)",
+        REF_PREFIX,
+      ]);
+
+      const refs = result.stdout.trim().split("\n").filter(Boolean);
+      const currentResumeRef = resumeCheckpoint ? `${REF_PREFIX}${resumeCheckpoint}` : null;
+      const checkpointRefs = refs.filter(r =>
+        !r.includes(BEFORE_RESTORE_PREFIX) && r !== currentResumeRef
+      );
+
+      if (checkpointRefs.length > MAX_CHECKPOINTS) {
+        const toDelete = checkpointRefs.slice(0, checkpointRefs.length - MAX_CHECKPOINTS);
+        for (const ref of toDelete) {
+          await exec("git", ["update-ref", "-d", ref]);
+          console.error(`[rewind] Pruned old checkpoint: ${ref}`);
+        }
+      }
+    } catch (err) {
+      console.error(`[rewind] Failed to prune checkpoints: ${err}`);
+    }
+  }
+
+  pi.on("session_start", async (_event, ctx) => {
     if (!ctx.hasUI) return;
 
     try {
-      const result = await ctx.exec("git", ["rev-parse", "--is-inside-work-tree"]);
+      const result = await pi.exec("git", ["rev-parse", "--is-inside-work-tree"]);
       isGitRepo = result.stdout.trim() === "true";
     } catch {
       isGitRepo = false;
@@ -129,7 +165,7 @@ export default function (pi: HookAPI) {
     const checkpointId = `checkpoint-resume-${Date.now()}`;
 
     try {
-      const success = await createCheckpointFromWorktree(ctx.exec, checkpointId);
+      const success = await createCheckpointFromWorktree(pi.exec, checkpointId);
       if (success) {
         resumeCheckpoint = checkpointId;
         console.error(`[rewind] Created resume checkpoint: ${checkpointId}`);
@@ -139,6 +175,11 @@ export default function (pi: HookAPI) {
     }
   });
 
+  pi.on("tool_result", async (_event, ctx) => {
+    const leaf = ctx.sessionManager.getLeafEntry();
+    if (leaf) currentEntryId = leaf.id;
+  });
+
   pi.on("turn_start", async (event, ctx) => {
     if (!ctx.hasUI) return;
     if (!isGitRepo) return;
@@ -146,25 +187,30 @@ export default function (pi: HookAPI) {
     const checkpointId = `checkpoint-${event.timestamp}`;
 
     try {
-      const success = await createCheckpointFromWorktree(ctx.exec, checkpointId);
-      if (success) {
-        checkpoints.set(event.turnIndex, checkpointId);
+      const success = await createCheckpointFromWorktree(pi.exec, checkpointId);
+      if (success && currentEntryId) {
+        checkpoints.set(currentEntryId, checkpointId);
         console.error(
-          `[rewind] Created checkpoint ${checkpointId} for turn ${event.turnIndex}`
+          `[rewind] Created checkpoint ${checkpointId} for entry ${currentEntryId}`
         );
-        await pruneCheckpoints(ctx.exec);
+        await pruneCheckpoints(pi.exec);
       }
     } catch (err) {
       console.error(`[rewind] Failed to create checkpoint: ${err}`);
     }
   });
 
-  pi.on("session", async (event, ctx) => {
-    if (event.reason !== "before_branch") return;
+  pi.on("session_before_branch", async (event, ctx) => {
     if (!ctx.hasUI) return;
-    if (!isGitRepo) return;
 
-    let checkpointId = checkpoints.get(event.targetTurnIndex);
+    try {
+      const result = await pi.exec("git", ["rev-parse", "--is-inside-work-tree"]);
+      if (result.stdout.trim() !== "true") return;
+    } catch {
+      return;
+    }
+
+    let checkpointId = checkpoints.get(event.entryId);
     let usingResumeCheckpoint = false;
 
     if (!checkpointId && resumeCheckpoint) {
@@ -172,7 +218,7 @@ export default function (pi: HookAPI) {
       usingResumeCheckpoint = true;
     }
 
-    const beforeRestoreRef = await findBeforeRestoreRef(ctx.exec);
+    const beforeRestoreRef = await findBeforeRestoreRef(pi.exec);
     const hasUndo = !!beforeRestoreRef;
 
     if (!checkpointId && !hasUndo) {
@@ -184,7 +230,7 @@ export default function (pi: HookAPI) {
     }
 
     const options: string[] = [];
-    
+
     if (checkpointId) {
       if (usingResumeCheckpoint) {
         options.push("Restore to session start (files + conversation)");
@@ -217,28 +263,28 @@ export default function (pi: HookAPI) {
 
     if (choice === "Undo last file rewind") {
       const success = await restoreWithBackup(
-        ctx.exec,
+        pi.exec,
         beforeRestoreRef!.commitSha,
         ctx.ui.notify.bind(ctx.ui)
       );
       if (success) {
-        ctx.ui.notify("Files restored to before last rewind", "success");
+        ctx.ui.notify("Files restored to before last rewind", "info");
       }
-      return { skipConversationRestore: true };
+      return { cancel: true };
     }
 
     const ref = `${REF_PREFIX}${checkpointId}`;
     const success = await restoreWithBackup(
-      ctx.exec,
+      pi.exec,
       ref,
       ctx.ui.notify.bind(ctx.ui)
     );
     if (success) {
       ctx.ui.notify(
-        usingResumeCheckpoint 
-          ? "Files restored to session start" 
+        usingResumeCheckpoint
+          ? "Files restored to session start"
           : "Files restored from checkpoint",
-        "success"
+        "info"
       );
     }
 
@@ -247,30 +293,87 @@ export default function (pi: HookAPI) {
     }
   });
 
-  async function pruneCheckpoints(exec: ExecFn) {
+  pi.on("session_before_tree", async (event, ctx) => {
+    if (!ctx.hasUI) return;
+
     try {
-      const result = await exec("git", [
-        "for-each-ref",
-        "--sort=creatordate",
-        "--format=%(refname)",
-        REF_PREFIX,
-      ]);
+      const result = await pi.exec("git", ["rev-parse", "--is-inside-work-tree"]);
+      if (result.stdout.trim() !== "true") return;
+    } catch {
+      return;
+    }
 
-      const refs = result.stdout.trim().split("\n").filter(Boolean);
-      const currentResumeRef = resumeCheckpoint ? `${REF_PREFIX}${resumeCheckpoint}` : null;
-      const checkpointRefs = refs.filter(r => 
-        !r.includes(BEFORE_RESTORE_PREFIX) && r !== currentResumeRef
-      );
+    const targetId = event.preparation.targetId;
+    let checkpointId = checkpoints.get(targetId);
+    let usingResumeCheckpoint = false;
 
-      if (checkpointRefs.length > MAX_CHECKPOINTS) {
-        const toDelete = checkpointRefs.slice(0, checkpointRefs.length - MAX_CHECKPOINTS);
-        for (const ref of toDelete) {
-          await exec("git", ["update-ref", "-d", ref]);
-          console.error(`[rewind] Pruned old checkpoint: ${ref}`);
-        }
+    if (!checkpointId && resumeCheckpoint) {
+      checkpointId = resumeCheckpoint;
+      usingResumeCheckpoint = true;
+    }
+
+    const beforeRestoreRef = await findBeforeRestoreRef(pi.exec);
+    const hasUndo = !!beforeRestoreRef;
+
+    if (!checkpointId && !hasUndo) {
+      ctx.ui.notify("No checkpoint available for this message", "info");
+      return;
+    }
+
+    const options: string[] = [];
+
+    if (checkpointId) {
+      if (usingResumeCheckpoint) {
+        options.push("Restore files to session start");
+      } else {
+        options.push("Restore files to that point");
       }
-    } catch (err) {
-      console.error(`[rewind] Failed to prune checkpoints: ${err}`);
+      options.push("Keep current files");
     }
-  }
+
+    if (hasUndo) {
+      options.push("Undo last file rewind");
+    }
+
+    options.push("Cancel navigation");
+
+    const choice = await ctx.ui.select("Restore Options", options);
+
+    if (!choice || choice === "Cancel navigation") {
+      ctx.ui.notify("Navigation cancelled", "info");
+      return { cancel: true };
+    }
+
+    if (choice === "Keep current files") {
+      return;
+    }
+
+    if (choice === "Undo last file rewind") {
+      const success = await restoreWithBackup(
+        pi.exec,
+        beforeRestoreRef!.commitSha,
+        ctx.ui.notify.bind(ctx.ui)
+      );
+      if (success) {
+        ctx.ui.notify("Files restored to before last rewind", "info");
+      }
+      return { cancel: true };
+    }
+
+    const ref = `${REF_PREFIX}${checkpointId}`;
+    const success = await restoreWithBackup(
+      pi.exec,
+      ref,
+      ctx.ui.notify.bind(ctx.ui)
+    );
+    if (success) {
+      ctx.ui.notify(
+        usingResumeCheckpoint
+          ? "Files restored to session start"
+          : "Files restored to checkpoint",
+        "info"
+      );
+    }
+  });
+
 }

package/install.js

@@ -6,9 +6,10 @@ const https = require("https");
 const os = require("os");
 
 const REPO_URL = "https://raw.githubusercontent.com/nicobailon/pi-rewind-hook/main";
-const HOOK_DIR = path.join(os.homedir(), ".pi", "agent", "hooks", "rewind");
+const EXT_DIR = path.join(os.homedir(), ".pi", "agent", "extensions", "rewind");
+const OLD_HOOK_DIR = path.join(os.homedir(), ".pi", "agent", "hooks", "rewind");
 const SETTINGS_FILE = path.join(os.homedir(), ".pi", "agent", "settings.json");
-const HOOK_PATH = "~/.pi/agent/hooks/rewind/index.ts";
+const EXT_PATH = "~/.pi/agent/extensions/rewind/index.ts";
 
 function download(url) {
   return new Promise((resolve, reject) => {
@@ -28,22 +29,19 @@ function download(url) {
 }
 
 async function main() {
-  console.log("Installing pi-rewind-hook...\n");
+  console.log("Installing pi-rewind-hook (Rewind Extension)...\n");
 
-  // Create hook directory
-  console.log(`Creating directory: ${HOOK_DIR}`);
-  fs.mkdirSync(HOOK_DIR, { recursive: true });
+  fs.mkdirSync(EXT_DIR, { recursive: true });
+  console.log(`Created directory: ${EXT_DIR}`);
 
-  // Download hook files
   console.log("Downloading index.ts...");
-  const hookContent = await download(`${REPO_URL}/index.ts`);
-  fs.writeFileSync(path.join(HOOK_DIR, "index.ts"), hookContent);
+  const extContent = await download(`${REPO_URL}/index.ts`);
+  fs.writeFileSync(path.join(EXT_DIR, "index.ts"), extContent);
 
   console.log("Downloading README.md...");
   const readmeContent = await download(`${REPO_URL}/README.md`);
-  fs.writeFileSync(path.join(HOOK_DIR, "README.md"), readmeContent);
+  fs.writeFileSync(path.join(EXT_DIR, "README.md"), readmeContent);
 
-  // Update settings.json
   console.log(`\nUpdating settings: ${SETTINGS_FILE}`);
   
   let settings = {};
@@ -56,25 +54,54 @@ async function main() {
     }
   }
 
-  // Ensure hooks array exists
-  if (!Array.isArray(settings.hooks)) {
-    settings.hooks = [];
+  if (settings.hooks && Array.isArray(settings.hooks) && settings.hooks.length > 0) {
+    console.log("\nMigrating hooks to extensions...");
+    if (!Array.isArray(settings.extensions)) {
+      settings.extensions = [];
+    }
+    for (const entry of settings.hooks) {
+      if (entry.includes("/hooks/rewind")) {
+        continue;
+      }
+      const newPath = entry.replace("/hooks/", "/extensions/");
+      if (!settings.extensions.includes(newPath)) {
+        settings.extensions.push(newPath);
+        console.log(`  Migrated: ${entry} -> ${newPath}`);
+      }
+    }
+    delete settings.hooks;
+    console.log("Removed old 'hooks' key from settings");
+  }
+
+  if (!Array.isArray(settings.extensions)) {
+    settings.extensions = [];
   }
 
-  // Add hook if not already present
-  if (!settings.hooks.includes(HOOK_PATH)) {
-    settings.hooks.push(HOOK_PATH);
-    
-    // Ensure parent directory exists
-    fs.mkdirSync(path.dirname(SETTINGS_FILE), { recursive: true });
-    fs.writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + "\n");
-    console.log(`Added "${HOOK_PATH}" to hooks array`);
+  const EXT_PATH_ALT = "~/.pi/agent/extensions/rewind";
+  const hasRewindExt = settings.extensions.some(p => 
+    p === EXT_PATH || p === EXT_PATH_ALT || 
+    p.includes("/extensions/rewind/index.ts") || 
+    p.endsWith("/extensions/rewind")
+  );
+
+  if (!hasRewindExt) {
+    settings.extensions.push(EXT_PATH);
+    console.log(`Added "${EXT_PATH}" to extensions array`);
   } else {
-    console.log("Hook already configured in settings.json");
+    console.log("Extension already configured in settings.json");
+  }
+
+  fs.mkdirSync(path.dirname(SETTINGS_FILE), { recursive: true });
+  fs.writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + "\n");
+
+  if (fs.existsSync(OLD_HOOK_DIR)) {
+    console.log(`\nCleaning up old hooks directory: ${OLD_HOOK_DIR}`);
+    fs.rmSync(OLD_HOOK_DIR, { recursive: true, force: true });
+    console.log("Removed old hooks/rewind directory");
   }
 
   console.log("\nInstallation complete!");
-  console.log("\nThe rewind hook will load automatically when you start pi.");
+  console.log("\nThe rewind extension will load automatically when you start pi.");
   console.log("Use /branch to rewind to a previous checkpoint.");
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-rewind-hook",
-  "version": "1.1.1",
-  "description": "Rewind hook for Pi agent - automatic git checkpoints with file/conversation restore",
+  "version": "1.3.0",
+  "description": "Rewind extension for Pi agent - automatic git checkpoints with file/conversation restore",
   "bin": {
     "pi-rewind-hook": "./install.js"
   },
@@ -12,11 +12,14 @@
   "keywords": [
     "pi",
     "pi-agent",
-    "hook",
+    "extension",
     "checkpoint",
     "rewind",
     "git"
   ],
   "author": "nicobailon",
-  "license": "MIT"
+  "license": "MIT",
+  "pi": {
+    "extensions": ["./index.ts"]
+  }
 }