pi-revit 0.3.1 → 0.4.0

package/src/Revit/OperationStore.cs

@@ -0,0 +1,178 @@
+using System.Diagnostics;
+using System.Security.Cryptography;
+using System.Text.Json;
+
+namespace RevitBridge;
+
+/// <summary>Session-local operation receipts. Expiring a result never permits the same ID to execute again.</summary>
+internal sealed class OperationStore
+{
+    internal sealed record Reply(int Status, object Response, string? Outcome = null);
+    internal sealed class Entry
+    {
+        internal required string Id;
+        internal required string Tool;
+        internal required string Fingerprint;
+        internal required long Deadline;
+        internal DateTimeOffset Created = DateTimeOffset.UtcNow;
+        internal DateTimeOffset? Started;
+        internal DateTimeOffset? Finished;
+        internal string State = "queued";
+        internal TaskCompletionSource<Reply>? Completion = new(TaskCreationOptions.RunContinuationsAsynchronously);
+        internal Reply? SavedReply;
+        internal int SavedBytes;
+    }
+
+    private readonly object _gate = new();
+    private readonly Dictionary<string, Entry> _entries = new(StringComparer.Ordinal);
+    private readonly Queue<Entry> _results = new();
+    private readonly int _maxRecords;
+    private readonly int _maxResults;
+    private readonly int _maxBytes;
+    private int _bytes;
+    public string Generation { get; } = Guid.NewGuid().ToString("N");
+
+    internal OperationStore(int maxRecords = 10000, int maxResults = 128, int maxBytes = 32 * 1024 * 1024)
+    {
+        _maxRecords = maxRecords; _maxResults = maxResults; _maxBytes = maxBytes;
+    }
+
+    public (Entry Entry, bool IsNew) Reserve(string id, string tool, JsonElement args, TimeSpan timeout)
+    {
+        id = ValidateId(id);
+        string fingerprint = Fingerprint(tool, args);
+        lock (_gate)
+        {
+            if (_entries.TryGetValue(id, out var existing))
+            {
+                if (existing.Fingerprint != fingerprint) throw new ArgumentException("operation_id was already used with different tool arguments. No new operation was started.");
+                return (existing, false);
+            }
+            if (_entries.Count >= _maxRecords) throw new InvalidOperationException("Operation receipt capacity reached. Restart the bridge before starting new tracked operations; existing receipts remain queryable.");
+            var entry = new Entry { Id = id, Tool = tool, Fingerprint = fingerprint,
+                Deadline = Stopwatch.GetTimestamp() + (long)(timeout.TotalSeconds * Stopwatch.Frequency) };
+            _entries.Add(id, entry);
+            return (entry, true);
+        }
+    }
+
+    public Task<Reply> Wait(Entry entry)
+    {
+        lock (_gate)
+        {
+            ExpireQueued(entry);
+            return entry.Completion?.Task ?? Task.FromResult(entry.SavedReply ?? new Reply(409, new
+            {
+                error = true, operation_id = entry.Id, state = entry.State,
+                message = "The operation already finished, but its full result has expired. It was not repeated. Inspect current model state before deciding on a new operation.",
+            }));
+        }
+    }
+
+    public bool TryStart(Entry entry)
+    {
+        lock (_gate)
+        {
+            ExpireQueued(entry);
+            if (entry.State != "queued") return false;
+            entry.State = "running"; entry.Started = DateTimeOffset.UtcNow;
+            return true;
+        }
+    }
+
+    public void Complete(Entry entry, Reply reply)
+    {
+        lock (_gate)
+        {
+            ExpireQueued(entry);
+            if (entry.Completion == null) return;
+            Finish(entry, reply.Outcome ?? (reply.Status < 400 ? "succeeded" : "failed"), reply);
+        }
+    }
+
+    public object Status(string id)
+    {
+        var parts = id.Split(':');
+        if (parts.Length == 2 && Guid.TryParse(parts[1], out var uuid)) id = parts[0] + ":" + uuid.ToString("N");
+        lock (_gate)
+        {
+            if (!_entries.TryGetValue(id, out var entry)) return new
+            {
+                operation_id = id, bridge_id = Generation, state = "unknown",
+                message = "No receipt exists in this bridge session. The outcome is unknown; this does not prove that the operation never executed. Check the original bridge and model before retrying.",
+            };
+            ExpireQueued(entry);
+            return new
+            {
+                operation_id = id, bridge_id = Generation, tool = entry.Tool, state = entry.State,
+                created_at = entry.Created, started_at = entry.Started, finished_at = entry.Finished,
+                result_available = entry.SavedReply != null, result_http_status = entry.SavedReply?.Status,
+                result = entry.SavedReply?.Response,
+            };
+        }
+    }
+
+    private void ExpireQueued(Entry entry)
+    {
+        if (entry.State == "queued" && Stopwatch.GetTimestamp() > entry.Deadline)
+            Finish(entry, "expired_before_start", new Reply(408, new { error = true, operation_id = entry.Id,
+                message = "Operation expired before it started; no tool action was performed." }));
+    }
+
+    private void Finish(Entry entry, string state, Reply reply)
+    {
+        var completion = entry.Completion!;
+        // Keep a detached JSON value, never API objects or callbacks, in the receipt cache.
+        byte[] bytes;
+        try { bytes = JsonSerializer.SerializeToUtf8Bytes(reply.Response); }
+        catch (Exception error)
+        {
+            state = "result_unavailable";
+            reply = new Reply(500, new { error = true, message = "The tool finished but its receipt could not be serialized. Model or other effects may already have occurred. Inspect before retrying. " + error.Message });
+            bytes = JsonSerializer.SerializeToUtf8Bytes(reply.Response);
+        }
+        entry.State = state; entry.Finished = DateTimeOffset.UtcNow;
+        entry.SavedReply = new Reply(reply.Status, JsonSerializer.Deserialize<JsonElement>(bytes));
+        entry.SavedBytes = bytes.Length; _bytes += bytes.Length;
+        _results.Enqueue(entry);
+        entry.Completion = null;
+        while (_results.Count > _maxResults || _bytes > _maxBytes)
+        {
+            var old = _results.Dequeue();
+            _bytes -= old.SavedBytes; old.SavedBytes = 0; old.SavedReply = null;
+        }
+        completion.TrySetResult(reply);
+    }
+
+    private string ValidateId(string id)
+    {
+        string[] parts = id.Split(':');
+        if (parts.Length != 2 || parts[0] != Generation || !Guid.TryParse(parts[1], out _))
+            throw new ArgumentException("operation_id must contain this bridge session's bridgeId and a UUID. An ID from another bridge/restart cannot be replayed; its outcome must be checked separately.");
+        return parts[0] + ":" + Guid.Parse(parts[1]).ToString("N");
+    }
+
+    private static string Fingerprint(string tool, JsonElement args)
+    {
+        using var stream = new MemoryStream();
+        using (var writer = new Utf8JsonWriter(stream))
+        {
+            void Write(JsonElement element)
+            {
+                if (element.ValueKind == JsonValueKind.Object)
+                {
+                    writer.WriteStartObject();
+                    foreach (var property in element.EnumerateObject().OrderBy(p => p.Name, StringComparer.Ordinal)) { writer.WritePropertyName(property.Name); Write(property.Value); }
+                    writer.WriteEndObject();
+                }
+                else if (element.ValueKind == JsonValueKind.Array)
+                {
+                    writer.WriteStartArray(); foreach (var item in element.EnumerateArray()) Write(item); writer.WriteEndArray();
+                }
+                else element.WriteTo(writer);
+            }
+            writer.WriteStartArray(); writer.WriteStringValue(tool); Write(args); writer.WriteEndArray();
+        }
+        return Convert.ToHexString(SHA256.HashData(stream.ToArray()));
+    }
+}

