@keyou007/agent-bot 0.1.12 → 0.1.13-alpha.0

package/src/cli/AgentPrerequisites.ts

@@ -0,0 +1,377 @@
+import { spawn } from "node:child_process";
+
+export type SupportedAgentId = "codex" | "traex";
+export type SupportedAgentState = "missing" | "outdated" | "ready";
+export type AgentMaintenanceKind = "install" | "upgrade";
+
+export interface AgentCommandResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  error?: string;
+}
+
+export interface AgentCommandSpec {
+  command: string;
+  args: string[];
+  display: string;
+  timeoutMs: number;
+  env?: NodeJS.ProcessEnv;
+  inheritStdio?: boolean;
+}
+
+export type AgentCommandRunner = (command: AgentCommandSpec) => Promise<AgentCommandResult>;
+
+export interface SupportedAgentInspection {
+  id: SupportedAgentId;
+  name: string;
+  state: SupportedAgentState;
+  installedVersion?: string;
+  latestVersion?: string;
+  latestCheckFailed?: boolean;
+  action?: {
+    kind: AgentMaintenanceKind;
+    command: string;
+  };
+}
+
+export interface InspectSupportedAgentsOptions {
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  run?: AgentCommandRunner;
+}
+
+const CODEX_PACKAGE = "@openai/codex";
+const TRAEX_CHANNEL = "alpha";
+const TRAEX_INSTALL_BASE_URL = "https://code.byted.org/api/tos-proxy/download";
+
+export async function inspectSupportedAgents(
+  options: InspectSupportedAgentsOptions = {},
+): Promise<SupportedAgentInspection[]> {
+  return Promise.all([
+    inspectSupportedAgent("codex", options),
+    inspectSupportedAgent("traex", options),
+  ]);
+}
+
+export async function inspectSupportedAgent(
+  id: SupportedAgentId,
+  options: InspectSupportedAgentsOptions = {},
+): Promise<SupportedAgentInspection> {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const run = options.run ?? runAgentCommand;
+  return id === "codex"
+    ? inspectCodex(platform, env, run)
+    : inspectTraex(platform, env, run);
+}
+
+export async function runSupportedAgentMaintenance(
+  id: SupportedAgentId,
+  kind: AgentMaintenanceKind,
+  options: InspectSupportedAgentsOptions = {},
+): Promise<AgentCommandResult> {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const run = options.run ?? runAgentCommand;
+  const command = maintenanceCommand(id, kind, platform, env);
+  const result = await run({ ...command, inheritStdio: true });
+  if (id !== "codex" || kind !== "upgrade" || commandSucceeded(result)) return result;
+  const fallback = codexNpmInstallCommand(platform, env);
+  return run({ ...fallback, inheritStdio: true });
+}
+
+async function inspectCodex(
+  platform: NodeJS.Platform,
+  env: NodeJS.ProcessEnv,
+  run: AgentCommandRunner,
+): Promise<SupportedAgentInspection> {
+  const installed = await run(capturedCommand("codex", ["--version"], platform, env, 5_000));
+  const installedVersion = commandVersion(installed);
+  if (!installedVersion) return missingInspection("codex", "Codex", platform, env);
+
+  const latest = await run(capturedCommand(
+    "npm",
+    ["view", CODEX_PACKAGE, "version", "--json"],
+    platform,
+    env,
+    15_000,
+  ));
+  const latestVersion = npmVersion(latest);
+  if (!latestVersion) {
+    return { id: "codex", name: "Codex", state: "ready", installedVersion, latestCheckFailed: true };
+  }
+  if (compareSemanticVersions(installedVersion, latestVersion) < 0) {
+    return {
+      id: "codex",
+      name: "Codex",
+      state: "outdated",
+      installedVersion,
+      latestVersion,
+      action: maintenanceAction("codex", "upgrade", platform, env),
+    };
+  }
+  return { id: "codex", name: "Codex", state: "ready", installedVersion, latestVersion };
+}
+
+async function inspectTraex(
+  platform: NodeJS.Platform,
+  env: NodeJS.ProcessEnv,
+  run: AgentCommandRunner,
+): Promise<SupportedAgentInspection> {
+  const installed = await run(capturedCommand("traex", ["--version"], platform, env, 5_000));
+  const installedVersion = commandVersion(installed);
+  if (!installedVersion) return missingInspection("traex", "TraeX", platform, env);
+
+  const latest = await run(capturedCommand(
+    "traex",
+    ["update", "--channel", TRAEX_CHANNEL, "check"],
+    platform,
+    env,
+    15_000,
+  ));
+  const latestVersion = /^Latest TraeCode CLI version:\s*(\S+)/mu.exec(commandOutput(latest))?.[1];
+  if (!latestVersion) {
+    return { id: "traex", name: "TraeX", state: "ready", installedVersion, latestCheckFailed: true };
+  }
+  if (compareSemanticVersions(installedVersion, latestVersion) < 0) {
+    return {
+      id: "traex",
+      name: "TraeX",
+      state: "outdated",
+      installedVersion,
+      latestVersion,
+      action: maintenanceAction("traex", "upgrade", platform, env),
+    };
+  }
+  return { id: "traex", name: "TraeX", state: "ready", installedVersion, latestVersion };
+}
+
+function missingInspection(
+  id: SupportedAgentId,
+  name: string,
+  platform: NodeJS.Platform,
+  env: NodeJS.ProcessEnv,
+): SupportedAgentInspection {
+  return {
+    id,
+    name,
+    state: "missing",
+    action: maintenanceAction(id, "install", platform, env),
+  };
+}
+
+function maintenanceAction(
+  id: SupportedAgentId,
+  kind: AgentMaintenanceKind,
+  platform: NodeJS.Platform,
+  env: NodeJS.ProcessEnv,
+): SupportedAgentInspection["action"] {
+  const command = maintenanceCommand(id, kind, platform, env);
+  return { kind, command: command.display };
+}
+
+function maintenanceCommand(
+  id: SupportedAgentId,
+  kind: AgentMaintenanceKind,
+  platform: NodeJS.Platform,
+  env: NodeJS.ProcessEnv,
+): AgentCommandSpec {
+  if (id === "codex") {
+    return kind === "install"
+      ? codexNpmInstallCommand(platform, env)
+      : commandSpec("codex", ["update"], platform, env, 5 * 60_000);
+  }
+  if (kind === "upgrade") {
+    return commandSpec("traex", ["update", "--channel", TRAEX_CHANNEL], platform, env, 5 * 60_000);
+  }
+
+  const installEnv = {
+    ...env,
+    TRAEX_INSTALL_ASSUME_YES: "1",
+    TRAEX_INSTALL_CHANNEL: TRAEX_CHANNEL,
+  };
+  if (platform === "win32") {
+    const scriptUrl = `${TRAEX_INSTALL_BASE_URL}/traex_install_windows.ps1`;
+    return {
+      command: "powershell.exe",
+      args: [
+        "-NoProfile",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-Command",
+        `Invoke-RestMethod -Uri '${scriptUrl}' | Invoke-Expression`,
+      ],
+      display: `$env:TRAEX_INSTALL_CHANNEL='${TRAEX_CHANNEL}'; irm '${scriptUrl}' | iex`,
+      timeoutMs: 5 * 60_000,
+      env: installEnv,
+    };
+  }
+  const scriptUrl = `${TRAEX_INSTALL_BASE_URL}/traex_install.sh`;
+  return {
+    command: "bash",
+    args: ["-c", `curl -fsSL '${scriptUrl}' | bash`],
+    display: `curl -fsSL '${scriptUrl}' | TRAEX_INSTALL_CHANNEL=${TRAEX_CHANNEL} bash`,
+    timeoutMs: 5 * 60_000,
+    env: installEnv,
+  };
+}
+
+function codexNpmInstallCommand(
+  platform: NodeJS.Platform,
+  env: NodeJS.ProcessEnv,
+): AgentCommandSpec {
+  return commandSpec(
+    "npm",
+    ["install", "--global", `${CODEX_PACKAGE}@latest`],
+    platform,
+    env,
+    5 * 60_000,
+  );
+}
+
+function commandSucceeded(result: AgentCommandResult): boolean {
+  return result.status === 0 && !result.error;
+}
+
+function capturedCommand(
+  command: string,
+  args: string[],
+  platform: NodeJS.Platform,
+  env: NodeJS.ProcessEnv,
+  timeoutMs: number,
+): AgentCommandSpec {
+  return commandSpec(command, args, platform, env, timeoutMs);
+}
+
+function commandSpec(
+  command: string,
+  args: string[],
+  _platform: NodeJS.Platform,
+  env: NodeJS.ProcessEnv,
+  timeoutMs: number,
+): AgentCommandSpec {
+  return {
+    command,
+    args,
+    display: [command, ...args].join(" "),
+    timeoutMs,
+    env,
+  };
+}
+
+function commandVersion(result: AgentCommandResult): string | undefined {
+  if (result.status !== 0) return undefined;
+  return versionInText(commandOutput(result));
+}
+
+function npmVersion(result: AgentCommandResult): string | undefined {
+  if (result.status !== 0) return undefined;
+  const output = result.stdout.trim();
+  try {
+    const parsed = JSON.parse(output) as unknown;
+    return typeof parsed === "string" ? versionInText(parsed) : undefined;
+  } catch {
+    return versionInText(output);
+  }
+}
+
+function commandOutput(result: AgentCommandResult): string {
+  return [result.stdout, result.stderr].filter(Boolean).join("\n");
+}
+
+function versionInText(value: string): string | undefined {
+  return /\b(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)\b/u.exec(value)?.[1];
+}
+
+export function compareSemanticVersions(left: string, right: string): number {
+  const leftVersion = parseSemanticVersion(left);
+  const rightVersion = parseSemanticVersion(right);
+  if (!leftVersion || !rightVersion) return 0;
+  for (let index = 0; index < 3; index += 1) {
+    const difference = leftVersion.core[index]! - rightVersion.core[index]!;
+    if (difference !== 0) return difference;
+  }
+  if (!leftVersion.prerelease && !rightVersion.prerelease) return 0;
+  if (!leftVersion.prerelease) return 1;
+  if (!rightVersion.prerelease) return -1;
+  const length = Math.max(leftVersion.prerelease.length, rightVersion.prerelease.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftPart = leftVersion.prerelease[index];
+    const rightPart = rightVersion.prerelease[index];
+    if (leftPart === undefined) return -1;
+    if (rightPart === undefined) return 1;
+    if (leftPart === rightPart) continue;
+    const leftNumber = /^\d+$/u.test(leftPart) ? Number(leftPart) : undefined;
+    const rightNumber = /^\d+$/u.test(rightPart) ? Number(rightPart) : undefined;
+    if (leftNumber !== undefined && rightNumber !== undefined) return leftNumber - rightNumber;
+    if (leftNumber !== undefined) return -1;
+    if (rightNumber !== undefined) return 1;
+    return leftPart.localeCompare(rightPart);
+  }
+  return 0;
+}
+
+function parseSemanticVersion(value: string): {
+  core: [number, number, number];
+  prerelease?: string[];
+} | undefined {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u.exec(value);
+  if (!match) return undefined;
+  return {
+    core: [Number(match[1]), Number(match[2]), Number(match[3])],
+    ...(match[4] ? { prerelease: match[4].split(".") } : {}),
+  };
+}
+
+export function runAgentCommand(command: AgentCommandSpec): Promise<AgentCommandResult> {
+  return new Promise((resolve) => {
+    const invocation = resolveInvocation(command);
+    const child = spawn(invocation.command, invocation.args, {
+      env: command.env ?? process.env,
+      windowsHide: true,
+      stdio: command.inheritStdio ? "inherit" : ["ignore", "pipe", "pipe"],
+    });
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    if (!command.inheritStdio) {
+      child.stdout?.on("data", (chunk: Buffer) => stdout.push(chunk));
+      child.stderr?.on("data", (chunk: Buffer) => stderr.push(chunk));
+    }
+    let error: string | undefined;
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill();
+    }, command.timeoutMs);
+    child.once("error", (spawnError) => {
+      error = spawnError.message;
+    });
+    child.once("close", (status) => {
+      clearTimeout(timer);
+      resolve({
+        status,
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8"),
+        ...(error || timedOut ? { error: timedOut ? `Timed out after ${command.timeoutMs}ms.` : error } : {}),
+      });
+    });
+  });
+}
+
+function resolveInvocation(command: AgentCommandSpec): { command: string; args: string[] } {
+  if (process.platform !== "win32" || /\.exe$/iu.test(command.command)) {
+    return { command: command.command, args: command.args };
+  }
+  const commandLine = [command.command, ...command.args].map(quoteCmdArgument).join(" ");
+  return {
+    command: process.env.ComSpec ?? "cmd.exe",
+    args: ["/d", "/s", "/c", commandLine],
+  };
+}
+
+function quoteCmdArgument(value: string): string {
+  return /^[A-Za-z0-9_@./:\\=+-]+$/u.test(value)
+    ? value
+    : `"${value.replaceAll('"', '""')}"`;
+}

