Sync runtime dotenv loading

README.md

@@ -38,29 +38,80 @@ Maintenance rule:
   it is genuinely general-purpose.
 - Public documentation should be updated in the main repo, not duplicated here.
 
-## Copied From The Main Repository
+## Sync Policy
 
-These files/directories are copied from the main repo and should be refreshed
-when their corresponding upstream implementation changes:
+The Space should stay small and deployment-focused. When the main repository
+changes, sync only the files needed by the hosted browser app, then inspect the
+diff manually. Do not copy the whole main repository into this Space.
 
-- `agent_base/`: core ReAct runtime, prompts, tool registry, provider
-  compatibility, trace/session state, image handling, compaction logic, and
-  imported runtime helpers required by that core.
-- `agent_base/tools/`: hosted-safe tool implementations used by the frontend.
-- `frontend/static/`: shared browser UI assets, styles, and client logic.
-- `frontend/local_server.py`: WebSocket streaming frontend server base, with
-  Space-specific managed-workspace behavior preserved.
-- `requirements.txt`: Python runtime dependencies needed by the hosted app.
+### Fully Synced From The Main Repository
 
-When updating these files from the main repo, inspect the diff and preserve the
-Space-specific changes listed below.
+These files/directories should normally match the main repo exactly, unless a
+future Space-specific need is documented here:
 
-## Space-Specific Changes
-
-These behaviors are intentional Space-only deltas:
+| Path | Purpose |
+| --- | --- |
+| `agent_base/base.py` | Base agent interface. |
+| `agent_base/console_utils.py` | Shared console/event formatting helpers. |
+| `agent_base/context_compact.py` | Context compaction logic. |
+| `agent_base/model_profiles.py` | Provider/model profile helpers. |
+| `agent_base/prompt.py` | Base system prompt. |
+| `agent_base/prompts/system_base.md` | Shared base prompt text. |
+| `agent_base/provider_compat.py` | Provider compatibility normalization. |
+| `agent_base/session_state.py` | Session state serialization. |
+| `agent_base/tools/*.py` | Tool implementations exposed by the Space app. |
+| `agent_base/trace_utils.py` | Trace writing utilities. |
+| `agent_base/utils.py` | Shared runtime utilities, including default `.env` loading. |
+| `VERSION` | Version marker shown by the app/runtime when needed. |
+
+### Partially Synced And Space-Modified
+
+These files are related to main-repo files, but must be merged manually because
+the hosted Space has different deployment semantics:
+
+| Path | Maintenance rule |
+| --- | --- |
+| `agent_base/react_agent.py` | Keep core ReAct/runtime behavior aligned with main. Preserve Space compatibility only when it is genuinely required by the hosted app. |
+| `frontend/local_server.py` | Based on the main local frontend server, but Space-modified for managed temporary workspaces, forced `agent_workspace/` + `agent_trace/` layout, workspace zip download, automatic cleanup, trajectory collection hooks, and no arbitrary server-folder picker semantics. Never overwrite this file blindly from main. |
+| `frontend/static/index.html` | Starts from the main frontend HTML, but removes the local workspace picker and adds hosted workspace download UI. |
+| `frontend/static/app.js` | Starts from the main frontend client, but removes local folder selection and adds download-token / workspace-zip handling. |
+| `frontend/static/app.css` | Starts from the main frontend CSS, but includes Space-only hosted workspace/download styling and omits local folder picker modal styles. |
+| `requirements.txt` | Starts from the main runtime dependencies, but keeps Space-only hosted dependencies such as `huggingface_hub` and `uvicorn[standard]`. |
+| `app.py` | Space-only FastAPI/Hugging Face entrypoint. It owns startup, cleanup scheduling, static mounting, and hosted defaults. |
+| `check_space_runtime.py` | Space-only smoke test for deployment import/runtime sanity. |
+| `Dockerfile` | Space-only Docker build. |
+| `.dockerignore` | Space-only Docker context pruning. |
+| `.gitattributes` | Space repository metadata. |
+| `.gitignore` | Space-only generated files, cache, and temporary run ignores. |
+| `README.md` | Space maintenance notes only. Public project docs belong in the main repo. |
+
+### Out Of Scope For The Space
+
+These main-repo areas should not be copied into this Space unless the hosted app
+explicitly starts using them:
+
+| Main-repo path | Reason |
+| --- | --- |
+| `pyproject.toml`, `MANIFEST.in`, `researchharness/` | PyPI packaging belongs to the main open-source repo, not the hosted app mirror. |
+| `.github/` | GitHub CI/release automation does not run in the Hugging Face Space repo. |
+| `run_agent.py`, `run_server.py`, `run_frontend.py` | Local CLI/API/frontend entrypoints are not how the Space is launched. |
+| `api/` | OpenAI-compatible API server is not part of the Space app. |
+| `benchmarks/` | Benchmark adapters and benchmark docs belong to the main repo. |
+| `docs/` | Long-form tutorials belong to the main repo. |
+| `tests/` | Main local/CI tests belong to the main repo; Space keeps only focused smoke checks. |
+| `.env.example` | Public environment template belongs to the main repo. |
+| `agent_base/tools/README.md` | Tool documentation belongs to the main repo; Space keeps only runtime code. |
+| `agent_base/prompts/plugins/` | Plugin prompt assets are not used by the hosted app unless a future Space feature explicitly needs them. |
+| `workspace/`, `api_runs/`, `traces/` | Local placeholder/runtime directories are not checked into Space. |
+| local benchmark helpers such as `benchmarks/**/local_*` | Local development helpers must not be deployed. |
+
+Keeping these files out prevents stale code paths and misleading documentation
+from accumulating in the Space.
+
+## Space-Specific Runtime Behavior
+
+These behaviors are intentional hosted-app deltas:
 
