supervisor/QUICK_START.md

# Quick Start Guide

Complete guide to running the Hero Supervisor with OSIS runners and examples.

## Prerequisites

1. **Redis** - Must be running
2. **Rust** - Version 1.88+ (run `rustup update`)

## 1. Start Redis

```bash
redis-server
```

## 2. Start Supervisor

```bash
cd /Users/timurgordon/code/git.ourworld.tf/herocode/supervisor
cargo run --bin supervisor
```

You should see:
```
╔════════════════════════════════════════════════════════════╗
║  Hero Supervisor Started                                   ║
╚════════════════════════════════════════════════════════════╝
  📡 OpenRPC Server: http://127.0.0.1:3030
  🔗 Redis: redis://localhost:6379
  🌐 Mycelium: Not compiled (use --features mycelium)
╚════════════════════════════════════════════════════════════╝
```

## 3. Start OSIS Runner

```bash
cd /Users/timurgordon/code/git.ourworld.tf/herocode/runner_rust
cargo run --bin runner_osis -- test_runner \
    --redis-url redis://localhost:6379 \
    --db-path /tmp/test_runner.db
```

You should see:
```
Starting OSIS Sync Runner with ID: test_runner
Database path: /tmp/test_runner.db
Redis URL: redis://localhost:6379
OSIS Sync Runner 'test_runner' started successfully
```

## 4. Run Example

```bash
cd /Users/timurgordon/code/git.ourworld.tf/herocode/supervisor
RUST_LOG=info cargo run --example simple_e2e
```

## Terminal Layout

```
┌─────────────────────┬─────────────────────┐
│  Terminal 1         │  Terminal 2         │
│  Redis              │  Supervisor         │
│  redis-server       │  cargo run --bin    │
│                     │  supervisor         │
├─────────────────────┼─────────────────────┤
│  Terminal 3         │  Terminal 4         │
│  OSIS Runner        │  Example            │
│  cargo run --bin    │  cargo run          │
│  runner_osis        │  --example          │
│                     │  simple_e2e         │
└─────────────────────┴─────────────────────┘
```

## What Each Component Does

### Redis
- Job queue storage
- Job result storage
- Runner coordination

### Supervisor
- OpenRPC HTTP server (port 3030)
- Job dispatch to runners
- Runner registration
- Job execution coordination

### OSIS Runner
- Listens for jobs on Redis queue
- Executes Rhai scripts
- Stores results back to Redis
- Uses HeroDB for data persistence

### Example
- Creates jobs with Rhai scripts
- Sends jobs to supervisor via OpenRPC
- Receives results
- Demonstrates both blocking and non-blocking modes

## Architecture

```
┌─────────────┐
│   Example   │  (simple_e2e.rs)
└──────┬──────┘
       │ HTTP/JSON-RPC
       ▼
┌─────────────┐
│ Supervisor  │  (port 3030)
└──────┬──────┘
       │ Redis Queue
       ▼
┌─────────────┐
│ OSIS Runner │  (test_runner)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   HeroDB    │  (Redis + local DB)
└─────────────┘
```

## Troubleshooting

### "Connection refused" on port 3030
- Make sure supervisor is running
- Check if another process is using port 3030

### "Connection refused" on port 6379
- Make sure Redis is running
- Check: `redis-cli ping` (should return "PONG")

### Runner not receiving jobs
- Check runner is registered: Look for "Runner registered successfully" in example output
- Check Redis connection: Both supervisor and runner must use same Redis URL
- Check queue name matches: Should be `hero:q:work:type:osis:group:default:inst:test_runner`

### "Job execution timeout"
- Increase timeout in job builder: `.timeout(120)`
- Check if runner is actually processing jobs (look for logs)

## Example Output

### Successful Run

```
╔════════════════════════════════════════╗
║  Simple End-to-End Demo               ║
╚════════════════════════════════════════╝

📋 Step 1: Registering Runner
─────────────────────────────────────────
✅ Runner registered successfully

📋 Step 2: Running a Simple Job (Blocking)
─────────────────────────────────────────
✅ Job completed!
   Result: {"message":"Hello from the runner!","number":42}

📋 Step 3: Running a Calculation Job
─────────────────────────────────────────
✅ Calculation completed!
   Result: {"sum":55,"product":3628800,"count":10}

📋 Step 4: Starting a Non-Blocking Job
─────────────────────────────────────────
✅ Job started!
   Job ID: abc-123 (running in background)

🎉 Demo completed successfully!
```

## Next Steps

1. **Try different Rhai scripts** - Modify the payload in examples
2. **Add more runners** - Start multiple runners with different IDs
3. **Explore the API** - Use the OpenRPC client library
4. **Build your own client** - See `clients/openrpc/` for examples

## Useful Commands

```bash
# Check Redis
redis-cli ping

# List Redis keys
redis-cli keys "hero:*"

# Monitor Redis commands
redis-cli monitor

# Check supervisor is running
curl http://localhost:3030

# View runner logs
# (check terminal where runner is running)
```

## Clean Up

```bash
# Stop all processes (Ctrl+C in each terminal)

# Clean up test database
rm /tmp/test_runner.db

# (Optional) Flush Redis
redis-cli FLUSHALL
```

---

**Status:** ✅ Ready to Use
**Last Updated:** 2025-10-24