package/src/cli/DefaultAgentSelection.ts

@@ -0,0 +1,56 @@
+import type { ConfiguredAgentOption } from "./Initializer.js";
+import type { SupportedAgentInspection } from "./AgentPrerequisites.js";
+
+export interface SelectableDefaultAgent extends ConfiguredAgentOption {
+  installedVersion?: string;
+}
+
+export function selectableDefaultAgents(
+  configured: ConfiguredAgentOption[],
+  inspections: SupportedAgentInspection[],
+): SelectableDefaultAgent[] {
+  const supported = new Map(inspections.map((inspection) => [inspection.id, inspection]));
+  return configured.flatMap((agent) => {
+    const inspection = supported.get(agent.name as SupportedAgentInspection["id"]);
+    if (inspection && !inspection.installedVersion) return [];
+    return [{
+      ...agent,
+      ...(inspection?.installedVersion ? { installedVersion: inspection.installedVersion } : {}),
+    }];
+  });
+}
+
+export function parseMaintenanceSelection(input: string, choiceCount: number): number[] | undefined {
+  const value = input.trim();
+  if (!value) return [];
+  if (/^(?:a|all)$/iu.test(value)) return Array.from({ length: choiceCount }, (_, index) => index);
+  const tokens = value.split(/[,，\s]+/u).filter(Boolean);
+  const selected = new Set<number>();
+  for (const token of tokens) {
+    const number = Number(token);
+    if (!Number.isInteger(number) || number < 1 || number > choiceCount) return undefined;
+    selected.add(number - 1);
+  }
+  return [...selected].sort((left, right) => left - right);
+}
+
+export function resolveDefaultAgentChoice(
+  input: string,
+  choices: SelectableDefaultAgent[],
+  currentAgent?: string,
+): number | undefined {
+  const value = input.trim();
+  if (!value) {
+    const currentIndex = choices.findIndex((choice) => choice.name === currentAgent);
+    return currentIndex >= 0 ? currentIndex : undefined;
+  }
+  const number = Number(value);
+  if (Number.isInteger(number) && number >= 1 && number <= choices.length) return number - 1;
+  const exactIndex = choices.findIndex((choice) => choice.name === value);
+  if (exactIndex >= 0) return exactIndex;
+  const folded = value.toLocaleLowerCase("en-US");
+  const matches = choices
+    .map((choice, index) => ({ choice, index }))
+    .filter(({ choice }) => choice.name.toLocaleLowerCase("en-US") === folded);
+  return matches.length === 1 ? matches[0]?.index : undefined;
+}

