RFC: FractalMind Three-Plane Architecture - SUI Authority, envd P2P Data/Execution, and Applications

[elliot245]

Summary

FractalMind AI currently spans several repositories and capabilities: SUI contracts, envd, remote desktop, Agent Console, messaging adapters, agent lifecycle tools, team/OKR tooling, and skill packages.

The capabilities are useful, but the architecture is harder to explain than it needs to be because runtime services, applications, trust primitives, and distributable skills are often presented as peer components.

This RFC proposes a simpler three-plane model:

1. SUI contracts as the Control / Authority Plane
2. envd as the P2P Data / Execution Plane
3. Agent Console and envd-desktop as the Application Plane

The short version is:

SUI decides who is allowed to do what. envd delivers and executes commands and data. Applications provide the user-facing and agent-facing capabilities.

1. Control / Authority Plane: SUI Contracts

SUI should be the durable source of authority for:

• organization and agent identity
• node and agent registration
• scoped capabilities
• delegation
• revocation
• governance
• bounded usage policies
• audit anchors

An authority decision should answer:

Can signer X perform action Y against organization, node, or agent Z under the current policy?

SUI should not merely provide a key format while an off-chain bearer token remains the real authority. The contract state, capability proof, or delegated authority derived from it should be what a target node ultimately verifies.

What should not go on-chain

The authority plane should not carry high-frequency or high-volume runtime data such as:

• heartbeats
• mouse or keyboard events
• SDP / ICE signaling payloads
• video or audio
• logs and terminal streams
• every individual shell or lifecycle command

Putting these on-chain would add latency, cost, availability coupling, and unnecessary data exposure.

Instead, SUI should grant a bounded capability with fields such as:

• signer / delegate
• target organization, node, or agent
• allowed action or scope
• expiration
• maximum uses or budget
• revocation state

2. P2P Data / Execution Plane: envd

envd should become the common peer-to-peer fabric for:

• peer discovery and authenticated connectivity
• encrypted command and result delivery
• node and agent inventory
• heartbeats and liveness
• logs and file transfer
• local agent lifecycle execution
• self-healing
• terminal and desktop session signaling
• WireGuard, WSS, WebRTC, and TURN-assisted connectivity where needed

The local agent-manager functionality fits here as a host execution adapter. It is not a separate network plane. envd can call a local adapter for tmux, systemd, Docker, or other runtimes while keeping one network protocol between peers.

Proposed command flow

1. SUI grants a capability or delegation with scope, target, expiry, and limits.
2. Agent Console creates a wallet- or passkey-signed session or command intent.
3. The intent includes a nonce, TTL, target, action, and capability reference.
4. envd transports the signed intent to the target peer.
5. The target envd verifies the signer, capability, scope, target, nonce, TTL, replay state, and a sufficiently fresh revocation checkpoint.
6. The target executes the action through the local runtime adapter.
7. Results and evidence return through the envd data path.
8. A session outcome or evidence hash may be anchored to SUI asynchronously. Raw logs, media, and inputs remain off-chain.

Availability policy

Nodes should not require a synchronous SUI RPC request for every mouse input or low-level command.

A reasonable policy could be:

• allow an already-issued, unexpired low-risk session to continue within its capability limits
• require fresh authority or revocation state for new high-risk actions
• fail closed for new high-risk authorization when authority state cannot be refreshed

The exact freshness window and risk classes need to be specified.

3. Application Plane

Agent Console

Agent Console is the controller application. It should:

• authenticate with a wallet or passkey
• discover authorized organizations, nodes, and agents
• create signed session and command intents
• display status, logs, and audit evidence
• request remote desktop, terminal, lifecycle, and workflow capabilities

It should not depend on a permanent coordinator bearer token or hold a node's long-lived local credential.

envd-desktop

envd-desktop is a node-side remote desktop application. It should:

• start only for an authorized, session-scoped request
• bind viewer/controller permissions to the verified capability
• stream media and input through WebRTC, using TURN when direct connectivity fails
• emit bounded session evidence without publishing raw media or inputs on-chain

The application is separate from the plane it uses: envd-desktop is an application, while its media and input streams travel through the data plane.