package/src/Revit/ToolRegistry.cs

@@ -1,5 +1,5 @@
-using System.Text.Json;
-using System.Text.Json.Nodes;
+using System.Text.Json;
+using System.Text.Json.Nodes;
 using Autodesk.Revit.DB;
 using Autodesk.Revit.UI;
 using RevitBridge.Tools;
@@ -15,9 +15,9 @@ namespace RevitBridge
     internal sealed record ToolContext(Document? Document, UIApplication? UIApplication);
 
     /// <summary>
-    /// Optional tool return shape: complete structured payload plus a display summary.
-    /// The bridge/extension expose complete bounded data or explicit result retrieval to
-    /// the model; structured details remain available for rendering and diagnostics.
+    /// Optional tool return shape: complete structured payload plus a display summary.
+    /// The bridge/extension expose complete bounded data or explicit result retrieval to
+    /// the model; structured details remain available for rendering and diagnostics.
     /// </summary>
     internal sealed record ToolOutput(object? Payload, string? CompactText = null);
 
@@ -32,7 +32,10 @@ namespace RevitBridge
         object ParametersSchema { get; }
 
         /// <summary>True only for tools that mutate the model. Write tools own their transaction.</summary>
-        bool Write => false;
+        bool Write => false;
+
+        /// <summary>Potential effects, independent of whether this particular call changes anything.</summary>
+        IReadOnlyList<string> Effects => Write ? new[] { "model" } : Array.Empty<string>();
 
         /// <summary>
         /// False only for tools that never touch the Revit API. They skip the bridge's
