[Phase 4] OpenCode Engine Adapter

[frankbria]

Summary

Implement an AgentAdapter for OpenCode, an open-source terminal-based AI coding assistant, allowing CodeFrame to delegate code writing to OpenCode as a subprocess.

Parent issue: #408

Motivation

OpenCode is a fast, terminal-native AI coding tool with multi-model support and strong file editing. It provides a different execution profile from Claude Code and can work with multiple LLM providers (OpenAI, Anthropic, etc.), giving CodeFrame users flexibility in which underlying model powers their coding agent.

Scope

New module: core/engines/opencode.py

1. OpenCodeAdapter implementing AgentAdapter:

class OpenCodeAdapter:
    name = "opencode"
    requires_api_key = {}  # OpenCode manages its own API keys/config
    
    def execute(self, task_prompt, workspace_path, context, timeout_ms):
        # 1. Build task prompt from context packager
        # 2. Launch opencode in non-interactive/script mode
        #    with cwd=workspace_path
        # 3. Capture output
        # 4. Parse results into AgentResult
        ...

2. OpenCode CLI invocation:

   • Research OpenCode's non-interactive/scripting mode
   • Pass task prompt via appropriate mechanism (stdin, flag, or file)
   • Set cwd to workspace path
   • Disable auto-commits (CodeFrame owns git workflow)

3. Output parsing:

   • Detect modified files via git diff after execution
   • Parse success/failure from exit code and output
   • Extract summary from completion output

4. Configuration:

   • opencode_path: path to opencode binary (default: opencode)
   • opencode_model: LLM model override (optional)
   • opencode_flags: additional CLI flags

Acceptance Criteria

• OpenCodeAdapter implements AgentAdapter protocol
• OpenCode launched as subprocess with correct cwd
• Task prompt passed via appropriate mechanism
• Timeout enforced
• Modified files detected via git diff
• Works with cf work start <id> --execute --engine opencode
• Integration test with mock binary

Dependencies

• Depends on [Phase 4] Agent Adapter Protocol Definition #409 (AgentAdapter protocol)
• Depends on [Phase 4] Task Context Packager for External Agents #410 (context packager)
• Requires OpenCode installed

[traycerai]

Plan

Observations

The codebase has a clear engine-selection architecture centred in execute_agent() in file:codeframe/core/runtime.py. The function accepts an engine string, validates it against a valid_engines tuple, and dispatches to either ReactAgent or the legacy Agent. LLM adapters follow a protocol in file:codeframe/adapters/llm/base.py. The --engine flag is already threaded from cf work start through work_start() in file:codeframe/cli/app.py into runtime.execute_agent(). No AgentAdapter protocol or AgentResult type exists yet — they are new Phase 4 additions (#409).

Approach

Add OpenCodeAdapter as a new engine option integrated directly into the existing execute_agent() dispatch pattern, consistent with how react and plan engines are wired. A thin AgentAdapter protocol and AgentResult dataclass are introduced in file:codeframe/core/engines/ so the new module has a proper home alongside future adapters. The context packager (#410) is composed in, but the adapter degrades gracefully if it isn't yet available.

---

Implementation Steps

1. Create codeframe/core/engines/ package

Create file:codeframe/core/engines/__init__.py as an empty package marker to establish core/engines/ as the canonical home for engine adapters.

---

2. Define the AgentAdapter protocol and AgentResult dataclass

Create file:codeframe/core/engines/base.py with:

• AgentResult — a @dataclass with fields:

  Field	Type	Description
  success	bool	Whether the engine reported success
  summary	str	Human-readable completion summary
  modified_files	list[str]	Paths changed, detected via git diff
  exit_code	int	Raw subprocess exit code
  raw_output	str	Captured stdout/stderr from the engine
  error	str	Error message if success=False

• AgentAdapter — a Protocol (from typing) with:

  • name: str — class-level identifier (e.g., "opencode")
  • requires_api_key: dict — keys the adapter needs in the environment
  • execute(task_prompt: str, workspace_path: Path, context: dict, timeout_ms: int) -> AgentResult

This mirrors the pattern of LLMProvider in file:codeframe/adapters/llm/base.py but is a structural Protocol so no inheritance is required.

---

3. Implement OpenCodeAdapter in codeframe/core/engines/opencode.py

Create file:codeframe/core/engines/opencode.py. Key design decisions:

3a. Class attributes

name = "opencode"
requires_api_key = {}   # OpenCode manages its own LLM credentials

3b. Configuration (read from env or constructor kwargs)

Config key	Env var	Default
opencode_path	CODEFRAME_OPENCODE_PATH	"opencode"
opencode_model	CODEFRAME_OPENCODE_MODEL	None (use OpenCode default)
opencode_flags	—	[]
timeout_ms	—	passed per-call

3c. execute() method — sequence

sequenceDiagram
    participant CF as execute_agent()
    participant OC as OpenCodeAdapter.execute()
    participant GD as git diff (before)
    participant SP as subprocess (opencode run)
    participant GD2 as git diff (after)

    CF->>OC: execute(task_prompt, workspace_path, context, timeout_ms)
    OC->>GD: capture baseline HEAD sha
    OC->>SP: opencode run --prompt "<task_prompt>" [--model <model>] [extra_flags]
    Note over SP: cwd=workspace_path, timeout=timeout_ms/1000
    SP-->>OC: stdout, stderr, returncode
    OC->>GD2: git diff HEAD --name-only → modified_files
    OC-->>CF: AgentResult(success, summary, modified_files, exit_code, raw_output)

Loading

Subprocess invocation details:

• Command: [opencode_path, "run", "--prompt", task_prompt, "--quiet"]
• Append ["--model", opencode_model] when opencode_model is set
• Append any opencode_flags
• Use subprocess.run(cmd, cwd=workspace_path, capture_output=True, text=True, timeout=timeout_ms/1000)
• Wrap in try/except subprocess.TimeoutExpired → return AgentResult(success=False, error="Timeout after …ms")
• Wrap in try/except FileNotFoundError → raise a clear EnvironmentError pointing to CODEFRAME_OPENCODE_PATH

Modified-file detection via gitpython (already in dependencies as gitpython>=3.1.40):

• Open git.Repo(workspace_path) before the subprocess call to snapshot the HEAD tree
• After the call, run repo.git.diff("HEAD", "--name-only") and split on newlines

Success heuristic:

• exit_code == 0 → success=True
• Non-zero exit or TimeoutExpired → success=False
• Extract the last non-empty line of stdout as summary

---

4. Wire opencode into execute_agent() in runtime.py

In file:codeframe/core/runtime.py, inside execute_agent():

1. Expand valid_engines from ("plan", "react") to ("plan", "react", "opencode").
2. Remove the blanket ANTHROPIC_API_KEY guard for the opencode path — it manages its own credentials.
   • Restructure to only require the key when engine in ("plan", "react").
3. Add an elif engine == "opencode": branch that:
   • Builds task_prompt from tasks.get(workspace, run.task_id) and any available context packager output.
   • Instantiates OpenCodeAdapter with config sourced from os.environ.
   • Calls adapter.execute(task_prompt, workspace.repo_path, context={}, timeout_ms=timeout_ms).
   • Maps AgentResult → existing AgentState/AgentStatus conventions:
     • AgentResult.success=True → AgentStatus.COMPLETED
     • AgentResult.success=False → AgentStatus.FAILED
   • Calls complete_run() or fail_run() accordingly, reusing the same post-execution path.
4. Log the engine used and modified files via run_logger.

---

5. Expose opencode in the CLI help text

In file:codeframe/cli/app.py, update the --engine option's help string from:

"Agent engine: 'react' (default, ReAct tool-use loop) or 'plan' (legacy step-based)"

to:

"Agent engine: 'react' (default), 'plan' (legacy), or 'opencode' (OpenCode subprocess)"

No other CLI changes are needed — the existing engine parameter propagation already covers it end-to-end.

---

6. Pre-flight validation helper

Add a validate_opencode_binary(opencode_path: str) -> None function (in file:codeframe/core/engines/opencode.py) that runs opencode_path --version via subprocess.run and raises a descriptive EnvironmentError if the binary is missing or returns a non-zero exit. Call this at the top of execute() so failures are caught early with a clear message rather than an opaque FileNotFoundError.

---

7. Update AGENTS.md engine table

In file:AGENTS.md, add a row to the Engine Selection table:

Engine	Flag	Pattern	Best For
ReAct (default)	--engine react	Observe → Think → Act loop	Most tasks, adaptive execution
Plan (legacy)	--engine plan	Plan all steps → Execute sequentially	Well-defined, predictable tasks
OpenCode (new)	--engine opencode	Delegate to OpenCode subprocess	Multi-model flexibility, terminal-native execution

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a clear engine-selection architecture centred in `execute_agent()` in `file:codeframe/core/runtime.py`. The function accepts an `engine` string, validates it against a `valid_engines` tuple, and dispatches to either `ReactAgent` or the legacy `Agent`. LLM adapters follow a protocol in `file:codeframe/adapters/llm/base.py`. The `--engine` flag is already threaded from `cf work start` through `work_start()` in `file:codeframe/cli/app.py` into `runtime.execute_agent()`. No `AgentAdapter` protocol or `AgentResult` type exists yet — they are new Phase 4 additions (#409).

## Approach

Add `OpenCodeAdapter` as a new engine option integrated directly into the existing `execute_agent()` dispatch pattern, consistent with how `react` and `plan` engines are wired. A thin `AgentAdapter` protocol and `AgentResult` dataclass are introduced in `file:codeframe/core/engines/` so the new module has a proper home alongside future adapters. The context packager (#410) is composed in, but the adapter degrades gracefully if it isn't yet available.

---

## Implementation Steps

### 1. Create `codeframe/core/engines/` package

Create `file:codeframe/core/engines/__init__.py` as an empty package marker to establish `core/engines/` as the canonical home for engine adapters.

---

### 2. Define the `AgentAdapter` protocol and `AgentResult` dataclass

Create `file:codeframe/core/engines/base.py` with:

- **`AgentResult`** — a `@dataclass` with fields:
  | Field | Type | Description |
  |---|---|---|
  | `success` | `bool` | Whether the engine reported success |
  | `summary` | `str` | Human-readable completion summary |
  | `modified_files` | `list[str]` | Paths changed, detected via git diff |
  | `exit_code` | `int` | Raw subprocess exit code |
  | `raw_output` | `str` | Captured stdout/stderr from the engine |
  | `error` | `str` | Error message if `success=False` |

- **`AgentAdapter`** — a `Protocol` (from `typing`) with:
  - `name: str` — class-level identifier (e.g., `"opencode"`)
  - `requires_api_key: dict` — keys the adapter needs in the environment
  - `execute(task_prompt: str, workspace_path: Path, context: dict, timeout_ms: int) -> AgentResult`

This mirrors the pattern of `LLMProvider` in `file:codeframe/adapters/llm/base.py` but is a structural `Protocol` so no inheritance is required.

---

### 3. Implement `OpenCodeAdapter` in `codeframe/core/engines/opencode.py`

Create `file:codeframe/core/engines/opencode.py`. Key design decisions:

#### 3a. Class attributes

```
name = "opencode"
requires_api_key = {}   # OpenCode manages its own LLM credentials
```

#### 3b. Configuration (read from env or constructor kwargs)

| Config key | Env var | Default |
|---|---|---|
| `opencode_path` | `CODEFRAME_OPENCODE_PATH` | `"opencode"` |
| `opencode_model` | `CODEFRAME_OPENCODE_MODEL` | `None` (use OpenCode default) |
| `opencode_flags` | — | `[]` |
| `timeout_ms` | — | passed per-call |

#### 3c. `execute()` method — sequence

```mermaid
sequenceDiagram
    participant CF as execute_agent()
    participant OC as OpenCodeAdapter.execute()
    participant GD as git diff (before)
    participant SP as subprocess (opencode run)
    participant GD2 as git diff (after)

    CF->>OC: execute(task_prompt, workspace_path, context, timeout_ms)
    OC->>GD: capture baseline HEAD sha
    OC->>SP: opencode run --prompt "<task_prompt>" [--model <model>] [extra_flags]
    Note over SP: cwd=workspace_path, timeout=timeout_ms/1000
    SP-->>OC: stdout, stderr, returncode
    OC->>GD2: git diff HEAD --name-only → modified_files
    OC-->>CF: AgentResult(success, summary, modified_files, exit_code, raw_output)
```

**Subprocess invocation details:**
- Command: `[opencode_path, "run", "--prompt", task_prompt, "--quiet"]`
- Append `["--model", opencode_model]` when `opencode_model` is set
- Append any `opencode_flags`
- Use `subprocess.run(cmd, cwd=workspace_path, capture_output=True, text=True, timeout=timeout_ms/1000)`
- Wrap in `try/except subprocess.TimeoutExpired` → return `AgentResult(success=False, error="Timeout after …ms")`
- Wrap in `try/except FileNotFoundError` → raise a clear `EnvironmentError` pointing to `CODEFRAME_OPENCODE_PATH`

**Modified-file detection via `gitpython`** (already in dependencies as `gitpython>=3.1.40`):
- Open `git.Repo(workspace_path)` before the subprocess call to snapshot the HEAD tree
- After the call, run `repo.git.diff("HEAD", "--name-only")` and split on newlines

**Success heuristic:**
- `exit_code == 0` → `success=True`
- Non-zero exit or `TimeoutExpired` → `success=False`
- Extract the last non-empty line of stdout as `summary`

---

### 4. Wire `opencode` into `execute_agent()` in `runtime.py`

In `file:codeframe/core/runtime.py`, inside `execute_agent()`:

1. Expand `valid_engines` from `("plan", "react")` to `("plan", "react", "opencode")`.
2. Remove the blanket `ANTHROPIC_API_KEY` guard for the `opencode` path — it manages its own credentials.
   - Restructure to only require the key when `engine in ("plan", "react")`.
3. Add an `elif engine == "opencode":` branch that:
   - Builds `task_prompt` from `tasks.get(workspace, run.task_id)` and any available context packager output.
   - Instantiates `OpenCodeAdapter` with config sourced from `os.environ`.
   - Calls `adapter.execute(task_prompt, workspace.repo_path, context={}, timeout_ms=timeout_ms)`.
   - Maps `AgentResult` → existing `AgentState`/`AgentStatus` conventions:
     - `AgentResult.success=True` → `AgentStatus.COMPLETED`
     - `AgentResult.success=False` → `AgentStatus.FAILED`
   - Calls `complete_run()` or `fail_run()` accordingly, reusing the same post-execution path.
4. Log the engine used and modified files via `run_logger`.

---

### 5. Expose `opencode` in the CLI help text

In `file:codeframe/cli/app.py`, update the `--engine` option's `help` string from:

> `"Agent engine: 'react' (default, ReAct tool-use loop) or 'plan' (legacy step-based)"`

to:

> `"Agent engine: 'react' (default), 'plan' (legacy), or 'opencode' (OpenCode subprocess)"`

No other CLI changes are needed — the existing `engine` parameter propagation already covers it end-to-end.

---

### 6. Pre-flight validation helper

Add a `validate_opencode_binary(opencode_path: str) -> None` function (in `file:codeframe/core/engines/opencode.py`) that runs `opencode_path --version` via `subprocess.run` and raises a descriptive `EnvironmentError` if the binary is missing or returns a non-zero exit. Call this at the top of `execute()` so failures are caught early with a clear message rather than an opaque `FileNotFoundError`.

---

### 7. Update `AGENTS.md` engine table

In `file:AGENTS.md`, add a row to the Engine Selection table:

| Engine | Flag | Pattern | Best For |
|--------|------|---------|----------|
| **ReAct** (default) | `--engine react` | Observe → Think → Act loop | Most tasks, adaptive execution |
| **Plan** (legacy) | `--engine plan` | Plan all steps → Execute sequentially | Well-defined, predictable tasks |
| **OpenCode** (new) | `--engine opencode` | Delegate to OpenCode subprocess | Multi-model flexibility, terminal-native execution |

---

Execution Information

Branch: main
Commit: 705b160

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

🔗 Related PRs

#30 - Review codebase against Claude SDK functionality [closed]
#125 - Implement WorkerAgent execute_task method [merged]
#246 - feat(agents): trigger multi-agent execution after task approval [merged]
#356 - fix: agent execution resilience + Phase 2.5 architecture research [merged]
#363 - feat: wire ReactAgent into runtime with --engine react CLI flag [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[frankbria]

Already implemented. OpenCode adapter exists at codeframe/core/adapters/opencode.py (merged in PR #431 as part of the adapter architecture work).