supervisor/docs/job-api-convention.md

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:

{
  "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:

{
  "method": "jobs.list",
  "params": []
}

Response:

[
  {
    "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:

// Success case
{
  "success": "Job completed successfully with output..."
}

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

Usage:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "method": "job.delete",
  "params": {
    "secret": "your-secret",
    "job_id": "job-123"
  }
}

Workflow Examples

Fire-and-Forget Job

// 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

// 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

// 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.