@jesdi/skills 0.0.30 → 0.0.32

package/skills/implement-spec/driver_agents.py

@@ -0,0 +1,145 @@
+"""Model entries, the command line per provider, prompt rendering and the blocking launch.
+
+A model entry is `provider/model@effort`; a bare `model@effort` is anthropic.
+"""
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import re
+import shutil
+import signal
+import subprocess
+import threading
+import time
+from pathlib import Path
+
+SKILL = Path(__file__).resolve().parent
+# Minutes per role.
+TIMEOUTS = {"explorer": 30, "test-writer": 30, "implementer": 90, "reviewer": 45, "correctness": 30, "fixer": 60,
+            "final-reviewer": 60, "conflict": 30, "pr-writer": 20}
+PROVIDERS = {"anthropic": ("claude", ("low", "medium", "high", "xhigh", "max")),
+             "openai": ("codex", ("minimal", "low", "medium", "high", "xhigh"))}
+READ_ONLY = ("reviewer", "correctness", "final-reviewer", "pr-writer")
+# A process group is here only while its leader is not reaped: then no other process can have its id.
+LIVE: set[int] = set()
+STOPPED = False
+_LIVE = threading.Lock()
+
+
+def split(entry: str) -> tuple[str, str, str]:
+    head, _, effort = str(entry).partition("@")
+    provider, _, model = head.partition("/") if "/" in head else ("anthropic", "", head)
+    return provider, model, effort
+
+
+def _entry_error(role: str, entry: str, first: bool) -> str | None:
+    provider, model, effort = split(entry)
+    if provider not in PROVIDERS:
+        return f"{role}: model entry {entry} names an unknown provider (known: {', '.join(PROVIDERS)})"
+    cli, efforts = PROVIDERS[provider]
+    if not model or effort not in efforts:
+        return f"{role}: model entry {entry} needs a model and an effort from {', '.join(efforts)}"
+    if first and not shutil.which(cli):
+        return f"{role}: {cli} is not on PATH (model entry {entry})"
+    return None
+
+
+def correctness_entry(models: dict[str, list[str]]) -> str:
+    """The first correctness entry on another provider than the implementer's first entry; "" when there is none."""
+    own = split(models["implementer"][0])[0]
+    return next((entry for entry in models["correctness"] if split(entry)[0] != own), "")
+
+
+def load_models(path: str | None) -> tuple[dict[str, list[str]], list[str]]:
+    """The skill's default lists with the roles of `path` on top, and every entry error."""
+    models = json.loads((SKILL / "models.json").read_text())
+    try:
+        models = {**models, **(json.loads(Path(path).read_text()) if path else {})}  # a list is a TypeError
+        # The entry of each role whose CLI must be on PATH; entries[0]: an empty list is an error.
+        first = {**{role: entries[0] for role, entries in models.items()}, "correctness": correctness_entry(models)}
+        found = [_entry_error(role, entry, entry == first[role]) for role, entries in models.items() for entry in entries]
+        if not first["correctness"]:
+            found.append(f"correctness: no entry of its list ({', '.join(models['correctness'])}) is on another "
+                         f"provider than the implementer's first entry {models['implementer'][0]}; the correctness "
+                         "pass never runs on the implementer's provider")
+    except (OSError, ValueError, AttributeError, LookupError, TypeError) as exc:
+        return {}, [f"--models {path}: {exc!r}"]
+    return models, [error for error in found if error]
+
+
+def command(role: str, entry: str, report: str) -> list[str]:
+    """The CLI call for one agent; the prompt goes to its stdin."""
+    provider, model, effort = split(entry)
+    if provider == "openai":
+        # No --ephemeral: the rollout on disk is the trace. A read-only agent cannot write its report, so -o saves it.
+        tail = ["--sandbox", "read-only", "-o", report] if role in READ_ONLY else ["--sandbox", "workspace-write"]
+        return ["codex", "exec", "--model", model, "-c", f'model_reasoning_effort="{effort}"', *tail]
+    # stream-json keeps tool output in the log and ends with a result that has total_cost_usd.
+    return ["claude", "-p", "--model", model, "--effort", effort, "--permission-mode", "auto",
+            "--output-format", "stream-json", "--verbose"]
+
+
+def render(name: str, values: dict[str, str]) -> str:
+    return re.sub(r"\{([a-z_]+)\}", lambda m: values[m.group(1)], (SKILL / "prompts" / f"{name}.md").read_text())
+
+
+def tail(prompt: str, report: str) -> str:
+    """The end of a rendered prompt, from the line that names the report path."""
+    return prompt[prompt.rfind("\n", 0, prompt.rfind(report)):]
+
+
+def launch(argv: list[str], prompt: Path, log: Path, seconds: float, slot: str = ".") -> int | None:
+    """Run one agent in `slot` to its end, output to `log`. Returns the exit code, None after a timeout."""
+    with prompt.open() as stdin, log.open("w") as out:
+        with _LIVE:
+            if STOPPED:
+                raise InterruptedError("the run is stopped")
+            # Its own process group, so the children that edit the tree stop with it.
+            proc = subprocess.Popen(argv, cwd=slot, stdin=stdin, stdout=out, stderr=subprocess.STDOUT,
+                                    start_new_session=True)
+            LIVE.add(proc.pid)
+        try:
+            ended = _ended(proc.pid, seconds)
+        finally:
+            # Kill before the reap, under the lock of stop(): until then no other process can have the group id.
+            with _LIVE:
+                _kill(proc.pid)
+                LIVE.discard(proc.pid)
+            code = proc.wait()
+        return code if ended else None
+
+
+def _ended(pid: int, seconds: float) -> bool:
+    """True when the child `pid` ends within `seconds`; it is not reaped."""
+    # ponytail: waitid has no timeout, so this polls as `Popen.wait(timeout)` does, at most each 50 ms.
+    end, pause = time.monotonic() + seconds, 0.0005
+    while not os.waitid(os.P_PID, pid, os.WEXITED | os.WNOWAIT | os.WNOHANG):
+        left = end - time.monotonic()
+        if left <= 0:
+            return False
+        pause = min(pause * 2, left, 0.05)
+        time.sleep(pause)
+    return True
+
+
+def _kill(group: int) -> None:
+    """SIGKILL a process group. No such group means all gone; macOS answers EPERM for a group of zombies."""
+    with contextlib.suppress(ProcessLookupError, PermissionError):
+        os.killpg(group, signal.SIGKILL)
+
+
+def stop() -> None:
+    """Kill every running agent and let no other start."""
+    global STOPPED
+    with _LIVE:
+        STOPPED = True
+        for group in list(LIVE):
+            _kill(group)
+
+
+def cost(log: Path) -> str | None:
+    """The dollar cost the CLI reported; None for codex, which reports tokens only."""
+    found = re.findall(r'"total_cost_usd":\s*([0-9.]+)', log.read_text(errors="replace"))
+    return found[-1] if found else None

