@foxfirecodes/pi-alerts 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @foxfirecodes/pi-alerts
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial package with terminal bell alerts for agent completion and extension UI prompts.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 foxfirecodes
+
+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,36 @@
+# pi-alerts
+
+Pi package that rings the terminal bell (`\a`) when pi needs your input.
+
+## Behavior
+
+- Rings when an agent turn ends and pi is ready for another prompt.
+- Rings before extension UI prompts such as `select`, `confirm`, `input`, `editor`, and `custom` dialogs. This covers permission prompts built with `ctx.ui.confirm()`.
+
+The bell is written directly to the attached terminal when one is available.
+
+## Install
+
+```bash
+pi install npm:@foxfirecodes/pi-alerts
+```
+
+## Development
+
+From this checkout:
+
+```bash
+pi install .
+```
+
+Or try it for one run:
+
+```bash
+pi -e /path/to/pi-extensions/packages/pi-alerts
+```
+
+To run automated tests:
+
+```bash
+pnpm test
+```

package/extensions/pi-alerts.js

@@ -0,0 +1,80 @@
+const BELL = "\x07";
+const UI_BELL_INSTALLED = Symbol.for("@foxfirecodes/pi-alerts.uiBellInstalled");
+const PROMPT_METHODS = ["select", "confirm", "input", "editor", "custom"];
+
+function defaultBellOutput() {
+  if (process.stdout?.isTTY) return process.stdout;
+  if (process.stderr?.isTTY) return process.stderr;
+  return undefined;
+}
+
+export function ringTerminalBell(output = defaultBellOutput()) {
+  if (!output) return false;
+  if ("isTTY" in output && output.isTTY === false) return false;
+
+  try {
+    output.write(BELL);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function promptOptions(methodName, args) {
+  if (
+    methodName === "select" ||
+    methodName === "confirm" ||
+    methodName === "input"
+  ) {
+    return args[2];
+  }
+
+  return undefined;
+}
+
+function promptAlreadyAborted(methodName, args) {
+  return Boolean(promptOptions(methodName, args)?.signal?.aborted);
+}
+
+export function installPromptBells(ui, ring = ringTerminalBell) {
+  if (!ui || ui[UI_BELL_INSTALLED]) return false;
+
+  let installed = false;
+
+  for (const methodName of PROMPT_METHODS) {
+    const original = ui[methodName];
+    if (typeof original !== "function") continue;
+
+    ui[methodName] = function promptBellWrapper(...args) {
+      if (!promptAlreadyAborted(methodName, args)) {
+        ring();
+      }
+
+      return original.apply(this, args);
+    };
+
+    installed = true;
+  }
+
+  if (installed) {
+    Object.defineProperty(ui, UI_BELL_INSTALLED, {
+      value: true,
+      enumerable: false,
+      configurable: true,
+    });
+  }
+
+  return installed;
+}
+
+export default function piAlerts(pi) {
+  pi.on("session_start", async (_event, ctx) => {
+    if (ctx.hasUI) installPromptBells(ctx.ui);
+  });
+
+  pi.on("agent_end", async (_event, ctx) => {
+    if (!ctx.hasUI || ctx.hasPendingMessages()) return;
+
+    ringTerminalBell();
+  });
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@foxfirecodes/pi-alerts",
+  "version": "0.1.0",
+  "description": "Pi extension that rings the terminal bell when pi needs your input.",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/foxfirecodes/pi-extensions.git",
+    "directory": "packages/pi-alerts"
+  },
+  "bugs": {
+    "url": "https://github.com/foxfirecodes/pi-extensions/issues"
+  },
+  "homepage": "https://github.com/foxfirecodes/pi-extensions/tree/main/packages/pi-alerts#readme",
+  "pi": {
+    "extensions": [
+      "./extensions/pi-alerts.js"
+    ]
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  }
+}

package/test/pi-alerts.test.js

@@ -0,0 +1,134 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import piAlerts, {
+  installPromptBells,
+  ringTerminalBell,
+} from "../extensions/pi-alerts.js";
+
+function createOutput({ isTTY = true } = {}) {
+  return {
+    isTTY,
+    chunks: [],
+    write(chunk) {
+      this.chunks.push(chunk);
+    },
+  };
+}
+
+test("exports a pi extension", () => {
+  assert.equal(typeof piAlerts, "function");
+});
+
+test("registers session and agent-end handlers", () => {
+  const handlers = new Map();
+  const pi = {
+    on(eventName, handler) {
+      handlers.set(eventName, handler);
+    },
+  };
+
+  piAlerts(pi);
+
+  assert.equal(typeof handlers.get("session_start"), "function");
+  assert.equal(typeof handlers.get("agent_end"), "function");
+});
+
+test("ringTerminalBell writes a bell to TTY output", () => {
+  const output = createOutput();
+
+  assert.equal(ringTerminalBell(output), true);
+  assert.deepEqual(output.chunks, ["\x07"]);
+});
+
+test("ringTerminalBell skips non-TTY output", () => {
+  const output = createOutput({ isTTY: false });
+
+  assert.equal(ringTerminalBell(output), false);
+  assert.deepEqual(output.chunks, []);
+});
+
+test("installPromptBells rings before extension UI prompts", async () => {
+  const calls = [];
+  const ui = {
+    async select(title) {
+      calls.push(["select", title]);
+      return "selected";
+    },
+    async confirm(title, message) {
+      calls.push(["confirm", title, message]);
+      return true;
+    },
+    async input(title, placeholder) {
+      calls.push(["input", title, placeholder]);
+      return "typed";
+    },
+    async editor(title, prefill) {
+      calls.push(["editor", title, prefill]);
+      return "edited";
+    },
+    async custom() {
+      calls.push(["custom"]);
+      return "custom-result";
+    },
+  };
+  let bells = 0;
+
+  assert.equal(
+    installPromptBells(ui, () => bells++),
+    true,
+  );
+
+  assert.equal(await ui.select("Choose"), "selected");
+  assert.equal(await ui.confirm("Allow?", "Run it?"), true);
+  assert.equal(await ui.input("Name", "placeholder"), "typed");
+  assert.equal(await ui.editor("Edit", "prefill"), "edited");
+  assert.equal(await ui.custom(), "custom-result");
+
+  assert.equal(bells, 5);
+  assert.deepEqual(calls, [
+    ["select", "Choose"],
+    ["confirm", "Allow?", "Run it?"],
+    ["input", "Name", "placeholder"],
+    ["editor", "Edit", "prefill"],
+    ["custom"],
+  ]);
+});
+
+test("installPromptBells is idempotent for the same UI context", async () => {
+  const ui = {
+    async confirm() {
+      return true;
+    },
+  };
+  let bells = 0;
+
+  assert.equal(
+    installPromptBells(ui, () => bells++),
+    true,
+  );
+  assert.equal(
+    installPromptBells(ui, () => bells++),
+    false,
+  );
+
+  await ui.confirm("Allow?", "Run it?");
+
+  assert.equal(bells, 1);
+});
+
+test("installPromptBells skips prompts whose signal is already aborted", async () => {
+  const ui = {
+    async select() {
+      return undefined;
+    },
+  };
+  const controller = new AbortController();
+  controller.abort();
+  let bells = 0;
+
+  installPromptBells(ui, () => bells++);
+  await ui.select("Choose", ["A"], { signal: controller.signal });
+
+  assert.equal(bells, 0);
+});