Job Module

The Job module (codebolt.job) provides a complete solution for managing jobs in a distributed agent environment. Jobs can represent tasks, issues, features, or any work units that need to be tracked and coordinated.

Core Features

Basic Job Management

• Create, read, update, and delete jobs
• Bulk delete operations
• Job listing with filters
• Job groups for organization

Dependencies

• Add and remove job dependencies
• Track blocking and related jobs
• Get ready and blocked jobs based on dependencies

Labels

• Tag jobs with labels for categorization
• List, add, and remove labels

Advanced Features

Pheromone System

Pheromones provide a stigmergic coordination mechanism for agents:

• Pheromone Types: Define custom pheromone types with display names and colors
• Deposit/Remove: Agents can deposit or remove pheromones on jobs
• Aggregation: Get aggregated pheromone data across depositors
• Decay: Time-based decay support for pheromone intensity
• Search: Find jobs by pheromone type and intensity

Split Proposals

For complex jobs that need to be broken down:

• Propose splitting a job into multiple sub-jobs
• Accept or delete split proposals

Job Locking

Prevent concurrent work on the same job:

• Acquire and release locks
• Check lock status
• Request unlock from lock holder

Job Bidding

Competitive assignment of jobs:

• Agents can bid on jobs with priority and reason
• Accept or withdraw bids
• List all bids on a job

Job Blockers

Track explicit blockers on jobs:

• Add blockers with descriptions
• Link blockers to other jobs
• Resolve or remove blockers

Usage Example

import codebolt from '@codebolt/codeboltjs';

// Create a job group
const groupResult = await codebolt.job.createJobGroup({
  shortName: 'PROJ',
  name: 'My Project'
});

// Create a job in the group
const jobResult = await codebolt.job.createJob(groupResult.group.id, {
  name: 'Implement feature X',
  type: 'feature',
  priority: 3,
  description: 'Detailed description...'
});

// Deposit a pheromone to indicate interest
await codebolt.job.depositPheromone(jobResult.job.id, {
  type: 'interested',
  intensity: 0.8,
  depositedBy: 'agent-123'
});

// Lock the job before working
await codebolt.job.lockJob(jobResult.job.id, 'agent-123', 'My Agent');

// When done, unlock
await codebolt.job.unlockJob(jobResult.job.id, 'agent-123');

Available Methods

CRUD Operations

Method	Description
createJob(groupId, data)	Create a new job
getJob(jobId)	Get job details
updateJob(jobId, data)	Update a job
deleteJob(jobId)	Delete a job
deleteJobs(jobIds)	Bulk delete jobs
listJobs(filters)	List jobs with optional filters
createJobGroup(data)	Create a job group

Dependencies

Method	Description
addDependency(jobId, targetId, type)	Add a dependency
removeDependency(jobId, targetId)	Remove a dependency
getReadyJobs(filters)	Get jobs ready to start
getBlockedJobs(filters)	Get blocked jobs

Labels

Method	Description
addLabel(label)	Add a label
removeLabel(label)	Remove a label
listLabels()	List all labels

Pheromones

Method	Description
getPheromoneTypes()	List pheromone types
addPheromoneType(data)	Add a pheromone type
removePheromoneType(name)	Remove a pheromone type
depositPheromone(jobId, deposit)	Deposit pheromone
removePheromone(jobId, type, depositedBy)	Remove pheromone
getPheromones(jobId)	List pheromones on a job
getPheromonesAggregated(jobId)	Get aggregated pheromones
listJobsByPheromone(type, minIntensity)	Search by pheromone
getPheromonesWithDecay(jobId)	Get with decay applied
getPheromonesAggregatedWithDecay(jobId)	Aggregated with decay

Split Proposals

Method	Description
addSplitProposal(jobId, proposal)	Propose split
deleteSplitProposal(jobId, proposalId)	Delete proposal
acceptSplitProposal(jobId, proposalId)	Accept proposal

Locking

Method	Description
lockJob(jobId, agentId, agentName)	Acquire lock
unlockJob(jobId, agentId)	Release lock
isJobLocked(jobId)	Check lock status

Unlock Requests

Method	Description
addUnlockRequest(jobId, request)	Request unlock
approveUnlockRequest(jobId, requestId, respondedBy)	Approve request
rejectUnlockRequest(jobId, requestId, respondedBy)	Reject request
deleteUnlockRequest(jobId, requestId)	Delete request

Bidding

Method	Description
addBid(jobId, bid)	Add a bid
withdrawBid(jobId, bidId)	Withdraw a bid
acceptBid(jobId, bidId)	Accept a bid
listBids(jobId)	List all bids

Blockers

Method	Description
addBlocker(jobId, blocker)	Add a blocker
removeBlocker(jobId, blockerId)	Remove a blocker
resolveBlocker(jobId, blockerId, resolvedBy)	Resolve a blocker