wave-agent-sdk 1.2.0 → 1.3.0

package/dist/services/configurationService.js

@@ -11,7 +11,7 @@ import { isValidHookEvent } from "../types/hooks.js";
 import { logger } from "../utils/globalLogger.js";
 import { getAllConfigPaths, getExistingConfigPaths, getUserConfigPaths, getProjectConfigPaths, } from "../utils/configPaths.js";
 import { isValidEnvironmentVars, } from "../types/environment.js";
-import { DEFAULT_WAVE_MAX_INPUT_TOKENS, DEFAULT_WAVE_MAX_OUTPUT_TOKENS, DEFAULT_SERVER_URL, } from "../utils/constants.js";
+import { DEFAULT_WAVE_MAX_INPUT_TOKENS, DEFAULT_WAVE_MAX_OUTPUT_TOKENS, DEFAULT_SERVER_URL, DEFAULT_LANGUAGE, } from "../utils/constants.js";
 import { parseCustomHeaders } from "../utils/stringUtils.js";
 import { getRemoteSettingsSync, mergeRemoteSettings, } from "./remoteSettingsService.js";
 import { createAuthAwareFetch } from "./authService.js";
@@ -199,22 +199,38 @@ export class ConfigurationService {
         this._configuredEnvKeys = new Set();
         // Per-session environment snapshot: settings.json `env` is stored here (NOT
         // written to process.env) so multiple sessions in one `wave --stdio` process
-        // don't cross-pollute. Resolve methods read `this.envSnapshot ?? process.env`.
+        // don't cross-pollute. Resolve methods read `this.liveEnvSnapshot ?? process.env`.
         this.envSnapshot = {};
     }
+    /**
+     * Register the turn-snapshot source (see {@link TurnConfigurationSnapshot}).
+     */
+    setTurnSnapshotSource(source) {
+        this.turnSnapshotSource = source;
+    }
     /**
      * Set agent options for configuration resolution
      */
     setOptions(options) {
         this.options = options;
     }
