pi-revit 0.3.1 → 0.5.0

package/src/Revit/Tools/SummarizeElements.cs

@@ -0,0 +1,94 @@
+using System.Text.Json;
+using System.Text.Json.Nodes;
+
+namespace RevitBridge.Tools;
+
+internal sealed class SummarizeElements : ITool
+{
+    private const int MaxElements = 10000;
+    public string Name => "summarize_elements";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+    public IReadOnlyList<string> Keywords => new[] { "statistics", "count by", "group by", "breakdown", "totals", "per level", "distribution" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Linked-model contents", "tool", "get_linked_elements"),
+        new ToolLimit("Scopes above 10,000 elements", "tool", "narrow the query, or get_elements with count_only for a total"),
+    };
+    public string Label => "Summarize Elements";
+    public string Tier => "advanced";
+    public string Description => "Count matching host-model elements grouped by category, type, level or one parameter value. Accepts get_elements category/class/level/type/filter scopes. At most 10,000 matches; narrow larger queries. Parameter grouping uses exact raw values, with a distinct missing-value group. Ambiguous display-name parameters are rejected. Counts cover the entire matching scope, not just the returned groups page.";
+    public object ParametersSchema
+    {
+        get
+        {
+            var query = ElementQueryScope.Schema();
+            return new
+            {
+                type = "object",
+                properties = new
+                {
+                    query,
+                    group_by = new { type = "string", @enum = new[] { "category", "typeName", "levelId", "parameter" } },
+                    parameter = new { type = "string", description = "Required for group_by=parameter. Name, built-in identity or guid:<GUID>." },
+                    type_parameter = new { type = "boolean", description = "Group by the parameter on the element type instead of the instance." },
+                    offset = new { type = "integer", minimum = 0 },
+                    limit = new { type = "integer", minimum = 1, maximum = 500 },
+                },
+                required = new[] { "group_by" },
+            };
+        }
+    }
+
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        string groupBy = JsonArgs.GetString(args, "group_by") ?? "";
+        if (groupBy is not ("category" or "typeName" or "levelId" or "parameter")) throw new ArgumentException("Unknown group_by value.");
+        string? parameter = JsonArgs.GetString(args, "parameter");
+        if (groupBy == "parameter" && string.IsNullOrWhiteSpace(parameter)) throw new ArgumentException("parameter is required for parameter grouping.");
+        bool typeParameter = JsonArgs.GetBool(args, "type_parameter", false);
+        var query = ElementQueryScope.Parse(args);
+        JsonElement RunQuery() => JsonSerializer.SerializeToElement(((ToolOutput)new GetElements().Execute(JsonSerializer.SerializeToElement(query), context)!).Payload);
+        query["count_only"] = true;
+        var countResult = RunQuery();
+        int total = countResult.GetProperty("total_count").GetInt32();
+        object? warnings = countResult.TryGetProperty("warnings", out var queryWarnings) ? queryWarnings.Clone() : null;
+        if (total > MaxElements) throw new ArgumentException($"Query matches {total} elements; narrow the scope to at most {MaxElements}.");
+        query["count_only"] = false;
+        query["limit"] = 1000;
+        if (groupBy == "parameter")
+        {
+            query["parameter_names"] = new JsonArray(parameter);
+            query["include_type_parameters"] = typeParameter;
+        }
+        var counts = new Dictionary<string, (object? Value, bool Missing, int Count)>();
+        for (int position = 0; position < total; position += 1000)
+        {
+            query["offset"] = position;
+            foreach (var row in RunQuery().GetProperty("elements").EnumerateArray())
+            {
+                object? value = null;
+                bool missing = false;
+                if (groupBy == "parameter")
+                {
+                    var projection = row.GetProperty("parameters").EnumerateArray().FirstOrDefault(p => p.GetProperty("isType").GetBoolean() == typeParameter);
+                    missing = projection.ValueKind == JsonValueKind.Undefined || !projection.GetProperty("found").GetBoolean();
+                    if (!missing)
+                    {
+                        if (projection.GetProperty("ambiguous").GetBoolean()) throw new ArgumentException($"Parameter '{parameter}' is ambiguous on element {row.GetProperty("id")}; use a built-in identity or shared GUID.");
+                        value = projection.GetProperty("matches")[0].GetProperty("value").Clone();
+                    }
+                }
+                else if (row.TryGetProperty(groupBy, out var field)) value = field.Clone();
+                string key = (missing ? "missing:" : "value:") + JsonSerializer.Serialize(value);
+                counts[key] = counts.TryGetValue(key, out var previous) ? (value, missing, previous.Count + 1) : (value, missing, 1);
+            }
+        }
+        int offset = Math.Max(0, JsonArgs.GetInt(args, "offset", 0));
+        int limit = Math.Clamp(JsonArgs.GetInt(args, "limit", 100), 1, 500);
+        var groups = counts.OrderByDescending(pair => pair.Value.Count).ThenBy(pair => pair.Key, StringComparer.Ordinal).Skip(offset).Take(limit)
+            .Select(pair => new { value = pair.Value.Value, missing = pair.Value.Missing, count = pair.Value.Count }).ToArray();
+        return new { total_elements = total, total_groups = counts.Count, group_by = groupBy, parameter, type_parameter = typeParameter,
+            numeric_values = "Revit internal units", warnings, offset, returned_count = groups.Length,
+            next_offset = offset + groups.Length < counts.Count ? (int?)(offset + groups.Length) : null, groups };
+    }
+}

