wave-agent-sdk 0.0.7 → 0.0.8

package/src/tools/bashTool.ts

@@ -1,4 +1,5 @@
 import { spawn, ChildProcess } from "child_process";
+import { logger } from "../utils/globalLogger.js";
 import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
 
 /**
@@ -133,8 +134,8 @@ export const bashTool: ToolPlugin = {
                 if (child.pid && !child.killed) {
                   try {
                     process.kill(-child.pid, "SIGKILL");
-                  } catch {
-                    // logger.error("Failed to force kill process:", killError);
+                  } catch (killError) {
+                    logger.error("Failed to force kill process:", killError);
                   }
                 }
               }, 1000);
@@ -147,8 +148,8 @@ export const bashTool: ToolPlugin = {
                     child.kill("SIGKILL");
                   }
                 }, 1000);
-              } catch {
-                // logger.error("Failed to kill child process:", directKillError);
+              } catch (directKillError) {
+                logger.error("Failed to kill child process:", directKillError);
               }
             }
           }

package/src/tools/deleteFileTool.ts

@@ -1,4 +1,5 @@
 import { unlink } from "fs/promises";
+import { logger } from "../utils/globalLogger.js";
 import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
 import { resolvePath, getDisplayPath } from "../utils/path.js";
 
@@ -48,7 +49,7 @@ export const deleteFileTool: ToolPlugin = {
       // Delete file
       await unlink(filePath);
 
-      // logger.debug(`Successfully deleted file: ${filePath}`);
+      logger.debug(`Successfully deleted file: ${filePath}`);
 
       return {
         success: true,

package/src/tools/editTool.ts

@@ -1,4 +1,5 @@
 import { readFile, writeFile } from "fs/promises";
+import { logger } from "../utils/globalLogger.js";
 import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
 import { resolvePath, getDisplayPath } from "../utils/path.js";
 import { diffLines } from "diff";
@@ -160,7 +161,7 @@ export const editTool: ToolPlugin = {
         ? `Replaced ${replacementCount} instances`
         : "Text replaced successfully";
 
-      // logger.debug(`Edit tool: ${shortResult}`);
+      logger.debug(`Edit tool: ${shortResult}`);
 
       return {
         success: true,
@@ -174,7 +175,7 @@ export const editTool: ToolPlugin = {
     } catch (error) {
       const errorMessage =
         error instanceof Error ? error.message : String(error);
-      // logger.error(`Edit tool error: ${errorMessage}`);
+      logger.error(`Edit tool error: ${errorMessage}`);
       return {
         success: false,
         content: "",

package/src/tools/multiEditTool.ts

@@ -1,4 +1,5 @@
 import { readFile, writeFile } from "fs/promises";
+import { logger } from "../utils/globalLogger.js";
 import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
 import { resolvePath, getDisplayPath } from "../utils/path.js";
 import { diffLines } from "diff";
@@ -149,7 +150,7 @@ export const multiEditTool: ToolPlugin = {
         if (edits[0] && edits[0].old_string === "") {
           originalContent = "";
           isNewFile = true;
-          // logger.debug(`Creating new file: ${resolvedPath}`);
+          logger.debug(`Creating new file: ${resolvedPath}`);
         } else {
           return {
             success: false,
@@ -236,7 +237,7 @@ export const multiEditTool: ToolPlugin = {
 
       const detailedContent = `${shortResult}\n\nOperations performed:\n${appliedEdits.map((edit, i) => `${i + 1}. ${edit}`).join("\n")}`;
 
-      // logger.debug(`MultiEdit tool: ${shortResult}`);
+      logger.debug(`MultiEdit tool: ${shortResult}`);
 
       return {
         success: true,
@@ -250,7 +251,7 @@ export const multiEditTool: ToolPlugin = {
     } catch (error) {
       const errorMessage =
         error instanceof Error ? error.message : String(error);
-      // logger.error(`MultiEdit tool error: ${errorMessage}`);
+      logger.error(`MultiEdit tool error: ${errorMessage}`);
       return {
         success: false,
         content: "",

package/src/tools/readTool.ts

@@ -1,4 +1,5 @@
 import { readFile } from "fs/promises";
+import { logger } from "../utils/globalLogger.js";
 import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
 import { resolvePath, getDisplayPath } from "../utils/path.js";
 import {
@@ -75,7 +76,7 @@ export const readTool: ToolPlugin = {
 
       // Check if file is empty
       if (fileContent.length === 0) {
-        // logger.warn(`File ${filePath} exists but has empty contents`);
+        logger.warn(`File ${filePath} exists but has empty contents`);
         return {
           success: true,
           content:

package/src/tools/writeTool.ts

@@ -1,5 +1,6 @@
 import { readFile, writeFile, mkdir } from "fs/promises";
 import { dirname } from "path";
+import { logger } from "../utils/globalLogger.js";
 import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
 import { resolvePath, getDisplayPath } from "../utils/path.js";
 import { diffLines } from "diff";
@@ -14,7 +15,7 @@ export const writeTool: ToolPlugin = {
     function: {
       name: "Write",
       description:
-        "Writes a file to the local filesystem.\n\nUsage:\n- This tool will overwrite the existing file if there is one at the provided path.\n- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.\n- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.\n- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.\n- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.",
+        "Writes a file to the local filesystem.\n\nUsage:\n- This tool will overwrite the existing file if there is one at the provided path.\n- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.\n- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.\n- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.\n- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.\n- IMPORTANT: Always provide file_path parameter before content parameter when calling this tool.",
       parameters: {
         type: "object",
         properties: {
@@ -95,9 +96,9 @@ export const writeTool: ToolPlugin = {
           mkdirError instanceof Error &&
           !mkdirError.message.includes("EEXIST")
         ) {
-          // logger.warn(
-          //   `Failed to create directory ${fileDir}: ${mkdirError.message}`,
-          // );
+          logger.warn(
+            `Failed to create directory ${fileDir}: ${mkdirError.message}`,
+          );
         }
       }
 
@@ -121,7 +122,7 @@ export const writeTool: ToolPlugin = {
       const chars = content.length;
       const detailedContent = `${shortResult} (${lines} lines, ${chars} characters)`;
 
-      // logger.debug(`Write tool: ${shortResult}`);
+      logger.debug(`Write tool: ${shortResult}`);
 
       return {
         success: true,
@@ -135,7 +136,7 @@ export const writeTool: ToolPlugin = {
     } catch (error) {
       const errorMessage =
         error instanceof Error ? error.message : String(error);
-      // logger.error(`Write tool error: ${errorMessage}`);
+      logger.error(`Write tool error: ${errorMessage}`);
       return {
         success: false,
         content: "",

package/src/types/commands.ts

@@ -23,4 +23,10 @@ export interface CustomSlashCommand {
   filePath: string;
   content: string;
   config?: CustomSlashCommandConfig;
+
+  // Nested command support
+  namespace?: string; // Parent directory for nested commands (e.g., "openspec")
+  isNested: boolean; // Whether command is in a subdirectory
+  depth: number; // 0 = root, 1 = nested
+  segments: string[]; // Path components for ID generation (e.g., ["openspec", "apply"])
 }

package/src/types/core.ts

@@ -3,6 +3,8 @@
  * Dependencies: None (foundation layer)
  */
 
+import type { CompletionUsage } from "openai/resources";
+
 /**
  * Logger interface definition
  * Compatible with OpenAI package Logger interface
@@ -24,6 +26,48 @@ export interface Usage {
   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
+
+  // Cache-related tokens (Claude models only)
+  cache_read_input_tokens?: number; // Tokens read from cache
+  cache_creation_input_tokens?: number; // Tokens used to create cache entries
+  cache_creation?: {
+    ephemeral_5m_input_tokens: number; // Tokens cached for 5 minutes
+    ephemeral_1h_input_tokens: number; // Tokens cached for 1 hour
+  };
+}
+
+/**
+ * Enhanced usage metrics including Claude cache information
+ * Backward compatible with standard OpenAI CompletionUsage
+ */
+export interface ClaudeUsage extends CompletionUsage {
+  // Standard OpenAI usage fields (inherited)
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+
+  // Claude-specific cache extensions
+  /**
+   * Number of tokens read from existing cache
+   * Indicates cost savings from cache hits
+   */
+  cache_read_input_tokens?: number;
+
+  /**
+   * Number of tokens used to create new cache entries
+   * Investment in future cache hits
+   */
+  cache_creation_input_tokens?: number;
+
+  /**
+   * Detailed breakdown of cache creation by duration
+   */
+  cache_creation?: {
+    /** Tokens cached for 5 minute duration */
+    ephemeral_5m_input_tokens: number;
+    /** Tokens cached for 1 hour duration */
+    ephemeral_1h_input_tokens: number;
+  };
 }
 
 export class ConfigurationError extends Error {

package/src/types/environment.ts

@@ -0,0 +1,60 @@
+/**
+ * Environment Variable System Types
+ *
+ * Provides comprehensive TypeScript types for environment variable validation,
+ * merging, and conflict resolution in the Wave Agent SDK.
+ */
+
+/**
+ * Result of environment variable validation
+ */
+export interface EnvironmentValidationResult {
+  isValid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Context containing merged environment variables and conflict information
+ */
+export interface MergedEnvironmentContext {
+  userVars: Record<string, string>;
+  projectVars: Record<string, string>;
+  mergedVars: Record<string, string>;
+  conflicts: Array<{
+    key: string;
+    userValue: string;
+    projectValue: string;
+    resolvedValue: string;
+  }>;
+}
+
+/**
+ * Type guard to check if a value is a valid environment variables object
+ */
+export function isValidEnvironmentVars(
+  env: unknown,
+): env is Record<string, string> {
+  if (typeof env !== "object" || env === null) {
+    return false;
+  }
+
+  // Check if all keys and values are strings
+  for (const [key, value] of Object.entries(env)) {
+    if (typeof key !== "string" || typeof value !== "string") {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Configuration options for environment merging
+ */
+export interface EnvironmentMergeOptions {
+  /** Whether to include warnings for conflicting variables */
+  includeConflictWarnings?: boolean;
+  /** Whether to validate variable names for common patterns */
+  validateVariableNames?: boolean;
+}

package/src/types/hooks.ts

@@ -8,7 +8,7 @@
 import { join } from "path";
 import { homedir } from "os";
 
-// Session path utility (from session.ts)
+// Session path utility (simplified version for hooks)
 export function getSessionFilePath(sessionId: string): string {
   const shortId = sessionId.split("_")[2] || sessionId.slice(-8);
   return join(homedir(), ".wave", "sessions", `session_${shortId}.json`);
@@ -19,7 +19,8 @@ export type HookEvent =
   | "PreToolUse"
   | "PostToolUse"
   | "UserPromptSubmit"
-  | "Stop";
+  | "Stop"
+  | "SubagentStop";
 
 // Individual hook command configuration
 export interface HookCommand {
@@ -33,8 +34,14 @@ export interface HookEventConfig {
   hooks: HookCommand[];
 }
 
-// Root configuration structure for all hook definitions
-export interface HookConfiguration {
+// Root configuration structure for all Wave Agent settings including hooks and environment variables
+export interface WaveConfiguration {
+  hooks?: Partial<Record<HookEvent, HookEventConfig[]>>;
+  env?: Record<string, string>; // Environment variables key-value pairs
+}
+
+// Legacy alias for backward compatibility - will be deprecated
+export interface HookConfiguration extends WaveConfiguration {
   hooks: Partial<Record<HookEvent, HookEventConfig[]>>;
 }
 
@@ -104,9 +111,13 @@ export class HookConfigurationError extends Error {
 
 // Type guards for runtime validation
 export function isValidHookEvent(event: string): event is HookEvent {
-  return ["PreToolUse", "PostToolUse", "UserPromptSubmit", "Stop"].includes(
-    event,
-  );
+  return [
+    "PreToolUse",
+    "PostToolUse",
+    "UserPromptSubmit",
+    "Stop",
+    "SubagentStop",
+  ].includes(event);
 }
 
 export function isValidHookCommand(cmd: unknown): cmd is HookCommand {
@@ -144,13 +155,14 @@ export interface HookJsonInput {
   session_id: string; // Format: "wave_session_{uuid}_{shortId}"
   transcript_path: string; // Format: "~/.wave/sessions/session_{shortId}.json"
   cwd: string; // Absolute path to current working directory
-  hook_event_name: HookEvent; // "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "Stop"
+  hook_event_name: HookEvent; // "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "Stop" | "SubagentStop"
 
   // Optional fields based on event type
   tool_name?: string; // Present for PreToolUse, PostToolUse
   tool_input?: unknown; // Present for PreToolUse, PostToolUse
   tool_response?: unknown; // Present for PostToolUse only
   user_prompt?: string; // Present for UserPromptSubmit only
+  subagent_type?: string; // Present when hook is executed by a subagent
 }
 
 // Extended context interface for passing additional data to hook executor
@@ -161,6 +173,7 @@ export interface ExtendedHookExecutionContext extends HookExecutionContext {
   toolInput?: unknown; // Tool input parameters (PreToolUse/PostToolUse)
   toolResponse?: unknown; // Tool execution result (PostToolUse only)
   userPrompt?: string; // User prompt text (UserPromptSubmit only)
+  subagentType?: string; // Subagent type when hook is executed by a subagent
 }
 
 // Environment variables injected into hook processes

package/src/types/index.ts

@@ -21,3 +21,5 @@ export * from "./processes.js";
 export * from "./commands.js";
 export * from "./skills.js";
 export * from "./config.js";
+export * from "./session.js";
+export * from "./environment.js";

package/src/types/memoryStore.ts

@@ -0,0 +1,94 @@
+/**
+ * Memory Store Type Definitions
+ *
+ * Provides TypeScript types for in-memory file storage system,
+ * enabling optimized access to frequently read files like AGENTS.md.
+ */
+
+export interface MemoryStore {
+  content: string; // Current file content in memory
+  lastModified: number; // File modification timestamp
+  path: string; // Absolute file path
+  isLoaded: boolean; // Whether content has been loaded
+}
+
+export interface MemoryStoreEntry {
+  content: string;
+  path: string;
+  lastModified: number;
+  isLoaded: boolean;
+}
+
+export interface MemoryStoreStats {
+  contentSize: number;
+  lastUpdated: number;
+  updateCount: number;
+  isLoaded: boolean;
+}
+
+export interface MemoryUpdateEvent {
+  path: string;
+  reason: "file_change" | "initial_load" | "manual_reload";
+  timestamp: number;
+  previousSize?: number;
+  newSize: number;
+}
+
+/**
+ * Memory Store Service Interface
+ * Maps to FR-006, FR-007: Memory storage and updates
+ */
+export interface MemoryStoreService {
+  /**
+   * Get content from memory store (loads from file if not loaded)
+   * Maps to FR-006: Keep AGENTS.md content in memory to avoid repeated reads
+   */
+  getContent(path: string): Promise<string>;
+
+  /**
+   * Update memory content from file
+   * Maps to FR-007: Update memory content when file changes
+   */
+  updateContent(path: string): Promise<void>;
+
+  /**
+   * Get memory store statistics
+   * For monitoring and debugging
+   */
+  getStats(path?: string): MemoryStoreStats;
+
+  /**
+   * Check if content is loaded in memory
+   * For status checking
+   */
+  isLoaded(path: string): boolean;
+
+  /**
+   * Manually reload content from file
+   * For force refresh scenarios
+   */
+  reloadContent(path: string): Promise<void>;
+
+  /**
+   * Remove content from memory store
+   * For cleanup when file is deleted
+   */
+  removeContent(path: string): boolean;
+
+  /**
+   * Clear all content from memory store
+   * For cleanup and testing
+   */
+  clear(): void;
+
+  /**
+   * Get all stored paths
+   * For monitoring and debugging
+   */
+  getStoredPaths(): string[];
+
+  /**
+   * Check if file exists and is accessible
+   */
+  fileExists(path: string): Promise<boolean>;
+}

package/src/types/messaging.ts

@@ -4,6 +4,7 @@
  */
 
 import type { Usage } from "./core.js";
+import type { SubagentConfiguration } from "../utils/subagentParser.js";
 
 export enum MessageSource {
   USER = "user",
@@ -14,6 +15,7 @@ export interface Message {
   role: "user" | "assistant";
   blocks: MessageBlock[];
   usage?: Usage; // Usage data for this message's AI operation (assistant messages only)
+  metadata?: Record<string, unknown>; // Additional metadata from AI responses
 }
 
 export type MessageBlock =
@@ -51,10 +53,18 @@ export interface ToolBlock {
   }>;
   id?: string;
   name?: string;
-  isRunning?: boolean; // Mark if tool is actually executing
+  /**
+   * Tool execution stage:
+   * - 'start': Tool call initiated (from AI service streaming)
+   * - 'streaming': Tool parameters being streamed (from AI service)
+   * - 'running': Tool execution in progress (from AI manager)
+   * - 'end': Tool execution completed (from AI manager)
+   */
+  stage: "start" | "streaming" | "running" | "end";
   success?: boolean;
   error?: string | Error;
   compactParams?: string; // Compact parameter display
+  parametersChunk?: string; // Incremental parameter updates for streaming
 }
 
 export interface ImageBlock {
@@ -83,6 +93,7 @@ export interface CommandOutputBlock {
 export interface CompressBlock {
   type: "compress";
   content: string;
+  sessionId: string;
 }
 
 export interface MemoryBlock {
@@ -98,5 +109,6 @@ export interface SubagentBlock {
   subagentId: string;
   subagentName: string;
   status: "active" | "completed" | "error" | "aborted";
-  messages: Message[];
+  sessionId: string;
+  configuration: SubagentConfiguration;
 }

package/src/types/session.ts

@@ -0,0 +1,25 @@
+/**
+ * Session management types for project-based organization with JSONL format
+ * Dependencies: Core messaging types
+ *
+ * SIMPLIFIED: Removed unused interfaces to focus on core functionality
+ */
+
+import type { Message } from "./messaging.js";
+
+// Enhanced message interface for JSONL storage (extends existing Message)
+export interface SessionMessage extends Message {
+  timestamp: string; // ISO 8601 - added for JSONL format
+  // Inherits: role: "user" | "assistant", blocks: MessageBlock[], usage?, metadata?
+}
+
+// Metadata line that appears as the first line in JSONL session files
+export interface SessionMetadataLine {
+  __meta__: true;
+  sessionId: string;
+  sessionType: "main" | "subagent";
+  parentSessionId?: string;
+  subagentType?: string;
+  workdir: string;
+  startedAt: string;
+}