pi-revit 0.3.1 → 0.5.0

package/skills/pi-revit/tool-manifest.json

@@ -0,0 +1,338 @@
+{
+  "schema_version": 2,
+  "description": "Hand-maintained documentation index: one summary and group per public tool, plus guidance resources. Executable contracts (schemas, effects, keywords, limits, verification) are owned by code and generated into contracts.generated.json.",
+  "documentation_revision": "2026-09-29.1",
+  "groups": [
+    {
+      "id": "connection",
+      "title": "Connection, discovery, and local utilities"
+    },
+    {
+      "id": "inspection",
+      "title": "Model inspection and review"
+    },
+    {
+      "id": "spatial",
+      "title": "Links, coordinates, and spatial analysis"
+    },
+    {
+      "id": "editing",
+      "title": "Selection and editing"
+    },
+    {
+      "id": "drawings",
+      "title": "Drawings, schedules, and delivery"
+    },
+    {
+      "id": "api",
+      "title": "API and custom execution"
+    }
+  ],
+  "tools": [
+    {
+      "name": "capture_view",
+      "source": "bridge",
+      "group": "drawings",
+      "summary": "Capture a view as an image for visual verification."
+    },
+    {
+      "name": "change_element_types",
+      "source": "bridge",
+      "group": "editing",
+      "summary": "Change element types with partial or atomic outcomes."
+    },
+    {
+      "name": "create_tags",
+      "source": "bridge",
+      "group": "drawings",
+      "summary": "Create host element, room, space and area tags."
+    },
+    {
+      "name": "delete_elements",
+      "source": "bridge",
+      "group": "editing",
+      "summary": "Preview or perform deletion including dependent elements."
+    },
+    {
+      "name": "execute_csharp",
+      "source": "bridge",
+      "group": "api",
+      "summary": "Execute custom synchronous C# in Revit."
+    },
+    {
+      "name": "export_documents",
+      "source": "bridge",
+      "group": "drawings",
+      "summary": "Export sheets, views or the model to PDF, DWG, PNG or IFC."
+    },
+    {
+      "name": "find_revit_tools",
+      "source": "native",
+      "group": "connection",
+      "summary": "Discover tools, activate capabilities, or find packaged documentation."
+    },
+    {
+      "name": "get_element_details",
+      "source": "bridge",
+      "group": "inspection",
+      "summary": "Inspect element parameters, geometry bounds and identity."
+    },
+    {
+      "name": "get_element_relationships",
+      "source": "bridge",
+      "group": "inspection",
+      "summary": "Inspect hosts, joined elements, members and dependents."
+    },
+    {
+      "name": "get_element_types",
+      "source": "bridge",
+      "group": "inspection",
+      "summary": "Discover available element types and family symbols."
+    },
+    {
+      "name": "get_elements",
+      "source": "bridge",
+      "group": "inspection",
+      "summary": "Query, count and filter elements and project parameter values."
+    },
+    {
+      "name": "get_linked_elements",
+      "source": "bridge",
+      "group": "spatial",
+      "summary": "Query elements inside a selected linked document."
+    },
+    {
+      "name": "get_linked_models",
+      "source": "bridge",
+      "group": "spatial",
+      "summary": "Discover loaded and unloaded Revit link instances."
+    },
+    {
+      "name": "get_model_coordinates",
+      "source": "bridge",
+      "group": "spatial",
+      "summary": "Read base points, project locations and shared-coordinate mappings."
+    },
+    {
+      "name": "get_model_health",
+      "source": "bridge",
+      "group": "inspection",
+      "summary": "Inspect model warnings and health information."
+    },
+    {
+      "name": "get_model_overview",
+      "source": "bridge",
+      "group": "inspection",
+      "summary": "Inspect project identity, units, levels and category counts."
+    },
+    {
+      "name": "get_revit_operation",
+      "source": "native",
+      "group": "connection",
+      "summary": "Inspect an original operation receipt after uncertain results."
+    },
+    {
+      "name": "get_schedule_fields",
+      "source": "bridge",
+      "group": "drawings",
+      "summary": "Discover eligible parameter and field-type pairs."
+    },
+    {
+      "name": "get_schedules",
+      "source": "bridge",
+      "group": "drawings",
+      "summary": "Inspect schedule fields, sorting, filters and table cells."
+    },
+    {
+      "name": "manage_element_sets",
+      "source": "bridge",
+      "group": "inspection",
+      "summary": "Retain query membership and reread current member values."
+    },
+    {
+      "name": "manage_revit_instances",
+      "source": "native",
+      "group": "connection",
+      "summary": "List and select local Revit bridge sessions."
+    },
+    {
+      "name": "manage_revit_scripts",
+      "source": "native",
+      "group": "connection",
+      "summary": "Save, inspect and run exact versions of reusable scripts."
+    },
+    {
+      "name": "manage_schedules",
+      "source": "bridge",
+      "group": "drawings",
+      "summary": "Create and configure schedules, fields, filters and sorting."
+    },
+    {
+      "name": "manage_selection",
+      "source": "bridge",
+      "group": "editing",
+      "summary": "Read or change selection, zoom and temporary isolation."
+    },
+    {
+      "name": "manage_sheet_placements",
+      "source": "bridge",
+      "group": "drawings",
+      "summary": "List, place and move viewports and schedules on sheets."
+    },
+    {
+      "name": "manage_sheets",
+      "source": "bridge",
+      "group": "drawings",
+      "summary": "Create, rename and renumber sheets."
+    },
+    {
+      "name": "manage_views",
+      "source": "bridge",
+      "group": "drawings",
+      "summary": "Create, duplicate and update plans, sections and 3D views."
+    },
+    {
+      "name": "measure_geometry",
+      "source": "bridge",
+      "group": "spatial",
+      "summary": "Measure point distance or approximate element bounding-box gaps."
+    },
+    {
+      "name": "open_view",
+      "source": "bridge",
+      "group": "editing",
+      "summary": "Activate a Revit view or sheet."
+    },
+    {
+      "name": "ping",
+      "source": "native",
+      "group": "connection",
+      "summary": "Check Revit bridge availability and versions."
+    },
+    {
+      "name": "query_spatial_elements",
+      "source": "bridge",
+      "group": "spatial",
+      "summary": "Query elements by bounding-box intersection or containment."
+    },
+    {
+      "name": "read_revit_result",
+      "source": "native",
+      "group": "connection",
+      "summary": "Read saved large results in bounded fragments."
+    },
+    {
+      "name": "search_api_docs",
+      "source": "bridge",
+      "group": "api",
+      "summary": "Search installed Revit API classes, methods, signatures and enums."
+    },
+    {
+      "name": "set_parameters",
+      "source": "bridge",
+      "group": "editing",
+      "summary": "Edit or preview parameter values with optional atomic rollback."
+    },
+    {
+      "name": "summarize_elements",
+      "source": "bridge",
+      "group": "inspection",
+      "summary": "Count a whole element query grouped by type, category, level or parameter."
+    },
+    {
+      "name": "transform_elements",
+      "source": "bridge",
+      "group": "editing",
+      "summary": "Move, copy or rotate elements with preview rollback."
+    }
+  ],
+  "guidance": [
+    {
+      "name": "execution-rules",
+      "kind": "reference",
+      "path": "references/execution-rules.md",
+      "summary": "Shared rules for model targeting, document identity, parameters, units and transactions.",
+      "keywords": [
+        "identity",
+        "document id",
+        "expected_document_id",
+        "units",
+        "parameters",
+        "transactions",
+        "preview",
+        "atomic",
+        "localized names"
+      ]
+    },
+    {
+      "name": "operation-recovery",
+      "kind": "reference",
+      "path": "references/operation-recovery.md",
+      "summary": "Recover after timeouts, cancellations and uncertain outcomes using operation receipts.",
+      "keywords": [
+        "timeout",
+        "retry",
+        "receipt",
+        "uncertain",
+        "failed",
+        "bridge unavailable",
+        "no document"
+      ]
+    },
+    {
+      "name": "visual-verification",
+      "kind": "reference",
+      "path": "references/visual-verification.md",
+      "summary": "Capture and inspect visible results and exported deliverables, then stop when the request is verified.",
+      "keywords": [
+        "verify",
+        "visual check",
+        "drawing check",
+        "image",
+        "overlap",
+        "layout",
+        "deliverable"
+      ]
+    },
+    {
+      "name": "tool-index",
+      "kind": "reference",
+      "path": "references/tool-index.md",
+      "summary": "Every public tool grouped by task, with manual links.",
+      "keywords": [
+        "tools",
+        "capabilities",
+        "tool list",
+        "manuals"
+      ]
+    },
+    {
+      "name": "room-documentation",
+      "kind": "workflow",
+      "path": "references/room-documentation.md",
+      "summary": "Room plans, sections, tags, schedules and sheets as one documentation workflow.",
+      "keywords": [
+        "rooms",
+        "room plan",
+        "room tags",
+        "room schedule",
+        "room sheets",
+        "room documentation"
+      ]
+    },
+    {
+      "name": "model-audit-export",
+      "kind": "workflow",
+      "path": "references/model-audit-export.md",
+      "summary": "Multi-step model audit, data review and requested exports.",
+      "keywords": [
+        "audit",
+        "review",
+        "model quality",
+        "export",
+        "report",
+        "data review"
+      ]
+    }
+  ]
+}

