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

ksadk/kernel/store.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""``AgentKernelStore`` port：durable Inbox / Run / ActivationLease 状态（Phase 1 Task 3）。
+"""``AgentKernelStore`` port：durable Inbox / Run / ActivationLease 状态（Kernel Task 3）。
 
 所有 mutation 都接受 ``expected_fence: int`` 并与当前 activation lease 的
 fencing token 做事务内 CAS 比较；不匹配抛 :class:`StaleFenceError`。
@@ -13,7 +13,7 @@ import hashlib
 import json
 from dataclasses import dataclass
 from datetime import datetime, timezone
-from typing import Protocol, runtime_checkable
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
 from uuid import uuid4
 
 from ksadk.kernel.contracts import (
@@ -24,6 +24,14 @@ from ksadk.kernel.contracts import (
 )
 from ksadk.kernel.state import InboxState, RunState
 
+if TYPE_CHECKING:
+    from ksadk.kernel.execution_grants import (
+        ExecutionGrantBarrier,
+        ExecutionGrantRecord,
+        ExecutionGrantSpec,
+        GrantState,
+    )
+
 
 def now_utc() -> datetime:
     return datetime.now(timezone.utc)
@@ -191,10 +199,43 @@ class AgentKernelStore(Protocol):
         self, command: AgentControlCommand, *, queue_limit: int
     ) -> AgentControlReceipt: ...
 
+    async def ensure_execution_grant(
+        self, spec: ExecutionGrantSpec
+    ) -> ExecutionGrantRecord: ...
+
+    async def get_execution_grant(
+        self, spec: ExecutionGrantSpec
+    ) -> ExecutionGrantBarrier | None: ...
+
+    async def set_execution_grant_state(
+        self, spec: ExecutionGrantSpec, state: GrantState, *,
+        expected_revision: int, idempotency_key: str,
+    ) -> ExecutionGrantBarrier: ...
+
     async def claim_next(
         self, agent_instance_id: str, session_id: str, fencing_token: int
     ) -> InboxMessage | None: ...
 
+    async def list_messages(
+        self, agent_instance_id: str, session_id: str | None = None
+    ) -> list[InboxMessage]: ...
+
+    async def list_pending(
+        self,
+        agent_instance_id: str,
+        session_id: str | None = None,
+        *,
+        fencing_token: int | None = None,
+    ) -> list[InboxMessage]: ...
+
+    async def claim_message(
+        self, message_id: str, fencing_token: int
+    ) -> InboxMessage: ...
+
+    async def discard_claim(
+        self, message_id: str, *, expected_fence: int
+    ) -> None: ...
+
     async def complete_claim(self, message_id: str, *, expected_fence: int) -> None: ...
 
     async def acquire_activation(self, request: ActivationLeaseRequest) -> ActivationLease: ...
@@ -221,6 +262,32 @@ class AgentKernelStore(Protocol):
 
     async def load_message(self, message_id: str) -> InboxMessage | None: ...
 
+    async def load_by_idempotency(
+        self, session_id: str, idempotency_key: str
+    ) -> InboxMessage | None: ...
+
+    async def reject_command(
+        self,
+        command: AgentControlCommand,
+        *,
+        status: str,
+        code: str,
+        message: str,
+        retryable: bool = False,
+    ) -> AgentControlReceipt: ...
+
+    async def inbox_depth(
+        self, agent_instance_id: str, session_id: str | None = None
+    ) -> int: ...
+
+    async def find_active_run(
+        self, agent_instance_id: str, session_id: str | None = None
+    ) -> RunRecord | None: ...
+
+    async def current_lease(
+        self, agent_instance_id: str, session_id: str | None = None
+    ) -> ActivationLease | None: ...
+
 
 __all__ = [
     "AgentKernelStore",

ksadk/kernel/worker.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""per-session FIFO worker（Phase 1 Task 6 Step 6）。
+"""per-session FIFO worker（Kernel Task 6 Step 6）。
 
 - 持有 activation lease（fencing token 通过 Store 的 CAS 校验）才能 claim。
 - 按 per-session accepted_seq 保序；active Run 存在时普通 enqueue 保持排队，
@@ -19,7 +19,6 @@ execution（同一 client 实例）；control lookup 永远按 durable run id。
 from __future__ import annotations
 
 import asyncio
-import json
 import logging
 from collections.abc import Callable, Mapping
 from dataclasses import dataclass, replace
@@ -36,6 +35,7 @@ from ksadk.interaction.provider import (
     UnavailableInteractionProvider,
 )
 from ksadk.interaction.providers import default_interaction_providers
