pi-revit 0.2.7 → 0.2.9

package/CHANGELOG.md

@@ -7,6 +7,50 @@ Format follows [Keep a Changelog](https://keepachangelog.com/); version headers
 Every published version gets an entry with **Added** / **Changed** / **Fixed** sections
 describing what the user will notice — not internal refactors.
 
+## [0.2.9] - 2026-07-21
+
+### Added
+- Self-healing tool discovery: when pi starts before Revit, the extension now keeps
+  retrying tool discovery in the background (every 15s) and also re-discovers on a
+  successful `ping` — no more sessions stuck with only `ping` registered until a fresh
+  pi start. When tools arrive mid-session, `ping`'s result says so.
+- `set_parameters` and `execute_csharp` accept an optional `expected_document` (the model
+  title): if the active document differs — e.g. the user switched models mid-session —
+  the write fails cleanly instead of landing in the wrong model.
+- `get_element_details.parameter_names` now also matches language-independent
+  BuiltInParameter enum names (e.g. `ALL_MODEL_MARK`), so filtering works in non-English
+  Revit UIs where display names are localized.
+
+### Fixed
+- `get_element_details` no longer reports a misleading "0 params" when a
+  `parameter_names` filter simply matched nothing — it now reports "N of M params
+  matched parameter_names" so localization misses are visible. (This explains the
+  earlier "0 params vs 38 params" reports: different filter arguments, not flaky reads.)
+- `get_elements`: a display-name filter rule in an **unscoped** query (no category /
+  of_class) is no longer promoted to a pinned collector filter based on a 50-element
+  probe — it stays on the per-element post-scan path, so categories beyond the probe
+  window can't be silently dropped when the same parameter name maps to different ids.
+
+### Changed
+- SKILL.md: guidance on localized parameter names (prefer BuiltInParameter enum names)
+  and on using `expected_document` for long sessions / multiple open models.
+- README: new "Safety model" section stating explicitly what the add-in enforces and
+  that write-confirmation UX is a client-side decision.
+
+Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
+restart Revit).
+
+## [0.2.8] - 2026-07-21
+
+### Fixed
+- `search_api_docs`: overload-targeted queries no longer fail on comma spacing.
+  `Wall.Create(Document,Curve` (no space) and `Wall.Create( Document, Curve` now match the
+  same overloads as `Wall.Create(Document, Curve` — the query's spacing around commas and
+  parentheses is normalized to the rendered signature style before matching.
+
+Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then restart
+Revit).
+
 ## [0.2.7] - 2026-07-21
 
 ### Added

package/README.md

