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

ksadk/harness/hooks.py

@@ -0,0 +1,259 @@
+# ksadk/harness/hooks.py
+"""G5 Provider 级扩展拦截面：四钩子协议与执行器（spec §5.2）。
+
+纪律：
+- 钩子按注册顺序同步 await；单钩子异常或协议违约（链式方法返回非预期类型）
+  → 注入的 event_fn 发 ``policy.decision``（四钩子一律可见降级，无开关；
+  payload 满足 POLICY_DECISION 必填键契约：action="hook_failed"、reason=摘要，
+  并附 outcome/hook_index/method/error 诊断键），该钩子输出降级丢弃、链式主值
+  回退到上一有效值，其余钩子独立执行——可见降级，不静默吞。event_fn 上报路径
+  自身失败亦被吞（stderr 记录），不得穿出 run_hooks 中止钩子链。
+- 钩子不获得 approval 绕过权、不获得沙箱豁免；on_provider_request 返回中
+  model 键的修改由调用方（引擎）忽略。
+- payload 键契约：on_context → {"messages": list[dict]}；
+  on_provider_request → {"model": str, "messages": list[dict]}；
+  on_provider_response → {"model": str, "usage": dict}（只读）；
+  on_tool_result → {"call": {call_id,name,arguments}, "result": {content: str}}。
+- 已知限制（provider 钩子的执行边界）：压缩/规划期模型调用不经
+  on_provider_request/on_provider_response（prepare_context 在建图前、
+  _before_model 设置活跃 Run 之前发生，钩子按「无可归属 Run」跳过 + stderr）；
+  recover_model_overflow 路径经钩子（发生在 reason 节点内部）。降级事件先入
+  引擎缓冲、由模型调用节点统一 flush，避免 mid-call engine._event 破坏
+  run.seq 与 loop seq_start 本地计数的对齐（详见 hooked_reasoner 模块 docstring）。
+- on_context 的降级不经引擎缓冲：prepare_context / recover_model_overflow 的
+  钩子调用发生在模型调用回合之外（预图调用或 reason 节点内压缩路径），
+  policy.decision 直接经管线 _hook_event 追加 run.events（seq 由引擎 _event
+  推进，不与 loop 本地计数冲突），是 seq 安全的特例。
+- 并行工具批次内，多个 tool call 各自的 on_tool_result 钩子链按链内注册顺序
+  交错执行（按批次并发调度），不保证全局串行；钩子实现不得依赖跨 call 的
+  全局执行顺序。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from copy import deepcopy
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Callable, Protocol
+
+from ksadk.harness.events import EventType
+
+
+@dataclass(frozen=True)
+class RunContext:
+    run_id: str
+    agent_id: str
+    user_id: str
+    session_id: str
+
+
+class HookType(str, Enum):
+    """G26 类型分档（§8 反向清单：不含 agent——hook 内起 agent拒绝）。"""
+
+    COMMAND = "command"   # 执行外部命令
+    HTTP = "http"         # HTTP 调用
+    PROMPT = "prompt"     # 注入/改写 prompt
+
+
+@dataclass(frozen=True)
+class HookDeclaration:
+    """G26 钩子声明：钩子对象 + 类型 + blocking 标记。
+
+    裁决2：所有类型默认 non_blocking；blocking 只由显式 ``blocking=True`` 决定
+    （默认不阻断主循环，对齐 §22「崩溃/超时一律降级为可见 non_blocking_error」）。
+    """
+
+    hook: "ProviderHook"
+    type: HookType = HookType.PROMPT
+    blocking: bool = False
+
+
+def _as_declaration(item: Any) -> HookDeclaration:
+    """向后兼容：裸 ProviderHook 自动包成默认 HookDeclaration。"""
+    if isinstance(item, HookDeclaration):
+        return item
+    return HookDeclaration(hook=item)
+
+
+class ProviderHook(Protocol):
+    async def on_context(
+        self, run: RunContext, messages: list[dict[str, Any]]
+    ) -> list[dict[str, Any]]: ...
+
+    async def on_provider_request(
+        self, run: RunContext, request: dict[str, Any]
+    ) -> dict[str, Any]: ...
+
+    async def on_provider_response(
+        self, run: RunContext, response_meta: dict[str, Any]
+    ) -> None: ...
+
+    async def on_tool_result(
+        self, run: RunContext, call: dict[str, Any], result: dict[str, Any]
+    ) -> dict[str, Any]: ...
+
+
+async def run_hooks(
+    hooks: tuple[Any, ...],
+    method_name: str,
+    run: RunContext,
+    event_fn: Callable[..., Any],
+    *,
+    payload: dict[str, Any],
+) -> Any:
+    """按注册顺序执行钩子；单钩子异常可见降级（spec §5.2）。
+
+    四钩子一律可见降级（无 degradable 开关）：单钩子异常或协议违约（链式方法
+    返回非预期类型）都发 ``policy.decision(action="hook_failed")`` 后钩子链继续
+    （违约输出丢弃，沿用上一有效值——与调用侧末态守卫同语义）。
+    on_provider_response 返回 None（只读观测）；其余方法返回链式处理的
+    payload 主值（on_context/on_tool_result → 列表/dict，
+    on_provider_request → dict）。method_name 非四钩子之一抛 ValueError。
+    """
+    if method_name not in (
+        "on_context",
+        "on_provider_request",
+        "on_provider_response",
+        "on_tool_result",
+    ):
+        raise ValueError(f"unknown hook method: {method_name!r}")
+    # 链式方法的期望返回类型（on_provider_response 只读、不参与链式传递）。
+    chained_types: dict[str, type] = {
+        "on_context": list,
+        "on_tool_result": dict,
+        "on_provider_request": dict,
+    }
+    value: Any = None
+    if method_name == "on_context":
+        value = deepcopy(list(payload["messages"]))
+    elif method_name == "on_tool_result":
+        value = deepcopy(dict(payload["result"]))
+    elif method_name == "on_provider_request":
+        value = deepcopy(dict(payload))
+    declarations = [_as_declaration(h) for h in hooks]
+    for index, decl in enumerate(declarations):
+        hook = decl.hook
+        method = getattr(hook, method_name, None)
+        if method is None:
+            continue
+        # ProviderHook 是 Protocol：其桩方法（body 为 ...）会被子类继承，使
+        # getattr 永不为 None。只实现部分钩子的观察者（例如仅
+        # on_provider_response）若被当成本方法调用会返回 None，从而把链式主值
+        # 清空（脱敏/改写被静默丢弃）。未覆写协议的桩方法必须跳过。
+        if getattr(method, "__func__", None) is getattr(ProviderHook, method_name, None):
+            continue
+        try:
+            # A hook receives a detached working value. Only a valid return
+            # is committed to the chain; exceptions/protocol failures cannot
+            # corrupt the preceding value through nested mutable aliases.
+            if method_name == "on_context":
+                candidate = await method(run, deepcopy(list(value or [])))
+            elif method_name == "on_tool_result":
+                candidate = await method(
+                    run, deepcopy(dict(payload["call"])), deepcopy(dict(value or {}))
+                )
+            elif method_name == "on_provider_request":
+                candidate = await method(run, deepcopy(dict(value or {})))
+            else:  # on_provider_response：只读观测
+                await method(run, deepcopy(dict(payload)))
+                continue
+            if isinstance(candidate, chained_types[method_name]):
+                # A successful hook may retain its returned object. Do not let
+                # a later/background mutation rewrite the accepted chain.
+                candidate = deepcopy(candidate)
+        except asyncio.CancelledError:
+            # G26 四态：被 Run 取消 → cancelled（不吞取消信号，原样 raise，仅记降级）
+            _report_degradation(
+                event_fn,
+                run,
+                method_name=method_name,
+                hook_index=index,
+                reason=f"{method_name}[{index}]: cancelled",
+                error="hook execution cancelled",
+                hook_outcome="cancelled",
+                hook_type=decl.type.value,
+            )
+            raise
+        except Exception as exc:  # noqa: BLE001 - 降级可见，不中断
+            outcome = "blocking" if decl.blocking else "non_blocking_error"
+            _report_degradation(
+                event_fn,
+                run,
+                method_name=method_name,
+                hook_index=index,
+                reason=f"{method_name}[{index}]: {str(exc)[:200]}",
+                error=str(exc)[:256],
+                hook_outcome=outcome,
+                hook_type=decl.type.value,
+            )
+            continue
+        expected = chained_types[method_name]
+        if not isinstance(candidate, expected):
+            # 协议违约（链式方法返回非预期类型）：若继续向下一钩子传递，字符串
+            # 会被 list()/dict() 按字符/键拆开，污染后续钩子的输入。丢弃该钩子
+            # 输出、沿用上一有效值后继续——与 on_context 末态守卫同语义，可见
+            # 降级不静默。协议违约一律 non_blocking_error（不阻断）。
+            code = "non-list" if expected is list else "non-dict"
+            _report_degradation(
+                event_fn,
+                run,
+                method_name=method_name,
+                hook_index=index,
+                reason=(
+                    f"{method_name}[{index}]: protocol violation ({code}); "
+                    "previous chain value kept"
+                ),
+                error=f"{method_name} 返回 {type(candidate).__name__}，期望 {expected.__name__}",
+                hook_outcome="non_blocking_error",
+                hook_type=decl.type.value,
+            )
+            continue
+        value = candidate
+    return value
+
+
+def _report_degradation(
+    event_fn: Callable[..., Any],
+    run: RunContext,
+    *,
+    method_name: str,
+    hook_index: int,
+    reason: str,
+    error: str,
+    hook_outcome: str = "non_blocking_error",
+    hook_type: str = "prompt",
+) -> None:
+    """发可见降级事件；上报路径自身失败被吞（stderr），不穿出 run_hooks。
+
+    G26 四态：``hook_outcome`` ∈ {blocking, non_blocking_error, cancelled}
+    （success 不发事件）。``hook_type`` 记分档（command/http/prompt）。
+    """
+    try:
+        event_fn(
+            run,
+            EventType.POLICY_DECISION,
+            {
+                # POLICY_DECISION 必填键契约（events.py）
+                "action": "hook_failed",
+                "reason": reason,
+                # 诊断附加键
+                "outcome": "hook_failed",
+                "hook_outcome": hook_outcome,
+                "hook_type": hook_type,
+                "hook_index": hook_index,
+                "method": method_name,
+                "error": error,
+            },
+        )
+    except Exception as report_exc:  # noqa: BLE001 - 上报失败不穿出
+        print(
+            f"[ksadk.harness.hooks] event_fn failed while reporting "
+            f"hook degradation ({method_name}[{hook_index}]): "
+            f"{report_exc!r}",
+            file=sys.stderr,
+        )
+
+
+__all__ = ["ProviderHook", "RunContext", "run_hooks", "HookType", "HookDeclaration"]

ksadk/harness/insights.py

@@ -0,0 +1,210 @@
+"""Harness 长任务洞察 API（长任务方案 §3.2 / P3 补强：Studio 实际消费）。
+
+Studio/控制面此前只有 SDK 查询函数（:mod:`ksadk.harness.observability`），
+没有真实 HTTP 消费端。本模块补上：
+
+- :class:`HarnessInsightsRegistry`：进程内 Run 事件登记处。引擎
+  （``ManagedLangGraphEngine(event_sink=...)``）把每个事件登记进来，
+  API 层按 ``run_id`` / ``session_id`` 查询；
+- :func:`build_insights_router`：FastAPI 路由，输出纯 dict 投影
+  （context-trace / token-report / compaction-trace）——Studio 不解析
+  Harness 私有对象，直接消费 JSON；
+- Capability Health Snapshot：统一查询 MCP / Skill / Sandbox 健康状态。
+
+输出边界：事件经 :func:`ksadk.harness.events.project_v2` 整流为 v2 信封
+（长任务方案 §8），再交给 observability 投影函数。
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import defaultdict
+from typing import Any, Callable
+
+from fastapi import APIRouter, FastAPI, HTTPException
+
+from ksadk.harness.context_tuning import context_tuning_recommendations
+from ksadk.harness.events import RuntimeEvent, project_v2
+from ksadk.harness.observability import (
+    capability_health,
+    compaction_trace,
+    context_inspection,
+    context_trace,
+    token_report,
+)
+from ksadk.harness.readiness import runtime_readiness
+from ksadk.harness.spec import HarnessSpec
+
+#: 引擎事件回调类型：``event_sink(session_id, run_id, event)``。
+EventSink = Callable[[str, str, RuntimeEvent], None]
+
+
+class HarnessInsightsRegistry:
+    """Run 事件的进程内登记处（引擎 → API 的桥）。
+
+    线程安全；事件保留在内存中，按 run_id / session_id 索引。生产部署
+    可替换为持久化实现（接口不变）。
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._by_run: dict[str, list[RuntimeEvent]] = defaultdict(list)
+        self._by_session: dict[str, list[RuntimeEvent]] = defaultdict(list)
+        self._spec_by_run: dict[str, HarnessSpec] = {}
+        self._run_ids_by_session: dict[str, list[str]] = defaultdict(list)
+
+    def register_spec(self, session_id: str, run_id: str, spec: HarnessSpec) -> None:
+        """登记 Run 实际使用的公开 HarnessSpec（不接受 Engine 私有对象）。"""
+        with self._lock:
+            self._spec_by_run[run_id] = spec
+            if run_id not in self._run_ids_by_session[session_id]:
+                self._run_ids_by_session[session_id].append(run_id)
+
+    def record(self, session_id: str, run_id: str, event: RuntimeEvent) -> None:
+        """登记一个事件（引擎 event_sink 以位置参数调用）。"""
+        with self._lock:
+            self._by_run[run_id].append(event)
+            self._by_session[session_id].append(event)
+
+    def sink(self, *, session_id: str, run_id: str) -> EventSink:
+        """构造绑定到指定 Run 的事件回调（传给引擎 ``event_sink``）。"""
+
+        def _sink(_session_id: str, _run_id: str, event: RuntimeEvent) -> None:
+            self.record(session_id=session_id, run_id=run_id, event=event)
+
+        return _sink
+
+    def run_events(self, run_id: str) -> list[RuntimeEvent]:
+        """整流为 v2 信封后返回（平台输出边界）。"""
+        with self._lock:
+            events = list(self._by_run.get(run_id) or [])
+        return project_v2(events)
+
+    def run_ids(self) -> list[str]:
+        """已登记事件的 run_id 列表（调试/管理面用）。"""
+        with self._lock:
+            return list(self._by_run)
+
+    def session_events(self, session_id: str) -> list[RuntimeEvent]:
+        with self._lock:
+            events = list(self._by_session.get(session_id) or [])
+        return project_v2(events)
+
+    def run_readiness(self, run_id: str) -> dict[str, Any] | None:
+        with self._lock:
+            spec = self._spec_by_run.get(run_id)
+        if spec is None:
+            return None
+        return runtime_readiness(spec, self.run_events(run_id))
+
+    def session_readiness(self, session_id: str) -> dict[str, Any] | None:
+        with self._lock:
+            run_ids = list(self._run_ids_by_session.get(session_id) or ())
+        if not run_ids:
+            return None
+        return self.run_readiness(run_ids[-1])
+
+
+def build_insights_router(registry: HarnessInsightsRegistry) -> APIRouter:
+    """构建 /insights 路由（挂到 HarnessApp / 独立 FastAPI 均可）。"""
+
+    router = APIRouter(prefix="/insights", tags=["harness-insights"])
+
+    def _events_or_404(run_id: str) -> list[RuntimeEvent]:
+        events = registry.run_events(run_id)
+        if not events:
+            raise HTTPException(status_code=404, detail=f"unknown run: {run_id}")
+        return events
+
+    @router.get("/runs/{run_id}/context-trace")
+    async def get_context_trace(run_id: str) -> dict[str, Any]:
+        """每次模型调用的 Manifest 快照（Planned/Projected/Actual 闭环）。"""
+        return {"items": context_trace(_events_or_404(run_id))}
+
+    @router.get("/runs/{run_id}/token-report")
+    async def get_token_report(run_id: str) -> dict[str, Any]:
+        """单 Run 的 Token 闭环汇总（门禁 / 计费对账输入）。"""
+        return token_report(_events_or_404(run_id))
+
+    @router.get("/runs/{run_id}/context-inspection")
+    async def get_context_inspection(run_id: str) -> dict[str, Any]:
+        """Studio 单页 Context 检查视图（不含 Prompt/Memory/Tool 正文）。"""
+        return context_inspection(_events_or_404(run_id))
+
+    @router.get("/runs/{run_id}/context-recommendations")
+    async def get_context_recommendations(run_id: str) -> dict[str, Any]:
+        """基于真实 Run 指标给出只读调优建议，不自动修改线上策略。"""
+        return context_tuning_recommendations(_events_or_404(run_id))
+
+    @router.get("/runs/{run_id}/compaction-trace")
+    async def get_compaction_trace(run_id: str) -> dict[str, Any]:
+        """压缩历史（前后 Token、触发原因、质量校验、Memory Flush 候选）。"""
+        return {"items": compaction_trace(_events_or_404(run_id))}
+
+    @router.get("/runs/{run_id}/capability-health")
+    async def get_capability_health(run_id: str) -> dict[str, Any]:
+        """Run 级 MCP / Skill / Sandbox 健康快照。"""
+        return capability_health(_events_or_404(run_id))
+
+    @router.get("/runs/{run_id}/runtime-readiness")
+    async def get_runtime_readiness(run_id: str) -> dict[str, Any]:
+        """Run 使用的 Spec + smoke 观测 → ready/warning/blocked。"""
+        report = registry.run_readiness(run_id)
+        if report is None:
+            raise HTTPException(status_code=404, detail=f"unknown run spec: {run_id}")
+        return report
+
+    @router.get("/sessions/{session_id}/token-report")
+    async def get_session_token_report(session_id: str) -> dict[str, Any]:
+        """会话级 Token 闭环汇总（跨 Run 聚合）。"""
+        events = registry.session_events(session_id)
+        if not events:
+            raise HTTPException(status_code=404, detail=f"unknown session: {session_id}")
+        return token_report(events)
+
+    @router.get("/sessions/{session_id}/context-inspection")
+    async def get_session_context_inspection(session_id: str) -> dict[str, Any]:
+        """会话级 Context 检查视图（跨 Run 聚合）。"""
+        events = registry.session_events(session_id)
+        if not events:
+            raise HTTPException(status_code=404, detail=f"unknown session: {session_id}")
+        return context_inspection(events)
+
+    @router.get("/sessions/{session_id}/context-recommendations")
+    async def get_session_context_recommendations(session_id: str) -> dict[str, Any]:
+        """跨 Run 聚合的会话级 Context 调优建议。"""
+        events = registry.session_events(session_id)
+        if not events:
+            raise HTTPException(status_code=404, detail=f"unknown session: {session_id}")
+        return context_tuning_recommendations(events)
+
+    @router.get("/sessions/{session_id}/capability-health")
+    async def get_session_capability_health(session_id: str) -> dict[str, Any]:
+        """会话级最新健康快照（跨 Run 按事件时序投影）。"""
+        events = registry.session_events(session_id)
+        if not events:
+            raise HTTPException(status_code=404, detail=f"unknown session: {session_id}")
+        return capability_health(events)
+
+    @router.get("/sessions/{session_id}/runtime-readiness")
+    async def get_session_runtime_readiness(session_id: str) -> dict[str, Any]:
+        """会话最近一次 Run 的运行就绪度。"""
+        report = registry.session_readiness(session_id)
+        if report is None:
+            raise HTTPException(status_code=404, detail=f"unknown session spec: {session_id}")
+        return report
+
+    return router
+
+
+def mount_insights(app: FastAPI, registry: HarnessInsightsRegistry) -> None:
+    """把 insights 路由挂到已有 FastAPI 应用。"""
+    app.include_router(build_insights_router(registry))
+
+
+__all__ = [
+    "EventSink",
+    "HarnessInsightsRegistry",
+    "build_insights_router",
+    "mount_insights",
+]