agentforge-framework 0.2.0__py3-none-any.whl

agentforge_framework/providers/base.py

@@ -0,0 +1,248 @@
+"""The Provider port: one Role, one invocation, one result.
+
+ADR-0001 makes every Agent a subprocess call to a coding-agent CLI. `Provider`
+is the whole of that contract — no streaming, no session, no conversation state.
+A Role, a prompt, a Context Pack, a Model Tier, and a working directory go in;
+an `AgentResult` comes out.
+
+Two things are deliberately split here:
+
+- The **envelope** — how a CLI reports its own success, and where in its output
+  the model's text is — belongs to the adapter. A version bump breaks one
+  adapter rather than the framework.
+- The **result block** — the delimited JSON a Role is instructed to end with —
+  belongs to AgentForge. It travels in the prompt, so every adapter gets it for
+  free and none of them has to invent an escalation convention.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import ClassVar
+
+from ..core.config import CapabilityTier, Config
+from ..core.contracts import (
+    AgentResult,
+    ContextPack,
+    Finding,
+    ModelTier,
+    Outcome,
+    Role,
+    Usage,
+)
+from ..core.plan_format import extract_result_block
+from ..core.process import CommandResult, CommandRunner, MissingBinary, require
+from ..core.skills import expand, read_skill
+
+
+class ProviderError(RuntimeError):
+    """A Provider could not be used at all, as distinct from an Agent failing."""
+
+
+class Provider(ABC):
+    """The port. One method, and it is the only thing a Role knows about."""
+
+    name: ClassVar[str] = "provider"
+    binary: ClassVar[str] = ""
+
+    #: Whether an Agent may run commands, not merely edit files. Default-deny
+    #: per ADR-0007: opened for one Run by an explicit flag, and expressed in
+    #: the argument vector rather than in prompt text, because a permission
+    #: written as an instruction is one the model can talk itself out of.
+    allow_commands: bool = False
+
+    @abstractmethod
+    def invoke(
+        self,
+        *,
+        role: Role,
+        prompt: str,
+        context: ContextPack,
+        tier: ModelTier,
+        cwd: Path,
+    ) -> AgentResult: ...
+
+    def preflight(self) -> None:
+        """Confirm the CLI exists, naming it if not. Called before a Run starts."""
+
+
+@dataclass(frozen=True)
+class ProviderOutput:
+    """What an adapter recovered from its CLI's envelope.
+
+    `usage` is what the CLI said the invocation consumed, and it is recovered
+    here rather than centrally because the envelope is the adapter's business:
+    ADR-0009 keeps a third Provider from adding a third place that knows how the
+    second one reports itself. `None` means the CLI reported nothing, which is
+    not the same as a free invocation.
+    """
+
+    text: str
+    error: str | None = None
+    usage: Usage | None = None
+
+
+class CliProvider(Provider):
+    """Shared plumbing for adapters that shell out to a coding-agent CLI.
+
+    Subclasses supply three small things: the tier-to-model mapping, the
+    argument vector, and how to get the model's text out of the CLI's envelope.
+    Everything else — turning that text into an `AgentResult` — is the shared
+    result-block contract.
+
+    Extending this is a convenience, not a requirement. An adapter that
+    implements `invoke` directly is equally valid, and writing one that way is
+    the honest test of whether the port is portable or merely Claude-shaped.
+    """
+
+    #: Tier to model identifier. Nothing outside an adapter knows these strings.
+    models: ClassVar[dict[ModelTier, str]] = {}
+
+    def __init__(
+        self,
+        runner: CommandRunner,
+        timeout: float | None = 1800.0,
+        allow_commands: bool = False,
+        config: Config | None = None,
+    ) -> None:
+        self.runner = runner
+        self.timeout = timeout
+        self.allow_commands = allow_commands
+        self.capability_tier = (config or Config()).capability_for(self.name)
+
+    def preflight(self) -> None:
+        try:
+            require(
+                self.runner,
+                self.binary,
+                f"AgentForge drives the {self.name} CLI (ADR-0001); install it or "
+                f"select another provider with --provider.",
+            )
+        except MissingBinary as exc:
+            raise ProviderError(str(exc)) from exc
+
+    def model_for(self, tier: ModelTier) -> str:
+        try:
+            return self.models[tier]
+        except KeyError as exc:
+            raise ProviderError(
+                f"the {self.name} adapter has no model for tier {tier!r}"
+            ) from exc
+
+    @abstractmethod
+    def build_argv(
+        self, prompt: str, model: str, native_skills: tuple[str, ...] = ()
+    ) -> Sequence[str]: ...
+
+    @abstractmethod
+    def parse_output(self, result: CommandResult) -> ProviderOutput: ...
+
+    def invoke(
+        self,
+        *,
+        role: Role,
+        prompt: str,
+        context: ContextPack,
+        tier: ModelTier,
+        cwd: Path,
+    ) -> AgentResult:
+        prompt, native_skills = self._deliver_skills(role, prompt)
+        argv = self.build_argv(prompt, self.model_for(tier), native_skills)
+        completed = self.runner.run(argv, cwd=cwd, timeout=self.timeout)
+        output = self.parse_output(completed)
+        return to_agent_result(role=role, tier=tier, output=output)
+
+    def _deliver_skills(self, role: Role, prompt: str) -> tuple[str, tuple[str, ...]]:
+        """Validate and deliver the Role's skills before the CLI is invoked.
+
+        A native Provider is named the skills the Role declared and no more: a
+        composite fans out to its parts through the CLI's own Skill mechanism,
+        which is what the mechanism is for.
+
+        A Fragment Provider has no such mechanism, so the composite is expanded
+        here and every body travels. Without that, a skill whose text says "run
+        these two" reaches a Provider that cannot run anything and the Role is
+        left with an instruction pointing at nothing.
+        """
+        if not role.skills:
+            return prompt, ()
+
+        if self.capability_tier is CapabilityTier.NATIVE:
+            for name in role.skills:
+                read_skill(name)  # refuse a name nothing answers for, before the CLI runs
+            commands = ", ".join(f"/agentforge:{name}" for name in role.skills)
+            instruction = (
+                f"Use the declared native AgentForge skills before doing this work: {commands}."
+            )
+            return f"{instruction}\n\n{prompt}", role.skills
+
+        fragments = [
+            f"## Skill: {name}\n\n{read_skill(name).rstrip()}" for name in expand(role.skills)
+        ]
+        return f"{prompt}\n\n" + "\n\n".join(fragments) + "\n", ()
+
+
+def to_agent_result(*, role: Role, tier: ModelTier, output: ProviderOutput) -> AgentResult:
+    """Turn a Role's text output into a result the runtime can act on.
+
+    A Role that reports nothing parseable is a failure, not a quiet success. The
+    alternative — treating unstructured text as a completed step — is how a Run
+    opens a pull request containing no changes and says it worked.
+
+    Every way out of here carries the usage the adapter recovered, failures
+    included. A Run that spent four dollars discovering its CLI was misconfigured
+    spent four dollars, and a total that quietly omitted them would be the one
+    figure a reader most wants.
+    """
+    if output.error:
+        return AgentResult(
+            role=role.name,
+            tier=tier,
+            outcome=Outcome.FAILED,
+            summary=output.error,
+            detail=output.text,
+            raw=output.text,
+            usage=output.usage,
+        )
+
+    payload = extract_result_block(output.text)
+    if payload is None:
+        return AgentResult(
+            role=role.name,
+            tier=tier,
+            outcome=Outcome.FAILED,
+            summary=(
+                f"the {role.name} Agent finished without reporting a result block, "
+                "so AgentForge cannot tell what it did"
+            ),
+            detail=output.text,
+            raw=output.text,
+            usage=output.usage,
+        )
+
+    try:
+        outcome = Outcome(str(payload.get("outcome", "")).strip().lower())
+    except ValueError:
+        outcome = Outcome.FAILED
+
+    summary = str(payload.get("summary") or "").strip()
+    if outcome is Outcome.FAILED and not summary:
+        summary = f"the {role.name} Agent reported an unrecognized outcome"
+
+    return AgentResult(
+        role=role.name,
+        tier=tier,
+        outcome=outcome,
+        summary=summary,
+        detail=str(payload.get("detail") or ""),
+        files_changed=tuple(payload.get("files_changed") or ()),
+        findings=tuple(Finding.coerce(item) for item in payload.get("findings") or ()),
+        raw=output.text,
+        usage=output.usage,
+    )
+
+
+__all__ = ["CliProvider", "Provider", "ProviderError", "ProviderOutput", "to_agent_result"]

agentforge_framework/providers/claude.py

@@ -0,0 +1,159 @@
+"""The Claude Code adapter.
+
+`claude -p` runs headlessly: it takes a prompt, edits files in the working
+directory, and exits. `--output-format json` wraps the run in an envelope
+carrying an `is_error` flag and the model's final text under `result`, which is
+the only reason this adapter can tell a CLI failure from an Agent failure.
+
+Model identifiers appear here and nowhere else in AgentForge (ADR-0004). The
+aliases are used rather than pinned versions so that a vendor release does not
+require an AgentForge release; a team that wants a specific version overrides
+the mapping in configuration once `agentforge init` exists (M5).
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from typing import ClassVar
+
+from ..core.contracts import ModelTier, Usage
+from ..core.process import CommandResult
+from ..core.skills import SKILLS_ROOT
+from .base import CliProvider, ProviderOutput
+
+
+class ClaudeProvider(CliProvider):
+    name: ClassVar[str] = "claude"
+    binary: ClassVar[str] = "claude"
+
+    models: ClassVar[dict[ModelTier, str]] = {
+        ModelTier.DEEP: "opus",
+        ModelTier.STANDARD: "sonnet",
+        ModelTier.CHEAP: "haiku",
+    }
+
+    #: ADR-0007's two postures, mapped onto this CLI's permission modes.
+    #: `acceptEdits` lets an Agent write files and nothing else; commands still
+    #: need a confirmation that headless mode cannot give, which is the whole
+    #: bug in #18. `bypassPermissions` is the open gate. An Agent that has to
+    #: ask before every edit cannot run unattended at all, so there is no
+    #: third, stricter posture — the blast radius is bounded by the branch the
+    #: runtime creates before any Agent is invoked.
+    DENIED: ClassVar[str] = "acceptEdits"
+    PERMITTED: ClassVar[str] = "bypassPermissions"
+
+    @property
+    def permission_mode(self) -> str:
+        return self.PERMITTED if self.allow_commands else self.DENIED
+
+    def build_argv(
+        self, prompt: str, model: str, native_skills: tuple[str, ...] = ()
+    ) -> Sequence[str]:
+        argv = (
+            self.binary,
+            "-p",
+            prompt,
+            "--model",
+            model,
+            "--output-format",
+            "json",
+            "--permission-mode",
+            self.permission_mode,
+        )
+        if native_skills:
+            argv += ("--plugin-dir", str(SKILLS_ROOT.parent))
+        return argv
+
+    def parse_output(self, result: CommandResult) -> ProviderOutput:
+        """Unwrap the JSON envelope.
+
+        Failure modes, in the order they actually happen: the CLI is missing or
+        crashed before printing anything; it printed something that is not JSON;
+        it printed a well-formed envelope reporting its own error.
+        """
+        stdout = result.stdout.strip()
+        if not stdout:
+            detail = result.stderr.strip() or f"exit status {result.returncode}"
+            return ProviderOutput(text="", error=f"the claude CLI produced no output: {detail}")
+
+        try:
+            envelope = json.loads(stdout)
+        except json.JSONDecodeError:
+            # Older CLIs and `--output-format text` print bare text. The result
+            # block still travels in it, so this degrades rather than fails.
+            if result.ok:
+                return ProviderOutput(text=stdout)
+            return ProviderOutput(
+                text=stdout,
+                error=f"the claude CLI exited {result.returncode} without a JSON envelope",
+            )
+
+        record = _final_record(envelope)
+        text = str(record.get("result") or record.get("text") or "")
+        usage = _usage(record)
+
+        if record.get("is_error") or not result.ok:
+            reason = text.strip() or result.stderr.strip() or f"exit status {result.returncode}"
+            return ProviderOutput(
+                text=text,
+                error=f"the claude CLI reported an error: {reason}",
+                usage=usage,
+            )
+
+        return ProviderOutput(text=text, usage=usage)
+
+
+#: What the envelope calls the tokens that went in. Cached ones are counted
+#: with the rest: they are cheaper, not free, and the price the CLI charged for
+#: them is already inside `total_cost_usd` — a token figure that omitted them
+#: would disagree with the dollar figure beside it.
+_INPUT_FIELDS = ("input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens")
+
+
+def _usage(record: dict) -> Usage | None:
+    """What this envelope says the invocation consumed.
+
+    This CLI is the generous one: dollars and a token split, both in the record
+    AgentForge was already parsing for the result text. `None` when the envelope
+    carries neither, so that a Run Log line can say the CLI reported nothing
+    rather than printing a zero nobody measured.
+    """
+    counts = record.get("usage")
+    counts = counts if isinstance(counts, dict) else {}
+
+    inputs = [_number(counts.get(field), int) for field in _INPUT_FIELDS]
+    counted = [value for value in inputs if value is not None]
+
+    usage = Usage(
+        provider=ClaudeProvider.name,
+        input_tokens=sum(counted) if counted else None,
+        output_tokens=_number(counts.get("output_tokens"), int),
+        cost_usd=_number(record.get("total_cost_usd"), float),
+    )
+    return usage if usage.reported else None
+
+
+def _number(value: object, cast):
+    """One figure out of the envelope, or `None` where it had none to give."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return cast(value)
+
+
+
+def _final_record(envelope: object) -> dict:
+    """The terminal record, whether the CLI emitted one object or a stream."""
+    if isinstance(envelope, dict):
+        return envelope
+    if isinstance(envelope, list):
+        for item in reversed(envelope):
+            if isinstance(item, dict) and item.get("type") == "result":
+                return item
+        for item in reversed(envelope):
+            if isinstance(item, dict):
+                return item
+    return {}
+
+
+__all__ = ["ClaudeProvider"]

agentforge_framework/providers/codex.py

@@ -0,0 +1,139 @@
+"""A second adapter, to keep ADR-0001's portability claim honest.
+
+This exists to prove the Provider port is not merely Claude-shaped. `codex exec`
+differs from `claude -p` in the two places that matter: it prints a transcript
+rather than a JSON envelope, so success has to be read from the exit status, and
+its model identifiers are its own.
+
+The posture flags and model slugs below are read off a real install — `codex
+--help` and `~/.codex/models_cache.json` — rather than guessed. The previous
+`gpt-5-codex*` identifiers existed on no account we could find, which is
+ADR-0004's whole point: tier names outlive model names, and a pinned
+identifier goes stale inside a release.
+
+This CLI carries reasoning effort separately from model choice, and the
+per-model defaults disagree: `gpt-5.6-sol` starts at `low` while the rest
+start at `medium`. Left alone, `deep` would buy the frontier model and ask it
+to think as little as possible. The adapter pins one value across all three
+tiers instead, so the Model Tier chooses the model and nothing else shifts
+underneath it.
+
+Per the note on Issue #1: the useful version of this file is one written by
+somebody who has not read `claude.py`. This one was not, so treat its shape as a
+weaker signal than a genuinely independent adapter would be.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from typing import ClassVar
+
+from ..core.contracts import ModelTier, Usage
+from ..core.process import CommandResult
+from .base import CliProvider, ProviderOutput
+
+
+class CodexProvider(CliProvider):
+    name: ClassVar[str] = "codex"
+    binary: ClassVar[str] = "codex"
+
+    #: Slugs read out of a real install's `~/.codex/models_cache.json` rather
+    #: than guessed. The tiers step back a generation at a time: the current
+    #: frontier model for `deep`, then the two preceding releases. The
+    #: same-generation alternatives (`gpt-5.6-terra`, `gpt-5.6-luna`) are the
+    #: obvious other reading of ADR-0004's three tiers; this mapping is the
+    #: maintainer's choice, and overriding it is a configuration line.
+    models: ClassVar[dict[ModelTier, str]] = {
+        ModelTier.DEEP: "gpt-5.6-sol",
+        ModelTier.STANDARD: "gpt-5.5",
+        ModelTier.CHEAP: "gpt-5.4",
+    }
+
+    #: ADR-0007's two postures, on the two axes `codex --help` documents.
+    #:
+    #: The sandbox never changes: an Agent writes in the workspace and nowhere
+    #: else, in both postures. What the gate moves is the approval policy.
+    #: `untrusted` auto-runs only reads (`ls`, `cat`, `sed`) and escalates
+    #: anything else, which is this CLI's nearest analogue to the `claude`
+    #: adapter's `acceptEdits`. `never` stops asking.
+    #:
+    #: `danger-full-access` and `--dangerously-bypass-approvals-and-sandbox`
+    #: are deliberately unused. ADR-0007 opens a gate; it does not remove the
+    #: sandbox, and an unattended Role is the last thing that should be outside
+    #: one.
+    SANDBOX: ClassVar[str] = "workspace-write"
+    DENIED: ClassVar[str] = "untrusted"
+    PERMITTED: ClassVar[str] = "never"
+
+    #: Pinned across every tier, because the per-model defaults disagree —
+    #: `gpt-5.6-sol` starts at `low`, the others at `medium`. Setting it here
+    #: keeps a Model Tier meaning one thing: it picks the model, and the
+    #: reasoning depth stays where the maintainer put it. `low` through `ultra`
+    #: are available; raising it is a configuration change under ADR-0004
+    #: rather than an edit here.
+    REASONING_EFFORT: ClassVar[str] = "medium"
+
+    def build_argv(
+        self, prompt: str, model: str, native_skills: tuple[str, ...] = ()
+    ) -> Sequence[str]:
+        """Options precede the subcommand: `codex [OPTIONS] <COMMAND> [ARGS]`.
+
+        This adapter previously passed `--full-auto` after `exec`, which fails
+        twice over: that flag does not exist in the current CLI, and options
+        placed after the subcommand are rejected regardless.
+
+        Reasoning effort is pinned rather than derived from the tier, which is
+        what lets it be set here at all: a per-tier value would need the Model
+        Tier, and the port hands that to `model_for` and not to this method.
+        """
+        return (
+            self.binary,
+            "--model",
+            model,
+            "-c",
+            f"model_reasoning_effort={self.REASONING_EFFORT}",
+            "--sandbox",
+            self.SANDBOX,
+            "--ask-for-approval",
+            self.PERMITTED if self.allow_commands else self.DENIED,
+            "exec",
+            prompt,
+        )
+
+    def parse_output(self, result: CommandResult) -> ProviderOutput:
+        """No envelope. The transcript is the output and the exit code is the verdict."""
+        usage = _usage(result.stdout)
+
+        if result.ok:
+            return ProviderOutput(text=result.stdout, usage=usage)
+
+        detail = (result.stderr or result.stdout or "").strip()
+        return ProviderOutput(
+            text=result.stdout,
+            error=f"the codex CLI exited {result.returncode}: {detail[:400]}",
+            usage=usage,
+        )
+
+
+#: The last line of a transcript, on a run that got that far. One figure and no
+#: split, which is the asymmetry ADR-0009 exists to keep honest: this adapter
+#: reports tokens and never dollars, and the Run Log says so rather than leaving
+#: a blank where a price would have been.
+_TOKENS = re.compile(r"tokens used:\s*([\d,]+)", re.IGNORECASE)
+
+
+def _usage(transcript: str) -> Usage | None:
+    """The token count this CLI prints when it finishes, if it printed one.
+
+    The last match rather than the first: a transcript that reports per-turn
+    counts ends with the one for the whole invocation, and an Agent that quoted
+    the phrase in its own output would otherwise be believed over the CLI.
+    """
+    matches = _TOKENS.findall(transcript or "")
+    if not matches:
+        return None
+    return Usage(provider=CodexProvider.name, total_tokens=int(matches[-1].replace(",", "")))
+
+
+__all__ = ["CodexProvider"]