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

ksadk/memory/adk/resilient_session_service.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+from dataclasses import dataclass
 from typing import Any, Optional
 
 from ksadk.compat.adk_compat import (
@@ -12,11 +13,22 @@ from ksadk.compat.adk_compat import (
     ListSessionsResponse,
     Session,
 )
+from ksadk.sessions.db_budget import DatabaseOperationDeadline, session_db_budget
 from ksadk.sessions.resilience import is_session_backend_failure
 
 logger = logging.getLogger(__name__)
 
 
+@dataclass(frozen=True)
+class ADKEventCommitUnknown:
+    """Fail-open live event whose durable COMMIT cannot be confirmed."""
+
+    app_name: str
+    user_id: str
+    session_id: str
+    event_id: str
+
+
 class ResilientADKSessionService(BaseSessionService):
     """Run ADK sessions locally while mirroring them to durable storage."""
 
@@ -26,6 +38,11 @@ class ResilientADKSessionService(BaseSessionService):
         self.primary = primary
         self.live = InMemorySessionService()
         self._primary_sessions: dict[tuple[str, str, str], Session] = {}
+        # A failed write has an unknown commit outcome. Never replay it or
+        # hydrate stale durable state over the live session after recovery.
+        self._dirty_sessions: set[tuple[str, str, str]] = set()
+        self._deleted_sessions: set[tuple[str, str, str]] = set()
+        self.unknown_event_commits: set[ADKEventCommitUnknown] = set()
         self._primary_enabled = True
         self._probe_task: asyncio.Task[None] | None = None
 
@@ -92,7 +109,42 @@ class ResilientADKSessionService(BaseSessionService):
     def _key(app_name: str, user_id: str, session_id: str) -> tuple[str, str, str]:
         return app_name, user_id, session_id
 
+    def _write_deadline(self) -> DatabaseOperationDeadline:
+        return DatabaseOperationDeadline(
+            getattr(self.primary, "db_budget", None) or session_db_budget()
+        )
+
+    async def reconcile_event_commit(
+        self, *, app_name: str, user_id: str, session_id: str, event_id: str
+    ) -> str:
+        """Read back a stable ADK event ID after a write's outcome is unknown.
+
+        Absence is still ``unknown`` because an in-flight commit may finish
+        after this read. This method never replays an event or clears dirty
+        local state.
+        """
+        try:
+            durable = await self.primary.get_session(
+                app_name=app_name, user_id=user_id, session_id=session_id
+            )
+        except Exception:
+            return "unknown"
+        if durable and any(event.id == event_id for event in durable.events):
+            self.unknown_event_commits.discard(
+                ADKEventCommitUnknown(app_name, user_id, session_id, event_id)
+            )
+            return "committed"
+        return "unknown"
+
     async def _hydrate(self, durable: Session) -> Session:
+        key = self._key(durable.app_name, durable.user_id, durable.id)
+        if key in self._dirty_sessions:
+            existing = await self.live.get_session(
+                app_name=durable.app_name, user_id=durable.user_id, session_id=durable.id
+            )
+            if existing is None:
+                raise RuntimeError("Dirty ADK session has no live state")
+            return existing
         existing = await self.live.get_session(
             app_name=durable.app_name,
             user_id=durable.user_id,
@@ -128,12 +180,15 @@ class ResilientADKSessionService(BaseSessionService):
         session_id: Optional[str] = None,
     ) -> Session:
         if session_id:
+            key = self._key(app_name, user_id, session_id)
             existing = await self.live.get_session(
                 app_name=app_name,
                 user_id=user_id,
                 session_id=session_id,
             )
-            if self._primary_enabled:
+            if key in self._dirty_sessions and existing is not None:
+                return existing
+            if self._primary_enabled and key not in self._dirty_sessions:
                 try:
                     durable = await self.primary.get_session(
                         app_name=app_name,
@@ -154,7 +209,9 @@ class ResilientADKSessionService(BaseSessionService):
             state=state,
             session_id=session_id,
         )
-        if self._primary_enabled:
+        key = self._key(app_name, user_id, live.id)
+        self._deleted_sessions.discard(key)
+        if self._primary_enabled and key not in self._dirty_sessions:
             try:
                 durable = await self.primary.create_session(
                     app_name=app_name,
@@ -164,8 +221,11 @@ class ResilientADKSessionService(BaseSessionService):
                 )
                 self._primary_sessions[self._key(app_name, user_id, live.id)] = durable
             except Exception as exc:
+                self._dirty_sessions.add(key)
                 if not self._handle_primary_failure(exc):
                     raise
+        else:
+            self._dirty_sessions.add(key)
         return live
 
     async def get_session(
@@ -176,13 +236,16 @@ class ResilientADKSessionService(BaseSessionService):
         session_id: str,
         config: Optional[GetSessionConfig] = None,
     ) -> Optional[Session]:
+        key = self._key(app_name, user_id, session_id)
         live = await self.live.get_session(
             app_name=app_name,
             user_id=user_id,
             session_id=session_id,
             config=config,
         )
-        if not self._primary_enabled:
+        if key in self._deleted_sessions:
+            return None
+        if not self._primary_enabled or key in self._dirty_sessions:
             return live
         try:
             durable = await self.primary.get_session(
@@ -207,6 +270,9 @@ class ResilientADKSessionService(BaseSessionService):
             try:
                 durable = await self.primary.list_sessions(app_name=app_name, user_id=user_id)
                 for session in durable.sessions:
+                    key = self._key(session.app_name, session.user_id, session.id)
+                    if key in self._dirty_sessions:
+                        continue
                     await self._hydrate(session)
             except Exception as exc:
                 if not self._handle_primary_failure(exc):
@@ -214,8 +280,11 @@ class ResilientADKSessionService(BaseSessionService):
         return await self.live.list_sessions(app_name=app_name, user_id=user_id)
 
     async def delete_session(self, *, app_name: str, user_id: str, session_id: str) -> None:
+        key = self._key(app_name, user_id, session_id)
         await self.live.delete_session(app_name=app_name, user_id=user_id, session_id=session_id)
-        self._primary_sessions.pop(self._key(app_name, user_id, session_id), None)
+        self._primary_sessions.pop(key, None)
+        self._dirty_sessions.add(key)
+        self._deleted_sessions.add(key)
         if self._primary_enabled:
             try:
                 await self.primary.delete_session(
@@ -223,33 +292,64 @@ class ResilientADKSessionService(BaseSessionService):
                     user_id=user_id,
                     session_id=session_id,
                 )
+                self._dirty_sessions.discard(key)
+                self._deleted_sessions.discard(key)
             except Exception as exc:
                 if not self._handle_primary_failure(exc):
                     raise
 
     async def append_event(self, session: Session, event: Event) -> Event:
         stored = await self.live.append_event(session, event)
-        if not self._primary_enabled:
-            return stored
+        deadline = self._write_deadline()
         key = self._key(session.app_name, session.user_id, session.id)
+        if not self._primary_enabled or key in self._dirty_sessions:
+            self._dirty_sessions.add(key)
+            return stored
         durable_session = self._primary_sessions.get(key)
         try:
             if durable_session is None:
-                durable_session = await self.primary.get_session(
-                    app_name=session.app_name,
-                    user_id=session.user_id,
-                    session_id=session.id,
-                )
-                if durable_session is None:
-                    durable_session = await self.primary.create_session(
+                durable_session = await deadline.run(
+                    self.primary.get_session(
                         app_name=session.app_name,
                         user_id=session.user_id,
-                        state=session.state,
                         session_id=session.id,
                     )
+                )
+                if durable_session is None:
+                    durable_session = await deadline.run(
+                        self.primary.create_session(
+                            app_name=session.app_name,
+                            user_id=session.user_id,
+                            state=session.state,
+                            session_id=session.id,
+                        )
+                    )
                 self._primary_sessions[key] = durable_session
-            await self.primary.append_event(durable_session, event)
+            await deadline.run(self.primary.append_event(durable_session, event))
         except Exception as exc:
+            if is_session_backend_failure(exc):
+                try:
+                    outcome = await deadline.run(
+                        self.reconcile_event_commit(
+                            app_name=session.app_name,
+                            user_id=session.user_id,
+                            session_id=session.id,
+                            event_id=event.id,
+                        )
+                    )
+                except Exception:
+                    outcome = "unknown"
+                if outcome == "committed":
+                    # A lost acknowledgement is not a failed write. Reload the
+                    # exact durable revision before the next append.
+                    self._primary_sessions.pop(key, None)
+                    return stored
+                self.unknown_event_commits.add(ADKEventCommitUnknown(*key, event.id))
+                logger.warning(
+                    "ADK event commit outcome unknown; retaining dirty live state",
+                    extra={"session_backend_reason_code": "ADK_EVENT_COMMIT_UNKNOWN"},
+                )
+            self._dirty_sessions.add(key)
             if not self._handle_primary_failure(exc):
                 raise
         return stored

ksadk/memory/adk/short_term_memory.py

@@ -153,18 +153,17 @@ class ShortTermMemory(BaseModel):
         try:
             from ksadk.compat.adk_compat import DatabaseSessionService
             from ksadk.memory.adk.resilient_session_service import ResilientADKSessionService
-            from ksadk.sessions.resilience import session_backend_timeout_seconds
-
-            service_kwargs = {}
             if normalized_db_url.startswith(("postgresql://", "postgresql+asyncpg://")):
-                timeout = session_backend_timeout_seconds()
-                service_kwargs["connect_args"] = {
-                    "timeout": timeout,
-                    "command_timeout": timeout,
-                }
+                from ksadk.memory.adk.bounded_database_session_service import (
+                    BoundedADKDatabaseSessionService,
+                )
+
+                primary = BoundedADKDatabaseSessionService(db_url=normalized_db_url)
+            else:
+                primary = DatabaseSessionService(db_url=normalized_db_url)
 
             self._session_service = ResilientADKSessionService(
-                DatabaseSessionService(db_url=normalized_db_url, **service_kwargs)
+                primary
             )
             logger.info("ShortTermMemory: using DatabaseSessionService")
         except ImportError:

ksadk/memory/coordinator.py

@@ -129,6 +129,11 @@ class MemoryCoordinator:
                 latency_ms=0,
                 accounting_accuracy="opaque",
             )
+        # TTL / 状态过滤（长任务方案 §7.2）：过期与已 supersede 的记录不进召回。
+        now_iso = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        active = [r for r in result.records if r.is_active_now(now_iso=now_iso)]
+        if len(active) != len(result.records):
+            result = replace(result, records=active)
         return result
 
     def list_core(self, request: CoreMemoryRequest) -> list[MemoryRecord]:
@@ -270,6 +275,11 @@ class MemoryCoordinator:
                 by_id[record.memory_id] = record
         return list(by_id.values())
 
+    def find_existing_for_candidate(self, candidate: MemoryCandidate) -> MemoryRecord | None:
+        """Return the active fact occupying the candidate's logical slot."""
+        records = self._find_active_slot_records(candidate)
+        return records[0] if records else None
+
     def propose_and_commit(
         self,
         candidate: MemoryCandidate,
@@ -346,7 +356,7 @@ class MemoryCoordinator:
             importance=candidate.importance,
             valid_from=now_iso,
             valid_to="",
-            expires_at="",
+            expires_at=candidate.expires_at,
             source_session_id="",
             source_event_ids=list(candidate.source_event_ids),
             source_seq_range=None,
@@ -359,17 +369,23 @@ class MemoryCoordinator:
                 "operation": evaluation.operation,
                 **({"slot_key": candidate.slot_key} if candidate.slot_key else {}),
                 **(
-                    {
-                        "supersedes": [
-                            item.memory_id for item in conflicting_records or [existing]
-                        ]
-                    }
+                    {"supersedes": [item.memory_id for item in conflicting_records or [existing]]}
                     if evaluation.operation == "update" and existing is not None
                     else {}
                 ),
             },
             created_at=now_iso,
             updated_at=now_iso,
+            # 长任务方案 §7.2：来源 Artifact / 敏感级别 / 写策略 / TTL / supersede 链。
+            source_artifact_refs=tuple(candidate.source_artifact_refs),
+            source_artifacts=tuple(candidate.source_artifacts),
+            sensitivity=candidate.sensitivity,
+            write_policy=candidate.write_policy,
+            supersedes=tuple(
+                item.memory_id for item in (conflicting_records or [existing]) if item is not None
+            )
+            if evaluation.operation == "update" and existing is not None
+            else (),
         )
         self._provider.upsert(
             record,

ksadk/memory/extraction.py

@@ -12,8 +12,12 @@
 
 from __future__ import annotations
 
+import hashlib
+import json
 import re
 import uuid
+from dataclasses import replace
+from types import SimpleNamespace
 from typing import Sequence
 
 from ksadk.memory.models import MemoryCandidate, MemoryScope
@@ -25,6 +29,23 @@ _EXPLICIT_PATTERNS: tuple[re.Pattern[str], ...] = (
     re.compile(r"(?i)remember\s+(?:that\s+)?(.+)", re.IGNORECASE),
     re.compile(r"(?i)请记[:：]?\s*(.+)"),
 )
+# A declared conversation/turn horizon belongs to Session history, not the
+# cross-session Memory provider. Inspect the memory-bearing first statement:
+# a later "For this turn reply ACK" only scopes the answer format.
+_SESSION_RETENTION = re.compile(
+    r"\b(?:for|during|within|in)\s+(?:only\s+)?(?:this|the\s+current)\s+"
+    r"(?:conversation|chat|session|turn)\b"
+    r"|(?:本次|这次|此次|当前|这个|本)(?:会话|对话|聊天)"
+    r"|(?:本轮|这轮)",
+    re.IGNORECASE,
+)
+
+
+def _session_only_memory(text: str) -> bool:
+    statement = re.split(r"[。！？!?\r\n]|\.(?=\s|$)", text.strip(), maxsplit=1)[0]
+    return _SESSION_RETENTION.search(statement) is not None
+
+
 # 明确纠正同一偏好槽位。首期只覆盖语义边界清晰的动作型偏好，避免把
 # “喜欢音乐”和“喜欢运动”等无关事实误判为冲突。
 _PREFERENCE_CORRECTION = re.compile(
@@ -34,6 +55,14 @@ _PREFERENCE_CORRECTION = re.compile(
     re.IGNORECASE,
 )
 _PREFERENCE_SLOT = re.compile(r"(?:我|本人)?喜欢(?P<action>吃|喝|用|看|听|玩)")
+# 一般祈使纠偏（"以后报表不要用英文，请改成中文"）：语义边界不如动作型偏好
+# 清晰，但"否定旧值 + 指定新值"结构明确，仍按显式纠错（update）处理。
+_GENERAL_CORRECTION = re.compile(
+    r"(?:以后|今后)?(?P<subject>[一-龥A-Za-z0-9]{1,12})?"
+    r"(?:请)?(?:不要|别)(?P<old>.{1,20}?)[，,]?"
+    r"(?:请)?(?:改成|改为|换成|改用)(?P<new>.+?)(?:[。.!！]|$)",
+    re.IGNORECASE,
+)
 _HOBBY_DECLARATION = re.compile(
     r"(?:我|本人)?的?爱好(?P<correction>其实|现在|改)?(?:是|改成|变成)\s*(?P<value>.+?)"
     r"(?:[。.!！]|$)",
@@ -47,7 +76,16 @@ _IMPLICIT_PREFERENCE_PATTERNS: tuple[re.Pattern[str], ...] = (
     ),
 )
 # 工具稳定事实信号。
-_FACT_SIGNALS = ("confirmed", "最终确认", "final", "verified", "确认成功")
+_FACT_SIGNALS = (
+    "confirmed",
+    "最终确认",
+    "final",
+    "verified",
+    "确认成功",
+    "查询成功",
+    "已认证",
+    "已核实",
+)
 
 
 def _event_text(event: any) -> str:  # type: ignore[name-defined]
@@ -78,17 +116,44 @@ def derive_profile_slot_key(content: str) -> str:
     return f"profile.preference.{labels[action]}"
 
 
+def is_explicit_memory_instruction(text: str) -> bool:
+    """Recognize a complete durable instruction, not a quoted substring.
+
+    Candidate extraction intentionally searches larger transcripts. A host
+    granting an immediate explicit write needs the narrower whole-input test.
+    Unsupported wording can use the host's exact-call consent path; this is
+    not a general semantic intent classifier.
+    """
+    text = text.strip()
+    if _session_only_memory(text):
+        return False
+    if any(pattern.fullmatch(text) for pattern in _EXPLICIT_PATTERNS):
+        return True
+    if _PREFERENCE_CORRECTION.fullmatch(text) or _GENERAL_CORRECTION.fullmatch(text):
+        return True
+    hobby = _HOBBY_DECLARATION.fullmatch(text)
+    return bool(hobby and hobby.group("correction"))
+
+
 def propose_memory_candidates(
     events: Sequence[any],  # type: ignore[name-defined]
     *,
     scope: MemoryScope = "user",
     scope_id: str = "",
+    max_content_chars: int | None = 1000,
 ) -> list[MemoryCandidate]:
     """从待压缩事件提取记忆候选（方案 §9.2）。
 
     纯确定性、无 LLM。返回候选列表交 Coordinator flush；Policy 决定 commit/reject。
     """
     candidates: list[MemoryCandidate] = []
+    if max_content_chars is not None and (
+        type(max_content_chars) is not int or max_content_chars < 1
+    ):
+        raise ValueError("memory candidate limit must be a positive integer or None")
+
+    def bounded(content):
+        return content if max_content_chars is None else content[:max_content_chars]
     if not events:
         return candidates
     for event in events:
@@ -102,6 +167,8 @@ def propose_memory_candidates(
 
         # 1. 用户显式记忆意图
         if author == "user" or event_type == "user_message":
+            if _session_only_memory(text):
+                continue
             hobby = _HOBBY_DECLARATION.search(text)
             if hobby and hobby.group("correction"):
                 new_value = hobby.group("value").strip().strip("。.，, ")
@@ -114,7 +181,7 @@ def propose_memory_candidates(
                             memory_type="profile",
                             scope=scope,
                             scope_id=scope_id,
-                            content=content[:1000],
+                            content=bounded(content),
                             confidence=0.95,
                             importance=0.9,
                             source_event_ids=[event_id],
@@ -123,6 +190,28 @@ def propose_memory_candidates(
                         )
                     )
                     continue
+            general = _GENERAL_CORRECTION.search(text)
+            if general:
+                subject = (general.group("subject") or "").strip()
+                new_value = general.group("new").strip().strip("。.，, ")
+                if new_value:
+                    content = f"{subject}改为{new_value}" if subject else f"改为{new_value}"
+                    candidates.append(
+                        MemoryCandidate(
+                            candidate_id=f"cand_{uuid.uuid4().hex[:16]}",
+                            operation="update",
+                            memory_type="profile",
+                            scope=scope,
+                            scope_id=scope_id,
+                            content=bounded(content),
+                            confidence=0.9,
+                            importance=0.8,
+                            source_event_ids=[event_id],
+                            slot_key=derive_profile_slot_key(content),
+                            reason="explicit_user_correction",
+                        )
+                    )
+                    continue
             correction = _PREFERENCE_CORRECTION.search(text)
             if correction:
                 prefix = correction.group("prefix").strip()
@@ -136,7 +225,7 @@ def propose_memory_candidates(
                             memory_type="profile",
                             scope=scope,
                             scope_id=scope_id,
-                            content=content[:1000],
+                            content=bounded(content),
                             confidence=0.95,
                             importance=0.9,
                             source_event_ids=[event_id],
@@ -158,7 +247,7 @@ def propose_memory_candidates(
                             memory_type="profile",
                             scope=scope,
                             scope_id=scope_id,
-                            content=content[:1000],
+                            content=bounded(content),
                             confidence=0.9,
                             importance=0.8,
                             source_event_ids=[event_id],
@@ -182,7 +271,7 @@ def propose_memory_candidates(
                             memory_type="profile",
                             scope=scope,
                             scope_id=scope_id,
-                            content=content[:1000],
+                            content=bounded(content),
                             confidence=0.75,
                             importance=0.65,
                             source_event_ids=[event_id],
@@ -203,7 +292,7 @@ def propose_memory_candidates(
                     memory_type="fact",
                     scope=scope,
                     scope_id=scope_id,
-                    content=text[:1000],
+                    content=bounded(text),
                     confidence=0.7,
                     importance=0.6,
                     source_event_ids=[event_id],
@@ -214,6 +303,65 @@ def propose_memory_candidates(
     return candidates
 
 
+def explicit_memory_target(text: str) -> tuple[str, str] | None:
+    """Decode one whole explicit goal without truncating its requested fact.
+
+    This is a pure intent interpretation. The synthetic extraction input never
+    supplies persisted provenance or write authorization; those remain the
+    host's actual goal, approval and Run event identities.
+    """
+    if not is_explicit_memory_instruction(text):
+        return None
+    candidates = propose_memory_candidates(
+        (SimpleNamespace(text=text, author="user", event_type="user_message"),),
+        max_content_chars=None,
+    )
+    explicit = [candidate for candidate in candidates
+                if candidate.reason.startswith("explicit_user")]
+    if len(explicit) != 1:
+        return None
+    return explicit[0].operation, explicit[0].content
+
+
+NATIVE_USER_EXTRACTION_POLICY = "native-original-user-profile/v2"
+
+
+def native_user_memory_candidate(
+    text: str, *, source_event_id: str, scope: MemoryScope, scope_id: str,
+) -> MemoryCandidate | None:
+    """Interpret a complete original user statement, never a transcript substring.
+
+    The host must supply canonical user input and its durable source identity.
+    Confidence describes known user authorship, not the truth of a preference
+    or permission to persist it. The existing Policy still requires independent
+    observations for implicit declarations. No model/summary/tool text is admitted.
+    """
+    text = text.strip()
+    explicit = is_explicit_memory_instruction(text)
+    implicit = any(pattern.fullmatch(text) for pattern in _IMPLICIT_PREFERENCE_PATTERNS)
+    hobby = _HOBBY_DECLARATION.fullmatch(text)
+    if not source_event_id.strip() or not (explicit or implicit or hobby):
+        return None
+    proposed = propose_memory_candidates(
+        (SimpleNamespace(text=text, author="user", event_type="user_message"),),
+        scope=scope, scope_id=scope_id, max_content_chars=None,
+    )
+    if not proposed and hobby and not hobby.group("correction"):
+        proposed = [MemoryCandidate(
+            candidate_id="pending", operation="add", memory_type="profile", scope=scope,
+            scope_id=scope_id, content=f"我的爱好是{hobby.group('value').strip()}",
+            confidence=1, importance=0.65, source_event_ids=[source_event_id],
+            reason="implicit_user_preference", slot_key="profile.preference.hobby",
+        )]
+    if len(proposed) != 1 or (not explicit and proposed[0].reason != "implicit_user_preference"):
+        return None
+    value = proposed[0]
+    identity = json.dumps((NATIVE_USER_EXTRACTION_POLICY, scope, scope_id, source_event_id,
+                           value.operation, value.content), ensure_ascii=False)
+    return replace(value, candidate_id="candidate_" + hashlib.sha256(identity.encode()).hexdigest(),
+                   confidence=1, source_event_ids=[source_event_id])
+
+
 class MemoryExtractor:
     """方案 §9.2 的 ``MemoryExtractor.propose()`` 接口封装。"""
 
@@ -225,4 +373,8 @@ class MemoryExtractor:
         return propose_memory_candidates(events, scope=self._scope, scope_id=self._scope_id)
 
 
-__all__ = ["MemoryExtractor", "derive_profile_slot_key", "propose_memory_candidates"]
+__all__ = [
+    "MemoryExtractor", "derive_profile_slot_key", "explicit_memory_target",
+    "is_explicit_memory_instruction", "propose_memory_candidates",
+    "native_user_memory_candidate", "NATIVE_USER_EXTRACTION_POLICY",
+]