wave-agent-sdk 0.18.7 → 0.19.0

package/src/agent.ts

@@ -41,6 +41,7 @@ import { SkillManager } from "./managers/skillManager.js";
 import { TaskManager } from "./services/taskManager.js";
 import { btw } from "./services/aiService.js";
 import { convertMessagesForAPI } from "./utils/convertMessagesForAPI.js";
+import { supportsVision } from "./utils/modelCapabilities.js";
 import { parseTaskNotificationXml } from "./utils/notificationXml.js";
 import { InitializationService } from "./services/initializationService.js";
 import { InteractionService } from "./services/interactionService.js";
@@ -598,17 +599,20 @@ export class Agent {
       options,
     );
 
-    // Initialize OpenTelemetry (non-blocking, graceful degradation)
+    // Initialize OpenTelemetry (awaited to ensure ALS context is ready before
+    // startInteractionSpan is called, preventing trace context fragmentation)
     const telemetryConfig = this.configurationService.resolveTelemetryConfig();
-    initializeTelemetry(telemetryConfig).catch((error) => {
+    try {
+      await initializeTelemetry(telemetryConfig);
+    } catch (error) {
       this.logger?.warn("Telemetry initialization failed:", error);
-    });
+    }
 
     // Log session_start event
     try {
       const modelConfig = this.getModelConfig();
       if (modelConfig.model) {
-        logOTelEvent("session_start", {
+        await logOTelEvent("session_start", {
           sessionId: this.messageManager.getSessionId(),
           model: modelConfig.model,
           workdir: this.workdir,
@@ -992,7 +996,9 @@ export class Agent {
    * @returns Promise that resolves to the AI's answer
    */
   public async askBtw(question: string): Promise<string> {
-    const messages = convertMessagesForAPI(this.messageManager.getMessages());
+    const messages = convertMessagesForAPI(this.messageManager.getMessages(), {
+      supportsVision: supportsVision(this.getModelConfig().capabilities),
+    });
     const result = await btw({
       gatewayConfig: this.getGatewayConfig(),
       modelConfig: this.getModelConfig(),

package/src/index.ts

@@ -14,6 +14,7 @@ export * from "./managers/messageQueue.js";
 // Export all utilities
 export * from "./utils/bashParser.js";
 export * from "./utils/convertMessagesForAPI.js";
+export * from "./utils/modelCapabilities.js";
 export * from "./utils/fileSearch.js";
 export * from "./utils/globalLogger.js";
 export * from "./utils/mcpUtils.js";

package/src/managers/aiManager.ts

@@ -1,6 +1,7 @@
 import { type CallAgentOptions } from "../services/aiService.js";
 import * as aiService from "../services/aiService.js";
 import { convertMessagesForAPI } from "../utils/convertMessagesForAPI.js";
+import { supportsVision } from "../utils/modelCapabilities.js";
 import { parseTaskNotificationXml } from "../utils/notificationXml.js";
 import { calculateComprehensiveTotalTokens } from "../utils/tokenCalculation.js";
 import { estimateTokens } from "../utils/tokenEstimate.js";
@@ -45,6 +46,7 @@ import {
   endInteractionSpan,
   startLLMRequestSpan,
   endLLMRequestSpan,
+  resetTracingState,
 } from "../telemetry/sessionTracing.js";
 import { logOTelEvent } from "../telemetry/events.js";
 
@@ -492,7 +494,7 @@ export class AIManager {
       );
 
       // 7. Execute message reconstruction
-      this.messageManager.compactMessagesAndUpdateSession(
+      await this.messageManager.compactMessagesAndUpdateSession(
         enhancedSummary,
         compactUsage,
       );
@@ -523,6 +525,9 @@ export class AIManager {
 
       this.consecutiveCompactionFailures = 0;
 
+      // Reset incremental tracing state after compaction
+      resetTracingState();
+
       // 9. Log OTEL event
       logOTelEvent("compaction", {
         beforeTokens: String(messagesToCompact.length),
@@ -838,7 +843,10 @@ export class AIManager {
 
           // Get recent message history
           const rawMessages = this.messageManager.getMessages();
-          const recentMessages = convertMessagesForAPI(rawMessages);
+          const currentModelConfig = this.getModelConfig();
+          const recentMessages = convertMessagesForAPI(rawMessages, {
+            supportsVision: supportsVision(currentModelConfig.capabilities),
+          });
 
           // Track if assistant message has been created
           let assistantMessageCreated = false;
@@ -953,6 +961,17 @@ export class AIManager {
 
           llmSpan = startLLMRequestSpan(
             model || this.getModelConfig().model || "",
+            {
+              context: "interaction",
+              systemPrompt:
+                typeof callAgentOptions.systemPrompt === "string"
+                  ? callAgentOptions.systemPrompt
+                  : undefined,
+              inputMessages: callAgentOptions.messages,
+              toolsSchema: callAgentOptions.tools
+                ? JSON.stringify(callAgentOptions.tools)
+                : undefined,
+            },
           );
 
           const result = await aiService.callAgent(callAgentOptions);
@@ -966,6 +985,7 @@ export class AIManager {
             outputTokens: result.usage?.completion_tokens,
             cacheReadTokens: result.usage?.cache_read_input_tokens,
             cacheCreationTokens: result.usage?.cache_creation_input_tokens,
+            modelOutput: result.content,
           });
 
           const createdByStreaming = assistantMessageCreated;

package/src/managers/mcpManager.ts

@@ -725,11 +725,17 @@ export class McpManager {
     }
   }
 
-  // Get all tools from connected servers
+  // Get all tools from connected servers.
+  // "reconnecting" servers retain their last-known tool snapshot so that
+  // transient SSE disconnects don't churn the tool list (which would bust
+  // the prompt cache). Tools are only dropped once the server truly fails
+  // (status "error"/"disconnected").
   getAllConnectedTools(): McpTool[] {
     const allTools: McpTool[] = [];
     for (const server of this.servers.values()) {
-      if (server.status === "connected" && server.tools) {
+      const usable =
+        server.status === "connected" || server.status === "reconnecting";
+      if (usable && server.tools) {
         allTools.push(...server.tools);
       }
     }

package/src/managers/messageManager.ts

@@ -94,8 +94,6 @@ export interface MessageManagerOptions {
 export class MessageManager {
   // Private state properties
   private sessionId: string;
-  private rootSessionId: string;
-  private parentSessionId?: string;
   private messages: Message[];
   private latestTotalTokens: number;
   private workdir: string;
@@ -118,7 +116,6 @@ export class MessageManager {
     options: MessageManagerOptions,
   ) {
     this.sessionId = generateSessionId();
-    this.rootSessionId = this.sessionId;
     this.messages = [];
     this.latestTotalTokens = 0;
     this.workdir = options.workdir;
@@ -152,11 +149,7 @@ export class MessageManager {
   }
 
   public getRootSessionId(): string {
-    return this.rootSessionId;
-  }
-
-  public getParentSessionId(): string | undefined {
-    return this.parentSessionId;
+    return this.sessionId;
   }
 
   public getMessages(): Message[] {
@@ -358,8 +351,6 @@ export class MessageManager {
         unsavedMessages,
         this.workdir,
         this.sessionType,
-        this.rootSessionId,
-        this.parentSessionId,
       );
 
       // Update the saved message count
@@ -383,7 +374,6 @@ export class MessageManager {
   public clearMessages(): void {
     this.setMessages([]);
     const newSessionId = generateSessionId();
-    this.rootSessionId = newSessionId;
     this.setSessionId(newSessionId);
     this.setlatestTotalTokens(0);
     this.savedMessageCount = 0; // Reset saved message count
@@ -399,8 +389,6 @@ export class MessageManager {
   // Initialize state from session data
   public initializeFromSession(sessionData: SessionData): void {
     this.setSessionId(sessionData.id);
-    this.rootSessionId = sessionData.rootSessionId || sessionData.id;
-    this.parentSessionId = sessionData.parentSessionId;
     this.setMessages([...sessionData.messages]);
     this.setlatestTotalTokens(sessionData.metadata.latestTotalTokens);
 
@@ -563,12 +551,13 @@ export class MessageManager {
   }
 
   /**
-   * Compact messages and update session, delete compacted messages, only keep compacted messages and last 3 messages
+   * Compact messages and update session — append compact message to same file (append-only).
+   * After compaction, in-memory messages are [compactMessage, ...lastThreeMessages].
    */
-  public compactMessagesAndUpdateSession(
+  public async compactMessagesAndUpdateSession(
     compactedContent: string,
     usage?: Usage,
-  ): void {
+  ): Promise<void> {
     // Get last 2 API rounds to preserve (structurally safe boundary)
     const lastThreeMessages = getLastApiRounds(this.messages, 2);
 
@@ -580,23 +569,27 @@ export class MessageManager {
         {
           type: "compact",
           content: compactedContent,
-          sessionId: this.sessionId,
         },
       ],
       timestamp: new Date().toISOString(),
       ...(usage && { usage }),
     };
 
-    // Build new message array: keep the compacted message and last 3 messages
+    // Build new message array: keep the compacted message and last messages
     const newMessages: Message[] = [compactMessage, ...lastThreeMessages];
 
-    // Update sessionId and parentSessionId
-    const oldSessionId = this.sessionId;
-    this.setSessionId(generateSessionId());
-    this.parentSessionId = oldSessionId;
+    // APPEND to the same session file (append-only, like Claude Code)
+    const { appendMessages } = await import("../services/session.js");
+    await appendMessages(
+      this.sessionId,
+      newMessages,
+      this.workdir,
+      this.sessionType,
+    );
 
-    // Set new message list
+    // Update in-memory state
     this.setMessages(newMessages);
+    this.savedMessageCount = newMessages.length;
 
     // Clear and rebuild loaded rule IDs from remaining meta messages
     this.clearLoadedRuleIds();
@@ -911,101 +904,26 @@ export class MessageManager {
     index: number,
     reversionManager?: import("./reversionManager.js").ReversionManager,
   ): Promise<void> {
-    const { messages, sessionIds } = await this.getFullMessageThread();
+    const { messages } = await this.getFullMessageThread();
 
     if (index < 0 || index >= messages.length) {
       throw new Error(`Invalid message index: ${index}`);
     }
 
-    // Find which session the index belongs to
-    let targetSessionId = this.sessionId;
-    let targetIndexInSession = index;
-
-    // We need to be careful here because loadFullMessageThread might have removed "compact" blocks
-    // Let's re-calculate based on the actual messages returned.
-    // Actually, it's easier to just load sessions one by one again or keep track of counts.
-
-    // For simplicity, let's assume we want to truncate the WHOLE thread.
-    // If the index is in a previous session, we need to:
-    // 1. Load that session.
-    // 2. Truncate it.
-    // 3. Make it the current session.
-    // 4. Delete/Invalidate subsequent sessions.
-
-    // To correctly map 'index' to a session, we need to know the message count of each session
-    // as they appear in the concatenated 'messages' array.
-
-    let remainingIndex = index;
-    const { loadSessionFromJsonl } = await import("../services/session.js");
-
-    for (const sid of sessionIds) {
-      const sessionData = await loadSessionFromJsonl(sid, this.workdir);
-      if (!sessionData) continue;
-
-      const sessionMessages = sessionData.messages;
-      // If this is not the first session in the thread, it might have a compact block at the start
-      // that was removed in getFullMessageThread.
-      const hasCompactBlock = sessionMessages[0]?.blocks.some(
-        (b) => b.type === "compact",
-      );
-      const effectiveMessages =
-        hasCompactBlock && sid !== sessionIds[0]
-          ? sessionMessages.slice(1)
-          : sessionMessages;
-
-      if (remainingIndex < effectiveMessages.length) {
-        targetSessionId = sid;
-        targetIndexInSession = hasCompactBlock
-          ? remainingIndex + 1
-          : remainingIndex;
-        break;
-      }
-      remainingIndex -= effectiveMessages.length;
-    }
-
-    // Load the target session to perform truncation
-    const targetSessionData = await loadSessionFromJsonl(
-      targetSessionId,
-      this.workdir,
-    );
-    if (!targetSessionData)
-      throw new Error(`Target session ${targetSessionId} not found`);
-
-    // Identify messages to be removed (from the whole thread)
+    const newMessages = messages.slice(0, index);
     const messagesToRemove = messages.slice(index);
     const messageIdsToRemove = messagesToRemove
       .map((m) => m.id as string)
       .filter((id) => !!id);
 
-    // Revert file changes if manager is provided
     if (reversionManager && messageIdsToRemove.length > 0) {
       await reversionManager.revertTo(messageIdsToRemove, messages);
     }
 
-    // Truncate messages in the target session
-    const newMessagesInSession = targetSessionData.messages.slice(
-      0,
-      targetIndexInSession,
-    );
-
-    // Update target session file
-    this.sessionId = targetSessionId;
-    this.rootSessionId = targetSessionData.rootSessionId || targetSessionId;
-    this.parentSessionId = targetSessionData.parentSessionId;
-    this.transcriptPath = this.computeTranscriptPath();
-
-    await this.rewriteSessionFile(newMessagesInSession);
-
-    // Update in-memory messages to the truncated session messages
-    // We do NOT include ancestor messages here to avoid exceeding context limits.
-    // The 'compact' block at the start of the session (if any) already summarizes them.
-    this.setMessages(newMessagesInSession);
-
-    // Update saved message count
-    this.savedMessageCount = newMessagesInSession.length;
-
-    // Notify session ID change if it changed
-    this.callbacks.onSessionIdChange?.(this.sessionId);
+    // Rewrite file with truncated messages
+    await this.rewriteSessionFile(newMessages);
+    this.setMessages(newMessages);
+    this.savedMessageCount = newMessages.length;
   }
 
   /**

package/src/managers/skillManager.ts

@@ -30,6 +30,7 @@ import { logger } from "../utils/globalLogger.js";
 export class SkillManager extends EventEmitter {
   private personalSkillsPath: string;
   private personalClaudeSkillsPath: string;
+  private personalAgentsSkillsPath: string;
   private scanTimeout: number;
   private workdir: string;
 
@@ -50,6 +51,8 @@ export class SkillManager extends EventEmitter {
       options.personalSkillsPath || join(homedir(), ".wave", "skills");
     this.personalClaudeSkillsPath =
       options.personalClaudeSkillsPath || join(homedir(), ".claude", "skills");
+    this.personalAgentsSkillsPath =
+      options.personalAgentsSkillsPath || join(homedir(), ".agents", "skills");
     this.scanTimeout = options.scanTimeout || 5000;
     this.workdir = options.workdir || process.cwd();
     this.watchEnabled = options.watch ?? false;
@@ -131,8 +134,10 @@ export class SkillManager extends EventEmitter {
     const pathsToWatch = [
       this.personalSkillsPath,
       this.personalClaudeSkillsPath,
+      this.personalAgentsSkillsPath,
       join(this.workdir, ".wave", "skills"),
       join(this.workdir, ".claude", "skills"),
+      join(this.workdir, ".agents", "skills"),
     ];
 
     logger?.debug(`Setting up skill watcher for: ${pathsToWatch.join(", ")}`);
@@ -225,6 +230,11 @@ export class SkillManager extends EventEmitter {
       "builtin",
     );
 
+    const personalAgentsCollection = await this.discoverSkillCollection(
+      this.personalAgentsSkillsPath,
+      "personal",
+    );
+
     const personalClaudeCollection = await this.discoverSkillCollection(
       this.personalClaudeSkillsPath,
       "personal",
@@ -243,12 +253,14 @@ export class SkillManager extends EventEmitter {
     return {
       builtinSkills: builtinCollection.skills,
       personalSkills: new Map([
-        ...personalClaudeCollection.skills,
+        ...personalAgentsCollection.skills, // lowest priority
+        ...personalClaudeCollection.skills, // overrides .agents
         ...personalCollection.skills, // .wave overrides .claude
       ]),
       projectSkills: projectCollection.skills,
       errors: [
         ...builtinCollection.errors,
+        ...personalAgentsCollection.errors,
         ...personalClaudeCollection.errors,
         ...personalCollection.errors,
         ...projectCollection.errors,
@@ -271,9 +283,11 @@ export class SkillManager extends EventEmitter {
     };
 
     if (type === "project") {
-      // Scan .claude/skills first, then .wave/skills (wave overrides)
+      // Scan .agents/skills first, then .claude/skills, then .wave/skills (wave overrides)
+      const agentsPath = join(basePath, ".agents", "skills");
       const claudePath = join(basePath, ".claude", "skills");
       const wavePath = join(basePath, ".wave", "skills");
+      await this.scanSkillPath(agentsPath, collection);
       await this.scanSkillPath(claudePath, collection);
       await this.scanSkillPath(wavePath, collection);
     } else {

package/src/prompts/index.ts

@@ -19,7 +19,11 @@ import {
   GREP_TOOL_NAME,
 } from "../constants/tools.js";
 
-export const BASE_SYSTEM_PROMPT = `You are an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.`;
+export const BASE_SYSTEM_PROMPT = `You are a coding agent developed by NetEase that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.`;
+
+export const MODEL_IDENTITY_PROMPT = `# Model identity
+
+If asked about your model, model version, underlying architecture, or product name, identify yourself simply as a coding agent developed by NetEase. Do not reveal the specific model ID, model family, model provider, or product name. Do not mention or hint at any of these details.`;
 
 export const DOING_TASKS_PROMPT = `# Doing tasks
 - The user will primarily request you to perform software engineering tasks. These may include solving bugs, adding new functionality, refactoring code, explaining code, and more. When given an unclear or generic instruction, consider it in the context of these software engineering tasks and the current working directory. For example, if the user asks you to change "methodName" to snake case, do not reply with just "method_name", instead find the method in the code and modify the code.
@@ -265,6 +269,7 @@ export function buildSystemPrompt(
 
   staticText += `\n\n${OUTPUT_EFFICIENCY_PROMPT}`;
   staticText += `\n\n${TONE_AND_STYLE_PROMPT}`;
+  staticText += `\n\n${MODEL_IDENTITY_PROMPT}`;
 
   const blocks: SystemPromptBlock[] = [{ text: staticText, cacheable: true }];
 

package/src/services/aiService.ts

@@ -13,11 +13,11 @@ import type { GatewayConfig, ModelConfig } from "../types/index.js";
 import { ConfigurationError, CONFIG_ERRORS } from "../types/index.js";
 import {
   transformMessagesForExplicitCache,
-  supportsPromptCaching,
   extendUsageWithCacheMetrics,
   type ClaudeUsage,
   type ClaudeChatCompletionContentPartText,
 } from "../utils/cacheControlUtils.js";
+import { supportsPromptCaching } from "../utils/modelCapabilities.js";
 
 import * as os from "os";
 import * as fs from "fs";
@@ -265,13 +265,12 @@ export async function callAgent(
     });
 
     // Determine model early (needed for system prompt construction)
-    const currentModel = model || modelConfig.model;
     const resolvedMaxTokens = options.maxTokens ?? modelConfig.maxTokens;
 
     // Build system message content
     let systemMessage: ChatCompletionMessageParam;
     if (Array.isArray(systemPrompt)) {
-      if (supportsPromptCaching(currentModel)) {
+      if (supportsPromptCaching(modelConfig.capabilities)) {
         // For Claude models, map blocks to content parts with cache_control on cacheable blocks
         const contentParts: ClaudeChatCompletionContentPartText[] =
           systemPrompt.map((block) => {
@@ -307,10 +306,10 @@ export async function callAgent(
 
     processedTools = tools;
 
-    if (supportsPromptCaching(currentModel)) {
+    if (supportsPromptCaching(modelConfig.capabilities)) {
       openaiMessages = transformMessagesForExplicitCache(
         openaiMessages,
-        currentModel,
+        modelConfig.capabilities,
       );
     }
 
@@ -320,12 +319,14 @@ export async function callAgent(
       fastModel: _fastModel,
       maxTokens: _maxTokens,
       permissionMode: _permissionMode,
+      capabilities: _capabilities,
       ...extraParams
     } = modelConfig;
     void _model;
     void _fastModel;
     void _maxTokens;
     void _permissionMode;
+    void _capabilities;
 
     const openaiModelConfig = getModelConfig(model || modelConfig.model, {
       max_tokens: resolvedMaxTokens,
@@ -866,6 +867,7 @@ export async function compactMessages(
     fastModel: _fastModel,
     maxTokens: _maxTokens,
     permissionMode: _permissionMode,
+    capabilities: _capabilities,
     fastModelConfig: _fastModelConfig,
     ...extraParams
   } = modelConfig;
@@ -873,6 +875,7 @@ export async function compactMessages(
   void _fastModel;
   void _maxTokens;
   void _permissionMode;
+  void _capabilities;
 
   // When a fast model override is provided, use the fast model's hyperparams
   // (if configured); otherwise fall back to the agent model's extraParams.
@@ -989,6 +992,7 @@ export async function processWebContent(
     fastModel: _fastModel,
     maxTokens: _maxTokens,
     permissionMode: _permissionMode,
+    capabilities: _capabilities,
     fastModelConfig: _fastModelConfig,
     ...extraParams
   } = modelConfig;
@@ -996,6 +1000,7 @@ export async function processWebContent(
   void _fastModel;
   void _maxTokens;
   void _permissionMode;
+  void _capabilities;
 
   // When a fast model override is provided, use the fast model's hyperparams
   // (if configured); otherwise fall back to the agent model's extraParams.
@@ -1106,12 +1111,14 @@ export async function btw(options: BtwOptions): Promise<BtwResult> {
     fastModel: _fastModel,
     maxTokens: _maxTokens,
     permissionMode: _permissionMode,
+    capabilities: _capabilities,
     ...extraParams
   } = modelConfig;
   void _model;
   void _fastModel;
   void _maxTokens;
   void _permissionMode;
+  void _capabilities;
 
   const openaiModelConfig = getModelConfig(options.model || modelConfig.model, {
     temperature: 0.1,

package/src/services/configurationService.ts

@@ -48,6 +48,7 @@ import {
 } from "./remoteSettingsService.js";
 import { createAuthAwareFetch } from "./authService.js";
 import { ensureWaveRuntimeFilesExcluded } from "../utils/gitUtils.js";
+import { atomicWriteFile } from "../utils/atomicWrite.js";
 
 /**
  * Default ConfigurationService implementation
@@ -545,12 +546,14 @@ export class ConfigurationService {
         fastModel: _ffm,
         maxTokens: _fmt,
         permissionMode: _fpm,
+        capabilities: _fcap,
         ...fastHyperparams
       } = fastModelConfigSource;
       void _fm;
       void _ffm;
       void _fmt;
       void _fpm;
+      void _fcap;
       baseConfig.fastModelConfig = fastHyperparams;
     }
 
@@ -729,7 +732,7 @@ export class ConfigurationService {
     }
 
     config.model = model;
-    await fs.writeFile(configPath, JSON.stringify(config, null, 2), "utf-8");
+    await atomicWriteFile(configPath, JSON.stringify(config, null, 2));
   }
 
   /**
@@ -816,11 +819,7 @@ export class ConfigurationService {
 
     if (!config.permissions.allow.includes(rule)) {
       config.permissions.allow.push(rule);
-      await fs.writeFile(
-        localConfigPath,
-        JSON.stringify(config, null, 2),
-        "utf-8",
-      );
+      await atomicWriteFile(localConfigPath, JSON.stringify(config, null, 2));
     }
   }
 
@@ -868,7 +867,7 @@ export class ConfigurationService {
 
     config.enabledPlugins[pluginId] = enabled;
 
-    await fs.writeFile(configPath, JSON.stringify(config, null, 2), "utf-8");
+    await atomicWriteFile(configPath, JSON.stringify(config, null, 2));
   }
 
   /**
@@ -940,11 +939,7 @@ export class ConfigurationService {
     }
     fileConfig.marketplaces[name] = config;
 
-    await fs.writeFile(
-      configPath,
-      JSON.stringify(fileConfig, null, 2),
-      "utf-8",
-    );
+    await atomicWriteFile(configPath, JSON.stringify(fileConfig, null, 2));
   }
 
   /**
@@ -978,11 +973,7 @@ export class ConfigurationService {
 
       if (fileConfig.marketplaces && name in fileConfig.marketplaces) {
         delete fileConfig.marketplaces[name];
-        await fs.writeFile(
-          configPath,
-          JSON.stringify(fileConfig, null, 2),
-          "utf-8",
-        );
+        await atomicWriteFile(configPath, JSON.stringify(fileConfig, null, 2));
       }
     } catch {
       // Ignore errors for corrupted or non-existent files
@@ -1020,11 +1011,7 @@ export class ConfigurationService {
 
       if (config.enabledPlugins && pluginId in config.enabledPlugins) {
         delete config.enabledPlugins[pluginId];
-        await fs.writeFile(
-          configPath,
-          JSON.stringify(config, null, 2),
-          "utf-8",
-        );
+        await atomicWriteFile(configPath, JSON.stringify(config, null, 2));
       }
     } catch {
       // Ignore errors for corrupted or non-existent files
@@ -1171,6 +1158,15 @@ export function loadWaveConfigFromFile(
 
   try {
     const content = readFileSync(filePath, "utf-8");
+
+    // Tolerate empty/whitespace-only files: a concurrent writer may have the
+    // file truncated mid-write. Returning null lets callers skip this source
+    // instead of crashing (consistent with the "file not found" path).
+    if (content.trim() === "") {
+      logger.warn(`Empty configuration file (likely mid-write): ${filePath}`);
+      return null;
+    }
+
     const config = JSON.parse(content) as WaveConfiguration;
 
     return {
@@ -1189,10 +1185,14 @@ export function loadWaveConfigFromFile(
     };
   } catch (error) {
     if (error instanceof SyntaxError) {
-      throw new Error(`Invalid JSON syntax in ${filePath}: ${error.message}`);
+      // Tolerate corrupt JSON: a concurrent writer may leave the file in a
+      // partially-written state. Warn and return null so callers skip this
+      // source instead of crashing.
+      logger.warn(`Invalid JSON syntax in ${filePath}: ${error.message}`);
+      return null;
     }
 
-    // Re-throw validation errors and other errors as-is
+    // Re-throw other errors as-is
     throw error;
   }
 }