Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
feat: add first-class OpenCode support (wrap, learn, mcp install) (#559)
T. P.91cd2102d7e9
diff --git a/docs/content/docs/failure-learning.mdx b/docs/content/docs/failure-learning.mdxindex 2dd1f0be2..15a4f58e1 100644--- a/docs/content/docs/failure-learning.mdx+++ b/docs/content/docs/failure-learning.mdx@@ -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```diff --git a/docs/content/docs/opencode.mdx b/docs/content/docs/opencode.mdxindex d82981a7b..a5df0fc3a 100644--- a/docs/content/docs/opencode.mdx+++ b/docs/content/docs/opencode.mdx@@ -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:diff --git a/headroom/learn/plugins/opencode.py b/headroom/learn/plugins/opencode.pynew file mode 100644index 000000000..ef16b56a4--- /dev/null+++ b/headroom/learn/plugins/opencode.py@@ -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()diff --git a/tests/test_learn/test_opencode_scanner.py b/tests/test_learn/test_opencode_scanner.pynew file mode 100644index 000000000..96ff2c366--- /dev/null+++ b/tests/test_learn/test_opencode_scanner.py@@ -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()diff --git a/tests/test_learn/test_registry.py b/tests/test_learn/test_registry.pyindex 2e6214c1e..eb98254fa 100644--- a/tests/test_learn/test_registry.py+++ b/tests/test_learn/test_registry.py@@ -2,6 +2,7 @@from __future__ import annotations+import contextlibfrom unittest.mock import MagicMock, patchimport 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() == []