wave-agent-sdk 1.0.9 → 1.0.10

package/dist/builtin/skills/simplify.d.ts

@@ -0,0 +1 @@
+export declare const simplifySkill: Record<string, string>;

package/{builtin/skills/simplify/SKILL.md → dist/builtin/skills/simplify.js}

@@ -1,4 +1,6 @@
----
+import { AGENT_TOOL_NAME } from "../../constants/tools.js";
+export const simplifySkill = {
+    "skills/simplify/SKILL.md": `---
 name: simplify
 description: Review the changed code for reuse, simplification, efficiency, and altitude cleanups, then apply the fixes. Quality only — it does not hunt for bugs; use /code-review for that.
 disable-model-invocation: true
@@ -10,11 +12,11 @@ Review all changed files for reuse, quality, and efficiency. Fix any issues foun
 
 ## Phase 1: Identify Changes
 
-Run `git diff` (or `git diff HEAD` if there are staged changes) to see what changed. If there are no git changes, review the most recently modified files that the user mentioned or that you edited earlier in this conversation.
+Run \`git diff\` (or \`git diff HEAD\` if there are staged changes) to see what changed. If there are no git changes, review the most recently modified files that the user mentioned or that you edited earlier in this conversation.
 
 ## Phase 2: Launch Three Review Agents in Parallel
 
-Use the Agent tool to launch all three agents concurrently in a single message. Pass each agent the full diff so it has the complete context.
+Use the ${AGENT_TOOL_NAME} tool to launch all three agents concurrently in a single message. Pass each agent the full diff so it has the complete context.
 
 ### Agent 1: Code Reuse Review
 
@@ -53,3 +55,5 @@ Review the same changes for efficiency:
 Wait for all three agents to complete. Aggregate their findings and fix each issue directly. If a finding is a false positive or not worth addressing, note it and move on — do not argue with the finding, just skip it.
 
 When done, briefly summarize what was fixed (or confirm the code was already clean).
+`,
+};

package/dist/builtin/subagents.d.ts

@@ -0,0 +1 @@
+export declare const subagents: Record<string, string>;

package/dist/builtin/subagents.js

