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

ksadk/events/store.py

@@ -0,0 +1,317 @@
+"""RuntimeEventStore — 统一事件 store + 两类订阅 + projection (goal-10,H2 §4.3)。
+
+复用现有 ``SessionEvent(seq_id cursor)`` 持久化骨架(session service),**不另造存储、
+不改表**:RuntimeEvent 的 ``phase``/``payload``/``schema_version``/``user_id`` 打包进
+``SessionEvent.content``/``metadata``(均为自由 dict),并以 ``_RUNTIME_MARKER`` 标记区分
+legacy session 事件(assistant_message/run_status 等),读取时只还原 runtime 事件。
+
+- ``append`` / ``list``:RuntimeEvent ↔ SessionEvent 双向映射。
+- ``subscribe_run``:单 invocation,终态(completed/failed/canceled)后关闭(对齐现有
+  run 级 SSE 语义,新 schema)。
+- ``subscribe_session``:session 级 cursor stream,跨 invocation,支持 run 后 action 与
+  replay(A2UI 依赖)。
+- ``project``:replay / 增量 projection(fold)。
+- cursor 断线续传:订阅方持 ``last_seq_id``,断线后按 ``after_seq_id`` 重连,不丢不重。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, AsyncIterator, Callable, Iterable, Optional
+
+from ksadk.events.runtime_event import EventType, RuntimeEvent
+from ksadk.sessions.base import SessionEvent
+
+logger = logging.getLogger(__name__)
+
+#: SessionEvent.metadata 中的标记:该条是由 RuntimeEvent 持久化来的(区分 legacy 事件)。
+_RUNTIME_MARKER = "ksadk_runtime_event"
+_A2A_TASK_AGENT_STATE_KEY = "__ksadk_a2a_task_agents"
+
+#: run 终态(subscribe_run 遇到即关闭;interrupted 是 input-required 暂停,非终态)。
+_RUN_TERMINAL_EVENT_TYPES = frozenset(
+    {
+        EventType.RUN_COMPLETED,
+        EventType.RUN_FAILED,
+        EventType.RUN_CANCELED,
+    }
+)
+
+#: 默认订阅轮询间隔(秒)与单条流上限(秒,防泄漏)。
+_DEFAULT_POLL_INTERVAL = 0.25
+_DEFAULT_STREAM_TIMEOUT = 5 * 60
+
+
+# ---------------------------------------------------------------------------
+# RuntimeEvent ↔ SessionEvent 映射
+# ---------------------------------------------------------------------------
+
+
+def runtime_event_to_session_event(event: RuntimeEvent) -> SessionEvent:
+    """把 RuntimeEvent 打包为 SessionEvent(content/metadata 承载新 schema 字段,不改表)。"""
+    event.validate_conformance()
+    return SessionEvent(
+        id=event.event_id,
+        session_id=event.session_id,
+        author=event.agent_id,
+        event_type=event.event_type,
+        content={"phase": event.phase, "payload": dict(event.payload)},
+        timestamp=event.timestamp,
+        seq_id=event.seq_id,
+        invocation_id=event.invocation_id,
+        metadata={
+            _RUNTIME_MARKER: True,
+            "user_id": event.user_id,
+            "schema_version": event.schema_version,
+        },
+    )
+
+
+def session_event_to_runtime_event(event: SessionEvent) -> Optional[RuntimeEvent]:
+    """把 SessionEvent 还原为 RuntimeEvent;非 runtime 事件(无标记)返回 None。"""
+    if not (event.metadata or {}).get(_RUNTIME_MARKER):
+        return None
+    content = event.content or {}
+    return RuntimeEvent.create(
+        event.event_type,
+        agent_id=event.author,
+        user_id=str(event.metadata.get("user_id") or ""),
+        session_id=event.session_id,
+        invocation_id=event.invocation_id or "",
+        seq_id=event.seq_id,
+        payload=dict(content.get("payload") or {}),
+        phase=content.get("phase"),
+        event_id=event.id,
+        timestamp=event.timestamp,
+    )
+
+
+# ---------------------------------------------------------------------------
+# RuntimeEventStore
+# ---------------------------------------------------------------------------
+
+
+class RuntimeEventStore:
+    """统一事件 store(复用 session service 的 seq_id cursor 持久化骨架)。"""
+
+    def __init__(self, session_service: Any) -> None:
+        self._service = session_service
+
+    # ---- append ----
+
+    async def append(self, events: Iterable[RuntimeEvent]) -> list[RuntimeEvent]:
+        """持久化一组 RuntimeEvent,返回存储层分配 cursor 后的事件。"""
+        appended: list[RuntimeEvent] = []
+        for event in events:
+            appended.append(await self.append_one(event))
+        return appended
+
+    async def append_one(self, event: RuntimeEvent) -> RuntimeEvent:
+        """Idempotently persist one event using its durable ``event_id``.
+
+        Replayed wire events return their original store-assigned cursor.  Reuse
+        of an ID for different content is rejected rather than silently losing a
+        legal event.
+        """
+        persisted, _created = await self.reserve_once(event)
+        return persisted
+
+    async def reserve_once(self, event: RuntimeEvent) -> tuple[RuntimeEvent, bool]:
+        """Durably claim ``event.event_id`` and report whether this caller won.
+
+        SQL backends enforce a unique event id, so this is also the command
+        reservation seam for side effects such as checkpoint resume.  A loser
+        receives the existing identical fact with ``created=False`` and must
+        not repeat the side effect.
+        """
+        existing = await self._event_by_id(event.session_id, event.event_id)
+        if existing is not None:
+            self._assert_same_event(existing, event)
+            return existing, False
+        try:
+            stored = await self._service.append_event(
+                event.session_id, runtime_event_to_session_event(event)
+            )
+        except Exception:
+            # Durable backends enforce a unique event id.  A concurrent writer
+            # may win between the read and append; resolve that race by reading
+            # the persisted fact and validating its content.
+            existing = await self._event_by_id(event.session_id, event.event_id)
+            if existing is None:
+                raise
+            self._assert_same_event(existing, event)
+            return existing, False
+        persisted = session_event_to_runtime_event(stored)
+        if persisted is None:  # pragma: no cover - marker is set above by construction
+            raise RuntimeError("RuntimeEvent 持久化后缺少 runtime marker")
+        return persisted, True
+
+    async def _event_by_id(self, session_id: str, event_id: str) -> RuntimeEvent | None:
+        raw = await self._service.get_events(session_id)
+        for stored in raw:
+            if stored.id != event_id:
+                continue
+            return session_event_to_runtime_event(stored)
+        return None
+
+    @staticmethod
+    def _assert_same_event(existing: RuntimeEvent, candidate: RuntimeEvent) -> None:
+        comparable = (
+            "event_type",
+            "agent_id",
+            "user_id",
+            "session_id",
+            "invocation_id",
+            "phase",
+            "payload",
+        )
+        if any(getattr(existing, field) != getattr(candidate, field) for field in comparable):
+            raise ValueError(f"RuntimeEvent id collision for {candidate.event_id!r}")
+
+    async def set_task_agent(self, session_id: str, task_id: str, agent_id: str) -> None:
+        """Persist the outbound A2A task locator in session state."""
+        session = await self._service.get_session_metadata(session_id)
+        if session is None:
+            raise ValueError(f"A2A space session {session_id!r} not found")
+        current = await self._service.get_state(
+            session.agent_id,
+            session.user_id,
+            session.id,
+            scope="session",
+        )
+        mapping = dict((current.state if current else {}).get(_A2A_TASK_AGENT_STATE_KEY) or {})
+        existing = mapping.get(task_id)
+        if existing and existing != agent_id:
+            raise ValueError(f"A2A task {task_id!r} is already bound to another agent")
+        mapping[task_id] = agent_id
+        await self._service.update_state(
+            agent_id=session.agent_id,
+            user_id=session.user_id,
+            session_id=session.id,
+            scope="session",
+            state_delta={_A2A_TASK_AGENT_STATE_KEY: mapping},
+        )
+
+    async def get_task_agent(self, session_id: str, task_id: str) -> str | None:
+        """Resolve a persisted outbound A2A task locator."""
+        session = await self._service.get_session_metadata(session_id)
+        if session is None:
+            return None
+        current = await self._service.get_state(
+            session.agent_id,
+            session.user_id,
+            session.id,
+            scope="session",
+        )
+        mapping = dict((current.state if current else {}).get(_A2A_TASK_AGENT_STATE_KEY) or {})
+        value = mapping.get(task_id)
+        return str(value) if value else None
+
+    # ---- list ----
+
+    async def list(
+        self,
+        session_id: str,
+        *,
+        after_seq_id: int = 0,
+        before_seq_id: Optional[int] = None,
+        invocation_id: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> list[RuntimeEvent]:
+        """按 seq cursor 读 RuntimeEvent(升序;可按 invocation 过滤 / before 上界回放)。"""
+        raw = await self._service.get_events(
+            session_id,
+            after_seq_id=after_seq_id,
+            before_seq_id=before_seq_id,
+            limit=limit,
+        )
+        events = [e for e in (session_event_to_runtime_event(se) for se in raw) if e is not None]
+        if invocation_id is not None:
+            events = [e for e in events if e.invocation_id == invocation_id]
+        events.sort(key=lambda e: e.seq_id)
+        return events
+
+    # ---- 两类订阅 ----
+
+    async def subscribe_run(
+        self,
+        session_id: str,
+        invocation_id: str,
+        *,
+        after_seq_id: int = 0,
+        poll_interval: float = _DEFAULT_POLL_INTERVAL,
+        timeout: float = _DEFAULT_STREAM_TIMEOUT,
+    ) -> AsyncIterator[RuntimeEvent]:
+        """单 invocation 订阅:只产该 invocation 的 RuntimeEvent,终态后关闭。
+
+        断线续传:调用方持返回事件的 ``seq_id``,断线后以 ``after_seq_id`` 重连即可续传,
+        不丢(>after 的全部重发)、不重(<=after 的不重发)。
+        """
+        last = int(after_seq_id or 0)
+        deadline = asyncio.get_event_loop().time() + timeout
+        while True:
+            events = await self.list(session_id, after_seq_id=last, invocation_id=invocation_id)
+            for event in events:
+                last = max(last, event.seq_id)
+                yield event
+                if event.event_type in _RUN_TERMINAL_EVENT_TYPES:
+                    return
+            if asyncio.get_event_loop().time() > deadline:
+                return
+            await asyncio.sleep(poll_interval)
+
+    async def subscribe_session(
+        self,
+        session_id: str,
+        *,
+        after_seq_id: int = 0,
+        poll_interval: float = _DEFAULT_POLL_INTERVAL,
+        timeout: float = _DEFAULT_STREAM_TIMEOUT,
+    ) -> AsyncIterator[RuntimeEvent]:
+        """session 级 cursor stream:跨 invocation 产全部 RuntimeEvent(replay + live)。
+
+        支持 run 后 action 与跨 invocation replay(A2UI 依赖);断线续传同 subscribe_run。
+        """
+        last = int(after_seq_id or 0)
+        deadline = asyncio.get_event_loop().time() + timeout
+        while True:
+            events = await self.list(session_id, after_seq_id=last)
+            for event in events:
+                last = max(last, event.seq_id)
+                yield event
+            if asyncio.get_event_loop().time() > deadline:
+                return
+            await asyncio.sleep(poll_interval)
+
+    # ---- projection / replay ----
+
+    async def project(
+        self,
+        session_id: str,
+        projection: Optional[Callable[[Any, RuntimeEvent], Any]] = None,
+        *,
+        initial: Any = None,
+        after_seq_id: int = 0,
+        before_seq_id: Optional[int] = None,
+    ) -> Any:
+        """replay / projection。
+
+        默认(``projection=None``):返回按 seq 升序的 RuntimeEvent 序列(replay)。
+        给定 ``projection(acc, event) -> acc``:自 ``initial`` 起 fold 全部事件,支持
+        增量 projection(以 ``after_seq_id`` 从某个 checkpoint 续投影)。
+        """
+        events = await self.list(session_id, after_seq_id=after_seq_id, before_seq_id=before_seq_id)
+        if projection is None:
+            return events
+        acc = initial
+        for event in events:
+            acc = projection(acc, event)
+        return acc
+
+
+__all__ = [
+    "RuntimeEventStore",
+    "runtime_event_to_session_event",
+    "session_event_to_runtime_event",
+]

ksadk/harness/__init__.py

@@ -0,0 +1,34 @@
+"""HarnessApp — 统一 Runtime 的可部署交付物 / composition root (goal-08)。"""
+
+from ksadk.harness.app import HarnessApp, HarnessCapabilities, HarnessPlugin
+from ksadk.harness.config import (
+    HarnessConfig,
+    HarnessConfigError,
+    McpToolSpec,
+    SandboxPolicy,
+)
+from ksadk.harness.reasoner import (
+    HarnessReasoner,
+    HarnessReasoningTurn,
+    HarnessToolCall,
+    LiteLLMHarnessReasoner,
+)
+from ksadk.harness.runner import YamlAgentRunner
+from ksadk.harness.sandbox import HarnessSandboxExecutor, SandboxPolicyDenied
+
+__all__ = [
+    "HarnessApp",
+    "HarnessCapabilities",
+    "HarnessConfig",
+    "HarnessConfigError",
+    "HarnessPlugin",
+    "HarnessReasoner",
+    "HarnessReasoningTurn",
+    "HarnessSandboxExecutor",
+    "HarnessToolCall",
+    "LiteLLMHarnessReasoner",
+    "McpToolSpec",
+    "SandboxPolicy",
+    "SandboxPolicyDenied",
+    "YamlAgentRunner",
+]

ksadk/harness/app.py

@@ -0,0 +1,278 @@
+"""HarnessApp — 统一 Runtime 的可部署交付物 / composition root。
+
+H2 §4.2:HarnessApp 是 composition root,**不包装复制 3000+ 行全局 app**——复用
+G0.1 ``create_runtime_app`` 装配;A2A、Responses、session、files 等**数据面** route
+group 装配,**控制面 action 不进入**;不 import 全局 ``base_app`` 再过滤复制路由。
+
+本层保持 AgentDraft 的最小字段面，但执行路径会运行真实模型推理、MCP transport 与
+Harness read-only sandbox policy。不含完整 AgentDraft v1 字段面、plugin 生态或 deploy 自动化。
+
+分层职责:yaml → RuntimeAdapter ``start(request)`` 的映射在**本层**;平台请求 →
+codex 配置(config.toml/AGENTS.md/mcp_servers)的翻译是 goal-09 CodexRuntime 的职责,
+不在本层做。
+"""
+
+from __future__ import annotations
+
+import logging
+import tempfile
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any, Callable, Optional, Protocol, Sequence
+
+from fastapi import FastAPI
+
+from ksadk.harness.config import HarnessConfig
+from ksadk.harness.reasoner import HarnessReasoner
+from ksadk.harness.runner import YamlAgentRunner
+from ksadk.runners.base_runner import BaseRunner
+from ksadk.runtime.adapter import RuntimeAdapter, StartRequest
+from ksadk.runtime.runner_adapter import RunnerRuntimeAdapter
+from ksadk.server.factory import RuntimeAppConfig, create_runtime_app
+from ksadk.server.routes.routers import GROUP_ROUTERS, load_route_modules
+
+logger = logging.getLogger(__name__)
+
+
+class HarnessPlugin(Protocol):
+    """基础 plugin host 的插件协议(骨架期最小钩子)。"""
+
+    def before_build(self, config: HarnessConfig) -> None:  # pragma: no cover - 协议
+        ...
+
+    def after_build(self, app: FastAPI, config: HarnessConfig) -> None:  # pragma: no cover
+        ...
+
+
+#: per-invocation override 允许覆盖的字段(最小子集内)。
+_OVERRIDEABLE = ("model", "prompt")
+
+
+@dataclass(frozen=True)
+class HarnessCapabilities:
+    """Protocol/data surfaces backed by this Harness composition."""
+
+    responses: bool = True
+    sessions: bool = True
+    files: bool = False
+    a2a: bool = False
+    agui: bool = False
+
+
+class HarnessApp:
+    """统一 Runtime 的 composition root(skeleton)。"""
+
+    def __init__(
+        self,
+        config: HarnessConfig,
+        *,
+        plugins: Sequence[HarnessPlugin] = (),
+        adapter_builder: Optional[Callable[[BaseRunner], RuntimeAdapter]] = None,
+        reasoner: HarnessReasoner | None = None,
+        workspace_root: str | Path | None = None,
+        a2a: Any | None = None,
+    ) -> None:
+        self._config = config
+        self._plugins = list(plugins)
+        self._adapter_builder = adapter_builder
+        self._reasoner = reasoner
+        self._a2a = a2a
+        self._owned_workspace: tempfile.TemporaryDirectory[str] | None
+        if workspace_root is None:
+            self._owned_workspace = tempfile.TemporaryDirectory(prefix="ksadk-harness-")
+            resolved_workspace: str | Path = self._owned_workspace.name
+        else:
+            self._owned_workspace = None
+            resolved_workspace = workspace_root
+        self._workspace_root = Path(resolved_workspace).resolve()
+        self._runner: BaseRunner | None = None
+        self._adapter: RuntimeAdapter | None = None
+        self._fastapi_app: FastAPI | None = None
+        self._capabilities = HarnessCapabilities(a2a=a2a is not None)
+        # Each Harness owns its session backend.  Route handlers may use this
+        # marker even when a host does not provide the optional session seam.
+        from ksadk.sessions import create_session_service
+
+        self._session_service = create_session_service(
+            backend="memory", project_dir=str(self._workspace_root)
+        )
+
+    @classmethod
+    def from_yaml(cls, path: str | Path, **kwargs: Any) -> "HarnessApp":
+        """从 yaml 装配(最小子集,超出明确报错)。"""
+        return cls(HarnessConfig.from_yaml(path), **kwargs)
+
+    @property
+    def config(self) -> HarnessConfig:
+        return self._config
+
+    # ---- override ----
+
+    def apply_overrides(self, overrides: Optional[dict[str, Any]]) -> HarnessConfig:
+        """per-invocation override:只允许最小子集内字段,超出报错(不静默忽略)。"""
+        if not overrides:
+            return self._config
+        unknown = set(overrides) - set(_OVERRIDEABLE)
+        if unknown:
+            raise ValueError(
+                f"override 仅允许 {list(_OVERRIDEABLE)}(最小子集),不支持: {sorted(unknown)}"
+            )
+        return replace(self._config, **overrides)
+
+    # ---- 组装 ----
+
+    def build_runner(self, overrides: Optional[dict[str, Any]] = None) -> BaseRunner:
+        if overrides is not None:
+            raise ValueError("build_runner 不接受 invocation override;请传给 start(request)")
+        if self._runner is None:
+            self._runner = self._build_runner(self._config)
+        return self._runner
+
+    def _build_runner(self, config: HarnessConfig) -> BaseRunner:
+        for plugin in self._plugins:
+            plugin.before_build(config)
+        if config.runtime == "codex":
+            # codex runtime:CodexRunner(经 ksadk web 已验证路径),detector stub 用 CODEX
+            from ksadk.detection.detector import FrameworkType
+            from ksadk.runners.codex_runner import CodexRunner
+
+            detection = type(
+                "D", (), {"name": config.model, "type": FrameworkType.CODEX}
+            )()
+            return CodexRunner(detection, str(self._workspace_root))
+        return YamlAgentRunner(
+            config,
+            reasoner=self._reasoner,
+            workspace_root=self._workspace_root,
+        )
+
+    def adapter(self, overrides: Optional[dict[str, Any]] = None) -> RuntimeAdapter:
+        """yaml → RuntimeAdapter(goal-07);start(request) 在此层映射。"""
+        if overrides is not None:
+            raise ValueError("adapter 不接受 invocation override;请传给 start(request)")
+        if self._adapter is not None:
+            return self._adapter
+        rt = "codex" if self._config.runtime == "codex" else "harness"
+
+        def _default_builder(runner: BaseRunner) -> RuntimeAdapter:
+            return RunnerRuntimeAdapter(runner, runtime_type=rt)
+
+        builder = self._adapter_builder or _default_builder
+        self._adapter = builder(self.build_runner())
+        return self._adapter
+
+    @property
+    def runner(self) -> BaseRunner:
+        """The one runner owned by this Harness composition root."""
+        return self.build_runner()
+
+    @property
+    def session_service(self) -> Any:
+        return self._session_service
+
+    @property
+    def capabilities(self) -> HarnessCapabilities:
+        return self._capabilities
+
+    def _route_groups(self) -> set[str]:
+        groups = {"health_meta", "models", "feedback", "tools", "ui_bootstrap"}
+        if self._capabilities.responses:
+            groups.update({"run", "openai_compat"})
+        if self._capabilities.sessions:
+            groups.update({"sessions", "sessions_adk_compat"})
+        if self._capabilities.files:
+            groups.add("workspace")
+        if self._capabilities.agui:
+            groups.add("agui")
+        return groups
+
+    def _request_with_overrides(
+        self, request: StartRequest, overrides: Optional[dict[str, Any]]
+    ) -> StartRequest:
+        metadata = dict(request.metadata or {})
+        changed = False
+        if request.model:
+            metadata["model_override"] = request.model
+            changed = True
+        request_prompt = request.config.get("prompt") or request.config.get("instructions")
+        if request_prompt is not None:
+            metadata["prompt_override"] = str(request_prompt)
+            changed = True
+        if overrides:
+            config = self.apply_overrides(overrides)
+            metadata["model_override"] = config.model
+            metadata["prompt_override"] = config.prompt
+            changed = True
+        if not changed:
+            return request
+        if hasattr(request, "model_copy"):
+            return request.model_copy(update={"metadata": metadata})
+        return request.copy(update={"metadata": metadata})
+
+    async def start(self, request: StartRequest, overrides: Optional[dict[str, Any]] = None):
+        """yaml → RuntimeAdapter.start(request)(本层映射)。"""
+        return await self.adapter().start(self._request_with_overrides(request, overrides))
+
+    def stream(self, handle: Any):
+        return self.adapter().stream(handle)
+
+    async def cancel(self, handle: Any):
+        return await self.adapter().cancel(handle)
+
+    async def resume(self, handle: Any, target: Any, payload: Any = None):
+        return await self.adapter().resume(handle, target, payload)
+
+    async def checkpoint(self, handle: Any):
+        return await self.adapter().checkpoint(handle)
+
+    async def close(self, handle: Any):
+        return await self.adapter().close(handle)
+
+    def _configure_routes(self, app: FastAPI, state: Any, groups: set[str]) -> None:
+        """Attach only route groups; never install integrated workspace/terminal routes."""
+        del state
+        load_route_modules()
+        ordered = sorted(group for group in groups if group != "health_meta")
+        if "health_meta" in groups:
+            ordered.append("health_meta")
+        for group in ordered:
+            router = GROUP_ROUTERS.get(group)
+            if router is not None:
+                app.include_router(router)
+
+    def build_app(self, overrides: Optional[dict[str, Any]] = None) -> FastAPI:
+        """装配可部署 app:复用 create_runtime_app,只挂数据面 route group(控制面不进)。"""
+        if overrides is not None:
+            # Overrides belong to StartRequest and must never create a second
+            # process-wide runner for the deployed app.
+            raise ValueError("build_app 不接受 invocation override;请传给 start(request)")
+        if self._fastapi_app is not None:
+            return self._fastapi_app
+        runner = self.build_runner()
+        app = create_runtime_app(
+            RuntimeAppConfig(
+                runner=runner,
+                runtime_type="codex" if self._config.runtime == "codex" else "harness",
+                route_groups=self._route_groups(),
+                a2a=self._a2a,
+                runtime_adapter=self.adapter() if self._a2a is not None else None,
+                session_backend_provider=lambda: {
+                    "Backend": "memory",
+                    "Shared": False,
+                    "ProductionSafe": False,
+                    "ContinuityDefault": "local_only",
+                },
+            ),
+            self._configure_routes,
+        )
+        app.state.runtime.runtime_adapter = self.adapter()
+        app.state.runtime.session_service = self._session_service
+        app.state.runtime.harness_capabilities = self._capabilities
+
+        for plugin in self._plugins:
+            plugin.after_build(app, self._config)
+        self._fastapi_app = app
+        return app
+
+
+__all__ = ["HarnessApp", "HarnessCapabilities", "HarnessPlugin"]