@astrofoundry/pi-astro 0.6.7 → 0.7.0

package/README.md

@@ -62,7 +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). 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`.
+- `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

@@ -51,12 +51,14 @@ function setPlatform(p: NodeJS.Platform): void {
 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(() => {
@@ -65,16 +67,79 @@ describe("notify-on-stop", () => {
         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)", async () => {
+    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();
-        expect(execMock.mock.calls[0][0]).toMatch(/afplay/);
+        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 () => {

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

@@ -3,11 +3,21 @@ 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") {
-        return "afplay /System/Library/Sounds/Glass.aiff";
+        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"';
@@ -39,7 +49,7 @@ export default function notifyOnStopExtension(pi: ExtensionAPI): void {
 
     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.",
+            "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") {

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.7",
+  "version": "0.7.0",
   "description": "Personal pi customizations (extensions, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"