feat(agent-mesh): legacy ApprovalHandler to protocol compatibility adapter (ADR-0030 step 3)

[Carlos Hernandez (carloshvp)]

Summary

Step 3 of the ADR-0030 migration: a reusable compatibility adapter so existing synchronous ApprovalHandler implementations (callback, console, webhook, auto-reject) drive the action-bound approval protocol.

Step 2 (#3076) bridged the legacy handler into the coordinator inline inside govern(). This PR extracts that into governance/approval_bridge.py, so every approval path (Agent OS escalation, MCP gateway, framework adapters) can reuse one handler-to-protocol mapping instead of reimplementing it.

What changed

• New governance/approval_bridge.py:
  • LegacyHandlerAdapter(handler, *, approver_kind=HUMAN, identity_assurance="approval-handler").
  • .collect(coordinator, request, legacy_request, *, stage_index=0) -> AdapterResult: asks the handler, maps approved / approver / reason onto one submit_entry, fail-closed on ApprovalProtocolError (unpermitted identity, expired request, unknown stage).
  • AdapterResult(approval, entry, error) with a .submitted convenience.
• govern.py: the require_approval coordinator path now uses the adapter; behavior is unchanged (net -17 lines there).
• The approval_protocol foundation package is untouched and never depends on the bridge.

Tests

tests/test_approval_bridge.py (6 tests): approve submits an ALLOW entry and resolves allow; reject submits DENY; an unpermitted identity fails closed (entry=None, error set, vote still reported); an expired request fails closed; reason and approver propagate; custom approver kind and assurance. Existing govern coordinator and approval suites still pass (85 total).

Scope

Single-stage via the synchronous handler, same as step 2. Multi-stage orchestration and async / webhook transport remain steps 4 and beyond.

Refs #2478. ADR-0030 step 3.

[github-actions]

🤖 AI Agent: test-generator — `agentmesh/governance/approval_bridge.py`

AI-generated review output. Treat it as untrusted analysis and verify before acting.

agentmesh/governance/approval_bridge.py

• test_collect_with_invalid_stage_index -- Validate behavior when an invalid stage_index is passed to collect.
• test_collect_with_missing_approval_request_id -- Test handling of missing or invalid approval_request_id in collect.
• test_collect_with_unexpected_handler_exception -- Ensure collect handles unexpected exceptions from the handler gracefully.

agentmesh/governance/govern.py

• test_handle_approval_with_adapter_error -- Verify behavior when LegacyHandlerAdapter.collect returns an error.
• test_handle_approval_with_unexpected_adapter_exception -- Ensure _handle_approval_via_coordinator handles unexpected exceptions from the adapter.

[github-actions]

🤖 AI Agent: code-reviewer — Action Items:

AI-generated review output. Treat it as untrusted analysis and verify before acting.

TL;DR: 0 blockers, 1 warning. The PR introduces a compatibility adapter for legacy approval handlers, which is well-implemented and tested, but the error messages could be more structured for better debugging.

#	Sev	Issue	Where
1	Warn	Error messages are plain strings, which may hinder debugging.	approval_bridge.py

Action Items:

None.

Warnings:

#	Issue	Where	Fine as follow-up PR?
1	Error messages in AdapterResult.error are plain strings. Consider using structured error objects for better debugging and downstream handling.	approval_bridge.py	Yes

[github-actions]

🤖 AI Agent: docs-sync-checker — Docs Sync

AI-generated review output. Treat it as untrusted analysis and verify before acting.

Docs Sync

Documentation is in sync.

[github-actions]

🤖 AI Agent: security-scanner — View details

AI-generated review output. Treat it as untrusted analysis and verify before acting.

No security issues found.

[github-actions]

🤖 AI Agent: breaking-change-detector — API Compatibility

AI-generated review output. Treat it as untrusted analysis and verify before acting.

API Compatibility

Severity	Change	Impact
High	ApprovalHandler.request_approval is no longer called directly in govern.py. Instead, it is wrapped by LegacyHandlerAdapter.collect.	Existing code or extensions relying on direct calls to ApprovalHandler.request_approval in govern.py may break.
High	The ApprovalProtocolError exception is now handled within LegacyHandlerAdapter.collect, and no longer propagates directly from govern.py.	Code relying on catching ApprovalProtocolError directly in govern.py will no longer function as expected.
Medium	The ApprovalHandler interface is now indirectly used via LegacyHandlerAdapter.	Custom implementations of ApprovalHandler may require testing to ensure compatibility with the new adapter.

[github-actions]

PR Review Summary

Check	Status	Details
🔍 Code Review	⚠️ Missing	No current-run comment
🛡️ Security Scan	⚠️ Missing	No current-run comment
🔄 Breaking Changes	⚠️ Missing	No current-run comment
📝 Docs Sync	⚠️ Missing	No current-run comment
🧪 Test Coverage	⚠️ Missing	No current-run comment

Verdict: ⚠️ AI review incomplete; ready for human review

AI review comments are untrusted advisory output. The summary reports workflow-generated completion status only, not model-authored pass/fail claims.

[Imran Siddique (imran-siddique)]

Clean extraction of the inline approval bridge into a reusable LegacyHandlerAdapter. Fail-closed design is correct: any ApprovalProtocolError from submit_entry returns entry=None with an error string, letting callers deny without special-casing. The govern.py diff confirms the adapter slots in cleanly. 122-line test file covers the key paths. LGTM.