wave-agent-sdk 0.0.7 → 0.0.10

package/src/types/environment.ts

@@ -0,0 +1,104 @@
+/**
+ * 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;
+}
+
+/**
+ * Result of environment variable processing operations
+ */
+export interface EnvironmentProcessResult {
+  /** The processed environment variables */
+  processedVars: Record<string, string>;
+  /** Any conflicts that occurred during processing */
+  conflicts: EnvironmentConflict[];
+  /** Non-critical warnings during processing */
+  warnings: string[];
+  /** Whether the variables were successfully applied to process.env */
+  applied: boolean;
+}
+
+/**
+ * Enhanced environment merge context with conflict details
+ */
+export interface EnvironmentMergeContext {
+  /** User-provided environment variables */
+  userVars: Record<string, string>;
+  /** Project-provided environment variables */
+  projectVars: Record<string, string>;
+  /** Final merged environment variables */
+  mergedVars: Record<string, string>;
+  /** Detailed conflict information */
+  conflicts: EnvironmentConflict[];
+}
+
+/**
+ * Detailed information about an environment variable conflict
+ */
+export interface EnvironmentConflict {
+  /** The environment variable key */
+  key: string;
+  /** Value from user configuration */
+  userValue: string;
+  /** Value from project configuration */
+  projectValue: string;
+  /** Final resolved value (which source won) */
+  resolvedValue: string;
+  /** Which source provided the final value */
+  source: "user" | "project";
+}

package/src/types/fileSearch.ts

@@ -0,0 +1,4 @@
+export interface FileItem {
+  path: string;
+  type: "file" | "directory";
+}

package/src/types/hooks.ts

@@ -5,21 +5,14 @@
  * enabling automated actions at specific workflow points.
  */
 
-import { join } from "path";
-import { homedir } from "os";
-
-// Session path utility (from session.ts)
-export function getSessionFilePath(sessionId: string): string {
-  const shortId = sessionId.split("_")[2] || sessionId.slice(-8);
-  return join(homedir(), ".wave", "sessions", `session_${shortId}.json`);
-}
-
 // Hook event types - trigger points in the AI workflow
 export type HookEvent =
   | "PreToolUse"
   | "PostToolUse"
   | "UserPromptSubmit"
-  | "Stop";
+  | "Stop"
+  | "SubagentStop"
+  | "Notification";
 
 // Individual hook command configuration
 export interface HookCommand {
@@ -33,8 +26,19 @@ 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
+  defaultMode?: "default" | "bypassPermissions" | "acceptEdits"; // Default permission mode for restricted tools
+  /** New field for persistent permissions */
+  permissions?: {
+    allow?: string[];
+  };
+}
+
+// Legacy alias for backward compatibility - will be deprecated
+export interface HookConfiguration extends WaveConfiguration {
   hooks: Partial<Record<HookEvent, HookEventConfig[]>>;
 }
 
@@ -104,9 +108,14 @@ 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",
+    "Notification",
+  ].includes(event);
 }
 
 export function isValidHookCommand(cmd: unknown): cmd is HookCommand {
@@ -144,13 +153,16 @@ 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" | "Notification"
 
   // 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
+  message?: string; // Present for Notification events
+  notification_type?: string; // Present for Notification events
 }
 
 // Extended context interface for passing additional data to hook executor
@@ -160,7 +172,11 @@ export interface ExtendedHookExecutionContext extends HookExecutionContext {
   cwd?: string; // Current working directory
   toolInput?: unknown; // Tool input parameters (PreToolUse/PostToolUse)
   toolResponse?: unknown; // Tool execution result (PostToolUse only)
+  env?: Record<string, string>; // Additional environment variables (from configuration)
   userPrompt?: string; // User prompt text (UserPromptSubmit only)
+  subagentType?: string; // Subagent type when hook is executed by a subagent
+  message?: string; // Notification message (Notification only)
+  notificationType?: string; // Notification type (Notification only)
 }
 
 // Environment variables injected into hook processes

package/src/types/index.ts

@@ -21,3 +21,10 @@ export * from "./processes.js";
 export * from "./commands.js";
 export * from "./skills.js";
 export * from "./config.js";
+export * from "./session.js";
+export * from "./environment.js";
+export * from "./configuration.js"; // New configuration management types
+export * from "./permissions.js";
+export * from "./tools.js"; // Tool parameter types
+export * from "./fileSearch.js"; // File search types
+export * from "./lsp.js";

package/src/types/lsp.ts

