[P4.4] Kilocode adapter — build + parse + capabilities + tests + docs

[frankbria]

Phase 4 — Provider onboarding.

Scope

• lib/agents/kilocode.sh:
  • Build: headless requires --auto; structured via -j/--json (needs --auto) or
    -i/--json-io (bidirectional, no TUI). -c/--continue (last only), -mo/--model,
    --yolo for approvals.
  • Parse: Kilocode JSON -> internal struct.
  • Capabilities: structured=yes, session=continue-last (weakest — note limitation),
    token usage=verify, permission_denials=no, api_limit=off.
• Tests via [P2.2]; docs/providers/KILOCODE.md; README row.

Acceptance

• ralph --provider kilocode drives the loop against a mock; continue-last session
  caveat documented. Full suite green.

Depends on: [P3.1].

[github-actions]

🏷️ Triage: Feature / Enhancement

Categorized this as an enhancement (applied the enhancement label).

Why: This is a provider-onboarding task — implementing the Kilocode adapter (lib/agents/kilocode.sh) for build/parse/capabilities, plus tests and docs. It's new functionality, not a defect, so it's an enhancement rather than a bug.

Not a duplicate: I checked the other open multi-provider issues. This is the distinct P4.4 phase; it does not overlap with #310 (P0.1 — capability matrix + ADR) or other phases. Each is a separate work item in the phased multi-provider plan.

Notes / next steps:

• The issue is well-specified (clear scope + acceptance criteria), so no further info is needed.
• It declares a dependency on [P3.1] — that should be resolved before implementation starts. Worth tracking via the queue/dependency tooling so it isn't picked up prematurely.
• The multi-provider label is retained for the umbrella tracking.

No bug or duplicate handling required.

Generated by Issue Triage Assistant for issue #321 · opus48 358.9K · ◷

[coderabbitai]

Coding Plan

Summary

• Follow lib/sandbox_docker.sh patterns for adapter structure with state primitives, validation, and command building
• Use --json-io mode for headless JSON communication without forcing autonomous approval modes
• Explicitly declare and document the "continue-last" session limitation as the key difference from Claude's full session support
• Implement token extraction with graceful fallback since availability is unverified

Design Choices

Design Choice 1: JSON output mode selection

Options Considered:

1. Use --json with --auto for structured output in fully autonomous mode
2. Use --json-io for bidirectional JSON communication without TUI dependency

Chosen Option: 2

Rationale: --json-io provides headless JSON operation without forcing --auto/--yolo approval modes, giving Ralph control over when to enable autonomous approval.

Design Choice 2: Token usage reporting

Options Considered:

1. Assume token usage is available and parse from response
2. Declare capability as "none" and skip token extraction

Chosen Option: 1

Rationale: Implement token extraction with graceful fallback to zero; document as "experimental" until verified with real Kilocode output.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Provider Adapter Core

Implement the Kilocode adapter shell library following the patterns established by lib/sandbox_docker.sh for state management and lib/response_analyzer.sh for output normalization.

Task 1: Create Kilocode Adapter Structure

Establish the adapter file with configuration variables and initialization following sandbox adapter conventions.

• Create lib/agents/kilocode.sh with standard header, source guard, and dependency on core libraries
• Define configuration variables: KILOCODE_CMD (default: kilo), KILOCODE_MODEL, KILOCODE_TIMEOUT_MINUTES, KILOCODE_AUTO_MODE (boolean), KILOCODE_YOLO_MODE (boolean)
• Implement kilocode_is_available() to verify the kilo CLI is installed and executable
• Implement validate_kilocode_config() to check model format and timeout bounds

Task 2: Implement Command Builder

Build the function that constructs the Kilocode CLI invocation array, mirroring build_claude_command() patterns.

• Implement build_kilocode_command(prompt_content, session_mode) that populates a global KILOCODE_CMD_ARGS array
• Add --json-io flag for structured bidirectional output without TUI
• Add --model flag when KILOCODE_MODEL is set
• Add --continue flag when session_mode is "continue" AND a previous session exists (continue-last limitation)
• Add --auto flag when KILOCODE_AUTO_MODE is enabled
• Add --yolo flag when KILOCODE_YOLO_MODE is enabled for full autonomy
• Append the prompt content as the final positional argument

