agentic-dev-loop 1.0.0a3__tar.gz → 1.0.0a4__tar.gz

{agentic_dev_loop-1.0.0a3 → agentic_dev_loop-1.0.0a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a3
+Version: 1.0.0a4
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -69,7 +69,7 @@ flowchart LR
 | Feature | What it gives you |
 | --- | --- |
 | **Stage-gated agent loop** | Agents do the work, test stages verify it, and the pipeline only advances when each stage passes its gates — looping back with full context when one fails. |
-| **Kernel-level sandboxing** | Agent work and command stages run isolated from your machine: no network access, no writes outside your workspace. No sandbox available → the run stops instead of degrading. |
+| **Kernel-level sandboxing** | Agent work and command stages run isolated from your machine: [no network access **by default** — authors opt specific stages in](#per-stage-networking), no writes outside your workspace. No sandbox available → the run stops instead of degrading. |
 | **Crash-safe resume** | Interrupt a run at any time and pick it up later — finished stages stay finished, and you resume from exactly where it stopped. |
 | **Live graph visualisation** | Follow every run in the browser: stage status, pass/fail verdicts, retry cycles, and live console output as it happens. |
 | **Extensible** | Plug in your own actions, tools, and document loaders to adapt the loop to your projects. |
@@ -191,10 +191,35 @@ steps:
 | `agent:` / `command:` / `action:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call); actions are registered host-side functions. |
 | `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
-| `env:` / `setup:` (command steps) | Declared env inside the sandbox (fixed safe base + declared vars only); `setup:` provisions the sandbox (network ON, stamp-cached, `--refresh` forces). |
+| `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` provisions the sandbox (command steps, network ON, stamp-cached); `network: true` grants egress to a command or agent step (default off) — see [Per-stage networking](#per-stage-networking). |
 | `isolation:` (optional) | Configures the sandbox — image override, resource caps, `allow_git_mutations`. It can never disable it. |
 | `state_dir` | Defaults to `~/.agentic-dev-loop/runs/<pipeline-hash>/` — artifacts and checkpoints live outside the sandbox mount. |
 
+### Per-stage networking
+
+The sandbox is network-off by default. A step that legitimately needs egress —
+a QA step that curls a service it booted, an agent that must hit an API or
+fetch package metadata mid-conversation — declares it explicitly:
+
+```yaml
+steps:
+  - name: fetch-docs
+    command: curl -fsSL https://example.com/spec.json -o spec.json
+    network: true            # egress for this step only
+```
+
+- **Default off.** Every step runs with `--network none` unless it declares
+  `network: true`. A networked step runs in a second, otherwise-identical
+  sandbox container (`--read-only`, `--cap-drop ALL`, single workspace mount)
+  on the Docker bridge network — the default network-none container is always
+  created too, so no infrastructure work happens mid-run.
+- **Command and agent steps** may declare it. Action steps are host-side and
+  never take it (a load-time error).
+- **Author opt-in is the control.** A networked step gives its agent raw
+  egress for that stage; the default stays network-off everywhere. Reserve it
+  for stages that need it (QA, integration). The residual risk is documented
+  in [docs/setup.md](docs/setup.md).
+
 ## Development environment
 
 ```bash

{agentic_dev_loop-1.0.0a3 → agentic_dev_loop-1.0.0a4}/README.md

@@ -30,7 +30,7 @@ flowchart LR
 | Feature | What it gives you |
 | --- | --- |
 | **Stage-gated agent loop** | Agents do the work, test stages verify it, and the pipeline only advances when each stage passes its gates — looping back with full context when one fails. |
-| **Kernel-level sandboxing** | Agent work and command stages run isolated from your machine: no network access, no writes outside your workspace. No sandbox available → the run stops instead of degrading. |
+| **Kernel-level sandboxing** | Agent work and command stages run isolated from your machine: [no network access **by default** — authors opt specific stages in](#per-stage-networking), no writes outside your workspace. No sandbox available → the run stops instead of degrading. |
 | **Crash-safe resume** | Interrupt a run at any time and pick it up later — finished stages stay finished, and you resume from exactly where it stopped. |
 | **Live graph visualisation** | Follow every run in the browser: stage status, pass/fail verdicts, retry cycles, and live console output as it happens. |
 | **Extensible** | Plug in your own actions, tools, and document loaders to adapt the loop to your projects. |
@@ -152,10 +152,35 @@ steps:
 | `agent:` / `command:` / `action:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call); actions are registered host-side functions. |
 | `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
-| `env:` / `setup:` (command steps) | Declared env inside the sandbox (fixed safe base + declared vars only); `setup:` provisions the sandbox (network ON, stamp-cached, `--refresh` forces). |
+| `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` provisions the sandbox (command steps, network ON, stamp-cached); `network: true` grants egress to a command or agent step (default off) — see [Per-stage networking](#per-stage-networking). |
 | `isolation:` (optional) | Configures the sandbox — image override, resource caps, `allow_git_mutations`. It can never disable it. |
 | `state_dir` | Defaults to `~/.agentic-dev-loop/runs/<pipeline-hash>/` — artifacts and checkpoints live outside the sandbox mount. |
 
+### Per-stage networking
+
+The sandbox is network-off by default. A step that legitimately needs egress —
+a QA step that curls a service it booted, an agent that must hit an API or
+fetch package metadata mid-conversation — declares it explicitly:
+
+```yaml
+steps:
+  - name: fetch-docs
+    command: curl -fsSL https://example.com/spec.json -o spec.json
+    network: true            # egress for this step only
+```
+
+- **Default off.** Every step runs with `--network none` unless it declares
+  `network: true`. A networked step runs in a second, otherwise-identical
+  sandbox container (`--read-only`, `--cap-drop ALL`, single workspace mount)
+  on the Docker bridge network — the default network-none container is always
+  created too, so no infrastructure work happens mid-run.
+- **Command and agent steps** may declare it. Action steps are host-side and
+  never take it (a load-time error).
+- **Author opt-in is the control.** A networked step gives its agent raw
+  egress for that stage; the default stays network-off everywhere. Reserve it
+  for stages that need it (QA, integration). The residual risk is documented
+  in [docs/setup.md](docs/setup.md).
+
 ## Development environment
 
 ```bash

{agentic_dev_loop-1.0.0a3 → agentic_dev_loop-1.0.0a4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-dev-loop"
-version = "1.0.0a3"
+version = "1.0.0a4"
 description = "Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase."
 readme = "README.md"
 requires-python = ">=3.12"

{agentic_dev_loop-1.0.0a3 → agentic_dev_loop-1.0.0a4}/src/agentic_dev_loop/agents.py

@@ -64,12 +64,14 @@ class SandboxTerminalExecutor(ToolExecutor):
 
     def __init__(self, sandbox: "Sandbox", *, workspace: str = "",
                  env: dict[str, str] | None = None,
-                 pipeline: str | None = None, step: str | None = None):
+                 pipeline: str | None = None, step: str | None = None,
+                 network: bool = False):
         self._sandbox = sandbox
         self._workspace = workspace
         self._env = env or {}
         self._pipeline = pipeline
         self._step = step
+        self._network = network
 
     def __call__(self, action, conversation=None):
         from openhands.tools.terminal import TerminalObservation
@@ -90,7 +92,7 @@ class SandboxTerminalExecutor(ToolExecutor):
         request = SandboxExecutionRequest(
             argv=command_argv(action.command), cwd=self._workspace,
             env=self._env, timeout=action.timeout,
-            pipeline=self._pipeline, step=self._step)
+            pipeline=self._pipeline, step=self._step, network=self._network)
         result = self._sandbox.run(request)
         output = result.stdout + result.stderr
         return TerminalObservation.from_text(
@@ -107,7 +109,8 @@ class SandboxTerminalExecutor(ToolExecutor):
 
 def register_sandbox_terminal(sandbox: "Sandbox", *, env: dict[str, str | None] | None = None,
                               workspace: str = "", pipeline: str | None = None,
-                              step: str | None = None) -> None:
+                              step: str | None = None,
+                              network: bool = False) -> 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."""
@@ -120,6 +123,6 @@ def register_sandbox_terminal(sandbox: "Sandbox", *, env: dict[str, str | None]
             conv_state,
             executor=SandboxTerminalExecutor(
                 sandbox, workspace=workspace, env=resolved_env,
-                pipeline=pipeline, step=step))
+                pipeline=pipeline, step=step, network=network))
 
     register_tool("terminal", factory)

{agentic_dev_loop-1.0.0a3 → agentic_dev_loop-1.0.0a4}/src/agentic_dev_loop/config.py

@@ -85,6 +85,7 @@ class StepConfig(BaseModel):
     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
+    network: bool = False  # per-stage egress (command + agent steps; action steps reject)
     on_pass: RouteTarget | None = None
     on_fail: RouteTarget | None = None
 
@@ -142,6 +143,11 @@ class StepConfig(BaseModel):
             raise ValueError(
                 f"step {self.name!r}: 'setup' is only allowed on 'command' steps"
             )
+        if self.network and self.action is not None:
+            raise ValueError(
+                f"step {self.name!r}: 'network' is only allowed on 'agent' or "
+                "'command' steps"
+            )
         return self
 
 

{agentic_dev_loop-1.0.0a3 → agentic_dev_loop-1.0.0a4}/src/agentic_dev_loop/dryrun.py

@@ -73,6 +73,8 @@ def _step_summary(step: StepConfig) -> str:
         parts = [f"action={step.action}"]
         if step.params:
             parts.append(f"params={step.params}")
+    if step.network:
+        parts.append("network=True")
     return ", ".join(parts)
 
 

{agentic_dev_loop-1.0.0a3 → agentic_dev_loop-1.0.0a4}/src/agentic_dev_loop/isolation.py

@@ -85,6 +85,7 @@ class SandboxExecutionRequest:
     cwd: str  # absolute container-side path (== host mount path)
     env: dict[str, str]  # resolved sandbox env (already scrubbed)
     timeout: float | None = None  # seconds; None = no limit
+    network: bool = False  # route to the bridge-network exec container when True
     # Host-side audit metadata (BR-11) — never sent into the container.
     pipeline: str | None = None
     step: str | None = None
@@ -92,6 +93,9 @@ class SandboxExecutionRequest:
     def __post_init__(self) -> None:
         if not self.argv:
             raise ValueError("SandboxExecutionRequest.argv must be non-empty")
+        # Coerce Path-like cwd to str so the invariant "cwd is always a str"
+        # holds at the boundary (audit digest etc. serialize it).
+        object.__setattr__(self, "cwd", os.fspath(self.cwd))
         if not (Path(self.cwd).is_absolute()
                 or PurePosixPath(self.cwd).is_absolute()):
             raise ValueError(f"SandboxExecutionRequest.cwd must be absolute: {self.cwd!r}")
@@ -280,17 +284,27 @@ def host_user_flag() -> str | None:
     return None
 
 
+def exec_container_name(run_id: str, network: bool = False) -> str:
+    """The execution container name for a network mode. Networked requests
+    land in a second, bridge-network container; the default is the always-on
+    network-none container (014 per-stage networking)."""
+    return f"{run_id}-exec-net" if network else f"{run_id}-exec"
+
+
 def docker_create_payload(*, run_id: str, image: str, profile: EffectiveProfile,
-                          workspace: str) -> list[str]:
+                          workspace: str, network: bool = False) -> list[str]:
     """Exact ``docker run -d --rm`` argv for the execution container (§3.3, KD-8).
-    Single mount {workspace} (Q1); --network none, --read-only, --cap-drop ALL;
-    --user host uid:gid (host-owned bind mounts, AE-SBX-009 root cause) with
+    Single mount {workspace} (Q1); ``--network none`` (bridge when ``network``
+    is true — 014 per-stage networking), --read-only, --cap-drop ALL; --user
+    host uid:gid (host-owned bind mounts, AE-SBX-009 root cause) with
     HOME=/tmp (the rootfs is read-only; /tmp is a 1777 tmpfs). ``--rm`` lets the
     daemon auto-remove the container the instant it exits, however it exits
     (D1) — a SIGKILLed CLI never reaches close()."""
     payload = [
-        "docker", "run", "--detach", "--rm", "--name", f"{run_id}-exec",
-        "--network", "none", "--read-only", "--cap-drop", "ALL",
+        "docker", "run", "--detach", "--rm", "--name",
+        exec_container_name(run_id, network),
+        "--network", "bridge" if network else "none",
+        "--read-only", "--cap-drop", "ALL",
         "--memory", profile.memory, "--cpus", str(profile.cpus),
         "--tmpfs", "/tmp", "--tmpfs", "/root",
     ]
@@ -410,20 +424,27 @@ def _request_digest(argv: list[str], cwd: str, env: dict[str, str]) -> str:
 
 
 class DockerBackend(Sandbox):
-    """Docker-based sandbox: one persistent execution container per run
-    (eagerly created + started, Q2), ``docker exec`` per request, destroyed on
-    close(). The injected ``runner`` callable is the unit-test seam."""
+    """Docker-based sandbox: a persistent network-none execution container per
+    run, plus — when any step declares ``network: true`` — a second
+    bridge-network container (eagerly created + started, Q2). ``docker exec``
+    per request routes to the container matching its network mode; both are
+    destroyed on close(). The injected ``runner`` callable is the unit-test
+    seam."""
 
     def __init__(self, *, image: str, workspace: str, iso_state_dir: str,
-                 profile: EffectiveProfile, runner: CommandRunner | None = None):
+                 profile: EffectiveProfile, runner: CommandRunner | None = None,
+                 network: bool = False):
         self._image = image
         self._workspace = workspace
         self._iso_state_dir = Path(iso_state_dir)  # host-only (audit)
         self._profile = profile
         self._runner = runner or _default_runner
         self._run_id = uuid.uuid4().hex
-        self._container = f"{self._run_id}-exec"
+        self._container = exec_container_name(self._run_id, network=False)
+        self._network_container = exec_container_name(self._run_id, network=True)
+        self._network_enabled = network
         self._started = False
+        self._network_started = False
 
     # -- infrastructure (startup) -------------------------------------------
 
@@ -456,16 +477,32 @@ class DockerBackend(Sandbox):
     def create_execution_container(self) -> None:
         """Eager create + start via ``docker run -d --rm`` (Q2, D1) — never
         lazy; ``run -d`` is create + start in one call, so there is no
-        separate ``docker start``."""
+        separate ``docker start``. When any step declares ``network: true`` a
+        second, otherwise-identical bridge-network container is started so no
+        infrastructure work happens mid-run (014 per-stage networking)."""
         payload = docker_create_payload(
             run_id=self._run_id, image=self._image, profile=self._profile,
-            workspace=self._workspace)
+            workspace=self._workspace, network=False)
         res = self._runner.run(payload, timeout=60)
         if res.exit_code != 0:
             raise SandboxError(
                 f"AE-SBX-010: container run failed: "
                 f"{res.stderr.strip() or res.stdout.strip()}")
         self._started = True
