[Phase 4] Kilocode Engine Adapter (VS Code Extension Protocol)

[frankbria]

Summary

Implement an AgentAdapter for Kilocode, the open-source AI coding assistant (fork of Roo Code/Cline), allowing CodeFrame to delegate code writing to Kilocode's capabilities.

Parent issue: #408

Motivation

Kilocode (open-source fork of Roo Code) provides sophisticated AI coding assistance with strong multi-model support and tool use capabilities. It has a growing ecosystem and community. Adding it as an engine option gives CodeFrame users access to its capabilities while CodeFrame handles orchestration.

Scope

New module: core/engines/kilocode.py

1. KilocodeAdapter implementing AgentAdapter:

class KilocodeAdapter:
    name = "kilocode"
    requires_api_key = {}  # Kilocode manages its own API keys
    
    def execute(self, task_prompt, workspace_path, context, timeout_ms):
        # 1. Determine Kilocode's CLI/API interface
        #    (may need to use its programmatic API or CLI mode)
        # 2. Pass task prompt and workspace context
        # 3. Monitor execution
        # 4. Parse results into AgentResult
        ...

2. Integration approach (to be determined during implementation):

   • Option A: If Kilocode has a CLI/headless mode, launch as subprocess
   • Option B: If Kilocode exposes an API, call it directly
   • Option C: If only VS Code extension, may need to interface via its extension protocol or wait for a CLI release

3. Output parsing:

   • Detect modified files via git diff after execution
   • Map Kilocode's output to AgentResult

4. Configuration:

   • kilocode_path: path to Kilocode binary/server
   • kilocode_model: LLM model override
   • kilocode_flags: additional configuration

Research Needed

• Determine Kilocode's non-interactive/programmatic interface
• Identify if CLI mode exists or if extension protocol is needed
• Determine how to pass task context and receive results

Acceptance Criteria

• KilocodeAdapter implements AgentAdapter protocol
• Kilocode invoked with correct workspace context
• Task prompt passed via appropriate mechanism
• Timeout enforced
• Modified files detected
• Works with cf work start <id> --execute --engine kilocode
• Integration test with mock interface

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 Kilocode installed/accessible

[traycerai]

Plan

Observations

The codebase currently supports two internal engine modes (react and plan) dispatched via execute_agent() in file:codeframe/core/runtime.py. The --engine flag is already wired in file:codeframe/cli/app.py (work_start). The AgentAdapter protocol referenced in the ticket does not exist yet — existing engines are concrete classes (ReactAgent, Agent). The git diff subsystem is available in file:codeframe/core/git.py (get_diff_stats, DiffStats, FileChange). Context packaging already exists in file:codeframe/core/context.py (ContextLoader, TaskContext). Kilocode's CLI (kilo run <message> --auto --workspace <path> --timeout <s> --model <m>) supports non-interactive, subprocess-invocable headless execution with clear exit codes (0 = success, 1 = error, 124 = timeout).

Approach

Since Kilocode has a working kilo run --auto CLI mode, the cleanest integration is Option A — subprocess. This avoids any VS Code extension protocol complexity, aligns with how CI/CD integration works, and keeps CodeFrame as the pure orchestrator. The adapter is self-contained in a new file, and execute_agent() in runtime.py is extended with a third branch for engine="kilocode".

---

Implementation Steps

1. Create codeframe/core/engines/kilocode.py

Create the new module at file:codeframe/core/engines/kilocode.py.

KilocodeAdapter class — attributes and constructor:

• Class-level name = "kilocode" and requires_api_key = {} (Kilocode manages its own API keys)
• Constructor accepts workspace, verbose, on_event callback (matching signatures of ReactAgent and Agent)
• Reads three optional config values from environment (following the same os.getenv pattern used in file:codeframe/adapters/llm/base.py):
  • KILOCODE_PATH → path to the kilo binary (default: "kilo" to rely on $PATH)
  • KILOCODE_MODEL → optional model override passed as --model
  • KILOCODE_FLAGS → optional extra CLI flags (space-separated string)

execute(task_id, workspace, timeout_ms) method — core logic:

1. Use ContextLoader(workspace).load(task_id) (from file:codeframe/core/context.py) to produce a TaskContext
2. Call task_context.to_prompt_context() to produce the formatted task prompt string
3. Build the kilo run subprocess command:
   • [kilocode_path, "run", prompt_text, "--auto", "--workspace", str(workspace.repo_path)]
   • Append --timeout <seconds> derived from timeout_ms // 1000 when provided
   • Append --model <model> when KILOCODE_MODEL is set
   • Append any extra flags from KILOCODE_FLAGS
4. Launch via subprocess.run(cmd, cwd=workspace.repo_path, capture_output=True, text=True, timeout=timeout_ms/1000)
5. Handle exit codes:
   • 0 → success
   • 124 → timeout exceeded
   • anything else → execution error; include stderr in error message
6. After subprocess completes (exit 0), call get_diff_stats(workspace) from file:codeframe/core/git.py to collect DiffStats.changed_files — return the list of modified file paths

