bugbout 0.1.0__py3-none-any.whl

bugbout/agents/gemini_cli.py

@@ -0,0 +1,73 @@
+"""Google's Gemini CLI."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import override
+
+from bugbout.agents.base import CodingAgent, Invocation, Session, read_jsonl
+from bugbout.sandbox import Confinement
+
+# Workspace settings, not the user's: no web tools, nothing reported home.
+_SETTINGS = {
+    "tools": {"exclude": ["web_fetch", "google_web_search"]},
+    "privacy": {"usageStatisticsEnabled": False},
+    "telemetry": {"enabled": False},
+}
+
+
+class GeminiCli(CodingAgent):
+    """``gemini --prompt`` in auto-approve mode, inside bugbout's sandbox.
+
+    Web tools are excluded through workspace settings. The whole process runs in
+    bugbout's sandbox: it reaches the Gemini API, but writes only in the
+    checkout, its logs and Gemini's own state directory.
+    """
+
+    harness = "gemini-cli"
+    executable = "gemini"
+
+    @override
+    def prepare(self, workdir: Path) -> None:
+        folder = workdir / ".gemini"  # never part of a measured patch
+        folder.mkdir(exist_ok=True)
+        (folder / "settings.json").write_text(json.dumps(_SETTINGS, indent=2), encoding="utf-8")
+
+    @override
+    def invocation(self, session: Session) -> Invocation:
+        argv = [
+            self.command(),
+            "--prompt", session.prompt,
+            *(["--model", self.model] if self.model else []),
+            "--approval-mode", "yolo",
+            "--output-format", "stream-json",
+            "--skip-trust",
+        ]  # fmt: skip
+        state = Path.home() / ".gemini"
+        confinement = Confinement(writable=(session.workdir, session.logdir, state), network=True)
+        # Gemini CLI would otherwise start a sandbox of its own inside bugbout's.
+        return Invocation(session.sandbox.wrap(argv, confinement), env={"GEMINI_SANDBOX": "false"})
+
+    @override
+    def parse(self, logdir: Path) -> tuple[str, dict[str, int]]:
+        parts: list[str] = []
+        usage: dict[str, int] = {}
+        for event in read_jsonl(logdir / "stdout.log"):
+            if event.get("type") == "message" and event.get("role") == "assistant":
+                parts.append(str(event.get("content", "")))
+            if event.get("type") != "result":
+                continue
+            if isinstance(stats := event.get("stats"), dict):
+                usage = {k: v for k, v in stats.items() if isinstance(v, int)}
+            if isinstance(error := event.get("error"), dict) and not parts:
+                parts.append(str(error.get("message", "")))  # why it stopped, as Gemini put it
+        return "".join(parts).strip()[-4000:], usage
+
+    @override
+    def describe(self) -> dict[str, str]:
+        return {
+            **super().describe(),
+            "sandbox": "bugbout's sandbox: writes only in the checkout and ~/.gemini",
+            "configuration": "workspace settings; web_fetch and google_web_search excluded",
+        }

bugbout/agents/mini_swe.py

@@ -0,0 +1,103 @@
+"""mini-swe-agent, the SWE-bench team's minimal agent, on any LiteLLM model."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Unpack, override
+
+from bugbout.agents.base import CodingAgent, Identity, Invocation, Session
+from bugbout.errors import ConfigError
+from bugbout.sandbox import Confinement
+
+PLUGINS = Path(__file__).resolve().parent / "plugins"
+SANDBOX_PREFIX_ENV = "BUGBOUT_SANDBOX_PREFIX"
+
+
+class MiniSweAgent(CodingAgent):
+    """``mini`` with an environment class that runs every command in bugbout's sandbox.
+
+    mini-swe-agent runs shell commands directly on the host, so bugbout supplies
+    its own environment (``plugins/bugbout_mini_env.py``): each command gets no
+    network and may write only in the checkout. Model calls stay in the agent's
+    own process, outside the sandbox.
+
+    Text actions - one bash block per reply - suit local models whose server
+    cannot parse tool calls reliably.
+    """
+
+    harness = "mini-swe-agent"
+    executable = "mini"
+
+    def __init__(
+        self,
+        model: str,
+        *,
+        text_actions: bool = False,
+        step_limit: int = 75,
+        model_kwargs: dict[str, str] | None = None,
+        **identity: Unpack[Identity],
+    ) -> None:
+        """``model`` is a LiteLLM model name, such as ``ollama/qwen3-coder:30b``."""
+        if not model:
+            raise ConfigError("mini-swe-agent needs a model: a LiteLLM name such as ollama/qwen3")
+        provider = model.split("/", 1)[0] if "/" in model else self.harness
+        identity.setdefault("quota", provider)
+        super().__init__(model, **identity)
+        self.text_actions = text_actions
+        self.step_limit = step_limit
+        self.model_kwargs = model_kwargs or {}
+
+    @override
+    def invocation(self, session: Session) -> Invocation:
+        settings = [f"agent.step_limit={self.step_limit}", f"environment.cwd={session.workdir}"]
+        settings += [
+            f"model.model_kwargs.{key}={value}" for key, value in self.model_kwargs.items()
+        ]
+        argv = [
+            self.command(),
+            "--model", self.model,
+            "--task", session.prompt,
+            "--yolo",
+            "--exit-immediately",
+            "--cost-limit", "0",
+            "--environment-class", "bugbout_mini_env.SandboxedEnvironment",
+            *(["--model-class", "litellm_textbased"] if self.text_actions else []),
+            "-c", "mini_textbased.yaml" if self.text_actions else "mini.yaml",
+            *[arg for setting in settings for arg in ("-c", setting)],
+            "--output", str(session.logdir / "trajectory.json"),
+        ]  # fmt: skip
+        confinement = Confinement(writable=(session.workdir, session.logdir))
+        inherited = os.environ.get("PYTHONPATH")
+        env = {
+            "PYTHONPATH": os.pathsep.join(filter(None, [str(PLUGINS), inherited])),
+            SANDBOX_PREFIX_ENV: json.dumps(session.sandbox.prefix(confinement)),
+            "MSWEA_COST_TRACKING": "ignore_errors",
+            "MSWEA_CONFIGURED": "true",
+            "LITELLM_LOCAL_MODEL_COST_MAP": "True",
+        }
+        return Invocation(argv, env=env)
+
+    @override
+    def parse(self, logdir: Path) -> tuple[str, dict[str, int]]:
+        try:
+            data = json.loads((logdir / "trajectory.json").read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return "", {}
+        said = [m.get("content") for m in data.get("messages", []) if m.get("role") == "assistant"]
+        last = next((s for s in reversed(said) if isinstance(s, str) and s.strip()), "")
+        info = data.get("info", {})
+        usage = {"steps": len(said)}
+        if isinstance(stats := info.get("model_stats"), dict):
+            usage.update({k: v for k, v in stats.items() if isinstance(v, int)})
+        return f"[{info.get('exit_status', '?')}] {last.strip()[-3000:]}", usage
+
+    @override
+    def describe(self) -> dict[str, str]:
+        return {
+            **super().describe(),
+            "actions": "text (one bash block per reply)" if self.text_actions else "tool calls",
+            "sandbox": "bugbout's sandbox per command: no network, writes only in the checkout",
+            "configuration": f"stock mini config, step limit {self.step_limit}",
+        }

bugbout/agents/plugins/bugbout_mini_env.py

@@ -0,0 +1,27 @@
+"""A mini-swe-agent environment that runs every command inside bugbout's sandbox.
+
+Loaded by mini-swe-agent's own interpreter (through ``PYTHONPATH``), not by
+bugbout's, so it depends on nothing but mini-swe-agent and the standard library.
+bugbout passes the sandbox as a ready-made argv prefix in an environment variable.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+from typing import Any
+
+from minisweagent.environments.local import LocalEnvironment  # type: ignore[import-not-found]
+
+SANDBOX_PREFIX_ENV = "BUGBOUT_SANDBOX_PREFIX"
+
+
+class SandboxedEnvironment(LocalEnvironment):  # type: ignore[misc]
+    def execute(self, action: dict[str, Any], cwd: str = "", *, timeout: int | None = None) -> Any:
+        if SANDBOX_PREFIX_ENV not in os.environ:
+            raise RuntimeError(f"{SANDBOX_PREFIX_ENV} is not set; refusing to run unsandboxed")
+        prefix: list[str] = json.loads(os.environ[SANDBOX_PREFIX_ENV])
+        command = str(action.get("command", ""))
+        wrapped = shlex.join([*prefix, "/bin/bash", "-c", command]) if prefix else command
+        return super().execute({**action, "command": wrapped}, cwd, timeout=timeout)

bugbout/agents/registry.py

@@ -0,0 +1,63 @@
+"""Agents by the names configuration files use.
+
+Other packages can add agents without touching bugbout, by declaring an entry
+point in the ``bugbout.agents`` group that names a :class:`CodingAgent` subclass::
+
+    [project.entry-points."bugbout.agents"]
+    my-agent = "my_package.agent:MyAgent"
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import entry_points
+from typing import Any
+
+from bugbout.agents.base import CodingAgent
+from bugbout.agents.claude_code import ClaudeCode
+from bugbout.agents.codex import Codex
+from bugbout.agents.command import CommandAgent
+from bugbout.agents.gemini_cli import GeminiCli
+from bugbout.agents.mini_swe import MiniSweAgent
+from bugbout.errors import ConfigError
+from bugbout.log import get_logger
+
+log = get_logger(__name__)
+
+ENTRY_POINT_GROUP = "bugbout.agents"
+BUILTIN: dict[str, type[CodingAgent]] = {
+    "codex": Codex,
+    "claude-code": ClaudeCode,
+    "gemini-cli": GeminiCli,
+    "mini-swe-agent": MiniSweAgent,
+    "command": CommandAgent,
+}
+
+
+def agent_types() -> dict[str, type[CodingAgent]]:
+    """Every agent type by name: the built-in ones, then any that plugins provide."""
+    found = dict(BUILTIN)
+    for entry in entry_points(group=ENTRY_POINT_GROUP):
+        if entry.name in found:
+            log.warning("Ignoring plugin agent %r: the name is taken", entry.name)
+            continue
+        try:
+            loaded = entry.load()
+        except Exception as exc:  # a broken plugin must not take bugbout down with it
+            log.warning("Could not load plugin agent %r: %s", entry.name, exc)
+            continue
+        if isinstance(loaded, type) and issubclass(loaded, CodingAgent):
+            found[entry.name] = loaded
+        else:
+            log.warning("Ignoring plugin agent %r: not a CodingAgent subclass", entry.name)
+    return found
+
+
+def create_agent(kind: str, **options: Any) -> CodingAgent:
+    """An agent of type ``kind``, configured with ``options``."""
+    types = agent_types()
+    if kind not in types:
+        raise ConfigError(f"unknown agent type {kind!r}; available: {', '.join(sorted(types))}")
+    try:
+        return types[kind](**options)
+    except TypeError as exc:
+        raise ConfigError(f"invalid options for a {kind} agent: {exc}") from exc

bugbout/agents/vendors.py

@@ -0,0 +1,36 @@
+"""Which vendor made the model behind a name.
+
+Independence is the judge's central rule - no vendor's evidence may vouch for its
+own models - so the mapping from a name to a vendor lives in exactly one place.
+Names are matched by marker, in order: ``codex/gpt-5.1`` and
+``mini-swe-agent/ollama/gpt-oss:20b`` are both OpenAI models, whatever runs them.
+"""
+
+from __future__ import annotations
+
+import re
+
+_MARKERS: tuple[tuple[re.Pattern[str], str], ...] = tuple(
+    (re.compile(pattern), vendor)
+    for pattern, vendor in (
+        (r"claude", "anthropic"),
+        (r"gemini|gemma", "google"),
+        (r"qwen", "alibaba"),
+        (r"devstral|codestral|magistral|mistral", "mistral"),
+        (r"deepseek", "deepseek"),
+        (r"llama", "meta"),
+        (r"grok", "xai"),
+        (r"kimi|moonshot", "moonshot"),
+        (r"glm", "zhipu"),
+        (r"gpt|codex|(?<![a-z0-9])o[1-9](?![0-9])", "openai"),
+    )
+)
+
+
+def vendor_of(name: str) -> str:
+    """The vendor whose model ``name`` refers to; an unknown name is its own vendor."""
+    lowered = name.lower()
+    for marker, vendor in _MARKERS:
+        if marker.search(lowered):
+            return vendor
+    return lowered.split("/")[0]

bugbout/arena/__init__.py

@@ -0,0 +1,30 @@
+"""The contest itself: briefs, the race, cross-examination and the judge."""
+
+from bugbout.arena.briefs import ASSIGNMENTS, FIX, Assignment, Brief, Fix, Reproduce, Specify
+from bugbout.arena.exhibits import Exhibit, exhibit_of
+from bugbout.arena.judge import DEFAULT_POLICY, POLICIES, Judge, JudgePolicy, Standing, Verdict
+from bugbout.arena.matrix import BASE, CrossExaminer, Matrix
+from bugbout.arena.race import Attempt, Race
+
+__all__ = [
+    "ASSIGNMENTS",
+    "BASE",
+    "DEFAULT_POLICY",
+    "FIX",
+    "POLICIES",
+    "Assignment",
+    "Attempt",
+    "Brief",
+    "CrossExaminer",
+    "Exhibit",
+    "Fix",
+    "Judge",
+    "JudgePolicy",
+    "Matrix",
+    "Race",
+    "Reproduce",
+    "Specify",
+    "Standing",
+    "Verdict",
+    "exhibit_of",
+]

bugbout/arena/briefs.py

@@ -0,0 +1,176 @@
+"""What an agent is asked to do with a task.
+
+The same coding agent can play two roles, and only the brief differs. As a
+**contestant** it fixes the issue and adds a regression test. As an
+**examiner** it must not touch the source at all: it writes tests that capture
+the issue and checks that they fail on the unfixed code for the reason the
+issue describes. An examiner never sees a contestant's patch - its tests are
+evidence about the requirement, not about anyone's fix.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import ClassVar, Literal
+
+Role = Literal["contestant", "examiner"]
+
+
+@dataclass(frozen=True, slots=True)
+class Brief:
+    """Everything an assignment's prompt is rendered from."""
+
+    repo: str
+    title: str
+    statement: str
+    source_root: str
+    test_root: str
+    runner: Path
+
+
+class Assignment(ABC):
+    """A role an agent can be given, expressed as the prompt it receives."""
+
+    name: ClassVar[str]
+    role: ClassVar[Role]
+    test_file: ClassVar[str]
+    """The new test file the agent is asked to write, inside the test directory."""
+
+    @property
+    @abstractmethod
+    def template(self) -> str: ...
+
+    def prompt(self, brief: Brief) -> str:
+        return self.template.format(
+            repo=brief.repo,
+            title=brief.title,
+            statement=brief.statement.strip(),
+            source_root=brief.source_root,
+            test_root=brief.test_root,
+            test_file=self.test_file,
+            runner=brief.runner,
+        )
+
+
+class Fix(Assignment):
+    """Contestant: resolve the issue, and prove it with a test."""
+
+    name = "fix"
+    role = "contestant"
+    test_file = "test_issue_regression.py"
+
+    @property
+    def template(self) -> str:
+        return """\
+You are resolving an issue in the {repo} repository. Your working directory is a checkout of \
+the repository at a commit where the issue below is still open. There is no git history.
+
+<issue>
+# {title}
+
+{statement}
+</issue>
+
+Do the following:
+1. Fix the issue by editing the library's source code (under `{source_root}/`).
+2. Write a regression test for this issue in a NEW file, `{test_root}/{test_file}`. \
+It must fail on the code as it is now and pass once your fix is in place. Do not modify or \
+delete existing tests.
+3. Run the tests to check your work with this exact command, which points Python at this \
+checkout:
+   {runner} {test_root}/{test_file}
+   Pass any other test file, or a -k expression, the same way.
+
+Work only inside this directory, and do not download the project or look it up online. When \
+you are finished, reply with a short summary of what you changed and why.
+"""
+
+
+class Reproduce(Assignment):
+    """Examiner: write failing tests that capture the issue, and fix nothing."""
+
+    name = "reproduce"
+    role = "examiner"
+    test_file = "test_issue_reproduction.py"
+
+    @property
+    def template(self) -> str:
+        return """\
+You are writing the regression test for an issue in the {repo} repository, BEFORE anyone has \
+fixed it. Your working directory is a checkout of the repository at a commit where the issue \
+below is still open. There is no git history.
+
+<issue>
+# {title}
+
+{statement}
+</issue>
+
+Your job is to capture the issue as a test - not to fix it:
+1. Do NOT modify the library's source code (under `{source_root}/`) or any existing test.
+2. Write pytest tests in a NEW file, `{test_root}/{test_file}`, that exercise exactly the \
+behaviour the issue asks for, through the library's public API. Cover each concrete case the \
+issue mentions or clearly implies. Do not test anything the issue does not ask to change.
+3. Run them with this exact command, which points Python at this checkout:
+   {runner} {test_root}/{test_file}
+   They MUST fail on the current code, and each failure must be caused by the bug the issue \
+describes - not by a typo, a wrong import, a misremembered API or a mistaken expectation. Read \
+the source until you are sure what correct behaviour is, then make each test assert exactly that.
+
+Work only inside this directory, and do not download the project or look it up online. When \
+you are finished, reply with a short summary of what each test checks.
+"""
+
+
+class Specify(Assignment):
+    """Examiner: write the tests a maintainer would demand of any fix - and fix nothing.
+
+    A reproduction checks the case the issue reports, and a partial fix passes
+    it. This brief asks for the general rule behind the issue, related inputs a
+    complete fix must handle, and behaviour a careless fix might break.
+    """
+
+    name = "specify"
+    role = "examiner"
+    test_file = "test_issue_specification.py"
+
+    @property
+    def template(self) -> str:
+        return """\
+You are the maintainer of the {repo} repository who will review fixes for the issue below. \
+Before anyone has fixed it, write the regression tests you would require a correct fix to pass. \
+Your working directory is a checkout at a commit where the issue is still open. There is no git \
+history.
+
+<issue>
+# {title}
+
+{statement}
+</issue>
+
+1. Do NOT modify the library's source code (under `{source_root}/`) or any existing test.
+2. Read the relevant source and the existing tests until you understand the behaviour the \
+library intends. Work out the general rule the issue implies - not just its literal example.
+3. Write pytest tests in a NEW file, `{test_root}/{test_file}`, in three groups:
+   a. the case the issue reports;
+   b. the same rule on closely related inputs a complete fix must also handle - other types \
+or values the same code path accepts, boundaries, the sibling branch of the same logic;
+   c. nearby behaviour the issue does not ask to change, which a careless fix might break.
+4. Run them with this exact command, which points Python at this checkout:
+   {runner} {test_root}/{test_file}
+   Every test in groups a and b MUST fail on the current code, because of the bug. If a related \
+input already works, it is not part of the bug: move it to group c or drop it. Every test in \
+group c MUST pass on the current code. Each failure must come from the bug - never from a typo, \
+a wrong import, a misremembered API or a mistaken expectation. Check each expectation against \
+the source and the existing tests before you keep it.
+
+Work only inside this directory, and do not download the project or look it up online. When \
+you are finished, reply with a short summary of the rule you tested and why.
+"""
+
+
+ASSIGNMENTS: dict[str, Assignment] = {a.name: a for a in (Fix(), Reproduce(), Specify())}
+FIX = ASSIGNMENTS["fix"]
+EXAMINER_ASSIGNMENTS = tuple(a.name for a in ASSIGNMENTS.values() if a.role == "examiner")

bugbout/arena/exhibits.py

@@ -0,0 +1,78 @@
+"""Exhibits: test files offered as evidence about a task.
+
+Two kinds of author write them. An **examiner** wrote its tests from the issue
+alone and never saw a patch. A **contestant** wrote a regression test for its
+own fix; run against everyone else's fix, that test is evidence too.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any, Literal, get_args
+
+from bugbout.arena.briefs import ASSIGNMENTS
+from bugbout.arena.race import Attempt
+from bugbout.tasks.task import is_test_module
+
+Kind = Literal["examiner", "contestant"]
+KINDS: frozenset[Kind] = frozenset(get_args(Kind))
+
+
+@dataclass(frozen=True, slots=True)
+class Exhibit:
+    task_id: str
+    author: str
+    vendor: str
+    kind: Kind
+    test_code: str
+    note: str = ""
+    """Anything the author did that it was not asked to, such as editing the source."""
+
+    error: str = ""
+    """Why there is no test, when there is none."""
+
+    @property
+    def usable(self) -> bool:
+        return bool(self.test_code.strip())
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Exhibit:
+        if data.get("kind") not in KINDS:
+            raise ValueError(f"unknown exhibit kind {data.get('kind')!r}")
+        return cls(**{k: v for k, v in data.items() if k in set(cls.__slots__)})
+
+
+def author_of(attempt: Attempt) -> str:
+    """Who an attempt's tests are attributed to: a contestant by name, an examiner by role too."""
+    if ASSIGNMENTS[attempt.assignment].role == "contestant":
+        return attempt.agent
+    return f"{attempt.assignment}/{attempt.agent}"
+
+
+def exhibit_of(attempt: Attempt, test_root: str) -> Exhibit:
+    """The test file an attempt created - the one its brief asked for, if it wrote that one."""
+    assignment = ASSIGNMENTS[attempt.assignment]
+    kind: Kind = "contestant" if assignment.role == "contestant" else "examiner"
+    root = test_root.strip("/")
+    created = attempt.patch.only(under=root, keep=True).created()
+    wanted = f"{root}/{assignment.test_file}"
+    written = (
+        wanted if wanted in created else next((p for p in sorted(created) if is_test_module(p)), "")
+    )
+    notes = []
+    if written and written != wanted:
+        notes.append(f"tests written to {written} instead of {wanted}")
+    if kind == "examiner" and attempt.patch.only(under=root, keep=False).files:
+        notes.append("edited the source, which was discarded")
+    return Exhibit(
+        task_id=attempt.task_id,
+        author=author_of(attempt),
+        vendor=attempt.vendor,
+        kind=kind,
+        test_code=created.get(written, ""),
+        note="; ".join(notes),
+        error="" if written else f"no test written ({attempt.status})",
+    )