agentic-dev-loop 1.0.0a28__tar.gz → 1.0.0a29__tar.gz

{agentic_dev_loop-1.0.0a28/src/agentic_dev_loop.egg-info → agentic_dev_loop-1.0.0a29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a28
+Version: 1.0.0a29
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -195,6 +195,8 @@ steps:
   - name: dev
     agent: dev
     produces: implementation-summary.md
+    terminal_timeout: 900
+    stop_when: { green_command: ".venv-sandbox/bin/python -m pytest tests/ -q", post_green_turns: 2 }
     on_pass: test
 
   - name: test
@@ -227,6 +229,8 @@ 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). `commit` is the sole host-side built-in action; consumer actions are sandbox-executed, command-shaped scripts (see [Host boundary](#host-boundary-security-model)). |
 | `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
+| `stop_when:` | Optional agent-step termination: `{ green_command: <argv regex>, post_green_turns: <int, default 2> }`. When the agent's most recent terminal observation matching `green_command` exits 0 and no workspace writes have happened since, the engine injects one nudge turn, allows `post_green_turns` further turns, then closes the conversation. Absent = run to finish. |
+| `terminal_timeout:` | Optional agent-step per-action timeout in seconds (gt 0). `SandboxTerminalExecutor` uses it when the agent leaves the terminal action timeout unset, overriding the SDK tool's default. `None` = current behavior. |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
 | `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` provisions the sandbox before the step runs (command or agent steps; network ON; stamp-cached, re-runs when the pipeline's lockfiles change); `network: true` lets a command/agent step reach the hosts its `egress:` allowlist names (default off) - see [Per-stage networking](#per-stage-networking). |
 | `mounts:` / `egress:` | Per-step workspace isolation. `mounts:` lists `{path, mode}` entries (`rw`/`ro`, default `ro`) and is **strict-by-default** - empty/missing mounts nothing; only declared-rw paths sync back to the repo. `egress:` is `{class, presets, targets}` (`class: browser` = broad-but-logged; otherwise a strict allowlist). See [Per-stage networking](#per-stage-networking) and [docs/setup.md](docs/setup.md). |

{agentic_dev_loop-1.0.0a28 → agentic_dev_loop-1.0.0a29}/README.md

@@ -153,6 +153,8 @@ steps:
   - name: dev
     agent: dev
     produces: implementation-summary.md
+    terminal_timeout: 900
+    stop_when: { green_command: ".venv-sandbox/bin/python -m pytest tests/ -q", post_green_turns: 2 }
     on_pass: test
 
   - name: test
@@ -185,6 +187,8 @@ 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). `commit` is the sole host-side built-in action; consumer actions are sandbox-executed, command-shaped scripts (see [Host boundary](#host-boundary-security-model)). |
 | `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
+| `stop_when:` | Optional agent-step termination: `{ green_command: <argv regex>, post_green_turns: <int, default 2> }`. When the agent's most recent terminal observation matching `green_command` exits 0 and no workspace writes have happened since, the engine injects one nudge turn, allows `post_green_turns` further turns, then closes the conversation. Absent = run to finish. |
+| `terminal_timeout:` | Optional agent-step per-action timeout in seconds (gt 0). `SandboxTerminalExecutor` uses it when the agent leaves the terminal action timeout unset, overriding the SDK tool's default. `None` = current behavior. |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
 | `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` provisions the sandbox before the step runs (command or agent steps; network ON; stamp-cached, re-runs when the pipeline's lockfiles change); `network: true` lets a command/agent step reach the hosts its `egress:` allowlist names (default off) - see [Per-stage networking](#per-stage-networking). |
 | `mounts:` / `egress:` | Per-step workspace isolation. `mounts:` lists `{path, mode}` entries (`rw`/`ro`, default `ro`) and is **strict-by-default** - empty/missing mounts nothing; only declared-rw paths sync back to the repo. `egress:` is `{class, presets, targets}` (`class: browser` = broad-but-logged; otherwise a strict allowlist). See [Per-stage networking](#per-stage-networking) and [docs/setup.md](docs/setup.md). |

{agentic_dev_loop-1.0.0a28 → agentic_dev_loop-1.0.0a29}/pyproject.toml

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

@@ -6,7 +6,8 @@ test fails if this package imports engine/viz or heavy deps.
 
 from .config import (PipelineConfig, StepConfig, LlmConfig, IsolationConfig,
                      VerdictSpec, Route, route_target, load_config,
-                     default_state_dir, TERMINALS, MountSpec, EgressSpec)
+                     default_state_dir, TERMINALS, MountSpec, EgressSpec,
+                     StopWhenSpec)
 from .results import Result
 from .verdict import Verdict, VerdictError, parse_verdict, RETRY
 
@@ -14,5 +15,6 @@ __all__ = [
     "PipelineConfig", "StepConfig", "LlmConfig", "IsolationConfig",
     "VerdictSpec", "Route", "route_target", "load_config",
     "default_state_dir", "TERMINALS", "MountSpec", "EgressSpec",
+    "StopWhenSpec",
     "Result", "Verdict", "VerdictError", "parse_verdict", "RETRY",
 ]

{agentic_dev_loop-1.0.0a28 → agentic_dev_loop-1.0.0a29}/src/agentic_dev_loop/core/config.py

@@ -305,6 +305,36 @@ class EgressSpec(BaseModel):
         return [_validate_egress_target(t) for t in v]
 
 
+class StopWhenSpec(BaseModel):
+    """Optional ``stop_when:`` termination signal on an agent step (032).
+
+    ``green_command`` is a regex matched against the agent's terminal
+    observation command; a matching observation that exits 0 - and no
+    workspace writes since - triggers one nudge turn, then
+    ``post_green_turns`` further turns before the engine closes the
+    conversation. Absent ``stop_when`` keeps the current run-to-finish
+    behaviour unchanged.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    green_command: str
+    post_green_turns: int = Field(default=2, ge=0)
+
+    @field_validator("green_command")
+    @classmethod
+    def _valid_regex(cls, v: str) -> str:
+        if not isinstance(v, str) or not v.strip():
+            raise ValueError(
+                "stop_when.green_command must be a non-empty string")
+        try:
+            re.compile(v)
+        except re.error as e:
+            raise ValueError(
+                f"stop_when.green_command is not a valid regex: {e}") from e
+        return v
+
+
 class StepConfig(BaseModel):
     """One pipeline step. Its type IS the key it carries: exactly one of
     `agent`, `action`, or `command` - empty values do not count, anything
@@ -322,6 +352,8 @@ class StepConfig(BaseModel):
     verdicts: VerdictSpec | None = None
     max_iterations: int | None = None
     timeout: float | None = Field(default=None, gt=0)  # seconds, command steps only
+    terminal_timeout: float | None = Field(default=None, gt=0)  # seconds, agent steps only (032)
+    stop_when: StopWhenSpec | None = None  # agent steps only (032)
     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 + sandbox actions; host-side actions reject at registry time)
@@ -386,6 +418,14 @@ class StepConfig(BaseModel):
             raise ValueError(
                 f"step {self.name!r}: 'timeout' requires 'command'"
             )
+        if self.terminal_timeout is not None and self.agent is None:
+            raise ValueError(
+                f"step {self.name!r}: 'terminal_timeout' requires 'agent'"
+            )
+        if self.stop_when is not None and self.agent is None:
+            raise ValueError(
+                f"step {self.name!r}: 'stop_when' requires 'agent'"
+            )
         if self.setup is not None and self.command is None and self.agent is None:
             raise ValueError(
                 f"step {self.name!r}: 'setup' is only allowed on 'command' or 'agent' steps"

{agentic_dev_loop-1.0.0a28 → agentic_dev_loop-1.0.0a29}/src/agentic_dev_loop/engine/agents.py

@@ -66,7 +66,9 @@ class SandboxTerminalExecutor(ToolExecutor):
     def __init__(self, sandbox: "Sandbox", *, workspace: str = "",
                  env: dict[str, str] | None = None,
                  pipeline: str | None = None, step: str | None = None,
-                 network: bool = False, mount_set=None, egress_policy=None):
+                 network: bool = False, mount_set=None, egress_policy=None,
+                 terminal_timeout: float | None = None,
+                 on_terminal_result=None):
         self._sandbox = sandbox
         self._workspace = workspace
         self._env = env or {}
@@ -75,6 +77,8 @@ class SandboxTerminalExecutor(ToolExecutor):
         self._network = network
         self._mount_set = mount_set
         self._egress_policy = egress_policy
+        self._terminal_timeout = terminal_timeout
+        self._on_terminal_result = on_terminal_result
 
     def __call__(self, action, conversation=None):
         from openhands.tools.terminal import TerminalObservation
@@ -92,9 +96,12 @@ class SandboxTerminalExecutor(ToolExecutor):
                 command=action.command, exit_code=None, timeout=False,
                 metadata=CmdOutputMetadata(exit_code=-1))
 
+        timeout = action.timeout
+        if timeout is None and self._terminal_timeout is not None:
+            timeout = self._terminal_timeout
         request = SandboxExecutionRequest(
             argv=command_argv(action.command), cwd=self._workspace,
-            env=self._env, timeout=action.timeout,
+            env=self._env, timeout=timeout,
             pipeline=self._pipeline, step=self._step, network=self._network,
             mount_set=self._mount_set, egress_policy=self._egress_policy)
         try:
@@ -112,6 +119,9 @@ class SandboxTerminalExecutor(ToolExecutor):
                     ConversationExecutionStatus.STUCK
                 )
             raise
+        if self._on_terminal_result is not None:
+            self._on_terminal_result(
+                action.command, result.exit_code, result.wrote_workspace)
         output = result.stdout + result.stderr
         return TerminalObservation.from_text(
             output, is_error=not result.succeeded and not result.is_timeout,
@@ -130,6 +140,8 @@ def register_sandbox_terminal(sandbox: "Sandbox", *, env: dict[str, str | None]
                               step: str | None = None,
                               network: bool = False,
                               mount_set=None, egress_policy=None,
+                              terminal_timeout: float | None = None,
+                              on_terminal_result=None,
                               secrets: dict[str, str] | None = None) -> None:
     """Per-run re-registration of the `terminal` name (KD-4): a callable
     factory that builds the SDK terminal with a `SandboxTerminalExecutor`.
@@ -147,6 +159,8 @@ def register_sandbox_terminal(sandbox: "Sandbox", *, env: dict[str, str | None]
             executor=SandboxTerminalExecutor(
                 sandbox, workspace=workspace, env=resolved_env,
                 pipeline=pipeline, step=step, network=network,
-                mount_set=mount_set, egress_policy=egress_policy))
+                mount_set=mount_set, egress_policy=egress_policy,
+                terminal_timeout=terminal_timeout,
+                on_terminal_result=on_terminal_result))
 
     register_tool("terminal", factory)

{agentic_dev_loop-1.0.0a28 → agentic_dev_loop-1.0.0a29}/src/agentic_dev_loop/engine/isolation.py

@@ -144,6 +144,7 @@ class SandboxExecutionResult:
     duration_seconds: float
     backend: str  # "docker"
     timed_out: bool = False
+    wrote_workspace: bool = False  # declared-rw paths changed (032)
 
     @property
     def succeeded(self) -> bool:
@@ -1068,8 +1069,15 @@ class DockerBackend(Sandbox):
                 "failing closed (BR-11.3): no networked execution runs "
                 "without egress enforcement")
         result = self._exec(request, prof.name)
+        report: SyncBackReport | None = None
         if mount_set.rw_paths() and self._export_root is not None:
-            self._sync_back(mount_set)
+            report = self._sync_back(mount_set)
+        if report is not None and (report.synced_paths or report.merged_paths):
+            result = SandboxExecutionResult(
+                exit_code=result.exit_code, stdout=result.stdout,
+                stderr=result.stderr, duration_seconds=result.duration_seconds,
+                backend=result.backend, timed_out=result.timed_out,
+                wrote_workspace=True)
         return result
 
     def _exec(self, request: SandboxExecutionRequest,
@@ -1161,7 +1169,7 @@ class DockerBackend(Sandbox):
         export_path.parent.mkdir(parents=True, exist_ok=True)
         shutil.copy2(host_path, export_path, follow_symlinks=False)
 
-    def _sync_back(self, mount_set: MountSet) -> None:
+    def _sync_back(self, mount_set: MountSet) -> SyncBackReport | None:
         """Sync declared-rw export changes back to the real repo (BR-4/F1),
         git-aware, host-side, with the sandbox step already complete.
 
@@ -1227,6 +1235,7 @@ class DockerBackend(Sandbox):
             "synced_paths": list(report.synced_paths),
             "merged_paths": list(report.merged_paths),
         })
+        return report
 
     def close(self) -> None:
         """Best-effort stop + rm; idempotent (BR-8.3). With ``--rm`` the

{agentic_dev_loop-1.0.0a28 → agentic_dev_loop-1.0.0a29}/src/agentic_dev_loop/engine/stages.py

@@ -20,6 +20,7 @@ pipeline config; the fixed policies stay here, not in config:
 from __future__ import annotations
 
 import os
+import re
 import subprocess
 import sys
 import traceback
@@ -54,6 +55,74 @@ LAST_ERROR = "last-error.md"
 ARTIFACT_CONTEXT_CAP = 24_000  # chars per artifact injected into a step's context
 
 
+class _StopWhenController:
+    """Turn-level stop-when-green observation (032).
+
+    Pure per-event state machine - no knowledge of how the conversation is
+    driven. ``on_event`` is a SDK conversation callback: it records the most
+    recent matching terminal observation and any subsequent file-editor
+    write, and pauses the conversation after every agent-sourced event so the
+    caller can drive one turn at a time.
+    """
+
+    NUDGE = "Step complete: produce your final response now"
+    _WRITE_COMMANDS = frozenset({"create", "str_replace", "insert", "undo_edit"})
+
+    def __init__(self, spec) -> None:
+        self._pattern = re.compile(spec.green_command)
+        self.post_green_turns = spec.post_green_turns
+        self.green_hit = False
+        self.writes_since_green = False
+        self.nudged = False
+        self.post_nudge_turns = 0
+        self.conversation = None
+
+    def attach(self, conversation) -> None:
+        self.conversation = conversation
+
+    @property
+    def green_signal(self) -> bool:
+        return self.green_hit and not self.writes_since_green
+
+    def on_event(self, event) -> None:
+        if self.conversation is None:
+            return
+        from openhands.sdk.event import ObservationEvent
+
+        if isinstance(event, ObservationEvent):
+            self._record_observation(event)
+        if getattr(event, "source", None) == "agent":
+            from openhands.sdk.conversation.state import (
+                ConversationExecutionStatus,
+            )
+            self.conversation.state.execution_status = (
+                ConversationExecutionStatus.PAUSED
+            )
+
+    def on_terminal_result(self, command: str | None, exit_code: int | None,
+                           wrote_workspace: bool) -> None:
+        """Feed the sandbox terminal result channel (032): a matching green
+        command is the signal; any other terminal write resets it."""
+        if command is not None and self._pattern.search(command):
+            self.green_hit = exit_code == 0
+            self.writes_since_green = False
+        elif wrote_workspace:
+            self.writes_since_green = True
+
+    def _record_observation(self, event) -> None:
+        observation = event.observation
+        tool_name = event.tool_name
+        if tool_name == "terminal":
+            command = getattr(observation, "command", None)
+            if command is not None and self._pattern.search(command):
+                self.green_hit = getattr(observation, "exit_code", None) == 0
+                self.writes_since_green = False
+        elif tool_name == "file_editor":
+            command = getattr(observation, "command", None)
+            if command in self._WRITE_COMMANDS and not observation.is_error:
+                self.writes_since_green = True
+
+
 @dataclass
 class Runtime:
     """Everything stage nodes need that isn't in LoopState: pipeline config,
@@ -85,6 +154,10 @@ class Runtime:
         try:
             from openhands.sdk.conversation.state import ConversationExecutionStatus
 
+            controller = None
+            if step is not None and step.stop_when is not None:
+                controller = _StopWhenController(step.stop_when)
+
             if self.sandbox is not None:
                 if step is not None:
                     cwd, mount_set, egress_policy = _step_sandbox(self, step)
@@ -99,13 +172,24 @@ class Runtime:
                     network=step.network if step is not None else False,
                     mount_set=mount_set,
                     egress_policy=egress_policy,
+                    terminal_timeout=(step.terminal_timeout
+                                      if step is not None else None),
+                    on_terminal_result=(controller.on_terminal_result
+                                        if controller is not None else None),
                     secrets=(step_secret_env(self.cfg, step, self.secrets)
                              if step is not None else None))
             agent = load_agent(self.agents_dir, agent_name, self.llm)
+            callbacks = [controller.on_event] if controller is not None else None
             conv = Conversation(agent=agent, workspace=str(self.workspace),
-                                max_iteration_per_run=max_iterations)
+                                max_iteration_per_run=max_iterations,
+                                callbacks=callbacks)
+            if controller is not None:
+                controller.attach(conv)
             conv.send_message(message)
-            conv.run()
+            if controller is not None:
+                self._run_stop_when_loop(conv, controller, max_iterations)
+            else:
+                conv.run()
 
             # 030, D1/D2: a sticky infra failure must fail the run with no
             # retry - check before any capture/verdict path would schedule an
@@ -144,6 +228,40 @@ class Runtime:
             if conv is not None:
                 conv.close()
 
+    def _run_stop_when_loop(self, conv, controller: _StopWhenController,
+                            max_iterations: int) -> None:
+        """Drive one turn at a time so a green signal can inject the nudge
+        and enforce the post-nudge turn budget. The controller's callback
+        pauses the SDK run loop after every agent-sourced event, so each
+        ``conv.run()`` here advances exactly one agent turn."""
+        from openhands.sdk.conversation.state import ConversationExecutionStatus
+
+        turns = 0
+        while True:
+            conv.run()
+            status = conv.state.execution_status
+            if status in (ConversationExecutionStatus.FINISHED,
+                          ConversationExecutionStatus.STUCK,
+                          ConversationExecutionStatus.ERROR):
+                break
+
+            turns += 1
+            if turns >= max_iterations:
+                conv.state.execution_status = ConversationExecutionStatus.ERROR
+                break
+
+            if not controller.nudged and controller.green_signal:
+                conv.send_message(controller.NUDGE)
+                controller.nudged = True
+                if controller.post_green_turns == 0:
+                    break
+                continue
+
+            if controller.nudged:
+                controller.post_nudge_turns += 1
+                if controller.post_nudge_turns >= controller.post_green_turns:
+                    break
+
 
 def prompt_dir(runtime: Runtime) -> str:
     """state_dir as agents must address it. Agents resolve prompt paths

{agentic_dev_loop-1.0.0a28 → agentic_dev_loop-1.0.0a29/src/agentic_dev_loop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a28
+Version: 1.0.0a29
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -195,6 +195,8 @@ steps:
   - name: dev
     agent: dev
     produces: implementation-summary.md
+    terminal_timeout: 900
+    stop_when: { green_command: ".venv-sandbox/bin/python -m pytest tests/ -q", post_green_turns: 2 }
     on_pass: test
 
   - name: test
@@ -227,6 +229,8 @@ 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). `commit` is the sole host-side built-in action; consumer actions are sandbox-executed, command-shaped scripts (see [Host boundary](#host-boundary-security-model)). |
 | `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
+| `stop_when:` | Optional agent-step termination: `{ green_command: <argv regex>, post_green_turns: <int, default 2> }`. When the agent's most recent terminal observation matching `green_command` exits 0 and no workspace writes have happened since, the engine injects one nudge turn, allows `post_green_turns` further turns, then closes the conversation. Absent = run to finish. |
+| `terminal_timeout:` | Optional agent-step per-action timeout in seconds (gt 0). `SandboxTerminalExecutor` uses it when the agent leaves the terminal action timeout unset, overriding the SDK tool's default. `None` = current behavior. |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
 | `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` provisions the sandbox before the step runs (command or agent steps; network ON; stamp-cached, re-runs when the pipeline's lockfiles change); `network: true` lets a command/agent step reach the hosts its `egress:` allowlist names (default off) - see [Per-stage networking](#per-stage-networking). |
 | `mounts:` / `egress:` | Per-step workspace isolation. `mounts:` lists `{path, mode}` entries (`rw`/`ro`, default `ro`) and is **strict-by-default** - empty/missing mounts nothing; only declared-rw paths sync back to the repo. `egress:` is `{class, presets, targets}` (`class: browser` = broad-but-logged; otherwise a strict allowlist). See [Per-stage networking](#per-stage-networking) and [docs/setup.md](docs/setup.md). |

{agentic_dev_loop-1.0.0a28 → agentic_dev_loop-1.0.0a29}/src/agentic_dev_loop.egg-info/SOURCES.txt

@@ -45,6 +45,7 @@ src/agentic_dev_loop/viz/__main__.py
 src/agentic_dev_loop/viz/server.py
 tests/test_028_declared_caches.py
 tests/test_029_merge_on_conflict.py
+tests/test_032_stop_when_green.py
 tests/test_actions.py
 tests/test_agents.py
 tests/test_aidlc.py

agentic_dev_loop-1.0.0a29/tests/test_032_stop_when_green.py

@@ -0,0 +1,363 @@
+"""Stop-when-green (032): config surface, the per-event signal state machine,
+the one-turn run-loop budget, and the terminal timeout override."""
+
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+import yaml
+from pydantic import ValidationError
+
+from openhands.sdk import LLM
+from openhands.sdk.conversation.state import ConversationExecutionStatus
+from openhands.sdk.event import ActionEvent, MessageEvent, ObservationEvent
+from openhands.sdk.llm.message import Message, MessageToolCall, TextContent
+from openhands.tools.file_editor import FileEditorObservation
+from openhands.tools.terminal import TerminalAction, TerminalObservation
+from openhands.tools.terminal.metadata import CmdOutputMetadata
+
+from agentic_dev_loop.core.config import PipelineConfig, StopWhenSpec, load_config
+from agentic_dev_loop.engine.agents import SandboxTerminalExecutor
+from agentic_dev_loop.engine.registry import default_registry
+from agentic_dev_loop.engine.stages import Runtime, _StopWhenController
+
+
+def _base() -> dict:
+    return {
+        "name": "t",
+        "llm": {"model": "m", "api_key_env": "K"},
+        "agents_dir": "agents",
+        "lockfiles": ["uv.lock"],
+        "steps": [{"name": "dev", "agent": "dev", "on_pass": "success"}],
+    }
+
+
+def _load(tmp_path, data):
+    p = tmp_path / "pipeline.yaml"
+    p.write_text(yaml.safe_dump(data))
+    return load_config(p)
+
+
+def _terminal_obs(command, exit_code):
+    return TerminalObservation.from_text(
+        "output", command=command, exit_code=exit_code,
+        metadata=CmdOutputMetadata(exit_code=exit_code))
+
+
+def _terminal_event(command, exit_code, idx=0):
+    return ObservationEvent(
+        tool_name="terminal",
+        tool_call_id=f"tc-{idx}",
+        action_id=f"a-{idx}",
+        observation=_terminal_obs(command, exit_code))
+
+
+def _file_write_event(command="create", idx=0, is_error=False):
+    obs = FileEditorObservation(
+        command=command, path="src/x.py", prev_exist=False,
+        old_content=None, new_content="x")
+    obs = obs.model_copy(update={"is_error": is_error})
+    return ObservationEvent(
+        tool_name="file_editor",
+        tool_call_id=f"fc-{idx}",
+        action_id=f"fa-{idx}",
+        observation=obs)
+
+
+def _agent_event(idx=0):
+    return ActionEvent(
+        thought=[TextContent(type="text", text="working")],
+        tool_name="terminal",
+        tool_call_id=f"ag-{idx}",
+        tool_call=MessageToolCall(
+            id=f"ag-{idx}", name="terminal", arguments="{}",
+            origin="completion"),
+        llm_response_id=f"r-{idx}",
+        action=TerminalAction(command="echo hi"))
+
+
+def _controller(green_command="pytest"):
+    return _StopWhenController(StopWhenSpec(green_command=green_command))
+
+
+class TestStopWhenConfig:
+    def test_valid_agent_step_round_trip(self, tmp_path):
+        data = _base()
+        data["steps"] = [{"name": "dev", "agent": "dev", "on_pass": "success",
+                          "stop_when": {"green_command": "pytest tests/"},
+                          "terminal_timeout": 900}]
+        step = _load(tmp_path, data).steps[0]
+        assert step.stop_when == StopWhenSpec(green_command="pytest tests/")
+        assert step.stop_when.post_green_turns == 2
+        assert step.terminal_timeout == 900
+
+    def test_post_green_turns_custom(self, tmp_path):
+        data = _base()
+        data["steps"] = [{"name": "dev", "agent": "dev", "on_pass": "success",
+                          "stop_when": {"green_command": "pytest",
+                                        "post_green_turns": 0}}]
+        assert _load(tmp_path, data).steps[0].stop_when.post_green_turns == 0
+
+    @pytest.mark.parametrize("bad", ["[", ""])
+    def test_invalid_regex_rejected(self, tmp_path, bad):
+        data = _base()
+        data["steps"] = [{"name": "dev", "agent": "dev",
+                          "stop_when": {"green_command": bad}}]
+        with pytest.raises(ValidationError, match="green_command"):
+            _load(tmp_path, data)
+
+    def test_negative_post_green_turns_rejected(self, tmp_path):
+        data = _base()
+        data["steps"] = [{"name": "dev", "agent": "dev",
+                          "stop_when": {"green_command": "pytest",
+                                        "post_green_turns": -1}}]
+        with pytest.raises(ValidationError):
+            _load(tmp_path, data)
+
+    @pytest.mark.parametrize("step", [
+        {"name": "test", "command": "true", "stop_when": {"green_command": "pytest"}},
+        {"name": "commit", "action": "commit", "stop_when": {"green_command": "pytest"}},
+        {"name": "test", "command": "true", "terminal_timeout": 900},
+        {"name": "commit", "action": "commit", "terminal_timeout": 900},
+    ])
+    def test_agent_only_fields_rejected_on_non_agent(self, tmp_path, step):
+        data = _base()
+        data["steps"] = [step]
+        with pytest.raises(ValidationError, match="requires 'agent'"):
+            _load(tmp_path, data)
+
+    def test_negative_terminal_timeout_rejected(self, tmp_path):
+        data = _base()
+        data["steps"] = [{"name": "dev", "agent": "dev",
+                          "terminal_timeout": -1}]
+        with pytest.raises(ValidationError):
+            _load(tmp_path, data)
+
+
+class TestStopWhenController:
+    def test_matching_green_terminal_sets_signal(self):
+        c = _controller()
+        c.attach(SimpleNamespace(state=SimpleNamespace(execution_status=None)))
+        c.on_event(_agent_event(0))
+        c.on_event(_terminal_event("pytest tests/ -q", 0))
+        assert c.green_signal is True
+
+    def test_matching_failure_clears_signal(self):
+        c = _controller()
+        c.attach(SimpleNamespace(state=SimpleNamespace(execution_status=None)))
+        c.on_event(_agent_event(0))
+        c.on_event(_terminal_event("pytest tests/ -q", 1))
+        assert c.green_signal is False
+
+    def test_file_write_after_green_resets_signal(self):
+        c = _controller()
+        c.attach(SimpleNamespace(state=SimpleNamespace(execution_status=None)))
+        c.on_event(_agent_event(0))
+        c.on_event(_terminal_event("pytest tests/ -q", 0))
+        c.on_event(_file_write_event("create"))
+        assert c.green_signal is False
+
+    def test_file_view_does_not_reset_signal(self):
+        c = _controller()
+        c.attach(SimpleNamespace(state=SimpleNamespace(execution_status=None)))
+        c.on_event(_agent_event(0))
+        c.on_event(_terminal_event("pytest tests/ -q", 0))
+        c.on_event(_file_write_event("view"))
+        assert c.green_signal is True
+
+    def test_later_nonmatching_terminal_keeps_signal(self):
+        c = _controller()
+        c.attach(SimpleNamespace(state=SimpleNamespace(execution_status=None)))
+        c.on_event(_agent_event(0))
+        c.on_event(_terminal_event("pytest tests/ -q", 0))
+        c.on_event(_terminal_event("git status", 0))
+        assert c.green_signal is True
+
+    def test_later_matching_failure_replaces_signal(self):
+        c = _controller()
+        c.attach(SimpleNamespace(state=SimpleNamespace(execution_status=None)))
+        c.on_event(_agent_event(0))
+        c.on_event(_terminal_event("pytest tests/ -q", 0))
+        c.on_event(_terminal_event("pytest tests/ -q", 2))
+        assert c.green_signal is False
+
+    def test_agent_event_pauses_conversation(self):
+        c = _controller()
+        conv = SimpleNamespace(state=SimpleNamespace(execution_status=None))
+        c.attach(conv)
+        c.on_event(_agent_event(0))
+        assert conv.state.execution_status is not None
+        assert conv.state.execution_status.name == "PAUSED"
+
+
+class TestTerminalWriteChannel:
+    def test_terminal_result_green_then_write_resets(self):
+        c = _controller()
+        c.on_terminal_result("pytest tests/ -q", 0, False)
+        assert c.green_signal is True
+        c.on_terminal_result("git diff", 0, True)
+        assert c.green_signal is False
+
+    def test_terminal_result_matching_failure_clears(self):
+        c = _controller()
+        c.on_terminal_result("pytest tests/ -q", 0, False)
+        c.on_terminal_result("pytest tests/ -q", 1, False)
+        assert c.green_signal is False
+
+    def test_executor_reports_writes(self, fake_sandbox, tmp_path):
+        seen = []
+        ex = SandboxTerminalExecutor(
+            fake_sandbox, workspace=str(tmp_path), env={"PATH": "/bin"},
+            on_terminal_result=lambda command, exit_code, wrote: seen.append(
+                (command, exit_code, wrote)))
+        fake_sandbox.script(lambda req: (0, "ok", False, True))
+        ex(TerminalAction(command="echo hi"), None)
+        assert seen == [("echo hi", 0, True)]
+
+
+class TestStopWhenRunLoop:
+    def _conv(self, controller):
+        class Fake:
+            def __init__(self):
+                self.state = SimpleNamespace(execution_status=None)
+                self.messages = []
+                self.run_calls = 0
+
+            def run(self):
+                self.run_calls += 1
+                # The controller callback normally pauses after the turn.
+                self.state.execution_status = SimpleNamespace(name="PAUSED")
+
+            def send_message(self, message):
+                self.messages.append(message)
+
+        return Fake()
+
+    def test_nudge_then_budget_close(self):
+        controller = _controller()
+        controller.green_hit = True
+        controller.writes_since_green = False
+        conv = self._conv(controller)
+        Runtime._run_stop_when_loop(None, conv, controller, max_iterations=10)
+        assert controller.nudged is True
+        assert conv.messages == [controller.NUDGE]
+        assert conv.run_calls == 1 + controller.post_green_turns
+        assert controller.post_nudge_turns == controller.post_green_turns
+
+    def test_post_green_turns_zero_closes_after_nudge(self):
+        controller = _StopWhenController(
+            StopWhenSpec(green_command="pytest", post_green_turns=0))
+        controller.green_hit = True
+        conv = self._conv(controller)
+        Runtime._run_stop_when_loop(None, conv, controller, max_iterations=10)
+        assert controller.nudged is True
+        assert conv.messages == [controller.NUDGE]
+        assert conv.run_calls == 1
+
+
+class TestRunAgentStopWhen:
+    def _runtime(self, tmp_path):
+        cfg = PipelineConfig.model_validate({
+            "name": "t",
+            "llm": {"model": "m", "api_key_env": "K"},
+            "agents_dir": "agents",
+            "lockfiles": ["uv.lock"],
+            "steps": [{
+                "name": "dev",
+                "agent": "dev",
+                "produces": ["implementation-summary.md"],
+                "stop_when": {"green_command": "pytest", "post_green_turns": 2},
+                "on_pass": "success",
+            }],
+        })
+        state_dir = tmp_path / ".pr"
+        state_dir.mkdir()
+        agents_dir = tmp_path / "agents"
+        agents_dir.mkdir()
+        (agents_dir / "dev.agent.md").write_text(
+            "---\nname: dev\ntools: [terminal]\n---\nDo the work.")
+        return Runtime(
+            cfg=cfg, registry=default_registry(),
+            llm=LLM(model="openai/test-model", api_key="sk-test"),
+            agents_dir=agents_dir, state_dir=state_dir,
+            workspace=tmp_path, sandbox=None)
+
+    def _fake_conv(self, script):
+        class Fake:
+            def __init__(self, script):
+                self.state = SimpleNamespace(events=[], execution_status=None)
+                self.callbacks = []
+                self.messages = []
+                self.closed = False
+                self.script = list(script)
+                self.run_calls = 0
+
+            def send_message(self, message):
+                self.messages.append(message)
+
+            def run(self):
+                self.run_calls += 1
+                events, status = self.script.pop(0)
+                for event in events:
+                    self.state.events.append(event)
+                    for cb in self.callbacks:
+                        cb(event)
+                self.state.execution_status = status
+
+            def close(self):
+                self.closed = True
+
+        return Fake(script)
+
+    def test_green_signal_nudges_closes_and_captures(self, tmp_path, monkeypatch):
+        runtime = self._runtime(tmp_path)
+        final = MessageEvent(
+            source="agent",
+            llm_message=Message(
+                role="assistant",
+                content=[TextContent(type="text", text="final summary")]))
+        script = [
+            ([_agent_event(0), _terminal_event("pytest tests/ -q", 0)],
+             ConversationExecutionStatus.PAUSED),
+            ([final], ConversationExecutionStatus.FINISHED),
+        ]
+        conv = self._fake_conv(script)
+
+        def factory(**kw):
+            conv.callbacks = kw.get("callbacks") or []
+            return conv
+
+        monkeypatch.setattr(
+            "agentic_dev_loop.engine.stages.Conversation", factory)
+
+        result = runtime.run_agent("dev", "the task", max_iterations=10,
+                                   step=runtime.cfg.steps[0])
+
+        assert result.ok is True
+        assert result.response == "final summary"
+        assert result.truncated is False
+        assert conv.messages == ["the task", _StopWhenController.NUDGE]
+        assert conv.run_calls == 2
+        assert conv.closed is True
+
+
+class TestTerminalTimeoutOverride:
+    def test_defaults_to_terminal_timeout(self, fake_sandbox, tmp_path):
+        ex = SandboxTerminalExecutor(
+            fake_sandbox, workspace=str(tmp_path), env={"PATH": "/bin"},
+            terminal_timeout=900)
+        ex(TerminalAction(command="echo hi"), None)
+        assert fake_sandbox.requests[0].timeout == 900
+
+    def test_action_timeout_wins(self, fake_sandbox, tmp_path):
+        ex = SandboxTerminalExecutor(
+            fake_sandbox, workspace=str(tmp_path), env={"PATH": "/bin"},
+            terminal_timeout=900)
+        ex(TerminalAction(command="echo hi", timeout=30), None)
+        assert fake_sandbox.requests[0].timeout == 30
+
+    def test_unset_keeps_none(self, fake_sandbox, tmp_path):
+        ex = SandboxTerminalExecutor(
+            fake_sandbox, workspace=str(tmp_path), env={"PATH": "/bin"})
+        ex(TerminalAction(command="echo hi"), None)
+        assert fake_sandbox.requests[0].timeout is None

{agentic_dev_loop-1.0.0a28 → agentic_dev_loop-1.0.0a29}/tests/test_sdk_compat.py

@@ -90,6 +90,33 @@ def test_canary_sdk_terminal_seam_still_present():
         "update COMPAT-SHIMS.md.")
 
 
+def test_canary_sdk_turn_level_pause_seam_still_present():
+    """Canary for the 032 turn-level stop-when-green seam (COMPAT-SHIMS.md):
+    passes while the SDK still accepts ``callbacks`` on LocalConversation,
+    passes agent-sourced events to them via ``agent.step(on_event=...)``, and
+    breaks its run loop on PAUSED; fails once any of those disappear - the
+    _StopWhenController pause loop is then dead and must be replaced with the
+    SDK's supported turn-level pause mechanism."""
+    import inspect
+
+    from openhands.sdk.conversation.impl.local_conversation import LocalConversation
+
+    assert "callbacks" in inspect.signature(LocalConversation.__init__).parameters, (
+        "The SDK's LocalConversation no longer accepts `callbacks=` - the 032 "
+        "turn-level stop-when-green seam in src/agentic_dev_loop/engine/stages.py "
+        "is dead. Adopt the SDK's supported pause mechanism and update "
+        "COMPAT-SHIMS.md.")
+    run_src = inspect.getsource(LocalConversation.run)
+    assert "on_event=self._on_event" in run_src, (
+        "The SDK's LocalConversation.run no longer passes its composed callback "
+        "to agent.step - the 032 callback seam no longer receives agent-sourced "
+        "events. Update COMPAT-SHIMS.md.")
+    assert "ConversationExecutionStatus.PAUSED" in run_src, (
+        "The SDK's LocalConversation.run no longer breaks on PAUSED - the 032 "
+        "one-turn run loop in src/agentic_dev_loop/engine/stages.py is dead. "
+        "Adopt the SDK's supported pause mechanism and update COMPAT-SHIMS.md.")
+
+
 def test_canary_sdk_run_loop_still_breaks_on_stuck():
     """Canary for the D3 fast-stop reliance (COMPAT-SHIMS.md): passes while
     the SDK's LocalConversation.run breaks on STUCK; fails once the run loop