-- `app.py` is the Hugging Face entrypoint and owns Space startup, cleanup, and
-  trajectory collection configuration.
 - Users cannot select arbitrary server folders. Each new chat gets an isolated
   managed run directory under `RH_SPACE_RUNS_DIR`.
 - The runtime layout is always:
@@ -81,21 +132,6 @@ These behaviors are intentional Space-only deltas:
 - Old inactive runs are cleaned periodically so the Space does not grow without
   bound.
 
-## Intentionally Removed From The Space
-
-The Space intentionally does not keep the full main-repo surface area:
-
-- `run_agent.py`, `run_server.py`, `run_frontend.py`
-- OpenAI-compatible API server code under `api/`
-- benchmark adapters and benchmark documentation under `benchmarks/`
-- long-form tutorials under `docs/`
-- local placeholder directories such as `workspace/`, `api_runs/`, and `traces/`
-- test fixtures and local test suites
-- `.env.example`
-
-Removing these files keeps the deployed app small and avoids stale code or
-misleading documentation drifting away from the main repository.
-
 ## Required Secrets
 
 Configure these as Hugging Face Space secrets before starting the app:

agent_base/react_agent.py

@@ -27,12 +27,11 @@ from agent_base.tools.tool_runtime import Bash, TerminalInterrupt, TerminalKill,
 from agent_base.tools.tool_user import AskUser
 from agent_base.tools.tool_web import ScholarSearch, WebFetch, WebSearch
 from agent_base.utils import (
-    PROJECT_ROOT,
     MissingRequiredEnvError,
     append_saved_image_paths_to_prompt,
     env_flag,
     image_input_content_parts,
-    load_dotenv,
+    load_default_dotenvs,
     read_role_prompt_files,
     require_required_env,
     safe_jsonable,
@@ -1494,7 +1493,7 @@ def _parse_cli_args(argv: list[str]) -> tuple[str, Optional[str], Optional[str],
 
 
 def main(argv: Optional[list[str]] = None) -> int:
-    load_dotenv(PROJECT_ROOT / ".env")
+    load_default_dotenvs()
     try:
         require_required_env("ResearchHarness agent")
         prompt_text, trace_dir, workspace_root, role_prompt, role_prompt_files, image_paths, chat_arg, extra_tools = _parse_cli_args(argv or sys.argv[1:])

agent_base/utils.py

@@ -69,6 +69,15 @@ def load_dotenv(path: Union[str, Path]) -> None:
         _DOTENV_LAST_LOADED[marker] = parsed_value
 
 
+def load_default_dotenvs() -> None:
+    """Load dotenv files for both installed and source-tree usage."""
+    cwd_env = Path.cwd() / ".env"
+    project_env = PROJECT_ROOT / ".env"
+    load_dotenv(cwd_env)
+    if cwd_env.resolve() != project_env.resolve():
+        load_dotenv(project_env)
+
+
 def env_flag(name: str) -> bool:
     return os.getenv(name, "").lower() in {"1", "true", "yes", "on"}
 

frontend/local_server.py

@@ -27,7 +27,7 @@ from agent_base.utils import (
     PROJECT_ROOT,
     append_saved_image_paths_to_prompt,
     image_input_content_parts,
-    load_dotenv,
+    load_default_dotenvs,
     require_required_env,
     safe_jsonable,
     stage_image_bytes_for_input,
@@ -608,7 +608,7 @@ def _run_agent_thread(
     model_name: str = "",
 ) -> None:
     try:
-        load_dotenv(PROJECT_ROOT / ".env")
+        load_default_dotenvs()
         require_required_env("ResearchHarness frontend")
         agent = FrontendInteractiveAgent(
             bridge=bridge,