@astrofoundry/pi-astro 0.6.6 → 0.6.7

package/README.md

@@ -62,6 +62,7 @@ pi                # launch; confirm [Extensions] lists astro-agents, claude-glob
 - `multi-edit` — registers the enhanced `edit` tool
 - `gemini-image` — registers `gemini_image` tool (requires a Gemini API key; prompts and saves on first use)
 - `security-guard` — blocks/prompts destructive bash commands and sensitive file access; configure at `~/.pi/agent/security-guard.json` (example written on first run); `/security-guard status|reload|test`
+- `notify-on-stop` — runs a shell command when the agent finishes a turn (sound, voice, desktop notification). Configure via env `PI_STOP_NOTIFY='afplay /System/Library/Sounds/Glass.aiff && say "Done"'`. Defaults to macOS Glass sound / Linux `notify-send`. Disable with `PI_STOP_NOTIFY_OFF=1`. `/notify status|test|off`.
 - `claude-globals` — auto-injects `~/.claude/CLAUDE.md` into every pi session's system prompt
 
 **Bundled subagents** (callable via `astro_agent`):

package/extensions/notify-on-stop/index.test.ts

@@ -0,0 +1,179 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const execMock = vi.fn();
+
+vi.mock("node:child_process", () => ({
+    exec: (cmd: string, opts: unknown, cb?: unknown) => {
+        execMock(cmd, opts, cb);
+        // Return a chainable fake child with on/stdout/stderr
+        const fake = {
+            on: vi.fn(),
+            stdout: { on: vi.fn() },
+            stderr: { on: vi.fn() },
+        };
+        return fake;
+    },
+}));
+
+type Handler = (event: unknown, ctx: unknown) => void | Promise<void>;
+type CommandHandler = (args: string, ctx: unknown) => Promise<void> | void;
+
+function makePi(): {
+    handlers: Record<string, Handler>;
+    commands: Map<string, { handler: CommandHandler }>;
+    on: (event: string, h: Handler) => void;
+    registerCommand: (name: string, opts: { description?: string; handler: CommandHandler }) => void;
+} {
+    const handlers: Record<string, Handler> = {};
+    const commands = new Map();
+    return {
+        handlers,
+        commands,
+        on: (event, h) => {
+            handlers[event] = h;
+        },
+        registerCommand: (name, opts) => {
+            commands.set(name, { handler: opts.handler });
+        },
+    };
+}
+
+function makeCtx(): { ui: { notify: ReturnType<typeof vi.fn> } } {
+    return { ui: { notify: vi.fn() } };
+}
+
+const origPlatform = Object.getOwnPropertyDescriptor(process, "platform")!;
+
+function setPlatform(p: NodeJS.Platform): void {
+    Object.defineProperty(process, "platform", { value: p, configurable: true });
+}
+
+describe("notify-on-stop", () => {
+    const origCmd = process.env.PI_STOP_NOTIFY;
+    const origOff = process.env.PI_STOP_NOTIFY_OFF;
+
+    beforeEach(() => {
+        vi.resetModules();
+        execMock.mockReset();
+        delete process.env.PI_STOP_NOTIFY;
+        delete process.env.PI_STOP_NOTIFY_OFF;
+    });
+
+    afterEach(() => {
+        Object.defineProperty(process, "platform", origPlatform);
+        if (origCmd === undefined) delete process.env.PI_STOP_NOTIFY;
+        else process.env.PI_STOP_NOTIFY = origCmd;
+        if (origOff === undefined) delete process.env.PI_STOP_NOTIFY_OFF;
+        else process.env.PI_STOP_NOTIFY_OFF = origOff;
+    });
+
+    it("runs default command on agent_end (macOS)", async () => {
+        setPlatform("darwin");
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        pi.handlers.agent_end({}, makeCtx());
+        expect(execMock).toHaveBeenCalled();
+        expect(execMock.mock.calls[0][0]).toMatch(/afplay/);
+    });
+
+    it("runs custom PI_STOP_NOTIFY over default", async () => {
+        setPlatform("darwin");
+        process.env.PI_STOP_NOTIFY = "my custom --cmd";
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        pi.handlers.agent_end({}, makeCtx());
+        expect(execMock.mock.calls[0][0]).toBe("my custom --cmd");
+    });
+
+    it("does NOT run anything when PI_STOP_NOTIFY_OFF=1", async () => {
+        setPlatform("darwin");
+        process.env.PI_STOP_NOTIFY_OFF = "1";
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        pi.handlers.agent_end({}, makeCtx());
+        expect(execMock).not.toHaveBeenCalled();
+    });
+
+    it("does nothing on an unsupported platform with no env", async () => {
+        setPlatform("win32");
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        pi.handlers.agent_end({}, makeCtx());
+        expect(execMock).not.toHaveBeenCalled();
+    });
+
+    it("Linux default uses notify-send", async () => {
+        setPlatform("linux");
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        pi.handlers.agent_end({}, makeCtx());
+        expect(execMock.mock.calls[0][0]).toMatch(/notify-send/);
+    });
+
+    it("trims whitespace on PI_STOP_NOTIFY and ignores empty strings", async () => {
+        setPlatform("darwin");
+        process.env.PI_STOP_NOTIFY = "   ";
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        pi.handlers.agent_end({}, makeCtx());
+        expect(execMock.mock.calls[0][0]).toMatch(/afplay/);
+    });
+
+    it("/notify status reports current command", async () => {
+        setPlatform("darwin");
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("status", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/afplay/), "info");
+    });
+
+    it("/notify status reports disabled when PI_STOP_NOTIFY_OFF", async () => {
+        setPlatform("darwin");
+        process.env.PI_STOP_NOTIFY_OFF = "1";
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/disabled/), "info");
+    });
+
+    it("/notify test runs the command immediately", async () => {
+        setPlatform("darwin");
+        process.env.PI_STOP_NOTIFY = "test-cmd";
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("test", ctx);
+        expect(execMock.mock.calls[0][0]).toBe("test-cmd");
+    });
+
+    it("/notify test warns when nothing configured", async () => {
+        setPlatform("win32");
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("test", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/nothing configured/), "warning");
+    });
+
+    it("/notify off gives persistence guidance", async () => {
+        setPlatform("darwin");
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        await pi.commands.get("notify")!.handler("off", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/PI_STOP_NOTIFY_OFF/), "info");
+    });
+});

package/extensions/notify-on-stop/index.ts

@@ -0,0 +1,71 @@
+import { exec } from "node:child_process";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+const ENV_CMD = "PI_STOP_NOTIFY";
+const ENV_OFF = "PI_STOP_NOTIFY_OFF";
+const TIMEOUT_MS = 10_000;
+
+function defaultCommand(): string | undefined {
+    if (process.platform === "darwin") {
+        return "afplay /System/Library/Sounds/Glass.aiff";
+    }
+    if (process.platform === "linux") {
+        return 'command -v notify-send >/dev/null 2>&1 && notify-send "pi" "Agent done"';
+    }
+    return undefined;
+}
+
+function resolveCommand(): string | undefined {
+    if (process.env[ENV_OFF] === "1") return undefined;
+    const custom = process.env[ENV_CMD]?.trim();
+    if (custom) return custom;
+    return defaultCommand();
+}
+
+function runNotify(cmd: string): void {
+    const child = exec(cmd, { shell: "/bin/sh", timeout: TIMEOUT_MS });
+    // Swallow errors so a broken notify command never surfaces into pi output.
+    child.on("error", () => {});
+    child.stderr?.on("data", () => {});
+    child.stdout?.on("data", () => {});
+}
+
+export default function notifyOnStopExtension(pi: ExtensionAPI): void {
+    pi.on("agent_end", () => {
+        const cmd = resolveCommand();
+        if (!cmd) return;
+        runNotify(cmd);
+    });
+
+    pi.registerCommand("notify", {
+        description:
+            "Stop-notify status/test. Usage: /notify [status|test|off]. Configure via env PI_STOP_NOTIFY, disable with PI_STOP_NOTIFY_OFF=1.",
+        handler: async (args, ctx) => {
+            const sub = args.trim().toLowerCase() || "status";
+            if (sub === "test") {
+                const cmd = resolveCommand();
+                if (!cmd) {
+                    ctx.ui.notify("notify: nothing configured / disabled", "warning");
+                    return;
+                }
+                runNotify(cmd);
+                ctx.ui.notify(`notify: ran "${cmd}"`, "info");
+                return;
+            }
+            if (sub === "off") {
+                ctx.ui.notify(
+                    `notify: to disable persistently, set ${ENV_OFF}=1 in your shell rc; this session's behavior is driven by env at startup.`,
+                    "info",
+                );
+                return;
+            }
+            const cmd = resolveCommand();
+            ctx.ui.notify(
+                cmd
+                    ? `notify: will run "${cmd}" on agent_end`
+                    : `notify: disabled (no default for this platform or ${ENV_OFF}=1)`,
+                "info",
+            );
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrofoundry/pi-astro",
-  "version": "0.6.6",
+  "version": "0.6.7",
   "description": "Personal pi customizations (extensions, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"