Skip to content

Commit 6cce91b

Browse files
authored
fix(server): reject terminal-task operations with UnsupportedOperationError (a2aproject#1268)
## What Spec [3.1.1](https://a2a-protocol.org/latest/specification/#311-send-message) names `UnsupportedOperationError` for "Messages sent to Tasks that are in a terminal state", and 3.3.2 repeats it for any operation on a terminal task. 5.4 maps that to `-32004` / `FAILED_PRECONDITION` / HTTP 400. `ActiveTask` raised `InvalidParamsError` (`-32602`) instead, at all three of its terminal-state guards. That covers both `send_message` and `subscribe_to_task`, because `DefaultRequestHandlerV2.on_subscribe_to_task` has no terminal check of its own: it calls `get_or_create`, which calls `ActiveTask.start()`, and the error surfaces out of the first `__anext__`. Worth knowing while reading: `DefaultRequestHandler` is an alias for `DefaultRequestHandlerV2` (`request_handlers/__init__.py:46`), so `default_request_handler.py` is the legacy handler and is not on the default path. It already answered subscribe correctly at line 613, which is why only the v2 path drifted. Its send path is corrected here too, so the two handlers and the two operations finally agree. ## Cancel keeps its own error `on_cancel_task` deliberately catches `ActiveTask`'s terminal-state error and re-raises `TaskNotCancelableError`, which 3.3.2 gives its own entry. That remap is retained, now keyed on the new error type. Two ACTS tests (`CORE-CANCEL-002`, `CORE-ERR-002`) cover it and still pass. ## Tests `test_on_subscribe_to_task_in_terminal_state` is new for v2. Its absence is why this survived: the legacy suite had the equivalent test and asserted the correct error all along, so the divergence never showed up. Mutation-checked - reverting `active_task.py:472` alone fails all four parametrized cases. An existing `# TODO: Is it correct error code ?` in `test_scenarios.py` sat next to this exact assertion. It is now answered rather than carried forward. ## Result Clears `CORE-SEND-002`, `CORE-ERR-004` and `STREAM-SUB-003` (all `must`) on jsonrpc, grpc and rest - 9 of the 21 failing MUST test-instances. | binding | must before | must after | | --- | --- | --- | | jsonrpc | 52/59 | 55/59 | | grpc | 40/47 | 43/47 | | rest | 42/49 | 45/49 |
1 parent 0d5473c commit 6cce91b

7 files changed

Lines changed: 48 additions & 16 deletions

File tree

‎src/a2a/server/agent_execution/active_task.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -72,8 +72,8 @@
7272
)
7373
from a2a.utils.errors import (
7474
InvalidAgentResponseError,
75-
InvalidParamsError,
7675
TaskNotFoundError,
76+
UnsupportedOperationError,
7777
)
7878

7979

