wave-agent-sdk 1.1.5 → 1.3.0

package/dist/services/jsonlHandler.js

@@ -2,9 +2,17 @@
  * JSONL file operations service
  * Handles reading and writing JSONL (JSON Lines) session files for improved performance
  */
-import { appendFile, readFile, writeFile, stat, mkdir } from "fs/promises";
+import { appendFile, readFile, writeFile, stat, mkdir, rename, unlink, } from "fs/promises";
+import { randomUUID } from "crypto";
 import { dirname } from "path";
-import { getLastLine, readFirstNLines } from "../utils/fileUtils.js";
+import { forEachLine, getLastLine, readFirstNLines, readTailLines, } from "../utils/fileUtils.js";
+import { extractLatestTotalTokens } from "../utils/tokenCalculation.js";
+import { isReservedEntry } from "./sessionEntries.js";
+/**
+ * Flush threshold for `truncateSession`'s output buffer. Only bounds the
+ * rewrite's memory — the file it produces is identical regardless of value.
+ */
+const TRUNCATE_FLUSH_BYTES = 64 * 1024;
 /**
  * JSONL handler class for message persistence operations
  */
@@ -42,6 +50,49 @@ export class JsonlHandler {
     async appendMessage(filePath, message) {
         return this.appendMessages(filePath, [message]);
     }
+    /**
+     * 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.
+     */
+    async appendCustomTitle(filePath, customTitle, sessionId) {
+        const entry = {
+            type: "custom-title",
+            customTitle,
+            ...(sessionId ? { sessionId } : {}),
+        };
+        await this.ensureDirectory(dirname(filePath));
+        await appendFile(filePath, `${JSON.stringify(entry)}\n`, "utf8");
+    }
+    /**
+     * 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.
+     */
+    async readCustomTitle(filePath) {
+        for (const line of (await readTailLines(filePath)).reverse()) {
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed.type !== "custom-title")
+                    continue;
+                return typeof parsed.customTitle === "string" && parsed.customTitle
+                    ? parsed.customTitle
+                    : undefined;
+            }
+            catch {
+                // Partial line at the tail window's boundary — keep looking.
+            }
+        }
+        return undefined;
+    }
     /**
      * Append multiple messages to JSONL file
      */