@@ -29,10 +29,32 @@ headless Revit add-in          ← no ribbon, no panels; just a bridge
 Revit API                      ← reads run directly; writes run in one named transaction
 ```
 
-The extension discovers its tools from the bridge at startup (`/reload` re-discovers), so the
-tool list always matches what the add-in serves. Everything between Pi and Revit is
-local-machine only; note that Pi sends conversation context and tool results to your selected
-LLM provider, like any Pi session.
+The extension discovers its tools from the bridge at startup (retrying in the background until
+Revit is up), so the tool list always matches what the add-in serves. Everything between Pi and
+Revit is local-machine only; note that Pi sends conversation context and tool results to your
+selected LLM provider, like any Pi session.
+
+## Safety model
+
+Be deliberate about pointing an LLM at a real project model. The add-in enforces what it can
+enforce mechanically, and is honest about what it cannot:
+
+- Every write tool is flagged `write: true` — that flag is the machine-readable signal a client
+  can gate on. Whether a write needs human confirmation is a **client-side decision**: the
+  add-in cannot know your policy, so confirmation UX belongs in the Pi client/agent layer, not
+  here.
+- All writes run in one named transaction: committed on success, rolled back on failure, always
+  visible in Revit's undo history. Commit-time warnings are reported back (`commitWarnings`);
+  error-severity failures roll back with Revit's failure text.
+- `execute_csharp` is an unrestricted escape hatch by design — scripts have full CLR access.
+  Treat it like giving the agent a macro editor, on a model you have saved or can restore.
+- Blocking popups are auto-answered so Revit can never hang behind a dialog; unrecognized
+  dialogs get the dismissive answer (Cancel/Close/No), never a blind OK.
+- Writes accept an optional `expected_document` check so a queued write cannot silently land in
+  a different model than intended.
+
+Practical advice: work on saved models, keep worksharing backups/central protection as usual,
+and review the agent's summary of what changed after any write session.
 
 ## Requirements
 

package/extensions/pi-revit/index.ts

@@ -275,7 +275,7 @@ async function announceUpdateOnce(notify: (message: string, level: "info") => vo
 	}
 }
 
-function registerPing(pi: ExtensionAPI) {
+function registerPing(pi: ExtensionAPI, onBridgeAlive?: () => Promise<"ready" | "registered" | "failed">) {
 	pi.registerTool({
 		name: "ping",
 		label: "Ping Revit Bridge",
@@ -287,18 +287,71 @@ function registerPing(pi: ExtensionAPI) {
 		async execute(_toolCallId, _params, signal) {
 			const payload = await bridgeRequest("/ping", { method: "GET" }, 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.
+			let registrationNote = "";
+			if (onBridgeAlive) {
+				const state = await onBridgeAlive();
+				if (state === "registered")
+					registrationNote = "\nNOTE: The Revit bridge tools (get_elements, set_parameters, execute_csharp, ...) were just registered in this session and are available from now on.";
+				else if (state === "failed")
+					registrationNote = "\nNOTE: Bridge tool discovery failed even though ping succeeded; retry ping or restart pi.";
+			}
 			return {
-				content: [{ type: "text", text: JSON.stringify(payload) + (warning ? `\nWARNING: ${warning}` : "") }],
+				content: [{ type: "text", text: JSON.stringify(payload) + (warning ? `\nWARNING: ${warning}` : "") + registrationNote }],
 				details: payload,
 			};
 		},
 	});
 }
 
+const REDISCOVERY_INTERVAL_MS = 15_000;
+
 export default async function revitConnector(pi: ExtensionAPI) {
+	// 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> {
+		if (bridgeToolsRegistered) return true;
+		if (discoveryInFlight) return discoveryInFlight;
+		discoveryInFlight = (async () => {
+			try {
+				const payload = (await bridgeRequest("/tools", { method: "GET" }, undefined, DISCOVERY_TIMEOUT_MS)) as {
+					tools?: BridgeToolDescriptor[];
+				};
+				const descriptors = Array.isArray(payload?.tools) ? payload.tools : [];
+				if (descriptors.length === 0) return false;
+				for (const descriptor of descriptors) {
+					if (!descriptor || typeof descriptor.name !== "string" || !descriptor.name) continue;
+					if (descriptor.name === "ping") continue;
+					registerBridgeTool(pi, descriptor);
+				}
+				bridgeToolsRegistered = true;
+				return true;
+			} catch {
+				// Bridge down (Revit closed, still starting, stale bridge.json):
+				// stay on ping only and try again later.
+				return false;
+			} finally {
+				discoveryInFlight = null;
+			}
+		})();
+		return discoveryInFlight;
+	}
+
 	// ping is hard-coded: it must work (and report clearly) even when the
-	// bridge is down, so it is never part of /tools discovery.
-	registerPing(pi);
+	// 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 () => {
+		if (bridgeToolsRegistered) return "ready";
+		return (await discoverAndRegister()) ? "registered" : "failed";
+	});
 
 	// Surface an incomplete update (see versionMismatch) once per session, right
 	// where the user lands after running `pi update --extensions`. Bridge down at
@@ -314,21 +367,12 @@ export default async function revitConnector(pi: ExtensionAPI) {
 		}
 	});
 
-	let descriptors: BridgeToolDescriptor[];
-	try {
-		const payload = (await bridgeRequest("/tools", { method: "GET" }, undefined, DISCOVERY_TIMEOUT_MS)) as {
-			tools?: BridgeToolDescriptor[];
-		};
-		descriptors = Array.isArray(payload?.tools) ? payload.tools : [];
-	} catch {
-		// Bridge down at startup (Revit closed, stale bridge.json, ...): keep
-		// only ping registered and never block pi startup. /reload re-discovers.
-		return;
-	}
+	if (await discoverAndRegister()) return;
 
-	for (const descriptor of descriptors) {
-		if (!descriptor || typeof descriptor.name !== "string" || !descriptor.name) continue;
-		if (descriptor.name === "ping") continue;
-		registerBridgeTool(pi, descriptor);
-	}
+	// 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()) clearInterval(timer);
+	}, REDISCOVERY_INTERVAL_MS);
+	timer.unref?.();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-revit",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Native Pi connector for Autodesk Revit. Run npx.cmd -y pi-revit for the full Windows install.",
   "author": "Ahmad Altahlawi",
   "license": "MIT",

package/scripts/setup-workspace.ps1

@@ -1,80 +1,80 @@
-#Requires -Version 5.1
-<#
-Sets up the pi-revit user environment on this PC:
-
-  1. Workspace at Documents\pi-revit (AGENTS.md conventions, Models\ output tree,
-     double-click launcher). An existing AGENTS.md is never overwritten.
-  2. Global `pi-revit` command installed next to the `pi` command, so any terminal can run:
-       pi-revit              -> Pi in the workspace
-       pi-revit -c           -> continue the last session
-     Model output sorts itself: the Revit tools file each export under
-     Models\<model title>\ automatically, keyed by the document it came from.
-
-Idempotent — safe to re-run. Usage:
-  scripts\setup-workspace.ps1
-  scripts\setup-workspace.ps1 -WorkspaceDir "D:\work\pi-revit"
-#>
-param(
-    [string]$WorkspaceDir = (Join-Path ([Environment]::GetFolderPath('MyDocuments')) 'pi-revit')
-)
-
-$ErrorActionPreference = 'Stop'
-$templates = Join-Path (Split-Path $PSScriptRoot -Parent) 'workspace'
-
-# 1. Workspace folders. Models\ is where the Revit tools file per-model output.
-New-Item -ItemType Directory -Force -Path (Join-Path $WorkspaceDir 'Models') | Out-Null
-
-# Conventions / notes: copy only when missing so user edits survive re-runs.
-$workspaceAgents = Join-Path $WorkspaceDir 'AGENTS.md'
-if (-not (Test-Path $workspaceAgents)) {
-    Copy-Item (Join-Path $templates 'AGENTS.md') $workspaceAgents
-}
-
-# Launcher is code, not user data: always refresh.
-Copy-Item (Join-Path $templates 'pi-revit-here.cmd') (Join-Path $WorkspaceDir 'pi-revit.cmd') -Force
-
-Write-Host "Workspace ready: $WorkspaceDir" -ForegroundColor Green
-
-# 2. Global pi-revit command next to pi (that directory is on PATH by definition).
-#    The template's workspace path is rewritten to honor -WorkspaceDir.
-#    Under `npx pi-revit`, npx prepends its ephemeral cache's node_modules\.bin to
-#    PATH, and that folder holds a pi shim pulled in via peerDependencies. A launcher
-#    written next to that shim lands in a folder that is neither on the user's own
-#    PATH nor long-lived, so skip pi entries inside this package's node_modules tree
-#    or any npx cache and use the user's permanent pi instead.
-function Get-PermanentPiCommand {
-    # Long-form both sides of the prefix comparison: PATH entries may carry 8.3
-    # short names (AHMAD~1.TAH) while $PSScriptRoot is normalized, and a form
-    # mismatch would silently defeat the own-tree exclusion.
-    function Resolve-LongPath([string]$p) {
-        try { (Get-Item -LiteralPath $p -ErrorAction Stop).FullName } catch { $p }
-    }
-    $ownTree = $null
-    $repoRoot = Resolve-LongPath (Split-Path $PSScriptRoot -Parent)
-    $idx = $repoRoot.LastIndexOf('\node_modules\', [StringComparison]::OrdinalIgnoreCase)
-    if ($idx -ge 0) { $ownTree = $repoRoot.Substring(0, $idx + '\node_modules\'.Length) }
-    Get-Command pi -All -ErrorAction SilentlyContinue | Where-Object {
-        if (-not $_.Source) { return $false }
-        $src = Resolve-LongPath $_.Source
-        ($src -notmatch '\\_npx\\') -and
-        (-not $ownTree -or -not $src.StartsWith($ownTree, [StringComparison]::OrdinalIgnoreCase))
-    } | Select-Object -First 1
-}
-
-$pi = Get-PermanentPiCommand
-if ($pi) {
-    $binDir = Split-Path $pi.Source -Parent
-    # Literal line swap (no regex): the workspace path may contain characters
-    # like $ that a -replace replacement string would misinterpret.
-    $globalCmd = Get-Content (Join-Path $templates 'pi-revit-global.cmd') | ForEach-Object {
-        if ($_ -like 'set "WORKSPACE=*') { 'set "WORKSPACE=' + $WorkspaceDir + '"' } else { $_ }
-    }
-    # cmd.exe parses .cmd files in the console's OEM code page: write the launcher
-    # in that encoding so workspace paths with non-ASCII characters (user names,
-    # localized folder names) stay intact.
-    Set-Content -Path (Join-Path $binDir 'pi-revit.cmd') -Value $globalCmd -Encoding Oem
-    Write-Host "Global command installed: $(Join-Path $binDir 'pi-revit.cmd')" -ForegroundColor Green
-    Write-Host 'Run pi-revit from any terminal (pi-revit -c continues the last session).'
-} else {
-    Write-Warning 'No permanent pi command found on PATH. Install Pi first (npm install -g --ignore-scripts @earendil-works/pi-coding-agent), then run npx.cmd -y pi-revit again (or re-run this script) to get the global pi-revit command.'
-}
+#Requires -Version 5.1
+<#
+Sets up the pi-revit user environment on this PC:
+
+  1. Workspace at Documents\pi-revit (AGENTS.md conventions, Models\ output tree,
+     double-click launcher). An existing AGENTS.md is never overwritten.
+  2. Global `pi-revit` command installed next to the `pi` command, so any terminal can run:
+       pi-revit              -> Pi in the workspace
+       pi-revit -c           -> continue the last session
+     Model output sorts itself: the Revit tools file each export under
+     Models\<model title>\ automatically, keyed by the document it came from.
+
+Idempotent — safe to re-run. Usage:
+  scripts\setup-workspace.ps1
+  scripts\setup-workspace.ps1 -WorkspaceDir "D:\work\pi-revit"
+#>
+param(
+    [string]$WorkspaceDir = (Join-Path ([Environment]::GetFolderPath('MyDocuments')) 'pi-revit')
+)
+
+$ErrorActionPreference = 'Stop'
+$templates = Join-Path (Split-Path $PSScriptRoot -Parent) 'workspace'
+
+# 1. Workspace folders. Models\ is where the Revit tools file per-model output.
+New-Item -ItemType Directory -Force -Path (Join-Path $WorkspaceDir 'Models') | Out-Null
+
+# Conventions / notes: copy only when missing so user edits survive re-runs.
+$workspaceAgents = Join-Path $WorkspaceDir 'AGENTS.md'
+if (-not (Test-Path $workspaceAgents)) {
+    Copy-Item (Join-Path $templates 'AGENTS.md') $workspaceAgents
+}
+
+# Launcher is code, not user data: always refresh.
+Copy-Item (Join-Path $templates 'pi-revit-here.cmd') (Join-Path $WorkspaceDir 'pi-revit.cmd') -Force
+
+Write-Host "Workspace ready: $WorkspaceDir" -ForegroundColor Green
+
+# 2. Global pi-revit command next to pi (that directory is on PATH by definition).
+#    The template's workspace path is rewritten to honor -WorkspaceDir.
+#    Under `npx pi-revit`, npx prepends its ephemeral cache's node_modules\.bin to
+#    PATH, and that folder holds a pi shim pulled in via peerDependencies. A launcher
+#    written next to that shim lands in a folder that is neither on the user's own
+#    PATH nor long-lived, so skip pi entries inside this package's node_modules tree
+#    or any npx cache and use the user's permanent pi instead.
+function Get-PermanentPiCommand {
+    # Long-form both sides of the prefix comparison: PATH entries may carry 8.3
+    # short names (SOMEUS~1.NAM) while $PSScriptRoot is normalized, and a form
+    # mismatch would silently defeat the own-tree exclusion.
+    function Resolve-LongPath([string]$p) {
+        try { (Get-Item -LiteralPath $p -ErrorAction Stop).FullName } catch { $p }
+    }
+    $ownTree = $null
+    $repoRoot = Resolve-LongPath (Split-Path $PSScriptRoot -Parent)
+    $idx = $repoRoot.LastIndexOf('\node_modules\', [StringComparison]::OrdinalIgnoreCase)
+    if ($idx -ge 0) { $ownTree = $repoRoot.Substring(0, $idx + '\node_modules\'.Length) }
+    Get-Command pi -All -ErrorAction SilentlyContinue | Where-Object {
+        if (-not $_.Source) { return $false }
+        $src = Resolve-LongPath $_.Source
+        ($src -notmatch '\\_npx\\') -and
+        (-not $ownTree -or -not $src.StartsWith($ownTree, [StringComparison]::OrdinalIgnoreCase))
+    } | Select-Object -First 1
+}
+
+$pi = Get-PermanentPiCommand
+if ($pi) {
+    $binDir = Split-Path $pi.Source -Parent
+    # Literal line swap (no regex): the workspace path may contain characters
+    # like $ that a -replace replacement string would misinterpret.
+    $globalCmd = Get-Content (Join-Path $templates 'pi-revit-global.cmd') | ForEach-Object {
+        if ($_ -like 'set "WORKSPACE=*') { 'set "WORKSPACE=' + $WorkspaceDir + '"' } else { $_ }
+    }
+    # cmd.exe parses .cmd files in the console's OEM code page: write the launcher
+    # in that encoding so workspace paths with non-ASCII characters (user names,
+    # localized folder names) stay intact.
+    Set-Content -Path (Join-Path $binDir 'pi-revit.cmd') -Value $globalCmd -Encoding Oem
+    Write-Host "Global command installed: $(Join-Path $binDir 'pi-revit.cmd')" -ForegroundColor Green
+    Write-Host 'Run pi-revit from any terminal (pi-revit -c continues the last session).'
+} else {
+    Write-Warning 'No permanent pi command found on PATH. Install Pi first (npm install -g --ignore-scripts @earendil-works/pi-coding-agent), then run npx.cmd -y pi-revit again (or re-run this script) to get the global pi-revit command.'
+}