capability-runtime 0.1.0__py3-none-any.whl

capability_runtime/ui_events/session.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, AsyncIterator, Dict, Optional, Set
+
+from skills_runtime.core.contracts import AgentEvent
+
+from ..logging_utils import log_suppressed_exception
+from ..protocol.capability import CapabilityResult, CapabilityStatus
+from ..protocol.context import ExecutionContext
+from .projector import RuntimeUIEventProjector, _AgentCtx
+from .store import AfterIdExpiredError, RuntimeEventStore
+from .v1 import RuntimeEvent, StreamLevel
+
+
+@dataclass(frozen=True)
+class ResumeErrorInfo:
+    after_id: str
+    known_min_id: Optional[str]
+    known_max_id: Optional[str]
+
+
+class RuntimeUIEventsSession:
+    """
+    UI events 会话：一次 run 的事件投影与多订阅者消费。
+
+    目标：
+    - 不绑定任何 Web 框架；
+    - 支持 `rid/after_id` 断线续传（exclusive）；
+    - heartbeat 保活；
+    - terminal status 收敛：确保订阅侧能收到终态事件。
+    """
+
+    def __init__(
+        self,
+        *,
+        runtime: Any,
+        capability_id: str,
+        input: Dict[str, Any],
+        context: ExecutionContext,
+        level: StreamLevel,
+        store: RuntimeEventStore,
+        heartbeat_interval_s: float,
+        input_queue_maxsize: int = 4096,
+        subscriber_queue_maxsize: int = 1024,
+    ) -> None:
+        self._runtime = runtime
+        self._capability_id = str(capability_id)
+        self._input = dict(input or {})
+        self._context = context
+        self._level = level
+        self._store = store
+        self._heartbeat_interval_s = float(heartbeat_interval_s)
+        if int(input_queue_maxsize) <= 0:
+            raise ValueError("input_queue_maxsize must be > 0")
+        if int(subscriber_queue_maxsize) <= 0:
+            raise ValueError("subscriber_queue_maxsize must be > 0")
+        self._input_queue_maxsize = int(input_queue_maxsize)
+        self._subscriber_queue_maxsize = int(subscriber_queue_maxsize)
+
+        self._projector = RuntimeUIEventProjector(run_id=self._context.run_id, level=self._level)
+        self._in_q: asyncio.Queue = asyncio.Queue(maxsize=self._input_queue_maxsize)
+        self._subs: Set[asyncio.Queue] = set()
+        self._started = False
+        self._done = asyncio.Event()
+        self._runner_task: asyncio.Task[None] | None = None
+        self._session_task: asyncio.Task[None] | None = None
+        self._background_error: BaseException | None = None
+
+    @property
+    def run_id(self) -> str:
+        return self._context.run_id
+
+    @property
+    def store(self) -> RuntimeEventStore:
+        return self._store
+
+    def _emit_subscriber_lagged(self, *, q: asyncio.Queue) -> RuntimeEvent:
+        err = self._projector.error(
+            kind="subscriber_lagged",
+            message="subscriber queue overflow; policy=disconnect",
+            data={"queue_maxsize": int(getattr(q, "maxsize", 0) or 0), "policy": "disconnect"},
+        )
+        # 该错误是“订阅者局部诊断信号”，不进入 store；避免客户端误用其 rid 作为 after_id 续传游标。
+        return err.model_copy(update={"rid": None})
+
+    def _cut_off_subscriber(self, *, q: asyncio.Queue) -> None:
+        self._subs.discard(q)
+        try:
+            while True:
+                q.get_nowait()
+        except asyncio.QueueEmpty:
+            pass
+        try:
+            q.put_nowait(self._emit_subscriber_lagged(q=q))
+        except Exception as exc:
+            # fail-open：断开慢订阅者必须不影响主事件流
+            log_suppressed_exception(
+                context="cut_off_subscriber_emit_lagged",
+                exc=exc,
+                run_id=self._context.run_id if self._context else None,
+            )
+
+    def _publish_nowait(self, ev: RuntimeEvent) -> None:
+        self._store.append(ev)
+        for q in list(self._subs):
+            try:
+                q.put_nowait(ev)
+            except asyncio.QueueFull:
+                self._cut_off_subscriber(q=q)
+            except Exception as exc:
+                # fail-open：单个订阅者的异常不得影响主事件流
+                log_suppressed_exception(
+                    context="publish_to_subscriber",
+                    exc=exc,
+                    extra={"event_type": getattr(ev, "type", None)},
+                )
+
+    def _emit_resume_error(self, *, info: ResumeErrorInfo) -> RuntimeEvent:
+        msg = (
+            f"after_id expired or not found: {info.after_id!r} "
+            f"(available: {info.known_min_id!r}..{info.known_max_id!r})"
+        )
+        return self._projector.error(
+            kind="after_id_expired",
+            message=msg,
+            data={
+                "after_id": info.after_id,
+                "known_min_id": info.known_min_id,
+                "known_max_id": info.known_max_id,
+            },
+        )
+
+    def _remember_task_failure(self, task: asyncio.Task[Any]) -> None:
+        """提取后台任务异常，避免 fire-and-forget 把错误静默丢掉。"""
+
+        try:
+            exc = task.exception()
+        except asyncio.CancelledError:
+            return
+        if exc is not None and self._background_error is None:
+            self._background_error = exc
+
+    async def ensure_started(self) -> None:
+        if self._started:
+            return
+        self._started = True
+
+        def _tap(agent_ev: AgentEvent, tap_ctx: Dict[str, Any]) -> None:
+            try:
+                expected_run_id = self._context.run_id
+                ctx_run_id = tap_ctx.get("run_id")
+                if isinstance(ctx_run_id, str) and ctx_run_id != expected_run_id:
+                    return
+                ev_run_id = getattr(agent_ev, "run_id", None)
+                if isinstance(ev_run_id, str) and ev_run_id != expected_run_id:
+                    return
+                self._in_q.put_nowait(("agent_event", agent_ev, tap_ctx))
+            except asyncio.QueueFull:
+                # fail-open：旁路 tap 不得影响主流程；输入队列背压时丢弃旁路事件
+                pass
+            except Exception as exc:
+                # fail-open：旁路 tap 过滤/入队异常不得影响主流程
+                log_suppressed_exception(
+                    context="ui_events_tap",
+                    exc=exc,
+                    run_id=self._context.run_id if self._context else None,
+                    extra={"event_type": getattr(agent_ev, "type", None)},
+                )
+
+        self._runtime._register_agent_event_tap(_tap)
+
+        async def _runner() -> None:
+            try:
+                async for item in self._runtime.run_stream(self._capability_id, input=self._input, context=self._context):
+                    if isinstance(item, dict):
+                        await self._in_q.put(("workflow_event", item))
+                    elif isinstance(item, CapabilityResult):
+                        await self._in_q.put(("terminal", item))
+                        return
+                    else:
+                        continue
+                await self._in_q.put(("error", RuntimeError("run_stream ended without terminal CapabilityResult")))
+            except Exception as exc:
+                await self._in_q.put(("error", exc))
+
+        task = asyncio.create_task(_runner())
+        task.add_done_callback(self._remember_task_failure)
+        self._runner_task = task
+
+        async def _loop() -> None:
+            try:
+                for ev in self._projector.start():
+                    self._publish_nowait(ev)
+
+                done = False
+                while not done:
+                    try:
+                        item = await asyncio.wait_for(self._in_q.get(), timeout=self._heartbeat_interval_s)
+                    except asyncio.TimeoutError:
+                        if self._level != StreamLevel.LITE:
+                            self._publish_nowait(self._projector.heartbeat())
+                        continue
+
+                    kind = item[0]
+                    if kind == "agent_event":
+                        agent_ev, tap_ctx = item[1], item[2]
+                        agent_ctx = _AgentCtx(
+                            run_id=str(tap_ctx.get("run_id") or self._context.run_id),
+                            capability_id=str(tap_ctx.get("capability_id") or ""),
+                            workflow_id=str(tap_ctx.get("workflow_id")) if isinstance(tap_ctx.get("workflow_id"), str) else None,
+                            workflow_instance_id=str(tap_ctx.get("workflow_instance_id"))
+                            if isinstance(tap_ctx.get("workflow_instance_id"), str)
+                            else None,
+                            step_id=str(tap_ctx.get("step_id")) if isinstance(tap_ctx.get("step_id"), str) else None,
+                            branch_id=str(tap_ctx.get("branch_id")) if isinstance(tap_ctx.get("branch_id"), str) else None,
+                            wf_frames=list(tap_ctx.get("wf_frames")) if isinstance(tap_ctx.get("wf_frames"), list) else None,
+                        )
+                        for out_ev in self._projector.on_agent_event(agent_ev, ctx=agent_ctx):
+                            self._publish_nowait(out_ev)
+                    elif kind == "workflow_event":
+                        wf_ev = item[1]
+                        for out_ev in self._projector.on_workflow_event(wf_ev):
+                            self._publish_nowait(out_ev)
+                    elif kind == "terminal":
+                        terminal = item[1]
+                        for out_ev in self._projector.on_terminal(terminal):
+                            self._publish_nowait(out_ev)
+                        done = True
+                    elif kind == "error":
+                        exc = item[1]
+                        self._publish_nowait(self._projector.error(kind="runner_error", message=str(exc)))
+                        for out_ev in self._projector.on_terminal(CapabilityResult(status=CapabilityStatus.FAILED, error=str(exc))):
+                            self._publish_nowait(out_ev)
+                        done = True
+            finally:
+                self._done.set()
+                await task
+                self._runtime._unregister_agent_event_tap(_tap)
+
+        session_task = asyncio.create_task(_loop())
+        session_task.add_done_callback(self._remember_task_failure)
+        self._session_task = session_task
+
+    async def wait_done(self) -> None:
+        await self._done.wait()
+        if self._session_task is not None:
+            await self._session_task
+        if self._background_error is not None:
+            raise self._background_error
+
+    async def subscribe(self, *, after_id: Optional[str]) -> AsyncIterator[RuntimeEvent]:
+        await self.ensure_started()
+        q: asyncio.Queue = asyncio.Queue(maxsize=self._subscriber_queue_maxsize)
+        self._subs.add(q)
+        try:
+            try:
+                replay = list(self._store.read_after(after_id=after_id))
+            except AfterIdExpiredError as exc:
+                err = self._emit_resume_error(
+                    info=ResumeErrorInfo(after_id=exc.after_id, known_min_id=exc.min_rid, known_max_id=exc.max_rid)
+                )
+                yield err
+                return
+
+            last_seq = replay[-1].seq if replay else 0
+            for ev in replay:
+                yield ev
+                if ev.type == "run.status" and ev.data.get("status") != "running":
+                    return
+
+            while True:
+                if self._done.is_set() and q.empty():
+                    return
+                ev = await q.get()
+                if ev.type == "error" and ev.data.get("kind") == "subscriber_lagged":
+                    yield ev
+                    return
+                if ev.seq <= last_seq:
+                    continue
+                last_seq = ev.seq
+                yield ev
+                if ev.type == "run.status" and ev.data.get("status") != "running":
+                    return
+        finally:
+            self._subs.discard(q)
+
+    async def _ensure_started(self) -> None:
+        """兼容旧调用方；新代码应使用公开的 `ensure_started()`。"""
+
+        await self.ensure_started()

