agentic-dev-loop 1.0.0a30__tar.gz → 1.0.0a31__tar.gz

{agentic_dev_loop-1.0.0a30/src/agentic_dev_loop.egg-info → agentic_dev_loop-1.0.0a31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a30
+Version: 1.0.0a31
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -541,6 +541,28 @@ dotnet restore --locked-mode      # installs exactly packages.lock.json
 Keep the lockfile tracked (do not gitignore it) and re-run the locked restore
 to prove it holds from a clean cache before setting `deps_policy: locked`.
 
+## Agent-facing error guide
+
+The engine bundles an always-on guide for the engine error codes an agent
+can actually observe while running terminal commands. The guide lives at
+`src/agentic_dev_loop/engine/agent_error_guide.md`, versioned with the engine
+code that emits the codes, and is injected into every agent step's task
+context at assembly time. There is no opt-in and no opt-out in v1; command
+and action steps never receive it because no agent reads them.
+
+Each agent-visible code has exactly one table row, shaped like this:
+
+| Code | Meaning | Correct response |
+| --- | --- | --- |
+| AE-SBX-016 | The loop refused to sync an edit because the real repo changed underneath on a path this workspace also touches; the file in this workspace is stale and its edits will not be applied. | The command is not the problem: retry once, do not edit or work around the named path, and mention the code in your final response if it persists. |
+
+The guide is consumer-agnostic: it explains the general mechanism and never
+names a consumer or a consumer domain rule ID. If an ID must appear inside a
+quoted engine message, the placeholder `<domain-rule-id>` is used. Any engine
+change that adds or changes an agent-visible error code must update the guide
+in the same commit; the test suite enforces the pairing by parsing the
+agent-visible `SandboxError` raise sites against the bundled table.
+
 ## Host boundary (security model)
 
 The orchestrator, tool layer, and the `commit` action run in the **host

{agentic_dev_loop-1.0.0a30 → agentic_dev_loop-1.0.0a31}/README.md

@@ -499,6 +499,28 @@ dotnet restore --locked-mode      # installs exactly packages.lock.json
 Keep the lockfile tracked (do not gitignore it) and re-run the locked restore
 to prove it holds from a clean cache before setting `deps_policy: locked`.
 
+## Agent-facing error guide
+
+The engine bundles an always-on guide for the engine error codes an agent
+can actually observe while running terminal commands. The guide lives at
+`src/agentic_dev_loop/engine/agent_error_guide.md`, versioned with the engine
+code that emits the codes, and is injected into every agent step's task
+context at assembly time. There is no opt-in and no opt-out in v1; command
+and action steps never receive it because no agent reads them.
+
+Each agent-visible code has exactly one table row, shaped like this:
+
+| Code | Meaning | Correct response |
+| --- | --- | --- |
+| AE-SBX-016 | The loop refused to sync an edit because the real repo changed underneath on a path this workspace also touches; the file in this workspace is stale and its edits will not be applied. | The command is not the problem: retry once, do not edit or work around the named path, and mention the code in your final response if it persists. |
+
+The guide is consumer-agnostic: it explains the general mechanism and never
+names a consumer or a consumer domain rule ID. If an ID must appear inside a
+quoted engine message, the placeholder `<domain-rule-id>` is used. Any engine
+change that adds or changes an agent-visible error code must update the guide
+in the same commit; the test suite enforces the pairing by parsing the
+agent-visible `SandboxError` raise sites against the bundled table.
+
 ## Host boundary (security model)
 
 The orchestrator, tool layer, and the `commit` action run in the **host

{agentic_dev_loop-1.0.0a30 → agentic_dev_loop-1.0.0a31}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-dev-loop"
-version = "1.0.0a30"
+version = "1.0.0a31"
 description = "Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -68,6 +68,7 @@ where = ["src"]
 
 [tool.setuptools.package-data]
 agentic_dev_loop = ["py.typed"]
+"agentic_dev_loop.engine" = ["*.md"]
 "agentic_dev_loop.engine.seccomp" = ["*.json"]
 
 [tool.pytest.ini_options]

agentic_dev_loop-1.0.0a31/src/agentic_dev_loop/engine/agent_error_guide.md

@@ -0,0 +1,6 @@
+| Code | Meaning | Correct response |
+| --- | --- | --- |
+| AE-SBX-008 | The sandbox refused a git mutation command. Only the single commit step may change git state; agents never commit, branch, tag, or otherwise mutate git. | Do not run the command or any git mutation again. Continue without touching git and leave committing to the commit step. |
+| AE-SBX-010 | The sandbox could not create the execution container for the command, so the command did not run. | The command is not the problem: retry once; if it persists, mention the code in your final response and stop. |
+| AE-SBX-016 | The loop refused to sync an edit because the real repo changed underneath on a path this workspace also touches; the file in this workspace is stale and its edits will not be applied. | The command is not the problem: retry once, do not edit or work around the named path, and mention the code in your final response if it persists. |
+| AE-SBX-018 | The network egress proxy for this step stopped, so the sandbox refused the command rather than run without enforcement. | The command is not the problem: do not retry it, mention the code in your final response, and stop. |

agentic_dev_loop-1.0.0a31/src/agentic_dev_loop/engine/agent_error_guide.py

@@ -0,0 +1,26 @@
+"""Bundled agent-facing error guide (034).
+
+The guide table is an engine-owned resource, versioned with the engine so the
+codes and their guidance cannot drift. Every agent step's task context gets
+the table injected at assembly time; command and action steps never do (no
+agent reads them).
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+
+GUIDE_RESOURCE = "agent_error_guide.md"
+GUIDE_HEADING = "Agent-facing error guide"
+
+
+def load_guide() -> str:
+    """The bundled guide table text."""
+    return (files("agentic_dev_loop.engine")
+            .joinpath(GUIDE_RESOURCE)
+            .read_text(encoding="utf-8"))
+
+
+def guide_section() -> str:
+    """The guide block injected into an agent step's task context."""
+    return f"## {GUIDE_HEADING}\n\n{load_guide()}"

{agentic_dev_loop-1.0.0a30 → agentic_dev_loop-1.0.0a31}/src/agentic_dev_loop/engine/stages.py

@@ -32,6 +32,7 @@ from typing import TYPE_CHECKING
 from langgraph.graph import END
 from openhands.sdk import Conversation
 
+from .agent_error_guide import guide_section
 from .agents import load_agent, register_sandbox_terminal
 from agentic_dev_loop.core.config import TERMINALS, PipelineConfig, Route, StepConfig, route_target
 from agentic_dev_loop.core.paths import _has_wildcards
@@ -364,12 +365,12 @@ def _artifact_file(runtime: Runtime, step_name: str) -> str | None:
 def build_context(runtime: Runtime, docs: dict[str, str], subject: str,
                   notes: list[str] | None = None,
                   artifacts: dict[str, str] | None = None) -> str:
-    """Assemble the attempt's shared message: subject, doc bundle, the
-    canonical dependency-policy paragraph (021), the expected-output-paths
-    section generated from step defs (a prompt merely naming files lets agents
-    skip them), accumulated stage artifacts (027), and previous-attempt
-    notes."""
-    parts = [f"You are working on {subject}.\n"]
+    """Assemble the attempt's shared message: the always-on agent-facing error
+    guide (034), subject, doc bundle, the canonical dependency-policy paragraph
+    (021), the expected-output-paths section generated from step defs (a prompt
+    merely naming files lets agents skip them), accumulated stage artifacts
+    (027), and previous-attempt notes."""
+    parts = [f"You are working on {subject}.\n", guide_section()]
     for name, content in docs.items():
         parts.append(f"## {name}\n\n{content}")
     if artifacts:
@@ -541,13 +542,14 @@ def brief_inputs_hash(runtime: Runtime, step: StepConfig,
 def build_brief_context(runtime: Runtime, step: StepConfig,
                         docs: dict[str, str],
                         doc_sources: dict[str, str] | None = None) -> str:
-    """Assemble the brief agent's task message (033): the resolved unit/plan
-    docs (re-read from disk where sources are known), the closed
-    ``brief_inputs.include`` file set, and the env-facts block. Prior verdicts
-    and feedback are deliberately absent - the notes channel delivers them per
-    attempt."""
+    """Assemble the brief agent's task message (033): the always-on
+    agent-facing error guide (034), the resolved unit/plan docs (re-read from
+    disk where sources are known), the closed ``brief_inputs.include`` file
+    set, and the env-facts block. Prior verdicts and feedback are deliberately
+    absent - the notes channel delivers them per attempt."""
     sections, env_facts = _brief_sections(runtime, step, docs, doc_sources)
-    parts = [f"## {name}\n\n{content}" for name, content in sections.items()]
+    parts = [guide_section()]
+    parts += [f"## {name}\n\n{content}" for name, content in sections.items()]
     if env_facts:
         parts.append("## Environment facts\n\n"
                      + "\n".join(f"- {fact}" for fact in env_facts))

{agentic_dev_loop-1.0.0a30 → agentic_dev_loop-1.0.0a31/src/agentic_dev_loop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a30
+Version: 1.0.0a31
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -541,6 +541,28 @@ dotnet restore --locked-mode      # installs exactly packages.lock.json
 Keep the lockfile tracked (do not gitignore it) and re-run the locked restore
 to prove it holds from a clean cache before setting `deps_policy: locked`.
 
+## Agent-facing error guide
+
+The engine bundles an always-on guide for the engine error codes an agent
+can actually observe while running terminal commands. The guide lives at
+`src/agentic_dev_loop/engine/agent_error_guide.md`, versioned with the engine
+code that emits the codes, and is injected into every agent step's task
+context at assembly time. There is no opt-in and no opt-out in v1; command
+and action steps never receive it because no agent reads them.
+
+Each agent-visible code has exactly one table row, shaped like this:
+
+| Code | Meaning | Correct response |
+| --- | --- | --- |
+| AE-SBX-016 | The loop refused to sync an edit because the real repo changed underneath on a path this workspace also touches; the file in this workspace is stale and its edits will not be applied. | The command is not the problem: retry once, do not edit or work around the named path, and mention the code in your final response if it persists. |
+
+The guide is consumer-agnostic: it explains the general mechanism and never
+names a consumer or a consumer domain rule ID. If an ID must appear inside a
+quoted engine message, the placeholder `<domain-rule-id>` is used. Any engine
+change that adds or changes an agent-visible error code must update the guide
+in the same commit; the test suite enforces the pairing by parsing the
+agent-visible `SandboxError` raise sites against the bundled table.
+
 ## Host boundary (security model)
 
 The orchestrator, tool layer, and the `commit` action run in the **host

{agentic_dev_loop-1.0.0a30 → agentic_dev_loop-1.0.0a31}/src/agentic_dev_loop.egg-info/SOURCES.txt

@@ -16,6 +16,8 @@ src/agentic_dev_loop/core/results.py
 src/agentic_dev_loop/core/verdict.py
 src/agentic_dev_loop/engine/__init__.py
 src/agentic_dev_loop/engine/actions.py
+src/agentic_dev_loop/engine/agent_error_guide.md
+src/agentic_dev_loop/engine/agent_error_guide.py
 src/agentic_dev_loop/engine/agents.py
 src/agentic_dev_loop/engine/cli.py
 src/agentic_dev_loop/engine/deps.py
@@ -48,6 +50,7 @@ tests/test_029_merge_on_conflict.py
 tests/test_032_stop_when_green.py
 tests/test_033_brief_step.py
 tests/test_actions.py
+tests/test_agent_error_guide.py
 tests/test_agents.py
 tests/test_aidlc.py
 tests/test_cli.py

agentic_dev_loop-1.0.0a31/tests/test_agent_error_guide.py

@@ -0,0 +1,184 @@
+"""Agent-facing error guide (034).
+
+The guide is an engine-owned bundled resource injected into every agent
+step's task context. These tests pin the injection point, the one-line-per-code
+table shape, the consumer-agnostic ASCII content, and the pairing between the
+guide and the agent-visible ``SandboxError`` codes emitted by the engine.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from collections import Counter
+from dataclasses import replace
+from pathlib import Path
+
+import pytest
+from openhands.sdk import LLM
+
+from agentic_dev_loop.core.config import PipelineConfig
+from agentic_dev_loop.engine.agent_error_guide import (
+    GUIDE_HEADING,
+    GUIDE_RESOURCE,
+    guide_section,
+    load_guide,
+)
+from agentic_dev_loop.engine.registry import default_registry
+from agentic_dev_loop.engine.stages import (
+    Runtime,
+    build_brief_context,
+    build_context,
+    make_agent_node,
+    make_command_node,
+)
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+ISOLATION = REPO_ROOT / "src" / "agentic_dev_loop" / "engine" / "isolation.py"
+
+# The source-of-truth agent-visible codes. AE-SBX-012/013/017/019 are emitted
+# from the same Sandbox.run surface but are internal: sticky infra failures
+# (012/019) stop the run before the agent can respond, and 013/017 are
+# engine-invariant/config errors that never describe a command the agent can
+# correct.
+AGENT_VISIBLE_CODES = {"AE-SBX-008", "AE-SBX-010", "AE-SBX-016", "AE-SBX-018"}
+INTERNAL_SANDBOX_CODES = {"AE-SBX-012", "AE-SBX-013", "AE-SBX-017", "AE-SBX-019"}
+
+_CODE_RE = re.compile(r"AE-SBX-\d{3}")
+
+
+def make_cfg(steps, **over):
+    base = {"name": "t", "llm": {"model": "m", "api_key_env": "K"},
+            "agents_dir": "agents", "lockfiles": ["uv.lock"], "steps": steps}
+    base.update(over)
+    return PipelineConfig.model_validate(base)
+
+
+def make_state(**over):
+    state = {"subject": "plan plan.md", "docs": {"plan.md": "THE PLAN"},
+             "artifacts": {}, "attempt": 1, "max_attempts": 3, "notes": [],
+             "failed": False, "outcome": None, "commit_allowed": False,
+             "step_verdicts": {}, "retry_target": None, "thread_id": "t1"}
+    state.update(over)
+    return state
+
+
+@pytest.fixture
+def runtime(tmp_path, fake_sandbox):
+    state_dir = tmp_path / ".pr"
+    state_dir.mkdir()
+    cfg = make_cfg([{"name": "dev", "agent": "dev",
+                     "produces": ["implementation-summary.md"],
+                     "on_pass": "success"}])
+    return Runtime(cfg=cfg, registry=default_registry(),
+                   llm=LLM(model="openai/test-model", api_key="sk-test"),
+                   agents_dir=tmp_path / "agents", state_dir=state_dir,
+                   workspace=tmp_path, sandbox=fake_sandbox)
+
+
+def _guide_codes(text: str) -> list[str]:
+    codes = []
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("|"):
+            continue
+        cells = [c.strip() for c in stripped.strip("|").split("|")]
+        if cells and _CODE_RE.fullmatch(cells[0]):
+            codes.append(cells[0])
+    return codes
+
+
+def _agent_path_error_codes() -> set[str]:
+    """Every AE-SBX code raised on the Sandbox.run surface an agent terminal
+    action can reach, parsed from the engine source."""
+    tree = ast.parse(ISOLATION.read_text(encoding="utf-8"), filename=str(ISOLATION))
+    target_nodes: list[ast.AST] = []
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if node.name == "_guard_git":
+                target_nodes.append(node)
+        elif isinstance(node, ast.ClassDef) and node.name == "DockerBackend":
+            for child in node.body:
+                if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    if child.name in {"run", "_run_legacy", "_run_profile",
+                                      "_exec", "_start_profile", "_sync_back"}:
+                        target_nodes.append(child)
+
+    found: set[str] = set()
+    for node in target_nodes:
+        for child in ast.walk(node):
+            if isinstance(child, ast.Raise) and isinstance(child.exc, ast.Call):
+                fn = child.exc.func
+                if isinstance(fn, ast.Name) and fn.id == "SandboxError":
+                    for part in ast.walk(child.exc):
+                        if isinstance(part, ast.Constant) and isinstance(part.value, str):
+                            found.update(_CODE_RE.findall(part.value))
+    return found
+
+
+class TestBundledGuide:
+    def test_loads_from_package_resource(self):
+        from importlib.resources import files
+
+        expected = (files("agentic_dev_loop.engine")
+                    .joinpath(GUIDE_RESOURCE)
+                    .read_text(encoding="utf-8"))
+        assert load_guide() == expected
+        assert "AE-SBX-016" in load_guide()
+
+    def test_section_wraps_table(self):
+        section = guide_section()
+        assert section.startswith(f"## {GUIDE_HEADING}\n\n")
+        assert "AE-SBX-016" in section
+
+    def test_ascii_and_consumer_agnostic(self):
+        text = load_guide()
+        assert text.isascii()
+        assert "consumer" not in text.lower()
+
+    def test_every_visible_code_has_exactly_one_line(self):
+        codes = _guide_codes(load_guide())
+        assert Counter(codes) == Counter(AGENT_VISIBLE_CODES)
+
+    def test_engine_agent_path_codes_pair_with_guide(self):
+        visible = _agent_path_error_codes() - INTERNAL_SANDBOX_CODES
+        assert visible == AGENT_VISIBLE_CODES
+
+
+class TestInjection:
+    def test_agent_context_contains_guide_before_docs(self, runtime):
+        ctx = build_context(runtime, {"plan.md": "THE PLAN"}, "plan plan.md")
+        assert f"## {GUIDE_HEADING}" in ctx
+        assert "AE-SBX-016" in ctx
+        assert ctx.index(f"## {GUIDE_HEADING}") < ctx.index("## plan.md")
+
+    def test_brief_context_contains_guide_before_docs(self, runtime):
+        (runtime.workspace / "AGENTS.md").write_text("REPO RULES")
+        step = make_cfg([{
+            "name": "brief", "agent": "brief", "produces": "attempt-brief.md",
+            "brief_inputs": {"include": ["AGENTS.md"],
+                             "env_facts": ["offline"]},
+            "on_pass": "success",
+        }]).steps[0]
+        ctx = build_brief_context(runtime, step, {"plan.md": "THE PLAN"})
+        assert f"## {GUIDE_HEADING}" in ctx
+        assert "AE-SBX-016" in ctx
+        assert ctx.index(f"## {GUIDE_HEADING}") < ctx.index("## plan.md")
+
+    def test_agent_node_message_contains_guide(self, runtime, fake_agents):
+        fake_agents.set("dev", [("respond", "done")])
+        make_agent_node(runtime, runtime.cfg.steps[0])(make_state())
+        (message,) = fake_agents.messages_for("dev")
+        assert f"## {GUIDE_HEADING}" in message
+        assert "AE-SBX-016" in message
+
+    def test_command_step_notes_do_not_gain_guide(self, runtime):
+        cfg = make_cfg([
+            {"name": "dev", "agent": "dev", "on_pass": "test"},
+            {"name": "test", "command": "false", "on_pass": "success",
+             "on_fail": {"goto": "dev", "retry": True}},
+        ])
+        rt = replace(runtime, cfg=cfg)
+        update = make_command_node(rt, cfg.steps[1])(make_state())
+        assert "notes" in update
+        assert all(f"## {GUIDE_HEADING}" not in note for note in update["notes"])