agentic-dev-loop 0.2.0__tar.gz → 1.0.0a1__tar.gz

{agentic_dev_loop-0.2.0 → agentic_dev_loop-1.0.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 0.2.0
+Version: 1.0.0a1
 Summary: Opinionated LangGraph engine for OpenHands agent pipelines
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -50,6 +50,17 @@ Publicly depends on [OpenHands SDK](https://github.com/OpenHands/software-agent-
 for agent execution and [LangGraph](https://github.com/langchain-ai/langgraph)
 (+ `langgraph-checkpoint-sqlite`) for the state graph.
 
+## Sandboxed execution
+
+The agent `terminal` tool and command steps run inside an **always-on**,
+Docker-based kernel-level sandbox — `--network none`, read-only rootfs,
+dropped capabilities, writes only on the bind-mounted workspace. The
+`isolation:` section configures the sandbox (image override, resource caps,
+per-step `env:`/`setup:`, git-mutation blocking); it can never disable it. A
+missing or unusable Docker engine fails fast with an `AE-SBX-*` message. See
+[docs/setup.md](docs/setup.md) for the engine setup, first-run image pull, the
+`pipeline.yaml` contract, stamp caching, and troubleshooting.
+
 ## Install & test
 
 ```bash
@@ -65,8 +76,9 @@ Requires Python ≥ 3.12.
 ```bash
 export OPENAI_API_KEY=...   # whatever env var your pipeline's api_key_env names
 agentic-dev-loop agentic-dev-loop/pipeline.yaml --plan plan.md
-agentic-dev-loop agentic-dev-loop/pipeline.yaml --ai-dlc-unit U2
+agentic-dev-loop agentic-dev-loop/pipeline.yaml --aidlc-unit unit-2
 agentic-dev-loop agentic-dev-loop/pipeline.yaml --resume <thread-id> --max-attempts 5
+agentic-dev-loop agentic-dev-loop/pipeline.yaml --plan plan.md --dry-run
 ./trigger-agentic-dev-loop.sh --plan plan.md   # same thing, from the repo root
 ```
 
@@ -84,10 +96,21 @@ expanded and live-tails its console. To eyeball the viz page without
 running a pipeline, `.venv/bin/python viz_demo.py` serves the real topology
 and replays a scripted run (every node state, verdict badges, retry cycle).
 
-`--ai-dlc-unit` accepts any unambiguous spelling of a unit number — `U2`,
-`2`, `U002`, `002` — or the full unit slug (`U002-custom-configuration`).
-If multiple unit directories match one id, the run fails loudly naming
-every candidate; pass the full slug to disambiguate.
+`--dry-run` performs the full load-and-validate pass — YAML parse, step
+config validation, extension and document-loader loading, agents_dir /
+verdict / routing-target resolution, and pure image-ref resolution — without
+executing anything, then prints a summary plan (pipeline path, subject,
+resolved loader + docs, per-step kind and key params, and the resolved
+isolation profile). It makes no LLM call, touches no Docker daemon, and
+writes no state, so it needs no API key; it exits `0` on a clean load and
+`1` with the usual load error otherwise.
+
+`--aidlc-unit` takes the unit directory name under
+`aidlc-docs/construction/` verbatim — `unit-2`,
+`unit-002-custom-configuration`, or any slug AI-DLC's own naming uses
+(AI-DLC imposes no naming convention on unit directories). No spelling
+tolerance, no numeric aliases: the slug must name the directory exactly,
+and a wrong slug fails loudly listing the directories that do exist.
 
 ## What a run looks like
 
@@ -105,11 +128,12 @@ dev ──▶ test ──▶ review ──▶ qa ──▶ commit
    `additional_files:` + auto-generated expected-output paths). Its writes
    are untracked; the pipeline only cares about declared `produces:` files.
 2. **test** is a mechanical command step: it runs the suite
-   (`.venv/bin/python -m pytest tests/ -q`) in the workspace shell. Exit 0
-   passes and moves on; anything else (including no exit by `timeout`) fails
-   and rewinds to `dev` with the failing output in the retry note.
+   (`.venv-sandbox/bin/python -m pytest tests/ -q -m "not docker"`) inside the
+   sandbox. Exit 0 passes and moves on; anything else (including no exit by
+   `timeout`) fails and rewinds to `dev` with the failing output in the retry
+   note.
 3. **review / qa** are verdict agents: each must write its declared
-   artifact (e.g. `.pr/qa-report.md`) whose **last** `VERDICT: <word>` line
+   artifact (e.g. `qa-report.md`) whose **last** `VERDICT: <word>` line
    decides routing. `pass` follows `on_pass`, `fail` follows `on_fail` —
    here `{goto: dev, retry: true}`, which consumes an attempt and feeds the
    artifact back to the dev agent as a retry note.
@@ -139,7 +163,8 @@ llm:
   api_key_env: OPENAI_API_KEY        # missing env var → run fails fast, naming it
   # timeout: null                    # default = no client timeout (long agent runs)
 
-state_dir: .pr                        # artifacts + checkpoints live here
+# state_dir omitted → default ~/.agentic-dev-loop/runs/<pipeline-hash>/
+# (artifacts + checkpoints live OUTSIDE the sandbox mount)
 max_attempts: 10                      # retries across the whole graph
 agents_dir: sdk_agents                # consumer-owned <name>.agent.md files
 
@@ -150,8 +175,9 @@ steps:
     on_pass: test                     # explicit; omitted → next step in order
 
   - name: test
-    command: .venv/bin/python -m pytest tests/ -q   # mechanical: exit code is the verdict
-    timeout: 600                                     # seconds; SIGKILLs the process group
+    command: .venv-sandbox/bin/python -m pytest tests/ -q -m "not docker"   # sandboxed: exit code is the verdict
+    setup: python -m venv .venv-sandbox && .venv-sandbox/bin/pip install -e ".[dev]"   # provision (network ON, stamp-cached)
+    timeout: 600                                     # seconds
     on_pass: review
     on_fail: {goto: dev, retry: true}
 
@@ -191,8 +217,9 @@ load. Graph-building dispatches on this `kind` (see `StepConfig.kind` in
   `artifact:` + `verdicts:` (verdict-parsed routing). `max_iterations` caps
   the agent's own loop.
 - **`command: <shell>`** — a *command step*: mechanical, never an LLM call.
-  The command runs in the workspace shell; exit 0 passes, anything else
-  (including no exit by `timeout`) fails. `timeout:` is its only extra field.
+  The command runs inside the sandbox (the bind-mounted workspace); exit 0
+  passes, anything else (including no exit by `timeout`) fails. `timeout:` and
+  `setup:` are its only extra fields.
 - **`action: <name>`** — an *action step*: invokes a registered node-shaped
   function `(state, params) -> state update` with the step's `params:`. The
   built-in is `commit`; extensions register more via `registry.add_action`.
@@ -203,8 +230,8 @@ load. Graph-building dispatches on this `kind` (see `StepConfig.kind` in
 
 ### Step semantics
 
-- A `command` step is **mechanical** — the command runs in the workspace
-  shell; exit 0 passes, anything else (including no exit by `timeout`,
+- A `command` step is **mechanical** — the command runs inside the
+  sandbox; exit 0 passes, anything else (including no exit by `timeout`,
   default 600s) fails and follows `on_fail` with the output tail in the
   retry note. The kind is the `command:` key, never the step's name.
 - `artifact` + `verdicts` mark a **verdict step**. `on_pass`/`on_fail` may be
@@ -258,10 +285,10 @@ Loader-selection flow: a loader's flag in argv selects it; flags from two
 loaders in one invocation error out; with no flag, the sole `defaultable`
 loader autoruns (the bundled `ai-dlc` loader autodetects the current unit
 from `aidlc-docs/aidlc-state.md`), otherwise the run proceeds with no
-injected docs and the pipeline `name:` as subject. Unit ids resolve by
-exact directory name or by numeric prefix (`unit-004-preset-management`
-answers to `4`, `004`, `U4`, `U004`, or its full slug); ambiguous ids fail
-loud listing all matches. A selected loader that
+injected docs and the pipeline `name:` as subject. A unit id must name
+its directory exactly (`--aidlc-unit unit-3`); there is no numeric
+fallback or spelling tolerance, and an unmatched slug fails loud listing
+the available directories. A selected loader that
 yields zero docs **fails fast** — context is never silently degraded.
 Duplicate CLI option strings across loaders are a load-time error naming both.
 
@@ -303,7 +330,7 @@ The development lifecycle workflow lives in
 phase details under `aws-aidlc-rule-details/`). Working docs — plans, user
 stories, units of work, state — live in `aidlc-docs/`, created as the
 workflow runs. The bundled `ai-dlc` document loader (see Extension points)
-wires the pipeline's `--ai-dlc-unit` flag to those docs.
+wires the pipeline's `--aidlc-unit` flag to those docs.
 
 OpenCode commands over the workflow: `/epic-status`, `/ticket-details`,
 `/unit-status`, `/update-subtask` (ticket boards over `aidlc-docs/`),

{agentic_dev_loop-0.2.0 → agentic_dev_loop-1.0.0a1}/README.md

@@ -12,6 +12,17 @@ Publicly depends on [OpenHands SDK](https://github.com/OpenHands/software-agent-
 for agent execution and [LangGraph](https://github.com/langchain-ai/langgraph)
 (+ `langgraph-checkpoint-sqlite`) for the state graph.
 
+## Sandboxed execution
+
+The agent `terminal` tool and command steps run inside an **always-on**,
+Docker-based kernel-level sandbox — `--network none`, read-only rootfs,
+dropped capabilities, writes only on the bind-mounted workspace. The
+`isolation:` section configures the sandbox (image override, resource caps,
+per-step `env:`/`setup:`, git-mutation blocking); it can never disable it. A
+missing or unusable Docker engine fails fast with an `AE-SBX-*` message. See
+[docs/setup.md](docs/setup.md) for the engine setup, first-run image pull, the
+`pipeline.yaml` contract, stamp caching, and troubleshooting.
+
 ## Install & test
 
 ```bash
@@ -27,8 +38,9 @@ Requires Python ≥ 3.12.
 ```bash
 export OPENAI_API_KEY=...   # whatever env var your pipeline's api_key_env names
 agentic-dev-loop agentic-dev-loop/pipeline.yaml --plan plan.md
-agentic-dev-loop agentic-dev-loop/pipeline.yaml --ai-dlc-unit U2
+agentic-dev-loop agentic-dev-loop/pipeline.yaml --aidlc-unit unit-2
 agentic-dev-loop agentic-dev-loop/pipeline.yaml --resume <thread-id> --max-attempts 5
+agentic-dev-loop agentic-dev-loop/pipeline.yaml --plan plan.md --dry-run
 ./trigger-agentic-dev-loop.sh --plan plan.md   # same thing, from the repo root
 ```
 
@@ -46,10 +58,21 @@ expanded and live-tails its console. To eyeball the viz page without
 running a pipeline, `.venv/bin/python viz_demo.py` serves the real topology
 and replays a scripted run (every node state, verdict badges, retry cycle).
 
-`--ai-dlc-unit` accepts any unambiguous spelling of a unit number — `U2`,
-`2`, `U002`, `002` — or the full unit slug (`U002-custom-configuration`).
-If multiple unit directories match one id, the run fails loudly naming
-every candidate; pass the full slug to disambiguate.
+`--dry-run` performs the full load-and-validate pass — YAML parse, step
+config validation, extension and document-loader loading, agents_dir /
+verdict / routing-target resolution, and pure image-ref resolution — without
+executing anything, then prints a summary plan (pipeline path, subject,
+resolved loader + docs, per-step kind and key params, and the resolved
+isolation profile). It makes no LLM call, touches no Docker daemon, and
+writes no state, so it needs no API key; it exits `0` on a clean load and
+`1` with the usual load error otherwise.
+
+`--aidlc-unit` takes the unit directory name under
+`aidlc-docs/construction/` verbatim — `unit-2`,
+`unit-002-custom-configuration`, or any slug AI-DLC's own naming uses
+(AI-DLC imposes no naming convention on unit directories). No spelling
+tolerance, no numeric aliases: the slug must name the directory exactly,
+and a wrong slug fails loudly listing the directories that do exist.
 
 ## What a run looks like
 
@@ -67,11 +90,12 @@ dev ──▶ test ──▶ review ──▶ qa ──▶ commit
    `additional_files:` + auto-generated expected-output paths). Its writes
    are untracked; the pipeline only cares about declared `produces:` files.
 2. **test** is a mechanical command step: it runs the suite
-   (`.venv/bin/python -m pytest tests/ -q`) in the workspace shell. Exit 0
-   passes and moves on; anything else (including no exit by `timeout`) fails
-   and rewinds to `dev` with the failing output in the retry note.
+   (`.venv-sandbox/bin/python -m pytest tests/ -q -m "not docker"`) inside the
+   sandbox. Exit 0 passes and moves on; anything else (including no exit by
+   `timeout`) fails and rewinds to `dev` with the failing output in the retry
+   note.
 3. **review / qa** are verdict agents: each must write its declared
-   artifact (e.g. `.pr/qa-report.md`) whose **last** `VERDICT: <word>` line
+   artifact (e.g. `qa-report.md`) whose **last** `VERDICT: <word>` line
    decides routing. `pass` follows `on_pass`, `fail` follows `on_fail` —
    here `{goto: dev, retry: true}`, which consumes an attempt and feeds the
    artifact back to the dev agent as a retry note.
@@ -101,7 +125,8 @@ llm:
   api_key_env: OPENAI_API_KEY        # missing env var → run fails fast, naming it
   # timeout: null                    # default = no client timeout (long agent runs)
 
-state_dir: .pr                        # artifacts + checkpoints live here
+# state_dir omitted → default ~/.agentic-dev-loop/runs/<pipeline-hash>/
+# (artifacts + checkpoints live OUTSIDE the sandbox mount)
 max_attempts: 10                      # retries across the whole graph
 agents_dir: sdk_agents                # consumer-owned <name>.agent.md files
 
@@ -112,8 +137,9 @@ steps:
     on_pass: test                     # explicit; omitted → next step in order
 
   - name: test
-    command: .venv/bin/python -m pytest tests/ -q   # mechanical: exit code is the verdict
-    timeout: 600                                     # seconds; SIGKILLs the process group
+    command: .venv-sandbox/bin/python -m pytest tests/ -q -m "not docker"   # sandboxed: exit code is the verdict
+    setup: python -m venv .venv-sandbox && .venv-sandbox/bin/pip install -e ".[dev]"   # provision (network ON, stamp-cached)
+    timeout: 600                                     # seconds
     on_pass: review
     on_fail: {goto: dev, retry: true}
 
@@ -153,8 +179,9 @@ load. Graph-building dispatches on this `kind` (see `StepConfig.kind` in
   `artifact:` + `verdicts:` (verdict-parsed routing). `max_iterations` caps
   the agent's own loop.
 - **`command: <shell>`** — a *command step*: mechanical, never an LLM call.
-  The command runs in the workspace shell; exit 0 passes, anything else
-  (including no exit by `timeout`) fails. `timeout:` is its only extra field.
+  The command runs inside the sandbox (the bind-mounted workspace); exit 0
+  passes, anything else (including no exit by `timeout`) fails. `timeout:` and
+  `setup:` are its only extra fields.
 - **`action: <name>`** — an *action step*: invokes a registered node-shaped
   function `(state, params) -> state update` with the step's `params:`. The
   built-in is `commit`; extensions register more via `registry.add_action`.
@@ -165,8 +192,8 @@ load. Graph-building dispatches on this `kind` (see `StepConfig.kind` in
 
 ### Step semantics
 
-- A `command` step is **mechanical** — the command runs in the workspace
-  shell; exit 0 passes, anything else (including no exit by `timeout`,
+- A `command` step is **mechanical** — the command runs inside the
+  sandbox; exit 0 passes, anything else (including no exit by `timeout`,
   default 600s) fails and follows `on_fail` with the output tail in the
   retry note. The kind is the `command:` key, never the step's name.
 - `artifact` + `verdicts` mark a **verdict step**. `on_pass`/`on_fail` may be
@@ -220,10 +247,10 @@ Loader-selection flow: a loader's flag in argv selects it; flags from two
 loaders in one invocation error out; with no flag, the sole `defaultable`
 loader autoruns (the bundled `ai-dlc` loader autodetects the current unit
 from `aidlc-docs/aidlc-state.md`), otherwise the run proceeds with no
-injected docs and the pipeline `name:` as subject. Unit ids resolve by
-exact directory name or by numeric prefix (`unit-004-preset-management`
-answers to `4`, `004`, `U4`, `U004`, or its full slug); ambiguous ids fail
-loud listing all matches. A selected loader that
+injected docs and the pipeline `name:` as subject. A unit id must name
+its directory exactly (`--aidlc-unit unit-3`); there is no numeric
+fallback or spelling tolerance, and an unmatched slug fails loud listing
+the available directories. A selected loader that
 yields zero docs **fails fast** — context is never silently degraded.
 Duplicate CLI option strings across loaders are a load-time error naming both.
 
@@ -265,7 +292,7 @@ The development lifecycle workflow lives in
 phase details under `aws-aidlc-rule-details/`). Working docs — plans, user
 stories, units of work, state — live in `aidlc-docs/`, created as the
 workflow runs. The bundled `ai-dlc` document loader (see Extension points)
-wires the pipeline's `--ai-dlc-unit` flag to those docs.
+wires the pipeline's `--aidlc-unit` flag to those docs.
 
 OpenCode commands over the workflow: `/epic-status`, `/ticket-details`,
 `/unit-status`, `/update-subtask` (ticket boards over `aidlc-docs/`),

{agentic_dev_loop-0.2.0 → agentic_dev_loop-1.0.0a1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-dev-loop"
-version = "0.2.0"
+version = "1.0.0a1"
 description = "Opinionated LangGraph engine for OpenHands agent pipelines"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -57,3 +57,8 @@ where = ["src"]
 
 [tool.setuptools.package-data]
 agentic_dev_loop = ["py.typed"]
+
+[tool.pytest.ini_options]
+markers = [
+    "docker: real-Docker integration tests (require a running Linux daemon)",
+]

{agentic_dev_loop-0.2.0 → agentic_dev_loop-1.0.0a1}/src/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-1.0.0a1/src/agentic_dev_loop/agents.py

@@ -0,0 +1,125 @@
+"""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`. 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
+    factory (frontmatter tool names resolved against the registry, unknown →
+    ValueError; the markdown body is delivered as the system prompt suffix).
+
+    Tool surface (BR-1): the frontmatter `tools:` list is the exact
+    capability allowlist — every name must resolve to a registered SDK tool.
+    `FinishTool` (done signal) and `ThinkTool` (reasoning scaffold) are added
+    by the SDK as default infra, never part of the allowlist and never
+    removable via `tools:`. There is no regex or default-tools knob.
+
+    Two pipeline policies on top of the SDK's native AgentDefinition loader:
+    the file must exist (fail fast — the SDK's dir loader would silently
+    skip it) and its frontmatter name must match its filename. A file with
+    no frontmatter or no name gets the SDK's stem fallback ("<name>.agent"),
+    which can never match the stem — so both degenerate cases fail the name
+    check."""
+    from openhands.sdk.subagent.registry import agent_definition_to_factory
+    from openhands.sdk.subagent.schema import AgentDefinition
+
+    path = Path(agents_dir) / f"{name}.agent.md"
+    if not path.is_file():
+        raise FileNotFoundError(f"Agent file not found: {path}")
+
+    agent_def = AgentDefinition.load(path)
+
+    stem = path.name.removesuffix(".agent.md")
+    if agent_def.name != stem:
+        raise ValueError(
+            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-0.2.0 → agentic_dev_loop-1.0.0a1}/src/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-0.2.0 → agentic_dev_loop-1.0.0a1}/src/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)