@msm-core/planner

The verify-and-adapt planner for durable agents. Pursue a goal the way a capable agent does — and never run away doing it.

goal ─▶ decompose (LLM, ≤ maxSteps) ─▶ run step (durable, @msm-core/jobs) ─▶ VERIFY
          │                                                                     │
          │  pass: next step                                              fail  │
          └──────────────────────────────────────────────────────────────────┤
                                                                               ▼
                                              decideRecovery (side-effect-aware)
                                               ├─ ceiling hit ─────────▶ escalate (human)
                                               ├─ step already ACTED ──▶ escalate (human)
                                               └─ read-only failure ───▶ brain revises the
                                                    REMAINING work (completed steps kept),
                                                    or asks a human as a last resort

Generic and brain-agnostic. The application layer parses its own manifest and wires the runtime; this package owns the behaviour.

Pieces

• decomposePlan(goal, judge, opts) — goal → bounded PlanStep[] (falls back to one step).
• makeVerifyPort(config, { judge, onFail }) — a @msm-core/jobs VerifyPort: deterministic checks (minLength/mustContain/mustNotContain) + opt-in LLM-judged criteria (via @msm-core/validate).
• decideRecovery(input) — after a verified step fails: retry a read-only failure with a revised plan for the remaining work, or escalate a side-effecting failure / a stuck brain / a hit ceiling to a human. shouldReplan is the hard, finite ceiling.
• createPlanRegistry(base) — runs an agent.plan job whose steps come from state.plan.

Three guarantees

1. Bounded — shouldReplan(count, max) is a finite ceiling; the replan chain can't loop.
2. Last-resort escalation — the brain tries a different approach before asking a human.
3. Side-effect aware — verification runs after the step acted, so a failed step that already sent/wrote/paid escalates (a human decides) instead of blindly re-acting; a retry resumes from the failed step and never re-runs completed work.

Built on @msm-core/jobs (durable execution + the VerifyPort seam) and @msm-core/validate (the LLM-as-judge cascade).