PUBLIC MODULE · lib/jobs.js
Agent.Jobs
Portable, folder-only project Jobs. ai-jobs enables, ai-jobs-disabled disables. Operations are best effort: there are no locks, daemon identity records, or cross-process coordination. Concurrent scans/mutations may duplicate work, lose updates, or race archives. Atomic single-file replacement remains used.
PUBLIC MODULE (owner of lib/jobs/). The façade publishes the operations a host or tool needs; task parsing, occurrence state, attempts, and archives stay private to lib/jobs/.
class Jobs class
Frozen static namespace for the folder-only Jobs operations exported by this module. Instances have no API; use the static methods/properties instead.
...argsnever- No constructor arguments are accepted.
Returns Jobs — A Jobs namespace instance (normally unused; use static members).
Defined in lib/jobs.js
class JobsError extends Error class
Error type used for actionable Jobs failures.
Defined in lib/jobs/errors-base.js
constructor(code, message, details = {…}) constructor
Create a coded jobs-domain error.
codestring- Stable error code identifying the failure.
messagestring- Human-readable error message passed to `Error`.
[details={}]object- Optional contextual data, such as a task filename or underlying cause.
Returns JobsError — The initialized error instance.
Throws — Any exception raised while the native `Error` constructor converts the supplied message.
Effects — Initializes the native error state and sets `name`, `code`, and `details` on the instance.
async foregroundJobsDaemon(projectRoot, options = {…}) function
Run a foreground best-effort daemon bound to the project root.
projectRootstring- Project root directory.
[options={}]object- Daemon options; supports `signal`, `state`, `execution`, `scan`, and `delay`.
Returns Promise<void> — Resolves when stopped or Jobs becomes unusable; rejects on initial validation or daemon errors.
Throws — {JobsError} If the project is not operational when starting.
Defined in lib/jobs/daemon.js
async disableJobs(projectRoot, options = {…}) function
Initialize or restore folder-only Jobs.
projectRootstring- Project root directory.
[settings={}]object- Settings argument retained by the lifecycle API.
[options={}]object- Options; `fs` may inject filesystem operations.
Returns Promise<{enabled: boolean}> — Enabled status.
Throws — {JobsError} If layout is invalid or active and disabled roots collide.
Defined in lib/jobs/lifecycle.js
async initializeJobs(projectRoot, settings = {…}, options = {…}) function
Initialize or restore folder-only Jobs.
projectRootstring- Project root directory.
[settings={}]object- Settings argument retained by the lifecycle API.
[options={}]object- Options; `fs` may inject filesystem operations.
Returns Promise<{enabled: boolean}> — Enabled status.
Throws — {JobsError} If layout is invalid or active and disabled roots collide.
Defined in lib/jobs/lifecycle.js
async dispatchJobs(projectRoot, options = {…}) function
Dispatch one best-effort serial scan of due Jobs.
projectRootstring- Project root directory.
[options={}]object- Scan options, including injected clock, filesystem, validation, executor, and execution settings.
Returns Promise<object> — Frozen scan result containing outcomes, errors, warnings, and optional error-log path.
Throws — {JobsError} For invalid clock values; scan and persistence failures are generally returned as errors.
Defined in lib/jobs/dispatcher.js
async scheduleJobs(root, command, options = {…}) function
Apply a task list/read/create/update/remove command.
rootstring- Project root directory.
commandobject- Command with action; non-list actions require a filename, and create/update require Markdown `source`.
[options={}]object- Options including `readOnly`, folder validation context, and settings.
Returns Promise<object> — Task listing, task source/read result, or mutation result.
Throws — {JobsError} For invalid commands, read-only mutation, ineligible Jobs, or invalid task metadata; filesystem errors may also reject.
Defined in lib/jobs/operations.js
async jobsStatus(projectRoot, options = {…}) function
Read a non-mutating projection of Jobs eligibility, tasks, schedule, attempts, and last scan.
projectRootstring- Project root directory.
[options={}]object- Options such as clock, defaults, and validation context.
Returns Promise<object> — Status projection with diagnostics; does not create folders or start a daemon.
Defined in lib/jobs/status.js
async validateJobsOperational(root, options = {…}) function
Apply a task list/read/create/update/remove command.
rootstring- Project root directory.
commandobject- Command with action; non-list actions require a filename, and create/update require Markdown `source`.
[options={}]object- Options including `readOnly`, folder validation context, and settings.
Returns Promise<object> — Task listing, task source/read result, or mutation result.
Throws — {JobsError} For invalid commands, read-only mutation, ineligible Jobs, or invalid task metadata; filesystem errors may also reject.
Defined in lib/jobs/operations.js