OpenJarvis 1.0.3.dev824__tar.gz → 1.0.3.dev825__tar.gz

{openjarvis-1.0.3.dev824 → openjarvis-1.0.3.dev825}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: OpenJarvis
-Version: 1.0.3.dev824
+Version: 1.0.3.dev825
 Summary: OpenJarvis — modular AI assistant backend with composable intelligence primitives
 Project-URL: Homepage, https://github.com/open-jarvis/OpenJarvis
 Project-URL: Documentation, https://open-jarvis.github.io/OpenJarvis/

{openjarvis-1.0.3.dev824 → openjarvis-1.0.3.dev825}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "OpenJarvis"
-version = "1.0.3.dev824"
+version = "1.0.3.dev825"
 description = "OpenJarvis — modular AI assistant backend with composable intelligence primitives"
 readme = "README.md"
 # Upper bound: numpy 2.2.x (pinned transitively via datasets/pandas) ships no

openjarvis-1.0.3.dev825/src/openjarvis/evals/backends/terminalbench_native.py

@@ -0,0 +1,277 @@
+"""Native TerminalBench V2.1 backend.
+
+Uses Harness for Docker-based execution and scoring.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from openjarvis.evals.core.backend import InferenceBackend
+from openjarvis.evals.core.types import RunSummary
+
+LOGGER = logging.getLogger(__name__)
+
+try:
+    from terminal_bench import BenchmarkResults, Harness
+
+    _HAS_TB = True
+except ImportError:
+    _HAS_TB = False
+
+# terminal-bench FailureMode values that are definitionally infrastructure
+# failures (the harness broke before/while driving the agent), never a
+# judgment on the model's answer. NOTE: clean trials leave failure_mode
+# "unset" in terminal-bench 0.2.18 — both on success AND on genuine
+# unresolved misses — so failure_mode alone can NOT be used to detect
+# harness errors (it would misflag every real model miss).
+_INFRA_FAILURE_MODES = frozenset({"agent_installation_failed", "unknown_agent_error"})
+
+# Harness kwargs that older terminal-bench versions may not support.
+_TIMEOUT_KWARGS = ("global_agent_timeout_sec", "global_timeout_multiplier")
+
+
+def summarize_benchmark_results(
+    results: Any,
+    *,
+    model: str,
+    benchmark: str = "terminalbench-native",
+) -> Tuple[RunSummary, List[Dict[str, str]]]:
+    """Convert terminal-bench ``BenchmarkResults`` into a ``RunSummary``.
+
+    Trials are classified into three buckets:
+
+    - resolved: ``is_resolved`` is True -> counted correct.
+    - model miss: unresolved, but the model was actually contacted ->
+      counted in the accuracy denominator.
+    - harness/infra failure: excluded from the accuracy denominator and
+      reported in ``RunSummary.errors`` plus the returned failure list.
+
+    Zero-model-contact signal choice: terminal-bench 0.2.18 leaves
+    ``failure_mode`` UNSET both on clean success and on genuine unresolved
+    misses, so failure_mode cannot distinguish "the model tried and failed"
+    from "the agent never called the model". Token usage can: this backend
+    always runs terminus-2, which reports real LiteLLM usage, so an
+    unresolved trial with zero/missing input+output tokens means no model
+    request ever completed — an infrastructure failure (in-container setup
+    hang/death, tmux failure), not a model miss. CAVEAT: terminal-bench
+    "installed agents" (openhands, claude-code, ...) hardcode 0 tokens even
+    on success; if this backend ever honors ``agent_name`` for installed
+    agents, this heuristic must be gated on the agent type.
+    """
+    trials = list(getattr(results, "results", None) or [])
+
+    harness_failures: List[Dict[str, str]] = []
+    scored = 0
+    correct = 0
+
+    for tr in trials:
+        task_id = getattr(tr, "task_id", None) or getattr(tr, "trial_name", "unknown")
+        is_resolved = getattr(tr, "is_resolved", None) is True
+        fm = getattr(tr, "failure_mode", None)
+        fm_value = str(getattr(fm, "value", fm) or "unset").lower()
+        tokens = (getattr(tr, "total_input_tokens", None) or 0) + (
+            getattr(tr, "total_output_tokens", None) or 0
+        )
+
+        zero_model_contact = not is_resolved and tokens == 0
+        infra_failure_mode = fm_value in _INFRA_FAILURE_MODES
+
+        if zero_model_contact or infra_failure_mode:
+            harness_failures.append(
+                {
+                    "task_id": str(task_id),
+                    "failure_mode": fm_value,
+                    "reason": (
+                        "zero_model_requests" if zero_model_contact else fm_value
+                    ),
+                }
+            )
+            continue
+
+        scored += 1
+        if is_resolved:
+            correct += 1
+
+    return (
+        RunSummary(
+            benchmark=benchmark,
+            category="agentic",
+            backend="terminalbench-native",
+            model=model,
+            total_samples=len(trials),
+            scored_samples=scored,
+            correct=correct,
+            accuracy=correct / scored if scored else 0.0,
+            errors=len(harness_failures),
+            mean_latency_seconds=0.0,
+            total_cost_usd=0.0,
+        ),
+        harness_failures,
+    )
+
+
+class TerminalBenchNativeBackend(InferenceBackend):
+    """Runs terminal-bench tasks natively via Harness with Docker execution.
+
+    Uses terminal-bench's own agent + LiteLLM to call the model,
+    Docker containers for task execution, and built-in test scripts
+    for scoring. This gives real agentic evaluation, not text-only.
+    """
+
+    backend_id = "terminalbench-native"
+
+    def __init__(
+        self,
+        model: str = "openai/default",
+        api_base: str = "http://localhost:8000/v1",
+        temperature: float = 0.2,
+        agent_name: str = "naive",
+        output_dir: str = "results/terminalbench/",
+        max_samples: Optional[int] = None,
+        dataset_name: str = "terminal-bench-core",
+        dataset_version: str = "0.1.1",
+        system_prompt: str = "",
+        max_tokens: int = 16384,
+        n_concurrent: int = 4,
+        global_agent_timeout_sec: Optional[float] = 1800.0,
+        global_timeout_multiplier: Optional[float] = None,
+    ) -> None:
+        """Args of note:
+
+        global_agent_timeout_sec: Hard wall-clock bound for each trial's
+            agent phase. terminal-bench runs installed-agent SETUP inside
+            this same budget with an infinite tmux timeout, so this bounds
+            SETUP+RUN together (a setup-only timeout needs an upstream
+            terminal-bench change). When set, it REPLACES each task's own
+            ``max_agent_timeout_sec``. Set ``None`` or ``0`` to fall back
+            to per-task budgets.
+        global_timeout_multiplier: Scales per-task budgets when
+            ``global_agent_timeout_sec`` is not set. ``None`` keeps
+            terminal-bench's default (1.0).
+        """
+        if not _HAS_TB:
+            raise ImportError("terminal-bench is required: pip install terminal-bench")
+
+        self._model = model
+        self._api_base = api_base
+        self._temperature = temperature
+        self._agent_name = agent_name
+        self._output_dir = Path(output_dir)
+        self._max_samples = max_samples
+        self._dataset_name = dataset_name
+        self._dataset_version = dataset_version
+        self._system_prompt = system_prompt
+        self._max_tokens = max_tokens
+        self._n_concurrent = n_concurrent
+        self._global_agent_timeout_sec = global_agent_timeout_sec
+        self._global_timeout_multiplier = global_timeout_multiplier
+        self._results: Optional[BenchmarkResults] = None
+
+    def run_harness(self, run_id: str) -> BenchmarkResults:
+        """Run the full terminal-bench harness and return results."""
+        output_path = self._output_dir / run_id
+        output_path.mkdir(parents=True, exist_ok=True)
+
+        harness_kwargs: Dict[str, Any] = {
+            "output_path": output_path,
+            "run_id": run_id,
+            "dataset_name": self._dataset_name,
+            "dataset_version": self._dataset_version,
+            "model_name": self._model,
+            "n_concurrent_trials": self._n_concurrent,
+            "cleanup": True,
+        }
+
+        # Use terminus-2 agent which accepts model_name + api_base as
+        # serializable strings (avoids Pydantic serialization issues with
+        # LLM objects in the harness lock file).
+        from terminal_bench.agents.agent_name import AgentName
+
+        harness_kwargs["agent_name"] = AgentName("terminus-2")
+        harness_kwargs["agent_kwargs"] = {
+            "model_name": self._model,
+            "api_base": self._api_base,
+            "temperature": self._temperature,
+        }
+
+        if self._max_samples is not None:
+            harness_kwargs["n_tasks"] = self._max_samples
+
+        # Bound each trial's agent phase. Without this, an in-container
+        # installed-agent SETUP hang runs with an infinite tmux timeout,
+        # bounded only by whatever budget the task happens to declare.
+        if self._global_agent_timeout_sec:
+            harness_kwargs["global_agent_timeout_sec"] = float(
+                self._global_agent_timeout_sec
+            )
+        if self._global_timeout_multiplier is not None:
+            harness_kwargs["global_timeout_multiplier"] = float(
+                self._global_timeout_multiplier
+            )
+
+        self._check_timeout_kwargs_supported(harness_kwargs)
+
+        harness = Harness(**harness_kwargs)
+        self._results = harness.run()
+        return self._results
+
+    @staticmethod
+    def _check_timeout_kwargs_supported(harness_kwargs: Dict[str, Any]) -> None:
+        """Fail loudly if this terminal-bench build lacks the timeout kwargs.
+
+        terminal-bench is an undeclared, unpinned dependency, so installs may
+        predate the global timeout kwargs (added by 0.2.x). Passing an
+        unknown kwarg raises an opaque TypeError; dropping it silently would
+        re-create the unbounded-setup hang. Detect and explain instead.
+        """
+        try:
+            params = inspect.signature(Harness.__init__).parameters
+        except (TypeError, ValueError):
+            return
+        if any(p.kind is inspect.Parameter.VAR_KEYWORD for p in params.values()):
+            return
+        unsupported = [
+            key
+            for key in _TIMEOUT_KWARGS
+            if key in harness_kwargs and key not in params
+        ]
+        if unsupported:
+            raise RuntimeError(
+                "The installed terminal-bench does not support "
+                f"{', '.join(unsupported)} (requires terminal-bench >= "
+                "0.2.18). Upgrade terminal-bench, or disable the bound by "
+                "setting global_agent_timeout_sec = 0 in the eval config "
+                "[run] section."
+            )
+
+    def generate(
+        self,
+        prompt: str,
+        *,
+        model: str,
+        system: str = "",
+        temperature: float = 0.0,
+        max_tokens: int = 2048,
+    ) -> str:
+        return ""
+
+    def generate_full(
+        self,
+        prompt: str,
+        *,
+        model: str,
+        system: str = "",
+        temperature: float = 0.0,
+        max_tokens: int = 2048,
+    ) -> Dict[str, Any]:
+        return {"content": "", "usage": {}, "model": model, "latency_seconds": 0.0}
+
+    def close(self) -> None:
+        pass
+
+
+__all__ = ["TerminalBenchNativeBackend", "summarize_benchmark_results"]

{openjarvis-1.0.3.dev824 → openjarvis-1.0.3.dev825}/src/openjarvis/evals/cli.py

@@ -690,14 +690,22 @@ def _run_terminalbench_native(
     from openjarvis.engine.openai_compat_engines import normalize_openai_base_url
     from openjarvis.evals.backends.terminalbench_native import (
         TerminalBenchNativeBackend,
+        summarize_benchmark_results,
     )
-    from openjarvis.evals.core.types import RunSummary
 
     model = config.model
     # LiteLLM expects "openai/<model>" for OpenAI-compatible servers
     litellm_model = f"openai/{model}"
     output_dir = getattr(config, "output_path", None) or "results/terminalbench-native/"
 
+    # Harness budgets: only forward explicit config values so the backend
+    # defaults (global_agent_timeout_sec=1800) apply otherwise.
+    timeout_kwargs = {}
+    if getattr(config, "global_agent_timeout_sec", None) is not None:
+        timeout_kwargs["global_agent_timeout_sec"] = config.global_agent_timeout_sec
+    if getattr(config, "global_timeout_multiplier", None) is not None:
+        timeout_kwargs["global_timeout_multiplier"] = config.global_timeout_multiplier
+
     # Normalize to exactly one trailing "/v1" — LiteLLM's api_base wants the
     # full OpenAI-compatible prefix, and users pass both forms of the URL.
     if base_url:
@@ -712,6 +720,7 @@ def _run_terminalbench_native(
         max_samples=config.max_samples,
         output_dir=output_dir,
         n_concurrent=config.max_workers or 4,
+        **timeout_kwargs,
     )
 
     import re
@@ -740,28 +749,20 @@ def _run_terminalbench_native(
     else:
         results = backend.run_harness(run_id)
 
-    # Convert BenchmarkResults to RunSummary
-    total = len(results.trial_results) if hasattr(results, "trial_results") else 0
-    correct = 0
-    if hasattr(results, "trial_results"):
-        for tr in results.trial_results:
-            if getattr(tr, "is_resolved", False):
-                correct += 1
-
-    accuracy = correct / total if total > 0 else 0.0
-    return RunSummary(
-        benchmark="terminalbench-native",
-        category="agentic",
-        backend="terminalbench-native",
-        model=model,
-        total_samples=total,
-        scored_samples=total,
-        correct=correct,
-        accuracy=accuracy,
-        errors=0,
-        mean_latency_seconds=0.0,
-        total_cost_usd=0.0,
-    )
+    # Convert BenchmarkResults to RunSummary, classifying harness/infra
+    # failures (e.g. zero-model-contact setup hangs) out of the resolve-rate.
+    summary, harness_failures = summarize_benchmark_results(results, model=model)
+    if harness_failures:
+        console.print(
+            f"  [red bold]{len(harness_failures)} harness/infra failure(s) "
+            "excluded from resolve-rate:[/red bold]"
+        )
+        for failure in harness_failures:
+            console.print(
+                f"  [red]- {failure['task_id']}: {failure['reason']} "
+                f"(failure_mode={failure['failure_mode']})[/red]"
+            )
+    return summary
 
 
 def _run_single(
@@ -1039,7 +1040,9 @@ def _print_agentic_summary(console: Console, traces, config) -> None:
     from rich.table import Table
 
     completed = sum(1 for t in traces if t.completed)
-    resolved = sum(1 for t in traces if t.is_resolved is True)
+    harness_errors = [t for t in traces if t.error_kind == "harness_error"]
+    model_traces = [t for t in traces if t.error_kind != "harness_error"]
+    resolved = sum(1 for t in model_traces if t.is_resolved is True)
     timed_out = sum(1 for t in traces if t.timed_out)
     total_turns = sum(t.num_turns for t in traces)
     total_tool_calls = sum(t.total_tool_calls for t in traces)
@@ -1067,8 +1070,11 @@ def _print_agentic_summary(console: Console, traces, config) -> None:
     table.add_row("Queries", str(len(traces)))
     table.add_row("Completed", f"{completed}/{len(traces)}")
     if any(t.is_resolved is not None for t in traces):
-        table.add_row("Resolved", f"{resolved}/{len(traces)}")
+        # Harness errors are excluded from the resolve-rate denominator:
+        # they are infra failures, not model misses.
+        table.add_row("Resolved", f"{resolved}/{len(model_traces)}")
     table.add_row("Timed out", str(timed_out))
+    table.add_row("Harness errors", str(len(harness_errors)))
     table.add_row("Total turns", str(total_turns))
     avg_t = f"{total_turns / len(traces):.1f}" if traces else "0"
     table.add_row("Avg turns/query", avg_t)
@@ -1095,6 +1101,19 @@ def _print_agentic_summary(console: Console, traces, config) -> None:
 
     console.print(table)
 
+    if harness_errors:
+        console.print(
+            f"[red bold]{len(harness_errors)} harness/infra failure(s) "
+            "excluded from resolve-rate:[/red bold]"
+        )
+        for t in harness_errors[:5]:
+            console.print(f"[red]  {t.query_id}: {(t.error or '')[:300]}[/red]")
+        if len(harness_errors) > 5:
+            console.print(
+                f"[red]  ... and {len(harness_errors) - 5} more "
+                "(see traces.jsonl)[/red]"
+            )
+
 
 def _run_from_config(
     config_path: str,

{openjarvis-1.0.3.dev824 → openjarvis-1.0.3.dev825}/src/openjarvis/evals/core/agentic_runner.py

@@ -20,6 +20,7 @@ from contextlib import nullcontext
 from pathlib import Path
 from typing import Any, Callable, Optional
 
+from openjarvis.evals.core.environment import TaskEnvironmentError
 from openjarvis.evals.core.event_recorder import AgentEvent, EventRecorder, EventType
 from openjarvis.evals.core.trace import QueryTrace, TurnTrace
 
@@ -176,9 +177,12 @@ class AgenticRunner:
                 )
             self._traces.append(trace)
 
-            status = (
-                "TIMEOUT" if trace.timed_out else ("OK" if trace.completed else "FAIL")
-            )
+            if trace.timed_out:
+                status = "TIMEOUT"
+            elif trace.error_kind == "harness_error":
+                status = "HARNESS_ERROR"
+            else:
+                status = "OK" if trace.completed else "FAIL"
             LOGGER.info(
                 "Task %s: %s in %.1fs",
                 query_id,
@@ -260,11 +264,12 @@ class AgenticRunner:
                         is_resolved=record.metadata.get("is_resolved"),
                     )
 
-                status = (
-                    "TIMEOUT"
-                    if trace.timed_out
-                    else ("OK" if trace.completed else "FAIL")
-                )
+                if trace.timed_out:
+                    status = "TIMEOUT"
+                elif trace.error_kind == "harness_error":
+                    status = "HARNESS_ERROR"
+                else:
+                    status = "OK" if trace.completed else "FAIL"
                 LOGGER.info(
                     "Task %s: %s in %.1fs",
                     query_id,
@@ -444,7 +449,23 @@ class AgenticRunner:
                 _run_body()
 
         except Exception as exc:
-            LOGGER.warning("Agent failed on query %s: %s", query_id, exc)
+            # Distinguish infrastructure breakage (task env failed to start,
+            # Docker/tmux death) from agent failures: harness errors must be
+            # recorded distinctly so scoring excludes them from resolve-rate
+            # instead of silently counting a model miss. Either way the run
+            # continues with the next record (fail THIS task, not the run).
+            is_harness_error = isinstance(exc, TaskEnvironmentError) or bool(
+                record.metadata.get("harness_error")
+            )
+            if is_harness_error:
+                LOGGER.error(
+                    "Harness/environment failure on query %s (record %s): %s",
+                    query_id,
+                    getattr(record, "record_id", "?"),
+                    exc,
+                )
+            else:
+                LOGGER.warning("Agent failed on query %s: %s", query_id, exc)
             end_time = time.time()
             # Unsubscribe EventBus relays
             if agent_bus is not None:
@@ -461,6 +482,8 @@ class AgenticRunner:
                 total_wall_clock_s=end_time - start_time,
                 completed=False,
                 is_resolved=record.metadata.get("is_resolved"),
+                error=str(exc),
+                error_kind="harness_error" if is_harness_error else "agent_error",
             )
 
         # Unsubscribe EventBus relays
@@ -534,6 +557,48 @@ class AgenticRunner:
                     model, turn.input_tokens, turn.output_tokens
                 )
 
+        # --- Zero-model-contact sanity check ----------------------------
+        # Failed in-container setups (e.g. an installed agent's SETUP phase
+        # hanging or dying) historically produced traces that looked like
+        # model results: completed=True, a synthetic 1-event turn,
+        # is_resolved=False from run_tests, and zero tokens — silently
+        # dragging resolve-rate down as a fake model miss. Signal choice:
+        # token usage plus LM inference events is the reliable discriminator
+        # here — a genuine model miss has token usage (and/or LM events),
+        # while "the agent never called the model" has neither. We do NOT
+        # key off completion status or is_resolved, which are identical in
+        # both cases. run_agent_loop envs drive the model directly
+        # (bypassing usage reporting), so their turn_wall_clocks count as
+        # model contact.
+        had_lm_events = any(
+            e.event_type in (EventType.LM_INFERENCE_START, EventType.LM_INFERENCE_END)
+            for e in events
+        )
+        had_loop_turns = bool(
+            task_env is not None and getattr(task_env, "turn_wall_clocks", None)
+        )
+        turn_tokens = sum(t.input_tokens + t.output_tokens for t in turns)
+        error: Optional[str] = None
+        error_kind: Optional[str] = None
+        if (
+            not had_lm_events
+            and not had_loop_turns
+            and in_tok + out_tok == 0
+            and turn_tokens == 0
+        ):
+            error = (
+                "zero_model_requests: the agent produced no LM inference "
+                "events and reported zero token usage — the model was never "
+                "contacted. This is a harness/infrastructure failure (e.g. "
+                "in-container agent setup hang/death), not a model miss, and "
+                "is excluded from resolve-rate. If your agent genuinely "
+                "contacted the model, make it report token usage or emit "
+                "LM_INFERENCE events. Response tail: "
+                f"{(response_text or '')[-500:]!r}"
+            )
+            error_kind = "harness_error"
+            LOGGER.error("Query %s: %s", query_id, error)
+
         # Query-level energy from telemetry window
         query_gpu_energy = _compute_energy_delta(readings, "gpu_energy_j")
         query_cpu_energy = _compute_energy_delta(readings, "cpu_energy_j")
@@ -563,6 +628,8 @@ class AgenticRunner:
             is_resolved=record.metadata.get("is_resolved"),
             query_mbu_avg_pct=query_mbu_avg,
             query_mbu_max_pct=query_mbu_max,
+            error=error,
+            error_kind=error_kind,
         )
 
         # Correlate energy with trace

{openjarvis-1.0.3.dev824 → openjarvis-1.0.3.dev825}/src/openjarvis/evals/core/config.py

@@ -143,6 +143,16 @@ def load_eval_config(path: str | Path) -> EvalSuiteConfig:
         sheets_worksheet=run_raw.get("sheets_worksheet", "Results"),
         sheets_credentials_path=run_raw.get("sheets_credentials_path", ""),
         max_turns=(int(run_raw["max_turns"]) if "max_turns" in run_raw else None),
+        global_agent_timeout_sec=(
+            float(run_raw["global_agent_timeout_sec"])
+            if "global_agent_timeout_sec" in run_raw
+            else None
+        ),
+        global_timeout_multiplier=(
+            float(run_raw["global_timeout_multiplier"])
+            if "global_timeout_multiplier" in run_raw
+            else None
+        ),
     )
 
     # Parse [[models]]
@@ -212,6 +222,16 @@ def load_eval_config(path: str | Path) -> EvalSuiteConfig:
                 max_tokens=int(b["max_tokens"]) if "max_tokens" in b else None,
                 subset=b.get("subset"),
                 record_ids=record_ids,
+                global_agent_timeout_sec=(
+                    float(b["global_agent_timeout_sec"])
+                    if "global_agent_timeout_sec" in b
+                    else None
+                ),
+                global_timeout_multiplier=(
+                    float(b["global_timeout_multiplier"])
+                    if "global_timeout_multiplier" in b
+                    else None
+                ),
             )
         )
 
@@ -275,6 +295,14 @@ def expand_suite(suite: EvalSuiteConfig) -> List[RunConfig]:
             if bench.judge_model is not None:
                 judge_model = bench.judge_model
 
+            # terminal-bench harness budgets: benchmark > [run]
+            global_agent_timeout_sec = suite.run.global_agent_timeout_sec
+            if bench.global_agent_timeout_sec is not None:
+                global_agent_timeout_sec = bench.global_agent_timeout_sec
+            global_timeout_multiplier = suite.run.global_timeout_multiplier
+            if bench.global_timeout_multiplier is not None:
+                global_timeout_multiplier = bench.global_timeout_multiplier
+
             # Auto-generate output path
             model_slug = model.name.replace("/", "-").replace(":", "-")
             output_path = f"{output_dir}/{bench.name}_{model_slug}.jsonl"
@@ -328,6 +356,8 @@ def expand_suite(suite: EvalSuiteConfig) -> List[RunConfig]:
                     base_url=suite.backend_external_base_url,
                     api_key=suite.backend_external_api_key,
                     record_ids=bench.record_ids,
+                    global_agent_timeout_sec=global_agent_timeout_sec,
+                    global_timeout_multiplier=global_timeout_multiplier,
                 )
             )
 

{openjarvis-1.0.3.dev824 → openjarvis-1.0.3.dev825}/src/openjarvis/evals/core/environment.py

@@ -8,6 +8,18 @@ from typing import Any, Dict, Tuple
 from openjarvis.evals.core.types import EvalRecord
 
 
+class TaskEnvironmentError(RuntimeError):
+    """A task execution environment failed to start or operate.
+
+    Raised when infrastructure backing a task (Docker container, docker
+    compose project, tmux session, recording binaries, ...) breaks. This is
+    a harness/environment failure, **not** a model failure: runners record
+    it distinctly (``QueryTrace.error_kind == "harness_error"``) so scoring
+    can exclude the sample from resolve-rate instead of silently counting
+    it as a model miss.
+    """
+
+
 class EnvironmentProvider(ABC):
     """Manages an external environment for evaluation benchmarks.
 
@@ -50,3 +62,6 @@ class EnvironmentProvider(ABC):
     @abstractmethod
     def teardown(self) -> None:
         """Stop the environment and release resources."""
+
+
+__all__ = ["EnvironmentProvider", "TaskEnvironmentError"]