agentic-dev-loop 0.2.0__py3-none-any.whl

agentic_dev_loop/graph.py

@@ -0,0 +1,275 @@
+"""Config-driven LangGraph builder + the run_pipeline public API.
+
+The pipeline is a cyclic state graph: one node per configured step, routers
+steer the retry cycle, and a SQLite checkpointer makes runs crash-resumable
+(--resume <thread-id> re-enters at the first stage that didn't complete).
+"""
+
+from __future__ import annotations
+
+import operator
+import uuid
+import webbrowser
+from pathlib import Path
+from typing import Annotated, TypedDict
+
+from langgraph.checkpoint.sqlite import SqliteSaver
+from langgraph.graph import END, START, StateGraph
+
+from . import viz
+from .actions import git_worktree_clean, kill_listeners_on_port
+from .config import load_config
+from .llm import build_llm
+from .loaders import select_loader
+from .registry import Registry, default_registry, load_extensions
+from .stages import (Runtime, build_context, clear_attempt_artifacts,
+                     make_action_node, make_agent_node, make_bump_node,
+                     make_command_node, make_router, success_node)
+
+CHECKPOINT_DB = "loop-checkpoints.sqlite"  # under state_dir, one DB per workspace
+
+
+class LoopState(TypedDict):
+    """State threaded through the graph. `notes` accumulates across attempts
+    (append reducer); every other key is last-write-wins."""
+    subject: str
+    docs: dict[str, str]
+    context: str                       # built at attempt start, shared by all stages
+    attempt: int
+    max_attempts: int
+    notes: Annotated[list[str], operator.add]
+    failed: bool                       # hard stage failure — ends the run
+    failed_step: str | None            # the step that hard-failed (resume target)
+    resume_target: str | None          # where a resumed run re-enters (START edge)
+    outcome: str | None                # "success" once routed to the success terminal
+    commit_allowed: bool               # worktree was clean at run start
+    step_verdicts: dict[str, str | None]  # per-step pass/fail/None(unclear)
+    retry_target: str | None           # where the bump node loops back to
+    thread_id: str
+
+
+def build_graph(runtime: Runtime, checkpointer=None):
+    """Compile the pipeline's state graph: one node per step (agent, command,
+    or action), plus the bump retry node and the success terminal. Unknown
+    action names fail here, at build time, not mid-run."""
+    for step in runtime.cfg.steps:
+        if step.action is not None and step.action not in runtime.registry.actions:
+            raise ValueError(
+                f"step {step.name!r}: unknown action {step.action!r} "
+                f"(registered: {sorted(runtime.registry.actions)})")
+    graph = StateGraph(LoopState)
+    for step in runtime.cfg.steps:
+        if step.kind == "agent":
+            node = make_agent_node(runtime, step)
+        elif step.kind == "command":
+            node = make_command_node(runtime, step)
+        else:
+            node = make_action_node(runtime, step)
+        graph.add_node(step.name, node)
+        graph.add_conditional_edges(step.name, make_router(runtime, step))
+    graph.add_node("bump", make_bump_node(runtime))
+    graph.add_conditional_edges("bump", lambda state: state["retry_target"])
+    graph.add_node("success", success_node)
+    graph.add_conditional_edges(
+        START,
+        lambda state: state.get("resume_target") or runtime.cfg.steps[0].name)
+    graph.add_edge("success", END)
+    return graph.compile(checkpointer=checkpointer)
+
+
+def _resolve_docs(cfg, base: Path, registry: Registry,
+                  args) -> tuple[dict[str, str], str]:
+    """Select and invoke the document loader, then append the pipeline's
+    additional_files (resolved relative to the pipeline file's dir;
+    listed-but-missing fails fast)."""
+    loader = select_loader(registry, args)
+    if loader is not None:
+        docs, subject = loader.resolve(args)
+        if not docs:
+            # U3 policy: an empty load silently degraded to a context the
+            # agents couldn't act on. Fail fast at the call site instead.
+            raise RuntimeError(
+                f"Document loader {loader.name!r} returned no docs — "
+                "refusing to build context from nothing")
+    else:
+        docs, subject = {}, cfg.name
+    for rel in cfg.additional_files:
+        path = base / rel
+        if not path.is_file():
+            raise FileNotFoundError(f"additional_files entry not found: {path}")
+        docs[path.name] = path.read_text()
+    return docs, subject
+
+
+def run_pipeline(cfg_path, args, *, viz_bus=None) -> tuple[bool, int]:
+    """Load a pipeline YAML, resolve docs via the selected document loader,
+    and run the graph to completion. Returns (success, attempts) — the
+    public API, yosk's `construct`/`resume_loop` equivalent.
+
+    `args` carries the parsed CLI namespace: loader flags, --resume,
+    --max-attempts (which overrides the YAML value when set), and --no-viz.
+
+    The live viz is on by default for CLI runs (suppressed with ``--no-viz``).
+    With ``viz_bus=None`` and viz suppressed, the graph runs via
+    ``graph.invoke`` exactly as before. A passed-in ``viz_bus`` (programmatic)
+    or a default-on CLI run switches to ``graph.stream`` and publishes live
+    events; the CLI path additionally serves the HTTP page and opens the
+    browser, and the process exits as soon as the loop completes.
+    Programmatic Namespaces without a ``no_viz`` attribute get no server —
+    default-on is a CLI-layer concern."""
+    cfg_path = Path(cfg_path)
+    cfg = load_config(cfg_path)
+    base = cfg_path.resolve().parent
+    max_attempts = getattr(args, "max_attempts", None) or cfg.max_attempts
+
+    registry = default_registry()
+    load_extensions(cfg.extensions, registry)
+
+    state_dir = base / cfg.state_dir
+    runtime = Runtime(cfg=cfg, registry=registry, llm=build_llm(cfg.llm),
+                      agents_dir=base / cfg.agents_dir, state_dir=state_dir,
+                      workspace=Path.cwd())
+    state_dir.mkdir(parents=True, exist_ok=True)
+
+    resume = getattr(args, "resume", None)
+    thread_id = resume or uuid.uuid4().hex
+    config = {"configurable": {"thread_id": thread_id}}
+    db = str(state_dir / CHECKPOINT_DB)
+    if resume:
+        initial = None  # state (docs/subject/context) comes from the checkpoint
+    else:
+        docs, subject = _resolve_docs(cfg, base, registry, args)
+        # A fresh run owns state_dir: drop cross-run leftovers (a previous
+        # failure's last-error.md, stale artifacts) so nothing mistakes
+        # them for this run's output. --resume keeps them.
+        clear_attempt_artifacts(runtime)
+        initial: LoopState = {
+            "subject": subject,
+            "docs": docs,
+            "context": build_context(runtime, docs, subject, []),
+            "attempt": 1,
+            "max_attempts": max_attempts,
+            "notes": [],
+            "failed": False,
+            "failed_step": None,
+            "resume_target": None,
+            "outcome": None,
+            # Only a clean-at-start worktree gets an auto-commit — otherwise
+            # the commit could swallow pre-existing changes. Computed BEFORE
+            # the checkpointer creates its db under state_dir, which would
+            # itself dirty the worktree.
+            "commit_allowed": git_worktree_clean(Path.cwd()),
+            "step_verdicts": {},
+            "retry_target": None,
+            "thread_id": thread_id,
+        }
+    bus = viz_bus
+    with SqliteSaver.from_conn_string(db) as saver:
+        if resume and saver.get_tuple(config) is None:
+            raise ValueError(
+                f"No checkpoint found for thread {thread_id!r} in {db} — "
+                f"nothing to resume.")
+        graph = build_graph(runtime, saver)
+
+        if resume and getattr(args, "max_attempts", None):
+            # A resumed run takes its state from the checkpoint, so the CLI
+            # override computed above would never reach it. Re-apply it to the
+            # checkpoint state before the run re-enters.
+            graph.update_state(config, {"max_attempts": max_attempts})
+
+        if resume and initial is None:
+            values = graph.get_state(config).values
+            if values.get("failed"):
+                # A hard-failed run's checkpoint has no pending work — a
+                # plain resume would return it untouched and exit silently.
+                # Re-enter at the step that failed so the run can complete.
+                failed_step = values.get("failed_step")
+                target = (failed_step or values.get("retry_target")
+                          or cfg.steps[0].name)
+                print(
+                    f"[{values.get('subject', '?')}] Resuming hard-failed run "
+                    f"(thread {thread_id}) — re-entering at step {target!r}. "
+                    f"Failure details: {state_dir}/last-error.md",
+                    flush=True)
+                initial = {**values, "failed": False,
+                           "resume_target": target, "failed_step": None}
+
+        if bus is None and not getattr(args, "no_viz", True):
+            start_state = initial if initial is not None \
+                else graph.get_state(config).values
+            topology, nodes = viz.topology_mermaid(cfg)
+            bus = viz.VizBus()
+            if args.viz_port:
+                kill_listeners_on_port(args.viz_port, match="agentic-dev-loop",
+                                       cwd=runtime.workspace)
+            httpd, _thread = viz.serve_viz(
+                bus, topology, start_state["subject"], args.viz_port, nodes)
+            bound = httpd.server_address[1]
+            url = f"http://127.0.0.1:{bound}"
+            if args.viz_port and bound != args.viz_port:
+                print(f"viz port {args.viz_port} busy — serving on {url}",
+                      flush=True)
+            print(f"Live graph viz: {url}", flush=True)
+            webbrowser.open(url)
+
+        if bus is not None:
+            start_state = initial if initial is not None \
+                else graph.get_state(config).values
+            bus.publish({
+                "type": "run_started",
+                "subject": start_state["subject"],
+                "max_attempts": start_state["max_attempts"],
+                "thread_id": thread_id,
+                "attempt": start_state["attempt"],
+            })
+            watch = viz.NodeWatch()
+            capture = viz.ConsoleCapture(bus, watch)
+            capture.attach()
+            heartbeat = viz.HeartbeatThread(watch, bus)
+            heartbeat.start()
+            final = None
+            try:
+                for part in graph.stream(initial, config,
+                                         stream_mode=["tasks", "updates"],
+                                         version="v2"):
+                    for event in viz.translate(part):
+                        if event["type"] == "node_started":
+                            watch.start(event["node"])
+                        elif event["type"] == "node_finished":
+                            watch.finish(event["node"])
+                        bus.publish(event)
+                final = graph.get_state(config).values
+            finally:
+                heartbeat.stop()
+                heartbeat.join()
+                if final is None:
+                    try:
+                        final = graph.get_state(config).values
+                    except Exception:
+                        final = None
+                if final is not None:
+                    success = final.get("outcome") == "success"
+                    attempts = final.get("attempt", 0)
+                else:
+                    success = False
+                    attempts = 0
+                bus.publish({"type": "run_finished",
+                             "success": success, "attempts": attempts})
+                capture.detach()
+        else:
+            final = graph.invoke(initial, config)
+            success = final["outcome"] == "success"
+            attempts = final["attempt"]
+
+    if not success and final is not None:
+        if final.get("failed"):
+            print(
+                f"[{final['subject']}] FAILED after {final['attempt']} "
+                f"attempt(s) — hard failure at step "
+                f"{final.get('failed_step', 'unknown')!r}; see "
+                f"{state_dir}/last-error.md",
+                flush=True)
+        else:
+            print(f"[{final['subject']}] FAILED after {final['attempt']} "
+                  f"attempt(s).", flush=True)
+    return success, attempts

