[3/3] Add OpenClaw adapter (RFC 005)

[Darktex]

Summary

Stacked on #390 (HarnessEnvironment).

Adds the first concrete HarnessAdapter implementation for OpenClaw, validating the adapter abstraction works with a real harness.

OpenClawAdapter

• Process lifecycle: Starts OpenClaw via asyncio.create_subprocess_exec, terminates on stop
• MCP tool injection: Writes mcpServers.openenv entries to .openclaw/openclaw.json, merges with existing config
• Communication: JSON-line protocol over stdin/stdout (sends {"message": "..."}, reads JSON response)
• Event extraction: Parses tool_calls from JSON responses into HarnessEvent objects
• Streaming: send_message_streaming() yields events from the turn
• Error handling: Session timeout detection, plain-text response fallback

Stack

#387  RFC 005: Agentic Harness Integration
  └── #389  Foundation types (HarnessConfig, HarnessAdapter, HarnessEvent, etc.)
       └── #390  HarnessEnvironment (multi-turn, trajectory)
            └── This PR: OpenClaw adapter

Test plan

• 18 unit tests with mocked subprocess (no OpenClaw binary required)
• Config file injection tested with real filesystem (tmp_path)
• 87 total harness tests pass
• Lint clean

Part of #385

[greptile-apps]

Greptile Summary

Adds the first concrete HarnessAdapter implementation for OpenClaw, validating RFC 005's adapter abstraction with a real harness.

Key Changes:

• Process lifecycle: Manages OpenClaw subprocess via asyncio with stdin/stdout pipes
• MCP tool injection: Writes mcpServers.openenv entries to .openclaw/openclaw.json, merges with existing config
• Communication: JSON-line protocol over stdin/stdout, parses responses with tool call extraction
• Event extraction: Maps OpenClaw responses to HarnessEvent objects for trajectory tracking
• Error handling: Implements session timeout detection and plain-text response fallback

Testing:

• 18 unit tests with mocked subprocess (no OpenClaw binary required)
• Config file injection tested with real filesystem operations
• Lifecycle, streaming, and integration with HarnessEnvironment covered

Alignment:

• Respects dual API boundary (no agent access to reset/step)
• Follows MCP as universal standard for tool injection
• Maintains container isolation via working directory constraints
• Implements RFC 005 design as specified

Confidence Score: 4/5

• Safe to merge with one minor style improvement recommended
• Implementation correctly follows RFC 005 design, includes comprehensive test coverage (18 tests), properly handles edge cases (timeouts, plain text responses, config merging). Only minor style issue with nested import. All system invariants respected (dual API boundary, agent isolation, MCP standard).
• No files require special attention

Important Files Changed

Filename	Overview
src/openenv/core/harnesses/adapters/init.py	Exports OpenClawAdapter - clean, standard module init
src/openenv/core/harnesses/adapters/openclaw.py	OpenClaw adapter with subprocess management, MCP tool injection, JSON-line communication - minor style issue with nested import
tests/core/test_harnesses/test_openclaw_adapter.py	Comprehensive test suite (18 tests) covering lifecycle, tool injection, messaging, streaming with mocked subprocess

Sequence Diagram

sequenceDiagram
    participant HE as HarnessEnvironment
    participant OCA as OpenClawAdapter
    participant OC as OpenClaw Process
    participant LLM as LLM Endpoint

    Note over HE,LLM: Initialization Phase
    HE->>OCA: inject_tools(tools)
    OCA->>OCA: Write .openclaw/openclaw.json
    Note right of OCA: Merge with existing config<br/>Add mcpServers.openenv entry
    
    HE->>OCA: start(working_directory)
    OCA->>OC: create_subprocess_exec()
    Note right of OC: Process started with<br/>stdin/stdout/stderr pipes

    Note over HE,LLM: Conversational Turn (step)
    HE->>OCA: send_message("Fix the bug")
    OCA->>OC: stdin.write({"message": "..."})
    Note right of OCA: JSON-line protocol
    
    OC->>LLM: LLM inference request
    LLM-->>OC: Response with tool_calls
    
    OC->>OC: Execute tool calls<br/>(read_file, write_file, etc)
    
    OC-->>OCA: stdout: {"response": "Done", "tool_calls": [...]}
    Note right of OCA: Parse JSON response<br/>Extract tool events
    
    OCA-->>HE: HarnessResponse(events, done)
    Note left of HE: Returns observation<br/>with trajectory events

    Note over HE,LLM: Cleanup Phase
    HE->>OCA: stop()
    OCA->>OC: terminate()
    alt Graceful shutdown
        OC-->>OCA: Process exits (returncode 0)
    else Timeout
        OCA->>OC: kill()
    end

Loading

_{Last reviewed commit: 00f509b}

[greptile-apps]

_{3 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}