@@ -76,7 +79,25 @@ namespace RevitBridge
             registry.Add(new SetParameters());
             registry.Add(new CaptureView());
             registry.Add(new ExportDocuments());
-            registry.Add(new GetModelHealth());
+            registry.Add(new GetModelHealth());
+            registry.Add(new GetLinkedModels());
+            registry.Add(new GetLinkedElements());
+            registry.Add(new GetSchedules());
+            registry.Add(new GetElementRelationships());
+            registry.Add(new SummarizeElements());
+            registry.Add(new ManageElementSets());
+            registry.Add(new TransformElements());
+            registry.Add(new Tools.DeleteElements());
+            registry.Add(new ChangeElementTypes());
+            registry.Add(new ManageViews());
+            registry.Add(new ManageSheets());
+            registry.Add(new ManageSheetPlacements());
+            registry.Add(new GetScheduleFields());
+            registry.Add(new ManageSchedules());
+            registry.Add(new CreateTags());
+            registry.Add(new QuerySpatialElements());
+            registry.Add(new MeasureGeometry());
+            registry.Add(new GetModelCoordinates());
             return registry;
         }
 
@@ -100,36 +121,37 @@ namespace RevitBridge
             description = tool.Description,
             category = tool.Write ? "write" : "read",
             tier = tool.Tier,
-            parameters = DescribeParameters(tool),
+            parameters = DescribeParameters(tool),
             executionMode = "sequential",
-            write = tool.Write,
+            write = tool.Write,
+            effects = tool.Effects,
             requiresDocument = tool.RequiresDocument,
             promptSnippet = tool.PromptSnippet,
-            promptGuidelines = tool.RequiresDocument
-                ? (tool.PromptGuidelines ?? Array.Empty<string>()).Concat(new[]
-                {
-                    $"{tool.Name}: use project.documentId from get_model_overview as expected_document_id to bind the call to that exact open document. It is required for model writes, open_view, and selection changes; legacy expected_document titles alone are insufficient. Refresh after closing/reopening or restarting Revit."
-                }).ToArray()
-                : tool.PromptGuidelines,
-        };
-
-        private static object DescribeParameters(ITool tool)
-        {
-            if (!tool.RequiresDocument) return tool.ParametersSchema;
-            var schema = JsonSerializer.SerializeToNode(tool.ParametersSchema)!.AsObject();
-            var properties = schema["properties"]!.AsObject();
-            properties["expected_document_id"] = new JsonObject
-            {
-                ["type"] = "string",
-                ["description"] = "Exact opaque project.documentId from get_model_overview. Required for document writes and UI mutations; optional for reads. Invalid after close/reopen or bridge restart."
-            };
-            if (DocumentGuard.AlwaysRequiresIdentity(tool.Name))
-            {
-                var required = schema["required"] as JsonArray ?? new JsonArray();
-                if (!required.Any(x => x?.GetValue<string>() == "expected_document_id")) required.Add("expected_document_id");
-                schema["required"] = required;
-            }
-            return schema;
-        }
+            promptGuidelines = tool.RequiresDocument
+                ? (tool.PromptGuidelines ?? Array.Empty<string>()).Concat(new[]
+                {
+                    $"{tool.Name}: use project.documentId from get_model_overview as expected_document_id to bind the call to that exact open document. It is required for model writes, open_view, and selection changes; legacy expected_document titles alone are insufficient. Refresh after closing/reopening or restarting Revit."
+                }).ToArray()
+                : tool.PromptGuidelines,
+        };
+
+        private static object DescribeParameters(ITool tool)
+        {
+            if (!tool.RequiresDocument) return tool.ParametersSchema;
+            var schema = JsonSerializer.SerializeToNode(tool.ParametersSchema)!.AsObject();
+            var properties = schema["properties"]!.AsObject();
+            properties["expected_document_id"] = new JsonObject
+            {
+                ["type"] = "string",
+                ["description"] = "Exact opaque project.documentId from get_model_overview. Required for document writes and UI mutations; optional for reads. Invalid after close/reopen or bridge restart."
+            };
+            if (tool.Write || DocumentGuard.AlwaysRequiresIdentity(tool.Name))
+            {
+                var required = schema["required"] as JsonArray ?? new JsonArray();
+                if (!required.Any(x => x?.GetValue<string>() == "expected_document_id")) required.Add("expected_document_id");
+                schema["required"] = required;
+            }
+            return schema;
+        }
     }
 }

