pi-revit 0.3.0 → 0.4.0

package/src/Revit/BridgeServer.cs

@@ -39,7 +39,8 @@ namespace RevitBridge
         private readonly CommandQueue _queue;
         private readonly ToolRegistry _registry;
         private readonly string _revitVersion;
-        private readonly Func<bool> _hasOpenDocument;
+        private readonly Func<bool> _hasOpenDocument;
+        private readonly OperationStore _operations = new();
 
         /// <summary>How often the bridge re-checks that bridge.json still points somewhere
         /// live (see EnsureBridgeInfo). Cheap: one small file read per tick.</summary>
@@ -117,17 +118,23 @@ namespace RevitBridge
 
         public static string BridgeInfoPath() => Path.Combine(BridgeInfoDirectory(), "bridge.json");
 
-        private void WriteBridgeInfo()
-        {
-            Directory.CreateDirectory(BridgeInfoDirectory());
-            File.WriteAllText(BridgeInfoPath(), JsonSerializer.Serialize(new
+        private void WriteBridgeInfo()
+        {
+            Directory.CreateDirectory(BridgeInfoDirectory());
+            string json = JsonSerializer.Serialize(new
             {
                 baseUrl = $"http://127.0.0.1:{_port}",
                 token = _token,
                 pid = Environment.ProcessId,
-                revitVersion = _revitVersion,
+                revitVersion = _revitVersion,
+                bridgeId = _operations.Generation,
+                supportsOperationTracking = true,
                 startedAtUtc = DateTime.UtcNow.ToString("o"),
-            }, new JsonSerializerOptions { WriteIndented = true }));
+            }, new JsonSerializerOptions { WriteIndented = true });
+            string instances = Path.Combine(BridgeInfoDirectory(), "instances");
+            Directory.CreateDirectory(instances);
+            File.WriteAllText(Path.Combine(instances, _operations.Generation + ".json"), json);
+            File.WriteAllText(BridgeInfoPath(), json);
         }
 
         /// <summary>
@@ -186,8 +193,9 @@ namespace RevitBridge
             }
         }
 
-        private static void DeleteBridgeInfoIfOwned()
-        {
+        private void DeleteBridgeInfoIfOwned()
+        {
+            try { File.Delete(Path.Combine(BridgeInfoDirectory(), "instances", _operations.Generation + ".json")); } catch { }
             try
             {
                 string path = BridgeInfoPath();
@@ -337,7 +345,10 @@ namespace RevitBridge
         private async Task<(int Status, object Response)> RouteAsync(string method, string path, Dictionary<string, string> query, string body, CancellationToken token)
         {
             if (method == "GET" && path == "/ping")
-                return (200, new { ok = true, service = "revit-bridge", revitVersion = _revitVersion, pid = Environment.ProcessId, addinVersion = AddinVersion });
+                return (200, new { ok = true, service = "revit-bridge", revitVersion = _revitVersion, pid = Environment.ProcessId, addinVersion = AddinVersion, bridgeId = _operations.Generation, supportsOperationTracking = true });
+
+            if (method == "GET" && path.StartsWith("/operations/", StringComparison.Ordinal))
+                return (200, _operations.Status(WebUtility.UrlDecode(path["/operations/".Length..])));
 
             if (method == "GET" && path == "/tools")
             {
@@ -378,14 +389,6 @@ namespace RevitBridge
             if (tool is null)
                 return (404, new { error = true, message = $"Unknown tool: {name}" });
 
-            // Pre-check before enqueueing: with zero documents open Revit does not
-            // pump ExternalEvents, so a queued call would hang instead of failing.
-            // The in-queue NoActiveDocumentException below remains as the backstop
-            // for a document closing between this check and execution. Tools that
-            // never touch the Revit API (RequiresDocument = false) skip the gate.
-            if (tool.RequiresDocument && !_hasOpenDocument())
-                return (409, new { error = true, hasActiveDocument = false, message = "No active Revit document is open." });
-
             JsonElement args;
             try
             {
@@ -399,34 +402,81 @@ namespace RevitBridge
                 return (400, new { error = true, message = $"Invalid JSON tool arguments: {ex.Message}" });
             }
 
-            int timeoutMs = ResolveTimeoutMs(query);
-
-            try
+            int timeoutMs = ResolveTimeoutMs(query);
+
+            if (query.TryGetValue("operation_id", out string? operationId))
+            {
+                try
+                {
+                    var (entry, isNew) = _operations.Reserve(operationId, name, args, TimeSpan.FromMilliseconds(timeoutMs));
+                    var completion = _operations.Wait(entry);
+                    if (isNew) _ = CompleteTrackedOperationAsync(entry, tool, args, timeoutMs);
+                    var reply = await completion;
+                    return (reply.Status, reply.Response);
+                }
+                catch (ArgumentException error) { return (409, new { error = true, message = error.Message, operation_id = operationId }); }
+                catch (InvalidOperationException error) { return (503, new { error = true, message = error.Message, operation_id = operationId }); }
+            }
+            var result = await RunToolAsync(tool, args, timeoutMs, null);
+            return (result.Status, result.Response);
+        }
+
+        private async Task CompleteTrackedOperationAsync(OperationStore.Entry entry, ITool tool, JsonElement args, int timeoutMs)
+        {
+            var reply = await RunToolAsync(tool, args, timeoutMs, entry);
+            _operations.Complete(entry, new OperationStore.Reply(reply.Status, reply.Response, reply.Outcome));
+        }
+
+        private async Task<(int Status, object Response, string? Outcome)> RunToolAsync(ITool tool, JsonElement args, int timeoutMs, OperationStore.Entry? operation)
+        {
+            string name = tool.Name;
+            // Cached receipts remain accessible even when the active document closes.
+            if (tool.RequiresDocument && !_hasOpenDocument())
+                return (409, new { error = true, hasActiveDocument = false, message = "No active Revit document is open." }, null);
+
+            void StartOperation()
+            {
+                if (operation != null && !_operations.TryStart(operation)) throw new TimeoutException("Operation expired before execution; no tool action was performed.");
+            }
+
+            try
             {
                 object? output = tool.RequiresDocument
                     ? await _queue.RunAsync(uiApp =>
-                    {
+                    {
+                        StartOperation();
                         var document = uiApp.ActiveUIDocument?.Document ?? throw new NoActiveDocumentException();
-                        RevitBridge.Tools.DocumentGuard.CheckForTool(args, document, tool.Name);
+                        RevitBridge.Tools.DocumentGuard.CheckForTool(args, document, tool.Name, tool.Write);
                         return tool.Execute(args, new ToolContext(document, uiApp));
                     }, TimeSpan.FromMilliseconds(timeoutMs))
                     // RequiresDocument = false tools never touch the Revit API, so they
                     // run right here on the server task instead of the CommandQueue.
-                    : tool.Execute(args, new ToolContext(null, null));
-
-                return (200, BuildToolResponse(name, output));
+                    : ExecuteWithoutDocument();
+
+                try { return (200, BuildToolResponse(name, output), null); }
+                catch (Exception error)
+                {
+                    return (500, new { error = true, toolName = name, result_unavailable = true,
+                        message = "The tool finished, but its response could not be constructed. Model or other effects may already have occurred; inspect them before retrying. " + error.Message }, "result_unavailable");
+                }
+
+                object? ExecuteWithoutDocument()
+                {
+                    StartOperation();
+                    return tool.Execute(args, new ToolContext(null, null));
+                }
             }
             catch (NoActiveDocumentException ex)
             {
-                return (409, new { error = true, hasActiveDocument = false, message = ex.Message });
+                return (409, new { error = true, hasActiveDocument = false, message = ex.Message }, null);
             }
             catch (ArgumentException ex)
             {
-                return (400, new { error = true, toolName = name, message = ex.Message });
+                return (400, new { error = true, toolName = name, message = ex.Message }, null);
             }
             catch (Exception ex)
             {
-                return (500, new { error = true, toolName = name, message = ex.Message });
+                return (500, new { error = true, toolName = name, message = ex.Message }, null);
             }
         }
 

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

@@ -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;
         }
 
@@ -102,7 +123,8 @@ namespace RevitBridge
             tier = tool.Tier,
             parameters = DescribeParameters(tool),
             executionMode = "sequential",
-            write = tool.Write,
+            write = tool.Write,
+            effects = tool.Effects,
             requiresDocument = tool.RequiresDocument,
             promptSnippet = tool.PromptSnippet,
             promptGuidelines = tool.RequiresDocument
@@ -123,7 +145,7 @@ namespace RevitBridge
                 ["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))
+            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");

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

@@ -29,9 +29,9 @@ internal static class DocumentGuard
         => 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)
+    public static void CheckForTool(JsonElement args, Document document, string toolName, bool writes = false)
     {
-        bool required = AlwaysRequiresIdentity(toolName)
+        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)));