wave-agent-sdk 0.0.6 → 0.0.8

package/src/services/session.ts

@@ -1,12 +1,15 @@
 import { promises as fs } from "fs";
 import { join } from "path";
 import { homedir } from "os";
+import { v6 as uuidv6 } from "uuid";
 import type { Message } from "../types/index.js";
+import type { SessionMessage } from "../types/session.js";
+import { PathEncoder } from "../utils/pathEncoder.js";
+import { JsonlHandler } from "../services/jsonlHandler.js";
+import { extractLatestTotalTokens } from "../utils/tokenCalculation.js";
 
 export interface SessionData {
   id: string;
-  timestamp: string;
-  version: string;
   messages: Message[];
   metadata: {
     workdir: string;
@@ -18,82 +21,95 @@ export interface SessionData {
 
 export interface SessionMetadata {
   id: string;
-  timestamp: string;
+  sessionType: "main" | "subagent";
+  parentSessionId?: string;
+  subagentType?: string;
   workdir: string;
-  startedAt: string;
-  lastActiveAt: string;
+  startedAt: Date;
+  lastActiveAt: Date;
   latestTotalTokens: number;
 }
 
-// Constants
-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
+ * Generate a new UUIDv6-based session ID
+ * @returns UUIDv6 string for time-ordered sessions
  */
-export function resolveSessionDir(sessionDir?: string): string {
-  return sessionDir || SESSION_DIR;
+export function generateSessionId(): string {
+  return uuidv6();
 }
 
+// Constants
+export const SESSION_DIR = join(homedir(), ".wave", "projects");
+const MAX_SESSION_AGE_DAYS = 14;
+
 /**
  * Ensure session directory exists
- * @param sessionDir Optional custom session directory
  */
-export async function ensureSessionDir(sessionDir?: string): Promise<void> {
-  const resolvedDir = resolveSessionDir(sessionDir);
+export async function ensureSessionDir(): Promise<void> {
   try {
-    await fs.mkdir(resolvedDir, { recursive: true });
+    await fs.mkdir(SESSION_DIR, { recursive: true });
   } catch (error) {
     throw new Error(`Failed to create session directory: ${error}`);
   }
 }
 
 /**
- * Generate session file path
+ * Generate session file path using project-based directory structure
+ * Note: With metadata-based approach, we no longer need separate subagent directories
+ * @param sessionId - UUIDv6 session identifier
+ * @param workdir - Working directory for the session
+ * @returns Promise resolving to full file path for the session JSONL file
  */
-export function getSessionFilePath(
+export async function getSessionFilePath(
   sessionId: string,
-  sessionDir?: string,
-): string {
-  const shortId = sessionId.split("_")[2] || sessionId.slice(-8);
-  const resolvedDir = resolveSessionDir(sessionDir);
-  return join(resolvedDir, `session_${shortId}.json`);
+  workdir: string,
+): Promise<string> {
+  const encoder = new PathEncoder();
+  const projectDir = await encoder.createProjectDirectory(workdir, SESSION_DIR);
+
+  // All sessions (main and subagent) now go in the same directory
+  // Session type is determined by metadata, not file path
+  return join(projectDir.encodedPath, `${sessionId}.jsonl`);
 }
 
 /**
- * Filter out diff blocks from messages to avoid saving unimportant data
+ * Create a new session with metadata
+ * @param sessionId - UUIDv6 session identifier
+ * @param workdir - Working directory for the session
+ * @param sessionType - Type of session ('main' or 'subagent')
+ * @param parentSessionId - Parent session ID for subagent sessions
+ * @param subagentType - Type of subagent for subagent sessions
  */
-function filterDiffBlocks(messages: Message[]): Message[] {
-  return messages
-    .map((message) => ({
-      ...message,
-      blocks: message.blocks.filter((block) => block.type !== "diff"),
-    }))
-    .filter((message) => message.blocks.length > 0);
+export async function createSession(
+  sessionId: string,
+  workdir: string,
+  sessionType: "main" | "subagent" = "main",
+  parentSessionId?: string,
+  subagentType?: string,
+): Promise<void> {
+  const jsonlHandler = new JsonlHandler();
+  const filePath = await getSessionFilePath(sessionId, workdir);
+  await jsonlHandler.createSession(
+    filePath,
+    sessionId,
+    workdir,
+    sessionType,
+    parentSessionId,
+    subagentType,
+  );
 }
 
 /**
- * Save session data to storage
+ * Append messages to session using JSONL format (new approach)
  *
- * @param sessionId - Unique identifier for the session
- * @param messages - Array of messages to save
+ * @param sessionId - UUIDv6 session identifier
+ * @param newMessages - Array of messages to append
  * @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(
+export async function appendMessages(
   sessionId: string,
-  messages: Message[],
+  newMessages: Message[],
   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") {
@@ -101,170 +117,319 @@ export async function saveSession(
   }
 
   // Do not save if there are no messages
-  if (messages.length === 0) {
+  if (newMessages.length === 0) {
     return;
   }
 
-  await ensureSessionDir(sessionDir);
-
-  // Filter out diff blocks before saving
-  const filteredMessages = filterDiffBlocks(messages);
-
-  const now = new Date().toISOString();
-  const sessionData: SessionData = {
-    id: sessionId,
-    timestamp: now,
-    version: VERSION,
-    messages: filteredMessages,
-    metadata: {
-      workdir: workdir,
-      startedAt: startedAt || now,
-      lastActiveAt: now,
-      latestTotalTokens,
-    },
-  };
+  const jsonlHandler = new JsonlHandler();
+  const filePath = await getSessionFilePath(sessionId, workdir);
 
-  const filePath = getSessionFilePath(sessionId, sessionDir);
+  // Check if session file exists, throw error if it doesn't
   try {
-    await fs.writeFile(filePath, JSON.stringify(sessionData, null, 2), "utf-8");
+    await fs.access(filePath);
   } catch (error) {
-    throw new Error(`Failed to save session ${sessionId}: ${error}`);
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      // File doesn't exist, throw error - sessions must be created explicitly
+      throw new Error(
+        `Session file not found: ${sessionId}. Use createSession() to create a new session first.`,
+      );
+    } else {
+      // Some other error accessing the file, re-throw it
+      throw error;
+    }
   }
+
+  const messagesWithTimestamp: SessionMessage[] = newMessages.map((msg) => ({
+    timestamp: new Date().toISOString(),
+    ...msg,
+  }));
+
+  await jsonlHandler.append(filePath, messagesWithTimestamp, { atomic: false });
 }
 
 /**
- * Load session data from storage
+ * Load session data from JSONL file (new approach)
  *
- * @param sessionId - Unique identifier for the session to load
- * @param sessionDir - Optional custom directory for session storage (defaults to ~/.wave/sessions/)
+ * @param sessionId - UUIDv6 session identifier
+ * @param workdir - Working directory for the session
  * @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(
+export async function loadSessionFromJsonl(
   sessionId: string,
-  sessionDir?: string,
+  workdir: string,
 ): Promise<SessionData | null> {
-  const filePath = getSessionFilePath(sessionId, sessionDir);
-
   try {
-    const content = await fs.readFile(filePath, "utf-8");
-    const sessionData = JSON.parse(content) as SessionData;
+    const jsonlHandler = new JsonlHandler();
+    const filePath = await getSessionFilePath(sessionId, workdir);
 
-    // Validate session data format
-    if (!sessionData.id || !sessionData.messages || !sessionData.metadata) {
-      throw new Error("Invalid session data format");
+    const messages = await jsonlHandler.read(filePath);
+
+    if (messages.length === 0) {
+      return null;
     }
 
+    // Extract metadata from messages
+    const firstMessage = messages[0];
+    const lastMessage = messages[messages.length - 1];
+
+    const sessionData: SessionData = {
+      id: sessionId,
+      messages: messages.map((msg) => {
+        // Remove timestamp property for backward compatibility
+        const { timestamp: _ignored, ...messageWithoutTimestamp } = msg;
+        void _ignored; // Use the variable to avoid eslint error
+        return messageWithoutTimestamp;
+      }),
+      metadata: {
+        workdir,
+        startedAt: firstMessage.timestamp,
+        lastActiveAt: lastMessage.timestamp,
+        latestTotalTokens: lastMessage.usage
+          ? extractLatestTotalTokens([lastMessage])
+          : 0,
+      },
+    };
+
     return sessionData;
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+
+    // Check if the underlying error is ENOENT (file doesn't exist)
+    if (
+      errorMessage.includes("ENOENT") ||
+      (error as NodeJS.ErrnoException).code === "ENOENT"
+    ) {
       return null; // Session file does not exist
     }
+
+    // Check for JSON parsing errors (corrupted files)
+    if (
+      errorMessage.includes("Invalid JSON") ||
+      errorMessage.includes("Unexpected token")
+    ) {
+      return null; // Treat corrupted files as non-existent
+    }
+
     throw new Error(`Failed to load session ${sessionId}: ${error}`);
   }
 }
 
 /**
- * Get the most recent session for a specific working directory
+ * Get the most recently active session for a specific working directory (new JSONL approach)
+ * Only returns main sessions, skips subagent sessions
+ * Sessions are sorted by last active time (most recently active first)
  *
- * @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
+ * @param workdir - Working directory to find the most recently active session for
+ * @returns Promise that resolves to the most recently active session data or null if no sessions exist
  */
-export async function getLatestSession(
+export async function getLatestSessionFromJsonl(
   workdir: string,
-  sessionDir?: string,
 ): Promise<SessionData | null> {
-  const sessions = await listSessions(workdir, false, sessionDir);
+  const sessions = await listSessionsFromJsonl(workdir, false); // Uses default includeSubagentSessions = false
+
   if (sessions.length === 0) {
     return null;
   }
 
-  // Sort by last active time, return the latest
+  // Sort by last active time (most recently active first)
   const latestSession = sessions.sort(
-    (a, b) =>
-      new Date(b.lastActiveAt).getTime() - new Date(a.lastActiveAt).getTime(),
+    (a, b) => b.lastActiveAt.getTime() - a.lastActiveAt.getTime(),
   )[0];
+  return loadSessionFromJsonl(latestSession.id, workdir);
+}
 
-  return loadSession(latestSession.id, sessionDir);
+/**
+ * List all sessions for a specific working directory (convenience wrapper)
+ * Only returns main sessions, skips subagent sessions
+ *
+ * @param workdir - Working directory to filter sessions by
+ * @returns Promise that resolves to array of session metadata objects
+ */
+export async function listSessions(
+  workdir: string,
+): Promise<SessionMetadata[]> {
+  return listSessionsFromJsonl(workdir, false); // Uses default includeSubagentSessions = false
 }
 
 /**
- * List all sessions for a specific working directory or across all working directories
+ * List all sessions for a specific working directory using JSONL format (new approach)
  *
  * @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/)
+ * @param includeSubagentSessions - If true, includes subagent sessions (default: false for user-facing operations)
  * @returns Promise that resolves to array of session metadata objects
- * @throws {Error} When session directory cannot be accessed or read
  */
-export async function listSessions(
+export async function listSessionsFromJsonl(
   workdir: string,
   includeAllWorkdirs = false,
-  sessionDir?: string,
+  includeSubagentSessions = false,
 ): Promise<SessionMetadata[]> {
   try {
-    await ensureSessionDir(sessionDir);
-    const resolvedDir = resolveSessionDir(sessionDir);
-    const files = await fs.readdir(resolvedDir);
+    const encoder = new PathEncoder();
+    const baseDir = SESSION_DIR;
 
-    const sessions: SessionMetadata[] = [];
+    // If not including all workdirs, just scan the specific project directory
+    if (!includeAllWorkdirs) {
+      const projectDir = await encoder.createProjectDirectory(workdir, baseDir);
+      const files = await fs.readdir(projectDir.encodedPath);
 
-    for (const file of files) {
-      if (!file.startsWith("session_") || !file.endsWith(".json")) {
-        continue;
+      const sessions: SessionMetadata[] = [];
+
+      for (const file of files) {
+        if (!file.endsWith(".jsonl")) {
+          continue;
+        }
+
+        const sessionId = file.replace(".jsonl", "");
+        try {
+          const jsonlHandler = new JsonlHandler();
+          const filePath = join(projectDir.encodedPath, file);
+
+          // Read metadata (efficient O(1) operation)
+          const metadata = await jsonlHandler.readMetadata(filePath);
+          if (metadata) {
+            // For lastActiveAt and latestTotalTokens, we need the last message
+            const lastMessage = await jsonlHandler.getLastMessage(filePath);
+
+            sessions.push({
+              id: sessionId,
+              sessionType: metadata.sessionType,
+              parentSessionId: metadata.parentSessionId,
+              subagentType: metadata.subagentType,
+              workdir: metadata.workdir,
+              startedAt: new Date(metadata.startedAt),
+              lastActiveAt: lastMessage
+                ? new Date(lastMessage.timestamp)
+                : new Date(metadata.startedAt),
+              latestTotalTokens: lastMessage?.usage
+                ? extractLatestTotalTokens([lastMessage])
+                : 0,
+            });
+          }
+        } catch {
+          // Skip corrupted session files
+          continue;
+        }
       }
 
-      try {
-        const filePath = join(resolvedDir, file);
-        const content = await fs.readFile(filePath, "utf-8");
-        const sessionData = JSON.parse(content) as SessionData;
+      // Sort by last active time (most recently active first)
+      const sortedSessions = sessions.sort(
+        (a, b) => b.lastActiveAt.getTime() - a.lastActiveAt.getTime(),
+      );
 
-        // Only return sessions for the current working directory, unless includeAllWorkdirs is true
-        if (!includeAllWorkdirs && sessionData.metadata.workdir !== workdir) {
+      // Filter out subagent sessions if requested
+      if (!includeSubagentSessions) {
+        return sortedSessions.filter(
+          (session) => session.sessionType === "main",
+        );
+      }
+
+      return sortedSessions;
+    }
+
+    // For all workdirs, scan all project directories
+    const sessions: SessionMetadata[] = [];
+    try {
+      const projectDirs = await fs.readdir(baseDir);
+
+      for (const projectDirName of projectDirs) {
+        const projectPath = join(baseDir, projectDirName);
+        const stat = await fs.stat(projectPath);
+
+        if (!stat.isDirectory()) {
           continue;
         }
 
-        sessions.push({
-          id: sessionData.id,
-          timestamp: sessionData.timestamp,
-          workdir: sessionData.metadata.workdir,
-          startedAt: sessionData.metadata.startedAt,
-          lastActiveAt: sessionData.metadata.lastActiveAt,
-          latestTotalTokens: sessionData.metadata.latestTotalTokens,
-        });
-      } catch {
-        // Skip corrupted session files and continue processing others
-        continue;
+        const files = await fs.readdir(projectPath);
+
+        for (const file of files) {
+          if (!file.endsWith(".jsonl")) {
+            continue;
+          }
+
+          const sessionId = file.replace(".jsonl", "");
+          try {
+            const jsonlHandler = new JsonlHandler();
+            const filePath = join(projectPath, file);
+
+            // Read metadata (efficient O(1) operation)
+            const metadata = await jsonlHandler.readMetadata(filePath);
+            if (metadata) {
+              // For lastActiveAt and latestTotalTokens, we need the last message
+              const lastMessage = await jsonlHandler.getLastMessage(filePath);
+
+              sessions.push({
+                id: sessionId,
+                sessionType: metadata.sessionType,
+                parentSessionId: metadata.parentSessionId,
+                subagentType: metadata.subagentType,
+                workdir: metadata.workdir,
+                startedAt: new Date(metadata.startedAt),
+                lastActiveAt: lastMessage
+                  ? new Date(lastMessage.timestamp)
+                  : new Date(metadata.startedAt),
+                latestTotalTokens: lastMessage?.usage
+                  ? extractLatestTotalTokens([lastMessage])
+                  : 0,
+              });
+            }
+          } catch {
+            // Skip corrupted session files
+            continue;
+          }
+        }
       }
+    } catch {
+      // If base directory doesn't exist, return empty array
+      return [];
     }
 
-    return sessions.sort(
-      (a, b) =>
-        new Date(b.lastActiveAt).getTime() - new Date(a.lastActiveAt).getTime(),
+    // Sort by last active time (most recently active first)
+    const sortedSessions = sessions.sort(
+      (a, b) => b.lastActiveAt.getTime() - a.lastActiveAt.getTime(),
     );
+
+    // Filter out subagent sessions if requested
+    if (!includeSubagentSessions) {
+      return sortedSessions.filter((session) => session.sessionType === "main");
+    }
+
+    return sortedSessions;
   } catch (error) {
     throw new Error(`Failed to list sessions: ${error}`);
   }
 }
 
 /**
- * Delete a session from storage
+ * Delete a session from JSONL storage (new approach)
  *
- * @param sessionId - Unique identifier for the session to delete
- * @param sessionDir - Optional custom directory for session storage (defaults to ~/.wave/sessions/)
+ * @param sessionId - UUIDv6 session identifier
+ * @param workdir - Working directory for the session
  * @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(
+export async function deleteSessionFromJsonl(
   sessionId: string,
-  sessionDir?: string,
+  workdir: string,
 ): Promise<boolean> {
-  const filePath = getSessionFilePath(sessionId, sessionDir);
-
   try {
+    const filePath = await getSessionFilePath(sessionId, workdir);
     await fs.unlink(filePath);
+
+    // Try to clean up empty project directory
+    const encoder = new PathEncoder();
+    const projectDir = await encoder.createProjectDirectory(
+      workdir,
+      SESSION_DIR,
+    );
+    try {
+      const files = await fs.readdir(projectDir.encodedPath);
+      if (files.length === 0) {
+        await fs.rmdir(projectDir.encodedPath);
+      }
+    } catch {
+      // Ignore errors if directory is not empty or can't be removed
+    }
+
     return true;
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") {
@@ -275,59 +440,118 @@ export async function deleteSession(
 }
 
 /**
- * Clean up expired sessions older than the configured maximum age
+ * Clean up expired sessions older than 14 days based on file modification time
  *
  * @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(
+export async function cleanupExpiredSessionsFromJsonl(
   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, sessionDir);
-  const now = new Date();
-  const maxAge = MAX_SESSION_AGE_DAYS * 24 * 60 * 60 * 1000; // Convert to milliseconds
+  try {
+    const encoder = new PathEncoder();
+    const projectDir = await encoder.createProjectDirectory(
+      workdir,
+      SESSION_DIR,
+    );
+    const files = await fs.readdir(projectDir.encodedPath);
+
+    const now = new Date();
+    const maxAge = MAX_SESSION_AGE_DAYS * 24 * 60 * 60 * 1000; // Convert to milliseconds
+    let deletedCount = 0;
 
-  let deletedCount = 0;
+    for (const file of files) {
+      if (!file.endsWith(".jsonl")) {
+        continue;
+      }
 
-  for (const session of sessions) {
-    const sessionAge = now.getTime() - new Date(session.lastActiveAt).getTime();
+      const filePath = join(projectDir.encodedPath, file);
 
-    if (sessionAge > maxAge) {
       try {
-        await deleteSession(session.id, sessionDir);
-        deletedCount++;
+        const stat = await fs.stat(filePath);
+        const fileAge = now.getTime() - stat.mtime.getTime();
+
+        if (fileAge > maxAge) {
+          await fs.unlink(filePath);
+          deletedCount++;
+        }
       } catch {
-        // Skip failed deletions and continue processing other sessions
+        // Skip failed operations and continue processing other files
         continue;
       }
     }
+
+    // Clean up empty project directory if no files remain
+    try {
+      const remainingFiles = await fs.readdir(projectDir.encodedPath);
+      if (remainingFiles.length === 0) {
+        await fs.rmdir(projectDir.encodedPath);
+      }
+    } catch {
+      // Ignore errors if directory is not empty or can't be removed
+    }
+
+    return deletedCount;
+  } catch {
+    // Return 0 if project directory doesn't exist or can't be accessed
+    return 0;
   }
+}
 
-  return deletedCount;
+/**
+ * Clean up empty project directories in the session directory
+ */
+export async function cleanupEmptyProjectDirectories(): Promise<void> {
+  // Do not perform cleanup operations in test environment
+  if (process.env.NODE_ENV === "test") {
+    return;
+  }
+
+  try {
+    const baseDir = SESSION_DIR;
+    const projectDirs = await fs.readdir(baseDir);
+
+    for (const projectDirName of projectDirs) {
+      const projectPath = join(baseDir, projectDirName);
+      const stat = await fs.stat(projectPath);
+
+      if (stat.isDirectory()) {
+        try {
+          const files = await fs.readdir(projectPath);
+
+          // If directory is empty, remove it
+          if (files.length === 0) {
+            await fs.rmdir(projectPath);
+          }
+        } catch {
+          // Skip errors for directories we can't read or remove
+          continue;
+        }
+      }
+    }
+  } catch {
+    // Ignore errors if base directory doesn't exist or can't be accessed
+  }
 }
 
 /**
- * Check if a session exists in storage
+ * Check if a session exists in JSONL storage (new approach)
  *
- * @param sessionId - Unique identifier for the session to check
- * @param sessionDir - Optional custom directory for session storage (defaults to ~/.wave/sessions/)
+ * @param sessionId - UUIDv6 session identifier
+ * @param workdir - Working directory for the session
  * @returns Promise that resolves to true if session exists, false otherwise
  */
-export async function sessionExists(
+export async function sessionExistsInJsonl(
   sessionId: string,
-  sessionDir?: string,
+  workdir: string,
 ): Promise<boolean> {
-  const filePath = getSessionFilePath(sessionId, sessionDir);
-
   try {
+    const filePath = await getSessionFilePath(sessionId, workdir);
     await fs.access(filePath);
     return true;
   } catch {