@aerok/pi-toolkit 0.1.0

package/extensions/bark/types.ts

@@ -0,0 +1,68 @@
+export type BarkLevel = "critical" | "active" | "timeSensitive" | "passive";
+export type NotifyPriority = "low" | "normal" | "high";
+export type EncryptionMode = "encrypted" | "plaintext";
+
+export interface BarkEncryptionConfig {
+  mode: EncryptionMode;
+  key?: string;
+  iv?: string;
+}
+
+export type BarkEventKey =
+  | "agent_settled"
+  | "agent_end"
+  | "session_shutdown"
+  | "ask_user_prompt"
+  | "permission_request";
+
+export interface RecapConfig {
+  enabled: boolean;
+  /** provider/model-id; empty means the current session model. */
+  model?: string;
+}
+
+export interface BarkGlobalConfig {
+  version: 2;
+  enabled: boolean;
+  serverUrl: string;
+  deviceKey?: string;
+  group?: string;
+  sound?: string;
+  icon?: string;
+  level: BarkLevel;
+  encryption: BarkEncryptionConfig;
+  events: Record<BarkEventKey, boolean>;
+  recap: RecapConfig;
+}
+
+/** Project files never contain server URLs or device keys. */
+export interface BarkProjectConfig {
+  version: 1;
+  enabled?: boolean;
+  group?: string | null;
+  sound?: string | null;
+  icon?: string | null;
+  level?: BarkLevel;
+  events?: Partial<Record<BarkEventKey, boolean>>;
+  recap?: Partial<RecapConfig>;
+}
+
+export interface ResolvedBarkConfig extends BarkGlobalConfig {
+  projectOverride: boolean;
+}
+
+export interface BarkNotification {
+  title: string;
+  body: string;
+  level?: BarkLevel;
+  group?: string;
+  sound?: string;
+  icon?: string;
+  call?: boolean;
+}
+
+export interface CachedModel {
+  provider: string;
+  id: string;
+  name?: string;
+}

package/extensions/image-placeholders/README.md

@@ -0,0 +1,22 @@
+# 图片粘贴占位符扩展
+
+这是 `pi-toolkit` 的独立图片扩展。在 Pi TUI 中粘贴剪贴板图片时，将默认临时文件长路径显示为紧凑占位符：
+
+```text
+[Image 1]
+[Image 2]
+```
+
+提交消息时，扩展会把占位符对应的图片作为真实图片附件发送给模型；占位符文字保留，便于引用具体图片。
+
+## 行为
+
+- 图片编号按单次提问独立计算，成功提交后重新从 `[Image 1]` 开始。
+- 使用当前主题强调色和粗体高亮有效占位符。
+- 兼容已有会话中的旧格式 `[图片N]`。
+- 删除未提交占位符后清理对应临时文件。
+- 从输入历史重新提交时重新附加原图片。
+- 当前模型不支持图片输入时阻止发送并恢复原输入。
+- 包装当前主编辑器，可与其他自定义编辑器扩展组合。
+
+由 `pi-toolkit` package manifest 自动加载，不要同时保留全局 `~/.pi/agent/extensions/image-placeholders` 副本。

package/extensions/image-placeholders/index.ts

