agentengine-sdk-python 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

ksadk/interaction/ledger.py

@@ -0,0 +1,189 @@
+# -*- coding: utf-8 -*-
+"""``InteractionLedger`` port 与跨后端共享的台账语义（Phase 1 Task 5）。
+
+所有 mutation 都接受 :class:`~ksadk.kernel.contracts.ActivationWriteGuard`
+并在 store 事务内与 activation lease 做 fence CAS；request 写 pending 行 +
+``interaction.requested``；terminal（resolve/cancel/expire）做 revision CAS、
+first-wins，并在**同一个 store 事务**内追加恰好一个 terminal SessionEvent
+（family=interaction, family_version=1）。
+
+公共事件 payload 是 interactionEvent 投影，省略
+``provider_id`` / ``native_target`` / ``continuation_metadata``。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Protocol, runtime_checkable
+from uuid import uuid4
+
+from ksadk.interaction.contracts import (
+    InteractionRecord,
+    InteractionReceipt,
+    InteractionSubmission,
+    RESOLVE_OUTCOMES,
+)
+from ksadk.kernel.contracts import (
+    ActivationWriteGuard,
+    SessionEventEnvelope,
+)
+
+INTERACTION_FAMILY = "interaction"
+INTERACTION_FAMILY_VERSION = 1
+
+ALREADY_RESOLVED = "interaction_already_resolved"
+REVISION_MISMATCH = "interaction_revision_mismatch"
+REQUEST_CONFLICT = "interaction_request_conflict"
+
+
+def request_digest(record: InteractionRecord) -> str:
+    """幂等域摘要：排除 revision/status/created_at 等可变或时钟字段。"""
+
+    canonical = json.dumps(
+        record.model_dump(
+            mode="json",
+            exclude={"revision", "status", "created_at"},
+        ),
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+    ).encode("utf-8")
+    return hashlib.sha256(canonical).hexdigest()
+
+
+def submission_digest(submission: InteractionSubmission) -> str:
+    canonical = json.dumps(
+        submission.model_dump(mode="json"),
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+    ).encode("utf-8")
+    return hashlib.sha256(canonical).hexdigest()
+
+
+def interaction_event(
+    record: InteractionRecord,
+    *,
+    event_type: str,
+    timestamp: str,
+    request: dict | None = None,
+    outcome: str | None = None,
+    response=None,
+    actor_ref: str | None = None,
+    reason: str | None = None,
+) -> SessionEventEnvelope:
+    """构造 family=interaction/v1 的公共 interactionEvent。
+
+    payload 是 schema 的 interactionEvent 投影：不含 provider_id /
+    native_target / continuation_metadata 等内部字段。
+    """
+
+    payload: dict = {
+        "schema_version": 1,
+        "event_type": event_type,
+        "interaction_id": record.interaction_id,
+        "tenant_id": record.tenant_id,
+        "agent_instance_id": record.agent_instance_id,
+        "session_id": record.session_id,
+        "run_id": record.run_id,
+        "kind": record.kind,
+        "revision": record.revision,
+        "timestamp": timestamp,
+    }
+    if request is not None:
+        payload["request"] = request
+    if outcome is not None:
+        payload["outcome"] = outcome
+    if response is not None:
+        payload["response"] = response
+    if actor_ref is not None:
+        payload["actor_ref"] = actor_ref
+    if reason is not None:
+        payload["reason"] = reason
+    return SessionEventEnvelope(
+        event_id=uuid4(),
+        session_id=record.session_id,
+        seq=0,  # 由 SessionEventStore 在持久化后分配
+        timestamp=timestamp,
+        family=INTERACTION_FAMILY,
+        family_version=INTERACTION_FAMILY_VERSION,
+        event_type=event_type,
+        payload=payload,
+        run_id=record.run_id,
+        actor_ref=actor_ref or "agent-kernel",
+    )
+
+
+def requested_event_payload(record: InteractionRecord, timestamp: str) -> SessionEventEnvelope:
+    request = {
+        "kind": record.kind,
+        "request_schema": record.request_schema,
+    }
+    if record.expires_at is not None:
+        request["expires_at"] = record.expires_at
+    if record.presentation is not None:
+        request["presentation"] = record.presentation.model_dump(mode="json")
+    return interaction_event(
+        record,
+        event_type="interaction.requested",
+        timestamp=timestamp,
+        request=request,
+    )
+
+
+def resolve_outcome(action: str) -> str:
+    try:
+        return RESOLVE_OUTCOMES[action]
+    except KeyError:  # pragma: no cover - schema 已约束 action 枚举
+        raise ValueError(f"non-resolve action {action!r}") from None
+
+
+@runtime_checkable
+class InteractionLedger(Protocol):
+    """Durable first-wins interaction 台账 port（AgentKernelStore 一致性域）。"""
+
+    async def request(
+        self, record: InteractionRecord, *, guard: ActivationWriteGuard
+    ) -> InteractionRecord: ...
+
+    async def resolve(
+        self, submission: InteractionSubmission, *, guard: ActivationWriteGuard
+    ) -> InteractionReceipt: ...
+
+    async def cancel(
+        self, interaction_id: str, expected_revision: int, *, guard: ActivationWriteGuard
+    ) -> InteractionReceipt: ...
+
+    async def expire(
+        self, interaction_id: str, expected_revision: int, *, guard: ActivationWriteGuard
+    ) -> InteractionReceipt: ...
+
+    async def get(
+        self,
+        interaction_id: str,
+        *,
+        tenant_id: str | None = None,
+        agent_instance_id: str | None = None,
+        session_id: str | None = None,
+        run_id: str | None = None,
+    ) -> InteractionRecord | None: ...
+
+    async def list_pending_interactions(
+        self, tenant_id: str, session_id: str
+    ) -> list[InteractionRecord]: ...
+
+
+__all__ = [
+    "ALREADY_RESOLVED",
+    "INTERACTION_FAMILY",
+    "INTERACTION_FAMILY_VERSION",
+    "InteractionLedger",
+    "REVISION_MISMATCH",
+    "REQUEST_CONFLICT",
+    "interaction_event",
+    "request_digest",
+    "requested_event_payload",
+    "resolve_outcome",
+    "submission_digest",
+]

ksadk/interaction/provider.py

@@ -0,0 +1,122 @@
+# -*- coding: utf-8 -*-
+"""InteractionProvider seam（Phase 1 Task 6 Step 1）。
+
+Interaction 回包的分发 seam：Worker 载入权威 :class:`InteractionRecord`
+后，把回包交给 record 绑定的 provider，由 provider 用 **activation 持有的**
+``RuntimeAdapter``/``RunHandle`` 以框架原生方式送达：
+
+- ``live_submit``：runtime 有 live 命令通道（如 Codex JSON-RPC approval），
+  回包经 ``adapter.submit`` 原路送达同一 client 实例，不重启流。
+- ``durable_resume``：runtime 以 checkpoint/continuation 收口（如
+  LangGraph），回包映射为存的 checkpoint/thread target 经 ``adapter.resume``
+  恢复执行。
+- ``unavailable``：生产 Adapter 无法以框架原生身份送达回包时**诚实拒绝**，
+  绝不静默重放一个新 run 冒充 resume。
+
+provider 的 mode 必须与 adapter 的
+:class:`~ksadk.kernel.contracts.RuntimeCapabilityMatrix` 一致：mode 只是
+静态声明，``resolve`` 内部仍逐次校验当前 adapter 的真实 capability，
+不一致时 fail closed（``runtime_interaction_unavailable``，不标 resolved）。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Protocol, runtime_checkable
+
+from ksadk.interaction.contracts import (
+    InteractionRecord,
+    InteractionSubmission,
+)
+from ksadk.runtime.adapter import RunHandle, RuntimeAdapter
+
+InteractionProviderMode = Literal["live_submit", "durable_resume", "unavailable"]
+
+RUNTIME_INTERACTION_UNAVAILABLE = "runtime_interaction_unavailable"
+"""provider 无法以框架原生身份送达回包时的稳定错误码（typed rejection）。"""
+
+
+@dataclass(frozen=True)
+class InteractionResolveContext:
+    """一次回包分发的执行上下文——全部来自当前 activation 的 ActiveExecution。"""
+
+    adapter: RuntimeAdapter
+    handle: RunHandle
+    activation_id: str
+    fencing_token: int
+
+
+@runtime_checkable
+class InteractionProvider(Protocol):
+    """把 Interaction 回包映射为框架原生 resume/submit 的 provider 协议。"""
+
+    provider_id: str
+    mode: InteractionProviderMode
+
+    async def resolve(
+        self,
+        context: InteractionResolveContext,
+        record: InteractionRecord,
+        submission: InteractionSubmission,
+    ) -> RunHandle: ...
+
+
+def require_capability(
+    context: InteractionResolveContext,
+    capability_name: str,
+    *,
+    provider_id: str,
+) -> None:
+    """fail-closed capability 校验：mode 声明与真实 adapter 能力不一致即拒绝。"""
+
+    from ksadk.kernel.errors import AgentKernelError
+
+    capability = getattr(context.adapter.capabilities(), capability_name, None)
+    if capability is None or not capability.supported:
+        reason = getattr(capability, "reason", "not_implemented") or "not_implemented"
+        raise AgentKernelError(
+            RUNTIME_INTERACTION_UNAVAILABLE,
+            f"interaction provider {provider_id!r} requires adapter capability "
+            f"{capability_name!r}, which is unavailable: {reason}",
+            retryable=False,
+            details={
+                "provider_id": provider_id,
+                "capability": capability_name,
+                "reason": reason,
+            },
+        )
+
+
+class UnavailableInteractionProvider:
+    """诚实占位：该 runtime 的回包送达路径尚未实现。"""
+
+    provider_id = ""
+    mode: InteractionProviderMode = "unavailable"
+
+    async def resolve(
+        self,
+        context: InteractionResolveContext,
+        record: InteractionRecord,
+        submission: InteractionSubmission,
+    ) -> RunHandle:
+        from ksadk.kernel.errors import AgentKernelError
+
+        provider_id = type(self).provider_id or record.provider_id
+        raise AgentKernelError(
+            RUNTIME_INTERACTION_UNAVAILABLE,
+            f"interaction provider for {provider_id!r} is unavailable: "
+            "runtime cannot deliver an interaction response with its native "
+            "identity; refusing to replay a new run",
+            retryable=False,
+            details={"provider_id": provider_id, "mode": "unavailable"},
+        )
+
+
+__all__ = [
+    "RUNTIME_INTERACTION_UNAVAILABLE",
+    "InteractionProvider",
+    "InteractionProviderMode",
+    "InteractionResolveContext",
+    "UnavailableInteractionProvider",
+    "require_capability",
+]