capability_runtime/ui_events/store.py

@@ -0,0 +1,127 @@
+"""
+Runtime UI Events：断线续传（rid/after_id）的最小 in-memory store。
+
+定位：
+- 提供最小可复用能力：append + read_after（exclusive）+ 过期诊断；
+- 不绑定任何 HTTP 框架或持久化实现；
+- run 级别隔离由调用方保证（通常一个 store 对应一个 run）。
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+import threading
+from typing import Deque, Dict, Iterable, Optional, Protocol
+
+from .v1 import RuntimeEvent
+
+
+class RuntimeEventStore(Protocol):
+    """
+    RuntimeEventStore：用于断线续传的最小 store 接口（可插拔）。
+
+    约束：
+    - `read_after` 为排他语义（exclusive：strictly after）
+    - after_id 过期/不在窗口内时，建议抛出 `AfterIdExpiredError`（可诊断）
+    """
+
+    @property
+    def min_rid(self) -> Optional[str]: ...
+
+    @property
+    def max_rid(self) -> Optional[str]: ...
+
+    def append(self, ev: RuntimeEvent) -> None: ...
+
+    def read_after(self, *, after_id: Optional[str]) -> Iterable[RuntimeEvent]: ...
+
+
+@dataclass(frozen=True)
+class AfterIdExpiredError(Exception):
+    """
+    after_id 不在可用窗口内（可能是裁剪过期，也可能是未知/非法游标）。
+
+    字段：
+    - after_id：请求的游标
+    - min_rid/max_rid：当前窗口内的可用范围（用于诊断与提示客户端策略）
+    """
+
+    after_id: str
+    min_rid: Optional[str]
+    max_rid: Optional[str]
+
+    def __str__(self) -> str:
+        return f"after_id expired or not found: {self.after_id!r} (available: {self.min_rid!r}..{self.max_rid!r})"
+
+
+class InMemoryRuntimeEventStore(RuntimeEventStore):
+    """
+    in-memory 事件存储（ring buffer）。
+
+    约束：
+    - `read_after` 为排他语义（exclusive：strictly after）
+    - 当 after_id 不在窗口内时抛出 AfterIdExpiredError（可诊断）
+    """
+
+    def __init__(self, *, max_events: int = 10_000) -> None:
+        if max_events <= 0:
+            raise ValueError("max_events must be > 0")
+        self._max_events = int(max_events)
+        self._events: Deque[RuntimeEvent] = deque(maxlen=self._max_events)
+        self._rid_to_pos: Dict[str, int] = {}
+        self._start_pos = 0
+        self._lock = threading.Lock()
+
+    @property
+    def min_rid(self) -> Optional[str]:
+        with self._lock:
+            if not self._events:
+                return None
+            return self._events[0].rid
+
+    @property
+    def max_rid(self) -> Optional[str]:
+        with self._lock:
+            if not self._events:
+                return None
+            return self._events[-1].rid
+
+    def append(self, ev: RuntimeEvent) -> None:
+        if ev.rid is None:
+            raise ValueError("RuntimeEvent.rid is required for resume store")
+        with self._lock:
+            if len(self._events) == self._max_events:
+                evicted = self._events.popleft()
+                if evicted.rid is not None:
+                    self._rid_to_pos.pop(evicted.rid, None)
+                self._start_pos += 1
+            pos = self._start_pos + len(self._events)
+            self._events.append(ev)
+            self._rid_to_pos[ev.rid] = pos
+
+    def read_after(self, *, after_id: Optional[str]) -> Iterable[RuntimeEvent]:
+        """
+        读取 after_id 之后的事件（exclusive）。
+
+        参数：
+        - after_id：续传游标；None 表示从头读取当前窗口
+        """
+
+        with self._lock:
+            snapshot = list(self._events)
+            min_rid = snapshot[0].rid if snapshot else None
+            max_rid = snapshot[-1].rid if snapshot else None
+            if after_id is None:
+                return snapshot
+            if not snapshot:
+                return []
+
+            pos = self._rid_to_pos.get(str(after_id))
+            if pos is None:
+                raise AfterIdExpiredError(after_id=str(after_id), min_rid=min_rid, max_rid=max_rid)
+
+            idx = pos - self._start_pos
+            if idx < 0 or idx >= len(snapshot):
+                raise AfterIdExpiredError(after_id=str(after_id), min_rid=min_rid, max_rid=max_rid)
+            return snapshot[idx + 1 :]

capability_runtime/ui_events/transport.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+"""
+Runtime UI Events：通用传输适配（JSON Lines / SSE 子集）。
+
+定位：
+- 不绑定任何 Web 框架；
+- 只负责 framing（把 RuntimeEvent 转成可流式发送的文本 chunk）。
+"""
+
+import json
+
+from .v1 import RuntimeEvent
+
+
+def encode_json_line(ev: RuntimeEvent, *, prefix_data: bool = False) -> str:
+    """
+    将单条 RuntimeEvent 编码为可流式发送的文本。
+
+    参数：
+    - ev：RuntimeEvent
+    - prefix_data：是否使用 `data: ` 前缀（SSE 子集兼容）
+
+    返回：
+    - JSONL：`<json>\\n`
+    - SSE 子集：`data: <json>\\n\\n`
+    """
+
+    payload = json.dumps(ev.model_dump(by_alias=True), ensure_ascii=False, separators=(",", ":"))
+    if prefix_data:
+        return f"data: {payload}\n\n"
+    return payload + "\n"
+

capability_runtime/ui_events/v1.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+"""
+Runtime UI Events v1（协议模型）。
+
+定位：
+- UI events 是“可观测/产品化投影层”，不是审计真相源；
+- 真相源仍为 WAL/events/tool evidence → NodeReport；
+- UI events 将（上游 `AgentEvent`、workflow 轻量事件、终态 `CapabilityResult`）投影为统一的 RuntimeEvent 信封；
+- 本模块仅定义 v1 的稳定信封字段与最小结构约束。
+"""
+
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class StreamLevel(str, Enum):
+    """事件输出层级。"""
+
+    LITE = "lite"
+    UI = "ui"
+    RAW = "raw"
+
+
+class PathSegment(BaseModel):
+    """PathSegment（图投影路径段）。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    kind: str = Field(min_length=1)
+    id: str = Field(min_length=1)
+    # v1 加法演进：用于多实例/嵌套消歧与展示（不要求每条事件都提供）
+    instance_id: Optional[str] = None
+    # `ref` 用于携带“逻辑身份”（例如 workflow spec id / capability id / tool name），避免 id 变为 opaque 后 UI 无法展示。
+    # 约束：保持通用性，只提供 kind/id 两个维度。
+    ref: Optional[Dict[str, str]] = None
+
+
+class Evidence(BaseModel):
+    """证据指针：用于回到 WAL/NodeReport/tool evidence 真相源。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    events_path: Optional[str] = None
+    call_id: Optional[str] = None
+    artifact_path: Optional[str] = None
+    node_report_schema: Optional[str] = None
+
+
+class RuntimeEvent(BaseModel):
+    """
+    RuntimeEvent v1：统一事件信封（Envelope）。
+
+    约束：
+    - `schema` 固定为 `capability-runtime.runtime_event.v1`
+    - `seq` 在单 run 内单调递增
+    - `rid` 为传输层游标（续传用），可与 `seq` 等价但语义不同
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    schema_id: str = Field(min_length=1, alias="schema")
+    type: str = Field(min_length=1)
+    run_id: str = Field(min_length=1)
+
+    seq: int = Field(ge=0)
+    ts_ms: int = Field(ge=0)
+    level: StreamLevel
+
+    path: List[PathSegment] = Field(default_factory=list)
+    data: Dict[str, Any] = Field(default_factory=dict)
+
+    rid: Optional[str] = None
+    evidence: Optional[Evidence] = None