wave-agent-sdk 1.0.4 → 1.0.6

package/src/utils/subagentParser.ts

@@ -1,279 +0,0 @@
-import { readFileSync, readdirSync, statSync } from "fs";
-import { join, extname, basename } from "path";
-import { logger } from "./globalLogger.js";
-import { getBuiltinSubagentsDir } from "./configPaths.js";
-
-export interface SubagentConfiguration {
-  name: string;
-  description: string;
-  tools?: string[];
-  model?: string;
-  systemPrompt: string;
-  filePath: string;
-  scope: "project" | "user" | "builtin" | "plugin";
-  priority: number;
-  /** Plugin root directory path, set when scope is "plugin" */
-  pluginRoot?: string;
-}
-
-interface SubagentFrontmatter {
-  name?: string;
-  description?: string;
-  tools?: string[];
-  model?: string;
-}
-
-/**
- * Parse YAML frontmatter from markdown file content
- */
-function parseFrontmatter(content: string): {
-  frontmatter: SubagentFrontmatter;
-  body: string;
-} {
-  const frontmatterRegex =
-    /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n([\s\S]*)$/;
-  const match = content.match(frontmatterRegex);
-
-  if (!match) {
-    return { frontmatter: {}, body: content.trim() };
-  }
-
-  const [, yamlContent, body] = match;
-  const frontmatter = parseYamlFrontmatter(yamlContent);
-
-  return { frontmatter, body: body.trim() };
-}
-
-/**
- * Simple YAML frontmatter parser for subagent files
- */
-function parseYamlFrontmatter(yamlContent: string): SubagentFrontmatter {
-  const frontmatter: SubagentFrontmatter = {};
-
-  try {
-    const lines = yamlContent.split("\n");
-    for (const line of lines) {
-      const trimmed = line.trim();
-      if (!trimmed || trimmed.startsWith("#")) continue;
-
-      const colonIndex = trimmed.indexOf(":");
-      if (colonIndex === -1) continue;
-
-      const key = trimmed.substring(0, colonIndex).trim();
-      const value = trimmed
-        .substring(colonIndex + 1)
-        .trim()
-        .replace(/^["']|["']$/g, "");
-
-      if (key && value) {
-        // Handle array values for tools
-        if (key === "tools" && value) {
-          let arrayValue = value;
-          if (arrayValue.startsWith("[") && arrayValue.endsWith("]")) {
-            arrayValue = arrayValue.slice(1, -1);
-          }
-          frontmatter[key] = arrayValue
-            .split(",")
-            .map((s) => s.trim())
-            .filter(Boolean);
-        } else {
-          if (key === "name" || key === "description" || key === "model") {
-            frontmatter[key] = value;
-          }
-        }
-      }
-    }
-  } catch {
-    // Return empty frontmatter on parse error - validation will catch missing fields
-  }
-
-  return frontmatter;
-}
-
-/**
- * Validate subagent configuration
- */
-function validateConfiguration(
-  config: SubagentFrontmatter,
-  filePath: string,
-): void {
-  if (!config.name) {
-    throw new Error(`Missing required field 'name' in ${filePath}`);
-  }
-
-  if (!config.description) {
-    throw new Error(`Missing required field 'description' in ${filePath}`);
-  }
-
-  // Validate name pattern - allow letters (upper/lowercase), numbers, and hyphens
-  const namePattern = /^[a-zA-Z][a-zA-Z0-9-]*$/;
-  if (!namePattern.test(config.name)) {
-    throw new Error(
-      `Invalid subagent name '${config.name}' in ${filePath}. Must start with a letter and contain only letters, numbers, and hyphens.`,
-    );
-  }
-
-  // Validate model if specified - allow any non-empty string
-  if (config.model && typeof config.model !== "string") {
-    throw new Error(
-      `Invalid model '${config.model}' in ${filePath}. Must be a string.`,
-    );
-  }
-}
-
-/**
- * Parse a single subagent markdown file with optional pluginRoot support
- */
-function parseSubagentFile(
-  filePath: string,
-  scope: "project" | "user" | "builtin" | "plugin",
-  pluginRoot?: string,
-): SubagentConfiguration {
-  try {
-    const content = readFileSync(filePath, "utf-8");
-    const { frontmatter, body } = parseFrontmatter(content);
-
-    // Use filename as default name if not specified in frontmatter
-    if (!frontmatter.name) {
-      frontmatter.name = basename(filePath, extname(filePath));
-    }
-
-    validateConfiguration(frontmatter, filePath);
-
-    if (!body.trim()) {
-      throw new Error(`Empty system prompt in ${filePath}`);
-    }
-
-    let priority = 1;
-    if (scope === "user") priority = 2;
-    if (scope === "builtin") priority = 3;
-    if (scope === "plugin") priority = 2; // Same priority as user-level
-
-    let systemPrompt = body;
-
-    // Substitute ${WAVE_PLUGIN_ROOT} for plugin scope at parse time
-    if (scope === "plugin" && pluginRoot) {
-      systemPrompt = systemPrompt.replace(
-        /\$\{WAVE_PLUGIN_ROOT\}/g,
-        pluginRoot,
-      );
-    }
-
-    return {
-      name: frontmatter.name!,
-      description: frontmatter.description!,
-      tools: frontmatter.tools,
-      model: frontmatter.model,
-      systemPrompt,
-      filePath,
-      scope,
-      priority,
-      pluginRoot: scope === "plugin" ? pluginRoot : undefined,
-    };
-  } catch (error) {
-    throw new Error(
-      `Failed to parse subagent file ${filePath}: ${error instanceof Error ? error.message : String(error)}`,
-    );
-  }
-}
-
-/**
- * Parse a plugin agent markdown file.
- * Exposed as a public API for PluginLoader to use.
- */
-export function parseAgentFile(
-  filePath: string,
-  scope: "plugin",
-  pluginRoot: string,
-): SubagentConfiguration {
-  return parseSubagentFile(filePath, scope, pluginRoot);
-}
-
-/**
- * Scan directory for subagent files
- */
-function scanSubagentDirectory(
-  dirPath: string,
-  scope: "project" | "user" | "builtin",
-): SubagentConfiguration[] {
-  const configurations: SubagentConfiguration[] = [];
-
-  try {
-    const entries = readdirSync(dirPath);
-
-    for (const entry of entries) {
-      const fullPath = join(dirPath, entry);
-      const stat = statSync(fullPath);
-
-      if (stat.isFile() && extname(entry) === ".md") {
-        try {
-          const config = parseSubagentFile(fullPath, scope);
-          configurations.push(config);
-        } catch (parseError) {
-          // Log error but continue with other files
-          logger.warn(
-            `Warning: ${parseError instanceof Error ? parseError.message : String(parseError)}`,
-          );
-        }
-      }
-    }
-  } catch {
-    // Directory doesn't exist or can't be read - this is OK
-  }
-
-  return configurations;
-}
-
-/**
- * Load all subagent configurations from project and user directories, plus built-in subagents
- */
-export async function loadSubagentConfigurations(
-  workdir: string,
-): Promise<SubagentConfiguration[]> {
-  const projectWaveDir = join(workdir, ".wave", "agents");
-  const projectClaudeDir = join(workdir, ".claude", "agents");
-  const userWaveDir = join(process.env.HOME || "~", ".wave", "agents");
-  const userClaudeDir = join(process.env.HOME || "~", ".claude", "agents");
-  const builtinDir = getBuiltinSubagentsDir();
-
-  // Load configurations from all sources
-  const builtinConfigs = scanSubagentDirectory(builtinDir, "builtin");
-  const userClaudeConfigs = scanSubagentDirectory(userClaudeDir, "user");
-  const userWaveConfigs = scanSubagentDirectory(userWaveDir, "user");
-  const projectClaudeConfigs = scanSubagentDirectory(
-    projectClaudeDir,
-    "project",
-  );
-  const projectWaveConfigs = scanSubagentDirectory(projectWaveDir, "project");
-
-  // Merge configurations, with .wave taking priority over .claude
-  const configMap = new Map<string, SubagentConfiguration>();
-
-  // Merge order: builtin → userClaude → userWave → projectClaude → projectWave
-  // Later writes override earlier ones, so .wave takes priority over .claude
-  for (const config of [
-    ...builtinConfigs,
-    ...userClaudeConfigs,
-    ...userWaveConfigs,
-    ...projectClaudeConfigs,
-    ...projectWaveConfigs,
-  ]) {
-    configMap.set(config.name, config);
-  }
-
-  return Array.from(configMap.values()).sort((a, b) => {
-    if (a.priority !== b.priority) return a.priority - b.priority;
-    return a.name.localeCompare(b.name);
-  });
-}
-
-/**
- * Find subagent by exact name match
- */
-export async function findSubagentByName(
-  name: string,
-  workdir: string,
-): Promise<SubagentConfiguration | null> {
-  const configurations = await loadSubagentConfigurations(workdir);
-  return configurations.find((config) => config.name === name) || null;
-}

package/src/utils/taskReminder.ts

@@ -1,96 +0,0 @@
-import type { Message } from "../types/messaging.js";
-import type { Task } from "../types/tasks.js";
-
-export const TASK_REMINDER_CONFIG = {
-  TURNS_SINCE_WRITE: 10,
-  TURNS_BETWEEN_REMINDERS: 10,
-};
-
-const TASK_MANAGEMENT_TOOLS = new Set(["TaskCreate", "TaskUpdate"]);
-const TASK_REMINDER_MARKER = "<!-- task-reminder -->";
-
-function isQualifyingAssistantMessage(message: Message): boolean {
-  if (message.role !== "assistant") return false;
-  if (message.isMeta) return false;
-  return message.blocks.some((block) => block.type !== "reasoning");
-}
-
-export function getTaskReminderTurnCounts(messages: Message[]): {
-  turnsSinceLastTaskManagement: number;
-  turnsSinceLastReminder: number;
-} {
-  let assistantTurnCount = 0;
-  let turnsSinceLastTaskManagement: number | undefined;
-  let turnsSinceLastReminder: number | undefined;
-
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const message = messages[i];
-
-    // Check blocks for task management tools and reminder markers
-    for (const block of message.blocks) {
-      if (
-        turnsSinceLastTaskManagement === undefined &&
-        block.type === "tool" &&
-        block.name &&
-        TASK_MANAGEMENT_TOOLS.has(block.name)
-      ) {
-        turnsSinceLastTaskManagement = assistantTurnCount;
-      }
-      if (
-        turnsSinceLastReminder === undefined &&
-        block.type === "text" &&
-        block.content.includes(TASK_REMINDER_MARKER)
-      ) {
-        turnsSinceLastReminder = assistantTurnCount;
-      }
-    }
-
-    if (isQualifyingAssistantMessage(message)) {
-      assistantTurnCount++;
-    }
-  }
-
-  return {
-    turnsSinceLastTaskManagement:
-      turnsSinceLastTaskManagement ?? assistantTurnCount,
-    turnsSinceLastReminder: turnsSinceLastReminder ?? assistantTurnCount,
-  };
-}
-
-export function buildTaskReminderText(tasks: Task[]): string {
-  let text = `${TASK_REMINDER_MARKER}\n`;
-  text +=
-    "The task tools haven't been used recently. If you're working on tasks that would benefit from tracking progress, consider using TaskCreate to add new tasks and TaskUpdate to update task status (set to in_progress when starting, completed when done). Also consider cleaning up the task list if it has become stale. Only use these if relevant to the current work. This is just a gentle reminder - ignore if not applicable. Make sure that you never mention this reminder to the user";
-
-  if (tasks.length > 0) {
-    text += "\n\nHere are the existing tasks:\n";
-    for (const task of tasks) {
-      text += `#${task.id} [${task.status}] ${task.subject}\n`;
-    }
-  }
-
-  return text;
-}
-
-export function maybeInjectTaskReminder(
-  turnCounts: {
-    turnsSinceLastTaskManagement: number;
-    turnsSinceLastReminder: number;
-  },
-  tasks: Task[],
-): string | null {
-  if (
-    turnCounts.turnsSinceLastTaskManagement <
-    TASK_REMINDER_CONFIG.TURNS_SINCE_WRITE
-  ) {
-    return null;
-  }
-  if (
-    turnCounts.turnsSinceLastReminder <
-    TASK_REMINDER_CONFIG.TURNS_BETWEEN_REMINDERS
-  ) {
-    return null;
-  }
-
-  return buildTaskReminderText(tasks);
-}

package/src/utils/tokenCalculation.ts

@@ -1,43 +0,0 @@
-import type { Usage } from "../types/index.js";
-
-/**
- * Calculate comprehensive total tokens including cache-related tokens
- *
- * This function computes the true total token cost by including:
- * - Base total_tokens (prompt + completion)
- * - Cache read tokens (cost savings indicator)
- * - Cache creation tokens (cache investment)
- *
- * For accurate cost tracking with Claude models that support cache control.
- *
- * @param usage - Usage statistics from AI operation
- * @returns Comprehensive total including all cache-related tokens
- */
-export function calculateComprehensiveTotalTokens(usage: Usage): number {
-  const baseTokens = usage.total_tokens;
-  const cacheReadTokens = usage.cache_read_input_tokens || 0;
-  const cacheCreateTokens = usage.cache_creation_input_tokens || 0;
-
-  return baseTokens + cacheReadTokens + cacheCreateTokens;
-}
-
-/**
- * Extract the latest total tokens from the last message with usage data
- * Uses comprehensive calculation that includes cache tokens for accurate tracking
- *
- * @param messages - Array of messages to search
- * @returns Comprehensive total tokens from the most recent usage data, or 0 if none found
- */
-export function extractLatestTotalTokens(
-  messages: Array<{ usage?: Usage }>,
-): number {
-  // Find the last message with usage data (iterate backwards for efficiency)
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const message = messages[i];
-    if (message.usage) {
-      return calculateComprehensiveTotalTokens(message.usage);
-    }
-  }
-
-  return 0; // No usage data found
-}