@@ -0,0 +1,164 @@
+import { BASH_TOOL_NAME, EDIT_TOOL_NAME, GLOB_TOOL_NAME, GREP_TOOL_NAME, LSP_TOOL_NAME, READ_TOOL_NAME, WRITE_TOOL_NAME, } from "../constants/tools.js";
+export const subagents = {
+    "subagents/bash.md": `---
+name: Bash
+description: Command execution specialist for running bash commands. Use this for git operations, command execution, and other terminal tasks.
+tools: [${BASH_TOOL_NAME}]
+model: inherit
+---
+
+You are a command execution specialist. Your role is to execute bash commands efficiently and safely.
+
+Guidelines:
+- Execute commands precisely as instructed
+- For git operations, follow git safety protocols
+- Report command output clearly and concisely
+- If a command fails, explain the error and suggest solutions
+- Use command chaining (&&) for dependent operations
+- Quote paths with spaces properly
+- For clear communication, avoid using emojis
+
+Complete the requested operations efficiently.
+`,
+    "subagents/explore.md": `---
+name: Explore
+description: 'Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for comprehensive analysis across multiple locations and naming conventions.'
+tools: [${GLOB_TOOL_NAME}, ${GREP_TOOL_NAME}, ${READ_TOOL_NAME}, ${BASH_TOOL_NAME}, ${LSP_TOOL_NAME}]
+model: fastModel
+---
+
+You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+	
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
+- Creating new files (no ${WRITE_TOOL_NAME}, touch, or file creation of any kind)
+- Modifying existing files (no ${EDIT_TOOL_NAME} operations)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools - attempting to edit files will fail.
+
+Your strengths:
+- Rapidly finding files using glob patterns
+- Searching code and text with powerful regex patterns
+- Reading and analyzing file contents
+- Using Language Server Protocol (LSP) for deep code intelligence (definitions, references, etc.)
+
+Guidelines:
+- Use ${GLOB_TOOL_NAME} for broad file pattern matching
+- Use ${GREP_TOOL_NAME} for searching file contents with regex
+- Use ${READ_TOOL_NAME} when you know the specific file path you need to read
+- Use ${LSP_TOOL_NAME} for code intelligence features like finding definitions, references, implementations, and symbols. This is especially useful for understanding complex code relationships.
+- Use ${BASH_TOOL_NAME} ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+- NEVER use ${BASH_TOOL_NAME} for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
+- Adapt your search approach based on the thoroughness level specified by the caller
+- Return file paths as absolute paths in your final response
+- For clear communication, avoid using emojis
+- Communicate your final report directly as a regular message - do NOT attempt to create files
+
+NOTE: You are meant to be a fast agent that returns output as quickly as possible. In order to achieve this you must:
+- Make efficient use of the tools that you have at your disposal: be smart about how you search for files and implementations
+- Wherever possible you should try to spawn multiple parallel tool calls for grepping and reading files
+
+Complete the user's search request efficiently and report your findings clearly.
+`,
+    "subagents/general-purpose.md": `---
+description: General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you.
+---
+
+You are an agent. Given the user's message, you should use the tools available to complete the task. Do what has been asked; nothing more, nothing less. When you complete the task simply respond with a detailed writeup.
+
+Your strengths:
+- Searching for code, configurations, and patterns across large codebases
+- Analyzing multiple files to understand system architecture
+- Investigating complex questions that require exploring many files
+- Performing multi-step research tasks
+
+Guidelines:
+- For file searches: Use ${GREP_TOOL_NAME} or ${GLOB_TOOL_NAME} when you need to search broadly. Use ${READ_TOOL_NAME} when you know the specific file path.
+- For analysis: Start broad and narrow down. Use multiple search strategies if the first doesn't yield results.
+- Be thorough: Check multiple locations, consider different naming conventions, look for related files.
+- NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one.
+- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested.
+- In your final response always share relevant file names and code snippets. Any file paths you return in your response MUST be absolute. Do NOT use relative paths.
+- For clear communication, avoid using emojis.
+`,
+    "subagents/plan.md": `---
+name: Plan
+description: Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.
+tools: [${GLOB_TOOL_NAME}, ${GREP_TOOL_NAME}, ${READ_TOOL_NAME}, ${BASH_TOOL_NAME}, ${LSP_TOOL_NAME}]
+model: inherit
+---
+
+You are a software architect and planning specialist. Your role is to explore the codebase and design implementation plans.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
+- Creating new files (no ${WRITE_TOOL_NAME}, touch, or file creation of any kind)
+- Modifying existing files (no ${EDIT_TOOL_NAME} operations)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to explore the codebase and design implementation plans. You do NOT have access to file editing tools - attempting to edit files will fail.
+
+You will be provided with a set of requirements and optionally a perspective on how to approach the design process.
+
+## Your Process
+
+1. **Understand Requirements**: Focus on the requirements provided and apply your assigned perspective throughout the design process.
+
+2. **Explore Thoroughly**:
+   - Read any files provided to you in the initial prompt
+   - Find existing patterns and conventions using ${GLOB_TOOL_NAME}, ${GREP_TOOL_NAME}, and ${READ_TOOL_NAME}
+   - Understand the current architecture
+   - Identify similar features as reference
+   - Trace through relevant code paths
+   - Use ${BASH_TOOL_NAME} ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+   - NEVER use ${BASH_TOOL_NAME} for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
+
+3. **Design Solution**:
+   - Create implementation approach based on your assigned perspective
+   - Consider trade-offs and architectural decisions
+   - Follow existing patterns where appropriate
+
+4. **Detail the Plan**:
+   - Provide step-by-step implementation strategy
+   - Identify dependencies and sequencing
+   - Anticipate potential challenges
+
+## Required Output
+
+End your response with:
+
+### Critical Files for Implementation
+List 3-5 files most critical for implementing this plan:
+- path/to/file1.ts - [Brief reason: e.g., "Core logic to modify"]
+- path/to/file2.ts - [Brief reason: e.g., "Interfaces to implement"]
+- path/to/file3.ts - [Brief reason: e.g., "Pattern to follow"]
+
+REMEMBER: You can ONLY explore and plan. You CANNOT and MUST NOT write, edit, or modify any files. You do NOT have access to file editing tools.
+`,
+    "subagents/vision.md": `---
+name: vision
+description: 'Image recognition specialist that runs on the model specified by the WAVE_VISION_MODEL environment variable. Use this when the current model does not support image recognition but the user has shared an image (identify the image by its "[Image source: <path>]" metadata). Pass the image file path(s) in the prompt; this agent reads the image with the ${READ_TOOL_NAME} tool and returns a detailed text description of its contents.'
+tools: [${READ_TOOL_NAME}]
+model: visionModel
+---
+
+You are an image recognition specialist. You run on a vision-capable model and your job is to look at image files and return detailed text descriptions of their contents.
+
+When given image file path(s):
+- Use the ${READ_TOOL_NAME} tool on each image path to load it. The ${READ_TOOL_NAME} tool returns the image as base64 image data that you can see directly.
+- Describe the image contents in detail: what is shown, any visible text (transcribe verbatim where relevant), layout, colors, objects, and anything else the caller asked about.
+- If an image cannot be read (file missing, not an image, or too large), report the error clearly and state which path failed.
+- Do not invent or guess content you cannot see — only describe what the image actually shows.
+- Return your description directly as a text message. Do NOT create files.
+- Avoid using emojis in your response.
+
+Complete the image recognition task and report your findings clearly.
+`,
+};

