gbrain/docs/guides/plugin-handlers.md

Plugin handlers — registering host-specific Minion handlers

GBrain's Minion worker ships with seven built-in handlers: sync, embed, lint, import, extract, backlinks, autopilot-cycle. These cover every background operation the gbrain CLI itself performs.

Host platforms (OpenClaw deployments, future hosts) register their own handlers via a plugin bootstrap that imports gbrain/minions. No handlers.json-style data file — handlers are code, loaded by the worker, with the same trust model as any other code in the host's repo.

Why code, not data

An earlier design draft shipped ~/.claude/gbrain-handlers.json where each entry was a shell command the worker would exec on job claim. Codex flagged this as a durable RCE surface: an agent-writable data file that spawns arbitrary shell. We dropped the data-file approach; handlers are code that the host imports explicitly and ships through code review.

The plugin contract

A host worker bootstrap looks like this (TypeScript):

import { MinionQueue, MinionWorker } from 'gbrain/minions';
import type { BrainEngine } from 'gbrain/engine';

async function main() {
  const engine: BrainEngine = /* your engine setup */;
  await engine.connect({});

  const worker = new MinionWorker(engine, { queue: 'default' });

  // Register every host-specific handler the host's cron manifest references.
  // Each handler returns a plain object (serialized as the job result).
  // Throw on failure — the worker catches and retries per max_attempts.

  worker.register('ea-inbox-sweep', async (ctx) => {
    const slot = ctx.data.slot ?? new Date().toISOString();
    // Host-specific agent turn: call your LLM, scan the inbox, write
    // brain pages, return a summary. ctx.signal.aborted indicates the
    // worker wants you to cooperate with shutdown — honor it.
    return { swept: true, slot };
  });

  worker.register('morning-briefing', async (ctx) => {
    /* host logic */
    return { briefed: true };
  });

  // Call start() AFTER every handler is registered. The worker's
  // stall-detector ignores jobs whose name is not in the registered set.
  await worker.start();
}

main().catch(err => { console.error(err); process.exit(1); });

Ship this as a separate binary in the host repo (e.g. your-openclaw-worker) or as a side-effect module that the stock gbrain jobs work command auto-loads on startup (configurable via a host-provided entry point).

Handler contract

Every handler receives a MinionJobContext:

interface MinionJobContext {
  data: Record<string, unknown>;   // job params (whatever the cron submit passed)
  job: MinionJob;                   // full job row (id, queue, attempts, etc.)
  signal: AbortSignal;              // set to aborted when the worker is shutting down
  inbox: MinionInbox;               // read messages sent to this job while it runs
}

Return a serializable object on success. Throw on failure (the worker will log + retry per max_attempts).

Abort cooperation. When ctx.signal.aborted becomes true, finish gracefully. The worker will wait 30s for you to return before SIGKILL. Long-running LLM calls should pass the signal through to whatever network library they use.

Idempotency. The queue enforces unique idempotency_key at the DB layer, so you don't need to worry about double-submits from a cron that fires while the previous invocation is still running.

Gbrain's migration flow

The v0.11.0 migration orchestrator (run by gbrain apply-migrations) detects cron entries whose handler name is NOT in GBrain's builtin set and emits a structured TODO to ~/.gbrain/migrations/pending-host-work.jsonl. Each TODO has shape:

{
  "type": "cron-handler-needs-host-registration",
  "handler": "ea-inbox-sweep",
  "cron_schedule": "0 */30 * * *",
  "manifest_path": "/path/to/cron/jobs.json",
  "current_cmd": "agentTurn ea-inbox-sweep",
  "recommendation": "Add a handler registration for `ea-inbox-sweep` in your host worker bootstrap per docs/guides/plugin-handlers.md. Once registered, re-run `gbrain apply-migrations` to auto-rewrite this entry.",
  "status": "pending"
}

The host agent walks these entries using skills/migrations/v0.11.0.md:

1. Read ~/.gbrain/migrations/pending-host-work.jsonl.
2. For each cron-handler-needs-host-registration row, ship a handler registration in the host's worker bootstrap following the pattern above.
3. Deploy the updated worker.
4. Re-run gbrain apply-migrations --yes. The orchestrator now recognizes the newly-registerable handler (worker writes the registered names to a discovery file on startup) and rewrites the cron entry to use gbrain jobs submit. The JSONL row is marked status: "complete".

Trust boundary

Handler code runs inside the worker process with the same privileges as the rest of the host binary. There is no elevation. But there is also no runtime sandbox — handlers can read + write anywhere the worker user can. Review handler PRs the same way you review any other code that touches production data.

Related

• skills/conventions/cron-via-minions.md — the rewrite convention for cron manifests.
• skills/migrations/v0.11.0.md — how the migration orchestrator drives the host agent through this work.
• skills/minion-orchestrator/SKILL.md — patterns for submitting, monitoring, steering, and replaying jobs once the handler is live.