capability-runtime 0.1.0__py3-none-any.whl

capability_runtime/host_protocol.py

@@ -0,0 +1,400 @@
+from __future__ import annotations
+
+"""HITL / wait-resume / approval 的宿主协议收敛层。"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+from .protocol.capability import CapabilityResult, CapabilityStatus
+from .types import NodeReport, NodeToolCallReport
+
+
+class HostRunStatus(str, Enum):
+    """宿主视角的运行状态。"""
+
+    RUNNING = "running"
+    WAITING_HUMAN = "waiting_human"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+@dataclass(frozen=True)
+class ApprovalTicket:
+    """
+    待审批票据。
+
+    参数：
+    - run_id：运行 ID
+    - capability_id：能力 ID
+    - approval_key：审批键
+    - tool_name/call_id：审批对应的工具调用标识
+    - workflow_id/workflow_instance_id/step_id：可选的 workflow 归属
+    - created_at_ms：best-effort 的创建时间戳
+    """
+
+    run_id: str
+    capability_id: str
+    approval_key: str
+    tool_name: str | None = None
+    call_id: str | None = None
+    workflow_id: str | None = None
+    workflow_instance_id: str | None = None
+    step_id: str | None = None
+    created_at_ms: int = 0
+
+
+@dataclass(frozen=True)
+class ResumeIntent:
+    """宿主续跑意图。"""
+
+    run_id: str
+    approval_key: str | None = None
+    decision: str | None = None
+    session_id: str | None = None
+    host_turn_id: str | None = None
+
+
+@dataclass(frozen=True)
+class HostRunSnapshot:
+    """
+    宿主运行摘要。
+
+    参数：
+    - run_id：运行 ID
+    - capability_id：能力 ID
+    - status：宿主状态
+    - node_status：NodeReport.status 原值（若有）
+    - approval_ticket：等待审批时的票据
+    - resume_state：宿主恢复所需的最小状态
+    - events_path：证据链 events 定位符
+    """
+
+    run_id: str
+    capability_id: str
+    status: HostRunStatus
+    node_status: str | None = None
+    approval_ticket: ApprovalTicket | None = None
+    resume_state: dict[str, Any] = field(default_factory=dict)
+    events_path: str | None = None
+    wait_kind: str | None = None
+    tool_name: str | None = None
+    call_id: str | None = None
+    workflow_id: str | None = None
+    workflow_instance_id: str | None = None
+    step_id: str | None = None
+    message_kind: str | None = None
+    message_preview: str | None = None
+
+
+def build_resume_intent(
+    *,
+    run_id: str,
+    approval_key: str | None = None,
+    decision: str | None = None,
+    session_id: str | None = None,
+    host_turn_id: str | None = None,
+) -> ResumeIntent:
+    """
+    构造宿主续跑意图。
+
+    参数：
+    - run_id：运行 ID
+    - approval_key：可选审批键
+    - decision：可选审批决定
+    - session_id：可选会话 ID
+    - host_turn_id：可选宿主 turn ID
+    """
+
+    return ResumeIntent(
+        run_id=run_id,
+        approval_key=approval_key,
+        decision=decision,
+        session_id=session_id,
+        host_turn_id=host_turn_id,
+    )
+
+
+def build_approval_ticket_from_report(
+    report: NodeReport | None,
+    *,
+    capability_id: str,
+) -> ApprovalTicket | None:
+    """
+    从 NodeReport 恢复 ApprovalTicket。
+
+    参数：
+    - report：NodeReport
+    - capability_id：能力 ID
+
+    返回：
+    - 待审批票据；无法恢复时返回 None
+    """
+
+    if report is None:
+        return None
+
+    call = _select_waiting_tool_call(report)
+    if call is None:
+        return None
+
+    approval_key = (call.approval_key or "").strip()
+    if not approval_key:
+        return None
+
+    meta = report.meta if isinstance(report.meta, dict) else {}
+    created_at_ms = meta.get("approval_requested_at_ms")
+    if not isinstance(created_at_ms, int):
+        created_at_ms = 0
+
+    return ApprovalTicket(
+        run_id=_resolve_run_id(result=None, report=report, metadata=None),
+        capability_id=capability_id,
+        approval_key=approval_key,
+        tool_name=str(call.name or "").strip() or None,
+        call_id=str(call.call_id or "").strip() or None,
+        workflow_id=_optional_text(meta.get("workflow_id")),
+        workflow_instance_id=_optional_text(meta.get("workflow_instance_id")),
+        step_id=_optional_text(meta.get("step_id")),
+        created_at_ms=created_at_ms,
+    )
+
+
+def summarize_host_run_result(result: CapabilityResult, *, capability_id: str) -> HostRunSnapshot:
+    """
+    把 terminal result 收敛成宿主运行摘要。
+
+    参数：
+    - result：终态 CapabilityResult
+    - capability_id：能力 ID
+    """
+
+    report = result.node_report
+    node_status = getattr(report, "status", None)
+    approval_ticket = build_approval_ticket_from_report(report, capability_id=capability_id)
+    status = _map_host_run_status(result=result, report=report, approval_ticket=approval_ticket)
+    wait_summary = _summarize_waiting_human_context(report=report, approval_ticket=approval_ticket)
+
+    resume_state: dict[str, Any] = {}
+    if approval_ticket is not None:
+        resume_state["waiting_approval_key"] = approval_ticket.approval_key
+
+    return HostRunSnapshot(
+        run_id=_resolve_run_id(result=result, report=report, metadata=result.metadata),
+        capability_id=capability_id,
+        status=status,
+        node_status=node_status,
+        approval_ticket=approval_ticket,
+        resume_state=resume_state,
+        events_path=_optional_text(getattr(report, "events_path", None)),
+        wait_kind=wait_summary["wait_kind"],
+        tool_name=wait_summary["tool_name"],
+        call_id=wait_summary["call_id"],
+        workflow_id=wait_summary["workflow_id"],
+        workflow_instance_id=wait_summary["workflow_instance_id"],
+        step_id=wait_summary["step_id"],
+        message_kind=wait_summary["message_kind"],
+        message_preview=wait_summary["message_preview"],
+    )
+
+
+def project_host_runtime_data(result: CapabilityResult, *, capability_id: str = "") -> dict[str, Any] | None:
+    """
+    为 UI terminal 事件投影最小宿主状态。
+
+    参数：
+    - result：终态 CapabilityResult
+    - capability_id：可选能力 ID；投影等待审批最小摘要时可为空
+    """
+
+    snapshot = summarize_host_run_result(result, capability_id=capability_id)
+    if snapshot.status != HostRunStatus.WAITING_HUMAN:
+        return None
+    return {
+        "status": snapshot.status.value,
+        "wait_kind": snapshot.wait_kind,
+        "run_id": snapshot.run_id,
+        "node_status": snapshot.node_status,
+        "events_path": snapshot.events_path,
+        "tool_name": snapshot.tool_name,
+        "call_id": snapshot.call_id,
+        "workflow_id": snapshot.workflow_id,
+        "workflow_instance_id": snapshot.workflow_instance_id,
+        "step_id": snapshot.step_id,
+        "approval_key": snapshot.approval_ticket.approval_key if snapshot.approval_ticket is not None else None,
+        "message_kind": snapshot.message_kind,
+        "message_preview": snapshot.message_preview,
+        "resume_state": dict(snapshot.resume_state),
+    }
+
+
+def _select_waiting_tool_call(report: NodeReport) -> NodeToolCallReport | None:
+    """选择最能代表 waiting approval 的工具调用。"""
+
+    waiting_candidates: list[NodeToolCallReport] = []
+    fallback_candidates: list[NodeToolCallReport] = []
+    for call in report.tool_calls:
+        if call.requires_approval:
+            fallback_candidates.append(call)
+            if call.approval_key and call.approval_decision is None:
+                waiting_candidates.append(call)
+    if waiting_candidates:
+        return waiting_candidates[0]
+    if report.status == "needs_approval" and fallback_candidates:
+        return fallback_candidates[0]
+    return None
+
+
+def _map_host_run_status(
+    *,
+    result: CapabilityResult,
+    report: NodeReport | None,
+    approval_ticket: ApprovalTicket | None,
+) -> HostRunStatus:
+    """将 terminal result + NodeReport 映射为宿主状态。"""
+
+    if getattr(report, "status", None) == "needs_approval" or approval_ticket is not None:
+        return HostRunStatus.WAITING_HUMAN
+    if result.status == CapabilityStatus.SUCCESS:
+        return HostRunStatus.COMPLETED
+    if result.status == CapabilityStatus.FAILED:
+        return HostRunStatus.FAILED
+    if result.status == CapabilityStatus.CANCELLED:
+        return HostRunStatus.CANCELLED
+    return HostRunStatus.RUNNING
+
+
+def _resolve_run_id(
+    *,
+    result: CapabilityResult | None,
+    report: NodeReport | None,
+    metadata: dict[str, Any] | None,
+) -> str:
+    """按 report → metadata → result.metadata 的顺序恢复 run_id。"""
+
+    if report is not None and isinstance(report.run_id, str) and report.run_id.strip():
+        return report.run_id.strip()
+    if isinstance(metadata, dict):
+        run_id = metadata.get("run_id")
+        if isinstance(run_id, str) and run_id.strip():
+            return run_id.strip()
+    if result is not None and isinstance(result.metadata, dict):
+        run_id = result.metadata.get("run_id")
+        if isinstance(run_id, str) and run_id.strip():
+            return run_id.strip()
+    return ""
+
+
+def _optional_text(value: Any) -> Optional[str]:
+    """把可选字段归一为非空字符串。"""
+
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None
+
+
+def _summarize_waiting_human_context(
+    *,
+    report: NodeReport | None,
+    approval_ticket: ApprovalTicket | None,
+) -> dict[str, str | None]:
+    """提取 waiting_human 场景的最小宿主摘要字段。"""
+
+    empty = {
+        "wait_kind": None,
+        "tool_name": None,
+        "call_id": None,
+        "workflow_id": None,
+        "workflow_instance_id": None,
+        "step_id": None,
+        "message_kind": None,
+        "message_preview": None,
+    }
+    if report is None:
+        return empty
+
+    meta = report.meta if isinstance(report.meta, dict) else {}
+    message_preview = _build_message_preview(meta.get("final_message"))
+    waiting_call = _select_host_waiting_tool_call(report)
+
+    tool_name = approval_ticket.tool_name if approval_ticket is not None else _optional_text(getattr(waiting_call, "name", None))
+    call_id = approval_ticket.call_id if approval_ticket is not None else _optional_text(getattr(waiting_call, "call_id", None))
+    workflow_id = approval_ticket.workflow_id if approval_ticket is not None else _optional_text(meta.get("workflow_id"))
+    workflow_instance_id = (
+        approval_ticket.workflow_instance_id if approval_ticket is not None else _optional_text(meta.get("workflow_instance_id"))
+    )
+    step_id = approval_ticket.step_id if approval_ticket is not None else _optional_text(meta.get("step_id"))
+
+    if approval_ticket is not None:
+        wait_kind = "approval"
+        message_kind = "approval_message"
+    else:
+        wait_kind, message_kind = _classify_non_approval_waiting(
+            raw_kind=meta.get("waiting_human_kind"),
+            tool_name=tool_name,
+            message_preview=message_preview,
+        )
+
+    return {
+        "wait_kind": wait_kind,
+        "tool_name": tool_name,
+        "call_id": call_id,
+        "workflow_id": workflow_id,
+        "workflow_instance_id": workflow_instance_id,
+        "step_id": step_id,
+        "message_kind": message_kind,
+        "message_preview": message_preview,
+    }
+
+
+def _select_host_waiting_tool_call(report: NodeReport) -> NodeToolCallReport | None:
+    """选择最能代表 waiting_human 摘要的工具调用。"""
+
+    approval_call = _select_waiting_tool_call(report)
+    if approval_call is not None:
+        return approval_call
+
+    for call in report.tool_calls:
+        if _optional_text(call.name) in {"ask_human", "request_user_input"}:
+            return call
+    if report.tool_calls:
+        return report.tool_calls[0]
+    return None
+
+
+def _classify_non_approval_waiting(
+    *,
+    raw_kind: Any,
+    tool_name: str | None,
+    message_preview: str | None,
+) -> tuple[str, str]:
+    """best-effort 分类非 approval 型 waiting_human。"""
+
+    normalized_kind = _optional_text(raw_kind)
+    if normalized_kind == "workflow_continue":
+        return "workflow_continue", "generic_waiting_human"
+    if normalized_kind in {"host_input", "ask_human", "request_user_input"}:
+        message_kind = "request_user_input" if normalized_kind == "request_user_input" else "ask_human"
+        return "host_input", message_kind
+
+    if tool_name == "request_user_input":
+        return "host_input", "request_user_input"
+    if tool_name == "ask_human":
+        return "host_input", "ask_human"
+
+    preview = str(message_preview or "").lower()
+    if "ask" in preview or "input" in preview:
+        return "host_input", "generic_waiting_human"
+    return "unknown", "generic_waiting_human"
+
+
+def _build_message_preview(value: Any) -> str | None:
+    """把 waiting message 归一为单行、最多 120 个字符的摘要。"""
+
+    if not isinstance(value, str):
+        return None
+    normalized = " ".join(value.split())
+    if not normalized:
+        return None
+    return normalized[:120]

capability_runtime/host_toolkit/__init__.py

@@ -0,0 +1,55 @@
+"""
+Host toolkit（宿主工具箱）。
+
+定位：
+- 本包用于帮助宿主（Host）以“业务主控（真相源）+ 框架提供工具”的方式落地单智能体 session/turn 生命周期。
+- 本包不实现业务存储/权限/审批 UI；仅提供可复用的模型、组装器与证据链辅助。
+
+注意：
+- system/developer 提示词在 MVR 中不通过 `initial_history` 注入，而通过 SDK prompt/config overlays 注入（见 `system_prompt`）。
+"""
+
+from .approvals_profiles import ApprovalsProfile, ApprovalsProfiles, validate_approvals_profile
+from .evidence_hooks import SystemPromptEvidence, SystemPromptEvidenceHook
+from .history import HistoryAssembler, HistoryAssemblerConfig
+from .invoke_capability import InvokeCapabilityAllowlist, make_invoke_capability_tool
+from .resume import (
+    ResumeReplaySummary,
+    build_resume_replay_summary,
+    load_agent_events_from_jsonl,
+    load_agent_events_from_locator,
+)
+from .system_prompt import (
+    StaticSystemPromptProvider,
+    SystemPrompt,
+    SystemPromptDigest,
+    SystemPromptProvider,
+    build_prompt_overlay,
+    compute_system_prompt_digest,
+)
+from .turn_delta import TurnDelta, TurnDeltaRedactor, TruncatingTurnDeltaRedactor
+
+__all__ = [
+    "ApprovalsProfile",
+    "ApprovalsProfiles",
+    "validate_approvals_profile",
+    "SystemPromptEvidence",
+    "SystemPromptEvidenceHook",
+    "HistoryAssembler",
+    "HistoryAssemblerConfig",
+    "InvokeCapabilityAllowlist",
+    "make_invoke_capability_tool",
+    "ResumeReplaySummary",
+    "build_resume_replay_summary",
+    "load_agent_events_from_jsonl",
+    "load_agent_events_from_locator",
+    "StaticSystemPromptProvider",
+    "SystemPrompt",
+    "SystemPromptDigest",
+    "SystemPromptProvider",
+    "build_prompt_overlay",
+    "compute_system_prompt_digest",
+    "TurnDelta",
+    "TurnDeltaRedactor",
+    "TruncatingTurnDeltaRedactor",
+]

capability_runtime/host_toolkit/approvals_profiles.py

@@ -0,0 +1,94 @@
+"""
+Approvals profiles：阻塞等待审批的最佳实践配置与校验。
+
+目标：
+- 提供可移植的 dev/prod profile 模板（不绑定业务 UI）；
+- 强制校验 `approval_timeout_ms` 与 `max_wall_time_sec` 的关系，避免“审批永远等不到结果”。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ApprovalsProfile(BaseModel):
+    """
+    ApprovalsProfile（可移植配置模板）。
+
+    参数：
+    - name：profile 名称（dev/prod/custom）
+    - approval_timeout_ms：等待人类审批的最长时间（超时按 denied）
+    - max_wall_time_sec：一次 run 的最大墙钟时间（预算）
+    - buffer_ms：安全 buffer（避免 wall-time 先于 approval timeout 触发）
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    approval_timeout_ms: int = Field(ge=1)
+    max_wall_time_sec: int = Field(ge=1)
+    buffer_ms: int = Field(default=60_000, ge=0)
+
+    def to_sdk_overlay(self) -> Dict[str, Any]:
+        """
+        转为 skills_runtime 配置 overlays。
+
+        返回：
+        - overlays dict（可写入 YAML 并作为 config_paths 传入）
+        """
+
+        return {
+            "run": {"max_wall_time_sec": int(self.max_wall_time_sec)},
+            "safety": {"approval_timeout_ms": int(self.approval_timeout_ms)},
+        }
+
+
+@dataclass(frozen=True)
+class ApprovalsProfiles:
+    """
+    推荐 profiles 集合（可作为默认值参考）。
+
+    注意：这些值仅是框架建议；调用方必须根据实际审批时延与节点预算调整。
+    """
+
+    dev: ApprovalsProfile = field(
+        default_factory=lambda: ApprovalsProfile(
+            name="dev",
+            approval_timeout_ms=60_000,
+            max_wall_time_sec=600,
+            buffer_ms=60_000,
+        )
+    )
+    prod: ApprovalsProfile = field(
+        default_factory=lambda: ApprovalsProfile(
+            name="prod",
+            approval_timeout_ms=600_000,
+            max_wall_time_sec=1800,
+            buffer_ms=120_000,
+        )
+    )
+
+
+def validate_approvals_profile(*, profile: ApprovalsProfile) -> None:
+    """
+    校验 approvals profile 的 timeout 关系。
+
+    规则：
+    - approval_timeout_ms <= max_wall_time_sec*1000 - buffer_ms
+
+    参数：
+    - profile：待校验 profile
+
+    异常：
+    - ValueError：关系不满足时抛出（用于 fail-closed）
+    """
+
+    max_ms = int(profile.max_wall_time_sec) * 1000
+    if int(profile.approval_timeout_ms) > max_ms - int(profile.buffer_ms):
+        raise ValueError(
+            "invalid approvals profile: approval_timeout_ms must be <= max_wall_time_sec*1000 - buffer_ms "
+            f"(got approval_timeout_ms={profile.approval_timeout_ms}, max_wall_time_sec={profile.max_wall_time_sec}, buffer_ms={profile.buffer_ms})"
+        )

capability_runtime/host_toolkit/evidence_hooks.py

@@ -0,0 +1,65 @@
+"""
+证据链辅助：把“system 策略注入摘要”写入 NodeReport.meta。
+
+说明：
+- Bridge core 不应理解 system 策略文本；这里仅写入最小披露摘要（sha256/bytes/policy_id）。
+- 该 hook 不要求必须实现 BridgeHook 全量方法；Bridge 调用侧通过 getattr 探测并安全调用。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, ConfigDict
+
+from ..types import NodeResult
+
+
+class SystemPromptEvidence(BaseModel):
+    """
+    system prompt 注入证据（最小披露）。
+
+    字段对齐 `openspec/specs/evidence-chain/spec.md`：
+    - system_prompt_injected
+    - system_prompt_sha256
+    - system_prompt_bytes
+    - system_policy_id
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    system_prompt_injected: bool
+    system_prompt_sha256: Optional[str] = None
+    system_prompt_bytes: Optional[int] = None
+    system_policy_id: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class SystemPromptEvidenceHook:
+    """
+    BridgeHook（片段）：在返回结果前把 system prompt 摘要写入 NodeReport.meta。
+
+    参数：
+    - evidence：system prompt 注入证据摘要（不得包含明文）
+    """
+
+    evidence: SystemPromptEvidence
+
+    def before_return_result(self, context: Dict[str, Any], node_result: NodeResult) -> None:
+        """
+        在 Bridge 返回 NodeResult 前写入证据链摘要。
+
+        参数：
+        - context：Bridge hook_context（脱敏摘要）
+        - node_result：桥接层返回值
+        """
+
+        meta = node_result.node_report.meta
+        meta.setdefault("system_prompt_injected", self.evidence.system_prompt_injected)
+        if self.evidence.system_prompt_sha256 is not None:
+            meta.setdefault("system_prompt_sha256", self.evidence.system_prompt_sha256)
+        if self.evidence.system_prompt_bytes is not None:
+            meta.setdefault("system_prompt_bytes", self.evidence.system_prompt_bytes)
+        if self.evidence.system_policy_id is not None:
+            meta.setdefault("system_policy_id", self.evidence.system_policy_id)

capability_runtime/host_toolkit/history.py

@@ -0,0 +1,74 @@
+"""
+HistoryAssembler：从 TurnDelta 序列组装 `initial_history`（最小披露）。
+
+约束（MVR）：
+- 仅输出 `role in {"user","assistant"}` 的最小消息形态 `{role, content}`；
+- tool 结果与敏感信息默认不进入 prompt（如需进入必须由宿主生成摘要后写入 user/assistant 文本）。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .turn_delta import TurnDelta
+
+
+class HistoryAssemblerConfig(BaseModel):
+    """
+    HistoryAssembler 配置。
+
+    参数：
+    - max_turns：最多回传多少个 turn（按时间顺序取末尾 N 个）
+    - max_message_chars：单条 message 的最大字符数（截断兜底，避免 prompt 膨胀）
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    max_turns: int = Field(default=20, ge=0)
+    max_message_chars: int = Field(default=8000, ge=1)
+
+
+@dataclass(frozen=True)
+class HistoryAssembler:
+    """
+    HistoryAssembler：将 TurnDelta[] 组装为 `initial_history`。
+
+    说明：
+    - 该类不读取 WAL，不推断工具行为；只消费宿主存储的 TurnDelta（真相源）。
+    - TurnDelta.user_input 缺失时会跳过 user message（保守策略）。
+    """
+
+    config: HistoryAssemblerConfig = field(default_factory=HistoryAssemblerConfig)
+
+    def build_initial_history(self, *, deltas: List[TurnDelta]) -> List[Dict[str, Any]]:
+        """
+        组装 `initial_history`（OpenAI wire messages 子集）。
+
+        参数：
+        - deltas：按时间顺序的 TurnDelta 列表（建议已按 created_at_ms 排序）
+
+        返回：
+        - `[{role, content}, ...]`，其中 role 仅包含 user/assistant
+        """
+
+        if self.config.max_turns <= 0 or not deltas:
+            return []
+
+        tail = deltas[-self.config.max_turns :]
+        out: List[Dict[str, Any]] = []
+        for d in tail:
+            if d.user_input is not None:
+                out.append({"role": "user", "content": self._truncate(d.user_input)})
+            if d.final_output:
+                out.append({"role": "assistant", "content": self._truncate(d.final_output)})
+        return out
+
+    def _truncate(self, text: str) -> str:
+        """截断 message 内容（兜底）。"""
+
+        s = str(text or "")
+        n = self.config.max_message_chars
+        return s if len(s) <= n else (s[: n - 3] + "...")