wave-agent-sdk 0.14.1 → 0.14.2

package/src/managers/aiManager.ts

@@ -30,7 +30,7 @@ import type { NotificationQueue } from "./notificationQueue.js";
 import { logger } from "../utils/globalLogger.js";
 
 export interface AIManagerCallbacks {
-  onCompressionStateChange?: (isCompressing: boolean) => void;
+  onCompactionStateChange?: (isCompacting: boolean) => void;
   onUsageAdded?: (usage: Usage) => void;
   onCwdChange?: (newCwd: string) => void;
 }
@@ -58,7 +58,7 @@ export class AIManager {
   private stream: boolean; // Streaming mode flag
   private modelOverride?: string;
   private _onCwdChange?: (newCwd: string) => void; // Store callback for CWD changes
-  private consecutiveCompressionFailures: number = 0;
+  private consecutiveCompactionFailures: number = 0;
 
   // Service overrides
   constructor(
@@ -177,7 +177,7 @@ export class AIManager {
     this._onCwdChange = callback;
   }
 
-  private isCompressing: boolean = false;
+  private isCompacting: boolean = false;
   private callbacks: AIManagerCallbacks;
 
   /**
@@ -253,8 +253,8 @@ export class AIManager {
     return "";
   }
 
-  // Private method to handle token statistics and message compression
-  private async handleTokenUsageAndCompression(
+  // Private method to handle token statistics and message compaction
+  private async handleTokenUsageAndCompaction(
     usage: Usage | undefined,
     abortController: AbortController,
   ): Promise<void> {
@@ -272,30 +272,30 @@ export class AIManager {
       this.getMaxInputTokens()
     ) {
       logger?.debug(
-        `Token usage exceeded ${this.getMaxInputTokens()}, compressing messages...`,
+        `Token usage exceeded ${this.getMaxInputTokens()}, compacting messages...`,
       );
 
-      // Check if messages need compression
-      const messagesToCompress = this.messageManager.getMessages();
+      // Check if messages need compaction
+      const messagesToCompact = this.messageManager.getMessages();
 
-      // If there are messages to compress, perform compression
-      if (messagesToCompress.length > 0) {
-        // Circuit breaker: skip compression after 3 consecutive failures
-        if (this.consecutiveCompressionFailures >= 3) {
+      // If there are messages to compact, perform compaction
+      if (messagesToCompact.length > 0) {
+        // Circuit breaker: skip compaction after 3 consecutive failures
+        if (this.consecutiveCompactionFailures >= 3) {
           logger?.warn(
-            `Skipping compression: ${this.consecutiveCompressionFailures} consecutive failures`,
+            `Skipping compaction: ${this.consecutiveCompactionFailures} consecutive failures`,
           );
           return;
         }
 
-        const recentChatMessages = convertMessagesForAPI(messagesToCompress);
+        const recentChatMessages = convertMessagesForAPI(messagesToCompact);
 
-        // Save session before compression to preserve original messages
+        // Save session before compaction to preserve original messages
         await this.messageManager.saveSession();
 
-        this.setIsCompressing(true);
+        this.setIsCompacting(true);
         try {
-          const compressionResult = await aiService.compressMessages({
+          const compactResult = await aiService.compactMessages({
             gatewayConfig: this.getGatewayConfig(),
             modelConfig: this.getModelConfig(),
             messages: recentChatMessages,
@@ -303,15 +303,15 @@ export class AIManager {
             model: this.getModelConfig().fastModel,
           });
 
-          // Handle usage tracking for compression operations
-          let compressionUsage: Usage | undefined;
-          if (compressionResult.usage) {
-            compressionUsage = {
-              prompt_tokens: compressionResult.usage.prompt_tokens,
-              completion_tokens: compressionResult.usage.completion_tokens,
-              total_tokens: compressionResult.usage.total_tokens,
+          // Handle usage tracking for compaction operations
+          let compactUsage: Usage | undefined;
+          if (compactResult.usage) {
+            compactUsage = {
+              prompt_tokens: compactResult.usage.prompt_tokens,
+              completion_tokens: compactResult.usage.completion_tokens,
+              total_tokens: compactResult.usage.total_tokens,
               model: this.getModelConfig().fastModel,
-              operation_type: "compress",
+              operation_type: "compact",
             };
           }
 
@@ -364,73 +364,152 @@ export class AIManager {
             }
           }
 
-          // 4. Skills context
-          const skills =
-            this.skillManager
-              ?.getAvailableSkills()
-              .filter((s) => !s.disableModelInvocation) || [];
-          if (skills.length > 0) {
-            const skillList = skills
-              .map((s) => `- ${s.name}: ${s.description || ""}`)
-              .join("\n");
-            contextParts.push(`\n\n[Available Skills]\n${skillList}`);
+          // 4. Invoked skills context (with token budget, matching Claude Code)
+          const POST_COMPACT_SKILLS_TOKEN_BUDGET = 25_000;
+          const POST_COMPACT_MAX_TOKENS_PER_SKILL = 5_000;
+          const invokedSkillNames =
+            this.messageManager.getInvokedSkillNames(10);
+          if (invokedSkillNames.length > 0 && this.skillManager) {
+            const invokedSkillParts: string[] = [];
+            let skillsUsedTokens = 0;
+            for (const skillName of invokedSkillNames) {
+              try {
+                const skill = await this.skillManager.loadSkill(skillName);
+                if (!skill) continue;
+
+                // Extract content after frontmatter (matching prepareSkillContent pattern)
+                const contentMatch = skill.content.match(
+                  /^---\n[\s\S]*?\n---\n([\s\S]*)$/,
+                );
+                let skillContent = contentMatch
+                  ? contentMatch[1].trim()
+                  : skill.content;
+
+                // Per-skill token budget enforcement (~4 chars per token)
+                const maxSkillChars = POST_COMPACT_MAX_TOKENS_PER_SKILL * 4;
+                if (skillContent.length > maxSkillChars) {
+                  skillContent =
+                    skillContent.slice(0, maxSkillChars) +
+                    "\n\n...[truncated]...";
+                }
+
+                const skillTokens = Math.ceil(skillContent.length / 4);
+                if (
+                  skillsUsedTokens + skillTokens >
+                  POST_COMPACT_SKILLS_TOKEN_BUDGET
+                )
+                  break;
+                skillsUsedTokens += skillTokens;
+
+                invokedSkillParts.push(
+                  `\n\n## ${skill.name}\n${skill.description ? `*${skill.description}*\n\n` : ""}\`\`\`\n${skillContent}\n\`\`\``,
+                );
+              } catch {
+                // Skip skills that can't be loaded
+              }
+            }
+            if (invokedSkillParts.length > 0) {
+              contextParts.push(
+                `\n\n[Invoked Skills]\n${invokedSkillParts.join("")}`,
+              );
+            }
           }
 
-          // 5. Background agents status
-          const agents = this.backgroundTaskManager?.getAllTasks() || [];
+          // 5. Background subagent status (shell tasks excluded, matching Claude Code's createAsyncAgentAttachmentsIfNeeded)
+          const agents =
+            this.backgroundTaskManager
+              ?.getAllTasks()
+              .filter((a) => a.type === "subagent") || [];
           if (agents.length > 0) {
-            const agentList = agents
-              .map((a) => `- Agent "${a.description}": ${a.status}`)
-              .join("\n");
-            contextParts.push(`\n\n[Background Tasks]\n${agentList}`);
+            const agentParts: string[] = [];
+            for (const a of agents) {
+              if (a.status === "killed") {
+                agentParts.push(
+                  `Task "${a.description}" (${a.id}) was stopped by the user.`,
+                );
+              } else if (a.status === "running") {
+                const parts = [
+                  `Background agent "${a.description}" (${a.id}) is still running.`,
+                  `Do NOT spawn a duplicate. You will be notified when it completes.`,
+                ];
+                if (a.outputPath) {
+                  parts.push(`You can read partial output at ${a.outputPath}.`);
+                }
+                agentParts.push(parts.join(" "));
+              } else {
+                // completed or failed
+                const parts = [
+                  `Task ${a.id} (status: ${a.status}) (description: ${a.description}).`,
+                ];
+                const deltaText = a.status === "failed" ? a.stderr : a.stdout;
+                if (deltaText && deltaText.length > 0) {
+                  const summary =
+                    deltaText.length > 500
+                      ? deltaText.slice(0, 500) + "..."
+                      : deltaText;
+                  parts.push(`Delta: ${summary}`);
+                }
+                if (a.outputPath) {
+                  parts.push(
+                    `Read the output file to retrieve the result: ${a.outputPath}.`,
+                  );
+                }
+                agentParts.push(parts.join(" "));
+              }
+            }
+            if (agentParts.length > 0) {
+              contextParts.push(
+                `\n\n[Background Tasks]\n${agentParts.join("\n")}`,
+              );
+            }
           }
 
           // Merge context restoration into summary
           const enhancedSummary =
-            compressionResult.content +
+            compactResult.content +
             (contextParts.length > 0
               ? `\n\n[Context Restoration]` + contextParts.join("")
               : "");
 
-          // Execute message reconstruction and sessionId update after compression
-          this.messageManager.compressMessagesAndUpdateSession(
+          // Execute message reconstruction and sessionId update after compaction
+          this.messageManager.compactMessagesAndUpdateSession(
             enhancedSummary,
-            compressionUsage,
+            compactUsage,
           );
 
           // Notify Agent to add to usage tracking
-          if (compressionUsage && this.callbacks?.onUsageAdded) {
-            this.callbacks.onUsageAdded(compressionUsage);
+          if (compactUsage && this.callbacks?.onUsageAdded) {
+            this.callbacks.onUsageAdded(compactUsage);
           }
 
           logger?.debug(
-            `Successfully compressed ${messagesToCompress.length} messages and updated session`,
+            `Successfully compacted ${messagesToCompact.length} messages and updated session`,
           );
-          this.consecutiveCompressionFailures = 0;
-        } catch (compressError) {
-          this.consecutiveCompressionFailures++;
+          this.consecutiveCompactionFailures = 0;
+        } catch (compactError) {
+          this.consecutiveCompactionFailures++;
           logger?.error(
-            `Failed to compress messages (${this.consecutiveCompressionFailures} consecutive):`,
-            compressError,
+            `Failed to compact messages (${this.consecutiveCompactionFailures} consecutive):`,
+            compactError,
           );
           this.messageManager.addErrorBlock(
-            `Failed to compress conversation history: ${compressError instanceof Error ? compressError.message : String(compressError)}. You may encounter context limit issues.`,
+            `Failed to compact conversation history: ${compactError instanceof Error ? compactError.message : String(compactError)}. You may encounter context limit issues.`,
           );
         } finally {
-          this.setIsCompressing(false);
+          this.setIsCompacting(false);
         }
       }
     }
   }
 
-  public getIsCompressing(): boolean {
-    return this.isCompressing;
+  public getIsCompacting(): boolean {
+    return this.isCompacting;
   }
 
-  public setIsCompressing(isCompressing: boolean): void {
-    if (this.isCompressing !== isCompressing) {
-      this.isCompressing = isCompressing;
-      this.callbacks.onCompressionStateChange?.(isCompressing);
+  public setIsCompacting(isCompacting: boolean): void {
+    if (this.isCompacting !== isCompacting) {
+      this.isCompacting = isCompacting;
+      this.callbacks.onCompactionStateChange?.(isCompacting);
     }
   }
 
@@ -914,8 +993,8 @@ export class AIManager {
         await Promise.all(toolExecutionPromises);
       }
 
-      // Handle token statistics and message compression
-      await this.handleTokenUsageAndCompression(result.usage, abortController);
+      // Handle token statistics and message compaction
+      await this.handleTokenUsageAndCompaction(result.usage, abortController);
 
       // Finalize text/reasoning blocks for the final response (no tools)
       this.messageManager.finalizeStreamingBlocks();

package/src/managers/backgroundTaskManager.ts

@@ -153,22 +153,27 @@ export class BackgroundTaskManager {
       if (logStream.writable) {
         logStream.end();
       }
-      shell.status = code === 0 ? "completed" : "failed";
+      const wasKilled = shell.status === "killed";
+      if (!wasKilled) {
+        shell.status = code === 0 ? "completed" : "failed";
+      }
       shell.exitCode = code ?? 0;
       shell.endTime = Date.now();
       shell.runtime = shell.endTime - startTime;
       this.notifyTasksChange();
 
-      // Enqueue completion notification
-      const notificationQueue = this.container.has("NotificationQueue")
-        ? this.container.get<NotificationQueue>("NotificationQueue")
-        : undefined;
-      if (notificationQueue) {
-        const statusStr = shell.status;
-        const summary = `Command "${command}" ${statusStr} with exit code ${code ?? 0}`;
-        notificationQueue.enqueue(
-          `<task-notification>\n<task-id>${id}</task-id>\n<task-type>shell</task-type>\n<output-file>${logPath}</output-file>\n<status>${statusStr}</status>\n<summary>${summary}</summary>\n</task-notification>`,
-        );
+      // Skip notification if task was manually killed (user/agent-initiated stop)
+      if (!wasKilled) {
+        const notificationQueue = this.container.has("NotificationQueue")
+          ? this.container.get<NotificationQueue>("NotificationQueue")
+          : undefined;
+        if (notificationQueue) {
+          const statusStr = shell.status;
+          const summary = `Command "${command}" ${statusStr} with exit code ${code ?? 0}`;
+          notificationQueue.enqueue(
+            `<task-notification>\n<task-id>${id}</task-id>\n<task-type>shell</task-type>\n<output-file>${logPath}</output-file>\n<status>${statusStr}</status>\n<summary>${summary}</summary>\n</task-notification>`,
+          );
+        }
       }
     };
 
@@ -301,22 +306,27 @@ export class BackgroundTaskManager {
       if (logStream.writable) {
         logStream.end();
       }
-      shell.status = code === 0 ? "completed" : "failed";
+      const wasKilled = shell.status === "killed";
+      if (!wasKilled) {
+        shell.status = code === 0 ? "completed" : "failed";
+      }
       shell.exitCode = code ?? 0;
       shell.endTime = Date.now();
       shell.runtime = shell.endTime - startTime;
       this.notifyTasksChange();
 
-      // Enqueue completion notification
-      const notificationQueue = this.container.has("NotificationQueue")
-        ? this.container.get<NotificationQueue>("NotificationQueue")
-        : undefined;
-      if (notificationQueue) {
-        const statusStr = shell.status;
-        const summary = `Command "${command}" ${statusStr} with exit code ${code ?? 0}`;
-        notificationQueue.enqueue(
-          `<task-notification>\n<task-id>${id}</task-id>\n<task-type>shell</task-type>\n<output-file>${logPath}</output-file>\n<status>${statusStr}</status>\n<summary>${summary}</summary>\n</task-notification>`,
-        );
+      // Skip notification if task was manually killed (user/agent-initiated stop)
+      if (!wasKilled) {
+        const notificationQueue = this.container.has("NotificationQueue")
+          ? this.container.get<NotificationQueue>("NotificationQueue")
+          : undefined;
+        if (notificationQueue) {
+          const statusStr = shell.status;
+          const summary = `Command "${command}" ${statusStr} with exit code ${code ?? 0}`;
+          notificationQueue.enqueue(
+            `<task-notification>\n<task-id>${id}</task-id>\n<task-type>shell</task-type>\n<output-file>${logPath}</output-file>\n<status>${statusStr}</status>\n<summary>${summary}</summary>\n</task-notification>`,
+          );
+        }
       }
     });
 

package/src/managers/hookManager.ts

@@ -12,6 +12,7 @@ import {
   type ExtendedHookExecutionContext,
   type HookExecutionResult,
   type HookValidationResult,
+  type SessionEndSource,
   HookConfigurationError,
   isValidHookEvent,
   isValidHookEventConfig,
@@ -80,9 +81,8 @@ export class HookManager {
    */
   loadConfigurationFromWaveConfig(waveConfig: WaveConfiguration | null): void {
     try {
-      this.configuration = waveConfig?.hooks || undefined;
-
-      // Validate the loaded configuration if it exists
+      // Merge Wave configuration hooks with existing plugin hooks
+      // (plugin hooks were registered earlier via registerPluginHooks)
       if (waveConfig?.hooks) {
         const validation = this.validatePartialConfiguration(waveConfig.hooks);
         if (!validation.valid) {
@@ -91,17 +91,18 @@ export class HookManager {
             validation.errors,
           );
         }
+        if (!this.configuration) {
+          this.configuration = {};
+        }
+        this.mergeHooksConfiguration(this.configuration, waveConfig.hooks);
       }
     } catch (error) {
-      // If loading fails, start with undefined configuration (no hooks)
-      this.configuration = undefined;
-
       // Re-throw configuration errors, but handle other errors gracefully
       if (error instanceof HookConfigurationError) {
         throw error;
       } else {
         logger?.warn(
-          `[HookManager] Failed to load configuration, continuing with no hooks: ${(error as Error).message}`,
+          `[HookManager] Failed to load configuration, continuing with existing hooks: ${(error as Error).message}`,
         );
       }
     }
@@ -298,6 +299,8 @@ export class HookManager {
         source: MessageSource.HOOK,
       });
     }
+    // For SessionStart, stdout is processed separately in executeSessionStartHooks
+    // For SessionEnd, stdout is ignored (fire-and-forget cleanup)
     // For other hook types (PreToolUse, PostToolUse, Stop, PermissionRequest), ignore stdout
   }
 
