pi-revit 0.2.18 → 0.3.1

package/src/Revit/Tools/GetElements.cs

@@ -21,7 +21,7 @@ namespace RevitBridge.Tools
 
         public string Name => "get_elements";
         public string Label => "Get Elements";
-        public string Description => "Query Revit elements: scope by category (display name like 'Walls' or enum name like 'OST_Walls'), element class, level, type id, or active view; filter by parameter rules; paginate with offset/limit or just count with count_only. Returns identity fields only (id, name, category, typeName, levelId) — read parameter values with get_element_details. Most filter rules evaluate inside Revit's collector; 'regex' rules (and rules on parameters that cannot be quick-filtered) run as a slower post-collector scan. Prefer combining display-name filter rules with a category or of_class scope: the same display name (e.g. 'Width') can resolve to different parameters per category, which forces the slower per-element scan in unscoped queries. Numeric rule values are interpreted in the document's display units for that parameter unless 'unit' is given.";
+        public string Description => "Query Revit elements: scope by category (display name like 'Walls' or enum name like 'OST_Walls'), element class, level, type id, or active view; filter by parameter rules; paginate with offset/limit or just count with count_only. Returns identity fields only (id, name, category, typeName, levelId) — read parameter values with get_element_details. Rules with an explicit BuiltInParameter or shared GUID can evaluate inside Revit's collector; display-name rules, regex rules, and unsupported quick filters run as a per-element scan. A display name can identify different parameters even within one category or class. Scope queries to reduce the scan, or use an explicit parameter identity when appropriate. Numeric rule values are interpreted in the document's display units for that parameter unless 'unit' is given.";
 
         public object ParametersSchema => new
         {
@@ -292,8 +292,9 @@ namespace RevitBridge.Tools
             if (rules.Count == 0)
                 return (null, null, Array.Empty<string>());
 
-            // Probe a few in-scope elements so display-name parameters resolve to ids
-            // and value typing / unit conversion can use the parameter's storage + spec.
+            // Probe a few in-scope elements for missing-name diagnostics and to find
+            // storage/spec exemplars for explicit parameter identities. A sample must
+            // never turn a display name into an assumed globally uniform identity.
             var probes = new List<Element>(ProbeSize);
             foreach (Element element in createBaseCollector())
             {
@@ -325,30 +326,19 @@ namespace RevitBridge.Tools
                 }
             }
 
-            // Display-name promotion is only trustworthy inside one category/class: the
-            // probe sees just the first ProbeSize elements in collector order, so in an
-            // unscoped query a unanimous sample can still hide other categories further
-            // on whose same-named parameter has a different id — and a pinned quick rule
-            // would silently drop their matches.
-            bool scoped = !string.IsNullOrWhiteSpace(JsonArgs.GetString(args, "category"))
-                || !string.IsNullOrWhiteSpace(JsonArgs.GetString(args, "of_class"));
-
             foreach (var rule in rules)
             {
                 if (rule.Op is RuleOp.Regex or RuleOp.IsEmpty or RuleOp.IsNotEmpty)
                     continue; // always post-scan (missing-parameter semantics)
+                // Category/class scope and unanimous samples do not establish a
+                // uniform parameter identity across later families. Resolve display
+                // names per element; only explicit identities may use a quick rule.
+                if (rule.BuiltIn is null && rule.SharedGuid is null)
+                    continue;
                 var found = probes.Select(probe => FindParameter(probe, rule)).Where(parameter => parameter != null).ToList();
                 if (found.Count == 0)
                     continue;
-                // BuiltInParameter/guid rules address one global parameter id. A plain
-                // display name can resolve to DIFFERENT ids per category or family
-                // (e.g. 'Width' -> DOOR_WIDTH vs WINDOW_WIDTH). Promote a display-name
-                // rule only when the query is scoped AND all probed elements agree on
-                // the id; otherwise it stays on the (per-element, correct) post-scan path.
-                bool oneGlobalId = rule.BuiltIn != null || rule.SharedGuid != null
-                    || (scoped && found.All(parameter => parameter!.Id == found[0]!.Id));
-                if (oneGlobalId)
-                    rule.QuickRule = TryBuildQuickRule(doc, rule, found[0]!);
+                rule.QuickRule = TryBuildQuickRule(doc, rule, found[0]!);
             }
 
             var quickRules = rules.Where(rule => rule.QuickRule != null).ToList();