@@ -0,0 +1,96 @@
+/**
+ * LSP (Language Server Protocol) configuration and communication types
+ */
+
+export interface LspServerConfig {
+  command: string;
+  args?: string[];
+  extensionToLanguage: Record<string, string>;
+  transport?: "stdio" | "socket";
+  env?: Record<string, string>;
+  initializationOptions?: unknown;
+  settings?: unknown;
+  workspaceFolder?: string;
+  startupTimeout?: number;
+  shutdownTimeout?: number;
+  restartOnCrash?: boolean;
+  maxRestarts?: number;
+}
+
+export interface LspConfig {
+  [language: string]: LspServerConfig;
+}
+
+export interface LspPosition {
+  line: number;
+  character: number;
+}
+
+export interface LspRange {
+  start: LspPosition;
+  end: LspPosition;
+}
+
+export interface LspLocation {
+  uri: string;
+  range: LspRange;
+}
+
+export interface LspLocationLink {
+  originSelectionRange?: LspRange;
+  targetUri: string;
+  targetRange: LspRange;
+  targetSelectionRange?: LspRange;
+}
+
+export interface LspHover {
+  contents:
+    | string
+    | { kind: string; value: string }
+    | Array<string | { kind: string; value: string }>;
+  range?: LspRange;
+}
+
+export interface LspSymbolInformation {
+  name: string;
+  kind: number;
+  location: LspLocation;
+  containerName?: string;
+}
+
+export interface LspDocumentSymbol {
+  name: string;
+  detail?: string;
+  kind: number;
+  range: LspRange;
+  selectionRange: LspRange;
+  children?: LspDocumentSymbol[];
+}
+
+export interface LspCallHierarchyItem {
+  name: string;
+  kind: number;
+  detail?: string;
+  uri: string;
+  range: LspRange;
+  selectionRange: LspRange;
+}
+
+export interface LspCallHierarchyIncomingCall {
+  from: LspCallHierarchyItem;
+  fromRanges: LspRange[];
+}
+
+export interface LspCallHierarchyOutgoingCall {
+  to: LspCallHierarchyItem;
+  fromRanges: LspRange[];
+}
+
+export interface ILspManager {
+  execute(args: {
+    operation: string;
+    filePath: string;
+    line: number;
+    character: number;
+  }): Promise<{ success: boolean; content: string }>;
+}

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)
+  additionalFields?: Record<string, unknown>; // Additional metadata from AI responses
 }
 
 export type MessageBlock =
@@ -21,11 +23,11 @@ export type MessageBlock =
   | ErrorBlock
   | ToolBlock
   | ImageBlock
-  | DiffBlock
   | CommandOutputBlock
   | CompressBlock
   | MemoryBlock
