cleveragents/cleveragents-core

Fork 3

test(a2a): add comprehensive BDD coverage for A2aLocalFacade — 18% → ≥97% #2307

New issue

Open

opened 2026-04-03 13:39:27 +00:00 by freemo · 2 comments

freemo commented

2026-04-03 13:39:27 +00:00

Owner

Metadata

Branch: test/a2a-facade-coverage
Commit Message: test(a2a): add comprehensive BDD coverage for A2aLocalFacade
Milestone: v3.7.0
Parent Epic: #933

Background and Context

src/cleveragents/a2a/facade.py is the sole local-mode dispatch layer between all CLI/TUI/IDE clients and the application services. Per the specification (ADR-047, ADR-048), A2aLocalFacade routes every A2A operation — plan lifecycle, registry queries, session management, context, health, sync, and namespace operations — to the appropriate service in local mode.

Despite being a critical architectural boundary, the file currently has only 18% test coverage (62 of 344 executable lines covered), with 282 lines completely untested. This violates the project-wide ≥97% coverage threshold enforced in CI.

Current Behaviour

Running nox -s coverage_report (or inspecting build/coverage.json) shows:

src/cleveragents/a2a/facade.py   18%   282 missing lines

The following areas have zero coverage:

Area	Lines	Description
TYPE_CHECKING imports	L40–48	Typed service imports used for annotations
Constructor + service accessors	L124–155	`__init__`, `_session_service`, `_plan_lifecycle_service`, `_tool_registry`, `_resource_registry_service`, `_event_queue`
`dispatch()` — success path	L168–183	Full request routing, timing, logging, and `A2aResponse` construction
`dispatch()` — error path	L185–201	`A2aOperationNotFoundError` re-raise, domain error mapping, error response
`register_service()`	L207–213	Service registration, handler-map invalidation
`list_operations()`	L217	Returns supported operation list
`_route_operation()`	L229–235	Handler lookup and invocation
`_handlers()` (cache build)	L243–298	Full dispatch dict construction (all 40+ operations)
Session handlers	L310–365	`_handle_session_create` (existing-id path, new-session path), `_handle_session_close` (all branches), `_cleanup_session_devcontainers` (success, empty-id, exception paths)
Plan lifecycle handlers	L373–433	`_handle_plan_create`, `_handle_plan_execute`, `_handle_plan_status`, `_handle_plan_diff`, `_handle_plan_apply` — all wired-service paths
Registry handlers	L440–462	`_handle_registry_list_tools` (wired), `_handle_registry_list_resources` (wired)
Context handler	L473–476	`_handle_context_get` stub response
Event handler	L484–492	`_handle_event_subscribe` — no-queue stub and wired-queue paths
Extension plan handlers	L499–576	`_handle_plan_cancel`, `_handle_plan_tree`, `_handle_plan_explain`, `_handle_plan_correct`, `_handle_plan_artifacts`, `_handle_plan_prompt`, `_handle_plan_rollback`, `_handle_plan_list` — all paths
Stub handlers	L584–615	`_handle_registry_list_stub`, `_handle_context_stub`, `_handle_health_check`, `_handle_diagnostics_run`, `_handle_sync_stub`, `_handle_namespace_stub`

Expected Behaviour

All branches and paths in A2aLocalFacade are exercised by BDD scenarios. Coverage for src/cleveragents/a2a/facade.py meets or exceeds 97%.

Acceptance Criteria

