Hero Horus

Hierarchical job orchestration system with three layers: Coordinator, Supervisor, and Runner.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      COORDINATOR                            │
│  Workflow orchestration, DAG execution, step dependencies   │
│  Port: 3302 (HTTP) / 3303 (WebSocket)                       │
└─────────────────────────┬───────────────────────────────────┘
                          │ OpenRPC/HTTP
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                      SUPERVISOR                             │
│  Job admission, authentication (secp256k1), routing         │
│  Port: 3301                                                 │
└─────────────────────────┬───────────────────────────────────┘
                          │ Redis Queue
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                        RUNNER                               │
│  Job execution (Hero CLI runner)                            │
└─────────────────────────────────────────────────────────────┘

Structure

hero_horus/
├── bin/
│   ├── coordinator/     # Workflow orchestrator (DAG)
│   ├── supervisor/      # Job dispatcher & auth
│   └── runners/hero/    # CLI/script executor
├── lib/
│   ├── models/job/      # Job model & signatures
│   ├── clients/         # Redis & OpenRPC clients
│   ├── runner/          # Runner trait
│   └── osiris/          # Base object storage
├── demo/                # Demo scripts
└── docs/                # Documentation

Quick Start

Prerequisites

• Rust toolchain
• Redis running on localhost:6379

Quick Start (Out of the Box)

# Start Redis first
redis-server

# Run everything with one command
make example

This starts Supervisor (port 3301), Runner, and Coordinator (port 3302), then runs a demo job.

Manual Start (Separate Terminals)

make run-supervisor    # Terminal 1 - port 3301
make run-runner        # Terminal 2
make run-coordinator   # Terminal 3 - port 3302
make demo              # Terminal 4

Examples

Simple Job (Supervisor → Runner)

curl -X POST http://127.0.0.1:3301 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hero-secret" \
  -d '{
    "jsonrpc": "2.0",
    "method": "job.run",
    "params": [{
      "id": 0,
      "caller_id": "demo-user",
      "context_id": "demo",
      "payload": "echo Hello from Hero Horus!",
      "runner": "hero-1",
      "timeout": 30
    }],
    "id": 1
  }'

Workflow (Coordinator → Supervisor → Runner)

A workflow is a DAG of steps with dependencies:

Step 1: extract     (no deps)      ──┐
Step 2: transform   (needs step 1) ──┼── Executed in order
Step 3: load        (needs step 2) ──┘

The coordinator:

1. Identifies ready steps (no pending dependencies)
2. Dispatches them to the supervisor
3. Waits for completion
4. Dispatches next ready steps
5. Repeats until all steps complete

Components

Coordinator

• Parses workflow definitions (FlowTemplate)
• Manages DAG execution with step dependencies
• Routes jobs to supervisors
• Tracks workflow state in Redis

Supervisor

• Job admission control
• Authentication via secp256k1 signatures
• Maintains runner registry
• Routes jobs to runner queues (Redis)

Runner (Hero)

• Polls Redis queue for jobs
• Executes shell commands/scripts
• Reports results back via Redis

Job Lifecycle

Created → Dispatched → Started → Finished
                           ↓
                        Error

API Methods

Supervisor (port 3301)

Method	Description
job.create	Store job (no dispatch)
job.start	Dispatch to runner
job.run	Create + dispatch + wait
job.status	Get job status
job.result	Get execution result
runner.list	List registered runners

Coordinator (port 3302)

Method	Description
flow.create	Create a workflow
flow.start	Start workflow execution
flow.status	Get workflow status
context.create	Create execution context