ksadk/interaction/providers/__init__.py

@@ -0,0 +1,52 @@
+# -*- coding: utf-8 -*-
+"""框架原生 InteractionProvider 注册表（Phase 1 Task 6）。
+
+provider 是无状态映射器（adapter/handle 由
+:class:`~ksadk.interaction.provider.InteractionResolveContext` 注入），
+因此注册表返回共享实例即可。key 同时覆盖 ``provider_id`` 与
+``runtime_type``（当前两者一致：codex/langgraph/adk）。
+"""
+
+from __future__ import annotations
+
+from typing import Mapping
+
+from ksadk.interaction.provider import (
+    InteractionProvider,
+    UnavailableInteractionProvider,
+)
+from ksadk.interaction.providers.adk import ADKInteractionProvider
+from ksadk.interaction.providers.codex import CodexInteractionProvider
+from ksadk.interaction.providers.langgraph import LangGraphInteractionProvider
+
+
+def default_interaction_providers() -> dict[str, InteractionProvider]:
+    """默认 provider 注册表：provider_id / runtime_type -> provider。"""
+
+    providers: list[InteractionProvider] = [
+        CodexInteractionProvider(),
+        LangGraphInteractionProvider(),
+        ADKInteractionProvider(),
+    ]
+    registry: dict[str, InteractionProvider] = {}
+    for provider in providers:
+        registry[provider.provider_id] = provider
+    return registry
+
+
+def provider_for(
+    registry: Mapping[str, InteractionProvider], runtime_type: str
+) -> InteractionProvider:
+    """按 runtime_type 取 provider；未知 runtime 诚实返回 unavailable 占位。"""
+
+    return registry.get(runtime_type, UnavailableInteractionProvider())
+
+
+__all__ = [
+    "ADKInteractionProvider",
+    "CodexInteractionProvider",
+    "LangGraphInteractionProvider",
+    "UnavailableInteractionProvider",
+    "default_interaction_providers",
+    "provider_for",
+]

