@graelo/pi-defer-modal 0.1.0

package/README.md

@@ -0,0 +1,137 @@
+# pi-defer-modal
+
+A Pi extension that defers modal dialogs while you're typing, preventing interruptions to your workflow.
+
+## Problem
+
+When extensions display modal dialogs (using `ctx.ui.select()`, `ctx.ui.confirm()`, or `ctx.ui.input()`), these modals grab keyboard focus immediately. If you're in the middle of typing a message, the modal **interrupts your typing** — keystrokes land in the modal instead of the editor, breaking your train of thought.
+
+## Solution
+
+This extension intercepts modal calls from any extension and defers them until you pause typing or submit your input. The tool calls stay blocked (as they should), but the UI presentation is delayed until you're ready.
+
+## Features
+
+- **Non-interrupting modals**: Modals wait until you pause typing before appearing
+- **Configurable modal types**: Choose which modal types to defer (select, confirm, input)
+- **Adjustable timing**: Configure how long to wait after your last keystroke
+- **Safety ceiling**: Maximum deferral time prevents tools from hanging indefinitely
+- **Status indicator**: Optional visual indicator when modals are being deferred
+- **Works with any extension**: Transparently intercepts modals from all extensions
+
+## Installation
+
+### From npm (recommended)
+
+```bash
+pnpm add pi-defer-modal
+```
+
+### Manual installation
+
+1. Clone or download this repository
+2. Place the `pi-defer-modal` directory in one of Pi's extension locations:
+   - Project-local: `.pi/extensions/pi-defer-modal/`
+   - Global: `~/.pi/agent/extensions/pi-defer-modal/`
+
+## Configuration
+
+Create a `config.json` file in the extension directory:
+
+```json
+{
+  "enabled": true,
+  "modalTypes": ["select", "confirm", "input"],
+  "quietMs": 1500,
+  "maxDeferMs": 30000,
+  "showStatusIndicator": true,
+  "statusText": "⏸ modal pending — pause to review"
+}
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable or disable modal deferral |
+| `modalTypes` | string[] | `["select", "confirm", "input"]` | Which modal types to defer |
+| `quietMs` | number | `1500` | Milliseconds of inactivity before showing deferred modals |
+| `maxDeferMs` | number | `30000` | Maximum time to defer a modal (prevents hanging) |
+| `showStatusIndicator` | boolean | `true` | Show a status indicator when modals are deferred |
+| `statusText` | string | `"⏸ modal pending — pause to review"` | Text to show in the status indicator |
+
+### Configuration Locations
+
+The extension checks for configuration in these locations (in order of priority):
+
+1. Project-local: `.pi/extensions/pi-defer-modal/config.json`
+2. Global: `~/.pi/agent/extensions/pi-defer-modal/config.json`
+
+## Commands
+
+### `/defer-modal-toggle`
+
+Toggle modal deferral on or off.
+
+```text
+/defer-modal-toggle
+```
+
+### `/defer-modal-config`
+
+Show the current configuration.
+
+```text
+/defer-modal-config
+```
+
+### `/defer-modal-reload`
+
+Reload configuration from file (useful after editing config.json).
+
+```text
+/defer-modal-reload
+```
+
+## How It Works
+
+1. **Typing Tracking**: The extension subscribes to `ctx.ui.onTerminalInput` to track when you type
+2. **Modal Interception**: It wraps the UI methods (`select`, `confirm`, `input`) to intercept modal calls
+3. **Deferral Logic**: When a modal is called, if you're actively typing, the extension waits until:
+   - You pause typing for `quietMs` milliseconds, OR
+   - You submit your input (press Enter), OR
+   - The maximum deferral time (`maxDeferMs`) elapses
+4. **Status Indicator**: While waiting, an optional status message shows that modals are pending
+
+## Example Usage
+
+With this extension enabled:
+
+1. You start typing a command: `git commit -m "fix: ...`
+2. An extension (like pi-permission-system) tries to show a permission modal
+3. Instead of interrupting you, the modal waits
+4. You finish typing and pause for 1.5 seconds (default `quietMs`)
+5. The permission modal appears, ready for your input
+
+## Compatibility
+
+- Works with Pi v0.2.0 and later
+- Compatible with all extensions that use standard UI modal methods
+- No changes required to existing extensions
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Type check
+pnpm run check
+
+# Build
+pnpm run build
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@graelo/pi-defer-modal",
+  "version": "0.1.0",
+  "description": "Defer modal dialogs while the user is typing to prevent interruption",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "build": "tsc",
+    "check": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typescript": "^6.0.3"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "extension",
+    "modal",
+    "dialog",
+    "typing",
+    "defer",
+    "non-interrupting"
+  ],
+  "author": "",
+  "license": "MIT"
+}