package/src/Revit/Tools/GetModelOverview.cs

@@ -46,6 +46,7 @@ namespace RevitBridge.Tools
             var project = new Dictionary<string, object?>
             {
                 ["title"] = doc.Title,
+                ["documentId"] = DocumentGuard.GetIdentity(doc),
                 ["name"] = info?.Name,
                 ["number"] = info?.Number,
                 ["clientName"] = info?.ClientName,

package/src/Revit/Tools/ManageSelection.cs

@@ -138,9 +138,23 @@ namespace RevitBridge.Tools
 
             if (isolateInView)
             {
-                var view = uiDocument.ActiveGraphicalView
-                    ?? throw new ArgumentException("isolate_in_view requires an active graphical view in Revit.");
-                ApplyTemporaryIsolate(doc, view, isolateTargets);
+                var view = uiDocument.ActiveGraphicalView;
+                IReadOnlyList<string> warnings;
+                try
+                {
+                    if (view is null)
+                        throw new ArgumentException("isolate_in_view requires an active graphical view in Revit.");
+                    warnings = ApplyTemporaryIsolate(doc, view, isolateTargets);
+                }
+                catch (Exception ex)
+                {
+                    throw new InvalidOperationException($"Selection action '{action}' completed before temporary isolate failed: {ex.Message}. Selection/zoom changes were not rolled back.", ex);
+                }
+                if (warnings.Count > 0)
+                {
+                    payload["commitWarnings"] = warnings;
+                    compactParts.Add($"{warnings.Count} Revit warning(s) auto-dismissed (see commitWarnings)");
+                }
                 payload["viewId"] = view.Id.Value;
                 payload["viewName"] = view.Name;
                 if (isolateTargets.Count == 0)
@@ -189,32 +203,27 @@ namespace RevitBridge.Tools
         /// only changes it inside an open transaction — so exactly this branch wraps
         /// a small one while the tool stays Write = false.
         /// </summary>
-        private static void ApplyTemporaryIsolate(Document doc, View view, ICollection<ElementId> elementIds)
+        private static IReadOnlyList<string> ApplyTemporaryIsolate(Document doc, View view, ICollection<ElementId> elementIds)
         {
             using var transaction = new Transaction(doc, "manage_selection: temporary isolate");
-            var failureGuard = FailureGuard.Attach(transaction);
             if (transaction.Start() != TransactionStatus.Started)
                 throw new InvalidOperationException("Unable to start the temporary-isolate transaction.");
+            var failureGuard = FailureGuard.Attach(transaction);
             try
             {
                 if (elementIds.Count == 0)
                     view.DisableTemporaryViewMode(TemporaryViewMode.TemporaryHideIsolate);
                 else
                     view.IsolateElementsTemporary(elementIds);
-                if (transaction.Commit() != TransactionStatus.Committed)
-                    throw new InvalidOperationException("The temporary-isolate transaction failed to commit." + failureGuard.DescribeErrors());
-            }
-            catch (Autodesk.Revit.Exceptions.InvalidOperationException ex)
-            {
-                if (transaction.GetStatus() == TransactionStatus.Started)
-                    transaction.RollBack();
-                throw new ArgumentException($"The active view '{view.Name}' does not support temporary isolate: {ex.Message}");
+                var status = transaction.Commit();
+                var finalStatus = transaction.GetStatus();
+                if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
+                    throw new InvalidOperationException($"The temporary-isolate commit returned {status}; current transaction status is {finalStatus}." + failureGuard.DescribeErrors());
+                return failureGuard.Warnings;
             }
-            catch
+            catch (Exception ex)
             {
-                if (transaction.GetStatus() == TransactionStatus.Started)
-                    transaction.RollBack();
-                throw;
+                throw new InvalidOperationException($"Temporary isolate in view '{view.Name}' failed: {ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}", ex);
             }
         }
     }

package/src/Revit/Tools/SetParameters.cs

@@ -70,9 +70,9 @@ namespace RevitBridge.Tools
             var failed = new List<Dictionary<string, object?>>();
 
             using var transaction = new Transaction(doc, "set_parameters");
-            var failureGuard = FailureGuard.Attach(transaction);
             if (transaction.Start() != TransactionStatus.Started)
                 throw new InvalidOperationException("Unable to start the set_parameters transaction.");
+            var failureGuard = FailureGuard.Attach(transaction);
 
             try
             {
@@ -101,21 +101,23 @@ namespace RevitBridge.Tools
 
                 if (succeeded.Count > 0)
                 {
-                    if (transaction.Commit() != TransactionStatus.Committed)
+                    var status = transaction.Commit();
+                    var finalStatus = transaction.GetStatus();
+                    if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
                         throw new InvalidOperationException(
-                            "Revit rejected the set_parameters commit and the transaction was rolled back; no changes were saved."
+                            $"The set_parameters commit returned {status}; current transaction status is {finalStatus}."
                             + failureGuard.DescribeErrors());
                 }
                 else
                 {
-                    transaction.RollBack();
+                    var status = transaction.RollBack();
+                    if (status != TransactionStatus.RolledBack || transaction.GetStatus() != TransactionStatus.RolledBack)
+                        throw new InvalidOperationException($"The set_parameters rollback returned {status}.");
                 }
             }
-            catch
+            catch (Exception ex)
             {
-                if (transaction.GetStatus() == TransactionStatus.Started)
-                    transaction.RollBack();
-                throw;
+                throw new InvalidOperationException($"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}", ex);
             }
 
             int elementCount = succeeded.Select(row => row["id"]).Distinct().Count();

package/src/Revit/Tools/ToolSupport.cs

@@ -259,43 +259,4 @@ namespace RevitBridge.Tools
         }
     }
 
