@zihanw/pi-forge 0.1.0 → 0.3.0

package/src/index.ts

@@ -1,34 +1,71 @@
-import { writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { buildSessionContext, type BuildSystemPromptOptions, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
 import {
 	compileMessages,
 	compileSystemPrompt,
 	createPromptVariableStore,
+	agentMessageToPreviewText,
 	getLatestUserMessage,
 	markSessionVariablesClean,
-	renderPreviewMessages,
 	resetTurnVariables,
 } from "./compiler.ts";
-import { chooseDefaultStack, isDisabledPromptStackId, loadPromptStacks, promptStacksDir } from "./loader.ts";
+import { chooseDefaultStack, isDisabledPromptStackId, loadPromptStacks, promptStackPath, promptStackReadDirs } from "./loader.ts";
+import { createProviderPayloadCapture, estimatePayloadTokens } from "./payload-capture.ts";
+import { applyResourcePolicy, hasResourcePolicy } from "./policy.ts";
+import { applyFinalizeRegexRulesToMessage } from "./regex.ts";
 import { importSillyTavernPreset } from "./sillytavern-importer.ts";
-import type { LoadedPromptStack, PromptStackDiagnostic, PromptVariableStore } from "./types.ts";
+import { migrateLegacyPromptStacks, renderMigrationReport } from "./stack-migration.ts";
+import type { CompileMessageSource, LoadedPromptStack, PromptStackDiagnostic, PromptVariableValue, PromptVariableStore } from "./types.ts";
+import { createWebEditorHost, loadWebEditorSettings, type WebHostRuntime } from "./web-host.ts";
+import { startWebEditorServer, type WebEditorPayloadCapture, type WebEditorPayloadSnapshot, type WebEditorPreview, type WebEditorPreviewSection, type WebEditorServer } from "./web-editor/index.ts";
 
 const STATE_ENTRY_TYPE = "pi-forge-prompt-stack-state";
 const VARIABLE_ENTRY_TYPE = "pi-forge-variable-state";
-const AGENT_VAR_PREFIX = "agent.";
+const WEB_EDITOR_GLOBAL_KEY = "__piForgeWebEditor";
+
+type PayloadDisplayTarget = "editor" | "web";
+
+interface SharedWebEditorState {
+	server?: WebEditorServer;
+	cwd?: string;
+	preferredPort?: number;
+}
+
+interface SharedWebEditorRegistry {
+	byCwd: Record<string, SharedWebEditorState | undefined>;
+}
+
+type PiForgeGlobal = typeof globalThis & {
+	__piForgeWebEditor?: SharedWebEditorRegistry;
+};
+
+function getSharedWebEditorRegistry(): SharedWebEditorRegistry {
+	const globalScope = globalThis as PiForgeGlobal;
+	globalScope[WEB_EDITOR_GLOBAL_KEY] ??= { byCwd: {} };
+	return globalScope[WEB_EDITOR_GLOBAL_KEY];
+}
 
 export default function piForge(pi: ExtensionAPI) {
+	const sharedWebEditors = getSharedWebEditorRegistry();
 	let stacks: LoadedPromptStack[] = [];
 	let active: LoadedPromptStack | undefined;
 	let currentSystemPromptOptions: BuildSystemPromptOptions | undefined;
 	let currentLatestUserMessage: string | undefined;
 	let currentVariableStore: PromptVariableStore | undefined;
 	let contextRewritePending = false;
-	let sessionVariables: Record<string, string> = {};
+	let sessionVariables: Record<string, PromptVariableValue> = {};
 	let lastPersistedActiveId: string | undefined;
 	let interceptNextProviderPayload = false;
+	let interceptPayloadSavePath: string | undefined;
+	let interceptPayloadDisplayTarget: PayloadDisplayTarget = "editor";
+	let payloadCaptureArmedAt: string | undefined;
+	let latestProviderPayloadCapture: WebEditorPayloadCapture | undefined;
+	let latestCompileDiagnostics: PromptStackDiagnostic[] = [];
+	let webEditor: WebEditorServer | undefined;
+	let webEditorCwd: string | undefined;
+	let webEditorPreferredPort: number | undefined;
+	let toolPolicyBaseline: string[] | undefined;
 
 	function activeId(): string | undefined {
 		return active?.stack.id;
@@ -50,6 +87,7 @@ export default function piForge(pi: ExtensionAPI) {
 			active = undefined;
 			if (id) persistActiveSelection("none");
 			if (ctx) updateStatus(ctx);
+			syncActiveToolPolicy(ctx);
 			return true;
 		}
 
@@ -58,6 +96,7 @@ export default function piForge(pi: ExtensionAPI) {
 		active = found;
 		persistActiveSelection(found.stack.id);
 		if (ctx) updateStatus(ctx);
+		syncActiveToolPolicy(ctx);
 		return true;
 	}
 
@@ -65,6 +104,7 @@ export default function piForge(pi: ExtensionAPI) {
 		if (!ctx.isProjectTrusted()) {
 			stacks = [];
 			active = undefined;
+			syncActiveToolPolicy(ctx);
 			ctx.ui.notify("pi-forge: project is not trusted; prompt stacks are disabled.", "warning");
 			updateStatus(ctx);
 			return;
@@ -73,6 +113,7 @@ export default function piForge(pi: ExtensionAPI) {
 		stacks = loadPromptStacks(ctx.cwd);
 		active = chooseDefaultStack(stacks, preferredId);
 		updateStatus(ctx);
+		syncActiveToolPolicy(ctx);
 	}
 
 	function updateStatus(ctx: ExtensionContext): void {
@@ -80,9 +121,42 @@ export default function piForge(pi: ExtensionAPI) {
 			ctx.ui.setStatus("pi-forge", ctx.ui.theme.fg("accent", "stack:" + active.stack.id));
 		} else {
 			ctx.ui.setStatus("pi-forge", undefined);
+			latestCompileDiagnostics = [];
+			ctx.ui.setStatus("pi-forge-diagnostics", undefined);
 		}
 	}
 
+	function syncActiveToolPolicy(ctx?: ExtensionContext): void {
+		const policy = active?.stack.tools;
+		if (!hasResourcePolicy(policy)) {
+			restoreToolPolicy(ctx);
+			return;
+		}
+
+		const baseline = toolPolicyBaseline ?? pi.getActiveTools();
+		toolPolicyBaseline ??= [...baseline];
+		const nextTools = applyResourcePolicy(filterKnownTools(baseline), policy);
+		pi.setActiveTools(nextTools);
+		if (ctx) {
+			const label = nextTools.length > 0 ? `tools:${nextTools.length}` : "tools:none";
+			ctx.ui.setStatus("pi-forge-tools", ctx.ui.theme.fg(nextTools.length > 0 ? "accent" : "warning", label));
+		}
+	}
+
+	function restoreToolPolicy(ctx?: ExtensionContext): void {
+		if (toolPolicyBaseline) {
+			pi.setActiveTools(filterKnownTools(toolPolicyBaseline));
+			toolPolicyBaseline = undefined;
+		}
+		if (ctx) ctx.ui.setStatus("pi-forge-tools", undefined);
+	}
+
+	function filterKnownTools(names: string[]): string[] {
+		const known = new Set(pi.getAllTools().map((tool) => tool.name));
+		if (known.size === 0) return names;
+		return names.filter((name) => known.has(name));
+	}
+
 	function notifyActivePreset(ctx: ExtensionContext, detail: string): void {
 		if (!active) return;
 		const errorCount = active.diagnostics.filter((d) => d.level === "error").length;
@@ -91,8 +165,152 @@ export default function piForge(pi: ExtensionAPI) {
 		ctx.ui.notify("pi-forge: active preset " + active.stack.id + suffix + " (" + detail + ")", errorCount ? "error" : "info");
 	}
 
+	function recordCompileDiagnostics(ctx: ExtensionContext, diagnostics: PromptStackDiagnostic[]): void {
+		latestCompileDiagnostics = diagnostics;
+		const errors = diagnostics.filter((d) => d.level === "error").length;
+		const warnings = diagnostics.filter((d) => d.level === "warning").length;
+		if (errors || warnings) {
+			ctx.ui.setStatus("pi-forge-diagnostics", ctx.ui.theme.fg(errors ? "error" : "warning", `forge:${errors}e/${warnings}w`));
+			return;
+		}
+		ctx.ui.setStatus("pi-forge-diagnostics", undefined);
+	}
+
+	function webHostRuntime(ctx: ExtensionCommandContext): WebHostRuntime {
+		return {
+			getStacks: () => stacks,
+			getActive: () => active,
+			getActiveId: activeId,
+			getSelectedActiveId: selectedActiveId,
+			setActive: (id) => setActive(id, ctx),
+			reloadStacks: (preferredId) => reloadStacks(ctx, preferredId),
+			buildPreview: (target) => buildPreview(ctx, target),
+			getPayload: () => ({ ok: true, ...webPayloadSnapshot() }),
+			armPayload: (savePath) => {
+				armPayloadIntercept(ctx, savePath, "web");
+				return { ok: true, ...webPayloadSnapshot() };
+			},
+			clearPayload: () => {
+				clearPayloadCapture(ctx);
+				return { ok: true, ...webPayloadSnapshot() };
+			},
+		};
+	}
+
+	function sharedWebEditorForCwd(cwd: string): SharedWebEditorState {
+		sharedWebEditors.byCwd[cwd] ??= {};
+		return sharedWebEditors.byCwd[cwd];
+	}
+
+	function syncWebEditorFromShared(cwd: string): void {
+		const shared = sharedWebEditorForCwd(cwd);
+		webEditor = shared.server;
+		webEditorCwd = shared.cwd;
+		webEditorPreferredPort = shared.preferredPort;
+	}
+
+	function rememberWebEditor(server: WebEditorServer, cwd: string, preferredPort: number | undefined): void {
+		const shared = sharedWebEditorForCwd(cwd);
+		webEditor = server;
+		webEditorCwd = cwd;
+		webEditorPreferredPort = preferredPort;
+		shared.server = server;
+		shared.cwd = cwd;
+		shared.preferredPort = preferredPort;
+	}
+
+	function clearWebEditor(server: WebEditorServer): void {
+		if (webEditor === server) {
+			webEditor = undefined;
+			webEditorCwd = undefined;
+			webEditorPreferredPort = undefined;
+		}
+		for (const [cwd, shared] of Object.entries(sharedWebEditors.byCwd)) {
+			if (shared?.server === server) delete sharedWebEditors.byCwd[cwd];
+		}
+	}
+
+	function refreshWebEditorHost(ctx: ExtensionContext): void {
+		syncWebEditorFromShared(ctx.cwd);
+		if (!webEditor) return;
+		const commandCtx = ctx as ExtensionCommandContext;
+		webEditor.updateHost(createWebEditorHost(commandCtx, webHostRuntime(commandCtx)));
+		rememberWebEditor(webEditor, ctx.cwd, webEditorPreferredPort);
+		ctx.ui.setStatus("pi-forge-editor", ctx.ui.theme.fg("accent", `editor:${webEditor.port}`));
+	}
+
+	async function openWebEditor(ctx: ExtensionCommandContext, mode: "open" | "restart" = "open"): Promise<void> {
+		syncWebEditorFromShared(ctx.cwd);
+		const settings = loadWebEditorSettings(ctx);
+		for (const warning of settings.warnings) ctx.ui.notify(warning, "warning");
+
+		if (webEditor && (mode === "restart" || webEditorPreferredPort !== settings.preferredPort)) {
+			const server = webEditor;
+			await server.close();
+			clearWebEditor(server);
+			ctx.ui.setStatus("pi-forge-editor", undefined);
+		}
+
+		if (!webEditor) {
+			try {
+				webEditor = await startWebEditorServer(createWebEditorHost(ctx, webHostRuntime(ctx)), { port: settings.preferredPort });
+			} catch (error) {
+				if (settings.preferredPort !== undefined) {
+					const detail = error instanceof Error ? error.message : String(error);
+					ctx.ui.notify(`pi-forge: preferred editor port 127.0.0.1:${settings.preferredPort} was unavailable (${detail}); using an available port instead.`, "warning");
+					try {
+						webEditor = await startWebEditorServer(createWebEditorHost(ctx, webHostRuntime(ctx)));
+					} catch (fallbackError) {
+						const fallbackDetail = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
+						ctx.ui.setStatus("pi-forge-editor", undefined);
+						ctx.ui.notify(`pi-forge: failed to start stack editor on an available localhost port: ${fallbackDetail}.`, "error");
+						return;
+					}
+				} else {
+					const detail = error instanceof Error ? error.message : String(error);
+					ctx.ui.setStatus("pi-forge-editor", undefined);
+					ctx.ui.notify(`pi-forge: failed to start stack editor on an available localhost port: ${detail}.`, "error");
+					return;
+				}
+			}
+			rememberWebEditor(webEditor, ctx.cwd, settings.preferredPort);
+			ctx.ui.setStatus("pi-forge-editor", ctx.ui.theme.fg("accent", `editor:${webEditor.port}`));
+			ctx.ui.notify(`pi-forge: stack editor running at ${webEditor.url}`, "info");
+		} else {
+			webEditor.updateHost(createWebEditorHost(ctx, webHostRuntime(ctx)));
+			rememberWebEditor(webEditor, ctx.cwd, settings.preferredPort);
+			ctx.ui.setStatus("pi-forge-editor", ctx.ui.theme.fg("accent", `editor:${webEditor.port}`));
+			ctx.ui.notify(`pi-forge: stack editor already running at ${webEditor.url}`, "info");
+		}
+
+		await showText(ctx, "pi-forge stack editor", `Open the local stack editor:\n\n${webEditor.url}\n\nServer bound to 127.0.0.1:${webEditor.port}\nOptional config: ${settings.configPath}\nProject: ${webEditorCwd}`);
+	}
+
+	async function stopWebEditor(ctx: ExtensionCommandContext): Promise<void> {
+		syncWebEditorFromShared(ctx.cwd);
+		if (!webEditor) {
+			ctx.ui.notify("pi-forge: stack editor is not running.", "info");
+			return;
+		}
+		const server = webEditor;
+		await server.close();
+		clearWebEditor(server);
+		ctx.ui.setStatus("pi-forge-editor", undefined);
+		ctx.ui.notify("pi-forge: stack editor stopped.", "info");
+	}
+
+	function getCurrentBranchEntries(ctx: ExtensionContext): unknown[] {
+		const leafId = ctx.sessionManager.getLeafId();
+		if (leafId === null) return [];
+		const sessionManager = ctx.sessionManager as {
+			getBranch?: (fromId?: string) => unknown[];
+			getEntries: () => unknown[];
+		};
+		return sessionManager.getBranch ? sessionManager.getBranch(leafId ?? undefined) : sessionManager.getEntries();
+	}
+
 	function getRestoredActiveId(ctx: ExtensionContext): string | undefined {
-		const entries = ctx.sessionManager.getEntries();
+		const entries = getCurrentBranchEntries(ctx);
 		for (let i = entries.length - 1; i >= 0; i--) {
 			const entry = entries[i] as { type?: string; customType?: string; data?: { activeStackId?: unknown } };
 			if (entry.type === "custom" && entry.customType === STATE_ENTRY_TYPE) {
@@ -102,13 +320,13 @@ export default function piForge(pi: ExtensionAPI) {
 		return undefined;
 	}
 
-	function getRestoredVariables(ctx: ExtensionContext): Record<string, string> {
-		const entries = ctx.sessionManager.getEntries();
+	function getRestoredVariables(ctx: ExtensionContext): Record<string, PromptVariableValue> {
+		const entries = getCurrentBranchEntries(ctx);
 		for (let i = entries.length - 1; i >= 0; i--) {
 			const entry = entries[i] as { type?: string; customType?: string; data?: { variables?: unknown } };
 			if (entry.type !== "custom" || entry.customType !== VARIABLE_ENTRY_TYPE) continue;
 			if (!entry.data || typeof entry.data.variables !== "object" || Array.isArray(entry.data.variables)) return {};
-			return normalizeStringRecord(entry.data.variables as Record<string, unknown>);
+			return normalizeVariableRecord(entry.data.variables as Record<string, unknown>);
 		}
 		return {};
 	}
@@ -120,32 +338,52 @@ export default function piForge(pi: ExtensionAPI) {
 		markSessionVariablesClean(store);
 	}
 
-	function normalizeStringRecord(value: Record<string, unknown>): Record<string, string> {
-		const result: Record<string, string> = {};
+	function normalizeVariableRecord(value: Record<string, unknown>): Record<string, PromptVariableValue> {
+		const result: Record<string, PromptVariableValue> = {};
 		for (const [key, raw] of Object.entries(value)) {
-			if (typeof raw === "string") result[key] = raw;
+			if (isPromptVariableValue(raw)) result[key] = raw;
 		}
 		return result;
 	}
 
-	pi.on("session_start", async (event, ctx) => {
+	function isPromptVariableValue(value: unknown): value is PromptVariableValue {
+		if (value === null) return true;
+		const type = typeof value;
+		if (type === "string" || type === "boolean") return true;
+		if (type === "number") return Number.isFinite(value);
+		if (Array.isArray(value)) return value.every(isPromptVariableValue);
+		if (!value || typeof value !== "object") return false;
+		return Object.values(value as Record<string, unknown>).every(isPromptVariableValue);
+	}
+
+	function restoreBranchScopedRuntime(ctx: ExtensionContext): void {
 		sessionVariables = getRestoredVariables(ctx);
 		currentVariableStore = undefined;
 		const restoredActiveId = getRestoredActiveId(ctx);
 		lastPersistedActiveId = restoredActiveId;
 		reloadStacks(ctx, restoredActiveId);
+	}
+
+	pi.on("session_start", async (event, ctx) => {
+		restoreBranchScopedRuntime(ctx);
+		refreshWebEditorHost(ctx);
 		notifyActivePreset(ctx, "after session " + event.reason);
 	});
 
 	pi.on("session_tree", async (_event, ctx) => {
+		restoreBranchScopedRuntime(ctx);
+		refreshWebEditorHost(ctx);
 		notifyActivePreset(ctx, "after tree navigation");
 	});
 
 	pi.on("session_compact", async (_event, ctx) => {
+		restoreBranchScopedRuntime(ctx);
+		refreshWebEditorHost(ctx);
 		notifyActivePreset(ctx, "after compaction");
 	});
 
 	pi.on("turn_start", async () => {
+		syncActiveToolPolicy();
 		const id = activeId();
 		if (id) persistActiveSelection(id);
 	});
@@ -164,6 +402,7 @@ export default function piForge(pi: ExtensionAPI) {
 			{ options: event.systemPromptOptions, ctx, latestUserMessage: event.prompt, now: new Date(), variables: currentVariableStore },
 			event.systemPrompt,
 		);
+		recordCompileDiagnostics(ctx, result.diagnostics);
 		persistVariablesIfDirty(currentVariableStore);
 
 		return { systemPrompt: result.systemPrompt };
@@ -185,10 +424,20 @@ export default function piForge(pi: ExtensionAPI) {
 			{ options: currentSystemPromptOptions, ctx, latestUserMessage, now: new Date(), variables: currentVariableStore },
 			event.messages,
 		);
+		recordCompileDiagnostics(ctx, [...latestCompileDiagnostics, ...result.diagnostics]);
 		persistVariablesIfDirty(currentVariableStore);
 		return { messages: result.messages };
 	});
 
+	pi.on("message_end", async (event, ctx) => {
+		if (!active) return;
+		const diagnostics: PromptStackDiagnostic[] = [];
+		const message = applyFinalizeRegexRulesToMessage(active.stack, event.message, diagnostics);
+		if (diagnostics.length > 0) recordCompileDiagnostics(ctx, [...latestCompileDiagnostics, ...diagnostics]);
+		if (!message) return;
+		return { message };
+	});
+
 	pi.on("agent_end", async () => {
 		persistVariablesIfDirty(currentVariableStore);
 		currentSystemPromptOptions = undefined;
@@ -199,64 +448,100 @@ export default function piForge(pi: ExtensionAPI) {
 
 	pi.on("before_provider_request", async (event, ctx) => {
 		if (!interceptNextProviderPayload) return;
+		const savePath = interceptPayloadSavePath;
+		const displayTarget = interceptPayloadDisplayTarget;
 		interceptNextProviderPayload = false;
+		interceptPayloadSavePath = undefined;
+		interceptPayloadDisplayTarget = "editor";
+		payloadCaptureArmedAt = undefined;
 		ctx.ui.setStatus("pi-forge-intercept", undefined);
 
-		const payload = safeStringify(event.payload);
+		const capture = captureProviderPayload(event.payload, savePath);
+		if (savePath) {
+			if (!ctx.isProjectTrusted()) {
+				ctx.ui.notify("pi-forge: project is not trusted; refusing to save provider payload.", "warning");
+			} else {
+				const resolvedPath = savePath.startsWith("/") ? savePath : join(ctx.cwd, savePath);
+				mkdirSync(dirname(resolvedPath), { recursive: true });
+				writeFileSync(resolvedPath, capture.text, "utf8");
+				ctx.ui.notify(`pi-forge: provider payload saved to ${resolvedPath} (${capture.chars} chars, ~${capture.approxTokens} tokens)`, "info");
+			}
+		}
+
+		if (displayTarget === "web") {
+			ctx.ui.notify(`pi-forge: provider payload captured for web editor (${capture.chars} chars, ~${capture.approxTokens} tokens).`, "info");
+			return;
+		}
+
 		if (ctx.hasUI) {
-			await ctx.ui.editor("pi-forge: provider payload", payload);
+			await ctx.ui.editor(`pi-forge: provider payload (${capture.chars} chars, ~${capture.approxTokens} tokens)`, capture.text);
 			return;
 		}
 
-		console.log(payload);
+		console.log(capture.text);
 	});
 
-	pi.registerTool({
-		name: "forge_set_var",
-		label: "Set Prompt Variable",
-		description: "Set a persistent session variable in the active prompt stack. Only variables starting with 'agent.' can be written by the agent; other variables are read-only.",
-		promptSnippet: "Set agent-scoped prompt stack variables for cross-turn state (character mood, task progress, discovered facts).",
-		promptGuidelines: [
-			"Use forge_set_var to persist state across turns — character mood, story progress, task checkpoints, or discovered facts the user might ask about later.",
-			`Only variable names starting with '${AGENT_VAR_PREFIX}' are writable. Static and manually-set variables are read-only.`,
-			"Do not use forge_set_var for prompt configuration; it is for tracked runtime state only.",
-		],
-		parameters: Type.Object({
-			name: Type.String({ description: `Variable name (must start with '${AGENT_VAR_PREFIX}')` }),
-			value: Type.String({ description: "Variable value" }),
-		}),
-		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-			const { name, value } = params;
-			if (!name.startsWith(AGENT_VAR_PREFIX)) {
-				return {
-					content: [{ type: "text", text: `Error: only variables starting with '${AGENT_VAR_PREFIX}' are writable by the agent. Received: ${name}` }],
-					details: { error: "namespace restriction", name },
-				};
-			}
-			sessionVariables[name] = value;
-			pi.appendEntry(VARIABLE_ENTRY_TYPE, { variables: { ...sessionVariables } });
-			return {
-				content: [{ type: "text", text: `Variable ${name} set.` }],
-				details: { name, value },
-			};
-		},
-	});
+	function armPayloadIntercept(ctx: ExtensionCommandContext, savePath?: string, displayTarget: PayloadDisplayTarget = "editor"): void {
+		interceptNextProviderPayload = true;
+		interceptPayloadSavePath = savePath;
+		interceptPayloadDisplayTarget = displayTarget;
+		payloadCaptureArmedAt = new Date().toISOString();
+		latestProviderPayloadCapture = undefined;
+		ctx.ui.setStatus("pi-forge-intercept", ctx.ui.theme.fg("warning", savePath ? "payload:armed+save" : "payload:armed"));
+		if (displayTarget === "web") {
+			ctx.ui.notify(savePath ? `pi-forge: next provider payload will be captured in the web editor and saved to ${savePath}.` : "pi-forge: next provider payload will be captured in the web editor.", "info");
+			return;
+		}
+		ctx.ui.notify(savePath ? `pi-forge: next provider payload will be displayed and saved to ${savePath}.` : "pi-forge: next provider payload will be displayed before sending.", "info");
+	}
+
+	function clearPayloadCapture(ctx: ExtensionCommandContext): void {
+		interceptNextProviderPayload = false;
+		interceptPayloadSavePath = undefined;
+		interceptPayloadDisplayTarget = "editor";
+		payloadCaptureArmedAt = undefined;
+		latestProviderPayloadCapture = undefined;
+		ctx.ui.setStatus("pi-forge-intercept", undefined);
+	}
 
 	pi.registerCommand("intercept", {
 		description: "Display the next provider payload before it is sent",
 		handler: async (_args, ctx) => {
-			interceptNextProviderPayload = true;
-			ctx.ui.setStatus("pi-forge-intercept", ctx.ui.theme.fg("warning", "intercept:armed"));
-			ctx.ui.notify("pi-forge: next provider payload will be displayed before sending.", "info");
+			armPayloadIntercept(ctx);
+		},
+	});
+
+	pi.registerCommand("payload", {
+		description: "Inspect or save provider payloads: /payload next [save=<path>]",
+		getArgumentCompletions: (prefix) => {
+			const parts = prefix.trimStart().split(/\s+/);
+			if (parts.length <= 1 && !prefix.endsWith(" ")) {
+				return ["next"].filter((cmd) => cmd.startsWith(parts[0] ?? "")).map((cmd) => ({ value: cmd, label: cmd }));
+			}
+			if (parts[0] === "next" && parts.length <= 2) {
+				const suggestion = "save=.pi/forge/payloads/last.json";
+				return suggestion.startsWith(parts[1] ?? "") ? [{ value: `next ${suggestion}`, label: suggestion }] : null;
+			}
+			return null;
+		},
+		handler: async (args, ctx) => {
+			const [command = "next", ...rest] = args.trim() ? args.trim().split(/\s+/) : ["next"];
+			if (command !== "next") {
+				ctx.ui.notify(`Unknown /payload subcommand: ${command}`, "warning");
+				return;
+			}
+			const saveArg = rest.find((arg) => arg.startsWith("save="));
+			const savePath = saveArg?.slice("save=".length).trim() || undefined;
+			armPayloadIntercept(ctx, savePath);
 		},
 	});
 
 	pi.registerCommand("preset", {
-		description: "Manage pi-forge prompt stacks: list, use, preview, validate, reload, vars",
+		description: "Manage pi-forge prompt stacks: list, use, preview, validate, reload, ui",
 		getArgumentCompletions: (prefix) => {
 			const parts = prefix.trimStart().split(/\s+/);
 			if (parts.length <= 1 && !prefix.endsWith(" ")) {
-				const commands = ["list", "use", "preview", "validate", "reload", "status", "vars", "import-silly"];
+				const commands = ["list", "use", "preview", "validate", "diagnostics", "reload", "status", "import-silly", "migrate-stacks", "ui"];
 				return commands.filter((cmd) => cmd.startsWith(parts[0] ?? "")).map((cmd) => ({ value: cmd, label: cmd }));
 			}
 			const first = parts[0];
@@ -265,17 +550,15 @@ export default function piForge(pi: ExtensionAPI) {
 				const ids = ["none", ...stacks.map((loaded) => loaded.stack.id)];
 				return ids.filter((id) => id.startsWith(fragment)).map((id) => ({ value: `${first} ${id}`, label: id }));
 			}
-			if (first === "vars") {
-				const sub = parts[1] ?? "";
-				if (parts.length <= 2 && !prefix.endsWith(" ")) {
-					const subs = ["set", "get", "clear", "list"];
-					return subs.filter((s) => s.startsWith(sub)).map((s) => ({ value: `vars ${s}`, label: s }));
-				}
-				if (["set", "get", "clear"].includes(sub) && parts.length <= 3) {
-					const fragment = parts[2] ?? "";
-					const names = Object.keys(sessionVariables);
-					return names.filter((n) => n.startsWith(fragment)).map((n) => ({ value: `vars ${sub} ${n}`, label: n }));
-				}
+			if (first === "ui" && parts.length <= 2) {
+				const fragment = parts[1] ?? "";
+				const subs = ["stop", "restart"];
+				return subs.filter((s) => s.startsWith(fragment)).map((s) => ({ value: `ui ${s}`, label: s }));
+			}
+			if (first === "migrate-stacks") {
+				const fragment = parts[parts.length - 1] ?? "";
+				const flags = ["--dry-run", "--overwrite", "--delete-legacy"];
+				return flags.filter((flag) => flag.startsWith(fragment)).map((flag) => ({ value: `${parts.slice(0, -1).join(" ")} ${flag}`.trim(), label: flag }));
 			}
 			return null;
 		},
@@ -299,49 +582,13 @@ export default function piForge(pi: ExtensionAPI) {
 				ctx.ui.notify(`pi-forge: reloaded ${stacks.length} prompt stack(s).`, "info");
 				return;
 
-			case "vars": {
+			case "ui": {
 				const sub = rest[0];
-
-				if (sub === "set") {
-					const name = rest[1];
-					const value = rest.slice(2).join(" ");
-					if (!name || value === "") {
-						ctx.ui.notify("Usage: /preset vars set <name> <value>", "warning");
-						return;
-					}
-					sessionVariables[name] = value;
-					pi.appendEntry(VARIABLE_ENTRY_TYPE, { variables: { ...sessionVariables } });
-					ctx.ui.notify(`pi-forge: set session variable ${name} = ${JSON.stringify(value)}`, "info");
+				if (sub === "stop") {
+					await stopWebEditor(ctx);
 					return;
 				}
-
-				if (sub === "get") {
-					const name = rest[1];
-					if (!name) {
-						ctx.ui.notify("Usage: /preset vars get <name>", "warning");
-						return;
-					}
-					const value = sessionVariables[name];
-					if (value === undefined) {
-						await showText(ctx, `pi-forge variable: ${name}`, `# ${name}\n\n(not set)`);
-					} else {
-						await showText(ctx, `pi-forge variable: ${name}`, `# ${name}\n\n${value}`);
-					}
-					return;
-				}
-
-				if (sub === "clear") {
-					const name = rest[1];
-					if (name) delete sessionVariables[name];
-					else sessionVariables = {};
-					currentVariableStore = createPromptVariableStore(sessionVariables);
-					pi.appendEntry(VARIABLE_ENTRY_TYPE, { variables: sessionVariables });
-					ctx.ui.notify(name ? `pi-forge: cleared session variable ${name}` : "pi-forge: cleared all session variables", "info");
-					return;
-				}
-
-				// No subcommand or "list" — show all variables
-				await showText(ctx, "pi-forge variables", renderVariablesList());
+				await openWebEditor(ctx, sub === "restart" ? "restart" : "open");
 				return;
 			}
 
@@ -379,23 +626,59 @@ export default function piForge(pi: ExtensionAPI) {
 				return;
 			}
 
+			case "diagnostics": {
+				await showText(ctx, "pi-forge diagnostics", renderCurrentDiagnostics());
+				return;
+			}
+
+			case "migrate-stacks": {
+				const flags = new Set(rest);
+				const dryRun = flags.has("--dry-run");
+				if (!ctx.isProjectTrusted() && !dryRun) {
+					ctx.ui.notify("pi-forge: project is not trusted; refusing to migrate prompt stacks.", "warning");
+					return;
+				}
+				const report = migrateLegacyPromptStacks(ctx.cwd, {
+					dryRun,
+					overwrite: flags.has("--overwrite"),
+					deleteLegacy: flags.has("--delete-legacy"),
+				});
+				if (!dryRun) reloadStacks(ctx, selectedActiveId());
+				const changed = report.copied + report.overwritten;
+				const summary = dryRun
+					? `pi-forge: migration dry run found ${report.files.length} legacy stack file(s).`
+					: `pi-forge: migrated ${changed} legacy stack file(s), skipped ${report.skipped}, errors ${report.errors}.`;
+				ctx.ui.notify(summary, report.errors ? "warning" : "info");
+				await showText(ctx, "pi-forge prompt-stack migration", renderMigrationReport(report));
+				return;
+			}
+
 			case "import-silly": {
+				if (!ctx.isProjectTrusted()) {
+					ctx.ui.notify("pi-forge: project is not trusted; refusing to write imported prompt stacks.", "warning");
+					return;
+				}
+
 				const sourcePath = rest[0];
 				if (!sourcePath) {
-					ctx.ui.notify("Usage: /preset import-silly <path> [character_id]", "warning");
+					ctx.ui.notify("Usage: /preset import-silly <path> [character_id] [--dry-run] [--overwrite]", "warning");
 					return;
 				}
 
+				const charIdToken = rest[1]?.startsWith("--") ? undefined : rest[1];
+				const flags = new Set(rest.slice(charIdToken ? 2 : 1));
+				const dryRun = flags.has("--dry-run");
+				let overwrite = flags.has("--overwrite");
+
 				const resolvedPath = sourcePath.startsWith("/") ? sourcePath : join(ctx.cwd, sourcePath);
 				if (!existsSync(resolvedPath)) {
 					ctx.ui.notify(`File not found: ${resolvedPath}`, "error");
 					return;
 				}
 
-				const charIdStr = rest[1];
-				const charId = charIdStr ? Number(charIdStr) : undefined;
-				if (charIdStr && (Number.isNaN(charId) || !Number.isFinite(charId))) {
-					ctx.ui.notify(`Invalid character_id: ${charIdStr}`, "error");
+				const charId = charIdToken ? Number(charIdToken) : undefined;
+				if (charIdToken && (Number.isNaN(charId) || !Number.isFinite(charId))) {
+					ctx.ui.notify(`Invalid character_id: ${charIdToken}`, "error");
 					return;
 				}
 
@@ -405,16 +688,34 @@ export default function piForge(pi: ExtensionAPI) {
 					return;
 				}
 
-				// Write the prompt stack
-				const stacksDir = promptStacksDir(ctx.cwd);
+				const existingStack = stacks.find((candidate) => candidate.stack.id === result.stack.id);
+				const stackPath = existingStack?.filePath ?? promptStackPath(ctx.cwd, result.stack.id);
+				const stacksDir = dirname(stackPath);
+				const reportDir = join(ctx.cwd, ".pi", "forge", "import-reports");
+				const reportPath = join(reportDir, `${result.stack.id}.md`);
+
+				if (dryRun) {
+					await showText(ctx, `pi-forge import dry run: ${result.stack.id}`, `Would write stack to: ${stackPath}\nWould write report to: ${reportPath}\n\n## Generated stack JSON\n\n\`\`\`json\n${JSON.stringify(result.stack, null, 2)}\n\`\`\`\n\n${result.report}`);
+					return;
+				}
+
+				const existingPaths = [stackPath, reportPath].filter((path) => existsSync(path));
+				if (existingPaths.length > 0 && !overwrite) {
+					if (!ctx.hasUI) {
+						ctx.ui.notify(`pi-forge: import would overwrite existing file(s): ${existingPaths.join(", ")}. Re-run with --overwrite.`, "error");
+						return;
+					}
+					overwrite = await ctx.ui.confirm("Overwrite pi-forge import output?", `These file(s) already exist:\n${existingPaths.join("\n")}\n\nOverwrite them?`);
+					if (!overwrite) {
+						ctx.ui.notify("pi-forge: import cancelled; existing files were left unchanged.", "info");
+						return;
+					}
+				}
+
 				if (!existsSync(stacksDir)) mkdirSync(stacksDir, { recursive: true });
-				const stackPath = join(stacksDir, `${result.stack.id}.json`);
 				writeFileSync(stackPath, JSON.stringify(result.stack, null, 2), "utf8");
 
-				// Write the import report
-				const reportDir = join(ctx.cwd, ".pi", "forge", "import-reports");
 				if (!existsSync(reportDir)) mkdirSync(reportDir, { recursive: true });
-				const reportPath = join(reportDir, `${result.stack.id}.md`);
 				writeFileSync(reportPath, result.report, "utf8");
 
 				// Reload stacks to pick up the new one
@@ -433,13 +734,14 @@ export default function piForge(pi: ExtensionAPI) {
 
 	function renderStackList(ctx: ExtensionCommandContext): string {
 		const lines = [
-			`Prompt stack directory: ${promptStacksDir(ctx.cwd)}`,
+			"Prompt stack directories:",
+			...promptStackReadDirs(ctx.cwd).map((dir, index) => `  ${index === 0 ? "primary" : "legacy"}: ${dir}`),
 			`Active stack: ${active?.stack.id ?? "(none)"}`,
 			"",
 		];
 
 		if (stacks.length === 0) {
-			lines.push("No prompt stacks found.", "Create .pi/prompt-stacks/default.json to auto-activate a stack.");
+			lines.push("No prompt stacks found.", "Create .pi/forge/prompt-stacks/default.json to auto-activate a stack.");
 			return lines.join("\n");
 		}
 
@@ -452,26 +754,41 @@ export default function piForge(pi: ExtensionAPI) {
 			lines.push(`  ${loaded.filePath}`);
 		}
 
-		lines.push("", "Commands:", "  /preset use <id|none>", "  /preset preview [id]", "  /preset validate [id]", "  /preset reload", "  /preset vars [set <name> <value>|get <name>|clear [name]]");
+		lines.push("", "Commands:", "  /preset use <id|none>", "  /preset preview [id]", "  /preset validate [id]", "  /preset diagnostics", "  /preset reload", "  /preset migrate-stacks [--dry-run] [--overwrite] [--delete-legacy]", "  /preset ui [stop|restart]");
 		return lines.join("\n");
 	}
 
-	function renderVariablesList(): string {
-		const lines = ["# pi-forge variables", "", "## Session variables", ""];
-		const sessionEntries = Object.entries(sessionVariables).sort(([a], [b]) => a.localeCompare(b));
-		if (sessionEntries.length === 0) lines.push("(none)");
-		else for (const [key, value] of sessionEntries) lines.push(`${key} = ${JSON.stringify(value)}`);
-
-		lines.push("", "## Active stack static variables", "");
-		const staticEntries = Object.entries(active?.stack.variables ?? {}).sort(([a], [b]) => a.localeCompare(b));
-		if (staticEntries.length === 0) lines.push("(none)");
-		else for (const [key, value] of staticEntries) lines.push(`${key} = ${JSON.stringify(value)}`);
-
-		lines.push("", "Turn variables are cleared for each user message and are only visible during prompt compilation.");
+	function renderCurrentDiagnostics(): string {
+		const lines = ["# pi-forge diagnostics", ""];
+		lines.push("## Active stack load/validation diagnostics", "");
+		lines.push(active ? renderDiagnostics(active.diagnostics) : "No active prompt stack.");
+		lines.push("", "## Latest runtime compile diagnostics", "");
+		lines.push(renderDiagnostics(latestCompileDiagnostics));
 		return lines.join("\n");
 	}
 
+	function webPayloadSnapshot(): WebEditorPayloadSnapshot {
+		if (interceptNextProviderPayload) {
+			return {
+				status: "armed",
+				armedAt: payloadCaptureArmedAt,
+				savePath: interceptPayloadSavePath,
+			};
+		}
+		if (latestProviderPayloadCapture) {
+			return {
+				status: "captured",
+				capture: latestProviderPayloadCapture,
+			};
+		}
+		return { status: "idle" };
+	}
+
 	function renderPreview(ctx: ExtensionCommandContext, target: LoadedPromptStack): string {
+		return buildPreview(ctx, target).text;
+	}
+
+	function buildPreview(ctx: ExtensionCommandContext, target: LoadedPromptStack): { text: string; preview: WebEditorPreview; diagnostics: PromptStackDiagnostic[] } {
 		const options = ctx.getSystemPromptOptions();
 		const sessionContext = buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId());
 		const latestUserMessage = getLatestUserMessage(sessionContext.messages);
@@ -480,8 +797,23 @@ export default function piForge(pi: ExtensionAPI) {
 		const system = compileSystemPrompt(target.stack, runtime, ctx.getSystemPrompt());
 		const messages = compileMessages(target.stack, runtime, sessionContext.messages);
 		const diagnostics = [...target.diagnostics, ...system.diagnostics, ...messages.diagnostics];
-
-		return [
+		const messageSections = messages.messages.map((message, index) => {
+			const content = agentMessageToPreviewText(message);
+			const source = messages.messageSources[index];
+			return previewSection(`message-${index}`, previewMessageTitle(source, index), content, message.role);
+		});
+		const systemSection = previewSection("system", "System prompt", system.systemPrompt || "(empty)");
+		const totalChars = systemSection.chars + messageSections.reduce((sum, section) => sum + section.chars, 0);
+		const preview: WebEditorPreview = {
+			stackId: target.stack.id,
+			generatedAt: new Date().toISOString(),
+			system: systemSection,
+			messages: messageSections,
+			totalChars,
+			approxTokens: estimatePayloadTokens(`${system.systemPrompt}\n${messageSections.map((section) => section.content).join("\n")}`),
+		};
+
+		const text = [
 			`# Prompt stack preview: ${target.stack.id}`,
 			"",
 			"## System prompt",
@@ -490,12 +822,51 @@ export default function piForge(pi: ExtensionAPI) {
 			"",
 			"## Message layout",
 			"",
-			renderPreviewMessages(messages.messages),
+			renderPreviewSectionText(messageSections),
 			"",
 			"## Diagnostics",
 			"",
 			renderDiagnostics(diagnostics),
 		].join("\n");
+
+		return { text, preview, diagnostics };
+	}
+
+	function previewMessageTitle(source: CompileMessageSource | undefined, index: number): string {
+		if (source?.kind === "stack-item") {
+			return source.itemName?.trim() || source.itemId || `Stack item ${index + 1}`;
+		}
+		if (source?.kind === "chat-history") {
+			const label = source.itemName?.trim() || "Chat history";
+			return `${label} #${source.historyIndex ?? index + 1}`;
+		}
+		if (source?.kind === "implicit-history") {
+			return `Conversation history #${source.historyIndex ?? index + 1}`;
+		}
+		return `Message ${index + 1}`;
+	}
+
+	function renderPreviewSectionText(sections: WebEditorPreviewSection[], maxChars = 8000): string {
+		let text = "";
+		for (const section of sections) {
+			const role = section.role ? ` (${section.role})` : "";
+			text += `\n--- ${section.title}${role} ---\n`;
+			text += section.content;
+			text += "\n";
+			if (text.length > maxChars) return `${text.slice(0, maxChars)}\n\n[preview truncated]`;
+		}
+		return text.trimStart();
+	}
+
+	function previewSection(id: string, title: string, content: string, role?: string): WebEditorPreviewSection {
+		return {
+			id,
+			title,
+			role,
+			content,
+			chars: content.length,
+			approxTokens: estimatePayloadTokens(content),
+		};
 	}
 
 	function renderDiagnostics(diagnostics: PromptStackDiagnostic[]): string {
@@ -511,11 +882,9 @@ export default function piForge(pi: ExtensionAPI) {
 		console.log(text);
 	}
 
-	function safeStringify(value: unknown): string {
-		try {
-			return JSON.stringify(value, null, 2);
-		} catch (error) {
-			return `Failed to stringify provider payload: ${error instanceof Error ? error.message : String(error)}`;
-		}
+	function captureProviderPayload(value: unknown, savePath?: string): WebEditorPayloadCapture {
+		const capture = createProviderPayloadCapture(value, { stackId: active?.stack.id, savePath });
+		latestProviderPayloadCapture = capture;
+		return capture;
 	}
 }