diff --git a/docs/specification.md b/docs/specification.md index dbe7bd381..02569c4d5 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -46740,9 +46740,9 @@ 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-12)" - **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) @@ -46750,7 +46750,8 @@ This section defines the ordered milestone plan for CleverAgents v3.x, mapping a - **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.7.0** 🔄 IN PROGRESS — TUI Implementation (529 open / 427 closed) + - **v3.8.0** 🔄 IN PROGRESS — Server Implementation (357 open / 132 closed) --- @@ -47009,6 +47010,82 @@ This section defines the ordered milestone plan for CleverAgents v3.x, mapping a --- +### v3.8.0 — Server Implementation + +**Goal**: Deploy CleverAgents as a multi-user collaborative server. The server +is a **separate application** (distinct deployment unit) that shares the Domain +and Application layers with the client. All client-server communication uses +A2A JSON-RPC 2.0 exclusively — no REST or GraphQL API. PostgreSQL replaces +SQLite for persistence. LangGraph Platform hosts actor execution as +RemoteGraphs. Teams share namespaces, resources, and actors. + +**Spec Coverage**: [Server and Client Architecture](#server-and-client-architecture), +[ADR-047](adr/ADR-047-acp-standard-adoption.md), +[ADR-048](adr/ADR-048-server-application-architecture.md) + +**Key ADRs**: [ADR-047](adr/ADR-047-acp-standard-adoption.md) (A2A Standard +Adoption), [ADR-048](adr/ADR-048-server-application-architecture.md) (Server +Application Architecture) + +#### Deliverables + +| # | Deliverable | Spec Reference | Verifiable Check | +|---|-------------|----------------|-----------------| +| 1 | A2A JSON-RPC 2.0 endpoint operational (single HTTP endpoint, no REST) | §Server Presentation Layer | `POST /` with valid A2A envelope returns correct JSON-RPC 2.0 response | +| 2 | Standard A2A methods functional (`tasks/send`, `tasks/get`, `tasks/cancel`, `tasks/sendSubscribe`) | §A2A Protocol | All four standard methods return spec-compliant responses | +| 3 | `_cleveragents/` extension methods: plan lifecycle (`plan.create`, `plan.execute`, `plan.apply`, `plan.status`, `plan.cancel`) | §A2A Extension Methods | Plan lifecycle operations complete end-to-end via A2A extension methods | +| 4 | `_cleveragents/` extension methods: registry CRUD (actor, skill, tool, resource, action) | §A2A Extension Methods | Registry entities can be created, read, updated, and deleted via A2A | +| 5 | `_cleveragents/sync/*` entity sync methods operational | §Server and Client Architecture — Entity Sync | Entity sync round-trips correctly between client and server | +| 6 | A2A stdio transport (local mode — agent as subprocess) functional | §A2A Protocol — Local Mode | `A2aLocalFacade` resolves operations in-process; no HTTP required | +| 7 | A2A HTTP transport (server mode) functional | §A2A Protocol — Server Mode | Server accepts A2A requests over HTTP; client connects via `A2aClient` | +| 8 | `TransportSelector` picks correct transport (stdio vs HTTP) based on config | §Client-Side Architecture | `--server` flag routes to HTTP transport; default uses stdio | +| 9 | LangGraph Platform RemoteGraph integration: actors deployed as RemoteGraphs | §Server Infrastructure: LangGraph Platform | Actor execution on server routes through LangGraph Platform RemoteGraph | +| 10 | PostgreSQL backend operational with Alembic migrations | §Server Infrastructure: Persistence | Server starts with PostgreSQL; `alembic upgrade head` applies all migrations | +| 11 | Server-specific additive tables present (team, namespace, API token, sync log) | §Server Infrastructure: Persistence | Server schema includes all server-only tables without breaking client schema | +| 12 | Authentication: API token validation (Bearer token in Agent Card) | §Server Security Architecture | Requests without valid Bearer token return 401; valid tokens succeed | +| 13 | Authorization: namespace-scoped RBAC (team membership controls resource access) | §Server Security Architecture | Cross-namespace access denied; same-namespace access permitted for team members | +| 14 | Multi-user namespace isolation: teams share resources within namespace | §Server and Client Architecture | Two users in same namespace see shared resources; users in different namespaces do not | +| 15 | Agent Card served at `/.well-known/agent.json` for ecosystem discovery | §A2A Protocol — Agent Card | `GET /.well-known/agent.json` returns valid Agent Card JSON | +| 16 | Multi-turn client callbacks operational (server pushes updates to client) | §Server Presentation Layer | Streaming plan execution events delivered to client via A2A callbacks | +| 17 | Docker image builds and runs correctly | §Server Deployment | `docker build` succeeds; `docker run` starts server; health check passes | +| 18 | Kubernetes Helm chart deploys server with PostgreSQL and LangGraph Platform | §Server Deployment | `helm install` deploys server; `kubectl get pods` shows all pods Running | +| 19 | HTTPS enforced in server mode (no plaintext HTTP in production config) | §Server Security Architecture | Server config requires TLS; plaintext HTTP rejected in production profile | +| 20 | Test coverage ≥ 97% | §Quality Gates | `nox -s coverage_report` passes | + +#### Key Architectural Constraints + +- **A2A exclusivity**: The server exposes **only** a single A2A JSON-RPC 2.0 + endpoint. No REST API, no GraphQL, no WebSocket (except as A2A transport). + This is a non-negotiable constraint from ADR-047. +- **Layer sharing**: Domain and Application layers are **identical packages** + shared between client and server. Infrastructure and Presentation layers + diverge. No domain logic may be duplicated. +- **PostgreSQL only**: The server uses PostgreSQL exclusively. SQLite is the + client-only persistence backend. No server code may reference SQLite. +- **RemoteGraph actors**: Server-side actor execution uses LangGraph Platform + RemoteGraph. The server does not run LangGraph graphs in-process. +- **Namespace isolation**: All server entities (resources, actors, skills, + tools, plans) are scoped to a namespace. Cross-namespace access is denied + at the authorization layer, not the application layer. +- **HTTPS required**: Server deployments must use TLS. The server must refuse + to start in production mode without a valid TLS configuration. +- **No client-side server code**: The `cleveragents.server` package must not + be imported by client-side code paths. The `TransportSelector` is the only + client component that knows about server existence. + +#### Definition of Done + +- All 20 deliverables verified by automated tests +- `nox` passes with coverage ≥ 97% +- No open P0/P1 bugs in v3.8.0 milestone +- Server runs end-to-end: client connects via A2A HTTP, executes a plan, + results persisted in PostgreSQL, actor runs on LangGraph Platform +- Docker image published; Helm chart deploys successfully to a test cluster +- Security review: authentication and namespace isolation verified by + integration tests (no mocking of auth layer) + +--- + ### Cross-Milestone Quality Gates These quality gates apply to **every milestone** and must pass before a milestone is considered complete: