@happyvertical/smrt-cli 0.55.15 → 0.55.17

package/dist/{server-Dp096tZj.js → server-C69K3w-t.js}

@@ -1,12 +1,107 @@
 import { c as SMRT_SCOPE, l as loadRegistryManifest, r as cliVersion, s as validateCookbookText, t as createCookbookApplier, u as resolveRecipeIndex } from "./apply-BNDIdixP.js";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createHash, randomUUID } from "node:crypto";
 import { validateCookbook } from "@happyvertical/smrt-core/cookbook";
+import { createServer } from "node:http";
 import { Server } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { buildBatchTool, checkSchema, createCookbookEngine } from "@happyvertical/smrt-core/cookbook/engine";
+//#region src/commands/kitchen/mcp/preview.ts
+/** Loopback-only bridge for the live SvelteKit preview during local development. */
+async function startKitchenPreview(session, port, origin) {
+	if (!/^http:\/\/127\.0\.0\.1:\d+$/.test(origin)) throw new Error("Preview origin must be a 127.0.0.1 HTTP origin.");
+	const server = createServer(async (request, response) => {
+		response.setHeader("Cache-Control", "no-store");
+		response.setHeader("Vary", "Origin");
+		response.setHeader("Content-Type", "application/json; charset=utf-8");
+		if (request.headers.origin !== origin) {
+			response.writeHead(403).end(JSON.stringify({
+				ok: false,
+				error: "Origin refused."
+			}));
+			return;
+		}
+		response.setHeader("Access-Control-Allow-Origin", origin);
+		response.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+		response.setHeader("Access-Control-Allow-Headers", "Content-Type");
+		if (request.method === "OPTIONS") {
+			response.writeHead(204).end();
+			return;
+		}
+		const path = new URL(request.url ?? "/", "http://127.0.0.1").pathname;
+		const match = /^\/plans\/(plan-[a-f0-9-]{8,36})(\/commands)?$/.exec(path);
+		if (!match || !session.previewPlans.has(match[1]) || !(request.method === "GET" && !match[2] || request.method === "POST" && match[2])) {
+			response.writeHead(404).end(JSON.stringify({
+				ok: false,
+				error: "Not found."
+			}));
+			return;
+		}
+		try {
+			let result;
+			if (request.method === "GET") result = await session.call("get_plan", { planId: match[1] });
+			else {
+				if (!/^application\/json(?:\s*;|$)/i.test(request.headers["content-type"] ?? "")) {
+					response.writeHead(415).end(JSON.stringify({
+						ok: false,
+						error: "JSON required."
+					}));
+					return;
+				}
+				const chunks = [];
+				let bytes = 0;
+				for await (const chunk of request) {
+					bytes += chunk.length;
+					if (bytes > 2097152) {
+						response.writeHead(413).end(JSON.stringify({
+							ok: false,
+							error: "Request too large."
+						}));
+						return;
+					}
+					chunks.push(chunk);
+				}
+				const input = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+				if (!input || typeof input !== "object" || Array.isArray(input)) {
+					response.writeHead(400).end(JSON.stringify({
+						ok: false,
+						error: {
+							code: "invalid_input",
+							message: "A JSON object is required."
+						}
+					}));
+					return;
+				}
+				result = await session.call("run_commands", {
+					...input,
+					planId: match[1]
+				});
+			}
+			response.writeHead(200).end(JSON.stringify(result.data));
+		} catch {
+			response.writeHead(400).end(JSON.stringify({
+				ok: false,
+				error: {
+					code: "invalid_input",
+					message: "Invalid JSON request."
+				}
+			}));
+		}
+	});
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(port, "127.0.0.1", resolve);
+	});
+	const address = server.address();
+	if (!address || typeof address === "string") throw new Error("Preview listener has no port.");
+	return {
+		server,
+		url: `http://127.0.0.1:${address.port}`
+	};
+}
+//#endregion
 //#region src/commands/kitchen/mcp/catalog.ts
 /**
 * The engine catalog (#3752) built from real recipe manifests: the recipes
@@ -199,6 +294,19 @@ var snapshotSchema = {
 	required: ["revision"],
 	additionalProperties: true
 };
+/** A document and snapshot captured together from the current engine state. */
+var stateSchema = {
+	type: "object",
+	description: "Current authoritative state; paired atomically, including on replay.",
+	properties: {
+		snapshot: snapshotSchema,
+		cookbook: {
+			type: "object",
+			additionalProperties: true
+		}
+	},
+	required: ["snapshot", "cookbook"]
+};
 /** An output schema: `ok` always, `error` when it is false, plus the extras. */
 var output = (properties, required = []) => ({
 	$schema: SCHEMA,
@@ -315,7 +423,7 @@ var KITCHEN_TOOLS = [
 	{
 		name: "start_plan",
 		title: "Start a plan",
-		description: "Start a new plan for an app, empty or from a ready-made cookbook (see list_cookbooks). Returns the plan id every other tool takes. The plan lives in this server process until apply_plan writes it to a project.",
+		description: "Start a new plan for an app, empty or from a ready-made cookbook (see list_cookbooks). Returns the plan id every other tool takes.",
 		inputSchema: input({
 			cookbook: {
 				type: "string",
@@ -332,7 +440,8 @@ var KITCHEN_TOOLS = [
 		}),
 		outputSchema: output({
 			planId: { type: "string" },
-			snapshot: snapshotSchema
+			snapshot: snapshotSchema,
+			state: stateSchema
 		}, []),
 		annotations: annotations("Start a plan", {})
 	},
@@ -360,7 +469,8 @@ var KITCHEN_TOOLS = [
 				type: "array",
 				items: { type: "object" }
 			},
-			snapshot: snapshotSchema
+			snapshot: snapshotSchema,
+			state: stateSchema
 		}),
 		annotations: annotations("Change the plan", { idempotentHint: true })
 	},
@@ -371,10 +481,22 @@ var KITCHEN_TOOLS = [
 		inputSchema: input({ planId }, ["planId"]),
 		outputSchema: output({
 			planId: { type: "string" },
-			snapshot: snapshotSchema
+			snapshot: snapshotSchema,
+			state: stateSchema
 		}),
 		annotations: annotations("Get the plan", READ_ONLY)
 	},
+	{
+		name: "open_preview",
+		title: "Open the live app preview",
+		description: "Return a local browser URL for this plan when the Kitchen preview bridge is enabled. The app shell and chat then use the same plan.",
+		inputSchema: input({ planId }, ["planId"]),
+		outputSchema: output({
+			planId: { type: "string" },
+			url: { type: "string" }
+		}),
+		annotations: annotations("Open the live app preview", READ_ONLY)
+	},
 	{
 		name: "validate_plan",
 		title: "Validate the plan",
@@ -526,6 +648,10 @@ var KitchenSession = class KitchenSession {
 	options;
 	loaded;
 	plans = /* @__PURE__ */ new Map();
+	updates = /* @__PURE__ */ new Map();
+	previewUrl;
+	/** Plans `open_preview` handed to the browser; the preview bridge serves only these. */
+	previewPlans = /* @__PURE__ */ new Set();
 	constructor(options) {
 		this.options = options;
 	}
@@ -540,8 +666,93 @@ var KitchenSession = class KitchenSession {
 		}
 		return this.loaded;
 	}
-	plan(id) {
-		return (typeof id === "string" ? this.plans.get(id) : void 0) ?? fail("not_found", `No plan ${JSON.stringify(id)} in this server; call start_plan (a restart forgets plans).`, { path: "planId" });
+	planPath(id) {
+		if (!/^plan-[a-f0-9-]{8,36}$/.test(id)) throw new Error("Invalid plan id.");
+		if (!this.options.plansDir) throw new Error("Plans directory is not configured.");
+		return join(this.options.plansDir, `${id}.json`);
+	}
+	savePlan(id, engine) {
+		if (!this.options.plansDir) return;
+		mkdirSync(this.options.plansDir, {
+			recursive: true,
+			mode: 448
+		});
+		const target = this.planPath(id);
+		const temporary = `${target}.${randomUUID()}.tmp`;
+		const serialized = `${JSON.stringify(engine.state())}\n`;
+		try {
+			writeFileSync(temporary, serialized, { mode: 384 });
+			renameSync(temporary, target);
+			this.plans.set(id, {
+				engine,
+				serialized
+			});
+		} finally {
+			if (existsSync(temporary)) rmSync(temporary);
+		}
+	}
+	/** Serialize the read/check/write transaction across Kitchen processes. */
+	async lockPlan(id) {
+		if (!this.options.plansDir) return () => {};
+		mkdirSync(this.options.plansDir, {
+			recursive: true,
+			mode: 448
+		});
+		const path = `${this.planPath(id)}.lock`;
+		const token = randomUUID();
+		const deadline = Date.now() + 3e4;
+		for (;;) {
+			try {
+				const fd = openSync(path, "wx", 384);
+				try {
+					writeFileSync(fd, JSON.stringify({
+						pid: process.pid,
+						token
+					}));
+				} catch {
+					rmSync(path, { force: true });
+					return fail("unavailable", "The plan cannot be locked on this device.");
+				} finally {
+					closeSync(fd);
+				}
+				return () => {
+					try {
+						if (JSON.parse(readFileSync(path, "utf8")).token === token) unlinkSync(path);
+					} catch {}
+				};
+			} catch (cause) {
+				if (cause.code !== "EEXIST") return fail("unavailable", "The plan cannot be locked on this device.");
+			}
+			if (Date.now() >= deadline) return fail("conflict", "This plan is busy in another Kitchen session. Retry the same command; if it stays busy, stop Kitchen and remove its stale plan lock.");
+			await new Promise((resolve) => setTimeout(resolve, 40));
+		}
+	}
+	async plan(id) {
+		if (typeof id === "string" && this.options.plansDir) {
+			if (!/^plan-[a-f0-9-]{8,36}$/.test(id)) return fail("not_found", `No plan ${JSON.stringify(id)}.`, { path: "planId" });
+			let serialized;
+			try {
+				serialized = readFileSync(this.planPath(id), "utf8");
+			} catch (error) {
+				if (error.code === "ENOENT") return fail("not_found", `No plan ${JSON.stringify(id)}.`, { path: "planId" });
+				throw error;
+			}
+			const cached = this.plans.get(id);
+			if (cached?.serialized === serialized) return cached;
+			const saved = JSON.parse(serialized);
+			const { catalog } = await this.catalog();
+			const plan = {
+				engine: createCookbookEngine({
+					catalog,
+					state: saved,
+					undoPrefix: `undo-${randomUUID()}`
+				}),
+				serialized
+			};
+			this.plans.set(id, plan);
+			return plan;
+		}
+		return (typeof id === "string" ? this.plans.get(id) : void 0) ?? fail("not_found", `No plan ${JSON.stringify(id)} in this server; call start_plan.`, { path: "planId" });
 	}
 	/** Validate arguments against a tool's published schema. */
 	static check(tool, args) {
@@ -576,18 +787,38 @@ var KitchenSession = class KitchenSession {
 			case "start_plan": return this.startPlan(args);
 			case "run_commands": return this.runCommands(args);
 			case "get_plan": {
-				const plan = this.plan(args.planId);
+				const plan = await this.plan(args.planId);
 				if (!("engine" in plan)) return plan;
 				const snapshot = plan.engine.snapshot();
 				return {
 					data: {
 						ok: true,
 						planId: args.planId,
-						snapshot
+						snapshot,
+						state: {
+							snapshot,
+							cookbook: plan.engine.cookbook()
+						}
 					},
 					text: describeSnapshot(snapshot)
 				};
 			}
+			case "open_preview": {
+				const plan = await this.plan(args.planId);
+				if (!("engine" in plan)) return plan;
+				if (!this.previewUrl || !this.options.previewOrigin) return fail("unavailable", "The local preview bridge is not enabled.");
+				const port = new URL(this.previewUrl).port;
+				this.previewPlans.add(args.planId);
+				const url = `${this.options.previewOrigin}/?kitchenPlan=${encodeURIComponent(args.planId)}&kitchenPort=${port}`;
+				return {
+					data: {
+						ok: true,
+						planId: args.planId,
+						url
+					},
+					text: `Open the live app shell: ${url}`
+				};
+			}
 			case "validate_plan": return this.validatePlan(args);
 			case "export_plan": return this.exportPlan(args);
 			case "apply_plan": return this.applyPlan(args);
@@ -636,7 +867,10 @@ var KitchenSession = class KitchenSession {
 	}
 	async startPlan(args) {
 		const { catalog } = await this.catalog();
-		const engine = createCookbookEngine({ catalog });
+		const engine = createCookbookEngine({
+			catalog,
+			undoPrefix: `undo-${randomUUID()}`
+		});
 		const steps = [];
 		if (typeof args.cookbook === "string") steps.push({
 			name: "apply_cookbook",
@@ -650,27 +884,62 @@ var KitchenSession = class KitchenSession {
 			const result = engine.run(step);
 			if (!result.ok) return failFrom(result.error);
 		}
-		const id = `plan-${randomUUID().slice(0, 8)}`;
-		this.plans.set(id, { engine });
-		while (this.plans.size > 20) {
-			const oldest = this.plans.keys().next().value;
-			if (oldest === void 0) break;
-			this.plans.delete(oldest);
+		const id = `plan-${randomUUID()}`;
+		if (this.options.plansDir) try {
+			this.savePlan(id, engine);
+		} catch {
+			return fail("unavailable", "The plan could not be saved on this device.");
+		}
+		else {
+			this.plans.set(id, { engine });
+			while (this.plans.size > 20) {
+				const oldest = this.plans.keys().next().value;
+				if (oldest === void 0) break;
+				this.plans.delete(oldest);
+			}
 		}
 		const snapshot = engine.snapshot();
 		return {
 			data: {
 				ok: true,
 				planId: id,
-				snapshot
+				snapshot,
+				state: {
+					snapshot,
+					cookbook: engine.cookbook()
+				}
 			},
 			text: `Started ${id}.\n${describeSnapshot(snapshot)}`
 		};
 	}
-	runCommands(args) {
-		const plan = this.plan(args.planId);
+	async runCommands(args) {
+		const id = args.planId;
+		const previous = this.updates.get(id) ?? Promise.resolve();
+		let release;
+		const gate = new Promise((resolve) => {
+			release = resolve;
+		});
+		const current = previous.then(() => gate);
+		this.updates.set(id, current);
+		await previous;
+		try {
+			const lock = await this.lockPlan(id);
+			if (typeof lock !== "function") return lock;
+			try {
+				return await this.runCommandsUnlocked(args);
+			} finally {
+				lock();
+			}
+		} finally {
+			release();
+			if (this.updates.get(id) === current) this.updates.delete(id);
+		}
+	}
+	async runCommandsUnlocked(args) {
+		const plan = await this.plan(args.planId);
 		if (!("engine" in plan)) return plan;
 		const { planId: _planId, ...batch } = args;
+		if (!Array.isArray(batch.commands)) return fail("invalid_input", "commands must be an array.", { path: "commands" });
 		const commands = batch.commands;
 		const lone = commands.length === 1 && commands[0]?.name === "undo" ? plan.engine.run({
 			...commands[0],
@@ -678,7 +947,26 @@ var KitchenSession = class KitchenSession {
 			...batch.expectedRevision !== void 0 ? { expectedRevision: batch.expectedRevision } : {}
 		}) : null;
 		if (lone) {
-			if (!lone.ok) return failFrom(lone.error);
+			if (!lone.ok) {
+				const failed = failFrom(lone.error);
+				return {
+					...failed,
+					data: {
+						...failed.data,
+						planId: args.planId,
+						state: {
+							snapshot: plan.engine.snapshot(),
+							cookbook: plan.engine.cookbook()
+						}
+					}
+				};
+			}
+			if (!lone.replayed) try {
+				this.savePlan(args.planId, plan.engine);
+			} catch {
+				this.plans.delete(args.planId);
+				return fail("unavailable", "The plan could not be saved on this device.");
+			}
 			return {
 				data: {
 					ok: true,
@@ -686,7 +974,11 @@ var KitchenSession = class KitchenSession {
 					...lone.replayed ? { replayed: true } : {},
 					receipt: lone.receipt,
 					results: [lone.receipt],
-					snapshot: lone.snapshot
+					snapshot: lone.snapshot,
+					state: {
+						snapshot: plan.engine.snapshot(),
+						cookbook: plan.engine.cookbook()
+					}
 				},
 				text: `${lone.receipt.summary}\n${describeSnapshot(lone.snapshot)}`
 			};
@@ -699,11 +991,21 @@ var KitchenSession = class KitchenSession {
 					ok: false,
 					planId: args.planId,
 					error: result.error,
-					snapshot: current
+					snapshot: current,
+					state: {
+						snapshot: current,
+						cookbook: plan.engine.cookbook()
+					}
 				},
 				text: `Error ${result.error.code}: ${result.error.message}\nNothing was changed (revision ${current.revision}).`
 			};
 		}
+		if (!result.replayed) try {
+			this.savePlan(args.planId, plan.engine);
+		} catch {
+			this.plans.delete(args.planId);
+			return fail("unavailable", "The plan could not be saved on this device.");
+		}
 		return {
 			data: {
 				ok: true,
@@ -711,13 +1013,17 @@ var KitchenSession = class KitchenSession {
 				...result.replayed ? { replayed: true } : {},
 				receipt: result.receipt,
 				results: result.results.map((r) => r.receipt),
-				snapshot: result.snapshot
+				snapshot: result.snapshot,
+				state: {
+					snapshot: plan.engine.snapshot(),
+					cookbook: plan.engine.cookbook()
+				}
 			},
 			text: `${result.replayed ? "Already applied (same id): " : ""}${result.results.map((r) => r.receipt.summary).join("\n")}\n${describeSnapshot(result.snapshot)}`
 		};
 	}
 	async validatePlan(args) {
-		const plan = this.plan(args.planId);
+		const plan = await this.plan(args.planId);
 		if (!("engine" in plan)) return plan;
 		const { index } = await this.catalog();
 		const checked = plan.engine.run({ name: "validate" });
@@ -741,8 +1047,8 @@ var KitchenSession = class KitchenSession {
 			text: valid ? `Valid. Packages needed: ${report.packages.join(", ") || "none"}.` : `Not valid:\n${firstLines(errors.length ? errors : diagnostics.map((d) => `${d.path}: ${d.message}`), 12)}`
 		};
 	}
-	exportPlan(args) {
-		const plan = this.plan(args.planId);
+	async exportPlan(args) {
+		const plan = await this.plan(args.planId);
 		if (!("engine" in plan)) return plan;
 		const result = plan.engine.run({
 			name: "export_cookbook",
@@ -762,7 +1068,7 @@ var KitchenSession = class KitchenSession {
 		};
 	}
 	async applyPlan(args) {
-		const plan = this.plan(args.planId);
+		const plan = await this.plan(args.planId);
 		if (!("engine" in plan)) return plan;
 		const dir = args.dir;
 		if (!isAbsolute(dir)) return fail("invalid_input", "dir must be an absolute path.", { path: "dir" });
@@ -835,6 +1141,217 @@ var KitchenSession = class KitchenSession {
 	}
 };
 //#endregion
+//#region src/commands/kitchen/mcp/bridge.ts
+/** Minimal MCP Apps bridge, injected before the self-contained Planner bundle. */
+var KITCHEN_BRIDGE = `<script>
+(() => {
+  const pending = new Map();
+  const listeners = new Set();
+  let sequence = 0;
+  let latest;
+  let hostOrigin = '*';
+  let initialized = false;
+  function send(message) { window.parent.postMessage({ jsonrpc: '2.0', ...message }, hostOrigin); }
+  function request(method, params) {
+    return new Promise((resolve, reject) => {
+      const id = 'kitchen-' + ++sequence;
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error('The host did not answer. Refresh the plan before retrying.'));
+      }, 30000);
+      pending.set(id, { resolve, reject, timer });
+      send({ id, method, params });
+    });
+  }
+  // The Planner is an app shell that scrolls inside itself, so it asks for a
+  // stable frame instead of its content height: the host's fixed height wins,
+  // else its maxHeight, else a default. Fullscreen belongs to the host.
+  const DEFAULT_HEIGHT = 720;
+  let dimensions = {};
+  let displayMode = 'inline';
+  let reported;
+  function appHeight() {
+    if (displayMode === 'fullscreen' || typeof dimensions.height === 'number') return undefined;
+    const max = dimensions.maxHeight;
+    return typeof max === 'number' && max > 0 ? Math.round(max) : DEFAULT_HEIGHT;
+  }
+  function reportSize() {
+    const height = appHeight();
+    if (height === undefined || height === reported) return;
+    reported = height;
+    send({ method: 'ui/notifications/size-changed', params: { height } });
+  }
+  function applyHostContext(context) {
+    if (!context || typeof context !== 'object') return;
+    const next = context.containerDimensions;
+    if (next && typeof next === 'object') dimensions = next;
+    if (typeof context.displayMode === 'string') displayMode = context.displayMode;
+  }
+  function publish(data) {
+    if (!data || typeof data.planId !== 'string' || !data.state) return;
+    latest = data;
+    for (const listener of listeners) listener(data);
+  }
+  window.addEventListener('message', (event) => {
+    if (event.source !== window.parent) return;
+    if (hostOrigin !== '*' && event.origin !== hostOrigin) return;
+    const message = event.data;
+    if (!message || message.jsonrpc !== '2.0') return;
+    if (message.id !== undefined && pending.has(message.id)) {
+      if (event.origin && event.origin !== 'null') hostOrigin = event.origin;
+      const item = pending.get(message.id);
+      clearTimeout(item.timer);
+      pending.delete(message.id);
+      if (message.error) item.reject(new Error(message.error.message || 'Host request failed'));
+      else item.resolve(message.result);
+    } else if (message.method === 'ui/notifications/host-context-changed') {
+      applyHostContext(message.params);
+      if (initialized) reportSize();
+    } else if (message.method === 'ui/notifications/tool-result') {
+      publish(message.params?.structuredContent);
+    } else if (message.method === 'ping' && message.id !== undefined) {
+      send({ id: message.id, result: {} });
+    }
+  });
+  const ready = request('ui/initialize', {
+    appInfo: { name: 'smrt-kitchen-planner', version: '1.0.0' },
+    appCapabilities: { availableDisplayModes: ['inline', 'fullscreen'] },
+    protocolVersion: '2026-01-26',
+  }).then((result) => {
+    if (result?.protocolVersion !== '2026-01-26') throw new Error('Unsupported MCP Apps protocol');
+    send({ method: 'ui/notifications/initialized', params: {} });
+    applyHostContext(result.hostContext);
+    initialized = true;
+    reportSize();
+    return result;
+  });
+  ready.catch(() => {});
+  window.smrtKitchen = {
+    async callTool(name, args) {
+      if (!['get_plan', 'run_commands', 'export_plan', 'validate_plan', 'planner_ui_update'].includes(name)) {
+        throw new Error('This tool is not available from the Planner UI');
+      }
+      await ready;
+      const result = await request('tools/call', { name, arguments: args });
+      if (!result?.structuredContent) throw new Error('The host returned no structured data');
+      return result.structuredContent;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      if (latest) listener(latest);
+      return () => listeners.delete(listener);
+    },
+  };
+  ready.then(async () => {
+    const resumePlanId = window.__smrtKitchenReloadPlanId;
+    if (resumePlanId) {
+      try {
+        const result = await request('tools/call', {
+          name: 'get_plan', arguments: { planId: resumePlanId },
+        });
+        publish(result?.structuredContent);
+      } catch { /* A later render result can still supply the plan. */ }
+    }
+    let version = window.__smrtKitchenUiVersion;
+    if (!version) return;
+    let checking = false;
+    let stopped = false;
+    let reloadNotice;
+    function showReloadNotice() {
+      if (reloadNotice) return;
+      reloadNotice = document.createElement('p');
+      reloadNotice.setAttribute('role', 'alert');
+      reloadNotice.textContent = 'The new Planner UI could not reload. Reopen this app tab to use it.';
+      document.body.prepend(reloadNotice);
+    }
+    const check = async () => {
+      if (checking || stopped || document.visibilityState === 'hidden') return;
+      checking = true;
+      let attemptedVersion = false;
+      try {
+        const result = await request('tools/call', {
+          name: 'planner_ui_update',
+          arguments: { version, planId: latest?.planId || resumePlanId || '' },
+        });
+        const update = result?.structuredContent;
+        if (update?.changed && typeof update.html === 'string' && typeof update.version === 'string') {
+          // A rejected artifact must not be resent every poll. A later build
+          // has a different digest and can still replace it.
+          version = update.version;
+          attemptedVersion = true;
+          const next = new DOMParser().parseFromString(update.html, 'text/html');
+          const nextStyle = next.getElementById('smrt-planner-styles');
+          const nextEntry = next.getElementById('smrt-planner-entry');
+          const currentStyle = document.getElementById('smrt-planner-styles');
+          const currentEntry = document.getElementById('smrt-planner-entry');
+          if (!nextStyle || !nextEntry || !currentStyle || !currentEntry || !window.smrtKitchenUnmount) {
+            throw new Error('The Planner bundle cannot be reloaded in this tab');
+          }
+          await window.smrtKitchenUnmount();
+          const style = document.createElement('style');
+          style.id = 'smrt-planner-styles';
+          style.textContent = nextStyle.textContent;
+          currentStyle.replaceWith(style);
+          const entry = document.createElement('script');
+          entry.id = 'smrt-planner-entry';
+          entry.textContent = nextEntry.textContent;
+          currentEntry.replaceWith(entry);
+          reloadNotice?.remove();
+          reloadNotice = undefined;
+        }
+      } catch {
+        if (attemptedVersion) showReloadNotice();
+        // A build may be in progress; check again for a newer digest.
+      }
+      checking = false;
+    };
+    const timer = setInterval(check, 1500);
+    window.addEventListener('pagehide', () => {
+      stopped = true;
+      clearInterval(timer);
+    }, { once: true });
+  }).catch(() => {});
+})();
+<\/script>`;
+//#endregion
+//#region src/commands/kitchen/mcp/ui.ts
+/** Opt-in desktop capability probe. This is not the Planner UI. */
+var KITCHEN_UI_URI = "ui://smrt-kitchen/capability-v1.html";
+var KITCHEN_UI_CONTENT = {
+	uri: KITCHEN_UI_URI,
+	name: "SMRT Kitchen desktop capability check",
+	mimeType: "text/html;profile=mcp-app",
+	text: `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+${KITCHEN_BRIDGE}
+<title>SMRT Kitchen capability check</title></head>
+<body><main><h1>SMRT Kitchen</h1>
+<p>Local MCP App resource rendered.</p>
+<p>This capability check does not edit your plan. Continue using the Kitchen tools in chat.</p>
+</main></body></html>`,
+	_meta: { ui: {
+		prefersBorder: true,
+		csp: {
+			connectDomains: [],
+			resourceDomains: []
+		}
+	} }
+};
+/** Load only an operator-selected local artifact; tool arguments never choose files. */
+function loadPlannerUi(file, resumePlanId) {
+	const html = readFileSync(file, "utf8");
+	if (!/<head(?:\s[^>]*)?>/i.test(html)) throw new Error("Planner UI must be a complete self-contained HTML document");
+	const digest = createHash("sha256").update(html).digest("hex").slice(0, 16);
+	const bootstrap = `<script>window.__smrtKitchenUiVersion=${JSON.stringify(digest)};window.__smrtKitchenReloadPlanId=${JSON.stringify(resumePlanId ?? "").replace(/</g, "\\u003c")};<\/script>`;
+	const text = html.replace(/<head(?:\s[^>]*)?>/i, (head) => head + bootstrap + KITCHEN_BRIDGE);
+	return {
+		...KITCHEN_UI_CONTENT,
+		uri: `ui://smrt-kitchen/planner-${digest}.html`,
+		name: "SMRT Planner",
+		text
+	};
+}
+//#endregion
 //#region src/commands/kitchen/mcp/server.ts
 /**
 * `smrt kitchen mcp` (#3752): the Kitchen tools served over stdio. stdout
@@ -849,24 +1366,143 @@ var CATALOG_CACHE_HINT = {
 /** Build the MCP server; one {@link KitchenSession} (plans, catalog) per server. */
 function createKitchenMcpServer(options) {
 	const session = new KitchenSession(options);
+	let plannerUi;
+	if (options.plannerUi) try {
+		plannerUi = loadPlannerUi(options.plannerUi);
+	} catch {
+		console.error(`[${SERVER_NAME}] Planner UI is unavailable; planning tools remain active.`);
+	}
+	const resources = [...options.uiSmoke ? [KITCHEN_UI_CONTENT] : [], ...plannerUi ? [plannerUi] : []];
+	const getPlanTool = KITCHEN_TOOLS.find((tool) => tool.name === "get_plan");
+	if (!getPlanTool) throw new Error("Kitchen get_plan tool is missing");
 	const server = new Server({
 		name: SERVER_NAME,
 		version: cliVersion()
 	}, {
-		capabilities: { tools: {} },
+		capabilities: {
+			tools: {},
+			...resources.length ? { resources: {} } : {}
+		},
 		cacheHints: { "tools/list": CATALOG_CACHE_HINT }
 	});
-	server.setRequestHandler("tools/list", async () => ({ tools: KITCHEN_TOOLS.map((tool) => ({
-		name: tool.name,
-		title: tool.title,
-		description: tool.description,
-		inputSchema: tool.inputSchema,
-		outputSchema: tool.outputSchema,
-		annotations: tool.annotations
-	})) }));
+	server.setRequestHandler("tools/list", async () => ({ tools: [
+		...KITCHEN_TOOLS.map((tool) => ({
+			name: tool.name,
+			title: tool.title,
+			description: tool.description,
+			inputSchema: tool.inputSchema,
+			outputSchema: tool.outputSchema,
+			annotations: tool.annotations
+		})),
+		...plannerUi ? [{
+			name: "planner_ui_update",
+			title: "Check Planner UI build",
+			description: "Check whether the local Planner UI artifact has changed.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					version: { type: "string" },
+					planId: { type: "string" }
+				},
+				required: ["version"],
+				additionalProperties: false
+			},
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: false
+			},
+			_meta: { ui: { visibility: ["app"] } }
+		}, {
+			...getPlanTool,
+			inputSchema: getPlanTool.inputSchema,
+			outputSchema: getPlanTool.outputSchema,
+			name: "render_plan",
+			title: "Open the Planner",
+			description: "Open the interactive Planner for an existing plan. Call start_plan first, then pass its planId. Data tools keep working without the UI.",
+			_meta: {
+				ui: { resourceUri: plannerUi.uri },
+				"openai/ui": { entrypoints: [{ type: "thread" }] }
+			}
+		}] : [],
+		...options.uiSmoke ? [{
+			name: "kitchen_ui_smoke",
+			title: "Check local Kitchen UI",
+			description: "Render a static local MCP Apps capability check. Does not edit or display the Planner.",
+			inputSchema: {
+				type: "object",
+				properties: {},
+				additionalProperties: false
+			},
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: false
+			},
+			_meta: { ui: { resourceUri: KITCHEN_UI_URI } }
+		}] : []
+	] }));
+	if (resources.length) {
+		server.setRequestHandler("resources/list", async () => ({ resources: resources.map(({ uri, name, mimeType }) => ({
+			uri,
+			name,
+			mimeType
+		})) }));
+		server.setRequestHandler("resources/read", async (request) => {
+			const resource = resources.find((item) => item.uri === request.params.uri);
+			if (!resource) throw new Error(`Unknown Kitchen resource: ${request.params.uri}`);
+			return { contents: [resource] };
+		});
+	}
 	server.setRequestHandler("tools/call", async (request) => {
 		const { name, arguments: args } = request.params;
-		const result = await session.call(name, args ?? {});
+		if (plannerUi && options.plannerUi && name === "planner_ui_update") {
+			const version = typeof args?.version === "string" ? args.version : "";
+			const planId = typeof args?.planId === "string" ? args.planId : void 0;
+			let current;
+			try {
+				current = loadPlannerUi(options.plannerUi, planId);
+			} catch {
+				return {
+					content: [{
+						type: "text",
+						text: "Planner UI build is not ready."
+					}],
+					structuredContent: {
+						changed: false,
+						version,
+						error: {
+							code: "unavailable",
+							message: "Planner UI build is not ready."
+						}
+					}
+				};
+			}
+			const currentVersion = current.uri.slice(26, -5);
+			const changed = currentVersion !== version;
+			const data = changed ? {
+				changed,
+				version: currentVersion,
+				html: current.text
+			} : {
+				changed,
+				version: currentVersion
+			};
+			return {
+				content: [{
+					type: "text",
+					text: changed ? "Planner UI updated." : "Planner UI unchanged."
+				}],
+				structuredContent: data
+			};
+		}
+		if (options.uiSmoke && name === "kitchen_ui_smoke") return { content: [{
+			type: "text",
+			text: "Local MCP Apps capability check. Confirm whether the host displays the SMRT Kitchen card."
+		}] };
+		const result = await session.call(plannerUi && name === "render_plan" ? "get_plan" : name, args ?? {});
 		return {
 			content: [{
 				type: "text",
@@ -883,10 +1519,17 @@ function createKitchenMcpServer(options) {
 }
 /** Serve on this process's stdio until the host closes it or the process is stopped. */
 async function runKitchenMcp(options) {
-	const handle = serveStdio(() => createKitchenMcpServer(options).server, { onerror: (error) => console.error(`[${SERVER_NAME}] ${error.message}`) });
+	const { server, session } = createKitchenMcpServer(options);
+	const preview = options.previewPort !== void 0 ? await startKitchenPreview(session, options.previewPort, options.previewOrigin ?? "") : void 0;
+	session.previewUrl = preview?.url;
+	if (preview) console.error(`[${SERVER_NAME}] Live preview bridge: ${preview.url}`);
+	const handle = serveStdio(() => server, { onerror: (error) => console.error(`[${SERVER_NAME}] ${error.message}`) });
 	await new Promise((resolve) => {
 		const done = () => {
-			handle.close().finally(resolve);
+			handle.close().finally(() => {
+				preview?.server.close();
+				resolve();
+			});
 		};
 		process.once("SIGINT", done);
 		process.once("SIGTERM", done);