package/src/config.ts

@@ -0,0 +1,197 @@
+/**
+ * Configuration for the pi-defer-modal extension.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+/**
+ * Configuration options for modal deferral behavior.
+ */
+export interface DeferModalConfig {
+  /**
+   * Enable or disable modal deferral while typing.
+   * When false, modals appear immediately as normal.
+   */
+  enabled: boolean;
+
+  /**
+   * Modal types to defer while typing.
+   * Supported types: "select", "confirm", "input"
+   */
+  modalTypes: string[];
+
+  /**
+   * Idle gap in milliseconds with no keystrokes that counts as "paused typing".
+   * Once this gap elapses, deferred modals will appear.
+   * Default: 1500ms
+   */
+  quietMs: number;
+
+  /**
+   * Maximum total deferral time in milliseconds.
+   * The modal will appear after this time even if the user never stops typing.
+   * This prevents "block the tool" from becoming "hang the tool".
+   * Default: 30000ms (30 seconds)
+   */
+  maxDeferMs: number;
+
+  /**
+   * Show a status indicator when modals are being deferred.
+   * Default: true
+   */
+  showStatusIndicator: boolean;
+
+  /**
+   * Custom status text to show when modals are being deferred.
+   * Default: "⏸ modal pending — pause to review"
+   */
+  statusText: string;
+}
+
+/**
+ * Default configuration values.
+ */
+export const DEFAULT_CONFIG: DeferModalConfig = {
+  enabled: false,
+  modalTypes: ["select", "confirm", "input"],
+  quietMs: 1500,
+  maxDeferMs: 30_000,
+  showStatusIndicator: true,
+  statusText: "⏸ modal pending — pause to review",
+};
+
+/**
+ * Extension ID for this extension.
+ */
+export const EXTENSION_ID = "pi-defer-modal";
+
+/**
+ * Status key for the pending modal indicator.
+ */
+export const STATUS_KEY = `${EXTENSION_ID}:modal-pending`;
+
+/**
+ * Configuration file name.
+ */
+export const CONFIG_FILENAME = "config.json";
+
+/**
+ * Configuration file locations to check, in order of priority.
+ * Later entries override earlier ones.
+ */
+function getConfigPaths(): string[] {
+  const paths: string[] = [];
+  
+  // 1. Project-local: .pi/extensions/pi-defer-modal/config.json
+  const projectPath = resolve(process.cwd(), ".pi", "extensions", EXTENSION_ID, CONFIG_FILENAME);
+  paths.push(projectPath);
+  
+  // 2. Global: ~/.pi/agent/extensions/pi-defer-modal/config.json
+  const home = homedir() || process.env.HOME || "/";
+  const globalPath = resolve(home, ".pi", "agent", "extensions", EXTENSION_ID, CONFIG_FILENAME);
+  paths.push(globalPath);
+  
+  return paths;
+}
+
+/**
+ * Load configuration from file, merging with defaults.
+ * Later files override earlier ones.
+ */
+export function loadConfig(): DeferModalConfig {
+  const config: Partial<DeferModalConfig> = {};
+  const paths = getConfigPaths();
+  
+  // Load from all available config files, later ones override earlier
+  for (const configPath of paths) {
+    if (existsSync(configPath)) {
+      try {
+        const content = readFileSync(configPath, "utf-8");
+        const fileConfig = JSON.parse(content) as Partial<DeferModalConfig>;
+        // Merge: file config overrides current config
+        Object.assign(config, fileConfig);
+        console.info(`[${EXTENSION_ID}] Loaded config from ${configPath}`);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[${EXTENSION_ID}] Failed to load config from ${configPath}: ${msg}`);
+      }
+    }
+  }
+  
+  // Merge with defaults and return
+  return { ...DEFAULT_CONFIG, ...config };
+}
+
+/**
+ * Create a config reader that can be used by the typing tracker.
+ * This allows the config to be refreshed and read consistently.
+ */
+export class ConfigStore {
+  private config: DeferModalConfig;
+
+  constructor(initialConfig: Partial<DeferModalConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...initialConfig };
+  }
+
+  /**
+   * Get the current configuration.
+   */
+  current(): DeferModalConfig {
+    return { ...this.config };
+  }
+
+  /**
+   * Update the configuration.
+   */
+  update(newConfig: Partial<DeferModalConfig>): void {
+    this.config = { ...this.config, ...newConfig };
+  }
+  
+  /**
+   * Reload configuration from file.
+   */
+  reload(): void {
+    const loadedConfig = loadConfig();
+    this.config = loadedConfig;
+  }
+
+  /**
+   * Check if a specific modal type should be deferred.
+   */
+  shouldDeferModalType(modalType: string): boolean {
+    const config = this.current();
+    if (!config.enabled) return false;
+    return config.modalTypes.includes(modalType);
+  }
+
+  /**
+   * Get the quiet time in milliseconds.
+   */
+  getQuietMs(): number {
+    return this.current().quietMs;
+  }
+
+  /**
+   * Get the maximum defer time in milliseconds.
+   */
+  getMaxDeferMs(): number {
+    return this.current().maxDeferMs;
+  }
+
+  /**
+   * Check if status indicator should be shown.
+   */
+  shouldShowStatus(): boolean {
+    return this.current().showStatusIndicator;
+  }
+
+  /**
+   * Get the status text to display.
+   */
+  getStatusText(): string {
+    return this.current().statusText;
+  }
+}

package/src/index.ts

@@ -0,0 +1,228 @@
+/**
+ * pi-defer-modal extension
+ * 
+ * Defers modal dialogs (select, confirm, input) while the user is actively typing,
+ * preventing interruption of the user's workflow. Once the user pauses typing
+ * or submits their input, the deferred modals appear.
+ * 
+ * This extension works transparently with any other extension that uses
+ * ctx.ui.select(), ctx.ui.confirm(), or ctx.ui.input().
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionUIDialogOptions,
+} from "@earendil-works/pi-coding-agent";
+
+import { ConfigStore, DEFAULT_CONFIG, EXTENSION_ID, loadConfig } from "./config";
+import { TypingTracker } from "./typing-tracker";
+
+/**
+ * Types for the UI methods we'll wrap.
+ */
+type UISelect = (
+  title: string,
+  options: string[],
+  opts?: ExtensionUIDialogOptions,
+) => Promise<string | undefined>;
+type UIConfirm = (
+  title: string,
+  message: string,
+  opts?: ExtensionUIDialogOptions,
+) => Promise<boolean>;
+type UIInput = (
+  title: string,
+  placeholder?: string,
+  opts?: ExtensionUIDialogOptions,
+) => Promise<string | undefined>;
+
+/**
+ * Original UI methods that we'll wrap and restore.
+ */
+interface OriginalUIMethods {
+  select?: UISelect;
+  confirm?: UIConfirm;
+  input?: UIInput;
+}
+
+/**
+ * Wrapped UI methods that defer modals while typing.
+ */
+class DeferredUI {
+  private readonly original: OriginalUIMethods;
+  private readonly typingTracker: TypingTracker;
+  private readonly config: ConfigStore;
+
+  constructor(
+    original: OriginalUIMethods,
+    typingTracker: TypingTracker,
+    config: ConfigStore,
+  ) {
+    this.original = original;
+    this.typingTracker = typingTracker;
+    this.config = config;
+  }
+
+  /**
+   * Wrap the select method to defer while typing if configured.
+   */
+  async select(
+    title: string,
+    options: string[],
+    opts?: ExtensionUIDialogOptions,
+  ): Promise<string | undefined> {
+    if (this.shouldDefer("select")) {
+      await this.typingTracker.waitForQuiet();
+    }
+    return this.original.select?.(title, options, opts);
+  }
+
+  /**
+   * Wrap the confirm method to defer while typing if configured.
+   */
+  async confirm(
+    title: string,
+    message: string,
+    opts?: ExtensionUIDialogOptions,
+  ): Promise<boolean> {
+    if (this.shouldDefer("confirm")) {
+      await this.typingTracker.waitForQuiet();
+    }
+    // confirm should always return boolean, not undefined
+    return this.original.confirm?.(title, message, opts) ?? false;
+  }
+
+  /**
+   * Wrap the input method to defer while typing if configured.
+   */
+  async input(
+    title: string,
+    placeholder?: string,
+    opts?: ExtensionUIDialogOptions,
+  ): Promise<string | undefined> {
+    if (this.shouldDefer("input")) {
+      await this.typingTracker.waitForQuiet();
+    }
+    return this.original.input?.(title, placeholder, opts);
+  }
+
+  /**
+   * Check if a modal type should be deferred based on configuration.
+   */
+  private shouldDefer(modalType: string): boolean {
+    return this.config.shouldDeferModalType(modalType);
+  }
+}
+
+/**
+ * Main extension function.
+ * This extension intercepts UI modal calls and defers them while the user is typing.
+ */
+export default function piDeferModalExtension(pi: ExtensionAPI): void {
+  // Load configuration from file and create store
+  const loadedConfig = loadConfig();
+  const config = new ConfigStore(loadedConfig);
+
+  // Create typing tracker
+  const typingTracker = new TypingTracker({ config });
+
+  // Store original UI methods
+  const originalUI: OriginalUIMethods = {};
+
+  // Flag to track if we've patched the UI
+  let isPatched = false;
+
+  // Patch the UI methods on session start
+  pi.on("session_start", (event, ctx) => {
+    if (isPatched) {
+      // Already patched - just update the tracker context
+      typingTracker.start(ctx);
+      return;
+    }
+
+    // Store original methods - we need to preserve the 'this' context
+    originalUI.select = ctx.ui.select?.bind(ctx.ui);
+    originalUI.confirm = ctx.ui.confirm?.bind(ctx.ui);
+    originalUI.input = ctx.ui.input?.bind(ctx.ui);
+
+    // Create deferred UI wrapper
+    const deferredUI = new DeferredUI(originalUI, typingTracker, config);
+
+    // Replace the UI methods with our wrapped versions
+    ctx.ui.select = deferredUI.select.bind(deferredUI);
+    ctx.ui.confirm = deferredUI.confirm.bind(deferredUI);
+    ctx.ui.input = deferredUI.input.bind(deferredUI);
+
+    isPatched = true;
+    typingTracker.start(ctx);
+
+    console.info(`[${EXTENSION_ID}] Modal deferral extension activated`);
+  });
+
+  // Clean up on session shutdown
+  pi.on("session_shutdown", () => {
+    typingTracker.stop();
+    isPatched = false;
+    console.info(`[${EXTENSION_ID}] Modal deferral extension deactivated`);
+  });
+
+  // Notify the tracker when user submits input
+  pi.on("input", (event, ctx) => {
+    typingTracker.notifySubmit();
+  });
+
+  // For now, we'll use a simple configuration approach.
+  // In a production extension, you might want to:
+  // 1. Load config from a config file
+  // 2. Provide a command to update config
+  // 3. Watch for config file changes
+  
+  // Register a command to toggle the extension
+  pi.registerCommand("defer-modal-toggle", {
+    description: "Toggle modal deferral on/off",
+    handler: async (args: string, ctx: ExtensionContext) => {
+      const currentConfig = config.current();
+      config.update({ enabled: !currentConfig.enabled }); 
+      const newConfig = config.current();
+      console.info(
+        `[${EXTENSION_ID}] Modal deferral ${newConfig.enabled ? "enabled" : "disabled"}`,
+      );
+      await ctx.ui.notify(
+        `Modal deferral is now ${newConfig.enabled ? "enabled" : "disabled"}.`
+      );
+    },
+  });
+
+  // Register a command to show current config
+  pi.registerCommand("defer-modal-config", {
+    description: "Show current modal deferral configuration",
+    handler: async (args: string, ctx: ExtensionContext) => {
+      const currentConfig = config.current();
+      await ctx.ui.notify(
+        `Modal deferral config:\n` +
+        `  Enabled: ${currentConfig.enabled}\n` +
+        `  Modal types: ${currentConfig.modalTypes.join(", ")}\n` +
+        `  Quiet time: ${currentConfig.quietMs}ms\n` +
+        `  Max defer: ${currentConfig.maxDeferMs}ms\n` +
+        `  Show status: ${currentConfig.showStatusIndicator}\n` +
+        `  Status text: "${currentConfig.statusText}"`
+      );
+    },
+  });
+
+  // Register a command to reload config from file
+  pi.registerCommand("defer-modal-reload", {
+    description: "Reload modal deferral configuration from file",
+    handler: async (args: string, ctx: ExtensionContext) => {
+      config.reload();
+      const currentConfig = config.current();
+      console.info(`[${EXTENSION_ID}] Configuration reloaded from file`);
+      await ctx.ui.notify(
+        `Configuration reloaded:\n` +
+        `  Enabled: ${currentConfig.enabled}\n` +
+        `  Quiet time: ${currentConfig.quietMs}ms`
+      );
+    },
+  });
+}

package/src/typing-tracker.ts

@@ -0,0 +1,163 @@
+/**
+ * TypingTracker - tracks user typing activity to defer modals appropriately.
+ * 
+ * This is a generic version that can be used to defer any modal dialog,
+ * not just permission prompts.
+ */
+
+import type {
+  ExtensionContext,
+  ExtensionUIContext,
+  TerminalInputHandler,
+} from "@earendil-works/pi-coding-agent";
+
+import { ConfigStore, STATUS_KEY } from "./config";
+
+/**
+ * Poll granularity (ms) for the debounce loop.
+ */
+const POLL_INTERVAL_MS = 50;
+
+/**
+ * Narrow UI surface the tracker needs; the real `ctx.ui` satisfies it.
+ */
+type TrackerUi = Partial<
+  Pick<ExtensionUIContext, "onTerminalInput" | "getEditorText" | "setStatus">
+>;
+
+/**
+ * Narrow ctx surface the tracker needs; the real `ctx` satisfies it.
+ */
+type TrackerCtx = Pick<ExtensionContext, "mode"> & { ui: TrackerUi };
+
+/**
+ * Dependencies for the TypingTracker.
+ */
+export interface TypingTrackerDeps {
+  config: ConfigStore;
+  /** Clock source; injectable for deterministic tests. Defaults to `Date.now`. */
+  now?: () => number;
+  /** Sleep; injectable for deterministic tests. Defaults to a `setTimeout` wait. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+/**
+ * Tracks recent keyboard activity for one session and gates modal display
+ * behind a "wait for the user to pause" debounce.
+ *
+ * Lifecycle: `start(ctx)` on session start (idempotent — re-entry drops the prior
+ * subscription, since `session_start` also fires on reload), `stop()` on shutdown.
+ * `notifySubmit()` is called from the `input` handler so submitting resolves any
+ * in-flight wait immediately.
+ */
+export class TypingTracker {
+  private readonly config: ConfigStore;
+  private readonly now: () => number;
+  private readonly sleep: (ms: number) => Promise<void>;
+  private ctx: TrackerCtx | null = null;
+  private unsubscribe: (() => void) | null = null;
+  private lastInputAt = 0;
+  private submitted = false;
+
+  constructor(deps: TypingTrackerDeps) {
+    this.config = deps.config;
+    this.now = deps.now ?? Date.now;
+    this.sleep =
+      deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  }
+
+  /**
+   * Subscribe to terminal input for `ctx`. Idempotent: drops any prior
+   * subscription first. Only subscribes in the interactive TUI; in other modes
+   * the ctx is stored but `waitForQuiet()` short-circuits.
+   */
+  start(ctx: TrackerCtx): void {
+    this.stop();
+    this.ctx = ctx;
+    if (ctx.mode !== "tui") return;
+    const onTerminalInput = ctx.ui.onTerminalInput;
+    if (typeof onTerminalInput !== "function") return;
+    const handler: TerminalInputHandler = () => {
+      this.lastInputAt = this.now();
+      return undefined; // observe only — never consume the keystroke
+    };
+    this.unsubscribe = onTerminalInput.call(ctx.ui, handler);
+  }
+
+  /**
+   * Unsubscribe from terminal input and clear the stored ctx.
+   */
+  stop(): void {
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = null;
+    }
+    this.ctx = null;
+  }
+
+  /**
+   * Resolve any in-flight wait immediately — the user submitted their input.
+   */
+  notifySubmit(): void {
+    this.submitted = true;
+  }
+
+  /**
+   * Resolve once the user has paused typing (or submitted), so a deferred modal
+   * does not interrupt active composition.
+   *
+   * Resolves immediately when deferral is disabled, outside the TUI, when the
+   * editor is empty (nothing to protect), or when typing already stopped longer
+   * ago than the quiet gap.
+   */
+  async waitForQuiet(): Promise<void> {
+    const config = this.config.current();
+    if (!config.enabled) return;
+
+    const ctx = this.ctx;
+    if (ctx?.mode !== "tui") return;
+    if (this.isEditorEmpty(ctx)) return;
+
+    const quietMs = config.quietMs;
+    if (this.now() - this.lastInputAt >= quietMs) return;
+
+    this.takeSubmitted(); // clear any stale submit from a prior wait
+    const startedAt = this.now();
+    
+    if (config.showStatusIndicator) {
+      this.setPendingStatus(ctx, config.statusText);
+    }
+    
+    try {
+      for (;;) {
+        if (this.takeSubmitted()) return;
+        if (this.isEditorEmpty(ctx)) return;
+        const sinceInput = this.now() - this.lastInputAt;
+        if (sinceInput >= quietMs) return;
+        if (this.now() - startedAt >= config.maxDeferMs) return;
+        await this.sleep(Math.min(quietMs - sinceInput, POLL_INTERVAL_MS));
+      }
+    } finally {
+      this.setPendingStatus(ctx, undefined);
+    }
+  }
+
+  /**
+   * Read and clear the submit flag in one step.
+   */
+  private takeSubmitted(): boolean {
+    const submitted = this.submitted;
+    this.submitted = false;
+    return submitted;
+  }
+
+  private isEditorEmpty(ctx: TrackerCtx): boolean {
+    const getEditorText = ctx.ui.getEditorText;
+    if (typeof getEditorText !== "function") return false;
+    return getEditorText.call(ctx.ui).trim().length === 0;
+  }
+
+  private setPendingStatus(ctx: TrackerCtx, text: string | undefined): void {
+    ctx.ui.setStatus?.(STATUS_KEY, text);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}