package/src/Revit/Tools/CaptureView.cs

@@ -19,7 +19,8 @@ namespace RevitBridge.Tools
         /// Long enough that a capture is never pulled out from under a session still reading it.</summary>
         private static readonly TimeSpan CaptureRetention = TimeSpan.FromHours(24);
 
-        public string Name => "capture_view";
+        public string Name => "capture_view";
+        public IReadOnlyList<string> Effects => new[] { "files" };
         public string Label => "Capture View";
         public string Description => "Export a PNG snapshot of a Revit view to a temporary file and return its path — the response contains NO image data; open the returned filePath with the read tool to actually see the image. Defaults to the active view; pass view_id for any other graphical view or sheet (find ids with get_elements, category 'Views' or 'Sheets'). The long image edge is capped at 1568 px. Schedules and view templates cannot be captured.";
         public string Tier => "advanced";

package/src/Revit/Tools/ChangeElementTypes.cs

@@ -0,0 +1,60 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class ChangeElementTypes : ITool
+{
+    public string Name => "change_element_types";
+    public string Label => "Change Element Types";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "Change the type of 1–200 elements using explicit element_id/type_id pairs. Revit validates each type against the target; invalid or pinned targets are reported per update. Some type changes replace the original element: always use resulting_id/unique_id afterward. Default partial success; atomic=true rolls back all if any update fails. preview=true commit-validates then rolls back, and replacement IDs from previews are temporary. Revit constraints can affect connected/hosted elements; results describe requested targets, not every dependent effect.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            updates = new { type = "array", minItems = 1, maxItems = 200, items = new
+            {
+                type = "object", properties = new { element_id = new { type = "integer", minimum = 1 }, type_id = new { type = "integer", minimum = 1 } },
+                required = new[] { "element_id", "type_id" },
+            } },
+            preview = ModelEditInputs.PreviewSchema,
+            atomic = new { type = "boolean", description = "Roll back the complete batch if any update fails. Default false." },
+        }, required = new[] { "updates" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        if (!args.TryGetProperty("updates", out var updates) || updates.ValueKind != JsonValueKind.Array || updates.GetArrayLength() is < 1 or > 200)
+            throw new ArgumentException("updates must contain 1–200 element_id/type_id pairs.");
+        var seen = new HashSet<long>();
+        var steps = new List<ModelEditBatch.Step>();
+        foreach (var update in updates.EnumerateArray())
+        {
+            long elementId = JsonArgs.GetLong(update, "element_id") ?? 0;
+            long typeId = JsonArgs.GetLong(update, "type_id") ?? 0;
+            if (elementId <= 0 || typeId <= 0 || !seen.Add(elementId)) throw new ArgumentException("Each update needs positive IDs, and element_id must be unique within the batch.");
+            steps.Add(new(new() { ["element_id"] = elementId, ["type_id"] = typeId }, () =>
+            {
+                var element = doc.GetElement(new ElementId(elementId)) ?? throw new ArgumentException($"Element {elementId} not found.");
+                if (element.Pinned) throw new ArgumentException("Target is pinned; it was not unpinned.");
+                var type = doc.GetElement(new ElementId(typeId)) as ElementType ?? throw new ArgumentException($"Type {typeId} not found.");
+                if (!element.IsValidType(type.Id)) throw new ArgumentException($"Type {typeId} is not valid for element {elementId}.");
+                var before = ModelEditInputs.Snapshot(element);
+                var replacement = element.ChangeTypeId(type.Id);
+                doc.Regenerate();
+                var resultId = replacement == ElementId.InvalidElementId ? new ElementId(elementId) : replacement;
+                var result = doc.GetElement(resultId) ?? throw new InvalidOperationException("Changed element could not be resolved.");
+                return new() { ["before"] = before, ["after"] = ModelEditInputs.Snapshot(result),
+                    ["resulting_id"] = result.Id.Value, ["unique_id"] = result.UniqueId,
+                    ["replaced"] = result.Id.Value != elementId,
+                    ["resulting_id_is_temporary"] = result.Id.Value != elementId && JsonArgs.GetBool(args, "preview", false) };
+            }));
+        }
+        var batch = ModelEditBatch.Run(doc, Name, args, steps);
+        foreach (var row in batch.Proposed)
+            if (row["replaced"] is true) row["resulting_id_is_temporary"] = true;
+        return batch.Payload;
+    }
+}

