feat(a2a): implement A2A facade session and plan lifecycle operations via CLI #9297

Open
opened 2026-04-14 14:23:58 +00:00 by HAL9000 · 1 comment
Owner

Metadata

  • Branch: feat/a2a-facade-session-plan-lifecycle
  • Commit Message: feat(a2a): implement A2A facade session and plan lifecycle operations via CLI
  • Milestone: v3.5.0

Background and Context

The v3.5.0 milestone (M6: Autonomy Hardening) requires A2A facade session and plan lifecycle operations to be fully functional via the CLI. Following the ACP → A2A protocol adoption (ADR-047) and server architecture redesign (ADR-048), the system must expose a clean A2aLocalFacade abstraction that routes all session and plan interactions through the Agent-to-Agent (A2A) protocol.

Currently, CLI commands for session management and plan execution interact directly with internal services without a standardized facade layer. This creates tight coupling, makes it difficult to support both local (stdio) and server (HTTP) transport modes, and prevents the system from scaling to multi-agent and multi-device scenarios planned in later milestones.

The A2aLocalFacade must:

  • Provide a unified interface for session lifecycle (create, list, show, close, delete)
  • Provide a unified interface for plan lifecycle via A2A (use, execute, cancel, rollback, status)
  • Support both local stdio transport (agent as subprocess) and server HTTP transport (single JSON-RPC endpoint)
  • Route agents session tell <message> through the A2A facade
  • Surface agents session list showing all active A2A sessions
  • Handle connection errors gracefully with configurable retry logic

This is a foundational requirement for the full autonomy acceptance flow (4+ levels of hierarchical decomposition, 10+ concurrent subplans) that is the primary goal of M6.


Expected Behavior

  1. Session Lifecycle via CLI

    • agents session create → creates a new A2A session, returns session ID
    • agents session list → lists all active A2A sessions with status, transport mode, and creation time
    • agents session show <id> → displays full session details including plan state and event history
    • agents session close <id> → gracefully closes the session, flushing pending events
    • agents session delete <id> → removes the session and all associated state
  2. Plan Lifecycle via A2A

    • agents plan use <plan-id> → attaches a plan to the current A2A session
    • agents plan execute → triggers plan execution through the A2A facade
    • agents plan cancel → cancels the running plan, emitting a cancellation event
    • agents plan rollback → rolls back to the last checkpoint via A2A
    • agents plan status → returns current plan status from the A2A session
  3. Transport Mode Support

    • Local mode (stdio): A2aLocalFacade spawns the agent as a subprocess and communicates via stdin/stdout JSON-RPC
    • Server mode (HTTP): A2aLocalFacade connects to a running server at a configured endpoint
  4. Error Handling

    • Connection failures trigger configurable retry with exponential backoff (default: 3 retries, 1s/2s/4s)
    • Timeout errors surface a clear CLI message with the session ID and suggested recovery command
    • Partial failures (e.g., plan cancel mid-execution) leave the session in a recoverable state

Acceptance Criteria

  • A2aLocalFacade class implemented with full session lifecycle: create_session, list_sessions, show_session, close_session, delete_session
  • Plan lifecycle methods implemented on A2aLocalFacade: use_plan, execute_plan, cancel_plan, rollback_plan, get_plan_status
  • agents session create CLI command routes through A2aLocalFacade and returns a valid session ID
  • agents session list CLI command displays all active A2A sessions with correct metadata
  • agents session show <id> CLI command returns full session details
  • agents session close <id> and agents session delete <id> CLI commands work correctly
  • agents session tell <message> routes through the A2A facade (not direct service calls)
  • agents plan use, execute, cancel, rollback, status all route through A2aLocalFacade
  • Local stdio transport mode functional: facade spawns subprocess and communicates via JSON-RPC
  • Server HTTP transport mode functional: facade connects to configured HTTP endpoint
  • Connection errors trigger retry logic with exponential backoff (3 retries by default)
  • Timeout and connection errors produce clear, actionable CLI error messages
  • Partial failures leave session in a recoverable state (no orphaned processes or locked state)
  • Unit tests cover all A2aLocalFacade methods with mocked transport
  • Integration tests cover full session + plan lifecycle in local stdio mode
  • Test coverage ≥ 97% for all new modules
  • nox passes with no regressions

