Skip to content
BMO

Adaptive orchestration

Adaptive orchestration is a default-on layer that lets BMO reshape how a session is coordinated without changing the underlying task you asked for. It is about coordination intent: choreography preset, topology, conflict strategy, isolation, coordinator style, edit-tool preference, and the opt-in model gene.

It is separate from Adaptive Context, which changes which context gets injected into a turn. Adaptive orchestration changes the set of coordination settings — preset, topology, isolation, style, edit-tool preference, and model slot hints — that shape how a run is coordinated. BMO calls this combined settings bundle the coordination genome.

Hand-drawn sketch: config baseline, classifier, and monitor overlays merge into an effective coordination genome, then apply at the next root run boundary

flowchart LR config["Config baseline"] --> merge["Merge effective coordination genome"] classifier["Goal classifier"] --> merge overlay["Monitor overlay from previous finalized run"] --> merge merge --> run["Current root run"] run --> trace["Prompt trace + status summary"] run --> monitor["Monitor evaluates finalized run"] monitor --> next["Next-run overlay patch"] classifier:::manual next:::unknown classDef manual stroke-dasharray:6 3 classDef unknown stroke-dasharray:2 2,opacity:0.85

When to use it

Section titled “When to use it”

Use adaptive orchestration when you want BMO to choose better coordination shapes for different kinds of work, for example:

  • staying lightweight for simple edits
  • shifting toward more structured coordination for broader tasks
  • reacting to token pressure or other monitor signals between root runs
  • downgrading from an expensive planning model to the small model slot after a task shifts into mechanical implementation, when the model gene is enabled

Enable and merge order

Section titled “Enable and merge order”

Adaptive orchestration is enabled when the config section or enabled field is omitted. Set enabled = false in bmo.toml or another merged config layer to disable it. See Configuration for the full field reference.

[options.adaptive_orchestration]
enabled = true


[options.adaptive_orchestration.default]
choreography_preset = "modal"
# topology, conflict_strategy, isolation, coordinator_style,
# edit_tool_preference, and model optional


[options.adaptive_orchestration.classifier]
mode = "heuristic" # default; "llm" enables one bounded classifier call per session


[options.adaptive_orchestration.monitor]
# Cumulative run tokens (input+output+cache) before token-pressure reshapes; 0 = off
soft_total_token_budget = 0
# Optional: also evaluate the monitor after every N tool completions in the root run (0 = finalize only)
# monitor_evaluate_every_n_tool_events = 0
# Optional read-only hints (arena friction, eval-shadow aggregates); see monitor topic doc
# hints_arena_enabled = false
# hints_eval_shadow_enabled = false


[options.adaptive_orchestration.model_gene]
# Opt-in: monitor may set model = "small" after planning turns become mechanical.
enabled = false

How it works

Section titled “How it works”
  • The config baseline provides the default coordination genome (the starting set of coordination settings).
  • The optional classifier contributes a bounded patch based on the task.
  • The monitor can reshape the in-memory session overlay after a finalized root run.
  • The optional model gene lets the monitor record a next-run model hint, currently a one-way downgrade to the small model slot after a task-complexity drop.
  • If a reshape changes choreography preset, BMO applies it at the next root run boundary, not in the middle of a live run. Model-gene changes follow the same next-boundary posture.

By default, the monitor evaluates at run finalization. When monitor_evaluate_every_n_tool_events is positive, the same evaluation can run on a background worker every N tool completions in the root run.

sequenceDiagram participant User participant Classifier participant Shaper participant RunCoordinator participant Monitor participant Overlay as NextRunOverlay 
User->>Classifier: session goal
Classifier->>Shaper: bounded genome patch
Shaper->>RunCoordinator: effective coordination genome
RunCoordinator->>RunCoordinator: root run executes
Note over RunCoordinator: live run is never mutated mid-flight
RunCoordinator->>Monitor: finalize run telemetry
Monitor->>Overlay: schedule overlay patch
Overlay-->>RunCoordinator: apply at next root run boundary

Observability

Section titled “Observability”

You can toggle this feature in the TUI via /settings (or /config) → Advanced → Adaptive orchestration. That toggle writes options.adaptive_orchestration.enabled and applies to new runs immediately.

When enabled, the prompt trace includes an adaptive_orchestration segment with metadata such as effective_genome, classification_source (config_baseline, heuristic, llm, llm_fallback_heuristic, llm_fallback_baseline, …), last_reshape_reason, last_reshape_signal_id, whether the reshaped runtime apply is still pending, and whether the model gene has already applied in the session.

You can view this trace in the TUI by opening the Agent Debugger (/debug or ctrl+p → Debugger), selecting a run, and looking at the prompt event metadata.

The main TUI also shows a compact adaptive orchestration summary in the status bar for the current session, so you can see the effective preset, active model gene, latest reshape hint, and whether the next-run apply is still pending without opening the debugger.

When enabled, you can inspect the live state through:

  • bmo config show-adaptive-orchestration for headless effective-config posture and canonical readout surfaces
  • get_adaptive_orchestration or bmo_get_adaptive_orchestration for live session parity JSON
  • GET /v1/sessions/{id}/adaptive-orchestration for HTTP parity
  • Agent Debugger prompt metadata
  • the status bar summary for the current session
  • the parity surfaces documented in Adaptive orchestration parity

All readouts use the same posture vocabulary: disabled, unavailable, enabled-idle, active, pending-apply, applied, degraded, and unknown. Posture evidence is metadata-only and does not expose raw prompts, tool bodies, model responses, or full regulatory digests.

stateDiagram-v2 [*] --> disabled: feature off disabled --> enabledIdle: enabled, no session evidence enabledIdle --> active: genome or monitor evidence active --> pendingApply: reshape scheduled pendingApply --> applied: next boundary apply applied --> active: further evaluations active --> degraded: bounded failure recorded degraded --> active: recovery enabledIdle --> unknown: no snapshot active --> unknown: evidence missing unknown --> enabledIdle: snapshot available
Section titled “Related: layered regulation and precedence”

Adaptive orchestration is only one layer in BMO’s regulation model. Mesh, health follow-ons, workspace observation, and choreography also contribute runtime behavior, but they do not all own the same state.

Start with How BMO thinks and acts if you want the user-facing overview.

For contributors: Deep precedence rules across regulation layers are documented in the repository topic ai-organism-constitution.md.

Section titled “Related”

For contributors: Classifier design and monitor signal details are covered in the repository topics adaptive-orchestrator-classifier.md and adaptive-orchestrator-monitor-signals.md.

Visual: coordination genome overlays

Section titled “Visual: coordination genome overlays”
Genome overlays
Baseline
Config genomeDefault choreography, topology, isolation, conflict strategy, edit preference, and model hint.
Classifier
Intent patchHeuristic or bounded LLM classification adjusts coordination shape.
Monitor
Outcome overlayFinalized run signals can prepare a next-run adjustment, including an opt-in model downgrade.
Boundary
Next root runRuntime apply waits for a safe run boundary instead of mutating a live run midstream.
Adaptive orchestration is an overlay stack, not an unbounded autonomous rewrite of the task.