pi-revit 0.1.0

package/src/Revit/BridgeServer.cs

@@ -0,0 +1,419 @@
+using System.IO;
+using System.Net;
+using System.Net.Sockets;
+using System.Text;
+using System.Text.Json;
+
+namespace RevitBridge
+{
+    /// <summary>
+    /// Minimal localhost HTTP bridge. Routes:
+    ///
+    ///   GET  /ping                  -> bridge availability
+    ///   GET  /tools                 -> tool metadata list
+    ///   GET  /tools/{name}          -> one tool's metadata
+    ///   POST /tools/{name}/execute  -> execute a tool on the Revit API thread
+    ///
+    /// Every request must carry ?token=... matching the per-start token written
+    /// to %APPDATA%\RevitBridge\bridge.json. The HTTP handling is deliberately
+    /// minimal (loopback only) with byte-accurate UTF-8 body reads.
+    /// </summary>
+    internal sealed class BridgeServer : IDisposable
+    {
+        private const int DefaultPort = 47777;
+        private const int MaxPort = 47797;
+        private const int MaxRequestBytes = 4_000_000;
+        private const int MaxContentChars = 12_000;
+
+        private readonly CommandQueue _queue;
+        private readonly ToolRegistry _registry;
+        private readonly string _revitVersion;
+        private readonly Func<bool> _hasOpenDocument;
+
+        private TcpListener? _listener;
+        private CancellationTokenSource? _cts;
+        private string _token = string.Empty;
+        private int _port;
+
+        public BridgeServer(CommandQueue queue, ToolRegistry registry, string revitVersion, Func<bool> hasOpenDocument)
+        {
+            _queue = queue;
+            _registry = registry;
+            _revitVersion = revitVersion;
+            _hasOpenDocument = hasOpenDocument;
+        }
+
+        public void Start()
+        {
+            if (_listener != null) return;
+
+            _token = Guid.NewGuid().ToString("N");
+            _cts = new CancellationTokenSource();
+
+            for (int port = ResolveStartPort(); port <= MaxPort; port++)
+            {
+                try
+                {
+                    _listener = new TcpListener(IPAddress.Loopback, port);
+                    _listener.Start();
+                    _port = port;
+                    break;
+                }
+                catch
+                {
+                    _listener = null;
+                }
+            }
+
+            if (_listener is null)
+                throw new InvalidOperationException($"Unable to start the Revit bridge on localhost ports {DefaultPort}-{MaxPort}.");
+
+            WriteBridgeInfo();
+            _ = Task.Run(() => AcceptLoopAsync(_cts.Token));
+        }
+
+        public void Stop()
+        {
+            try { _cts?.Cancel(); } catch { }
+            try { _listener?.Stop(); } catch { }
+            _listener = null;
+            _cts?.Dispose();
+            _cts = null;
+            DeleteBridgeInfoIfOwned();
+        }
+
+        public void Dispose() => Stop();
+
+        private static int ResolveStartPort()
+        {
+            var raw = Environment.GetEnvironmentVariable("REVIT_BRIDGE_PORT");
+            return int.TryParse(raw, out int port) && port > 0 ? port : DefaultPort;
+        }
+
+        internal static string BridgeInfoDirectory() => Path.Combine(
+            Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData),
+            "RevitBridge");
+
+        public static string BridgeInfoPath() => Path.Combine(BridgeInfoDirectory(), "bridge.json");
+
+        private void WriteBridgeInfo()
+        {
+            Directory.CreateDirectory(BridgeInfoDirectory());
+            File.WriteAllText(BridgeInfoPath(), JsonSerializer.Serialize(new
+            {
+                baseUrl = $"http://127.0.0.1:{_port}",
+                token = _token,
+                pid = Environment.ProcessId,
+                revitVersion = _revitVersion,
+                startedAtUtc = DateTime.UtcNow.ToString("o"),
+            }, new JsonSerializerOptions { WriteIndented = true }));
+        }
+
+        private static void DeleteBridgeInfoIfOwned()
+        {
+            try
+            {
+                string path = BridgeInfoPath();
+                if (!File.Exists(path)) return;
+                using var doc = JsonDocument.Parse(File.ReadAllText(path));
+                if (doc.RootElement.TryGetProperty("pid", out var pid) && pid.TryGetInt32(out int value) && value == Environment.ProcessId)
+                    File.Delete(path);
+            }
+            catch
+            {
+                // Never let cleanup break Revit shutdown.
+            }
+        }
+
+        private async Task AcceptLoopAsync(CancellationToken token)
+        {
+            while (!token.IsCancellationRequested && _listener != null)
+            {
+                TcpClient? client = null;
+                try
+                {
+                    client = await _listener.AcceptTcpClientAsync(token);
+                    _ = Task.Run(() => HandleClientAsync(client, token), token);
+                }
+                catch (OperationCanceledException)
+                {
+                    client?.Dispose();
+                    break;
+                }
+                catch
+                {
+                    client?.Dispose();
+                }
+            }
+        }
+
+        private async Task HandleClientAsync(TcpClient client, CancellationToken token)
+        {
+            using var _ = client;
+            NetworkStream? stream = null;
+            try
+            {
+                stream = client.GetStream();
+                var request = await ReadRequestAsync(stream, token);
+                if (request is null) return;
+
+                var (method, target, body) = request.Value;
+                var uri = new Uri("http://127.0.0.1" + target);
+                var query = ParseQuery(uri.Query);
+
+                if (!query.TryGetValue("token", out var tokenValue) || !string.Equals(tokenValue, _token, StringComparison.Ordinal))
+                {
+                    await WriteJsonAsync(stream, 403, new { error = true, message = "Invalid Revit bridge token." }, token);
+                    return;
+                }
+
+                var (status, response) = await RouteAsync(method, uri.AbsolutePath, query, body, token);
+                await WriteJsonAsync(stream, status, response, token);
+            }
+            catch (Exception ex)
+            {
+                if (stream != null)
+                {
+                    try { await WriteJsonAsync(stream, 500, new { error = true, message = ex.Message }, token); }
+                    catch { }
+                }
+            }
+        }
+
+        /// <summary>Reads one HTTP request with a byte-accurate Content-Length body.</summary>
+        private static async Task<(string Method, string Target, string Body)?> ReadRequestAsync(NetworkStream stream, CancellationToken token)
+        {
+            var buffer = new byte[8192];
+            using var data = new MemoryStream();
+            int headerEnd = -1;
+
+            while (headerEnd < 0)
+            {
+                int n = await stream.ReadAsync(buffer, token);
+                if (n <= 0) return null;
+                data.Write(buffer, 0, n);
+                if (data.Length > MaxRequestBytes)
+                    throw new InvalidOperationException("Request too large.");
+                headerEnd = FindHeaderEnd(data.GetBuffer(), (int)data.Length);
+            }
+
+            string headerText = Encoding.ASCII.GetString(data.GetBuffer(), 0, headerEnd);
+            string[] lines = headerText.Split("\r\n");
+            string[] requestParts = lines[0].Split(' ', 3, StringSplitOptions.RemoveEmptyEntries);
+            if (requestParts.Length < 2)
+                throw new InvalidOperationException("Invalid HTTP request line.");
+
+            string method = requestParts[0].ToUpperInvariant();
+            if (method != "GET" && method != "POST")
+                throw new InvalidOperationException("Only GET and POST are supported.");
+
+            int contentLength = 0;
+            foreach (string line in lines.Skip(1))
+            {
+                int separator = line.IndexOf(':');
+                if (separator <= 0) continue;
+                if (line.AsSpan(0, separator).Trim().Equals("Content-Length", StringComparison.OrdinalIgnoreCase))
+                    int.TryParse(line.AsSpan(separator + 1).Trim(), out contentLength);
+            }
+
+            if (contentLength is < 0 or > MaxRequestBytes)
+                throw new InvalidOperationException("Invalid Content-Length.");
+
+            int bodyStart = headerEnd + 4;
+            var bodyBytes = new byte[contentLength];
+            int alreadyRead = Math.Min((int)data.Length - bodyStart, contentLength);
+            Array.Copy(data.GetBuffer(), bodyStart, bodyBytes, 0, alreadyRead);
+
+            int read = alreadyRead;
+            while (read < contentLength)
+            {
+                int n = await stream.ReadAsync(bodyBytes.AsMemory(read, contentLength - read), token);
+                if (n <= 0) break;
+                read += n;
+            }
+
+            return (method, requestParts[1], Encoding.UTF8.GetString(bodyBytes, 0, read));
+        }
+
+        private static int FindHeaderEnd(byte[] data, int length)
+        {
+            for (int i = 3; i < length; i++)
+            {
+                if (data[i - 3] == '\r' && data[i - 2] == '\n' && data[i - 1] == '\r' && data[i] == '\n')
+                    return i - 3;
+            }
+            return -1;
+        }
+
+        private static Dictionary<string, string> ParseQuery(string query)
+        {
+            var result = new Dictionary<string, string>(StringComparer.Ordinal);
+            foreach (string pair in query.TrimStart('?').Split('&', StringSplitOptions.RemoveEmptyEntries))
+            {
+                int separator = pair.IndexOf('=');
+                if (separator <= 0) continue;
+                result[WebUtility.UrlDecode(pair[..separator])] = WebUtility.UrlDecode(pair[(separator + 1)..]);
+            }
+            return result;
+        }
+
+        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 });
+
+            if (method == "GET" && path == "/tools")
+            {
+                var tools = _registry.DescribeAll();
+                return (200, new { protocolVersion = 1, tools, count = tools.Count });
+            }
+
+            const string toolPrefix = "/tools/";
+            if (path.StartsWith(toolPrefix, StringComparison.OrdinalIgnoreCase))
+            {
+                string tail = path[toolPrefix.Length..].Trim('/');
+
+                if (tail.EndsWith("/execute", StringComparison.OrdinalIgnoreCase))
+                {
+                    if (method != "POST")
+                        return (405, new { error = true, message = "Tool execution requires POST." });
+
+                    string name = WebUtility.UrlDecode(tail[..^"/execute".Length].Trim('/'));
+                    return await ExecuteToolAsync(name, body, query, token);
+                }
+
+                if (method != "GET")
+                    return (405, new { error = true, message = "Tool description requires GET." });
+
+                string describeName = WebUtility.UrlDecode(tail);
+                var tool = _registry.Get(describeName);
+                return tool is null
+                    ? (404, new { error = true, message = $"Unknown tool: {describeName}" })
+                    : (200, _registry.Describe(tool));
+            }
+
+            return (404, new { error = true, message = $"Unknown Revit bridge endpoint: {path}" });
+        }
+
+        private async Task<(int Status, object Response)> ExecuteToolAsync(string name, string body, Dictionary<string, string> query, CancellationToken token)
+        {
+            var tool = _registry.Get(name);
+            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
+            {
+                using var doc = JsonDocument.Parse(string.IsNullOrWhiteSpace(body) ? "{}" : body);
+                if (doc.RootElement.ValueKind != JsonValueKind.Object)
+                    return (400, new { error = true, message = "Tool arguments must be a JSON object." });
+                args = doc.RootElement.Clone();
+            }
+            catch (JsonException ex)
+            {
+                return (400, new { error = true, message = $"Invalid JSON tool arguments: {ex.Message}" });
+            }
+
+            int timeoutMs = ResolveTimeoutMs(query);
+
+            try
+            {
+                object? output = tool.RequiresDocument
+                    ? await _queue.RunAsync(uiApp =>
+                    {
+                        var document = uiApp.ActiveUIDocument?.Document ?? throw new NoActiveDocumentException();
+                        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));
+            }
+            catch (NoActiveDocumentException ex)
+            {
+                return (409, new { error = true, hasActiveDocument = false, message = ex.Message });
+            }
+            catch (ArgumentException ex)
+            {
+                return (400, new { error = true, toolName = name, message = ex.Message });
+            }
+            catch (Exception ex)
+            {
+                return (500, new { error = true, toolName = name, message = ex.Message });
+            }
+        }
+
+        /// <summary>Optional timeout_ms query param, clamped to 1s..10min; default 30s.</summary>
+        private static int ResolveTimeoutMs(Dictionary<string, string> query)
+            => query.TryGetValue("timeout_ms", out var raw) && int.TryParse(raw, out int value)
+                ? Math.Clamp(value, 1_000, 600_000)
+                : 30_000;
+
+        /// <summary>Compact text for model context; full payload in details. Tools may
+        /// return a ToolOutput (CompactText -> content, Payload -> details.payload) or
+        /// any plain object (serialized to both).</summary>
+        private static object BuildToolResponse(string toolName, object? output)
+        {
+            object? payload = output;
+            string? compact = null;
+            if (output is ToolOutput toolOutput)
+            {
+                payload = toolOutput.Payload;
+                compact = toolOutput.CompactText;
+            }
+
+            string text = compact ?? JsonSerializer.Serialize(payload ?? new { });
+            bool truncated = text.Length > MaxContentChars;
+            if (truncated)
+            {
+                string suffix = $"... [truncated at {MaxContentChars} chars; full payload is in details]";
+                text = text[..Math.Max(0, MaxContentChars - suffix.Length)] + suffix;
+            }
+
+            return new
+            {
+                success = true,
+                toolName,
+                content = new[] { new { type = "text", text } },
+                details = new { payload, contentTruncated = truncated },
+                isError = false,
+            };
+        }
+
+        private static async Task WriteJsonAsync(NetworkStream stream, int status, object value, CancellationToken token)
+        {
+            string reason = status switch
+            {
+                200 => "OK",
+                400 => "Bad Request",
+                403 => "Forbidden",
+                404 => "Not Found",
+                405 => "Method Not Allowed",
+                409 => "Conflict",
+                500 => "Internal Server Error",
+                _ => "OK",
+            };
+
+            byte[] body = JsonSerializer.SerializeToUtf8Bytes(value);
+            string header =
+                $"HTTP/1.1 {status} {reason}\r\n" +
+                "Content-Type: application/json; charset=utf-8\r\n" +
+                $"Content-Length: {body.Length}\r\n" +
+                "Connection: close\r\n" +
+                "\r\n";
+
+            await stream.WriteAsync(Encoding.ASCII.GetBytes(header), token);
+            await stream.WriteAsync(body, token);
+            await stream.FlushAsync(token);
+        }
+    }
+}

