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

ksadk/events/adapters/langgraph.py

@@ -50,6 +50,7 @@ from ksadk.events.adapters._langgraph_support import (
 )
 from ksadk.events.canonical import (
     ApprovalRequest,
+    StructuredInputRequest,
     ContinuationCreated,
     ErrorInfo,
     InteractionRequested,
@@ -446,6 +447,10 @@ class LangGraphEventAdapter:
     ) -> tuple[RuntimeEvent, ...]:
         payload, metadata = _message_data(params.get("data"))
         node = _required_string(metadata.get("langgraph_node"), "messages metadata.langgraph_node")
+        if isinstance(payload, ToolMessage):
+            # LangGraph 1.2.0 also echoes tool outcomes on the messages lane.
+            # The tools lane owns their canonical result and error identity.
+            return ()
         if isinstance(payload, AIMessage):
             return _map_whole_message(
                 payload=payload,
@@ -628,6 +633,9 @@ class LangGraphEventAdapter:
         interaction_events = self._interaction_events_from_interrupts(
             context=context, frame=frame, source=source, env=env, interrupts=interrupts
         )
+        # Associate the companion pause with the pending interaction so Kernel
+        # preserves WAITING instead of publishing a terminal interruption.
+        interaction_id = interaction_events[0].interaction_id if interaction_events else None
         if context.checkpoint_ref is None:
             return (
                 *interaction_events,
@@ -642,6 +650,7 @@ class LangGraphEventAdapter:
                     ),
                     status="interrupted",
                     reason=reason,
+                    interaction_id=interaction_id,
                 ),
             )
 
@@ -697,6 +706,7 @@ class LangGraphEventAdapter:
                 ),
                 status="interrupted",
                 reason=reason,
+                interaction_id=interaction_id,
                 continuation_id=continuation_id,
             ),
         )
@@ -730,6 +740,10 @@ class LangGraphEventAdapter:
                 if isinstance(detail_value, (dict, list, str, int, float, bool, type(None)))
                 else None
             )
+            is_input = isinstance(detail_json, dict) and detail_json.get("kind") == "structured_input"
+            request = (StructuredInputRequest(
+                prompt=detail_json.get("prompt"), schema=detail_json.get("schema", {}),
+            ) if is_input else ApprovalRequest(call_id=intr_id or None, kind="tool", detail=detail_json))
             events.append(
                 InteractionRequested(
                     **env(
@@ -741,12 +755,8 @@ class LangGraphEventAdapter:
                         source,
                     ),
                     interaction_id=interaction_id,
-                    interaction_kind="approval",
-                    request=ApprovalRequest(
-                        call_id=intr_id or None,
-                        kind="tool",
-                        detail=detail_json,
-                    ),
+                    interaction_kind="structured_input" if is_input else "approval",
+                    request=request,
                 )
             )
         return tuple(events)

ksadk/events/canonical.py

@@ -263,6 +263,11 @@ class UsageReported(EventEnvelope):
     total_tokens: JsonInteger = Field(ge=0)
     cached_tokens: JsonInteger = Field(default=0, ge=0)
     reasoning_tokens: JsonInteger = Field(default=0, ge=0)
