wave-agent-sdk 0.0.8 → 0.0.10

package/src/utils/fileUtils.ts

@@ -1,4 +1,8 @@
-import fs from "node:fs";
+import fs from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { homedir } from "node:os";
 
 /**
  * Reads the first line of a file efficiently using Node.js readline.
@@ -7,7 +11,6 @@ import fs from "node:fs";
  * @return {Promise<string>} - The first non-empty line of the file, or an empty string otherwise.
  */
 export async function readFirstLine(filePath: string): Promise<string> {
-  const { createReadStream } = fs;
   const { createInterface } = await import("node:readline");
 
   const fileStream = createReadStream(filePath);
@@ -34,32 +37,124 @@ export async function readFirstLine(filePath: string): Promise<string> {
 }
 
 /**
- * Reads a file from the end and returns the first non-empty line.
+ * Reads a file from the end and returns the last non-empty line.
+ *
+ * This version supports files that end with:
+ *   - "\n" (Unix-style, including modern macOS)
+ *   - "\r\n" (Windows-style)
+ *   - "\r" (older Mac-style, HL7, etc.)
  *
  * @param {string} filePath - The path to the file.
+ * @param {number} [minLength=1] - Minimum length for the returned line.
  * @return {Promise<string>} - The last non-empty line of the file, or an empty string if no non-empty lines found.
  */
-export async function getLastLine(filePath: string): Promise<string> {
-  const { exec } = await import("child_process");
-  const { promisify } = await import("util");
-  const execAsync = promisify(exec);
-
+export async function getLastLine(
+  filePath: string,
+  minLength = 1,
+): Promise<string> {
+  let fileHandle;
   try {
-    // Use tail with multiple lines to handle cases where the last line might be empty
-    const { stdout } = await execAsync(`tail -n 3 "${filePath}"`);
-    const lines = stdout.split(/\r?\n/);
-
-    // Find the first non-empty line working backwards
-    for (let i = lines.length - 1; i >= 0; i--) {
-      const line = lines[i].trim();
-      if (line.length > 0) {
-        return line;
+    const stats = await fs.stat(filePath);
+    const fileSize = stats.size;
+
+    if (fileSize === 0) return "";
+
+    fileHandle = await fs.open(filePath, "r");
+    const bufferSize = 8 * 1024; // 8KB buffer is usually enough for the last line
+    const buffer = Buffer.alloc(bufferSize);
+
+    let lineEnd: number | null = null;
+    let lineStart: number | null = null;
+    let currentPosition = fileSize;
+
+    while (currentPosition > 0 && lineStart === null) {
+      const readSize = Math.min(bufferSize, currentPosition);
+      currentPosition -= readSize;
+
+      const { bytesRead } = await fileHandle.read(
+        buffer,
+        0,
+        readSize,
+        currentPosition,
+      );
+
+      for (let i = bytesRead - 1; i >= 0; i--) {
+        const charCode = buffer[i];
+        if (lineEnd === null) {
+          // Still looking for the end of the last non-empty line (skip trailing newlines and whitespace)
+          if (charCode > 32) {
+            lineEnd = currentPosition + i + 1;
+          }
+        } else {
+          // Looking for the start of the line (the newline before it)
+          if (charCode === 10 || charCode === 13) {
+            lineStart = currentPosition + i + 1;
+            break;
+          }
+        }
       }
     }
 
-    return "";
+    if (lineEnd === null) return "";
+    if (lineStart === null) lineStart = 0;
+
+    const length = lineEnd - lineStart;
+    if (length < minLength) return "";
+
+    const resultBuffer = Buffer.alloc(length);
+    await fileHandle.read(resultBuffer, 0, length, lineStart);
+    const result = resultBuffer.toString("utf8").trim();
+    return result.length >= minLength ? result : "";
   } catch {
-    // If tail fails (e.g., file doesn't exist), return empty string
+    // If reading fails (e.g., file doesn't exist), return empty string
     return "";
+  } finally {
+    if (fileHandle) {
+      await fileHandle.close();
+    }
+  }
+}
+
+/**
+ * Ensures that a pattern is present in the global git ignore file.
+ *
+ * @param {string} pattern - The pattern to add to global git ignore.
+ */
+export async function ensureGlobalGitIgnore(pattern: string): Promise<void> {
+  try {
+    let globalIgnorePath: string;
+    try {
+      globalIgnorePath = execSync("git config --get core.excludesfile", {
+        encoding: "utf8",
+      }).trim();
+    } catch {
+      // If not set, use default paths
+      const xdgConfigHome =
+        process.env.XDG_CONFIG_HOME || path.join(homedir(), ".config");
+      globalIgnorePath = path.join(xdgConfigHome, "git", "ignore");
+    }
+
+    if (!globalIgnorePath) return;
+
+    // Ensure directory exists
+    await fs.mkdir(path.dirname(globalIgnorePath), { recursive: true });
+
+    let content = "";
+    try {
+      content = await fs.readFile(globalIgnorePath, "utf8");
+    } catch {
+      // File doesn't exist
+    }
+
+    const lines = content.split("\n").map((line) => line.trim());
+    if (!lines.includes(pattern)) {
+      const newContent =
+        content.endsWith("\n") || content === ""
+          ? `${content}${pattern}\n`
+          : `${content}\n${pattern}\n`;
+      await fs.writeFile(globalIgnorePath, newContent, "utf8");
+    }
+  } catch {
+    // Ignore errors
   }
 }

package/src/utils/globalLogger.ts

@@ -46,23 +46,6 @@ export function setGlobalLogger(logger: Logger | null): void {
   globalLogger = logger;
 }
 
-/**
- * Retrieve the current global logger instance
- *
- * @returns Current logger instance or null if unconfigured
- *
- * @example
- * ```typescript
- * const currentLogger = getGlobalLogger();
- * if (currentLogger) {
- *   currentLogger.info('Direct logger access');
- * }
- * ```
- */
-export function getGlobalLogger(): Logger | null {
-  return globalLogger;
-}
-
 /**
  * Reset global logger to unconfigured state
  * Equivalent to setGlobalLogger(null)

package/src/utils/largeOutputHandler.ts

@@ -0,0 +1,55 @@
+import { writeFile } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
+import { logger } from "./globalLogger.js";
+import {
+  estimateTokenCount,
+  getTokenUsageDescription,
+} from "./tokenEstimator.js";
+
+// Token threshold for writing output to temp file (20k tokens)
+export const LARGE_OUTPUT_TOKEN_THRESHOLD = 20000;
+
+/**
+ * Handle large command output by writing to temporary file when token threshold is exceeded
+ *
+ * Uses token-based threshold (20k tokens) to determine when output should be written to temp file.
+ * This provides accurate estimation of actual token cost for LLM processing.
+ *
+ * @param output - The command output string
+ * @returns Object containing processed content and optional file path
+ */
+export async function handleLargeOutput(output: string): Promise<{
+  content: string;
+  filePath?: string;
+}> {
+  const estimatedTokens = estimateTokenCount(output);
+
+  // Check token threshold
+  if (estimatedTokens <= LARGE_OUTPUT_TOKEN_THRESHOLD) {
+    return { content: output };
+  }
+
+  try {
+    // Create temp file for large output
+    const tempFileName = `bash-output-${Date.now()}-${Math.random().toString(36).substr(2, 9)}.txt`;
+    const tempFilePath = join(tmpdir(), tempFileName);
+
+    await writeFile(tempFilePath, output, "utf8");
+
+    const sizeKB = Math.round(output.length / 1024);
+    const tokenDescription = getTokenUsageDescription(
+      output,
+      LARGE_OUTPUT_TOKEN_THRESHOLD,
+    );
+
+    return {
+      content: `Large output (${sizeKB} KB, ${tokenDescription}) written to temporary file. Use the Read tool to access the full content.`,
+      filePath: tempFilePath,
+    };
+  } catch (error) {
+    logger.warn(`Failed to write large output to temp file: ${error}`);
+    // Fallback to direct output if temp file creation fails
+    return { content: output };
+  }
+}

package/src/utils/markdownParser.ts

@@ -37,18 +37,7 @@ function parseFrontmatter(content: string): {
       const key = trimmedLine.slice(0, colonIndex).trim();
       const value = trimmedLine.slice(colonIndex + 1).trim();
 
-      // Handle array values for allowed-tools
-      if (key === "allowed-tools" && value) {
-        // Simple array parsing: "tool1, tool2, tool3" or "[tool1, tool2]"
-        let arrayValue = value;
-        if (arrayValue.startsWith("[") && arrayValue.endsWith("]")) {
-          arrayValue = arrayValue.slice(1, -1);
-        }
-        frontmatter[key] = arrayValue
-          .split(",")
-          .map((s) => s.trim())
-          .filter(Boolean);
-      } else if (value) {
+      if (value) {
         frontmatter[key] = value;
       }
     }
@@ -73,13 +62,6 @@ export function parseMarkdownFile(filePath: string): ParsedMarkdownFile {
     if (frontmatter) {
       config = {};
 
-      if (
-        frontmatter["allowed-tools"] &&
-        Array.isArray(frontmatter["allowed-tools"])
-      ) {
-        config.allowedTools = frontmatter["allowed-tools"] as string[];
-      }
-
       if (frontmatter.model && typeof frontmatter.model === "string") {
         config.model = frontmatter.model;
       }

package/src/utils/messageOperations.ts

@@ -47,12 +47,6 @@ export type AgentToolBlockUpdateParams = Omit<
   "messages"
 >;
 
-export interface AddDiffBlockParams {
-  messages: Message[];
-  path: string;
-  diffResult: Array<{ value: string; added?: boolean; removed?: boolean }>;
-}
-
 export interface AddErrorBlockParams {
   messages: Message[];
   error: string;
@@ -186,7 +180,7 @@ export const addAssistantMessageToMessages = (
   content?: string,
   toolCalls?: ChatCompletionMessageFunctionToolCall[],
   usage?: Usage,
-  metadata?: Record<string, unknown>,
+  additionalFields?: Record<string, unknown>,
 ): Message[] => {
   const blocks: Message["blocks"] = [];
 
@@ -213,34 +207,12 @@ export const addAssistantMessageToMessages = (
     role: "assistant",
     blocks,
     usage, // Include usage data if provided
-    ...(metadata ? { metadata: { ...metadata } } : {}),
+    ...(additionalFields ? { additionalFields: { ...additionalFields } } : {}),
   };
 
   return [...messages, initialAssistantMessage];
 };
 
-// Update File Operation Block of the last assistant message
-export const addDiffBlockToMessage = ({
-  messages,
-  path,
-  diffResult,
-}: AddDiffBlockParams): Message[] => {
-  const newMessages = [...messages];
-  // Find the last assistant message
-  for (let i = newMessages.length - 1; i >= 0; i--) {
-    if (newMessages[i].role === "assistant") {
-      // Directly add diff block instead of replacing existing blocks
-      newMessages[i].blocks.push({
-        type: "diff",
-        path: path,
-        diffResult: diffResult,
-      });
-      break;
-    }
-  }
-  return newMessages;
-};
-
 // Update Tool Block of the last assistant message
 export const updateToolBlockInMessage = ({
   messages,
@@ -453,7 +425,7 @@ export const addCommandOutputMessage = ({
   command,
 }: AddCommandOutputParams): Message[] => {
   const outputMessage: Message = {
-    role: "assistant",
+    role: "user",
     blocks: [
       {
         type: "command_output",
@@ -475,10 +447,10 @@ export const updateCommandOutputInMessage = ({
   output,
 }: UpdateCommandOutputParams): Message[] => {
   const newMessages = [...messages];
-  // Find the last assistant message with a command_output block for this command
+  // Find the last user message with a command_output block for this command
   for (let i = newMessages.length - 1; i >= 0; i--) {
     const msg = newMessages[i];
-    if (msg.role === "assistant") {
+    if (msg.role === "user") {
       const commandBlock = msg.blocks.find(
         (block) =>
           block.type === "command_output" &&
@@ -501,10 +473,10 @@ export const completeCommandInMessage = ({
   exitCode,
 }: CompleteCommandParams): Message[] => {
   const newMessages = [...messages];
-  // Find the last assistant message with a command_output block for this command
+  // Find the last user message with a command_output block for this command
   for (let i = newMessages.length - 1; i >= 0; i--) {
     const msg = newMessages[i];
-    if (msg.role === "assistant") {
+    if (msg.role === "user") {
       const commandBlock = msg.blocks.find(
         (block) =>
           block.type === "command_output" &&

package/src/utils/pathEncoder.ts

@@ -190,9 +190,9 @@ export class PathEncoder {
   }
 
   /**
-   * Create project directory entity from original path
+   * Get project directory info without creating the directory
    */
-  async createProjectDirectory(
+  async getProjectDirectory(
     originalPath: string,
     baseSessionDir: string,
   ): Promise<ProjectDirectory> {
@@ -221,13 +221,6 @@ export class PathEncoder {
       pathHash = this.generateHash(resolvedPath, this.options.hashLength);
     }
 
-    // Ensure the encoded directory exists
-    try {
-      await mkdir(encodedPath, { recursive: true });
-    } catch {
-      // Ignore errors if directory already exists
-    }
-
     return {
       originalPath: resolvedPath,
       encodedName,
@@ -237,6 +230,28 @@ export class PathEncoder {
     };
   }
 
+  /**
+   * Create project directory entity from original path
+   */
+  async createProjectDirectory(
+    originalPath: string,
+    baseSessionDir: string,
+  ): Promise<ProjectDirectory> {
+    const projectDirectory = await this.getProjectDirectory(
+      originalPath,
+      baseSessionDir,
+    );
+
+    // Ensure the encoded directory exists
+    try {
+      await mkdir(projectDirectory.encodedPath, { recursive: true });
+    } catch {
+      // Ignore errors if directory already exists
+    }
+
+    return projectDirectory;
+  }
+
   /**
    * Validate that an encoded name is filesystem-safe
    */

package/src/utils/subagentParser.ts

@@ -9,7 +9,7 @@ export interface SubagentConfiguration {
   model?: string;
   systemPrompt: string;
   filePath: string;
-  scope: "project" | "user";
+  scope: "project" | "user" | "builtin";
   priority: number;
 }
 
@@ -101,11 +101,11 @@ function validateConfiguration(
     throw new Error(`Missing required field 'description' in ${filePath}`);
   }
 
-  // Validate name pattern
-  const namePattern = /^[a-z][a-z0-9-]*$/;
+  // Validate name pattern - allow letters (upper/lowercase), numbers, and hyphens
+  const namePattern = /^[a-zA-Z][a-zA-Z0-9-]*$/;
   if (!namePattern.test(config.name)) {
     throw new Error(
-      `Invalid subagent name '${config.name}' in ${filePath}. Must start with a letter and contain only lowercase letters, numbers, and hyphens.`,
+      `Invalid subagent name '${config.name}' in ${filePath}. Must start with a letter and contain only letters, numbers, and hyphens.`,
     );
   }
 
@@ -187,7 +187,7 @@ function scanSubagentDirectory(
 }
 
 /**
- * Load all subagent configurations from project and user directories
+ * Load all subagent configurations from project and user directories, plus built-in subagents
  */
 export async function loadSubagentConfigurations(
   workdir: string,
@@ -195,14 +195,17 @@ export async function loadSubagentConfigurations(
   const projectDir = join(workdir, ".wave", "agents");
   const userDir = join(process.env.HOME || "~", ".wave", "agents");
 
+  // Load configurations from all sources
+  const { getBuiltinSubagents } = await import("./builtinSubagents.js");
+  const builtinConfigs = getBuiltinSubagents();
   const projectConfigs = scanSubagentDirectory(projectDir, "project");
   const userConfigs = scanSubagentDirectory(userDir, "user");
 
-  // Merge configurations, with project configs taking precedence
+  // Merge configurations, with project configs taking highest precedence
   const configMap = new Map<string, SubagentConfiguration>();
 
-  // Process in reverse priority order (user first, then project)
-  for (const config of [...userConfigs, ...projectConfigs]) {
+  // Process in reverse priority order (built-in first, then user, then project)
+  for (const config of [...builtinConfigs, ...userConfigs, ...projectConfigs]) {
     configMap.set(config.name, config);
   }
 

package/src/utils/tokenEstimator.ts

@@ -0,0 +1,68 @@
+/**
+ * Simple token estimation utility for text content
+ *
+ * This provides a fast approximation of token count without requiring
+ * actual tokenization, which would be expensive for large content.
+ */
+
+/**
+ * Estimate the number of tokens in a text string
+ *
+ * Uses a simple heuristic based on character count and common patterns:
+ * - Average token length varies by language and content type
+ * - English text: ~4-5 characters per token
+ * - Code/structured text: ~3-4 characters per token
+ * - Numbers/symbols: ~2-3 characters per token
+ *
+ * This function uses a conservative estimate of 4 characters per token
+ * which works well for mixed content (text + code + symbols).
+ *
+ * @param text - The text to estimate tokens for
+ * @returns Estimated number of tokens
+ */
+export function estimateTokenCount(text: string): number {
+  if (!text || text.length === 0) {
+    return 0;
+  }
+
+  // Base estimation: 4 characters per token (conservative)
+  const baseEstimate = Math.ceil(text.length / 4);
+
+  // Adjust for whitespace (spaces don't contribute much to token count)
+  const whitespaceCount = (text.match(/\s/g) || []).length;
+  const adjustedEstimate = Math.ceil((text.length - whitespaceCount * 0.5) / 4);
+
+  // Use the more conservative (higher) estimate
+  return Math.max(baseEstimate, adjustedEstimate);
+}
+
+/**
+ * Check if estimated token count exceeds a threshold
+ *
+ * @param text - The text to check
+ * @param threshold - Token threshold (default: 20,000)
+ * @returns True if estimated tokens exceed threshold
+ */
+export function exceedsTokenThreshold(
+  text: string,
+  threshold: number = 20000,
+): boolean {
+  return estimateTokenCount(text) > threshold;
+}
+
+/**
+ * Get a human-readable description of estimated token usage
+ *
+ * @param text - The text to analyze
+ * @param threshold - Token threshold for comparison
+ * @returns Description string with token count and threshold info
+ */
+export function getTokenUsageDescription(
+  text: string,
+  threshold: number = 20000,
+): string {
+  const estimatedTokens = estimateTokenCount(text);
+  const exceedsThreshold = estimatedTokens > threshold;
+
+  return `${estimatedTokens.toLocaleString()} tokens (${exceedsThreshold ? "exceeds" : "within"} ${threshold.toLocaleString()} limit)`;
+}

package/dist/constants/events.d.ts

@@ -1,28 +0,0 @@
-/**
- * Event name constants to prevent typos and ensure consistency
- *
- * Using constants instead of magic strings prevents bugs like:
- * - ConfigurationWatcher emitting 'configurationChange'
- * - LiveConfigManager listening for 'configurationChanged'
- *
- * This pattern ensures compile-time validation of event names.
- */
-export declare const CONFIGURATION_EVENTS: {
-    readonly CONFIGURATION_CHANGE: "configurationChange";
-    readonly WATCHER_ERROR: "watcherError";
-};
-export declare const FILE_WATCHER_EVENTS: {
-    readonly CHANGE: "change";
-    readonly CREATE: "create";
-    readonly DELETE: "delete";
-    readonly RENAME: "rename";
-};
-export declare const MEMORY_STORE_EVENTS: {
-    readonly FILE_ADDED: "fileAdded";
-    readonly FILE_CHANGED: "fileChanged";
-    readonly FILE_REMOVED: "fileRemoved";
-};
-export type ConfigurationEventName = (typeof CONFIGURATION_EVENTS)[keyof typeof CONFIGURATION_EVENTS];
-export type FileWatcherEventName = (typeof FILE_WATCHER_EVENTS)[keyof typeof FILE_WATCHER_EVENTS];
-export type MemoryStoreEventName = (typeof MEMORY_STORE_EVENTS)[keyof typeof MEMORY_STORE_EVENTS];
-//# sourceMappingURL=events.d.ts.map

package/dist/constants/events.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/constants/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,eAAO,MAAM,oBAAoB;;;CAGvB,CAAC;AAGX,eAAO,MAAM,mBAAmB;;;;;CAKtB,CAAC;AAGX,eAAO,MAAM,mBAAmB;;;;CAItB,CAAC;AAGX,MAAM,MAAM,sBAAsB,GAChC,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAC;AACnE,MAAM,MAAM,oBAAoB,GAC9B,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AACjE,MAAM,MAAM,oBAAoB,GAC9B,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/constants/events.js

@@ -1,27 +0,0 @@
-/**
- * Event name constants to prevent typos and ensure consistency
- *
- * Using constants instead of magic strings prevents bugs like:
- * - ConfigurationWatcher emitting 'configurationChange'
- * - LiveConfigManager listening for 'configurationChanged'
- *
- * This pattern ensures compile-time validation of event names.
- */
-// Configuration Watcher Events
-export const CONFIGURATION_EVENTS = {
-    CONFIGURATION_CHANGE: "configurationChange",
-    WATCHER_ERROR: "watcherError",
-};
-// File Watcher Events
-export const FILE_WATCHER_EVENTS = {
-    CHANGE: "change",
-    CREATE: "create",
-    DELETE: "delete",
-    RENAME: "rename",
-};
-// Memory Store Events
-export const MEMORY_STORE_EVENTS = {
-    FILE_ADDED: "fileAdded",
-    FILE_CHANGED: "fileChanged",
-    FILE_REMOVED: "fileRemoved",
-};