agentic_dev_loop/llm.py

@@ -0,0 +1,60 @@
+"""LLM construction from pipeline config. Fail fast on a missing key —
+never fall back to another env var (no silent fallbacks)."""
+
+import os
+
+from openhands.sdk import LLM
+from openhands.sdk.llm.utils import model_features as _model_features
+
+from .config import LlmConfig
+
+# Compat shim: OpenHands SDK 1.17 gates reasoning_content passback on a closed
+# model-name list (SEND_REASONING_CONTENT_MODELS) that does not know
+# deepseek-v4-pro. DeepSeek's thinking mode 400s on any multi-turn request
+# whose history omits prior reasoning_content. Unlike force_string_serializer,
+# the SDK exposes no instance-level override, so register the model here.
+# Remove once the SDK lists the model or adds an override.
+_DEEPSEEK_MODEL = "deepseek-v4-pro"
+if _DEEPSEEK_MODEL not in _model_features.SEND_REASONING_CONTENT_MODELS:
+    _model_features.SEND_REASONING_CONTENT_MODELS.append(_DEEPSEEK_MODEL)
+
+# Compat shim 2: the SDK splits a multi-tool-call turn into one assistant
+# message per call (Agent.step) and carries reasoning_content only on the
+# first; Message.to_chat_dict also drops empty-string reasoning. DeepSeek's
+# thinking mode 400s any request whose history contains reasoning_content
+# but omits it from an assistant tool-call message ("The reasoning_content
+# in the thinking mode must be passed back to the API"). Repair the
+# serialized history: an assistant tool-call message without its own
+# reasoning borrows the turn's last reasoning (reset on user turns), and a
+# present-but-empty reasoning is still written (field presence matters).
+# Remove once the SDK distributes reasoning_content to every message.
+_ORIGINAL_FORMAT_MESSAGES = LLM.format_messages_for_llm
+if not getattr(_ORIGINAL_FORMAT_MESSAGES, "_agentic_dev_loop_reasoning_repair", False):
+    def _repair_reasoning_passback(self, messages: list) -> list[dict]:
+        out = _ORIGINAL_FORMAT_MESSAGES(self, messages)
+        last = None
+        for msg, d in zip(messages, out):
+            if msg.role == "user":
+                last = None
+            if msg.role == "assistant" and msg.tool_calls:
+                rc = getattr(msg, "reasoning_content", None)
+                if rc is not None:
+                    last = rc
+                if last is not None:
+                    d["reasoning_content"] = last
+        return out
+
+    _repair_reasoning_passback._agentic_dev_loop_reasoning_repair = True
+    LLM.format_messages_for_llm = _repair_reasoning_passback
+
+
+def build_llm(cfg: LlmConfig) -> LLM:
+    api_key = os.environ.get(cfg.api_key_env)
+    if not api_key:
+        raise RuntimeError(f"{cfg.api_key_env} environment variable is required")
+    return LLM(
+        model=cfg.model,
+        api_key=api_key,
+        base_url=cfg.base_url,
+        timeout=cfg.timeout,  # policy: no LLM timeout unless explicitly set
+    )