package/dist/managers/aiManager.js

@@ -1,6 +1,7 @@
 import * as aiService from "../services/aiService.js";
 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 } from "../utils/tokenCalculation.js";
 import { estimateTokens } from "../utils/tokenEstimate.js";
@@ -452,6 +453,10 @@ export class AIManager {
             const enhancedSummary = await this.buildPostCompactContext(formattedSummary);
             // 8. Execute message reconstruction
             await this.messageManager.compactMessagesAndUpdateSession(enhancedSummary, compactUsage);
+            // Clear readFileState after compaction (aligned with Claude Code's
+            // compact flow): a file_unchanged stub would otherwise reference Read
+            // results that were just folded away. Clearing forces a real re-read.
+            this.readFileState.clear();
             // Re-add plan mode reminder as persistent meta message after compaction
             const postCompactMode = this.permissionManager?.getCurrentEffectiveMode(this.getModelConfig().permissionMode);
             if (postCompactMode === "plan") {
@@ -1904,6 +1909,18 @@ ${question}`;
             };
             // Execute tool
             const toolResult = await this.toolManager.execute(functionToolCall.function?.name || "", toolArgs, context);
+            // MCP tools can return images (e.g. Figma screenshots) as in-memory
+            // base64. When this agent's model cannot see them, persist each image to
+            // a temp file so the non-vision path in convertMessagesForAPI can attach
+            // `[Image source: <path>]` metadata and the main model can delegate
+            // recognition to the vision subagent. Vision-capable models keep the
+            // inline base64 — no disk writes.
+            let toolImages = toolResult.images;
+            if (toolImages &&
+                toolImages.length > 0 &&
+                !supportsVision(this.getModelConfig().capabilities)) {
+                toolImages = persistToolImages(toolImages);
+            }
             // Build result content, adding truncation warning if JSON was recovered
             let toolResultContent = toolResult.content ||
                 (toolResult.error ? `Error: ${toolResult.error}` : "");
@@ -1926,7 +1943,7 @@ ${question}`;
                 backgroundedByUser: toolResult.backgroundedByUser,
                 assistantAutoBackgrounded: toolResult.assistantAutoBackgrounded,
                 startLineNumber: toolResult.startLineNumber,
-                images: toolResult.images,
+                images: toolImages,
                 timestamp: Date.now(),
             });
             // Execute PostToolUse hooks after successful tool completion

package/dist/managers/mcpManager.js