@@ -374,6 +377,16 @@ export class HookManager {
         messageManager.addErrorBlock(errorMessage);
         return { shouldBlock: false };
 
+      case "SessionStart":
+        // Non-blocking for startup, show error in error block
+        messageManager.addErrorBlock(errorMessage);
+        return { shouldBlock: false };
+
+      case "SessionEnd":
+        // Blocking error (exit code 2): show in error block, don't block shutdown
+        messageManager.addErrorBlock(errorMessage);
+        return { shouldBlock: false };
+
       default:
         return { shouldBlock: false };
     }
@@ -577,7 +590,9 @@ export class HookManager {
       (event === "UserPromptSubmit" ||
         event === "Stop" ||
         event === "SubagentStop" ||
-        event === "WorktreeCreate") &&
+        event === "WorktreeCreate" ||
+        event === "SessionStart" ||
+        event === "SessionEnd") &&
       context.toolName !== undefined
     ) {
       logger?.warn(
@@ -654,7 +669,9 @@ export class HookManager {
       event === "Stop" ||
       event === "SubagentStop" ||
       event === "WorktreeCreate" ||
-      event === "CwdChanged"
+      event === "CwdChanged" ||
+      event === "SessionStart" ||
+      event === "SessionEnd"
     ) {
       return true;
     }
@@ -714,7 +731,9 @@ export class HookManager {
       (event === "UserPromptSubmit" ||
         event === "Stop" ||
         event === "SubagentStop" ||
-        event === "WorktreeCreate") &&
+        event === "WorktreeCreate" ||
+        event === "SessionStart" ||
+        event === "SessionEnd") &&
       config.matcher
     ) {
       errors.push(`${prefix}: Event ${event} should not have a matcher`);
@@ -755,6 +774,8 @@ export class HookManager {
           PermissionRequest: 0,
           WorktreeCreate: 0,
           CwdChanged: 0,
+          SessionStart: 0,
+          SessionEnd: 0,
         },
       };
     }
@@ -768,6 +789,8 @@ export class HookManager {
       PermissionRequest: 0,
       WorktreeCreate: 0,
       CwdChanged: 0,
+      SessionStart: 0,
+      SessionEnd: 0,
     };
 
     let totalConfigs = 0;
@@ -844,4 +867,96 @@ export class HookManager {
 
     this.mergeHooksConfiguration(this.configuration, stampedHooks);
   }
+
+  /**
+   * Execute SessionStart hooks during initialization.
+   * Collects additionalContext and initialUserMessage from hook stdout.
+   */
+  async executeSessionStartHooks(
+    source: "startup" | "resume" | "compact",
+    sessionId: string,
+    transcriptPath: string,
+    agentType?: string,
+  ): Promise<{
+    results: HookExecutionResult[];
+    additionalContext?: string;
+    initialUserMessage?: string;
+  }> {
+    const context: ExtendedHookExecutionContext = {
+      event: "SessionStart",
+      projectDir: this.workdir,
+      timestamp: new Date(),
+      sessionId,
+      transcriptPath,
+      cwd: this.workdir,
+      source,
+      agentType,
+      env: Object.fromEntries(
+        Object.entries(process.env).filter((e) => e[1] !== undefined),
+      ) as Record<string, string>,
+    };
+
+    const results = await this.executeHooks("SessionStart", context);
+
+    let additionalContext: string | undefined;
+    let initialUserMessage: string | undefined;
+
+    // Process stdout from successful hooks
+    for (const result of results) {
+      if (result.success && result.stdout?.trim()) {
+        const trimmed = result.stdout.trim();
+        // Try to parse as JSON for structured output
+        try {
+          const parsed = JSON.parse(trimmed);
+          if (parsed.hookSpecificOutput?.additionalContext) {
+            additionalContext =
+              (additionalContext ? additionalContext + "\n" : "") +
+              parsed.hookSpecificOutput.additionalContext;
+          }
+          if (parsed.initialUserMessage) {
+            initialUserMessage = parsed.initialUserMessage;
+          }
+        } catch {
+          // Not JSON, treat as additional context
+          additionalContext =
+            (additionalContext ? additionalContext + "\n" : "") + trimmed;
+        }
+      }
+    }
+
+    return { results, additionalContext, initialUserMessage };
+  }
+
+  /**
+   * Execute SessionEnd hooks during agent destruction.
+   * Non-blocking: always continues shutdown even if hooks fail.
+   * No stdout processing needed (SessionEnd hooks are fire-and-forget cleanup).
+   */
+  async executeSessionEndHooks(
+    source: SessionEndSource,
+    sessionId: string,
+    transcriptPath: string,
+  ): Promise<HookExecutionResult[]> {
+    const context: ExtendedHookExecutionContext = {
+      event: "SessionEnd",
+      projectDir: this.workdir,
+      timestamp: new Date(),
+      sessionId,
+      transcriptPath,
+      cwd: this.workdir,
+      endSource: source,
+      env: Object.fromEntries(
+        Object.entries(process.env).filter((e) => e[1] !== undefined),
+      ) as Record<string, string>,
+    };
+
+    const results = await this.executeHooks("SessionEnd", context);
+
+    // Process results but never block shutdown
+    if (results.length > 0) {
+      this.processHookResults("SessionEnd", results);
+    }
+
+    return results;
+  }
 }