agentic-dev-loop 0.3.0__py3-none-any.whl → 1.0.0a2__py3-none-any.whl

agentic_dev_loop/actions.py

@@ -30,6 +30,15 @@ def _git(args: list[str], cwd: Path) -> subprocess.CompletedProcess:
                           env=child_env())
 
 
+def _trusted_hooks_dir() -> str:
+    """The agentic-dev-loop-managed hooks dir (Q3): repo hooks in ``.git/hooks``
+    never execute during the trusted commit action. Created empty; git runs
+    with ``-c core.hooksPath=<this dir>`` so there is no hook to run."""
+    d = Path("~/.agentic-dev-loop/state/hooks").expanduser()
+    d.mkdir(parents=True, exist_ok=True)
+    return str(d)
+
+
 def git_worktree_clean(path: Path) -> bool:
     """True only when `path` is a git repo with no uncommitted changes.
     Outside a repo there is no clean baseline — False (fail-safe, keeps the
@@ -155,6 +164,28 @@ def kill_listeners_on_port(port: int, match: str | None = None,
                            shell=False, env=child_env())
 
 
+def checkpoint_exclude_pathspec(state_dir: str | None, cwd: Path) -> str | None:
+    """git pathspec excluding the live checkpoint DB from ``git add -A``.
+
+    The checkpointer keeps ``state_dir/loop-checkpoints.sqlite`` open for the
+    whole run; on Windows an open SQLite file blocks other readers, so
+    ``git add`` fails to hash it (CI-red gate failure). When the state dir
+    sits inside the repo, exclude its sqlite files (db + wal/shm) from the
+    auto-commit — checkpoint state is runtime machinery, not constructed
+    work. Returns None when there is nothing in-repo to exclude (no state
+    dir known, or it lives outside the repo).
+    """
+    if not state_dir:
+        return None
+    rel = os.path.relpath(state_dir, cwd)
+    if rel == ".." or rel.startswith(".." + os.sep):
+        return None
+    rel = rel.replace(os.sep, "/")
+    if rel == ".":
+        return ":(exclude)*.sqlite*"
+    return f":(exclude){rel}/*.sqlite*"
+
+
 def commit(state: dict, params: dict) -> dict:
     """The pipeline's only commit point. Skipped loudly when the worktree was
     dirty at run start, so the auto-commit can never swallow pre-existing
@@ -172,12 +203,24 @@ def commit(state: dict, params: dict) -> dict:
         raise ValueError("commit action requires params.message "
                          "(a template rendered with {subject})")
     cwd = Path.cwd()
-    _git(["add", "-A"], cwd=cwd)
+    hooks = _trusted_hooks_dir()
+    add_argv = ["-c", f"core.hooksPath={hooks}", "add", "-A"]
+    exclude = checkpoint_exclude_pathspec(state.get("state_dir"), cwd)
+    if exclude:
+        add_argv += ["--", exclude]
+    added = _git(add_argv, cwd=cwd)
+    if added.returncode != 0:
+        # The add is the step that touches the most files (a locked DB, a
+        # permission problem) — its error is the diagnostic that matters.
+        print(f"WARNING: [{subject}] auto-commit failed — git add: "
+              f"{added.stderr.strip()}", file=sys.stderr, flush=True)
+        return {}
     if not _git(["status", "--porcelain"], cwd=cwd).stdout.strip():
         print(f"[{subject}] Nothing to commit.", flush=True)
         return {}
     message = params["message"].format(subject=subject)
-    result = _git(["commit", "-m", message], cwd=cwd)
+    result = _git(["-c", f"core.hooksPath={hooks}", "commit", "-m", message],
+                  cwd=cwd)
     if result.returncode != 0:
         # The work is built and verified — a git error is a loud warning,
         # not a pipeline failure.

agentic_dev_loop/agents.py

@@ -1,19 +1,27 @@
 """Agent file loading + SDK factory mechanics.
 
 The SDK's built-in tools are registered at import (its registry is global);
-consumer tools are registered by extensions via `Registry.add_tool`."""
+consumer tools are registered by extensions via `Registry.add_tool`. Unit-3
+adds the sandbox terminal seam: `SandboxTerminalExecutor` delegates each
+terminal action to a `Sandbox.run`, and `register_sandbox_terminal` re-registers
+the `terminal` tool name per run (KD-4 / §6)."""
 
 from pathlib import Path
 from typing import TYPE_CHECKING
 
 from openhands.sdk import LLM
+from openhands.sdk.tool import ToolExecutor
 from openhands.tools.file_editor import FileEditorTool  # noqa: F401 — registers "file_editor"
 from openhands.tools.task_tracker import TaskTrackerTool  # noqa: F401 — registers "task_tracker"
 from openhands.tools.terminal import TerminalTool  # noqa: F401 — registers "terminal"
 
+from .isolation import SandboxExecutionRequest, command_argv, resolve_sandbox_env
+
 if TYPE_CHECKING:
     from openhands.sdk.agent.agent import Agent
 
+    from .isolation import Sandbox
+
 
 def load_agent(agents_dir: Path | str, name: str, llm: LLM) -> "Agent":
     """Load `<agents_dir>/<name>.agent.md` and build the Agent via the SDK
@@ -47,3 +55,71 @@ def load_agent(agents_dir: Path | str, name: str, llm: LLM) -> "Agent":
             f"Agent file {path} name {agent_def.name!r} does not match "
             f"filename {stem!r}")
     return agent_definition_to_factory(agent_def)(llm)
+
+
+class SandboxTerminalExecutor(ToolExecutor):
+    """A stateless terminal executor: each action is a fresh ``Sandbox.run``
+    (no persistent shell session). ``is_input`` degrades to an unsupported
+    observation; ``reset`` is a no-op (there is no session to reset)."""
+
+    def __init__(self, sandbox: "Sandbox", *, workspace: str = "",
+                 env: dict[str, str] | None = None,
+                 pipeline: str | None = None, step: str | None = None):
+        self._sandbox = sandbox
+        self._workspace = workspace
+        self._env = env or {}
+        self._pipeline = pipeline
+        self._step = step
+
+    def __call__(self, action, conversation=None):
+        from openhands.tools.terminal import TerminalObservation
+        from openhands.tools.terminal.metadata import CmdOutputMetadata
+
+        if action.reset:
+            return TerminalObservation.from_text(
+                "[reset unsupported — stateless sandbox]",
+                command=action.command, exit_code=None, timeout=False,
+                metadata=CmdOutputMetadata(exit_code=-1))
+
+        if action.is_input:
+            return TerminalObservation.from_text(
+                "[input unsupported — stateless sandbox]",
+                command=action.command, exit_code=None, timeout=False,
+                metadata=CmdOutputMetadata(exit_code=-1))
+
+        request = SandboxExecutionRequest(
+            argv=command_argv(action.command), cwd=self._workspace,
+            env=self._env, timeout=action.timeout,
+            pipeline=self._pipeline, step=self._step)
+        result = self._sandbox.run(request)
+        output = result.stdout + result.stderr
+        return TerminalObservation.from_text(
+            output, is_error=not result.succeeded and not result.is_timeout,
+            command=action.command, exit_code=result.exit_code,
+            timeout=result.timed_out,
+            metadata=CmdOutputMetadata(
+                exit_code=result.exit_code if result.exit_code is not None else -1,
+                working_dir=self._workspace))
+
+    def close(self) -> None:
+        pass  # the sandbox is closed by Runtime; idempotent
+
+
+def register_sandbox_terminal(sandbox: "Sandbox", *, env: dict[str, str | None] | None = None,
+                              workspace: str = "", pipeline: str | None = None,
+                              step: str | None = None) -> None:
+    """Per-run re-registration of the `terminal` name (KD-4): a callable
+    factory that builds the SDK terminal with a `SandboxTerminalExecutor`.
+    Pipelines are sequential, so re-registering per agent step is safe."""
+    from openhands.sdk.tool import register_tool
+
+    resolved_env = resolve_sandbox_env(env)
+
+    def factory(conv_state, **params):
+        return TerminalTool.create(
+            conv_state,
+            executor=SandboxTerminalExecutor(
+                sandbox, workspace=workspace, env=resolved_env,
+                pipeline=pipeline, step=step))
+
+    register_tool("terminal", factory)

agentic_dev_loop/cli.py

@@ -10,7 +10,8 @@ import sys
 from pathlib import Path
 
 from .config import load_config
-from .graph import run_pipeline
+from .dryrun import dry_run
+from .isolation import clean_stamps, isolation_state_dir
 from .registry import default_registry, load_extensions
 
 
@@ -49,6 +50,15 @@ def _core_parser() -> argparse.ArgumentParser:
                         help="preferred port for the live graph view "
                              "(default: 8321; falls back to a free port when "
                              "busy)")
+    parser.add_argument("--refresh", action="store_true",
+                        help="force re-provision of every setup: hook "
+                             "(bypasses the stamp cache)")
+    parser.add_argument("--dry-run", action="store_true",
+                        help="validate the pipeline and print a summary plan "
+                             "without executing anything (no LLM, no "
+                             "sandbox, no state writes)")
+    parser.add_argument("--clean-stamps", action="store_true",
+                        help="delete cached provision stamps and exit")
     _add_version_flag(parser)
     return parser
 
