capability-runtime 0.1.0__py3-none-any.whl

capability_runtime/host_toolkit/resume.py

@@ -0,0 +1,317 @@
+"""
+Resume / 续跑辅助工具（可选）。
+
+定位：
+- 提供“从 events.jsonl 回放得到的最小 resume 状态”的工具化入口；
+- 默认用于摘要/诊断（例如：恢复 approvals cache、生成 resume summary）；
+- 不强制把 WAL replay 作为下一轮 prompt 的唯一 history 真相源（真相源仍由宿主持久化的 TurnDelta 决定）。
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Iterable, List, Optional, Union
+
+from pydantic import BaseModel, ConfigDict
+
+from skills_runtime.core.contracts import AgentEvent
+from skills_runtime.state.replay import ResumeReplayState, rebuild_resume_replay_state
+
+
+def load_agent_events_from_locator(
+    *,
+    events_path: Union[Path, str],
+    wal_backend: Any | None = None,
+) -> List[AgentEvent]:
+    """
+    从 locator 加载 AgentEvent 列表（用于回放/诊断）。
+
+    参数：
+    - events_path：WAL 路径或 locator（本仓对外字段名为 `events_path`；上游 `skills-runtime-sdk>=1.0` 可能为 `wal_locator`）
+    - wal_backend：可选 WAL backend；当 locator 为 `wal://...` 时必须提供
+
+    返回：
+    - AgentEvent 列表（按文件顺序）
+    """
+
+    loc = str(events_path)
+    if loc.startswith("wal://"):
+        if wal_backend is None:
+            raise ValueError("wal_backend is required for wal locator")
+        read_events = getattr(wal_backend, "read_events", None)
+        if callable(read_events):
+            return _coerce_agent_events(read_events(loc))
+        read_text = getattr(wal_backend, "read_text", None)
+        if callable(read_text):
+            raw = read_text(loc)
+            return _parse_agent_events_jsonl(raw)
+        raise TypeError("wal_backend does not support wal locator reads")
+
+    # best-effort：允许 filesystem locator 追加 `#run_id=...` 等片段；文件读取仅使用其路径部分。
+    if "#" in loc:
+        loc = loc.split("#", 1)[0]
+
+    raw = Path(loc).read_text(encoding="utf-8")
+    return _parse_agent_events_jsonl(raw)
+
+
+def load_agent_events_from_jsonl(
+    *,
+    events_path: Union[Path, str],
+    wal_backend: Any | None = None,
+) -> List[AgentEvent]:
+    """
+    兼容别名：保留旧函数名，实际委托到 locator 读取逻辑。
+    """
+
+    return load_agent_events_from_locator(events_path=events_path, wal_backend=wal_backend)
+
+
+class ResumeReplaySummary(BaseModel):
+    """
+    resume replay 的最小摘要（默认用于诊断/观测，不包含 tool 输出明文）。
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    events_count: int
+    last_terminal_type: Optional[str] = None
+    approvals: dict
+    tool_calls: "ReplayToolCallDigest"
+
+
+class ReplayToolCallDigest(BaseModel):
+    """replay / resume 所需的最小 tool call 摘要。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    requested_count: int
+    finished_count: int
+    pending_count: int
+    latest_pending_call_ids: list[str]
+    latest_tool_calls: list[dict]
+
+
+class HostResumeState(BaseModel):
+    """
+    宿主续跑状态摘要。
+
+    字段说明：
+    - `run_id`：本轮运行 ID
+    - `approvals`：最小审批统计
+    - `last_terminal_type`：最近终态事件类型
+    - `waiting_approval_key`：尚未决议的审批键
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    run_id: str
+    approvals: dict
+    last_terminal_type: Optional[str] = None
+    waiting_approval_key: Optional[str] = None
+    tool_calls: ReplayToolCallDigest
+
+
+def build_resume_replay_summary(
+    *,
+    events: List[AgentEvent] | None = None,
+    events_path: Union[Path, str, None] = None,
+    wal_backend: Any | None = None,
+) -> tuple[ResumeReplayState, ResumeReplaySummary]:
+    """
+    基于 events 回放得到 resume state，并生成诊断摘要。
+
+    参数：
+    - events：可选 AgentEvent 列表
+    - events_path：可选 locator；当未直接提供 events 时用于加载事件
+    - wal_backend：可选 WAL backend；当 events_path 为 `wal://...` 时透传给 locator 读取
+
+    返回：
+    - (ResumeReplayState, ResumeReplaySummary)
+    """
+
+    events = _resolve_agent_events(events=events, events_path=events_path, wal_backend=wal_backend)
+    st = rebuild_resume_replay_state(events)
+    tool_calls = _build_replay_tool_call_digest(events)
+
+    last_terminal_type = None
+    for ev in reversed(events):
+        if ev.type in ("run_completed", "run_failed", "run_cancelled"):
+            last_terminal_type = ev.type
+            break
+
+    summary = ResumeReplaySummary(
+        events_count=len(events),
+        last_terminal_type=last_terminal_type,
+        approvals={
+            "approved_for_session_keys_count": len(st.approved_for_session_keys),
+            "denied_approvals_by_key_count": len(st.denied_approvals_by_key),
+        },
+        tool_calls=tool_calls,
+    )
+    return st, summary
+
+
+def build_host_resume_state(
+    *,
+    events: List[AgentEvent] | None = None,
+    events_path: Union[Path, str, None] = None,
+    wal_backend: Any | None = None,
+) -> HostResumeState:
+    """
+    基于 events 回放得到面向宿主的续跑状态。
+
+    参数：
+    - events：可选 AgentEvent 列表
+    - events_path：可选 locator；当未直接提供 events 时用于加载事件
+    - wal_backend：可选 WAL backend；当 events_path 为 `wal://...` 时透传给 locator 读取
+
+    返回：
+    - HostResumeState（不暴露 tool 输出明文）
+    """
+
+    events = _resolve_agent_events(events=events, events_path=events_path, wal_backend=wal_backend)
+    st, summary = build_resume_replay_summary(events=events)
+    requested_keys: List[str] = []
+    resolved_keys: set[str] = set()
+    run_id = ""
+
+    for ev in events:
+        if not run_id and isinstance(ev.run_id, str):
+            run_id = ev.run_id
+        approval_key = ev.payload.get("approval_key")
+        if not isinstance(approval_key, str) or not approval_key.strip():
+            continue
+        approval_key = approval_key.strip()
+        if ev.type == "approval_requested":
+            requested_keys.append(approval_key)
+        elif ev.type == "approval_decided":
+            resolved_keys.add(approval_key)
+
+    waiting_approval_key = None
+    for approval_key in reversed(requested_keys):
+        if approval_key not in resolved_keys:
+            waiting_approval_key = approval_key
+            break
+
+    return HostResumeState(
+        run_id=run_id,
+        approvals={
+            **summary.approvals,
+            "pending_approval_keys_count": len([key for key in requested_keys if key not in resolved_keys]),
+        },
+        last_terminal_type=summary.last_terminal_type,
+        waiting_approval_key=waiting_approval_key,
+        tool_calls=summary.tool_calls,
+    )
+
+
+def _events_after_last_run_started(events: List[AgentEvent]) -> List[AgentEvent]:
+    """只消费最近一次 run_started 之后的事件片段，与上游 replay 口径保持一致。"""
+
+    last_idx = -1
+    for i, ev in enumerate(events):
+        if ev.type == "run_started":
+            last_idx = i
+    if last_idx < 0:
+        return list(events)
+    return list(events[last_idx + 1 :])
+
+
+def _resolve_agent_events(
+    *,
+    events: List[AgentEvent] | None,
+    events_path: Union[Path, str, None],
+    wal_backend: Any | None,
+) -> List[AgentEvent]:
+    """统一解析 events / locator 两类输入。"""
+
+    if events is not None:
+        return list(events)
+    if events_path is None:
+        raise TypeError("either events or events_path is required")
+    return load_agent_events_from_locator(events_path=events_path, wal_backend=wal_backend)
+
+
+def _parse_agent_events_jsonl(raw: str) -> List[AgentEvent]:
+    """把 JSONL 文本解析为 AgentEvent 列表。"""
+
+    events: List[AgentEvent] = []
+    for line in raw.splitlines():
+        s = line.strip()
+        if not s:
+            continue
+        obj = json.loads(s)
+        events.append(AgentEvent.model_validate(obj))
+    return events
+
+
+def _coerce_agent_events(items: Iterable[Any]) -> List[AgentEvent]:
+    """把 backend 返回的事件序列归一为 AgentEvent 列表。"""
+
+    events: List[AgentEvent] = []
+    for item in items:
+        if isinstance(item, AgentEvent):
+            events.append(item)
+        else:
+            events.append(AgentEvent.model_validate(item))
+    return events
+
+
+def _build_replay_tool_call_digest(events: List[AgentEvent]) -> ReplayToolCallDigest:
+    """从事件流中提取 replay / resume 所需的最小 tool call 摘要。"""
+
+    seg = _events_after_last_run_started(events)
+    requested_count = 0
+    finished_count = 0
+    pending_ids: list[str] = []
+    first_seen_order: list[str] = []
+    calls_by_id: dict[str, dict] = {}
+
+    for ev in seg:
+        if ev.type == "tool_call_requested":
+            call_id = str(ev.payload.get("call_id") or "").strip()
+            name = str(ev.payload.get("name") or ev.payload.get("tool") or "").strip()
+            if not call_id or not name:
+                continue
+            requested_count += 1
+            if call_id not in first_seen_order:
+                first_seen_order.append(call_id)
+            if call_id not in pending_ids:
+                pending_ids.append(call_id)
+            calls_by_id[call_id] = {
+                "call_id": call_id,
+                "name": name,
+                "step_id": str(ev.step_id or "").strip() or None,
+                "status": "pending",
+            }
+            continue
+
+        if ev.type == "tool_call_finished":
+            call_id = str(ev.payload.get("call_id") or "").strip()
+            name = str(ev.payload.get("tool") or ev.payload.get("name") or "").strip()
+            if not call_id or not name:
+                continue
+            finished_count += 1
+            if call_id not in first_seen_order:
+                first_seen_order.append(call_id)
+            if call_id in pending_ids:
+                pending_ids.remove(call_id)
+            prev = calls_by_id.get(call_id) or {}
+            calls_by_id[call_id] = {
+                "call_id": call_id,
+                "name": name,
+                "step_id": prev.get("step_id") or (str(ev.step_id or "").strip() or None),
+                "status": "finished",
+            }
+
+    latest_ids = first_seen_order[-20:]
+    latest_tool_calls = [calls_by_id[call_id] for call_id in latest_ids if call_id in calls_by_id]
+    return ReplayToolCallDigest(
+        requested_count=requested_count,
+        finished_count=finished_count,
+        pending_count=len(pending_ids),
+        latest_pending_call_ids=list(pending_ids),
+        latest_tool_calls=latest_tool_calls,
+    )

