Skip to content

Commit 6be10db

Browse files
committed
fix(server): always stamp status.timestamp on terminal task states
Framework failure paths could persist a FAILED task without status.timestamp: the consumer failure path built a TaskStatusUpdateEvent with an unstamped TaskStatus (which TaskManager.save_task_event then CopyFrom'd over the task, clearing any prior timestamp), and the producer failure path mutated task.status.state directly before saving. DatabaseTaskStore derives last_updated from status.timestamp, so the task was persisted with last_updated = NULL, breaking ListTasks ordering and time-based filters (issue #1331). Per the approach endorsed on the issue, this lands both layers: - failure sites in ActiveTask (_write_failed_status, _mark_task_as_failed, and the producer failure path) stamp the current time explicitly; - TaskManager.save_task_event gains a defensive backstop that auto-populates the timestamp whenever a terminal state arrives unstamped, covering raw Task and status-event paths alike. Non-terminal states are left untouched, and explicitly provided timestamps are never overwritten. Signed-off-by: andy <linux2011@qq.com>
1 parent d316d0e commit 6be10db

4 files changed

Lines changed: 177 additions & 1 deletion

File tree

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

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,11 @@
4040
import logging
4141
import uuid
4242

43+
from datetime import datetime, timezone
4344
from typing import TYPE_CHECKING, Any, cast
4445

46+
from google.protobuf.timestamp_pb2 import Timestamp
47+
4548
from a2a.server.agent_execution.context import RequestContext
4649

4750

@@ -97,6 +100,13 @@
97100
}
98101

99102

103+
def _now_timestamp() -> Timestamp:
104+
"""Current UTC time as a protobuf Timestamp (issue #1331)."""
105+
ts = Timestamp()
106+
ts.FromDatetime(datetime.now(timezone.utc))
107+
return ts
108+
109+
100110
class _RequestStarted:
101111
def __init__(self, request_id: uuid.UUID, request_context: RequestContext):
102112
self.request_id = request_id
@@ -166,7 +176,10 @@ async def _write_failed_status(self) -> Task | None:
166176
handled_event = TaskStatusUpdateEvent(
167177
task_id=task.id,
168178
context_id=task.context_id,
169-
status=TaskStatus(state=TaskState.TASK_STATE_FAILED),
179+
status=TaskStatus(
180+
state=TaskState.TASK_STATE_FAILED,
181+
timestamp=_now_timestamp(),
182+
),
170183
)
171184
try:
172185
return await self._handle_task_event(handled_event)
@@ -676,6 +689,7 @@ async def _run_producer(self) -> None:
676689
)
677690
if task.status.state not in TERMINAL_TASK_STATES:
678691
task.status.state = TaskState.TASK_STATE_FAILED
692+
task.status.timestamp.CopyFrom(_now_timestamp())
679693
await self._task_manager.save_task_event(task)
680694
self._task_created.set()
681695
await self._event_queue_agent.enqueue_event(cast('Event', e))
@@ -996,6 +1010,7 @@ async def _mark_task_as_failed(self, exception: Exception) -> Task | None:
9961010
context_id=task.context_id,
9971011
status=TaskStatus(
9981012
state=TaskState.TASK_STATE_FAILED,
1013+
timestamp=_now_timestamp(),
9991014
),
10001015
)
10011016
)

‎src/a2a/server/tasks/task_manager.py‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,11 @@
22

33
import logging
44

5+
from datetime import datetime, timezone
56
from typing import TYPE_CHECKING
67

