# Hero Supervisor Job API Convention

## Overview

The Hero Supervisor OpenRPC API follows a consistent naming convention for job-related operations:

- **`jobs.`** - General job operations (plural)
- **`job.`** - Specific job operations (singular)

This convention provides a clear distinction between operations that work with multiple jobs or create new jobs versus operations that work with a specific existing job.

## API Methods

### General Job Operations (`jobs.`)

#### `jobs.create`
Creates a new job without immediately queuing it to a runner.

**Parameters:**
- `secret` (string): Authentication secret (admin or user)
- `job` (Job object): Complete job specification

**Returns:**
- `job_id` (string): Unique identifier of the created job

**Usage:**
```json
{
  "method": "jobs.create",
  "params": {
    "secret": "your-secret",
    "job": {
      "id": "job-123",
      "caller_id": "client-1",
      "context_id": "context-1",
      "payload": "print('Hello World')",
      "executor": "osis",
      "runner": "osis-runner-1",
      "timeout": 300,
      "env_vars": {},
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    }
  }
}
```

#### `jobs.list`
Lists all jobs in the system with full details.

**Parameters:** None

**Returns:**
- `jobs` (array of Job objects): List of all jobs with complete information

**Usage:**
```json
{
  "method": "jobs.list",
  "params": []
}
```

**Response:**
```json
[
  {
    "id": "job-123",
    "caller_id": "client-1",
    "context_id": "context-1",
    "payload": "print('Hello World')",
    "executor": "osis",
    "runner": "osis-runner-1",
    "timeout": 300,
    "env_vars": {},
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
]
```

### Specific Job Operations (`job.`)

#### `job.run`
Runs a job immediately on the appropriate runner and returns the result.

**Parameters:**
- `secret` (string): Authentication secret (admin or user)
- `job` (Job object): Complete job specification

**Returns:**
- `result` (JobResult): Either success or error result

**JobResult Format:**
```json
// Success case
{
  "success": "Job completed successfully with output..."
}

// Error case
{
  "error": "Job failed with error message..."
}
```

**Usage:**
```json
{
  "method": "job.run",
  "params": {
    "secret": "your-secret",
    "job": { /* job object */ }
  }
}
```

#### `job.start`
Starts a previously created job by queuing it to its assigned runner.

**Parameters:**
- `secret` (string): Authentication secret (admin or user)
- `job_id` (string): ID of the job to start

**Returns:** `null` (void)

**Usage:**
```json
{
  "method": "job.start",
  "params": {
    "secret": "your-secret",
    "job_id": "job-123"
  }
}
```

#### `job.status`
Gets the current status of a job.

**Parameters:**
- `job_id` (string): ID of the job to check

**Returns:**
- `status` (JobStatusResponse): Current job status information

**JobStatusResponse Format:**
```json
{
  "job_id": "job-123",
  "status": "running",
  "created_at": "2023-01-01T00:00:00Z",
  "started_at": "2023-01-01T00:00:05Z",
  "completed_at": null
}
```

**Status Values:**
- `created` - Job has been created but not queued
- `queued` - Job has been queued to a runner
- `running` - Job is currently executing
- `completed` - Job finished successfully
- `failed` - Job failed with an error
- `timeout` - Job timed out

**Usage:**
```json
{
  "method": "job.status",
  "params": ["job-123"]
}
```

#### `job.result`
Gets the result of a completed job. This method blocks until the result is available.

**Parameters:**
- `job_id` (string): ID of the job to get results for

**Returns:**
- `result` (JobResult): Either success or error result

**Usage:**
```json
{
  "method": "job.result",
  "params": ["job-123"]
}
```

#### `job.stop`
Stops a running job.

**Parameters:**
- `secret` (string): Authentication secret (admin or user)
- `job_id` (string): ID of the job to stop

**Returns:** `null` (void)

**Usage:**
```json
{
  "method": "job.stop",
  "params": {
    "secret": "your-secret",
    "job_id": "job-123"
  }
}
```

#### `job.delete`
Deletes a job from the system.

**Parameters:**
- `secret` (string): Authentication secret (admin or user)
- `job_id` (string): ID of the job to delete

**Returns:** `null` (void)

**Usage:**
```json
{
  "method": "job.delete",
  "params": {
    "secret": "your-secret",
    "job_id": "job-123"
  }
}
```

## Workflow Examples

### Fire-and-Forget Job
```javascript
// Create and immediately run a job
const result = await client.job_run(secret, jobSpec);
if (result.success) {
  console.log("Job completed:", result.success);
} else {
  console.error("Job failed:", result.error);
}
```

### Asynchronous Job Processing
```javascript
// 1. Create the job
const jobId = await client.jobs_create(secret, jobSpec);

// 2. Start the job
await client.job_start(secret, jobId);

// 3. Poll for completion (non-blocking)
let status;
do {
  status = await client.job_status(jobId);
  if (status.status === 'running') {
    await sleep(1000); // Wait 1 second
  }
} while (status.status === 'running' || status.status === 'queued');

// 4. Get the result
const result = await client.job_result(jobId);
```

### Batch Job Management
```javascript
// Create multiple jobs
const jobIds = [];
for (const jobSpec of jobSpecs) {
  const jobId = await client.jobs_create(secret, jobSpec);
  jobIds.push(jobId);
}

// Start all jobs
for (const jobId of jobIds) {
  await client.job_start(secret, jobId);
}

// Monitor progress
const results = [];
for (const jobId of jobIds) {
  const result = await client.job_result(jobId); // Blocks until complete
  results.push(result);
}

// Optional: Stop or delete jobs if needed
for (const jobId of jobIds) {
  await client.job_stop(secret, jobId);   // Stop running job
  await client.job_delete(secret, jobId); // Delete from system
}
```

## Authentication

All job operations require authentication using one of the following secret types:

- **Admin secrets**: Full access to all operations
- **User secrets**: Access to job operations (`jobs.create`, `job.run`, `job.start`)
- **Register secrets**: Only access to runner registration

## Error Handling

All methods return standard JSON-RPC error responses for:

- **Authentication errors** (-32602): Invalid or missing secrets
- **Job not found errors** (-32000): Job ID doesn't exist
- **Internal errors** (-32603): Server-side processing errors

## Migration from Legacy API

### Old → New Method Names

| Legacy Method | New Method | Notes |
|---------------|------------|-------|
| `run_job` | `job.run` | Same functionality, new naming |
| `list_jobs` | `jobs.list` | Same functionality, new naming |
| `create_job` | `jobs.create` | Enhanced to not auto-queue |

### New Methods Added

- `job.start` - Start a created job
- `job.stop` - Stop a running job
- `job.delete` - Delete a job from the system
- `job.status` - Get job status (non-blocking)
- `job.result` - Get job result (blocking)

### API Changes

- **Job struct**: Replaced `job_type` field with `executor`
- **jobs.list**: Now returns full Job objects instead of just job IDs
- **Enhanced job lifecycle**: Added stop and delete operations

This provides much more granular control over job lifecycle management.