pi-revit 0.3.1 → 0.5.0

package/extensions/pi-revit/scope-monitor.ts

@@ -0,0 +1,114 @@
+/**
+ * Scope monitor (inv:existing-objects-not-reused). Tool-agnostic: it reads the model_changes
+ * report the bridge attaches to every model-changing result, and the name_collision facts a
+ * rejected creation carries, never tool names. Per user request it keeps the IDs of objects
+ * created in that request. When a call changes an object that existed before the request and
+ * whose name the request mentions, or a name the request uses is already taken, it returns a
+ * note that the object predates the request; the platform protocol then requires asking or
+ * reporting. It steers and never blocks. Reset at the start of every user prompt.
+ */
+export interface ChangedItem { id: number; name?: string | null; category?: string | null }
+export interface ModelChanges {
+	observed?: boolean;
+	rolled_back?: boolean;
+	/** Family types and parameters (not elements) added, removed or changed by the call, in a family document. */
+	family?: { types_added?: string[]; types_removed?: string[]; types_changed?: string[]; parameters_added?: string[]; parameters_removed?: string[] };
+	added?: { count: number; items?: ChangedItem[] };
+	modified?: { count: number; items?: ChangedItem[] };
+	deleted?: { count: number; ids?: number[] };
+}
+export interface NameCollision { existing_id: number | null; kind?: string; name?: string; sheet_number?: string }
+
+/** The model_changes report of a bridge payload, or null (older bridge, read tool, non-object payload). */
+export function readModelChanges(payload: unknown): ModelChanges | null {
+	const value = payload !== null && typeof payload === "object" ? (payload as { model_changes?: unknown }).model_changes : undefined;
+	return value !== null && typeof value === "object" ? value as ModelChanges : null;
+}
+
+/**
+ * Whether a call actually changed the model, from model_changes: a report without observed
+ * document changes means nothing changed (a read through a write-capable tool). Undefined only
+ * when there is no report (an older bridge), so declared metadata decides.
+ */
+export function changedModel(payload: unknown): boolean | undefined {
+	const changes = readModelChanges(payload);
+	if (!changes) return undefined;
+	if (!changes.observed) return false;
+	return (changes.added?.count ?? 0) + (changes.modified?.count ?? 0) + (changes.deleted?.count ?? 0) > 0;
+}
+
+/** Every name_collision object anywhere in a payload (rejected rows keep it next to their reason). */
+export function findCollisions(payload: unknown, found: NameCollision[] = [], depth = 0): NameCollision[] {
+	if (depth > 6 || payload === null || typeof payload !== "object") return found;
+	for (const [key, value] of Object.entries(payload as Record<string, unknown>)) {
+		if (key === "name_collision" && value && typeof value === "object" && "existing_id" in value) found.push(value as NameCollision);
+		else if (key !== "model_changes") findCollisions(value, found, depth + 1);
+	}
+	return found;
+}
+
+const normalize = (text: string) => text.normalize("NFKC").toLowerCase().replace(/\s+/g, " ").trim();
+const words = new Intl.Segmenter(undefined, { granularity: "word" });
+const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+/**
+ * Word boundaries of a text in any writing system, from Unicode segmentation (ICU): spaces and
+ * punctuation where a script uses them, dictionary boundaries where it does not (Chinese,
+ * Japanese, Thai, Khmer, ...). No language or script list is involved.
+ */
+export function wordBoundaries(text: string): Set<number> {
+	const bounds = new Set([0, text.length]);
+	for (const segment of words.segment(text)) { bounds.add(segment.index); bounds.add(segment.index + segment.segment.length); }
+	return bounds;
+}
+
+/** Whether name occurs in text as whole words: 'Site' is not mentioned by 'opposite'. */
+export function mentionsName(text: string, bounds: Set<number>, name: string | null | undefined, minGraphemes = 2): boolean {
+	const value = normalize(name ?? "");
+	if ([...graphemes.segment(value)].length < minGraphemes) return false;
+	for (let at = text.indexOf(value); at >= 0; at = text.indexOf(value, at + 1))
+		if (bounds.has(at) && bounds.has(at + value.length)) return true;
+	return false;
+}
+
+export function createScopeMonitor(options: { minNameGraphemes?: number } = {}) {
+	let request = "";
+	let bounds = new Set<number>();
+	const created = new Set<number>();
+	const createdFamilyTypes = new Set<string>();
+	const notedFamilyTypes = new Set<string>();
+	const noted = new Set<number>();
+	const notedCollisions = new Set<number | string>();
+	const mentioned = (name: string | null | undefined) => mentionsName(request, bounds, name, options.minNameGraphemes ?? 2);
+	return {
+		/** Start of a new user request; its text decides which object names the request mentions. */
+		reset(prompt: string) {
+			request = normalize(prompt ?? ""); bounds = wordBoundaries(request);
+			created.clear(); noted.clear(); notedCollisions.clear(); createdFamilyTypes.clear(); notedFamilyTypes.clear();
+		},
+		/** Record one tool result; returns a scope note to append, or null. */
+		afterResult(payload: unknown): string | null {
+			const notes: string[] = [];
+			const changes = readModelChanges(payload);
+			for (const item of changes?.added?.items ?? []) created.add(item.id);
+			for (const name of changes?.family?.types_added ?? []) createdFamilyTypes.add(name);
+			// Family types have no element ID; the same rule applies to them by name.
+			const familyTypes = (changes?.family?.types_changed ?? []).filter(name => !createdFamilyTypes.has(name) && !notedFamilyTypes.has(name) && mentioned(name));
+			for (const name of familyTypes) notedFamilyTypes.add(name);
+			const preexisting = [...(changes?.modified?.items ?? []).filter(item => !created.has(item.id) && !noted.has(item.id) && mentioned(item.name)),
+				...familyTypes.map(name => ({ id: null as unknown as number, name, category: "family type" }))];
+			for (const item of preexisting) if (item.id !== null) noted.add(item.id);
+			if (preexisting.length) notes.push(`PI-Revit scope note: this call changed ${preexisting.map(item => item.id === null ? `family type '${item.name}'` : `'${item.name}' (id ${item.id})`).join(", ")}, which existed before this request: no call in this request created it. `
+				+ "If the request asked you to create an object with this name, you changed an existing object instead: tell the user exactly what you changed and ask before changing it further. If the request asked you to change this existing object, continue.");
+			// Family types have no element ID; they are noted by name instead.
+			const key = (c: NameCollision) => c.existing_id ?? `${c.kind}:${c.name}`;
+			const collisions = findCollisions(payload).filter(collision => !notedCollisions.has(key(collision)));
+			for (const collision of collisions) notedCollisions.add(key(collision));
+			if (collisions.length) notes.push(`PI-Revit scope note: ${collisions.map(c => `'${c.name ?? c.sheet_number}' is already used by ${c.kind ?? "an object"}${c.existing_id !== null ? ` ${c.existing_id}` : ""}`).join("; ")}. `
+				+ "That object existed before this call. Do not edit, rename, reuse, replace or delete it to get past the collision: ask the user which object or name to use, or create under a distinct name and report the collision.");
+			return notes.length ? notes.join("\n") : null;
+		},
+		/** IDs of objects created in this request, as reported by model_changes. */
+		created: () => [...created],
+	};
+}

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,166 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { contractHash, descriptorLimits, packagedContracts, withApiLookups, type ToolLimit } from "./contracts.js";
+import { createDiscoveryIndex } from "./discovery.js";
+import { documentedTools, packagedGuidance, readablePathWithin, resolveToolDocumentation, skillRoot } from "./tool-documentation.js";
+
+export interface BridgeToolDescriptor {
+	name: string;
+	label?: string;
+	description?: string;
+	category?: string;
+	tier?: string;
+	parameters?: unknown;
+	executionMode?: string;
+	write?: boolean;
+	effects?: string[];
+	requiresDocument?: boolean;
+	documentKinds?: string[] | null;
+	promptSnippet?: string | null;
+	promptGuidelines?: string[] | null;
+	keywords?: string[] | null;
+	limits?: unknown;
+	verification?: string | null;
+}
+
+interface Candidate {
+	name: string; source: "native" | "bridge"; description: string | null; summary: string | null; keywords: string[];
+	tier: string | null; effects: string[] | null; verification: string | null; limits: ToolLimit[] | null; inputs: string[]; documentKinds: string[] | null;
+}
+interface Guide { name: string; kind: string; path: string | null; summary: string; keywords: string[] }
+
+/** Packaged guidance plus every skill found beside this package's skill (future subject skills included). */
+function loadGuidance(): Guide[] {
+	const guides: Guide[] = packagedGuidance.map(g => ({ name: g.name, kind: g.kind, path: readablePathWithin(skillRoot, g.path), summary: g.summary, keywords: g.keywords ?? [] }));
+	const skillsRoot = path.resolve(skillRoot, "..");
+	let directories: string[] = [];
+	try { directories = readdirSync(skillsRoot, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name).sort(); } catch { /* no sibling skills */ }
+	for (const directory of directories) {
+		const file = readablePathWithin(skillsRoot, path.join(directory, "SKILL.md"));
+		if (!file) continue;
+		try {
+			const front = readFileSync(file, "utf8").match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] ?? "";
+			const field = (key: string) => front.match(new RegExp(`^${key}:\\s*(.+)$`, "m"))?.[1]?.trim().replace(/^["']|["']$/g, "") ?? null;
+			const keywords = (field("keywords") ?? "").split(",").map(k => k.trim()).filter(Boolean);
+			guides.push({ name: field("name") ?? directory, kind: "skill", path: file, summary: field("description") ?? "", keywords });
+		} catch { /* unreadable skill metadata is skipped, never fatal */ }
+	}
+	return guides;
+}
+
+const FALLBACK_ROUTE = [
+	"A missing dedicated tool does not mean the operation is impossible.",
+	"If a tool is still expected, retry with fewer task words, a different wording, exact names, or scope=documentation.",
+	"Otherwise verify the needed Revit API members with search_api_docs, then use execute_csharp within the requested scope.",
+	"Report that something is not possible only after that check, naming what was checked.",
+];
+
+/** 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>();
+	const liveHashes = new Map<string, string>();
+	// Pi retains registrations when a bridge switch merely deactivates them.
+	// Keep this separate from the selected bridge's current discovery snapshot.
+	const registeredBridgeNames = new Set<string>();
+	const manifestByName = new Map(documentedTools.map(entry => [entry.name, entry]));
+	const natives = documentedTools.filter(entry => entry.source === "native");
+	const guides = loadGuidance();
+	const index = createDiscoveryIndex();
+	let bridgeVersion: string | null = null;
+	let observedAt: string | null = null;
+	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)));
+	}
+	function candidate(name: string, source: "native" | "bridge", live?: BridgeToolDescriptor): Candidate {
+		const packaged = packagedContracts.get(name);
+		return {
+			name, source,
+			description: live?.description ?? null,
+			summary: manifestByName.get(name)?.summary ?? null,
+			// Live v2 metadata wins; packaged metadata fills gaps from older bridges; unknown stays unknown.
+			keywords: live?.keywords ?? packaged?.keywords ?? [],
+			tier: live?.tier ?? packaged?.tier ?? (source === "native" ? "core" : null),
+			effects: live?.effects ?? (live?.write !== undefined ? (live.write ? ["model"] : []) : packaged?.effects ?? null),
+			verification: live?.verification ?? packaged?.verification ?? null,
+			limits: descriptorLimits(live?.limits) ?? packaged?.limits ?? null,
+			inputs: Object.keys(((live?.parameters ?? packaged?.parameters) as { properties?: object } | undefined)?.properties ?? {}),
+			documentKinds: live?.documentKinds ?? packaged?.document_kinds ?? null,
+		};
+	}
+
+	pi.registerTool({
+		name: "find_revit_tools",
+		label: "Find Revit Tools",
+		description: "Search PI-Revit tools, workflows and guidance by English task words, and activate matching tools. Tool vocabulary is English: translate a request written in another language into English search words first. The default available scope covers native utilities and the selected bridge's last-discovered tools; a query or names activates matches, while browsing only lists. scope=documentation searches packaged manuals without contacting Revit or activating tools, including when Revit is closed. Each tool result gives its declared limits with alternatives, its verification method, its manual path and whether that manual matches the selected bridge's contract. When nothing matches every word, the result states the remaining route: API search, then custom execution. Activation is additive and runs no Revit operation.",
+		promptSnippet: "Find PI-Revit capabilities, their limits and alternatives, and activate specialist tools.",
+		promptGuidelines: ["find_revit_tools: search with short English task words (translate the user's language first); use names for a known tool and scope=documentation while Revit is closed. Read only the returned manuals you need."],
+		parameters: Type.Object({
+			scope: Type.Optional(Type.Union([Type.Literal("available"), Type.Literal("documentation")], { description: "available (default): search registered native and last-discovered bridge tools. documentation: read-only packaged manual lookup; no bridge request or activation." })),
+			query: Type.Optional(Type.String({ description: "Short English task words, such as 'tag rooms' or 'count walls per level'; translate from the user's language first. Tools matching every word rank first, followed by strong partial matches; when nothing matches every word the remaining route is explained. Use separate queries for different capabilities." })),
+			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) {
+			const scope = args.scope ?? "available";
+			if (scope !== "available" && scope !== "documentation") throw new Error("scope must be available or documentation.");
+			if (scope === "documentation" && args.activate === true) throw new Error("documentation scope does not activate tools. Use available scope to activate registered tools.");
+			if (scope === "available" && observedAt === null) await discover();
+			const candidates = new Map<string, Candidate>();
+			if (scope === "documentation") for (const tool of documentedTools) candidates.set(tool.name, candidate(tool.name, tool.source));
+			for (const tool of natives) candidates.set(tool.name, candidate(tool.name, "native"));
+			for (const tool of entries.values()) candidates.set(tool.name, candidate(tool.name, "bridge", tool));
+			const names = args.names?.length ? [...new Set(args.names)] : undefined;
+			if (names?.some(name => !candidates.has(name))) throw new Error(`Unknown Revit tool names or tools unavailable in this scope: ${names.filter(name => !candidates.has(name)).join(", ")}. Use scope=documentation to look up packaged manuals independently of bridge availability.`);
+			const query = (args.query ?? "").trim();
+			const toDocument = (c: Candidate) => ({ name: c.name, keywords: c.keywords, summary: c.summary, description: c.description, limits: c.limits?.map(limit => limit.what), inputs: c.inputs });
+			let mode: "names" | "browse" | "all" | "partial" | "none";
+			let matches: Candidate[];
+			if (names) { mode = "names"; matches = [...candidates.values()].filter(c => names.includes(c.name)).sort((a, b) => a.name.localeCompare(b.name)); }
+			else if (!query) { mode = "browse"; matches = [...candidates.values()].sort((a, b) => a.name.localeCompare(b.name)); }
+			else { const result = index.search([...candidates.values()], query, toDocument); mode = result.mode; matches = result.matches.map(m => m.item); }
+			const offset = Math.max(0, args.offset ?? 0);
+			const pageSize = Math.max(1, Math.min(20, args.limit ?? (mode === "partial" ? 5 : 10)));
+			const page = matches.slice(offset, offset + pageSize);
+			const activate = scope === "available" && (args.activate ?? (mode === "names" || mode === "all" || mode === "partial"));
+			if (activate && page.length) pi.setActiveTools([...new Set([...pi.getActiveTools(), ...page.map(entry => entry.name)])]);
+			const active = new Set(pi.getActiveTools());
+			const guidance = query && !names ? index.search(guides, query, g => ({ name: g.name, keywords: g.keywords, summary: g.summary })).matches.slice(0, 5)
+				.map(({ item }) => ({ name: item.name, kind: item.kind, path: item.path, summary: item.summary })) : [];
+			const result = {
+				scope, bridge_catalog_known: observedAt !== null, bridge_catalog_observed_at: observedAt, match: mode,
+				instructions: "Bridge availability is a discovery snapshot, not a fresh health check; registration, advertisement and activation are separate. Follow a tool's limits alternatives when it does not cover the request; an API alternative's lookup verifies all its members in one search_api_docs call. contract_match means the manual was generated from the selected bridge's exact input contract; otherwise trust the active schema. Read only relevant manual paths.",
+				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 ?? entry.summary, source: entry.source,
+					tier: entry.tier, effects: entry.effects, verification: entry.verification, document_kinds: entry.documentKinds,
+					limits: entry.limits ? withApiLookups(entry.limits) : "unknown: no declared limits; if the tool does not cover the request, use the capability route",
+					registered: entry.source === "native" || registeredBridgeNames.has(entry.name),
+					advertised_by_selected_bridge: entry.source === "native" ? null : observedAt !== null ? entries.has(entry.name) : null,
+					active: active.has(entry.name),
+					documentation: resolveToolDocumentation(entry.name, { contractHash: entries.has(entry.name) ? liveHashes.get(entry.name) ?? null : null, bridgeVersion }) })),
+				guidance,
+				...(query && (mode === "none" || mode === "partial") ? { fallback: { reason: mode === "none" ? "No tool matched this query." : "No tool matched every word; these are partial matches.", route: FALLBACK_ROUTE } } : {}),
+			};
+			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();
+		liveHashes.clear();
+		bridgeVersion = null;
+		observedAt = null;
+	}
+	return { add: (entry: BridgeToolDescriptor) => {
+		entries.set(entry.name, entry); liveHashes.set(entry.name, contractHash(entry)); registeredBridgeNames.add(entry.name); observedAt = new Date().toISOString();
+	},
+		// Called after successful /tools discovery, including a valid empty array.
+		setBridgeVersion: (value: string | null) => { bridgeVersion = value; observedAt = new Date().toISOString(); },
+		liveContracts: () => new Map(liveHashes), hideAdvanced, reset };
+}

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

@@ -0,0 +1,72 @@
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import manifest from "../../skills/pi-revit/tool-manifest.json";
+import { version as packageVersion } from "../../package.json";
+import { packagedContracts } from "./contracts.js";
+
+export interface DocumentedTool { name: string; source: "native" | "bridge"; group: string; summary: string; }
+export interface GuidanceEntry { name: string; kind: string; path: string; summary: string; keywords?: string[] }
+// This index is documentation metadata only. Live registration remains authoritative
+// for input schemas, effects, tool availability and execution.
+export const documentedTools = manifest.tools as DocumentedTool[];
+export const packagedGuidance = manifest.guidance as GuidanceEntry[];
+export const documentationRevision = manifest.documentation_revision as string;
+const byName = new Map(documentedTools.map(tool => [tool.name, tool]));
+const defaultRoot = fileURLToPath(new URL("../../skills/pi-revit/references/tools/", import.meta.url));
+export const skillRoot = fileURLToPath(new URL("../../skills/pi-revit/", import.meta.url));
+export const manualDirectory = defaultRoot;
+
+/**
+ * Compatibility compares the executable-contract hash of the selected bridge's live
+ * descriptor with the hash the packaged manual was generated from:
+ *   package_local     native tool documented and shipped with this extension
+ *   contract_match    identical input schema and effects; the manual describes this contract
+ *   contract_changed  the live contract differs; trust the active schema over the manual
+ *   undocumented      the live tool has no packaged contract (newer bridge)
+ *   unknown           no live contract observed (bridge not discovered)
+ */
+export interface LiveEvidence { contractHash?: string | null; bridgeVersion?: string | null }
+
+/** Real-path containment keeps documentation lookup inside `root`; failures are nonfatal. */
+export function readablePathWithin(root: string, relative: string): string | null {
+	try {
+		const base = realpathSync(root), real = realpathSync(path.resolve(root, relative));
+		const inside = path.relative(base, real);
+		if (inside && inside !== ".." && !inside.startsWith(`..${path.sep}`) && !path.isAbsolute(inside) && statSync(real).isFile()) {
+			accessSync(real, constants.R_OK);
+			return real;
+		}
+	} catch {
+		// Missing, unreadable or concurrently replaced documentation must not
+		// prevent tool registration or discovery. Do not read manual bodies here.
+	}
+	return null;
+}
+
+export function createDocumentationResolver(root = defaultRoot) {
+	return (name: string, live: LiveEvidence = {}) => {
+		const entry = byName.get(name);
+		const contract = packagedContracts.get(name);
+		const liveHash = live.contractHash ?? null;
+		if (!entry) return {
+			key: name, status: "missing", path: null, packaged_contract_hash: null, live_contract_hash: liveHash,
+			compatibility: liveHash ? "undocumented" : "unknown",
+		};
+		const readablePath = readablePathWithin(root, `${entry.name}.md`);
+		const packagedHash = contract?.contract_hash ?? null;
+		return {
+			key: entry.name, status: readablePath ? "available" : "missing", path: readablePath,
+			revision: documentationRevision, package_version: packageVersion,
+			packaged_contract_hash: packagedHash,
+			live_contract_hash: entry.source === "bridge" ? liveHash : null,
+			observed_bridge_version: entry.source === "bridge" ? live.bridgeVersion ?? null : null,
+			compatibility: entry.source === "native" ? "package_local"
+				: !liveHash ? "unknown"
+				: !packagedHash ? "undocumented"
+				: liveHash === packagedHash ? "contract_match" : "contract_changed",
+		};
+	};
+}
+
+export const resolveToolDocumentation = createDocumentationResolver();

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

@@ -0,0 +1,8 @@
+/** Compose the extension-only retry input after the bridge has added document targeting. */
+export function publicBridgeSchema(parameters: unknown) {
+	const schema = structuredClone(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.",
+	} };
+	return schema;
+}

package/package.json

@@ -1,59 +1,65 @@
-{
-  "name": "pi-revit",
-  "version": "0.3.1",
-  "description": "Native Pi connector for Autodesk Revit. Run npx.cmd -y pi-revit for the full Windows install.",
-  "author": "Ahmad Altahlawi",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Triavision-ai/pi-revit.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Triavision-ai/pi-revit/issues"
-  },
-  "homepage": "https://github.com/Triavision-ai/pi-revit#readme",
-  "keywords": [
-    "pi-package",
-    "pi-extension",
-    "revit",
-    "bim",
-    "autodesk",
-    "revit-api"
-  ],
-  "bin": {
-    "pi-revit": "bin/pi-revit.js"
-  },
-  "scripts": {
-    "deploy": "powershell -ExecutionPolicy Bypass -File scripts/deploy.ps1",
-    "setup": "powershell -ExecutionPolicy Bypass -File scripts/setup-workspace.ps1",
-    "uninstall:revit": "powershell -ExecutionPolicy Bypass -File scripts/uninstall.ps1",
-    "test:search": "dotnet run --project tests/search-engine",
-    "test:installer": "node --test tests/installer/*.test.cjs",
-    "test:sdk": "powershell -NoProfile -ExecutionPolicy Bypass -File tests/installer/sdk.test.ps1"
-  },
-  "files": [
-    "bin/",
-    "extensions/",
-    "skills/",
-    "scripts/",
-    "src/",
-    "workspace/",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "pi": {
-    "extensions": [
-      "./extensions/pi-revit/index.ts"
-    ],
-    "skills": [
-      "./skills"
-    ]
-  },
-  "engines": {
-    "node": ">=20.3"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "typebox": "*"
-  }
-}
+{
+  "name": "pi-revit",
+  "version": "0.5.0",
+  "description": "Native Pi connector for Autodesk Revit. Run npx.cmd -y pi-revit for the full Windows install.",
+  "author": "Ahmad Altahlawi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Triavision-ai/pi-revit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Triavision-ai/pi-revit/issues"
+  },
+  "homepage": "https://github.com/Triavision-ai/pi-revit#readme",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "revit",
+    "bim",
+    "autodesk",
+    "revit-api"
+  ],
+  "bin": {
+    "pi-revit": "bin/pi-revit.js"
+  },
+  "scripts": {
+    "deploy": "powershell -ExecutionPolicy Bypass -File scripts/deploy.ps1",
+    "setup": "powershell -ExecutionPolicy Bypass -File scripts/setup-workspace.ps1",
+    "uninstall:revit": "powershell -ExecutionPolicy Bypass -File scripts/uninstall.ps1",
+    "test:search": "dotnet run --project tests/search-engine",
+    "test:extension": "node scripts/test-extension.mjs",
+    "test:docs": "node scripts/check-tool-documentation.mjs",
+    "test:installer": "node --test tests/installer/*.test.cjs",
+    "test:sdk": "powershell -NoProfile -ExecutionPolicy Bypass -File tests/installer/sdk.test.ps1",
+    "generate:contracts": "node scripts/generate-contracts.mjs",
+    "test:corpus": "node tests/discovery/run-corpus.mjs"
+  },
+  "files": [
+    "bin/",
+    "extensions/",
+    "skills/",
+    "scripts/",
+    "src/",
+    "workspace/",
+    "docs/",
+    "AGENTS.md",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/pi-revit/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "engines": {
+    "node": ">=20.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  }
+}