@astrofoundry/pi-astro 0.5.1 → 0.6.1

package/extensions/gemini-image/parseTweaks.ts

@@ -0,0 +1,191 @@
+/**
+ * Parse a free-text review/tweak utterance into partial parameter updates.
+ *
+ * Intentionally conservative: we recognize a known vocabulary (models,
+ * aspect ratios, sizes, numeric counts, person-gen tokens, and explicit
+ * `prompt:` / `negative:` / `seed:` / `save to <path>` phrases). Unknown
+ * tokens are returned in `unrecognized` so the caller can surface them.
+ */
+
+import {
+    ALL_MODELS,
+    GEMINI_ASPECT_RATIOS,
+    IMAGEN_ASPECT_RATIOS,
+    GEMINI_IMAGE_SIZES,
+    PERSON_GENERATION_VALUES,
+    type ImageModel,
+} from "./models.ts";
+
+export interface TweakPatch {
+    prompt?: string;
+    model?: ImageModel;
+    aspect_ratio?: string;
+    image_size?: "1K" | "2K" | "4K";
+    number_of_images?: number;
+    negative_prompt?: string;
+    person_generation?: (typeof PERSON_GENERATION_VALUES)[number];
+    seed?: number;
+    save_to?: string;
+    verbatim?: boolean;
+}
+
+export interface ParseOutcome {
+    patch: TweakPatch;
+    unrecognized: string[];
+    intent: "confirm" | "cancel" | "tweak";
+}
+
+const MODEL_ALIASES: Record<string, ImageModel> = {
+    flash: "gemini-2.5-flash-image",
+    "flash image": "gemini-2.5-flash-image",
+    "gemini flash": "gemini-2.5-flash-image",
+    "2.5 flash": "gemini-2.5-flash-image",
+    "nano banana 2": "gemini-3.1-flash-image-preview",
+    "nano banana": "gemini-3.1-flash-image-preview",
+    "3.1 flash": "gemini-3.1-flash-image-preview",
+    pro: "gemini-3-pro-image-preview",
+    "pro model": "gemini-3-pro-image-preview",
+    "gemini pro": "gemini-3-pro-image-preview",
+    "3 pro": "gemini-3-pro-image-preview",
+    "nano banana pro": "gemini-3-pro-image-preview",
+    imagen: "imagen-4.0-generate-001",
+    "imagen standard": "imagen-4.0-generate-001",
+    "imagen 4": "imagen-4.0-generate-001",
+    "imagen fast": "imagen-4.0-fast-generate-001",
+    "imagen 4 fast": "imagen-4.0-fast-generate-001",
+    "imagen ultra": "imagen-4.0-ultra-generate-001",
+    "imagen 4 ultra": "imagen-4.0-ultra-generate-001",
+};
+
+const ALL_ASPECT_RATIOS = [
+    ...new Set([...GEMINI_ASPECT_RATIOS, ...IMAGEN_ASPECT_RATIOS]),
+];
+const ALL_SIZES = [...GEMINI_IMAGE_SIZES];
+
+function trimQuotes(s: string): string {
+    return s.replace(/^['"`](.*)['"`]$/s, "$1").trim();
+}
+
+export function parseTweaks(raw: string): ParseOutcome {
+    const patch: TweakPatch = {};
+    const unrecognized: string[] = [];
+    const trimmed = raw.trim();
+
+    if (trimmed === "") {
+        return { patch, unrecognized, intent: "confirm" };
+    }
+    if (/^(y|yes|ok|go|confirm|proceed)$/i.test(trimmed)) {
+        return { patch, unrecognized, intent: "confirm" };
+    }
+    if (/^(n|no|cancel|abort|quit|exit)$/i.test(trimmed)) {
+        return { patch, unrecognized, intent: "cancel" };
+    }
+
+    let rest = trimmed;
+
+    const extract = (pattern: RegExp, onMatch: (m: RegExpExecArray) => void): void => {
+        const match = pattern.exec(rest);
+        if (match) {
+            onMatch(match);
+            rest = (rest.slice(0, match.index) + rest.slice(match.index + match[0].length)).trim();
+        }
+    };
+
+    // prompt: <rest> / use prompt <rest>  (greedy — takes rest of string unless another keyword follows)
+    extract(
+        /(?:^|\s)(?:use\s+prompt\s*[:=]?|prompt\s*[:=])\s*(.+?)(?=(?:\s+(?:model|size|image_size|aspect|ratio|images?|n=|count|negative|seed|save|person|verbatim|raw|as-?is|dont_allow|allow_adult|allow_all)\b)|$)/i,
+        (m) => {
+            patch.prompt = trimQuotes(m[1]);
+        },
+    );
+
+    extract(/(?:^|\s)(?:negative(?:_prompt)?)\s*[:=]\s*(.+?)(?=$|\s+(?:model|size|aspect|ratio|images?|n=|count|seed|save|person|verbatim|raw)\b)/i, (m) => {
+        patch.negative_prompt = trimQuotes(m[1]);
+    });
+
+    extract(/(?:^|\s)seed\s*[:=]?\s*(-?\d+)/i, (m) => {
+        patch.seed = Number(m[1]);
+    });
+
+    extract(/(?:^|\s)save\s+to\s+(\S+)/i, (m) => {
+        patch.save_to = m[1];
+    });
+
+    extract(/(?:^|\s)(verbatim|as-?is|raw)\b/i, () => {
+        patch.verbatim = true;
+    });
+
+    extract(/(?:^|\s)(\d+)\s*(?:images?|imgs?)\b/i, (m) => {
+        patch.number_of_images = Math.max(1, Math.min(4, Number(m[1])));
+    });
+    extract(/(?:^|\s)(?:n|count)\s*[:=]\s*(\d+)/i, (m) => {
+        patch.number_of_images = Math.max(1, Math.min(4, Number(m[1])));
+    });
+    extract(/(?:^|\s)give\s+me\s+(\d+)\b/i, (m) => {
+        patch.number_of_images = Math.max(1, Math.min(4, Number(m[1])));
+    });
+
+    for (const size of ALL_SIZES) {
+        const re = new RegExp(`(?:^|\\s)${size}(?=\\s|$)`, "i");
+        const m = re.exec(rest);
+        if (m) {
+            patch.image_size = size;
+            rest = (rest.slice(0, m.index) + rest.slice(m.index + m[0].length)).trim();
+            break;
+        }
+    }
+
+    for (const ratio of ALL_ASPECT_RATIOS) {
+        const re = new RegExp(`(?:^|\\s)${ratio.replace(":", "\\s*:\\s*")}(?=\\s|$)`);
+        const m = re.exec(rest);
+        if (m) {
+            patch.aspect_ratio = ratio;
+            rest = (rest.slice(0, m.index) + rest.slice(m.index + m[0].length)).trim();
+            break;
+        }
+    }
+
+    for (const pg of PERSON_GENERATION_VALUES) {
+        const re = new RegExp(`(?:^|\\s)${pg}(?=\\s|$)`, "i");
+        const m = re.exec(rest);
+        if (m) {
+            patch.person_generation = pg;
+            rest = (rest.slice(0, m.index) + rest.slice(m.index + m[0].length)).trim();
+            break;
+        }
+    }
+
+    // Full model id exact match
+    for (const model of ALL_MODELS) {
+        const idx = rest.toLowerCase().indexOf(model.toLowerCase());
+        if (idx !== -1) {
+            patch.model = model;
+            rest = (rest.slice(0, idx) + rest.slice(idx + model.length)).trim();
+            break;
+        }
+    }
+
+    // Model aliases (only if model not set yet) — check longest first so "nano banana pro" beats "pro"
+    if (!patch.model) {
+        const aliases = Object.keys(MODEL_ALIASES).sort((a, b) => b.length - a.length);
+        for (const alias of aliases) {
+            const re = new RegExp(`(?:^|\\s)${alias.replace(/\s+/g, "\\s+")}(?=\\s|$|[.,])`, "i");
+            const m = re.exec(rest);
+            if (m) {
+                patch.model = MODEL_ALIASES[alias];
+                rest = (rest.slice(0, m.index) + rest.slice(m.index + m[0].length)).trim();
+                break;
+            }
+        }
+    }
+
+    // Split leftover into whitespace-separated tokens; non-filler ones are "unrecognized".
+    const leftover = rest.split(/\s+/).filter((t) => t.length > 0 && !/^(use|and|with|,)$/i.test(t));
+    if (leftover.length > 0) unrecognized.push(...leftover);
+
+    return {
+        patch,
+        unrecognized,
+        intent: Object.keys(patch).length > 0 ? "tweak" : "tweak",
+    };
+}

package/extensions/gemini-image/pricing.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+import { estimateCost, formatUsd, hasPricing } from "./pricing.ts";
+
+describe("estimateCost", () => {
+    it("Imagen 4 Fast: $0.02 × N images", () => {
+        const e = estimateCost({
+            model: "imagen-4.0-fast-generate-001",
+            prompt: "cat",
+            numberOfImages: 3,
+        });
+        expect(e.estimatedUsd).toBeCloseTo(0.06, 5);
+        expect(e.breakdown).toContain("0.02");
+    });
+
+    it("Imagen 4 Standard single image", () => {
+        const e = estimateCost({
+            model: "imagen-4.0-generate-001",
+            prompt: "x",
+            numberOfImages: 1,
+        });
+        expect(e.estimatedUsd).toBeCloseTo(0.04, 5);
+    });
+
+    it("Imagen 4 Ultra", () => {
+        const e = estimateCost({
+            model: "imagen-4.0-ultra-generate-001",
+            prompt: "x",
+            numberOfImages: 4,
+        });
+        expect(e.estimatedUsd).toBeCloseTo(0.24, 5);
+    });
+
+    it("Gemini 3 Pro 4K is more expensive than 2K", () => {
+        const at4k = estimateCost({
+            model: "gemini-3-pro-image-preview",
+            prompt: "small",
+            numberOfImages: 1,
+            imageSize: "4K",
+        });
+        const at2k = estimateCost({
+            model: "gemini-3-pro-image-preview",
+            prompt: "small",
+            numberOfImages: 1,
+            imageSize: "2K",
+        });
+        expect(at4k.estimatedUsd).toBeGreaterThan(at2k.estimatedUsd);
+    });
+
+    it("Gemini 3 Pro prompt tokens contribute to cost (long prompt > short)", () => {
+        const longPrompt = "x".repeat(10_000);
+        const shortEst = estimateCost({
+            model: "gemini-3-pro-image-preview",
+            prompt: "x",
+            numberOfImages: 1,
+        });
+        const longEst = estimateCost({
+            model: "gemini-3-pro-image-preview",
+            prompt: longPrompt,
+            numberOfImages: 1,
+        });
+        expect(longEst.estimatedUsd).toBeGreaterThan(shortEst.estimatedUsd);
+    });
+
+    it("Flash estimate scales linearly with numberOfImages", () => {
+        const one = estimateCost({
+            model: "gemini-2.5-flash-image",
+            prompt: "x",
+            numberOfImages: 1,
+        });
+        const four = estimateCost({
+            model: "gemini-2.5-flash-image",
+            prompt: "x",
+            numberOfImages: 4,
+        });
+        // Output dominates; roughly 4x
+        expect(four.estimatedUsd).toBeGreaterThan(3.5 * one.estimatedUsd * 0.99);
+    });
+});
+
+describe("formatUsd", () => {
+    it("renders sub-cent as <$0.01", () => {
+        expect(formatUsd(0.002)).toBe("<$0.01");
+    });
+
+    it("renders 4 decimals for normal amounts", () => {
+        expect(formatUsd(0.1234)).toBe("$0.1234");
+    });
+});
+
+describe("hasPricing", () => {
+    it("returns true for all known models", () => {
+        expect(hasPricing("gemini-2.5-flash-image")).toBe(true);
+        expect(hasPricing("imagen-4.0-fast-generate-001")).toBe(true);
+    });
+});

package/extensions/gemini-image/pricing.ts

@@ -0,0 +1,102 @@
+/**
+ * Gemini image-generation price table.
+ *
+ * Last verified: 2026-04-24 via ai.google.dev/gemini-api/docs/pricing.
+ * Prices drift — edit when re-checked.
+ */
+
+import type { ImageModel } from "./models.ts";
+
+interface ImagenPrice {
+    kind: "flat";
+    perImage: number; // USD
+}
+
+interface GeminiNativePrice {
+    kind: "token";
+    // $ per 1M input tokens
+    inputPer1M: number;
+    // $ per output image at 1K/2K resolution
+    outputPerImage1Kor2K: number;
+    // $ per output image at 4K resolution
+    outputPerImage4K: number;
+    // Approx output tokens per image (for reference; not used in estimate)
+    tokensPerImage: number;
+}
+
+type ModelPrice = ImagenPrice | GeminiNativePrice;
+
+const PRICES: Record<ImageModel, ModelPrice> = {
+    "imagen-4.0-fast-generate-001": { kind: "flat", perImage: 0.02 },
+    "imagen-4.0-generate-001": { kind: "flat", perImage: 0.04 },
+    "imagen-4.0-ultra-generate-001": { kind: "flat", perImage: 0.06 },
+    "gemini-2.5-flash-image": {
+        kind: "token",
+        inputPer1M: 0.3,
+        outputPerImage1Kor2K: 0.039,
+        outputPerImage4K: 0.039,
+        tokensPerImage: 1290,
+    },
+    "gemini-3.1-flash-image-preview": {
+        kind: "token",
+        inputPer1M: 0.3,
+        outputPerImage1Kor2K: 0.039,
+        outputPerImage4K: 0.078,
+        tokensPerImage: 1290,
+    },
+    "gemini-3-pro-image-preview": {
+        kind: "token",
+        inputPer1M: 2.0,
+        outputPerImage1Kor2K: 0.134,
+        outputPerImage4K: 0.24,
+        tokensPerImage: 1290,
+    },
+};
+
+export interface EstimateInput {
+    model: ImageModel;
+    prompt: string;
+    numberOfImages: number;
+    imageSize?: "1K" | "2K" | "4K";
+    inputImagesBytes?: number;
+}
+
+export interface EstimateResult {
+    estimatedUsd: number;
+    breakdown: string;
+}
+
+const CHARS_PER_TOKEN_APPROX = 4;
+
+export function estimateCost(input: EstimateInput): EstimateResult {
+    const price = PRICES[input.model];
+    if (price.kind === "flat") {
+        const usd = price.perImage * input.numberOfImages;
+        return {
+            estimatedUsd: usd,
+            breakdown: `${input.numberOfImages} × $${price.perImage.toFixed(2)}/image`,
+        };
+    }
+
+    const inputTokens = Math.ceil(input.prompt.length / CHARS_PER_TOKEN_APPROX);
+    const inputCost = (inputTokens / 1_000_000) * price.inputPer1M;
+    const perImage =
+        input.imageSize === "4K" ? price.outputPerImage4K : price.outputPerImage1Kor2K;
+    const outputCost = perImage * input.numberOfImages;
+    const total = inputCost + outputCost;
+    return {
+        estimatedUsd: total,
+        breakdown:
+            `${input.numberOfImages} × $${perImage.toFixed(3)} (${input.imageSize ?? "1K/2K"}) + ` +
+            `~${inputTokens} input tokens`,
+    };
+}
+
+export function formatUsd(usd: number): string {
+    if (usd < 0.01) return `<$0.01`;
+    return `$${usd.toFixed(4)}`;
+}
+
+export function hasPricing(model: ImageModel): boolean {
+    return model in PRICES;
+}

package/extensions/grimoire/index.test.ts

@@ -0,0 +1,244 @@
+import { EventEmitter } from "node:events";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock node:child_process BEFORE importing the module under test.
+vi.mock("node:child_process", () => {
+    const mod = {
+        execFileSync: vi.fn(),
+        spawn: vi.fn(),
+    };
+    return mod;
+});
+
+type SpawnFactory = () => { proc: EventEmitter & { stdout: EventEmitter; stderr: EventEmitter; kill: (sig: string) => void }; emitClose: (code: number) => void; emitError: (err: Error) => void; emitData: (where: "stdout" | "stderr", chunk: string) => void };
+
+function makeFakeProc(): ReturnType<SpawnFactory> {
+    const proc = Object.assign(new EventEmitter(), {
+        stdout: new EventEmitter(),
+        stderr: new EventEmitter(),
+        kill: vi.fn(),
+    });
+    return {
+        proc,
+        emitClose: (code: number) => proc.emit("close", code),
+        emitError: (err: Error) => proc.emit("error", err),
+        emitData: (where, chunk) => proc[where].emit("data", Buffer.from(chunk)),
+    };
+}
+
+interface CapturedTool {
+    name: string;
+    description: string;
+    promptGuidelines?: string[];
+    execute: (id: string, input: { query: string; source?: string; top?: number }, signal?: AbortSignal, onUpdate?: unknown, ctx?: unknown) => Promise<unknown>;
+}
+
+interface CapturedPi {
+    registerTool: (tool: CapturedTool) => void;
+    tools: CapturedTool[];
+}
+
+function makePi(): CapturedPi {
+    const tools: CapturedTool[] = [];
+    return {
+        tools,
+        registerTool: (tool) => {
+            tools.push(tool);
+        },
+    };
+}
+
+function makeCtx(): { ui: { notify: ReturnType<typeof vi.fn> }; notifications: Array<[string, string | undefined]> } {
+    const notifications: Array<[string, string | undefined]> = [];
+    return {
+        notifications,
+        ui: {
+            notify: vi.fn((msg: string, type?: string) => {
+                notifications.push([msg, type]);
+            }),
+        },
+    };
+}
+
+describe("grimoire extension", () => {
+    beforeEach(() => {
+        vi.resetModules();
+        vi.clearAllMocks();
+    });
+
+    afterEach(() => {
+        vi.clearAllMocks();
+    });
+
+    it("loads --help into promptGuidelines when grimoire is available", async () => {
+        const { execFileSync } = await import("node:child_process");
+        vi.mocked(execFileSync).mockReturnValue("FAKE HELP OUTPUT" as unknown as ReturnType<typeof execFileSync>);
+
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+
+        const tool = pi.tools[0];
+        expect(tool.name).toBe("grimoire");
+        expect(tool.promptGuidelines?.some((g) => g.includes("FAKE HELP OUTPUT"))).toBe(true);
+    });
+
+    it("falls back to 'not available' promptGuidelines when grimoire CLI is missing", async () => {
+        const { execFileSync } = await import("node:child_process");
+        vi.mocked(execFileSync).mockImplementation(() => {
+            throw new Error("ENOENT");
+        });
+
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+
+        expect(pi.tools[0].promptGuidelines?.[0]).toMatch(/NOT available/i);
+    });
+
+    it("execute throws when CLI was not available at load time", async () => {
+        const { execFileSync } = await import("node:child_process");
+        vi.mocked(execFileSync).mockImplementation(() => {
+            throw new Error("ENOENT");
+        });
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        await expect(
+            pi.tools[0].execute("t1", { query: "x" }, undefined, undefined, ctx),
+        ).rejects.toThrow(/not installed/i);
+        expect(ctx.notifications.some((n) => n[1] === "error")).toBe(true);
+    });
+
+    it("execute returns stdout when grimoire exits 0 with results", async () => {
+        const { execFileSync, spawn } = await import("node:child_process");
+        vi.mocked(execFileSync).mockReturnValue("help" as unknown as ReturnType<typeof execFileSync>);
+        const fake = makeFakeProc();
+        vi.mocked(spawn).mockReturnValue(fake.proc as unknown as ReturnType<typeof spawn>);
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        const promise = pi.tools[0].execute("t1", { query: "react hooks" }, undefined, undefined, ctx);
+        fake.emitData("stdout", "result line 1\nresult line 2\n");
+        fake.emitClose(0);
+        const result = (await promise) as { content: Array<{ text: string }> };
+        expect(result.content[0].text).toContain("result line 1");
+    });
+
+    it("execute with source + top passes them through as CLI args", async () => {
+        const { execFileSync, spawn } = await import("node:child_process");
+        vi.mocked(execFileSync).mockReturnValue("help" as unknown as ReturnType<typeof execFileSync>);
+        const fake = makeFakeProc();
+        vi.mocked(spawn).mockReturnValue(fake.proc as unknown as ReturnType<typeof spawn>);
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        const promise = pi.tools[0].execute("t", { query: "q", source: "react", top: 3 }, undefined, undefined, ctx);
+        fake.emitData("stdout", "out");
+        fake.emitClose(0);
+        await promise;
+        const callArgs = vi.mocked(spawn).mock.calls[0][1] as string[];
+        expect(callArgs).toContain("--source");
+        expect(callArgs).toContain("react");
+        expect(callArgs).toContain("--top");
+        expect(callArgs).toContain("3");
+    });
+
+    it("execute notifies warning and returns soft result on no-results", async () => {
+        const { execFileSync, spawn } = await import("node:child_process");
+        vi.mocked(execFileSync).mockReturnValue("help" as unknown as ReturnType<typeof execFileSync>);
+        const fake = makeFakeProc();
+        vi.mocked(spawn).mockReturnValue(fake.proc as unknown as ReturnType<typeof spawn>);
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        const promise = pi.tools[0].execute("t", { query: "zzz" }, undefined, undefined, ctx);
+        fake.emitData("stdout", "No results found.\n");
+        fake.emitClose(0);
+        const result = (await promise) as { content: Array<{ text: string }> };
+        expect(result.content[0].text).toMatch(/No results found/);
+        expect(ctx.notifications.some((n) => n[1] === "warning")).toBe(true);
+    });
+
+    it("execute also treats empty stdout as no-results and suggests widening scope when source given", async () => {
+        const { execFileSync, spawn } = await import("node:child_process");
+        vi.mocked(execFileSync).mockReturnValue("help" as unknown as ReturnType<typeof execFileSync>);
+        const fake = makeFakeProc();
+        vi.mocked(spawn).mockReturnValue(fake.proc as unknown as ReturnType<typeof spawn>);
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        const promise = pi.tools[0].execute("t", { query: "zzz", source: "react" }, undefined, undefined, ctx);
+        fake.emitData("stdout", "");
+        fake.emitClose(0);
+        const result = (await promise) as { content: Array<{ text: string }> };
+        expect(result.content[0].text).toMatch(/widening scope/);
+    });
+
+    it("execute rejects on non-zero exit code", async () => {
+        const { execFileSync, spawn } = await import("node:child_process");
+        vi.mocked(execFileSync).mockReturnValue("help" as unknown as ReturnType<typeof execFileSync>);
+        const fake = makeFakeProc();
+        vi.mocked(spawn).mockReturnValue(fake.proc as unknown as ReturnType<typeof spawn>);
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        const promise = pi.tools[0].execute("t", { query: "q" }, undefined, undefined, ctx);
+        fake.emitData("stderr", "bad source");
+        fake.emitClose(1);
+        await expect(promise).rejects.toThrow(/exited with code 1/);
+    });
+
+    it("execute rejects on ENOENT at spawn time with install guidance + notify", async () => {
+        const { execFileSync, spawn } = await import("node:child_process");
+        vi.mocked(execFileSync).mockReturnValue("help" as unknown as ReturnType<typeof execFileSync>);
+        const fake = makeFakeProc();
+        vi.mocked(spawn).mockReturnValue(fake.proc as unknown as ReturnType<typeof spawn>);
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        const promise = pi.tools[0].execute("t", { query: "q" }, undefined, undefined, ctx);
+        const err = Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+        fake.emitError(err);
+        await expect(promise).rejects.toThrow(/not installed/i);
+        expect(ctx.notifications.some((n) => n[1] === "error")).toBe(true);
+    });
+
+    it("execute rejects on non-ENOENT spawn error", async () => {
+        const { execFileSync, spawn } = await import("node:child_process");
+        vi.mocked(execFileSync).mockReturnValue("help" as unknown as ReturnType<typeof execFileSync>);
+        const fake = makeFakeProc();
+        vi.mocked(spawn).mockReturnValue(fake.proc as unknown as ReturnType<typeof spawn>);
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        const promise = pi.tools[0].execute("t", { query: "q" }, undefined, undefined, ctx);
+        fake.emitError(new Error("mystery"));
+        await expect(promise).rejects.toThrow(/failed to run/i);
+    });
+
+    it("execute kills process on abort signal", async () => {
+        const { execFileSync, spawn } = await import("node:child_process");
+        vi.mocked(execFileSync).mockReturnValue("help" as unknown as ReturnType<typeof execFileSync>);
+        const fake = makeFakeProc();
+        vi.mocked(spawn).mockReturnValue(fake.proc as unknown as ReturnType<typeof spawn>);
+        const mod = await import("./index.ts");
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        const ctx = makeCtx();
+        const ac = new AbortController();
+        const promise = pi.tools[0].execute("t", { query: "q" }, ac.signal, undefined, ctx);
+        ac.abort();
+        expect(fake.proc.kill).toHaveBeenCalledWith("SIGTERM");
+        fake.emitClose(0);
+        await expect(promise).resolves.toBeDefined();
+    });
+});