feat(a2a): implement _cleveragents/ extension method routing #876

Open
opened 2026-03-13 22:59:24 +00:00 by freemo · 1 comment
Owner

Metadata

  • Commit Message: feat(a2a): implement _cleveragents/ extension method routing
  • Branch: feature/m6-a2a-extension-methods

Background and Context

The specification defines 6 families of CleverAgents-specific A2A extension methods prefixed with _cleveragents/: plan lifecycle (_cleveragents/plan/*), registry CRUD (_cleveragents/registry/*), context management (_cleveragents/context/*), entity sync (_cleveragents/sync/*), namespace management (_cleveragents/namespace/*), and diagnostics (_cleveragents/health/*).

Currently, the A2aLocalFacade uses a completely proprietary operation vocabulary (e.g., session.create, plan.create, registry.list_tools) that does not match the A2A extension method naming convention. A grep for _cleveragents/ across the entire codebase returns zero results. The facade must be refactored to use the spec-aligned method names.

Expected Behavior

The A2aLocalFacade and future A2aHttpTransport must route these extension methods to the appropriate application services:

  • _cleveragents/plan/use, _cleveragents/plan/execute, _cleveragents/plan/apply, _cleveragents/plan/status, etc.
  • _cleveragents/registry/tools/list, _cleveragents/registry/resources/list, etc.
  • _cleveragents/context/get, _cleveragents/context/set, etc.
  • _cleveragents/sync/push, _cleveragents/sync/pull, etc.
  • _cleveragents/namespace/list, _cleveragents/namespace/resolve, etc.
  • _cleveragents/health/check, _cleveragents/health/diagnostics, etc.

Acceptance Criteria

  • A2aLocalFacade.dispatch() routes _cleveragents/-prefixed methods to correct services
  • All 6 extension method families have at least their core operations routed
  • Method routing table is documented and maintainable
  • Old proprietary operation names are deprecated with backward compatibility
  • Extension methods are declared in the Agent Card (when #867 is implemented)

Subtasks

  • Define complete method routing table for all 6 families
  • Refactor A2aLocalFacade.dispatch() to support _cleveragents/ prefix routing
  • Implement routing for _cleveragents/plan/* methods
  • Implement routing for _cleveragents/registry/* methods
  • Implement routing for _cleveragents/context/* methods
  • Implement routing for _cleveragents/health/* methods
  • Stub routing for _cleveragents/sync/* and _cleveragents/namespace/*
  • Deprecate old proprietary operation names
  • Tests (Behave): Add scenarios for each extension method family
  • 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, 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.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
## Metadata - **Commit Message**: `feat(a2a): implement _cleveragents/ extension method routing` - **Branch**: `feature/m6-a2a-extension-methods` ## Background and Context The specification defines 6 families of CleverAgents-specific A2A extension methods prefixed with `_cleveragents/`: plan lifecycle (`_cleveragents/plan/*`), registry CRUD (`_cleveragents/registry/*`), context management (`_cleveragents/context/*`), entity sync (`_cleveragents/sync/*`), namespace management (`_cleveragents/namespace/*`), and diagnostics (`_cleveragents/health/*`). Currently, the `A2aLocalFacade` uses a completely proprietary operation vocabulary (e.g., `session.create`, `plan.create`, `registry.list_tools`) that does not match the A2A extension method naming convention. A grep for `_cleveragents/` across the entire codebase returns zero results. The facade must be refactored to use the spec-aligned method names. ## Expected Behavior The `A2aLocalFacade` and future `A2aHttpTransport` must route these extension methods to the appropriate application services: - `_cleveragents/plan/use`, `_cleveragents/plan/execute`, `_cleveragents/plan/apply`, `_cleveragents/plan/status`, etc. - `_cleveragents/registry/tools/list`, `_cleveragents/registry/resources/list`, etc. - `_cleveragents/context/get`, `_cleveragents/context/set`, etc. - `_cleveragents/sync/push`, `_cleveragents/sync/pull`, etc. - `_cleveragents/namespace/list`, `_cleveragents/namespace/resolve`, etc. - `_cleveragents/health/check`, `_cleveragents/health/diagnostics`, etc. ## Acceptance Criteria - [ ] `A2aLocalFacade.dispatch()` routes `_cleveragents/`-prefixed methods to correct services - [ ] All 6 extension method families have at least their core operations routed - [ ] Method routing table is documented and maintainable - [ ] Old proprietary operation names are deprecated with backward compatibility - [ ] Extension methods are declared in the Agent Card (when #867 is implemented) ## Subtasks - [ ] Define complete method routing table for all 6 families - [ ] Refactor `A2aLocalFacade.dispatch()` to support `_cleveragents/` prefix routing - [ ] Implement routing for `_cleveragents/plan/*` methods - [ ] Implement routing for `_cleveragents/registry/*` methods - [ ] Implement routing for `_cleveragents/context/*` methods - [ ] Implement routing for `_cleveragents/health/*` methods - [ ] Stub routing for `_cleveragents/sync/*` and `_cleveragents/namespace/*` - [ ] Deprecate old proprietary operation names - [ ] Tests (Behave): Add scenarios for each extension method family - [ ] 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, 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. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.
freemo added this to the v3.6.0 milestone 2026-03-13 23:00:13 +00:00
freemo self-assigned this 2026-03-14 04:27:29 +00:00
Author
Owner

Implementation Notes — Day 37

Design: Flat handler map with dual naming

Used a single flat handler dict containing both _cleveragents/-prefixed extension methods and legacy dot-notation names. Both point to the same handler functions, avoiding code duplication. The flat approach was chosen over hierarchical prefix dispatch for simplicity and debuggability.

Key Code Locations

  • _EXTENSION_OPERATIONS / _LEGACY_OPERATIONSsrc/cleveragents/a2a/facade.py (commit ce5af7b8)
  • _handlers() method — same file, expanded routing table
  • New handler stubs — same file (plan_cancel, plan_tree, plan_explain, plan_correct, plan_artifacts, plan_prompt, plan_rollback, plan_list, registry_list_stub, context_stub, health_check, diagnostics_run, sync_stub, namespace_stub)

Quality Gates

  • Lint: | Typecheck: 0 errors | Unit tests: 387 features, 11117 scenarios | Integration: all passed | Coverage: 97%
## Implementation Notes — Day 37 ### Design: Flat handler map with dual naming Used a single flat handler dict containing both `_cleveragents/`-prefixed extension methods and legacy dot-notation names. Both point to the same handler functions, avoiding code duplication. The flat approach was chosen over hierarchical prefix dispatch for simplicity and debuggability. ### Key Code Locations - `_EXTENSION_OPERATIONS` / `_LEGACY_OPERATIONS` — `src/cleveragents/a2a/facade.py` (commit ce5af7b8) - `_handlers()` method — same file, expanded routing table - New handler stubs — same file (plan_cancel, plan_tree, plan_explain, plan_correct, plan_artifacts, plan_prompt, plan_rollback, plan_list, registry_list_stub, context_stub, health_check, diagnostics_run, sync_stub, namespace_stub) ### Quality Gates - Lint: ✅ | Typecheck: ✅ 0 errors | Unit tests: ✅ 387 features, 11117 scenarios | Integration: ✅ all passed | Coverage: ✅ 97%
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#876
No description provided.