@astrofoundry/pi-astro 0.6.7 → 0.8.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/gemini-image/index.test.ts

@@ -1,4 +1,4 @@
-import { mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -131,7 +131,7 @@ describe("gemini-image extension", () => {
         expect((res.content as Array<{ type: string }>)[1].type).toBe("image");
     });
 
-    it("always saves to <cwd>/.gemini-images by default", async () => {
+    it("saves under <cwd>/.gemini-images/<YYYY-MM-DD>/ with a zero-padded counter prefix by default", async () => {
         pngImageResponse();
         const { tool } = await load();
         const res = await tool.execute(
@@ -143,11 +143,14 @@ describe("gemini-image extension", () => {
         );
         const paths = res.details.savedPaths as string[];
         expect(paths).toHaveLength(1);
-        expect(paths[0]).toContain(".gemini-images");
-        expect(readdirSync(join(fakeCwd, ".gemini-images"))).toHaveLength(1);
+        const today = new Date().toISOString().slice(0, 10);
+        const dayDir = join(fakeCwd, ".gemini-images", today);
+        expect(paths[0]).toBe(join(dayDir, "000-a-thing.png"));
+        expect(readdirSync(join(fakeCwd, ".gemini-images"))).toEqual([today]);
+        expect(readdirSync(dayDir)).toEqual(["000-a-thing.png"]);
     });
 
-    it("save_to override writes into that directory (resolved against cwd)", async () => {
+    it("save_to override writes into <save_to>/<YYYY-MM-DD>/NNN-*.png", async () => {
         pngImageResponse();
         const { tool } = await load();
         const res = await tool.execute(
@@ -158,7 +161,79 @@ describe("gemini-image extension", () => {
             makeCtx({ cwd: fakeCwd }),
         );
         const paths = res.details.savedPaths as string[];
-        expect(paths[0]).toContain(join(fakeCwd, "out"));
+        const today = new Date().toISOString().slice(0, 10);
+        expect(paths[0]).toBe(join(fakeCwd, "out", today, "000-x.png"));
+    });
+
+    it("second call on the same day increments the counter (000 -> 001)", async () => {
+        pngImageResponse();
+        const { tool } = await load();
+        const first = await tool.execute(
+            "t",
+            { prompt: "alpha", skip_confirm: true },
+            undefined,
+            undefined,
+            makeCtx({ cwd: fakeCwd }),
+        );
+        pngImageResponse();
+        const second = await tool.execute(
+            "t",
+            { prompt: "beta", skip_confirm: true },
+            undefined,
+            undefined,
+            makeCtx({ cwd: fakeCwd }),
+        );
+        const today = new Date().toISOString().slice(0, 10);
+        const dayDir = join(fakeCwd, ".gemini-images", today);
+        expect((first.details.savedPaths as string[])[0]).toBe(join(dayDir, "000-alpha.png"));
+        expect((second.details.savedPaths as string[])[0]).toBe(join(dayDir, "001-beta.png"));
+    });
+
+    it("counter resumes from max existing NNN prefix even if earlier entries were deleted", async () => {
+        const today = new Date().toISOString().slice(0, 10);
+        const dayDir = join(fakeCwd, ".gemini-images", today);
+        mkdirSync(dayDir, { recursive: true });
+        writeFileSync(join(dayDir, "042-earlier.png"), "existing");
+        pngImageResponse();
+        const { tool } = await load();
+        const res = await tool.execute(
+            "t",
+            { prompt: "gamma", skip_confirm: true },
+            undefined,
+            undefined,
+            makeCtx({ cwd: fakeCwd }),
+        );
+        expect((res.details.savedPaths as string[])[0]).toBe(join(dayDir, "043-gamma.png"));
+    });
+
+    it("multi-image call (Imagen) gets consecutive counters within the same call", async () => {
+        generateImagesMock.mockResolvedValue({
+            generatedImages: [
+                { image: { imageBytes: "A", mimeType: "image/png" } },
+                { image: { imageBytes: "B", mimeType: "image/png" } },
+                { image: { imageBytes: "C", mimeType: "image/png" } },
+            ],
+        });
+        const { tool } = await load();
+        const res = await tool.execute(
+            "t",
+            {
+                prompt: "batch",
+                model: "imagen-4.0-fast-generate-001",
+                number_of_images: 3,
+                skip_confirm: true,
+            },
+            undefined,
+            undefined,
+            makeCtx({ cwd: fakeCwd }),
+        );
+        const today = new Date().toISOString().slice(0, 10);
+        const dayDir = join(fakeCwd, ".gemini-images", today);
+        expect(res.details.savedPaths).toEqual([
+            join(dayDir, "000-batch.png"),
+            join(dayDir, "001-batch.png"),
+            join(dayDir, "002-batch.png"),
+        ]);
     });
 
     it("silently saves API key on first paste (no confirm prompt)", async () => {

package/extensions/gemini-image/index.ts

@@ -1,4 +1,4 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
@@ -51,7 +51,9 @@ const params = Type.Object({
         }),
     ),
     save_to: Type.Optional(
-        Type.String({ description: `Directory to save PNG(s). Default: <cwd>/${DEFAULT_SAVE_SUBDIR}/.` }),
+        Type.String({
+            description: `Base directory to save PNG(s). Images are written to <save_to>/YYYY-MM-DD/NNN-<slug>.png where NNN is a zero-padded counter that resumes from the highest existing prefix in that day's folder. Default base: <cwd>/${DEFAULT_SAVE_SUBDIR}/.`,
+        }),
     ),
     skip_confirm: Type.Optional(Type.Boolean({ description: "Skip the review/confirm prompt and call the API directly." })),
 });
@@ -219,22 +221,42 @@ async function callImagen(
     return { images };
 }
 
-function saveImages(images: DecodedImage[], dir: string, prompt: string): string[] {
+function todayFolderName(): string {
+    return new Date().toISOString().slice(0, 10);
+}
+
+function nextCounter(dir: string): number {
+    const existing = readdirSync(dir);
+    let max = -1;
+    for (const name of existing) {
+        const match = /^(\d{3,})-/.exec(name);
+        if (!match) continue;
+        const n = parseInt(match[1], 10);
+        if (n > max) max = n;
+    }
+    return max + 1;
+}
+
+function saveImages(images: DecodedImage[], baseDir: string, prompt: string): string[] {
+    const dir = join(baseDir, todayFolderName());
     mkdirSync(dir, { recursive: true });
+
     const slug =
         prompt
             .toLowerCase()
             .replace(/[^a-z0-9]+/g, "-")
             .replace(/^-+|-+$/g, "")
             .slice(0, 40) || "image";
-    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+
+    let counter = nextCounter(dir);
     const paths: string[] = [];
-    for (let i = 0; i < images.length; i++) {
-        const ext = images[i].mimeType === "image/jpeg" ? "jpg" : "png";
-        const base = images.length > 1 ? `${slug}-${ts}-${i + 1}.${ext}` : `${slug}-${ts}.${ext}`;
-        const full = join(dir, base);
-        writeFileSync(full, Buffer.from(images[i].data, "base64"));
+    for (const img of images) {
+        const ext = img.mimeType === "image/jpeg" ? "jpg" : "png";
+        const prefix = String(counter).padStart(3, "0");
+        const full = join(dir, `${prefix}-${slug}.${ext}`);
+        writeFileSync(full, Buffer.from(img.data, "base64"));
         paths.push(full);
+        counter++;
     }
     return paths;
 }

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