AgentResult-compatible return — since there is no formal AgentResult dataclass yet (the ticket's dependency #409 may not be merged), return an object compatible with how execute_agent() in file:codeframe/core/runtime.py reads AgentState.status. Return an AgentState-like object (import AgentState and AgentStatus from file:codeframe/core/agent.py) with:

• status = AgentStatus.COMPLETED on success
• status = AgentStatus.FAILED on non-zero exit, attach error message

Subprocess safety:

• Wrap the subprocess call in a try/except subprocess.TimeoutExpired block and map it to AgentStatus.FAILED with a descriptive timeout reason
• Wrap FileNotFoundError (binary not on PATH) to raise a descriptive ValueError explaining how to install/configure Kilocode

2. Extend execute_agent() in codeframe/core/runtime.py

In the execute_agent() function (line ~591):

• Extend valid_engines tuple from ("plan", "react") to ("plan", "react", "kilocode")
• Remove the ANTHROPIC_API_KEY guard (lines ~635–639) when engine == "kilocode" — Kilocode manages its own keys; the guard should only apply for plan/react
• Add a third elif engine == "kilocode": branch after the react branch:
  • Import and instantiate KilocodeAdapter from codeframe.core.engines.kilocode
  • Call adapter.execute(run.task_id, workspace, timeout_ms=None) (no timeout by default, can be wired later)
  • Return the result wrapped as AgentState

3. Update CLI engine documentation in codeframe/cli/app.py

In work_start (line ~1996–2000), update the --engine option help text to advertise kilocode as a valid choice:

"Agent engine: 'react' (default), 'plan' (legacy), or 'kilocode' (delegates to Kilocode CLI)"

No other CLI changes are needed since the engine string flows directly through to execute_agent().

4. Document configuration in .env.example

Add three entries to file:.env.example (and the staging variant file:.env.staging.example) following the existing env-var documentation style:

KILOCODE_PATH=kilo           # Path to kilo binary; defaults to 'kilo' on $PATH
KILOCODE_MODEL=              # Optional model override passed to kilo --model
KILOCODE_FLAGS=              # Optional extra CLI flags (space-separated)

---

Data / Control Flow

sequenceDiagram
    participant CLI as cf work start --engine kilocode
    participant Runtime as execute_agent() [runtime.py]
    participant Adapter as KilocodeAdapter [kilocode.py]
    participant CtxLoader as ContextLoader [context.py]
    participant Kilo as kilo run --auto (subprocess)
    participant Git as get_diff_stats() [git.py]

    CLI->>Runtime: engine="kilocode", workspace, run
    Runtime->>Adapter: instantiate & execute(task_id, workspace)
    Adapter->>CtxLoader: load(task_id) → TaskContext
    CtxLoader-->>Adapter: TaskContext (prompt, files, blockers)
    Adapter->>Adapter: task_context.to_prompt_context() → prompt_str
    Adapter->>Kilo: subprocess: kilo run <prompt> --auto --workspace <path> [--model] [--timeout]
    Kilo-->>Adapter: exit code (0=ok, 1=err, 124=timeout)
    Adapter->>Git: get_diff_stats(workspace) → DiffStats.changed_files
    Git-->>Adapter: list[FileChange]
    Adapter-->>Runtime: AgentState(status=COMPLETED|FAILED)
    Runtime->>Runtime: complete_run() or fail_run()
    Runtime-->>CLI: AgentState

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently supports two internal engine modes (`react` and `plan`) dispatched via `execute_agent()` in `file:codeframe/core/runtime.py`. The `--engine` flag is already wired in `file:codeframe/cli/app.py` (`work_start`). The `AgentAdapter` protocol referenced in the ticket does not exist yet — existing engines are concrete classes (`ReactAgent`, `Agent`). The git diff subsystem is available in `file:codeframe/core/git.py` (`get_diff_stats`, `DiffStats`, `FileChange`). Context packaging already exists in `file:codeframe/core/context.py` (`ContextLoader`, `TaskContext`). Kilocode's CLI (`kilo run <message> --auto --workspace <path> --timeout <s> --model <m>`) supports non-interactive, subprocess-invocable headless execution with clear exit codes (0 = success, 1 = error, 124 = timeout).

## Approach

Since Kilocode has a working `kilo run --auto` CLI mode, the cleanest integration is **Option A — subprocess**. This avoids any VS Code extension protocol complexity, aligns with how CI/CD integration works, and keeps CodeFrame as the pure orchestrator. The adapter is self-contained in a new file, and `execute_agent()` in `runtime.py` is extended with a third branch for `engine="kilocode"`.

---

## Implementation Steps

### 1. Create `codeframe/core/engines/kilocode.py`

Create the new module at `file:codeframe/core/engines/kilocode.py`.

**`KilocodeAdapter` class** — attributes and constructor:
- Class-level `name = "kilocode"` and `requires_api_key = {}` (Kilocode manages its own API keys)
- Constructor accepts `workspace`, `verbose`, `on_event` callback (matching signatures of `ReactAgent` and `Agent`)
- Reads three optional config values from environment (following the same `os.getenv` pattern used in `file:codeframe/adapters/llm/base.py`):
  - `KILOCODE_PATH` → path to the `kilo` binary (default: `"kilo"` to rely on `$PATH`)
  - `KILOCODE_MODEL` → optional model override passed as `--model`
  - `KILOCODE_FLAGS` → optional extra CLI flags (space-separated string)

**`execute(task_id, workspace, timeout_ms)` method** — core logic:
1. Use `ContextLoader(workspace).load(task_id)` (from `file:codeframe/core/context.py`) to produce a `TaskContext`
2. Call `task_context.to_prompt_context()` to produce the formatted task prompt string
3. Build the `kilo run` subprocess command:
   - `[kilocode_path, "run", prompt_text, "--auto", "--workspace", str(workspace.repo_path)]`
   - Append `--timeout <seconds>` derived from `timeout_ms // 1000` when provided
   - Append `--model <model>` when `KILOCODE_MODEL` is set
   - Append any extra flags from `KILOCODE_FLAGS`
4. Launch via `subprocess.run(cmd, cwd=workspace.repo_path, capture_output=True, text=True, timeout=timeout_ms/1000)`
5. Handle exit codes:
   - `0` → success
   - `124` → timeout exceeded
   - anything else → execution error; include `stderr` in error message
6. After subprocess completes (exit 0), call `get_diff_stats(workspace)` from `file:codeframe/core/git.py` to collect `DiffStats.changed_files` — return the list of modified file paths

**`AgentResult`-compatible return** — since there is no formal `AgentResult` dataclass yet (the ticket's dependency #409 may not be merged), return an object compatible with how `execute_agent()` in `file:codeframe/core/runtime.py` reads `AgentState.status`. Return an `AgentState`-like object (import `AgentState` and `AgentStatus` from `file:codeframe/core/agent.py`) with:
- `status = AgentStatus.COMPLETED` on success
- `status = AgentStatus.FAILED` on non-zero exit, attach error message

**Subprocess safety:**
- Wrap the subprocess call in a `try/except subprocess.TimeoutExpired` block and map it to `AgentStatus.FAILED` with a descriptive timeout reason
- Wrap `FileNotFoundError` (binary not on PATH) to raise a descriptive `ValueError` explaining how to install/configure Kilocode

### 2. Extend `execute_agent()` in `codeframe/core/runtime.py`

In the `execute_agent()` function (line ~591):

- Extend `valid_engines` tuple from `("plan", "react")` to `("plan", "react", "kilocode")`
- Remove the `ANTHROPIC_API_KEY` guard (lines ~635–639) when `engine == "kilocode"` — Kilocode manages its own keys; the guard should only apply for `plan`/`react`
- Add a third `elif engine == "kilocode":` branch after the `react` branch:
  - Import and instantiate `KilocodeAdapter` from `codeframe.core.engines.kilocode`
  - Call `adapter.execute(run.task_id, workspace, timeout_ms=None)` (no timeout by default, can be wired later)
  - Return the result wrapped as `AgentState`

### 3. Update CLI engine documentation in `codeframe/cli/app.py`

In `work_start` (line ~1996–2000), update the `--engine` option help text to advertise `kilocode` as a valid choice:

> `"Agent engine: 'react' (default), 'plan' (legacy), or 'kilocode' (delegates to Kilocode CLI)"`

No other CLI changes are needed since the `engine` string flows directly through to `execute_agent()`.

### 4. Document configuration in `.env.example`

Add three entries to `file:.env.example` (and the staging variant `file:.env.staging.example`) following the existing env-var documentation style:

```
KILOCODE_PATH=kilo           # Path to kilo binary; defaults to 'kilo' on $PATH
KILOCODE_MODEL=              # Optional model override passed to kilo --model
KILOCODE_FLAGS=              # Optional extra CLI flags (space-separated)
```

---

## Data / Control Flow

```mermaid
sequenceDiagram
    participant CLI as cf work start --engine kilocode
    participant Runtime as execute_agent() [runtime.py]
    participant Adapter as KilocodeAdapter [kilocode.py]
    participant CtxLoader as ContextLoader [context.py]
    participant Kilo as kilo run --auto (subprocess)
    participant Git as get_diff_stats() [git.py]

    CLI->>Runtime: engine="kilocode", workspace, run
    Runtime->>Adapter: instantiate & execute(task_id, workspace)
    Adapter->>CtxLoader: load(task_id) → TaskContext
    CtxLoader-->>Adapter: TaskContext (prompt, files, blockers)
    Adapter->>Adapter: task_context.to_prompt_context() → prompt_str
    Adapter->>Kilo: subprocess: kilo run <prompt> --auto --workspace <path> [--model] [--timeout]
    Kilo-->>Adapter: exit code (0=ok, 1=err, 124=timeout)
    Adapter->>Git: get_diff_stats(workspace) → DiffStats.changed_files
    Git-->>Adapter: list[FileChange]
    Adapter-->>Runtime: AgentState(status=COMPLETED|FAILED)
    Runtime->>Runtime: complete_run() or fail_run()
    Runtime-->>CLI: AgentState
```

---

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]
#31 - Create SDK migration implementation plan [merged]
#125 - Implement WorkerAgent execute_task method [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!