pi-revit 0.3.1 → 0.4.0

package/src/Revit/Tools/ElementQueryScope.cs

@@ -0,0 +1,27 @@
+using System.Text.Json;
+using System.Text.Json.Nodes;
+
+namespace RevitBridge.Tools;
+
+internal static class ElementQueryScope
+{
+    public static JsonObject Schema()
+    {
+        var schema = JsonSerializer.SerializeToNode(new GetElements().ParametersSchema)!.AsObject();
+        foreach (string key in new[] { "count_only", "fields", "offset", "limit", "parameter_names", "include_type_parameters" })
+            schema["properties"]!.AsObject().Remove(key);
+        schema["description"] = "Filter the whole matching scope. Query paging and projections are not supported here.";
+        schema["additionalProperties"] = false;
+        return schema;
+    }
+
+    public static JsonObject Parse(JsonElement args)
+    {
+        var query = args.TryGetProperty("query", out var input) ? JsonNode.Parse(input.GetRawText()) as JsonObject : new JsonObject();
+        if (query == null) throw new ArgumentException("query must be an object.");
+        var allowed = Schema()["properties"]!.AsObject();
+        foreach (var property in query)
+            if (!allowed.ContainsKey(property.Key)) throw new ArgumentException($"query does not support '{property.Key}'. It always uses the whole matching scope.");
+        return query;
+    }
+}

package/src/Revit/Tools/ExecuteCsharp.cs

