pi-focus-bell 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thmtz
+
+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, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# pi-focus-bell
+
+Rings your terminal bell when a [pi](https://github.com/earendil-works/pi) session finishes and is waiting on you. Leave a session running, go do something else, and get pulled back the moment it needs input instead of babysitting it.
+
+The core behavior is simple: on `agent_end` (pi has finished a turn and is idle), it emits a terminal bell (`BEL`, `\a`).
+
+On top of that it is tmux-aware. If the pane running the session is the one you are already looking at, there is nothing to alert you to, so it stays quiet. It only rings when that pane is out of focus. Outside tmux, where focus can't be determined, it rings on every turn end.
+
+## Why a bell instead of a desktop notification?
+
+The bell isn't just cosmetic. A raw `BEL` propagates through the whole stack: tmux forwards it (`bell-action any`, `visual-bell off`) up the ssh session to the outer terminal, which turns it into audio. One bell covers the local-terminal, tmux, and remote-over-ssh cases with no per-hop config, and works even where no notification daemon exists. (pi's bundled `notify.ts` example takes the other route: OSC desktop notifications, fired on every turn regardless of focus.)
+
+## Install
+
+```bash
+pi install npm:pi-focus-bell
+```
+
+Or drop `focus-bell.ts` directly into your global extensions directory (`~/.pi/agent/extensions/`), which pi auto-loads.
+
+## Requirements for the audio relay
+
+The extension only emits the `BEL`. For it to become an audible sound over tmux + ssh, the outer layers must be configured to carry and play it:
+
+**tmux** (`.tmux.conf`):
+
+```
+set -g bell-action any
+set -g visual-bell off
+setw -g monitor-bell on
+```
+
+`visual-bell off` matters: with it on, tmux swallows the audible bell and only flashes the status line.
+
+**Your terminal** must play a sound on `BEL`. For example, Ghostty:
+
+```
+bell-features = audio
+bell-audio-path = /System/Library/Sounds/Funk.aiff
+bell-audio-volume = 0.8
+```
+
+## Configuration
+
+Two optional environment variables:
+
+- `PI_BELL_ALWAYS`: if set, skip focus gating and ring on every turn end, even when you're looking at pi's pane.
+- `PI_BELL_DEBUG`: if set to a file path, append one line per event describing what the extension decided (rang, gated, or failed). Handy for answering "is it even firing?"
+
+```bash
+PI_BELL_DEBUG=/tmp/pi-bell.log pi
+```
+
+## Testing it
+
+The bell only rings when pi's pane is unfocused, so you have to switch away before the turn ends:
+
+1. Start `pi` in a tmux pane.
+2. Give it a prompt that takes a few seconds and hit Enter.
+3. Immediately switch to another tmux pane or window.
+4. When pi finishes, the terminal should ring.
+
+If it stays silent while you are looking at pi's pane, that's the focus gate working as intended.
+
+## Known limitations
+
+pi computes an internal `willRetry` flag when a turn ends but does not currently expose it to extension events. So when pi hits a transient error (e.g. a 429) and is about to auto-retry, this extension can't tell that apart from a turn that's genuinely waiting on you, and may ring once during the retry backoff. The clean fix is upstream: pi exposing `willRetry` on the extension `agent_end` event.
+
+## License
+
+MIT

package/focus-bell.ts

