@oh-my-pi/pi-coding-agent 4.2.1 → 4.2.2

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [4.2.2] - 2026-01-11
+### Added
+
+- Added persistent cache storage for Codex usage data that survives application restarts
+- Added `--no-lsp` to disable LSP tools, formatting, diagnostics, and warmup for a session
+
+### Changed
+
+- Changed `SettingsManager.create()` to be async, requiring `await` when creating settings managers
+- Changed `loadSettings()` to be async, requiring `await` when loading settings
+- Changed `discoverSkills()` to be async, requiring `await` when discovering skills
+- Changed `loadSlashCommands()` to be async, requiring `await` when loading slash commands
+- Changed `buildSystemPrompt()` to be async, requiring `await` when building system prompts
+- Changed `loadSkills()` to be async, requiring `await` when loading skills
+- Changed `loadProjectContextFiles()` to be async, requiring `await` when loading context files
+- Changed `getShellConfig()` to be async, requiring `await` when getting shell configuration
+- Changed capability provider `load()` methods to be async-only, removing synchronous `loadSync` API
+- Updated `plan` agent with enhanced structured planning process, parallel exploration via `explore` agent spawning, and improved output format with examples
+- Removed `planner` agent command template, consolidating planning functionality into the `plan` agent
+
 ## [4.2.1] - 2026-01-11
 ### Added
 

package/docs/sdk.md

@@ -682,11 +682,11 @@ import { createAgentSession, SettingsManager, SessionManager } from "@oh-my-pi/p
 
 // Default: loads from files (global + project merged)
 const { session } = await createAgentSession({
-	settingsManager: SettingsManager.create(),
+	settingsManager: await SettingsManager.create(),
 });
 
 // With overrides
