mvp-factory-openhands/OPENHANDS_INTEGRATION_STATUS.md

# OpenHands Integration Status Report

**Date:** 2025-11-30
**Phase:** OpenHands CLI Integration Testing
**Status:** Technical Blocker Identified

---

## Executive Summary

We attempted to integrate OpenHands with n8n workflows using both API and CLI approaches. While both methods show partial functionality, there are technical blockers preventing full automation:

1. **API Approach:** Conversations can be created, but runtime containers fail to start due to network namespace isolation
2. **CLI Approach:** Works interactively but requires TTY for auto-confirmation, which is problematic in non-TTY environments (like n8n SSH nodes)

---

## What We Tested

### 1. OpenHands CLI Direct Execution

**Command:** `/home/bam/.local/bin/openhands -t "Create a file"`

**Result:**
- ✅ CLI starts successfully
- ✅ Agent initializes with MiniMax-M2 model
- ✅ Task is processed and action created
- ❌ **BLOCKER:** Waits for interactive confirmation ("Choose an option:")
- ❌ File not created in non-TTY environment

**Output Log:**
```
Predicted Security Risk: LOW
Agent Action created, waiting for confirmation
Choose an option:
  Yes, proceed
  Reject
  Always proceed (don't ask again)

No input received; pausing agent.
```

### 2. OpenHands API Approach

**Test:** Create conversation via HTTP API

**Command:**
```bash
curl -X POST http://localhost:3000/api/conversations \
  -H "Content-Type: application/json" \
  -d '{"initial_user_msg": "Create a file"}'
```

**Result:**
- ✅ Conversation created successfully (ID: a23d491e55ae4e0995b563a54705d59c)
- ❌ **BLOCKER:** Runtime stuck at "STATUS$STARTING_RUNTIME"
- ❌ Network namespace isolation prevents runtime container from connecting

**Status Response:**
```json
{
  "status": "STARTING",
  "runtime_status": "STATUS$STARTING_RUNTIME",
  "conversation_id": "a23d491e55ae4e0995b563a54705d59c"
}
```

### 3. CLI Automation Attempts

#### Attempt 1: Python Wrapper (subprocess.PIPE)
**File:** `/home/bam/run-openhands.py`

**Result:**
- Created wrapper with stdin pipe
- Still receives TTY warning: "Warning: Input is not a terminal (fd=0)"
- Auto-confirmation logic attempted but unreliable

#### Attempt 2: Bash Script with Timeout
**File:** `/home/bam/test-openhands-cli.sh`

**Result:**
- Uses piped input: `echo -e "task\ny" | openhands -t ""`
- ❌ Input not properly received
- Task starts but never completes

#### Attempt 3: Python with pty Module
**File:** `/home/bam/openhands-pty.py`

**Result:**
- Created pseudo-TTY for proper terminal emulation
- Uses select() for async I/O
- ⏳ Still running during test (potential solution)

---

## n8n Workflows Created

We created three n8n workflow configurations:

### 1. Simple CLI Workflow
**File:** `/home/bam/claude/mvp-factory/openhands-cli-simple.json`
- Single SSH node
- Direct CLI execution
- Expected to fail due to TTY issues

### 2. tmux-based Workflow
**File:** `/home/bam/claude/mvp-factory/openhands-cli-tmux-workflow.json`
- Uses tmux for session management
- Attempts to run CLI in persistent session
- May work but untested

### 3. Complete Workflow with Webhook
**File:** `/home/bam/claude/mvp-factory/openhands-n8n-workflow.json`
- Webhook trigger for Gitea integration
- SSH execution node
- Verification node
- Response node
- **BEST CANDIDATE** for testing

---

## Root Cause Analysis

### Network Namespace Isolation Issue

**Problem:** OpenHands server runs on host network, but runtime containers are in bridge network. The `--add-host host.docker.internal:host-gateway` flag resolves DNS but not port connectivity.

**Evidence:**
- API responds on http://localhost:3000
- Conversation creation succeeds
- Runtime startup fails silently
- Status remains "STATUS$STARTING_RUNTIME"

### TTY/Interactive Input Issue

**Problem:** OpenHands CLI requires interactive confirmation for security, but n8n SSH nodes don't provide TTY.

**Evidence:**
- "Warning: Input is not a terminal (fd=0)"
- "Choose an option:" prompt appears
- Piped input not properly handled
- Auto-confirmation doesn't trigger

---

## Potential Solutions

### Solution 1: Improve Python Wrapper
**Approach:** Enhance `/home/bam/run-openhands.py` or `/home/bam/openhands-pty.py`

**Implementation:**
- Use pexpect library (if available) for robust interaction
- Implement proper response timing
- Add retry logic
- Test thoroughly

**Pros:**
- Works within existing setup
- No infrastructure changes
- Reusable for other automation

**Cons:**
- Requires Python library installation
- May still have timing issues

### Solution 2: Use tmux in n8n
**Approach:** Use tmux for persistent sessions in SSH node

**Implementation:**
```bash
tmux new-session -d -s task
tmux send-keys -t task 'openhands -t "task"' C-m
sleep 30
tmux capture-pane -t task -p
```

**Pros:**
- Provides proper TTY
- Industry-standard approach
- Works with existing SSH

**Cons:**
- Adds session management complexity
- Requires tmux on target system
- May timeout on long tasks

### Solution 3: Use OpenHands Built-in Automation
**Approach:** Check if OpenHands has non-interactive or batch mode

**Commands to check:**
```bash
openhands --help
openhands -h
cat ~/.openhands/settings.json
```

**Pros:**
- Official solution
- Most reliable
- Supported by upstream