+    #: 计量语义（长任务方案 §19.2 usage_mode）：``delta`` 单次调用的增量，
+    #: 消费者累加；``cumulative`` provider 已给出的累计值，消费者覆盖；
+    #: ``snapshot`` 定期快照，消费者覆盖。默认 ``delta`` 使旧事件/消费者
+    #: 保持「逐次累加」语义，不回退既有行为。
+    mode: Literal["delta", "cumulative", "snapshot"] = Field(default="delta")
 
 
 RuntimeEvent: TypeAlias = Annotated[

ksadk/events/canonical_store.py

@@ -10,6 +10,7 @@ enforce the canonical idempotency domain before a session cursor is allocated.
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import hashlib
 import json
 import uuid
@@ -20,6 +21,8 @@ from typing import TYPE_CHECKING, Any
 from ksadk.events.canonical import RuntimeEvent, dump_runtime_event, parse_runtime_event
 from ksadk.kernel.contracts import ActivationWriteGuard, SessionEventEnvelope
 from ksadk.sessions.base import SessionEvent, SessionEventSeqBinding
+from ksadk.sessions.db_budget import DatabaseOperationDeadline, session_db_budget
+from ksadk.sessions.resilience import is_session_backend_failure
 
 if TYPE_CHECKING:
     from ksadk.events.session_event import SessionEventStore
@@ -112,6 +115,8 @@ def session_event_to_runtime_event(event: SessionEvent) -> RuntimeEvent | None:
             raise ValueError("runtime family SessionEvent is missing runtime_event content")
         if payload.get("seq") != event.seq_id:
             raise ValueError("canonical RuntimeEvent seq does not match physical seq")
+        if payload.get("event_type") != event.event_type:
+            raise ValueError("canonical RuntimeEvent event type does not match envelope")
         return parse_runtime_event(payload)
     if not metadata.get(_CANONICAL_RUNTIME_MARKER):
         return None
@@ -212,8 +217,32 @@ class RuntimeEventStore:
             raise ValueError("typed append requires a session_id bound at construction")
         if not isinstance(guard, ActivationWriteGuard):
             raise TypeError("RuntimeEventStore only accepts ActivationWriteGuard")
+        deadline = DatabaseOperationDeadline(session_db_budget())
         envelope = runtime_event_envelope(self._typed_session_id, event)
-        persisted = await self._event_store.append(envelope, guard=guard)
+        try:
+            persisted = await self._event_store.append(envelope, guard=guard)
+        except Exception as error:
+            # A lost commit acknowledgement is resolved by the stable event
+            # identity.  Never re-append: that would repeat a guarded write
+            # after a possible fence change.  Domain/fence errors remain errors.
+            if not is_session_backend_failure(error):
+                raise
+            lookup = getattr(self._event_store, "get_by_id", None)
+            if not callable(lookup):
+                raise
+            try:
+                persisted = await deadline.run(
+                    lookup(self._typed_session_id, envelope.event_id)
+                )
+            except Exception:
+                raise error
+            if persisted is None:
+                raise error
+            if persisted.session_id != envelope.session_id or persisted.family != "runtime":
+                raise ValueError("committed runtime event identity mismatch")
+            confirmed = parse_runtime_event(dict(persisted.payload) | {"seq": persisted.seq})
+            self._assert_same_fact(confirmed, event)
+            return confirmed
         return parse_runtime_event(dict(persisted.payload) | {"seq": persisted.seq})
 
     async def append_one(self, session_id: str, event: RuntimeEvent) -> RuntimeEvent:
@@ -223,12 +252,26 @@ class RuntimeEventStore:
     async def persist_one(self, session_id: str, event: RuntimeEvent) -> tuple[RuntimeEvent, bool]:
         """Persist before publication and return whether this call created the fact."""
 
+        budget = getattr(self._service, "db_budget", None) or session_db_budget()
+        deadline = DatabaseOperationDeadline(budget)
+        return await deadline.run(self._persist_one(session_id, event))
+
+    async def _event_by_id_for_write(self, session_id: str, event_id: str) -> RuntimeEvent | None:
+        lookup = getattr(self._service, "get_event_by_id_for_write", None)
+        if self._event_store is None and callable(lookup):
+            self._require_storage_capabilities()
+            stored = await lookup(session_id, canonical_storage_id(session_id, event_id))
+            return session_event_to_runtime_event(stored) if stored is not None else None
+        return await self.event_by_id(session_id, event_id)
+
+    async def _persist_one(self, session_id: str, event: RuntimeEvent) -> tuple[RuntimeEvent, bool]:
+
         if getattr(event, "schema_version", None) != 2:
             raise ValueError("canonical RuntimeEventStore accepts schema_version=2 only")
         if not session_id.strip():
             raise ValueError("session_id must be nonempty")
         self._require_storage_capabilities()
-        existing = await self.event_by_id(session_id, event.event_id)
+        existing = await self._event_by_id_for_write(session_id, event.event_id)
         if existing is not None:
             self._assert_same_fact(existing, event)
             return existing, False
@@ -239,7 +282,7 @@ class RuntimeEventStore:
             # The deterministic physical id turns concurrent appends into an
             # insert-winner/insert-loser race on durable backends.  Re-read the
             # winner and only absorb the error when it is the same fact.
-            existing = await self.event_by_id(session_id, event.event_id)
+            existing = await self._event_by_id_for_write(session_id, event.event_id)
             if existing is None:
                 raise
             self._assert_same_fact(existing, event)
@@ -325,11 +368,27 @@ class RuntimeEventStore:
         return events[:limit]
 
     async def event_by_id(self, session_id: str, event_id: str) -> RuntimeEvent | None:
-        if self._service is not None:
+        # Typed envelopes use a UUID event identity before the physical row
+        # key is allocated. The legacy carrier key cannot find those rows,
+        # even when the typed store happens to expose its session service.
+        if self._event_store is None and self._service is not None:
             self._require_storage_capabilities()
             storage_id = canonical_storage_id(session_id, event_id)
             stored = await self._service.get_event_by_id(session_id, storage_id)
             return session_event_to_runtime_event(stored) if stored is not None else None
+        lookup = getattr(self._event_store, "get_by_id", None)
+        if callable(lookup):
+            envelope = await lookup(session_id, runtime_event_envelope_id(session_id, event_id))
+            if envelope is None:
+                return None
+            if envelope.session_id != session_id:
+                raise ValueError("canonical event lookup returned another session")
+            if envelope.family != "runtime" or envelope.family_version != 2:
+                raise ValueError("canonical event lookup returned another event family")
+            event = parse_runtime_event(dict(envelope.payload) | {"seq": envelope.seq})
+            if event.event_id != event_id:
+                raise ValueError("canonical event lookup returned another event identity")
+            return event
         for event in await self.list(session_id):
             if event.event_id == event_id:
                 return event
@@ -380,6 +439,21 @@ class RuntimeEventStore:
             events = events[-limit:]
         return events
 
+    async def latest_seq_by_sessions(self, session_ids: list[str]) -> dict[str, int]:
+        """Read canonical watermarks in one backend query when available."""
+
+        if not session_ids:
+            return {}
+        bulk_reader = getattr(self._service, "latest_event_seq_by_sessions", None)
+        if callable(bulk_reader):
+            return await bulk_reader(list(session_ids))
+        result: dict[str, int] = {}
+        for session_id in session_ids:
+            latest = await self.list(session_id, limit=1)
+            if latest:
+                result[session_id] = latest[-1].seq
+        return result
+
     async def list_run_ids(self, session_id: str) -> list[str]:
         """Distinct run ids in session order of first appearance."""
 
@@ -396,6 +470,22 @@ class RuntimeEventStore:
         poll_interval: float = 0.25,
         timeout: float = 5 * 60,
     ) -> AsyncIterator[RuntimeEvent]:
