Skip to content

Commit 69f48e1

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 a59bb68 commit 69f48e1

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
@@ -979,6 +979,9 @@ async def cancel(
979979
updated = Task()
980980
updated.CopyFrom(task)
981981
updated.status.state = TaskState.TASK_STATE_CANCELED
982+
# CopyFrom carried over the previous state's timestamp; a terminal
983+
# transition has to be stamped with its own time.
984+
updated.status.timestamp.FromDatetime(datetime.now(timezone.utc))
982985
await self._task_manager.save_task_event(updated)
983986
task = updated
984987
return task
@@ -1113,6 +1116,7 @@ async def _mark_task_as_failed(self, exception: Exception) -> Task | None:
11131116
context_id=task.context_id,
11141117
status=TaskStatus(
11151118
state=TaskState.TASK_STATE_FAILED,
1119+
timestamp=datetime.now(timezone.utc),
11161120
),
11171121
)
11181122
)

‎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
@@ -354,6 +355,9 @@ async def _write_cancel(
354355
cancelled = Task()
355356
cancelled.CopyFrom(current)
356357
cancelled.status.state = TaskState.TASK_STATE_CANCELED
358+
# CopyFrom carried over the previous state's timestamp; stamping here
359+
# also covers the event built from this status below.
360+
cancelled.status.timestamp.FromDatetime(datetime.now(timezone.utc))
357361
event = TaskStatusUpdateEvent(
358362
task_id=task_id,
359363
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
@@ -3669,6 +3669,21 @@ async def cancel(self, context: RequestContext, event_queue: EventQueue):
36693669
pass
36703670

36713671

3672+
class ExplodingExecutor(AgentExecutor):
3673+
"""Creates the task, then crashes mid-flight (issue #1331)."""
3674+
3675+
task_id = None
3676+
3677+
async def execute(self, context: RequestContext, event_queue: EventQueue):
3678+
task = new_task_from_user_message(context.message)
3679+
self.task_id = task.id
3680+
await event_queue.enqueue_event(task)
3681+
raise RuntimeError('agent crashed mid-flight')
3682+
3683+
async def cancel(self, context: RequestContext, event_queue: EventQueue):
3684+
pass
3685+
3686+
36723687
@pytest.mark.asyncio
36733688
async def test_on_message_send_raises_when_agent_produces_no_events():
36743689
"""A silent executor must fail fast instead of hanging forever (#1330)."""
@@ -3718,3 +3733,37 @@ async def test_on_message_send_stream_raises_when_agent_produces_no_events():
37183733
params, create_server_call_context()
37193734
):
37203735
pass
3736+
3737+
3738+
@pytest.mark.asyncio
3739+
async def test_framework_failure_persists_timestamp_on_failed_task():
3740+
"""A framework-written FAILED status carries a timestamp (#1331)."""
3741+
task_store = InMemoryTaskStore()
3742+
executor = ExplodingExecutor()
3743+
request_handler = DefaultRequestHandlerV2(
3744+
agent_executor=executor,
3745+
task_store=task_store,
3746+
agent_card=create_default_agent_card(),
3747+
)
3748+
params = SendMessageRequest(
3749+
message=Message(
3750+
role=Role.ROLE_USER,
3751+
message_id='msg_explode',
3752+
parts=[Part(text='Hi')],
3753+
),
3754+
configuration=SendMessageConfiguration(
3755+
accepted_output_modes=['text/plain']
3756+
),
3757+
)
3758+
3759+
with pytest.raises(RuntimeError, match='agent crashed mid-flight'):
3760+
await request_handler.on_message_send(
3761+
params, create_server_call_context()
3762+
)
3763+
3764+
stored = await task_store.get(
3765+
executor.task_id, create_server_call_context()
3766+
)
3767+
assert stored is not None
3768+
assert stored.status.state == TaskState.TASK_STATE_FAILED
3769+
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)