@@ -20,11 +20,12 @@ namespace RevitBridge.Tools
     /// </summary>
     public sealed class ScriptGlobals
     {
-        internal ScriptGlobals(Document document, UIDocument uiDocument, UIApplication uiApplication, Action<object?> dump)
+        internal ScriptGlobals(Document document, UIDocument uiDocument, UIApplication uiApplication, JsonElement inputValues, Action<object?> dump)
         {
             doc = document;
             uidoc = uiDocument;
-            uiapp = uiApplication;
+            uiapp = uiApplication;
+            inputs = inputValues;
             Dump = dump;
         }
 
@@ -35,7 +36,10 @@ namespace RevitBridge.Tools
         public UIDocument uidoc { get; }
 
         /// <summary>The Revit UI application.</summary>
-        public UIApplication uiapp { get; }
+        public UIApplication uiapp { get; }
+
+        /// <summary>Structured inputs supplied separately from the script source.</summary>
+        public JsonElement inputs { get; }
 
         /// <summary>Records a value into the result's dumps[] (safely projected at call time).</summary>
         public Action<object?> Dump { get; }
@@ -59,19 +63,21 @@ namespace RevitBridge.Tools
 
         public string Name => "execute_csharp";
         public string Label => "Execute C#";
-        public string Description => "Compile and run a C# script on the Revit API thread against the open model — the escape hatch for anything without a dedicated tool: element creation, deletion, geometry edits (move/copy/rotate), views, sheets, schedules, tagging, families, links, worksets. Globals: doc (Document), uidoc (UIDocument), uiapp (UIApplication), and Dump(value) to record intermediate values into the result's dumps[]. Default imports: System, System.Linq, System.Collections.Generic, Autodesk.Revit.DB, Autodesk.Revit.UI — add using directives at the top for sub-namespaces (e.g. using Autodesk.Revit.DB.Architecture;). The entire run is wrapped in ONE transaction named 'execute_csharp': committed on success; on failure rollback is attempted and its confirmed status is reported (do not open your own Transaction; sub-transactions are fine). The script's final expression or return statement becomes returnValue; return primitives, strings, or anonymous objects/lists — Revit API values are projected to safe shapes (Element -> {id,name,category,typeName,levelId}, ElementId -> number, XYZ -> {x,y,z}, Parameter -> {name,value,displayValue}; other API objects become strings) with depth and item caps, so never rely on raw API objects round-tripping. Lengths are in internal units (decimal feet) — convert with UnitUtils. Prefer collector-level filtering (FilteredElementCollector .OfCategory/.OfClass/.WhereElementIsNotElementType) and bounded loops: the call budget is 120s and Revit cannot be interrupted mid-script. Scripts must be fully synchronous — await/async is rejected at compile time, and blocking on tasks (Task.Result/.Wait()) can freeze Revit. Modal dialogs raised while running are auto-dismissed and reported in suppressedDialogs — unrecognized dialogs are answered dismissively (Cancel/Close/No) rather than confirmed, so an operation that raises a confirmation prompt may be cancelled; check suppressedDialogs when a result looks incomplete. Verify unfamiliar signatures with search_api_docs first.";
-        public bool Write => true;
+        public string Description => "Compile and run a C# script on the Revit API thread against the open model — the escape hatch for anything without a dedicated tool: element creation, deletion, geometry edits (move/copy/rotate), views, sheets, schedules, tagging, families, links, worksets. Globals: doc (Document), uidoc (UIDocument), uiapp (UIApplication), inputs (System.Text.Json.JsonElement, defaults to an empty object), and Dump(value) to record intermediate values into the result's dumps[]. Default imports: System, System.Linq, System.Collections.Generic, Autodesk.Revit.DB, Autodesk.Revit.UI — add using directives at the top for sub-namespaces (e.g. using Autodesk.Revit.DB.Architecture;). The entire run is wrapped in ONE transaction named 'execute_csharp': committed on success; on failure rollback is attempted and its confirmed status is reported (do not open your own Transaction; sub-transactions are fine). The script's final expression or return statement becomes returnValue; return primitives, strings, or anonymous objects/lists — Revit API values are projected to safe shapes (Element -> {id,name,category,typeName,levelId}, ElementId -> number, XYZ -> {x,y,z}, Parameter -> {name,value,displayValue}; other API objects become strings) with depth and item caps, so never rely on raw API objects round-tripping. Lengths are in internal units (decimal feet) — convert with UnitUtils. Prefer collector-level filtering (FilteredElementCollector .OfCategory/.OfClass/.WhereElementIsNotElementType) and bounded loops: the call budget is 120s and Revit cannot be interrupted mid-script. Scripts must be fully synchronous — await/async is rejected at compile time, and blocking on tasks (Task.Result/.Wait()) can freeze Revit. Modal dialogs raised while running are auto-dismissed and reported in suppressedDialogs — unrecognized dialogs are answered dismissively (Cancel/Close/No) rather than confirmed, so an operation that raises a confirmation prompt may be cancelled; check suppressedDialogs when a result looks incomplete. Verify unfamiliar signatures with search_api_docs first.";
+        public bool Write => true;
+        public IReadOnlyList<string> Effects => new[] { "model", "ui", "files", "external" };
 
         public object ParametersSchema => new
         {
             type = "object",
             properties = new
             {
-                code = new
+                code = new
                 {
                     type = "string",
-                    description = "C# script body (top-level statements; using directives allowed at the top). Globals doc/uidoc/uiapp and Dump(value) are in scope. The final expression or a return statement is the result.",
-                },
+                    description = "C# script body (top-level statements; using directives allowed at the top). Globals doc/uidoc/uiapp/inputs and Dump(value) are in scope. The final expression or a return statement is the result.",
+                },
+                inputs = new { type = "object", description = "Optional structured JSON inputs, available as the inputs JsonElement global. Default empty object. Values are never interpolated into source code." },
                 expected_document = new
                 {
                     type = "string",
@@ -96,8 +102,11 @@ namespace RevitBridge.Tools
             DocumentGuard.CheckExpectedDocument(args, doc);
 
             string code = JsonArgs.GetString(args, "code") ?? string.Empty;
-            if (string.IsNullOrWhiteSpace(code))
-                throw new ArgumentException("code must be a non-empty C# script.");
+            if (string.IsNullOrWhiteSpace(code))
+                throw new ArgumentException("code must be a non-empty C# script.");
+            var inputValues = args.TryGetProperty("inputs", out var suppliedInputs) ? suppliedInputs.Clone() : JsonSerializer.SerializeToElement(new { });
+            if (inputValues.ValueKind != JsonValueKind.Object) throw new ArgumentException("inputs must be a JSON object.");
+            if (inputValues.GetRawText().Length > 100000) throw new ArgumentException("inputs must not exceed 100,000 JSON characters.");
 
             var stopwatch = Stopwatch.StartNew();
 
@@ -109,7 +118,7 @@ namespace RevitBridge.Tools
             RejectAsyncCode(script.GetCompilation());
 
             var dumps = new List<object?>();
-            var globals = new ScriptGlobals(doc, uidoc, uiapp, value =>
+            var globals = new ScriptGlobals(doc, uidoc, uiapp, inputValues, value =>
             {
                 if (dumps.Count < MaxDumps)
                     dumps.Add(Project(value, 0));
@@ -119,9 +128,9 @@ namespace RevitBridge.Tools
 
             using var dialogGuard = new DialogGuard(uiapp);
             using var transaction = new Transaction(doc, "execute_csharp");
-            if (transaction.Start() != TransactionStatus.Started)
-                throw new InvalidOperationException("Unable to start the execute_csharp transaction.");
-            var failureGuard = FailureGuard.Attach(transaction);
+            if (transaction.Start() != TransactionStatus.Started)
+                throw new InvalidOperationException("Unable to start the execute_csharp transaction.");
+            var failureGuard = FailureGuard.Attach(transaction);
 
             object? returnValue;
             string? projectionError = null;
@@ -147,24 +156,24 @@ namespace RevitBridge.Tools
             }
             catch (Exception ex)
             {
-                throw new InvalidOperationException(
-                    FormatRuntimeError(ex, dialogGuard.Suppressed) + " " + FailureGuard.RollBackAndDescribe(transaction), ex);
-            }
-
-            try
-            {
-                var status = transaction.Commit();
-                var finalStatus = transaction.GetStatus();
-                if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
-                    throw new InvalidOperationException($"The execute_csharp commit returned {status}; current transaction status is {finalStatus}.");
-            }
-            catch (Exception ex)
-            {
-                throw new InvalidOperationException(
-                    $"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}"
-                    + failureGuard.DescribeErrors()
-                    + DescribeDialogs(dialogGuard.Suppressed), ex);
-            }
+                throw new InvalidOperationException(
+                    FormatRuntimeError(ex, dialogGuard.Suppressed) + " " + FailureGuard.RollBackAndDescribe(transaction), ex);
+            }
+
+            try
+            {
+                var status = transaction.Commit();
+                var finalStatus = transaction.GetStatus();
+                if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
+                    throw new InvalidOperationException($"The execute_csharp commit returned {status}; current transaction status is {finalStatus}.");
+            }
+            catch (Exception ex)
+            {
+                throw new InvalidOperationException(
+                    $"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}"
+                    + failureGuard.DescribeErrors()
+                    + DescribeDialogs(dialogGuard.Suppressed), ex);
+            }
 
             stopwatch.Stop();
 
@@ -194,7 +203,8 @@ namespace RevitBridge.Tools
                 Assembly.Load("netstandard"),
                 typeof(Enumerable).Assembly,                                // System.Linq
                 typeof(Regex).Assembly,                                     // System.Text.RegularExpressions
-                typeof(Console).Assembly,                                   // System.Console
+                typeof(Console).Assembly,                                   // System.Console
+                typeof(JsonElement).Assembly,                               // System.Text.Json
                 typeof(Document).Assembly,                                  // RevitAPI
                 typeof(UIApplication).Assembly)                             // RevitAPIUI
             .WithImports("System", "System.Linq", "System.Collections.Generic", "Autodesk.Revit.DB", "Autodesk.Revit.UI")
@@ -209,7 +219,7 @@ namespace RevitBridge.Tools
             });
             string more = errors.Count > MaxReportedErrors ? $"\n  … +{errors.Count - MaxReportedErrors} more error(s)" : string.Empty;
             return $"C# compilation failed with {errors.Count} error(s):\n{string.Join("\n", lines)}{more}\n"
-                + "Globals: doc, uidoc, uiapp, Dump(value). Default imports: System, System.Linq, System.Collections.Generic, "
+                + "Globals: doc, uidoc, uiapp, inputs (JsonElement), Dump(value). Default imports: System, System.Linq, System.Collections.Generic, "
                 + "Autodesk.Revit.DB, Autodesk.Revit.UI — add using directives for other namespaces.";
         }
 
