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

backend/app/controller/skill_controller.py

backend/app/controller/tool_controller.py

src/components/Folder/index.tsx

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

backend/app/hands/capabilities.py

+    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

backend/app/hands/capabilities.py

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


what's the cloud vm? just curious

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

backend/app/hands/capabilities.py

+        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

backend/app/hands/sandbox_hands.py

+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

backend/app/hands/cluster_interface.py

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


Make resource type to string enum?

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

backend/app/hands/remote_hands.py

+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

backend/app/hardware/interface.py

+
+
+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

backend/app/router_layer/hands_resolver.py

+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

backend/app/controller/chat_controller.py

+    # 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.

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 bot found potential problems Apr 5, 2026

View reviewed changes

backend/app/controller/skill_controller.py Fixed Show fixed Hide fixed

backend/app/controller/tool_controller.py Fixed Show fixed Hide fixed

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

View reviewed changes

src/components/Folder/index.tsx Fixed Show fixed Hide 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: establish Brain-centered architecture and frontend/backend separation foundations#1536

refactor: establish Brain-centered architecture and frontend/backend separation foundations#1536
4pmtong wants to merge 6 commits intomainfrom
refactor_eigent

4pmtong commented Apr 2, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bytecii left a comment

Uh oh!

bytecii Apr 10, 2026

Uh oh!

bytecii Apr 10, 2026

Uh oh!

bytecii Apr 10, 2026

Uh oh!

bytecii Apr 10, 2026

Uh oh!

bytecii Apr 10, 2026

Uh oh!

bytecii Apr 10, 2026

Uh oh!

bytecii Apr 10, 2026

Uh oh!

bytecii Apr 10, 2026

Uh oh!

bytecii Apr 10, 2026

Uh oh!

4pmtong Apr 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		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__)

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

4pmtong commented Apr 2, 2026 •

edited

Loading