package/src/Revit/Tools/ToolContract.cs

@@ -0,0 +1,48 @@
+namespace RevitBridge
+{
+    /// <summary>
+    /// A declared capability boundary: something the tool deliberately does not cover and
+    /// the route to use instead. Alternative kinds: "tool" (Ref names another public tool),
+    /// "api" (Ref names Revit API members to verify with search_api_docs before custom
+    /// execution), "user" (needs a user action or decision), or "revit_unsupported" (the
+    /// Revit API itself does not offer it; Ref states the evidence). A limit never ends at
+    /// "unsupported" without a route, so agents do not report a false impossibility.
+    /// Kept in its own file so every project that compiles tool sources shares one type.
+    /// </summary>
+    internal sealed record ToolLimit(string What, string Alternative, string? Ref = null)
+    {
+        public static readonly IReadOnlyList<string> AlternativeKinds = new[] { "tool", "api", "user", "revit_unsupported" };
+    }
+
+    /// <summary>Allowed ITool.Verification values; see ITool.Verification.</summary>
+    internal static class ToolVerification
+    {
+        public static readonly IReadOnlyList<string> Kinds = new[] { "reread", "capture", "inspect_output", "none" };
+    }
+
+    /// <summary>
+    /// Document kinds a tool works in (inv:document-kind-declared). Every bridge tool declares
+    /// ITool.DocumentKinds; the dispatcher refuses any other kind before the tool runs, with the
+    /// route to use instead. Revit-free, so the refusal is tested offline.
+    /// </summary>
+    internal static class DocumentKind
+    {
+        public const string Project = "project";
+        public const string Family = "family";
+        public static readonly IReadOnlyList<string> Both = new[] { Project, Family };
+        public static readonly IReadOnlyList<string> ProjectOnly = new[] { Project };
+
+        /// <summary>Revit API route for family types, parameters and formulas; also a declared limit alternative.</summary>
+        public const string FamilyApi = "FamilyManager.Types; FamilyManager.NewType; FamilyManager.Set; FamilyManager.AddParameter; FamilyManager.SetFormula";
+
+        /// <summary>Why a tool cannot run in the active document, with the alternative; null when it can.</summary>
+        public static string? Refusal(string tool, IReadOnlyList<string> supported, string active, string title)
+        {
+            if (supported.Count == 0 || supported.Contains(active)) return null;
+            string route = active == Family
+                ? $"A family document has no sheets, schedules, rooms, links or project coordinates. For family types, parameters and formulas use the Revit API: verify '{FamilyApi}' with search_api_docs, then use execute_csharp."
+                : "Open the family for editing (Document.EditFamily) or ask the user to open the family document.";
+            return $"{tool} works in {string.Join(" and ", supported)} documents; the active document '{title}' is a {active} document. Nothing was run. {route}";
+        }
+    }
+}

package/src/Revit/Tools/ToolSupport.cs

@@ -191,6 +191,10 @@ namespace RevitBridge.Tools
                     _ => null,
                 };
             }
