wave-agent-sdk 0.0.3 → 0.0.5

package/src/services/aiService.ts

@@ -74,7 +74,7 @@ export interface CallAgentOptions {
   messages: ChatCompletionMessageParam[];
   sessionId?: string;
   abortSignal?: AbortSignal;
-  memory?: string; // Memory content parameter, content read from WAVE.md
+  memory?: string; // Memory content parameter, content read from AGENTS.md
   workdir: string; // Current working directory
   tools?: ChatCompletionFunctionTool[]; // Tool configuration
   model?: string; // Custom model
@@ -214,9 +214,18 @@ export interface CompressMessagesOptions {
   abortSignal?: AbortSignal;
 }
 
+export interface CompressMessagesResult {
+  content: string;
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+}
+
 export async function compressMessages(
   options: CompressMessagesOptions,
-): Promise<string> {
+): Promise<CompressMessagesResult> {
   const { gatewayConfig, modelConfig, messages, abortSignal } = options;
 
   // Create OpenAI client with injected configuration
@@ -294,15 +303,29 @@ For technical conversations, structure as:
       },
     );
 
-    return (
+    const content =
       response.choices[0]?.message?.content?.trim() ||
-      "Failed to compress conversation history"
-    );
+      "Failed to compress conversation history";
+    const usage = response.usage
+      ? {
+          prompt_tokens: response.usage.prompt_tokens,
+          completion_tokens: response.usage.completion_tokens,
+          total_tokens: response.usage.total_tokens,
+        }
+      : undefined;
+
+    return {
+      content,
+      usage,
+    };
   } catch (error) {
     if ((error as Error).name === "AbortError") {
       throw new Error("Compression request was aborted");
     }
     // // logger.error("Failed to compress messages:", error);
-    return "Failed to compress conversation history";
+    return {
+      content: "Failed to compress conversation history",
+      usage: undefined,
+    };
   }
 }

package/src/services/memory.ts

