@oh-my-pi/pi-coding-agent 3.15.1 → 3.20.1

package/examples/sdk/06-hooks.ts

@@ -2,12 +2,13 @@
  * Hooks Configuration
  *
  * Hooks intercept agent events for logging, blocking, or modification.
+ * Note: "hooks" is now called "extensions" in the API.
  */
 
-import { createAgentSession, type HookFactory, SessionManager } from "@oh-my-pi/pi-coding-agent";
+import { createAgentSession, type ExtensionFactory, SessionManager } from "@oh-my-pi/pi-coding-agent";
 
-// Logging hook
-const loggingHook: HookFactory = (api) => {
+// Logging hook (now called extension)
+const loggingHook: ExtensionFactory = (api) => {
 	api.on("agent_start", async () => {
 		console.log("[Hook] Agent starting");
 	});
@@ -22,8 +23,8 @@ const loggingHook: HookFactory = (api) => {
 	});
 };
 
-// Blocking hook (returns { block: true, reason: "..." })
-const safetyHook: HookFactory = (api) => {
+// Blocking extension (returns { block: true, reason: "..." })
+const safetyHook: ExtensionFactory = (api) => {
 	api.on("tool_call", async (event) => {
 		if (event.toolName === "bash") {
 			const cmd = (event.input as { command?: string }).command ?? "";
@@ -35,9 +36,9 @@ const safetyHook: HookFactory = (api) => {
 	});
 };
 
-// Use inline hooks
+// Use inline extensions (hooks is now extensions)
 const { session } = await createAgentSession({
-	hooks: [{ factory: loggingHook }, { factory: safetyHook }],
+	extensions: [loggingHook, safetyHook],
 	sessionManager: SessionManager.inMemory(),
 });
 
@@ -50,12 +51,12 @@ session.subscribe((event) => {
 await session.prompt("List files in the current directory.");
 console.log();
 
-// Disable all hooks:
-// hooks: []
+// Disable all extensions:
+// extensions: []
 
-// Merge with discovered hooks:
-// const discovered = await discoverHooks();
-// hooks: [...discovered, { factory: myHook }]
+// Merge with discovered extensions:
+// const discovered = await discoverExtensions();
+// extensions: [...discovered.extensions.map(e => e.factory), myHook]
 
 // Add paths without replacing discovery:
-// additionalHookPaths: ["/extra/hooks"]
+// additionalExtensionPaths: ["/extra/extensions"]

package/examples/sdk/08-prompt-templates.ts

@@ -0,0 +1,42 @@
+/**
+ * Prompt Templates
+ *
+ * File-based templates that inject content when invoked with /templatename.
+ */
+
+import {
+	createAgentSession,
+	discoverPromptTemplates,
+	type PromptTemplate,
+	SessionManager,
+} from "@oh-my-pi/pi-coding-agent";
+
+// Discover templates from cwd/.pi/prompts/ and ~/.pi/agent/prompts/
+const discovered = await discoverPromptTemplates();
+console.log("Discovered prompt templates:");
+for (const template of discovered) {
+	console.log(`  /${template.name}: ${template.description}`);
+}
+
+// Define custom templates
+const deployTemplate: PromptTemplate = {
+	name: "deploy",
+	description: "Deploy the application",
+	source: "(custom)",
+	content: `# Deploy Instructions
+
+1. Build: npm run build
+2. Test: npm test
+3. Deploy: npm run deploy`,
+};
+
+// Use discovered + custom templates
+await createAgentSession({
+	promptTemplates: [...discovered, deployTemplate],
+	sessionManager: SessionManager.inMemory(),
+});
+
+console.log(`Session created with ${discovered.length + 1} prompt templates`);
+
+// Disable prompt templates:
+// promptTemplates: []

package/examples/sdk/08-slash-commands.ts

@@ -2,24 +2,25 @@
  * Slash Commands
  *
  * File-based commands that inject content when invoked with /commandname.
+ * Note: File-based slash commands are now called "prompt templates".
  */
 
 import {
 	createAgentSession,
-	discoverSlashCommands,
-	type FileSlashCommand,
+	discoverPromptTemplates,
+	type PromptTemplate,
 	SessionManager,
 } from "@oh-my-pi/pi-coding-agent";
 
-// Discover commands from cwd/.omp/commands/ and ~/.omp/agent/commands/
-const discovered = discoverSlashCommands();
-console.log("Discovered slash commands:");
+// Discover prompt templates from cwd/.pi/prompts/ and ~/.pi/agent/prompts/
+const discovered = await discoverPromptTemplates();
+console.log("Discovered prompt templates:");
 for (const cmd of discovered) {
 	console.log(`  /${cmd.name}: ${cmd.description}`);
 }
 
-// Define custom commands
-const deployCommand: FileSlashCommand = {
+// Define custom prompt templates
+const deployCommand: PromptTemplate = {
 	name: "deploy",
 	description: "Deploy the application",
 	source: "(custom)",
@@ -30,13 +31,17 @@ const deployCommand: FileSlashCommand = {
 3. Deploy: npm run deploy`,
 };
 
-// Use discovered + custom commands
+// Note: slashCommands is now managed by the agent session automatically.
+// Custom commands can be loaded via discoverCustomTSCommands() for TypeScript commands.
+// For file-based markdown commands, use promptTemplates instead.
+
+// Convert file-based slash commands to prompt templates
 await createAgentSession({
-	slashCommands: [...discovered, deployCommand],
+	promptTemplates: [...discovered, deployCommand],
 	sessionManager: SessionManager.inMemory(),
 });
 
-console.log(`Session created with ${discovered.length + 1} slash commands`);
+console.log(`Session created with ${discovered.length + 1} prompt templates`);
 
-// Disable slash commands:
-// slashCommands: []
+// Disable prompt templates:
+// promptTemplates: []

package/examples/sdk/09-api-keys-and-oauth.ts

@@ -15,8 +15,8 @@ import {
 
 // Default: discoverAuthStorage() uses ~/.omp/agent/auth.json
 // discoverModels() loads built-in + custom models from ~/.omp/agent/models.json
-const authStorage = discoverAuthStorage();
-const modelRegistry = discoverModels(authStorage);
+const authStorage = await discoverAuthStorage();
+const modelRegistry = await discoverModels(authStorage);
 
 await createAgentSession({
 	sessionManager: SessionManager.inMemory(),

package/examples/sdk/12-full-control.ts

@@ -15,7 +15,7 @@ import {
 	createAgentSession,
 	createBashTool,
 	createReadTool,
-	type HookFactory,
+	type ExtensionFactory,
 	ModelRegistry,
 	SessionManager,
 	SettingsManager,
@@ -33,8 +33,8 @@ if (process.env.MY_ANTHROPIC_KEY) {
 // Model registry with no custom models.json
 const modelRegistry = new ModelRegistry(authStorage);
 
-// Inline hook
-const auditHook: HookFactory = (api) => {
+// Inline extension
+const auditHook: ExtensionFactory = (api) => {
 	api.on("tool_call", async (event) => {
 		console.log(`[Audit] ${event.toolName}`);
 		return undefined;
@@ -76,11 +76,11 @@ const { session } = await createAgentSession({
 Available: read, bash, status. Be concise.`,
 	// Use factory functions with the same cwd to ensure path resolution works correctly
 	tools: [createReadTool(cwd), createBashTool(cwd)],
-	customTools: [{ tool: statusTool }],
-	hooks: [{ factory: auditHook }],
+	customTools: [statusTool],
+	extensions: [auditHook],
 	skills: [],
 	contextFiles: [],
-	slashCommands: [],
+	promptTemplates: [],
 	sessionManager: SessionManager.inMemory(),
 	settingsManager,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "3.15.1",
+	"version": "3.20.1",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"ompConfig": {
@@ -39,9 +39,11 @@
 		"prepublishOnly": "bun run generate-template && bun run clean && bun run build"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-agent-core": "3.15.1",
-		"@oh-my-pi/pi-ai": "3.15.1",
-		"@oh-my-pi/pi-tui": "3.15.1",
+		"@oh-my-pi/pi-agent-core": "3.20.1",
+		"@oh-my-pi/pi-ai": "3.20.1",
+		"@oh-my-pi/pi-git-tool": "3.20.1",
+		"@oh-my-pi/pi-tui": "3.20.1",
+		"@openai/agents": "^0.3.7",
 		"@sinclair/typebox": "^0.34.46",
 		"ajv": "^8.17.1",
 		"chalk": "^5.5.0",
@@ -55,18 +57,20 @@
 		"nanoid": "^5.1.6",
 		"ndjson": "^2.0.0",
 		"node-html-parser": "^6.1.13",
+		"sharp": "^0.34.2",
 		"smol-toml": "^1.6.0",
 		"strip-ansi": "^7.1.2",
-		"sharp": "^0.34.2",
 		"winston": "^3.17.0",
 		"winston-daily-rotate-file": "^5.0.0",
-		"yaml": "^2.8.2"
+		"yaml": "^2.8.2",
+		"zod": "^4.3.5"
 	},
 	"devDependencies": {
 		"@types/diff": "^7.0.2",
+		"@types/ms": "^2.1.0",
 		"@types/ndjson": "^2.0.4",
 		"@types/node": "^24.3.0",
-		"vitest": "^3.2.4"
+		"ms": "^2.1.3"
 	},
 	"keywords": [
 		"coding-agent",

package/src/capability/extension-module.ts

@@ -0,0 +1,34 @@
+/**
+ * Extension Modules Capability
+ *
+ * TypeScript/JavaScript extension modules loaded by the extension system.
+ */
+
+import { defineCapability } from "./index";
+import type { SourceMeta } from "./types";
+
+/**
+ * A loaded extension module.
+ */
+export interface ExtensionModule {
+	/** Extension module name (derived from path) */
+	name: string;
+	/** Absolute path to extension entrypoint */
+	path: string;
+	/** Source level */
+	level: "user" | "project";
+	/** Source metadata */
+	_source: SourceMeta;
+}
+
+export const extensionModuleCapability = defineCapability<ExtensionModule>({
+	id: "extension-modules",
+	displayName: "Extension Modules",
+	description: "TypeScript/JavaScript extension modules loaded by the extension system",
+	key: (ext) => ext.name,
+	validate: (ext) => {
+		if (!ext.name) return "Missing name";
+		if (!ext.path) return "Missing path";
+		return undefined;
+	},
+});

package/src/cli/args.ts

@@ -29,7 +29,7 @@ export interface Args {
 	models?: string[];
 	tools?: ToolName[];
 	hooks?: string[];
-	customTools?: string[];
+	extensions?: string[];
 	print?: boolean;
 	export?: string;
 	noSkills?: boolean;
@@ -37,6 +37,8 @@ export interface Args {
 	listModels?: string | true;
 	messages: string[];
 	fileArgs: string[];
+	/** Unknown flags (potentially extension flags) - map of flag name to value */
+	unknownFlags: Map<string, boolean | string>;
 }
 
 const VALID_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
@@ -45,10 +47,11 @@ export function isValidThinkingLevel(level: string): level is ThinkingLevel {
 	return VALID_THINKING_LEVELS.includes(level as ThinkingLevel);
 }
 
-export function parseArgs(args: string[]): Args {
+export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "boolean" | "string" }>): Args {
 	const result: Args = {
 		messages: [],
 		fileArgs: [],
+		unknownFlags: new Map(),
 	};
 
 	for (let i = 0; i < args.length; i++) {
@@ -120,9 +123,9 @@ export function parseArgs(args: string[]): Args {
 		} else if (arg === "--hook" && i + 1 < args.length) {
 			result.hooks = result.hooks ?? [];
 			result.hooks.push(args[++i]);
-		} else if (arg === "--tool" && i + 1 < args.length) {
-			result.customTools = result.customTools ?? [];
-			result.customTools.push(args[++i]);
+		} else if ((arg === "--extension" || arg === "-e") && i + 1 < args.length) {
+			result.extensions = result.extensions ?? [];
+			result.extensions.push(args[++i]);
 		} else if (arg === "--no-skills") {
 			result.noSkills = true;
 		} else if (arg === "--skills" && i + 1 < args.length) {
@@ -137,6 +140,18 @@ export function parseArgs(args: string[]): Args {
 			}
 		} else if (arg.startsWith("@")) {
 			result.fileArgs.push(arg.slice(1)); // Remove @ prefix
+		} else if (arg.startsWith("--") && extensionFlags) {
+			// Check if it's an extension-registered flag
+			const flagName = arg.slice(2);
+			const extFlag = extensionFlags.get(flagName);
+			if (extFlag) {
+				if (extFlag.type === "boolean") {
+					result.unknownFlags.set(flagName, true);
+				} else if (extFlag.type === "string" && i + 1 < args.length) {
+					result.unknownFlags.set(flagName, args[++i]);
+				}
+			}
+			// Unknown flags without extensionFlags are silently ignored (first pass)
 		} else if (!arg.startsWith("-")) {
 			result.messages.push(arg);
 		}
@@ -170,8 +185,8 @@ ${chalk.bold("Options:")}
   --tools <tools>                Comma-separated list of tools to enable (default: read,bash,edit,write)
                                  Available: read, bash, edit, write, grep, find, ls
   --thinking <level>             Set thinking level: off, minimal, low, medium, high, xhigh
-  --hook <path>                  Load a hook file (can be used multiple times)
-  --tool <path>                  Load a custom tool file (can be used multiple times)
+  --hook <path>                  Load a hook/extension file (can be used multiple times)
+  --extension, -e <path>         Load an extension file (can be used multiple times)
   --no-skills                    Disable skills discovery and loading
   --skills <patterns>            Comma-separated glob patterns to filter skills (e.g., git-*,docker)
   --export <file>                Export session file to HTML and exit

package/src/cli/file-processor.ts

@@ -2,12 +2,12 @@
  * Process @file CLI arguments into text content and image attachments
  */
 
-import { access, readFile, stat } from "node:fs/promises";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import type { ImageContent } from "@oh-my-pi/pi-ai";
 import chalk from "chalk";
-import sharp from "sharp";
 import { resolveReadPath } from "../core/tools/path-utils";
+import { formatDimensionNote, resizeImage } from "../utils/image-resize";
 import { detectSupportedImageMimeTypeFromFile } from "../utils/mime";
 
 export interface ProcessedFiles {
@@ -15,55 +15,14 @@ export interface ProcessedFiles {
 	images: ImageContent[];
 }
 
-const RESIZE_TRIGGER_MAX_DIMENSION = 2048;
-const MAX_RESIZE_WIDTH = 1920;
-const MAX_RESIZE_HEIGHT = 1080;
-const JPEG_CONVERT_THRESHOLD_BYTES = 2 * 1024 * 1024;
-const JPEG_QUALITY = 85;
-
-async function processImageAttachment(buffer: Buffer, mimeType: string): Promise<{ buffer: Buffer; mimeType: string }> {
-	const metadata = await sharp(buffer, { failOnError: false }).metadata();
-	const width = metadata.width ?? 0;
-	const height = metadata.height ?? 0;
-	const maxDim = Math.max(width, height);
-	const shouldResize = width > 0 && height > 0 && maxDim > RESIZE_TRIGGER_MAX_DIMENSION;
-	const shouldConvertToJpeg = buffer.length > JPEG_CONVERT_THRESHOLD_BYTES;
-
-	if (!shouldResize && !shouldConvertToJpeg) {
-		return { buffer, mimeType };
-	}
-
-	let pipeline = sharp(buffer, { failOnError: false });
-	if (shouldResize) {
-		pipeline = pipeline.resize({
-			width: MAX_RESIZE_WIDTH,
-			height: MAX_RESIZE_HEIGHT,
-			fit: "inside",
-			withoutEnlargement: true,
-		});
-	}
-
-	if (shouldConvertToJpeg) {
-		pipeline = pipeline.jpeg({ quality: JPEG_QUALITY });
-		return { buffer: await pipeline.toBuffer(), mimeType: "image/jpeg" };
-	}
-
-	if (mimeType === "image/png") {
-		pipeline = pipeline.png();
-	} else if (mimeType === "image/webp") {
-		pipeline = pipeline.webp();
-	} else if (mimeType === "image/gif") {
-		pipeline = pipeline.gif();
-	} else {
-		pipeline = pipeline.jpeg({ quality: JPEG_QUALITY });
-		return { buffer: await pipeline.toBuffer(), mimeType: "image/jpeg" };
-	}
-
-	return { buffer: await pipeline.toBuffer(), mimeType };
+export interface ProcessFileOptions {
+	/** Whether to auto-resize images to 2000x2000 max. Default: true */
+	autoResizeImages?: boolean;
 }
 
 /** Process @file arguments into text content and image attachments */
-export async function processFileArguments(fileArgs: string[]): Promise<ProcessedFiles> {
+export async function processFileArguments(fileArgs: string[], options?: ProcessFileOptions): Promise<ProcessedFiles> {
+	const _autoResizeImages = options?.autoResizeImages ?? true;
 	let text = "";
 	const images: ImageContent[] = [];
 
@@ -71,16 +30,12 @@ export async function processFileArguments(fileArgs: string[]): Promise<Processe
 		// Expand and resolve path (handles ~ expansion and macOS screenshot Unicode spaces)
 		const absolutePath = resolve(resolveReadPath(fileArg, process.cwd()));
 
-		// Check if file exists
-		try {
-			await access(absolutePath);
-		} catch {
+		// Check if file exists and is not empty
+		if (!existsSync(absolutePath)) {
 			console.error(chalk.red(`Error: File not found: ${absolutePath}`));
 			process.exit(1);
 		}
-
-		// Check if file is empty
-		const stats = await stat(absolutePath);
+		const stats = statSync(absolutePath);
 		if (stats.size === 0) {
 			// Skip empty files
 			continue;
@@ -90,24 +45,40 @@ export async function processFileArguments(fileArgs: string[]): Promise<Processe
 
 		if (mimeType) {
 			// Handle image file
-			const content = await readFile(absolutePath);
-			const processed = await processImageAttachment(content, mimeType);
-			const base64Content = processed.buffer.toString("base64");
-
-			const attachment: ImageContent = {
-				type: "image",
-				mimeType: processed.mimeType,
-				data: base64Content,
-			};
+			const buffer = readFileSync(absolutePath);
+			const base64Content = buffer.toString("base64");
+
+			let attachment: ImageContent;
+			let dimensionNote: string | undefined;
+
+			if (_autoResizeImages) {
+				const resized = await resizeImage({ type: "image", data: base64Content, mimeType });
+				dimensionNote = formatDimensionNote(resized);
+				attachment = {
+					type: "image",
+					mimeType: resized.mimeType,
+					data: resized.data,
+				};
+			} else {
+				attachment = {
+					type: "image",
+					mimeType,
+					data: base64Content,
+				};
+			}
 
 			images.push(attachment);
 
-			// Add text reference to image
-			text += `<file name="${absolutePath}"></file>\n`;
+			// Add text reference to image with optional dimension note
+			if (dimensionNote) {
+				text += `<file name="${absolutePath}">${dimensionNote}</file>\n`;
+			} else {
+				text += `<file name="${absolutePath}"></file>\n`;
+			}
 		} else {
 			// Handle text file
 			try {
-				const content = await readFile(absolutePath, "utf-8");
+				const content = readFileSync(absolutePath, "utf-8");
 				text += `<file name="${absolutePath}">\n${content}\n</file>\n`;
 			} catch (error: unknown) {
 				const message = error instanceof Error ? error.message : String(error);

package/src/cli/list-models.ts

@@ -25,7 +25,7 @@ function formatTokenCount(count: number): string {
  * List available models, optionally filtered by search pattern
  */
 export async function listModels(modelRegistry: ModelRegistry, searchPattern?: string): Promise<void> {
-	const models = await modelRegistry.getAvailable();
+	const models = modelRegistry.getAvailable();
 
 	if (models.length === 0) {
 		console.log("No models available. Set API keys in environment variables.");

package/src/config.ts

@@ -104,6 +104,11 @@ export function getCommandsDir(): string {
 	return join(getAgentDir(), "commands");
 }
 
+/** Get path to prompts directory */
+export function getPromptsDir(): string {
+	return join(getAgentDir(), "prompts");
+}
+
 /** Get path to sessions directory */
 export function getSessionsDir(): string {
 	return join(getAgentDir(), "sessions");
@@ -230,8 +235,8 @@ export function readConfigFile<T = unknown>(
 
 	for (const { path: base, source, level } of dirs) {
 		const filePath = join(base, subpath);
-		if (existsSync(filePath)) {
-			try {
+		try {
+			if (existsSync(filePath)) {
 				const content = readFileSync(filePath, "utf-8");
 				return {
 					path: filePath,
@@ -239,9 +244,9 @@ export function readConfigFile<T = unknown>(
 					level,
 					content: JSON.parse(content) as T,
 				};
-			} catch {
-				// Continue to next file on parse error
 			}
+		} catch {
+			// Continue to next file on parse error
 		}
 	}
 
@@ -261,8 +266,8 @@ export function readAllConfigFiles<T = unknown>(
 
 	for (const { path: base, source, level } of dirs) {
 		const filePath = join(base, subpath);
-		if (existsSync(filePath)) {
-			try {
+		try {
+			if (existsSync(filePath)) {
 				const content = readFileSync(filePath, "utf-8");
 				results.push({
 					path: filePath,
@@ -270,9 +275,9 @@ export function readAllConfigFiles<T = unknown>(
 					level,
 					content: JSON.parse(content) as T,
 				});
-			} catch {
-				// Skip files that fail to parse
 			}
+		} catch {
+			// Skip files that fail to parse
 		}
 	}
 
@@ -319,9 +324,9 @@ export function findConfigFileWithMeta(
 // Walk-Up Config Discovery (for monorepo scenarios)
 // =============================================================================
 
-function isDirectory(p: string): boolean {
+async function isDirectory(p: string): Promise<boolean> {
 	try {
-		return statSync(p).isDirectory();
+		return existsSync(p) && statSync(p).isDirectory();
 	} catch {
 		return false;
 	}
@@ -335,14 +340,17 @@ function isDirectory(p: string): boolean {
  * @param cwd - Starting directory
  * @returns First existing directory found, or undefined
  */
-export function findNearestProjectConfigDir(subpath: string, cwd: string = process.cwd()): ConfigDirEntry | undefined {
+export async function findNearestProjectConfigDir(
+	subpath: string,
+	cwd: string = process.cwd(),
+): Promise<ConfigDirEntry | undefined> {
 	let currentDir = cwd;
 
 	while (true) {
 		// Check all config bases at this level, in priority order
 		for (const { base, name } of PROJECT_CONFIG_BASES) {
 			const candidate = join(currentDir, base, subpath);
-			if (isDirectory(candidate)) {
+			if (await isDirectory(candidate)) {
 				return { path: candidate, source: name, level: "project" };
 			}
 		}
@@ -361,7 +369,10 @@ export function findNearestProjectConfigDir(subpath: string, cwd: string = proce
  * Returns one entry per config base (.omp, .pi, .claude) - the nearest one found.
  * Results are in priority order (highest first).
  */
-export function findAllNearestProjectConfigDirs(subpath: string, cwd: string = process.cwd()): ConfigDirEntry[] {
+export async function findAllNearestProjectConfigDirs(
+	subpath: string,
+	cwd: string = process.cwd(),
+): Promise<ConfigDirEntry[]> {
 	const results: ConfigDirEntry[] = [];
 	const foundBases = new Set<string>();
 
@@ -372,7 +383,7 @@ export function findAllNearestProjectConfigDirs(subpath: string, cwd: string = p
 			if (foundBases.has(name)) continue;
 
 			const candidate = join(currentDir, base, subpath);
-			if (isDirectory(candidate)) {
+			if (await isDirectory(candidate)) {
 				results.push({ path: candidate, source: name, level: "project" });
 				foundBases.add(name);
 			}