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

ksadk/kernel/execution_grants_sqlite.py

@@ -0,0 +1,209 @@
+"""SQLite grants share BEGIN IMMEDIATE with admission and Inbox claim.
+
+Receipts live in this same database, so a lost acknowledgement is resolved by
+the original mutation key even after another transition or a process restart.
+SessionEvent publication is not the authority for a grant barrier.
+"""
+
+from __future__ import annotations
+
+from ksadk.kernel.contracts import AgentControlCommand
+from ksadk.kernel.errors import InvalidCommandError
+from ksadk.kernel.execution_grants import (
+    ExecutionGrantBarrier,
+    ExecutionGrantBlocked,
+    ExecutionGrantRecord,
+    ExecutionGrantSpec,
+    GrantState,
+    command_grant_error,
+    execution_grant_id,
+    grant_operation_digest,
+    make_grant_barrier,
+    require_grant_scope,
+    transition_grant,
+)
+from ksadk.kernel.store import now_iso
+
+EXECUTION_GRANT_SCHEMA = """
+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 INTEGER 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)
+);
+"""
+
+
+class SQLiteExecutionGrantMixin:
+    async def _sqlite_grant_record(self, connection, grant_id: str) -> ExecutionGrantRecord | None:
+        row = await self._fetchone(
+            connection, "SELECT * FROM kernel_execution_grants WHERE grant_id=?", (grant_id,)
+        )
+        return ExecutionGrantRecord.model_validate(dict(row)) if row is not None else None
+
+    async def ensure_execution_grant(self, spec: ExecutionGrantSpec) -> ExecutionGrantRecord:
+        async with self._write_lock:
+            connection = await self._begin()
+            try:
+                record = await self._sqlite_grant_record(connection, spec.grant_id)
+                if record is not None:
+                    require_grant_scope(record, spec)
+                else:
+                    record = ExecutionGrantRecord(
+                        **spec.model_dump(), created_at=now_iso(), updated_at=now_iso()
+                    )
+                    await connection.execute(
+                        "INSERT INTO kernel_execution_grants (grant_id, tenant_id, "
+                        "agent_instance_id, "
+                        "session_id, owner_ref, state, revision, created_at, updated_at) VALUES "
+                        "(?,?,?,?,?,?,?,?,?)",
+                        tuple(record.model_dump().values()),
+                    )
+                await connection.commit()
+                return record
+            except BaseException:
+                await connection.rollback()
+                raise
+
+    async def _sqlite_grant_barrier(self, connection, record) -> ExecutionGrantBarrier:
+        cursor = await connection.execute(
+            "SELECT message_id FROM kernel_inbox WHERE agent_instance_id=? AND session_id=? "
+            "ORDER BY accepted_seq",
+            (record.agent_instance_id, record.session_id),
+        )
+        rows = await cursor.fetchall()
+        await cursor.close()
+        messages = [await self.load_message(row["message_id"]) for row in rows]
+        cursor = await connection.execute(
+            "SELECT run_id FROM kernel_runs WHERE agent_instance_id=? AND session_id=?",
+            (record.agent_instance_id, record.session_id),
+        )
+        rows = await cursor.fetchall()
+        await cursor.close()
+        runs = [await self.load_run(row["run_id"]) for row in rows]
+        return make_grant_barrier(record, [m for m in messages if m], [r for r in runs if r])
+
+    async def get_execution_grant(self, spec: ExecutionGrantSpec) -> ExecutionGrantBarrier | None:
+        async with self._write_lock:
+            connection = await self._begin()
+            try:
+                record = await self._sqlite_grant_record(connection, spec.grant_id)
+                if record is None:
+                    await connection.commit()
+                    return None
+                require_grant_scope(record, spec)
+                barrier = await self._sqlite_grant_barrier(connection, record)
+                await connection.commit()
+                return barrier
+            except BaseException:
+                await connection.rollback()
+                raise
+
+    async def set_execution_grant_state(
+        self,
+        spec: ExecutionGrantSpec,
+        state: GrantState,
+        *,
+        expected_revision: int,
+        idempotency_key: str,
+    ) -> ExecutionGrantBarrier:
+        if not idempotency_key or not idempotency_key.strip():
+            raise InvalidCommandError("grant mutation requires idempotency_key")
+        digest = grant_operation_digest(spec, state, expected_revision)
+        async with self._write_lock:
+            connection = await self._begin()
+            try:
+                record = await self._sqlite_grant_record(connection, spec.grant_id)
+                if record is None:
+                    raise InvalidCommandError("execution grant not found")
+                require_grant_scope(record, spec)
+                previous = await self._fetchone(
+                    connection,
+                    "SELECT * FROM kernel_execution_grant_operations WHERE grant_id=? AND "
+                    "idempotency_key=?",
+                    (spec.grant_id, idempotency_key),
+                )
+                if previous is not None:
+                    if previous["request_digest"] != digest:
+                        raise InvalidCommandError("execution grant idempotency conflict")
+                    await connection.commit()
+                    return ExecutionGrantBarrier.model_validate_json(previous["receipt_json"])
+                updated = transition_grant(record, state, expected_revision, now_iso())
+                await connection.execute(
+                    "UPDATE kernel_execution_grants SET state=?, revision=?, updated_at=? WHERE "
+                    "grant_id=?",
+                    (updated.state, updated.revision, updated.updated_at, spec.grant_id),
+                )
+                if state == "revoked":
+                    await connection.execute(
+                        "UPDATE kernel_inbox SET status='discarded' WHERE agent_instance_id=? "
+                        "AND session_id=? "
+                        "AND status='accepted' AND json_extract(payload_json, "
+                        "'$.command_type')='enqueue' "
+                        "AND json_extract(payload_json, '$.payload.execution_grant_id')=?",
+                        (spec.agent_instance_id, spec.session_id, spec.grant_id),
+                    )
+                barrier = await self._sqlite_grant_barrier(connection, updated)
+                await connection.execute(
+                    "INSERT INTO kernel_execution_grant_operations "
+                    "(grant_id, idempotency_key, request_digest, receipt_json) VALUES (?,?,?,?)",
+                    (spec.grant_id, idempotency_key, digest, barrier.model_dump_json()),
+                )
+                await connection.commit()
+                return barrier
+            except BaseException:
+                await connection.rollback()
+                raise
+
+    async def _sqlite_admission_grant_error(self, connection, command) -> str | None:
+        grant_id = execution_grant_id(command)
+        if not grant_id:
+            return None
+        return command_grant_error(command, await self._sqlite_grant_record(connection, grant_id))
+
+    async def _sqlite_require_claim_grant(self, connection, row) -> None:
+        command = AgentControlCommand.model_validate_json(row["payload_json"])
+        grant_id = execution_grant_id(command)
+        if not grant_id:
+            return
+        record = await self._sqlite_grant_record(connection, grant_id)
+        error = command_grant_error(command, record)
+        if row["status"] == "claimed" and error in (None, "execution_grant_revoked"):
+            return
+        if error:
+            raise ExecutionGrantBlocked(
+                error.removeprefix("execution_grant_"), message_id=row["message_id"]
+            )
+        if record.state == "suspended":
+            raise ExecutionGrantBlocked("suspended", message_id=row["message_id"])
+        earlier = await self._fetchone(
+            connection,
+            "SELECT 1 FROM kernel_inbox WHERE agent_instance_id=? AND session_id=? "
+            "AND accepted_seq < ? AND status IN ('accepted','claimed') "
+            "AND json_extract(payload_json, '$.command_type')='enqueue' LIMIT 1",
+            (row["agent_instance_id"], row["session_id"], row["accepted_seq"]),
+        )
+        busy = await self._fetchone(
+            connection,
+            "SELECT 1 FROM kernel_runs WHERE agent_instance_id=? AND session_id=? "
+            "AND state IN ('pending','running','paused','waiting') LIMIT 1",
+            (row["agent_instance_id"], row["session_id"]),
+        )
+        if earlier or busy:
+            raise ExecutionGrantBlocked(
+                "queued" if earlier else "busy", message_id=row["message_id"]
+            )