Subtasks

1. Design & Architecture

  • Define A2aLocalFacade interface and method signatures
  • Document transport abstraction layer (stdio vs HTTP) in a design note or ADR update
  • Identify all existing CLI commands that need to be rerouted through the facade

2. Core Facade Implementation

  • Implement A2aLocalFacade base class with transport abstraction
  • Implement create_session / list_sessions / show_session / close_session / delete_session
  • Implement use_plan / execute_plan / cancel_plan / rollback_plan / get_plan_status
  • Implement retry logic with exponential backoff for connection errors
  • Implement timeout handling with configurable thresholds

3. Transport Layer

  • Implement local stdio transport: subprocess spawn, JSON-RPC framing, stdin/stdout I/O
  • Implement HTTP transport: JSON-RPC over HTTP POST to configured endpoint
  • Add transport factory / resolver (auto-detect or explicit config)

4. CLI Integration

  • Reroute agents session create through A2aLocalFacade
  • Reroute agents session list through A2aLocalFacade
  • Reroute agents session show <id> through A2aLocalFacade
  • Reroute agents session close <id> through A2aLocalFacade
  • Reroute agents session delete <id> through A2aLocalFacade
  • Reroute agents session tell <message> through A2aLocalFacade
  • Reroute agents plan use / execute / cancel / rollback / status through A2aLocalFacade

5. Error Handling & Resilience

  • Implement graceful degradation on connection failure (clear error + recovery hint)
  • Ensure partial failures (mid-execution cancel) leave recoverable session state
  • Add structured logging for all facade operations (session ID, transport, operation, duration)

6. Testing

  • Unit tests for A2aLocalFacade with mocked stdio transport
  • Unit tests for A2aLocalFacade with mocked HTTP transport
  • Unit tests for retry logic (verify backoff intervals and max retries)
  • Integration tests: full session lifecycle in local stdio mode
  • Integration tests: full plan lifecycle (use → execute → status → cancel → rollback) in local stdio mode
  • CLI end-to-end tests for all rerouted commands
  • Verify test coverage ≥ 97% for new modules

7. Documentation

  • Update CLI reference docs for all affected agents session and agents plan commands
  • Add A2aLocalFacade API documentation (docstrings + generated reference)
  • Add usage examples for both local and server transport modes

Definition of Done