@@ -241,7 +251,7 @@ namespace RevitBridge.Tools
             string line = TryGetScriptLine(ex) is { } scriptLine ? $" at script line {scriptLine}" : string.Empty;
             string inner = ex.InnerException is { } innerEx ? $" Inner: {innerEx.GetType().Name}: {innerEx.Message}" : string.Empty;
             return $"C# script threw {ex.GetType().Name}{line}: {ex.Message}.{inner}"
-                + DescribeDialogs(suppressedDialogs);
+                + DescribeDialogs(suppressedDialogs);
         }
 
         private static string DescribeDialogs(IReadOnlyList<string> suppressed)

package/src/Revit/Tools/ExportDocuments.cs

@@ -1,6 +1,6 @@
-using System.IO;
-using System.Security.Cryptography;
-using System.Text;
+using System.IO;
+using System.Security.Cryptography;
+using System.Text;
 using System.Text.Json;
 using Autodesk.Revit.DB;
 
@@ -22,7 +22,8 @@ namespace RevitBridge.Tools
         public string Name => "export_documents";
         public string Label => "Export Documents";
         public string Description => "Export documents from the open Revit model. format 'pdf'/'dwg'/'png' export the given sheet/view ids to files: pdf combines everything into one file by default (combine=false writes one PDF per sheet/view, named by Revit's naming rule); png renders 2048 px wide; ifc exports the whole model, or just what one given view shows. Files sort themselves per model: with output_dir omitted they land in Documents\\pi-revit\\Models\\<model title>--<identity hash>\\exports, derived from the document being exported (pass output_dir only for a different explicit target); file_name_prefix sets the base file name (default: the document title; Revit appends view/sheet suffixes for multi-file exports). Returns the produced file paths with sizes. Find sheet/view ids with get_elements (category 'Sheets' or 'Views') first.";
