agentic-dev-loop 1.0.0a23__tar.gz → 1.0.0a25__tar.gz

{agentic_dev_loop-1.0.0a23/src/agentic_dev_loop.egg-info → agentic_dev_loop-1.0.0a25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a23
+Version: 1.0.0a25
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -79,8 +79,10 @@ flowchart LR
 
 The fixed policies *are* the product: fail fast on missing config/secrets, no
 silent fallbacks, verdicts only from artifacts, bounded retries, per-attempt
-artifact hygiene, a single clean-worktree-gated commit point, and no default
-LLM timeout (agent runs are long).
+artifact hygiene, a single clean-worktree-gated commit point, no default LLM
+timeout (agent runs are long), and fail fast on a broken sandbox - daemon-side
+exec failures are classified and stop the run without an agent retry loop,
+while a startup reaper reclaims containers leaked by a crashed run.
 
 ## Installation
 
@@ -221,6 +223,7 @@ steps:
 | `deps_policy` | `locked` (default) or `open`. `locked` = the human-owned lockfile is the source of truth and the agent may not add dependencies; `open` = the bootstrap protocol (the agent may add exact-pinned manifest entries). See [Dependency policy](#dependency-policy-locked-by-default). |
 | `lockfiles` | The pipeline's declared lockfile names (workspace-relative), injected into agent context and named by the missing-dependency fail-fast. Required (non-empty) when `deps_policy: locked` - a `locked` pipeline with no lockfiles fails fast at load. |
 | `caches:` / `sync_excludes:` | Top-level run-wide lists. `caches:` names repo-relative toolchain cache dirs bind-mounted rw from the real workspace (auto-created if missing); `sync_excludes:` names scratch paths skipped from both the export copy and sync-back (wildcard `*` spans separators, so `**/bin/**` matches a `/bin/` segment at any depth). Both default to `[]`. See [docs/setup.md](docs/setup.md). |
+| `merge_on_conflict:` | Top-level run-wide list of append-style logs (same path vocabulary as `sync_excludes:`, default `[]`). A concurrent host edit to a listed path is union-merged instead of raising: the host file wins and the sandbox's export-only lines are appended in order; both sides converge and the run continues. See [docs/setup.md](docs/setup.md). |
 
 ### Secrets (`secrets:`) - refs only, never values
 
@@ -305,6 +308,137 @@ steps:
   everywhere. Reserve it for stages that need it (QA, integration). The
   residual risks are documented in [docs/setup.md](docs/setup.md).
 
+### Sync-back conflicts (host edits during a run)
+
+Only declared-`rw` paths sync back to the real repo after a step. If the host
+also edits a declared-`rw` path while the step is running, sync-back prints
+`[isolation] sync-back conflict: ...` and raises `AE-SBX-016`; the host's
+version wins, the baseline is re-snapshotted, and the next step (even
+`echo hello`) runs clean instead of re-raising forever. For append-style logs
+edited by both sides (an audit log, say), declare them in the top-level
+`merge_on_conflict:` list: those paths are union-merged - the host keeps its
+lines, the sandbox's new lines are appended in order, both sides converge, and
+the run continues with `[isolation] merged concurrent edits: ...` on the
+console.
+
+
+## Authoring a loop for your own repo
+
+A consumer repo needs two things written by hand - a pipeline file and the
+agent files it names - both committed before the first run (the host-boundary
+check refuses dirty tooling, and the `commit` step never commits it). Two
+reference layouts ship today: this repo dogfoods the engine on itself
+(python + pytest, no frontend, CLI-only qa), and the consumer repo carries
+the wider shape (.NET + npm frontend + a networked browser-probing qa step).
+
+```
+<repo>/agentic-dev-loop/pipeline.yaml
+<repo>/agentic-dev-loop/sdk_agents/dev.agent.md
+<repo>/agentic-dev-loop/sdk_agents/review.agent.md
+<repo>/agentic-dev-loop/sdk_agents/qa.agent.md
+```
+
+### The agent files
+
+Each `sdk_agents/<name>.agent.md` is a markdown prompt plus YAML frontmatter:
+`name` matches a step's `agent:` value; `tools` lists the tool names the step
+may use (`terminal` always; a repo can add more via extensions, e.g.
+`figma`).
+
+```markdown
+---
+name: review                 # matches a step's `agent:` value
+tools: [terminal]
+---
+# Review Agent
+## WORKFLOW                   # numbered steps
+## RULES                      # absolute never/always rules
+## SANDBOX NOTES              # the sandbox truth for THIS step
+## OUTPUT                     # the verdict contract
+```
+
+Three roles, three contracts:
+
+| Role | Verdict contract | Typical sandbox |
+| --- | --- | --- |
+| dev | none - the final response is captured as the `produces:` summary | rw mount, offline |
+| review | `VERDICT: APPROVED` / `VERDICT: NEEDS CHANGES` on the first content line | ro mount, offline |
+| qa | `VERDICT: PASS` / `VERDICT: FAIL`; map `unverifiable: UNVERIFIABLE` if you want a third way | shaped by the repo: rw + network + `class: browser` when it boots servers and drives a browser (the consumer repo); ro + offline when it probes the CLI only (this repo) |
+
+The conventions that make a good agent file - each one below exists because
+an agent burned budget learning it mid-run:
+
+- **State the sandbox truth in the prompt.** Every agent file carries a
+  `SANDBOX NOTES` section naming exactly what its step allows: mounts ro or
+  rw, network on or off, and which gates have already run. Never make the
+  agent discover it.
+- **Gates are the source of truth - cite the record, never re-run.** A
+  command the test gate, the editor-tests gate, or the dev summary reports
+  as run is coverage evidence, cited as `covered by <test>` or the gate
+  record. Review and qa never re-run builds or suites; qa maps every
+  acceptance criterion to existing coverage and probes only the remainder.
+- **dev enumerates its impossible set and stops at it.** The dev prompt
+  says: stop the moment your next step needs a command this sandbox cannot
+  run, and lists the set (package-manager fetches after a new pin, npm or
+  vitest offline, playwright downloads, database-category tests), one
+  attempt per command. That keeps the productive edit/build/test loop and
+  kills doomed retries. The set is toolchain-specific - write yours; this
+  repo's is a single bullet (no package managers), the consumer repo's is
+  four.
+- **Failure output returns as *Previous attempt feedback*.** Steps route
+  `on_fail: { goto: dev, retry: true }`, so gate failure output lands in
+  the dev agent's next context; the dev prompt makes every listed issue a
+  required fix.
+- **No git mutations, ever.** The `commit` step is the single commit point.
+- **`max_iterations` per role.** qa is bounded probing (60 in both
+  reference repos); dev is open-ended construction and stays uncapped
+  (the engine default).
+
+### The pipeline file
+
+The full field reference is above; this is the stage lineup and what to
+adapt per repo.
+
+| Stage | Kind | Typical shape | Why |
+| --- | --- | --- | --- |
+| dev | agent | rw, offline | does the work; edits are untracked |
+| restore | command | network + `presets: [package-registries]` | fetches what dev pinned (`deps_policy: open`) or the locked install; also the audit escalation point |
+| test | command | offline is fine (warm cache) | exit code is the verdict; the source of truth |
+| editor-tests | command | network + `presets: [package-registries]` | frontend suites that cannot run offline (`npm ci && npm test`). A separate step, never merged into `test`: the step name is the failure diagnosis, its timeout does not contend the backend suite's, and a retry re-runs only its own chain |
+| conformance | command | network + `presets: [package-registries]` | repo-specific fitness checks (the consumer repo: jscpd + DDD rules) |
+| review | agent | ro, offline | static conformance verdict |
+| qa | agent | per repo (see table above) | live-behaviour probes; `max_iterations: 60`; inject secrets only if the probes need them |
+| commit | action | host-side | the single commit point |
+
+Adaptation checklist for a new repo:
+
+1. `llm:` - model, `base_url`, `api_key_env`.
+2. `isolation:` - toolchain image override (the consumer repo pins a
+   toolchain image by digest) and `seccomp_profile: bundled:chromium-userns`
+   only if a stage runs Chromium.
+3. `caches:` - toolchain cache dirs as rw bind-mounts shared across runs
+   (`.nuget-packages`, `qa/node_modules`, `qa/.browsers`,
+   `frontend-editor/node_modules`); caches are never synced back.
+4. `sync_excludes:` - build output trees (`**/bin/**`, `**/obj/**`).
+5. `secrets:` - refs only, resolved from host env; each step opts in to the
+   refs it needs.
+6. `egress:` - `presets: [package-registries]` for fetch steps;
+   `class: browser` (broad-but-logged) for browser-tier qa only.
+7. `deps_policy:` and `lockfiles:` - see
+   [Dependency policy](#dependency-policy-locked-by-default).
+8. The dev prompt's impossible set - write it for your toolchain.
+9. `additional_files:` - the repo's `AGENTS.md`, coding standards, design
+   docs: shared context for every agent step.
+
+Validate before the first run - dry-run loads and prints the resolved plan
+with no LLM, no Docker, no state writes:
+
+```bash
+agentic-dev-loop agentic-dev-loop/pipeline.yaml --dry-run
+```
+
+Then commit the tooling and run for real.
+
 ## Dependency policy (locked by default)
 
 The supply-chain dial is a pipeline-level `deps_policy:` field, **locked by

{agentic_dev_loop-1.0.0a23 → agentic_dev_loop-1.0.0a25}/README.md

@@ -37,8 +37,10 @@ flowchart LR
 
 The fixed policies *are* the product: fail fast on missing config/secrets, no
 silent fallbacks, verdicts only from artifacts, bounded retries, per-attempt
-artifact hygiene, a single clean-worktree-gated commit point, and no default
-LLM timeout (agent runs are long).
+artifact hygiene, a single clean-worktree-gated commit point, no default LLM
+timeout (agent runs are long), and fail fast on a broken sandbox - daemon-side
+exec failures are classified and stop the run without an agent retry loop,
+while a startup reaper reclaims containers leaked by a crashed run.
 
 ## Installation
 
@@ -179,6 +181,7 @@ steps:
 | `deps_policy` | `locked` (default) or `open`. `locked` = the human-owned lockfile is the source of truth and the agent may not add dependencies; `open` = the bootstrap protocol (the agent may add exact-pinned manifest entries). See [Dependency policy](#dependency-policy-locked-by-default). |
 | `lockfiles` | The pipeline's declared lockfile names (workspace-relative), injected into agent context and named by the missing-dependency fail-fast. Required (non-empty) when `deps_policy: locked` - a `locked` pipeline with no lockfiles fails fast at load. |
 | `caches:` / `sync_excludes:` | Top-level run-wide lists. `caches:` names repo-relative toolchain cache dirs bind-mounted rw from the real workspace (auto-created if missing); `sync_excludes:` names scratch paths skipped from both the export copy and sync-back (wildcard `*` spans separators, so `**/bin/**` matches a `/bin/` segment at any depth). Both default to `[]`. See [docs/setup.md](docs/setup.md). |
+| `merge_on_conflict:` | Top-level run-wide list of append-style logs (same path vocabulary as `sync_excludes:`, default `[]`). A concurrent host edit to a listed path is union-merged instead of raising: the host file wins and the sandbox's export-only lines are appended in order; both sides converge and the run continues. See [docs/setup.md](docs/setup.md). |
 
 ### Secrets (`secrets:`) - refs only, never values
 
@@ -263,6 +266,137 @@ steps:
   everywhere. Reserve it for stages that need it (QA, integration). The
   residual risks are documented in [docs/setup.md](docs/setup.md).
 
+### Sync-back conflicts (host edits during a run)
+
+Only declared-`rw` paths sync back to the real repo after a step. If the host
+also edits a declared-`rw` path while the step is running, sync-back prints
+`[isolation] sync-back conflict: ...` and raises `AE-SBX-016`; the host's
+version wins, the baseline is re-snapshotted, and the next step (even
+`echo hello`) runs clean instead of re-raising forever. For append-style logs
+edited by both sides (an audit log, say), declare them in the top-level
+`merge_on_conflict:` list: those paths are union-merged - the host keeps its
+lines, the sandbox's new lines are appended in order, both sides converge, and
+the run continues with `[isolation] merged concurrent edits: ...` on the
+console.
+
+
+## Authoring a loop for your own repo
+
+A consumer repo needs two things written by hand - a pipeline file and the
+agent files it names - both committed before the first run (the host-boundary
+check refuses dirty tooling, and the `commit` step never commits it). Two
+reference layouts ship today: this repo dogfoods the engine on itself
+(python + pytest, no frontend, CLI-only qa), and the consumer repo carries
+the wider shape (.NET + npm frontend + a networked browser-probing qa step).
+
+```
+<repo>/agentic-dev-loop/pipeline.yaml
+<repo>/agentic-dev-loop/sdk_agents/dev.agent.md
+<repo>/agentic-dev-loop/sdk_agents/review.agent.md
+<repo>/agentic-dev-loop/sdk_agents/qa.agent.md
+```
+
+### The agent files
+
+Each `sdk_agents/<name>.agent.md` is a markdown prompt plus YAML frontmatter:
+`name` matches a step's `agent:` value; `tools` lists the tool names the step
+may use (`terminal` always; a repo can add more via extensions, e.g.
+`figma`).
+
+```markdown
+---
+name: review                 # matches a step's `agent:` value
+tools: [terminal]
+---
+# Review Agent
+## WORKFLOW                   # numbered steps
+## RULES                      # absolute never/always rules
+## SANDBOX NOTES              # the sandbox truth for THIS step
+## OUTPUT                     # the verdict contract
+```
+
+Three roles, three contracts:
+
+| Role | Verdict contract | Typical sandbox |
+| --- | --- | --- |
+| dev | none - the final response is captured as the `produces:` summary | rw mount, offline |
+| review | `VERDICT: APPROVED` / `VERDICT: NEEDS CHANGES` on the first content line | ro mount, offline |
+| qa | `VERDICT: PASS` / `VERDICT: FAIL`; map `unverifiable: UNVERIFIABLE` if you want a third way | shaped by the repo: rw + network + `class: browser` when it boots servers and drives a browser (the consumer repo); ro + offline when it probes the CLI only (this repo) |
+
+The conventions that make a good agent file - each one below exists because
+an agent burned budget learning it mid-run:
+
+- **State the sandbox truth in the prompt.** Every agent file carries a
+  `SANDBOX NOTES` section naming exactly what its step allows: mounts ro or
+  rw, network on or off, and which gates have already run. Never make the
+  agent discover it.
+- **Gates are the source of truth - cite the record, never re-run.** A
+  command the test gate, the editor-tests gate, or the dev summary reports
+  as run is coverage evidence, cited as `covered by <test>` or the gate
+  record. Review and qa never re-run builds or suites; qa maps every
+  acceptance criterion to existing coverage and probes only the remainder.
+- **dev enumerates its impossible set and stops at it.** The dev prompt
+  says: stop the moment your next step needs a command this sandbox cannot
+  run, and lists the set (package-manager fetches after a new pin, npm or
+  vitest offline, playwright downloads, database-category tests), one
+  attempt per command. That keeps the productive edit/build/test loop and
+  kills doomed retries. The set is toolchain-specific - write yours; this
+  repo's is a single bullet (no package managers), the consumer repo's is
+  four.
+- **Failure output returns as *Previous attempt feedback*.** Steps route
+  `on_fail: { goto: dev, retry: true }`, so gate failure output lands in
+  the dev agent's next context; the dev prompt makes every listed issue a
+  required fix.
+- **No git mutations, ever.** The `commit` step is the single commit point.
+- **`max_iterations` per role.** qa is bounded probing (60 in both
+  reference repos); dev is open-ended construction and stays uncapped
+  (the engine default).
+
+### The pipeline file
+
+The full field reference is above; this is the stage lineup and what to
+adapt per repo.
+
+| Stage | Kind | Typical shape | Why |
+| --- | --- | --- | --- |
+| dev | agent | rw, offline | does the work; edits are untracked |
+| restore | command | network + `presets: [package-registries]` | fetches what dev pinned (`deps_policy: open`) or the locked install; also the audit escalation point |
+| test | command | offline is fine (warm cache) | exit code is the verdict; the source of truth |
+| editor-tests | command | network + `presets: [package-registries]` | frontend suites that cannot run offline (`npm ci && npm test`). A separate step, never merged into `test`: the step name is the failure diagnosis, its timeout does not contend the backend suite's, and a retry re-runs only its own chain |
+| conformance | command | network + `presets: [package-registries]` | repo-specific fitness checks (the consumer repo: jscpd + DDD rules) |
+| review | agent | ro, offline | static conformance verdict |
+| qa | agent | per repo (see table above) | live-behaviour probes; `max_iterations: 60`; inject secrets only if the probes need them |
+| commit | action | host-side | the single commit point |
+
+Adaptation checklist for a new repo:
+
+1. `llm:` - model, `base_url`, `api_key_env`.
+2. `isolation:` - toolchain image override (the consumer repo pins a
+   toolchain image by digest) and `seccomp_profile: bundled:chromium-userns`
+   only if a stage runs Chromium.
+3. `caches:` - toolchain cache dirs as rw bind-mounts shared across runs
+   (`.nuget-packages`, `qa/node_modules`, `qa/.browsers`,
+   `frontend-editor/node_modules`); caches are never synced back.
+4. `sync_excludes:` - build output trees (`**/bin/**`, `**/obj/**`).
+5. `secrets:` - refs only, resolved from host env; each step opts in to the
+   refs it needs.
+6. `egress:` - `presets: [package-registries]` for fetch steps;
+   `class: browser` (broad-but-logged) for browser-tier qa only.
+7. `deps_policy:` and `lockfiles:` - see
+   [Dependency policy](#dependency-policy-locked-by-default).
+8. The dev prompt's impossible set - write it for your toolchain.
+9. `additional_files:` - the repo's `AGENTS.md`, coding standards, design
+   docs: shared context for every agent step.
+
+Validate before the first run - dry-run loads and prints the resolved plan
+with no LLM, no Docker, no state writes:
+
+```bash
+agentic-dev-loop agentic-dev-loop/pipeline.yaml --dry-run
+```
+
+Then commit the tooling and run for real.
+
 ## Dependency policy (locked by default)
 
 The supply-chain dial is a pipeline-level `deps_policy:` field, **locked by

{agentic_dev_loop-1.0.0a23 → agentic_dev_loop-1.0.0a25}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-dev-loop"
-version = "1.0.0a23"
+version = "1.0.0a25"
 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.0a23 → agentic_dev_loop-1.0.0a25}/src/agentic_dev_loop/core/config.py

@@ -446,6 +446,10 @@ class PipelineConfig(BaseModel):
     # "no sync-back excludes".
     caches: list[str] = []
     sync_excludes: list[str] = []
+    # 029: append-style logs that sync-back union-merges on a concurrent
+    # edit instead of raising. Same declared-path vocabulary as
+    # ``sync_excludes:``.
+    merge_on_conflict: list[str] = []
 
     @field_validator("deps_policy")
     @classmethod
@@ -460,7 +464,7 @@ class PipelineConfig(BaseModel):
     def _coerce_lockfiles(cls, v: Any) -> Any:
         return [v] if isinstance(v, str) else v
 
-    @field_validator("caches", "sync_excludes", mode="before")
+    @field_validator("caches", "sync_excludes", "merge_on_conflict", mode="before")
     @classmethod
     def _coerce_declared_paths(cls, v: Any) -> Any:
         return [v] if isinstance(v, str) else v
@@ -475,6 +479,11 @@ class PipelineConfig(BaseModel):
     def _valid_sync_excludes(cls, v: list[str]) -> list[str]:
         return [_validate_declared_path(c, allow_wildcards=True) for c in v]
 
+    @field_validator("merge_on_conflict")
+    @classmethod
+    def _valid_merge_on_conflict(cls, v: list[str]) -> list[str]:
+        return [_validate_declared_path(m, allow_wildcards=True) for m in v]
+
     @field_validator("secrets", mode="before")
     @classmethod
     def _reject_value_shaped_refs(cls, v: Any) -> Any:
@@ -579,6 +588,32 @@ class PipelineConfig(BaseModel):
                         f"{('/'.join(cp))!r}")
         return self
 
+    @model_validator(mode="after")
+    def _merge_avoid_excludes_and_caches(self) -> "PipelineConfig":
+        """029: a literal merge_on_conflict entry equal to or under a literal
+        sync_excludes entry or a literal caches entry is redundant - excluded
+        and cached paths never sync, so they can never conflict. Wildcard
+        merge entries are skipped (their overlap is fuzzy, 028 parity)."""
+        cache_parts = [relative_parts(c) for c in self.caches if relative_parts(c)]
+        exclude_parts = [relative_parts(e) for e in self.sync_excludes
+                         if not _has_wildcards(e) and relative_parts(e)]
+        for merge in self.merge_on_conflict:
+            if _has_wildcards(merge):
+                continue
+            mp = relative_parts(merge)
+            for cp in cache_parts:
+                if mp[:len(cp)] == cp:
+                    raise ValueError(
+                        f"merge_on_conflict entry {merge!r} is redundant: it is "
+                        f"already excluded as declared cache {('/'.join(cp))!r}")
+            for ep in exclude_parts:
+                if mp[:len(ep)] == ep:
+                    raise ValueError(
+                        f"merge_on_conflict entry {merge!r} is redundant: it is "
+                        f"already excluded by sync_excludes entry "
+                        f"{('/'.join(ep))!r}")
+        return self
+
     @model_validator(mode="after")
     def _sandbox_venv_not_declared_cache(self) -> "PipelineConfig":
         """028: the sandbox venv is engine infrastructure, never author data.

{agentic_dev_loop-1.0.0a23 → agentic_dev_loop-1.0.0a25}/src/agentic_dev_loop/engine/agents.py

@@ -15,7 +15,8 @@ from openhands.tools.file_editor import FileEditorTool  # noqa: F401 - registers
 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
+from .isolation import (SandboxError, SandboxExecutionRequest, command_argv,
+                        resolve_sandbox_env)
 
 if TYPE_CHECKING:
     from openhands.sdk.agent.agent import Agent
@@ -96,7 +97,21 @@ class SandboxTerminalExecutor(ToolExecutor):
             env=self._env, timeout=action.timeout,
             pipeline=self._pipeline, step=self._step, network=self._network,
             mount_set=self._mount_set, egress_policy=self._egress_policy)
-        result = self._sandbox.run(request)
+        try:
+            result = self._sandbox.run(request)
+        except SandboxError as exc:
+            # 030, D3: a sticky infra failure proves the exec path is dead, so
+            # tell the SDK run loop to break this step instead of flapping to
+            # max_iterations. See COMPAT-SHIMS.md for the reliance + canary.
+            if (conversation is not None
+                    and exc is self._sandbox.infra_error):
+                from openhands.sdk.conversation.state import (
+                    ConversationExecutionStatus,
+                )
+                conversation.state.execution_status = (
+                    ConversationExecutionStatus.STUCK
+                )
+            raise
         output = result.stdout + result.stderr
         return TerminalObservation.from_text(
             output, is_error=not result.succeeded and not result.is_timeout,