pi-revit 0.4.0 → 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

@@ -39,8 +39,8 @@ namespace RevitBridge
         private readonly CommandQueue _queue;
         private readonly ToolRegistry _registry;
         private readonly string _revitVersion;
-        private readonly Func<bool> _hasOpenDocument;
-        private readonly OperationStore _operations = new();
+        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>
@@ -118,23 +118,23 @@ namespace RevitBridge
 
         public static string BridgeInfoPath() => Path.Combine(BridgeInfoDirectory(), "bridge.json");
 
-        private void WriteBridgeInfo()
-        {
-            Directory.CreateDirectory(BridgeInfoDirectory());
-            string json = 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,
-                bridgeId = _operations.Generation,
-                supportsOperationTracking = true,
+                revitVersion = _revitVersion,
+                bridgeId = _operations.Generation,
+                supportsOperationTracking = true,
                 startedAtUtc = DateTime.UtcNow.ToString("o"),
-            }, 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);
+            }, 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>
@@ -193,9 +193,9 @@ namespace RevitBridge
             }
         }
 
-        private void DeleteBridgeInfoIfOwned()
-        {
-            try { File.Delete(Path.Combine(BridgeInfoDirectory(), "instances", _operations.Generation + ".json")); } catch { }
+        private void DeleteBridgeInfoIfOwned()
+        {
+            try { File.Delete(Path.Combine(BridgeInfoDirectory(), "instances", _operations.Generation + ".json")); } catch { }
             try
             {
                 string path = BridgeInfoPath();
@@ -345,10 +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, bridgeId = _operations.Generation, supportsOperationTracking = true });
-
-            if (method == "GET" && path.StartsWith("/operations/", StringComparison.Ordinal))
-                return (200, _operations.Status(WebUtility.UrlDecode(path["/operations/".Length..])));
+                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")
             {
@@ -402,81 +402,87 @@ namespace RevitBridge
                 return (400, new { error = true, message = $"Invalid JSON tool arguments: {ex.Message}" });
             }
 
-            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
+            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, tool.Write);
-                        return tool.Execute(args, new ToolContext(document, uiApp));
+                    {
+                        StartOperation();
+                        var document = uiApp.ActiveUIDocument?.Document ?? throw new NoActiveDocumentException();
+                        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.
-                    : 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));
-                }
+                    : 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 }, null);
+                return (409, new { error = true, hasActiveDocument = false, message = ex.Message }, null);
             }
             catch (ArgumentException ex)
             {
-                return (400, new { error = true, toolName = name, message = ex.Message }, null);
+                return (400, new { error = true, toolName = name, message = ex.Message }, null);
             }
             catch (Exception ex)
             {
-                return (500, new { error = true, toolName = name, message = ex.Message }, null);
+                return (500, new { error = true, toolName = name, message = ex.Message }, null);
             }
         }
 
@@ -486,9 +492,9 @@ namespace RevitBridge
                 ? Math.Clamp(value, 1_000, 600_000)
                 : 30_000;
 
-        /// <summary>Complete bounded JSON for model context; the full payload always
-        /// remains in details for the extension's saved-result retrieval. ToolOutput
-        /// compact text is a display summary, not a substitute for requested data.</summary>
+        /// <summary>Complete bounded JSON for model context; the full payload always
+        /// remains in details for the extension's saved-result retrieval. ToolOutput
+        /// compact text is a display summary, not a substitute for requested data.</summary>
         private static object BuildToolResponse(string toolName, object? output)
         {
             object? payload = output;
@@ -499,11 +505,11 @@ namespace RevitBridge
                 compact = toolOutput.CompactText;
             }
 
-            string text = JsonSerializer.Serialize(payload);
+            string text = JsonSerializer.Serialize(payload);
             bool truncated = text.Length > MaxContentChars;
             if (truncated)
             {
-                text = $"Result exceeds the {MaxContentChars}-character inline limit. The complete value is in details.payload; the Pi extension saves it locally and provides read_revit_result for bounded retrieval.";
+                text = $"Result exceeds the {MaxContentChars}-character inline limit. The complete value is in details.payload; the Pi extension saves it locally and provides read_revit_result for bounded retrieval.";
             }
 
             return new
@@ -511,7 +517,7 @@ namespace RevitBridge
                 success = true,
                 toolName,
                 content = new[] { new { type = "text", text } },
-                details = new { payload, summary = compact, contentTruncated = truncated },
+                details = new { payload, summary = compact, contentTruncated = truncated },
                 isError = false,
             };
         }