minion-orchestrator

Files (1)

• SKILL.md

SKILL.md (first lines)

# Minion Orchestrator

## Contract

Minions is a Postgres-native job queue for durable, observable background work.
This single skill handles two lanes:
- Deterministic shell jobs (`gbrain jobs submit shell ...`)
- LLM subagent jobs (`gbrain agent run ...`)

When to route to Minions: durable, observable work that must survive restarts,
fan out across many parallel tasks, or persist across sessions. Routing policy
is defined in `skills/conventions/subagent-routing.md` — the project default is
`pain_triggered` (native subagents first, Minions after specific pain signals
fire); Mode A (all-through-Minions) is opt-in.

Guarantees:
- Jobs survive gateway restart (Postgres-backed)
- Every job has structured progress, token accounting, and session transcripts
- Running agents can be steered mid-flight via inbox messages
- Jobs can be paused, resumed, or cancelled at any time
- Parent-child DAGs with configurable failure policies

## Route the Request: Shell Job vs Subagent

| Condition | Action |
|---|---|
| User asks for deterministic command/script run | Shell job (CLI: `gbrain jobs submit shell ...`) |
| User asks to "run in minions" + explicit command/argv | Shell job (CLI, `--params` with `cmd` or `argv`) |
| User asks for research/reasoning/iterative agent | Subagent job (CLI: `gbrain agent run`) |
| User asks to steer/pause/resume an agent | Subagent job lifecycle tools (MCP-callable) |
| Single simple operation under ~30s | Consider inline execution first |
| Needs restart durability/observability | Submit as Minion job |
| Parallel work (2+ streams) | `gbrain agent run --fanout-manifest` or parent + child subagents |

If intent is ambiguous, ask one clarification:
"Do you want a deterministic shell command job, or an LLM agent job?"

## Shell Jobs (Deterministic Scripts)

Use for reproducible command execution, ETL steps, cron work, and scriptable
tasks where no LLM reasoning loop is needed.

### Preconditions (read before submitting your first shell job)

- **`GBRAIN_ALLOW_SHELL_JOBS=1` must be set on the worker environment.**
  Without it, the shell handler refuses to register and submissions sit in
  `waiting` silently. Gate lives in `src/core/minions/handlers/shell.ts`.
- **Security:** flipping `GBRAIN_ALLOW_SHELL_JOBS=1` authorizes arbitrary
  command execution on the worker. On a shared queue, this is a remote code
  execution surface. Treat as privileged infrastructure authorization.
- **Execution mode — pick one:**
  - **Postgres + daemon:** `gbrain jobs work` runs a persistent worker that
    claims and executes jobs from the queue.
  - **PGLite + --follow:** `gbrain jobs submit ... --follow` runs inline.
    The daemon mode is not available on PGLite (exclusive file lock). See
    `docs/guides/minions-shell-jobs.md`.
- **MCP boundary:** shell-job submission is CLI-only. `submit_job name="shell"`
  over MCP throws an `OperationError` with code `permission_denied` ("'shell'
  jobs cannot be submitted over MCP") because `shell` is in `PROTECTED_JOB_NAMES`.
  Agents CAN observe shell jobs via `get_job` / `list_jobs` / `get_job_progress`
  (not protected), but cannot submit them. Operator or autopilot submits;
  agent observes.
- **Verify setup:** after configuration, run `gbrain jobs stats` (CLI) to
  confirm the worker is registered and consuming the queue.

### Submit (CLI, operator or autopilot)

Shell jobs take their command via `--params` as a JSON object with `cmd` (string)
or `argv` (array), plus `cwd` and optional `env`.

Command string form:
```
gbrain jobs submit shell --params '{"cmd":"echo hello","cwd":"/abs/path"}'
```

Argv form (no shell expansion):
```
gbrain jobs submit shell --params '{"argv":["bash","-lc","echo hello"],"cwd":"/abs/path"}'
```

Inline execution on PGLite or any one-shot deployment:
```
gbrain jobs submit shell --params '{"cmd":"echo hello","cwd":"/tmp"}' --follow
```

Queue/lifecycle flags exposed by `gbrain jobs submit --help`: `--queue`,
`--priority`, `--delay`, `--max-attempts`, `--max-stalled`, `--backoff-type`,
`--backoff-delay`, `--backoff-jitter`, `--timeout-ms`, `--idempotency-key`,
`--dry-run`.

### Monitor (agents or operator)

These operations are MCP-callable and safe for agent use:

```
list_jobs --name shell --status active
get_job ID
get_job_progress ID
```

Check structured result fields (exit code, stdout/stderr tails, attempts,
timings) from `get_job`. Use `gbrain jobs stats` (CLI) for worker/queue
health dashboard.

### Control (MCP-callable)

```
cancel_job id=ID
replay_job id=ID
```

`replay_job` is not protected — only shell *submission* is. Agents can
cancel or replay a shell job without CLI access.

Use idempotency keys for recurring shell workloads to avoid duplicate runs.

## Subagent Jobs (LLM Orchestration)

Use for open-ended reasoning, tool-using research, and fan-out synthesis.

From weareturnone/gbrain, MIT.