capability-runtime 0.1.0__tar.gz

capability_runtime-0.1.0/PKG-INFO

@@ -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.

capability_runtime-0.1.0/README.md

@@ -0,0 +1,216 @@
+<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.

capability_runtime-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "capability-runtime"
+version = "0.1.0"
+description = "Bridge/glue layer that composes Agently (LLM/TriggerFlow) with skills-runtime-sdk (skills/tools/WAL/events)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+  "PyYAML>=6",
+  "pydantic>=2,<3",
+  "agently==4.0.8",
+  "skills-runtime-sdk==0.1.11",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7",
+  "pytest-asyncio>=0.23",
+  "mypy>=1.8",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+  "integration: optional integration tests (may require docker/services)",
+]
+
+[tool.mypy]
+python_version = "3.10"
+mypy_path = "src"
+explicit_package_bases = true
+ignore_missing_imports = true
+warn_unused_ignores = false
+warn_unused_configs = true
+disable_error_code = ["import-untyped"]
+
+[[tool.mypy.overrides]]
+module = ["examples.*"]
+ignore_errors = true
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"

capability_runtime-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

capability_runtime-0.1.0/src/capability_runtime/__init__.py

@@ -0,0 +1,90 @@
+"""capability-runtime：统一 Runtime 入口（能力协议 + 执行 + 报告）。"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+# === 统一入口 ===
+from .config import CustomTool, RuntimeConfig
+from .runtime import Runtime
+from .service_facade import RuntimeServiceFacade, RuntimeServiceHandle, RuntimeServiceRequest, RuntimeSession
+from .structured_stream import StructuredStreamEvent
+
+# === 报告类型 ===
+from .types import NodeReport, NodeResult
+
+# === Host toolkit（精选公共导出）===
+from .host_toolkit import InvokeCapabilityAllowlist, make_invoke_capability_tool
+from .host_protocol import ApprovalTicket, HostRunSnapshot, HostRunStatus, ResumeIntent
+from .manifest import CapabilityDescriptor, CapabilityManifestEntry, CapabilityVisibility
+
+# === Protocol 导出 ===
+from .protocol.agent import AgentIOSchema, AgentSpec
+from .protocol.capability import (
+    CapabilityKind,
+    CapabilityRef,
+    CapabilityResult,
+    CapabilitySpec,
+    CapabilityStatus,
+)
+from .protocol.context import ExecutionContext
+from .protocol.workflow import (
+    ConditionalStep,
+    InputMapping,
+    LoopStep,
+    ParallelStep,
+    Step,
+    WorkflowSpec,
+)
+from .services import RuntimeServices
+from .workflow_runtime import WorkflowReplayRequest, WorkflowRunSnapshot, WorkflowRunStatus, WorkflowStepSnapshot
+
+# === 错误导出 ===
+from .errors import CapabilityNotFoundError, RuntimeFrameworkError
+
+__all__ = [
+    # Runtime
+    "Runtime",
+    "RuntimeConfig",
+    "CustomTool",
+    "StructuredStreamEvent",
+    # Reports
+    "NodeReport",
+    "NodeResult",
+    # Host toolkit (selected)
+    "InvokeCapabilityAllowlist",
+    "make_invoke_capability_tool",
+    # Protocol
+    "CapabilityKind",
+    "CapabilityRef",
+    "CapabilitySpec",
+    "CapabilityStatus",
+    "CapabilityResult",
+    "CapabilityManifestEntry",
+    "CapabilityDescriptor",
+    "CapabilityVisibility",
+    "HostRunStatus",
+    "ApprovalTicket",
+    "ResumeIntent",
+    "HostRunSnapshot",
+    "WorkflowRunStatus",
+    "WorkflowStepSnapshot",
+    "WorkflowRunSnapshot",
+    "WorkflowReplayRequest",
+    "RuntimeSession",
+    "RuntimeServiceRequest",
+    "RuntimeServiceHandle",
+    "RuntimeServiceFacade",
+    "AgentSpec",
+    "AgentIOSchema",
+    "WorkflowSpec",
+    "Step",
+    "LoopStep",
+    "ParallelStep",
+    "ConditionalStep",
+    "InputMapping",
+    "ExecutionContext",
+    "RuntimeServices",
+    # Errors
+    "RuntimeFrameworkError",
+    "CapabilityNotFoundError",
+]

capability_runtime-0.1.0/src/capability_runtime/adapters/__init__.py

@@ -0,0 +1,13 @@
+"""Adapters：桥接上游与能力组织层。"""
+from __future__ import annotations
+
+# 已有桥接适配器（不修改）
+# from .agently_backend import AgentlyChatBackend
+# from .triggerflow_tool import ...
+
+# 新增能力适配器
+from .agent_adapter import AgentAdapter
+
+__all__ = [
+    "AgentAdapter",
+]