pi-revit 0.3.1 → 0.5.0

package/extensions/pi-revit/index.ts

@@ -1,21 +1,26 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type, type TSchema } from "typebox";
+import { readFileSync } from "node:fs";
 import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { version as packageVersion } from "../../package.json";
-
-interface BridgeInfo {
-	baseUrl: string;
-	token: string;
-	pid?: number;
-	revitVersion?: string;
-}
+import { createToolCatalog, type BridgeToolDescriptor } from "./tool-catalog.js";
+import { createInstanceRouter, type BridgeInfo } from "./instance-router.js";
+import { registerScriptLibrary } from "./script-library.js";
+import { documentationRevision, documentedTools, manualDirectory, skillRoot } from "./tool-documentation.js";
+import { publicBridgeSchema } from "./tool-schema.js";
+import { packagedContracts } from "./contracts.js";
+import { buildPlatformSection, hoistSharedGuidelines } from "./platform-prompt.js";
+import { createCompletionMonitor } from "./completion-monitor.js";
+import { changedModel, createScopeMonitor } from "./scope-monitor.js";
+
+type BridgeResolver = (operationId?: string) => Promise<BridgeInfo>;
 
 interface ContentBlock {
-	type: string;
+	type: "text";
 	text: string;
 }
 
@@ -30,21 +35,6 @@ interface BridgeToolResponse {
 	hasActiveDocument?: boolean;
 }
 
-/** One entry of GET /tools, as served by ToolRegistry.Describe() on the bridge. */
-interface BridgeToolDescriptor {
-	name: string;
-	label?: string;
-	description?: string;
-	category?: string;
-	tier?: string;
-	parameters?: unknown;
-	executionMode?: string;
-	write?: boolean;
-	requiresDocument?: boolean;
-	promptSnippet?: string | null;
-	promptGuidelines?: string[] | null;
-}
-
 const DEFAULT_TIMEOUT_MS = 30_000;
 const LONG_TIMEOUT_MS = 120_000;
 const DISCOVERY_TIMEOUT_MS = 10_000;
@@ -113,11 +103,11 @@ function timeoutError(timeoutMs: number): Error {
 
 export async function bridgeRequest(
 	pathname: string,
-	init: { method: "GET" | "POST"; body?: string; query?: Record<string, string> },
+	init: { method: "GET" | "POST"; body?: string; query?: Record<string, string>; bridge?: BridgeInfo },
 	signal?: AbortSignal,
 	timeoutMs = DEFAULT_TIMEOUT_MS,
 ): Promise<unknown> {
-	const info = await readBridgeInfo();
+	const info = init.bridge ?? await readBridgeInfo();
 	const query = new URLSearchParams({ ...(init.query ?? {}), token: info.token });
 	const url = `${info.baseUrl}${pathname}?${query.toString()}`;
 
@@ -243,33 +233,82 @@ function registerResultReader(pi: ExtensionAPI) {
 	});
 }
 