This issue is closed when:

  1. A2aLocalFacade is fully implemented with session and plan lifecycle methods, supporting both stdio and HTTP transports.
  2. All listed CLI commands (agents session create/list/show/close/delete/tell and agents plan use/execute/cancel/rollback/status) route through the facade.
  3. Retry logic with exponential backoff is implemented and tested.
  4. All acceptance criteria checkboxes above are checked.
  5. Test coverage ≥ 97% for all new and modified modules.
  6. nox passes with no regressions on the feat/a2a-facade-session-plan-lifecycle branch.
  7. PR is reviewed, approved, and merged into the main branch targeting the v3.5.0 milestone.

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Branch**: `feat/a2a-facade-session-plan-lifecycle` - **Commit Message**: `feat(a2a): implement A2A facade session and plan lifecycle operations via CLI` - **Milestone**: v3.5.0 --- ## Background and Context The v3.5.0 milestone (M6: Autonomy Hardening) requires A2A facade session and plan lifecycle operations to be fully functional via the CLI. Following the ACP → A2A protocol adoption (ADR-047) and server architecture redesign (ADR-048), the system must expose a clean `A2aLocalFacade` abstraction that routes all session and plan interactions through the Agent-to-Agent (A2A) protocol. Currently, CLI commands for session management and plan execution interact directly with internal services without a standardized facade layer. This creates tight coupling, makes it difficult to support both local (stdio) and server (HTTP) transport modes, and prevents the system from scaling to multi-agent and multi-device scenarios planned in later milestones. The `A2aLocalFacade` must: - Provide a unified interface for session lifecycle (create, list, show, close, delete) - Provide a unified interface for plan lifecycle via A2A (use, execute, cancel, rollback, status) - Support both local stdio transport (agent as subprocess) and server HTTP transport (single JSON-RPC endpoint) - Route `agents session tell <message>` through the A2A facade - Surface `agents session list` showing all active A2A sessions - Handle connection errors gracefully with configurable retry logic This is a foundational requirement for the full autonomy acceptance flow (4+ levels of hierarchical decomposition, 10+ concurrent subplans) that is the primary goal of M6. --- ## Expected Behavior 1. **Session Lifecycle via CLI** - `agents session create` → creates a new A2A session, returns session ID - `agents session list` → lists all active A2A sessions with status, transport mode, and creation time - `agents session show <id>` → displays full session details including plan state and event history - `agents session close <id>` → gracefully closes the session, flushing pending events - `agents session delete <id>` → removes the session and all associated state 2. **Plan Lifecycle via A2A** - `agents plan use <plan-id>` → attaches a plan to the current A2A session - `agents plan execute` → triggers plan execution through the A2A facade - `agents plan cancel` → cancels the running plan, emitting a cancellation event - `agents plan rollback` → rolls back to the last checkpoint via A2A - `agents plan status` → returns current plan status from the A2A session 3. **Transport Mode Support** - Local mode (stdio): `A2aLocalFacade` spawns the agent as a subprocess and communicates via stdin/stdout JSON-RPC - Server mode (HTTP): `A2aLocalFacade` connects to a running server at a configured endpoint 4. **Error Handling** - Connection failures trigger configurable retry with exponential backoff (default: 3 retries, 1s/2s/4s) - Timeout errors surface a clear CLI message with the session ID and suggested recovery command - Partial failures (e.g., plan cancel mid-execution) leave the session in a recoverable state --- ## Acceptance Criteria - [ ] `A2aLocalFacade` class implemented with full session lifecycle: `create_session`, `list_sessions`, `show_session`, `close_session`, `delete_session` - [ ] Plan lifecycle methods implemented on `A2aLocalFacade`: `use_plan`, `execute_plan`, `cancel_plan`, `rollback_plan`, `get_plan_status` - [ ] `agents session create` CLI command routes through `A2aLocalFacade` and returns a valid session ID - [ ] `agents session list` CLI command displays all active A2A sessions with correct metadata - [ ] `agents session show <id>` CLI command returns full session details - [ ] `agents session close <id>` and `agents session delete <id>` CLI commands work correctly - [ ] `agents session tell <message>` routes through the A2A facade (not direct service calls) - [ ] `agents plan use`, `execute`, `cancel`, `rollback`, `status` all route through `A2aLocalFacade` - [ ] Local stdio transport mode functional: facade spawns subprocess and communicates via JSON-RPC - [ ] Server HTTP transport mode functional: facade connects to configured HTTP endpoint - [ ] Connection errors trigger retry logic with exponential backoff (3 retries by default) - [ ] Timeout and connection errors produce clear, actionable CLI error messages - [ ] Partial failures leave session in a recoverable state (no orphaned processes or locked state) - [ ] Unit tests cover all `A2aLocalFacade` methods with mocked transport - [ ] Integration tests cover full session + plan lifecycle in local stdio mode - [ ] Test coverage ≥ 97% for all new modules - [ ] `nox` passes with no regressions --- ## Subtasks ### 1. Design & Architecture - [ ] Define `A2aLocalFacade` interface and method signatures - [ ] Document transport abstraction layer (stdio vs HTTP) in a design note or ADR update - [ ] Identify all existing CLI commands that need to be rerouted through the facade ### 2. Core Facade Implementation - [ ] Implement `A2aLocalFacade` base class with transport abstraction - [ ] Implement `create_session` / `list_sessions` / `show_session` / `close_session` / `delete_session` - [ ] Implement `use_plan` / `execute_plan` / `cancel_plan` / `rollback_plan` / `get_plan_status` - [ ] Implement retry logic with exponential backoff for connection errors - [ ] Implement timeout handling with configurable thresholds ### 3. Transport Layer - [ ] Implement local stdio transport: subprocess spawn, JSON-RPC framing, stdin/stdout I/O - [ ] Implement HTTP transport: JSON-RPC over HTTP POST to configured endpoint - [ ] Add transport factory / resolver (auto-detect or explicit config) ### 4. CLI Integration - [ ] Reroute `agents session create` through `A2aLocalFacade` - [ ] Reroute `agents session list` through `A2aLocalFacade` - [ ] Reroute `agents session show <id>` through `A2aLocalFacade` - [ ] Reroute `agents session close <id>` through `A2aLocalFacade` - [ ] Reroute `agents session delete <id>` through `A2aLocalFacade` - [ ] Reroute `agents session tell <message>` through `A2aLocalFacade` - [ ] Reroute `agents plan use / execute / cancel / rollback / status` through `A2aLocalFacade` ### 5. Error Handling & Resilience - [ ] Implement graceful degradation on connection failure (clear error + recovery hint) - [ ] Ensure partial failures (mid-execution cancel) leave recoverable session state - [ ] Add structured logging for all facade operations (session ID, transport, operation, duration) ### 6. Testing - [ ] Unit tests for `A2aLocalFacade` with mocked stdio transport - [ ] Unit tests for `A2aLocalFacade` with mocked HTTP transport - [ ] Unit tests for retry logic (verify backoff intervals and max retries) - [ ] Integration tests: full session lifecycle in local stdio mode - [ ] Integration tests: full plan lifecycle (use → execute → status → cancel → rollback) in local stdio mode - [ ] CLI end-to-end tests for all rerouted commands - [ ] Verify test coverage ≥ 97% for new modules ### 7. Documentation - [ ] Update CLI reference docs for all affected `agents session` and `agents plan` commands - [ ] Add `A2aLocalFacade` API documentation (docstrings + generated reference) - [ ] Add usage examples for both local and server transport modes --- ## Definition of Done This issue is closed when: 1. `A2aLocalFacade` is fully implemented with session and plan lifecycle methods, supporting both stdio and HTTP transports. 2. All listed CLI commands (`agents session create/list/show/close/delete/tell` and `agents plan use/execute/cancel/rollback/status`) route through the facade. 3. Retry logic with exponential backoff is implemented and tested. 4. All acceptance criteria checkboxes above are checked. 5. Test coverage ≥ 97% for all new and modified modules. 6. `nox` passes with no regressions on the `feat/a2a-facade-session-plan-lifecycle` branch. 7. PR is reviewed, approved, and merged into the main branch targeting the v3.5.0 milestone. --- **Automated by CleverAgents Bot** Agent: new-issue-creator
HAL9000 added this to the v3.5.0 milestone 2026-04-14 14:32:56 +00:00
Author
Owner