package/src/Revit/Tools/CreateTags.cs

@@ -0,0 +1,95 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+using Autodesk.Revit.DB.Architecture;
+using Autodesk.Revit.DB.Mechanical;
+
+namespace RevitBridge.Tools;
+
+internal sealed class CreateTags : ITool
+{
+    public string Name => "create_tags";
+    public string Label => "Create Tags";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "Create up to 100 tags for host-document elements in one explicit view using a loaded tag FamilySymbol. kind=element uses IndependentTag; room, space and area use their corresponding spatial tag APIs. Targets contain element_id and head_position [x,y,z] in document internal coordinates with explicit length unit. head_position always means the tag head, including with leader=true. Spatial tags require a compatible plan view and positions at that spatial element's level; orientation applies only to element tags. Templates, perspective views and unlocked 3D views cannot host independent tags. Default partial success; atomic=true rolls back all on any failure. preview=true commit-validates then rolls back; all proposed tag IDs are temporary. Linked targets and face/subelement references are outside this tool.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            kind = new { type = "string", @enum = new[] { "element", "room", "space", "area" } },
+            view_id = new { type = "integer", minimum = 1 }, tag_type_id = new { type = "integer", minimum = 1 }, unit = ModelEditInputs.LengthUnitSchema,
+            targets = new { type = "array", minItems = 1, maxItems = 100, items = new { type = "object", properties = new { element_id = new { type = "integer", minimum = 1 }, head_position = ModelEditInputs.VectorSchema("Tag head in document internal coordinates, in unit.") }, required = new[] { "element_id", "head_position" } } },
+            leader = new { type = "boolean" }, orientation = new { type = "string", @enum = new[] { "horizontal", "vertical" } },
+            preview = ModelEditInputs.PreviewSchema, atomic = new { type = "boolean" },
+        }, required = new[] { "kind", "view_id", "tag_type_id", "unit", "targets" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        string kind = JsonArgs.GetString(args, "kind") ?? "";
+        if (kind is not ("element" or "room" or "space" or "area")) throw new ArgumentException("Unknown tag kind.");
+        var view = doc.GetElement(new ElementId(JsonArgs.GetLong(args, "view_id") ?? 0)) as View ?? throw new ArgumentException("view_id is not a view.");
+        if (view.IsTemplate || (view is View3D three && (three.IsPerspective || !three.IsLocked))) throw new ArgumentException("Tags require a non-template view; 3D views must be orthographic and locked.");
+        if (kind != "element" && view is not ViewPlan) throw new ArgumentException("Spatial tags require a plan view.");
+        var type = doc.GetElement(new ElementId(JsonArgs.GetLong(args, "tag_type_id") ?? 0)) as FamilySymbol ?? throw new ArgumentException("tag_type_id must identify a loaded tag FamilySymbol.");
+        bool leader = false;
+        if (args.TryGetProperty("leader", out var leaderValue))
+        {
+            if (leaderValue.ValueKind is not (JsonValueKind.True or JsonValueKind.False)) throw new ArgumentException("leader must be boolean.");
+            leader = leaderValue.GetBoolean();
+        }
+        if (kind != "element" && args.TryGetProperty("orientation", out _)) throw new ArgumentException("orientation applies only to element tags.");
+        var orientation = (JsonArgs.GetString(args, "orientation") ?? "horizontal") switch
+        {
+            "horizontal" => TagOrientation.Horizontal, "vertical" => TagOrientation.Vertical, _ => throw new ArgumentException("Invalid orientation."),
+        };
+        if (!args.TryGetProperty("targets", out var targets) || targets.ValueKind != JsonValueKind.Array || targets.GetArrayLength() is < 1 or > 100) throw new ArgumentException("targets must contain 1–100 tag requests.");
+        double scale = ModelEditInputs.LengthScale(args);
+        var steps = new List<ModelEditBatch.Step>();
+        foreach (var input in targets.EnumerateArray())
+        {
+            if (input.ValueKind != JsonValueKind.Object) throw new ArgumentException("Each target must be an object.");
+            long id = JsonArgs.GetLong(input, "element_id") ?? 0;
+            if (id <= 0) throw new ArgumentException("Target element_id must be positive.");
+            var point = ModelEditInputs.Vector(input, "head_position").Multiply(scale);
+            steps.Add(new(new() { ["element_id"] = id }, () =>
+            {
+                var element = doc.GetElement(new ElementId(id)) ?? throw new ArgumentException($"Element {id} not found.");
+                if (!type.IsActive) { type.Activate(); doc.Regenerate(); }
+                Element tag;
+                if (kind == "element")
+                {
+                    var independent = IndependentTag.Create(doc, type.Id, view.Id, new Reference(element), false, orientation, point);
+                    independent.HasLeader = leader;
+                    independent.TagHeadPosition = point;
+                    tag = independent;
+                }
+                else
+                {
+                    if (element.Location is not LocationPoint location || view.GenLevel == null || element.LevelId != view.GenLevel.Id)
+                        throw new ArgumentException("A spatial tag target must be placed on the plan view's level.");
+                    var anchor = new UV(location.Point.X, location.Point.Y);
+                    SpatialElementTag spatial = kind switch
+                    {
+                        "room" when element is Room => doc.Create.NewRoomTag(new LinkElementId(element.Id), anchor, view.Id),
+                        "space" when element is Space space => doc.Create.NewSpaceTag(space, anchor, view),
+                        "area" when element is Area area => doc.Create.NewAreaTag((ViewPlan)view, area, anchor),
+                        _ => throw new ArgumentException($"Element {id} does not match kind {kind}."),
+                    };
+                    if (!spatial.IsValidType(type.Id)) throw new ArgumentException("Tag type does not match the spatial tag category.");
+                    var replacement = spatial.ChangeTypeId(type.Id);
+                    if (replacement != ElementId.InvalidElementId) spatial = (SpatialElementTag)doc.GetElement(replacement);
+                    spatial.HasLeader = leader; spatial.TagHeadPosition = point;
+                    tag = spatial;
+                }
+                doc.Regenerate();
+                var actual = tag is IndependentTag independentResult ? independentResult.TagHeadPosition : ((SpatialElementTag)tag).TagHeadPosition;
+                return new() { ["tag_id"] = tag.Id.Value, ["unique_id"] = tag.UniqueId, ["tag_type_id"] = tag.GetTypeId().Value, ["view_id"] = tag.OwnerViewId.Value,
+                    ["kind"] = kind, ["head_position"] = new[] { actual.X, actual.Y, actual.Z }, ["unit"] = "feet", ["leader"] = leader, ["id_is_temporary"] = false };
+            }));
+        }
+        var batch = ModelEditBatch.Run(doc, Name, args, steps);
+        foreach (var row in batch.Proposed) row["id_is_temporary"] = true;
+        return batch.Payload;
+    }
+}

