wave-agent-sdk 0.0.5 → 0.0.6

package/src/services/hook.ts

@@ -0,0 +1,360 @@
+/**
+ * Hook Services
+ *
+ * Consolidated hook services providing both execution and configuration functionality.
+ * Combines hook command execution and settings management into a single module.
+ */
+
+import { spawn, type ChildProcess } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import {
+  type HookExecutionContext,
+  type HookExecutionResult,
+  type HookExecutionOptions,
+  type ExtendedHookExecutionContext,
+  type HookJsonInput,
+  type HookConfiguration,
+  type PartialHookConfiguration,
+  getSessionFilePath,
+  isValidHookEvent,
+} from "../types/hooks.js";
+
+// =============================================================================
+// Hook Execution Functions
+// =============================================================================
+
+/**
+ * Build JSON input data for hook stdin
+ */
+function buildHookJsonInput(
+  context: ExtendedHookExecutionContext,
+): HookJsonInput {
+  const jsonInput: HookJsonInput = {
+    session_id: context.sessionId || "unknown",
+    transcript_path:
+      context.transcriptPath ||
+      (context.sessionId ? getSessionFilePath(context.sessionId) : ""),
+    cwd: context.cwd || context.projectDir,
+    hook_event_name: context.event,
+  };
+
+  // Add optional fields based on event type
+  if (context.event === "PreToolUse" || context.event === "PostToolUse") {
+    if (context.toolName) {
+      jsonInput.tool_name = context.toolName;
+    }
+    if (context.toolInput !== undefined) {
+      jsonInput.tool_input = context.toolInput;
+    }
+  }
+
+  if (context.event === "PostToolUse" && context.toolResponse !== undefined) {
+    jsonInput.tool_response = context.toolResponse;
+  }
+
+  if (
+    context.event === "UserPromptSubmit" &&
+    context.userPrompt !== undefined
+  ) {
+    jsonInput.user_prompt = context.userPrompt;
+  }
+
+  return jsonInput;
+}
+
+/**
+ * Execute a single hook command
+ */
+export async function executeCommand(
+  command: string,
+  context: HookExecutionContext | ExtendedHookExecutionContext,
+  options?: HookExecutionOptions,
+): Promise<HookExecutionResult> {
+  const defaultTimeout = 10000; // 10 seconds
+  const maxTimeout = 300000; // 5 minutes
+  const skipExecution =
+    process.env.NODE_ENV === "test" &&
+    process.env.TEST_HOOK_EXECUTION !== "true";
+
+  const startTime = Date.now();
+  const timeout = Math.min(options?.timeout ?? defaultTimeout, maxTimeout);
+
+  // Return mock result if execution is skipped
+  if (skipExecution) {
+    return {
+      success: true,
+      exitCode: 0,
+      stdout: "",
+      stderr: "",
+      duration: 0,
+      timedOut: false,
+    };
+  }
+
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+
+    // Parse command for shell execution
+    const isWindows = process.platform === "win32";
+    const shell = isWindows ? "cmd.exe" : "/bin/sh";
+    const shellFlag = isWindows ? "/c" : "-c";
+
+    const childProcess: ChildProcess = spawn(shell, [shellFlag, command], {
+      stdio: ["pipe", "pipe", "pipe"],
+      cwd: context.projectDir,
+      env: {
+        ...process.env,
+        HOOK_EVENT: context.event,
+        HOOK_TOOL_NAME: context.toolName || "",
+        HOOK_PROJECT_DIR: context.projectDir,
+      },
+    });
+
+    // Set up timeout
+    const timeoutHandle = setTimeout(() => {
+      timedOut = true;
+      childProcess.kill("SIGTERM");
+
+      // Force kill after additional delay
+      setTimeout(() => {
+        if (!childProcess.killed) {
+          childProcess.kill("SIGKILL");
+        }
+      }, 2000);
+    }, timeout);
+
+    // Handle stdout
+    if (childProcess.stdout) {
+      childProcess.stdout.on("data", (data: Buffer) => {
+        stdout += data.toString();
+      });
+    }
+
+    // Handle stderr
+    if (childProcess.stderr) {
+      childProcess.stderr.on("data", (data: Buffer) => {
+        stderr += data.toString();
+      });
+    }
+
+    // Send JSON input to stdin if we have extended context
+    if (childProcess.stdin && "sessionId" in context) {
+      try {
+        const jsonInput = buildHookJsonInput(context);
+        childProcess.stdin.write(JSON.stringify(jsonInput, null, 2));
+        childProcess.stdin.end();
+      } catch {
+        // Continue execution even if JSON input fails
+      }
+    } else if (childProcess.stdin) {
+      childProcess.stdin.end();
+    }
+
+    // Handle process completion
+    childProcess.on("close", (code: number | null) => {
+      clearTimeout(timeoutHandle);
+      const duration = Date.now() - startTime;
+
+      resolve({
+        success: !timedOut && (code === 0 || code === null),
+        exitCode: code || 0,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        duration,
+        timedOut,
+      });
+    });
+
+    // Handle process errors
+    childProcess.on("error", (error: Error) => {
+      clearTimeout(timeoutHandle);
+      const duration = Date.now() - startTime;
+
+      resolve({
+        success: false,
+        exitCode: 1,
+        stdout: stdout.trim(),
+        stderr: error.message,
+        duration,
+        timedOut,
+      });
+    });
+  });
+}
+
+/**
+ * Execute multiple commands in sequence
+ */
+export async function executeCommands(
+  commands: string[],
+  context: HookExecutionContext | ExtendedHookExecutionContext,
+  options?: HookExecutionOptions,
+): Promise<HookExecutionResult[]> {
+  const results: HookExecutionResult[] = [];
+
+  for (const command of commands) {
+    const result = await executeCommand(command, context, options);
+    results.push(result);
+
+    // Stop on first failure unless continueOnFailure is set
+    if (!result.success && !options?.continueOnFailure) {
+      break;
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Validate command safety (basic checks)
+ */
+export function isCommandSafe(command: string): boolean {
+  const trimmed = command.trim();
+
+  // Empty commands are safe (no-op)
+  if (!trimmed) {
+    return true;
+  }
+
+  // Check for obviously dangerous patterns
+  const dangerousPatterns = [
+    /rm\s+-rf\s+\//, // rm -rf /
+    /sudo\s+rm/, // sudo rm
+    />\s*\/dev\/sd[a-z]/, // writing to disk devices
+    /dd\s+if=.*of=\/dev/, // dd to devices
+    /mkfs/, // filesystem creation
+    /fdisk/, // disk partitioning
+    /format\s+[a-z]:/, // Windows format command
+  ];
+
+  return !dangerousPatterns.some((pattern) =>
+    pattern.test(trimmed.toLowerCase()),
+  );
+}
+
+// =============================================================================
+// Hook Settings Functions
+// =============================================================================
+
+/**
+ * Get the user-specific hooks configuration file path
+ */
+export function getUserHooksConfigPath(): string {
+  return join(homedir(), ".wave", "settings.json");
+}
+
+/**
+ * Get the project-specific hooks configuration file path
+ */
+export function getProjectHooksConfigPath(workdir: string): string {
+  return join(workdir, ".wave", "settings.json");
+}
+
+/**
+ * Load hooks configuration from a JSON file
+ */
+export function loadHooksConfigFromFile(
+  filePath: string,
+): PartialHookConfiguration | null {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+
+  const content = readFileSync(filePath, "utf-8");
+  const config = JSON.parse(content) as HookConfiguration;
+
+  // Validate basic structure
+  if (!config || typeof config !== "object" || !config.hooks) {
+    throw new Error(`Invalid hooks configuration structure in ${filePath}`);
+  }
+
+  return config.hooks;
+}
+
+/**
+ * Load user-specific hooks configuration
+ */
+export function loadUserHooksConfig(): PartialHookConfiguration | null {
+  return loadHooksConfigFromFile(getUserHooksConfigPath());
+}
+
+/**
+ * Load project-specific hooks configuration
+ */
+export function loadProjectHooksConfig(
+  workdir: string,
+): PartialHookConfiguration | null {
+  return loadHooksConfigFromFile(getProjectHooksConfigPath(workdir));
+}
+
+/**
+ * Load and merge hooks configuration from both user and project sources
+ */
+export function loadMergedHooksConfig(
+  workdir: string,
+): PartialHookConfiguration | null {
+  const userConfig = loadUserHooksConfig();
+  const projectConfig = loadProjectHooksConfig(workdir);
+
+  // No configuration found
+  if (!userConfig && !projectConfig) {
+    return null;
+  }
+
+  // Only one configuration found
+  if (!userConfig) return projectConfig;
+  if (!projectConfig) return userConfig;
+
+  // Merge configurations (project overrides user)
+  const merged: PartialHookConfiguration = {};
+
+  // Combine all hook events
+  const allEvents = new Set([
+    ...Object.keys(userConfig),
+    ...Object.keys(projectConfig),
+  ]);
+
+  for (const event of allEvents) {
+    if (!isValidHookEvent(event)) continue;
+
+    const userEventConfigs = userConfig[event] || [];
+    const projectEventConfigs = projectConfig[event] || [];
+
+    // Project configurations take precedence
+    merged[event] = [...userEventConfigs, ...projectEventConfigs];
+  }
+
+  return merged;
+}
+
+/**
+ * Check if hooks configuration exists (user or project)
+ */
+export function hasHooksConfiguration(workdir: string): boolean {
+  return (
+    existsSync(getUserHooksConfigPath()) ||
+    existsSync(getProjectHooksConfigPath(workdir))
+  );
+}
+
+/**
+ * Get hooks configuration information for debugging
+ */
+export function getHooksConfigurationInfo(workdir: string): {
+  hasUser: boolean;
+  hasProject: boolean;
+  paths: string[];
+} {
+  const userPath = getUserHooksConfigPath();
+  const projectPath = getProjectHooksConfigPath(workdir);
+
+  return {
+    hasUser: existsSync(userPath),
+    hasProject: existsSync(projectPath),
+    paths: [userPath, projectPath],
+  };
+}

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;
@@ -235,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;
       }
     }
 
@@ -304,10 +304,9 @@ export async function cleanupExpiredSessions(
       try {
         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;
       }
     }
   }

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/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/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[];
+}