agentengine-sdk-python 0.8.2__py3-none-any.whl → 0.8.4__py3-none-any.whl

ksadk/memory/adk/backends/sdk_ltm_backend.py

@@ -52,7 +52,8 @@ DEFAULT_SCENE_ID = "_sys_general"
 # "记忆不存在"识别模式（方案 §17.4：准确错误码待真实 fixture 固化，
 # 首版按保守中英文模式匹配，fixture 到位后收敛为精确匹配）。
 _NOT_EXIST_RE = re.compile(
-    r"not[ _]?exist|does not exist|memory.*不存在|记忆不存在|记忆已被删除|resourcenotfound|notfound",
+    r"not[ _]?exist|does not exist|memory.*不存在|记忆不存在|记忆已被删除|"
+    r"resourcenotfound|notfound",
     re.IGNORECASE,
 )
 
@@ -98,6 +99,7 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
     agent_id: str = ""
     scene_id: str = DEFAULT_SCENE_ID
     last_error: str = ""
+    last_http_status: int | None = None
     last_create_response: dict[str, Any] = Field(default_factory=dict)
     last_session_status: dict[str, Any] = Field(default_factory=dict)
 
@@ -176,7 +178,16 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
         client_profile = ClientProfile()
         client_profile.httpProfile = http_profile
 
-        self._aicp_client = aicp_module.AicpClient(cred, self.region, profile=client_profile)
+        owner = self
+
+        class ObservedAicpClient(aicp_module.AicpClient):
+            def _check_status(self, response):
+                # Preserve the status that the upstream SDK's generic exception
+                # otherwise discards. No response content is used as authority.
+                owner.last_http_status = response.status
+                return super()._check_status(response)
+
+        self._aicp_client = ObservedAicpClient(cred, self.region, profile=client_profile)
 
         # 强制覆写 API 版本为记忆库 API 所需的 2025-11-14
         self._aicp_client._apiVersion = "2025-11-14"
@@ -246,6 +257,7 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
 
         try:
             self.last_error = ""
+            self.last_create_response = {}
             conversation = self._build_conversation(event_strings)
             if not conversation:
                 logger.info("No valid conversation items to save")
@@ -278,6 +290,11 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
 
             response = client.call("CreateMemorySdk", params, options={"IsPostJson": True})
             self.last_create_response = self._parse_json_response(response) or {}
+            if kwargs.get("strict", False):
+                data = self.last_create_response
+                if not self._confirmed_mutation_response(data):
+                    self.last_error = "MEMORY_WRITE_RESPONSE_UNKNOWN"
+                    return False
             self.last_session_status = {
                 "SessionId": session_id,
                 "AgentUserId": user_id,
@@ -290,8 +307,8 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
             return True
 
         except Exception as e:
-            self.last_error = str(e)
-            logger.error(f"CreateMemorySdk failed: {e}")
+            self.last_error = "MEMORY_WRITE_UNKNOWN" if kwargs.get("strict", False) else str(e)
+            logger.error("CreateMemorySdk did not return a confirmed acknowledgment")
             return False
 
     def search_memory(self, user_id: str, query: str, top_k: int = 5, **kwargs) -> list[str]:
@@ -379,7 +396,9 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
             "SceneId": self._effective_scene_id(),
         }
         response = client.call("QueryMemorySdk", params, options={"IsPostJson": True})
-        records = self._parse_query_records_response(response, user_id=user_id)
+        records = self._parse_query_records_response(
+            response, user_id=user_id, strict=kwargs.get("strict", False)
+        )
         logger.info(
             f"QueryMemorySdk structured: user={user_id}, records={len(records)}"
         )
@@ -452,9 +471,16 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
             )
 
         data = self._parse_json_response(response)
+        if kwargs.get("strict", False) and not self._confirmed_mutation_response(data):
+            return MemoryMutationResult(
+                ok=False, memory_id=memory_id, status="failed",
+                message="记忆更新结果未确认",
+            )
         response_memory_id = self._parse_new_memory_id(data)
         new_memory_id = response_memory_id
