outerloop-science 0.1.0__py3-none-any.whl

outerloop/intake.py

@@ -0,0 +1,126 @@
+"""The requested lane: maintainer issues become runs.
+
+An open issue on the target repo qualifies when its author carries repo
+standing (same association gate as review comments). The tick claims at most
+one per cycle by commenting a claim marker, then submits a climb job whose
+task carries the issue text data-fenced; the resulting PR references the
+issue, and the run's report lands back on the issue thread — the loop closes
+with whoever asked (docs/design/architecture.md, "The life of a run").
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+from outerloop.brief import MAX_TASK_CHARS, cap, code_fence
+from outerloop.contract import Contract
+from outerloop.followup import QUALIFYING_ASSOCIATIONS
+from outerloop.github import is_own_login
+from outerloop.markers import has_label, has_marker, marker
+
+log = logging.getLogger(__name__)
+
+CLAIM_MARKER = marker("claimed")
+# Posted (by the bot only) to undo a claim whose run never started — a failed
+# submit must not strand the issue, since the claim scan skips claimed issues.
+RELEASE_MARKER = marker("claim-released")
+# Claim attempts per issue before intake gives up on it: a durable submit
+# failure must not claim/release (and comment) forever. Same idea as the
+# steward lane's MAX_STEWARD_ATTEMPTS.
+MAX_INTAKE_ATTEMPTS = 3
+
+
+@dataclass(frozen=True)
+class IssueTask:
+    number: int
+    title: str
+    body: str
+    author: str
+    benchmark: str  # inferred from the issue text against the contract
+
+
+def infer_benchmark(text: str, contract: Contract) -> str:
+    """The single contract benchmark the issue names, or "" if not exactly
+    one — ambiguity is a human problem, not a guess."""
+    lowered = text.casefold()
+    named = [b.name for b in contract.benchmarks if b.name.casefold() in lowered]
+    return named[0] if len(named) == 1 else ""
+
+
+def qualifying_issue(issue: dict, bot_login: str) -> bool:
+    author = str((issue.get("user") or {}).get("login", ""))
+    if is_own_login(author, bot_login):
+        return False  # the kernel's own issues (research log, alarms) are never orders
+    if str(issue.get("author_association", "")) not in QUALIFYING_ASSOCIATIONS:
+        return False
+    return bool(str(issue.get("title") or "").strip())
+
+
+def pick_issue(github, repo: str, contract: Contract, bot_login: str) -> IssueTask | None:
+    """The oldest qualifying, unclaimed issue that names exactly one
+    benchmark. At most one — intake is deliberately slow."""
+    if not bot_login.strip():
+        # fail closed like the steward picker: with no identity the claim
+        # scan below would see NO claims and re-claim every tick — an
+        # unbounded paid loop
+        log.warning("pick_issue: bot_login is blank; intake lane sits out")
+        return None
+    issues = sorted(github.list_open_issues(repo), key=lambda i: i.get("number", 0))
+    for issue in issues:
+        labels = {
+            str(label.get("name", "")).casefold()
+            for label in issue.get("labels", [])
+            if isinstance(label, dict)
+        }
+        if has_label(labels, "steward"):
+            continue  # the steward lane's, never the solver's
+        if not qualifying_issue(issue, bot_login):
+            continue
+        number = int(issue["number"])
+        claimed = False
+        attempts = 0
+        for c in github.list_comments(repo, number):
+            author = str((c.get("user") or {}).get("login", ""))
+            if not is_own_login(author, bot_login):
+                continue  # only the bot's own markers count — no forged releases
+            body = str(c.get("body", ""))
+            if has_marker(body, "claimed"):
+                claimed = True
+                attempts += 1
+            if has_marker(body, "claim-released"):
+                claimed = False
+        if claimed:
+            continue  # already claimed by a run
+        if attempts >= MAX_INTAKE_ATTEMPTS:
+            log.info("issue #%s burned %d claim attempts; needs a human look", number, attempts)
+            continue
+        text = f"{issue.get('title', '')}\n{issue.get('body') or ''}"
+        benchmark = infer_benchmark(text, contract)
+        if not benchmark:
+            log.info("issue #%s names zero or several benchmarks; skipping", number)
+            continue
+        return IssueTask(
+            number=number,
+            title=str(issue.get("title") or ""),
+            body=str(issue.get("body") or ""),
+            author=str((issue.get("user") or {}).get("login", "")),
+            benchmark=benchmark,
+        )
+    return None
+
+
+def issue_hypothesis(task: IssueTask) -> str:
+    """The task text for the brief: the maintainer's ask, data-fenced.
+
+    The author passed the standing gate, so the REQUEST is legitimate; the
+    fence marks where quoted text ends and the harness's authority resumes.
+    """
+    quoted = cap(f"{task.title}\n\n{task.body}".strip(), MAX_TASK_CHARS - 400)
+    fence = code_fence(quoted)
+    return (
+        f"A maintainer (@{task.author}) opened issue #{task.number} requesting "
+        f"work on the `{task.benchmark}` benchmark. Their request:\n"
+        f"{fence}\n{quoted}\n{fence}\n"
+        "Address the request's substance within the contract's rules."
+    )

outerloop/launchlog.py

@@ -0,0 +1,239 @@
+"""The per-run launch ledger: append-only JSON lines in the run directory, one
+record when a sleep's launches are submitted and one when each job's result
+comes back at the wake. It is what `history` reads and what labels a launch in
+the queue view (docs/design/session-watcher.md, "History"). Kernel-owned: the
+run directory is never the session's to write."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from outerloop.syscall import Launch, LaunchResult, launch_jobs
+
+LEDGER = "launches.jsonl"
+# generous: a run is depth_k launches x sleep_k sleeps x the array width, far below this
+MAX_LEDGER_BYTES = 4_000_000
+
+
+def _append(run_dir: Path, rows: list[dict[str, Any]]) -> None:
+    if not rows:
+        return
+    run_dir.mkdir(parents=True, exist_ok=True)
+    path = run_dir / LEDGER
+    # a crash mid-append leaves a torn last line; start on a fresh one so the
+    # torn line is the only record lost, never the next one too
+    torn = False
+    try:
+        with path.open("rb") as fh:
+            fh.seek(-1, 2)
+            torn = fh.read(1) != b"\n"
+    except OSError:
+        pass
+    with path.open("a", encoding="utf-8") as fh:
+        if torn:
+            fh.write("\n")
+        for row in rows:
+            fh.write(json.dumps(row, sort_keys=True) + "\n")
+
+
+def append_submitted(
+    run_dir: Path, *, sleep: int, launches: tuple[Launch, ...], job_ids: list[str], at: float
+) -> None:
+    """One record per launch of a sleep, with the job ids it fanned out to. The
+    ids are positional over `launch_jobs` order, exactly as the park recorded
+    them; a launch whose ids are missing (an older park) gets none. A launch
+    already recorded under this (sleep, name) is not written again: a run
+    re-parks the same sleep through a multi-stage gate, and the first record
+    is the one with the author's words."""
+    known = {
+        (int(row.get("sleep") or 0), str(row.get("name") or ""))
+        for row in read_ledger(run_dir)
+        if row.get("event") == "submitted"
+    }
+    # one id per launch (a sweep is one Slurm job array), or one per task for
+    # a park recorded when arrays were separate jobs
+    per_launch = len(job_ids) == len(launches)
+    rows: list[dict[str, Any]] = []
+    k = 0
+    for launch in launches:
+        n = 1 if per_launch else len(launch_jobs(launch))
+        ids = job_ids[k : k + n]
+        k += n
+        if (sleep, launch.name) in known:
+            continue
+        rows.append(
+            {
+                "event": "submitted",
+                "sleep": sleep,
+                "name": launch.name,
+                "why": launch.why,
+                "minutes": launch.minutes,
+                "array": launch.array,
+                "concurrency": launch.concurrency,
+                "job_ids": list(ids),
+                "at": at,
+            }
+        )
+    _append(run_dir, rows)
+
+
+def append_ended(
+    run_dir: Path,
+    *,
+    sleep: int,
+    results: tuple[LaunchResult, ...],
+    at: float,
+    elapsed_seconds: list[int | None] | None = None,
+) -> None:
+    """One record per job that came back at the wake, keyed to its sleep, with
+    how long it ran when the compute could say (aligned with `results`) and
+    the last line it printed — captured now, because a later launch with the
+    same name overwrites the job dir. A job already recorded as ended under
+    this (sleep, name) is not written again: a submitted park's wake and the
+    author's wake may both see the same jobs."""
+    known = {
+        (int(row.get("sleep") or 0), str(row.get("name") or ""))
+        for row in read_ledger(run_dir)
+        if row.get("event") == "ended"
+    }
+    _append(
+        run_dir,
+        [
+            {
+                "event": "ended",
+                "sleep": sleep,
+                "name": r.name,
+                "exit_code": r.exit_code,
+                "state": r.slurm_state,
+                "elapsed": (
+                    elapsed_seconds[i]
+                    if elapsed_seconds is not None and i < len(elapsed_seconds)
+                    else None
+                ),
+                "last_line": last_line(r.stdout_tail),
+                "at": at,
+            }
+            for i, r in enumerate(results)
+            if (sleep, r.name) not in known
+        ],
+    )
+
+
+def last_line(text: str, cap: int = 160) -> str:
+    """The last non-empty line of a job's output — its result line, as the
+    wake shows the author — on one line and bounded. "" when there is none."""
+    for line in reversed(text.splitlines()):
+        flat = " ".join(line.split())
+        if flat:
+            return flat[:cap]
+    return ""
+
+
+def read_ledger(run_dir: Path) -> list[dict[str, Any]]:
+    """Every record, oldest first; a malformed line is skipped, a missing file
+    is an empty history."""
+    try:
+        with (run_dir / LEDGER).open("rb") as fh:
+            raw = fh.read(MAX_LEDGER_BYTES)
+    except OSError:
+        return []
+    rows: list[dict[str, Any]] = []
+    for line in raw.decode("utf-8", "replace").splitlines():
+        try:
+            row = json.loads(line)
+        except ValueError:
+            continue
+        if isinstance(row, dict):
+            rows.append(row)
+    return rows
+
+
+def history(run_dir: Path) -> list[dict[str, Any]]:
+    """Submitted launches in order, each with the ended records of its jobs.
+    The identity is (sleep, name): a name is unique within one sleep only."""
+    rows = read_ledger(run_dir)
+    entries: dict[tuple[int, str], dict[str, Any]] = {}
+    for row in rows:
+        if row.get("event") != "submitted":
+            continue
+        key = (int(row.get("sleep") or 0), str(row.get("name") or ""))
+        entries[key] = {
+            "sleep": row.get("sleep"),
+            "name": row.get("name"),
+            "why": row.get("why", ""),
+            "minutes": row.get("minutes"),
+            "array": row.get("array", 1),
+            "concurrency": row.get("concurrency", 0),
+            "job_ids": list(row.get("job_ids") or []),
+            "submitted_at": row.get("at"),
+            "jobs": [],
+        }
+    for row in rows:
+        if row.get("event") != "ended":
+            continue
+        # an array member is `<name>.<i>`; the dot is outside the name alphabet
+        launch_name = str(row.get("name") or "").split(".", 1)[0]
+        entry = entries.get((int(row.get("sleep") or 0), launch_name))
+        if entry is not None:
+            entry["jobs"].append(
+                {
+                    "name": row.get("name"),
+                    "exit_code": row.get("exit_code"),
+                    "state": row.get("state", ""),
+                    "elapsed": row.get("elapsed"),
+                    "last_line": str(row.get("last_line") or ""),
+                    "ended_at": row.get("at"),
+                }
+            )
+    return list(entries.values())
+
+
+def experiments_rows(run_dir: Path) -> list[dict[str, Any]]:
+    """The pull request's experiments table: one row per job of every launch
+    this run — its sleep, name and why, how it ended and how long it ran, and
+    the last line it printed, all from the ledger (the job dir is overwritten
+    by a later launch of the same name). A job not back yet says so."""
+    rows: list[dict[str, Any]] = []
+    for entry in history(run_dir):
+        ended = {str(j.get("name")): j for j in entry["jobs"]}
+        array = int(entry.get("array") or 1)
+        name = str(entry.get("name") or "")
+        jobs = [name] if array <= 1 else [f"{name}.{k}" for k in range(array)]
+        for job in jobs:
+            j = ended.get(job)
+            rows.append(
+                {
+                    "sleep": entry.get("sleep"),
+                    "launch": name,
+                    "why": str(entry.get("why") or ""),
+                    "array": array,
+                    "concurrency": int(entry.get("concurrency") or 0),
+                    "job": job,
+                    "back": j is not None,
+                    "exit_code": j.get("exit_code") if j else None,
+                    "state": str(j.get("state") or "") if j else "",
+                    "elapsed": j.get("elapsed") if j else None,
+                    "result": str(j.get("last_line") or "") if j else "",
+                }
+            )
+    return rows
+
+
+def why_by_job(run_dir: Path) -> dict[str, dict[str, Any]]:
+    """Slurm job id -> the launch it belongs to (name, why, sleep): how the
+    queue view labels a launch job for every agent."""
+    out: dict[str, dict[str, Any]] = {}
+    for row in read_ledger(run_dir):
+        if row.get("event") != "submitted":
+            continue
+        for job_id in row.get("job_ids") or []:
+            out[str(job_id)] = {
+                "name": row.get("name", ""),
+                "why": row.get("why", ""),
+                "sleep": row.get("sleep"),
+                "array": int(row.get("array") or 1),
+                "concurrency": int(row.get("concurrency") or 0),
+            }
+    return out

outerloop/limits.py

@@ -0,0 +1,80 @@
+"""Effective session/job limits: contract wishes clamped by our ceilings.
+
+Contracts live in TARGET repos and are untrusted input (contract.py's
+threat model). A target may therefore SHAPE the orchestrator's spend on it
+— shorter sessions, tighter job walltimes — but must never be able to
+raise it: every contract value is clamped into [floor, ceiling], and the
+ceilings are code on the orchestrator side, not configuration a target
+can reach. Absent values fall back to the defaults the pilot has run with
+all along.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+# (default, floor, ceiling) per knob. Floors keep a hostile-or-typo'd
+# contract from starving runs into uselessness (a 1-turn session still
+# spends money and reports nothing). CEILING == DEFAULT, deliberately:
+# contracts are merged by TARGET-repo maintainers, not by us, so any
+# ceiling above the default would let them raise our spend — the knobs
+# shape strictly downward. Raising a target's budget is an
+# orchestrator-side decision (config we control), not a contract edit.
+# Raised from 60/60/90/60 on 2026-08-09 (maintainer decision): the first
+# steward work order to BUILD an env burned its full 60-turn budget mid-
+# work — session budgets sized for solver tweaks starve construction work.
+# floor = session floor + overhead + self-deadline margin: even at the
+# floors, a session must fit inside its job with the ending's runway.
+# Public: the tick's OUTERLOOP_MAX_JOB_MINUTES knob floors here too.
+ATTEMPT_JOB_MINUTES_FLOOR = 40
+
+# Public: the tick shrinks a capped job's session with the same floor the
+# contract clamp uses.
+SESSION_MINUTES_FLOOR = 10
+
+_BOUNDS: dict[str, tuple[int, int, int]] = {
+    "session_max_turns": (120, 10, 120),
+    "session_minutes": (90, SESSION_MINUTES_FLOOR, 90),
+    "attempt_job_minutes": (120, ATTEMPT_JOB_MINUTES_FLOOR, 120),
+    "followup_job_minutes": (90, 20, 90),
+}
+
+# A climb job must outlive its session long enough for the orchestrator's
+# own work around it (clone, two evals, publish, ending writes). Public:
+# the tick's cap warning uses it as the no-runway threshold too.
+ATTEMPT_OVERHEAD_MINUTES = 20
+
+
+@dataclass(frozen=True)
+class EffectiveLimits:
+    session_max_turns: int
+    session_minutes: int
+    attempt_job_minutes: int
+    followup_job_minutes: int
+
+
+def _clamp(name: str, value: int | None) -> int:
+    default, floor, ceiling = _BOUNDS[name]
+    if value is None:
+        return default
+    return max(floor, min(int(value), ceiling))
+
+
+def effective_limits(budgets: Any = None) -> EffectiveLimits:
+    """Resolve a contract's optional budget knobs into enforceable limits.
+
+    `budgets` is the contract's Budgets model (or None for pure defaults);
+    unknown/absent attributes read as None. The session is finally shrunk
+    to fit inside the climb job with room for the orchestrator's overhead —
+    a session that outlives its job ends as a kill, not a report.
+    """
+    values = {
+        name: _clamp(name, getattr(budgets, name, None) if budgets is not None else None)
+        for name in _BOUNDS
+    }
+    max_session = values["attempt_job_minutes"] - ATTEMPT_OVERHEAD_MINUTES
+    if values["session_minutes"] > max_session:
+        floor = _BOUNDS["session_minutes"][1]
+        values["session_minutes"] = max(floor, max_session)
+    return EffectiveLimits(**values)