@@ -441,7 +441,7 @@ async def start(
441441
logger.debug('ActiveTask[%s]: Starting', self._task_id)
442442
async with self._lock:
443443
if self._is_finished.is_set():
444-
raise InvalidParamsError(
444+
raise UnsupportedOperationError(
445445
f'Task {self._task_id} is already completed. Cannot start it again.'
446446
)
447447

@@ -469,7 +469,7 @@ async def start(
469469
if task:
470470
self._task_created.set()
471471
if task.status.state in TERMINAL_TASK_STATES:
472-
raise InvalidParamsError(
472+
raise UnsupportedOperationError(
473473
message=f'Task {task.id} is in terminal state: {task.status.state}'
474474
)
475475
elif not create_task_if_missing:
@@ -623,7 +623,7 @@ async def subscribe(
623623

624624
async with self._lock:
625625
if self._is_finished.is_set():
626-
raise InvalidParamsError(
626+
raise UnsupportedOperationError(
627627
f'Task {self._task_id} is already completed.'
628628
)
629629
self._reference_count += 1

‎src/a2a/server/request_handlers/default_request_handler.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -292,7 +292,7 @@ async def _setup_message_execution(
292292

293293
if task:
294294
if task.status.state in TERMINAL_TASK_STATES:
295-
raise InvalidParamsError(
295+
raise UnsupportedOperationError(
296296
message=f'Task {task.id} is in terminal state: {task.status.state}'
297297
)
298298

‎src/a2a/server/request_handlers/default_request_handler_v2.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@
4747
PushNotificationNotSupportedError,
4848
TaskNotCancelableError,
4949
TaskNotFoundError,
50+
UnsupportedOperationError,
5051
)
5152
from a2a.utils.task import (
5253
apply_history_length,
@@ -198,7 +199,7 @@ async def on_cancel_task( # noqa: D102
198199
task_id, call_context=context, create_task_if_missing=False
199200
)
200201
result = await active_task.cancel(context)
201-
except InvalidParamsError as e:
202+
except UnsupportedOperationError as e:
202203
raise TaskNotCancelableError from e
203204

204205
if isinstance(result, Message):

‎tests/integration/test_scenarios.py‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -50,9 +50,9 @@
5050
from a2a.utils import TransportProtocol
5151
from a2a.utils.errors import (
5252
InvalidAgentResponseError,
53-
InvalidParamsError,
5453
TaskNotCancelableError,
5554
TaskNotFoundError,
55+
UnsupportedOperationError,
5656
)
5757

5858

@@ -428,8 +428,9 @@ async def cancel(
428428
role=Role.ROLE_USER,
429429
parts=[Part(text='message to completed task')],
430430
)
431-
# TODO: Is it correct error code ?
432-
with pytest.raises(InvalidParamsError):
431+
# Spec 3.1.1: messages sent to a task in a terminal state are rejected
432+
# with UnsupportedOperationError.
433+
with pytest.raises(UnsupportedOperationError):
433434
async for _ in client.send_message(SendMessageRequest(message=msg2)):
434435
pass
435436

@@ -489,7 +490,7 @@ async def cancel(
489490

490491
if streaming:
491492
with pytest.raises(
492-
InvalidParamsError,
493+
UnsupportedOperationError,
493494
match='Task .* is in terminal state',
494495
):
495496
await client.subscribe(

‎tests/server/agent_execution/test_active_task.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
TaskStatusUpdateEvent,
2222
)
2323
from a2a.utils._async_queue_compat import QueueShutDown, create_async_queue
24-
from a2a.utils.errors import InvalidParamsError
24+
from a2a.utils.errors import UnsupportedOperationError
2525

2626

2727
logger = logging.getLogger(__name__)
@@ -805,7 +805,7 @@ async def execute_mock(req, q):
805805
await active_task._is_finished.wait()
806806

807807
with pytest.raises(
808-
InvalidParamsError, match=r'Task .* is already completed'
808+
UnsupportedOperationError, match=r'Task .* is already completed'
809809
):
810810
async for _ in active_task.subscribe():
811811
pass

‎tests/server/request_handlers/test_default_request_handler.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2553,7 +2553,7 @@ async def test_on_message_send_task_in_terminal_state(
25532553
'a2a.server.request_handlers.default_request_handler.TaskManager.get_task',
25542554
return_value=terminal_task,
25552555
):
2556-
with pytest.raises(InvalidParamsError) as exc_info:
2556+
with pytest.raises(UnsupportedOperationError) as exc_info:
25572557
await request_handler.on_message_send(
25582558
params, create_server_call_context()
25592559
)
@@ -2597,7 +2597,7 @@ async def test_on_message_send_stream_task_in_terminal_state(
25972597
'a2a.server.request_handlers.default_request_handler.TaskManager.get_task',
25982598
return_value=terminal_task,
25992599
):
2600-
with pytest.raises(InvalidParamsError) as exc_info:
2600+
with pytest.raises(UnsupportedOperationError) as exc_info:
26012601
async for _ in request_handler.on_message_send_stream(
26022602
params, create_server_call_context()
26032603
):

‎tests/server/request_handlers/test_default_request_handler_v2.py‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
InvalidParamsError,
4040
PushNotificationNotSupportedError,
4141
TaskNotFoundError,
42+
UnsupportedOperationError,
4243
)
4344
from a2a.types.a2a_pb2 import (
4445
AgentCapabilities,
@@ -1014,7 +1015,7 @@ async def test_on_message_send_task_in_terminal_state(terminal_state):
10141015
'a2a.server.request_handlers.default_request_handler.TaskManager.get_task',
10151016
return_value=terminal_task,
10161017
),
1017-
pytest.raises(InvalidParamsError) as exc_info,
1018+
pytest.raises(UnsupportedOperationError) as exc_info,
10181019
):
10191020
await request_handler.on_message_send(
10201021
params, create_server_call_context()
@@ -1053,7 +1054,7 @@ async def test_on_message_send_stream_task_in_terminal_state(terminal_state):
10531054
'a2a.server.request_handlers.default_request_handler.TaskManager.get_task',
10541055
return_value=terminal_task,
10551056
),
1056-
pytest.raises(InvalidParamsError) as exc_info,
1057+
pytest.raises(UnsupportedOperationError) as exc_info,
10571058
):
10581059
async for _ in request_handler.on_message_send_stream(
10591060
params, create_server_call_context()
@@ -1065,6 +1066,35 @@ async def test_on_message_send_stream_task_in_terminal_state(terminal_state):
10651066
)
10661067

10671068

1069+
@pytest.mark.asyncio
1070+
@pytest.mark.parametrize('terminal_state', TERMINAL_TASK_STATES)
1071+
async def test_on_subscribe_to_task_in_terminal_state(terminal_state):
1072+
"""Subscribing to a terminal task is rejected with UnsupportedOperationError."""
1073+
state_name = TaskState.Name(terminal_state)
1074+
task_id = f'subscribe_terminal_task_{state_name}'
1075+
terminal_task = create_sample_task(
1076+
task_id=task_id, status_state=terminal_state
1077+
)
1078+
mock_task_store = AsyncMock(spec=TaskStore)
1079+
mock_task_store.get.return_value = terminal_task
1080+
request_handler = DefaultRequestHandlerV2(
1081+
agent_executor=MockAgentExecutor(),
1082+
task_store=mock_task_store,
1083+
agent_card=create_default_agent_card(),
1084+
)
1085+
1086+
with pytest.raises(UnsupportedOperationError) as exc_info:
1087+
async for _ in request_handler.on_subscribe_to_task(
1088+
SubscribeToTaskRequest(id=task_id), create_server_call_context()
1089+
):
1090+
pass
1091+
1092+
assert (
1093+
f'Task {task_id} is in terminal state: {terminal_state}'
1094+
in exc_info.value.message
1095+
)
1096+
1097+
10681098
@pytest.mark.asyncio
10691099
async def test_on_message_send_task_id_provided_but_task_not_found():
10701100
"""Test on_message_send when task_id is provided but task doesn't exist."""

0 commit comments

Comments
 (0)