package/src/utils/tokenEstimate.ts

@@ -1,34 +0,0 @@
-/**
- * CJK-aware token estimation without external dependencies.
- *
- * The naive `length / 4` heuristic under-estimates CJK text by ~4x because
- * each Chinese/Japanese/Korean character is typically 1-2 tokens, not 0.25.
- * This function separates CJK characters from other text and applies
- * different ratios:
- *
- * - CJK characters: 1 char ≈ 1 token
- * - Other characters: 4 chars ≈ 1 token (2 for JSON/JSONL/JSONC)
- *
- * The estimate intentionally leans high for CJK (safe direction for limit
- * checks — better to reject than to let oversized content through).
- */
-
-// CJK Unified Ideographs + Extension A + Hiragana + Katakana + Hangul Syllables
-const CJK_REGEX =
-  /[\u4e00-\u9fff\u3400-\u4dbf\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/g;
-
-/**
- * Estimate token count for a string, with CJK-awareness.
- *
- * @param content - The text content to estimate
- * @param ext - File extension (without dot), e.g. "ts", "json". JSON/JSONL/JSONC
- *              files use a tighter ratio (2 chars/token) for non-CJK text.
- * @returns Estimated token count
- */
-export function estimateTokens(content: string, ext?: string): number {
-  const cjkCount = (content.match(CJK_REGEX) || []).length;
-  const otherCount = content.length - cjkCount;
-  const bytesPerToken =
-    ext === "json" || ext === "jsonl" || ext === "jsonc" ? 2 : 4;
-  return Math.ceil(cjkCount + otherCount / bytesPerToken);
-}

package/src/utils/toolResultStorage.ts

@@ -1,117 +0,0 @@
-/**
- * Shared tool result persistence and truncation logic.
- *
- * When a tool result exceeds a size threshold, the full content is saved to a
- * file in /tmp/wave-tool-results/ and the model receives a <persisted-output>
- * preview with the file path so it can use the Read tool to access the full output.
- */
-
-import * as fs from "fs";
-import * as path from "path";
-import * as os from "os";
-import {
-  DEFAULT_MAX_RESULT_SIZE_CHARS,
-  PREVIEW_SIZE_BYTES,
-} from "../constants/toolLimits.js";
-import { logger } from "./globalLogger.js";
-
-const TOOL_RESULTS_DIR = path.join(os.tmpdir(), "wave-tool-results");
-
-/**
- * Get (and create if needed) the tool-results directory.
- * Uses /tmp/wave-tool-results/ for simplicity and automatic OS cleanup.
- */
-export function getToolResultsDir(): string {
-  fs.mkdirSync(TOOL_RESULTS_DIR, { recursive: true });
-  return TOOL_RESULTS_DIR;
-}
-
-/**
- * Persist full tool output to a file in the tool-results directory.
- * Returns the file path on success, or undefined on failure.
- */
-export function persistToolResult(
-  content: string,
-  prefix: string = "tool",
-): string | undefined {
-  try {
-    const dir = getToolResultsDir();
-    const id = `${prefix}_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
-    const filePath = path.join(dir, `${id}.txt`);
-    fs.writeFileSync(filePath, content, "utf8");
-    return filePath;
-  } catch (error) {
-    logger?.error("Failed to persist tool result:", error);
-    return undefined;
-  }
-}
-
-/**
- * Generate a preview from content: first `previewSize` characters with ellipsis.
- */
-export function generatePreview(
-  content: string,
-  previewSize: number = PREVIEW_SIZE_BYTES,
-): string {
-  if (content.length <= previewSize) return content;
-  return content.substring(0, previewSize) + "\n...";
-}
-
-/**
- * Build the <persisted-output> wrapper message that the model sees.
- *
- * Example output:
- * <persisted-output>
- * Output too large (150,000 characters). Full output saved to: /tmp/wave-tool-results/mcp_server_tool_12345.txt
- * Preview (first 2,048 characters):
- * {preview content}
- * ...
- * </persisted-output>
- */
-export function buildPersistedOutputMessage(
-  totalChars: number,
-  filePath: string,
-  preview: string,
-): string {
-  return [
-    "<persisted-output>",
-    `Output too large (${totalChars.toLocaleString()} characters). Full output saved to: ${filePath}`,
-    `Preview (first ${PREVIEW_SIZE_BYTES.toLocaleString()} characters):`,
-    preview,
-    "</persisted-output>",
-  ].join("\n");
-}
-
-/**
- * Process tool result: if content exceeds maxChars, persist to file and return
- * truncated content with <persisted-output> wrapper. Otherwise return unchanged.
- *
- * This is the main entry point for both MCP and bash tools.
- *
- * @param content - The tool result content
- * @param maxChars - Maximum characters before persistence kicks in (defaults to DEFAULT_MAX_RESULT_SIZE_CHARS)
- * @param prefix - File name prefix for the persisted file (e.g. "bash", "mcp")
- * @returns The content to send to the model (either original or persisted-output wrapper)
- */
-export function processToolResult(
-  content: string,
-  maxChars: number = DEFAULT_MAX_RESULT_SIZE_CHARS,
-  prefix: string = "tool",
-): string {
-  if (content.length <= maxChars) {
-    return content;
-  }
-
-  const filePath = persistToolResult(content, prefix);
-
-  if (filePath) {
-    const preview = generatePreview(content);
-    return buildPersistedOutputMessage(content.length, filePath, preview);
-  }
-
-  // Fallback: truncation only (persistence failed)
-  return (
-    content.substring(0, maxChars) +
-    "\n\n... (output truncated, failed to persist full output)"
-  );
-}

package/src/utils/worktreeSession.ts

@@ -1,26 +0,0 @@
-/**
- * Worktree session state tracking.
- *
- * The session state is stored per-agent in each session's DI container (see the
- * "WorktreeSession" container slot registered in containerSetup.ts and accessed via
- * AIManager.getWorktreeSession()/setWorktreeSession()). This keeps worktree state
- * isolated per session in stdio multi-agent mode — a process-level singleton would
- * leak state across concurrent sessions (see docs/specs/multi-agent/worktree.md FR-042).
- */
-
-export interface WorktreeSession {
-  /** The working directory the session was in before EnterWorktree */
-  originalCwd: string;
-  /** Path to the worktree directory */
-  worktreePath: string;
-  /** Git branch name for the worktree */
-  worktreeBranch: string;
-  /** User-provided or auto-generated worktree name */
-  worktreeName: string;
-  /** Whether this worktree was newly created (vs resumed existing) */
-  isNew: boolean;
-  /** The canonical git repo root */
-  repoRoot: string;
-  /** The HEAD commit of the original branch at worktree creation time */
-  originalHeadCommit?: string;
-}