add hero runner and clean improve runner lib

2025-11-14 02:18:48 +01:00
parent d2ff7835e2
commit 75e62f4730
9 changed files with 694 additions and 148 deletions
--- a/bin/runners/hero/README.md
+++ b/bin/runners/hero/README.md
@@ -0,0 +1,168 @@
+# Hero Runner
+
+A specialized runner for the Hero ecosystem that executes heroscripts using the `hero` CLI tool.
+
+## Overview
+
+The Hero runner executes heroscripts by calling `hero run -h <payload>` for each job. This makes it ideal for:
+
+- Running heroscripts from job payloads
+- Executing Hero automation tasks
+- Integrating with the Hero CLI ecosystem
+- Running scripted workflows
+
+## Features
+
+- **Heroscript Execution**: Executes `hero run -h <payload>` for each job
+- **Environment Variables**: Passes job environment variables to the hero command
+- **Timeout Support**: Respects job timeout settings
+- **Signature Verification**: Verifies job signatures before execution
+- **Simple Integration**: No complex payload parsing - just pass the heroscript content
+
+## Usage
+
+### Starting the Runner
+
+```bash
+# Basic usage
+herorunner my-hero-runner
+
+# With custom Redis URL
+herorunner my-hero-runner --redis-url redis://localhost:6379
+```
+
+### Command-line Options
+
+- `runner_id`: Runner identifier (required, positional)
+- `-r, --redis-url`: Redis URL (default: `redis://localhost:6379`)
+
+## Job Payload Format
+
+The job payload should contain the heroscript content that will be passed to `hero run -h`.
+
+### Example Payload
+
+```
+print("Hello from heroscript!")
+```
+
+The runner will execute: `hero run -h 'print("Hello from heroscript!")'`
+
+## Examples
+
+### Example 1: Simple Heroscript
+
+Job payload:
+```
+print("Processing job...")
+```
+
+Executed as: `hero run -h 'print("Processing job...")'`
+
+### Example 2: Multi-line Heroscript
+
+Job payload:
+```
+print("Starting task...")
+// Your heroscript logic here
+print("Task completed!")
+```
+
+### Example 3: With Environment Variables
+
+Job with env_vars:
+```json
+{
+  "payload": "print(env.MY_VAR)",
+  "env_vars": {
+    "MY_VAR": "Hello from Hero Runner"
+  }
+}
+```
+
+## Architecture
+
+The Hero runner implements the `Runner` trait from `hero-runner` library:
+
+```
+┌─────────────────────┐
+│  HeroExecutor      │
+│                     │
+│  - execute_command()│
+│  - process_job()    │
+└─────────────────────┘
+          │
+          │ implements
+          ▼
+┌─────────────────────┐
+│   Runner Trait      │
+│                     │
+│  - spawn()          │
+│  - process_job()    │
+│  - runner_type()    │
+└─────────────────────┘
+          │
+          │ executes
+          ▼
+┌─────────────────────┐
+│  hero run -h        │
+│  <heroscript>       │
+└─────────────────────┘
+```
+
+## Security Considerations
+
+1. **Heroscript Execution**: The runner executes heroscripts via the `hero` CLI. Ensure job payloads are from trusted sources.
+2. **Signature Verification**: Always verify job signatures before execution.
+3. **Environment Variables**: Be cautious with sensitive data in environment variables.
+4. **Hero CLI Access**: Ensure the `hero` command is available in the system PATH.
+
+## Error Handling
+
+The runner handles various error scenarios:
+
+- **Hero CLI Not Found**: Returns error if the `hero` command is not available
+- **Timeout**: Kills the process if it exceeds the job timeout
+- **Non-zero Exit**: Returns error if `hero run -h` exits with non-zero status
+- **Heroscript Errors**: Returns error output from the hero CLI
+
+## Logging
+
+The runner logs to stdout/stderr with the following log levels:
+
+- `INFO`: Job start/completion, runner lifecycle
+- `DEBUG`: Command details, parsing information
+- `ERROR`: Execution failures, timeout errors
+
+## Integration with Supervisor
+
+The Vlang runner integrates with the Hero Supervisor:
+
+1. Register the runner with the supervisor
+2. Supervisor queues jobs to the runner's Redis queue
+3. Runner polls the queue and executes commands
+4. Results are stored back in Redis
+
+## Development
+
+### Building
+
+```bash
+cargo build -p runner-hero
+```
+
+### Running Tests
+
+```bash
+cargo test -p runner-hero
+```
+
+### Running Locally
+
+```bash
+cargo run -p runner-hero -- test-runner
+```
+
+## License
+
+MIT OR Apache-2.0