v0.9.3: Fleet model classes, loadout auto, and semantic route roles

[Hmbown]

Goal

Build the shared model/loadout selector used by TUI, CLI, exec, subagents, and Fleet workers.

Fleet needs one clear user-facing automatic mode: Fleet loadout auto. It should resolve the whole compute loadout for a role/slot, not just pick a model string and not just tweak thinking level.

auto must not mean "reuse the global default model" and must not call a hardcoded selector model. It resolves through the same provider/model catalog and route resolver used by normal interactive selection.

Important: Fleet loadout auto is explicit opt-in. CodeWhale must not inspect freeform prompt text and silently change provider, model, Fleet model class, or reasoning mode. Auto selection can use explicit metadata such as Fleet role, Fleet slot/loadout, command purpose, hard capability requirements, cost/latency preferences, context limits, and fallback policy.

Auto Contract

Use one user-facing concept:

• Fleet loadout auto: resolves provider, Fleet model class, canonical model, provider wire model, reasoning policy, tool/structured/long-context requirements, local/private constraints, cost/usage posture, and fallback policy.

Do not expose two same-looking auto knobs in normal Fleet authoring. If the implementation needs an advanced route-level reasoning policy, name it explicitly as reasoning_policy = "auto" or similar, document it as part of the resolved loadout, and record the effective reasoning level in the run ledger.

Recommended authoring shape:

worker.role = "reviewer"
worker.loadout = "auto"

Optional explicit override shape:

worker.role = "reviewer"
worker.model_class = "balanced"
worker.reasoning_policy = "auto"

Broad Fleet loadout auto should be the default meaning of auto because users want a role/slot to get the right class of worker, not a different thinking knob on a preselected model.

If loadout auto uses an LLM/router model to decide, that router must be explicitly configured by the user. The run record must persist router provider/model, router input summary, decision source, effective route, effective reasoning, and fallback chain outcome. Deterministic policy-based auto is acceptable as the default when no router model is configured.

Architecture Contract

This issue depends on #2608 and #3384.

The selector must keep these concepts separate:

• Provider facts: how to talk to a provider, auth schemes, endpoint protocols, default base URLs, model-id policy, live catalog support.
• Model facts: provider-agnostic model behavior such as context window, max output, modalities, reasoning, tools, JSON/schema support, streaming, and prompt density.
• Provider model offerings: provider + canonical model + wire model id + endpoint + provider-specific capability/pricing/usage overrides.
• Route candidates: runtime-resolved objects that combine provider facts, model facts, offerings, user config, auth, base URL, validation, and effective capability.
• Semantic route roles: provider-agnostic selection intent, not vendor names or model families.
• Fleet model classes: user-friendly three-tier presets that map Fleet slots to route roles/capability predicates.

A model may satisfy many roles and classes. Do not encode a renamed pro/flash pair as the routing API.

Reasoning Policy

Reasoning/thinking levels have enough provider-specific details that they need a structured policy, not scattered caller logic.

The route layer should distinguish:

• user-facing levels: off, low, medium, high, max/xhigh, and advanced reasoning_policy = "auto";
• route capability: supported, unsupported, unknown;
• disable support: can disable, cannot disable, unknown;
• provider wire mapping: e.g. reasoning_effort, thinking, think, Responses reasoning.effort, token/budget fields, or no field;
• bounds/caps from user config, Fleet slot, provider policy, and cost/usage policy.

A Fleet role may ask for loadout auto; the resolver then chooses the route and reasoning policy inside user/session bounds. It must record the effective reasoning level and the source of that choice.

Reasoning policy is not a hidden prompt classifier. It may depend on explicit role/slot/purpose/capability metadata and configured router policy, not raw freeform prompt interpretation.

Fleet Model Classes

Fleet should expose a simple default three-class model system, similar in spirit to strong/balanced/fast model tiers rather than provider-specific names:

• strong: highest-quality/higher-reasoning route inside policy. Prefer for hard coding, debugging, security, release, architecture, and uncertain work.
• balanced: default full-quality route for normal interactive planning, building, review, and synthesis.
• fast: low-latency or cheaper route for scouting, summaries, simple checks, routing, classifiers, and bulk fanout.

A provider can map:

• all three classes to one model when it only has one suitable route;
• two classes to two models;
• three classes to three different models;
• a class to an explicit provider/model override when the user pins it.

Never fabricate a model id to fill a class. If no class-specific sibling exists, use the provider/current default that satisfies hard requirements.

Semantic Route Roles

Initial lower-level role vocabulary:

• primary: default full-quality interactive route.
• fast: low-latency simple turns, summaries, routing, and cheap checks.
• economy / alias cheap: bulk fanout where cost matters more than top quality.
• reasoning: hard coding, debugging, architecture, security, uncertain work.
• long_context: tasks where fitting/reusing context is the main constraint.
• tool: agentic/tool-call route.
• structured: JSON/schema/extraction/repair/classifier route.
• local: local-serving or privacy preference.

fallback is not a model role. Keep fallback as ordered chain/source metadata.

Capabilities stay separate from roles and classes. Capabilities should be tri-state where practical: supported, unsupported, unknown. Unknown is not the same as false.

Ranking Policy

Use this conflict order when Fleet loadout auto or fallback is explicitly enabled:

1. Explicit user/provider/model choice.
2. Hard requirements: auth, route validity, modality, context fit, tool calls, JSON/schema, local/private policy.
3. Fleet role/slot/loadout policy and caller-provided command purpose.
4. Context pressure: if it will not fit, long_context wins.
5. Tool reliability: tool-heavy work beats cheap/fast.
6. User cost mode: economy wins only after hard requirements and risk checks.
7. Latency: fast wins for explicitly trivial/status/summarization/router roles.
8. Configured fallback chain.
9. Stable deterministic tie-breaker.

Do not use freeform prompt-content classification as a hidden routing signal.

Fleet Integration

Fleet specs should require a semantic worker role and optionally a Fleet model class or semantic route role. Explicit provider/model routes are overrides, not the normal authoring path.

Authored specs stay portable:

worker.role = "reviewer"
worker.loadout = "auto"

Resolved run records must persist the effective route for audit:

provider = "..."
model = "..."
wire_model = "..."
reasoning = "..."
route_source = "fleet-loadout-auto"
worker_role = "reviewer"
model_class = "balanced"
router_source = "deterministic-policy"

Default worker policy:

• explore, read-only, scout: fast.
• smoke-runner, simple verifier: fast, upgrade to balanced or strong only for failure analysis.
• reviewer, planner: balanced.
• builder, implementer: balanced.
• orchestrator, synthesis, release, security: strong when supported and allowed.
• unknown/custom: inherit unless explicitly configured.

Guardrail: if a provider has no known fast sibling, fast resolves to the current/provider default model. Never fabricate a DeepSeek, cloud, or aggregator model id on Ollama, Moonshot, local runtimes, custom endpoints, or any provider that did not offer it.

Scope

1. Define Fleet loadout auto as the single normal user-facing automatic route/loadout concept.
2. Define the semantic route role vocabulary and capability predicates in the shared route/model layer.
3. Define Fleet model classes (strong, balanced, fast) as configurable presets over route roles and capability predicates.
4. Define route-level reasoning policy as part of loadout resolution, not a second normal auto mode.
5. Build resolved-route inventory from configured providers, static catalog data, live provider catalog cache, and user overrides.
6. Make loadout auto an explicit opt-in sentinel resolved from metadata/policy or user-configured router model, not a concrete model id and not hidden prompt inspection.
7. Expose inventory and route explanations to /model, /provider, CLI, exec, subagents, and Fleet.
8. Persist effective provider/model/wire-model/reasoning/source/router metadata in Fleet and subagent run records.
9. Add parity tests proving the same worker role and model class resolve identically through subagent and Fleet paths.

Acceptance Criteria

• Fleet loadout auto routes through shared catalog/resolver APIs, not a Fleet-specific table.
• Normal Fleet authoring exposes one broad auto, not two ambiguous auto knobs.
• Loadout auto can resolve provider, model class, model, reasoning policy, capability requirements, cost/usage posture, and fallback policy.
• Route-level reasoning policy is recorded as part of the resolved loadout.
• LLM/router-model-based auto requires explicit user config and audited run records.
• Auto is explicit opt-in and does not use hidden prompt-content classification.
• Fleet model classes are provider-agnostic and configurable.
• Model selection asks for semantic roles/classes and capability predicates, not DeepSeek/Kimi/GLM-specific helpers.
• One model can satisfy multiple roles/classes.
• A failed route resolution fails before mutating config, UI state, engine state, or run ledger state.
• Custom IDs are never auto-picked; they are honored only when explicitly supplied or saved for that provider/endpoint.
• Local/custom/pass-through providers preserve user model strings and do not invent cloud model ids.
• The ledger records effective route details for every headless worker.

Verification

Required tests:

• Synthetic provider matrix for role/class resolution across direct, aggregator, local, and custom providers.
• Fleet loadout auto test resolving provider/model/reasoning together.
• Explicit model class plus reasoning policy test.
• Router-model config required test when LLM-based routing is enabled.
• Mismatched provider/model regression from the Z.ai/GLM + deepseek-v4-pro failure.
• fast fallback test where no fast sibling exists.
• Ambiguous model alias test that asks for provider disambiguation instead of silently switching.
• No-hidden-prompt-router test: freeform prompt text alone cannot change provider/model/reasoning mode.
• Subagent/Fleet parity test for worker role, model class, semantic route role, reasoning, tool support, and spawn-depth behavior.

Related

• v0.8.65 EPIC: Separate provider facts, model facts, offerings, and route resolution #2608 provider/model/offering/catalog architecture.
• v0.8.65: Resolve every provider/model switch through a ReadyRouteCandidate #3384 ReadyRouteCandidate mutation gate.
• v0.8.65: Selected-route reasoning and token-limit wire-protocol mapping #3024 selected-route reasoning and token-limit wire mapping.
• v0.8.65: Fleet profiles for agent roles, loadouts, permissions, and delegation #3167 Fleet profiles, slots, roles, and loadouts.
• v0.8.65 EPIC: Fleet execution substrate for profiled workers #3154 Fleet/WhaleFlow execution substrate.
• v0.8.65: Provider-scoped model candidates for /model, picker, and slash completions #3383 and v0.8.65: Cross-provider /model search using explicit route rows #3075 model picker projections.

[Hmbown]

Retargeting to v0.8.61. The v0.8.60 branch fixed the immediate broken route behavior enough for release testing: provider-qualified Z.ai/GLM works, codewhale fleet no longer misroutes through a TUI prompt, and auto/default routing has a typed inventory foundation.

The full issue is still bigger than the v0.8.60 release gate: route-effective authenticated model inventory, fleet role model policy, explicit/auto constraints, and selector reporting still need a dedicated follow-up slice.