wave-agent-sdk 0.0.4 → 0.0.6

package/src/services/session.ts

@@ -1,7 +1,7 @@
 import { promises as fs } from "fs";
 import { join } from "path";
 import { homedir } from "os";
-import type { Message } from "../types.js";
+import type { Message } from "../types/index.js";
 
 export interface SessionData {
   id: string;
@@ -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;
 
@@ -191,8 +235,8 @@ export async function listSessions(
           latestTotalTokens: sessionData.metadata.latestTotalTokens,
         });
       } catch {
-        // Ignore corrupted session files
-        console.warn(`Skipping corrupted session file: ${file}`);
+        // Skip corrupted session files and continue processing others
+        continue;
       }
     }
 
@@ -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,12 +302,11 @@ 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(
-          `Failed to delete expired session ${session.id}: ${error}`,
-        );
+      } catch {
+        // Skip failed deletions and continue processing other sessions
+        continue;
       }
     }
   }
@@ -256,10 +315,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/taskTool.ts

@@ -1,4 +1,4 @@
-import type { ToolPlugin, ToolResult } from "./types.js";
+import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
 import type { SubagentManager } from "../managers/subagentManager.js";
 
 /**
@@ -47,7 +47,10 @@ ${subagentList || "No subagents configured"}`;
       },
     },
 
-    execute: async (args: Record<string, unknown>): Promise<ToolResult> => {
+    execute: async (
+      args: Record<string, unknown>,
+      context: ToolContext,
+    ): Promise<ToolResult> => {
       // Input validation
       const description = args.description as string;
       const prompt = args.prompt as string;
@@ -98,11 +101,16 @@ ${subagentList || "No subagents configured"}`;
         }
 
         // Create subagent instance and execute task
-        const instance = await subagentManager.createInstance(
-          configuration,
+        const instance = await subagentManager.createInstance(configuration, {
           description,
+          prompt,
+          subagent_type,
+        });
+        const response = await subagentManager.executeTask(
+          instance,
+          prompt,
+          context.abortSignal,
         );
-        const response = await subagentManager.executeTask(instance, prompt);
 
         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/commands.ts

@@ -0,0 +1,26 @@
+/**
+ * Slash command and custom command types
+ * Dependencies: None
+ */
+
+export interface SlashCommand {
+  id: string;
+  name: string;
+  description: string;
+  handler: (args?: string) => Promise<void> | void;
+}
+
+export interface CustomSlashCommandConfig {
+  allowedTools?: string[];
+  model?: string;
+  description?: string;
+}
+
+export interface CustomSlashCommand {
+  id: string;
+  name: string;
+  description?: string; // Add description field
+  filePath: string;
+  content: string;
+  config?: CustomSlashCommandConfig;
+}

package/src/types/config.ts

@@ -0,0 +1,14 @@
+/**
+ * Agent and service configuration types
+ * Dependencies: None
+ */
+
+export interface GatewayConfig {
+  apiKey: string;
+  baseURL: string;
+}
+
+export interface ModelConfig {
+  agentModel: string;
+  fastModel: string;
+}

package/src/types/core.ts

@@ -0,0 +1,49 @@
+/**
+ * Core foundational types used across multiple domains
+ * Dependencies: None (foundation layer)
+ */
+
+/**
+ * Logger interface definition
+ * Compatible with OpenAI package Logger interface
+ */
+export interface Logger {
+  error: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  debug: (...args: unknown[]) => void;
+}
+
+/**
+ * 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
+}
+
+export class ConfigurationError extends Error {
+  constructor(
+    message: string,
+    public readonly field: string,
+    public readonly provided?: unknown,
+  ) {
+    super(message);
+    this.name = "ConfigurationError";
+  }
+}
+
+// Standard error messages
+export const CONFIG_ERRORS = {
+  MISSING_API_KEY:
+    "Gateway configuration requires apiKey. Provide via constructor or AIGW_TOKEN environment variable.",
+  MISSING_BASE_URL:
+    "Gateway configuration requires baseURL. Provide via constructor or AIGW_URL environment variable.",
+  INVALID_TOKEN_LIMIT: "Token limit must be a positive integer.",
+  EMPTY_API_KEY: "API key cannot be empty string.",
+  EMPTY_BASE_URL: "Base URL cannot be empty string.",
+} as const;

package/src/{hooks/types.ts → types/hooks.ts}

@@ -68,6 +68,7 @@ export interface HookExecutionResult {
 export interface HookExecutionOptions {
   timeout?: number; // milliseconds, default 10000
   cwd?: string; // working directory, defaults to projectDir
+  continueOnFailure?: boolean; // continue executing remaining hooks on failure
 }
 
 // Validation result for hook configuration

package/src/types/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Main type index - Barrel export for backward compatibility
+ * Re-exports all domain types for legacy imports
+ *
+ * Legacy import pattern (continues to work):
+ *   import { Message, Logger, McpTool } from 'wave-agent-sdk/types';
+ *
+ * New domain-specific import pattern:
+ *   import { Message } from 'wave-agent-sdk/types/messaging';
+ *   import { Logger } from 'wave-agent-sdk/types/core';
+ *   import { McpTool } from 'wave-agent-sdk/types/mcp';
+ */
+
+// Core foundational types
+export * from "./core.js";
+
+// Domain-specific types
+export * from "./messaging.js";
+export * from "./mcp.js";
+export * from "./processes.js";
+export * from "./commands.js";
+export * from "./skills.js";
+export * from "./config.js";

