@fyeeme/pi-peon-ping 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [Unreleased]
+
+## [1.1.0] - 2026-07-26
+
+### Added
+
+- New lifecycle event mappings: `session_before_compact` → `PreCompact` (context compaction) and `tool_call` for `ask_user_question` → `PermissionRequest` (input required)
+- Category-aware event firing — reads peon-ping `config.json` and skips spawning `peon.sh` for events whose category is toggled off. New helpers: `EVENT_CATEGORY`, `resolveConfigPath`, `readPeonConfig`, `isCategoryEnabled`
+- `findPeonCli` / `execPeonCli` utility functions for CLI invocation of peon.sh
+- `peon-ping-toggle` and `peon-ping-use` commands
+
+### Changed
+
+- Map `UserPromptSubmit` and `Stop` to `before_agent_start` and `agent_end` (once per prompt) instead of `turn_start` / `turn_end` (once per turn), so the completion sound fires once per agent run rather than on every turn
+
 ## [1.0.0] - 2025-07-25
 
 ### Added

package/README.md

@@ -49,13 +49,30 @@ ln -s $(pwd)/packages/extensions/pi-peon-ping ~/.pi/agent/extensions/pi-peon-pin
 
 ## Event Mapping
 
-| pi event                     | peon-ping event        | Occurs when                     |
-|------------------------------|------------------------|---------------------------------|
-| `session_start`              | `SessionStart`         | Pi starts or resumes a session  |
-| `turn_start`                 | `UserPromptSubmit`     | You submit a prompt             |
-| `turn_end`                   | `Stop`                 | Agent finishes responding       |
-| `tool_result` (isError)      | `PostToolUseFailure`   | A tool call fails               |
-| `session_shutdown`           | `SessionEnd`           | Session ends                    |
+Each pi event is mapped to a peon-ping event, which peon-ping routes to a sound
+**category** — the keys under `categories` in `~/.openpeon/config.json`. Toggle a
+category off there to silence just that event without touching the others.
+
+| pi event | peon-ping event | category | Occurs when |
+|---|---|---|---|
+| `session_start` | `SessionStart` | `session.start` | Pi starts or resumes a session |
+| `before_agent_start` | `UserPromptSubmit` | `task.acknowledge` | You submit a prompt (once per agent run) |
+| `agent_end` | `Stop` | `task.complete` | An agent run finishes (once per prompt) |
+| `tool_result` (isError) | `PostToolUseFailure` | `task.error` | A tool call fails |
+| `tool_call` (`ask_user_question`) | `PermissionRequest` | `input.required` | Agent asks you a question |
+| `session_before_compact` | `PreCompact` | `resource.limit` | Context is about to be compacted |
+| `session_shutdown` | `SessionEnd` | — | Session ends (always fires) |
+
+> **Why `agent_end` / `before_agent_start` instead of `turn_*`?**
+> A single agent run spans multiple turns (e.g. several tool calls in a row).
+> Mapping `turn_end` → `Stop` would fire the completion sound on every turn;
+> `agent_end` fires once per prompt, which is what the completion sound should
+> mean. Same reasoning for `before_agent_start` vs `turn_start`.
+
+> **`input.required` needs the `ask_user_question` tool**, provided by an
+> extension such as [@juicesharp/rpiv-ask-user-question](https://github.com/juicesharp/rpiv-ask-user-question).
+> It listens for the `tool_call` event with `toolName === "ask_user_question"`.
+> Without such a tool installed, this category never fires.
 
 ## Configuration
 
@@ -67,18 +84,18 @@ ln -s $(pwd)/packages/extensions/pi-peon-ping ~/.pi/agent/extensions/pi-peon-pin
 
 ### peon.sh Discovery
 
-pi-peon-ping 自动查找已安装的 `peon.sh`，优先级如下（高 → 低）：
+pi-peon-ping auto-discovers the installed `peon.sh` with the following priority (high → low):
 
-| 优先级 | 来源 | 路径 |
-|--------|------|------|
-| 1 | `$PEON_SH` 环境变量 | 用户指定 |
+| Priority | Source | Path |
+|----------|--------|------|
+| 1 | `$PEON_SH` env var | User-specified |
 | 2 | Homebrew (macOS) | `$(brew --prefix peon-ping)/libexec/peon.sh` |
-| 3 | curl 安装 (Linux/macOS) | `~/.claude/hooks/peon-ping/peon.sh` |
-| 4 | `--openpeon` 模式 | `~/.openpeon/hooks/peon-ping/peon.sh` |
-| 5 | OpenClaw 安装 | `~/.openclaw/hooks/peon-ping/peon.sh` |
-| 6 | Windows/Git Bash WSL2 回退 | `~/.claude/hooks/peon-ping/peon.ps1` |
+| 3 | curl install (Linux/macOS) | `~/.claude/hooks/peon-ping/peon.sh` |
+| 4 | `--openpeon` mode | `~/.openpeon/hooks/peon-ping/peon.sh` |
+| 5 | OpenClaw install | `~/.openclaw/hooks/peon-ping/peon.sh` |
+| 6 | Windows/Git Bash WSL2 fallback | `~/.claude/hooks/peon-ping/peon.ps1` |
 
-当找到 `.ps1` 文件时，自动使用 `powershell` 而非 `bash` 执行。
+When a `.ps1` file is found, it is automatically run with `powershell` instead of `bash`.
 
 ### peon-ping 配置
 
@@ -89,6 +106,7 @@ peon packs use glados          # Switch sound pack
 peon packs install --all       # Install all packs
 peon trainer on                # Enable trainer mode
 peon notifications off         # Mute popups but keep sounds
+peon mute                      # Mute all sounds (toggle back with `peon toggle`)
 peon mobile ntfy my-topic      # Push notifications to phone
 peon ssh-audio relay           # Route audio for remote sessions
 ```
@@ -103,7 +121,7 @@ rm -rf ~/.pi/agent/extensions/pi-peon-ping
 
 This is a thin adapter — it does not play sounds or send notifications directly. Instead, it finds `peon.sh` (from the peon-ping install) and spawns it with a JSON payload on each lifecycle event. `peon.sh` handles all sound selection, playback, notifications, and trainer logic.
 
-The tab title is updated to reflect current agent state: `● working...` during a turn, `✓ done` on completion, `✗ error` on tool failures.
+The tab title reflects agent state: `● working...` when an agent run starts, `✓ done` when it finishes, `✗ error` on tool failures.
 
 ## Credits
 

package/index.ts

@@ -35,9 +35,9 @@
  */
 
 import { spawn, execFileSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
-import { basename, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 // ============================================================================
@@ -153,16 +153,98 @@ export function getSessionId(ctx: ExtensionContext): string {
 	return `pi-${Date.now()}`;
 }
 
+// ============================================================================
+// Peon-ping config (categories)
+// ============================================================================
+
+/**
+ * Event → peon-ping category key mapping (mirrors peon.sh's routing).
+ * SessionEnd is intentionally unmapped so it always fires regardless of
+ * category toggles (peon.sh has no matching category for session teardown).
+ */
+export const EVENT_CATEGORY: Record<string, string> = {
+	SessionStart: "session.start",
+	UserPromptSubmit: "task.acknowledge",
+	Stop: "task.complete",
+	PostToolUseFailure: "task.error",
+	PreCompact: "resource.limit",
+	PermissionRequest: "input.required",
+};
+
+/**
+ * Resolve the peon-ping config.json path, following the same priority as
+ * peon.sh:
+ *   1. $PWD/.claude/hooks/peon-ping/config.json (project-local)
+ *   2. ~/.openpeon/config.json (user data dir)
+ *   3. $PEON_DIR/config.json (install-level)
+ */
+export function resolveConfigPath(peonPath: string): string | null {
+	// 1. Project-local config
+	const localCfg = join(process.cwd(), ".claude", "hooks", "peon-ping", "config.json");
+	if (existsSync(localCfg)) return localCfg;
+
+	// 2. ~/.openpeon/config.json
+	const openpeonCfg = join(homedir(), ".openpeon", "config.json");
+	if (existsSync(openpeonCfg)) return openpeonCfg;
+
+	// 3. Install-level (same directory as peon.sh)
+	const peonDir = dirname(peonPath);
+	const installCfg = join(peonDir, "config.json");
+	if (existsSync(installCfg)) return installCfg;
+
+	return null;
+}
+
+export interface PeonConfig {
+	categories?: Record<string, boolean>;
+}
+
+/**
+ * Read the peon-ping config.json and return the parsed object,
+ * or null if the config file cannot be read.
+ */
+export function readPeonConfig(peonPath: string): PeonConfig | null {
+	const cfgPath = resolveConfigPath(peonPath);
+	if (!cfgPath) return null;
+	try {
+		return JSON.parse(readFileSync(cfgPath, "utf-8")) as PeonConfig;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Check whether a peon-ping category is enabled in the config.
+ * If no config is found, returns true (allow — mimic peon.sh default).
+ */
+export function isCategoryEnabled(config: PeonConfig | null, category: string): boolean {
+	if (!config?.categories) return true;
+	const val = config.categories[category];
+	// peon.sh defaults: task.acknowledge → false, everything else → true
+	if (val === undefined) return category !== "task.acknowledge";
+	return val === true;
+}
+
 // ============================================================================
 // peon.sh invocation
 // ============================================================================
 
+/**
+ * Fire a peon-ping event. Spawns peon.sh with the given hook_event_name,
+ * but only if the corresponding category is enabled in the peon-ping config.
+ * This avoids spawning a process for suppressed events.
+ */
 export function firePeon(
 	peonPath: string,
 	event: string,
 	cwd: string,
 	sessionId: string,
+	config?: PeonConfig | null,
 ): void {
+	const category = EVENT_CATEGORY[event];
+	const enabled = !category || isCategoryEnabled(config ?? null, category);
+	if (!enabled) return;
+
 	const payload = JSON.stringify({
 		hook_event_name: event,
 		notification_type: "",
@@ -185,6 +267,35 @@ export function firePeon(
 	}
 }
 
+// ============================================================================
+// peon CLI invocation (for commands)
+// ============================================================================
+
+export function findPeonCli(peonPath?: string | null): string | null {
+	// peon.sh accepts CLI args too — just use it directly
+	return peonPath ?? findPeonSh();
+}
+
+export async function execPeonCli(
+	cliPath: string,
+	args: string[],
+): Promise<{ stdout: string; exitCode: number | null }> {
+	return new Promise((resolve) => {
+		const { shell, script } = resolveShellAndScript(cliPath);
+		const proc = spawn(shell, [script, ...args], {
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		let stdout = "";
+		proc.stdout?.on("data", (chunk: Buffer) => { stdout += chunk.toString(); });
+
+		proc.on("close", (code) => {
+			resolve({ stdout: stdout.trim(), exitCode: code });
+		});
+		proc.on("error", () => resolve({ stdout: "", exitCode: -1 }));
+	});
+}
+
 // ============================================================================
 // Extension
 // ============================================================================
@@ -199,36 +310,98 @@ export default function peonPingExtension(pi: ExtensionAPI): void {
 		return;
 	}
 
+	const cliPath = findPeonCli(peonPath);
 	const cwd = process.cwd();
 	const projectName = basename(cwd) || "pi";
 
+	// -----------------------------------------------------------------------
+	// Lifecycle event forwarding (respect peon-ping category toggles)
+	// Config is re-read on each event so runtime category changes (via
+	// `peon notifications`) take effect without a pi restart.
+	// -----------------------------------------------------------------------
+
 	pi.on("session_start", async (_event, ctx) => {
+		const config = readPeonConfig(peonPath);
 		const sessionId = getSessionId(ctx);
 		if (ctx.hasUI) setTabTitle(`● ${projectName}: ready`);
-		firePeon(peonPath, "SessionStart", cwd, sessionId);
+		firePeon(peonPath, "SessionStart", cwd, sessionId, config);
 	});
 
-	pi.on("turn_start", async (_event, ctx) => {
+	pi.on("before_agent_start", async (_event, ctx) => {
+		const config = readPeonConfig(peonPath);
 		const sessionId = getSessionId(ctx);
 		if (ctx.hasUI) setTabTitle(`● ${projectName}: working...`);
-		firePeon(peonPath, "UserPromptSubmit", cwd, sessionId);
+		firePeon(peonPath, "UserPromptSubmit", cwd, sessionId, config);
+	});
+
+	pi.on("session_before_compact", async (_event, ctx) => {
+		const config = readPeonConfig(peonPath);
+		const sessionId = getSessionId(ctx);
+		firePeon(peonPath, "PreCompact", cwd, sessionId, config);
 	});
 
-	pi.on("turn_end", async (_event, ctx) => {
+	pi.on("agent_end", async (_event, ctx) => {
+		const config = readPeonConfig(peonPath);
 		const sessionId = getSessionId(ctx);
 		if (ctx.hasUI) setTabTitle(`✓ ${projectName}: done`);
-		firePeon(peonPath, "Stop", cwd, sessionId);
+		firePeon(peonPath, "Stop", cwd, sessionId, config);
 	});
 
 	pi.on("tool_result", async (event, ctx) => {
 		if (!event.isError) return;
+		const config = readPeonConfig(peonPath);
 		const sessionId = getSessionId(ctx);
 		if (ctx.hasUI) setTabTitle(`✗ ${projectName}: error`);
-		firePeon(peonPath, "PostToolUseFailure", cwd, sessionId);
+		firePeon(peonPath, "PostToolUseFailure", cwd, sessionId, config);
+	});
+
+	// Agent is asking the user a question (e.g. ask_user_question tool) →
+	// peon-ping "input.required" category. Fires before the tool runs.
+	pi.on("tool_call", async (event, ctx) => {
+		if (event.toolName !== "ask_user_question") return;
+		const config = readPeonConfig(peonPath);
+		const sessionId = getSessionId(ctx);
+		firePeon(peonPath, "PermissionRequest", cwd, sessionId, config);
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {
+		const config = readPeonConfig(peonPath);
 		const sessionId = getSessionId(ctx);
-		firePeon(peonPath, "SessionEnd", cwd, sessionId);
+		firePeon(peonPath, "SessionEnd", cwd, sessionId, config);
+	});
+
+	// -----------------------------------------------------------------------
+	// Commands
+	// -----------------------------------------------------------------------
+
+	if (!cliPath) return;
+
+	pi.registerCommand("peon-ping-toggle", {
+		description: "Toggle peon-ping mute on/off",
+		handler: async (_args, ctx) => {
+			const result = await execPeonCli(cliPath, ["toggle"]);
+			if (result.exitCode !== 0) {
+				ctx.ui.notify(result.stdout || "toggle failed", "error");
+			} else {
+				ctx.ui.notify(result.stdout || "toggled", "info");
+			}
+		},
+	});
+
+	pi.registerCommand("peon-ping-use", {
+		description: "Switch sound pack: /peon-ping-use <name>",
+		handler: async (args, ctx) => {
+			const name = args.trim();
+			if (!name) {
+				ctx.ui.notify("Usage: /peon-ping-use <pack-name>", "warning");
+				return;
+			}
+			const result = await execPeonCli(cliPath, ["packs", "use", "--install", name]);
+			if (result.exitCode !== 0) {
+				ctx.ui.notify(result.stdout || `Failed to switch to ${name}`, "error");
+			} else {
+				ctx.ui.notify(result.stdout || `Switched to ${name}`, "info");
+			}
+		},
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fyeeme/pi-peon-ping",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "peon-ping adapter for pi — routes lifecycle events through peon.sh for sound packs, notifications, and trainer reminders.",
   "type": "module",
   "license": "MIT",