-        public bool Write => true;
+        public bool Write => true;
+        public IReadOnlyList<string> Effects => new[] { "model", "files" };
         public string Tier => "advanced";
 
         public object ParametersSchema => new
@@ -88,37 +89,37 @@ namespace RevitBridge.Tools
             // recent (a shared output_dir, another tool writing alongside) does not.
             var before = SnapshotWriteTimes(outputDir);
 
-            IReadOnlyList<string> commitWarnings = Array.Empty<string>();
-            try
-            {
-                switch (format)
-                {
-                    case "pdf": ExportPdf(doc, views, outputDir, baseName, combine); break;
-                    case "dwg": ExportDwg(doc, views, outputDir, baseName); break;
-                    case "png": ExportPng(doc, views, outputDir, baseName); break;
-                    default: commitWarnings = ExportIfc(doc, views, outputDir, baseName); break;
-                }
-            }
-            catch (Exception ex)
-            {
-                // A failed export may already have written some files. A Revit
-                // transaction rollback cannot undo those filesystem changes.
-                string observed;
-                try
-                {
-                    var changed = FindChangedFiles(outputDir, before).ToList();
-                    observed = changed.Count == 0
-                        ? "No changed files were observed."
-                        : $"Observed {changed.Count} new or changed file(s): {string.Join(", ", changed.Take(20))}{(changed.Count > 20 ? " (additional files omitted)" : string.Empty)}.";
-                }
-                catch (Exception scanError)
-                {
-                    observed = $"Could not inspect remaining files: {scanError.Message}.";
-                }
-                throw new InvalidOperationException($"{ex.Message} The export failed; files in '{outputDir}' may be incomplete and were not removed. {observed}", ex);
-            }
-
-            var files = FindChangedFiles(outputDir, before)
+            IReadOnlyList<string> commitWarnings = Array.Empty<string>();
+            try
+            {
+                switch (format)
+                {
+                    case "pdf": ExportPdf(doc, views, outputDir, baseName, combine); break;
+                    case "dwg": ExportDwg(doc, views, outputDir, baseName); break;
+                    case "png": ExportPng(doc, views, outputDir, baseName); break;
+                    default: commitWarnings = ExportIfc(doc, views, outputDir, baseName); break;
+                }
+            }
+            catch (Exception ex)
+            {
+                // A failed export may already have written some files. A Revit
+                // transaction rollback cannot undo those filesystem changes.
+                string observed;
+                try
+                {
+                    var changed = FindChangedFiles(outputDir, before).ToList();
+                    observed = changed.Count == 0
+                        ? "No changed files were observed."
+                        : $"Observed {changed.Count} new or changed file(s): {string.Join(", ", changed.Take(20))}{(changed.Count > 20 ? " (additional files omitted)" : string.Empty)}.";
+                }
+                catch (Exception scanError)
+                {
+                    observed = $"Could not inspect remaining files: {scanError.Message}.";
+                }
+                throw new InvalidOperationException($"{ex.Message} The export failed; files in '{outputDir}' may be incomplete and were not removed. {observed}", ex);
+            }
+
+            var files = FindChangedFiles(outputDir, before)
                 .Select(path => new Dictionary<string, object?>
                 {
                     ["path"] = path,
@@ -129,23 +130,23 @@ namespace RevitBridge.Tools
                 throw new InvalidOperationException($"The {format} export finished but produced no files in {outputDir}.");
 
             string sample = string.Join(", ", files.Take(3).Select(file => Path.GetFileName((string)file["path"]!)));
-            string compact = $"Exported {files.Count} {format.ToUpperInvariant()} file(s) to {outputDir}: {sample}{(files.Count > 3 ? $" (+{files.Count - 3} more)" : string.Empty)}.";
-            if (commitWarnings.Count > 0)
-                compact += $" {commitWarnings.Count} Revit warning(s) auto-dismissed (see commitWarnings).";
+            string compact = $"Exported {files.Count} {format.ToUpperInvariant()} file(s) to {outputDir}: {sample}{(files.Count > 3 ? $" (+{files.Count - 3} more)" : string.Empty)}.";
+            if (commitWarnings.Count > 0)
+                compact += $" {commitWarnings.Count} Revit warning(s) auto-dismissed (see commitWarnings).";
             return new ToolOutput(new
             {
                 format,
                 outputDir,
                 fileCount = files.Count,
-                files,
-                commitWarnings,
-            }, compact);
-        }
-
-        private static IEnumerable<string> FindChangedFiles(string directory, IReadOnlyDictionary<string, DateTime> before)
-            => Directory.GetFiles(directory)
-                .Where(path => !before.TryGetValue(path, out DateTime writtenBefore) || SafeWriteTime(path) != writtenBefore)
-                .OrderBy(path => path, StringComparer.OrdinalIgnoreCase);
+                files,
+                commitWarnings,
+            }, compact);
+        }
+
+        private static IEnumerable<string> FindChangedFiles(string directory, IReadOnlyDictionary<string, DateTime> before)
+            => Directory.GetFiles(directory)
+                .Where(path => !before.TryGetValue(path, out DateTime writtenBefore) || SafeWriteTime(path) != writtenBefore)
+                .OrderBy(path => path, StringComparer.OrdinalIgnoreCase);
 
         /// <summary>path -> last write time for the files already in the output directory.
         /// A file whose time cannot be read is left out, so the export reports it if it