ksadk/kernel/ingress.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""Agent Kernel ingress 收敛层（Phase 1 Task 8）。
+"""Agent Kernel ingress 收敛层（Kernel Task 8）。
 
 把 KsADK 现有五个入口（RunAgent / Responses / AG-UI / A2A / Studio）的
 mutation 统一收敛到 ``AgentKernel.submit``：
@@ -20,6 +20,7 @@ mutation 统一收敛到 ``AgentKernel.submit``：
 kernel 路径下命令的实际执行由 ``AgentWorker``（Task 6/7 交付）认领并驱动
 RuntimeAdapter；ingress 只 submit + 订阅投影，不直接触碰 RuntimeExecutor。
 """
+
 from __future__ import annotations
 
 import hashlib
@@ -94,9 +95,22 @@ def get_agent_kernel() -> Any | None:
 
 
 def kernel_route_active() -> bool:
-    """当前请求是否走 kernel ingress（开关开 且 kernel 已注册）。"""
+    """Whether public compatibility routes may self-admit through the kernel.
+
+    A hosted Runtime accepts AgentControl commands only with a permit issued by
+    Server.  The public ``/v1/responses`` / legacy ``RunAgent`` routes do not
+    carry that permit, so routing them through ``trusted_context`` would create
+    a process-local signature that the hosted verifier must reject.  Keep those
+    authenticated compatibility routes on their established executor path;
+    Server continues to use the dedicated ``/agent-kernel/v1/*`` ingress, which
+    validates the Server-issued permit independently of this selector.
+    """
 
