@zihanw/pi-forge 0.3.1 → 0.3.2

package/examples/custom-system-status-extension/index.ts

@@ -1,12 +1,26 @@
 import { cpus, freemem, loadavg, totalmem, uptime } from "node:os";
-import { resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { registerMacro, registerSlot } from "../../src/index.ts";
 
-interface PiForgeRegistrationApi {
-	registerMacro: typeof registerMacro;
-	registerSlot: typeof registerSlot;
+interface ForgeRegistrationApi {
+	registerMacro(definition: {
+		name: string;
+		source?: string;
+		description?: string;
+		render: () => string;
+	}): () => void;
+	registerSlot(definition: {
+		name: string;
+		source?: string;
+		description?: string;
+		options?: Record<string, unknown>;
+		render: (ctx: {
+			options: Record<string, unknown>;
+			format: () => "xml" | "plain" | "json";
+			helpers: {
+				escapeXml(value: string): string;
+				plainBullet(label: string, value: string): string;
+			};
+		}) => string;
+	}): () => void;
 }
 
 interface SystemStatusSnapshot {
@@ -22,117 +36,63 @@ interface SystemStatusSnapshot {
 	uptimeSeconds: number;
 }
 
-interface ExampleRegistryState {
-	unregister: Array<() => void>;
-}
-
-type ExampleGlobal = typeof globalThis & {
-	__piForgeSystemStatusExample?: ExampleRegistryState;
-};
-
-function registryState(): ExampleRegistryState {
-	const globalScope = globalThis as ExampleGlobal;
-	globalScope.__piForgeSystemStatusExample ??= { unregister: [] };
-	return globalScope.__piForgeSystemStatusExample;
-}
-
-function resetRegistrations(): void {
-	const state = registryState();
-	for (const unregister of state.unregister.splice(0)) unregister();
-}
-
-export default async function systemStatusExtension(_pi: ExtensionAPI): Promise<void> {
-	const { registerMacro, registerSlot } = await loadPiForgeRegistrationApi();
-	resetRegistrations();
-	const state = registryState();
-
-	state.unregister.push(
-		registerMacro({
-			name: "cpuLoad",
-			source: "pi-forge-example-system-status",
-			description: "Current machine CPU load as normalized 1-minute OS load average.",
-			render: () => formatCpuLoad(readSystemStatus()),
-		}),
-		registerSlot({
-			name: "machine-status",
-			source: "pi-forge-example-system-status",
-			description: "Current machine CPU, memory, and uptime snapshot.",
-			options: {
-				format: { type: "enum", values: ["plain", "xml"], default: "plain" },
-				heading: { type: "string", default: "Machine status" },
-				includeMemory: { type: "boolean", default: true },
-				includeUptime: { type: "boolean", default: true },
-			},
-			render: (ctx) => {
-				const snapshot = readSystemStatus();
-				const includeMemory = ctx.options.includeMemory !== false;
-				const includeUptime = ctx.options.includeUptime !== false;
-				const heading = typeof ctx.options.heading === "string" && ctx.options.heading.trim()
-					? ctx.options.heading.trim()
-					: "Machine status";
-
-				if (ctx.format() === "xml") {
-					const lines = [
-						"<machine_status>",
-						`  <cpu logical_cores=\"${snapshot.logicalCores}\" normalized_load_1m=\"${snapshot.normalizedLoad1.toFixed(3)}\" model=\"${ctx.helpers.escapeXml(snapshot.cpuModel)}\">${ctx.helpers.escapeXml(formatCpuLoad(snapshot))}</cpu>`,
-						`  <load_average one_minute=\"${snapshot.load1.toFixed(2)}\" five_minutes=\"${snapshot.load5.toFixed(2)}\" fifteen_minutes=\"${snapshot.load15.toFixed(2)}\" />`,
-					];
-					if (includeMemory) {
-						lines.push(`  <memory used_percent=\"${snapshot.usedMemoryPercent.toFixed(1)}\" free_mb=\"${snapshot.freeMemoryMb}\" total_mb=\"${snapshot.totalMemoryMb}\" />`);
-					}
-					if (includeUptime) {
-						lines.push(`  <uptime>${ctx.helpers.escapeXml(formatDuration(snapshot.uptimeSeconds))}</uptime>`);
-					}
-					lines.push("</machine_status>");
-					return lines.join("\n");
-				}
-
+export default function registerSystemStatus(api: ForgeRegistrationApi): void {
+	api.registerMacro({
+		name: "cpuLoad",
+		source: "pi-forge-example-system-status",
+		description: "Current machine CPU load as normalized 1-minute OS load average.",
+		render: () => formatCpuLoad(readSystemStatus()),
+	});
+
+	api.registerSlot({
+		name: "machine-status",
+		source: "pi-forge-example-system-status",
+		description: "Current machine CPU, memory, and uptime snapshot.",
+		options: {
+			format: { type: "enum", values: ["plain", "xml"], default: "plain" },
+			heading: { type: "string", default: "Machine status" },
+			includeMemory: { type: "boolean", default: true },
+			includeUptime: { type: "boolean", default: true },
+		},
+		render: (ctx) => {
+			const snapshot = readSystemStatus();
+			const includeMemory = ctx.options.includeMemory !== false;
+			const includeUptime = ctx.options.includeUptime !== false;
+			const heading = typeof ctx.options.heading === "string" && ctx.options.heading.trim()
+				? ctx.options.heading.trim()
+				: "Machine status";
+
+			if (ctx.format() === "xml") {
 				const lines = [
-					`${heading}:`,
-					ctx.helpers.plainBullet("CPU", `${snapshot.logicalCores} logical cores, ${snapshot.cpuModel}`),
-					ctx.helpers.plainBullet("CPU load", formatCpuLoad(snapshot)),
-					ctx.helpers.plainBullet("Load average", `${snapshot.load1.toFixed(2)} / ${snapshot.load5.toFixed(2)} / ${snapshot.load15.toFixed(2)} (1m/5m/15m)`),
+					"<machine_status>",
+					`  <cpu logical_cores=\"${snapshot.logicalCores}\" normalized_load_1m=\"${snapshot.normalizedLoad1.toFixed(3)}\" model=\"${ctx.helpers.escapeXml(snapshot.cpuModel)}\">${ctx.helpers.escapeXml(formatCpuLoad(snapshot))}</cpu>`,
+					`  <load_average one_minute=\"${snapshot.load1.toFixed(2)}\" five_minutes=\"${snapshot.load5.toFixed(2)}\" fifteen_minutes=\"${snapshot.load15.toFixed(2)}\" />`,
 				];
 				if (includeMemory) {
-					lines.push(ctx.helpers.plainBullet("Memory", `${snapshot.usedMemoryPercent.toFixed(1)}% used (${snapshot.freeMemoryMb} MB free / ${snapshot.totalMemoryMb} MB total)`));
+					lines.push(`  <memory used_percent=\"${snapshot.usedMemoryPercent.toFixed(1)}\" free_mb=\"${snapshot.freeMemoryMb}\" total_mb=\"${snapshot.totalMemoryMb}\" />`);
 				}
 				if (includeUptime) {
-					lines.push(ctx.helpers.plainBullet("Uptime", formatDuration(snapshot.uptimeSeconds)));
+					lines.push(`  <uptime>${ctx.helpers.escapeXml(formatDuration(snapshot.uptimeSeconds))}</uptime>`);
 				}
+				lines.push("</machine_status>");
 				return lines.join("\n");
-			},
-		}),
-	);
-}
-
-async function loadPiForgeRegistrationApi(): Promise<PiForgeRegistrationApi> {
-	const override = process.env.PI_FORGE_MODULE;
-	if (override) {
-		return importPiForgeApi(pathToFileURL(resolve(override)).href);
-	}
-
-	try {
-		return await importPiForgeApi("@zihanw/pi-forge");
-	} catch {
-		try {
-			return await importPiForgeApi("../../src/index.ts");
-		} catch (error) {
-			const detail = error instanceof Error ? error.message : String(error);
-			throw new Error(
-				"Unable to load pi-forge registration API. Install @zihanw/pi-forge, " +
-				"set PI_FORGE_MODULE=/absolute/path/to/pi-forge/src/index.ts, or run this example in place from the pi-forge checkout. " +
-				`Last error: ${detail}`,
-			);
-		}
-	}
-}
-
-async function importPiForgeApi(specifier: string): Promise<PiForgeRegistrationApi> {
-	const mod = await import(specifier) as Partial<PiForgeRegistrationApi>;
-	if (typeof mod.registerMacro !== "function" || typeof mod.registerSlot !== "function") {
-		throw new Error(`Module does not export registerMacro/registerSlot: ${specifier}`);
-	}
-	return { registerMacro: mod.registerMacro, registerSlot: mod.registerSlot };
+			}
+
+			const lines = [
+				`${heading}:`,
+				ctx.helpers.plainBullet("CPU", `${snapshot.logicalCores} logical cores, ${snapshot.cpuModel}`),
+				ctx.helpers.plainBullet("CPU load", formatCpuLoad(snapshot)),
+				ctx.helpers.plainBullet("Load average", `${snapshot.load1.toFixed(2)} / ${snapshot.load5.toFixed(2)} / ${snapshot.load15.toFixed(2)} (1m/5m/15m)`),
+			];
+			if (includeMemory) {
+				lines.push(ctx.helpers.plainBullet("Memory", `${snapshot.usedMemoryPercent.toFixed(1)}% used (${snapshot.freeMemoryMb} MB free / ${snapshot.totalMemoryMb} MB total)`));
+			}
+			if (includeUptime) {
+				lines.push(ctx.helpers.plainBullet("Uptime", formatDuration(snapshot.uptimeSeconds)));
+			}
+			return lines.join("\n");
+		},
+	});
 }
 
 function readSystemStatus(): SystemStatusSnapshot {

package/examples/custom-system-status-extension/prompt-stack.json

@@ -3,7 +3,7 @@
   "type": "pi-forge.prompt-stack",
   "id": "custom-system-status",
   "name": "Custom System Status",
-  "description": "Example stack that uses a trusted custom macro and custom slot registered by examples/custom-system-status-extension/index.ts.",
+  "description": "Example stack that uses a trusted custom macro and custom slot registered from .pi/forge/extensions/system-status.ts.",
   "mode": "append",
   "items": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zihanw/pi-forge",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Pi extension for prompt stack and agent profile management.",
   "type": "module",
   "exports": {

package/src/forge-extensions.ts

@@ -0,0 +1,223 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+	getRegisteredMacros,
+	registerMacro,
+	type PromptMacroDefinition,
+} from "./macro-engine.ts";
+import { promptRenderHelpers, type PromptRenderHelpers } from "./render-helpers.ts";
+import {
+	getRegisteredSlots,
+	registerSlot,
+	type PromptSlotDefinition,
+} from "./slot-renderers.ts";
+import { forgeDir, forgeExtensionsDir, globalForgeDir, globalForgeExtensionsDir } from "./storage.ts";
+import type { PromptStackDiagnostic } from "./types.ts";
+
+export interface ForgeExtensionApi {
+	cwd: string;
+	forgeDir: string;
+	extensionPath: string;
+	helpers: PromptRenderHelpers;
+	registerMacro(definition: PromptMacroDefinition): () => void;
+	registerSlot(definition: PromptSlotDefinition): () => void;
+	getRegisteredMacros: typeof getRegisteredMacros;
+	getRegisteredSlots: typeof getRegisteredSlots;
+}
+
+export type ForgeExtensionRegister = (api: ForgeExtensionApi) => void | (() => void) | Promise<void | (() => void)>;
+
+export interface ForgeExtensionState {
+	unregister: Array<() => void>;
+	loadVersion: number;
+}
+
+export interface ForgeExtensionLoadResult {
+	diagnostics: PromptStackDiagnostic[];
+	loadedPaths: string[];
+}
+
+interface ForgeExtensionCandidate {
+	filePath: string;
+	forgeDir: string;
+}
+
+export function createForgeExtensionState(): ForgeExtensionState {
+	return { unregister: [], loadVersion: 0 };
+}
+
+export async function reloadForgeExtensions(cwd: string, state: ForgeExtensionState): Promise<ForgeExtensionLoadResult> {
+	const diagnostics = unloadForgeExtensions(state);
+	state.loadVersion++;
+	const loadedPaths: string[] = [];
+
+	for (const candidate of discoverForgeExtensionCandidates(cwd)) {
+		const result = await loadForgeExtensionFile(cwd, candidate.forgeDir, candidate.filePath, state.loadVersion);
+		diagnostics.push(...result.diagnostics);
+		if (result.loaded) {
+			state.unregister.push(...result.unregister);
+			loadedPaths.push(candidate.filePath);
+		}
+	}
+
+	return { diagnostics, loadedPaths };
+}
+
+export function unloadForgeExtensions(state: ForgeExtensionState): PromptStackDiagnostic[] {
+	const diagnostics: PromptStackDiagnostic[] = [];
+	for (const unregister of state.unregister.splice(0).reverse()) {
+		try {
+			unregister();
+		} catch (error) {
+			diagnostics.push({
+				level: "warning",
+				message: `Failed to unload pi-forge extension: ${error instanceof Error ? error.message : String(error)}`,
+			});
+		}
+	}
+	return diagnostics;
+}
+
+export function discoverForgeExtensionFiles(cwd: string): string[] {
+	return discoverForgeExtensionCandidates(cwd).map((candidate) => candidate.filePath);
+}
+
+function discoverForgeExtensionCandidates(cwd: string): ForgeExtensionCandidate[] {
+	const dirs = [
+		{ dir: globalForgeExtensionsDir(), forgeDir: globalForgeDir() },
+		{ dir: forgeExtensionsDir(cwd), forgeDir: forgeDir(cwd) },
+	];
+	const seenDirs = new Set<string>();
+	return dirs.flatMap(({ dir, forgeDir }) => {
+		if (seenDirs.has(dir)) return [];
+		seenDirs.add(dir);
+		return discoverForgeExtensionFilesInDir(dir).map((filePath) => ({ filePath, forgeDir }));
+	});
+}
+
+function discoverForgeExtensionFilesInDir(dir: string): string[] {
+	if (!existsSync(dir)) return [];
+
+	const files: string[] = [];
+	let entries: string[];
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return [];
+	}
+
+	for (const name of entries.sort()) {
+		if (name.startsWith(".")) continue;
+		const fullPath = join(dir, name);
+		let stats;
+		try {
+			stats = statSync(fullPath);
+		} catch {
+			continue;
+		}
+
+		if (stats.isFile() && isForgeExtensionFile(fullPath)) {
+			files.push(fullPath);
+			continue;
+		}
+
+		if (!stats.isDirectory()) continue;
+		for (const indexName of ["index.ts", "index.js", "index.mjs", "index.cjs"]) {
+			const indexPath = join(fullPath, indexName);
+			if (existsSync(indexPath)) {
+				files.push(indexPath);
+				break;
+			}
+		}
+	}
+
+	return files;
+}
+
+async function loadForgeExtensionFile(
+	cwd: string,
+	forgeDirPath: string,
+	filePath: string,
+	loadVersion: number,
+): Promise<{ loaded: boolean; unregister: Array<() => void>; diagnostics: PromptStackDiagnostic[] }> {
+	const unregister: Array<() => void> = [];
+	const diagnostics: PromptStackDiagnostic[] = [];
+	try {
+		const module = await import(`${pathToFileURL(filePath).href}?piForgeReload=${loadVersion}`);
+		const register = readRegisterFunction(module);
+		if (!register) {
+			return {
+				loaded: false,
+				unregister,
+				diagnostics: [{
+					level: "warning",
+					message: `pi-forge extension ${extensionLabel(filePath)} must export a default function or named register function.`,
+				}],
+			};
+		}
+
+		const cleanup = await register(createForgeExtensionApi(cwd, forgeDirPath, filePath, unregister));
+		if (typeof cleanup === "function") unregister.push(once(cleanup));
+		return { loaded: true, unregister, diagnostics };
+	} catch (error) {
+		for (const cleanup of unregister.splice(0).reverse()) {
+			try {
+				cleanup();
+			} catch {
+				// Preserve the original load error; cleanup failures are secondary.
+			}
+		}
+		diagnostics.push({
+			level: "warning",
+			message: `Failed to load pi-forge extension ${extensionLabel(filePath)}: ${error instanceof Error ? error.message : String(error)}`,
+		});
+		return { loaded: false, unregister: [], diagnostics };
+	}
+}
+
+function createForgeExtensionApi(cwd: string, forgeDirPath: string, extensionPath: string, unregister: Array<() => void>): ForgeExtensionApi {
+	return {
+		cwd,
+		forgeDir: forgeDirPath,
+		extensionPath,
+		helpers: promptRenderHelpers,
+		registerMacro: (definition) => trackUnregister(unregister, registerMacro(definition)),
+		registerSlot: (definition) => trackUnregister(unregister, registerSlot(definition)),
+		getRegisteredMacros,
+		getRegisteredSlots,
+	};
+}
+
+function trackUnregister(unregisters: Array<() => void>, unregister: () => void): () => void {
+	const tracked = once(unregister);
+	unregisters.push(tracked);
+	return tracked;
+}
+
+function once(callback: () => void): () => void {
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		callback();
+	};
+}
+
+function readRegisterFunction(module: unknown): ForgeExtensionRegister | undefined {
+	const record = module && typeof module === "object" ? module as { default?: unknown; register?: unknown } : {};
+	if (typeof record.default === "function") return record.default as ForgeExtensionRegister;
+	if (typeof record.register === "function") return record.register as ForgeExtensionRegister;
+	if (record.default && typeof record.default === "object" && typeof (record.default as { register?: unknown }).register === "function") {
+		return (record.default as { register: ForgeExtensionRegister }).register;
+	}
+	return undefined;
+}
+
+function isForgeExtensionFile(filePath: string): boolean {
+	return (filePath.endsWith(".ts") || filePath.endsWith(".js") || filePath.endsWith(".mjs") || filePath.endsWith(".cjs")) && !filePath.endsWith(".d.ts");
+}
+
+function extensionLabel(filePath: string): string {
+	return basename(filePath);
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 import type { BuildSystemPromptOptions, ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createForgeExtensionState, reloadForgeExtensions, unloadForgeExtensions } from "./forge-extensions.ts";
 import { registerLifecycleHandlers } from "./lifecycle.ts";
 import { chooseDefaultStack, isDisabledPromptStackId, loadPromptStacks } from "./loader.ts";
 import { registerPayloadCommands, registerPayloadRequestHandler, armPayloadIntercept, clearPayloadCapture, webPayloadSnapshot } from "./payload-command.ts";
@@ -31,6 +32,10 @@ export {
 	type PromptExtensionOptionType,
 	type PromptRegistryEntry,
 } from "./extension-registry.ts";
+export {
+	type ForgeExtensionApi,
+	type ForgeExtensionRegister,
+} from "./forge-extensions.ts";
 export {
 	createVariableAccess,
 	promptRenderHelpers,
@@ -69,6 +74,7 @@ export default function piForge(pi: ExtensionAPI) {
 	let webEditorCwd: string | undefined;
 	let webEditorPreferredPort: number | undefined;
 	let toolPolicyBaseline: string[] | undefined;
+	const forgeExtensionState = createForgeExtensionState();
 
 	function activeId(): string | undefined {
 		return state.active?.stack.id;
@@ -102,8 +108,11 @@ export default function piForge(pi: ExtensionAPI) {
 		return true;
 	}
 
-	function reloadStacks(ctx: ExtensionContext, preferredId?: string): void {
+	async function reloadStacks(ctx: ExtensionContext, preferredId?: string): Promise<void> {
 		if (!ctx.isProjectTrusted()) {
+			const unloadDiagnostics = unloadForgeExtensions(forgeExtensionState);
+			state.forgeExtensionDiagnostics = unloadDiagnostics;
+			state.forgeExtensionPaths = [];
 			state.stacks = [];
 			state.active = undefined;
 			syncActiveToolPolicy(ctx);
@@ -112,7 +121,13 @@ export default function piForge(pi: ExtensionAPI) {
 			return;
 		}
 
+		const extensionResult = await reloadForgeExtensions(ctx.cwd, forgeExtensionState);
+		state.forgeExtensionDiagnostics = extensionResult.diagnostics;
+		state.forgeExtensionPaths = extensionResult.loadedPaths;
 		state.stacks = loadPromptStacks(ctx.cwd);
+		if (state.forgeExtensionDiagnostics.length > 0) {
+			for (const loaded of state.stacks) loaded.diagnostics.unshift(...state.forgeExtensionDiagnostics);
+		}
 		state.active = chooseDefaultStack(state.stacks, preferredId);
 		updateStatus(ctx);
 		syncActiveToolPolicy(ctx);

package/src/lifecycle.ts

@@ -12,7 +12,7 @@ import { STATE_ENTRY_TYPE, VARIABLE_ENTRY_TYPE, type PiForgeRuntimeState } from
 import type { PromptStackDiagnostic, PromptVariableStore, PromptVariableValue } from "./types.ts";
 
 export interface LifecycleDeps {
-	reloadStacks(ctx: ExtensionContext, preferredId?: string): void;
+	reloadStacks(ctx: ExtensionContext, preferredId?: string): Promise<void>;
 	refreshWebEditorHost(ctx: ExtensionContext): void;
 	notifyActivePreset(ctx: ExtensionContext, detail: string): void;
 	syncActiveToolPolicy(ctx?: ExtensionContext): void;
@@ -23,19 +23,19 @@ export interface LifecycleDeps {
 
 export function registerLifecycleHandlers(pi: ExtensionAPI, state: PiForgeRuntimeState, deps: LifecycleDeps): void {
 	pi.on("session_start", async (event, ctx) => {
-		restoreBranchScopedRuntime(ctx, state, deps);
+		await restoreBranchScopedRuntime(ctx, state, deps);
 		deps.refreshWebEditorHost(ctx);
 		deps.notifyActivePreset(ctx, "after session " + event.reason);
 	});
 
 	pi.on("session_tree", async (_event, ctx) => {
-		restoreBranchScopedRuntime(ctx, state, deps);
+		await restoreBranchScopedRuntime(ctx, state, deps);
 		deps.refreshWebEditorHost(ctx);
 		deps.notifyActivePreset(ctx, "after tree navigation");
 	});
 
 	pi.on("session_compact", async (_event, ctx) => {
-		restoreBranchScopedRuntime(ctx, state, deps);
+		await restoreBranchScopedRuntime(ctx, state, deps);
 		deps.refreshWebEditorHost(ctx);
 		deps.notifyActivePreset(ctx, "after compaction");
 	});
@@ -105,12 +105,12 @@ export function registerLifecycleHandlers(pi: ExtensionAPI, state: PiForgeRuntim
 	});
 }
 
-function restoreBranchScopedRuntime(ctx: ExtensionContext, state: PiForgeRuntimeState, deps: LifecycleDeps): void {
+async function restoreBranchScopedRuntime(ctx: ExtensionContext, state: PiForgeRuntimeState, deps: LifecycleDeps): Promise<void> {
 	state.sessionVariables = getRestoredVariables(ctx);
 	state.currentVariableStore = undefined;
 	const restoredActiveId = getRestoredActiveId(ctx);
 	state.lastPersistedActiveId = restoredActiveId;
-	deps.reloadStacks(ctx, restoredActiveId);
+	await deps.reloadStacks(ctx, restoredActiveId);
 }
 
 function getCurrentBranchEntries(ctx: ExtensionContext): unknown[] {

package/src/preset-command.ts

@@ -6,12 +6,13 @@ import { renderDiagnostics, renderPreview, showText } from "./preview.ts";
 import type { PiForgeRuntimeState } from "./runtime-state.ts";
 import { importSillyTavernPreset } from "./sillytavern-importer.ts";
 import { migrateLegacyPromptStacks, renderMigrationReport } from "./stack-migration.ts";
+import { forgeExtensionsDir, globalForgeExtensionsDir } from "./storage.ts";
 import type { LoadedPromptStack } from "./types.ts";
 
 export interface PresetCommandDeps {
 	selectedActiveId(): string | undefined;
 	setActive(id: string | undefined, ctx?: ExtensionCommandContext): boolean;
-	reloadStacks(ctx: ExtensionCommandContext, preferredId?: string): void;
+	reloadStacks(ctx: ExtensionCommandContext, preferredId?: string): Promise<void>;
 	openWebEditor(ctx: ExtensionCommandContext, mode?: "open" | "restart"): Promise<void>;
 	stopWebEditor(ctx: ExtensionCommandContext): Promise<void>;
 }
@@ -65,7 +66,7 @@ async function handlePresetCommand(
 			return;
 
 		case "reload":
-			deps.reloadStacks(ctx, deps.selectedActiveId());
+			await deps.reloadStacks(ctx, deps.selectedActiveId());
 			ctx.ui.notify(`pi-forge: reloaded ${state.stacks.length} prompt stack(s).`, "info");
 			return;
 
@@ -130,7 +131,7 @@ async function handlePresetCommand(
 				overwrite: flags.has("--overwrite"),
 				deleteLegacy: flags.has("--delete-legacy"),
 			});
-			if (!dryRun) deps.reloadStacks(ctx, deps.selectedActiveId());
+			if (!dryRun) await deps.reloadStacks(ctx, deps.selectedActiveId());
 			const changed = report.copied + report.overwritten;
 			const summary = dryRun
 				? `pi-forge: migration dry run found ${report.files.length} legacy stack file(s).`
@@ -220,7 +221,7 @@ async function handleImportSilly(
 	if (!existsSync(reportDir)) mkdirSync(reportDir, { recursive: true });
 	writeFileSync(reportPath, result.report, "utf8");
 
-	deps.reloadStacks(ctx, deps.selectedActiveId());
+	await deps.reloadStacks(ctx, deps.selectedActiveId());
 
 	ctx.ui.notify(`pi-forge: imported ${result.stack.id} (${result.stack.items.length} items)`, "info");
 	await showText(ctx, `pi-forge import report: ${result.stack.id}`, `Stack written to: ${stackPath}\nReport written to: ${reportPath}\n\n${result.report}`);
@@ -230,6 +231,10 @@ function renderStackList(state: PiForgeRuntimeState, ctx: ExtensionCommandContex
 	const lines = [
 		"Prompt stack directories:",
 		...promptStackReadDirs(ctx.cwd).map((dir, index) => `  ${index === 0 ? "primary" : "legacy"}: ${dir}`),
+		"Forge extension directories:",
+		`  global: ${globalForgeExtensionsDir()}`,
+		`  project: ${forgeExtensionsDir(ctx.cwd)}`,
+		`Loaded forge extensions: ${state.forgeExtensionPaths.length}`,
 		`Active stack: ${state.active?.stack.id ?? "(none)"}`,
 		"",
 	];
@@ -256,6 +261,10 @@ function renderCurrentDiagnostics(state: PiForgeRuntimeState): string {
 	const lines = ["# pi-forge diagnostics", ""];
 	lines.push("## Active stack load/validation diagnostics", "");
 	lines.push(state.active ? renderDiagnostics(state.active.diagnostics) : "No active prompt stack.");
+	lines.push("", "## pi-forge extension diagnostics", "");
+	lines.push(renderDiagnostics(state.forgeExtensionDiagnostics));
+	lines.push("", "## Loaded pi-forge extensions", "");
+	lines.push(state.forgeExtensionPaths.length > 0 ? state.forgeExtensionPaths.map((path) => `- ${path}`).join("\n") : "(none)");
 	lines.push("", "## Latest runtime compile diagnostics", "");
 	lines.push(renderDiagnostics(state.latestCompileDiagnostics));
 	return lines.join("\n");

package/src/runtime-state.ts

@@ -17,6 +17,8 @@ export interface PiForgeRuntimeState {
 	sessionVariables: Record<string, PromptVariableValue>;
 	lastPersistedActiveId?: string;
 	latestCompileDiagnostics: PromptStackDiagnostic[];
+	forgeExtensionDiagnostics: PromptStackDiagnostic[];
+	forgeExtensionPaths: string[];
 	interceptNextProviderPayload: boolean;
 	interceptPayloadSavePath?: string;
 	interceptPayloadDisplayTarget: PayloadDisplayTarget;
@@ -30,6 +32,8 @@ export function createRuntimeState(): PiForgeRuntimeState {
 		contextRewritePending: false,
 		sessionVariables: {},
 		latestCompileDiagnostics: [],
+		forgeExtensionDiagnostics: [],
+		forgeExtensionPaths: [],
 		interceptNextProviderPayload: false,
 		interceptPayloadDisplayTarget: "editor",
 	};

package/src/storage.ts

@@ -1,9 +1,26 @@
+import { homedir } from "node:os";
 import { isAbsolute, join, relative, resolve } from "node:path";
 
 export function promptStacksDir(cwd: string): string {
 	return join(cwd, ".pi", "forge", "prompt-stacks");
 }
 
+export function forgeDir(cwd: string): string {
+	return join(cwd, ".pi", "forge");
+}
+
+export function forgeExtensionsDir(cwd: string): string {
+	return join(forgeDir(cwd), "extensions");
+}
+
+export function globalForgeDir(): string {
+	return join(homedir(), ".pi", "forge");
+}
+
+export function globalForgeExtensionsDir(): string {
+	return join(globalForgeDir(), "extensions");
+}
+
 export function legacyPromptStacksDir(cwd: string): string {
 	return join(cwd, ".pi", "prompt-stacks");
 }