Skip to content

Commit 6154686

Browse files
committed
fix(settings): stop a resolved default being writable; sync roadmap/spec/docs
A 5-lens audit of the branch produced 14 confirmed findings (9 more were refuted and dropped). This lands the ones that belong in this PR; the four live-verification findings that are pre-existing and unrelated are filed as issues #1083 and #1084 rather than widened into this change. THE REAL BUG — a resolved default WAS writable, which falsifies the claim this PR made: SettingsSection keeps a component-local `dirty` ref, and dirtyKeys is the UNION of that ref and the working/original comparison. Nothing keyed the section, so Reload replaced both snapshots while leaving the ref populated: pick Compact -> Reload -> Save PATCHed `tool_response_mode: "full"` into a config that never had the key. Every section is now keyed on a form epoch bumped per hydration, so it remounts with an empty ref. Verified live: after Reload the abandoned edit is gone, Save is disabled, and the key is still absent from the config file on disk. This also fixes the general case — the stale ref could strand ANY field. TESTS THAT COULD NOT FAIL. Cross-model review caught the vacuous "both copies normalized" assertion in the tray test; the same audit found I had left the identical tautology in the Web UI twin, plus a Raw-tab test that matched source text and so could not see whether `cfg` was still the untouched response by the time it was serialized. Both are now real assertions against an extracted `hydrateConfigState` helper (the Vue counterpart of the Swift `hydrate(from:)` seam). Mutation-checked in both directions: normalizing one snapshot fails them, and stripping the section keys fails the regression test. SYNC: - roadmap.yaml: the schema-deferred epic still said `in_progress` with a note ending "plan in progress" — spec 102 shipped in #1063. Now `done` with a `pr:` ref, and the note's "~88% smaller listing" projection is corrected with the measured 29.7%/34.8% and the 38.9% ceiling. ROADMAP.md is GENERATED, so the edit is in the YAML and the file regenerated via scripts/gen-roadmap.py. - spec.md/plan.md asserted SC-001's >=70% as fact in four more places, and plan.md claimed "Backend-only; no frontend, tray, or Swift changes" plus "no tray state" — both contradicted by the UI work. SC-001 is now marked NOT MET with the measurement, the ceiling, and the two options open to the maintainer. tasks.md was already honest; only two drift notes corrected (T083 said four new goldens, git shows three; T073 named the wrong file). - docs: "routing_mode sits directly above it" was wrong — tool_response_mode is between them. The settings-page restart list named `data_dir`, which is not a field at all, and omitted routing_mode.
1 parent cd0aee3 commit 6154686

10 files changed

Lines changed: 173 additions & 90 deletions

File tree