package/src/cli/Initializer.ts

@@ -5,6 +5,7 @@ import path from "node:path";
 import { cliText } from "./i18n.js";
 import { fileURLToPath } from "node:url";
 import { parse as parseDotEnv } from "dotenv";
+import { isMap, isScalar, parseDocument, type YAMLMap } from "yaml";
 import {
   agentBotHome,
   defaultConfigPath,
@@ -12,7 +13,7 @@ import {
   resolveUserPath,
 } from "../config/paths.js";
 
-export type InitializationStatus = "created" | "existing" | "reset";
+export type InitializationStatus = "created" | "existing" | "updated" | "reset";
 
 export interface InitializedPath {
   path: string;
@@ -38,6 +39,16 @@ export interface InitializationOptions {
   reset?: boolean;
 }
 
+export interface ConfiguredAgentOption {
+  name: string;
+  title: string;
+}
+
+export interface ConfiguredAgentSelection {
+  agents: ConfiguredAgentOption[];
+  defaultAgent?: string;
+}
+
 export type FeishuCredentialStatus = "configured" | "missing" | "incomplete";
 
 export interface FeishuCredentialState {
@@ -82,8 +93,8 @@ export function initializeAgentBot(options: InitializationOptions = {}): Initial
     ? resetProfileContents(homePath, configPath, envPath, configDirectory)
     : undefined;
 
-  const config = copyIfMissing(configTemplatePath, configPath);
-  const envFile = copyIfMissing(envTemplatePath, envPath);
+  const config = initializeConfig(configTemplatePath, configPath);
+  const envFile = initializeEnv(envTemplatePath, envPath);
   restrictFilePermissions(envFile.path);
   const data = ensureDirectory(path.join(configDirectory, "data"));
   const logs = ensureDirectory(path.join(configDirectory, "logs"));
@@ -98,6 +109,68 @@ export function initializeAgentBot(options: InitializationOptions = {}): Initial
   };
 }
 
+export function readConfiguredAgentSelection(configPath: string): ConfiguredAgentSelection {
+  const document = parseConfigurationDocument(fs.readFileSync(configPath, "utf8"), configPath);
+  if (!isMap(document.contents)) {
+    throw new Error(cliText(
+      `Configuration file must contain a YAML mapping: ${configPath}`,
+      `配置文件必须包含 YAML 映射：${configPath}`,
+    ));
+  }
+  const configuredAgents = document.contents.get("agents", true);
+  if (!isMap(configuredAgents)) {
+    throw new Error(cliText(
+      `Configuration file must contain an agents mapping: ${configPath}`,
+      `配置文件必须包含 agents 映射：${configPath}`,
+    ));
+  }
+  const agents = configuredAgents.items.flatMap((pair) => {
+    const name = yamlMappingKey(pair.key);
+    if (!name) return [];
+    const titleNode = isMap(pair.value) ? pair.value.get("title", true) : undefined;
+    const title = isScalar(titleNode) && typeof titleNode.value === "string"
+      ? titleNode.value
+      : name;
+    return [{ name, title }];
+  });
+  const defaultAgent = document.getIn(["defaults", "agent"]);
+  return {
+    agents,
+    ...(typeof defaultAgent === "string" && defaultAgent.trim() ? { defaultAgent } : {}),
+  };
+}
+
+export function writeDefaultAgent(configPath: string, agentName: string): boolean {
+  const original = fs.readFileSync(configPath, "utf8");
+  const document = parseConfigurationDocument(original, configPath);
+  if (!isMap(document.contents)) {
+    throw new Error(cliText(
+      `Configuration file must contain a YAML mapping: ${configPath}`,
+      `配置文件必须包含 YAML 映射：${configPath}`,
+    ));
+  }
+  const configuredAgents = document.contents.get("agents", true);
+  if (!isMap(configuredAgents) || !configuredAgents.has(agentName)) {
+    throw new Error(cliText(
+      `Cannot select an Agent that is not configured: ${agentName}`,
+      `不能选择尚未配置的 Agent：${agentName}`,
+    ));
+  }
+  const defaults = document.contents.get("defaults", true);
+  if (defaults !== undefined && !isMap(defaults)) {
+    throw new Error(cliText(
+      `Configuration defaults must contain a YAML mapping: ${configPath}`,
+      `配置文件的 defaults 必须是 YAML 映射：${configPath}`,
+    ));
+  }
+  const currentAgent = document.getIn(["defaults", "agent"]);
+  if (currentAgent === agentName) return false;
+  if (isMap(defaults)) defaults.set("agent", agentName);
+  else document.setIn(["defaults"], { agent: agentName });
+  writeFileAtomically(configPath, document.toString());
+  return true;
+}
+
 export function readFeishuCredentials(envPath: string, env: NodeJS.ProcessEnv = process.env): FeishuCredentialState {
   const fileValues = fs.existsSync(envPath) ? parseDotEnv(fs.readFileSync(envPath, "utf8")) : {};
   const appId = firstNonBlank(env.FEISHU_APP_ID, fileValues.FEISHU_APP_ID);
@@ -244,6 +317,134 @@ function copyIfMissing(sourcePath: string, targetPath: string): InitializedPath
   }
 }
 
