fix(harness): resolve runtime paths from project root (#2642)

* fix(harness): resolve runtime paths from project root

* docs(config): update

* fix(config): address runtime path review feedback

* test(config): fix skills path e2e root

* test(config): cover legacy config fallback when project root lacks config files

Verifies that when DEER_FLOW_PROJECT_ROOT is unset and cwd has no
config.yaml/extensions_config.json, AppConfig and ExtensionsConfig fall back
to the legacy backend/repo-root candidates — the backward-compat path
requested in PR #2642 review.

---------

Co-authored-by: Willem Jiang <willem.jiang@gmail.com>

backend/packages/harness/deerflow/config/app_config.py

@@ -17,6 +17,7 @@ from deerflow.config.guardrails_config import GuardrailsConfig, load_guardrails_
 from deerflow.config.memory_config import MemoryConfig, load_memory_config_from_dict
 from deerflow.config.model_config import ModelConfig
 from deerflow.config.run_events_config import RunEventsConfig
+from deerflow.config.runtime_paths import existing_project_file
 from deerflow.config.sandbox_config import SandboxConfig
 from deerflow.config.skill_evolution_config import SkillEvolutionConfig
 from deerflow.config.skills_config import SkillsConfig
@@ -46,8 +47,8 @@ class CircuitBreakerConfig(BaseModel):
     recovery_timeout_sec: int = Field(default=60, description="Time in seconds before attempting to recover the circuit")
 
 
-def _default_config_candidates() -> tuple[Path, ...]:
-    """Return deterministic config.yaml locations without relying on cwd."""
+def _legacy_config_candidates() -> tuple[Path, ...]:
+    """Return source-tree config.yaml locations for monorepo compatibility."""
     backend_dir = Path(__file__).resolve().parents[4]
     repo_root = backend_dir.parent
     return (backend_dir / "config.yaml", repo_root / "config.yaml")
@@ -110,7 +111,8 @@ class AppConfig(BaseModel):
         Priority:
         1. If provided `config_path` argument, use it.
         2. If provided `DEER_FLOW_CONFIG_PATH` environment variable, use it.
-        3. Otherwise, search deterministic backend/repository-root defaults from `_default_config_candidates()`.
+        3. Otherwise, search the caller project root.
+        4. Finally, search legacy backend/repository-root defaults for monorepo compatibility.
         """
         if config_path:
             path = Path(config_path)
@@ -123,10 +125,14 @@ class AppConfig(BaseModel):
                 raise FileNotFoundError(f"Config file specified by environment variable `DEER_FLOW_CONFIG_PATH` not found at {path}")
             return path
         else:
-            for path in _default_config_candidates():
+            project_config = existing_project_file(("config.yaml",))
+            if project_config is not None:
+                return project_config
+
+            for path in _legacy_config_candidates():
                 if path.exists():
                     return path
-            raise FileNotFoundError("`config.yaml` file not found at the default backend or repository root locations")
+            raise FileNotFoundError("`config.yaml` file not found in the project root or legacy backend/repository root locations")
 
     @classmethod
     def from_file(cls, config_path: str | None = None) -> Self:

backend/packages/harness/deerflow/config/extensions_config.py

@@ -7,6 +7,8 @@ from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
+from deerflow.config.runtime_paths import existing_project_file
+
 
 class McpOAuthConfig(BaseModel):
     """OAuth configuration for an MCP server (HTTP/SSE transports)."""
@@ -73,8 +75,8 @@ class ExtensionsConfig(BaseModel):
         Priority:
         1. If provided `config_path` argument, use it.
         2. If provided `DEER_FLOW_EXTENSIONS_CONFIG_PATH` environment variable, use it.
-        3. Otherwise, check for `extensions_config.json` in the current directory, then in the parent directory.
-        4. For backward compatibility, also check for `mcp_config.json` if `extensions_config.json` is not found.
+        3. Otherwise, search the caller project root for `extensions_config.json`, then `mcp_config.json`.
+        4. For backward compatibility, also search legacy backend/repository-root defaults.
         5. If not found, return None (extensions are optional).
 
         Args:
@@ -83,8 +85,9 @@ class ExtensionsConfig(BaseModel):
         Resolution order:
             1. If provided `config_path` argument, use it.
             2. If provided `DEER_FLOW_EXTENSIONS_CONFIG_PATH` environment variable, use it.
-            3. Otherwise, search backend/repository-root defaults for
+            3. Otherwise, search the caller project root for
                `extensions_config.json`, then legacy `mcp_config.json`.
+            4. Finally, search backend/repository-root defaults for monorepo compatibility.
 
         Returns:
             Path to the extensions config file if found, otherwise None.
@@ -100,6 +103,10 @@ class ExtensionsConfig(BaseModel):
                 raise FileNotFoundError(f"Extensions config file specified by environment variable `DEER_FLOW_EXTENSIONS_CONFIG_PATH` not found at {path}")
             return path
         else:
+            project_config = existing_project_file(("extensions_config.json", "mcp_config.json"))
+            if project_config is not None:
+                return project_config
+
             backend_dir = Path(__file__).resolve().parents[4]
             repo_root = backend_dir.parent
             for path in (

backend/packages/harness/deerflow/config/paths.py

@@ -3,6 +3,8 @@ import re
 import shutil
 from pathlib import Path, PureWindowsPath
 
+from deerflow.config.runtime_paths import runtime_home
+
 # Virtual path prefix seen by agents inside the sandbox
 VIRTUAL_PATH_PREFIX = "/mnt/user-data"
 
@@ -11,9 +13,8 @@ _SAFE_USER_ID_RE = re.compile(r"^[A-Za-z0-9_\-]+$")
 
 
 def _default_local_base_dir() -> Path:
-    """Return the repo-local DeerFlow state directory without relying on cwd."""
-    backend_dir = Path(__file__).resolve().parents[4]
-    return backend_dir / ".deer-flow"
+    """Return the caller project's writable DeerFlow state directory."""
+    return runtime_home()
 
 
 def _validate_thread_id(thread_id: str) -> str:
@@ -81,7 +82,7 @@ class Paths:
     BaseDir resolution (in priority order):
         1. Constructor argument `base_dir`
         2. DEER_FLOW_HOME environment variable
-        3. Repo-local fallback derived from this module path: `{backend_dir}/.deer-flow`
+        3. Caller project fallback: `{project_root}/.deer-flow`
     """
 
     def __init__(self, base_dir: str | Path | None = None) -> None:

backend/packages/harness/deerflow/config/runtime_paths.py

@@ -0,0 +1,41 @@
+"""Runtime path resolution for standalone harness usage."""
+
+import os
+from pathlib import Path
+
+
+def project_root() -> Path:
+    """Return the caller project root for runtime-owned files."""
+    if env_root := os.getenv("DEER_FLOW_PROJECT_ROOT"):
+        root = Path(env_root).resolve()
+        if not root.exists():
+            raise ValueError(f"DEER_FLOW_PROJECT_ROOT is set to '{env_root}', but the resolved path '{root}' does not exist.")
+        if not root.is_dir():
+            raise ValueError(f"DEER_FLOW_PROJECT_ROOT is set to '{env_root}', but the resolved path '{root}' is not a directory.")
+        return root
+    return Path.cwd().resolve()
+
+
+def runtime_home() -> Path:
+    """Return the writable DeerFlow state directory."""
+    if env_home := os.getenv("DEER_FLOW_HOME"):
+        return Path(env_home).resolve()
+    return project_root() / ".deer-flow"
+
+
+def resolve_path(value: str | os.PathLike[str], *, base: Path | None = None) -> Path:
+    """Resolve absolute paths as-is and relative paths against the project root."""
+    path = Path(value)
+    if not path.is_absolute():
+        path = (base or project_root()) / path
+    return path.resolve()
+
+
+def existing_project_file(names: tuple[str, ...]) -> Path | None:
+    """Return the first existing named file under the project root."""
+    root = project_root()
+    for name in names:
+        candidate = root / name
+        if candidate.is_file():
+            return candidate
+    return None

backend/packages/harness/deerflow/config/skills_config.py

@@ -1,11 +1,9 @@
+import os
 from pathlib import Path
 
 from pydantic import BaseModel, Field
 
-
-def _default_repo_root() -> Path:
-    """Resolve the repo root without relying on the current working directory."""
-    return Path(__file__).resolve().parents[5]
+from deerflow.config.runtime_paths import project_root, resolve_path
 
 
 class SkillsConfig(BaseModel):
@@ -17,7 +15,7 @@ class SkillsConfig(BaseModel):
     )
     path: str | None = Field(
         default=None,
-        description="Path to skills directory. If not specified, defaults to ../skills relative to backend directory",
+        description="Path to skills directory. If not specified, defaults to skills under the caller project root.",
     )
     container_path: str = Field(
         default="/mnt/skills",
@@ -32,15 +30,11 @@ class SkillsConfig(BaseModel):
             Path to the skills directory
         """
         if self.path:
-            # Use configured path (can be absolute or relative)
-            path = Path(self.path)
-            if not path.is_absolute():
-                # If relative, resolve from the repo root for deterministic behavior.
-                path = _default_repo_root() / path
-            return path.resolve()
-        else:
-            # Default: <repo_root>/skills
-            return _default_repo_root() / "skills"
+            # Use configured path (can be absolute or relative to project root)
+            return resolve_path(self.path)
+        if env_path := os.getenv("DEER_FLOW_SKILLS_PATH"):
+            return resolve_path(env_path)
+        return project_root() / "skills"
 
     def get_skill_container_path(self, skill_name: str, category: str = "public") -> str:
         """

backend/packages/harness/deerflow/skills/storage/local_skill_storage.py

@@ -12,7 +12,7 @@ from collections.abc import Iterable
 from datetime import UTC, datetime
 from pathlib import Path
 
-from deerflow.config.skills_config import _default_repo_root
+from deerflow.config.runtime_paths import resolve_path
 from deerflow.skills.storage.skill_storage import SKILL_MD_FILE, SkillStorage
 from deerflow.skills.types import SkillCategory
 
@@ -44,10 +44,7 @@ class LocalSkillStorage(SkillStorage):
             config = app_config or get_app_config()
             self._host_root: Path = config.skills.get_skills_path()
         else:
-            path = Path(host_path)
-            if not path.is_absolute():
-                path = _default_repo_root() / path
-            self._host_root = path.resolve()
+            self._host_root = resolve_path(host_path)
 
     # ------------------------------------------------------------------
     # Abstract operation implementations