Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/agent_env/agents/agents/opencode/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<name>/`, where OpenCode finds them |
| `trajectory/v1` | the task's `opencode run --format json` events, live while it runs (format `opencode-events/1`) |
Expand Down
3 changes: 3 additions & 0 deletions src/agent_env/agents/agents/opencode/a2a_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the line of code is self explanatory. Remove the comment

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

Expand Down Expand Up @@ -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")
Expand Down
50 changes: 43 additions & 7 deletions src/agent_env/agents/agents/opencode/opencode_bridge.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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)
Expand All @@ -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)
Expand All @@ -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:
Expand All @@ -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
Expand All @@ -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.
"""

Expand All @@ -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] = []
Expand Down Expand Up @@ -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
Expand Down
17 changes: 14 additions & 3 deletions tst/unit/agents/opencode/test_message_contract.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
178 changes: 178 additions & 0 deletions tst/unit/agents/opencode/test_opencode_bridge_max_turns.py
Original file line number Diff line number Diff line change
@@ -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)
Loading