@@ -656,7 +656,7 @@ export class McpManager {
                     else if (c.type === "image" && c.data) {
                         images.push({
                             data: c.data,
-                            mediaType: "image/png", // Default to PNG
+                            mediaType: c.mimeType || "image/png", // MCP standard mimeType, PNG fallback
                         });
                     }
                     else if (c.type === "resource") {

package/dist/managers/messageManager.d.ts

@@ -222,6 +222,12 @@ export declare class MessageManager {
      * Extract file read contents from tool result blocks in a message.
      */
     private extractFileReadsFromMessage;
+    /**
+     * Bound recentFileReads growth: evict oldest entries beyond the cache limit
+     * and drop content from all but the most recent entries (paths are kept for
+     * hasFileBeenRead). Prevents unbounded memory growth in long sessions.
+     */
+    private trimRecentFileReads;
     /**
      * Get recent file read contents, sorted by timestamp (newest first).
      * @param maxFiles - Maximum number of files to return

package/dist/managers/messageManager.js

@@ -5,6 +5,13 @@ import { appendMessages, createSession, generateSessionId, SESSION_DIR, } from "
 import { pathEncoder } from "../utils/pathEncoder.js";
 import { estimateTokens } from "../utils/tokenEstimate.js";
 import { READ_TOOL_NAME } from "../constants/tools.js";
+// Cap for recentFileReads: content is only consumed by getRecentFileReads
+// (top 5 for post-compact restoration), so bound both the entry count and the
+// number of entries that keep full content (aligned with Claude Code's
+// FileStateCache 100-entry limit). Paths beyond the content cap are kept so
+// hasFileBeenRead still works for read-before-edit enforcement.
+const RECENT_FILE_READS_CACHE_LIMIT = 100;
+const RECENT_FILE_READS_CONTENT_LIMIT = 10;
 import { logger } from "../utils/globalLogger.js";
 export class MessageManager {
     constructor(container, options) {
@@ -397,6 +404,8 @@ export class MessageManager {
         // Update in-memory state
         this.setMessages(newMessages);
         this.savedMessageCount = newMessages.length;
+        // Trim recent file read cache so contents compacted away are released
+        this.trimRecentFileReads();
         // Clear and rebuild loaded rule IDs from remaining meta messages
         this.clearLoadedRuleIds();
         this.rebuildLoadedRuleIds();
@@ -779,10 +788,34 @@ export class MessageManager {
                         content: block.result,
                         timestamp: Date.now(),
                     });
+                    this.trimRecentFileReads();
                 }
             }
         }
     }
+    /**
+     * Bound recentFileReads growth: evict oldest entries beyond the cache limit
+     * and drop content from all but the most recent entries (paths are kept for
+     * hasFileBeenRead). Prevents unbounded memory growth in long sessions.
+     */
+    trimRecentFileReads() {
+        if (this.recentFileReads.size > RECENT_FILE_READS_CACHE_LIMIT) {
+            const sortedAsc = Array.from(this.recentFileReads.entries()).sort(([, a], [, b]) => a.timestamp - b.timestamp);
+            const excess = this.recentFileReads.size - RECENT_FILE_READS_CACHE_LIMIT;
+            for (const [path] of sortedAsc.slice(0, excess)) {
+                this.recentFileReads.delete(path);
+            }
+        }
+        if (this.recentFileReads.size > RECENT_FILE_READS_CONTENT_LIMIT) {
+            const sortedDesc = Array.from(this.recentFileReads.entries()).sort(([, a], [, b]) => b.timestamp - a.timestamp);
+            for (const [path, entry] of sortedDesc.slice(RECENT_FILE_READS_CONTENT_LIMIT)) {
+                this.recentFileReads.set(path, {
+                    content: "",
+                    timestamp: entry.timestamp,
+                });
+            }
+        }
+    }
     /**
      * Get recent file read contents, sorted by timestamp (newest first).
      * @param maxFiles - Maximum number of files to return

package/dist/managers/subagentManager.d.ts

@@ -150,6 +150,14 @@ export declare class SubagentManager {
      * Clean up completed, errored, or aborted instances
      */
     cleanupInstance(subagentId: string): void;
+    /**
+     * Release a subagent instance so its graph (message history, file-read
+     * caches, log stream) can be garbage-collected. Besides removing the
+     * instance from the map, this drops the background task's onStop closure,
+     * which captures the instance and would otherwise keep the whole graph
+     * alive for the rest of the session.
+     */
+    private releaseInstance;
     /**
      * Get all active instances
      */

package/dist/managers/subagentManager.js

@@ -171,6 +171,16 @@ export class SubagentManager {
         // Without this, concurrent background subagents steal sibling completion
         // notifications from the parent queue, causing the main agent to exit early.
         subagentContainer.register("MessageQueue", new MessageQueue());
+        // Deliberately shadow the parent ReversionManager with `undefined` so the
+        // subagent resolves no reversion manager instead of falling back to the
+        // parent's. Subagent Write/Edit must not be recorded into the main agent's
+        // file_history buffer — this mirrors Claude Code's explicit isolation for
+        // forked agents (`updateFileHistoryState: () => {}` in forkedAgent.ts).
+        // Without this, the subagent drains the SHARED parent buffer into its own
+        // transient messages (discarded on cleanup), leaving orphaned snapshot
+        // files on disk and racing the main agent's own drain. All ReversionManager
+        // consumers are truthiness-guarded, so resolving to `undefined` is safe.
+        subagentContainer.register("ReversionManager", undefined);
         // Register a modified AgentOptions without onLoadingChange to prevent subagent loading
         // from affecting the parent agent's loading state
         const parentOptions = this.container.get("AgentOptions");
@@ -342,13 +352,29 @@ export class SubagentManager {
                             task.runtime = task.endTime - startTime;
                         }
                     }
+                    finally {
+                        // Free the instance once the background task finishes: without
+                        // this the instance (message history, caches) would linger in the
+                        // map for the whole session, and the task's onStop closure would
+                        // keep it alive even after that.
+                        this.releaseInstance(instance.subagentId);
+                    }
                 })();
                 return taskId;
             }
-            return await this.internalExecute(instance, prompt, abortSignal);
+            const result = await this.internalExecute(instance, prompt, abortSignal);
+            // Free the instance once the subagent finishes. Callers that still hold
+            // the reference can read its messageManager, but the map entry and the
+            // background task's onStop closure are released so the message history
+            // and caches can be garbage-collected.
+            this.releaseInstance(instance.subagentId);
+            return result;
         }
         catch (error) {
             this.updateInstanceStatus(instance.subagentId, "error");
+            // Release on failure too so errored instances don't linger for the
+            // session (the abort listener already releases on abort).
+            this.releaseInstance(instance.subagentId);
             throw error;
         }
     }
@@ -543,8 +569,37 @@ export class SubagentManager {
             (instance.status === "completed" ||
                 instance.status === "error" ||
                 instance.status === "aborted")) {
-            this.instances.delete(subagentId);
+            this.releaseInstance(subagentId);
+        }
+    }
+    /**
+     * Release a subagent instance so its graph (message history, file-read
+     * caches, log stream) can be garbage-collected. Besides removing the
+     * instance from the map, this drops the background task's onStop closure,
+     * which captures the instance and would otherwise keep the whole graph
+     * alive for the rest of the session.
+     */
+    releaseInstance(subagentId) {
+        const instance = this.instances.get(subagentId);
+        if (!instance) {
+            return;
+        }
+        if (instance.backgroundTaskId) {
+            const backgroundTaskManager = this.container.has("BackgroundTaskManager")
+                ? this.container.get("BackgroundTaskManager")
+                : undefined;
+            const task = backgroundTaskManager?.getTask(instance.backgroundTaskId);
+            if (task) {
+                task.onStop = undefined;
+            }
+        }
+        if (instance.logStream && !instance.logStream.writableEnded) {
+            // Only force-close a stream that hasn't been ended yet (the completion
+            // and error paths already call end(); destroy would drop buffered data).
+            instance.logStream.destroy();
         }
+        instance.logStream = undefined;
+        this.instances.delete(subagentId);
     }
     /**
      * Get all active instances

package/dist/tools/editTool.js

@@ -243,6 +243,7 @@ Usage:
                 context.readFileState.set(resolvedPath, {
                     mtime: newStats.mtime.getTime(),
                     hash,
+                    source: "edit",
                     offset: undefined,
                     limit: undefined,
                 });

package/dist/tools/readTool.js

@@ -208,12 +208,14 @@ Usage:
                 : resolvePath(filePath, context.workdir);
             const stats = await stat(actualFilePath);
             // Deduplication: only dedup if the exact same range was read before
+            // (aligned with Claude Code — full reads dedup too). Entries written by
+            // Edit/Write have source "edit"/"write" and never dedup, so a file that
+            // was written before its first Read is still returned in full.
             if (context.readFileState) {
                 const state = context.readFileState.get(actualFilePath);
-                // Only dedup entries from a prior Read with explicit offset (not Edit/Write entries)
                 if (state &&
-                    state.mtime === stats.mtime.getTime() &&
-                    state.offset !== undefined) {
+                    state.source === "read" &&
+                    state.mtime === stats.mtime.getTime()) {
                     const rangeMatch = state.offset === offset && state.limit === limit;
                     if (rangeMatch) {
                         return {
@@ -249,6 +251,7 @@ Usage:
                 context.readFileState.set(actualFilePath, {
                     mtime: stats.mtime.getTime(),
                     hash,
+                    source: "read",
                     offset, // undefined for full reads
                     limit, // undefined for full reads
                 });

package/dist/tools/types.d.ts

@@ -95,6 +95,7 @@ export interface ToolContext {
     readFileState?: Map<string, {
         mtime: number;
         hash: string;
+        source: "read" | "edit" | "write";
         offset?: number;
         limit?: number;
     }>;

package/dist/tools/writeTool.js

@@ -179,6 +179,7 @@ Usage:
                 context.readFileState.set(resolvedPath, {
                     mtime: newStats.mtime.getTime(),
                     hash,
+                    source: "write",
                     offset: undefined,
                     limit: undefined,
                 });

package/dist/types/messaging.d.ts

@@ -37,6 +37,7 @@ export interface ToolBlock {
     images?: Array<{
         data: string;
         mediaType?: string;
+        path?: string;
     }>;
     id?: string;
     name?: string;

package/dist/utils/builtinEmbed.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Builtin content embedding.
+ *
+ * Builtin skills/subagents/plugins ship as TS source (src/builtin/*.ts) and are
+ * compiled into the bundle. At runtime they are lazily materialized to a
+ * content-hashed cache directory under the OS temp dir, so consumers that
+ * readdirSync real directories keep working unchanged — including inside
+ * esbuild bundles that never ship a `builtin/` dir on disk.
+ */
+/**
+ * Content-hash key: sha256 of the sorted `rel\0content` entries, truncated.
+ * Any change to builtin content yields a new key, auto-invalidating stale caches.
+ */
+export declare function getBuiltinCacheKey(): string;
+/**
+ * Materialize builtin content to `{tmpdir}/wave-builtin/{contentHash}/` and
+ * return the directory. Memoized per process; idempotent across processes via
+ * the `.wave-builtin-complete` marker written last (a torn write leaves no
+ * marker, so the next run rewrites).
+ */
+export declare function ensureBuiltinMaterialized(): string;