Other applications and adapters

Other FractalMind components can be positioned without creating more architecture planes:

• fractalbot: human-channel application adapter for Slack, Telegram, Feishu, Discord, and other channels
• agent-manager: local node execution adapter
• team, chat, OKR, calendar, and heartbeat skills: capabilities or distribution packages
• Explorer: read-only application / projection
• D-Email: optional asynchronous messaging application or transport

Skills, ROMs, specs, and applications should not be counted as independent runtime infrastructure services.

Current Implementation Gap

The proposed model is a target architecture, not a description of the current runtime.

Today:

• envd primarily uses coordinator REST/WebSocket connectivity rather than a complete P2P authority model
• Agent Console relies on a coordinator API token
• the coordinator currently participates in privileged command routing
• SUI identity can protect parts of the node connection, but SUI policy is not yet the live authorization source for every remote-control session
• fractalmind-envd contains an older TypeScript gateway alongside the newer embedded Go coordinator
• authority responsibilities overlap between fractalmind-protocol and the policy Move package inside fractalmind-envd

The coordinator should gradually become a replaceable, multi-instance rendezvous / relay / index cache, not an authority owner. A relay outage should affect connectivity, but compromising a relay should not grant control over a node.

Repository and Component Simplification

The three-plane model suggests the following cleanup:

Keep as core products

• fractalmind-protocol: Control / Authority Plane contracts and SDK
• fractalmind-envd: P2P Data / Execution Plane
• agent-console: controller application
• envd-desktop: node-side remote desktop application, currently shipped with envd
• skills: capability catalog and distribution surface

Consolidate or retire

• remove the legacy TypeScript gateway inside fractalmind-envd after Go parity is confirmed
• retire the standalone sponsor command after sponsorship is fully represented as an envd role
• move agent availability/calendar behavior into agent-manager where the runtime state already lives
• stop presenting team/OKR/chat/turbo skills as independent runtime services
• make one authority contract package canonical instead of maintaining overlapping policy sources

The private fractalmind-gateway repository is a separate Postgres/Redis private-deployment product line. It should receive an explicit keep/archive/rename decision rather than being confused with the legacy gateway inside envd.

Proposed Migration

Phase 0: Freeze contracts and vocabulary

• adopt Control/Authority, Data/Execution, and Application Plane terminology
• define a canonical NodeCommand / NodeEvent envelope
• include signer, target, action, capability reference, nonce, TTL, idempotency key, and evidence fields
• define the minimum SUI capability, delegation, and revocation contracts
• select one canonical envd checkout and implementation source
• mark the old gateway implementations as deprecated

Phase 1: Replace bearer authority

• add wallet/passkey signed intents to Agent Console
• verify capabilities and revocation state at the target envd
• encapsulate tmux/systemd/Docker lifecycle behavior behind a local runtime adapter
• scope desktop, terminal, logs, and lifecycle operations separately
• prevent fractalbot from directly invoking local lifecycle commands outside the authority flow

Phase 2: Decentralize connectivity

• reduce the coordinator to rendezvous, relay, and index/cache responsibilities
• support replaceable or multiple relay instances
• make peer-side verification sufficient for authorization
• anchor bounded outcome/evidence hashes to SUI asynchronously
• remove duplicate gateway and authority implementations

Open Questions

1. What should the canonical SUI capability object look like?
2. Which scopes are required initially: view, control, logs, terminal, shell, lifecycle, deploy?
3. Which actions require fresh chain state, and which may use a cached revocation checkpoint?
4. How should capability delegation and maximum-use budgets work?
5. What should provide peer discovery and rendezvous before full P2P discovery is available?
6. Should relay selection be on-chain, DHT-based, configuration-based, or hybrid?
7. How should session evidence be represented without leaking private operational data?
8. Should the private centralized deployment remain a supported edition or be archived?

Proposed Decision

Adopt the three-plane model as the target architecture:

• SUI contracts: Control / Authority Plane
• envd: P2P Data / Execution Plane
• Agent Console and envd-desktop: Application Plane

