sudocode 1.1.20 → 1.1.22

package/node_modules/@sudocode-ai/local-server/dist/services/narration-service.js

@@ -1,749 +0,0 @@
-/**
- * Narration Service
- *
- * Converts execution events (NormalizedEntry) into spoken narration text.
- * Summarizes agent actions for voice feedback during execution.
- *
- * @module services/narration-service
- */
-/**
- * Default narration configuration
- */
-const DEFAULT_CONFIG = {
-    enabled: false,
-    // 1000 chars allows most messages to be read in full
-    // TTS handles longer text fine, and users expect full messages
-    maxAssistantMessageLength: 1000,
-    maxCommandLength: 50,
-    includeFilePaths: true,
-    narrateToolResults: false,
-    narrateToolUse: true,
-    narrateAssistantMessages: true,
-    narrateSpeakOnly: false,
-};
-/**
- * NarrationService
- *
- * Transforms NormalizedEntry execution events into human-readable narration
- * suitable for text-to-speech output.
- *
- * Narration rules:
- * | Event | Narration |
- * |-------|-----------|
- * | tool_use: Read | "Reading [filename]" |
- * | tool_use: Edit | "Editing [filename]" |
- * | tool_use: Write | "Writing [filename]" |
- * | tool_use: Bash | "Running [command summary]" |
- * | tool_use: Grep | "Searching for [pattern]" |
- * | tool_use: Glob | "Finding files matching [pattern]" |
- * | assistant (short) | Speak directly |
- * | assistant (long) | Summarize to ~2 sentences |
- * | error | "Error: [summary]" |
- * | result | "Done. [summary]" |
- *
- * @example
- * ```typescript
- * const service = new NarrationService();
- *
- * for await (const entry of executionStream) {
- *   const narration = service.summarizeForVoice(entry);
- *   if (narration) {
- *     // Emit voice narration event
- *     emit({
- *       type: 'voice_narration',
- *       executionId: 'exec-123',
- *       ...narration
- *     });
- *   }
- * }
- * ```
- */
-export class NarrationService {
-    config;
-    constructor(config) {
-        this.config = { ...DEFAULT_CONFIG, ...config };
-    }
-    /**
-     * Convert an execution event to a voice narration event
-     *
-     * @param entry - The normalized entry from agent execution
-     * @returns NarrationResult if the event should be narrated, null otherwise
-     */
-    summarizeForVoice(entry) {
-        // If narrateSpeakOnly is enabled, only narrate explicit speak tool calls
-        if (this.config.narrateSpeakOnly) {
-            if (entry.type.kind !== "tool_use") {
-                return null;
-            }
-            const toolName = entry.type.tool.toolName.toLowerCase();
-            // TODO: Filter for sudocode MCP?
-            if (toolName !== "speak") {
-                return null;
-            }
-            // Fall through to describeToolUse for speak tool
-        }
-        switch (entry.type.kind) {
-            case "tool_use":
-                return this.describeToolUse(entry);
-            case "assistant_message":
-                // Skip if assistant message narration is disabled
-                if (!this.config.narrateAssistantMessages) {
-                    return null;
-                }
-                return this.summarizeAssistantMessage(entry.content);
-            case "error":
-                return this.summarizeError(entry);
-            case "thinking":
-                // Skip thinking events - internal reasoning shouldn't be narrated
-                return null;
-            case "system_message":
-                // Skip system messages - they're not user-facing
-                return null;
-            case "user_message":
-                // Skip user messages - the user knows what they said
-                return null;
-            default:
-                return null;
-        }
-    }
-    /**
-     * Create a full VoiceNarrationEvent with execution ID
-     *
-     * @param entry - The normalized entry from agent execution
-     * @param executionId - The execution ID to associate with the event
-     * @returns VoiceNarrationEvent if the event should be narrated, null otherwise
-     */
-    createNarrationEvent(entry, executionId) {
-        const result = this.summarizeForVoice(entry);
-        if (!result)
-            return null;
-        return {
-            type: "voice_narration",
-            executionId,
-            text: result.text,
-            category: result.category,
-            priority: result.priority,
-        };
-    }
-    /**
-     * Describe a tool use event in natural language
-     */
-    describeToolUse(entry) {
-        if (entry.type.kind !== "tool_use")
-            return null;
-        const tool = entry.type.tool;
-        const toolName = tool.toolName.toLowerCase();
-        // If narrateToolUse is disabled, only allow 'speak' tool through
-        if (!this.config.narrateToolUse && toolName !== "speak") {
-            return null;
-        }
-        // Only narrate the start of tool execution (running status)
-        // or completed tools if configured to narrate results
-        if (tool.status !== "running" && !this.config.narrateToolResults) {
-            return null;
-        }
-        // If tool completed and we should narrate results
-        if (this.config.narrateToolResults &&
-            (tool.status === "success" || tool.status === "failed")) {
-            return this.describeToolResult(tool);
-        }
-        // Special handling for 'speak' tool - extract text and priority from args
-        if (toolName === "speak") {
-            const args = tool.action.kind === "tool"
-                ? tool.action.args
-                : {};
-            const text = args.text;
-            if (!text)
-                return null;
-            const priority = args.priority || "normal";
-            return {
-                text,
-                category: "status",
-                priority,
-            };
-        }
-        // Describe the tool action starting
-        const text = this.describeToolAction(tool.toolName, tool.action);
-        if (!text)
-            return null;
-        return {
-            text,
-            category: "progress",
-            priority: "normal",
-        };
-    }
-    /**
-     * Generate narration text for a specific tool action
-     */
-    describeToolAction(toolName, action) {
-        switch (action.kind) {
-            case "file_read":
-                return `Reading ${this.formatPath(action.path)}`;
-            case "file_write":
-                return `Writing ${this.formatPath(action.path)}`;
-            case "file_edit":
-                return `Editing ${this.formatPath(action.path)}`;
-            case "command_run":
-                return `Running ${this.formatCommand(action.command)}`;
-            case "search":
-                return `Searching for ${this.truncate(action.query, 30)}`;
-            case "tool":
-                // Generic tool - describe based on tool name
-                return this.describeGenericTool(action.toolName, action.args || {});
-            default:
-                // Unknown action type - use tool name
-                return `Using ${toolName}`;
-        }
-    }
-    /**
-     * Describe a generic tool use
-     */
-    describeGenericTool(toolName, args) {
-        const normalizedName = toolName.toLowerCase();
-        // Handle common tool names
-        switch (normalizedName) {
-            case "read":
-                if (args.file_path || args.path) {
-                    return `Reading ${this.formatPath(String(args.file_path || args.path))}`;
-                }
-                return "Reading a file";
-            case "write":
-                if (args.file_path || args.path) {
-                    return `Writing ${this.formatPath(String(args.file_path || args.path))}`;
-                }
-                return "Writing a file";
-            case "edit":
-                if (args.file_path || args.path) {
-                    return `Editing ${this.formatPath(String(args.file_path || args.path))}`;
-                }
-                return "Editing a file";
-            case "bash":
-                if (args.command) {
-                    return `Running ${this.formatCommand(String(args.command))}`;
-                }
-                return "Running a command";
-            case "grep":
-                if (args.pattern) {
-                    return `Searching for ${this.truncate(String(args.pattern), 30)}`;
-                }
-                return "Searching code";
-            case "glob":
-                if (args.pattern) {
-                    return `Finding files matching ${this.truncate(String(args.pattern), 30)}`;
-                }
-                return "Finding files";
-            case "task":
-                return "Starting a background task";
-            case "webfetch":
-            case "web_fetch":
-                if (args.url) {
-                    return `Fetching ${this.formatUrl(String(args.url))}`;
-                }
-                return "Fetching from the web";
-            case "websearch":
-            case "web_search":
-                if (args.query) {
-                    return `Searching the web for ${this.truncate(String(args.query), 30)}`;
-                }
-                return "Searching the web";
-            case "speak":
-                // Agent explicitly wants to speak this text - return as-is
-                if (args.text) {
-                    return String(args.text);
-                }
-                return null;
-            default:
-                return `Using ${toolName}`;
-        }
-    }
-    /**
-     * Describe a tool result (for when narrateToolResults is enabled)
-     */
-    describeToolResult(tool) {
-        if (tool.status === "failed" || !tool.result?.success) {
-            const errorMsg = tool.result?.error || "unknown error";
-            return {
-                text: `${tool.toolName} failed: ${this.truncate(errorMsg, 50)}`,
-                category: "error",
-                priority: "high",
-            };
-        }
-        return {
-            text: `${tool.toolName} completed successfully`,
-            category: "progress",
-            priority: "low",
-        };
-    }
-    /**
-     * Summarize an assistant message for voice narration
-     */
-    summarizeAssistantMessage(content) {
-        if (!content || content.trim().length === 0) {
-            return null;
-        }
-        const trimmed = content.trim();
-        // If message is short enough, use it directly
-        if (trimmed.length <= this.config.maxAssistantMessageLength) {
-            return {
-                text: trimmed,
-                category: "status",
-                priority: "normal",
-            };
-        }
-        // For longer messages, extract key sentences
-        const summarized = this.extractKeySentences(trimmed);
-        return {
-            text: summarized,
-            category: "status",
-            priority: "normal",
-        };
-    }
-    /**
-     * Extract key sentences from a longer text
-     *
-     * Strategy:
-     * 1. Split into sentences
-     * 2. Take first 1-2 sentences that are meaningful
-     * 3. Skip sentences that are just formatting or headers
-     */
-    extractKeySentences(text) {
-        // Split on sentence boundaries
-        const sentencePattern = /[.!?]+\s+|[\n\r]+/;
-        const sentences = text.split(sentencePattern).filter((s) => {
-            const trimmed = s.trim();
-            // Skip empty sentences, markdown headers, code blocks, etc.
-            return (trimmed.length > 10 &&
-                !trimmed.startsWith("#") &&
-                !trimmed.startsWith("```") &&
-                !trimmed.startsWith("|") && // tables
-                !trimmed.match(/^[-*]\s/) // bullet points
-            );
-        });
-        if (sentences.length === 0) {
-            // Fall back to truncating the original text
-            return this.truncate(text, this.config.maxAssistantMessageLength);
-        }
-        // Take first 1-2 sentences
-        const firstSentence = sentences[0].trim();
-        if (sentences.length === 1 || firstSentence.length > 80) {
-            return this.truncate(firstSentence, this.config.maxAssistantMessageLength);
-        }
-        const secondSentence = sentences[1]?.trim();
-        if (secondSentence) {
-            const combined = `${firstSentence}. ${secondSentence}`;
-            if (combined.length <= this.config.maxAssistantMessageLength + 20) {
-                return combined;
-            }
-        }
-        return firstSentence;
-    }
-    /**
-     * Summarize an error event
-     */
-    summarizeError(entry) {
-        if (entry.type.kind !== "error") {
-            return {
-                text: "An error occurred",
-                category: "error",
-                priority: "high",
-            };
-        }
-        const error = entry.type.error;
-        const message = error.message || "An unknown error occurred";
-        return {
-            text: `Error: ${this.truncate(message, 80)}`,
-            category: "error",
-            priority: "high",
-        };
-    }
-    /**
-     * Format a file path for narration
-     *
-     * Extracts just the filename or last path component for brevity.
-     */
-    formatPath(path) {
-        if (!this.config.includeFilePaths) {
-            return "a file";
-        }
-        // Extract filename from path
-        const parts = path.split(/[/\\]/);
-        const filename = parts[parts.length - 1];
-        // If path has directory context, include parent
-        if (parts.length > 1) {
-            const parent = parts[parts.length - 2];
-            if (parent && parent !== "." && parent !== "..") {
-                return `${parent}/${filename}`;
-            }
-        }
-        return filename;
-    }
-    /**
-     * Format a command for narration
-     *
-     * Truncates long commands and extracts the main command.
-     */
-    formatCommand(command) {
-        const trimmed = command.trim();
-        // Extract first part (the actual command)
-        const firstWord = trimmed.split(/\s+/)[0];
-        // For common commands, provide more context
-        const commonCommands = ["npm", "yarn", "pnpm", "git", "docker", "make"];
-        if (commonCommands.includes(firstWord)) {
-            // Include the subcommand for these
-            const parts = trimmed.split(/\s+/);
-            if (parts.length >= 2) {
-                const subcommand = `${parts[0]} ${parts[1]}`;
-                if (subcommand.length <= this.config.maxCommandLength) {
-                    return subcommand;
-                }
-            }
-        }
-        return this.truncate(trimmed, this.config.maxCommandLength);
-    }
-    /**
-     * Format a URL for narration
-     */
-    formatUrl(url) {
-        try {
-            const parsed = new URL(url);
-            // Return just the hostname
-            return parsed.hostname;
-        }
-        catch {
-            return this.truncate(url, 30);
-        }
-    }
-    /**
-     * Truncate text to a maximum length
-     */
-    truncate(text, maxLength) {
-        if (text.length <= maxLength) {
-            return text;
-        }
-        return text.slice(0, maxLength - 3) + "...";
-    }
-    /**
-     * Update the narration configuration
-     */
-    updateConfig(config) {
-        this.config = { ...this.config, ...config };
-    }
-    /**
-     * Get the current configuration
-     */
-    getConfig() {
-        return { ...this.config };
-    }
-}
-/**
- * Default rate limiter configuration
- */
-const DEFAULT_RATE_LIMITER_CONFIG = {
-    // Low interval - client handles TTS queuing, server just prevents rapid-fire bursts
-    minIntervalMs: 100,
-    maxQueueSize: 10,
-    coalesceToolCalls: true,
-    coalesceWindowMs: 500,
-};
-/**
- * NarrationRateLimiter
- *
- * Limits narration event emissions to prevent overwhelming the TTS system.
- *
- * Rate limiting rules:
- * - Don't emit narration more than once per second
- * - Coalesce rapid tool calls into summary ("Reading 3 files...")
- * - Skip low-priority narrations if queue is building up
- *
- * @example
- * ```typescript
- * const limiter = new NarrationRateLimiter();
- *
- * for await (const entry of executionStream) {
- *   const narration = narrationService.summarizeForVoice(entry);
- *   if (narration) {
- *     const result = limiter.submit(narration);
- *     if (result) {
- *       // Emit the narration event
- *       broadcastVoiceNarration(projectId, executionId, result);
- *     }
- *   }
- * }
- *
- * // At end of execution, flush any pending narrations
- * const final = limiter.flush();
- * if (final) {
- *   broadcastVoiceNarration(projectId, executionId, final);
- * }
- * ```
- */
-export class NarrationRateLimiter {
-    config;
-    lastEmitTime = 0;
-    pendingQueue = [];
-    coalescingToolCalls = [];
-    lastToolCallTime = 0;
-    constructor(config) {
-        this.config = { ...DEFAULT_RATE_LIMITER_CONFIG, ...config };
-    }
-    /**
-     * Submit a narration for potential emission
-     *
-     * Returns the narration to emit immediately, or null if rate limited.
-     * The narration may be modified (e.g., coalesced tool calls).
-     *
-     * @param narration - The narration result to submit
-     * @returns The narration to emit, or null if rate limited
-     */
-    submit(narration) {
-        const now = Date.now();
-        // Check if this is a tool call that should be coalesced
-        if (this.config.coalesceToolCalls && narration.category === "progress") {
-            const coalesced = this.tryCoalesceToolCall(narration, now);
-            if (coalesced === "pending") {
-                // Tool call was added to coalescing queue, nothing to emit yet
-                return null;
-            }
-            else if (coalesced) {
-                // Coalesced result ready to emit
-                narration = coalesced;
-            }
-        }
-        // Check rate limit
-        const timeSinceLastEmit = now - this.lastEmitTime;
-        if (timeSinceLastEmit < this.config.minIntervalMs) {
-            // Rate limited - queue or skip based on priority
-            return this.handleRateLimited(narration, now);
-        }
-        // Can emit now - but first check if we have pending high-priority items
-        const pending = this.popHighestPriority();
-        if (pending) {
-            // Emit pending item first, queue current
-            this.pendingQueue.push({ narration, timestamp: now });
-            this.lastEmitTime = now;
-            return pending;
-        }
-        // Emit current narration
-        this.lastEmitTime = now;
-        return narration;
-    }
-    /**
-     * Flush any pending narrations
-     *
-     * Call this at the end of an execution to emit any remaining narrations.
-     *
-     * @returns The highest priority pending narration, or null if none
-     */
-    flush() {
-        // First, flush any coalescing tool calls
-        const coalescedResult = this.flushCoalescing();
-        if (coalescedResult) {
-            return coalescedResult;
-        }
-        // Then return highest priority pending item
-        return this.popHighestPriority();
-    }
-    /**
-     * Check if there are any pending narrations
-     */
-    hasPending() {
-        return this.pendingQueue.length > 0 || this.coalescingToolCalls.length > 0;
-    }
-    /**
-     * Reset the rate limiter state
-     */
-    reset() {
-        this.lastEmitTime = 0;
-        this.pendingQueue = [];
-        this.coalescingToolCalls = [];
-        this.lastToolCallTime = 0;
-    }
-    /**
-     * Try to coalesce tool calls into a summary
-     *
-     * @returns "pending" if added to queue, NarrationResult if ready to emit, null if not a coalesceable call
-     */
-    tryCoalesceToolCall(narration, now) {
-        const text = narration.text;
-        // Check if this is a file/search operation that can be coalesced
-        const fileReadMatch = text.match(/^Reading\s+(.+)$/);
-        const fileEditMatch = text.match(/^Editing\s+(.+)$/);
-        const searchMatch = text.match(/^Searching\s+(.+)$/);
-        let action = null;
-        if (fileReadMatch)
-            action = "Reading";
-        else if (fileEditMatch)
-            action = "Editing";
-        else if (searchMatch)
-            action = "Searching";
-        if (!action) {
-            // Not a coalesceable tool call, flush any pending and return null
-            return this.flushCoalescing();
-        }
-        // Check if within coalescing window
-        if (this.coalescingToolCalls.length > 0 &&
-            now - this.lastToolCallTime > this.config.coalesceWindowMs) {
-            // Window expired, flush previous and start new
-            const flushed = this.flushCoalescing();
-            this.coalescingToolCalls = [{ action, count: 1 }];
-            this.lastToolCallTime = now;
-            if (flushed) {
-                // Return flushed result, current is queued
-                return flushed;
-            }
-            return "pending";
-        }
-        // Add to coalescing queue
-        const existing = this.coalescingToolCalls.find((c) => c.action === action);
-        if (existing) {
-            existing.count++;
-        }
-        else {
-            this.coalescingToolCalls.push({ action, count: 1 });
-        }
-        this.lastToolCallTime = now;
-        return "pending";
-    }
-    /**
-     * Flush coalescing queue into a summary narration
-     */
-    flushCoalescing() {
-        if (this.coalescingToolCalls.length === 0) {
-            return null;
-        }
-        const calls = this.coalescingToolCalls;
-        this.coalescingToolCalls = [];
-        this.lastToolCallTime = 0;
-        // Single action
-        if (calls.length === 1) {
-            const { action, count } = calls[0];
-            if (count === 1) {
-                // Just one call, no need to summarize
-                return null;
-            }
-            const fileWord = count === 1 ? "file" : "files";
-            return {
-                text: `${action} ${count} ${fileWord}`,
-                category: "progress",
-                priority: "normal",
-            };
-        }
-        // Multiple actions - create combined summary
-        const parts = calls.map(({ action, count }) => {
-            const fileWord = count === 1 ? "file" : "files";
-            return `${action.toLowerCase()} ${count} ${fileWord}`;
-        });
-        return {
-            text: parts.join(", "),
-            category: "progress",
-            priority: "normal",
-        };
-    }
-    /**
-     * Handle a rate-limited narration
-     *
-     * Queues high priority narrations, skips low priority if queue is full.
-     */
-    handleRateLimited(narration, now) {
-        // Skip low priority if queue is building up
-        if (narration.priority === "low" &&
-            this.pendingQueue.length >= this.config.maxQueueSize) {
-            return null;
-        }
-        // Queue the narration
-        this.pendingQueue.push({ narration, timestamp: now });
-        // Prune old low-priority items if queue is too large
-        while (this.pendingQueue.length > this.config.maxQueueSize) {
-            const lowPriorityIndex = this.pendingQueue.findIndex((p) => p.narration.priority === "low");
-            if (lowPriorityIndex >= 0) {
-                this.pendingQueue.splice(lowPriorityIndex, 1);
-            }
-            else {
-                // No low priority items, remove oldest
-                this.pendingQueue.shift();
-            }
-        }
-        return null;
-    }
-    /**
-     * Pop the highest priority pending narration
-     */
-    popHighestPriority() {
-        if (this.pendingQueue.length === 0) {
-            return null;
-        }
-        // Priority order: high > normal > low
-        const priorityOrder = { high: 0, normal: 1, low: 2 };
-        // Find highest priority
-        let bestIndex = 0;
-        let bestPriority = priorityOrder[this.pendingQueue[0].narration.priority];
-        for (let i = 1; i < this.pendingQueue.length; i++) {
-            const priority = priorityOrder[this.pendingQueue[i].narration.priority];
-            if (priority < bestPriority) {
-                bestIndex = i;
-                bestPriority = priority;
-            }
-        }
-        // Remove and return
-        const [item] = this.pendingQueue.splice(bestIndex, 1);
-        return item.narration;
-    }
-}
-/**
- * Get narration configuration from voice settings config.
- *
- * @param voiceConfig - Optional narration settings from project config.json
- */
-export function getNarrationConfig(voiceConfig) {
-    const config = {};
-    if (voiceConfig?.narration?.narrateToolUse !== undefined) {
-        config.narrateToolUse = voiceConfig.narration.narrateToolUse;
-    }
-    if (voiceConfig?.narration?.narrateToolResults !== undefined) {
-        config.narrateToolResults = voiceConfig.narration.narrateToolResults;
-    }
-    if (voiceConfig?.narration?.narrateAssistantMessages !== undefined) {
-        config.narrateAssistantMessages =
-            voiceConfig.narration.narrateAssistantMessages;
-    }
-    if (voiceConfig?.narration?.narrateSpeakOnly !== undefined) {
-        config.narrateSpeakOnly = voiceConfig.narration.narrateSpeakOnly;
-    }
-    return config;
-}
-/**
- * Global narration service instance
- * Lazy-initialized on first use
- */
-let narrationServiceInstance = null;
-/**
- * Get or create the global narration service instance
- *
- * Configuration priority (highest to lowest):
- * 1. config parameter (explicit override)
- * 2. voiceConfig (from project config.json)
- * 3. Environment variables (backwards compatibility)
- * 4. Default values
- *
- * @param config - Optional configuration override (takes precedence over everything)
- * @param voiceConfig - Optional voice settings from project config.json
- * @returns The narration service instance
- */
-export function getNarrationService(config, voiceConfig) {
-    if (!narrationServiceInstance) {
-        // Merge: voiceConfig/env < provided config
-        const baseConfig = getNarrationConfig(voiceConfig);
-        narrationServiceInstance = new NarrationService({
-            ...baseConfig,
-            ...config,
-        });
-    }
-    return narrationServiceInstance;
-}
-/**
- * Reset the global narration service instance (for testing)
- */
-export function resetNarrationService() {
-    narrationServiceInstance = null;
-}
-//# sourceMappingURL=narration-service.js.map