Add support for an ADAPTER_PYTHON environment variable as a shortcut for setting python_env in the config

README.md

@@ -94,12 +94,19 @@ Run the code-review example:
 
 ```bash
 export NVIDIA_API_KEY=...
-export HERMES_PYTHON="$PWD/.tmp/hermes-venv/bin/python"
+export ADAPTER_PYTHON="$PWD/.tmp/hermes-venv/bin/python"
 
 .venv/bin/python -m examples.code_review_agent \
   --input "Reply with exactly: fabric works"
 ```
 
+`ADAPTER_PYTHON` selects the interpreter used to launch any Python adapter.
+An explicit `harness.settings.python` or `harness.settings.python_env` takes
+precedence. If none is configured and `ADAPTER_PYTHON` is unset, Fabric falls
+back to `python3`. 
+
+Use `ADAPTER_PYTHON` when the harness is installed in a separate environment from Fabric. The environment must have the adapter package installed, the adapters tend to be small and self-contained with minimal dependencies.
+
 The run returns a normalized `RunResult` JSON payload and writes logs/artifacts
 under `examples/code_review_agent/artifacts/hermes-sdk/`. Its complete base
 config and clone-based variants live in

adapters/codex-cli/pyproject.toml

@@ -26,4 +26,4 @@ include = ["nemo_fabric_adapters.codex_cli*"]
 "share/nemo-fabric/adapters/codex-cli" = ["fabric-adapter.json"]
 
 [tool.uv.sources]
-nemo-fabric-adapters-common = { path = "../common" }
+nemo-fabric-adapters-common = { path = "../common", editable = true }

adapters/codex-cli/src/nemo_fabric_adapters/codex_cli/adapter.py

@@ -47,36 +47,6 @@
     "PostToolUseFailure",
     "PreToolUse",
 }
-INHERITED_ENV_NAMES = {
-    "APPDATA",
-    "CODEX_HOME",
-    "COMSPEC",
-    "HOME",
-    "HTTP_PROXY",
-    "HTTPS_PROXY",
-    "LANG",
-    "LC_ALL",
-    "LC_CTYPE",
-    "LOCALAPPDATA",
-    "NO_PROXY",
-    "PATH",
-    "PATHEXT",
-    "SHELL",
-    "SSL_CERT_DIR",
-    "SSL_CERT_FILE",
-    "SYSTEMROOT",
-    "TEMP",
-    "TMP",
-    "TMPDIR",
-    "USERPROFILE",
-    "XDG_CACHE_HOME",
-    "XDG_CONFIG_HOME",
-    "XDG_DATA_HOME",
-    "http_proxy",
-    "https_proxy",
-    "no_proxy",
-}
-
 
 class CodexSettings(NamedTuple):
     telemetry_provider: str
@@ -488,15 +458,20 @@ def build_env(
     *,
     relay_gateway_url: str | None = None,
 ) -> dict[str, str]:
-    env = {name: os.environ[name] for name in INHERITED_ENV_NAMES if name in os.environ}
+    env = common_utils.virtualenv_subprocess_env()
+
     configured = common_utils.settings_payload(payload).get("env")
     if configured is None:
         configured = {}
+
     if not isinstance(configured, Mapping):
         raise ValueError("env must be a mapping of variable names to values")
+
     env.update({str(key): str(value) for key, value in configured.items()})
+
     if relay_gateway_url is not None:
         env["NEMO_RELAY_GATEWAY_URL"] = relay_gateway_url
+
     return env
 
 

adapters/common/src/nemo_fabric_adapters/common/utils.py

@@ -22,6 +22,36 @@
     )
 
 
+def current_virtualenv() -> Path | None:
+    """Return the current virtual environment, if Python is running in one."""
+
+    if sys.prefix == getattr(sys, "base_prefix", sys.prefix):
+        return None
+    return Path(sys.prefix)
+
+
+def virtualenv_subprocess_env() -> dict[str, str]:
+    """
+    When inside of a virtual environment, return a copy of os.environ with the virtualenv exposed.
+
+    When outside of a virtual environment a copy of os.environ is returned.
+    """
+
+    env = os.environ.copy()
+    virtualenv = current_virtualenv()
+    if virtualenv is None:
+        return env   
+
+    scripts = virtualenv / ("Scripts" if os.name == "nt" else "bin")
+    path = env.get("PATH")
+    env["VIRTUAL_ENV"] = str(virtualenv)
+    env["PATH"] = os.pathsep.join(
+        part for part in (str(scripts), path) if part
+    )
+    env.pop("PYTHONHOME", None)
+    return env
+
+
 def effective_config(payload: dict[str, Any]) -> dict[str, Any]:
     return payload.get("effective_config") or {}
 

adapters/hermes-cli/pyproject.toml

@@ -27,4 +27,4 @@ include = ["nemo_fabric_adapters.hermes_cli*"]
 "share/nemo-fabric/adapters/hermes-cli" = ["fabric-adapter.json"]
 
 [tool.uv.sources]
-nemo-fabric-adapters-common = { path = "../common" }
+nemo-fabric-adapters-common = { path = "../common", editable = true }