-    return kernel_ingress_enabled() and get_agent_kernel() is not None
+    return (
+        kernel_ingress_enabled()
+        and get_agent_kernel() is not None
+        and authority_mode() != _AUTHORITY_HOSTED
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -207,15 +221,11 @@ def trusted_context(
     # mode the local signature remains unverifiable against Server JWKS, so
     # this does not create a Server-admission bypass.
     if agent_instance_id == "local-agent":
-        agent_instance_id = (
-            os.environ.get("AGENT_INSTANCE_ID", "").strip() or agent_instance_id
-        )
+        agent_instance_id = os.environ.get("AGENT_INSTANCE_ID", "").strip() or agent_instance_id
     if launch_context is not None:
         config = getattr(launch_context, "config", None) or {}
         tenant_id = str(config.get("tenant_id") or tenant_id)
-        agent_instance_id = str(
-            config.get("agent_instance_id") or agent_instance_id
-        )
+        agent_instance_id = str(config.get("agent_instance_id") or agent_instance_id)
     issuer = issuer or _default_issuer()
     permit = issuer.issue(
         tenant_id=tenant_id,
@@ -517,9 +527,7 @@ async def subscribe_projected(
         subscribe_kwargs["should_stop"] = should_stop
     if "timeout" in _params:
         subscribe_kwargs["timeout"] = timeout
-    async for envelope in kernel.subscribe(
-        subscription, permit=trusted.permit, **subscribe_kwargs
-    ):
+    async for envelope in kernel.subscribe(subscription, permit=trusted.permit, **subscribe_kwargs):
         projected = envelope if projector is None else projector(envelope)
         if projected is None:
             continue
@@ -659,7 +667,9 @@ async def bootstrap_agent_kernel_from_env() -> Any | None:
             tenant_id=session_service.tenant_id,
             workspace_id=session_service.workspace_id,
         )
-        store = PostgresAgentKernelStore(pool, event_log, owns_pool=True)
+        store = PostgresAgentKernelStore(
+            pool, event_log, tenant_id=session_service.tenant_id, owns_pool=True
+        )
         # typed RuntimeEvent 写路径走 fenced store：ActivationWriteGuard
         # append 与 activation 行验证同一事务（Task 4 Step 5）。
         events = PostgresFencedSessionEventStore(store)
@@ -733,6 +743,7 @@ def _env_permit_verifier(*, nonce_store: Any = None) -> Any:
     jwks_url = os.environ.get(ENV_JWKS_URL, "").strip()
     if jwks_url:
         from ksadk.kernel.authorization import AgentControlPermitVerifier
+
         source = _remote_jwks_source(jwks_url)
         if _is_hosted():
             # hosted 模式：server JWKS 是唯一信任源，绝不合并本地公钥。
@@ -770,12 +781,21 @@ async def _ensure_shared_log_session(command: Any) -> None:
     if service is None:
         return
     try:
-        if await service.get_session(session_id) is None:
-            await service.create_session(
-                agent_id=str(getattr(command, "agent_instance_id", "") or "runtime"),
-                user_id=str(getattr(command, "tenant_id", "") or "tenant"),
-                session_id=session_id,
-            )
+        from ksadk.conversations.runtime_persistence import ensure_conversation_session
+
+        payload = getattr(command, "payload", {})
+        identity = payload.get("invocation_identity") if isinstance(payload, Mapping) else None
+        agent_id = str(getattr(command, "agent_instance_id", "") or "runtime")
+        existing = await service.get_session_metadata(session_id)
+        if existing is not None and str(existing.agent_id or "").strip():
+            agent_id = str(existing.agent_id)
+        await ensure_conversation_session(
+            agent_id=agent_id,
+            user_id=str(getattr(command, "tenant_id", "") or "tenant"),
+            session_id=session_id,
+            session_service_provider=lambda: service,
+            invocation_identity=identity,
+        )
     except Exception:
         pass
 
@@ -936,9 +956,7 @@ def _build_kernel_router() -> Any:
             )
             # local 仅为开发便利自签，query 的 authorization_ref 必须同 permit
             # 本体一致，避免错误地用 caller 自报值触发恒 fail-closed。
-            query = query.model_copy(
-                update={"authorization_ref": trusted.permit.permit_id}
-            )
+            query = query.model_copy(update={"authorization_ref": trusted.permit.permit_id})
             permit = trusted.permit
         snapshot = await kernel.status(query, permit=permit)
         return JSONResponse(json.loads(snapshot.model_dump_json()))
@@ -968,10 +986,7 @@ def _build_kernel_router() -> Any:
                 content={
                     "error": {
                         "Code": "missing_resource_identity",
-                        "Message": (
-                            "hosted subscription requires tenant_id and "
-                            "agent_instance_id"
-                        ),
+                        "Message": ("hosted subscription requires tenant_id and agent_instance_id"),
                     }
                 },
             )
@@ -1035,9 +1050,7 @@ def _build_kernel_router() -> Any:
                 frame.setdefault("seq", seq)
                 if not isinstance(envelope, dict):
                     frame.setdefault("family", getattr(envelope, "family", None))
-                    frame.setdefault(
-                        "family_version", getattr(envelope, "family_version", None)
-                    )
+                    frame.setdefault("family_version", getattr(envelope, "family_version", None))
                     frame.setdefault("event_type", getattr(envelope, "event_type", None))
                     if getattr(envelope, "run_id", None):
                         frame.setdefault("run_id", envelope.run_id)

ksadk/kernel/mapping.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""command -> RuntimeAdapter 方法映射与 capability 判定（Phase 1 Task 6 Step 5）。
+"""command -> RuntimeAdapter 方法映射与 capability 判定（Kernel Task 6 Step 5）。
 
 映射表是唯一事实来源：enqueue 只在没有 active Run 时执行 start；
 steer/inject 只传给 native adapter method；每条命令产生的

ksadk/kernel/memory_store.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""InMemory ``AgentKernelStore``（Phase 1 Task 3 Step 4）。
+"""InMemory ``AgentKernelStore``（Kernel Task 3 Step 4）。
 
 只用于单进程开发与 conformance 测试，不宣称跨进程 durable。
 以 per-(agent, session) asyncio lock 保证 accept/claim/transition 的原子语义；
@@ -16,15 +16,15 @@ from uuid import uuid4
 
 from ksadk.events.session_event import SessionEventStore
 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,
@@ -41,6 +41,7 @@ from ksadk.kernel.contracts import (
     SessionEventEnvelope,
 )
 from ksadk.kernel.errors import InvalidCommandError, StaleFenceError
+from ksadk.kernel.execution_grants_memory import MemoryExecutionGrantMixin
 from ksadk.kernel.state import (
     InboxState,
     assert_inbox_transition,
@@ -58,7 +59,7 @@ from ksadk.kernel.store import (
 )
 
 
-class InMemoryAgentKernelStore:
+class InMemoryAgentKernelStore(MemoryExecutionGrantMixin):
     def __init__(self, session_event_store: SessionEventStore) -> None:
         self._events = session_event_store
         self._locks: dict[tuple[str, str], asyncio.Lock] = {}
@@ -67,6 +68,8 @@ class InMemoryAgentKernelStore:
         self._accepted_seq: dict[str, int] = {}
         self._activations: dict[tuple[str, str], dict[str, Any]] = {}
         self._runs: dict[str, RunRecord] = {}
+        self._execution_grants = {}
+        self._execution_grant_operations = {}
         # Interaction ledger（Task 5）：(tenant_id, interaction_id) -> row。
         self._interactions: dict[tuple[str, str], dict[str, Any]] = {}
         self._interaction_submissions: dict[tuple[str, str, str], dict[str, Any]] = {}
@@ -91,7 +94,9 @@ class InMemoryAgentKernelStore:
     def _lease_expired(row: dict[str, Any]) -> bool:
         return row["lease_expires_at"] <= time.time()
 
-    def _check_fence(self, agent_instance_id: str, session_id: str, expected_fence: int) -> dict[str, Any]:
+    def _check_fence(
+        self, agent_instance_id: str, session_id: str, expected_fence: int
+    ) -> dict[str, Any]:
         row = self._activation_row(agent_instance_id, session_id)
         if (
             row is None
@@ -204,6 +209,12 @@ class InMemoryAgentKernelStore:
                     accepted_seq=existing["accepted_seq"],
                 )
 
+            grant_error = self._memory_admission_grant_error(command)
+            if grant_error:
+                return await self.reject_command(
+                    command, status="rejected", code=grant_error, message=grant_error,
+                )
+
             depth = sum(
                 1
                 for row in self._messages.values()
@@ -356,7 +367,6 @@ class InMemoryAgentKernelStore:
             elif (
                 fencing_token is not None
                 and row["status"] == InboxState.CLAIMED
-                and row["claimed_fence"] == int(fencing_token)
             ):
                 rows.append(row)
         rows.sort(key=lambda row: row["accepted_seq"])
@@ -371,19 +381,21 @@ class InMemoryAgentKernelStore:
             raise InvalidCommandError(f"unknown message_id {message_id!r}")
         async with self._lock(row["agent_instance_id"], row["session_id"]):
             fresh = self._messages[str(message_id)]
+            activation = self._check_fence(
+                fresh["agent_instance_id"], fresh["session_id"], fencing_token
+            )
+            self._memory_require_claim_grant(fresh)
             if (
                 fresh["status"] == InboxState.CLAIMED
                 and fresh["claimed_fence"] == int(fencing_token)
             ):
                 return self._to_message(fresh)
-            activation = self._check_fence(
-                fresh["agent_instance_id"], fresh["session_id"], fencing_token
-            )
-            if fresh["status"] != InboxState.ACCEPTED:
+            if fresh["status"] not in (InboxState.ACCEPTED, InboxState.CLAIMED):
                 raise InvalidCommandError(
                     f"message {message_id!r} is not claimable at status {fresh['status']}"
                 )
-            assert_inbox_transition(InboxState(fresh["status"]), InboxState.CLAIMED)
+            if fresh["status"] == InboxState.ACCEPTED:
+                assert_inbox_transition(InboxState(fresh["status"]), InboxState.CLAIMED)
             fresh["status"] = InboxState.CLAIMED
             fresh["claimed_fence"] = int(fencing_token)
             await self._emit(
@@ -513,6 +525,7 @@ class InMemoryAgentKernelStore:
             if not candidates:
                 return None
             row = candidates[0]
+            self._memory_require_claim_grant(row)
             if row["status"] == InboxState.ACCEPTED:
                 assert_inbox_transition(InboxState(row["status"]), InboxState.CLAIMED)
             row["status"] = InboxState.CLAIMED

ksadk/kernel/postgres_store.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""PostgreSQL ``AgentKernelStore``（Phase 1 Task 4）。
+"""PostgreSQL ``AgentKernelStore``（Kernel Task 4）。
 
 预发多写者 durable Inbox / Run / ActivationLease 存储：
 - schema 见 ``ksadk/kernel/sql/001_agent_kernel.sql``（BIGINT fencing_token、
@@ -31,15 +31,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,
@@ -56,6 +56,8 @@ from ksadk.kernel.contracts import (
     SessionEventEnvelope,
 )
 from ksadk.kernel.errors import InvalidCommandError, StaleFenceError
+from ksadk.kernel.execution_grants import execution_grant_id
+from ksadk.kernel.execution_grants_postgres import PostgresExecutionGrantMixin
 from ksadk.kernel.state import (
     InboxState,
     RunState,
@@ -310,7 +312,7 @@ class PostgresNonceStore:
                 )
 
 
-class PostgresAgentKernelStore:
+class PostgresAgentKernelStore(PostgresExecutionGrantMixin):
     def __init__(
         self,
         pool: Any,
@@ -345,6 +347,8 @@ class PostgresAgentKernelStore:
                 "DELETE FROM kernel_inbox; DELETE FROM kernel_runs;"
                 " DELETE FROM kernel_activations; DELETE FROM kernel_accepted_seq;"
                 " DELETE FROM kernel_interactions; DELETE FROM kernel_interaction_submissions;"
+                " DELETE FROM kernel_execution_grant_operations;"
+                " DELETE FROM kernel_execution_grants;"
                 " DELETE FROM ksadk_events WHERE namespace = 'default';"
             )
 
@@ -433,6 +437,8 @@ class PostgresAgentKernelStore:
             raise InvalidCommandError("queue_limit must be positive")
         async with self._connection() as connection:
             async with connection.transaction():
+                if execution_grant_id(command):
+                    await self._postgres_lock_command_grant(connection, command)
                 existing = await connection.fetchrow(
                     "SELECT message_id, accepted_seq, request_digest FROM kernel_inbox"
                     " WHERE tenant_id=$1 AND session_id=$2 AND idempotency_key=$3",
@@ -474,6 +480,19 @@ class PostgresAgentKernelStore:
                         accepted_seq=int(existing["accepted_seq"]),
                     )
 
+                grant_error = await self._postgres_admission_grant_error(connection, command)
+                if grant_error:
+                    await self._append_admission(connection, command, control_event(
+                        session_id=command.session_id, event_type="control.command_rejected",
+                        payload={
+                            "command_id": str(command.command_id), "status": "rejected",
+                            "reason": grant_error,
+                        },
+                    ))
+                    return self._receipt(command, "rejected", error=ControlError(
+                        code=grant_error, message=grant_error, retryable=False,
+                    ))
+
                 depth = await connection.fetchval(
                     "SELECT COUNT(*) FROM kernel_inbox WHERE tenant_id=$1"
                     " AND agent_instance_id=$2 AND session_id=$3 AND status='accepted'",
@@ -686,23 +705,29 @@ class PostgresAgentKernelStore:
         message_id = str(message_id)
         async with self._connection() as connection:
             async with connection.transaction():
+                # Lock grant before Inbox, matching the revocation lock order.
+                candidate = await connection.fetchrow(
+                    "SELECT payload FROM kernel_inbox WHERE message_id=$1::uuid", message_id,
+                )
+                if candidate is None:
+                    raise InvalidCommandError(f"unknown message_id {message_id!r}")
+                command = AgentControlCommand.model_validate_json(candidate["payload"])
+                grant = await self._postgres_lock_command_grant(connection, command)
                 row = await connection.fetchrow(
                     "SELECT * FROM kernel_inbox WHERE message_id=$1::uuid FOR UPDATE",
                     message_id,
                 )
                 if row is None:
                     raise InvalidCommandError(f"unknown message_id {message_id!r}")
+                activation = await self._assert_fence(
+                    connection, row["agent_instance_id"], row["session_id"], fencing_token,
+                )
+                await self._postgres_require_claim_grant(connection, row, command, grant)
                 if (
                     row["status"] == InboxState.CLAIMED.value
                     and int(row["claimed_fence"]) == int(fencing_token)
                 ):
-                    return self._row_to_message(row)  # type: ignore[return-value]
-                activation = await self._assert_fence(
-                    connection,
-                    row["agent_instance_id"],
-                    row["session_id"],
-                    fencing_token,
-                )
+                    return self._row_to_message(row)
                 if row["status"] not in (
                     InboxState.ACCEPTED.value,
                     InboxState.CLAIMED.value,
@@ -876,7 +901,7 @@ class PostgresAgentKernelStore:
                     connection, agent_instance_id, session_id, fencing_token
                 )
                 row = await connection.fetchrow(
-                    "SELECT message_id, status FROM kernel_inbox"
+                    "SELECT * FROM kernel_inbox"
                     " WHERE agent_instance_id=$1 AND session_id=$2"
                     " AND (status='accepted' OR (status='claimed' AND claimed_fence <> $3))"
                     " ORDER BY accepted_seq"
@@ -888,27 +913,32 @@ class PostgresAgentKernelStore:
                 )
                 if row is None:
                     return None
-                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=$1"
-                    " WHERE message_id=$2::uuid",
-                    int(fencing_token),
-                    str(row["message_id"]),
-                )
-                await self._append_activation_fact(
-                    connection,
-                    control_event(
-                        session_id=session_id,
-                        event_type="control.message_claimed",
-                        payload={
-                            "message_id": str(row["message_id"]),
-                            "fencing_token": int(fencing_token),
-                        },
-                    ),
-                    activation,
-                    fencing_token,
-                )
+                command = AgentControlCommand.model_validate_json(row["payload"])
+                grant_qualified_path = execution_grant_id(command) is not None
+                if not grant_qualified_path:
+                    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=$1"
+                        " WHERE message_id=$2::uuid",
+                        int(fencing_token),
+                        str(row["message_id"]),
+                    )
+                    await self._append_activation_fact(
+                        connection,
+                        control_event(
+                            session_id=session_id,
+                            event_type="control.message_claimed",
+                            payload={
+                                "message_id": str(row["message_id"]),
+                                "fencing_token": int(fencing_token),
+                            },
+                        ),
+                        activation,
+                        fencing_token,
+                    )
+        if grant_qualified_path:
+            return await self.claim_message(str(row["message_id"]), fencing_token)
         return await self.load_message(row["message_id"])
 
     async def complete_claim(self, message_id: str, *, expected_fence: int) -> None: