refactor: establish Brain-centered architecture and frontend/backend separation foundations by 4pmtong · Pull Request #1536 · eigent-ai/eigent

4pmtong · 2026-04-02T15:34:43Z

Related Issue

Closes #

Description

This PR delivers the current Brain + Web separation milestone.

It continues the ongoing refactor toward a Brain-centered architecture, where runtime capabilities are determined by the Brain environment rather than by client type. The goal of this phase is to preserve the existing Desktop experience while making Web + Local Brain a supported path built on shared, Brain-facing abstractions instead of Electron-specific assumptions.

Within that scope, this PR has three primary outcomes:

it strengthens the Brain-side architecture around routing, session handling, Hands resolution, capability detection, and resource abstraction
it advances frontend separation so shared web/desktop flows use Host and Brain-facing paths instead of depending directly on Electron-only globals
it folds several high-impact regressions discovered during the refactor back into the new architecture, so the milestone improves behavior without adding more legacy branching

Concretely, this PR moves the codebase further toward the target architecture described in the refactor work:

Brain capabilities are determined by deployment environment, not by client channel
shared frontend code should not depend directly on Electron-only globals
browser, file, and session flows should be routed through Brain / Hands abstractions
Desktop remains backward compatible while Web gains first-class support

Notable user-facing improvements included in this PR:

web login now returns users to the web app instead of redirecting into an Electron-only flow
Browser > CDP Browser Connection now works in dev:web by using Brain APIs in web mode
browser connection handling is normalized around endpoint-based state, keeping Local Brain as the default behavior today while preparing the path for future Hands-based browser resource expansion
task execution now reuses an existing connected CDP endpoint instead of resetting browser state unnecessarily
Agent Folder rendering now handles duplicate filenames correctly when multiple tasks generate files with the same name

This PR should be reviewed as a refactor milestone rather than as a collection of isolated bug fixes. The fixes included here are intentionally integrated into the Brain/Web separation work so the resulting behavior stays aligned with the target architecture.

Out of scope for this PR:

making RemoteHands the default runtime path
changing the default Local Brain deployment model
completing future cluster / worker orchestration beyond the extension points needed for this refactor phase

Testing Evidence (REQUIRED)

I have included human-verified testing evidence in this PR.
This PR includes frontend/UI changes, and I attached screenshot(s) or screen recording(s).
No frontend/UI changes in this PR.

What is the purpose of this pull request?

Bug fix
New Feature
Documentation update
Other

Contribution Guidelines Acknowledgement

I have read and agree to the Eigent Contribution Guideline

bytecii

In general the design is ok. But IMO we should refactor and put things to different PRs, otherwise it's hard to review.

bytecii · 2026-04-10T05:34:02Z

+    has_browser: bool = False
+    """browser hand: can control CDP browser"""
+
+    filesystem_scope: str = "full"


Maybe make full etc as the strenum types?

bytecii · 2026-04-10T05:34:36Z

+    """workspace root path"""
+
+    deployment_type: str = "local"
+    """deployment type (for logging): local | cloud_vm | sandbox | docker"""


what's the cloud vm? just curious

I think she meant a full virtual machine remotely; not just in docker.

bytecii · 2026-04-10T05:35:52Z