@@ -227,29 +228,29 @@ namespace RevitBridge.Tools
         /// <summary>The IFC exporter writes IFC GUID parameters onto exported elements,
         /// so the Revit API requires a transaction around it — owned here, matching
         /// Revit's own behavior of committing those GUIDs on export.</summary>
-        private static IReadOnlyList<string> ExportIfc(Document doc, List<View> views, string outputDir, string baseName)
+        private static IReadOnlyList<string> ExportIfc(Document doc, List<View> views, string outputDir, string baseName)
         {
             var options = new IFCExportOptions();
             if (views.Count == 1)
                 options.FilterViewId = views[0].Id;
 
             using var transaction = new Transaction(doc, "export_documents: ifc");
-            if (transaction.Start() != TransactionStatus.Started)
-                throw new InvalidOperationException("Unable to start the IFC export transaction.");
-            var failureGuard = FailureGuard.Attach(transaction);
+            if (transaction.Start() != TransactionStatus.Started)
+                throw new InvalidOperationException("Unable to start the IFC export transaction.");
+            var failureGuard = FailureGuard.Attach(transaction);
             try
             {
                 if (!Run(() => doc.Export(outputDir, baseName, options), "IFC"))
                     throw new InvalidOperationException("Revit reported a failed IFC export.");
-                var status = transaction.Commit();
-                var finalStatus = transaction.GetStatus();
-                if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
-                    throw new InvalidOperationException($"The IFC export commit returned {status}; current transaction status is {finalStatus}." + failureGuard.DescribeErrors());
-                return failureGuard.Warnings;
-            }
-            catch (Exception ex)
-            {
-                throw new InvalidOperationException($"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}", ex);
+                var status = transaction.Commit();
+                var finalStatus = transaction.GetStatus();
+                if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
+                    throw new InvalidOperationException($"The IFC export commit returned {status}; current transaction status is {finalStatus}." + failureGuard.DescribeErrors());
+                return failureGuard.Warnings;
+            }
+            catch (Exception ex)
+            {
+                throw new InvalidOperationException($"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}", ex);
             }
         }
 