package/src/Revit/CommandQueue.cs

@@ -0,0 +1,93 @@
+using System.Collections.Concurrent;
+using System.Diagnostics;
+using Autodesk.Revit.UI;
+
+namespace RevitBridge
+{
+    /// <summary>
+    /// Thrown by queued work when no Revit document is open.
+    /// The bridge maps this to HTTP 409 with hasActiveDocument = false.
+    /// </summary>
+    internal sealed class NoActiveDocumentException : InvalidOperationException
+    {
+        public NoActiveDocumentException()
+            : base("No active Revit document is open.")
+        {
+        }
+    }
+
+    /// <summary>
+    /// Schedules work onto the Revit API thread via an ExternalEvent and returns
+    /// a Task that completes with the result (standard ExternalEvent +
+    /// TaskCompletionSource dispatch).
+    /// </summary>
+    internal sealed class CommandQueue : IExternalEventHandler
+    {
+        private sealed class WorkItem
+        {
+            public required Func<UIApplication, object?> Action { get; init; }
+            public required TaskCompletionSource<object?> Completion { get; init; }
+
+            /// <summary>Stopwatch timestamp after which the item must not start; 0 = no deadline.</summary>
+            public long DeadlineTimestamp { get; init; }
+        }
+
+        private readonly ConcurrentQueue<WorkItem> _queue = new();
+
+        /// <summary>Set once from Application.OnStartup (a valid Revit API context).</summary>
+        public ExternalEvent? ExternalEvent { get; set; }
+
+        public Task<T> RunAsync<T>(Func<UIApplication, T> action, TimeSpan? timeout = null)
+        {
+            var completion = new TaskCompletionSource<object?>(TaskCreationOptions.RunContinuationsAsynchronously);
+            _queue.Enqueue(new WorkItem
+            {
+                Action = app => action(app),
+                Completion = completion,
+                DeadlineTimestamp = timeout is { } budget
+                    ? Stopwatch.GetTimestamp() + (long)(budget.TotalSeconds * Stopwatch.Frequency)
+                    : 0,
+            });
+
+            var externalEvent = ExternalEvent;
+            if (externalEvent is null)
+            {
+                completion.TrySetException(new InvalidOperationException("Revit bridge command queue is not initialized."));
+            }
+            else
+            {
+                externalEvent.Raise();
+            }
+
+            return Await<T>(completion.Task);
+        }
+
+        private static async Task<T> Await<T>(Task<object?> task) => (T)(await task.ConfigureAwait(false))!;
+
+        public void Execute(UIApplication app)
+        {
+            while (_queue.TryDequeue(out var item))
+            {
+                // The HTTP caller abandons the request at the same deadline, so running
+                // the item late would mutate the model behind the agent's back.
+                if (item.DeadlineTimestamp != 0 && Stopwatch.GetTimestamp() > item.DeadlineTimestamp)
+                {
+                    item.Completion.TrySetException(new TimeoutException(
+                        "Tool call expired before execution; no work was performed. Revit stayed busy past the timeout_ms deadline; retry, optionally with a larger timeout_ms."));
+                    continue;
+                }
+
+                try
+                {
+                    item.Completion.TrySetResult(item.Action(app));
+                }
+                catch (Exception ex)
+                {
+                    item.Completion.TrySetException(ex);
+                }
+            }
+        }
+
+        public string GetName() => "Revit Bridge Command Queue";
+    }
+}