+        if self._event_store is not None and self._service is None:
+            # The typed view may be backed by a fenced SessionEventStore rather
+            # than a BaseSessionService.  In that mode ``_service`` is
+            # intentionally None, so consume the store's envelope subscription
+            # instead of reaching for the legacy ``get_events`` API.
+            async with contextlib.aclosing(
+                self._subscribe_typed(
+                    session_id,
+                    after_seq=after_seq,
+                    poll_interval=poll_interval,
+                    timeout=timeout,
+                )
+            ) as stream:
+                async for event in stream:
+                    yield event
+            return
         cursor = int(after_seq or 0)
         deadline = asyncio.get_running_loop().time() + timeout
         while True:
@@ -419,6 +509,22 @@ class RuntimeEventStore:
         poll_interval: float = 0.25,
         timeout: float = 5 * 60,
     ) -> AsyncIterator[RuntimeEvent]:
+        if self._event_store is not None and self._service is None:
+            async with contextlib.aclosing(
+                self._subscribe_typed(
+                    session_id,
+                    after_seq=after_seq,
+                    poll_interval=poll_interval,
+                    timeout=timeout,
+                )
+            ) as stream:
+                async for event in stream:
+                    if event.run_id != run_id:
+                        continue
+                    yield event
+                    if event.event_type in _TERMINAL_EVENT_TYPES:
+                        return
+            return
         cursor = int(after_seq or 0)
         deadline = asyncio.get_running_loop().time() + timeout
         while True:
@@ -435,6 +541,96 @@ class RuntimeEventStore:
                 return
             await asyncio.sleep(poll_interval)
 
+    async def _subscribe_typed(
+        self,
+        session_id: str,
+        *,
+        after_seq: int,
+        poll_interval: float,
+        timeout: float,
+    ) -> AsyncIterator[RuntimeEvent]:
+        """Bridge a generic envelope subscription into canonical RuntimeEvents.
+
+        The typed backend owns replay-to-live ordering; this bridge reads the
+        committed prefix first and then continues from its last physical
+        cursor.  ``poll_interval`` remains part of the public API for parity
+        with the service-backed path; the typed backend controls its cadence.
+        """
+
+        if self._event_store is None:  # pragma: no cover - guarded by callers
+            return
+        from ksadk.events.session_event import envelope_to_session_event
+
+        cursor = int(after_seq)
+        deadline = asyncio.get_running_loop().time() + timeout
+
+        def runtime_event_from_envelope(envelope: Any) -> RuntimeEvent | None:
+            row = envelope_to_session_event(envelope)
+            # ``envelope_to_session_event`` prepares a write carrier and
+            # therefore leaves its transient binding at seq=0.  The
+            # envelope stream is post-commit, so copy its physical cursor
+            # before validating the runtime payload.
+            row.seq_id = int(envelope.seq)
+            row.seq_binding = None
+            return session_event_to_runtime_event(row)
+
+        # A timeout bounds waiting for live events, while already-committed
+        # replay rows remain observable even when timeout=0.  Read pages before
+        # opening the live iterator, then resume from the last physical cursor
+        # so rows committed during the handoff are not duplicated or dropped.
+        while True:
+            envelopes = await self._event_store.read(session_id, cursor, 1000)
+            if not envelopes:
+                break
+            previous_cursor = cursor
+            envelopes.sort(key=lambda envelope: int(envelope.seq))
+            for envelope in envelopes:
+                sequence = int(envelope.seq)
+                if sequence <= cursor:
+                    continue
+                cursor = sequence
+                runtime_event = runtime_event_from_envelope(envelope)
+                if runtime_event is not None:
+                    yield runtime_event
+            if len(envelopes) < 1000:
+                break
+            if cursor == previous_cursor:
+                # A broken backend must not make the bridge spin forever on a
+                # page that contains only duplicate/out-of-order rows.
+                break
+
+        if timeout <= 0:
+            return
+
+        iterator = self._event_store.subscribe(session_id, cursor).__aiter__()
+        try:
+            while True:
+                remaining = deadline - asyncio.get_running_loop().time()
+                if remaining <= 0:
+                    return
+                try:
+                    envelope = await asyncio.wait_for(iterator.__anext__(), remaining)
+                except StopAsyncIteration:
+                    return
+                except asyncio.TimeoutError:
+                    return
+
+                # Advance the cursor for non-runtime families too.  The typed
+                # SessionEventStore shares one physical session log, and
+                # failing to consume control/workflow rows would replay them on
+                # every poll of a runtime-only view.
+                sequence = int(envelope.seq)
+                if sequence <= cursor:
+                    continue
+                cursor = sequence
+                runtime_event = runtime_event_from_envelope(envelope)
+                if runtime_event is not None:
+                    yield runtime_event
+        finally:
+            close = getattr(iterator, "aclose", None)
+            if close is not None:
+                await close()
+
     @staticmethod
     def _assert_same_fact(existing: RuntimeEvent, candidate: RuntimeEvent) -> None:
         existing_payload = dump_runtime_event(existing)

ksadk/events/reducer.py

@@ -189,6 +189,8 @@ class StreamReducer:
 
     def __init__(self) -> None:
         self._run_id: str | None = None
+        self._root_scope_id: str | None = None
+        self._managed_scopes: set[str] = set()
         self._status: RunStatus | None = None
         self._last_seq: int | None = None
         self._items: OrderedDict[tuple[str, str], ItemProjection] = OrderedDict()
@@ -219,13 +221,93 @@ class StreamReducer:
             return self._noop_patch(event)
 
         self._validate_run(event)
+        managed_descriptor = self._validate_managed_scope(event)
         patch = self._apply_event(event)
+        if managed_descriptor:
+            self._managed_scopes.add(event.scope_id)
+        if event.event_type in _RUN_LIFECYCLE_EVENT_TYPES and self._root_scope_id is None:
+            self._root_scope_id = event.scope_id
         if self._run_id is None:
             self._run_id = event.run_id
         self._last_seq = event.seq
         self._record_recent(event, fingerprint)
         return patch
 
+    def _validate_managed_scope(self, event: RuntimeEvent) -> bool:
+        if event.event_type in _RUN_LIFECYCLE_EVENT_TYPES:
+            # Older graph adapters use child run.progress as a nonterminal
+            # observation. Preserve that lane until a managed descriptor opts
+            # the run into the root-only contract; child terminals never pass.
+            if (
+                (
+                    event.parent_scope_id is not None
+                    and (not isinstance(event, RunProgress) or self._managed_scopes)
+                )
+                or event.scope_id in self._managed_scopes
+                or (
+                    self._managed_scopes
+                    and self._root_scope_id is not None
+                    and event.scope_id != self._root_scope_id
+                )
+            ):
+                raise self._error(
+                    event, "child_run_lifecycle", "run lifecycle belongs to root scope"
+                )
+        if not isinstance(event, (ItemStarted, ItemUpdated, ItemSnapshotReplaced, ItemCompleted)):
+            return False
+        if isinstance(event, ItemUpdated):
+            parts = (event.update,)
+        else:
+            snapshot = event.initial if isinstance(event, ItemStarted) else event.snapshot
+            parts = snapshot.parts if snapshot else ()
+        descriptors = [
+            part.data
+            for part in parts
+            if isinstance(part, DataContent)
+            and isinstance(part.data, dict)
+            and part.data.get("schema") == "execution.scope/v1"
+        ]
+        if not descriptors:
+            return False
+        from ksadk.a2a.presentation import ExecutionScopeDescriptor, validate_scope_transition
+
+        try:
+            if len(descriptors) != 1 or event.item_kind != "status":
+                raise ValueError("scope descriptor requires one status item")
+            current = ExecutionScopeDescriptor.model_validate(descriptors[0])
+            if (
+                current.scope_id != event.scope_id
+                or current.parent_scope_id != event.parent_scope_id
+            ):
+                raise ValueError("scope descriptor does not match event scope")
+            previous = self._items.get((event.scope_id, event.item_id))
+            if previous:
+                for part in previous.parts:
+                    if (
+                        isinstance(part, DataContent)
+                        and isinstance(part.data, dict)
+                        and part.data.get("schema") == "execution.scope/v1"
+                    ):
+                        validate_scope_transition(
+                            ExecutionScopeDescriptor.model_validate(part.data), current
+                        )
+            for ref in current.output_refs:
+                item = self._items.get((ref.scope_id, ref.item_id))
+                if (
+                    item is None
+                    or item.status != "completed"
+                    or (
+                        ref.part_id is not None
+                        and not any(p.part_id == ref.part_id for p in item.parts)
+                    )
+                ):
+                    raise ValueError("scope output reference is not completed")
+        except ValueError as exc:
+            raise self._error(
+                event, "invalid_execution_scope", "invalid execution scope descriptor"
+            ) from exc
+        return True
+
     def snapshot(self) -> RunProjection:
         """Return a detached projection suitable for live output or replay."""
 

