capability-runtime 0.1.0__py3-none-any.whl

capability_runtime/adapters/workflow_engine.py

@@ -0,0 +1,43 @@
+"""Workflow 引擎内部协议。"""
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Dict, Protocol, Union
+
+from ..protocol.capability import CapabilityResult
+from ..protocol.context import ExecutionContext
+from ..protocol.workflow import WorkflowSpec
+from ..services import RuntimeServices
+
+# Workflow 轻量流式事件：默认给编排/UI 读取，不承担深审计职责。
+WorkflowStreamEvent = Dict[str, Any]
+WorkflowStreamItem = Union[WorkflowStreamEvent, CapabilityResult]
+
+
+class WorkflowEngine(Protocol):
+    """
+    Workflow 引擎协议（内部使用）。
+
+    约束：
+    - 对外 API 仍由 Runtime 暴露；
+    - 引擎可替换，但 execute/execute_stream 契约必须稳定。
+    """
+
+    async def execute(
+        self,
+        *,
+        spec: WorkflowSpec,
+        input: Dict[str, Any],
+        context: ExecutionContext,
+        services: RuntimeServices,
+    ) -> CapabilityResult:
+        """执行 Workflow（非流式）。"""
+
+    async def execute_stream(
+        self,
+        *,
+        spec: WorkflowSpec,
+        input: Dict[str, Any],
+        context: ExecutionContext,
+        services: RuntimeServices,
+    ) -> AsyncIterator[WorkflowStreamItem]:
+        """执行 Workflow（流式）。"""

