outerloop-science 0.1.0__py3-none-any.whl

outerloop/__init__.py

@@ -0,0 +1,18 @@
+"""Outerloop: autonomous research agents that improve a benchmark on your own code."""
+
+import os
+
+__version__ = "0.1.0"
+
+
+def _bridge_legacy_env() -> None:
+    """Accept the pre-rename `AUTORESEARCH_*` names at the process boundary for
+    one release: copy each into its `OUTERLOOP_*` twin when the twin is unset,
+    so the kernel reads one name. The chain scripts do the same in shell.
+    Removed in the release after 0.1."""
+    for key, value in list(os.environ.items()):
+        if key.startswith("AUTORESEARCH_"):
+            os.environ.setdefault("OUTERLOOP_" + key[len("AUTORESEARCH_") :], value)
+
+
+_bridge_legacy_env()

outerloop/__main__.py

@@ -0,0 +1,3 @@
+from outerloop.cli import main
+
+raise SystemExit(main())

outerloop/appauth.py

@@ -0,0 +1,230 @@
+"""GitHub App installation-token auth (docs/design/github-app-auth.md).
+
+`AppInstallationTokenProvider` satisfies the `TokenProvider` protocol used
+throughout `github.py`. Role CLIs construct bot auth through
+`resolve_bot_auth`, which selects this provider when an App config file is
+given (`--github-app-file` / `OUTERLOOP_GITHUB_APP_FILE`) and falls back
+to the PAT file otherwise — the cutover flag, revertible by unsetting the
+env. Each `token()` mints a short-lived JWT (RS256, signed by the App
+private key), exchanges it for a ~1h installation token scoped to the
+installation's repos, and caches that token until a refresh margin before
+it expires.
+
+The RS256 signer and the HTTP transport are injected so the provider — and
+its tests — build and run without the `cryptography` dependency or a
+network; the production signer lives behind the `app-auth` extra.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from outerloop.github import AUTH_SAFE_OPENER, FileTokenProvider, TokenProvider
+from outerloop.paths import CONFIG_DIR
+
+# RS256-sign the JWT signing input, returning the raw signature bytes.
+Signer = Callable[[bytes], bytes]
+# Perform the token-exchange POST and return the parsed JSON body.
+Transport = Callable[[urllib.request.Request], Any]
+
+API = "https://api.github.com"
+# GitHub caps App JWT lifetime at 10 minutes; stay comfortably under it.
+_JWT_TTL_S = 9 * 60
+# Backdate `iat` to tolerate clock skew between us and GitHub.
+_JWT_BACKDATE_S = 60
+# Re-mint the installation token this long before it actually expires, so a
+# token is never handed out on the edge of expiry.
+_REFRESH_MARGIN_S = 5 * 60
+
+# Every installation token minted by this process, whichever provider
+# instance minted it. `redact` appends these to its snapshotted secrets
+# tuple at write time, so a token minted after a call site captured its
+# tuple still never reaches a report, record, or log.
+_ISSUED_TOKENS: list[str] = []
+
+
+def issued_tokens() -> tuple[str, ...]:
+    """All installation tokens minted this process, for write-time redaction."""
+    return tuple(_ISSUED_TOKENS)
+
+
+def _b64url(data: bytes) -> str:
+    """URL-safe base64 without padding — the JWT wire encoding."""
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def build_app_jwt(app_id: int, now: float, sign: Signer) -> str:
+    """A GitHub App JWT: header.payload.signature, RS256 over the first two."""
+    header = _b64url(json.dumps({"alg": "RS256", "typ": "JWT"}).encode())
+    payload = _b64url(
+        json.dumps(
+            {
+                "iat": int(now) - _JWT_BACKDATE_S,
+                "exp": int(now) + _JWT_TTL_S,
+                "iss": str(app_id),
+            }
+        ).encode()
+    )
+    signing_input = f"{header}.{payload}"
+    signature = _b64url(sign(signing_input.encode("ascii")))
+    return f"{signing_input}.{signature}"
+
+
+def _parse_expiry(expires_at: str) -> float:
+    """`2026-09-01T12:00:00Z` (or with an offset) -> unix seconds."""
+    text = expires_at.strip()
+    if text.endswith("Z"):
+        text = text[:-1] + "+00:00"
+    return datetime.fromisoformat(text).timestamp()
+
+
+def _default_transport(request: urllib.request.Request) -> Any:
+    # the shared opener: a cross-host redirect must not forward the App JWT
+    try:
+        with AUTH_SAFE_OPENER.open(request, timeout=30) as response:
+            payload = response.read()
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode(errors="replace")[:500]
+        raise ValueError(f"installation-token exchange failed ({exc.code}): {body}") from None
+    except urllib.error.URLError as exc:
+        raise ValueError(f"installation-token exchange failed: {exc.reason}") from None
+    return json.loads(payload) if payload else None
+
+
+class AppInstallationTokenProvider:
+    """A `TokenProvider` minting cached, short-lived installation tokens."""
+
+    def __init__(
+        self,
+        app_id: int,
+        installation_id: int,
+        sign: Signer,
+        *,
+        transport: Transport | None = None,
+        now: Callable[[], float] = time.time,
+    ) -> None:
+        self.app_id = app_id
+        self.installation_id = installation_id
+        self._sign = sign
+        self._transport = transport or _default_transport
+        self._now = now
+        self._token = ""
+        self._expiry = 0.0
+        # every token ever minted this process — the PAT was one immortal
+        # string, but these rotate ~hourly, so a redaction set snapshotted at
+        # construction goes stale; redaction must pull issued() at write time
+        self._issued: list[str] = []
+
+    def token(self) -> str:
+        now = self._now()
+        if self._token and now < self._expiry - _REFRESH_MARGIN_S:
+            return self._token
+        jwt = build_app_jwt(self.app_id, now, self._sign)
+        request = urllib.request.Request(
+            f"{API}/app/installations/{self.installation_id}/access_tokens",
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {jwt}",
+                "Accept": "application/vnd.github+json",
+                "X-GitHub-Api-Version": "2022-11-28",
+            },
+        )
+        body = self._transport(request)
+        if not isinstance(body, dict) or not body.get("token"):
+            raise ValueError("installation-token response missing a token")
+        self._token = str(body["token"])
+        self._issued.append(self._token)
+        _ISSUED_TOKENS.append(self._token)
+        expires_at = body.get("expires_at")
+        # a missing/garbled expiry is treated as immediate — safe: we simply
+        # re-mint on every call rather than trust an unknown lifetime
+        try:
+            self._expiry = _parse_expiry(str(expires_at)) if expires_at else now
+        except ValueError:
+            self._expiry = now
+        return self._token
+
+    def issued(self) -> tuple[str, ...]:
+        """Every token this provider has minted, for redaction sets built at
+        write time — a set snapshotted at construction misses refreshes."""
+        return tuple(self._issued)
+
+
+def signer_from_private_key(pem_path: Path) -> Signer:
+    """The production RS256 signer, built from the App private-key PEM. Lazily
+    imports `cryptography` (the `app-auth` extra) so the module and its tests
+    do not depend on it; the key file must be owner-only (chmod 600), the same
+    custody the PAT file has."""
+    if not pem_path.is_file():
+        raise ValueError(f"{pem_path} is not a readable private-key file")
+    if pem_path.stat().st_mode & 0o077:
+        raise PermissionError(f"{pem_path} is group/world accessible; chmod 600 it")
+    try:
+        from cryptography.hazmat.primitives import hashes, serialization
+        from cryptography.hazmat.primitives.asymmetric import padding, rsa
+    except ImportError as exc:  # pragma: no cover - exercised only without the extra
+        raise ImportError(
+            "GitHub App auth needs the cryptography package "
+            "(pip install cryptography), a base dependency since 0.1.0.dev2"
+        ) from exc
+
+    key = serialization.load_pem_private_key(pem_path.read_bytes(), password=None)
+    if not isinstance(key, rsa.RSAPrivateKey):
+        raise ValueError(f"{pem_path} is not an RSA key; GitHub App keys are RSA")
+
+    def sign(message: bytes) -> bytes:
+        return key.sign(message, padding.PKCS1v15(), hashes.SHA256())
+
+    return sign
+
+
+def app_provider_from_file(app_file: Path) -> AppInstallationTokenProvider:
+    """Build the provider from the App config file: JSON with `app_id`,
+    `installation_id` (integers), and `private_key` (path to the PEM). The
+    ids are not secrets; the file exists so the whole App identity travels
+    as one path on the same rails the PAT path already rides."""
+    try:
+        config = json.loads(app_file.read_text())
+    except (OSError, ValueError) as exc:
+        raise ValueError(f"cannot read App config {app_file}: {exc}") from None
+    missing = [k for k in ("app_id", "installation_id", "private_key") if not config.get(k)]
+    if missing:
+        raise ValueError(f"App config {app_file} is missing {', '.join(missing)}")
+    return AppInstallationTokenProvider(
+        int(config["app_id"]),
+        int(config["installation_id"]),
+        signer_from_private_key(Path(str(config["private_key"])).expanduser()),
+    )
+
+
+def resolve_bot_auth(pat_file: str | Path, app_file: str | Path = "") -> TokenProvider:
+    """The one seam every role CLI constructs bot auth through: the App
+    provider when an App config file is given, the PAT file otherwise."""
+    if str(app_file).strip():
+        return app_provider_from_file(Path(str(app_file)).expanduser())
+    return FileTokenProvider(Path(str(pat_file)).expanduser())
+
+
+def add_credential_args(parser: argparse.ArgumentParser) -> None:
+    """Add the shared bot-auth options to a role parser: `--pat-file`, and
+    `--github-app-file`, which supplies installation tokens instead of the PAT
+    when set. `resolve_bot_auth` reads the pair. One owner so the defaults and
+    help cannot drift between attempt, followup, and steward."""
+    parser.add_argument("--pat-file", default=str(CONFIG_DIR / "bot_pat"))
+    parser.add_argument(
+        "--github-app-file",
+        default=os.environ.get("OUTERLOOP_GITHUB_APP_FILE", ""),
+        help="GitHub App config (JSON: app_id, installation_id, private_key); "
+        "when set, installation tokens replace the PAT",
+    )

outerloop/appmanifest.py

@@ -0,0 +1,203 @@
+"""GitHub App Manifest flow for `outerloop init --github-app`.
+
+Creates the adopter's OWN GitHub App in one click instead of a hand-rolled PAT.
+Because the bot runs on the adopter's own compute (self-hosted), the App's
+private key must live there — a shared App would mean either we run the fleet or
+we hand out a master key — so each adopter owns their App. GitHub's manifest flow
+makes that a click: a pre-filled create page, then a code we exchange for the key.
+
+The flow is paste-based and hostless on the adopter's side: init prints ONE URL
+to the hosted helper page (`setup.outerloop.science`), which carries the
+manifest in its URL *fragment* (never sent to any server). The adopter opens it
+in any browser — laptop or, for a headless cluster, anywhere — clicks Create,
+and GitHub redirects back to that page with a one-time code the page displays.
+The adopter pastes the code here; we exchange it for the app id + key, write
+`github_app.<slug>.json` + the PEM (both 0600), help install the App, and capture
+the installation id. The written files are what `resolve_bot_auth` reads via
+`OUTERLOOP_GITHUB_APP_FILE`, the same path `outerloop start` uses.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import secrets
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from outerloop.appauth import API, build_app_jwt, signer_from_private_key
+from outerloop.paths import write_private
+
+# The hosted helper page: it auto-POSTs the manifest to GitHub, then displays the
+# returned code. It is also the manifest's redirect_url, so GitHub sends the code
+# straight back to it. Its own subdomain (the apex is the landing page), served
+# from web/ in this repo so the page and the CLI stay versioned together.
+# `OUTERLOOP_SETUP_URL` overrides it — a staging copy, or a self-hoster's own.
+SETUP_URL = os.environ.get("OUTERLOOP_SETUP_URL") or "https://setup.outerloop.science"
+
+# The App's fine-grained permissions — exactly what the fleet exercises: contents
+# to push commits, pull_requests to open/label PRs, issues for the courtesy note
+# on the requesting issue. Nothing else (least privilege; matches the live bot).
+DEFAULT_PERMISSIONS = {
+    "contents": "write",
+    "issues": "write",
+    "metadata": "read",
+    "pull_requests": "write",
+}
+
+# The POST/GET transport returns parsed JSON; injected so the pure logic tests
+# without a network.
+Transport = Callable[[urllib.request.Request], Any]
+
+
+def build_manifest(name: str, url: str, redirect_url: str = SETUP_URL) -> dict:
+    """The manifest GitHub creates the App from: our permissions, no webhook,
+    installable only on the creating account (`public=false`). `redirect_url` is
+    where GitHub returns the code — the hosted helper page by default."""
+    return {
+        "name": name,
+        "url": url,
+        "redirect_url": redirect_url,
+        "public": False,
+        "default_permissions": dict(DEFAULT_PERMISSIONS),
+        "hook_attributes": {"active": False, "url": url},
+    }
+
+
+def build_setup_url(manifest: dict, state: str, org: str = "") -> str:
+    """The one URL the adopter opens: the hosted helper page with the manifest,
+    state, and org packed into the URL *fragment* (base64) — a fragment stays in
+    the browser and is never sent to any server, so the manifest isn't logged."""
+    payload = json.dumps({"manifest": manifest, "state": state, "org": org})
+    encoded = base64.urlsafe_b64encode(payload.encode()).decode()
+    return f"{SETUP_URL}#{encoded}"
+
+
+def request_manifest_code(
+    name: str,
+    homepage_url: str,
+    org: str = "",
+    *,
+    print_fn: Callable[[str], None] = print,
+    input_fn: Callable[[str], str] = input,
+) -> str:
+    """Print the setup URL and read back the code the hosted page shows. Works
+    anywhere a browser can reach the internet — no localhost, no callback."""
+    state = secrets.token_urlsafe(16)
+    manifest = build_manifest(name, homepage_url)
+    url = build_setup_url(manifest, state, org)
+    where = f"the {org} organization" if org else "your account"
+    print_fn("Step 1 of 3: create the GitHub App.")
+    print_fn("  Open this link in a browser where you are signed in to GitHub (any machine):")
+    print_fn(f"\n  {url}\n")
+    print_fn(f"  GitHub shows a page titled 'Create GitHub App' under {where}. Click the")
+    host = urllib.parse.urlsplit(SETUP_URL).netloc or SETUP_URL
+    print_fn("  green 'Create GitHub App' button. GitHub then sends you to")
+    print_fn(f"  {host}, which shows a one-time code.")
+    return input_fn("Paste that code here: ").strip()
+
+
+def _default_transport(request: urllib.request.Request) -> Any:
+    with urllib.request.urlopen(request, timeout=30) as resp:
+        payload = resp.read()
+    return json.loads(payload) if payload else None
+
+
+def convert_manifest(code: str, *, transport: Transport | None = None) -> dict:
+    """Exchange the one-time manifest `code` for the App's credentials (id, pem,
+    slug, ...). GitHub invalidates the code on first use and after ~1h."""
+    transport = transport or _default_transport
+    request = urllib.request.Request(
+        f"{API}/app-manifests/{code}/conversions",
+        method="POST",
+        headers={
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    )
+    try:
+        body = transport(request)
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode(errors="replace")[:200]
+        raise ValueError(f"manifest conversion failed ({exc.code}): {detail}") from None
+    if not isinstance(body, dict):
+        raise ValueError("manifest conversion returned no object")
+    missing = [k for k in ("id", "pem", "slug") if not body.get(k)]
+    if missing:
+        raise ValueError(f"manifest conversion missing {', '.join(missing)}")
+    return body
+
+
+def save_app_creds(
+    conversion: dict, config_dir: Path, installation_id: int = 0
+) -> tuple[Path, Path]:
+    """Write the PEM (0600) and `github_app.<slug>.json` pointing at it, both
+    owner-only. `installation_id` stays 0 until the App is installed and
+    `capture_installation_id` fills it. Returns (pem_path, app_json_path)."""
+    config_dir.mkdir(parents=True, exist_ok=True)
+    slug = str(conversion["slug"])
+    pem_path = config_dir / f"{slug}-app.pem"
+    write_private(pem_path, str(conversion["pem"]))
+    app_json = config_dir / f"github_app.{slug}.json"
+    write_private(
+        app_json,
+        json.dumps(
+            {
+                "app_id": int(conversion["id"]),
+                "installation_id": int(installation_id),
+                "private_key": str(pem_path),
+            },
+            indent=2,
+        )
+        + "\n",
+    )
+    return pem_path, app_json
+
+
+def install_url(conversion: dict) -> str:
+    """Where the adopter installs the freshly created App on their repos."""
+    return f"https://github.com/apps/{conversion['slug']}/installations/new"
+
+
+def capture_installation_id(
+    app_id: int,
+    pem_path: Path,
+    owner: str = "",
+    *,
+    transport: Transport | None = None,
+    now: Callable[[], float] = time.time,
+) -> int:
+    """After the App is installed, its installation id for `owner` (or the sole
+    installation when `owner` is blank). App JWT → GET /app/installations. 0 when
+    nothing is installed yet — the caller retries after the adopter installs."""
+    transport = transport or _default_transport
+    sign = signer_from_private_key(pem_path)
+    jwt = build_app_jwt(app_id, now(), sign)
+    request = urllib.request.Request(
+        f"{API}/app/installations",
+        headers={
+            "Authorization": f"Bearer {jwt}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    )
+    installs = transport(request) or []
+    if owner:
+        for inst in installs:
+            if str((inst.get("account") or {}).get("login", "")).lower() == owner.lower():
+                return int(inst["id"])
+        return 0
+    return int(installs[0]["id"]) if installs else 0
+
+
+def set_installation_id(app_json: Path, installation_id: int) -> None:
+    """Fill the installation id into an already-written github_app.<slug>.json."""
+    data = json.loads(app_json.read_text())
+    data["installation_id"] = int(installation_id)
+    write_private(app_json, json.dumps(data, indent=2) + "\n")