pi-revit 0.3.0 → 0.4.0

package/extensions/pi-revit/index.ts

@@ -5,17 +5,15 @@ 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,21 +28,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 +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()}`;
 
@@ -243,33 +226,64 @@ 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) },
-		},
-		signal,
-		timeoutMs,
-	)) as BridgeToolResponse;
-
-	return { content: await modelContent(name, payload), details: payload.details };
-}
+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) {
-	const timeoutMs = toolTimeoutMs(descriptor.name);
+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.
@@ -385,30 +399,70 @@ function registerPing(pi: ExtensionAPI, onBridgeAlive?: () => Promise<"ready" |
 const REDISCOVERY_INTERVAL_MS = 15_000;
 
 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 };
+}

package/extensions/pi-revit/script-library.ts

@@ -0,0 +1,146 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { mkdir, readdir, readFile, writeFile, rename } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import path from "node:path";
+import os from "node:os";
+
+type InputKind = "string" | "number" | "integer" | "boolean" | "object" | "array";
+interface Definition { name: string; description: string; code: string; input_types: Record<string, InputKind>; }
+interface Version extends Definition { version: string; created_at: string; }
+interface Receipt { operation_id: string; bridge_id: string; }
+type Result = { content: { type: "text"; text: string }[]; details?: unknown };
+type Runner = (args: Record<string, unknown>, signal: AbortSignal | undefined, prepared: (receipt: Receipt) => Promise<void>) => Promise<Result>;
+const kinds = ["string", "number", "integer", "boolean", "object", "array"] as const;
+const object = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+const hash = (value: unknown) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const scriptName = (name: unknown) => {
+    if (typeof name !== "string" || !/^[a-z][a-z0-9_-]{0,63}$/.test(name)) throw new Error("name must be 1–64 lowercase letters, digits, underscores or hyphens, starting with a letter.");
+    return name;
+};
+const versionId = (version: unknown) => {
+    if (typeof version !== "string" || !/^[a-f0-9]{64}$/.test(version)) throw new Error("version must be the exact saved 64-character hash.");
+    return version;
+};
+
+export function createScriptLibrary(root: string) {
+    const versions = path.join(root, "versions"), history = path.join(root, "history");
+    const definition = (value: Record<string, unknown>): Definition => {
+        const name = scriptName(value.name);
+        if (typeof value.code !== "string" || !value.code.trim() || value.code.length > 100000) throw new Error("code must contain 1–100,000 characters.");
+        if (typeof value.description !== "string" || value.description.length > 2000) throw new Error("description must be a string of at most 2,000 characters.");
+        if (!object(value.input_types) || Object.keys(value.input_types).length > 40) throw new Error("input_types must declare at most 40 named inputs.");
+        const input_types: Record<string, InputKind> = Object.create(null);
+        for (const key of Object.keys(value.input_types).sort()) {
+            if (!/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(key) || !kinds.includes(value.input_types[key] as InputKind)) throw new Error(`Invalid input declaration: ${key}.`);
+            input_types[key] = value.input_types[key] as InputKind;
+        }
+        return { name, description: value.description, code: value.code, input_types };
+    };
+    async function files(directory: string) {
+        try { return (await readdir(directory)).filter(file => file.endsWith(".json")); }
+        catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; throw error; }
+    }
+    async function read(name: unknown, version: unknown): Promise<Version> {
+        const value = JSON.parse(await readFile(path.join(versions, `${scriptName(name)}--${versionId(version)}.json`), "utf8"));
+        const content = definition(value);
+        if (content.name !== name || hash(content) !== version || value.version !== version) throw new Error("Saved script integrity check failed; no code was executed.");
+        return { ...content, version: value.version, created_at: value.created_at };
+    }
+    async function save(args: Record<string, unknown>) {
+        const content = definition(args), version = hash(content);
+        await mkdir(versions, { recursive: true });
+        const file = path.join(versions, `${content.name}--${version}.json`);
+        const value = { ...content, version, created_at: new Date().toISOString() };
+        try { await writeFile(file, JSON.stringify(value, null, 2), { encoding: "utf8", flag: "wx" }); }
+        catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+        const saved = await read(content.name, version);
+        return { name: saved.name, version, created_at: saved.created_at, file_path: file, executed: false };
+    }
+    function validateInputs(saved: Version, input: unknown) {
+        if (!object(input)) throw new Error("inputs must be a JSON object.");
+        if (JSON.stringify(input).length > 100000) throw new Error("inputs exceed 100,000 JSON characters.");
+        for (const name of Object.keys(input)) if (!Object.hasOwn(saved.input_types, name)) throw new Error(`Undeclared input: ${name}.`);
+        for (const [name, kind] of Object.entries(saved.input_types)) {
+            const value = input[name];
+            const valid = Object.hasOwn(input, name) && (kind === "array" ? Array.isArray(value) : kind === "object" ? object(value)
+                : kind === "integer" ? Number.isSafeInteger(value) : kind === "number" ? typeof value === "number" && Number.isFinite(value) : typeof value === kind);
+            if (!valid) throw new Error(`Input '${name}' is required and must be ${kind}.`);
+        }
+        return input;
+    }
+    async function list(name: unknown, offset: number, limit: number) {
+        const filter = name === undefined ? undefined : scriptName(name);
+        const names = (await files(versions)).filter(file => /^[a-z][a-z0-9_-]{0,63}--[a-f0-9]{64}\.json$/.test(file) && (!filter || file.slice(0, file.lastIndexOf("--")) === filter)).sort();
+        const entries = [];
+        for (const file of names.slice(offset, offset + limit)) {
+            const split = file.lastIndexOf("--");
+            const value = await read(file.slice(0, split), file.slice(split + 2, -5));
+            entries.push({ name: value.name, version: value.version, description: value.description, input_types: value.input_types, created_at: value.created_at });
+        }
+        return { total_count: names.length, offset, entries, next_offset: offset + entries.length < names.length ? offset + entries.length : null };
+    }
+    async function writeHistory(record: Record<string, unknown>) {
+        await mkdir(history, { recursive: true });
+        const file = path.join(history, `${record.run_id}.json`), temp = `${file}.${randomUUID()}.tmp`;
+        await writeFile(temp, JSON.stringify(record, null, 2), { encoding: "utf8", flag: "wx" });
+        await rename(temp, file);
+    }
+    async function readHistory(name: unknown, offset: number, limit: number) {
+        const filter = name === undefined ? undefined : scriptName(name);
+        const entries = [];
+        for (const file of await files(history)) {
+            if (!/^[a-f0-9-]{36}\.json$/.test(file)) continue;
+            const value = JSON.parse(await readFile(path.join(history, file), "utf8"));
+            if (!filter || value.name === filter) entries.push(value);
+        }
+        entries.sort((a, b) => b.started_at.localeCompare(a.started_at) || a.run_id.localeCompare(b.run_id));
+        return { total_count: entries.length, offset, entries: entries.slice(offset, offset + limit), next_offset: offset + limit < entries.length ? offset + limit : null };
+    }
+    return { root, read, save, list, validateInputs, writeHistory, readHistory };
+}
+
+export function registerScriptLibrary(pi: ExtensionAPI, run: Runner, render: (value: unknown) => Promise<Result>) {
+    const library = createScriptLibrary(path.join(process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming"), "pi-revit", "scripts"));
+    pi.registerTool({
+        name: "manage_revit_scripts", label: "Manage Revit Scripts",
+        description: "Save, list, read, run and inspect local reusable C# scripts. Saving never executes code. Versions are immutable content hashes; read a version before explicitly running that exact hash. Every declared input is required; extra inputs are rejected. input_types validates top-level JSON kinds only; scripts validate nested contents and domain rules. Runs use execute_csharp with separate inputs JsonElement, exact expected_document_id and operation receipts. Scripts have the same unrestricted model/UI/file/external effects and transaction behavior as execute_csharp. Local history records version, document, input hash and receipt, not input values or results. After interruption, inspect get_revit_operation before retrying with the same _operation_id and identical inputs. No automatic runs or model saving.",
+        parameters: Type.Object({
+            action: Type.Union(["list", "save", "read", "run", "history"].map(value => Type.Literal(value))),
+            name: Type.Optional(Type.String()), version: Type.Optional(Type.String()), description: Type.Optional(Type.String({ maxLength: 2000 })),
+            code: Type.Optional(Type.String({ minLength: 1, maxLength: 100000 })),
+            input_types: Type.Optional(Type.Record(Type.String(), Type.Union(kinds.map(value => Type.Literal(value))))),
+            inputs: Type.Optional(Type.Record(Type.String(), Type.Unknown())), expected_document_id: Type.Optional(Type.String()), _operation_id: Type.Optional(Type.String()),
+            offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+        }),
+        executionMode: "sequential",
+        async execute(_id, args, signal) {
+            const offset = Math.max(0, args.offset ?? 0), limit = Math.max(1, Math.min(100, args.limit ?? 20));
+            if (args.action === "save") return render(await library.save(args));
+            if (args.action === "list") return render(await library.list(args.name, offset, limit));
+            if (args.action === "history") return render(await library.readHistory(args.name, offset, limit));
+            if (args.action !== "read" && args.action !== "run") throw new Error("Unknown script library action.");
+            const saved = await library.read(args.name, args.version);
+            if (args.action === "read") return render(saved);
+            if (typeof args.expected_document_id !== "string" || !args.expected_document_id) throw new Error("Run requires expected_document_id from get_model_overview.");
+            const inputs = library.validateInputs(saved, args.inputs ?? {});
+            const record: Record<string, unknown> = { run_id: randomUUID(), name: saved.name, version: saved.version, started_at: new Date().toISOString(), expected_document_id: args.expected_document_id, inputs_hash: hash(inputs), state: "prepared" };
+            let dispatched = false;
+            try {
+                const result = await run({ code: saved.code, inputs, expected_document_id: args.expected_document_id, ...(args._operation_id !== undefined ? { _operation_id: args._operation_id } : {}) }, signal, async receipt => {
+                    Object.assign(record, receipt); await library.writeHistory(record); dispatched = true;
+                });
+                Object.assign(record, { state: "response_received", completed_at: new Date().toISOString() });
+                try { await library.writeHistory(record); }
+                catch { result.content.push({ type: "text", text: "The script response was received, but the final local history update failed. Use the operation receipt for its outcome." }); }
+                return result;
+            } catch (error) {
+                if (dispatched) {
+                    Object.assign(record, { state: "outcome_unconfirmed", completed_at: new Date().toISOString() });
+                    try { await library.writeHistory(record); } catch { /* Preserve the original error and operation ID. */ }
+                }
+                throw error;
+            }
+        },
+    });
+}

package/extensions/pi-revit/tool-catalog.ts

@@ -0,0 +1,67 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+export interface BridgeToolDescriptor {
+	name: string;
+	label?: string;
+	description?: string;
+	category?: string;
+	tier?: string;
+	parameters?: unknown;
+	executionMode?: string;
+	write?: boolean;
+	effects?: string[];
+	requiresDocument?: boolean;
+	promptSnippet?: string | null;
+	promptGuidelines?: string[] | null;
+}
+
+/** The bridge registry is the source of truth; discovery never duplicates its schemas. */
+export function createToolCatalog(pi: ExtensionAPI, discover: () => Promise<boolean>) {
+	const entries = new Map<string, BridgeToolDescriptor>();
+	function hideAdvanced(names: string[] = [...entries.keys()]) {
+		const advanced = new Set(names.filter(name => entries.get(name)?.tier === "advanced"));
+		pi.setActiveTools(pi.getActiveTools().filter(name => !advanced.has(name)));
+	}
+
+	pi.registerTool({
+		name: "find_revit_tools",
+		label: "Find Revit Tools",
+		description: "Search the installed Revit tool catalogue and activate matching tools for this Pi session. Search words match tool names and descriptions. Supply exact names to activate known tools. With no query or names, list tools without activating them. Activation is additive and does not run any Revit operation. Read the returned schemas on the next model turn before calling a newly activated tool.",
+		promptSnippet: "Find and activate specialist Revit tools for links, schedules, relationships, inspection and editing.",
+		promptGuidelines: ["Use find_revit_tools to discover and activate specialist Revit tools before using execute_csharp for a task that may already have a dedicated tool."],
+		parameters: Type.Object({
+			query: Type.Optional(Type.String({ description: "Search words, such as linked elements or schedules." })),
+			names: Type.Optional(Type.Array(Type.String(), { maxItems: 20, description: "Exact tool names; takes precedence over query." })),
+			activate: Type.Optional(Type.Boolean({ description: "Activate returned matches. Default true for a query or exact names; false for browsing." })),
+			offset: Type.Optional(Type.Integer({ minimum: 0 })),
+			limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 20 })),
+		}),
+		executionMode: "sequential",
+		async execute(_id, args) {
+			if (!entries.size && !(await discover())) throw new Error("The Revit tool catalogue is unavailable. Start Revit with the bridge loaded and retry.");
+			const names = args.names?.length ? [...new Set(args.names)] : undefined;
+			if (names?.some(name => !entries.has(name))) throw new Error(`Unknown Revit tool names: ${names.filter(name => !entries.has(name)).join(", ")}`);
+			const words = (args.query ?? "").trim().toLowerCase().split(/[\s_]+/).filter(Boolean);
+			const matches = [...entries.values()].filter(entry => names ? names.includes(entry.name)
+				: words.every(word => `${entry.name.replaceAll("_", " ")} ${entry.description ?? ""}`.toLowerCase().includes(word)))
+				.sort((a, b) => a.name.localeCompare(b.name));
+			const offset = Math.max(0, args.offset ?? 0);
+			const page = matches.slice(offset, offset + Math.max(1, Math.min(20, args.limit ?? 10)));
+			const activate = args.activate ?? Boolean(names || words.length);
+			if (activate && page.length) pi.setActiveTools([...new Set([...pi.getActiveTools(), ...page.map(entry => entry.name)])]);
+			const active = new Set(pi.getActiveTools());
+			const result = {
+				total_count: matches.length, offset, returned_count: page.length,
+				next_offset: offset + page.length < matches.length ? offset + page.length : null,
+				tools: page.map(entry => ({ name: entry.name, description: entry.description, tier: entry.tier ?? "core", effects: entry.effects ?? (entry.write ? ["model"] : []), active: active.has(entry.name) })),
+			};
+			return { content: [{ type: "text" as const, text: JSON.stringify(result) }], details: result };
+		},
+	});
+	function reset() {
+		pi.setActiveTools(pi.getActiveTools().filter(name => !entries.has(name)));
+		entries.clear();
+	}
+	return { add: (entry: BridgeToolDescriptor) => entries.set(entry.name, entry), hideAdvanced, reset };
+}