From a91db86cc02a005335e215525bd43e678492cd97 Mon Sep 17 00:00:00 2001
From: Ahmad Haidar <ahmad.haidar.syr@gmail.com>
Date: Wed, 22 Oct 2025 18:56:15 +0300
Subject: [PATCH 1/2] feat(agents-api): Add updated_at field to list_docs query
 and sorting functionality

---
 .../agents_api/queries/docs/list_docs.py      | 16 ++++--
 src/agents-api/tests/test_docs_queries.py     | 51 +++++++++++++++++++
 2 files changed, 64 insertions(+), 3 deletions(-)

diff --git a/src/agents-api/agents_api/queries/docs/list_docs.py b/src/agents-api/agents_api/queries/docs/list_docs.py
index f5dbcb48b..b6e61b97b 100644
--- a/src/agents-api/agents_api/queries/docs/list_docs.py
+++ b/src/agents-api/agents_api/queries/docs/list_docs.py
@@ -34,7 +34,8 @@
     d.embedding_dimensions,
     d.language,
     d.metadata,
-    d.created_at
+    d.created_at,
+    d.updated_at
 FROM docs d
 JOIN doc_owners doc_own
     ON d.developer_id = doc_own.developer_id
@@ -47,6 +48,12 @@
     AND doc_own.owner_id = $4
 """
 
+# AIDEV-NOTE: map exposed sort keys to fully-qualified columns to avoid join ambiguity
+SORT_COLUMN_MAP: dict[str, str] = {
+    "created_at": "d.created_at",
+    "updated_at": "d.updated_at",
+}
+
 
 @rewrap_exceptions(common_db_exceptions("doc", ["list"]))
 @wrap_in_class(
@@ -128,11 +135,14 @@ async def list_docs(
         d.embedding_dimensions,
         d.language,
         d.metadata,
-        d.created_at"""
+        d.created_at,
+        d.updated_at"""
 
     # Add sorting and pagination
+    order_column = SORT_COLUMN_MAP[sort_by]
+    direction_sql = "ASC" if direction == "asc" else "DESC"
     query += (
-        f" ORDER BY {sort_by} {direction} LIMIT ${len(params) + 1} OFFSET ${len(params) + 2}"
+        f" ORDER BY {order_column} {direction_sql} LIMIT ${len(params) + 1} OFFSET ${len(params) + 2}"
     )
     params.extend([limit, offset])
 
diff --git a/src/agents-api/tests/test_docs_queries.py b/src/agents-api/tests/test_docs_queries.py
index f732888c4..d2a796746 100644
--- a/src/agents-api/tests/test_docs_queries.py
+++ b/src/agents-api/tests/test_docs_queries.py
@@ -1,3 +1,4 @@
+import asyncio
 from uuid import uuid4
 
 from agents_api.autogen.openapi_model import CreateDocRequest, Doc
@@ -346,6 +347,56 @@ async def _(dsn=pg_dsn, developer=test_developer, user=test_user):
     assert exc.raised.detail == "Invalid sort direction"
 
 
+@test("queries filters test... list docs sorted by updated_at uses latest timestamps")
+async def _(dsn=pg_dsn, developer=test_developer, user=test_user):
+    pool = await create_db_pool(dsn=dsn)
+
+    shared_metadata = {"sort_group": "updated_at_sort_regression"}
+
+    first_doc = await create_doc(
+        developer_id=developer.id,
+        data=CreateDocRequest(
+            title="Sort regression doc 1",
+            content="content one",
+            metadata=shared_metadata,
+            embed_instruction="Embed",
+        ),
+        owner_type="user",
+        owner_id=user.id,
+        connection_pool=pool,
+    )
+
+    # Ensure the second document has a greater updated_at timestamp
+    await asyncio.sleep(0.01)
+
+    second_doc = await create_doc(
+        developer_id=developer.id,
+        data=CreateDocRequest(
+            title="Sort regression doc 2",
+            content="content two",
+            metadata=shared_metadata,
+            embed_instruction="Embed",
+        ),
+        owner_type="user",
+        owner_id=user.id,
+        connection_pool=pool,
+    )
+
+    docs = await list_docs(
+        developer_id=developer.id,
+        owner_type="user",
+        owner_id=user.id,
+        connection_pool=pool,
+        metadata_filter=shared_metadata,
+        sort_by="updated_at",
+        direction="desc",
+    )
+
+    assert len(docs) >= 2
+    assert docs[0].id == second_doc.id
+    assert docs[1].id == first_doc.id
+
+
 @test("query: list agent docs")
 async def _(dsn=pg_dsn, developer=test_developer, agent=test_agent):
     pool = await create_db_pool(dsn=dsn)

From 5514730033bbf47ba9e07cc626a6d606aae1bb7c Mon Sep 17 00:00:00 2001
From: Ahmad-mtos <Ahmad-mtos@users.noreply.github.com>
Date: Wed, 22 Oct 2025 15:58:59 +0000
Subject: [PATCH 2/2] refactor: Lint agents-api (CI)

---
 src/agents-api/agents_api/queries/docs/list_docs.py | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/src/agents-api/agents_api/queries/docs/list_docs.py b/src/agents-api/agents_api/queries/docs/list_docs.py
index b6e61b97b..df9ea9da3 100644
--- a/src/agents-api/agents_api/queries/docs/list_docs.py
+++ b/src/agents-api/agents_api/queries/docs/list_docs.py
@@ -141,9 +141,7 @@ async def list_docs(
     # Add sorting and pagination
     order_column = SORT_COLUMN_MAP[sort_by]
     direction_sql = "ASC" if direction == "asc" else "DESC"
-    query += (
-        f" ORDER BY {order_column} {direction_sql} LIMIT ${len(params) + 1} OFFSET ${len(params) + 2}"
-    )
+    query += f" ORDER BY {order_column} {direction_sql} LIMIT ${len(params) + 1} OFFSET ${len(params) + 2}"
     params.extend([limit, offset])
 
     return query, params