-async function runBridgeTool(name: string, args: unknown, signal: AbortSignal | undefined, timeoutMs: number) {
-	const payload = (await bridgeRequest(
-		`/tools/${encodeURIComponent(name)}/execute`,
-		{
-			method: "POST",
-			body: JSON.stringify(args ?? {}),
-			query: { timeout_ms: String(timeoutMs) },
+async function runBridgeTool(name: string, args: unknown, signal: AbortSignal | undefined, timeoutMs: number, resolve: BridgeResolver,
+	prepared?: (receipt: { operation_id: string; bridge_id: string }) => Promise<void>) {
+	const body = { ...(args as Record<string, unknown> ?? {}) };
+	const retryId = body._operation_id;
+	delete body._operation_id;
+	if (retryId !== undefined && (typeof retryId !== "string" || !retryId)) throw new Error("_operation_id must be the exact ID of a previous request.");
+	const info = await resolve(retryId as string | undefined);
+	if (retryId && (!info.supportsOperationTracking || !info.bridgeId)) throw new Error("This bridge does not support operation receipts; the request was not sent.");
+	const operationId = info.supportsOperationTracking && info.bridgeId ? (retryId as string | undefined) ?? `${info.bridgeId}:${randomUUID()}` : undefined;
+	if (operationId && !operationId.startsWith(`${info.bridgeId}:`)) throw new Error("This operation belongs to a different bridge session. Its outcome is unknown here; it was not replayed.");
+	if (prepared && (!operationId || !info.bridgeId)) throw new Error("Script library runs require a bridge with operation receipts. The script was not sent.");
+	try {
+		if (prepared) await prepared({ operation_id: operationId!, bridge_id: info.bridgeId! });
+		const payload = (await bridgeRequest(
+			`/tools/${encodeURIComponent(name)}/execute`,
+			{ method: "POST", body: JSON.stringify(body), bridge: info,
+				query: { timeout_ms: String(timeoutMs), ...(operationId ? { operation_id: operationId } : {}) } },
+			signal, timeoutMs,
+		)) as BridgeToolResponse;
+		const content = await modelContent(name, payload);
+		if (operationId) content.push({ type: "text", text: `Operation ID: ${operationId}. Check get_revit_operation after a timeout; retrying with this exact _operation_id and identical arguments will not repeat the action.` });
+		return { content, details: operationId ? { ...(payload.details as object ?? {}), operation_id: operationId, bridge_id: info.bridgeId } : payload.details };
+	} catch (error) {
+		if (!operationId) throw error;
+		throw new Error(`${error instanceof Error ? error.message : String(error)}\nOperation ID: ${operationId}. Use get_revit_operation to inspect its outcome. Do not retry an edit with a new ID until its effects are known.`);
+	}
+}
+
+function registerOperationReader(pi: ExtensionAPI, resolve: BridgeResolver) {
+	pi.registerTool({
+		name: "get_revit_operation",
+		label: "Get Revit Operation",
+		description: "Read an operation receipt without waiting for Revit's model thread. Reports queued, running, succeeded, failed, expired_before_start, result_unavailable or unknown, with the original result when retained. Unknown after restart is not proof that the edit never ran. Full results are bounded to the latest 128 receipts / 32 MiB; IDs remain reserved for up to 10,000 operations per bridge session so expired results never cause re-execution.",
+		promptSnippet: "Check the outcome of a timed-out Revit operation before retrying an edit.",
+		parameters: Type.Object({ operation_id: Type.String({ minLength: 1, maxLength: 120 }) }),
+		executionMode: "sequential",
+		async execute(_id, args, signal) {
+			const bridge = await resolve(args.operation_id);
+			const result = await bridgeRequest(`/operations/${encodeURIComponent(args.operation_id)}`, { method: "GET", bridge }, signal, 10_000);
+			return { content: await modelContent("get_revit_operation", { details: { payload: result } }), details: result };
 		},
-		signal,
-		timeoutMs,
-	)) as BridgeToolResponse;
+	});
+}
 
-	return { content: await modelContent(name, payload), details: payload.details };
+interface RequestMonitors { completion: ReturnType<typeof createCompletionMonitor>; scope: ReturnType<typeof createScopeMonitor> }
+
+/** The bridge value of a tool result (details.payload for current and older bridges). */
+function resultPayload(details: unknown): unknown {
+	return details !== null && typeof details === "object" && Object.hasOwn(details, "payload") ? (details as { payload: unknown }).payload : details;
 }
 
-function registerBridgeTool(pi: ExtensionAPI, descriptor: BridgeToolDescriptor) {
+/** Notes the request monitors add to a result: scope first (it can require asking the user), then completion. */
+function monitorNotes(monitors: RequestMonitors | undefined, tool: string, params: unknown, meta: { write?: boolean; effects?: string[] | null }, details: unknown): string[] {
+	if (!monitors) return [];
+	const payload = resultPayload(details);
+	return [monitors.scope.afterResult(payload), monitors.completion.afterCall(tool, params, meta, changedModel(payload))].filter((note): note is string => !!note);
+}
+
+/** `guidelines` are this tool's own rules; rules shared by several tools live once in the platform section. */
+function registerBridgeTool(pi: ExtensionAPI, descriptor: BridgeToolDescriptor, resolve: BridgeResolver, guidelines: string[],
+	monitors?: RequestMonitors) {
 	const timeoutMs = toolTimeoutMs(descriptor.name);
+	const schema = publicBridgeSchema(descriptor.parameters);
 	pi.registerTool({
 		name: descriptor.name,
 		label: descriptor.label ?? descriptor.name,
 		description: descriptor.description ?? `Revit bridge tool '${descriptor.name}'.`,
-		parameters: Type.Unsafe((descriptor.parameters ?? { type: "object", properties: {} }) as TSchema),
+		parameters: Type.Unsafe(schema as TSchema),
 		promptSnippet: descriptor.promptSnippet ?? undefined,
-		promptGuidelines: descriptor.promptGuidelines ?? undefined,
+		promptGuidelines: guidelines,
 		executionMode: descriptor.executionMode === "parallel" ? "parallel" : "sequential",
 		async execute(_toolCallId, params, signal) {
-			return runBridgeTool(descriptor.name, params, signal, timeoutMs);
+			const result = await runBridgeTool(descriptor.name, params, signal, timeoutMs, resolve);
+			// Result- and metadata-driven steering: objects that predate the request, and repeated re-verification after edits.
+			const notes = monitorNotes(monitors, descriptor.name, params, descriptor, result.details);
+			return notes.length ? { ...result, content: [...result.content, ...notes.map(text => ({ type: "text" as const, text }))] } : result;
 		},
 	});
 }
@@ -352,17 +391,51 @@ async function announceUpdateOnce(notify: (message: string, level: "info") => vo
 	}
 }
 
-function registerPing(pi: ExtensionAPI, onBridgeAlive?: () => Promise<"ready" | "registered" | "failed">) {
+const packageRoot = fileURLToPath(new URL("../../", import.meta.url));
+const nativeToolNames = new Set(documentedTools.filter(tool => tool.source === "native").map(tool => tool.name));
+
+/** Branch and commit when the extension runs from a source checkout; null for an installed package. */
+function sourceRevision(): { branch: string | null; commit: string | null } | null {
+	try {
+		const gitDir = path.join(packageRoot, ".git");
+		const head = readFileSync(path.join(gitDir, "HEAD"), "utf8").trim();
+		if (!head.startsWith("ref: ")) return { branch: null, commit: head };
+		const ref = head.slice(5);
+		let commit: string | null = null;
+		try { commit = readFileSync(path.join(gitDir, ref), "utf8").trim(); }
+		catch { commit = readFileSync(path.join(gitDir, "packed-refs"), "utf8").split(/\r?\n/).find(line => line.endsWith(` ${ref}`))?.split(" ")[0] ?? null; }
+		return { branch: ref.replace(/^refs\/heads\//, ""), commit };
+	} catch { return null; }
+}
+
+/** What is actually loaded: package, guidance revision, source revision and per-tool contract agreement. */
+function loadedStatus(live: Map<string, string>) {
+	const matching: string[] = [], changed: string[] = [], undocumented: string[] = [];
+	for (const [name, hash] of live) {
+		const packaged = packagedContracts.get(name);
+		if (!packaged) undocumented.push(name);
+		else if (packaged.contract_hash === hash) matching.push(name);
+		else changed.push(name);
+	}
+	return {
+		extension_package: packageVersion, extension_root: packageRoot, documentation_revision: documentationRevision, source: sourceRevision(),
+		contracts: live.size ? { matching: matching.length, changed, undocumented,
+			packaged_not_advertised: [...packagedContracts.values()].filter(tool => tool.source === "bridge" && !live.has(tool.name)).map(tool => tool.name) }
+			: "no bridge catalogue discovered yet",
+	};
+}
+
+function registerPing(pi: ExtensionAPI, resolve: BridgeResolver, onBridgeAlive?: () => Promise<"ready" | "registered" | "failed">, status?: () => unknown) {
 	pi.registerTool({
 		name: "ping",
 		label: "Ping Revit Bridge",
-		description: "Check that the Revit bridge is reachable and report the Revit version.",
+		description: "Check that the Revit bridge is reachable and report the Revit version, plus which PI-Revit extension package, guidance revision, source revision and tool contracts are loaded (changed or undocumented contracts mean manuals may not match the bridge).",
 		parameters: Type.Object({}),
 		promptSnippet: "Check Revit bridge availability.",
-		promptGuidelines: ["Use ping when Revit tools fail or bridge availability is unclear."],
+		promptGuidelines: ["Use ping when Revit tools fail or bridge availability is unclear; it also reports which PI-Revit package, guidance revision and contracts are loaded."],
 		executionMode: "sequential",
 		async execute(_toolCallId, _params, signal) {
-			const payload = await bridgeRequest("/ping", { method: "GET" }, signal, 10_000);
+			const payload = await bridgeRequest("/ping", { method: "GET", bridge: await resolve() }, signal, 10_000);
 			const warning = versionMismatch((payload as { addinVersion?: string }).addinVersion);
 			// The bridge is alive: if this session started before Revit and only has
 			// ping, register the bridge tools now and tell the model they arrived.
@@ -374,9 +447,11 @@ function registerPing(pi: ExtensionAPI, onBridgeAlive?: () => Promise<"ready" |
 				else if (state === "failed")
 					registrationNote = "\nNOTE: Bridge tool discovery failed even though ping succeeded; retry ping or restart pi.";
 			}
+			const loaded = status?.();
 			return {
-				content: [{ type: "text", text: JSON.stringify(payload) + (warning ? `\nWARNING: ${warning}` : "") + registrationNote }],
-				details: payload,
+				content: [{ type: "text", text: JSON.stringify(payload) + (warning ? `\nWARNING: ${warning}` : "") + registrationNote
+					+ (loaded ? `\nPI-Revit loaded: ${JSON.stringify(loaded)}` : "") }],
+				details: loaded ? { ...(payload as object), pi_revit: loaded } : payload,
 			};
 		},
 	});
@@ -385,35 +460,92 @@ function registerPing(pi: ExtensionAPI, onBridgeAlive?: () => Promise<"ready" |
 const REDISCOVERY_INTERVAL_MS = 15_000;
 
 export default async function revitConnector(pi: ExtensionAPI) {
+	const bridgeVersions = new Map<string, string | null>();
+	const bridgeKey = (info: BridgeInfo) => info.bridgeId ?? `${info.baseUrl}\0${info.token}`;
+	const instances = createInstanceRouter(readBridgeInfo, async info => {
+		const payload = await bridgeRequest("/ping", { method: "GET", bridge: info }, undefined, 2000) as Record<string, unknown>;
+		bridgeVersions.set(bridgeKey(info), typeof payload.addinVersion === "string" ? payload.addinVersion : null);
+		return payload;
+	});
 	registerResultReader(pi);
+	registerOperationReader(pi, instances.resolve);
+	const monitors: RequestMonitors = { completion: createCompletionMonitor(), scope: createScopeMonitor() };
+	registerScriptLibrary(pi, async (args, signal, prepared) => {
+		const result = await runBridgeTool("execute_csharp", args, signal, LONG_TIMEOUT_MS, instances.resolve, prepared);
+		const notes = monitorNotes(monitors, "manage_revit_scripts", args, { write: true }, result.details);
+		return notes.length ? { ...result, content: [...result.content, ...notes.map(text => ({ type: "text" as const, text }))] } : result;
+	},
+		async value => ({ content: await modelContent("manage_revit_scripts", { details: { payload: value } }), details: value }));
+	pi.registerTool({
+		name: "manage_revit_instances", label: "Manage Revit Instances",
+		description: "List reachable local Revit bridge sessions or select one for this Pi session. The first sole instance is bound automatically; multiple instances require explicit selection before model calls. After that session closes or restarts, select its new bridge_id: calls never fall back to another session. Selection refreshes the tool catalogue. Operation receipt lookups and identical retries use their original session. Read get_model_overview again after switching; document IDs are session-specific.",
+		parameters: Type.Object({ action: Type.Optional(Type.Union([Type.Literal("list"), Type.Literal("select")])), bridge_id: Type.Optional(Type.String()) }),
+		executionMode: "sequential",
+		async execute(_id, args) {
+			let result: unknown;
+			if ((args.action ?? "list") === "list") result = { instances: await instances.list() };
+			else if (args.action === "select" && args.bridge_id) {
+				// Drain discovery for the previous target before changing selection.
+				if (discoveryInFlight) await discoveryInFlight;
+				const selection = await instances.select(args.bridge_id);
+				// A retry timer may have started another discovery while selection probed.
+				// Drain that request too, then reset synchronously before fetching anew.
+				if (discoveryInFlight) await discoveryInFlight;
+				bridgeToolsRegistered = false;
+				catalog.reset();
+				const ready = await discoverAndRegister();
+				result = { ...selection, tool_catalog_ready: ready };
+				if (!ready && sessionActive) startRetry();
+			} else throw new Error("select requires bridge_id from the instance list.");
+			return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
+		},
+	});
 	// Self-healing discovery: when pi starts before Revit is ready, the initial
-	// GET /tools fails and only ping is registered. Rather than requiring a
+	// GET /tools fails and only native utilities are registered. Rather than requiring a
 	// fresh pi start (/reload does not reliably re-run async registration), a
 	// background retry keeps probing until the bridge appears, and a successful
 	// ping also triggers an immediate attempt.
 	let bridgeToolsRegistered = false;
+	let sharedRules: string[] = [];
 	let discoveryInFlight: Promise<boolean> | null = null;
+	let sessionActive = false;
+	let disposed = false;
+	let timer: ReturnType<typeof setInterval> | undefined;
+	const catalog = createToolCatalog(pi, discoverAndRegister);
 
 	async function discoverAndRegister(): Promise<boolean> {
+		if (disposed) return false;
 		if (bridgeToolsRegistered) return true;
 		if (discoveryInFlight) return discoveryInFlight;
 		discoveryInFlight = (async () => {
 			try {
-				const payload = (await bridgeRequest("/tools", { method: "GET" }, undefined, DISCOVERY_TIMEOUT_MS)) as {
+				const selectedBridge = await instances.resolve();
+				const payload = (await bridgeRequest("/tools", { method: "GET", bridge: selectedBridge }, undefined, DISCOVERY_TIMEOUT_MS)) as {
 					tools?: BridgeToolDescriptor[];
 				};
 				const descriptors = Array.isArray(payload?.tools) ? payload.tools : [];
-				if (descriptors.length === 0) return false;
-				for (const descriptor of descriptors) {
-					if (!descriptor || typeof descriptor.name !== "string" || !descriptor.name) continue;
-					if (descriptor.name === "ping" || descriptor.name === "read_revit_result") continue;
-					registerBridgeTool(pi, descriptor);
+				if (disposed || !Array.isArray(payload?.tools)) return false;
+				catalog.setBridgeVersion(bridgeVersions.get(bridgeKey(selectedBridge)) ?? null);
+				// Native tool names are reserved: a bridge cannot replace an extension utility.
+				const valid = descriptors.filter(descriptor => descriptor && typeof descriptor.name === "string" && descriptor.name
+					&& !nativeToolNames.has(descriptor.name));
+				const { shared, perTool } = hoistSharedGuidelines(valid);
+				sharedRules = shared;
+				const added: string[] = [];
+				for (const descriptor of valid) {
+					registerBridgeTool(pi, descriptor, instances.resolve, perTool.get(descriptor.name) ?? [], monitors);
+					catalog.add(descriptor);
+					added.push(descriptor.name);
+				}
+				if (sessionActive) {
+					catalog.hideAdvanced(added);
+					pi.setActiveTools([...new Set([...pi.getActiveTools(), ...descriptors.filter(d => added.includes(d.name) && d.tier !== "advanced").map(d => d.name)])]);
 				}
 				bridgeToolsRegistered = true;
 				return true;
 			} catch {
 				// Bridge down (Revit closed, still starting, stale bridge.json):
-				// stay on ping only and try again later.
+				// keep native utilities available and try again later.
 				return false;
 			} finally {
 				discoveryInFlight = null;
@@ -426,18 +558,30 @@ export default async function revitConnector(pi: ExtensionAPI) {
 	// bridge is down, so it is never part of /tools discovery. A successful
 	// ping doubles as a re-discovery trigger — the natural first call in a
 	// session that finds itself without bridge tools.
-	registerPing(pi, async () => {
+	registerPing(pi, instances.resolve, async () => {
 		if (bridgeToolsRegistered) return "ready";
 		return (await discoverAndRegister()) ? "registered" : "failed";
+	}, () => loadedStatus(catalog.liveContracts()));
+
+	// One always-visible platform section per run: global protocols plus rules shared
+	// by several tools. It does not depend on the skill being read or on tool count.
+	pi.on("before_agent_start", async event => {
+		monitors.completion.reset();
+		monitors.scope.reset((event as { prompt?: string }).prompt ?? "");
+		const options = (event as { systemPromptOptions?: { sections?: Record<string, string> } }).systemPromptOptions;
+		if (options?.sections) options.sections.pi_revit = buildPlatformSection({ manualDirectory, skillRoot, sharedRules });
 	});
 
 	// Surface an incomplete update (see versionMismatch) once per session, right
 	// where the user lands after running `pi update --extensions`. Bridge down at
 	// session start is the normal Revit-closed case: stay quiet.
 	pi.on("session_start", async (_event, ctx) => {
+		sessionActive = true;
+		catalog.hideAdvanced();
+		if (!bridgeToolsRegistered) startRetry();
 		await announceUpdateOnce((message, level) => ctx.ui.notify(message, level));
 		try {
-			const payload = (await bridgeRequest("/ping", { method: "GET" }, undefined, 3_000)) as { addinVersion?: string };
+			const payload = (await bridgeRequest("/ping", { method: "GET", bridge: await instances.resolve() }, undefined, 3_000)) as { addinVersion?: string };
 			const warning = versionMismatch(payload.addinVersion);
 			if (warning) ctx.ui.notify(warning, "warning");
 		} catch {
@@ -445,33 +589,35 @@ export default async function revitConnector(pi: ExtensionAPI) {
 		}
 	});
 
-	if (await discoverAndRegister()) return;
-
-	// Never block pi startup on Revit: keep retrying quietly in the background
-	// and stop the moment discovery succeeds.
-	const timer = setInterval(async () => {
-		if (!(await discoverAndRegister())) return;
-		clearInterval(timer);
-		// The ping path announces newly registered tools in its result text; this path
-		// must speak too. Without it the tools appear silently in the next system
-		// prompt while nothing in the conversation contradicts an earlier "Revit is
-		// not running" — the session's belief goes stale. Custom messages participate
-		// in LLM context; deliverAs "nextTurn" queues it for the next user prompt
-		// without interrupting or triggering anything.
-		try {
-			pi.sendMessage(
-				{
-					customType: "pi-revit",
-					content:
-						"Revit is now reachable: the Revit bridge tools (get_elements, set_parameters, execute_csharp, ...) were just registered in this session and are available from now on.",
-					display: true,
-				},
-				{ deliverAs: "nextTurn" },
-			);
-		} catch {
-			// An older pi without sendMessage, or a torn-down session: the
-			// registration itself succeeded and must never be undone by the announcer.
-		}
-	}, REDISCOVERY_INTERVAL_MS);
-	timer.unref?.();
+	pi.on("session_shutdown", async () => {
+		disposed = true;
+		sessionActive = false;
+		if (timer) clearInterval(timer);
+		timer = undefined;
+	});
+
+	function startRetry() {
+		if (timer || disposed) return;
+		timer = setInterval(async () => {
+			if (!(await discoverAndRegister())) return;
+			if (timer) clearInterval(timer);
+			timer = undefined;
+			if (disposed) return;
+			// Refresh the model's knowledge on its next turn without interrupting the user.
+			try {
+				pi.sendMessage(
+					{
+						customType: "pi-revit",
+						content: "Revit is now reachable. Core bridge tools are available; use find_revit_tools to activate specialist tools.",
+						display: true,
+					},
+					{ deliverAs: "nextTurn" },
+				);
+			} catch {
+				// Tool registration remains valid if the session cannot accept a message.
+			}
+		}, REDISCOVERY_INTERVAL_MS);
+		timer.unref?.();
+	}
+	await discoverAndRegister();
 }

package/extensions/pi-revit/instance-router.ts

@@ -0,0 +1,86 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { createHash } from "node:crypto";
+
+export interface BridgeInfo {
+    baseUrl: string;
+    token: string;
+    pid?: number;
+    revitVersion?: string;
+    bridgeId?: string;
+    supportsOperationTracking?: boolean;
+}
+
+/** Selection belongs to one extension instance. A selected session never silently falls back. */
+export function createInstanceRouter(readLegacy: () => Promise<BridgeInfo>, probe: (info: BridgeInfo) => Promise<Record<string, unknown>>) {
+    let selected: string | undefined;
+    // Older bridges have no generation ID. Derive a stable opaque selector from
+    // their per-start credentials without exposing the credential itself.
+    const identity = (info: BridgeInfo) => info.bridgeId ?? createHash("sha256").update(info.baseUrl + "\0" + info.token).digest("hex").slice(0, 32);
+    const directory = () => path.join(process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming"), "RevitBridge", "instances");
+    async function candidates(): Promise<BridgeInfo[]> {
+        const entries = new Map<string, BridgeInfo>();
+        let files: string[] = [];
+        try { files = (await readdir(directory())).filter(name => /^[0-9a-f]{32}\.json$/.test(name)); } catch { }
+        // Old crash records may accumulate; probe only records whose process still exists.
+        for (const file of files) {
+            try {
+                const info = JSON.parse(await readFile(path.join(directory(), file), "utf8")) as BridgeInfo;
+                if (info.bridgeId !== file.slice(0, -5) || !info.baseUrl || !info.token || !Number.isSafeInteger(info.pid)) continue;
+                try { process.kill(info.pid!, 0); } catch { continue; }
+                entries.set(info.bridgeId, info);
+            } catch { }
+        }
+        try {
+            const legacy = await readLegacy();
+            entries.set(identity(legacy), legacy);
+        } catch { }
+        return [...entries.values()];
+    }
+    async function live() {
+        const found = await Promise.all((await candidates()).map(async info => {
+            try {
+                const ping = await probe(info);
+                if (info.bridgeId && ping.bridgeId !== info.bridgeId) return null;
+                return { info, ping };
+            } catch { return null; }
+        }));
+        return found.filter((entry): entry is NonNullable<typeof entry> => entry !== null);
+    }
+    async function resolve(operationId?: string): Promise<BridgeInfo> {
+        const target = operationId?.split(":")[0] ?? selected;
+        if (target) {
+            const info = (await candidates()).find(entry => identity(entry) === target);
+            if (!info) throw new Error("The original or selected Revit bridge session is unavailable. Its outcome is unknown here; no action was sent to another instance. Use manage_revit_instances to select an available session.");
+            return info;
+        }
+        const entries = await candidates();
+        // Bind only a verified live session; a crash record must not prevent
+        // startup discovery from recovering when Revit is launched later.
+        if (entries.length === 1) {
+            const ping = await probe(entries[0]);
+            if (entries[0].bridgeId && ping.bridgeId !== entries[0].bridgeId)
+                throw new Error("Revit discovery points to a different bridge generation. Refresh the instance list.");
+            selected = identity(entries[0]); return entries[0];
+        }
+        const available = await live();
+        if (available.length > 1) throw new Error("Several Revit instances are open. Use manage_revit_instances to list and select the intended bridge_id before calling model tools.");
+        if (available.length === 1) { selected = identity(available[0].info); return available[0].info; }
+        return readLegacy();
+    }
+    async function list() {
+        return (await live()).map(({ info, ping }) => ({ bridge_id: identity(info), pid: info.pid ?? null,
+            revit_version: info.revitVersion ?? null, addin_version: ping.addinVersion ?? null,
+            selected: selected === identity(info), supports_operation_tracking: info.supportsOperationTracking === true }));
+    }
+    async function select(id: string) {
+        if (!/^[0-9a-f]{32}$/.test(id)) throw new Error("bridge_id must be an exact session ID from manage_revit_instances.");
+        const match = (await live()).find(entry => identity(entry.info) === id);
+        if (!match) throw new Error("That bridge session is no longer reachable; selection was unchanged.");
+        selected = id;
+        return { bridge_id: id, pid: match.info.pid, addin_version: match.ping.addinVersion,
+            instructions: "Selection applies to this Pi extension session. Read get_model_overview for a fresh exact document identity before editing. Operation receipts and identical retries are routed to their original bridge session." };
+    }
+    return { resolve, list, select };
+}

package/extensions/pi-revit/platform-prompt.ts

@@ -0,0 +1,40 @@
+import path from "node:path";
+
+/**
+ * The PI-Revit platform section: cross-cutting protocols stated exactly once, always in
+ * context (injected through before_agent_start), independent of whether the skill is read
+ * and of how many tools exist. Tool-specific facts stay in each tool's own guidelines.
+ */
+export const PLATFORM_PROTOCOL = [
+	"PI-Revit protocol. It applies to every Revit tool, present or future, whether or not the pi-revit skill has been read.",
+	"1. Capability: before saying PI-Revit can or cannot do something, check. find_revit_tools (scope=documentation also works while Revit is closed) returns matching tools, their declared limits with alternatives, and related workflows. If a tool does not cover the request, follow its declared alternative. If nothing dedicated fits, verify all needed API members with search_api_docs, up to 10 names per call separated by ';' and use execute_csharp within the requested scope. Say an operation is not possible only after that check, and name what you checked; distinguish \"no dedicated tool\", \"the Revit API does not offer it\" and \"needs the user\".",
+	"2. Scope and completion: explanations do not change the model and inspections do not repair it. For a change, list the request's explicit requirements, do only those, and verify each with the tool's declared verification method. Then stop and report what changed, how it was verified and anything unmet. Offer further improvements as suggestions instead of making them. Never hide or remove content the request asks to show. An object made from an existing one inherits its state: results report it as inherited_state, and model_changes lists what each call added, modified or deleted, with the visibility of new views. Check that state against the request and say what you derived from.",
+	"3. Existing objects: objects that existed before the request are not yours. If one already has a name the request asks you to create, or a creation is rejected as a name collision, do not edit, reuse, replace or delete it: ask the user, or use a distinct name and report the collision.",
+	"4. Evidence: base claims about capabilities and model state on tool results, manuals or API documentation checked in this session, and say which.",
+	"5. Identity: for model changes, previews, exports, view activation and selection changes, pass project.documentId from get_model_overview unchanged as expected_document_id; project.documentKind says whether it is a project or a family, and tools refuse kinds they do not declare. Refresh it after reopening, restarting or switching instances. Save As keeps the ID but changes which file a later save affects.",
+	"6. Language: the user may write in any language, and the model's Revit UI may be localized. Reply in the user's language. Search tools and API documentation with English terms. Read localized category and parameter names from tool results, and prefer exact identities (BuiltInParameter names, guid:<GUID>) over translated display names.",
+];
+
+export function buildPlatformSection(options: { manualDirectory: string; skillRoot: string; sharedRules: readonly string[] }): string {
+	const lines = [
+		...PLATFORM_PROTOCOL,
+		`7. Guidance: each tool's manual is ${path.join(options.manualDirectory, "<tool_name>.md")}; read only the manual of a tool you will use. find_revit_tools returns exact paths and whether a manual matches the selected bridge's contract. Shared rules: ${path.join(options.skillRoot, "references", "execution-rules.md")}. Uncertain outcomes: ${path.join(options.skillRoot, "references", "operation-recovery.md")}.`,
+	];
+	if (options.sharedRules.length) lines.push("Rules shared by several Revit tools:", ...options.sharedRules.map(rule => `- ${rule}`));
+	return lines.join("\n");
+}
+
+/**
+ * Split bridge guidelines into per-tool rules and rules shared by two or more tools.
+ * A tool's own name is normalized away first, so "set_parameters: use X" and
+ * "open_view: use X" are recognized as one shared rule. Works for any bridge version.
+ */
+export function hoistSharedGuidelines(descriptors: readonly { name: string; promptGuidelines?: string[] | null }[]) {
+	const normalized = (name: string, rule: string) => rule.split(name).join("{tool}").replace(/^\{tool\}:\s*/, "").trim();
+	const counts = new Map<string, number>();
+	for (const d of descriptors) for (const rule of new Set((d.promptGuidelines ?? []).map(r => normalized(d.name, r)))) counts.set(rule, (counts.get(rule) ?? 0) + 1);
+	const shared = [...counts].filter(([, count]) => count >= 2).map(([rule]) => rule);
+	const sharedSet = new Set(shared);
+	const perTool = new Map(descriptors.map(d => [d.name, (d.promptGuidelines ?? []).filter(rule => !sharedSet.has(normalized(d.name, rule)))]));
+	return { shared: shared.map(rule => rule.replaceAll("{tool}", "the tool")), perTool };
+}