+            // Shared projection: special or system-owned objects are flagged for every tool
+            // that lists elements (inv:special-objects-flagged). Ordinary elements add nothing.
+            if (ElementTraits.For(element) is { } traits)
+                row["traits"] = traits;
             return row;
         }
     }

package/src/Revit/Tools/TransformElements.cs

@@ -0,0 +1,73 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class TransformElements : ITool
+{
+    public string Name => "transform_elements";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+    public IReadOnlyList<string> Keywords => new[] { "move", "copy", "rotate", "shift", "offset", "relocate" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Mirroring", "api", "ElementTransformUtils.MirrorElements"),
+        new ToolLimit("Pinned elements (move and rotate reject them)", "user", "Confirm unpinning (Element.Pinned) first"),
+        new ToolLimit("Elements inside linked models", "user", "Edit the linked model itself"),
+    };
+    public string? Verification => "reread";
+    public string Label => "Transform Elements";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "Move, copy or rotate 1–200 elements together in the active document. Coordinates use the document internal origin and axes; unit is required. Rotation uses a right-handed axis and angle_degrees. The whole selection succeeds or rolls back as one step; pinned elements are never automatically unpinned. Revit may move constrained/hosted dependents too. A copy's result reports inherited_state: values and traits the copies carried over, such as Mark, Comments, group or design-option membership. preview=true validates commit then rolls back; any created IDs in a preview are temporary and must not be reused. Snapshots describe requested elements, not a complete dependent-change audit.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            action = new { type = "string", @enum = new[] { "move", "copy", "rotate" } },
+            element_ids = ModelEditInputs.IdsSchema,
+            unit = ModelEditInputs.LengthUnitSchema,
+            translation = ModelEditInputs.VectorSchema("Move/copy displacement [x,y,z] in unit."),
+            axis_origin = ModelEditInputs.VectorSchema("Rotation axis origin [x,y,z] in unit, relative to internal origin."),
+            axis_direction = ModelEditInputs.VectorSchema("Nonzero rotation axis direction [x,y,z], dimensionless."),
+            angle_degrees = new { type = "number", description = "Signed right-hand rotation angle in degrees." },
+            preview = ModelEditInputs.PreviewSchema,
+        }, required = new[] { "action", "element_ids", "unit" },
+    };
+
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        var ids = ModelEditInputs.Ids(args);
+        string action = JsonArgs.GetString(args, "action") ?? "";
+        if (action is not ("move" or "copy" or "rotate")) throw new ArgumentException("action must be move, copy or rotate.");
+        double scale = ModelEditInputs.LengthScale(args);
+        XYZ? translation = action != "rotate" ? ModelEditInputs.Vector(args, "translation").Multiply(scale) : null;
+        XYZ? origin = action == "rotate" ? ModelEditInputs.Vector(args, "axis_origin").Multiply(scale) : null;
+        XYZ? direction = action == "rotate" ? ModelEditInputs.Vector(args, "axis_direction") : null;
+        double angle = action == "rotate" ? ModelEditInputs.Number(args, "angle_degrees") * Math.PI / 180 : 0;
+        if (direction != null && direction.GetLength() < 1e-12) throw new ArgumentException("axis_direction must be nonzero.");
+        var result = ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(
+            new() { ["action"] = action, ["element_ids"] = ids.Select(x => x.Value).ToArray() }, () =>
+            {
+                var elements = ids.Select(id => doc.GetElement(id) ?? throw new ArgumentException($"Element {id.Value} not found.")).ToArray();
+                if (action != "copy" && elements.Any(e => e.Pinned)) throw new ArgumentException("Selection contains pinned elements; no elements were unpinned.");
+                var before = elements.Select(ModelEditInputs.Snapshot).ToArray();
+                ICollection<ElementId> outputIds = ids;
+                if (action == "move") ElementTransformUtils.MoveElements(doc, ids, translation!);
+                else if (action == "copy") outputIds = ElementTransformUtils.CopyElements(doc, ids, translation!);
+                else ElementTransformUtils.RotateElements(doc, ids, Line.CreateUnbound(origin!, direction!.Normalize()), angle);
+                doc.Regenerate();
+                var result = new Dictionary<string, object?> { ["before"] = before, ["after"] = outputIds.Select(doc.GetElement).Where(e => e != null).Select(ModelEditInputs.Snapshot).ToArray(),
+                    ["created_ids"] = action == "copy" ? outputIds.Select(id => id.Value).ToArray() : Array.Empty<long>(),
+                    ["coordinate_system"] = "document_internal", ["snapshot_unit"] = "feet",
+                    ["created_ids_are_temporary"] = action == "copy" && JsonArgs.GetBool(args, "preview", false) };
+                // Copies carry their sources' values and traits (inv:derived-state-reported). CopyElements
+                // returns copies in no guaranteed order, so each copy is reported without pairing it to one source.
+                if (action == "copy")
+                    result["inherited_state"] = outputIds.Take(InheritedState.ListCap).Select(doc.GetElement).Where(e => e != null)
+                        .Select(copy => new { id = copy!.Id.Value, state = InheritedState.OfElement(copy, null) }).Where(row => row.state != null).ToArray();
+                return result;
+            }) });
+        return result.Payload;
+    }
+}

package/workspace/AGENTS.md

@@ -1,72 +1,78 @@
 # pi-revit workspace
 
-This folder tree is the working area for Pi + Revit sessions. The pi-revit tools talk to the
-Revit bridge add-in, targeting Revit 2025, 2026, and 2027. The 0.3.0 changes were
-tested live on Revit 2025. Bridge document tools require a project open; `ping` and
-`search_api_docs` work without a document. `read_revit_result` reads saved local
-results without contacting Revit.
+This folder tree is the working area for Pi + Revit sessions. The pi-revit tools talk to the
+Revit bridge add-in, targeting Revit 2025, 2026, and 2027. This file owns workspace
+and output conventions. The `pi-revit` skill and focused tool manuals own current
+operating guidance. `find_revit_tools` with `scope: "documentation"` returns manual
+paths even while Revit is closed. Most bridge tools require a project open; `ping`
+and `search_api_docs` need the bridge but no document. `read_revit_result` reads
+saved local results without contacting Revit.
 
 ## File rules — where every file goes
 
 Work sorts by model, automatically. The export tool files its output under the model it came
-from — never a decision for you or the user to make:
+from; it is not a decision for you or the user to make:
 
 ```text
 Documents\pi-revit\
 ├─ AGENTS.md            <- this file
 ├─ pi-revit.cmd         <- double-click launcher
 └─ Models\
-   └─ <model title>--<identity hash>\  <- selected automatically for the exported document
-      ├─ model.txt      <- document identity/path marker written by the add-in
+   └─ <model title>--<identity hash>\  <- selected automatically for the exported document
+      ├─ model.txt      <- document identity/path marker written by the add-in
       ├─ exports\       <- export_documents output (its default)
       ├─ captures\      <- view snapshots worth keeping
       └─ scripts\       <- generated scripts and analysis for that model
 ```
 
 1. **Let exports sort themselves**: call `export_documents` without `output_dir` — files land
-   in an identity-derived model folder automatically. Treat the returned `outputDir`
-   and file paths as authoritative; do not derive the hash from the model title or
-   opaque `project.documentId`. Save As can change the destination. Existing title-only
-   folders remain untouched. Pass
+   in an identity-derived model folder automatically. Treat the returned `outputDir`
+   and file paths as authoritative; do not derive the hash from the model title or
+   opaque `project.documentId`. Save As can change the destination. Existing title-only
+   folders remain untouched. Pass
    `output_dir` only when the user names a different target.
 2. **Anything else you produce about a model goes into that model's folder**: view captures the