+function initializeConfig(templatePath: string, configPath: string): InitializedPath {
+  if (!fs.existsSync(configPath)) {
+    const copied = copyIfMissing(templatePath, configPath);
+    if (copied.status === "created") return copied;
+  }
+
+  const original = fs.readFileSync(configPath, "utf8");
+  const template = fs.readFileSync(templatePath, "utf8");
+  const configDocument = parseConfigurationDocument(original, configPath);
+  const templateDocument = parseConfigurationDocument(template, templatePath);
+  if (!isMap(configDocument.contents) || !isMap(templateDocument.contents)) {
+    throw new Error(cliText(
+      `Configuration files must contain a YAML mapping: ${configPath}`,
+      `配置文件必须包含 YAML 映射：${configPath}`,
+    ));
+  }
+
+  const updated = mergeMissingConfiguration(
+    configDocument.contents,
+    templateDocument.contents,
+    [],
+  );
+  if (!updated) return { path: configPath, status: "existing" };
+  writeFileAtomically(configPath, configDocument.toString());
+  return { path: configPath, status: "updated" };
+}
+
+function initializeEnv(templatePath: string, envPath: string): InitializedPath {
+  if (!fs.existsSync(envPath)) {
+    const copied = copyIfMissing(templatePath, envPath);
+    if (copied.status === "created") return copied;
+  }
+
+  const original = fs.readFileSync(envPath, "utf8");
+  const template = fs.readFileSync(templatePath, "utf8");
+  const existingKeys = dotEnvKeys(original);
+  const missingLines = template
+    .split(/\r?\n/)
+    .flatMap((line) => {
+      const key = dotEnvAssignmentKey(line);
+      if (!key || existingKeys.has(key)) return [];
+      existingKeys.add(key);
+      return [line];
+    });
+  if (missingLines.length === 0) return { path: envPath, status: "existing" };
+
+  const newline = original.includes("\r\n") ? "\r\n" : "\n";
+  const separator = original.length === 0 || /\r?\n$/u.test(original) ? "" : newline;
+  writeFileAtomically(envPath, `${original}${separator}${missingLines.join(newline)}${newline}`);
+  return { path: envPath, status: "updated" };
+}
+
+function parseConfigurationDocument(contents: string, filePath: string) {
+  const document = parseDocument(contents);
+  if (document.errors.length === 0) return document;
+  throw new Error(cliText(
+    `Could not upgrade configuration file ${filePath}: ${document.errors[0]?.message ?? "invalid YAML"}`,
+    `无法升级配置文件 ${filePath}：${document.errors[0]?.message ?? "YAML 无效"}`,
+  ));
+}
+
+function mergeMissingConfiguration(
+  config: YAMLMap,
+  template: YAMLMap,
+  parentPath: string[],
+): boolean {
+  let updated = false;
+  for (const templatePair of template.items) {
+    const key = yamlMappingKey(templatePair.key);
+    if (!key) continue;
+    if (!config.has(key)) {
+      if (shouldPreserveMissingConfiguration(parentPath, key)) continue;
+      const clonedPair = templatePair.clone();
+      if (parentPath.length === 0 && key === "defaults" && isMap(clonedPair.value)) {
+        clonedPair.value.delete("agent");
+        if (clonedPair.value.items.length === 0) continue;
+      }
+      config.add(clonedPair);
+      updated = true;
+      continue;
+    }
+
+    const configValue = config.get(key, true);
+    if (isMap(configValue) && isMap(templatePair.value)) {
+      updated = mergeMissingConfiguration(configValue, templatePair.value, [...parentPath, key]) || updated;
+    }
+  }
+  return updated;
+}
+
+function shouldPreserveMissingConfiguration(parentPath: string[], key: string): boolean {
+  if (parentPath.length === 1 && parentPath[0] === "agents") return true;
+  return parentPath.length === 1 && parentPath[0] === "defaults" && key === "agent";
+}
+
+function yamlMappingKey(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  return isScalar(value) && typeof value.value === "string" ? value.value : undefined;
+}
+
+function dotEnvKeys(contents: string): Set<string> {
+  return new Set(contents.split(/\r?\n/).flatMap((line) => {
+    const key = dotEnvAssignmentKey(line);
+    return key ? [key] : [];
+  }));
+}
+
+function dotEnvAssignmentKey(line: string): string | undefined {
+  return /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/u.exec(line)?.[1];
+}
+
+function writeFileAtomically(filePath: string, contents: string): void {
+  const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  let temporaryFile: number | undefined;
+  try {
+    temporaryFile = fs.openSync(temporaryPath, "wx", fs.statSync(filePath).mode);
+    fs.writeFileSync(temporaryFile, contents, "utf8");
+    fs.fsyncSync(temporaryFile);
+    fs.closeSync(temporaryFile);
+    temporaryFile = undefined;
+    fs.renameSync(temporaryPath, filePath);
+    syncDirectory(path.dirname(filePath));
+  } finally {
+    if (temporaryFile !== undefined) fs.closeSync(temporaryFile);
+    fs.rmSync(temporaryPath, { force: true });
+  }
+}
+
 function resetProfileContents(
   homePath: string,
   configPath: string,