cleveragents/cleveragents-core

Fork 3

UAT: A2A multi-turn interaction extension methods (`_cleveragents/fs/`, `_cleveragents/terminal/`) missing from facade — server-hosted agents cannot access client-local resources #3650

New issue

Open

opened 2026-04-05 21:06:30 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 21:06:30 +00:00

Owner

Metadata

Branch: bugfix/a2a-facade-missing-fs-terminal-extension-methods
Commit Message: fix(a2a): add _cleveragents/fs/* and _cleveragents/terminal/* extension methods to facade
Milestone: None (backlog)
Parent Epic: #366

Background and Context

Per docs/specification.md (lines 23440–23451 and 43499), A2A supports multi-turn interactions for operations that require client-side input. When a server-hosted agent needs client-local resources or human approval, the Task enters input-required state and the following extension methods are used:

Extension Method	Purpose
`_cleveragents/fs/read_text_file`	Agent reads a file on the client machine (local project resources)
`_cleveragents/fs/write_text_file`	Agent writes a file on the client machine
`_cleveragents/terminal/create`	Agent requests a terminal on the client machine (sandbox execution)
`_cleveragents/terminal/output`	Terminal output streaming
`_cleveragents/terminal/release`	Terminal lifecycle management — release
`_cleveragents/terminal/wait_for_exit`	Terminal lifecycle management — wait for exit
`_cleveragents/terminal/kill`	Terminal lifecycle management — kill

The spec also states (line 43499):

Multi-turn interactions to clients (Task input-required state, _cleveragents/fs/*, _cleveragents/terminal/*): Forwarded from executing actors back to the connected client — enabling server-hosted agents to access client-local resources.

These multi-turn interactions enable a server-hosted agent to access client-local resources without requiring the server to have direct access to the user's filesystem or terminal.

Current Behavior

The A2aLocalFacade._EXTENSION_OPERATIONS list in src/cleveragents/a2a/facade.py does not include any _cleveragents/fs/* or _cleveragents/terminal/* methods. These extension methods are completely absent from:

_EXTENSION_OPERATIONS list
_handlers() dispatch map
Any handler implementation

Calling facade.dispatch(A2aRequest(method="_cleveragents/fs/read_text_file", params={...})) raises A2aOperationNotFoundError.

Expected Behavior

The facade must support the following extension methods for multi-turn client interactions:

_cleveragents/fs/read_text_file — read a file from the client's local filesystem
_cleveragents/fs/write_text_file — write a file to the client's local filesystem
_cleveragents/terminal/create — create a terminal session on the client
_cleveragents/terminal/output — stream terminal output
_cleveragents/terminal/release — release a terminal session
_cleveragents/terminal/wait_for_exit — wait for terminal process to exit
_cleveragents/terminal/kill — kill a terminal process

These are required for server-hosted agents to access client-local resources via the A2A multi-turn interaction pattern.

Subtasks

Add _cleveragents/fs/read_text_file to _EXTENSION_OPERATIONS and implement handler in src/cleveragents/a2a/facade.py
Add _cleveragents/fs/write_text_file to _EXTENSION_OPERATIONS and implement handler in src/cleveragents/a2a/facade.py
Add _cleveragents/terminal/create to _EXTENSION_OPERATIONS and implement handler in src/cleveragents/a2a/facade.py
Add _cleveragents/terminal/output to _EXTENSION_OPERATIONS and implement handler in src/cleveragents/a2a/facade.py
Add _cleveragents/terminal/release to _EXTENSION_OPERATIONS and implement handler in src/cleveragents/a2a/facade.py
Add _cleveragents/terminal/wait_for_exit to _EXTENSION_OPERATIONS and implement handler in src/cleveragents/a2a/facade.py
Add _cleveragents/terminal/kill to _EXTENSION_OPERATIONS and implement handler in src/cleveragents/a2a/facade.py
Ensure _handlers() dispatch map is updated for all seven new methods
Tests (Behave): Add scenarios covering each new extension method dispatch
Tests (Robot): Add integration tests for multi-turn client interaction via facade
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 seven _cleveragents/fs/* and _cleveragents/terminal/* extension methods are registered in _EXTENSION_OPERATIONS and dispatched correctly via _handlers()
Each handler correctly implements the multi-turn client interaction pattern per docs/specification.md lines 23440–23451 and 43499
facade.dispatch(A2aRequest(method="_cleveragents/fs/read_text_file", params={...})) no longer raises A2aOperationNotFoundError
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
All nox stages pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.6.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**: `bugfix/a2a-facade-missing-fs-terminal-extension-methods` - **Commit Message**: `fix(a2a): add _cleveragents/fs/* and _cleveragents/terminal/* extension methods to facade` - **Milestone**: None (backlog) - **Parent Epic**: #366 ## Background and Context Per `docs/specification.md` (lines 23440–23451 and 43499), A2A supports multi-turn interactions for operations that require client-side input. When a server-hosted agent needs client-local resources or human approval, the Task enters `input-required` state and the following extension methods are used: | Extension Method | Purpose | |---|---| | `_cleveragents/fs/read_text_file` | Agent reads a file on the client machine (local project resources) | | `_cleveragents/fs/write_text_file` | Agent writes a file on the client machine | | `_cleveragents/terminal/create` | Agent requests a terminal on the client machine (sandbox execution) | | `_cleveragents/terminal/output` | Terminal output streaming | | `_cleveragents/terminal/release` | Terminal lifecycle management — release | | `_cleveragents/terminal/wait_for_exit` | Terminal lifecycle management — wait for exit | | `_cleveragents/terminal/kill` | Terminal lifecycle management — kill | The spec also states (line 43499): > **Multi-turn interactions to clients** (Task `input-required` state, `_cleveragents/fs/*`, `_cleveragents/terminal/*`): Forwarded from executing actors back to the connected client — enabling server-hosted agents to access client-local resources. These multi-turn interactions enable a server-hosted agent to access client-local resources without requiring the server to have direct access to the user's filesystem or terminal. ## Current Behavior The `A2aLocalFacade._EXTENSION_OPERATIONS` list in `src/cleveragents/a2a/facade.py` does **not** include any `_cleveragents/fs/*` or `_cleveragents/terminal/*` methods. These extension methods are completely absent from: - `_EXTENSION_OPERATIONS` list - `_handlers()` dispatch map - Any handler implementation Calling `facade.dispatch(A2aRequest(method="_cleveragents/fs/read_text_file", params={...}))` raises `A2aOperationNotFoundError`. ## Expected Behavior The facade must support the following extension methods for multi-turn client interactions: - `_cleveragents/fs/read_text_file` — read a file from the client's local filesystem - `_cleveragents/fs/write_text_file` — write a file to the client's local filesystem - `_cleveragents/terminal/create` — create a terminal session on the client - `_cleveragents/terminal/output` — stream terminal output - `_cleveragents/terminal/release` — release a terminal session - `_cleveragents/terminal/wait_for_exit` — wait for terminal process to exit - `_cleveragents/terminal/kill` — kill a terminal process These are required for server-hosted agents to access client-local resources via the A2A multi-turn interaction pattern. ## Subtasks - [ ] Add `_cleveragents/fs/read_text_file` to `_EXTENSION_OPERATIONS` and implement handler in `src/cleveragents/a2a/facade.py` - [ ] Add `_cleveragents/fs/write_text_file` to `_EXTENSION_OPERATIONS` and implement handler in `src/cleveragents/a2a/facade.py` - [ ] Add `_cleveragents/terminal/create` to `_EXTENSION_OPERATIONS` and implement handler in `src/cleveragents/a2a/facade.py` - [ ] Add `_cleveragents/terminal/output` to `_EXTENSION_OPERATIONS` and implement handler in `src/cleveragents/a2a/facade.py` - [ ] Add `_cleveragents/terminal/release` to `_EXTENSION_OPERATIONS` and implement handler in `src/cleveragents/a2a/facade.py` - [ ] Add `_cleveragents/terminal/wait_for_exit` to `_EXTENSION_OPERATIONS` and implement handler in `src/cleveragents/a2a/facade.py` - [ ] Add `_cleveragents/terminal/kill` to `_EXTENSION_OPERATIONS` and implement handler in `src/cleveragents/a2a/facade.py` - [ ] Ensure `_handlers()` dispatch map is updated for all seven new methods - [ ] Tests (Behave): Add scenarios covering each new extension method dispatch - [ ] Tests (Robot): Add integration tests for multi-turn client interaction via facade - [ ] 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 seven `_cleveragents/fs/*` and `_cleveragents/terminal/*` extension methods are registered in `_EXTENSION_OPERATIONS` and dispatched correctly via `_handlers()` - [ ] Each handler correctly implements the multi-turn client interaction pattern per `docs/specification.md` lines 23440–23451 and 43499 - [ ] `facade.dispatch(A2aRequest(method="_cleveragents/fs/read_text_file", params={...}))` no longer raises `A2aOperationNotFoundError` - [ ] 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 - [ ] All nox stages pass - [ ] Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.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 the

labels

2026-04-05 21:06:44 +00:00

freemo added a new dependency

2026-04-05 21:06:48 +00:00

#366 Epic: Post-MVP Deferred Work

freemo referenced this issue

2026-04-05 21:07:38 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue

2026-04-05 21:24:08 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo commented

2026-04-06 06:33:25 +00:00

Author

Owner

Duplicate Detection — Independent UAT Confirmation

This issue was independently rediscovered during a separate UAT testing session on 2026-04-06, confirming the bug is reproducible and real.

UAT Tester Reproduction Steps (confirmed):

from cleveragents.a2a.facade import A2aLocalFacade
from cleveragents.a2a.models import A2aRequest
from cleveragents.a2a.errors import A2aOperationNotFoundError

facade = A2aLocalFacade()
for op in ['_cleveragents/fs/read_text_file', '_cleveragents/fs/write_text_file',
           '_cleveragents/terminal/create', '_cleveragents/terminal/output',
           '_cleveragents/terminal/release', '_cleveragents/terminal/wait_for_exit',
           '_cleveragents/terminal/kill']:
    try:
        facade.dispatch(A2aRequest(method=op, params={}))
    except A2aOperationNotFoundError:
        print(f"MISSING: {op}")
# All 7 operations print MISSING

All 7 operations confirmed missing — A2aOperationNotFoundError raised for every _cleveragents/fs/* and _cleveragents/terminal/* method.

Action taken: Added Type/Automation label to reflect UAT automation discovery. No duplicate issue created — this existing issue fully captures the bug.

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

## Duplicate Detection — Independent UAT Confirmation This issue was independently rediscovered during a separate UAT testing session on **2026-04-06**, confirming the bug is reproducible and real. **UAT Tester Reproduction Steps (confirmed):** ```python from cleveragents.a2a.facade import A2aLocalFacade from cleveragents.a2a.models import A2aRequest from cleveragents.a2a.errors import A2aOperationNotFoundError facade = A2aLocalFacade() for op in ['_cleveragents/fs/read_text_file', '_cleveragents/fs/write_text_file', '_cleveragents/terminal/create', '_cleveragents/terminal/output', '_cleveragents/terminal/release', '_cleveragents/terminal/wait_for_exit', '_cleveragents/terminal/kill']: try: facade.dispatch(A2aRequest(method=op, params={})) except A2aOperationNotFoundError: print(f"MISSING: {op}") # All 7 operations print MISSING ``` **All 7 operations confirmed missing** — `A2aOperationNotFoundError` raised for every `_cleveragents/fs/*` and `_cleveragents/terminal/*` method. **Action taken:** Added `Type/Automation` label to reflect UAT automation discovery. No duplicate issue created — this existing issue fully captures the bug. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo referenced this issue

2026-04-06 06:34:11 +00:00

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