package/src/Revit/RevitBridge.addin

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<RevitAddIns>
+  <AddIn Type="Application">
+    <Name>Revit Bridge</Name>
+    <Assembly>RevitBridge\RevitBridge.dll</Assembly>
+    <FullClassName>RevitBridge.Application</FullClassName>
+    <AddInId>5E4AA11A-BBAF-4B2C-8649-EC6C541FABA1</AddInId>
+    <VendorId>pi-revit</VendorId>
+    <VendorDescription>Headless local bridge that exposes Revit API tools to a Pi coding-agent session.</VendorDescription>
+  </AddIn>
+</RevitAddIns>

package/src/Revit/RevitBridge.csproj

@@ -0,0 +1,48 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <!-- net8.0-windows -> Revit 2025/2026; net10.0-windows -> Revit 2027. The build picks
+         per-TFM defaults below; deploy.ps1 builds the single TFM that matches its -RevitVersion. -->
+    <TargetFrameworks>net8.0-windows;net10.0-windows</TargetFrameworks>
+    <LangVersion>latest</LangVersion>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <AssemblyName>RevitBridge</AssemblyName>
+    <RootNamespace>RevitBridge</RootNamespace>
+    <PlatformTarget>x64</PlatformTarget>
+    <!-- MSB3277: harmless version-conflict noise from RevitAPIUI transitive deps; nothing is copied local. -->
+    <MSBuildWarningsAsMessages>MSB3277</MSBuildWarningsAsMessages>
+    <!-- execute_csharp: copy the Roslyn package closure into the build output so
+         scripts/deploy.ps1 can ship it next to RevitBridge.dll. -->
+    <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
+    <!-- Compiler messages stay English-only; skips ~13 localized Roslyn resource subfolders. -->
+    <SatelliteResourceLanguages>en</SatelliteResourceLanguages>
+  </PropertyGroup>
+
+  <!-- RevitAPI.dll location, defaulted per target framework. Override either target with:
+       dotnet build -p:TargetFramework=net10.0-windows -p:RevitApiPath="D:\Autodesk\Revit 2027" -->
+  <PropertyGroup Condition="'$(RevitApiPath)' == '' and '$(TargetFramework)' == 'net10.0-windows'">
+    <RevitApiPath>C:\Program Files\Autodesk\Revit 2027</RevitApiPath>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(RevitApiPath)' == ''">
+    <RevitApiPath>C:\Program Files\Autodesk\Revit 2025</RevitApiPath>
+  </PropertyGroup>
+
+  <!-- Revit API assemblies are provided by Revit at runtime; never copy them local. -->
+  <ItemGroup>
+    <Reference Include="RevitAPI">
+      <HintPath>$(RevitApiPath)\RevitAPI.dll</HintPath>
+      <Private>false</Private>
+    </Reference>
+    <Reference Include="RevitAPIUI">
+      <HintPath>$(RevitApiPath)\RevitAPIUI.dll</HintPath>
+      <Private>false</Private>
+    </Reference>
+  </ItemGroup>
+
+  <!-- Roslyn scripting engine for the execute_csharp tool. -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Scripting" Version="4.8.0" />
+  </ItemGroup>
+
+</Project>

