pi-revit 0.3.1 → 0.4.0

package/extensions/pi-revit/index.ts

@@ -1,21 +1,19 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type, type TSchema } from "typebox";
-import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
+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";
+import { version as packageVersion } from "../../package.json";
+import { createToolCatalog, type BridgeToolDescriptor } from "./tool-catalog.js";
+import { createInstanceRouter, type BridgeInfo } from "./instance-router.js";
+import { registerScriptLibrary } from "./script-library.js";
 
-interface BridgeInfo {
-	baseUrl: string;
-	token: string;
-	pid?: number;
-	revitVersion?: string;
-}
+type BridgeResolver = (operationId?: string) => Promise<BridgeInfo>;
 
-interface ContentBlock {
-	type: string;
+interface ContentBlock {
+	type: "text";
 	text: string;
 }
 
@@ -30,31 +28,16 @@ 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;
-const MAX_MODEL_CONTENT_CHARS = 12_000;
-const MAX_RESULT_PAGE_CHARS = 8_000;
-
-// IDs only resolve results created by this extension instance. A caller cannot
-// turn read_revit_result into an arbitrary filesystem read by supplying a path.
-const savedResults = new Map<string, string>();
-let resultDirectory: Promise<string> | undefined;
+const MAX_MODEL_CONTENT_CHARS = 12_000;
+const MAX_RESULT_PAGE_CHARS = 8_000;
+
+// IDs only resolve results created by this extension instance. A caller cannot
+// turn read_revit_result into an arbitrary filesystem read by supplying a path.
+const savedResults = new Map<string, string>();
+let resultDirectory: Promise<string> | undefined;
 
 /** Tools with a longer budget; everything else gets DEFAULT_TIMEOUT_MS. The same
  * value is sent to the bridge as timeout_ms and used client-side via AbortSignal. */
@@ -113,11 +96,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()}`;
 
@@ -160,116 +143,147 @@ export async function bridgeRequest(
 	return payload;
 }
 
-export function capText(text: string): string {
-	if (text.length <= MAX_MODEL_CONTENT_CHARS) return text;
-	const suffix = `... [truncated preview at ${MAX_MODEL_CONTENT_CHARS} chars]`;
-	return text.slice(0, Math.max(0, MAX_MODEL_CONTENT_CHARS - suffix.length)) + suffix;
-}
-
-async function modelContent(name: string, payload: BridgeToolResponse): Promise<{ type: "text"; text: string }[]> {
-	const details = payload.details;
-	const value = details !== null && typeof details === "object" && Object.hasOwn(details, "payload")
-		? (details as { payload: unknown }).payload
-		: details;
-	// Current and older bridges both carry the full value in details.payload.
-	// Pi sends content to the model; details alone is only available to its UI.
-	const text = details !== undefined
-		? JSON.stringify(value, null, 2) ?? "null"
-		: payload.content?.map((block) => block.text).join("\n") ?? "{}";
-	if (text.length <= MAX_MODEL_CONTENT_CHARS) return [{ type: "text", text }];
-
-	const resultId = randomUUID();
-	let filePath: string;
-	try {
-		const directory = await (resultDirectory ??= mkdtemp(path.join(os.tmpdir(), "pi-revit-results-")).catch((error) => {
-			// A transient failure must not poison every later large result in this session.
-			resultDirectory = undefined;
-			throw error;
-		}));
-		filePath = path.join(directory, `${resultId}.json`);
-		await writeFile(filePath, text, { encoding: "utf8", flag: "wx", mode: 0o600 });
-	} catch (error) {
-		const reason = error instanceof Error ? error.message : String(error);
-		throw new Error(`Revit completed '${name}', but its large result could not be saved locally: ${reason}. Verify model state before retrying a write.`);
-	}
-	savedResults.set(resultId, filePath);
-	return [{ type: "text", text: JSON.stringify({
-		result_id: resultId,
-		file_path: filePath,
-		total_chars: text.length,
-		complete_inline: false,
-		retrieval: { tool: "read_revit_result", result_id: resultId, offset: 0, limit: MAX_RESULT_PAGE_CHARS },
-		instructions: "The complete result is saved locally. Call read_revit_result, then follow next_offset until has_more is false. Each page is a fragment of the saved text, not a standalone result. Offsets count UTF-16 code units. The absolute file can also be opened with read; it remains available after an extension reload, when this session's result ID may no longer resolve.",
-	}) }];
-}
-
-function registerResultReader(pi: ExtensionAPI) {
-	pi.registerTool({
-		name: "read_revit_result",
-		label: "Read Saved Revit Result",
-		description: "Read a bounded fragment of a large Revit tool result using its opaque result_id. This reads a saved local result and does not contact Revit. Follow next_offset until has_more is false; text fragments concatenate to the complete saved result. Offsets count UTF-16 code units.",
-		parameters: Type.Object({
-			result_id: Type.String({ description: "Opaque result_id returned by a Revit tool in this extension session." }),
-			offset: Type.Optional(Type.Integer({ minimum: 0, description: "Character offset from the previous page's next_offset; default 0." })),
-			limit: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_RESULT_PAGE_CHARS, description: "Maximum characters to return; default 8000. Escaping may require a smaller fragment." })),
-		}),
-		executionMode: "sequential",
-		async execute(_toolCallId, params) {
-			const offset = params.offset ?? 0;
-			const limit = params.limit ?? MAX_RESULT_PAGE_CHARS;
-			if (!Number.isSafeInteger(offset) || offset < 0) throw new Error("offset must be a non-negative integer.");
-			if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_RESULT_PAGE_CHARS)
-				throw new Error(`limit must be an integer from 1 to ${MAX_RESULT_PAGE_CHARS}.`);
-			const filePath = savedResults.get(params.result_id);
-			if (!filePath) throw new Error("Unknown result_id for this extension session. Use the original result's file_path with read if the extension was reloaded.");
-			const text = await readFile(filePath, "utf8");
-			if (offset > text.length) throw new Error(`offset exceeds this result's ${text.length} characters.`);
-			const encode = (count: number) => JSON.stringify({
-				result_id: params.result_id, offset, returned_chars: count, total_chars: text.length,
-				has_more: offset + count < text.length,
-				next_offset: offset + count < text.length ? offset + count : null,
-				fragment: true, text: text.slice(offset, offset + count),
-			});
-			// Bound the actual model message, including JSON escaping and metadata.
-			let low = 0;
-			let high = Math.min(limit, text.length - offset);
-			while (low < high) {
-				const count = Math.ceil((low + high) / 2);
-				if (encode(count).length <= MAX_MODEL_CONTENT_CHARS) low = count;
-				else high = count - 1;
-			}
-			return { content: [{ type: "text", text: encode(low) }], details: { filePath } };
-		},
-	});
-}
-
-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) },
-		},
-		signal,
-		timeoutMs,
-	)) as BridgeToolResponse;
-
-	return { content: await modelContent(name, payload), details: payload.details };
-}
-
-function registerBridgeTool(pi: ExtensionAPI, descriptor: BridgeToolDescriptor) {
-	const timeoutMs = toolTimeoutMs(descriptor.name);
+export function capText(text: string): string {
+	if (text.length <= MAX_MODEL_CONTENT_CHARS) return text;
+	const suffix = `... [truncated preview at ${MAX_MODEL_CONTENT_CHARS} chars]`;
+	return text.slice(0, Math.max(0, MAX_MODEL_CONTENT_CHARS - suffix.length)) + suffix;
+}
+
+async function modelContent(name: string, payload: BridgeToolResponse): Promise<{ type: "text"; text: string }[]> {
+	const details = payload.details;
+	const value = details !== null && typeof details === "object" && Object.hasOwn(details, "payload")
+		? (details as { payload: unknown }).payload
+		: details;
+	// Current and older bridges both carry the full value in details.payload.
+	// Pi sends content to the model; details alone is only available to its UI.
+	const text = details !== undefined
+		? JSON.stringify(value, null, 2) ?? "null"
+		: payload.content?.map((block) => block.text).join("\n") ?? "{}";
+	if (text.length <= MAX_MODEL_CONTENT_CHARS) return [{ type: "text", text }];
+
+	const resultId = randomUUID();
+	let filePath: string;
+	try {
+		const directory = await (resultDirectory ??= mkdtemp(path.join(os.tmpdir(), "pi-revit-results-")).catch((error) => {
+			// A transient failure must not poison every later large result in this session.
+			resultDirectory = undefined;
+			throw error;
+		}));
+		filePath = path.join(directory, `${resultId}.json`);
+		await writeFile(filePath, text, { encoding: "utf8", flag: "wx", mode: 0o600 });
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new Error(`Revit completed '${name}', but its large result could not be saved locally: ${reason}. Verify model state before retrying a write.`);
+	}
+	savedResults.set(resultId, filePath);
+	return [{ type: "text", text: JSON.stringify({
+		result_id: resultId,
+		file_path: filePath,
+		total_chars: text.length,
+		complete_inline: false,
+		retrieval: { tool: "read_revit_result", result_id: resultId, offset: 0, limit: MAX_RESULT_PAGE_CHARS },
+		instructions: "The complete result is saved locally. Call read_revit_result, then follow next_offset until has_more is false. Each page is a fragment of the saved text, not a standalone result. Offsets count UTF-16 code units. The absolute file can also be opened with read; it remains available after an extension reload, when this session's result ID may no longer resolve.",
+	}) }];
+}
+
+function registerResultReader(pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "read_revit_result",
+		label: "Read Saved Revit Result",
+		description: "Read a bounded fragment of a large Revit tool result using its opaque result_id. This reads a saved local result and does not contact Revit. Follow next_offset until has_more is false; text fragments concatenate to the complete saved result. Offsets count UTF-16 code units.",
+		parameters: Type.Object({
+			result_id: Type.String({ description: "Opaque result_id returned by a Revit tool in this extension session." }),
+			offset: Type.Optional(Type.Integer({ minimum: 0, description: "Character offset from the previous page's next_offset; default 0." })),
+			limit: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_RESULT_PAGE_CHARS, description: "Maximum characters to return; default 8000. Escaping may require a smaller fragment." })),
+		}),
+		executionMode: "sequential",
+		async execute(_toolCallId, params) {
+			const offset = params.offset ?? 0;
+			const limit = params.limit ?? MAX_RESULT_PAGE_CHARS;
+			if (!Number.isSafeInteger(offset) || offset < 0) throw new Error("offset must be a non-negative integer.");
+			if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_RESULT_PAGE_CHARS)
+				throw new Error(`limit must be an integer from 1 to ${MAX_RESULT_PAGE_CHARS}.`);
+			const filePath = savedResults.get(params.result_id);
+			if (!filePath) throw new Error("Unknown result_id for this extension session. Use the original result's file_path with read if the extension was reloaded.");
+			const text = await readFile(filePath, "utf8");
+			if (offset > text.length) throw new Error(`offset exceeds this result's ${text.length} characters.`);
+			const encode = (count: number) => JSON.stringify({
+				result_id: params.result_id, offset, returned_chars: count, total_chars: text.length,
+				has_more: offset + count < text.length,
+				next_offset: offset + count < text.length ? offset + count : null,
+				fragment: true, text: text.slice(offset, offset + count),
+			});
+			// Bound the actual model message, including JSON escaping and metadata.
+			let low = 0;
+			let high = Math.min(limit, text.length - offset);
+			while (low < high) {
+				const count = Math.ceil((low + high) / 2);
+				if (encode(count).length <= MAX_MODEL_CONTENT_CHARS) low = count;
+				else high = count - 1;
+			}
+			return { content: [{ type: "text", text: encode(low) }], details: { filePath } };
+		},
+	});
+}
+
+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 };
+		},
+	});
+}
+
+function registerBridgeTool(pi: ExtensionAPI, descriptor: BridgeToolDescriptor, resolve: BridgeResolver) {
+	const timeoutMs = toolTimeoutMs(descriptor.name);
+	const schema = structuredClone(descriptor.parameters ?? { type: "object", properties: {} }) as { properties?: Record<string, unknown> };
+	schema.properties = { ...schema.properties, _operation_id: { type: "string", description: "Optional exact operation ID for retrying an identical earlier request. Reuses its result without repeating the action. Omit for a new operation." } };
 	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),
-		promptSnippet: descriptor.promptSnippet ?? undefined,
-		promptGuidelines: descriptor.promptGuidelines ?? undefined,
+		parameters: Type.Unsafe(schema as TSchema),
+		promptSnippet: descriptor.tier === "advanced" ? undefined : descriptor.promptSnippet ?? undefined,
+		promptGuidelines: descriptor.tier === "advanced" ? undefined : descriptor.promptGuidelines ?? undefined,
 		executionMode: descriptor.executionMode === "parallel" ? "parallel" : "sequential",
 		async execute(_toolCallId, params, signal) {
-			return runBridgeTool(descriptor.name, params, signal, timeoutMs);
+			return runBridgeTool(descriptor.name, params, signal, timeoutMs, resolve);
 		},
 	});
 }
@@ -352,7 +366,7 @@ async function announceUpdateOnce(notify: (message: string, level: "info") => vo
 	}
 }
 
-function registerPing(pi: ExtensionAPI, onBridgeAlive?: () => Promise<"ready" | "registered" | "failed">) {
+function registerPing(pi: ExtensionAPI, resolve: BridgeResolver, onBridgeAlive?: () => Promise<"ready" | "registered" | "failed">) {
 	pi.registerTool({
 		name: "ping",
 		label: "Ping Revit Bridge",
@@ -362,7 +376,7 @@ function registerPing(pi: ExtensionAPI, onBridgeAlive?: () => Promise<"ready" |
 		promptGuidelines: ["Use ping when Revit tools fail or bridge availability is unclear."],
 		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.
@@ -384,31 +398,71 @@ function registerPing(pi: ExtensionAPI, onBridgeAlive?: () => Promise<"ready" |
 
 const REDISCOVERY_INTERVAL_MS = 15_000;
 
-export default async function revitConnector(pi: ExtensionAPI) {
-	registerResultReader(pi);
+export default async function revitConnector(pi: ExtensionAPI) {
+	const instances = createInstanceRouter(readBridgeInfo, async info => await bridgeRequest("/ping", { method: "GET", bridge: info }, undefined, 2000) as Record<string, unknown>);
+	registerResultReader(pi);
+	registerOperationReader(pi, instances.resolve);
+	registerScriptLibrary(pi, (args, signal, prepared) => runBridgeTool("execute_csharp", args, signal, LONG_TIMEOUT_MS, instances.resolve, prepared),
+		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
 	// 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 discoveryInFlight: Promise<boolean> | null = null;
-
-	async function discoverAndRegister(): Promise<boolean> {
+	let bridgeToolsRegistered = false;
+	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 payload = (await bridgeRequest("/tools", { method: "GET", bridge: await instances.resolve() }, 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) {
+				const descriptors = Array.isArray(payload?.tools) ? payload.tools : [];
+				if (disposed || descriptors.length === 0) return false;
+				const added: string[] = [];
+				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 (["ping", "read_revit_result", "find_revit_tools", "get_revit_operation", "manage_revit_instances", "manage_revit_scripts"].includes(descriptor.name)) continue;
+					registerBridgeTool(pi, descriptor, instances.resolve);
+					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 {
@@ -426,7 +480,7 @@ 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";
 	});
@@ -434,10 +488,13 @@ export default async function revitConnector(pi: ExtensionAPI) {
 	// 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) => {
+	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 +502,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 };
+}