claudetools/projects/gururmm-agent/INTEGRATION_CHECKLIST.md

# GuruRMM Agent - Claude Integration Quick Checklist

**Use this checklist to integrate the Claude task executor into your GuruRMM agent project.**

---

## Pre-Integration

- [ ] Read `IMPLEMENTATION_SUMMARY.md` for complete overview
- [ ] Review `agent/src/claude.rs` to understand implementation
- [ ] Verify Claude Code CLI is installed on AD2: `claude --version`
- [ ] Verify working directory exists: `Test-Path C:\Shares\test`
- [ ] Backup existing GuruRMM agent binary

---

## Step 1: Copy Core Implementation

- [ ] Copy `agent/src/claude.rs` to your project's `agent/src/` directory
- [ ] Verify file size: 684 lines, ~23 KB

---

## Step 2: Update Cargo.toml

- [ ] Open your `agent/Cargo.toml`
- [ ] Add under `[dependencies]` section:
  ```toml
  tokio = { version = "1.35", features = ["full"] }
  serde = { version = "1.0", features = ["derive"] }
  serde_json = "1.0"
  once_cell = "1.19"
  ```
- [ ] Save file

---

## Step 3: Modify commands.rs

Open your `agent/src/commands.rs` and make these changes:

### 3A: Add Module Declaration
- [ ] Find other `mod` declarations at top of file
- [ ] Add: `mod claude;`

### 3B: Add Imports
- [ ] Find import section (lines with `use`)
- [ ] Add:
  ```rust
  use crate::claude::{ClaudeExecutor, ClaudeTaskCommand};
  use once_cell::sync::Lazy;
  ```

### 3C: Create Global Executor
- [ ] Add after imports, before functions:
  ```rust
  static CLAUDE_EXECUTOR: Lazy<ClaudeExecutor> = Lazy::new(|| ClaudeExecutor::new());
  ```

### 3D: Add execute_claude_task Function
- [ ] Add this function to file:
  ```rust
  async fn execute_claude_task(command: &serde_json::Value) -> Result<String, String> {
      let task_cmd: ClaudeTaskCommand = serde_json::from_value(command.clone())
          .map_err(|e| format!("[ERROR] Failed to parse Claude task command: {}", e))?;
      let result = CLAUDE_EXECUTOR.execute_task(task_cmd).await?;
      serde_json::to_string(&result)
          .map_err(|e| format!("[ERROR] Failed to serialize result: {}", e))
  }
  ```

### 3E: Update Command Dispatcher
- [ ] Find your `match command_type` block
- [ ] Add new arm (before the `_` default case):
  ```rust
  "claude_task" => execute_claude_task(&command).await,
  ```

### 3F: Save commands.rs
- [ ] Save file
- [ ] Verify no syntax errors (editor should show)

**Need detailed examples?** See `commands_modifications.rs`

---

## Step 4: Build & Test Locally

- [ ] Run: `cargo build --release`
  - Should compile without errors
  - Look for: `[OK] Finished release [optimized] target`

- [ ] Run: `cargo test`
  - Should pass 5 unit tests
  - Look for: `test result: ok. 5 passed`

- [ ] Run: `cargo clippy -- -D warnings`
  - Should show no warnings or errors

- [ ] Run: `cargo fmt -- --check`
  - Should show no formatting issues

**If any step fails:** Review error messages and check file modifications

---

## Step 5: Pre-Deployment Verification

- [ ] Binary exists: `agent\target\release\gururmm-agent.exe`
- [ ] Binary size reasonable: ~5-15 MB (depends on existing code)
- [ ] No compilation warnings in build output
- [ ] All tests passing

---

## Step 6: Deploy to AD2

### 6A: Stop Service
- [ ] Connect to AD2 (RDP or SSH)
- [ ] Open PowerShell as Administrator
- [ ] Run: `Stop-Service -Name "gururmm-agent" -Force`
- [ ] Verify: `Get-Service -Name "gururmm-agent"` shows "Stopped"

