pi-undo 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# pi-undo
+
+A pi extension that undoes the last user turn in the current session via `/undo`.
+
+## Install
+
+```bash
+# local path
+pi install /absolute/path/to/pi-undo
+
+# or try once without installing
+pi -e /absolute/path/to/pi-undo
+```
+
+## Usage
+
+| Command | Effect |
+|---------|--------|
+| `/undo` | Undo the last user turn |
+| `/undo 2` | Undo the last two user turns |
+
+Behavior matches selecting the previous user message in `/tree`:
+
+1. Moves the session leaf to the parent of that user message (append-only branch).
+2. Puts the undone prompt text back in the editor so you can edit and resubmit.
+3. Leaves the abandoned path in the session tree (nothing is deleted).
+
+## What it does **not** do
+
+- Does **not** revert filesystem changes from tools (`edit`, `write`, `bash`, …).
+  Session history and disk state are separate. Use something like the
+  [git-checkpoint](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/examples/extensions/git-checkpoint.ts)
+  example if you want code restored when branching.
+- Does **not** run while the agent is streaming. Abort first, then `/undo`.
+
+## Prompt cache / read-write cache safety
+
+Undo goes through `ctx.navigateTree()`:
+
+- Session storage stays append-only (tree branch, no rewrite/truncation of JSONL).
+- Agent message state is rebuilt from the retained branch prefix.
+- The same session id is kept, so provider prompt-cache affinity remains valid
+  for the shared prefix (everything still on the active path after the rewind).
+
+Avoid hand-editing the session file or clearing messages outside the tree API —
+that is what breaks cache alignment.
+
+## How it works
+
+```text
+user₁ → asst₁ → user₂ → asst₂   ← leaf
+                 ▲
+                 └── /undo targets this user message
+
+After /undo:
+user₁ → asst₁   ← new leaf
+                 └── (user₂ → asst₂ still in tree as abandoned branch)
+
+Editor contains the text of user₂ for re-edit/resubmit.
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,75 @@
+/**
+ * /undo - walk the active session branch back one user turn.
+ *
+ * Uses ctx.navigateTree() so session state stays append-only (tree branch),
+ * agent messages rebuild from the retained prefix, and prompt-cache affinity
+ * is preserved for everything still on the active path.
+ *
+ * Does not revert filesystem changes made by tools during the undone turn.
+ * Pair with git-checkpoint (or similar) if you need code restore on branch.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+function findLastUserMessageId(ctx: ExtensionCommandContext): string | undefined {
+	const branch = ctx.sessionManager.getBranch();
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i];
+		if (entry.type === "message" && entry.message.role === "user") {
+			return entry.id;
+		}
+	}
+	return undefined;
+}
+
+function parseSteps(args: string): number | undefined {
+	const trimmed = args.trim();
+	if (!trimmed) return 1;
+	if (!/^\d+$/.test(trimmed)) return undefined;
+	const n = Number(trimmed);
+	if (!Number.isInteger(n) || n < 1) return undefined;
+	return n;
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("undo", {
+		description: "Undo the last user turn (usage: /undo [n])",
+		handler: async (args, ctx) => {
+			const steps = parseSteps(args);
+			if (steps === undefined) {
+				ctx.ui.notify("Usage: /undo [n]  (n = positive integer, default 1)", "warning");
+				return;
+			}
+
+			if (!ctx.isIdle()) {
+				ctx.ui.notify("Agent is busy. Abort the current turn first, then /undo.", "warning");
+				return;
+			}
+
+			let undone = 0;
+			for (let i = 0; i < steps; i++) {
+				const targetId = findLastUserMessageId(ctx);
+				if (!targetId) {
+					if (undone === 0) {
+						ctx.ui.notify("Nothing to undo", "info");
+					} else {
+						ctx.ui.notify(`Undid ${undone} turn${undone === 1 ? "" : "s"} (no more on this branch)`, "info");
+					}
+					return;
+				}
+
+				// Navigate to the user message: leaf moves to its parent, prompt
+				// text is restored to the editor. No branch summary — undo is a
+				// deliberate rewind, not a context-preserving switch.
+				const result = await ctx.navigateTree(targetId, { summarize: false });
+				if (result.cancelled) {
+					ctx.ui.notify(undone === 0 ? "Undo cancelled" : `Undid ${undone}, then cancelled`, "warning");
+					return;
+				}
+				undone++;
+			}
+
+			ctx.ui.notify(undone === 1 ? "Undid last turn" : `Undid ${undone} turns`, "info");
+		},
+	});
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "pi-undo",
+  "version": "0.1.0",
+  "description": "A pi extension that undoes the last user turn in a session via /undo",
+  "license": "MIT",
+  "author": "Richard Anaya",
+  "type": "module",
+  "main": "index.ts",
+  "types": "index.ts",
+  "files": [
+    "index.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prepublishOnly": "echo 'Ready to publish'"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "cli",
+    "tui",
+    "undo",
+    "session",
+    "branch",
+    "terminal",
+    "ai"
+  ]
+}