wave-agent-sdk 1.1.5 → 1.3.0

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) {

package/dist/services/initializationService.js

@@ -9,6 +9,25 @@ export class InitializationService {
         const startTime = performance.now();
         // Set global logger early so managers can use it during initialization
         setGlobalLogger(logger || null);
+        // Load the remote settings disk cache synchronously, before anything reads
+        // the configuration chain. Two consumers depend on it being this early:
+        // loadMergedConfiguration (below) merges the cached managed settings (env,
+        // model, disallowedTools), and plugin loading (also below) reads the managed
+        // enabledPlugins / marketplaces so an admin-pushed plugin is installed and
+        // enabled on this very startup (spec enterprise server-managed-config
+        // 「托管配置下发插件市场与启用列表」场景 1). Settings `env` is stored in the
+        // per-session env snapshot (NOT process.env), except WAVE_SERVER_URL which is
+        // mirrored to process.env so the network fetch (below) can read it via
+        // authService.getServerUrl(); no race.
+        try {
+            const phaseStart = performance.now();
+            await remoteSettingsService.initialize();
+            logger?.debug(`Initialization Phase [Remote Settings Cache] took ${(performance.now() - phaseStart).toFixed(2)}ms`);
+        }
+        catch (error) {
+            logger?.error("Failed to initialize remote settings:", error);
+            // Don't throw error to prevent app startup failure - continue without remote settings
+        }
         // Initialize managers first
         try {
             const phaseStart = performance.now();
@@ -44,21 +63,6 @@ export class InitializationService {
             logger?.error("Failed to initialize MCP servers:", error);
             // Don't throw error to prevent app startup failure
         }
-        // Load remote settings disk cache synchronously.
-        // Must happen BEFORE loadMergedConfiguration so cached managed settings
-        // (env, model, disallowedTools) are merged into the config. Settings `env`
-        // is stored in the per-session env snapshot (NOT process.env), except
-        // WAVE_SERVER_URL which is mirrored to process.env so the network fetch
-        // (below) can read it via authService.getServerUrl(); no race.
-        try {
-            const phaseStart = performance.now();
-            await remoteSettingsService.initialize();
-            logger?.debug(`Initialization Phase [Remote Settings Cache] took ${(performance.now() - phaseStart).toFixed(2)}ms`);
-        }
-        catch (error) {
-            logger?.error("Failed to initialize remote settings:", error);
-            // Don't throw error to prevent app startup failure - continue without remote settings
-        }
         // Initialize hooks configuration
         try {
             const phaseStart = performance.now();
@@ -84,8 +88,8 @@ export class InitializationService {
                     if (configResult.configuration.permissions.deny) {
                         permissionManager.updateDeniedRules(configResult.configuration.permissions.deny);
                     }
-                    if (configResult.configuration.permissions.permissionMode) {
-                        permissionManager.updateConfiguredPermissionMode(configResult.configuration.permissions.permissionMode);
+                    if (configResult.configuration.permissions.defaultMode) {
+                        permissionManager.updateConfiguredPermissionMode(configResult.configuration.permissions.defaultMode);
                     }
                     if (configResult.configuration.permissions.additionalDirectories) {
                         permissionManager.updateAdditionalDirectories(configResult.configuration.permissions.additionalDirectories);

package/dist/services/interactionService.d.ts

@@ -18,11 +18,19 @@ export interface InteractionContext {
     taskManager: TaskManager;
     options: AgentOptions;
     abortMessage: () => void;
+    /**
+     * Move every directory-derived piece of session state (session transcript
+     * location, project rules, memory caches) to another working directory.
+     * Used when restoring a session that lives in a different directory.
+     */
+    switchWorkdir: (workdir: string) => Promise<void>;
 }
 export declare class InteractionService {
     static sendMessage(context: InteractionContext, content: string, images?: Array<{
         path: string;
         mimeType: string;
     }>): Promise<void>;
-    static restoreSession(context: InteractionContext, sessionId: string): Promise<void>;
+    static restoreSession(context: InteractionContext, sessionId: string, restoreOptions?: {
+        workdir?: string;
+    }): Promise<void>;
 }

package/dist/services/interactionService.js

@@ -75,8 +75,14 @@ export class InteractionService {
             // Loading state will be automatically updated by the useEffect that watches messages
         }
     }
-    static async restoreSession(context, sessionId) {
-        const { messageManager, hookManager, logger, subagentManager, taskManager, options, abortMessage, } = context;
+    static async restoreSession(context, sessionId, restoreOptions) {
+        const { messageManager, hookManager, logger, subagentManager, taskManager, options, abortMessage, switchWorkdir, } = context;
+        // The target session may live in another project directory. Everything
+        // below that reads a path (loading the transcript, the SessionStart hook's
+        // transcript path, the next append) must use the target directory, never
+        // the current one — otherwise the switch writes a second copy of the same
+        // session into the current project directory.
+        const targetWorkdir = restoreOptions?.workdir ?? messageManager.getWorkdir();
         // 1. Validation
         if (!sessionId || sessionId === messageManager.getSessionId()) {
             return; // No-op if session ID is invalid or already current
@@ -89,6 +95,9 @@ export class InteractionService {
             logger?.warn("Failed to save current session before restore:", error);
             // Continue with restoration even if save fails
         }
+        // 2b. Flush point for the session being left behind: it is about to be
+        //     read from disk again by whoever lists sessions next.
+        await messageManager.reAppendSessionMetadata();
         // 3. Run SessionEnd hooks for the current session (cleanup before switching)
         const currentSessionId = messageManager.getSessionId();
         const currentTranscriptPath = messageManager.getTranscriptPath();
@@ -101,18 +110,29 @@ export class InteractionService {
             }
         }
         // 4. Load target session
-        const sessionData = await loadSessionFromJsonl(sessionId, messageManager.getWorkdir());
+        const sessionData = await loadSessionFromJsonl(sessionId, targetWorkdir);
         if (!sessionData) {
             throw new Error(`Session not found: ${sessionId}`);
         }
-        // 5. Clean current state
+        // 5. Move this session to the target directory. Only after the target
+        //    transcript has loaded successfully, so a failed restore leaves the
+        //    current session (and its directory) untouched.
+        if (targetWorkdir !== messageManager.getWorkdir()) {
+            await switchWorkdir(targetWorkdir);
+        }
+        // 6. Clean current state
         abortMessage(); // Abort any running operations
         subagentManager.cleanup(); // Clean up active subagents
-        // 6. Rebuild usage (in correct order)
+        // 7. Rebuild usage (in correct order)
         messageManager.rebuildUsageFromMessages(sessionData.messages);
-        // 7. Initialize session state last
+        // 8. Initialize session state last
         messageManager.initializeFromSession(sessionData);
-        // 8. Run SessionStart hooks for the restored session and inject additional
+        // 8b. Flush point for the session we just took over. `initializeFromSession`
+        //     has adopted the title recovered by the load-time whole-file scan, so
+        //     this is where a title that had slid out of the tail window is written
+        //     back at EOF (Claude Code's `adoptResumedSessionFile` does the same).
+        await messageManager.reAppendSessionMetadata();
+        // 9. Run SessionStart hooks for the restored session and inject additional
         //    context as a meta user message (matches Claude Code's resume behavior:
         //    SessionEnd then SessionStart, hook messages appended to the conversation)
         if (hookManager) {
@@ -131,7 +151,7 @@ export class InteractionService {
         }
         // Update task manager with the root session ID to ensure continuity across compactions
         taskManager.setTaskListId(sessionData.id);
-        // 9. Load tasks for the restored session
+        // 10. Load tasks for the restored session
         const tasks = await taskManager.listTasks();
         options.callbacks?.onTasksChange?.(tasks);
     }

package/dist/services/jsonlHandler.d.ts

@@ -24,6 +24,20 @@ export interface SessionMetadataHeader {
     /** Git branch at creation time (`git branch --show-current`), when the directory is a git repo. */
     gitBranch?: string;
 }
+/**
+ * User-set conversation title, appended as its own JSONL entry on rename.
+ * A dedicated entry type (rather than a field on the append-only metadata
+ * header) is what lets the title be changed after creation without rewriting
+ * the file: it is appended at rename time, and re-appended at EOF at the
+ * session's sparse flush points (`reAppendSessionMetadata` — exit, compaction,
+ * resume, rewind) rather than on every save.
+ */
+export interface CustomTitleEntry {
+    type: "custom-title";
+    customTitle: string;
+    /** Session the title belongs to (the file is per-session; kept for traceability). */
+    sessionId?: string;
+}
 /**
  * JSONL handler class for message persistence operations
  */
@@ -49,6 +63,26 @@ export declare class JsonlHandler {
      * Append a single message to JSONL file
      */
     appendMessage(filePath: string, message: Message): Promise<void>;
+    /**
+     * Append a user-set conversation title (`{"type":"custom-title",...}`).
+     *
+     * Appending — never rewriting — keeps the file's append-only contract intact
+     * and leaves the metadata header and every message untouched. The entry has
+     * no `timestamp`, so it can never be mistaken for a message by readers that
+     * filter on timestamps.
+     */
+    appendCustomTitle(filePath: string, customTitle: string, sessionId?: string): Promise<void>;
+    /**
+     * Read the session's user-set title from the tail window, if present.
+     *
+     * Scans the tail and keeps the newest entry, so a rename always wins over an
+     * earlier one. Only the tail is read: this is the cheap path used by session
+     * listing and by `reAppendSessionMetadata`'s external-writer refresh, and the
+     * write side re-appends the entry at EOF at its sparse flush points. An entry
+     * that later messages have already pushed out of the window is invisible
+     * here — that is what `readMessagesAndCustomTitle` recovers on resume.
+     */
+    readCustomTitle(filePath: string): Promise<string | undefined>;
     /**
      * Append multiple messages to JSONL file
      */
@@ -61,10 +95,42 @@ export declare class JsonlHandler {
      * Read all messages from JSONL file (simplified - no metadata handling)
      */
     read(filePath: string): Promise<Message[]>;
+    /**
+     * Read the whole file once, returning every message plus the newest
+     * `custom-title` entry.
+     *
+     * `readCustomTitle` only scans the tail window, so a title that later
+     * messages pushed out of it is invisible there. The whole file still holds
+     * it, and the resume path collects it here: that recovered value is what a
+     * later `reAppendSessionMetadata` writes back at EOF, which is what makes an
+     * evicted title self-heal instead of being lost for good.
+     *
+     * @param filePath - Path to the session JSONL file
+     * @returns The messages (reserved entries filtered out) and the newest
+     *          non-empty custom title, when the file carries one
+     */
+    readMessagesAndCustomTitle(filePath: string): Promise<{
+        messages: Message[];
+        customTitle?: string;
+    }>;
     /**
      * Get the last message from JSONL file using efficient file reading (simplified)
      */
     getLastMessage(filePath: string): Promise<Message | null>;
+    /**
+     * Latest context-usage total for a session file.
+     *
+     * Sessions accumulate usage-less messages at the end — SessionStart hook
+     * meta messages are appended (and persisted) on every resume — so the last
+     * line alone cannot answer "how much context did this conversation use".
+     * Scan backwards over the file's tail window and take the newest message
+     * that carries usage.
+     *
+     * @param filePath - Path to the session JSONL file
+     * @returns total_tokens of the newest usage-bearing message, or 0 when the
+     *          tail holds none (empty/unreadable file, no completed request yet)
+     */
+    getLatestTotalTokens(filePath: string): Promise<number>;
     /**
      * Read the creation-time metadata from the session file's header line.
      *
@@ -75,6 +141,38 @@ export declare class JsonlHandler {
      * @returns The persisted metadata, or null when the file has no header
      */
     readMetadata(filePath: string): Promise<SessionMetadataHeader | null>;
+    /**
+     * Rewrite a session file keeping only its first `keepMessageCount` messages.
+     *
+     * This is the one operation that removes history from a session file
+     * (`/rewind`); every other write appends. It is a filter over the file's
+     * original lines rather than a re-serialization of parsed messages:
+     *
+     * - Reserved entries (`metadata` header, `custom-title`, and any type added
+     *   to `RESERVED_ENTRY_TYPES` later) are carried over byte for byte, wherever
+     *   they sit in the file. Rebuilding the file from `Message[]` used to lose
+     *   them — `read()` filters reserved entries out, so a rewrite could not see
+     *   the header or the title — which silently degraded the session to the
+     *   "legacy file without a header" shape: `createdAt` fell back to
+     *   `new Date()`, `gitBranch` vanished, and the title could never be read
+     *   back again.
+     * - Lines that are neither reserved nor a message (no `timestamp`) are also
+     *   carried over, so an entry type written by a newer version survives a
+     *   rewind performed by an older one.
+     * - Only message lines past `keepMessageCount` are dropped.
+     *
+     * The result is written to a temp file and renamed into place, so an
+     * interrupted rewrite leaves the original file untouched.
+     *
+     * The "is this a message line" test deliberately mirrors `read()`
+     * (`!isReservedEntry(type) && timestamp`) and the partial-trailing-line
+     * tolerance mirrors its interrupted-append handling, so the caller's message
+     * count and this file's line order stay in step.
+     *
+     * @param filePath - Session JSONL path (must already exist)
+     * @param keepMessageCount - Number of leading messages to keep
+     */
+    truncateSession(filePath: string, keepMessageCount: number): Promise<void>;
     /**
      * Validate messages before writing
      */