@@ -16,7 +16,7 @@ export const addMemory = async (
   }
 
   try {
-    const memoryFilePath = path.join(workdir, "WAVE.md");
+    const memoryFilePath = path.join(workdir, "AGENTS.md");
 
     // Format memory entry, starting with -, no timestamp
     const memoryEntry = `- ${message.substring(1).trim()}\n`;
@@ -41,7 +41,7 @@ export const addMemory = async (
     // Write file
     await fs.writeFile(memoryFilePath, updatedContent, "utf-8");
 
-    // logger.info(`Memory added to ${memoryFilePath}:`, message);
+    // logger.debug(`Memory added to ${memoryFilePath}:`, message);
   } catch (error) {
     // logger.error("Failed to add memory:", error);
     throw new Error(`Failed to add memory: ${(error as Error).message}`);
@@ -63,7 +63,7 @@ export const ensureUserMemoryFile = async (): Promise<void> => {
         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");
-        // logger.info(`Created user memory file: ${USER_MEMORY_FILE}`);
+        // logger.debug(`Created user memory file: ${USER_MEMORY_FILE}`);
       } else {
         throw error;
       }
@@ -93,7 +93,7 @@ export const addUserMemory = async (message: string): Promise<void> => {
     // Write file
     await fs.writeFile(USER_MEMORY_FILE, updatedContent, "utf-8");
 
-    // logger.info(`User memory added to ${USER_MEMORY_FILE}:`, message);
+    // logger.debug(`User memory added to ${USER_MEMORY_FILE}:`, message);
   } catch (error) {
     // logger.error("Failed to add user memory:", error);
     throw new Error(`Failed to add user memory: ${(error as Error).message}`);
@@ -113,7 +113,7 @@ export const getUserMemoryContent = async (): Promise<string> => {
 // Read project memory file content
 export const readMemoryFile = async (workdir: string): Promise<string> => {
   try {
-    const memoryFilePath = path.join(workdir, "WAVE.md");
+    const memoryFilePath = path.join(workdir, "AGENTS.md");
     return await fs.readFile(memoryFilePath, "utf-8");
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") {

package/src/services/session.ts

@@ -30,12 +30,23 @@ const SESSION_DIR = join(homedir(), ".wave", "sessions");
 const VERSION = "1.0.0";
 const MAX_SESSION_AGE_DAYS = 30;
 
+/**
+ * Resolve session directory path with fallback to default
+ * @param sessionDir Optional custom session directory
+ * @returns Resolved session directory path
+ */
+export function resolveSessionDir(sessionDir?: string): string {
+  return sessionDir || SESSION_DIR;
+}
+
 /**
  * Ensure session directory exists
+ * @param sessionDir Optional custom session directory
  */
-async function ensureSessionDir(): Promise<void> {
+export async function ensureSessionDir(sessionDir?: string): Promise<void> {
+  const resolvedDir = resolveSessionDir(sessionDir);
   try {
-    await fs.mkdir(SESSION_DIR, { recursive: true });
+    await fs.mkdir(resolvedDir, { recursive: true });
   } catch (error) {
     throw new Error(`Failed to create session directory: ${error}`);
   }
@@ -44,9 +55,13 @@ async function ensureSessionDir(): Promise<void> {
 /**
  * Generate session file path
  */
-export function getSessionFilePath(sessionId: string): string {
+export function getSessionFilePath(
+  sessionId: string,
+  sessionDir?: string,
+): string {
   const shortId = sessionId.split("_")[2] || sessionId.slice(-8);
-  return join(SESSION_DIR, `session_${shortId}.json`);
+  const resolvedDir = resolveSessionDir(sessionDir);
+  return join(resolvedDir, `session_${shortId}.json`);
 }
 
 /**
@@ -62,7 +77,15 @@ function filterDiffBlocks(messages: Message[]): Message[] {
 }
 
 /**
- * Save session data
+ * Save session data to storage
+ *
+ * @param sessionId - Unique identifier for the session
+ * @param messages - Array of messages to save
+ * @param workdir - Working directory for the session
+ * @param latestTotalTokens - Total tokens used in the session
+ * @param startedAt - ISO timestamp when session started (defaults to current time)
+ * @param sessionDir - Optional custom directory for session storage (defaults to ~/.wave/sessions/)
+ * @throws {Error} When session cannot be saved due to permission or disk space issues
  */
 export async function saveSession(
   sessionId: string,
@@ -70,6 +93,7 @@ export async function saveSession(
   workdir: string,
   latestTotalTokens: number = 0,
   startedAt?: string,
+  sessionDir?: string,
 ): Promise<void> {
   // Do not save session files in test environment
   if (process.env.NODE_ENV === "test") {
@@ -81,7 +105,7 @@ export async function saveSession(
     return;
   }
 
-  await ensureSessionDir();
+  await ensureSessionDir(sessionDir);
 
   // Filter out diff blocks before saving
   const filteredMessages = filterDiffBlocks(messages);
@@ -100,7 +124,7 @@ export async function saveSession(
     },
   };
 
-  const filePath = getSessionFilePath(sessionId);
+  const filePath = getSessionFilePath(sessionId, sessionDir);
   try {
     await fs.writeFile(filePath, JSON.stringify(sessionData, null, 2), "utf-8");
   } catch (error) {
@@ -109,12 +133,18 @@ export async function saveSession(
 }
 
 /**
- * Load session data
+ * Load session data from storage
+ *
+ * @param sessionId - Unique identifier for the session to load
+ * @param sessionDir - Optional custom directory for session storage (defaults to ~/.wave/sessions/)
+ * @returns Promise that resolves to session data or null if session doesn't exist
+ * @throws {Error} When session exists but cannot be read or contains invalid data
  */
 export async function loadSession(
   sessionId: string,
+  sessionDir?: string,
 ): Promise<SessionData | null> {
-  const filePath = getSessionFilePath(sessionId);
+  const filePath = getSessionFilePath(sessionId, sessionDir);
 
   try {
     const content = await fs.readFile(filePath, "utf-8");
@@ -135,12 +165,18 @@ export async function loadSession(
 }
 
 /**
- * Get most recent session
+ * Get the most recent session for a specific working directory
+ *
+ * @param workdir - Working directory to find the most recent session for
+ * @param sessionDir - Optional custom directory for session storage (defaults to ~/.wave/sessions/)
+ * @returns Promise that resolves to the most recent session data or null if no sessions exist
+ * @throws {Error} When session directory cannot be accessed or session data is corrupted
  */
 export async function getLatestSession(
   workdir: string,
+  sessionDir?: string,
 ): Promise<SessionData | null> {
-  const sessions = await listSessions(workdir);
+  const sessions = await listSessions(workdir, false, sessionDir);
   if (sessions.length === 0) {
     return null;
   }
@@ -151,19 +187,27 @@ export async function getLatestSession(
       new Date(b.lastActiveAt).getTime() - new Date(a.lastActiveAt).getTime(),
   )[0];
 
-  return loadSession(latestSession.id);
+  return loadSession(latestSession.id, sessionDir);
 }
 
 /**
- * List all sessions
+ * List all sessions for a specific working directory or across all working directories
+ *
+ * @param workdir - Working directory to filter sessions by
+ * @param includeAllWorkdirs - If true, returns sessions from all working directories
+ * @param sessionDir - Optional custom directory for session storage (defaults to ~/.wave/sessions/)
+ * @returns Promise that resolves to array of session metadata objects
+ * @throws {Error} When session directory cannot be accessed or read
  */
 export async function listSessions(
   workdir: string,
   includeAllWorkdirs = false,
+  sessionDir?: string,
 ): Promise<SessionMetadata[]> {
   try {
-    await ensureSessionDir();
-    const files = await fs.readdir(SESSION_DIR);
+    await ensureSessionDir(sessionDir);
+    const resolvedDir = resolveSessionDir(sessionDir);
+    const files = await fs.readdir(resolvedDir);
 
     const sessions: SessionMetadata[] = [];
 
@@ -173,7 +217,7 @@ export async function listSessions(
       }
 
       try {
-        const filePath = join(SESSION_DIR, file);
+        const filePath = join(resolvedDir, file);
         const content = await fs.readFile(filePath, "utf-8");
         const sessionData = JSON.parse(content) as SessionData;
 
@@ -206,10 +250,18 @@ export async function listSessions(
 }
 
 /**
- * Delete session
+ * Delete a session from storage
+ *
+ * @param sessionId - Unique identifier for the session to delete
+ * @param sessionDir - Optional custom directory for session storage (defaults to ~/.wave/sessions/)
+ * @returns Promise that resolves to true if session was deleted, false if it didn't exist
+ * @throws {Error} When session exists but cannot be deleted due to permission issues
  */
-export async function deleteSession(sessionId: string): Promise<boolean> {
-  const filePath = getSessionFilePath(sessionId);
+export async function deleteSession(
+  sessionId: string,
+  sessionDir?: string,
+): Promise<boolean> {
+  const filePath = getSessionFilePath(sessionId, sessionDir);
 
   try {
     await fs.unlink(filePath);
@@ -223,15 +275,23 @@ export async function deleteSession(sessionId: string): Promise<boolean> {
 }
 
 /**
- * Clean up expired sessions
+ * Clean up expired sessions older than the configured maximum age
+ *
+ * @param workdir - Working directory to clean up sessions for
+ * @param sessionDir - Optional custom directory for session storage (defaults to ~/.wave/sessions/)
+ * @returns Promise that resolves to the number of sessions that were deleted
+ * @throws {Error} When session directory cannot be accessed or sessions cannot be deleted
  */
-export async function cleanupExpiredSessions(workdir: string): Promise<number> {
+export async function cleanupExpiredSessions(
+  workdir: string,
+  sessionDir?: string,
+): Promise<number> {
   // Do not perform cleanup operations in test environment
   if (process.env.NODE_ENV === "test") {
     return 0;
   }
 
-  const sessions = await listSessions(workdir, true);
+  const sessions = await listSessions(workdir, true, sessionDir);
   const now = new Date();
   const maxAge = MAX_SESSION_AGE_DAYS * 24 * 60 * 60 * 1000; // Convert to milliseconds
 
@@ -242,7 +302,7 @@ export async function cleanupExpiredSessions(workdir: string): Promise<number> {
 
     if (sessionAge > maxAge) {
       try {
-        await deleteSession(session.id);
+        await deleteSession(session.id, sessionDir);
         deletedCount++;
       } catch (error) {
         console.warn(
@@ -256,10 +316,17 @@ export async function cleanupExpiredSessions(workdir: string): Promise<number> {
 }
 
 /**
- * Check if session exists
+ * Check if a session exists in storage
+ *
+ * @param sessionId - Unique identifier for the session to check
+ * @param sessionDir - Optional custom directory for session storage (defaults to ~/.wave/sessions/)
+ * @returns Promise that resolves to true if session exists, false otherwise
  */
-export async function sessionExists(sessionId: string): Promise<boolean> {
-  const filePath = getSessionFilePath(sessionId);
+export async function sessionExists(
+  sessionId: string,
+  sessionDir?: string,
+): Promise<boolean> {
+  const filePath = getSessionFilePath(sessionId, sessionDir);
 
   try {
     await fs.access(filePath);

package/src/tools/bashTool.ts

@@ -44,10 +44,10 @@ export const bashTool: ToolPlugin = {
   ): Promise<ToolResult> => {
     const command = args.command as string;
     const runInBackground = args.run_in_background as boolean | undefined;
-    // Set default timeout: 30s for foreground, no timeout for background
+    // Set default timeout: 60s for foreground, no timeout for background
     const timeout =
       (args.timeout as number | undefined) ??
-      (runInBackground ? undefined : 30000);
+      (runInBackground ? undefined : 60000);
 
     if (!command || typeof command !== "string") {
       return {

package/src/tools/deleteFileTool.ts

@@ -48,7 +48,7 @@ export const deleteFileTool: ToolPlugin = {
       // Delete file
       await unlink(filePath);
 
-      // logger.info(`Successfully deleted file: ${filePath}`);
+      // logger.debug(`Successfully deleted file: ${filePath}`);
 
       return {
         success: true,

package/src/tools/editTool.ts

@@ -160,7 +160,7 @@ export const editTool: ToolPlugin = {
         ? `Replaced ${replacementCount} instances`
         : "Text replaced successfully";
 
-      // logger.info(`Edit tool: ${shortResult}`);
+      // logger.debug(`Edit tool: ${shortResult}`);
 
       return {
         success: true,

package/src/tools/multiEditTool.ts

@@ -149,7 +149,7 @@ export const multiEditTool: ToolPlugin = {
         if (edits[0] && edits[0].old_string === "") {
           originalContent = "";
           isNewFile = true;
-          // logger.info(`Creating new file: ${resolvedPath}`);
+          // logger.debug(`Creating new file: ${resolvedPath}`);
         } else {
           return {
             success: false,
@@ -236,7 +236,7 @@ export const multiEditTool: ToolPlugin = {
 
       const detailedContent = `${shortResult}\n\nOperations performed:\n${appliedEdits.map((edit, i) => `${i + 1}. ${edit}`).join("\n")}`;
 
-      // logger.info(`MultiEdit tool: ${shortResult}`);
+      // logger.debug(`MultiEdit tool: ${shortResult}`);
 
       return {
         success: true,

package/src/tools/writeTool.ts

@@ -121,7 +121,7 @@ export const writeTool: ToolPlugin = {
       const chars = content.length;
       const detailedContent = `${shortResult} (${lines} lines, ${chars} characters)`;
 
-      // logger.info(`Write tool: ${shortResult}`);
+      // logger.debug(`Write tool: ${shortResult}`);
 
       return {
         success: true,

package/src/types.ts

@@ -14,6 +14,7 @@ export interface Logger {
 export interface Message {
   role: "user" | "assistant";
   blocks: MessageBlock[];
+  usage?: Usage; // Usage data for this message's AI operation (assistant messages only)
 }
 
 export type MessageBlock =
@@ -332,6 +333,18 @@ export class ConfigurationError extends Error {
   }
 }
 
+/**
+ * Usage statistics for AI operations
+ * Extends OpenAI's Usage format with additional tracking fields
+ */
+export interface Usage {
+  prompt_tokens: number; // Tokens used in prompts
+  completion_tokens: number; // Tokens generated in completions
+  total_tokens: number; // Sum of prompt + completion tokens
+  model?: string; // Model used for the operation (e.g., "gpt-4", "gpt-3.5-turbo")
+  operation_type?: "agent" | "compress"; // Type of operation that generated usage
+}
+
 // Standard error messages
 export const CONFIG_ERRORS = {
   MISSING_API_KEY:

package/src/utils/messageOperations.ts

@@ -1,4 +1,4 @@
-import type { Message } from "../types.js";
+import type { Message, Usage } from "../types.js";
 import { readFileSync } from "fs";
 import { extname } from "path";
 import { ChatCompletionMessageFunctionToolCall } from "openai/resources.js";
@@ -177,6 +177,7 @@ export const addAssistantMessageToMessages = (
   messages: Message[],
   content?: string,
   toolCalls?: ChatCompletionMessageFunctionToolCall[],
+  usage?: Usage,
 ): Message[] => {
   const blocks: Message["blocks"] = [];
 
@@ -202,6 +203,7 @@ export const addAssistantMessageToMessages = (
   const initialAssistantMessage: Message = {
     role: "assistant",
     blocks,
+    usage, // Include usage data if provided
   };
 
   return [...messages, initialAssistantMessage];