mvp-factory-setups/OPENHANDS_SDK_SETUP.md

# OpenHands SDK + n8n Integration Guide

**Updated:** 2025-12-01
**Status:** ✅ WORKING - SDK wrapper approach successful

## ✅ What's Working

### Core Components:
- **OpenHands CLI:** `/home/bam/.local/bin/openhands` (v1.3.0)
- **SDK Wrapper:** `/home/bam/openhands-sdk-wrapper-sh.sh` (sh-compatible)
- **n8n Workflow:** "OpenHands SDK Clean Working" (ID: 9cgyx4hHEvGjyEaE)
- **SSH Authentication:** Working (permissions fixed)
- **File Verification:** Working (workflow confirms creation)

### Key Files:
```
/home/bam/openhands-sdk-wrapper-sh.sh  # Main wrapper script (sh-compatible)
/home/bam/OPENHANDS_N8N_WORKING.json   # Working n8n workflow template
/home/bam/openhands/.env               # API keys (MiniMax, DeepSeek)
/home/bam/.ssh/                        # SSH credentials (fixed permissions)
```

## 🎯 Next Steps: Gitea Webhook Integration

### Step 1: Create Gitea Repository & Webhook

**In Gitea (https://git.oky.sh):**

1. **Create Test Repository:**
   ```bash
   # Or via web UI: New Repository → "test-project"
   ```

2. **Add Webhook:**
   - Settings → Webhooks → Add Webhook → Gitea
   - **URL:** `https://n8n.oky.sh/webhook/gitea-push`
   - **Method:** POST
   - **Content Type:** application/json
   - **Secret:** [generate random string]
   - **Trigger:** Push events
   - **Active:** ✓

### Step 2: Update n8n Workflow for Webhook

**Current Workflow:** Manual Trigger → OpenHands SDK → Verify

**New Workflow Design:**
```
[1] Webhook Trigger (Gitea push)
     ↓
[2] JSON Parser - Extract repo info
     ↓
[3] SSH - Clone repository
     → git clone https://git.oky.sh/user/repo.git /home/bam/workspace/repo
     ↓
[4] SSH - Execute OpenHands SDK
     → sh /home/bam/openhands-sdk-wrapper-sh.sh "Build and test project {{ $json.repository.name }}"
     ↓
[5] SSH - Verify build artifacts
     → Check for dist/, build/, or test results
     ↓
[6] HTTP - Update Gitea commit status
     → POST /api/v1/repos/{owner}/{repo}/statuses/{sha}
```

### Step 3: n8n Webhook Node Configuration

**Node 1: Webhook Trigger**
```json
{
  "path": "gitea-push",
  "httpMethod": "POST",
  "responseMode": "responseNode"
}
```

**Node 2: Extract Data (Set Node)**
```json
{
  "repository": "{{ $json.repository.full_name }}",
  "clone_url": "{{ $json.repository.clone_url }}",
  "commit": "{{ $json.after }}",
  "branch": "{{ $json.ref }}"
}
```

**Node 3: Clone Repo (SSH Node)**
```bash
cd /home/bam/workspace
if [ -d "{{ $json.repository.name }}" ]; then
  cd {{ $json.repository.name }} && git pull
else
  git clone {{ $json.clone_url }}
fi
```

**Node 4: Execute OpenHands (SSH Node)**
```bash
sh /home/bam/openhands-sdk-wrapper-sh.sh \
  "Navigate to /home/bam/workspace/{{ $json.repository.name }} and run: npm install && npm test && npm build. Report any errors."
```

**Node 5: Verify Success (SSH Node)**
```bash
cd /home/bam/workspace/{{ $json.repository.name }}
if [ -d "dist" ] || [ -f "build/index.html" ]; then
  echo "BUILD_SUCCESS"
else
  echo "BUILD_FAILED"
fi
```

**Node 6: Update Gitea (HTTP Request)**
```json
{
  "url": "https://git.oky.sh/api/v1/repos/{{ $json.repository }}/statuses/{{ $json.commit }}",
  "method": "POST",
  "headers": {
    "Authorization": "token YOUR_GITEA_TOKEN",
    "Content-Type": "application/json"
  },
  "body": {
    "state": "success",
    "description": "Build passed - OpenHands SDK",
    "context": "openhands/build"
  }
}
```

## 🧪 Testing Workflow

### Test 1: Manual Webhook Test
```bash
# In Gitea webhook settings, click "Test Delivery"
# Should trigger n8n workflow
```

### Test 2: Git Push Test
```bash
cd /home/bam/workspace/test-project
echo "Test" > README.md
git add .
git commit -m "Test webhook trigger"
git push origin main

# Check n8n execution at: https://n8n.oky.sh
# Verify OpenHands SDK executed
# Check Gitea commit status updated
```

### Test 3: Build Failure Test
```bash
# Add intentional error to code
git commit -am "Introduce syntax error" && git push

# Verify:
# - n8n workflow runs
# - OpenHands SDK detects error
# - Gitea commit status shows "failure"
```

## 📋 Node Configuration Details

### SSH Nodes (Repeat for each):
- **Credential:** SSH Private Key account
- **Authentication:** privateKey
- **Host:** localhost
- **User:** bam

### Environment Variables:
```bash
# Loaded by wrapper script from /home/bam/openhands/.env:
MINIMAX_API_KEY=xxx      # Primary LLM
DEEPSEEK_API_KEY=xxx     # Fallback LLM
```

## ✅ Success Criteria

**Integration Complete When:**
1. ✅ Git push triggers n8n workflow
2. ✅ n8n clones repository
3. ✅ OpenHands SDK executes build/test
4. ✅ Workflow returns success/failure
5. ✅ Gitea commit status updated
6. ✅ End-to-end: Push → Build → Status Update

## 🔧 Troubleshooting

### SSH Authentication Fails:
```bash
# Check ownership
sudo chown -R bam:bam /home/bam /home/bam/.ssh
sudo chmod 755 /home/bam
```

### Webhook Not Triggering:
```bash
# Check n8n webhook URL
curl https://n8n.oky.sh/webhook/gitea-push

# Check Gitea webhook logs
# Repository → Settings → Webhooks → Recent Deliveries
```

### OpenHands SDK Hangs:
```bash
# Wrapper script should handle this
# Check /tmp/software-agent-sdk/ logs
tail -f /tmp/software-agent-sdk/logs/*.log
```

## 📚 Quick Reference

### Workflow ID:
- **Production:** `9cgyx4hHEvGjyEaE` (OpenHands SDK Clean Working)

### Wrapper Usage:
```bash
sh /home/bam/openhands-sdk-wrapper-sh.sh "Your task description here"
```

### Test Workflow:
```bash
# In n8n UI: https://n8n.oky.sh
# Click "OpenHands SDK Clean Working"
# Click "Execute Workflow"
```

---

**Current Status:** Ready to proceed with Gitea webhook integration
**Next Action:** Create test repository and configure webhook