agentengine-sdk-python 0.7.0__py3-none-any.whl → 0.8.1__py3-none-any.whl

ksadk/sessions/continuity.py

@@ -22,7 +22,7 @@ class SessionContinuityStatus:
     details: dict[str, Any] = field(default_factory=dict)
 
     def to_payload(self) -> dict[str, Any]:
-        payload = {
+        payload: dict[str, Any] = {
             "Level": self.level.value,
             "Path": self.path,
             "Runner": self.runner,
@@ -320,8 +320,7 @@ class ADKSessionAdapter(RunnerSessionAdapter):
             stm_backend = getattr(_stm, "backend", None) if _stm is not None else None
             is_durable = stm_backend is not None and stm_backend != "local"
             level = (
-                SessionContinuityLevel.RUNTIME if is_durable
-                else SessionContinuityLevel.SEMANTIC
+                SessionContinuityLevel.RUNTIME if is_durable else SessionContinuityLevel.SEMANTIC
             )
             path = "adk_resume"
         elif has_native_session:

ksadk/sessions/in_memory.py

@@ -5,6 +5,7 @@ import copy
 import time
 from typing import Optional
 
+from ksadk.ids import new_session_id
 from ksadk.sessions.base import BaseSessionService, Session, SessionEvent, SessionState, generate_id
 
 
@@ -25,7 +26,7 @@ class InMemorySessionService(BaseSessionService):
                 return copy.deepcopy(self._sessions[session_id])
 
             session = Session(
-                id=session_id or generate_id(),
+                id=session_id or new_session_id(),
                 agent_id=agent_id,
                 user_id=user_id,
             )
@@ -43,6 +44,15 @@ class InMemorySessionService(BaseSessionService):
             session = self._sessions.get(session_id)
             return copy.deepcopy(session) if session else None
 
+    async def get_session_metadata(self, session_id: str) -> Optional[Session]:
+        async with self._lock:
+            session = self._sessions.get(session_id)
+            if session is None:
+                return None
+            metadata = copy.deepcopy(session)
+            metadata.events = []
+            return metadata
+
     async def list_sessions(
         self,
         agent_id: str,
@@ -56,7 +66,10 @@ class InMemorySessionService(BaseSessionService):
                 for session in self._sessions.values()
                 if session.agent_id == agent_id and (user_id is None or session.user_id == user_id)
             ]
-            sessions.sort(key=lambda item: (item.updated_at, item.created_at), reverse=True)
+            sessions.sort(
+                key=lambda item: (item.updated_at, item.created_at, item.id),
+                reverse=True,
+            )
             start = offset or 0
             end = None if limit is None else start + limit
             return sessions[start:end]
@@ -191,6 +204,37 @@ class InMemorySessionService(BaseSessionService):
                 events = [event for event in events if event.seq_id < before_seq_id]
             return len(events)
 
+    async def get_events_for_agent(
+        self,
+        agent_id: str,
+        user_id: Optional[str] = None,
+        offset: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> list[SessionEvent]:
+        async with self._lock:
+            merged = [
+                copy.deepcopy(event)
+                for session in self._sessions.values()
+                if session.agent_id == agent_id and (user_id is None or session.user_id == user_id)
+                for event in session.events
+            ]
+            merged.sort(key=lambda event: (event.timestamp, event.seq_id, event.id))
+            end = max(len(merged) - (offset or 0), 0)
+            start = 0 if limit is None else max(end - limit, 0)
+            return merged[start:end]
+
+    async def count_events_for_agent(
+        self,
+        agent_id: str,
+        user_id: Optional[str] = None,
+    ) -> int:
+        async with self._lock:
+            return sum(
+                len(session.events)
+                for session in self._sessions.values()
+                if session.agent_id == agent_id and (user_id is None or session.user_id == user_id)
+            )
+
     async def get_state(
         self,
         agent_id: str,

ksadk/sessions/local_service.py

@@ -7,11 +7,12 @@ import json
 import os
 import sqlite3
 import time
+from collections.abc import Iterator
 from contextlib import closing, contextmanager
 from pathlib import Path
-from collections.abc import Iterator
 from typing import Optional
 
+from ksadk.ids import new_session_id
 from ksadk.sessions.base import (
     BaseSessionService,
     Session,
@@ -76,6 +77,14 @@ class LocalSessionService(BaseSessionService):
         async with self._lock:
             return await asyncio.to_thread(self._get_session_sync, session_id)
 
+    async def get_session_metadata(self, session_id: str) -> Optional[Session]:
+        async with self._lock:
+            return await asyncio.to_thread(
+                self._get_session_sync,
+                session_id,
+                include_events=False,
+            )
+
     async def list_sessions(
         self,
         agent_id: str,
@@ -161,6 +170,114 @@ class LocalSessionService(BaseSessionService):
                 before_seq_id,
             )
 
+    async def get_events_for_agent(
+        self,
+        agent_id: str,
+        user_id: Optional[str] = None,
+        offset: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> list[SessionEvent]:
+        async with self._lock:
+            return await asyncio.to_thread(
+                self._get_events_for_agent_sync,
+                agent_id,
+                user_id,
+                offset,
+                limit,
+            )
+
+    async def count_events_for_agent(
+        self,
+        agent_id: str,
+        user_id: Optional[str] = None,
+    ) -> int:
+        async with self._lock:
+            return await asyncio.to_thread(
+                self._count_events_for_agent_sync,
+                agent_id,
+                user_id,
+            )
+
+    def _get_events_for_agent_sync(
+        self,
+        agent_id: str,
+        user_id: Optional[str],
+        offset: Optional[int],
+        limit: Optional[int],
+    ) -> list[SessionEvent]:
+        columns = (
+            "e.id, e.session_id, e.author, e.event_type, e.content_json, e.timestamp, "
+            "e.state_delta_json, e.seq_id, e.invocation_id, e.metadata_json"
+        )
+        user_clause = "AND s.user_id = ?" if user_id is not None else ""
+        from_clause = (
+            f"FROM {KSADK_EVENTS_TABLE} e "
+            f"JOIN {KSADK_SESSIONS_TABLE} s ON s.id = e.session_id "
+            f"WHERE s.agent_id = ? {user_clause}"
+        )
+        base_params: list[object] = [agent_id]
+        if user_id is not None:
+            base_params.append(user_id)
+        with self._connection() as connection:
+            if limit is not None or offset is not None:
+                # 与 get_events 一致的"最新 N 条"尾部语义：先 DESC 取窗口再 ASC 重排
+                query = f"""
+                    SELECT id, session_id, author, event_type, content_json, timestamp,
+                           state_delta_json, seq_id, invocation_id, metadata_json
+                    FROM (
+                        SELECT {columns}
+                        {from_clause}
+                        ORDER BY e.timestamp DESC, e.seq_id DESC, e.id DESC
+                        LIMIT ? OFFSET ?
+                    )
+                    ORDER BY timestamp ASC, seq_id ASC, id ASC
+                """
+                params = [*base_params, limit if limit is not None else -1, offset or 0]
+            else:
+                query = f"""
+                    SELECT {columns}
+                    {from_clause}
+                    ORDER BY e.timestamp ASC, e.seq_id ASC, e.id ASC
+                """
+                params = base_params
+            rows = connection.execute(query, params).fetchall()
+            return [
+                SessionEvent(
+                    id=row["id"],
+                    session_id=row["session_id"],
+                    author=row["author"],
+                    event_type=row["event_type"],
+                    content=json.loads(row["content_json"] or "{}"),
+                    timestamp=row["timestamp"],
+                    state_delta=json.loads(row["state_delta_json"] or "{}"),
+                    seq_id=row["seq_id"],
+                    invocation_id=row["invocation_id"],
+                    metadata=json.loads(row["metadata_json"] or "{}"),
+                )
+                for row in rows
+            ]
+
+    def _count_events_for_agent_sync(
+        self,
+        agent_id: str,
+        user_id: Optional[str],
+    ) -> int:
+        user_clause = "AND s.user_id = ?" if user_id is not None else ""
+        params: list[object] = [agent_id]
+        if user_id is not None:
+            params.append(user_id)
+        with self._connection() as connection:
+            row = connection.execute(
+                f"""
+                SELECT COUNT(*) AS total
+                FROM {KSADK_EVENTS_TABLE} e
+                JOIN {KSADK_SESSIONS_TABLE} s ON s.id = e.session_id
+                WHERE s.agent_id = ? {user_clause}
+                """,
+                params,
+            ).fetchone()
+            return int(row["total"] if row else 0)
+
     async def get_state(
         self,
         agent_id: str,
@@ -258,9 +375,7 @@ class LocalSessionService(BaseSessionService):
             and not self._table_exists(connection, KSADK_EVENTS_TABLE)
             and {"session_id", "author", "event_type"}.issubset(legacy_event_columns)
         ):
-            connection.execute(
-                f"ALTER TABLE {LEGACY_EVENTS_TABLE} RENAME TO {KSADK_EVENTS_TABLE}"
-            )
+            connection.execute(f"ALTER TABLE {LEGACY_EVENTS_TABLE} RENAME TO {KSADK_EVENTS_TABLE}")
 
         legacy_state_columns = self._table_columns(connection, LEGACY_STATES_TABLE)
         if (
@@ -268,15 +383,12 @@ class LocalSessionService(BaseSessionService):
             and not self._table_exists(connection, KSADK_STATES_TABLE)
             and {"scope", "agent_id", "state_json"}.issubset(legacy_state_columns)
         ):
-            connection.execute(
-                f"ALTER TABLE {LEGACY_STATES_TABLE} RENAME TO {KSADK_STATES_TABLE}"
-            )
+            connection.execute(f"ALTER TABLE {LEGACY_STATES_TABLE} RENAME TO {KSADK_STATES_TABLE}")
 
     def _ensure_schema(self) -> None:
         with self._connection() as connection:
             self._migrate_legacy_schema(connection)
-            connection.executescript(
-                f"""
+            connection.executescript(f"""
                 CREATE TABLE IF NOT EXISTS {KSADK_SESSIONS_TABLE} (
                     id TEXT PRIMARY KEY,
                     agent_id TEXT NOT NULL,
@@ -309,6 +421,16 @@ class LocalSessionService(BaseSessionService):
                 CREATE INDEX IF NOT EXISTS idx_ksadk_events_session_seq
                 ON {KSADK_EVENTS_TABLE} (session_id, seq_id);
 
+                -- 跨会话事件查询（get_events_for_agent）JOIN sessions 按
+                -- s.agent_id 过滤 + ORDER BY e.timestamp；覆盖索引服务 JOIN 键
+                -- s.id=e.session_id + 排序。
+                CREATE INDEX IF NOT EXISTS idx_ksadk_events_session_ts
+                ON {KSADK_EVENTS_TABLE} (session_id, timestamp, id);
+
+                -- ListSessions 按 agent_id 过滤 + updated_at DESC 排序。
+                CREATE INDEX IF NOT EXISTS idx_ksadk_sessions_agent_updated
+                ON {KSADK_SESSIONS_TABLE} (agent_id, updated_at DESC, id);
+
                 CREATE TABLE IF NOT EXISTS {KSADK_STATES_TABLE} (
                     scope TEXT NOT NULL,
                     agent_id TEXT NOT NULL,
@@ -319,8 +441,7 @@ class LocalSessionService(BaseSessionService):
                     updated_at REAL NOT NULL,
                     PRIMARY KEY (scope, agent_id, user_id, session_id)
                 );
-                """
-            )
+                """)
             self._ensure_columns(
                 connection,
                 KSADK_SESSIONS_TABLE,
@@ -367,7 +488,7 @@ class LocalSessionService(BaseSessionService):
 
             now = time.time()
             session = Session(
-                id=session_id or generate_id(),
+                id=session_id or new_session_id(),
                 agent_id=agent_id,
                 user_id=user_id,
                 created_at=now,
@@ -413,6 +534,7 @@ class LocalSessionService(BaseSessionService):
         session_id: str,
         *,
         connection: Optional[sqlite3.Connection] = None,
+        include_events: bool = True,
     ) -> Optional[Session]:
         owns_connection = connection is None
         connection = connection or self._connect()
@@ -439,7 +561,11 @@ class LocalSessionService(BaseSessionService):
                 first_prompt=row["first_prompt"],
                 last_prompt=row["last_prompt"],
                 state=json.loads(row["state_json"] or "{}"),
-                events=self._get_events_sync(session_id, connection=connection),
+                events=(
+                    self._get_events_sync(session_id, connection=connection)
+                    if include_events
+                    else []
+                ),
                 created_at=row["created_at"],
                 updated_at=row["updated_at"],
                 version=row["version"],
@@ -467,7 +593,7 @@ class LocalSessionService(BaseSessionService):
             if user_id is not None:
                 query += " AND user_id = ?"
                 params.append(user_id)
-            query += " ORDER BY updated_at DESC, created_at DESC"
+            query += " ORDER BY updated_at DESC, created_at DESC, id DESC"
             if limit is not None:
                 query += " LIMIT ?"
                 params.append(limit)
@@ -520,8 +646,12 @@ class LocalSessionService(BaseSessionService):
             if row is None:
                 return False
 
-            connection.execute(f"DELETE FROM {KSADK_EVENTS_TABLE} WHERE session_id = ?", (session_id,))
-            connection.execute(f"DELETE FROM {KSADK_STATES_TABLE} WHERE session_id = ?", (session_id,))
+            connection.execute(
+                f"DELETE FROM {KSADK_EVENTS_TABLE} WHERE session_id = ?", (session_id,)
+            )
+            connection.execute(
+                f"DELETE FROM {KSADK_STATES_TABLE} WHERE session_id = ?", (session_id,)
+            )
             connection.execute(f"DELETE FROM {KSADK_SESSIONS_TABLE} WHERE id = ?", (session_id,))
             connection.commit()
             return True
@@ -541,7 +671,8 @@ class LocalSessionService(BaseSessionService):
 
             next_seq = int(
                 connection.execute(
-                    f"SELECT COALESCE(MAX(seq_id), 0) + 1 FROM {KSADK_EVENTS_TABLE} WHERE session_id = ?",
+                    f"SELECT COALESCE(MAX(seq_id), 0) + 1 "
+                    f"FROM {KSADK_EVENTS_TABLE} WHERE session_id = ?",
                     (session_id,),
                 ).fetchone()[0]
             )

ksadk/sessions/postgres_service.py

@@ -9,6 +9,7 @@ import time
 from typing import Any, Optional
 from urllib.parse import urlsplit, urlunsplit
 
+from ksadk.ids import new_session_id
 from ksadk.sessions.base import (
     BaseSessionService,
     Session,
@@ -59,7 +60,7 @@ class PostgresSessionService(BaseSessionService):
         session_id: Optional[str] = None,
     ) -> Session:
         await self._ensure_schema()
-        session_key = session_id or generate_id()
+        session_key = session_id or new_session_id()
         async with self._pool.acquire() as connection:
             async with connection.transaction():
                 existing = await self._get_session_with_connection(connection, session_key)
@@ -70,8 +71,9 @@ class PostgresSessionService(BaseSessionService):
                 await connection.execute(
                     f"""
                     INSERT INTO {KSADK_PG_SESSIONS_TABLE} (
-                        namespace, tenant_id, workspace_id, id, agent_id, user_id, title, title_source, summary,
-                        first_prompt, last_prompt, state_json, created_at, updated_at, version
+                        namespace, tenant_id, workspace_id, id, agent_id, user_id,
+                        title, title_source, summary, first_prompt, last_prompt,
+                        state_json, created_at, updated_at, version
                     )
                     VALUES ($1, $2, $3, $4, $5, $6, '', '', '', '', '', $7::jsonb, $8, $9, 0)
                     ON CONFLICT (namespace, id) DO NOTHING
@@ -96,7 +98,8 @@ class PostgresSessionService(BaseSessionService):
                 await connection.execute(
                     f"""
                     INSERT INTO {KSADK_PG_STATES_TABLE} (
-                        namespace, tenant_id, workspace_id, scope, agent_id, user_id, session_id, state_json, version, updated_at
+                        namespace, tenant_id, workspace_id, scope, agent_id,
+                        user_id, session_id, state_json, version, updated_at
                     )
                     VALUES ($1, $2, $3, 'session', $4, $5, $6, $7::jsonb, 0, $8)
                     ON CONFLICT (namespace, scope, agent_id, user_id, session_id)
@@ -118,6 +121,15 @@ class PostgresSessionService(BaseSessionService):
         async with self._pool.acquire() as connection:
             return await self._get_session_with_connection(connection, session_id)
 
+    async def get_session_metadata(self, session_id: str) -> Optional[Session]:
+        await self._ensure_schema()
+        async with self._pool.acquire() as connection:
+            return await self._get_session_with_connection(
+                connection,
+                session_id,
+                include_events=False,
+            )
+
     async def list_sessions(
         self,
         agent_id: str,
@@ -128,7 +140,8 @@ class PostgresSessionService(BaseSessionService):
         await self._ensure_schema()
         async with self._pool.acquire() as connection:
             query = f"""
-                SELECT id, agent_id, user_id, title, title_source, summary, first_prompt, last_prompt,
+                SELECT id, agent_id, user_id, title, title_source, summary,
+                       first_prompt, last_prompt,
                        state_json, created_at, updated_at, version
                 FROM {KSADK_PG_SESSIONS_TABLE}
                 WHERE namespace = $1 AND agent_id = $2
@@ -137,7 +150,7 @@ class PostgresSessionService(BaseSessionService):
             if user_id is not None:
                 params.append(user_id)
                 query += f" AND user_id = ${len(params)}"
-            query += " ORDER BY updated_at DESC, created_at DESC"
+            query += " ORDER BY updated_at DESC, created_at DESC, id DESC"
             if limit is not None:
                 params.append(limit)
                 query += f" LIMIT ${len(params)}"
@@ -205,7 +218,8 @@ class PostgresSessionService(BaseSessionService):
             async with connection.transaction():
                 row = await connection.fetchrow(
                     f"""
-                    SELECT id, agent_id, user_id, title, title_source, summary, first_prompt, last_prompt,
+                    SELECT id, agent_id, user_id, title, title_source, summary,
+                           first_prompt, last_prompt,
                            state_json, created_at, updated_at, version
                     FROM {KSADK_PG_SESSIONS_TABLE}
                     WHERE namespace = $1 AND id = $2
@@ -294,10 +308,14 @@ class PostgresSessionService(BaseSessionService):
                 await connection.execute(
                     f"""
                     INSERT INTO {KSADK_PG_EVENTS_TABLE} (
-                        namespace, tenant_id, workspace_id, id, session_id, author, event_type, content_json, timestamp,
+                        namespace, tenant_id, workspace_id, id, session_id, author,
+                        event_type, content_json, timestamp,
                         state_delta_json, seq_id, invocation_id, metadata_json
                     )
-                    VALUES ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9, $10::jsonb, $11, $12, $13::jsonb)
+                    VALUES (
+                        $1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9,
+                        $10::jsonb, $11, $12, $13::jsonb
+                    )
                     """,
                     self.namespace,
                     self.tenant_id,
@@ -419,6 +437,85 @@ class PostgresSessionService(BaseSessionService):
             """
             return int(await connection.fetchval(query, *params) or 0)
 
+    def _agent_events_query_parts(
+        self,
+        agent_id: str,
+        user_id: Optional[str],
+    ) -> tuple[str, list[Any]]:
+        """跨会话事件查询的公共 JOIN/WHERE。events 表无 agent_id 列，需 join sessions。"""
+        conditions = [
+            "e.namespace = $1",
+            "s.namespace = e.namespace",
+            "s.id = e.session_id",
+            "s.agent_id = $2",
+        ]
+        params: list[Any] = [self.namespace, agent_id]
+        if user_id is not None:
+            params.append(user_id)
+            conditions.append(f"s.user_id = ${len(params)}")
+        where_clause = " AND ".join(conditions)
+        from_clause = (
+            f"FROM {KSADK_PG_EVENTS_TABLE} e "
+            f"JOIN {KSADK_PG_SESSIONS_TABLE} s "
+            "ON s.namespace = e.namespace AND s.id = e.session_id "
+            f"WHERE {where_clause}"
+        )
+        return from_clause, params
+
+    async def get_events_for_agent(
+        self,
+        agent_id: str,
+        user_id: Optional[str] = None,
+        offset: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> list[SessionEvent]:
+        await self._ensure_schema()
+        from_clause, params = self._agent_events_query_parts(agent_id, user_id)
+        columns = (
+            "e.id, e.session_id, e.author, e.event_type, e.content_json, e.timestamp, "
+            "e.state_delta_json, e.seq_id, e.invocation_id, e.metadata_json"
+        )
+        async with self._pool.acquire() as connection:
+            if limit is not None or offset is not None:
+                # 与 get_events 一致的"最新 N 条"尾部语义：先 DESC 取窗口再 ASC 重排
+                if limit is not None:
+                    params.append(limit)
+                    limit_sql = f"LIMIT ${len(params)}"
+                else:
+                    limit_sql = ""
+                params.append(offset or 0)
+                offset_sql = f"OFFSET ${len(params)}"
+                query = f"""
+                    SELECT id, session_id, author, event_type, content_json, timestamp,
+                           state_delta_json, seq_id, invocation_id, metadata_json
+                    FROM (
+                        SELECT {columns}
+                        {from_clause}
+                        ORDER BY e.timestamp DESC, e.seq_id DESC, e.id DESC
+                        {limit_sql} {offset_sql}
+                    ) AS latest_events
+                    ORDER BY timestamp ASC, seq_id ASC, id ASC
+                """
+            else:
+                query = f"""
+                    SELECT {columns}
+                    {from_clause}
+                    ORDER BY e.timestamp ASC, e.seq_id ASC, e.id ASC
+                """
+            rows = await connection.fetch(query, *params)
+            return [self._event_from_row(row) for row in rows]
+
+    async def count_events_for_agent(
+        self,
+        agent_id: str,
+        user_id: Optional[str] = None,
+    ) -> int:
+        await self._ensure_schema()
+        from_clause, params = self._agent_events_query_parts(agent_id, user_id)
+        async with self._pool.acquire() as connection:
+            query = f"SELECT COUNT(*) AS total {from_clause}"
+            return int(await connection.fetchval(query, *params) or 0)
+
     async def get_state(
         self,
         agent_id: str,
@@ -445,7 +542,8 @@ class PostgresSessionService(BaseSessionService):
                 f"""
                 SELECT scope, agent_id, user_id, session_id, state_json, version, updated_at
                 FROM {KSADK_PG_STATES_TABLE}
-                WHERE namespace = $1 AND scope = $2 AND agent_id = $3 AND user_id = $4 AND session_id = $5
+                WHERE namespace = $1 AND scope = $2 AND agent_id = $3
+                  AND user_id = $4 AND session_id = $5
                 """,
                 self.namespace,
                 scope,
@@ -506,7 +604,8 @@ class PostgresSessionService(BaseSessionService):
                     f"""
                     SELECT state_json, version
                     FROM {KSADK_PG_STATES_TABLE}
-                    WHERE namespace = $1 AND scope = $2 AND agent_id = $3 AND user_id = $4 AND session_id = $5
+                    WHERE namespace = $1 AND scope = $2 AND agent_id = $3
+                      AND user_id = $4 AND session_id = $5
                     FOR UPDATE
                     """,
                     self.namespace,
@@ -521,7 +620,8 @@ class PostgresSessionService(BaseSessionService):
                 await connection.execute(
                     f"""
                     INSERT INTO {KSADK_PG_STATES_TABLE} (
-                        namespace, tenant_id, workspace_id, scope, agent_id, user_id, session_id, state_json, version, updated_at
+                        namespace, tenant_id, workspace_id, scope, agent_id,
+                        user_id, session_id, state_json, version, updated_at
                     )
                     VALUES ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9, $10)
                     ON CONFLICT (namespace, scope, agent_id, user_id, session_id)
@@ -568,7 +668,7 @@ class PostgresSessionService(BaseSessionService):
             if self._pool is not None:
                 return
             try:
-                import asyncpg
+                import asyncpg  # type: ignore[import-untyped]
             except ImportError as exc:
                 raise SessionBackendUnavailable(
                     "asyncpg is required for KSADK_SESSION_BACKEND=postgres"
@@ -595,8 +695,7 @@ class PostgresSessionService(BaseSessionService):
                 return
             await self._ensure_pool()
             async with self._pool.acquire() as connection:
-                await connection.execute(
-                    f"""
+                await connection.execute(f"""
                     CREATE TABLE IF NOT EXISTS {KSADK_PG_SESSIONS_TABLE} (
                         namespace TEXT NOT NULL,
                         tenant_id TEXT NOT NULL DEFAULT 'default',
@@ -640,6 +739,18 @@ class PostgresSessionService(BaseSessionService):
                     CREATE INDEX IF NOT EXISTS idx_ksadk_pg_events_session_seq
                     ON {KSADK_PG_EVENTS_TABLE} (namespace, session_id, seq_id);
 
+                    -- 跨会话事件查询（get_events_for_agent）需 JOIN sessions 按
+                    -- s.agent_id 过滤并按 e.timestamp 排序；events 表无 agent_id 列，
+                    -- 覆盖索引 (namespace, session_id, timestamp, id) 服务 JOIN 键
+                    -- s.id=e.session_id + ORDER BY e.timestamp DESC。
+                    CREATE INDEX IF NOT EXISTS idx_ksadk_pg_events_session_ts
+                    ON {KSADK_PG_EVENTS_TABLE} (namespace, session_id, timestamp, id);
+
+                    -- ListSessions 归并按 agent_id 过滤 + updated_at DESC 排序；
+                    -- sessions 表 PK 是 (namespace, id)，缺 agent_id 前缀索引。
+                    CREATE INDEX IF NOT EXISTS idx_ksadk_pg_sessions_agent_updated
+                    ON {KSADK_PG_SESSIONS_TABLE} (namespace, agent_id, updated_at DESC, id);
+
                     CREATE TABLE IF NOT EXISTS {KSADK_PG_STATES_TABLE} (
                         namespace TEXT NOT NULL,
                         tenant_id TEXT NOT NULL DEFAULT 'default',
@@ -666,11 +777,9 @@ class PostgresSessionService(BaseSessionService):
                     ADD COLUMN IF NOT EXISTS tenant_id TEXT NOT NULL DEFAULT 'default';
                     ALTER TABLE {KSADK_PG_STATES_TABLE}
                     ADD COLUMN IF NOT EXISTS workspace_id TEXT NOT NULL DEFAULT 'default';
-                    """
-                )
+                    """)
                 try:
-                    await connection.execute(
-                        f"""
+                    await connection.execute(f"""
                     CREATE OR REPLACE VIEW {PG_READABLE_EVENTS_VIEW} AS
                     SELECT
                         event_row.namespace,
@@ -715,8 +824,7 @@ class PostgresSessionService(BaseSessionService):
                     JOIN {KSADK_PG_SESSIONS_TABLE} AS session_row
                       ON session_row.namespace = event_row.namespace
                      AND session_row.id = event_row.session_id;
-                        """
-                    )
+                        """)
                 except Exception as exc:
                     logger.warning("Postgres readable session view unavailable: %s", exc)
             self._schema_ready = True
@@ -727,6 +835,7 @@ class PostgresSessionService(BaseSessionService):
         session_id: str,
         *,
         for_update: bool = False,
+        include_events: bool = True,
     ) -> Optional[Session]:
         lock_clause = " FOR UPDATE" if for_update else ""
         row = await connection.fetchrow(
@@ -742,10 +851,16 @@ class PostgresSessionService(BaseSessionService):
         )
         if row is None:
             return None
-        events = [] if for_update else await self._get_events_with_connection(connection, session_id)
+        events = (
+            await self._get_events_with_connection(connection, session_id)
+            if include_events and not for_update
+            else []
+        )
         return self._session_from_row(row, events=events)
 
-    async def _get_events_with_connection(self, connection: Any, session_id: str) -> list[SessionEvent]:
+    async def _get_events_with_connection(
+        self, connection: Any, session_id: str
+    ) -> list[SessionEvent]:
         rows = await connection.fetch(
             f"""
             SELECT id, session_id, author, event_type, content_json, timestamp,
@@ -785,7 +900,8 @@ class PostgresSessionService(BaseSessionService):
         await connection.execute(
             f"""
             INSERT INTO {KSADK_PG_STATES_TABLE} (
-                namespace, tenant_id, workspace_id, scope, agent_id, user_id, session_id, state_json, version, updated_at
+                namespace, tenant_id, workspace_id, scope, agent_id,
+                user_id, session_id, state_json, version, updated_at
             )
             VALUES ($1, $2, $3, 'session', $4, $5, $6, $7::jsonb, $8, $9)
             ON CONFLICT (namespace, scope, agent_id, user_id, session_id)
@@ -888,7 +1004,9 @@ def mask_postgres_session_dsn(dsn: str) -> str:
     host = parts.hostname or ""
     port = f":{parts.port}" if parts.port else ""
     auth = f"{username}:***@" if username else "***@"
-    return urlunsplit((parts.scheme, f"{auth}{host}{port}", parts.path, parts.query, parts.fragment))
+    return urlunsplit(
+        (parts.scheme, f"{auth}{host}{port}", parts.path, parts.query, parts.fragment)
+    )
 
 
 __all__ = [