package/dist/utils/builtinEmbed.js

@@ -0,0 +1,53 @@
+/**
+ * Builtin content embedding.
+ *
+ * Builtin skills/subagents/plugins ship as TS source (src/builtin/*.ts) and are
+ * compiled into the bundle. At runtime they are lazily materialized to a
+ * content-hashed cache directory under the OS temp dir, so consumers that
+ * readdirSync real directories keep working unchanged — including inside
+ * esbuild bundles that never ship a `builtin/` dir on disk.
+ */
+import { createHash } from "crypto";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { dirname, join } from "path";
+import { BUILTIN_CONTENT } from "../builtin/index.js";
+const BUILTIN_CACHE_ROOT = "wave-builtin";
+const BUILTIN_CACHE_COMPLETE = ".wave-builtin-complete";
+/**
+ * Content-hash key: sha256 of the sorted `rel\0content` entries, truncated.
+ * Any change to builtin content yields a new key, auto-invalidating stale caches.
+ */
+export function getBuiltinCacheKey() {
+    const entries = Object.keys(BUILTIN_CONTENT)
+        .sort()
+        .map((rel) => `${rel}\0${BUILTIN_CONTENT[rel]}`);
+    return createHash("sha256")
+        .update(entries.join("\0"))
+        .digest("hex")
+        .slice(0, 16);
+}
+let _builtinDir;
+/**
+ * Materialize builtin content to `{tmpdir}/wave-builtin/{contentHash}/` and
+ * return the directory. Memoized per process; idempotent across processes via
+ * the `.wave-builtin-complete` marker written last (a torn write leaves no
+ * marker, so the next run rewrites).
+ */
+export function ensureBuiltinMaterialized() {
+    if (_builtinDir)
+        return _builtinDir;
+    const dir = join(tmpdir(), BUILTIN_CACHE_ROOT, getBuiltinCacheKey());
+    const marker = join(dir, BUILTIN_CACHE_COMPLETE);
+    if (!existsSync(marker)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        for (const [rel, content] of Object.entries(BUILTIN_CONTENT)) {
+            const filePath = join(dir, rel);
+            mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+            writeFileSync(filePath, content);
+        }
+        writeFileSync(marker, "");
+    }
+    _builtinDir = dir;
+    return dir;
+}