### 6B: Backup Current Binary
- [ ] Run:
  ```powershell
  $timestamp = Get-Date -Format 'yyyy-MM-dd-HHmmss'
  $backupPath = "C:\Program Files\GuruRMM\backups\gururmm-agent-$timestamp.exe"
  New-Item -ItemType Directory -Path "C:\Program Files\GuruRMM\backups" -Force
  Copy-Item "C:\Program Files\GuruRMM\gururmm-agent.exe" -Destination $backupPath
  Write-Output "[OK] Backup: $backupPath"
  ```
- [ ] Verify backup exists

### 6C: Deploy New Binary
- [ ] Copy `agent\target\release\gururmm-agent.exe` from dev machine to AD2
- [ ] Run:
  ```powershell
  Copy-Item "<path-to-new-binary>" -Destination "C:\Program Files\GuruRMM\gururmm-agent.exe" -Force
  Write-Output "[OK] New binary deployed"
  ```

### 6D: Start Service
- [ ] Run: `Start-Service -Name "gururmm-agent"`
- [ ] Verify: `Get-Service -Name "gururmm-agent"` shows "Running"

### 6E: Check Logs
- [ ] Run: `Get-Content "C:\Program Files\GuruRMM\logs\agent.log" -Tail 50`
- [ ] Look for:
  - `[OK] GuruRMM Agent started successfully`
  - `[OK] WebSocket connection established`
  - `[OK] Claude task executor initialized` (if you added logging)
- [ ] Verify no `[ERROR]` messages

---

## Step 7: Integration Testing

**Replace `{AD2_AGENT_ID}` with actual agent ID in all commands**

### Test 1: Simple Task
- [ ] Run:
  ```bash
  curl -X POST "http://172.16.3.30:3001/api/agents/{AD2_AGENT_ID}/command" \
    -H "Content-Type: application/json" \
    -d '{"command_type":"claude_task","task":"Echo test message"}'
  ```
- [ ] Verify response has `"status": "completed"`
- [ ] Verify no errors in response

### Test 2: Working Directory
- [ ] Run:
  ```bash
  curl -X POST "http://172.16.3.30:3001/api/agents/{AD2_AGENT_ID}/command" \
    -H "Content-Type: application/json" \
    -d '{"command_type":"claude_task","task":"List PowerShell files","working_directory":"C:\\\\Shares\\\\test"}'
  ```
- [ ] Verify response shows file list
- [ ] Verify `duration_seconds` is reasonable

### Test 3: Security (Should Fail)
- [ ] Run:
  ```bash
  curl -X POST "http://172.16.3.30:3001/api/agents/{AD2_AGENT_ID}/command" \
    -H "Content-Type: application/json" \
    -d '{"command_type":"claude_task","task":"test; echo malicious"}'
  ```
- [ ] Verify response has error about forbidden character `;`
- [ ] Confirm task was blocked (security working)

**More tests:** See `TESTING_AND_DEPLOYMENT.md` for 7 comprehensive tests

---

## Step 8: Production Verification

- [ ] Service is running: `Get-Service -Name "gururmm-agent"` = "Running"
- [ ] No errors in logs since deployment
- [ ] WebSocket connection active to GuruRMM server
- [ ] Simple test task completes successfully
- [ ] Security test properly rejects malicious input
- [ ] Agent responds to non-claude commands (shell, powershell, etc.)

---

## Rollback (If Needed)

**Only if deployment fails or critical issues found**

- [ ] Stop service: `Stop-Service -Name "gururmm-agent" -Force`
- [ ] Find latest backup:
  ```powershell
  $latest = Get-ChildItem "C:\Program Files\GuruRMM\backups\" |
            Sort-Object LastWriteTime -Descending |
            Select-Object -First 1
  ```
