Skip to content

Commit c923c37

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 11f1116 commit c923c37

5 files changed

Lines changed: 177 additions & 0 deletions

File tree

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -971,6 +971,9 @@ async def cancel(self, call_context: ServerCallContext) -> Task:
971971
updated = Task()
972972
updated.CopyFrom(task)
973973
updated.status.state = TaskState.TASK_STATE_CANCELED
974+
# CopyFrom carried over the previous state's timestamp; a terminal
975+
# transition has to be stamped with its own time.
976+
updated.status.timestamp.FromDatetime(datetime.now(timezone.utc))
974977
await self._task_manager.save_task_event(updated)
975978
task = updated
976979
return task
@@ -1105,6 +1108,7 @@ async def _mark_task_as_failed(self, exception: Exception) -> Task | None:
11051108
context_id=task.context_id,
11061109
status=TaskStatus(
11071110
state=TaskState.TASK_STATE_FAILED,
1111+
timestamp=datetime.now(timezone.utc),
11081112
),
11091113
)
11101114
)

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
import warnings
66

77
from contextlib import aclosing
8+
from datetime import datetime, timezone
89
from typing import TYPE_CHECKING, Any, cast
910

1011
from a2a.plugins.manager import get_global
@@ -353,6 +354,9 @@ async def _write_cancel(
353354
cancelled = Task()
354355
cancelled.CopyFrom(current)
355356
cancelled.status.state = TaskState.TASK_STATE_CANCELED
357+
# CopyFrom carried over the previous state's timestamp; stamping here
358+
# also covers the event built from this status below.
359+
cancelled.status.timestamp.FromDatetime(datetime.now(timezone.utc))
356360
event = TaskStatusUpdateEvent(
357361
task_id=task_id,
358362
context_id=current.context_id,

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
import logging
44

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

78
from a2a.plugins.types import TaskEventInfo
@@ -14,6 +15,7 @@
1415
TaskStatus,
1516
TaskStatusUpdateEvent,
1617
)
18+
from a2a.utils.constants import TERMINAL_TASK_STATES
1719
from a2a.utils.errors import InvalidAgentResponseError, InvalidParamsError
1820
from a2a.utils.telemetry import trace_function
1921

@@ -220,6 +222,16 @@ async def get_task(self) -> Task | None:
220222
logger.debug('Task %s not found.', self.task_id)
221223
return self._current_task
222224

225+
def _stamp_terminal_timestamp(
226+
self, holder: Task | TaskStatusUpdateEvent
227+
) -> None:
228+
"""Auto-stamps a terminal status that arrives without a timestamp."""
229+
if (
230+
holder.status.state in TERMINAL_TASK_STATES
231+
and not holder.status.HasField('timestamp')
232+
):
233+
holder.status.timestamp.FromDatetime(datetime.now(timezone.utc))
234+
223235
async def save_task_event(
224236
self, event: Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent
225237
) -> Task | None:
@@ -260,6 +272,7 @@ async def save_task_event(
260272
task_id_from_event,
261273
)
262274
if isinstance(event, Task):
275+
self._stamp_terminal_timestamp(event)
263276
self._pending_event = event
264277
try:
265278
await self._save_task(event)
@@ -278,6 +291,10 @@ async def save_task_event(
278291
logger.debug(
279292
'Updating task %s status to: %s', task.id, event.status.state
280293
)
294+
# Stamped on the event, not the copy below: the same event object
295+
# is published to subscribers, push notifications and the event
296+
# table, so it has to carry the timestamp too.
297+
self._stamp_terminal_timestamp(event)
281298
if task.status.HasField('message'):
282299
task.history.append(task.status.message)
283300
if event.metadata:

‎tests/server/request_handlers/test_default_request_handler_v2.py‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3369,3 +3369,52 @@ async def test_failed_cancel_restarts_idle_release() -> None:
33693369

33703370
assert await _wait_for_release(handler, task.id)
33713371
await handler.aclose()
3372+
3373+
3374+
class ExplodingExecutor(AgentExecutor):
3375+
"""Creates the task, then crashes mid-flight (issue #1331)."""
3376+
3377+
task_id = None
3378+
3379+
async def execute(self, context: RequestContext, event_queue: EventQueue):
3380+
task = new_task_from_user_message(context.message)
3381+
self.task_id = task.id
3382+
await event_queue.enqueue_event(task)
3383+
raise RuntimeError('agent crashed mid-flight')
3384+
3385+
async def cancel(self, context: RequestContext, event_queue: EventQueue):
3386+
pass
3387+
3388+
3389+
@pytest.mark.asyncio
3390+
async def test_framework_failure_persists_timestamp_on_failed_task():
3391+
"""A framework-written FAILED status carries a timestamp (#1331)."""
3392+
task_store = InMemoryTaskStore()
3393+
executor = ExplodingExecutor()
3394+
request_handler = DefaultRequestHandlerV2(
3395+
agent_executor=executor,
3396+
task_store=task_store,
3397+
agent_card=create_default_agent_card(),
3398+
)
3399+
params = SendMessageRequest(
3400+
message=Message(
3401+
role=Role.ROLE_USER,
3402+
message_id='msg_explode',
3403+
parts=[Part(text='Hi')],
3404+
),
3405+
configuration=SendMessageConfiguration(
3406+
accepted_output_modes=['text/plain']
3407+
),
3408+
)
3409+
3410+
with pytest.raises(RuntimeError, match='agent crashed mid-flight'):
3411+
await request_handler.on_message_send(
3412+
params, create_server_call_context()
3413+
)
3414+
3415+
stored = await task_store.get(
3416+
executor.task_id, create_server_call_context()
3417+
)
3418+
assert stored is not None
3419+
assert stored.status.state == TaskState.TASK_STATE_FAILED
3420+
assert stored.status.HasField('timestamp')

‎tests/server/tasks/test_task_manager.py‎

Lines changed: 103 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

@@ -20,6 +21,7 @@
2021
TaskStatusUpdateEvent,
2122
)
2223
from a2a.utils.errors import InvalidAgentResponseError, InvalidParamsError
24+
from google.protobuf.timestamp_pb2 import Timestamp
2325

2426

2527
class SampleUser(User):
@@ -509,3 +511,104 @@ def test_append_artifact_to_task():
509511
match='append=True for nonexistent artifact_id',
510512
):
511513
append_artifact_to_task(task, append_event_5)
514+
515+
516+
@pytest.mark.asyncio
517+
async def test_save_task_event_stamps_terminal_status_without_timestamp(
518+
task_manager: TaskManager, mock_task_store: AsyncMock
519+
) -> None:
520+
"""Terminal states arriving unstamped are auto-stamped (#1331)."""
521+
initial_task = create_minimal_task()
522+
mock_task_store.get.return_value = initial_task
523+
event = TaskStatusUpdateEvent(
524+
task_id=MINIMAL_TASK_ID,
525+
context_id=MINIMAL_CONTEXT_ID,
526+
status=TaskStatus(state=TaskState.TASK_STATE_FAILED),
527+
)
528+
529+
await task_manager.save_task_event(event)
530+
531+
saved_task = mock_task_store.save.call_args[0][0]
532+
assert saved_task.status.state == TaskState.TASK_STATE_FAILED
533+
assert saved_task.status.HasField('timestamp')
534+
535+
536+
@pytest.mark.asyncio
537+
async def test_save_task_event_preserves_provided_terminal_timestamp(
538+
task_manager: TaskManager, mock_task_store: AsyncMock
539+
) -> None:
540+
"""An explicitly provided timestamp is never overwritten (#1331)."""
541+
initial_task = create_minimal_task()
542+
mock_task_store.get.return_value = initial_task
543+
provided = Timestamp()
544+
provided.FromDatetime(datetime(2026, 1, 1, tzinfo=timezone.utc))
545+
event = TaskStatusUpdateEvent(
546+
task_id=MINIMAL_TASK_ID,
547+
context_id=MINIMAL_CONTEXT_ID,
548+
status=TaskStatus(
549+
state=TaskState.TASK_STATE_FAILED, timestamp=provided
550+
),
551+
)
552+
553+
await task_manager.save_task_event(event)
554+
555+
saved_task = mock_task_store.save.call_args[0][0]
556+
assert saved_task.status.timestamp.ToDatetime(
557+
tzinfo=timezone.utc
558+
) == datetime(2026, 1, 1, tzinfo=timezone.utc)
559+
560+
561+
@pytest.mark.asyncio
562+
async def test_save_task_event_does_not_stamp_non_terminal_status(
563+
task_manager: TaskManager, mock_task_store: AsyncMock
564+
) -> None:
565+
"""Non-terminal states are left alone by the backstop (#1331)."""
566+
initial_task = create_minimal_task()
567+
mock_task_store.get.return_value = initial_task
568+
event = TaskStatusUpdateEvent(
569+
task_id=MINIMAL_TASK_ID,
570+
context_id=MINIMAL_CONTEXT_ID,
571+
status=TaskStatus(state=TaskState.TASK_STATE_WORKING),
572+
)
573+
574+
await task_manager.save_task_event(event)
575+
576+
saved_task = mock_task_store.save.call_args[0][0]
577+
assert saved_task.status.state == TaskState.TASK_STATE_WORKING
578+
assert not saved_task.status.HasField('timestamp')
579+
580+
581+
@pytest.mark.asyncio
582+
async def test_save_task_event_stamps_raw_failed_task_without_timestamp(
583+
task_manager: TaskManager, mock_task_store: AsyncMock
584+
) -> None:
585+
"""The raw-Task path (direct mutation failure sites) is guarded too
586+
(#1331)."""
587+
failing_task = create_minimal_task()
588+
failing_task.status.state = TaskState.TASK_STATE_FAILED
589+
590+
returned = await task_manager.save_task_event(failing_task)
591+
592+
assert returned.status.state == TaskState.TASK_STATE_FAILED
593+
assert returned.status.HasField('timestamp')
594+
595+
596+
@pytest.mark.asyncio
597+
async def test_save_task_event_stamps_the_published_event(
598+
task_manager: TaskManager, mock_task_store: AsyncMock
599+
) -> None:
600+
"""The caller's event object is stamped too, since the same instance is
601+
published to subscribers, push notifications and the event table."""
602+
initial_task = create_minimal_task()
603+
mock_task_store.get.return_value = initial_task
604+
event = TaskStatusUpdateEvent(
605+
task_id=MINIMAL_TASK_ID,
606+
context_id=MINIMAL_CONTEXT_ID,
607+
status=TaskStatus(state=TaskState.TASK_STATE_COMPLETED),
608+
)
609+
610+
await task_manager.save_task_event(event)
611+
612+
assert event.status.HasField('timestamp')
613+
saved_task = mock_task_store.save.call_args[0][0]
614+
assert saved_task.status.timestamp == event.status.timestamp

0 commit comments

Comments
 (0)