package/src/Revit/BridgeServer.cs

@@ -40,6 +40,7 @@ namespace RevitBridge
         private readonly ToolRegistry _registry;
         private readonly string _revitVersion;
         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>
@@ -120,14 +121,20 @@ namespace RevitBridge
         private void WriteBridgeInfo()
         {
             Directory.CreateDirectory(BridgeInfoDirectory());
-            File.WriteAllText(BridgeInfoPath(), JsonSerializer.Serialize(new
+            string json = JsonSerializer.Serialize(new
             {
                 baseUrl = $"http://127.0.0.1:{_port}",
                 token = _token,
                 pid = Environment.ProcessId,
                 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
             {
@@ -401,32 +404,85 @@ namespace RevitBridge
 
             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);
-                        return tool.Execute(args, new ToolContext(document, uiApp));
+                        RevitBridge.Tools.DocumentGuard.CheckForTool(args, document, tool.Name, tool.Write);
+                        // A tool declared for other document kinds is refused before it runs (inv:document-kind-declared).
+                        RevitBridge.Tools.DocumentGuard.CheckKind(tool, document);
+                        // Every tool that can change the model reports what it changed (model_changes),
+                        // without tool-specific code, so future tools inherit it.
+                        using var changes = RevitBridge.Tools.ModelChangeRecorder.For(tool, uiApp.Application, document);
+                        var result = tool.Execute(args, new ToolContext(document, uiApp));
+                        return changes == null ? result : changes.Attach(result);
                     }, 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));
+                    : 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");
+                }
 
-                return (200, BuildToolResponse(name, output));
+                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()));
+    }
+}