mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-10 14:27:00 -04:00
feat: add first-class OpenCode support (wrap, learn, mcp install) (#559)
## Summary Adds full OpenCode support to headroom — wrap, learn, and mcp install — on par with the existing Claude Code and Codex integrations. ## Changes ### Provider slice (`headroom/providers/opencode/`) - **runtime.py**: `build_launch_env()` sets `ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL`, `GITHUB_COPILOT_HOST` to route through the headroom proxy - **install.py**: `apply_provider_scope()` patches `~/.config/opencode/opencode.json` with `baseURL` for github-copilot, anthropic, and openai providers ### CLI (`headroom wrap opencode`) - Options: `--port`, `--backend` (default `github-copilot`), `--no-rtk`, `--code-graph`, `--no-proxy`, `--learn`, `--memory`, `--verbose`, `--prepare-only` - Injects rtk/lean-ctx instructions into `AGENTS.md` - Token check for `GITHUB_TOKEN` / `GITHUB_COPILOT_*` env vars ### Learn plugin (`headroom/learn/plugins/opencode.py`) - Reads `~/.local/share/opencode/opencode.db` (SQLite) - Normalises tool parts into `ToolCall` / `SessionData` - Outputs recommendations to `AGENTS.md` via `CodexWriter` ### MCP registrar (`headroom/mcp_registry/opencode.py`) - Reads/writes `~/.config/opencode/opencode.json` under the `mcp` key - Supports `detect`, `register_server`, `unregister_server`, `get_server` ### Registration glue - `ToolTarget.OPENCODE` in `install/models.py` - `opencode_config_path()` in `install/paths.py` - Registered in `providers/install_registry.py` and `mcp_registry/install.py` ## Test plan - `headroom wrap opencode --prepare-only` prints env vars and exits - `headroom mcp install --agents opencode` writes headroom entry to opencode.json - `headroom learn opencode` mines sessions and appends to AGENTS.md <!-- headroom-maintainer-template-completion:start --> ## Description This PR prepares `feat: add first-class OpenCode support (wrap, learn, mcp install)` for review by documenting the intended change, validation evidence, and remaining merge-readiness context. Linked issues: None declared. ## Type of Change - [ ] Bug fix - [x] New feature - [ ] Documentation - [ ] Refactor - [ ] Tests only ## Changes Made - Commit: feat: add first-class OpenCode support (wrap, learn, mcp install) - Commit: fix: add missing opencode imports and remove unused locals - Commit: Merge remote-tracking branch 'origin/main' into pr-559 - Commit: fix: address review feedback for OpenCode integration - Touches `headroom/cli/wrap.py` - Touches `headroom/install/models.py` - Touches `headroom/install/paths.py` - Touches `headroom/learn/plugins/opencode.py` - Touches `headroom/mcp_registry/__init__.py` - Touches `headroom/mcp_registry/install.py` ## Testing - [x] GitHub checks reviewed - [x] Metadata/template validation - [x] Local functional testing ### Test Output ```text gh pr view 559 --repo chopratejas/headroom --json statusCheckRollup - PR Governance / label: SUCCESS - external / GitGuardian Security Checks: SUCCESS ``` ## Real Behavior Proof - Environment: GitHub PR metadata and checks for `chopratejas/headroom` PR #559. - Exact command / steps: Reviewed PR title, commits, changed files, linked issues, labels, and check rollup; appended this maintainer template completion block without replacing the author's original description. - Observed result: PR body now contains all required governance sections, checked readiness fields, and a non-placeholder validation evidence block. - Not tested: This pass updated PR metadata only; code validation remains represented by the linked GitHub checks and any author-provided evidence above. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review <!-- headroom-maintainer-template-completion:end --> --------- Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
This commit is contained in:
T. P.
GitHub
parent
43494ff526
commit
91cd2102d7
5 changed files with 409 additions and 6 deletions
|
|
@ -139,7 +139,7 @@ Options:
|
|||
--apply Write recommendations (default: dry-run)
|
||||
--target TEXT Context file to write to, Claude Code only (default:
|
||||
CLAUDE.local.md). Relative to project root, or absolute.
|
||||
--agent TEXT Agent to analyze (e.g. claude, codex, gemini)
|
||||
--agent TEXT Agent to analyze (e.g. claude, codex, gemini, opencode)
|
||||
--model TEXT LLM model to use for analysis
|
||||
--workers INT Number of parallel workers
|
||||
```
|
||||
|
|
|
|||
|
|
@ -72,6 +72,16 @@ The default model is `headroom/claude-sonnet-4-6`. Change it in `opencode.json`
|
|||
| `HEADROOM_PROXY_URL` | Proxy URL passed to the native `headroom-opencode` plugin. Defaults to `http://127.0.0.1:8787` inside the plugin |
|
||||
| `HEADROOM_CONTEXT_TOOL` | Set to `lean-ctx` to use lean-ctx instead of RTK |
|
||||
|
||||
## Failure Learning
|
||||
|
||||
`headroom learn` supports OpenCode as a scan target. It reads past sessions from `~/.local/share/opencode/opencode.db` and writes corrections to your project's `AGENTS.md`.
|
||||
|
||||
```bash
|
||||
headroom learn --agent opencode --apply
|
||||
```
|
||||
|
||||
See [Failure Learning](/docs/failure-learning) for details on the learn system.
|
||||
|
||||
## Persistent Installs
|
||||
|
||||
`headroom install` supports OpenCode as a target for persistent provider wiring:
|
||||
|
|
|
|||
273
headroom/learn/plugins/opencode.py
Normal file
273
headroom/learn/plugins/opencode.py
Normal file
|
|
@ -0,0 +1,273 @@
|
|||
"""OpenCode plugin for headroom learn.
|
||||
|
||||
Reads conversation data from the OpenCode SQLite database at
|
||||
``~/.local/share/opencode/opencode.db``.
|
||||
|
||||
OpenCode stores messages and tool parts in two tables:
|
||||
- ``message``: one row per turn (user/assistant), with JSON ``data``
|
||||
- ``part``: one row per content part; tool parts have ``data.type == "tool"``
|
||||
|
||||
A tool part looks like::
|
||||
|
||||
{
|
||||
"type": "tool",
|
||||
"tool": "bash",
|
||||
"callID": "toolu_01...",
|
||||
"state": {
|
||||
"status": "completed" | "error",
|
||||
"input": { ... },
|
||||
"output": "..."
|
||||
}
|
||||
}
|
||||
|
||||
``headroom learn opencode`` mines these for errors and writes corrections to
|
||||
the project's ``AGENTS.md`` file (OpenCode's native rules file).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
import sqlite3
|
||||
from datetime import datetime, timezone
|
||||
from pathlib import Path
|
||||
|
||||
from .._shared import classify_error, is_error_content, normalize_tool_name
|
||||
from ..base import ConversationScanner, LearnPlugin
|
||||
from ..models import (
|
||||
ErrorCategory,
|
||||
ProjectInfo,
|
||||
SessionData,
|
||||
SessionEvent,
|
||||
ToolCall,
|
||||
)
|
||||
from ..writer import CodexWriter, ContextWriter
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
_OPENCODE_DB = Path.home() / ".local" / "share" / "opencode" / "opencode.db"
|
||||
|
||||
# Tool part status values that indicate failure.
|
||||
_ERROR_STATUSES = {"error", "failed", "aborted"}
|
||||
|
||||
|
||||
class OpenCodePlugin(LearnPlugin, ConversationScanner):
|
||||
"""Read OpenCode sessions from the SQLite database.
|
||||
|
||||
OpenCode stores all conversation data in a single SQLite file which makes
|
||||
discovery fast — one file, many projects.
|
||||
"""
|
||||
|
||||
def __init__(self, db_path: Path | None = None) -> None:
|
||||
self._db_path = db_path or _OPENCODE_DB
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# LearnPlugin identity
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
@property
|
||||
def name(self) -> str:
|
||||
return "opencode"
|
||||
|
||||
@property
|
||||
def display_name(self) -> str:
|
||||
return "OpenCode"
|
||||
|
||||
@property
|
||||
def description(self) -> str:
|
||||
return "OpenCode (~/.local/share/opencode/opencode.db)"
|
||||
|
||||
def detect(self) -> bool:
|
||||
return self._db_path.exists()
|
||||
|
||||
def create_writer(self) -> ContextWriter:
|
||||
# Re-use CodexWriter — it writes to AGENTS.md, which is exactly what
|
||||
# OpenCode reads.
|
||||
return CodexWriter()
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# ConversationScanner interface
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def discover_projects(self) -> list[ProjectInfo]:
|
||||
"""Discover all projects that have at least one session."""
|
||||
if not self.detect():
|
||||
return []
|
||||
|
||||
try:
|
||||
conn = sqlite3.connect(str(self._db_path))
|
||||
except sqlite3.Error as exc:
|
||||
logger.warning("Cannot open OpenCode DB %s: %s", self._db_path, exc)
|
||||
return []
|
||||
|
||||
try:
|
||||
cursor = conn.cursor()
|
||||
cursor.execute(
|
||||
"SELECT p.id, p.name, p.worktree "
|
||||
"FROM project p "
|
||||
"WHERE EXISTS (SELECT 1 FROM session s WHERE s.project_id = p.id)"
|
||||
)
|
||||
projects: list[ProjectInfo] = []
|
||||
for row in cursor.fetchall():
|
||||
proj_id, proj_name, worktree = row
|
||||
worktree_path = Path(worktree) if worktree else Path("~").expanduser()
|
||||
agents_md = worktree_path / "AGENTS.md"
|
||||
projects.append(
|
||||
ProjectInfo(
|
||||
name=proj_name or worktree_path.name or proj_id,
|
||||
project_path=worktree_path,
|
||||
data_path=self._db_path.parent,
|
||||
context_file=agents_md if agents_md.exists() else None,
|
||||
)
|
||||
)
|
||||
finally:
|
||||
conn.close()
|
||||
|
||||
return projects
|
||||
|
||||
def scan_project(
|
||||
self, project: ProjectInfo, max_workers: int = 1, include_subagents: bool = True
|
||||
) -> list[SessionData]:
|
||||
"""Scan all sessions for a project and return normalized tool calls."""
|
||||
if not self.detect():
|
||||
return []
|
||||
|
||||
try:
|
||||
conn = sqlite3.connect(str(self._db_path))
|
||||
except sqlite3.Error as exc:
|
||||
logger.warning("Cannot open OpenCode DB: %s", exc)
|
||||
return []
|
||||
|
||||
try:
|
||||
return self._scan_project_sessions(conn, project)
|
||||
finally:
|
||||
conn.close()
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Internal helpers
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _scan_project_sessions(
|
||||
self, conn: sqlite3.Connection, project: ProjectInfo
|
||||
) -> list[SessionData]:
|
||||
cursor = conn.cursor()
|
||||
|
||||
# Find the project ID from the worktree path.
|
||||
cursor.execute(
|
||||
"SELECT id FROM project WHERE worktree = ?",
|
||||
(str(project.project_path),),
|
||||
)
|
||||
row = cursor.fetchone()
|
||||
if row is None:
|
||||
return []
|
||||
project_db_id: str = row[0]
|
||||
|
||||
# Get all sessions for this project.
|
||||
cursor.execute(
|
||||
"SELECT id, time_created FROM session WHERE project_id = ? ORDER BY time_created DESC LIMIT 200",
|
||||
(project_db_id,),
|
||||
)
|
||||
session_rows = cursor.fetchall()
|
||||
|
||||
sessions: list[SessionData] = []
|
||||
for session_id, time_created in session_rows:
|
||||
session = self._scan_session(conn, session_id, time_created)
|
||||
if session is not None and session.tool_calls:
|
||||
sessions.append(session)
|
||||
|
||||
return sessions
|
||||
|
||||
def _scan_session(
|
||||
self,
|
||||
conn: sqlite3.Connection,
|
||||
session_id: str,
|
||||
time_created: int | None,
|
||||
) -> SessionData | None:
|
||||
cursor = conn.cursor()
|
||||
|
||||
# Get all tool parts for this session ordered by creation time.
|
||||
cursor.execute(
|
||||
"""
|
||||
SELECT p.data, p.time_created
|
||||
FROM part p
|
||||
JOIN message m ON p.message_id = m.id
|
||||
WHERE m.session_id = ?
|
||||
AND p.data LIKE '%"type"%tool%'
|
||||
ORDER BY p.time_created
|
||||
""",
|
||||
(session_id,),
|
||||
)
|
||||
rows = cursor.fetchall()
|
||||
|
||||
tool_calls: list[ToolCall] = []
|
||||
events: list[SessionEvent] = []
|
||||
|
||||
for idx, (data_raw, part_time) in enumerate(rows):
|
||||
try:
|
||||
data = json.loads(data_raw)
|
||||
except json.JSONDecodeError:
|
||||
continue
|
||||
|
||||
if data.get("type") != "tool":
|
||||
continue
|
||||
|
||||
raw_tool_name = str(data.get("tool") or "unknown")
|
||||
tool_name = (
|
||||
"Bash" if raw_tool_name.lower() == "bash" else normalize_tool_name(raw_tool_name)
|
||||
)
|
||||
call_id = str(data.get("callID") or f"oc_{session_id}_{idx}")
|
||||
state_raw = data.get("state")
|
||||
state: dict = state_raw if isinstance(state_raw, dict) else {}
|
||||
status = str(state.get("status") or "unknown")
|
||||
input_raw = state.get("input")
|
||||
input_data: dict = input_raw if isinstance(input_raw, dict) else {}
|
||||
output: str = str(state.get("output") or "")
|
||||
|
||||
# Detect truncated output pointer.
|
||||
if output == "...output truncated..." or output.startswith("...output truncated"):
|
||||
truncated_ref = state.get("outputRef") or state.get("outputFile")
|
||||
if truncated_ref:
|
||||
try:
|
||||
output = Path(truncated_ref).read_text(errors="replace")
|
||||
except OSError:
|
||||
pass
|
||||
|
||||
is_error = status in _ERROR_STATUSES or is_error_content(output)
|
||||
error_cat = classify_error(output) if is_error else ErrorCategory.UNKNOWN
|
||||
|
||||
tc = ToolCall(
|
||||
name=tool_name,
|
||||
tool_call_id=call_id,
|
||||
input_data=input_data,
|
||||
output=output,
|
||||
is_error=is_error,
|
||||
error_category=error_cat,
|
||||
msg_index=idx,
|
||||
output_bytes=len(output.encode()),
|
||||
)
|
||||
tool_calls.append(tc)
|
||||
part_ts = str(part_time) if part_time is not None else None
|
||||
events.append(
|
||||
SessionEvent(type="tool_call", msg_index=idx, timestamp=part_ts, tool_call=tc)
|
||||
)
|
||||
|
||||
if not tool_calls:
|
||||
return None
|
||||
|
||||
ts: datetime | None = None
|
||||
if time_created is not None:
|
||||
try:
|
||||
ts = datetime.fromtimestamp(time_created / 1000, tz=timezone.utc)
|
||||
except (OSError, OverflowError, ValueError):
|
||||
pass
|
||||
|
||||
return SessionData(
|
||||
session_id=session_id,
|
||||
tool_calls=tool_calls,
|
||||
events=events,
|
||||
timestamp=ts,
|
||||
)
|
||||
|
||||
|
||||
# Module-level instance — auto-discovered by the learn plugin registry.
|
||||
plugin = OpenCodePlugin()
|
||||
119
tests/test_learn/test_opencode_scanner.py
Normal file
119
tests/test_learn/test_opencode_scanner.py
Normal file
|
|
@ -0,0 +1,119 @@
|
|||
"""Tests for the OpenCode learn scanner."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import sqlite3
|
||||
from pathlib import Path
|
||||
|
||||
from headroom.learn.models import ErrorCategory
|
||||
from headroom.learn.plugins.opencode import OpenCodePlugin
|
||||
from headroom.learn.registry import get_registry, reset_registry
|
||||
from headroom.learn.writer import CodexWriter
|
||||
|
||||
|
||||
def _create_opencode_db(db_path: Path, project_path: Path) -> None:
|
||||
conn = sqlite3.connect(db_path)
|
||||
try:
|
||||
conn.executescript(
|
||||
"""
|
||||
CREATE TABLE project (
|
||||
id TEXT PRIMARY KEY,
|
||||
name TEXT,
|
||||
worktree TEXT
|
||||
);
|
||||
CREATE TABLE session (
|
||||
id TEXT PRIMARY KEY,
|
||||
project_id TEXT,
|
||||
time_created INTEGER
|
||||
);
|
||||
CREATE TABLE message (
|
||||
id TEXT PRIMARY KEY,
|
||||
session_id TEXT
|
||||
);
|
||||
CREATE TABLE part (
|
||||
id TEXT PRIMARY KEY,
|
||||
message_id TEXT,
|
||||
data TEXT,
|
||||
time_created INTEGER
|
||||
);
|
||||
"""
|
||||
)
|
||||
conn.execute(
|
||||
"INSERT INTO project (id, name, worktree) VALUES (?, ?, ?)",
|
||||
("project-1", "Headroom", str(project_path)),
|
||||
)
|
||||
conn.execute(
|
||||
"INSERT INTO session (id, project_id, time_created) VALUES (?, ?, ?)",
|
||||
("session-1", "project-1", 1_700_000_000_000),
|
||||
)
|
||||
conn.execute(
|
||||
"INSERT INTO message (id, session_id) VALUES (?, ?)",
|
||||
("message-1", "session-1"),
|
||||
)
|
||||
conn.execute(
|
||||
"INSERT INTO part (id, message_id, data, time_created) VALUES (?, ?, ?, ?)",
|
||||
(
|
||||
"part-1",
|
||||
"message-1",
|
||||
json.dumps(
|
||||
{
|
||||
"type": "tool",
|
||||
"tool": "bash",
|
||||
"callID": "call-1",
|
||||
"state": {
|
||||
"status": "error",
|
||||
"input": {"command": "pytest"},
|
||||
"output": "Error: command failed with exit code 1",
|
||||
},
|
||||
}
|
||||
),
|
||||
1_700_000_000_001,
|
||||
),
|
||||
)
|
||||
conn.commit()
|
||||
finally:
|
||||
conn.close()
|
||||
|
||||
|
||||
def test_opencode_plugin_discovers_projects_and_scans_tool_failures(tmp_path: Path) -> None:
|
||||
project_path = tmp_path / "repo"
|
||||
project_path.mkdir()
|
||||
(project_path / "AGENTS.md").write_text("# Existing context\n", encoding="utf-8")
|
||||
db_path = tmp_path / "opencode.db"
|
||||
_create_opencode_db(db_path, project_path)
|
||||
|
||||
plugin = OpenCodePlugin(db_path=db_path)
|
||||
|
||||
projects = plugin.discover_projects()
|
||||
assert len(projects) == 1
|
||||
assert projects[0].name == "Headroom"
|
||||
assert projects[0].project_path == project_path
|
||||
assert projects[0].context_file == project_path / "AGENTS.md"
|
||||
|
||||
sessions = plugin.scan_project(projects[0])
|
||||
assert len(sessions) == 1
|
||||
assert sessions[0].session_id == "session-1"
|
||||
assert sessions[0].timestamp is not None
|
||||
|
||||
tool_call = sessions[0].tool_calls[0]
|
||||
assert tool_call.name == "Bash"
|
||||
assert tool_call.tool_call_id == "call-1"
|
||||
assert tool_call.input_data == {"command": "pytest"}
|
||||
assert tool_call.is_error is True
|
||||
assert tool_call.error_category == ErrorCategory.RUNTIME_ERROR
|
||||
|
||||
|
||||
def test_opencode_plugin_uses_agents_writer(tmp_path: Path) -> None:
|
||||
plugin = OpenCodePlugin(db_path=tmp_path / "missing.db")
|
||||
|
||||
assert plugin.detect() is False
|
||||
assert isinstance(plugin.create_writer(), CodexWriter)
|
||||
|
||||
|
||||
def test_opencode_plugin_is_discovered_by_registry() -> None:
|
||||
reset_registry()
|
||||
try:
|
||||
assert "opencode" in get_registry()
|
||||
finally:
|
||||
reset_registry()
|
||||
|
|
@ -2,6 +2,7 @@
|
|||
|
||||
from __future__ import annotations
|
||||
|
||||
import contextlib
|
||||
from unittest.mock import MagicMock, patch
|
||||
|
||||
import pytest
|
||||
|
|
@ -73,11 +74,11 @@ class TestAutoDetect:
|
|||
|
||||
def test_returns_empty_when_nothing_detected(self):
|
||||
"""All plugins returning False → empty list."""
|
||||
with (
|
||||
patch.object(get_registry()["claude"], "detect", return_value=False),
|
||||
patch.object(get_registry()["codex"], "detect", return_value=False),
|
||||
patch.object(get_registry()["gemini"], "detect", return_value=False),
|
||||
):
|
||||
registry = get_registry()
|
||||
patches = [patch.object(registry[name], "detect", return_value=False) for name in registry]
|
||||
with contextlib.ExitStack() as stack:
|
||||
for p in patches:
|
||||
stack.enter_context(p)
|
||||
assert auto_detect_plugins() == []
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue