Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python
8.0 KB
Raw Blame
"""Harbor installed agent for graff (github.com/justrach/codegraff).

Installs the static Linux graff binary in the task container, either from a
GitHub release (`version`, checked against that release's SHA256SUMS; the
latest release when omitted) or from a local binary (`binary`), then solves
the task as one headless `graff -p` run with every tool approved. Headless runs wait for their own background work before they end
(ADR 0215), so a build or test suite the agent starts in the background is
collected rather than dropped.

graff keeps its session, traces and scratch worktrees in `.graff/` under the
working directory. After the run that directory moves into the agent logs, so
the verifier sees only the agent's changes to the task.
"""

from __future__ import annotations

import shlex
from pathlib import Path, PurePosixPath
from typing import Annotated, Any, override

from harbor.agents.installed.base import BaseInstalledAgent, with_prompt_template
from harbor.agents.model_connection import ModelConnectionSpec
from harbor.agents.options import Cli, InstalledAgentOptions
from harbor.environments.base import BaseEnvironment
from harbor.models.agent.context import AgentContext
from pydantic import Field

from graff_harbor.usage import parse_footer

RELEASES = "https://github.com/justrach/codegraff/releases"
REMOTE = PurePosixPath("/installed-agent/graff")
LOGS = PurePosixPath("/logs/agent")


class GraffOptions(InstalledAgentOptions):
    binary: str | None = Field(
        default=None,
        description="Local static Linux graff binary to upload instead of a release.",
    )
    max_model_calls: Annotated[int | None, Cli("--max-model-calls")] = Field(
        default=None, description="Stop the run after this many model calls."
    )


def release_tag(version: str | None) -> str:
    """`latest`, or a release tag with its leading `v`."""
    if not version or version == "latest":
        return "latest"
    return version if version.startswith("v") else f"v{version}"


def release_base(release: str) -> str:
    """Download base for `latest` or a tag such as `v0.0.302.10`."""
    if release == "latest":
        return f"{RELEASES}/latest/download"
    return f"{RELEASES}/download/{release}"


def install_script(release: str) -> str:
    """Fetch the release tarball for this machine and verify it."""
    base = shlex.quote(release_base(release))
    return "\n".join(
        [
            "set -eu",
            'case "$(uname -m)" in',
            "  x86_64|amd64) arch=x86_64 ;;",
            "  aarch64|arm64) arch=aarch64 ;;",
            '  *) echo "graff: unsupported architecture $(uname -m)" >&2; exit 1 ;;',
            "esac",
            'tmp="$(mktemp -d)"',
            'cd "$tmp"',
            f'curl -fsSL -o graff.tar.gz {base}/graff-"$arch"-linux.tar.gz',
            f"curl -fsSL -o SHA256SUMS {base}/SHA256SUMS",
            'want="$(grep " graff-$arch-linux.tar.gz$" SHA256SUMS | head -n 1 | cut -d " " -f 1)"',
            'got="$(sha256sum graff.tar.gz | cut -d " " -f 1)"',
            'if [ -z "$want" ] || [ "$want" != "$got" ]; then',
            '  echo "graff: release checksum mismatch" >&2',
            "  exit 1",
            "fi",
            "tar -xzf graff.tar.gz",
            f'cp "graff-$arch-linux/graff" {REMOTE}/graff',
            'rm -rf "$tmp"',
        ]
    )


def run_command(model: str, flags: str) -> str:
    """One headless graff run, then `.graff/` moves out of the task tree."""
    graff = shlex.join(
        [
            str(REMOTE / "graff"),
            "--yolo",
            "--no-telemetry",
            "--model",
            model,
        ]
    )
    extra = f" {flags}" if flags else ""
    return "\n".join(
        [
            'had_state=""',
            'if [ -e .graff ]; then had_state=1; fi',
            f'{graff}{extra} -p "$(cat {LOGS}/instruction.md)" '
            f">{LOGS}/graff.stdout 2>{LOGS}/graff.stderr",
            "rc=$?",
            'if [ -z "$had_state" ] && [ -d .graff ]; then',
            f"  mkdir -p {LOGS}/graff-state",
            f"  cp -R .graff/. {LOGS}/graff-state/ && rm -rf .graff",
            "  git worktree prune >/dev/null 2>&1 || true",
            "fi",
            'exit "$rc"',
        ]
    )


class Graff(BaseInstalledAgent):
    """graff, installed from a release or a local static Linux binary."""

    MODEL_CONNECTION = ModelConnectionSpec(passthrough=True)
    options_model = GraffOptions

    def __init__(self, *args: Any, **kwargs: Any) -> None:
        super().__init__(*args, **kwargs)
        if not self.model_name or "/" not in self.model_name:
            raise ValueError(
                "Use a provider/model name, e.g. anthropic/claude-sonnet-5-5"
            )
        self._release = release_tag(self._version)
        binary = self.options.binary if isinstance(self.options, GraffOptions) else None
        self._binary = Path(binary).expanduser().resolve() if binary else None
        if self._binary is not None and not self._binary.is_file():
            raise ValueError(f"graff binary not found: {self._binary}")

    @staticmethod
    @override
    def name() -> str:
        return "graff"

    @override
    def get_version_command(self) -> str | None:
        return f"{REMOTE}/graff --version"

    @override
    def parse_version(self, stdout: str) -> str:
        lines = stdout.strip().splitlines()
        return lines[0].removeprefix("graff").strip() if lines else ""

    @override
    async def install(self, environment: BaseEnvironment) -> None:
        # The release download needs curl, and Terminal-Bench verifiers
        # bootstrap their test runners with it. An uploaded binary does not,
        # so there a missing package mirror is only a warning.
        await self.exec_as_root(environment, command=f"mkdir -p {REMOTE}")
        if self._binary is not None:
            try:
                await self.ensure_system_dependencies(environment, ("curl",))
            except Exception as error:  # noqa: BLE001 - best effort off the release path
                self.logger.warning("curl install failed (%s); continuing with the uploaded binary", error)
            await environment.upload_file(self._binary, str(REMOTE / "graff"))
        else:
            await self.ensure_system_dependencies(environment, ("curl",))
            await self.exec_as_root(environment, command=install_script(self._release))
        await self.exec_as_root(
            environment,
            command=f"chmod 755 {REMOTE}/graff && {REMOTE}/graff --version",
        )

    @override
    @with_prompt_template
    async def run(
        self, instruction: str, environment: BaseEnvironment, context: AgentContext
    ) -> None:
        await self.exec_as_agent(environment, command=f"mkdir -p {LOGS}")
        await self._upload_config_text(
            environment,
            content=instruction,
            filename="instruction.md",
            remote_path=str(LOGS / "instruction.md"),
        )
        env = {
            **self.model_connection.env,
            "GRAFF_NO_TELEMETRY": "1",
            "GRAFF_BEHAVIOR_UPLOAD": "off",
            "NO_COLOR": "1",
        }
        await self.exec_as_agent(
            environment,
            command=run_command(self.model_name or "", self.build_cli_flags()),
            env=env,
        )

    @override
    def populate_context_post_run(self, context: AgentContext) -> None:
        stderr = self.logs_dir / "graff.stderr"
        usage = parse_footer(stderr.read_text(errors="replace")) if stderr.exists() else None
        metadata = {**(context.metadata or {}), "graff_release": self._release}
        if self._binary is not None:
            metadata["graff_binary"] = self._binary.name
        if usage is None:
            metadata["graff_usage_missing"] = True
        else:
            context.n_input_tokens = usage.input_tokens
            context.n_cache_tokens = usage.cached_tokens
            context.n_output_tokens = usage.output_tokens
            context.cost_usd = usage.cost_usd
            metadata["graff_api_calls"] = usage.calls
        context.metadata = metadata