Registering job handlers

01How handlers are found

Every job has a name. A worker only claims jobs whose name it has a handler for, so the stock nexusbrain jobs work process never picks up a job called ea-inbox-sweep. Such a job waits until a worker that registered ea-inbox-sweep is running.

You register handlers with worker.register(name, handler) on a MinionWorker, before calling worker.start(). A handler is an async function that receives a job context and returns the job's result.

02Write a worker that registers your handler

1. 1

   Create a worker file in your host repo.

   The object you return is saved as the job's result. A normal thrown error fails the attempt, and the job is retried until it runs out of attempts. UnrecoverableError skips the retries.

   import { MinionWorker, UnrecoverableError } from 'nexusbrain/minions';
   import type { MinionJobContext } from 'nexusbrain/minions';
   import { loadConfig, toEngineConfig } from 'nexusbrain/config';
   import { createEngine } from 'nexusbrain/engine-factory';
   
   const config = loadConfig();
   if (!config) throw new Error('No brain config found. Run nexusbrain init first.');
   const engineConfig = toEngineConfig(config);
   const engine = await createEngine(engineConfig);
   await engine.connect(engineConfig);
   
   const worker = new MinionWorker(engine, { queue: 'default', concurrency: 2 });
   
   worker.register('ea-inbox-sweep', async (job: MinionJobContext) => {
     const mailbox = job.data.mailbox;
     if (typeof mailbox !== 'string') {
       throw new UnrecoverableError('ea-inbox-sweep: data.mailbox is required');
     }
     await job.log(`sweeping ${mailbox}`);
   
     // Your host-specific work goes here. Stop early if the job is cancelled
     // or times out.
     if (job.signal.aborted) throw new Error('aborted');
   
     await job.updateProgress({ step: 'done' });
     return { mailbox, swept: true };
   });
   
   // Register every other host handler here, before start().
   
   await worker.start(); // runs until SIGTERM or SIGINT
   await engine.disconnect();

   Copy

   You should seeThe file type-checks against the nexusbrain package.

2. 2

   Start the worker.

   start() refuses to run with no handlers: "No handlers registered. Call worker.register(name, handler) before start()." It stops cleanly on SIGTERM or SIGINT and gives running jobs time to finish.

   bun run worker.ts

   Copy

   You should seeThe process keeps running and waits for jobs.

03Use the job context

• Worker options you can pass to new MinionWorker(engine, opts) include queue (default default), concurrency (default 1), lockDuration (default 30000 ms), pollInterval (default 5000 ms), maxRssMb (0 turns the memory watchdog off) and healthCheckInterval (default 60000 ms, 0 turns it off).
• A worker only takes jobs from its own queue. Submit to the same queue name the worker uses.

04Test the handler with a real job

To submit from your own code instead of the CLI, create new MinionQueue(engine) and call await queue.add('ea-inbox-sweep', { mailbox: '[email protected]' }, { max_attempts: 3 }).

1. 1

   Submit a job with the handler's name while your worker runs.

   Do not add --follow. It runs the job inside the CLI, which only knows the built-in handlers, and stops with "Unknown job type".

   nexusbrain jobs submit ea-inbox-sweep --params '{"mailbox":"[email protected]"}'

   Copy

   You should seeThe new job printed as JSON with its id.

2. 2

   Check the result.

   nexusbrain jobs get <id>

   Copy

   You should see"Job #<id>: ea-inbox-sweep (COMPLETED)", your log lines in History, and a Result line with the object your handler returned.

3. 3

   Check that bad input is not retried.

   nexusbrain jobs submit ea-inbox-sweep --params '{}'

   Copy

   You should seeAfter the worker picks it up, nexusbrain jobs get <id> shows the job as DEAD with the error "ea-inbox-sweep: data.mailbox is required".

05Finish the Minions migration

The v0.11.0 migration moves scheduled agent tasks onto the queue. It looks for cron manifests named cron/jobs.json or cron.json in ~/.claude and ~/.openclaw, plus any directory you pass with --host-dir. For each entry of kind agentTurn, session or skill, it checks the handler name.

1. 1

   See which handlers need registering.

   cat ~/.nexusbrain/migrations/pending-host-work.jsonl

   Copy

   You should seeOne JSON line per task, with handler, cron_schedule, manifest_path and "status":"pending".

2. 2

   Register each listed handler in your worker and deploy it.

   Use the handler name from the handler field exactly, as in the worker file above.

   You should seeYour worker is running with every listed handler registered.

3. 3

   Point each cron entry for your own handlers at the queue.

   The migration only rewrites built-in names, so change these entries yourself to submit the job, for example nexusbrain jobs submit ea-inbox-sweep --params '{}'. Your worker then runs it.

   You should seeThe scheduler submits a job at each run and nexusbrain jobs list shows it completing.

4. 4

   Run the migrations again.

   The partial v0.11.0 migration resumes. It never adds the same handler and manifest twice, so when nothing new is found it is recorded as complete. Use --dry-run first to see the plan, and --host-dir <path> if your cron manifest lives somewhere else.

   nexusbrain apply-migrations --yes

   Copy

   You should seenexusbrain apply-migrations --list shows v0.11.0 as applied.

06Troubleshooting