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

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,105 +78,9 @@ 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 = """
-CREATE TABLE IF NOT EXISTS kernel_inbox (
-  message_id TEXT PRIMARY KEY,
-  agent_instance_id TEXT NOT NULL,
-  session_id TEXT NOT NULL,
-  idempotency_key TEXT NOT NULL,
-  request_digest TEXT NOT NULL,
-  accepted_seq INTEGER NOT NULL,
-  status TEXT NOT NULL CHECK (status IN ('accepted','claimed','completed','discarded')),
-  claimed_fence INTEGER,
-  payload_json TEXT NOT NULL,
-  UNIQUE(session_id, idempotency_key)
-);
-CREATE INDEX IF NOT EXISTS idx_kernel_inbox_claim
-  ON kernel_inbox (agent_instance_id, session_id, status, accepted_seq);
-CREATE INDEX IF NOT EXISTS idx_kernel_inbox_idempotency
-  ON kernel_inbox (session_id, idempotency_key);
-
-CREATE TABLE IF NOT EXISTS kernel_runs (
-  run_id TEXT PRIMARY KEY,
-  agent_instance_id TEXT NOT NULL,
-  session_id TEXT NOT NULL,
-  state TEXT NOT NULL CHECK (state IN (
-    'pending','running','paused','waiting','completed','failed','cancelled','interrupted'
-  )),
-  activation_fence INTEGER NOT NULL DEFAULT 0,
-  created_at TEXT NOT NULL,
-  updated_at TEXT NOT NULL,
-  metadata_json TEXT NOT NULL DEFAULT '{}'
-);
-CREATE INDEX IF NOT EXISTS idx_kernel_runs_session_state
-  ON kernel_runs (session_id, state);
-
-CREATE TABLE IF NOT EXISTS kernel_activations (
-  agent_instance_id TEXT NOT NULL,
-  session_id TEXT NOT NULL,
-  activation_id TEXT NOT NULL,
-  fencing_token INTEGER NOT NULL,
-  lease_expires_at REAL NOT NULL,
-  lease_expires_at_iso TEXT NOT NULL,
-  released INTEGER NOT NULL DEFAULT 0,
-  runtime_type TEXT NOT NULL DEFAULT 'ksadk',
-  bundle_digest TEXT NOT NULL DEFAULT '',
-  capability_digest TEXT NOT NULL DEFAULT '',
-  PRIMARY KEY (agent_instance_id, session_id)
-);
-CREATE INDEX IF NOT EXISTS idx_kernel_activations_expiry
-  ON kernel_activations (lease_expires_at);
-
-CREATE TABLE IF NOT EXISTS kernel_accepted_seq (
-  session_id TEXT PRIMARY KEY,
-  last_seq INTEGER NOT NULL DEFAULT 0
-);
-
-CREATE TABLE IF NOT EXISTS kernel_interactions (
-  interaction_id TEXT NOT NULL,
-  tenant_id TEXT NOT NULL,
-  agent_instance_id TEXT NOT NULL,
-  session_id TEXT NOT NULL,
-  run_id TEXT NOT NULL,
-  kind TEXT NOT NULL CHECK (kind IN ('approval','structured_input','plan_review','custom')),
-  request_schema_json TEXT NOT NULL,
-  presentation_json TEXT,
-  revision INTEGER NOT NULL,
-  status TEXT NOT NULL CHECK (status IN (
-    'pending','resolving','resolved','cancelled','expired'
-  )),
-  created_at TEXT NOT NULL,
-  expires_at TEXT,
-  provider_id TEXT NOT NULL DEFAULT '',
-  native_target_json TEXT,
-  continuation_json TEXT,
-  request_digest TEXT NOT NULL,
-  response_json TEXT,
-  outcome TEXT,
-  actor TEXT,
-  event_id TEXT,
-  accepted_seq INTEGER,
-  fencing_token INTEGER,
-  updated_at TEXT,
-  PRIMARY KEY (tenant_id, interaction_id)
-);
-CREATE INDEX IF NOT EXISTS idx_kernel_interactions_pending
-  ON kernel_interactions (tenant_id, session_id, status);
-
-CREATE TABLE IF NOT EXISTS kernel_interaction_submissions (
-  tenant_id TEXT NOT NULL,
-  interaction_id TEXT NOT NULL,
-  idempotency_key TEXT NOT NULL,
-  submission_digest TEXT NOT NULL,
-  receipt_json TEXT NOT NULL,
-  PRIMARY KEY (tenant_id, interaction_id, idempotency_key)
-);
-"""
-
+from ksadk.kernel.sqlite_schema import SCHEMA_VERSION, _SCHEMA
 