@@ -86,37 +137,76 @@ export class JsonlHandler {
      * Read all messages from JSONL file (simplified - no metadata handling)
      */
     async read(filePath) {
+        return (await this.readMessagesAndCustomTitle(filePath)).messages;
+    }
+    /**
+     * 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
+     */
+    async readMessagesAndCustomTitle(filePath) {
         try {
             const content = await readFile(filePath, "utf8");
+            // append() always terminates a written batch with "\n" (see append),
+            // so a file that does not end with a newline means the process was
+            // interrupted mid-write, leaving a partial trailing line behind.
+            const endsWithNewline = content.length === 0 || content.endsWith("\n");
             const lines = content
                 .split(/\r?\n/)
                 .map((line) => line.trim())
                 .filter((line) => line.length > 0);
             if (lines.length === 0) {
-                return [];
+                return { messages: [] };
             }
             const allMessages = [];
-            // Parse all messages, skipping the metadata header line (if any)
+            let customTitle;
+            // Parse every line: real messages are kept, reserved entries (the
+            // metadata header, and custom titles) are read for their own fields.
             for (let i = 0; i < lines.length; i++) {
                 const line = lines[i];
                 try {
                     const message = JSON.parse(line);
-                    // Metadata header line: not a message, skip
-                    if (message.type === "metadata")
+                    if (message.type === "custom-title") {
+                        // Last one wins: a later rename supersedes an earlier one.
+                        if (typeof message.customTitle === "string" &&
+                            message.customTitle) {
+                            customTitle = message.customTitle;
+                        }
+                        continue;
+                    }
+                    // Any other reserved entry (metadata header): not a message
+                    if (isReservedEntry(message.type))
                         continue;
                     if (message.timestamp)
                         allMessages.push(message);
                 }
                 catch (error) {
+                    // A parse failure on the final line of a file that lacks a trailing
+                    // newline is the residue of an interrupted append (complete batches
+                    // always end with "\n"): drop the partial line and keep every
+                    // message that was fully written. Corruption on any earlier line is
+                    // genuine corruption and still fails.
+                    if (!endsWithNewline && i === lines.length - 1) {
+                        continue;
+                    }
                     // Throw error for invalid JSON lines with line number
                     throw new Error(`Invalid JSON at line ${i + 1}: ${error}`);
                 }
             }
-            return allMessages;
+            return { messages: allMessages, customTitle };
         }
         catch (error) {
             if (error.code === "ENOENT") {
-                return [];
+                return { messages: [] };
             }
             throw new Error(`Failed to read JSONL file "${filePath}": ${error}`);
         }
@@ -143,20 +233,63 @@ export class JsonlHandler {
             }
             try {
                 const parsed = JSON.parse(lastLine);
-                // A file whose only line is the metadata header has no messages yet
-                if (parsed.type === "metadata") {
-                    return null;
+                if (!isReservedEntry(parsed.type)) {
+                    return parsed;
                 }
-                return parsed;
             }
             catch (error) {
                 throw new Error(`Invalid JSON in last line of "${filePath}": ${error}`);
             }
+            // The file ends with a reserved entry — a `custom-title` appended by a
+            // rename, or the metadata header of a session with no messages yet. Both
+            // are non-messages, so walk the tail window back to the newest message.
+            for (const line of (await readTailLines(filePath)).reverse()) {
+                try {
+                    const parsed = JSON.parse(line);
+                    if (isReservedEntry(parsed.type))
+                        continue;
+                    return parsed;
+                }
+                catch {
+                    // Partial line at the tail window's boundary — keep looking.
+                }
+            }
+            return null;
         }
         catch (error) {
             throw new Error(`Failed to get last message from "${filePath}": ${error}`);
         }
     }
+    /**
+     * 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)
+     */
+    async getLatestTotalTokens(filePath) {
+        const messages = [];
+        for (const line of await readTailLines(filePath)) {
+            try {
+                const parsed = JSON.parse(line);
+                // Reserved entry (metadata header, custom-title): not a message
+                if (isReservedEntry(parsed.type))
+                    continue;
+                messages.push(parsed);
+            }
+            catch {
+                // Partial line at the tail window's boundary — drop it.
+                continue;
+            }
+        }
+        return extractLatestTotalTokens(messages);
+    }
     /**
      * Read the creation-time metadata from the session file's header line.
      *
@@ -186,6 +319,111 @@ export class JsonlHandler {
         }
         return 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
+     */
+    async truncateSession(filePath, keepMessageCount) {
+        const tempPath = `${filePath}.tmp.${process.pid}.${randomUUID()}`;
+        try {
+            // Materialize the temp file up front so an empty result still renames.
+            await writeFile(tempPath, "", "utf8");
+            let keptMessages = 0;
+            let pendingBrokenLine = false;
+            let buffered = [];
+            let bufferedLength = 0;
+            const flush = async () => {
+                if (buffered.length === 0) {
+                    return;
+                }
+                await appendFile(tempPath, buffered.join(""), "utf8");
+                buffered = [];
+                bufferedLength = 0;
+            };
+            const keepLine = async (line) => {
+                const chunk = `${line}\n`;
+                buffered.push(chunk);
+                bufferedLength += chunk.length;
+                if (bufferedLength >= TRUNCATE_FLUSH_BYTES) {
+                    await flush();
+                }
+            };
+            const handleLine = async (raw) => {
+                const line = raw.trim();
+                if (line.length === 0) {
+                    return;
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch (error) {
+                    if (pendingBrokenLine) {
+                        throw new Error(`Invalid JSON in session file "${filePath}": ${error}`);
+                    }
+                    pendingBrokenLine = true;
+                    return;
+                }
+                // A parseable line after a broken one proves the broken line was not
+                // the file's last, so it is corruption rather than a partial write.
+                if (pendingBrokenLine) {
+                    throw new Error(`Invalid JSON in session file "${filePath}": truncated trailing line`);
+                }
+                if (isReservedEntry(parsed.type) || !parsed.timestamp) {
+                    await keepLine(line);
+                    return;
+                }
+                if (keptMessages < keepMessageCount) {
+                    keptMessages++;
+                    await keepLine(line);
+                }
+            };
+            const { endsWithNewline } = await forEachLine(filePath, handleLine);
+            // A broken line is only acceptable as the last line of a file that lacks
+            // a trailing newline — the residue of an interrupted append.
+            if (pendingBrokenLine && endsWithNewline) {
+                throw new Error(`Invalid JSON in session file "${filePath}"`);
+            }
+            await flush();
+            await rename(tempPath, filePath);
+        }
+        catch (error) {
+            try {
+                await unlink(tempPath);
+            }
+            catch {
+                // Cleanup is best effort — the original error is more important.
+            }
+            throw error;
+        }
+    }
     /**
      * Validate messages before writing
      */

package/dist/services/memory.d.ts

@@ -19,11 +19,27 @@ export declare class MemoryService {
      */
     ensureAutoMemoryDirectory(workdir: string): Promise<void>;
     /**
-     * Get the first 200 lines of MEMORY.md.
+     * Get the auto-memory entrypoint (`MEMORY.md`), bounded by both the line and
+     * the character cap. Truncation appends a warning naming the cap that fired,
+     * so the model can tell the index it is reading is incomplete.
      */
     getAutoMemoryContent(workdir: string): Promise<string>;
     ensureUserMemoryFile(): Promise<void>;
     getUserMemoryContent(): Promise<string>;
     readMemoryFile(workdir: string): Promise<string>;
     getCombinedMemoryContent(workdir: string): Promise<string>;
+    /**
+     * Persist the user-level memory file (~/.wave/AGENTS.md), creating it if
+     * missing. Clears the user-memory cache so subsequent reads see the new
+     * content (the default-template fallback to ~/.claude/AGENTS.md is also
+     * bypassed once the user writes real content).
+     */
+    writeUserMemoryContent(content: string): Promise<void>;
+    /**
+     * Persist the project-level memory file (<workdir>/AGENTS.md), creating it
+     * if missing. Reads fall back to CLAUDE.md but writes always target
+     * AGENTS.md (the canonical project memory file). Clears the project-memory
+     * cache so subsequent reads see the new content.
+     */
+    writeProjectMemoryContent(workdir: string, content: string): Promise<void>;
 }

package/dist/services/memory.js

@@ -3,8 +3,11 @@ import * as path from "node:path";
 import { homedir } from "node:os";
 import { USER_MEMORY_FILE, DATA_DIRECTORY } from "../utils/constants.js";
 import { logger } from "../utils/globalLogger.js";
+import { atomicWriteFile } from "../utils/atomicWrite.js";
 import { getGitCommonDir } from "../utils/gitUtils.js";
 import { pathEncoder } from "../utils/pathEncoder.js";
+import { MEMORY_ENTRYPOINT_NAME } from "../constants/memory.js";
+import { truncateEntrypointContent } from "../utils/memoryEntrypoint.js";
 export class MemoryService {
     constructor(container) {
         this.container = container;
@@ -51,7 +54,7 @@ export class MemoryService {
             catch (error) {
                 if (error.code === "ENOENT") {
                     const initialContent = "# Project Memory\n\nThis file serves as an index for the project's auto-memory. Wave uses this to track knowledge across sessions.\n\n";
-                    await fs.writeFile(memoryFile, initialContent, "utf-8");
+                    await atomicWriteFile(memoryFile, initialContent);
                     logger.debug(`Created auto-memory file: ${memoryFile}`);
                 }
                 else {
@@ -65,18 +68,19 @@ export class MemoryService {
         }
     }
     /**
-     * Get the first 200 lines of MEMORY.md.
+     * Get the auto-memory entrypoint (`MEMORY.md`), bounded by both the line and
+     * the character cap. Truncation appends a warning naming the cap that fired,
+     * so the model can tell the index it is reading is incomplete.
      */
     async getAutoMemoryContent(workdir) {
         if (this._cachedAutoMemoryContent !== null) {
             return this._cachedAutoMemoryContent;
         }
         const memoryDir = this.getAutoMemoryDirectory(workdir);
-        const memoryFile = path.join(memoryDir, "MEMORY.md");
+        const memoryFile = path.join(memoryDir, MEMORY_ENTRYPOINT_NAME);
         try {
-            const content = await fs.readFile(memoryFile, "utf-8");
-            const lines = content.split("\n").slice(0, 200);
-            this._cachedAutoMemoryContent = lines.join("\n");
+            const raw = await fs.readFile(memoryFile, "utf-8");
+            this._cachedAutoMemoryContent = truncateEntrypointContent(raw).content;
             return this._cachedAutoMemoryContent;
         }
         catch (error) {
@@ -103,7 +107,7 @@ export class MemoryService {
                         userMemoryFile: USER_MEMORY_FILE,
                     });
                     const initialContent = "# User Memory\n\nThis is the user-level memory file, recording important information and context across projects.\n\n";
-                    await fs.writeFile(USER_MEMORY_FILE, initialContent, "utf-8");
+                    await atomicWriteFile(USER_MEMORY_FILE, initialContent);
                     logger.debug(`Created user memory file: ${USER_MEMORY_FILE}`);
                 }
                 else {
@@ -215,4 +219,37 @@ export class MemoryService {
         this._cachedCombinedMemory = combined;
         return combined;
     }
+    /**
+     * Persist the user-level memory file (~/.wave/AGENTS.md), creating it if
+     * missing. Clears the user-memory cache so subsequent reads see the new
+     * content (the default-template fallback to ~/.claude/AGENTS.md is also
+     * bypassed once the user writes real content).
+     */
+    async writeUserMemoryContent(content) {
+        await this.ensureUserMemoryFile();
+        await atomicWriteFile(USER_MEMORY_FILE, content);
+        this._cachedUserMemory = null;
+        this._cachedCombinedMemory = null;
+        logger.debug("User memory content written", {
+            userMemoryFile: USER_MEMORY_FILE,
+            contentLength: content.length,
+        });
+    }
+    /**
+     * Persist the project-level memory file (<workdir>/AGENTS.md), creating it
+     * if missing. Reads fall back to CLAUDE.md but writes always target
+     * AGENTS.md (the canonical project memory file). Clears the project-memory
+     * cache so subsequent reads see the new content.
+     */
+    async writeProjectMemoryContent(workdir, content) {
+        const memoryFilePath = path.join(workdir, "AGENTS.md");
+        await fs.mkdir(workdir, { recursive: true });
+        await atomicWriteFile(memoryFilePath, content);
+        this._cachedProjectMemory = null;
+        this._cachedCombinedMemory = null;
+        logger.debug("Project memory content written", {
+            memoryFilePath,
+            contentLength: content.length,
+        });
+    }
 }

package/dist/services/officialMarketplaceMirror.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Builtin official marketplace zip-snapshot mirror fetch.
+ *
+ * The official marketplace (wave-plugins-official, BUILTIN in MarketplaceService)
+ * is hosted on GitHub, which is poorly reachable from CN networks. Instead of a
+ * dumb-HTTP git endpoint we mirror the "content-addressed zip + latest pointer +
+ * local sentinel" model Claude Code uses for its official marketplace
+ * (officialMarketplaceGcs.ts, inc-5046):
+ *
+ *   1. GET `{base}/latest` (10s timeout) → content-addressed sha
+ *   2. Compare against the local sentinel `.wave-market-sha` at the market root
+ *      — equal ⇒ no-op (idempotent, one ~40B request per run)
+ *   3. GET `{base}/{sha}.zip` (60s timeout) → extract into a `.staging` dir
+ *      (path-traversal/absolute-path rejection, size limits, exec-bit restore
+ *      from zip external attrs)
+ *   4. Atomic swap: rm old market dir + rename staging → market dir, write the
+ *      sentinel back
+ *
+ * Any failure returns null; the caller decides whether to fall through to the
+ * existing git path (guarded by a kill switch, mirroring Claude's
+ * tengu_plugin_official_mkt_git_fallback flag).
+ */
+/** Sentinel file name stored at the market root holding the last fetched sha. */
+export declare const OFFICIAL_MARKET_SENTINEL_FILE = ".wave-market-sha";
+/** Env var override for the mirror base URL (highest precedence). */
+export declare const OFFICIAL_MARKET_MIRROR_BASE_URL_ENV = "WAVE_OFFICIAL_MARKET_MIRROR_BASE_URL";
+/**
+ * Kill switch for the git fallback after a mirror failure (default: allowed).
+ * Mirrors Claude Code's `tengu_plugin_official_mkt_git_fallback` flag. When
+ * false and the mirror fails, the builtin marketplace update is skipped
+ * (retried on next run) instead of hitting GitHub.
+ */
+export declare const ALLOW_OFFICIAL_MARKET_GIT_FALLBACK = true;
+/**
+ * Resolves the mirror base URL: env var wins, otherwise the built-in constant.
+ * Returns null when neither is configured (mirror channel disabled).
+ */
+export declare function resolveOfficialMarketplaceMirrorBaseUrl(): string | null;
+/**
+ * Rejects zip entry paths that would escape the extraction root: absolute
+ * paths (POSIX or Windows drive/UNC), `..` segments, and null bytes. Paths
+ * use either `/` or `\` as separator. Returns the normalized relative path on
+ * success or null for entries that must be skipped (empty/directory-only is
+ * handled by the caller via the trailing `/`).
+ */
+export declare function sanitizeZipEntryPath(entryPath: string): string | null;
+/**
+ * Fetches the official marketplace from the zip-snapshot mirror and extracts
+ * it to installLocation. Idempotent — compares the local `.wave-market-sha`
+ * sentinel before downloading.
+ *
+ * @param installLocation where to extract (must be inside marketplacesCacheDir)
+ * @param marketplacesCacheDir the marketplace cache root (defense-in-depth:
+ *   this function `rm`s installLocation during the atomic swap)
+ * @param baseUrl optional explicit base URL (tests); defaults to env/constant
+ * @returns the fetched sha on success (including no-op), null on any failure
+ *   (unconfigured mirror, network, 404, corrupt zip, unsafe entries). Caller
+ *   decides whether to fall through to git.
+ */
+export declare function fetchOfficialMarketplaceFromMirror(installLocation: string, marketplacesCacheDir: string, baseUrl?: string): Promise<string | null>;
+interface ZipValidationState {
+    fileCount: number;
+    totalUncompressed: number;
+    compressedSize: number;
+}
+/**
+ * Validates one zip entry (called from the fflate filter). Throws to abort the
+ * whole extraction when an entry is unsafe or the archive exceeds limits.
+ */
+export declare function validateZipEntry(name: string, originalSize: number, state: ZipValidationState): void;
+/**
+ * Parse Unix file modes from a zip's central directory.
+ *
+ * fflate's `unzipSync` returns only `Record<string, Uint8Array>` — it does not
+ * surface the external file attributes stored in the central directory, so
+ * executable bits would be lost (everything extracts as 0644). Returns
+ * `name → mode` for entries created on a Unix host (`versionMadeBy` high byte
+ * === 3); other entries are omitted and extract with default mode.
+ *
+ * Format per PKZIP APPNOTE.TXT §4.3.12 (central directory) and §4.3.16 (EOCD).
+ * ZIP64 is not handled — returns `{}` on archives >4GB or >65535 entries,
+ * which is fine for marketplace zips.
+ */
+export declare function parseZipModes(data: Uint8Array): Record<string, number>;
+export {};