capability_runtime/host_toolkit/system_prompt.py

@@ -0,0 +1,132 @@
+"""
+system/developer 提示词（策略层）工具。
+
+MVR 约束：
+- system/developer 提示词不通过 `initial_history` 注入；
+- 由宿主生成 SDK overlays（prompt/config）并注入到 `skills_runtime.Agent`（或通过 Bridge 透传 config_paths）。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict
+
+
+class SystemPrompt(BaseModel):
+    """
+    system/developer 提示词集合。
+
+    字段：
+    - system_text：system 提示词（可为空）
+    - developer_text：developer 提示词（可为空）
+    - policy_id：策略 ID/版本（可选；用于审计与回归追溯）
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    system_text: Optional[str] = None
+    developer_text: Optional[str] = None
+    policy_id: Optional[str] = None
+
+
+class SystemPromptDigest(BaseModel):
+    """
+    system 提示词注入摘要（最小披露）。
+
+    注意：该对象不得包含提示词明文。
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    injected: bool
+    sha256: Optional[str] = None
+    bytes: Optional[int] = None
+    policy_id: Optional[str] = None
+
+
+@runtime_checkable
+class SystemPromptProvider(Protocol):
+    """
+    SystemPromptProvider：由宿主提供/实现。
+
+    说明：
+    - 框架不规定 system/developer 提示词从哪里来（文件/DB/规则引擎/租户配置）。
+    - 该 provider 只返回“策略文本”，实际注入由调用方通过 overlays 完成。
+    """
+
+    def get_system_prompt(self, *, context: Dict[str, Any]) -> SystemPrompt:
+        """
+        读取/生成 system 提示词。
+
+        参数：
+        - context：宿主上下文（例如 tenant/user/session_id 等），由宿主定义
+
+        返回：
+        - SystemPrompt（可能为空）
+        """
+
+        ...
+
+
+@dataclass(frozen=True)
+class StaticSystemPromptProvider:
+    """最小默认实现：返回固定的 SystemPrompt（便于测试与示例）。"""
+
+    prompt: SystemPrompt
+
+    def get_system_prompt(self, *, context: Dict[str, Any]) -> SystemPrompt:
+        """忽略上下文，返回固定 prompt。"""
+
+        return self.prompt
+
+
+def build_prompt_overlay(*, prompt: SystemPrompt) -> Dict[str, Any]:
+    """
+    把 SystemPrompt 转成 skills_runtime 配置 overlays（prompt.*）。
+
+    参数：
+    - prompt：SystemPrompt
+
+    返回：
+    - overlays dict（可写入 YAML 并作为 config_paths 传入）
+    """
+
+    return {
+        "prompt": {
+            "system_text": prompt.system_text,
+            "developer_text": prompt.developer_text,
+        }
+    }
+
+
+def compute_system_prompt_digest(*, prompt: SystemPrompt) -> SystemPromptDigest:
+    """
+    计算 system prompt 摘要（sha256/bytes/policy_id），用于 NodeReport.meta。
+
+    参数：
+    - prompt：SystemPrompt（可能为空）
+
+    返回：
+    - SystemPromptDigest（不含明文）
+    """
+
+    injected = bool((prompt.system_text or "").strip() or (prompt.developer_text or "").strip())
+    if not injected:
+        return SystemPromptDigest(injected=False, sha256=None, bytes=0, policy_id=prompt.policy_id)
+
+    canonical = {
+        "system_text": prompt.system_text or "",
+        "developer_text": prompt.developer_text or "",
+        "policy_id": prompt.policy_id,
+    }
+    raw = json.dumps(canonical, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return SystemPromptDigest(
+        injected=True,
+        sha256=hashlib.sha256(raw).hexdigest(),
+        bytes=len(raw),
+        policy_id=prompt.policy_id,
+    )

capability_runtime/host_toolkit/turn_delta.py

@@ -0,0 +1,128 @@
+"""
+TurnDelta：一次 turn 的“事实记录”（数据面 + 控制面 + 审计指针）。
+
+说明：
+- TurnDelta 的目标是让业务存储“可审计事实”，而不是被迫存储上游 messages 细节。
+- TurnDelta 可用于生成下一轮的 `initial_history`（通过 HistoryAssembler），也可用于审计/回放（通过 events_path 指针）。
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Optional, Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..types import NodeReport
+
+
+@runtime_checkable
+class TurnDeltaRedactor(Protocol):
+    """
+    TurnDelta 脱敏策略接口（由宿主实现）。
+
+    约束：
+    - 该接口仅处理“用户/助手文本”的脱敏；tool 证据链脱敏由 SDK/Bridge 负责。
+    - 默认实现不保证识别所有 secrets；宿主应按自身合规要求实现更强策略。
+    """
+
+    def redact_user_input(self, text: str) -> str:
+        """
+        脱敏 user_input。
+
+        参数：
+        - text：原始 user_input 文本
+
+        返回：
+        - 脱敏后的文本（可截断/替换/移除）
+        """
+
+        ...
+
+    def redact_assistant_output(self, text: str) -> str:
+        """
+        脱敏 assistant_output（即 final_output）。
+
+        参数：
+        - text：原始 final_output 文本
+
+        返回：
+        - 脱敏后的文本
+        """
+
+        ...
+
+
+@dataclass(frozen=True)
+class TruncatingTurnDeltaRedactor:
+    """
+    默认脱敏器：仅做截断（避免过长内容进入存储/日志）。
+
+    注意：该策略不做 secrets 识别，仅作为“最小兜底”。
+    """
+
+    max_chars: int = 2000
+
+    def redact_user_input(self, text: str) -> str:
+        """对 user_input 做截断脱敏。"""
+
+        s = str(text or "")
+        return s if len(s) <= self.max_chars else (s[: self.max_chars - 3] + "...")
+
+    def redact_assistant_output(self, text: str) -> str:
+        """对 assistant_output 做截断脱敏。"""
+
+        s = str(text or "")
+        return s if len(s) <= self.max_chars else (s[: self.max_chars - 3] + "...")
+
+
+class TurnDelta(BaseModel):
+    """
+    TurnDelta（一次回合事实）。
+
+    字段说明：
+    - session_id/host_turn_id：由宿主生成，用于生命周期管理与追溯。
+    - run_id：一次执行的 run 标识（推荐与 host_turn_id 一一映射）。
+    - user_input：本回合用户输入（可选；若缺失则无法从 TurnDelta 组装回 user message）。
+    - final_output：数据面输出（自由文本允许，但建议宿主按需脱敏）。
+    - node_report：控制面强结构（NodeReport，schema v1）。
+    - events_path：WAL 定位符（locator；来自 SDK/Bridge；不得伪造）。
+    - created_at_ms：宿主记录的本回合创建时间（用于排序与回放）；不作为安全证据源。
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    session_id: Optional[str] = None
+    host_turn_id: Optional[str] = None
+    run_id: Optional[str] = None
+
+    user_input: Optional[str] = None
+    final_output: str = ""
+
+    node_report: NodeReport
+    events_path: Optional[str] = None
+
+    created_at_ms: int = Field(default_factory=lambda: int(time.time() * 1000))
+
+    def redacted(self, *, redactor: TurnDeltaRedactor) -> "TurnDelta":
+        """
+        返回脱敏后的 TurnDelta（不修改原对象）。
+
+        参数：
+        - redactor：脱敏策略
+
+        返回：
+        - 新的 TurnDelta（user_input/final_output 经脱敏）
+        """
+
+        return TurnDelta(
+            session_id=self.session_id,
+            host_turn_id=self.host_turn_id,
+            run_id=self.run_id,
+            user_input=redactor.redact_user_input(self.user_input) if self.user_input is not None else None,
+            final_output=redactor.redact_assistant_output(self.final_output),
+            node_report=self.node_report,
+            events_path=self.events_path,
+            created_at_ms=self.created_at_ms,
+        )

capability_runtime/logging_utils.py

@@ -0,0 +1,94 @@
+"""
+日志工具模块：提供运行时错误可观测性支持。
+
+设计要点：
+- 使用标准库 logging，不引入外部依赖
+- 所有静默异常记录到 DEBUG 级别
+- 日志包含 exc_info=True 以保留完整堆栈
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional
+
+# 模块级 logger
+_logger = logging.getLogger("capability_runtime")
+
+
+def get_logger(name: Optional[str] = None) -> logging.Logger:
+    """
+    获取 capability_runtime 命名空间下的 logger。
+
+    参数：
+    - name：可选子模块名，如 "runtime" → "capability_runtime.runtime"
+
+    返回：
+    - logging.Logger 实例
+    """
+    if name:
+        return _logger.getChild(name)
+    return _logger
+
+
+def log_suppressed_exception(
+    *,
+    context: str,
+    exc: BaseException,
+    run_id: Optional[str] = None,
+    capability_id: Optional[str] = None,
+    extra: Optional[Dict[str, Any]] = None,
+) -> None:
+    """
+    记录被静默处理的异常（DEBUG 级别）。
+
+    参数：
+    - context：异常发生上下文描述（如 "emit_agent_event_taps"）
+    - exc：被捕获的异常实例
+    - run_id：可选运行 ID
+    - capability_id：可选能力 ID
+    - extra：可选额外字段
+
+    说明：
+    - 使用 DEBUG 级别，避免生产日志量增加
+    - 自动包含 exc_info=True 保留堆栈
+    - 禁止在 extra 中包含敏感信息（密钥、凭证、完整 payload）
+    """
+    log_extra: Dict[str, Any] = {
+        "error_type": type(exc).__name__,
+        "error_message": str(exc)[:200],  # 截断避免日志膨胀
+    }
+    if run_id:
+        log_extra["run_id"] = run_id
+    if capability_id:
+        log_extra["capability_id"] = capability_id
+    if extra:
+        # 过滤敏感字段
+        safe_extra = {k: v for k, v in extra.items() if k not in _SENSITIVE_KEYS}
+        log_extra.update(safe_extra)
+
+    _logger.debug(
+        f"suppressed exception in {context}",
+        exc_info=exc,
+        extra=log_extra,
+    )
+
+
+# 敏感字段黑名单
+_SENSITIVE_KEYS = frozenset([
+    "password",
+    "secret",
+    "token",
+    "api_key",
+    "apikey",
+    "credential",
+    "authorization",
+    "bearer",
+    "private_key",
+])
+
+
+__all__ = [
+    "get_logger",
+    "log_suppressed_exception",
+]