ksadk/interaction/providers/adk.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+"""ADK InteractionProvider：诚实声明 unavailable（Phase 1 Task 6 Step 6）。
+
+ADK 的 confirmation/function-response 回包语义上要求以原 invocation 的
+native 身份续跑；当前生产 ``ADKRuntimeAdapter``（forward-only resume 经
+invocation_id）无法在一次 Interaction 回包中保留该 native 身份——
+``submit_interaction`` capability 是 unavailable（无 live 命令通道），
+resume 则会以新 invocation 重放。因此本 provider 诚实 advertise
+``unavailable`` 并 fail closed，**绝不静默重放一个新 run 冒充回包送达**。
+"""
+
+from __future__ import annotations
+
+from ksadk.interaction.contracts import (
+    InteractionRecord,
+    InteractionSubmission,
+)
+from ksadk.interaction.provider import (
+    InteractionResolveContext,
+    UnavailableInteractionProvider,
+)
+from ksadk.runtime.adapter import RunHandle
+
+
+class ADKInteractionProvider(UnavailableInteractionProvider):
+    """provider_id=adk，mode=unavailable（对齐 RunnerRuntimeAdapter 矩阵）。"""
+
+    provider_id = "adk"
+    mode = "unavailable"
+
+    async def resolve(
+        self,
+        context: InteractionResolveContext,
+        record: InteractionRecord,
+        submission: InteractionSubmission,
+    ) -> RunHandle:
+        return await super().resolve(context, record, submission)
+
+
+__all__ = ["ADKInteractionProvider"]

