@sema-agent/client-core 0.110.0 → 0.112.0

package/dist/localConfig/mcp/edit.js

@@ -0,0 +1,846 @@
+import { applyLocalConfigIntent, previewLocalConfigIntent, localConfigAccess, } from '../kernel.js';
+import { mcpServerNameVerdict } from '../../mcpWireCaps.js';
+import { readHostSettingsOnce } from '../../hostSettingsSource.js';
+import { settingsWriteStep } from '../settingsWrite.js';
+import { settingsCredentialKeyPaths } from '../../settingsCredentialKeyPaths.js';
+import { MCP_SERVER_SCOPES, USER_SCOPE_PATH, PROJECT_FILE_PATH, localScopePath, judgeTable, ownData, stringListOf, subTableOf, documentOf, fileReadingOf, nameListOf, } from './servers.js';
+export const MCP_SERVER_EDIT_OPS = Object.freeze(['add', 'update', 'remove', 'setEnabled', 'setProjectApproval', 'importFromSibling']);
+const REFUSAL_REASON = Object.freeze({
+    edit_malformed: 'invalid_request',
+    name_unusable: 'name_unusable',
+    name_reserved: 'name_reserved',
+    mcp_entry_invalid: 'mcp_entry_invalid',
+    name_taken: 'already_exists',
+    not_found: 'not_found',
+    ambiguous_scope: 'ambiguous_scope',
+    scope_not_offered: 'scope_unwritable',
+    scope_unreadable: 'scope_unreadable',
+    policy_locked: 'policy_denied',
+    base_conflict: 'base_conflict',
+    credentials_need_reentry: 'credentials_need_reentry',
+    untrusted_folder: 'untrusted_folder',
+});
+export const refusalReasonOf = (w) => REFUSAL_REASON[w];
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const own = (v, k) => {
+    const r = ownData(v, k);
+    return r.ok ? r.value : undefined;
+};
+const def = (o, k, v) => {
+    Object.defineProperty(o, k, { value: v, writable: true, enumerable: true, configurable: true });
+};
+function copyLayer(v) {
+    const out = {};
+    if (!isRecord(v))
+        return out;
+    for (const k of Object.keys(v)) {
+        const d = Object.getOwnPropertyDescriptor(v, k);
+        if (d !== undefined)
+            Object.defineProperty(out, k, { ...d, enumerable: true, configurable: true });
+    }
+    return out;
+}
+export function withPath(doc, path, value) {
+    const root = copyLayer(doc);
+    let box = root;
+    for (let i = 0; i < path.length - 1; i++) {
+        const seg = path[i];
+        const r = ownData(box, seg);
+        if (!r.ok)
+            return undefined;
+        if (r.value !== undefined && !isRecord(r.value))
+            return undefined;
+        const next = copyLayer(r.value);
+        def(box, seg, next);
+        box = next;
+    }
+    const last = path[path.length - 1];
+    if (value === undefined)
+        delete box[last];
+    else
+        def(box, last, value);
+    return root;
+}
+function tableWith(table, name, value) {
+    const out = {};
+    let placed = false;
+    if (table !== undefined) {
+        for (const k of Object.keys(table)) {
+            if (k === name) {
+                placed = true;
+                if (value !== undefined)
+                    def(out, k, value);
+                continue;
+            }
+            const d = Object.getOwnPropertyDescriptor(table, k);
+            if (d !== undefined)
+                Object.defineProperty(out, k, { ...d, enumerable: true, configurable: true });
+        }
+    }
+    if (!placed && value !== undefined)
+        def(out, name, value);
+    return out;
+}
+const docOf = (fresh, d) => documentOf(fresh[d]);
+function placeOf(scope, projectKey) {
+    if (scope === 'user')
+        return { doc: 'globalConfig', path: USER_SCOPE_PATH };
+    if (scope === 'project')
+        return { doc: 'projectMcp', path: PROJECT_FILE_PATH };
+    return projectKey === undefined ? undefined : { doc: 'globalConfig', path: localScopePath(projectKey) };
+}
+export const mcpRowBaseOf = (revision) => (revision === null ? null : `rev:${revision}`);
+const ADD_KEYS = Object.freeze(['op', 'name', 'entry', 'scope', 'onNameTaken']);
+const UPDATE_KEYS = Object.freeze(['op', 'name', 'scope', 'base', 'set', 'unset', 'env', 'headers', 'keep']);
+const REMOVE_KEYS = Object.freeze(['op', 'name', 'scope']);
+const ENABLE_KEYS = Object.freeze(['op', 'name', 'enabled']);
+const APPROVAL_KEYS = Object.freeze(['op', 'name', 'approval']);
+const IMPORT_KEYS = Object.freeze(['op', 'entries', 'scope']);
+const isScope = (v) => MCP_SERVER_SCOPES.some((s) => s === v);
+function plainData(v, depth = 0) {
+    if (depth > 16)
+        return false;
+    if (v === null || typeof v === 'string' || typeof v === 'boolean' || (typeof v === 'number' && Number.isFinite(v)))
+        return true;
+    if (typeof v !== 'object')
+        return false;
+    try {
+        if (!Array.isArray(v)) {
+            const p = Object.getPrototypeOf(v);
+            if (p !== null && Object.getPrototypeOf(p) !== null)
+                return false;
+        }
+        for (const k of Reflect.ownKeys(v)) {
+            if (typeof k !== 'string')
+                return false;
+            const d = Object.getOwnPropertyDescriptor(v, k);
+            if (d === undefined)
+                continue;
+            if (Array.isArray(v) && k === 'length')
+                continue;
+            if (!Object.hasOwn(d, 'value') || d.enumerable !== true || !plainData(d.value, depth + 1))
+                return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function secretMapOk(v) {
+    if (v === undefined)
+        return true;
+    if (!isRecord(v) || !plainData(v) || Object.keys(v).some((k) => k !== 'set' && k !== 'delete'))
+        return false;
+    const set = own(v, 'set');
+    if (set !== undefined && (!isRecord(set) || Object.keys(set).some((k) => typeof own(set, k) !== 'string')))
+        return false;
+    const del = own(v, 'delete');
+    return del === undefined || stringListOf(del) !== undefined;
+}
+export function shapeMcpServerEdit(v) {
+    try {
+        if (!isRecord(v) || !plainData(v))
+            return { ok: false, path: null };
+        const op = own(v, 'op');
+        const keysOk = (allowed) => Object.keys(v).find((k) => !allowed.includes(k));
+        const name = own(v, 'name');
+        const nameOk = typeof name === 'string';
+        switch (op) {
+            case 'add': {
+                const extra = keysOk(ADD_KEYS);
+                if (extra !== undefined)
+                    return { ok: false, path: extra };
+                if (!nameOk)
+                    return { ok: false, path: 'name' };
+                if (!isRecord(own(v, 'entry')))
+                    return { ok: false, path: 'entry' };
+                if (!isScope(own(v, 'scope')))
+                    return { ok: false, path: 'scope' };
+                const t = own(v, 'onNameTaken');
+                if (t !== undefined && t !== 'refuse' && t !== 'replace' && t !== 'rename')
+                    return { ok: false, path: 'onNameTaken' };
+                return { ok: true, edit: v };
+            }
+            case 'update': {
+                const extra = keysOk(UPDATE_KEYS);
+                if (extra !== undefined)
+                    return { ok: false, path: extra };
+                if (!nameOk)
+                    return { ok: false, path: 'name' };
+                if (!isScope(own(v, 'scope')))
+                    return { ok: false, path: 'scope' };
+                if (typeof own(v, 'base') !== 'string' || own(v, 'base') === '')
+                    return { ok: false, path: 'base' };
+                const set = own(v, 'set');
+                if (set !== undefined && (!isRecord(set) || Object.keys(set).some((k) => k === 'env' || k === 'headers')))
+                    return { ok: false, path: 'set' };
+                const unset = own(v, 'unset');
+                const unsetList = unset === undefined ? [] : stringListOf(unset);
+                if (unsetList === undefined)
+                    return { ok: false, path: 'unset' };
+                if (!secretMapOk(own(v, 'env')))
+                    return { ok: false, path: 'env' };
+                if (!secretMapOk(own(v, 'headers')))
+                    return { ok: false, path: 'headers' };
+                if (unsetList.some((k) => (isRecord(set) && Object.hasOwn(set, k)) || ((k === 'env' || k === 'headers') && own(v, k) !== undefined)))
+                    return { ok: false, path: 'unset' };
+                const keep = own(v, 'keep');
+                if (keep !== undefined && (!isRecord(keep) || typeof own(keep, 'base') !== 'string' || stringListOf(own(keep, 'members')) === undefined || Object.keys(keep).some((k) => k !== 'base' && k !== 'members')))
+                    return { ok: false, path: 'keep' };
+                return { ok: true, edit: v };
+            }
+            case 'remove': {
+                const extra = keysOk(REMOVE_KEYS);
+                if (extra !== undefined)
+                    return { ok: false, path: extra };
+                if (!nameOk)
+                    return { ok: false, path: 'name' };
+                const scope = own(v, 'scope');
+                if (scope !== undefined && !isScope(scope))
+                    return { ok: false, path: 'scope' };
+                return { ok: true, edit: v };
+            }
+            case 'setEnabled': {
+                const extra = keysOk(ENABLE_KEYS);
+                if (extra !== undefined)
+                    return { ok: false, path: extra };
+                if (!nameOk)
+                    return { ok: false, path: 'name' };
+                if (typeof own(v, 'enabled') !== 'boolean')
+                    return { ok: false, path: 'enabled' };
+                return { ok: true, edit: v };
+            }
+            case 'setProjectApproval': {
+                const extra = keysOk(APPROVAL_KEYS);
+                if (extra !== undefined)
+                    return { ok: false, path: extra };
+                if (!nameOk)
+                    return { ok: false, path: 'name' };
+                const a = own(v, 'approval');
+                if (a !== 'approve' && a !== 'reject' && a !== 'clear')
+                    return { ok: false, path: 'approval' };
+                return { ok: true, edit: v };
+            }
+            case 'importFromSibling': {
+                const extra = keysOk(IMPORT_KEYS);
+                if (extra !== undefined)
+                    return { ok: false, path: extra };
+                const entries = own(v, 'entries');
+                if (!isRecord(entries) || Object.keys(entries).length === 0 || Object.keys(entries).length > 256)
+                    return { ok: false, path: 'entries' };
+                if (!isScope(own(v, 'scope')))
+                    return { ok: false, path: 'scope' };
+                return { ok: true, edit: v };
+            }
+            default:
+                return { ok: false, path: 'op' };
+        }
+    }
+    catch {
+        return { ok: false, path: null };
+    }
+}
+const refusedOutcome = (detail, notices = [], plan) => Object.freeze({
+    receipt: Object.freeze({ kind: 'refused', reason: refusalReasonOf(detail.refusal) }),
+    refusal: Object.freeze(detail),
+    ...(plan === undefined ? {} : { plan }),
+    notices: Object.freeze([...notices]),
+});
+function nameRefusal(name, siblings, reserved) {
+    if (reserved.has(name))
+        return { refusal: 'name_reserved', by: 'host' };
+    const v = mcpServerNameVerdict(name, siblings);
+    if (v.usable)
+        return undefined;
+    return v.reason === 'name_reserved' ? { refusal: 'name_reserved', by: 'package' } : { refusal: 'name_unusable', nameReason: v.reason };
+}
+function entryVerdict(name, entry, host, lang) {
+    const table = {};
+    def(table, name, entry);
+    const judged = judgeTable(table, host.env, { expand: true, reserved: new Set(), ...(lang === undefined ? {} : { lang }) });
+    const one = judged?.[0];
+    if (one === undefined)
+        return { ok: false, problems: Object.freeze([]) };
+    if (one.spec !== undefined)
+        return { ok: true, spec: one.spec, missing: one.missing };
+    const nonName = one.problems.filter((p) => !['name_blank', 'name_edge_whitespace', 'name_collides_after_trim', 'name_too_long', 'name_reserved'].includes(p.reason));
+    if (one.missing.length > 0 && nonName.length > 0 && nonName.every((p) => p.reason === 'transport_invalid'))
+        return { ok: true, spec: undefined, missing: one.missing };
+    return { ok: false, problems: nonName.length > 0 ? nonName : one.problems };
+}
+const NAME_N_MAX = 99;
+function policyLockOf(ctx) {
+    const ent = ctx.enterprise;
+    if (isRecord(ent) && (own(ent, 'status') === 'loaded' || own(ent, 'status') === 'unreadable'))
+        return 'enterprise_config';
+    const s = ctx.settings;
+    if (s === undefined || s === 'none')
+        return undefined;
+    try {
+        const read = readHostSettingsOnce(s, 'applyMcpServerEdit');
+        const doc = read.layers.policySettings.doc;
+        const v = doc === null ? undefined : own(doc, 'strictPluginOnlyCustomization');
+        return v === true || (stringListOf(v) ?? []).includes('mcp') ? 'plugin_only' : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function approvalTrust(ctx) {
+    const s = ctx.settings;
+    if (s === undefined || s === 'none')
+        return 'unreadable';
+    try {
+        return readHostSettingsOnce(s, 'applyMcpServerEdit').trust;
+    }
+    catch {
+        return 'unreadable';
+    }
+}
+const targetOf = (e) => JSON.stringify([own(e, 'type') ?? null, own(e, 'command') ?? null, own(e, 'args') ?? null, own(e, 'url') ?? null, own(e, 'headersHelper') ?? null]);
+function maskedArgIndices(args) {
+    const list = stringListOf(args);
+    if (list === undefined)
+        return [];
+    const out = [];
+    for (const f of settingsCredentialKeyPaths({ args: list })) {
+        const m = /^args\[(\d+)\]$/.exec(f.path);
+        if (m !== null)
+            out.push(Number(m[1]));
+    }
+    return out;
+}
+function updatedEntry(old, edit, base) {
+    const next = copyLayer(old);
+    const set = edit.set === undefined ? undefined : edit.set;
+    if (set !== undefined)
+        for (const k of Object.keys(set))
+            def(next, k, own(set, k));
+    const unset = stringListOf(edit.unset) ?? [];
+    for (const k of unset)
+        delete next[k];
+    const carried = { env: [], headers: [], args: [] };
+    for (const key of ['env', 'headers']) {
+        if (unset.includes(key))
+            continue;
+        const m = edit[key];
+        const oldMap = own(old, key);
+        if (m === undefined && !isRecord(oldMap))
+            continue;
+        const map = copyLayer(oldMap);
+        const setM = m?.set;
+        if (setM !== undefined)
+            for (const mk of Object.keys(setM))
+                def(map, mk, own(setM, mk));
+        for (const mk of stringListOf(m?.delete) ?? [])
+            delete map[mk];
+        if (isRecord(oldMap))
+            for (const mk of Object.keys(oldMap))
+                if (Object.hasOwn(map, mk) && (setM === undefined || !Object.hasOwn(setM, mk)))
+                    carried[key].push(mk);
+        if (m !== undefined || isRecord(oldMap))
+            def(next, key, map);
+    }
+    if (!unset.includes('args') && (set === undefined || !Object.hasOwn(set, 'args')))
+        carried.args.push(...maskedArgIndices(own(old, 'args')));
+    if (targetOf(old) !== targetOf(next) && carried.env.length + carried.headers.length + carried.args.length > 0) {
+        const want = [...carried.env.map((n) => `env:${n}`), ...carried.headers.map((n) => `headers:${n}`), ...carried.args.map((i) => `args:${i}`)].sort();
+        const keep = edit.keep;
+        const got = keep === undefined ? undefined : [...(stringListOf(keep.members) ?? [])].sort();
+        if (keep !== undefined && keep.base !== base)
+            return { ok: false, detail: { refusal: 'base_conflict' } };
+        if (got === undefined || JSON.stringify(got) !== JSON.stringify(want))
+            return { ok: false, detail: { refusal: 'credentials_need_reentry', env: Object.freeze(carried.env), headers: Object.freeze(carried.headers), args: Object.freeze(carried.args) } };
+    }
+    return { ok: true, entry: next };
+}
+function editFactsOf(ctx) {
+    const c = isRecord(ctx) ? ctx : { lane: {} };
+    const host = isRecord(c.host) ? c.host : {};
+    return {
+        c,
+        host,
+        reserved: new Set(stringListOf(own(host, 'reservedNames')) ?? []),
+        projectKey: typeof c.projectKey === 'string' && c.projectKey !== '' ? c.projectKey : undefined,
+        lang: c.lang,
+    };
+}
+function scopeGateOf(scope, f) {
+    if (scope === 'local' && f.projectKey === undefined)
+        return { refusal: 'scope_not_offered', scope, why: 'no_project_key' };
+    if (scope === 'project' && own(f.host, 'projectConfigRootSet') === true)
+        return { refusal: 'scope_not_offered', scope, why: 'project_config_root' };
+    return undefined;
+}
+function preGatesOf(e, f) {
+    if (e.op === 'add' || e.op === 'update' || e.op === 'importFromSibling') {
+        const lock = policyLockOf(f.c);
+        if (lock !== undefined)
+            return { ok: false, detail: { refusal: 'policy_locked', by: lock } };
+        const gate = scopeGateOf(e.scope, f);
+        if (gate !== undefined)
+            return { ok: false, detail: gate };
+    }
+    if (e.op === 'setEnabled' && f.projectKey === undefined)
+        return { ok: false, detail: { refusal: 'scope_not_offered', scope: 'local', why: 'no_project_key' } };
+    if (e.op === 'add') {
+        const nr = nameRefusal(e.name, [], f.reserved);
+        if (nr !== undefined)
+            return { ok: false, detail: nr };
+        const ev = entryVerdict(e.name, e.entry, f.host, f.lang);
+        if (!ev.ok)
+            return { ok: false, detail: { refusal: 'mcp_entry_invalid', problems: ev.problems } };
+        return { ok: true, entry: { spec: ev.spec, missing: ev.missing } };
+    }
+    if (e.op === 'importFromSibling') {
+        const good = [];
+        const skipped = [];
+        const problems = [];
+        for (const name of Object.keys(e.entries)) {
+            const raw = own(e.entries, name);
+            const nr = nameRefusal(name, [], f.reserved);
+            if (nr !== undefined) {
+                skipped.push({ name, reason: nr.refusal });
+                continue;
+            }
+            const ev = entryVerdict(name, raw, f.host, f.lang);
+            if (!ev.ok) {
+                skipped.push({ name, reason: 'mcp_entry_invalid' });
+                problems.push(...ev.problems);
+                continue;
+            }
+            good.push({ name, entry: copyLayer(raw) });
+        }
+        if (good.length === 0)
+            return { ok: false, detail: { refusal: 'mcp_entry_invalid', problems: Object.freeze(problems) }, plan: { op: 'importFromSibling', name: '', scope: e.scope, imported: Object.freeze([]), skipped: Object.freeze(skipped) } };
+        return { ok: true, good, skipped };
+    }
+    return { ok: true };
+}
+const entryProbeOf = (spec) => (spec !== undefined ? { kind: 'spec', spec } : { kind: 'none', why: 'env_missing' });
+function fixedProbeOf(e) {
+    if (e.op === 'remove')
+        return { kind: 'none', why: 'removed' };
+    if (e.op === 'setEnabled')
+        return { kind: 'none', why: e.enabled ? 'not_active' : 'removed' };
+    return { kind: 'none', why: 'not_active' };
+}
+function updateVerdictOn(r, path, e, f) {
+    const cur = documentOf(r);
+    const t = subTableOf(cur, path);
+    if (t.kind === 'bad')
+        return { ok: false, detail: { refusal: 'scope_unreadable' } };
+    const old = t.kind === 'table' ? own(t.table, e.name) : undefined;
+    if (!isRecord(old))
+        return { ok: false, detail: { refusal: 'not_found' } };
+    const base = mcpRowBaseOf(r !== undefined && r.status === 'loaded' ? r.revision : null);
+    if (base === null || base !== e.base)
+        return { ok: false, detail: { refusal: 'base_conflict' } };
+    const u = updatedEntry(old, e, base);
+    if (!u.ok)
+        return { ok: false, detail: u.detail };
+    const ev = entryVerdict(e.name, u.entry, f.host, f.lang);
+    if (!ev.ok)
+        return { ok: false, detail: { refusal: 'mcp_entry_invalid', problems: ev.problems } };
+    return { ok: true, cur, table: t.kind === 'table' ? t.table : undefined, entry: u.entry, probe: entryProbeOf(ev.spec) };
+}
+async function snapshotOrUndefined(store) {
+    try {
+        const raw = await store.read(Object.freeze(['globalConfig', 'projectMcp']));
+        const holder = isRecord(raw) ? raw : {};
+        return Object.freeze({ globalConfig: fileReadingOf(holder, 'globalConfig', 'unreadable'), projectMcp: fileReadingOf(holder, 'projectMcp', 'unreadable') });
+    }
+    catch {
+        return undefined;
+    }
+}
+async function noticesFor(name, scope, entry, store, ctx, missing) {
+    const out = [];
+    const fresh = await snapshotOrUndefined(store);
+    if (fresh !== undefined) {
+        const rank = { user: 0, project: 1, local: 2 };
+        for (const s of MCP_SERVER_SCOPES) {
+            if (s === scope)
+                continue;
+            const place = placeOf(s, ctx.projectKey);
+            if (place === undefined)
+                continue;
+            const t = subTableOf(docOf(fresh, place.doc), place.path);
+            if (t.kind !== 'table')
+                continue;
+            const other = own(t.table, name);
+            if (other === undefined)
+                continue;
+            if (rank[s] > rank[scope])
+                out.push({ kind: 'shadowed_by', scope: s });
+            if (JSON.stringify([own(other, 'command') ?? null, own(other, 'url') ?? null]) !== JSON.stringify([own(entry, 'command') ?? null, own(entry, 'url') ?? null]))
+                out.push({ kind: 'endpoint_differs', scope: s });
+        }
+    }
+    const dep = ctx.host === undefined ? undefined : stringListOf(own(ctx.host, 'deploymentNames'));
+    if (dep !== undefined && dep.includes(name))
+        out.push({ kind: 'deployment_wins' });
+    if (missing.length > 0)
+        out.push({ kind: 'env_missing', names: Object.freeze([...missing]) });
+    return out;
+}
+export async function applyMcpServerEdit(edit, store, ctx, opts) {
+    try {
+        const shaped = shapeMcpServerEdit(edit);
+        if (!shaped.ok)
+            return refusedOutcome({ refusal: 'edit_malformed', path: shaped.path });
+        const e = shaped.edit;
+        const f = editFactsOf(ctx);
+        const { c, host, reserved, projectKey } = f;
+        const dry = isRecord(opts) && opts.dryRun === true;
+        const docsFor = () => {
+            if (e.op === 'setEnabled')
+                return ['globalConfig'];
+            if (e.op === 'setProjectApproval')
+                return ['localSettings'];
+            if (e.op === 'remove' && e.scope === undefined)
+                return ['globalConfig', 'projectMcp'];
+            if (e.op === 'add' && e.onNameTaken === 'rename')
+                return ['globalConfig', 'projectMcp'];
+            if (e.op === 'importFromSibling')
+                return ['globalConfig', 'projectMcp'];
+            return [e.scope === 'project' ? 'projectMcp' : 'globalConfig'];
+        };
+        const access = localConfigAccess(c.lane, { access: 'write', docs: docsFor() });
+        if (!access.ok)
+            return Object.freeze({ receipt: Object.freeze({ kind: 'unavailable', cause: access.cause }), notices: Object.freeze([]) });
+        const pre = preGatesOf(e, f);
+        if (!pre.ok)
+            return refusedOutcome(pre.detail, [], pre.plan);
+        const box = {};
+        const refuse = (d) => {
+            box.captured = d;
+            return { kind: 'refuse', reason: refusalReasonOf(d.refusal) };
+        };
+        let step;
+        let notices = [];
+        if (e.op === 'add') {
+            const ev = pre.entry;
+            notices = await noticesFor(e.name, e.scope, e.entry, store, c, ev.missing);
+            box.probe = entryProbeOf(ev.spec);
+            const place = placeOf(e.scope, projectKey);
+            const otherDoc = place.doc === 'globalConfig' ? 'projectMcp' : 'globalConfig';
+            const mode = e.onNameTaken ?? 'refuse';
+            const entryCopy = copyLayer(e.entry);
+            step = {
+                doc: place.doc,
+                role: 'effect',
+                ...(mode === 'rename' ? { lock: [otherDoc] } : {}),
+                plan: ({ fresh }) => {
+                    const cur = docOf(fresh, place.doc);
+                    const t = subTableOf(cur, place.path);
+                    if (t.kind === 'bad')
+                        return refuse({ refusal: 'scope_unreadable' });
+                    const table = t.kind === 'table' ? t.table : undefined;
+                    const siblings = table === undefined ? [] : Object.keys(table).filter((k) => k !== e.name);
+                    const sib = nameRefusal(e.name, siblings, reserved);
+                    if (sib !== undefined)
+                        return refuse(sib);
+                    let name = e.name;
+                    let replaced = false;
+                    if (table !== undefined && Object.hasOwn(table, e.name)) {
+                        if (mode === 'refuse')
+                            return refuse({ refusal: 'name_taken', scope: e.scope, exhausted: false });
+                        if (mode === 'replace')
+                            replaced = true;
+                        else {
+                            const taken = new Set();
+                            for (const s of MCP_SERVER_SCOPES) {
+                                const p = placeOf(s, projectKey);
+                                if (p === undefined)
+                                    continue;
+                                const tt = subTableOf(docOf(fresh, p.doc), p.path);
+                                if (tt.kind === 'table')
+                                    for (const k of Object.keys(tt.table))
+                                        taken.add(k);
+                            }
+                            let found;
+                            for (let n = 1; n <= NAME_N_MAX && found === undefined; n++) {
+                                const cand = `${e.name}_${n}`;
+                                if (!taken.has(cand) && nameRefusal(cand, siblings, reserved) === undefined)
+                                    found = cand;
+                            }
+                            if (found === undefined)
+                                return refuse({ refusal: 'name_taken', scope: e.scope, exhausted: true });
+                            name = found;
+                        }
+                    }
+                    const next = withPath(cur, place.path, tableWith(table, name, entryCopy));
+                    if (next === undefined)
+                        return refuse({ refusal: 'scope_unreadable' });
+                    box.plan = { op: 'add', name, scope: e.scope, ...(name !== e.name ? { renamedFrom: e.name } : {}), ...(replaced ? { replaced: true } : {}) };
+                    return { kind: 'write', next };
+                },
+            };
+        }
+        else if (e.op === 'update') {
+            const place = placeOf(e.scope, projectKey);
+            step = {
+                doc: place.doc,
+                role: 'effect',
+                plan: ({ fresh }) => {
+                    const v = updateVerdictOn(fresh[place.doc], place.path, e, f);
+                    if (!v.ok)
+                        return refuse(v.detail);
+                    box.probe = v.probe;
+                    const next = withPath(v.cur, place.path, tableWith(v.table, e.name, v.entry));
+                    if (next === undefined)
+                        return refuse({ refusal: 'scope_unreadable' });
+                    box.plan = { op: 'update', name: e.name, scope: e.scope };
+                    return { kind: 'write', next };
+                },
+            };
+        }
+        else if (e.op === 'remove') {
+            box.probe = fixedProbeOf(e);
+            const candidatesIn = (fresh) => {
+                const scopes = [];
+                let unreadable = false;
+                for (const s of ['local', 'project', 'user']) {
+                    const p = placeOf(s, projectKey);
+                    if (p === undefined)
+                        continue;
+                    const t = subTableOf(docOf(fresh, p.doc), p.path);
+                    if (t.kind === 'bad')
+                        unreadable = true;
+                    else if (t.kind === 'table' && Object.hasOwn(t.table, e.name))
+                        scopes.push(s);
+                }
+                return { scopes, unreadable };
+            };
+            let scope = e.scope;
+            if (scope === undefined) {
+                const snap = await snapshotOrUndefined(store);
+                if (snap === undefined)
+                    return refusedOutcome({ refusal: 'scope_unreadable' });
+                const cand = candidatesIn(snap);
+                if (cand.unreadable)
+                    return refusedOutcome({ refusal: 'scope_unreadable' });
+                if (cand.scopes.length === 0)
+                    return refusedOutcome({ refusal: 'not_found' });
+                if (cand.scopes.length > 1)
+                    return refusedOutcome({ refusal: 'ambiguous_scope', scopes: Object.freeze(cand.scopes) });
+                scope = cand.scopes[0];
+            }
+            const target = scope;
+            const gate = scopeGateOf(target, f);
+            if (gate !== undefined)
+                return refusedOutcome(gate);
+            const place = placeOf(target, projectKey);
+            const unscoped = e.scope === undefined;
+            step = {
+                doc: place.doc,
+                role: 'effect',
+                ...(unscoped ? { lock: [place.doc === 'globalConfig' ? 'projectMcp' : 'globalConfig'] } : {}),
+                plan: ({ fresh }) => {
+                    if (unscoped) {
+                        const cand = candidatesIn(fresh);
+                        if (cand.unreadable)
+                            return refuse({ refusal: 'scope_unreadable' });
+                        if (cand.scopes.length > 1)
+                            return refuse({ refusal: 'ambiguous_scope', scopes: Object.freeze(cand.scopes) });
+                        if (cand.scopes.length === 0)
+                            return refuse({ refusal: 'not_found' });
+                        const inLock = scopeGateOf(cand.scopes[0], f);
+                        if (inLock !== undefined)
+                            return refuse(inLock);
+                        if (cand.scopes[0] !== target)
+                            return refuse({ refusal: 'base_conflict' });
+                    }
+                    const cur = docOf(fresh, place.doc);
+                    const t = subTableOf(cur, place.path);
+                    if (t.kind === 'bad')
+                        return refuse({ refusal: 'scope_unreadable' });
+                    if (t.kind !== 'table' || !Object.hasOwn(t.table, e.name))
+                        return refuse({ refusal: 'not_found' });
+                    const next = withPath(cur, place.path, tableWith(t.table, e.name, undefined));
+                    if (next === undefined)
+                        return refuse({ refusal: 'scope_unreadable' });
+                    box.plan = { op: 'remove', name: e.name, scope: target };
+                    return { kind: 'write', next };
+                },
+            };
+        }
+        else if (e.op === 'setEnabled') {
+            const defaultOff = new Set(stringListOf(own(host, 'defaultOffNames')) ?? []);
+            box.probe = fixedProbeOf(e);
+            const projPath = ['projects', projectKey];
+            step = {
+                doc: 'globalConfig',
+                role: 'effect',
+                plan: ({ fresh }) => {
+                    const cur = docOf(fresh, 'globalConfig');
+                    const t = subTableOf(cur, projPath);
+                    if (t.kind === 'bad')
+                        return refuse({ refusal: 'scope_unreadable' });
+                    const entry = t.kind === 'table' ? t.table : undefined;
+                    const listAt = (k) => {
+                        const r = nameListOf(entry, k);
+                        return r.kind === 'absent' ? [] : r.kind === 'list' ? [...r.list] : undefined;
+                    };
+                    const disabled = listAt('disabledMcpServers');
+                    const enabled = listAt('enabledMcpServers');
+                    if (disabled === undefined || enabled === undefined)
+                        return refuse({ refusal: 'scope_unreadable' });
+                    let nextEntry = copyLayer(entry);
+                    const put = (k, list, had) => {
+                        if (list.length === 0 && !had)
+                            return;
+                        def(nextEntry, k, list);
+                    };
+                    const hadD = entry !== undefined && Object.hasOwn(entry, 'disabledMcpServers');
+                    const hadE = entry !== undefined && Object.hasOwn(entry, 'enabledMcpServers');
+                    if (e.enabled) {
+                        put('disabledMcpServers', disabled.filter((n) => n !== e.name), hadD);
+                        if (defaultOff.has(e.name))
+                            put('enabledMcpServers', enabled.includes(e.name) ? enabled : [...enabled, e.name], hadE);
+                    }
+                    else {
+                        put('disabledMcpServers', disabled.includes(e.name) ? disabled : [...disabled, e.name], hadD);
+                        if (hadE)
+                            put('enabledMcpServers', enabled.filter((n) => n !== e.name), hadE);
+                    }
+                    if (entry === undefined && Object.keys(nextEntry).length === 0)
+                        nextEntry = {};
+                    const next = withPath(cur, projPath, nextEntry);
+                    if (next === undefined)
+                        return refuse({ refusal: 'scope_unreadable' });
+                    box.plan = { op: 'setEnabled', name: e.name };
+                    return { kind: 'write', next };
+                },
+            };
+        }
+        else if (e.op === 'setProjectApproval') {
+            box.probe = fixedProbeOf(e);
+            const WANT = { approve: ['set', 'delete'], reject: ['delete', 'set'], clear: ['delete', 'delete'] };
+            const want = WANT[e.approval];
+            const edit1 = (intent, op) => (op === 'set' ? { intent, member: e.name, op, value: e.name } : { intent, member: e.name, op });
+            const inner = settingsWriteStep({ doc: 'localSettings', trust: approvalTrust(c), edits: [edit1('mcpJsonEnabled', want[0]), edit1('mcpJsonDisabled', want[1])] });
+            step = {
+                ...inner,
+                plan: (input) => {
+                    const out = inner.plan(input);
+                    if (out.kind === 'refuse' && out.reason === 'untrusted_folder')
+                        box.captured = { refusal: 'untrusted_folder' };
+                    else if (out.kind === 'refuse' && out.reason === 'scope_unwritable')
+                        box.captured = { refusal: 'scope_not_offered', scope: 'local', why: 'layer_not_admitted' };
+                    if (out.kind !== 'refuse')
+                        box.plan = { op: 'setProjectApproval', name: e.name };
+                    return out;
+                },
+            };
+        }
+        else {
+            const place = placeOf(e.scope, projectKey);
+            const good = pre.good ?? [];
+            const skipped = pre.skipped ?? [];
+            box.probe = fixedProbeOf(e);
+            step = {
+                doc: place.doc,
+                role: 'effect',
+                lock: [place.doc === 'globalConfig' ? 'projectMcp' : 'globalConfig'],
+                plan: ({ fresh }) => {
+                    const cur = docOf(fresh, place.doc);
+                    const t = subTableOf(cur, place.path);
+                    if (t.kind === 'bad')
+                        return refuse({ refusal: 'scope_unreadable' });
+                    const taken = new Set();
+                    for (const s of MCP_SERVER_SCOPES) {
+                        const p = placeOf(s, projectKey);
+                        if (p === undefined)
+                            continue;
+                        const tt = subTableOf(docOf(fresh, p.doc), p.path);
+                        if (tt.kind === 'table')
+                            for (const k of Object.keys(tt.table))
+                                taken.add(k);
+                    }
+                    let table = t.kind === 'table' ? copyLayer(t.table) : undefined;
+                    const imported = [];
+                    const skippedHere = [...skipped];
+                    for (const g of good) {
+                        let name = g.name;
+                        if (taken.has(name)) {
+                            let found;
+                            for (let n = 1; n <= NAME_N_MAX && found === undefined; n++) {
+                                const cand = `${g.name}_${n}`;
+                                if (!taken.has(cand) && nameRefusal(cand, [], reserved) === undefined)
+                                    found = cand;
+                            }
+                            if (found === undefined) {
+                                skippedHere.push({ name: g.name, reason: 'name_taken' });
+                                continue;
+                            }
+                            name = found;
+                        }
+                        taken.add(name);
+                        table = tableWith(table, name, g.entry);
+                        imported.push(name === g.name ? { name } : { name, renamedFrom: g.name });
+                    }
+                    if (imported.length === 0)
+                        return refuse({ refusal: 'name_taken', scope: e.scope, exhausted: true });
+                    const next = withPath(cur, place.path, table);
+                    if (next === undefined)
+                        return refuse({ refusal: 'scope_unreadable' });
+                    box.plan = { op: 'importFromSibling', name: imported[0].name, scope: e.scope, imported: Object.freeze(imported), skipped: Object.freeze(skippedHere) };
+                    return { kind: 'write', next };
+                },
+            };
+        }
+        const intent = Object.freeze({ appliesOn: 'next_turn', steps: Object.freeze([Object.freeze(step)]) });
+        const receipt = dry ? await previewLocalConfigIntent(intent, store, c.lane) : await applyLocalConfigIntent(intent, store, c.lane);
+        const captured = box.captured;
+        const planOut = box.plan;
+        let probe = box.probe;
+        const refusal = receipt.kind === 'refused' && captured !== undefined && refusalReasonOf(captured.refusal) === receipt.reason ? captured : undefined;
+        if (receipt.kind === 'refused' && probe !== undefined && probe.kind === 'spec')
+            probe = { kind: 'none', why: 'edit_refused' };
+        return Object.freeze({
+            receipt,
+            ...(refusal === undefined ? {} : { refusal: Object.freeze(refusal) }),
+            ...(planOut === undefined || receipt.kind === 'refused' || receipt.kind === 'unavailable' ? {} : { plan: Object.freeze(planOut) }),
+            notices: Object.freeze(notices),
+            ...(dry && probe !== undefined ? { probe: Object.freeze(probe) } : {}),
+        });
+    }
+    catch {
+        return Object.freeze({ receipt: Object.freeze({ kind: 'refused', reason: 'invalid_request' }), notices: Object.freeze([]) });
+    }
+}
+export async function mcpServerProbeTargetOf(edit, store, ctx) {
+    const refused = { kind: 'refused' };
+    try {
+        const f = editFactsOf(ctx);
+        const access = localConfigAccess(f.c.lane, { access: 'read' });
+        if (!access.ok)
+            return Object.freeze({ kind: 'unavailable', cause: access.cause });
+        const shaped = shapeMcpServerEdit(edit);
+        if (!shaped.ok)
+            return refused;
+        const e = shaped.edit;
+        const pre = preGatesOf(e, f);
+        if (!pre.ok)
+            return refused;
+        if (e.op === 'add')
+            return Object.freeze(entryProbeOf(pre.entry?.spec));
+        if (e.op === 'update') {
+            const place = placeOf(e.scope, f.projectKey);
+            const snap = await snapshotOrUndefined(store);
+            if (snap === undefined)
+                return refused;
+            const v = updateVerdictOn(snap[place.doc], place.path, e, f);
+            return v.ok ? Object.freeze(v.probe) : refused;
+        }
+        if (e.op === 'remove' && e.scope !== undefined && scopeGateOf(e.scope, f) !== undefined)
+            return refused;
+        return Object.freeze(fixedProbeOf(e));
+    }
+    catch {
+        return refused;
+    }
+}