-        if not response_memory_id or response_memory_id == memory_id:
+        if not kwargs.get("strict", False) and (
+            not response_memory_id or response_memory_id == memory_id
+        ):
             # The service can merge an edited memory into another record while
             # returning no new ID (or echoing the old one).  Do not expose that
             # stale handle to callers: confirm the current handle by listing
@@ -512,7 +538,7 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
             "AgentUserId": user_id,
         }
         try:
-            client.call("DeleteMemory", params, options={"IsPostJson": True})
+            response = client.call("DeleteMemory", params, options={"IsPostJson": True})
         except Exception as exc:
             if self._is_not_exist_error(exc):
                 return MemoryMutationResult(
@@ -529,6 +555,13 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
                 status="failed",
                 message="记忆删除失败",
             )
+        if kwargs.get("strict", False) and not self._confirmed_mutation_response(
+            self._parse_json_response(response)
+        ):
+            return MemoryMutationResult(
+                ok=False, memory_id=memory_id, status="failed",
+                message="记忆删除结果未确认",
+            )
         return MemoryMutationResult(
             ok=True,
             memory_id=memory_id,
@@ -536,6 +569,19 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
             message="已删除",
         )
 
+    @staticmethod
+    def _confirmed_mutation_response(data: Any) -> bool:
+        metadata = data.get("ResponseMetadata", {}) if isinstance(data, dict) else {}
+        return bool(
+            isinstance(data, dict) and isinstance(metadata, dict)
+            and not data.get("Error") and not metadata.get("Error")
+            and ("Success" not in data or data["Success"] is True)
+            and type(data.get("Code")) is not bool
+            and data.get("Code") in (None, 0, "0", 200, "200")
+            and isinstance(data.get("RequestId", metadata.get("RequestId")), str)
+            and data.get("RequestId", metadata.get("RequestId"))
+        )
+
     def get_extraction_status(
         self,
         *,
@@ -547,16 +593,21 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
         State 映射 0/50/100/-50/-100；未找到 Session 返回 unknown。
         searchable 需 Service 层结合 ListMemories 确认后置位。
         """
-        item = self.get_session_status(user_id=user_id, session_id=session_id)
+        item, error_code = self._lookup_session_status(user_id=user_id, session_id=session_id)
         if not isinstance(item, dict):
             return MemoryExtractionStatus(
                 session_id=session_id,
                 state=None,
                 status="unknown",
-                message="Session 状态未知",
+                message="Session 状态查询未完成" if error_code else "Session 状态未知",
+                error_code=error_code,
             )
         state = item.get("State")
-        state_int = int(state) if isinstance(state, (int, float, str)) and str(state).lstrip("-").isdigit() else None
+        state_int = (
+            int(state)
+            if isinstance(state, (int, float, str)) and str(state).lstrip("-").isdigit()
+            else None
+        )
         status = map_session_state(state_int)
         message = {
             "queued": "排队中",
@@ -617,19 +668,29 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
         return ""
 
     def _parse_query_records_response(
-        self, response: Any, *, user_id: str
+        self, response: Any, *, user_id: str, strict: bool = False
     ) -> List[LongTermMemoryRecord]:
         """严格解析 QueryMemorySdk 结构化响应：Data[].Memories[]。"""
         try:
             data = self._parse_json_response(response)
         except (json.JSONDecodeError, TypeError):
+            if strict:
+                raise ValueError("MEMORY_SEARCH_RESPONSE_INVALID") from None
             logger.error("QueryMemorySdk records: invalid JSON response")
             return []
         if not isinstance(data, dict):
+            if strict:
+                raise ValueError("MEMORY_SEARCH_RESPONSE_INVALID")
             logger.error("QueryMemorySdk records: unexpected payload type")
             return []
         items = data.get("Data")
+        if strict and (
+            data.get("Error") or data.get("Code") not in (None, 0, "0", 200, "200")
+        ):
+            raise ValueError("MEMORY_SEARCH_RESPONSE_INVALID")
         if not isinstance(items, list):
+            if strict:
+                raise ValueError("MEMORY_SEARCH_RESPONSE_INVALID")
             logger.warning(
                 "QueryMemorySdk records: unknown schema, keys=%s; fail closed",
                 list(data.keys()),
@@ -639,11 +700,15 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
         for item in items:
             memories = item.get("Memories") if isinstance(item, dict) else None
             if not isinstance(memories, list):
+                if strict:
+                    raise ValueError("MEMORY_SEARCH_RESPONSE_INVALID")
                 continue
             for memory in memories:
                 record = self._record_from_item(memory, user_id=user_id)
                 if record is not None:
                     records.append(record)
+                elif strict:
+                    raise ValueError("MEMORY_SEARCH_RESPONSE_INVALID")
         return records
 
     def _parse_list_memories_response(
@@ -717,38 +782,93 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
         user_id: str,
         session_id: str,
         page_size: int = 20,
+        max_pages: int = 20,
     ) -> dict[str, Any] | None:
-        """Return raw AICP session status for a recently submitted memory session."""
-        if not session_id:
-            return None
-
-        client = self._get_client()
-        memory_collection_id = self._effective_memory_collection_id()
-        params = {
-            "MemoryCollectionId": memory_collection_id,
-            "AgentUserId": user_id,
-            "Page": 1,
-            "PageSize": page_size,
-        }
-
+        """Look up a session across bounded pages; preserve legacy raw return shape."""
+        item, error_code = self._lookup_session_status(
+            user_id=user_id, session_id=session_id, page_size=page_size, max_pages=max_pages
+        )
+        self.last_error = error_code
+        self.last_session_status = dict(item or {})
+        return item
+
+    def _lookup_session_status(
+        self, *, user_id: str, session_id: str, page_size: int = 20, max_pages: int = 20
+    ) -> tuple[dict[str, Any] | None, str]:
+        if (type(page_size) is not int or not 1 <= page_size <= 100
+                or type(max_pages) is not int or not 1 <= max_pages <= 1000):
+            raise ValueError("Invalid memory status pagination budget")
+        if not user_id or not session_id:
+            return None, "MEMORY_STATUS_IDENTITY_REQUIRED"
+        seen: set[str] = set()
+        previous_total = None
         try:
-            response = client.call("ListSessions", params, options={"IsPostJson": True})
-            data = self._parse_json_response(response)
-        except Exception as e:
-            self.last_error = str(e)
-            logger.warning(f"ListSessions failed while checking memory status: {e}")
-            return None
-
-        payload = data.get("Data") if isinstance(data, dict) else None
-        items = payload.get("Items") if isinstance(payload, dict) else None
-        if not isinstance(items, list):
-            return None
-
-        for item in items:
-            if isinstance(item, dict) and item.get("SessionId") == session_id:
-                self.last_session_status = item
-                return item
-        return None
+            client = self._get_client()
+            collection = self._effective_memory_collection_id()
+            for page in range(1, max_pages + 1):
+                response = client.call("ListSessions", {
+                    "MemoryCollectionId": collection, "AgentUserId": user_id,
+                    "Page": page, "PageSize": page_size,
+                }, options={"IsPostJson": True})
+                data = self._parse_json_response(response)
+                metadata = data.get("ResponseMetadata", {}) if isinstance(data, dict) else {}
+                if (
+                    not isinstance(data, dict) or data.get("Error")
+                    or not isinstance(metadata, dict) or metadata.get("Error")
+                    or type(data.get("Code")) is bool
+                    or data.get("Code") not in (None, 0, "0", 200, "200")
+                ):
+                    return None, "MEMORY_STATUS_QUERY_FAILED"
+                payload = data.get("Data")
+                items = payload.get("Items") if isinstance(payload, dict) else None
+                if not isinstance(items, list) or len(items) > page_size or any(
+                    not isinstance(item, dict) or not isinstance(item.get("SessionId"), str)
+                    or not item["SessionId"] for item in items
+                ):
+                    return None, "MEMORY_STATUS_RESPONSE_INVALID"
+                total_count = payload.get("TotalCount")
+                total_alias = payload.get("Total")
+                if total_count is not None and total_alias is not None:
+                    normalized_count = (
+                        int(total_count)
+                        if isinstance(total_count, str) and total_count.isdigit()
+                        else total_count
+                    )
+                    normalized_alias = (
+                        int(total_alias)
+                        if isinstance(total_alias, str) and total_alias.isdigit()
+                        else total_alias
+                    )
+                    if normalized_count != normalized_alias:
+                        return None, "MEMORY_STATUS_RESPONSE_INVALID"
+                total = total_count if total_count is not None else total_alias
+                if isinstance(total, str) and total.isdigit():
+                    total = int(total)
+                if total is not None and (type(total) is not int or total < 0):
+                    return None, "MEMORY_STATUS_RESPONSE_INVALID"
+                if page > 1 and total != previous_total:
+                    return None, "MEMORY_STATUS_DIRECTORY_CHANGED"
+                previous_total = total
+                ids = [item["SessionId"] for item in items]
+                if len(set(ids)) != len(ids) or seen.intersection(ids):
+                    return None, "MEMORY_STATUS_PAGINATION_REPEATED"
+                seen.update(ids)
+                for item in items:
+                    if item["SessionId"] == session_id:
+                        if (
+                            item.get("AgentUserId", user_id) != user_id
+                            or item.get("MemoryCollectionId", collection) != collection
+                        ):
+                            return None, "MEMORY_STATUS_SCOPE_MISMATCH"
+                        return dict(item), ""
+                if total is not None and len(seen) >= total:
+                    return None, "" if len(seen) == total else "MEMORY_STATUS_DIRECTORY_CHANGED"
+                if len(items) < page_size:
+                    return None, "" if total is None else "MEMORY_STATUS_DIRECTORY_INCOMPLETE"
+            return None, "MEMORY_STATUS_PAGE_BUDGET_EXHAUSTED"
+        except Exception:
+            logger.warning("ListSessions status query failed")
+            return None, "MEMORY_STATUS_QUERY_FAILED"
 
     def _parse_query_response(self, response: str) -> list[str]:
         """解析 QueryMemorySdk 响应

ksadk/memory/adk/resilient_session_service.py

@@ -38,11 +38,11 @@ class ResilientADKSessionService(BaseSessionService):
             return
         self._primary_enabled = False
         logger.error(
-            "ADK session persistence degraded; using in-memory live session: %s",
-            exc,
+            "ADK session persistence degraded; using in-memory live session",
             extra={
                 "session_backend_state": "degraded",
                 "session_backend": type(self.primary).__name__,
+                "session_backend_reason_code": "SESSION_STORE_UNREACHABLE",
             },
         )
         self._start_probe()
@@ -63,22 +63,30 @@ class ResilientADKSessionService(BaseSessionService):
             await asyncio.sleep(self._probe_interval_seconds)
             if self._primary_enabled:
                 break
-            try:
-                await self.primary.get_session(
-                    app_name="__ksadk_probe__",
-                    user_id="__ksadk_probe__",
-                    session_id="__ksadk_probe__",
-                )
-            except Exception:
-                continue
-            self._primary_enabled = True
-            logger.info(
-                "ADK session persistence recovered; durable backend re-enabled",
-                extra={
-                    "session_backend_state": "recovered",
-                    "session_backend": type(self.primary).__name__,
-                },
+            await self.refresh_persistence_capability()
+
+    async def refresh_persistence_capability(self) -> bool:
+        """Probe a degraded ADK database service without rebuilding the runner."""
+        if self._primary_enabled:
+            return True
+        try:
+            await self.primary.get_session(
+                app_name="__ksadk_probe__",
+                user_id="__ksadk_probe__",
+                session_id="__ksadk_probe__",
             )
+        except Exception:
+            return False
+        self._primary_enabled = True
+        logger.info(
+            "ADK session persistence recovered; durable backend re-enabled",
+            extra={
+                "session_backend_state": "recovered",
+                "session_backend": type(self.primary).__name__,
+                "session_backend_reason_code": "READY",
+            },
+        )
+        return True
 
     @staticmethod
     def _key(app_name: str, user_id: str, session_id: str) -> tuple[str, str, str]:

ksadk/memory/adk/short_term_memory.py

@@ -33,6 +33,7 @@ from ksadk.compat.adk_compat import (
     InMemorySessionService,
     Session,
 )
+from ksadk.sessions.topology import StorageTarget, resolve_persistence_topology
 
 logger = logging.getLogger(__name__)
 
@@ -55,14 +56,20 @@ def _normalize_backend_name(backend: str) -> str:
 
 
 def _normalize_database_url(db_url: str) -> str:
-    """Normalize sqlite URLs for google.adk DatabaseSessionService.
+    """Normalize database URLs for google.adk DatabaseSessionService.
 
-    ADK uses SQLAlchemy async engines underneath, so plain `sqlite:///...`
-    URLs fail while `sqlite+aiosqlite:///...` works.
+    ADK uses SQLAlchemy async engines underneath, so plain PostgreSQL and
+    SQLite URLs need their corresponding async driver schemes.
     """
     normalized = str(db_url or "").strip()
     if not normalized:
         return ""
+    if normalized.startswith("postgresql+asyncpg:"):
+        return normalized
+    if normalized.startswith("postgresql:"):
+        return "postgresql+asyncpg:" + normalized[len("postgresql:") :]
+    if normalized.startswith("postgres:"):
+        return "postgresql+asyncpg:" + normalized[len("postgres:") :]
     if normalized.startswith("sqlite+aiosqlite:"):
         return normalized
     if normalized.startswith("sqlite:"):
@@ -159,9 +166,7 @@ class ShortTermMemory(BaseModel):
             self._session_service = ResilientADKSessionService(
                 DatabaseSessionService(db_url=normalized_db_url, **service_kwargs)
             )
-            logger.info(
-                f"ShortTermMemory: using DatabaseSessionService " f"({normalized_db_url[:30]}...)"
-            )
+            logger.info("ShortTermMemory: using DatabaseSessionService")
         except ImportError:
             logger.warning(
                 "DatabaseSessionService not available. "
@@ -170,10 +175,11 @@ class ShortTermMemory(BaseModel):
             )
             self._session_service = InMemorySessionService()
             self.backend = "local"
-        except Exception as e:
+        except Exception as exc:
             logger.error(
-                f"Failed to create DatabaseSessionService: {e}. "
-                f"Falling back to InMemorySessionService."
+                "Failed to create DatabaseSessionService (%s); "
+                "falling back to InMemorySessionService.",
+                type(exc).__name__,
             )
             self._session_service = InMemorySessionService()
             self.backend = "local"
@@ -237,6 +243,13 @@ class ShortTermMemory(BaseModel):
             logger.error(f"Failed to create session: {e}")
             return None
 
+    @classmethod
+    def from_persistence_target(cls, target: StorageTarget) -> "ShortTermMemory":
+        """Build ADK-native state from an effective Checkpoint storage target."""
+        if target.backend == "postgres" and target.dsn:
+            return cls(backend="database", db_url=_normalize_database_url(target.dsn))
+        return cls(backend="local")
+
     @classmethod
     def from_env(cls) -> "ShortTermMemory":
         """从环境变量创建 ShortTermMemory
@@ -251,6 +264,10 @@ class ShortTermMemory(BaseModel):
             KSADK_SESSION_BACKEND: 统一 session backend fallback
             KSADK_SESSION_DSN: 统一 session DSN fallback
         """
+        topology = resolve_persistence_topology(framework="adk")
+        if topology.checkpoint.backend == "postgres" and topology.checkpoint.dsn:
+            return cls.from_persistence_target(topology.checkpoint)
+
         explicit_backend = _normalize_backend_name(
             _env_first(
                 "KSADK_ADK_SESSION_BACKEND",

ksadk/memory/models.py

@@ -127,6 +127,8 @@ class MemoryExtractionStatus:
     status: str
     searchable: bool = False
     message: str = ""
+    # Query failure does not prove that the previously submitted write failed.
+    error_code: str = ""
 
 
 def map_session_state(state: int | None) -> str:
@@ -176,7 +178,7 @@ class MemoryConflictError(MemoryOperationError):
 MEMORY_MODEL_VERSION = "v1"
 
 MemoryScope = Literal["user", "agent", "workspace", "org"]
-MemoryType = Literal["profile", "fact", "episode"]
+MemoryType = Literal["profile", "fact", "episode", "unknown"]
 MemoryStatus = Literal["active", "superseded", "deleted", "expired"]
 MemoryOperation = Literal["add", "update", "delete", "ignore"]
 MemorySearchStatus = Literal["ok", "not_configured", "timeout", "unauthorized", "failed"]
@@ -206,8 +208,8 @@ class MemoryRecord:
     content: str
     summary: str
     status: MemoryStatus
-    confidence: float
-    importance: float
+    confidence: float | None
+    importance: float | None
     valid_from: str
     valid_to: str
     expires_at: str
@@ -215,7 +217,8 @@ class MemoryRecord:
     source_event_ids: list[str]
     source_seq_range: tuple[int, int] | None
     content_hash: str
-    version: int
+    # None means the provider has no record revision/CAS contract.
+    version: int | None
     metadata: dict[str, Any] = field(default_factory=dict)
     created_at: str = ""
     updated_at: str = ""

ksadk/memory/provider_resolver.py

@@ -32,6 +32,9 @@ def resolve_memory_provider(provider_ref: str) -> MemoryProviderLike:
     """
     ref = str(provider_ref or "").strip().lower()
 
+    if ref.startswith("binding://"):
+        raise ValueError("RESOURCE_MEMORY_BINDING_REQUIRES_ACTIVATION")
+
     if ref in ("local-inmemory", "inmemory"):
         from ksadk.memory.adk.backends.inmemory_ltm_backend import (
             InMemoryLTMBackend,

ksadk/memory/providers/local_sqlite.py

@@ -141,6 +141,13 @@ class SqliteMemoryProvider:
         workspace_id: str = "local",
     ) -> None:
         self._db_path = str(db_path)
+        if self._db_path != ":memory:":
+            # A fresh local Studio has not created its session directory yet.
+            # SQLite creates the database file, but not missing parents.
+            Path(self._db_path).expanduser().resolve().parent.mkdir(
+                parents=True,
+                exist_ok=True,
+            )
         self._tenant_id = tenant_id
         self._workspace_id = workspace_id
         self._lock = threading.Lock()

ksadk/model_proxy/server.py

@@ -444,13 +444,18 @@ class ProxyServer:
             # 应用层取消信号:让活动 SSE 的 _stream_gen 主动 break
             self._app.state.cancel_event.set()
         if self._server is not None:
-            # should_exit 触发主循环进入 shutdown;force_exit 让 shutdown 跳过等待
-            # connections/tasks 完成(活动 SSE 下不再无限等)。两者缺一:只 should_exit
-            # 会被活动连接卡死,只 force_exit 主循环根本不进 shutdown。
+            # Enter Uvicorn's normal shutdown so its lifespan task receives a
+            # shutdown event.  Setting force_exit here skips that event and
+            # makes every completed Studio turn print a CancelledError.
             self._server.should_exit = True
-            self._server.force_exit = True
         if self._thread is not None:
-            self._thread.join(timeout=5)
+            self._thread.join(timeout=3)
+            if self._thread.is_alive() and self._server is not None:
+                # The application cancel signal normally drains active SSE
+                # generators.  Keep a bounded last resort for a broken client
+                # or upstream that ignores cancellation.
+                self._server.force_exit = True
+                self._thread.join(timeout=2)
         if self._sock is not None:
             try:
                 self._sock.close()