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

ksadk/kernel/recovery.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""冷恢复决策表：RecoveryCoordinator（Phase 1 Task 7）。
+"""冷恢复决策表：RecoveryCoordinator（Kernel Task 7）。
 
 接管一个 agent_instance 的 open run 时按固定决策表收口：
 
@@ -31,6 +31,7 @@ from ksadk.kernel.contracts import (
     RuntimeCapabilityMatrix,
     WriteContext,
 )
+from ksadk.kernel.errors import InvalidCommandError, StaleFenceError
 from ksadk.kernel.state import RunState, is_terminal_run
 from ksadk.kernel.store import AgentKernelStore, RunRecord, control_event
 
@@ -100,12 +101,15 @@ class RecoveryCoordinator:
         activation: ActivationLease,
         *,
         run_id: str | None = None,
+        session_id: str | None = None,
     ) -> RecoveryReport:
         fence = activation.fencing_token
         guard: WriteContext = ActivationWriteGuard(
             activation_id=activation.activation_id, fencing_token=fence
         )
-        run = await self._load_run(agent_instance_id, run_id)
+        run = await self._load_run(agent_instance_id, run_id, session_id=session_id)
+        if run is not None:
+            await self._require_session_lease(run, activation)
         if run is None or is_terminal_run(run.state):
             return await self._decide(
                 agent_instance_id,
@@ -131,11 +135,36 @@ class RecoveryCoordinator:
             capabilities.attach.supported
             and capabilities.durable_restore.supported
             and handle_digest_valid
-            and self._executor is not None
-            and self._launch_context is not None
+            and (
+                self._adapter_factory is not None
+                or (self._executor is not None and self._launch_context is not None)
+            )
         ):
             try:
-                handle = await self._executor.attach_record(run, self._launch_context)
+                from ksadk.runtime.adapter import RunHandle
+
+                persisted_handle = RunHandle.model_validate(handle_dump)
+                if self._adapter_factory is not None:
+                    # PluginHost/DSH builds must recover through their pinned
+                    # provider adapter. Going through the global RuntimeExecutor
+                    # would create a different direct runtime and bypass the
+                    # provider's checkpoint, capabilities and resources.
+                    adapter = self._adapter_factory()
+                    handle = await adapter.durable_restore(persisted_handle)
+                    if handle != persisted_handle:
+                        raise ValueError(
+                            "adapter durable_restore must preserve persisted handle identity"
+                        )
+                    stream_owner = adapter
+                else:
+                    assert self._executor is not None
+                    assert self._launch_context is not None
+                    handle = await self._executor.attach_record(run, self._launch_context)
+                    adapter = getattr(self._executor, "adapter", None)
+                    stream_owner = self._executor
+
+                def stream():  # type: ignore[no-untyped-def]
+                    return stream_owner.stream(handle)
             except Exception as error:
                 return await self._decide(
                     agent_instance_id,
@@ -150,13 +179,26 @@ class RecoveryCoordinator:
             self._register_execution(
                 run.run_id,
                 handle.run_id,
-                getattr(self._executor, "adapter", None),
+                adapter,
                 handle,
             )
+            if run.state is RunState.WAITING:
+                # A durable interaction checkpoint has no remaining events
+                # until a user/approver replies.  Empty stream output here is
+                # not completion: retain WAITING and the attached execution so
+                # submit_interaction reaches the same provider instance.
+                return await self._decide(
+                    agent_instance_id,
+                    activation,
+                    run,
+                    outcome="attached",
+                    reason="durable_interaction_attached",
+                    guard=guard,
+                )
             # attach 成功后重新消费剩余 stream：事实继续落库，自然结束收口。
             try:
                 await self._consume_remaining_stream(
-                    lambda: self._executor.stream(handle),  # type: ignore[union-attr]
+                    stream,
                     run,
                     guard,
                 )
@@ -203,6 +245,7 @@ class RecoveryCoordinator:
         activation: ActivationLease,
         *,
         reason: str = "recover_error_settled_interrupted",
+        session_id: str | None = None,
     ) -> RecoveryReport:
         """P0-1 兜底收口：``recover`` 抛错后的确定性 interrupted 决策。
 
