capability-runtime 0.1.0__py3-none-any.whl

capability_runtime/upstream_compat.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+"""
+上游兼容层（skills-runtime-sdk）。
+
+定位：
+- 本仓作为 runtime/adapter/bridge 的“契约收敛层”，需要在不 fork 上游的前提下吸收破坏性变更；
+- 本模块只做“版本感知的最小适配”，避免把上游变更扩散到业务与协议层（protocol/ 不应 import 上游）。
+
+当前覆盖：
+- skills spaces schema：`account/domain` ↔ `namespace`
+- strict mention：`$[account:domain].skill` ↔ `$[namespace].skill`
+"""
+
+from typing import Any, Dict, List, Literal, Optional, Tuple
+
+from .logging_utils import log_suppressed_exception
+
+
+SkillsSpaceSchema = Literal["account_domain", "namespace"]
+
+
+def detect_skills_space_schema() -> SkillsSpaceSchema:
+    """
+    探测当前安装的 skills-runtime-sdk 期望的 skills.spaces schema。
+
+    返回：
+    - "namespace"：上游要求 `skills.spaces[].namespace`（并可能拒绝 legacy 字段）
+    - "account_domain"：上游要求 `skills.spaces[].account` + `domain`
+    """
+
+    try:
+        import skills_runtime.config.loader as loader
+
+        space = getattr(getattr(loader, "AgentSdkSkillsConfig", None), "Space", None)
+        if space is not None:
+            fields = getattr(space, "model_fields", None)
+            if isinstance(fields, dict) and "namespace" in fields:
+                return "namespace"
+    except Exception as exc:
+        # 探测失败时保持保守：沿用历史 schema，避免误判导致初始化期直接崩。
+        log_suppressed_exception(
+            context="detect_skills_space_schema_loader",
+            exc=exc,
+            extra={"method": "AgentSdkSkillsConfig.Space"},
+        )
+        return "account_domain"
+
+    # fallback：通过 mentions API 特性推断（v0.1.5 引入 is_valid_namespace）
+    try:
+        import skills_runtime.skills.mentions as mentions
+
+        if hasattr(mentions, "is_valid_namespace"):
+            return "namespace"
+    except Exception as exc:
+        log_suppressed_exception(
+            context="detect_skills_space_schema_mentions",
+            exc=exc,
+            extra={"method": "mentions.is_valid_namespace"},
+        )
+        return "account_domain"
+
+    return "account_domain"
+
+
+def build_namespace_from_account_domain(*, account: str, domain: str) -> str:
+    """
+    将 legacy account/domain 映射为 namespace（最小无损映射：两段拼接）。
+
+    参数：
+    - account：旧版 account slug
+    - domain：旧版 domain slug
+
+    返回：
+    - namespace 字符串（形如 `account:domain`）
+    """
+
+    return f"{str(account).strip()}:{str(domain).strip()}"
+
+
+def split_namespace_to_account_domain(namespace: str) -> Tuple[str, str]:
+    """
+    将 namespace 映射回 legacy account/domain（仅当 namespace 恰好 2 段时允许）。
+
+    参数：
+    - namespace：namespace 字符串（形如 `a:b` / `a:b:c`）
+
+    返回：
+    - (account, domain)
+
+    异常：
+    - ValueError：当 namespace 不是 2 段时（无法无损映射到旧版 schema）
+    """
+
+    raw = str(namespace).strip()
+    parts = [p for p in raw.split(":") if p]
+    if len(parts) != 2:
+        raise ValueError("namespace must have exactly 2 segments to map into legacy account/domain")
+    return parts[0], parts[1]
+
+
+def normalize_spaces_for_upstream(
+    *,
+    spaces: Any,
+    target_schema: SkillsSpaceSchema,
+) -> Tuple[Optional[List[Dict[str, Any]]], List[str]]:
+    """
+    归一化 `skills.spaces` 为上游可接受的字段集合（最小转换 + 可追溯 warnings）。
+
+    参数：
+    - spaces：可能为 None / list[dict] / 其它（非 list 时返回 None）
+    - target_schema：目标 schema（account_domain 或 namespace）
+
+    返回：
+    - normalized_spaces：归一后的 spaces（无法处理时为 None，表示“不改动/交给上游报错”）
+    - warnings：转换/丢弃/拒绝的摘要文本（用于 worklog/测试取证；不绑定上游 Issue 结构）
+    """
+
+    if spaces is None:
+        return None, []
+    if not isinstance(spaces, list):
+        return None, []
+
+    warnings: List[str] = []
+    out: List[Dict[str, Any]] = []
+
+    for idx, sp in enumerate(spaces):
+        if not isinstance(sp, dict):
+            warnings.append(f"skills.spaces[{idx}] is not a dict; keep as-is (skip normalize)")
+            return None, warnings
+
+        sp_obj: Dict[str, Any] = dict(sp)
+
+        if target_schema == "namespace":
+            if isinstance(sp_obj.get("namespace"), str) and sp_obj.get("namespace", "").strip():
+                sp_obj.pop("account", None)
+                sp_obj.pop("domain", None)
+                out.append(sp_obj)
+                continue
+
+            account = sp_obj.get("account")
+            domain = sp_obj.get("domain")
+            if isinstance(account, str) and account.strip() and isinstance(domain, str) and domain.strip():
+                sp_obj["namespace"] = build_namespace_from_account_domain(account=account, domain=domain)
+                sp_obj.pop("account", None)
+                sp_obj.pop("domain", None)
+                warnings.append(f"converted skills.spaces[{idx}] account/domain -> namespace")
+                out.append(sp_obj)
+                continue
+
+            warnings.append(f"skills.spaces[{idx}] missing namespace and account/domain; keep as-is (skip normalize)")
+            return None, warnings
+
+        # target_schema == "account_domain"
+        if isinstance(sp_obj.get("account"), str) and sp_obj.get("account", "").strip() and isinstance(
+            sp_obj.get("domain"), str
+        ) and sp_obj.get("domain", "").strip():
+            sp_obj.pop("namespace", None)
+            out.append(sp_obj)
+            continue
+
+        namespace = sp_obj.get("namespace")
+        if isinstance(namespace, str) and namespace.strip():
+            try:
+                account, domain = split_namespace_to_account_domain(namespace)
+            except ValueError:
+                warnings.append(
+                    f"skills.spaces[{idx}] namespace cannot map to legacy account/domain (need 2 segments)"
+                )
+                return None, warnings
+            sp_obj["account"] = account
+            sp_obj["domain"] = domain
+            sp_obj.pop("namespace", None)
+            warnings.append(f"converted skills.spaces[{idx}] namespace -> account/domain")
+            out.append(sp_obj)
+            continue
+
+        warnings.append(f"skills.spaces[{idx}] missing account/domain and namespace; keep as-is (skip normalize)")
+        return None, warnings
+
+    return out, warnings
+

capability_runtime/utils/__init__.py

@@ -0,0 +1 @@
+"""公共工具函数模块。"""

capability_runtime/utils/usage.py

@@ -0,0 +1,65 @@
+"""
+Usage 提取工具：从 LLM usage payload 中提取标准化指标。
+
+兼容：
+- 本仓规范字段：`input_tokens/output_tokens/total_tokens`
+- OpenAI 风格字段：`prompt_tokens/completion_tokens/total_tokens`
+- 可选嵌套：`payload["usage"]`
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+def _usage_int(value: Any) -> Optional[int]:
+    """把 usage 数值归一为非负 int；无法识别时返回 None。"""
+
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value if value >= 0 else None
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return None
+    return parsed if parsed >= 0 else None
+
+
+def extract_usage_metrics(payload: Any) -> Dict[str, Optional[Any]]:
+    """
+    从 `llm_usage` payload 中提取 usage 摘要。
+
+    参数：
+    - payload：AgentEvent.payload 或类似结构
+
+    返回：
+    - dict 包含 model/input_tokens/output_tokens/total_tokens
+    """
+
+    if not isinstance(payload, dict):
+        return {"model": None, "input_tokens": None, "output_tokens": None, "total_tokens": None}
+
+    usage_raw = payload.get("usage")
+    usage_dict: Dict[str, Any] = usage_raw if isinstance(usage_raw, dict) else payload
+    model = payload.get("model")
+    if not isinstance(model, str) or not model.strip():
+        model = usage_dict.get("model")
+    model_text = model.strip() if isinstance(model, str) and model.strip() else None
+
+    input_tokens = _usage_int(usage_dict.get("input_tokens"))
+    if input_tokens is None:
+        input_tokens = _usage_int(usage_dict.get("prompt_tokens"))
+
+    output_tokens = _usage_int(usage_dict.get("output_tokens"))
+    if output_tokens is None:
+        output_tokens = _usage_int(usage_dict.get("completion_tokens"))
+
+    total_tokens = _usage_int(usage_dict.get("total_tokens"))
+
+    return {
+        "model": model_text,
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "total_tokens": total_tokens,
+    }

capability_runtime/workflow_runtime.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+"""Workflow host-facing runtime state / replay surface."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from .host_protocol import project_host_runtime_data
+from .protocol.capability import CapabilityResult, CapabilityStatus
+
+
+class WorkflowRunStatus(str, Enum):
+    """workflow 宿主状态。"""
+
+    RUNNING = "running"
+    WAITING_HUMAN = "waiting_human"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+@dataclass(frozen=True)
+class WorkflowStepSnapshot:
+    """
+    workflow 步骤摘要。
+
+    参数：
+    - step_id：步骤 ID
+    - status：步骤状态
+    - capability_id：可选能力 ID
+    - error：可选错误信息
+    """
+
+    step_id: str
+    status: str
+    capability_id: str | None = None
+    error: str | None = None
+
+
+@dataclass(frozen=True)
+class WorkflowRunSnapshot:
+    """
+    workflow 运行摘要。
+
+    参数：
+    - run_id：运行 ID
+    - workflow_id：workflow ID
+    - workflow_instance_id：workflow 实例 ID
+    - status：宿主状态
+    - steps：步骤摘要列表
+    - current_step_id：当前步骤 ID
+    - waiting_approval_key：等待审批键
+    - events_path：证据链 events 定位符
+    """
+
+    run_id: str
+    workflow_id: str
+    workflow_instance_id: str
+    status: WorkflowRunStatus
+    steps: list[WorkflowStepSnapshot] = field(default_factory=list)
+    current_step_id: str | None = None
+    waiting_approval_key: str | None = None
+    events_path: str | None = None
+    host_runtime: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True)
+class WorkflowReplayRequest:
+    """
+    workflow replay 请求。
+
+    参数：
+    - workflow_id：workflow ID
+    - run_id：宿主指定的 replay run ID
+    - from_snapshot：可选上次运行快照
+    - current_input：可选当前输入
+    """
+
+    workflow_id: str
+    run_id: str
+    from_snapshot: WorkflowRunSnapshot | None = None
+    current_input: dict[str, Any] | None = None
+
+
+def summarize_workflow_items(
+    *,
+    workflow_id: str,
+    items: list[Any],
+    terminal: CapabilityResult | None = None,
+) -> WorkflowRunSnapshot:
+    """
+    从 workflow 轻量事件和 terminal result 收敛 WorkflowRunSnapshot。
+
+    参数：
+    - workflow_id：workflow ID
+    - items：workflow 事件列表
+    - terminal：可选终态结果
+    """
+
+    run_id = ""
+    workflow_instance_id = ""
+    current_step_id: str | None = None
+    ordered_steps: list[str] = []
+    steps: dict[str, WorkflowStepSnapshot] = {}
+    final_status: WorkflowRunStatus = WorkflowRunStatus.RUNNING
+
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        typ = str(item.get("type") or "")
+        if not run_id:
+            run_id = str(item.get("run_id") or "")
+        if typ == "workflow.started":
+            workflow_instance_id = str(item.get("workflow_instance_id") or workflow_id)
+            continue
+        if typ == "workflow.step.started":
+            step_id = str(item.get("step_id") or "").strip()
+            if not step_id:
+                continue
+            current_step_id = step_id
+            if step_id not in ordered_steps:
+                ordered_steps.append(step_id)
+            steps[step_id] = WorkflowStepSnapshot(
+                step_id=step_id,
+                status="running",
+                capability_id=_optional_text(item.get("capability_id")),
+            )
+            continue
+        if typ == "workflow.step.finished":
+            step_id = str(item.get("step_id") or "").strip()
+            if not step_id:
+                continue
+            if step_id not in ordered_steps:
+                ordered_steps.append(step_id)
+            status = str(item.get("status") or "pending").strip() or "pending"
+            steps[step_id] = WorkflowStepSnapshot(
+                step_id=step_id,
+                status=status,
+                capability_id=_optional_text(item.get("capability_id")),
+                error=_optional_text(item.get("error")),
+            )
+            if status in {"running", "pending"}:
+                current_step_id = step_id
+            elif current_step_id == step_id:
+                current_step_id = None
+            continue
+        if typ == "workflow.finished":
+            final_status = _map_workflow_status_from_event(str(item.get("status") or "pending"))
+
+    waiting_approval_key = None
+    events_path = None
+    host_runtime: dict[str, Any] | None = None
+    if terminal is not None and terminal.node_report is not None:
+        host_runtime = project_host_runtime_data(terminal, capability_id=workflow_id)
+        if isinstance(host_runtime, dict):
+            final_status = WorkflowRunStatus.WAITING_HUMAN
+            waiting_approval_key = _optional_text(host_runtime.get("approval_key"))
+            host_step_id = _optional_text(host_runtime.get("step_id"))
+            if host_step_id:
+                current_step_id = host_step_id
+        if isinstance(terminal.node_report.events_path, str) and terminal.node_report.events_path:
+            events_path = terminal.node_report.events_path
+        if not run_id:
+            run_id = terminal.node_report.run_id
+
+    if terminal is not None and final_status == WorkflowRunStatus.RUNNING:
+        final_status = _map_workflow_status_from_terminal(terminal.status)
+
+    if not run_id and terminal is not None:
+        run_id = str(terminal.metadata.get("run_id") or "")
+    if not workflow_instance_id:
+        workflow_instance_id = workflow_id
+
+    return WorkflowRunSnapshot(
+        run_id=run_id,
+        workflow_id=workflow_id,
+        workflow_instance_id=workflow_instance_id,
+        status=final_status,
+        steps=[steps[step_id] for step_id in ordered_steps],
+        current_step_id=current_step_id,
+        waiting_approval_key=waiting_approval_key,
+        events_path=events_path,
+        host_runtime=host_runtime,
+    )
+
+
+def _map_workflow_status_from_event(status: str) -> WorkflowRunStatus:
+    """把 workflow 事件状态归一为 WorkflowRunStatus。"""
+
+    normalized = str(status or "").strip()
+    if normalized == "success":
+        return WorkflowRunStatus.COMPLETED
+    if normalized == "failed":
+        return WorkflowRunStatus.FAILED
+    if normalized == "cancelled":
+        return WorkflowRunStatus.CANCELLED
+    return WorkflowRunStatus.RUNNING
+
+
+def _map_workflow_status_from_terminal(status: CapabilityStatus) -> WorkflowRunStatus:
+    """把 terminal CapabilityStatus 映射为 WorkflowRunStatus。"""
+
+    if status == CapabilityStatus.SUCCESS:
+        return WorkflowRunStatus.COMPLETED
+    if status == CapabilityStatus.FAILED:
+        return WorkflowRunStatus.FAILED
+    if status == CapabilityStatus.CANCELLED:
+        return WorkflowRunStatus.CANCELLED
+    return WorkflowRunStatus.RUNNING
+
+
+def _optional_text(value: Any) -> str | None:
+    """把可选值归一为非空字符串。"""
+
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None