package/src/Revit/Tools/DeleteElements.cs

@@ -0,0 +1,44 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class DeleteElements : ITool
+{
+    public string Name => "delete_elements";
+    public string Label => "Delete Elements";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "Delete 1–200 explicitly selected elements in one atomic step, returning the full set of IDs returned by Revit's deletion API, including dependents. Use preview=true to inspect that set with commit validation and confirmed rollback. Optional expected_deleted_ids rejects a changed deletion set before commit; pass the full preview set to bind a later deletion to that set. Pinned requested elements are rejected. At most 10,000 deleted IDs are permitted; a larger cascade rolls back. Returned IDs include dependencies removed by Document.Delete, not a complete audit of surviving elements modified by Revit.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            element_ids = ModelEditInputs.IdsSchema,
+            preview = ModelEditInputs.PreviewSchema,
+            expected_deleted_ids = new { type = "array", minItems = 1, maxItems = 10000, uniqueItems = true, items = new { type = "integer", minimum = 1 }, description = "Exact full deleted_ids set from a previous preview; mismatches roll back." },
+        }, required = new[] { "element_ids" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        var ids = ModelEditInputs.Ids(args);
+        List<long>? expected = args.TryGetProperty("expected_deleted_ids", out _) ? JsonArgs.GetLongArray(args, "expected_deleted_ids") : null;
+        if (expected != null && (expected.Count is < 1 or > 10000 || expected.Any(x => x <= 0) || expected.Distinct().Count() != expected.Count))
+            throw new ArgumentException("expected_deleted_ids must contain 1–10,000 distinct positive IDs.");
+        return ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(
+            new() { ["element_ids"] = ids.Select(x => x.Value).ToArray() }, () =>
+            {
+                foreach (var id in ids)
+                {
+                    var element = doc.GetElement(id) ?? throw new ArgumentException($"Element {id.Value} not found.");
+                    if (element.Pinned) throw new ArgumentException($"Element {id.Value} is pinned; no elements were unpinned.");
+                }
+                var deleted = doc.Delete(ids).Select(id => id.Value).OrderBy(id => id).ToArray();
+                if (deleted.Length > 10000) throw new ArgumentException("Deletion exceeds the 10,000-ID cascade limit.");
+                if (expected != null && !deleted.ToHashSet().SetEquals(expected)) throw new ArgumentException("The deletion set changed since the preview; deletion was rolled back. Run a fresh preview.");
+                return new() { ["deleted_ids"] = deleted, ["deleted_count"] = deleted.Length,
+                    ["dependent_ids"] = deleted.Except(ids.Select(x => x.Value)).ToArray() };
+            }) }).Payload;
+    }
+}

