Personal AI, On Personal Devices
Python
feat(agents): add OpenCodeAgent — run the opencode coding agent on a local engine
krypticmouse4fa9163ea95e
diff --git a/docs/user-guide/agents.md b/docs/user-guide/agents.mdindex 2a988f54..8cec9dd6 100644--- a/docs/user-guide/agents.md+++ b/docs/user-guide/agents.md@@ -13,6 +13,7 @@ Agents are the agentic logic layer of OpenJarvis. They determine how a query is| `RLMAgent` | `rlm` | Yes | Yes | Recursive LM with persistent REPL || `OpenHandsAgent` | `openhands` | No | Yes | Wraps real openhands-sdk || `ClaudeCodeAgent` | `claude_code` | No | Yes | Claude Agent SDK via Node.js subprocess |+| `OpenCodeAgent` | `opencode` | No | Yes | [opencode](https://opencode.ai) coding agent on your local engine || `OperativeAgent` | `operative` | Yes | Yes | Persistent scheduled agent with state management || `MonitorOperativeAgent` | `monitor_operative` | Yes | Yes | Long-horizon agent with 4 configurable strategy axes |@@ -383,6 +384,54 @@ jarvis ask --agent claude_code "Refactor the tests to use pytest fixtures"---+## OpenCodeAgent++The `OpenCodeAgent` delegates coding tasks to [opencode](https://opencode.ai), the open-source coding agent, running it **on your local engine**. opencode handles the agentic loop, file edits, and tool use; OpenJarvis supplies the model — keeping coding-agent work local-first.++!!! warning "Requirements"+ Requires the `opencode` binary on `PATH` (`npm i -g opencode-ai` or `brew install anomalyco/tap/opencode`). It is **not** bundled; `run()` returns a clear error if it is missing. No `ANTHROPIC_API_KEY` needed — inference goes through your OpenJarvis engine.++**How it works:**++1. Derives an OpenAI-compatible base URL from the `engine` (e.g. Ollama/vLLM/llama.cpp at `<host>/v1`) and writes an `opencode.json` in the workspace registering it as an `@ai-sdk/openai-compatible` provider (`openjarvis/<model>`).+2. Spawns a headless `opencode serve` (loopback, random port) and waits for `/global/health`.+3. Creates a session (`POST /session`) and sends the task (`POST /session/{id}/message`) with `model={providerID, modelID}` and the selected `agent` (`build` or `plan`).+4. Parses the returned message `parts` — text parts → `content`, tool parts → `tool_results` — into an `AgentResult`.+5. `close()` disposes the session/server.++**Constructor parameters (selected):**++| Parameter | Type | Default | Description |+|---------------------|-------------------|------------------|----------------------------------------------------------|+| `engine` | `InferenceEngine` | -- | Used to derive the local OpenAI-compatible provider URL |+| `model` | `str` | -- | Model id served at the provider (e.g. `qwen3:8b`) |+| `workspace` | `str` | `os.getcwd()` | Directory opencode operates in |+| `agent` | `str` | `"build"` | opencode agent: `build` (full access) or `plan` (read-only) |+| `provider_base_url` | `str` | derived | Override the engine-derived OpenAI base URL |+| `provider_id` | `str` | `"openjarvis"` | opencode provider id to register/use |+| `model_id` | `str` | `model` | Model id within the provider |+| `server_password` | `str` | `$OPENCODE_SERVER_PASSWORD` | Optional basic-auth for the opencode server |+| `timeout` | `int` | `600` | HTTP timeout in seconds |++```python+from openjarvis.agents.opencode import OpenCodeAgent++agent = OpenCodeAgent(engine, "qwen3:8b", workspace="/path/to/project", agent="build")+result = agent.run("Add type hints to utils.py and run the tests")+print(result.content)+agent.close()+```++```bash+# Via CLI (opencode must be installed)+jarvis ask --agent opencode "Refactor the parser to use a state machine"+```++!!! tip "Pass-through providers"+ If the `engine` has no derivable base URL, pass `model` as `provider/model` (e.g. `ollama/llama3`) and opencode resolves it from its own configuration — no `opencode.json` is written.++---+## OperativeAgentThe `OperativeAgent` is a persistent, scheduled autonomous agent with built-in session persistence and state recall. Designed for "Operators" -- autonomous agents that run on a schedule with automatic state management between ticks. Extends `ToolUsingAgent`.diff --git a/src/openjarvis/agents/__init__.py b/src/openjarvis/agents/__init__.pyindex 506e2c13..e616628e 100644--- a/src/openjarvis/agents/__init__.py+++ b/src/openjarvis/agents/__init__.py@@ -54,6 +54,11 @@ try:except ImportError:pass+try:+ import openjarvis.agents.opencode # noqa: F401+except ImportError:+ pass+try:import openjarvis.agents.operative # noqa: F401except ImportError:diff --git a/src/openjarvis/agents/opencode.py b/src/openjarvis/agents/opencode.pynew file mode 100644index 00000000..a53cce11--- /dev/null+++ b/src/openjarvis/agents/opencode.py@@ -0,0 +1,332 @@+"""OpenCodeAgent -- wraps the `opencode` coding agent via its headless HTTP server.++Spawns ``opencode serve`` (https://opencode.ai) and drives a session over its+HTTP API, configured to use OpenJarvis's local engine through an+OpenAI-compatible provider. This keeps coding-agent work local-first: opencode+handles the agentic loop / tools, OpenJarvis supplies the model.++opencode is an external binary (install: ``npm i -g opencode-ai`` or+``brew install anomalyco/tap/opencode``). It is not bundled; :meth:`run`+raises a clear error if it is not on ``PATH``.+"""++from __future__ import annotations++import json+import logging+import os+import re+import shutil+import subprocess+import time+from pathlib import Path+from typing import Any, List, Optional++from openjarvis.agents._stubs import AgentContext, AgentResult, BaseAgent+from openjarvis.core.events import EventBus+from openjarvis.core.registry import AgentRegistry+from openjarvis.core.types import ToolResult+from openjarvis.engine._stubs import InferenceEngine++logger = logging.getLogger(__name__)++_LISTENING_RE = re.compile(r"listening on\s+(https?://\S+)", re.IGNORECASE)+++def is_opencode_available() -> bool:+ """Return True if the ``opencode`` binary is on PATH."""+ return shutil.which("opencode") is not None+++def _derive_openai_base_url(engine: Any) -> str:+ """Best-effort OpenAI-compatible base URL for an OpenJarvis engine.++ HTTP engines (Ollama, vLLM, llama.cpp, SGLang, LM Studio, …) expose a+ ``_host`` and serve an OpenAI-compatible API at ``<host>/v1``. Returns ""+ when it cannot be derived (caller then requires an explicit base URL or a+ pre-configured opencode provider).+ """+ for attr in ("openai_base_url", "base_url"):+ val = getattr(engine, attr, "")+ if val:+ return str(val).rstrip("/")+ host = getattr(engine, "_host", "") or getattr(engine, "host", "")+ if host:+ host = str(host).rstrip("/")+ return host if host.endswith("/v1") else f"{host}/v1"+ return ""+++def _extract_text(parts: List[dict]) -> str:+ """Join the assistant's text parts from an opencode message response."""+ return "".join(+ p.get("text", "")+ for p in parts+ if isinstance(p, dict) and p.get("type") == "text"+ ).strip()+++def _extract_tool_results(parts: List[dict]) -> List[ToolResult]:+ """Map opencode ``tool`` parts to OpenJarvis ToolResults (best-effort)."""+ results: List[ToolResult] = []+ for p in parts:+ if not isinstance(p, dict) or p.get("type") != "tool":+ continue+ state = p.get("state", {}) if isinstance(p.get("state"), dict) else {}+ status = state.get("status", "")+ output = state.get("output")+ 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")),+ content=str(output),+ success=status not in ("error", "failed"),+ )+ )+ return results++[email protected]("opencode")+class OpenCodeAgent(BaseAgent):+ """Agent that delegates coding tasks to a local ``opencode`` server.++ 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).+ """++ agent_id = "opencode"+ accepts_tools = False+ _default_temperature = 0.7+ _default_max_tokens = 1024++ def __init__(+ self,+ engine: InferenceEngine,+ model: str,+ *,+ bus: Optional[EventBus] = None,+ temperature: Optional[float] = None,+ max_tokens: Optional[int] = None,+ workspace: str = "",+ agent: str = "build",+ provider_id: str = "openjarvis",+ provider_base_url: str = "",+ model_id: str = "",+ api_key: str = "",+ hostname: str = "127.0.0.1",+ port: int = 0,+ server_password: str = "",+ timeout: int = 600,+ opencode_bin: str = "",+ ) -> None:+ super().__init__(+ engine,+ model,+ bus=bus,+ temperature=temperature,+ max_tokens=max_tokens,+ )+ self._workspace = workspace or os.getcwd()+ self._agent = agent+ self._provider_id = provider_id+ self._provider_base_url = provider_base_url or _derive_openai_base_url(engine)+ self._model_id = model_id or model+ self._api_key = api_key+ self._hostname = hostname+ self._port = port+ self._server_password = server_password or os.environ.get(+ "OPENCODE_SERVER_PASSWORD", ""+ )+ self._timeout = timeout+ self._opencode_bin = opencode_bin or shutil.which("opencode") or "opencode"+ self._proc: Optional[subprocess.Popen] = None+ self._base: str = ""++ # ------------------------------------------------------------------+ # Server lifecycle+ # ------------------------------------------------------------------++ def _write_provider_config(self) -> None:+ """Register OpenJarvis's engine as an OpenAI-compatible opencode provider.++ Written to ``<workspace>/opencode.json`` (opencode reads project config+ from its working directory). Skipped when no base URL is available — in+ that case ``model`` is assumed to name a provider opencode already+ knows (e.g. ``ollama/llama3``).+ """+ if not self._provider_base_url:+ return+ cfg_path = Path(self._workspace) / "opencode.json"+ existing: dict = {}+ if cfg_path.exists():+ try:+ existing = json.loads(cfg_path.read_text(encoding="utf-8"))+ except (json.JSONDecodeError, OSError):+ existing = {}+ options: dict = {"baseURL": self._provider_base_url}+ if self._api_key:+ options["apiKey"] = self._api_key+ providers = existing.setdefault("provider", {})+ providers[self._provider_id] = {+ "npm": "@ai-sdk/openai-compatible",+ "name": "OpenJarvis Local",+ "options": options,+ "models": {self._model_id: {"name": self._model_id}},+ }+ existing.setdefault("$schema", "https://opencode.ai/config.json")+ cfg_path.write_text(json.dumps(existing, indent=2), encoding="utf-8")++ def _ensure_server(self) -> str:+ """Spawn ``opencode serve`` (once) and return its base URL."""+ if self._base and self._proc and self._proc.poll() is None:+ return self._base+ if not is_opencode_available() and not Path(self._opencode_bin).exists():+ raise RuntimeError(+ "OpenCodeAgent requires the 'opencode' binary. Install it with "+ "`npm i -g opencode-ai` or `brew install anomalyco/tap/opencode` "+ "(see https://opencode.ai)."+ )+ self._write_provider_config()+ env = dict(os.environ)+ if self._server_password:+ env["OPENCODE_SERVER_PASSWORD"] = self._server_password+ self._proc = subprocess.Popen(+ [+ self._opencode_bin,+ "serve",+ "--port",+ str(self._port),+ "--hostname",+ self._hostname,+ ],+ cwd=self._workspace,+ env=env,+ stdout=subprocess.PIPE,+ stderr=subprocess.STDOUT,+ text=True,+ )+ # Parse the "listening on <url>" line from startup output.+ deadline = time.monotonic() + 60+ base = ""+ assert self._proc.stdout is not None+ while time.monotonic() < deadline:+ line = self._proc.stdout.readline()+ if not line:+ if self._proc.poll() is not None:+ raise RuntimeError("opencode server exited during startup")+ continue+ m = _LISTENING_RE.search(line)+ if m:+ base = m.group(1).rstrip("/")+ break+ if not base:+ self.close()+ raise RuntimeError("opencode server did not report a listening URL")+ self._base = base+ return base++ def _client(self):+ import httpx++ headers = {}+ if self._server_password:+ import base64++ token = base64.b64encode(+ f"opencode:{self._server_password}".encode()+ ).decode()+ headers["Authorization"] = f"Basic {token}"+ return httpx.Client(base_url=self._base, headers=headers, timeout=self._timeout)++ def close(self) -> None:+ """Dispose the opencode session/server and terminate the process."""+ if self._base:+ try:+ with self._client() as c:+ c.post("/global/dispose")+ except Exception:+ pass+ if self._proc and self._proc.poll() is None:+ self._proc.terminate()+ try:+ self._proc.wait(timeout=10)+ except subprocess.TimeoutExpired:+ self._proc.kill()+ self._proc = None+ self._base = ""++ # ------------------------------------------------------------------+ # Run+ # ------------------------------------------------------------------++ def run(+ self,+ input: str,+ context: Optional[AgentContext] = None,+ **kwargs: Any,+ ) -> AgentResult:+ """Run a coding task through opencode and return the assistant result."""+ self._emit_turn_start(input)+ try:+ self._ensure_server()+ except RuntimeError as exc:+ self._emit_turn_end(turns=1, error=True)+ return AgentResult(+ content=str(exc), turns=1, metadata={"error": True}+ )++ 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,+ "parts": [{"type": "text", "text": input}],+ }+ if self._provider_base_url or "/" not in self._model_id:+ body["model"] = {+ "providerID": self._provider_id,+ "modelID": self._model_id,+ }+ else:+ prov, _, mid = self._model_id.partition("/")+ body["model"] = {"providerID": prov, "modelID": mid}++ resp = c.post(f"/session/{session_id}/message", json=body)+ resp.raise_for_status()+ data = resp.json()+ except Exception as exc:+ logger.error("opencode run failed: %s", exc, exc_info=True)+ self._emit_turn_end(turns=1, error=True)+ return AgentResult(+ content=f"opencode agent failed: {exc}",+ turns=1,+ metadata={"error": True},+ )++ parts = data.get("parts", []) if isinstance(data, dict) else []+ info = data.get("info", {}) if isinstance(data, dict) else {}+ content = _extract_text(parts)+ tool_results = _extract_tool_results(parts)++ self._emit_turn_end(turns=1)+ return AgentResult(+ content=content,+ 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,+ },+ )+++__all__ = ["OpenCodeAgent", "is_opencode_available"]diff --git a/tests/agents/test_opencode_agent.py b/tests/agents/test_opencode_agent.pynew file mode 100644index 00000000..27c2b21c--- /dev/null+++ b/tests/agents/test_opencode_agent.py@@ -0,0 +1,174 @@+"""Tests for OpenCodeAgent (wraps the `opencode` coding agent).++The pure helpers, provider-config wiring, graceful degradation, and response+parsing are tested without the `opencode` binary. SPIKE_RESPONSE is the actual+message shape captured from a live `opencode serve` session.+"""++from __future__ import annotations++import json+from types import SimpleNamespace++from openjarvis.agents.opencode import (+ OpenCodeAgent,+ _derive_openai_base_url,+ _extract_text,+ _extract_tool_results,+ is_opencode_available,+)++SPIKE_RESPONSE = {+ "info": {+ "role": "assistant",+ "agent": "build",+ "modelID": "local-model",+ "providerID": "openjarvis",+ "finish": "stop",+ "tokens": {"input": 0, "output": 0},+ "sessionID": "ses_x",+ "id": "msg_x",+ },+ "parts": [+ {"type": "step-start"},+ {"type": "text", "text": "Hello from the local model. "},+ {"type": "step-finish", "reason": "stop"},+ ],+}+++class TestPartParsing:+ def test_extract_text_joins_text_parts(self):+ assert _extract_text(SPIKE_RESPONSE["parts"]) == "Hello from the local model."++ def test_extract_text_ignores_non_text(self):+ assert _extract_text([{"type": "step-start"}, {"type": "tool"}]) == ""++ def test_extract_tool_results_success(self):+ parts = [{"type": "tool", "tool": "bash",+ "state": {"status": "completed", "output": "ok"}}]+ tr = _extract_tool_results(parts)+ assert len(tr) == 1+ assert tr[0].tool_name == "bash"+ assert tr[0].content == "ok"+ assert tr[0].success is True++ def test_extract_tool_results_error(self):+ parts = [{"type": "tool", "tool": "edit",+ "state": {"status": "error", "output": "boom"}}]+ assert _extract_tool_results(parts)[0].success is False+++class TestDeriveBaseUrl:+ def test_from_host_appends_v1(self):+ eng = SimpleNamespace(_host="http://localhost:11434")+ assert _derive_openai_base_url(eng) == "http://localhost:11434/v1"++ def test_host_already_v1(self):+ eng = SimpleNamespace(_host="http://x:8000/v1")+ assert _derive_openai_base_url(eng) == "http://x:8000/v1"++ def test_explicit_base_url_attr(self):+ eng = SimpleNamespace(base_url="http://y/v1")+ assert _derive_openai_base_url(eng) == "http://y/v1"++ def test_none_when_unknown(self):+ assert _derive_openai_base_url(SimpleNamespace()) == ""+++class TestAvailability:+ def test_true(self, monkeypatch):+ monkeypatch.setattr("openjarvis.agents.opencode.shutil.which",+ lambda n: "/usr/bin/opencode")+ assert is_opencode_available() is True++ def test_false(self, monkeypatch):+ monkeypatch.setattr("openjarvis.agents.opencode.shutil.which", lambda n: None)+ assert is_opencode_available() is False+++class TestProviderConfig:+ def test_writes_provider(self, tmp_path):+ agent = OpenCodeAgent(SimpleNamespace(_host="http://localhost:11434"),+ "qwen3:8b", workspace=str(tmp_path))+ agent._write_provider_config()+ cfg = json.loads((tmp_path / "opencode.json").read_text())+ prov = cfg["provider"]["openjarvis"]+ assert prov["npm"] == "@ai-sdk/openai-compatible"+ assert prov["options"]["baseURL"] == "http://localhost:11434/v1"+ assert "qwen3:8b" in prov["models"]++ def test_merges_existing(self, tmp_path):+ (tmp_path / "opencode.json").write_text(+ json.dumps({"theme": "dark", "provider": {"other": {}}})+ )+ OpenCodeAgent(SimpleNamespace(_host="http://h:1"), "m",+ workspace=str(tmp_path))._write_provider_config()+ cfg = json.loads((tmp_path / "opencode.json").read_text())+ assert cfg["theme"] == "dark" # preserved+ assert "other" in cfg["provider"] and "openjarvis" in cfg["provider"]++ def test_skips_when_no_base_url(self, tmp_path):+ # No derivable base URL + pre-namespaced model -> rely on opencode's+ # own provider; don't write a config.+ OpenCodeAgent(SimpleNamespace(), "ollama/llama3",+ workspace=str(tmp_path))._write_provider_config()+ assert not (tmp_path / "opencode.json").exists()+++class TestRunGracefulDegradation:+ def test_missing_binary_returns_error_result(self, monkeypatch, tmp_path):+ monkeypatch.setattr("openjarvis.agents.opencode.shutil.which", lambda n: None)+ agent = OpenCodeAgent(SimpleNamespace(_host="http://h:1"), "m",+ workspace=str(tmp_path),+ opencode_bin="/nonexistent/opencode")+ res = agent.run("do something")+ assert res.metadata.get("error") is True+ assert "opencode" in res.content.lower()+++class _FakeResp:+ def __init__(self, data):+ self._d = data++ def raise_for_status(self):+ pass++ def json(self):+ return self._d+++class _FakeClient:+ def __enter__(self):+ return self++ def __exit__(self, *a):+ return False++ def post(self, path, json=None):+ if path == "/session":+ return _FakeResp({"id": "ses_x"})+ if path.endswith("/message"):+ _FakeClient.last_body = json+ return _FakeResp(SPIKE_RESPONSE)+ return _FakeResp({})+++class TestRunParsing:+ def test_run_parses_message(self, monkeypatch, tmp_path):+ agent = OpenCodeAgent(SimpleNamespace(_host="http://h:1"), "local-model",+ workspace=str(tmp_path), agent="build")+ 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: _FakeClient())++ res = agent.run("Write a hello world")+ assert res.content == "Hello from the local model."+ assert res.metadata["finish"] == "stop"+ assert res.metadata["model_id"] == "local-model"+ assert res.metadata["agent"] == "build"+ # the model was addressed as openjarvis/local-model+ assert _FakeClient.last_body["model"] == {+ "providerID": "openjarvis", "modelID": "local-model"+ }+ assert _FakeClient.last_body["agent"] == "build"