UAT: A2A client-local resource access extension methods (`_cleveragents/fs/`, `_cleveragents/terminal/`) are completely absent — spec requires server-hosted agents to access client-local files and terminals #4079

New issue

Open

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

freemo commented

2026-04-06 10:06:41 +00:00

Owner

Metadata

Branch: feat/a2a-client-local-resource-access
Commit Message: feat(a2a): implement _cleveragents/fs/* and _cleveragents/terminal/* extension methods for client-local resource access
Milestone: Backlog
Parent Epic: #933 (Epic: A2A Protocol Compliance — JSON-RPC 2.0 Framing, Standard Operations, and Extension Methods)

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

Bug Report

What was tested: A2A client-local resource access extension methods against the specification

Expected behavior (from spec, section "Server and Client Architecture" and "A2A Multi-Turn Interactions"):

The spec defines a critical server-mode capability: when a server-hosted agent needs to access client-local resources (files, terminals), it uses _cleveragents/ extension methods via the A2A multi-turn interaction pattern (Task enters input-required state).

The spec explicitly lists these extension methods:

Extension Method	Purpose
`_cleveragents/fs/read_text_file`	Agent reads a file on the client machine
`_cleveragents/fs/write_text_file`	Agent writes a file on the client machine
`_cleveragents/terminal/create`	Agent requests a terminal on the client machine
`_cleveragents/terminal/output`	Terminal output streaming
`_cleveragents/terminal/release`	Terminal lifecycle management
`_cleveragents/terminal/wait_for_exit`	Wait for terminal process to exit
`_cleveragents/terminal/kill`	Kill terminal process

The spec states:

"When an agent executing on the server needs to access client-local resources (files, terminals), it uses _cleveragents/ extension methods (fs/read_text_file, fs/write_text_file, terminal/*) which the client handles locally via the A2A multi-turn interaction pattern (Task enters input-required state). This enables server-hosted plan execution even when some resources exist only on the client machine."

Actual behavior (from code analysis):

Searching the entire codebase for _cleveragents/fs, _cleveragents/terminal, fs/read_text_file, fs/write_text_file, terminal/create, terminal/output returns zero results.

The A2aLocalFacade in src/cleveragents/a2a/facade.py registers these extension method groups:

_cleveragents/plan/* — implemented
_cleveragents/registry/* — implemented
_cleveragents/sync/* — stubs only
_cleveragents/namespace/* — stubs only
_cleveragents/diagnostics/* — stub only

But _cleveragents/fs/* and _cleveragents/terminal/* are completely absent — not even registered as stubs.

Code location:

src/cleveragents/a2a/facade.py — _SUPPORTED_METHODS list (lines 59-94) — no fs/* or terminal/* entries

Steps to reproduce:

Configure server mode
Start a plan that requires reading a client-local file
Observe: the server-hosted agent cannot request client-local file access
Observe: no _cleveragents/fs/read_text_file method is available

Severity: High — without these extension methods, server-hosted plan execution cannot access client-local resources. This breaks the core server-mode use case where users start plans on a remote server but have local project files.

Subtasks

Register _cleveragents/fs/read_text_file extension method in A2aLocalFacade
Register _cleveragents/fs/write_text_file extension method in A2aLocalFacade
Register _cleveragents/terminal/create extension method in A2aLocalFacade
Register _cleveragents/terminal/output extension method in A2aLocalFacade
Register _cleveragents/terminal/release, wait_for_exit, kill extension methods
Implement client-side handlers for fs/* methods (read/write local files)
Implement client-side handlers for terminal/* methods (create/manage local terminals)
Implement Task input-required state transition for multi-turn interactions
Add unit tests (Behave scenarios) for client-local resource access
Add integration tests (Robot Framework) for multi-turn file access workflow

Definition of Done

All _cleveragents/fs/* extension methods are registered and functional
All _cleveragents/terminal/* extension methods are registered and functional
Task enters input-required state when server agent needs client-local resources
Client handles fs/* requests by reading/writing local files
Client handles terminal/* requests by creating/managing local terminal processes
All existing A2A tests continue to pass
New Behave scenarios cover client-local resource access workflows
Pyright type checking passes with no suppressions
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

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

## Metadata - **Branch**: `feat/a2a-client-local-resource-access` - **Commit Message**: `feat(a2a): implement _cleveragents/fs/* and _cleveragents/terminal/* extension methods for client-local resource access` - **Milestone**: Backlog - **Parent Epic**: #933 (Epic: A2A Protocol Compliance — JSON-RPC 2.0 Framing, Standard Operations, and Extension Methods) > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.4.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Bug Report **What was tested:** A2A client-local resource access extension methods against the specification **Expected behavior (from spec, section "Server and Client Architecture" and "A2A Multi-Turn Interactions"):** The spec defines a critical server-mode capability: when a server-hosted agent needs to access client-local resources (files, terminals), it uses `_cleveragents/` extension methods via the A2A multi-turn interaction pattern (Task enters `input-required` state). The spec explicitly lists these extension methods: | Extension Method | Purpose | |---|---| | `_cleveragents/fs/read_text_file` | Agent reads a file on the client machine | | `_cleveragents/fs/write_text_file` | Agent writes a file on the client machine | | `_cleveragents/terminal/create` | Agent requests a terminal on the client machine | | `_cleveragents/terminal/output` | Terminal output streaming | | `_cleveragents/terminal/release` | Terminal lifecycle management | | `_cleveragents/terminal/wait_for_exit` | Wait for terminal process to exit | | `_cleveragents/terminal/kill` | Kill terminal process | The spec states: > "When an agent executing on the server needs to access **client-local resources** (files, terminals), it uses `_cleveragents/` extension methods (`fs/read_text_file`, `fs/write_text_file`, `terminal/*`) which the client handles locally via the A2A multi-turn interaction pattern (Task enters `input-required` state). This enables server-hosted plan execution even when some resources exist only on the client machine." **Actual behavior (from code analysis):** Searching the entire codebase for `_cleveragents/fs`, `_cleveragents/terminal`, `fs/read_text_file`, `fs/write_text_file`, `terminal/create`, `terminal/output` returns **zero results**. The `A2aLocalFacade` in `src/cleveragents/a2a/facade.py` registers these extension method groups: - `_cleveragents/plan/*` — implemented - `_cleveragents/registry/*` — implemented - `_cleveragents/sync/*` — stubs only - `_cleveragents/namespace/*` — stubs only - `_cleveragents/diagnostics/*` — stub only But `_cleveragents/fs/*` and `_cleveragents/terminal/*` are **completely absent** — not even registered as stubs. **Code location:** - `src/cleveragents/a2a/facade.py` — `_SUPPORTED_METHODS` list (lines 59-94) — no `fs/*` or `terminal/*` entries **Steps to reproduce:** 1. Configure server mode 2. Start a plan that requires reading a client-local file 3. Observe: the server-hosted agent cannot request client-local file access 4. Observe: no `_cleveragents/fs/read_text_file` method is available **Severity:** High — without these extension methods, server-hosted plan execution cannot access client-local resources. This breaks the core server-mode use case where users start plans on a remote server but have local project files. ## Subtasks - [ ] Register `_cleveragents/fs/read_text_file` extension method in `A2aLocalFacade` - [ ] Register `_cleveragents/fs/write_text_file` extension method in `A2aLocalFacade` - [ ] Register `_cleveragents/terminal/create` extension method in `A2aLocalFacade` - [ ] Register `_cleveragents/terminal/output` extension method in `A2aLocalFacade` - [ ] Register `_cleveragents/terminal/release`, `wait_for_exit`, `kill` extension methods - [ ] Implement client-side handlers for `fs/*` methods (read/write local files) - [ ] Implement client-side handlers for `terminal/*` methods (create/manage local terminals) - [ ] Implement Task `input-required` state transition for multi-turn interactions - [ ] Add unit tests (Behave scenarios) for client-local resource access - [ ] Add integration tests (Robot Framework) for multi-turn file access workflow ## Definition of Done - [ ] All `_cleveragents/fs/*` extension methods are registered and functional - [ ] All `_cleveragents/terminal/*` extension methods are registered and functional - [ ] Task enters `input-required` state when server agent needs client-local resources - [ ] Client handles `fs/*` requests by reading/writing local files - [ ] Client handles `terminal/*` requests by creating/managing local terminal processes - [ ] All existing A2A tests continue to pass - [ ] New Behave scenarios cover client-local resource access workflows - [ ] Pyright type checking passes with no suppressions - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 10:06:48 +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:10:08 +00:00

freemo referenced this issue

2026-04-06 10:10:44 +00:00

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

freemo referenced this issue

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