Name		Name	Last commit message	Last commit date
parent directory ..
README.md		README.md
code-execution.md		code-execution.md
execution-guard.md		execution-guard.md
mcp-dispatch.md		mcp-dispatch.md
pytest-bridge.md		pytest-bridge.md
python-runtime.md		python-runtime.md

README.md

Execution System Architecture

The execution system is the shared runtime in source/DevTools.Execution/. It discovers user code, builds the execution tree, watches roots for changes, resolves script dependencies, and dispatches work through host adapters.

The platform is not Revit-only. Revit and AutoCAD currently provide host adapters; future .NET-capable hosts should plug in through the same abstractions.

Last updated: 2026-09-15

Source Map

Area	Path
Shared registrations	source/DevTools.Execution/ExecutionExtensions.cs
Orchestrator	source/DevTools.Execution/Services/ExecutionOrchestrator.cs
Providers	source/DevTools.Execution/Providers/
CPython runtime	source/DevTools.Execution/Providers/Python/
External pipe server	source/DevTools.Execution/External/DevToolsPipeServer.cs
MCP runtime	source/DevTools.Execution/External/Mcp/
Pytest bridge	source/DevTools.Execution/External/Testing/
Embedded scripts	source/DevTools.Execution/Resources/scripts/
Execution guard	source/RevitDevTool.Core/Execution/
Revit adapters	source/RevitDevTool/Adapters/
AutoCAD adapters	source/AcadDevTool/Adapters/

Architecture

flowchart TB
    UI["Shared presentation UI\nCommand/Package/MCP/Memory views"]
    Orch["ExecutionOrchestrator"]
    Providers["IExecutionProvider\nAssembly + Script"]
    Strategies["IExecutionStrategy\nAssembly, Python, IronPython, FSharp, CSharp"]
    Host["Host adapters\nIHostContextExecutor, ICommandDiscovery, ICommandRunner, script bridges"]
    Guard["ExecutionGuard\nDialog + Failure suppression"]
    Services["TreeStateManager\nFileWatcherService\nPackageService"]
    External["DevToolsPipeServer\nMCP + pytest routes"]

    UI --> Orch
    Orch --> Providers
    Providers --> Strategies
    Strategies --> Host
    Host --> Guard
    Orch --> Services
    External --> Orch
    External --> Services

DevTools.Execution owns orchestration and contracts. Host projects own API-thread dispatch, command discovery, command invocation, script builtins, and host-specific context.

Execution Enums

Two enums in source/DevTools.Execution.Abstractions/ separate container organisation from execution backend:

public enum ContainerMode { Script, Assembly }
public enum ExecutionMode { Python, IronPython, FSharp, CSharp, Dotnet, Unsupported }
public enum ExecutionGuardMode { Passthrough, Suppress }

Host Boundary

Shared execution depends on interfaces:

Interface	Purpose
IHostContextExecutor	Marshal work to the host-safe context/API thread.
ICommandDiscovery	Parse host commands from an assembly.
ICommandRunner	Invoke discovered or compiled commands.
ICompiledScriptBridge	Parent-bind host APIs, find the compiled command type, rewrite host-year #r paths. FSI compile refs are derived from parent Locations in Execution, not a fourth contract member.
IPythonBridge	Configure CPython builtins/scope for the host.
IIronPythonBridge	Configure IronPython builtins and host assemblies; TryGetHostEngine is pyRevit ScriptExecutor or null (embedded 3.4.2).
DebugEndpoints	Cached CPython/IronPython listen ports and attach flags for Execution UI.
IDocumentBridge	Open, close, and save documents in the host context.

Revit wiring lives in RevitHostingExtensions. AutoCAD wiring lives in AcadHostingExtensions. New hosts should add their own adapter project rather than leaking host APIs into DevTools.Execution.

ExecutionExtensions.AddExecutionServices registers DebugEndpoints, PythonInitializer, and IronPythonInitializer. PythonExecutor, PythonDebugger, and IronPythonDebugger are public static helpers (not DI singletons). CAD start, port lease, and catalog reload: python-runtime.md.

Deep Documentation

Topic	File
Script runtimes, orchestrator flow, package service	code-execution.md
CPython init, host attach, providers	python-runtime.md
Dialog & failure suppression (ExecutionGuard)	execution-guard.md
Pytest in-host bridge	pytest-bridge.md
MCP primitive dispatch & pipe server	mcp-dispatch.md

Verification

Current tests are useful but shallow. When changing execution behavior:

Build the most relevant host/year with scripts/build-host.ps1.
Add a focused test for pure shared logic when practical.
Document live-host verification gaps explicitly.

Related Docs

docs/agents/execution-system.md (agent digest — quick reference)
docs/agents/host-boundaries.md
docs/architecture/MCP/README.md
docs/architecture/Execution/pytest-bridge.md
docs/architecture/Logging/README.md

RevitDevTool/docs/architecture/Execution at develop · trgiangv/RevitDevTool · GitHub

Expand file tree

Breadcrumbs

Execution

Directory actions

More options