-  | SubagentBlock;
+  | SubagentBlock
+  | ReasoningBlock;
 
 export interface TextBlock {
   type: "text";
@@ -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 {
@@ -62,16 +72,6 @@ export interface ImageBlock {
   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;
@@ -83,6 +83,7 @@ export interface CommandOutputBlock {
 export interface CompressBlock {
   type: "compress";
   content: string;
+  sessionId: string;
 }
 
 export interface MemoryBlock {
@@ -98,5 +99,11 @@ export interface SubagentBlock {
   subagentId: string;
   subagentName: string;
   status: "active" | "completed" | "error" | "aborted";
-  messages: Message[];
+  sessionId: string;
+  configuration: SubagentConfiguration;
+}
+
+export interface ReasoningBlock {
+  type: "reasoning";
+  content: string;
 }

package/src/types/permissions.ts

@@ -0,0 +1,48 @@
+/**
+ * Permission system types for Wave Agent SDK
+ * Dependencies: None
+ */
+
+/** Permission mode configuration */
+export type PermissionMode = "default" | "bypassPermissions" | "acceptEdits";
+
+/** Result of a permission check */
+export interface PermissionDecision {
+  /** Whether to allow or deny the operation */
+  behavior: "allow" | "deny";
+  /** Optional message explaining the decision (required for deny) */
+  message?: string;
+  /** Signal to change the session's permission mode */
+  newPermissionMode?: PermissionMode;
+  /** Signal to persist a new allowed rule */
+  newPermissionRule?: string;
+}
+
+/** Callback function for custom permission logic */
+export type PermissionCallback = (
+  context: ToolPermissionContext,
+) => Promise<PermissionDecision>;
+
+/** Internal context passed to PermissionManager */
+export interface ToolPermissionContext {
+  /** Name of the tool being executed */
+  toolName: string;
+  /** Current permission mode */
+  permissionMode: PermissionMode;
+  /** Custom permission callback if provided */
+  canUseToolCallback?: PermissionCallback;
+  /** Tool input parameters for better context */
+  toolInput?: Record<string, unknown>;
+}
+
+/** List of tools that require permission checks in default mode */
+export const RESTRICTED_TOOLS = [
+  "Edit",
+  "MultiEdit",
+  "Delete",
+  "Bash",
+  "Write",
+] as const;
+
+/** Type for restricted tool names */
+export type RestrictedTool = (typeof RESTRICTED_TOOLS)[number];

package/src/types/session.ts

@@ -0,0 +1,20 @@
+/**
+ * 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?, additionalFields?
+}
+
+// Session filename structure for simple filename-based metadata
+export interface SessionFilename {
+  sessionId: string;
+  sessionType: "main" | "subagent";
+}

package/src/types/skills.ts

@@ -61,6 +61,7 @@ export interface SkillManagerOptions {
   personalSkillsPath?: string;
   scanTimeout?: number;
   logger?: Logger;
+  workdir?: string;
 }
 
 export interface ParsedSkillFile {

package/src/types/tools.ts

@@ -0,0 +1,38 @@
+/**
+ * Tool parameter types for edit and write operations
+ */
+
+/**
+ * Parameters for the Write tool
+ */
+export interface WriteToolParameters {
+  file_path: string;
+  content: string;
+}
+
+/**
+ * Parameters for a single edit operation in the Edit tool
+ */
+export interface EditOperation {
+  old_string: string;
+  new_string: string;
+  replace_all?: boolean;
+}
+
+/**
+ * Parameters for the Edit tool
+ */
+export interface EditToolParameters {
+  file_path: string;
+  old_string: string;
+  new_string: string;
+  replace_all?: boolean;
+}
+
+/**
+ * Parameters for the MultiEdit tool
+ */
+export interface MultiEditToolParameters {
+  file_path: string;
+  edits: EditOperation[];
+}

package/src/utils/abortUtils.ts

@@ -0,0 +1,118 @@
+/**
+ * Utilities for safe AbortSignal listener management to prevent memory leaks
+ */
+
+/**
+ * Safely adds a one-time abort listener that automatically cleans up after firing
+ * @param signal - The AbortSignal to listen to
+ * @param callback - The function to call when aborted
+ * @returns A cleanup function to manually remove the listener if needed
+ */
+export function addOnceAbortListener(
+  signal: AbortSignal,
+  callback: () => void,
+): () => void {
+  if (signal.aborted) {
+    // Signal already aborted, call immediately
+    callback();
+    return () => {}; // No cleanup needed
+  }
+
+  const handler = () => {
+    callback();
+  };
+
+  // Use { once: true } to automatically remove listener after first call
+  signal.addEventListener("abort", handler, { once: true });
+
+  // Return cleanup function for manual removal if needed
+  return () => {
+    signal.removeEventListener("abort", handler);
+  };
+}
+
+/**
+ * Creates a Promise that rejects when the AbortSignal is aborted
+ * Uses once-only listener to prevent accumulation
+ * @param signal - The AbortSignal to listen to
+ * @param errorMessage - Optional custom error message
+ * @returns Promise that rejects on abort
+ */
+export function createAbortPromise(
+  signal: AbortSignal,
+  errorMessage: string = "Operation was aborted",
+): Promise<never> {
+  return new Promise<never>((_, reject) => {
+    if (signal.aborted) {
+      reject(new Error(errorMessage));
+      return;
+    }
+
+    // Use once-only listener to prevent accumulation
+    signal.addEventListener(
+      "abort",
+      () => {
+        reject(new Error(errorMessage));
+      },
+      { once: true },
+    );
+  });
+}
+
+/**
+ * Wrapper that manages abort signal listeners with automatic cleanup
+ * @param signal - The AbortSignal to manage
+ * @param operation - Function that sets up listeners and returns cleanup
+ * @returns Promise that resolves with the operation result
+ */
+export async function withAbortCleanup<T>(
+  signal: AbortSignal,
+  operation: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+  // Track all cleanup functions
+  const cleanups: (() => void)[] = [];
+
+  try {
+    const result = await operation(signal);
+    return result;
+  } finally {
+    // Clean up all listeners
+    cleanups.forEach((cleanup) => cleanup());
+  }
+}
+
+/**
+ * Consolidates multiple abort listeners into a single listener
+ * Useful when multiple handlers need to respond to the same abort signal
+ * @param signal - The AbortSignal to listen to
+ * @param callbacks - Array of functions to call when aborted
+ * @returns Cleanup function to remove the consolidated listener
+ */
+export function addConsolidatedAbortListener(
+  signal: AbortSignal,
+  callbacks: (() => void)[],
+): () => void {
+  if (signal.aborted) {
+    // Signal already aborted, call all callbacks immediately
+    callbacks.forEach((cb) => cb());
+    return () => {}; // No cleanup needed
+  }
+
+  const handler = () => {
+    callbacks.forEach((cb) => {
+      try {
+        cb();
+      } catch (error) {
+        console.error("Error in abort callback:", error);
+      }
+    });
+  };
+
+  // Use { once: true } to automatically remove listener after first call
+  signal.addEventListener("abort", handler, { once: true });
+
+  // Return cleanup function for manual removal if needed
+  return () => {
+    signal.removeEventListener("abort", handler);
+  };
+}