-class SQLiteAgentKernelStore:
+class SQLiteAgentKernelStore(SQLiteExecutionGrantMixin):
     def __init__(
         self,
         db_path: str | Path,
@@ -204,9 +107,15 @@ class SQLiteAgentKernelStore:
         connection = await self._connect()
         async with self._write_lock:
             # CREATE ... IF NOT EXISTS + 整数 user_version，重复启动幂等。
-            await connection.executescript(_SCHEMA)
-            await connection.execute(f"PRAGMA user_version={SCHEMA_VERSION}")
-            await connection.commit()
+            await connection.executescript(_SCHEMA + EXECUTION_GRANT_SCHEMA)
+            await connection.execute("BEGIN IMMEDIATE")
+            try:
+                await self._migrate_execution_grants(connection)
+                await connection.execute(f"PRAGMA user_version={SCHEMA_VERSION}")
+                await connection.commit()
+            except BaseException:
+                await connection.rollback()
+                raise
 
     async def close(self) -> None:
         if self._connection is not None:
@@ -222,10 +131,12 @@ class SQLiteAgentKernelStore:
 
     @staticmethod
     async def _fetchone(connection: aiosqlite.Connection, sql: str, params: tuple) -> Any:
-        cursor = await connection.execute(sql, params)
-        row = await cursor.fetchone()
-        await cursor.close()
-        return row
+        # Consume the cursor in one SQLite worker call. An unfinished SELECT on
+        # this shared connection can otherwise overlap another coroutine's
+        # BEGIN IMMEDIATE and fail with SQLITE_BUSY_SNAPSHOT after an event-log
+        # writer commits. No authorization/transaction retry is involved.
+        rows = await connection.execute_fetchall(sql, params)
+        return rows[0] if rows else None
 
     @staticmethod
     def _activation_row(row: aiosqlite.Row | None) -> dict[str, Any] | None:
@@ -234,7 +145,10 @@ class SQLiteAgentKernelStore:
         return dict(row)
 
     async def _check_fence(
-        self, connection: aiosqlite.Connection, agent_instance_id: str, session_id: str,
+        self,
+        connection: aiosqlite.Connection,
+        agent_instance_id: str,
+        session_id: str,
         expected_fence: int,
     ) -> dict[str, Any]:
         row = await self._fetchone(
@@ -259,16 +173,26 @@ 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
@@ -333,9 +257,7 @@ class SQLiteAgentKernelStore:
                             "rejected",
                             error=ControlError(
                                 code="idempotency_conflict",
-                                message=(
-                                    "idempotency key reused with a different request digest"
-                                ),
+                                message=("idempotency key reused with a different request digest"),
                                 retryable=False,
                             ),
                         )
@@ -347,6 +269,16 @@ 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 +338,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,14 +355,13 @@ class SQLiteAgentKernelStore:
                         causation_id=str(command.command_id),
                     ),
                     command,
+                    connection=connection,
                 )
                 await connection.commit()
             except BaseException:
                 await connection.rollback()
                 raise
-        return self._receipt(
-            command, "accepted", message_id=message_id, accepted_seq=accepted_seq
-        )
+        return self._receipt(command, "accepted", message_id=message_id, accepted_seq=accepted_seq)
 
     async def load_message(self, message_id: str) -> InboxMessage | None:
         connection = await self._connect()