8+
from google.protobuf.timestamp_pb2 import Timestamp
9+
710
from a2a.types.a2a_pb2 import (
811
Artifact,
912
Message,
@@ -17,6 +20,14 @@
1720
from a2a.utils.telemetry import trace_function
1821

1922

23+
TERMINAL_TASK_STATES = {
24+
TaskState.TASK_STATE_COMPLETED,
25+
TaskState.TASK_STATE_CANCELED,
26+
TaskState.TASK_STATE_FAILED,
27+
TaskState.TASK_STATE_REJECTED,
28+
}
29+
30+
2031
if TYPE_CHECKING:
2132
from a2a.server.cluster.task_store import VersionedTaskStore
2233
from a2a.server.cluster.version import TaskVersion
@@ -205,6 +216,22 @@ async def get_task(self) -> Task | None:
205216
logger.debug('Task %s not found.', self.task_id)
206217
return self._current_task
207218

219+
def _stamp_terminal_timestamp(self, task: Task) -> None:
220+
"""Auto-stamp terminal states that arrive without a timestamp.
221+
222+
Defensive backstop for issue #1331: failure paths that mutate a
223+
task (or build a status event) can leave a terminal state
224+
unstamped, which DatabaseTaskStore would persist as
225+
last_updated = NULL.
226+
"""
227+
if (
228+
task.status.state in TERMINAL_TASK_STATES
229+
and not task.status.HasField('timestamp')
230+
):
231+
ts = Timestamp()
232+
ts.FromDatetime(datetime.now(timezone.utc))
233+
task.status.timestamp.CopyFrom(ts)
234+
208235
async def save_task_event(
209236
self, event: Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent
210237
) -> Task | None:
@@ -245,6 +272,7 @@ async def save_task_event(
245272
task_id_from_event,
246273
)
247274
if isinstance(event, Task):
275+
self._stamp_terminal_timestamp(event)
248276
self._pending_event = event
249277
try:
250278
await self._save_task(event)
@@ -263,6 +291,7 @@ async def save_task_event(
263291
if event.metadata:
264292
task.metadata.MergeFrom(event.metadata)
265293
task.status.CopyFrom(event.status)
294+
self._stamp_terminal_timestamp(task)
266295
else:
267296
logger.debug('Appending artifact to task %s', task.id)
268297
append_artifact_to_task(task, event)

‎tests/server/request_handlers/test_default_request_handler_v2.py‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2776,3 +2776,53 @@ async def test_on_message_send_stream_message_response_releases_active_task() ->
27762776
assert [type(event) for event in events] == [Message]
27772777
assert await _wait_until_released(handler, baseline) == set()
27782778
assert handler._active_task_registry._active_tasks == {}
2779+
2780+
2781+
class ExplodingExecutor(AgentExecutor):
2782+
"""Creates the task, then crashes mid-flight (issue #1331)."""
2783+
2784+
task_id = None
2785+
2786+
async def execute(self, context: RequestContext, event_queue: EventQueue):
2787+
task = new_task_from_user_message(context.message)
2788+
self.task_id = task.id
2789+
await event_queue.enqueue_event(task)
2790+
raise RuntimeError('agent crashed mid-flight')
2791+
2792+
async def cancel(self, context: RequestContext, event_queue: EventQueue):
2793+
pass
2794+
2795+
2796+
@pytest.mark.asyncio
2797+
async def test_framework_failure_persists_timestamp_on_failed_task():
2798+
"""A framework-written FAILED status must carry a status timestamp, so
2799+
DatabaseTaskStore does not persist last_updated as NULL (#1331)."""
2800+
task_store = InMemoryTaskStore()
2801+
executor = ExplodingExecutor()
2802+
request_handler = DefaultRequestHandlerV2(
2803+
agent_executor=executor,
2804+
task_store=task_store,
2805+
agent_card=create_default_agent_card(),
2806+
)
2807+
params = SendMessageRequest(
2808+
message=Message(
2809+
role=Role.ROLE_USER,
2810+
message_id='msg_explode',
2811+
parts=[Part(text='Hi')],
2812+
),
2813+
configuration=SendMessageConfiguration(
2814+
accepted_output_modes=['text/plain']
2815+
),
2816+
)
2817+
2818+
with pytest.raises(RuntimeError, match='agent crashed mid-flight'):
2819+
await request_handler.on_message_send(
2820+
params, create_server_call_context()
2821+
)
2822+
2823+
stored = await task_store.get(
2824+
executor.task_id, create_server_call_context()
2825+
)
2826+
assert stored is not None
2827+
assert stored.status.state == TaskState.TASK_STATE_FAILED
2828+
assert stored.status.HasField('timestamp')

‎tests/server/tasks/test_task_manager.py‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
from datetime import datetime, timezone
12
from typing import Any
23
from unittest.mock import AsyncMock
34

@@ -19,6 +20,7 @@
1920
TaskStatusUpdateEvent,
2021
)
2122
from a2a.utils.errors import InvalidAgentResponseError, InvalidParamsError
23+
from google.protobuf.timestamp_pb2 import Timestamp
2224

2325

2426
class SampleUser(User):
@@ -444,3 +446,83 @@ def test_append_artifact_to_task():
444446
match='append=True for nonexistent artifact_id',
445447
):
446448
append_artifact_to_task(task, append_event_5)
449+
450+
451+
@pytest.mark.asyncio
452+
async def test_save_task_event_stamps_terminal_status_without_timestamp(
453+
task_manager: TaskManager, mock_task_store: AsyncMock
454+
) -> None:
455+
"""Terminal states arriving unstamped are auto-stamped (#1331)."""
456+
initial_task = create_minimal_task()
457+
mock_task_store.get.return_value = initial_task
458+
event = TaskStatusUpdateEvent(
459+
task_id=MINIMAL_TASK_ID,
460+
context_id=MINIMAL_CONTEXT_ID,
461+
status=TaskStatus(state=TaskState.TASK_STATE_FAILED),
462+
)
463+
464+
await task_manager.save_task_event(event)
465+
466+
saved_task = mock_task_store.save.call_args[0][0]
467+
assert saved_task.status.state == TaskState.TASK_STATE_FAILED
468+
assert saved_task.status.HasField('timestamp')
469+
470+
471+
@pytest.mark.asyncio
472+
async def test_save_task_event_preserves_provided_terminal_timestamp(
473+
task_manager: TaskManager, mock_task_store: AsyncMock
474+
) -> None:
475+
"""An explicitly provided timestamp is never overwritten (#1331)."""
476+
initial_task = create_minimal_task()
477+
mock_task_store.get.return_value = initial_task
478+
provided = Timestamp()
479+
provided.FromDatetime(datetime(2026, 1, 1, tzinfo=timezone.utc))
480+
event = TaskStatusUpdateEvent(
481+
task_id=MINIMAL_TASK_ID,
482+
context_id=MINIMAL_CONTEXT_ID,
483+
status=TaskStatus(
484+
state=TaskState.TASK_STATE_FAILED, timestamp=provided
485+
),
486+
)
487+
488+
await task_manager.save_task_event(event)
489+
490+
saved_task = mock_task_store.save.call_args[0][0]
491+
assert saved_task.status.timestamp.ToDatetime(
492+
tzinfo=timezone.utc
493+
) == datetime(2026, 1, 1, tzinfo=timezone.utc)
494+
495+
496+
@pytest.mark.asyncio
497+
async def test_save_task_event_does_not_stamp_non_terminal_status(
498+
task_manager: TaskManager, mock_task_store: AsyncMock
499+
) -> None:
500+
"""Non-terminal states are left alone by the backstop (#1331)."""
501+
initial_task = create_minimal_task()
502+
mock_task_store.get.return_value = initial_task
503+
event = TaskStatusUpdateEvent(
504+
task_id=MINIMAL_TASK_ID,
505+
context_id=MINIMAL_CONTEXT_ID,
506+
status=TaskStatus(state=TaskState.TASK_STATE_WORKING),
507+
)
508+
509+
await task_manager.save_task_event(event)
510+
511+
saved_task = mock_task_store.save.call_args[0][0]
512+
assert saved_task.status.state == TaskState.TASK_STATE_WORKING
513+
assert not saved_task.status.HasField('timestamp')
514+
515+
516+
@pytest.mark.asyncio
517+
async def test_save_task_event_stamps_raw_failed_task_without_timestamp(
518+
task_manager: TaskManager, mock_task_store: AsyncMock
519+
) -> None:
520+
"""The raw-Task path (direct mutation failure sites) is guarded too
521+
(#1331)."""
522+
failing_task = create_minimal_task()
523+
failing_task.status.state = TaskState.TASK_STATE_FAILED
524+
525+
returned = await task_manager.save_task_event(failing_task)
526+
527+
assert returned.status.state == TaskState.TASK_STATE_FAILED
528+
assert returned.status.HasField('timestamp')

0 commit comments

Comments
 (0)