Begin with Phase 0. This gives the project a stable vocabulary and security boundary before repository consolidation or production migration.

Feedback is especially welcome on capability design, revocation freshness, P2P rendezvous, and the first set of application scopes.

[elliot245]

The RFC GAP has been split into executable, repository-scoped issues.

Cross-repository tracker and dependency graph:
#6

New implementation tracks:

• Authority plane: Implement canonical delegated capabilities and revocation checkpoints for remote control fractalmind-protocol#17
• envd command/verifier, runtime adapter, relay decentralization, desktop session scope, and legacy retirement: Define canonical NodeCommand / NodeEvent envelopes and target-side authorization fractalmind-envd#64 through Retire the legacy TypeScript gateway and standalone sponsor-service after parity fractalmind-envd#68
• Agent Console signed intents: https://github.com/fractalmind-ai/agent-console/issues/17
• fractalbot authority-path migration: Route privileged agent lifecycle actions through envd signed intents fractalbot#365
• Local runtime/availability adapters: Expose a stable local JSON runtime adapter and canonical availability state agent-manager-skill#162 and Migrate agent-calendar to an agent-manager-backed compatibility facade agent-calendar-skill#1
• Skill distribution policy: Define canonical source and mirror/archive policy for standalone skill repositories skills#10
• Private centralized edition decision: https://github.com/fractalmind-ai/fractalmind-gateway/issues/1
• Public architecture documentation: Document the three-plane architecture and component classification fractalmind-ai.github.io#21

Existing protocol #11-#14 and envd #34-#39 are retained as dependencies instead of being duplicated. The tracker enforces Phase 0 -> Phase 1 -> Phase 2 sequencing and parity/rollback evidence before legacy removal.

[ofekron]

Maintainer disclosure: I build Better Agent, a local workspace supervising native Claude, Codex, and Gemini agents with scoped approvals and restart recovery.

The three-plane split is clear. I would make the capability object action-specific rather than treating terminal or control as broad powers.

A minimal capability could bind:

• issuer, delegate, and delegation chain;
• organization/node/agent target;
• action class and resolved resource scope;
• session/attempt audience;
• not-before, expiry, nonce domain, and capability generation;
• maximum uses and/or budget reservation;
• whether subdelegation is allowed and its depth/attenuation rules;
• required revocation freshness class;
• evidence/receipt destination;
• policy version and key ID.

Initial scopes should avoid overlap:

• view_status
• read_logs
• read_files with path roots
• write_files with path roots
• terminal_exec with command/argument policy
• desktop_view
• desktop_control
• lifecycle_start/stop/restart
• deploy or publish as separate high-risk actions

A generic shell or control scope is too broad to be the default composition primitive.

For freshness, I would classify actions:

• cached checkpoint allowed: status and already-authorized read-only session views with no new secret release;
• short freshness required: new log/file reads, because sensitivity may change;
• authoritative fresh state required: terminal execution, writes, lifecycle mutation, credential access, desktop control, delegation, deploy/publish.

If freshness cannot be established, preserve the existing low-risk session only within its exact scope and deadline; do not allow new authority. The UI should visibly show degraded/uncertain authority.

Maximum-use budgets need reservation semantics for concurrency. Two peers must not each observe one remaining use and both execute. The target verifier should atomically consume or reserve a use under a capability/attempt identity, with an idempotency key so retries do not double-spend. Subdelegation can only attenuate scope, expiry, uses, and budget.

For private session evidence, anchor commitments rather than raw logs:

• capability and attempt IDs;
• admitted node/runtime identity;
• command/action class and redacted target summary;
• request/result digests;
• approval/policy reference;
• start/terminal/uncertain state;
• encrypted off-chain evidence locator;
• redaction profile and retention policy.

A signed result proves what envd reported, not necessarily that an external side effect occurred correctly. Keep application verification or independently observed outcome as a separate evidence relation.

Before retiring coordinator authority, test relay compromise, stale revocation state, duplicate delivery, crash after side effect before acknowledgement, and restart with uncertain outcome. None should mint authority or project false success.

License note: Better Agent is source-available and free for non-commercial use; commercial use requires separate permission.