package/skills/implement-spec/driver_answers.py

@@ -0,0 +1,79 @@
+"""The answers file `.agent/implement-answers.json`, in the shape of skills/review-page/schema.md.
+
+    {"v": 1, "stage": "implement", "submitted": "changes", "revision": <decisions.json revision>,
+     "answers": {<question id>: <option id>, "<question id>.note": <text>}}
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+FILE = Path(".agent/implement-answers.json")
+
+
+def _offered(document: dict) -> dict[str, list[str]]:
+    """question id -> its option ids, for the open questions."""
+    return {q["id"]: [option["id"] for option in q["options"]] for q in document["questions"]}
+
+
+def pair(text: str) -> tuple[str, str]:
+    """One `--answer <question id>=<option id>`."""
+    question, equals, option = text.partition("=")
+    if not (question and equals and option):
+        raise ValueError(text)
+    return question, option
+
+
+def given(pairs: list[tuple[str, str]], document: dict) -> list[str]:
+    """Write the answers file for `--answer`, bound to `document`. Returns the usage errors; then no file is written."""
+    offered = _offered(document)
+    errors = [f"--answer {question}={option}: " + (f"{question} offers {', '.join(offered[question])}"
+                                                   if question in offered else f"no open question {question}")
+              for question, option in pairs if option not in offered.get(question, [])]
+    if pairs and not errors:
+        FILE.write_text(json.dumps({"v": 1, "stage": "implement", "submitted": "changes",
+                                    "revision": document["revision"], "answers": dict(pairs)}, indent=1) + "\n")
+    return errors
+
+
+def _unbound(file: object, revision: str) -> str:
+    """Why no answer of the file counts; "" when the file is a submission for this revision."""
+    if not isinstance(file, dict) or not isinstance(file.get("answers"), dict):
+        return "it is not an object with an `answers` object"
+    if (file.get("v"), file.get("stage")) != (1, "implement"):
+        return "it is not a version 1 file of the implement stage"
+    if not file.get("submitted"):
+        return "it is a draft: `submitted` is not set"
+    if file.get("revision") != revision:
+        return (f"its revision {str(file.get('revision'))[:12]} is not the revision {revision[:12]} of the "
+                "decisions file: the questions changed after it was written")
+    return ""
+
+
+def _each(given: dict, offered: dict[str, list[str]]) -> tuple[dict, list[str]]:
+    """(the answers and notes that count, a sentence per ignored one)."""
+    answers, ignored = {}, []
+    for key, value in given.items():
+        question = key.removesuffix(".note")
+        if question not in offered:
+            ignored.append(f"The answer for {key} in {FILE} is ignored: there is no open question {question}.")
+        elif key == question and value not in offered[question]:
+            ignored.append(f"The answer {value!r} for {question} in {FILE} is ignored: the question offers "
+                           f"{', '.join(offered[question])}.")
+        elif isinstance(value, str):
+            answers[key] = value
+    return answers, ignored
+
+
+def read(document: dict) -> tuple[dict, list[str]]:
+    """(the answers that count, a ledger sentence per ignored thing). With no open question nothing is read."""
+    offered = _offered(document)
+    if not (offered and FILE.exists()):
+        return {}, []
+    try:
+        file = json.loads(FILE.read_text())
+    except (OSError, ValueError) as exc:
+        return {}, [f"The answers file {FILE} is ignored: it is not readable JSON: {exc}."]
+    if why := _unbound(file, document["revision"]):
+        return {}, [f"The answers file {FILE} is ignored: {why}."]
+    return _each(file["answers"], offered)

package/skills/implement-spec/driver_decisions.py

@@ -0,0 +1,152 @@
+"""Human stops as bounded questions: the question kinds, decisions.json and what an answer does.
+
+A question in state.json `run.questions`; `answer` is None while it is open:
+    {id, title, why, evidence, options: [{id, description}], recommended, ticket, kind, subject, stop, answer}
+decisions.json: {run: <run.revision>, questions: [the open ones, first six fields], revision: <SHA-256 of the rest>}."""
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import NamedTuple
+
+PUBLIC = ("id", "title", "why", "evidence", "options", "recommended")
+CONTRADICTS = "locked test contradicts spec:"
+
+
+class Option(NamedTuple):
+    description: str
+    ruling: str
+    fields: dict  # what the ticket record gets when its stop is settled; {} keeps the ticket BLOCKED
+
+
+class Kind(NamedTuple):
+    parks: bool  # an open question of this kind ends the run with exit 2
+    title: str
+    why: str
+    recommended: str
+    options: dict[str, Option]
+
+
+KINDS = {
+    "locked-test": Kind(
+        True,
+        "Ticket {ticket}: the implementer reports that a locked test contradicts the spec: {subject}",
+        "The implementer of ticket {ticket} stopped with BLOCKED. The ticket and each ticket that it blocks wait "
+        "until the test or the implementer is overruled.",
+        "overrule-implementer",
+        {"overrule-test": Option(
+            "The test is wrong. The test-writer corrects it in one correction run, then the implementer runs again.",
+            "Ruling: {ticket} locked test overruled: the test-writer corrects {subject}, then the implementer runs "
+            "again.", {"phase": "test-writer", "note": "overruled"}),
+         "overrule-implementer": Option(
+            "The test is right. The implementer runs again and makes the test green as it is.",
+            "Ruling: {ticket} locked test stands: the implementer is overruled on {subject} and runs again.",
+            {"phase": "implement", "note": "stands"})}),
+    "finding": Kind(
+        False,
+        "Ticket {ticket}: a finding is open after fix round 4: {subject}",
+        "Four fix rounds did not close this finding, so ticket {ticket} is BLOCKED and each ticket that it blocks "
+        "waits.",
+        "split",
+        {"accept": Option(
+            "Close the finding as it is. The ticket merges when each of its open findings is accepted.",
+            "Ruling: {ticket} finding closed as it is (accept): {subject}.", {"phase": "merge"}),
+         "split": Option(
+            "Keep the ticket BLOCKED. The open part becomes a ticket of its own.",
+            "Ruling: {ticket} stays BLOCKED, the open part becomes a new ticket (split): {subject}.", {}),
+         "redesign": Option(
+            "Keep the ticket BLOCKED. The design changes before more work on it.",
+            "Ruling: {ticket} stays BLOCKED, the design changes first (redesign): {subject}.", {})}),
+    # A final-review question belongs to no ticket: its `ticket` is "".
+    "final-finding": Kind(
+        True,
+        "Final review: a finding is open after the second review round: {subject}",
+        "The final review ran its two rounds and this finding is open. Nothing is pushed while it is open.",
+        "fix",
+        {"fix": Option(
+            "Keep the finding open. The run ends with nothing pushed, and the finding is fixed before a push.",
+            "Ruling: final-review finding stays open and nothing is pushed (fix): {subject}.", {}),
+         "accept": Option(
+            "Close the finding as it is. The branch can be pushed when each open finding is accepted.",
+            "Ruling: final-review finding closed as it is (accept): {subject}.", {})}),
+}
+
+
+def contradicted(role: str, report: dict) -> str:
+    """The locked tests an implementer's BLOCKED report says contradict the spec; "" when it is not that stop."""
+    if role != "implementer" or report.get("status") != "BLOCKED":
+        return ""
+    return "; ".join(filter(None, (concern[len(CONTRADICTS):].strip() for concern in report["concerns"]
+                                   if concern.startswith(CONTRADICTS))))
+
+
+def question(kind: str, ticket: str, subject: str, evidence: list[str], asked: list[dict], stop: int) -> dict:
+    """A new open question, id `<NN>-<kind>-<n>` (`<kind>-<n>` with no ticket); n counts in `asked`, the whole run."""
+    made, values = KINDS[kind], {"ticket": ticket, "subject": subject}
+    number = 1 + sum((q["ticket"], q["kind"]) == (ticket, kind) for q in asked)
+    return {"id": f"{ticket}-{kind}-{number}".lstrip("-"), "title": made.title.format(**values), "why": made.why.format(**values),
+            "evidence": evidence, "recommended": made.recommended,
+            "options": [{"id": name, "description": option.description} for name, option in made.options.items()],
+            "ticket": ticket, "kind": kind, "subject": subject, "stop": stop, "answer": None}
+
+
+def stop(run: dict, kind: str, ticket: str, subjects: list[str], evidence: list[str]) -> None:
+    """Count one stop in `run` and add one open question of `kind` per subject. No subject is no stop."""
+    run["stops"] += bool(subjects)
+    for subject in subjects:
+        run["questions"].append(question(kind, ticket, subject, evidence, run["questions"], run["stops"]))
+
+
+def decides(kind: str, subjects: int) -> str:
+    return f"the operator decides on {subjects} question{'s' * (subjects > 1)} of kind {kind}"
+
+
+def document(run: dict) -> dict:
+    """decisions.json for `run` of state.json."""
+    body = {"run": run["revision"],
+            "questions": [{name: q[name] for name in PUBLIC} for q in run["questions"] if q["answer"] is None]}
+    canonical = json.dumps(body, sort_keys=True, separators=(",", ":"))
+    return {"revision": hashlib.sha256(canonical.encode()).hexdigest(), **body}
+
+
+def rulings(questions: list[dict]) -> list[str]:
+    """The ruling sentence of each answered question, without the note of the operator."""
+    return [KINDS[q["kind"]].options[q["answer"]].ruling.format(**q) for q in questions if q["answer"] is not None]
+
+
+def parked(questions: list[dict]) -> bool:
+    return any(q["answer"] is None and KINDS[q["kind"]].parks for q in questions)
+
+
+def _settled(questions: list[dict], ticket: str, stop: int) -> dict:
+    """The ticket fields from the answers of one stop; {} while one is open or one keeps the ticket BLOCKED."""
+    fields = [q["answer"] and KINDS[q["kind"]].options[q["answer"]].fields
+              for q in questions if (q["ticket"], q["stop"]) == (ticket, stop)]
+    return {name: value for one in fields for name, value in one.items()} if all(fields) else {}
+
+
+def apply(questions: list[dict], answers: dict) -> tuple[list[str], dict[str, dict]]:
+    """Answer the open questions in `answers`. Returns (a ruling per answer, ticket -> fields that let it go on)."""
+    rulings, stops = [], {}
+    for q in questions:
+        if q["answer"] is None and q["id"] in answers:
+            q["answer"] = answers[q["id"]]
+            note = answers.get(f"{q['id']}.note")
+            rulings.append(KINDS[q["kind"]].options[q["answer"]].ruling.format(**q)
+                           + f" Note of the operator: {note}" * bool(note))
+            stops[q["ticket"]] = q["stop"]
+    moved = {ticket: _settled(questions, ticket, stop) for ticket, stop in stops.items()}
+    return rulings, {ticket: fields for ticket, fields in moved.items() if fields}
+
+
+def text(open_questions: list[dict], answers: str, page: str) -> str:
+    """What the operator reads at a stop in local mode."""
+    lines = []
+    for q in open_questions:
+        lines += [f"Question {q['id']}: {q['title']}", f"  Why: {q['why']}", f"  Evidence: {', '.join(q['evidence'])}"]
+        lines += [f"  {o['id']}{' (recommended)' * (o['id'] == q['recommended'])}: {o['description']}"
+                  for o in q["options"]]
+    if lines:
+        lines.append(f"Answer each question and run the driver again: --answer <question id>=<option id>, or submit "
+                     f"{page}, which writes {answers}.")
+    return "".join(line + "\n" for line in lines)