Task 3: Implement Response Parser

Parse Kilocode JSON output into the internal analysis struct format expected by the loop.

• Implement parse_kilocode_response(output_file, result_file) following parse_json_response() patterns
• Extract status from Kilocode's completion indicator (map to COMPLETE/UNKNOWN)
• Extract exit_signal from response structure or embedded RALPH_STATUS block in output text
• Extract session_id with awareness that Kilocode only tracks "last session" (no arbitrary ID retrieval)
• Extract files_modified from response metadata if available
• Extract summary from result/output text field
• Extract token usage (input_tokens, output_tokens) with fallback to zero if not present
• Write normalized JSON to result_file matching the internal struct schema

Task 4: Implement Capabilities Declaration

Declare what features Kilocode supports so the loop can adapt its behavior accordingly.

• Implement get_kilocode_capabilities() returning a JSON object with:
  • structured_output: true — supports JSON mode
  • session_mode: "continue-last" — can only continue the most recent session, not arbitrary sessions by ID
  • token_usage: "experimental" — availability unverified, graceful fallback
  • permission_denials: false — Kilocode does not report permission denials
  • api_limit_tracking: false — no built-in API rate limiting
• Document the session limitation prominently: Ralph cannot resume arbitrary sessions, only the last one

🤖 Prompt for AI agents

Implement the Kilocode provider adapter shell library at
`lib/agents/kilocode.sh`, following the structural patterns of
`lib/sandbox_docker.sh` for state management and `lib/response_analyzer.sh` for
response normalization.

**File setup:**
- Create `lib/agents/kilocode.sh` with a standard shell script header, a
`source` guard to prevent double-sourcing, and `source` declarations for
required core libraries

**Configuration variables** (define at the top of the file with defaults):
- `KILOCODE_CMD` — default: `kilo`
- `KILOCODE_MODEL` — empty by default
- `KILOCODE_TIMEOUT_MINUTES`
- `KILOCODE_AUTO_MODE` — boolean
- `KILOCODE_YOLO_MODE` — boolean

**`kilocode_is_available()`:**
- Check that the `kilo` CLI binary is installed and executable on the system
PATH

**`validate_kilocode_config()`:**
- Validate model format when `KILOCODE_MODEL` is set
- Check that timeout bounds are within acceptable ranges

**`build_kilocode_command(prompt_content, session_mode)`:**
- Populate a global `KILOCODE_CMD_ARGS` array (mirror the pattern of
`build_claude_command()`)
- Always include `--json-io` flag for headless structured bidirectional output
(no TUI)
- Conditionally add `--model` when `KILOCODE_MODEL` is set
- Conditionally add `--continue` only when `session_mode` is `"continue"` AND a
previous session exists (respect the continue-last limitation)
- Conditionally add `--auto` when `KILOCODE_AUTO_MODE` is enabled
- Conditionally add `--yolo` when `KILOCODE_YOLO_MODE` is enabled
- Append `prompt_content` as the final positional argument

**`parse_kilocode_response(output_file, result_file)`:**
- Follow the patterns of `parse_json_response()` from `lib/response_analyzer.sh`
- Extract and map the following fields to the internal struct schema:
- `status`: from Kilocode's completion indicator, mapped to `COMPLETE`/`UNKNOWN`
- `exit_signal`: from response structure or embedded `RALPH_STATUS` block in
output text
- `session_id`: with awareness that Kilocode only tracks "last session" — no
arbitrary ID retrieval
  - `files_modified`: from response metadata if available
  - `summary`: from result/output text field
- `input_tokens` / `output_tokens`: extracted if present, fallback to zero if
not
- Write the normalized JSON to `result_file`

**`get_kilocode_capabilities()`:**
- Return a JSON object with the following fields:
  - `structured_output: true`
  - `session_mode: "continue-last"`
  - `token_usage: "experimental"`
  - `permission_denials: false`
  - `api_limit_tracking: false`
- Add prominent inline comments documenting the session limitation (Ralph can
only resume the last session, not arbitrary sessions by ID)

Phase 2: Testing

Build comprehensive tests following the existing BATS test patterns in tests/unit/ and tests/integration/.

Task 1: Create Test Fixtures

Establish mock Kilocode output data for deterministic testing.

• Create tests/fixtures/kilocode/ directory for provider-specific fixtures
• Add success_response.json — complete task with files modified, session info
• Add continue_response.json — resumed session output
• Add error_response.json — failed execution with error indicators
• Add minimal_response.json — bare minimum valid output (tests graceful degradation)
• Add no_tokens_response.json — response without token usage fields

Task 2: Unit Tests for Adapter Functions

Test each adapter function in isolation.

• Create tests/unit/test_kilocode_adapter.bats
• Test kilocode_is_available() with mock binary present/absent scenarios
• Test validate_kilocode_config() with valid and invalid configurations
• Test build_kilocode_command() verifies correct flag composition for:
  • Basic invocation with prompt only
  • Model override via KILOCODE_MODEL
  • Continue mode with --continue flag
  • Auto mode with --auto flag
  • YOLO mode with --yolo flag
  • Combined flags in correct order
• Test parse_kilocode_response() correctly normalizes each fixture to internal struct
• Test get_kilocode_capabilities() returns expected capability object

Task 3: Integration Tests for Provider Routing

Test that the provider dispatch correctly invokes the Kilocode adapter.

• Create tests/integration/test_kilocode_execution.bats
• Test provider selection routes to Kilocode adapter when --provider kilocode is specified
• Test session continuation respects "continue-last" limitation (cannot specify arbitrary session ID)
• Test graceful handling when kilo binary is not available
• Test configuration validation errors surface appropriately
• Mock the actual CLI execution to verify correct command construction without requiring Kilocode installed

🤖 Prompt for AI agents

Create BATS test fixtures and test files for the Kilocode adapter, following the
existing patterns in `tests/unit/` and `tests/integration/`.

**Test fixtures** — create `tests/fixtures/kilocode/` and add the following JSON
files:
- `success_response.json` — a complete task response including files modified
and session info
- `continue_response.json` — a resumed session output
- `error_response.json` — a failed execution with error indicators
- `minimal_response.json` — the bare minimum valid output to test graceful
degradation
- `no_tokens_response.json` — a valid response with token usage fields absent

**Unit tests** — create `tests/unit/test_kilocode_adapter.bats`:
- Test `kilocode_is_available()` with a mock binary present and with the binary
absent
- Test `validate_kilocode_config()` for both valid and invalid configurations
- Test `build_kilocode_command()` for correct flag composition in all
combinations:
  - Basic invocation (prompt only)
  - Model override via `KILOCODE_MODEL`
  - Continue mode producing `--continue` flag
  - Auto mode producing `--auto` flag
  - YOLO mode producing `--yolo` flag
  - Combined flags in the expected order
- Test `parse_kilocode_response()` against each fixture file to confirm correct
normalization to the internal struct
- Test `get_kilocode_capabilities()` returns the exact expected capability
object

**Integration tests** — create `tests/integration/test_kilocode_execution.bats`:
- Test that `--provider kilocode` routes execution to the Kilocode adapter
- Test that session continuation enforces the "continue-last" limitation
(arbitrary session IDs are rejected)
- Test graceful failure when the `kilo` binary is not available
- Test that configuration validation errors surface with appropriate messages
- Mock CLI execution to verify correct command construction without requiring
Kilocode to be installed

Phase 3: Documentation

Create provider documentation and update project references.

Task 1: Provider Documentation

Document Kilocode-specific configuration, usage, and limitations.

• Create docs/providers/KILOCODE.md with sections:
  • Overview: What Kilocode is and why you'd use it with Ralph
  • Installation: npm install -g @kilocode/cli`` prerequisite
  • Configuration: All KILOCODE_* environment variables with defaults
  • Usage examples: ralph --provider kilocode, with model override, with YOLO mode
  • Session limitation: Prominent callout that --continue only resumes the last session, not arbitrary sessions — Ralph cannot implement full session continuity with Kilocode
  • Capability comparison: Table showing Kilocode vs Claude capabilities
  • Troubleshooting: Common issues (binary not found, model not available)