‎ROADMAP.md‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -67,8 +67,8 @@ graph LR
6767
classDef in_progress fill:#1f6feb,stroke:#0b3d91,color:#ffffff;
6868
classDef in_review fill:#9a6700,stroke:#5c3d00,color:#ffffff;
6969
classDef todo fill:#6e7781,stroke:#3d4248,color:#ffffff;
70-
class sandbox_isolation,scanner_v2,scanner_simplification done;
71-
class analytics_dashboard,schema_deferred,telemetry_identity,telemetry_v7_churn in_progress;
70+
class sandbox_isolation,scanner_v2,scanner_simplification,schema_deferred done;
71+
class analytics_dashboard,telemetry_identity,telemetry_v7_churn in_progress;
7272
class tpa_db in_review;
7373
class ux_audit,action_log_transparency,remote_access_tunnel,token_bench,tool_graph,discovery_eval_harness todo;
7474
```
@@ -154,15 +154,6 @@ graph LR
154154

155155
</details>
156156

157-
<details>
158-
<summary>🔵 Deferred-schema serialization for the direct tools/list surface (spec 102) — In progress · P1</summary>
159-
160-
> Direct mode enumerates every upstream tool but always ships full inputSchema (~30K tokens for a 100-tool fleet; Spec 083 profiling put ~77% of the payload in schemas agents rarely read). Deferred serialization keeps every tool name, description and annotation and appends the Spec 085 compact signature instead of the schema (~88% smaller listing), with describe_tool on the direct surface to recover it and the shipped pre-dispatch validation turning a wrong guess into one self-healing retry. Not a new routing_mode — a serialization mode of the direct surface, on the same tool_response_mode axis that already governs retrieve_tools. Spec merged in #1035 (issue #971, maintainer-accepted direction); plan in progress.
161-
162-
Spec: [102-schema-deferred](./specs/102-schema-deferred/)
163-
164-
</details>
165-
166157
<details>
167158
<summary>🔵 Telemetry identity &amp; data quality (machine_id + CI-filter hardening) — In progress · P1</summary>
168159

@@ -711,6 +702,15 @@ graph LR
711702

712703
</details>
713704

705+
<details>
706+
<summary>🟢 Deferred-schema serialization for the direct tools/list surface (spec 102) — Done · P1</summary>
707+
708+
> Direct mode enumerates every upstream tool but always ships full inputSchema (~30K tokens for a 100-tool fleet; Spec 083 profiling put ~77% of the payload in schemas agents rarely read). Deferred serialization keeps every tool name, description and annotation and appends the Spec 085 compact signature instead of the schema (~88% smaller listing), with describe_tool on the direct surface to recover it and the shipped pre-dispatch validation turning a wrong guess into one self-healing retry. Not a new routing_mode — a serialization mode of the direct surface, on the same tool_response_mode axis that already governs retrieve_tools. Spec merged in #1035 (issue #971, maintainer-accepted direction). COMPLETE: all 89 tasks shipped in #1063; the settings UI for both serialization axes followed in #1082. MEASURED SAVINGS FELL WELL SHORT OF THE ~88% PROJECTION ABOVE: 29.7% on the frozen reference corpus and 34.8% on a 527-tool snapshot, against SC-001's >=70% target, with 38.9% the arithmetic ceiling even if both the schema and the signature were deleted. The projection assumed schemas dominate the payload; names, descriptions and annotations turn out to carry most of it. SC-001 is knowingly unmet and awaits a maintainer decision (restate per corpus shape, or re-target at a schema-heavy corpus) — see specs/102-schema-deferred/tasks.md T035a.
709+
710+
Spec: [102-schema-deferred](./specs/102-schema-deferred/) · PR: #1063
711+
712+
</details>
713+
714714
<details>
715715
<summary>🟢 Tray↔core decoupling: socket/REST API only, no config-file reads — Done · P2</summary>
716716

@@ -740,7 +740,6 @@ graph LR
740740
| --- | --- | --- | --- | --- | --- |
741741
| Release qualification gate (auto-QA matrix blocks the tag) | In progress | P0 | — | [081-release-qa-gate](./specs/081-release-qa-gate/) | |
742742
| Analytics dashboard as default page | In progress | P1 | 25/26 (96%) | [069-observability-usage-graphs](./specs/069-observability-usage-graphs/) | |
743-
| Deferred-schema serialization for the direct tools/list surface (spec 102) | In progress | P1 | 89/89 (100%) | [102-schema-deferred](./specs/102-schema-deferred/) | |
744743
| Telemetry identity & data quality (machine_id + CI-filter hardening) | In progress | P1 | — | | |
745744
| Telemetry v7: honest funnel + churn instrumentation | In progress | P1 | — | [080-telemetry-v7-churn](./specs/080-telemetry-v7-churn/) | |
746745
| MCP protocol upgrade to 2026-07-28 revision | In progress | P3 | — | [058-mcp-2026-upgrade](./specs/058-mcp-2026-upgrade/) | #1033 |
@@ -765,6 +764,7 @@ graph LR
765764
| Spec 076 deterministic offline tool-scanner `MCP-3574` | Done | P1 | 22/24 (92%) | [076-deterministic-tool-scanner](./specs/076-deterministic-tool-scanner/) | |
766765
| Registries — easier search + add-server | Done | P1 | 21/24 (88%) | [070-registry-easy-upstream-add](./specs/070-registry-easy-upstream-add/) | |
767766
| Scanner simplification (deterministic default, opt-in deep scan) | Done | P1 | 38/42 (90%) | [077-scanner-simplification](./specs/077-scanner-simplification/) | |
767+
| Deferred-schema serialization for the direct tools/list surface (spec 102) | Done | P1 | 89/89 (100%) | [102-schema-deferred](./specs/102-schema-deferred/) | #1063 |
768768
| Tray↔core decoupling: socket/REST API only, no config-file reads | Done | P2 | — | | |
769769

770770
## Shipped (archived)

‎docs/features/schema-deferred-direct-mode.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -79,10 +79,11 @@ mcpproxy serve --direct-tool-response-mode=deferred
7979
```
8080