Triage: Verified [AUTO-OWNR-1]

Valid feature: A2A facade session and plan lifecycle operations are explicitly listed in the v3.5.0 milestone acceptance criteria: "A2A facade session and plan lifecycle operations functional via CLI." This issue provides a comprehensive specification for A2aLocalFacade with session lifecycle, plan lifecycle, transport abstraction (stdio/HTTP), retry logic, and CLI integration.

This is foundational for the full autonomy acceptance flow (4+ levels of hierarchical decomposition, 10+ concurrent subplans) that is the primary goal of M6.

Assigning to v3.5.0 (Autonomy Hardening) as this is explicitly required by the milestone. Priority High — core M6 deliverable.

MoSCoW: Must Have — A2A facade is explicitly required by the v3.5.0 milestone acceptance criteria and is foundational for the autonomy hardening goal.


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

✅ **Triage: Verified** [AUTO-OWNR-1] Valid feature: A2A facade session and plan lifecycle operations are explicitly listed in the v3.5.0 milestone acceptance criteria: "A2A facade session and plan lifecycle operations functional via CLI." This issue provides a comprehensive specification for `A2aLocalFacade` with session lifecycle, plan lifecycle, transport abstraction (stdio/HTTP), retry logic, and CLI integration. This is foundational for the full autonomy acceptance flow (4+ levels of hierarchical decomposition, 10+ concurrent subplans) that is the primary goal of M6. Assigning to **v3.5.0** (Autonomy Hardening) as this is explicitly required by the milestone. Priority **High** — core M6 deliverable. MoSCoW: **Must Have** — A2A facade is explicitly required by the v3.5.0 milestone acceptance criteria and is foundational for the autonomy hardening goal. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
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.

Dependencies

No dependencies set.

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