package/src/{types.ts → types/index.ts.backup}

@@ -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/types/mcp.ts

@@ -0,0 +1,31 @@
+/**
+ * Model Context Protocol types
+ * Dependencies: None
+ */
+
+export interface McpServerConfig {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+export interface McpConfig {
+  mcpServers: Record<string, McpServerConfig>;
+}
+
+export interface McpTool {
+  name: string;
+  description?: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export interface McpServerStatus {
+  name: string;
+  config: McpServerConfig;
+  status: "disconnected" | "connected" | "connecting" | "error";
+  tools?: McpTool[];
+  toolCount?: number;
+  capabilities?: string[];
+  lastConnected?: number;
+  error?: string;
+}

package/src/types/messaging.ts

@@ -0,0 +1,103 @@
+/**
+ * Message and communication block types
+ * Dependencies: Core (Usage)
+ */
+
+import type { Usage } from "./core.js";
+
+export interface Message {
+  role: "user" | "assistant";
+  blocks: MessageBlock[];
+  usage?: Usage; // Usage data for this message's AI operation (assistant messages only)
+}
+
+export type MessageBlock =
+  | TextBlock
+  | ErrorBlock
+  | ToolBlock
+  | ImageBlock
+  | DiffBlock
+  | CommandOutputBlock
+  | CompressBlock
+  | MemoryBlock
+  | CustomCommandBlock
+  | SubagentBlock;
+
+export interface TextBlock {
+  type: "text";
+  content: string;
+}
+
+export interface ErrorBlock {
+  type: "error";
+  content: string;
+}
+
+export interface ToolBlock {
+  type: "tool";
+  parameters?: string;
+  result?: string;
+  shortResult?: string; // Add shortResult field
+  images?: Array<{
+    // Add image data support
+    data: string; // Base64 encoded image data
+    mediaType?: string; // Media type of the image
+  }>;
+  id?: string;
+  name?: string;
+  isRunning?: boolean; // Mark if tool is actually executing
+  success?: boolean;
+  error?: string | Error;
+  compactParams?: string; // Compact parameter display
+}
+
+export interface ImageBlock {
+  type: "image";
+  imageUrls?: string[];
+}
+
+export interface DiffBlock {
+  type: "diff";
+  path: string;
+  diffResult: Array<{
+    value: string;
+    added?: boolean;
+    removed?: boolean;
+  }>;
+}
+
+export interface CommandOutputBlock {
+  type: "command_output";
+  command: string;
+  output: string;
+  isRunning: boolean;
+  exitCode: number | null;
+}
+
+export interface CompressBlock {
+  type: "compress";
+  content: string;
+}
+
+export interface MemoryBlock {
+  type: "memory";
+  content: string;
+  isSuccess: boolean;
+  memoryType?: "project" | "user"; // Memory type
+  storagePath?: string; // Storage path text
+}
+
+export interface CustomCommandBlock {
+  type: "custom_command";
+  commandName: string;
+  content: string; // Complete command content, used when passing to AI
+  originalInput?: string; // Original user input, used for UI display (e.g., "/fix-issue 123 high")
+}
+
+export interface SubagentBlock {
+  type: "subagent";
+  subagentId: string;
+  subagentName: string;
+  status: "active" | "completed" | "error" | "aborted";
+  messages: Message[];
+}

package/src/types/processes.ts

@@ -0,0 +1,18 @@
+/**
+ * Background process and shell management types
+ * Dependencies: None
+ */
+
+import type { ChildProcess } from "child_process";
+
+export interface BackgroundShell {
+  id: string;
+  process: ChildProcess;
+  command: string;
+  startTime: number;
+  status: "running" | "completed" | "killed";
+  stdout: string;
+  stderr: string;
+  exitCode?: number;
+  runtime?: number;
+}