package/dist/utils/configPaths.d.ts

@@ -9,7 +9,6 @@
  * - Local configs: {workdir}/.wave/settings.local.json > {workdir}/.wave/settings.json
  * - Project configs override user configs (existing behavior)
  */
-export declare function getPackageRoot(): string;
 /**
  * Get the builtin skills directory path
  */

package/dist/utils/configPaths.js

@@ -9,48 +9,27 @@
  * - Local configs: {workdir}/.wave/settings.local.json > {workdir}/.wave/settings.json
  * - Project configs override user configs (existing behavior)
  */
-import { join, dirname } from "path";
+import { join } from "path";
 import { homedir } from "os";
 import { existsSync } from "fs";
-import { fileURLToPath } from "url";
-import { findUpSync } from "find-up";
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-/**
- * Resolve the package root directory by finding the nearest package.json.
- * Works correctly even when bundled (e.g. esbuild into a VS Code extension),
- * as long as vendor/ and builtin/ remain alongside package.json on disk.
- */
-let _packageRoot;
-export function getPackageRoot() {
-    if (_packageRoot)
-        return _packageRoot;
-    const pkgPath = findUpSync("package.json", { cwd: __dirname });
-    if (pkgPath) {
-        _packageRoot = dirname(pkgPath);
-        return _packageRoot;
-    }
-    // Fallback: relative to this file (works during development)
-    _packageRoot = join(__dirname, "..", "..");
-    return _packageRoot;
-}
+import { ensureBuiltinMaterialized } from "./builtinEmbed.js";
 /**
  * Get the builtin skills directory path
  */
 export function getBuiltinSkillsDir() {
-    return join(getPackageRoot(), "builtin", "skills");
+    return join(ensureBuiltinMaterialized(), "skills");
 }
 /**
  * Get the builtin subagents directory path
  */
 export function getBuiltinSubagentsDir() {
-    return join(getPackageRoot(), "builtin", "subagents");
+    return join(ensureBuiltinMaterialized(), "subagents");
 }
 /**
  * Get the builtin plugins directory path
  */
 export function getBuiltinPluginsDir() {
-    return join(getPackageRoot(), "builtin", "plugins");
+    return join(ensureBuiltinMaterialized(), "plugins");
 }
 /**
  * Get the user-specific configuration file path (legacy function)