package/src/Revit/Tools/DocumentGuard.cs

@@ -1,64 +1,64 @@
-using System.Text.Json;
-using Autodesk.Revit.DB;
-
-namespace RevitBridge.Tools;
-
-/// <summary>Opaque identity of one open native document in this loaded bridge session.</summary>
-internal static class DocumentGuard
-{
-    private sealed record Identity(Document Document, string Value);
-    private static readonly string Generation = Guid.NewGuid().ToString("N");
-    private static readonly List<Identity> Identities = new();
-
-    public static string GetIdentity(Document document)
-    {
-        if (!document.IsValidObject)
-            throw new ArgumentException("The target document is closed or invalid. Read get_model_overview again.");
-        // Revit can supply multiple managed wrappers for the same native document.
-        // Its documented Equals semantics identify that native document; reference identity cannot.
-        // All accesses happen on the Revit API thread. Pruning avoids retaining closed documents.
-        Identities.RemoveAll(entry => !entry.Document.IsValidObject);
-        var existing = Identities.FirstOrDefault(entry => entry.Document.Equals(document));
-        if (existing != null) return existing.Value;
-        var created = new Identity(document, Generation + ":" + Guid.NewGuid().ToString("N"));
-        Identities.Add(created);
-        return created.Value;
-    }
-
-    public static bool AlwaysRequiresIdentity(string toolName)
-        => toolName is "set_parameters" or "execute_csharp" or "export_documents" or "open_view";
-
-    /// <summary>Must run on the Revit API thread immediately before the tool action.</summary>
-    public static void CheckForTool(JsonElement args, Document document, string toolName)
-    {
-        bool required = AlwaysRequiresIdentity(toolName)
-            || (toolName == "manage_selection"
-                && (!string.Equals((JsonArgs.GetString(args, "action") ?? "get").Trim(), "get", StringComparison.OrdinalIgnoreCase)
-                    || JsonArgs.GetBool(args, "isolate_in_view", false)));
-        if (required && !args.TryGetProperty("expected_document_id", out _))
-            throw new ArgumentException("expected_document_id is required for this operation. Read project.documentId from get_model_overview for the intended open document and pass it unchanged. A title alone cannot identify a document. No action was performed.");
-        CheckExpectedDocument(args, document);
-    }
-
-    public static void CheckExpectedDocument(JsonElement args, Document document)
-    {
-        if (args.TryGetProperty("expected_document_id", out var id))
-        {
-            if (id.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(id.GetString()))
-                throw new ArgumentException("expected_document_id must be a non-empty identity from get_model_overview. No action was performed.");
-            if (!string.Equals(id.GetString(), GetIdentity(document), StringComparison.Ordinal))
-                throw new ArgumentException($"The active document '{document.Title}' is not the exact open document this call expected, or that identity is stale after reopening/restarting. No action was performed. Activate the intended document and read get_model_overview again.");
-        }
-
-        // Retained as an additional human-readable check, never as a substitute for identity.
-        string? expected = JsonArgs.GetString(args, "expected_document");
-        if (string.IsNullOrWhiteSpace(expected)) return;
-        static string Normalize(string title)
-        {
-            string value = title.Trim();
-            return value.EndsWith(".rvt", StringComparison.OrdinalIgnoreCase) ? value[..^4] : value;
-        }
-        if (!string.Equals(Normalize(expected), Normalize(document.Title), StringComparison.OrdinalIgnoreCase))
-            throw new ArgumentException($"Active document is '{document.Title}' but this call expected title '{expected}'. No action was performed. Read get_model_overview for the intended document.");
-    }
-}
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+/// <summary>Opaque identity of one open native document in this loaded bridge session.</summary>
+internal static class DocumentGuard
+{
+    private sealed record Identity(Document Document, string Value);
+    private static readonly string Generation = Guid.NewGuid().ToString("N");
+    private static readonly List<Identity> Identities = new();
+
+    public static string GetIdentity(Document document)
+    {
+        if (!document.IsValidObject)
+            throw new ArgumentException("The target document is closed or invalid. Read get_model_overview again.");
+        // Revit can supply multiple managed wrappers for the same native document.
+        // Its documented Equals semantics identify that native document; reference identity cannot.
+        // All accesses happen on the Revit API thread. Pruning avoids retaining closed documents.
+        Identities.RemoveAll(entry => !entry.Document.IsValidObject);
+        var existing = Identities.FirstOrDefault(entry => entry.Document.Equals(document));
+        if (existing != null) return existing.Value;
+        var created = new Identity(document, Generation + ":" + Guid.NewGuid().ToString("N"));
+        Identities.Add(created);
+        return created.Value;
+    }
+
+    public static bool AlwaysRequiresIdentity(string toolName)
+        => toolName is "set_parameters" or "execute_csharp" or "export_documents" or "open_view";
+
+    /// <summary>Must run on the Revit API thread immediately before the tool action.</summary>
+    public static void CheckForTool(JsonElement args, Document document, string toolName, bool writes = false)
+    {
+        bool required = writes || AlwaysRequiresIdentity(toolName)
+            || (toolName == "manage_selection"
+                && (!string.Equals((JsonArgs.GetString(args, "action") ?? "get").Trim(), "get", StringComparison.OrdinalIgnoreCase)
+                    || JsonArgs.GetBool(args, "isolate_in_view", false)));
+        if (required && !args.TryGetProperty("expected_document_id", out _))
+            throw new ArgumentException("expected_document_id is required for this operation. Read project.documentId from get_model_overview for the intended open document and pass it unchanged. A title alone cannot identify a document. No action was performed.");
+        CheckExpectedDocument(args, document);
+    }
+
+    public static void CheckExpectedDocument(JsonElement args, Document document)
+    {
+        if (args.TryGetProperty("expected_document_id", out var id))
+        {
+            if (id.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(id.GetString()))
+                throw new ArgumentException("expected_document_id must be a non-empty identity from get_model_overview. No action was performed.");
+            if (!string.Equals(id.GetString(), GetIdentity(document), StringComparison.Ordinal))
+                throw new ArgumentException($"The active document '{document.Title}' is not the exact open document this call expected, or that identity is stale after reopening/restarting. No action was performed. Activate the intended document and read get_model_overview again.");
+        }
+
+        // Retained as an additional human-readable check, never as a substitute for identity.
+        string? expected = JsonArgs.GetString(args, "expected_document");
+        if (string.IsNullOrWhiteSpace(expected)) return;
+        static string Normalize(string title)
+        {
+            string value = title.Trim();
+            return value.EndsWith(".rvt", StringComparison.OrdinalIgnoreCase) ? value[..^4] : value;
+        }
+        if (!string.Equals(Normalize(expected), Normalize(document.Title), StringComparison.OrdinalIgnoreCase))
+            throw new ArgumentException($"Active document is '{document.Title}' but this call expected title '{expected}'. No action was performed. Read get_model_overview for the intended document.");
+    }
+}