agentic_dev_loop/loaders.py

@@ -0,0 +1,60 @@
+"""Built-in `plan` document loader + the loader-selection flow."""
+
+import argparse
+from pathlib import Path
+
+from .registry import DocumentLoader, Registry
+
+
+def resolve_plan_docs(plan_path: Path | str) -> dict[str, str]:
+    """Load a single plan doc as the pipeline's full context — plan mode is
+    self-contained (no unit/inception docs; shared files like coding
+    standards come from the pipeline's `additional_files:`, appended by the
+    runner)."""
+    path = Path(plan_path)
+    if not path.is_file():
+        raise FileNotFoundError(f"Plan doc not found: {path}")
+    return {path.name: path.read_text()}
+
+
+class PlanDocumentLoader:
+    name = "plan"
+    defaultable = False  # needs a path — never autodetects
+
+    def add_cli_args(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument("--plan", type=Path, default=None,
+                            help="Path to a single plan doc")
+
+    def resolve(self, args: argparse.Namespace) -> tuple[dict[str, str], str]:
+        docs = resolve_plan_docs(args.plan)
+        return docs, f"plan {args.plan.name}"
+
+
+def select_loader(registry: Registry, args: argparse.Namespace) -> DocumentLoader | None:
+    """The document-loader coexistence model — load many, invoke one:
+
+    1. A loader flag present in argv (parsed value not None) selects its
+       loader; other loaders are bypassed. Flags from two different loaders
+       in one invocation → error naming both (genuine ambiguity).
+    2. No loader flag → the sole `defaultable` loader runs (e.g. aidlc
+       autodetects the current unit). Multiple defaultables → error.
+    3. None defaultable → None: run with no injected docs; the subject is
+       the pipeline's `name:`.
+
+    Convention: loader flags must default to None so "present" is decidable.
+    """
+    invoked = {loader_name for dest, loader_name in registry.cli_dests.items()
+               if getattr(args, dest, None) is not None}
+    if len(invoked) > 1:
+        raise ValueError(
+            f"Flags from multiple document loaders in one invocation: "
+            f"{sorted(invoked)}")
+    if invoked:
+        name = invoked.pop()
+        return next(l for l in registry.document_loaders if l.name == name)
+    defaultable = [l for l in registry.document_loaders if l.defaultable]
+    if len(defaultable) > 1:
+        raise ValueError(
+            f"Multiple defaultable document loaders: "
+            f"{[l.name for l in defaultable]}")
+    return defaultable[0] if defaultable else None

agentic_dev_loop/outputs.py

@@ -0,0 +1,147 @@
+"""Captured agent output: value objects that own the response→artifact and
+response→verdict channels (unit-1).
+
+The pipeline — not the agent — writes the step's artifact from the agent's
+final SDK response. `Verdict.from_text` parses that same text for routing.
+Expected conditions are typed `Result` errors, never exceptions.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from pathlib import Path
+
+from openhands.sdk.conversation.response_utils import get_agent_final_response
+
+from .results import Result
+
+# Leading markdown/list/quote decoration tolerated on a verdict line.
+_LEAD_DECOR = "#*_`>- "
+# Decoration tolerated between VERDICT and ':' and after the keyword.
+_DECOR = "*_`> "
+# Caveat delimiters: after one of these, arbitrary prose may follow the
+# keyword without the line losing its decision status. '.' doubles as the
+# bare sentence terminator.
+_CAVEAT = "—–,;:."
+# Negators recognized immediately before the keyword.
+_NEGATORS = ("NOT", "DOES NOT", "DID NOT")
+
+
+class CaptureError(enum.Enum):
+    EMPTY_RESPONSE = "empty_response"
+    IO_ERROR = "io_error"
+
+
+class VerdictError(enum.Enum):
+    NO_VERDICT = "no_verdict"
+    AMBIGUOUS = "ambiguous"
+
+
+@dataclass(frozen=True)
+class Verdict:
+    """A parsed decision: `value` is the canonical outcome (e.g. 'pass').
+
+    Parsing policy (BR-2): the last decoration-tolerant `VERDICT: X` line
+    that carries a *decision* wins; a keyword followed directly by prose is
+    discussion, not a decision. Conflicting decisions are never silently
+    resolved — they surface as AMBIGUOUS and retry.
+    """
+
+    value: str
+
+    @staticmethod
+    def from_text(text: str, verdicts: dict[str, str]) -> "Result[Verdict, VerdictError]":
+        decisions: set[str] = set()
+        saw_verdict_line = False
+        for line in text.splitlines():
+            is_line, decision = _parse_line(line, verdicts)
+            if is_line:
+                saw_verdict_line = True
+            if decision is not None:
+                decisions.add(decision)
+        if len(decisions) == 1:
+            return Result.ok(Verdict(value=next(iter(decisions))))
+        if len(decisions) > 1:
+            return Result.err(VerdictError.AMBIGUOUS)
+        if saw_verdict_line:
+            return Result.err(VerdictError.AMBIGUOUS)
+        return Result.err(VerdictError.NO_VERDICT)
+
+
+def _parse_line(line: str, verdicts: dict[str, str]) -> tuple[bool, str | None]:
+    """Parse one line -> (is_verdict_line, decision_or_None).
+
+    Ported verbatim from the pre-unit-1 `verdicts.py` parser; the original
+    returned None for both non-verdict lines and verdict lines without a
+    decision — the flag now separates those cases for BR-2.5/BR-2.6.
+    """
+    stripped = line.strip().lstrip(_LEAD_DECOR)
+    if not stripped.upper().startswith("VERDICT"):
+        return False, None
+    rest = stripped[len("VERDICT"):].lstrip(_DECOR)
+    if not rest.startswith(":"):
+        return True, None
+    body = rest[1:].strip()
+    negated = False
+    for negator in _NEGATORS:
+        if body.upper().startswith(negator + " "):
+            negated = True
+            body = body[len(negator):].strip()
+            break
+    body = body.lstrip(_DECOR)
+    for keyword in sorted(verdicts, key=len, reverse=True):
+        if not body.upper().startswith(keyword.upper()):
+            continue
+        after = body[len(keyword):].strip().lstrip(_DECOR).strip()
+        if after.startswith("?"):
+            return True, None
+        if after.startswith("!"):
+            if after[1:].strip():
+                return True, None  # bare '!' is emphasis; '!' plus prose is not
+        elif after and after[0] not in _CAVEAT and not after.startswith("-"):
+            return True, None  # bare prose — discussion, not a decision
+        if negated:
+            if len(verdicts) == 2:
+                other = next(k for k in verdicts if k != keyword)
+                return True, verdicts[other]
+            return True, None  # negation on a larger set is ambiguous
+        return True, verdicts[keyword]
+    return True, None
+
+
+@dataclass(frozen=True)
+class CapturedOutput:
+    """The agent's final response, captured by the pipeline (FR-1.2)."""
+
+    raw_text: str
+    artifact_path: Path
+
+    @staticmethod
+    def from_agent_result(
+        conv, artifact: str, state_dir: Path
+    ) -> "Result[CapturedOutput, CaptureError]":
+        text = _final_agent_text(conv)
+        if not text.strip():
+            return Result.err(CaptureError.EMPTY_RESPONSE)
+        return Result.ok(CapturedOutput(raw_text=text, artifact_path=state_dir / artifact))
+
+    def write(self) -> Result[None, CaptureError]:
+        """Write the captured response to the step's artifact path (BR-4/BR-5)."""
+        try:
+            self.artifact_path.parent.mkdir(parents=True, exist_ok=True)
+            self.artifact_path.write_text(self.raw_text)
+            return Result.ok(None)
+        except OSError:
+            return Result.err(CaptureError.IO_ERROR)
+
+
+def _final_agent_text(conv) -> str:
+    """Extract the agent's final response from an SDK conversation.
+
+    Delegates to the SDK's own `get_agent_final_response`, which handles both
+    ways an agent can end a run — a `FinishTool` call or a plain-text message.
+    The events live on ``conv.state.events`` (NOT ``conv.events``), and must be
+    read before ``conv.close()`` releases the event stream.
+    """
+    return get_agent_final_response(getattr(conv.state, "events", []))

agentic_dev_loop/proc.py

@@ -0,0 +1,54 @@
+"""Pure subprocess helpers shared by command and action steps.
+
+Command steps classify their command string, split simple commands into argv
+lists, and scrub the child environment; action steps reuse the pid-token gate
+and the same env scrubbing. All four functions are stateless (PBT targets).
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+from collections.abc import Mapping
+
+_SHELL_METACHARS = frozenset("&|;><$`~*?[]")
+_FIXED_ENV = ("PATH", "HOME", "LANG", "LC_ALL", "TERM")
+
+
+def needs_shell(command: str) -> bool:
+    """True when `command` carries shell metacharacters (``&&``, ``|``,
+    ``;``, ``>``, ``<``, ``$``, backticks, ``~``, or glob chars). Simple
+    commands are shlex-split and run shell-free; anything else keeps
+    ``shell=True`` (BR-4.1 / BR-4.2)."""
+    return any(char in _SHELL_METACHARS for char in command)
+
+
+def split_command(command: str) -> list[str]:
+    """Split a simple command into argv via ``shlex.split``. Callers invoke
+    this only when ``needs_shell`` is false — ``shlex`` never sees a shell
+    command (BR-4.1)."""
+    return shlex.split(command)
+
+
+def is_pid_token(token: str) -> bool:
+    """True only for a plain decimal integer — the only tokens from ``lsof``
+    output safe to hand to ``kill``/``ps`` (BR-5.2)."""
+    return token.isascii() and token.isdigit()
+
+
+def child_env(allowlist: list[str] | None = None,
+              api_key_env: str | None = None,
+              parent: Mapping[str, str] | None = None) -> dict[str, str]:
+    """Build a scrubbed child environment: the fixed known-safe whitelist
+    (``PATH``, ``HOME``, ``LANG``, ``LC_ALL``, ``TERM``), plus the env var
+    named by ``api_key_env`` (always included by default), plus any
+    additional names in ``allowlist`` (the author-extensible
+    ``env_allowlist``). Everything else is excluded
+    (BR-4.3, BR-5.4, NFR-2.1)."""
+    source = os.environ if parent is None else parent
+    names = set(_FIXED_ENV)
+    if api_key_env:
+        names.add(api_key_env)
+    if allowlist:
+        names.update(allowlist)
+    return {name: source[name] for name in names if name in source}