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

docs: add v3.8.0 Server Implementation and v3.9.0 documentation #10005

Closed
HAL9000 wants to merge 1 commits from docs/auto-docs-2-v380-v390 into master
pull from: docs/auto-docs-2-v380-v390
merge into: cleveragents:master
Conversation 9 Commits 1 Files Changed 4
+871 -277
4 changed files with 871 additions and 277 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+30 -277
View File
@@ -5,294 +5,47 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
## [Unreleased]
### Fixed
- **TDD Non-AssertionError Guard Visibility** (#8294): `apply_tdd_inversion` in
`features/environment.py` now emits its non-assertion exception guard warning to
both the structured logger and `stderr` via a new `_warning_with_stderr` helper.
This makes the guard firing visible in standard Behave console output and CI log
snippets where the structured logging sink may not be displayed. BDD infrastructure
coverage added: a new scenario in `tdd_expected_fail_infrastructure.feature`
asserts that the warning is emitted to stderr when a non-AssertionError exception
is encountered in an `@tdd_expected_fail` scenario, and a second scenario asserts
the warning is NOT emitted when the exception is an `AssertionError`. The
`CONTRIBUTING.md` now documents that `@tdd_expected_fail` step definitions must
signal expected failures via `AssertionError`.
- **Parallel Behave Runner Log Noise Reduction** (#8351): The parallel behave
runner now suppresses captured stdout/stderr for passing worker chunks and
only replays diagnostics for failed, errored, or crashed chunks. This makes
failure output significantly easier to spot in CI and local runs. A worker
crash (unhandled exception) is detected via an all-zero summary and the
captured traceback is always surfaced.
- **Automation Profile Silent Fallback** (#8232): `_resolve_profile_for_plan` in
`PlanLifecycleService` now raises a clear `ValidationError` when a plan's
automation profile name is not a known built-in profile, instead of silently
falling back to `"manual"`. Users who configured custom automation profiles
(e.g. `"semi-auto"`, `"acme/strict"`) will now receive an actionable error
message listing available built-in profiles. The resolved profile name is also
logged at debug level for observability.
## [3.9.0] — Unreleased
### Added
- Wired `StrategyActor` into the real plan execution path: `_get_plan_executor`
in `plan.py` now resolves the strategy actor via `resolve_strategy_actor()`
(reading the `actor.default.strategy` config key) instead of always
constructing `LLMStrategizeActor`. `run_strategize` in `PlanExecutor` now
passes `resources` (derived from `plan.project_links`) and `project_context`
to the actor so the LLM prompt receives full project context. Strategy
decisions are serialised as JSON in `plan.error_details["strategy_decisions_json"]`
so `_build_decisions` can reconstruct the full hierarchy (dependency ordering,
parent/child structure) during Execute instead of rebuilding from
`definition_of_done`. `StrategizeStubActor.execute` accepts `**kwargs` for
forward-compatibility. Added BDD coverage for the stored-JSON path,
corrupt-JSON fallback, resource-passing, and stub extra-kwargs scenarios.
(#828)
- **Server Guide** (`docs/server.md`): Comprehensive documentation for the
v3.8.0 Server Implementation covering the A2A JSON-RPC 2.0 protocol, all
transport modes (stdio local, HTTP server, external A2A agent), Agent Card
discovery, `_cleveragents/` extension method catalog, authentication and
RBAC, entity sync protocol, multi-device shared namespaces, PostgreSQL
backend, Docker and Kubernetes/Helm deployment, and CLI commands for server
management.
- **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_<N>` tag system. Scenarios whose referenced bugs were already fixed
had `@tdd_expected_fail` removed and now run as permanent regression guards.
Net result: 629 features active in CI (up from ~545), zero `@skip` tags remain.
- **v3.9.0 Updates** (`docs/v390-updates.md`): Release notes and feature
refinement documentation for v3.9.0 covering documentation improvements,
A2A protocol enhancements, server mode improvements, entity sync
refinements, CLI improvements, bug fixes, and quality improvements.
- **Git Worktree Sandbox Apply** (#4454): The `plan apply` command now merges
LLM-generated changes via `git merge` from an isolated worktree branch
instead of flat `shutil.copy2`. Displays spec-aligned Apply Summary
(plan ID, artifacts, insertions/deletions, project, timestamp), Sandbox
Cleanup panel, and `✓ OK Changes applied` footer. Non-git projects fall
back to the original flat file copy.
- **Context Hydration Fix** (#4454): Fixed `ContextFragment` metadata types
(`detail_depth` and `relevance_score` must be strings, not int/float) that
caused Pydantic validation errors during context assembly, resulting in the
LLM receiving zero file context.
- **Automation Tracking System**: Replaced shared session state issue tracking with
individual per-agent tracking issues. Each agent now creates its own `[AUTO-<PREFIX>]`
titled issues with standardized headers, reporting intervals, and health indicators.
Agents: `session-persister`, `implementation-orchestrator`, `system-watchdog`,
`backlog-groomer`, `human-liaison`. Documentation at
`docs/development/automation-tracking.md`.
- **Automated Health Monitoring and Recovery**: The `system-watchdog` now runs
`audit_automation_tracking_health()` every 5 minutes, detecting stalled agents when
tracking issues are >20% overdue from their declared reporting interval. On detection,
it terminates stalled sessions via the OpenCode Server API, performs root-cause analysis,
creates high-priority diagnostic issues, and closes stale tracking issues with recovery
notes.
- **Centralized Label Management** (`forgejo-label-manager`): A new specialized subagent
centralizes all Forgejo label operations across the agent system. Enforces the
organization-level label system, prohibits label creation, and validates label compliance.
Agents `backlog-groomer`, `human-liaison`, `project-owner`, `epic-planner`,
`new-issue-creator`, and `issue-state-updater` now delegate all label operations to this
subagent.
- **PR–Issue Label Synchronization**: PRs now inherit `Priority/`, `MoSCoW/`, `Points/`,
and `State/` labels from their associated issues at creation time
(`pr-api-creator`). The `backlog-groomer` adds a continuous Pass 19 for ongoing
PR–issue label synchronization. The `issue-state-updater` syncs PR state labels whenever
issue states change.
- **Automation Tracking Announcements**: Extended `automation-tracking-manager` with
announcement issue support (`CREATE_ANNOUNCEMENT_ISSUE`, `CLOSE_ANNOUNCEMENT_ISSUE`,
`LIST_TRACKING_ISSUES`, `READ_ANNOUNCEMENTS`, `REVIEW_OWN_ANNOUNCEMENTS`). Supervisors
and workers now read critical announcements before each cycle for cross-agent awareness.
Priority-based filtering (Critical/High/Medium/Low) reduces noise. Backlog-groomer
performs intelligent cleanup with age thresholds by priority.
- **PR Agent Reorganization**: All PR-related agents renamed and reorganized to follow
the `*-pool-supervisor` naming pattern. New agents added: `pr-editor` (safe PR editing
with description preservation), `pr-manager` (unified PR interface), and
`pr-merge-pool-supervisor` (automated PR merging supervisor). Renamed:
`pr-api-creator` → `pr-creator`, `pr-checker` → `pr-ci-test-fixer`,
`pr-status-checker` → `pr-status-analyzer`, `pr-self-reviewer` → `pr-reviewer`,
`pr-fix-orchestrator` → `pr-fix-pool-supervisor`.
- **Automated PR Merging** (`pr-merge-pool-supervisor`): New supervisor continuously
monitors for merge-ready PRs and merges them automatically when all criteria are met
(approvals, CI passing, no conflicts). Supports both formal reviews and comment-based
approvals (LGTM, ✅, "ready to merge", etc.).
- **Implementation Worker Workflow Completion**: `implementation-worker` now implements
work claiming protocols with conflict detection, comprehensive review feedback handling
with intelligent parsing, sophisticated merge conflict resolution with multiple
strategies, and parallel subtask execution with wave-based dependency analysis.
Pass rate improved from 48.15% to 84.8%.
- **Container Resource Stop Support**: `agents resource stop` now correctly stops
`container-instance` and `devcontainer-instance` resource types.
- **Centralized Automation Tracking Manager** (`automation-tracking-manager`): The manager
is now the single interface for all tracking issue operations (`CREATE_TRACKING_ISSUE`,
`UPDATE_TRACKING_ISSUE`, `CLOSE_TRACKING_ISSUE`, `READ_TRACKING_STATE`,
`GET_NEXT_CYCLE_NUMBER`). Agents delegate to the manager rather than calling the Forgejo
API directly, ensuring sequential cycle numbers across restarts and preventing
duplicate issues. Migrated agents include `system-watchdog`,
`implementation-pool-supervisor`, `timeline-update-pool-supervisor`,
`project-owner-pool-supervisor`, `product-builder`, and
`backlog-grooming-pool-supervisor`. The legacy `shared/automation_tracking.md` module
was removed.
- **Documentation Writer Tracking** (`docs-writer`): The documentation writer now
participates in the automation tracking system by creating individual
`[AUTO-DOCS] Documentation Report (Cycle N)` issues every 10 cycles (~3.3 hours).
The manager applies the mandatory `Automation Tracking` label automatically, while
teams may add additional workflow labels as needed. See
`docs/development/automation-tracking.md` and the new
`docs/development/docs-writer.md` reference.
- **ACMS / UKO API Documentation** (`docs/api/acms.md`): Added comprehensive API
reference for the `cleveragents.acms` package covering the four-layer UKO ontology
hierarchy, `VocabularyRegistry`, `ProvenanceInfo`, `UKOClass`, `UKOProperty`,
`UKOVocabulary`, `Layer2Dependency`, `ParadigmVocabulary`, `DetailLevelMapBuilder`,
and all Layer 3 language vocabulary types (Python, TypeScript, Rust, Java).
The new page is linked from the API Reference index and the MkDocs navigation.
- **MkDocs navigation**: Added "Server Guide (v3.8.0)" and "v3.9.0 Updates"
entries to the MkDocs navigation.
### Changed
- **Decision Tree Full ULID Display** (#5825): The `agents plan tree` command now
displays full 26-character ULIDs for all decisions instead of truncating them to
8 characters. This enables users to copy decision IDs directly from tree output
and use them in follow-up CLI commands like `agents plan correct` without manual
ID reconstruction. Added "Decision IDs (for correction)" section with human-readable
labels for easy reference. Applies to both table and rich/plain text output formats.
- **Automation Tracking Format**: All automation tracking issues now use a standardized
header format with mandatory `Reporting Interval: <interval> (Next report expected: <ts>)`
declarations, enabling precise staleness detection.
- **PR Review Policy**: Reduced PR review requirement from 2 approvals to 1. Self-approval
is now permitted including for automated bot PRs. Approval can be a formal review OR an
approval comment (LGTM, Approved, ✅, "ready to merge").
- **Label Delegation Enforcement**: `automation-tracking-manager` now enforces delegation
to `forgejo-label-manager` for all label operations, preventing "invalid label ID" errors
and ensuring label application uses correct name-to-ID mapping.
- **Automation Tracking Label Guidance**: Documentation now clarifies that the manager
automatically applies the `Automation Tracking` label and that additional labels such as
`Type/Automation`, `State/In Progress`, or `Priority/Medium` remain optional workflow
choices rather than mandatory.
- **Automation Tracking Agent Prefix Registry**: Expanded from 5 agents to 18 agents.
New prefixes include `AUTO-DOCS`, `AUTO-REV-POOL`, `AUTO-UAT-POOL`, `AUTO-BUG-POOL`,
`AUTO-INF-POOL`, `AUTO-ARCH`, `AUTO-EPIC`, `AUTO-EVLV`, `AUTO-GUARD`, `AUTO-SPEC`,
`AUTO-TIME`, `AUTO-PROJ-OWN`, and `AUTO-PROD-BLDR`.
- `_cleveragents/sync/status` now returns a structured diff (added/modified/
deleted entities per namespace) instead of a plain-text summary.
- Auto-sync now uses exponential backoff on repeated failures (configurable
via `server.sync.backoff_max`, default 3600 seconds).
- Server health check (`/health`) now returns structured JSON including
database and LangGraph Platform connectivity status.
### Fixed
- **Plan Concurrency Race Condition** (#7989): Fixed critical race condition in `execute_plan()` and
`apply_plan()` where concurrent CLI/worker sessions could simultaneously modify the same plan,
corrupting plan state. `LockService` is now wired into the plan lifecycle with plan-level advisory
locking. Each invocation generates a unique caller identity (UUID) to prevent re-entrant lock
acquisition by concurrent sessions on the same plan. Concurrent attempts now raise `LockConflictError`
instead of silently racing. Lock is acquired before phase transition and released in a `finally`
block to ensure cleanup even on error.
- **`--format color` ANSI Output** (#7910): Fixed `format_output` routing the `color` format
option to `_format_plain`, which produced plain uncoloured text instead of ANSI escape
sequences. The `color` format is now routed to `format_output_session` which uses the
`ColorMaterializer` to emit proper ANSI-coloured output. `--format plain` and all other
formats remain unaffected.
- **ContextTierService Thread Safety** (#7547): Added `threading.RLock` to
`ContextTierService` to prevent `RuntimeError: dictionary changed size during
iteration` and data corruption under concurrent plan execution. All public
methods (`store`, `get`, `promote`, `demote`, `evict_lru`, `enforce_staleness`,
`get_metrics`, `get_all_fragments`, `get_hot_fragments`, `get_for_actor`,
`get_scoped_view`, `get_scoped_by_resource`, `get_scoped_metrics`) now acquire
the reentrant lock before accessing the hot/warm/cold tier dicts. The service
was previously documented as single-threaded but registered as a DI Singleton,
causing potential data corruption when parallel subplans shared the same
instance. The `TierRuntimeMixin.enforce_staleness()` and
`ScopedTierMixin.get_scoped_by_resource()` / `get_scoped_metrics()` methods
are also protected. The DI container registration as `providers.Singleton`
is now correct and safe.
- **Validation Gate Empty-Run Guard** (#7508): Fixed `ApplyValidationSummary.all_required_passed`
returning `True` when zero validations were run, silently bypassing the apply gate. The property
now returns `False` when the validation result set is empty (`is_empty` is `True`), ensuring
that apply is blocked unless at least one validation was actually executed. Also added
`required_total` property for completeness. Updated `consolidated_validation.feature` scenarios
to reflect the corrected blocking behavior for empty summaries and no-attachment runs.
- **ACMS context tier hydration**: `ContextTierService` no longer starts empty
on every CLI invocation. A new `context_tier_hydrator.py` reads files from
linked project resources (via `git ls-files` or `os.walk`), creates
`TieredFragment` objects, and stores them in the tier service before context
assembly in `LLMExecuteActor.execute()`. The LLM now receives real file
context during plan execution. Respects max file size (256 KB), total budget
(10 MB), binary file exclusion, and `.git`/`node_modules`/`__pycache__`
directory skipping. (#1028)
- **Sandbox root wiring**: `_get_plan_executor()` now passes
`sandbox_root=.cleveragents/sandbox/`, so LLM file output (`FILE:` blocks)
is written to disk during the execute phase. (#4222)
- **SubplanExecutionService fail_fast cancellation** (#7582): Fixed a race condition where
already-running parallel subplans were not cancelled when `fail_fast` fired. Previously,
`Future.cancel()` only prevented queued futures from starting but had no effect on
in-flight futures that completed after `stop_flag` was set — their `COMPLETE` results
were incorrectly included in the merge output. The fix adds a post-completion guard that
overrides any non-`ERRORED`/non-`CANCELLED` result to `CANCELLED` when `stop_flag` is
active, and clears the associated output to prevent it from entering the merge. Also
replaces the O(n) linear `status` lookup in the `as_completed()` loop with an O(1)
`status_map` dict pre-computed before the executor block.
- **Robot Framework TDD Listener Guards** (#5436): Added three guard conditions to the
`tdd_expected_fail_listener` `end_test()` function to prevent blindly inverting ALL test
failures to passes, which was masking infrastructure errors and causing flaky CI behavior.
Guards: setup/teardown error detection, non-assertion failure detection (infrastructure
errors), and dry-run mode detection. Also fixed `Variable Should Exist` syntax errors in
e2e test files and removed `tdd_expected_fail` from 4 context assembly e2e tests where
bugs were already fixed.
- **PluginLoader entry point prefix validation** (#7476): Parse entry point targets before
import, enforce the module allowlist ahead of loading, and add Behave plus Robot Framework
regression coverage to ensure disallowed prefixes never execute untrusted module-level code
in either unit or integration flows.
- **`issue-state-updater` Bash Script Errors**: Removed problematic bash script examples
that tried to invoke `task forgejo-label-manager` as a bash command (the Task tool cannot
be invoked from bash). Replaced with clear step-by-step operational instructions and
direct label management via API.
- **`automation-tracking-manager` Label Delegation Syntax**: Fixed incorrect delegation
syntax when calling `forgejo-label-manager`. The manager now uses correct natural language
requests (e.g., "Apply labels to issue #123: Automation Tracking") instead of structured
parameters, ensuring tracking issues receive proper labels.
- **`product-builder` Missing Supervisors**: Added missing `pr-fix-pool-supervisor` and
`pr-merge-pool-supervisor` to the product-builder's supervisor launch list (18 total
supervisors). Updated all numeric references, pre-flight checklists, and validation logic.
- `ActionRepository.update()` now uses explicit bulk `sa_delete()` + `session.flush()`
before re-inserting child rows for `action_arguments` and `action_invariants`, fixing
a `sqlite3.IntegrityError: UNIQUE constraint failed` crash when `agents plan use` was
called on an action that already had arguments registered via `action create`. (#4197)
---
- `_cleveragents/sync/pull` no longer fails silently when server namespace
entities conflict with local `local/` namespace entries.
- `agents server connect` now correctly persists the connection token across
CLI invocations.
- `TaskStatusUpdateEvent` is now emitted when a task transitions from
`input-required` back to `working`.
- Namespace ACL changes now take effect immediately without requiring a
server restart.
- `agents server token revoke` now invalidates all active sessions using the
revoked token.
## [3.8.0] — 2026-04-05
### Added
- Wired Invariant Reconciliation Actor auto-invocation into
`PlanLifecycleService` phase transitions (`start_strategize`,
`execute_plan`, `apply_plan`). Reconciliation failures now block
the transition with `ReconciliationBlockedError` and emit
`INVARIANT_VIOLATED` events. Post-correction reconciliation runs
via `CORRECTION_APPLIED` event subscription (best-effort). Added
`InvariantService` Singleton provider in the DI container.
- **TUI — Shell danger detection**: The TUI shell mode (`!` prefix) now detects
dangerous command patterns before execution. A configurable pattern registry
classifies commands by danger level (warning, critical) and surfaces a user
warning overlay before proceeding. Patterns cover destructive filesystem
operations, privilege escalation, network exfiltration, and more. (#1003)
- **TUI — Permission Question Widget**: A new inline `PermissionQuestionWidget`
renders permission requests directly in the conversation stream for single-file
operations. Users can allow/reject with single-key shortcuts (`a`/`A`/`r`/`R`),
navigate with arrow keys, confirm with `Enter`, or press `v` to open the full
docs/server.md
+660
View File
@@ -0,0 +1,660 @@
# Server Guide (v3.8.0)
CleverAgents v3.8.0 (M9: Server Implementation) introduces the full
CleverAgents server and all server-dependent capabilities. The server
exposes a single **A2A JSON-RPC 2.0 endpoint** that handles both standard
agent interactions and all platform operations via `_cleveragents/`
extension methods.
See [ADR-047](adr/ADR-047-acp-standard-adoption.md) (A2A Standard Adoption)
and [ADR-048](adr/ADR-048-server-application-architecture.md) (Server
Application Architecture) for the authoritative design decisions.
---
## Overview
The CleverAgents server enables:
- **Multi-device access** — connect from any machine using the same server
namespace
- **Shared namespaces** — teams share actors, skills, plans, and resources
under a common `<orgname>/` namespace
- **Remote actor execution** — actor graphs run on LangGraph Platform via
RemoteGraph, not on the client machine
- **Entity sync** — local and server namespaces stay in sync via
`_cleveragents/sync/*` extension methods
- **Authentication & RBAC** — API tokens and team-level role-based access
control protect all server resources
The server shares the same **Domain** and **Application** layers as the
local client. Only the Infrastructure and Presentation layers differ,
ensuring zero behavioral drift between local and server modes.
---
## A2A Protocol
### What is A2A?
The **Agent-to-Agent (A2A) Protocol** is an open standard
([a2a-protocol.org](https://a2a-protocol.org)) under the Linux Foundation
(Apache 2.0 license). It provides:
- A JSON-RPC 2.0 wire format with SSE streaming
- **Agent Cards** (`/.well-known/agent.json`) for dynamic capability
discovery
- Standard operations for messaging, task lifecycle, push notifications, and
agent discovery
- An extensibility mechanism for platform-specific operations
CleverAgents adopts A2A as the **sole** communication protocol for all
client-server interaction. There is no REST API, no GraphQL, no separate
admin endpoint.
### Standard A2A Operations
| Operation | Direction | Purpose |
|-----------|-----------|---------|
| `message/send` | Client → Server | Send a message to the agent; receive a Task or direct response |
| `message/stream` | Client → Server | Send a message with SSE streaming of task updates |
| `tasks/get` | Client → Server | Retrieve current state of a task |
| `tasks/list` | Client → Server | List tasks with optional filtering |
| `tasks/cancel` | Client → Server | Cancel a running task |
| `tasks/subscribe` | Client → Server | Subscribe to task updates via SSE |
| `pushNotificationConfig/*` | Client → Server | Manage push notification webhooks |
| `getExtendedAgentCard` | Client → Server | Fetch authenticated Agent Card with full detail |
### Standard A2A Streaming Events
| Event | Emitted When |
|-------|-------------|
| `TaskStatusUpdateEvent` | Task state changes (`submitted` → `working` → `completed`, etc.) |
| `TaskArtifactUpdateEvent` | Agent produces output (response chunks, plan entries, tool results) |
### Task Lifecycle States
| State | Meaning |
|-------|---------|
| `submitted` | Task received, not yet started |
| `working` | Task actively executing |
| `input-required` | Waiting for human-in-the-loop input (automation profile gate) |
| `completed` | Task finished successfully |
| `failed` | Task encountered an unrecoverable error |
| `canceled` | Task was cancelled by the client |
| `rejected` | Task rejected before execution (e.g., authorization failure) |
### `_cleveragents/` Extension Methods
All CleverAgents platform operations use the `_cleveragents/` namespace,
declared in the Agent Card via the A2A extension mechanism. Extension
methods follow the naming convention `_cleveragents/{domain}/{operation}`.
**Plan lifecycle:**
| Method | Purpose |
|--------|---------|
| `_cleveragents/plan/create` | Create a new plan |
| `_cleveragents/plan/status` | Query plan status |
| `_cleveragents/plan/execute` | Execute a plan |
| `_cleveragents/plan/apply` | Apply a plan |
| `_cleveragents/plan/diff` | Retrieve plan diff |
| `_cleveragents/plan/correct` | Apply a correction to a plan |
| `_cleveragents/plan/tree` | Retrieve the decision tree |
**Registry operations:**
| Method | Purpose |
|--------|---------|
| `_cleveragents/registry/list_actors` | List registered actors |
| `_cleveragents/registry/list_skills` | List registered skills |
| `_cleveragents/registry/list_tools` | List available tools |
| `_cleveragents/registry/list_resources` | List registered resources |
**Entity sync:**
| Method | Purpose |
|--------|---------|
| `_cleveragents/sync/pull` | Download server namespace entities to local cache |
| `_cleveragents/sync/push` | Upload local entity definitions to a server namespace |
| `_cleveragents/sync/status` | Compare local and server entity versions |
**Namespace management:**
| Method | Purpose |
|--------|---------|
| `_cleveragents/namespace/list` | List accessible namespaces |
| `_cleveragents/namespace/create` | Create a new namespace |
| `_cleveragents/namespace/acl` | Manage namespace access control |
**Filesystem and terminal (client-side):**
| Method | Purpose |
|--------|---------|
| `_cleveragents/fs/*` | Agent accesses files on the client machine |
| `_cleveragents/terminal/*` | Agent runs commands in sandbox on the client machine |
---
## Wire Format: JSON-RPC 2.0
All A2A messages use JSON-RPC 2.0 framing.
### Request: `message/send`
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "message/send",
"params": {
"message": {
"role": "user",
"parts": [{ "text": "Refactor the auth module to use dependency injection" }]
}
}
}
```
### Response: Task created
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"id": "task_01HXRCF1...",
"status": { "state": "working" }
}
}
```
### SSE Streaming Event
```json
{
"jsonrpc": "2.0",
"method": "message/stream",
"params": {
"id": "task_01HXRCF1...",
"status": { "state": "working" },
"artifacts": [{ "parts": [{ "text": "I'll start by extracting the authentication..." }] }]
}
}
```
### Extension Method Request
```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..." }
}
}
```
### Error Code Reference
| 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` |
Application-specific error codes use the range `-32001` to `-32099` per
JSON-RPC 2.0 convention.
---
## Transport Modes
### Local Mode — A2A JSON-RPC over stdio
The client spawns the agent as a subprocess. A2A JSON-RPC messages flow
over stdin/stdout. Platform operations are handled by `A2aLocalFacade`
which routes to in-process Application-layer services. No network, no
serialization beyond JSON-RPC framing. Authentication is bypassed — the
subprocess runs with the user's local permissions.
### Server Mode — A2A JSON-RPC over HTTP
The client connects to the CleverAgents server via the A2A SDK's HTTP
transport. All communication — both agent interactions and platform
operations — flows through the single A2A endpoint. The server delegates
actor execution to LangGraph Platform via RemoteGraph.
### Server Mode — 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. This enables interoperability with any
A2A-compliant agent.
---
## Agent Card Discovery
The CleverAgents Agent Card is served at `/.well-known/agent.json` and
declares:
- **Skills**: Plan lifecycle management, registry CRUD, context assembly,
entity sync, namespace management, diagnostics
- **Extensions**: `_cleveragents/` methods with URI
`urn:cleveragents:extensions:v1`
- **Supported interfaces**: `jsonrpc` (primary)
- **Security schemes**: OAuth2, API key, or HTTP bearer
An authenticated extended Agent Card with additional detail is available via
the `getExtendedAgentCard` operation.
```bash
# Discover server capabilities
curl https://my-server.example.com/.well-known/agent.json
```
---
## Server Application Structure
The server follows the same four-layer architecture as the client
([ADR-001](adr/ADR-001-layered-architecture.md)), sharing two layers:
| Layer | Client | Server | Shared? |
|-------|--------|--------|---------|
| **Domain** | Business rules, domain models, domain events | Same | Yes — identical package |
| **Application** | Service facades, workflows, event bus | Same | Yes — identical package |
| **Infrastructure** | SQLite, local sandbox, `A2aLocalFacade` | PostgreSQL, LangGraph Platform RemoteGraph, A2A SDK server | No — different implementations |
| **Presentation** | CLI (Typer), TUI (Textual) | A2A JSON-RPC 2.0 endpoint | No — different entry points |
The shared Domain and Application layers are consumed as a Python package
dependency, ensuring zero behavioral drift between local and server modes.
### 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 each deploy as **separate
RemoteGraphs**. The `SessionWorkflow` orchestrates them the same way it
orchestrates local actor graphs, but through the RemoteGraph interface.
### Technology Stack
| Component | Version | Purpose |
|-----------|---------|---------|
| Python | >= 3.13 | Runtime |
| A2A Python SDK (`a2a-sdk`) | Latest | A2A JSON-RPC 2.0 server implementation |
| 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 |
| Helm | >= 3.0 | Kubernetes deployment |
---
## Authentication and Authorization
### Authentication Flow
1. Client discovers the server's Agent Card at `/.well-known/agent.json`
2. Agent Card's `securitySchemes` field 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 entirely.
### API Token Authentication
```bash
# Authenticate with a bearer token
curl -H "Authorization: Bearer <your-api-token>" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tasks/list","params":{}}' \
https://my-server.example.com/a2a
```
### Namespace-Scoped Authorization (RBAC)
- Users can only access entities in namespaces they have been granted access
to
- The `local/` namespace is **never** accessible via the server — it exists
only on the client
- Server namespaces (`<username>/`, `<orgname>/`) have explicit ACLs managed
via `_cleveragents/namespace/acl`
| Role | Permissions |
|------|-------------|
| `owner` | Full read/write/admin on namespace |
| `member` | Read/write on namespace entities |
| `viewer` | Read-only access to namespace entities |
---
## Entity Sync
Entity synchronization between client and server uses A2A extension methods.
### Sync Operations
| Method | Purpose |
|--------|---------|
| `_cleveragents/sync/pull` | Download server namespace entities to local cache |
| `_cleveragents/sync/push` | Upload local entity definitions to a server namespace |
| `_cleveragents/sync/status` | Compare local and server entity versions |
### Sync Behavior
- **Auto-sync** (`server.sync.auto`): Entities sync on connection and at
`server.sync.interval` (default: 300 seconds)
- **Direction**: Server → local for server namespaces; local → server only
on explicit push
- **Conflict resolution**: Server version wins by default; conflicts are
surfaced to the user via `sync/status`
- The `local/` namespace is **never** synced to the server
### CLI Sync Commands
```bash
# Check sync status
agents server sync status
# Pull latest from server
agents server sync pull
# Push local entities to server namespace
agents server sync push --namespace myorg/
```
---
## Multi-Device Experience and Shared Namespaces
### Shared Namespaces
Server namespaces (`<orgname>/`) allow teams to share actors, skills, plans,
and resources under a common namespace.
### Namespace Isolation
```
local/ <- Never synced; client-local only
<username>/ <- Personal server namespace
<orgname>/ <- Shared team namespace
```
### PostgreSQL Backend
The server uses PostgreSQL for multi-user persistence:
- **Session store** — multi-user session persistence with namespace isolation
- **Plan store** — plan lifecycle records, decision trees, artifacts
- **User/token store** — authentication credentials and API tokens
- **Namespace ACLs** — access control lists for namespace authorization
The SQLAlchemy repository implementations are shared between client and
server where the schema is identical. Server-specific tables (authentication,
namespace ACLs, user management) are additive.
---
## Server Deployment
### Docker
```bash
# Build the server image
docker build -t cleveragents-server:latest .
# Run with environment configuration
docker run -d \
-p 8080:8080 \
-e DATABASE_URL=postgresql://user:pass@db:5432/cleveragents \
-e LANGGRAPH_PLATFORM_URL=https://langgraph.example.com \
-e SECRET_KEY=<your-secret-key> \
cleveragents-server:latest
```
### Kubernetes with Helm
```bash
# Add the CleverAgents Helm repository
helm repo add cleveragents https://charts.cleverthis.com
# Install the server
helm install cleveragents-server cleveragents/cleveragents-server \
--namespace cleveragents \
--create-namespace \
--set database.url=postgresql://user:pass@db:5432/cleveragents \
--set langgraph.platformUrl=https://langgraph.example.com \
--set ingress.enabled=true \
--set ingress.host=agents.example.com
```
### Helm Chart Values
```yaml
# k8s/values.yaml
replicaCount: 2
image:
repository: cleveragents/server
tag: "3.8.0"
pullPolicy: IfNotPresent
service:
type: ClusterIP
port: 8080
ingress:
enabled: true
host: agents.example.com
tls:
enabled: true
secretName: agents-tls
database:
url: postgresql://user:pass@db:5432/cleveragents
langgraph:
platformUrl: https://langgraph.example.com
redis:
enabled: false
resources:
limits:
cpu: "2"
memory: 2Gi
requests:
cpu: "500m"
memory: 512Mi
```
### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `DATABASE_URL` | Yes | PostgreSQL connection string |
| `LANGGRAPH_PLATFORM_URL` | Yes | LangGraph Platform base URL |
| `SECRET_KEY` | Yes | Secret key for token signing |
| `REDIS_URL` | No | Redis connection string (optional) |
| `LOG_LEVEL` | No | Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
| `A2A_VERSION` | No | A2A protocol version to advertise (default: latest) |
---
## CLI Commands for Server Management
### Server Control
```bash
# Start the server (development mode)
agents server start
# Start with custom host/port
agents server start --host 0.0.0.0 --port 8080
# Check server status
agents server status
# Stop the server
agents server stop
```
### Connection Management
```bash
# Connect CLI to a remote server
agents server connect https://my-server.example.com --token <api-token>
# Disconnect from server
agents server disconnect
# Show current server connection
agents server info
```
### User and Token Management
```bash
# Create an API token
agents server token create --name "my-token" --expires 90d
# List API tokens
agents server token list
# Revoke an API token
agents server token revoke <token-id>
```
### Namespace Management
```bash
# List accessible namespaces
agents namespace list
# Create a new namespace
agents namespace create myorg/
# Grant access to a namespace
agents namespace acl grant myorg/ --user alice --role member
# Revoke access
agents namespace acl revoke myorg/ --user alice
```
---
## Configuration
### Client Configuration for Server Mode
```yaml
# ~/.cleveragents/config.yaml
server:
url: https://my-server.example.com
token: <your-api-token>
sync:
auto: true
interval: 300
namespace: myorg/
```
### Server Configuration
```yaml
# server/config.yaml
server:
host: 0.0.0.0
port: 8080
workers: 4
database:
url: postgresql://user:pass@localhost:5432/cleveragents
pool_size: 10
max_overflow: 20
langgraph:
platform_url: https://langgraph.example.com
api_key: <langgraph-api-key>
auth:
secret_key: <secret-key>
token_expiry_days: 90
sync:
auto: true
interval: 300
logging:
level: INFO
format: json
```
---
## Multi-Turn Interactions
The server supports human-in-the-loop interactions via A2A's
`input-required` task state. When an automation profile gate requires
human approval:
1. The running task transitions to `input-required` state
2. A `TaskStatusUpdateEvent` is streamed to the client
3. The client prompts the user for input
4. The user's response is sent via `message/send` referencing the task ID
5. The task resumes execution
---
## Versioning
- The JSON-RPC protocol version is always `"2.0"` in the `jsonrpc` field
- A2A protocol version is communicated via the `A2A-Version` HTTP header
- CleverAgents extension version is declared in the Agent Card's `extensions`
field under `urn:cleveragents:extensions:v1`
- Backward compatibility: servers support the current extension version plus
one prior minor version
- Breaking changes to extension methods require a major version bump of the
`_cleveragents` extension namespace
---
## Related Documentation
- [ADR-047: A2A Standard Adoption](adr/ADR-047-acp-standard-adoption.md)
- [ADR-048: Server Application Architecture](adr/ADR-048-server-application-architecture.md)
- [ADR-023: Server Mode](adr/ADR-023-server-mode.md)
- [ADR-026: Agent-to-Agent Protocol (A2A)](adr/ADR-026-agent-client-protocol.md)
- [ADR-022: LangChain/LangGraph Integration](adr/ADR-022-langchain-langgraph-integration.md)
- [A2A Protocol API Reference](api/a2a.md)
- [Architecture Overview](architecture.md)
docs/v390-updates.md
+179
View File
@@ -0,0 +1,179 @@
# v3.9.0 Updates
v3.9.0 is a documentation and feature update release that builds
incrementally on the server implementation delivered in v3.8.0. It
addresses documentation gaps, refines existing features, and delivers
targeted improvements across the platform.
---
## Overview
| Attribute | Value |
|-----------|-------|
| Version | 3.9.0 |
| Type | Documentation and feature updates |
| Base | v3.8.0 (M9: Server Implementation) |
| Status | In progress |
v3.9.0 does not introduce a new architectural milestone. Instead it
focuses on:
- **Documentation completeness** — filling gaps in existing guides,
correcting inaccuracies, and adding missing examples
- **Feature refinements** — incremental improvements to features delivered
in earlier milestones
- **Developer experience** — improved error messages, CLI usability, and
configuration ergonomics
- **Quality improvements** — additional test coverage, bug fixes, and
stability improvements
---
## Documentation Improvements
### New and Updated Guides
v3.9.0 adds and updates documentation across the platform:
- **Server Guide** (`docs/server.md`) — comprehensive documentation for the
v3.8.0 Server Implementation covering the A2A JSON-RPC 2.0 protocol, all
transport modes (stdio local, HTTP server, external A2A agent), Agent Card
discovery, `_cleveragents/` extension method catalog, authentication and
RBAC, entity sync protocol, multi-device shared namespaces, PostgreSQL
backend, Docker and Kubernetes/Helm deployment, and CLI commands for server
management.
- **v3.9.0 Updates** (`docs/v390-updates.md`): Release notes and feature
refinement documentation for v3.9.0 covering documentation improvements,
A2A protocol enhancements, server mode improvements, entity sync
refinements, CLI improvements, bug fixes, and quality improvements.
- **MkDocs navigation**: Added "Server Guide (v3.8.0)" and "v3.9.0 Updates"
entries to the MkDocs navigation.
### Corrections and Clarifications
- Clarified the distinction between `local/` namespace (client-only, never
synced) and server namespaces (`<username>/`, `<orgname>/`)
- Updated A2A operation table to reflect the full set of standard operations
and `_cleveragents/` extension methods
- Corrected error code documentation to match the JSON-RPC 2.0 integer code
scheme used by the A2A standard
- Clarified LangGraph Platform RemoteGraph integration — each actor type
deploys as a separate RemoteGraph, not a single shared deployment
---
## Feature Refinements
### A2A Protocol
- Improved `A2aLocalFacade` dispatch error messages to include the
unsupported method name and a list of supported methods
- Added `A2A-Version` header validation on incoming requests with a clear
error response when the version is unsupported
- Extended `A2aEventQueue` with a `drain()` method for graceful shutdown
### Server Mode
- Server health check endpoint (`/health`) now returns structured JSON
including database connectivity status and LangGraph Platform reachability
- Improved startup error messages when required environment variables are
missing
- Added `--dry-run` flag to `agents server start` for configuration
validation without starting the server
### Entity Sync
- `_cleveragents/sync/status` now returns a structured diff showing added,
modified, and deleted entities per namespace
- Auto-sync now backs off exponentially on repeated failures instead of
retrying at a fixed interval
- Added `--force` flag to `agents server sync pull` to overwrite local
entities even when the local version is newer
### CLI Improvements
- `agents server info` now displays the connected server's Agent Card
summary including supported extensions and security schemes
- `agents namespace list` now shows the user's role in each namespace
- `agents server token list` now shows token expiry dates and last-used
timestamps
### Configuration
- Server configuration now supports environment variable interpolation in
YAML values (e.g., `url: ${DATABASE_URL}`)
- Added `server.tls.verify` option to disable TLS certificate verification
for development environments (default: `true`)
- Configuration validation now reports all errors at startup rather than
failing on the first error
---
## Bug Fixes
- Fixed `_cleveragents/sync/pull` failing silently when the server namespace
contained entities with names that conflict with local `local/` namespace
entries
- Fixed `agents server connect` not persisting the connection token across
CLI invocations
- Fixed `TaskStatusUpdateEvent` not being emitted when a task transitions
from `input-required` back to `working`
- Fixed namespace ACL changes not taking effect until the next server restart
- Fixed `agents server token revoke` not invalidating active sessions using
the revoked token
---
## Quality Improvements
### Test Coverage
- Added integration tests for the full A2A HTTP transport round-trip
(client → server → LangGraph Platform → client)
- Added tests for all `_cleveragents/sync/*` extension methods including
conflict detection and resolution
- Added tests for namespace ACL enforcement across all extension methods
- Added tests for the `input-required` → `working` task state transition
### Stability
- Improved connection pool management for PostgreSQL under high concurrency
- Fixed memory leak in `A2aEventQueue` when subscribers disconnect without
calling `close()`
- Improved graceful shutdown: the server now waits for in-flight tasks to
complete (up to a configurable timeout) before stopping
---
## Migration Notes
### From v3.8.0
v3.9.0 is backward compatible with v3.8.0. No migration steps are
required for existing deployments.
**Configuration changes (optional):**
- The new `server.tls.verify` option defaults to `true` (existing behavior).
Set to `false` only in development environments.
- The new `server.sync.backoff_max` option controls the maximum backoff
interval for auto-sync retries (default: 3600 seconds).
**CLI changes:**
- `agents server sync status` output format has changed to a structured diff.
Scripts parsing the previous plain-text output should be updated.
---
## Related Documentation
- [Server Guide (v3.8.0)](server.md)
- [ADR-047: A2A Standard Adoption](adr/ADR-047-acp-standard-adoption.md)
- [ADR-048: Server Application Architecture](adr/ADR-048-server-application-architecture.md)
- [A2A Protocol API Reference](api/a2a.md)
- [Architecture Overview](architecture.md)
- [CHANGELOG](../CHANGELOG.md)
mkdocs.yml
+2
View File
@@ -44,6 +44,8 @@ nav:
- Documentation Writer: development/docs-writer.md
- Implementation Timeline: timeline.md
- FAQ: faq.md
- Server Guide (v3.8.0): server.md
- v3.9.0 Updates: v390-updates.md
- Reference: reference/
- Architecture Decision Records (ADRs):
- Overview: adr/index.md