-    /// <summary>
-    /// Optional wrong-document protection for write tools. A write queued while the
-    /// user switches models would otherwise land in whichever document is active when
-    /// the queued call runs -- possibly silently, since low element ids resolve in
-    /// most documents. Tools pass the caller's optional expected_document through
-    /// here before touching the model.
-    /// </summary>
-    internal static class DocumentGuard
-    {
-        /// <summary>Throws when expected_document is provided and does not match the
-        /// active document's title (case-insensitive; the .rvt extension and a
-        /// detached suffix are tolerated). No-op when the argument is absent.</summary>
-        public static void CheckExpectedDocument(JsonElement args, Document doc)
-        {
-            string? expected = JsonArgs.GetString(args, "expected_document");
-            if (string.IsNullOrWhiteSpace(expected))
-                return;
-            string actual = doc.Title;
-            if (Matches(expected, actual))
-                return;
-            throw new ArgumentException(
-                $"Active document is '{actual}' but this call expected '{expected}'. Nothing was changed. "
-                + "The user switched models (or several are open); re-read the target model (get_model_overview) and retry against the right one.");
-        }
-
-        private static bool Matches(string expected, string actual)
-        {
-            static string Normalize(string value)
-            {
-                string v = value.Trim();
-                if (v.EndsWith(".rvt", StringComparison.OrdinalIgnoreCase))
-                    v = v[..^4];
-                if (v.EndsWith("_detached", StringComparison.OrdinalIgnoreCase))
-                    v = v[..^"_detached".Length];
-                return v;
-            }
-            return string.Equals(Normalize(expected), Normalize(actual), StringComparison.OrdinalIgnoreCase);
-        }
-    }
 }

package/workspace/AGENTS.md

@@ -1,8 +1,10 @@
 # pi-revit workspace
 
 This folder tree is the working area for Pi + Revit sessions. The pi-revit tools talk to the
-Revit bridge add-in; Revit 2025, 2026, or 2027 must be running with a project open
-(only `ping` and `search_api_docs` work without a document).
+Revit bridge add-in, targeting Revit 2025, 2026, and 2027. The 0.3.0 changes were
+tested live on Revit 2025. Bridge document tools require a project open; `ping` and
+`search_api_docs` work without a document. `read_revit_result` reads saved local
+results without contacting Revit.
 
 ## File rules — where every file goes
 
@@ -14,20 +16,26 @@ Documents\pi-revit\
 ├─ AGENTS.md            <- this file
 ├─ pi-revit.cmd         <- double-click launcher
 └─ Models\
-   └─ <model title>\    <- created automatically by the tools, one folder per Revit model
-      ├─ model.txt      <- the model's identity (GUID + file path), written by the add-in
+   └─ <model title>--<identity hash>\  <- selected automatically for the exported document
+      ├─ model.txt      <- document identity/path marker written by the add-in
       ├─ exports\       <- export_documents output (its default)
       ├─ captures\      <- view snapshots worth keeping
       └─ scripts\       <- generated scripts and analysis for that model
 ```
 
 1. **Let exports sort themselves**: call `export_documents` without `output_dir` — files land
-   in `Models\<model title>\exports` automatically, keyed to the exported document. Pass
+   in an identity-derived model folder automatically. Treat the returned `outputDir`
+   and file paths as authoritative; do not derive the hash from the model title or
+   opaque `project.documentId`. Save As can change the destination. Existing title-only
+   folders remain untouched. Pass
    `output_dir` only when the user names a different target.
 2. **Anything else you produce about a model goes into that model's folder**: view captures the
-   user wants to keep in `Models\<model title>\captures` (`capture_view` writes to temp — copy
-   the PNG over; the model title comes from `get_model_overview`), scripts and analysis in
-   `Models\<model title>\scripts`. Create these subfolders on first use.
+   user wants to keep in that verified model folder's `captures` subfolder
+   (`capture_view` writes to temp), and scripts and analysis in its `scripts`
+   subfolder. For a default export, the model folder is the parent of returned
+   `outputDir`. If no folder has been established, identify it from existing model
+   markers or choose an explicit destination for the task; do not trigger an
+   unnecessary export or guess a title-only folder. Create subfolders on first use.
 3. **Never create files loose in the workspace root.** The root holds `AGENTS.md`,
    `pi-revit.cmd`, `Models\`, and Pi's own session data — nothing else, ever.
 
@@ -35,7 +43,30 @@ Documents\pi-revit\
 
 - Start unfamiliar models with `get_model_overview`; use `get_elements` for any listing or
   counting; read parameter values with `get_element_details`.
+- Copy the intended model's `project.documentId` unchanged into `expected_document_id`
+  for `set_parameters`, `execute_csharp`, `export_documents`, `open_view`, and
+  selection/zoom changes. Any `manage_selection` call with `isolate_in_view: true`
+  also requires it, including action `get`. Pure reads may omit it; supplied IDs
+  are checked. Legacy `expected_document` titles alone do not satisfy the guard.
+  After a rejection, verify the intended model before refreshing its ID. Closing
+  and reopening a model or restarting Revit invalidates earlier IDs.
 - Before `execute_csharp`, verify unfamiliar API signatures with `search_api_docs`.
 - Write tools (`set_parameters`, `execute_csharp`) change the real model — state clearly what
   was changed. `set_parameters` commits partial successes: always check its `failed` list.
-  A failed `execute_csharp` rolls back entirely and reports the error.
+  Inspect `commitWarnings` and the actual transaction outcome. A failed
+  `execute_csharp` attempts rollback; do not assume rollback succeeded. A
+  `returnValueError` can follow a committed edit. Earlier UI actions and created
+  files can persist after failure. Read reported effects before retrying.
+- When a result returns `result_id`, use `read_revit_result` from offset zero and
+  follow `next_offset` until `has_more` is false. Join its `text` fragments in order;
+  offsets count UTF-16 code units. The returned absolute file path remains a
+  fallback for `read` after extension reload while the file exists. Tool query
+  pagination and limits still apply separately.
+
+## Upgrade notes
+
+After installing 0.3.0, deploy the matching add-in with Revit closed, restart Revit,
+and start a fresh Pi session to load the new tool schemas. Obtain a new overview
+before changing a document. Setup preserves existing `AGENTS.md`; older workspaces
+need these exact-ID, saved-result, and identity-derived folder rules merged into
+their existing instructions.