V2 admin renders derived `enable_multi_agent_orchestration` as an editable toggle in AI Models → Connections

Summary

The V2 admin surface renders enable_multi_agent_orchestration as a standalone toggle inside AI Models → Connections. It should not be a toggle at all: it is a derived value, and writing it directly desynchronises it from the setting it is derived from.

Why it appears there

Settings that admin_settings_fields.py does not describe are still shown, by scanning the settings document for enable_* booleans and matching each to a nav section that shares its leading word stems (buildCapabilityIndex in AdminSettingsPage.tsx).

Replicating that heuristic against the live ADMIN_NAV:

key tokens: ['multi', 'agent', 'orchestration']
best match: ('AI Models', 'Connections', 'multi-endpoint-configuration')  score: 1

It matches on multi against multi-endpoint-configuration and wins. So it renders as a switch labelled "Multi agent orchestration", with no help text, in a card about model connections.

Why it is more than a misfiling

enable_multi_agent_orchestration is not independently settable. route_backend_agents.py computes it from orchestration_type:

matched_type = next((t for t in types if t.get("value") == orchestration_type), None)
if matched_type['agent_mode'] == 'multi':
    enable_multi = True
else:
    enable_multi = False
...
settings["orchestration_type"] = orchestration_type
settings["enable_multi_agent_orchestration"] = enable_multi
...
setattr(builtins, "kernel_reload_needed", True)

There is no control for it in any templates/admin/_panes/*.html; the admin-facing control is orchestration_type in agents.html.

Toggling it from V2 therefore:

1. Writes the key directly through the settings PATCH, leaving it disagreeing with orchestration_type.
2. Skips the kernel_reload_needed trigger that the orchestration route sets.

Consumers read it independently of orchestration_type (route_backend_chats.py, route_backend_agents.py), so a desynchronised pair changes how chat dispatches to agents.

Why declaring it is not the fix

The documented remedy for a misfiled key is to declare it in its real section, which removes it from the scan. That does not work here.

test_v2_admin_capability_placement.py deliberately checks that a declared field has a V1 pane counterpart, "because a schema field with no server-rendered counterpart would write a setting the rest of the application never reads". This key has no such counterpart, so declaring it would correctly fail that test — the test is right, and the key genuinely should not be an admin-settings field.

Suggested fix

Add a way to exclude a key from the capability scan without declaring a control for it — for example a CAPABILITY_SCAN_EXCLUSIONS set in admin_settings_fields.py, each entry carrying a written justification, returned alongside field_schema from GET /api/v2/admin/settings and honoured by buildCapabilityIndex.

That mechanism would apply to any setting owned by its own API rather than the admin settings form, so this is likely not the only key that needs it. Auditing the remaining undeclared enable_* keys for the same shape would be worthwhile.

Not fixed in the current work

Found while building the AI Models rebuild (#1415 and its stacked follow-ups). Deliberately left out of those PRs because the fix needs new machinery in the renderer and the schema module, and three stacked branches were in flight against those same files.

Related

• #1415 — Rebuild admin AI Models: global model connections (phase 1), which introduced the Connections card this renders in.

Start with admin_settings_fields.py, GET /api/v2/admin/settings, and buildCapabilityIndex in AdminSettingsPage.tsx; review test_v2_admin_capability_placement.py for the existing schema constraints. Trace how enable_multi_agent_orchestration is computed in route_backend_agents.py and ensure the exclusion is returned by the schema and honored by the capability scan. Done means the derived key no longer appears as an editable toggle while orchestration_type remains the admin control.