+    /** Configuration the current turn reads from (live configuration outside a turn). */
+    get liveConfiguration() {
+        const snapshot = this.turnSnapshotSource?.();
+        return snapshot ? snapshot.configuration : this.currentConfiguration;
+    }
+    /** Environment snapshot the current turn reads from. */
+    get liveEnvSnapshot() {
+        const snapshot = this.turnSnapshotSource?.();
+        return snapshot ? snapshot.env : this.envSnapshot;
+    }
     /**
      * Returns a copy of the per-session environment snapshot (settings.json `env`).
      * Priority over OS env; does NOT include OS env. For subprocess spawning use
      * {@link getMergedEnv} instead.
      */
     getEnvSnapshot() {
-        return { ...this.envSnapshot };
+        return { ...this.liveEnvSnapshot };
     }
     /**
      * Returns OS env merged with the session snapshot (snapshot wins). Use this
@@ -222,7 +238,7 @@ export class ConfigurationService {
      * so they inherit both OS env and the session's settings env.
      */
     getMergedEnv() {
-        return Object.fromEntries(Object.entries({ ...process.env, ...this.envSnapshot }).filter(([, v]) => v !== undefined));
+        return Object.fromEntries(Object.entries({ ...process.env, ...this.liveEnvSnapshot }).filter(([, v]) => v !== undefined));
     }
     // Core loading operations
     /**
@@ -420,7 +436,7 @@ export class ConfigurationService {
         }
         else {
             resolvedApiKey =
-                this.envSnapshot.WAVE_API_KEY ?? process.env.WAVE_API_KEY;
+                this.liveEnvSnapshot.WAVE_API_KEY ?? process.env.WAVE_API_KEY;
         }
         // Resolve base URL: override > options > env (settings.json) > process.env
         // Note: Explicitly provided empty strings should be treated as invalid, not fall back to env
@@ -433,23 +449,23 @@ export class ConfigurationService {
         }
         else {
             resolvedBaseURL =
-                this.envSnapshot.WAVE_BASE_URL ?? process.env.WAVE_BASE_URL;
+                this.liveEnvSnapshot.WAVE_BASE_URL ?? process.env.WAVE_BASE_URL;
         }
         // Fallback to process.env if still not resolved (for dynamic updates in tests)
         if (resolvedApiKey === undefined) {
             resolvedApiKey =
-                this.envSnapshot.WAVE_API_KEY ?? process.env.WAVE_API_KEY;
+                this.liveEnvSnapshot.WAVE_API_KEY ?? process.env.WAVE_API_KEY;
         }
         if (!resolvedBaseURL) {
             resolvedBaseURL =
-                this.envSnapshot.WAVE_BASE_URL ?? process.env.WAVE_BASE_URL;
+                this.liveEnvSnapshot.WAVE_BASE_URL ?? process.env.WAVE_BASE_URL;
         }
         // Treat empty string as not provided
         if (resolvedBaseURL?.trim() === "") {
             resolvedBaseURL = undefined;
         }
         // Resolve custom headers from environment: env (settings.json) > process.env
-        const envCustomHeaders = this.envSnapshot.WAVE_CUSTOM_HEADERS ??
+        const envCustomHeaders = this.liveEnvSnapshot.WAVE_CUSTOM_HEADERS ??
             process.env.WAVE_CUSTOM_HEADERS ??
             "";
         const parsedEnvHeaders = parseCustomHeaders(envCustomHeaders);
@@ -482,16 +498,16 @@ export class ConfigurationService {
         // If admin wants hard enforcement, they set the `model` scalar field (overwrites local in mergeRemoteSettings).
         const resolvedAgentModel = model ||
             this.options.model ||
-            this.currentConfiguration?.model ||
-            (this.envSnapshot.WAVE_MODEL ?? process.env.WAVE_MODEL);
+            this.liveConfiguration?.model ||
+            (this.liveEnvSnapshot.WAVE_MODEL ?? process.env.WAVE_MODEL);
         // Resolve fast model: override > options > process.env (includes settings.json env)
         const resolvedFastModel = fastModel ||
             this.options.fastModel ||
-            (this.envSnapshot.WAVE_FAST_MODEL ?? process.env.WAVE_FAST_MODEL);
+            (this.liveEnvSnapshot.WAVE_FAST_MODEL ?? process.env.WAVE_FAST_MODEL);
         // Resolve vision model: override > options > process.env (includes settings.json env)
         const resolvedVisionModel = visionModel ||
             this.options.visionModel ||
-            (this.envSnapshot.WAVE_VISION_MODEL ?? process.env.WAVE_VISION_MODEL);
+            (this.liveEnvSnapshot.WAVE_VISION_MODEL ?? process.env.WAVE_VISION_MODEL);
         const baseConfig = {
             model: resolvedAgentModel,
             fastModel: resolvedFastModel,
@@ -500,8 +516,7 @@ export class ConfigurationService {
         };
         // Resolve fast model generation params from models[fastModel].options.
         // Set on baseConfig before the modelSpecificConfig spread so it isn't overwritten.
-        const fastModelSource = resolvedFastModel &&
-            this.currentConfiguration?.models?.[resolvedFastModel];
+        const fastModelSource = resolvedFastModel && this.liveConfiguration?.models?.[resolvedFastModel];
         if (fastModelSource && fastModelSource.options) {
             baseConfig.fastModelOptions = fastModelSource.options;
         }
@@ -514,7 +529,7 @@ export class ConfigurationService {
         }
         // Merge model-specific settings from configuration
         const modelSpecificConfig = resolvedAgentModel &&
-            this.currentConfiguration?.models?.[resolvedAgentModel];
+            this.liveConfiguration?.models?.[resolvedAgentModel];
         if (modelSpecificConfig) {
             const resolved = {
                 ...baseConfig,
@@ -549,14 +564,14 @@ export class ConfigurationService {
         // same chain as resolveModelConfig: caller > options > currentConfiguration > env.
         const resolvedModel = model ||
             this.options.model ||
-            this.currentConfiguration?.model ||
-            (this.envSnapshot.WAVE_MODEL ?? process.env.WAVE_MODEL);
-        const modelConfig = resolvedModel && this.currentConfiguration?.models?.[resolvedModel];
+            this.liveConfiguration?.model ||
+            (this.liveEnvSnapshot.WAVE_MODEL ?? process.env.WAVE_MODEL);
+        const modelConfig = resolvedModel && this.liveConfiguration?.models?.[resolvedModel];
         if (modelConfig && modelConfig.maxInputTokens !== undefined) {
             return modelConfig.maxInputTokens;
         }
         // Try env (settings.json snapshot) first, then process.env
-        const envMaxInputTokens = this.envSnapshot.WAVE_MAX_INPUT_TOKENS ??
+        const envMaxInputTokens = this.liveEnvSnapshot.WAVE_MAX_INPUT_TOKENS ??
             process.env.WAVE_MAX_INPUT_TOKENS;
         if (envMaxInputTokens) {
             const parsed = parseInt(envMaxInputTokens, 10);
@@ -569,9 +584,14 @@ export class ConfigurationService {
     }
     /**
      * Resolves preferred language with fallbacks
-     * Resolution priority: override > options > settings.json > undefined
+     * Resolution priority: override > options > settings.json > default (`zh-CN`)
+     *
+     * 末尾的默认值保证「未设置」时也有明确生效值，且与设置页下拉的默认项一致
+     * （spec agent-config 边界说明「语言默认值」）。调用方不得再假定
+     * 「undefined = 不注入语言指令」。
+     *
      * @param constructorLanguage - Language override (optional)
-     * @returns Resolved language or undefined
+     * @returns Resolved language (never empty)
      */
     resolveLanguage(constructorLanguage) {
         // 1. Override (highest priority)
@@ -582,30 +602,42 @@ export class ConfigurationService {
         if (this.options.language !== undefined) {
             return this.options.language;
         }
-        // 2. settings.json (merged)
-        if (this.currentConfiguration?.language) {
-            return this.currentConfiguration.language;
+        // 3. settings.json (merged)
+        if (this.liveConfiguration?.language) {
+            return this.liveConfiguration.language;
         }
-        return undefined;
+        // 4. Default
+        return DEFAULT_LANGUAGE;
     }
     /**
      * Resolves auto-memory enabled state with fallbacks
-     * Resolution priority: session options (host settings-page value) > settings.json > WAVE_DISABLE_AUTO_MEMORY > default (true)
+     * Resolution priority: session options (session-level override) > settings.json > WAVE_DISABLE_AUTO_MEMORY > default (true)
      * @returns Resolved auto-memory enabled state
      */
     resolveAutoMemoryEnabled() {
-        // 1. Per-session options override (hosts pass the settings-page toggle over
-        //    stdio initialize/updateConfig; Agent.create → setOptions stores it)
+        return this.resolveAutoMemoryEnabledFrom(this.liveConfiguration, this.liveEnvSnapshot);
+    }
+    /**
+     * Same resolution chain but read from the live merged configuration, ignoring
+     * the turn snapshot. The permission safe zone is a live mechanism (like
+     * permission rules, applied by LiveConfigManager on reload), so its sync must
+     * not be pinned to the turn-start value.
+     */
+    resolveAutoMemoryEnabledNow() {
+        return this.resolveAutoMemoryEnabledFrom(this.currentConfiguration, this.envSnapshot);
+    }
+    resolveAutoMemoryEnabledFrom(config, env) {
+        // 1. Per-session options override (session-level override semantics; user
+        //    preferences are no longer passed this way — see core/agent-config.md)
         if (this.options.autoMemoryEnabled !== undefined) {
             return this.options.autoMemoryEnabled;
         }
         // 2. settings.json (merged)
-        if (this.currentConfiguration?.autoMemoryEnabled !== undefined) {
-            return this.currentConfiguration.autoMemoryEnabled;
+        if (config?.autoMemoryEnabled !== undefined) {
+            return config.autoMemoryEnabled;
         }
         // 3. WAVE_DISABLE_AUTO_MEMORY environment variable (settings snapshot > OS env)
-        const disableAutoMemory = this.envSnapshot.WAVE_DISABLE_AUTO_MEMORY ??
-            process.env.WAVE_DISABLE_AUTO_MEMORY;
+        const disableAutoMemory = env.WAVE_DISABLE_AUTO_MEMORY ?? process.env.WAVE_DISABLE_AUTO_MEMORY;
         if (disableAutoMemory === "1" || disableAutoMemory === "true") {
             return false;
         }
@@ -618,7 +650,7 @@ export class ConfigurationService {
      * @returns Resolved worktree base ref
      */
     resolveWorktreeBaseRef() {
-        const baseRef = this.currentConfiguration?.worktree?.baseRef;
+        const baseRef = this.liveConfiguration?.worktree?.baseRef;
         if (baseRef === "head") {
             return "head";
         }
@@ -626,12 +658,13 @@ export class ConfigurationService {
     }
     /**
      * Resolves auto-memory extraction frequency with fallbacks
-     * Resolution priority: session options (host settings-page value) > settings.json > WAVE_AUTO_MEMORY_FREQUENCY > default (1)
+     * Resolution priority: session options (程序化会话级覆盖) > settings.json > WAVE_AUTO_MEMORY_FREQUENCY > default (1)
      * @returns Resolved auto-memory extraction frequency (turns)
      */
     resolveAutoMemoryFrequency() {
-        // 1. Per-session options override (hosts pass the settings-page value over
-        //    stdio initialize/updateConfig; Agent.create → setOptions stores it).
+        // 1. Per-session options override (Agent.create → setOptions 的程序化会话级
+        //    覆盖；三端设置页的值不走这里——它们落用户级 settings.json，由实时重载
+        //    在下一轮生效，见 spec core/agent-config.md「设置实时重载」)。
         //    Only positive values are honored so a malformed 0/negative never
         //    degenerates into per-turn extraction.
         if (this.options.autoMemoryFrequency !== undefined &&
@@ -639,11 +672,11 @@ export class ConfigurationService {
             return this.options.autoMemoryFrequency;
         }
         // 2. settings.json (merged)
-        if (this.currentConfiguration?.autoMemoryFrequency !== undefined) {
-            return this.currentConfiguration.autoMemoryFrequency;
+        if (this.liveConfiguration?.autoMemoryFrequency !== undefined) {
+            return this.liveConfiguration.autoMemoryFrequency;
         }
         // 3. WAVE_AUTO_MEMORY_FREQUENCY environment variable (settings snapshot > OS env)
-        const envFrequency = this.envSnapshot.WAVE_AUTO_MEMORY_FREQUENCY ??
+        const envFrequency = this.liveEnvSnapshot.WAVE_AUTO_MEMORY_FREQUENCY ??
             process.env.WAVE_AUTO_MEMORY_FREQUENCY;
         if (envFrequency) {
             const parsed = parseInt(envFrequency, 10);
@@ -670,7 +703,7 @@ export class ConfigurationService {
             return this.options.maxTokens;
         }
         // Try env (settings.json snapshot) first, then process.env
-        const envMaxOutputTokens = this.envSnapshot.WAVE_MAX_OUTPUT_TOKENS ??
+        const envMaxOutputTokens = this.liveEnvSnapshot.WAVE_MAX_OUTPUT_TOKENS ??
             process.env.WAVE_MAX_OUTPUT_TOKENS;
         if (envMaxOutputTokens) {
             const parsed = parseInt(envMaxOutputTokens, 10);
@@ -682,11 +715,20 @@ export class ConfigurationService {
         return DEFAULT_WAVE_MAX_OUTPUT_TOKENS;
     }
     /**
-     * Set the active model in the session
+     * Set the active model in the session.
+     *
+     * Persisting to `~/.wave/settings.json` is best-effort: the in-memory model
+     * applies immediately, and a failed write (e.g. a locked file / rename EPERM
+     * on Windows) is logged instead of escaping as an unhandled rejection.
      */
-    setModel(model) {
+    async setModel(model) {
         this.options.model = model;
-        this.persistModelToSettings(model);
+        try {
+            await this.persistModelToSettings(model);
+        }
+        catch (error) {
+            logger.warn(`Failed to persist model to settings: ${error}`);
+        }
     }
     async persistModelToSettings(model) {
         const configPath = getUserConfigPaths()[0]; // ~/.wave/settings.json
@@ -714,17 +756,17 @@ export class ConfigurationService {
         const models = new Set();
         // Add current model from options or environment (settings snapshot > OS env)
         const currentModel = this.options.model ||
-            (this.envSnapshot.WAVE_MODEL ?? process.env.WAVE_MODEL);
+            (this.liveEnvSnapshot.WAVE_MODEL ?? process.env.WAVE_MODEL);
         if (currentModel) {
             models.add(currentModel);
         }
         // Persisted model from settings (includes remote-merged)
-        if (this.currentConfiguration?.model) {
-            models.add(this.currentConfiguration.model);
+        if (this.liveConfiguration?.model) {
+            models.add(this.liveConfiguration.model);
         }
         // Add models from merged configuration
-        if (this.currentConfiguration?.models) {
-            Object.keys(this.currentConfiguration.models).forEach((model) => {
+        if (this.liveConfiguration?.models) {
+            Object.keys(this.liveConfiguration.models).forEach((model) => {
                 models.add(model);
             });
         }
@@ -734,7 +776,7 @@ export class ConfigurationService {
      * Get the telemetry config from the loaded settings.
      */
     resolveTelemetryConfig() {
-        return this.currentConfiguration?.monitoring?.telemetry;
+        return this.liveConfiguration?.monitoring?.telemetry;
     }
     /**
      * Resolve all configuration file paths
@@ -934,11 +976,23 @@ export class ConfigurationService {
         }
     }
     /**
-     * Get merged marketplaces from all scopes
+     * Get merged marketplaces from all scopes, with admin-managed (remote) entries
+     * taking precedence per key (spec enterprise server-managed-config「托管配置
+     * 下发插件市场与启用列表」场景 5).
      */
     getMergedMarketplaces(workdir) {
         const mergedConfig = loadMergedWaveConfig(workdir);
-        return mergedConfig?.marketplaces || {};
+        return {
+            ...(mergedConfig?.marketplaces || {}),
+            ...(this.getManagedMarketplaces() || {}),
+        };
+    }
+    /**
+     * Marketplaces declared by the remote (managed) settings. `null` means the
+     * managed layer declares none, leaving the local configuration chain in charge.
+     */
+    getManagedMarketplaces() {
+        return getRemoteSettingsSync()?.marketplaces ?? null;
     }
     /**
      * Get marketplaces at a specific scope
@@ -1059,11 +1113,25 @@ export class ConfigurationService {
         }
     }
     /**
-     * Get merged enabled plugins from all scopes
+     * Get merged enabled plugins from all scopes, with admin-managed (remote)
+     * entries taking precedence per key (spec enterprise server-managed-config
+     * 「托管配置下发插件市场与启用列表」场景 5). A managed `false` therefore
+     * force-disables a plugin no matter what the local files say.
      */
     getMergedEnabledPlugins(workdir) {
         const mergedConfig = loadMergedWaveConfig(workdir);
-        return mergedConfig?.enabledPlugins || {};
+        return {
+            ...(mergedConfig?.enabledPlugins || {}),
+            ...(this.getManagedEnabledPlugins() || {}),
+        };
+    }
+    /**
+     * Enabled-plugin entries declared by the remote (managed) settings. `null`
+     * means the managed layer declares none. Doubles as the authoritative
+     * "is this plugin managed by the organization" lookup (spec plugin A-024).
+     */
+    getManagedEnabledPlugins() {
+        return getRemoteSettingsSync()?.enabledPlugins ?? null;
     }
     /**
      * Load Wave configuration from a JSON file
@@ -1193,6 +1261,7 @@ export function loadWaveConfigFromFile(filePath) {
             marketplaces: config.marketplaces || undefined,
             worktree: config.worktree || undefined,
             enableArtifact: config.enableArtifact !== undefined ? config.enableArtifact : undefined,
+            enableExec: config.enableExec !== undefined ? config.enableExec : undefined,
         };
     }
     catch (error) {
@@ -1344,6 +1413,10 @@ export function loadMergedWaveConfig(workdir) {
         if (config.enableArtifact !== undefined) {
             mergedConfig.enableArtifact = config.enableArtifact;
         }
+        // Merge enableExec (last one wins)
+        if (config.enableExec !== undefined) {
+            mergedConfig.enableExec = config.enableExec;
+        }
         // Merge models
         if (config.models) {
             if (!mergedConfig.models)
@@ -1374,6 +1447,7 @@ export function loadMergedWaveConfig(workdir) {
         language: mergedConfig.language,
         model: mergedConfig.model,
         autoMemoryEnabled: mergedConfig.autoMemoryEnabled,
+        autoMemoryFrequency: mergedConfig.autoMemoryFrequency,
         cleanupPeriodDays: mergedConfig.cleanupPeriodDays,
         marketplaces: mergedConfig.marketplaces &&
             Object.keys(mergedConfig.marketplaces).length > 0
@@ -1384,6 +1458,7 @@ export function loadMergedWaveConfig(workdir) {
             : undefined,
         worktree: mergedConfig.worktree,
         enableArtifact: mergedConfig.enableArtifact,
+        enableExec: mergedConfig.enableExec,
     };
 }
 /**

package/dist/services/contentSummarizer.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared fast-model content processing.
+ *
+ * WebFetch runs every fetched page through a small, fast model, and the
+ * reader-view artifact read summarizes someone else's page the same way.
+ * Both go through this single implementation (prompt → answer).
+ */
+import type { ToolContext, ToolResult } from "../tools/types.js";
+/** Human-readable byte size (e.g. "512B", "2.0KB", "1.5MB"). */
+export declare function formatSize(bytes: number): string;
+/**
+ * Run the fast model over `content` with `prompt` and return its answer as the
+ * tool result. The main model only ever sees this answer.
+ */
+export declare function processContentWithAI(url: string, prompt: string, content: string, statusCode: number, statusText: string, context: ToolContext, contentSize?: number): Promise<ToolResult>;

package/dist/services/contentSummarizer.js

@@ -0,0 +1,45 @@
+/**
+ * Shared fast-model content processing.
+ *
+ * WebFetch runs every fetched page through a small, fast model, and the
+ * reader-view artifact read summarizes someone else's page the same way.
+ * Both go through this single implementation (prompt → answer).
+ */
+/** Human-readable byte size (e.g. "512B", "2.0KB", "1.5MB"). */
+export function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+/**
+ * Run the fast model over `content` with `prompt` and return its answer as the
+ * tool result. The main model only ever sees this answer.
+ */
+export async function processContentWithAI(url, prompt, content, statusCode, statusText, context, contentSize) {
+    if (!context.aiManager || !context.aiService) {
+        return {
+            success: false,
+            content: content,
+            error: "AI Manager or AI Service not available for processing content",
+        };
+    }
+    const modelConfig = context.aiManager.getModelConfig();
+    const fastModel = modelConfig.fastModel;
+    const aiResponse = await context.aiService.processWebContent({
+        gatewayConfig: context.aiManager.getGatewayConfig(),
+        modelConfig: modelConfig,
+        content: content,
+        prompt: prompt,
+        model: fastModel,
+        abortSignal: context.abortSignal,
+    });
+    const sizeStr = contentSize !== undefined ? formatSize(contentSize) : "unknown size";
+    const statusStr = `${statusCode} ${statusText}`.trim();
+    return {
+        success: true,
+        content: aiResponse.content || "",
+        shortResult: `Received ${sizeStr} (${statusStr}) from ${url}`,
+    };
+}

package/dist/services/execAvailability.d.ts

@@ -0,0 +1,9 @@
+/** Code default for Exec availability. */
+export declare const EXEC_DEFAULT_ENABLED = true;
+/**
+ * Whether the Exec tool may be registered for the given workdir.
+ * Resolution order: remote managed settings (`enableExec` from
+ * `GET /api/wave/settings`, admin override) → explicit `enableExec` in local
+ * merged settings → code default.
+ */
+export declare function isExecEnabled(workdir?: string): boolean;

package/dist/services/execAvailability.js

@@ -0,0 +1,32 @@
+/**
+ * Exec feature availability.
+ *
+ * Exec collapses the MCP tool pool into a single scriptable tool, which changes
+ * what the model sees in `tools[]`. It is on by default (the collapse applies
+ * whenever the pool is non-empty — there is no minimum tool count);
+ * `enableExec: false` is the escape hatch for a session that wants the flat MCP
+ * declarations back without downgrading.
+ */
+import { loadMergedWaveConfig } from "./configurationService.js";
+import { getRemoteSettingsSync } from "./remoteSettingsService.js";
+/** Code default for Exec availability. */
+export const EXEC_DEFAULT_ENABLED = true;
+/**
+ * Whether the Exec tool may be registered for the given workdir.
+ * Resolution order: remote managed settings (`enableExec` from
+ * `GET /api/wave/settings`, admin override) → explicit `enableExec` in local
+ * merged settings → code default.
+ */
+export function isExecEnabled(workdir) {
+    const remote = getRemoteSettingsSync();
+    if (remote?.enableExec !== undefined) {
+        return remote.enableExec;
+    }
+    if (workdir) {
+        const config = loadMergedWaveConfig(workdir);
+        if (config?.enableExec !== undefined) {
+            return config.enableExec;
+        }
+    }
+    return EXEC_DEFAULT_ENABLED;
+}

package/dist/services/fileWatcher.js

@@ -5,7 +5,59 @@
  * Handles file watching with debouncing, error recovery, and graceful fallbacks.
  */
 import * as chokidar from "chokidar";
+import * as fs from "fs";
+import * as path from "path";
 import { EventEmitter } from "events";
+/**
+ * Expand a watch path to its canonical long form (Windows only).
+ *
+ * libuv's fs-event backend resolves each event path with `GetLongPathNameW()`
+ * and then asserts the result is prefixed by the watched directory string
+ * (`uv__relative_path()`, src\win\fs-event.c). libuv <= 1.51 expanded the
+ * watched directory itself; 1.52 dropped that step (it ships with Node 24.16+,
+ * 26.x, and Electron 43 — which bundles Node 24.18), so `handle->dirw`
+ * keeps whatever the caller passed, and watching an 8.3 short path
+ * (`C:\Users\LIUYIQ~1\...` — what %TEMP% yields when it is configured with a
+ * short name) aborts the whole process on the first event. The abort is not a
+ * catchable error, so the root must be canonicalized before it reaches
+ * chokidar. `fs.realpathSync()` alone is not enough: only the `.native()`
+ * variant expands short names.
+ *
+ * Paths that don't exist yet (`~/.wave/settings.json` on a fresh install) are
+ * handled by expanding the nearest existing ancestor and appending the
+ * remaining segments back; if nothing can be resolved the input is returned
+ * unchanged.
+ */
+function toLongFormPath(target) {
+    if (process.platform !== "win32")
+        return target;
+    // Only drive-qualified (`C:\...`) and UNC (`\\server\share`) paths are real
+    // Windows paths. POSIX-style input (what tests and other platforms use) is
+    // passed through untouched rather than re-rooted onto the current drive.
+    if (!/^[a-zA-Z]:[\\/]/.test(target) && !target.startsWith("\\\\")) {
+        return target;
+    }
+    let candidate = target;
+    const missing = [];
+    for (;;) {
+        try {
+            const resolved = fs.realpathSync.native(candidate);
+            return missing.length > 0 ? path.join(resolved, ...missing) : resolved;
+        }
+        catch {
+            const parent = path.dirname(candidate);
+            if (parent === candidate)
+                return target;
+            missing.unshift(path.basename(candidate));
+            candidate = parent;
+        }
+    }
+}
+/** Whether `filePath` (slash-normalized) is the watched root or inside it. */
+function isWithin(filePath, root) {
+    const normalizedRoot = root.replace(/\\/g, "/");
+    return (filePath === normalizedRoot || filePath.startsWith(normalizedRoot + "/"));
+}
 export class FileWatcherService extends EventEmitter {
     constructor(logger, config) {
         super();
@@ -38,6 +90,7 @@ export class FileWatcherService extends EventEmitter {
             // Create new watcher entry
             const entry = {
                 path,
+                watchPath: toLongFormPath(path),
                 watcher: null,
                 isActive: false,
                 lastEvent: Date.now(),
@@ -64,7 +117,7 @@ export class FileWatcherService extends EventEmitter {
             return;
         try {
             if (entry.watcher) {
-                entry.watcher.unwatch(path);
+                entry.watcher.unwatch(entry.watchPath);
             }
             this.watchers.delete(path);
         }
@@ -148,7 +201,7 @@ export class FileWatcherService extends EventEmitter {
                 this.setupGlobalWatcherEvents();
             }
             // Add path to global watcher
-            this.globalWatcher.add(entry.path);
+            this.globalWatcher.add(entry.watchPath);
             entry.watcher = this.globalWatcher;
             entry.isActive = true;
             entry.errorCount = 0;
@@ -207,12 +260,14 @@ export class FileWatcherService extends EventEmitter {
             timestamp: Date.now(),
             size: stats?.size,
         };
-        // Notify all watchers that match the path or are parents of the path
+        // Notify all watchers that match the path or are parents of the path.
+        // Events arrive under whichever form chokidar was given (the long form on
+        // Windows), while entries are keyed by the caller's original path, so both
+        // have to be considered.
         for (const [watchedPath, entry] of this.watchers.entries()) {
             const normalizedFilePath = filePath.replace(/\\/g, "/");
-            const normalizedWatchedPath = watchedPath.replace(/\\/g, "/");
-            if (normalizedFilePath === normalizedWatchedPath ||
-                normalizedFilePath.startsWith(normalizedWatchedPath + "/")) {
+            if (isWithin(normalizedFilePath, watchedPath) ||
+                isWithin(normalizedFilePath, entry.watchPath)) {
                 entry.lastEvent = event.timestamp;
                 // Notify all callbacks for this watcher
                 for (const callback of entry.callbacks) {