+from ksadk.kernel.approval_presentation import approval_presentation
 from ksadk.kernel.contracts import (
     ActivationLease,
     ActivationWriteGuard,
@@ -54,6 +54,11 @@ from ksadk.kernel.errors import (
     StaleFenceError,
     UnsupportedControlError,
 )
+from ksadk.kernel.execution_grants import (
+    ExecutionGrantBlocked,
+    execution_grant_id,
+    execution_grant_run_id,
+)
 from ksadk.kernel.mapping import COMMAND_HANDLERS, RESUME_TARGET_KINDS
 from ksadk.kernel.state import RunState
 from ksadk.kernel.store import (
@@ -62,7 +67,9 @@ from ksadk.kernel.store import (
     control_event,
     new_message_id,
 )
+from ksadk.kernel.worker_identity import prepare_worker_identity
 from ksadk.runtime.adapter import (
+    CONVERSATION_PREPROCESSING_METADATA_KEY,
     CancelResult,
     PauseResult,
     RunHandle,
@@ -75,6 +82,7 @@ from ksadk.runtime.adapter import (
 from ksadk.runtime.adapter import (
     ResumeTarget as AdapterResumeTarget,
 )
+from ksadk.runtime_context import TRUSTED_IDENTITY_METADATA_KEY
 
 logger = logging.getLogger(__name__)
 
@@ -121,12 +129,14 @@ class AgentKernelWorker:
         session_events: object | None = None,
         interaction_providers: Mapping[str, InteractionProvider] | None = None,
         start_request_defaults: Mapping[str, object] | None = None,
+        session_service: object | None = None,
     ) -> None:
         self._store = store
         self._adapter_factory = adapter_factory
         # SessionEventStore（typed RuntimeEventStore 的 envelope 写路径）。
         # 缺省时不落 runtime 事件，仅保证 stream 被消费到自然结束。
         self._session_events = session_events
+        self._session_service = session_service
         # Deployment-owned defaults (model, prompt and sandbox) come from the
         # admitted immutable manifest. Server may attach a bounded per-turn
         # model/approval selector to the signed command; the worker validates
@@ -247,27 +257,31 @@ class AgentKernelWorker:
         # enqueue，此时其后的 interrupt/pause/steer 等控制命令必须能越过
         # 该 enqueue 作用于 active Run。只处理当前 activation 持有 lease 的
         # session，避免跨 session 抢占。
-        eligible = None
+        suspended_enqueue = False
         for message in sorted(pending, key=lambda m: m.accepted_seq):
             if session_id is not None and message.session_id != session_id:
                 continue
             lease = await self._store.current_lease(agent_instance_id, message.session_id)
             if lease is None or lease.activation_id != activation.activation_id:
-                continue  # 该 session 归其它 activation（或无人）持有
-            if message.command is None:  # pragma: no cover - defensive
+                continue
+            if message.command is None:
                 continue
             if message.command.command_type == "enqueue":
                 active = await self._store.find_active_run(agent_instance_id, message.session_id)
-                if active is not None:
-                    continue  # enqueue 保持排队
-            eligible = message
-            break
-        if eligible is None:
-            return WorkResult(outcome="idle")
-
-        claimed = await self._store.claim_message(eligible.message_id, fence)
-        result = await self._execute_claim(claimed.command, activation)
-        return result
+                if active is not None or suspended_enqueue:
+                    continue
+            try:
+                # Store claim and execution-grant validation share one atomic
+                # transaction. A prior list/read is never start authorization.
+                claimed = await self._store.claim_message(message.message_id, fence)
+            except ExecutionGrantBlocked as error:
+                if error.grant_state in {"suspended", "queued", "busy"}:
+                    # Preserve enqueue FIFO while still letting cancel/resume
+                    # controls behind the suspended command reach active work.
+                    suspended_enqueue = True
+                continue
+            return await self._execute_claim(claimed.command, activation)
+        return WorkResult(outcome="idle")
 
     # ------------------------------------------------------------- execution
 
@@ -382,7 +396,21 @@ class AgentKernelWorker:
 
         fence = activation.fencing_token
         guard = ActivationWriteGuard(activation_id=activation.activation_id, fencing_token=fence)
-        run_id = new_message_id()
+        grant_id = execution_grant_id(command)
+        run_id = execution_grant_run_id(command) if grant_id else new_message_id()
+        if grant_id:
+            previous = await self._store.load_run(run_id)
+            if previous is not None:
+                # Once start may have reached the provider, neither a lost ACK
+                # nor takeover may invent a second model run. Normal recovery
+                # attaches durable handles; a handle-less pending start is
+                # uncertain and requires attention, never an automatic replay.
+                if previous.state == RunState.PENDING:
+                    await self._store.save_run_transition(previous.model_copy(update={
+                        "state": RunState.INTERRUPTED,
+                        "reason": "execution_start_uncertain",
+                    }), expected_fence=fence)
+                return run_id
         adapter = self._adapter_factory()
         pending = RunRecord(
             run_id=run_id,
@@ -396,6 +424,7 @@ class AgentKernelWorker:
             # back to one occurrence without matching text or wall-clock time.
             metadata={
                 "command_id": str(command.command_id),
+                **({"execution_grant_id": grant_id} if grant_id else {}),
                 "source_kind": command.source.kind,
                 "source_ref": command.source.ref,
                 "correlation_id": command.correlation_id,
@@ -429,10 +458,26 @@ class AgentKernelWorker:
         }
         if approval_mode in approval_overrides:
             request_config["approval_mode"] = approval_overrides[approval_mode]
+        effective_user_id, invocation_identity = await prepare_worker_identity(
+            command=command,
+            defaults=defaults,
+            session_service=self._session_service,
+        )
+
+        conversation_metadata = {}
+        if adapter.runtime.runtime_type == "harness" and self._session_events is not None:
+            from ksadk.kernel.worker_history import harness_conversation_messages
+
+            conversation_metadata[CONVERSATION_PREPROCESSING_METADATA_KEY] = {
+                "messages": await harness_conversation_messages(
+                    command, store=self._store, session_events=self._session_events,
+                ),
+            }
+
         handle = await adapter.start(
             StartRequest(
                 input=command.payload.get("content"),
-                user_id=str(command.tenant_id or "agent-kernel"),
+                user_id=effective_user_id,
                 session_id=command.session_id,
                 agent_id=str(defaults.get("agent_id") or command.agent_instance_id),
                 model=selected_model,
@@ -447,7 +492,21 @@ class AgentKernelWorker:
                     ),
                     "command_id": str(command.command_id),
                     "run_id": run_id,
+                    **(
+                        {TRUSTED_IDENTITY_METADATA_KEY: dict(invocation_identity)}
+                        if isinstance(invocation_identity, Mapping)
+                        else {}
+                    ),
                     **continuation_metadata,
+                    **conversation_metadata,
+                    # Opaque policy reference is supplied only by a trusted
+                    # ingress. The Provider resolves and reauthorizes it for
+                    # this exact Run; Kernel owns no plugin policy semantics.
+                    **(
+                        {"execution_policy_ref": command.payload["execution_policy_ref"]}
+                        if isinstance(command.payload.get("execution_policy_ref"), str)
+                        else {}
+                    ),
                 },
             )
         )
@@ -747,7 +806,7 @@ class AgentKernelWorker:
         """Persist one framework interaction as the durable ledger authority."""
 
         from ksadk.events.canonical import ApprovalRequest, InteractionRequested
-        from ksadk.interaction.contracts import InteractionPresentation, InteractionRecord
+        from ksadk.interaction.contracts import InteractionRecord
 
         assert isinstance(event, InteractionRequested)
         presentation = None
@@ -763,25 +822,7 @@ class AgentKernelWorker:
                 "required": ["decision"],
             }
             native_target = {"call_id": event.request.call_id or event.interaction_id}
-            detail = event.request.detail if isinstance(event.request.detail, Mapping) else {}
-            visible_arguments = {
-                key: detail[key]
-                for key in ("command", "cwd", "reason", "grantRoot", "proposedExecpolicyAmendment")
-                if key in detail and detail[key] is not None
-            }
-            presentation = InteractionPresentation(
-                title={
-                    "command_execution": "run_command",
-                    "file_change": "apply_patch",
-                    "permissions": "request_permission",
-                    "dynamic_tool_call": "tool_call",
-                }.get(event.request.kind, event.request.kind),
-                description=json.dumps(
-                    {"arguments": visible_arguments},
-                    ensure_ascii=False,
-                    separators=(",", ":"),
-                ),
-            )
+            presentation = approval_presentation(event.request)
         else:
             request_schema = dict(event.request.schema_)
             # Codex maps the native JSON-RPC request id to a stable canonical
@@ -933,10 +974,7 @@ class AgentKernelWorker:
         # e.g. calling LangGraph checkpoint resume with a Codex live handle
         # would acknowledge a response that can never reach the original run.
         provider = execution.interaction_provider
-        if (
-            provider.provider_id != record.provider_id
-            or provider.mode == "unavailable"
-        ):
+        if provider.provider_id != record.provider_id or provider.mode == "unavailable":
             raise AgentKernelError(
                 RUNTIME_INTERACTION_UNAVAILABLE,
                 f"interaction provider {record.provider_id!r} cannot deliver "

ksadk/kernel/worker_history.py

@@ -0,0 +1,72 @@
+"""Recover Harness turn input from the Kernel's durable conversation facts."""
+
+from __future__ import annotations
+
+from ksadk.conversations.context import project_model_messages
+from ksadk.events.canonical import RunCompleted
+from ksadk.events.canonical_store import RuntimeEventStore, runtime_event_to_session_event
+from ksadk.kernel.contracts import AgentControlCommand
+from ksadk.kernel.state import RunState
+from ksadk.kernel.store import AgentKernelStore
+from ksadk.sessions.base import SessionEvent
+
+
+async def harness_conversation_messages(
+    command: AgentControlCommand,
+    *,
+    store: AgentKernelStore,
+    session_events: object,
+) -> list[dict[str, str]]:
+    """Project successful prior turns; never use an adapter's process cache.
+
+    Harness checkpoints belong to individual Runs. The Kernel retains the
+    admitted user input in its Inbox and the reply in canonical RuntimeEvents;
+    join those facts by Run.command_id, within this instance, tenant and Session.
+    Reuse conversation projection so tool/approval and multiple-message semantics
+    stay aligned with the ordinary conversation preparation path.
+    """
+
+    inbox = {
+        str(message.command.command_id): message.command
+        for message in await store.list_messages(command.agent_instance_id, command.session_id)
+        if message.command is not None
+        and message.command.command_type == "enqueue"
+        and message.command.tenant_id == command.tenant_id
+        and message.command.session_id == command.session_id
+        and message.command.agent_instance_id == command.agent_instance_id
+        and message.command.command_id != command.command_id
+    }
+    events = await RuntimeEventStore(session_events).list(command.session_id)
+    by_run: dict[str, list[SessionEvent]] = {}
+    projected_runs: set[str] = set()
+    history: list[dict[str, str]] = []
+    for event in events:
+        rows = by_run.setdefault(event.run_id, [])
+        rows.append(runtime_event_to_session_event(command.session_id, event))
+        if not isinstance(event, RunCompleted) or event.run_id in projected_runs:
+            continue
+        run = await store.load_run(event.run_id)
+        if (
+            run is None
+            or run.state is not RunState.COMPLETED
+            or run.agent_instance_id != command.agent_instance_id
+            or run.session_id != command.session_id
+        ):
+            continue
+        previous = inbox.get(str(run.metadata.get("command_id") or ""))
+        if previous is None:
+            continue
+        # This row is an in-memory projection of the already-admitted Inbox
+        # command, not another persistent copy of the user's message.
+        user = SessionEvent(
+            id=str(previous.command_id),
+            session_id=command.session_id,
+            invocation_id=run.run_id,
+            event_type="user_message",
+            content={"parts": [{"text": str(previous.payload.get("content") or "")}]},
+            seq_id=max(1, rows[0].seq_id - 1),
+        )
+        history.extend(project_model_messages([user, *rows], assistant_role="assistant"))
+        projected_runs.add(event.run_id)
+    history.append({"role": "user", "content": str(command.payload.get("content") or "")})
+    return history

ksadk/kernel/worker_identity.py

@@ -0,0 +1,47 @@
+"""Trusted business-identity preparation for kernel worker starts."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from ksadk.conversations.runtime_persistence import ensure_conversation_session
+from ksadk.kernel.contracts import AgentControlCommand
+from ksadk.sessions.invocation_identity import identity_native_user_id
+
+
+async def prepare_worker_identity(
+    *,
+    command: AgentControlCommand,
+    defaults: Mapping[str, object],
+    session_service: object | None,
+) -> tuple[str, Mapping[str, Any] | None]:
+    """Resolve the storage user and retain only an admitted identity payload."""
+
+    invocation_identity = command.payload.get("invocation_identity")
+    effective_user_id = str(command.tenant_id or "agent-kernel")
+    if not isinstance(invocation_identity, Mapping):
+        return effective_user_id, None
+    if session_service is None:
+        return identity_native_user_id(invocation_identity), invocation_identity
+
+    # Hosted runtimes have two stable identifiers: the platform deployment
+    # instance (used by the Kernel command) and the public AgentId used by
+    # CreateSession/RunAgent.  The admission path has already authorized the
+    # command against this session; use the persisted session owner as the
+    # canonical lookup key instead of treating the internal instance alias as
+    # a different Agent.  This prevents a valid hosted turn from becoming a
+    # misleading ``Session not found`` during worker startup.
+    agent_id = str(defaults.get("agent_id") or command.agent_instance_id)
+    existing = await session_service.get_session_metadata(command.session_id)
+    if existing is not None and str(existing.agent_id or "").strip():
+        agent_id = str(existing.agent_id)
+    canonical_session = await ensure_conversation_session(
+        agent_id=agent_id,
+        user_id=effective_user_id,
+        session_id=command.session_id,
+        session_service_provider=lambda: session_service,
+        invocation_identity=invocation_identity,
+        allow_agent_alias=True,
+    )
+    return canonical_session.user_id, invocation_identity

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

@@ -34,6 +34,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 +55,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]
@@ -123,6 +140,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=content[:1000],
+                            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()