feat(opencode-agents): open one OpenCode session per call

[apucacao]

Decision

One OpenCode session per call. The handler takes base_url for a running opencode serve, opens GET /event, then POST /session and POST /session/{id}/message, and reduces only that session with the existing _Reducer. A judge gets its own session. Agent instructions, including the judge prompt, are rendered with parse_template.

Why

The reducer drops every event whose session id is not the one it was bound to. create_opencode_handler used to take one session_id for the whole process, so a judge prompt entered the agent's session, or the agent's answer was scored as the verdict. A Vega-local handler was rejected: the session boundary belongs in this package.

A failed message POST used to wait forever on an open /event stream. Early exit waited on garbage collection before aborting. A 50ms drain could drop the final message.updated.

events= and session_id= are removed. The package is not on PyPI and is still pre-v1.

What this PR deliberately does not do

• It does not add a completion route. create_opencode_handler stays ("*", "agent").
• It does not render non-system config messages, history, or the user turn. That is feat(opencode-agents): render agent instruction templates #182.
• It does not change who evaluates the AI Config.
• It does not take fix(opencode-agents): skip judges and record structured history #177's judge raise. Judges run, as a full OpenCode agent with the server's tools. There is no tool-less judge parameter.
• It does not reimplement turnkey's stall reconnect.

Next

#182 renders {{variables}} in non-system config messages. History and the user turn stay raw. #180 stays open and is not part of this stack.

  

[jeffdupont]

Since #177 and this PR both handle the judge/session problem: is the plan to land #177 first (for the _input_messages history fix) and have this PR remove its judge raise and skip_judges docs when you rebase? Or drop the raise from #177 and keep only the history change?

For context, a trial merge of main + #177 + this PR conflicts in handler.py (4 hunks) and test_handler.py (2 hunks). If #177's raise survives the rebase, judges stay blocked even though this PR gives them their own session.

[cursor]

@jeffdupont Keep only #177's _input_messages history fix (e54111d). The judge raise and the skip_judges docs are obsolete.

This PR already opens a session per call, so a judge does not enter the agent's session. Leaving the raise in place would block that. a29afc3 records the block-array history on the span and does not bring the raise over. #177 and #180 stay open.

[jeffdupont]

Thanks for this — the per-call session model is a nice simplification. A few things need addressing before merge:

1. Run can hang indefinitely when the message POST fails (server.py:116-126, _read_until_done; client created with timeout=None at server.py:66)
While the post task is pending, the loop awaits lines.__anext__() with no timeout and only checks post.done() after another SSE line arrives. A real /event stream never closes, so if POST /session/{id}/message returns e.g. 400 (bad provider/model id) without a session.idle, the handler hangs until some unrelated bus frame shows up — or forever. Reproduced with a MockTransport whose /event stays open after server.connected and the POST returns 400. Suggest racing the next line against the post task (asyncio.wait(..., return_when=FIRST_COMPLETED)), raising immediately on a ≥400 status, and a finite default timeout for the non-SSE calls. Tests miss this because every mocked /event body is finite.

2. Judges are re-enabled but templates aren't rendered (handler.py:690-731)
This PR drops the skip_judges=True guidance, but nothing in the package calls parse_template. run_judges passes variables={"message_history", "response_to_evaluate"} and expects the handler to substitute them, so the judge sees literal {{message_history}} and produces a degraded score that's still tracked. It also regresses agent instructions using {{ldContext.*}} (on main, the events callable could render them). Either land rendering here / merge #182 first, or keep the skip_judges advice until #182 lands. test_a_judge_opens_its_own_session only asserts two sessions opened — it should assert the rendered judge prompt and a parsed score.

3. Abort on early exit / session.error depends on GC (handler.py:579-590, 664-683)
The async generators are iterated with bare async for and never aclose()d, so the finally (cancel post, POST /abort, close stream/owned client) only runs whenever asyncio's asyncgen finalizer gets to it. Reproduced: breaking after the first TEXT_MESSAGE_CONTENT sent zero aborts until a sleep + gc.collect(). With an injected client this can race the caller closing it. Wrap with contextlib.aclosing(...) and add tests asserting the abort happens immediately.

4. 50 ms drain can truncate output/usage (server.py:17)
Once the POST returns, any 50 ms gap ends the turn even without this session's session.idle. On a loaded or remote server the final message.updated (with usage) can arrive later and get silently dropped. Prefer session.idle as the authoritative end with a much longer fallback, or reconcile from the POST response body.

5. Judges run as a full OpenCode agent with tools (handler.py:486-510)
A judge prompt containing the evaluated (possibly user-influenced) response runs with bash/edit tools in the server's cwd. At minimum document it; ideally allow a tool-less agent for judges (e.g. judge_agent=).

Nits

• server.py:133-135 / handler.py:113: a session.idle with no sessionID is treated as this session's end; require an exact match.
• handler.py:524: kwargs.pop("base_url") raises a bare KeyError; create_opencode_handler raises a clear TypeError for the same case.

Also flagging merge order with #182 and #177 — #182 should land before (or with) this, and this makes most of #177's judge guard redundant.

[cursor]

Addressed in d29fe06.

1. A failed POST /session/{id}/message is raced against the next SSE line and raises on status >= 400 while /event stays open. Session create, abort, and the message POST use finite timeouts. The SSE read does not.
2. Agent instructions, including the judge prompt, are rendered with parse_template on this PR, so the skip_judges guidance stays off. test_a_judge_opens_its_own_session asserts the judge system prompt no longer contains {{response_to_evaluate}} or {{message_history}}.
3. The stream, reducer, and session generators are closed with contextlib.aclosing. Breaking after the first text chunk aborts without gc.collect(). session.error aborts the same way.
4. The turn ends on this session's session.idle. After the POST returns, the fallback is 5s, not 50ms, so a late message.updated is kept.
5. Docs say a judge runs as a full OpenCode agent with the server's tools. There is no tool-less judge parameter.

Nits: an idle event with no session id does not end the turn. opencode_agents without base_url raises TypeError.

OpenCode tests: 42 passed. Not merged.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d29fe06. Configure here.}

[jeffdupont]

Re-reviewed at 491939d. Every point from my 20 Oct review is fixed. For each one, I removed the fix and checked that a test fails:

1. Failed message POST no longer hangs: the next SSE line is raced against the POST (server.py:155-166), and calls use finite timeouts. See the one ask below.
2. Judge prompts are rendered: _system_text runs parse_template on instructions. A messages-mode judge reaches the handler with its messages already collapsed into instructions by core (judges.py:141-153), so it is covered too. Removing the render fails test_a_judge_opens_its_own_session.
3. Abort no longer waits for garbage collection: every generator level is wrapped in aclosing. Turning aclosing into a no-op fails test_breaking_aborts_without_waiting_for_gc.
4. No 50 ms drain: this session's session.idle ends the turn, with a 5 s quiet fallback. Setting the fallback back to 50 ms fails test_a_late_completion_survives_the_post_returning.
5. Judge tools: documented in the README and the docstring. That is the minimum I asked for; a tool-less judge agent can come later.

• Nits: session.idle needs an exact sessionID match (a test fails without it), and a missing base_url raises TypeError. Bugbot's cancelled-read finding is fixed and tested.

43 passed locally. CI is green, and the branch merges cleanly with main now that #177 has landed.

One ask (should fix, not blocking): test_a_failed_message_post_does_not_wait_for_the_bus passes even with the race removed. _OpenBus sends assistant_open and text_delta right away, and when the second frame arrives the loop sees the finished POST and raises. A real server sends nothing after rejecting the message, and that silence is the hang this fix prevents. With a silent bus for the 400 case (head = [] if script.message_status >= 400 else [...]), the test passes with the fix and times out at 2 s without it. Making that change means the test actually guards the fix.

Stack: #182 sits on this PR, and #180 is still open even though #182 says that route was rejected. Can #180 be closed?