UAT: ACP backward compatibility layer is missing — acp/ directory is empty with no migration path for legacy ACP clients #4094

New issue

Open

opened 2026-04-06 10:18:11 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 10:18:11 +00:00

Owner

Metadata

Branch: fix/acp-backward-compatibility-layer
Commit Message: fix(acp): add backward compatibility layer and migration path for legacy ACP clients
Milestone: (backlog — see note below)
Parent Epic: #933

Bug Report

Feature Area: API Versioning and Backward Compatibility
Severity: Medium
Found by: UAT Testing (automated)

Summary

The specification states that A2A is the successor to the deprecated Agent Client Protocol (ACP) and "retains backward compatibility with ACP's JSON-RPC 2.0 foundation." However, the src/cleveragents/acp/ directory exists but is completely empty (contains only __pycache__). There is no migration path, no compatibility shim, and no documentation for ACP clients that need to migrate to A2A.

Expected Behavior

Per the specification:

A2A is the successor to ACP
A2A retains backward compatibility with ACP's JSON-RPC 2.0 foundation
There should be a documented migration path for ACP clients

The acp/ directory should either:

Contain a compatibility layer that maps ACP operations to A2A operations, OR
Contain documentation/migration guide explaining how ACP clients should migrate, OR
Be removed if ACP compatibility is intentionally not supported (with a clear statement in the spec)

Actual Behavior

src/cleveragents/acp/
└── (empty — only __pycache__)

The acp/ directory is a stub with no content. The a2a/__init__.py docstring mentions "ACP" but only in passing:

"In local mode the :class:A2aLocalFacade maps A2A operation names to direct Python method calls..."

There is no:

ACP-to-A2A operation mapping
ACP client compatibility shim
Migration documentation
Deprecation notice with timeline

Impact

ACP clients have no documented migration path to A2A
The "backward compatibility" claim in the spec is not backed by any implementation
The empty acp/ directory creates confusion about whether ACP support is planned or abandoned
Clients using legacy ACP operation names (e.g., session.create, plan.create) are handled by the _LEGACY_OPERATIONS list in facade.py, but this is not documented as the ACP compatibility layer

Code Location

src/cleveragents/acp/ — empty directory (should contain compatibility layer or be removed)
src/cleveragents/a2a/facade.py — _LEGACY_OPERATIONS list (undocumented ACP compatibility)
docs/specification.md — claims backward compatibility with ACP

Note on Partial Compatibility

The A2aLocalFacade in facade.py does maintain a _LEGACY_OPERATIONS list:

_LEGACY_OPERATIONS: list[str] = [
    "session.create",
    "session.close",
    "plan.create",
    "plan.execute",
    ...
]

These legacy operation names appear to be the ACP compatibility layer, but they are:

Not documented as ACP compatibility
Not in the acp/ package
Marked as "deprecated" without a removal timeline

Subtasks

Audit _LEGACY_OPERATIONS in a2a/facade.py and formally document as the ACP compatibility layer
Create src/cleveragents/acp/__init__.py with a compatibility shim or clear migration guide
Add a deprecation notice with a concrete removal timeline for legacy ACP operation names
Document the ACP-to-A2A migration path (either in the acp/ package docstring or in docs/)
Update docs/specification.md to clarify the exact scope of ACP backward compatibility
Tests (pytest/Behave): verify legacy ACP operation names still route correctly through the A2A facade
Run nox (all default sessions), fix any errors
Verify coverage ≥ 97% via nox -s coverage_report

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 (fix(acp): add backward compatibility layer and migration path for legacy ACP clients), 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 (fix/acp-backward-compatibility-layer).
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass.
Coverage ≥ 97%.

Backlog note: This issue was discovered during autonomous operation
on milestone v3.7.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

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

## Metadata - **Branch**: `fix/acp-backward-compatibility-layer` - **Commit Message**: `fix(acp): add backward compatibility layer and migration path for legacy ACP clients` - **Milestone**: *(backlog — see note below)* - **Parent Epic**: #933 ## Bug Report **Feature Area:** API Versioning and Backward Compatibility **Severity:** Medium **Found by:** UAT Testing (automated) ### Summary The specification states that A2A is the successor to the deprecated Agent Client Protocol (ACP) and "retains backward compatibility with ACP's JSON-RPC 2.0 foundation." However, the `src/cleveragents/acp/` directory exists but is completely empty (contains only `__pycache__`). There is no migration path, no compatibility shim, and no documentation for ACP clients that need to migrate to A2A. ### Expected Behavior Per the specification: - A2A is the successor to ACP - A2A retains backward compatibility with ACP's JSON-RPC 2.0 foundation - There should be a documented migration path for ACP clients The `acp/` directory should either: 1. Contain a compatibility layer that maps ACP operations to A2A operations, OR 2. Contain documentation/migration guide explaining how ACP clients should migrate, OR 3. Be removed if ACP compatibility is intentionally not supported (with a clear statement in the spec) ### Actual Behavior ``` src/cleveragents/acp/ └── (empty — only __pycache__) ``` The `acp/` directory is a stub with no content. The `a2a/__init__.py` docstring mentions "ACP" but only in passing: > "In **local mode** the :class:`A2aLocalFacade` maps A2A operation names to direct Python method calls..." There is no: - ACP-to-A2A operation mapping - ACP client compatibility shim - Migration documentation - Deprecation notice with timeline ### Impact - ACP clients have no documented migration path to A2A - The "backward compatibility" claim in the spec is not backed by any implementation - The empty `acp/` directory creates confusion about whether ACP support is planned or abandoned - Clients using legacy ACP operation names (e.g., `session.create`, `plan.create`) are handled by the `_LEGACY_OPERATIONS` list in `facade.py`, but this is not documented as the ACP compatibility layer ### Code Location - `src/cleveragents/acp/` — empty directory (should contain compatibility layer or be removed) - `src/cleveragents/a2a/facade.py` — `_LEGACY_OPERATIONS` list (undocumented ACP compatibility) - `docs/specification.md` — claims backward compatibility with ACP ### Note on Partial Compatibility The `A2aLocalFacade` in `facade.py` does maintain a `_LEGACY_OPERATIONS` list: ```python _LEGACY_OPERATIONS: list[str] = [ "session.create", "session.close", "plan.create", "plan.execute", ... ] ``` These legacy operation names appear to be the ACP compatibility layer, but they are: 1. Not documented as ACP compatibility 2. Not in the `acp/` package 3. Marked as "deprecated" without a removal timeline ## Subtasks - [ ] Audit `_LEGACY_OPERATIONS` in `a2a/facade.py` and formally document as the ACP compatibility layer - [ ] Create `src/cleveragents/acp/__init__.py` with a compatibility shim or clear migration guide - [ ] Add a deprecation notice with a concrete removal timeline for legacy ACP operation names - [ ] Document the ACP-to-A2A migration path (either in the `acp/` package docstring or in `docs/`) - [ ] Update `docs/specification.md` to clarify the exact scope of ACP backward compatibility - [ ] Tests (pytest/Behave): verify legacy ACP operation names still route correctly through the A2A facade - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage ≥ 97% via `nox -s coverage_report` ## 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 (`fix(acp): add backward compatibility layer and migration path for legacy ACP clients`), 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 (`fix/acp-backward-compatibility-layer`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage ≥ 97%. --- > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.7.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 10:18:35 +00:00

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

freemo added the

Points

label

2026-04-06 10:20:57 +00:00

freemo referenced this issue

2026-04-06 10:23:25 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775