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

ksadk/runtime/adapter.py

@@ -0,0 +1,345 @@
+"""RuntimeAdapter 平台接口 (goal-03 / G0.3 冻结稿)。
+
+**只做签名与语义冻结,不实现具体 adapter**(具体 adapter 是后续 A4/A6,如 ADK/LangGraph
+adapter)。本模块定义三层结构与六动词签名,供 Runtime 产生端、server 持久化、A2A
+真实 cancel 等共同消费。
+
+结构(H2 §4.2):
+
+- :class:`BaseRuntime`:表达 Runtime **原生能力**(现有 ``BaseRunner`` 的演进目标,不推倒)。
+- :class:`RuntimeAdapter`:把原生能力映射为**平台接口**(六动词)。
+- :class:`RuntimeRegistry`:按 ``runtime_type`` 注册 adapter(替代 ``runners/factory.py``
+  的 if/elif 分发)。
+
+六动词语义契约(2026-07-21 友商代码核验,见 docstring 各处):
+
+1. ``stream`` 返回 :class:`~ksadk.events.runtime_event.RuntimeEvent` 事件流(对接 G0.2),
+   模型 = **事件流 + 独立命令/恢复通道**:审批回包走 ``resume``/``submit``,不在事件流
+   回写(非 duplex stream)——codex/ADK/LangGraph 都是这个模型。
+2. ``cancel`` 是状态机,返回 :class:`CancelResult` 枚举(不是 bool——Wegent 实测 bool
+   区分不了"记 pending"和"真 interrupt")。
+3. ``resume`` 拆 :class:`ResumeTarget`(恢复目标)与 :class:`ResumePayload`(回包)两个
+   参数,不混成 union(ADK 区分 invocation_id 目标 vs function response 回包;Codex 区分
+   resume_thread_id vs Op 回包)。
+4. ``checkpoint`` 粒度用 :class:`CheckpointCapability` 声明(不承诺所有 runtime 同等能力,
+   诚实暴露 capability matrix)。
+5. ``start`` 带 session/tenant 维度(:class:`StartRequest` 的 ``user_id`` + ``session_id``),
+   不只是 prompt。
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Any, AsyncIterator, Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ksadk.events.runtime_event import RuntimeEvent
+
+# ---------------------------------------------------------------------------
+# cancel 状态机
+# ---------------------------------------------------------------------------
+
+
+class CancelResult(str, Enum):
+    """cancel 的结果状态机。
+
+    Wegent ``cancel()`` 实测:无活跃 turn 记 pending 也返回 true、成功 interrupt 也返回
+    true,**bool 区分不了两种结果**——因此必须用枚举显式区分。
+    """
+
+    INTERRUPTED_ACTIVE_TURN = "interrupted_active_turn"
+    """有活跃 turn,已真实 interrupt。"""
+
+    PENDING_CANCEL_RECORDED = "pending_cancel_recorded"
+    """无活跃 turn,已记录 pending cancel,下一个 turn 开始时被消费。"""
+
+    NOT_RUNNING = "not_running"
+    """目标不在运行(无可取消的活跃/pending run)。"""
+
+    FAILED = "failed"
+    """取消动作本身失败(如底层 runtime 报错)。"""
+
+
+# ---------------------------------------------------------------------------
+# resume 目标与回包(两件拆开的的事)
+# ---------------------------------------------------------------------------
+
+
+class ResumeTarget(BaseModel):
+    """恢复目标:回到哪里。
+
+    - ``invocation_id``:精确到某次调用(ADK forward-only resume)。
+    - ``thread_id``:某条会话线程(Codex resume_thread_id)。
+    - ``checkpoint_id``:某个 checkpoint(LangGraph time-travel)。
+    """
+
+    kind: Literal["invocation_id", "thread_id", "checkpoint_id"]
+    id: str
+
+
+class ResumePayload(BaseModel):
+    """恢复回包:带着什么输入恢复(可为空——纯粹续跑)。
+
+    - ``tool_result``:工具执行结果(function response)。
+    - ``approval_decision``:审批决定(对应 ``approval.requested`` 的回包,走命令通道)。
+    - ``hitl_answer``:human-in-the-loop 回答。
+    - ``free_text``:自由文本输入。
+    """
+
+    kind: Literal["tool_result", "approval_decision", "hitl_answer", "free_text"]
+    call_id: Optional[str] = None
+    """对应的 ``approval.requested`` / ``tool.call`` 的 id(如有)。"""
+    data: Any = None
+
+
+# ---------------------------------------------------------------------------
+# checkpoint 能力声明
+# ---------------------------------------------------------------------------
+
+
+class CheckpointCapability(BaseModel):
+    """checkpoint 粒度声明。诚实暴露,不承诺所有 runtime 同等能力。
+
+    与现有 ``BaseRunner.describe_checkpoint_capability`` 对齐演进。
+    """
+
+    supported: bool
+    granularity: Literal["delta", "snapshot", "none"]
+    """delta(增量)vs snapshot(快照)vs none。"""
+    rollback_scope: Literal["turn", "invocation", "none"]
+    """可按 turn 还是 invocation 回滚。"""
+    fork_supported: bool
+    """是否支持从某 checkpoint fork 出新分支。"""
+    durable: bool
+    """是否持久化(跨进程/重启保留)。"""
+    shared_across_pods: bool
+    """是否跨 pod 共享(K8s 多副本可读同一 checkpoint)。"""
+    reason: str = ""
+
+
+class CheckpointDescriptor(BaseModel):
+    """一次 checkpoint 的描述(checkpoint 动词的返回值)。"""
+
+    checkpoint_id: str
+    invocation_id: str
+    capability: CheckpointCapability
+    ref: dict[str, Any] = Field(default_factory=dict)
+    """runtime 私有引用(如 LangGraph checkpoint 的 (thread_id, checkpoint_id) 元组)。"""
+
+
+# ---------------------------------------------------------------------------
+# start 请求与 run 句柄
+# ---------------------------------------------------------------------------
+
+
+CONVERSATION_PREPROCESSING_METADATA_KEY = "conversation_request"
+"""StartRequest metadata key for the shared conversation preprocessing contract."""
+
+
+class ConversationPreprocessingRequest(BaseModel):
+    """Transport-neutral input for the existing conversation preprocessing path.
+
+    Protocol adapters keep their wire-specific fields out of the runner payload and
+    place the canonical conversation inputs here.  ``RunnerRuntimeAdapter`` then
+    reuses the same history, attachment, model-policy, platform-context, ambient
+    KB/memory and tracing preparation as the normal RunAgent/Responses entrypoints.
+
+    The model is additive and allows unknown fields so a newer protocol adapter can
+    talk to an older runtime without losing forward-compatible metadata.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    messages: list[dict[str, Any]] = Field(default_factory=list)
+    model_metadata: dict[str, Any] = Field(default_factory=dict)
+    model_options: dict[str, Any] = Field(default_factory=dict)
+    state_delta: dict[str, Any] = Field(default_factory=dict)
+    instructions: Optional[str] = None
+    request_metadata: dict[str, Any] = Field(default_factory=dict)
+    custom_metadata: dict[str, Any] = Field(default_factory=dict)
+    account_id: Optional[str] = None
+    response_id: Optional[str] = None
+
+
+class StartRequest(BaseModel):
+    """start 的输入:带 session/tenant 维度,不只是 prompt。"""
+
+    input: Any
+    """用户消息或结构化输入。"""
+    user_id: str
+    session_id: str
+    agent_id: Optional[str] = None
+    model: Optional[str] = None
+    config: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    def conversation_preprocessing(self) -> Optional[ConversationPreprocessingRequest]:
+        """Return the opt-in shared preprocessing request, if one was supplied."""
+
+        raw = self.metadata.get(CONVERSATION_PREPROCESSING_METADATA_KEY)
+        if raw is None:
+            return None
+        return ConversationPreprocessingRequest.model_validate(raw)
+
+
+class RunHandle(BaseModel):
+    """一次 run 的不透明句柄(start 返回,后续 stream/cancel/resume/checkpoint/close 用)。"""
+
+    run_id: str
+    """= invocation_id。"""
+    session_id: str
+    runtime_type: str
+    native_ref: dict[str, Any] = Field(default_factory=dict)
+    """adapter 私有引用(如 ADK 的 (app_name, user_id, session_id)、Codex 的 thread_ref)。"""
+
+
+# ---------------------------------------------------------------------------
+# BaseRuntime:Runtime 原生能力
+# ---------------------------------------------------------------------------
+
+
+class BaseRuntime(ABC):
+    """Runtime 原生能力面(现有 ``BaseRunner`` 的演进目标,不推倒)。
+
+    ``BaseRunner`` 的 ``request_cancel`` / ``describe_checkpoint_capability`` /
+    ``invoke`` / ``stream`` 是原生能力的现状;``BaseRuntime`` 是其平台化抽象。
+    具体 runner(ADK/LangGraph/...)以 ``BaseRuntime`` 表达原生能力,再由
+    :class:`RuntimeAdapter` 映射为平台六动词。
+    """
+
+    runtime_type: str = "unknown"
+
+    @abstractmethod
+    def native_capabilities(self) -> dict[str, Any]:
+        """原生能力声明(cancel / checkpoint / resume / session continuity 等)。"""
+        raise NotImplementedError
+
+
+# ---------------------------------------------------------------------------
+# RuntimeAdapter:平台六动词
+# ---------------------------------------------------------------------------
+
+
+class RuntimeAdapter(ABC):
+    """把 :class:`BaseRuntime` 的原生能力映射为平台接口(六动词)。
+
+    签名冻结:以下六个方法的名字、参数、返回类型在 v1 冻结,只允许 additive 演进
+    (新增方法/可选参数),不允许改既有签名。
+    """
+
+    def __init__(self, runtime: BaseRuntime) -> None:
+        self._runtime = runtime
+
+    @property
+    def runtime(self) -> BaseRuntime:
+        return self._runtime
+
+    @abstractmethod
+    async def start(self, request: StartRequest) -> RunHandle:
+        """启动一次 run,返回句柄。"""
+        raise NotImplementedError
+
+    @abstractmethod
+    def stream(self, handle: RunHandle) -> AsyncIterator[RuntimeEvent]:
+        """订阅 run 的结构化事件流(对接 G0.2 RuntimeEvent)。
+
+        注意:这是**事件流 + 独立命令/恢复通道**模型——审批回包/工具结果走
+        :meth:`resume`,不在本事件流上回写(非 duplex stream)。
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def cancel(self, handle: RunHandle) -> CancelResult:
+        """请求取消。返回状态机结果;成功 cancel 级联丢弃该 turn 的 pending 审批。"""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def resume(
+        self,
+        handle: RunHandle,
+        target: ResumeTarget,
+        payload: Optional[ResumePayload],
+    ) -> RunHandle:
+        """恢复 run。``target`` 是恢复目标,``payload`` 是回包(可为空)。"""
+        raise NotImplementedError
+
+    async def attach(self, handle: RunHandle) -> RunHandle:
+        """Attach a persisted handle in this process before ``resume``/``stream``.
+
+        A handle restored from durable task metadata is not evidence that the
+        underlying runner exists in this process.  Adapters which support
+        cross-process recovery must implement this seam using their framework's
+        durable checkpoint/session API.  The default deliberately fails closed.
+        """
+        raise RuntimeError(
+            f"{type(self).__name__} does not support attaching persisted run "
+            f"{handle.run_id!r}; durable runtime restore is unavailable"
+        )
+
+    def is_handle_attached(self, handle: RunHandle) -> bool:
+        """Return whether ``handle`` is already attached to this adapter process."""
+        return False
+
+    @abstractmethod
+    async def checkpoint(self, handle: RunHandle) -> CheckpointDescriptor:
+        """在当前位置创建 checkpoint,返回描述(粒度见 capability)。"""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def close(self, handle: RunHandle) -> None:
+        """释放 run 持有的运行期资源。"""
+        raise NotImplementedError
+
+
+# ---------------------------------------------------------------------------
+# RuntimeRegistry
+# ---------------------------------------------------------------------------
+
+
+class RuntimeRegistry:
+    """按 ``runtime_type`` 注册/查找 :class:`RuntimeAdapter`。
+
+    替代 ``runners/factory.py`` 的 if/elif 分发:新 runtime 通过 ``register``
+    注册,不再改 factory 分支。
+    """
+
+    def __init__(self) -> None:
+        self._adapters: dict[str, type[RuntimeAdapter]] = {}
+
+    def register(self, runtime_type: str, adapter_cls: type[RuntimeAdapter]) -> None:
+        if not isinstance(runtime_type, str) or not runtime_type.strip():
+            raise ValueError("runtime_type 必须是非空字符串")
+        if not (isinstance(adapter_cls, type) and issubclass(adapter_cls, RuntimeAdapter)):
+            raise TypeError(f"adapter_cls 必须是 RuntimeAdapter 子类: {adapter_cls!r}")
+        self._adapters[runtime_type.strip()] = adapter_cls
+
+    def get(self, runtime_type: str) -> type[RuntimeAdapter]:
+        try:
+            return self._adapters[runtime_type]
+        except KeyError:
+            raise KeyError(
+                f"未注册的 runtime_type: {runtime_type!r}(已注册: {sorted(self._adapters)})"
+            ) from None
+
+    def create(self, runtime_type: str, runtime: BaseRuntime) -> RuntimeAdapter:
+        """按 runtime_type 实例化 adapter(注入原生 runtime)。"""
+        return self.get(runtime_type)(runtime)
+
+    def registered_types(self) -> list[str]:
+        return sorted(self._adapters)
+
+
+__all__ = [
+    "BaseRuntime",
+    "CancelResult",
+    "CheckpointCapability",
+    "CheckpointDescriptor",
+    "ResumePayload",
+    "ResumeTarget",
+    "RunHandle",
+    "RuntimeAdapter",
+    "RuntimeRegistry",
+    "StartRequest",
+]

ksadk/runtime/framework_adapters.py

@@ -0,0 +1,124 @@
+"""ADK / LangGraph 两个框架的 RuntimeAdapter (goal-07)。
+
+在通用 :class:`~ksadk.runtime.runner_adapter.RunnerRuntimeAdapter` 之上,只声明
+框架差异(resume 目标 + checkpoint 粒度),诚实暴露,不开接口后门:
+
+- ADK:**forward-only**,resume 经 ``invocation_id``;不支持 time-travel/fork。
+- LangGraph:**time-travel**,resume 经 ``checkpoint_id``;可按 turn 回滚/fork。
+
+并用 :func:`build_default_registry` 注册进 G0.3 ``RuntimeRegistry``。
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ksadk.runners.base_runner import BaseRunner
+from ksadk.runtime.adapter import (
+    CheckpointCapability,
+    ResumePayload,
+    ResumeTarget,
+    RunHandle,
+    RuntimeRegistry,
+)
+from ksadk.runtime.runner_adapter import RunnerRuntimeAdapter
+
+
+class ADKRuntimeAdapter(RunnerRuntimeAdapter):
+    """ADK 框架 adapter(forward-only resume)。"""
+
+    def __init__(self, runner: BaseRunner) -> None:
+        super().__init__(runner, runtime_type="adk")
+
+    async def _resume_native(
+        self,
+        handle: RunHandle,
+        target: ResumeTarget,
+        payload: Optional[ResumePayload],
+    ) -> Optional[dict]:
+        # ADK forward-only:恢复目标 = invocation_id。注入 adk_runner 真消费的
+        # ``checkpoint_resume`` + ``framework_ref.adk.invocation_id`` → run_async(invocation_id)。
+        return {
+            "checkpoint_resume": True,
+            "run_id": target.id,
+            "framework_ref": {"adk": {"invocation_id": target.id}},
+            "input": payload.data if payload else None,
+        }
+
+    def _checkpoint_capability(self) -> CheckpointCapability:
+        capability = super()._checkpoint_capability()
+        if not capability.supported:
+            return capability
+        return capability.model_copy(
+            update={
+                "granularity": "delta",
+                "rollback_scope": "invocation",
+                "fork_supported": False,
+            }
+        )
+
+
+class LangGraphRuntimeAdapter(RunnerRuntimeAdapter):
+    """LangGraph 框架 adapter(time-travel resume)。"""
+
+    def __init__(self, runner: BaseRunner) -> None:
+        super().__init__(runner, runtime_type="langgraph")
+
+    async def _resume_native(
+        self,
+        handle: RunHandle,
+        target: ResumeTarget,
+        payload: Optional[ResumePayload],
+    ) -> Optional[dict]:
+        if target.kind != "checkpoint_id":
+            raise ValueError(f"LangGraph resume requires checkpoint_id target, got {target.kind!r}")
+        known_checkpoint_ids = {
+            str(checkpoint_id)
+            for checkpoint_id in handle.native_ref.get("known_checkpoint_ids", [])
+        }
+        if target.id not in known_checkpoint_ids:
+            raise ValueError(f"checkpoint {target.id!r} does not belong to run {handle.run_id!r}")
+        if payload is not None and payload.call_id:
+            pending_approval_ids = {
+                str(call_id) for call_id in handle.native_ref.get("pending_approval_ids", [])
+            }
+            if payload.call_id not in pending_approval_ids:
+                raise ValueError(f"unknown interrupt {payload.call_id!r}")
+        # LangGraph time-travel:恢复目标 = checkpoint_id。注入 langgraph_runner 真消费的
+        # ``checkpoint_resume`` + ``framework_ref.langgraph.{checkpoint_id,thread_id}``。
+        return {
+            "checkpoint_resume": True,
+            "resume_payload_provided": payload is not None,
+            "resume_interrupt_id": payload.call_id if payload else None,
+            "framework_ref": {
+                "langgraph": {"checkpoint_id": target.id, "thread_id": handle.session_id}
+            },
+            "input": payload.data if payload else None,
+        }
+
+    def _checkpoint_capability(self) -> CheckpointCapability:
+        capability = super()._checkpoint_capability()
+        if not capability.supported:
+            return capability
+        return capability.model_copy(
+            update={
+                "granularity": "snapshot",
+                "rollback_scope": "turn",
+                "fork_supported": True,
+            }
+        )
+
+
+def build_default_registry() -> RuntimeRegistry:
+    """构造默认 RuntimeRegistry 并注册 ADK/LangGraph adapter 类型。"""
+    registry = RuntimeRegistry()
+    registry.register("adk", ADKRuntimeAdapter)
+    registry.register("langgraph", LangGraphRuntimeAdapter)
+    return registry
+
+
+__all__ = [
+    "ADKRuntimeAdapter",
+    "LangGraphRuntimeAdapter",
+    "build_default_registry",
+]