-const settingsManager = SettingsManager.create();
+const settingsManager = await SettingsManager.create();
 settingsManager.applyOverrides({
 	compaction: { enabled: false },
 	retry: { enabled: true, maxRetries: 5 },
@@ -701,13 +701,13 @@ const { session } = await createAgentSession({
 
 // Custom directories
 const { session } = await createAgentSession({
-	settingsManager: SettingsManager.create("/custom/cwd", "/custom/agent"),
+	settingsManager: await SettingsManager.create("/custom/cwd", "/custom/agent"),
 });
 ```
 
 **Static factories:**
 
-- `SettingsManager.create(cwd?, agentDir?)` - Load from files
+- `SettingsManager.create(cwd?, agentDir?)` - Load from files (async)
 - `SettingsManager.inMemory(settings?)` - No file I/O
 
 **Project-specific settings:**
@@ -765,7 +765,7 @@ const contextFiles = discoverContextFiles(cwd, agentDir);
 const commands = discoverSlashCommands(cwd, agentDir);
 
 // Settings (global + project merged)
-const settings = loadSettings(cwd, agentDir);
+const settings = await loadSettings(cwd, agentDir);
 
 // Build system prompt manually
 const prompt = buildSystemPrompt({

package/examples/sdk/10-settings.ts

@@ -7,11 +7,11 @@
 import { createAgentSession, loadSettings, SessionManager, SettingsManager } from "@oh-my-pi/pi-coding-agent";
 
 // Load current settings (merged global + project)
-const settings = loadSettings();
+const settings = await loadSettings();
 console.log("Current settings:", JSON.stringify(settings, null, 2));
 
 // Override specific settings
-const settingsManager = SettingsManager.create();
+const settingsManager = await SettingsManager.create();
 settingsManager.applyOverrides({
 	compaction: { enabled: false },
 	retry: { enabled: true, maxRetries: 5, baseDelayMs: 1000 },

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "4.2.1",
+	"version": "4.2.2",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"ompConfig": {
@@ -39,10 +39,10 @@
 		"prepublishOnly": "bun run generate-template && bun run clean && bun run build"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "4.2.1",
-		"@oh-my-pi/pi-agent-core": "4.2.1",
-		"@oh-my-pi/pi-git-tool": "4.2.1",
-		"@oh-my-pi/pi-tui": "4.2.1",
+		"@oh-my-pi/pi-ai": "4.2.2",
+		"@oh-my-pi/pi-agent-core": "4.2.2",
+		"@oh-my-pi/pi-git-tool": "4.2.2",
+		"@oh-my-pi/pi-tui": "4.2.2",
 		"@openai/agents": "^0.3.7",
 		"@sinclair/typebox": "^0.34.46",
 		"ajv": "^8.17.1",

package/src/capability/fs.ts

@@ -0,0 +1,90 @@
+import type { Dirent } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+const contentCache = new Map<string, string | null>();
+const dirCache = new Map<string, Dirent[]>();
+
+function resolvePath(path: string): string {
+	return resolve(path);
+}
+
+export async function readFile(path: string): Promise<string | null> {
+	const abs = resolvePath(path);
+	if (contentCache.has(abs)) {
+		return contentCache.get(abs) ?? null;
+	}
+
+	try {
+		const content = await Bun.file(abs).text();
+		contentCache.set(abs, content);
+		return content;
+	} catch {
+		contentCache.set(abs, null);
+		return null;
+	}
+}
+
+export async function readDirEntries(path: string): Promise<Dirent[]> {
+	const abs = resolvePath(path);
+	if (dirCache.has(abs)) {
+		return dirCache.get(abs) ?? [];
+	}
+
+	try {
+		const entries = await readdir(abs, { withFileTypes: true });
+		dirCache.set(abs, entries);
+		return entries;
+	} catch {
+		dirCache.set(abs, []);
+		return [];
+	}
+}
+
+export async function readDir(path: string): Promise<string[]> {
+	const entries = await readDirEntries(path);
+	return entries.map((entry) => entry.name);
+}
+
+export async function walkUp(
+	startDir: string,
+	name: string,
+	opts: { file?: boolean; dir?: boolean } = {},
+): Promise<string | null> {
+	const { file = true, dir = true } = opts;
+	let current = resolvePath(startDir);
+
+	while (true) {
+		const entries = await readDirEntries(current);
+		const entry = entries.find((e) => e.name === name);
+		if (entry) {
+			if (file && entry.isFile()) return join(current, name);
+			if (dir && entry.isDirectory()) return join(current, name);
+		}
+		const parent = dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+}
+
+export function cacheStats(): { content: number; dir: number } {
+	return {
+		content: contentCache.size,
+		dir: dirCache.size,
+	};
+}
+
+export function clearCache(): void {
+	contentCache.clear();
+	dirCache.clear();
+}
+
+export function invalidate(path: string): void {
+	const abs = resolvePath(path);
+	contentCache.delete(abs);
+	dirCache.delete(abs);
+	const parent = dirname(abs);
+	if (parent !== abs) {
+		dirCache.delete(parent);
+	}
+}

package/src/capability/index.ts

@@ -7,9 +7,9 @@
  * - Loading items for a capability across all providers
  */
 
-import { type Dirent, readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { resolve } from "node:path";
+import { clearCache as clearFsCache, cacheStats as fsCacheStats, invalidate as invalidateFs } from "./fs";
 import type {
 	Capability,
 	CapabilityInfo,
@@ -40,87 +40,6 @@ const disabledProviders = new Set<string>();
 /** Settings manager for persistence (if set) */
 let settingsManager: { getDisabledProviders(): string[]; setDisabledProviders(ids: string[]): void } | null = null;
 
-// =============================================================================
-// Filesystem Cache
-// =============================================================================
-
-type StatResult = "file" | "dir" | null;
-
-const statCache = new Map<string, StatResult>();
-const contentCache = new Map<string, string | null>();
-const dirCache = new Map<string, Dirent[]>();
-
-function clearCache(): void {
-	statCache.clear();
-	contentCache.clear();
-	dirCache.clear();
-}
-
-function createFsHelpers(cwd: string): LoadContext["fs"] {
-	return {
-		exists(path: string): boolean {
-			const abs = resolve(cwd, path);
-			if (!statCache.has(abs)) {
-				try {
-					const stat = statSync(abs);
-					statCache.set(abs, stat.isDirectory() ? "dir" : stat.isFile() ? "file" : null);
-				} catch {
-					statCache.set(abs, null);
-				}
-			}
-			return statCache.get(abs) !== null;
-		},
-
-		isDir(path: string): boolean {
-			this.exists(path);
-			return statCache.get(resolve(cwd, path)) === "dir";
-		},
-
-		isFile(path: string): boolean {
-			this.exists(path);
-			return statCache.get(resolve(cwd, path)) === "file";
-		},
-
-		readFile(path: string): string | null {
-			const abs = resolve(cwd, path);
-			if (!contentCache.has(abs)) {
-				try {
-					contentCache.set(abs, readFileSync(abs, "utf-8"));
-				} catch {
-					contentCache.set(abs, null);
-				}
-			}
-			return contentCache.get(abs) ?? null;
-		},
-
-		readDir(path: string): string[] {
-			const abs = resolve(cwd, path);
-			if (!this.isDir(path)) return [];
-			if (!dirCache.has(abs)) {
-				try {
-					dirCache.set(abs, readdirSync(abs, { withFileTypes: true }));
-				} catch {
-					dirCache.set(abs, []);
-				}
-			}
-			return (dirCache.get(abs) ?? []).map((e) => e.name);
-		},
-
-		walkUp(name: string, opts: { file?: boolean; dir?: boolean } = {}): string | null {
-			const { file = true, dir = true } = opts;
-			let current = cwd;
-			while (true) {
-				const candidate = join(current, name);
-				if (file && this.isFile(candidate)) return candidate;
-				if (dir && this.isDir(candidate)) return candidate;
-				const parent = dirname(current);
-				if (parent === current) return null;
-				current = parent;
-			}
-		},
-	};
-}
-
 // =============================================================================
 // Registration API
 // =============================================================================
@@ -175,129 +94,55 @@ export function registerProvider<T>(capabilityId: string, provider: Provider<T>)
 // =============================================================================
 
 /**
- * Core loading logic shared by both load() and loadSync().
+ * Async loading logic shared by loadCapability().
  */
-function loadImpl<T>(
+async function loadImpl<T>(
 	capability: Capability<T>,
 	providers: Provider<T>[],
 	ctx: LoadContext,
 	options: LoadOptions,
-): CapabilityResult<T> {
+): Promise<CapabilityResult<T>> {
 	const allItems: Array<T & { _source: SourceMeta; _shadowed?: boolean }> = [];
 	const allWarnings: string[] = [];
 	const contributingProviders: string[] = [];
 
-	for (const provider of providers) {
-		try {
-			const result = provider.load(ctx);
-
-			if (result instanceof Promise) {
-				throw new Error(
-					`Provider "${provider.id}" returned a Promise. Use load() instead of loadSync() for async providers.`,
-				);
-			}
-
-			if (result.warnings) {
-				allWarnings.push(...result.warnings.map((w) => `[${provider.displayName}] ${w}`));
+	const results = await Promise.all(
+		providers.map(async (provider) => {
+			try {
+				const result = await provider.load(ctx);
+				return { provider, result };
+			} catch (error) {
+				return { provider, error };
 			}
-
-			if (result.items.length > 0) {
-				contributingProviders.push(provider.id);
-
-				for (const item of result.items) {
-					const itemWithSource = item as T & { _source: SourceMeta };
-					if (itemWithSource._source) {
-						itemWithSource._source.providerName = provider.displayName;
-						allItems.push(itemWithSource as T & { _source: SourceMeta; _shadowed?: boolean });
-					} else {
-						allWarnings.push(`[${provider.displayName}] Item missing _source metadata, skipping`);
-					}
-				}
-			}
-		} catch (err) {
-			if (err instanceof Error && err.message.includes("returned a Promise")) {
-				throw err;
-			}
-			allWarnings.push(`[${provider.displayName}] Failed to load: ${err}`);
+		}),
+	);
+
+	for (const entry of results) {
+		const { provider } = entry;
+		if ("error" in entry) {
+			allWarnings.push(`[${provider.displayName}] Failed to load: ${entry.error}`);
+			continue;
 		}
-	}
-
-	// Deduplicate by key (first wins = highest priority)
-	const seen = new Map<string, number>();
-	const deduped: Array<T & { _source: SourceMeta }> = [];
 
-	for (let i = 0; i < allItems.length; i++) {
-		const item = allItems[i];
-		const key = capability.key(item);
+		const result = entry.result;
+		if (!result) continue;
 
-		if (key === undefined) {
-			deduped.push(item);
-		} else if (!seen.has(key)) {
-			seen.set(key, i);
-			deduped.push(item);
-		} else {
-			item._shadowed = true;
-		}
-	}
-
-	// Validate items (only non-shadowed items)
-	if (capability.validate && !options.includeInvalid) {
-		for (let i = deduped.length - 1; i >= 0; i--) {
-			const error = capability.validate(deduped[i]);
-			if (error) {
-				const source = deduped[i]._source;
-				allWarnings.push(
-					`[${source?.providerName ?? "unknown"}] Invalid item at ${source?.path ?? "unknown"}: ${error}`,
-				);
-				deduped.splice(i, 1);
-			}
+		if (result.warnings) {
+			allWarnings.push(...result.warnings.map((w) => `[${provider.displayName}] ${w}`));
 		}
-	}
 
-	return {
-		items: deduped,
-		all: allItems,
-		warnings: allWarnings,
-		providers: contributingProviders,
-	};
-}
+		if (result.items.length > 0) {
+			contributingProviders.push(provider.id);
 
-/**
- * Async loading logic shared by load().
- */
-async function loadImplAsync<T>(
-	capability: Capability<T>,
-	providers: Provider<T>[],
-	ctx: LoadContext,
-	options: LoadOptions,
-): Promise<CapabilityResult<T>> {
-	const allItems: Array<T & { _source: SourceMeta; _shadowed?: boolean }> = [];
-	const allWarnings: string[] = [];
-	const contributingProviders: string[] = [];
-
-	for (const provider of providers) {
-		try {
-			const result = await provider.load(ctx);
-
-			if (result.warnings) {
-				allWarnings.push(...result.warnings.map((w) => `[${provider.displayName}] ${w}`));
-			}
-
-			if (result.items.length > 0) {
-				contributingProviders.push(provider.id);
-
-				for (const item of result.items) {
-					const itemWithSource = item as T & { _source: SourceMeta };
-					if (itemWithSource._source) {
-						itemWithSource._source.providerName = provider.displayName;
-						allItems.push(itemWithSource as T & { _source: SourceMeta; _shadowed?: boolean });
-					} else {
-						allWarnings.push(`[${provider.displayName}] Item missing _source metadata, skipping`);
-					}
+			for (const item of result.items) {
+				const itemWithSource = item as T & { _source: SourceMeta };
+				if (itemWithSource._source) {
+					itemWithSource._source.providerName = provider.displayName;
+					allItems.push(itemWithSource as T & { _source: SourceMeta; _shadowed?: boolean });
+				} else {
+					allWarnings.push(`[${provider.displayName}] Item missing _source metadata, skipping`);
 				}
 			}
-		} catch (err) {
-			allWarnings.push(`[${provider.displayName}] Failed to load: ${err}`);
 		}
 	}
 
@@ -362,7 +207,7 @@ function filterProviders<T>(capability: Capability<T>, options: LoadOptions): Pr
 /**
  * Load a capability by ID.
  */
-export async function load<T>(capabilityId: string, options: LoadOptions = {}): Promise<CapabilityResult<T>> {
+export async function loadCapability<T>(capabilityId: string, options: LoadOptions = {}): Promise<CapabilityResult<T>> {
 	const capability = capabilities.get(capabilityId) as Capability<T> | undefined;
 	if (!capability) {
 		throw new Error(`Unknown capability: "${capabilityId}"`);
@@ -370,28 +215,10 @@ export async function load<T>(capabilityId: string, options: LoadOptions = {}):
 
 	const cwd = options.cwd ?? process.cwd();
 	const home = homedir();
-	const ctx: LoadContext = { cwd, home, fs: createFsHelpers(cwd) };
+	const ctx: LoadContext = { cwd, home };
 	const providers = filterProviders(capability, options);
 
-	return loadImplAsync(capability, providers, ctx, options);
-}
-
-/**
- * Synchronous load (for capabilities where all providers are sync).
- * Throws if any provider returns a Promise.
- */
-export function loadSync<T>(capabilityId: string, options: LoadOptions = {}): CapabilityResult<T> {
-	const capability = capabilities.get(capabilityId) as Capability<T> | undefined;
-	if (!capability) {
-		throw new Error(`Unknown capability: "${capabilityId}"`);
-	}
-
-	const cwd = options.cwd ?? process.cwd();
-	const home = homedir();
-	const ctx: LoadContext = { cwd, home, fs: createFsHelpers(cwd) };
-	const providers = filterProviders(capability, options);
-
-	return loadImpl(capability, providers, ctx, options);
+	return await loadImpl(capability, providers, ctx, options);
 }
 
 // =============================================================================
@@ -567,36 +394,23 @@ export function getAllProvidersInfo(): ProviderInfo[] {
  * Reset all caches. Call after chdir or filesystem changes.
  */
 export function reset(): void {
-	clearCache();
+	clearFsCache();
 }
 
 /**
  * Invalidate cache for a specific path.
  * @param path - Absolute or relative path to invalidate
- * @param cwd - Working directory for resolving relative paths (defaults to process.cwd())
  */
 export function invalidate(path: string, cwd?: string): void {
-	const abs = resolve(cwd ?? process.cwd(), path);
-	statCache.delete(abs);
-	contentCache.delete(abs);
-	dirCache.delete(abs);
-	// Also invalidate parent for directory listings
-	const parent = dirname(abs);
-	if (parent !== abs) {
-		statCache.delete(parent);
-		dirCache.delete(parent);
-	}
+	const resolved = cwd ? resolve(cwd, path) : path;
+	invalidateFs(resolved);
 }
 
 /**
  * Get cache stats for diagnostics.
  */
-export function cacheStats(): { stat: number; content: number; dir: number } {
-	return {
-		stat: statCache.size,
-		content: contentCache.size,
-		dir: dirCache.size,
-	};
+export function cacheStats(): { content: number; dir: number } {
+	return fsCacheStats();
 }
 
 // =============================================================================

package/src/capability/types.ts

@@ -14,16 +14,6 @@ export interface LoadContext {
 	cwd: string;
 	/** User home directory */
 	home: string;
-	/** Filesystem helpers (cached) */
-	fs: {
-		exists(path: string): boolean;
-		isDir(path: string): boolean;
-		isFile(path: string): boolean;
-		readFile(path: string): string | null;
-		readDir(path: string): string[];
-		/** Walk up from cwd looking for a file/dir, returns first match */
-		walkUp(name: string, opts?: { file?: boolean; dir?: boolean }): string | null;
-	};
 }
 
 /**
@@ -61,7 +51,7 @@ export interface Provider<T> {
 	 * Load items for this capability.
 	 * Returns items in provider's preferred order (usually project before user).
 	 */
-	load(ctx: LoadContext): LoadResult<T> | Promise<LoadResult<T>>;
+	load(ctx: LoadContext): Promise<LoadResult<T>>;
 }
 
 /**

package/src/cli/args.ts

@@ -31,6 +31,7 @@ export interface Args {
 	models?: string[];
 	tools?: string[];
 	noTools?: boolean;
+	noLsp?: boolean;
 	hooks?: string[];
 	extensions?: string[];
 	noExtensions?: boolean;
@@ -100,6 +101,8 @@ export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "
 			result.models = args[++i].split(",").map((s) => s.trim());
 		} else if (arg === "--no-tools") {
 			result.noTools = true;
+		} else if (arg === "--no-lsp") {
+			result.noLsp = true;
 		} else if (arg === "--tools" && i + 1 < args.length) {
 			const toolNames = args[++i].split(",").map((s) => s.trim());
 			const validTools: string[] = [];
@@ -196,6 +199,7 @@ ${chalk.bold("Options:")}
   --models <patterns>            Comma-separated model patterns for Ctrl+P cycling
                                  Supports globs (anthropic/*, *sonnet*) and fuzzy matching
   --no-tools                     Disable all built-in tools
+  --no-lsp                       Disable LSP tools, formatting, and diagnostics
   --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

package/src/core/agent-session.ts

@@ -99,7 +99,7 @@ export interface AgentSessionConfig {
 	/** Tool registry for LSP and settings */
 	toolRegistry?: Map<string, AgentTool>;
 	/** System prompt builder that can consider tool availability */
-	rebuildSystemPrompt?: (toolNames: string[], tools: Map<string, AgentTool>) => string;
+	rebuildSystemPrompt?: (toolNames: string[], tools: Map<string, AgentTool>) => Promise<string>;
 	/** TTSR manager for time-traveling stream rules */
 	ttsrManager?: TtsrManager;
 }
@@ -249,7 +249,7 @@ export class AgentSession {
 
 	// Tool registry and prompt builder for extensions
 	private _toolRegistry: Map<string, AgentTool>;
-	private _rebuildSystemPrompt: ((toolNames: string[], tools: Map<string, AgentTool>) => string) | undefined;
+	private _rebuildSystemPrompt: ((toolNames: string[], tools: Map<string, AgentTool>) => Promise<string>) | undefined;
 	private _baseSystemPrompt: string;
 
 	// TTSR manager for time-traveling stream rules
@@ -628,7 +628,7 @@ export class AgentSession {
 	 * Also rebuilds the system prompt to reflect the new tool set.
 	 * Changes take effect on the next agent turn.
 	 */
-	setActiveToolsByName(toolNames: string[]): void {
+	async setActiveToolsByName(toolNames: string[]): Promise<void> {
 		const tools: AgentTool[] = [];
 		const validToolNames: string[] = [];
 		for (const name of toolNames) {
@@ -642,7 +642,7 @@ export class AgentSession {
 
 		// Rebuild base system prompt with new tool set
 		if (this._rebuildSystemPrompt) {
-			this._baseSystemPrompt = this._rebuildSystemPrompt(validToolNames, this._toolRegistry);
+			this._baseSystemPrompt = await this._rebuildSystemPrompt(validToolNames, this._toolRegistry);
 			this.agent.setSystemPrompt(this._baseSystemPrompt);
 		}
 	}