-   user wants to keep in that verified model folder's `captures` subfolder
-   (`capture_view` writes to temp), and scripts and analysis in its `scripts`
-   subfolder. For a default export, the model folder is the parent of returned
-   `outputDir`. If no folder has been established, identify it from existing model
-   markers or choose an explicit destination for the task; do not trigger an
-   unnecessary export or guess a title-only folder. Create subfolders on first use.
-3. **Never create files loose in the workspace root.** The root holds `AGENTS.md`,
+   user wants to keep in that verified model folder's `captures` subfolder
+   (`capture_view` writes to temp), and scripts and analysis in its `scripts`
+   subfolder. For a default export, the model folder is the parent of returned
+   `outputDir`. If no folder has been established, identify it from existing model
+   markers or choose an explicit destination for the task; do not trigger an
+   unnecessary export or guess a title-only folder. Create subfolders on first use.
+3. **Never create files loose in the workspace root.** <!-- inv:workspace-root-clean --> The root holds `AGENTS.md`,
    `pi-revit.cmd`, `Models\`, and Pi's own session data — nothing else, ever.
 
 ## Tool habits
 
-- Start unfamiliar models with `get_model_overview`; use `get_elements` for any listing or
-  counting; read parameter values with `get_element_details`.
-- Copy the intended model's `project.documentId` unchanged into `expected_document_id`
-  for `set_parameters`, `execute_csharp`, `export_documents`, `open_view`, and
-  selection/zoom changes. Any `manage_selection` call with `isolate_in_view: true`
-  also requires it, including action `get`. Pure reads may omit it; supplied IDs
-  are checked. Legacy `expected_document` titles alone do not satisfy the guard.
-  After a rejection, verify the intended model before refreshing its ID. Closing
-  and reopening a model or restarting Revit invalidates earlier IDs.
-- Before `execute_csharp`, verify unfamiliar API signatures with `search_api_docs`.
-- Write tools (`set_parameters`, `execute_csharp`) change the real model — state clearly what
-  was changed. `set_parameters` commits partial successes: always check its `failed` list.
-  Inspect `commitWarnings` and the actual transaction outcome. A failed
-  `execute_csharp` attempts rollback; do not assume rollback succeeded. A
-  `returnValueError` can follow a committed edit. Earlier UI actions and created
-  files can persist after failure. Read reported effects before retrying.
-- When a result returns `result_id`, use `read_revit_result` from offset zero and
-  follow `next_offset` until `has_more` is false. Join its `text` fragments in order;
-  offsets count UTF-16 code units. The returned absolute file path remains a
-  fallback for `read` after extension reload while the file exists. Tool query
-  pagination and limits still apply separately.
-
-## Upgrade notes
-
-After installing 0.3.0, deploy the matching add-in with Revit closed, restart Revit,
-and start a fresh Pi session to load the new tool schemas. Obtain a new overview
-before changing a document. Setup preserves existing `AGENTS.md`; older workspaces
-need these exact-ID, saved-result, and identity-derived folder rules merged into
-their existing instructions.
+- Distinguish explanations, inspections, and requested changes. General questions
+  need not connect to a model. An audit alone does not authorize repairs or exports.
+- For model work, use the skill's execution rules, select the intended session,
+  and start unfamiliar models with `get_model_overview`. Discover dedicated tools
+  and read their returned manual paths and current schemas before using custom code.
+- Copy the intended model's `project.documentId` unchanged into `expected_document_id`
+  whenever required by the schema/runtime, including writes, previews, export,
+  view/selection changes and every `manage_sheet_placements` action. Selection
+  isolation also requires it with action `get`. Supplied IDs on reads are checked.
+  A title alone is insufficient. On rejection verify the intended target before
+  refreshing the ID; reopening a document or restarting Revit invalidates old IDs.
+- Before `execute_csharp`, verify unfamiliar API signatures with `search_api_docs`.
+- Report actual retained changes. `set_parameters` defaults to partial success;
+  previews roll back, and atomic failures roll back the batch. Read the manual and
+  distinguish `succeeded`, `proposed`, and `failed`; discard rolled-back IDs.
+  Inspect `commitWarnings` and the actual transaction outcome. A failed
+  `execute_csharp` attempts rollback; do not assume rollback succeeded. A
+  `returnValueError` can follow a committed edit. Earlier UI actions and created
+  files can persist after failure. Read reported effects before retrying.
+- When a result returns `result_id`, use `read_revit_result` from offset zero and
+  follow `next_offset` until `has_more` is false. Join its `text` fragments in order;
+  offsets count UTF-16 code units. The returned absolute file path remains a
+  fallback for `read` after extension reload while the file exists. Tool query
+  pagination and limits still apply separately.
+
+## Upgrade notes
+
+After a package/add-in upgrade, deploy the matching add-in with Revit closed, restart Revit,
+and start a fresh Pi session to load the new tool schemas. Obtain a new overview
+before changing a document. Setup preserves existing `AGENTS.md`; older workspaces
+need updated exact-ID, saved-result, identity-derived folder and guidance-routing
+rules merged into their existing instructions. These are upgrade steps, not
+actions to perform during an ordinary model question or documentation check.