cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

docs: clarified the fact that the server will not be the same executable

Browse Source
This commit is contained in:
Jeffrey Phillips Freeman
2026-02-06 16:43:01 -05:00
parent 4e5144e225
commit 2b4eb845bc
1 changed files with 100 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files
implementation_plan.md
+100 -97
View File
@@ -34,7 +34,7 @@
CleverAgents is your **command center for AI agents**—a unified platform for orchestrating any task you want agents to accomplish, from developing large software projects to writing comprehensive technical papers, administering databases, managing cloud infrastructure, or any complex multi-step workflow. The core value proposition is enabling **long-running, complex, large-scale tasks to execute autonomously with minimal human intervention**, making it ideal for building entire software systems, producing extensive documentation, or managing sophisticated operations largely hands-off.
In **server mode**, CleverAgents becomes a collaborative hub where teams can share resources—prompts, actors, actions, and projects—while executing plans in the cloud. This enables a consistent experience across all your devices: start a complex task on your laptop, check progress from your phone, and review results from any machine.
When connected to a **CleverAgents server** (developed independently), the client becomes a gateway to a collaborative hub where teams can share resources—prompts, actors, actions, and projects—while executing plans on the server. This enables a consistent experience across all your devices: start a complex task on your laptop, check progress from your phone, and review results from any machine. Note: The server is a separate project; this implementation plan covers the client only.
While CleverAgents leverages LangGraph and LangChain for the underlying LLM runtime primitives (tool calling, graphs, routing), its value lies in what it builds on top:
@@ -66,7 +66,7 @@ While CleverAgents leverages LangGraph and LangChain for the underlying LLM runt
- Ship a Python-based, feature-complete application named **CleverAgents** implementing the four-phase plan lifecycle with actors, projects, resources, and sandbox-based execution.
- Implement functionality using Pythonic architecture: dependency inversion, strategy, adapter, observer, state, builder, factory, template method, event sourcing, and decorator patterns where appropriate.
- Build a unified Python executable (`agents`) that supports both in-process single-user mode and `agents serve --port <port>` multi-user deployments without cloud dependencies.
- Build a unified Python executable (`agents`) that operates as a **client-only application**, supporting stand-alone local-only mode or connecting to an independently developed server for multi-user deployments.
- Enforce fail-fast error handling, rich logging, and comprehensive type coverage with docstrings and runtime validation aligned to Python best practices.
- Provide a pluggable ORM abstraction supporting heavy (PostgreSQL/MySQL) and lightweight (SQLite/DuckDB/in-memory) backends, with zero-code configuration switches.
- Generate fresh documentation via Docusaurus integrated within the `docs/` directory of the CleverAgents project.
@@ -336,7 +336,7 @@ The following work from the previous implementation has been completed and will
| **M4: Decision Tree** | +21 days | Decision recording during Strategize, basic correction |
| **M5: Multi-Project & Subplans** | +25 days | Subplan spawning, parallel execution |
| **M6: Large Project Autonomy** | +30 days | Handle 10K+ file projects, decision correction, deep subplan hierarchies (LOCAL MODE ONLY) |
| **M7: Server Mode** | +35+ days | `agents serve` with remote project support (DEFERRED from original Day 30) |
| **M7: Server Connectivity** | +35+ days | Client-server communication for remote project support (server developed independently) |
| **M8: Full Feature Set** | +40 days | All spec features complete |
### Critical Path to 7-Day MVP (Source Code Only)
@@ -567,25 +567,25 @@ Execute all required tests through the appropriate `nox` sessions—never call `
| **M4: Decisions** | Day 21 | Decision recording, tree viewing, correction mechanism | `agents plan tree` shows decisions → `agents plan explain` works → `agents plan correct --mode=revert` re-executes from correction point |
| **M5: Subplans** | Day 25 | Hierarchical subplans with parallel execution and merging | Parent plan spawns 5+ subplans → Parallel execution → Three-way merge → Validation passes |
| **M6: Large Projects** | Day 30 | Handle 10,000+ file projects, autonomous language porting | Can port a 500-file Python module to TypeScript using hierarchical decomposition with decision correction |
| **Server Mode** | Beyond Day 30 | Stubs and interfaces in place during Days 1-30; full implementation deferred | Server endpoints stubbed, remote resource abstraction defined, but local execution only |
| **Server Connectivity** | Beyond Day 30 | Client interfaces for server communication; server developed independently | Client-to-server API abstractions defined, but local execution only; no server implementation in this project |
### CRITICAL: Server Mode Deferral Policy
### CRITICAL: Server Connectivity Policy
**Server mode is explicitly deferred beyond Day 30.** The initial 30-day timeline focuses exclusively on LOCAL MODE operation. During Days 1-30, developers should:
**The CleverAgents client does NOT include server functionality.** The server is a separate project that will be developed independently. This implementation plan covers the **client only**. During Days 1-30, developers should:
1. **Design with Server Mode in Mind**: Ensure abstractions support future network-accessible deployment
2. **Create Interface Stubs Only**: Define `ServerAPI`, `RemoteExecutionService`, `AuthenticationService` interfaces but implement as stubs that raise `NotImplementedError("Server mode not yet implemented")`
3. **No Server Implementation Work**: Do NOT spend time on actual server implementation, authentication, multi-user, or remote execution
1. **Design with Server Connectivity in Mind**: Ensure abstractions support future connection to an external server
2. **Create Client Interface Stubs Only**: Define `ServerClientAPI`, `RemoteExecutionClient`, `AuthenticationClient` interfaces but implement as stubs that raise `NotImplementedError("Server connectivity not yet implemented")`
3. **No Server Implementation Work**: The server is NOT part of this project—do NOT spend time on server implementation, only on client-side connection interfaces
4. **Focus on Core Functionality**: All effort goes to plan lifecycle, actors, skills, sandboxing, decisions, and subplans
The following Section 8 (Server Mode) items are explicitly **OUT OF SCOPE** for the 30-day deadline:
- FastAPI server implementation
- WebSocket streaming
- Remote project execution
- Multi-user authentication
- API endpoints (beyond stubs)
The following Section 8 (Server Connectivity) items are explicitly **OUT OF SCOPE** for the 30-day deadline:
- Client-to-server API integration
- WebSocket streaming to server
- Remote project execution via server
- Server authentication flow (client-side)
- Server API client implementation (beyond stubs)
**Rationale**: Getting a minimally usable application working for single-user local operation in 7 days, and large project autonomy in 30 days, is more valuable than a half-working server mode.
**Rationale**: Getting a minimally usable application working for single-user local operation in 7 days, and large project autonomy in 30 days, is more valuable than incomplete server connectivity. The server will be developed as a separate project.
### Critical Path Analysis
@@ -7663,92 +7663,92 @@ TESTING [Rui - Continuous]: Write tests BEFORE implementation
---
### Section 8: Server Mode [DEFERRED - Beyond Day 30]
### Section 8: Server Connectivity [DEFERRED - Beyond Day 30]
**Target: Post-30-day work (NOT part of initial 30-day timeline)**
> **IMPORTANT**: This entire section is **DEFERRED** beyond the 30-day deadline per the Server Mode Deferral Policy (see above). During Days 1-30, only **stub interfaces** should be created. Full implementation begins after Day 30.
> **IMPORTANT**: This section covers **client-side interfaces for connecting to an external server**. The server itself is a **separate project** that will be developed independently. This client will NOT include server functionality—it operates purely as a client that can either run in stand-alone local-only mode or connect to a separately deployed CleverAgents server.
#### Stage F0: Server Interface Stubs [Day 28-29 - REQUIRED DURING MVP]
#### Stage F0: Server Client Interface Stubs [Day 28-29 - REQUIRED DURING MVP]
These stubs ensure the architecture supports future server mode without implementing it:
These stubs ensure the client architecture supports future server connectivity without implementing it:
- [ ] **Stage F0: Server Interface Stubs** (Day 28-29) **[Luis - Required]**
- [ ] **F0.1** [Luis] Create `src/cleveragents/interfaces/server_api.py` with protocol stubs:
- [ ] `class ServerAPI(Protocol):` with all method signatures
- [ ] `async def start_server(host: str, port: int) -> None: raise NotImplementedError("Server mode not yet implemented")`
- [ ] `async def stop_server() -> None: raise NotImplementedError(...)`
- [ ] `async def create_action_remote(...) -> Action: raise NotImplementedError(...)`
- [ ] `async def execute_plan_remote(...) -> Plan: raise NotImplementedError(...)`
- [ ] Commit: "feat(interfaces): add ServerAPI protocol stub"
- [ ] **F0.2** [Luis] Create `src/cleveragents/interfaces/remote_execution.py`:
- [ ] `class RemoteExecutionService(Protocol):` - protocol for remote plan execution
- [ ] **Stage F0: Server Client Interface Stubs** (Day 28-29) **[Luis - Required]**
- [ ] **F0.1** [Luis] Create `src/cleveragents/interfaces/server_client.py` with protocol stubs:
- [ ] `class ServerClient(Protocol):` with all method signatures for client-to-server communication
- [ ] `async def connect(server_url: str) -> None: raise NotImplementedError("Server connectivity not yet implemented")`
- [ ] `async def disconnect() -> None: raise NotImplementedError(...)`
- [ ] `async def sync_action(action: Action) -> Action: raise NotImplementedError(...)`
- [ ] `async def request_remote_execution(plan_id: str) -> str: raise NotImplementedError(...)`
- [ ] Commit: "feat(interfaces): add ServerClient protocol stub"
- [ ] **F0.2** [Luis] Create `src/cleveragents/interfaces/remote_execution_client.py`:
- [ ] `class RemoteExecutionClient(Protocol):` - protocol for requesting remote plan execution from server
- [ ] `async def submit_plan(plan_id: str, server_url: str) -> str: raise NotImplementedError(...)`
- [ ] `async def poll_status(execution_id: str) -> ExecutionStatus: raise NotImplementedError(...)`
- [ ] `async def fetch_results(execution_id: str) -> ExecutionResult: raise NotImplementedError(...)`
- [ ] Commit: "feat(interfaces): add RemoteExecutionService protocol stub"
- [ ] **F0.3** [Luis] Create `src/cleveragents/interfaces/authentication.py`:
- [ ] `class AuthenticationService(Protocol):` - protocol for auth
- [ ] Commit: "feat(interfaces): add RemoteExecutionClient protocol stub"
- [ ] **F0.3** [Luis] Create `src/cleveragents/interfaces/auth_client.py`:
- [ ] `class AuthClient(Protocol):` - protocol for client authentication with server
- [ ] `async def authenticate(credentials: Credentials) -> AuthToken: raise NotImplementedError(...)`
- [ ] `async def validate_token(token: str) -> TokenValidation: raise NotImplementedError(...)`
- [ ] `async def refresh_token(token: str) -> AuthToken: raise NotImplementedError(...)`
- [ ] Commit: "feat(interfaces): add AuthenticationService protocol stub"
- [ ] **F0.4** [Luis] Add `agents serve` CLI command as stub:
- [ ] Add to `src/cleveragents/cli/commands/server.py`
- [ ] Command signature: `@click.command("serve") @click.option("--host", default="127.0.0.1") @click.option("--port", default=8080)`
- [ ] Implementation: `click.echo("Server mode not yet implemented. Coming soon!")`; `raise SystemExit(1)`
- [ ] Commit: "feat(cli): add serve command stub"
- [ ] Commit: "feat(interfaces): add AuthClient protocol stub"
- [ ] **F0.4** [Luis] Add `agents connect` CLI command as stub:
- [ ] Add to `src/cleveragents/cli/commands/server_client.py`
- [ ] Command signature: `@click.command("connect") @click.argument("server_url")`
- [ ] Implementation: `click.echo("Server connectivity not yet implemented. Coming soon!")`; `raise SystemExit(1)`
- [ ] Commit: "feat(cli): add connect command stub"
- [ ] **F0.5** [Rui] Write minimal tests verifying stubs raise NotImplementedError:
- [ ] Test: Calling ServerAPI methods raises NotImplementedError
- [ ] Test: `agents serve` displays "not implemented" message and exits
- [ ] Commit: "test(behave): add server stub tests"
- [ ] Test: Calling ServerClient methods raises NotImplementedError
- [ ] Test: `agents connect` displays "not implemented" message and exits
- [ ] Commit: "test(behave): add server client stub tests"
---
#### Stages F1-F4: Full Server Implementation [DEFERRED - Beyond Day 30]
#### Stages F1-F4: Server Client Implementation [DEFERRED - Beyond Day 30]
> **These stages are OUT OF SCOPE for the 30-day timeline.** Do not begin work on them until after Day 30 milestone is achieved.
> **These stages are OUT OF SCOPE for the 30-day timeline.** Do not begin work on them until after Day 30 milestone is achieved. Note: These stages implement **client-side** connectivity; the server is a separate project.
- [ ] **Stage F1: Server Infrastructure** (Post-Day 30) **[Luis]** **[DEFERRED]**
- [ ] **F1.1** [Luis] Create FastAPI server in `src/cleveragents/runtime/server.py`
- [ ] **F1.2** [Luis] Health/version endpoints
- [ ] **F1.3** [Luis] OpenAPI documentation generation
- [ ] **F1.4** [Rui] Server startup/shutdown tests
- [ ] **Stage F1: Server Client Infrastructure** (Post-Day 30) **[Luis]** **[DEFERRED]**
- [ ] **F1.1** [Luis] Create HTTP client in `src/cleveragents/infrastructure/server_client.py`
- [ ] **F1.2** [Luis] Connection health check and version negotiation
- [ ] **F1.3** [Luis] API client code generation from server OpenAPI spec
- [ ] **F1.4** [Rui] Client connection tests (with mock server)
- [ ] **Stage F2: Plan Execution API** (Post-Day 30) **[Luis]** **[DEFERRED]**
- [ ] **F2.1** [Luis] POST /actions - create action
- [ ] **F2.2** [Luis] POST /plans - use action to create plan
- [ ] **F2.3** [Luis] POST /plans/{id}/execute
- [ ] **F2.4** [Luis] POST /plans/{id}/apply
- [ ] **F2.5** [Luis] GET /plans/{id} - status
- [ ] **F2.6** [Rui] API integration tests
- [ ] **Stage F2: Plan Sync Client** (Post-Day 30) **[Luis]** **[DEFERRED]**
- [ ] **F2.1** [Luis] Sync local actions to server
- [ ] **F2.2** [Luis] Request plan creation on server
- [ ] **F2.3** [Luis] Request plan execution on server
- [ ] **F2.4** [Luis] Request plan apply on server
- [ ] **F2.5** [Luis] Fetch plan status from server
- [ ] **F2.6** [Rui] Client-side API integration tests (with mock server)
- [ ] **Stage F3: WebSocket Streaming** (Post-Day 30) **[Luis]** **[DEFERRED]**
- [ ] **F3.1** [Luis] WebSocket endpoint for plan updates
- [ ] **F3.2** [Luis] Stream phase transitions, node completions
- [ ] **F3.3** [Rui] WebSocket integration tests
- [ ] **Stage F3: WebSocket Client** (Post-Day 30) **[Luis]** **[DEFERRED]**
- [ ] **F3.1** [Luis] WebSocket client for receiving plan updates from server
- [ ] **F3.2** [Luis] Handle phase transitions, node completions from server
- [ ] **F3.3** [Rui] WebSocket client tests (with mock server)
- [ ] **Stage F4: Remote Project Execution** (Post-Day 30) **[Hamza]** **[DEFERRED]**
- [ ] **F4.1** [Hamza] Server can access remote resources
- [ ] **F4.2** [Hamza] Client sends execution requests to server
- [ ] **F4.3** [Rui] End-to-end tests for remote execution
- [ ] **Stage F4: Remote Project Support** (Post-Day 30) **[Hamza]** **[DEFERRED]**
- [ ] **F4.1** [Hamza] Client can specify remote resources for server execution
- [ ] **F4.2** [Hamza] Client sends execution requests to server for remote resources
- [ ] **F4.3** [Rui] End-to-end tests for remote execution (with mock server)
**M6 SUCCESS CRITERIA** (Post-Day 30):
- [ ] `agents serve` starts a working API server
- [ ] Plans can be created and executed via API
- [ ] Real-time updates via WebSocket
- [ ] Remote projects can be used
**M7 SUCCESS CRITERIA** (Post-Day 30):
- [ ] `agents connect <server_url>` establishes connection to an external server
- [ ] Plans can be synced and executed on a remote server
- [ ] Real-time updates received via WebSocket from server
- [ ] Remote projects can be specified and executed on server
**--- MERGE POINT 2: Day 30 - Large Project Autonomy Target (LOCAL MODE ONLY) ---**
By Day 30, the system must be able to (all in LOCAL MODE, server mode is deferred):
By Day 30, the system must be able to (all in LOCAL MODE, server connectivity is deferred):
- [ ] Handle projects with 10,000+ files using hierarchical decomposition
- [ ] Port source code from one language to another autonomously
- [ ] Use hierarchical subplans (5+ levels deep) for large tasks
- [ ] Correct decisions at any point without full re-execution
- [ ] Operate entirely in local mode (server stubs in place but not implemented)
- [ ] Operate entirely in local mode (server client stubs in place but not implemented)
**Note**: Server mode (M6 as originally defined) is deferred beyond Day 30. The new Day 30 goal focuses on autonomous large project handling in local mode.
**Note**: Server connectivity (M7 as redefined) is deferred beyond Day 30. The server is a separate project. The Day 30 goal focuses on autonomous large project handling in local mode.
---
@@ -7932,7 +7932,7 @@ This section runs in parallel throughout the project with Brent working independ
- [ ] **9.2** [Brent] Review all Projects & Resources PRs (Workstream B)
- [ ] **9.3** [Brent] Review all Actors & Skills PRs (Workstream C)
- [ ] **9.4** [Brent] Review Decision Tree PRs
- [ ] **9.5** [Brent] Review Server Mode PRs
- [ ] **9.5** [Brent] Review Server Connectivity PRs (client-side only)
- [ ] **Stage 10: Linting & Type Checking Enforcement** **[Brent - Continuous]**
- [ ] **10.1** [Brent] Run `nox -s lint` after each PR merge, fix any issues
@@ -8482,11 +8482,11 @@ This section runs in parallel throughout the project with Brent working independ
The following items are deferred or no longer applicable:
- [ ] **Deferred: REPL Mode** - Focus on CLI first, REPL is optional enhancement
- [ ] **Deferred: Auth/Team Commands** - Requires server infrastructure
- [ ] **Deferred: Auth/Team Commands** - Requires server connectivity (server is a separate project)
- [ ] **Deferred: TUI/Web Interface** - After CLI is complete
- [ ] **Deferred: Database Resources** - After source code resources work
- [ ] **Deferred: Cloud Infrastructure Resources** - After source code resources work
- [ ] **Deferred: Permission System** - Server mode prerequisite
- [ ] **Deferred: Permission System** - Requires server connectivity (server is a separate project)
- [ ] Namespace-level permissions (who can create/edit org actions)
- [ ] Project-level permissions (who can modify resources, apply changes)
- [ ] Plan-level permissions (can this plan write, require approvals)
@@ -8549,18 +8549,18 @@ The following items are deferred or no longer applicable:
| 22-23 | F1.1-F1.8 Context Indexing | Hamza | Large codebase indexing |
| 24-25 | F2.1-F2.6 Hot/Warm/Cold Context | Jeff + Hamza | Three-tier memory |
| 26-27 | Deep Subplan Hierarchies (5+ levels) | Jeff + Luis | Autonomous decomposition |
| 28-29 | F0.1-F0.5 Server Interface Stubs + Large Project Tests | Luis + Rui | Server stubs (NOT implementation), 10K file tests |
| 30 | M6 integration testing | All | Large project autonomy verified (Server mode DEFERRED) |
| 28-29 | F0.1-F0.5 Server Client Interface Stubs + Large Project Tests | Luis + Rui | Client stubs (NOT server impl), 10K file tests |
| 30 | M6 integration testing | All | Large project autonomy verified (Server connectivity DEFERRED) |
> **Note**: Server mode (F1-F4) is DEFERRED beyond Day 30. Days 26-29 focus on server **stubs only** and large project testing.
> **Note**: Server connectivity (F1-F4) is DEFERRED beyond Day 30. Days 26-29 focus on client **stubs only** and large project testing. The server is a separate project.
### Week 5 (Days 31-35) - M7 Target (Server Mode - Previously Deferred)
### Week 5 (Days 31-35) - M7 Target (Server Connectivity - Client Side Only)
| Day | Focus | Owner | Deliverable |
|-----|-------|-------|-------------|
| 31-32 | F1.1-F1.4 FastAPI Server Infrastructure | Luis | Basic server running |
| 33 | F2.1-F2.6 Plan Execution API | Luis | REST endpoints working |
| 34 | F3.1-F3.3 WebSocket Streaming | Luis | Real-time updates |
| 35 | F4.1-F4.3 Remote Project Execution | Hamza | Remote projects accessible |
| 31-32 | F1.1-F1.4 Server Client Infrastructure | Luis | HTTP client for server communication |
| 33 | F2.1-F2.6 Plan Sync Client | Luis | Client can sync plans to server |
| 34 | F3.1-F3.3 WebSocket Client | Luis | Client receives real-time updates |
| 35 | F4.1-F4.3 Remote Project Support | Hamza | Client can request server execution |
### Week 6 (Days 36-40) - M8 Target (Full Feature Set + Polish)
| Day | Focus | Owner | Deliverable |
@@ -8981,23 +8981,26 @@ DAY 30: M6 TARGET ⊕
---
## SERVER MODE DEFERRAL NOTICE
## SERVER CONNECTIVITY DEFERRAL NOTICE
**Server mode (WORKSTREAM F) is deferred beyond the 30-day timeline.**
**Server connectivity (WORKSTREAM F) is deferred beyond the 30-day timeline. The server is a separate project—this implementation covers the client only.**
During Days 1-30, the following stub infrastructure should be created:
- [ ] FastAPI server entry point (`agents serve` command)
- [ ] Health check endpoint that returns version info
- [ ] Abstract interfaces for remote execution
The CleverAgents executable (`agents`) is purely a **client application** that can:
1. Run in stand-alone local-only mode (no server required)
2. Connect to an independently developed CleverAgents server for multi-user/collaborative features
During Days 1-30, the following client stub infrastructure should be created:
- [ ] Server client connection command (`agents connect <server_url>` - stub)
- [ ] Abstract interfaces for client-to-server communication
- [ ] Resource abstraction that can detect local vs remote resources
- [ ] Placeholder API routes that return "Not implemented in local mode"
- [ ] Placeholder client methods that return "Server connectivity not yet implemented"
**What is NOT needed by Day 30:**
- Full REST API implementation
- WebSocket streaming
- Remote plan execution
- Multi-user authentication
- Permission system
- Server-side database storage
- Server implementation (the server is a separate project)
- Full client-server API implementation
- WebSocket client implementation
- Remote plan execution requests
- Authentication flow with server
- Permission system integration
The code should be structured so that adding server mode later is straightforward, but no functional server code is required for the 30-day milestone.
The client code should be structured so that adding server connectivity later is straightforward, but no functional server communication code is required for the 30-day milestone. The server will be developed as a separate project.