@@ -0,0 +1,312 @@
+import { readFile, rm } from "node:fs/promises";
+import { basename, extname } from "node:path";
+
+import {
+	CustomEditor,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { ImageContent } from "@earendil-works/pi-ai";
+
+// Accept the previous Chinese markers when restoring existing session history.
+const MARKER_PATTERN = /\[(?:Image\s+|图片)(\d+)\]/gi;
+const CLIPBOARD_FILE_PATTERN = /^pi-clipboard-[0-9a-f-]+\.(?:png|jpe?g|webp|gif)$/i;
+const SHARED_STATE_KEY = Symbol.for("pi.image-placeholders.state.v2");
+const WRAPPED_FACTORY_KEY = Symbol.for("pi.image-placeholders.wrapped-factory.v2");
+const PATCHED_EDITOR_KEY = Symbol.for("pi.image-placeholders.patched-editor.v2");
+
+interface StoredImage {
+	id: number;
+	path?: string;
+	data?: string;
+	mimeType: string;
+	submitted: boolean;
+}
+
+interface PlaceholderState {
+	attachments: Map<number, StoredImage>;
+	history: Map<string, Map<number, StoredImage>>;
+	nextId: number;
+}
+
+type GlobalSymbolRegistry = typeof globalThis & {
+	[key: symbol]: unknown;
+};
+
+function getSharedStates(): Map<string, PlaceholderState> {
+	const globalState = globalThis as GlobalSymbolRegistry;
+	const existing = globalState[SHARED_STATE_KEY];
+	if (existing instanceof Map) {
+		return existing as Map<string, PlaceholderState>;
+	}
+
+	const states = new Map<string, PlaceholderState>();
+	globalState[SHARED_STATE_KEY] = states;
+	return states;
+}
+
+function sessionKey(ctx: ExtensionContext): string {
+	return ctx.sessionManager.getSessionFile() ?? `ephemeral:${ctx.cwd}`;
+}
+
+function markerFor(id: number): string {
+	return `[Image ${id}]`;
+}
+
+function extractMarkerIds(text: string): number[] {
+	const ids: number[] = [];
+	const seen = new Set<number>();
+
+	for (const match of text.matchAll(MARKER_PATTERN)) {
+		const id = Number(match[1]);
+		if (Number.isSafeInteger(id) && id > 0 && !seen.has(id)) {
+			seen.add(id);
+			ids.push(id);
+		}
+	}
+
+	return ids;
+}
+
+function mimeTypeForPath(path: string): string | undefined {
+	switch (extname(path).toLowerCase()) {
+		case ".png":
+			return "image/png";
+		case ".jpg":
+		case ".jpeg":
+			return "image/jpeg";
+		case ".webp":
+			return "image/webp";
+		case ".gif":
+			return "image/gif";
+		default:
+			return undefined;
+	}
+}
+
+function isPiClipboardImagePath(text: string): boolean {
+	return CLIPBOARD_FILE_PATTERN.test(basename(text)) && mimeTypeForPath(text) !== undefined;
+}
+
+async function removeTempFile(path: string | undefined): Promise<void> {
+	if (!path) return;
+	await rm(path, { force: true }).catch(() => undefined);
+}
+
+function restoreSubmittedImages(ctx: ExtensionContext, state: PlaceholderState): void {
+	const history = new Map<string, Map<number, StoredImage>>();
+
+	for (const entry of ctx.sessionManager.getBranch()) {
+		if (entry.type !== "message" || entry.message.role !== "user") continue;
+
+		const content = entry.message.content;
+		if (!Array.isArray(content)) continue;
+
+		const text = content
+			.filter((block): block is { type: "text"; text: string } => block.type === "text")
+			.map((block) => block.text)
+			.join("\n");
+		const markerIds = extractMarkerIds(text);
+		const images = content.filter((block): block is ImageContent => block.type === "image");
+		const promptImages = new Map<number, StoredImage>();
+
+		for (let index = 0; index < Math.min(markerIds.length, images.length); index++) {
+			const id = markerIds[index]!;
+			const image = images[index]!;
+			promptImages.set(id, {
+				id,
+				data: image.data,
+				mimeType: image.mimeType,
+				submitted: true,
+			});
+		}
+
+		if (promptImages.size > 0) history.set(text, promptImages);
+	}
+
+	state.history = history;
+	state.nextId = state.attachments.size > 0
+		? Math.max(...state.attachments.keys()) + 1
+		: 1;
+}
+
+function restoreEditorAfterFailure(ctx: ExtensionContext, text: string, message: string): void {
+	ctx.ui.setEditorText(text);
+	ctx.ui.notify(message, "error");
+}
+
+function replaceClipboardPath(text: string, state: PlaceholderState): string {
+	if (!isPiClipboardImagePath(text)) return text;
+
+	const id = state.nextId++;
+	state.attachments.set(id, {
+		id,
+		path: text,
+		mimeType: mimeTypeForPath(text)!,
+		submitted: false,
+	});
+	return markerFor(id);
+}
+
+export default function imagePlaceholders(pi: ExtensionAPI): void {
+	let state: PlaceholderState | undefined;
+	let activeSessionKey: string | undefined;
+	let installTimer: ReturnType<typeof setTimeout> | undefined;
+	let terminalInputUnsubscribe: (() => void) | undefined;
+
+	const installEditorWrapper = (ctx: ExtensionContext): void => {
+		if (!state || ctx.mode !== "tui") return;
+
+		const previousFactory = ctx.ui.getEditorComponent();
+		if (previousFactory && Reflect.get(previousFactory, WRAPPED_FACTORY_KEY) === true) return;
+
+		const wrappedFactory: NonNullable<ReturnType<typeof ctx.ui.getEditorComponent>> = (
+			tui,
+			theme,
+			keybindings,
+		) => {
+			const editor = previousFactory?.(tui, theme, keybindings) ?? new CustomEditor(tui, theme, keybindings);
+			if (Reflect.get(editor, PATCHED_EDITOR_KEY) === true) return editor;
+
+			const originalInsert = Reflect.get(editor, "insertTextAtCursor");
+			if (typeof originalInsert === "function") {
+				Reflect.set(editor, "insertTextAtCursor", (text: string) => {
+					originalInsert.call(editor, state ? replaceClipboardPath(text, state) : text);
+				});
+			}
+
+			const originalRender = Reflect.get(editor, "render");
+			if (typeof originalRender === "function") {
+				Reflect.set(editor, "render", (width: number): string[] => {
+					const lines = originalRender.call(editor, width) as string[];
+					if (!state) return lines;
+
+					const getEditorText = Reflect.get(editor, "getExpandedText") ?? Reflect.get(editor, "getText");
+					const editorText = typeof getEditorText === "function" ? getEditorText.call(editor) as string : "";
+					const activeImages = state.attachments.size > 0
+						? state.attachments
+						: state.history.get(editorText);
+
+					return lines.map((line) =>
+						line.replace(MARKER_PATTERN, (marker, rawId: string) => {
+							const id = Number(rawId);
+							if (!activeImages?.has(id)) return marker;
+							return ctx.ui.theme.fg("accent", ctx.ui.theme.bold(marker));
+						}),
+					);
+				});
+			}
+			Reflect.set(editor, PATCHED_EDITOR_KEY, true);
+			return editor;
+		};
+
+		Reflect.set(wrappedFactory, WRAPPED_FACTORY_KEY, true);
+		ctx.ui.setEditorComponent(wrappedFactory);
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		activeSessionKey = sessionKey(ctx);
+		const sharedStates = getSharedStates();
+		state = sharedStates.get(activeSessionKey) ?? {
+			attachments: new Map<number, StoredImage>(),
+			history: new Map<string, Map<number, StoredImage>>(),
+			nextId: 1,
+		};
+		sharedStates.set(activeSessionKey, state);
+		restoreSubmittedImages(ctx, state);
+
+		if (ctx.mode !== "tui") return;
+
+		// Other extensions (notably pi-powerline-footer) install their editor during
+		// session_start. Defer composition so we wrap the final editor instead of
+		// replacing it, and repair the wrapper if a later extension replaces it.
+		installTimer = setTimeout(() => installEditorWrapper(ctx), 50);
+		terminalInputUnsubscribe = ctx.ui.onTerminalInput(() => {
+			installEditorWrapper(ctx);
+			return undefined;
+		});
+	});
+
+	pi.on("session_tree", (_event, ctx) => {
+		if (state) restoreSubmittedImages(ctx, state);
+	});
+
+	pi.on("input", async (event, ctx) => {
+		if (event.source !== "interactive" || !state) {
+			return { action: "continue" };
+		}
+
+		const markerIds = extractMarkerIds(event.text);
+		const referencedIds = new Set(markerIds);
+
+		for (const [id, image] of state.attachments) {
+			if (!referencedIds.has(id)) {
+				await removeTempFile(image.path);
+				state.attachments.delete(id);
+			}
+		}
+
+		const sourceImages = state.attachments.size > 0
+			? state.attachments
+			: state.history.get(event.text);
+		const referencedImages = markerIds
+			.map((id) => sourceImages?.get(id))
+			.filter((image): image is StoredImage => image !== undefined);
+		if (referencedImages.length === 0) {
+			state.nextId = 1;
+			return { action: "continue" };
+		}
+
+		if (ctx.model && !ctx.model.input.includes("image")) {
+			restoreEditorAfterFailure(ctx, event.text, `当前模型 ${ctx.model.id} 不支持图片输入`);
+			return { action: "handled" };
+		}
+
+		const images: ImageContent[] = [];
+		const archivedImages = new Map<number, StoredImage>();
+		for (const image of referencedImages) {
+			try {
+				if (!image.data) {
+					if (!image.path) throw new Error("临时图片路径不存在");
+					image.data = (await readFile(image.path)).toString("base64");
+					await removeTempFile(image.path);
+					image.path = undefined;
+				}
+				image.submitted = true;
+				images.push({ type: "image", data: image.data, mimeType: image.mimeType });
+				archivedImages.set(image.id, { ...image, path: undefined, submitted: true });
+			} catch (error) {
+				const reason = error instanceof Error ? error.message : String(error);
+				restoreEditorAfterFailure(ctx, event.text, `${markerFor(image.id)} 读取失败：${reason}`);
+				return { action: "handled" };
+			}
+		}
+
+		state.history.set(event.text, archivedImages);
+		state.attachments.clear();
+		state.nextId = 1;
+
+		return {
+			action: "transform",
+			text: event.text,
+			// Keep placeholder images first so they can be reconstructed from session history.
+			images: [...images, ...(event.images ?? [])],
+		};
+	});
+
+	pi.on("session_shutdown", async (event) => {
+		if (installTimer) clearTimeout(installTimer);
+		installTimer = undefined;
+		terminalInputUnsubscribe?.();
+		terminalInputUnsubscribe = undefined;
+
+		if (!state || !activeSessionKey || event.reason === "reload") return;
+
+		await Promise.all(
+			[...state.attachments.values()].map((image) => removeTempFile(image.path)),
+		);
+		getSharedStates().delete(activeSessionKey);
+		state = undefined;
+		activeSessionKey = undefined;
+	});
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@aerok/pi-toolkit",
+  "version": "0.1.0",
+  "description": "Encrypted Bark notifications and image paste placeholders for Pi",
+  "type": "module",
+  "license": "MIT",
+  "author": "wayne1943x",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wayne1943x/pi-toolkit.git"
+  },
+  "homepage": "https://github.com/wayne1943x/pi-toolkit#readme",
+  "bugs": {
+    "url": "https://github.com/wayne1943x/pi-toolkit/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "toolkit",
+    "bark",
+    "notifications",
+    "encryption",
+    "ios",
+    "image-paste"
+  ],
+  "scripts": {
+    "test": "tsx --test tests/**/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test"
+  },
+  "files": [
+    "extensions/**/*.ts",
+    "extensions/**/*.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/bark/index.ts",
+      "./extensions/image-placeholders/index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "^0.84.0",
+    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "@earendil-works/pi-tui": "^0.84.0",
+    "typebox": "^1.1.38"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.84.0",
+    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "@earendil-works/pi-tui": "^0.84.0",
+    "@types/node": "^25.0.0",
+    "tsx": "^4.21.0",
+    "typebox": "^1.1.38",
+    "typescript": "^6.0.0"
+  }
+}