package/src/Revit/ToolRegistry.cs

@@ -0,0 +1,109 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+using Autodesk.Revit.UI;
+using RevitBridge.Tools;
+
+namespace RevitBridge
+{
+    /// <summary>
+    /// Execution context handed to tools. Document and UIApplication are non-null when the
+    /// tool runs on the Revit API thread (RequiresDocument = true, the default). Tools with
+    /// RequiresDocument = false run on the bridge's server task with both set to null and
+    /// must not touch the Revit API.
+    /// </summary>
+    internal sealed record ToolContext(Document? Document, UIApplication? UIApplication);
+
+    /// <summary>
+    /// Optional tool return shape: compact text for model context plus the full payload for
+    /// details. Tools may instead return any plain JSON-serializable object, which the bridge
+    /// serializes into both channels (capped in content).
+    /// </summary>
+    internal sealed record ToolOutput(object? Payload, string? CompactText = null);
+
+    /// <summary>A single Revit tool exposed through the bridge.</summary>
+    internal interface ITool
+    {
+        string Name { get; }
+        string Label { get; }
+        string Description { get; }
+
+        /// <summary>JSON schema (anonymous object) describing the tool arguments.</summary>
+        object ParametersSchema { get; }
+
+        /// <summary>True only for tools that mutate the model. Write tools own their transaction.</summary>
+        bool Write => false;
+
+        /// <summary>
+        /// False only for tools that never touch the Revit API. They skip the bridge's
+        /// no-document 409 gate and run directly on the server task instead of the Revit
+        /// API thread, so ToolContext.Document/UIApplication are null for them.
+        /// </summary>
+        bool RequiresDocument => true;
+
+        /// <summary>Activation tier metadata: "core" (default) or "advanced".</summary>
+        string Tier => "core";
+
+        /// <summary>Optional one-line "Available tools" system prompt entry.</summary>
+        string? PromptSnippet => null;
+
+        /// <summary>Optional system prompt guideline bullets. Each bullet must name the tool.</summary>
+        IReadOnlyList<string>? PromptGuidelines => null;
+
+        /// <summary>
+        /// Runs on the Revit API thread (or the server task when RequiresDocument is false).
+        /// Returns a ToolOutput or any plain JSON-serializable payload.
+        /// </summary>
+        object? Execute(JsonElement args, ToolContext context);
+    }
+
+    /// <summary>Name -> tool map plus the metadata projection served by GET /tools.</summary>
+    internal sealed class ToolRegistry
+    {
+        private readonly SortedDictionary<string, ITool> _tools = new(StringComparer.Ordinal);
+
+        public static ToolRegistry CreateDefault()
+        {
+            var registry = new ToolRegistry();
+            registry.Add(new SearchApiDocs());
+            registry.Add(new ExecuteCsharp());
+            registry.Add(new GetModelOverview());
+            registry.Add(new GetElements());
+            registry.Add(new GetElementTypes());
+            registry.Add(new GetElementDetails());
+            registry.Add(new ManageSelection());
+            registry.Add(new SetParameters());
+            registry.Add(new CaptureView());
+            registry.Add(new ExportDocuments());
+            registry.Add(new GetModelHealth());
+            return registry;
+        }
+
+        public void Add(ITool tool)
+        {
+            if (_tools.ContainsKey(tool.Name))
+                throw new InvalidOperationException($"Duplicate tool name: {tool.Name}");
+            _tools[tool.Name] = tool;
+        }
+
+        public ITool? Get(string name)
+            => _tools.TryGetValue(name, out var tool) ? tool : null;
+
+        public IReadOnlyList<object> DescribeAll()
+            => _tools.Values.Select(Describe).ToArray();
+
+        public object Describe(ITool tool) => new
+        {
+            name = tool.Name,
+            label = tool.Label,
+            description = tool.Description,
+            category = tool.Write ? "write" : "read",
+            tier = tool.Tier,
+            parameters = tool.ParametersSchema,
+            executionMode = "sequential",
+            write = tool.Write,
+            requiresDocument = tool.RequiresDocument,
+            promptSnippet = tool.PromptSnippet,
+            promptGuidelines = tool.PromptGuidelines,
+        };
+    }
+}