@nexus-cortex/executors 4.26.0

package/dist/implementations/extensions/SlashCommandTool.js

@@ -0,0 +1,315 @@
+/**
+ * SlashCommand Tool - Execute custom slash commands from .cortex/commands/
+ *
+ * Loads and executes custom commands defined in Markdown files with YAML frontmatter.
+ * Supports argument substitution using $1, $2, etc.
+ *
+ * Command Format (.md files):
+ * ```markdown
+ * ---
+ * description: Command description
+ * argument-hint: [arg1] [arg2]
+ * ---
+ *
+ * Command body with $1 and $2 placeholders
+ * ```
+ */
+import { BaseTool } from '../../base/index.js';
+import { promises as fs } from 'node:fs';
+import { join, basename, extname } from 'node:path';
+import { glob } from 'glob';
+/**
+ * SlashCommand Tool Executor
+ *
+ * Executes custom slash commands from .cortex/commands/ directory.
+ * Commands are defined in Markdown files with YAML frontmatter.
+ *
+ * Example command file (.cortex/commands/review-pr.md):
+ * ```markdown
+ * ---
+ * description: Review a pull request
+ * argument-hint: [pr-number]
+ * ---
+ *
+ * Review pull request #$1
+ *
+ * Instructions:
+ * 1. Fetch PR details from GitHub
+ * 2. Analyze the code changes
+ * 3. Provide feedback
+ * ```
+ *
+ * Usage: SlashCommand({ command: "/review-pr 123" })
+ */
+export class SlashCommandToolExecutor extends BaseTool {
+    commandsCache = null;
+    commandsDir;
+    constructor(config) {
+        super('SlashCommand', 'SlashCommand', 'Execute custom slash commands from .cortex/commands/', {
+            type: 'object',
+            properties: {
+                command: {
+                    type: 'string',
+                    description: 'The slash command to execute with its arguments (e.g., "/review-pr 123")',
+                },
+            },
+            required: ['command'],
+        });
+        this.commandsDir = join(config.workingDirectory, '.cortex', 'commands');
+    }
+    validateToolParams(params) {
+        if (!params.command || typeof params.command !== 'string') {
+            return 'command must be a non-empty string';
+        }
+        if (!params.command.startsWith('/')) {
+            return 'command must start with a forward slash (/)';
+        }
+        if (params.command.trim() === '/') {
+            return 'command name cannot be empty';
+        }
+        return null;
+    }
+    getDescription(params) {
+        const commandName = this.parseCommandName(params.command);
+        return `Executing slash command: ${commandName}`;
+    }
+    async execute(params, signal, updateOutput) {
+        const startTime = Date.now();
+        try {
+            // Validate parameters
+            const validationError = this.validateToolParams(params);
+            if (validationError) {
+                return {
+                    ...this.createErrorResult(validationError),
+                    metadata: { executionTime: Date.now() - startTime },
+                };
+            }
+            // Parse command and arguments
+            const { commandName, args } = this.parseCommand(params.command);
+            // Load command definition
+            const commandDef = await this.loadCommand(commandName, signal);
+            if (!commandDef) {
+                return {
+                    ...this.createErrorResult(`Command '${commandName}' not found in ${this.commandsDir}\n\n` +
+                        `Available commands: ${await this.getAvailableCommands()}`),
+                    metadata: {
+                        executionTime: Date.now() - startTime,
+                        commandName,
+                    },
+                };
+            }
+            // Substitute arguments in command body
+            const expandedCommand = this.substituteArguments(commandDef.body, args);
+            // Return the expanded command as output
+            const output = this.formatCommandOutput(commandName, commandDef, expandedCommand, args);
+            return {
+                ...this.createSuccessResult(output),
+                metadata: {
+                    executionTime: Date.now() - startTime,
+                    commandName,
+                    argumentCount: args.length,
+                    description: commandDef.description,
+                },
+            };
+        }
+        catch (error) {
+            if (signal.aborted) {
+                return {
+                    ...this.createErrorResult('Command execution was cancelled'),
+                    metadata: { executionTime: Date.now() - startTime },
+                };
+            }
+            return {
+                ...this.createErrorResult(`Error executing slash command: ${error.message || String(error)}`),
+                metadata: {
+                    executionTime: Date.now() - startTime,
+                    error: error.message || String(error),
+                },
+            };
+        }
+    }
+    /**
+     * Parse command string into name and arguments
+     * Example: "/review-pr 123 --verbose" → { commandName: "review-pr", args: ["123", "--verbose"] }
+     */
+    parseCommand(command) {
+        const trimmed = command.trim();
+        const parts = trimmed.split(/\s+/).filter(Boolean);
+        const commandName = parts[0] ? parts[0].slice(1) : ''; // Remove leading /
+        const args = parts.slice(1);
+        return { commandName, args };
+    }
+    /**
+     * Parse just the command name (for display purposes)
+     */
+    parseCommandName(command) {
+        return this.parseCommand(command).commandName;
+    }
+    /**
+     * Load command definition from .cortex/commands/ directory
+     * Supports recursive directory structure
+     */
+    async loadCommand(commandName, signal) {
+        // Load all commands if not cached
+        if (!this.commandsCache) {
+            await this.loadAllCommands(signal);
+        }
+        if (!this.commandsCache) {
+            return null;
+        }
+        return this.commandsCache.get(commandName) || null;
+    }
+    /**
+     * Load all command definitions from .cortex/commands/
+     */
+    async loadAllCommands(signal) {
+        this.commandsCache = new Map();
+        try {
+            // Check if commands directory exists
+            try {
+                await fs.access(this.commandsDir);
+            }
+            catch {
+                // Directory doesn't exist, return empty cache
+                return;
+            }
+            // Find all .md files recursively
+            const files = await glob('**/*.md', {
+                cwd: this.commandsDir,
+                nodir: true,
+                dot: false,
+                signal,
+            });
+            // Load each command file
+            for (const file of files) {
+                const filePath = join(this.commandsDir, file);
+                const commandDef = await this.parseCommandFile(filePath);
+                if (commandDef) {
+                    this.commandsCache.set(commandDef.name, commandDef);
+                }
+            }
+        }
+        catch (error) {
+            // Silently fail if directory doesn't exist or can't be read
+            if (error.code !== 'ENOENT') {
+                console.error(`[SlashCommand] Error loading commands: ${error.message}`);
+            }
+        }
+    }
+    /**
+     * Parse command definition from .md file
+     *
+     * Format:
+     * ```markdown
+     * ---
+     * description: Command description
+     * argument-hint: [arg1] [arg2]
+     * ---
+     *
+     * Command body with $1 and $2 placeholders
+     * ```
+     */
+    async parseCommandFile(filePath) {
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            // Extract frontmatter and body
+            const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/);
+            if (!frontmatterMatch) {
+                console.error(`[SlashCommand] Invalid command file format: ${filePath} (missing frontmatter)`);
+                return null;
+            }
+            const frontmatterText = frontmatterMatch[1] || '';
+            const body = frontmatterMatch[2] || '';
+            // Parse frontmatter (simple YAML parser for our use case)
+            const frontmatter = this.parseFrontmatter(frontmatterText);
+            // Get command name from filename (without extension)
+            const fileName = basename(filePath, extname(filePath));
+            return {
+                name: fileName,
+                description: frontmatter.description || `Execute ${fileName} command`,
+                argumentHint: frontmatter['argument-hint'] || undefined,
+                body: body.trim(),
+            };
+        }
+        catch (error) {
+            console.error(`[SlashCommand] Error parsing command file ${filePath}: ${error.message}`);
+            return null;
+        }
+    }
+    /**
+     * Simple YAML frontmatter parser
+     * Handles basic key: value pairs
+     */
+    parseFrontmatter(text) {
+        const result = {};
+        const lines = text.split('\n');
+        for (const line of lines) {
+            const match = line.match(/^(\S+):\s*(.*)$/);
+            if (match && match[1] && match[2] !== undefined) {
+                const key = match[1].trim();
+                const value = match[2].trim();
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    /**
+     * Substitute arguments in command body
+     * Replaces $1, $2, etc. with actual argument values
+     */
+    substituteArguments(body, args) {
+        let result = body;
+        // Replace $1, $2, etc. with actual arguments
+        for (let i = 0; i < args.length; i++) {
+            const placeholder = `$${i + 1}`;
+            const arg = args[i];
+            result = result.split(placeholder).join(arg);
+        }
+        // Replace any remaining placeholders with empty string
+        result = result.replace(/\$\d+/g, '');
+        return result;
+    }
+    /**
+     * Format command output for display
+     */
+    formatCommandOutput(commandName, commandDef, expandedCommand, args) {
+        const parts = [];
+        // Command header
+        parts.push(`# Slash Command: /${commandName}`);
+        parts.push('');
+        parts.push(`**Description**: ${commandDef.description}`);
+        if (commandDef.argumentHint) {
+            parts.push(`**Arguments**: ${commandDef.argumentHint}`);
+        }
+        if (args.length > 0) {
+            parts.push(`**Provided Arguments**: ${args.join(', ')}`);
+        }
+        parts.push('');
+        parts.push('---');
+        parts.push('');
+        // Expanded command body
+        parts.push(expandedCommand);
+        return parts.join('\n');
+    }
+    /**
+     * Get list of available commands (for error messages)
+     */
+    async getAvailableCommands() {
+        if (!this.commandsCache) {
+            await this.loadAllCommands(new AbortController().signal);
+        }
+        if (!this.commandsCache || this.commandsCache.size === 0) {
+            return '(none found)';
+        }
+        return Array.from(this.commandsCache.keys())
+            .map((name) => `/${name}`)
+            .join(', ');
+    }
+    /**
+     * Clear the commands cache (useful for testing or reloading)
+     */
+    clearCache() {
+        this.commandsCache = null;
+    }
+}
+//# sourceMappingURL=SlashCommandTool.js.map

package/dist/implementations/extensions/SlashCommandTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SlashCommandTool.js","sourceRoot":"","sources":["../../../src/implementations/extensions/SlashCommandTool.ts"],"names":[],"mappings":"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"}

package/dist/implementations/extensions/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Extension Tools
+ *
+ * Tools for extension integration (commands, skills, etc.)
+ */
+export { SlashCommandToolExecutor } from './SlashCommandTool.js';
+export type { SlashCommandParams } from './SlashCommandTool.js';
+export { SkillToolExecutor } from './SkillTool.js';
+export type { SkillParams } from './SkillTool.js';
+export { ResearchBacklogToolExecutor } from './ResearchBacklogTool.js';
+export type { ResearchBacklogParams } from './ResearchBacklogTool.js';
+export { EndTurnToolExecutor } from './EndTurnTool.js';
+export type { EndTurnParams } from './EndTurnTool.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/implementations/extensions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/implementations/extensions/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACjE,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACvE,YAAY,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/implementations/extensions/index.js

@@ -0,0 +1,10 @@
+/**
+ * Extension Tools
+ *
+ * Tools for extension integration (commands, skills, etc.)
+ */
+export { SlashCommandToolExecutor } from './SlashCommandTool.js';
+export { SkillToolExecutor } from './SkillTool.js';
+export { ResearchBacklogToolExecutor } from './ResearchBacklogTool.js';
+export { EndTurnToolExecutor } from './EndTurnTool.js';
+//# sourceMappingURL=index.js.map

package/dist/implementations/extensions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/implementations/extensions/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAGjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGnD,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAGvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/implementations/file/EditTool.d.ts

@@ -0,0 +1,232 @@
+/**
+ * EditFile Tool Executor
+ *
+ * Performs exact string replacements within a file.
+ * Requires precise matching of old_string for safety.
+ *
+ * Adapted and simplified from Gemini CLI patterns
+ * - Removed: ModifiableTool interface, user approval, LLM-based correction
+ * - Kept: Core string replacement, occurrence validation, diff generation
+ *
+ * IMPORTANT: Following the read-before-edit protocol, this tool requires a prior Read
+ * operation in the same session before allowing edits. This ensures the LLM
+ * has current file content and prevents edits based on stale context.
+ */
+import { BaseTool, type ToolResult } from '../../base/index.js';
+import type { ExecutorConfig } from '../../base/ToolRegistry.js';
+/**
+ * Fingerprint of a file section - used for content-based freshness detection
+ * Instead of just checking timestamps, we can verify if the actual content has changed
+ */
+export interface SectionFingerprint {
+    startLine: number;
+    endLine: number;
+    contentHash: string;
+    timestamp: number;
+}
+/**
+ * Session-level tracking of files that have been read/edited.
+ * This enforces the read-before-edit protocol with timestamp-based staleness detection
+ * and content-based fingerprinting for smarter freshness checks.
+ *
+ * Key behavior (read-before-edit):
+ * - Files must be read before editing
+ * - After each edit, the file becomes "stale" and must be re-read
+ * - Content fingerprinting allows detecting if unrelated edits affect your target section
+ * - This ensures LLM always has current file state in evolving codebases
+ */
+export declare class FileReadTracker {
+    private static fileReadTimestamps;
+    private static fileEditTimestamps;
+    private static editedSections;
+    private static sectionFingerprints;
+    private static readonly MAX_CONSECUTIVE_EDITS;
+    private static consecutiveEditCount;
+    private static lastEditRegion;
+    /**
+     * Calculate SHA-256 hash of content, truncated to 16 characters
+     * This is efficient and provides sufficient uniqueness for content comparison
+     */
+    static calculateSectionHash(content: string): string;
+    /**
+     * Store a fingerprint for a read section
+     * Called by ReadFileTool after successfully reading a section
+     */
+    static storeSectionFingerprint(filePath: string, startLine: number, endLine: number, content: string): void;
+    /**
+     * Update fingerprint after a successful edit
+     * This keeps the fingerprint in sync with our known changes, enabling consecutive edits.
+     * The key insight: after WE edit the file, we know the new content is correct.
+     * We update the fingerprint so subsequent edits can verify no EXTERNAL changes occurred.
+     */
+    static updateFingerprintAfterEdit(filePath: string, startLine: number, endLine: number, newContent: string): void;
+    /**
+     * Check if a previously read section still has the same content
+     * Returns true if the section's current content matches the stored fingerprint
+     */
+    static isSectionFresh(filePath: string, startLine: number, endLine: number): boolean;
+    /**
+     * Check if a line range overlaps or is adjacent to another range
+     * Used for brief read mode to allow consecutive edits in same region
+     */
+    static isRegionAdjacent(range1: {
+        startLine: number;
+        endLine: number;
+    }, range2: {
+        startLine: number;
+        endLine: number;
+    }, tolerance?: number): boolean;
+    /**
+     * Mark a file as read at current timestamp
+     * Optionally store content fingerprint for section-based freshness detection
+     */
+    static markAsRead(filePath: string, startLine?: number, endLine?: number, content?: string): void;
+    /**
+     * Mark a file as edited at current timestamp
+     * Tracks the edit region for consecutive edit allowance in brief read mode
+     *
+     * @param filePath Path to the file being edited
+     * @param startLine Optional start line of the edit (for region tracking)
+     * @param endLine Optional end line of the edit (for region tracking)
+     */
+    static markAsEdited(filePath: string, startLine?: number, endLine?: number): void;
+    /**
+     * Check if an edit should be allowed under brief read mode
+     * Returns true if:
+     * 1. We're under MAX_CONSECUTIVE_EDITS
+     * 2. The edit is in the same or adjacent region as previous edits
+     * 3. The section's content hash still matches (no external changes)
+     */
+    static canSkipReRead(filePath: string, editStartLine?: number, editEndLine?: number): boolean;
+    /**
+     * Check if file has been read AND is still fresh (not edited since last read)
+     * Matches a standard coding CLI behavior: require re-read after each edit
+     */
+    static hasBeenRead(filePath: string): boolean;
+    /**
+     * Get suggested read parameters for re-reading after edit
+     * Returns the section around the last edit for efficient re-reading
+     */
+    static getSuggestedReadParams(filePath: string): {
+        offset: number;
+        limit: number;
+    } | null;
+    /**
+     * Find where a string appears in a file and return suggested read parameters
+     * This enables smart error messages that tell the model exactly where to read
+     *
+     * @param filePath Path to the file
+     * @param searchString The string to find (typically old_string from failed edit)
+     * @param contextLines Number of lines of context above/below (default: 10)
+     * @returns Suggested offset/limit, or null if string not found or file can't be read
+     */
+    static findStringInFile(filePath: string, searchString: string, contextLines?: number): {
+        offset: number;
+        limit: number;
+        lineNumber: number;
+    } | null;
+    /**
+     * Clear all session state
+     */
+    static clearSession(): void;
+    /**
+     * Get list of files read in this session
+     */
+    static getReadFiles(): string[];
+    /**
+     * Check if file is stale (edited after last read)
+     */
+    static isStale(filePath: string): boolean;
+    /**
+     * Cross-agent staleness: of the files THIS session has read, which have
+     * changed on disk since they were read — by ANY writer (the user, another
+     * agent, or an external process)? Unlike `isStale` (which only sees this
+     * agent's own EditTool edits via `markAsEdited`), this compares each read
+     * file's CURRENT disk mtime against the read timestamp. mtime is bumped by
+     * every writer, so this catches uncommitted changes made outside this agent.
+     *
+     * Used by the harness to warn the model to re-read before editing when two
+     * agents (or a human + agent) share one working tree.
+     *
+     * @returns Files read this session that are now modified or deleted on disk.
+     */
+    static getExternallyChangedFiles(): {
+        path: string;
+        deleted: boolean;
+    }[];
+    /**
+     * Phase 3: Suggest optimal read parameters for multiple edit targets
+     * When the model plans multiple edits, this calculates a single read that covers all targets
+     *
+     * @param filePath Path to the file
+     * @param editTargets Array of strings to search for (old_string values for planned edits)
+     * @param contextLines Number of context lines above/below (default: 10)
+     * @returns Suggested offset/limit that covers all targets, or null if not all targets found
+     */
+    static suggestBatchRead(filePath: string, editTargets: string[], contextLines?: number): {
+        offset: number;
+        limit: number;
+        coverage: {
+            target: string;
+            lineNumber: number;
+        }[];
+    } | null;
+    /**
+     * Get the consecutive edit count for a file
+     * Useful for displaying in error messages
+     */
+    static getConsecutiveEditCount(filePath: string): number;
+    /**
+     * Get the max allowed consecutive edits
+     */
+    static getMaxConsecutiveEdits(): number;
+}
+/**
+ * Parameters for the Edit tool
+ */
+export interface EditToolParams {
+    /**
+     * The absolute path to the file to modify
+     */
+    file_path: string;
+    /**
+     * The exact literal text to replace
+     */
+    old_string: string;
+    /**
+     * The exact literal text to replace it with
+     */
+    new_string: string;
+    /**
+     * Whether to replace all occurrences (default: false, only replaces one)
+     */
+    replace_all?: boolean;
+    /**
+     * Number of replacements expected (default: 1 if not replace_all, otherwise actual count).
+     * Used for validation - edit will fail if actual count doesn't match expected.
+     */
+    expected_replacements?: number;
+}
+/**
+ * EditFile Tool Executor
+ *
+ * Features:
+ * - Exact string replacement (no fuzzy matching)
+ * - Single or multiple occurrence replacement
+ * - Validates unique match (unless replace_all is true)
+ * - Generates diff for display
+ * - Security: prevents path traversal
+ */
+export declare class EditTool extends BaseTool<EditToolParams, ToolResult> {
+    private config;
+    constructor(config: ExecutorConfig);
+    validateToolParams(params: EditToolParams): string | null;
+    getDescription(params: EditToolParams): string;
+    execute(params: EditToolParams, signal: AbortSignal, updateOutput?: (output: string) => void): Promise<ToolResult>;
+    /**
+     * Creates a new file (when old_string is empty)
+     * @private
+     */
+    private createNewFile;
+}
+//# sourceMappingURL=EditTool.d.ts.map

package/dist/implementations/file/EditTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EditTool.d.ts","sourceRoot":"","sources":["../../../src/implementations/file/EditTool.ts"],"names":[],"mappings":"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"}