@astrofoundry/pi-astro 0.6.6 → 0.7.0

package/README.md

@@ -62,6 +62,9 @@ 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). macOS default: plays the Glass system sound **and** speaks "Agent done" via `say` using the **`Samantha (Enhanced)`** voice. Linux default: `notify-send "pi" "Agent done"`. Override the voice with `PI_STOP_NOTIFY_VOICE=<voice-name>` (macOS only; e.g. `Alex`, `Karen`, `Daniel (Enhanced)`). Replace the full command with `PI_STOP_NOTIFY='afplay /System/Library/Sounds/Glass.aiff && say "Done"'`. Disable everything with `PI_STOP_NOTIFY_OFF=1`. `/notify status|test|off`.
+  - **macOS voice install (required once for the default):** open **System Settings → Accessibility → Spoken Content → System Voice → Manage Voices…**, expand **English**, check **Samantha (Enhanced)**, click **Done** to download (~500 MB – 1 GB). Verify with `say -v "Samantha (Enhanced)" hi`. If the voice is missing, `say` errors silently and you'll only hear the Glass sound.
+- `vscode-image` — only active inside VS Code's integrated terminal (`TERM_PROGRAM=vscode`). Switches pi-tui's image output to the **Kitty graphics protocol** so images returned by tools like `gemini_image` render as real pixels instead of the `[Image: …]` text fallback. **Requires enabling `Terminal › Integrated: Enable Images` in VS Code settings** (off by default); restart the integrated terminal after flipping it. Disable with `PI_VSCODE_IMAGE_OFF=1`. `/vscode-image` prints current status.
 - `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,244 @@
+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;
+    const origVoice = process.env.PI_STOP_NOTIFY_VOICE;
+
+    beforeEach(() => {
+        vi.resetModules();
+        execMock.mockReset();
+        delete process.env.PI_STOP_NOTIFY;
+        delete process.env.PI_STOP_NOTIFY_OFF;
+        delete process.env.PI_STOP_NOTIFY_VOICE;
+    });
+
+    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;
+        if (origVoice === undefined) delete process.env.PI_STOP_NOTIFY_VOICE;
+        else process.env.PI_STOP_NOTIFY_VOICE = origVoice;
+    });
+
+    it("runs default command on agent_end (macOS): afplay + say with Samantha (Enhanced)", 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();
+        const cmd = execMock.mock.calls[0][0] as string;
+        expect(cmd).toMatch(/^afplay \/System\/Library\/Sounds\/Glass\.aiff && say -v /);
+        expect(cmd).toContain("'Samantha (Enhanced)'");
+        expect(cmd).toContain("'Agent done'");
+    });
+
+    it("PI_STOP_NOTIFY_VOICE overrides the default voice (macOS)", async () => {
+        setPlatform("darwin");
+        process.env.PI_STOP_NOTIFY_VOICE = "Alex";
+        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());
+        const cmd = execMock.mock.calls[0][0] as string;
+        expect(cmd).toContain("say -v 'Alex'");
+        expect(cmd).not.toContain("Samantha");
+    });
+
+    it("PI_STOP_NOTIFY_VOICE with apostrophes is POSIX-safely quoted", async () => {
+        setPlatform("darwin");
+        process.env.PI_STOP_NOTIFY_VOICE = "O'Neill";
+        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());
+        const cmd = execMock.mock.calls[0][0] as string;
+        expect(cmd).toContain("say -v 'O'\\''Neill'");
+    });
+
+    it("PI_STOP_NOTIFY_VOICE with only whitespace falls back to default voice (macOS)", async () => {
+        setPlatform("darwin");
+        process.env.PI_STOP_NOTIFY_VOICE = "   ";
+        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());
+        const cmd = execMock.mock.calls[0][0] as string;
+        expect(cmd).toContain("'Samantha (Enhanced)'");
+    });
+
+    it("PI_STOP_NOTIFY_VOICE is ignored when PI_STOP_NOTIFY overrides the full command", async () => {
+        setPlatform("darwin");
+        process.env.PI_STOP_NOTIFY = "my custom --cmd";
+        process.env.PI_STOP_NOTIFY_VOICE = "Alex";
+        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("PI_STOP_NOTIFY_VOICE has no effect on Linux default", async () => {
+        setPlatform("linux");
+        process.env.PI_STOP_NOTIFY_VOICE = "Alex";
+        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());
+        const cmd = execMock.mock.calls[0][0] as string;
+        expect(cmd).toMatch(/notify-send/);
+        expect(cmd).not.toContain("say");
+        expect(cmd).not.toContain("Alex");
+    });
+
+    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,81 @@
+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 ENV_VOICE = "PI_STOP_NOTIFY_VOICE";
+const TIMEOUT_MS = 10_000;
+const DEFAULT_VOICE = "Samantha (Enhanced)";
+const MACOS_SPOKEN_MESSAGE = "Agent done";
+
+function shellQuote(value: string): string {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+function defaultCommand(): string | undefined {
+    if (process.platform === "darwin") {
+        const voice = process.env[ENV_VOICE]?.trim() || DEFAULT_VOICE;
+        const sound = "afplay /System/Library/Sounds/Glass.aiff";
+        const speak = `say -v ${shellQuote(voice)} ${shellQuote(MACOS_SPOKEN_MESSAGE)}`;
+        return `${sound} && ${speak}`;
+    }
+    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 (full override) or PI_STOP_NOTIFY_VOICE (macOS default voice); 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/extensions/vscode-image/index.test.ts

@@ -0,0 +1,114 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const setCapabilitiesMock = vi.fn();
+
+vi.mock("@mariozechner/pi-tui", () => ({
+    setCapabilities: setCapabilitiesMock,
+}));
+
+type CommandHandler = (args: string, ctx: unknown) => Promise<void> | void;
+
+function makePi(): {
+    commands: Map<string, { handler: CommandHandler }>;
+    registerCommand: (name: string, opts: { description?: string; handler: CommandHandler }) => void;
+} {
+    const commands = new Map<string, { handler: CommandHandler }>();
+    return {
+        commands,
+        registerCommand: (name, opts) => {
+            commands.set(name, { handler: opts.handler });
+        },
+    };
+}
+
+function makeCtx(): { ui: { notify: ReturnType<typeof vi.fn> } } {
+    return { ui: { notify: vi.fn() } };
+}
+
+describe("vscode-image", () => {
+    const origTerm = process.env.TERM_PROGRAM;
+    const origOff = process.env.PI_VSCODE_IMAGE_OFF;
+
+    beforeEach(() => {
+        vi.resetModules();
+        setCapabilitiesMock.mockReset();
+        delete process.env.TERM_PROGRAM;
+        delete process.env.PI_VSCODE_IMAGE_OFF;
+    });
+
+    afterEach(() => {
+        if (origTerm === undefined) delete process.env.TERM_PROGRAM;
+        else process.env.TERM_PROGRAM = origTerm;
+        if (origOff === undefined) delete process.env.PI_VSCODE_IMAGE_OFF;
+        else process.env.PI_VSCODE_IMAGE_OFF = origOff;
+    });
+
+    it("does nothing when TERM_PROGRAM is unset", async () => {
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        expect(setCapabilitiesMock).not.toHaveBeenCalled();
+        expect(pi.commands.has("vscode-image")).toBe(false);
+    });
+
+    it("does nothing when TERM_PROGRAM is not vscode", async () => {
+        process.env.TERM_PROGRAM = "iterm.app";
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        expect(setCapabilitiesMock).not.toHaveBeenCalled();
+        expect(pi.commands.has("vscode-image")).toBe(false);
+    });
+
+    it("enables Kitty protocol when TERM_PROGRAM=vscode", async () => {
+        process.env.TERM_PROGRAM = "vscode";
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        expect(setCapabilitiesMock).toHaveBeenCalledWith({
+            images: "kitty",
+            trueColor: true,
+            hyperlinks: true,
+        });
+        expect(pi.commands.has("vscode-image")).toBe(true);
+    });
+
+    it("matches TERM_PROGRAM case-insensitively", async () => {
+        process.env.TERM_PROGRAM = "VSCode";
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        expect(setCapabilitiesMock).toHaveBeenCalled();
+    });
+
+    it("skips setCapabilities when PI_VSCODE_IMAGE_OFF=1 but still registers command", async () => {
+        process.env.TERM_PROGRAM = "vscode";
+        process.env.PI_VSCODE_IMAGE_OFF = "1";
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        expect(setCapabilitiesMock).not.toHaveBeenCalled();
+        expect(pi.commands.has("vscode-image")).toBe(true);
+    });
+
+    it("/vscode-image reports enabled state", async () => {
+        process.env.TERM_PROGRAM = "vscode";
+        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("vscode-image")!.handler("", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/Kitty/), "info");
+    });
+
+    it("/vscode-image reports disabled when PI_VSCODE_IMAGE_OFF=1", async () => {
+        process.env.TERM_PROGRAM = "vscode";
+        process.env.PI_VSCODE_IMAGE_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("vscode-image")!.handler("", ctx);
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/disabled/), "info");
+    });
+});

package/extensions/vscode-image/index.ts

@@ -0,0 +1,42 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { setCapabilities } from "@mariozechner/pi-tui";
+
+const ENV_OFF = "PI_VSCODE_IMAGE_OFF";
+
+function inVSCode(): boolean {
+    return process.env.TERM_PROGRAM?.toLowerCase() === "vscode";
+}
+
+function isDisabled(): boolean {
+    return process.env[ENV_OFF] === "1";
+}
+
+export default function vscodeImageExtension(pi: ExtensionAPI): void {
+    if (!inVSCode()) return;
+
+    if (!isDisabled()) {
+        setCapabilities({
+            images: "kitty",
+            trueColor: true,
+            hyperlinks: true,
+        });
+    }
+
+    pi.registerCommand("vscode-image", {
+        description:
+            "VSCode image-protocol status. Usage: /vscode-image. Disable with PI_VSCODE_IMAGE_OFF=1 (requires pi restart).",
+        handler: async (_args, ctx) => {
+            if (isDisabled()) {
+                ctx.ui.notify(
+                    `vscode-image: disabled (${ENV_OFF}=1). Unset the env var and restart pi to re-enable.`,
+                    "info",
+                );
+                return;
+            }
+            ctx.ui.notify(
+                "vscode-image: Kitty graphics protocol enabled. Ensure \"Terminal > Integrated: Enable Images\" is ON in VS Code settings.",
+                "info",
+            );
+        },
+    });
+}

package/package.json

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