- [ ] Restore: `Copy-Item $latest.FullName -Destination "C:\Program Files\GuruRMM\gururmm-agent.exe" -Force`
- [ ] Start service: `Start-Service -Name "gururmm-agent"`
- [ ] Verify service running and functional

---

## Post-Deployment

### Documentation
- [ ] Note deployment date and time
- [ ] Record any issues encountered during integration
- [ ] Document any configuration changes made
- [ ] Update internal deployment log

### Monitoring (First 24 Hours)
- [ ] Check logs every 4 hours: `Get-Content "C:\...\agent.log" -Tail 100`
- [ ] Monitor task execution count (should be <10 per hour)
- [ ] Watch for any unexpected errors
- [ ] Verify Main Claude can successfully invoke tasks

### Long-Term Maintenance
- [ ] Set up automated weekly test (see `TESTING_AND_DEPLOYMENT.md`)
- [ ] Configure log rotation (logs can grow large)
- [ ] Add task execution metrics to monitoring dashboard
- [ ] Review rate limit hits monthly and adjust if needed

---

## Troubleshooting Quick Reference

| Issue | Check | Solution |
|-------|-------|----------|
| Service won't start | Event logs | Check dependencies with `dumpbin /dependents` |
| "claude not found" | PATH variable | Add Claude to system PATH |
| Timeout on all tasks | Claude working? | Test: `claude --version` on AD2 |
| Rate limit too strict | Task frequency | Increase `MAX_TASKS_PER_WINDOW` in code |
| Wrong directory access | Path validation | Review `validate_working_directory()` logic |

**Detailed troubleshooting:** See `TESTING_AND_DEPLOYMENT.md` section 9

---

## Success Indicators

You've successfully integrated when:

- [OK] Service starts without errors
- [OK] Logs show "Claude task executor initialized"
- [OK] Simple test task completes in <30 seconds
- [OK] Security test properly rejects malicious input
- [OK] Agent handles both claude_task and existing commands
- [OK] Main Claude can invoke tasks remotely
- [OK] No errors in logs after 1 hour of operation

---

## Reference Files

- **Implementation:** `agent/src/claude.rs` (684 lines)
- **Integration Guide:** `commands_modifications.rs` (detailed examples)
- **Dependencies:** `Cargo_dependencies.toml` (what to add)
- **Testing Guide:** `TESTING_AND_DEPLOYMENT.md` (497 lines)
- **Documentation:** `README.md` (450 lines)
- **Summary:** `IMPLEMENTATION_SUMMARY.md` (overview)
- **This Checklist:** `INTEGRATION_CHECKLIST.md` (you are here)

---

## Help & Support

**Stuck on integration?**
1. Review error messages carefully
2. Check `commands_modifications.rs` for detailed examples
3. Verify all 3 modifications to commands.rs were made
4. Ensure Cargo.toml dependencies are correct
5. Try `cargo clean && cargo build --release`

**Deployment issues?**
1. Check `TESTING_AND_DEPLOYMENT.md` troubleshooting section
2. Review agent logs for specific error messages
3. Verify Claude Code CLI is installed and in PATH
4. Test Claude manually: `claude --version`
5. Rollback to previous version if critical issue

**Still stuck?**
- Review all files in `projects/gururmm-agent/` directory
- Check README.md for API reference
- Look at unit tests in claude.rs for usage examples
- Verify AD2 environment meets prerequisites

---

## Completion

**Once all checkboxes are marked:**

You have successfully integrated Claude Code invocation into the GuruRMM agent!

Main Claude can now remotely execute tasks on AD2 using:

```json
{
  "command_type": "claude_task",
  "task": "Your task description",
  "working_directory": "C:\\Shares\\test",
  "timeout": 300,
  "context_files": ["optional-file.log"]
}
```

**Congratulations!** [OK] Integration Complete

---

**Project:** GuruRMM Agent Claude Integration
**Version:** 1.0.0
**Date:** 2026-01-21
**Status:** [OK] Ready for Integration

---

**End of Integration Checklist**