docs(agentex): trim SSE/status comments to terse one-liners

Comment-only change; no behavior change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: deepthi-rao-scale

agentex/src/domain/entities/tasks.py

@@ -29,15 +29,9 @@ class TaskStatus(str, Enum):
     DELETED = "DELETED"
 
 
-# Canonical status partition (single source of truth for both the task-status
-# state machine and SSE stream termination).
-#
-# Non-terminal: a turn is in flight (RUNNING) or the task is paused and
-# resumable (INTERRUPTED). A task may only transition to a terminal status from
-# one of these. Terminal is the complement: no further events are produced and
-# no new turns are accepted. Defining terminal as the complement means a newly
-# added status is treated as terminal unless it is explicitly listed as
-# non-terminal here.
+# Canonical status partition (state machine + SSE termination).
+# Non-terminal: RUNNING or INTERRUPTED (resumable); terminal is the rest.
+# New statuses are terminal unless added to the non-terminal set.
 NON_TERMINAL_TASK_STATUSES = frozenset({TaskStatus.RUNNING, TaskStatus.INTERRUPTED})
 TERMINAL_TASK_STATUSES = frozenset(TaskStatus) - NON_TERMINAL_TASK_STATUSES
 

agentex/src/domain/use_cases/streams_use_case.py

@@ -103,26 +103,12 @@ async def stream_task_events(
             task_id = task.id
 
         stream_topic = get_task_event_stream_topic(task_id=task_id)
-        # Snapshot the read cursor BEFORE reading task status (and before yielding
-        # "connected"). Ordering is load-bearing for two reasons:
-        #   1. A terminal transition writes the DB *before* it XADDs its
-        #      task_updated event. Snapshotting the tail first means that if the
-        #      status read below still says non-terminal, the terminal event (if
-        #      one is racing in) is guaranteed to land *after* this cursor, so the
-        #      live loop will read it — no missed-terminal zombie.
-        #   2. "connected" is the client's cue to send its message, which makes
-        #      the agent start XADD-ing deltas; snapshotting after that yield
-        #      could let the first deltas advance the tail and be skipped.
-        # Resolves to "0-0" (from the beginning) when the stream is empty.
+        # Cursor before status read: catches a racing terminal event.
         last_id = await self.stream_repository.get_stream_tail_id(stream_topic)
-        # Authoritative connect-time check. If the task is ALREADY terminal, any
-        # terminal event sits behind the live tail and the read loop below would
-        # never surface it — so replay whatever is buffered and end here. This
-        # handles the late-connect case deterministically (no polling needed);
-        # the in-loop check below handles a task that finishes while streaming.
         task = await self.task_service.get_task(id=task_id)
         # Send initial connection data
         yield f"data: {TaskStreamConnectedEventEntity(type='connected', taskId=task_id).model_dump_json()}\n\n"
+        # Already terminal: replay buffered events and end (late connect).
         if task.status in TERMINAL_TASK_STATUSES:
             async for _id, data in self.read_messages(topic=stream_topic, last_id="0"):
                 yield f"data: {data.model_dump_json()}\n\n"
@@ -158,8 +144,7 @@ async def stream_task_events(
                         data_str = f"data: {data.model_dump_json()}\n\n"
                         yield data_str
                         last_message_time = asyncio.get_running_loop().time()
-                        # A terminal task_updated is always the last event
-                        # produced, so nothing follows it — end the stream here.
+                        # Terminal event is the last one — end here.
                         if (
                             isinstance(data, TaskStreamTaskUpdatedEventEntity)
                             and data.task is not None
@@ -176,8 +161,7 @@ async def stream_task_events(
                     # healthy again, so reset the backoff/error counter.
                     consecutive_errors = 0
 
-                    # No messages this cycle: send a keepalive ping on the
-                    # configured interval so proxies don't reap an idle stream.
+                    # Idle: send keepalive ping so proxies don't reap us.
                     if message_count == 0:
                         current_time = asyncio.get_running_loop().time()
                         if current_time - last_message_time >= ping_interval:
@@ -224,9 +208,7 @@ async def stream_task_events(
             )
             yield f"data: {TaskStreamErrorEventEntity(type='error', message=str(e)).model_dump_json()}\n\n"
         finally:
-            # No cleanup_stream here: the topic is shared by all viewers of the
-            # task, so deleting it on one subscriber's exit would break the
-            # others. The sliding TTL reclaims it instead.
+            # Don't delete the shared topic; the TTL reclaims it.
             logger.info(f"SSE stream for task {task_id} has ended")
 
 

agentex/src/domain/use_cases/tasks_use_case.py

@@ -137,10 +137,7 @@ async def update_mutable_fields_on_task(
 
         return task_entity
 
-    # Statuses a task can be transitioned to a terminal status from: RUNNING is
-    # the normal case; INTERRUPTED (paused, still-continuable) can also still be
-    # canceled/completed/etc later. This is exactly the canonical non-terminal
-    # set — its complement is what SSE streaming treats as terminal.
+    # Statuses a task can transition to terminal from (the non-terminal set).
     _TERMINAL_TRANSITION_SOURCES = NON_TERMINAL_TASK_STATUSES
 
     async def _transition_to_terminal(