+        if in_docker:
+            logger.info("Brain running in Docker, using limited capabilities")
+            deployment = "docker"
+            caps = BrainCapabilities(


QQ should this be the HandCapabilities instead? for example browser is hand's capability?

bytecii · 2026-04-10T05:36:19Z

+from app.hands.interface import IHands
+
+# Terminal command allowlist for sandbox
+SANDBOX_TERMINAL_ALLOWLIST = frozenset(


Seems that this is unused?

bytecii · 2026-04-10T05:37:51Z

+    @abstractmethod
+    async def acquire(
+        self,
+        resource_type: str,


Make resource type to string enum?

bytecii · 2026-04-10T05:38:24Z

+from app.hands.interface import IHands
+
+
+class RemoteHands(IHands):


Maybe we can put all Hands to a hands subfolder and import it to the hands/init.py

bytecii · 2026-04-10T05:39:21Z

+
+
+class IHardwareBridge(ABC):
+    """Hardware capability bridge. Only Desktop has implementation, others use NullBridge"""


So should we implement this for the desktop?

bytecii · 2026-04-10T05:40:09Z

+from app.hands.capabilities import detect_capabilities
+from app.hands.environment_hands import EnvironmentHands
+
+logger = logging.getLogger("hands.resolver")


Let's use the following

Suggested change

logger = logging.getLogger("hands.resolver")

logger = logging.getLogger(__name__)

bytecii · 2026-04-10T05:52:21Z

+    # TODO(multi-tenant): os.environ is global – concurrent sessions overwrite
+    # each other's API keys, file paths, and browser ports.  Pass these values
+    # through Chat / request context instead of mutating the process environment.
    os.environ["file_save_path"] = data.file_save_path()


to my understanding as the brain in the server, will it has some problems if we set env as previously just in desktop?

Yes, It need redesign if we deploy the brain in the server, can use S3 instead of it.

a7m-1st · 2026-04-14T02:07:24Z

+            if hands is not None:
+                if (
+                    item in TERMINAL_DEPENDENT_TOOLKITS
+                    and not hands.can_execute_terminal()
+                ):
+                    logger.info(
+                        f"Skipping {item} for {agent_name}: no terminal hand"
+                    )
+                    continue
+                if (
+                    item in BROWSER_DEPENDENT_TOOLKITS
+                    and not hands.can_use_browser()
+                ):
+                    logger.info(
+                        f"Skipping {item} for {agent_name}: no browser hand"
+                    )
+                    continue


I think we can simplify this?

a7m-1st · 2026-04-14T02:16:51Z

+    workspace_root: str = "~/.eigent/workspace"
+    """workspace root path"""


Can we convert this to PATH type instead? Resolving the path might cause issues down the line.

a7m-1st · 2026-04-14T02:34:47Z

+@router.get("/files")
+async def list_project_files(
+    project_id: str = Query(..., description="Project ID"),
+    email: str = Query(..., description="User email"),
+    task_id: str | None = Query(
+        None, description="Optional task ID to scope listing"
+    ),
+) -> list[dict]:
+    """


Not sure if its me; my task was to write "hello world" file. The file is generated, but the route returned
/files/stream?path=task_1776131785382-755%5Chello_world.txt&project_id=1776121925475-837&email=ahmed%40gmail%20com

Thus if you try to click the file title in Eigent, it doesn't open the file. The file rendering is not there too.

Lastly just a small comment, previously we were fetching "All project files", thus it appeared having flat hierarchy. But now they are nested ; just a small comment.

a7m-1st · 2026-04-14T02:44:45Z

+        self.workspace_root = Path(workspace_root).expanduser()
+
+    def read_file(self, path: str) -> str:
+        resolved = self._ensure_in_workspace(path)


Actually, a neat idea (if we don't mind the bandwidth) is to just send base64 strings as attachments. Previously the /chat sends attaches[] with local file paths. Now it is:

1. upload file separately 2. get file_id 3. send the message with file references

We can instead attach a base64 string, then decode it back then save it in whatever the backend is hosted (vm, docker or others) or upload it in the background. This way we don't need to have separate steps; for <10mb resources.
ref: https://github.com/a7m-1st/medigent/blob/main/backend/app/utils/file_utils.py

a7m-1st · 2026-04-14T02:56:54Z

+    def list_dir(self, path: str) -> list[str]:
+        return [p.name for p in Path(path).iterdir()]
+


Rereading from disk (recursively) using python is expensive. Especially while SSE running, the python thread gets blocked thus waiting for some time before response. We mitigated this issue by migrating to websockets: ref: https://github.com/a7m-1st/medigent/blob/main/backend/app/controller/session_controller.py

Also Consider caching the get all files response unless there is a change.
ref: https://github.com/a7m-1st/medigent/blob/c32f3cf8cad1daa4fccb80085a9668286628f2f8/backend/app/controller/chat_controller.py#L453

For the first issue; there should be a better solution.. websockets just supressed the problem it didn't fix it.

WIP: refactor

cfe92bb

4pmtong marked this pull request as draft April 2, 2026 15:34

4pmtong added 4 commits April 5, 2026 10:21

fix: improve web browser/login flow and handle duplicate agent files

68e171b

add docs

e1f747e

Merge remote-tracking branch 'origin/main' into refactor_eigent

9210436

Merge remote-tracking branch 'origin/main' into refactor_eigent

94a07d5

github-advanced-security AI found potential problems Apr 5, 2026

View reviewed changes

Comment thread backend/app/controller/skill_controller.py Fixed

Comment thread backend/app/controller/tool_controller.py Fixed

github-advanced-security AI found potential problems Apr 5, 2026

View reviewed changes

Comment thread src/components/Folder/index.tsx Fixed

fix(ci): unblock workflows and address CodeQL findings

addb6fa

4pmtong marked this pull request as ready for review April 5, 2026 03:33

4pmtong requested review from Wendong-Fan, bytecii and nitpicker55555 April 5, 2026 03:37

4pmtong changed the title ~~WIP: refactor~~ refactor: land the Brain + Web separation milestone Apr 5, 2026

4pmtong changed the title ~~refactor: land the Brain + Web separation milestone~~ refactor: advance Brain-centered architecture and Web + Local Brain support Apr 5, 2026

4pmtong changed the title ~~refactor: advance Brain-centered architecture and Web + Local Brain support~~ refactor: establish Brain-centered architecture and frontend/backend separation foundations Apr 5, 2026

a7m-1st self-requested a review April 9, 2026 01:41

bytecii reviewed Apr 10, 2026

View reviewed changes

a7m-1st reviewed Apr 14, 2026

View reviewed changes

		from app.hands.interface import IHands


		class RemoteHands(IHands):



		class IHardwareBridge(ABC):
		"""Hardware capability bridge. Only Desktop has implementation, others use NullBridge"""

	logger = logging.getLogger("hands.resolver")
	logger = logging.getLogger(__name__)

		workspace_root: str = "~/.eigent/workspace"
		"""workspace root path"""

		def list_dir(self, path: str) -> list[str]:
		return [p.name for p in Path(path).iterdir()]

Conversation

4pmtong commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related Issue

Description

Testing Evidence (REQUIRED)

What is the purpose of this pull request?

Contribution Guidelines Acknowledgement

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bytecii left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

a7m-1st Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

4pmtong commented Apr 2, 2026 •

edited

Loading

a7m-1st Apr 14, 2026 •

edited

Loading