ksadk/runtime/preprocessing.py

@@ -0,0 +1,118 @@
+"""Shared conversation preprocessing for RuntimeAdapter-backed transports."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from ksadk.conversations.runtime_input import (
+    _build_runner_ambient_contexts,
+    _build_runner_request_payload,
+    _inject_runner_deferred_tools_for_request,
+    _runner_type_name,
+)
+from ksadk.conversations.runtime_preparation import build_run_input
+from ksadk.runtime.adapter import (
+    CONVERSATION_PREPROCESSING_METADATA_KEY,
+    StartRequest,
+)
+from ksadk.runtime_context import PlatformInvocationContext
+
+
+@dataclass
+class PreparedRuntimeStart:
+    """Runner payload plus the ContextVar/tracing identity used to execute it."""
+
+    runner_input: dict[str, Any]
+    context: PlatformInvocationContext
+    input_text: str
+    response_id: str | None = None
+
+
+def _fallback_messages(input_value: Any) -> list[dict[str, Any]]:
+    if isinstance(input_value, list) and all(isinstance(item, dict) for item in input_value):
+        return [dict(item) for item in input_value]
+    if isinstance(input_value, dict) and isinstance(input_value.get("messages"), list):
+        return [dict(item) for item in input_value["messages"] if isinstance(item, dict)]
+    return [{"role": "user", "content": input_value}]
+
+
+async def prepare_runtime_start(request: StartRequest, runner: Any) -> PreparedRuntimeStart | None:
+    """Prepare an opted-in StartRequest through the canonical conversation pipeline.
+
+    Requests without ``conversation_request`` retain the frozen RuntimeAdapter v1
+    behavior.  This keeps A2A, Harness and framework contract callers unchanged while
+    allowing AG-UI and future transports to share the production input semantics.
+    """
+
+    conversation = request.conversation_preprocessing()
+    if conversation is None:
+        return None
+
+    prepare_for_request = getattr(runner, "prepare_for_request", None)
+    if callable(prepare_for_request):
+        prepare_for_request(request.model)
+
+    outer_metadata = {
+        key: value
+        for key, value in request.metadata.items()
+        if key != CONVERSATION_PREPROCESSING_METADATA_KEY
+    }
+    request_metadata = {**outer_metadata, **conversation.request_metadata}
+    messages = conversation.messages or _fallback_messages(request.input)
+    prepared = await build_run_input(
+        agent_id=str(request.agent_id or "agent"),
+        user_id=request.user_id,
+        session_id=request.session_id,
+        messages=messages,
+        model=request.model,
+        model_metadata=conversation.model_metadata or None,
+        model_options=conversation.model_options or None,
+        state_delta=conversation.state_delta or None,
+        instructions=conversation.instructions,
+        request_metadata=request_metadata,
+        custom_metadata=conversation.custom_metadata,
+        invocation_id=str(request.metadata.get("invocation_id") or "") or None,
+    )
+    _inject_runner_deferred_tools_for_request(runner, prepared)
+    ambient_contexts = _build_runner_ambient_contexts(
+        runner=runner,
+        user_id=request.user_id,
+        user_input=prepared.user_input,
+    )
+    runtime_context = PlatformInvocationContext(
+        agent_id=str(request.agent_id or "agent"),
+        user_id=request.user_id,
+        account_id=str(conversation.account_id or ""),
+        session_id=prepared.session_id,
+        history=list(prepared.history),
+        input_content=list(prepared.input_content),
+        input_messages=list(prepared.input_messages),
+        input_parts=list(prepared.user_parts),
+        attachments=list(prepared.attachments),
+        attachment_results=list(prepared.attachment_results),
+        current_attachments=list(prepared.current_attachments),
+        current_attachment_results=list(prepared.current_attachment_results),
+        has_current_files=prepared.has_current_files,
+        runner_type=_runner_type_name(runner),
+        metadata=dict(conversation.custom_metadata),
+        model=request.model,
+        model_options=prepared.model_options,
+        kb_context=ambient_contexts.get("kb_context"),
+        memory_context=ambient_contexts.get("memory_context"),
+    )
+    canonical_payload = _build_runner_request_payload(
+        prepared=prepared,
+        model=request.model,
+        runtime_context=runtime_context,
+        runner=runner,
+    )
+    return PreparedRuntimeStart(
+        runner_input={**request.config, **canonical_payload},
+        context=runtime_context,
+        input_text=prepared.user_input or prepared.user_display_input,
+        response_id=conversation.response_id,
+    )
+
+
+__all__ = ["PreparedRuntimeStart", "prepare_runtime_start"]