BDD feature file(s) cover every handler method in A2aLocalFacade, including both the stub (no-service) and wired-service paths for each operation.
The dispatch() method's success path, A2aOperationNotFoundError re-raise path, and domain-error-mapping path are all exercised.
register_service() and list_operations() are covered.
_cleanup_session_devcontainers() is covered: empty session_id early-return, successful cleanup with stopped containers, and exception-swallowing path.
_handle_event_subscribe() is covered for both the no-queue stub and the wired-queue path.
All extension operation handlers (_cleveragents/plan/*, _cleveragents/registry/*, _cleveragents/context/*, _cleveragents/health/*, _cleveragents/sync/*, _cleveragents/namespace/*) are covered.
nox -s coverage_report reports ≥97% for src/cleveragents/a2a/facade.py.
All nox default sessions pass without errors.

Supporting Information

Specification: ADR-047 (A2A standard adoption), ADR-048 (server/client architecture) — docs/specification.md
Parent Epic: #933 (A2A Protocol Compliance)
Related coverage issues: #2291 (a2a/errors.py), #2280 (a2a/clients.py), #2302 (a2a/events.py)
Existing partial coverage feature files: features/a2a_facade_coverage.feature, features/a2a_facade_coverage_boost.feature — these cover some paths but leave 82% of the file untested.
Coverage data source: build/coverage.json (last full CI run)

Subtasks

Audit features/a2a_facade_coverage.feature and features/a2a_facade_coverage_boost.feature to identify which lines they already cover
Write BDD scenarios for dispatch() — success path (with and without service), A2aOperationNotFoundError re-raise, and domain error mapping
Write BDD scenarios for register_service() — valid registration and handler-map invalidation
Write BDD scenarios for list_operations() — returns full operation list
Write BDD scenarios for _handlers() cache — first build and cache-hit on second call
Write BDD scenarios for _handle_session_create — existing-id idempotent path, no-service stub path, wired-service new-session path
Write BDD scenarios for _handle_session_close — no-service path, wired-service path, empty-session-id error path
Write BDD scenarios for _cleanup_session_devcontainers — empty-id early return, successful cleanup with stopped containers, exception-swallowing path
Write BDD scenarios for all plan lifecycle handlers (_handle_plan_create, _handle_plan_execute, _handle_plan_status, _handle_plan_diff, _handle_plan_apply) — wired-service paths
Write BDD scenarios for _handle_registry_list_tools and _handle_registry_list_resources — wired-service paths
Write BDD scenarios for _handle_context_get stub response
Write BDD scenarios for _handle_event_subscribe — no-queue stub and wired-queue paths
Write BDD scenarios for all extension plan handlers (_handle_plan_cancel, _handle_plan_tree, _handle_plan_explain, _handle_plan_correct, _handle_plan_artifacts, _handle_plan_prompt, _handle_plan_rollback, _handle_plan_list)
Write BDD scenarios for all stub handlers (_handle_registry_list_stub, _handle_context_stub, _handle_health_check, _handle_diagnostics_run, _handle_sync_stub, _handle_namespace_stub)
Implement step definitions for any new scenarios not covered by existing step files
Verify coverage ≥97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (test(a2a): add comprehensive BDD coverage for A2aLocalFacade), followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (test/a2a-facade-coverage).
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
nox -s coverage_report confirms src/cleveragents/a2a/facade.py ≥97%.
All nox stages pass.
Coverage ≥97% project-wide.

Automated by CleverAgents Bot
Supervisor: Unknown | Agent: ca-new-issue-creator

## Metadata - **Branch**: `test/a2a-facade-coverage` - **Commit Message**: `test(a2a): add comprehensive BDD coverage for A2aLocalFacade` - **Milestone**: v3.7.0 - **Parent Epic**: #933 ## Background and Context `src/cleveragents/a2a/facade.py` is the **sole local-mode dispatch layer** between all CLI/TUI/IDE clients and the application services. Per the specification (ADR-047, ADR-048), `A2aLocalFacade` routes every A2A operation — plan lifecycle, registry queries, session management, context, health, sync, and namespace operations — to the appropriate service in local mode. Despite being a critical architectural boundary, the file currently has only **18% test coverage** (62 of 344 executable lines covered), with **282 lines completely untested**. This violates the project-wide ≥97% coverage threshold enforced in CI. ## Current Behaviour Running `nox -s coverage_report` (or inspecting `build/coverage.json`) shows: ``` src/cleveragents/a2a/facade.py 18% 282 missing lines ``` The following areas have **zero coverage**: | Area | Lines | Description | |---|---|---| | TYPE_CHECKING imports | L40–48 | Typed service imports used for annotations | | Constructor + service accessors | L124–155 | `__init__`, `_session_service`, `_plan_lifecycle_service`, `_tool_registry`, `_resource_registry_service`, `_event_queue` | | `dispatch()` — success path | L168–183 | Full request routing, timing, logging, and `A2aResponse` construction | | `dispatch()` — error path | L185–201 | `A2aOperationNotFoundError` re-raise, domain error mapping, error response | | `register_service()` | L207–213 | Service registration, handler-map invalidation | | `list_operations()` | L217 | Returns supported operation list | | `_route_operation()` | L229–235 | Handler lookup and invocation | | `_handlers()` (cache build) | L243–298 | Full dispatch dict construction (all 40+ operations) | | Session handlers | L310–365 | `_handle_session_create` (existing-id path, new-session path), `_handle_session_close` (all branches), `_cleanup_session_devcontainers` (success, empty-id, exception paths) | | Plan lifecycle handlers | L373–433 | `_handle_plan_create`, `_handle_plan_execute`, `_handle_plan_status`, `_handle_plan_diff`, `_handle_plan_apply` — all wired-service paths | | Registry handlers | L440–462 | `_handle_registry_list_tools` (wired), `_handle_registry_list_resources` (wired) | | Context handler | L473–476 | `_handle_context_get` stub response | | Event handler | L484–492 | `_handle_event_subscribe` — no-queue stub and wired-queue paths | | Extension plan handlers | L499–576 | `_handle_plan_cancel`, `_handle_plan_tree`, `_handle_plan_explain`, `_handle_plan_correct`, `_handle_plan_artifacts`, `_handle_plan_prompt`, `_handle_plan_rollback`, `_handle_plan_list` — all paths | | Stub handlers | L584–615 | `_handle_registry_list_stub`, `_handle_context_stub`, `_handle_health_check`, `_handle_diagnostics_run`, `_handle_sync_stub`, `_handle_namespace_stub` | ## Expected Behaviour All branches and paths in `A2aLocalFacade` are exercised by BDD scenarios. Coverage for `src/cleveragents/a2a/facade.py` meets or exceeds **97%**. ## Acceptance Criteria - [ ] BDD feature file(s) cover every handler method in `A2aLocalFacade`, including both the stub (no-service) and wired-service paths for each operation. - [ ] The `dispatch()` method's success path, `A2aOperationNotFoundError` re-raise path, and domain-error-mapping path are all exercised. - [ ] `register_service()` and `list_operations()` are covered. - [ ] `_cleanup_session_devcontainers()` is covered: empty session_id early-return, successful cleanup with stopped containers, and exception-swallowing path. - [ ] `_handle_event_subscribe()` is covered for both the no-queue stub and the wired-queue path. - [ ] All extension operation handlers (`_cleveragents/plan/*`, `_cleveragents/registry/*`, `_cleveragents/context/*`, `_cleveragents/health/*`, `_cleveragents/sync/*`, `_cleveragents/namespace/*`) are covered. - [ ] `nox -s coverage_report` reports ≥97% for `src/cleveragents/a2a/facade.py`. - [ ] All nox default sessions pass without errors. ## Supporting Information - Specification: ADR-047 (A2A standard adoption), ADR-048 (server/client architecture) — `docs/specification.md` - Parent Epic: #933 (A2A Protocol Compliance) - Related coverage issues: #2291 (`a2a/errors.py`), #2280 (`a2a/clients.py`), #2302 (`a2a/events.py`) - Existing partial coverage feature files: `features/a2a_facade_coverage.feature`, `features/a2a_facade_coverage_boost.feature` — these cover some paths but leave 82% of the file untested. - Coverage data source: `build/coverage.json` (last full CI run) ## Subtasks - [ ] Audit `features/a2a_facade_coverage.feature` and `features/a2a_facade_coverage_boost.feature` to identify which lines they already cover - [ ] Write BDD scenarios for `dispatch()` — success path (with and without service), `A2aOperationNotFoundError` re-raise, and domain error mapping - [ ] Write BDD scenarios for `register_service()` — valid registration and handler-map invalidation - [ ] Write BDD scenarios for `list_operations()` — returns full operation list - [ ] Write BDD scenarios for `_handlers()` cache — first build and cache-hit on second call - [ ] Write BDD scenarios for `_handle_session_create` — existing-id idempotent path, no-service stub path, wired-service new-session path - [ ] Write BDD scenarios for `_handle_session_close` — no-service path, wired-service path, empty-session-id error path - [ ] Write BDD scenarios for `_cleanup_session_devcontainers` — empty-id early return, successful cleanup with stopped containers, exception-swallowing path - [ ] Write BDD scenarios for all plan lifecycle handlers (`_handle_plan_create`, `_handle_plan_execute`, `_handle_plan_status`, `_handle_plan_diff`, `_handle_plan_apply`) — wired-service paths - [ ] Write BDD scenarios for `_handle_registry_list_tools` and `_handle_registry_list_resources` — wired-service paths - [ ] Write BDD scenarios for `_handle_context_get` stub response - [ ] Write BDD scenarios for `_handle_event_subscribe` — no-queue stub and wired-queue paths - [ ] Write BDD scenarios for all extension plan handlers (`_handle_plan_cancel`, `_handle_plan_tree`, `_handle_plan_explain`, `_handle_plan_correct`, `_handle_plan_artifacts`, `_handle_plan_prompt`, `_handle_plan_rollback`, `_handle_plan_list`) - [ ] Write BDD scenarios for all stub handlers (`_handle_registry_list_stub`, `_handle_context_stub`, `_handle_health_check`, `_handle_diagnostics_run`, `_handle_sync_stub`, `_handle_namespace_stub`) - [ ] Implement step definitions for any new scenarios not covered by existing step files - [ ] Verify coverage ≥97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`test(a2a): add comprehensive BDD coverage for A2aLocalFacade`), followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`test/a2a-facade-coverage`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - `nox -s coverage_report` confirms `src/cleveragents/a2a/facade.py` ≥97%. - All nox stages pass. - Coverage ≥97% project-wide. --- **Automated by CleverAgents Bot** Supervisor: Unknown | Agent: ca-new-issue-creator

freemo added this to the v3.7.0 milestone

2026-04-03 13:41:22 +00:00

freemo commented

2026-04-03 13:42:32 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: High (confirmed) — 18% coverage on the sole local-mode dispatch layer is a critical gap. This is the most under-tested critical file in the A2A module.
Milestone: v3.7.0 (confirmed — A2A Protocol Compliance Epic #933)
MoSCoW: Should Have — A2aLocalFacade is the central dispatch layer for all local-mode operations. 18% coverage means 82% of the dispatch logic is untested. This is a significant quality risk.
Parent Epic: #933 (confirmed correct)

This is a large scope issue (282 uncovered lines, ~15 handler methods) but critically important for A2A protocol reliability.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: High (confirmed) — 18% coverage on the sole local-mode dispatch layer is a critical gap. This is the most under-tested critical file in the A2A module. - **Milestone**: v3.7.0 (confirmed — A2A Protocol Compliance Epic #933) - **MoSCoW**: Should Have — `A2aLocalFacade` is the central dispatch layer for all local-mode operations. 18% coverage means 82% of the dispatch logic is untested. This is a significant quality risk. - **Parent Epic**: #933 (confirmed correct) This is a large scope issue (282 uncovered lines, ~15 handler methods) but critically important for A2A protocol reliability. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added a new dependency

2026-04-03 13:44:35 +00:00

#933 Epic: A2A Protocol Compliance — JSON-RPC 2.0 Framing, Standard Operations, and Extension Methods

freemo self-assigned this

2026-04-03 16:57:57 +00:00

freemo referenced this issue

2026-04-03 19:45:40 +00:00

Task: Autonomous build progress report — v3.7.0 Production Push — 2026-04-03 #2436

freemo commented

2026-04-03 19:47:53 +00:00

Author

Owner

Starting implementation on branch test/a2a-facade-coverage.

Resume status: Fresh run (branch existed but had no commits beyond master).

Plan: 17 subtasks analyzed. Grouping into parallel waves:

Wave 1 (independent): Subtasks 1 (audit), 2 (dispatch), 3 (register_service), 4 (list_operations), 5 (_handlers cache), 11 (_handle_context_get), 14 (stub handlers)
Wave 2 (depends on Wave 1 audit): Subtasks 6 (session_create), 7 (session_close), 8 (cleanup_devcontainers), 9 (plan lifecycle), 10 (registry), 12 (event_subscribe), 13 (extension plan handlers)
Wave 3: Subtask 15 (step definitions for new scenarios)
Wave 4: Subtasks 16 (verify coverage), 17 (run nox)

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

Starting implementation on branch `test/a2a-facade-coverage`. **Resume status**: Fresh run (branch existed but had no commits beyond master). **Plan**: 17 subtasks analyzed. Grouping into parallel waves: - **Wave 1** (independent): Subtasks 1 (audit), 2 (dispatch), 3 (register_service), 4 (list_operations), 5 (_handlers cache), 11 (_handle_context_get), 14 (stub handlers) - **Wave 2** (depends on Wave 1 audit): Subtasks 6 (session_create), 7 (session_close), 8 (cleanup_devcontainers), 9 (plan lifecycle), 10 (registry), 12 (event_subscribe), 13 (extension plan handlers) - **Wave 3**: Subtask 15 (step definitions for new scenarios) - **Wave 4**: Subtasks 16 (verify coverage), 17 (run nox) --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker