Skip to content

Personal AI, On Personal Devices

Python

fix(opencode): support OpenCode V2 server API with auto-detection (fixes #1164) (#1170)

rahul raic8a89c31b899
diff --git a/src/openjarvis/agents/opencode.py b/src/openjarvis/agents/opencode.py
index e08d6330..55335dce 100644
--- a/src/openjarvis/agents/opencode.py
+++ b/src/openjarvis/agents/opencode.py
@@ -16,6 +16,7 @@ import json
import logging
import os
import re
+import secrets
import shutil
import subprocess
import time
@@ -81,7 +82,7 @@ def _extract_text(parts: List[dict]) -> str:
def _extract_tool_results(parts: List[dict]) -> List[ToolResult]:
- """Map opencode ``tool`` parts to OpenJarvis ToolResults (best-effort)."""
+ """Map opencode ``tool`` parts to OpenJarvis ToolResults (supports V1 and V2)."""
results: List[ToolResult] = []
for p in parts:
if not isinstance(p, dict) or p.get("type") != "tool":
@@ -89,11 +90,22 @@ def _extract_tool_results(parts: List[dict]) -> List[ToolResult]:
state = p.get("state", {}) if isinstance(p.get("state"), dict) else {}
status = state.get("status", "")
output = state.get("output")
+ if output is None and "content" in state:
+ c = state["content"]
+ if isinstance(c, list):
+ output = "".join(
+ item.get("text", "") if isinstance(item, dict) else str(item)
+ for item in c
+ ).strip()
+ elif isinstance(c, dict):
+ output = c.get("text", "") or str(c)
+ else:
+ output = str(c)
if output is None:
output = state.get("title", "") or (json.dumps(state) if state else "")
results.append(
ToolResult(
- tool_name=p.get("tool", p.get("name", "unknown")),
+ tool_name=p.get("name") or p.get("tool") or "unknown",
content=str(output),
# opencode tool state: completed | error | running | pending
success=status == "completed",
@@ -102,6 +114,40 @@ def _extract_tool_results(parts: List[dict]) -> List[ToolResult]:
return results
+def _fetch_v2_messages(client: Any, session_id: str) -> List[dict]:
+ """Read the entire V2 transcript in chronological order.
+
+ V2 defaults to the newest 50 messages. Its cursor carries the ordering,
+ so only the first request may specify ``order``. A cursor can point past
+ the last message; an empty page terminates that traversal.
+ """
+ messages: List[dict] = []
+ params: dict = {"order": "asc", "limit": 200}
+ seen_cursors: set[str] = set()
+ while True:
+ response = client.get(f"/api/session/{session_id}/message", params=params)
+ response.raise_for_status()
+ body = response.json()
+ page = body.get("data") if isinstance(body, dict) else None
+ if not isinstance(page, list) or any(not isinstance(m, dict) for m in page):
+ raise RuntimeError("OpenCode V2 returned an invalid transcript")
+ messages.extend(page)
+ if not page:
+ return messages
+ cursor = body.get("cursor", {})
+ if not isinstance(cursor, dict):
+ raise RuntimeError("OpenCode V2 returned an invalid transcript cursor")
+ next_cursor = cursor.get("next")
+ if next_cursor is None:
+ return messages
+ if not isinstance(next_cursor, str) or not next_cursor:
+ raise RuntimeError("OpenCode V2 returned an invalid transcript cursor")
+ if next_cursor in seen_cursors:
+ raise RuntimeError("OpenCode V2 repeated a transcript cursor")
+ seen_cursors.add(next_cursor)
+ params = {"cursor": next_cursor, "limit": 200}
+
+
@AgentRegistry.register("opencode")
class OpenCodeAgent(BaseAgent):
"""Agent that delegates coding tasks to a local ``opencode`` server.
@@ -109,6 +155,7 @@ class OpenCodeAgent(BaseAgent):
The ``engine`` is used to wire opencode at an OpenAI-compatible provider so
inference runs on OpenJarvis's selected local model. ``agent`` selects
opencode's built-in agent: ``build`` (full access) or ``plan`` (read-only).
+ Supports both OpenCode V1 and V2 (2.x) server APIs.
"""
agent_id = "opencode"
@@ -122,6 +169,7 @@ class OpenCodeAgent(BaseAgent):
engine: InferenceEngine,
model: str,
*,
+ api_version: str = "auto",
bus: Optional[EventBus] = None,
temperature: Optional[float] = None,
max_tokens: Optional[int] = None,
@@ -151,6 +199,15 @@ class OpenCodeAgent(BaseAgent):
rate_limiter=rate_limiter,
agent_id=agent_id,
)
+ if api_version not in ("auto", "v1", "v2"):
+ raise ValueError(
+ f"Invalid api_version {api_version!r}; expected 'auto', 'v1', or 'v2'"
+ )
+ self._api_version = api_version
+ self._resolved_api_version: Optional[str] = (
+ None if api_version == "auto" else api_version
+ )
+ self._current_session_id: Optional[str] = None
self._workspace = workspace or os.getcwd()
self._agent = agent
self._provider_id = provider_id
@@ -160,8 +217,14 @@ class OpenCodeAgent(BaseAgent):
self._permission = permission
self._hostname = hostname
self._port = port
- self._server_password = server_password or os.environ.get(
- "OPENCODE_SERVER_PASSWORD", ""
+ # V2 always authenticates, generating a password when none is supplied.
+ # Choose it here so the spawned server and our client share a credential
+ # without reading or logging the server's generated password.
+ self._server_password = (
+ server_password
+ or os.environ.get("OPENCODE_PASSWORD", "")
+ or os.environ.get("OPENCODE_SERVER_PASSWORD", "")
+ or secrets.token_urlsafe(32)
)
self._timeout = timeout
self._opencode_bin = opencode_bin or shutil.which("opencode") or "opencode"
@@ -227,8 +290,10 @@ class OpenCodeAgent(BaseAgent):
config_path.write_text(json.dumps(self._build_config(), indent=2), "utf-8")
env = dict(os.environ)
env["OPENCODE_CONFIG"] = str(config_path)
- if self._server_password:
- env["OPENCODE_SERVER_PASSWORD"] = self._server_password
+ # V1 uses the legacy name; V2 prefers OPENCODE_PASSWORD. Set both so an
+ # inherited value cannot override an explicitly supplied password.
+ env["OPENCODE_PASSWORD"] = self._server_password
+ env["OPENCODE_SERVER_PASSWORD"] = self._server_password
self._proc = subprocess.Popen(
[
self._opencode_bin,
@@ -282,6 +347,8 @@ class OpenCodeAgent(BaseAgent):
if self._base:
try:
with self._client() as c:
+ if self._resolved_api_version == "v2" and self._current_session_id:
+ c.delete(f"/api/session/{self._current_session_id}")
c.post("/global/dispose")
except Exception:
pass
@@ -293,6 +360,9 @@ class OpenCodeAgent(BaseAgent):
self._proc.kill()
self._proc = None
self._base = ""
+ self._current_session_id = None
+ if self._api_version == "auto":
+ self._resolved_api_version = None
if self._config_dir:
shutil.rmtree(self._config_dir, ignore_errors=True)
self._config_dir = None
@@ -316,10 +386,9 @@ class OpenCodeAgent(BaseAgent):
# Resolve which opencode provider/model to address. Fail clearly rather
# than letting opencode 500 on an unregistered provider.
if self._provider_base_url:
- model_spec = {"providerID": self._provider_id, "modelID": self._model_id}
+ prov, mid = self._provider_id, self._model_id
elif "/" in self._model_id:
prov, _, mid = self._model_id.partition("/")
- model_spec = {"providerID": prov, "modelID": mid}
else:
self._emit_turn_end(turns=1, error=True)
return AgentResult(
@@ -333,6 +402,9 @@ class OpenCodeAgent(BaseAgent):
metadata={"error": True},
)
+ model_spec_v1 = {"providerID": prov, "modelID": mid}
+ model_spec_v2 = {"providerID": prov, "id": mid}
+
try:
self._ensure_server()
except RuntimeError as exc:
@@ -341,38 +413,156 @@ class OpenCodeAgent(BaseAgent):
data: dict = {}
turn_parts: List[dict] = []
+ active_version = self._resolved_api_version or "v1"
+ session_id = ""
+
try:
with self._client() as c:
- ses = c.post("/session", json={"title": input[:80]})
- ses.raise_for_status()
- session_id = ses.json()["id"]
-
- body: dict = {
- "agent": self._agent,
- "model": model_spec,
- "parts": [{"type": "text", "text": input}],
- }
-
- resp = c.post(f"/session/{session_id}/message", json=body)
- resp.raise_for_status()
- data = resp.json()
-
- # The prompt POST returns only the final assistant message;
- # tool executions live in intermediate messages of the turn, so
- # pull the whole session to recover them (verified against a
- # live opencode session). Falls back to the final message.
- turn_parts = list(data.get("parts", []))
- try:
- msgs = c.get(f"/session/{session_id}/message").json()
- if isinstance(msgs, list):
- turn_parts = [
- part
- for mm in msgs
- if isinstance(mm, dict)
- for part in mm.get("parts", [])
- ]
- except Exception as get_exc:
- logger.debug("opencode message fetch failed: %s", get_exc)
+ version = self._resolved_api_version
+
+ # Session creation with auto-fallback
+ if version == "v2":
+ ses = c.post(
+ "/api/session",
+ json={
+ "title": input[:80],
+ "agent": self._agent,
+ "model": model_spec_v2,
+ },
+ )
+ ses.raise_for_status()
+ ses_data = ses.json()
+ session_id = ses_data.get("id") or (ses_data.get("data") or {}).get(
+ "id"
+ )
+ elif version == "v1":
+ ses = c.post("/session", json={"title": input[:80]})
+ ses.raise_for_status()
+ session_id = ses.json().get("id")
+ else:
+ # auto-detection: try V1 first, fallback to V2 on 404
+ try:
+ ses = c.post("/session", json={"title": input[:80]})
+ ses.raise_for_status()
+ session_id = ses.json().get("id")
+ self._resolved_api_version = "v1"
+ except Exception as ses_exc:
+ status = getattr(
+ getattr(ses_exc, "response", None), "status_code", None
+ )
+ if status == 404:
+ logger.info(
+ "OpenCode /session returned 404; "
+ "falling back to /api/session (v2)"
+ )
+ ses = c.post(
+ "/api/session",
+ json={
+ "title": input[:80],
+ "agent": self._agent,
+ "model": model_spec_v2,
+ },
+ )
+ ses.raise_for_status()
+ ses_data = ses.json()
+ session_id = ses_data.get("id") or (
+ ses_data.get("data") or {}
+ ).get("id")
+ self._resolved_api_version = "v2"
+ else:
+ raise
+
+ if not session_id:
+ raise RuntimeError(
+ "Could not obtain session ID from opencode server"
+ )
+ self._current_session_id = session_id
+ active_version = self._resolved_api_version or "v1"
+
+ # Prompt / message dispatch
+ if active_version == "v2":
+ resp = c.post(
+ f"/api/session/{session_id}/prompt",
+ json={"text": input},
+ )
+ resp.raise_for_status()
+
+ # V2 admits a queued user input, not a completed assistant
+ # reply. Both synchronization and transcript retrieval must
+ # succeed before we can report a completed turn.
+ wait = c.post(f"/api/experimental/session/{session_id}/wait")
+ wait.raise_for_status()
+ terminal: Optional[dict] = None
+ for message in _fetch_v2_messages(c, session_id):
+ if message.get("type") == "idle":
+ terminal = message
+ continue
+ if message.get("type") != "assistant":
+ continue
+ terminal = None
+ parts = message.get("content")
+ if not isinstance(parts, list):
+ raise RuntimeError(
+ "OpenCode V2 returned invalid assistant content"
+ )
+ turn_parts.extend(parts)
+ data = message
+ if not data:
+ raise RuntimeError(
+ "OpenCode V2 completed without an assistant reply"
+ )
+ # The wait route reports idle even when execution failed.
+ # The terminal transcript marker records the actual outcome;
+ # a provider finish reason alone does not describe the turn.
+ if terminal is None:
+ raise RuntimeError(
+ "OpenCode V2 returned an incomplete turn transcript"
+ )
+ if terminal.get("outcome") != "succeeded" or terminal.get("error"):
+ error = terminal.get("error")
+ detail = (
+ error.get("message", "Turn failed")
+ if isinstance(error, dict)
+ else f"Turn {terminal.get('outcome', 'did not complete')}"
+ )
+ raise RuntimeError(f"OpenCode V2 failed: {detail}")
+ if data.get("error") or data.get("finish") in (
+ "error",
+ "content-filter",
+ ):
+ error = data.get("error")
+ detail = (
+ error.get("message", "Assistant generation failed")
+ if isinstance(error, dict)
+ else "Assistant generation failed"
+ )
+ raise RuntimeError(f"OpenCode V2 assistant failed: {detail}")
+ if data.get("finish") not in ("stop", "length", "tool-calls"):
+ raise RuntimeError(
+ "OpenCode V2 returned an unfinished assistant reply"
+ )
+ else:
+ body: dict = {
+ "agent": self._agent,
+ "model": model_spec_v1,
+ "parts": [{"type": "text", "text": input}],
+ }
+ resp = c.post(f"/session/{session_id}/message", json=body)
+ resp.raise_for_status()
+ data = resp.json()
+
+ turn_parts = list(data.get("parts", []))
+ try:
+ msgs = c.get(f"/session/{session_id}/message").json()
+ if isinstance(msgs, list):
+ turn_parts = [
+ part
+ for mm in msgs
+ if isinstance(mm, dict)
+ for part in (mm.get("parts") or mm.get("content") or [])
+ ]
+ except Exception as get_exc:
+ logger.debug("opencode message fetch failed: %s", get_exc)
except Exception as exc:
logger.error("opencode run failed: %s", exc, exc_info=True)
self._emit_turn_end(turns=1, error=True)
@@ -383,7 +573,13 @@ class OpenCodeAgent(BaseAgent):
)
info = data.get("info", {}) if isinstance(data, dict) else {}
- content = _extract_text(data.get("parts", []))
+ model_obj = data.get("model", {}) if isinstance(data.get("model"), dict) else {}
+ final_parts = data.get("content") or data.get("parts") or []
+ content = (
+ _extract_text(final_parts)
+ if isinstance(final_parts, list)
+ else (data.get("text", "") if isinstance(data, dict) else "")
+ )
tool_results = _extract_tool_results(turn_parts)
self._emit_turn_end(turns=1)
@@ -392,12 +588,21 @@ class OpenCodeAgent(BaseAgent):
tool_results=tool_results,
turns=1,
metadata={
- "finish": info.get("finish"),
- "tokens": info.get("tokens"),
- "provider_id": info.get("providerID", self._provider_id),
- "model_id": info.get("modelID", self._model_id),
- "session_id": info.get("sessionID", ""),
- "agent": self._agent,
+ "finish": data.get("finish") or info.get("finish"),
+ "tokens": data.get("tokens") or info.get("tokens"),
+ "provider_id": (
+ model_obj.get("providerID") or info.get("providerID", prov)
+ ),
+ "model_id": (
+ model_obj.get("id")
+ or model_obj.get("modelID")
+ or info.get("modelID", mid)
+ ),
+ "session_id": (
+ data.get("sessionID") or info.get("sessionID", session_id or "")
+ ),
+ "agent": data.get("agent") or self._agent,
+ "api_version": active_version,
},
)
diff --git a/tests/agents/test_opencode_agent.py b/tests/agents/test_opencode_agent.py
index 100567ce..9137edb4 100644
--- a/tests/agents/test_opencode_agent.py
+++ b/tests/agents/test_opencode_agent.py
@@ -8,6 +8,10 @@ message shape captured from a live `opencode serve` session.
from __future__ import annotations
from types import SimpleNamespace
+from typing import Any
+
+import httpx
+import pytest
from openjarvis.agents.opencode import (
OpenCodeAgent,
@@ -265,3 +269,232 @@ class TestRunParsing:
assert res.tool_results[0].tool_name == "write"
assert res.tool_results[0].success is True
assert "Wrote file" in res.tool_results[0].content
+
+
+V2_SPIKE_RESPONSE = {
+ "id": "msg_assistant_1",
+ "time": {"created": 1, "completed": 2},
+ "type": "assistant",
+ "agent": "build",
+ "finish": "stop",
+ "tokens": {"input": 10, "output": 25},
+ "model": {"id": "local-model", "providerID": "openjarvis"},
+ "content": [
+ {"type": "text", "text": "Hello from OpenCode V2."},
+ {
+ "type": "tool",
+ "name": "write",
+ "id": "call_v2_1",
+ "state": {
+ "status": "completed",
+ "content": [{"type": "text", "text": "V2 file written successfully."}],
+ },
+ },
+ ],
+}
+
+
+class _FakeStatusResp:
+ def __init__(self, data: Any, status_code: int = 200):
+ self._d = data
+ self.status_code = status_code
+
+ def raise_for_status(self):
+ if self.status_code >= 400:
+ request = httpx.Request("POST", "http://localhost")
+ response = httpx.Response(self.status_code, request=request)
+ raise httpx.HTTPStatusError(
+ "Mock error", request=request, response=response
+ )
+
+ def json(self):
+ return self._d
+
+
+class _FakeV2Client:
+ def __init__(self, v1_status: int = 404):
+ self._v1_status = v1_status
+ self.calls = []
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *a):
+ return False
+
+ def post(self, path: str, json: Any = None):
+ self.calls.append(("POST", path, json))
+ if path == "/session":
+ if self._v1_status == 404:
+ return _FakeStatusResp({"detail": "Not Found"}, status_code=404)
+ return _FakeStatusResp({"id": "ses_v1"}, status_code=self._v1_status)
+ if path == "/api/session":
+ return _FakeStatusResp({"data": {"id": "ses_v2"}})
+ if path == "/api/session/ses_v2/prompt":
+ return _FakeStatusResp(
+ {
+ "data": {
+ "id": "msg_user_1",
+ "sessionID": "ses_v2",
+ "type": "user",
+ "time": {"created": 0},
+ "payload": {"text": json["text"]},
+ "delivery": "queue",
+ }
+ }
+ )
+ if "/wait" in path:
+ return _FakeStatusResp({}, status_code=204)
+ if path.endswith("/message"):
+ return _FakeStatusResp(SPIKE_RESPONSE)
+ return _FakeStatusResp({})
+
+ def get(self, path: str, **kw):
+ self.calls.append(("GET", path, kw))
+ if path == "/api/session/ses_v2/message":
+ return _FakeStatusResp(
+ {
+ "data": [
+ V2_SPIKE_RESPONSE,
+ {
+ "id": "msg_idle_1",
+ "time": {"created": 3},
+ "type": "idle",
+ "outcome": "succeeded",
+ },
+ ],
+ }
+ )
+ if path == "/session/ses_v1/message":
+ return _FakeStatusResp(TURN_MESSAGES)
+ return _FakeStatusResp({})
+
+ def delete(self, path: str, **kw):
+ self.calls.append(("DELETE", path, kw))
+ return _FakeStatusResp({}, status_code=204)
+
+
+class TestApiVersionConfiguration:
+ def test_default_api_version_is_auto(self, tmp_path):
+ agent = OpenCodeAgent(
+ SimpleNamespace(_host="http://h:1"),
+ "m",
+ workspace=str(tmp_path),
+ )
+ assert agent._api_version == "auto"
+ assert agent._resolved_api_version is None
+
+ def test_explicit_v1_and_v2(self, tmp_path):
+ agent_v1 = OpenCodeAgent(
+ SimpleNamespace(_host="http://h:1"),
+ "m",
+ workspace=str(tmp_path),
+ api_version="v1",
+ )
+ assert agent_v1._api_version == "v1"
+ assert agent_v1._resolved_api_version == "v1"
+
+ agent_v2 = OpenCodeAgent(
+ SimpleNamespace(_host="http://h:1"),
+ "m",
+ workspace=str(tmp_path),
+ api_version="v2",
+ )
+ assert agent_v2._api_version == "v2"
+ assert agent_v2._resolved_api_version == "v2"
+
+ def test_invalid_api_version_raises(self, tmp_path):
+ with pytest.raises(ValueError, match="Invalid api_version"):
+ OpenCodeAgent(
+ SimpleNamespace(_host="http://h:1"),
+ "m",
+ workspace=str(tmp_path),
+ api_version="v3",
+ )
+
+
+class TestV2AndAutoDetection:
+ def test_v2_explicit_flow(self, monkeypatch, tmp_path):
+ client = _FakeV2Client()
+ agent = OpenCodeAgent(
+ SimpleNamespace(_host="http://h:1"),
+ "local-model",
+ workspace=str(tmp_path),
+ api_version="v2",
+ )
+ monkeypatch.setattr(agent, "_ensure_server", lambda: "http://127.0.0.1:7654")
+ agent._base = "http://127.0.0.1:7654"
+ monkeypatch.setattr(agent, "_client", lambda: client)
+
+ res = agent.run("Write a test")
+ assert res.content == "Hello from OpenCode V2."
+ assert res.metadata["finish"] == "stop"
+ assert res.metadata["model_id"] == "local-model"
+ assert res.metadata["api_version"] == "v2"
+ assert len(res.tool_results) == 1
+ assert res.tool_results[0].tool_name == "write"
+ assert res.tool_results[0].success is True
+ assert "V2 file written" in res.tool_results[0].content
+
+ paths = [call[1] for call in client.calls]
+ assert "/api/session" in paths
+ assert "/api/session/ses_v2/prompt" in paths
+ assert "/api/session/ses_v2/message" in paths
+ assert "/session" not in paths
+
+ def test_auto_detection_falls_back_to_v2_on_404(self, monkeypatch, tmp_path):
+ client = _FakeV2Client(v1_status=404)
+ agent = OpenCodeAgent(
+ SimpleNamespace(_host="http://h:1"),
+ "local-model",
+ workspace=str(tmp_path),
+ api_version="auto",
+ )
+ monkeypatch.setattr(agent, "_ensure_server", lambda: "http://127.0.0.1:7654")
+ agent._base = "http://127.0.0.1:7654"
+ monkeypatch.setattr(agent, "_client", lambda: client)
+
+ res = agent.run("Write a test")
+ assert res.content == "Hello from OpenCode V2."
+ assert agent._resolved_api_version == "v2"
+
+ client.calls.clear()
+ res2 = agent.run("Second turn")
+ assert res2.content == "Hello from OpenCode V2."
+ paths = [call[1] for call in client.calls]
+ assert "/session" not in paths
+
+ def test_auto_detection_stays_v1_when_200(self, monkeypatch, tmp_path):
+ client = _FakeV2Client(v1_status=200)
+ agent = OpenCodeAgent(
+ SimpleNamespace(_host="http://h:1"),
+ "local-model",
+ workspace=str(tmp_path),
+ api_version="auto",
+ )
+ monkeypatch.setattr(agent, "_ensure_server", lambda: "http://127.0.0.1:7654")
+ agent._base = "http://127.0.0.1:7654"
+ monkeypatch.setattr(agent, "_client", lambda: client)
+
+ res = agent.run("Write a test")
+ assert res.content == "Hello from the local model."
+ assert agent._resolved_api_version == "v1"
+
+ def test_close_cleans_up_v2_session(self, monkeypatch, tmp_path):
+ client = _FakeV2Client()
+ agent = OpenCodeAgent(
+ SimpleNamespace(_host="http://h:1"),
+ "local-model",
+ workspace=str(tmp_path),
+ api_version="v2",
+ )
+ monkeypatch.setattr(agent, "_ensure_server", lambda: "http://127.0.0.1:7654")
+ agent._base = "http://127.0.0.1:7654"
+ monkeypatch.setattr(agent, "_client", lambda: client)
+
+ agent.run("Run task")
+ agent.close()
+
+ delete_calls = [call for call in client.calls if call[0] == "DELETE"]
+ assert len(delete_calls) == 1
+ assert delete_calls[0][1] == "/api/session/ses_v2"
diff --git a/tests/agents/test_opencode_v2_protocol.py b/tests/agents/test_opencode_v2_protocol.py
new file mode 100644
index 00000000..5e17f293
--- /dev/null
+++ b/tests/agents/test_opencode_v2_protocol.py
@@ -0,0 +1,434 @@
+"""OpenCode protocol regressions using real HTTPX requests, without a model.
+
+The V2 fixture follows the tagged v2.0.32 protocol and server handlers:
+https://github.com/anomalyco/opencode/blob/v2.0.32/packages/protocol/openapi.json
+https://github.com/anomalyco/opencode/blob/v2.0.32/packages/server/src/handlers/message.ts
+https://github.com/anomalyco/opencode/blob/v2.0.32/packages/cli/src/server-process.ts
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from types import SimpleNamespace
+
+import httpx
+import pytest
+
+import openjarvis.agents.opencode as opencode
+
+
+def _assistant(number: int, text: str, **changes) -> dict:
+ return {
+ "id": f"msg_{number:04}",
+ "time": {"created": number, "completed": number + 0.5},
+ "type": "assistant",
+ "agent": "build",
+ "model": {"providerID": "openjarvis", "id": "local-model"},
+ "content": [{"type": "text", "text": text}],
+ "finish": "stop",
+ **changes,
+ }
+
+
+def _idle(number: int, outcome: str = "succeeded", **changes) -> dict:
+ return {
+ "id": f"msg_{number:04}",
+ "time": {"created": number},
+ "type": "idle",
+ "outcome": outcome,
+ **changes,
+ }
+
+
+class _ProtocolServer:
+ """An authenticated V1/V2 HTTP contract with V2's default ordering/cursors."""
+
+ def __init__(self, version="v2", messages=None):
+ self.version = version
+ self.password = "fixture-password"
+ self.messages = (
+ messages
+ if messages is not None
+ else [
+ _assistant(2, "Inspecting the code."),
+ _assistant(3, "Final answer."),
+ _idle(4),
+ ]
+ )
+ self.calls: list[httpx.Request] = []
+ self.wait_status = 204
+ self.wait_timeout = False
+ self.transcript_status = 200
+ self.bad_transcript = None
+ self.repeat_cursor = False
+ self.session_count = 0
+
+ def __call__(self, request: httpx.Request) -> httpx.Response:
+ self.calls.append(request)
+ expected = (
+ "Basic " + base64.b64encode(f"opencode:{self.password}".encode()).decode()
+ )
+ if request.headers.get("authorization") != expected:
+ return httpx.Response(401, json={"message": "Authentication required"})
+ path = request.url.path
+ body = json.loads(request.content) if request.content else None
+ if path == "/session" and request.method == "POST":
+ if self.version != "v1":
+ return httpx.Response(404, json={"message": "Not found"})
+ return httpx.Response(200, json={"id": "ses_v1"})
+ if path == "/session/ses_v1/message":
+ message = {
+ "info": {"role": "assistant", "finish": "stop"},
+ "parts": [{"type": "text", "text": "V1 final answer."}],
+ }
+ return httpx.Response(
+ 200, json=message if request.method == "POST" else [message]
+ )
+ if path == "/api/session" and request.method == "POST":
+ assert set(body) == {"title", "agent", "model"}
+ assert body["model"] == {"providerID": "openjarvis", "id": "local-model"}
+ self.session_count += 1
+ return httpx.Response(
+ 200, json={"data": {"id": f"ses_{self.session_count}"}}
+ )
+ if path.endswith("/prompt"):
+ assert set(body) == {"text"}
+ return httpx.Response(
+ 200,
+ json={
+ "data": {
+ "id": "msg_0001",
+ "sessionID": path.split("/")[3],
+ "time": {"created": 1},
+ "type": "user",
+ "payload": {"text": body["text"]},
+ "delivery": "queue",
+ }
+ },
+ )
+ if path.endswith("/wait"):
+ if self.wait_timeout:
+ raise httpx.ReadTimeout("Fixture wait timeout", request=request)
+ return httpx.Response(self.wait_status)
+ if path.endswith("/message"):
+ if self.transcript_status != 200:
+ return httpx.Response(
+ self.transcript_status, json={"message": "Failed"}
+ )
+ if self.bad_transcript is not None:
+ return httpx.Response(200, json=self.bad_transcript)
+ params = request.url.params
+ if "cursor" in params:
+ assert "order" not in params
+ order, offset = params["cursor"].split(":")
+ start = int(offset)
+ else:
+ order, start = params.get("order", "desc"), 0
+ messages = sorted(
+ self.messages,
+ key=lambda m: m["time"]["created"],
+ reverse=order == "desc",
+ )
+ page = messages[start : start + int(params.get("limit", "50"))]
+ # Upstream includes next for every nonempty page, even the last.
+ next_cursor = f"{order}:{start + len(page)}" if page else None
+ if self.repeat_cursor and "cursor" in params:
+ page = messages[:1]
+ next_cursor = params["cursor"]
+ return httpx.Response(
+ 200, json={"data": page, "cursor": {"next": next_cursor}}
+ )
+ if request.method == "DELETE":
+ return httpx.Response(204)
+ return httpx.Response(404)
+
+
+def protocol_agent(monkeypatch, tmp_path):
+ server = _ProtocolServer()
+ real_client = httpx.Client
+ monkeypatch.setattr(
+ httpx,
+ "Client",
+ lambda **kwargs: real_client(**kwargs, transport=httpx.MockTransport(server)),
+ )
+ agent = opencode.OpenCodeAgent(
+ SimpleNamespace(_host="http://engine.invalid"),
+ "local-model",
+ workspace=str(tmp_path),
+ api_version="auto",
+ server_password=server.password,
+ )
+ agent._base = "http://fixture.invalid"
+ monkeypatch.setattr(agent, "_ensure_server", lambda: agent._base)
+ return server, agent
+
+
+def test_v2_final_answer_and_cached_detection(protocol_agent):
+ server, agent = protocol_agent
+ assert agent.run("First task").content == "Final answer."
+ result = agent.run("Second task")
+ assert result.content == "Final answer."
+ assert result.metadata["api_version"] == "v2"
+ assert sum(r.url.path == "/session" for r in server.calls) == 1
+
+
+def test_v1_model_payload_and_reply_remain_compatible(protocol_agent):
+ server, agent = protocol_agent
+ server.version = "v1"
+ result = agent.run("Task")
+ assert result.content == "V1 final answer."
+ assert result.metadata["api_version"] == "v1"
+ prompt = next(
+ r
+ for r in server.calls
+ if r.method == "POST" and r.url.path.endswith("/message")
+ )
+ assert json.loads(prompt.content)["model"] == {
+ "providerID": "openjarvis",
+ "modelID": "local-model",
+ }
+ assert not any("/wait" in r.url.path for r in server.calls)
+
+
+def test_v2_reads_all_pages_and_preserves_tool_results(protocol_agent):
+ server, agent = protocol_agent
+ server.messages = []
+ for number in range(1, 206):
+ server.messages.append(
+ _assistant(
+ number,
+ "",
+ finish="tool-calls",
+ content=[
+ {
+ "type": "tool",
+ "id": f"call_{number}",
+ "name": "read",
+ "time": {"created": number},
+ "state": {
+ "status": "completed",
+ "input": {},
+ "content": [{"type": "text", "text": f"Result {number}"}],
+ },
+ }
+ ],
+ )
+ )
+ server.messages.append(_assistant(206, "Final answer."))
+ server.messages.append(_idle(207))
+ result = agent.run("Long task")
+ assert result.content == "Final answer."
+ assert len(result.tool_results) == 205
+ assert [r.content for r in result.tool_results] == [
+ f"Result {number}" for number in range(1, 206)
+ ]
+ assert all(r.success for r in result.tool_results)
+ pages = [r for r in server.calls if r.method == "GET"]
+ assert len(pages) == 3 # 200, 7, then the empty cursor terminator
+
+
[email protected]("status", [401, 404, 503])
+def test_v2_wait_http_failure_is_an_error(protocol_agent, status):
+ server, agent = protocol_agent
+ server.wait_status = status
+ result = agent.run("Task")
+ assert result.metadata.get("error") is True
+ assert not any(r.method == "GET" for r in server.calls)
+
+
+def test_v2_wait_timeout_is_an_error(protocol_agent):
+ server, agent = protocol_agent
+ server.wait_timeout = True
+ result = agent.run("Task")
+ assert result.metadata.get("error") is True
+ assert not any(r.method == "GET" for r in server.calls)
+
+
+def test_v2_transcript_http_failure_is_an_error(protocol_agent):
+ server, agent = protocol_agent
+ server.transcript_status = 500
+ result = agent.run("Task")
+ assert result.metadata.get("error") is True
+
+
+ "body", [{"data": None}, {"data": [None]}, {"data": [], "error": "failed"}]
+)
+def test_v2_invalid_or_empty_transcript_is_an_error(protocol_agent, body):
+ server, agent = protocol_agent
+ server.bad_transcript = body
+ assert agent.run("Task").metadata.get("error") is True
+
+
+def test_v2_repeated_cursor_fails_instead_of_looping(protocol_agent):
+ server, agent = protocol_agent
+ server.repeat_cursor = True
+ result = agent.run("Task")
+ assert result.metadata.get("error") is True
+ assert "repeated" in result.content
+ assert sum(r.method == "GET" for r in server.calls) == 2
+
+
+ "changes",
+ [
+ {"finish": None},
+ {"finish": "unknown"},
+ {"finish": "content-filter"},
+ {"finish": "error"},
+ {
+ "error": {
+ "type": "provider",
+ "message": "Provider rejected request",
+ "status": 429,
+ }
+ },
+ ],
+)
+def test_v2_failed_assistant_is_an_error(protocol_agent, changes):
+ server, agent = protocol_agent
+ server.messages = [_assistant(2, "Partial text", **changes), _idle(3)]
+ result = agent.run("Task")
+ assert result.metadata.get("error") is True
+
+
[email protected]("finish", [None, "tool-calls", "stop", "length"])
+def test_v2_missing_terminal_marker_is_an_error(protocol_agent, finish):
+ server, agent = protocol_agent
+ server.messages = [_assistant(2, "Partial text", finish=finish)]
+ assert agent.run("Task").metadata.get("error") is True
+
+
[email protected]("outcome", ["failed", "interrupted"])
[email protected]("finish", ["stop", "length"])
+def test_v2_idle_failure_is_not_successful_completion(protocol_agent, outcome, finish):
+ server, agent = protocol_agent
+ server.messages = [
+ _assistant(2, "Partial text", finish=finish),
+ _idle(
+ 3,
+ outcome,
+ error={"type": "output-limit", "message": "Output limit reached"},
+ ),
+ ]
+ result = agent.run("Task")
+ assert result.metadata.get("error") is True
+ assert "Output limit reached" in result.content
+
+
+def test_v2_old_idle_marker_cannot_complete_a_new_reply(protocol_agent):
+ server, agent = protocol_agent
+ server.messages = [
+ _assistant(2, "Earlier reply"),
+ _idle(3),
+ _assistant(4, "Partial"),
+ ]
+ assert agent.run("Task").metadata.get("error") is True
+
+
[email protected]("finish", ["stop", "length", "tool-calls"])
+def test_v2_successful_idle_is_authoritative(protocol_agent, finish):
+ server, agent = protocol_agent
+ server.messages = [_assistant(2, "Completed", finish=finish), _idle(3)]
+ result = agent.run("Task")
+ assert not result.metadata.get("error")
+ assert result.content == "Completed"
+ assert result.metadata["finish"] == finish
+
+
[email protected]("version", ["v1", "v2"])
+def test_startup_generated_password_authenticates_over_http(
+ monkeypatch, tmp_path, version
+):
+ """Exercise _ensure_server, its process environment and the real HTTP client."""
+ monkeypatch.delenv("OPENCODE_PASSWORD", raising=False)
+ monkeypatch.delenv("OPENCODE_SERVER_PASSWORD", raising=False)
+ protocol = _ProtocolServer(version=version)
+
+ class Handler(BaseHTTPRequestHandler):
+ def handle_request(self):
+ body = self.rfile.read(int(self.headers.get("Content-Length", "0")))
+ response = protocol(
+ httpx.Request(
+ self.command,
+ f"http://localhost{self.path}",
+ headers=dict(self.headers),
+ content=body,
+ )
+ )
+ self.send_response(response.status_code)
+ self.send_header("Content-Type", "application/json")
+ self.send_header("Content-Length", str(len(response.content)))
+ self.end_headers()
+ self.wfile.write(response.content)
+
+ do_POST = do_GET = do_DELETE = handle_request
+
+ def log_message(self, *args):
+ pass
+
+ httpd = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+ worker = threading.Thread(target=httpd.serve_forever, daemon=True)
+ worker.start()
+ url = f"http://127.0.0.1:{httpd.server_port}"
+ spawned = {}
+
+ def spawn(*args, **kwargs):
+ env = kwargs["env"]
+ assert env["OPENCODE_PASSWORD"] == env["OPENCODE_SERVER_PASSWORD"]
+ assert len(env["OPENCODE_PASSWORD"]) >= 32
+ protocol.password = env["OPENCODE_PASSWORD"]
+ spawned.update(kwargs)
+ return SimpleNamespace(
+ stdout=io.StringIO(f"server listening on {url}\n"),
+ poll=lambda: None,
+ terminate=lambda: None,
+ wait=lambda **kw: None,
+ )
+
+ monkeypatch.setattr(opencode, "is_opencode_available", lambda: True)
+ monkeypatch.setattr(opencode.subprocess, "Popen", spawn)
+ agent = opencode.OpenCodeAgent(
+ SimpleNamespace(_host="http://engine.invalid"),
+ "local-model",
+ workspace=str(tmp_path),
+ )
+ try:
+ result = agent.run("Task")
+ assert not result.metadata.get("error"), result.content
+ assert result.content == (
+ "V1 final answer." if version == "v1" else "Final answer."
+ )
+ assert protocol.password not in result.content
+ assert spawned
+ finally:
+ agent.close()
+ httpd.shutdown()
+ httpd.server_close()
+ worker.join()
+
+
+ "explicit,modern,legacy,expected",
+ [
+ ("explicit", "modern", "legacy", "explicit"),
+ ("", "modern", "legacy", "modern"),
+ ("", "", "legacy", "legacy"),
+ ],
+)
+def test_server_password_precedence(monkeypatch, explicit, modern, legacy, expected):
+ monkeypatch.setenv("OPENCODE_PASSWORD", modern)
+ monkeypatch.setenv("OPENCODE_SERVER_PASSWORD", legacy)
+ agent = opencode.OpenCodeAgent(
+ SimpleNamespace(), "provider/model", server_password=explicit
+ )
+ with agent._client() as client:
+ assert (
+ client.headers["authorization"]
+ == "Basic " + base64.b64encode(f"opencode:{expected}".encode()).decode()
+ )