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

ksadk/kernel/teams_execution_context.py

@@ -0,0 +1,408 @@
+"""Durable, host-owned Teams context references beside the Kernel inbox.
+
+Nothing in this registry grants authority by itself. Only an authenticated Host
+loader may supply records, and the runtime checks the live grant on each use.
+The PostgreSQL adapter shares the Kernel pool/schema/tenant; SQLite shares its
+connection and writer lock. Replacing the database changes its incarnation.
+"""
+
+from __future__ import annotations
+
+import json
+from contextlib import asynccontextmanager
+from typing import Any, Protocol
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from ksadk.kernel.contracts import AgentControlCommand
+from ksadk.kernel.execution_grants import ExecutionGrantSpec
+from ksadk.kernel.store import command_digest
+from ksadk.plugins.teams.cloud_contracts import Digest, Identifier, TeamsExecutionRef, digest
+
+
+class ContextConflict(ValueError):
+    """A durable reference was reused with different authority or payload."""
+
+
+class StoreIdentityMismatch(ValueError):
+    """The original durable inbox cannot be proved; never interpret as missing."""
+
+
+class PreparedTeamsContext(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid", revalidate_instances="always")
+
+    context_ref: Identifier
+    context_digest: Digest
+    policy_ref: Identifier
+    policy_digest: Digest
+    owner_subject: Identifier
+    ref: TeamsExecutionRef
+    grant: ExecutionGrantSpec
+    command: AgentControlCommand
+    # JSON facts from the trusted loader, not executable tools or caller policy.
+    context: dict[str, Any] = Field(default_factory=dict)
+    material_manifest_ref: Identifier | None = None
+    material_manifest_digest: Digest | None = None
+
+    @model_validator(mode="after")
+    def exact_scope(self):
+        ref, command, grant = self.ref, self.command, self.grant
+        if (self.material_manifest_ref is None) != (self.material_manifest_digest is None):
+            raise ContextConflict("material manifest reference and digest are required together")
+        if command.command_type != "enqueue" or any(
+            (
+                str(command.command_id) != ref.commandId,
+                command.session_id != ref.sessionId,
+                command.idempotency_key != ref.idempotencyKey,
+                grant.agent_instance_id != command.agent_instance_id,
+                grant.session_id != command.session_id,
+                grant.tenant_id != command.tenant_id,
+                grant.attempt_epoch != ref.attemptEpoch,
+                command.payload.get("execution_grant_id") != grant.grant_id,
+                command.payload.get("execution_grant_attempt_epoch") != ref.attemptEpoch,
+                command.payload.get("execution_policy_ref") != self.policy_ref,
+                command.payload.get("teams_context_ref") != self.context_ref,
+            )
+        ):
+            raise ContextConflict("prepared command/context/grant scope mismatch")
+        if ref.target.kind == "cloud_agent" and (
+            ref.target.agentInstanceId != command.agent_instance_id
+        ):
+            raise ContextConflict("prepared target instance mismatch")
+        if self.context_digest != digest(self.context):
+            raise ContextConflict("prepared context digest mismatch")
+        return self
+
+    @property
+    def payload_digest(self) -> str:
+        return "sha256:" + command_digest(self.command)
+
+    @property
+    def session_owner_digest(self) -> str:
+        return digest(
+            {
+                "tenant": self.grant.tenant_id,
+                "owner": self.owner_subject,
+                "authority": self.ref.authorityId,
+                "group": self.ref.groupId,
+                "teamRun": self.ref.teamRunId,
+                "member": self.ref.runMemberId,
+                "binding": self.ref.bindingRef,
+                "instance": self.grant.agent_instance_id,
+            }
+        )
+
+
+class TeamsExecutionContextRegistry(Protocol):
+    """Shared adapters must persist in the *same* store as the original inbox."""
+
+    durable: bool
+    shared_across_hosts: bool
+    kernel_store: Any
+
+    async def initialize(self) -> str: ...
+    async def incarnation(self) -> str: ...
+    async def owns_session(self, session_id: str) -> bool: ...
+    async def put(self, context: PreparedTeamsContext, *, expected_incarnation: str) -> None: ...
+    async def get(
+        self, context_ref: str, *, expected_incarnation: str
+    ) -> PreparedTeamsContext | None: ...
+    async def put_callback(self, context_ref, permit, *, expected_incarnation: str) -> None: ...
+    async def get_callback(self, context_ref, revision, *, expected_incarnation: str): ...
+
+
+_SCHEMA = (
+    "CREATE TABLE IF NOT EXISTS teams_host_extensions (namespace TEXT NOT NULL, "
+    "name TEXT NOT NULL, identity TEXT NOT NULL, PRIMARY KEY(namespace,name))",
+    "CREATE TABLE IF NOT EXISTS teams_host_callback_permits ("
+    "namespace TEXT NOT NULL, context_ref TEXT NOT NULL, grant_revision INTEGER NOT NULL, "
+    "body TEXT NOT NULL, PRIMARY KEY(namespace, context_ref, grant_revision))",
+    "CREATE TABLE IF NOT EXISTS teams_host_store_identity ("
+    "namespace TEXT PRIMARY KEY, incarnation TEXT NOT NULL)",
+    "CREATE TABLE IF NOT EXISTS teams_host_session_owners ("
+    "namespace TEXT NOT NULL, session_id TEXT NOT NULL, owner_digest TEXT NOT NULL, "
+    "PRIMARY KEY(namespace, session_id))",
+    "CREATE TABLE IF NOT EXISTS teams_host_native_nonces ("
+    "namespace TEXT NOT NULL, nonce TEXT NOT NULL, command_id TEXT NOT NULL, "
+    "idempotency_key TEXT NOT NULL, PRIMARY KEY(namespace, nonce))",
+    "CREATE TABLE IF NOT EXISTS teams_host_contexts ("
+    "namespace TEXT NOT NULL, context_ref TEXT NOT NULL, session_id TEXT NOT NULL, "
+    "command_id TEXT NOT NULL, idempotency_key TEXT NOT NULL, policy_ref TEXT NOT NULL, "
+    "body TEXT NOT NULL, PRIMARY KEY(namespace, context_ref), "
+    "UNIQUE(namespace, session_id, command_id), "
+    "UNIQUE(namespace, session_id, idempotency_key), UNIQUE(namespace, policy_ref))",
+)
+
+
+class _Registry:
+    durable = True
+    shared_across_hosts = False
+
+    async def initialize(self) -> str:
+        async with self._transaction() as db:
+            # Fail if pointed at a standalone/new uninitialized metadata DB.
+            await db.execute("SELECT 1 FROM kernel_inbox LIMIT 1")
+            for statement in _SCHEMA:
+                await db.execute(statement)
+            await db.execute(
+                "INSERT INTO teams_host_store_identity(namespace, incarnation) VALUES (?, ?) "
+                "ON CONFLICT(namespace) DO NOTHING",
+                (self.namespace, str(uuid4())),
+            )
+            return await self._identity(db)
+
+    async def _identity(self, db, expected=None):
+        row = await db.one(
+            "SELECT incarnation FROM teams_host_store_identity WHERE namespace=?",
+            (self.namespace,),
+        )
+        if row is None or (expected is not None and row["incarnation"] != expected):
+            raise StoreIdentityMismatch("original Kernel store identity mismatch")
+        return str(row["incarnation"])
+
+    async def incarnation(self) -> str:
+        async with self._transaction() as db:
+            return await self._identity(db)
+
+    async def extension_identity(self, name, *, expected_incarnation):
+        async with self._transaction() as db:
+            await self._identity(db, expected_incarnation)
+            row = await db.one(
+                "SELECT identity FROM teams_host_extensions WHERE namespace=? AND name=?",
+                (self.namespace, name),
+            )
+            return row["identity"] if row else None
+
+    async def bind_extension_identity(self, name, identity, *, expected_incarnation):
+        async with self._transaction() as db:
+            await self._identity(db, expected_incarnation)
+            await db.execute(
+                "INSERT INTO teams_host_extensions(namespace,name,identity) VALUES(?,?,?) "
+                "ON CONFLICT DO NOTHING",
+                (self.namespace, name, identity),
+            )
+            row = await db.one(
+                "SELECT identity FROM teams_host_extensions WHERE namespace=? AND name=?",
+                (self.namespace, name),
+            )
+            if row is None or row["identity"] != identity:
+                raise StoreIdentityMismatch("original Host extension identity changed")
+
+    async def register(self, nonce: str, command_id: str, idempotency_key: str) -> bool:
+        """Durable native-permit nonce storage in the original Kernel database."""
+        async with self._transaction() as db:
+            await self._identity(db)
+            await db.execute(
+                "INSERT INTO teams_host_native_nonces(namespace,nonce,command_id,idempotency_key) "
+                "VALUES(?,?,?,?) ON CONFLICT DO NOTHING",
+                (self.namespace, nonce, command_id, idempotency_key),
+            )
+            row = await db.one(
+                "SELECT command_id,idempotency_key FROM teams_host_native_nonces "
+                "WHERE namespace=? AND nonce=?",
+                (self.namespace, nonce),
+            )
+            return row is not None and (row["command_id"], row["idempotency_key"]) == (
+                command_id,
+                idempotency_key,
+            )
+
+    async def owns_session(self, session_id: str) -> bool:
+        """Ingress fence: reserved Teams sessions cannot bypass the Teams gate."""
+        async with self._transaction() as db:
+            await self._identity(db)
+            row = await db.one(
+                "SELECT 1 FROM teams_host_session_owners WHERE namespace=? AND session_id=?",
+                (self.namespace, session_id),
+            )
+            return row is not None
+
+    async def put(self, context: PreparedTeamsContext, *, expected_incarnation: str) -> None:
+        # Revalidate and serialize immediately: nested dicts in a frozen model
+        # are not immutable and must not be retained as an authority cache.
+        context = PreparedTeamsContext.model_validate_json(context.model_dump_json())
+        body = json.dumps(context.model_dump(mode="json"), sort_keys=True, separators=(",", ":"))
+        async with self._transaction() as db:
+            await self._identity(db, expected_incarnation)
+            await db.execute(
+                "INSERT INTO teams_host_session_owners(namespace,session_id,owner_digest) "
+                "VALUES (?,?,?) ON CONFLICT(namespace,session_id) DO NOTHING",
+                (self.namespace, context.ref.sessionId, context.session_owner_digest),
+            )
+            owner = await db.one(
+                "SELECT owner_digest FROM teams_host_session_owners "
+                "WHERE namespace=? AND session_id=?",
+                (self.namespace, context.ref.sessionId),
+            )
+            if owner["owner_digest"] != context.session_owner_digest:
+                raise ContextConflict("session is reserved for another trusted scope")
+            await db.execute(
+                "INSERT INTO teams_host_contexts(namespace,context_ref,session_id,command_id,"
+                "idempotency_key,policy_ref,body) VALUES (?,?,?,?,?,?,?) ON CONFLICT DO NOTHING",
+                (
+                    self.namespace,
+                    context.context_ref,
+                    context.ref.sessionId,
+                    context.ref.commandId,
+                    context.ref.idempotencyKey,
+                    context.policy_ref,
+                    body,
+                ),
+            )
+            row = await db.one(
+                "SELECT body FROM teams_host_contexts WHERE namespace=? AND context_ref=?",
+                (self.namespace, context.context_ref),
+            )
+            if row is None or row["body"] != body:
+                raise ContextConflict("prepared execution reference conflicts with durable context")
+
+    async def get(
+        self, context_ref: str, *, expected_incarnation: str
+    ) -> PreparedTeamsContext | None:
+        async with self._transaction() as db:
+            await self._identity(db, expected_incarnation)
+            row = await db.one(
+                "SELECT body FROM teams_host_contexts WHERE namespace=? AND context_ref=?",
+                (self.namespace, context_ref),
+            )
+            return PreparedTeamsContext.model_validate_json(row["body"]) if row else None
+
+    async def put_callback(self, context_ref, permit, *, expected_incarnation):
+        """Persist an independently verified, short callback transport credential.
+
+        This never changes the immutable context or establishes a grant clock.
+        The composition root verifies all claims before writing and every use.
+        Separate revision slots prevent a delayed old response replacing the
+        active revision's callback authority.
+        """
+        from ksadk.plugins.teams.cloud_permits import TeamsCallbackPermit, _time
+
+        permit = TeamsCallbackPermit.model_validate(permit)
+        async with self._transaction() as db:
+            await self._identity(db, expected_incarnation)
+            context = await db.one(
+                "SELECT 1 FROM teams_host_contexts WHERE namespace=? AND context_ref=?",
+                (self.namespace, context_ref),
+            )
+            if context is None:
+                raise ContextConflict("callback requires an original prepared context")
+            args = (self.namespace, context_ref, permit.grantRevision)
+            old = await db.one(
+                "SELECT body FROM teams_host_callback_permits "
+                "WHERE namespace=? AND context_ref=? AND grant_revision=?",
+                args,
+            )
+            if old and _time(
+                TeamsCallbackPermit.model_validate_json(old["body"]).expiresAt
+            ) >= _time(permit.expiresAt):
+                return
+            await db.execute(
+                "INSERT INTO teams_host_callback_permits"
+                "(namespace,context_ref,grant_revision,body) "
+                "VALUES(?,?,?,?) ON CONFLICT(namespace,context_ref,grant_revision) "
+                "DO UPDATE SET body=excluded.body",
+                args + (permit.model_dump_json(),),
+            )
+
+    async def get_callback(self, context_ref, revision, *, expected_incarnation):
+        from ksadk.plugins.teams.cloud_permits import TeamsCallbackPermit
+
+        async with self._transaction() as db:
+            await self._identity(db, expected_incarnation)
+            row = await db.one(
+                "SELECT body FROM teams_host_callback_permits "
+                "WHERE namespace=? AND context_ref=? AND grant_revision=?",
+                (self.namespace, context_ref, revision),
+            )
+            return TeamsCallbackPermit.model_validate_json(row["body"]) if row else None
+
+
+class _SQLiteConnection:
+    def __init__(self, connection):
+        self.connection = connection
+
+    async def execute(self, sql, args=()):
+        cursor = await self.connection.execute(sql, args)
+        await cursor.close()
+
+    async def one(self, sql, args=()):
+        cursor = await self.connection.execute(sql, args)
+        try:
+            return await cursor.fetchone()
+        finally:
+            await cursor.close()
+
+
+class SQLiteTeamsExecutionContextRegistry(_Registry):
+    """Single-host adapter; shares the Kernel connection and write transaction."""
+
+    def __init__(self, kernel_store):
+        from ksadk.kernel.sqlite_store import SQLiteAgentKernelStore
+
+        if not isinstance(kernel_store, SQLiteAgentKernelStore):
+            raise TypeError("a SQLite Kernel store is required")
+        self.kernel_store = kernel_store
+        self.namespace = "default"
+        self._inode = None
+
+    @asynccontextmanager
+    async def _transaction(self):
+        store = self.kernel_store
+        async with store._write_lock:
+            connection = await store._connect()
+            info = store.db_path.stat()
+            identity = (info.st_dev, info.st_ino)
+            if self._inode is not None and self._inode != identity:
+                raise StoreIdentityMismatch("Kernel database file was replaced")
+            self._inode = identity
+            await connection.execute("BEGIN IMMEDIATE")
+            try:
+                yield _SQLiteConnection(connection)
+                await connection.commit()
+            except BaseException:
+                await connection.rollback()
+                raise
+
+
+class _PostgresConnection:
+    def __init__(self, connection):
+        self.connection = connection
+
+    @staticmethod
+    def sql(sql):
+        parts = sql.split("?")
+        return "".join(
+            part + (f"${i + 1}" if i < len(parts) - 1 else "") for i, part in enumerate(parts)
+        )
+
+    async def execute(self, sql, args=()):
+        return await self.connection.execute(self.sql(sql), *args)
+
+    async def one(self, sql, args=()):
+        return await self.connection.fetchrow(self.sql(sql), *args)
+
+
+class PostgresTeamsExecutionContextRegistry(_Registry):
+    """Shared-host adapter using the actual Kernel asyncpg pool and tenant."""
+
+    shared_across_hosts = True
+
+    def __init__(self, kernel_store):
+        from ksadk.kernel.postgres_store import PostgresAgentKernelStore
+
+        if not isinstance(kernel_store, PostgresAgentKernelStore):
+            raise TypeError("a PostgreSQL Kernel store is required")
+        self.kernel_store = kernel_store
+        self.namespace = kernel_store.tenant_id
+
+    @asynccontextmanager
+    async def _transaction(self):
+        async with self.kernel_store._connection() as connection:
+            async with connection.transaction():
+                # Serialize initial DDL and owner/context insert across pods.
+                await connection.execute(
+                    "SELECT pg_advisory_xact_lock(hashtextextended($1, 0))",
+                    "teams-host-registry:" + self.namespace,
+                )
+                yield _PostgresConnection(connection)

ksadk/kernel/teams_host_http.py

@@ -0,0 +1,237 @@
+"""Authenticated Teams HTTP ports layered on the canonical AgentControl ingress.
+
+The injected resolver selects only a preconfigured Host, never an endpoint from
+request data. Every Host method verifies its own signed, operation-scoped permit;
+loading a context or resolving a Host is not execution authorization.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from fastapi import APIRouter
+from fastapi.encoders import jsonable_encoder
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, ConfigDict, Field
+
+from ksadk.kernel.contracts import AgentControlCommand
+from ksadk.kernel.execution_grants import ExecutionGrantBlocked
+from ksadk.kernel.teams_execution_context import ContextConflict, StoreIdentityMismatch
+from ksadk.plugins.teams.cloud_permits import BindingProbePermit, PermitError, TeamsExecutionPermit
+from ksadk.plugins.teams.effect_contracts import EffectsRequest as EffectsRequest
+
+TEAMS_HOST_BASE_PATH = "/agent-kernel/teams-host/v1"
+
+
+class HostRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    contextRef: str = Field(min_length=1)
+    expectedIncarnation: str = Field(min_length=1)
+    permit: TeamsExecutionPermit
+
+    def arguments(self):
+        return dict(
+            context_ref=self.contextRef,
+            expected_incarnation=self.expectedIncarnation,
+            permit=self.permit,
+        )
+
+
+class DescribeRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    permit: BindingProbePermit
+
+
+class LookupRequest(HostRequest):
+    commandId: str
+    idempotencyKey: str
+    payloadDigest: str
+
+
+class ControlLookupRequest(HostRequest):
+    command: AgentControlCommand
+
+
+class GetGrantRequest(HostRequest):
+    renewalId: str | None = None
+
+
+class SetGrantRequest(HostRequest):
+    state: Literal["active", "suspended", "revoked"]
+    expectedRevision: int = Field(ge=1)
+    controlId: str | None = None
+    renewalId: str | None = None
+    expiresAt: str | None = None
+
+
+class SetAdmissionRequest(HostRequest):
+    admissionAllowed: bool = Field(strict=True)
+    expectedAdmissionRevision: int = Field(ge=1)
+    controlId: str = Field(min_length=1)
+
+
+class ObserveRequest(HostRequest):
+    afterSeq: int = Field(default=0, ge=0)
+    limit: int = Field(default=200, ge=1, le=200)
+    snapshotUpperSeq: int | None = Field(default=None, ge=0)
+
+
+def host_error(error: Exception) -> JSONResponse:
+    if isinstance(error, StoreIdentityMismatch):
+        status, code = 409, "store_identity_mismatch"
+    elif isinstance(error, (PermitError, ExecutionGrantBlocked)):
+        status, code = 403, "teams_authorization_rejected"
+    elif isinstance(error, ContextConflict):
+        status, code = 409, "teams_context_conflict"
+    else:
+        status, code = 503, "teams_host_unavailable"
+    # Never expose callback URL, credential, SQL or context contents.
+    return JSONResponse({"error": {"Code": code, "Message": code}}, status_code=status)
+
+
+def create_teams_host_router(resolve_host):
+    """resolve_host(*, context_ref, permit) -> an actual KernelTeamsExecutionHost.
+
+    Probe selection uses a signed binding reference. Execution selection uses a
+    durable or Server-loaded context reference; the Host then fences every scope.
+    Internal network/service authentication should additionally wrap this router.
+    """
+    router = APIRouter(prefix=TEAMS_HOST_BASE_PATH)
+
+    async def invoke(body, operation, **extra):
+        try:
+            host = await resolve_host(context_ref=body.contextRef, permit=body.permit)
+            result = await getattr(host, operation)(**body.arguments(), **extra)
+            return JSONResponse(jsonable_encoder(result))
+        except (ValueError, ExecutionGrantBlocked) as error:
+            return host_error(error)
+
+    @router.post("/DescribeBinding")
+    async def describe(body: DescribeRequest):
+        try:
+            host = await resolve_host(context_ref=None, permit=body.permit)
+            return JSONResponse(jsonable_encoder(await host.describe_binding(permit=body.permit)))
+        except (ValueError, ExecutionGrantBlocked) as error:
+            return host_error(error)
+
+    @router.post("/PrepareExecution")
+    async def prepare(body: HostRequest):
+        return await invoke(body, "prepare_execution")
+
+    @router.post("/EnsureSession")
+    async def ensure(body: HostRequest):
+        return await invoke(body, "ensure_session")
+
+    @router.post("/LookupExecution")
+    async def lookup(body: LookupRequest):
+        return await invoke(
+            body,
+            "lookup_execution",
+            command_id=body.commandId,
+            idempotency_key=body.idempotencyKey,
+            payload_digest=body.payloadDigest,
+        )
+
+    @router.post("/GetExecutionEffects")
+    async def effects(body: EffectsRequest):
+        return await invoke(body, "get_execution_effects", after=body.after, limit=body.limit)
+
+    @router.post("/GetExecutionResult")
+    async def result(body: HostRequest):
+        return await invoke(body, "get_execution_result")
+
+    @router.post("/LookupControlExecution")
+    async def lookup_control(body: ControlLookupRequest):
+        return await invoke(body, "lookup_control", command=body.command)
+
+    @router.post("/GetExecutionGrant")
+    async def get_grant(body: GetGrantRequest):
+        return await invoke(body, "get_execution_grant", renewal_id=body.renewalId)
+
+    @router.post("/SetExecutionGrant")
+    async def set_grant(body: SetGrantRequest):
+        if body.renewalId is not None:
+            try:
+                if body.controlId is not None or body.state != "active" or body.expiresAt is None:
+                    raise ContextConflict("invalid grant renewal")
+                host = await resolve_host(context_ref=body.contextRef, permit=body.permit)
+                # Time authority comes from the authenticated Server loader, not
+                # a node's wall clock or a timestamp in this request body.
+                if host.renewal_loader is None:
+                    raise ContextConflict("trusted renewal operation loader unavailable")
+                window = await host.renewal_loader(body.contextRef, body.renewalId)
+                if window.expires_at != body.expiresAt:
+                    raise ContextConflict("renewal differs from trusted Server grant window")
+                value = await host.renew_execution_grant(
+                    **body.arguments(),
+                    expected_revision=body.expectedRevision,
+                    renewal_id=body.renewalId,
+                    trusted_window=window,
+                )
+                return JSONResponse(jsonable_encoder(value))
+            except (ValueError, ExecutionGrantBlocked) as error:
+                return host_error(error)
+        if body.controlId is None or body.expiresAt is not None:
+            return host_error(ContextConflict("invalid grant mutation"))
+        return await invoke(
+            body,
+            "set_execution_grant",
+            state=body.state,
+            expected_revision=body.expectedRevision,
+            control_id=body.controlId,
+        )
+
+    @router.post("/SetExecutionAdmission")
+    async def set_admission(body: SetAdmissionRequest):
+        return await invoke(
+            body,
+            "set_execution_admission",
+            allowed=body.admissionAllowed,
+            expected_revision=body.expectedAdmissionRevision,
+            control_id=body.controlId,
+        )
+
+    @router.post("/ObserveExecution")
+    async def observe(body: ObserveRequest):
+        return await invoke(
+            body,
+            "observe_execution",
+            after_seq=body.afterSeq,
+            limit=body.limit,
+            snapshot_upper_seq=body.snapshotUpperSeq,
+        )
+
+    return router
+
+
+class TeamsNativeIngressGate:
+    """Require dual permits for Teams commands, including native endpoint calls."""
+
+    def __init__(self, resolve_host, owns_session):
+        self.resolve_host, self.owns_session = resolve_host, owns_session
+
+    async def __call__(self, *, command, teams: Any, kernel, native_permit):
+        is_teams = bool(command.payload.get("teams_context_ref")) or await self.owns_session(
+            command.session_id
+        )
+        if teams is None:
+            if is_teams:
+                raise PermitError("Teams execution requires its own signed authorization")
+            return
+        body = HostRequest.model_validate(teams)
+        host = await self.resolve_host(context_ref=body.contextRef, permit=body.permit)
+        if host.kernel is not kernel:
+            raise ContextConflict("Teams Host must own the native ingress Kernel")
+        await host.validate_native_authorization(
+            native_permit,
+            context_ref=body.contextRef,
+            expected_incarnation=body.expectedIncarnation,
+        )
+        if command.command_type == "enqueue":
+            if command.payload.get("teams_context_ref") != body.contextRef:
+                raise ContextConflict("native command context mismatch")
+            await host.validate_enqueue(
+                command, expected_incarnation=body.expectedIncarnation, permit=body.permit
+            )
+        else:
+            await host.validate_native_control(command, **body.arguments())