wezterm-pi-helper 1.0.0

package/README.md

@@ -0,0 +1,46 @@
+# wezterm-pi-helper
+
+Fixes WezTerm keyboard issues when running [pi](https://github.com/mariozechner/pi) on WSL2.
+
+## Problem
+
+WezTerm on WSL2 for Windows has a bug where Kitty keyboard protocol flag 4 ("report alternate keys") causes shifted keys (capitals, @, #, $, etc.) to not be sent at all. This makes typing very inpractical.
+
+## Solution
+
+This extension monkey-patches pi's terminal handling to use Kitty protocol flag 3 instead of 7 when running in WezTerm, avoiding the buggy flag 4.
+
+## Installation
+
+```bash
+cd ~/.pi/agent/extensions
+npm install wezterm-pi-helper
+```
+
+Or add to your `~/.pi/agent/extensions/package.json`:
+
+```json
+{
+  "dependencies": {
+    "wezterm-pi-helper": "^1.0.0"
+  }
+}
+```
+
+Then run `npm install`.
+
+## How it works
+
+The extension detects WezTerm via the `TERM_PROGRAM` environment variable. When detected, it overrides `ProcessTerminal.prototype.setupStdinBuffer` to use Kitty keyboard protocol flags 1+2 (value 3) instead of 1+2+4 (value 7).
+
+- Flag 1: Disambiguate escape codes
+- Flag 2: Report event types (press/repeat/release)
+- Flag 4: Report alternate keys (causes the bug in WezTerm on WSL2)
+
+## Why tmux works without this patch
+
+If you've noticed pi works fine in tmux on WezTerm, that's because tmux intercepts the Kitty protocol query and handles keyboard input itself, masking the buggy WezTerm behavior.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "wezterm-pi-helper",
+  "version": "1.0.0",
+  "description": "Fixes WezTerm keyboard issues on WSL2",
+  "main": "./src/index.ts",
+  "type": "module",
+  "files": ["src"],
+  "keywords": ["pi-extension", "wezterm", "wsl2"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://git.sr.ht/~manelvf/wezterm-pi-helper"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  },
+  "pi": {
+    "extensions": ["./src/index.ts"]
+  }
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { ProcessTerminal, StdinBuffer, setKittyProtocolActive } from "@mariozechner/pi-tui";
+
+export default function (pi: ExtensionAPI) {
+	const isWezTerm = process.env.TERM_PROGRAM === "WezTerm";
+	if (!isWezTerm) return;
+
+	// Monkey-patch setupStdinBuffer to use WezTerm-compatible Kitty flags
+	// TypeScript's 'private' is not enforced at runtime
+	(ProcessTerminal.prototype as any).setupStdinBuffer = function (this: any): void {
+		this.stdinBuffer = new StdinBuffer({ timeout: 10 });
+
+		const kittyResponsePattern = /^\x1b\[\?(\d+)u$/;
+
+		this.stdinBuffer.on("data", (sequence: string) => {
+			if (!this._kittyProtocolActive) {
+				const match = sequence.match(kittyResponsePattern);
+				if (match) {
+					this._kittyProtocolActive = true;
+					setKittyProtocolActive(true);
+
+					// WezTerm fix: use flag 3 instead of 7
+					// Flag 4 causes shifted keys to not be sent in WezTerm on WSL2
+					process.stdout.write("\x1b[>3u");
+					return;
+				}
+			}
+
+			if (this.inputHandler) {
+				this.inputHandler(sequence);
+			}
+		});
+
+		this.stdinBuffer.on("paste", (content: string) => {
+			if (this.inputHandler) {
+				this.inputHandler(`\x1b[200~${content}\x1b[201~`);
+			}
+		});
+
+		this.stdinDataHandler = (data: string) => {
+			this.stdinBuffer!.process(data);
+		};
+	};
+}