pi-revit 0.2.18 → 0.3.0

package/src/Revit/Tools/ManageSelection.cs

@@ -136,11 +136,25 @@ namespace RevitBridge.Tools
                 compactParts.Add($"ids not found: {string.Join(", ", notFound)}");
             }
 
-            if (isolateInView)
-            {
-                var view = uiDocument.ActiveGraphicalView
-                    ?? throw new ArgumentException("isolate_in_view requires an active graphical view in Revit.");
-                ApplyTemporaryIsolate(doc, view, isolateTargets);
+            if (isolateInView)
+            {
+                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,33 +203,28 @@ 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)
-        {
-            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.");
+        private static IReadOnlyList<string> ApplyTemporaryIsolate(Document doc, View view, ICollection<ElementId> elementIds)
+        {
+            using var transaction = new Transaction(doc, "manage_selection: temporary isolate");
+            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}");
-            }
-            catch
-            {
-                if (transaction.GetStatus() == TransactionStatus.Started)
-                    transaction.RollBack();
-                throw;
-            }
+                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 (Exception ex)
+            {
+                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.");
+            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)
-                        throw new InvalidOperationException(
-                            "Revit rejected the set_parameters commit and the transaction was rolled back; no changes were saved."
+                    var status = transaction.Commit();
+                    var finalStatus = transaction.GetStatus();
+                    if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
+                        throw new InvalidOperationException(
+                            $"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
-            {
-                if (transaction.GetStatus() == TransactionStatus.Started)
-                    transaction.RollBack();
-                throw;
+            catch (Exception ex)
+            {
+                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,28 +16,57 @@ 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.
 
 ## Tool habits
 
-- Start unfamiliar models with `get_model_overview`; use `get_elements` for any listing or
-  counting; read parameter values with `get_element_details`.
-- 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.
+- 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.
+  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.