@@ -75,6 +85,18 @@ def main(argv: list[str] | None = None) -> int:
         _core_parser().parse_args(argv)
         return 2  # unreachable — parse_args exits first
     args = build_parser(known.pipeline).parse_args(argv)
+    if args.clean_stamps:
+        cfg = load_config(args.pipeline)
+        state = isolation_state_dir(cfg)
+        removed = clean_stamps(state)
+        print(f"Removed {removed} cached provision stamp(s) from "
+              f"{state / 'stamps'}", flush=True)
+        return 0
+    if args.dry_run:
+        return dry_run(args.pipeline, args)
+    # The run path alone needs the heavy graph/SDK imports — defer so a
+    # dry run, --clean-stamps, and --help stay side-effect free.
+    from .graph import run_pipeline
     success, _attempts = run_pipeline(args.pipeline, args)
     if not success:
         print("agentic-dev-loop: pipeline failed — exiting with code 1",

agentic_dev_loop/config.py

@@ -1,5 +1,9 @@
 """Pipeline YAML schema and loader. Strict: unknown keys fail at every level."""
 
+from __future__ import annotations
+
+import hashlib
+import re
 from pathlib import Path
 from typing import Any
 
@@ -32,6 +36,36 @@ def route_target(route: RouteTarget | None) -> str | None:
     return route.goto if isinstance(route, Route) else route
 
 
+class IsolationConfig(BaseModel):
+    """Optional `isolation:` section — configures the always-on sandbox (BR-2).
+    Absence means opinionated defaults, never unsandboxed behaviour. Unknown
+    keys fail at load (BR-5). `state_dir` is HOST-ONLY (stamps + audit) and is
+    never mounted into the sandbox (Q1)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    image: str | None = None            # per-pipeline override (KD-2 ref rules)
+    refresh: bool = False               # force re-provision (NFR-5)
+    memory: str | None = None           # override exec container memory
+    cpus: float | None = None           # override exec container cpus
+    allow_git_mutations: bool = False   # BR-6 knob
+    state_dir: str = "~/.agentic-dev-loop/state"  # stamps + audit (host-only)
+
+    @field_validator("memory")
+    @classmethod
+    def _check_memory(cls, v: str | None) -> str | None:
+        if v is not None and re.fullmatch(r"\d+[kmg]", v) is None:
+            raise ValueError(f"memory {v!r} must match ^\\d+[kmg]$")
+        return v
+
+    @field_validator("cpus")
+    @classmethod
+    def _check_cpus(cls, v: float | None) -> float | None:
+        if v is not None and v <= 0:
+            raise ValueError("cpus must be > 0")
+        return v
+
+
 class StepConfig(BaseModel):
     """One pipeline step. Its type IS the key it carries: exactly one of
     `agent`, `action`, or `command` — empty values do not count, anything
@@ -49,6 +83,8 @@ class StepConfig(BaseModel):
     verdicts: VerdictSpec | None = None
     max_iterations: int | None = None
     timeout: float | None = Field(default=None, gt=0)  # seconds, command steps only
+    env: dict[str, str | None] | None = None  # NFR-1: null = inherit host value
+    setup: str | None = None  # BR-13: command steps only
     on_pass: RouteTarget | None = None
     on_fail: RouteTarget | None = None
 
@@ -102,6 +138,10 @@ class StepConfig(BaseModel):
             raise ValueError(
                 f"step {self.name!r}: 'timeout' requires 'command'"
             )
+        if self.setup is not None and self.command is None:
+            raise ValueError(
+                f"step {self.name!r}: 'setup' is only allowed on 'command' steps"
+            )
         return self
 
 
@@ -122,7 +162,8 @@ class PipelineConfig(BaseModel):
     additional_files: list[str] = []
     env_allowlist: list[str] = []
     llm: LlmConfig
-    state_dir: str = ".pr"
+    isolation: IsolationConfig | None = None  # None = always-on defaults
+    state_dir: str = ".pr"  # default relocated to ~/.agentic-dev-loop/runs/<hash>/ at load
     max_attempts: int = 3
     agents_dir: str
     steps: list[StepConfig] = Field(min_length=1)
@@ -147,10 +188,23 @@ class PipelineConfig(BaseModel):
         return self
 
 
+def default_state_dir(pipeline_path: Path) -> str:
+    """The new run-state default (Q1): checkpoint DB + last-error.md live OUTSIDE
+    the workspace mount, under ~/.agentic-dev-loop/runs/<pipeline-hash>/ where
+    pipeline-hash is the first 12 chars of the sha256 of the absolute
+    pipeline-file path. Explicit `state_dir:` configs keep working unchanged."""
+    digest = hashlib.sha256(
+        str(Path(pipeline_path).resolve()).encode("utf-8")).hexdigest()[:12]
+    return str(Path("~/.agentic-dev-loop/runs").expanduser() / digest)
+
+
 def load_config(path: Path) -> PipelineConfig:
-    data = yaml.safe_load(Path(path).read_text())
+    path = Path(path)
+    data = yaml.safe_load(path.read_text())
     if not isinstance(data, dict):
         raise ValueError(
             f"pipeline config must be a mapping, got {type(data).__name__}: {path}"
         )
+    if "state_dir" not in data:
+        data["state_dir"] = default_state_dir(path)
     return PipelineConfig.model_validate(data)

agentic_dev_loop/dryrun.py

@@ -0,0 +1,122 @@
+"""`--dry-run`: the full load-and-validate pass with zero execution.
+
+Everything short of running a step happens here — YAML parse, step schema
+validation, extension loading (document loaders included), agents_dir /
+verdict / routing-target resolution, isolation config validation, and pure
+image-ref resolution (no Docker calls). No LLM is built, no sandbox is
+started, and no state/checkpoint/viz writes happen, so a dry run needs no
+API key.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .config import PipelineConfig, StepConfig, load_config
+from .loaders import resolve_docs
+from .isolation import (isolation_state_dir, resolve_effective_profile,
+                        resolve_image_ref)
+from .registry import Registry, default_registry, load_extensions
+
+
+def _validate_agents(cfg: PipelineConfig, agents_dir: Path) -> None:
+    """Every `agent:` step must resolve to an existing file under agents_dir
+    (the same fail-fast `load_agent` enforces at run time)."""
+    for step in cfg.steps:
+        if step.agent is not None:
+            path = agents_dir / f"{step.agent}.agent.md"
+            if not path.is_file():
+                raise FileNotFoundError(f"Agent file not found: {path}")
+
+
+def _validate_actions(cfg: PipelineConfig, registry: Registry) -> None:
+    """Unknown action names fail at graph build time; catch them here so a
+    dry run is a true load pass."""
+    for step in cfg.steps:
+        if step.action is not None and step.action not in registry.actions:
+            raise ValueError(
+                f"step {step.name!r}: unknown action {step.action!r} "
+                f"(registered: {sorted(registry.actions)})")
+
+
+def _resolved_image(cfg: PipelineConfig) -> tuple[str, str, float]:
+    """The exec image ref + resource caps. An explicit `image: ""` is a hard
+    fail (AE-SBX-005) rather than a silent fallback to the digest-pinned
+    default; the env override still wins, exactly as at startup."""
+    profile = resolve_effective_profile(cfg.isolation)
+    if cfg.isolation is not None and cfg.isolation.image == "":
+        image = resolve_image_ref("")
+    else:
+        image = resolve_image_ref(profile.image)
+    return image, profile.memory, profile.cpus
+
+
+def _step_summary(step: StepConfig) -> str:
+    """The kind + key params for one step, on a single line."""
+    if step.kind == "agent":
+        parts = [f"agent={step.agent}"]
+        if step.artifact is not None:
+            parts.append(f"artifact={step.artifact}")
+        if step.verdicts is not None:
+            parts.append(f"verdicts={step.verdicts.pass_}/{step.verdicts.fail}")
+        if step.produces:
+            parts.append(f"produces={','.join(step.produces)}")
+        if step.max_iterations is not None:
+            parts.append(f"max_iterations={step.max_iterations}")
+    elif step.kind == "command":
+        parts = [f"command={step.command}"]
+        if step.timeout is not None:
+            parts.append(f"timeout={step.timeout:g}")
+        if step.setup is not None:
+            parts.append(f"setup={step.setup}")
+    else:
+        parts = [f"action={step.action}"]
+        if step.params:
+            parts.append(f"params={step.params}")
+    return ", ".join(parts)
+
+
+def _print_summary(cfg_path: Path, cfg: PipelineConfig, subject: str,
+                   loader, docs: dict[str, str], image: str, memory: str,
+                   cpus: float, state_dir: Path) -> None:
+    print(f"Pipeline: {cfg_path.resolve()}")
+    print(f"Subject: {subject}")
+    if loader is not None:
+        print(f"Document loader: {loader.name} ({len(docs)} docs)")
+        for key in sorted(docs):
+            print(f"  - {key}")
+    else:
+        print("Document loader: none")
+    print("Steps:")
+    for step in cfg.steps:
+        print(f"  - {step.name} [{step.kind}]: {_step_summary(step)}")
+    print("Isolation:")
+    print("  backend: docker")
+    print(f"  image: {image}")
+    print(f"  memory: {memory}")
+    print(f"  cpus: {cpus}")
+    print(f"  state_dir: {state_dir}")
+    print("dry run complete — nothing executed")
+
+
+def dry_run(cfg_path, args) -> int:
+    """Validate a pipeline end-to-end without executing it, and print a
+    summary plan. Returns 0 on a clean load; any load failure propagates as
+    the existing loud error (the CLI exits 1)."""
+    cfg_path = Path(cfg_path)
+    cfg = load_config(cfg_path)
+    base = cfg_path.resolve().parent
+
+    registry = default_registry()
+    load_extensions(cfg.extensions, registry)
+
+    _validate_agents(cfg, base / cfg.agents_dir)
+    _validate_actions(cfg, registry)
+
+    loader, docs, subject = resolve_docs(cfg, base, registry, args)
+    image, memory, cpus = _resolved_image(cfg)
+    state_dir = isolation_state_dir(cfg)
+
+    _print_summary(cfg_path, cfg, subject, loader, docs, image, memory, cpus,
+                   state_dir)
+    return 0

agentic_dev_loop/extensions/aidlc.py

@@ -45,7 +45,7 @@ def resolve_unit_docs(docs_dir: Path | str, unit_slug: str) -> dict[str, str]:
 
     for file in sorted(unit_dir.rglob("*")):
         if file.is_file() and file.suffix in _DOC_SUFFIXES:
-            key = str(file.relative_to(unit_dir))
+            key = file.relative_to(unit_dir).as_posix()
             docs[key] = file.read_text()
 
     # At this point docs holds only unit-dir files — an empty load means the

agentic_dev_loop/graph.py

@@ -19,8 +19,9 @@ 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 .isolation import startup_sandbox
 from .llm import build_llm
-from .loaders import select_loader
+from .loaders import resolve_docs
 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,
@@ -43,6 +44,7 @@ class LoopState(TypedDict):
     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
+    state_dir: str                     # resolved pipeline state dir (for the commit action)
     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
@@ -77,29 +79,6 @@ def build_graph(runtime: Runtime, checkpointer=None):
     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,
@@ -125,10 +104,27 @@ def run_pipeline(cfg_path, args, *, viz_bus=None) -> tuple[bool, int]:
     registry = default_registry()
     load_extensions(cfg.extensions, registry)
 
-    state_dir = base / cfg.state_dir
+    state_dir = Path(cfg.state_dir).expanduser()
+    if not state_dir.is_absolute():
+        state_dir = base / state_dir
+
+    # Eager startup (Q2): probe -> image -> create+start exec container ->
+    # pre-provision all declared setups, BEFORE the graph builds. Zero infra
+    # operations mid-run; the only sandbox call during steps is run(request).
+    sandbox = startup_sandbox(cfg, workspace=Path.cwd(),
+                               refresh=getattr(args, "refresh", False))
+    try:
+        return _run_pipeline(cfg, base, registry, state_dir, max_attempts,
+                             args, viz_bus, sandbox)
+    finally:
+        sandbox.close()
+
+
+def _run_pipeline(cfg, base, registry, state_dir, max_attempts, args, viz_bus,
+                  sandbox) -> tuple[bool, int]:
     runtime = Runtime(cfg=cfg, registry=registry, llm=build_llm(cfg.llm),
                       agents_dir=base / cfg.agents_dir, state_dir=state_dir,
-                      workspace=Path.cwd())
+                      workspace=Path.cwd(), sandbox=sandbox)
     state_dir.mkdir(parents=True, exist_ok=True)
 
     resume = getattr(args, "resume", None)
@@ -138,7 +134,7 @@ def run_pipeline(cfg_path, args, *, viz_bus=None) -> tuple[bool, int]:
     if resume:
         initial = None  # state (docs/subject/context) comes from the checkpoint
     else:
-        docs, subject = _resolve_docs(cfg, base, registry, args)
+        _loader, 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.
@@ -159,6 +155,7 @@ def run_pipeline(cfg_path, args, *, viz_bus=None) -> tuple[bool, int]:
             # the checkpointer creates its db under state_dir, which would
             # itself dirty the worktree.
             "commit_allowed": git_worktree_clean(Path.cwd()),
+            "state_dir": str(state_dir),
             "step_verdicts": {},
             "retry_target": None,
             "thread_id": thread_id,