agent-harness-aibom 0.1.0__tar.gz

agent_harness_aibom-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the agent-harness-aibom contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_harness_aibom-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: agent-harness-aibom
+Version: 0.1.0
+Summary: AIBOM generator for AI agent harnesses (Hermes, OpenClaw) and their model/skill/MCP/hook surface
+Author: Practical DevSecOps
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# agent-harness-aibom
+
+An AIBOM (AI Bill of Materials) generator for AI agent harnesses —
+currently Hermes and [OpenClaw](https://docs.openclaw.ai) — that emits standard CycloneDX 1.6
+JSON extended with harness-specific fields (skill fingerprints, MCP server
+TLS/auth posture, hook approval state, model provenance). See
+[`SPEC.md`](SPEC.md) for the full data model and its rationale.
+
+This is the "ground truth" layer for a broader exercise: scan a real
+harness with this tool, scan the same harness with a general-purpose
+scanner (e.g. Cisco AI BOM), and diff what each one saw.
+
+## Install
+
+```bash
+pip install -e ".[dev]"   # from a checkout, for development
+```
+
+(Not yet published to PyPI.)
+
+## Usage
+
+```bash
+# Auto-detect and scan whatever's installed under $HOME
+harness-aibom scan --runtime auto -o aibom.json
+
+# Scan a specific runtime explicitly
+harness-aibom scan --runtime hermes -o hermes-aibom.json
+harness-aibom scan --runtime openclaw -o openclaw-aibom.json
+
+# Check a document's shape
+harness-aibom validate aibom.json
+
+# Compare two scans -- e.g. before/after a suspected skill compromise
+harness-aibom diff before.json after.json
+```
+
+`scan` runs entirely against the local filesystem and local subprocesses/
+HTTP calls (`hermes`/`openclaw` CLIs, Ollama's `/api/tags`). To scan a
+remote lab VM, install the package there (or SSH in and run it) — there's
+no built-in remote transport yet.
+
+Missing pieces are never fatal: if `hermes` isn't on `PATH`, or Ollama
+isn't reachable, the scan still completes and prints a `warning[...]` line
+to stderr explaining what it skipped, so students can see exactly what
+partial information looks like.
+
+## Example output
+
+[`examples/hermes-aibom.example.json`](examples/hermes-aibom.example.json)
+and [`examples/openclaw-aibom.example.json`](examples/openclaw-aibom.example.json)
+were generated by running `scan` against the test fixtures in
+`tests/fixtures/` (a synthetic `config.yaml`/`openclaw.json`, no live
+`hermes`/`openclaw`/`ollama` on this machine) — a realistic example of
+graceful degradation when the runtime binary isn't present.
+
+## Project layout
+
+```
+src/harness_aibom/
+├── model.py          # Component / HarnessDocument -- the in-memory data model
+├── cyclonedx.py       # model.py -> CycloneDX 1.6 JSON
+├── fingerprint.py      # sha256 helpers
+├── validate.py         # structural checks on a harness-aibom document
+├── diff.py             # before/after comparison
+├── cli.py               # `harness-aibom` entrypoint
+└── collectors/
+    ├── base.py          # Collector ABC
+    ├── ollama.py         # shared: model discovery via Ollama's HTTP API
+    ├── mcp.py             # shared: MCP server extraction from a config dict
+    ├── secrets.py          # shared: secrets-surface discovery (paths/perms only)
+    ├── hermes.py            # Hermes collector
+    └── openclaw.py          # OpenClaw collector
+```
+
+## CI and publishing
+
+- `.github/workflows/ci.yml` runs the test suite and a CLI smoke test on
+  every push and pull request, on Python 3.10, 3.11, and 3.12.
+- `.github/workflows/publish.yml` builds and publishes the package to PyPI
+  when you publish a GitHub Release. It uses PyPI Trusted Publishing, so no
+  password lives in this repo. One-time setup before your first release:
+  1. Go to <https://pypi.org/manage/account/publishing/>.
+  2. Add a new trusted publisher for project `agent-harness-aibom`.
+  3. Set the owner and repo name to match this GitHub repo.
+  4. Set the workflow name to `publish.yml`.
+  5. Set the environment name to `pypi`.
+
+## Testing
+
+```bash
+pytest -q
+```
+
+Collector tests run entirely against fixtures under `tests/fixtures/`
+(`hermes_home/`, `openclaw_home/`) with injected fake `run`/`fetch`
+functions — no real `hermes`/`openclaw`/`ollama` needed to run the suite.
+
+## Roadmap
+
+This is v0.1 — the spec plus two working collectors. Natural next steps,
+roughly in order:
+
+1. Harden hook parsing against a live Hermes box (see `SPEC.md` §5).
+2. Point this at the actual CAASP lab VMs and fix whatever the real output
+   shapes get wrong.
+3. Scan the same harness with Cisco AI BOM and diff the two documents —
+   the gap-analysis exercise this package exists to support.
+4. cosign signing/provenance for the emitted AIBOM.
+5. Package for PyPI.

agent_harness_aibom-0.1.0/README.md

@@ -0,0 +1,110 @@
+# agent-harness-aibom
+
+An AIBOM (AI Bill of Materials) generator for AI agent harnesses —
+currently Hermes and [OpenClaw](https://docs.openclaw.ai) — that emits standard CycloneDX 1.6
+JSON extended with harness-specific fields (skill fingerprints, MCP server
+TLS/auth posture, hook approval state, model provenance). See
+[`SPEC.md`](SPEC.md) for the full data model and its rationale.
+
+This is the "ground truth" layer for a broader exercise: scan a real
+harness with this tool, scan the same harness with a general-purpose
+scanner (e.g. Cisco AI BOM), and diff what each one saw.
+
+## Install
+
+```bash
+pip install -e ".[dev]"   # from a checkout, for development
+```
+
+(Not yet published to PyPI.)
+
+## Usage
+
+```bash
+# Auto-detect and scan whatever's installed under $HOME
+harness-aibom scan --runtime auto -o aibom.json
+
+# Scan a specific runtime explicitly
+harness-aibom scan --runtime hermes -o hermes-aibom.json
+harness-aibom scan --runtime openclaw -o openclaw-aibom.json
+
+# Check a document's shape
+harness-aibom validate aibom.json
+
+# Compare two scans -- e.g. before/after a suspected skill compromise
+harness-aibom diff before.json after.json
+```
+
+`scan` runs entirely against the local filesystem and local subprocesses/
+HTTP calls (`hermes`/`openclaw` CLIs, Ollama's `/api/tags`). To scan a
+remote lab VM, install the package there (or SSH in and run it) — there's
+no built-in remote transport yet.
+
+Missing pieces are never fatal: if `hermes` isn't on `PATH`, or Ollama
+isn't reachable, the scan still completes and prints a `warning[...]` line
+to stderr explaining what it skipped, so students can see exactly what
+partial information looks like.
+
+## Example output
+
+[`examples/hermes-aibom.example.json`](examples/hermes-aibom.example.json)
+and [`examples/openclaw-aibom.example.json`](examples/openclaw-aibom.example.json)
+were generated by running `scan` against the test fixtures in
+`tests/fixtures/` (a synthetic `config.yaml`/`openclaw.json`, no live
+`hermes`/`openclaw`/`ollama` on this machine) — a realistic example of
+graceful degradation when the runtime binary isn't present.
+
+## Project layout
+
+```
+src/harness_aibom/
+├── model.py          # Component / HarnessDocument -- the in-memory data model
+├── cyclonedx.py       # model.py -> CycloneDX 1.6 JSON
+├── fingerprint.py      # sha256 helpers
+├── validate.py         # structural checks on a harness-aibom document
+├── diff.py             # before/after comparison
+├── cli.py               # `harness-aibom` entrypoint
+└── collectors/
+    ├── base.py          # Collector ABC
+    ├── ollama.py         # shared: model discovery via Ollama's HTTP API
+    ├── mcp.py             # shared: MCP server extraction from a config dict
+    ├── secrets.py          # shared: secrets-surface discovery (paths/perms only)
+    ├── hermes.py            # Hermes collector
+    └── openclaw.py          # OpenClaw collector
+```
+
+## CI and publishing
+
+- `.github/workflows/ci.yml` runs the test suite and a CLI smoke test on
+  every push and pull request, on Python 3.10, 3.11, and 3.12.
+- `.github/workflows/publish.yml` builds and publishes the package to PyPI
+  when you publish a GitHub Release. It uses PyPI Trusted Publishing, so no
+  password lives in this repo. One-time setup before your first release:
+  1. Go to <https://pypi.org/manage/account/publishing/>.
+  2. Add a new trusted publisher for project `agent-harness-aibom`.
+  3. Set the owner and repo name to match this GitHub repo.
+  4. Set the workflow name to `publish.yml`.
+  5. Set the environment name to `pypi`.
+
+## Testing
+
+```bash
+pytest -q
+```
+
+Collector tests run entirely against fixtures under `tests/fixtures/`
+(`hermes_home/`, `openclaw_home/`) with injected fake `run`/`fetch`
+functions — no real `hermes`/`openclaw`/`ollama` needed to run the suite.
+
+## Roadmap
+
+This is v0.1 — the spec plus two working collectors. Natural next steps,
+roughly in order:
+
+1. Harden hook parsing against a live Hermes box (see `SPEC.md` §5).
+2. Point this at the actual CAASP lab VMs and fix whatever the real output
+   shapes get wrong.
+3. Scan the same harness with Cisco AI BOM and diff the two documents —
+   the gap-analysis exercise this package exists to support.
+4. cosign signing/provenance for the emitted AIBOM.
+5. Package for PyPI.

agent_harness_aibom-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "agent-harness-aibom"
+version = "0.1.0"
+description = "AIBOM generator for AI agent harnesses (Hermes, OpenClaw) and their model/skill/MCP/hook surface"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Practical DevSecOps" }]
+dependencies = [
+    "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[project.scripts]
+harness-aibom = "harness_aibom.cli:main"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

agent_harness_aibom-0.1.0/setup.cfg

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

agent_harness_aibom-0.1.0/src/agent_harness_aibom.egg-info/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: agent-harness-aibom
+Version: 0.1.0
+Summary: AIBOM generator for AI agent harnesses (Hermes, OpenClaw) and their model/skill/MCP/hook surface
+Author: Practical DevSecOps
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# agent-harness-aibom
+
+An AIBOM (AI Bill of Materials) generator for AI agent harnesses —
+currently Hermes and [OpenClaw](https://docs.openclaw.ai) — that emits standard CycloneDX 1.6
+JSON extended with harness-specific fields (skill fingerprints, MCP server
+TLS/auth posture, hook approval state, model provenance). See
+[`SPEC.md`](SPEC.md) for the full data model and its rationale.
+
+This is the "ground truth" layer for a broader exercise: scan a real
+harness with this tool, scan the same harness with a general-purpose
+scanner (e.g. Cisco AI BOM), and diff what each one saw.
+
+## Install
+
+```bash
+pip install -e ".[dev]"   # from a checkout, for development
+```
+
+(Not yet published to PyPI.)
+
+## Usage
+
+```bash
+# Auto-detect and scan whatever's installed under $HOME
+harness-aibom scan --runtime auto -o aibom.json
+
+# Scan a specific runtime explicitly
+harness-aibom scan --runtime hermes -o hermes-aibom.json
+harness-aibom scan --runtime openclaw -o openclaw-aibom.json
+
+# Check a document's shape
+harness-aibom validate aibom.json
+
+# Compare two scans -- e.g. before/after a suspected skill compromise
+harness-aibom diff before.json after.json
+```
+
+`scan` runs entirely against the local filesystem and local subprocesses/
+HTTP calls (`hermes`/`openclaw` CLIs, Ollama's `/api/tags`). To scan a
+remote lab VM, install the package there (or SSH in and run it) — there's
+no built-in remote transport yet.
+
+Missing pieces are never fatal: if `hermes` isn't on `PATH`, or Ollama
+isn't reachable, the scan still completes and prints a `warning[...]` line
+to stderr explaining what it skipped, so students can see exactly what
+partial information looks like.
+
+## Example output
+
+[`examples/hermes-aibom.example.json`](examples/hermes-aibom.example.json)
+and [`examples/openclaw-aibom.example.json`](examples/openclaw-aibom.example.json)
+were generated by running `scan` against the test fixtures in
+`tests/fixtures/` (a synthetic `config.yaml`/`openclaw.json`, no live
+`hermes`/`openclaw`/`ollama` on this machine) — a realistic example of
+graceful degradation when the runtime binary isn't present.
+
+## Project layout
+
+```
+src/harness_aibom/
+├── model.py          # Component / HarnessDocument -- the in-memory data model
+├── cyclonedx.py       # model.py -> CycloneDX 1.6 JSON
+├── fingerprint.py      # sha256 helpers
+├── validate.py         # structural checks on a harness-aibom document
+├── diff.py             # before/after comparison
+├── cli.py               # `harness-aibom` entrypoint
+└── collectors/
+    ├── base.py          # Collector ABC
+    ├── ollama.py         # shared: model discovery via Ollama's HTTP API
+    ├── mcp.py             # shared: MCP server extraction from a config dict
+    ├── secrets.py          # shared: secrets-surface discovery (paths/perms only)
+    ├── hermes.py            # Hermes collector
+    └── openclaw.py          # OpenClaw collector
+```
+
+## CI and publishing
+
+- `.github/workflows/ci.yml` runs the test suite and a CLI smoke test on
+  every push and pull request, on Python 3.10, 3.11, and 3.12.
+- `.github/workflows/publish.yml` builds and publishes the package to PyPI
+  when you publish a GitHub Release. It uses PyPI Trusted Publishing, so no
+  password lives in this repo. One-time setup before your first release:
+  1. Go to <https://pypi.org/manage/account/publishing/>.
+  2. Add a new trusted publisher for project `agent-harness-aibom`.
+  3. Set the owner and repo name to match this GitHub repo.
+  4. Set the workflow name to `publish.yml`.
+  5. Set the environment name to `pypi`.
+
+## Testing
+
+```bash
+pytest -q
+```
+
+Collector tests run entirely against fixtures under `tests/fixtures/`
+(`hermes_home/`, `openclaw_home/`) with injected fake `run`/`fetch`
+functions — no real `hermes`/`openclaw`/`ollama` needed to run the suite.
+
+## Roadmap
+
+This is v0.1 — the spec plus two working collectors. Natural next steps,
+roughly in order:
+
+1. Harden hook parsing against a live Hermes box (see `SPEC.md` §5).
+2. Point this at the actual CAASP lab VMs and fix whatever the real output
+   shapes get wrong.
+3. Scan the same harness with Cisco AI BOM and diff the two documents —
+   the gap-analysis exercise this package exists to support.
+4. cosign signing/provenance for the emitted AIBOM.
+5. Package for PyPI.

agent_harness_aibom-0.1.0/src/agent_harness_aibom.egg-info/SOURCES.txt

@@ -0,0 +1,30 @@
+LICENSE
+README.md
+pyproject.toml
+src/agent_harness_aibom.egg-info/PKG-INFO
+src/agent_harness_aibom.egg-info/SOURCES.txt
+src/agent_harness_aibom.egg-info/dependency_links.txt
+src/agent_harness_aibom.egg-info/entry_points.txt
+src/agent_harness_aibom.egg-info/requires.txt
+src/agent_harness_aibom.egg-info/top_level.txt
+src/harness_aibom/__init__.py
+src/harness_aibom/cli.py
+src/harness_aibom/cyclonedx.py
+src/harness_aibom/diff.py
+src/harness_aibom/fingerprint.py
+src/harness_aibom/model.py
+src/harness_aibom/validate.py
+src/harness_aibom/collectors/__init__.py
+src/harness_aibom/collectors/base.py
+src/harness_aibom/collectors/hermes.py
+src/harness_aibom/collectors/mcp.py
+src/harness_aibom/collectors/ollama.py
+src/harness_aibom/collectors/openclaw.py
+src/harness_aibom/collectors/secrets.py
+tests/test_cli.py
+tests/test_cyclonedx.py
+tests/test_diff.py
+tests/test_fingerprint.py
+tests/test_hermes_collector.py
+tests/test_openclaw_collector.py
+tests/test_validate.py

agent_harness_aibom-0.1.0/src/agent_harness_aibom.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_harness_aibom-0.1.0/src/agent_harness_aibom.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+harness-aibom = harness_aibom.cli:main

agent_harness_aibom-0.1.0/src/agent_harness_aibom.egg-info/requires.txt

@@ -0,0 +1,4 @@
+PyYAML>=6.0
+
+[dev]
+pytest>=8.0

agent_harness_aibom-0.1.0/src/agent_harness_aibom.egg-info/top_level.txt

@@ -0,0 +1 @@
+harness_aibom

agent_harness_aibom-0.1.0/src/harness_aibom/__init__.py

@@ -0,0 +1,10 @@
+"""agent-harness-aibom: an AIBOM generator for AI agent harnesses.
+
+This package answers a narrower question than a general-purpose AI BOM
+scanner: what exactly constitutes a *deployed agent harness* -- its runtime
+binary, the model endpoint(s) it talks to, the configuration and skills it
+loads, the MCP servers and hooks it can reach, and the secrets surface
+around all of that. See SPEC.md at the repo root for the full data model.
+"""
+
+__version__ = "0.1.0"

agent_harness_aibom-0.1.0/src/harness_aibom/cli.py

@@ -0,0 +1,109 @@
+"""`harness-aibom` command-line entrypoint: scan / validate / diff."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .collectors.hermes import HermesCollector
+from .collectors.openclaw import OpenClawCollector
+from .cyclonedx import current_hostname, to_cyclonedx
+from .diff import diff_documents
+from .model import HarnessDocument
+from .validate import validate_document
+
+COLLECTORS = {
+    "hermes": HermesCollector,
+    "openclaw": OpenClawCollector,
+}
+
+
+def _run_scan(args: argparse.Namespace) -> int:
+    home = Path(args.home).expanduser() if args.home else Path.home()
+
+    if args.runtime == "auto":
+        candidates = [cls(home=home) for cls in COLLECTORS.values()]
+        active = [c for c in candidates if c.is_present()]
+        if not active:
+            print(f"no supported runtime found under {home}", file=sys.stderr)
+            return 1
+    else:
+        active = [COLLECTORS[args.runtime](home=home)]
+
+    for collector in active:
+        doc = HarnessDocument(
+            harness_name=f"{collector.runtime_kind}@{current_hostname()}",
+            runtime_kind=collector.runtime_kind,
+            hostname=current_hostname(),
+        )
+        collector.collect(doc)
+        for w in doc.warnings:
+            print(f"warning[{collector.runtime_kind}]: {w}", file=sys.stderr)
+
+        bom = to_cyclonedx(doc)
+        text = json.dumps(bom, indent=2 if args.pretty else None)
+
+        if args.output:
+            out_path = Path(args.output)
+            if len(active) > 1:
+                out_path = out_path.with_name(f"{collector.runtime_kind}-{out_path.name}")
+            out_path.write_text(text + "\n")
+            print(f"wrote {out_path}")
+        else:
+            print(text)
+
+    return 0
+
+
+def _run_validate(args: argparse.Namespace) -> int:
+    data = json.loads(Path(args.file).read_text())
+    errors = validate_document(data)
+    if errors:
+        for e in errors:
+            print(f"error: {e}", file=sys.stderr)
+        return 1
+    print(f"{args.file}: valid")
+    return 0
+
+
+def _run_diff(args: argparse.Namespace) -> int:
+    before = json.loads(Path(args.before).read_text())
+    after = json.loads(Path(args.after).read_text())
+    print(json.dumps(diff_documents(before, after), indent=2))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="harness-aibom")
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    scan = sub.add_parser("scan", help="scan a running harness and emit a CycloneDX AIBOM")
+    scan.add_argument("--runtime", choices=["auto", *COLLECTORS], default="auto")
+    scan.add_argument("--home", help="home directory to scan under (default: current user's)")
+    scan.add_argument("--output", "-o", help="write to this file instead of stdout")
+    scan.add_argument("--pretty", action="store_true", default=True, help="pretty-print JSON (default: on)")
+    scan.set_defaults(func=_run_scan)
+
+    validate = sub.add_parser("validate", help="check a harness-aibom JSON document's shape")
+    validate.add_argument("file")
+    validate.set_defaults(func=_run_validate)
+
+    diff = sub.add_parser("diff", help="compare two harness-aibom documents, e.g. before/after a suspected compromise")
+    diff.add_argument("before")
+    diff.add_argument("after")
+    diff.set_defaults(func=_run_diff)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent_harness_aibom-0.1.0/src/harness_aibom/collectors/__init__.py

@@ -0,0 +1,2 @@
+"""Runtime-specific collectors. Each module here implements one Collector
+subclass (see base.py) for one agent harness product (Hermes, OpenClaw)."""

agent_harness_aibom-0.1.0/src/harness_aibom/collectors/base.py

@@ -0,0 +1,33 @@
+"""Collector base class shared by every runtime-specific collector."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from ..model import HarnessDocument
+
+
+class Collector(ABC):
+    """One collector = one runtime kind (hermes, openclaw, ...).
+
+    A collector never raises just because the runtime isn't installed --
+    it records that via `doc.warn()` and adds nothing. It should only raise
+    for genuine programmer errors (e.g. a broken test fixture), not for
+    "this piece is missing on this machine".
+    """
+
+    runtime_kind: str
+
+    def __init__(self, home: Path | None = None):
+        self.home = home or Path.home()
+
+    @abstractmethod
+    def is_present(self) -> bool:
+        """Cheap, side-effect-free check: does this runtime look installed
+        under self.home? Used by `scan --runtime auto`."""
+
+    @abstractmethod
+    def collect(self, doc: HarnessDocument) -> None:
+        """Populate doc with every component/relationship this collector
+        can find. Must not raise for missing-but-optional pieces."""