capability_runtime-0.1.0.dist-info/METADATA

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: capability-runtime
+Version: 0.1.0
+Summary: Bridge/glue layer that composes Agently (LLM/TriggerFlow) with skills-runtime-sdk (skills/tools/WAL/events).
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: agently==4.0.8
+Requires-Dist: skills-runtime-sdk==0.1.11
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+
+<div align="center">
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+</div>
+
+# capability-runtime
+
+`capability-runtime` is a production-oriented runtime/adapter layer that exposes a
+stable `Runtime` API while composing two upstream systems:
+
+- `skills-runtime-sdk` for skills, tools, approvals, WAL, and event evidence
+- `Agently` for OpenAI-compatible transport and TriggerFlow-based orchestration internals
+
+The public contract of this repository is intentionally narrow:
+
+- capability primitives: `AgentSpec` and `WorkflowSpec`
+- execution entrypoint: `Runtime`
+- evidence surface: `NodeReport`, host snapshots, and service-facade helpers
+
+## What You Get
+
+- A single execution surface: `Runtime.run()` and `Runtime.run_stream()`
+- Public capability registration and manifest descriptors
+- Workflow orchestration on top of the runtime without exposing TriggerFlow as a public API
+- Evidence-first results through `NodeReport`, tool-call reports, approval summaries, and WAL locators
+- Host-facing helpers for wait/resume, approval tickets, continuity, and service streaming
+
+## Architecture At A Glance
+
+```text
+                           +-----------------------------+
+                           | Host Application            |
+                           | - register capabilities     |
+                           | - run / stream / continue   |
+                           +--------------+--------------+
+                                          |
+                                          v
++------------------------------------------------------------------------+
+| capability-runtime                                                     |
+|                                                                        |
+|  Public contract                                                       |
+|  - AgentSpec / WorkflowSpec                                            |
+|  - Runtime                                                             |
+|  - NodeReport / HostRunSnapshot / RuntimeServiceFacade                 |
+|                                                                        |
+|  Internal adapters                                                     |
+|  - AgentAdapter                                                        |
+|  - TriggerFlowWorkflowEngine                                           |
+|  - service/session continuity bridge                                   |
++------------------------------+-----------------------------------------+
+                               |
+                               v
+                 +-------------------------------+
+                 | skills-runtime-sdk            |
+                 | - skills + tools              |
+                 | - approvals + exec sessions   |
+                 | - WAL / AgentEvent evidence   |
+                 +---------------+---------------+
+                                 |
+                                 v
+                 +-------------------------------+
+                 | Agently / TriggerFlow         |
+                 | - OpenAI-compatible transport |
+                 | - workflow execution internals|
+                 +-------------------------------+
+```
+
+## Install
+
+From source:
+
+```bash
+python -m pip install -e .
+```
+
+With development dependencies:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+When the package is published, the install form is:
+
+```bash
+python -m pip install capability-runtime
+```
+
+Import name:
+
+```python
+import capability_runtime
+```
+
+## Quickstart
+
+### 1. Offline runtime loop
+
+```bash
+python examples/01_quickstart/run_mock.py
+```
+
+This path is the smallest reproducible loop:
+
+- register an `AgentSpec`
+- validate the registry
+- run in `mode="mock"`
+- inspect the terminal `CapabilityResult`
+
+### 2. Bridge mode with a real model backend
+
+```bash
+cp examples/01_quickstart/.env.example examples/01_quickstart/.env
+python examples/01_quickstart/run_bridge.py
+```
+
+Bridge mode reuses Agently's OpenAI-compatible transport but still delegates the
+actual skills/tools/WAL semantics to `skills-runtime-sdk`.
+
+### 3. Workflow orchestration
+
+```bash
+python examples/02_workflow/run.py
+```
+
+For a higher-level index, start with [examples/README.md](examples/README.md).
+
+## Public API At A Glance
+
+The package root exposes the supported contract:
+
+```python
+from capability_runtime import (
+    Runtime,
+    RuntimeConfig,
+    CustomTool,
+    AgentSpec,
+    AgentIOSchema,
+    WorkflowSpec,
+    Step,
+    LoopStep,
+    ParallelStep,
+    ConditionalStep,
+    InputMapping,
+    CapabilitySpec,
+    CapabilityKind,
+    CapabilityResult,
+    CapabilityStatus,
+    NodeReport,
+    HostRunSnapshot,
+    ApprovalTicket,
+    ResumeIntent,
+    RuntimeServiceFacade,
+    RuntimeServiceRequest,
+    RuntimeServiceHandle,
+    RuntimeSession,
+)
+```
+
+The runtime currently supports three execution modes through `RuntimeConfig.mode`:
+
+- `mock`: deterministic local testing without a real LLM backend
+- `bridge`: Agently transport + `skills-runtime-sdk` execution semantics
+- `sdk_native`: native `skills-runtime-sdk` backend without Agently transport
+
+## Repository Layout
+
+```text
+.
+├── src/capability_runtime/      # package source
+├── examples/                    # human-facing runnable examples
+├── docs_for_coding_agent/       # compact pack for coding agents
+├── help/                        # public help and operational guides
+├── config/                      # example config shapes
+├── scripts/                     # release / validation helpers
+└── tests/                       # offline regression guardrails
+```
+
+## Documentation Map
+
+- [help/README.md](help/README.md): public help index
+- [examples/README.md](examples/README.md): runnable examples by scenario
+- [docs_for_coding_agent/README.md](docs_for_coding_agent/README.md): compact coding-agent pack
+- [config/README.md](config/README.md): config shape reference
+
+Recommended reading order for new users:
+
+1. [help/00-overview.md](help/00-overview.md)
+2. [help/01-quickstart.md](help/01-quickstart.md)
+3. [help/03-python-api.md](help/03-python-api.md)
+4. [examples/README.md](examples/README.md)
+
+## Release And PyPI Publishing
+
+This repository ships GitHub Actions workflows for:
+
+- Tier-0 CI on push and pull request
+- tag-driven and manual PyPI publishing
+
+Release guardrails:
+
+- the Git tag must match `pyproject.toml`'s `[project].version`
+- the Git tag must match `capability_runtime.__version__`
+- the publish job builds both sdist and wheel before uploading
+
+The publish workflow is designed for PyPI Trusted Publishing. You still need to
+configure the corresponding Trusted Publisher entry on `pypi.org`.
+
+## Relationship To The Upstreams
+
+- `skills-runtime-sdk` remains the source of truth for skills, approvals, tools,
+  WAL, and event evidence.
+- `Agently` remains the transport/orchestration substrate where this repository
+  chooses to bridge instead of forking or reimplementing.
+- `capability-runtime` is the contract-convergence layer: it narrows those
+  upstream capabilities into a smaller host-facing runtime surface.