pi-revit 0.2.18 → 0.3.1

package/CHANGELOG.md

@@ -5,9 +5,48 @@ Format follows [Keep a Changelog](https://keepachangelog.com/); version headers
 `## [x.y.z] - YYYY-MM-DD` so tooling (and Pi's changelog parser format) can read them.
 
 Every published version gets an entry with **Added** / **Changed** / **Fixed** sections
-describing what the user will notice — not internal refactors.
-
-## [0.2.18] - 2026-08-21
+describing what the user will notice — not internal refactors.
+
+## [0.3.1] - 2026-09-16
+
+### Fixed
+
+- The installer checks the selected .NET SDK before installing packages or building the add-in. Missing or older SDKs now produce a clear explanation, the matching Windows x64 SDK download link, and retry instructions. Interactive installs offer to open the download page. Manual builds and deployments also check the SDK before compiling.
+
+## [0.3.0] - 2026-09-09
+
+### Added
+
+- `read_revit_result` retrieves complete large tool results in bounded fragments.
+  Result IDs belong to the current Pi extension session; saved files remain
+  readable by path while available.
+
+### Changed
+
+- **Breaking:** writes and UI mutations require `expected_document_id` from
+  `get_model_overview`'s `project.documentId`. Refresh it after close/reopen or
+  bridge restart. A legacy title alone is insufficient; supplied IDs on reads
+  are also checked.
+- Default export folders include a model-identity hash, separating same-title
+  models. Existing folders remain untouched; explicit output directories work
+  as before.
+
+### Fixed
+
+- Requested values and all returned rows reach Pi instead of only UI/debug
+  details. Large-result retrieval preserves each tool's pagination and limits.
+- Scoped display-name filters resolve each element's parameter, including
+  matches beyond the first 50 elements; explicit built-in/GUID filters stay optimized.
+- Type-only parameter requests work independently of instance-parameter inclusion.
+- Transaction results distinguish confirmed commit/rollback from incomplete
+  cleanup. Failure handling follows the transaction lifecycle; UI and export
+  errors disclose effects or files already produced.
+
+Update both the Pi package and Revit add-in with Revit closed, then restart Revit
+and start a fresh Pi session. Live verification covered bounded workflows on
+Revit 2025.4.3; Revit 2026/2027 were not tested for this release.
+
+## [0.2.18] - 2026-08-21
 
 ### Fixed
 - When pi starts before Revit and the background rediscovery timer (rather than a `ping`

package/README.md

@@ -1,17 +1,17 @@
 # pi-revit
 
 Native Revit tools for [Pi](https://pi.dev) — ask about, query, script, and modify the open
-Autodesk Revit model from your terminal.
-
+Autodesk Revit model from your terminal.
+
 ```text
 You: how many levels in the model?
 Pi:  calls get_model_overview → "There are 14 levels in the Revit model."
 
 You: select all structural columns
-Pi:  get_elements → manage_selection → "Selected 222 structural columns."
+Pi:  get_model_overview → get_elements → manage_selection → "Selected 222 structural columns."
 
 You: rename level 'L1' to 'Ground Floor'
-Pi:  calls set_parameters → "Done — Level 'L1' is now 'Ground Floor'."
+Pi:  get_model_overview → set_parameters → "Done — Level 'L1' is now 'Ground Floor'."
 ```
 
 ## How it works
@@ -26,7 +26,7 @@ localhost HTTP bridge          ← per-start token; connection info in %APPDATA%
 headless Revit add-in          ← no ribbon, no panels; just a bridge
    │  ExternalEvent queue (Revit API thread)
    ▼
-Revit API                      ← reads run directly; writes run in one named transaction
+Revit API                      ← tool-owned model transactions; separate UI/file effects
 ```
 
 The extension discovers its tools from the bridge at startup (retrying in the background until
@@ -39,19 +39,51 @@ selected LLM provider, like any Pi session.
 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.
+- Tool metadata describes its classification; UI actions such as selection and view
+  activation can change state even when `write` is false. Confirmation policy belongs
+  to the client. Exact document targeting is enforced separately as described below.
+- Parameter writes, C# scripts, temporary isolation, and IFC export own named Revit
+  transactions. Failure handling is attached after transaction start, and results
+  check transaction outcomes before claiming commit or rollback. `set_parameters`
+  can commit a partially successful batch; inspect every failed update and
+  `commitWarnings`. An unconfirmed rollback is reported as such.
 - `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.
+- `execute_csharp` has a dialog guard that attempts dismissive responses to dialogs
+  raised while the script runs. It does not establish that every Revit dialog or
+  failure mode can be handled automatically.
+- A model transaction does not undo filesystem output or earlier selection/zoom
+  changes. A failed export can leave incomplete files; its error reports the output
+  location and observed changed files. An isolation failure reports any earlier
+  selection action that already completed.
+
+### Target the exact open document
+
+Call `get_model_overview` for the intended model and copy `project.documentId`
+unchanged into `expected_document_id` on subsequent operations:
+
+```json
+{
+  "expected_document_id": "<project.documentId from the current overview>",
+  "updates": [{ "element_id": 12345, "parameter": "ALL_MODEL_INSTANCE_COMMENTS", "value": "Reviewed" }]
+}
+```
+
+Replace the placeholders with the current document ID and an actual element ID.
+The exact ID is required for `set_parameters`, `execute_csharp`,
+`export_documents`, and `open_view`. It is also required for selection/zoom
+changes and any `manage_selection` call with `isolate_in_view: true`, including
+action `get`. Pure reads may omit it; a supplied ID is always checked.
+
+The identity represents one currently open native document in one loaded bridge
+session. It is not a persistent project ID, path, export-folder key, or credential.
+Closing/reopening the document or restarting the bridge invalidates prior IDs.
+Read the intended document's overview again after those transitions. The guard
+checks the actual target on Revit's API thread immediately before execution.
+
+Legacy `expected_document` titles remain an optional additional sanity check.
+A title alone no longer satisfies the required guard, even when it matches.
+Clients must refresh discovery and supply the new field after upgrading to 0.3.0.
 
 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.
@@ -75,9 +107,18 @@ npx.cmd -y pi-revit
 ```
 
 This installs the Pi package, builds and deploys the Revit bridge add-in, creates the
-`Documents\pi-revit` workspace, and installs the global `pi-revit` command.
-
-Start Revit (click **Always Load** on the unsigned add-in prompt once) and open any
+`Documents\pi-revit` workspace, and installs the global `pi-revit` command.
+
+The installer first checks the selected .NET SDK. If it is missing or too old,
+installation stops with the required version, a download link, and retry steps.
+Interactive terminals also offer to open the download page. Revit uses a runtime
+to run; compiling this add-in also needs the SDK. For Revit 2027, install the
+[.NET 10 SDK for Windows x64](https://dotnet.microsoft.com/en-us/download/dotnet/10.0),
+reopen PowerShell, and rerun the installer. Existing .NET versions can stay installed.
+If an older SDK is still selected, check `dotnet --list-sdks`, your `PATH`, and any
+`global.json` in the current directory or its parents.
+
+Start Revit (click **Always Load** on the unsigned add-in prompt once) and open any
 project. No panel or ribbon appears — the add-in is headless.
 
 ### Manual npm install
@@ -114,10 +155,19 @@ git clone https://github.com/Triavision-ai/pi-revit.git
 cd pi-revit
 powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1
 pi install ./
-powershell -ExecutionPolicy Bypass -File scripts\setup-workspace.ps1
-```
-
-## Use it
+powershell -ExecutionPolicy Bypass -File scripts\setup-workspace.ps1
+```
+
+### Upgrading to 0.3.0
+
+**Breaking change:** writes and UI mutations now require `expected_document_id`.
+Close Revit, update the Pi package and redeploy the add-in using the installation
+steps above, then restart Revit and start a fresh Pi session. Both components must
+be updated. Call `get_model_overview` and copy `project.documentId` into subsequent
+mutating calls; a legacy `expected_document` title alone is insufficient. Refresh
+the ID after closing/reopening a document or restarting Revit.
+
+## Use it
 
 Open **any terminal** — PowerShell, CMD, or Windows Terminal — and type:
 
@@ -141,12 +191,18 @@ automatically and all Revit session history lives in one predictable place (`pi-
 continues the last session). The Revit tools themselves are installed globally in Pi, and the
 extension discovers them live from the bridge inside Revit each time a session starts.
 
-**Per model, automatically:** files sort themselves. Exports land in
-`Documents\pi-revit\Models\<model title>\exports` — the add-in derives the folder from the
-document being exported, so even a session that touches many models files every output under
-the right one, with no naming decision from you or the AI. Each model folder carries a
-`model.txt` recording the model's GUID and file path, so two models that share a title stay
-distinguishable.
+**Per model, automatically:** files sort themselves. Exports land in
+`Documents\pi-revit\Models\<model title>--<identity hash>\exports`. The suffix derives
+from the normalized saved-file path, cloud region/project/model identity, or Revit
+Server path. Distinct saved paths therefore use different destinations even when
+their titles or inherited project IDs match. Save As to another path selects a new
+destination. Unsaved models or unavailable persistent identities use a token stable
+only for that open document; their destination may change after reopening.
+
+`model.txt` records the identity used. Existing title-only directories remain
+untouched; upgrading does not migrate or merge old exports. An explicit
+`output_dir` still overrides the default. File attribution uses a directory
+snapshot, so avoid unrelated concurrent writers in a shared output directory.
 
 Plain `pi` from any folder also works; `pi-revit` just adds the right working folder on top.
 
@@ -165,19 +221,58 @@ Plain `pi` from any folder also works; `pi-revit` just adds the right working fo
 | `search_api_docs` | Search the offline Revit API docs (works with no document open) |
 | `execute_csharp` | Run a C# script in one auto-managed transaction — the escape hatch |
 | `capture_view` | PNG snapshot of a view to a temp file (read the returned path to see it) |
-| `export_documents` | PDF/DWG/PNG/IFC export of sheets and views — auto-sorted into `Models\<model>\exports` |
-| `get_model_health` | Warnings grouped + worksets, phases, design options audit |
+| `export_documents` | PDF/DWG/PNG/IFC export of sheets and views — sorted into `Models\<title>--<identity hash>\exports` |
+| `get_model_health` | Warnings grouped + worksets, phases, design options audit |
+| `read_revit_result` | Read bounded fragments of a saved large tool result; extension-only, no Revit call |
+
+### Read complete results
+
+Requested rows and parameter values are included in model-visible tool content.
+Results up to 12,000 characters are complete inline. For a larger result, the Pi
+extension saves the complete tool payload as UTF-8 JSON and returns `result_id`,
+`file_path`, `total_chars`, `complete_inline: false`, and retrieval instructions.
+
+Call `read_revit_result` with the returned ID and `offset: 0`, then follow each
+`next_offset` until `has_more` is false. A requested fragment is at most 8,000
+UTF-16 code units; it may be smaller so the escaped response stays within the
+message limit. Concatenate each page's `text` in order. Individual fragments are
+not standalone JSON objects from the original result. Use the returned offsets,
+not byte counts or a guessed increment.
+
+Result IDs are registered in memory by the current extension instance. After an
+extension reload or new Pi process, an old ID may no longer resolve; use the
+original absolute `file_path` with Pi's normal `read` tool while that file remains
+available. Saved results live in a unique OS temporary directory, can contain
+model data, and are subject to eventual OS/user cleanup. If saving fails after
+Revit completed an operation, inspect actual model state before retrying a write.
+
+Complete payload retrieval does not expand a tool's own query page or declared
+limits. Continue `get_elements`/`get_element_types` pagination separately, and
+check warning-group or projection truncation indicators. A bridge-only client
+must consume `details.payload` for oversized results; `read_revit_result` belongs
+to the Pi extension.
+
+Display-name parameter filters now resolve on every element, including inside a
+category/class scope. Explicit built-in IDs and shared GUIDs can retain collector
+optimization. In `get_element_details`, `include.parameters` and
+`include.type_parameters` are independent; disabling instance parameters still
+allows a type-only result.
 
 ## Limitations — read before using on real projects
 
 - **Write tools are unrestricted by design.** `set_parameters` and `execute_csharp` modify the
   open model directly — there is no confirmation prompt and no sandbox. Writes run in named
-  transactions, undoable with Ctrl+Z in Revit (`execute_csharp` rolls back entirely on any
-  error; `set_parameters` commits partial successes and reports each failure), but the model is
-  yours to protect: test on copies, keep backups, read the result's `failed` lists.
+  transactions (`execute_csharp` attempts rollback after script failure;
+  `set_parameters` commits partial successes and reports each failure). Read the
+  actual transaction outcome and failed lists. Script result-projection failure
+  can leave a successful edit committed with a `returnValueError`; filesystem and
+  UI effects are separate from model rollback.
 - The add-in multi-targets .NET 8 (Revit 2025/2026) and .NET 10 (Revit 2027); `deploy.ps1`
   auto-detects the Revit versions you have installed and builds only the matching framework(s),
-  so you only need the SDK for the Revit you run. Verified on Revit 2025 and 2027.
+  so you only need the SDK for the Revit you run. The 0.3.0 changes were tested live
+  on Revit 2025.4.3 (build 25.4.30.30, German UI). Revit 2026/2027 and large-model
+  performance were not tested for this release. Export API/file checks do not
+  establish full DWG drawing or IFC schema/geometry validation.
 - **One Revit instance at a time** is discoverable (last started wins). When that instance
   closes or crashes, another one that is still running takes the slot over within 30s.
 - A tool call that outlives its timeout is abandoned client-side but may still complete inside

package/bin/pi-revit.js

@@ -1,13 +1,15 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 const { spawnSync } = require("node:child_process");
 const fs = require("node:fs");
 const path = require("node:path");
 
-const root = path.resolve(__dirname, "..");
-const scriptsDir = path.join(root, "scripts");
+const root = path.resolve(__dirname, "..");
+const scriptsDir = path.join(root, "scripts");
+const packageVersion = require(path.join(root, "package.json")).version;
+const packageSpec = `npm:pi-revit@${packageVersion}`;
 
 function usage() {
-	console.log(`pi-revit installer\n\nUsage:\n  npx.cmd -y pi-revit\n\nWhat it does on Windows:\n  1. Runs: pi install npm:pi-revit\n  2. Builds and deploys the Revit bridge add-in\n  3. Creates the Documents\\pi-revit workspace and global pi-revit command\n\nClose Revit before running. Revit 2025, 2026, or 2027 and the matching .NET SDK are required.`);
+	console.log(`pi-revit installer\n\nUsage:\n  npx.cmd -y pi-revit\n\nWhat it does on Windows:\n  1. Runs: pi install ${packageSpec}\n  2. Builds and deploys the matching Revit bridge add-in\n  3. Creates the Documents\\pi-revit workspace and global pi-revit command\n\nClose Revit before running. Revit 2025, 2026, or 2027 and the matching .NET SDK are required.`);
 }
 
 function fail(message) {
@@ -35,10 +37,10 @@ function runCmd(title, commandLine) {
 	if (result.status !== 0) process.exit(result.status ?? 1);
 }
 
-function runPowerShellScript(scriptName) {
+function runPowerShellScript(scriptName, args = []) {
 	const scriptPath = path.join(scriptsDir, scriptName);
 	if (!fs.existsSync(scriptPath)) fail(`missing script: ${scriptPath}`);
-	run(scriptName, "powershell.exe", ["-ExecutionPolicy", "Bypass", "-File", scriptPath]);
+	run(scriptName, "powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", scriptPath, ...args]);
 }
 
 function revitIsRunning() {
@@ -72,9 +74,7 @@ if (!commandExists("pi")) {
 	fail("the 'pi' command was not found on PATH. Install Pi first: npm install -g --ignore-scripts @earendil-works/pi-coding-agent");
 }
 
-if (!commandExists("dotnet")) {
-	fail("the 'dotnet' command was not found on PATH. Install the .NET SDK required by your Revit version.");
-}
+runPowerShellScript("deploy.ps1", ["-CheckOnly", "-OfferDownload"]);
 
 if (revitIsRunning()) {
 	waitForEnter();
@@ -84,7 +84,7 @@ if (revitIsRunning()) {
 console.log("pi-revit full installer");
 console.log("This installs the Pi package, deploys the Revit add-in, and creates the workspace/global command.");
 
-runCmd("Install the Pi package from npm", "pi install npm:pi-revit");
+runCmd("Install the matching Pi package from npm", `pi install ${packageSpec}`);
 runPowerShellScript("deploy.ps1");
 runPowerShellScript("setup-workspace.ps1");
 

package/extensions/pi-revit/index.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type, type TSchema } from "typebox";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -48,6 +49,12 @@ const DEFAULT_TIMEOUT_MS = 30_000;
 const LONG_TIMEOUT_MS = 120_000;
 const DISCOVERY_TIMEOUT_MS = 10_000;
 const MAX_MODEL_CONTENT_CHARS = 12_000;
+const MAX_RESULT_PAGE_CHARS = 8_000;
+
+// IDs only resolve results created by this extension instance. A caller cannot
+// turn read_revit_result into an arbitrary filesystem read by supplying a path.
+const savedResults = new Map<string, string>();
+let resultDirectory: Promise<string> | undefined;
 
 /** Tools with a longer budget; everything else gets DEFAULT_TIMEOUT_MS. The same
  * value is sent to the bridge as timeout_ms and used client-side via AbortSignal. */
@@ -155,10 +162,87 @@ export async function bridgeRequest(
 
 export function capText(text: string): string {
 	if (text.length <= MAX_MODEL_CONTENT_CHARS) return text;
-	const suffix = `... [truncated at ${MAX_MODEL_CONTENT_CHARS} chars; full payload is in details]`;
+	const suffix = `... [truncated preview at ${MAX_MODEL_CONTENT_CHARS} chars]`;
 	return text.slice(0, Math.max(0, MAX_MODEL_CONTENT_CHARS - suffix.length)) + suffix;
 }
 
+async function modelContent(name: string, payload: BridgeToolResponse): Promise<{ type: "text"; text: string }[]> {
+	const details = payload.details;
+	const value = details !== null && typeof details === "object" && Object.hasOwn(details, "payload")
+		? (details as { payload: unknown }).payload
+		: details;
+	// Current and older bridges both carry the full value in details.payload.
+	// Pi sends content to the model; details alone is only available to its UI.
+	const text = details !== undefined
+		? JSON.stringify(value, null, 2) ?? "null"
+		: payload.content?.map((block) => block.text).join("\n") ?? "{}";
+	if (text.length <= MAX_MODEL_CONTENT_CHARS) return [{ type: "text", text }];
+
+	const resultId = randomUUID();
+	let filePath: string;
+	try {
+		const directory = await (resultDirectory ??= mkdtemp(path.join(os.tmpdir(), "pi-revit-results-")).catch((error) => {
+			// A transient failure must not poison every later large result in this session.
+			resultDirectory = undefined;
+			throw error;
+		}));
+		filePath = path.join(directory, `${resultId}.json`);
+		await writeFile(filePath, text, { encoding: "utf8", flag: "wx", mode: 0o600 });
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new Error(`Revit completed '${name}', but its large result could not be saved locally: ${reason}. Verify model state before retrying a write.`);
+	}
+	savedResults.set(resultId, filePath);
+	return [{ type: "text", text: JSON.stringify({
+		result_id: resultId,
+		file_path: filePath,
+		total_chars: text.length,
+		complete_inline: false,
+		retrieval: { tool: "read_revit_result", result_id: resultId, offset: 0, limit: MAX_RESULT_PAGE_CHARS },
+		instructions: "The complete result is saved locally. Call read_revit_result, then follow next_offset until has_more is false. Each page is a fragment of the saved text, not a standalone result. Offsets count UTF-16 code units. The absolute file can also be opened with read; it remains available after an extension reload, when this session's result ID may no longer resolve.",
+	}) }];
+}
+
+function registerResultReader(pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "read_revit_result",
+		label: "Read Saved Revit Result",
+		description: "Read a bounded fragment of a large Revit tool result using its opaque result_id. This reads a saved local result and does not contact Revit. Follow next_offset until has_more is false; text fragments concatenate to the complete saved result. Offsets count UTF-16 code units.",
+		parameters: Type.Object({
+			result_id: Type.String({ description: "Opaque result_id returned by a Revit tool in this extension session." }),
+			offset: Type.Optional(Type.Integer({ minimum: 0, description: "Character offset from the previous page's next_offset; default 0." })),
+			limit: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_RESULT_PAGE_CHARS, description: "Maximum characters to return; default 8000. Escaping may require a smaller fragment." })),
+		}),
+		executionMode: "sequential",
+		async execute(_toolCallId, params) {
+			const offset = params.offset ?? 0;
+			const limit = params.limit ?? MAX_RESULT_PAGE_CHARS;
+			if (!Number.isSafeInteger(offset) || offset < 0) throw new Error("offset must be a non-negative integer.");
+			if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_RESULT_PAGE_CHARS)
+				throw new Error(`limit must be an integer from 1 to ${MAX_RESULT_PAGE_CHARS}.`);
+			const filePath = savedResults.get(params.result_id);
+			if (!filePath) throw new Error("Unknown result_id for this extension session. Use the original result's file_path with read if the extension was reloaded.");
+			const text = await readFile(filePath, "utf8");
+			if (offset > text.length) throw new Error(`offset exceeds this result's ${text.length} characters.`);
+			const encode = (count: number) => JSON.stringify({
+				result_id: params.result_id, offset, returned_chars: count, total_chars: text.length,
+				has_more: offset + count < text.length,
+				next_offset: offset + count < text.length ? offset + count : null,
+				fragment: true, text: text.slice(offset, offset + count),
+			});
+			// Bound the actual model message, including JSON escaping and metadata.
+			let low = 0;
+			let high = Math.min(limit, text.length - offset);
+			while (low < high) {
+				const count = Math.ceil((low + high) / 2);
+				if (encode(count).length <= MAX_MODEL_CONTENT_CHARS) low = count;
+				else high = count - 1;
+			}
+			return { content: [{ type: "text", text: encode(low) }], details: { filePath } };
+		},
+	});
+}
+
 async function runBridgeTool(name: string, args: unknown, signal: AbortSignal | undefined, timeoutMs: number) {
 	const payload = (await bridgeRequest(
 		`/tools/${encodeURIComponent(name)}/execute`,
@@ -171,14 +255,7 @@ async function runBridgeTool(name: string, args: unknown, signal: AbortSignal |
 		timeoutMs,
 	)) as BridgeToolResponse;
 
-	const content =
-		Array.isArray(payload.content) && payload.content.length > 0
-			? payload.content.map((block) =>
-					typeof block.text === "string" ? { ...block, text: capText(block.text) } : block,
-				)
-			: [{ type: "text", text: capText(JSON.stringify(payload.details ?? {})) }];
-
-	return { content, details: payload.details };
+	return { content: await modelContent(name, payload), details: payload.details };
 }
 
 function registerBridgeTool(pi: ExtensionAPI, descriptor: BridgeToolDescriptor) {
@@ -308,6 +385,7 @@ function registerPing(pi: ExtensionAPI, onBridgeAlive?: () => Promise<"ready" |
 const REDISCOVERY_INTERVAL_MS = 15_000;
 
 export default async function revitConnector(pi: ExtensionAPI) {
+	registerResultReader(pi);
 	// 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
@@ -328,7 +406,7 @@ export default async function revitConnector(pi: ExtensionAPI) {
 				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;
+					if (descriptor.name === "ping" || descriptor.name === "read_revit_result") continue;
 					registerBridgeTool(pi, descriptor);
 				}
 				bridgeToolsRegistered = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-revit",
-  "version": "0.2.18",
+  "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",
@@ -27,7 +27,9 @@
     "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: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/",

package/scripts/build.ps1

@@ -17,9 +17,15 @@ param(
 )
 
 $ErrorActionPreference = 'Stop'
-$project = Join-Path $PSScriptRoot '..\src\Revit\RevitBridge.csproj'
-
-$buildArgs = @('build', $project, '-c', $Configuration)
+$project = Join-Path $PSScriptRoot '..\src\Revit\RevitBridge.csproj'
+
+. (Join-Path $PSScriptRoot 'check-sdk.ps1')
+$frameworks = if ($TargetFramework) { $TargetFramework -split ';' } else {
+    ([xml](Get-Content $project -Raw)).Project.PropertyGroup.TargetFrameworks | Where-Object { $_ } | ForEach-Object { $_ -split ';' }
+}
+if (-not (Test-PiRevitSdk -TargetFrameworks $frameworks)) { exit 1 }
+
+$buildArgs = @('build', $project, '-c', $Configuration)
 
 # Stamp the package version into the assembly so the bridge can report which release
 # the deployed add-in came from; the pi extension compares it against its own package

package/scripts/check-sdk.ps1

@@ -0,0 +1,66 @@
+#Requires -Version 5.1
+
+function Test-PiRevitSdk {
+    param(
+        [string[]]$TargetFrameworks,
+        [string]$Context = 'Revit bridge build',
+        [switch]$OfferDownload
+    )
+
+    # Check the SDK selected in the build's working directory, not just installed
+    # SDKs: global.json or PATH can still select an older SDK.
+    $requiredMajor = 0
+    foreach ($framework in $TargetFrameworks) {
+        if ($framework -notmatch '^net(\d+)\.') {
+            throw "Cannot determine the required .NET SDK for '$framework'."
+        }
+        $requiredMajor = [Math]::Max($requiredMajor, [int]$matches[1])
+    }
+    if ($requiredMajor -eq 0) { throw 'No target frameworks were supplied for the SDK check.' }
+
+    $selectedVersion = $null
+    if (Get-Command dotnet -ErrorAction SilentlyContinue) {
+        try {
+            $versionOutput = @(& dotnet --version 2>&1)
+            if ($LASTEXITCODE -eq 0) {
+                foreach ($line in $versionOutput) {
+                    if ("$line".Trim() -match '^(\d+)\.\d+\.\d+(?:-[\w.-]+)?$') {
+                        $selectedVersion = "$line".Trim()
+                        if ([int]$matches[1] -ge $requiredMajor) { return $true }
+                    }
+                }
+            }
+        }
+        catch {
+            # A runtime-only installation or an unresolved global.json can make
+            # --version fail. Present the same actionable prerequisite message.
+        }
+    }
+
+    $downloadUrl = "https://dotnet.microsoft.com/en-us/download/dotnet/$requiredMajor.0"
+    Write-Host "`npi-revit prerequisite check: $Context" -ForegroundColor Yellow
+    Write-Host "Building this add-in requires the .NET $requiredMajor SDK or a newer compatible SDK."
+    if ($selectedVersion) {
+        Write-Host "Your build tools currently use .NET SDK $selectedVersion."
+    }
+    else {
+        Write-Host 'No usable .NET SDK could be selected in this terminal.'
+    }
+    Write-Host 'Revit can run normally with its runtime; compiling the pi-revit add-in also needs the SDK.'
+    Write-Host "Install the .NET $requiredMajor SDK for Windows x64 (choose SDK, not Runtime)."
+    Write-Host 'You can keep your existing .NET versions installed.'
+    Write-Host "Download: $downloadUrl"
+    Write-Host 'Then reopen PowerShell and rerun your install or build command.'
+    Write-Host 'If the SDK is already installed, check dotnet --list-sdks, PATH, and any global.json selecting an older SDK.'
+
+    if ($OfferDownload -and [Environment]::UserInteractive -and -not [Console]::IsInputRedirected) {
+        try {
+            $answer = Read-Host 'Open the SDK download page now? [y/N]'
+            if ($answer -match '^(?i:y|yes)$') { Start-Process $downloadUrl | Out-Null }
+        }
+        catch {
+            Write-Host "Open the download link above in your browser."
+        }
+    }
+    return $false
+}

package/scripts/deploy.ps1

@@ -16,13 +16,16 @@ Usage:
   scripts\deploy.ps1                                              # auto-detect + deploy to all installed
   scripts\deploy.ps1 -RevitVersion 2026
   scripts\deploy.ps1 -RevitVersion 2027 -RevitApiPath "D:\Autodesk\Revit 2027"
-  scripts\deploy.ps1 -SkipBuild
+  scripts\deploy.ps1 -SkipBuild
+  scripts\deploy.ps1 -CheckOnly                                 # check prerequisites without installing
 #>
 param(
     [string]$RevitVersion = '',
     [string]$Configuration = 'Release',
     [string]$RevitApiPath = '',
-    [switch]$SkipBuild
+    [switch]$SkipBuild,
+    [switch]$CheckOnly,
+    [switch]$OfferDownload
 )
 
 $ErrorActionPreference = 'Stop'
@@ -68,11 +71,20 @@ else {
     Write-Host ("Detected Revit: " + (($targets | ForEach-Object { $_.Version }) -join ', ')) -ForegroundColor Cyan
 }
 
-# Build once per distinct target framework, compiling against a matching RevitAPI.dll.
+# Validate every target before starting any build or deployment.
+if ($CheckOnly -or -not $SkipBuild) {
+    . (Join-Path $PSScriptRoot 'check-sdk.ps1')
+    $context = 'Detected Revit: ' + (($targets | ForEach-Object { $_.Version }) -join ', ')
+    if (-not (Test-PiRevitSdk -TargetFrameworks @($targets.Tfm) -Context $context -OfferDownload:$OfferDownload)) { exit 1 }
+}
+if ($CheckOnly) { exit 0 }
+
+# Build once per distinct target framework, compiling against a matching RevitAPI.dll.
 if (-not $SkipBuild) {
     foreach ($group in ($targets | Group-Object Tfm)) {
         $apiPath = ($group.Group | Select-Object -First 1).Path
-        & (Join-Path $PSScriptRoot 'build.ps1') -Configuration $Configuration -RevitApiPath $apiPath -TargetFramework $group.Name
+        & (Join-Path $PSScriptRoot 'build.ps1') -Configuration $Configuration -RevitApiPath $apiPath -TargetFramework $group.Name
+        if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
     }
 }