capability_runtime/config.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+"""
+统一运行时配置（RuntimeConfig）。
+
+说明：
+- 本仓定位为 runtime/adapter/bridge 的契约收敛层；
+- 业务不应在本仓中被定义或侵入；
+- 执行模式通过 `RuntimeConfig.mode` 切换，而不是通过更换入口类。
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Literal, Optional
+
+from skills_runtime.core.exec_sessions import ExecSessionsProvider
+from skills_runtime.llm.protocol import ChatBackend
+from skills_runtime.safety.approvals import ApprovalProvider
+from skills_runtime.state.wal_protocol import WalBackend
+from skills_runtime.tools.protocol import HumanIOProvider, ToolSpec
+
+
+PreflightMode = Literal["error", "warn", "off"]
+RuntimeMode = Literal["mock", "bridge", "sdk_native"]
+OutputValidationMode = Literal["off", "warn", "error"]
+
+
+@dataclass(frozen=True)
+class CustomTool:
+    """
+    预注册的自定义工具（每次创建 SDK Agent 时注入）。
+
+    参数：
+    - spec：工具规格（ToolSpec）
+    - handler：工具处理函数（签名需兼容上游 ToolRegistry）
+    - override：是否允许覆盖同名工具
+    - descriptor：可选上游 tool descriptor（若注册签名支持则透传）
+    """
+
+    spec: ToolSpec
+    handler: Any
+    override: bool = False
+    descriptor: Any | None = None
+
+
+@dataclass(frozen=True)
+class RuntimeConfig:
+    """
+    统一运行时配置。
+
+    参数分组：
+    - 执行模式：mode
+    - 桥接执行：workspace_root / sdk_config_paths / agently_agent
+    - Workflow：workflow_engine（可注入）
+    - SDK 注入：approval_provider / human_io / cancel_checker / wal_backend / env_vars
+    - Skills 配置：skills_config / in_memory_skills
+    - 自定义工具：custom_tools
+    - 护栏：max_depth / max_total_loop_iterations / preflight_mode
+    - Mock：mock_handler
+    - 观测：on_event
+    """
+
+    # === 执行模式 ===
+    mode: RuntimeMode = "bridge"
+
+    # === 桥接配置（mode=bridge 时使用）===
+    workspace_root: Optional[Path] = None
+    sdk_config_paths: List[Path] = field(default_factory=list)
+    agently_agent: Optional[Any] = None
+
+    # === Workflow 引擎注入（可选）===
+    #
+    # 说明：
+    # - 默认使用 TriggerFlowWorkflowEngine（Agently TriggerFlow）；
+    # - 当上游 workflow engine 需要替换/隔离时，可注入兼容接口的实现：
+    #   - execute(*, spec, input, context, runtime) -> CapabilityResult
+    #   - execute_stream(*, spec, input, context, runtime) -> AsyncIterator[WorkflowStreamItem]
+    workflow_engine: Optional[Any] = None
+
+    # === 可选 Runtime RPC client/server 注入（v1）===
+    #
+    # 说明：
+    # - `runtime_client`：供 RuntimeServiceFacade 在 RPC 执行目标下使用；
+    # - `runtime_server`：供 Runtime.bind_runtime_server() 显式绑定本地 Runtime；
+    # - 两者均采用 duck typing，不在 RuntimeConfig 层做强类型约束。
+    runtime_client: Optional[Any] = None
+    runtime_server: Optional[Any] = None
+
+    # === SDK 注入 ===
+    approval_provider: Optional[ApprovalProvider] = None
+    human_io: Optional[HumanIOProvider] = None
+    cancel_checker: Optional[Callable[[], bool]] = None
+    exec_sessions: Optional[ExecSessionsProvider] = None
+    collab_manager: Optional[object] = None
+    wal_backend: Optional[WalBackend] = None
+    env_vars: Dict[str, str] = field(default_factory=dict)
+
+    # === SDK LLM backend 注入（离线回归/测试）===
+    #
+    # 说明：
+    # - 默认情况下 backend 由 mode 决定：
+    #   - bridge：AgentlyChatBackend（复用 OpenAICompatible requester 作为传输层）
+    #   - sdk_native：skills_runtime 原生 OpenAIChatCompletionsBackend
+    # - 当你需要离线可回归（不依赖外网/真实 key），可注入 FakeChatBackend 等实现驱动真实 Agent loop，
+    #   以获得完整的 tool/approvals/WAL/NodeReport 证据链。
+    # - 该字段仅改变“LLM 传输层”，不改变 tool/skills/WAL 的执行真相源（仍为 skills_runtime.Agent）。
+    sdk_backend: Optional[ChatBackend] = None
+
+    # === Skills 配置 ===
+    skills_config: Optional[Dict[str, Any]] = None
+    in_memory_skills: Optional[Dict[str, List[dict]]] = None
+
+    # === 自定义 Tools ===
+    custom_tools: List[CustomTool] = field(default_factory=list)
+
+    # === 护栏 ===
+    max_depth: int = 10
+    max_total_loop_iterations: int = 50000
+    preflight_mode: PreflightMode = "error"
+
+    # === Output Validator（可选）===
+    #
+    # 说明：
+    # - 取代旧的 SchemaGate/SchemaGateMode：以 callback 方式提供输出校验；
+    # - callback 返回值应是“可观测摘要”，不得把大段 payload 原文塞入 meta；
+    # - 推荐签名（keyword-only）：
+    #   validate(*, final_output: str, node_report: NodeReport, context: dict) -> dict
+    output_validation_mode: OutputValidationMode = "off"
+    output_validator: Optional[Callable[..., Any]] = None
+
+    # === Mock（mode=mock 时使用）===
+    #
+    # 说明：
+    # - 用于离线回归与场景测试；
+    # - 允许两种签名（二选一）：
+    #   1) handler(spec, input_dict) -> Any | CapabilityResult
+    #   2) handler(spec, input_dict, context) -> Any | CapabilityResult
+    # - 返回 CapabilityResult 时 Runtime 将直接透传（便于测试 pending/failed/report 语义）。
+    mock_handler: Optional[Callable[..., Any]] = None
+
+    # === 事件回调（可观测性）===
+    #
+    # 说明：
+    # - 允许两种签名（二选一）：
+    #   1) on_event(event) -> None
+    #   2) on_event(event, context) -> None
+    # - 回调异常将被吞掉（fail-open），避免影响主流程。
+    on_event: Optional[Callable[..., None]] = None
+
+
+def normalize_workspace_root(workspace_root: Optional[Path]) -> Path:
+    """
+    归一化 workspace_root。
+
+    参数：
+    - workspace_root：可选 Path；为 None 时默认当前目录
+
+    返回：
+    - 绝对路径 Path
+    """
+
+    return (workspace_root or Path(".")).expanduser().resolve()
+
+
+__all__ = [
+    "PreflightMode",
+    "RuntimeMode",
+    "OutputValidationMode",
+    "CustomTool",
+    "RuntimeConfig",
+    "normalize_workspace_root",
+]

capability_runtime/errors.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+"""框架统一错误定义。"""
+
+from .protocol.context import RecursionLimitError
+
+
+class RuntimeFrameworkError(Exception):
+    """框架基础错误。"""
+
+
+class CapabilityNotFoundError(RuntimeFrameworkError):
+    """指定 ID 的能力未注册。"""
+
+
+__all__ = [
+    "RuntimeFrameworkError",
+    "CapabilityNotFoundError",
+    "RecursionLimitError",
+]

capability_runtime/guards.py

@@ -0,0 +1,150 @@
+"""执行守卫——全局循环与编排保护。"""
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Any, Awaitable, Callable, Dict, List
+
+from .protocol.capability import CapabilityResult, CapabilityStatus
+
+
+class LoopBreakerError(Exception):
+    """全局循环迭代次数超限。"""
+
+
+class ExecutionGuards:
+    """
+    全局执行守卫（per-run）。
+
+    职责：
+    - 维护“全局循环迭代次数”计数器，用于熔断失控的 Loop；
+    - 提供 LoopStep 的确定性执行方法（`run_loop`），并在每次迭代调用 `tick()`。
+
+    说明：
+    - 该守卫是 `LoopStep.max_iterations` 之上的第二道防线；
+    - 调用方应在每次顶层 run 开始前调用 `reset()`，避免跨 run 串扰。
+    """
+
+    def __init__(self, *, max_total_loop_iterations: int = 50000):
+        self._max = max_total_loop_iterations
+        self._counter = 0
+
+    def tick(self) -> None:
+        """
+        记录一次循环迭代。
+
+        超过全局上限时抛出 LoopBreakerError（fail-fast）。
+        """
+
+        self._counter += 1
+        if self._counter > self._max:
+            raise LoopBreakerError(
+                f"Global loop iteration limit ({self._max}) exceeded. "
+                f"Total iterations so far: {self._counter}"
+            )
+
+    @property
+    def counter(self) -> int:
+        """当前累计迭代次数。"""
+
+        return self._counter
+
+    def reset(self) -> None:
+        """重置计数器（通常在新的顶层 run 时调用）。"""
+
+        self._counter = 0
+
+    async def run_loop(
+        self,
+        *,
+        items: List[Any],
+        max_iterations: int,
+        execute_fn: Callable[[Any, int], Awaitable[CapabilityResult]],
+        fail_strategy: str = "abort",
+    ) -> CapabilityResult:
+        """
+        执行 LoopStep 语义（确定性）。
+
+        参数：
+        - items：要遍历的集合（必须为 list）
+        - max_iterations：最多迭代次数（在 items 长度之上取 min）
+        - execute_fn：执行函数，签名为 `(item, index) -> CapabilityResult`
+        - fail_strategy："abort" | "skip" | "collect"
+
+        返回：
+        - CapabilityResult，其中 output 为结果列表；metadata 提供 completed/total/skipped 等摘要。
+        """
+
+        # 输入验证：items 必须为 list
+        if not isinstance(items, list):
+            return CapabilityResult(
+                status=CapabilityStatus.FAILED,
+                error=f"run_loop: items must be list, got {type(items).__name__}",
+                error_code="INVALID_LOOP_INPUT",
+                metadata={"actual_type": type(items).__name__},
+            )
+
+        results: List[Any] = []
+        errors: List[Dict[str, Any]] = []
+        effective_max = min(max_iterations, len(items))
+
+        for idx, item in enumerate(items[:effective_max]):
+            self.tick()
+
+            try:
+                result = await execute_fn(item, idx)
+            except Exception as exc:
+                result = CapabilityResult(
+                    status=CapabilityStatus.FAILED,
+                    error=f"Loop iteration {idx} exception: {exc}",
+                    error_code="ENGINE_ERROR",
+                    metadata={"exception_type": type(exc).__name__},
+                )
+
+            if result.status != CapabilityStatus.SUCCESS:
+                # LoopStep 内部一旦出现非 success：
+                # - FAILED：按 fail_strategy 处理（abort/skip/collect）
+                # - PENDING/RUNNING/CANCELLED：不应被当作成功继续推进（否则会吞掉 needs_approval/incomplete 等语义）
+                if result.status in (CapabilityStatus.PENDING, CapabilityStatus.RUNNING, CapabilityStatus.CANCELLED):
+                    return replace(
+                        result,
+                        output=results,
+                        metadata={
+                            **dict(getattr(result, "metadata", {}) or {}),
+                            "completed_iterations": idx,
+                            "total_planned": effective_max,
+                            "aborted_status": getattr(result.status, "value", str(result.status)),
+                        },
+                    )
+
+                if fail_strategy == "abort":
+                    return replace(
+                        result,
+                        output=results,
+                        error=f"Loop aborted at iteration {idx}/{effective_max}: {result.error}",
+                        metadata={
+                            **dict(getattr(result, "metadata", {}) or {}),
+                            "completed_iterations": idx,
+                            "total_planned": effective_max,
+                        },
+                    )
+                if fail_strategy == "skip":
+                    errors.append({"index": idx, "error": result.error})
+                    continue
+                if fail_strategy == "collect":
+                    results.append({"status": "failed", "error": result.error, "index": idx})
+                    continue
+
+            results.append(result.output)
+
+        return CapabilityResult(
+            status=CapabilityStatus.SUCCESS,
+            output=results,
+            metadata={
+                "completed_iterations": len(results),
+                "total_planned": effective_max,
+                "skipped_errors": errors if errors else None,
+            },
+        )
+
+
+__all__ = ["LoopBreakerError", "ExecutionGuards"]