@clementprevot/pi-show-image 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clément Prévot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# @clementprevot/pi-show-image
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [Pi](https://pi.dev) extension that lets the agent show you a local image inline in the terminal, for example a screenshot it took during QA. Only you see the image: the agent gets back one line of text, so showing an image costs no image tokens.
+
+## Install
+
+```bash
+pi install npm:@clementprevot/pi-show-image
+```
+
+Updates ship with `pi update --extensions`. The extension applies to your next session (quit and relaunch, or run `/reload`).
+
+## Usage
+
+The agent calls the `show_image` tool:
+
+```json
+{ "path": "/tmp/login-page.png", "caption": "Login page after the fix" }
+```
+
+- `path`: a local PNG file, absolute, relative to the working directory, or starting with `~/`.
+- `caption` (optional): one line shown above the image.
+
+You can show an image yourself with `/show-image <path>`.
+
+To have your agent use it, add a line like this one to your instructions: "To show me an image, call `show_image` with its path."
+
+## How it works
+
+1. The tool resolves the path and checks that the file exists and is a PNG.
+2. It records a custom session entry with the path and the caption, and nothing else: no image data lands in the session file.
+3. An entry renderer reads the file and draws it with pi's `Image` component, at 60 cells wide. Pi picks the terminal image protocol (Kitty graphics or iTerm2) and falls back to a text placeholder on terminals without image support.
+4. Custom entries never enter the model context, so the agent only sees the tool's text result.
+
+Because the entry holds a path, a session reopened after the file was deleted shows a notice instead of the image.
+
+## Limits
+
+- PNG only. Kitty-protocol terminals (Kitty, Ghostty, WezTerm) only accept PNG, and pi converts other formats only for its own tool results. Convert other formats first, for example `sips -s format png photo.jpg --out photo.png` on macOS or `magick photo.jpg photo.png`.
+- Interactive sessions only. In print or RPC mode the tool reports an error, since there is no terminal to draw in.
+- Inside tmux or other multiplexers, images depend on pi's terminal detection and on the multiplexer forwarding the image protocol.
+
+## Privacy and data
+
+The extension reads the files you or the agent point it at and writes their paths to the session file. It makes no network calls and collects no data.
+
+## Local development
+
+```bash
+npm install
+npm test
+npm run typecheck
+```
+
+To try the extension in a live session without installing it:
+
+```bash
+pi -e /path/to/this/repo
+```
+
+## License
+
+[MIT](LICENSE)

package/index.ts

@@ -0,0 +1,113 @@
+import { readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, resolve } from "node:path";
+import { detectSupportedImageMimeTypeFromFile, type ExtensionAPI, type Theme } from "@earendil-works/pi-coding-agent";
+import { Container, Image, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+export const ENTRY_TYPE = "show-image";
+const WIDTH_CELLS = 60;
+
+export type ShownImage = {
+	path: string;
+	caption?: string;
+};
+
+export function resolveImagePath(input: string, cwd: string, home = homedir()): string {
+	const path = input.trim();
+	if (path === "~") return home;
+	if (path.startsWith("~/")) return resolve(home, path.slice(2));
+	return resolve(cwd, path);
+}
+
+/** Throws errors whose message is shown as-is to the model or the user. */
+export async function showImage(
+	pi: Pick<ExtensionAPI, "appendEntry">,
+	input: ShownImage,
+	cwd: string,
+	hasUI: boolean,
+): Promise<string> {
+	if (!input.path.trim()) throw new Error("Give the path of the image to show.");
+	const path = resolveImagePath(input.path, cwd);
+	let mimeType: string | null;
+	try {
+		if (!statSync(path).isFile()) throw new Error(`${path} is not a file.`);
+		mimeType = await detectSupportedImageMimeTypeFromFile(path);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new Error(`No file at ${path}.`);
+		throw error;
+	}
+	// Kitty-protocol terminals only accept PNG, and pi converts other formats only for its own tool results.
+	if (mimeType !== "image/png") {
+		throw new Error(
+			`${path} is not a still PNG image. Convert it first, for example with \`sips -s format png <file> --out <file>.png\` on macOS or \`magick <file> <file>.png\`.`,
+		);
+	}
+	if (!hasUI) throw new Error("No interactive terminal in this session: the image cannot be shown.");
+	const caption = input.caption?.trim();
+	pi.appendEntry<ShownImage>(ENTRY_TYPE, caption ? { path, caption } : { path });
+	return `Showed ${path} to the user. The image was not sent to you.`;
+}
+
+export function renderShownImage(data: ShownImage | undefined, theme: Theme): Container {
+	const container = new Container();
+	if (!data?.path) {
+		container.addChild(new Text(theme.fg("warning", "show-image: entry without a path"), 1, 0));
+		return container;
+	}
+	const caption = data.caption ? `${data.caption} ` : "";
+	container.addChild(new Text(`${theme.fg("accent", caption)}${theme.fg("muted", data.path)}`, 1, 0));
+	let base64: string;
+	try {
+		base64 = readFileSync(data.path).toString("base64");
+	} catch {
+		container.addChild(new Text(theme.fg("warning", "The image file is no longer available."), 1, 0));
+		return container;
+	}
+	container.addChild(
+		new Image(
+			base64,
+			"image/png",
+			{ fallbackColor: (text) => theme.fg("muted", text) },
+			{ maxWidthCells: WIDTH_CELLS, filename: basename(data.path) },
+		),
+	);
+	return container;
+}
+
+export default function showImageExtension(pi: ExtensionAPI): void {
+	pi.registerEntryRenderer<ShownImage>(ENTRY_TYPE, (entry, _options, theme) => renderShownImage(entry.data, theme));
+
+	pi.registerTool({
+		name: "show_image",
+		label: "Show image",
+		description:
+			"Show a local PNG image to the user, inline in the terminal. The image is not sent to you: use read when you need to look at it yourself.",
+		promptSnippet: "Show a local PNG image (screenshot, chart) to the user inline in the terminal",
+		promptGuidelines: [
+			"Use show_image when the user should see an image, for example a screenshot taken during QA.",
+			"show_image does not send the image to you; use read when you need to inspect it.",
+		],
+		parameters: Type.Object({
+			path: Type.String({
+				description: "Path to a local PNG file: absolute, relative to the working directory, or starting with ~/",
+			}),
+			caption: Type.Optional(Type.String({ description: "One line telling the user what the image shows" })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const text = await showImage(pi, params, ctx.cwd, ctx.hasUI);
+			return { content: [{ type: "text", text }], details: undefined };
+		},
+	});
+
+	pi.registerCommand("show-image", {
+		description: "Show a local PNG image inline: /show-image <path>",
+		handler: async (args, ctx) => {
+			try {
+				await showImage(pi, { path: args }, ctx.cwd, ctx.hasUI);
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			}
+		},
+	});
+}

package/package.json

@@ -1,6 +1,50 @@
 {
-  "name": "@clementprevot/pi-show-image",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@clementprevot/pi-show-image",
+	"version": "0.1.0",
+	"description": "Pi extension that lets the agent show you a local image inline in the terminal, without sending the image to the model",
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"image",
+		"screenshot",
+		"kitty",
+		"iterm2",
+		"tui"
+	],
+	"license": "MIT",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/clementprevot/pi-show-image.git"
+	},
+	"engines": {
+		"node": ">=22.6"
+	},
+	"files": [
+		"index.ts"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"@types/node": "^24.0.0",
+		"typebox": "*",
+		"typescript": "^5.9.0"
+	},
+	"scripts": {
+		"test": "node --test test/*.test.ts",
+		"typecheck": "tsc --noEmit"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}