@@ -456,17 +382,228 @@ 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"
+        rows = await connection.execute_fetchall(sql, params)
+        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"
+        rows = await connection.execute_fetchall(sql, params)
+        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
+                await self._sqlite_require_claim_grant(connection, row)
+                if row["status"] not in (
+                    InboxState.ACCEPTED.value,
+                    InboxState.CLAIMED.value,
+                ):
+                    raise InvalidCommandError(
+                        f"message {message_id!r} is not claimable at status {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 {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:
         async with self._write_lock:
             connection = await self._begin()
             try:
-                activation = self._activation_row(await self._fetchone(
-                    connection,
-                    "SELECT * FROM kernel_activations WHERE agent_instance_id=? AND session_id=?",
-                    (agent_instance_id, session_id),
-                ))
+                activation = self._activation_row(
+                    await self._fetchone(
+                        connection,
+                        "SELECT * FROM kernel_activations "
+                        "WHERE agent_instance_id=? AND session_id=?",
+                        (agent_instance_id, session_id),
+                    )
+                )
                 if (
                     activation is None
                     or activation["lease_expires_at"] <= time.time()
@@ -490,6 +627,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(
@@ -524,9 +662,8 @@ class SQLiteAgentKernelStore:
                 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)
+                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 {expected_fence}"
@@ -557,7 +694,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 +735,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"
@@ -731,9 +871,7 @@ class SQLiteAgentKernelStore:
 
         presentation = None
         if row["presentation_json"]:
-            presentation = InteractionPresentation.model_validate_json(
-                row["presentation_json"]
-            )
+            presentation = InteractionPresentation.model_validate_json(row["presentation_json"])
         return InteractionRecord(
             interaction_id=row["interaction_id"],
             tenant_id=row["tenant_id"],
@@ -749,14 +887,10 @@ class SQLiteAgentKernelStore:
             presentation=presentation,
             provider_id=row["provider_id"] or "",
             native_target=(
-                json.loads(row["native_target_json"])
-                if row["native_target_json"]
-                else None
+                json.loads(row["native_target_json"]) if row["native_target_json"] else None
             ),
             continuation_metadata=(
-                json.loads(row["continuation_json"])
-                if row["continuation_json"]
-                else None
+                json.loads(row["continuation_json"]) if row["continuation_json"] else None
             ),
         )
 
@@ -769,11 +903,7 @@ class SQLiteAgentKernelStore:
             record.run_id,
             record.kind,
             json.dumps(record.request_schema, ensure_ascii=False),
-            (
-                record.presentation.model_dump_json()
-                if record.presentation is not None
-                else None
-            ),
+            (record.presentation.model_dump_json() if record.presentation is not None else None),
             record.revision,
             record.status,
             record.created_at,
@@ -869,17 +999,11 @@ class SQLiteAgentKernelStore:
                             submission.idempotency_key,
                         ),
                     )
-                    if (
-                        existing_sub is not None
-                        and existing_sub["submission_digest"] == sub_digest
-                    ):
+                    if existing_sub is not None and existing_sub["submission_digest"] == sub_digest:
                         await connection.commit()