**Cons:**
- May not exist in current version (1.3.0)

### Solution 4: API with Fixed Runtime
**Approach:** Fix network namespace issue for API approach

**Implementation:**
- Use host networking for runtime (dangerous)
- Custom Docker network configuration
- Different runtime architecture

**Pros:**
- Clean API interface
- Better error handling
- Proper status monitoring

**Cons:**
- Requires significant infrastructure changes
- Security implications
- May break other functionality

---

## Current Workflow Architecture

```
Gitea Push → n8n Webhook → SSH Node → OpenHands CLI → File Creation
                  ↓
            Verification Node
                  ↓
            Response to Gitea (optional)
```

**Webhooks:**
- Gitea → https://n8n.oky.sh/webhook/openhands-task
- n8n will execute OpenHands task
- Verify file creation
- Return status to Gitea (future enhancement)

---

## Immediate Next Steps

### Option 1: Continue with CLI Approach (Recommended)
1. Test the `openhands-pty.py` wrapper more thoroughly
2. If it works, update n8n workflow to use it
3. Test with real Gitea webhook
4. Add error handling and timeouts

### Option 2: Debug API Runtime Issue
1. Check Docker logs for runtime startup errors
2. Test network connectivity between containers
3. Try different Docker networking modes
4. If fixed, use API approach (cleaner)

### Option 3: Hybrid Approach
1. Use API to create conversation
2. Use CLI to execute task
3. Monitor status via API
4. Best of both worlds?

---

## Files Created/Modified

```
/home/bam/
├── run-openhands.py              # Python wrapper (original)
├── openhands-pty.py              # Python wrapper with pty
├── test-openhands-cli.sh         # Bash test script
├── start-openhands-fixed.sh      # Docker startup script
└── claude/mvp-factory/
    ├── openhands-cli-simple.json           # Simple workflow
    ├── openhands-cli-tmux-workflow.json    # tmux-based workflow
    ├── openhands-n8n-workflow.json         # Complete workflow
    └── OPENHANDS_INTEGRATION_STATUS.md     # This file
```

---

## Testing Required

### Pre-Production Testing

1. **Wrapper Script Testing**
   - [ ] Test `/home/bam/openhands-pty.py` with simple task
   - [ ] Verify file creation works
   - [ ] Test timeout handling
   - [ ] Test error handling

2. **n8n Workflow Testing**
   - [ ] Import `/home/bam/claude/mvp-factory/openhands-n8n-workflow.json`
   - [ ] Configure SSH credentials
   - [ ] Test webhook manually
   - [ ] Check execution logs

3. **End-to-End Testing**
   - [ ] Configure Gitea webhook
   - [ ] Push to test repository
   - [ ] Verify workflow triggers
   - [ ] Check OpenHands execution
   - [ ] Verify file creation

4. **Integration Testing**
   - [ ] Test with real project (not just file creation)
   - [ ] Test npm install & build
   - [ ] Test error scenarios
   - [ ] Test timeout handling

---

## Risks and Considerations

### Security Risks
- OpenHands has sudo access in container
- SSH credentials stored in n8n
- Webhook endpoints exposed publicly
- Runtime isolation issues

### Reliability Risks
- TTY issues may prevent automation
- Network namespace problems
- Timeout handling inadequate
- No retry logic currently

### Operational Risks
- Long-running tasks in SSH node
- Session management complexity
- Log storage and rotation
- Resource consumption

---

## Success Criteria

To consider this integration complete:

1. ✅ OpenHands can be triggered via n8n
2. ✅ Task executes successfully (not just starts)
3. ✅ File/folder creation verified
4. ✅ Gitea webhook triggers workflow
5. ✅ End-to-end flow works (Push → Build → Verify)
6. ✅ Error handling and timeouts implemented
7. ✅ Documentation updated

---

## Recommendations

### Immediate (Today)
1. **Test `openhands-pty.py` thoroughly**
   - If it works: Use in n8n workflow
   - If not: Debug and improve

2. **Use `/home/bam/claude/mvp-factory/openhands-n8n-workflow.json`**
   - Most complete workflow
   - Ready for testing
   - Good documentation

### Short-term (This Week)
1. **Fix remaining TTY/automation issues**
2. **Add proper error handling**
3. **Test with real build tasks**
4. **Configure Gitea webhook properly**

### Long-term
1. **Investigate API runtime fix**
2. **Add retry logic and timeouts**
3. **Implement proper status reporting**
4. **Add logging and monitoring**

---

## Conclusion

The OpenHands integration is **partially functional** but has **technical blockers** preventing full automation. Both API and CLI approaches work partially:

- **CLI:** Starts but doesn't complete due to TTY issues
- **API:** Creates conversations but runtime fails to start

**Next action:** Test the `openhands-pty.py` wrapper and if successful, integrate into n8n workflow for full automation testing.

---

## Appendix: Command Reference

### Test OpenHands CLI Directly
```bash
/home/bam/.local/bin/openhands -t "Create a test file"
# Press 'y' when prompted, then 'exit'
```

### Test Python Wrapper
```bash
python3 /home/bam/run-openhands.py "Create a file"
# Or
python3 /home/bam/openhands-pty.py "Create a file"
```

### Test API Directly
```bash
curl -X POST http://localhost:3000/api/conversations \
  -H "Content-Type: application/json" \
  -d '{"initial_user_msg": "Create a file"}'
```

### Check n8n Workflows
```bash
curl -u admin:password https://n8n.oky.sh/api/v1/workflows
```

### Monitor OpenHands Server
```bash
docker logs -f openhands-app
# Or if running via systemd
sudo journalctl -u openhands.service -f
```

---

**End of Report**