ksadk/interaction/providers/codex.py

@@ -0,0 +1,94 @@
+# -*- coding: utf-8 -*-
+"""Codex InteractionProvider：live JSON-RPC approval 回包（Phase 1 Task 6 Step 6）。
+
+Codex 的 HITL 模型是**事件流 + 独立 live 命令通道**：审批卡阻塞在
+``item/commandExecution/requestApproval``，回包必须经
+:meth:`ksadk.codex.runtime.CodexRuntimeAdapter.submit` 以原 ``call_id`` 送达
+**同一 client 实例**（thread 表在 adapter 进程内，换实例 = 回包丢失）。
+本 provider 不重启流，也不伪造新 run。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ksadk.interaction.contracts import (
+    InteractionRecord,
+    InteractionSubmission,
+)
+from ksadk.interaction.provider import (
+    InteractionResolveContext,
+    require_capability,
+)
+from ksadk.runtime.adapter import ResumePayload, RunHandle
+
+# interaction action -> codex 原生 approval decision 词表。
+_CODEX_APPROVAL_DECISIONS = {
+    "approve": "approve",
+    "reject": "deny",
+    "cancel": "cancel",
+}
+
+
+class CodexInteractionProvider:
+    """provider_id=codex，mode=live_submit（对齐 CodexRuntimeAdapter 矩阵）。"""
+
+    provider_id = "codex"
+    mode = "live_submit"
+
+    async def resolve(
+        self,
+        context: InteractionResolveContext,
+        record: InteractionRecord,
+        submission: InteractionSubmission,
+    ) -> RunHandle:
+        require_capability(
+            context, "submit_interaction", provider_id=self.provider_id
+        )
+        native_target = record.native_target or {}
+        call_id = str(native_target.get("call_id") or record.interaction_id)
+        if not call_id:
+            raise ValueError("codex interaction requires a native call_id")
+        if record.kind == "approval":
+            payload_kind = "approval_decision"
+            data = self._approval_data(submission.response, submission.action)
+        else:
+            payload_kind = "hitl_answer"
+            data = self._structured_data(submission.response)
+        await context.adapter.submit(
+            context.handle,
+            ResumePayload(kind=payload_kind, call_id=call_id, data=data),
+        )
+        # live_submit 不换 handle、不重启流：回包送达后原 stream 自然续跑。
+        return context.handle
+
+    @staticmethod
+    def _approval_data(response: Any, action: str) -> Any:
+        """approve/reject 映射为 codex 原生 decision；显式 response 优先。"""
+
+        decision = _CODEX_APPROVAL_DECISIONS.get(str(action), str(action))
+        if isinstance(response, dict):
+            data = {
+                key: value for key, value in response.items() if value is not None
+            }
+            if not any(key in data for key in ("decision", "name")):
+                data["decision"] = decision
+            elif "decision" in data:
+                # The runtime advertises the public Interaction vocabulary
+                # (decision enum approve/reject) in request_schema; a client
+                # echoing it must be normalized to the codex-native word
+                # instead of failing the client vocab check fail-closed.
+                data["decision"] = _CODEX_APPROVAL_DECISIONS.get(
+                    str(data["decision"]), str(data["decision"])
+                )
+            return data
+        return {"decision": decision}
+
+    @staticmethod
+    def _structured_data(response: Any) -> Any:
+        if isinstance(response, dict):
+            return dict(response)
+        return {"answer": response}
+
+
+__all__ = ["CodexInteractionProvider"]

ksadk/interaction/providers/langgraph.py

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+"""LangGraph InteractionProvider：checkpoint resume 回包（Phase 1 Task 6 Step 6）。
+
+LangGraph 的 HITL 模型是 interrupt + checkpoint：graph 停在
+``__interrupt__``，durable 状态保存在 thread 的 checkpoint。回包必须映射为
+request 时存的 checkpoint/thread target，经
+:meth:`ksadk.runtime.framework_adapters.LangGraphRuntimeAdapter.resume`
+恢复**同一个 thread**（time-travel 语义），绝不新起一个 run。
+"""
+
+from __future__ import annotations
+
+from ksadk.interaction.contracts import (
+    InteractionRecord,
+    InteractionSubmission,
+)
+from ksadk.interaction.provider import (
+    InteractionResolveContext,
+    require_capability,
+)
+from ksadk.runtime.adapter import ResumePayload, ResumeTarget, RunHandle
+
+
+class LangGraphInteractionProvider:
+    """provider_id=langgraph，mode=durable_resume（对齐 checkpoint 矩阵）。"""
+
+    provider_id = "langgraph"
+    mode = "durable_resume"
+
+    async def resolve(
+        self,
+        context: InteractionResolveContext,
+        record: InteractionRecord,
+        submission: InteractionSubmission,
+    ) -> RunHandle:
+        require_capability(context, "resume", provider_id=self.provider_id)
+        native_target = record.native_target or {}
+        checkpoint_id = str(native_target.get("checkpoint_id") or "")
+        if not checkpoint_id:
+            raise ValueError(
+                "langgraph interaction requires a stored checkpoint_id target"
+            )
+        thread_id = str(native_target.get("thread_id") or context.handle.session_id)
+        context.handle.native_ref.setdefault("thread_id", thread_id)
+        payload_kind = "approval_decision" if record.kind == "approval" else "hitl_answer"
+        payload = ResumePayload(
+            kind=payload_kind,
+            call_id=str(native_target.get("call_id") or record.interaction_id),
+            data=submission.response,
+        )
+        return await context.adapter.resume(
+            context.handle,
+            ResumeTarget(kind="checkpoint_id", id=checkpoint_id),
+            payload,
+        )
+
+
+__all__ = ["LangGraphInteractionProvider"]

ksadk/kernel/__init__.py

@@ -0,0 +1,117 @@
+# Agent Kernel v1 合同与稳定错误码的公开入口。
+from ksadk.kernel.authorization import (
+    AgentControlPermitVerifier,
+    JwksSource,
+    PermitExpiredError,
+    VerifiedAdmission,
+)
+from ksadk.kernel.contract_fingerprints import (
+    AGENT_KERNEL_V1_AGGREGATE_DIGEST,
+    AGENT_KERNEL_V1_CONTRACT_SET,
+    runtime_capability_matrix_digest,
+    runtime_capability_matrix_wire_value,
+)
+from ksadk.kernel.contracts import (
+    ActivationLease,
+    ActivationWriteGuard,
+    AdmissionWriteGuard,
+    AgentControlCommand,
+    AgentControlPermit,
+    AgentControlReceipt,
+    AgentStatusQuery,
+    AgentStatusSnapshot,
+    ControlError,
+    ControlSource,
+    EnqueuePayload,
+    InjectPayload,
+    InterruptPayload,
+    JsonValue,
+    PausePayload,
+    ResumePayload,
+    ResumeTarget,
+    RuntimeCapability,
+    RuntimeCapabilityMatrix,
+    SessionEventEnvelope,
+    SessionEventSubscription,
+    SessionEventWriteGuard,
+    SteerPayload,
+    SubmitInteractionPayload,
+    WireModel,
+    WriteContext,
+)
+from ksadk.kernel.control import AgentKernel, default_capability_matrix
+from ksadk.kernel.errors import (
+    ERROR_CODES,
+    AgentKernelError,
+    ContractMismatchError,
+    InvalidCommandError,
+    InvalidPermitError,
+    PersistenceUncertainError,
+    QueueFullError,
+    StaleFenceError,
+    UnsupportedError,
+)
+
+# worker 依赖 ksadk.runtime.adapter；runtime.adapter 又经 ksadk.events 回指本包的
+# contracts，急切导入会成环，故用 PEP 562 惰性导出。
+
+_LAZY_EXPORTS = {"AgentKernelWorker": "ksadk.kernel.worker", "WorkResult": "ksadk.kernel.worker"}
+
+
+def __getattr__(name: str):  # noqa: ANN001
+    module_path = _LAZY_EXPORTS.get(name)
+    if module_path is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    return getattr(importlib.import_module(module_path), name)
+
+__all__ = [
+    "AgentControlPermitVerifier",
+    "AgentKernel",
+    "AgentKernelWorker",
+    "JwksSource",
+    "PermitExpiredError",
+    "VerifiedAdmission",
+    "WorkResult",
+    "default_capability_matrix",
+    "AGENT_KERNEL_V1_AGGREGATE_DIGEST",
+    "AGENT_KERNEL_V1_CONTRACT_SET",
+    "runtime_capability_matrix_digest",
+    "runtime_capability_matrix_wire_value",
+    "ERROR_CODES",
+    "AgentKernelError",
+    "ContractMismatchError",
+    "InvalidCommandError",
+    "InvalidPermitError",
+    "PersistenceUncertainError",
+    "QueueFullError",
+    "StaleFenceError",
+    "UnsupportedError",
+    "ActivationLease",
+    "ActivationWriteGuard",
+    "AdmissionWriteGuard",
+    "AgentControlCommand",
+    "AgentControlPermit",
+    "AgentControlReceipt",
+    "AgentStatusQuery",
+    "AgentStatusSnapshot",
+    "ControlError",
+    "ControlSource",
+    "EnqueuePayload",
+    "InjectPayload",
+    "InterruptPayload",
+    "JsonValue",
+    "PausePayload",
+    "ResumePayload",
+    "ResumeTarget",
+    "RuntimeCapability",
+    "RuntimeCapabilityMatrix",
+    "SessionEventEnvelope",
+    "SessionEventSubscription",
+    "SessionEventWriteGuard",
+    "SteerPayload",
+    "SubmitInteractionPayload",
+    "WireModel",
+    "WriteContext",
+]