@@ -0,0 +1,123 @@
+/**
+ * pi-focus-bell — ring the terminal bell (BEL, \a) when pi finishes a turn and
+ * is waiting on you, staying quiet when you're already looking at its pane.
+ *
+ * Why a bell and not a desktop notification (cf. the bundled notify.ts example)?
+ * A raw BEL propagates through the whole stack: tmux (bell-action any,
+ * visual-bell off) forwards it up the ssh session to the outer terminal, which
+ * plays audio natively (e.g. Ghostty's `bell-features = audio`). So one BEL
+ * covers the local-terminal, tmux, and remote-over-ssh cases with no per-hop
+ * config, and works even when there's no desktop-notification daemon.
+ *
+ * Focus gating: inside tmux we only ring when pi's own pane is NOT the active
+ * pane of the active window, so it doesn't ping while you're watching it.
+ * Outside tmux we can't cheaply know focus, so we always ring.
+ *
+ * The BEL is written straight to the pane's slave tty (resolved via tmux),
+ * bypassing pi's TUI render buffer, with /dev/tty as a fallback.
+ *
+ * Environment:
+ *   PI_BELL_ALWAYS  if set, skip focus gating and always ring on turn end.
+ *   PI_BELL_DEBUG   if set to a file path, append a line per event describing
+ *                   what the extension decided (rang, gated, failed).
+ */
+import { execFileSync } from "node:child_process";
+import { openSync, writeSync, closeSync, appendFileSync } from "node:fs";
+
+const ALWAYS = !!process.env.PI_BELL_ALWAYS;
+const DEBUG_PATH = process.env.PI_BELL_DEBUG;
+
+function debug(msg: string): void {
+  if (!DEBUG_PATH) return;
+  try {
+    appendFileSync(DEBUG_PATH, `[${new Date().toISOString()}] ${msg}\n`);
+  } catch {
+    // Debug logging is best-effort; never let it disrupt the agent.
+  }
+}
+
+function tmux(args: string[]): string | undefined {
+  try {
+    return execFileSync("tmux", args, { encoding: "utf-8" }).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/** Active pane id of the active window, or undefined if not resolvable. */
+function activePaneId(): string | undefined {
+  const out = tmux([
+    "list-panes",
+    "-s",
+    "-F",
+    "#{?pane_active,#{?window_active,#{pane_id},},}",
+  ]);
+  const id = out?.replace(/\s+/g, "");
+  return id ? id : undefined;
+}
+
+/** Write a single BEL to `path`, returning true on success. */
+function writeBel(path: string): boolean {
+  try {
+    const fd = openSync(path, "a");
+    try {
+      writeSync(fd, "\x07");
+    } finally {
+      closeSync(fd);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function ringBell(): void {
+  const pane = process.env.TMUX_PANE;
+
+  // Not in tmux: ring on the controlling tty unconditionally.
+  if (!process.env.TMUX || !pane) {
+    debug("not in tmux; ringing /dev/tty");
+    writeBel("/dev/tty");
+    return;
+  }
+
+  if (!ALWAYS) {
+    // Only ring when we can confirm our pane isn't the focused one. Fail closed:
+    // if focus can't be resolved (tmux hiccup, stale $TMUX), stay silent rather
+    // than risk ringing the pane you're already watching.
+    const active = activePaneId();
+    if (!active) {
+      debug(`focus unresolved; staying silent (pane=${pane})`);
+      return;
+    }
+    if (pane === active) {
+      debug(`pane ${pane} is focused; not ringing`);
+      return;
+    }
+    debug(`pane ${pane} unfocused (active=${active}); ringing`);
+  } else {
+    debug(`PI_BELL_ALWAYS set; ringing pane ${pane} regardless of focus`);
+  }
+
+  const paneTty = tmux(["display-message", "-p", "-t", pane, "#{pane_tty}"]);
+  if (!paneTty || !writeBel(paneTty)) {
+    debug(`pane tty unwritable (${paneTty ?? "unresolved"}); falling back to /dev/tty`);
+    writeBel("/dev/tty");
+  } else {
+    debug(`BEL -> ${paneTty}`);
+  }
+}
+
+export default function (pi: any) {
+  pi.on("agent_end", async (_event: unknown, ctx: any) => {
+    // Only meaningful when attached to a terminal.
+    if (ctx?.mode && ctx.mode !== "tui") return;
+    // NOTE: pi computes a `willRetry` flag on agent_end but does not currently
+    // pass it to extension events, so we can't distinguish a "waiting for you"
+    // completion from one pi is about to auto-retry after a transient error.
+    // Worst case is one extra bell during a retry backoff. A clean fix needs pi
+    // to expose `willRetry` on the extension AgentEndEvent.
+    debug("agent_end");
+    ringBell();
+  });
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "pi-focus-bell",
+  "version": "0.1.0",
+  "description": "Rings the terminal bell when a pi session finishes and is waiting on you, staying quiet when you're already looking at its tmux pane.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "extension",
+    "terminal",
+    "bell",
+    "notification",
+    "tmux"
+  ],
+  "files": [
+    "focus-bell.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thmtz/pi-focus-bell.git"
+  },
+  "pi": {
+    "extensions": [
+      "./focus-bell.ts"
+    ]
+  }
+}