diff --git a/src/agent_env/agents/agents/opencode/README.md b/src/agent_env/agents/agents/opencode/README.md index 0e0d04c72..73a7b0b1e 100644 --- a/src/agent_env/agents/agents/opencode/README.md +++ b/src/agent_env/agents/agents/opencode/README.md @@ -29,7 +29,7 @@ disk: | Extension | Implementation | |---|---| -| `agent-config/v1` | `OpenCodeConfig`: `model`, `effort` (the provider's `reasoningEffort`), `system_prompt`, `output_format` (a JSON schema the answer is checked against), `project_id`, `task_id`, `timeout_seconds` (1800 by default), `builtin_tools` (below) | +| `agent-config/v1` | `OpenCodeConfig`: `model`, `effort` (the provider's `reasoningEffort`), `system_prompt`, `output_format` (a JSON schema the answer is checked against), `project_id`, `task_id`, `timeout_seconds` (1800 by default), `max_turns` (the steps, model requests, a task may make, as Claude Code's `--max-turns`: once the last one asks for another, the CLI is killed and the task fails with `Reached maximum number of turns (N)`. OpenCode v1's own `steps` limit isn't used, since it doesn't stop a model that keeps calling tools), `builtin_tools` (below) | | `mcp-config/v1` | SDK default; each server passed to the task's CLI | | `skill-config/v1` | inline and bundle skills installed as `$XDG_CONFIG_HOME/opencode/skills//`, where OpenCode finds them | | `trajectory/v1` | the task's `opencode run --format json` events, live while it runs (format `opencode-events/1`) | diff --git a/src/agent_env/agents/agents/opencode/a2a_server.py b/src/agent_env/agents/agents/opencode/a2a_server.py index c95f34da8..f83c86abc 100644 --- a/src/agent_env/agents/agents/opencode/a2a_server.py +++ b/src/agent_env/agents/agents/opencode/a2a_server.py @@ -139,6 +139,8 @@ class OpenCodeConfig(AgentConfig): project_id: str | None = None task_id: str | None = None timeout_seconds: int = Field(default=1800, gt=0) + # Steps, model requests, a turn may make; see run_opencode. + max_turns: int | None = None # Which of the CLI's own tools it may use. With any selection, the tools of the MCP servers agent-env gives it stay. builtin_tools: OpenCodeTools | None = None @@ -384,6 +386,7 @@ def record(event: dict) -> None: builtin_tools=request.config.builtin_tools, event_callback=record, workspace=str(WORKSPACE_DIR), + max_turns=request.config.max_turns, ) except Exception: logger.exception("OpenCode invocation failed") diff --git a/src/agent_env/agents/agents/opencode/opencode_bridge.py b/src/agent_env/agents/agents/opencode/opencode_bridge.py index ac3fd86c3..247ca21b4 100644 --- a/src/agent_env/agents/agents/opencode/opencode_bridge.py +++ b/src/agent_env/agents/agents/opencode/opencode_bridge.py @@ -430,10 +430,15 @@ async def run_opencode( builtin_tools: OpenCodeTools | None = None, event_callback: Callable[[dict], None] | None = None, workspace: str = "/app", + max_turns: int | None = None, ) -> OpencodeResult: """Run one `opencode run` turn in ``workspace``. ``event_callback`` gets each JSON event as the CLI prints it: exactly the events of the returned trajectory, in order. ``builtin_tools`` selects the CLI's own tools, as - ``_permission`` describes; the tools of ``mcp_servers`` stay offered with any selection.""" + ``_permission`` describes; the tools of ``mcp_servers`` stay offered with any selection. + + ``max_turns`` bounds the turn's steps, OpenCode's model requests, as ``--max-turns`` bounds Claude Code's: once + the last step it allows asks for another, the CLI is killed and the turn fails. OpenCode v1's own ``steps`` limit + only asks the model to stop, and still offers it every tool (anomalyco/opencode#55921).""" model = model or DEFAULT_MODEL attribution = _attribution_headers(project_id, task_id) if attribution: @@ -491,8 +496,13 @@ async def run_opencode( )) _RUNNING.add(proc) parser = _EventParser(event_callback) + + def at_turn_limit() -> bool: + return max_turns is not None and parser.needs_step_past(max_turns) + try: - stderr = await asyncio.wait_for(_stream_cli(proc, prompt.encode(), parser.on_line), timeout=timeout_s) + stderr = await asyncio.wait_for(_stream_cli(proc, prompt.encode(), parser.on_line, at_turn_limit), + timeout=timeout_s) except asyncio.CancelledError: _kill_cli(proc) await _reap(proc) @@ -514,6 +524,10 @@ async def run_opencode( _RUNNING.discard(proc) result = parser.result(stderr, proc.returncode) + if at_turn_limit(): + # Claude Code's words, which callers already read as the turn limit. + result.error = f"Reached maximum number of turns ({max_turns})" + result.error_code = None if output_format is not None and result.error is None: try: structured_output = json.loads(result.response) @@ -530,12 +544,14 @@ async def run_opencode( _STDOUT_READ_BYTES = 64 * 1024 -async def _stream_cli(proc, stdin_data: bytes, on_line: Callable[[str], None]) -> bytes: +async def _stream_cli(proc, stdin_data: bytes, on_line: Callable[[str], None], + stop: Callable[[], bool] = lambda: False) -> bytes: """``proc.communicate(stdin_data)``, handing ``on_line`` each stdout line as it arrives. Lines are split as ``stdout.decode(errors="replace").splitlines()`` splits the whole output, so they are the same lines; a line has no length limit, - as with ``communicate``. Returns stderr once the CLI has exited.""" + as with ``communicate``. Returns stderr once the CLI has exited, or, once + ``stop`` holds after a read, kills the CLI and returns no stderr.""" async def feed_stdin() -> None: try: @@ -562,6 +578,10 @@ async def feed_stdin() -> None: on_line(line) pieces = [] pieces.append(rest) + if stop(): + _kill_cli(proc) + await _reap(proc) + return b"" for line in b"".join(pieces).decode(errors="replace").splitlines(): on_line(line) await stdin_task @@ -587,12 +607,17 @@ def _parse_events(stdout: bytes, stderr: bytes, returncode: int | None) -> Openc return parser.result(stderr, returncode) +# The step-finish reasons after which OpenCode's loop makes another model request; any other reason ends the turn. +_CONTINUING_STEP_REASONS = frozenset({"tool-calls", "unknown"}) + + class _EventParser: """Parse the `--format json` JSONL event stream one line at a time. Events carry a `type` and (for content) a `part`. We accumulate assistant - `text` parts as the response, count `tool` parts as tool calls, and note - the session id wherever it appears. The whole event list is the trajectory, + `text` parts as the response, count `tool` parts as tool calls and + `step-finish` parts as steps, and note the session id wherever it + appears. The whole event list is the trajectory, and each event is handed to ``event_callback`` as it is parsed. """ @@ -601,6 +626,8 @@ def __init__(self, event_callback: Callable[[dict], None] | None = None) -> None self.trajectory: list[dict] = [] self.text_chunks: list[str] = [] self.tool_calls: set[str] = set() + self.steps: set[str] = set() + self.last_step_continues = False self.session_id: str | None = None self.completed = False self.event_errors: list[str] = [] @@ -683,12 +710,21 @@ def on_line(self, line: str) -> None: call_id = (part or event).get("callID") or (part or event).get("id") or f"tool-{len(self.tool_calls)}" self.tool_calls.add(str(call_id)) elif etype == "step_finish" or ptype == "step-finish": - if (part or event).get("reason") == "stop": + reason = (part or event).get("reason") + self.steps.add(str((part or event).get("id") or f"step-{len(self.steps)}")) + self.last_step_continues = reason in _CONTINUING_STEP_REASONS + if reason == "stop": self.completed = True if self._event_callback is not None: self._event_callback(event) + def needs_step_past(self, max_steps: int) -> bool: + """Whether the turn has needed a model request past ``max_steps``: more steps finished, or the last step it + allows asked for another. Decided at a step's end, so how the CLI's output is split into reads can't change + it.""" + return len(self.steps) > max_steps or (len(self.steps) == max_steps and self.last_step_continues) + def result(self, stderr: bytes, returncode: int | None) -> OpencodeResult: # A turn is successful once OpenCode emits a terminal step_finish{reason:stop}. # OpenCode can exit non-zero *after* a completed turn (e.g. when an attached diff --git a/tst/unit/agents/opencode/test_message_contract.py b/tst/unit/agents/opencode/test_message_contract.py index 6a0acb574..c19d316d6 100644 --- a/tst/unit/agents/opencode/test_message_contract.py +++ b/tst/unit/agents/opencode/test_message_contract.py @@ -181,16 +181,27 @@ async def test_a_turn_gets_the_sdks_peer_tools_with_its_registered_servers(monke @pytest.mark.asyncio async def test_the_turns_config_and_workspace_reach_the_cli(oc, turns, folders): config = {"model": "provider/model", "effort": "high", "system_prompt": "be brief", "project_id": "p-1", - "task_id": "t-1", "role": "solver", "timeout_seconds": 42} + "task_id": "t-1", "role": "solver", "timeout_seconds": 42, "max_turns": 45} async with oc.client() as client: assert (await client.post("/ext/agent-config", json=config)).status_code == 200 await oc.send(client, "go") (call,) = turns.calls assert {key: call[key] for key in ("prompt", "model", "effort", "system_prompt", "project_id", "task_id", "role", - "timeout_s", "workspace")} == { + "timeout_s", "workspace", "max_turns")} == { "prompt": "go", "model": "provider/model", "effort": "high", "system_prompt": "be brief", - "project_id": "p-1", "task_id": "t-1", "role": "solver", "timeout_s": 42, "workspace": str(folders)} + "project_id": "p-1", "task_id": "t-1", "role": "solver", "timeout_s": 42, "workspace": str(folders), + "max_turns": 45} + + +@pytest.mark.asyncio +async def test_a_turn_stopped_at_its_limit_fails_with_the_limit_as_its_error(oc, turns): + turns.answer = lambda kwargs: result(response="", error="Reached maximum number of turns (3)", session_id="ses_1") + async with oc.client() as client: + task = await oc.send(client, "go") + + assert (task["status"]["state"], task["status"]["message"]["parts"][0]["text"]) == ( + "failed", "Reached maximum number of turns (3)") @pytest.mark.asyncio diff --git a/tst/unit/agents/opencode/test_opencode_bridge_max_turns.py b/tst/unit/agents/opencode/test_opencode_bridge_max_turns.py new file mode 100644 index 000000000..9a938a46b --- /dev/null +++ b/tst/unit/agents/opencode/test_opencode_bridge_max_turns.py @@ -0,0 +1,178 @@ +"""A turn's ``max_turns`` bounds its steps, OpenCode's model requests: once the last step it allows asks for another, +the CLI is killed and the turn fails in Claude Code's words.""" +import asyncio +import itertools +import json +import os +import shlex + +import pytest + +from agent_env.a2a_agent import A2AAgent +from tst.unit.agents.opencode.agent import opencode_bridge +from tst.unit.agents.opencode.fake_cli import FakeCLI + +SESSION = "ses_limit" +LIMIT_ERROR = "Reached maximum number of turns ({})" +_part_ids = itertools.count() + + +def _jsonl(*events: dict) -> bytes: + return "".join(json.dumps(event) + "\n" for event in events).encode() + + +def _event(etype: str, ptype: str, **part) -> dict: + return {"type": etype, "sessionID": SESSION, + "part": {"id": f"prt_{next(_part_ids)}", "sessionID": SESSION, "type": ptype, **part}} + + +def step(*tool_calls: str, answer: str | None = None, reason: str | None = None) -> list[dict]: + """One step's events as `opencode run` prints them: its tools' results, then its end, which asks for another step + when it made tool calls.""" + return [ + _event("step_start", "step-start"), + *(_event("tool_use", "tool", callID=call, tool="bash", state={"status": "completed"}) for call in tool_calls), + *([_event("text", "text", text=answer)] if answer else []), + _event("step_finish", "step-finish", reason=reason or ("tool-calls" if tool_calls else "stop")), + ] + + +class _Reads: + """A CLI's stdout handing out ``chunks`` one read at a time, then ending, or staying open as a CLI still running.""" + + def __init__(self, chunks: list[bytes], *, hang: bool) -> None: + self.chunks = list(chunks) + self.hang = hang + + async def read(self, _n: int = -1) -> bytes: + if self.chunks: + return self.chunks.pop(0) + if self.hang: + await asyncio.Event().wait() + return b"" + + +# Ways the CLI's output can arrive. The final step is its last three events: its start, its answer and its end. +SPLITS = { + "in-one-read": lambda events: [_jsonl(*events)], + "a-read-per-event": lambda events: [_jsonl(event) for event in events], + "final-step-in-its-own-read": lambda events: [_jsonl(*events[:-3]), _jsonl(*events[-3:])], + "lines-split-across-reads": lambda events: [ + data[start:start + 7] for data in [_jsonl(*events)] for start in range(0, len(data), 7)], +} + + +@pytest.fixture +def cli(monkeypatch): + """Runs a turn against a FakeCLI whose stdout hands out ``chunks``; the CLI is the run's second value.""" + monkeypatch.setattr(opencode_bridge, "_context_xdg", lambda _context: {}) + + async def run(chunks, *, hang=False, **kwargs): + proc = FakeCLI(hang=hang) + proc.stdout = _Reads(chunks, hang=hang) + + async def spawn(*_cmd, **_kwargs): + return proc + + monkeypatch.setattr(opencode_bridge.asyncio, "create_subprocess_exec", spawn) + result = await asyncio.wait_for( + opencode_bridge.run_opencode(prompt="p", context_id="limit-test", timeout_s=60, **kwargs), 10) + return result, proc + + return run + + +def test_prompt_agents_max_turns_survives_negotiation_with_the_card(oc): + negotiated = A2AAgent.negotiate_agent_config(oc.card, {"model": "provider/model", "max_turns": 200}) + + assert negotiated.fields["max_turns"] == 200 + + +@pytest.mark.asyncio +@pytest.mark.parametrize("reason", ["tool-calls", "unknown"]) +async def test_the_cli_is_stopped_once_its_last_allowed_step_asks_for_another_in_claude_codes_words(cli, reason): + events = [*step("c1"), *step("c2", reason=reason)] + + result, proc = await cli([_jsonl(*events)], hang=True, max_turns=2) + + assert proc.killed + assert (result.error, result.error_code) == (LIMIT_ERROR.format(2), None) + assert (result.tool_call_count, result.session_id, result.trajectory) == (2, SESSION, events) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("split", SPLITS.values(), ids=SPLITS.keys()) +async def test_a_turn_that_answers_on_its_last_allowed_step_completes_however_its_output_is_read(cli, split): + result, proc = await cli(split([*step("c1"), *step("c2"), *step(answer="done")]), max_turns=3) + + assert not proc.killed + assert (result.error, result.response, result.tool_call_count) == (None, "done", 2) + + +@pytest.mark.asyncio +@pytest.mark.parametrize("split", SPLITS.values(), ids=SPLITS.keys()) +async def test_a_turn_that_needs_a_step_past_its_limit_fails_however_its_output_is_read(cli, split): + result, _ = await cli(split([*step("c1"), *step("c2"), *step(answer="done")]), max_turns=2) + + assert result.error == LIMIT_ERROR.format(2) + + +@pytest.mark.asyncio +async def test_a_steps_parallel_tool_calls_count_as_one_turn(cli): + result, proc = await cli([_jsonl(*step("c1", "c2", "c3"), *step(answer="done"))], max_turns=2) + + assert not proc.killed + assert (result.error, result.tool_call_count) == (None, 3) + + +@pytest.mark.asyncio +async def test_a_step_reported_twice_counts_once(cli): + first = step("c1") + result, _ = await cli([_jsonl(*first, first[-1], *step(answer="done"))], max_turns=2) + + assert result.error is None + + +@pytest.mark.asyncio +async def test_a_last_allowed_step_that_ends_the_turn_another_way_is_not_the_limit(cli): + result, _ = await cli([_jsonl(*step(answer="cut off", reason="length"))], max_turns=1) + + assert result.error is not None + assert result.error != LIMIT_ERROR.format(1) + + +@pytest.mark.asyncio +async def test_without_a_limit_the_turn_runs_every_step(cli): + events = [event for n in range(5) for event in step(f"c{n}")] + result, proc = await cli([_jsonl(*events, *step(answer="done"))]) + + assert not proc.killed + assert (result.error, result.tool_call_count) == (None, 5) + + +@pytest.mark.asyncio +async def test_a_turn_stopped_at_its_limit_skips_the_output_format_check(cli): + result, _ = await cli([_jsonl(*step("c1"))], hang=True, max_turns=1, + output_format={"type": "json_schema", "schema": {"type": "object"}}) + + assert (result.error, result.structured_output) == (LIMIT_ERROR.format(1), None) + + +def test_a_turn_limit_kills_a_real_cli_and_returns_without_waiting_for_it(monkeypatch, tmp_path): + pid_file = tmp_path / "pid" + lines = _jsonl(*step("c1"), *step("c2")).decode() + script = f"echo $$ > {pid_file}; printf %s {shlex.quote(lines)}; exec sleep 600" + spawn = asyncio.create_subprocess_exec + + async def cli_that_keeps_running(*_cmd, **kwargs): + return await spawn("sh", "-c", script, **kwargs) + + monkeypatch.setattr(asyncio, "create_subprocess_exec", cli_that_keeps_running) + monkeypatch.setattr(opencode_bridge, "_context_xdg", lambda _context: {}) + + result = asyncio.run(asyncio.wait_for( + opencode_bridge.run_opencode(prompt="p", context_id="limit-test", timeout_s=60, max_turns=2), 10)) + + assert (result.error, result.tool_call_count) == (LIMIT_ERROR.format(2), 2) + with pytest.raises(ProcessLookupError): + os.kill(int(pid_file.read_text()), 0)