@uniqbit/mate-core 0.17.0-canary.8 → 0.17.1

package/src/tools/setup/dynamic-plugins/hydrate.ts

@@ -1,16 +1,13 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { parse } from "yaml";
-
 import { getActiveDistribution } from "../../../distribution";
 import { FRAMEWORK_NAME } from "../../../framework";
 import { CompanionResolver } from "../../../lib/orchestrator/companion-resolver";
 import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
-import { PLUGIN_DECLARATION_POLICIES } from "../../../lib/orchestrator/config-store";
-import type { PluginDeclaration } from "../../../lib/orchestrator/types";
 import type { Plugin } from "../plugin";
 import type { PluginRegistry } from "../registry";
+import { readDeclarations, validateDeclaration } from "./declarations";
 import { loadDynamicPlugin, type DynamicPluginLoadDeps } from "./loader";
 
 // Packages already registered in this process; re-hydration (e.g. right after
@@ -29,10 +26,6 @@ export interface HydrateDynamicPluginsDeps extends DynamicPluginLoadDeps {
   warn?: (message: string) => void;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /**
  * Quiet variant of companion resolution: never prompts, never errors. An
  * ambiguous or absent companion means hydration is a no-op —
@@ -58,38 +51,6 @@ async function resolveCompanionQuietly(
   }
 }
 
-/**
- * Raw read of the companion's `plugins:` list. Deliberately avoids
- * `ConfigStore.load()` — hydration runs on every invocation and must never
- * create or migrate config files as a side effect.
- */
-async function readDeclarations(companionPath: string): Promise<unknown[]> {
-  try {
-    const raw = await fs.readFile(
-      path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
-      "utf8",
-    );
-    const parsed = parse(raw) as unknown;
-    if (!isRecord(parsed) || !Array.isArray(parsed.plugins)) return [];
-    return parsed.plugins;
-  } catch {
-    return [];
-  }
-}
-
-function validateDeclaration(entry: unknown): { declaration?: PluginDeclaration; error?: string } {
-  if (!isRecord(entry) || typeof entry.package !== "string" || typeof entry.version !== "string") {
-    return { error: `ignoring malformed plugins entry: ${JSON.stringify(entry)}` };
-  }
-  const policy = entry.policy;
-  if (policy !== undefined && !PLUGIN_DECLARATION_POLICIES.includes(policy as never)) {
-    return {
-      error: `plugin "${entry.package}": policy "${String(policy)}" is not allowed for declared plugins (allowed: ${PLUGIN_DECLARATION_POLICIES.join(", ")}).`,
-    };
-  }
-  return { declaration: entry as unknown as PluginDeclaration };
-}
-
 /**
  * A framework declaration is the activation switch for a dynamic plugin.
  * Own-property override rather than a spread: class-instance plugins keep

package/src/tools/setup/dynamic-plugins/loader.ts

@@ -14,6 +14,12 @@ import {
   type PluginHost,
 } from "./host";
 import { dynamicPluginsWorkspaceRoot, pluginPackageRoot } from "./paths";
+import {
+  disallowedPluginMessage,
+  isPluginAllowed,
+  PluginPolicyError,
+  readPluginPolicy,
+} from "./policy";
 
 interface PluginManifest {
   mate?: { pluginApiVersion?: unknown };
@@ -47,6 +53,16 @@ export async function loadDynamicPlugin(
   const name = declaration.package;
   const packageRoot = pluginPackageRoot(companionPath, name);
 
+  /** Fails closed: a malformed policy allows nothing. Checked before any plugin file is touched. */
+  try {
+    if (!isPluginAllowed(readPluginPolicy(deps.env ?? process.env), name)) {
+      return { ok: false, warning: `${disallowedPluginMessage(name)}; not loaded.` };
+    }
+  } catch (error) {
+    if (!(error instanceof PluginPolicyError)) throw error;
+    return { ok: false, warning: `plugin "${name}" not loaded: ${error.message}` };
+  }
+
   let manifest: PluginManifest;
   try {
     manifest = JSON.parse(

package/src/tools/setup/dynamic-plugins/policy.ts

@@ -0,0 +1,55 @@
+/** Environment variable carrying the appliance's declared-plugin package allowlist. */
+export const ALLOWED_PLUGINS_ENV = "MATE_ALLOWED_PLUGINS";
+
+/**
+ * Parsed allowlist: exact package names and scope-wide `@scope/*` patterns.
+ * An empty list permits no package; the policy's absence permits all.
+ */
+export interface PluginPolicy {
+  exact: string[];
+  scopes: string[];
+}
+
+export class PluginPolicyError extends Error {}
+
+const EXACT_PATTERN = /^(@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+const SCOPE_PATTERN = /^@[a-z0-9][a-z0-9._~-]*\/\*$/;
+
+/**
+ * Parses a comma-separated allowlist. `undefined` means no policy; an empty
+ * or blank string is an explicit empty policy. Malformed entries throw so a
+ * typo can never widen or silently narrow the trust decision.
+ */
+export function parseAllowedPlugins(raw: string | undefined): PluginPolicy | null {
+  if (raw === undefined) return null;
+  const policy: PluginPolicy = { exact: [], scopes: [] };
+  if (raw.trim() === "") return policy;
+  for (const part of raw.split(",")) {
+    const entry = part.trim();
+    if (SCOPE_PATTERN.test(entry)) policy.scopes.push(entry.slice(0, entry.indexOf("/") + 1));
+    else if (EXACT_PATTERN.test(entry)) policy.exact.push(entry);
+    else {
+      throw new PluginPolicyError(
+        `${ALLOWED_PLUGINS_ENV}: malformed entry ${JSON.stringify(entry)}; expected an exact package name or a scope pattern such as "@acme/*"`,
+      );
+    }
+  }
+  return policy;
+}
+
+/** Reads the effective policy from an environment; throws on a malformed value. */
+export function readPluginPolicy(
+  env: Record<string, string | undefined> = process.env,
+): PluginPolicy | null {
+  return parseAllowedPlugins(env[ALLOWED_PLUGINS_ENV]);
+}
+
+export function isPluginAllowed(policy: PluginPolicy | null, packageName: string): boolean {
+  if (policy === null) return true;
+  if (policy.exact.includes(packageName)) return true;
+  return policy.scopes.some((scope) => packageName.startsWith(scope));
+}
+
+export function disallowedPluginMessage(packageName: string): string {
+  return `plugin "${packageName}" is not allowed by ${ALLOWED_PLUGINS_ENV}`;
+}

package/src/tools/setup/dynamic-plugins/staging.ts

@@ -0,0 +1,53 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+export class TrackedOutputError extends Error {}
+
+export type StagedProjection = (stagingPath: string) => Promise<void>;
+
+function git(cwd: string, args: string[]): string {
+  const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+  if (result.error || result.status !== 0) {
+    throw new TrackedOutputError(
+      `git ${args[0]} failed in ${cwd}: ${result.error?.message ?? result.stderr?.trim() ?? result.status}`,
+    );
+  }
+  return result.stdout;
+}
+
+function changedPaths(cwd: string): string[] {
+  return git(cwd, ["status", "--porcelain", "--untracked-files=all"])
+    .split("\n")
+    .filter((line) => line.trim() !== "")
+    .map((line) => line.slice(3));
+}
+
+/**
+ * Checks that what plugins would generate is already committed. The live
+ * checkout must have no edits of its own; the projection then runs against a
+ * disposable clone of its commit, and any file that differs afterwards is
+ * drift. Nothing is written back to the live checkout. Returns the drifting
+ * paths (empty when the checkout is complete).
+ */
+export async function verifyTrackedPluginOutputs(
+  companionPath: string,
+  project: StagedProjection,
+): Promise<string[]> {
+  const pending = changedPaths(companionPath);
+  if (pending.length > 0) {
+    throw new TrackedOutputError(
+      `the checkout has uncommitted changes, which frozen setup will not overwrite: ${pending.join(", ")}`,
+    );
+  }
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "mate-staging-"));
+  try {
+    const staged = path.join(root, "companion");
+    git(root, ["clone", "--quiet", "--no-hardlinks", companionPath, staged]);
+    await project(staged);
+    return changedPaths(staged);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+}

package/src/tools/setup/dynamic-plugins/verify.ts

@@ -0,0 +1,70 @@
+import fs from "node:fs/promises";
+
+import { FRAMEWORK_NAME } from "../../../framework";
+import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import { readDeclarations, validateDeclaration } from "./declarations";
+import { loadDynamicPlugin, type DynamicPluginLoadDeps } from "./loader";
+import { pluginPackageRoot } from "./paths";
+import {
+  disallowedPluginMessage,
+  isPluginAllowed,
+  PluginPolicyError,
+  readPluginPolicy,
+} from "./policy";
+
+export interface PluginVerificationFailure {
+  package: string;
+  reason: string;
+}
+
+/**
+ * Strict, installation-free check of every declared plugin: allowed, installed
+ * and loadable with the effective environment. Unlike hydration it fails
+ * closed on the first-class problems ordinary commands only warn about. Only
+ * allowlisted packages are imported.
+ */
+export async function verifyDeclaredPlugins(
+  companionPath: string,
+  deps: DynamicPluginLoadDeps = {},
+): Promise<PluginVerificationFailure[]> {
+  const env = deps.env ?? process.env;
+  const failures: PluginVerificationFailure[] = [];
+  let policy: ReturnType<typeof readPluginPolicy>;
+  try {
+    policy = readPluginPolicy(env);
+  } catch (error) {
+    if (!(error instanceof PluginPolicyError)) throw error;
+    return [{ package: "(allowlist)", reason: error.message }];
+  }
+
+  const declarations: PluginDeclaration[] = [];
+  for (const entry of await readDeclarations(companionPath)) {
+    const { declaration, error } = validateDeclaration(entry);
+    if (declaration) declarations.push(declaration);
+    else failures.push({ package: "(malformed entry)", reason: error ?? "invalid plugins entry" });
+  }
+
+  for (const declaration of declarations) {
+    const name = declaration.package;
+    if (!isPluginAllowed(policy, name)) {
+      failures.push({ package: name, reason: disallowedPluginMessage(name) });
+      continue;
+    }
+    // oxlint-disable-next-line no-await-in-loop -- declared order is part of the contract
+    const installed = await fs
+      .access(pluginPackageRoot(companionPath, name))
+      .then(() => true)
+      .catch(() => false);
+    if (!installed) {
+      failures.push({
+        package: name,
+        reason: `not installed; run setup (\`${FRAMEWORK_NAME} install --yes --frozen-plugins\`) to install it`,
+      });
+      continue;
+    }
+    // oxlint-disable-next-line no-await-in-loop -- declared order is part of the contract
+    const result = await loadDynamicPlugin(companionPath, declaration, { ...deps, env });
+    if (!result.ok) failures.push({ package: name, reason: result.warning });
+  }
+  return failures;
+}

package/src/tools/setup/mate.ts

@@ -92,7 +92,7 @@ The default path writes self-contained HTML to a unique OS temporary directory a
 The built-in \`mate report\` path collects Mate usage data and adapts it to the same contract and renderer.
 `;
 
-export async function deployMateSkillDir(src: string, dest: string): Promise<void> {
+async function deployMateSkillDir(src: string, dest: string): Promise<void> {
   await fs.mkdir(dest, { recursive: true });
   const entries = await fs.readdir(src, { withFileTypes: true });
   for (const entry of entries) {

package/src/tools/setup/providers/claude-format.ts

@@ -87,7 +87,7 @@ export function filterClaudeHookGroups(
 // Claude plugin, and the retired mate-artifact-finish.sh archive hook is gone
 // entirely; their markers are retained migration-only so stale managed groups
 // written by earlier releases keep being stripped, and are never re-added.
-export const MANAGED_HOOK_MARKERS = [
+const MANAGED_HOOK_MARKERS = [
   "validate-artifact-path",
   "mate-session-banner",
   "react-doctor.sh",

package/src/tools/setup/providers/claude.ts

@@ -151,7 +151,7 @@ export function renderManagedClaudeMcpServers(
 // servers) on top of whatever already exists in the settings document. Managed
 // groups/entries always lead their arrays so the emitted shape stays stable
 // across syncs; unmanaged content is preserved untouched.
-export function renderManagedClaudeSettings(
+function renderManagedClaudeSettings(
   existing: ClaudeSettings,
   companionPath: string,
   config: FrameworkConfig,

package/src/tools/setup/providers/opencode-format.ts

@@ -3,10 +3,9 @@ import path from "node:path";
 
 import type { McpEntryDescriptor } from "./claude-format";
 
-// OpenCode runtime config format primitives: parse/serialize for
-// `opencode.json`/`tui.json`, plugin-reference array handling, and MCP entry
-// shapes. This module owns the file formats only — which entries are
-// Mate-managed is the callers' (Runtime Surface) knowledge.
+// OpenCode V2 config format primitives, plus the one-time V1-to-V2 normalization
+// used while reconciling an existing companion config. This module owns file
+// formats only — which entries are Mate-managed is the callers' knowledge.
 
 export type OpenCodeConfig = Record<string, unknown>;
 
@@ -38,21 +37,214 @@ export async function writeOpenCodeConfig(
 }
 
 export function getOpenCodePluginReferences(config: OpenCodeConfig): unknown[] {
-  return Array.isArray(config.plugin) ? config.plugin : [];
+  return [
+    ...(Array.isArray(config.plugin) ? config.plugin : []),
+    ...(Array.isArray(config.plugins) ? config.plugins : []),
+  ];
 }
 
-/** Replace the plugin array in place; an empty list removes the key. */
+function normalizePluginReference(reference: unknown): unknown {
+  if (Array.isArray(reference) && typeof reference[0] === "string" && isRecord(reference[1])) {
+    return { package: reference[0], options: reference[1] };
+  }
+  return reference;
+}
+
+/** Replace plugin references using the V2 key; an empty list removes it. */
 export function setOpenCodePluginReferences(config: OpenCodeConfig, references: unknown[]): void {
+  delete config.plugin;
   if (references.length === 0) {
-    delete config.plugin;
+    delete config.plugins;
     return;
   }
-  config.plugin = references;
+  config.plugins = references.map(normalizePluginReference);
+}
+
+/** V2 splits one V1 timeout into separate catalog and execution budgets. */
+function splitMcpTimeout(timeout: number): { catalog: number; execution: number } {
+  return { catalog: timeout, execution: timeout };
+}
+
+function normalizeMcpEntry(value: unknown): unknown {
+  if (!isRecord(value)) return value;
+
+  const entry = { ...value };
+  if (typeof entry.enabled === "boolean") {
+    if (entry.disabled === undefined) entry.disabled = !entry.enabled;
+    delete entry.enabled;
+  }
+  if (typeof entry.timeout === "number") {
+    entry.timeout = splitMcpTimeout(entry.timeout);
+  }
+  for (const [legacy, current] of [
+    ["clientId", "client_id"],
+    ["clientSecret", "client_secret"],
+    ["callbackPort", "callback_port"],
+    ["redirectUri", "redirect_uri"],
+  ] as const) {
+    if (entry[legacy] !== undefined) {
+      if (entry[current] === undefined) entry[current] = entry[legacy];
+      delete entry[legacy];
+    }
+  }
+  return entry;
+}
+
+const LEGACY_PERMISSION_ACTIONS: Record<string, string> = {
+  bash: "shell",
+  task: "subagent",
+  write: "edit",
+  patch: "edit",
+};
+
+function permissionAction(legacyAction: string): string {
+  return LEGACY_PERMISSION_ACTIONS[legacyAction] ?? legacyAction;
+}
+
+function appendPermissionRules(target: unknown[], permissions: unknown): void {
+  if (!isRecord(permissions)) return;
+  for (const [legacyAction, rules] of Object.entries(permissions)) {
+    const action = permissionAction(legacyAction);
+    if (rules === "allow" || rules === "deny" || rules === "ask") {
+      target.push({ action, resource: "*", effect: rules });
+      continue;
+    }
+    if (!isRecord(rules)) continue;
+    for (const [resource, effect] of Object.entries(rules)) {
+      if (effect === "allow" || effect === "deny" || effect === "ask") {
+        target.push({ action, resource, effect });
+      }
+    }
+  }
+}
+
+function dedupePluginReferences(config: OpenCodeConfig): void {
+  const references = getOpenCodePluginReferences(config);
+  if (references.length === 0 && !("plugin" in config)) return;
+
+  const seen = new Set<string>();
+  setOpenCodePluginReferences(
+    config,
+    references.map(normalizePluginReference).filter((entry) => {
+      const key = JSON.stringify(entry);
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    }),
+  );
+}
+
+function normalizeCompaction(config: OpenCodeConfig): void {
+  if (!isRecord(config.compaction)) return;
+
+  const compaction = { ...config.compaction };
+  const keep = isRecord(compaction.keep) ? { ...compaction.keep } : {};
+  if (keep.tokens === undefined && compaction.preserve_recent_tokens !== undefined) {
+    keep.tokens = compaction.preserve_recent_tokens;
+  }
+  if (compaction.buffer === undefined && compaction.reserved !== undefined) {
+    compaction.buffer = compaction.reserved;
+  }
+  delete compaction.preserve_recent_tokens;
+  delete compaction.reserved;
+  // V2 compaction uses checkpoint-based summaries, not V1 pruning/tail turns.
+  delete compaction.prune;
+  delete compaction.tail_turns;
+  if (Object.keys(keep).length > 0) compaction.keep = keep;
+  else delete compaction.keep;
+  config.compaction = compaction;
+}
+
+/** Moves flat V1 `mcp.<name>` entries under `mcp.servers`; an existing V2 entry wins per key. */
+function normalizeMcpServers(config: OpenCodeConfig): void {
+  if (!isRecord(config.mcp)) return;
+
+  const mcp = { ...config.mcp };
+  const servers = isRecord(mcp.servers) ? { ...mcp.servers } : {};
+  for (const [name, value] of Object.entries(mcp)) {
+    if (name === "servers" || name === "timeout") continue;
+    const previous = normalizeMcpEntry(value);
+    const current = servers[name];
+    servers[name] =
+      isRecord(previous) && isRecord(current) ? { ...previous, ...current } : (current ?? previous);
+    delete mcp[name];
+  }
+  for (const [name, entry] of Object.entries(servers)) {
+    servers[name] = normalizeMcpEntry(entry);
+  }
+  if (Object.keys(servers).length > 0) mcp.servers = servers;
+  else delete mcp.servers;
+  if (typeof mcp.timeout === "number") {
+    mcp.timeout = splitMcpTimeout(mcp.timeout);
+  }
+  config.mcp = mcp;
+}
+
+function normalizeExperimentalMcpTimeout(config: OpenCodeConfig): void {
+  if (!isRecord(config.experimental) || typeof config.experimental.mcp_timeout !== "number") return;
+
+  const timeout = config.experimental.mcp_timeout;
+  const mcp = isRecord(config.mcp) ? { ...config.mcp } : {};
+  const existingTimeout = isRecord(mcp.timeout) ? { ...mcp.timeout } : {};
+  mcp.timeout = {
+    catalog: existingTimeout.catalog ?? timeout,
+    execution: existingTimeout.execution ?? timeout,
+  };
+  config.mcp = mcp;
+  const experimental = { ...config.experimental };
+  delete experimental.mcp_timeout;
+  if (Object.keys(experimental).length > 0) config.experimental = experimental;
+  else delete config.experimental;
+}
+
+/** Converts V1 `permission` maps and disabled `tools` into V2 rules ahead of existing ones. */
+function normalizePermissions(config: OpenCodeConfig): void {
+  const permissionRules: unknown[] = [];
+  appendPermissionRules(permissionRules, config.permission);
+  if (isRecord(config.tools)) {
+    for (const [toolName, enabled] of Object.entries(config.tools)) {
+      if (enabled === false) {
+        permissionRules.push({ action: permissionAction(toolName), resource: "*", effect: "deny" });
+      }
+    }
+    delete config.tools;
+  }
+  const currentPermissions = Array.isArray(config.permissions) ? config.permissions : [];
+  if (permissionRules.length > 0 || "permission" in config) {
+    config.permissions = [...permissionRules, ...currentPermissions];
+  }
+  delete config.permission;
+}
+
+function normalizeSkills(config: OpenCodeConfig): void {
+  if (!isRecord(config.skills)) return;
+
+  const legacySkills = config.skills;
+  const normalizedSkills = [
+    ...(Array.isArray(legacySkills.paths) ? legacySkills.paths : []),
+    ...(Array.isArray(legacySkills.urls) ? legacySkills.urls : []),
+  ];
+  config.skills = [...new Set(normalizedSkills.filter((entry) => typeof entry === "string"))];
+}
+
+/** Normalize supported V1 config syntax to V2 without discarding unrelated settings. */
+export function normalizeOpenCodeConfig(config: OpenCodeConfig): OpenCodeConfig {
+  dedupePluginReferences(config);
+  normalizeCompaction(config);
+  normalizeMcpServers(config);
+  normalizeExperimentalMcpTimeout(config);
+  normalizePermissions(config);
+  normalizeSkills(config);
+  return config;
 }
 
 function mergeConfig(target: Record<string, unknown>, source: Record<string, unknown>): void {
   for (const [key, sourceValue] of Object.entries(source)) {
     const targetValue = target[key];
+    if (key === "permissions" && Array.isArray(targetValue) && Array.isArray(sourceValue)) {
+      target[key] = [...targetValue, ...sourceValue];
+      continue;
+    }
     if (isRecord(targetValue) && isRecord(sourceValue)) {
       mergeConfig(targetValue, sourceValue);
       continue;
@@ -79,7 +271,7 @@ export function mergeOpenCodeConfigContent(
     try {
       const parsed = JSON.parse(existing) as unknown;
       if (isRecord(parsed)) {
-        config = parsed;
+        config = normalizeOpenCodeConfig(parsed);
       }
     } catch {
       // Ignore invalid inherited config content rather than breaking launch.
@@ -89,36 +281,34 @@ export function mergeOpenCodeConfigContent(
   mergeConfig(config, overlay);
 
   if (options.appendSkillPaths && options.appendSkillPaths.length > 0) {
-    const skills = isRecord(config.skills) ? config.skills : {};
-    const paths = Array.isArray(skills.paths) ? skills.paths : [];
-    const existingPaths = new Set(paths);
-    skills.paths = [
-      ...paths,
+    const skills = Array.isArray(config.skills) ? config.skills : [];
+    const existingPaths = new Set(skills);
+    config.skills = [
+      ...skills,
       ...options.appendSkillPaths.filter((skillPath) => !existingPaths.has(skillPath)),
     ];
-    config.skills = skills;
   }
 
   return JSON.stringify(config);
 }
 
-/** Map a provider-agnostic MCP descriptor to OpenCode's `mcp` entry shape. */
+/** Map a provider-agnostic MCP descriptor to OpenCode V2's server entry shape. */
 export function toOpenCodeMcpEntry(descriptor: McpEntryDescriptor): Record<string, unknown> {
   if (descriptor.url) {
-    return { type: "remote", url: descriptor.url, enabled: true };
+    return { type: "remote", url: descriptor.url, disabled: false };
   }
   return {
     type: "local",
     command: [descriptor.command ?? "", ...(descriptor.args ?? [])].filter(Boolean),
     ...(descriptor.env ? { environment: descriptor.env } : {}),
-    enabled: true,
+    disabled: false,
   };
 }
 
 /**
- * Reconcile a single server entry in the `mcp` map while preserving every
+ * Reconcile a single server under `mcp.servers` while preserving every
  * unrelated key. `entry: null` removes the server; removal never creates the
- * file, and an emptied `mcp` map is dropped entirely.
+ * file, and an emptied `mcp.servers` map is dropped.
  */
 export async function updateOpenCodeMcpServer(
   configPath: string,
@@ -128,19 +318,24 @@ export async function updateOpenCodeMcpServer(
   const { present, config } = await readOpenCodeConfig(configPath);
   if (entry === null && !present) return;
 
+  normalizeOpenCodeConfig(config);
   const mcp: Record<string, unknown> = isRecord(config.mcp) ? { ...config.mcp } : {};
+  const servers: Record<string, unknown> = isRecord(mcp.servers) ? { ...mcp.servers } : {};
   if (entry === null) {
-    if (!(name in mcp)) return;
-    delete mcp[name];
+    if (!(name in servers)) return;
+    delete servers[name];
   } else {
-    mcp[name] = entry;
+    servers[name] = normalizeMcpEntry(entry);
   }
 
   const next = { ...config };
-  if (Object.keys(mcp).length > 0) {
+  if (Object.keys(servers).length > 0) {
+    mcp.servers = servers;
     next.mcp = mcp;
   } else {
-    delete next.mcp;
+    delete mcp.servers;
+    if (Object.keys(mcp).length > 0) next.mcp = mcp;
+    else delete next.mcp;
   }
   await writeOpenCodeConfig(configPath, next);
 }