8181
Or from the UI — **Settings → General → "Detail in Direct-mode listings"**, in
82-
both the Web UI and the macOS tray. `routing_mode` sits directly above it in the
83-
same section. Note the asymmetry: changing the serialization mode applies hot,
84-
but changing `routing_mode` needs a restart (the badge on that field says so),
85-
because `/mcp` binds its routing mode once at startup.
82+
both the Web UI and the macOS tray. The routing-mode field ("How agents find
83+
tools") heads the same section, two rows above. Note the asymmetry: changing the
84+
serialization mode applies hot, but changing `routing_mode` needs a restart (the
85+
badge on that field says so), because `/mcp` binds its routing mode once at
86+
startup.
8687

8788
**This is a separate axis from `tool_response_mode`.** That key (and its
8889
`--tool-response-mode` flag and `MCPPROXY_TOOL_RESPONSE_MODE` alias) still governs

‎docs/features/settings-page.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,10 @@ pipeline. Because the merge starts from the live config and overlays just your
2929
changes, unrelated values and masked secrets (API key, secret headers) are never
3030
overwritten.
3131

32-
Fields that need a restart (`listen`, `data_dir`, `api_key`, `tls.*`) show a
33-
**restart** badge; sensitive changes (reveal secret headers, disabling
32+
Fields that need a restart (`listen`, `api_key`, `routing_mode`, `tls.*`,
33+
`code_execution_pool_size`, and `server_edition.enabled` on the server edition)
34+
show a **restart** badge — the two response-detail modes deliberately carry no
35+
badge, because they hot-reload; sensitive changes (reveal secret headers, disabling
3436
quarantine/management, binding to a non-loopback address) require an explicit
3537
confirmation before they apply.
3638

‎frontend/src/views/Settings.vue‎

Lines changed: 21 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@
3232
<div v-if="loaded && search.trim()" class="card bg-base-100 shadow-md" data-test="settings-search-results">
3333
<div class="card-body">
3434
<h2 class="card-title text-lg">🔍 Search results <span class="text-sm font-normal text-base-content/60">({{ filteredFields.length }})</span></h2>
35-
<SettingsSection section-id="search" :fields="filteredFields" :working="state.working" :original="state.original" />
35+
<SettingsSection :key="`sec-${formEpoch}`" section-id="search" :fields="filteredFields" :working="state.working" :original="state.original" />
3636
</div>
3737
</div>
3838

@@ -82,15 +82,15 @@
8282
{{ p.label }}: {{ p.on ? 'on' : 'off' }}
8383
</span>
8484
</div>
85-
<SettingsSection section-id="security" :fields="securityFields" :working="state.working" :original="state.original" />
85+
<SettingsSection :key="`sec-${formEpoch}`" section-id="security" :fields="securityFields" :working="state.working" :original="state.original" />
8686
</div>
8787
</div>
8888

8989
<!-- General -->
9090
<div v-show="activeTab === 'general'" class="card bg-base-100 shadow-md">
9191
<div class="card-body">
9292
<h2 class="card-title text-lg">⚙️ General</h2>
93-
<SettingsSection section-id="general" :fields="generalFields" :working="state.working" :original="state.original" />
93+
<SettingsSection :key="`sec-${formEpoch}`" section-id="general" :fields="generalFields" :working="state.working" :original="state.original" />
9494
</div>
9595
</div>
9696

@@ -110,7 +110,7 @@
110110
:data-test="`settings-accordion-docs-${acc.id}`"
111111
>Learn more ↗</a>
112112
</p>
113-
<SettingsSection :section-id="acc.id" :fields="acc.fields" :working="state.working" :original="state.original" />
113+
<SettingsSection :key="`acc-${acc.id}-${formEpoch}`" :section-id="acc.id" :fields="acc.fields" :working="state.working" :original="state.original" />
114114
</div>
115115
</details>
116116
<div class="text-xs text-base-content/50 px-1">
@@ -123,7 +123,7 @@
123123
<div v-if="hasServerEdition" v-show="activeTab === 'teams'" class="card bg-base-100 shadow-md">
124124
<div class="card-body">
125125
<h2 class="card-title text-lg" data-test="settings-server-edition-title">{{ serverEditionTitle }}</h2>
126-
<SettingsSection section-id="teams" :fields="serverEditionFields" :working="state.working" :original="state.original" />
126+
<SettingsSection :key="`sec-${formEpoch}`" section-id="teams" :fields="serverEditionFields" :working="state.working" :original="state.original" />
127127
</div>
128128
</div>
129129

@@ -194,7 +194,7 @@ import {
194194
docsUrl,
195195
isBlankInstructions,
196196
restartRequiredLabels,
197-
normalizeFieldDefaults,
197+
hydrateConfigState,
198198
type SettingField,
199199
type SettingsAccordion,
200200
} from '@/views/settings/fields'
@@ -249,6 +249,13 @@ const loadError = ref('')
249249
const activeTab = ref<string>('security')
250250
const showConnect = ref(false)
251251
const state = reactive<{ working: any; original: any }>({ working: {}, original: {} })
252+
// Bumped on every (re)hydration so each SettingsSection remounts with a fresh
253+
// component-local `dirty` ref. Without this, a field the user edited and then
254+
// abandoned via Reload stays in that ref, and because dirtyKeys is the UNION of
255+
// it and the working/original comparison, Save would PATCH a key whose value
256+
// never actually moved — writing a resolved default into a config that omitted
257+
// the key entirely.
258+
const formEpoch = ref(0)
252259
// Server-edition (multi-user) config lives under `server_edition` (MCP-1086).
253260
// Gate on the canonical key, falling back to the legacy `teams` key so a config
254261
// written before the rename still surfaces the Server Edition tab.
@@ -320,20 +327,6 @@ const editorOptions = {
320327
lineNumbers: 'on' as const,
321328
}
322329
323-
function clone<T>(v: T): T {
324-
return JSON.parse(JSON.stringify(v))
325-
}
326-
327-
// Back-compat for the teams -> server_edition rename (MCP-1086): if a config
328-
// only carries the legacy `teams` key, mirror it onto `server_edition` so the
329-
// form (which binds to `server_edition.*`) hydrates. Mutates and returns cfg.
330-
function aliasServerEdition(cfg: any): any {
331-
if (cfg && cfg.server_edition == null && cfg.teams != null) {
332-
cfg.server_edition = cfg.teams
333-
}
334-
return cfg
335-
}
336-
337330
async function loadConfig() {
338331
loading.value = true
339332
loadError.value = ''
@@ -349,9 +342,14 @@ async function loadConfig() {
349342
// keys the API omits (the serialization modes: absent means "full"), so
350343
// their <select> shows the real default instead of an empty box. Applied
351344
// to both copies — otherwise the untouched field would read as dirty.
352-
state.working = normalizeFieldDefaults(aliasServerEdition(clone(cfg)))
353-
state.original = normalizeFieldDefaults(aliasServerEdition(clone(cfg)))
354-
configJson.value = JSON.stringify(cfg, null, 2)
345+
const hydrated = hydrateConfigState(cfg)
346+
state.working = hydrated.working
347+
state.original = hydrated.original
348+
formEpoch.value++
349+
// hydrated.raw, not cfg: the Raw tab must show the untouched response,
350+
// and this makes that dependency explicit rather than relying on the
351+
// hydration helper's internal cloning.
352+
configJson.value = JSON.stringify(hydrated.raw, null, 2)
355353
configStatus.value = { valid: true }
356354
loaded.value = true
357355
maybePrefillInstructions()

‎frontend/src/views/settings/fields.ts‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -519,6 +519,38 @@ export function allCatalogFields(): SettingField[] {
519519
* "full". Applied to BOTH the working copy and the last-saved snapshot so a
520520
* field nobody touched never counts as an unsaved change.
521521
*/
522+
/**
523+
* Back-compat for the teams -> server_edition rename (MCP-1086): if a config
524+
* only carries the legacy `teams` key, mirror it onto `server_edition` so the
525+
* form (which binds to `server_edition.*`) hydrates. Mutates and returns cfg.
526+
*/
527+
export function aliasServerEdition(cfg: any): any {
528+
if (cfg && cfg.server_edition == null && cfg.teams != null) {
529+
cfg.server_edition = cfg.teams
530+
}
531+
return cfg
532+
}
533+
534+
/**
535+
* Build the Settings form state from a raw `GET /api/v1/config` response.
536+
*
537+
* Extracted from Settings.vue so the hydration invariant is testable directly
538+
* rather than by matching source text. That invariant:
539+
*
540+
* - `working` and `original` BOTH get the resolved defaults, so a field nobody
541+
* touched never counts as an unsaved change.
542+
* - `raw` is the untouched response. The Raw JSON tab must show server truth,
543+
* and both helpers above MUTATE their argument, so the clones matter.
544+
*/
545+
export function hydrateConfigState(cfg: any): { working: any; original: any; raw: any } {
546+
const clone = (v: any) => (v == null ? v : JSON.parse(JSON.stringify(v)))
547+
return {
548+
working: normalizeFieldDefaults(aliasServerEdition(clone(cfg))),
549+
original: normalizeFieldDefaults(aliasServerEdition(clone(cfg))),
550+
raw: clone(cfg),
551+
}
552+
}
553+
522554
export function normalizeFieldDefaults(cfg: any): any {
523555
if (cfg == null || typeof cfg !== 'object') return cfg
524556
for (const f of allCatalogFields()) {

‎frontend/tests/unit/settings-serialization-modes.spec.ts‎

Lines changed: 67 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import { readFileSync } from 'node:fs'
33
import { resolve } from 'node:path'
44
import {
55
GENERAL_FIELDS,
6+
hydrateConfigState,
67
allCatalogFields,
78
normalizeFieldDefaults,
89
restartRequiredLabels,
@@ -90,23 +91,14 @@ describe('normalizeFieldDefaults', () => {
9091
expect(cfg.direct_tool_response_mode).toBe('deferred')
9192
})
9293

93-
// Settings.vue must normalize `working` AND `original` from the same
94-
// response. Normalizing only the working copy is a live footgun: the value
95-
// genuinely diverges from the raw response, so the untouched field would
96-
// compare unequal and the section would open claiming an unsaved change.
97-
// (Asserting the divergence is what gives the "normalize both" rule teeth —
98-
// comparing two identically-normalized objects would pass unconditionally.)
99-
it('diverges from the raw response, so both copies must be normalized', () => {
94+
// The normalized copy genuinely diverges from the raw response — which is
95+
// what makes the "normalize both snapshots" rule load-bearing. (Comparing two
96+
// identically-normalized objects would pass unconditionally; that vacuous
97+
// form is what cross-model review caught in the tray twin of this test.)
98+
it('diverges from the raw response', () => {
10099
const response = { listen: '127.0.0.1:8080' }
101-
const working = normalizeFieldDefaults({ ...response })
102-
103-
expect(getPath(working, 'tool_response_mode')).toBe('full')
104100
expect(getPath(response, 'tool_response_mode')).toBeUndefined()
105-
106-
const original = normalizeFieldDefaults({ ...response })
107-
for (const f of allCatalogFields()) {
108-
expect(getPath(working, f.key)).toEqual(getPath(original, f.key))
109-
}
101+
expect(getPath(normalizeFieldDefaults({ ...response }), 'tool_response_mode')).toBe('full')
110102
})
111103

112104
it('leaves fields that declare no default untouched', () => {
@@ -122,26 +114,65 @@ describe('normalizeFieldDefaults', () => {
122114
})
123115
})
124116

125-
// The catalogue is inert until Settings.vue applies it. There is no mount
126-
// harness for that view, so pin the wiring at the source level — the same
127-
// approach settings-deep-scan-field.spec.ts uses. Without this, dropping the
128-
// normalize call would leave every test above green while the Settings page
129-
// showed two empty dropdowns.
130-
describe('Settings.vue wiring', () => {
131-
const source = readFileSync(
132-
resolve(__dirname, '../../src/views/Settings.vue'),
133-
'utf-8',
134-
)
135-
136-
it('normalizes both the working copy and the last-saved snapshot', () => {
137-
expect(source).toMatch(/state\.working = normalizeFieldDefaults\(/)
138-
expect(source).toMatch(/state\.original = normalizeFieldDefaults\(/)
139-
})
140-
141-
it('leaves the Raw JSON tab on the untouched server response', () => {
142-
// configJson must serialize `cfg`, not a normalized clone — the Raw tab
143-
// shows what the core actually holds, and normalization invents keys the
144-
// config file does not contain.
145-
expect(source).toMatch(/configJson\.value = JSON\.stringify\(cfg,/)
117+
// hydrateConfigState is what Settings.vue's loadConfig() actually calls, so
118+
// these assert the invariant itself rather than matching source text — a
119+
// source-text match cannot tell whether `cfg` is still the untouched response
120+
// by the time the Raw tab serializes it.
121+
describe('hydrateConfigState', () => {
122+
const response = () => ({ listen: '127.0.0.1:8080' })
123+
124+
it('normalizes both snapshots, so nothing reads as dirty on open', () => {
125+
const { working, original } = hydrateConfigState(response())
126+
expect(getPath(working, 'tool_response_mode')).toBe('full')
127+
expect(getPath(original, 'tool_response_mode')).toBe('full')
128+
for (const f of allCatalogFields()) {
129+
expect(getPath(working, f.key)).toEqual(getPath(original, f.key))
130+
}
131+
})
132+
133+
it('keeps raw as the untouched server response for the Raw JSON tab', () => {
134+
const { raw } = hydrateConfigState(response())
135+
expect(JSON.stringify(raw)).not.toContain('tool_response_mode')
136+
expect(JSON.stringify(raw)).not.toContain('direct_tool_response_mode')
137+
expect(getPath(raw, 'listen')).toBe('127.0.0.1:8080')
138+
})
139+
140+
it('does not mutate its argument', () => {
141+
const cfg = response()
142+
hydrateConfigState(cfg)
143+
expect(getPath(cfg, 'tool_response_mode')).toBeUndefined()
144+
})
145+
146+
it('still aliases a legacy teams-keyed config onto server_edition', () => {
147+
const { working } = hydrateConfigState({ teams: { enabled: true } })
148+
expect(getPath(working, 'server_edition.enabled')).toBe(true)
149+
})
150+
151+
it('preserves an explicitly-set mode', () => {
152+
const { working, raw } = hydrateConfigState({ direct_tool_response_mode: 'deferred' })
153+
expect(getPath(working, 'direct_tool_response_mode')).toBe('deferred')
154+
expect(getPath(raw, 'direct_tool_response_mode')).toBe('deferred')
155+
})
156+
})
157+
158+
// Regression: cross-model review found that a resolved default WAS writable.
159+
// SettingsSection keeps a component-local `dirty` ref and dirtyKeys is the
160+
// UNION of it and the working/original comparison. Reload replaces both
161+
// snapshots but used to leave that ref populated, so: pick Compact -> Reload ->
162+
// Save PATCHed `tool_response_mode: "full"` into a config that never had the
163+
// key. Settings.vue now keys every section on a form epoch bumped per
164+
// hydration, so the section remounts with an empty ref.
165+
describe('Settings.vue rehydration (stale-dirty regression)', () => {
166+
const source = readFileSync(resolve(__dirname, '../../src/views/Settings.vue'), 'utf-8')
167+
168+
it('bumps a form epoch on every hydration', () => {
169+
expect(source).toMatch(/formEpoch\.value\+\+/)
170+
})
171+
172+
it('keys every SettingsSection on that epoch so the dirty ref cannot survive', () => {
173+
const sections = source.match(/<SettingsSection\b/g) || []
174+
const keyed = source.match(/<SettingsSection :key="`[^`]*\$\{formEpoch\}`"/g) || []
175+
expect(sections.length).toBeGreaterThan(0)
176+
expect(keyed.length).toBe(sections.length)
146177
})
147178
})

0 commit comments

Comments
 (0)