diff --git a/docs/specification.md b/docs/specification.md index 0743e2ae2..559a62b77 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -48524,15 +48524,17 @@ The compaction hook is implemented in `src/cleveragents/langgraph/` (either in ` 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-12)" +!!! note "Milestone Status (as of 2026-04-13)" - **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 (666 open / 258 closed) - - **v3.3.0** 🔄 IN PROGRESS — Corrections + Subplans + Checkpoints (122 open / 108 closed) - - **v3.4.0** 🔄 IN PROGRESS — ACMS v1 + Context Scaling (204 open / 137 closed) - - **v3.5.0** 🔄 IN PROGRESS — Autonomy Hardening (977 open / 201 closed) - - **v3.6.0** 🔄 IN PROGRESS — Advanced Concepts & Deferred Features (280 open / 152 closed) - - **v3.7.0** 🔄 IN PROGRESS — TUI Implementation (526 open / 427 closed) + - **v3.2.0** 🔄 IN PROGRESS — Decisions + Validations + Invariants (756 open / 269 closed) + - **v3.3.0** 🔄 IN PROGRESS — Corrections + Subplans + Checkpoints (131 open / 109 closed) + - **v3.4.0** 🔄 IN PROGRESS — ACMS v1 + Context Scaling (227 open / 139 closed) + - **v3.5.0** 🔄 IN PROGRESS — Autonomy Hardening (1,016 open / 210 closed) + - **v3.6.0** 🔄 IN PROGRESS — Advanced Concepts & Deferred Features (292 open / 152 closed) + - **v3.7.0** 🔄 IN PROGRESS — TUI Implementation (541 open / 427 closed) + - **v3.8.0** 🔄 IN PROGRESS — Server Implementation (356 open / 133 closed) + - **v3.9.0** 🔄 IN PROGRESS — Documentation & Maintenance (16 open / 4 closed) --- @@ -48802,6 +48804,51 @@ This section defines the ordered milestone plan for CleverAgents v3.x, mapping a - No open P0/P1 bugs in v3.7.0 milestone - Full TUI functional end-to-end: launch, persona, reference/command input, multi-session, settings, session management +### v3.8.0 — Server Implementation + +**Goal**: Implement the CleverAgents server and all server-dependent capabilities using the A2A (Agent-to-Agent) protocol standard. + +**Spec Coverage**: [Server and Client Architecture](#server-and-client-architecture), [A2A Protocol](#agent-to-agent-protocol-a2a), [Authentication and Authorization](#authentication-and-authorization), [Entity Sync Protocol](#entity-sync-protocol) + +**Key ADRs**: [ADR-047](adr/ADR-047-acp-standard-adoption.md), [ADR-048](adr/ADR-048-server-application-architecture.md) + +#### Deliverables + +| # | Deliverable | Spec Reference | Verifiable Check | +|---|-------------|----------------|-----------------| +| 1 | A2A HTTP transport endpoint functional (JSON-RPC 2.0 over HTTP) | §Server Architecture — A2A Endpoint | `curl -X POST /a2a` with valid JSON-RPC returns response | +| 2 | A2A stdio transport functional (local mode — agent as subprocess) | §A2A Protocol — Stdio Transport | `agents --local` routes through stdio A2A transport | +| 3 | `_cleveragents/` extension methods routed correctly | §A2A Protocol — Extension Methods | `_cleveragents/plan/list` returns plan list from server | +| 4 | LangGraph Platform RemoteGraph integration for actor execution | §Server Architecture — RemoteGraph | Actor graphs deployed to LangGraph Platform; invoked via RemoteGraph | +| 5 | Server authentication: API token validation | §Authentication and Authorization | Requests without valid Bearer token return 401 | +| 6 | Namespace-scoped authorization: users access only their namespaces | §Authentication and Authorization — Namespaces | User A cannot access User B's namespace entities | +| 7 | Entity sync: `_cleveragents/sync/pull` downloads server entities | §Entity Sync Protocol — Pull | `agents server sync pull` downloads server namespace entities to local cache | +| 8 | Entity sync: `_cleveragents/sync/push` uploads local entities | §Entity Sync Protocol — Push | `agents server sync push` uploads local entities to server namespace | +| 9 | Entity sync: `_cleveragents/sync/status` compares versions | §Entity Sync Protocol — Status | `agents server sync status` shows diff between local and server entities | +| 10 | PostgreSQL backend for multi-user persistence | §Server Architecture — Persistence | Server stores plans, sessions, and entities in PostgreSQL | +| 11 | Server deployment: Docker container builds and starts | §Server Architecture — Deployment | `docker build` and `docker run` produce working server container | +| 12 | Server deployment: Helm chart renders and deploys to Kubernetes | §Server Architecture — Kubernetes | `helm install cleveragents k8s/` deploys server to Kubernetes cluster | +| 13 | Multi-device experience: plan started on one device resumable on another | §Server Architecture — Multi-Device | Plan started via CLI resumable via TUI on different machine | +| 14 | `local/` namespace never accessible via server | §Server Architecture — Namespace Isolation | Server rejects any request targeting `local/` namespace | +| 15 | Test coverage ≥ 97% | §Quality Gates | `nox -s coverage_report` passes | + +#### Key Architectural Constraints + +- **A2A-only interface**: The server's ONLY client-facing interface is the A2A JSON-RPC 2.0 endpoint. No REST API, no GraphQL, no admin endpoints (ADR-048). +- **Shared Domain/Application layers**: Server shares Domain and Application layers with the client as a Python package dependency — zero behavioral drift (ADR-048). +- **RemoteGraph execution**: Actor graphs MUST execute via LangGraph Platform RemoteGraph — the server does not execute actor graphs in-process (ADR-048). +- **Namespace isolation**: The `local/` namespace is NEVER accessible or syncable via the server (ADR-048). +- **Authentication required**: All A2A connections require authentication before any task operations (ADR-048). +- **PostgreSQL for multi-user**: Server uses PostgreSQL (not SQLite) for multi-user persistence with proper transaction isolation (ADR-048). + +#### Definition of Done + +- All 15 deliverables verified by automated tests +- `nox` passes with coverage ≥ 97% +- No open P0/P1 bugs in v3.8.0 milestone +- Server starts, accepts A2A connections, executes plans via RemoteGraph, and syncs entities end-to-end +- Docker container and Helm chart deployment verified + --- ### Testing Strategy — E2E {#testing-strategy-e2e}