style(agentex): collapse verbose comments/docstrings to one line

Self-review cleanup: tighten the multi-line comments and docstrings added for
current_state down to single lines (drop AI-slop narration; keep only the
non-obvious why), per the repo's comment-discipline convention.

Author: qwhex

agentex/database/migrations/alembic/versions/2026_07_22_1200_add_task_current_state_b2c3d4e5f6a7.py

@@ -18,10 +18,7 @@
 
 
 def upgrade() -> None:
-    # Opaque label mirroring an agent's StateMachine current state. Nullable and
-    # additive; agents opt in by emitting it. Metadata-only add, non-blocking.
-    # Idempotent (IF NOT EXISTS) so re-running on an environment that already has
-    # the column is a no-op. Width matches TaskORM.current_state (String(255)).
+    # Nullable additive column; idempotent, metadata-only, non-blocking.
     op.execute(
         "ALTER TABLE tasks ADD COLUMN IF NOT EXISTS current_state VARCHAR(255)"
     )

agentex/src/adapters/orm.py

@@ -75,11 +75,7 @@ class TaskORM(BaseORM):
     cleaned_at = Column(DateTime(timezone=True), nullable=True)
     params = Column(JSONB, nullable=True)
     task_metadata = Column(JSONB, nullable=True)
-    # Opaque, framework-agnostic label mirroring an agent's StateMachine current
-    # state. Written best-effort by the agent on each transition; reconciled on
-    # read. Orthogonal to `status` (Temporal workflow lifecycle). Bounded: a
-    # state label is short, and the value is echoed onto every task_updated SSE
-    # payload, so we cap it to avoid unbounded stream amplification.
+    # Opaque agent-state label, orthogonal to `status`; capped since it rides every task_updated SSE payload.
     current_state = Column(String(255), nullable=True)
     # Many-to-Many relationship with agents
     agents = relationship("AgentORM", secondary="task_agents", back_populates="tasks")

agentex/src/api/routes/tasks.py