+        if not self._network_enabled:
+            return
+        net_payload = docker_create_payload(
+            run_id=self._run_id, image=self._image, profile=self._profile,
+            workspace=self._workspace, network=True)
+        net_res = self._runner.run(net_payload, timeout=60)
+        if net_res.exit_code != 0:
+            # reclaim the already-started network-none container — never leak it.
+            self._runner.run(["docker", "rm", "-f", self._container], timeout=60)
+            self._started = False
+            raise SandboxError(
+                f"AE-SBX-013: networked container run failed: "
+                f"{net_res.stderr.strip() or net_res.stdout.strip()}")
+        self._network_started = True
 
     def provision(self, setup_cmd: str, stamp_key: str, stamp_dir: str,
                   force: bool) -> None:
@@ -488,11 +525,17 @@ class DockerBackend(Sandbox):
 
     def run(self, request: SandboxExecutionRequest) -> SandboxExecutionResult:
         _guard_git(request, self._profile.git_mutations_blocked)
+        container = self._network_container if request.network else self._container
+        if request.network and not self._network_started:
+            raise SandboxError(
+                "AE-SBX-013: networked execution requested but no networked "
+                "container is running — declare `network: true` on the step "
+                "(docs/setup.md §3)")
         start = time.monotonic()
         exec_argv = ["docker", "exec"]
         for key, value in request.env.items():
             exec_argv += ["-e", f"{key}={value}"]
-        exec_argv += ["-w", self._workspace, self._container]
+        exec_argv += ["-w", self._workspace, container]
         runner_timeout = None
         if request.timeout is not None:
             exec_argv += ["/usr/bin/timeout", str(math.ceil(request.timeout))]
@@ -504,7 +547,7 @@ class DockerBackend(Sandbox):
         result = SandboxExecutionResult(
             exit_code=res.exit_code, stdout=res.stdout, stderr=res.stderr,
             duration_seconds=duration, backend="docker", timed_out=timed_out)
-        self._audit(request, result)
+        self._audit(request, result, container)
         if res.exit_code is None:
             raise SandboxError(
                 f"AE-SBX-012: Docker daemon lost mid-run: "
@@ -516,12 +559,18 @@ class DockerBackend(Sandbox):
         daemon may already have auto-removed the container by the time close()
         runs, so a nonzero stop/rm exit code ("no such container") is treated
         as success, never raised (D2)."""
-        if not self._started:
-            return
-        self._runner.run(["docker", "stop", "-t", "5", self._container], timeout=60)
-        # rm -f returns rc != 0 when --rm already removed it — ignore, never raise.
-        self._runner.run(["docker", "rm", "-f", self._container], timeout=60)
-        self._started = False
+        if self._started:
+            self._runner.run(["docker", "stop", "-t", "5", self._container],
+                             timeout=60)
+            # rm -f returns rc != 0 when --rm already removed it — ignore, never raise.
+            self._runner.run(["docker", "rm", "-f", self._container], timeout=60)
+            self._started = False
+        if self._network_started:
+            self._runner.run(["docker", "stop", "-t", "5", self._network_container],
+                             timeout=60)
+            self._runner.run(["docker", "rm", "-f", self._network_container],
+                             timeout=60)
+            self._network_started = False
 
     # -- internal -----------------------------------------------------------
 
@@ -538,14 +587,14 @@ class DockerBackend(Sandbox):
                 "failed; refusing to continue")
 
     def _audit(self, request: SandboxExecutionRequest,
-               result: SandboxExecutionResult) -> None:
+               result: SandboxExecutionResult, container: str) -> None:
         append_audit_record(self._iso_state_dir, {
             "timestamp": datetime.now(timezone.utc).isoformat(),
             "pipeline": request.pipeline or "",
             "step": request.step or "",
             "request_digest": _request_digest(request.argv, request.cwd, request.env),
             "backend": "docker",
-            "container_id": self._container,
+            "container_id": container,
             "exit_code": result.exit_code,
             "timed_out": result.timed_out,
             "duration_seconds": result.duration_seconds,
@@ -710,9 +759,10 @@ def startup_sandbox(cfg: PipelineConfig, *, workspace: Path,
     profile = resolve_effective_profile(cfg.isolation)
     image = resolve_image_ref(profile.image)
     iso_state_dir = isolation_state_dir(cfg)
+    needs_network = any(step.network for step in cfg.steps)
     backend = DockerBackend(
         image=image, workspace=str(workspace), iso_state_dir=str(iso_state_dir),
-        profile=profile, runner=runner)
+        profile=profile, runner=runner, network=needs_network)
     backend.ensure_image()
     backend.create_execution_container()
     if refresh is None:

{agentic_dev_loop-1.0.0a3 → agentic_dev_loop-1.0.0a4}/src/agentic_dev_loop/stages.py

@@ -110,7 +110,8 @@ def run_agent(agent_name: str, message: str, runtime: Runtime,
                 env=step.env if step is not None else None,
                 workspace=str(runtime.workspace),
                 pipeline=runtime.cfg.name,
-                step=step.name if step is not None else None)
+                step=step.name if step is not None else None,
+                network=step.network if step is not None else False)
         agent = load_agent(runtime.agents_dir, agent_name, runtime.llm)
         conv = Conversation(agent=agent, workspace=str(runtime.workspace),
                             max_iteration_per_run=max_iterations)
@@ -151,7 +152,8 @@ def _run_command(command: str, workspace: Path, timeout: float,
                  env: dict[str, str] | None = None,
                  sandbox: Sandbox | None = None,
                  pipeline: str | None = None,
-                 step: str | None = None) -> tuple[int | None, str, bool]:
+                 step: str | None = None,
+                 network: bool = False) -> tuple[int | None, str, bool]:
     """Run a command step in the workspace, capturing combined stdout/stderr.
 
     With a ``Sandbox`` the command routes through the isolation boundary: git
@@ -166,7 +168,7 @@ def _run_command(command: str, workspace: Path, timeout: float,
     if sandbox is not None:
         request = SandboxExecutionRequest(
             argv=command_argv(command), cwd=str(workspace), env=env or {},
-            timeout=timeout, pipeline=pipeline, step=step)
+            timeout=timeout, pipeline=pipeline, step=step, network=network)
         result = sandbox.run(request)
         return result.exit_code, result.stdout + result.stderr, result.timed_out
     if needs_shell(command):
@@ -346,7 +348,8 @@ def make_command_node(runtime: Runtime, step: StepConfig):
         try:
             exit_code, output, timed_out = _run_command(
                 step.command, runtime.workspace, timeout, env,
-                sandbox=sandbox, pipeline=runtime.cfg.name, step=step.name)
+                sandbox=sandbox, pipeline=runtime.cfg.name, step=step.name,
+                network=step.network)
         except Exception:
             print(traceback.format_exc()[-4000:], file=sys.stderr, flush=True)
             return {"failed": True, "failed_step": step.name}

{agentic_dev_loop-1.0.0a3 → agentic_dev_loop-1.0.0a4}/src/agentic_dev_loop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a3
+Version: 1.0.0a4
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -69,7 +69,7 @@ flowchart LR
 | Feature | What it gives you |
 | --- | --- |
 | **Stage-gated agent loop** | Agents do the work, test stages verify it, and the pipeline only advances when each stage passes its gates — looping back with full context when one fails. |
-| **Kernel-level sandboxing** | Agent work and command stages run isolated from your machine: no network access, no writes outside your workspace. No sandbox available → the run stops instead of degrading. |
+| **Kernel-level sandboxing** | Agent work and command stages run isolated from your machine: [no network access **by default** — authors opt specific stages in](#per-stage-networking), no writes outside your workspace. No sandbox available → the run stops instead of degrading. |
 | **Crash-safe resume** | Interrupt a run at any time and pick it up later — finished stages stay finished, and you resume from exactly where it stopped. |
 | **Live graph visualisation** | Follow every run in the browser: stage status, pass/fail verdicts, retry cycles, and live console output as it happens. |
 | **Extensible** | Plug in your own actions, tools, and document loaders to adapt the loop to your projects. |
@@ -191,10 +191,35 @@ steps:
 | `agent:` / `command:` / `action:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call); actions are registered host-side functions. |
 | `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
-| `env:` / `setup:` (command steps) | Declared env inside the sandbox (fixed safe base + declared vars only); `setup:` provisions the sandbox (network ON, stamp-cached, `--refresh` forces). |
+| `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` provisions the sandbox (command steps, network ON, stamp-cached); `network: true` grants egress to a command or agent step (default off) — see [Per-stage networking](#per-stage-networking). |
 | `isolation:` (optional) | Configures the sandbox — image override, resource caps, `allow_git_mutations`. It can never disable it. |
 | `state_dir` | Defaults to `~/.agentic-dev-loop/runs/<pipeline-hash>/` — artifacts and checkpoints live outside the sandbox mount. |
 
+### Per-stage networking
+
+The sandbox is network-off by default. A step that legitimately needs egress —
+a QA step that curls a service it booted, an agent that must hit an API or
+fetch package metadata mid-conversation — declares it explicitly:
+
+```yaml
+steps:
+  - name: fetch-docs
+    command: curl -fsSL https://example.com/spec.json -o spec.json
+    network: true            # egress for this step only
+```
+
+- **Default off.** Every step runs with `--network none` unless it declares
+  `network: true`. A networked step runs in a second, otherwise-identical
+  sandbox container (`--read-only`, `--cap-drop ALL`, single workspace mount)
+  on the Docker bridge network — the default network-none container is always
+  created too, so no infrastructure work happens mid-run.
+- **Command and agent steps** may declare it. Action steps are host-side and
+  never take it (a load-time error).
+- **Author opt-in is the control.** A networked step gives its agent raw
+  egress for that stage; the default stays network-off everywhere. Reserve it
+  for stages that need it (QA, integration). The residual risk is documented
+  in [docs/setup.md](docs/setup.md).
+
 ## Development environment
 
 ```bash

{agentic_dev_loop-1.0.0a3 → agentic_dev_loop-1.0.0a4}/tests/test_agents.py

@@ -144,6 +144,23 @@ class TestSandboxTerminalExecutor:
         obs = ex(TerminalAction(command="sleep 5", timeout=1), None)
         assert obs.timeout is True
 
+    def test_network_reaches_request(self, fake_sandbox, tmp_path):
+        from openhands.tools.terminal import TerminalAction
+
+        from agentic_dev_loop.agents import SandboxTerminalExecutor
+        ex = SandboxTerminalExecutor(fake_sandbox, workspace=str(tmp_path),
+                                     env={}, network=True)
+        ex(TerminalAction(command="curl https://example.com"), None)
+        assert fake_sandbox.requests[0].network is True
+
+    def test_network_defaults_off(self, fake_sandbox, tmp_path):
+        from openhands.tools.terminal import TerminalAction
+
+        from agentic_dev_loop.agents import SandboxTerminalExecutor
+        ex = SandboxTerminalExecutor(fake_sandbox, workspace=str(tmp_path), env={})
+        ex(TerminalAction(command="echo hi"), None)
+        assert fake_sandbox.requests[0].network is False
+
 
 class TestRegisterSandboxTerminal:
     def test_resolves_to_sandbox_executor(self, fake_sandbox, tmp_path):

{agentic_dev_loop-1.0.0a3 → agentic_dev_loop-1.0.0a4}/tests/test_config.py

@@ -460,3 +460,36 @@ class TestStepEnvAndSetup:
         step = _load(tmp_path, data).steps[0]
         rt = type(step).model_validate(step.model_dump())
         assert rt.env == {"A": "x", "B": None}
+
+
+class TestStepNetwork:
+    def test_network_defaults_false(self, tmp_path):
+        step = _load(tmp_path, _base()).steps[0]
+        assert step.network is False
+
+    def test_network_on_command_step(self, tmp_path):
+        data = _base()
+        data["steps"] = [{"name": "fetch", "command": "curl https://example.com",
+                          "network": True, "on_pass": "success"}]
+        assert _load(tmp_path, data).steps[0].network is True
+
+    def test_network_on_agent_step(self, tmp_path):
+        data = _base()
+        data["steps"] = [{"name": "qa", "agent": "qa", "network": True,
+                          "on_pass": "success"}]
+        assert _load(tmp_path, data).steps[0].network is True
+
+    def test_network_on_action_step_rejected(self, tmp_path):
+        data = _base()
+        data["steps"] = [{"name": "commit", "action": "commit", "network": True,
+                          "on_pass": "success"}]
+        with pytest.raises(ValidationError,
+                           match="'network' is only allowed on 'agent' or "
+                                 "'command' steps"):
+            _load(tmp_path, data)
+
+    def test_network_false_on_action_step_allowed(self, tmp_path):
+        data = _base()
+        data["steps"] = [{"name": "commit", "action": "commit", "network": False,
+                          "on_pass": "success"}]
+        assert _load(tmp_path, data).steps[0].network is False

{agentic_dev_loop-1.0.0a3 → agentic_dev_loop-1.0.0a4}/tests/test_dry_run.py

@@ -100,6 +100,17 @@ class TestDryRun:
                      "--no-viz", "--resume", "some-thread-id",
                      "--refresh", "--max-attempts", "5"]) == 0
 
+    def test_network_step_surfaced_in_summary(self, repo, capsys):
+        (repo / "pipeline.yaml").write_text(
+            DRY_RUN_YAML.replace(
+                "    command: .venv-sandbox/bin/python -m pytest tests/ -q\n",
+                "    command: .venv-sandbox/bin/python -m pytest tests/ -q\n"
+                "    network: true\n"))
+        assert main(["pipeline.yaml", "--dry-run", "--plan", "plan.md"]) == 0
+        out = capsys.readouterr().out
+        assert "test [command]" in out
+        assert "network=True" in out
+
 
 class TestDryRunHelp:
     def test_help_documents_flag(self, repo, capsys):

{agentic_dev_loop-1.0.0a3 → agentic_dev_loop-1.0.0a4}/tests/test_isolation.py

@@ -19,9 +19,9 @@ from agentic_dev_loop.isolation import (
     DockerBackend, EffectiveProfile, ProbeResult, SandboxError,
     SandboxExecutionRequest, SandboxExecutionResult, append_audit_record,
     clean_stamps, docker_create_payload, docker_provision_payload,
-    is_git_mutation, probe_docker, read_stamp, resolve_effective_profile,
-    resolve_image_ref, resolve_sandbox_env, select_backend, setup_stamp_key,
-    translate_mount_path, write_stamp,
+    exec_container_name, is_git_mutation, probe_docker, read_stamp,
+    resolve_effective_profile, resolve_image_ref, resolve_sandbox_env,
+    select_backend, setup_stamp_key, translate_mount_path, write_stamp,
 )
 
 
@@ -311,6 +311,30 @@ class TestPayloads:
         assert "--user" not in create
         assert "--user" not in provision
 
+    def test_networked_create_payload(self, tmp_path):
+        """014: `network: true` swaps the network mode AND the container name,
+        but nothing else — the networked container is otherwise identical
+        (read-only, cap-dropped, single mount)."""
+        ws = str(tmp_path)
+        p = docker_create_payload(run_id="r1", image="img",
+                                  profile=self._profile(), workspace=ws,
+                                  network=True)
+        assert "--network" in p and "bridge" in p
+        assert "none" not in p
+        assert "--name" in p and f"{p[p.index('--name') + 1]}" == "r1-exec-net"
+        assert "--read-only" in p
+        assert "--cap-drop" in p and "ALL" in p
+        mounts = [p[i + 1] for i, a in enumerate(p) if a == "-v"]
+        assert mounts == [f"{ws}:{ws}"]
+
+
+class TestExecContainerName:
+    def test_default_is_network_none(self):
+        assert exec_container_name("abc") == "abc-exec"
+
+    def test_networked_suffix(self):
+        assert exec_container_name("abc", network=True) == "abc-exec-net"
+
 
 class TestSelectBackend:
     def test_totality(self):
@@ -374,13 +398,14 @@ class TestResolveImageRef:
 # ---------------------------------------------------------------------------
 
 
-def _backend(tmp_path, runner, *, image="img@sha256:abc", git_blocked=True):
+def _backend(tmp_path, runner, *, image="img@sha256:abc", git_blocked=True,
+              network=False):
     return DockerBackend(
         image=image, workspace=str(tmp_path / "ws"),
         iso_state_dir=str(tmp_path / "state"),
         profile=EffectiveProfile(True, True, True, True, git_blocked,
                                  image, "4g", 2.0),
-        runner=runner)
+        runner=runner, network=network)
 
 
 class TestEnsureImage:
@@ -432,6 +457,30 @@ class TestCreateExecutionContainer:
         assert "--network" in runner.calls[0] and "none" in runner.calls[0]
         assert len(runner.calls) == 1
 
+    def test_networked_second_container_eagerly_created(self, tmp_path):
+        """014: when any step declares network, startup creates BOTH the
+        network-none container and a bridge-network container — zero infra
+        work is deferred to the run phase."""
+        runner = FakeRunner(ok("cid-none"), ok("cid-net"))
+        backend = _backend(tmp_path, runner, network=True)
+        backend.create_execution_container()
+        assert len(runner.calls) == 2
+        none_argv, net_argv = runner.calls
+        assert "--network" in none_argv and "none" in none_argv
+        assert none_argv[none_argv.index("--name") + 1].endswith("-exec")
+        assert "--network" in net_argv and "bridge" in net_argv
+        assert net_argv[net_argv.index("--name") + 1].endswith("-exec-net")
+
+    def test_networked_container_failure_is_loud_and_reclaims_main(self, tmp_path):
+        runner = FakeRunner(ok("cid-none"), fail(125, "network bridge unavailable"))
+        backend = _backend(tmp_path, runner, network=True)
+        with pytest.raises(SandboxError, match="AE-SBX-013"):
+            backend.create_execution_container()
+        assert backend._started is False
+        # the already-started network-none container is reclaimed, never leaked
+        rm = [c for c in runner.calls if c[1] == "rm"]
+        assert rm and backend._container in rm[-1]
+
 
 class TestRun:
     def test_exec_argv_assembly(self, tmp_path):
@@ -457,6 +506,34 @@ class TestRun:
         assert backend._container in runner.calls[-1]
         assert "/usr/bin/timeout" not in runner.calls[-1]
 
+    def test_networked_request_routes_to_network_container(self, tmp_path):
+        """014: an exec routes to the bridge-network container iff the request
+        declares network — the default stays network-none."""
+        runner = FakeRunner(ok(""), ok(""))
+        backend = _backend(tmp_path, runner, network=True)
+        backend._container = "c1"
+        backend._network_container = "c1-net"
+        backend._started = True
+        backend._network_started = True
+        req = SandboxExecutionRequest(argv=["curl", "https://example.com"],
+                                      cwd=str(tmp_path / "ws"), env={},
+                                      network=True)
+        backend.run(req)
+        assert "c1-net" in runner.calls[-1]
+        assert "c1" not in runner.calls[-1]
+
+    def test_networked_request_without_network_container_is_loud(self, tmp_path):
+        runner = FakeRunner()
+        backend = _backend(tmp_path, runner, network=True)
+        backend._container = "c1"
+        backend._started = True  # network container never started
+        req = SandboxExecutionRequest(argv=["curl", "https://example.com"],
+                                      cwd=str(tmp_path / "ws"), env={},
+                                      network=True)
+        with pytest.raises(SandboxError, match="AE-SBX-013"):
+            backend.run(req)
+        assert not runner.calls  # never reached docker exec
+
     def test_exit_124_is_timeout(self, tmp_path):
         runner = FakeRunner(CmdResult(124, "out", ""))
         backend = _backend(tmp_path, runner)
@@ -545,6 +622,18 @@ class TestClose:
         backend.close()  # must not raise
         assert not backend._started
 
+    def test_closes_network_container_too(self, tmp_path):
+        runner = FakeRunner(ok(""), ok(""), ok(""), ok(""))
+        backend = _backend(tmp_path, runner, network=True)
+        backend._container = "c1"
+        backend._network_container = "c1-net"
+        backend._started = True
+        backend._network_started = True
+        backend.close()
+        stopped = [c[-1] for c in runner.calls if c[1] == "stop"]
+        assert stopped == ["c1", "c1-net"]
+        assert not backend._started and not backend._network_started
+
 
 # ---------------------------------------------------------------------------
 # Provision + stamps + audit (real temp dirs)
@@ -649,6 +738,42 @@ class TestStartupSandbox:
         finally:
             sandbox.close()
 
+    def test_network_declaration_starts_second_container(self, tmp_path, monkeypatch):
+        """014: declaring `network: true` on any step makes eager startup
+        create the bridge-network container in addition to the default
+        network-none one — the default (no declaration) stays single-container."""
+        from agentic_dev_loop.config import PipelineConfig
+        from agentic_dev_loop.isolation import startup_sandbox
+
+        ws = tmp_path / "ws"
+        ws.mkdir()
+        cfg = PipelineConfig.model_validate({
+            "name": "p", "llm": {"model": "m", "api_key_env": "K"},
+            "agents_dir": "agents",
+            "steps": [{"name": "dev", "agent": "dev", "on_pass": "test"},
+                      {"name": "test", "command": "make", "network": True,
+                       "on_pass": "success"}],
+            "isolation": {"state_dir": str(tmp_path / "iso-state")},
+        })
+        monkeypatch.setattr("agentic_dev_loop.isolation.shutil.which",
+                            lambda *a: "/usr/bin/docker")
+        monkeypatch.setenv("AGENTIC_DEV_LOOP_DEV_IMAGE", "img:tag")
+        runner = FakeRunner(
+            ok("1.54"),           # probe version
+            ok("linux"),          # probe ostype
+            ok(""),               # image inspect
+            ok(""),               # docker run -d --rm (network-none exec)
+            ok(""),               # docker run -d --rm (networked exec)
+        )
+        sandbox = startup_sandbox(cfg, workspace=ws, runner=runner)
+        try:
+            run_argv = [c for c in runner.calls if c[1] == "run"]
+            assert len(run_argv) == 2
+            assert "--network" in run_argv[0] and "none" in run_argv[0]
+            assert "--network" in run_argv[1] and "bridge" in run_argv[1]
+        finally:
+            sandbox.close()
+
     def test_refresh_forces_provision(self, tmp_path, monkeypatch):
         from agentic_dev_loop.isolation import (setup_stamp_key, startup_sandbox,
                                                 write_stamp)

{agentic_dev_loop-1.0.0a3 → agentic_dev_loop-1.0.0a4}/tests/test_isolation_integration.py

@@ -110,6 +110,60 @@ class TestGitGuardE2E:
         assert not isinstance(result, SandboxError)
 
 
+class TestNetworkedContainerE2E:
+    """014: `network: true` steps run in a second, bridge-network container.
+    The distinguishing observable is the interface set — network-none has only
+    loopback; the bridge container additionally gets a routable eth0. This is
+    deterministic (no external egress required)."""
+
+    @pytest.fixture
+    def networked_backend(self, tmp_path):
+        reason = _docker_available()
+        if reason is not None:
+            pytest.skip(reason)
+        inspect = SubprocessRunner().run(
+            ["docker", "image", "inspect", TEST_IMAGE, "--format", "{{.Id}}"],
+            timeout=30)
+        if inspect.exit_code != 0:
+            pytest.skip(f"integration image {TEST_IMAGE!r} not present locally")
+        ws = tmp_path / "ws"
+        ws.mkdir()
+        profile = resolve_effective_profile(IsolationConfig(image=TEST_IMAGE))
+        b = DockerBackend(image=TEST_IMAGE, workspace=str(ws),
+                          iso_state_dir=str(tmp_path / "state"), profile=profile,
+                          network=True)
+        b.ensure_image()
+        b.create_execution_container()
+        yield b, ws
+        b.close()
+
+    def test_networked_container_has_bridge_interface(self, networked_backend):
+        b, ws = networked_backend
+        req = SandboxExecutionRequest(
+            argv=["python", "-c",
+                  "import socket; print(' '.join(sorted(n for _, n in socket.if_nameindex())))"],
+            cwd=ws,
+            env={"PATH": "/usr/local/bin:/usr/bin:/bin", "HOME": "/tmp"},
+            network=True)
+        result = b.run(req)
+        assert result.exit_code == 0, result.stderr
+        names = result.stdout.split()
+        assert "lo" in names
+        assert any(name != "lo" for name in names)
+
+    def test_default_container_still_network_none(self, networked_backend):
+        b, ws = networked_backend
+        req = SandboxExecutionRequest(
+            argv=["python", "-c",
+                  "print(len(open('/proc/net/route').read().strip().splitlines()[1:]))"],
+            cwd=ws,
+            env={"PATH": "/usr/local/bin:/usr/bin:/bin", "HOME": "/tmp"},
+            network=False)
+        result = b.run(req)
+        assert result.exit_code == 0, result.stderr
+        assert result.stdout.strip() == "0"  # no routes at all — no egress
+
+
 class TestProvisionE2E:
     def test_provision_stamp_skip_refresh(self, backend, tmp_path):
         b, ws = backend

{agentic_dev_loop-1.0.0a3 → agentic_dev_loop-1.0.0a4}/tests/test_isolation_pbt.py

@@ -12,8 +12,9 @@ from hypothesis import assume, given, strategies as st
 
 from agentic_dev_loop.isolation import (
     EffectiveProfile, ProbeResult, SandboxExecutionRequest, SandboxExecutionResult,
-    docker_create_payload, is_git_mutation, resolve_effective_profile,
-    resolve_sandbox_env, select_backend, setup_stamp_key, translate_mount_path,
+    docker_create_payload, exec_container_name, is_git_mutation,
+    resolve_effective_profile, resolve_sandbox_env, select_backend,
+    setup_stamp_key, translate_mount_path,
 )
 
 profiles = st.builds(
@@ -69,6 +70,27 @@ class TestResolveSandboxEnvScrub:
         assert set(env) == {"PATH", "HOME", "LANG", "LC_ALL", "TERM"}
 
 
+class TestNetworkModePayload:
+    @given(profile=profiles, workspace=st.text(min_size=1), run_id=st.text(min_size=1))
+    def test_default_is_network_none(self, profile, workspace, run_id):
+        p = docker_create_payload(run_id=run_id, image="img", profile=profile,
+                                  workspace=workspace, network=False)
+        assert "--network" in p and "none" in p
+        assert "--name" in p and p[p.index("--name") + 1] == exec_container_name(run_id)
+
+    @given(profile=profiles, workspace=st.text(min_size=1), run_id=st.text(min_size=1))
+    def test_network_true_swaps_mode_and_name(self, profile, workspace, run_id):
+        p = docker_create_payload(run_id=run_id, image="img", profile=profile,
+                                  workspace=workspace, network=True)
+        assert "--network" in p and "bridge" in p
+        assert "--name" in p and p[p.index("--name") + 1] == exec_container_name(
+            run_id, network=True)
+        # the rest of the hardening invariants still hold for the networked container
+        assert "--read-only" in p and "--cap-drop" in p and "ALL" in p
+        mounts = [p[i + 1] for i, a in enumerate(p) if a == "-v"]
+        assert mounts == [f"{workspace}:{workspace}"]
+
+
 class TestSetupStampKey:
     @given(cmd=st.text(), lockfiles=st.dictionaries(st.text(min_size=1), st.text()))
     def test_stable(self, cmd, lockfiles):

{agentic_dev_loop-1.0.0a3 → agentic_dev_loop-1.0.0a4}/tests/test_stages.py

@@ -511,6 +511,16 @@ class TestSandboxedCommandNode:
         assert fake_sandbox.requests[0].env["MY_VAR"] == "declared"
         assert fake_sandbox.requests[0].env["PATH"].startswith("/usr/local/bin")
 
+    def test_network_defaults_off(self, runtime, fake_sandbox):
+        node = self._node(runtime, "echo routed")
+        node(make_state())
+        assert fake_sandbox.requests[0].network is False
+
+    def test_network_true_reaches_request(self, runtime, fake_sandbox):
+        node = self._node(runtime, "curl https://example.com", network=True)
+        node(make_state())
+        assert fake_sandbox.requests[0].network is True
+
     def test_git_mutation_hard_fails_not_retried(self, runtime, fake_sandbox):
         cfg = make_cfg([
             {"name": "dev", "agent": "dev", "on_pass": "test"},