From ec42bf33d1fb42075c4144cf775b38428f806dae Mon Sep 17 00:00:00 2001 From: CleverThis Date: Fri, 10 Apr 2026 05:57:21 +0000 Subject: [PATCH] docs(spec): add v3.8.0 Server Implementation milestone plan ISSUES CLOSED: #7229 --- docs/specification.md | 68 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 60 insertions(+), 8 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index dbe7bd381..d154f32ce 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -46740,17 +46740,18 @@ The following table shows which Protocol each pipeline slot implements and what ## Milestone Plan -This section defines the ordered milestone plan for CleverAgents v3.x, mapping architectural features to verifiable deliverables. Each milestone builds on the previous and is independently testable. Milestones v3.0.0 and v3.1.0 are **complete**. This plan covers v3.2.0 through v3.7.0 — the production-ready target. +This section defines the ordered milestone plan for CleverAgents v3.x, mapping architectural features to verifiable deliverables. Each milestone builds on the previous and is independently testable. Milestones v3.0.0 and v3.1.0 are **complete**. This plan covers v3.2.0 through v3.8.0 — the production-ready target. -!!! note "Milestone Status (as of 2026-04-08)" +!!! note "Milestone Status (as of 2026-04-10)" - **v3.0.0** ✅ CLOSED — Minimal Local Source-Code Workflow - **v3.1.0** ✅ CLOSED — Actor Compiler + Full LLM Integration - - **v3.2.0** 🔄 IN PROGRESS — Decisions + Validations + Invariants (85 open / 235 closed) - - **v3.3.0** 🔄 IN PROGRESS — Corrections + Subplans + Checkpoints (65 open / 108 closed) - - **v3.4.0** 🔄 IN PROGRESS — ACMS v1 + Context Scaling (55 open / 130 closed) - - **v3.5.0** 🔄 IN PROGRESS — Autonomy Hardening (486 open / 188 closed) - - **v3.6.0** 🔄 IN PROGRESS — Advanced Concepts & Deferred Features (162 open / 150 closed) - - **v3.7.0** 🔄 IN PROGRESS — TUI Implementation (461 open / 403 closed) + - **v3.2.0** 🔄 IN PROGRESS — Decisions + Validations + Invariants (515 open / 249 closed) + - **v3.3.0** 🔄 IN PROGRESS — Corrections + Subplans + Checkpoints (112 open / 108 closed) + - **v3.4.0** 🔄 IN PROGRESS — ACMS v1 + Context Scaling (177 open / 133 closed) + - **v3.5.0** 🔄 IN PROGRESS — Autonomy Hardening (872 open / 197 closed) + - **v3.6.0** 🔄 IN PROGRESS — Advanced Concepts & Deferred Features (242 open / 150 closed) + - **v3.7.0** 🔄 IN PROGRESS — TUI Implementation (515 open / 425 closed) + - **v3.8.0** 🔄 IN PROGRESS — Server Implementation (344 open / 131 closed) --- @@ -47009,6 +47010,57 @@ This section defines the ordered milestone plan for CleverAgents v3.x, mapping a --- +### v3.8.0 — Server Implementation + +**Goal**: Implement the CleverAgents server and all server-dependent capabilities. The server enables multi-user collaborative workflows, shared namespaces, cloud-hosted plan execution, and multi-device access. This milestone completes the A2A protocol implementation for both local (stdio) and server (HTTP) transports. + +**Spec Coverage**: [Server and Client Architecture](#server-and-client-architecture), [A2A Protocol](#agent-to-agent-protocol-a2a), [Server Mode](#server-mode), [Security Architecture](#security-architecture) + +**Key ADRs**: [ADR-047](adr/ADR-047-acp-standard-adoption.md), [ADR-048](adr/ADR-048-server-application-architecture.md), [ADR-023](adr/ADR-023-server-mode.md) + +#### Deliverables + +| # | Deliverable | Spec Reference | Verifiable Check | +|---|-------------|----------------|-----------------| +| 1 | A2A JSON-RPC 2.0 endpoint functional (`/`) with Agent Card discovery | §Server and Client Architecture — Server Presentation Layer | `curl /` returns valid Agent Card JSON; `message/send` routes to SessionWorkflow | +| 2 | A2A stdio transport: `cleveragents agent serve` spawns agent subprocess | §Server and Client Architecture — Local/Server Interchangeability | `agents plan use` in local mode routes through stdio A2A transport | +| 3 | A2A HTTP transport: `server.url` config switches client to HTTP mode | §Server and Client Architecture — Client-Side Architecture | Setting `server.url` causes all CLI commands to route through HTTP A2A | +| 4 | `_cleveragents/` extension methods routed to Application-layer services | §Server and Client Architecture — Server Presentation Layer | `_cleveragents/plan/status`, `_cleveragents/registry/*` all functional via HTTP | +| 5 | LangGraph Platform RemoteGraph integration for server-side actor execution | §Server and Client Architecture — Server Infrastructure: LangGraph Platform | Plan execution in server mode invokes actors via RemoteGraph; results stream back to client | +| 6 | PostgreSQL backend: server uses PostgreSQL via same SQLAlchemy ORM | §Server and Client Architecture — Server Infrastructure: Persistence | Server starts with PostgreSQL; all plan/decision/resource data persisted correctly | +| 7 | Alembic migrations for server-specific tables (users, tokens, namespace ACLs) | §Server and Client Architecture — Server Infrastructure: Persistence | `alembic upgrade head` creates server-specific tables without modifying shared schema | +| 8 | API token authentication: Bearer token validated on every request | §Server and Client Architecture — Server Security Architecture | Unauthenticated request returns 401; valid token grants access | +| 9 | Namespace-scoped authorization: users access only granted namespaces | §Server and Client Architecture — Server Security Architecture | User A cannot read/write User B's namespace entities | +| 10 | Entity sync via `_cleveragents/sync/*` extension methods | §Server Mode — Entity Sync | `agents sync` pushes local entities to server; pull brings server entities to local | +| 11 | Multi-user shared namespaces: multiple users share org-level namespace | §Server Mode — Shared Namespaces | Two users in same org namespace both see shared actions/actors/skills | +| 12 | `agents server start` launches server process | §CLI Commands — server | `agents server start` starts FastAPI+A2A server; health check endpoint responds | +| 13 | `agents server stop` / `agents server status` functional | §CLI Commands — server | Stop terminates server process; status shows running/stopped state | +| 14 | Docker container image builds and runs correctly | §Server and Client Architecture — Server Deployment | `docker build -f Dockerfile.server .` succeeds; container starts and serves A2A endpoint | +| 15 | Kubernetes Helm chart deploys server to cluster | §Server and Client Architecture — Server Deployment | `helm install cleveragents k8s/` deploys successfully; pods reach Running state | +| 16 | Server credential isolation: per-user API keys encrypted at rest | §Security Architecture — Server Mode Credential Isolation | API keys stored AES-256-GCM encrypted; never transmitted to client | +| 17 | Multi-turn interactions: server-hosted actors can access client-local resources | §Server and Client Architecture — Server Presentation Layer | Actor running on server can read/write client-local files via `_cleveragents/fs/*` | +| 18 | `agents login ` authenticates and stores token | §CLI Commands — server | `agents login` prompts for credentials; token stored in config; subsequent commands use it | +| 19 | Test coverage ≥ 97% | §Quality Gates | `nox -s coverage_report` passes | + +#### Key Architectural Constraints + +- **A2A exclusivity**: The server exposes **only** the A2A JSON-RPC 2.0 endpoint. No REST API, no GraphQL, no admin endpoint. All operations flow through A2A. +- **Shared layers**: Domain and Application layers are identical between client and server. Zero behavioral drift is enforced by consuming them as the same Python package. +- **PostgreSQL dialect**: The server uses PostgreSQL via SQLAlchemy. The ORM models are identical to the client's SQLite models; only the dialect changes. No server-specific ORM models. +- **RemoteGraph isolation**: Each actor graph (strategy, execution, estimation) deploys as a **separate** LangGraph Platform deployment. They do not share state; the `SessionWorkflow` orchestrates them. +- **Transport agnosticism**: Application-layer code must not reference transport type. The `TransportSelector` pattern ensures CLI commands work identically in local and server mode. +- **`local/` namespace**: The `local/` namespace is never accessible via server. Server users operate in their own or shared org namespaces. +- **TLS required**: HTTPS is required for all production server deployments. TLS terminates at the Kubernetes ingress. + +#### Definition of Done + +- All 19 deliverables verified by automated tests +- `nox` passes with coverage ≥ 97% +- No open P0/P1 bugs in v3.8.0 milestone +- Full server mode functional end-to-end: login, shared namespace, plan execution via RemoteGraph, entity sync, multi-user isolation + +--- + ### Cross-Milestone Quality Gates These quality gates apply to **every milestone** and must pass before a milestone is considered complete: -- 2.52.0