ksadk/events/run_authority.py

@@ -0,0 +1,176 @@
+"""Run-scoped access to the Kernel-owned, fenced canonical event store."""
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+from ksadk.events.canonical_store import RuntimeEventStore
+
+
+class RunEventAuthority:
+    """An ephemeral capability, never serialized into request/session state."""
+
+    def __init__(
+        self,
+        event_store,
+        *,
+        session_id,
+        run_id,
+        guard,
+        interaction_ledger=None,
+        tenant_id=None,
+        agent_instance_id=None,
+        managed_a2a_bootstraps=None,
+    ):
+        self.session_id, self.run_id = session_id, run_id
+        self._store = RuntimeEventStore(event_store, session_id=session_id)
+        self._guard = guard
+        self._active = False
+        self._used = False
+        self._events = event_store
+        self._ledger = interaction_ledger
+        self._tenant, self._agent = tenant_id, agent_instance_id
+        self._managed_a2a_bootstraps = (
+            managed_a2a_bootstraps if managed_a2a_bootstraps is not None else {}
+        )
+
+    def _require(self, session_id, run_id):
+        if not self._active:
+            raise RuntimeError("canonical run authority is no longer active")
+        if session_id != self.session_id or run_id != self.run_id:
+            raise ValueError("canonical run authority identity mismatch")
+
+    def require_session(self, session_id):
+        self._require(session_id, self.run_id)
+
+    @property
+    def publication_epoch(self):
+        """Identify the actual Kernel owner, not a fabricated framework run."""
+        from ksadk.events.identity import stable_item_id
+
+        self.require_session(self.session_id)
+        return stable_item_id(
+            "kernel", self._guard.activation_id, str(self._guard.fencing_token)
+        )
+
+    def managed_invocation_policy(self):
+        """Compose approval and audited authorization within this run's fence."""
+        from datetime import datetime, timezone
+        from uuid import uuid4
+
+        from ksadk.a2a.invocation_policy import runtime_a2a_invocation_policy
+        from ksadk.a2a.runtime_approval import KernelA2AApprovalResolver, approval_target
+        from ksadk.kernel.contracts import SessionEventEnvelope
+
+        self.require_session(self.session_id)
+        if self._ledger is None or not self._tenant or not self._agent:
+            raise RuntimeError("A2A_KERNEL_POLICY_DEPENDENCIES_REQUIRED")
+
+        async def audit(request, decision, route):
+            self._require(request.handle.session_id, request.handle.run_id)
+            await self._events.append(
+                SessionEventEnvelope(
+                    event_id=uuid4(),
+                    session_id=self.session_id,
+                    seq=0,
+                    timestamp=datetime.now(timezone.utc).isoformat(),
+                    family="control",
+                    family_version=1,
+                    event_type="control.a2a_policy_evaluated",
+                    run_id=self.run_id,
+                    actor_ref="agent-kernel",
+                    payload={
+                        "schema": "a2a.policy-audit/v1",
+                        "invocation_sha256": approval_target(request)["invocation_sha256"],
+                        "action": decision.action,
+                        "reason_code": decision.reason_code,
+                        "route_kind": route,
+                    },
+                ),
+                guard=self._guard,
+            )
+
+        return runtime_a2a_invocation_policy(
+            audit=audit,
+            approval_resolver=KernelA2AApprovalResolver(
+                self._ledger, self._events, tenant_id=self._tenant, agent_instance_id=self._agent
+            ),
+        )
+
+    def register_managed_a2a(self, bootstrap):
+        self._require(self.session_id, self.run_id)
+        if getattr(bootstrap, "scoped_cancel_available", False):
+            self._managed_a2a_bootstraps[bootstrap.runtime_metadata.runtime_id] = bootstrap
+
+    async def cancel_a2a_scope(self, scope_id):
+        """Resolve a caller-owned child, then reuse the durable cancel protocol."""
+        self._require(self.session_id, self.run_id)
+        for bootstrap in tuple(self._managed_a2a_bootstraps.values()):
+            saved = await bootstrap.invocation_checkpoint_store.read(scope_id)
+            if saved is None:
+                continue
+            if (saved.handle.session_id != self.session_id
+                    or saved.handle.run_id != self.run_id
+                    or saved.request.context.caller_agent_id
+                    != bootstrap.runtime_metadata.agent_id):
+                raise ValueError("A2A_SCOPE_OWNER_CONFLICT")
+            service = bootstrap.invocation_service_for_space(
+                saved.request.spec.space_id, event_store=self,
+                policy=self.managed_invocation_policy(),
+            )
+            # cancel() re-reads under a lease, or atomically records intent when
+            # the active invocation owns it; this unlocked read grants no write.
+            return await service.cancel(saved.handle)
+        raise KeyError("A2A_INVOCATION_NOT_FOUND")
+
+    async def persist_one(self, session_id, event):
+        self._require(session_id, event.run_id)
+        existing = await self._store.resolve_existing(session_id, event)
+        # Always use the guarded append, even on a duplicate. An expired owner
+        # must not regain publication authority merely because a fact exists.
+        persisted = await self._store.append_typed(event, guard=self._guard)
+        return persisted, existing is None
+
+    async def save_runtime_checkpoint(self, checkpoint):
+        """Persist private adapter state under this exact live Kernel owner.
+
+        Checkpoint contents may include native conversation records; they must
+        never be published as SessionEvents or returned as control receipts.
+        """
+        self._require(self.session_id, self.run_id)
+        save = getattr(self._ledger, "save_runtime_checkpoint", None)
+        if not callable(save) or not self._agent:
+            raise RuntimeError("runtime checkpoint store is unavailable")
+        await save(self.run_id, checkpoint, agent_instance_id=self._agent,
+                   session_id=self.session_id, guard=self._guard)
+
+    def runtime_checkpoint_identity(self):
+        self._require(self.session_id, self.run_id)
+        if not self._agent or not self._tenant:
+            raise RuntimeError("runtime checkpoint identity is unavailable")
+        return {"agent_instance_id": self._agent, "tenant_id": self._tenant}
+
+    async def list(self, session_id, *, run_id=None, **kwargs):
+        run_id = self.run_id if run_id is None else run_id
+        self._require(session_id, run_id)
+        return await self._store.list(session_id, run_id=run_id, **kwargs)
+
+
+_current: ContextVar[RunEventAuthority | None] = ContextVar("canonical_run_authority", default=None)
+
+
+def current_run_event_authority():
+    return _current.get()
+
+
+@contextmanager
+def bind_run_event_authority(authority):
+    if authority._used:
+        raise RuntimeError("canonical run authority cannot be rebound")
+    authority._used = True
+    authority._active = True
+    token = _current.set(authority)
+    try:
+        yield authority
+    finally:
+        authority._active = False
+        _current.reset(token)

ksadk/harness/__init__.py

@@ -22,6 +22,10 @@ _EXPORTS = {
     "HarnessReasoningTurn": ("ksadk.harness.reasoner", "HarnessReasoningTurn"),
     "HarnessToolCall": ("ksadk.harness.reasoner", "HarnessToolCall"),
     "LiteLLMHarnessReasoner": ("ksadk.harness.reasoner", "LiteLLMHarnessReasoner"),
+    "ModelGatewayHarnessReasoner": (
+        "ksadk.harness.reasoner",
+        "ModelGatewayHarnessReasoner",
+    ),
     "AcceptanceCheck": ("ksadk.harness.run_control", "AcceptanceCheck"),
     "MilestoneSpec": ("ksadk.harness.run_control", "MilestoneSpec"),
     "RunControlSpec": ("ksadk.harness.run_control", "RunControlSpec"),

ksadk/harness/artifact_adapters/__init__.py

@@ -0,0 +1 @@
+"""Host adapters for Native ArtifactPort implementations."""