@@ -310,72 +311,72 @@ namespace RevitBridge.Tools
         }
 
         /// <summary>Per-model folder under the pi-revit workspace:
-        /// Documents\pi-revit\Models\&lt;model title&gt;--&lt;identity hash&gt;.
-        /// Existing title-only folders are left untouched; identity markers are
-        /// diagnostic records, not the mechanism that separates exports.</summary>
-        private static string ModelFolder(Document doc)
+        /// Documents\pi-revit\Models\&lt;model title&gt;--&lt;identity hash&gt;.
+        /// Existing title-only folders are left untouched; identity markers are
+        /// diagnostic records, not the mechanism that separates exports.</summary>
+        private static string ModelFolder(Document doc)
         {
             string workspace = Path.Combine(
                 Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments), "pi-revit");
-            string identity = GetModelIdentity(doc);
-            string folder = Path.Combine(workspace, "Models", GetModelFolderName(doc.Title, identity));
-            Directory.CreateDirectory(folder);
-            TryRecordModelIdentity(folder, doc, identity);
-            return folder;
-        }
-
-        internal static string GetModelFolderName(string title, string identity)
-        {
-            string cleanTitle = SanitizeFileName(string.IsNullOrWhiteSpace(title) ? "untitled" : title);
-            // Bound the default path component, leaving room for the identity and exports.
-            if (cleanTitle.Length > 80)
-                cleanTitle = cleanTitle[..80];
-            string hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(identity))).ToLowerInvariant()[..24];
-            return $"{cleanTitle}--{hash}";
-        }
-
-        // Revit can return different managed wrappers for one open native document.
-        // Document.Equals/GetHashCode identify that open document, unlike reference
-        // equality in ConditionalWeakTable. Closed document entries are pruned below.
-        // Tool execution and this dictionary are confined to the Revit API thread.
-        private static readonly Dictionary<Document, string> OpenDocumentIdentities = new();
-
-        internal static string GetModelIdentity(Document doc)
-        {
-            try
-            {
-                if (doc.IsModelInCloud)
-                {
-                    var path = doc.GetCloudModelPath();
-                    return $"cloud:{path.Region.ToUpperInvariant()}:{path.GetProjectGUID():D}:{path.GetModelGUID():D}";
-                }
-                string pathName = doc.PathName;
-                if (!string.IsNullOrWhiteSpace(pathName))
-                {
-                    // Revit file paths are Windows paths; canonicalize separators,
-                    // relative segments and case. Revit Server identities use RSN URLs.
-                    if (pathName.StartsWith("RSN://", StringComparison.OrdinalIgnoreCase))
-                        return "server:" + pathName.Replace('\\', '/').TrimEnd('/').ToUpperInvariant();
-                    return "file:" + Path.GetFullPath(pathName).Replace('/', '\\').ToUpperInvariant();
-                }
-            }
-            catch
-            {
-                // An unavailable identity must not collapse unrelated documents into
-                // a shared title-only directory. Use the same safe fallback as unsaved docs.
-            }
-            foreach (var closed in OpenDocumentIdentities.Keys.Where(key => !key.IsValidObject).ToList())
-                OpenDocumentIdentities.Remove(closed);
-            if (!OpenDocumentIdentities.TryGetValue(doc, out string? identity))
-                OpenDocumentIdentities[doc] = identity = $"session:{Guid.NewGuid():N}";
-            return identity;
-        }
-
-        private static void TryRecordModelIdentity(string folder, Document doc, string identity)
+            string identity = GetModelIdentity(doc);
+            string folder = Path.Combine(workspace, "Models", GetModelFolderName(doc.Title, identity));
+            Directory.CreateDirectory(folder);
+            TryRecordModelIdentity(folder, doc, identity);
+            return folder;
+        }
+
+        internal static string GetModelFolderName(string title, string identity)
+        {
+            string cleanTitle = SanitizeFileName(string.IsNullOrWhiteSpace(title) ? "untitled" : title);
+            // Bound the default path component, leaving room for the identity and exports.
+            if (cleanTitle.Length > 80)
+                cleanTitle = cleanTitle[..80];
+            string hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(identity))).ToLowerInvariant()[..24];
+            return $"{cleanTitle}--{hash}";
+        }
+
+        // Revit can return different managed wrappers for one open native document.
+        // Document.Equals/GetHashCode identify that open document, unlike reference
+        // equality in ConditionalWeakTable. Closed document entries are pruned below.
+        // Tool execution and this dictionary are confined to the Revit API thread.
+        private static readonly Dictionary<Document, string> OpenDocumentIdentities = new();
+
+        internal static string GetModelIdentity(Document doc)
+        {
+            try
+            {
+                if (doc.IsModelInCloud)
+                {
+                    var path = doc.GetCloudModelPath();
+                    return $"cloud:{path.Region.ToUpperInvariant()}:{path.GetProjectGUID():D}:{path.GetModelGUID():D}";
+                }
+                string pathName = doc.PathName;
+                if (!string.IsNullOrWhiteSpace(pathName))
+                {
+                    // Revit file paths are Windows paths; canonicalize separators,
+                    // relative segments and case. Revit Server identities use RSN URLs.
+                    if (pathName.StartsWith("RSN://", StringComparison.OrdinalIgnoreCase))
+                        return "server:" + pathName.Replace('\\', '/').TrimEnd('/').ToUpperInvariant();
+                    return "file:" + Path.GetFullPath(pathName).Replace('/', '\\').ToUpperInvariant();
+                }
+            }
+            catch
+            {
+                // An unavailable identity must not collapse unrelated documents into
+                // a shared title-only directory. Use the same safe fallback as unsaved docs.
+            }
+            foreach (var closed in OpenDocumentIdentities.Keys.Where(key => !key.IsValidObject).ToList())
+                OpenDocumentIdentities.Remove(closed);
+            if (!OpenDocumentIdentities.TryGetValue(doc, out string? identity))
+                OpenDocumentIdentities[doc] = identity = $"session:{Guid.NewGuid():N}";
+            return identity;
+        }
+
+        private static void TryRecordModelIdentity(string folder, Document doc, string identity)
         {
             try
             {
-                string line = $"{identity}\t{doc.PathName}";
+                string line = $"{identity}\t{doc.PathName}";
                 string marker = Path.Combine(folder, "model.txt");
                 if (!File.Exists(marker) || !File.ReadAllLines(marker).Contains(line))
                     File.AppendAllLines(marker, new[] { line });

package/src/Revit/Tools/FailureGuard.cs

@@ -16,36 +16,36 @@ namespace RevitBridge.Tools
         public List<string> Warnings { get; } = new();
         public List<string> Errors { get; } = new();
 
-        public static FailureGuard Attach(Transaction transaction)
-        {
-            if (transaction.GetStatus() != TransactionStatus.Started)
-                throw new InvalidOperationException("FailureGuard must be attached after the transaction starts; Start resets failure handling options.");
-            var guard = new FailureGuard();
+        public static FailureGuard Attach(Transaction transaction)
+        {
+            if (transaction.GetStatus() != TransactionStatus.Started)
+                throw new InvalidOperationException("FailureGuard must be attached after the transaction starts; Start resets failure handling options.");
+            var guard = new FailureGuard();
             var options = transaction.GetFailureHandlingOptions();
             options.SetFailuresPreprocessor(guard);
             options.SetClearAfterRollback(true);
             transaction.SetFailureHandlingOptions(options);
-            return guard;
-        }
-
-        /// <summary>Best-effort cleanup that preserves the original failure and never
-        /// claims a rollback unless Revit confirms its final transaction status.</summary>
-        public static string RollBackAndDescribe(Transaction transaction)
-        {
-            try
-            {
-                if (transaction.GetStatus() == TransactionStatus.Started)
-                    transaction.RollBack();
-                var status = transaction.GetStatus();
-                return status == TransactionStatus.RolledBack
-                    ? "The transaction was rolled back; no changes from this transaction were saved."
-                    : $"Transaction status is {status}; rollback is not confirmed. Inspect Revit before retrying.";
-            }
-            catch (Exception ex)
-            {
-                return $"Rollback could not be confirmed ({ex.GetType().Name}: {ex.Message}). Inspect Revit before retrying.";
-            }
-        }
+            return guard;
+        }
+
+        /// <summary>Best-effort cleanup that preserves the original failure and never
+        /// claims a rollback unless Revit confirms its final transaction status.</summary>
+        public static string RollBackAndDescribe(Transaction transaction)
+        {
+            try
+            {
+                if (transaction.GetStatus() == TransactionStatus.Started)
+                    transaction.RollBack();
+                var status = transaction.GetStatus();
+                return status == TransactionStatus.RolledBack
+                    ? "The transaction was rolled back; no changes from this transaction were saved."
+                    : $"Transaction status is {status}; rollback is not confirmed. Inspect Revit before retrying.";
+            }
+            catch (Exception ex)
+            {
+                return $"Rollback could not be confirmed ({ex.GetType().Name}: {ex.Message}). Inspect Revit before retrying.";
+            }
+        }
 
         public FailureProcessingResult PreprocessFailures(FailuresAccessor accessor)
         {