minor changes

Author: riturajFi

src/server/core/acontext_core/infra/db.py

@@ -197,6 +197,8 @@ async def create_tables(self) -> None:
         logger.info("pgvector extension init")
         async with self.engine.begin() as conn:
             await conn.run_sync(ORM_BASE.metadata.create_all)
+        # Apply idempotent schema patches after the ORM tables exist so older
+        # deployments pick up the new session title column without a manual migration.
         await self._apply_schema_migrations()
 
         self._table_created = True

src/server/core/acontext_core/infra/schema_migrations.py

@@ -2,6 +2,8 @@
 from sqlalchemy.ext.asyncio import AsyncSession
 
 DISPLAY_TITLE_COLUMN_PATCH_NAME = "sessions.display_title"
+# Use IF NOT EXISTS so the patch is safe on both fresh databases and older
+# deployments that may already have the new column.
 DISPLAY_TITLE_COLUMN_PATCH_SQL = text(
     "ALTER TABLE sessions ADD COLUMN IF NOT EXISTS display_title TEXT;"
 )

src/server/core/acontext_core/llm/complete/mock_sdk.py

@@ -32,7 +32,8 @@ async def mock_complete(
     - If prompt contains "SESSION_TITLE_E2E" -> Create one deterministic task, then stop
     - Otherwise return a generic response
     """
-    # Safe handling of mutable default arguments
+    # Accept both dict-shaped messages and SDK objects so the mock can stand in
+    # for the different response-to-message adapters used across the codebase.
     history_messages = history_messages or []
     prompt_kwargs = prompt_kwargs or {}
     prompt_id = prompt_kwargs.get("prompt_id", "mock-prompt")
@@ -70,7 +71,9 @@ async def mock_complete(
             )
         ]
     elif "SESSION_TITLE_E2E" in full_text:
+        # The live e2e test uses this trigger to force one deterministic task.
         if "Task 1 created" in full_text:
+            # After the first tool round, return plain content so the agent stops.
             content = "Session title task captured"
             tool_calls = None
         else:

src/server/core/acontext_core/schema/orm/session.py

@@ -56,6 +56,8 @@ class Session(CommonMixin):
         default=None, metadata={"db": Column(JSONB, nullable=True)}
     )
 
+    # Generated, user-facing label for the session. It stays nullable until the
+    # first real task description is available.
     display_title: Optional[str] = field(
         default=None, metadata={"db": Column(Text, nullable=True)}
     )

src/server/core/acontext_core/service/controller/message.py

@@ -91,13 +91,17 @@ async def process_session_pending_message(
                 for m in messages
             ]
 
+        # Resolve the learning-space link in a separate short-lived transaction
+        # so the message status update path stays focused on queue state.
         ls_session = None
         async with DB_CLIENT.get_session_context() as session:
             r = await LS.get_learning_space_for_session(session, session_id)
             _ls_session, eil = r.unpack()
             if eil is None:
                 ls_session = _ls_session
 
+        # Run the agent only after the read-only lookups are complete so the
+        # long-running LLM work does not hold the earlier DB session open.
         agent_result = await AT.task_agent_curd(
             project_id,
             session_id,
@@ -118,6 +122,8 @@ async def process_session_pending_message(
         else:
             wide["task_agent_outcome"] = "success"
 
+        # Persist the final status in a fresh transaction so the message rows
+        # reflect the agent result even if the agent work was slow.
         async with DB_CLIENT.get_session_context() as db_session:
             await MD.update_message_status_to(
                 db_session, pending_message_ids, after_status

src/server/core/acontext_core/service/data/session.py

@@ -16,6 +16,8 @@ async def fetch_session(
 async def update_session_display_title(
     db_session: AsyncSession, session_id: asUUID, display_title: str
 ) -> Result[None]:
+    # Force-write helper used by callers that intentionally want to replace a
+    # previously generated title.
     session_record = await db_session.get(Session, session_id)
     if session_record is None:
         return Result.reject(f"Session {session_id} not found")
@@ -32,6 +34,7 @@ async def update_session_display_title_once(
     session_record, eil = (await fetch_session(db_session, session_id)).unpack()
     if eil:
         return Result.reject(eil.errmsg)
+    # Preserve the first non-empty title we have already stored.
     if (session_record.display_title or "").strip():
         return Result.resolve(False)
     session_record.display_title = display_title
@@ -46,6 +49,7 @@ async def should_generate_session_display_title(
     session_record, eil = r.unpack()
     if eil:
         return Result.reject(eil.errmsg)
+    # Empty strings are treated the same as NULL so we can regenerate blanks.
     return Result.resolve(
         session_record.display_title is None
         or session_record.display_title.strip() == ""

src/server/core/acontext_core/service/data/task.py

@@ -90,6 +90,7 @@ async def fetch_current_tasks(
 async def fetch_first_task_description(
     db_session: AsyncSession, session_id: asUUID
 ) -> Result[str | None]:
+    # The session title mirrors the first real task, not the planning section.
     query = (
         select(Task)
         .where(Task.session_id == session_id)
@@ -105,6 +106,7 @@ async def fetch_first_task_description(
 async def _sync_session_display_title(
     db_session: AsyncSession, session_id: asUUID
 ) -> None:
+    # Best-effort sync: only write when we have a non-empty title candidate.
     title, eil = (await fetch_first_task_description(db_session, session_id)).unpack()
     if eil is None and title:
         await SD.update_session_display_title_once(db_session, session_id, title)
@@ -139,6 +141,7 @@ async def update_task(
         flag_modified(task, "data")
 
     await db_session.flush()
+    # Flush first so the title lookup sees the final task state for this edit.
     await _sync_session_display_title(db_session, task.session_id)
     # Changes will be committed when the session context exits
     return Result.resolve(task)
@@ -193,6 +196,8 @@ async def insert_task(
 
     db_session.add(task)
     await db_session.flush()
+    # Insertions can change the first visible task, so sync the title after the
+    # new row is persisted.
     await _sync_session_display_title(db_session, session_id)
     return Result.resolve(task)
 

src/server/core/tests/llm/test_mock_sdk.py

@@ -145,6 +145,7 @@ async def test_fetch_tasks_no_results(self, db_client):
 class TestFetchFirstTaskDescription:
     @pytest.mark.asyncio
     async def test_returns_first_non_planning_task_by_order(self, db_client):
+        # Planning tasks are excluded so the title comes from the first real task.
         async with db_client.get_session_context() as session:
             project = Project(
                 secret_key_hmac="task_title_h1", secret_key_hash_phc="task_title_h1"
@@ -190,6 +191,7 @@ async def test_returns_first_non_planning_task_by_order(self, db_client):
 
     @pytest.mark.asyncio
     async def test_returns_none_without_non_planning_tasks(self, db_client):
+        # A planning-only session should not produce a title candidate.
         async with db_client.get_session_context() as session:
             project = Project(
                 secret_key_hmac="task_title_h2", secret_key_hash_phc="task_title_h2"