adapters/hermes-cli/src/nemo_fabric_adapters/hermes_cli/adapter.py

@@ -179,12 +179,17 @@ def build_command(
 
 
 def build_env(settings: dict[str, Any], hermes_home: Path) -> dict[str, str]:
-    env = os.environ.copy()
-    env.update({str(key): str(value) for key, value in (settings.get("env") or {}).items()})
+    env = common_utils.virtualenv_subprocess_env()
+
+    env.update({
+        str(key): str(value)
+        for key, value in (settings.get("env") or {}).items()
+    })
     env["HOME"] = str(hermes_home)
     env["HERMES_HOME"] = str(hermes_home)
     env.setdefault("HERMES_YOLO_MODE", "1")
     env.setdefault("HERMES_ACCEPT_HOOKS", "1")
+
     return env
 
 

adapters/hermes-sdk/pyproject.toml

@@ -26,4 +26,4 @@ include = ["nemo_fabric_adapters.hermes_sdk*"]
 "share/nemo-fabric/adapters/hermes-sdk" = ["fabric-adapter.json"]
 
 [tool.uv.sources]
-nemo-fabric-adapters-common = { path = "../common" }
+nemo-fabric-adapters-common = { path = "../common", editable = true }

crates/fabric-core/src/error.rs

@@ -147,6 +147,14 @@ pub enum FabricError {
         /// Underlying JSON parse error.
         source: serde_json::Error,
     },
+    /// The default Python adapter interpreter path was invalid.
+    #[error("environment variable `ADAPTER_PYTHON` (`{value}`) must point to a valid file")]
+    InvalidAdapterPython {
+        /// Value read from `ADAPTER_PYTHON`.
+        value: String,
+        /// Path resolved from the configured value.
+        path: PathBuf,
+    },
     /// A process runner failed to start or complete.
     #[error("process runner failed for `{command}`: {source}")]
     ProcessRunner {

crates/fabric-core/src/runtime.rs

@@ -4,6 +4,7 @@
 //! Runtime invocation helpers.
 
 use std::collections::BTreeMap;
+use std::ffi::OsString;
 use std::io::{ErrorKind, Write};
 use std::path::{Path, PathBuf};
 use std::process::{Command, Stdio};
@@ -23,6 +24,7 @@ use crate::config::{
 use crate::error::{FabricError, Result};
 
 static NEXT_ID: AtomicU64 = AtomicU64::new(1);
+const ADAPTER_PYTHON_ENV: &str = "ADAPTER_PYTHON";
 #[cfg(test)]
 static TEST_STOPPED_AGENTS: Mutex<Vec<String>> = Mutex::new(Vec::new());
 
@@ -584,6 +586,12 @@ struct PythonAdapterSettings {
     env: BTreeMap<String, String>,
 }
 
+#[derive(Debug, Clone, PartialEq)]
+struct PythonCommand {
+    path: PathBuf,
+    adapter_python_value: Option<String>,
+}
+
 impl RuntimeAdapter for ProcessAdapter {
     fn start(&self, plan: &RunPlan, environment: EnvironmentHandle) -> Result<RuntimeHandle> {
         if environment.provider != "local" {
@@ -639,6 +647,7 @@ impl RuntimeAdapter for PythonAdapter {
                 adapter_kind: AdapterKind::Python,
             });
         }
+        preflight_python_adapter(plan)?;
         let runtime_id = new_id("runtime");
         let runtime_binding = runtime_binding(&runtime_id, plan, &environment)?;
         Ok(RuntimeHandle {
@@ -926,7 +935,7 @@ fn run_python_adapter(
         .or_else(|| runtime.environment.workspace.clone())
         .unwrap_or_else(|| plan.agent_root.clone());
 
-    let python = resolve_python_command(&plan.config_root, &settings);
+    let python = resolve_python_command(&plan.config_root, &settings).path;
     let mut artifacts = artifact_manifest(plan)?;
     let fabric_home = prepare_fabric_home(&artifacts, runtime, &invocation)?;
     let relay_config = prepare_relay_runtime_config(
@@ -1319,16 +1328,61 @@ fn resolve_command_path(root: &Path, path: &Path) -> PathBuf {
     path.to_path_buf()
 }
 
-fn resolve_python_command(root: &Path, settings: &PythonAdapterSettings) -> PathBuf {
+fn preflight_python_adapter(plan: &RunPlan) -> Result<()> {
+    let settings = parse_python_settings(plan)?;
+    let command = resolve_python_command(&plan.config_root, &settings);
+    validate_python_command(command)
+}
+
+fn validate_python_command(command: PythonCommand) -> Result<()> {
+    if let Some(value) = command.adapter_python_value {
+        if !command.path.is_file() {
+            return Err(FabricError::InvalidAdapterPython {
+                value,
+                path: command.path,
+            });
+        }
+    }
+    Ok(())
+}
+
+fn resolve_python_command(root: &Path, settings: &PythonAdapterSettings) -> PythonCommand {
+    resolve_python_command_with_env(root, settings, |name| std::env::var_os(name))
+}
+
+fn resolve_python_command_with_env(
+    root: &Path,
+    settings: &PythonAdapterSettings,
+    env: impl Fn(&str) -> Option<OsString>,
+) -> PythonCommand {
     if let Some(path) = settings.python.as_ref() {
-        return resolve_command_path(root, path);
+        return PythonCommand {
+            path: resolve_command_path(root, path),
+            adapter_python_value: None,
+        };
     }
     if let Some(env_name) = settings.python_env.as_ref() {
-        if let Some(path) = std::env::var_os(env_name) {
-            return resolve_command_path(root, Path::new(&path));
+        if let Some(path) = env(env_name) {
+            return PythonCommand {
+                path: resolve_command_path(root, Path::new(&path)),
+                adapter_python_value: None,
+            };
         }
+        return PythonCommand {
+            path: PathBuf::from("python3"),
+            adapter_python_value: None,
+        };
+    }
+    if let Some(value) = env(ADAPTER_PYTHON_ENV) {
+        return PythonCommand {
+            path: resolve_command_path(root, Path::new(&value)),
+            adapter_python_value: Some(value.to_string_lossy().into_owned()),
+        };
+    }
+    PythonCommand {
+        path: PathBuf::from("python3"),
+        adapter_python_value: None,
     }
-    PathBuf::from("python3")
 }
 
 fn absolute_path(path: PathBuf) -> Result<PathBuf> {
@@ -2503,6 +2557,93 @@ runtime:
         let _ = fs::remove_dir_all(root);
     }
 
+    fn python_settings() -> PythonAdapterSettings {
+        PythonAdapterSettings {
+            module: "test.adapter".to_string(),
+            python: None,
+            python_env: None,
+            args: Vec::new(),
+            cwd: None,
+            env: BTreeMap::new(),
+        }
+    }
+
+    #[test]
+    fn python_command_uses_adapter_python_as_default_python_env() {
+        let root = Path::new("/config");
+        let settings = python_settings();
+        let command = resolve_python_command_with_env(root, &settings, |name| {
+            (name == ADAPTER_PYTHON_ENV).then(|| OsString::from("venv/bin/python"))
+        });
+
+        assert_eq!(command.path, root.join("venv/bin/python"));
+        assert_eq!(
+            command.adapter_python_value.as_deref(),
+            Some("venv/bin/python")
+        );
+
+        let command = resolve_python_command_with_env(root, &settings, |_| None);
+        assert_eq!(command.path, PathBuf::from("python3"));
+        assert_eq!(command.adapter_python_value, None);
+    }
+
+    #[test]
+    fn explicit_python_settings_override_adapter_python() {
+        let root = Path::new("/config");
+        let mut settings = python_settings();
+        settings.python_env = Some("CUSTOM_PYTHON".to_string());
+        let command = resolve_python_command_with_env(root, &settings, |name| match name {
+            "CUSTOM_PYTHON" => Some(OsString::from("/custom/python")),
+            ADAPTER_PYTHON_ENV => Some(OsString::from("/adapter/python")),
+            _ => None,
+        });
+        assert_eq!(command.path, PathBuf::from("/custom/python"));
+        assert_eq!(command.adapter_python_value, None);
+
+        let command = resolve_python_command_with_env(root, &settings, |name| {
+            (name == ADAPTER_PYTHON_ENV).then(|| OsString::from("/adapter/python"))
+        });
+        assert_eq!(command.path, PathBuf::from("python3"));
+        assert_eq!(command.adapter_python_value, None);
+
+        settings.python = Some(PathBuf::from("/configured/python"));
+        let command = resolve_python_command_with_env(root, &settings, |_| {
+            Some(OsString::from("/environment/python"))
+        });
+        assert_eq!(command.path, PathBuf::from("/configured/python"));
+        assert_eq!(command.adapter_python_value, None);
+    }
+
+    #[test]
+    fn adapter_python_preflight_requires_a_file() {
+        let root = std::env::temp_dir().join(new_id("fabric-adapter-python-test"));
+        fs::create_dir_all(&root).expect("create test directory");
+        let interpreter = root.join("python");
+        fs::write(&interpreter, "").expect("create interpreter file");
+
+        validate_python_command(PythonCommand {
+            path: interpreter,
+            adapter_python_value: Some("python".to_string()),
+        })
+        .expect("file path should pass preflight");
+
+        let error = validate_python_command(PythonCommand {
+            path: root.join("missing-python"),
+            adapter_python_value: Some("missing-python".to_string()),
+        })
+        .expect_err("missing path should fail preflight");
+        assert!(matches!(error, FabricError::InvalidAdapterPython { .. }));
+
+        let error = validate_python_command(PythonCommand {
+            path: root.clone(),
+            adapter_python_value: Some(root.to_string_lossy().into_owned()),
+        })
+        .expect_err("directory path should fail preflight");
+        assert!(matches!(error, FabricError::InvalidAdapterPython { .. }));
+
+        let _ = fs::remove_dir_all(root);
+    }
+
     #[test]
     fn python_adapter_runs_hermes_shim() {
         let plan = resolve_run_plan(fixture_agent_dir(), Some("env_local")).expect("run plan");