wave-agent-sdk 1.1.2 → 1.1.4

package/dist/builtin/skills/settings.js

@@ -164,9 +164,13 @@ Wave provides detailed context to hook processes via \`stdin\` as a JSON object.
 - \`new_cwd\`: (CwdChanged) The new working directory.
 - \`compact_instructions\`: (PreCompact) Custom instructions for the compaction, if any.
 - \`compact_summary\`: (PostCompact) The AI-generated compaction summary text.
-- \`source\`: (SessionStart) The session start source: \`"startup"\`, \`"resume"\`, or \`"compact"\`.
+- \`background_tasks\`: (Stop) Snapshot of running background tasks (array of \`{id, type: "shell"|"subagent"|"workflow", status, description, command?, startedAt}\`).
+- \`session_crons\`: (Stop) Snapshot of session-scoped cron jobs (array of \`{name, schedule, prompt}\`).
+- \`last_assistant_message\`: (Stop, SubagentStop) Text content of the last assistant message.
+- \`plan_file_path\`: (Present when in plan mode) Path to the active plan file.
+- \`source\`: (SessionStart) The session start source: \`"startup"\`, \`"resume"\`, \`"compact"\`, or \`"clear"\`.
 - \`agent_type\`: (SessionStart) The agent type identifier.
-- \`end_source\`: (SessionEnd) The session end source: \`"exit"\`, \`"stop"\`, or \`"compact"\`.
+- \`end_source\`: (SessionEnd) The session end source: \`"exit"\`, \`"resume"\`, \`"stop"\`, \`"compact"\`, or \`"clear"\`.
 
 ## Hook Exit Codes
 
@@ -1049,6 +1053,7 @@ For detailed guidance on creating plugins and marketplaces, see [PLUGINS.md](\${
 - \`autoMemoryEnabled\`: Enable or disable auto-memory (default: \`true\`).
 - \`autoMemoryFrequency\`: Frequency of auto-memory extraction turns (default: \`1\`).
 - \`enableArtifact\`: Enable the Artifact tool, which publishes local \`.html\`/\`.md\` files as shareable (default-private) web pages. Defaults to \`false\` while the frame backend is not live; set to \`true\` to register the tool and enable WebFetch interception for artifact URLs. Toggling it hot-reloads the tool registry.
+- \`worktree.baseRef\`: Base ref for new worktrees. \`"fresh"\` (default) creates a new branch from \`origin/<default branch>\`; \`"head"\` branches from the current local HEAD, skipping origin resolution and network fetch. Use \`"head"\` when working from un-pushed local branches.
 
 \`\`\`json
 {

package/dist/managers/aiManager.js

@@ -3,7 +3,7 @@ import { convertMessagesForAPI } from "../utils/convertMessagesForAPI.js";
 import { supportsVision } from "../utils/modelCapabilities.js";
 import { persistToolImages } from "../utils/toolImagePersistence.js";
 import { parseTaskNotificationXml, taskNotificationToXml, } from "../utils/notificationXml.js";
-import { calculateComprehensiveTotalTokens, estimateContextTokens, } from "../utils/tokenCalculation.js";
+import { estimateContextTokens } from "../utils/tokenCalculation.js";
 import { estimateTokens } from "../utils/tokenEstimate.js";
 import { getTaskReminderTurnCounts, maybeInjectTaskReminder, TASK_REMINDER_CONFIG, } from "../utils/taskReminder.js";
 import { createWriteStream, existsSync } from "node:fs";
@@ -370,16 +370,16 @@ export class AIManager {
         return "";
     }
     // Private method to update the displayed token statistics from a response.
-    // The comprehensive value (including cache tokens) is intentionally kept:
-    // it drives cost/usage display. Auto-compaction is NOT decided here — it
-    // happens pre-request via maybeAutoCompactBeforeRequest so that over-limit
-    // requests never go out (aligned with Claude Code's proactive autocompact).
+    // Uses only total_tokens — OpenAI-compatible usage already includes cache
+    // hits there, so adding cache fields would double-count and show an
+    // inflated context percentage. Same semantics as the auto-compaction
+    // threshold (maybeAutoCompactBeforeRequest), keeping display and
+    // compaction judgment consistent.
     updateLatestTotalTokens(usage) {
         if (!usage)
             return;
-        // Update token statistics - display comprehensive token usage including cache tokens
-        const comprehensiveTotalTokens = calculateComprehensiveTotalTokens(usage);
-        this.messageManager.setlatestTotalTokens(comprehensiveTotalTokens);
+        // Update token statistics - display total_tokens (cache fields excluded)
+        this.messageManager.setlatestTotalTokens(usage.total_tokens);
     }
     /**
      * Pre-request auto-compaction check (aligned with Claude Code's

package/dist/managers/liveConfigManager.d.ts

@@ -10,7 +10,7 @@ import { Container } from "../utils/container.js";
 import type { WaveConfiguration } from "../types/configuration.js";
 export interface LiveConfigManagerOptions {
     workdir: string;
-    onReload?: (config: WaveConfiguration) => void;
+    onReload?: (config: WaveConfiguration) => void | Promise<void>;
 }
 export declare class LiveConfigManager {
     private container;

package/dist/managers/liveConfigManager.js

@@ -177,8 +177,11 @@ export class LiveConfigManager {
                 this.permissionManager.updateDeniedRules(this.currentConfiguration.permissions?.deny || []);
                 this.permissionManager.updateAdditionalDirectories(this.currentConfiguration.permissions?.additionalDirectories || []);
             }
-            // Trigger reload callback
-            this.options.onReload?.(this.currentConfiguration);
+            // Trigger reload callback. Awaited so fire-and-forget work spawned by the
+            // callback (e.g. skill rediscovery) completes before the reload resolves —
+            // otherwise Agent.create() can return with a cleared skill map (see race
+            // where refreshSkills() clears skillMetadata before async discoverSkills).
+            await this.options.onReload?.(this.currentConfiguration);
             return this.currentConfiguration;
         }
         catch (error) {

package/dist/managers/permissionManager.js

@@ -10,6 +10,7 @@ import { minimatch } from "minimatch";
 import { RESTRICTED_TOOLS } from "../types/permissions.js";
 import { splitBashCommand, stripEnvVars, stripRedirections, hasWriteRedirections, getSmartPrefix, isDangerousFind, hasCommandSubstitution, hasProcessSubstitution, hasSedInPlace, stripGitScopePrefix, DANGEROUS_COMMANDS, READ_ONLY_COMMANDS, } from "../utils/bashParser.js";
 import { isPathInside } from "../utils/pathSafety.js";
+import { toWindowsPath } from "../utils/path.js";
 import { BASH_TOOL_NAME, EDIT_TOOL_NAME, WRITE_TOOL_NAME, READ_TOOL_NAME, ASK_USER_QUESTION_TOOL_NAME, } from "../constants/tools.js";
 const DEFAULT_ALLOWED_RULES = [
     "Bash(git status*)",
@@ -286,29 +287,37 @@ export class PermissionManager {
      */
     isInsideSafeZone(targetPath, workdir) {
         const effectiveWorkdir = this.workdir || workdir;
+        // Convert MSYS/git-bash style paths (/c/Users/...) to native Windows form
+        // so `cd /c/...` and file args resolve correctly on win32 instead of
+        // becoming bogus C:\c\... paths that never match the Safe Zone.
+        const normalizedTarget = toWindowsPath(targetPath);
+        const normalizedWorkdir = effectiveWorkdir
+            ? toWindowsPath(effectiveWorkdir)
+            : undefined;
         // Resolve the target path relative to effectiveWorkdir if it's not absolute
-        const absolutePath = effectiveWorkdir && !path.isAbsolute(targetPath)
-            ? path.resolve(effectiveWorkdir, targetPath)
-            : path.resolve(targetPath);
+        const absolutePath = normalizedWorkdir && !path.isAbsolute(normalizedTarget)
+            ? path.resolve(normalizedWorkdir, normalizedTarget)
+            : path.resolve(normalizedTarget);
         // Check workdir
-        if (effectiveWorkdir && isPathInside(absolutePath, effectiveWorkdir)) {
+        if (effectiveWorkdir &&
+            isPathInside(absolutePath, toWindowsPath(effectiveWorkdir))) {
             return { isInside: true, resolvedPath: absolutePath };
         }
         // Check additional directories
         for (const dir of this.additionalDirectories) {
-            if (isPathInside(absolutePath, dir)) {
+            if (isPathInside(absolutePath, toWindowsPath(dir))) {
                 return { isInside: true, resolvedPath: absolutePath };
             }
         }
         // Check instance additional directories
         for (const dir of this.instanceAdditionalDirectories) {
-            if (isPathInside(absolutePath, dir)) {
+            if (isPathInside(absolutePath, toWindowsPath(dir))) {
                 return { isInside: true, resolvedPath: absolutePath };
             }
         }
         // Check system additional directories
         for (const dir of this.systemAdditionalDirectories) {
-            if (isPathInside(absolutePath, dir)) {
+            if (isPathInside(absolutePath, toWindowsPath(dir))) {
                 return { isInside: true, resolvedPath: absolutePath };
             }
         }

package/dist/services/MarketplaceService.js

@@ -4,7 +4,7 @@ import * as crypto from "crypto";
 import { getPluginsDir } from "../utils/configPaths.js";
 import { GitService } from "./GitService.js";
 import { ConfigurationService } from "./configurationService.js";
-import { logger } from "../utils/globalLogger.js";
+import { logger, logError, logWarn } from "../utils/globalLogger.js";
 /**
  * Marketplace Service
  *
@@ -270,7 +270,7 @@ export class MarketplaceService {
             return JSON.parse(content);
         }
         catch (error) {
-            console.error("Failed to load installed plugins:", error);
+            logError("Failed to load installed plugins:", error);
             return { plugins: [] };
         }
     }
@@ -513,7 +513,7 @@ export class MarketplaceService {
                     if (marketplace.source.source === "github" ||
                         marketplace.source.source === "git") {
                         if (!isGitAvailable) {
-                            console.warn(`Skipping update for Git/GitHub marketplace "${marketplace.name}" because Git is not installed.`);
+                            logWarn(`Skipping update for Git/GitHub marketplace "${marketplace.name}" because Git is not installed.`);
                             continue;
                         }
                         const targetPath = this.getMarketplacePath(marketplace.source);
@@ -548,7 +548,7 @@ export class MarketplaceService {
                                     await this.uninstallPlugin(`${plugin.name}@${plugin.marketplace}`, plugin.projectPath);
                                 }
                                 catch (error) {
-                                    console.error(`Failed to uninstall orphaned plugin "${plugin.name}" from marketplace "${marketplace.name}":`, error);
+                                    logError(`Failed to uninstall orphaned plugin "${plugin.name}" from marketplace "${marketplace.name}":`, error);
                                 }
                                 continue;
                             }
@@ -556,14 +556,14 @@ export class MarketplaceService {
                                 await this.installPlugin(`${plugin.name}@${plugin.marketplace}`, plugin.projectPath);
                             }
                             catch (error) {
-                                console.error(`Failed to update plugin "${plugin.name}" from marketplace "${marketplace.name}":`, error);
+                                logError(`Failed to update plugin "${plugin.name}" from marketplace "${marketplace.name}":`, error);
                             }
                         }
                     }
                 }
                 catch (error) {
                     const msg = `Failed to update marketplace "${marketplace.name}": ${error instanceof Error ? error.message : String(error)}`;
-                    console.error(msg);
+                    logError(msg);
                     errors.push(msg);
                 }
             }
@@ -588,7 +588,7 @@ export class MarketplaceService {
                     });
                 }
                 catch (error) {
-                    console.error(`Auto-update failed for marketplace "${marketplaceName}":`, error);
+                    logError(`Auto-update failed for marketplace "${marketplaceName}":`, error);
                 }
             }
         });

package/dist/services/configurationService.d.ts

@@ -8,6 +8,12 @@ import type { ConfigurationLoadResult, ValidationResult, ConfigurationPaths, Wav
 import { type EnvironmentValidationResult, type MergedEnvironmentContext, type EnvironmentMergeOptions } from "../types/environment.js";
 import { GatewayConfig, ModelConfig, PermissionMode, AgentOptions } from "../types/index.js";
 import { ClientOptions } from "openai";
+/**
+ * Validate a configuration object's structure and values. Module-level so it
+ * can be reused without instantiating ConfigurationService (e.g. background
+ * session cleanup runs before config is loaded).
+ */
+export declare function validateConfigurationObject(config: WaveConfiguration): ValidationResult;
 /**
  * Default ConfigurationService implementation
  *

package/dist/services/configurationService.js

@@ -17,6 +17,175 @@ import { getRemoteSettingsSync, mergeRemoteSettings, } from "./remoteSettingsSer
 import { createAuthAwareFetch } from "./authService.js";
 import { ensureWaveRuntimeFilesExcluded } from "../utils/gitUtils.js";
 import { atomicWriteFile } from "../utils/atomicWrite.js";
+/**
+ * Validate a configuration object's structure and values. Module-level so it
+ * can be reused without instantiating ConfigurationService (e.g. background
+ * session cleanup runs before config is loaded).
+ */
+export function validateConfigurationObject(config) {
+    const result = {
+        isValid: true,
+        errors: [],
+        warnings: [],
+    };
+    // Validate basic structure
+    if (!config || typeof config !== "object") {
+        result.isValid = false;
+        result.errors.push("Configuration must be a valid object");
+        return result;
+    }
+    // Validate hooks if present
+    if (config.hooks !== undefined) {
+        if (typeof config.hooks !== "object" || config.hooks === null) {
+            result.isValid = false;
+            result.errors.push("Hooks configuration must be an object");
+        }
+        else {
+            for (const [event, eventConfigs] of Object.entries(config.hooks)) {
+                if (!isValidHookEvent(event)) {
+                    result.warnings.push(`Unknown hook event: ${event}`);
+                    continue;
+                }
+                if (!Array.isArray(eventConfigs)) {
+                    result.isValid = false;
+                    result.errors.push(`Hook event '${event}' must be an array`);
+                    continue;
+                }
+                // Validate individual hook configurations
+                for (let i = 0; i < eventConfigs.length; i++) {
+                    const hookConfig = eventConfigs[i];
+                    if (!hookConfig || typeof hookConfig !== "object") {
+                        result.isValid = false;
+                        result.errors.push(`Hook configuration ${i} for event '${event}' must be an object`);
+                    }
+                }
+            }
+        }
+    }
+    // Validate enabledPlugins if present
+    if (config.enabledPlugins !== undefined) {
+        if (typeof config.enabledPlugins !== "object" ||
+            config.enabledPlugins === null) {
+            result.isValid = false;
+            result.errors.push("enabledPlugins configuration must be an object");
+        }
+        else {
+            for (const [pluginId, enabled] of Object.entries(config.enabledPlugins)) {
+                if (typeof enabled !== "boolean") {
+                    result.isValid = false;
+                    result.errors.push(`Value for plugin '${pluginId}' in enabledPlugins must be a boolean`);
+                }
+                if (!pluginId.includes("@")) {
+                    result.warnings.push(`Plugin ID '${pluginId}' in enabledPlugins should follow 'name@marketplace' format`);
+                }
+            }
+        }
+    }
+    // Validate environment variables if present
+    if (config.env !== undefined) {
+        const envValidation = validateEnvironmentConfig(config.env);
+        if (!envValidation.isValid) {
+            result.isValid = false;
+            result.errors.push(...envValidation.errors);
+        }
+        result.warnings.push(...envValidation.warnings);
+    }
+    // Validate permissions if present
+    if (config.permissions !== undefined) {
+        if (typeof config.permissions !== "object" || config.permissions === null) {
+            result.isValid = false;
+            result.errors.push("Permissions configuration must be an object");
+        }
+        else {
+            // Validate allow if present
+            if (config.permissions.allow !== undefined) {
+                if (!Array.isArray(config.permissions.allow)) {
+                    result.isValid = false;
+                    result.errors.push("Permissions allow must be an array of strings");
+                }
+                else if (!config.permissions.allow.every((rule) => typeof rule === "string")) {
+                    result.isValid = false;
+                    result.errors.push("All permission allow rules must be strings");
+                }
+            }
+            // Validate deny if present
+            if (config.permissions.deny !== undefined) {
+                if (!Array.isArray(config.permissions.deny)) {
+                    result.isValid = false;
+                    result.errors.push("Permissions deny must be an array of strings");
+                }
+                else if (!config.permissions.deny.every((rule) => typeof rule === "string")) {
+                    result.isValid = false;
+                    result.errors.push("All permission deny rules must be strings");
+                }
+            }
+            // Validate permissionMode if present
+            if (config.permissions.permissionMode !== undefined) {
+                const validModes = [
+                    "default",
+                    "bypassPermissions",
+                    "acceptEdits",
+                    "plan",
+                    "dontAsk",
+                ];
+                if (!validModes.includes(config.permissions.permissionMode)) {
+                    result.isValid = false;
+                    result.errors.push(`Invalid permissionMode: "${config.permissions.permissionMode}". Must be one of: ${validModes.join(", ")}`);
+                }
+            }
+        }
+    }
+    // Validate autoMemoryEnabled if present
+    if (config.autoMemoryEnabled !== undefined &&
+        typeof config.autoMemoryEnabled !== "boolean") {
+        result.isValid = false;
+        result.errors.push("autoMemoryEnabled configuration must be a boolean");
+    }
+    // Validate autoMemoryFrequency if present
+    if (config.autoMemoryFrequency !== undefined &&
+        (typeof config.autoMemoryFrequency !== "number" ||
+            config.autoMemoryFrequency <= 0)) {
+        result.isValid = false;
+        result.errors.push("autoMemoryFrequency configuration must be a positive number");
+    }
+    // Validate cleanupPeriodDays if present
+    if (config.cleanupPeriodDays !== undefined &&
+        (typeof config.cleanupPeriodDays !== "number" ||
+            !Number.isInteger(config.cleanupPeriodDays) ||
+            config.cleanupPeriodDays < 0)) {
+        result.isValid = false;
+        result.errors.push("cleanupPeriodDays configuration must be a non-negative integer");
+    }
+    // Validate models if present
+    if (config.models !== undefined) {
+        if (typeof config.models !== "object" || config.models === null) {
+            result.isValid = false;
+            result.errors.push("models configuration must be an object");
+        }
+        else {
+            for (const [modelName, modelConfig] of Object.entries(config.models)) {
+                if (typeof modelConfig !== "object" || modelConfig === null) {
+                    result.isValid = false;
+                    result.errors.push(`Configuration for model '${modelName}' must be an object`);
+                }
+            }
+        }
+    }
+    // Validate worktree if present
+    if (config.worktree !== undefined) {
+        if (typeof config.worktree !== "object" || config.worktree === null) {
+            result.isValid = false;
+            result.errors.push("worktree configuration must be an object");
+        }
+        else if (config.worktree.baseRef !== undefined &&
+            config.worktree.baseRef !== "fresh" &&
+            config.worktree.baseRef !== "head") {
+            result.isValid = false;
+            result.errors.push(`Invalid worktree.baseRef: "${config.worktree.baseRef}". Must be "fresh" or "head".`);
+        }
+    }
+    return result;
+}
 /**
  * Default ConfigurationService implementation
  *
@@ -120,161 +289,7 @@ export class ConfigurationService {
      * Validate configuration object structure and values
      */
     validateConfiguration(config) {
-        const result = {
-            isValid: true,
-            errors: [],
-            warnings: [],
-        };
-        // Validate basic structure
-        if (!config || typeof config !== "object") {
-            result.isValid = false;
-            result.errors.push("Configuration must be a valid object");
-            return result;
-        }
-        // Validate hooks if present
-        if (config.hooks !== undefined) {
-            if (typeof config.hooks !== "object" || config.hooks === null) {
-                result.isValid = false;
-                result.errors.push("Hooks configuration must be an object");
-            }
-            else {
-                for (const [event, eventConfigs] of Object.entries(config.hooks)) {
-                    if (!isValidHookEvent(event)) {
-                        result.warnings.push(`Unknown hook event: ${event}`);
-                        continue;
-                    }
-                    if (!Array.isArray(eventConfigs)) {
-                        result.isValid = false;
-                        result.errors.push(`Hook event '${event}' must be an array`);
-                        continue;
-                    }
-                    // Validate individual hook configurations
-                    for (let i = 0; i < eventConfigs.length; i++) {
-                        const hookConfig = eventConfigs[i];
-                        if (!hookConfig || typeof hookConfig !== "object") {
-                            result.isValid = false;
-                            result.errors.push(`Hook configuration ${i} for event '${event}' must be an object`);
-                        }
-                    }
-                }
-            }
-        }
-        // Validate enabledPlugins if present
-        if (config.enabledPlugins !== undefined) {
-            if (typeof config.enabledPlugins !== "object" ||
-                config.enabledPlugins === null) {
-                result.isValid = false;
-                result.errors.push("enabledPlugins configuration must be an object");
-            }
-            else {
-                for (const [pluginId, enabled] of Object.entries(config.enabledPlugins)) {
-                    if (typeof enabled !== "boolean") {
-                        result.isValid = false;
-                        result.errors.push(`Value for plugin '${pluginId}' in enabledPlugins must be a boolean`);
-                    }
-                    if (!pluginId.includes("@")) {
-                        result.warnings.push(`Plugin ID '${pluginId}' in enabledPlugins should follow 'name@marketplace' format`);
-                    }
-                }
-            }
-        }
-        // Validate environment variables if present
-        if (config.env !== undefined) {
-            const envValidation = validateEnvironmentConfig(config.env);
-            if (!envValidation.isValid) {
-                result.isValid = false;
-                result.errors.push(...envValidation.errors);
-            }
-            result.warnings.push(...envValidation.warnings);
-        }
-        // Validate permissions if present
-        if (config.permissions !== undefined) {
-            if (typeof config.permissions !== "object" ||
-                config.permissions === null) {
-                result.isValid = false;
-                result.errors.push("Permissions configuration must be an object");
-            }
-            else {
-                // Validate allow if present
-                if (config.permissions.allow !== undefined) {
-                    if (!Array.isArray(config.permissions.allow)) {
-                        result.isValid = false;
-                        result.errors.push("Permissions allow must be an array of strings");
-                    }
-                    else if (!config.permissions.allow.every((rule) => typeof rule === "string")) {
-                        result.isValid = false;
-                        result.errors.push("All permission allow rules must be strings");
-                    }
-                }
-                // Validate deny if present
-                if (config.permissions.deny !== undefined) {
-                    if (!Array.isArray(config.permissions.deny)) {
-                        result.isValid = false;
-                        result.errors.push("Permissions deny must be an array of strings");
-                    }
-                    else if (!config.permissions.deny.every((rule) => typeof rule === "string")) {
-                        result.isValid = false;
-                        result.errors.push("All permission deny rules must be strings");
-                    }
-                }
-                // Validate permissionMode if present
-                if (config.permissions.permissionMode !== undefined) {
-                    const validModes = [
-                        "default",
-                        "bypassPermissions",
-                        "acceptEdits",
-                        "plan",
-                        "dontAsk",
-                    ];
-                    if (!validModes.includes(config.permissions.permissionMode)) {
-                        result.isValid = false;
-                        result.errors.push(`Invalid permissionMode: "${config.permissions.permissionMode}". Must be one of: ${validModes.join(", ")}`);
-                    }
-                }
-            }
-        }
-        // Validate autoMemoryEnabled if present
-        if (config.autoMemoryEnabled !== undefined &&
-            typeof config.autoMemoryEnabled !== "boolean") {
-            result.isValid = false;
-            result.errors.push("autoMemoryEnabled configuration must be a boolean");
-        }
-        // Validate autoMemoryFrequency if present
-        if (config.autoMemoryFrequency !== undefined &&
-            (typeof config.autoMemoryFrequency !== "number" ||
-                config.autoMemoryFrequency <= 0)) {
-            result.isValid = false;
-            result.errors.push("autoMemoryFrequency configuration must be a positive number");
-        }
-        // Validate models if present
-        if (config.models !== undefined) {
-            if (typeof config.models !== "object" || config.models === null) {
-                result.isValid = false;
-                result.errors.push("models configuration must be an object");
-            }
-            else {
-                for (const [modelName, modelConfig] of Object.entries(config.models)) {
-                    if (typeof modelConfig !== "object" || modelConfig === null) {
-                        result.isValid = false;
-                        result.errors.push(`Configuration for model '${modelName}' must be an object`);
-                    }
-                }
-            }
-        }
-        // Validate worktree if present
-        if (config.worktree !== undefined) {
-            if (typeof config.worktree !== "object" || config.worktree === null) {
-                result.isValid = false;
-                result.errors.push("worktree configuration must be an object");
-            }
-            else if (config.worktree.baseRef !== undefined &&
-                config.worktree.baseRef !== "fresh" &&
-                config.worktree.baseRef !== "head") {
-                result.isValid = false;
-                result.errors.push(`Invalid worktree.baseRef: "${config.worktree.baseRef}". Must be "fresh" or "head".`);
-            }
-        }
-        return result;
+        return validateConfigurationObject(config);
     }
     /**
      * Validate configuration file without loading
@@ -1078,6 +1093,9 @@ export function loadWaveConfigFromFile(filePath) {
             autoMemoryFrequency: config.autoMemoryFrequency !== undefined
                 ? config.autoMemoryFrequency
                 : undefined,
+            cleanupPeriodDays: config.cleanupPeriodDays !== undefined
+                ? config.cleanupPeriodDays
+                : undefined,
             models: config.models || undefined,
             marketplaces: config.marketplaces || undefined,
             worktree: config.worktree || undefined,
@@ -1216,6 +1234,10 @@ export function loadMergedWaveConfig(workdir) {
         if (config.autoMemoryFrequency !== undefined) {
             mergedConfig.autoMemoryFrequency = config.autoMemoryFrequency;
         }
+        // Merge cleanupPeriodDays (last one wins)
+        if (config.cleanupPeriodDays !== undefined) {
+            mergedConfig.cleanupPeriodDays = config.cleanupPeriodDays;
+        }
         // Merge marketplaces (last one wins for same key)
         if (config.marketplaces) {
             if (!mergedConfig.marketplaces)
@@ -1260,6 +1282,7 @@ export function loadMergedWaveConfig(workdir) {
         language: mergedConfig.language,
         model: mergedConfig.model,
         autoMemoryEnabled: mergedConfig.autoMemoryEnabled,
+        cleanupPeriodDays: mergedConfig.cleanupPeriodDays,
         marketplaces: mergedConfig.marketplaces &&
             Object.keys(mergedConfig.marketplaces).length > 0
             ? mergedConfig.marketplaces

package/dist/services/session.d.ts

@@ -150,13 +150,6 @@ export declare function listAllSessions(options?: {
     worktreePaths?: string[];
     workdir?: string;
 }): Promise<SessionMetadata[]>;
-/**
- * Clean up expired sessions older than 14 days based on file modification time
- *
- * @param workdir - Working directory to clean up sessions for
- * @returns Promise that resolves to the number of sessions that were deleted
- */
-export declare function cleanupExpiredSessionsFromJsonl(workdir: string): Promise<number>;
 /**
  * Clean up empty project directories in the session directory
  */

package/dist/services/session.js

@@ -43,7 +43,6 @@ export function generateSubagentFilename(sessionId) {
 }
 // Constants
 export const SESSION_DIR = join(homedir(), ".wave", "projects");
-const MAX_SESSION_AGE_DAYS = 14;
 /**
  * Ensure session directory exists
  */
@@ -568,59 +567,6 @@ export async function listAllSessions(options) {
         throw new Error(`Failed to list all sessions: ${error}`);
     }
 }
-/**
- * Clean up expired sessions older than 14 days based on file modification time
- *
- * @param workdir - Working directory to clean up sessions for
- * @returns Promise that resolves to the number of sessions that were deleted
- */
-export async function cleanupExpiredSessionsFromJsonl(workdir) {
-    // Do not perform cleanup operations in test environment
-    if (process.env.NODE_ENV === "test") {
-        return 0;
-    }
-    try {
-        const encoder = new PathEncoder();
-        const projectDir = await encoder.getProjectDirectory(workdir, SESSION_DIR);
-        const files = await fs.readdir(projectDir.encodedPath);
-        const now = new Date();
-        const maxAge = MAX_SESSION_AGE_DAYS * 24 * 60 * 60 * 1000; // Convert to milliseconds
-        let deletedCount = 0;
-        for (const file of files) {
-            if (!file.endsWith(".jsonl")) {
-                continue;
-            }
-            const filePath = join(projectDir.encodedPath, file);
-            try {
-                const stat = await fs.stat(filePath);
-                const fileAge = now.getTime() - stat.mtime.getTime();
-                if (fileAge > maxAge) {
-                    await fs.unlink(filePath);
-                    deletedCount++;
-                }
-            }
-            catch {
-                // Skip failed operations and continue processing other files
-                continue;
-            }
-        }
-        // Clean up empty project directory if no files remain
-        try {
-            const remainingFiles = await fs.readdir(projectDir.encodedPath);
-            if (remainingFiles.length === 0) {
-                await fs.rmdir(projectDir.encodedPath);
-            }
-        }
-        catch {
-            // Ignore errors if directory is not empty or can't be removed
-        }
-        return deletedCount;
-    }
-    catch {
-        // Return 0 if project directory doesn't exist or can't be accessed
-        return 0;
-    }
-}
 /**
  * Clean up empty project directories in the session directory
  */
@@ -859,10 +805,6 @@ export async function handleSessionRestoration(restoreSessionId, continueLastSes
     if (!workdir) {
         throw new Error("Working directory is required for session restoration");
     }
-    // Clean up expired sessions first
-    cleanupExpiredSessionsFromJsonl(workdir).catch((error) => {
-        logger.warn("Failed to cleanup expired sessions:", error);
-    });
     if (!restoreSessionId && !continueLastSession) {
         return;
     }

package/dist/types/configuration.d.ts

@@ -57,6 +57,13 @@ export interface WaveConfiguration {
     };
     /** Whether the Artifact tool is enabled. Unset follows the code default constant (ARTIFACT_DEFAULT_ENABLED). */
     enableArtifact?: boolean;
+    /**
+     * Session transcript retention in days (aligned with Claude Code's
+     * cleanupPeriodDays). Session jsonl files in ~/.wave/projects older than
+     * this many days are cleaned up in the background at startup.
+     * Default: 30. 0 disables cleanup entirely.
+     */
+    cleanupPeriodDays?: number;
 }
 /**
  * Legacy alias for backward compatibility - will be deprecated

package/dist/types/core.d.ts

@@ -39,8 +39,8 @@ export interface Change {
 }
 export declare class ConfigurationError extends Error {
     readonly field: string;
-    readonly provided?: unknown | undefined;
-    constructor(message: string, field: string, provided?: unknown | undefined);
+    readonly provided?: unknown;
+    constructor(message: string, field: string, provided?: unknown);
 }
 export declare const CONFIG_ERRORS: {
     readonly MISSING_MODEL: "Agent configuration requires model. Provide via constructor or WAVE_MODEL environment variable.";

package/dist/utils/containerSetup.js

@@ -23,6 +23,7 @@ import { SubagentManager } from "../managers/subagentManager.js";
 import { LiveConfigManager } from "../managers/liveConfigManager.js";
 import { ReversionService } from "../services/reversionService.js";
 import { cleanupMetaOnlySessions } from "../services/session.js";
+import { runSessionCleanupInBackground } from "./sessionCleanup.js";
 import { MemoryService } from "../services/memory.js";
 import { AutoMemoryService } from "../services/autoMemoryService.js";
 import { USER_MEMORY_FILE } from "./constants.js";
@@ -160,6 +161,9 @@ export function setupAgentContainer(setupOptions) {
         .catch((error) => {
         logger.error("Failed to cleanup meta-only session files:", error);
     });
+    // Global session retention cleanup (cleanupPeriodDays, default 30 days).
+    // Once per process; reads settings itself since config isn't loaded yet.
+    runSessionCleanupInBackground(workdir);
     const reversionManager = new ReversionManager(container);
     container.register("ReversionManager", reversionManager);
     const canUseToolWithPermissionRequest = options.canUseTool
@@ -221,15 +225,19 @@ export function setupAgentContainer(setupOptions) {
     container.register("CanUseToolCallback", canUseToolWithPermissionRequest);
     const liveConfigManager = new LiveConfigManager(container, {
         workdir,
-        onReload: () => {
+        onReload: async () => {
             const models = configurationService.getConfiguredModels();
             callbacks.onConfiguredModelsChange?.(models);
             // Re-evaluate feature-gated tools (e.g. Artifact behind
             // enableArtifact) so toggling the flag applies without a restart.
             toolManager.reloadFeatureGatedTools();
             // Same gate for the builtin /artifact skill: refresh emits "refreshed"
-            // so slash-command registration follows enableArtifact.
-            void skillManager.reloadFeatureGatedSkills().catch((error) => {
+            // so slash-command registration follows enableArtifact. Awaited (via the
+            // awaited onReload) so skills are re-populated before Agent.create()
+            // returns — reloadFeatureGatedSkills() clears the skill map before
+            // rediscovering asynchronously, which would otherwise expose an empty
+            // skill list to callers right after create().
+            await skillManager.reloadFeatureGatedSkills().catch((error) => {
                 logger.error("Failed to reload feature-gated skills:", error);
             });
         },

package/dist/utils/convertMessagesForAPI.js

@@ -299,7 +299,7 @@ export function convertMessagesForAPI(messages, options) {
                 if (block.type === "task_notification") {
                     contentParts.push({
                         type: "text",
-                        text: taskNotificationToXml(block),
+                        text: `A background agent completed a task:\n${taskNotificationToXml(block)}`,
                     });
                 }
             });

package/dist/utils/globalLogger.d.ts

@@ -85,3 +85,16 @@ export declare const logger: {
      */
     readonly error: (...args: unknown[]) => void;
 };
+/**
+ * Log an error through the channel matching the execution context:
+ * - Interactive terminals (stdout is a TTY) with a configured global logger
+ *   route through the logger (e.g. a log file), keeping the terminal UI clean.
+ * - Non-interactive hosts (stdio pipes, scripts) and contexts without a
+ *   configured logger fall back to stderr via console.error.
+ */
+export declare function logError(...args: unknown[]): void;
+/**
+ * Log a warning through the channel matching the execution context
+ * (see logError for the routing rule).
+ */
+export declare function logWarn(...args: unknown[]): void;

package/dist/utils/globalLogger.js

@@ -118,3 +118,30 @@ export const logger = {
         globalLogger.error(...args);
     },
 };
+/**
+ * Log an error through the channel matching the execution context:
+ * - Interactive terminals (stdout is a TTY) with a configured global logger
+ *   route through the logger (e.g. a log file), keeping the terminal UI clean.
+ * - Non-interactive hosts (stdio pipes, scripts) and contexts without a
+ *   configured logger fall back to stderr via console.error.
+ */
+export function logError(...args) {
+    if (process.stdout.isTTY && isLoggerConfigured()) {
+        logger.error(...args);
+    }
+    else {
+        console.error(...args);
+    }
+}
+/**
+ * Log a warning through the channel matching the execution context
+ * (see logError for the routing rule).
+ */
+export function logWarn(...args) {
+    if (process.stdout.isTTY && isLoggerConfigured()) {
+        logger.warn(...args);
+    }
+    else {
+        console.warn(...args);
+    }
+}

package/dist/utils/messageOperations.js

@@ -482,6 +482,7 @@ export const addNotificationMessageToMessages = ({ messages, taskId, taskType, s
         id: generateMessageId(),
         role: "user",
         blocks: [block],
+        isMeta: true,
         timestamp: new Date().toISOString(),
     };
     return [...messages, notificationMessage];

package/dist/utils/sessionCleanup.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Session retention cleanup — aligned with Claude Code's cleanupOldSessionFiles()
+ * (~/.claude-code/src/utils/cleanup.ts).
+ *
+ * Scans ~/.wave/projects for session .jsonl files (main `<uuid>.jsonl` and
+ * `subagent-<uuid>.jsonl`) whose mtime is older than the retention cutoff and
+ * deletes them, then removes project directories left empty. Auto-memory
+ * (`memory/` subdirectories) is never touched.
+ *
+ * Retention is configurable via settings `cleanupPeriodDays` (default 30).
+ * `0` disables cleanup. If settings are corrupt or fail validation while the
+ * user explicitly set `cleanupPeriodDays`, cleanup is skipped entirely — the
+ * same guard Claude Code uses to avoid deleting files when the configured
+ * retention period cannot be trusted.
+ */
+/** Default retention period in days (Claude Code DEFAULT_CLEANUP_PERIOD_DAYS). */
+export declare const DEFAULT_CLEANUP_PERIOD_DAYS = 30;
+export interface SessionCleanupResult {
+    /** Number of session files deleted */
+    deleted: number;
+    /** Number of files/directories that failed to process */
+    errors: number;
+}
+/**
+ * Resolve the effective cleanup period in days, or null to skip cleanup.
+ *
+ * null (skip) happens when:
+ * - settings files exist but cannot be parsed/loaded (corrupt JSON, mid-write)
+ * - settings validation fails AND the user explicitly set cleanupPeriodDays
+ *
+ * Missing settings entirely is NOT a skip: the default 30 days applies.
+ */
+export declare function resolveCleanupPeriodDays(workdir: string): number | null;
+/**
+ * Delete session .jsonl files in ~/.wave/projects older than periodDays,
+ * then remove project directories left empty. Directories that still contain
+ * anything (e.g. `memory/` auto-memory) are preserved. Never throws; errors
+ * are counted and skipped, and a missing/unreadable projects dir is a silent
+ * no-op.
+ */
+export declare function cleanupOldSessionFiles(periodDays: number): Promise<SessionCleanupResult>;
+/**
+ * Kick off session cleanup in the background, once per process. Fire-and-forget:
+ * never throws, never blocks agent startup. In test environments cleanup is a
+ * no-op (same convention as the other startup cleanups in session.ts).
+ */
+export declare function runSessionCleanupInBackground(workdir: string): void;

package/dist/utils/sessionCleanup.js

@@ -0,0 +1,169 @@
+/**
+ * Session retention cleanup — aligned with Claude Code's cleanupOldSessionFiles()
+ * (~/.claude-code/src/utils/cleanup.ts).
+ *
+ * Scans ~/.wave/projects for session .jsonl files (main `<uuid>.jsonl` and
+ * `subagent-<uuid>.jsonl`) whose mtime is older than the retention cutoff and
+ * deletes them, then removes project directories left empty. Auto-memory
+ * (`memory/` subdirectories) is never touched.
+ *
+ * Retention is configurable via settings `cleanupPeriodDays` (default 30).
+ * `0` disables cleanup. If settings are corrupt or fail validation while the
+ * user explicitly set `cleanupPeriodDays`, cleanup is skipped entirely — the
+ * same guard Claude Code uses to avoid deleting files when the configured
+ * retention period cannot be trusted.
+ */
+import { existsSync, promises as fs } from "fs";
+import { join } from "path";
+import { logger } from "./globalLogger.js";
+import { SESSION_DIR } from "../services/session.js";
+import { loadMergedWaveConfig, validateConfigurationObject, } from "../services/configurationService.js";
+import { getProjectConfigPaths, getUserConfigPaths } from "./configPaths.js";
+/** Default retention period in days (Claude Code DEFAULT_CLEANUP_PERIOD_DAYS). */
+export const DEFAULT_CLEANUP_PERIOD_DAYS = 30;
+// Module-level flag: session cleanup runs once per process, on first agent
+// container setup — aligned with CC's once-per-process startup housekeeping.
+let cleanupScheduled = false;
+/**
+ * Resolve the effective cleanup period in days, or null to skip cleanup.
+ *
+ * null (skip) happens when:
+ * - settings files exist but cannot be parsed/loaded (corrupt JSON, mid-write)
+ * - settings validation fails AND the user explicitly set cleanupPeriodDays
+ *
+ * Missing settings entirely is NOT a skip: the default 30 days applies.
+ */
+export function resolveCleanupPeriodDays(workdir) {
+    let merged;
+    try {
+        merged = loadMergedWaveConfig(workdir);
+    }
+    catch (error) {
+        logger.debug(`Session cleanup: skipping (failed to load settings: ${error.message})`);
+        return null;
+    }
+    // No config file at all → default retention. Config files exist but merged
+    // config is null (corrupt JSON / empty file) → skip conservatively rather
+    // than deleting based on a partial config.
+    if (merged === null) {
+        if (hasAnySettingsFile(workdir)) {
+            logger.debug("Session cleanup: skipping (settings file exists but could not be parsed)");
+            return null;
+        }
+        return DEFAULT_CLEANUP_PERIOD_DAYS;
+    }
+    // Guard (CC): validation errors + explicit cleanupPeriodDays → skip entirely.
+    const validation = validateConfigurationObject(merged);
+    if (validation.errors.length > 0 && merged.cleanupPeriodDays !== undefined) {
+        logger.debug("Session cleanup: skipping (settings have validation errors but cleanupPeriodDays was explicitly set). Fix settings errors to enable cleanup.");
+        return null;
+    }
+    return merged.cleanupPeriodDays ?? DEFAULT_CLEANUP_PERIOD_DAYS;
+}
+/**
+ * Delete session .jsonl files in ~/.wave/projects older than periodDays,
+ * then remove project directories left empty. Directories that still contain
+ * anything (e.g. `memory/` auto-memory) are preserved. Never throws; errors
+ * are counted and skipped, and a missing/unreadable projects dir is a silent
+ * no-op.
+ */
+export async function cleanupOldSessionFiles(periodDays) {
+    const result = { deleted: 0, errors: 0 };
+    const cutoffDate = new Date(Date.now() - periodDays * 24 * 60 * 60 * 1000);
+    let projectEntries;
+    try {
+        projectEntries = await fs.readdir(SESSION_DIR, { withFileTypes: true });
+    }
+    catch {
+        // Projects dir doesn't exist or is unreadable — nothing to clean
+        return result;
+    }
+    for (const projectEntry of projectEntries) {
+        if (!projectEntry.isDirectory())
+            continue;
+        const projectDir = join(SESSION_DIR, projectEntry.name);
+        let entries;
+        try {
+            entries = await fs.readdir(projectDir, { withFileTypes: true });
+        }
+        catch {
+            result.errors++;
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith(".jsonl"))
+                continue;
+            try {
+                if (await unlinkIfOld(join(projectDir, entry.name), cutoffDate)) {
+                    result.deleted++;
+                }
+            }
+            catch {
+                result.errors++;
+            }
+        }
+        // Removes the project dir only if it is now empty; dirs still containing
+        // files (e.g. memory/) or subdirectories are left untouched.
+        await tryRmdir(projectDir);
+    }
+    return result;
+}
+/**
+ * Kick off session cleanup in the background, once per process. Fire-and-forget:
+ * never throws, never blocks agent startup. In test environments cleanup is a
+ * no-op (same convention as the other startup cleanups in session.ts).
+ */
+export function runSessionCleanupInBackground(workdir) {
+    if (process.env.NODE_ENV === "test")
+        return;
+    if (cleanupScheduled)
+        return;
+    cleanupScheduled = true;
+    void (async () => {
+        try {
+            const periodDays = resolveCleanupPeriodDays(workdir);
+            if (periodDays === null) {
+                return; // skip reason already logged in resolveCleanupPeriodDays
+            }
+            if (periodDays === 0) {
+                logger.debug("Session cleanup: disabled (cleanupPeriodDays is 0)");
+                return;
+            }
+            const result = await cleanupOldSessionFiles(periodDays);
+            if (result.deleted > 0) {
+                logger.debug(`Session cleanup: removed ${result.deleted} session file(s)`);
+            }
+            if (result.errors > 0) {
+                logger.warn(`Session cleanup: encountered ${result.errors} error(s) while cleaning session files`);
+            }
+        }
+        catch (error) {
+            logger.warn(`Session cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    })();
+}
+/**
+ * Whether any settings file exists that loadMergedWaveConfig would consider
+ * (user settings.json + project settings.json/local.json).
+ */
+function hasAnySettingsFile(workdir) {
+    const userPaths = getUserConfigPaths();
+    const projectPaths = getProjectConfigPaths(workdir);
+    return [userPaths[0], projectPaths[1], projectPaths[0]].some((p) => existsSync(p));
+}
+async function unlinkIfOld(filePath, cutoffDate) {
+    const stats = await fs.stat(filePath);
+    if (stats.mtime < cutoffDate) {
+        await fs.unlink(filePath);
+        return true;
+    }
+    return false;
+}
+async function tryRmdir(dirPath) {
+    try {
+        await fs.rmdir(dirPath);
+    }
+    catch {
+        // Not empty or doesn't exist
+    }
+}

