refactor(agentex): simplify entity converter, DRY test setup, tighten docstrings

- Replace manual field-by-field convert_task_to_entity with
  TaskEntity.model_validate(task) — future fields propagate automatically.
- Add test_running_task fixture; 5 of 6 current_state integration tests
  now share it instead of creating agent+task inline (~110 lines removed).
- Collapse multi-line docstrings to one line in repository and service.
- Remove redundant inline comments in use case.
- Remove stray print statement in stream integration test.

Author: qwhex

agentex/src/domain/entities/tasks.py

@@ -87,16 +87,4 @@ class TaskEntity(BaseModel):
 
 def convert_task_to_entity(task: Task) -> TaskEntity:
     """Converts the pydantic model from the API layer to the domain layer"""
-
-    return TaskEntity(
-        id=task.id,
-        name=task.name,
-        status=TaskStatus[task.status.value] if task.status is not None else None,
-        status_reason=task.status_reason,
-        created_at=task.created_at,
-        updated_at=task.updated_at,
-        cleaned_at=task.cleaned_at,
-        params=task.params,
-        task_metadata=task.task_metadata,
-        current_state=task.current_state,
-    )
+    return TaskEntity.model_validate(task)

agentex/src/domain/repositories/task_repository.py

@@ -243,11 +243,7 @@ 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 the given caller-mutable columns on one task row via
-        ``UPDATE ... RETURNING`` — 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 absent.
-        """
+        """Column-scoped atomic update; can't clobber status/params. Returns updated entity or None."""
         unknown = fields.keys() - _MUTABLE_TASK_COLUMNS
         if unknown:
             raise ValueError(
@@ -259,9 +255,7 @@ async def update_mutable_fields(
     async def _update_returning(
         self, task_id: str, values: dict[str, Any]
     ) -> TaskEntity | None:
-        """``UPDATE tasks SET <values> WHERE id`` → the updated entity, or ``None`` if no
-        such task exists. Shared by merge_params and update_mutable_fields.
-        """
+        """UPDATE … SET … WHERE id → updated entity or None. Shared by merge_params and update_mutable_fields."""
         async with (
             self.start_async_db_session(True) as session,
             async_sql_exception_handler(),

agentex/src/domain/services/task_service.py

@@ -222,9 +222,7 @@ async def update_task(self, task: TaskEntity) -> TaskEntity:
     async def update_mutable_fields(
         self, task_id: str, fields: dict[str, Any]
     ) -> TaskEntity | None:
-        """Column-scoped atomic update of the given columns, then publish task_updated.
-        Returns the updated entity, or ``None`` if the task no longer exists.
-        """
+        """Column-scoped atomic update, then publish task_updated. Returns updated entity or None."""
         updated_task = await self.task_repository.update_mutable_fields(task_id, fields)
         if updated_task is None:
             return None

agentex/src/domain/use_cases/tasks_use_case.py

@@ -115,19 +115,16 @@ async def update_mutable_fields_on_task(
             else:
                 raise ItemDoesNotExist(f"Task {name} not found")
 
-        # No-op if no mutable field was supplied.
         if task_metadata is None and merge_params is None and current_state is None:
             return task_entity
 
-        # 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
 
-        # 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
@@ -138,7 +135,6 @@ async def update_mutable_fields_on_task(
                 task_entity.id, fields
             )
             if updated is None:
-                # 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

@@ -57,6 +57,18 @@ async def test_pagination_tasks(self, isolated_repositories, test_agent):
             tasks.append(await task_repo.create(agent_id=test_agent.id, task=task))
         return tasks
 
+    @pytest_asyncio.fixture
+    async def test_running_task(self, isolated_repositories, test_agent):
+        """Create a minimal running task for tests that don't care about its name"""
+        task_repo = isolated_repositories["task_repository"]
+        task = TaskEntity(
+            id=orm_id(),
+            name=f"running-task-{orm_id()[:8]}",
+            status=TaskStatus.RUNNING,
+            status_reason="Running task for testing",
+        )
+        return await task_repo.create(agent_id=test_agent.id, task=task)
+
     @pytest_asyncio.fixture
     async def test_task_with_params(self, isolated_repositories, test_agent):
         """Create a test task with params directly via repository"""
@@ -506,8 +518,7 @@ async def test_get_task_by_name_non_existent_returns_404(self, isolated_client):
     async def test_list_tasks_omits_params_in_response(
         self, isolated_client, test_task_with_params
     ):
-        """The list summary must omit `params` (secrets/PII) but still carry the small
-        opaque `current_state` label; fetch a single task for the full record."""
+        """List summary omits params but carries current_state."""
         # When - Request all tasks
         response = await isolated_client.get("/tasks")
 
@@ -678,27 +689,10 @@ async def test_update_task_endpoint_success(
         assert response_data["task_metadata"]["metrics"]["complexity_score"] == 75
 
     async def test_update_task_current_state(
-        self, isolated_client, isolated_repositories
+        self, isolated_client, test_running_task
     ):
         """PUT current_state: set it, omitted leaves it untouched, point-read reconciles."""
-        agent_repo = isolated_repositories["agent_repository"]
-        agent = AgentEntity(
-            id=orm_id(),
-            name="current-state-agent",
-            description="Agent for current_state update testing",
-            acp_url="http://test-acp:8000",
-            acp_type=ACPType.SYNC,
-        )
-        await agent_repo.create(agent)
-
-        task_repo = isolated_repositories["task_repository"]
-        task = TaskEntity(
-            id=orm_id(),
-            name="task-for-current-state",
-            status=TaskStatus.RUNNING,
-            status_reason="Test task for current_state",
-        )
-        created_task = await task_repo.create(agent_id=agent.id, task=task)
+        created_task = test_running_task
 
         # Fresh task: current_state present in response and null by default.
         response = await isolated_client.get(f"/tasks/{created_task.id}")
@@ -725,27 +719,10 @@ async def test_update_task_current_state(
         assert response.json()["current_state"] == "awaiting_input"
 
     async def test_update_task_current_state_and_metadata_together(
-        self, isolated_client, isolated_repositories
+        self, isolated_client, test_running_task
     ):
         """current_state + task_metadata in one PUT both persist without clobbering status."""
-        agent_repo = isolated_repositories["agent_repository"]
-        agent = AgentEntity(
-            id=orm_id(),
-            name="current-state-combined-agent",
-            description="Agent for combined update testing",
-            acp_url="http://test-acp:8000",
-            acp_type=ACPType.SYNC,
-        )
-        await agent_repo.create(agent)
-
-        task_repo = isolated_repositories["task_repository"]
-        task = TaskEntity(
-            id=orm_id(),
-            name="task-for-combined-update",
-            status=TaskStatus.RUNNING,
-            status_reason="Test task for combined update",
-        )
-        created_task = await task_repo.create(agent_id=agent.id, task=task)
+        created_task = test_running_task
 
         response = await isolated_client.put(
             f"/tasks/{created_task.id}",
@@ -758,27 +735,17 @@ async def test_update_task_current_state_and_metadata_together(
         assert body["status"] == "RUNNING"
 
     async def test_update_task_current_state_by_name(
-        self, isolated_client, isolated_repositories
+        self, isolated_client, isolated_repositories, test_agent
     ):
         """PUT /tasks/name/{name} forwards current_state too."""
-        agent_repo = isolated_repositories["agent_repository"]
-        agent = AgentEntity(
-            id=orm_id(),
-            name="current-state-by-name-agent",
-            description="Agent for by-name current_state testing",
-            acp_url="http://test-acp:8000",
-            acp_type=ACPType.SYNC,
-        )
-        await agent_repo.create(agent)
-
         task_repo = isolated_repositories["task_repository"]
         task = TaskEntity(
             id=orm_id(),
             name="task-for-current-state-by-name",
             status=TaskStatus.RUNNING,
             status_reason="Test task for by-name current_state",
         )
-        await task_repo.create(agent_id=agent.id, task=task)
+        await task_repo.create(agent_id=test_agent.id, task=task)
 
         response = await isolated_client.put(
             "/tasks/name/task-for-current-state-by-name",
@@ -788,87 +755,30 @@ async def test_update_task_current_state_by_name(
         assert response.json()["current_state"] == "working"
 
     async def test_update_task_current_state_empty_string(
-        self, isolated_client, isolated_repositories
+        self, isolated_client, test_running_task
     ):
         """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(),
-            name="current-state-empty-agent",
-            description="Agent for empty-string current_state testing",
-            acp_url="http://test-acp:8000",
-            acp_type=ACPType.SYNC,
-        )
-        await agent_repo.create(agent)
-
-        task_repo = isolated_repositories["task_repository"]
-        task = TaskEntity(
-            id=orm_id(),
-            name="task-for-current-state-empty",
-            status=TaskStatus.RUNNING,
-            status_reason="Test task for empty current_state",
-        )
-        created_task = await task_repo.create(agent_id=agent.id, task=task)
-
         response = await isolated_client.put(
-            f"/tasks/{created_task.id}", json={"current_state": ""}
+            f"/tasks/{test_running_task.id}", json={"current_state": ""}
         )
         assert response.status_code == 200
         assert response.json()["current_state"] == ""
 
     async def test_update_task_current_state_too_long_rejected(
-        self, isolated_client, isolated_repositories
+        self, isolated_client, test_running_task
     ):
         """current_state exceeding the max length is rejected with 422."""
-        agent_repo = isolated_repositories["agent_repository"]
-        agent = AgentEntity(
-            id=orm_id(),
-            name="current-state-toolong-agent",
-            description="Agent for max-length current_state testing",
-            acp_url="http://test-acp:8000",
-            acp_type=ACPType.SYNC,
-        )
-        await agent_repo.create(agent)
-
-        task_repo = isolated_repositories["task_repository"]
-        task = TaskEntity(
-            id=orm_id(),
-            name="task-for-current-state-toolong",
-            status=TaskStatus.RUNNING,
-            status_reason="Test task for over-long current_state",
-        )
-        created_task = await task_repo.create(agent_id=agent.id, task=task)
-
         response = await isolated_client.put(
-            f"/tasks/{created_task.id}", json={"current_state": "x" * 256}
+            f"/tasks/{test_running_task.id}", json={"current_state": "x" * 256}
         )
         assert response.status_code == 422
 
     async def test_update_task_request_ignores_unknown_fields(
-        self, isolated_client, isolated_repositories
+        self, isolated_client, test_running_task
     ):
         """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(),
-            name="unknown-fields-agent",
-            description="Agent for unknown-field compat testing",
-            acp_url="http://test-acp:8000",
-            acp_type=ACPType.SYNC,
-        )
-        await agent_repo.create(agent)
-
-        task_repo = isolated_repositories["task_repository"]
-        task = TaskEntity(
-            id=orm_id(),
-            name="task-for-unknown-fields",
-            status=TaskStatus.RUNNING,
-            status_reason="Test task for unknown-field compat",
-        )
-        created_task = await task_repo.create(agent_id=agent.id, task=task)
-
         response = await isolated_client.put(
-            f"/tasks/{created_task.id}",
+            f"/tasks/{test_running_task.id}",
             json={"current_state": "working", "field_from_a_newer_sdk": "ignored"},
         )
         assert response.status_code == 200

agentex/tests/integration/test_task_stream.py

@@ -287,8 +287,6 @@ async def collect_stream_events():
 
         assert updated_task.current_state == "awaiting_input"
 
-        print("✅ current_state update successfully triggered stream event")
-
     async def test_get_task_returns_updated_metadata_after_stream_update(
         self, test_agent_and_task, tasks_use_case
     ):

agentex/tests/unit/services/test_task_service.py

@@ -992,9 +992,7 @@ 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 leaves status untouched
-        (the use-case stale-read clobber regression is guarded in test_tasks_use_case.py).
-        """
+        """Writing current_state leaves status untouched (column-scoped update)."""
         await create_or_get_agent(agent_repository, sample_agent)
         created_task = await task_service.create_task(
             agent=sample_agent, task_name="task-for-noclobber"

agentex/tests/unit/use_cases/test_tasks_use_case.py

@@ -662,9 +662,7 @@ async def test_update_current_state_does_not_clobber_concurrent_status(
         agent_repository,
         sample_agent,
     ):
-        """Regression: a stale RUNNING read racing a COMPLETED transition must not revert
-        status on the current_state write. Fails on the old whole-row merge, passes column-scoped.
-        """
+        """Stale-read race: current_state write must not revert a concurrent status transition."""
         await create_or_get_agent(agent_repository, sample_agent)
         task = await task_service.create_task(
             agent=sample_agent, task_name="current-state-clobber-test"