Missions

A mission is a long-running goal that agents collaborate to achieve. Where the regular agent loop handles one user turn at a time, missions persist across turns, survive process restart, run autonomously in the background, and produce a structured audit trail. The mission engine is ready.

When to use a mission

Reach for the mission engine when a goal:

• has more than 2–3 steps and benefits from explicit planning,
• should keep running while you do other things — “research X, then draft a summary, then save it to my notes”,
• needs a clear pause / resume / cancel surface,
• should leave an inspectable trail of what happened, in what order, at what cost.

For one-shot questions (“what’s the weather”), the regular single-agent loop is still the right tool — missions add orchestration overhead that only pays off when there’s real multi-step work to coordinate.

How it works

Enter mission mode with:

aibutler mode mission

Three roles cooperate over AI Butler’s reliable internal bus:

• Supervisor — owns one mission end-to-end: reads the plan, dispatches each step, waits for the result, persists step state, and moves the mission through its state machine.
• Manager — the optional middle tier. A plan step can carry a list of sub-steps; the supervisor delegates such grouped steps to a manager, which dispatches the sub-steps to the worker pool and reports one aggregated result back up.
• Worker — receives dispatched tasks and runs each one through the full agent loop (model adapter, tool dispatcher, and the mission’s capability set), then reports the result back.

Every dispatch and result travels over the reliable bus with acknowledgement and timeout semantics, so a crashed worker doesn’t silently swallow a step.

Plans can declare step dependencies, and the supervisor dispatches independent steps in parallel (DAG execution). When a step fails, a configured replanner can propose a recovery sequence — an LLM-driven consult that works in both sequential and parallel mode — instead of failing the whole mission. Workers can also run multiple tasks concurrently when the workload is I/O-bound.

Lifecycle

created → planned → running ⇄ waiting_user → completed
                       │
                       ├──→ failed
                       │
                       └──→ cancelled

State transitions are enforced by the engine — invalid moves return an error rather than silently corrupting state. Every transition is persisted as a mission event, so you can replay exactly what happened.

Pause, resume, or cancel at any time with the mission.interrupt tool (action=pause|resume|cancel). A paused mission sits in waiting_user until you pick it back up; state survives a full process restart.

Confirmation-gated capabilities pause missions automatically: when a step needs a capability that requires confirmation, the mission moves to waiting_user and emits a mission.confirmation_required event — resume it with mission.interrupt action=resume once you’ve reviewed the request.

Audit trail

Missions inherit AI Butler’s audit posture: every step records what ran, with which capability grant, for how long, and what it returned. Reviewing a finished mission answers “what did the agent actually do” from the database, not from memory.

There’s also a Missions panel in the web chat sidebar for watching missions from the dashboard; steering (pause/resume/cancel) happens through mission.interrupt in conversation.

Current limits

Honest scoping:

• Sub-steps inside a grouped step run sequentially, and a sub-step can’t carry its own sub-steps — no recursive nesting.

See Scheduling for recurring work that doesn’t need multi-step orchestration, and Swarm for the broader multi-agent picture.