feat(harnessx): configurable provider + per-task budget caps

Add a [harnessx] config block so the agentic plane can be steered from
openultrasast.toml, and make the LLM provider selectable (the hunter and verifier
previously hardcoded AnthropicProvider).

- config.HarnessxConfig: provider ("anthropic"|"openai"|"litellm", default
  anthropic), max_cost_usd (2.0), token_threshold (120000); parsed from [harnessx].
- harness_ext.build_provider: single lazy, capability-guarded provider factory.
  The provider name is validated before any import, so an unknown choice fails with
  a clear ValueError even when the extra is absent; each provider reads its own
  standard key env var (openai -> OPENAI_API_KEY, anthropic -> ANTHROPIC_API_KEY).
- HxScanOrchestrator and verify_findings_dispatch take a provider and route through
  build_provider; cli threads config.harnessx.{provider,max_cost_usd,token_threshold}
  into both the hunter and the verifier.
- README: "Configuring the HarnessX agentic plane" section (install, models,
  provider, budgets, fallback/degradation).

Test isolation: convert the "harnessx not in sys.modules" import-guards to a
hermetic subprocess fixture (tests/conftest.py assert_cold_of_harnessx) and
simulate extra-absent in the CLI dispatch tests, so the suite is deterministic
whether or not the optional extra is installed (it now is, locally). Verified the
OpenAI path constructs end-to-end (build_provider -> OpenAIProvider; orchestrator
-> Harness) with the budget threaded through.

137 passed, 3 skipped; ruff + mypy clean; detection gate PASS.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

tests/conftest.py

@@ -0,0 +1,33 @@
+"""Shared test fixtures."""
+
+import subprocess
+import sys
+
+import pytest
+
+_HARNESSX_GUARD = (
+    "\nimport sys as _sys\n"
+    "_leaked = sorted(m for m in _sys.modules if m == 'harnessx' or m.startswith('harnessx.'))\n"
+    "assert not _leaked, 'leaked harnessx modules: ' + repr(_leaked)\n"
+)
+
+
+@pytest.fixture
+def assert_cold_of_harnessx():  # type: ignore[no-untyped-def]
+    """Run ``code`` in a fresh interpreter and assert it imported no ``harnessx`` module.
+
+    Hermetic by construction: the lazy-import guarantee is verified the same way
+    whether or not the optional extra is installed in this environment (a global
+    ``sys.modules`` check would be polluted by other tests once the extra is present).
+    """
+
+    def _check(code: str) -> str:
+        proc = subprocess.run(
+            [sys.executable, "-c", code + _HARNESSX_GUARD],
+            capture_output=True,
+            text=True,
+        )
+        assert proc.returncode == 0, f"exit={proc.returncode}\nstdout={proc.stdout}\nstderr={proc.stderr}"
+        return proc.stdout
+
+    return _check

tests/test_cli_hx_dispatch.py

@@ -1,8 +1,10 @@
 """CLI capability-gated dispatch + graceful degradation (Phase 3 task 6.5).
 
-These run in the default (extra-absent) environment: standard mode with models
-configured must fall back to the deterministic hunter/structural verifier and
-record a degradation; with no models configured the manifest stays byte-identical.
+Simulates the extra-absent environment (via a monkeypatched capability probe so the
+behaviour is deterministic whether or not the optional extra is installed): standard
+mode with models configured must fall back to the deterministic hunter/structural
+verifier and record a degradation; with no models configured the manifest stays
+byte-identical.
 """
 
 import json