Task 2: Update Project Documentation

Add Kilocode to project-level documentation.

• Update README.md provider table with a Kilocode row showing: name, session support (continue-last†), structured output (yes), notes with footnote about session limitation
• Add Kilocode to any provider listing in CLAUDE.md if a provider documentation section exists
• Ensure docs/providers/ directory is created if it doesn't exist (may be created by P3.1)

🤖 Prompt for AI agents

Create and update documentation files to cover the Kilocode provider.

**Create `docs/providers/KILOCODE.md`** with the following sections:
- **Overview**: Describe what Kilocode is and why a user would choose it with
Ralph
- **Installation**: Document the `npm install -g `@kilocode/cli`` prerequisite
- **Configuration**: List all `KILOCODE_*` environment variables with their
defaults and descriptions
- **Usage examples**: Show `ralph --provider kilocode`, usage with a model
override, and usage with YOLO mode
- **Session limitation**: Include a prominent callout/warning block explaining
that `--continue` only resumes the *last* session — Ralph cannot implement full
session continuity with Kilocode since arbitrary session IDs cannot be retrieved
- **Capability comparison**: Add a table comparing Kilocode vs Claude
capabilities side by side
- **Troubleshooting**: Cover common issues including binary not found and model
not available

**Update `README.md`:**
- Add a Kilocode row to the provider table with columns: name, session support
(`continue-last†`), structured output (`yes`), and a note referencing the
session limitation footnote

**Update `CLAUDE.md`:**
- Add Kilocode to any provider listing section if one exists

**Directory:**
- Ensure `docs/providers/` directory exists before creating `KILOCODE.md` (it
may already be created by P3.1)

Research

The codebase currently has no provider adapter pattern — it is hardwired to the Claude CLI. The closest existing pattern is lib/sandbox_docker.sh, which demonstrates state management, command building (build_sandbox_exec_args), and status functions. Response normalization follows the pattern in lib/response_analyzer.sh which converts provider JSON to an internal struct with fields like status, exit_signal, session_id, files_modified, and confidence. This ticket depends on P3.1 (provider base infrastructure) which would establish the lib/agents/ directory structure and --provider flag routing.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the Kilocode provider adapter shell library at
`lib/agents/kilocode.sh`, following the structural patterns of
`lib/sandbox_docker.sh` for state management and `lib/response_analyzer.sh` for
response normalization.

**File setup:**
- Create `lib/agents/kilocode.sh` with a standard shell script header, a
`source` guard to prevent double-sourcing, and `source` declarations for
required core libraries

**Configuration variables** (define at the top of the file with defaults):
- `KILOCODE_CMD` — default: `kilo`
- `KILOCODE_MODEL` — empty by default
- `KILOCODE_TIMEOUT_MINUTES`
- `KILOCODE_AUTO_MODE` — boolean
- `KILOCODE_YOLO_MODE` — boolean

**`kilocode_is_available()`:**
- Check that the `kilo` CLI binary is installed and executable on the system
PATH

**`validate_kilocode_config()`:**
- Validate model format when `KILOCODE_MODEL` is set
- Check that timeout bounds are within acceptable ranges

**`build_kilocode_command(prompt_content, session_mode)`:**
- Populate a global `KILOCODE_CMD_ARGS` array (mirror the pattern of
`build_claude_command()`)
- Always include `--json-io` flag for headless structured bidirectional output
(no TUI)
- Conditionally add `--model` when `KILOCODE_MODEL` is set
- Conditionally add `--continue` only when `session_mode` is `"continue"` AND a
previous session exists (respect the continue-last limitation)
- Conditionally add `--auto` when `KILOCODE_AUTO_MODE` is enabled
- Conditionally add `--yolo` when `KILOCODE_YOLO_MODE` is enabled
- Append `prompt_content` as the final positional argument

