agentforge-framework 0.2.0__py3-none-any.whl

agentforge_framework/core/plan_format.py

@@ -0,0 +1,272 @@
+"""The Issue body: prose for the human, one JSON block for the Agent.
+
+ADR-0002 puts the handoff contract in a GitHub issue and ADR-0003 freezes it
+once written. Those two together mean the body has to satisfy two readers at
+once. A human judges the plan before any code is written, so the body is
+Markdown. `agentforge implement` recovers the Plan a week later on a different
+machine, so the body also carries a delimited JSON block and the parser reads
+that and only that. No heuristics, no scraping of the prose.
+
+The prose is generated from the same `PlanDocument` as the block, so the two
+cannot disagree at filing time. If a human edits one half afterwards, the block
+is the authority — it is what every Role parses.
+"""
+
+from __future__ import annotations
+
+import json
+
+from .contracts import (
+    PLAN_FORMAT_VERSION,
+    ContextPack,
+    Plan,
+    PlanDocument,
+    Roster,
+    Task,
+)
+
+PLAN_OPEN = "<!-- agentforge:plan -->"
+PLAN_CLOSE = "<!-- /agentforge:plan -->"
+
+RESULT_OPEN = "<!-- agentforge:result -->"
+RESULT_CLOSE = "<!-- /agentforge:result -->"
+
+#: A Gate's verdict travels in a marker of its own rather than in a result
+#: block, because a Gate is not an Agent and `parse_run_log` must keep returning
+#: Agent Results only. See ADR-0008.
+GATE_OPEN = "<!-- agentforge:gate -->"
+GATE_CLOSE = "<!-- /agentforge:gate -->"
+
+
+class PlanFormatError(ValueError):
+    """An Issue body does not carry a plan AgentForge can execute."""
+
+
+def render_issue_title(task: Task) -> str:
+    """A title a human recognizes in a list of thirty issues."""
+    statement = " ".join(task.statement.split())
+    if len(statement) <= 72:
+        return statement
+    return statement[:69].rstrip(" ,.;:-") + "..."
+
+
+def render_issue_body(task: Task, document: PlanDocument) -> str:
+    """The full Issue body: readable plan, then the frozen block."""
+    parts = [
+        "## Task",
+        "",
+        f"> {task.statement.strip()}",
+        "",
+        "## Plan",
+        "",
+        document.plan.summary.strip(),
+        "",
+    ]
+
+    if document.plan.steps:
+        parts += ["### Steps", ""]
+        for index, step in enumerate(document.plan.steps, start=1):
+            parts.append(f"{index}. **{step.id}** — {step.intent}")
+            if step.files:
+                parts.append(f"   - Files: {', '.join(f'`{f}`' for f in step.files)}")
+            if step.acceptance:
+                parts.append(f"   - Done when: {step.acceptance}")
+        parts.append("")
+
+    if document.plan.constraints:
+        parts += ["### Constraints", ""]
+        parts += [f"- {constraint}" for constraint in document.plan.constraints]
+        parts.append("")
+
+    parts += [
+        "## Roster",
+        "",
+        (
+            f"Running the `{document.workflow}` Workflow, in this order. "
+            "A Gate between two Steps holds the Run until it clears."
+        ),
+        "",
+        "| Order | Role | Model Tier |",
+        "| --- | --- | --- |",
+    ]
+    for index, role in enumerate(document.roster, start=1):
+        parts.append(f"| {index} | {role.name} | `{role.tier}` |")
+    parts.append("")
+
+    if document.context:
+        parts += ["## Context Pack", ""]
+        for label, values in (
+            ("Files", document.context.files),
+            ("Symbols", document.context.symbols),
+            ("References", document.context.references),
+            ("Conventions", document.context.conventions),
+        ):
+            if values:
+                parts.append(f"- {label}: " + ", ".join(values))
+        parts.append("")
+
+    if document.notes:
+        parts += ["## Notes", ""]
+        parts += [f"- {note}" for note in document.notes]
+        parts.append("")
+
+    parts += [
+        "---",
+        "",
+        PLAN_OPEN,
+        "```json",
+        json.dumps(document.to_dict(), indent=2, sort_keys=True),
+        "```",
+        PLAN_CLOSE,
+        "",
+        (
+            "*Filed by AgentForge. The block above is the frozen execution contract "
+            "(ADR-0003). Every Role parses it; edit it rather than the prose.*"
+        ),
+    ]
+    return "\n".join(parts) + "\n"
+
+
+def extract_plan_payload(text: str) -> dict:
+    """The raw plan block, before Roles are resolved.
+
+    The Orchestrator needs this: the model it just ran may have named a Role
+    that does not exist yet, and dropping those is Roster selection's job rather
+    than the parser's.
+    """
+    payload = _extract_block(text, PLAN_OPEN, PLAN_CLOSE)
+    if payload is None:
+        raise PlanFormatError(
+            "no AgentForge plan block found; "
+            "it was not written by `agentforge plan`, or the block was deleted"
+        )
+
+    try:
+        data = json.loads(payload)
+    except json.JSONDecodeError as exc:
+        raise PlanFormatError(f"plan block is not valid JSON: {exc}") from exc
+
+    if not isinstance(data, dict) or "plan" not in data:
+        raise PlanFormatError("plan block carries no `plan`")
+    return data
+
+
+def parse_issue_body(body: str, resolve=None) -> PlanDocument:
+    """Recover the frozen `PlanDocument` from an Issue body."""
+    data = extract_plan_payload(body)
+
+    version = int(data.get("version", PLAN_FORMAT_VERSION))
+    if version > PLAN_FORMAT_VERSION:
+        raise PlanFormatError(
+            f"issue carries plan format v{version}; this AgentForge understands "
+            f"v{PLAN_FORMAT_VERSION}. Upgrade AgentForge."
+        )
+
+    if resolve is None:
+        from ..agents import resolve_role as resolve
+
+    try:
+        document = PlanDocument.from_dict(data, resolve)
+    except KeyError as exc:
+        raise PlanFormatError(f"plan block is missing {exc}") from exc
+
+    if not document.roster:
+        raise PlanFormatError("plan block carries an empty Roster; there is nothing to run")
+    return document
+
+
+def render_result_block(payload: dict) -> str:
+    """The block a Role is asked to end its output with. Shared by every Provider."""
+    return "\n".join(
+        [RESULT_OPEN, "```json", json.dumps(payload, indent=2), "```", RESULT_CLOSE]
+    )
+
+
+def extract_result_block(text: str) -> dict | None:
+    """Pull an Agent's structured verdict out of its free text, if it wrote one."""
+    payload = _extract_block(text, RESULT_OPEN, RESULT_CLOSE)
+    if payload is None:
+        return None
+    try:
+        data = json.loads(payload)
+    except json.JSONDecodeError:
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def render_gate_block(payload: dict) -> str:
+    """The block a Gate ends its Run Log entry with. Written by AgentForge only.
+
+    A Role is asked for a result block; nobody is asked for one of these. The
+    Gate that evaluated writes it, so the next Run can read back which Gate
+    spoke and what it said.
+    """
+    return "\n".join(
+        [GATE_OPEN, "```json", json.dumps(payload, indent=2), "```", GATE_CLOSE]
+    )
+
+
+def extract_gate_block(text: str) -> dict | None:
+    """Pull a Gate's verdict out of a Run Log comment, if it carries one."""
+    payload = _extract_block(text, GATE_OPEN, GATE_CLOSE)
+    if payload is None:
+        return None
+    try:
+        data = json.loads(payload)
+    except json.JSONDecodeError:
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _extract_block(text: str, open_marker: str, close_marker: str) -> str | None:
+    """The JSON inside a delimited, fenced block. Last one wins.
+
+    Last rather than first because an Agent that quotes the instructions it was
+    given writes the example before it writes its answer.
+
+    The closing fence is the last one inside the markers rather than the first,
+    because JSON escapes no backticks: a Gate quoting a failing suite and an
+    Agent quoting the code it changed both put fences inside the payload, and
+    stopping at the first one truncates the JSON into something unparseable.
+    The close marker is what bounds the search, so a block missing one falls
+    back to the first fence rather than reaching into whatever follows it.
+    """
+    start = text.rfind(open_marker)
+    if start == -1:
+        return None
+    end = text.find(close_marker, start)
+    bounded = end != -1
+    inner = text[start + len(open_marker) : end if bounded else len(text)]
+
+    fence = inner.find("```")
+    if fence == -1:
+        return inner.strip() or None
+    inner = inner[fence + 3 :]
+    inner = inner.removeprefix("json")
+    closing = inner.rfind("```") if bounded else inner.find("```")
+    if closing != -1:
+        inner = inner[:closing]
+    return inner.strip() or None
+
+
+__all__ = [
+    "GATE_CLOSE",
+    "GATE_OPEN",
+    "PLAN_CLOSE",
+    "PLAN_OPEN",
+    "RESULT_CLOSE",
+    "RESULT_OPEN",
+    "ContextPack",
+    "Plan",
+    "PlanDocument",
+    "PlanFormatError",
+    "Roster",
+    "extract_gate_block",
+    "extract_plan_payload",
+    "extract_result_block",
+    "parse_issue_body",
+    "render_gate_block",
+    "render_issue_body",
+    "render_issue_title",
+    "render_result_block",
+]

