[P4.3] Droid adapter — build + parse + capabilities + tests + docs

[frankbria]

Phase 4 — Provider onboarding. (Factory Droid)

Scope

• lib/agents/droid.sh:
  • Build: droid exec, -o/--output-format json (and/or stream-jsonrpc),
    --session-id <id>, -m <id> (note default model is claude-opus-4-8),
    --auto <level> for approvals.
  • Parse: Droid json output -> internal struct.
  • Capabilities: structured=yes, session=resume-id, token usage=verify, api_limit=off.
• Tests via [P2.2]; docs/providers/DROID.md; README row.

Acceptance

• ralph --provider droid drives the loop against a mock. Full suite green.

Depends on: [P3.1].

[github-actions]

🏷️ Triage: enhancement

This issue has been categorized as an enhancement / feature request and labeled accordingly.

Why: [P4.3] is a provider-onboarding task — it adds a new Factory Droid adapter (lib/agents/droid.sh) so Ralph can drive the loop with ralph --provider droid. That's new functionality, not a defect, so it gets enhancement (alongside the existing multi-provider epic label).

Not a duplicate: each provider adapter is tracked as its own issue (Gemini #318, OpenCode #319, Kilocode #321, Copilot #322, Codex pilot #317). This is the distinct Droid slice, so it stands on its own.

Recommended next steps / sequencing:

• This task depends on [P3.1] ([P3.1] Codex adapter (pilot) — build + parse + capabilities + tests + docs #317) — the Codex pilot adapter, which establishes the adapter template and proves the seam end-to-end. Work here should start once [P3.1] Codex adapter (pilot) — build + parse + capabilities + tests + docs #317 lands.
• It also relies on the generic adapter test harness [P2.2] ([P2.2] Generic adapter test harness (mock CLIs) #316) for unit tests, and the contract/capabilities groundwork in [P0.2] ([P0.2] Define adapter interface contract + capabilities schema #311) / [P2.1] ([P2.1] Capabilities matrix + graceful feature degradation #315).
• Acceptance is clear: ralph --provider droid drives the loop against a mock with the full suite green, plus docs/providers/DROID.md and a README matrix row.

Note: the scope lists Droid's default model as claude-opus-4-8 and api_limit=off — worth confirming token-usage support against live droid exec --help output during implementation, since the issue marks it "verify".

Generated by Issue Triage Assistant for issue #320 · opus48 431.9K · ◷

[coderabbitai]

Coding Plan

Summary

• Create minimal agent provider infrastructure by extracting Claude logic to lib/agents/claude.sh and adding --provider routing, avoiding a heavyweight abstraction layer
• Implement Droid adapter following the proven sandbox adapter function naming conventions (validate_*, build_*_command, parse_*_response, get_*_capabilities)
• Leverage existing parse_json_response() multi-format support rather than building Droid-specific parsing from scratch
• Follow established test patterns with inline mode-parameterized mocks for comprehensive unit and integration coverage

Design Choices

Design Choice 1: Provider abstraction layer does not exist (P3.1 dependency)

Options Considered:

1. Block the ticket until a formal provider abstraction layer is built
2. Create minimal agent routing infrastructure inline as part of this ticket

Chosen Option: 2

Rationale: Create minimal routing infrastructure within this ticket, following the sandbox adapter pattern, to unblock Droid while keeping scope contained.

Design Choice 2: Droid CLI output format

Options Considered:

1. Assume Droid outputs a Claude-compatible JSON format with .result, .sessionId, .usage
2. Assume Droid outputs a flat format with top-level status, exit_signal, session_id, files_modified fields
3. Support both formats via the existing parse_json_response() three-format handling

Chosen Option: 3

Rationale: Leverage the existing parse_json_response() in response_analyzer.sh which already handles flat, object, and JSONL formats. The Droid adapter will normalize output to the flat format when needed.

Design Choice 3: Droid prompt input method

Options Considered:

1. Pass prompt via -p "<content>" flag (Claude-style)
2. Pass prompt via stdin
3. Pass prompt via file path argument

Chosen Option: 1

Rationale: Assume -p "<content>" flag for consistency with the Claude adapter pattern. This can be adjusted when actual Droid CLI documentation is available.

💡 User Tips

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

Implementation Steps

Phase 1: Agent Provider Infrastructure

Create the foundational infrastructure to support multiple agent providers, adding the --provider flag and agent routing logic to ralph_loop.sh.

Task 1: Add --provider CLI Flag and Configuration

Add the provider selection mechanism to Ralph's CLI and configuration system.

• Add AGENT_PROVIDER variable to ralph_loop.sh configuration section (near line 104), defaulting to "claude"
• Add --provider <name> flag parsing in main() CLI argument handling (near line 2556)
• Add AGENT_PROVIDER support in .ralphrc loading via load_ralphrc() function
• Validate provider value is one of: claude, droid

Task 2: Create Agent Directory Structure

Establish the lib/agents/ directory following sandbox adapter conventions.

• Create lib/agents/ directory
• Create lib/agents/claude.sh by extracting Claude-specific logic from ralph_loop.sh (specifically build_claude_command() lines 1535-1628)
• Move Claude command building, validation, and output format handling to the extracted adapter
• Ensure existing functionality remains intact after extraction

Task 3: Implement Agent Routing in Main Loop

Add dispatch logic to route between Claude and Droid adapters based on AGENT_PROVIDER.

• Add agent adapter sourcing in ralph_loop.sh based on AGENT_PROVIDER value
• Create build_agent_command() dispatcher function that calls build_claude_command() or build_droid_command() based on provider
• Update execute_claude_code() (or rename to execute_agent_code()) to use the dispatcher
• Ensure wrap_claude_command_for_sandbox() works with both providers' command arrays

🤖 Prompt for AI agents

Implement the foundational agent provider infrastructure in `ralph_loop.sh` and
create the `lib/agents/` directory with an extracted Claude adapter. The goal is
to add `--provider` routing without breaking existing Claude functionality.

- In `ralph_loop.sh` configuration section (near line 104), add `AGENT_PROVIDER`
variable defaulting to `"claude"`
- In `main()` CLI argument handling (near line 2556), add `--provider <name>`
flag parsing
- In `load_ralphrc()`, add support for loading `AGENT_PROVIDER` from `.ralphrc`
- Add validation that `AGENT_PROVIDER` is one of: `claude`, `droid`
- Create the `lib/agents/` directory
- Create `lib/agents/claude.sh` by extracting Claude-specific logic from
`ralph_loop.sh`, specifically `build_claude_command()` (lines 1535-1628),
including Claude command building, validation, and output format handling
- Ensure all existing functionality remains intact after extraction
- Add agent adapter sourcing in `ralph_loop.sh` based on the `AGENT_PROVIDER`
value
- Create a `build_agent_command()` dispatcher function that calls
`build_claude_command()` or `build_droid_command()` based on provider
- Update `execute_claude_code()` (or rename to `execute_agent_code()`) to use
the dispatcher
- Ensure `wrap_claude_command_for_sandbox()` works with both providers' command
arrays

Phase 2: Droid Adapter Implementation

Implement the complete Droid adapter with build, parse, and capabilities functions.

Task 1: Create Droid Adapter Core

Create lib/agents/droid.sh with configuration validation and command building.

• Create lib/agents/droid.sh following the sandbox adapter function naming pattern
• Implement validate_droid_config(): check DROID_CMD exists (default: droid), validate DROID_MODEL if set
• Implement build_droid_command(prompt_file, loop_context, session_id):
  • Start with AGENT_CMD_ARGS=("$DROID_CMD" "exec")
  • Add -m "$DROID_MODEL" (default: claude-opus-4-8)
  • Add -o "json" for structured output
  • Add --session-id "$session_id" when session_id is non-empty
  • Add --auto "$DROID_AUTO_LEVEL" for approval handling (default: configurable)
  • Add -p "$(cat $prompt_file)" for prompt content
• Export DROID_CMD, DROID_MODEL, DROID_AUTO_LEVEL configuration variables

Task 2: Implement Droid Response Parsing

Add Droid-specific output parsing that integrates with the existing response analyzer.

• Implement parse_droid_response(output_file) in lib/agents/droid.sh
• Extract session ID from Droid's response format (assumed: .session_id or .metadata.session_id)
• Extract token usage from Droid's response (assumed: .usage.input_tokens, .usage.output_tokens)
• Transform Droid output to the flat format expected by parse_json_response() if needed
• Handle the is_error field for error propagation (follow Claude pattern)

Task 3: Define Droid Capabilities

Implement capability declarations that the main loop can query.

• Add get_droid_capabilities() function returning capability flags:
  • structured=yes (always uses JSON output)
  • session=resume-id (supports session continuation via --session-id)
  • token_usage=yes (response includes usage data)
  • api_limit=no (no special rate limit handling needed)
• Add droid_supports_capability(capability_name) helper for main loop queries
• Integrate capability checks into execute_agent_code() for conditional behavior

Task 4: Session and Token Integration

Wire Droid session persistence and token tracking into the existing infrastructure.

• Update save_claude_session() (or create save_agent_session()) to handle Droid's session ID location
• Update extract_token_usage() in ralph_loop.sh to support Droid's token fields
• Ensure .ralph/.claude_session_id file works for Droid (or create provider-specific session files)
• Update init_claude_session() to be provider-aware for session expiry checks

🤖 Prompt for AI agents

Create `lib/agents/droid.sh` implementing the full Droid adapter — config
validation, command building, response parsing, capabilities, and session/token
integration. Follow the sandbox adapter function naming conventions
(`validate_*`, `build_*_command`, `parse_*_response`, `get_*_capabilities`).

**Core adapter (`lib/agents/droid.sh`):**
- Implement `validate_droid_config()`: check that `DROID_CMD` exists (default:
`droid`), validate `DROID_MODEL` if set
- Implement `build_droid_command(prompt_file, loop_context, session_id)`:
  - Start with `AGENT_CMD_ARGS=("$DROID_CMD" "exec")`
  - Add `-m "$DROID_MODEL"` (default: `claude-opus-4-8`)
  - Add `-o "json"` for structured output
  - Add `--session-id "$session_id"` when session_id is non-empty
- Add `--auto "$DROID_AUTO_LEVEL"` for approval handling (default: configurable)
  - Add `-p "$(cat $prompt_file)"` for prompt content
- Export `DROID_CMD`, `DROID_MODEL`, `DROID_AUTO_LEVEL` configuration variables

**Response parsing:**
- Implement `parse_droid_response(output_file)` in `lib/agents/droid.sh`
- Extract session ID from `.session_id` or `.metadata.session_id`
- Extract token usage from `.usage.input_tokens` and `.usage.output_tokens`
- Transform Droid output to the flat format expected by `parse_json_response()`
if needed
- Handle the `is_error` field for error propagation following the Claude pattern

**Capabilities:**
- Add `get_droid_capabilities()` returning: `structured=yes`,
`session=resume-id`, `token_usage=yes`, `api_limit=no`
- Add `droid_supports_capability(capability_name)` helper for main loop queries
- Integrate capability checks into `execute_agent_code()` for conditional
behavior

**Session and token integration:**
- Update `save_claude_session()` (or create `save_agent_session()`) to handle
Droid's session ID location
- Update `extract_token_usage()` in `ralph_loop.sh` to support Droid's token
fields
- Ensure `.ralph/.claude_session_id` works for Droid or create provider-specific
session files
- Update `init_claude_session()` to be provider-aware for session expiry checks

Phase 3: Tests and Documentation

Create comprehensive tests following P2.2 patterns and complete documentation.

Task 1: Create Droid Unit Tests

Implement unit tests for all Droid adapter functions.

• Create tests/unit/test_agent_droid.bats following the pattern in test_sandbox_docker.bats
• Implement _mock_droid() helper with mode parameter (ok, no-binary, exec-fail, session-fail)
• Write tests for validate_droid_config(): accepts defaults, rejects missing binary
• Write tests for build_droid_command(): correct flag order, session handling, model override
• Write tests for parse_droid_response(): session extraction, token extraction, error handling
• Write tests for get_droid_capabilities(): returns expected capability set

Task 2: Create Integration Tests

Implement integration tests that verify Droid works within the Ralph loop.

• Create tests/integration/test_droid_execution.bats following test_docker_execution.bats pattern
• Source ralph_loop.sh and wire mock Droid to test --provider droid routing
• Test that build_agent_command() dispatches correctly to build_droid_command()
• Test session persistence across mocked loop iterations
• Test token counting accumulation with Droid responses

Task 3: Create Provider Documentation

Create comprehensive Droid provider documentation.

• Create docs/DROID.md (following existing docs/DOCKER_SANDBOX.md structure, not docs/providers/)
• Include sections: Architecture, Setup, CLI Reference, .ralphrc Configuration, Session Management, Troubleshooting
• Document the --provider droid flag and all DROID_* configuration variables
• Include example commands and expected output formats

Task 4: Update Existing Documentation

Update README, CLAUDE.md, and templates to reflect the new provider.

• Update README.md: Add Droid to provider section, add --provider flag documentation, add example commands
• Update CLAUDE.md: Add library component entry for lib/agents/droid.sh, update Key Commands with --provider section, revise "final provider set" statement
• Update templates/ralphrc.template: Add AGENT_PROVIDER and DROID_* configuration block following Docker/E2B section pattern

🤖 Prompt for AI agents

Create comprehensive unit tests, integration tests, and documentation for the
Droid adapter. Follow existing test patterns and documentation structure
throughout.

**Unit tests (`tests/unit/test_agent_droid.bats`):**
- Follow the pattern in `test_sandbox_docker.bats`
- Implement `_mock_droid()` helper with mode parameter: `ok`, `no-binary`,
`exec-fail`, `session-fail`
- Write tests for `validate_droid_config()`: accepts defaults, rejects missing
binary
- Write tests for `build_droid_command()`: correct flag order, session handling,
model override
- Write tests for `parse_droid_response()`: session extraction, token
extraction, error handling
- Write tests for `get_droid_capabilities()`: returns expected capability set

**Integration tests (`tests/integration/test_droid_execution.bats`):**
- Follow `test_docker_execution.bats` pattern
- Source `ralph_loop.sh` and wire mock Droid to test `--provider droid` routing
- Test that `build_agent_command()` dispatches correctly to
`build_droid_command()`
- Test session persistence across mocked loop iterations
- Test token counting accumulation with Droid responses

**Provider documentation (`docs/DROID.md`):**
- Follow the existing `docs/DOCKER_SANDBOX.md` structure (not `docs/providers/`)
- Include sections: Architecture, Setup, CLI Reference, `.ralphrc`
Configuration, Session Management, Troubleshooting
- Document the `--provider droid` flag and all `DROID_*` configuration variables
- Include example commands and expected output formats

**Update existing documentation:**
- `README.md`: Add Droid to provider section, add `--provider` flag
documentation, add example commands
- `CLAUDE.md`: Add library component entry for `lib/agents/droid.sh`, update Key
Commands with `--provider` section, revise "final provider set" statement
- `templates/ralphrc.template`: Add `AGENT_PROVIDER` and `DROID_*` configuration
block following the Docker/E2B section pattern

Research

Ralph is currently a Claude-only autonomous development loop system. There is no agent provider abstraction—the Claude CLI is hardcoded throughout ralph_loop.sh via build_claude_command() and execute_claude_code(). The codebase does have a sandbox provider pattern (lib/sandbox_docker.sh, lib/sandbox_e2b.sh) with consistent function naming conventions that can inform the agent adapter design. Response parsing is centralized in lib/response_analyzer.sh, which handles three JSON formats and writes normalized output to .ralph/.json_parse_result. The test framework uses inline mock scripts written to disk with mode-parameterized behavior, and documentation follows a consistent structure in docs/.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the foundational agent provider infrastructure in `ralph_loop.sh` and
create the `lib/agents/` directory with an extracted Claude adapter. The goal is
to add `--provider` routing without breaking existing Claude functionality.

- In `ralph_loop.sh` configuration section (near line 104), add `AGENT_PROVIDER`
variable defaulting to `"claude"`
- In `main()` CLI argument handling (near line 2556), add `--provider <name>`
flag parsing
- In `load_ralphrc()`, add support for loading `AGENT_PROVIDER` from `.ralphrc`
- Add validation that `AGENT_PROVIDER` is one of: `claude`, `droid`
- Create the `lib/agents/` directory
- Create `lib/agents/claude.sh` by extracting Claude-specific logic from
`ralph_loop.sh`, specifically `build_claude_command()` (lines 1535-1628),
including Claude command building, validation, and output format handling
- Ensure all existing functionality remains intact after extraction
- Add agent adapter sourcing in `ralph_loop.sh` based on the `AGENT_PROVIDER`
value
- Create a `build_agent_command()` dispatcher function that calls
`build_claude_command()` or `build_droid_command()` based on provider
- Update `execute_claude_code()` (or rename to `execute_agent_code()`) to use
the dispatcher
- Ensure `wrap_claude_command_for_sandbox()` works with both providers' command
arrays
===============================================================================

Task: 2

Create `lib/agents/droid.sh` implementing the full Droid adapter — config
validation, command building, response parsing, capabilities, and session/token
integration. Follow the sandbox adapter function naming conventions
(`validate_*`, `build_*_command`, `parse_*_response`, `get_*_capabilities`).

**Core adapter (`lib/agents/droid.sh`):**
- Implement `validate_droid_config()`: check that `DROID_CMD` exists (default:
`droid`), validate `DROID_MODEL` if set
- Implement `build_droid_command(prompt_file, loop_context, session_id)`:
  - Start with `AGENT_CMD_ARGS=("$DROID_CMD" "exec")`
  - Add `-m "$DROID_MODEL"` (default: `claude-opus-4-8`)
  - Add `-o "json"` for structured output
  - Add `--session-id "$session_id"` when session_id is non-empty
- Add `--auto "$DROID_AUTO_LEVEL"` for approval handling (default: configurable)
  - Add `-p "$(cat $prompt_file)"` for prompt content
- Export `DROID_CMD`, `DROID_MODEL`, `DROID_AUTO_LEVEL` configuration variables

**Response parsing:**
- Implement `parse_droid_response(output_file)` in `lib/agents/droid.sh`
- Extract session ID from `.session_id` or `.metadata.session_id`
- Extract token usage from `.usage.input_tokens` and `.usage.output_tokens`
- Transform Droid output to the flat format expected by `parse_json_response()`
if needed
- Handle the `is_error` field for error propagation following the Claude pattern

**Capabilities:**
- Add `get_droid_capabilities()` returning: `structured=yes`,
`session=resume-id`, `token_usage=yes`, `api_limit=no`
- Add `droid_supports_capability(capability_name)` helper for main loop queries
- Integrate capability checks into `execute_agent_code()` for conditional
behavior

**Session and token integration:**
- Update `save_claude_session()` (or create `save_agent_session()`) to handle
Droid's session ID location
- Update `extract_token_usage()` in `ralph_loop.sh` to support Droid's token
fields
- Ensure `.ralph/.claude_session_id` works for Droid or create provider-specific
session files
- Update `init_claude_session()` to be provider-aware for session expiry checks
===============================================================================

Task: 3

Create comprehensive unit tests, integration tests, and documentation for the
Droid adapter. Follow existing test patterns and documentation structure
throughout.

**Unit tests (`tests/unit/test_agent_droid.bats`):**
- Follow the pattern in `test_sandbox_docker.bats`
- Implement `_mock_droid()` helper with mode parameter: `ok`, `no-binary`,
`exec-fail`, `session-fail`
- Write tests for `validate_droid_config()`: accepts defaults, rejects missing
binary
- Write tests for `build_droid_command()`: correct flag order, session handling,
model override
- Write tests for `parse_droid_response()`: session extraction, token
extraction, error handling
- Write tests for `get_droid_capabilities()`: returns expected capability set

**Integration tests (`tests/integration/test_droid_execution.bats`):**
- Follow `test_docker_execution.bats` pattern
- Source `ralph_loop.sh` and wire mock Droid to test `--provider droid` routing
- Test that `build_agent_command()` dispatches correctly to
`build_droid_command()`
- Test session persistence across mocked loop iterations
- Test token counting accumulation with Droid responses

**Provider documentation (`docs/DROID.md`):**
- Follow the existing `docs/DOCKER_SANDBOX.md` structure (not `docs/providers/`)
- Include sections: Architecture, Setup, CLI Reference, `.ralphrc`
Configuration, Session Management, Troubleshooting
- Document the `--provider droid` flag and all `DROID_*` configuration variables
- Include example commands and expected output formats

**Update existing documentation:**
- `README.md`: Add Droid to provider section, add `--provider` flag
documentation, add example commands
- `CLAUDE.md`: Add library component entry for `lib/agents/droid.sh`, update Key
Commands with `--provider` section, revise "final provider set" statement
- `templates/ralphrc.template`: Add `AGENT_PROVIDER` and `DROID_*` configuration
block following the Docker/E2B section pattern

💡 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!