diff --git a/CHANGELOG.md b/CHANGELOG.md index ade2d531a..5435e4c95 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Added +- **Architecture Overview Documentation**: Expanded A2A protocol overview with JSON-RPC envelopes, event streaming, and remote transport; documented storage/persistence, LangGraph execution, TUI architecture, server roadmap, and milestone progress. + - **TDD Issue-Capture Test Activation** (#7025): Replaced 234 bare `@skip` tags across 82 Behave feature files with the correct `@tdd_expected_fail @tdd_issue @tdd_issue_` tag system. Scenarios whose referenced bugs were already fixed diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 62a76a4bc..f64e07b8c 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -2,6 +2,7 @@ * Aditya Chhabra * Brent E. Edwards +* CleverThis * HAL 9000 * Hamza Khyari * Jeffrey Phillips Freeman diff --git a/docs/architecture.md b/docs/architecture.md index 76ea25633..362110cf9 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -298,8 +298,24 @@ All CLI, TUI, and server interactions cross the A2A boundary [ADR-047](adr/ADR-047-acp-standard-adoption.md)): - **Local mode** — `A2aLocalFacade` maps operations to direct Python calls -- **Server mode** — `A2aHttpTransport` (stub; full implementation pending) -- Version negotiation via `A2aVersionNegotiator` + and exposes the full `_cleveragents/plan/*` and `_cleveragents/registry/*` + surface. Handler dispatch is cached so repeated calls avoid rebuilding the + routing table, and domain exceptions are mapped to JSON-RPC error codes by + `map_domain_error`. +- **JSON-RPC 2.0 envelope** — `A2aRequest` / `A2aResponse` enforce the wire + contract, generate ULID request identifiers, and require `"jsonrpc": "2.0"` + per the spec adopted in ADR-047. +- **Event streaming** — `A2aEventQueue`, `EventBusBridge`, and + `SseEventFormatter` translate plan lifecycle `DomainEvent` objects into + Server-Sent Events (`task/statusUpdate`, `task/artifactUpdate`) so the TUI + and future server clients can follow progress without polling. +- **Version negotiation** — `A2aVersionNegotiator` rejects unsupported protocol + versions and logs accepted ones, keeping the CLI, TUI, and future server in + lock-step. +- **Remote transport roadmap** — `A2aHttpTransport` is still a stub in local + mode; the FastAPI-based JSON-RPC service planned for v3.8.0 will supply the + concrete implementation. The lightweight `a2a.asgi` module already exposes + Kubernetes health probes for early server deployment testing. --- @@ -355,6 +371,117 @@ Never construct services directly in application code. --- +## Storage & Persistence + +- Local deployments default to `sqlite:///.cleveragents/db.sqlite` (wired in + `Container.database_url`) with SQLAlchemy models in + `cleveragents.infrastructure.database.models`. Alembic migrations under + `alembic/` keep the schema aligned with the implementation plan. +- `PlanLifecycleService` operates in dual mode: with a `UnitOfWork` it persists + actions, plans, decisions, invariants, and async jobs to SQLite while + mirroring writes in an in-memory cache; without a unit of work (tests) it + falls back to the cache-only path. +- Tool executions wrap in `ChangeSetCapture`, emitting deterministic entries via + `ChangeSetEntryRepository`. These records drive diff previews, audit logs, and + the forthcoming decision timeline features. +- Git-backed projects apply changes in isolated worktrees (`GitWorktreeSandbox`) + so the developer working copy stays clean until Apply succeeds. + +--- + +## LangGraph Execution & Validation Pipeline + +- `cleveragents.actor.compiler.compile_actor` converts YAML graph actors into + `CompiledActor` bundles with LangGraph node configs, entry/exit validation, + and LSP binding metadata. +- `cleveragents.langgraph.graph.LangGraph` plus + `langgraph.bridge.RxPyLangGraphBridge` execute those graphs through the + reactive stream router, preserving execution history, state snapshots, and + cancellation signals for diagnostics. +- `cleveragents.tool.router.ToolRouter` normalises OpenAI, Anthropic, and + LangChain tool payloads into `ToolCallRequest` objects, invokes + `ToolRunner`, and emits `NormalizedToolCallResult` records with validation + metadata. `ChangeSetCapture` can wrap any write-capable `ToolSpec` so file + mutations feed directly into plan diffs. +- The apply phase uses `ApplyValidationGate` and the pluggable + `ValidationRunner` to execute validation tools, persist pass/fail metadata, + and block Apply when mandatory checks fail — groundwork for the v3.2.0 + Decisions + Validations milestone. + +--- + +## TUI Architecture + +- The optional Textual dependency is loaded at runtime; `CleverAgentsTuiApp` + composes overlays for help, slash commands, reference insertion, persona + management, and the first-run actor selector, with a fallback that explains + how to install the extra if Textual is missing. +- Input flows through `InputModeRouter`, which routes between free-form chat, + slash commands (handled by `TuiCommandRouter`), and shell execution guarded by + `tui.shell_safety.PatternDetector`. Commands resolve services from the shared + DI container so persona, session, and registry operations behave identically + to the CLI. +- Persona state (`tui.persona.state`) tracks per-session presets and scopes, and + the permissions overlay (`tui.permissions`) surfaces tool approval requests + inline. Session export/import share the same `SessionService` used by the CLI. +- Milestone v3.7.0 extends this surface with persistent session tabs, checkpoint + timelines, and persona presets; the widget scaffolding (`widgets.*`) already + contains the overlays and controls those features will inhabit. + +--- + +## Server Roadmap + +- `cleveragents.a2a.asgi:app` provides `/live`, `/ready`, and `/health` + endpoints so the Helm chart under `k8s/` can deploy probes ahead of the full + server build. +- Remote transport remains stubbed: `A2aHttpTransport` raises + `A2aNotAvailableError` for all methods and `A2aEventQueue.subscribe_remote` + does the same. The v3.8.0 milestone replaces these stubs with a FastAPI-based + JSON-RPC gateway backed by PostgreSQL. +- Server mode reuses the existing service container; the separation between + transport (`facade`, `models`, `events`) and business logic is complete, so + only the HTTP layer and database wiring remain. + +--- + +## Milestone Progress + +### Completed + +- **v3.0.0 – Minimal Local Source-Code Workflow** + Delivered SQLite-backed persistence (`Container.database_url`, + `UnitOfWork`), git worktree sandboxing, ChangeSet capture for tool mutations, + and actor-driven plan execution in local mode. +- **v3.1.0 – Actor Compiler + Full LLM Integration** + Landed the LangGraph-based actor compiler, MCP/LSP adapters, the tool router, + validation runner, and event queue wiring so CLI/TUI sessions share the same + execution pipeline. + +### In Flight + +- **v3.2.0 – Decisions + Validations + Invariants** — builds on + `PlanLifecycleService`, `DecisionService`, and `ApplyValidationGate` to record + decision trees, enforce invariants, and surface validation outcomes. +- **v3.3.0 – Corrections + Subplans + Checkpoints** — extends + `GitWorktreeSandbox`, `ChangeSetCapture`, and the subplan tooling to support + targeted corrections and checkpoint review. +- **v3.4.0 – ACMS v1 + Context Scaling** — expands `ContextTierService`, + context hydration, and UKO runtime so larger projects can stream curated + context to actors. +- **v3.5.0 – Autonomy Hardening** — hardens guardrails by leveraging + `PlanPreflightGuardrail`, shell safety scoring, and the A2A event queue for + background monitoring. +- **v3.6.0 – Advanced Concepts** — introduces additional LLM backends, + container execution (`tool.container_executor`), and richer resource types. +- **v3.7.0 – TUI Implementation** — completes the Textual experience with + session persistence, persona presets, and surfacing plan checkpoints. +- **v3.8.0 – Server Implementation** — ships the FastAPI/JSON-RPC gateway, + remote event streaming, and PostgreSQL-backed persistence on top of the + existing ASGI/transport scaffolding. + +--- + ## Key Design Decisions | Decision | ADR | Summary |