@@ -196,8 +196,7 @@ async def update_task(
         id=task_id,
         task_metadata=request.task_metadata,
         merge_params=request.merge_params,
-        # Pass through only when the client actually sent the key, so an explicit
-        # null clears the label while an omitted field leaves it untouched.
+        # Forward only when the client sent the key: explicit null clears, omitted leaves unchanged.
         current_state=(
             request.current_state
             if "current_state" in request.model_fields_set
@@ -224,8 +223,7 @@ async def update_task_by_name(
         name=task_name,
         task_metadata=request.task_metadata,
         merge_params=request.merge_params,
-        # Pass through only when the client actually sent the key, so an explicit
-        # null clears the label while an omitted field leaves it untouched.
+        # Forward only when the client sent the key: explicit null clears, omitted leaves unchanged.
         current_state=(
             request.current_state
             if "current_state" in request.model_fields_set

agentex/src/api/schemas/tasks.py

@@ -7,9 +7,7 @@
 from src.api.schemas.agents import Agent
 from src.utils.model_utils import BaseModel
 
-# Upper bound on the opaque `current_state` label. Kept in sync with the
-# `TaskORM.current_state` column width (String(255)); a state label is short and
-# the value rides every task_updated SSE payload, so it is capped.
+# Bound on the current_state label; mirrors the String(255) column width.
 CURRENT_STATE_MAX_LENGTH = 255
 
 
@@ -68,9 +66,7 @@ class Task(BaseModel):
         None,
         title="Task metadata",
     )
-    # No max_length on this response field on purpose: input is already bounded
-    # by UpdateTaskRequest + the String(255) column, and enforcing the bound on
-    # the read path would turn a future column-widening into a 500 on every read.
+    # No bound on the read path: enforcing it would 500 if the column is ever widened (writes are already bounded).
     current_state: str | None = Field(
         None,
         title=(

agentex/src/domain/repositories/task_repository.py

@@ -257,22 +257,11 @@ async def merge_params(self, task_id: str, patch: dict) -> TaskEntity | None:
     async def update_mutable_fields(
         self, task_id: str, fields: dict[str, Any]
     ) -> TaskEntity | None:
-        """Atomically set only the given scalar columns on a single task row.
-
-        Unlike ``update`` (a whole-row ``session.merge`` of a possibly-stale
-        entity, which rewrites every column and can clobber a concurrently
-        changed ``status``/``params``), this issues a single
-        ``UPDATE ... SET <only these columns> WHERE id = :id RETURNING *``.
-        Touching only the supplied columns means a concurrent status transition
-        or param merge is never reverted. With a non-empty ``fields`` this returns
-        the updated entity, or ``None`` if no task with ``task_id`` exists.
-
-        ``fields`` values are applied verbatim, so passing ``current_state=None``
-        clears the column (callers distinguish "clear" from "omit" upstream).
-
-        An empty ``fields`` is a defensive no-op that returns the current task
-        (raising ``ItemDoesNotExist`` if absent); the sole caller never reaches it,
-        as it gates the call behind a non-empty field set.
+        """Atomically ``UPDATE ... SET <only the given columns> WHERE id`` — column-scoped,
+        so (unlike ``update``'s whole-row merge) it can't clobber a concurrently changed
+        ``status``/``params``. Values apply verbatim (``current_state=None`` clears). Returns
+        the updated entity, or ``None`` if the task doesn't exist. Empty ``fields`` is an
+        unreachable defensive no-op (the sole caller gates on a non-empty set).
         """
         if not fields:
             return await self.get(id=task_id)

agentex/src/domain/services/task_service.py

@@ -245,14 +245,8 @@ async def update_task(self, task: TaskEntity) -> TaskEntity:
     async def update_mutable_fields(
         self, task_id: str, fields: dict[str, Any]
     ) -> TaskEntity | None:
-        """Atomically update only the given scalar columns on a task, then
-        publish a task_updated event.
-
-        Column-scoped (see ``TaskRepository.update_mutable_fields``) so it cannot
-        clobber a concurrently changed ``status``/``params`` — unlike
-        ``update_task``'s whole-row merge, which the status-writing callers
-        (delete/fail/forward) still rely on. Returns the updated entity, or
-        ``None`` if the task no longer exists.
+        """Column-scoped atomic update of the given columns, then publish task_updated.
+        Returns the updated entity, or ``None`` if the task no longer exists.
         """
         updated_task = await self.task_repository.update_mutable_fields(
             task_id, fields

agentex/src/domain/use_cases/tasks_use_case.py

@@ -12,9 +12,7 @@
 
 
 class _Unset:
-    """Sentinel distinguishing "field omitted" from "field explicitly set to null"
-    in a PATCH-style update, so an explicit null can clear a column while an
-    omitted field is left untouched."""
+    """Sentinel: PATCH field omitted (untouched) vs. explicitly null (cleared)."""
 
 
 UNSET: Any = _Unset()
@@ -106,11 +104,8 @@ async def update_mutable_fields_on_task(
         merge_params: dict[str, Any] | None = None,
         current_state: str | None | _Unset = UNSET,
     ) -> TaskEntity:
-        """Update mutable fields on a task entity. This is used by our API since not all fields should be mutable.
-
-        ``current_state`` uses the UNSET sentinel so an explicit null clears the
-        column while an omitted field leaves it untouched. ``task_metadata`` keeps
-        its legacy semantics (``None`` means "not supplied").
+        """Update mutable fields on a task. ``current_state`` uses the UNSET sentinel
+        (explicit null clears, omitted leaves it); ``task_metadata`` None means "not supplied".
         """
 
         if not id and not name:
@@ -134,21 +129,15 @@ async def update_mutable_fields_on_task(
         ):
             return task_entity
 
-        # `merge_params` is a separate atomic JSONB shallow-merge so concurrent
-        # callers don't overwrite each other's fields. Run it first so the
-        # refreshed entity it returns becomes the value we return if no scalar
-        # field updates follow.
+        # Atomic JSONB shallow-merge; run first so its refreshed entity is the fallback return.
         if merge_params:
             merged = await self.task_service.merge_task_params(
                 task_entity.id, merge_params
             )
             if merged is not None:
                 task_entity = merged
 
-        # Apply task_metadata/current_state via a single column-scoped atomic
-        # update — one task_updated publish, and (unlike a whole-row merge) no
-        # risk of clobbering a concurrently changed status/params. current_state
-        # rides that publish, powering reactive delivery to stream consumers.
+        # Single column-scoped write → one task_updated publish, no whole-row clobber.
         fields: dict[str, Any] = {}
         if task_metadata is not None:
             fields["task_metadata"] = task_metadata
@@ -159,11 +148,7 @@ async def update_mutable_fields_on_task(
                 task_entity.id, fields
             )
             if updated is None:
-                # The row vanished between the initial read and the write. No live
-                # hard-delete path reaches here today (delete is a soft status
-                # update, already guarded above), so this is defensive — but raise
-                # rather than return stale data, matching the not-found contract
-                # above and the sibling terminal-transition methods.
+                # Row vanished mid-flight (defensive; no live hard-delete path). Raise, don't return stale.
                 raise ItemDoesNotExist(f"Task {id or name} not found")
             task_entity = updated
 

agentex/tests/integration/api/tasks/test_tasks_api.py

@@ -686,8 +686,7 @@ async def test_update_task_endpoint_success(
     async def test_update_task_current_state(
         self, isolated_client, isolated_repositories
     ):
-        """PUT /tasks/{id} writes current_state; explicit null clears it while an
-        omitted field leaves it untouched; point-read is source of truth."""
+        """PUT current_state: explicit null clears, omitted leaves it, point-read reconciles."""
         agent_repo = isolated_repositories["agent_repository"]
         agent = AgentEntity(
             id=orm_id(),
@@ -743,8 +742,7 @@ async def test_update_task_current_state(
     async def test_update_task_current_state_and_metadata_together(
         self, isolated_client, isolated_repositories
     ):
-        """current_state + task_metadata in one PUT both persist (single write),
-        without clobbering status."""
+        """current_state + task_metadata in one PUT both persist without clobbering status."""
         agent_repo = isolated_repositories["agent_repository"]
         agent = AgentEntity(
             id=orm_id(),
@@ -807,8 +805,7 @@ async def test_update_task_current_state_by_name(
     async def test_update_task_current_state_empty_string(
         self, isolated_client, isolated_repositories
     ):
-        """Empty string is a valid label distinct from null (guards against a
-        future falsy check treating "" as "unset")."""
+        """Empty string is a valid label distinct from null (guards a falsy-check regression)."""
         agent_repo = isolated_repositories["agent_repository"]
         agent = AgentEntity(
             id=orm_id(),
@@ -865,9 +862,7 @@ async def test_update_task_current_state_too_long_rejected(
     async def test_update_task_request_ignores_unknown_fields(
         self, isolated_client, isolated_repositories
     ):
-        """Guards the extra="ignore" assumption a newer SDK relies on: a payload
-        carrying fields the server doesn't model must 200 (drop them), not 422.
-        Breaks loudly if UpdateTaskRequest ever switches to extra="forbid"."""
+        """Unknown fields are ignored (200, not 422) — guards the extra="ignore" SDK-compat assumption."""
         agent_repo = isolated_repositories["agent_repository"]
         agent = AgentEntity(
             id=orm_id(),

agentex/tests/integration/test_task_stream.py

@@ -233,8 +233,7 @@ async def collect_stream_events():
     async def test_current_state_update_triggers_stream_event(
         self, test_agent_and_task, tasks_use_case, streams_use_case
     ):
-        """current_state rides the existing task_updated event, so a client
-        subscribed to the task stream is pushed the new state reactively."""
+        """current_state rides the existing task_updated event (reactive push to subscribers)."""
         _agent, task = test_agent_and_task
 
         stream_events = []
@@ -260,23 +259,20 @@ async def collect_stream_events():
                 pass
 
         stream_task = asyncio.create_task(collect_stream_events())
-        # Let the subscription establish before the update; the stream is
-        # tail-only, so an event published before we subscribe would be missed.
+        # Let the tail-only subscription establish before the update, or the event is missed.
         await asyncio.sleep(0.1)
 
         updated_task = await tasks_use_case.update_mutable_fields_on_task(
             id=task.id, current_state="awaiting_input"
         )
 
-        # Wait until the collector sees task_updated (it breaks on it) rather
-        # than guessing a fixed delay; the timeout is only a failure ceiling.
+        # Wait for the collector to see task_updated (it breaks on it); timeout is only a ceiling.
         try:
             async with asyncio.timeout(5):
                 await stream_task
         except (TimeoutError, asyncio.CancelledError):
             stream_task.cancel()
-            # Re-await so the task's own cancellation cleanup runs and no
-            # "Task exception was never retrieved" warning leaks at teardown.
+            # Re-await so cancellation cleanup runs and no dangling-task warning leaks at teardown.
             await asyncio.gather(stream_task, return_exceptions=True)
 
         task_updated_events = [

agentex/tests/unit/services/test_task_service.py

@@ -941,8 +941,7 @@ async def test_update_task_with_task_metadata_changes(
     async def test_update_task_current_state_publishes_stream_event(
         self, task_service, agent_repository, sample_agent, redis_stream_repository
     ):
-        """update_task persists current_state and carries it on the published
-        task_updated event, so subscribed clients see the new state."""
+        """update_task persists current_state and carries it on the task_updated event."""
         await create_or_get_agent(agent_repository, sample_agent)
         created_task = await task_service.create_task(
             agent=sample_agent, task_name="task-for-current-state"
@@ -967,8 +966,7 @@ async def test_update_task_current_state_publishes_stream_event(
     async def test_update_mutable_fields_persists_and_publishes(
         self, task_service, agent_repository, sample_agent, redis_stream_repository
     ):
-        """update_mutable_fields writes only the given columns and publishes a
-        task_updated event carrying them."""
+        """update_mutable_fields persists the given columns and publishes task_updated."""
         await create_or_get_agent(agent_repository, sample_agent)
         created_task = await task_service.create_task(
             agent=sample_agent, task_name="task-for-mutable-fields"
@@ -994,10 +992,9 @@ async def test_update_mutable_fields_persists_and_publishes(
     async def test_update_mutable_fields_leaves_status_untouched(
         self, task_service, agent_repository, sample_agent, redis_stream_repository
     ):
-        """The primitive is column-scoped: writing current_state does not touch
-        status. (The use-case-level clobber regression — a stale read racing a
-        status transition — is guarded in test_tasks_use_case.py; this only pins
-        that the repository UPDATE sets no columns beyond those supplied.)"""
+        """The primitive is column-scoped: writing current_state leaves status untouched
+        (the use-case stale-read clobber regression is guarded in test_tasks_use_case.py).
+        """
         await create_or_get_agent(agent_repository, sample_agent)
         created_task = await task_service.create_task(
             agent=sample_agent, task_name="task-for-noclobber"