-                        return InteractionReceipt.model_validate_json(
-                            existing_sub["receipt_json"]
-                        )
+                        return InteractionReceipt.model_validate_json(existing_sub["receipt_json"])
                     raise InvalidCommandError(
-                        "interaction already reached terminal status"
-                        f" {current.status!r}",
+                        f"interaction already reached terminal status {current.status!r}",
                         details={
                             "reason": ALREADY_RESOLVED,
                             "interaction_id": current.interaction_id,
@@ -967,13 +1091,9 @@ class SQLiteAgentKernelStore:
         async with self._write_lock:
             connection = await self._begin()
             try:
-                row = await self._interaction_row_for_guard(
-                    connection, interaction_id, guard
-                )
+                row = await self._interaction_row_for_guard(connection, interaction_id, guard)
                 if row is None:
-                    raise InvalidCommandError(
-                        f"unknown interaction_id {interaction_id!r}"
-                    )
+                    raise InvalidCommandError(f"unknown interaction_id {interaction_id!r}")
                 await self._check_interaction_guard(
                     connection, row["agent_instance_id"], row["session_id"], guard
                 )
@@ -981,8 +1101,7 @@ class SQLiteAgentKernelStore:
                 assert current is not None
                 if is_terminal(current.status):
                     raise InvalidCommandError(
-                        f"interaction already reached terminal status"
-                        f" {current.status!r}",
+                        f"interaction already reached terminal status {current.status!r}",
                         details={
                             "reason": ALREADY_RESOLVED,
                             "interaction_id": current.interaction_id,
@@ -1002,9 +1121,7 @@ class SQLiteAgentKernelStore:
                     update={"status": status, "revision": current.revision + 1}
                 )
                 event_type = (
-                    "interaction.cancelled"
-                    if status == "cancelled"
-                    else "interaction.expired"
+                    "interaction.cancelled" if status == "cancelled" else "interaction.expired"
                 )
                 stored = await self._append_interaction_event_on(
                     connection,
@@ -1099,12 +1216,10 @@ class SQLiteAgentKernelStore:
                 (interaction_id, tenant_id, agent_instance_id, session_id, run_id),
             )
             return self._row_to_record(row)
-        cursor = await connection.execute(
+        rows = await connection.execute_fetchall(
             "SELECT * FROM kernel_interactions WHERE interaction_id=? LIMIT 2",
             (interaction_id,),
         )
-        rows = await cursor.fetchall()
-        await cursor.close()
         if len(rows) > 1:
             raise InvalidCommandError(
                 f"interaction_id {interaction_id!r} is ambiguous without trusted scope",
@@ -1113,17 +1228,23 @@ class SQLiteAgentKernelStore:
         return self._row_to_record(rows[0]) if rows else None
 
     async def get_terminal_receipt(
-        self, interaction_id: str, *, tenant_id: str, agent_instance_id: str,
-        session_id: str, run_id: str,
+        self,
+        interaction_id: str,
+        *,
+        tenant_id: str,
+        agent_instance_id: str,
+        session_id: str,
+        run_id: str,
     ) -> InteractionReceipt | None:
         """Read the committed outcome inside a complete trusted scope.
 
         Resolved alone does not mean approved. Pending/resolving records never
         yield an authorization receipt; callers must still match the request.
         """
-        if not all(isinstance(value, str) and value for value in (
-            interaction_id, tenant_id, agent_instance_id, session_id, run_id
-        )):
+        if not all(
+            isinstance(value, str) and value
+            for value in (interaction_id, tenant_id, agent_instance_id, session_id, run_id)
+        ):
             raise InvalidCommandError("interaction receipt requires a complete trusted scope")
         row = await self._fetchone(
             await self._connect(),
@@ -1134,8 +1255,11 @@ class SQLiteAgentKernelStore:
         if row is None or not is_terminal(row["status"]):
             return None
         return InteractionReceipt(
-            interaction_id=row["interaction_id"], revision=int(row["revision"]),
-            status=row["status"], outcome=row["outcome"], event_id=row["event_id"],
+            interaction_id=row["interaction_id"],
+            revision=int(row["revision"]),
+            status=row["status"],
+            outcome=row["outcome"],
+            event_id=row["event_id"],
             accepted_seq=row["accepted_seq"],
         )
 
@@ -1143,13 +1267,11 @@ class SQLiteAgentKernelStore:
         self, tenant_id: str, session_id: str
     ) -> list[InteractionRecord]:
         connection = await self._connect()
-        cursor = await connection.execute(
+        rows = await connection.execute_fetchall(
             "SELECT * FROM kernel_interactions WHERE tenant_id=? AND session_id=?"
             " AND status='pending' ORDER BY created_at",
             (tenant_id, session_id),
         )
-        rows = await cursor.fetchall()
-        await cursor.close()
         records = [self._row_to_record(row) for row in rows]
         return [r for r in records if r is not None]
 
@@ -1286,6 +1408,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(
@@ -1315,23 +1463,24 @@ class SQLiteAgentKernelStore:
     ) -> dict[str, Any]:
         connection = await self._connect()
         if agent_instance_id is not None:
-            row = self._activation_row(await self._fetchone(
-                connection,
-                "SELECT * FROM kernel_activations WHERE agent_instance_id=? AND session_id=?",
-                (agent_instance_id, session_id),
-            ))
+            row = self._activation_row(
+                await self._fetchone(
+                    connection,
+                    "SELECT * FROM kernel_activations WHERE agent_instance_id=? AND session_id=?",
+                    (agent_instance_id, session_id),
+                )
+            )
             if row is None:
                 raise StaleFenceError(
                     "no active activation lease",
                     details={"agent_instance_id": agent_instance_id, "session_id": session_id},
                 )
             return row
-        cursor = await connection.execute(
+        records = await connection.execute_fetchall(
             "SELECT * FROM kernel_activations WHERE session_id=? AND released=0",
             (session_id,),
         )
-        rows = [self._activation_row(row) for row in await cursor.fetchall()]
-        await cursor.close()
+        rows = [self._activation_row(row) for row in records]
         rows = [row for row in rows if row is not None]
         if len(rows) != 1:
             raise StaleFenceError(
@@ -1342,6 +1491,19 @@ class SQLiteAgentKernelStore:
 
     # -------------------------------------------------------------------- runs
 
+    async def find_command_run(
+        self, agent_instance_id: str, session_id: str, command_id: str
+    ) -> RunRecord | None:
+        connection = await self._connect()
+        rows = await connection.execute_fetchall(
+            "SELECT run_id FROM kernel_runs WHERE agent_instance_id=? AND session_id=? "
+            "AND json_extract(metadata_json, '$.command_id')=? LIMIT 2",
+            (agent_instance_id, session_id, command_id),
+        )
+        if len(rows) > 1:
+            raise InvalidCommandError("ambiguous runs for the same command")
+        return await self.load_run(rows[0]["run_id"]) if rows else None
+
     async def load_run(self, run_id: str) -> RunRecord | None:
         row = await self._fetchone(
             await self._connect(), "SELECT * FROM kernel_runs WHERE run_id=?", (run_id,)
@@ -1359,9 +1521,52 @@ class SQLiteAgentKernelStore:
             metadata=json.loads(row["metadata_json"]),
         )
 
-    async def save_run_transition(
-        self, run: RunRecord, *, expected_fence: int
-    ) -> RunRecord:
+    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_runtime_checkpoint(
+        self, run_id: str, checkpoint: dict, *, agent_instance_id: str,
+        session_id: str, guard: ActivationWriteGuard,
+    ) -> None:
+        from ksadk.kernel.runtime_checkpoint import checkpoint_copy, require_checkpoint_owner
+
+        checkpoint = checkpoint_copy(checkpoint)
+        async with self._write_lock:
+            connection = await self._begin()
+            try:
+                activation = await self._check_fence(
+                    connection, agent_instance_id, session_id, guard.fencing_token,
+                )
+                if activation["activation_id"] != guard.activation_id:
+                    raise StaleFenceError("runtime checkpoint activation mismatch")
+                run = await self.load_run(run_id)
+                require_checkpoint_owner(
+                    run, agent_instance_id=agent_instance_id, session_id=session_id,
+                )
+                metadata = dict(run.metadata, runtime_checkpoint=checkpoint)
+                await connection.execute(
+                    "UPDATE kernel_runs SET metadata_json=?, updated_at=? WHERE run_id=?",
+                    (json.dumps(metadata, ensure_ascii=False), now_iso(), run_id),
+                )
+                await connection.commit()
+            except BaseException:
+                await connection.rollback()
+                raise
+
+    async def save_run_transition(self, run: RunRecord, *, expected_fence: int) -> RunRecord:
         async with self._write_lock:
             connection = await self._begin()
             try:
@@ -1369,6 +1574,11 @@ class SQLiteAgentKernelStore:
                     connection, run.agent_instance_id, run.session_id, expected_fence
                 )
                 existing = await self.load_run(run.run_id)
+                from ksadk.kernel.runtime_checkpoint import preserve_runtime_checkpoint
+
+                run = run.model_copy(update={"metadata": preserve_runtime_checkpoint(
+                    run.metadata, existing.metadata if existing else None,
+                )})
                 assert_run_transition(existing.state if existing else None, run.state)
                 if is_active_run(run.state):
                     cursor = await connection.execute(