@@ -216,7 +259,9 @@ class RecoveryCoordinator:
             activation_id=activation.activation_id,
             fencing_token=activation.fencing_token,
         )
-        run = await self._load_run(agent_instance_id, None)
+        run = await self._load_run(agent_instance_id, None, session_id=session_id)
+        if run is not None:
+            await self._require_session_lease(run, activation)
         if run is None or is_terminal_run(run.state):
             return await self._decide(
                 agent_instance_id,
@@ -346,14 +391,33 @@ class RecoveryCoordinator:
         )
 
     async def _load_run(
-        self, agent_instance_id: str, run_id: str | None
+        self, agent_instance_id: str, run_id: str | None, *, session_id: str | None
     ) -> RunRecord | None:
         if run_id is not None:
-            return await self._store.load_run(run_id)
-        finder = getattr(self._store, "find_active_run", None)
-        if finder is not None:
-            return await finder(agent_instance_id)
-        return None
+            run = await self._store.load_run(run_id)
+        else:
+            run = await self._store.find_active_run(agent_instance_id, session_id)
+        if run is not None and (
+            run.agent_instance_id != agent_instance_id
+            or (session_id is not None and run.session_id != session_id)
+        ):
+            raise InvalidCommandError("Run does not belong to the requested recovery scope")
+        return run
+
+    async def _require_session_lease(
+        self, run: RunRecord, activation: ActivationLease
+    ) -> None:
+        # Fencing counters are independent per session and commonly equal.
+        # Validate the activation identity before attaching a native execution;
+        # a matching integer alone cannot authorize another member's Run.
+        owned = await self._store.current_lease(run.agent_instance_id, run.session_id)
+        if (
+            activation.agent_instance_id != run.agent_instance_id
+            or owned is None
+            or owned.activation_id != activation.activation_id
+            or owned.fencing_token != activation.fencing_token
+        ):
+            raise StaleFenceError("recovery requires the Run's current session lease")
 
     async def _interrupt_deterministically(
         self,

ksadk/kernel/sql/001_agent_kernel.sql

@@ -118,3 +118,26 @@ CREATE TABLE IF NOT EXISTS kernel_interaction_submissions (
   created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
   PRIMARY KEY (tenant_id, interaction_id, idempotency_key)
 );
+
+-- Revocable execution-grants/v1 extension. Grant lock precedes Inbox lock.
+-- Timestamps use the portable wire representation; receipts are stable JSON.
+CREATE TABLE IF NOT EXISTS kernel_execution_grants (
+  grant_id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  agent_instance_id TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  owner_ref TEXT NOT NULL,
+  state TEXT NOT NULL CHECK (state IN ('active','suspended','revoked')),
+  revision BIGINT NOT NULL CHECK (revision > 0),
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_kernel_execution_grants_scope
+  ON kernel_execution_grants (tenant_id, agent_instance_id, session_id);
+CREATE TABLE IF NOT EXISTS kernel_execution_grant_operations (
+  grant_id TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL,
+  request_digest TEXT NOT NULL,
+  receipt_json TEXT NOT NULL,
+  PRIMARY KEY (grant_id, idempotency_key)
+);

ksadk/kernel/sqlite_store.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""SQLite ``AgentKernelStore``（Phase 1 Task 3 Step 5）。
+"""SQLite ``AgentKernelStore``（Kernel Task 3 Step 5）。
 
 单文件 durable Inbox / Run / ActivationLease 存储：
 - WAL journal + 每次 mutation ``BEGIN IMMEDIATE`` 做跨进程 CAS；
@@ -22,8 +22,6 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-from uuid import uuid4
-
 import aiosqlite
 
 from ksadk.events.session_event import (
@@ -35,15 +33,15 @@ from ksadk.events.session_event import (
     validate_write_guard,
 )
 from ksadk.interaction.contracts import (
-    InteractionRecord,
     InteractionReceipt,
+    InteractionRecord,
     InteractionSubmission,
     is_terminal,
 )
 from ksadk.interaction.ledger import (
     ALREADY_RESOLVED,
-    REVISION_MISMATCH,
     REQUEST_CONFLICT,
+    REVISION_MISMATCH,
     interaction_event,
     request_digest,
     requested_event_payload,
@@ -60,6 +58,7 @@ from ksadk.kernel.contracts import (
     SessionEventEnvelope,
 )
 from ksadk.kernel.errors import InvalidCommandError, StaleFenceError
+from ksadk.kernel.execution_grants_sqlite import EXECUTION_GRANT_SCHEMA, SQLiteExecutionGrantMixin
 from ksadk.kernel.state import (
     InboxState,
     assert_inbox_transition,
@@ -79,7 +78,7 @@ from ksadk.sessions._local_tables import KSADK_EVENTS_TABLE, KSADK_SESSIONS_TABL
 from ksadk.sessions.base import SessionEvent
 from ksadk.sessions.local_service import LocalSessionService
 
-SCHEMA_VERSION = 2
+SCHEMA_VERSION = 3
 
 _SCHEMA = """
 CREATE TABLE IF NOT EXISTS kernel_inbox (
@@ -177,7 +176,7 @@ CREATE TABLE IF NOT EXISTS kernel_interaction_submissions (
 """
 
 
-class SQLiteAgentKernelStore:
+class SQLiteAgentKernelStore(SQLiteExecutionGrantMixin):
     def __init__(
         self,
         db_path: str | Path,
@@ -204,7 +203,7 @@ class SQLiteAgentKernelStore:
         connection = await self._connect()
         async with self._write_lock:
             # CREATE ... IF NOT EXISTS + 整数 user_version，重复启动幂等。
-            await connection.executescript(_SCHEMA)
+            await connection.executescript(_SCHEMA + EXECUTION_GRANT_SCHEMA)
             await connection.execute(f"PRAGMA user_version={SCHEMA_VERSION}")
             await connection.commit()
 
@@ -259,16 +258,20 @@ class SQLiteAgentKernelStore:
         return activation
 
     async def _emit_admission(
-        self, envelope: SessionEventEnvelope, command: AgentControlCommand
+        self, envelope: SessionEventEnvelope, command: AgentControlCommand,
+        *, connection: aiosqlite.Connection | None = None,
     ) -> None:
         # admission 事实的 guard 绑定提交方 permit 引用与 command_id。
-        await self._events.append(
-            envelope,
-            guard=AdmissionWriteGuard(
-                authorization_ref=command.authorization_ref,
-                command_id=command.command_id,
-            ),
+        guard = AdmissionWriteGuard(
+            authorization_ref=command.authorization_ref,
+            command_id=command.command_id,
         )
+        service = getattr(self._events, "session_service", None)
+        if (connection is not None and isinstance(service, LocalSessionService)
+                and service.db_path == self.db_path):
+            await self._append_interaction_event_on(connection, envelope, guard)
+        else:
+            await self._events.append(envelope, guard=guard)
 
     async def _emit_activation(
         self, envelope: SessionEventEnvelope, activation: dict[str, Any], fence: int
@@ -347,6 +350,13 @@ class SQLiteAgentKernelStore:
                         accepted_seq=existing["accepted_seq"],
                     )
 
+                grant_error = await self._sqlite_admission_grant_error(connection, command)
+                if grant_error:
+                    await connection.commit()
+                    return await self.reject_command(
+                        command, status="rejected", code=grant_error, message=grant_error,
+                    )
+
                 depth_row = await self._fetchone(
                     connection,
                     "SELECT COUNT(*) AS depth FROM kernel_inbox "
@@ -406,14 +416,9 @@ class SQLiteAgentKernelStore:
                         command.model_dump_json(),
                     ),
                 )
-                # persist-before-ack：session 事件库与 kernel 库是两个独立
-                # SQLite 文件，无法共享一个事务。诚实取舍是在 kernel 事务
-                # commit 之前追加 accepted 事件：事件写入失败 -> 回滚 Inbox，
-                # 不产生 "persisted-but-untracked" 半状态，客户端可安全重试。
-                # 残余窗口：事件已追加但 kernel commit 崩溃 -> 出现一条孤儿
-                # accepted 事件而无 Inbox 行；该窗口不返回 ack，重试会重新
-                # 走完整路径（seq 单调，可能产生一条重复 accepted 事件），
-                # 不存在已 ack 但未持久化的状态。
+                # Shared local storage appends the event through this same
+                # connection, atomically with Inbox admission. Legacy external
+                # event stores retain the pre-existing persist-before-ack path.
                 await self._emit_admission(
                     control_event(
                         session_id=command.session_id,
@@ -428,6 +433,7 @@ class SQLiteAgentKernelStore:
                         causation_id=str(command.command_id),
                     ),
                     command,
+                    connection=connection,
                 )
                 await connection.commit()
             except BaseException:
@@ -456,6 +462,233 @@ class SQLiteAgentKernelStore:
             command=AgentControlCommand.model_validate_json(row["payload_json"]),
         )
 
+    async def load_by_idempotency(
+        self, session_id: str, idempotency_key: str
+    ) -> InboxMessage | None:
+        connection = await self._connect()
+        row = await self._fetchone(
+            connection,
+            "SELECT message_id FROM kernel_inbox "
+            "WHERE session_id=? AND idempotency_key=?",
+            (session_id, idempotency_key),
+        )
+        return await self.load_message(row["message_id"]) if row is not None else None
+
+    async def reject_command(
+        self,
+        command: AgentControlCommand,
+        *,
+        status: str,
+        code: str,
+        message: str,
+        retryable: bool = False,
+    ) -> AgentControlReceipt:
+        """Persist a redacted admission rejection without creating Inbox work."""
+
+        await self._emit_admission(
+            control_event(
+                session_id=command.session_id,
+                event_type="control.command_rejected",
+                payload={
+                    "command_id": str(command.command_id),
+                    "status": status,
+                    "reason": code,
+                },
+                causation_id=str(command.command_id),
+            ),
+            command,
+        )
+        return self._receipt(
+            command,
+            status,
+            error=ControlError(code=code, message=message, retryable=retryable),
+        )
+
+    async def list_messages(
+        self, agent_instance_id: str, session_id: str | None = None
+    ) -> list[InboxMessage]:
+        connection = await self._connect()
+        sql = "SELECT message_id FROM kernel_inbox WHERE agent_instance_id=?"
+        params: tuple[Any, ...] = (agent_instance_id,)
+        if session_id is not None:
+            sql += " AND session_id=?"
+            params += (session_id,)
+        sql += " ORDER BY accepted_seq"
+        cursor = await connection.execute(sql, params)
+        rows = await cursor.fetchall()
+        await cursor.close()
+        messages = [await self.load_message(row["message_id"]) for row in rows]
+        return [message for message in messages if message is not None]
+
+    async def list_pending(
+        self,
+        agent_instance_id: str,
+        session_id: str | None = None,
+        *,
+        fencing_token: int | None = None,
+    ) -> list[InboxMessage]:
+        """Return FIFO-visible Inbox rows for the current activation.
+
+        ``accepted`` rows are always pending.  When a fence is supplied,
+        ``claimed`` rows are included as well so the same owner can retry and
+        a takeover owner can reclaim work left by an older process.
+        """
+
+        connection = await self._connect()
+        sql = "SELECT message_id FROM kernel_inbox WHERE agent_instance_id=?"
+        params: tuple[Any, ...] = (agent_instance_id,)
+        if session_id is not None:
+            sql += " AND session_id=?"
+            params += (session_id,)
+        if fencing_token is None:
+            sql += " AND status='accepted'"
+        else:
+            sql += " AND status IN ('accepted','claimed')"
+        sql += " ORDER BY accepted_seq"
+        cursor = await connection.execute(sql, params)
+        rows = await cursor.fetchall()
+        await cursor.close()
+        messages = [await self.load_message(row["message_id"]) for row in rows]
+        return [message for message in messages if message is not None]
+
+    async def claim_message(
+        self, message_id: str, fencing_token: int
+    ) -> InboxMessage:
+        """Claim one selected message, idempotently for the same fence."""
+
+        message_id = str(message_id)
+        async with self._write_lock:
+            connection = await self._begin()
+            try:
+                row = await self._fetchone(
+                    connection,
+                    "SELECT * FROM kernel_inbox WHERE message_id=?",
+                    (message_id,),
+                )
+                if row is None:
+                    raise InvalidCommandError(f"unknown message_id {message_id!r}")
+                activation = await self._check_fence(
+                    connection,
+                    row["agent_instance_id"],
+                    row["session_id"],
+                    fencing_token,
+                )
+                await self._sqlite_require_claim_grant(connection, row)
+                if (
+                    row["status"] == InboxState.CLAIMED.value
+                    and row["claimed_fence"] == int(fencing_token)
+                ):
+                    await connection.commit()
+                    message = await self.load_message(message_id)
+                    assert message is not None
+                    return message
+                if row["status"] not in (
+                    InboxState.ACCEPTED.value,
+                    InboxState.CLAIMED.value,
+                ):
+                    raise InvalidCommandError(
+                        f"message {message_id!r} is not claimable at status "
+                        f"{row['status']}"
+                    )
+                if row["status"] == InboxState.ACCEPTED.value:
+                    assert_inbox_transition(
+                        InboxState(row["status"]), InboxState.CLAIMED
+                    )
+                await connection.execute(
+                    "UPDATE kernel_inbox SET status='claimed', claimed_fence=? "
+                    "WHERE message_id=?",
+                    (int(fencing_token), message_id),
+                )
+                await connection.commit()
+            except BaseException:
+                await connection.rollback()
+                raise
+        await self._emit_activation(
+            control_event(
+                session_id=row["session_id"],
+                event_type="control.message_claimed",
+                payload={
+                    "message_id": message_id,
+                    "accepted_seq": int(row["accepted_seq"]),
+                    "fencing_token": int(fencing_token),
+                },
+            ),
+            activation,
+            fencing_token,
+        )
+        message = await self.load_message(message_id)
+        assert message is not None
+        return message
+
+    async def discard_claim(
+        self, message_id: str, *, expected_fence: int
+    ) -> None:
+        """Settle a typed rejection as ``claimed -> discarded``."""
+
+        message_id = str(message_id)
+        async with self._write_lock:
+            connection = await self._begin()
+            try:
+                row = await self._fetchone(
+                    connection,
+                    "SELECT * FROM kernel_inbox WHERE message_id=?",
+                    (message_id,),
+                )
+                if row is None:
+                    raise InvalidCommandError(f"unknown message_id {message_id!r}")
+                activation = await self._check_fence(
+                    connection,
+                    row["agent_instance_id"],
+                    row["session_id"],
+                    expected_fence,
+                )
+                if (
+                    row["status"] != InboxState.CLAIMED.value
+                    or row["claimed_fence"] != int(expected_fence)
+                ):
+                    raise StaleFenceError(
+                        f"message {message_id!r} is not claimed at fence "
+                        f"{expected_fence}"
+                    )
+                assert_inbox_transition(
+                    InboxState(row["status"]), InboxState.DISCARDED
+                )
+                await connection.execute(
+                    "UPDATE kernel_inbox SET status='discarded' WHERE message_id=?",
+                    (message_id,),
+                )
+                await connection.commit()
+            except BaseException:
+                await connection.rollback()
+                raise
+        await self._emit_activation(
+            control_event(
+                session_id=row["session_id"],
+                event_type="control.message_discarded",
+                payload={
+                    "message_id": message_id,
+                    "fencing_token": int(expected_fence),
+                },
+            ),
+            activation,
+            expected_fence,
+        )
+
+    async def inbox_depth(
+        self, agent_instance_id: str, session_id: str | None = None
+    ) -> int:
+        connection = await self._connect()
+        sql = (
+            "SELECT COUNT(*) AS depth FROM kernel_inbox "
+            "WHERE agent_instance_id=? AND status='accepted'"
+        )
+        params: tuple[Any, ...] = (agent_instance_id,)
+        if session_id is not None:
+            sql += " AND session_id=?"
+            params += (session_id,)
+        row = await self._fetchone(connection, sql, params)
+        return int(row["depth"] if row is not None else 0)
+
     async def claim_next(
         self, agent_instance_id: str, session_id: str, fencing_token: int
     ) -> InboxMessage | None:
@@ -490,6 +723,7 @@ class SQLiteAgentKernelStore:
                 if row is None:
                     await connection.commit()
                     return None
+                await self._sqlite_require_claim_grant(connection, row)
                 if row["status"] == InboxState.ACCEPTED.value:
                     assert_inbox_transition(InboxState(row["status"]), InboxState.CLAIMED)
                 await connection.execute(
@@ -557,7 +791,7 @@ class SQLiteAgentKernelStore:
         connection: aiosqlite.Connection,
         agent_instance_id: str,
         session_id: str,
-        guard: ActivationWriteGuard,
+        guard: ActivationWriteGuard | AdmissionWriteGuard,
     ) -> dict[str, Any]:
         row = await self._fetchone(
             connection,
@@ -598,7 +832,10 @@ class SQLiteAgentKernelStore:
             if isinstance(self._events, SessionServiceEventStore)
             else None
         )
-        if not isinstance(service, LocalSessionService) or service.db_path != self.db_path.resolve():
+        if (
+            not isinstance(service, LocalSessionService)
+            or service.db_path != self.db_path.resolve()
+        ):
             raise RuntimeError(
                 "SQLite InteractionLedger requires SessionEventStore backed by the "
                 "same SQLite database"
@@ -1286,6 +1523,32 @@ class SQLiteAgentKernelStore:
                 await connection.rollback()
                 raise
 
+    async def current_lease(
+        self, agent_instance_id: str, session_id: str | None = None
+    ) -> ActivationLease | None:
+        connection = await self._connect()
+        sql = (
+            "SELECT * FROM kernel_activations WHERE agent_instance_id=? "
+            "AND released=0 AND lease_expires_at>?"
+        )
+        params: tuple[Any, ...] = (agent_instance_id, time.time())
+        if session_id is not None:
+            sql += " AND session_id=?"
+            params += (session_id,)
+        sql += " ORDER BY lease_expires_at DESC LIMIT 1"
+        row = await self._fetchone(connection, sql, params)
+        if row is None:
+            return None
+        return ActivationLease(
+            agent_instance_id=row["agent_instance_id"],
+            activation_id=row["activation_id"],
+            fencing_token=int(row["fencing_token"]),
+            lease_expires_at=row["lease_expires_at_iso"],
+            bundle_digest=row["bundle_digest"],
+            runtime_type=row["runtime_type"],
+            capability_digest=row["capability_digest"],
+        )
+
     # ------------------------------------------------------------------ events
 
     async def append_event(
@@ -1359,6 +1622,22 @@ class SQLiteAgentKernelStore:
             metadata=json.loads(row["metadata_json"]),
         )
 
+    async def find_active_run(
+        self, agent_instance_id: str, session_id: str | None = None
+    ) -> RunRecord | None:
+        connection = await self._connect()
+        sql = (
+            "SELECT run_id FROM kernel_runs WHERE agent_instance_id=? "
+            "AND state IN ('running','paused','waiting')"
+        )
+        params: tuple[Any, ...] = (agent_instance_id,)
+        if session_id is not None:
+            sql += " AND session_id=?"
+            params += (session_id,)
+        sql += " ORDER BY created_at LIMIT 1"
+        row = await self._fetchone(connection, sql, params)
+        return await self.load_run(row["run_id"]) if row is not None else None
+
     async def save_run_transition(
         self, run: RunRecord, *, expected_fence: int
     ) -> RunRecord:

ksadk/kernel/state.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""Agent Kernel Inbox/Run 状态机与事务不变量（Phase 1 Task 3）。
+"""Agent Kernel Inbox/Run 状态机与事务不变量（Kernel Task 3）。
 
 Inbox 固定 ``accepted -> claimed -> completed|discarded``；
 Run 固定 ``pending -> running -> paused|waiting|completed|failed|cancelled|interrupted``，
@@ -8,8 +8,7 @@ Run 固定 ``pending -> running -> paused|waiting|completed|failed|cancelled|int
 
 from __future__ import annotations
 
-from enum import StrEnum
-
+from ksadk._str_enum import StrEnum
 from ksadk.kernel.errors import InvalidCommandError