pi-double-esc 1.0.1

package/README.md

@@ -0,0 +1,102 @@
+<div align="center">
+
+# ⏏️ pi-double-esc
+
+**Prevent accidental Escape aborts in [pi](https://github.com/earendil-works/pi-coding-agent)**
+
+_Require a second Escape press within 500ms to confirm any abort action._
+
+[![pi extension](https://img.shields.io/badge/pi-extension-blueviolet)](https://github.com/earendil-works/pi-coding-agent)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+<img alt="double-esc hint" src="./media/esc.jpg" width="800">
+
+</div>
+
+---
+
+## What It Does
+
+When the LLM is streaming a response:
+
+- **First Escape press**: Shows an `esc again to abort` hint on the editor border — does **not** abort
+- **Second Escape** within the debounce window: Actually aborts the streaming response
+- If the debounce window expires, the hint clears and escape resets
+
+When the LLM is **not** streaming, Escape works normally (immediate) — no debounce applied. Autocomplete dismissal always works on a single Escape.
+
+## Installation
+
+### Option 1: Install via pi package (Recommended)
+
+Install directly from GitHub as a pi package:
+
+```bash
+pi install https://github.com/monotykamary/pi-double-esc@main
+```
+
+Or add to your `settings.json`:
+
+```json
+{
+  "packages": [
+    "https://github.com/monotykamary/pi-double-esc@main"
+  ]
+}
+```
+
+### Option 2: Global Installation
+
+Copy the extension to pi's global extensions directory:
+
+```bash
+cp double-esc.ts ~/.pi/agent/extensions/
+```
+
+### Option 3: Project-Local Installation
+
+Copy to your project's `.pi/extensions/` directory:
+
+```bash
+mkdir -p .pi/extensions
+cp double-esc.ts .pi/extensions/
+```
+
+### Option 4: Quick Test
+
+```bash
+pi -e ./double-esc.ts
+```
+
+## Configuration
+
+Set the `PI_DOUBLE_ESC_MS` environment variable to change the debounce timeout (default: 1500ms):
+
+```bash
+PI_DOUBLE_ESC_MS=2000 pi
+```
+
+## How It Works
+
+The extension replaces pi's editor component with a `CustomEditor` subclass that intercepts Escape key presses:
+
+1. On each `session_start`, `ctx.ui.setEditorComponent()` installs the custom editor
+2. The editor uses `ctx.isIdle()` (which reflects `!session.isStreaming`) to detect streaming state
+3. While streaming, the first Escape shows a visual hint and starts a debounce timer
+4. A second Escape within the window calls `super.handleInput(data)` to perform the actual abort
+5. Any other keypress or timeout expiry dismisses the hint
+
+The debounce logic lives in `src/double-esc-logic.ts` as pure functions for testability.
+
+## Development
+
+```bash
+npm install          # install dev dependencies
+npm test            # run tests
+npm run typecheck   # type check
+npm run lint:dead   # check for unused exports
+```
+
+## License
+
+MIT

package/double-esc.ts

@@ -0,0 +1,120 @@
+/**
+ * Double Escape Debounce — prevents accidental Escape from aborting the LLM
+ *
+ * Usage: pi --extension ./double-esc.ts
+ *
+ * When the LLM is streaming:
+ *   - First Escape press: shows "ESC AGAIN TO ABORT" hint in the editor border
+ *   - Second Escape within the debounce window: actually aborts streaming
+ *   - If the window expires, the hint clears and escape resets
+ *
+ * When not streaming:
+ *   - Escape works normally (immediate) — no debounce applied
+ *
+ * Autocomplete dismissal always works on single Escape (handled by Editor parent).
+ *
+ * The debounce timeout defaults to 1500ms and can be configured via
+ * the PI_DOUBLE_ESC_MS environment variable.
+ */
+
+import { CustomEditor, type ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth, visibleWidth, type TUI, type EditorTheme } from "@earendil-works/pi-tui";
+import {
+  createInitialState,
+  getDefaultDebounceMs,
+  handleEscape,
+  handleOtherKey,
+  handleTimeout,
+  type DoubleEscapeState,
+} from "./src/index.js";
+
+class DoubleEscapeEditor extends CustomEditor {
+  private escState: DoubleEscapeState = createInitialState();
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private isIdle: () => boolean;
+  private appTheme: Theme;
+
+  constructor(
+    tui: TUI,
+    editorTheme: EditorTheme,
+    keybindings: any,
+    theme: Theme,
+    isIdle: () => boolean,
+    options?: any,
+  ) {
+    super(tui, editorTheme, keybindings, options);
+    this.appTheme = theme;
+    this.isIdle = isIdle;
+  }
+
+  private clearDebounce(): void {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape")) {
+      const result = handleEscape(this.escState, this.isIdle());
+
+      this.escState = result.state;
+
+      if (result.action === "show_hint") {
+        this.clearDebounce();
+        this.debounceTimer = setTimeout(() => {
+          this.escState = handleTimeout(this.escState).state;
+          this.tui.requestRender();
+        }, getDefaultDebounceMs());
+        this.tui.requestRender();
+        return;
+      }
+
+      if (result.action === "abort") {
+        this.clearDebounce();
+        super.handleInput(data);
+        return;
+      }
+
+      // "nothing" — idle state, pass through
+      super.handleInput(data);
+      return;
+    }
+
+    // Non-escape key while hint is showing: dismiss hint
+    if (this.escState.hintActive) {
+      this.escState = handleOtherKey(this.escState).state;
+      this.clearDebounce();
+      this.tui.requestRender();
+    }
+
+    super.handleInput(data);
+  }
+
+  render(width: number): string[] {
+    const lines = super.render(width);
+    if (lines.length === 0) return lines;
+
+    if (this.escState.hintActive) {
+      const label = " esc again to abort ";
+      const styledLabel = this.appTheme.fg("dim", label);
+      const last = lines.length - 1;
+      const line = lines[last]!;
+      const lineW = visibleWidth(line);
+      const gap = 2;
+      if (lineW >= label.length + gap) {
+        lines[last] = truncateToWidth(line, lineW - label.length - gap, "") + styledLabel + truncateToWidth(line, gap, "");
+      }
+    }
+
+    return lines;
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", (_event, ctx) => {
+    ctx.ui.setEditorComponent((tui, editorTheme, kb) =>
+      new DoubleEscapeEditor(tui, editorTheme, kb, ctx.ui.theme, () => ctx.isIdle()),
+    );
+  });
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "pi-double-esc",
+  "version": "1.0.1",
+  "description": "Prevent accidental Escape from aborting the LLM \u2014 requires double-press to interrupt while streaming",
+  "type": "module",
+  "author": "Tom X Nguyen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/monotykamary/pi-double-esc.git"
+  },
+  "homepage": "https://github.com/monotykamary/pi-double-esc#readme",
+  "bugs": {
+    "url": "https://github.com/monotykamary/pi-double-esc/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "extension",
+    "escape",
+    "debounce",
+    "double-escape",
+    "interrupt",
+    "abort"
+  ],
+  "files": [
+    "*.ts",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint:dead": "knip --no-gitignore"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.79.4",
+    "@earendil-works/pi-tui": "0.79.4",
+    "@types/node": "25.9.1",
+    "@vitest/coverage-v8": "4.1.7",
+    "knip": "6.14.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.7"
+  },
+  "pi": {
+    "extensions": [
+      "./double-esc.ts"
+    ]
+  },
+  "overrides": {
+    "brace-expansion": "5.0.6"
+  },
+  "peerDependencies": {}
+}

package/src/double-esc-logic.ts

@@ -0,0 +1,102 @@
+/**
+ * Double-escape debounce logic — pure functions and state class for testing.
+ *
+ * The editor extension in double-esc.ts uses these building blocks.
+ * All state is encapsulated in DoubleEscapeState; the editor merely
+ * calls press() and clearOnOtherKey() and reads the resulting state.
+ */
+
+export interface DoubleEscapeState {
+  /** First escape has been pressed, waiting for confirmation */
+  hintActive: boolean;
+  /** Number of escapes in the current debounce window */
+  escapeCount: number;
+}
+
+export interface DoubleEscapeResult {
+  /** Updated state after the action */
+  state: DoubleEscapeState;
+  /** What the caller should do */
+  action: "show_hint" | "abort" | "nothing";
+}
+
+const DEFAULT_DEBOUNCE_MS = 1500;
+
+export function getDefaultDebounceMs(): number {
+  const env = process.env.PI_DOUBLE_ESC_MS;
+  if (env) {
+    const parsed = parseInt(env, 10);
+    if (!isNaN(parsed) && parsed > 0) return parsed;
+  }
+  return DEFAULT_DEBOUNCE_MS;
+}
+
+/**
+ * Handle an escape key press.
+ *
+ * @param currentState  Current debounce state
+ * @param isIdle        Whether the agent is idle (not streaming)
+ * @returns             Result with updated state and action
+ */
+export function handleEscape(
+  currentState: DoubleEscapeState,
+  isIdle: boolean,
+): DoubleEscapeResult {
+  // When idle and no hint is showing, pass through immediately
+  if (isIdle && !currentState.hintActive) {
+    return { state: currentState, action: "nothing" };
+  }
+
+  const newCount = currentState.escapeCount + 1;
+
+  if (newCount === 1) {
+    // First press: show hint, start debounce
+    return {
+      state: { hintActive: true, escapeCount: 1 },
+      action: "show_hint",
+    };
+  }
+
+  // Second+ press within window: abort
+  return {
+    state: { hintActive: false, escapeCount: 0 },
+    action: "abort",
+  };
+}
+
+/**
+ * Handle any non-escape key press while hint is showing.
+ * Dismisses the hint and resets the debounce state.
+ */
+export function handleOtherKey(currentState: DoubleEscapeState): DoubleEscapeResult {
+  if (!currentState.hintActive) {
+    return { state: currentState, action: "nothing" };
+  }
+
+  return {
+    state: { hintActive: false, escapeCount: 0 },
+    action: "nothing",
+  };
+}
+
+/**
+ * Handle debounce timeout expiry.
+ * Clears the hint and resets state.
+ */
+export function handleTimeout(currentState: DoubleEscapeState): DoubleEscapeResult {
+  if (!currentState.hintActive) {
+    return { state: currentState, action: "nothing" };
+  }
+
+  return {
+    state: { hintActive: false, escapeCount: 0 },
+    action: "nothing",
+  };
+}
+
+/**
+ * Create the initial state.
+ */
+export function createInitialState(): DoubleEscapeState {
+  return { hintActive: false, escapeCount: 0 };
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { handleEscape, handleOtherKey, handleTimeout, createInitialState, getDefaultDebounceMs } from "./double-esc-logic.js";
+export type { DoubleEscapeState, DoubleEscapeResult } from "./double-esc-logic.js";

package/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["__tests__/**/*.test.ts"],
+    exclude: ["node_modules", "dist", ".idea", ".git", ".cache"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html"],
+      exclude: ["node_modules/", "**/*.d.ts", "**/*.test.ts"],
+    },
+  },
+});