agentforge_framework/core/process.py

@@ -0,0 +1,141 @@
+"""The one place AgentForge touches an external process.
+
+`gh`, the coding-agent CLIs, `git`, and the vendored unslop scanners all route
+through this port. Nothing else in the codebase imports `subprocess`.
+
+The payoff is in the test suite: a fake runner scripted by argument-vector
+prefix stands in for every external tool at once, so the whole framework above
+this line runs as real code with no network, no GitHub account, and no
+coding-agent CLI installed.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+
+class MissingBinary(RuntimeError):
+    """A required external tool is not on PATH.
+
+    Raised in preference to a bare `FileNotFoundError` so the message names the
+    binary a user has to install rather than the syscall that failed.
+    """
+
+    def __init__(self, binary: str, hint: str = "") -> None:
+        message = f"{binary!r} is not installed or not on PATH"
+        if hint:
+            message = f"{message}. {hint}"
+        super().__init__(message)
+        self.binary = binary
+
+
+@dataclass(frozen=True)
+class CommandResult:
+    """Exit status, standard output, and standard error. Nothing else."""
+
+    argv: tuple[str, ...]
+    returncode: int
+    stdout: str = ""
+    stderr: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+    def check(self) -> CommandResult:
+        """Return self, or raise with enough context to debug the failure."""
+        if self.ok:
+            return self
+        rendered = " ".join(self.argv)
+        detail = (self.stderr or self.stdout or "").strip()
+        raise CommandFailed(f"`{rendered}` exited {self.returncode}: {detail[:800]}", result=self)
+
+
+class CommandFailed(RuntimeError):
+    """An external process ran and returned a non-zero status."""
+
+    def __init__(self, message: str, result: CommandResult) -> None:
+        super().__init__(message)
+        self.result = result
+
+
+class CommandRunner(Protocol):
+    """The port. An argument vector and a working directory go in; a result
+    comes out."""
+
+    def run(
+        self,
+        argv: Sequence[str],
+        *,
+        cwd: Path | str | None = None,
+        stdin: str | None = None,
+        timeout: float | None = None,
+    ) -> CommandResult: ...
+
+    def has_binary(self, binary: str) -> bool:
+        """Whether the tool is available, checked before a Run spends anything."""
+        ...
+
+
+class SubprocessRunner:
+    """The real implementation. The only `subprocess` call site in AgentForge."""
+
+    def run(
+        self,
+        argv: Sequence[str],
+        *,
+        cwd: Path | str | None = None,
+        stdin: str | None = None,
+        timeout: float | None = None,
+    ) -> CommandResult:
+        argv = tuple(str(part) for part in argv)
+        try:
+            completed = subprocess.run(
+                argv,
+                cwd=str(cwd) if cwd else None,
+                input=stdin,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=timeout,
+                # A non-zero exit is a result here, not an exception. `gh` uses
+                # one to mean "no such issue" and the unslop scanners use one to
+                # mean "found something"; callers decide what it means.
+                check=False,
+            )
+        except FileNotFoundError as exc:
+            raise MissingBinary(argv[0]) from exc
+        except subprocess.TimeoutExpired as exc:
+            return CommandResult(
+                argv=argv,
+                returncode=124,
+                stdout=_text(exc.stdout),
+                stderr=f"timed out after {timeout}s",
+            )
+        return CommandResult(
+            argv=argv,
+            returncode=completed.returncode,
+            stdout=completed.stdout or "",
+            stderr=completed.stderr or "",
+        )
+
+    def has_binary(self, binary: str) -> bool:
+        return shutil.which(binary) is not None
+
+
+def _text(value: bytes | str | None) -> str:
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+    return value or ""
+
+
+def require(runner: CommandRunner, binary: str, hint: str = "") -> None:
+    """Fail before a model is invoked rather than halfway through a Run."""
+    if not runner.has_binary(binary):
+        raise MissingBinary(binary, hint)

agentforge_framework/core/project.py

@@ -0,0 +1,262 @@
+"""What `agentforge init` learns about a repository, and what it writes down.
+
+Two halves, kept apart because they are held to different standards. Detection
+reads the repository and answers three questions — which Plugins answer for it,
+what its suite appears to be, which Provider it will drive — and is allowed to
+be wrong, because everything it produces is printed for a human to correct.
+Rendering turns the answers into `.agentforge/config.yaml`, and is allowed to
+write only what `core.config` reads back.
+
+That second rule is the whole shape of this module. `docs/PLAN.md` promised a
+config file owning tier mapping, Provider selection, plugin activation, and Gate
+policy; `load_config` reads two keys. Writing the other three would be writing
+keys nothing consults, which is worse than not writing them: a human who edits a
+key that has no effect has been lied to by the file. So what init detects and
+cannot yet persist it prints, and the gap stays visible. See ADR-0020.
+
+Nothing here decides whether the repository may be written to. `open_repository`
+answers that, and the CLI asks it first, so a repository that cannot host a Run
+never gets a config file suggesting it can.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml as pyyaml
+
+from .config import DEFAULT_CAPABILITIES, DEFAULT_TEST_SUITE, CapabilityTier
+
+CONFIG_DIR = ".agentforge"
+CONFIG_FILE = "config.yaml"
+
+#: How many tracked files the language census reads. A repository's languages
+#: are visible in the first couple of thousand files, and the census is a line
+#: of output rather than a decision anything turns on.
+MAX_CENSUS = 2000
+
+#: Suffix to the name a human calls it. Deliberately short: this names what
+#: AgentForge might have something to say about, and a census listing `.gitignore`
+#: as a language would be noise dressed as information.
+LANGUAGES = {
+    ".py": "Python",
+    ".sql": "SQL",
+    ".yml": "YAML",
+    ".yaml": "YAML",
+    ".ipynb": "Notebook",
+    ".scala": "Scala",
+    ".java": "Java",
+    ".ts": "TypeScript",
+    ".tsx": "TypeScript",
+    ".js": "JavaScript",
+    ".jsx": "JavaScript",
+    ".go": "Go",
+    ".rs": "Rust",
+    ".sh": "Shell",
+    ".md": "Markdown",
+}
+
+
+@dataclass(frozen=True)
+class ProjectContext:
+    """What AgentForge learned about one repository at `agentforge init`.
+
+    `suite_detected` and `plugins` are the two fields that exist because a human
+    reads this before a machine does. The first says whether the suite in the
+    file was found or assumed, which is the difference between a line to leave
+    alone and a line to correct. The second is printed and never written:
+    activation is decided per Run from the frozen Plan's blast radius, and a
+    `plugins:` key would be a key nothing consults.
+    """
+
+    root: Path
+    provider: str
+    capability_tier: CapabilityTier
+    test_suite: tuple[str, ...] = DEFAULT_TEST_SUITE
+    suite_detected: str = ""
+    languages: tuple[str, ...] = ()
+    plugins: tuple[str, ...] = ()
+
+
+def detect(
+    root: Path | str,
+    provider: str,
+    tracked: tuple[str, ...] = (),
+    plugins: tuple[str, ...] = (),
+) -> ProjectContext:
+    """Everything init has to say about this repository.
+
+    `tracked` is the repository's files as git reports them, and `plugins` the
+    names `core.registry` activated for it. Both are passed in rather than read
+    here: this module opens no process and imports no registry, so detection is
+    a pure function of what it was handed and a test needs no repository.
+    """
+    suite, because = _suite(Path(root), tracked)
+    return ProjectContext(
+        root=Path(root),
+        provider=provider,
+        capability_tier=DEFAULT_CAPABILITIES.get(provider, CapabilityTier.FRAGMENT),
+        test_suite=suite,
+        suite_detected=because,
+        languages=_languages(tracked),
+        plugins=tuple(plugins),
+    )
+
+
+def config_path(root: Path | str) -> Path:
+    return Path(root) / CONFIG_DIR / CONFIG_FILE
+
+
+def render_config(context: ProjectContext) -> str:
+    """The file, with a comment on every line a human might want to change.
+
+    Written by hand rather than dumped, because the comments are the point. A
+    reader who cannot tell a detected value from a default has to re-derive both
+    before touching either, and the first thing anybody does to a generated
+    config is edit it.
+    """
+    suite = ", ".join(_quoted(part) for part in context.test_suite)
+    because = (
+        f"detected: {context.suite_detected}"
+        if context.suite_detected
+        else "not detected — this is the documented default, so correct it if it is wrong"
+    )
+
+    return f"""\
+# AgentForge project configuration, written by `agentforge init`.
+#
+# This file holds what AgentForge reads and nothing else. Which Plugins answer
+# for this repository is decided per Run from the frozen Plan's blast radius
+# (ADR-0016), so there is no `plugins:` key here to edit.
+
+providers:
+  # What this Provider's CLI can be relied on to support, declared rather than
+  # probed (ADR-0005). `native` delivers a Role's skills as the CLI's own
+  # commands; `fragment` inlines them into the prompt instead.
+  {context.provider}:
+    capability_tier: {context.capability_tier}
+
+gates:
+  tests:
+    # The argument vector the `tests` Gate runs, in this repository.
+    # {because}
+    suite: [{suite}]
+"""
+
+
+def differences(context: ProjectContext, existing: str) -> tuple[str, ...]:
+    """How the config on disk differs from the one init would write.
+
+    Compared as the values `load_config` would read rather than as text, so a
+    file somebody reformatted, commented, or reordered is not reported as a
+    difference. The point of the comparison is to tell a human whether their
+    edits are still there, and a diff that fired on whitespace would not.
+    """
+    try:
+        data = pyyaml.safe_load(existing) or {}
+    except pyyaml.YAMLError as exc:
+        return (f"the file on disk is not valid YAML: {exc}",)
+
+    if not isinstance(data, dict):
+        return ("the file on disk is not a mapping",)
+
+    found: list[str] = []
+
+    providers = data.get("providers") or {}
+    tier = (providers.get(context.provider) or {}).get("capability_tier")
+    if tier is None:
+        found.append(f"it names no capability tier for {context.provider!r}")
+    elif str(tier) != str(context.capability_tier):
+        found.append(
+            f"{context.provider} capability tier: {tier} on disk, "
+            f"{context.capability_tier} from detection"
+        )
+
+    suite = ((data.get("gates") or {}).get("tests") or {}).get("suite")
+    if suite is not None:
+        rendered = " ".join(suite) if isinstance(suite, list) else str(suite)
+        if rendered.split() != list(context.test_suite):
+            found.append(
+                f"test suite: `{rendered}` on disk, "
+                f"`{' '.join(context.test_suite)}` from detection"
+            )
+
+    return tuple(found)
+
+
+def _suite(root: Path, tracked: tuple[str, ...]) -> tuple[tuple[str, ...], str]:
+    """The suite this repository appears to run, and the evidence for it.
+
+    Ordered by how specific the evidence is rather than by popularity: a
+    repository declaring a pytest section is telling us directly, and one with a
+    `tests/` directory is telling us by convention. A repository that shows
+    nothing gets the documented default and is told it was a default — guessing
+    silently is how a Gate ends up running the wrong command for a month.
+    """
+    files = set(tracked)
+
+    text = _read(root / "pyproject.toml")
+    if "[tool.pytest" in text:
+        return ("pytest",), "a `[tool.pytest]` section in pyproject.toml"
+
+    if "pytest.ini" in files or "conftest.py" in files:
+        return ("pytest",), "pytest configuration at the repository root"
+
+    if any(path.startswith("tests/") for path in files):
+        return ("pytest",), "a `tests/` directory"
+
+    package = _read(root / "package.json")
+    if '"test"' in package:
+        return ("npm", "test"), "a `test` script in package.json"
+
+    if "go.mod" in files:
+        return ("go", "test", "./..."), "a go.mod at the repository root"
+
+    if "Cargo.toml" in files:
+        return ("cargo", "test"), "a Cargo.toml at the repository root"
+
+    return DEFAULT_TEST_SUITE, ""
+
+
+def _languages(tracked: tuple[str, ...]) -> tuple[str, ...]:
+    """The languages this repository is written in, commonest first.
+
+    A census rather than a claim: it counts the suffixes git already knows
+    about, so a `.venv` nobody committed does not make this a repository full of
+    somebody else's Python.
+    """
+    counts: dict[str, int] = {}
+    for path in tracked[:MAX_CENSUS]:
+        language = LANGUAGES.get(Path(path).suffix.lower())
+        if language:
+            counts[language] = counts.get(language, 0) + 1
+
+    # Sorted by count and then by name, so two languages with the same number of
+    # files do not swap places between two runs against one repository.
+    return tuple(name for name, _ in sorted(counts.items(), key=lambda item: (-item[1], item[0])))
+
+
+def _read(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+
+
+def _quoted(part: str) -> str:
+    """A suite argument as YAML. Quoted, because `-q` unquoted is not a string."""
+    return '"' + part.replace('"', '\\"') + '"'
+
+
+__all__ = [
+    "CONFIG_DIR",
+    "CONFIG_FILE",
+    "LANGUAGES",
+    "MAX_CENSUS",
+    "ProjectContext",
+    "config_path",
+    "detect",
+    "differences",
+    "render_config",
+]