**`parse_kilocode_response(output_file, result_file)`:**
- Follow the patterns of `parse_json_response()` from `lib/response_analyzer.sh`
- Extract and map the following fields to the internal struct schema:
- `status`: from Kilocode's completion indicator, mapped to `COMPLETE`/`UNKNOWN`
- `exit_signal`: from response structure or embedded `RALPH_STATUS` block in
output text
- `session_id`: with awareness that Kilocode only tracks "last session" — no
arbitrary ID retrieval
  - `files_modified`: from response metadata if available
  - `summary`: from result/output text field
- `input_tokens` / `output_tokens`: extracted if present, fallback to zero if
not
- Write the normalized JSON to `result_file`

**`get_kilocode_capabilities()`:**
- Return a JSON object with the following fields:
  - `structured_output: true`
  - `session_mode: "continue-last"`
  - `token_usage: "experimental"`
  - `permission_denials: false`
  - `api_limit_tracking: false`
- Add prominent inline comments documenting the session limitation (Ralph can
only resume the last session, not arbitrary sessions by ID)
===============================================================================

Task: 2

Create BATS test fixtures and test files for the Kilocode adapter, following the
existing patterns in `tests/unit/` and `tests/integration/`.

**Test fixtures** — create `tests/fixtures/kilocode/` and add the following JSON
files:
- `success_response.json` — a complete task response including files modified
and session info
- `continue_response.json` — a resumed session output
- `error_response.json` — a failed execution with error indicators
- `minimal_response.json` — the bare minimum valid output to test graceful
degradation
- `no_tokens_response.json` — a valid response with token usage fields absent

**Unit tests** — create `tests/unit/test_kilocode_adapter.bats`:
- Test `kilocode_is_available()` with a mock binary present and with the binary
absent
- Test `validate_kilocode_config()` for both valid and invalid configurations
- Test `build_kilocode_command()` for correct flag composition in all
combinations:
  - Basic invocation (prompt only)
  - Model override via `KILOCODE_MODEL`
  - Continue mode producing `--continue` flag
  - Auto mode producing `--auto` flag
  - YOLO mode producing `--yolo` flag
  - Combined flags in the expected order
- Test `parse_kilocode_response()` against each fixture file to confirm correct
normalization to the internal struct
- Test `get_kilocode_capabilities()` returns the exact expected capability
object

**Integration tests** — create `tests/integration/test_kilocode_execution.bats`:
- Test that `--provider kilocode` routes execution to the Kilocode adapter
- Test that session continuation enforces the "continue-last" limitation
(arbitrary session IDs are rejected)
- Test graceful failure when the `kilo` binary is not available
- Test that configuration validation errors surface with appropriate messages
- Mock CLI execution to verify correct command construction without requiring
Kilocode to be installed
===============================================================================

Task: 3

Create and update documentation files to cover the Kilocode provider.

**Create `docs/providers/KILOCODE.md`** with the following sections:
- **Overview**: Describe what Kilocode is and why a user would choose it with
Ralph
- **Installation**: Document the `npm install -g `@kilocode/cli`` prerequisite
- **Configuration**: List all `KILOCODE_*` environment variables with their
defaults and descriptions
- **Usage examples**: Show `ralph --provider kilocode`, usage with a model
override, and usage with YOLO mode
- **Session limitation**: Include a prominent callout/warning block explaining
that `--continue` only resumes the *last* session — Ralph cannot implement full
session continuity with Kilocode since arbitrary session IDs cannot be retrieved
- **Capability comparison**: Add a table comparing Kilocode vs Claude
capabilities side by side
- **Troubleshooting**: Cover common issues including binary not found and model
not available

**Update `README.md`:**
- Add a Kilocode row to the provider table with columns: name, session support
(`continue-last†`), structured output (`yes`), and a note referencing the
session limitation footnote

**Update `CLAUDE.md`:**
- Add Kilocode to any provider listing section if one exists

**Directory:**
- Ensure `docs/providers/` directory exists before creating `KILOCODE.md` (it
may already be created by P3.1)

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!