@yeaft/webchat-agent 1.0.413 → 1.0.415

package/yeaft/config-api.js

@@ -8,12 +8,14 @@
  * like maxContinueTurns or debug that don't belong in the UI.
  */
 
-import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { DEFAULT_YEAFT_DIR } from './init.js';
 import { normalizeProviderModels, parseModelRef, serializeModelForPersistence } from './models.js';
 import { normaliseTelemetrySection, normaliseYeaftSection } from './config.js';
+import { normaliseBrowserRuntimeSection, validateBrowserRuntimeUpdate } from '../browser-runtime/config.js';
 import { normalizePluginConfig } from './plugins.js';
+import { mutateAgentConfig, readAgentConfigForWrite } from './config-store.js';
 import { isGitHubCopilotProvider, serializeKnownProviderForPersistence } from './llm/known-providers.js';
 
 /**
@@ -28,16 +30,7 @@ import { isGitHubCopilotProvider, serializeKnownProviderForPersistence } from '.
  * @throws {Error} when an existing config cannot be safely preserved
  */
 function readConfigForWrite(configPath) {
-  if (!existsSync(configPath)) return {};
-  const json = JSON.parse(readFileSync(configPath, 'utf8'));
-  if (!json || typeof json !== 'object' || Array.isArray(json)
-    || Object.getPrototypeOf(json) !== Object.prototype) {
-    throw new Error('config.json must contain an object');
-  }
-  if (Object.prototype.hasOwnProperty.call(json, 'plugins')) {
-    normalizePluginConfig(json.plugins);
-  }
-  return json;
+  return readAgentConfigForWrite(configPath);
 }
 
 /**
@@ -142,85 +135,57 @@ function normalizeManagedModelDefaults(config) {
  */
 export function updateLlmConfig(update, dir) {
   const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
-  const configPath = join(root, 'config.json');
-
-  // Preserve all existing fields only when the on-disk document and its
-  // Plugins policy are valid. Never turn a failed read into a fresh config.
-  let existing;
-  try {
-    existing = readConfigForWrite(configPath);
-  } catch (err) {
-    return { error: `Failed to read config.json: ${err?.message || err}` };
-  }
 
-  // Validate providers structure
   if (update.providers !== undefined) {
-    if (!Array.isArray(update.providers)) {
-      return { error: 'providers must be an array' };
-    }
-    for (const p of update.providers) {
-      if (!p.name || typeof p.name !== 'string') {
+    if (!Array.isArray(update.providers)) return { error: 'providers must be an array' };
+    for (const provider of update.providers) {
+      if (!provider.name || typeof provider.name !== 'string') {
         return { error: 'Each provider must have a name' };
       }
-      if (isGitHubCopilotProvider(p)) continue;
-      if (!p.baseUrl || typeof p.baseUrl !== 'string') {
-        return { error: `Provider "${p.name}" must have a baseUrl` };
+      if (isGitHubCopilotProvider(provider)) continue;
+      if (!provider.baseUrl || typeof provider.baseUrl !== 'string') {
+        return { error: `Provider "${provider.name}" must have a baseUrl` };
       }
-      if (!Array.isArray(p.models) || p.models.length === 0) {
-        return { error: `Provider "${p.name}" must have at least one model` };
+      if (!Array.isArray(provider.models) || provider.models.length === 0) {
+        return { error: `Provider "${provider.name}" must have at least one model` };
       }
     }
-    // Normalize + re-serialize each provider's models so that:
-    //   - id-only entries are persisted as plain strings (back-compat)
-    //   - entries with ctx / maxOutput are persisted as objects
-    //   - empty / 0 / NaN values get stripped
-    existing.providers = update.providers.map(p => {
-      const managed = serializeKnownProviderForPersistence(p);
-      if (managed) return managed;
-      const normalized = normalizeProviderModels(p);
-      return {
-        ...p,
-        models: normalized.map(serializeModelForPersistence),
-      };
-    });
   }
 
-  // Update model selections. A managed provider catalog is authoritative:
-  // when it drops the old Agent default, keep no hidden reference to that
-  // model in primaryModel or fastModel.
-  if (update.primaryModel !== undefined) {
-    existing.primaryModel = update.primaryModel || null;
-  }
-  if (update.fastModel !== undefined) {
-    existing.fastModel = update.fastModel || null;
-  }
-  if (update.providers !== undefined) normalizeManagedModelDefaults(existing);
-  if (update.language !== undefined) {
-    existing.language = update.language;
-  }
-  if (update.debug !== undefined) {
-    existing.debug = update.debug === true;
-  }
-
-  // Write back
   try {
-    writeFileSync(configPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
-  } catch (e) {
-    return { error: `Failed to write config.json: ${e.message}` };
+    return mutateAgentConfig(root, existing => {
+      if (update.providers !== undefined) {
+        existing.providers = update.providers.map(provider => {
+          const managed = serializeKnownProviderForPersistence(provider);
+          if (managed) return managed;
+          return {
+            ...provider,
+            models: normalizeProviderModels(provider).map(serializeModelForPersistence),
+          };
+        });
+      }
+      if (update.primaryModel !== undefined) existing.primaryModel = update.primaryModel || null;
+      if (update.fastModel !== undefined) existing.fastModel = update.fastModel || null;
+      if (update.providers !== undefined) normalizeManagedModelDefaults(existing);
+      if (update.language !== undefined) existing.language = update.language;
+      if (update.debug !== undefined) existing.debug = update.debug === true;
+
+      const agentConfig = {
+        providers: Array.isArray(existing.providers) ? existing.providers : [],
+        primaryModel: existing.primaryModel || null,
+        fastModel: existing.fastModel || null,
+        language: existing.language || 'en',
+        debug: existing.debug === true,
+      };
+      return {
+        ...agentConfig,
+        agentConfig,
+        effectiveConfig: agentConfig,
+      };
+    });
+  } catch (error) {
+    return { error: `Failed to read config.json or persist update: ${error?.message || error}` };
   }
-
-  const agentConfig = {
-    providers: Array.isArray(existing.providers) ? existing.providers : [],
-    primaryModel: existing.primaryModel || null,
-    fastModel: existing.fastModel || null,
-    language: existing.language || 'en',
-    debug: existing.debug === true,
-  };
-  return {
-    ...agentConfig,
-    agentConfig,
-    effectiveConfig: agentConfig,
-  };
 }
 
 // ─── Yeaft runtime settings (task-318) ────────────────────────────
@@ -261,7 +226,6 @@ export function getYeaftSettings(dir) {
  */
 export function updateYeaftSettings(update, dir) {
   const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
-  const configPath = join(root, 'config.json');
 
   if (!update || typeof update !== 'object') {
     return { error: 'update payload required' };
@@ -288,37 +252,26 @@ export function updateYeaftSettings(update, dir) {
     }
   }
 
-  // Preserve all existing fields only when the on-disk document and its
-  // Plugins policy are valid. A Settings update must not repair bad JSON into
-  // a config whose missing Plugins fields inherit all capabilities.
-  let existing;
-  try {
-    existing = readConfigForWrite(configPath);
-  } catch (err) {
-    return { error: `Failed to read config.json: ${err?.message || err}` };
-  }
-
-  const prev = normaliseYeaftSection(existing.yeaft);
-  const merged = {
-    maxConcurrentThreads: update.maxConcurrentThreads !== undefined
-      ? Math.floor(Number(update.maxConcurrentThreads))
-      : prev.maxConcurrentThreads,
-    autoArchiveIdleDays: update.autoArchiveIdleDays !== undefined
-      ? Math.floor(Number(update.autoArchiveIdleDays))
-      : prev.autoArchiveIdleDays,
-    recentTurnsLimit: update.recentTurnsLimit !== undefined
-      ? Math.floor(Number(update.recentTurnsLimit))
-      : prev.recentTurnsLimit,
-  };
-  existing.yeaft = merged;
-
   try {
-    writeFileSync(configPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
-  } catch (e) {
-    return { error: `Failed to write config.json: ${e.message}` };
+    return mutateAgentConfig(root, existing => {
+      const prev = normaliseYeaftSection(existing.yeaft);
+      const merged = {
+        maxConcurrentThreads: update.maxConcurrentThreads !== undefined
+          ? Math.floor(Number(update.maxConcurrentThreads))
+          : prev.maxConcurrentThreads,
+        autoArchiveIdleDays: update.autoArchiveIdleDays !== undefined
+          ? Math.floor(Number(update.autoArchiveIdleDays))
+          : prev.autoArchiveIdleDays,
+        recentTurnsLimit: update.recentTurnsLimit !== undefined
+          ? Math.floor(Number(update.recentTurnsLimit))
+          : prev.recentTurnsLimit,
+      };
+      existing.yeaft = merged;
+      return merged;
+    });
+  } catch (error) {
+    return { error: `Failed to read config.json or persist update: ${error?.message || error}` };
   }
-
-  return merged;
 }
 
 /**
@@ -357,25 +310,50 @@ export function updateTelemetrySettings(update, dir) {
   if (Object.keys(update).some(key => !allowed.has(key))) {
     return { error: 'unknown telemetry setting' };
   }
+  const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
+  try {
+    return mutateAgentConfig(root, existing => {
+      const merged = normaliseTelemetrySection({
+        ...(existing.telemetry && typeof existing.telemetry === 'object' ? existing.telemetry : {}),
+        ...update,
+      });
+      existing.telemetry = merged;
+      return merged;
+    });
+  } catch (error) {
+    return { error: `Failed to read config.json or persist update: ${error?.message || error}` };
+  }
+}
+
+// ─── Browser Runtime settings ───────────────────────────────────────
+
+export function getBrowserRuntimeSettings(dir) {
   const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
   const configPath = join(root, 'config.json');
-  let existing;
+  if (!existsSync(configPath)) return normaliseBrowserRuntimeSection(null);
   try {
-    existing = readConfigForWrite(configPath);
-  } catch (err) {
-    return { error: `Failed to read config.json: ${err?.message || err}` };
+    const json = JSON.parse(readFileSync(configPath, 'utf8'));
+    return normaliseBrowserRuntimeSection(json.browserRuntime);
+  } catch (error) {
+    return { error: `Failed to read config.json: ${error.message}` };
   }
-  const merged = normaliseTelemetrySection({
-    ...(existing.telemetry && typeof existing.telemetry === 'object' ? existing.telemetry : {}),
-    ...update,
-  });
-  existing.telemetry = merged;
+}
+
+export function updateBrowserRuntimeSettings(update, dir) {
+  const validationError = validateBrowserRuntimeUpdate(update);
+  if (validationError) return { error: validationError };
+  const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
   try {
-    writeFileSync(configPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
-  } catch (e) {
-    return { error: `Failed to write config.json: ${e.message}` };
+    return mutateAgentConfig(root, existing => {
+      const previous = existing.browserRuntime && typeof existing.browserRuntime === 'object'
+        ? existing.browserRuntime
+        : {};
+      existing.browserRuntime = normaliseBrowserRuntimeSection({ ...previous, ...update });
+      return existing.browserRuntime;
+    });
+  } catch (error) {
+    return { error: `Failed to read config.json or persist update: ${error?.message || error}` };
   }
-  return merged;
 }
 
 // ─── Search settings (web-search backend selection + Tavily key) ────
@@ -443,7 +421,6 @@ export function getSearchSettings(dir) {
  */
 export function updateSearchSettings(update, dir) {
   const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
-  const configPath = join(root, 'config.json');
 
   if (!update || typeof update !== 'object') {
     return { error: 'update payload required' };
@@ -455,23 +432,17 @@ export function updateSearchSettings(update, dir) {
     return { error: 'tavilyApiKey must be a string' };
   }
 
-  let existing;
   try {
-    existing = readConfigForWrite(configPath);
-  } catch (err) {
-    return { error: `Failed to read config.json: ${err?.message || err}` };
-  }
-  const prev = (existing && typeof existing.search === 'object' && existing.search) || {};
-  const merged = { ...prev };
-  if (update.backend !== undefined) merged.backend = update.backend;
-  if (update.tavilyApiKey !== undefined) merged.tavilyApiKey = update.tavilyApiKey;
-  if (update.disableHtmlFallback !== undefined) merged.disableHtmlFallback = !!update.disableHtmlFallback;
-  existing.search = merged;
-
-  try {
-    writeFileSync(configPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
-  } catch (e) {
-    return { error: `Failed to write config.json: ${e.message}` };
+    mutateAgentConfig(root, existing => {
+      const prev = (existing && typeof existing.search === 'object' && existing.search) || {};
+      const merged = { ...prev };
+      if (update.backend !== undefined) merged.backend = update.backend;
+      if (update.tavilyApiKey !== undefined) merged.tavilyApiKey = update.tavilyApiKey;
+      if (update.disableHtmlFallback !== undefined) merged.disableHtmlFallback = !!update.disableHtmlFallback;
+      existing.search = merged;
+    });
+  } catch (error) {
+    return { error: `Failed to read config.json or persist update: ${error?.message || error}` };
   }
   return getSearchSettings(root);
 }
@@ -549,24 +520,17 @@ export function getPluginConfig(dir) {
  */
 export function updatePluginConfig(plugins, dir) {
   const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
-  const configPath = join(root, 'config.json');
   let normalized;
-  let existing;
   try {
-    existing = readConfigForWrite(configPath);
     normalized = normalizePluginConfig(plugins);
-  } catch (err) {
-    return { error: `Failed to read plugin config: ${err?.message || err}` };
-  }
-
-  if (Object.keys(normalized).length === 0) delete existing.plugins;
-  else existing.plugins = normalized;
-  try {
-    writeFileSync(configPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
-  } catch (err) {
-    return { error: `Failed to write plugin config: ${err?.message || err}` };
+    return mutateAgentConfig(root, existing => {
+      if (Object.keys(normalized).length === 0) delete existing.plugins;
+      else existing.plugins = normalized;
+      return { plugins: normalized };
+    });
+  } catch (error) {
+    return { error: `Failed to read plugin config or persist update: ${error?.message || error}` };
   }
-  return { plugins: normalized };
 }
 
 // ─── MCP server config (mcpServers array in config.json) ──
@@ -684,33 +648,21 @@ export function upsertMcpServer(server, dir) {
   if (err) return { error: err };
 
   const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
-  const configPath = join(root, 'config.json');
-  let existing;
-  try {
-    existing = readConfigForWrite(configPath);
-  } catch (err) {
-    return { error: `Failed to read config.json: ${err?.message || err}` };
-  }
-  const list = Array.isArray(existing.mcpServers) ? existing.mcpServers.slice() : [];
-
   const normalised = normaliseMcpServer(server);
   if (!normalised) return { error: 'invalid server payload' };
 
-  const idx = list.findIndex(s => s && typeof s === 'object' && s.name === normalised.name);
-  if (idx >= 0) {
-    list[idx] = normalised;
-  } else {
-    list.push(normalised);
-  }
-  existing.mcpServers = list;
-
   try {
-    writeFileSync(configPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
-  } catch (e) {
-    return { error: `Failed to write config.json: ${e.message}` };
+    return mutateAgentConfig(root, existing => {
+      const list = Array.isArray(existing.mcpServers) ? existing.mcpServers.slice() : [];
+      const index = list.findIndex(entry => entry && typeof entry === 'object' && entry.name === normalised.name);
+      if (index >= 0) list[index] = normalised;
+      else list.push(normalised);
+      existing.mcpServers = list;
+      return { servers: list.map(normaliseMcpServer).filter(Boolean), server: normalised };
+    });
+  } catch (error) {
+    return { error: `Failed to read config.json or persist update: ${error?.message || error}` };
   }
-
-  return { servers: list.map(normaliseMcpServer).filter(Boolean), server: normalised };
 }
 
 /**
@@ -732,24 +684,18 @@ export function removeMcpServer(name, dir) {
   // matching against the padded string.
   const target = name.trim();
   const root = dir || process.env.YEAFT_DIR || DEFAULT_YEAFT_DIR;
-  const configPath = join(root, 'config.json');
-  let existing;
-  try {
-    existing = readConfigForWrite(configPath);
-  } catch (err) {
-    return { error: `Failed to read config.json: ${err?.message || err}` };
-  }
-  const list = Array.isArray(existing.mcpServers) ? existing.mcpServers.slice() : [];
-  const next = list.filter(s => !(s && typeof s === 'object' && s.name === target));
-  const removed = next.length !== list.length;
-  existing.mcpServers = next;
-
   try {
-    writeFileSync(configPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
-  } catch (e) {
-    return { error: `Failed to write config.json: ${e.message}` };
+    return mutateAgentConfig(root, existing => {
+      const list = Array.isArray(existing.mcpServers) ? existing.mcpServers.slice() : [];
+      const next = list.filter(entry => !(entry && typeof entry === 'object' && entry.name === target));
+      existing.mcpServers = next;
+      return {
+        servers: next.map(normaliseMcpServer).filter(Boolean),
+        removed: next.length !== list.length,
+      };
+    });
+  } catch (error) {
+    return { error: `Failed to read config.json or persist update: ${error?.message || error}` };
   }
-
-  return { servers: next.map(normaliseMcpServer).filter(Boolean), removed };
 }
 

package/yeaft/config-store.js

@@ -0,0 +1,192 @@
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+} from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { hostname } from 'node:os';
+import { normalizePluginConfig } from './plugins.js';
+import { writeAtomic } from './storage/atomic.js';
+
+const LOCK_WAIT_MS = 10_000;
+const LOCK_STALE_MS = 5 * 60_000;
+const LOCK_RETRY_MS = 10;
+
+function sleepSync(ms) {
+  const buffer = new Int32Array(new SharedArrayBuffer(4));
+  Atomics.wait(buffer, 0, 0, ms);
+}
+
+function ensureOwnerDirectory(path) {
+  if (existsSync(path)) {
+    const details = lstatSync(path);
+    if (!details.isDirectory()) throw new Error('Yeaft data root is not a directory');
+    if (process.platform !== 'win32') {
+      const currentMode = details.mode & 0o777;
+      const restrictedMode = currentMode & 0o700;
+      if (currentMode !== restrictedMode) chmodSync(path, restrictedMode);
+    }
+    return;
+  }
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  if (process.platform !== 'win32') chmodSync(path, 0o700);
+}
+
+function readConfigForWrite(configPath) {
+  if (!existsSync(configPath)) return {};
+  const json = JSON.parse(readFileSync(configPath, 'utf8'));
+  if (!json || typeof json !== 'object' || Array.isArray(json)
+    || Object.getPrototypeOf(json) !== Object.prototype) {
+    throw new Error('config.json must contain an object');
+  }
+  if (Object.prototype.hasOwnProperty.call(json, 'plugins')) {
+    normalizePluginConfig(json.plugins);
+  }
+  return json;
+}
+
+function processIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function readConfigLockOwner(lockDir) {
+  const lockStat = lstatSync(lockDir);
+  if (!lockStat.isDirectory()) throw new Error('config.json lock path is not a directory');
+  try {
+    const owner = JSON.parse(readFileSync(join(lockDir, 'owner.json'), 'utf8'));
+    return { owner, lockStat };
+  } catch {
+    return { owner: null, lockStat };
+  }
+}
+
+function configLockCanBeTaken(lockDir) {
+  const { owner, lockStat } = readConfigLockOwner(lockDir);
+  if (owner?.host === hostname()) return !processIsAlive(Number(owner.pid));
+  if (owner) return false;
+  return Date.now() - lockStat.mtimeMs > LOCK_STALE_MS;
+}
+
+function lockIsOwned(lockDir, token) {
+  try {
+    const owner = JSON.parse(readFileSync(join(lockDir, 'owner.json'), 'utf8'));
+    return owner?.token === token;
+  } catch {
+    return false;
+  }
+}
+
+function removeConfigLockIfOwned(lockDir, token) {
+  if (!lockIsOwned(lockDir, token)) return false;
+  const claimed = `${lockDir}.release-${token}`;
+  try {
+    renameSync(lockDir, claimed);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+  if (!lockIsOwned(claimed, token)) {
+    try { renameSync(claimed, lockDir); } catch {}
+    return false;
+  }
+  rmSync(claimed, { recursive: true, force: true });
+  return true;
+}
+
+function lockOwnerIdentity(owner) {
+  if (!owner) return null;
+  if (typeof owner.token === 'string' && owner.token) return `token:${owner.token}`;
+  return `legacy:${owner.host || ''}:${Number(owner.pid) || 0}:${Number(owner.startedAt) || 0}`;
+}
+
+function takeConfigLock(lockDir) {
+  const observed = readConfigLockOwner(lockDir).owner;
+  if (!configLockCanBeTaken(lockDir)) return false;
+  const observedIdentity = lockOwnerIdentity(observed);
+  const claimed = `${lockDir}.stale-${randomUUID()}`;
+  try {
+    renameSync(lockDir, claimed);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return true;
+    return false;
+  }
+  const claimedOwner = readConfigLockOwner(claimed).owner;
+  const ownerChanged = lockOwnerIdentity(claimedOwner) !== observedIdentity;
+  const ownerRevived = claimedOwner?.host === hostname()
+    && processIsAlive(Number(claimedOwner.pid));
+  if (ownerChanged || ownerRevived) {
+    try { renameSync(claimed, lockDir); } catch {}
+    return false;
+  }
+  rmSync(claimed, { recursive: true, force: true });
+  return true;
+}
+
+function acquireConfigLock(root, { waitMs = LOCK_WAIT_MS } = {}) {
+  ensureOwnerDirectory(root);
+  const lockDir = join(root, '.config.json.lock');
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    const token = randomUUID();
+    try {
+      mkdirSync(lockDir, { mode: 0o700 });
+      writeFileSync(join(lockDir, 'owner.json'), JSON.stringify({
+        pid: process.pid,
+        host: hostname(),
+        token,
+        startedAt: Date.now(),
+      }), { flag: 'wx', mode: 0o600 });
+      return () => removeConfigLockIfOwned(lockDir, token);
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      try {
+        if (takeConfigLock(lockDir)) continue;
+      } catch (inspectionError) {
+        if (inspectionError?.code === 'ENOENT') continue;
+        throw inspectionError;
+      }
+      if (Date.now() >= deadline) throw new Error('config.json is busy');
+      sleepSync(Math.min(LOCK_RETRY_MS, Math.max(1, deadline - Date.now())));
+    }
+  }
+}
+
+/**
+ * Mutate one Agent-owned config.json under a cross-process lock.
+ * The callback runs after the file is re-read and validated inside the lock.
+ */
+export function mutateAgentConfig(root, mutate, options = {}) {
+  if (!root) throw new Error('Yeaft data root required');
+  if (typeof mutate !== 'function') throw new Error('config mutator required');
+  const release = acquireConfigLock(root, options);
+  const configPath = join(root, 'config.json');
+  try {
+    const exists = existsSync(configPath);
+    const current = readConfigForWrite(configPath);
+    const result = mutate(current, { exists, configPath });
+    writeAtomic(configPath, `${JSON.stringify(current, null, 2)}\n`, { mode: 0o600 });
+    return result;
+  } finally {
+    release();
+  }
+}
+
+export function mutateAgentConfigPath(configPath, mutate, options = {}) {
+  return mutateAgentConfig(dirname(configPath), mutate, options);
+}
+
+export function readAgentConfigForWrite(configPath) {
+  return readConfigForWrite(configPath);
+}

package/yeaft/config.js

@@ -27,6 +27,7 @@ import { getModelEffortOptions, getThinkingCapability, modelSupportsEffort, reso
 import { inferProtocolFromModelId } from './llm/router.js';
 import { normalizeKnownProviderForRuntime } from './llm/known-providers.js';
 import { createDenyAllPluginConfig, normalizePluginConfig } from './plugins.js';
+import { normaliseBrowserRuntimeSection } from '../browser-runtime/config.js';
 import { readWorkspaceFile } from './workspace-file.js';
 
 /** Default configuration values. */
@@ -368,6 +369,7 @@ function loadLegacyConfig(dir, overrides) {
     // task-318: legacy path never had the `yeaft` section — defaults.
     yeaft: normaliseYeaftSection(null),
     telemetry: normaliseTelemetrySection(null),
+    browserRuntime: normaliseBrowserRuntimeSection(null),
     plugins: {},
     providers: null,
     primaryModel: null,
@@ -524,6 +526,7 @@ export function loadConfig(overrides = {}) {
     // don't pollute the flat config namespace used by chat code.
     yeaft: normaliseYeaftSection(jsonConfig.yeaft),
     telemetry: normaliseTelemetrySection(jsonConfig.telemetry),
+    browserRuntime: normaliseBrowserRuntimeSection(jsonConfig.browserRuntime),
 
     // Agent-level tools / skills / MCP server allowlists. Missing fields mean
     // all currently discovered capabilities remain enabled. A persisted schema