@@ -20,6 +22,7 @@ def _run(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, config_body: str | Non
     repo = tmp_path / "repo"
     repo.mkdir()
     (repo / "app.py").write_text(_VULN)
+    monkeypatch.setattr(cli, "has_harnessx", lambda: False)  # simulate the extra being absent
     monkeypatch.setenv("OPENULTRASAST_RUNS_DIR", ".runs")
     argv = ["scan", str(repo), "--mode", "standard"]
     if config_body is not None:
@@ -32,7 +35,6 @@ def _run(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, config_body: str | Non
 
 
 def test_degradation_recorded_when_models_set_but_extra_absent(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
-    assert not cli.has_harnessx()  # this CI env has no harnessx extra
     manifest = _run(tmp_path, monkeypatch, '[models]\nhunter = "anthropic/claude"\nverifier = "anthropic/claude"\n')
 
     degradations = manifest.get("degradations", [])

tests/test_config.py

@@ -28,6 +28,33 @@ def test_load_config_reads_toml(tmp_path: Path) -> None:
     assert config.dynamic.network_scope == ("127.0.0.1:8080",)
 
 
+def test_harnessx_defaults_when_section_absent() -> None:
+    config = load_config(None)
+    assert config.harnessx.provider == "anthropic"
+    assert config.harnessx.max_cost_usd == 2.0
+    assert config.harnessx.token_threshold == 120_000
+
+
+def test_load_config_reads_harnessx_section(tmp_path: Path) -> None:
+    config_path = tmp_path / "openultrasast.toml"
+    config_path.write_text(
+        "\n".join(
+            [
+                "[harnessx]",
+                'provider = "openai"',
+                "max_cost_usd = 5.0",
+                "token_threshold = 200000",
+            ]
+        )
+    )
+
+    config = load_config(config_path)
+
+    assert config.harnessx.provider == "openai"
+    assert config.harnessx.max_cost_usd == 5.0
+    assert config.harnessx.token_threshold == 200_000
+
+
 def test_write_resolved_config_creates_json(tmp_path: Path) -> None:
     output = tmp_path / "run" / "resolved_config.json"
 

tests/test_harness_ext.py

@@ -1,13 +1,19 @@
 """HarnessX optional-extra packaging + capability guard (Phase 3 task 5.2)."""
 
 import re
-import sys
 import tomllib
 from pathlib import Path
 
 import pytest
 
-from openultrasast.harness_ext import HARNESSX_EXTRA, HarnessXUnavailableError, has_harnessx, require_harnessx
+from openultrasast.harness_ext import (
+    HARNESSX_EXTRA,
+    SUPPORTED_PROVIDERS,
+    HarnessXUnavailableError,
+    build_provider,
+    has_harnessx,
+    require_harnessx,
+)
 
 PYPROJECT = tomllib.loads(Path("pyproject.toml").read_text())
 
@@ -25,18 +31,15 @@ def test_harnessx_is_a_sha_pinned_optional_extra() -> None:
     ), extras[0]
 
 
-def test_importing_openultrasast_does_not_import_harnessx() -> None:
+def test_importing_openultrasast_does_not_import_harnessx(assert_cold_of_harnessx) -> None:  # type: ignore[no-untyped-def]
     # The big modules (cli, harness_ext) must not eagerly import the heavy extra.
-    import openultrasast.cli  # noqa: F401
-    import openultrasast.harness_ext  # noqa: F401
-
-    assert "harnessx" not in sys.modules
+    assert_cold_of_harnessx("import openultrasast.cli\nimport openultrasast.harness_ext")
 
 
-def test_has_harnessx_probes_without_importing() -> None:
-    available = has_harnessx()
-    assert isinstance(available, bool)
-    assert "harnessx" not in sys.modules  # find_spec must not import the module
+def test_has_harnessx_probes_without_importing(assert_cold_of_harnessx) -> None:  # type: ignore[no-untyped-def]
+    assert isinstance(has_harnessx(), bool)
+    # find_spec must not import the module.
+    assert_cold_of_harnessx("from openultrasast.harness_ext import has_harnessx\nassert isinstance(has_harnessx(), bool)")
 
 
 def test_require_harnessx_raises_with_install_guidance_when_absent() -> None:
@@ -44,3 +47,27 @@ def test_require_harnessx_raises_with_install_guidance_when_absent() -> None:
         pytest.skip("HarnessX extra is installed in this environment")
     with pytest.raises(HarnessXUnavailableError, match=re.escape(HARNESSX_EXTRA)):
         require_harnessx()
+
+
+def test_build_provider_rejects_unknown_provider_before_importing(assert_cold_of_harnessx) -> None:  # type: ignore[no-untyped-def]
+    # Name is validated before any import, so this fails loudly even without the extra.
+    with pytest.raises(ValueError, match="unknown HarnessX provider"):
+        build_provider("gpt-4o", "bogus")
+    assert_cold_of_harnessx(
+        "from openultrasast.harness_ext import build_provider\n"
+        "try:\n    build_provider('gpt-4o', 'bogus')\n"
+        "except ValueError:\n    pass\n"
+        "else:\n    raise SystemExit('expected ValueError')\n"
+    )
+
+
+def test_supported_providers_cover_anthropic_and_openai() -> None:
+    assert {"anthropic", "openai"} <= set(SUPPORTED_PROVIDERS)
+
+
+@pytest.mark.parametrize(("provider", "class_name"), [("anthropic", "AnthropicProvider"), ("openai", "OpenAIProvider")])
+def test_build_provider_constructs_selected_provider(provider: str, class_name: str) -> None:
+    if not has_harnessx():
+        pytest.skip("HarnessX extra not installed in this environment")
+    built = build_provider("test-model", provider)
+    assert type(built).__name__ == class_name

tests/test_hunter_harness.py

@@ -1,17 +1,13 @@
 """HarnessX hunter sub-harness: guarding, findings parsing, construction smoke (task 6.1)."""
 
-import sys
-
 import pytest
 
 from openultrasast.harness_ext import HarnessXUnavailableError, build_sast, has_harnessx
 from openultrasast.hunter_harness import HxScanOrchestrator, _extract_findings
 
 
-def test_module_import_does_not_pull_harnessx() -> None:
-    import openultrasast.hunter_harness  # noqa: F401
-
-    assert "harnessx" not in sys.modules
+def test_module_import_does_not_pull_harnessx(assert_cold_of_harnessx) -> None:  # type: ignore[no-untyped-def]
+    assert_cold_of_harnessx("import openultrasast.hunter_harness")
 
 
 def test_extract_findings_parses_json_array_and_tolerates_garbage() -> None:

tests/test_verify_judge.py

@@ -1,7 +1,5 @@
 """Verifier dispatcher: structural fallback (default) + judge verdict mapping (Phase 3 task 6.4)."""
 
-import sys
-
 from openultrasast.findings import StaticFinding
 from openultrasast.verification import VerificationStatus, verify_findings
 from openultrasast.verify_judge import _verdict_to_verification, verify_findings_dispatch
@@ -40,9 +38,20 @@ def test_dispatch_stays_structural_when_model_unset_or_extra_absent() -> None:
     assert verify_findings_dispatch(findings, verifier_model="claude-x", use_harnessx=False) == verify_findings(findings)
 
 
-def test_dispatch_does_not_import_harnessx_on_fallback() -> None:
-    verify_findings_dispatch([_finding()], verifier_model="claude-x", use_harnessx=True)
-    assert "harnessx" not in sys.modules
+def test_dispatch_does_not_import_harnessx_on_fallback(assert_cold_of_harnessx) -> None:  # type: ignore[no-untyped-def]
+    # Even with a model and use_harnessx=True, when the capability is absent the
+    # dispatch must fall back without importing the extra. Simulate absence so the
+    # guarantee holds whether or not the extra is installed in this environment.
+    assert_cold_of_harnessx(
+        "import openultrasast.verify_judge as vj\n"
+        "vj.has_harnessx = lambda: False\n"
+        "from openultrasast.findings import StaticFinding\n"
+        "f = StaticFinding(finding_id='x:app.py:1', path='app.py', title='t', severity='low',\n"
+        "    confidence='low', evidence_level='static_corroboration', rationale='r', line=1,\n"
+        "    function_name=None, reachability_status='unknown', reachability_evidence=[],\n"
+        "    reachability_conditions=[], tags=[], ranking_priority=1.0)\n"
+        "vj.verify_findings_dispatch([f], verifier_model='claude-x', use_harnessx=True)\n"
+    )
 
 
 def test_verdict_mapping_is_evidence_gated() -> None: