wave-agent-sdk 0.7.1 → 0.8.0

package/src/tools/writeTool.ts

@@ -123,7 +123,7 @@ Usage:
             return {
               success: false,
               content: "",
-              error: `Write operation denied, reason: ${permissionResult.message || "No reason provided"}`,
+              error: `Write operation denied by user, reason: ${permissionResult.message || "No reason provided"}`,
             };
           }
         } catch {

package/src/types/agent.ts

@@ -0,0 +1,83 @@
+import type { ClientOptions } from "openai";
+import type {
+  Message,
+  Logger,
+  PermissionMode,
+  PermissionCallback,
+  ILspManager,
+  PluginConfig,
+  BackgroundTask,
+} from "./index.js";
+import type { MessageManagerCallbacks } from "../managers/messageManager.js";
+import type { BackgroundTaskManagerCallbacks } from "../managers/backgroundTaskManager.js";
+import type { McpManagerCallbacks } from "../managers/mcpManager.js";
+import type { SubagentManagerCallbacks } from "../managers/subagentManager.js";
+
+/**
+ * Configuration options for Agent instances
+ *
+ * IMPORTANT: This interface is used by both Agent constructor and Agent.create()
+ * Any changes to this interface must be compatible with both methods.
+ */
+export interface AgentOptions {
+  // Optional configuration with environment fallbacks
+  apiKey?: string;
+  baseURL?: string;
+  defaultHeaders?: Record<string, string>;
+  fetchOptions?: ClientOptions["fetchOptions"];
+  fetch?: ClientOptions["fetch"];
+  model?: string;
+  fastModel?: string;
+  maxInputTokens?: number;
+  maxTokens?: number;
+  /** Preferred language for agent communication */
+  language?: string;
+
+  // Existing options (preserved)
+  callbacks?: AgentCallbacks;
+  restoreSessionId?: string;
+  continueLastSession?: boolean;
+  logger?: Logger;
+  /**Add optional initial messages parameter for testing convenience */
+  messages?: Message[];
+  /**Working directory - if not specified, use process.cwd() */
+  workdir?: string;
+  /**Optional custom system prompt - if provided, replaces default system prompt */
+  systemPrompt?: string;
+  /**Permission mode - defaults to "default" */
+  permissionMode?: PermissionMode;
+  /**Custom permission callback */
+  canUseTool?: PermissionCallback;
+  /**Whether to use streaming mode for AI responses - defaults to true */
+  stream?: boolean;
+  /**Optional custom LSP manager - if not provided, a standalone one will be created */
+  lspManager?: ILspManager;
+  /**Optional local plugins to load */
+  plugins?: PluginConfig[];
+  /**
+   * Optional list of tool names to enable.
+   * - undefined: Enable all built-in tools and plugins (default).
+   * - []: Disable all tools.
+   * - string[]: Enable only the tools with the specified names.
+   */
+  tools?: string[];
+  /**Optional worktree name */
+  worktreeName?: string;
+  /**Whether this is a newly created worktree */
+  isNewWorktree?: boolean;
+}
+
+export interface AgentCallbacks
+  extends MessageManagerCallbacks,
+    BackgroundTaskManagerCallbacks,
+    McpManagerCallbacks,
+    SubagentManagerCallbacks {
+  onBackgroundTasksChange?: (tasks: BackgroundTask[]) => void;
+  onTasksChange?: (tasks: import("./tasks.js").Task[]) => void;
+  onPermissionModeChange?: (mode: PermissionMode) => void;
+  onSubagentLatestTotalTokensChange?: (
+    subagentId: string,
+    tokens: number,
+  ) => void;
+  onBackgroundCurrentTask?: () => void;
+}

package/src/types/commands.ts

@@ -24,12 +24,6 @@ export interface CustomSlashCommand {
   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"])
-
   // Plugin support
   pluginPath?: string; // Absolute path to the plugin root directory (only set for plugin commands)
 }

package/src/types/config.ts

@@ -15,7 +15,7 @@ export interface GatewayConfig {
 }
 
 export interface ModelConfig {
-  agentModel: string;
+  model: string;
   fastModel: string;
   maxTokens?: number;
   permissionMode?: PermissionMode;

package/src/types/hooks.ts

@@ -19,7 +19,8 @@ export type HookEvent =
   | "UserPromptSubmit"
   | "Stop"
   | "SubagentStop"
-  | "Notification";
+  | "Notification"
+  | "WorktreeCreate";
 
 // Individual hook command configuration
 export interface HookCommand {
@@ -98,6 +99,7 @@ export function isValidHookEvent(event: string): event is HookEvent {
     "Stop",
     "SubagentStop",
     "Notification",
+    "WorktreeCreate",
   ].includes(event);
 }
 
@@ -146,6 +148,7 @@ export interface HookJsonInput {
   subagent_type?: string; // Present when hook is executed by a subagent
   message?: string; // Present for Notification events
   notification_type?: string; // Present for Notification events
+  name?: string; // Present for WorktreeCreate events
 }
 
 // Extended context interface for passing additional data to hook executor
@@ -160,6 +163,7 @@ export interface ExtendedHookExecutionContext extends HookExecutionContext {
   subagentType?: string; // Subagent type when hook is executed by a subagent
   message?: string; // Notification message (Notification only)
   notificationType?: string; // Notification type (Notification only)
+  worktreeName?: string; // Worktree name (WorktreeCreate only)
 }
 
 // Environment variables injected into hook processes

package/src/types/index.ts

@@ -34,3 +34,4 @@ export * from "./marketplace.js";
 export * from "./memoryRule.js";
 export * from "./history.js";
 export * from "./tasks.js";
+export * from "./agent.js";

package/src/types/messaging.ts

@@ -23,7 +23,7 @@ export type MessageBlock =
   | ErrorBlock
   | ToolBlock
   | ImageBlock
-  | CommandOutputBlock
+  | BangBlock
   | CompressBlock
   | ReasoningBlock
   | FileHistoryBlock;
@@ -73,8 +73,8 @@ export interface ImageBlock {
   imageUrls?: string[];
 }
 
-export interface CommandOutputBlock {
-  type: "command_output";
+export interface BangBlock {
+  type: "bang";
   command: string;
   output: string;
   isRunning: boolean;

package/src/types/skills.ts

@@ -8,6 +8,12 @@ export interface SkillMetadata {
   description: string;
   type: "personal" | "project";
   skillPath: string;
+  allowedTools?: string[];
+  context?: "fork";
+  agent?: string;
+  model?: string;
+  disableModelInvocation?: boolean;
+  userInvocable?: boolean;
 }
 
 export interface Skill extends SkillMetadata {
@@ -20,6 +26,12 @@ export interface Skill extends SkillMetadata {
 export interface SkillFrontmatter {
   name: string;
   description: string;
+  "allowed-tools"?: string | string[];
+  context?: "fork";
+  agent?: string;
+  model?: string;
+  "disable-model-invocation"?: boolean | string;
+  "user-invocable"?: boolean | string;
   [key: string]: unknown;
 }
 
@@ -53,6 +65,7 @@ export interface SkillInvocationContext {
 
 export interface SkillToolArgs {
   skill_name: string;
+  args?: string;
 }
 
 export interface SkillManagerOptions {

package/src/utils/commandPathResolver.ts

@@ -1,23 +1,15 @@
 import { relative, basename } from "path";
 
 /**
- * Command path resolver utilities for nested command discovery
- * Handles conversion between file paths and command IDs with colon syntax
+ * Command path resolver utilities for command discovery
+ * Handles conversion between file paths and command IDs
  */
 
-export interface CommandIdParts {
-  namespace?: string; // e.g., "openspec" for "openspec:apply"
-  commandName: string; // e.g., "apply" for "openspec:apply"
-  isNested: boolean; // true if command has namespace
-  depth: number; // 0 for root, 1 for nested
-  segments: string[]; // Path components array
-}
-
 /**
  * Generate command ID from file path
  * @param filePath - Absolute path to markdown file
  * @param rootDir - Root commands directory path
- * @returns Command identifier string (e.g., "openspec:apply")
+ * @returns Command identifier string
  * @throws Error on invalid path structure
  */
 export function generateCommandId(filePath: string, rootDir: string): string {
@@ -42,84 +34,28 @@ export function generateCommandId(filePath: string, rootDir: string): string {
     throw new Error(`Command files must have .md extension`);
   }
 
-  segments[segments.length - 1] = basename(lastSegment, ".md");
+  const commandName = basename(lastSegment, ".md");
 
   // Handle empty filename after removing extension
-  if (segments[segments.length - 1] === "") {
+  if (commandName === "") {
     throw new Error("Command filename cannot be empty");
   }
 
-  // Validate depth (max 1 level of nesting)
-  if (segments.length > 2) {
+  // Validate depth (no nesting allowed)
+  if (segments.length > 1) {
     throw new Error(
-      `Command nesting too deep: ${relativePath}. Maximum depth is 1 level.`,
+      `Command nesting not supported: ${relativePath}. Commands must be in the root directory.`,
     );
   }
 
-  // Validate segments
-  for (const segment of segments) {
-    if (!validateSegment(segment)) {
-      throw new Error(
-        `Invalid command path segment: "${segment}" in ${relativePath}. Must match pattern /^[a-zA-Z][a-zA-Z0-9_.-]*$/`,
-      );
-    }
-  }
-
-  // Generate command ID
-  if (segments.length === 1) {
-    return segments[0]; // Flat command
-  } else {
-    return segments.join(":"); // Nested command with colon syntax
-  }
-}
-
-/**
- * Parse command ID into components
- * @param commandId - Command identifier (e.g., "openspec:apply")
- * @returns Object with namespace and command name
- * @throws Error on malformed command ID
- */
-export function parseCommandId(commandId: string): CommandIdParts {
-  // Handle null/undefined inputs
-  if (commandId == null) {
-    throw new Error("Command ID cannot be null or undefined");
-  }
-
-  if (commandId === "") {
-    throw new Error("Command ID cannot be empty");
-  }
-
-  if (!validateCommandId(commandId)) {
+  // Validate command name
+  if (!validateSegment(commandName)) {
     throw new Error(
-      `Invalid command ID format: "${commandId}". Must match pattern /^[a-zA-Z0-9_-]+(?::[a-zA-Z0-9_-]+)?$/`,
+      `Invalid command name: "${commandName}" in ${relativePath}. Must match pattern /^[a-zA-Z][a-zA-Z0-9_.-]*$/`,
     );
   }
 
-  const parts = commandId.split(":");
-
-  if (parts.length === 1) {
-    // Flat command
-    return {
-      namespace: undefined,
-      commandName: parts[0],
-      isNested: false,
-      depth: 0,
-      segments: [parts[0]],
-    };
-  } else if (parts.length === 2) {
-    // Nested command
-    return {
-      namespace: parts[0],
-      commandName: parts[1],
-      isNested: true,
-      depth: 1,
-      segments: [parts[0], parts[1]],
-    };
-  } else {
-    throw new Error(
-      `Invalid command ID format: "${commandId}". Too many colon separators.`,
-    );
-  }
+  return commandName;
 }
 
 /**
@@ -133,9 +69,8 @@ export function validateCommandId(commandId: string): boolean {
     return false;
   }
 
-  // Command ID can have multiple colons (though generateCommandId enforces max 1 level)
-  // This validates the format but doesn't enforce depth limits
-  const pattern = /^[a-zA-Z][a-zA-Z0-9_-]*(?::[a-zA-Z][a-zA-Z0-9_-]*)*$/;
+  // Command ID must be a single segment (no colons)
+  const pattern = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
   return pattern.test(commandId);
 }
 
@@ -149,41 +84,3 @@ function validateSegment(segment: string): boolean {
   const pattern = /^[a-zA-Z][a-zA-Z0-9_.-]*$/;
   return pattern.test(segment);
 }
-
-/**
- * Convert file path to command segments array
- * @param filePath - Absolute path to markdown file
- * @param rootDir - Root commands directory path
- * @returns Array of path segments
- */
-export function getCommandSegments(
-  filePath: string,
-  rootDir: string,
-): string[] {
-  const relativePath = relative(rootDir, filePath);
-  const segments = relativePath.split("/").filter((segment) => segment !== "");
-
-  // Remove .md extension from the last segment
-  const lastSegment = segments[segments.length - 1];
-  segments[segments.length - 1] = basename(lastSegment, ".md");
-
-  return segments;
-}
-
-/**
- * Get namespace from command segments
- * @param segments - Command path segments
- * @returns Namespace string or undefined for flat commands
- */
-export function getNamespace(segments: string[]): string | undefined {
-  return segments.length > 1 ? segments[0] : undefined;
-}
-
-/**
- * Get command depth from segments
- * @param segments - Command path segments
- * @returns Depth number (0 for root, 1 for nested)
- */
-export function getDepth(segments: string[]): number {
-  return Math.max(0, segments.length - 1);
-}

package/src/utils/configValidator.ts

@@ -89,20 +89,16 @@ export class ConfigValidator {
 
   /**
    * Validates model configuration (basic validation)
-   * @param agentModel - Agent model string
+   * @param model - Agent model string
    * @param fastModel - Fast model string
    * @throws ConfigurationError if invalid
    */
-  static validateModelConfig(agentModel: string, fastModel: string): void {
-    if (
-      !agentModel ||
-      typeof agentModel !== "string" ||
-      agentModel.trim() === ""
-    ) {
+  static validateModelConfig(model: string, fastModel: string): void {
+    if (!model || typeof model !== "string" || model.trim() === "") {
       throw new ConfigurationError(
         "Agent model must be a non-empty string.",
-        "agentModel",
-        agentModel,
+        "model",
+        model,
       );
     }
 

package/src/utils/containerSetup.ts

@@ -14,14 +14,14 @@ import { HookManager } from "../managers/hookManager.js";
 import { SkillManager } from "../managers/skillManager.js";
 import { SlashCommandManager } from "../managers/slashCommandManager.js";
 import { PluginManager } from "../managers/pluginManager.js";
-import { BashManager } from "../managers/bashManager.js";
+import { BangManager } from "../managers/bangManager.js";
 import { MemoryRuleManager } from "../managers/MemoryRuleManager.js";
 import { ReversionManager } from "../managers/reversionManager.js";
 import { SubagentManager } from "../managers/subagentManager.js";
 import { LiveConfigManager } from "../managers/liveConfigManager.js";
 import { ConfigurationService } from "../services/configurationService.js";
 import { ReversionService } from "../services/reversionService.js";
-import type { AgentOptions } from "../agent.js";
+import type { AgentOptions } from "../types/index.js";
 import type {
   PermissionMode,
   Usage,
@@ -41,9 +41,8 @@ export interface AgentContainerSetupOptions {
   stream: boolean;
 
   // Callbacks to Agent methods
-  onSessionIdChange: (sessionId: string) => void;
-  onTasksChange: (tasks: BackgroundTask[]) => void;
-  onSessionTasksChange: (tasks: Task[]) => void;
+  onBackgroundTasksChange: (tasks: BackgroundTask[]) => void;
+  onTasksChange: (tasks: Task[]) => void;
   onPermissionModeChange: (mode: PermissionMode) => void;
   handlePlanModeTransition: (mode: PermissionMode) => void;
   setPermissionMode: (mode: PermissionMode) => void;
@@ -66,9 +65,8 @@ export function setupAgentContainer(
     configurationService,
     systemPrompt,
     stream,
-    onSessionIdChange,
+    onBackgroundTasksChange,
     onTasksChange,
-    onSessionTasksChange,
     onPermissionModeChange,
     handlePlanModeTransition,
     setPermissionMode,
@@ -94,7 +92,12 @@ export function setupAgentContainer(
     callbacks: {
       ...callbacks,
       onSessionIdChange: (sessionId) => {
-        onSessionIdChange(sessionId);
+        const taskManager = container.get<TaskManager>("TaskManager");
+        if (taskManager) {
+          taskManager.syncWithSession().catch((error) => {
+            logger.error("Failed to sync task list with session:", error);
+          });
+        }
         callbacks.onSessionIdChange?.(sessionId);
       },
     },
@@ -111,15 +114,15 @@ export function setupAgentContainer(
   container.register("TaskManager", taskManager);
   taskManager.on("tasksChange", async () => {
     const tasks = await taskManager.listTasks();
-    onSessionTasksChange(tasks);
+    onTasksChange(tasks);
   });
 
   const backgroundTaskManager = new BackgroundTaskManager(container, {
     callbacks: {
       ...callbacks,
-      onTasksChange: (tasks) => {
-        onTasksChange(tasks);
-        callbacks.onTasksChange?.(tasks);
+      onBackgroundTasksChange: (tasks) => {
+        onBackgroundTasksChange(tasks);
+        callbacks.onBackgroundTasksChange?.(tasks);
       },
     },
     workdir,
@@ -272,8 +275,8 @@ export function setupAgentContainer(
   const pluginManager = new PluginManager(container, { workdir });
   container.register("PluginManager", pluginManager);
 
-  const bashManager = new BashManager(container, { workdir });
-  container.register("BashManager", bashManager);
+  const bangManager = new BangManager(container, { workdir });
+  container.register("BangManager", bangManager);
 
   return container;
 }

package/src/utils/customCommands.ts

@@ -3,12 +3,7 @@ import { join, extname, basename } from "path";
 import { homedir } from "os";
 import type { CustomSlashCommand } from "../types/index.js";
 import { parseMarkdownFile } from "./markdownParser.js";
-import {
-  generateCommandId,
-  getCommandSegments,
-  getNamespace,
-  getDepth,
-} from "./commandPathResolver.js";
+import { generateCommandId } from "./commandPathResolver.js";
 import { logger } from "./globalLogger.js";
 
 /**
@@ -26,104 +21,46 @@ export function getUserCommandsDir(): string {
 }
 
 /**
- * Scan a directory for markdown command files with nested directory support
+ * Scan a directory for markdown command files (flat structure only)
  * @param dirPath - Root commands directory path
- * @param maxDepth - Maximum nesting depth to scan (default: 1)
  */
-export function scanCommandsDirectory(
-  dirPath: string,
-  maxDepth: number = 1,
-): CustomSlashCommand[] {
+export function scanCommandsDirectory(dirPath: string): CustomSlashCommand[] {
   if (!existsSync(dirPath)) {
     return [];
   }
 
-  return scanCommandsDirectoryRecursive(dirPath, dirPath, 0, maxDepth);
-}
-
-/**
- * Recursively scan directory for commands with depth control
- * @param currentPath - Current directory being scanned
- * @param rootPath - Root commands directory (for relative path calculation)
- * @param currentDepth - Current nesting depth
- * @param maxDepth - Maximum allowed depth
- */
-function scanCommandsDirectoryRecursive(
-  currentPath: string,
-  rootPath: string,
-  currentDepth: number,
-  maxDepth: number,
-): CustomSlashCommand[] {
   const commands: CustomSlashCommand[] = [];
 
   try {
-    const entries = readdirSync(currentPath);
+    const entries = readdirSync(dirPath);
 
     for (const entryName of entries) {
-      const fullPath = join(currentPath, entryName);
-
-      let isDirectory = false;
-      let isFile = false;
+      const fullPath = join(dirPath, entryName);
 
       try {
         const stats = statSync(fullPath);
-        isDirectory = stats.isDirectory();
-        isFile = stats.isFile();
-      } catch (error) {
-        // Skip entries that cannot be stat'd
-        logger.warn(`Cannot access ${fullPath}:`, error);
-        continue;
-      }
-
-      if (isDirectory) {
-        // Skip subdirectories if we're at max depth
-        if (currentDepth >= maxDepth) {
-          logger.warn(
-            `Skipping directory ${fullPath}: exceeds maximum nesting depth of ${maxDepth}`,
-          );
+        if (!stats.isFile() || extname(entryName) !== ".md") {
           continue;
         }
 
-        // Recursively scan subdirectory
-        const nestedCommands = scanCommandsDirectoryRecursive(
-          fullPath,
-          rootPath,
-          currentDepth + 1,
-          maxDepth,
-        );
-        commands.push(...nestedCommands);
-      } else if (isFile && extname(entryName) === ".md") {
         // Process markdown file
-        try {
-          const commandId = generateCommandId(fullPath, rootPath);
-          const segments = getCommandSegments(fullPath, rootPath);
-          const namespace = getNamespace(segments);
-          const depth = getDepth(segments);
-
-          const { content, config } = parseMarkdownFile(fullPath);
-
-          commands.push({
-            id: commandId,
-            name: basename(entryName, ".md"),
-            description: config?.description,
-            filePath: fullPath,
-            content,
-            config,
-
-            // Nested command metadata
-            namespace,
-            isNested: depth > 0,
-            depth,
-            segments,
-          });
-        } catch (error) {
-          logger.warn(`Failed to load custom command from ${fullPath}:`, error);
-        }
+        const commandId = generateCommandId(fullPath, dirPath);
+        const { content, config } = parseMarkdownFile(fullPath);
+
+        commands.push({
+          id: commandId,
+          name: basename(entryName, ".md"),
+          description: config?.description,
+          filePath: fullPath,
+          content,
+          config,
+        });
+      } catch (error) {
+        logger.warn(`Failed to load custom command from ${fullPath}:`, error);
       }
-      // Skip non-markdown files silently
     }
   } catch (error) {
-    logger.warn(`Failed to scan commands directory ${currentPath}:`, error);
+    logger.warn(`Failed to scan commands directory ${dirPath}:`, error);
   }
 
   return commands;