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

[AUTO-DOCS-2] docs(milestone): Add v3.8.0 Server Implementation and v3.9.0 documentation #10010

Closed
HAL9000 wants to merge 1 commits from docs/auto-docs-2-v3.8.0-v3.9.0-documentation into master
pull from: docs/auto-docs-2-v3.8.0-v3.9.0-documentation
merge into: cleveragents:master
Conversation 6 Commits 1 Files Changed 4
+571
4 changed files with 571 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/milestones/index.md
+47
View File
@@ -0,0 +1,47 @@
# Milestones
This section documents the major milestones in the CleverAgents project timeline.
## Current Milestones
### [v3.8.0 — M9: Server Implementation](v3.8.0.md)
v3.8.0 delivers the **CleverAgents Server** — a production-ready, multi-user deployment mode
that enables teams to share entity definitions, execute plans on shared infrastructure, and
collaborate across devices.
**Status**: In Progress (Day 104 — 2026-04-14: 26.6% complete, 135/508 story points)
Key features:
- A2A Protocol (JSON-RPC 2.0) as the sole client-facing interface
- FastAPI server with multi-user support
- PostgreSQL backend for persistence
- LangGraph Platform integration for remote actor execution
- Docker and Kubernetes deployment
[Read the full v3.8.0 documentation →](v3.8.0.md)
### [v3.9.0 — Documentation and Feature Updates](v3.9.0.md)
v3.9.0 is a documentation and feature update release that follows the v3.8.0 Server
Implementation milestone. It consolidates documentation across all prior milestones,
adds missing API reference pages, and delivers targeted feature improvements.
**Status**: In Progress (Day 104 — 2026-04-14: 7.0% complete, 4/57 story points)
Key updates:
- Comprehensive milestone documentation
- Updated API reference pages
- Server health and diagnostics commands
- Entity sync conflict resolution
- Namespace ACL management
[Read the full v3.9.0 documentation →](v3.9.0.md)
---
## Related Documentation
- [Implementation Timeline](../timeline.md) — Full project timeline and milestone status
- [Architecture](../architecture.md) — System architecture overview
- [Architecture Decision Records (ADRs)](../adr/index.md) — Design decisions and rationale
docs/milestones/v3.8.0.md
+385
View File
@@ -0,0 +1,385 @@
# v3.8.0 — M9: Server Implementation
**Release**: v3.8.0
**Milestone**: M9 — Server Implementation
**Status**: In Progress (Day 104 — 2026-04-14: 26.6% complete, 135/508 story points)
**Target**: v3.8.0
---
## Overview
v3.8.0 delivers the **CleverAgents Server** — a production-ready, multi-user deployment mode
that enables teams to share entity definitions, execute plans on shared infrastructure, and
collaborate across devices. This milestone implements the full server stack defined in
[ADR-047](../adr/ADR-047-acp-standard-adoption.md) and
[ADR-048](../adr/ADR-048-server-application-architecture.md).
The server exposes a single **A2A JSON-RPC 2.0** endpoint as its sole client-facing interface.
All communication — agent interactions and platform operations alike — flows through this
endpoint. There is no REST API, no GraphQL, no separate admin surface.
---
## Key Features
### A2A Protocol (JSON-RPC 2.0)
CleverAgents adopts the **Agent-to-Agent (A2A) Protocol** ([a2a-protocol.org](https://a2a-protocol.org))
as the sole communication standard for all client-server interaction. The A2A standard is
governed by the Linux Foundation (Apache 2.0) and provides:
- **JSON-RPC 2.0 wire format** for all messages
- **Agent Cards** (`/.well-known/agent.json`) for dynamic capability discovery
- **Standard operations**: `message/send`, `message/stream`, `tasks/get`, `tasks/list`,
`tasks/cancel`, `tasks/subscribe`, `pushNotificationConfig/*`, `getExtendedAgentCard`
- **SSE streaming** for real-time task status and artifact updates
- **Task lifecycle states**: `submitted` to `working` to `input-required` to `completed` /
`failed` / `canceled` / `rejected`
- **CleverAgents extension methods** (`_cleveragents/` prefix) for platform-specific
operations (plan lifecycle, registry CRUD, entity sync, namespace management)
See [ADR-047](../adr/ADR-047-acp-standard-adoption.md) for the full protocol specification.
### Transport Modes
The system supports three transport configurations:
**Local Mode (stdio)**
The client spawns the agent as a subprocess. A2A JSON-RPC messages flow over
stdin/stdout. Platform operations are resolved in-process by `A2aLocalFacade`.
No network, no authentication required.
```
Client Process --stdio--> Agent Subprocess (A2A server)
|
+-- A2aLocalFacade (platform ops in-process)
+-- Actor Graph (LangGraph, local execution)
```
**Server Mode (HTTP)**
The CLI operates as a thin client. All communication flows through the A2A
HTTP endpoint. Actor graphs execute on LangGraph Platform via RemoteGraph.
```
Client --HTTP--> CleverAgents A2A Server
|
+-- Standard A2A --> SessionWorkflow + LangGraph Platform
+-- Extension methods --> PlanService, RegistryServices, SyncService
```
**External A2A Agent**
When an agent is hosted on an external A2A-compatible server, the client sends
standard A2A operations to that server and `_cleveragents/` extension methods
to the CleverAgents server.
```
Client --HTTP--> External A2A Server (agent interactions)
--HTTP--> CleverAgents A2A Server (extension methods only)
```
### FastAPI Server
The server Presentation layer is implemented using **FastAPI** with the A2A Python SDK's
server-side connection handler. Key characteristics:
- Single A2A JSON-RPC 2.0 endpoint — no REST routes
- Agent Card served at `/.well-known/agent.json`
- SSE streaming for task status and artifact updates
- Multi-turn interaction support via `input-required` task state
### Authentication
Authentication uses standard HTTP security schemes declared in the Agent Card:
1. Client discovers the Agent Card at `/.well-known/agent.json`
2. Agent Card's `securitySchemes` declares supported auth mechanisms (OAuth2, API key, HTTP bearer)
3. Client authenticates using the declared mechanism (e.g., `Authorization: Bearer <token>`)
4. All subsequent requests include the authentication credentials
5. The `A2A-Version` header communicates the protocol version
Local mode (stdio transport) bypasses authentication — the agent subprocess runs with the
user's local permissions.
### Multi-Device Support
Server mode enables multi-device collaboration:
- **Shared namespaces**: `<username>/` and `<orgname>/` namespaces resolve against the server
- **Entity sync**: `_cleveragents/sync/*` extension methods synchronize entity definitions
between client and server
- **Auto-sync**: Controlled by `server.sync.auto` (default: `true`), syncing on startup and
at `server.sync.interval` (default: 300 seconds)
- **Namespace isolation**: Users can only access entities in namespaces they have been granted
access to; the `local/` namespace is never accessible via server
### PostgreSQL Backend
Server mode uses **PostgreSQL** for multi-user persistence:
| Component | Technology |
|-----------|-----------|
| Database | PostgreSQL >= 15 via SQLAlchemy |
| Migrations | Alembic |
| Session store | PostgreSQL (multi-user, namespace-isolated) |
| Plan store | PostgreSQL (plan lifecycle, decision trees, artifacts) |
The SQLAlchemy repository implementations are shared between client (SQLite) and server
(PostgreSQL) where the schema is identical. Server-specific tables (authentication, namespace
ACLs, user management) are additive.
### LangGraph Platform Integration
Actor graphs (StateGraphs defined in YAML) are deployed to **LangGraph Platform** as separate
deployments. The server invokes them via **RemoteGraph**:
- Different actors for different plan phases (strategy, execution, estimation) each deploy as
separate RemoteGraphs
- `SessionWorkflow` orchestrates them identically to local actor graphs, but through the
RemoteGraph interface
- LangGraph Platform provides production-grade graph execution with built-in scaling,
persistence, and monitoring
### Docker and Kubernetes Deployment
The server is packaged as a Docker container and deployed to Kubernetes via Helm:
| Component | Technology |
|-----------|-----------|
| Container | Docker |
| Orchestration | Kubernetes |
| Configuration | Helm chart (`k8s/`) |
| Ingress | Kubernetes Ingress (TLS termination) |
| Database | PostgreSQL (external, managed or self-hosted) |
| LangGraph Platform | External service (managed or self-hosted) |
---
## Architecture
The server follows the same four-layer architecture as the client (ADR-001), sharing the
Domain and Application layers and providing its own Infrastructure and Presentation layers:
| Layer | Client | Server | Shared? |
|-------|--------|--------|---------|
| **Domain** | Business rules, domain models, domain events | Same | Yes |
| **Application** | Service facades, workflows, event bus | Same | Yes |
| **Infrastructure** | SQLite, local sandbox, `A2aLocalFacade` | PostgreSQL, LangGraph RemoteGraph, A2A SDK server | No |
| **Presentation** | CLI (Typer), TUI (Textual), IDE plugin | A2A JSON-RPC 2.0 endpoint (FastAPI) | No |
The shared Domain and Application layers are consumed as a Python package dependency,
ensuring zero behavioral drift between local and server modes.
### Wire Format Examples
**Sending a message (JSON-RPC 2.0 request):**
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "message/send",
"params": {
"message": {
"role": "user",
"parts": [{ "text": "Refactor the auth module to use dependency injection" }]
}
}
}
```
**Task created (response):**
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"id": "task_01HXRCF1...",
"status": { "state": "working" }
}
}
```
**Extension method (platform operation):**
```json
{
"jsonrpc": "2.0",
"id": 42,
"method": "_cleveragents/plan/status",
"params": { "plan_id": "01HXRCF1..." }
}
```
**Error response:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32001,
"message": "Plan not found",
"data": { "plan_id": "01HXRCF1..." }
}
}
```
---
## CLI Commands
### Server Configuration
```bash
# Configure server connection
ca config set server.url https://your-server.example.com
ca config set server.token <your-token>
# Enable/disable auto-sync
ca config set server.sync.auto true
ca config set server.sync.interval 300
```
### Entity Sync
```bash
# Pull server namespace entities to local cache
ca sync pull
# Push local entity definitions to a server namespace
ca sync push
# Compare local and server entity versions
ca sync status
```
### Namespace Management
```bash
# List available namespaces (local + server)
ca namespace list
# Use a server namespace as default
ca config set core.namespace freemo/
```
---
## Quick Start
### Local Mode (No Server Required)
Local mode works fully offline with zero configuration:
```bash
# Install CleverAgents
pip install cleveragents
# Start a session (local mode, A2A over stdio)
ca session start
# Execute a plan locally
ca plan run "Refactor the auth module"
```
### Server Mode
**Step 1 — Deploy the server** using the Helm chart:
```bash
helm install cleveragents k8s/ \
--set database.url=postgresql://user:pass@host/db \
--set langgraph.url=https://your-langgraph-platform.example.com
```
**Step 2 — Configure the CLI** to connect to the server:
```bash
ca config set server.url https://your-server.example.com
ca config set server.token <your-token>
```
**Step 3 — Verify the connection** by fetching the Agent Card:
```bash
ca server status
```
**Step 4 — Sync entities** from the server:
```bash
ca sync pull
```
**Step 5 — Execute a plan on the server**:
```bash
ca plan run "Refactor the auth module" --server
```
---
## Error Code Reference
A2A uses JSON-RPC 2.0 integer error codes:
| Code | Meaning | Domain Exception |
|------|---------|-----------------|
| `-32700` | Parse error (malformed JSON) | — |
| `-32600` | Invalid request | — |
| `-32601` | Method not found | `A2aOperationNotFoundError` |
| `-32602` | Invalid params | `ValidationError` |
| `-32603` | Internal error | Any unhandled `Exception` |
| `-32001` | Entity not found | `ResourceNotFoundError` |
| `-32002` | Authentication required | `AuthenticationError` |
| `-32003` | Authorization forbidden | `AuthorizationError` |
| `-32004` | Invalid state | `BusinessRuleViolation` |
| `-32005` | Already exists | `DuplicateEntityError` |
| `-32006` | Budget exceeded | `BudgetExceededError` |
| `-32007` | Version mismatch | `A2aVersionMismatchError` |
| `-32008` | Plan error | `PlanError` |
---
## Related ADRs
| ADR | Title | Relevance |
|-----|-------|-----------|
| [ADR-023](../adr/ADR-023-server-mode.md) | Server Mode | Defines local vs. server deployment modes |
| [ADR-026](../adr/ADR-026-agent-client-protocol.md) | Agent-to-Agent Protocol (A2A) | Original A2A boundary role definition |
| [ADR-047](../adr/ADR-047-acp-standard-adoption.md) | A2A Standard Adoption | Adopts external A2A standard, JSON-RPC 2.0 wire format |
| [ADR-048](../adr/ADR-048-server-application-architecture.md) | Server Application Architecture | Concrete server architecture (FastAPI, LangGraph Platform, PostgreSQL) |
| [ADR-022](../adr/ADR-022-langchain-langgraph-integration.md) | LangChain/LangGraph Integration | LangGraph Platform as remote actor execution backend |
| [ADR-019](../adr/ADR-019-storage-and-persistence.md) | Storage and Persistence | PostgreSQL for server-mode persistence |
---
## Technology Stack
| Component | Version | Purpose |
|-----------|---------|---------|
| Python | >= 3.13 | Runtime |
| A2A Python SDK (`a2a-sdk`) | Latest | A2A JSON-RPC 2.0 server implementation |
| FastAPI | Latest | HTTP server framework |
| LangGraph Platform | Latest | Remote actor graph execution |
| PostgreSQL | >= 15 | Multi-user persistence |
| SQLAlchemy | >= 2.0 | ORM (shared with client) |
| Alembic | >= 1.13 | Database migrations |
| structlog | >= 24.1 | Structured logging |
| Redis | >= 7.0 (optional) | Caching, session affinity for multi-instance |
| Docker | Latest | Container packaging |
| Helm | >= 3.0 | Kubernetes deployment |
---
*See also: [v3.9.0](v3.9.0.md) — Documentation and feature updates following this milestone.*
---
**Automated by CleverAgents Bot**
Supervisor: Documentation Pool | Agent: documentation-pool-supervisor
Worker: [AUTO-DOCS-2]
docs/milestones/v3.9.0.md
+136
View File
@@ -0,0 +1,136 @@
# v3.9.0 — Documentation and Feature Updates
**Release**: v3.9.0
**Status**: In Progress (Day 104 — 2026-04-14: 7.0% complete, 4/57 story points)
**Target**: v3.9.0
---
## Overview
v3.9.0 is a documentation and feature update release that follows the v3.8.0 Server
Implementation milestone. It consolidates documentation across all prior milestones,
adds missing API reference pages, and delivers targeted feature improvements identified
during the v3.8.0 implementation cycle.
As of Day 104 (2026-04-14), v3.9.0 has 57 open issues (scope expanded from 17 to 57)
with 4 closed. The milestone is actively receiving new issues as the v3.8.0 implementation
surfaces documentation gaps and feature requests.
---
## Scope
### Documentation Updates
v3.9.0 addresses documentation gaps across the entire CleverAgents documentation surface:
- **Milestone documentation**: Comprehensive guides for v3.8.0 (M9: Server Implementation)
and all prior milestones
- **API reference**: Updated API reference pages for new modules introduced in v3.8.0
(A2A protocol, server application, authentication)
- **Architecture documentation**: Updated architecture overview reflecting the server
deployment mode and A2A protocol adoption
- **ADR cross-references**: Ensuring all ADRs (ADR-047, ADR-048) are properly linked
from relevant documentation pages
- **Quick start guides**: Updated quick start guides for both local and server modes
- **FAQ updates**: New FAQ entries for common server deployment questions
### Feature Updates
Feature improvements targeted for v3.9.0 include:
- **Server health commands**: `ca server status` and `ca server ping` for connection
diagnostics
- **Sync conflict resolution UI**: Interactive conflict resolution for entity sync
operations (`ca sync pull --interactive`)
- **Agent Card inspection**: `ca server card` command to display the server's Agent Card
in human-readable format
- **Token management**: `ca server token` commands for managing authentication tokens
- **Namespace ACL management**: `ca namespace acl` commands for managing namespace
access control lists
---
## Documentation Standards
All documentation in v3.9.0 follows the project's documentation standards:
- **Continuous documentation** — updated alongside code, not after the fact
- **Single documentation surface** — one canonical location per doc type
- **Traceability** — logical references to ADRs and specifications, not line numbers
- **MkDocs-compatible** — all files are valid MkDocs Markdown with proper navigation
### Documentation Structure
```
docs/
milestones/ # Per-milestone documentation (NEW in v3.9.0)
v3.8.0.md # M9: Server Implementation
v3.9.0.md # Documentation and feature updates (this file)
adr/ # Architecture Decision Records (ADR-001 through ADR-048)
api/ # API reference (auto-generated + hand-written)
development/ # Developer guides
modules/ # Module-level usage guides
reference/ # Comprehensive reference documentation
```
---
## Key Changes from v3.8.0
| Area | Change |
|------|--------|
| Documentation | Milestone docs for v3.8.0 and v3.9.0 added to `docs/milestones/` |
| Navigation | `mkdocs.yml` updated with Milestones section |
| API Reference | New pages for A2A protocol, server application, authentication modules |
| CLI | `ca server status`, `ca server ping`, `ca server card` commands |
| CLI | `ca server token` token management commands |
| CLI | `ca namespace acl` namespace ACL management commands |
| Sync | Interactive conflict resolution for `ca sync pull` |
---
## Migration Notes
v3.9.0 is backward-compatible with v3.8.0. No breaking changes are introduced.
If you are upgrading from a pre-v3.8.0 release:
1. Review the [v3.8.0 migration guide](v3.8.0.md#quick-start) for server setup instructions
2. Update your CLI to v3.9.0: `pip install --upgrade cleveragents`
3. Run `ca sync pull` to fetch the latest entity definitions from your server
---
## Related Documentation
- [v3.8.0 — M9: Server Implementation](v3.8.0.md) — The milestone this release documents
- [Architecture](../architecture.md) — System architecture overview
- [ADR-047 — A2A Standard Adoption](../adr/ADR-047-acp-standard-adoption.md)
- [ADR-048 — Server Application Architecture](../adr/ADR-048-server-application-architecture.md)
- [Implementation Timeline](../timeline.md) — Full project timeline and milestone status
- [FAQ](../faq.md) — Frequently asked questions
---
## Progress Tracking
v3.9.0 progress is tracked in the Forgejo milestone. As of Day 104:
- **Total issues**: 57 (scope expanded from 17)
- **Closed**: 4 (7.0%)
- **Open**: 53 (93.0%)
- **Active session**: Session 4 (issue #4799, 32 workers)
The milestone scope is actively expanding as the v3.8.0 implementation surfaces new
documentation requirements and feature requests.
---
*See also: [v3.8.0](v3.8.0.md) — The server implementation milestone this release documents.*
---
**Automated by CleverAgents Bot**
Supervisor: Documentation Pool | Agent: documentation-pool-supervisor
Worker: [AUTO-DOCS-2]
mkdocs.yml
+3
View File
@@ -42,6 +42,9 @@ nav:
- Automation Tracking: development/automation-tracking.md
- Custom Sandbox Strategy: development/custom_sandbox_strategy.md
- Documentation Writer: development/docs-writer.md
- Milestones:
- v3.8.0 Server Implementation: milestones/v3.8.0.md
- v3.9.0 Documentation Updates: milestones/v3.9.0.md
- Implementation Timeline: timeline.md
- FAQ: faq.md
- Reference: reference/