pi-quick-cancel 0.2.0

package/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+Copyright (c) 2026 ezoushen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE.

package/README.md

@@ -0,0 +1,76 @@
+# pi-quick-cancel
+
+Cancel a running turn, rewind the chat to before the prompt was sent, and put
+the prompt back in the editor — a true unwind, so it is as if the prompt was
+never submitted (except that it is waiting in the editor).
+
+## Install
+
+```sh
+pi install npm:pi-quick-cancel
+```
+
+## What it does
+
+Pressing the shortcut (or running `/quick-cancel`) does one thing, whether a
+turn is running or the last one already completed: it cancels any in-flight
+run, rewinds the session tree so the canonical chat history ends just before
+the prompt (the user message and any assistant output drop out of the context
+entirely), rebuilds the visible transcript, and puts the prompt back in the
+editor. If you were typing a new prompt, that text is left untouched.
+
+Mechanically: the shortcut dispatches the `quick-cancel` command, which waits
+for the loop to settle and invokes pi's tree navigation on the prompt's
+session entry — the only API surface that rebuilds the transcript.
+
+### Why `ctrl+alt+x`
+
+This extension registers its own shortcut that must actually fire. `escape` is
+already pi's built-in interrupt, so binding this to it is **skipped by pi** — the
+extension's handler would never be registered, and the shortcut would silently
+do nothing. `ctrl+alt+x` avoids that: `ctrl`+`alt`+a letter is delivered as a
+distinct escape sequence by terminals (so it does not collide with a free
+letter, and is not stripped like `ctrl+shift+x` would be to `ctrl+x`). Bind
+another key with the `key` setting if you prefer.
+
+## External contract
+
+One shortcut (default `ctrl+alt+x`, or `key` / `PI_QUICK_CANCEL_KEY`) and one
+command (`/quick-cancel`), both driving the same rewind described above. An
+invalid `key` falls back to `ctrl+alt+x` with a warning once per session.
+
+The terminal must actually send `ctrl+alt+x` for the shortcut to fire; a
+terminal without the kitty keyboard protocol may send the legacy `ESC`
+sequence instead, which pi does not bind. Verified against one such runtime:
+`alt+<letter>` (the classic `ESC`+letter meta form) fires fine, while
+`alt+escape` arrives as an ambiguous double-`ESC` and cannot be bound at all.
+
+## Settings
+
+Set `key` in `pi-quick-cancel.json` in the Pi agent settings directory, or use
+`PI_QUICK_CANCEL_KEY`:
+
+| setting | default | environment variable | purpose |
+|---|---|---|---|
+| `key` | `ctrl+alt+x` | `PI_QUICK_CANCEL_KEY` | Shortcut with one or more modifiers and a letter, digit, or named key. |
+
+For example:
+
+```json
+{
+  "key": "ctrl+alt+e"
+}
+```
+
+## Limitations
+
+Only the prompt **text** is returned to the editor. Any images that were
+attached to the original prompt cannot be restored through the editor, so they
+are not returned — re-attach them when you resend.
+
+## If the contract is unmet
+
+An invalid `key` falls back to `ctrl+alt+x` and warns once per session. If a key
+is bound to a key pi already uses (such as `escape` or `ctrl+x`), pi skips the
+extension's shortcut, so the shortcut never fires — pick a key that does not
+conflict with a built-in, or use the `quick-cancel` command.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "pi-quick-cancel",
+  "version": "0.2.0",
+  "description": "Cancel a running turn, rewind the chat to before the prompt was sent, and restore the prompt to the editor.",
+  "type": "module",
+  "main": "./quick-cancel.js",
+  "exports": "./quick-cancel.js",
+  "files": [
+    "quick-cancel.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ezoushen/pi-extensions.git",
+    "directory": "extensions/quick-cancel"
+  },
+  "homepage": "https://github.com/ezoushen/pi-extensions/tree/main/extensions/quick-cancel#readme",
+  "bugs": {
+    "url": "https://github.com/ezoushen/pi-extensions/issues"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./quick-cancel.js"
+    ]
+  }
+}

package/quick-cancel.js

@@ -0,0 +1,155 @@
+// shared/announce.ts
+var stderrAnnounced = /* @__PURE__ */ new Set();
+function announce(ctx, message, level, reason = message) {
+  if (ctx?.hasUI === false) {
+    if (stderrAnnounced.has(reason)) return;
+    stderrAnnounced.add(reason);
+    try {
+      process.stderr.write(`${message}
+`);
+    } catch {
+    }
+    return;
+  }
+  try {
+    ctx?.ui?.notify?.(message, level);
+  } catch {
+  }
+}
+
+// shared/settings.ts
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+var announcedConfigErrors = /* @__PURE__ */ new Set();
+function readConfig(path, ctx) {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    if (!announcedConfigErrors.has(path)) {
+      announcedConfigErrors.add(path);
+      const message = error instanceof Error ? error.message : String(error);
+      announce(ctx, `settings: could not parse ${path} (${message}); using defaults.`, "warning", `settings-parse:${path}`);
+    }
+    return {};
+  }
+}
+function resolveSettings(name, definitions, context, runtime = {}) {
+  const environment = runtime.environment ?? process.env;
+  const globalPath = join(runtime.agentDir ?? getAgentDir(), `${name}.json`);
+  const projectPath = join(context.cwd, CONFIG_DIR_NAME, `${name}.json`);
+  const globalConfig = readConfig(globalPath, context);
+  const projectConfig = context.isProjectTrusted() ? readConfig(projectPath, context) : {};
+  const resolved = {};
+  for (const key of Object.keys(definitions)) {
+    const definition = definitions[key];
+    let value = definition.default;
+    let provenance = { source: "default" };
+    if (definition.discover) {
+      try {
+        const discovered = definition.discover();
+        if (discovered !== void 0) {
+          value = discovered.value;
+          provenance = { source: "discovered", name: definition.discoverName ?? "discovery" };
+        }
+      } catch {
+      }
+    }
+    if (Object.hasOwn(globalConfig, key)) {
+      value = globalConfig[key];
+      provenance = { source: "global", path: globalPath };
+    }
+    if (Object.hasOwn(projectConfig, key)) {
+      value = projectConfig[key];
+      provenance = { source: "project", path: projectPath };
+    }
+    const environmentValue = environment[definition.env];
+    if (environmentValue !== void 0) {
+      value = definition.parseEnv ? definition.parseEnv(environmentValue) : environmentValue;
+      provenance = { source: "environment", name: definition.env };
+    }
+    resolved[key] = { value, provenance };
+  }
+  return resolved;
+}
+
+// extensions/quick-cancel/quick-cancel.ts
+var DEFAULT_KEY = "ctrl+alt+x";
+var KEY_SETTING = { key: { default: DEFAULT_KEY, env: "PI_QUICK_CANCEL_KEY" } };
+function isShortcutKey(value) {
+  if (typeof value !== "string") return false;
+  const parts = value.split("+");
+  const base = parts.pop();
+  return parts.length > 0 && new Set(parts).size === parts.length && parts.every((part) => ["ctrl", "alt", "shift", "super"].includes(part)) && base !== void 0 && (/^[a-z0-9]$/.test(base) || ["enter", "escape", "tab", "space", "backspace", "delete", "up", "down", "left", "right", "home", "end"].includes(base));
+}
+function contentText(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content.map((part) => part && typeof part === "object" && "text" in part ? String(part.text) : "").join("");
+  }
+  return "";
+}
+function findPromptEntryId(sm, prompt) {
+  const entries = sm.getEntries();
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry.type !== "message" || entry.message?.role !== "user") continue;
+    if (prompt === null || contentText(entry.message.content).trim() === prompt.trim()) return entry.id;
+  }
+  return void 0;
+}
+function registerQuickCancel(pi, settingsRuntime = {}) {
+  const resolved = resolveSettings("pi-quick-cancel", KEY_SETTING, {
+    cwd: process.cwd(),
+    hasUI: true,
+    isProjectTrusted: () => false
+  }, settingsRuntime);
+  const configuredKey = resolved.key.value;
+  const validKey = isShortcutKey(configuredKey);
+  const key = validKey ? configuredKey : DEFAULT_KEY;
+  let warnedAboutKey = false;
+  let captured = null;
+  pi.on("session_start", (_event, ctx) => {
+    if (!validKey && !warnedAboutKey) {
+      announce(ctx, "pi-quick-cancel: invalid key setting; using ctrl+alt+x", "warning", "pi-quick-cancel:invalid-key");
+      warnedAboutKey = true;
+    }
+  });
+  pi.on("before_agent_start", (event) => {
+    captured = event.prompt;
+  });
+  pi.on("agent_end", () => {
+    captured = null;
+  });
+  const rewind = async (ctx) => {
+    const prompt = captured;
+    if (!ctx.isIdle()) {
+      ctx.abort();
+      await ctx.waitForIdle();
+    }
+    const sm = ctx.sessionManager;
+    const entryId = findPromptEntryId(sm, prompt);
+    if (!entryId) {
+      announce(ctx, "pi-quick-cancel: nothing to rewind", "info");
+      return;
+    }
+    const result = await ctx.navigateTree(entryId);
+    if (result.cancelled) return;
+    const entry = sm.getEntry(entryId);
+    const promptText = prompt ?? (entry ? contentText(entry.message?.content) : "");
+    if (promptText && !ctx.ui?.getEditorText?.()) ctx.ui?.setEditorText?.(promptText);
+    announce(ctx, "pi-quick-cancel: rewound to before the prompt", "info");
+  };
+  pi.registerCommand("quick-cancel", {
+    description: "Rewind the chat to before the last prompt and return the prompt to the editor",
+    handler: (_args, ctx) => rewind(ctx)
+  });
+  pi.registerShortcut(key, {
+    description: "Rewind the chat to before the prompt (cancels the run)",
+    handler: () => pi.sendUserMessage("/quick-cancel", { expandPromptTemplates: true })
+  });
+}
+export {
+  registerQuickCancel as default
+};