# mort → majordomo migration blueprint

The plan for converting mort off `go-llm`/`go-agentkit` and onto majordomo,
executed as the final phase of the build run. Inventory source: a full
sweep of mort's 160 importing files (2026-06-10).

**Mandate (Steve, mid-run):** this is not a 1:1 port. mort's agent / LLM /
tool code may be rewritten wholesale into a properly designed, extensible
system — the constraint is user-facing behavior: `.query` still does quick
research, `.research` / `.deepresearch` keep their roles, chatbot and
general agents keep broadly the same functionality.

## Layering: what moves, what stays

```
mort features (.query, chatbot, cookbook, scaddy, ...)        — stay, re-wired
mort orchestration (lanes, run-critic, budgets, delivery,
  encryption, compaction policy, tracing/usage recording)     — stay, re-based
go-llm + go-agentkit                                          — DELETED
majordomo (Parse/tiers/chains/health, providers, media,
  tools, agents, skills)                                      — the new floor
```

mort-side systems survive because majordomo's seams are public: providers
and models are small interfaces (lane wrapping = an `llm.Provider`
decorator; the foreman 30-minute timeout = a `Model` decorator), the agent
loop exposes observers, and the registry accepts any provider.

## Core mappings

| mort today (go-llm / agentkit) | majordomo |
|---|---|
| `llm.Parse(spec)` / `llms.ParseModelRequest` | `Registry.Parse` (same grammar; chains, aliases, `LLM_*` lazily) |
| tier convars + `llm.RegisterResolver` | `RegisterResolver` (library addition №1) backed by the same convar reads |
| legacy aliases (`sonnet`, `haiku`, ...) | `RegisterAlias` table, unchanged strings |
| comma failover chains + bench-on-failure | chain executor + health tracker (ADR-0006/0008) |
| `llm.SetFailoverDefaults/Observer`, `failoverlog` | `WithHealthConfig`/`WithChainConfig` + `ChainConfig.Observer` (addition №7) feeding the same `llm_failover_events` store |
| `.failover bench/unbench/list` | `health.Tracker` `Bench`/`Unbench`/`Snapshot` (addition №6) |
| `llm.Client` + provider constructors + `OPENAI_KEY` etc. | built-ins + env keys; mort's nonstandard `OPENAI_KEY`/`GOOGLE_GEMINI_API_KEY` bridged via `WithAPIKey` at wiring |
| deepseek/moonshot/xai/groq clients | `openai.New(WithName(...), WithBaseURL(...))` compat presets registered at boot |
| `LLM_M1=foreman://...` env DSN | identical (ADR-0004 parity); foreman timeout via a Model-wrapping decorator |
| `llm.Define[Args]` / `DefineSimple` (60+ sites) | `DefineTool[Args]` (addition №2, schema via `SchemaFor`) |
| `llm.NewToolBox` / `ToolBox.Execute/AllTools` | `llm.NewToolbox` / `Execute` / `Tools` |
| `llm.Message/UserMessage/SystemMessage/UserMessageWithImages` | `Message` constructors + `UserParts(Text, Image...)` |
| `llm.Image{Base64/URL}` | `ImagePart` (bytes; URL images fetched by mort's imageutil at the edge — it already downloads Discord attachments) |
| `model.Complete(ctx, req)` | `Model.Generate` |
| `llms.GenerateWith[T]` (hidden tool trick) | `majordomo.Generate[T]` (native structured output; `flexBool`-style tolerance stays mort-side in the few schemas that need it) |
| `llm.WithPromptCaching/WithMaxTokens/WithTemperature` | request options; prompt caching = addition №4 (Anthropic cache_control) |
| reasoning `:high` suffixes in specs | stripped by mort's spec layer → `WithReasoningEffort` (ADR-0003) |
| usage detail keys (cached/reasoning tokens) | `Usage` detail fields (addition №3) |
| `agentkit.Agent{...}.Run` | `agent.New(...).Run` |
| `Observer/FuncObserver/MultiObserver` | `WithStepObserver` / `OnStep` (multiple registrations compose) |
| `MaxIter` / `MaxIterFunc` (critic adjust_budget) | `WithMaxSteps` / `WithMaxStepsFunc` (addition №5a) |
| `Steer` mailbox (critic nudges) | `WithSteer` per-step message injection (addition №5b) |
| `ContextCompactor` | `WithCompactor` pre-step hook (addition №5c); mort keeps its summarize-the-middle policy |
| `MaxConsecutiveToolErrors` / `MaxSameToolCallRepeats` | loop guards (addition №5d) |
| `ErrMaxIterExhausted` | `agent.ErrMaxSteps` |
| `SessionTools{Tools,PostRun,Cleanup}` / `AttachImages` | mort-side session-tool layer over `AddToolbox` + run history; artifacts/delivery were always mort code |
| `AgentDefinition`/`PhaseDefinition`/`RunPipeline` | mort-side phase runner: sequential `agent.Run` calls with per-phase model/tools/system + template vars (mort's executor owns this today anyway) |
| skill manifests (`skills/*/skill.yml`) | unchanged YAML → `skill.New(name, WithInstructions(sys), WithToolbox(...))` + mort's executor bounds |
| `llm.Transcription` types | move into `pkg/logic/transcribe` (out of majordomo's scope) |
| lane wrapping of `provider.Provider` | `laneProvider` implementing `llm.Provider`, registered via `RegisterProvider` — no fork needed (this was inventory pain point №6) |

## Library additions planned during conversion

Each is additive, general-purpose, and lands in majordomo main with tests
and an ADR before mort consumes it:

1. `Registry.RegisterResolver(Resolver)` — dynamic alias resolution
   (DB-backed tiers); checked after static aliases during expansion, output
   re-expanded recursively with the same cycle guard.
2. `DefineTool[Args](name, desc, fn)` — typed tools: schema from
   `SchemaFor[Args]`, arguments unmarshaled before the handler runs.
3. `Usage{CacheReadTokens, CacheWriteTokens, ReasoningTokens}` populated by
   the providers that report them (Anthropic, OpenAI, Google).
4. `WithPromptCaching()` → Anthropic `cache_control` (system + last turn);
   no-op elsewhere.
5. Agent loop hooks: (a) `WithMaxStepsFunc`, (b) `WithSteer`,
   (c) `WithCompactor`, (d) `WithToolErrorLimits`.
6. `health.Tracker.Bench(key, until)` / `Unbench(key)` / `Snapshot()` for
   the `.failover` admin surface and web UI.
7. `ChainConfig.Observer` — one callback per failover decision (attempt,
   classification, bench) feeding mort's event log.

## Conversion order (Phase 9 execution plan)

1. **Library additions** above (majordomo main, gated, committed).
2. **`pkg/logic/llms` rebuild** — the choke point. One mort package that
   owns: a `majordomo.Registry` with mort's env keys, compat providers,
   lane-wrapped registration, the convar-backed tier resolver, legacy
   aliases, the foreman timeout decorator, health observer wiring, and the
   `ParseModelRequest/ParseModelForContext/GenerateWith/CallAndExecute/
   SimpleCall` mort-facing API (now thin wrappers over majordomo). The
   reasoning-suffix dialect is stripped here.
3. **Tool layer** — `pkg/skilltools` registry keeps its gating/audit
   design; `gated_tool.go` re-bases `NewGatedTool[Args]` on
   `DefineTool[Args]`; ~96 tools recompile against `llm.Tool`.
4. **Executors** — `skillexec` + `agentexec` re-based on `agent.Agent`
   (loop guards, compactor, steer, observers from the additions). The
   no-tools direct path falls out naturally (empty toolset sends no tools
   array). Phased agents = mort-side sequential runner.
5. **Call sites** — chatbot, cookbook, recipe, summary, standingquery,
   tasks, fitness, drawbot, lottery, reminder, epon, scaddy, clipper,
   transcribe: mechanical re-pointing to the new `llms` wrappers and
   canonical types.
6. **Delete** go-llm + go-agentkit from go.mod; repo-wide grep must be
   clean; `go build ./...` + tests green.
7. Branch, push, PR (never touching mort's `main`).

## Behavioral deltas to verify after conversion

- Default chain knobs differ (go-llm: 3 retries/5m flat cooldown/jitter;
  majordomo: 1 retry/threshold 2/5s→5m exponential). mort's convars
  (`llms.failover.max_retries`, `llms.failover.cooldown_seconds`) map onto
  `ChainConfig.TransientRetries` + `health.Config` so operators keep their
  dials; semantics ADR-0006 apply.
- go-llm benched-everything chains ignore cooldowns; majordomo returns the
  joined exhaustion error. mort's executor already retries failed runs.
- `ErrRequestSpecific` (400/413/422) failed over WITHOUT benching in
  go-llm; majordomo fails fast by default — mort sets
  `AdvanceOnPermanent: true` to preserve availability behavior.
- Image URLs: go-llm providers fetched `llm.Image{URL}`; majordomo is
  bytes-only — `imageutil.FromTextURLs` now downloads (it already has the
  HTTP plumbing and the 50MB cap).