pi-revit 0.4.0 → 0.5.1

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

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

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

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

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],
+	};
+}