package/dist/utils/tokenCalculation.d.ts

@@ -1,24 +1,12 @@
 import type { Message, Usage } from "../types/index.js";
 /**
- * Calculate comprehensive total tokens including cache-related tokens
- *
- * This function computes the true total token cost by including:
- * - Base total_tokens (prompt + completion)
- * - Cache read tokens (cost savings indicator)
- * - Cache creation tokens (cache investment)
- *
- * For accurate cost tracking with Claude models that support cache control.
- *
- * @param usage - Usage statistics from AI operation
- * @returns Comprehensive total including all cache-related tokens
- */
-export declare function calculateComprehensiveTotalTokens(usage: Usage): number;
-/**
- * Extract the latest total tokens from the last message with usage data
- * Uses comprehensive calculation that includes cache tokens for accurate tracking
+ * Extract the latest total tokens from the last message with usage data.
+ * Uses only `total_tokens` — OpenAI-compatible usage already includes cache
+ * hits there, so adding cache fields would double-count (same semantics as
+ * the auto-compaction threshold; keeps UI usage display aligned with it).
  *
  * @param messages - Array of messages to search
- * @returns Comprehensive total tokens from the most recent usage data, or 0 if none found
+ * @returns Total tokens from the most recent usage data, or 0 if none found
  */
 export declare function extractLatestTotalTokens(messages: Array<{
     usage?: Usage;

package/dist/utils/tokenCalculation.js

@@ -1,36 +1,19 @@
 import { estimateTokens } from "./tokenEstimate.js";
 /**
- * Calculate comprehensive total tokens including cache-related tokens
- *
- * This function computes the true total token cost by including:
- * - Base total_tokens (prompt + completion)
- * - Cache read tokens (cost savings indicator)
- * - Cache creation tokens (cache investment)
- *
- * For accurate cost tracking with Claude models that support cache control.
- *
- * @param usage - Usage statistics from AI operation
- * @returns Comprehensive total including all cache-related tokens
- */
-export function calculateComprehensiveTotalTokens(usage) {
-    const baseTokens = usage.total_tokens;
-    const cacheReadTokens = usage.cache_read_input_tokens || 0;
-    const cacheCreateTokens = usage.cache_creation_input_tokens || 0;
-    return baseTokens + cacheReadTokens + cacheCreateTokens;
-}
-/**
- * Extract the latest total tokens from the last message with usage data
- * Uses comprehensive calculation that includes cache tokens for accurate tracking
+ * Extract the latest total tokens from the last message with usage data.
+ * Uses only `total_tokens` — OpenAI-compatible usage already includes cache
+ * hits there, so adding cache fields would double-count (same semantics as
+ * the auto-compaction threshold; keeps UI usage display aligned with it).
  *
  * @param messages - Array of messages to search
- * @returns Comprehensive total tokens from the most recent usage data, or 0 if none found
+ * @returns Total tokens from the most recent usage data, or 0 if none found
  */
 export function extractLatestTotalTokens(messages) {
     // Find the last message with usage data (iterate backwards for efficiency)
     for (let i = messages.length - 1; i >= 0; i--) {
         const message = messages[i];
         if (message.usage) {
-            return calculateComprehensiveTotalTokens(message.usage);
+            return message.usage.total_tokens;
         }
     }
     return 0; // No usage data found

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wave-agent-sdk",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "SDK for building AI-powered development tools and agents",
   "keywords": [
     "ai",
@@ -62,7 +62,6 @@
     "@types/turndown": "^5.0.6",
     "@vitest/coverage-v8": "^4.1.7",
     "rimraf": "^6.1.2",
-    "tsc-alias": "^1.8.16",
     "vitest": "^4.1.7"
   },
   "engines": {
@@ -70,15 +69,15 @@
   },
   "license": "MIT",
   "scripts": {
-    "build": "rimraf dist && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "build": "rimraf dist && tsc -p tsconfig.build.json",
     "type-check": "tsc --noEmit --incremental",
-    "watch": "tsc -p tsconfig.build.json --watch & tsc-alias -p tsconfig.build.json --watch",
+    "watch": "tsc -p tsconfig.build.json --watch",
     "test": "vitest run --reporter=dot",
     "test:coverage": "vitest run --coverage --reporter=dot",
     "test:unit": "vitest run --reporter=dot --exclude 'tests/integration/**' --exclude '**/*.integration.test.ts'",
     "test:unit:coverage": "vitest run --coverage --reporter=dot --exclude 'tests/integration/**' --exclude '**/*.integration.test.ts'",
     "test:integration": "vitest run --reporter=dot tests/integration .integration.test",
-    "lint": "eslint --cache",
+    "lint": "oxlint",
     "format": "prettier --write ."
   }
 }